docs(core): restructure OSS docs around context-layer narrative

docs/core/.sync.yml

@@ -23,6 +23,7 @@ sync_dirs:
   - concepts
   - guides
   - reference
+  - sdk
 
 # Not synced (excluded by being outside sync_dirs / sync_files):
 # - README.md — this folder's index

docs/core/concepts/architecture.md

@@ -1,6 +1,23 @@
 # Architecture
 
-Wren AI Core CLI is a modular Python application that transforms semantic SQL through an MDL layer before executing it against your database. This page explains how the components fit together.
+Wren AI is built as a system for **correctness** — not as a single feature. Text-to-SQL fails when any one of six pieces is missing; we build all six as primitives the agent orchestrates.
+
+## Correctness is a system, not a switch
+
+Correctness is the result of six things working together. Miss any one of them and the agent fails in that exact gap.
+
+| Pillar | What it means | Where it lives in Wren AI |
+|---|---|---|
+| **Schema linking** | Knowing which tables to look at for a given question. | MDL + memory schema retrieval (`wren memory fetch`) |
+| **Value profiling** | Knowing what values actually live in those columns — what `status = 4` resolves to, whether `is_active` is `'Y'/'N'` or `true/false`. | Connector type coercion + `instructions.md` indexed into memory |
+| **Ambiguity detection** | Knowing when a question is ambiguous and a clarification is needed before generating SQL. | Skill orchestration layer (handled by the agent using Wren AI's primitives) |
+| **Generation trace** | Being able to show *how* an answer was constructed — which models, which joins, which CTEs. | `wren dry-plan` returns the expanded SQL deterministically |
+| **Retry and repair** | Being able to recover when the first SQL fails — re-plan, try a different model, surface a structured error. | Structured error responses + `wren dry-run` for pre-flight validation |
+| **Eval** | Detecting regression when underlying definitions change — schema drift, business rule rewrites, model renames. | Golden NL-SQL eval runner (in development) |
+
+This is why Wren AI exposes **primitives**, not a closed product. The agent does the orchestration — picking the skill, asking the clarification, looping on retry. The trace lives where the agent's reasoning lives. We do not wrap correctness inside our own dashboard that you have to learn.
+
+The rest of this page documents the components that implement those primitives.
 
 ## Overview
 

docs/core/concepts/memory_system.md

@@ -0,0 +1,32 @@
+# The memory system
+
+Wren AI's memory layer is the second of five layers of context — the place where successful natural-language-to-SQL pairs, prior interactions, and user feedback accumulate so the agent gets better at querying your data the more it is used.
+
+Memory is local. It is stored under `.wren/memory/` in your project directory, indexed with [LanceDB](https://lancedb.com/), and never leaves your machine unless you commit it to a shared Git repository.
+
+## What lives in memory
+
+- **NL-SQL pairs** — `("How many customers placed more than one order?", "SELECT ... FROM customers ...")` — stored when an agent runs a query that succeeds.
+- **Pinned business questions** — questions you mark as canonical examples; these are weighted higher during recall.
+- **Schema and column descriptions** — extracted from your MDL so retrieval can match both questions and structure.
+- **Instructions** — content from `instructions.md` is indexed alongside the rest so retrieval can surface relevant rules.
+
+## How recall works
+
+When the agent needs to answer a new question, it first asks the memory layer for the most relevant context:
+
+1. `wren memory fetch --query "..."` returns the most likely tables, columns, and relationships
+2. `wren memory recall --query "..."` returns the most similar past NL-SQL pairs
+3. The agent reads both and uses them as the grounding for its SQL generation
+
+The more queries you and your team run, the more reliable recall becomes.
+
+## When to re-index
+
+Memory is automatically updated when you store a new pair (`wren memory store`), but the full LanceDB index is only rebuilt when you run `wren memory index`. Re-index after:
+
+- bulk-editing `instructions.md`
+- changing model descriptions in `models/*/metadata.yml`
+- importing a large batch of seed NL-SQL examples
+
+See `wren memory --help` for the full set of commands.

docs/core/concepts/skills.md

@@ -0,0 +1,12 @@
+# How agents use Wren AI (Skills)
+
+Wren AI ships with a small set of **skills** — structured workflows that tell an AI coding agent (Claude Code, Openclaw, Hermes, Codex, etc.) how to operate the `wren` CLI without having to memorize commands.
+
+A skill is a markdown file with metadata that the agent reads before acting. Skills are installed once per project with `npx skills add Canner/WrenAI --skill '*'`, and from then on the agent picks the right skill for each user request — generating an MDL from a new database, querying through the semantic layer, enriching context from your team docs, and so on.
+
+Two skills are central to the workflow:
+
+- `wren-generate-mdl` — one-time scaffolding. The agent explores your database, normalizes types, and writes an initial MDL project.
+- `wren-usage` — day-to-day querying. The agent gathers context, recalls past queries, writes SQL through the semantic layer, executes, and stores successful pairs back into memory.
+
+A third skill, **`wren-enrich-context`**, is in active development. It is the second beat of the "scaffold fast, enrich deep" workflow — once your MDL covers structure, enrich-context fills in business meaning (what `status = 4` really means, which table is canonical, how internal project codenames map to data) by either grilling you one question at a time, or by ingesting your team's raw docs in auto-pilot mode.