diff --git a/README.md b/README.md
index 79d863cb..9430b39b 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,9 @@
     ▐   ▐        █▀█ █ ▀█  █  █▄█ █ ▀█
     ▐   ▐
 ```
+
 # Meet Anton - an agent that gets real work done
+
 Anton is a personal AI agent that helps you get actual-work done. Tell it what you need in plain language and it takes it from there - sending emails, calling APIs, connecting to data sources, building dashboards, and delivering results. No setup, no plugins, no fuss.
 
 It doesn't just answer questions. It *does things*: cleans your inbox, builds integrations, analyzes your data, automates workflows - whatever the task requires.
@@ -77,7 +79,9 @@ Set up a WhatsApp integration so I can message you from my phone.
 
 Anton doesn't wait for someone to build a connector. It writes the integration code itself, sets it up, and gets it running - so you can chat with it from WhatsApp, Telegram, or whatever channel you need.
 
+
 ### 🔧 Ask for anything that requires action
+
 - **Send emails** - connect accounts, draft messages or even send them on your behalf.
 - **Manage Calendarss** - Summarize your day, create meetings, block time, etc. All just by asking.
 - **Automated reporting** - pull from multiple databases, crunch numbers, deliver a report on a schedule.
diff --git a/anton/README.md b/anton/README.md
index c810734f..74abc5fa 100644
--- a/anton/README.md
+++ b/anton/README.md
@@ -11,19 +11,24 @@ And here we are: Like an adrenaline junkie eyeing at a bungee looking for anothe
 
 It is probably obvious now, but Anton has a brain-inspired architecture, and the more we build it the more it resembles/mirrors functional parts of the brain.  On the other hand we also understand that people don't need to know anything about the brain to play with Anton, so we mapped some of the places/files where users can have inputs, or investigate what's up, to names that make more sense than the scientific name of that function of the brain.
 
-The current implementation has three blocks:
+The current implementation has six blocks, mapping the major learning systems:
 
-| Brain Region                 | Function                                         | Anton Equivalent                                              |
-|------------------------------|--------------------------------------------------|---------------------------------------------------------------|
-| Prefrontal Cortex (PFC)      | Executive control, planning, the "inner voice"  | Orchestrator — decides what to work on, how, and when to stop |
-| Working Memory (dlPFC)       | Temporary reasoning space, ~4 slots             | Scratchpads — isolated reasoning environments                 |
-| Hippocampus                  | Episodic memory, records experiences            | Experience Store — logs of problem + context + solution       |
+| Brain Region                 | Function                                          | Anton Equivalent                                              |
+|------------------------------|---------------------------------------------------|---------------------------------------------------------------|
+| Prefrontal Cortex (PFC)      | Executive control, planning, the "inner voice"   | Orchestrator — decides what to work on, how, and when to stop |
+| Working Memory (dlPFC)       | Temporary reasoning space, ~4 slots              | Scratchpads — isolated reasoning environments                 |
+| Hippocampus                  | Episodic memory, records experiences             | Experience Store — logs of problem + context + solution       |
+| Cortex (semantic memory)     | Facts, rules, identity — the consolidated knowledge | Engrams — `lessons.md`, `rules.md`, `profile.md`            |
+| Striatum (procedural memory) | Habits and learned procedures — patterns of action | Skills — multi-stage reusable procedures with declarative + chunked + code representations |
+| Cerebellum (error learning)  | Supervised correction — "what I expected vs what happened" | Cerebellum — buffers errored scratchpad cells, extracts generalizable lessons via post-mortem |
+
+These six systems coexist the way they coexist in the brain: declarative and procedural memory are dissociable (a person with hippocampal damage like H.M. can lose new declarative memories but still learn motor skills), and the cerebellum operates in parallel with continued action rather than blocking it.
 
 
 
 ## Architecture of Anton
 
-These three parts work in a very simple way:
+The high-level flow — how the executive, scratchpads, and the long-term stores collaborate on every turn:
 
 ```
   ┌────────────────────────────────────────────────────┐
@@ -31,7 +36,7 @@ These three parts work in a very simple way:
   │                                                    │
   │  On new problem:                                   │
   │    1. Check SKILL LIBRARY → match?                 │
-  │       YES → deploy skill's template scratchpad     │
+  │       YES → recall_skill(label) → load procedure   │
   │       NO  → open fresh scratchpad                  │
   │    2. Monitor scratchpad progress                  │
   │    3. Detect stuck/failure → pivot strategy        │
@@ -49,27 +54,33 @@ These three parts work in a very simple way:
   │  - Can request sub-scratchpads (decomposition)       │
   │  - Can invoke the hypocampus in a loop               │
   │                                                      │
-  └────────────────────┬─────────────────────────────────┘
-                       │ on success
-                       ▼
-  ┌──────────────────────────────────────────────────────┐
-  │         EXPERIENCE STORE (hippocampus)               │
-  │                                                      │
-  │  Each entry:                                         │
-  │  {                                                   │
-  │    problem_signature: "...",                         │
-  │    context: { what tools, what domain, what input }, │
-  │    scratchpad_trace: [ step1, step2, ... ],          │
-  │    outcome: success | failure,                       │
-  │    cost: tokens/time spent,                          │
-  │    salience: how important/novel was this            │
-  │  }                                                   │
-  │                                                      │
-  │  Searchable by similarity (embeddings)               │
-  └──────────────────────────────────────────────────────┘
-
+  │  Every cell execution fires pre/post hooks observed  │
+  │  by the CEREBELLUM (post-mortem error learning).     │
+  └──────┬──────────────┬───────────────────┬────────────┘
+         │              │                   │
+         │ on success   │ on cell errors    │ on success
+         ▼              ▼                   ▼
+  ┌────────────┐  ┌──────────────┐  ┌─────────────────────┐
+  │ EXPERIENCE │  │  CEREBELLUM  │  │   SKILL LIBRARY     │
+  │   STORE    │  │              │  │                     │
+  │ (hipp.)    │  │ Buffers bad  │  │ /skill save → LLM   │
+  │            │  │ cells, runs  │  │ drafts a procedure  │
+  │ Episodes — │  │ post-mortem  │  │ with label + name + │
+  │ JSONL log  │  │ via LLM,     │  │ when_to_use +       │
+  │ of every   │  │ encodes new  │  │ declarative_md.     │
+  │ turn.      │  │ lessons via  │  │                     │
+  │            │  │ Cortex.      │  │ Future turns recall │
+  │ Recall via │  │              │  │ the procedure via   │
+  │ `recall`   │  │ Lessons feed │  │ recall_skill tool.  │
+  │ tool.      │  │ next code    │  │                     │
+  │            │  │ generation   │  │ Stored at           │
+  │            │  │ (procedural  │  │ ~/.anton/skills/    │
+  │            │  │ priming).    │  │   <label>/          │
+  └────────────┘  └──────────────┘  └─────────────────────┘
 ```
 
+The brain analog: the executive (PFC) plans and delegates to working memory (scratchpads), which can pull on procedural memory (striatum/skills) for known recipes and on declarative memory (hippocampus/cortex/engrams) for facts. The cerebellum runs in parallel with continued action — it never blocks the agent, it just refines future cells through supervised error learning.
+
 And the Hipocampus also is controlled as follows:
 
 ```
@@ -122,6 +133,8 @@ And the Hipocampus also is controlled as follows:
 | **Prefrontal Cortex** (dlPFC/vmPFC) | `cortex.py` | The executive coordinator. Manages two hippocampi (global + project), decides which memories to load into the LLM's context window, gates whether new memories need confirmation. |
 | **Medial Temporal Lobe** (episodic) | `episodes.py` | Raw episodic memory. Logs every conversation turn as timestamped JSONL — user input, assistant responses, tool calls, scratchpad output. Searchable via the `recall` tool. Like HSAM: never forgets. |
 | **Hippocampal Replay** (SWS consolidation) | `consolidator.py` | After a scratchpad session ends, replays what happened in compressed form and extracts durable lessons via a fast LLM call. Like sleep — offline, post-hoc, selective. |
+| **Striatum** (procedural memory) | `skills.py` | Long-term procedural memory. Stores reusable skills as multi-stage directories (declarative → chunks → code). The LLM retrieves skills on demand via the `recall_skill` tool, the way the basal ganglia activates a learned action sequence in response to a familiar context. |
+| **Cerebellum** (supervised error learning) | `cerebellum.py` | Forward-model + error correction. Observes every scratchpad cell via pre/post execute hooks, buffers errored/warning cells across the turn, and runs a post-mortem LLM diff to extract generalizable lessons. Lessons flow through the existing wisdom-injection pipeline into future code generation. Operates in parallel with the agent — never blocks. |
 | **Reconsolidation** (Nader et al.) | `reconsolidator.py` | One-time migration. When old memory formats are reactivated, they enter a labile state and get re-encoded in the new format. Preserves content, updates structure. |
 | **Medial PFC / Default Mode Network** | `profile.md` | Always-on self-model. Identity facts (name, timezone, preferences) that contextualize all processing — you don't "look up" your own name. |
 | **Basal Ganglia + OFC** | `rules.md` | Go/No-Go behavioral gates. The direct pathway enables ("always"), the indirect pathway suppresses ("never"), the OFC handles conditions ("when X → do Y"). |
@@ -134,17 +147,26 @@ And the Hipocampus also is controlled as follows:
 
 ```
 ~/.anton/                              GLOBAL scope (cross-project)
-└── memory/
-    ├── profile.md                     Identity — who the user is
-    ├── rules.md                       Always/never/when behavioral rules
-    ├── lessons.md                     Semantic facts from experience
-    └── topics/                        Deep domain expertise
-        └── *.md
+├── memory/
+│   ├── profile.md                     Identity — who the user is
+│   ├── rules.md                       Always/never/when behavioral rules
+│   ├── lessons.md                     Semantic facts from experience
+│   └── topics/                        Deep domain expertise
+│       └── *.md
+└── skills/                            PROCEDURAL MEMORY (striatum)
+    └── <label>/                       One directory per skill
+        ├── meta.json                  label, name, when_to_use, provenance, presence flags
+        ├── declarative.md             Stage 1 — step-by-step procedure (always present)
+        ├── chunks.md                  Stage 2 — higher-level recipes/macros (optional, v2+)
+        ├── code/                      Stage 3 — runnable helper modules (optional, v2+)
+        │   └── __init__.py
+        ├── requirements.txt           Stage 3 dependencies (optional)
+        └── stats.json                 Per-stage usage counters (recommended/used)
 
 <project>/.anton/                      PROJECT scope (workspace-specific)
 ├── memory/
 │   ├── rules.md                       Project-specific rules
-│   ├── lessons.md                     Project-specific knowledge
+│   ├── lessons.md                     Project-specific knowledge (cerebellum writes here)
 │   └── topics/
 │       └── *.md
 ├── episodes/                          EPISODIC MEMORY (conversation archive)
@@ -154,7 +176,7 @@ And the Hipocampus also is controlled as follows:
 └── .env                               Secrets (unchanged)
 ```
 
-Profile (`profile.md`) is global-only — identity is singular. Rules and lessons exist at both scopes. `anton.md` stays as the user-written instruction file and is not managed by the memory system.
+Profile (`profile.md`) is global-only — identity is singular. Rules and lessons exist at both scopes. Skills live globally (one library across projects) at `~/.anton/skills/`. `anton.md` stays as the user-written instruction file and is not managed by the memory system.
 
 ## Memory Entry Format
 
@@ -442,6 +464,192 @@ On first run after upgrading, Anton automatically migrates old memory formats:
 - Old files are preserved — nothing is deleted.
 - Runs synchronously at startup (fast, no LLM calls needed).
 
+## Procedural Memory — The Skills System
+
+Skills are Anton's **procedural memory** — reusable workflows the user has marked as worth remembering. Brain analog: the **striatum** stores motor programs and habits, learned action sequences that fire when a familiar context is recognized. Anton's skill system mirrors this: when the LLM sees a request that matches a stored skill, it pulls the procedure into working memory and follows it instead of reasoning from scratch.
+
+Skills are intentionally distinct from engrams. **Engrams hold facts** ("CoinGecko rate-limits at 50 req/min"), are loaded into every prompt unconditionally because they're cheap, and live in `lessons.md` / `rules.md` / `profile.md`. **Skills hold whole procedures** ("how to summarize a CSV end-to-end"), are NOT loaded into every prompt, and the LLM explicitly retrieves them via the `recall_skill` tool when it recognizes a match. Both systems coexist in the brain — declarative and procedural memory are dissociable — and both coexist in Anton.
+
+### Skill Directory Format
+
+Each skill is a directory at `~/.anton/skills/<label>/` containing multi-stage representations that coexist (rather than graduating between stages):
+
+```
+~/.anton/skills/csv_summary/
+├── meta.json          ← label, name, description, when_to_use, provenance, presence flags
+├── declarative.md     ← Stage 1: step-by-step procedure the LLM reads (always present)
+├── chunks.md          ← Stage 2: higher-level recipes/macros (emerges with use, v2+)
+├── code/              ← Stage 3: runnable helper modules (emerges with reliability, v2+)
+│   └── __init__.py
+├── requirements.txt   ← Stage 3 dependencies (optional)
+└── stats.json         ← per-stage usage counters
+```
+
+The three stages mirror the cortico-striatal-cerebellar gradient:
+- **Stage 1 (declarative)** — what the prefrontal cortex reads when first learning a skill. Slow, deliberate, fully flexible.
+- **Stage 2 (chunks)** — chunked sub-procedures (associative striatum). Faster than Stage 1, still LLM-mediated.
+- **Stage 3 (code)** — runnable helpers (sensorimotor striatum). Cheapest, fastest, used when context is highly familiar.
+
+The executive picks the highest stage that's reliable enough for the current context. v1 only ships Stage 1; the directory format pre-allocates the other slots so consolidation can fill them later without a migration.
+
+### Naming: `label`, not `slug`
+
+Each skill's unique identifier is its `label`. In cognitive psychology, a *label* is the declarative handle by which a procedural memory is addressed in working memory — the verbal token the executive holds when deciding to invoke a stored procedure. It's deliberately distinct from `name` (the human-readable display like "CSV Summary") and `when_to_use` (the retrieval cue describing the matching context).
+
+### How Skills Get Created
+
+Skills are created manually in v1 via the `/skill save` command. The user runs it after a successful task; the LLM reads the recent scratchpad cells + chat history and drafts the skill via `LLMClient.generate_object` with a `_SkillDraft` Pydantic schema:
+
+```
+you> Take a quick look at sales_q3.csv
+
+anton> [opens scratchpad, loads pandas, infers schema, prints describe(), plots distributions]
+       Here's what I found...
+
+you> /skill save csv summary
+anton> Drafting a skill from recent work…
+       Saved skill csv_summary → ~/.anton/skills/csv_summary/
+       Name: CSV Summary
+       When to use: User asks to explore, summarize, or describe a CSV file.
+```
+
+Automatic skill extraction (the consolidator promoting recurring scratchpad patterns into skills) is a v2/v3 feature. v1 deliberately uses manual curation to learn what "good" skills look like before automating.
+
+### How Skills Get Used
+
+On every turn, the system prompt includes a compact `## Procedural memory` section listing every available skill as one line: `- <label> — <when_to_use>`. The full procedures stay on disk. When the LLM recognizes a match, it calls the `recall_skill` tool:
+
+```
+{"name": "recall_skill", "input": {"label": "csv_summary"}}
+```
+
+The tool reads `declarative.md` and returns it as the tool result, which the LLM follows as guidance for the rest of the turn. Each successful recall increments `stats.json::stage_1::recommended` — that's the classifier signal, mechanically captured without any LLM compliance dance.
+
+Brain analog: the prefrontal cortex doesn't keep every skill loaded. It has fast pattern recognition that flags "I might need skill X" and *retrieves* the skill into working memory only when it actually needs it. The `recall_skill` tool is exactly this retrieval operation.
+
+### Skill Slash Commands
+
+| Command | What it does |
+|---|---|
+| `/skill save [name hint]` | LLM drafts a new skill from recent work and saves it |
+| `/skills list` (or `/skill list`) | Show all saved skills with usage counters |
+| `/skill show <label>` | Print one skill's procedure + stats (typo-tolerant via closest_match) |
+| `/skill remove <label>` | Delete a skill from disk |
+
+### Typo Recovery
+
+When the LLM passes a label that doesn't exist (typos, guesses), `recall_skill` uses `closest_match()` to find the nearest existing slug via difflib and returns that skill's procedure with a warning. The `recommended` counter is credited to the *resolved* label, not the input — so `recall_skill('csv_sumary')` still increments `csv_summary` in the stats. The LLM gets useful behavior even when it gets the spelling wrong.
+
+## Cerebellum — Supervised Error Learning
+
+The Cerebellum is Anton's **supervised error-correction system**. It observes every scratchpad cell and learns from the ones that diverge from intent. Brain analog: the cerebellum's classical role is *forward modeling and error correction* — when a motor command is issued, the cerebellum predicts the expected sensory consequences, and when actual feedback arrives, it computes the prediction error and uses it to refine future commands.
+
+For Anton, the "motor command" is a scratchpad cell. Before the cell runs, the LLM declares its intent via the `one_line_description` field on the scratchpad tool. That description IS the forward model — the prediction of what the cell should do. After the cell runs, we have its actual outcome (stdout, stderr, error). The Cerebellum compares the two and, when they diverge meaningfully, encodes a generalizable lesson that future code-generating LLM calls will see.
+
+### Decoupling: Hooks Live in the Dispatcher, Not the Runtime
+
+The Cerebellum operates via two observer hooks called from the scratchpad tool dispatcher (`handle_scratchpad`), NOT from the runtime backend itself:
+
+```
+handle_scratchpad (orchestration layer)
+  ├─ build prelim Cell from tool input
+  ├─ FIRE pre-execute observers ──→ Cerebellum.on_pre_execute (counter)
+  ├─ pad.execute(code, ...)        (pure execution — runtime never sees observers)
+  ├─ FIRE post-execute observers ─→ Cerebellum.on_post_execute (buffer if errored)
+  └─ return formatted result
+```
+
+This decoupling is intentional. `LocalScratchpadRuntime`, `ScratchpadManager`, and any future `RemoteScratchpadRuntime` are **completely hook-agnostic** — they don't import the Cerebellum, they don't have hook attributes, they never call observers. When a remote runtime backend is added, it inherits zero hook code because there is none to inherit. The orchestration layer is the only place where execution and observation meet.
+
+### Cheap Path
+
+Most cells succeed cleanly. The Cerebellum's `on_post_execute` hook checks `cell.error is None and not cell.stderr.strip()` and returns immediately for clean cells — they're never buffered, no LLM call is ever made for them. Only cells that errored or warned trigger the buffer. The cost of running the Cerebellum on a happy-path turn is **zero LLM calls**.
+
+### Batched Per-Turn Diff
+
+When errored cells exist, they accumulate in a buffer across the turn. At end-of-turn, `_schedule_cerebellum_flush()` fires `Cerebellum.flush()` as a fire-and-forget background task. The user gets their reply immediately while the diff runs in parallel:
+
+1. The buffered cells get formatted into a compact post-mortem prompt
+2. One LLM call via `LLMClient.generate_object_code` (the cheap coding model) returns a `_DiffPassResult` Pydantic model with extracted lessons
+3. Each lesson is wrapped as an `Engram` with `kind="lesson"`, `topic="scratchpad"`, `source="consolidation"`, and routed through `Cortex.encode()` — the same path manual lessons and the consolidator already use
+4. Future scratchpad cells see those lessons via the existing `recall_scratchpad_wisdom()` injection into the scratchpad tool description
+
+The cerebellum is a **producer** only — it generates new lesson entries for the existing storage and retrieval pipeline. There's no parallel storage system, no separate `corrections.md` file. Whatever the consolidator and `/memorize` write to, the cerebellum also writes to.
+
+Brain analog: cerebellar plasticity (LTD at parallel-fiber → Purkinje cell synapses) operates in parallel with continued action, never blocking it. Lessons compound silently across turns; future cells avoid traps that earlier cells fell into.
+
+### The Generated Lessons Look Like
+
+```markdown
+- For CSV files with mixed column types, pass low_memory=False to pd.read_csv. <!-- topic:scratchpad source:consolidation ts:2026-04-11 -->
+- Wrap pd.to_datetime() calls in errors='coerce' when the input may contain malformed strings. <!-- topic:scratchpad source:consolidation ts:2026-04-11 -->
+```
+
+These appear in `lessons.md` like any other engram, carry the same metadata, and get pruned by the same compaction loop when memory grows past threshold.
+
+## Structured Output — `LLMClient.generate_object`
+
+Anton has a single primitive for getting structured data out of the LLM, used by the cerebellum, the consolidator, the cortex's identity/compaction passes, the connect collector, the skill drafter, and the custom-datasource flow. It lives at `anton/llm/client.py`:
+
+```python
+async def generate_object(
+    self,
+    schema_class,        # A Pydantic BaseModel subclass, or list[Model]
+    *,
+    system: str,
+    messages: list[dict],
+    max_tokens: int | None = None,
+):
+    """Forced-tool-call structured output via the planning provider."""
+```
+
+There's also a paired `generate_object_code(...)` that uses the cheap *coding* provider — appropriate for fast/cheap structured tasks like the cerebellum's post-mortem and the cortex's identity extraction.
+
+### How It Works
+
+1. The Pydantic model is converted to a JSON schema via `model_json_schema()`
+2. A synthetic tool is built whose `input_schema` is that JSON schema
+3. The LLM provider is called with `tool_choice={"type": "tool", "name": tool_name}` — this *forces* the LLM to call the tool rather than returning text
+4. The tool's input dict is validated through `model_validate()` and returned as a typed instance
+
+### Why It Beats Asking for JSON in Text
+
+| Old pattern (text JSON) | New pattern (`generate_object`) |
+|---|---|
+| "Return ONLY valid JSON, no commentary, no markdown fences" | Forced tool_choice — the LLM cannot return text |
+| Manual `json.loads()` with try/except | Pydantic `model_validate()` with structural validation |
+| Strip markdown fences with regex (`_strip_json_fences`) | Never needed — there's no text response to strip |
+| Defensive `if not isinstance(data, dict): return` checks | Pydantic catches type errors at the schema layer |
+| Field-by-field `.get(key, default)` extraction | Typed attribute access on the validated instance |
+
+### The Shared Helper
+
+The schema-derivation and validation logic lives in exactly one place — `anton/llm/structured.py` — and is shared by both `LLMClient.generate_object` (main process, async) and `_ScratchpadLLM.generate_object` (subprocess bridge, sync). Two pure helper functions:
+
+```python
+def build_structured_tool(schema_class) -> tuple[dict, type, bool]:
+    """Pydantic model → (tool_dict, validator_class, is_list)."""
+
+def unwrap_structured_response(tool_call_input, validator_class, is_list):
+    """LLM tool call input → validated typed Pydantic instance."""
+```
+
+This pattern is what every extraction call site uses. Adding a new one is mechanical: define a Pydantic model with `Field(description=...)` on each field, call `await session._llm.generate_object(MySchema, ...)`, wrap in try/except for graceful degradation. The field descriptions on the Pydantic model double as the LLM's instructions — there's no separate prompt explaining the schema.
+
+### Where It's Used
+
+| Module | Schema | Provider | Purpose |
+|---|---|---|---|
+| `connect_collector.py::extract_variables` | `_ExtractionResult` | planning | Parse free-form credential input into structured fields |
+| `commands/skills.py::handle_skill_save` | `_SkillDraft` | planning | LLM drafts a skill from recent scratchpad work |
+| `commands/datasource.py::handle_add_custom_datasource` | `_CustomDatasourceSpec` | planning | LLM identifies a custom datasource's auth fields |
+| `cortex.py::_compact_file` | `_CompactionResult` | **coding** | Memory deduplication during synaptic homeostasis |
+| `cortex.py::maybe_update_identity` | `_IdentityFacts` | **coding** | Default-mode identity extraction every 5 turns |
+| `consolidator.py::replay_and_extract` | `_ConsolidatedLessons` | **coding** | Sleep-replay extraction of lessons from scratchpad sessions |
+| `cerebellum.py::_run_diff` | `_DiffPassResult` | **coding** | Post-mortem error learning from cell failures |
+
+The split between *planning* and *coding* providers preserves the original intent of each call site — anything that previously used `_llm.code()` now uses `generate_object_code` (cheap, fast model), and anything that previously used `_llm.plan()` now uses `generate_object` (planning model).
+
 ## Concurrency Safety
 
 | Operation | Scope | Strategy |
@@ -486,12 +694,24 @@ Source (user/LLM/consolidation)
 ```
 anton/memory/
 ├── hippocampus.py      Engram + Hippocampus class
-├── cortex.py           Cortex class
+├── cortex.py           Cortex class (executive declarative-memory coordinator)
 ├── episodes.py         Episode + EpisodicMemory class
-├── consolidator.py     Consolidator class
+├── consolidator.py     Consolidator class (sleep-replay → Engrams)
+├── cerebellum.py       Cerebellum class (supervised error learning over scratchpad cells)
+├── skills.py           Skill, SkillStore, SkillStats — procedural memory storage layer
 ├── reconsolidator.py   needs_reconsolidation() + reconsolidate() functions
 ├── learnings.py        [legacy] LearningStore — replaced by Hippocampus
 └── store.py            SessionStore — session history (orthogonal to long-term memory)
+
+anton/llm/
+├── client.py           LLMClient with plan/code/generate_object/generate_object_code
+├── structured.py       build_structured_tool + unwrap_structured_response (shared helper)
+└── ...                 anthropic.py, openai.py, provider.py, prompt_builder.py
+
+anton/tools/
+├── recall_skill.py     RECALL_SKILL_TOOL — the LLM's procedural memory retrieval primitive
+├── tool_handlers.py    handle_scratchpad with pre/post-execute observer firing
+└── ...                 registry.py, tool_defs.py
 ```
 
 ### `hippocampus.py` — Storage Engine
@@ -516,17 +736,17 @@ The Hippocampus handles one scope (global OR project). It doesn't decide what to
 
 ### `cortex.py` — Executive Coordinator
 
-The Cortex manages two Hippocampus instances and orchestrates all memory operations.
+The Cortex manages two Hippocampus instances and orchestrates all declarative memory operations. It is also the encoding endpoint that the cerebellum and consolidator route their generated lessons through.
 
 | Method | Purpose |
 |---|---|
 | `build_memory_context()` | Assemble memories for system prompt injection (~5800 token budget) |
-| `get_scratchpad_context()` | Combine scratchpad wisdom from both scopes for tool description injection |
-| `encode(engrams)` | Route engrams to correct hippocampus by scope. Returns action log. |
+| `get_scratchpad_context()` | Combine scratchpad wisdom from both scopes for tool description injection. **This is the channel the cerebellum's lessons flow through into future code generation.** |
+| `encode(engrams)` | Route engrams to correct hippocampus by scope. Returns action log. Called by `/memorize`, the consolidator, and the cerebellum. |
 | `encoding_gate(engram)` | Check if an engram needs user confirmation (mode-dependent) |
-| `needs_compaction()` | Check if any file exceeds 50 entries |
-| `compact_all()` | LLM-assisted deduplication + merge on all oversized files |
-| `maybe_update_identity(message)` | Extract identity facts from user message (fast model, background) |
+| `needs_compaction()` | Check if any file exceeds the threshold |
+| `compact_all()` | LLM-assisted deduplication + merge on all oversized files. Uses `generate_object_code(_CompactionResult, ...)`. |
+| `maybe_update_identity(message)` | Extract identity facts from user message via `generate_object_code(_IdentityFacts, ...)`. Background, fires every 5 turns. |
 
 ### `episodes.py` — Episodic Memory
 
@@ -546,7 +766,51 @@ The EpisodicMemory handles raw conversation logging and recall.
 | Method | Purpose |
 |---|---|
 | `should_replay(cells)` | Heuristic check: errors, 5+ cells, or cancellations → True |
-| `replay_and_extract(cells, llm)` | Compress cells → fast LLM call → parse JSON → return Engrams |
+| `replay_and_extract(cells, llm)` | Compress cells → `generate_object_code(_ConsolidatedLessons, ...)` → return Engrams |
+
+### `cerebellum.py` — Supervised Error Learning
+
+| Method | Purpose |
+|---|---|
+| `on_pre_execute(cell)` | Pre-execute hook called by `handle_scratchpad`. Counter only in v1. |
+| `on_post_execute(cell)` | Post-execute hook. Cheap path skips clean cells; errored/warning cells get buffered. |
+| `flush()` | Run the batched diff pass on all buffered cells, encode lessons via Cortex, clear buffer. Fire-and-forget at end-of-turn. |
+| `reset()` | Drop the buffer without encoding (used when a turn is cancelled mid-flight). |
+| `buffered_count` | Number of cells waiting for the next flush. |
+| `_run_diff(cells)` | Internal: send buffered cells to `generate_object_code(_DiffPassResult, ...)` and return validated lessons. |
+| `_encode_lessons(lessons)` | Internal: wrap lessons as Engrams (`kind="lesson"`, `topic="scratchpad"`, `source="consolidation"`) and route through `Cortex.encode()`. |
+
+### `skills.py` — Procedural Memory Store
+
+| Method | Purpose |
+|---|---|
+| `SkillStore.list_all()` | Return every loadable skill, sorted by label. |
+| `SkillStore.list_summaries()` | Lightweight listing — `[{"label": "...", "name": "...", "when_to_use": "..."}]`. Used by the prompt builder to inject the procedural-memory section without loading any declarative content. |
+| `SkillStore.load(label)` | Read a single skill by label. Returns None if absent or malformed. |
+| `SkillStore.save(skill)` | Write the skill directory. Creates `meta.json`, `declarative.md`, `stats.json`. Never wipes accumulated counters. |
+| `SkillStore.delete(label)` | Remove a skill directory. |
+| `SkillStore.increment_recommended(label, *, stage)` | Atomic-ish bump of the per-stage `recommended` counter (called by `recall_skill`). |
+| `SkillStore.closest_match(bad_label, *, cutoff=0.6)` | Difflib-based fuzzy match for typo recovery. |
+| `make_unique_label(base, store)` | Generate a slug that doesn't collide with any existing skill (`csv_summary`, `csv_summary_2`, ...). |
+| `slugify(text)` | Normalize arbitrary text into a snake_case identifier. |
+
+### `tools/recall_skill.py` — Procedural Memory Retrieval Tool
+
+The LLM-facing tool that pulls a skill into working memory. Lives alongside the other tool defs but is the only tool whose handler reads `session._skill_store`.
+
+| Element | Purpose |
+|---|---|
+| `RECALL_SKILL_TOOL` | The `ToolDef` registered with the session — name, description, input_schema, handler. |
+| `handle_recall_skill(session, tc_input)` | Resolve the label (with closest_match fallback for typos), increment the per-stage `recommended` counter, return a formatted procedure to the LLM as the tool result. |
+
+### `llm/structured.py` — Shared Schema Helper
+
+Two pure helper functions for forced-tool-call structured output. Used by both `LLMClient.generate_object` (main process, async) and `_ScratchpadLLM.generate_object` (subprocess bridge, sync) — they share this code via lazy imports so neither runtime forces pydantic at module load time.
+
+| Function | Purpose |
+|---|---|
+| `build_structured_tool(schema_class)` | Pydantic model (or `list[Model]`) → `(tool_dict, validator_class, is_list)`. The `tool_dict` is ready to pass as `tools=[...]` with `tool_choice={"type": "tool", "name": tool_dict["name"]}`. |
+| `unwrap_structured_response(tool_call_input, validator_class, is_list)` | Validate the LLM's tool call input via Pydantic and unwrap the wrapper if it was a list. Raises `pydantic.ValidationError` on schema drift. |
 
 ### `reconsolidator.py` — Legacy Migration
 
@@ -557,11 +821,11 @@ The EpisodicMemory handles raw conversation logging and recall.
 
 ## Integration Points in chat.py
 
-The memory system is wired into `ChatSession` and `_chat_loop()`:
+The memory + skills + cerebellum systems are wired into `ChatSession` and `_chat_loop()`:
 
 ```
 1. _chat_loop() startup:
-   → Creates Cortex(global_dir, project_dir, mode, llm)
+   → Creates Cortex(global_hc=Hippocampus(global_dir), project_hc=Hippocampus(project_dir), mode, llm)
    → Creates EpisodicMemory(episodes_dir, enabled=settings.episodic_memory)
    → Starts episodic session if enabled
    → Runs reconsolidation if needed
@@ -570,49 +834,74 @@ The memory system is wired into `ChatSession` and `_chat_loop()`:
 2. ChatSession.__init__():
    → Stores cortex as self._cortex
    → Stores episodic as self._episodic
+   → Initializes self._skill_store = SkillStore() (procedural memory)
+   → Initializes self._cerebellum = Cerebellum(cortex=self._cortex, llm=self._llm)
+   → Initializes self._scratchpad_observers = [self._cerebellum]
    → Initializes self._pending_memory_confirmations = []
 
 3. ChatSession._build_system_prompt():
    → Calls cortex.build_memory_context()  →  injected before anton.md
+   → Passes self._skill_store to prompt builder
+   → Builder appends "## Procedural memory" section listing all available skills
 
 4. ChatSession._build_tools():
    → Calls cortex.get_scratchpad_context()  →  appended to scratchpad tool desc
    → Includes MEMORIZE_TOOL in tool list
    → Includes RECALL_TOOL when episodic memory is enabled
+   → Includes RECALL_SKILL_TOOL (always available — no-op if no skills saved)
 
 5. Tool dispatch (tools.py):
    → "memorize" → handle_memorize() → cortex.encode()
    → "recall" → handle_recall() → episodic.recall_formatted()
+   → "recall_skill" → handle_recall_skill() → SkillStore.load() + increment_recommended()
+   → "scratchpad" exec → handle_scratchpad() fires pre/post observers around pad.execute()
 
-6. turn_stream():
+6. handle_scratchpad (tool_handlers.py) — observer dispatch:
+   → Build prelim Cell from tool input (code + description + estimated_time)
+   → _fire_pre_execute(session, prelim_cell) → cerebellum.on_pre_execute (counter)
+   → pad.execute(...) — pure execution, runtime never sees observers
+   → _fire_post_execute(session, cell) → cerebellum.on_post_execute (buffer if errored)
+
+7. turn_stream():
    → Logs user input to episodic memory (before LLM call)
    → Logs assistant response to episodic memory (after LLM call)
 
-7. _stream_and_handle_tools() tool loop:
+8. _stream_and_handle_tools() tool loop:
    → Logs each tool_call to episodic memory
    → Logs each tool_result to episodic memory
    → Logs scratchpad cell output to episodic memory
    → _maybe_consolidate_scratchpads() → background asyncio.create_task
 
-8. After turn (turn_stream):
+9. End of turn (turn / turn_stream):
    → Every 5 turns → cortex.maybe_update_identity() as background task
+   → _schedule_cerebellum_flush() → fire-and-forget background task
+     → Runs cerebellum diff on all buffered cells
+     → Encodes extracted lessons via cortex.encode()
+     → Lessons appear in next turn's scratchpad tool description automatically
+
+10. Before user prompt (_chat_loop):
+    → Show pending memory confirmations → user approves/rejects/picks
 
-9. Before user prompt (_chat_loop):
-   → Show pending memory confirmations → user approves/rejects/picks
+11. Slash commands for skills (chat.py):
+    → /skill save [name hint] → handle_skill_save() → drafts via generate_object → SkillStore.save()
+    → /skills or /skill list → handle_skills_list() → tabular display of skills + counters
+    → /skill show <label> → handle_skill_show() → full procedure + stats
+    → /skill remove <label> → handle_skill_remove() → SkillStore.delete()
 
-10. /setup wizard (sub-menu):
+12. /setup wizard (sub-menu):
     → Option 1: Models — provider, API key, planning & coding models
     → Option 2: Memory — memory mode (autopilot/copilot/off) + episodic toggle
     → Persisted to ANTON_MEMORY_MODE and ANTON_EPISODIC_MEMORY in .anton/.env
 
-11. /memory (read-only dashboard):
+13. /memory (read-only dashboard):
     → Shows semantic memory counts (global/project rules, lessons, topics)
     → Shows episodic memory status (ON/OFF) and session count
     → No configuration prompts — directs to /setup > Memory
 
-12. _rebuild_session():
+14. _rebuild_session():
     → Updates cortex._llm and cortex.mode when settings change
     → Propagates episodic memory instance
+    → Re-creates cerebellum if llm or cortex changed
 ```
 
 ## Context Budget Summary
@@ -624,7 +913,11 @@ The memory system is wired into `ChatSession` and `_chat_loop()`:
 | Project rules | Basal Ganglia | ~1500 tokens | Always (system prompt) |
 | Global lessons | ATL semantics | ~1000 tokens | Always (most recent first) |
 | Project lessons | ATL semantics | ~1000 tokens | Always (most recent first) |
-| Scratchpad wisdom | Procedural memory | ~500 tokens | Scratchpad active (tool desc) |
+| Scratchpad wisdom | Procedural priming | ~500 tokens | Scratchpad active (tool desc). Cerebellum-generated lessons flow through here. |
+| Procedural memory list | Striatum (skill labels) | ~50 tokens per skill (compact list) | Always — when any skills are saved. Full procedures NOT loaded; only labels + when_to_use. |
 | Topic files | Cortical association | Unlimited | On demand |
-| Episodic recall | MTL episodic | Variable | On demand (recall tool) |
-| **Total in prompt** | **Working memory** | **~5800 tokens** | ~3% of 200K context |
+| Skill procedures | Striatum (full skills) | Variable per skill | On demand (`recall_skill` tool) — only when the LLM recognizes a match |
+| Episodic recall | MTL episodic | Variable | On demand (`recall` tool) |
+| **Total in prompt** | **Working memory** | **~5800 tokens + ~50/skill** | ~3% of 200K context |
+
+The procedural memory list scales linearly with the number of saved skills but stays cheap (~50 tokens each — slug + one-line `when_to_use`). The full skill procedures are *paid for only when retrieved*, the same way the prefrontal cortex doesn't keep every procedural memory loaded — it has fast pattern recognition that flags relevance and pulls the full procedure from storage on demand.
diff --git a/anton/__init__.py b/anton/__init__.py
index 9b102be7..8c0d5d5b 100644
--- a/anton/__init__.py
+++ b/anton/__init__.py
@@ -1 +1 @@
-__version__ = "1.1.5"
+__version__ = "2.0.0"
diff --git a/anton/analytics.py b/anton/analytics.py
index 182eb59e..f87fe556 100644
--- a/anton/analytics.py
+++ b/anton/analytics.py
@@ -1,21 +1,45 @@
 """Fire-and-forget anonymous analytics events.
 
 Every call spawns a daemon thread that issues a single GET request to the
-configured analytics URL.  The request carries only the action name and a
-timestamp — no PII, no payload beyond what the query string contains.
+configured analytics URL.  The request carries only the action name, a
+timestamp, and an anonymous machine fingerprint — no PII, no payload
+beyond what the query string contains.
 
 Guarantees:
   • Never blocks the caller.
   • Never raises — all exceptions are silently swallowed.
   • Daemon threads die automatically when the process exits.
+
+Machine fingerprint
+===================
+
+Each event includes an ``aid`` (Anton Installation ID) — a deterministic
+SHA-256 hash of the machine's MAC address (``uuid.getnode()``).  This is:
+
+  • **Anonymous**: the hash is one-way; the raw MAC never leaves the
+    device.  No hostname, no platform, no PII.
+  • **Stateless**: no file on normal machines — computed from the MAC.
+  • **Stable**: changes only if the primary network adapter changes.
+
+Fallback for Docker / containers: if Python can't find a real MAC
+(detected via the multicast bit), a random UUID is persisted to
+``~/.anton/.installation_id`` so it stays stable across restarts.
+File I/O only happens in this edge case — normal desktops never
+touch disk.
+
+The ``aid`` is truncated to 16 hex characters (~64 bits of entropy) —
+enough to be collision-free across millions of installations, short
+enough to be a readable query parameter.
 """
 
 from __future__ import annotations
 
+import hashlib
 import threading
 import time
 import urllib.parse
 import urllib.request
+import uuid
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -23,8 +47,50 @@
 
 _TIMEOUT = 3  # seconds
 
+# Cached after first computation — the fingerprint never changes within
+# a process, so computing it once is sufficient.
+_cached_aid: str | None = None
+
+
+def get_installation_id() -> str:
+    """Return a deterministic, anonymous machine fingerprint.
+
+    The fingerprint is a truncated SHA-256 of the MAC address on normal
+    machines. If no real MAC is available (Docker containers with stripped
+    networking), a random UUID is persisted to ``~/.anton/.installation_id``
+    as a one-time fallback. Computed once per process and cached.
+
+    Returns:
+        A 16-character hex string (64 bits of entropy).
+    """
+    global _cached_aid
+    if _cached_aid is not None:
+        return _cached_aid
+
+    try:
+        node = uuid.getnode()
+        is_random_fallback = bool(node & (1 << 40))  # multicast bit = Python faked it
+
+        if is_random_fallback:
+            # No real MAC (e.g. Docker with stripped networking).
+            # Persist a UUID to disk so it's stable across restarts.
+            from pathlib import Path
+
+            path = Path("~/.anton/.installation_id").expanduser()
+            if path.is_file():
+                _cached_aid = path.read_text(encoding="utf-8").strip()[:16]
+            else:
+                _cached_aid = uuid.uuid4().hex[:16]
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(_cached_aid + "\n", encoding="utf-8")
+        else:
+            _cached_aid = hashlib.sha256(str(node).encode()).hexdigest()[:16]
+    except Exception:
+        _cached_aid = "unknown"
+    return _cached_aid
+
 
-def send_event(settings: AntonSettings, action: str, **extra: str) -> None:
+def send_event(settings: "AntonSettings", action: str, **extra: str) -> None:
     """Send an analytics event in a background thread.
 
     Args:
@@ -41,6 +107,7 @@ def send_event(settings: AntonSettings, action: str, **extra: str) -> None:
 
         params: dict[str, str] = {
             "action": action,
+            "aid": get_installation_id(),
             "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
             "_": str(int(time.time() * 1000)),
         }
diff --git a/anton/chat.py b/anton/chat.py
index 71251d2c..164e8ec8 100644
--- a/anton/chat.py
+++ b/anton/chat.py
@@ -1,14 +1,10 @@
 from __future__ import annotations
 
 import asyncio
-import json as _json
 import os
 import urllib.error
-import re as _re
 import sys
-import uuid
 import time
-from collections.abc import AsyncIterator, Callable
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -16,19 +12,17 @@
 
 from anton.clipboard import (
     cleanup_old_uploads,
-    clipboard_unavailable_reason,
     grab_clipboard,
     is_clipboard_supported,
     parse_dropped_paths as _parse_dropped_paths,
     save_clipboard_image,
 )
-from anton.llm.prompts import CHAT_SYSTEM_PROMPT, build_visualizations_prompt
-from anton.llm.provider import (
-    ContextOverflowError,
+from anton.core.session import ChatSession, ChatSessionConfig
+from anton.core.llm.prompt_builder import SystemPromptContext
+from anton.core.llm.provider import (
     TokenLimitExceeded,
     StreamComplete,
     StreamContextCompacted,
-    StreamEvent,
     StreamTaskProgress,
     StreamTextDelta,
     StreamToolResult,
@@ -36,25 +30,13 @@
     StreamToolUseEnd,
     StreamToolUseStart,
 )
-from anton.scratchpad import ScratchpadManager
-from anton.tools import (
-    CONNECT_DATASOURCE_TOOL,
-    MEMORIZE_TOOL,
-    PUBLISH_TOOL,
-    RECALL_TOOL,
-    SCRATCHPAD_TOOL,
-    dispatch_tool,
-    format_cell_result,
-    prepare_scratchpad_exec,
-)
 from anton.checks import TokenLimitInfo, TokenLimitStatus, check_minds_token_limits
 from anton.commands.setup import (
     handle_memory,
     handle_setup,
-    handle_setup_memory,
     handle_setup_models,
 )
-from anton.commands.ui import handle_theme, print_slash_help
+from anton.commands.ui import handle_explain, handle_theme, print_slash_help
 from anton.utils.clipboard import (
     ensure_clipboard,
     format_clipboard_image_message,
@@ -69,13 +51,14 @@
     handle_connect_datasource,
     handle_test_datasource,
 )
+from anton.commands.skills import (
+    handle_skill_remove,
+    handle_skill_save,
+    handle_skill_show,
+    handle_skills_list,
+)
+from anton.tools import CONNECT_DATASOURCE_TOOL, PUBLISH_TOOL
 from anton.utils.prompt import (
-    MINDS_KEYS,
-    LLM_KEYS,
-    SECRET_PATTERNS,
-    mask_secret,
-    is_secret_key,
-    display_value,
     prompt_or_cancel,
     prompt_minds_api_key,
 )
@@ -84,1192 +67,30 @@
     normalize_minds_url,
     describe_minds_connection_error,
     list_minds,
-    get_mind,
-    refresh_knowledge,
     list_datasources,
     test_llm,
 )
-from anton.data_vault import DataVault
+from anton.core.datasources.data_vault import LocalDataVault
 from anton.utils.datasources import (
-    build_datasource_context,
     register_secret_vars,
-    restore_namespaced_env,
-    remove_engine_block,
-    scrub_credentials,
-    parse_connection_slug,
 )
-from anton.datasource_registry import (
-    DatasourceEngine,
-    DatasourceField,
+from anton.core.datasources.datasource_registry import (
     DatasourceRegistry,
 )
-from anton.llm.openai import build_chat_completion_kwargs
 
 from prompt_toolkit import PromptSession
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.key_binding import KeyBindings
 from prompt_toolkit.styles import Style as PTStyle
-from rich.prompt import Confirm, Prompt
+from rich.prompt import Prompt
 
 if TYPE_CHECKING:
     from rich.console import Console
 
     from anton.config.settings import AntonSettings
-    from anton.context.self_awareness import SelfAwarenessContext
-    from anton.llm.client import LLMClient
-    from anton.memory.cortex import Cortex
-    from anton.memory.episodes import EpisodicMemory
-    from anton.memory.history_store import HistoryStore
+    from anton.core.memory.episodes import EpisodicMemory
     from anton.workspace import Workspace
 
 
-_MAX_TOOL_ROUNDS = 25  # Hard limit on consecutive tool-call rounds per turn
-_MAX_CONTINUATIONS = 3  # Max times the verification loop can restart the tool loop
-_CONTEXT_PRESSURE_THRESHOLD = 0.7  # Trigger compaction when context is 70% full
-_MAX_CONSECUTIVE_ERRORS = 5  # Stop if the same tool fails this many times in a row
-_RESILIENCE_NUDGE_AT = 2  # Inject resilience nudge after this many consecutive errors
-_RESILIENCE_NUDGE = (
-    "\n\nSYSTEM: This tool has failed twice in a row. Before retrying the same approach or "
-    "asking the user for help, try a creative workaround — different headers/user-agent, "
-    "a public API, archive.org, an alternate library, or a completely different data source. "
-    "Only involve the user if the problem truly requires something only they can provide."
-)
-
-# TODO: Is this enough for now?
-TOKEN_STATUS_CACHE_TTL = 60.0
-
-
-
-class ChatSession:
-    """Manages a multi-turn conversation with tool-call delegation."""
-
-    def __init__(
-        self,
-        llm_client: LLMClient,
-        *,
-        self_awareness: SelfAwarenessContext | None = None,
-        cortex: Cortex | None = None,
-        episodic: EpisodicMemory | None = None,
-        runtime_context: str = "",
-        workspace: Workspace | None = None,
-        console: Console | None = None,
-        coding_provider: str = "anthropic",
-        coding_api_key: str = "",
-        coding_base_url: str = "",
-        initial_history: list[dict] | None = None,
-        history_store: HistoryStore | None = None,
-        session_id: str | None = None,
-        proactive_dashboards: bool = False,
-    ) -> None:
-        self._llm = llm_client
-        self._self_awareness = self_awareness
-        self._cortex = cortex
-        self._episodic = episodic
-        self._runtime_context = runtime_context
-        self._proactive_dashboards = proactive_dashboards
-        self._workspace = workspace
-        self._console = console
-        self._history: list[dict] = list(initial_history) if initial_history else []
-        self._pending_memory_confirmations: list = []
-        self._turn_count = (
-            sum(1 for m in self._history if m.get("role") == "user")
-            if initial_history
-            else 0
-        )
-        self._history_store = history_store
-        self._session_id = session_id
-        self._cancel_event = asyncio.Event()
-        self._escape_watcher: "EscapeWatcher | None" = None
-        self._active_datasource: str | None = None
-        self._scratchpads = ScratchpadManager(
-            coding_provider=coding_provider,
-            coding_model=getattr(llm_client, "coding_model", ""),
-            coding_api_key=coding_api_key,
-            coding_base_url=coding_base_url,
-            workspace_path=workspace.base if workspace else None,
-        )
-
-    @property
-    def history(self) -> list[dict]:
-        return self._history
-
-    def repair_history(self) -> None:
-        """Fix dangling tool_use blocks left by mid-stream cancellation.
-
-        The Anthropic API requires every tool_use to be followed by a
-        tool_result.  If we cancelled mid-turn, the last assistant message
-        may contain tool_use blocks with no corresponding tool_result in
-        the next message.  Append synthetic tool_results so the
-        conversation can continue.
-        """
-        if not self._history:
-            return
-        last = self._history[-1]
-        if last.get("role") != "assistant":
-            return
-        content = last.get("content")
-        if not isinstance(content, list):
-            return
-        tool_ids = [
-            block["id"]
-            for block in content
-            if isinstance(block, dict) and block.get("type") == "tool_use"
-        ]
-        if not tool_ids:
-            return
-        self._history.append(
-            {
-                "role": "user",
-                "content": [
-                    {
-                        "type": "tool_result",
-                        "tool_use_id": tid,
-                        "content": "Cancelled by user.",
-                    }
-                    for tid in tool_ids
-                ],
-            }
-        )
-
-    def _persist_history(self) -> None:
-        """Save current history to disk if a history store is configured."""
-        if self._history_store and self._session_id:
-            self._history_store.save(self._session_id, self._history)
-
-    async def _build_system_prompt(self, user_message: str = "") -> str:
-        import datetime as _dt
-        _now = _dt.datetime.now()
-        _current_datetime = _now.strftime("%A, %B %d, %Y at %I:%M %p")
-
-        prompt = CHAT_SYSTEM_PROMPT.format(
-            runtime_context=self._runtime_context,
-            visualizations_section=build_visualizations_prompt(
-                self._proactive_dashboards
-            ),
-            current_datetime=_current_datetime,
-        )
-        # Inject memory context (replaces old self_awareness)
-        if self._cortex is not None:
-            memory_section = await self._cortex.build_memory_context(user_message)
-            if memory_section:
-                prompt += memory_section
-        elif self._self_awareness is not None:
-            # Fallback for legacy usage (tests, etc.)
-            sa_section = self._self_awareness.build_prompt_section()
-            if sa_section:
-                prompt += sa_section
-        # Inject anton.md project context (user-written takes priority)
-        if self._workspace is not None:
-            md_context = self._workspace.build_anton_md_context()
-            if md_context:
-                prompt += md_context
-        # Inject connected datasource context without credentials
-        ds_ctx = build_datasource_context(active_only=self._active_datasource)
-        if ds_ctx:
-            prompt += ds_ctx
-        return prompt
-
-    # Packages the LLM is most likely to care about when writing scratchpad code.
-    _NOTABLE_PACKAGES: set[str] = {
-        "numpy",
-        "pandas",
-        "matplotlib",
-        "seaborn",
-        "scipy",
-        "scikit-learn",
-        "requests",
-        "httpx",
-        "aiohttp",
-        "beautifulsoup4",
-        "lxml",
-        "pillow",
-        "sympy",
-        "networkx",
-        "sqlalchemy",
-        "pydantic",
-        "rich",
-        "tqdm",
-        "click",
-        "fastapi",
-        "flask",
-        "django",
-        "openai",
-        "anthropic",
-        "tiktoken",
-        "transformers",
-        "torch",
-        "polars",
-        "pyarrow",
-        "openpyxl",
-        "xlsxwriter",
-        "plotly",
-        "bokeh",
-        "altair",
-        "pytest",
-        "hypothesis",
-        "yaml",
-        "pyyaml",
-        "toml",
-        "tomli",
-        "tomllib",
-        "jinja2",
-        "markdown",
-        "pygments",
-        "cryptography",
-        "paramiko",
-        "boto3",
-    }
-
-    def _build_tools(self) -> list[dict]:
-        scratchpad_tool = dict(SCRATCHPAD_TOOL)
-        pkg_list = self._scratchpads._available_packages
-        if pkg_list:
-            notable = sorted(p for p in pkg_list if p.lower() in self._NOTABLE_PACKAGES)
-            if notable:
-                pkg_line = ", ".join(notable)
-                extra = f"\n\nInstalled packages ({len(pkg_list)} total, notable: {pkg_line})."
-            else:
-                extra = f"\n\nInstalled packages: {len(pkg_list)} total (standard library plus dependencies)."
-            scratchpad_tool["description"] = SCRATCHPAD_TOOL["description"] + extra
-
-        # Inject scratchpad wisdom from memory (procedural priming)
-        if self._cortex is not None:
-            wisdom = self._cortex.get_scratchpad_context()
-            if wisdom:
-                scratchpad_tool[
-                    "description"
-                ] += f"\n\nLessons from past sessions:\n{wisdom}"
-
-        tools = [scratchpad_tool]
-        if self._cortex is not None:
-            tools.append(MEMORIZE_TOOL)
-        elif self._self_awareness is not None:
-            # Legacy fallback
-            from anton.tools import MEMORIZE_TOOL as _MT
-
-            tools.append(_MT)
-        if self._episodic is not None and self._episodic.enabled:
-            tools.append(RECALL_TOOL)
-        tools.append(CONNECT_DATASOURCE_TOOL)
-        tools.append(PUBLISH_TOOL)
-        return tools
-
-    async def close(self) -> None:
-        """Clean up scratchpads and other resources."""
-        await self._scratchpads.close_all()
-
-    async def _summarize_history(self) -> None:
-        """Compress old conversation turns into a summary using the coding model.
-
-        Splits history into old (first 60%) and recent (last 40%), keeping at
-        least 4 recent turns.  The old portion is summarized by the fast coding
-        model and replaced with a single user message.
-        """
-        if len(self._history) < 6:
-            return  # Too short to summarize
-
-        min_recent = 4
-        split = max(int(len(self._history) * 0.6), 1)
-        # Ensure we keep at least min_recent turns
-        split = min(split, len(self._history) - min_recent)
-        if split < 2:
-            return
-
-        # Walk split backward to avoid breaking tool_use / tool_result pairs.
-        # A user message containing tool_result blocks must stay with the
-        # preceding assistant message that contains the matching tool_use.
-        while split > 1:
-            msg = self._history[split]
-            if msg.get("role") != "user":
-                break
-            content = msg.get("content")
-            if not isinstance(content, list):
-                break
-            has_tool_result = any(
-                isinstance(b, dict) and b.get("type") == "tool_result" for b in content
-            )
-            if not has_tool_result:
-                break
-            # This user message has tool_results — keep it (and its paired
-            # assistant message) in the recent portion.
-            split -= 1
-            # Also pull back over the preceding assistant message so the
-            # pair stays together.
-            if split > 1 and self._history[split].get("role") == "assistant":
-                split -= 1
-
-        if split < 2:
-            return
-
-        old_turns = self._history[:split]
-        recent_turns = self._history[split:]
-
-        # Serialize old turns into text for summarization
-        lines: list[str] = []
-        for msg in old_turns:
-            role = msg.get("role", "unknown")
-            content = msg.get("content", "")
-            if isinstance(content, str):
-                lines.append(f"[{role}]: {content[:2000]}")
-            elif isinstance(content, list):
-                for block in content:
-                    if isinstance(block, dict):
-                        if block.get("type") == "text":
-                            lines.append(f"[{role}]: {block['text'][:1000]}")
-                        elif block.get("type") == "tool_use":
-                            lines.append(
-                                f"[{role}/tool_use]: {block.get('name', '')}({str(block.get('input', ''))[:500]})"
-                            )
-                        elif block.get("type") == "tool_result":
-                            lines.append(
-                                f"[tool_result]: {str(block.get('content', ''))[:500]}"
-                            )
-
-        old_text = "\n".join(lines)
-        # Cap at ~8000 chars to avoid overloading the summarizer
-        if len(old_text) > 8000:
-            old_text = old_text[:8000] + "\n... (truncated)"
-
-        try:
-            summary_response = await self._llm.code(
-                system=(
-                    "Summarize this conversation history concisely. Preserve:\n"
-                    "- Key decisions and conclusions\n"
-                    "- Important data/results discovered\n"
-                    "- Variable names and values that are still relevant\n"
-                    "- Errors encountered and how they were resolved\n"
-                    "Keep it under 2000 tokens. Use bullet points."
-                ),
-                messages=[{"role": "user", "content": old_text}],
-                max_tokens=2048,
-            )
-            summary = summary_response.content or "(summary unavailable)"
-        except Exception:
-            # If summarization fails, just do a simple truncation
-            summary = f"(Earlier conversation with {len(old_turns)} turns — summarization failed)"
-
-        summary_msg = {
-            "role": "user",
-            "content": f"[Context summary of earlier conversation]\n{summary}",
-        }
-
-        # If the recent portion starts with a user message, insert a minimal
-        # assistant separator to avoid consecutive user messages (API error).
-        if recent_turns and recent_turns[0].get("role") == "user":
-            self._history = [
-                summary_msg,
-                {"role": "assistant", "content": "Understood."},
-                *recent_turns,
-            ]
-        else:
-            self._history = [summary_msg] + recent_turns
-
-    def _compact_scratchpads(self) -> bool:
-        """Compact all active scratchpads. Returns True if any were compacted."""
-        compacted = False
-        for pad in self._scratchpads._pads.values():
-            if pad._compact_cells():
-                compacted = True
-        return compacted
-
-    async def turn(self, user_input: str | list[dict]) -> str:
-        self._history.append({"role": "user", "content": user_input})
-
-        user_msg_str = user_input if isinstance(user_input, str) else ""
-        system = await self._build_system_prompt(user_msg_str)
-        tools = self._build_tools()
-
-        try:
-            response = await self._llm.plan(
-                system=system,
-                messages=self._history,
-                tools=tools,
-            )
-        except ContextOverflowError:
-            await self._summarize_history()
-            self._compact_scratchpads()
-            response = await self._llm.plan(
-                system=system,
-                messages=self._history,
-                tools=tools,
-            )
-
-        # Proactive compaction
-        if response.usage.context_pressure > _CONTEXT_PRESSURE_THRESHOLD:
-            await self._summarize_history()
-            self._compact_scratchpads()
-
-        # Handle tool calls
-        tool_round = 0
-        error_streak: dict[str, int] = {}
-        resilience_nudged: set[str] = set()
-
-        while response.tool_calls:
-            tool_round += 1
-            if tool_round > _MAX_TOOL_ROUNDS:
-                self._history.append(
-                    {"role": "assistant", "content": response.content or ""}
-                )
-                self._history.append(
-                    {
-                        "role": "user",
-                        "content": (
-                            f"SYSTEM: You have used {_MAX_TOOL_ROUNDS} tool-call rounds on this turn. "
-                            "Pause here. Summarize what you have accomplished so far and what remains. "
-                            "If you believe you are on a good track and can finish the task with more steps, "
-                            "tell the user and ask if they'd like you to continue. "
-                            "Do NOT retry automatically — wait for the user's response."
-                        ),
-                    }
-                )
-                response = await self._llm.plan(
-                    system=system,
-                    messages=self._history,
-                )
-                break
-
-            # Build assistant message with content blocks
-            assistant_content: list[dict] = []
-            if response.content:
-                assistant_content.append({"type": "text", "text": response.content})
-            for tc in response.tool_calls:
-                assistant_content.append(
-                    {
-                        "type": "tool_use",
-                        "id": tc.id,
-                        "name": tc.name,
-                        "input": tc.input,
-                    }
-                )
-            self._history.append({"role": "assistant", "content": assistant_content})
-
-            # Process each tool call via registry
-            tool_results: list[dict] = []
-            for tc in response.tool_calls:
-                try:
-                    result_text = await dispatch_tool(self, tc.name, tc.input)
-                except Exception as exc:
-                    result_text = f"Tool '{tc.name}' failed: {exc}"
-
-                result_text = scrub_credentials(result_text)
-                result_text = _apply_error_tracking(
-                    result_text,
-                    tc.name,
-                    error_streak,
-                    resilience_nudged,
-                )
-
-                tool_results.append(
-                    {
-                        "type": "tool_result",
-                        "tool_use_id": tc.id,
-                        "content": result_text,
-                    }
-                )
-
-            self._history.append({"role": "user", "content": tool_results})
-
-            # Get follow-up from LLM
-            try:
-                response = await self._llm.plan(
-                    system=system,
-                    messages=self._history,
-                    tools=tools,
-                )
-            except ContextOverflowError:
-                await self._summarize_history()
-                self._compact_scratchpads()
-                response = await self._llm.plan(
-                    system=system,
-                    messages=self._history,
-                    tools=tools,
-                )
-
-            # Proactive compaction during tool loop
-            if response.usage.context_pressure > _CONTEXT_PRESSURE_THRESHOLD:
-                await self._summarize_history()
-                self._compact_scratchpads()
-
-        # Text-only response
-        reply = response.content or ""
-        self._history.append({"role": "assistant", "content": reply})
-
-        # Periodic memory vacuum (Systems Consolidation)
-        if self._cortex is not None and self._cortex.mode != "off":
-            self._cortex.maybe_vacuum()
-
-        return reply
-
-    async def turn_stream(
-        self, user_input: str | list[dict]
-    ) -> AsyncIterator[StreamEvent]:
-        """Streaming version of turn(). Yields events as they arrive."""
-        self._history.append({"role": "user", "content": user_input})
-
-        # Log user input to episodic memory
-        if self._episodic is not None:
-            content = (
-                user_input if isinstance(user_input, str) else str(user_input)[:2000]
-            )
-            self._episodic.log_turn(self._turn_count + 1, "user", content)
-
-        user_msg_str = user_input if isinstance(user_input, str) else ""
-        assistant_text_parts: list[str] = []
-        _max_auto_retries = 2
-        _retry_count = 0
-
-        while True:
-            try:
-                async for event in self._stream_and_handle_tools(user_msg_str):
-                    if isinstance(event, StreamTextDelta):
-                        assistant_text_parts.append(event.text)
-                    yield event
-                break  # completed successfully
-            except Exception as _agent_exc:
-                # Token/billing limit — don't retry, let the chat loop handle it
-                if isinstance(_agent_exc, TokenLimitExceeded):
-                    raise
-                _retry_count += 1
-                if _retry_count <= _max_auto_retries:
-                    # Inject the error into history and let the LLM try to recover
-                    self._history.append(
-                        {
-                            "role": "user",
-                            "content": (
-                                f"SYSTEM: An error interrupted execution: {_agent_exc}\n\n"
-                                "If you can diagnose and fix the issue, continue working on the task. "
-                                "Adjust your approach to avoid the same error. "
-                                "If this is unrecoverable, summarize what you accomplished and suggest next steps."
-                            ),
-                        }
-                    )
-                    # Continue the while loop — _stream_and_handle_tools will be called
-                    # again with the error context now in history
-                    continue
-                else:
-                    # Exhausted retries — stop and summarize for the user
-                    self._history.append(
-                        {
-                            "role": "user",
-                            "content": (
-                                f"SYSTEM: The task has failed {_retry_count} times. Latest error: {_agent_exc}\n\n"
-                                "Stop retrying. Please:\n"
-                                "1. Summarize what you accomplished so far.\n"
-                                "2. Explain what went wrong in plain language.\n"
-                                "3. Suggest next steps — what the user can try (e.g. rephrase, "
-                                "simplify the request, or ask you to continue from where you left off).\n"
-                                "Be concise and helpful."
-                            ),
-                        }
-                    )
-                    try:
-                        async for event in self._llm.plan_stream(
-                            system=await self._build_system_prompt(user_msg_str),
-                            messages=self._history,
-                        ):
-                            if isinstance(event, StreamTextDelta):
-                                assistant_text_parts.append(event.text)
-                            yield event
-                    except Exception:
-                        fallback = f"An unexpected error occurred: {_agent_exc}. Please try again or rephrase your request."
-                        assistant_text_parts.append(fallback)
-                        yield StreamTextDelta(text=fallback)
-                    break
-
-        # Log assistant response to episodic memory
-        if self._episodic is not None and assistant_text_parts:
-            self._episodic.log_turn(
-                self._turn_count + 1,
-                "assistant",
-                "".join(assistant_text_parts)[:2000],
-            )
-
-        # Identity extraction (Default Mode Network — every 5 turns)
-        self._turn_count += 1
-        self._persist_history()
-        if self._cortex is not None and self._cortex.mode != "off":
-            if self._turn_count % 5 == 0 and isinstance(user_input, str):
-                asyncio.create_task(self._cortex.maybe_update_identity(user_input))
-            # Periodic memory vacuum (Systems Consolidation)
-            self._cortex.maybe_vacuum()
-
-    async def _stream_and_handle_tools(
-        self, user_message: str = ""
-    ) -> AsyncIterator[StreamEvent]:
-        """Stream one LLM call, handle tool loops, yield all events."""
-        system = await self._build_system_prompt(user_message)
-        tools = self._build_tools()
-
-        # Guard against summarizing an already-summarized history within the same
-        # turn (e.g. ContextOverflowError on first call + pressure > threshold on
-        # the tool-loop follow-up would previously produce a summary of a summary).
-        _compacted_this_turn = False
-
-        response: StreamComplete | None = None
-
-        try:
-            async for event in self._llm.plan_stream(
-                system=system,
-                messages=self._history,
-                tools=tools,
-            ):
-                yield event
-                if isinstance(event, StreamComplete):
-                    response = event
-        except ContextOverflowError:
-            await self._summarize_history()
-            self._compact_scratchpads()
-            _compacted_this_turn = True
-            yield StreamContextCompacted(
-                message="Context was getting long — older history has been summarized."
-            )
-            async for event in self._llm.plan_stream(
-                system=system,
-                messages=self._history,
-                tools=tools,
-            ):
-                yield event
-                if isinstance(event, StreamComplete):
-                    response = event
-
-        if response is None:
-            return
-
-        llm_response = response.response
-
-        # Detect max_tokens truncation — the LLM was cut off mid-response.
-        # Inject a continuation prompt so it can finish what it was doing.
-        if llm_response.stop_reason in ("max_tokens", "length") and not llm_response.tool_calls:
-            self._history.append(
-                {"role": "assistant", "content": llm_response.content or ""}
-            )
-            self._history.append(
-                {
-                    "role": "user",
-                    "content": (
-                        "SYSTEM: Your response was truncated because it exceeded the output token limit. "
-                        "Continue exactly where you left off. If you were about to call a tool, "
-                        "call it now. If the code you were writing was too long, split it into smaller parts."
-                    ),
-                }
-            )
-            response = None
-            try:
-                async for event in self._llm.plan_stream(
-                    system=system,
-                    messages=self._history,
-                    tools=tools,
-                ):
-                    yield event
-                    if isinstance(event, StreamComplete):
-                        response = event
-            except ContextOverflowError:
-                if not _compacted_this_turn:
-                    await self._summarize_history()
-                    self._compact_scratchpads()
-                    _compacted_this_turn = True
-                yield StreamContextCompacted(
-                    message="Context was getting long — older history has been summarized."
-                )
-                async for event in self._llm.plan_stream(
-                    system=system,
-                    messages=self._history,
-                    tools=tools,
-                ):
-                    yield event
-                    if isinstance(event, StreamComplete):
-                        response = event
-
-            if response is None:
-                return
-            llm_response = response.response
-
-        # Proactive compaction
-        if (
-            not _compacted_this_turn
-            and llm_response.usage.context_pressure > _CONTEXT_PRESSURE_THRESHOLD
-        ):
-            await self._summarize_history()
-            self._compact_scratchpads()
-            _compacted_this_turn = True
-            yield StreamContextCompacted(
-                message="Context was getting long — older history has been summarized."
-            )
-
-        # Tool-call loop with circuit breaker, wrapped in a completion
-        # verification outer loop that can restart the tool loop if the
-        # task isn't actually done yet.
-        continuation = 0
-        _max_rounds_hit = False
-
-        while True:  # Completion verification loop
-            tool_round = 0
-            error_streak: dict[str, int] = {}
-            resilience_nudged: set[str] = set()
-
-            while llm_response.tool_calls:
-                tool_round += 1
-                if tool_round > _MAX_TOOL_ROUNDS:
-                    _max_rounds_hit = True
-                    self._history.append(
-                        {"role": "assistant", "content": llm_response.content or ""}
-                    )
-                    self._history.append(
-                        {
-                            "role": "user",
-                            "content": (
-                                f"SYSTEM: You have used {_MAX_TOOL_ROUNDS} tool-call rounds on this turn. "
-                                "Pause here. Summarize what you have accomplished so far and what remains. "
-                                "If you believe you are on a good track and can finish the task with more steps, "
-                                "tell the user and ask if they'd like you to continue. "
-                                "Do NOT retry automatically — wait for the user's response."
-                            ),
-                        }
-                    )
-                    async for event in self._llm.plan_stream(
-                        system=system,
-                        messages=self._history,
-                    ):
-                        yield event
-                    break
-
-                # Build assistant message with content blocks
-                assistant_content: list[dict] = []
-                if llm_response.content:
-                    assistant_content.append(
-                        {"type": "text", "text": llm_response.content}
-                    )
-                for tc in llm_response.tool_calls:
-                    assistant_content.append(
-                        {
-                            "type": "tool_use",
-                            "id": tc.id,
-                            "name": tc.name,
-                            "input": tc.input,
-                        }
-                    )
-                self._history.append(
-                    {"role": "assistant", "content": assistant_content}
-                )
-
-                # Process each tool call
-                tool_results: list[dict] = []
-                for tc in llm_response.tool_calls:
-                    if self._episodic is not None:
-                        self._episodic.log_turn(
-                            self._turn_count + 1,
-                            "tool_call",
-                            str(tc.input)[:2000],
-                            tool=tc.name,
-                        )
-
-                    try:
-                        if tc.name == "scratchpad" and tc.input.get("action") == "exec":
-                            # Inline streaming exec — yields progress events
-                            prep = await prepare_scratchpad_exec(self, tc.input)
-                            if isinstance(prep, str):
-                                result_text = prep
-                            else:
-                                (
-                                    pad,
-                                    code,
-                                    description,
-                                    estimated_time,
-                                    estimated_seconds,
-                                ) = prep
-                                yield StreamTaskProgress(
-                                    phase="scratchpad_start",
-                                    message=description or "Running code",
-                                    eta_seconds=estimated_seconds,
-                                )
-                                import time as _time
-
-                                _sp_t0 = _time.monotonic()
-                                from anton.scratchpad import Cell
-
-                                cell = None
-                                async for item in pad.execute_streaming(
-                                    code,
-                                    description=description,
-                                    estimated_time=estimated_time,
-                                    estimated_seconds=estimated_seconds,
-                                    cancel_event=self._cancel_event,
-                                ):
-                                    if isinstance(item, str):
-                                        yield StreamTaskProgress(
-                                            phase="scratchpad", message=item
-                                        )
-                                    elif isinstance(item, Cell):
-                                        cell = item
-                                _sp_elapsed = _time.monotonic() - _sp_t0
-                                yield StreamTaskProgress(
-                                    phase="scratchpad_done",
-                                    message=description or "Done",
-                                    eta_seconds=_sp_elapsed,
-                                )
-                                result_text = (
-                                    format_cell_result(cell)
-                                    if cell
-                                    else "No result produced."
-                                )
-                                if self._episodic is not None and cell is not None:
-                                    self._episodic.log_turn(
-                                        self._turn_count + 1,
-                                        "scratchpad",
-                                        (cell.stdout or "")[:2000],
-                                        description=description,
-                                    )
-                        elif tc.name == "connect_new_datasource" or (
-                            tc.name == "publish_or_preview" and tc.input.get("action") == "publish"
-                        ):
-                            # Interactive tool — pause spinner AND escape watcher
-                            yield StreamTaskProgress(
-                                phase="interactive",
-                                message="",
-                            )
-                            if self._escape_watcher:
-                                self._escape_watcher.pause()
-                            result_text = await dispatch_tool(self, tc.name, tc.input)
-                            if self._escape_watcher:
-                                self._escape_watcher.resume()
-                            yield StreamTaskProgress(
-                                phase="analyzing",
-                                message="Analyzing results...",
-                            )
-                        else:
-                            result_text = await dispatch_tool(self, tc.name, tc.input)
-                            if (
-                                tc.name == "scratchpad"
-                                and tc.input.get("action") == "dump"
-                            ):
-                                yield StreamToolResult(content=result_text)
-                                result_text = (
-                                    "The full notebook has been displayed to the user above. "
-                                    "Do not repeat it. Here is the content for your reference:\n\n"
-                                    + result_text
-                                )
-                    except Exception as exc:
-                        result_text = f"Tool '{tc.name}' failed: {exc}"
-
-                    if self._episodic is not None:
-                        self._episodic.log_turn(
-                            self._turn_count + 1,
-                            "tool_result",
-                            result_text[:2000],
-                            tool=tc.name,
-                        )
-                    result_text = scrub_credentials(result_text)
-                    result_text = _apply_error_tracking(
-                        result_text, tc.name, error_streak, resilience_nudged
-                    )
-                    tool_results.append(
-                        {
-                            "type": "tool_result",
-                            "tool_use_id": tc.id,
-                            "content": result_text,
-                        }
-                    )
-
-                self._history.append({"role": "user", "content": tool_results})
-
-                # Signal that tools are done and LLM is now analyzing
-                yield StreamTaskProgress(
-                    phase="analyzing", message="Analyzing results..."
-                )
-
-                # Stream follow-up
-                response = None
-                try:
-                    async for event in self._llm.plan_stream(
-                        system=system,
-                        messages=self._history,
-                        tools=tools,
-                    ):
-                        yield event
-                        if isinstance(event, StreamComplete):
-                            response = event
-                except ContextOverflowError:
-                    if not _compacted_this_turn:
-                        await self._summarize_history()
-                        self._compact_scratchpads()
-                        _compacted_this_turn = True
-                    yield StreamContextCompacted(
-                        message="Context was getting long — older history has been summarized."
-                    )
-                    async for event in self._llm.plan_stream(
-                        system=system,
-                        messages=self._history,
-                        tools=tools,
-                    ):
-                        yield event
-                        if isinstance(event, StreamComplete):
-                            response = event
-
-                if response is None:
-                    return
-                llm_response = response.response
-
-                # Detect max_tokens truncation inside tool loop
-                if llm_response.stop_reason in ("max_tokens", "length") and not llm_response.tool_calls:
-                    self._history.append(
-                        {"role": "assistant", "content": llm_response.content or ""}
-                    )
-                    self._history.append(
-                        {
-                            "role": "user",
-                            "content": (
-                                "SYSTEM: Your response was truncated because it exceeded the output token limit. "
-                                "Continue exactly where you left off. If you were about to call a tool, "
-                                "call it now. If the code you were writing was too long, split it into smaller parts."
-                            ),
-                        }
-                    )
-                    response = None
-                    try:
-                        async for event in self._llm.plan_stream(
-                            system=system,
-                            messages=self._history,
-                            tools=tools,
-                        ):
-                            yield event
-                            if isinstance(event, StreamComplete):
-                                response = event
-                    except ContextOverflowError:
-                        if not _compacted_this_turn:
-                            await self._summarize_history()
-                            self._compact_scratchpads()
-                            _compacted_this_turn = True
-                        yield StreamContextCompacted(
-                            message="Context was getting long — older history has been summarized."
-                        )
-                        async for event in self._llm.plan_stream(
-                            system=system,
-                            messages=self._history,
-                            tools=tools,
-                        ):
-                            yield event
-                            if isinstance(event, StreamComplete):
-                                response = event
-
-                    if response is None:
-                        return
-                    llm_response = response.response
-
-                # Proactive compaction during tool loop
-                if (
-                    not _compacted_this_turn
-                    and llm_response.usage.context_pressure
-                    > _CONTEXT_PRESSURE_THRESHOLD
-                ):
-                    await self._summarize_history()
-                    self._compact_scratchpads()
-                    _compacted_this_turn = True
-                    yield StreamContextCompacted(
-                        message="Context was getting long — older history has been summarized."
-                    )
-
-            # --- Completion verification ---
-            # Only verify when tools were actually used (not for simple Q&A)
-            # and we haven't hit the max-rounds hard stop.
-            if tool_round == 0 or _max_rounds_hit:
-                break
-
-            # Append the assistant's final text so the verifier can see it
-            reply = llm_response.content or ""
-            self._history.append({"role": "assistant", "content": reply})
-
-            if continuation >= _MAX_CONTINUATIONS:
-                # Budget exhausted — ask LLM to diagnose and present to user
-                self._history.append(
-                    {
-                        "role": "user",
-                        "content": (
-                            "SYSTEM: You have attempted to complete this task multiple times "
-                            "but verification indicates it is still not done. Do NOT try again. "
-                            "Instead:\n"
-                            "1. Summarize exactly what was accomplished so far.\n"
-                            "2. Identify the specific blocker or failure preventing completion.\n"
-                            "3. Suggest concrete next steps the user can take to unblock this.\n"
-                            "Be honest and specific — do not be vague about what went wrong."
-                        ),
-                    }
-                )
-                yield StreamTaskProgress(
-                    phase="analyzing", message="Diagnosing incomplete task..."
-                )
-                async for event in self._llm.plan_stream(
-                    system=system,
-                    messages=self._history,
-                ):
-                    yield event
-                # Consolidation still runs after diagnosis
-                break
-
-            # Ask the LLM to self-assess completion.
-            # Use a copy of history with a trailing user message so models
-            # that don't support assistant-prefill won't reject the request.
-            verify_messages = list(self._history) + [
-                {
-                    "role": "user",
-                    "content": (
-                        "SYSTEM: Evaluate whether the task the user originally requested "
-                        "has been fully completed based on the conversation above."
-                    ),
-                }
-            ]
-            verification = await self._llm.plan(
-                system=(
-                    "You are a task-completion verifier. Given the conversation, determine "
-                    "whether the user's original request has been fully completed.\n\n"
-                    "Respond with EXACTLY one of these lines, followed by a brief reason:\n"
-                    "STATUS: COMPLETE — <reason>\n"
-                    "STATUS: INCOMPLETE — <reason>\n"
-                    "STATUS: STUCK — <reason>\n\n"
-                    "COMPLETE = the task is done or the response fully answers the question.\n"
-                    "INCOMPLETE = more work can be done to finish the task.\n"
-                    "STUCK = a blocker prevents completion (missing info, permissions, etc).\n\n"
-                    "Be strict: if the user asked for X and only part of X was delivered, "
-                    "that is INCOMPLETE, not COMPLETE. But if the user asked a question "
-                    "and the assistant answered it, that is COMPLETE even without tool use."
-                ),
-                messages=verify_messages,
-                max_tokens=256,
-            )
-
-            status_text = (verification.content or "").strip().upper()
-            if "STATUS: COMPLETE" in status_text:
-                break
-            if "STATUS: STUCK" in status_text:
-                # Stuck — inject diagnosis request and let the LLM explain
-                reason = (verification.content or "").strip()
-                self._history.append(
-                    {
-                        "role": "user",
-                        "content": (
-                            f"SYSTEM: Task verification determined this task is stuck.\n"
-                            f"Verifier assessment: {reason}\n\n"
-                            "Explain to the user what went wrong, what you tried, and "
-                            "suggest specific next steps they can take to unblock this."
-                        ),
-                    }
-                )
-                yield StreamTaskProgress(
-                    phase="analyzing", message="Diagnosing blocked task..."
-                )
-                async for event in self._llm.plan_stream(
-                    system=system,
-                    messages=self._history,
-                ):
-                    yield event
-                break
-
-            # INCOMPLETE — continue working
-            continuation += 1
-            reason = (verification.content or "").strip()
-            self._history.append(
-                {
-                    "role": "user",
-                    "content": (
-                        f"SYSTEM: Task verification determined this task is not yet complete "
-                        f"(attempt {continuation}/{_MAX_CONTINUATIONS}).\n"
-                        f"Verifier assessment: {reason}\n\n"
-                        "Continue working on the original request. Pick up where you left off "
-                        "and finish the remaining work. Do not repeat work already done."
-                    ),
-                }
-            )
-            yield StreamTaskProgress(
-                phase="analyzing",
-                message=f"Task incomplete — continuing ({continuation}/{_MAX_CONTINUATIONS})...",
-            )
-
-            # Re-enter tool loop: get next LLM response with tools available
-            response = None
-            async for event in self._llm.plan_stream(
-                system=system,
-                messages=self._history,
-                tools=tools,
-            ):
-                yield event
-                if isinstance(event, StreamComplete):
-                    response = event
-            if response is None:
-                return
-            llm_response = response.response
-            # Loop back to the top of the completion verification loop
-
-        # Text-only final response — append to history (if not already appended
-        # by the verification block above).
-        if not self._history or self._history[-1].get("role") != "assistant":
-            reply = llm_response.content or ""
-            self._history.append({"role": "assistant", "content": reply})
-
-        # Consolidation: replay scratchpad sessions to extract lessons
-        if self._cortex is not None and self._cortex.mode != "off":
-            self._maybe_consolidate_scratchpads()
-
-    def _maybe_consolidate_scratchpads(self) -> None:
-        """Check if any scratchpad sessions warrant consolidation and fire it off."""
-        from anton.memory.consolidator import Consolidator
-
-        consolidator = Consolidator()
-        for pad in self._scratchpads._pads.values():
-            cells = list(pad.cells)
-            if consolidator.should_replay(cells):
-                asyncio.create_task(self._consolidate(cells))
-
-    async def _consolidate(self, cells: list) -> None:
-        """Run offline consolidation on a completed scratchpad session."""
-        from anton.memory.consolidator import Consolidator
-
-        consolidator = Consolidator()
-        engrams = await consolidator.replay_and_extract(cells, self._llm)
-        if not engrams or self._cortex is None:
-            return
-
-        auto_encode = [e for e in engrams if not self._cortex.encoding_gate(e)]
-        needs_confirm = [e for e in engrams if self._cortex.encoding_gate(e)]
-
-        if auto_encode:
-            await self._cortex.encode(auto_encode)
-
-        if needs_confirm:
-            self._pending_memory_confirmations.extend(needs_confirm)
-
-
-def _apply_error_tracking(
-    result_text: str,
-    tool_name: str,
-    error_streak: dict[str, int],
-    resilience_nudged: set[str],
-) -> str:
-    """Track consecutive errors per tool and append nudge/circuit-breaker messages."""
-    is_error = any(
-        marker in result_text
-        for marker in ("[error]", "Task failed:", "failed", "timed out", "Rejected:")
-    )
-    if is_error:
-        error_streak[tool_name] = error_streak.get(tool_name, 0) + 1
-    else:
-        error_streak[tool_name] = 0
-        resilience_nudged.discard(tool_name)
-
-    streak = error_streak.get(tool_name, 0)
-    if streak >= _RESILIENCE_NUDGE_AT and tool_name not in resilience_nudged:
-        result_text += _RESILIENCE_NUDGE
-        resilience_nudged.add(tool_name)
-
-    if streak >= _MAX_CONSECUTIVE_ERRORS:
-        result_text += (
-            f"\n\nSYSTEM: The '{tool_name}' tool has failed {_MAX_CONSECUTIVE_ERRORS} times "
-            "in a row. Stop retrying this approach. Either try a completely different "
-            "strategy or tell the user what's going wrong so they can help."
-        )
-
-    return result_text
-
-
-
 async def _handle_connect(
     console: Console,
     settings: AntonSettings,
@@ -1514,6 +335,7 @@ async def _handle_publish(
     file_arg: str = "",
 ) -> None:
     """Handle /publish command — publish an HTML report to the web."""
+    import json
     import webbrowser
     from pathlib import Path
 
@@ -1615,15 +437,44 @@ async def _handle_publish(
         console.print()
         return
 
-    # 3. Publish
+    # 3. Check if this file was previously published
+    published_json = output_dir / ".published.json"
+    published_map = {}
+    try:
+        if published_json.is_file():
+            published_map = json.loads(published_json.read_text())
+    except Exception:
+        pass
+
+    report_id = None
+    file_key = target.name
+    prev = published_map.get(file_key)
+
+    if prev and prev.get("report_id"):
+        console.print(f"  [anton.muted]Previously published: {prev.get('url', '')}[/]")
+        update_choice = await prompt_or_cancel(
+            "  Update existing report, or publish as new?",
+            choices=["update", "new", "u", "n"],
+            choices_display="update/new",
+            default="update",
+        )
+        if update_choice is None:
+            console.print()
+            return
+        if update_choice in ("update", "u"):
+            report_id = prev["report_id"]
+
+    # 4. Publish
     from rich.live import Live
     from rich.spinner import Spinner
 
-    with Live(Spinner("dots", text="  Publishing...", style="anton.cyan"), console=console, transient=True):
+    action_text = "  Updating..." if report_id else "  Publishing..."
+    with Live(Spinner("dots", text=action_text, style="anton.cyan"), console=console, transient=True):
         try:
             result = publish(
                 target,
                 api_key=settings.minds_api_key,
+                report_id=report_id,
                 publish_url=settings.publish_url,
                 ssl_verify=settings.minds_ssl_verify,
             )
@@ -1633,10 +484,31 @@ async def _handle_publish(
             return
 
     view_url = result.get("view_url", "")
-    console.print(f"  [anton.success]Published![/]")
+    returned_report_id = result.get("report_id", "")
+    version = result.get("version", 1)
+    unchanged = result.get("unchanged", False)
+
+    if unchanged:
+        console.print(f"  [anton.muted]Already up to date (v{version})[/]")
+    elif report_id:
+        console.print(f"  [anton.success]Updated! (v{version})[/]")
+    else:
+        console.print(f"  [anton.success]Published![/]")
     console.print(f"  [link={view_url}]{view_url}[/link]")
     console.print()
 
+    # 5. Save mapping
+    if returned_report_id:
+        published_map[file_key] = {
+            "report_id": returned_report_id,
+            "url": view_url,
+            "last_md5": result.get("md5", ""),
+        }
+        try:
+            published_json.write_text(json.dumps(published_map, indent=2))
+        except Exception:
+            pass
+
     if view_url:
         webbrowser.open(view_url)
 
@@ -1738,7 +610,7 @@ async def _handle_unpublish(
     with Live(Spinner("dots", text="  Removing...", style="anton.cyan"), console=console, transient=True):
         try:
             unpublish(
-                selected["md5"],
+                selected.get("report_id") or selected["md5"],
                 api_key=settings.minds_api_key,
                 publish_url=settings.publish_url,
                 ssl_verify=settings.minds_ssl_verify,
@@ -1871,7 +743,7 @@ async def _agent_zero(console: Console, session: "ChatSession", settings) -> str
         f'OUTPUT_PATH = {output_html!r}',
     )
 
-    from anton.scratchpad import Cell
+    from anton.core.backends.base import Cell
     from rich.live import Live
     from rich.spinner import Spinner
     from rich.text import Text
@@ -2097,8 +969,9 @@ async def _chat_loop(
     console: Console, settings: AntonSettings, *, resume: bool = False, first_run: bool = False, desktop_first_run: bool = False
 ) -> None:
     from anton.context.self_awareness import SelfAwarenessContext
-    from anton.llm.client import LLMClient
-    from anton.memory.cortex import Cortex
+    from anton.core.llm.client import LLMClient
+    from anton.core.memory.cortex import Cortex
+    from anton.core.memory.hippocampus import Hippocampus
     from anton.workspace import Workspace
 
     # Use a mutable container so closures always see the current client
@@ -2113,7 +986,7 @@ async def _chat_loop(
 
     # Inject all Local Vault connections as namespaced DS_* env vars so every
     # scratchpad subprocess inherits them. Must happen before any ChatSession is created.
-    dv = DataVault()
+    dv = LocalDataVault()
     dreg = DatasourceRegistry()
     for conn in dv.list_connections():
         dv.inject_env(conn["engine"], conn["name"])  # flat=False by default
@@ -2126,8 +999,8 @@ async def _chat_loop(
     project_memory_dir = settings.workspace_path / ".anton" / "memory"
 
     cortex = Cortex(
-        global_dir=global_memory_dir,
-        project_dir=project_memory_dir,
+        global_hc=Hippocampus(global_memory_dir),
+        project_hc=Hippocampus(project_memory_dir),
         mode=settings.memory_mode,
         llm_client=state["llm_client"],
     )
@@ -2145,7 +1018,7 @@ async def _chat_loop(
     if cortex.needs_compaction():
         asyncio.create_task(cortex.compact_all())
 
-    from anton.memory.episodes import EpisodicMemory
+    from anton.core.memory.episodes import EpisodicMemory
 
     episodes_dir = settings.workspace_path / ".anton" / "episodes"
     episodic = EpisodicMemory(episodes_dir, enabled=settings.episodic_memory)
@@ -2164,26 +1037,23 @@ async def _chat_loop(
     # Build runtime context so the LLM knows what it's running on
     runtime_context = build_runtime_context(settings)
 
-    coding_api_key = (
-        settings.anthropic_api_key
-        if settings.coding_provider == "anthropic"
-        else settings.openai_api_key
-    ) or ""
-    session = ChatSession(
-        state["llm_client"],
+    output_path = f"{settings.output_dir.rstrip('/')}/"
+    session = ChatSession(ChatSessionConfig(
+        llm_client=state["llm_client"],
         self_awareness=self_awareness,
         cortex=cortex,
         episodic=episodic,
-        runtime_context=runtime_context,
+        system_prompt_context=SystemPromptContext(
+            runtime_context=runtime_context,
+            output_context=f"Save output to `{output_path}` (create it if needed).",
+        ),
         workspace=workspace,
         console=console,
-        coding_provider=settings.coding_provider,
-        coding_api_key=coding_api_key,
-        coding_base_url=settings.openai_base_url or "",
         history_store=history_store,
         session_id=current_session_id,
         proactive_dashboards=settings.proactive_dashboards,
-    )
+        tools=[CONNECT_DATASOURCE_TOOL, PUBLISH_TOOL],
+    ))
 
     # Handle --resume flag at startup
     if resume:
@@ -2309,7 +1179,7 @@ def _bottom_toolbar():
                 from anton.channel.theme import get_palette as _gp
                 _you_color = _gp().user_prompt
                 user_input = await prompt_session.prompt_async(
-                    [(f"bold fg:{_you_color}", "you>"), ("", " ")]
+                    [(f"bold fg:{_you_color}", "you>"), ("", '\u2009')]
                 )
             except EOFError:
                 break
@@ -2402,14 +1272,15 @@ def _bottom_toolbar():
                         session._scratchpads,
                         session,
                         prefill=arg or None,
+                        vault=session._data_vault,
                     )
                     continue
                 elif cmd == "/list":
-                    handle_list_data_sources(console)
+                    handle_list_data_sources(console, vault=session._data_vault)
                     continue
                 elif cmd == "/remove":
                     arg = parts[1].strip() if len(parts) > 1 else ""
-                    await handle_remove_data_source(console, arg)
+                    await handle_remove_data_source(console, arg, vault=session._data_vault)
                     continue
                 elif cmd == "/edit":
                     arg = parts[1].strip() if len(parts) > 1 else ""
@@ -2424,14 +1295,41 @@ def _bottom_toolbar():
                             session._scratchpads,
                             session,
                             datasource_name=arg,
+                            vault=session._data_vault,
                         )
                     continue
                 elif cmd == "/test":
                     arg = parts[1].strip() if len(parts) > 1 else ""
                     await handle_test_datasource(
-                        console, session._scratchpads, arg
+                        console, session._scratchpads, arg, vault=session._data_vault
                     )
                     continue
+                elif cmd == "/skill":
+                    # /skill save [name hint] | /skill show <label> | /skill remove <label>
+                    sub_parts = parts[1].strip().split(maxsplit=1) if len(parts) > 1 else []
+                    sub = sub_parts[0] if sub_parts else ""
+                    rest = sub_parts[1] if len(sub_parts) > 1 else ""
+                    if sub == "save":
+                        await handle_skill_save(
+                            console, session, name_hint=rest
+                        )
+                    elif sub == "show":
+                        handle_skill_show(console, rest)
+                    elif sub == "remove":
+                        handle_skill_remove(console, rest)
+                    elif sub == "list" or sub == "":
+                        handle_skills_list(console)
+                    else:
+                        console.print()
+                        console.print(
+                            "[anton.warning]Usage: /skill save [name] | "
+                            "/skill list | /skill show <label> | /skill remove <label>[/]"
+                        )
+                        console.print()
+                    continue
+                elif cmd == "/skills":
+                    handle_skills_list(console)
+                    continue
                 elif cmd == "/resume":
                     session, resumed_id = await handle_resume(
                         console,
@@ -2458,6 +1356,9 @@ def _bottom_toolbar():
                 elif cmd == "/unpublish":
                     await _handle_unpublish(console, settings, workspace)
                     continue
+                elif cmd == "/explain":
+                    handle_explain(console, settings.workspace_path)
+                    continue
                 elif cmd == "/help":
                     print_slash_help(console)
                     continue
@@ -2496,10 +1397,24 @@ def _bottom_toolbar():
 
             _query_count += 1
             _total_questions += 1
+
+            # Determine the LLM provider label for telemetry
+            _provider = settings.planning_provider or ""
+            if _provider == "openai-compatible" and settings.minds_api_key:
+                _llm_provider = "mdb_ai"
+            elif _provider == "anthropic":
+                _llm_provider = "anthropic"
+            elif "gemini" in (settings.planning_model or "").lower():
+                _llm_provider = "gemini"
+            elif _provider in ("openai", "openai-compatible"):
+                _llm_provider = "openai"
+            else:
+                _llm_provider = "other"
+
             if _query_count == 1:
-                send_event(settings, "anton_first_query")
+                send_event(settings, "anton_first_query", llm_provider=_llm_provider)
             else:
-                send_event(settings, "anton_query")
+                send_event(settings, "anton_query", llm_provider=_llm_provider)
 
             display.start()
             t0 = time.monotonic()
@@ -2543,7 +1458,7 @@ def _bottom_toolbar():
                 if settings.minds_api_key and settings.minds_url:
                     #TODO: Lets check if this is best solution
                     now = time.monotonic()
-                    if last_token_status_checked_at is None or (now - last_token_status_checked_at) >= TOKEN_STATUS_CACHE_TTL:
+                    if last_token_status_checked_at is None or (now - last_token_status_checked_at) >= settings.token_status_cache_ttl:
                         last_token_status = check_minds_token_limits(
                             settings.minds_url.rstrip("/"),
                             settings.minds_api_key,
diff --git a/anton/chat_session.py b/anton/chat_session.py
index a042ab52..846ec0da 100644
--- a/anton/chat_session.py
+++ b/anton/chat_session.py
@@ -8,12 +8,13 @@
 from rich.console import Console
 
 from anton.config.settings import AntonSettings
+from anton.core.llm.prompt_builder import SystemPromptContext
 from anton.minds_client import refresh_knowledge
 
 if TYPE_CHECKING:
     from anton.chat import ChatSession
-    from anton.memory.cortex import Cortex
-    from anton.memory.episodes import EpisodicMemory
+    from anton.core.memory.cortex import Cortex
+    from anton.core.memory.episodes import EpisodicMemory
     from anton.memory.history_store import HistoryStore
     from anton.workspace import Workspace
 
@@ -65,8 +66,9 @@ def rebuild_session(
     session_id: str | None = None,
 ) -> "ChatSession":
     """Rebuild LLMClient + ChatSession after settings change."""
-    from anton.llm.client import LLMClient
+    from anton.core.llm.client import LLMClient
     from anton.chat import ChatSession
+    from anton.core.session import ChatSessionConfig
 
     state["llm_client"] = LLMClient.from_settings(settings)
 
@@ -79,23 +81,19 @@ def rebuild_session(
     refresh_knowledge(settings, cortex)
 
     runtime_context = build_runtime_context(settings)
-    api_key = (
-        settings.anthropic_api_key
-        if settings.coding_provider == "anthropic"
-        else settings.openai_api_key
-    ) or ""
-    return ChatSession(
-        state["llm_client"],
+    output_path = f"{settings.output_dir.rstrip('/')}/"
+    return ChatSession(ChatSessionConfig(
+        llm_client=state["llm_client"],
         self_awareness=self_awareness,
         cortex=cortex,
         episodic=episodic,
-        runtime_context=runtime_context,
+        system_prompt_context=SystemPromptContext(
+            runtime_context=runtime_context,
+            output_context=f"Save output to `{output_path}` (create it if needed).",
+        ),
         workspace=workspace,
         console=console,
-        coding_provider=settings.coding_provider,
-        coding_api_key=api_key,
-        coding_base_url=settings.openai_base_url or "",
         history_store=history_store,
         session_id=session_id,
         proactive_dashboards=settings.proactive_dashboards,
-    )
+    ))
diff --git a/anton/chat_ui.py b/anton/chat_ui.py
index a50c5e59..ee891a01 100644
--- a/anton/chat_ui.py
+++ b/anton/chat_ui.py
@@ -28,14 +28,58 @@ class _ToolActivity:
     eta_str: str = ""
     printed: bool = False  # whether the activity line has been printed
     done: bool = False  # whether execution is complete
-
-
-_TOOL_LABELS: dict[str, str] = {
-    "scratchpad": "Scratchpad",
-    "memorize": "Memory",
-    "recall": "Recall",
+    start_time: float = 0.0  # monotonic timestamp when execution began
+    work_elapsed: float = 0.0  # actual execution seconds (filled on done)
+    reasoning_elapsed: float = 0.0  # LLM thinking seconds after this step
+    done_line_printed: bool = False  # whether the combined ✔ line was printed
+
+
+# Witty one-liners for non-scratchpad tool display. One is picked at
+# random each time the tool fires, so the UI never feels repetitive.
+_TOOL_PHRASES: dict[str, list[str]] = {
+    "recall_skill": [
+        "Pulling up the procedure\u2026",
+        "Recalling the recipe\u2026",
+        "Loading the playbook\u2026",
+        "Reaching into procedural memory\u2026",
+        "Activating muscle memory\u2026",
+    ],
+    "memorize": [
+        "Jotting this down\u2026",
+        "Committing to memory\u2026",
+        "Filing away for later\u2026",
+        "Encoding a new engram\u2026",
+        "Stashing that in long-term storage\u2026",
+    ],
+    "recall": [
+        "Digging through the archives\u2026",
+        "Searching episodic memory\u2026",
+        "Rewinding the tape\u2026",
+        "Scanning past conversations\u2026",
+        "Activating hippocampal recall\u2026",
+    ],
+    "publish_or_preview": [
+        "Preparing the preview\u2026",
+        "Rendering your dashboard\u2026",
+        "Getting things ready to show\u2026",
+        "Spinning up the preview\u2026",
+    ],
+    "connect_new_datasource": [
+        "Setting up the connection\u2026",
+        "Wiring up the datasource\u2026",
+        "Establishing the link\u2026",
+    ],
 }
 
+# Fallback for tools without their own phrase list
+_GENERIC_TOOL_PHRASES = [
+    "On it\u2026",
+    "Working on that\u2026",
+    "Running the tool\u2026",
+    "Processing\u2026",
+    "Executing\u2026",
+]
+
 _MAX_DESC = 60
 
 _REFRESH_FPS = 6
@@ -45,24 +89,27 @@ class _ToolActivity:
 
 
 def _tool_display_text(name: str, input_json: str) -> str:
-    """Map tool name + raw JSON input to a human-readable description."""
-    label = _TOOL_LABELS.get(name, name)
+    """Map tool name + raw JSON input to a human-readable description.
+
+    For scratchpad: return just the description text (no wrapper).
+    For other tools: return a witty random phrase from _TOOL_PHRASES.
+    """
     try:
         data = json.loads(input_json)
     except (json.JSONDecodeError, TypeError):
-        return label
+        data = {}
 
-    desc = ""
     if name == "scratchpad":
         desc = data.get("one_line_description") or data.get("action", "")
-    elif name == "memorize":
-        entries = data.get("entries", [])
-        desc = f"{len(entries)} entry/entries"
-    if desc:
-        if len(desc) > _MAX_DESC:
-            desc = desc[: _MAX_DESC - 1] + "\u2026"
-        return f"{label}({desc})"
-    return label
+        if desc:
+            if len(desc) > _MAX_DESC:
+                desc = desc[: _MAX_DESC - 1] + "\u2026"
+            return desc
+        return "Running code"
+
+    # Non-scratchpad: pick a witty phrase
+    phrases = _TOOL_PHRASES.get(name, _GENERIC_TOOL_PHRASES)
+    return random.choice(phrases)  # noqa: S311
 
 
 THINKING_MESSAGES = [
@@ -270,11 +317,15 @@ def show_tool_execution(self, task: str) -> None:
 
     def on_tool_use_start(self, tool_id: str, name: str) -> None:
         """Track a new tool use."""
+        import time as _time
+
         if not self._active:
             return
         self._in_tool_phase = True
         self._last_was_tool = True
-        activity = _ToolActivity(tool_id=tool_id, name=name)
+        activity = _ToolActivity(
+            tool_id=tool_id, name=name, start_time=_time.monotonic()
+        )
         self._activities.append(activity)
 
     def on_tool_use_delta(self, tool_id: str, json_delta: str) -> None:
@@ -315,11 +366,10 @@ def update_progress(
             return
 
         if phase == "scratchpad_start":
-            # Print the scratchpad activity line NOW (before execution)
+            # Print the scratchpad description line NOW (no estimate — just
+            # the description, since LLM estimates are unreliable).
             for act in reversed(self._activities):
                 if act.name == "scratchpad" and not act.printed:
-                    if eta:
-                        act.eta_str = f"~{int(eta)}s"
                     self._stop_spinner()
                     self._print_activity_line(act)
                     act.printed = True
@@ -330,17 +380,16 @@ def update_progress(
             return
 
         if phase == "scratchpad_done":
-            # Mark the scratchpad line as complete with actual elapsed time
+            # Stash work elapsed — the ✔ line is deferred until
+            # reasoning_done arrives so we can print one combined line.
             for act in reversed(self._activities):
                 if act.name == "scratchpad" and act.printed and not act.done:
-                    elapsed = eta if eta else 0  # eta_seconds carries elapsed time
                     act.done = True
-                    self._stop_spinner()
-                    self._print_done_line(act, elapsed)
+                    act.work_elapsed = eta if eta else 0
                     self._line1_fun = random.choice(THINKING_MESSAGES)  # noqa: S311
                     self._line2_status = random.choice(WORKING_FOOTER_MESSAGES)  # noqa: S311
                     self._line3_peek = ""
-                    self._start_spinner()
+                    self._update_spinner()
                     break
             return
 
@@ -358,6 +407,48 @@ def update_progress(
             self._stop_spinner()
             return
 
+        if phase == "tool_start":
+            # Non-scratchpad tool started execution — spinner shows the
+            # witty phrase; the activity line was already printed at
+            # on_tool_use_end with the description.
+            self._line2_status = message
+            self._update_spinner()
+            return
+
+        if phase == "tool_done":
+            # Stash work elapsed — combined line printed on reasoning_done.
+            elapsed = eta if eta else 0
+            for act in reversed(self._activities):
+                if act.name == message and act.printed and not act.done:
+                    act.done = True
+                    act.work_elapsed = elapsed
+                    break
+            return
+
+        if phase == "reasoning_start":
+            # LLM is thinking between tool rounds. Spinner shows a
+            # fresh witty message. The elapsed time will be printed
+            # when reasoning_done arrives.
+            self._line1_fun = random.choice(THINKING_MESSAGES)  # noqa: S311
+            self._line2_status = random.choice(WORKING_FOOTER_MESSAGES)  # noqa: S311
+            self._line3_peek = ""
+            self._update_spinner()
+            return
+
+        if phase == "reasoning_done":
+            reasoning_elapsed = eta if eta else 0
+            # Find the last done-but-not-yet-printed activity and print
+            # the combined ✔ line: worked + reasoned on one line.
+            self._stop_spinner()
+            for act in reversed(self._activities):
+                if act.done and not act.done_line_printed:
+                    act.reasoning_elapsed = reasoning_elapsed
+                    act.done_line_printed = True
+                    self._print_done_line(act, act.work_elapsed, reasoning_elapsed)
+                    break
+            self._start_spinner()
+            return
+
         label = PHASE_LABELS.get(phase, phase)
         eta_str = f"  ~{int(eta)}s" if eta else ""
         self._line2_status = f"{label}  {message}{eta_str}"
@@ -368,6 +459,14 @@ def finish(self) -> None:
         """Stop spinner and print the final answer."""
         self._stop_spinner()
 
+        # Flush any activity whose ✔ line was deferred but never got a
+        # reasoning_done (happens for the last tool in a turn — the LLM
+        # goes straight to text, so reasoning_done never fires).
+        for act in self._activities:
+            if act.done and not act.done_line_printed:
+                act.done_line_printed = True
+                self._print_done_line(act, act.work_elapsed)
+
         # Print initial text as muted "inner speech" (if not already printed)
         if self._initial_text and not self._initial_printed:
             if self._activities:
@@ -424,24 +523,50 @@ def _extract_peek(self, text: str) -> str:
         return last
 
     def _print_activity_line(self, act: _ToolActivity) -> None:
-        """Print a single activity line permanently (before execution)."""
+        """Print a single activity line permanently (before execution).
+
+        For scratchpad: just the description text.
+        For other tools: the witty phrase from _tool_display_text.
+        No estimate is shown — only the actual elapsed time is printed
+        later by _print_done_line.
+        """
         line = Text()
-        label = act.description or _TOOL_LABELS.get(act.name, act.name)
+        label = act.description or act.name
         prefix = "\u23bf " if act is self._activities[0] else "  "
         line.append(prefix)
         line.append(label, style="bold")
-        if act.eta_str:
-            line.append(f" {act.eta_str}", style="anton.muted")
         self._console.print(line)
 
-    def _print_done_line(self, act: _ToolActivity, elapsed: float) -> None:
-        """Print a completion marker for a finished activity."""
+    def _print_done_line(
+        self,
+        act: _ToolActivity,
+        work_elapsed: float,
+        reasoning_elapsed: float = 0.0,
+    ) -> None:
+        """Print a single combined completion line for a finished activity.
+
+        Format: ``  ✔ (Worked: 1.9s, Reasoned: 7.1s)``
+        If reasoning_elapsed is 0 (e.g. last tool in the turn with no
+        follow-up reasoning), only the work time is shown.
+        """
         line = Text()
         line.append("  \u2714 ", style="green")
-        elapsed_str = f"{elapsed:.1f}s" if elapsed >= 1 else f"{int(elapsed * 1000)}ms"
-        line.append(elapsed_str, style="anton.muted")
+        work_str = self._fmt_elapsed(work_elapsed)
+
+        if reasoning_elapsed > 0:
+            reason_str = self._fmt_elapsed(reasoning_elapsed)
+            line.append(f"(Worked: {work_str}, Reasoned: {reason_str})", style="anton.muted")
+        else:
+            line.append(work_str, style="anton.muted")
+
         self._console.print(line)
 
+    @staticmethod
+    def _fmt_elapsed(seconds: float) -> str:
+        if seconds >= 1:
+            return f"{seconds:.1f}s"
+        return f"{int(seconds * 1000)}ms"
+
 
 class EscapeWatcher:
     """Detect Escape keypress during streaming via cbreak terminal mode."""
diff --git a/anton/cli.py b/anton/cli.py
index 7a26df6a..032918b2 100644
--- a/anton/cli.py
+++ b/anton/cli.py
@@ -21,11 +21,12 @@
 from anton import __version__
 
 from anton.utils.prompt import prompt_or_cancel
-from anton.llm.openai import build_chat_completion_kwargs
+from anton.core.llm.openai import build_chat_completion_kwargs
 
 from anton.chat import ChatSession
-from anton.llm.client import LLMClient
-from anton.scratchpad import ScratchpadManager
+from anton.core.session import ChatSessionConfig
+from anton.core.llm.client import LLMClient
+from anton.core.backends.manager import ScratchpadManager
 
 from anton.commands.datasource import (
     handle_remove_data_source,
@@ -301,7 +302,11 @@ def main(
 
     from anton.analytics import send_event
 
-    send_event(settings, "anton_started")
+    send_event(
+        settings,
+        "anton_started",
+        has_mdb_key="1" if settings.minds_api_key else "0",
+    )
 
     if ctx.invoked_subcommand is None:
         from anton.chat import run_chat
@@ -569,7 +574,7 @@ def _on_esc(event):
     def _toolbar():
         return HTML("<style fg='#ff69b4'>\u23f5\u23f5 Esc to go back</style>")
 
-    suffix = f" ({default}): " if default else ": "
+    suffix = f" ({default}):" if default else ":"
     session: PromptSession[str] = PromptSession(
         mouse_support=False,
         bottom_toolbar=_toolbar,
@@ -585,6 +590,7 @@ def _toolbar():
     except RuntimeError:
         in_async = False
 
+    suffix = suffix + '\u2009'
     if in_async:
         # We're inside an async context (e.g. /setup from chat loop)
         # Run prompt_toolkit in a thread to avoid nested event loop conflict
@@ -1170,7 +1176,7 @@ def connect_data_source(
         )
         or "",
     )
-    session = ChatSession(llm_client)
+    session = ChatSession(ChatSessionConfig(llm_client=llm_client))
 
     async def _run() -> None:
         await handle_connect_datasource(
@@ -1214,7 +1220,7 @@ def edit_data_source(
         )
         or "",
     )
-    session = ChatSession(llm_client)
+    session = ChatSession(ChatSessionConfig(llm_client=llm_client))
 
     async def _run() -> None:
         await handle_connect_datasource(
diff --git a/anton/commands/datasource.py b/anton/commands/datasource.py
deleted file mode 100644
index 9652367b..00000000
--- a/anton/commands/datasource.py
+++ /dev/null
@@ -1,1191 +0,0 @@
-"""Slash-command handlers for datasource commands."""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-import uuid
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from rich.console import Console
-from rich.markdown import Markdown
-from rich.padding import Padding
-
-from anton.data_vault import DataVault
-from anton.datasource_registry import DatasourceEngine, DatasourceField, DatasourceRegistry
-from anton.utils.datasources import (
-    register_secret_vars,
-    remove_engine_block,
-    restore_namespaced_env,
-    parse_connection_slug,
-)
-from anton.utils.prompt import prompt_or_cancel
-from anton.scratchpad import ScratchpadManager
-
-if TYPE_CHECKING:
-    from anton.chat import ChatSession
-
-_PROMPT_RECONNECT_CANCEL = "(reconnect/cancel)"
-
-
-def handle_list_data_sources(console: Console) -> None:
-    """Print all saved Local Vault connections in a table with status."""
-    from rich.table import Table
-
-    vault = DataVault()
-    registry = DatasourceRegistry()
-    conns = vault.list_connections()
-    console.print()
-    if not conns:
-        console.print("[anton.muted]No data sources connected yet.[/]")
-        console.print("[anton.muted]Use /connect to add one.[/]")
-        console.print()
-        return
-
-    table = Table(title="Local Vault — Saved Connections", show_lines=False)
-    table.add_column("Name", style="bold")
-    table.add_column("Source")
-    table.add_column("Status")
-
-    for c in conns:
-        slug = f"{c['engine']}-{c['name']}"
-        engine_def = registry.get(c["engine"])
-        source = engine_def.display_name if engine_def else c["engine"]
-        fields = vault.load(c["engine"], c["name"]) or {}
-
-        if not fields:
-            status = "[yellow]incomplete[/]"
-        elif engine_def and engine_def.auth_method != "choice":
-            required = [f.name for f in engine_def.fields if f.required]
-            missing = [name for name in required if name not in fields]
-            status = "[yellow]incomplete[/]" if missing else "[green]saved[/]"
-        else:
-            status = "[green]saved[/]"
-
-        table.add_row(slug, source, status)
-
-    console.print(table)
-    console.print()
-
-
-async def handle_remove_data_source(console: Console, slug: str) -> None:
-    """Delete a connection from the Local Vault by slug (engine-name)."""
-    vault = DataVault()
-    registry = DatasourceRegistry()
-
-    if not slug:
-        connections = vault.list_connections()
-        if not connections:
-            console.print("[anton.muted]No saved connections to remove.[/]")
-            console.print()
-            return
-        console.print()
-        console.print("[anton.cyan](anton)[/] Which connection do you want to remove?\n")
-        for i, c in enumerate(connections, 1):
-            conn_slug = f"{c['engine']}-{c['name']}"
-            engine_def = registry.get(c["engine"])
-            label = engine_def.display_name if engine_def else c["engine"]
-            console.print(f"          [bold]{i:>2}.[/bold] {conn_slug} [dim]({label})[/]")
-        console.print()
-        choices = [str(i) for i in range(1, len(connections) + 1)]
-        pick = await prompt_or_cancel("(anton) Enter a number", choices=choices)
-        if pick is None:
-            console.print("[anton.muted]Cancelled.[/]")
-            console.print()
-            return
-        picked = connections[int(pick) - 1]
-        slug = f"{picked['engine']}-{picked['name']}"
-
-    parsed = parse_connection_slug(slug, [e.engine for e in registry.all_engines()], vault=vault)
-    if parsed is None:
-        console.print(
-            f"[anton.warning]Invalid name '{slug}'. Use engine-name format.[/]"
-        )
-        console.print()
-        return
-    engine, name = parsed
-    if vault.load(engine, name) is None:
-        console.print(f"[anton.warning]No connection '{slug}' found.[/]")
-        console.print()
-        return
-
-    confirm = await prompt_or_cancel(
-        f"(anton) Remove '{slug}' from Local Vault?",
-        choices=["y", "n"], default="n",
-    )
-    if confirm is not None and confirm.strip().lower() == "y":
-        vault.delete(engine, name)
-        restore_namespaced_env(vault)
-        engine_def = registry.get(engine)
-        if engine_def is not None and engine_def.custom:
-            remaining = [
-                c for c in vault.list_connections() if c["engine"] == engine
-            ]
-            if not remaining:
-                user_path = DatasourceRegistry._USER_PATH
-                if user_path.is_file():
-                    updated = remove_engine_block(
-                        user_path.read_text(encoding="utf-8"), engine
-                    )
-                    user_path.write_text(updated, encoding="utf-8")
-                    registry.reload()
-        console.print(f"[anton.success]Removed {slug}.[/]")
-    else:
-        console.print("[anton.muted]Cancelled.[/]")
-    console.print()
-
-
-async def show_credential_help(
-    console: Console,
-    session: "ChatSession",
-    service_name: str,
-    current_field,
-    all_fields: list,
-) -> None:
-    """Use the LLM to explain how to obtain credentials."""
-    field_descriptions = ", ".join(
-        f"{f.name} ({f.description})" for f in all_fields
-    )
-    storage_note = (
-        "The credentials will be stored securely in Anton's Local Vault — "
-        "do NOT suggest storage tips, password managers, or safe-keeping advice."
-    )
-    if current_field is not None:
-        prompt = (
-            f"I'm connecting to {service_name} and need to provide: {field_descriptions}\n\n"
-            f"I need help with the '{current_field.name}' field"
-            f" ({current_field.description}).\n\n"
-            "Give me a brief step-by-step guide on where and how to get this credential. "
-            f"Be concise — numbered steps, no fluff. {storage_note}"
-        )
-        heading = f"[anton.cyan](anton)[/] How to get [bold]{current_field.name}[/]:"
-    else:
-        prompt = (
-            f"I'm connecting to {service_name} and need these credentials: {field_descriptions}\n\n"
-            "Give me a brief step-by-step guide on where and how to obtain each of these. "
-            f"Be concise — numbered steps, no fluff. {storage_note}"
-        )
-        heading = f"[anton.cyan](anton)[/] How to get credentials for [bold]{service_name}[/]:"
-
-    console.print()
-    console.print("[anton.muted]        Looking up instructions…[/]")
-
-    try:
-        resp = await session._llm.plan(
-            system="You are a helpful assistant that guides users through obtaining credentials for services.",
-            messages=[
-                {
-                    "role": "user",
-                    "content": prompt,
-                }
-            ],
-            max_tokens=512,
-        )
-        help_text = (resp.content or "").strip()
-    except Exception:
-        help_text = "Sorry, couldn't fetch help right now. Try checking the service's documentation."
-
-    console.print()
-    console.print(heading)
-    console.print()
-    console.print(Padding(Markdown(help_text), (0, 0, 0, 8)))
-    console.print()
-
-
-async def run_connection_test(
-    console: "Console",
-    scratchpads: "ScratchpadManager",
-    vault: "DataVault",
-    engine_def: "DatasourceEngine",
-    credentials: dict[str, str],
-    retry_fields: "list[DatasourceField]",
-) -> bool:
-    """Inject flat DS_* vars, run engine_def.test_snippet, restore env.
-
-    Returns True on success, False if the user declines retry after failure.
-    Mutates credentials in-place when the user re-enters secrets on retry.
-    """
-    while True:
-        console.print()
-        console.print("[anton.cyan](anton)[/] Got it. Testing connection…")
-
-        vault.clear_ds_env()
-        for key, value in credentials.items():
-            os.environ[f"DS_{key.upper()}"] = value
-        register_secret_vars(engine_def)  # flat mode, for scrubbing during test
-
-        try:
-            pad = await scratchpads.get_or_create("__datasource_test__")
-            await pad.reset()
-            if engine_def.pip:
-                if isinstance(engine_def.pip, list):
-                    pip_pkgs = engine_def.pip
-                else:
-                    # Split space-separated package strings into individual packages
-                    pip_pkgs = engine_def.pip.split()
-                install_result = await pad.install_packages(pip_pkgs)
-                if "failed" in (install_result or "").lower():
-                    console.print()
-                    console.print(f"[anton.warning](anton)[/] Package install issue: {install_result[:200]}")
-
-            # Run the test, retry up to 2 times on ModuleNotFoundError
-            cell = None
-            for attempt in range(3):
-                cell = await pad.execute(engine_def.test_snippet)
-                if cell.error and "ModuleNotFoundError" in cell.error:
-                    # Extract the missing module and try to install it
-                    match = re.search(r"No module named '([^']+)'", cell.error)
-                    if match:
-                        missing = match.group(1).split(".")[0]
-                        await pad.install_packages([missing])
-                        continue
-                break
-        finally:
-            restore_namespaced_env(vault)
-
-        if cell.error or (cell.stdout.strip() != "ok" and cell.stderr.strip()):
-            error_text = cell.error or cell.stderr.strip() or cell.stdout.strip()
-            last_line = next(
-                (ln for ln in reversed(error_text.splitlines()) if ln.strip()), error_text
-            )
-            console.print()
-            console.print("[anton.warning](anton)[/] ✗ Connection failed.")
-            console.print()
-            console.print(f"        Error: {last_line}")
-            console.print()
-            retry = await prompt_or_cancel(
-                "(anton) Would you like to re-enter your credentials?",
-                choices=["y", "n"], default="n",
-            )
-            if retry is None or retry.strip().lower() != "y":
-                return False
-            console.print()
-            for f in retry_fields:
-                if not f.secret:
-                    continue
-                value = await prompt_or_cancel(f"(anton) {f.name}", password=True)
-                if value is None:
-                    return False
-                if value:
-                    credentials[f.name] = value
-            continue
-
-        console.print("[anton.success]        ✓ Connected successfully![/]")
-        return True
-
-
-async def handle_add_custom_datasource(
-    console: Console,
-    name: str,
-    registry,
-    session: "ChatSession",
-    *,
-    known_service: bool = False,
-):
-    """Ask for the tool name, use the LLM to identify required fields, then collect credentials."""
-
-    console.print()
-    if name:
-        tool_name = name
-    else:
-        tool_name = await prompt_or_cancel(
-            "(anton) What is the name of the tool or service?",
-        )
-        if not tool_name or not tool_name.strip():
-            return None
-        tool_name = tool_name.strip()
-
-    if known_service:
-        # LLM already recognised this service — skip the auth question
-        user_answer = ""
-        console.print("[anton.muted]        Working out the connection details…[/]")
-    else:
-        user_answer = await prompt_or_cancel(
-            f"(anton) How do you authenticate with {tool_name}? "
-            "Describe what credentials you have (don't paste actual values)",
-        )
-        if not user_answer or not user_answer.strip():
-            return None
-        console.print()
-        console.print("[anton.muted]    Got it — working out the connection details…[/]")
-
-    llm_prompt = f"The user wants to connect to {repr(tool_name)}."
-    if user_answer:
-        llm_prompt += f" They said: {user_answer}"
-    else:
-        llm_prompt += " Determine the standard authentication fields for this service."
-    llm_prompt += (
-        "\n\nReturn ONLY valid JSON (no markdown fences, no commentary):\n"
-        '{"display_name":"Human-readable name","pip":"pip-package or empty string",'
-        '"test_snippet":"python code that tests the connection using os.environ vars DS_FIELDNAME (uppercase field name with DS_ prefix) and prints ok on success, or empty string if untestable",'
-        '"fields":[{"name":"snake_case_name","value":"value if given inline else empty",'
-        '"secret":true or false,"required":true or false,"description":"what it is"}]}'
-    )
-
-    try:
-        response = await session._llm.plan(
-            system="You are a data source connection expert.",
-            messages=[
-                {
-                    "role": "user",
-                    "content": llm_prompt,
-                }
-            ],
-            max_tokens=1024,
-        )
-        text = response.content.strip()
-        # Keep
-        text = re.sub(r"^```[^\n]*\n|```\s*$", "", text, flags=re.MULTILINE).strip()
-        data = json.loads(text)
-    except Exception:
-        console.print(
-            "[anton.warning]        Couldn't identify connection details. Try again.[/]"
-        )
-        console.print()
-        return None
-
-    test_snippet = str(data.get("test_snippet", "")).strip()
-    raw_fields = data.get("fields") or []
-    fields: list[DatasourceField] = []
-    for f in raw_fields:
-        if not isinstance(f, dict) or not f.get("name"):
-            continue
-        fields.append(
-            DatasourceField(
-                name=f["name"],
-                required=bool(f.get("required", True)),
-                secret=bool(f.get("secret", False)),
-                description=str(f.get("description", "")),
-            )
-        )
-
-    if not fields:
-        console.print("[anton.warning]    Couldn't identify any connection fields.[/]")
-        console.print()
-        return None
-
-    display_name = str(data.get("display_name", name))
-    pip_pkg = str(data.get("pip", ""))
-
-    # Show summary
-    console.print()
-    console.print("      [bold]── What I'll save ──────────────────────────[/]")
-    credentials: dict[str, str] = {}
-    for f, raw in zip(fields, raw_fields):
-        inline_value = str(raw.get("value", "")).strip()
-        if f.secret and inline_value:
-            console.print(
-                f"        • [bold]{f.name:<14}[/] (secret — provided, stored securely)"
-            )
-            credentials[f.name] = inline_value
-        elif f.secret:
-            console.print(
-                f"        • [bold]{f.name:<14}[/] (secret — I'll ask for this)"
-            )
-        else:
-            val_display = inline_value or "[anton.muted]<to be collected>[/]"
-            console.print(f"        • [bold]{f.name:<14}[/] {val_display}")
-            if inline_value:
-                credentials[f.name] = inline_value
-    console.print()
-
-    # Offer help before collecting credentials
-    help_answer = await prompt_or_cancel(
-        "(anton) Do you need instructions on how to obtain these credentials?",
-        choices=["y", "n"], default="n",
-    )
-    if help_answer is None:
-        return None
-    if help_answer.strip().lower() == "y":
-        await show_credential_help(
-            console, session, display_name, None, fields,
-        )
-
-    # Prompt for any secret fields not provided inline
-    for f, raw in zip(fields, raw_fields):
-        if not f.secret:
-            continue
-        if str(raw.get("value", "")).strip():
-            continue
-        value = await prompt_or_cancel(f"(anton) {f.name}", password=True)
-        if value is None:
-            return None
-        if value:
-            credentials[f.name] = value
-
-    # Prompt for any required non-secret fields not provided inline
-    for f, raw in zip(fields, raw_fields):
-        if f.secret:
-            continue
-        if not f.required:
-            continue
-        if f.name in credentials:
-            continue
-        value = await prompt_or_cancel(f"(anton) {f.name}")
-        if value is None:
-            return None
-        if value:
-            credentials[f.name] = value
-
-    # Offer to collect optional non-secret fields
-    for f, raw in zip(fields, raw_fields):
-        if f.secret or f.required or f.name in credentials:
-            continue
-        value = await prompt_or_cancel(f"(anton) {f.name} (optional — press Enter to skip)")
-        if value is None:
-            return None
-        if value:
-            credentials[f.name] = value
-
-    if not credentials:
-        console.print("[anton.warning]        No credentials collected. Aborting.[/]")
-        console.print()
-        return None
-
-    # Build engine slug and write definition to ~/.anton/datasources.md
-    slug = re.sub(r"[^\w]", "_", display_name.lower()).strip("_")
-    field_lines = "\n".join(
-        f"  - {{ name: {f.name}, required: {str(f.required).lower()}, "
-        f'secret: {str(f.secret).lower()}, description: "{f.description}" }}'
-        for f in fields
-    )
-    test_snippet_yaml = ""
-    if test_snippet:
-        indented = "\n".join(f"  {line}" for line in test_snippet.splitlines())
-        test_snippet_yaml = f"test_snippet: |\n{indented}\n"
-
-    yaml_block = (
-        f"\n---\n\n## {display_name}\n"
-        "```yaml\n"
-        f"engine: {slug}\n"
-        f"display_name: {display_name}\n"
-        + (f"pip: {pip_pkg}\n" if pip_pkg else "")
-        + f"fields:\n{field_lines}\n"
-        + test_snippet_yaml
-        + "```\n"
-    )
-    user_ds_path = Path("~/.anton/datasources.md").expanduser()
-    tmp_path = user_ds_path.with_suffix(".tmp")
-
-    # Write to temp, validate it parses, then rename atomically
-    existing = (
-        user_ds_path.read_text(encoding="utf-8") if user_ds_path.is_file() else ""
-    )
-
-    existing = remove_engine_block(existing, slug)
-
-    tmp_path.write_text(existing + yaml_block, encoding="utf-8")
-
-    parsed = registry.validate_file(tmp_path)
-    if slug in parsed:
-        import shutil
-
-        shutil.move(str(tmp_path), str(user_ds_path))
-    else:
-        tmp_path.unlink(missing_ok=True)
-        console.print(
-            "[anton.warning]Could not validate engine definition — "
-            "credentials saved but engine not written to datasources.md.[/]"
-        )
-
-    registry.reload()
-    engine_def = registry.get(slug)
-    if engine_def is None:
-        # Fallback: construct inline so the flow can continue even if parse failed
-        engine_def = DatasourceEngine(
-            engine=slug,
-            display_name=display_name,
-            pip=pip_pkg,
-            fields=fields,
-            test_snippet=test_snippet,
-        )
-
-    # All required fields must be present before the caller saves credentials
-    missing_required = [f.name for f in fields if f.required and f.name not in credentials]
-    if missing_required:
-        console.print(
-            "[anton.warning]    Cannot save — missing required fields: "
-            f"{', '.join(missing_required)}. Aborting.[/]"
-        )
-        console.print()
-        return None
-
-    return engine_def, credentials
-
-
-async def handle_connect_datasource(
-    console: Console,
-    scratchpads: ScratchpadManager,
-    session: "ChatSession",
-    datasource_name: str | None = None,
-    prefill: str | None = None,
-) -> "ChatSession":
-    """
-    Connect a data source by entering credentials, either for a new name or re-entering for an existing one.
-    """
-
-    vault = DataVault()
-    registry = DatasourceRegistry()
-
-    if datasource_name is not None:
-        parsed = parse_connection_slug(
-            datasource_name, [e.engine for e in registry.all_engines()], vault=vault
-        )
-        if parsed is None:
-            console.print(
-                f"[anton.warning]Invalid slug '{datasource_name}'. "
-                "Expected format: engine-name.[/]"
-            )
-            console.print()
-            return session
-        edit_engine, edit_name = parsed
-        existing = vault.load(edit_engine, edit_name)
-        if existing is None:
-            console.print(
-                f"[anton.warning]No connection '{datasource_name}' found in Local Vault.[/]"
-            )
-            console.print()
-            return session
-        engine_def = registry.get(edit_engine)
-        if engine_def is None:
-            console.print(
-                f"[anton.warning]Unknown engine '{edit_engine}'. "
-                "Cannot update credentials.[/]"
-            )
-            console.print()
-            return session
-
-        console.print()
-        console.print(
-            f"[anton.cyan](anton)[/] Editing [bold]\"{datasource_name}\"[/bold]"
-            f" ({engine_def.display_name})."
-        )
-        console.print("[anton.muted]        Press Enter to keep the current value.[/]")
-        console.print()
-
-        # Detect which fields to present (handle auth_method=choice)
-        active_fields = engine_def.fields
-        if engine_def.auth_method == "choice" and engine_def.auth_methods:
-            for am in engine_def.auth_methods:
-                am_field_names = {af.name for af in am.fields}
-                if any(k in am_field_names for k in existing):
-                    active_fields = am.fields
-                    break
-            if not active_fields:
-                active_fields = engine_def.auth_methods[0].fields
-
-        # Start from existing values; let user update field-by-field
-        credentials: dict[str, str] = dict(existing)
-        for f in active_fields:
-            current = existing.get(f.name, "")
-            field_label = f"(anton) {f.name}"
-            if not f.required:
-                field_label += " (optional)"
-
-            if f.secret:
-                masked = "••••••••" if current else ""
-                label = f"{field_label} [{masked}]" if masked else field_label
-                value = await prompt_or_cancel(label, password=True)
-                if value is None:
-                    return session
-                if value:
-                    credentials[f.name] = value
-                # else: keep existing (already in credentials)
-            elif current:
-                value = await prompt_or_cancel(
-                    f"{field_label}",
-                    default=current,
-                )
-                if value is None:
-                    return session
-                credentials[f.name] = value if value else current
-            elif f.default:
-                value = await prompt_or_cancel(
-                    f"{field_label}",
-                    default=f.default,
-                )
-                if value is None:
-                    return session
-                if value:
-                    credentials[f.name] = value
-            else:
-                value = await prompt_or_cancel(field_label)
-                if value is None:
-                    return session
-                if value:
-                    credentials[f.name] = value
-
-        if engine_def.test_snippet:
-            if not await run_connection_test(
-                console, scratchpads, vault, engine_def, credentials, active_fields
-            ):
-                return session
-
-        vault.save(edit_engine, edit_name, credentials)
-        restore_namespaced_env(vault)
-        register_secret_vars(engine_def, engine=edit_engine, name=edit_name)
-        console.print()
-        console.print(
-            f'        Credentials updated for [bold]"{datasource_name}"[/bold].'
-        )
-        console.print()
-        console.print(
-            "[anton.muted]        You can now ask me questions about your data.[/]"
-        )
-        console.print()
-        session._history.append(
-            {
-                "role": "assistant",
-                "content": (
-                    f"I've updated the credentials for the {engine_def.display_name} connection "
-                    f'"{datasource_name}" in the Local Vault.'
-                ),
-            }
-        )
-        return session
-
-    console.print()
-    all_engines = registry.all_engines()
-    popular_engines = [e for e in all_engines if e.popular and not e.custom]
-    other_engines = [e for e in all_engines if not e.popular and not e.custom]
-    custom_engines = [e for e in all_engines if e.custom]
-    display_engines = popular_engines + other_engines + custom_engines
-
-    saved_connections = vault.list_connections()
-    # Build deduplicated list of saved connection display entries
-    saved_entries: list[tuple[str, str]] = []  # (slug, display_name)
-    for c in saved_connections:
-        slug = f"{c['engine']}-{c['name']}"
-        engine = registry.get(c["engine"])
-        label = engine.display_name if engine else c["engine"]
-        saved_entries.append((slug, label))
-
-    def print_sections() -> None:
-        console.print(
-            "[anton.cyan](anton)[/] Choose a data source:\n"
-        )
-        console.print("       [bold]  Primary")
-        console.print(
-            "         [bold]  0.[/bold] Custom datasource"
-            " (connect anything via API, SQL, or MCP)\n"
-        )
-        if popular_engines:
-            console.print("       [bold]  Most popular")
-            for i, e in enumerate(popular_engines, 1):
-                console.print(f"          [bold]{i:>2}.[/bold] {e.display_name}")
-            console.print()
-        if saved_entries:
-            start = len(popular_engines) + 1
-            console.print("       [bold]  Recent connections")
-            for i, (slug, label) in enumerate(saved_entries, start):
-                console.print(f"          [bold]{i:>2}.[/bold] {label}")
-            console.print()
-
-    def print_all() -> None:
-        console.print(
-            "[anton.cyan](anton)[/] All data sources (★ = popular):\n"
-        )
-        console.print("       [bold]  Primary")
-        console.print(
-            "         [bold]  0.[/bold] Custom datasource"
-            " (connect anything via API, SQL, or MCP)\n"
-        )
-        for i, e in enumerate(display_engines, 1):
-            star = " ★" if e.popular else ""
-            console.print(f"          [bold]{i:>2}.[/bold] {e.display_name}{star}")
-        console.print()
-
-    if prefill:
-        answer = prefill
-    else:
-        print_sections()
-        console.print(
-            "       [anton.muted]Don't see yours? Type a datasource name (e.g., GitHub, Gmail, Jira, ...)\n"
-            "       It can be virtually any datasource — we'll figure out the details together.[/]"
-        )
-        console.print()
-        answer = await prompt_or_cancel(
-            "(anton) Enter a number or type a datasource name",
-        )
-        if answer is None:
-            return session
-        if answer.strip().lower() == "all":
-            console.print()
-            print_all()
-            answer = await prompt_or_cancel(
-                "(anton) Enter a number or type a name",
-            )
-            if answer is None:
-                return session
-
-    stripped_answer = answer.strip()
-    known_slugs = {
-        f"{c['engine']}-{c['name']}": c for c in vault.list_connections()
-    }
-    if stripped_answer in known_slugs:
-        conn = known_slugs[stripped_answer]
-        restore_namespaced_env(vault)
-        session._active_datasource = stripped_answer
-        recon_engine_def = registry.get(conn["engine"])
-        if recon_engine_def:
-            register_secret_vars(recon_engine_def, engine=conn["engine"], name=conn["name"])
-            engine_label = recon_engine_def.display_name
-        else:
-            engine_label = conn["engine"]
-        console.print()
-        console.print(
-            f'[anton.success]        ✓ Reconnected to [bold]"{stripped_answer}"[/bold].[/]'
-        )
-        console.print()
-        session._history.append(
-            {
-                "role": "assistant",
-                "content": (
-                    f'I\'ve reconnected to the {engine_label} connection "{stripped_answer}" '
-                    f"in the Local Vault. I can now query this data source when needed."
-                ),
-            }
-        )
-        return session
-
-    engine_def: DatasourceEngine | None = None
-    custom_source = False
-    llm_recognised = False
-    # Saved connections are numbered after popular engines
-    saved_start = len(popular_engines) + 1
-    max_num = len(popular_engines) + len(saved_entries)
-
-    if stripped_answer.isdigit() or (stripped_answer.lstrip("-").isdigit()):
-        pick_num = int(stripped_answer)
-        if pick_num == 0:
-            custom_source = True
-        elif 1 <= pick_num <= len(popular_engines):
-            engine_def = popular_engines[pick_num - 1]
-        elif saved_entries and saved_start <= pick_num <= max_num:
-            # User picked a recent connection type — start a new connection of that engine
-            picked_slug, picked_label = saved_entries[pick_num - saved_start]
-            picked_engine = picked_slug.split("-", 1)[0]
-            engine_def = registry.get(picked_engine)
-            if engine_def is None:
-                custom_source = True
-        else:
-            console.print(
-                f"[anton.warning](anton)[/] '{stripped_answer}' is out of range. "
-                f"Please enter 0\u2013{max_num}.[/]"
-            )
-            console.print()
-            return session
-
-    if engine_def is None and not custom_source:
-        engine_def = registry.find_by_name(stripped_answer)
-        # if exact match not found, try substring match against display and engine names
-        if engine_def is None:
-            needle = stripped_answer.lower()
-            candidates = [
-                e
-                for e in all_engines
-                if needle in e.display_name.lower() or needle in e.engine.lower()
-            ]
-            if len(candidates) == 1:
-                engine_def = candidates[0]
-            elif len(candidates) > 1:
-                console.print()
-                console.print(
-                    f"[anton.warning](anton)[/] '{stripped_answer}' matches multiple engines — "
-                    "which one did you mean?"
-                )
-                console.print()
-                for i, e in enumerate(candidates, 1):
-                    console.print(f"        {i}. {e.display_name}")
-                console.print()
-                pick = await prompt_or_cancel("(anton) Enter a number")
-                if pick is None:
-                    return session
-                pick = (pick or "").strip()
-                try:
-                    engine_def = candidates[int(pick) - 1]
-                except (ValueError, IndexError):
-                    console.print("[anton.warning]Invalid choice. Aborting.[/]")
-                    console.print()
-                    return session
-        # Ask the LLM to identify the datasource
-        if engine_def is None:
-            engine_names = [e.display_name for e in all_engines]
-            try:
-                console.print()
-                console.print("[anton.muted]        Looking up datasource…[/]")
-                llm_resp = await session._llm.plan(
-                    system="You are a datasource identification assistant.",
-                    messages=[
-                        {
-                            "role": "user",
-                            "content": (
-                                f"The user typed: {stripped_answer!r}\n"
-                                f"Known datasources: {engine_names!r}\n\n"
-                                "If the user input clearly matches one of the known datasources, "
-                                "reply with EXACTLY: MATCH:<display_name>\n"
-                                "If it does NOT match any known datasource but you recognise it "
-                                "as a real service/tool, reply with EXACTLY: CUSTOM\n"
-                                "If you don't recognise it at all, reply with EXACTLY: UNKNOWN\n"
-                                "Reply with only one of those three forms, nothing else."
-                            ),
-                        }
-                    ],
-                    max_tokens=64,
-                )
-                llm_text = (llm_resp.content or "").strip()
-            except Exception:
-                llm_text = "UNKNOWN"
-
-            llm_recognised = llm_text == "CUSTOM" or llm_text.startswith("MATCH:")
-
-            if llm_text.startswith("MATCH:"):
-                matched_name = llm_text[len("MATCH:"):].strip()
-                matched_engine = next(
-                    (e for e in all_engines if e.display_name == matched_name), None
-                )
-                if matched_engine is not None:
-                    if matched_name.lower() != stripped_answer.lower():
-                        confirm = await prompt_or_cancel(
-                            f'(anton) Did you mean "{matched_name}"?',
-                            choices=["y", "n"], default="y",
-                        )
-                        if confirm is not None and confirm.strip().lower() == "y":
-                            engine_def = matched_engine
-                    else:
-                        engine_def = matched_engine
-
-            if engine_def is None:
-                custom_source = True
-
-    if custom_source:
-        result = await handle_add_custom_datasource(
-            console, stripped_answer if not stripped_answer.isdigit() else "", registry, session,
-            known_service=llm_recognised,
-        )
-        if result is None:
-            return session
-        engine_def, credentials = result
-        if engine_def.test_snippet:
-            if not await run_connection_test(
-                console, scratchpads, vault, engine_def, credentials, engine_def.fields
-            ):
-                return session
-        conn_name = uuid.uuid4().hex[:8]
-        vault.save(engine_def.engine, conn_name, credentials)
-        slug = f"{engine_def.engine}-{conn_name}"
-        restore_namespaced_env(vault)
-        session._active_datasource = slug
-        register_secret_vars(engine_def, engine=engine_def.engine, name=conn_name)
-        console.print(
-            f'        Credentials saved to Local Vault as [bold]"{slug}"[/bold].'
-        )
-        console.print()
-        console.print(
-            "[anton.muted]        You can now ask me questions about your data.[/]"
-        )
-        console.print()
-        session._history.append(
-            {
-                "role": "assistant",
-                "content": (
-                    f'I\'ve saved a {engine_def.display_name} connection named "{slug}" '
-                    f"to the Local Vault. I can now query this data source when needed."
-                ),
-            }
-        )
-        return session
-
-    assert engine_def is not None  # custom_source path always returns before this line
-    active_fields = engine_def.fields
-    if engine_def.auth_method == "choice" and engine_def.auth_methods:
-        console.print()
-        console.print(
-            f"[anton.cyan](anton)[/] How would you like to authenticate with "
-            f"[bold]{engine_def.display_name}[/]?"
-        )
-        console.print()
-        for i, am in enumerate(engine_def.auth_methods, 1):
-            console.print(f"        {i}. {am.display}")
-        console.print()
-        choice_str = await prompt_or_cancel("(anton) Enter a number")
-        if choice_str is None:
-            return session
-        choice_str = (choice_str or "").strip()
-        try:
-            choice_idx = int(choice_str) - 1
-            chosen_method = engine_def.auth_methods[choice_idx]
-        except (ValueError, IndexError):
-            console.print("[anton.warning]Invalid choice. Aborting.[/]")
-            console.print()
-            return session
-        active_fields = chosen_method.fields
-
-    required_fields = [f for f in active_fields if f.required]
-    optional_fields = [f for f in active_fields if not f.required]
-
-    console.print()
-    console.print(
-        f"[anton.cyan](anton)[/] To connect [bold]{engine_def.display_name}[/], "
-        "I'll need the following:"
-    )
-    console.print()
-
-    if required_fields:
-        console.print("        [bold]Required[/]      " + "─" * 39)
-        for f in required_fields:
-            console.print(
-                f"        • [bold]{f.name:<12}[/] [anton.muted]— {f.description}[/]"
-            )
-
-    if optional_fields:
-        console.print()
-        console.print("        [bold]Optional[/]      " + "─" * 39)
-        for f in optional_fields:
-            console.print(
-                f"        • [bold]{f.name:<12}[/] [anton.muted]— {f.description}[/]"
-            )
-
-    console.print()
-
-    help_answer = await prompt_or_cancel(
-        "(anton) Do you need instructions on how to obtain these credentials?",
-        choices=["y", "n"], default="n",
-    )
-    if help_answer is None:
-        return session
-    if help_answer.strip().lower() == "y":
-        await show_credential_help(
-            console, session, engine_def.display_name, None, active_fields,
-        )
-
-    while True:
-        mode_answer = await prompt_or_cancel(
-            "(anton) Do you have these available?",
-            choices_display="y/n/list params", default="y",
-        )
-        if mode_answer is None:
-            return session
-        mode_answer = mode_answer.strip().lower()
-
-        if mode_answer in ("y", "n"):
-            break
-
-        # Check if user gave valid comma-separated param names
-        requested = {n.strip().lower() for n in mode_answer.split(",")}
-        matched = [f for f in active_fields if f.name.lower() in requested]
-        if matched:
-            break
-
-        console.print(
-            "[anton.warning]        Please enter y, n, or a comma-separated list of parameter names "
-            f"({', '.join(f.name for f in active_fields)}).[/]"
-        )
-        console.print()
-
-    if mode_answer == "n":
-        console.print()
-        console.print(
-            "[anton.cyan](anton)[/] No problem. Which parameters do you have? "
-            "I'll save a partial connection now, and you can fill in the rest later "
-            "with [bold]/edit[/]."
-        )
-        console.print()
-        console.print("       Provide what you have (press enter to skip any field):")
-        console.print()
-        fields_to_collect = active_fields
-        partial = True
-    elif mode_answer == "y":
-        fields_to_collect = active_fields
-        partial = False
-    else:
-        fields_to_collect = matched
-        partial = False
-
-    console.print()
-    credentials: dict[str, str] = {}
-
-    for f in fields_to_collect:
-        if f.secret:
-            value = await prompt_or_cancel(f"(anton) {f.name}", password=True)
-        elif f.default:
-            value = await prompt_or_cancel(f"(anton) {f.name}", default=f.default)
-        else:
-            value = await prompt_or_cancel(f"(anton) {f.name}")
-        if value is None:
-            return session
-        if value:
-            credentials[f.name] = value
-
-    if partial:
-        auto_name = uuid.uuid4().hex[:8]
-        vault.save(engine_def.engine, auto_name, credentials)
-        slug = f"{engine_def.engine}-{auto_name}"
-        console.print()
-        console.print(
-            f"[anton.muted]Partial connection saved to Local Vault as "
-            f'[bold]"{slug}"[/bold]. '
-            f"Run [bold]/edit {slug}[/bold] to complete it when you're ready.[/]"
-        )
-        console.print()
-        return session
-
-    if engine_def.test_snippet:
-        if not await run_connection_test(
-            console, scratchpads, vault, engine_def, credentials, active_fields
-        ):
-            return session
-
-    conn_name = registry.derive_name(engine_def, credentials)
-    if not conn_name:
-        conn_name = uuid.uuid4().hex[:8]
-
-    slug = f"{engine_def.engine}-{conn_name}"
-
-    if vault.load(engine_def.engine, conn_name) is not None:
-        console.print()
-        console.print(
-            f'[anton.warning](anton)[/] A connection [bold]"{slug}"[/bold] already exists.'
-        )
-        console.print()
-        choice = await prompt_or_cancel(
-            f"(anton) {_PROMPT_RECONNECT_CANCEL}",
-        )
-        if choice is None or choice.strip().lower() != "reconnect":
-            console.print("[anton.muted]Cancelled.[/]")
-            console.print()
-            return session
-        restore_namespaced_env(vault)
-        register_secret_vars(engine_def, engine=engine_def.engine, name=conn_name)
-        console.print()
-        console.print(
-            f'[anton.success]        ✓ Reconnected to [bold]"{slug}"[/bold].[/]'
-        )
-        console.print()
-        session._history.append(
-            {
-                "role": "assistant",
-                "content": (
-                    f'I\'ve reconnected to the {engine_def.display_name} connection "{slug}" '
-                    f"in the Local Vault. I can now query this data source when needed."
-                ),
-            }
-        )
-        return session
-
-    vault.save(engine_def.engine, conn_name, credentials)
-    restore_namespaced_env(vault)
-    session._active_datasource = slug
-    register_secret_vars(engine_def, engine=engine_def.engine, name=conn_name)
-    console.print(f'        Credentials saved to Local Vault as [bold]"{slug}"[/bold].')
-
-    console.print()
-    console.print(
-        "[anton.muted]        You can now ask me questions about your data.[/]"
-    )
-    console.print()
-
-    # Inject a brief assistant message so the LLM is aware of the new connection
-    session._history.append(
-        {
-            "role": "assistant",
-            "content": (
-                f'I\'ve saved a {engine_def.display_name} connection named "{slug}" '
-                f"to the Local Vault. I can now query this data source when needed."
-            ),
-        }
-    )
-    return session
-
-
-async def handle_test_datasource(
-    console: Console,
-    scratchpads: ScratchpadManager,
-    slug: str,
-) -> None:
-    """Test an existing Local Vault connection by running its test_snippet."""
-    if not slug:
-        console.print(
-            "[anton.warning]Usage: /test <engine-name>[/]"
-        )
-        console.print()
-        return
-
-    vault = DataVault()
-    registry = DatasourceRegistry()
-    parsed = parse_connection_slug(slug, [e.engine for e in registry.all_engines()], vault=vault)
-    if parsed is None:
-        console.print(
-            f"[anton.warning]Invalid name '{slug}'. Use engine-name format.[/]"
-        )
-        console.print()
-        return
-    engine, name = parsed
-    fields = vault.load(engine, name)
-    if fields is None:
-        console.print(
-            f"[anton.warning]No connection '{slug}' found in Local Vault.[/]"
-        )
-        console.print()
-        return
-
-    engine_def = registry.get(engine)
-    if engine_def is None:
-        console.print(
-            f"[anton.warning]Unknown engine '{engine}'. Cannot test.[/]"
-        )
-        console.print()
-        return
-
-    if not engine_def.test_snippet:
-        console.print(
-            f"[anton.warning]No test snippet defined for '{engine}'. Cannot test.[/]"
-        )
-        console.print()
-        return
-
-    console.print()
-    console.print(
-        f"[anton.cyan](anton)[/] Testing connection [bold]{slug}[/bold]…"
-    )
-
-    vault.clear_ds_env()
-    vault.inject_env(engine, name, flat=True)
-    register_secret_vars(engine_def)  # flat names for scrubbing during test
-
-    cell = None
-    try:
-        pad = await scratchpads.get_or_create("__datasource_test__")
-        await pad.reset()
-        if engine_def.pip:
-            await pad.install_packages([engine_def.pip])
-        cell = await pad.execute(engine_def.test_snippet)
-    finally:
-        restore_namespaced_env(vault)
-
-    if cell is None or cell.error or (
-        cell.stdout.strip() != "ok" and cell.stderr.strip()
-    ):
-        error_text = ""
-        if cell is not None:
-            error_text = cell.error or cell.stderr.strip() or cell.stdout.strip()
-        first_line = (
-            next((ln for ln in error_text.splitlines() if ln.strip()), error_text)
-            if error_text
-            else "unknown error"
-        )
-        console.print()
-        console.print(
-            f"[anton.warning](anton)[/] ✗ Connection test failed for"
-            f" [bold]{slug}[/bold]."
-        )
-        console.print()
-        console.print(f"        Error: {first_line}")
-    else:
-        console.print(
-            f"[anton.success]        ✓ Connection test passed for"
-            f" [bold]{slug}[/bold]![/]"
-        )
-    console.print()
diff --git a/anton/commands/datasource/__init__.py b/anton/commands/datasource/__init__.py
new file mode 100644
index 00000000..929c840d
--- /dev/null
+++ b/anton/commands/datasource/__init__.py
@@ -0,0 +1,23 @@
+"""Datasource slash-command handlers."""
+
+from anton.commands.datasource.helpers import show_credential_help
+from anton.commands.datasource.connect import _PROMPT_RECONNECT_CANCEL
+from anton.commands.datasource.manage import handle_list_data_sources, handle_remove_data_source
+from anton.commands.datasource.custom import (
+    handle_add_custom_datasource,
+    _CustomDatasourceField,
+    _CustomDatasourceSpec,
+)
+from anton.commands.datasource.verify import run_connection_test, handle_test_datasource
+from anton.commands.datasource.connect import handle_connect_datasource
+
+__all__ = [
+    "_PROMPT_RECONNECT_CANCEL",
+    "show_credential_help",
+    "handle_list_data_sources",
+    "handle_remove_data_source",
+    "handle_add_custom_datasource",
+    "run_connection_test",
+    "handle_test_datasource",
+    "handle_connect_datasource",
+]
diff --git a/anton/commands/datasource/connect.py b/anton/commands/datasource/connect.py
new file mode 100644
index 00000000..351dff87
--- /dev/null
+++ b/anton/commands/datasource/connect.py
@@ -0,0 +1,790 @@
+"""Main datasource connection flow."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import TYPE_CHECKING
+
+from anton.connect_collector import ConnectionCollector, extract_variables
+from anton.core.datasources.data_vault import DataVault, LocalDataVault
+from anton.core.datasources.datasource_registry import DatasourceRegistry
+from anton.utils.datasources import parse_connection_slug, register_secret_vars, restore_namespaced_env
+from anton.utils.prompt import prompt_or_cancel
+from anton.commands.datasource.helpers import show_credential_help
+from anton.commands.datasource.custom import handle_add_custom_datasource
+from anton.commands.datasource.verify import run_connection_test
+
+_PROMPT_RECONNECT_CANCEL = "(reconnect/cancel)"
+
+
+def _build_redirect_message(
+    collector: ConnectionCollector,
+    user_message: str,
+    target_engine: str | None = None,
+) -> str:
+    """Build a structured REDIRECT message for the main agent."""
+    collector.redirect_message = user_message.strip()
+    payload = collector.to_redirect_result()
+    parts = [
+        f"REDIRECT during {payload['engine_display']} connection setup.",
+        f"Collected so far: {json.dumps(payload['collected_variables'])}.",
+    ]
+    if payload["missing_required"]:
+        parts.append(
+            f"Still missing: {', '.join(payload['missing_required'])}."
+        )
+    if target_engine:
+        parts.append(f"User wants to switch to: {target_engine}.")
+    parts.append(f'User said: "{collector.redirect_message}".')
+    parts.append(
+        "Decide what to do next — you may call connect_new_datasource "
+        "again with the correct engine and pass known_variables to "
+        "pre-fill what's already collected."
+    )
+    return " ".join(parts)
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from anton.chat import ChatSession
+    from anton.core.backends.manager import ScratchpadManager
+
+
+async def _reconnect_to_saved(
+    console: "Console",
+    session: "ChatSession",
+    vault: "DataVault",
+    registry: "DatasourceRegistry",
+    slug: str,
+    conn: dict,
+    *,
+    from_tool_call: bool = False,
+) -> "ChatSession":
+    """Inject env for a saved connection and mark it as the active datasource."""
+    restore_namespaced_env(vault)
+    session._active_datasource = slug
+    recon_engine_def = registry.get(conn["engine"])
+    if recon_engine_def:
+        register_secret_vars(recon_engine_def, engine=conn["engine"], name=conn["name"])
+        engine_label = recon_engine_def.display_name
+    else:
+        engine_label = conn["engine"]
+    console.print()
+    console.print(
+        f'[anton.success]        ✓ Reconnected to [bold]"{slug}"[/bold].[/]'
+    )
+    console.print()
+    if not from_tool_call:
+        session._history.append(
+            {
+                "role": "assistant",
+                "content": (
+                    f'I\'ve reconnected to the {engine_label} connection "{slug}" '
+                    f"in the Local Vault. I can now query this data source when needed."
+                ),
+            }
+        )
+    return session
+
+
+async def handle_connect_datasource(
+    console: "Console",
+    scratchpads: "ScratchpadManager",
+    session: "ChatSession",
+    datasource_name: str | None = None,
+    prefill: str | None = None,
+    known_variables: dict[str, str] | None = None,
+    from_tool_call: bool = False,
+    vault: "DataVault | None" = None,
+) -> "ChatSession":
+    """
+    Connect a data source by entering credentials, either for a new name or re-entering for an existing one.
+
+    `known_variables` may pre-fill credential fields (e.g. when called as a
+    tool by the LLM, which may have already extracted host/port/etc. from
+    the conversation).
+
+    `from_tool_call=True` when invoked via the LLM `connect_new_datasource`
+    tool. In that case we must NOT append assistant messages to
+    `session._history` — we are sitting between a `tool_use` block and its
+    `tool_result` block, and appending messages there violates the
+    Anthropic API invariant. The tool wrapper builds its own return
+    message from the vault diff instead.
+    """
+
+    vault = vault or LocalDataVault()
+    registry = DatasourceRegistry()
+
+    if datasource_name is not None:
+        parsed = parse_connection_slug(
+            datasource_name, [e.engine for e in registry.all_engines()], vault=vault
+        )
+        if parsed is None:
+            console.print(
+                f"[anton.warning]Invalid slug '{datasource_name}'. "
+                "Expected format: engine-name.[/]"
+            )
+            console.print()
+            return session
+        edit_engine, edit_name = parsed
+        existing = vault.load(edit_engine, edit_name)
+        if existing is None:
+            console.print(
+                f"[anton.warning]No connection '{datasource_name}' found in Local Vault.[/]"
+            )
+            console.print()
+            return session
+        engine_def = registry.get(edit_engine)
+        if engine_def is None:
+            console.print(
+                f"[anton.warning]Unknown engine '{edit_engine}'. "
+                "Cannot update credentials.[/]"
+            )
+            console.print()
+            return session
+
+        console.print()
+        console.print(
+            f"[anton.cyan](anton)[/] Editing [bold]\"{datasource_name}\"[/bold]"
+            f" ({engine_def.display_name})."
+        )
+        console.print("[anton.muted]        Press Enter to keep the current value.[/]")
+        console.print()
+
+        active_fields = engine_def.fields
+        if engine_def.auth_method == "choice" and engine_def.auth_methods:
+            for am in engine_def.auth_methods:
+                am_field_names = {af.name for af in am.fields}
+                if any(k in am_field_names for k in existing):
+                    active_fields = am.fields
+                    break
+            if not active_fields:
+                active_fields = engine_def.auth_methods[0].fields
+
+        credentials: dict[str, str] = dict(existing)
+        for f in active_fields:
+            current = existing.get(f.name, "")
+            field_label = f"(anton) {f.name}"
+            if not f.required:
+                field_label += " (optional)"
+
+            if f.secret:
+                masked = "••••••••" if current else ""
+                label = f"{field_label} [{masked}]" if masked else field_label
+                value = await prompt_or_cancel(label, password=True)
+                if value is None:
+                    return session
+                if value:
+                    credentials[f.name] = value
+            elif current:
+                value = await prompt_or_cancel(
+                    f"{field_label}",
+                    default=current,
+                )
+                if value is None:
+                    return session
+                credentials[f.name] = value if value else current
+            elif f.default:
+                value = await prompt_or_cancel(
+                    f"{field_label}",
+                    default=f.default,
+                )
+                if value is None:
+                    return session
+                if value:
+                    credentials[f.name] = value
+            else:
+                value = await prompt_or_cancel(field_label)
+                if value is None:
+                    return session
+                if value:
+                    credentials[f.name] = value
+
+        if engine_def.test_snippet:
+            if not await run_connection_test(
+                console, scratchpads, vault, engine_def, credentials, active_fields
+            ):
+                return session
+
+        vault.save(edit_engine, edit_name, credentials)
+        restore_namespaced_env(vault)
+        register_secret_vars(engine_def, engine=edit_engine, name=edit_name)
+        console.print()
+        console.print(
+            f'        Credentials updated for [bold]"{datasource_name}"[/bold].'
+        )
+        console.print()
+        console.print(
+            "[anton.muted]        You can now ask me questions about your data.[/]"
+        )
+        console.print()
+        if not from_tool_call:
+            session._history.append(
+                {
+                    "role": "assistant",
+                    "content": (
+                        f"I've updated the credentials for the {engine_def.display_name} connection "
+                        f'"{datasource_name}" in the Local Vault.'
+                    ),
+                }
+            )
+        return session
+
+    console.print()
+    all_engines = registry.all_engines()
+    popular_engines = [e for e in all_engines if e.popular and not e.custom]
+    other_engines = [e for e in all_engines if not e.popular and not e.custom]
+    custom_engines = [e for e in all_engines if e.custom]
+    display_engines = popular_engines + other_engines + custom_engines
+
+    saved_connections = vault.list_connections()
+    seen_engines: set[str] = set()
+    recent_engine_entries: list[tuple[str, str]] = []
+    for c in saved_connections:
+        if c["engine"] not in seen_engines:
+            seen_engines.add(c["engine"])
+            engine_obj = registry.get(c["engine"])
+            label = engine_obj.display_name if engine_obj else c["engine"]
+            recent_engine_entries.append((c["engine"], label))
+
+    def print_sections() -> None:
+        console.print(
+            "[anton.cyan](anton)[/] Select a data source to create a new connection:\n"
+        )
+        console.print("       [bold]  Primary")
+        console.print(
+            "         [bold]  0.[/bold] Custom datasource"
+            " (connect anything via API, SQL, or MCP)\n"
+        )
+        if popular_engines:
+            console.print("       [bold]  Most popular")
+            for i, e in enumerate(popular_engines, 1):
+                console.print(f"          [bold]{i:>2}.[/bold] {e.display_name}")
+            console.print()
+        if recent_engine_entries:
+            start = len(popular_engines) + 1
+            console.print("       [bold]  Recently used data sources")
+            for i, (_, label) in enumerate(recent_engine_entries, start):
+                console.print(f"          [bold]{i:>2}.[/bold] {label}")
+            console.print()
+
+    def print_all() -> None:
+        console.print(
+            "[anton.cyan](anton)[/] All data sources (★ = popular):\n"
+        )
+        console.print("       [bold]  Primary")
+        console.print(
+            "         [bold]  0.[/bold] Custom datasource"
+            " (connect anything via API, SQL, or MCP)\n"
+        )
+        for i, e in enumerate(display_engines, 1):
+            star = " ★" if e.popular else ""
+            console.print(f"          [bold]{i:>2}.[/bold] {e.display_name}{star}")
+        console.print()
+
+    async def get_create_new_answer() -> str | None:
+        print_sections()
+        console.print(
+            "       [anton.muted]Don't see yours? Type a datasource name (e.g., GitHub, Gmail, Jira, ...)\n"
+            "       It can be virtually any datasource — we'll figure out the details together.[/]"
+        )
+        console.print()
+        ans = await prompt_or_cancel(
+            "(anton) Enter a number or type a datasource name",
+        )
+        if ans is None:
+            return None
+        if ans.strip().lower() == "all":
+            console.print()
+            print_all()
+            ans = await prompt_or_cancel(
+                "(anton) Enter a number or type a name",
+            )
+        return ans
+
+    if prefill:
+        answer = prefill
+    elif saved_connections:
+        console.print()
+        console.print("[anton.cyan](anton)[/] What would you like to do?\n")
+        console.print("          [bold]  1.[/bold] Use an existing connection")
+        console.print("          [bold]  2.[/bold] Create a new connection")
+        console.print()
+        top_choice = await prompt_or_cancel(
+            "(anton) Enter a number", choices=["1", "2"]
+        )
+        if top_choice is None:
+            return session
+
+        if top_choice == "1":
+            console.print()
+            console.print("[anton.cyan](anton)[/] Your saved connections:\n")
+            for i, c in enumerate(saved_connections, 1):
+                conn_slug = f"{c['engine']}-{c['name']}"
+                engine_obj = registry.get(c["engine"])
+                engine_label = engine_obj.display_name if engine_obj else c["engine"]
+                console.print(
+                    f"          [bold]{i:>2}.[/bold] {conn_slug}"
+                    f" [dim]— {engine_label}[/]"
+                )
+            console.print()
+            pick = await prompt_or_cancel(
+                "(anton) Enter a number",
+                choices=[str(i) for i in range(1, len(saved_connections) + 1)],
+            )
+            if pick is None:
+                return session
+            picked_conn = saved_connections[int(pick) - 1]
+            picked_slug = f"{picked_conn['engine']}-{picked_conn['name']}"
+            return await _reconnect_to_saved(
+                console, session, vault, registry, picked_slug, picked_conn,
+                from_tool_call=from_tool_call,
+            )
+
+        answer = await get_create_new_answer()
+        if answer is None:
+            return session
+    else:
+        answer = await get_create_new_answer()
+        if answer is None:
+            return session
+
+    stripped_answer = answer.strip()
+    known_slugs = {
+        f"{c['engine']}-{c['name']}": c for c in vault.list_connections()
+    }
+    if stripped_answer in known_slugs:
+        conn = known_slugs[stripped_answer]
+        return await _reconnect_to_saved(
+            console, session, vault, registry, stripped_answer, conn,
+            from_tool_call=from_tool_call,
+        )
+
+    engine_def = None
+    custom_source = False
+    llm_recognised = False
+    saved_start = len(popular_engines) + 1
+    max_num = len(popular_engines) + len(recent_engine_entries)
+
+    if stripped_answer.isdigit() or (stripped_answer.lstrip("-").isdigit()):
+        pick_num = int(stripped_answer)
+        if pick_num == 0:
+            custom_source = True
+        elif 1 <= pick_num <= len(popular_engines):
+            engine_def = popular_engines[pick_num - 1]
+        elif recent_engine_entries and saved_start <= pick_num <= max_num:
+            picked_engine_slug, _ = recent_engine_entries[pick_num - saved_start]
+            engine_def = registry.get(picked_engine_slug)
+            if engine_def is None:
+                custom_source = True
+        else:
+            console.print(
+                f"[anton.warning](anton)[/] '{stripped_answer}' is out of range. "
+                f"Please enter 0\u2013{max_num}.[/]"
+            )
+            console.print()
+            return session
+
+    if engine_def is None and not custom_source:
+        engine_def = registry.find_by_name(stripped_answer)
+        if engine_def is None:
+            needle = stripped_answer.lower()
+            candidates = [
+                e
+                for e in all_engines
+                if needle in e.display_name.lower() or needle in e.engine.lower()
+            ]
+            if len(candidates) == 1:
+                engine_def = candidates[0]
+            elif len(candidates) > 1:
+                console.print()
+                console.print(
+                    f"[anton.warning](anton)[/] '{stripped_answer}' matches multiple engines — "
+                    "which one did you mean?"
+                )
+                console.print()
+                for i, e in enumerate(candidates, 1):
+                    console.print(f"        {i}. {e.display_name}")
+                console.print()
+                pick = await prompt_or_cancel("(anton) Enter a number")
+                if pick is None:
+                    return session
+                pick = (pick or "").strip()
+                try:
+                    engine_def = candidates[int(pick) - 1]
+                except (ValueError, IndexError):
+                    console.print("[anton.warning]Invalid choice. Aborting.[/]")
+                    console.print()
+                    return session
+
+        if engine_def is None:
+            engine_names = [e.display_name for e in all_engines]
+            try:
+                console.print()
+                console.print("[anton.muted]        Looking up datasource…[/]")
+                llm_resp = await session._llm.plan(
+                    system="You are a datasource identification assistant.",
+                    messages=[
+                        {
+                            "role": "user",
+                            "content": (
+                                f"The user typed: {stripped_answer!r}\n"
+                                f"Known datasources: {engine_names!r}\n\n"
+                                "If the user input clearly matches one of the known datasources, "
+                                "reply with EXACTLY: MATCH:<display_name>\n"
+                                "If it does NOT match any known datasource but you recognise it "
+                                "as a real service/tool, reply with EXACTLY: CUSTOM\n"
+                                "If you don't recognise it at all, reply with EXACTLY: UNKNOWN\n"
+                                "Reply with only one of those three forms, nothing else."
+                            ),
+                        }
+                    ],
+                    max_tokens=64,
+                )
+                llm_text = (llm_resp.content or "").strip()
+            except Exception:
+                llm_text = "UNKNOWN"
+
+            llm_recognised = llm_text == "CUSTOM" or llm_text.startswith("MATCH:")
+
+            if llm_text.startswith("MATCH:"):
+                matched_name = llm_text[len("MATCH:"):].strip()
+                matched_engine = next(
+                    (e for e in all_engines if e.display_name == matched_name), None
+                )
+                if matched_engine is not None:
+                    if matched_name.lower() != stripped_answer.lower():
+                        confirm = await prompt_or_cancel(
+                            f'(anton) Did you mean "{matched_name}"?',
+                            choices=["y", "n"], default="y",
+                        )
+                        if confirm is not None and confirm.strip().lower() == "y":
+                            engine_def = matched_engine
+                    else:
+                        engine_def = matched_engine
+
+            if engine_def is None:
+                custom_source = True
+
+    if custom_source:
+        result = await handle_add_custom_datasource(
+            console, stripped_answer if not stripped_answer.isdigit() else "", registry, session,
+            known_service=llm_recognised,
+        )
+        if result is None:
+            return session
+        engine_def, credentials = result
+        if engine_def.test_snippet:
+            if not await run_connection_test(
+                console, scratchpads, vault, engine_def, credentials, engine_def.fields
+            ):
+                return session
+        conn_name = uuid.uuid4().hex[:8]
+        vault.save(engine_def.engine, conn_name, credentials)
+        slug = f"{engine_def.engine}-{conn_name}"
+        restore_namespaced_env(vault)
+        session._active_datasource = slug
+        register_secret_vars(engine_def, engine=engine_def.engine, name=conn_name)
+        console.print(
+            f'        Credentials saved to Local Vault as [bold]"{slug}"[/bold].'
+        )
+        console.print()
+        console.print(
+            "[anton.muted]        You can now ask me questions about your data.[/]"
+        )
+        console.print()
+        if not from_tool_call:
+            session._history.append(
+                {
+                    "role": "assistant",
+                    "content": (
+                        f'I\'ve saved a {engine_def.display_name} connection named "{slug}" '
+                        f"to the Local Vault. I can now query this data source when needed."
+                    ),
+                }
+            )
+        return session
+
+    assert engine_def is not None
+    active_fields = engine_def.fields
+    chosen_method = None
+    if engine_def.auth_method == "choice" and engine_def.auth_methods:
+        console.print()
+        console.print(
+            f"[anton.cyan](anton)[/] How would you like to authenticate with "
+            f"[bold]{engine_def.display_name}[/]?"
+        )
+        console.print()
+        for i, am in enumerate(engine_def.auth_methods, 1):
+            console.print(f"        {i}. {am.display}")
+        console.print()
+        choice_str = await prompt_or_cancel("(anton) Enter a number")
+        if choice_str is None:
+            return session
+        choice_str = (choice_str or "").strip()
+        try:
+            choice_idx = int(choice_str) - 1
+            chosen_method = engine_def.auth_methods[choice_idx]
+        except (ValueError, IndexError):
+            console.print("[anton.warning]Invalid choice. Aborting.[/]")
+            console.print()
+            return session
+        active_fields = chosen_method.fields
+
+    collector = ConnectionCollector(
+        engine_def=engine_def,
+        auth_method=chosen_method,
+    )
+    if known_variables:
+        collector.fill_many(known_variables)
+
+    known_engine_slugs = [e.engine for e in registry.all_engines()]
+    partial = False
+    required_fields = [f for f in active_fields if f.required]
+    optional_fields = [f for f in active_fields if not f.required]
+
+    if collector.is_complete:
+        filled_names = [
+            f.name for f in active_fields if collector.collected.get(f.name)
+        ]
+        console.print()
+        console.print(
+            f"[anton.cyan](anton)[/] Got everything for [bold]"
+            f"{engine_def.display_name}[/] from context: "
+            f"{', '.join(filled_names)}."
+        )
+        console.print()
+    else:
+        console.print()
+        console.print(
+            f"[anton.cyan](anton)[/] To connect [bold]"
+            f"{engine_def.display_name}[/], I'll need the following:"
+        )
+        console.print()
+
+        if required_fields:
+            console.print("        [bold]Required[/]      " + "─" * 39)
+            for f in required_fields:
+                marker = (
+                    "[green]✓[/] " if collector.collected.get(f.name) else "• "
+                )
+                console.print(
+                    f"        {marker}[bold]{f.name:<12}[/] "
+                    f"[anton.muted]— {f.description}[/]"
+                )
+
+        if optional_fields:
+            console.print()
+            console.print("        [bold]Optional[/]      " + "─" * 39)
+            for f in optional_fields:
+                marker = (
+                    "[green]✓[/] " if collector.collected.get(f.name) else "• "
+                )
+                console.print(
+                    f"        {marker}[bold]{f.name:<12}[/] "
+                    f"[anton.muted]— {f.description}[/]"
+                )
+
+        console.print()
+
+        if not collector.collected:
+            help_answer = await prompt_or_cancel(
+                "(anton) Do you need instructions on how to obtain these credentials?",
+                choices_display="y/n", default="n",
+            )
+            if help_answer is None:
+                return session
+            normalized = help_answer.strip().lower()
+            if normalized == "y":
+                await show_credential_help(
+                    console, session, engine_def.display_name, None, active_fields,
+                )
+            elif normalized and normalized != "n":
+                extracted = await extract_variables(
+                    help_answer,
+                    expected_fields=collector.active_fields,
+                    current_engine=engine_def.engine,
+                    current_engine_display=engine_def.display_name,
+                    known_engine_slugs=known_engine_slugs,
+                    session=session,
+                )
+                if extracted.is_redirect:
+                    redirect_text = _build_redirect_message(
+                        collector, help_answer, extracted.redirect_engine
+                    )
+                    session._pending_connect_redirect = redirect_text
+                    if not from_tool_call:
+                        session._history.append(
+                            {"role": "assistant", "content": redirect_text}
+                        )
+                    return session
+                if extracted.variables:
+                    filled = collector.fill_many(extracted.variables)
+                    if filled:
+                        console.print(
+                            f"[anton.muted]        Got: {', '.join(filled)}[/]"
+                        )
+                        console.print()
+
+    while not collector.is_complete:
+        collector.format_status(console)
+        console.print()
+
+        next_field = collector.next_field
+        only_one_required = (
+            next_field is not None
+            and next_field.required
+            and len(collector.missing_required) == 1
+        )
+
+        if only_one_required and next_field is not None:
+            label = f"(anton) {next_field.name}"
+            if next_field.secret:
+                value = await prompt_or_cancel(label, password=True)
+            elif next_field.default:
+                value = await prompt_or_cancel(label, default=next_field.default)
+            else:
+                value = await prompt_or_cancel(label)
+            if value is None:
+                return session
+            if not value:
+                partial = True
+                break
+            collector.fill(next_field.name, value)
+            continue
+
+        missing_names = ", ".join(f.name for f in collector.missing_required)
+        prompt_label = (
+            f"(anton) Provide values for {missing_names} "
+            f"(one at a time, or 'key=value key2=value2', or 'skip')"
+        )
+        value = await prompt_or_cancel(prompt_label)
+        if value is None:
+            return session
+        if value.strip().lower() == "skip":
+            partial = True
+            break
+        if not value.strip():
+            continue
+
+        extracted = await extract_variables(
+            value,
+            expected_fields=collector.active_fields,
+            current_engine=engine_def.engine,
+            current_engine_display=engine_def.display_name,
+            known_engine_slugs=known_engine_slugs,
+            session=session,
+        )
+
+        if extracted.is_redirect:
+            redirect_text = _build_redirect_message(
+                collector, value, extracted.redirect_engine
+            )
+            session._pending_connect_redirect = redirect_text
+            if not from_tool_call:
+                session._history.append(
+                    {"role": "assistant", "content": redirect_text}
+                )
+            return session
+
+        if extracted.variables:
+            filled = collector.fill_many(extracted.variables)
+            if filled:
+                console.print(
+                    f"[anton.muted]        Got: {', '.join(filled)}[/]"
+                )
+                console.print()
+                continue
+
+        if next_field is not None:
+            collector.fill(next_field.name, value.strip())
+        else:
+            console.print(
+                "[anton.warning]        Couldn't parse that. "
+                "Try 'key=value' or one value at a time.[/]"
+            )
+            console.print()
+
+    credentials: dict[str, str] = dict(collector.collected)
+
+    if partial:
+        auto_name = uuid.uuid4().hex[:8]
+        vault.save(engine_def.engine, auto_name, credentials)
+        slug = f"{engine_def.engine}-{auto_name}"
+        console.print()
+        console.print(
+            f"[anton.muted]Partial connection saved to Local Vault as "
+            f'[bold]"{slug}"[/bold]. '
+            f"Run [bold]/edit {slug}[/bold] to complete it when you're ready.[/]"
+        )
+        console.print()
+        return session
+
+    if engine_def.test_snippet:
+        if not await run_connection_test(
+            console, scratchpads, vault, engine_def, credentials, active_fields
+        ):
+            session._pending_connect_status = "test_failed"
+            return session
+
+    conn_name = registry.derive_name(engine_def, credentials)
+    if not conn_name:
+        conn_name = uuid.uuid4().hex[:8]
+
+    slug = f"{engine_def.engine}-{conn_name}"
+
+    if vault.load(engine_def.engine, conn_name) is not None:
+        console.print()
+        console.print(
+            f'[anton.warning](anton)[/] A connection [bold]"{slug}"[/bold] already exists.'
+        )
+        console.print()
+        choice = await prompt_or_cancel(
+            f"(anton) {_PROMPT_RECONNECT_CANCEL}",
+        )
+        if choice is None or choice.strip().lower() != "reconnect":
+            console.print("[anton.muted]Cancelled.[/]")
+            console.print()
+            return session
+        restore_namespaced_env(vault)
+        register_secret_vars(engine_def, engine=engine_def.engine, name=conn_name)
+        console.print()
+        console.print(
+            f'[anton.success]        ✓ Reconnected to [bold]"{slug}"[/bold].[/]'
+        )
+        console.print()
+        if not from_tool_call:
+            session._history.append(
+                {
+                    "role": "assistant",
+                    "content": (
+                        f'I\'ve reconnected to the {engine_def.display_name} connection "{slug}" '
+                        f"in the Local Vault. I can now query this data source when needed."
+                    ),
+                }
+            )
+        return session
+
+    vault.save(engine_def.engine, conn_name, credentials)
+    restore_namespaced_env(vault)
+    session._active_datasource = slug
+    register_secret_vars(engine_def, engine=engine_def.engine, name=conn_name)
+    console.print(f'        Credentials saved to Local Vault as [bold]"{slug}"[/bold].')
+
+    console.print()
+    console.print(
+        "[anton.muted]        You can now ask me questions about your data.[/]"
+    )
+    console.print()
+
+    if not from_tool_call:
+        session._history.append(
+            {
+                "role": "assistant",
+                "content": (
+                    f'I\'ve saved a {engine_def.display_name} connection named "{slug}" '
+                    f"to the Local Vault. I can now query this data source when needed."
+                ),
+            }
+        )
+    return session
diff --git a/anton/commands/datasource/custom.py b/anton/commands/datasource/custom.py
new file mode 100644
index 00000000..bc2ec1b0
--- /dev/null
+++ b/anton/commands/datasource/custom.py
@@ -0,0 +1,310 @@
+"""Custom datasource creation (LLM-assisted)."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from anton.core.datasources.datasource_registry import DatasourceEngine, DatasourceField
+from anton.utils.datasources import remove_engine_block
+from anton.utils.prompt import prompt_or_cancel
+from anton.commands.datasource.helpers import show_credential_help
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from anton.chat import ChatSession
+    from anton.core.datasources.datasource_registry import DatasourceRegistry
+
+
+class _CustomDatasourceField(BaseModel):
+    """One credential field in a custom-datasource spec."""
+
+    name: str = Field(
+        ...,
+        description=(
+            "snake_case field name (e.g. 'host', 'api_key'). Must be a "
+            "valid Python identifier; this becomes both the on-disk key "
+            "and the env var suffix (DS_<NAME>)."
+        ),
+    )
+    value: str = Field(
+        default="",
+        description=(
+            "Inline value if the user already provided one in their "
+            "description, otherwise empty string."
+        ),
+    )
+    secret: bool = Field(
+        default=False,
+        description=(
+            "True if the field is sensitive (passwords, API keys, "
+            "tokens) — affects how it's stored and prompted for."
+        ),
+    )
+    required: bool = Field(
+        default=True,
+        description="True if the connection cannot be tested without this field.",
+    )
+    description: str = Field(
+        default="",
+        description=(
+            "One-line description shown to the user when prompting "
+            "for this field."
+        ),
+    )
+
+
+class _CustomDatasourceSpec(BaseModel):
+    """Structured output of the LLM call in handle_add_custom_datasource."""
+
+    display_name: str = Field(
+        ...,
+        description="Human-readable name for the service (e.g. 'GitHub API').",
+    )
+    pip: str = Field(
+        default="",
+        description=(
+            "pip-installable package name (or space-separated names) "
+            "needed to interact with this service. Empty string if no "
+            "extra package is required (e.g. plain HTTPS via stdlib)."
+        ),
+    )
+    test_snippet: str = Field(
+        default="",
+        description=(
+            "Python code that tests the connection using os.environ "
+            "vars DS_FIELDNAME (uppercase field name with DS_ prefix) "
+            "and prints 'ok' on success. Empty string if untestable."
+        ),
+    )
+    fields: list[_CustomDatasourceField] = Field(
+        default_factory=list,
+        description=(
+            "Credential fields the user will need to provide. List in "
+            "the order they should be prompted."
+        ),
+    )
+
+
+async def handle_add_custom_datasource(
+    console: "Console",
+    name: str,
+    registry: "DatasourceRegistry",
+    session: "ChatSession",
+    *,
+    known_service: bool = False,
+):
+    """Ask for the tool name, use the LLM to identify required fields, then collect credentials."""
+
+    console.print()
+    if name:
+        tool_name = name
+    else:
+        tool_name = await prompt_or_cancel(
+            "(anton) What is the name of the tool or service?",
+        )
+        if not tool_name or not tool_name.strip():
+            return None
+        tool_name = tool_name.strip()
+
+    if known_service:
+        user_answer = ""
+        console.print("[anton.muted]        Working out the connection details…[/]")
+    else:
+        user_answer = await prompt_or_cancel(
+            f"(anton) How do you authenticate with {tool_name}? "
+            "Describe what credentials you have (don't paste actual values)",
+        )
+        if not user_answer or not user_answer.strip():
+            return None
+        console.print()
+        console.print("[anton.muted]    Got it — working out the connection details…[/]")
+
+    llm_prompt = f"The user wants to connect to {repr(tool_name)}."
+    if user_answer:
+        llm_prompt += f" They said: {user_answer}"
+    else:
+        llm_prompt += " Determine the standard authentication fields for this service."
+    llm_prompt += (
+        "\n\nReturn the connection spec following the schema you've been given. "
+        "For test_snippet, write Python that uses os.environ['DS_<FIELDNAME>'] "
+        "vars (uppercase, DS_ prefix) and prints 'ok' on success."
+    )
+
+    try:
+        spec: _CustomDatasourceSpec = await session._llm.generate_object(
+            _CustomDatasourceSpec,
+            system="You are a data source connection expert.",
+            messages=[{"role": "user", "content": llm_prompt}],
+            max_tokens=1024,
+        )
+    except Exception:
+        console.print(
+            "[anton.warning]        Couldn't identify connection details. Try again.[/]"
+        )
+        console.print()
+        return None
+
+    test_snippet = spec.test_snippet.strip()
+    fields: list[DatasourceField] = []
+    for f in spec.fields:
+        if not f.name:
+            continue
+        fields.append(
+            DatasourceField(
+                name=f.name,
+                required=f.required,
+                secret=f.secret,
+                description=f.description,
+            )
+        )
+
+    if not fields:
+        console.print("[anton.warning]    Couldn't identify any connection fields.[/]")
+        console.print()
+        return None
+
+    display_name = spec.display_name or name
+    pip_pkg = spec.pip
+
+    # Show summary
+    console.print()
+    console.print("      [bold]── What I'll save ──────────────────────────[/]")
+    credentials: dict[str, str] = {}
+    for f, raw in zip(fields, spec.fields):
+        inline_value = (raw.value or "").strip()
+        if f.secret and inline_value:
+            console.print(
+                f"        • [bold]{f.name:<14}[/] (secret — provided, stored securely)"
+            )
+            credentials[f.name] = inline_value
+        elif f.secret:
+            console.print(
+                f"        • [bold]{f.name:<14}[/] (secret — I'll ask for this)"
+            )
+        else:
+            val_display = inline_value or "[anton.muted]<to be collected>[/]"
+            console.print(f"        • [bold]{f.name:<14}[/] {val_display}")
+            if inline_value:
+                credentials[f.name] = inline_value
+    console.print()
+
+    help_answer = await prompt_or_cancel(
+        "(anton) Do you need instructions on how to obtain these credentials?",
+        choices=["y", "n"], default="n",
+    )
+    if help_answer is None:
+        return None
+    if help_answer.strip().lower() == "y":
+        await show_credential_help(
+            console, session, display_name, None, fields,
+        )
+
+    # Prompt for any secret fields not provided inline
+    for f, raw in zip(fields, spec.fields):
+        if not f.secret:
+            continue
+        if (raw.value or "").strip():
+            continue
+        value = await prompt_or_cancel(f"(anton) {f.name}", password=True)
+        if value is None:
+            return None
+        if value:
+            credentials[f.name] = value
+
+    # Prompt for any required non-secret fields not provided inline
+    for f, raw in zip(fields, spec.fields):
+        if f.secret:
+            continue
+        if not f.required:
+            continue
+        if f.name in credentials:
+            continue
+        value = await prompt_or_cancel(f"(anton) {f.name}")
+        if value is None:
+            return None
+        if value:
+            credentials[f.name] = value
+
+    # Offer to collect optional non-secret fields
+    for f, raw in zip(fields, spec.fields):
+        if f.secret or f.required or f.name in credentials:
+            continue
+        value = await prompt_or_cancel(f"(anton) {f.name} (optional — press Enter to skip)")
+        if value is None:
+            return None
+        if value:
+            credentials[f.name] = value
+
+    if not credentials:
+        console.print("[anton.warning]        No credentials collected. Aborting.[/]")
+        console.print()
+        return None
+
+    # Build engine slug and write definition to ~/.anton/datasources.md
+    slug = re.sub(r"[^\w]", "_", display_name.lower()).strip("_")
+    field_lines = "\n".join(
+        f"  - {{ name: {f.name}, required: {str(f.required).lower()}, "
+        f'secret: {str(f.secret).lower()}, description: "{f.description}" }}'
+        for f in fields
+    )
+    test_snippet_yaml = ""
+    if test_snippet:
+        indented = "\n".join(f"  {line}" for line in test_snippet.splitlines())
+        test_snippet_yaml = f"test_snippet: |\n{indented}\n"
+
+    yaml_block = (
+        f"\n---\n\n## {display_name}\n"
+        "```yaml\n"
+        f"engine: {slug}\n"
+        f"display_name: {display_name}\n"
+        + (f"pip: {pip_pkg}\n" if pip_pkg else "")
+        + f"fields:\n{field_lines}\n"
+        + test_snippet_yaml
+        + "```\n"
+    )
+    user_ds_path = Path("~/.anton/datasources.md").expanduser()
+    tmp_path = user_ds_path.with_suffix(".tmp")
+
+    existing = (
+        user_ds_path.read_text(encoding="utf-8") if user_ds_path.is_file() else ""
+    )
+    existing = remove_engine_block(existing, slug)
+
+    tmp_path.write_text(existing + yaml_block, encoding="utf-8")
+
+    parsed = registry.validate_file(tmp_path)
+    if slug in parsed:
+        shutil.move(str(tmp_path), str(user_ds_path))
+    else:
+        tmp_path.unlink(missing_ok=True)
+        console.print(
+            "[anton.warning]Could not validate engine definition — "
+            "credentials saved but engine not written to datasources.md.[/]"
+        )
+
+    registry.reload()
+    engine_def = registry.get(slug)
+    if engine_def is None:
+        engine_def = DatasourceEngine(
+            engine=slug,
+            display_name=display_name,
+            pip=pip_pkg,
+            fields=fields,
+            test_snippet=test_snippet,
+        )
+
+    missing_required = [f.name for f in fields if f.required and f.name not in credentials]
+    if missing_required:
+        console.print(
+            "[anton.warning]    Cannot save — missing required fields: "
+            f"{', '.join(missing_required)}. Aborting.[/]"
+        )
+        console.print()
+        return None
+
+    return engine_def, credentials
diff --git a/anton/commands/datasource/helpers.py b/anton/commands/datasource/helpers.py
new file mode 100644
index 00000000..c44f5e7d
--- /dev/null
+++ b/anton/commands/datasource/helpers.py
@@ -0,0 +1,69 @@
+"""Shared helpers for datasource commands."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.markdown import Markdown
+from rich.padding import Padding
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from anton.chat import ChatSession
+
+
+async def show_credential_help(
+    console: "Console",
+    session: "ChatSession",
+    service_name: str,
+    current_field,
+    all_fields: list,
+) -> None:
+    """Use the LLM to explain how to obtain credentials."""
+    field_descriptions = ", ".join(
+        f"{f.name} ({f.description})" for f in all_fields
+    )
+    storage_note = (
+        "The credentials will be stored securely in Anton's Local Vault — "
+        "do NOT suggest storage tips, password managers, or safe-keeping advice."
+    )
+    if current_field is not None:
+        prompt = (
+            f"I'm connecting to {service_name} and need to provide: {field_descriptions}\n\n"
+            f"I need help with the '{current_field.name}' field"
+            f" ({current_field.description}).\n\n"
+            "Give me a brief step-by-step guide on where and how to get this credential. "
+            f"Be concise — numbered steps, no fluff. {storage_note}"
+        )
+        heading = f"[anton.cyan](anton)[/] How to get [bold]{current_field.name}[/]:"
+    else:
+        prompt = (
+            f"I'm connecting to {service_name} and need these credentials: {field_descriptions}\n\n"
+            "Give me a brief step-by-step guide on where and how to obtain each of these. "
+            f"Be concise — numbered steps, no fluff. {storage_note}"
+        )
+        heading = f"[anton.cyan](anton)[/] How to get credentials for [bold]{service_name}[/]:"
+
+    console.print()
+    console.print("[anton.muted]        Looking up instructions…[/]")
+
+    try:
+        resp = await session._llm.plan(
+            system="You are a helpful assistant that guides users through obtaining credentials for services.",
+            messages=[
+                {
+                    "role": "user",
+                    "content": prompt,
+                }
+            ],
+            max_tokens=512,
+        )
+        help_text = (resp.content or "").strip()
+    except Exception:
+        help_text = "Sorry, couldn't fetch help right now. Try checking the service's documentation."
+
+    console.print()
+    console.print(heading)
+    console.print()
+    console.print(Padding(Markdown(help_text), (0, 0, 0, 8)))
+    console.print()
diff --git a/anton/commands/datasource/manage.py b/anton/commands/datasource/manage.py
new file mode 100644
index 00000000..ed8e8c0a
--- /dev/null
+++ b/anton/commands/datasource/manage.py
@@ -0,0 +1,120 @@
+"""List and remove datasource commands."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from anton.core.datasources.data_vault import DataVault, LocalDataVault
+from anton.core.datasources.datasource_registry import DatasourceRegistry
+from anton.utils.datasources import parse_connection_slug, remove_engine_block, restore_namespaced_env
+from anton.utils.prompt import prompt_or_cancel
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+
+def handle_list_data_sources(console: "Console", vault: DataVault | None = None) -> None:
+    """Print all saved Local Vault connections in a table with status."""
+    from rich.table import Table
+
+    vault = vault or LocalDataVault()
+    registry = DatasourceRegistry()
+    conns = vault.list_connections()
+    console.print()
+    if not conns:
+        console.print("[anton.muted]No data sources connected yet.[/]")
+        console.print("[anton.muted]Use /connect to add one.[/]")
+        console.print()
+        return
+
+    table = Table(title="Local Vault — Saved Connections", show_lines=False)
+    table.add_column("Name", style="bold")
+    table.add_column("Source")
+    table.add_column("Status")
+
+    for c in conns:
+        slug = f"{c['engine']}-{c['name']}"
+        engine_def = registry.get(c["engine"])
+        source = engine_def.display_name if engine_def else c["engine"]
+        fields = vault.load(c["engine"], c["name"]) or {}
+
+        if not fields:
+            status = "[yellow]incomplete[/]"
+        elif engine_def and engine_def.auth_method != "choice":
+            required = [f.name for f in engine_def.fields if f.required]
+            missing = [name for name in required if name not in fields]
+            status = "[yellow]incomplete[/]" if missing else "[green]saved[/]"
+        else:
+            status = "[green]saved[/]"
+
+        table.add_row(slug, source, status)
+
+    console.print(table)
+    console.print()
+
+
+async def handle_remove_data_source(console: "Console", slug: str, vault: DataVault | None = None) -> None:
+    """Delete a connection from the Local Vault by slug (engine-name)."""
+    vault = vault or LocalDataVault()
+    registry = DatasourceRegistry()
+
+    if not slug:
+        connections = vault.list_connections()
+        if not connections:
+            console.print("[anton.muted]No saved connections to remove.[/]")
+            console.print()
+            return
+        console.print()
+        console.print("[anton.cyan](anton)[/] Which connection do you want to remove?\n")
+        for i, c in enumerate(connections, 1):
+            conn_slug = f"{c['engine']}-{c['name']}"
+            engine_def = registry.get(c["engine"])
+            label = engine_def.display_name if engine_def else c["engine"]
+            console.print(f"          [bold]{i:>2}.[/bold] {conn_slug} [dim]({label})[/]")
+        console.print()
+        choices = [str(i) for i in range(1, len(connections) + 1)]
+        pick = await prompt_or_cancel("(anton) Enter a number", choices=choices)
+        if pick is None:
+            console.print("[anton.muted]Cancelled.[/]")
+            console.print()
+            return
+        picked = connections[int(pick) - 1]
+        slug = f"{picked['engine']}-{picked['name']}"
+
+    parsed = parse_connection_slug(slug, [e.engine for e in registry.all_engines()], vault=vault)
+    if parsed is None:
+        console.print(
+            f"[anton.warning]Invalid name '{slug}'. Use engine-name format.[/]"
+        )
+        console.print()
+        return
+    engine, name = parsed
+    if vault.load(engine, name) is None:
+        console.print(f"[anton.warning]No connection '{slug}' found.[/]")
+        console.print()
+        return
+
+    confirm = await prompt_or_cancel(
+        f"(anton) Remove '{slug}' from Local Vault?",
+        choices=["y", "n"], default="n",
+    )
+    if confirm is not None and confirm.strip().lower() == "y":
+        vault.delete(engine, name)
+        restore_namespaced_env(vault)
+        engine_def = registry.get(engine)
+        if engine_def is not None and engine_def.custom:
+            remaining = [
+                c for c in vault.list_connections() if c["engine"] == engine
+            ]
+            if not remaining:
+                user_path = DatasourceRegistry._USER_PATH
+                if user_path.is_file():
+                    updated = remove_engine_block(
+                        user_path.read_text(encoding="utf-8"), engine
+                    )
+                    user_path.write_text(updated, encoding="utf-8")
+                    registry.reload()
+        console.print(f"[anton.success]Removed {slug}.[/]")
+    else:
+        console.print("[anton.muted]Cancelled.[/]")
+    console.print()
diff --git a/anton/commands/datasource/verify.py b/anton/commands/datasource/verify.py
new file mode 100644
index 00000000..3980e3f3
--- /dev/null
+++ b/anton/commands/datasource/verify.py
@@ -0,0 +1,187 @@
+"""Connection testing commands."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import TYPE_CHECKING
+
+from anton.core.datasources.data_vault import DataVault, LocalDataVault
+from anton.core.datasources.datasource_registry import DatasourceEngine, DatasourceField, DatasourceRegistry
+from anton.utils.datasources import parse_connection_slug, register_secret_vars, restore_namespaced_env
+from anton.utils.prompt import prompt_or_cancel
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from anton.core.backends.manager import ScratchpadManager
+
+
+async def run_connection_test(
+    console: "Console",
+    scratchpads: "ScratchpadManager",
+    vault: "DataVault",
+    engine_def: "DatasourceEngine",
+    credentials: dict[str, str],
+    retry_fields: "list[DatasourceField]",
+) -> bool:
+    """Inject flat DS_* vars, run engine_def.test_snippet, restore env.
+
+    Returns True on success, False if the user declines retry after failure.
+    Mutates credentials in-place when the user re-enters secrets on retry.
+    """
+    while True:
+        console.print()
+        console.print("[anton.cyan](anton)[/] Got it. Testing connection…")
+
+        vault.clear_ds_env()
+        for key, value in credentials.items():
+            os.environ[f"DS_{key.upper()}"] = value
+        register_secret_vars(engine_def)  # flat mode, for scrubbing during test
+
+        try:
+            pad = await scratchpads.get_or_create("__datasource_test__")
+            await pad.reset()
+            if engine_def.pip:
+                if isinstance(engine_def.pip, list):
+                    pip_pkgs = engine_def.pip
+                else:
+                    pip_pkgs = engine_def.pip.split()
+                install_result = await pad.install_packages(pip_pkgs)
+                if "failed" in (install_result or "").lower():
+                    console.print()
+                    console.print(f"[anton.warning](anton)[/] Package install issue: {install_result[:200]}")
+
+            cell = None
+            for attempt in range(3):
+                cell = await pad.execute(engine_def.test_snippet)
+                if cell.error and "ModuleNotFoundError" in cell.error:
+                    match = re.search(r"No module named '([^']+)'", cell.error)
+                    if match:
+                        missing = match.group(1).split(".")[0]
+                        await pad.install_packages([missing])
+                        continue
+                break
+        finally:
+            restore_namespaced_env(vault)
+
+        if cell.error or (cell.stdout.strip() != "ok" and cell.stderr.strip()):
+            error_text = cell.error or cell.stderr.strip() or cell.stdout.strip()
+            last_line = next(
+                (ln for ln in reversed(error_text.splitlines()) if ln.strip()), error_text
+            )
+            console.print()
+            console.print("[anton.warning](anton)[/] ✗ Connection failed.")
+            console.print()
+            console.print(f"        Error: {last_line}")
+            console.print()
+            retry = await prompt_or_cancel(
+                "(anton) Would you like to re-enter your credentials?",
+                choices=["y", "n"], default="n",
+            )
+            if retry is None or retry.strip().lower() != "y":
+                return False
+            console.print()
+            for f in retry_fields:
+                if not f.secret:
+                    continue
+                value = await prompt_or_cancel(f"(anton) {f.name}", password=True)
+                if value is None:
+                    return False
+                if value:
+                    credentials[f.name] = value
+            continue
+
+        console.print("[anton.success]        ✓ Connected successfully![/]")
+        return True
+
+
+async def handle_test_datasource(
+    console: "Console",
+    scratchpads: "ScratchpadManager",
+    slug: str,
+    vault: DataVault | None = None,
+) -> None:
+    """Test an existing Local Vault connection by running its test_snippet."""
+    if not slug:
+        console.print(
+            "[anton.warning]Usage: /test <engine-name>[/]"
+        )
+        console.print()
+        return
+
+    vault = vault or LocalDataVault()
+    registry = DatasourceRegistry()
+    parsed = parse_connection_slug(slug, [e.engine for e in registry.all_engines()], vault=vault)
+    if parsed is None:
+        console.print(
+            f"[anton.warning]Invalid name '{slug}'. Use engine-name format.[/]"
+        )
+        console.print()
+        return
+    engine, name = parsed
+    fields = vault.load(engine, name)
+    if fields is None:
+        console.print(
+            f"[anton.warning]No connection '{slug}' found in Local Vault.[/]"
+        )
+        console.print()
+        return
+
+    engine_def = registry.get(engine)
+    if engine_def is None:
+        console.print(
+            f"[anton.warning]Unknown engine '{engine}'. Cannot test.[/]"
+        )
+        console.print()
+        return
+
+    if not engine_def.test_snippet:
+        console.print(
+            f"[anton.warning]No test snippet defined for '{engine}'. Cannot test.[/]"
+        )
+        console.print()
+        return
+
+    console.print()
+    console.print(
+        f"[anton.cyan](anton)[/] Testing connection [bold]{slug}[/bold]…"
+    )
+
+    vault.clear_ds_env()
+    vault.inject_env(engine, name, flat=True)
+    register_secret_vars(engine_def)  # flat names for scrubbing during test
+
+    cell = None
+    try:
+        pad = await scratchpads.get_or_create("__datasource_test__")
+        await pad.reset()
+        if engine_def.pip:
+            await pad.install_packages([engine_def.pip])
+        cell = await pad.execute(engine_def.test_snippet)
+    finally:
+        restore_namespaced_env(vault)
+
+    if cell is None or cell.error or (
+        cell.stdout.strip() != "ok" and cell.stderr.strip()
+    ):
+        error_text = ""
+        if cell is not None:
+            error_text = cell.error or cell.stderr.strip() or cell.stdout.strip()
+        first_line = (
+            next((ln for ln in error_text.splitlines() if ln.strip()), error_text)
+            if error_text
+            else "unknown error"
+        )
+        console.print()
+        console.print(
+            f"[anton.warning](anton)[/] ✗ Connection test failed for"
+            f" [bold]{slug}[/bold]."
+        )
+        console.print()
+        console.print(f"        Error: {first_line}")
+    else:
+        console.print(
+            f"[anton.success]        ✓ Connection test passed for"
+            f" [bold]{slug}[/bold]![/]"
+        )
+    console.print()
diff --git a/anton/commands/session.py b/anton/commands/session.py
index 9822daec..7b4d1856 100644
--- a/anton/commands/session.py
+++ b/anton/commands/session.py
@@ -12,9 +12,9 @@
 
 if TYPE_CHECKING:
     from anton.chat import ChatSession
-    from anton.memory.episodes import EpisodicMemory
+    from anton.core.memory.episodes import EpisodicMemory
     from anton.memory.history_store import HistoryStore
-    from anton.memory.cortex import Cortex
+    from anton.core.memory.cortex import Cortex
     from anton.workspace import Workspace
 
 
diff --git a/anton/commands/setup.py b/anton/commands/setup.py
index 3ab1126c..b5be940a 100644
--- a/anton/commands/setup.py
+++ b/anton/commands/setup.py
@@ -10,9 +10,9 @@
 
 if TYPE_CHECKING:
     from anton.chat import ChatSession
-    from anton.memory.episodes import EpisodicMemory
+    from anton.core.memory.episodes import EpisodicMemory
     from anton.memory.history_store import HistoryStore
-    from anton.memory.cortex import Cortex
+    from anton.core.memory.cortex import Cortex
     from anton.workspace import Workspace
 
 
diff --git a/anton/commands/skills.py b/anton/commands/skills.py
new file mode 100644
index 00000000..292c92ef
--- /dev/null
+++ b/anton/commands/skills.py
@@ -0,0 +1,422 @@
+"""Slash-command handlers for the skills system.
+
+Commands:
+
+- `/skill save [optional name hint]` — LLM reads recent scratchpad work +
+  conversation history and drafts a Skill (label, name, when_to_use,
+  declarative procedure). Saved automatically; no interactive editing.
+- `/skills list` — show all saved skills with usage counters.
+- `/skill show <label>` — print a single skill's full procedure + stats.
+- `/skill remove <label>` — delete a skill from disk.
+
+Brain analogue: this is the experience-to-procedure consolidation step.
+The user explicitly marks a successful piece of work as "worth
+remembering as a procedure." The LLM does the synthesis (prefrontal
+cortex deciding what was structural vs. contextual), and the result
+gets written to long-term procedural memory. Future invocations
+retrieve via the recall_skill tool.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.table import Table
+
+from anton.core.memory.skills import (
+    Skill,
+    SkillStats,
+    SkillStore,
+    make_unique_label,
+    slugify,
+)
+
+if TYPE_CHECKING:
+    from anton.core.session import ChatSession
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLM-facing schema (Pydantic) — used by LLMClient.generate_object
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _SkillDraft(BaseModel):
+    """Structured output of the /skill save LLM call.
+
+    The LLM is forced to call a tool whose input matches this schema,
+    so the call site never has to parse JSON or strip fences.
+    """
+
+    label: str = Field(
+        ...,
+        description=(
+            "snake_case identifier for the skill. Short (2-4 words), "
+            "captures the essence. Examples: 'csv_summary', "
+            "'web_scraping', 'api_paginated_fetch'."
+        ),
+    )
+    name: str = Field(
+        ...,
+        description="Human-readable display name (e.g. 'CSV Summary').",
+    )
+    description: str = Field(
+        default="",
+        description="One-sentence description of what the skill does.",
+    )
+    when_to_use: str = Field(
+        ...,
+        description=(
+            "One sentence describing when this skill applies — what the "
+            "user has to ask for. This is the most important field — "
+            "it's what the classifier shows to the LLM next time. "
+            "Specific enough that the LLM can recognize matches "
+            "without being too narrow."
+        ),
+    )
+    declarative_md: str = Field(
+        ...,
+        description=(
+            "Step-by-step procedure as markdown. Numbered steps. Be "
+            "specific about decisions made (which library, why), "
+            "reference the actual approach taken — not generic advice. "
+            "A future agent will read this and follow it on a similar "
+            "but not identical task. Write as instructions for a "
+            "future agent, not a retrospective. Do not invent steps "
+            "that didn't happen."
+        ),
+    )
+
+
+_DRAFT_SYSTEM_PROMPT = (
+    "You are helping a user save a reusable procedure (a 'skill') based on "
+    "work they just completed. You will be given the recent scratchpad "
+    "execution history and the relevant conversation turns. Your job is to "
+    "synthesize them into a step-by-step procedure that a future agent (you) "
+    "can follow when faced with a similar task."
+)
+
+
+_DRAFT_USER_PROMPT_TEMPLATE = """\
+The user just ran the following command and wants to save the underlying procedure as a reusable skill.
+
+{name_hint_section}
+
+## Conversation context (most recent turns)
+
+{conversation}
+
+## Scratchpad execution history
+
+{scratchpad}
+
+---
+
+Synthesize this into a reusable skill following the schema you've been given.
+"""
+
+
+def _format_scratchpad_cells(cells: list) -> str:
+    """Render scratchpad cells as a compact text block for the LLM."""
+    if not cells:
+        return "(no scratchpad work in this session)"
+    chunks: list[str] = []
+    for i, cell in enumerate(cells, 1):
+        code = (getattr(cell, "code", "") or "").strip()
+        stdout = (getattr(cell, "stdout", "") or "").strip()
+        stderr = (getattr(cell, "stderr", "") or "").strip()
+        error = getattr(cell, "error", None)
+        chunks.append(f"### Cell {i}")
+        if code:
+            # Truncate very long cells to keep the prompt manageable
+            code_excerpt = code if len(code) <= 2000 else code[:2000] + "\n... [truncated]"
+            chunks.append("```python")
+            chunks.append(code_excerpt)
+            chunks.append("```")
+        if stdout:
+            stdout_excerpt = stdout if len(stdout) <= 800 else stdout[:800] + "\n... [truncated]"
+            chunks.append("stdout:")
+            chunks.append(stdout_excerpt)
+        if stderr:
+            chunks.append("stderr:")
+            chunks.append(stderr[:400])
+        if error:
+            chunks.append(f"error: {str(error)[:400]}")
+        chunks.append("")
+    return "\n".join(chunks)
+
+
+def _format_history_turns(history: list[dict], *, max_turns: int = 8) -> str:
+    """Render recent conversation history as plain text, skipping tool blocks."""
+    if not history:
+        return "(no conversation history yet)"
+    lines: list[str] = []
+    # Walk backwards collecting up to max_turns user/assistant turns with text
+    collected: list[tuple[str, str]] = []
+    for entry in reversed(history):
+        if not isinstance(entry, dict):
+            continue
+        role = entry.get("role", "")
+        content = entry.get("content", "")
+        text = ""
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            # Extract text blocks from structured content
+            text_parts = []
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    text_parts.append(str(block.get("text", "")))
+            text = "\n".join(text_parts).strip()
+        text = text.strip()
+        if not text:
+            continue
+        if role not in ("user", "assistant"):
+            continue
+        collected.append((role, text))
+        if len(collected) >= max_turns:
+            break
+    if not collected:
+        return "(no readable conversation turns)"
+    # Reverse back to chronological
+    for role, text in reversed(collected):
+        excerpt = text if len(text) <= 1000 else text[:1000] + "\n... [truncated]"
+        lines.append(f"**{role}:** {excerpt}")
+        lines.append("")
+    return "\n".join(lines).strip()
+
+
+def _gather_session_scratchpad_cells(session: "ChatSession") -> list:
+    """Collect cells from every scratchpad in the session."""
+    pads = getattr(session._scratchpads, "_pads", {})
+    out: list = []
+    for pad in pads.values():
+        cells = getattr(pad, "cells", None) or []
+        out.extend(cells)
+    return out
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# /skill save
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+async def handle_skill_save(
+    console: Console,
+    session: "ChatSession",
+    *,
+    name_hint: str = "",
+    store: SkillStore | None = None,
+) -> None:
+    """Draft a skill from recent work and save it to the procedural memory store."""
+    store = store or getattr(session, "_skill_store", None) or SkillStore()
+
+    cells = _gather_session_scratchpad_cells(session)
+    history = getattr(session, "_history", []) or []
+
+    if not cells and not history:
+        console.print()
+        console.print(
+            "[anton.warning](anton)[/] Nothing to save yet — there's no scratchpad work "
+            "or conversation history in this session."
+        )
+        console.print()
+        return
+
+    name_hint_section = (
+        f"The user suggested the name: {name_hint!r}. "
+        "Use it as the basis for `name` and `label`, but you may refine the label "
+        "to be snake_case and short.\n"
+        if name_hint.strip()
+        else ""
+    )
+
+    user_prompt = _DRAFT_USER_PROMPT_TEMPLATE.format(
+        name_hint_section=name_hint_section,
+        conversation=_format_history_turns(history),
+        scratchpad=_format_scratchpad_cells(cells),
+    )
+
+    console.print()
+    console.print("[anton.cyan](anton)[/] Drafting a skill from recent work…")
+
+    try:
+        draft: _SkillDraft = await session._llm.generate_object(
+            _SkillDraft,
+            system=_DRAFT_SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": user_prompt}],
+            max_tokens=1500,
+        )
+    except Exception as exc:
+        console.print()
+        console.print(
+            f"[anton.warning](anton)[/] Couldn't draft the skill: {exc}"
+        )
+        console.print()
+        return
+
+    raw_label = draft.label.strip() or slugify(name_hint or draft.name)
+    name = draft.name.strip() or raw_label.replace("_", " ").title()
+    description = draft.description.strip()
+    when_to_use = draft.when_to_use.strip()
+    declarative_md = draft.declarative_md.strip()
+
+    if not declarative_md:
+        console.print()
+        console.print(
+            "[anton.warning](anton)[/] The drafted skill has no procedure — refusing to save."
+        )
+        console.print()
+        return
+
+    label = make_unique_label(raw_label, store)
+
+    skill = Skill(
+        label=label,
+        name=name,
+        description=description,
+        when_to_use=when_to_use,
+        declarative_md=declarative_md,
+        created_at=datetime.now(timezone.utc).isoformat(),
+        provenance="manual",
+    )
+    path = store.save(skill)
+
+    console.print()
+    console.print(
+        f"[anton.success](anton)[/] Saved skill [bold]{label}[/bold] → {path}"
+    )
+    console.print(f"        [anton.muted]Name:[/] {name}")
+    if when_to_use:
+        console.print(f"        [anton.muted]When to use:[/] {when_to_use}")
+    console.print(
+        "        [anton.muted]Available next session — and via `recall_skill` this turn.[/]"
+    )
+    console.print()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# /skills list
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def handle_skills_list(console: Console, store: SkillStore | None = None) -> None:
+    store = store or SkillStore()
+    skills = store.list_all()
+    console.print()
+    if not skills:
+        console.print(
+            "[anton.muted]No skills saved yet. Use [bold]/skill save[/bold] "
+            "after a successful task to create one.[/]"
+        )
+        console.print()
+        return
+
+    table = Table(title="Procedural memory — saved skills", show_lines=False)
+    table.add_column("Label", style="bold")
+    table.add_column("Name")
+    table.add_column("When to use")
+    table.add_column("Recalls", justify="right")
+    table.add_column("Stages")
+
+    for s in skills:
+        stages = []
+        if s.stage_1_present:
+            stages.append("1")
+        if s.stage_2_present:
+            stages.append("2")
+        if s.stage_3_present:
+            stages.append("3")
+        when = s.when_to_use if len(s.when_to_use) <= 60 else s.when_to_use[:57] + "..."
+        table.add_row(
+            s.label,
+            s.name,
+            when,
+            str(s.stats.total_recalls),
+            ",".join(stages) or "-",
+        )
+
+    console.print(table)
+    console.print()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# /skill show
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def handle_skill_show(
+    console: Console, label: str, store: SkillStore | None = None
+) -> None:
+    store = store or SkillStore()
+    if not label:
+        console.print()
+        console.print("[anton.warning]Usage: /skill show <label>[/]")
+        console.print()
+        return
+    skill = store.load(label)
+    if skill is None:
+        closest = store.closest_match(label)
+        console.print()
+        if closest:
+            console.print(
+                f"[anton.warning]No skill '{label}'. Did you mean '{closest}'?[/]"
+            )
+        else:
+            console.print(f"[anton.warning]No skill named '{label}'.[/]")
+        console.print()
+        return
+
+    console.print()
+    console.print(f"[anton.cyan](anton)[/] [bold]{skill.name}[/]  ([dim]{skill.label}[/])")
+    if skill.description:
+        console.print(f"        {skill.description}")
+    if skill.when_to_use:
+        console.print(f"        [dim]when to use:[/] {skill.when_to_use}")
+    console.print()
+    console.print(
+        f"        [dim]recalls:[/] {skill.stats.total_recalls}  "
+        f"[dim]stage 1:[/] {skill.stats.stage_1.recommended}  "
+        f"[dim]stage 2:[/] {skill.stats.stage_2.recommended}  "
+        f"[dim]stage 3 used:[/] {skill.stats.stage_3.used}"
+    )
+    console.print()
+    console.print(Markdown(skill.declarative_md))
+    console.print()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# /skill remove
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def handle_skill_remove(
+    console: Console, label: str, store: SkillStore | None = None
+) -> None:
+    store = store or SkillStore()
+    if not label:
+        console.print()
+        console.print("[anton.warning]Usage: /skill remove <label>[/]")
+        console.print()
+        return
+    if store.delete(label):
+        console.print()
+        console.print(
+            f"[anton.success](anton)[/] Removed skill [bold]{label}[/bold]."
+        )
+        console.print()
+    else:
+        console.print()
+        console.print(f"[anton.warning]No skill named '{label}'.[/]")
+        console.print()
+
+
+__all__ = [
+    "handle_skill_save",
+    "handle_skill_show",
+    "handle_skill_remove",
+    "handle_skills_list",
+]
diff --git a/anton/commands/ui.py b/anton/commands/ui.py
index f5bcabf6..c07a62b7 100644
--- a/anton/commands/ui.py
+++ b/anton/commands/ui.py
@@ -1,9 +1,11 @@
-"""Slash-command handlers for /theme and /help."""
+"""Slash-command handlers for /theme, /explain, and /help."""
 
 from __future__ import annotations
 
 from rich.console import Console
 
+from anton.explainability import ExplainabilityStore
+
 
 def handle_theme(console: Console, arg: str) -> None:
     """Switch the color theme (light/dark)."""
@@ -17,7 +19,9 @@ def handle_theme(console: Console, arg: str) -> None:
     elif arg in ("light", "dark"):
         new_mode = arg
     else:
-        console.print(f"[anton.warning]Unknown theme '{arg}'. Use: /theme light | /theme dark[/]")
+        console.print(
+            f"[anton.warning]Unknown theme '{arg}'. Use: /theme light | /theme dark[/]"
+        )
         console.print()
         return
 
@@ -37,7 +41,9 @@ def print_slash_help(console: Console) -> None:
     console.print("  [bold]/llm[/]      — Change LLM provider or API key")
 
     console.print("\n[bold]Data Connections[/]")
-    console.print("  [bold]/connect[/]   — Connect a database or API to your Local Vault")
+    console.print(
+        "  [bold]/connect[/]   — Connect a database or API to your Local Vault"
+    )
     console.print("  [bold]/list[/]      — List all saved connections")
     console.print("  [bold]/edit[/]      — Edit credentials for an existing connection")
     console.print("  [bold]/remove[/]    — Remove a saved connection")
@@ -53,9 +59,62 @@ def print_slash_help(console: Console) -> None:
     console.print("  [bold]/resume[/]    — Continue a previous session")
     console.print("  [bold]/publish[/]   — Publish an HTML report to the web")
     console.print("  [bold]/unpublish[/] — Remove a published report")
+    console.print(
+        "  [bold]/explain[/]   — Show explainability details for the latest answer"
+    )
 
     console.print("\n[bold]General[/]")
     console.print("  [bold]/help[/]      — Show this help menu")
     console.print("  [bold]exit[/]       — Exit the chat")
 
     console.print()
+
+
+def handle_explain(console: Console, workspace_path) -> None:
+    """Print explainability details for the latest answer in the workspace."""
+    store = ExplainabilityStore(workspace_path)
+    record = store.load_latest()
+    if record is None:
+        console.print(
+            "[anton.warning]No explainability record found yet for this workspace.[/]"
+        )
+        console.print()
+        return
+
+    console.print()
+    console.print("[anton.cyan]Explain This Answer[/]")
+    console.print(f"[anton.muted]Turn {record.turn} • {record.created_at}[/]")
+    console.print()
+
+    console.print("[bold]Summary[/]")
+    console.print(record.summary or "No summary available.")
+    console.print()
+
+    console.print("[bold]Data Sources Used[/]")
+    if record.data_sources:
+        for source in record.data_sources:
+            engine = source.get("engine")
+            if engine:
+                console.print(f"  - {source.get('name', 'Unknown')} ({engine})")
+            else:
+                console.print(f"  - {source.get('name', 'Unknown')}")
+    else:
+        console.print("  - None captured")
+    console.print()
+
+    console.print("[bold]Generated SQL[/]")
+    if record.sql_queries:
+        for i, query in enumerate(record.sql_queries, 1):
+            header = f"  Query {i}: {query.get('datasource', 'Unknown datasource')}"
+            if query.get("engine"):
+                header += f" ({query['engine']})"
+            console.print(header)
+            console.print("```sql")
+            console.print(query.get("sql", ""))
+            console.print("```")
+            if query.get("status") == "error" and query.get("error_message"):
+                console.print(f"[anton.warning]{query['error_message']}[/]")
+            console.print()
+    else:
+        console.print("  - No SQL generated")
+        console.print()
diff --git a/anton/config/settings.py b/anton/config/settings.py
index c12d9d29..57eb2b68 100644
--- a/anton/config/settings.py
+++ b/anton/config/settings.py
@@ -5,6 +5,8 @@
 from pydantic import PrivateAttr, field_validator
 from pydantic_settings import BaseSettings
 
+from anton.core.settings import CoreSettings
+
 
 def _build_env_files() -> list[str]:
     """Build .env loading chain: cwd/.env -> .anton/.env -> ~/.anton/.env"""
@@ -21,7 +23,7 @@ def _build_env_files() -> list[str]:
 _ENV_FILES = _build_env_files()
 
 
-class AntonSettings(BaseSettings):
+class AntonSettings(CoreSettings):
     model_config = {"env_prefix": "ANTON_", "env_file": _ENV_FILES, "env_file_encoding": "utf-8", "extra": "ignore"}
 
     planning_provider: str = "anthropic"
@@ -40,6 +42,8 @@ class AntonSettings(BaseSettings):
 
     context_dir: str = ".anton/context"
 
+    output_dir: str = ".anton/output"
+
     memory_mode: str = "autopilot"  # autopilot | copilot | off
 
     episodic_memory: bool = True  # episodic memory archive — on by default
@@ -66,7 +70,7 @@ class AntonSettings(BaseSettings):
     minds_datasource_engine: str | None = None
     minds_ssl_verify: bool = True
 
-    # Publish service (anton-services API Gateway)
+    # Publish service
     publish_url: str = "https://4nton.ai"
 
     @field_validator("minds_ssl_verify", mode="before")
@@ -110,3 +114,5 @@ def resolve_workspace(self, folder: str | None = None) -> None:
             self.memory_dir = str(base / self.memory_dir)
         if not Path(self.context_dir).is_absolute():
             self.context_dir = str(base / self.context_dir)
+        if not Path(self.output_dir).is_absolute():
+            self.output_dir = str(base / self.output_dir)
diff --git a/anton/connect_collector.py b/anton/connect_collector.py
new file mode 100644
index 00000000..c209138f
--- /dev/null
+++ b/anton/connect_collector.py
@@ -0,0 +1,273 @@
+"""Smart variable collection for the /connect flow.
+
+Provides:
+- `ConnectionCollector` — a state machine that tracks which credential
+  fields have been filled vs. are still missing for a specific engine.
+- `extract_variables()` — an LLM-driven parser that reads free-form user
+  input and returns (a) the structured variables detected and (b) whether
+  the user is redirecting (changing datasource, cancelling, etc).
+
+The LLM handles all the messy cases naturally: natural language
+("my host is db.example.com"), connection strings
+(`postgres://u:p@host:5432/db`), aliases (pwd→password, hostname→host),
+comma-separated lists, and redirect phrasing ("actually it's mysql").
+
+This mirrors the LLM-returns-JSON pattern already used by
+`handle_add_custom_datasource()` in anton/commands/datasource.py.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+from pydantic import BaseModel, Field
+
+from anton.core.datasources.datasource_registry import (
+    AuthMethod,
+    DatasourceEngine,
+    DatasourceField,
+)
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from anton.core.session import ChatSession
+
+
+@dataclass
+class ExtractedData:
+    """Result of running extract_variables() on a user response."""
+
+    variables: dict[str, str] = field(default_factory=dict)
+    is_redirect: bool = False
+    redirect_engine: str | None = None
+    redirect_reason: str = ""
+
+
+@dataclass
+class ConnectionCollector:
+    """Tracks the puzzle state of a single connection attempt.
+
+    Holds the engine definition and which fields have been filled in so
+    far. Use `fill_many()` to apply extracted variables and the
+    `missing_*` / `is_complete` / `next_field` properties to drive the
+    smart prompt loop.
+    """
+
+    engine_def: DatasourceEngine
+    auth_method: AuthMethod | None = None
+    collected: dict[str, str] = field(default_factory=dict)
+    redirect_message: str = ""
+
+    @property
+    def active_fields(self) -> list[DatasourceField]:
+        if self.auth_method is not None:
+            return self.auth_method.fields
+        return self.engine_def.fields
+
+    @property
+    def field_names(self) -> set[str]:
+        return {f.name for f in self.active_fields}
+
+    @property
+    def missing_required(self) -> list[DatasourceField]:
+        return [
+            f for f in self.active_fields
+            if f.required and not self.collected.get(f.name)
+        ]
+
+    @property
+    def missing_optional(self) -> list[DatasourceField]:
+        return [
+            f for f in self.active_fields
+            if not f.required and not self.collected.get(f.name)
+        ]
+
+    @property
+    def is_complete(self) -> bool:
+        return not self.missing_required
+
+    @property
+    def next_field(self) -> DatasourceField | None:
+        """The next field to ask about — first missing required, else first missing optional."""
+        if self.missing_required:
+            return self.missing_required[0]
+        if self.missing_optional:
+            return self.missing_optional[0]
+        return None
+
+    def fill(self, key: str, value: str) -> bool:
+        """Store value for a field. Returns True if accepted, False if unknown field."""
+        if key not in self.field_names:
+            return False
+        if value:
+            self.collected[key] = value
+        return True
+
+    def fill_many(self, pairs: dict[str, str]) -> list[str]:
+        """Bulk-fill from a dict. Returns list of keys actually accepted."""
+        accepted: list[str] = []
+        for k, v in pairs.items():
+            if self.fill(k, v):
+                accepted.append(k)
+        return accepted
+
+    def format_status(self, console: "Console") -> None:
+        """Print a Rich-formatted summary of what's filled vs. missing."""
+        filled_active = [
+            f.name for f in self.active_fields if self.collected.get(f.name)
+        ]
+        if filled_active:
+            console.print(
+                "        [anton.muted]Filled:[/] " + ", ".join(filled_active)
+            )
+        if self.missing_required:
+            console.print(
+                "        [anton.muted]Still needed:[/] "
+                + ", ".join(f.name for f in self.missing_required)
+            )
+
+    def to_redirect_result(self) -> dict:
+        """Serializable summary for the main agent when the user changes direction."""
+        return {
+            "status": "redirect",
+            "engine": self.engine_def.engine,
+            "engine_display": self.engine_def.display_name,
+            "collected_variables": dict(self.collected),
+            "missing_required": [f.name for f in self.missing_required],
+            "redirect_message": self.redirect_message,
+        }
+
+
+_SYSTEM_PROMPT = (
+    "You extract structured connection credentials from user messages. "
+    "You are helping fill out a form for a specific datasource."
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLM-facing schema (Pydantic) — used by LLMClient.generate_object
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _ExtractionResult(BaseModel):
+    """Structured output of extract_variables.
+
+    The LLM is forced to call a tool whose input matches this schema,
+    so the call site never has to parse JSON, strip markdown fences,
+    or guard against non-dict responses.
+    """
+
+    variables: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            "Mapping of canonical field name (snake_case) to extracted "
+            "value. Only include fields from the expected list above. "
+            "Recognize common aliases (hostname→host, pwd→password, "
+            "db→database, username→user) and map to the canonical name. "
+            "If the user pasted a connection string (e.g. "
+            "postgres://u:p@host:5432/db), extract host/port/user/"
+            "password/database from it. If the user just provided a "
+            "plain value for one field without naming it (e.g. typed "
+            "'localhost' when asked for host), leave this empty — the "
+            "caller will treat the raw text as the next field's value. "
+            "Never invent values."
+        ),
+    )
+    is_redirect: bool = Field(
+        default=False,
+        description=(
+            "True ONLY if the user is clearly trying to cancel or switch "
+            "to a DIFFERENT datasource (e.g. \"actually it's mysql\", "
+            "\"never mind\", \"cancel\"). Providing credentials is NOT "
+            "a redirect."
+        ),
+    )
+    redirect_engine: str = Field(
+        default="",
+        description=(
+            "If the user mentioned a different datasource by name (from "
+            "the 'other known slugs' list), set this to that slug. "
+            "Otherwise empty string."
+        ),
+    )
+    redirect_reason: str = Field(
+        default="",
+        description="Short phrase describing the redirect, or empty string.",
+    )
+
+
+async def extract_variables(
+    raw_input: str,
+    *,
+    expected_fields: list[DatasourceField],
+    current_engine: str,
+    current_engine_display: str,
+    known_engine_slugs: list[str],
+    session: "ChatSession",
+) -> ExtractedData:
+    """Use the LLM to parse free-form user input into connection variables.
+
+    Returns an `ExtractedData` with:
+      - `variables`: field name → value for any credentials detected
+      - `is_redirect`: True if the user is changing direction
+      - `redirect_engine`: the new engine slug if they named one
+      - `redirect_reason`: a short description of the redirect
+
+    Trusts the LLM to handle aliases (hostname→host, pwd→password),
+    connection strings (postgres://user:pass@host:5432/db), natural
+    language ("my host is db.example.com"), and free-form redirect
+    phrasing ("actually let's do mysql instead").
+
+    Uses `LLMClient.generate_object` for forced-schema structured
+    output — no manual JSON parsing or fence stripping. Falls back to
+    an empty result on any LLM/validation error so the caller can
+    treat the raw input as the next field's value.
+    """
+    result = ExtractedData()
+    text = (raw_input or "").strip()
+    if not text:
+        return result
+
+    field_lines = "\n".join(
+        f"  - {f.name}{' (secret)' if f.secret else ''}: "
+        f"{f.description or '(no description)'}"
+        for f in expected_fields
+    )
+    other_engines = ", ".join(s for s in known_engine_slugs if s != current_engine)
+
+    user_prompt = (
+        f"Current datasource: {current_engine_display} (slug: {current_engine})\n"
+        f"Expected fields for this datasource:\n{field_lines}\n\n"
+        f"Other known datasource slugs: {other_engines}\n\n"
+        f"The user was asked to provide credentials and wrote:\n"
+        f"{text!r}\n\n"
+        "Extract any credential values, then determine whether the user is "
+        "trying to redirect to a different datasource."
+    )
+
+    try:
+        extraction: _ExtractionResult = await session._llm.generate_object(
+            _ExtractionResult,
+            system=_SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": user_prompt}],
+            max_tokens=512,
+        )
+    except Exception:
+        return result
+
+    # Filter and normalize variables — only keep keys that match the
+    # expected field list (the LLM might hallucinate field names).
+    valid_names = {f.name for f in expected_fields}
+    for k, v in extraction.variables.items():
+        key = str(k).strip()
+        value = str(v).strip()
+        if key in valid_names and value:
+            result.variables[key] = value
+
+    result.is_redirect = extraction.is_redirect
+    if extraction.redirect_engine.strip():
+        result.redirect_engine = extraction.redirect_engine.strip()
+    result.redirect_reason = extraction.redirect_reason.strip()
+
+    return result
diff --git a/anton/llm/__init__.py b/anton/core/__init__.py
similarity index 100%
rename from anton/llm/__init__.py
rename to anton/core/__init__.py
diff --git a/anton/core/backends/__init__.py b/anton/core/backends/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/anton/core/backends/base.py b/anton/core/backends/base.py
new file mode 100644
index 00000000..c45a1147
--- /dev/null
+++ b/anton/core/backends/base.py
@@ -0,0 +1,251 @@
+"""ScratchpadRuntime ABC — pluggable scratchpad backend contract.
+
+Core interface shared by LocalScratchpadRuntime (CLI) and
+our cloud ScratchpadRuntime (Enterprise).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass
+class Cell:
+    """A single scratchpad execution unit — code in, outputs out."""
+
+    code: str
+    stdout: str
+    stderr: str
+    error: str | None
+    description: str = ""
+    estimated_time: str = ""
+    logs: str = ""
+
+
+class ScratchpadRuntime(ABC):
+    """Abstract base class for scratchpad execution backends.
+
+    Concrete implementations provide a specific execution environment
+    (local venv, Docker container, etc.). The shared display, compaction,
+    and timeout logic lives here so all backends benefit automatically.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        coding_provider: str,
+        coding_model: str,
+        coding_api_key: str,
+        coding_base_url: str,
+        cells: list[Cell] | None = None,
+        workspace_path: Path | None = None,
+    ) -> None:
+        self.name = name
+        self._coding_provider = coding_provider
+        self._coding_model = coding_model
+        self._coding_api_key = coding_api_key
+        self._coding_base_url = coding_base_url
+        self.cells: list[Cell] = cells if cells is not None else []
+        self._workspace_path = workspace_path or Path("~/.anton").expanduser()
+        self._installed_packages: set[str] = set()
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Launch the runtime environment."""
+
+    @abstractmethod
+    async def reset(self) -> None:
+        """Kill the runtime, clear cells, and restart."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Shut down the runtime, preserving any persistent resources."""
+
+    @abstractmethod
+    async def cancel(self) -> None:
+        """Cancel the currently running cell and restart the runtime."""
+
+    @abstractmethod
+    async def install_packages(self, packages: list[str]) -> str:
+        """Install Python packages into the runtime environment."""
+
+    @abstractmethod
+    async def execute_streaming(
+        self,
+        code: str,
+        *,
+        description: str = "",
+        estimated_time: str = "",
+        estimated_seconds: int = 0,
+    ):
+        """Execute code and yield progress strings then a final Cell."""
+
+    @abstractmethod
+    async def cleanup(self) -> None:
+        """Release all backend-specific resources (venv dir, containers, etc.).
+
+        Called by ScratchpadManager.remove() to fully destroy this runtime.
+        Unlike close(), cleanup() removes persistent storage too.
+        """
+
+    async def execute(
+        self,
+        code: str,
+        *,
+        description: str = "",
+        estimated_time: str = "",
+        estimated_seconds: int = 0,
+    ) -> Cell:
+        """Drain execute_streaming() and return just the final Cell."""
+        async for item in self.execute_streaming(
+            code,
+            description=description,
+            estimated_time=estimated_time,
+            estimated_seconds=estimated_seconds,
+        ):
+            if isinstance(item, Cell):
+                return item
+        return Cell(code=code, stdout="", stderr="", error="No result produced.")
+
+    def view(self) -> str:
+        """Format all cells with their outputs for LLM consumption."""
+        if not self.cells:
+            return f"Scratchpad '{self.name}' is empty."
+
+        parts: list[str] = []
+        for i, cell in enumerate(self.cells):
+            header = f"--- Cell {i + 1}"
+            if cell.description:
+                header += f": {cell.description}"
+            header += " ---"
+            parts.append(header)
+            parts.append(cell.code)
+            if cell.stdout:
+                parts.append(f"[output]\n{cell.stdout}")
+            if cell.logs:
+                parts.append(f"[logs]\n{cell.logs}")
+            if cell.stderr:
+                parts.append(f"[stderr]\n{cell.stderr}")
+            if cell.error:
+                parts.append(f"[error]\n{cell.error}")
+            if not cell.stdout and not cell.logs and not cell.stderr and not cell.error:
+                parts.append("(no output)")
+        return "\n".join(parts)
+
+    def render_notebook(self) -> str:
+        """Return a clean markdown notebook-style summary of all cells."""
+        numbered: list[tuple[int, Cell]] = []
+        idx = 0
+        for cell in self.cells:
+            idx += 1
+            if not cell.code.strip():
+                continue
+            numbered.append((idx, cell))
+
+        if not numbered:
+            return f"Scratchpad '{self.name}' has no cells."
+
+        parts: list[str] = [f"## Scratchpad: {self.name} ({len(numbered)} cells)"]
+
+        for i, (num, cell) in enumerate(numbered):
+            header = f"\n### Cell {num}"
+            if cell.description:
+                header += f" \u2014 {cell.description}"
+            parts.append(header)
+            parts.append(f"```python\n{cell.code}\n```\n")
+
+            if cell.error:
+                last_line = cell.error.strip().split("\n")[-1]
+                parts.append(f"**Error:** `{last_line}`")
+                if cell.stdout:
+                    truncated = self._truncate_output(cell.stdout.rstrip("\n"))
+                    parts.append(f"**Partial output:**\n```\n{truncated}\n```\n")
+            elif cell.stdout:
+                truncated = self._truncate_output(cell.stdout.rstrip("\n"))
+                parts.append(f"**Output:**\n```\n{truncated}\n```\n")
+
+            if cell.logs:
+                truncated_logs = self._truncate_output(
+                    cell.logs.rstrip("\n"), max_lines=10, max_chars=1000
+                )
+                parts.append(f"**Logs:**\n```\n{truncated_logs}\n```\n")
+
+            if i < len(numbered) - 1:
+                parts.append("---")
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def _truncate_output(text: str, max_lines: int = 20, max_chars: int = 2000) -> str:
+        """Truncate output to max_lines / max_chars, whichever is shorter."""
+        lines = text.split("\n")
+        if len(lines) > max_lines:
+            kept = "\n".join(lines[:max_lines])
+            remaining = len(lines) - max_lines
+            return kept + f"\n... ({remaining} more lines)"
+        if len(text) > max_chars:
+            total = 0
+            kept_lines: list[str] = []
+            for line in lines:
+                if total + len(line) + 1 > max_chars and kept_lines:
+                    break
+                kept_lines.append(line)
+                total += len(line) + 1
+            return "\n".join(kept_lines) + "\n... (truncated)"
+        return text
+
+    def _compact_cells(self) -> bool:
+        """Collapse old cells into a summary cell to reduce context size.
+
+        Keeps the most recent settings.cell_keep_recent cells intact. Returns
+        True if compaction actually happened.
+        """
+        from anton.core.settings import CoreSettings
+
+        keep = CoreSettings().cell_keep_recent
+        if len(self.cells) <= keep + 1:
+            return False
+
+        to_compact = self.cells[:-keep]
+        recent = self.cells[-keep:]
+
+        summary_lines: list[str] = []
+        for i, cell in enumerate(to_compact, 1):
+            status = "error" if cell.error else "ok"
+            desc = cell.description or f"Cell {i}"
+            first_line = ""
+            output = cell.stdout or cell.error or ""
+            if output:
+                first_line = output.strip().split("\n")[0][:120]
+            summary_lines.append(f"  [{status}] {desc}: {first_line}")
+
+        summary_text = f"# Compacted {len(to_compact)} earlier cells:\n" + "\n".join(
+            summary_lines
+        )
+        summary_cell = Cell(
+            code="# (compacted — see summary above)",
+            stdout=summary_text,
+            stderr="",
+            error=None,
+            description=f"Summary of cells 1–{len(to_compact)}",
+        )
+        self.cells = [summary_cell] + recent
+        return True
+
+
+class ScratchpadRuntimeFactory(Protocol):
+    def __call__(
+        self,
+        *,
+        name: str,
+        cells: list[Cell] | None,
+        coding_provider: str,
+        coding_model: str,
+        coding_api_key: str,
+        coding_base_url: str,
+        workspace_path: Path | None,
+    ) -> ScratchpadRuntime: ...
\ No newline at end of file
diff --git a/anton/core/backends/local.py b/anton/core/backends/local.py
new file mode 100644
index 00000000..66020742
--- /dev/null
+++ b/anton/core/backends/local.py
@@ -0,0 +1,693 @@
+"""LocalScratchpadRuntime — venv-based scratchpad for the CLI."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import sys
+import tempfile
+import venv
+from pathlib import Path
+
+from anton.core.backends.base import Cell, ScratchpadRuntime
+from anton.core.backends.wire import (
+    CELL_DELIM,
+    PROGRESS_MARKER,
+    RESULT_END,
+    RESULT_START,
+)
+from anton.core.settings import CoreSettings
+from anton.core.backends.utils import compute_timeouts
+
+_BOOT_SCRIPT_PATH = Path(__file__).parent / "scratchpad_boot.py"
+_MAX_OUTPUT = 10_000
+
+
+class LocalScratchpadRuntime(ScratchpadRuntime):
+    """Runs scratchpad cells in a persistent per-named venv subprocess."""
+
+    _MAX_VENV_RETRIES = 3
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        coding_provider: str,
+        coding_model: str,
+        coding_api_key: str,
+        coding_base_url: str,
+        cells: list[Cell] | None = None,
+        workspace_path: Path | None = None,
+        _venvs_base: Path | None = None,
+    ) -> None:
+        super().__init__(
+            name,
+            coding_provider=coding_provider,
+            coding_model=coding_model,
+            coding_api_key=coding_api_key,
+            coding_base_url=coding_base_url,
+            cells=cells,
+            workspace_path=workspace_path,
+        )
+        self._proc: asyncio.subprocess.Process | None = None
+        self._boot_path: str | None = None
+        self._venv_dir: str | None = None
+        self._venv_python: str | None = None
+        if _venvs_base is not None:
+            self._venvs_base = _venvs_base
+        elif workspace_path is not None:
+            self._venvs_base = workspace_path / ".anton" / "scratchpad-venvs"
+        else:
+            self._venvs_base = Path("~/.anton/scratchpad-venvs").expanduser()
+
+    def _ensure_venv(self) -> None:
+        if self._venv_dir is not None and self._verify_venv_python():
+            return
+
+        venv_path = self._venvs_base / self.name
+        if venv_path.is_dir() and self._try_recycle_venv(venv_path):
+            return
+
+        if venv_path.is_dir():
+            self._nuke_venv()
+
+        last_error: Exception | None = None
+        for attempt in range(1, self._MAX_VENV_RETRIES + 1):
+            try:
+                self._create_venv()
+                if self._verify_venv_python():
+                    self._setup_parent_site_packages()
+                    self._save_python_version()
+                    return
+                raise RuntimeError(
+                    f"venv Python binary at {self._venv_python} is not functional"
+                )
+            except Exception as exc:
+                last_error = exc
+                self._nuke_venv()
+
+        raise RuntimeError(
+            f"Failed to create a working Python venv after {self._MAX_VENV_RETRIES} "
+            f"attempts. Last error: {last_error}. "
+            f"Try running: python3 -c 'print(\"ok\")' to verify your Python installation."
+        )
+
+    @staticmethod
+    def _find_uv() -> str | None:
+        uv = shutil.which("uv")
+        if uv:
+            return uv
+        if sys.platform == "win32":
+            candidates = (
+                os.path.expanduser("~/.local/bin/uv.exe"),
+                os.path.expanduser("~/.cargo/bin/uv.exe"),
+            )
+        else:
+            candidates = (
+                os.path.expanduser("~/.local/bin/uv"),
+                os.path.expanduser("~/.cargo/bin/uv"),
+            )
+        for candidate in candidates:
+            if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+                return candidate
+        return None
+
+    def _create_venv(self) -> None:
+        import subprocess as _sp
+
+        self._venv_dir = str(self._venvs_base / self.name)
+        os.makedirs(self._venv_dir, exist_ok=True)
+
+        uv = self._find_uv()
+        if uv:
+            _sp.run(
+                [
+                    uv,
+                    "venv",
+                    self._venv_dir,
+                    "--python",
+                    sys.executable,
+                    "--system-site-packages",
+                    "--seed",
+                    "--quiet",
+                ],
+                check=True,
+                capture_output=True,
+                timeout=30,
+            )
+        else:
+            venv.create(
+                self._venv_dir,
+                system_site_packages=True,
+                with_pip=False,
+                clear=True,
+            )
+
+        if sys.platform == "win32":
+            bin_dir = os.path.join(self._venv_dir, "Scripts")
+            self._venv_python = os.path.join(bin_dir, "python.exe")
+            self._add_windows_firewall_rule()
+        else:
+            bin_dir = os.path.join(self._venv_dir, "bin")
+            self._venv_python = os.path.join(bin_dir, "python")
+
+    def _verify_venv_python(self) -> bool:
+        if self._venv_python is None:
+            return False
+        if not os.path.exists(self._venv_python):
+            return False
+        try:
+            import subprocess
+
+            result = subprocess.run(
+                [self._venv_python, "-c", "print('ok')"],
+                capture_output=True,
+                timeout=5,
+            )
+            return result.returncode == 0 and "ok" in result.stdout.decode()
+        except Exception:
+            return False
+
+    def _nuke_venv(self) -> None:
+        if self._venv_dir is not None:
+            try:
+                shutil.rmtree(self._venv_dir)
+            except OSError:
+                pass
+        self._venv_dir = None
+        self._venv_python = None
+
+    def _add_windows_firewall_rule(self) -> None:
+        if self._venv_python is None or not os.path.isfile(self._venv_python):
+            return
+        import subprocess as _sp
+
+        rule_name = f"Anton Scratchpad - {self.name}"
+        try:
+            _sp.run(
+                [
+                    "netsh",
+                    "advfirewall",
+                    "firewall",
+                    "add",
+                    "rule",
+                    f"name={rule_name}",
+                    "dir=out",
+                    "action=allow",
+                    f"program={self._venv_python}",
+                ],
+                capture_output=True,
+                timeout=10,
+            )
+        except Exception:
+            pass
+        self._installed_packages.clear()
+
+    def _setup_parent_site_packages(self) -> None:
+        if sys.prefix != sys.base_prefix:
+            import site as _site
+
+            parent_site = _site.getsitepackages()
+            child_site = None
+            for dirpath, dirnames, _ in os.walk(self._venv_dir):
+                if "site-packages" in dirnames:
+                    child_site = os.path.join(dirpath, "site-packages")
+                    break
+            if child_site and parent_site:
+                pth_path = os.path.join(child_site, "_parent_venv.pth")
+                with open(pth_path, "w") as f:
+                    for sp in parent_site:
+                        f.write(sp + "\n")
+
+    def _try_recycle_venv(self, venv_path: Path) -> bool:
+        try:
+            self._venv_dir = str(venv_path)
+            if sys.platform == "win32":
+                self._venv_python = os.path.join(
+                    self._venv_dir, "Scripts", "python.exe"
+                )
+            else:
+                self._venv_python = os.path.join(self._venv_dir, "bin", "python")
+
+            if not self._verify_venv_python():
+                return False
+            if not self._check_python_version():
+                return False
+            self._load_requirements()
+            self._setup_parent_site_packages()
+            return True
+        except Exception:
+            return False
+
+    def _save_requirements(self) -> None:
+        if not self._venv_dir or not self._installed_packages:
+            return
+        try:
+            req_path = os.path.join(self._venv_dir, "requirements.txt")
+            with open(req_path, "w") as f:
+                for pkg in sorted(self._installed_packages):
+                    f.write(pkg + "\n")
+        except OSError:
+            pass
+
+    def _load_requirements(self) -> None:
+        if not self._venv_dir:
+            return
+        req_path = os.path.join(self._venv_dir, "requirements.txt")
+        try:
+            with open(req_path) as f:
+                for line in f:
+                    pkg = line.strip()
+                    if pkg:
+                        self._installed_packages.add(pkg)
+        except FileNotFoundError:
+            pass
+
+    def _save_python_version(self) -> None:
+        if not self._venv_dir:
+            return
+        try:
+            ver_path = os.path.join(self._venv_dir, ".python_version")
+            with open(ver_path, "w") as f:
+                f.write(f"{sys.version_info.major}.{sys.version_info.minor}\n")
+        except OSError:
+            pass
+
+    def _check_python_version(self) -> bool:
+        if not self._venv_dir:
+            return False
+        ver_path = os.path.join(self._venv_dir, ".python_version")
+        try:
+            with open(ver_path) as f:
+                saved = f.read().strip()
+            expected = f"{sys.version_info.major}.{sys.version_info.minor}"
+            return saved == expected
+        except FileNotFoundError:
+            return False
+
+    async def start(self) -> None:
+        """Write the boot script to a temp file and launch the subprocess."""
+        self._ensure_venv()
+
+        boot_code = _BOOT_SCRIPT_PATH.read_text()
+        fd, path = tempfile.mkstemp(suffix=".py", prefix="anton_scratchpad_")
+        os.write(fd, boot_code.encode())
+        os.close(fd)
+        self._boot_path = path
+
+        env = os.environ.copy()
+        if self._coding_model:
+            env["ANTON_SCRATCHPAD_MODEL"] = self._coding_model
+        if self._coding_provider:
+            env["ANTON_SCRATCHPAD_PROVIDER"] = self._coding_provider
+        if "ANTHROPIC_API_KEY" not in env and "ANTON_ANTHROPIC_API_KEY" in env:
+            env["ANTHROPIC_API_KEY"] = env["ANTON_ANTHROPIC_API_KEY"]
+        if "OPENAI_API_KEY" not in env and "ANTON_OPENAI_API_KEY" in env:
+            env["OPENAI_API_KEY"] = env["ANTON_OPENAI_API_KEY"]
+        if "OPENAI_BASE_URL" not in env and "ANTON_OPENAI_BASE_URL" in env:
+            env["OPENAI_BASE_URL"] = env["ANTON_OPENAI_BASE_URL"]
+        if (
+            "OPENAI_API_KEY" not in env
+            and "ANTON_MINDS_API_KEY" in env
+            and self._coding_provider == "openai-compatible"
+        ):
+            env["OPENAI_API_KEY"] = env["ANTON_MINDS_API_KEY"]
+        if (
+            "OPENAI_BASE_URL" not in env
+            and "ANTON_MINDS_URL" in env
+            and self._coding_provider == "openai-compatible"
+        ):
+            env["OPENAI_BASE_URL"] = f"{env['ANTON_MINDS_URL'].rstrip('/')}/api/v1"
+        if self._coding_api_key:
+            sdk_key = {
+                "anthropic": "ANTHROPIC_API_KEY",
+                "openai": "OPENAI_API_KEY",
+                "openai-compatible": "OPENAI_API_KEY",
+            }.get(self._coding_provider, "")
+            if sdk_key:
+                env[sdk_key] = self._coding_api_key
+        if self._coding_provider in ("openai", "openai-compatible"):
+            base_url = (
+                self._coding_base_url
+                or env.get("ANTON_OPENAI_BASE_URL")
+                or env.get("OPENAI_BASE_URL")
+                or ""
+            )
+            if base_url:
+                env["OPENAI_BASE_URL"] = base_url
+                env["ANTON_OPENAI_BASE_URL"] = base_url
+        uv = self._find_uv()
+        if uv:
+            env["ANTON_UV_PATH"] = uv
+
+        _anton_root = str(Path(__file__).resolve().parent.parent.parent.parent)
+        python_path = env.get("PYTHONPATH", "")
+        if _anton_root not in python_path:
+            env["PYTHONPATH"] = _anton_root + (
+                os.pathsep + python_path if python_path else ""
+            )
+
+        try:
+            self._proc = await asyncio.create_subprocess_exec(
+                self._venv_python,
+                path,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+                start_new_session=(sys.platform != "win32"),
+            )
+        except (FileNotFoundError, PermissionError, OSError) as exc:
+            self._nuke_venv()
+            raise RuntimeError(
+                f"Failed to start scratchpad: {exc}. "
+                "The Python venv has been deleted and will be recreated on next attempt."
+            ) from exc
+
+    async def reset(self) -> None:
+        """Kill the process, clear cells, and restart."""
+        await self._stop_process()
+        self.cells.clear()
+        if not self._verify_venv_python():
+            self._nuke_venv()
+        await self.start()
+
+    async def close(self) -> None:
+        """Kill the process and save requirements; preserve the venv."""
+        await self._stop_process()
+        if self._venv_dir is not None:
+            self._save_requirements()
+            self._venv_dir = None
+            self._venv_python = None
+
+    async def cancel(self) -> None:
+        """Kill the current cell and restart the runtime."""
+        if self._proc is None or self._proc.returncode is not None:
+            return
+        self._kill_tree()
+        try:
+            await asyncio.wait_for(self._proc.wait(), timeout=5)
+        except asyncio.TimeoutError:
+            pass
+        self.cells.append(
+            Cell(
+                code="# (cancelled by user)",
+                stdout="",
+                stderr="",
+                error="Cancelled by user.",
+                description="Cancelled",
+            )
+        )
+        self._proc = None
+        await self.start()
+
+    async def cleanup(self) -> None:
+        """Kill process and delete the venv entirely."""
+        await self._stop_process()
+        self._nuke_venv()
+
+    async def execute_streaming(
+        self,
+        code: str,
+        *,
+        description: str = "",
+        estimated_time: str = "",
+        estimated_seconds: int = 0,
+    ):
+        """Async generator: yields progress strings then a final Cell."""
+        if self._proc is None or self._proc.returncode is not None:
+            yield Cell(
+                code=code,
+                stdout="",
+                stderr="",
+                error="Scratchpad process is not running. Use reset to restart.",
+                description=description,
+                estimated_time=estimated_time,
+            )
+            return
+
+        payload = code + "\n" + CELL_DELIM + "\n"
+        self._proc.stdin.write(payload.encode())  # type: ignore[union-attr]
+        await self._proc.stdin.drain()  # type: ignore[union-attr]
+
+        total_timeout, inactivity_timeout = compute_timeouts(estimated_seconds)
+
+        try:
+            result_data: dict | None = None
+            async for item in self._read_result(
+                total_timeout=total_timeout,
+                inactivity_timeout=inactivity_timeout,
+            ):
+                if isinstance(item, str):
+                    yield item
+                else:
+                    result_data = item
+        except (asyncio.TimeoutError, asyncio.CancelledError) as exc:
+            self._kill_tree()
+            try:
+                await asyncio.wait_for(self._proc.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                pass
+            error_msg = (
+                f"{exc}. Process killed — state lost. Use reset to restart.\n\n"
+                "If a database query was running, it may still be executing server-side.\n"
+                "To check and cancel: run SHOW PROCESSLIST (MySQL) or\n"
+                "SELECT * FROM information_schema.processlist WHERE status='running' "
+                "and cancel with KILL <id>.\n"
+                "For Snowflake: use SHOW RUNNING QUERIES and "
+                "SELECT SYSTEM$CANCEL_ALL_QUERIES(<session_id>)."
+            )
+            cell = Cell(
+                code=code,
+                stdout="",
+                stderr="",
+                error=error_msg,
+                description=description,
+                estimated_time=estimated_time,
+            )
+            self.cells.append(cell)
+            yield cell
+            return
+        except Exception as exc:
+            cell = Cell(
+                code=code,
+                stdout="",
+                stderr="",
+                error=(
+                    f"Scratchpad result could not be read: {exc}. "
+                    "The scratchpad is still running — you can retry."
+                ),
+                description=description,
+                estimated_time=estimated_time,
+            )
+            self.cells.append(cell)
+            yield cell
+            return
+
+        if result_data is None:
+            result_data = {
+                "stdout": "",
+                "stderr": "",
+                "error": "Process exited unexpectedly.",
+            }
+
+        for pkg in result_data.get("auto_installed") or []:
+            self._installed_packages.add(pkg.lower())
+
+        cell = Cell(
+            code=code,
+            stdout=result_data.get("stdout", ""),
+            stderr=result_data.get("stderr", ""),
+            error=result_data.get("error"),
+            description=description,
+            estimated_time=estimated_time,
+            logs=result_data.get("logs", ""),
+        )
+        self.cells.append(cell)
+        yield cell
+
+    async def _read_result(
+        self,
+        *,
+        total_timeout: float | None = None,
+        inactivity_timeout: float | None = None,
+    ):
+        """Read stdout until result delimiters; yield progress strings then dict."""
+        import time as _time
+
+        s = CoreSettings()
+        if total_timeout is None:
+            total_timeout = float(s.cell_timeout_default)
+        if inactivity_timeout is None:
+            inactivity_timeout = float(s.cell_inactivity_timeout)
+
+        lines: list[str] = []
+        in_result = False
+        start = _time.monotonic()
+        current_inactivity = inactivity_timeout
+
+        while True:
+            elapsed = _time.monotonic() - start
+            remaining_total = total_timeout - elapsed
+            if remaining_total <= 0:
+                raise asyncio.TimeoutError(
+                    f"Cell timed out after {total_timeout:.0f}s total"
+                )
+
+            line_timeout = min(current_inactivity, remaining_total)
+            try:
+                raw = await asyncio.wait_for(
+                    self._proc.stdout.readline(),  # type: ignore[union-attr]
+                    timeout=line_timeout,
+                )
+            except asyncio.TimeoutError:
+                elapsed_now = _time.monotonic() - start
+                if elapsed_now >= total_timeout - 0.5:
+                    raise asyncio.TimeoutError(
+                        f"Cell timed out after {total_timeout:.0f}s total"
+                    ) from None
+                raise asyncio.TimeoutError(
+                    f"Cell killed after {current_inactivity:.0f}s of inactivity "
+                    "(no output or progress() calls)"
+                ) from None
+
+            if not raw:
+                yield {
+                    "stdout": "",
+                    "stderr": "",
+                    "error": "Process exited unexpectedly.",
+                }
+                return
+
+            line = raw.decode().rstrip("\r\n")
+
+            if line.startswith(PROGRESS_MARKER):
+                current_inactivity = max(
+                    current_inactivity, float(s.cell_inactivity_after_progress)
+                )
+                message = line[len(PROGRESS_MARKER) :].strip()
+                yield message
+                continue
+
+            if line == RESULT_START:
+                in_result = True
+                continue
+            if line == RESULT_END:
+                break
+            if in_result:
+                lines.append(line)
+
+        raw_text = "\n".join(lines)
+        try:
+            yield json.loads(raw_text)
+        except json.JSONDecodeError:
+            try:
+                start_idx = raw_text.index("{")
+                end_idx = raw_text.rindex("}") + 1
+                yield json.loads(raw_text[start_idx:end_idx])
+            except (ValueError, json.JSONDecodeError):
+                yield {
+                    "stdout": raw_text,
+                    "stderr": "",
+                    "logs": "",
+                    "error": "Scratchpad result was malformed (JSON parse failed). "
+                    "Output above may be partial.",
+                }
+
+    async def install_packages(self, packages: list[str]) -> str:
+        if not packages:
+            return "No packages specified."
+        needed = [p for p in packages if p.lower() not in self._installed_packages]
+        if not needed:
+            return "All packages already installed."
+        self._ensure_venv()
+
+        uv = self._find_uv()
+        if uv:
+            cmd = [uv, "pip", "install", "--python", self._venv_python, *needed]
+        else:
+            cmd = [self._venv_python, "-m", "pip", "install", "--no-input", *needed]
+
+        _install_timeout = CoreSettings().cell_install_timeout
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+        try:
+            stdout, _ = await asyncio.wait_for(
+                proc.communicate(), timeout=_install_timeout
+            )
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+            return f"Install timed out after {_install_timeout}s."
+        output = stdout.decode()
+        if proc.returncode != 0:
+            return f"Install failed (exit {proc.returncode}):\n{output}"
+        for p in needed:
+            self._installed_packages.add(p.lower())
+        return output
+
+    async def _stop_process(self) -> None:
+        if self._proc is not None and self._proc.returncode is None:
+            try:
+                self._kill_tree()
+                await asyncio.wait_for(self._proc.wait(), timeout=5)
+            except (ProcessLookupError, asyncio.TimeoutError):
+                pass
+        if self._proc is not None:
+            pipe = self._proc.stdin
+            if pipe is not None:
+                if hasattr(pipe, "is_closing"):
+                    if not pipe.is_closing():
+                        pipe.close()
+                else:
+                    pipe.close()
+        self._proc = None
+        if self._boot_path is not None:
+            try:
+                os.unlink(self._boot_path)
+            except OSError:
+                pass
+            self._boot_path = None
+
+    def _kill_tree(self) -> None:
+        if self._proc is None or self._proc.returncode is not None:
+            return
+        pid = self._proc.pid
+        if sys.platform != "win32":
+            import signal
+
+            try:
+                os.killpg(pid, signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                try:
+                    self._proc.kill()
+                except ProcessLookupError:
+                    pass
+        else:
+            self._proc.kill()
+
+
+def local_scratchpad_runtime_factory(
+    *,
+    name: str,
+    coding_provider: str,
+    coding_model: str,
+    coding_api_key: str,
+    coding_base_url: str,
+    cells: list[Cell] | None,
+    workspace_path: Path | None,
+) -> ScratchpadRuntime:
+    return LocalScratchpadRuntime(
+        name=name,
+        coding_provider=coding_provider,
+        coding_model=coding_model,
+        coding_api_key=coding_api_key,
+        coding_base_url=coding_base_url,
+        cells=cells,
+        workspace_path=workspace_path,
+    )
diff --git a/anton/core/backends/manager.py b/anton/core/backends/manager.py
new file mode 100644
index 00000000..f1d7d7fe
--- /dev/null
+++ b/anton/core/backends/manager.py
@@ -0,0 +1,86 @@
+"""ScratchpadManager — lifecycle manager for named scratchpad runtimes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from anton.core.backends.base import Cell, ScratchpadRuntime, ScratchpadRuntimeFactory
+
+
+class ScratchpadManager:
+    """Manages named scratchpad runtime instances."""
+
+    def __init__(
+        self,
+        runtime_factory: ScratchpadRuntimeFactory,
+        coding_provider: str,
+        coding_model: str,
+        coding_api_key: str,
+        coding_base_url: str,
+        cells: list[Cell] | None = None,
+        workspace_path: Path | None = None,
+    ) -> None:
+        self._pads: dict[str, ScratchpadRuntime] = {}
+        self._runtime_factory = runtime_factory
+        self._coding_provider = coding_provider
+        self._coding_model = coding_model
+        self._coding_api_key = coding_api_key
+        self._coding_base_url = coding_base_url
+        self._cells = cells
+        self._workspace_path = workspace_path
+        self._available_packages: list[str] = self.probe_packages()
+
+    @property
+    def pads(self) -> dict[str, ScratchpadRuntime]:
+        """Read-only view of the active scratchpad runtimes."""
+        return self._pads
+
+    @property
+    def available_packages(self) -> list[str]:
+        """Sorted list of installed package distribution names."""
+        return self._available_packages
+
+    @staticmethod
+    def probe_packages() -> list[str]:
+        """Return sorted list of installed package distribution names."""
+        from importlib.metadata import distributions
+
+        return sorted({d.metadata["Name"] for d in distributions()})
+
+    async def get_or_create(self, name: str) -> ScratchpadRuntime:
+        """Return existing pad or create + start a new one."""
+        if name not in self._pads:
+            pad = self._runtime_factory(
+                name=name,
+                cells=self._cells,
+                coding_provider=self._coding_provider,
+                coding_model=self._coding_model,
+                coding_api_key=self._coding_api_key,
+                coding_base_url=self._coding_base_url,
+                workspace_path=self._workspace_path,
+            )
+            await pad.start()
+            self._pads[name] = pad
+        return self._pads[name]
+
+    async def remove(self, name: str) -> str:
+        """Kill and fully delete a scratchpad (including its persistent venv)."""
+        pad = self._pads.pop(name, None)
+        if pad is None:
+            return f"No scratchpad named '{name}'."
+        await pad.cleanup()
+        return f"Scratchpad '{name}' removed."
+
+    def list_pads(self) -> list[str]:
+        return list(self._pads.keys())
+
+    async def cancel_all_running(self) -> None:
+        """Cancel running executions in all scratchpads and restart them."""
+        for pad in self._pads.values():
+            await pad.cancel()
+
+    async def close_all(self) -> None:
+        """Cleanup all scratchpads on session end."""
+        for pad in self._pads.values():
+            await pad.close()
+        self._pads.clear()
diff --git a/anton/scratchpad_boot.py b/anton/core/backends/scratchpad_boot.py
similarity index 73%
rename from anton/scratchpad_boot.py
rename to anton/core/backends/scratchpad_boot.py
index f3267548..46a19aa3 100644
--- a/anton/scratchpad_boot.py
+++ b/anton/core/backends/scratchpad_boot.py
@@ -4,12 +4,53 @@
 import sys
 import traceback
 
-_CELL_DELIM = "__ANTON_CELL_END__"
-_RESULT_START = "__ANTON_RESULT__"
-_RESULT_END = "__ANTON_RESULT_END__"
+import dill
+
+from anton.core.backends.wire import (
+    CELL_DELIM,
+    RESULT_START,
+    RESULT_END,
+)
+
+
+# --- Python session persistence and namespace injection ---
+PERSIST_SESSION = os.environ.get("ANTON_SCRATCHPAD_PERSIST_SESSION", "false").lower() in {"1", "true", "yes", "on"}
+SESSION_PATH = os.environ.get("ANTON_SCRATCHPAD_SESSION_PATH", "/anton_scratchpad_session.pkl")
+
+
+def _load_namespace() -> tuple[dict, str | None]:
+    if not PERSIST_SESSION:
+        return {"__builtins__": __builtins__}, None
+    try:
+        with open(SESSION_PATH, "rb") as f:
+            ns = dill.load(f)
+        if not isinstance(ns, dict):
+            raise TypeError("Session file did not contain a namespace dict")
+        ns.setdefault("__builtins__", __builtins__)
+        return ns, None
+    except FileNotFoundError:
+        return {"__builtins__": __builtins__}, None
+    except Exception:
+        return (
+            {"__builtins__": __builtins__},
+            "Failed to load scratchpad session; starting fresh.\n" + traceback.format_exc(),
+        )
+
+
+def _dump_namespace(ns: dict) -> str | None:
+    if not PERSIST_SESSION:
+        return None
+    try:
+        with open(SESSION_PATH, "wb") as f:
+            dill.dump(ns, f)
+        return None
+    except Exception:
+        return "Failed to dump scratchpad session.\n" + traceback.format_exc()
+
 
 # Persistent namespace across cells
-namespace = {"__builtins__": __builtins__}
+namespace, _ = _load_namespace()
+namespace["_anton_explainability_queries"] = []
 
 # --- Inject get_llm() for LLM access from scratchpad code ---
 _scratchpad_model = os.environ.get("ANTON_SCRATCHPAD_MODEL", "")
@@ -17,19 +58,27 @@
     try:
         import asyncio as _llm_asyncio
 
-        _scratchpad_provider_name = os.environ.get("ANTON_SCRATCHPAD_PROVIDER", "anthropic")
+        _scratchpad_provider_name = os.environ.get(
+            "ANTON_SCRATCHPAD_PROVIDER", "anthropic"
+        )
         if _scratchpad_provider_name in ("openai", "openai-compatible"):
-            from anton.llm.openai import OpenAIProvider as _ProviderClass
+            from anton.core.llm.openai import OpenAIProvider as _ProviderClass
         else:
-            from anton.llm.anthropic import AnthropicProvider as _ProviderClass
+            from anton.core.llm.anthropic import AnthropicProvider as _ProviderClass
 
-        _llm_ssl_verify = os.environ.get("ANTON_MINDS_SSL_VERIFY", "true").lower() != "false"
+        _llm_ssl_verify = (
+            os.environ.get("ANTON_MINDS_SSL_VERIFY", "true").lower() != "false"
+        )
         if _scratchpad_provider_name in ("openai", "openai-compatible"):
             # Explicitly pass base_url so Minds/openai-compatible endpoints work.
             # The OpenAI SDK may or may not pick up OPENAI_BASE_URL from env,
             # so we pass it directly to be safe.
-            _llm_base_url = os.environ.get("OPENAI_BASE_URL") or os.environ.get("ANTON_OPENAI_BASE_URL")
-            _llm_api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("ANTON_OPENAI_API_KEY")
+            _llm_base_url = os.environ.get("OPENAI_BASE_URL") or os.environ.get(
+                "ANTON_OPENAI_BASE_URL"
+            )
+            _llm_api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get(
+                "ANTON_OPENAI_API_KEY"
+            )
             _llm_provider = _ProviderClass(
                 api_key=_llm_api_key or None,
                 base_url=_llm_base_url or None,
@@ -48,13 +97,14 @@ async def _run_with_heartbeat(coro):
             scratchpad inactivity timeout (30s) kills the process.  This
             wrapper runs a heartbeat task alongside the real work.
             """
+
             async def _heartbeat():
                 elapsed = 0
                 while True:
                     await _llm_asyncio.sleep(_LLM_HEARTBEAT_INTERVAL)
                     elapsed += _LLM_HEARTBEAT_INTERVAL
                     _real_stdout.write(
-                        _PROGRESS_MARKER + f" Waiting for LLM… ({elapsed}s)\n"
+                        PROGRESS_MARKER + f" Waiting for LLM… ({elapsed}s)\n"
                     )
                     _real_stdout.flush()
 
@@ -75,24 +125,30 @@ class _ScratchpadLLM:
             def model(self):
                 return _llm_model
 
-            def complete(self, *, system, messages, tools=None, tool_choice=None, max_tokens=4096):
+            def complete(
+                self, *, system, messages, tools=None, tool_choice=None, max_tokens=4096
+            ):
                 """Call the LLM synchronously. Returns an LLMResponse.
 
                 Automatically emits progress heartbeats every 10s so that
                 long API calls don't trip the scratchpad inactivity timeout.
                 """
-                return _llm_asyncio.run(_run_with_heartbeat(
-                    _llm_provider.complete(
-                        model=_llm_model,
-                        system=system,
-                        messages=messages,
-                        tools=tools,
-                        tool_choice=tool_choice,
-                        max_tokens=max_tokens,
+                return _llm_asyncio.run(
+                    _run_with_heartbeat(
+                        _llm_provider.complete(
+                            model=_llm_model,
+                            system=system,
+                            messages=messages,
+                            tools=tools,
+                            tool_choice=tool_choice,
+                            max_tokens=max_tokens,
+                        )
                     )
-                ))
+                )
 
-            async def complete_async(self, *, system, messages, tools=None, tool_choice=None, max_tokens=4096):
+            async def complete_async(
+                self, *, system, messages, tools=None, tool_choice=None, max_tokens=4096
+            ):
                 """Call the LLM asynchronously. Returns an LLMResponse.
 
                 Use this inside async code (e.g. asyncio.gather) for concurrent
@@ -109,12 +165,20 @@ async def complete_async(self, *, system, messages, tools=None, tool_choice=None
                     )
                 )
 
-            def generate_object(self, schema_class, *, system, messages, max_tokens=4096):
+            def generate_object(
+                self, schema_class, *, system, messages, max_tokens=4096
+            ):
                 """Generate a structured object matching a Pydantic model.
 
                 Uses tool_choice to force the LLM to return structured data.
                 Supports single models and list[Model].
 
+                The schema-building and unwrapping logic is shared with
+                `LLMClient.generate_object` (in the main process) via
+                `anton.core.llm.structured` — only the actual provider
+                call differs between the two runtime contexts (sync
+                subprocess here, async planning there).
+
                 Args:
                     schema_class: A Pydantic BaseModel subclass, or list[Model].
                     system: System prompt.
@@ -124,45 +188,29 @@ def generate_object(self, schema_class, *, system, messages, max_tokens=4096):
                 Returns:
                     An instance of schema_class (or a list of instances).
                 """
-                from pydantic import BaseModel as _BaseModel
-
-                is_list = hasattr(schema_class, "__origin__") and schema_class.__origin__ is list
-                if is_list:
-                    inner_class = schema_class.__args__[0]
-
-                    class _ArrayWrapper(_BaseModel):
-                        items: list[inner_class]
-
-                    schema = _ArrayWrapper.model_json_schema()
-                    tool_name = f"{inner_class.__name__}_array"
-                else:
-                    schema = schema_class.model_json_schema()
-                    tool_name = schema_class.__name__
+                from anton.core.llm.structured import (
+                    build_structured_tool,
+                    unwrap_structured_response,
+                )
 
-                tool = {
-                    "name": tool_name,
-                    "description": f"Generate structured output matching the {tool_name} schema.",
-                    "input_schema": schema,
-                }
+                tool, validator_class, is_list = build_structured_tool(
+                    schema_class
+                )
 
                 response = self.complete(
                     system=system,
                     messages=messages,
                     tools=[tool],
-                    tool_choice={"type": "tool", "name": tool_name},
+                    tool_choice={"type": "tool", "name": tool["name"]},
                     max_tokens=max_tokens,
                 )
 
                 if not response.tool_calls:
                     raise ValueError("LLM did not return structured output.")
 
-                import json as _json
-                raw = response.tool_calls[0].input
-
-                if is_list:
-                    wrapper = _ArrayWrapper.model_validate(raw)
-                    return wrapper.items
-                return schema_class.model_validate(raw)
+                return unwrap_structured_response(
+                    response.tool_calls[0].input, validator_class, is_list
+                )
 
         _scratchpad_llm_instance = _ScratchpadLLM()
 
@@ -170,7 +218,9 @@ def get_llm():
             """Get a pre-configured LLM client. No API keys needed."""
             return _scratchpad_llm_instance
 
-        def agentic_loop(*, system, user_message, tools, handle_tool, max_turns=10, max_tokens=4096):
+        def agentic_loop(
+            *, system, user_message, tools, handle_tool, max_turns=10, max_tokens=4096
+        ):
             """Run a synchronous LLM tool-call loop.
 
             The LLM reasons, calls tools via handle_tool(name, inputs) -> str,
@@ -207,12 +257,14 @@ def agentic_loop(*, system, user_message, tools, handle_tool, max_turns=10, max_
                 if response.content:
                     assistant_content.append({"type": "text", "text": response.content})
                 for tc in response.tool_calls:
-                    assistant_content.append({
-                        "type": "tool_use",
-                        "id": tc.id,
-                        "name": tc.name,
-                        "input": tc.input,
-                    })
+                    assistant_content.append(
+                        {
+                            "type": "tool_use",
+                            "id": tc.id,
+                            "name": tc.name,
+                            "input": tc.input,
+                        }
+                    )
                 messages.append({"role": "assistant", "content": assistant_content})
 
                 # Execute each tool and collect results
@@ -222,11 +274,13 @@ def agentic_loop(*, system, user_message, tools, handle_tool, max_turns=10, max_
                         result = handle_tool(tc.name, tc.input)
                     except Exception as exc:
                         result = f"Error: {exc}"
-                    tool_results.append({
-                        "type": "tool_result",
-                        "tool_use_id": tc.id,
-                        "content": result,
-                    })
+                    tool_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": tc.id,
+                            "content": result,
+                        }
+                    )
                 messages.append({"role": "user", "content": tool_results})
 
             # Hit max_turns
@@ -241,12 +295,15 @@ def agentic_loop(*, system, user_message, tools, handle_tool, max_turns=10, max_
 _minds_datasource = os.environ.get("ANTON_MINDS_DATASOURCE", "")
 _minds_api_key = os.environ.get("ANTON_MINDS_API_KEY", "")
 _minds_url = os.environ.get("ANTON_MINDS_URL", "")
+_minds_engine = os.environ.get("ANTON_MINDS_DATASOURCE_ENGINE", "")
 if _minds_datasource and _minds_api_key and _minds_url:
     try:
         import ssl as _minds_ssl
         import urllib.request as _minds_urllib
 
-        _minds_ssl_verify = os.environ.get("ANTON_MINDS_SSL_VERIFY", "true").lower() != "false"
+        _minds_ssl_verify = (
+            os.environ.get("ANTON_MINDS_SSL_VERIFY", "true").lower() != "false"
+        )
 
         def query_minds_data(query, datasource=None):
             """Query a Minds datasource with SQL. Returns dict with type, data, column_names, error_message."""
@@ -258,7 +315,10 @@ def query_minds_data(query, datasource=None):
             req.add_header("Authorization", f"Bearer {_minds_api_key}")
             req.add_header("Content-Type", "application/json")
             req.add_header("Accept", "application/json")
-            req.add_header("User-Agent", "Mozilla/5.0 (compatible; Anton/1.0; +https://github.com/mindsdb/anton)")
+            req.add_header(
+                "User-Agent",
+                "Mozilla/5.0 (compatible; Anton/1.0; +https://github.com/mindsdb/anton)",
+            )
             req.add_header("Accept-Language", "en-US,en;q=0.9")
             req.add_header("Accept-Encoding", "identity")
             req.add_header("Connection", "keep-alive")
@@ -271,13 +331,28 @@ def query_minds_data(query, datasource=None):
 
             try:
                 with _minds_urllib.urlopen(req, context=ctx, timeout=60) as resp:
-                    return json.loads(resp.read().decode())
+                    parsed = json.loads(resp.read().decode())
+                    namespace.setdefault("_anton_explainability_queries", []).append({
+                        "datasource": ds,
+                        "sql": query,
+                        "engine": _minds_engine or None,
+                        "status": "ok",
+                        "error_message": None,
+                    })
+                    return parsed
             except _minds_urllib.HTTPError as e:
                 body = ""
                 try:
                     body = e.read().decode()
                 except Exception:
                     pass
+                namespace.setdefault("_anton_explainability_queries", []).append({
+                    "datasource": ds,
+                    "sql": query,
+                    "engine": _minds_engine or None,
+                    "status": "error",
+                    "error_message": f"HTTP {e.code}: {body or e.reason}",
+                })
                 return {
                     "type": "error",
                     "data": None,
@@ -285,6 +360,13 @@ def query_minds_data(query, datasource=None):
                     "error_message": f"HTTP {e.code}: {body or e.reason}",
                 }
             except Exception as e:
+                namespace.setdefault("_anton_explainability_queries", []).append({
+                    "datasource": ds,
+                    "sql": query,
+                    "engine": _minds_engine or None,
+                    "status": "error",
+                    "error_message": str(e),
+                })
                 return {
                     "type": "error",
                     "data": None,
@@ -300,16 +382,20 @@ def query_minds_data(query, datasource=None):
 _real_stdout = sys.stdout
 _real_stdin = sys.stdin
 
-_PROGRESS_MARKER = "__ANTON_PROGRESS__"
+from anton.core.backends.wire import PROGRESS_MARKER
+
 _MAX_OUTPUT = 10_000
 
+
 def progress(message=""):
     """Signal that long-running work is still active. Resets the inactivity timer."""
-    _real_stdout.write(_PROGRESS_MARKER + " " + str(message) + "\n")
+    _real_stdout.write(PROGRESS_MARKER + " " + str(message) + "\n")
     _real_stdout.flush()
 
+
 namespace["progress"] = progress
 
+
 def sample(var, mode="preview", _name=None):
     """Inspect a variable with type-aware formatting.
 
@@ -332,6 +418,7 @@ def sample(var, mode="preview", _name=None):
 
     try:
         import pandas as _pd
+
         if isinstance(var, _pd.DataFrame):
             lines.append(f"Shape: {var.shape[0]} rows x {var.shape[1]} cols")
             lines.append(f"Columns: {list(var.columns)}")
@@ -370,6 +457,7 @@ def sample(var, mode="preview", _name=None):
 
     try:
         import numpy as _np
+
         if isinstance(var, _np.ndarray):
             lines.append(f"Shape: {var.shape}, Dtype: {var.dtype}")
             if mode == "preview":
@@ -378,9 +466,13 @@ def sample(var, mode="preview", _name=None):
                 lines.append(f"First {n} values: {flat[:n].tolist()}")
                 if len(flat) > 10:
                     lines.append(f"Last 3 values: {flat[-3:].tolist()}")
-                lines.append(f"Min: {var.min()}, Max: {var.max()}, Mean: {var.mean():.4g}")
+                lines.append(
+                    f"Min: {var.min()}, Max: {var.max()}, Mean: {var.mean():.4g}"
+                )
             else:
-                lines.append(f"Min: {var.min()}, Max: {var.max()}, Mean: {var.mean():.4g}, Std: {var.std():.4g}")
+                lines.append(
+                    f"Min: {var.min()}, Max: {var.max()}, Mean: {var.mean():.4g}, Std: {var.std():.4g}"
+                )
                 lines.append(f"\n{repr(var)}")
             print(_truncate_sample("\n".join(lines), limit))
             return
@@ -402,6 +494,7 @@ def sample(var, mode="preview", _name=None):
                 lines.append(f"  {k!r}: {val_repr}")
         else:
             import json as _json
+
             try:
                 lines.append(_json.dumps(var, indent=2, default=str))
             except (TypeError, ValueError):
@@ -413,8 +506,14 @@ def sample(var, mode="preview", _name=None):
         kind = type(var).__name__
         lines.append(f"Length: {len(var)}")
         if len(var) > 0:
-            lines.append(f"Item types: {type(var[0]).__name__}" +
-                         (f" (mixed)" if len(var) > 1 and type(var[0]) != type(var[-1]) else ""))
+            lines.append(
+                f"Item types: {type(var[0]).__name__}"
+                + (
+                    f" (mixed)"
+                    if len(var) > 1 and type(var[0]) != type(var[-1])
+                    else ""
+                )
+            )
         if mode == "preview":
             n = min(5, len(var))
             for i in range(n):
@@ -504,8 +603,10 @@ def _truncate_sample(text, max_chars):
 # warnings, and errors from libraries.
 import logging as _logging
 
+
 class _CellLogHandler(_logging.Handler):
     """Logging handler that writes to whichever StringIO is current."""
+
     def __init__(self):
         super().__init__(level=_logging.INFO)
         self.buf = None
@@ -518,6 +619,7 @@ def emit(self, record):
             except Exception:
                 pass
 
+
 _cell_log_handler = _CellLogHandler()
 _logging.root.addHandler(_cell_log_handler)
 _logging.root.setLevel(_logging.INFO)
@@ -537,7 +639,7 @@ def emit(self, record):
                 eof = True
                 break
             stripped = line.rstrip("\r\n")
-            if stripped == _CELL_DELIM:
+            if stripped == CELL_DELIM:
                 break
             lines.append(line)
     except EOFError:
@@ -548,9 +650,9 @@ def emit(self, record):
     code = "".join(lines)
     if not code.strip():
         result = {"stdout": "", "stderr": "", "logs": "", "error": None}
-        _real_stdout.write(_RESULT_START + "\n")
+        _real_stdout.write(RESULT_START + "\n")
         _real_stdout.write(json.dumps(result) + "\n")
-        _real_stdout.write(_RESULT_END + "\n")
+        _real_stdout.write(RESULT_END + "\n")
         _real_stdout.flush()
         continue
 
@@ -558,6 +660,7 @@ def emit(self, record):
     err_buf = io.StringIO()
     log_buf = io.StringIO()
     error = None
+    namespace["_anton_explainability_queries"] = []
     _cell_log_handler.buf = log_buf
 
     sys.stdout = out_buf
@@ -573,19 +676,24 @@ def emit(self, record):
             sys.stdout = _real_stdout
             sys.stderr = sys.__stderr__
             _cell_log_handler.buf = None
-            _real_stdout.write(_PROGRESS_MARKER + " " + f"Installing {_missing}..." + "\n")
+            _real_stdout.write(
+                PROGRESS_MARKER + " " + f"Installing {_missing}..." + "\n"
+            )
             _real_stdout.flush()
             import subprocess as _sp
+
             _uv_path = os.environ.get("ANTON_UV_PATH", "")
             if _uv_path:
                 _pip = _sp.run(
                     [_uv_path, "pip", "install", "--python", sys.executable, _missing],
-                    capture_output=True, timeout=120,
+                    capture_output=True,
+                    timeout=120,
                 )
             else:
                 _pip = _sp.run(
                     [sys.executable, "-m", "pip", "install", _missing],
-                    capture_output=True, timeout=120,
+                    capture_output=True,
+                    timeout=120,
                 )
             # Reset buffers and retry
             out_buf = io.StringIO()
@@ -616,16 +724,24 @@ def emit(self, record):
 
     stdout_val = out_buf.getvalue()
     if len(stdout_val) > _MAX_OUTPUT:
-        stdout_val = stdout_val[:_MAX_OUTPUT] + f"\n\n... (truncated, {len(stdout_val)} chars total)"
+        stdout_val = (
+            stdout_val[:_MAX_OUTPUT]
+            + f"\n\n... (truncated, {len(stdout_val)} chars total)"
+        )
+
+    # Persist session after each cell.
+    _dump_namespace(namespace)
+
     result = {
         "stdout": stdout_val,
         "stderr": err_buf.getvalue(),
         "logs": log_buf.getvalue(),
         "error": error,
+        "explainability_queries": list(namespace.get("_anton_explainability_queries", [])),
     }
     if _auto_installed:
         result["auto_installed"] = _auto_installed
-    _real_stdout.write(_RESULT_START + "\n")
+    _real_stdout.write(RESULT_START + "\n")
     _real_stdout.write(json.dumps(result) + "\n")
-    _real_stdout.write(_RESULT_END + "\n")
+    _real_stdout.write(RESULT_END + "\n")
     _real_stdout.flush()
diff --git a/anton/core/backends/utils.py b/anton/core/backends/utils.py
new file mode 100644
index 00000000..07cd1796
--- /dev/null
+++ b/anton/core/backends/utils.py
@@ -0,0 +1,14 @@
+from anton.core.settings import CoreSettings
+
+
+def compute_timeouts(estimated_seconds: int) -> tuple[float, float]:
+    """Compute (total_timeout, inactivity_timeout) from an estimated run time.
+
+    Reads defaults from CoreSettings so they're tunable via env vars.
+    """
+    s = CoreSettings()
+    if estimated_seconds <= 0:
+        return float(s.cell_timeout_default), float(s.cell_inactivity_timeout)
+    total = max(estimated_seconds * 2, estimated_seconds + 30)
+    inactivity = max(estimated_seconds * 0.5, 30)
+    return float(total), float(inactivity)
\ No newline at end of file
diff --git a/anton/core/backends/wire.py b/anton/core/backends/wire.py
new file mode 100644
index 00000000..46e16e6d
--- /dev/null
+++ b/anton/core/backends/wire.py
@@ -0,0 +1,10 @@
+"""Wire protocol constants shared between LocalScratchpadRuntime and scratchpad_boot.py.
+
+These delimiter strings must be identical on both sides of the subprocess pipe.
+Neither side should redefine them — import from here.
+"""
+
+CELL_DELIM = "__ANTON_CELL_END__"
+RESULT_START = "__ANTON_RESULT__"
+RESULT_END = "__ANTON_RESULT_END__"
+PROGRESS_MARKER = "__ANTON_PROGRESS__"
diff --git a/anton/core/datasources/__init__.py b/anton/core/datasources/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/anton/data_vault.py b/anton/core/datasources/data_vault.py
similarity index 75%
rename from anton/data_vault.py
rename to anton/core/datasources/data_vault.py
index 61f55cc3..dd1eb73a 100644
--- a/anton/data_vault.py
+++ b/anton/core/datasources/data_vault.py
@@ -5,6 +5,7 @@
 import re
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Protocol, runtime_checkable
 
 
 def _sanitize(value: str) -> str:
@@ -24,8 +25,47 @@ def _slug_env_prefix(engine: str, name: str) -> str:
     return "DS_" + re.sub(r"[^\w]", "_", raw).upper()
 
 
-class DataVault:
-    """Manages data source connection credentials in ~/.anton/data_vault/."""
+@runtime_checkable
+class DataVault(Protocol):
+    """Interface for credential storage backends.
+
+    The local implementation (LocalDataVault) stores JSON files in
+    ~/.anton/data_vault/. Cloud implementations can satisfy this protocol
+    with any backend (database, secrets manager, etc.) scoped to a user
+    or tenant.
+    """
+
+    def save(self, engine: str, name: str, credentials: dict[str, str]) -> object:
+        """Persist credentials for engine/name. Returns an implementation-defined path/key."""
+        ...
+
+    def load(self, engine: str, name: str) -> dict[str, str] | None:
+        """Return the fields dict for a connection, or None if not found."""
+        ...
+
+    def delete(self, engine: str, name: str) -> bool:
+        """Remove a connection. Returns True if it existed."""
+        ...
+
+    def list_connections(self) -> list[dict[str, str]]:
+        """Return [{engine, name, created_at}] for all stored connections."""
+        ...
+
+    def inject_env(self, engine: str, name: str, *, flat: bool = False) -> list[str] | None:
+        """Load credentials and set DS_* environment variables."""
+        ...
+
+    def clear_ds_env(self) -> None:
+        """Remove all DS_* variables from os.environ."""
+        ...
+
+    def next_connection_number(self, engine: str) -> int:
+        """Return the next auto-increment number for an engine (1-based)."""
+        ...
+
+
+class LocalDataVault:
+    """File-based credential store in ~/.anton/data_vault/."""
 
     def __init__(self, vault_dir: Path | None = None) -> None:
         self._dir = vault_dir or Path("~/.anton/data_vault").expanduser()
@@ -115,7 +155,7 @@ def inject_env(self, engine: str, name: str, *, flat: bool = False) -> list[str]
             prefix = _slug_env_prefix(engine, name)
             for key, value in fields.items():
                 var = f"{prefix}__{key.upper()}"
-                os.environ[var] = value
+                os.environ[var] = value if isinstance(value, str) else str(value)
                 var_names.append(var)
         return var_names
 
@@ -140,7 +180,7 @@ def next_connection_number(self, engine: str) -> int:
         ]
         max_n = 0
         for fname in existing:
-            suffix = fname[len(prefix) :]
+            suffix = fname[len(prefix):]
             if suffix.isdigit():
                 max_n = max(max_n, int(suffix))
         return max_n + 1
diff --git a/anton/datasource_registry.py b/anton/core/datasources/datasource_registry.py
similarity index 98%
rename from anton/datasource_registry.py
rename to anton/core/datasources/datasource_registry.py
index e932807e..1b0206b2 100644
--- a/anton/datasource_registry.py
+++ b/anton/core/datasources/datasource_registry.py
@@ -123,7 +123,7 @@ def _parse_file(
 class DatasourceRegistry:
     """Parsed registry of all available data source engines."""
 
-    _BUILTIN_PATH: Path = Path(__file__).parent / "config" / "datasources.md"
+    _BUILTIN_PATH: Path = Path(__file__).resolve().parent / "datasources.md"
     _USER_PATH: Path = Path("~/.anton/datasources.md").expanduser()
 
     def __init__(self) -> None:
diff --git a/anton/config/datasources.md b/anton/core/datasources/datasources.md
similarity index 100%
rename from anton/config/datasources.md
rename to anton/core/datasources/datasources.md
diff --git a/anton/core/llm/__init__.py b/anton/core/llm/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/anton/llm/anthropic.py b/anton/core/llm/anthropic.py
similarity index 84%
rename from anton/llm/anthropic.py
rename to anton/core/llm/anthropic.py
index a88176d5..6c6114d8 100644
--- a/anton/llm/anthropic.py
+++ b/anton/core/llm/anthropic.py
@@ -5,10 +5,11 @@
 
 import anthropic
 
-from anton.llm.provider import (
+from .provider import (
     ContextOverflowError,
     LLMProvider,
     LLMResponse,
+    ProviderConnectionInfo,
     StreamComplete,
     StreamEvent,
     StreamTextDelta,
@@ -22,12 +23,18 @@
 
 
 class AnthropicProvider(LLMProvider):
+    name: str = "anthropic"
+
     def __init__(self, api_key: str | None = None) -> None:
+        self._api_key = api_key
         kwargs = {}
         if api_key:
             kwargs["api_key"] = api_key
         self._client = anthropic.AsyncAnthropic(**kwargs)
 
+    def export_connection_info(self) -> ProviderConnectionInfo:
+        return ProviderConnectionInfo(provider=self.name, api_key=self._api_key)
+
     async def complete(
         self,
         *,
@@ -57,10 +64,15 @@ async def complete(
                 raise ContextOverflowError(str(exc)) from exc
             raise
         except anthropic.APIStatusError as exc:
-            if exc.status_code == 429 and isinstance(exc.body, dict) and exc.body.get("detail"):
+            if (
+                exc.status_code == 429
+                and isinstance(exc.body, dict)
+                and exc.body.get("detail")
+            ):
                 msg = f"Server returned 429 — {exc.body['detail']}"
                 msg += " Visit https://mdb.ai to upgrade or to top up your tokens."
-                from anton.llm.provider import TokenLimitExceeded
+                from .provider import TokenLimitExceeded
+
                 raise TokenLimitExceeded(msg) from exc
             else:
                 msg = f"Server returned {exc.status_code} — the LLM endpoint may be temporarily unavailable. Try again in a moment."
@@ -132,7 +144,12 @@ async def stream(
                         idx = event.index
                         block = event.content_block
                         if block.type == "tool_use":
-                            blocks[idx] = {"type": "tool_use", "id": block.id, "name": block.name, "json_parts": []}
+                            blocks[idx] = {
+                                "type": "tool_use",
+                                "id": block.id,
+                                "name": block.name,
+                                "json_parts": [],
+                            }
                             yield StreamToolUseStart(id=block.id, name=block.name)
                         else:
                             blocks[idx] = {"type": "text"}
@@ -147,7 +164,9 @@ async def stream(
                             info = blocks.get(idx, {})
                             if info.get("type") == "tool_use":
                                 info["json_parts"].append(delta.partial_json)
-                                yield StreamToolUseDelta(id=info["id"], json_delta=delta.partial_json)
+                                yield StreamToolUseDelta(
+                                    id=info["id"], json_delta=delta.partial_json
+                                )
 
                     elif event.type == "content_block_stop":
                         idx = event.index
@@ -156,7 +175,9 @@ async def stream(
                             raw_json = "".join(info["json_parts"])
                             parsed_input = json.loads(raw_json) if raw_json else {}
                             tool_calls.append(
-                                ToolCall(id=info["id"], name=info["name"], input=parsed_input)
+                                ToolCall(
+                                    id=info["id"], name=info["name"], input=parsed_input
+                                )
                             )
                             yield StreamToolUseEnd(id=info["id"])
 
@@ -169,10 +190,15 @@ async def stream(
                 raise ContextOverflowError(str(exc)) from exc
             raise
         except anthropic.APIStatusError as exc:
-            if exc.status_code == 429 and isinstance(exc.body, dict) and exc.body.get("detail"):
+            if (
+                exc.status_code == 429
+                and isinstance(exc.body, dict)
+                and exc.body.get("detail")
+            ):
                 msg = f"Server returned 429 — {exc.body['detail']}"
                 msg += " Visit https://mdb.ai to upgrade or to top up your tokens."
-                from anton.llm.provider import TokenLimitExceeded
+                from .provider import TokenLimitExceeded
+
                 raise TokenLimitExceeded(msg) from exc
             else:
                 msg = f"Server returned {exc.status_code} — the LLM endpoint may be temporarily unavailable. Try again in a moment."
diff --git a/anton/core/llm/client.py b/anton/core/llm/client.py
new file mode 100644
index 00000000..abce3620
--- /dev/null
+++ b/anton/core/llm/client.py
@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+from .provider import LLMProvider, LLMResponse, StreamEvent
+
+if TYPE_CHECKING:
+    from anton.config.settings import AntonSettings
+
+
+class LLMClient:
+    def __init__(
+        self,
+        *,
+        planning_provider: LLMProvider,
+        planning_model: str,
+        coding_provider: LLMProvider,
+        coding_model: str,
+        max_tokens: int = 8192,
+    ) -> None:
+        self._planning_provider = planning_provider
+        self._planning_model = planning_model
+        self._coding_provider = coding_provider
+        self._coding_model = coding_model
+        self._max_tokens = max_tokens
+
+    async def plan(
+        self,
+        *,
+        system: str,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        max_tokens: int | None = None,
+    ) -> LLMResponse:
+        return await self._planning_provider.complete(
+            model=self._planning_model,
+            system=system,
+            messages=messages,
+            tools=tools,
+            max_tokens=max_tokens or self._max_tokens,
+        )
+
+    async def plan_stream(
+        self,
+        *,
+        system: str,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[StreamEvent]:
+        async for event in self._planning_provider.stream(
+            model=self._planning_model,
+            system=system,
+            messages=messages,
+            tools=tools,
+            max_tokens=max_tokens or self._max_tokens,
+        ):
+            yield event
+
+    @property
+    def coding_provider(self) -> LLMProvider:
+        """The LLM provider used for coding/skill execution."""
+        return self._coding_provider
+
+    @property
+    def coding_model(self) -> str:
+        """The model name used for coding/skill execution."""
+        return self._coding_model
+
+    async def code(
+        self,
+        *,
+        system: str,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        max_tokens: int | None = None,
+    ) -> LLMResponse:
+        return await self._coding_provider.complete(
+            model=self._coding_model,
+            system=system,
+            messages=messages,
+            tools=tools,
+            max_tokens=max_tokens or self._max_tokens,
+        )
+
+    async def _generate_object_with(
+        self,
+        schema_class,
+        *,
+        provider: LLMProvider,
+        model: str,
+        system: str,
+        messages: list[dict],
+        max_tokens: int | None,
+    ):
+        """Internal: forced-tool-call structured output via any provider.
+
+        Shared by `generate_object` (planning) and `generate_object_code`
+        (coding). The schema-building/unwrapping logic is in
+        `anton.core.llm.structured` so the scratchpad bridge can use the
+        same primitives without depending on this class.
+        """
+        from anton.core.llm.structured import (
+            build_structured_tool,
+            unwrap_structured_response,
+        )
+
+        tool, validator_class, is_list = build_structured_tool(schema_class)
+
+        response = await provider.complete(
+            model=model,
+            system=system,
+            messages=messages,
+            tools=[tool],
+            tool_choice={"type": "tool", "name": tool["name"]},
+            max_tokens=max_tokens or self._max_tokens,
+        )
+
+        if not response.tool_calls:
+            raise ValueError(
+                f"LLM did not return a tool call for forced schema {tool['name']}."
+            )
+
+        return unwrap_structured_response(
+            response.tool_calls[0].input, validator_class, is_list
+        )
+
+    async def generate_object(
+        self,
+        schema_class,
+        *,
+        system: str,
+        messages: list[dict],
+        max_tokens: int | None = None,
+    ):
+        """Generate a structured object using the *planning* provider.
+
+        Forces the planning LLM to call a synthetic tool whose
+        input_schema is derived from the Pydantic model. The tool's
+        input is then validated through `model_validate`, returning a
+        typed instance (or a list of instances for `list[Model]`).
+
+        This is the right primitive for any code that wants structured
+        output from the LLM. It is more reliable than asking for JSON
+        in the response text because:
+
+          - The LLM is *forced* (via `tool_choice`) to call the tool
+          - The tool's input is constrained by the JSON schema
+          - Pydantic catches any structural drift via `model_validate`
+
+        Use this method for any structured-output operation that
+        currently uses `plan()`. For operations that should use the
+        cheaper coding model (memory compaction, identity extraction,
+        anything that ran via `code()` previously), use
+        `generate_object_code()` instead.
+
+        Args:
+            schema_class: A Pydantic `BaseModel` subclass, or a
+                `list[Model]` annotation for a homogeneous list.
+            system: System prompt for the call.
+            messages: Conversation messages.
+            max_tokens: Token budget. Defaults to `self._max_tokens`.
+
+        Returns:
+            An instance of `schema_class`, or a `list[Model]` when the
+            input was a list annotation.
+
+        Raises:
+            ValueError: If the LLM fails to produce a tool call (rare —
+                forced tool_choice usually prevents this).
+            pydantic.ValidationError: If the tool's input doesn't match
+                the schema.
+
+        The schema-building / unwrapping logic is shared with
+        `_ScratchpadLLM.generate_object` (in `scratchpad_boot.py`) via
+        `anton.core.llm.structured` — only the actual provider call
+        differs between the two runtime contexts (async planning here,
+        sync subprocess there).
+        """
+        return await self._generate_object_with(
+            schema_class,
+            provider=self._planning_provider,
+            model=self._planning_model,
+            system=system,
+            messages=messages,
+            max_tokens=max_tokens,
+        )
+
+    async def generate_object_code(
+        self,
+        schema_class,
+        *,
+        system: str,
+        messages: list[dict],
+        max_tokens: int | None = None,
+    ):
+        """Generate a structured object using the *coding* provider.
+
+        Same forced-tool-call mechanism as `generate_object`, but routes
+        through the coding provider/model. Use this when the operation
+        is a fast, cheap structured task that previously called
+        `code()` — e.g. memory compaction, identity extraction,
+        scratchpad post-mortem analysis. The savings vs. the planning
+        model add up across many small calls.
+        """
+        return await self._generate_object_with(
+            schema_class,
+            provider=self._coding_provider,
+            model=self._coding_model,
+            system=system,
+            messages=messages,
+            max_tokens=max_tokens,
+        )
+
+    @classmethod
+    def from_settings(cls, settings: AntonSettings) -> LLMClient:
+        from .anthropic import AnthropicProvider
+        from .openai import OpenAIProvider
+
+        providers = {
+            "anthropic": lambda: AnthropicProvider(api_key=settings.anthropic_api_key),
+            "openai": lambda: OpenAIProvider(
+                api_key=settings.openai_api_key,
+                base_url=settings.openai_base_url,
+                ssl_verify=settings.minds_ssl_verify,
+            ),
+            "openai-compatible": lambda: OpenAIProvider(
+                api_key=settings.openai_api_key,
+                base_url=settings.openai_base_url,
+                ssl_verify=settings.minds_ssl_verify,
+            ),
+        }
+
+        planning_factory = providers.get(settings.planning_provider)
+        coding_factory = providers.get(settings.coding_provider)
+
+        if planning_factory is None:
+            raise ValueError(f"Unknown planning provider: {settings.planning_provider}")
+        if coding_factory is None:
+            raise ValueError(f"Unknown coding provider: {settings.coding_provider}")
+
+        return cls(
+            planning_provider=planning_factory(),
+            planning_model=settings.planning_model,
+            coding_provider=coding_factory(),
+            coding_model=settings.coding_model,
+            max_tokens=getattr(settings, "max_tokens", 8192),
+        )
diff --git a/anton/llm/openai.py b/anton/core/llm/openai.py
similarity index 83%
rename from anton/llm/openai.py
rename to anton/core/llm/openai.py
index d57a709d..29c08313 100644
--- a/anton/llm/openai.py
+++ b/anton/core/llm/openai.py
@@ -5,10 +5,11 @@
 
 import openai
 
-from anton.llm.provider import (
+from .provider import (
     ContextOverflowError,
     LLMProvider,
     LLMResponse,
+    ProviderConnectionInfo,
     StreamComplete,
     StreamEvent,
     StreamTextDelta,
@@ -25,14 +26,16 @@ def _translate_tools(tools: list[dict]) -> list[dict]:
     """Anthropic tool format -> OpenAI function-calling format."""
     result = []
     for tool in tools:
-        result.append({
-            "type": "function",
-            "function": {
-                "name": tool["name"],
-                "description": tool.get("description", ""),
-                "parameters": tool.get("input_schema", {}),
-            },
-        })
+        result.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": tool["name"],
+                    "description": tool.get("description", ""),
+                    "parameters": tool.get("input_schema", {}),
+                },
+            }
+        )
     return result
 
 
@@ -99,14 +102,16 @@ def _translate_assistant_blocks(blocks: list[dict]) -> list[dict]:
         if block.get("type") == "text":
             text_parts.append(block["text"])
         elif block.get("type") == "tool_use":
-            tool_calls.append({
-                "id": block["id"],
-                "type": "function",
-                "function": {
-                    "name": block["name"],
-                    "arguments": json.dumps(block.get("input", {})),
-                },
-            })
+            tool_calls.append(
+                {
+                    "id": block["id"],
+                    "type": "function",
+                    "function": {
+                        "name": block["name"],
+                        "arguments": json.dumps(block.get("input", {})),
+                    },
+                }
+            )
 
     msg: dict = {"role": "assistant"}
     content = "\n".join(text_parts) if text_parts else None
@@ -133,11 +138,13 @@ def _translate_user_blocks(blocks: list[dict]) -> list[dict]:
                 content = "\n".join(
                     b.get("text", "") for b in content if b.get("type") == "text"
                 )
-            result.append({
-                "role": "tool",
-                "tool_call_id": block["tool_use_id"],
-                "content": str(content),
-            })
+            result.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": block["tool_use_id"],
+                    "content": str(content),
+                }
+            )
         elif block.get("type") == "text":
             content_parts.append({"type": "text", "text": block.get("text", "")})
         elif block.get("type") == "image":
@@ -146,18 +153,22 @@ def _translate_user_blocks(blocks: list[dict]) -> list[dict]:
             if source.get("type") == "base64":
                 media_type = source.get("media_type", "image/png")
                 data = source.get("data", "")
-                content_parts.append({
-                    "type": "image_url",
-                    "image_url": {"url": f"data:{media_type};base64,{data}"},
-                })
+                content_parts.append(
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:{media_type};base64,{data}"},
+                    }
+                )
 
     if content_parts:
         # If only text parts, flatten to a simple string for compatibility
         if all(p.get("type") == "text" for p in content_parts):
-            result.append({
-                "role": "user",
-                "content": "\n".join(p["text"] for p in content_parts),
-            })
+            result.append(
+                {
+                    "role": "user",
+                    "content": "\n".join(p["text"] for p in content_parts),
+                }
+            )
         else:
             result.append({"role": "user", "content": content_parts})
 
@@ -184,12 +195,18 @@ def build_chat_completion_kwargs(
 
 
 class OpenAIProvider(LLMProvider):
+    name: str = "openai"
+
     def __init__(
         self,
         api_key: str | None = None,
         base_url: str | None = None,
         ssl_verify: bool = True,
     ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._ssl_verify = ssl_verify
+
         import httpx
 
         kwargs = {}
@@ -201,6 +218,14 @@ def __init__(
             kwargs["http_client"] = httpx.AsyncClient(verify=False)
         self._client = openai.AsyncOpenAI(**kwargs)
 
+    def export_connection_info(self) -> ProviderConnectionInfo:
+        return ProviderConnectionInfo(
+            provider=self.name,
+            api_key=self._api_key,
+            base_url=self._base_url,
+            ssl_verify=self._ssl_verify,
+        )
+
     async def complete(
         self,
         *,
@@ -231,10 +256,15 @@ async def complete(
                 raise ContextOverflowError(str(exc)) from exc
             raise
         except openai.APIStatusError as exc:
-            if exc.status_code == 429 and isinstance(exc.body, dict) and exc.body.get("detail"):
+            if (
+                exc.status_code == 429
+                and isinstance(exc.body, dict)
+                and exc.body.get("detail")
+            ):
                 msg = f"Server returned 429 — {exc.body['detail']}"
                 msg += " Visit https://mdb.ai to upgrade or to top up your tokens."
-                from anton.llm.provider import TokenLimitExceeded
+                from .provider import TokenLimitExceeded
+
                 raise TokenLimitExceeded(msg) from exc
             else:
                 msg = f"Server returned {exc.status_code} — the LLM endpoint may be temporarily unavailable. Try again in a moment."
@@ -256,7 +286,9 @@ async def complete(
                     ToolCall(
                         id=tc.id,
                         name=tc.function.name,
-                        input=json.loads(tc.function.arguments) if tc.function.arguments else {},
+                        input=json.loads(tc.function.arguments)
+                        if tc.function.arguments
+                        else {},
                     )
                 )
 
@@ -331,7 +363,9 @@ async def stream(
                             # New tool call
                             tc_state[idx] = {
                                 "id": tc_delta.id or "",
-                                "name": tc_delta.function.name if tc_delta.function and tc_delta.function.name else "",
+                                "name": tc_delta.function.name
+                                if tc_delta.function and tc_delta.function.name
+                                else "",
                                 "args_parts": [],
                             }
                             if tc_state[idx]["id"] and tc_state[idx]["name"]:
@@ -348,7 +382,9 @@ async def stream(
 
                         # Accumulate argument fragments
                         if tc_delta.function and tc_delta.function.arguments:
-                            tc_state[idx]["args_parts"].append(tc_delta.function.arguments)
+                            tc_state[idx]["args_parts"].append(
+                                tc_delta.function.arguments
+                            )
                             yield StreamToolUseDelta(
                                 id=tc_state[idx]["id"],
                                 json_delta=tc_delta.function.arguments,
@@ -359,10 +395,15 @@ async def stream(
                 raise ContextOverflowError(str(exc)) from exc
             raise
         except openai.APIStatusError as exc:
-            if exc.status_code == 429 and isinstance(exc.body, dict) and exc.body.get("detail"):
+            if (
+                exc.status_code == 429
+                and isinstance(exc.body, dict)
+                and exc.body.get("detail")
+            ):
                 msg = f"Server returned 429 — {exc.body['detail']}"
                 msg += " Visit https://mdb.ai to upgrade or top up your tokens."
-                from anton.llm.provider import TokenLimitExceeded
+                from .provider import TokenLimitExceeded
+
                 raise TokenLimitExceeded(msg) from exc
             else:
                 msg = f"Server returned {exc.status_code} — the LLM endpoint may be temporarily unavailable. Try again in a moment."
diff --git a/anton/core/llm/prompt_builder.py b/anton/core/llm/prompt_builder.py
new file mode 100644
index 00000000..d7340fe6
--- /dev/null
+++ b/anton/core/llm/prompt_builder.py
@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .prompts import (
+    BASE_VISUALIZATIONS_PROMPT,
+    CHAT_SYSTEM_PROMPT,
+    VISUALIZATIONS_MARKDOWN_OUTPUT_FORMAT_PROMPT,
+    VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT,
+)
+
+if TYPE_CHECKING:
+    from anton.core.memory.skills import SkillStore
+    from anton.core.tools.tool_defs import ToolDef
+
+
+@dataclass(frozen=True)
+class SystemPromptContext:
+    """Bundled prompt-injection points for the system prompt.
+
+    Four levels with increasing importance (later = stronger influence):
+      1. ``prefix``  — prepended before the base prompt
+      2. ``runtime_context`` — interpolated into the RUNTIME IDENTITY section
+      3. ``output_context`` — free-text instructions on where to
+         store generated resources (visualizations, HTML files, data exports)
+      4. ``suffix``  — appended after all other sections
+    """
+
+    runtime_context: str = ""
+    prefix: str = ""
+    suffix: str = ""
+    output_context: str = ""
+
+
+class ChatSystemPromptBuilder:
+    """
+    Build Anton's chat system prompt from core components.
+    """
+
+    def _build_tool_prompts_section(self, tool_defs: list["ToolDef"] | None) -> str:
+        """Build an optional system-prompt section from `ToolDef.prompt`."""
+        if not tool_defs:
+            return ""
+
+        chunks: list[str] = []
+        for tool in tool_defs:
+            prompt = getattr(tool, "prompt", None)
+
+            if not prompt:
+                continue
+
+            prompt_text = str(prompt).strip()
+            if not prompt_text:
+                continue
+
+            chunks.append(prompt_text)
+
+        if not chunks:
+            return ""
+
+        return "\n\n".join(chunks)
+
+    def _build_procedural_memory_section(
+        self, skill_store: "SkillStore | None"
+    ) -> str:
+        """Build the '## Procedural memory' section listing available skills.
+
+        Lists each skill as `- label: when_to_use` (one line) plus a short
+        instruction telling the LLM to call `recall_skill(label)` to load
+        the full procedure. Returns an empty string if no store is wired
+        or no skills are saved — the caller skips the section entirely.
+        """
+        if skill_store is None:
+            return ""
+        try:
+            summaries = skill_store.list_summaries()
+        except Exception:
+            return ""
+        if not summaries:
+            return ""
+
+        lines: list[str] = [
+            "",
+            "",
+            "## Procedural memory (skills available)",
+            "",
+            (
+                "These are reusable procedures you've previously refined for "
+                "recurring tasks. When the user's request matches one of "
+                "them, call `recall_skill(label)` to load the full step-by-"
+                "step procedure into your context. You may recall multiple "
+                "skills if the task spans several. If none apply, proceed "
+                "with normal reasoning."
+            ),
+            "",
+        ]
+        for s in summaries:
+            label = s.get("label", "")
+            when = s.get("when_to_use", "").strip()
+            if not label:
+                continue
+            if when:
+                lines.append(f"- `{label}` — {when}")
+            else:
+                lines.append(f"- `{label}`")
+        return "\n".join(lines)
+
+    def _build_visualizations_section(
+        self,
+        *,
+        proactive_dashboards: bool,
+        output_context: str,
+    ) -> str:
+        visualizations_output_format_prompt = (
+            VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT
+            if proactive_dashboards
+            else VISUALIZATIONS_MARKDOWN_OUTPUT_FORMAT_PROMPT
+        )
+        output_format = visualizations_output_format_prompt.format(
+            output_context=output_context,
+        )
+        return BASE_VISUALIZATIONS_PROMPT.format(output_format=output_format)
+
+    def build(
+        self,
+        *,
+        current_datetime: str,
+        system_prompt_context: SystemPromptContext,
+        proactive_dashboards: bool,
+        tool_defs: list["ToolDef"] | None = None,
+        memory_context: str = "",
+        project_context: str = "",
+        self_awareness_context: str = "",
+        datasource_context: str = "",
+        skill_store: "SkillStore | None" = None,
+    ) -> str:
+        visualizations_section = self._build_visualizations_section(
+            proactive_dashboards=proactive_dashboards,
+            output_context=system_prompt_context.output_context,
+        )
+
+        prompt = ""
+
+        prefix = system_prompt_context.prefix.strip()
+        if prefix:
+            prompt += f"{prefix}\n\n"
+
+        prompt += CHAT_SYSTEM_PROMPT.format(
+            runtime_context=system_prompt_context.runtime_context,
+            visualizations_section=visualizations_section,
+            current_datetime=current_datetime,
+        )
+
+        tool_prompts = self._build_tool_prompts_section(tool_defs)
+        if tool_prompts:
+            prompt += tool_prompts
+
+        if memory_context:
+            prompt += memory_context
+        if project_context:
+            prompt += project_context
+        if self_awareness_context:
+            prompt += self_awareness_context
+        if datasource_context:
+            prompt += datasource_context
+
+        procedural_memory = self._build_procedural_memory_section(skill_store)
+        if procedural_memory:
+            prompt += procedural_memory
+
+        suffix = system_prompt_context.suffix.strip()
+        if suffix:
+            prompt += f"\n\n{suffix}"
+
+        return prompt
+
+
+__all__ = ["ChatSystemPromptBuilder", "SystemPromptContext"]
diff --git a/anton/llm/prompts.py b/anton/core/llm/prompts.py
similarity index 84%
rename from anton/llm/prompts.py
rename to anton/core/llm/prompts.py
index cce3ea9f..3596eb85 100644
--- a/anton/llm/prompts.py
+++ b/anton/core/llm/prompts.py
@@ -1,16 +1,7 @@
-LEARNING_EXTRACT_PROMPT = """\
-Analyze this task execution and extract reusable learnings.
-For each learning, provide:
-- topic: short snake_case category name
-- content: the learning detail (1-3 sentences)
-- summary: one-line summary for indexing
-
-Return a JSON array. If no meaningful learnings, return [].
-
-Example output:
-[{"topic": "file_operations", "content": "Always check if a file exists before reading.", "summary": "Check file existence before reads"}]
-"""
-
+# TODO: Update references to memory directories when new memory abstractions are implemented.
+# (Lines )
+# TODO: Update references to data vault directory? Will it be used this way across our environments?
+# (Lines )
 CHAT_SYSTEM_PROMPT = """\
 You are Anton — a self-evolving autonomous system that collaborates with people to \
 solve problems. You are NOT a code assistant or chatbot. You are a coworker with a \
@@ -120,14 +111,6 @@
 Don't suggest personal data analysis if the user's question is purely informational \
 with no personal angle.
 
-CONTENT SHARING POLICY:
-- Publishing dashboards or reports to the web is done ONLY via the `publish_or_preview` tool. \
-Do NOT upload, post, or share generated files (HTML, data, images) to external hosting \
-services (paste sites, gists, CDNs, file hosts) via scratchpad code — unless the user \
-explicitly names the service and confirms. Reading from public APIs and writing to the \
-user's connected datasources (databases, CRMs, etc.) is fine — this rule only applies to \
-sharing generated output with the public internet.
-
 SCRATCHPAD:
 - Use the scratchpad for computation, data analysis, web scraping, plotting, file I/O, \
 shell commands, and anything that needs precise execution.
@@ -169,11 +152,6 @@
 - Host Python packages are available by default. Use the scratchpad install action to \
 add more — installed packages persist across resets.
 
-FILE ATTACHMENTS:
-- Users can drag files or paste clipboard images. These appear as <file path="..."> tags.
-- For binary files (images, PDFs), use the scratchpad to read and process them.
-- Clipboard images are saved to .anton/uploads/ — open with Pillow, OpenCV, etc.
-
 {visualizations_section}
 
 CONVERSATION DISCIPLINE (critical):
@@ -230,15 +208,14 @@
 # Visualization prompt variants — selected by ANTON_PROACTIVE_DASHBOARDS flag
 # ---------------------------------------------------------------------------
 
-_VISUALIZATIONS_PROACTIVE = """\
+BASE_VISUALIZATIONS_PROMPT = """\
 VISUALIZATIONS (charts, plots, maps, dashboards, reports):
 
-Insights-first workflow — ALWAYS follow this order for dashboards and multi-chart requests:
+Insights-first workflow — ALWAYS follow this order for analysis and reports:
 1. FETCH DATA FIRST: Use one scratchpad call to pull data and compute key metrics. Return \
-structured results (numbers, percentages, rankings) — not HTML yet.
-2. STREAM INSIGHTS IMMEDIATELY: Before building any visualization, narrate your findings \
-to the user in the chat. They should get value within seconds, not after waiting for HTML. \
-Structure insights as:
+structured results (numbers, percentages, rankings).
+2. STREAM INSIGHTS IMMEDIATELY: Narrate your findings to the user in the chat. They should \
+get value within seconds. Structure insights as:
   - DATA HIGHLIGHTS: Start with a compact summary table showing the key numbers at a glance \
 (use markdown tables). This gives the user the raw data immediately — positions, values, \
 returns, key metrics — before you interpret them.
@@ -252,7 +229,14 @@
 Timezone? Real-time or delayed? Don't hide these — state them clearly.
   - ACTIONABLE EDGE: What could the user do with this information? Risks to watch, \
 thresholds that matter, scenarios worth considering.
-3. WRITE A DASHBOARD BRIEF: Before coding the HTML, plan the dashboard out loud:
+
+Output format:
+{output_format}
+"""
+
+
+VISUALIZATIONS_HTML_OUTPUT_FORMAT_PROMPT = """\
+WRITE A DASHBOARD BRIEF: Before coding the HTML, plan the dashboard out loud:
   - What story does each chart tell? (not "a bar chart of X" but "this shows how Y \
 is driving Z, annotated at the inflection point")
   - What is the visual hierarchy? Hero KPIs at top, main narrative chart first, \
@@ -260,7 +244,8 @@
   - What should be annotated? Key dates, threshold crossings, outliers.
   - What color scheme ties it together? Consistent meaning (green=positive, red=negative) \
 across all charts.
-4. BUILD THE DASHBOARD — use multiple scratchpad cells, but produce ONE single self-contained HTML file:
+
+BUILD THE DASHBOARD — use multiple scratchpad cells, but produce ONE single self-contained HTML file:
 
   CRITICAL: The final dashboard MUST be a single .html file with ALL data, CSS, and JS inlined. \
 Do NOT reference external local files (like data.js) — browsers block local file:// cross-references \
@@ -292,13 +277,13 @@
 
   FINAL CELL — Assemble and write the HTML file:
   Combine: `html = html_body.replace('</body>', f'<script>{{data_js}}{{js_charts}}</script></body>')` \
-or similar. Write to `.anton/output/name.html` and open in browser.
+or similar.
 
   SELF-CONTAINED OUTPUT (critical):
   Prefer inlining everything — CSS in `<style>`, JS in `<script>`, data as JS variables. \
 A single .html file is the most portable and publishable format. \
 If the dataset is very large (>100KB of JSON), you may write it to a separate .js file \
-in the SAME directory (e.g. `.anton/output/dashboard_data.js`) and reference it with a \
+in the SAME directory and reference it with a \
 relative `<script src="dashboard_data.js">` tag. The publisher will auto-bundle sibling \
 files referenced in the HTML. Never reference files outside the output directory.
 
@@ -319,12 +304,7 @@
 Output format:
 - Unless the user explicitly asks for a different format, always output visualizations \
 as polished, single-file HTML pages — never raw PNGs or bare image files.
-- Save output to `.anton/output/` (create it if needed). Use descriptive filenames like \
-`cpi_portfolio.html`, not `output.html`.
-- Do NOT auto-open the file in the browser from scratchpad code. Instead, after writing \
-the HTML file, call the `publish_or_preview` tool with the file path and a short title. \
-This tool will interactively ask the user if they want to preview locally, publish to the \
-web, or skip. Let the tool handle the browser opening and publishing flow.
+{output_context}
 
 Visual design:
 - Make it look good by default. Use a dark theme (#0d1117 background, #e6edf3 text), \
@@ -369,32 +349,12 @@
 assignment. Think dark-mode dashboard, not Jupyter default.\
 """
 
-_VISUALIZATIONS_CLI_ONLY = """\
-VISUALIZATIONS AND ANALYSIS OUTPUT:
 
+# TODO: Should we remove mentions of the terminal here?
+VISUALIZATIONS_MARKDOWN_OUTPUT_FORMAT_PROMPT = """\
 Do NOT proactively create HTML dashboards, charts, or browser-based visualizations. \
 All analysis output should be formatted for the CLI terminal.
 
-Insights-first workflow — ALWAYS follow this order for analysis and reports:
-1. FETCH DATA FIRST: Use one scratchpad call to pull data and compute key metrics. Return \
-structured results (numbers, percentages, rankings).
-2. STREAM INSIGHTS IMMEDIATELY: Narrate your findings to the user in the chat. They should \
-get value within seconds. Structure insights as:
-  - DATA HIGHLIGHTS: Start with a compact summary table showing the key numbers at a glance \
-(use markdown tables). This gives the user the raw data immediately — positions, values, \
-returns, key metrics — before you interpret them.
-  - HEADLINE: One sentence, the single most important finding. Lead with impact, not description.
-  - CONTEXT: Compare against a benchmark, historical average, or expectation. Raw numbers \
-without comparison are meaningless.
-  - THE NON-OBVIOUS: What would an expert analyst notice? Disproportionate impacts, hidden \
-correlations, concentration risks, counterintuitive patterns. Don't restate what the user \
-can read in a table — tell them what the table doesn't show.
-  - ASSUMPTIONS: Be explicit. What data source? What time range? Closing vs adjusted prices? \
-Timezone? Real-time or delayed? Don't hide these — state them clearly.
-  - ACTIONABLE EDGE: What could the user do with this information? Risks to watch, \
-thresholds that matter, scenarios worth considering.
-
-CLI output format:
 - Present all results as well-formatted markdown: tables, bullet points, headers, and \
 inline numbers. The terminal is the primary display — make it look great there.
 - Use markdown tables for tabular data. Keep columns aligned and readable.
@@ -402,14 +362,58 @@
 - For large datasets, summarize the top N and offer to show more.
 - When the user EXPLICITLY asks for a chart, dashboard, plot, or HTML visualization, \
 THEN build it as a self-contained HTML file with inlined CSS, JS, and data. \
-Save to .anton/output/. Do NOT auto-open the file from scratchpad code — instead call the \
-`publish_or_preview` tool with the file path and title after writing it. \
+{output_context}
 Use Apache ECharts (CDN), dark theme (#0d1117), and follow standard dashboard best practices. \
 If the dataset is very large (>100KB), write it to a separate .js file in the same directory. \
 Never split CSS or chart logic into separate files — only large data payloads.\
 """
 
 
-def build_visualizations_prompt(proactive: bool = False) -> str:
-    """Return the visualization section for the system prompt."""
-    return _VISUALIZATIONS_PROACTIVE if proactive else _VISUALIZATIONS_CLI_ONLY
+CONSOLIDATION_PROMPT = """\
+You are a memory consolidation system for an AI coding assistant.
+
+Review this scratchpad session (sequence of code cells with their results) and
+extract durable, reusable lessons. Focus on:
+
+1. **Rules** — patterns to always/never follow:
+   - "Always call progress() before long API calls in scratchpad"
+   - "Never use time.sleep() in scratchpad cells"
+   - Conditional rules: "If fetching paginated data → use async + progress()"
+
+2. **Lessons** — factual knowledge discovered:
+   - API behaviors: "CoinGecko free tier rate-limits at ~50 req/min"
+   - Library quirks: "pandas read_csv needs encoding='utf-8-sig' for BOM files"
+   - Data facts: "Bitcoin price data via /coins/bitcoin/market_chart/range"
+
+Return a JSON array of objects:
+[
+  {
+    "text": "the memory to encode",
+    "kind": "always" | "never" | "when" | "lesson",
+    "scope": "global" | "project",
+    "topic": "optional-topic-slug",
+    "confidence": "high" | "medium"
+  }
+]
+
+Rules for scope:
+- "project": DEFAULT — use this for most memories. Anything related to the current
+  codebase, its APIs, file paths, libraries, patterns, conventions, or behaviors
+  observed during this session belongs here.
+- "global": RARE — only for truly universal knowledge that applies to any project
+  (e.g. general language quirks, stdlib gotchas). When in doubt, use "project".
+
+Rules for confidence:
+- "high": clearly correct, verified by the session results
+- "medium": probably correct but worth confirming
+
+If no meaningful lessons exist, return [].
+Do NOT extract trivial observations. Only encode genuinely reusable knowledge.
+"""
+
+RESILIENCE_NUDGE = (
+    "\n\nSYSTEM: This tool has failed twice in a row. Before retrying the same approach or "
+    "asking the user for help, try a creative workaround — different headers/user-agent, "
+    "a public API, archive.org, an alternate library, or a completely different data source. "
+    "Only involve the user if the problem truly requires something only they can provide."
+)
diff --git a/anton/llm/provider.py b/anton/core/llm/provider.py
similarity index 82%
rename from anton/llm/provider.py
rename to anton/core/llm/provider.py
index ceae40bf..ef22692e 100644
--- a/anton/llm/provider.py
+++ b/anton/core/llm/provider.py
@@ -27,6 +27,7 @@ class LLMResponse:
     usage: Usage = field(default_factory=Usage)
     stop_reason: str | None = None
 
+
 @dataclass
 class StreamTextDelta:
     text: str
@@ -57,6 +58,7 @@ class StreamComplete:
 @dataclass
 class StreamTaskProgress:
     """Progress event from agent task execution (planning, building, executing)."""
+
     phase: str
     message: str
     eta_seconds: float | None = None
@@ -65,12 +67,14 @@ class StreamTaskProgress:
 @dataclass
 class StreamToolResult:
     """Tool result that should be displayed to the user (e.g. scratchpad dump)."""
+
     content: str
 
 
 @dataclass
 class StreamContextCompacted:
     """Notification that context was compacted to free up space."""
+
     message: str
 
 
@@ -130,7 +134,23 @@ class TokenLimitExceeded(Exception):
     """Raised when the LLM returns 429 due to billing/token limits."""
 
 
+@dataclass
+class ProviderConnectionInfo:
+    """Serializable provider connection details.
+
+    `api_key` is marked repr=False to reduce accidental leakage via logs/debugging.
+    """
+
+    provider: str
+    api_key: str | None = field(default=None, repr=False)
+    base_url: str | None = None
+    ssl_verify: bool | None = None
+
+
 class LLMProvider(ABC):
+    # Human-readable provider id (e.g. "anthropic", "openai-compatible").
+    name: str = ""
+
     @abstractmethod
     async def complete(
         self,
@@ -143,6 +163,14 @@ async def complete(
         max_tokens: int = 4096,
     ) -> LLMResponse: ...
 
+    def export_connection_info(self) -> ProviderConnectionInfo:
+        """Return provider connection details for other runtimes (e.g. scratchpad).
+
+        Providers should override this to expose the minimal needed configuration
+        without relying on SDK client internals.
+        """
+        return ProviderConnectionInfo(provider=self.name)
+
     async def stream(
         self,
         *,
diff --git a/anton/core/llm/structured.py b/anton/core/llm/structured.py
new file mode 100644
index 00000000..02372c8e
--- /dev/null
+++ b/anton/core/llm/structured.py
@@ -0,0 +1,128 @@
+"""Shared schema-building / response-unwrapping for structured LLM output.
+
+Two pure helper functions that turn a Pydantic model (or `list[Model]`)
+into the inputs needed for a forced tool-call, and validate the LLM's
+response back into a typed Python instance.
+
+Used by:
+
+  - `LLMClient.generate_object` — async, planning-LLM, main process
+  - `_ScratchpadLLM.generate_object` — sync, scratchpad subprocess bridge
+
+The two call sites differ only in *how* they invoke the provider (async
+vs sync, different model/credential resolution). The schema-derivation
+and Pydantic validation logic is identical and lives here exactly once.
+
+Why a separate module
+=====================
+
+The original implementation was duplicated across `client.py` (added
+for the cerebellum) and `scratchpad_boot.py` (the existing scratchpad
+bridge). The two halves can't share a class because they live in
+different runtime contexts (main process async vs subprocess sync), but
+they CAN share pure helper functions — which is what this module
+provides. Importing this module from either side is cheap and safe;
+the subprocess already imports from `anton.core.*` at boot.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_structured_tool(schema_class) -> tuple[dict, type, bool]:
+    """Build a forced tool-call definition from a Pydantic schema.
+
+    Args:
+        schema_class: A Pydantic ``BaseModel`` subclass, OR a
+            ``list[Model]`` annotation for a homogeneous list. The
+            list-of-model case is supported by wrapping the inner
+            type in a synthetic ``_ArrayWrapper`` model with an
+            ``items`` field — many providers refuse top-level
+            arrays in tool input schemas, so the wrapper is required.
+
+    Returns:
+        A 3-tuple of:
+
+        - **tool_dict**: ready to pass as ``tools=[tool_dict]`` to
+          ``provider.complete()``. The caller should also pass
+          ``tool_choice={"type": "tool", "name": tool_dict["name"]}``
+          to force the LLM to call this specific tool.
+        - **validator_class**: the Pydantic class to call
+          ``model_validate()`` on (the wrapper for the list case,
+          the original class otherwise).
+        - **is_list**: True iff the original input was a ``list[Model]``
+          annotation. The caller uses this to decide whether to unwrap
+          the wrapper's ``items`` field after validation.
+
+    Note:
+        Pydantic is imported lazily so this module can be imported
+        without forcing pydantic to be available at import time. The
+        only operations on this module that REQUIRE pydantic are the
+        actual function calls — at which point any caller doing
+        structured output already needs pydantic anyway.
+    """
+    from pydantic import BaseModel
+
+    is_list = (
+        hasattr(schema_class, "__origin__")
+        and schema_class.__origin__ is list
+    )
+    if is_list:
+        inner_class = schema_class.__args__[0]
+
+        class _ArrayWrapper(BaseModel):
+            items: list[inner_class]  # type: ignore[valid-type]
+
+        schema = _ArrayWrapper.model_json_schema()
+        tool_name = f"{inner_class.__name__}_array"
+        validator_class: type = _ArrayWrapper
+    else:
+        schema = schema_class.model_json_schema()
+        tool_name = schema_class.__name__
+        validator_class = schema_class
+
+    tool = {
+        "name": tool_name,
+        "description": (
+            f"Generate structured output matching the {tool_name} schema."
+        ),
+        "input_schema": schema,
+    }
+    return tool, validator_class, is_list
+
+
+def unwrap_structured_response(
+    tool_call_input: dict[str, Any],
+    validator_class: type,
+    is_list: bool,
+):
+    """Validate a forced tool-call's input via Pydantic and unwrap.
+
+    Args:
+        tool_call_input: The ``.input`` dict from the LLM's ``ToolCall``.
+        validator_class: The validator class returned from
+            ``build_structured_tool``.
+        is_list: The ``is_list`` flag returned from
+            ``build_structured_tool``.
+
+    Returns:
+        A validated Pydantic instance, or a ``list[Model]`` if the
+        original schema was a list annotation.
+
+    Raises:
+        pydantic.ValidationError: If ``tool_call_input`` doesn't match
+            the schema. With forced tool_choice this is rare — the
+            provider usually rejects misshapen tool calls server-side
+            — but the validation step is the safety net.
+    """
+    validated = validator_class.model_validate(tool_call_input)
+    if is_list:
+        return validated.items  # type: ignore[attr-defined]
+    return validated
+
+
+__all__ = [
+    "build_structured_tool",
+    "unwrap_structured_response",
+]
diff --git a/anton/core/memory/__init__.py b/anton/core/memory/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/anton/core/memory/base.py b/anton/core/memory/base.py
new file mode 100644
index 00000000..26b71437
--- /dev/null
+++ b/anton/core/memory/base.py
@@ -0,0 +1,67 @@
+"""HippocampusProtocol — structural interface for memory backend swappability.
+
+The Protocol defines the public contract of a Hippocampus instance so that
+Enterprise adapters can provide alternate backends (e.g. database-backed,
+cloud-synced) without inheriting from the file-based implementation.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HippocampusProtocol(Protocol):
+    """Structural protocol for a single-scope memory store.
+
+    Implementors handle read/write at one scope (global or project).
+    The concrete ``Hippocampus`` class in ``core/memory/hippocampus.py``
+    satisfies this protocol automatically via structural sub-typing.
+    """
+
+    def recall_identity(self) -> str:
+        """Return the identity snapshot (profile.md equivalent)."""
+        ...
+
+    def recall_rules(self) -> str:
+        """Return behavioral gates (rules.md equivalent)."""
+        ...
+
+    def recall_lessons(self, token_budget: int = 1000) -> str:
+        """Return semantic facts within the given token budget."""
+        ...
+
+    def recall_topic(self, slug: str) -> str:
+        """Return deep domain expertise for a topic slug."""
+        ...
+
+    def recall_scratchpad_wisdom(self) -> str:
+        """Return procedural knowledge relevant to scratchpad execution."""
+        ...
+
+    def encode_rule(
+        self,
+        text: str,
+        kind: Literal["always", "never", "when"],
+        confidence: str = "medium",
+        source: str = "llm",
+    ) -> None:
+        """Write a behavioral gate to storage."""
+        ...
+
+    def encode_lesson(
+        self,
+        text: str,
+        topic: str = "",
+        source: str = "llm",
+    ) -> None:
+        """Write a semantic fact to storage."""
+        ...
+
+    def rewrite_identity(self, entries: list[str]) -> None:
+        """Replace the identity snapshot in full."""
+        ...
+
+    def entry_count(self) -> int:
+        """Count total entries across rules and lessons stores."""
+        ...
diff --git a/anton/core/memory/cerebellum.py b/anton/core/memory/cerebellum.py
new file mode 100644
index 00000000..c2d6bd03
--- /dev/null
+++ b/anton/core/memory/cerebellum.py
@@ -0,0 +1,385 @@
+"""Cerebellum — supervised error learning over scratchpad execution.
+
+Brain analogue
+==============
+
+The cerebellum's classical role is *forward modeling and error correction*:
+when a motor command is issued, the cerebellum predicts the expected
+sensory consequences. When actual feedback arrives, it computes the
+prediction error and uses it to refine future commands. The learning
+rule is supervised — there's an explicit "teacher" (the actual outcome)
+against which the prediction is compared.
+
+Anton's analogue
+================
+
+For Anton, the "motor command" is a scratchpad cell. Before the cell
+runs, the LLM declares its intent via the `one_line_description` field
+on the scratchpad tool. That description IS the forward model — the
+prediction of what the cell should do. After the cell runs, we have
+its actual outcome (stdout, stderr, error). The cerebellum compares
+the two and, when they diverge meaningfully, encodes a correction
+note that future code-generating LLM calls will see.
+
+Storage and retrieval
+=====================
+
+The cerebellum is a *producer* only. It does not own its own storage.
+Corrections are encoded as `Engram` objects with `kind="lesson"` and
+`topic="scratchpad"` via `Cortex.encode()`, the same path that manual
+lessons and the consolidator already use. They flow back into future
+prompts via the existing `Cortex.get_scratchpad_context()` →
+`recall_scratchpad_wisdom()` → scratchpad tool description injection
+chain. We add nothing to the storage layer — the cerebellum just
+generates new entries for the existing pipe.
+
+Decoupling
+==========
+
+This module knows nothing about scratchpad runtimes. It exposes two
+async hook methods (`on_pre_execute`, `on_post_execute`) that take a
+`Cell` object. Whoever orchestrates execution (today: the
+`handle_scratchpad` dispatcher) is responsible for calling them at the
+right moments. The runtime backends — local, future remote, future
+Docker — are completely hook-agnostic. See discussion in v2.2 design.
+
+Diff frequency
+==============
+
+The cerebellum batches its observations *per turn*, not per cell. Each
+post-execute hook only buffers the cell; the actual diff/encoding work
+runs at end-of-turn (triggered explicitly by the session, or by the
+next pre-execute call from a different turn — whichever comes first).
+This keeps cost predictable: at most one extra LLM call per
+scratchpad-using turn, regardless of how many cells the LLM ran.
+
+Cheap path
+==========
+
+Cells that complete cleanly (no error, empty stderr) contribute zero
+LLM-call cost — they're never sent to the diff function. Only cells
+that errored or warned trigger the post-turn diff.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from anton.core.backends.base import Cell
+from anton.core.memory.hippocampus import Engram
+
+if TYPE_CHECKING:
+    from anton.core.llm.client import LLMClient
+    from anton.core.memory.cortex import Cortex
+
+
+_log = logging.getLogger(__name__)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLM-facing schema (Pydantic) — used by LLMClient.generate_object
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _LessonDraft(BaseModel):
+    """One generalizable lesson the diff pass extracted from a cell."""
+
+    text: str = Field(
+        ...,
+        description=(
+            "One sentence (ideally < 25 words) the next code-writing agent "
+            "should know to avoid the same trap. Specific and actionable. "
+            "Generalizable across files/projects, not session-specific."
+        ),
+    )
+    topic: str = Field(
+        default="scratchpad",
+        description="Topic tag for retrieval. Default 'scratchpad'.",
+    )
+
+
+class _DiffPassResult(BaseModel):
+    """Wrapper schema returned by the cerebellum's diff LLM call.
+
+    The LLM is *forced* to call a tool whose input matches this schema,
+    so we never have to parse text JSON or strip markdown fences.
+    """
+
+    lessons: list[_LessonDraft] = Field(
+        default_factory=list,
+        description=(
+            "Generalizable lessons extracted from the batch. Empty list if "
+            "the cells either succeeded cleanly or didn't reveal any "
+            "reusable insight. Prefer fewer, broader lessons over many "
+            "narrow ones."
+        ),
+    )
+
+
+_DIFF_SYSTEM_PROMPT = (
+    "You are a code-execution post-mortem analyst. You receive a batch of "
+    "scratchpad cells the agent just ran in one turn — for each cell, the "
+    "agent's stated intent and what actually happened. Your job is to "
+    "extract any *generalizable* lessons that future code-writing agents "
+    "should know to avoid the same trap."
+)
+
+
+_DIFF_USER_TEMPLATE = """\
+The agent just executed the following scratchpad cells in a single turn. For each cell, you see:
+- The agent's stated intent (the `one_line_description` field on the tool call)
+- The actual result (stdout, stderr, error)
+
+Identify any *generalizable* lessons from these executions that a future code-writing agent should know to avoid the same trap. Be specific and actionable. Skip cells where everything went fine — only report lessons from genuine divergences.
+
+Cells:
+
+{cells_block}
+
+Rules:
+- Only report a lesson if the cell genuinely failed or diverged from its stated intent. If everything went fine, return an empty list.
+- Lessons should be generalizable, not session-specific. "Use low_memory=False with mixed-dtype CSVs" is good. "The file sales_q3.csv had a problem on line 12000" is bad.
+- Prefer fewer, more reusable lessons over many narrow ones.
+- Do NOT invent lessons that aren't supported by the cell evidence.
+- Each lesson should be one sentence, ideally under 25 words.
+"""
+
+
+def _format_cell_for_diff(cell: Cell, index: int) -> str:
+    """Render a single cell as a compact section for the diff prompt."""
+    lines: list[str] = [f"### Cell {index}"]
+    intent = (cell.description or "").strip() or "(no description provided)"
+    lines.append(f"**Intent:** {intent}")
+
+    code = (cell.code or "").strip()
+    if code:
+        snippet = code if len(code) <= 800 else code[:800] + "\n... [truncated]"
+        lines.append("**Code:**")
+        lines.append("```python")
+        lines.append(snippet)
+        lines.append("```")
+
+    stdout = (cell.stdout or "").strip()
+    if stdout:
+        excerpt = stdout if len(stdout) <= 500 else stdout[:500] + "\n... [truncated]"
+        lines.append(f"**stdout:** {excerpt}")
+
+    stderr = (cell.stderr or "").strip()
+    if stderr:
+        excerpt = stderr if len(stderr) <= 400 else stderr[:400] + "\n... [truncated]"
+        lines.append(f"**stderr:** {excerpt}")
+
+    error = (cell.error or "").strip() if cell.error else ""
+    if error:
+        excerpt = error if len(error) <= 400 else error[:400] + "\n... [truncated]"
+        lines.append(f"**error:** {excerpt}")
+
+    if not stdout and not stderr and not error:
+        lines.append("(no output produced)")
+
+    return "\n".join(lines)
+
+
+@dataclass
+class CerebellumLesson:
+    """A single correction extracted by the diff pass.
+
+    The dataclass form is the public type the cerebellum exposes to the
+    rest of Anton (Cell, Engram, etc. all use dataclasses). Internally,
+    the diff LLM call uses the Pydantic `_LessonDraft` schema for forced
+    structured output; we convert at the boundary.
+    """
+
+    text: str
+    topic: str = "scratchpad"
+
+
+class Cerebellum:
+    """Forward-model + error-driven learner over scratchpad cells.
+
+    Usage:
+
+        cb = Cerebellum(cortex=session._cortex, llm=session._llm)
+        # Wired into the dispatcher as a scratchpad observer:
+        await cb.on_pre_execute(prelim_cell)
+        await cb.on_post_execute(final_cell)
+        # At end of turn (or before the next pre-execute from a different turn):
+        await cb.flush()
+
+    Cells are buffered until `flush()` is called. The diff pass runs only
+    on the buffered cells that errored or warned — clean cells contribute
+    nothing. Lessons are encoded via `cortex.encode()` and flow into
+    future prompts through the existing wisdom-injection pipeline.
+    """
+
+    def __init__(
+        self,
+        *,
+        cortex: "Cortex | None",
+        llm: "LLMClient | None",
+        max_lessons_per_flush: int = 3,
+    ) -> None:
+        self._cortex = cortex
+        self._llm = llm
+        self._max_lessons = max_lessons_per_flush
+        # Cells observed since the last flush. Indexed by insertion order.
+        self._buffered: list[Cell] = []
+        # Optional intent capture from pre-execute. Today we just trust the
+        # cell that arrives at post_execute, but pre_execute is also a
+        # natural place to clear stale buffers from prior cancelled turns.
+        self._pre_count: int = 0
+
+    # ── observer hooks ─────────────────────────────────────────────
+
+    async def on_pre_execute(self, cell: Cell) -> None:
+        """Called by the dispatcher right before a cell is sent to the runtime.
+
+        The cell here is preliminary — code + description are populated,
+        but stdout/stderr/error are empty. We don't currently use the
+        prelim cell directly (the LLM's intent is already captured in
+        cell.description, which post_execute will see again), but the
+        hook exists so future expansions can do real forward-model work.
+        """
+        self._pre_count += 1
+
+    async def on_post_execute(self, cell: Cell) -> None:
+        """Called by the dispatcher right after a cell finishes executing.
+
+        We buffer the cell here. The actual diff/encode work runs in
+        flush() — see class docstring for the batching rationale.
+        """
+        # Cheap path: clean cells never need diffing
+        if self._is_clean(cell):
+            return
+        self._buffered.append(cell)
+
+    async def flush(self) -> list[CerebellumLesson]:
+        """Run the batched diff pass and encode any extracted lessons.
+
+        Should be called at end-of-turn. Safe to call when the buffer is
+        empty (returns []). Safe to call multiple times (idempotent — the
+        buffer is cleared each time).
+
+        Returns the lessons that were encoded, mostly for testing /
+        observability. Production code typically ignores the return value.
+        """
+        if not self._buffered:
+            return []
+        if self._cortex is None or self._llm is None:
+            # Best-effort: silently no-op if memory infrastructure is missing
+            self._buffered.clear()
+            return []
+
+        cells = self._buffered[:]
+        self._buffered.clear()
+
+        try:
+            lessons = await self._run_diff(cells)
+        except Exception as exc:
+            _log.warning("cerebellum diff pass failed: %s", exc)
+            return []
+
+        if not lessons:
+            return []
+
+        try:
+            await self._encode_lessons(lessons)
+        except Exception as exc:
+            _log.warning("cerebellum failed to encode lessons: %s", exc)
+
+        return lessons
+
+    def reset(self) -> None:
+        """Drop the current buffer without encoding anything.
+
+        Used when a turn is cancelled mid-flight — we don't want to
+        encode lessons from a turn the user backed out of.
+        """
+        self._buffered.clear()
+        self._pre_count = 0
+
+    @property
+    def buffered_count(self) -> int:
+        """Number of cells currently waiting for the next flush."""
+        return len(self._buffered)
+
+    # ── internals ──────────────────────────────────────────────────
+
+    @staticmethod
+    def _is_clean(cell: Cell) -> bool:
+        """A cell is 'clean' if it produced no error and no stderr text.
+
+        Clean cells contribute zero diff cost — they're skipped before
+        the LLM call ever happens. This is the cheap path that keeps
+        the cerebellum's overhead near zero on a happy-path turn.
+        """
+        if cell.error:
+            return False
+        stderr = (cell.stderr or "").strip()
+        if stderr:
+            return False
+        return True
+
+    async def _run_diff(self, cells: list[Cell]) -> list[CerebellumLesson]:
+        """Send the buffered cells to the LLM and return validated lessons.
+
+        Uses `LLMClient.generate_object_code` (the cheap/fast coding
+        provider) to force structured output via a forced tool call
+        whose schema is the `_DiffPassResult` Pydantic model. There's
+        no manual JSON parsing, no markdown fence stripping, and no
+        try/except around `json.loads` — Pydantic and the forced
+        tool_choice eliminate those failure modes entirely. If the
+        LLM round-trip itself fails (network, validation), the
+        caller's try/except in `flush()` swallows it.
+
+        We use the *coding* provider (not planning) because this is a
+        fast post-mortem on cell output — exactly the kind of cheap
+        structured task the coding model is sized for.
+        """
+        cells_block = "\n\n".join(
+            _format_cell_for_diff(c, i + 1) for i, c in enumerate(cells)
+        )
+        prompt = _DIFF_USER_TEMPLATE.format(cells_block=cells_block)
+
+        result: _DiffPassResult = await self._llm.generate_object_code(
+            _DiffPassResult,
+            system=_DIFF_SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=600,
+        )
+
+        # Convert the validated Pydantic drafts to the public dataclass
+        # form. Cap at max_lessons_per_flush to bound the encoding cost
+        # of any single flush.
+        out: list[CerebellumLesson] = []
+        for draft in result.lessons[: self._max_lessons]:
+            text = (draft.text or "").strip()
+            if not text:
+                continue
+            topic = (draft.topic or "scratchpad").strip() or "scratchpad"
+            out.append(CerebellumLesson(text=text, topic=topic))
+        return out
+
+    async def _encode_lessons(self, lessons: list[CerebellumLesson]) -> None:
+        """Hand the lessons to Cortex for storage in the existing pipeline."""
+        engrams = [
+            Engram(
+                text=lesson.text,
+                kind="lesson",
+                scope="project",
+                confidence="medium",
+                topic=lesson.topic,
+                source="consolidation",
+            )
+            for lesson in lessons
+        ]
+        if not engrams:
+            return
+        await self._cortex.encode(engrams)
+
+
+__all__ = ["Cerebellum", "CerebellumLesson"]
diff --git a/anton/memory/consolidator.py b/anton/core/memory/consolidator.py
similarity index 55%
rename from anton/memory/consolidator.py
rename to anton/core/memory/consolidator.py
index d5ccecda..91f226d0 100644
--- a/anton/memory/consolidator.py
+++ b/anton/core/memory/consolidator.py
@@ -22,57 +22,70 @@
 
 from __future__ import annotations
 
-import json
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
-from anton.memory.hippocampus import Engram
+from pydantic import BaseModel, Field
+
+from anton.core.llm.prompts import CONSOLIDATION_PROMPT
+from anton.core.memory.hippocampus import Engram
 
 if TYPE_CHECKING:
-    from anton.llm.client import LLMClient
-    from anton.scratchpad import Cell
-
-
-_CONSOLIDATION_PROMPT = """\
-You are a memory consolidation system for an AI coding assistant.
-
-Review this scratchpad session (sequence of code cells with their results) and
-extract durable, reusable lessons. Focus on:
-
-1. **Rules** — patterns to always/never follow:
-   - "Always call progress() before long API calls in scratchpad"
-   - "Never use time.sleep() in scratchpad cells"
-   - Conditional rules: "If fetching paginated data → use async + progress()"
-
-2. **Lessons** — factual knowledge discovered:
-   - API behaviors: "CoinGecko free tier rate-limits at ~50 req/min"
-   - Library quirks: "pandas read_csv needs encoding='utf-8-sig' for BOM files"
-   - Data facts: "Bitcoin price data via /coins/bitcoin/market_chart/range"
-
-Return a JSON array of objects:
-[
-  {
-    "text": "the memory to encode",
-    "kind": "always" | "never" | "when" | "lesson",
-    "scope": "global" | "project",
-    "topic": "optional-topic-slug",
-    "confidence": "high" | "medium"
-  }
-]
-
-Rules for scope:
-- "project": DEFAULT — use this for most memories. Anything related to the current
-  codebase, its APIs, file paths, libraries, patterns, conventions, or behaviors
-  observed during this session belongs here.
-- "global": RARE — only for truly universal knowledge that applies to any project
-  (e.g. general language quirks, stdlib gotchas). When in doubt, use "project".
-
-Rules for confidence:
-- "high": clearly correct, verified by the session results
-- "medium": probably correct but worth confirming
-
-If no meaningful lessons exist, return [].
-Do NOT extract trivial observations. Only encode genuinely reusable knowledge.
-"""
+    from anton.core.llm.client import LLMClient
+    from anton.core.backends.base import Cell
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLM-facing schema (Pydantic) — used by LLMClient.generate_object_code
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _ConsolidatedLesson(BaseModel):
+    """One engram extracted from a scratchpad replay."""
+
+    text: str = Field(
+        ...,
+        description=(
+            "The lesson itself — what a future agent should know to do "
+            "this kind of task better. Concrete and actionable."
+        ),
+    )
+    kind: Literal["always", "never", "when", "lesson"] = Field(
+        default="lesson",
+        description=(
+            "Engram type. 'always'/'never' = behavioral rules, "
+            "'when' = conditional rule, 'lesson' = semantic fact."
+        ),
+    )
+    scope: Literal["global", "project"] = Field(
+        default="project",
+        description=(
+            "'global' = applies across all projects, 'project' = "
+            "specific to this codebase. Default project."
+        ),
+    )
+    confidence: Literal["high", "medium", "low"] = Field(
+        default="medium",
+        description=(
+            "How confident you are this lesson generalizes. 'high' "
+            "auto-encodes; 'medium'/'low' may require user confirmation."
+        ),
+    )
+    topic: str = Field(
+        default="",
+        description="Optional topic tag for retrieval grouping.",
+    )
+
+
+class _ConsolidatedLessons(BaseModel):
+    """Wrapper for the list of lessons returned by the consolidator."""
+
+    items: list[_ConsolidatedLesson] = Field(
+        default_factory=list,
+        description=(
+            "Lessons extracted from the scratchpad replay. Empty list "
+            "if nothing worth remembering. Cap at ~5 — be selective."
+        ),
+    )
 
 
 class Consolidator:
@@ -109,12 +122,16 @@ def should_replay(self, cells: list[Cell]) -> bool:
 
         # Check for cancellation markers in stderr
         for cell in cells:
-            if cell.stderr and ("cancelled" in cell.stderr.lower() or "killed" in cell.stderr.lower()):
+            if cell.stderr and (
+                "cancelled" in cell.stderr.lower() or "killed" in cell.stderr.lower()
+            ):
                 return True
 
         return False
 
-    async def replay_and_extract(self, cells: list[Cell], llm_client: LLMClient) -> list[Engram]:
+    async def replay_and_extract(
+        self, cells: list[Cell], llm_client: LLMClient
+    ) -> list[Engram]:
         """Replay the scratchpad session and extract lessons.
 
         Like SWS replay: compresses the full session into a compact summary,
@@ -148,52 +165,30 @@ async def replay_and_extract(self, cells: list[Cell], llm_client: LLMClient) ->
         session_summary = "\n".join(summary_lines)
 
         try:
-            response = await llm_client.code(
-                system=_CONSOLIDATION_PROMPT,
+            result: _ConsolidatedLessons = await llm_client.generate_object_code(
+                _ConsolidatedLessons,
+                system=CONSOLIDATION_PROMPT,
                 messages=[{"role": "user", "content": session_summary}],
                 max_tokens=2048,
             )
-
-            raw = response.content.strip()
-            # Handle markdown code fences
-            if raw.startswith("```"):
-                raw = raw.split("\n", 1)[1] if "\n" in raw else raw[3:]
-                if raw.endswith("```"):
-                    raw = raw[:-3]
-                raw = raw.strip()
-
-            items = json.loads(raw)
-            if not isinstance(items, list):
-                return []
-
         except Exception:
             return []
 
         engrams: list[Engram] = []
-        for item in items:
-            if not isinstance(item, dict) or "text" not in item:
+        for item in result.items:
+            text = (item.text or "").strip()
+            if not text:
                 continue
-
-            kind = item.get("kind", "lesson")
-            if kind not in ("always", "never", "when", "lesson"):
-                kind = "lesson"
-
-            scope = item.get("scope", "project")
-            if scope not in ("global", "project"):
-                scope = "project"
-
-            confidence = item.get("confidence", "medium")
-            if confidence not in ("high", "medium", "low"):
-                confidence = "medium"
-
-            engrams.append(Engram(
-                text=item["text"],
-                kind=kind,
-                scope=scope,
-                confidence=confidence,
-                topic=item.get("topic", ""),
-                source="consolidation",
-            ))
+            engrams.append(
+                Engram(
+                    text=text,
+                    kind=item.kind,
+                    scope=item.scope,
+                    confidence=item.confidence,
+                    topic=item.topic,
+                    source="consolidation",
+                )
+            )
 
         # Cap extraction to prevent memory bloat from single sessions
         return engrams[:5]
diff --git a/anton/memory/cortex.py b/anton/core/memory/cortex.py
similarity index 77%
rename from anton/memory/cortex.py
rename to anton/core/memory/cortex.py
index 4a3d185c..6d344dac 100644
--- a/anton/memory/cortex.py
+++ b/anton/core/memory/cortex.py
@@ -13,36 +13,79 @@
   - encode() → executive decision to encode (directing the hippocampus)
   - encoding_gate() → encoding gate modulated by the memory mode
 
-The Cortex coordinates two Hippocampus instances (global + project scope),
+The Cortex coordinates two HippocampusProtocol instances (global + project scope),
 like how the PFC coordinates retrieval from multiple brain memory systems.
 """
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from anton.memory.hippocampus import Engram, Hippocampus
+from pydantic import BaseModel, Field
+
+from anton.core.memory.base import HippocampusProtocol
+from anton.core.memory.hippocampus import Engram, Hippocampus
 
 if TYPE_CHECKING:
-    from anton.llm.client import LLMClient
+    from anton.core.llm.client import LLMClient
 
 
-_IDENTITY_EXTRACT_PROMPT = """\
-Extract identity facts from this user message. Return a JSON array of strings,
-each a concise fact about the user (name, timezone, expertise, preferences, tools).
+# ─────────────────────────────────────────────────────────────────────────────
+# Pydantic schemas — used by LLMClient.generate_object
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _IdentityFacts(BaseModel):
+    """Result of the identity-extraction LLM call.
+
+    Each fact is a concise statement about the user (name, timezone,
+    expertise, preferences, tools). Empty list when nothing relevant
+    is found in the message.
+    """
+
+    facts: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Identity facts extracted from the user message. Each fact "
+            "is a concise statement about the user. Examples: "
+            "'Name: Jorge', 'Timezone: PST', 'Prefers dark mode', "
+            "'Uses uv over pip'. Only extract facts that are clearly "
+            "about the user's identity, preferences, or working style. "
+            "Ignore transient conversation details. Return an empty list "
+            "if nothing identity-relevant is found."
+        ),
+    )
+
+
+class _CompactionResult(BaseModel):
+    """Result of the memory-compaction LLM call.
+
+    Returns the deduplicated entries to keep, plus optional metadata
+    about what was merged and pruned (purely for logging — the cortex
+    only acts on `kept`).
+    """
 
-If no identity-relevant information is found, return [].
+    kept: list[str] = Field(
+        ...,
+        description=(
+            "Entry strings to keep after compaction. Preserve the "
+            "trailing `<!-- ... -->` metadata comment on each entry "
+            "exactly as it appears in the input."
+        ),
+    )
+    merged: list[str] = Field(
+        default_factory=list,
+        description="Strings describing what was merged (for logging).",
+    )
+    pruned: list[str] = Field(
+        default_factory=list,
+        description="Strings describing what was removed and why (for logging).",
+    )
 
-Examples of identity facts:
-- "Name: Jorge"
-- "Timezone: PST"
-- "Prefers dark mode"
-- "Uses uv over pip"
 
-Only extract facts that are clearly about the user's identity, preferences,
-or working style. Ignore transient conversation details.
+_IDENTITY_EXTRACT_PROMPT = """\
+Extract identity facts from this user message — concise statements about the user (name, timezone, expertise, preferences, tools). Only extract facts that are clearly about the user's identity, preferences, or working style. Ignore transient conversation details. Return an empty list if nothing identity-relevant is found.
 """
 
 _COMPACTION_PROMPT = """\
@@ -52,40 +95,35 @@
 3. Remove entries that are superseded by newer, more specific entries
 4. Keep all unique, useful entries
 
-Return a JSON object with:
-- "kept": array of entry strings to keep — preserve the trailing `<!-- ... -->` metadata comment on each entry exactly as it appears
-- "merged": array of strings describing what was merged
-- "pruned": array of strings describing what was removed and why
-
-Be conservative — when in doubt, keep the entry.
+Be conservative — when in doubt, keep the entry. Preserve the trailing `<!-- ... -->` metadata comment on each kept entry exactly as it appears.
 """
 
 
 class Cortex:
     """Executive coordinator for Anton's memory systems.
 
-    Manages two Hippocampus instances (global + project scope), decides what
+    Manages two HippocampusProtocol instances (global + project scope), decides what
     memories to load into working memory (the context window), and gates
     encoding based on the current memory mode (the neuromodulatory setting).
     """
 
     def __init__(
         self,
-        global_dir: Path,
-        project_dir: Path,
+        global_hc: HippocampusProtocol,
+        project_hc: HippocampusProtocol,
         mode: str = "autopilot",
         llm_client: LLMClient | None = None,
     ) -> None:
         """Initialize the executive with two hippocampal stores.
 
         Args:
-            global_dir: Path to ~/.anton/memory/ (cross-project memories)
-            project_dir: Path to <project>/.anton/memory/ (project-specific)
+            global_hc: Memory store for cross-project memories (global scope)
+            project_hc: Memory store for project-specific memories
             mode: Memory mode — autopilot|copilot|off (encoding gate)
             llm_client: For LLM-assisted operations (profile extraction, compaction)
         """
-        self.global_hc = Hippocampus(global_dir)
-        self.project_hc = Hippocampus(project_dir)
+        self.global_hc = global_hc
+        self.project_hc = project_hc
         self.mode = mode
         self._llm = llm_client
         self._turn_count = 0
@@ -120,14 +158,18 @@ async def build_memory_context(self, user_message: str = "") -> str:
         # 2. Global rules (with smart retrieval)
         global_rules = self.global_hc.recall_rules()
         if global_rules:
-            global_rules = await self._retrieve_relevant_rules(global_rules, user_message)
+            global_rules = await self._retrieve_relevant_rules(
+                global_rules, user_message
+            )
             if global_rules:
                 sections.append(f"## Your Memory — Global Rules\n{global_rules}")
 
         # 3. Project rules (with smart retrieval)
         project_rules = self.project_hc.recall_rules()
         if project_rules:
-            project_rules = await self._retrieve_relevant_rules(project_rules, user_message)
+            project_rules = await self._retrieve_relevant_rules(
+                project_rules, user_message
+            )
             if project_rules:
                 sections.append(f"## Your Memory — Project Rules\n{project_rules}")
 
@@ -201,10 +243,12 @@ async def _retrieve_relevant_rules(self, all_rules: str, user_message: str) -> s
         try:
             response = await self._llm.code(
                 system=self._RULES_RETRIEVAL_PROMPT,
-                messages=[{
-                    "role": "user",
-                    "content": f"User message: {user_message}\n\nRules:\n{when_text}",
-                }],
+                messages=[
+                    {
+                        "role": "user",
+                        "content": f"User message: {user_message}\n\nRules:\n{when_text}",
+                    }
+                ],
                 max_tokens=4096,
             )
             result = response.content.strip()
@@ -333,6 +377,8 @@ async def compact_all(self) -> None:
             return
 
         for hc in (self.global_hc, self.project_hc):
+            if not isinstance(hc, Hippocampus):
+                continue  # compaction is file-specific; non-file backends skip
             if hc.entry_count() > self._COMPACTION_THRESHOLD:
                 await self._compact_file(hc, hc._lessons_path, "lesson")
                 await self._compact_file(hc, hc._rules_path, "rules")
@@ -346,6 +392,8 @@ async def vacuum(self) -> None:
         if self._llm is None:
             return
         for hc in (self.global_hc, self.project_hc):
+            if not isinstance(hc, Hippocampus):
+                continue  # compaction is file-specific; non-file backends skip
             await self._compact_file(hc, hc._lessons_path, "lesson")
             await self._compact_file(hc, hc._rules_path, "rules")
 
@@ -370,19 +418,21 @@ async def _compact_file(self, hc: Hippocampus, path: Path, kind: str) -> None:
             return
 
         content = path.read_text(encoding="utf-8")
-        entries = [ln.strip() for ln in content.splitlines() if ln.strip().startswith("- ")]
+        entries = [
+            ln.strip() for ln in content.splitlines() if ln.strip().startswith("- ")
+        ]
 
         if len(entries) < 8:
             return
 
         try:
-            response = await self._llm.code(
+            result: _CompactionResult = await self._llm.generate_object_code(
+                _CompactionResult,
                 system=_COMPACTION_PROMPT,
                 messages=[{"role": "user", "content": "\n".join(entries)}],
                 max_tokens=4096,
             )
-            result = json.loads(response.content)
-            kept = result.get("kept", entries)
+            kept = result.kept or entries
         except Exception:
             return  # Don't corrupt memory on failure
 
@@ -392,9 +442,12 @@ async def _compact_file(self, hc: Hippocampus, path: Path, kind: str) -> None:
         # Rebuild the file
         if kind == "rules":
             # Preserve section structure
-            always = [e for e in kept if "always" in e.lower() or not any(
-                k in e.lower() for k in ("never", "when", "if ")
-            )]
+            always = [
+                e
+                for e in kept
+                if "always" in e.lower()
+                or not any(k in e.lower() for k in ("never", "when", "if "))
+            ]
             never = [e for e in kept if "never" in e.lower()]
             when_rules = [e for e in kept if "when" in e.lower() or "if " in e.lower()]
 
@@ -423,13 +476,14 @@ async def maybe_update_identity(self, user_message: str) -> None:
             return
 
         try:
-            response = await self._llm.code(
+            result: _IdentityFacts = await self._llm.generate_object_code(
+                _IdentityFacts,
                 system=_IDENTITY_EXTRACT_PROMPT,
                 messages=[{"role": "user", "content": user_message}],
                 max_tokens=512,
             )
-            facts = json.loads(response.content)
-            if not isinstance(facts, list) or not facts:
+            facts = result.facts
+            if not facts:
                 return
         except Exception:
             return
@@ -452,7 +506,8 @@ async def maybe_update_identity(self, user_message: str) -> None:
                 key = fact.split(":")[0].strip().lower() if ":" in fact else ""
                 if key:
                     existing_entries = [
-                        e for e in existing_entries
+                        e
+                        for e in existing_entries
                         if not e.lower().startswith(key + ":")
                     ]
                 existing_entries.append(fact)
diff --git a/anton/memory/episodes.py b/anton/core/memory/episodes.py
similarity index 94%
rename from anton/memory/episodes.py
rename to anton/core/memory/episodes.py
index 339fd135..24a1c6f1 100644
--- a/anton/memory/episodes.py
+++ b/anton/core/memory/episodes.py
@@ -37,7 +37,6 @@ def __init__(self, episodes_dir: Path, *, enabled: bool = True) -> None:
         self._session_id: str | None = None
         self._file: Path | None = None
 
-
     @property
     def enabled(self) -> bool:
         return self._enabled
@@ -75,6 +74,7 @@ def log(self, episode: Episode) -> None:
             with self._file.open("a", encoding="utf-8") as f:
                 if sys.platform != "win32":
                     import fcntl
+
                     fcntl.flock(f, fcntl.LOCK_EX)
                     f.write(line)
                     fcntl.flock(f, fcntl.LOCK_UN)
@@ -99,14 +99,16 @@ def log_turn(
         elif role == "tool_result":
             content = content[:_MAX_TOOL_RESULT]
 
-        self.log(Episode(
-            ts=datetime.now(timezone.utc).isoformat(),
-            session=self._session_id,
-            turn=turn,
-            role=role,
-            content=content,
-            meta=dict(meta),
-        ))
+        self.log(
+            Episode(
+                ts=datetime.now(timezone.utc).isoformat(),
+                session=self._session_id,
+                turn=turn,
+                role=role,
+                content=content,
+                meta=dict(meta),
+            )
+        )
 
     def recall(
         self,
@@ -214,7 +216,9 @@ def recall_formatted(
         lines: list[str] = []
         for ep in episodes:
             # Show more content for assistant/scratchpad responses
-            max_len = 2000 if ep.role in ("assistant", "scratchpad", "tool_result") else 500
+            max_len = (
+                2000 if ep.role in ("assistant", "scratchpad", "tool_result") else 500
+            )
             lines.append(f"[{ep.ts}] ({ep.role}) {ep.content[:max_len]}")
         return "\n".join(lines)
 
diff --git a/anton/memory/hippocampus.py b/anton/core/memory/hippocampus.py
similarity index 98%
rename from anton/memory/hippocampus.py
rename to anton/core/memory/hippocampus.py
index 4bea725e..9134a301 100644
--- a/anton/memory/hippocampus.py
+++ b/anton/core/memory/hippocampus.py
@@ -64,7 +64,6 @@ def __init__(self, base_dir: Path) -> None:
         self._lessons_path = base_dir / "lessons.md"
         self._topics_dir = base_dir / "topics"
 
-
     def recall_identity(self) -> str:
         """Load the always-on self-model (profile.md).
 
@@ -247,7 +246,8 @@ def encode_rule(
                 i += 1
                 section_entries: list[str] = []
                 while i < len(lines) and not (
-                    lines[i].strip().startswith("## ") and lines[i].strip() != section_header
+                    lines[i].strip().startswith("## ")
+                    and lines[i].strip() != section_header
                 ):
                     section_entries.append(lines[i])
                     i += 1
@@ -333,7 +333,9 @@ def entry_count(self) -> int:
             if path.is_file():
                 try:
                     content = path.read_text(encoding="utf-8")
-                    count += sum(1 for ln in content.splitlines() if ln.strip().startswith("- "))
+                    count += sum(
+                        1 for ln in content.splitlines() if ln.strip().startswith("- ")
+                    )
                 except (OSError, UnicodeDecodeError):
                     continue
         return count
@@ -353,6 +355,7 @@ def _encode_with_lock(self, path: Path, text: str, mode: str = "append") -> None
             with open(tmp_path, "w", encoding="utf-8") as f:
                 if sys.platform != "win32":
                     import fcntl
+
                     fcntl.flock(f.fileno(), fcntl.LOCK_EX)
                 try:
                     f.write(text)
@@ -360,6 +363,7 @@ def _encode_with_lock(self, path: Path, text: str, mode: str = "append") -> None
                 finally:
                     if sys.platform != "win32":
                         import fcntl
+
                         fcntl.flock(f.fileno(), fcntl.LOCK_UN)
             tmp_path.replace(path)
         else:
@@ -367,6 +371,7 @@ def _encode_with_lock(self, path: Path, text: str, mode: str = "append") -> None
             with open(path, "a", encoding="utf-8") as f:
                 if sys.platform != "win32":
                     import fcntl
+
                     fcntl.flock(f.fileno(), fcntl.LOCK_EX)
                 try:
                     f.write(text)
@@ -374,6 +379,7 @@ def _encode_with_lock(self, path: Path, text: str, mode: str = "append") -> None
                 finally:
                     if sys.platform != "win32":
                         import fcntl
+
                         fcntl.flock(f.fileno(), fcntl.LOCK_UN)
 
     @staticmethod
diff --git a/anton/core/memory/skills.py b/anton/core/memory/skills.py
new file mode 100644
index 00000000..0d0b1a87
--- /dev/null
+++ b/anton/core/memory/skills.py
@@ -0,0 +1,422 @@
+"""Procedural memory: skills as multi-stage directories.
+
+A *skill* is one concept with multiple representations that coexist:
+
+  - Stage 1 (declarative.md) — step-by-step procedure the LLM reads. Always present.
+  - Stage 2 (chunks.md)      — higher-level recipes/macros. Emerges from use. (v2+)
+  - Stage 3 (code/)          — runnable helper modules. Emerges from reliability. (v2+)
+
+Each skill lives at `~/.anton/skills/<label>/` as a directory:
+
+    ~/.anton/skills/csv_summary/
+    ├── meta.json          # label, name, description, when_to_use, provenance, presence flags
+    ├── declarative.md     # Stage 1 — required
+    ├── chunks.md          # Stage 2 — optional
+    ├── code/              # Stage 3 — optional
+    │   └── __init__.py
+    ├── requirements.txt   # Stage 3 deps — optional
+    └── stats.json         # per-stage usage counters
+
+This module is the storage layer only — read/write/search. The classifier
+(`recall_skill` tool) and the LLM-driven save command live elsewhere.
+
+Brain analogue: cortico-striatal procedural memory. The executive (PFC)
+recognizes a familiar pattern in the user's request, retrieves the
+matching procedure from the striatum, and executes it. Stages coexist
+rather than graduating — the executive picks the highest stage that's
+reliable enough for the current context.
+
+Relationship to `Engram` (anton/core/memory/hippocampus.py):
+    `Engram` is the unit of *declarative* memory in Anton — a single
+    fact, rule, or lesson stored as a flat bullet in rules.md / lessons.md /
+    profile.md. Engrams are loaded into every prompt unconditionally because
+    they're cheap (one line each). The brain-region analogue is the
+    hippocampus → neocortex consolidation pathway.
+
+    `Skill` is the unit of *procedural* memory in Anton — a multi-step
+    workflow stored as a directory of staged representations. Skills are
+    NOT loaded into every prompt; the LLM sees only their compact label +
+    when_to_use line and explicitly retrieves the full procedure via the
+    `recall_skill` tool when it recognizes a match. The brain-region
+    analogue is the hippocampus → striatum / cerebellum pathway.
+
+    Both systems coexist in the brain (declarative and procedural memory
+    are dissociable — H.M. lost the former but kept the latter), and they
+    coexist in Anton. Engrams hold facts; Skills hold procedures.
+
+Naming note:
+    The unique identifier for a skill is called its `label`. In cognitive
+    psychology this is the declarative handle by which a procedural
+    memory is addressed in working memory — the verbal token the
+    executive holds when deciding to invoke a stored procedure. It is
+    deliberately distinct from `name` (the human-readable display) and
+    `when_to_use` (the retrieval cue describing the matching context).
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import re
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+_DEFAULT_SKILLS_ROOT = Path("~/.anton/skills").expanduser()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Data classes
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class StageStats:
+    """Per-stage usage tracking.
+
+    `recommended` increments every time the classifier (recall_skill tool)
+    pulls this stage into context. `used` increments when scratchpad code
+    actually imports a Stage 3 helper — Stage 1 and Stage 2 only have a
+    `recommended` signal because there's no mechanical way to detect
+    whether the LLM "followed" a markdown procedure.
+    """
+
+    recommended: int = 0
+    used: int = 0
+    last_used: str = ""  # ISO timestamp
+    confidence: float = 0.0
+
+
+@dataclass
+class SkillStats:
+    total_recalls: int = 0
+    stage_1: StageStats = field(default_factory=StageStats)
+    stage_2: StageStats = field(default_factory=StageStats)
+    stage_3: StageStats = field(default_factory=StageStats)
+
+
+@dataclass
+class Skill:
+    """In-memory representation of a skill directory.
+
+    Always carries the metadata. The Stage 1 markdown is loaded eagerly
+    because it's small and almost always needed. Stage 2 and Stage 3
+    content (when present) is loaded on demand by callers.
+
+    The `label` is the declarative handle for this procedural memory —
+    the snake_case identifier the LLM uses when it calls
+    `recall_skill(label)`. It is the directory name on disk.
+    """
+
+    label: str
+    name: str
+    description: str
+    when_to_use: str
+    declarative_md: str
+    created_at: str
+    provenance: str  # "manual" | "consolidator" (future)
+    stage_1_present: bool = True
+    stage_2_present: bool = False
+    stage_3_present: bool = False
+    stats: SkillStats = field(default_factory=SkillStats)
+
+    def to_meta_dict(self) -> dict:
+        """Serialize the meta.json payload (excludes declarative content + stats)."""
+        return {
+            "label": self.label,
+            "name": self.name,
+            "description": self.description,
+            "when_to_use": self.when_to_use,
+            "created_at": self.created_at,
+            "provenance": self.provenance,
+            "stage_1_present": self.stage_1_present,
+            "stage_2_present": self.stage_2_present,
+            "stage_3_present": self.stage_3_present,
+        }
+
+    def to_stats_dict(self) -> dict:
+        return {
+            "total_recalls": self.stats.total_recalls,
+            "stage_1": _stage_stats_to_dict(self.stats.stage_1),
+            "stage_2": _stage_stats_to_dict(self.stats.stage_2),
+            "stage_3": _stage_stats_to_dict(self.stats.stage_3),
+        }
+
+
+def _stage_stats_to_dict(s: StageStats) -> dict:
+    return {
+        "recommended": s.recommended,
+        "used": s.used,
+        "last_used": s.last_used,
+        "confidence": s.confidence,
+    }
+
+
+def _stage_stats_from_dict(d: dict) -> StageStats:
+    return StageStats(
+        recommended=int(d.get("recommended", 0)),
+        used=int(d.get("used", 0)),
+        last_used=str(d.get("last_used", "")),
+        confidence=float(d.get("confidence", 0.0)),
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Slug helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+_SLUG_RE = re.compile(r"[^a-z0-9_]+")
+
+
+def slugify(text: str) -> str:
+    """Normalize arbitrary text into a snake_case identifier.
+
+    Strips non-alphanumerics, lowercases, collapses runs of underscores.
+    Empty input becomes 'skill'. Used to produce path/URL-safe labels;
+    the term "slugify" refers to the formatting operation, not to the
+    semantic role of the result (which we call a `label`).
+    """
+    s = text.strip().lower().replace("-", "_").replace(" ", "_")
+    s = _SLUG_RE.sub("_", s)
+    s = re.sub(r"_+", "_", s).strip("_")
+    return s or "skill"
+
+
+def make_unique_label(base: str, store: "SkillStore") -> str:
+    """Return a label that doesn't collide with any existing skill.
+
+    If `base` (after slugify normalization) is already unique, return it
+    as-is. Otherwise append `_2`, `_3`, ... until a free slot is found.
+    """
+    candidate = slugify(base)
+    if store.load(candidate) is None:
+        return candidate
+    n = 2
+    while True:
+        next_candidate = f"{candidate}_{n}"
+        if store.load(next_candidate) is None:
+            return next_candidate
+        n += 1
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Store
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class SkillStore:
+    """File-backed store of skills under `~/.anton/skills/` (by default).
+
+    Each skill is a directory whose name is its `label` (the snake_case
+    declarative handle). The store is stateless — it reads from disk on
+    demand. Callers should not cache Skill instances long-term, since
+    stats are mutated through the store's increment helpers and a stale
+    in-memory copy will drift.
+    """
+
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = Path(root) if root is not None else _DEFAULT_SKILLS_ROOT
+
+    # ── reading ─────────────────────────────────────────────────────
+
+    def _skill_dir(self, label: str) -> Path:
+        return self.root / label
+
+    def _ensure_root(self) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def load(self, label: str) -> Skill | None:
+        """Read a single skill by label. Returns None if absent or malformed."""
+        d = self._skill_dir(label)
+        meta_path = d / "meta.json"
+        decl_path = d / "declarative.md"
+        if not meta_path.is_file() or not decl_path.is_file():
+            return None
+        try:
+            meta = json.loads(meta_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return None
+        try:
+            declarative = decl_path.read_text(encoding="utf-8")
+        except OSError:
+            return None
+        stats = self._load_stats(label)
+        return Skill(
+            label=str(meta.get("label", label)),
+            name=str(meta.get("name", label)),
+            description=str(meta.get("description", "")),
+            when_to_use=str(meta.get("when_to_use", "")),
+            declarative_md=declarative,
+            created_at=str(meta.get("created_at", "")),
+            provenance=str(meta.get("provenance", "manual")),
+            stage_1_present=bool(meta.get("stage_1_present", True)),
+            stage_2_present=bool(meta.get("stage_2_present", False)),
+            stage_3_present=bool(meta.get("stage_3_present", False)),
+            stats=stats,
+        )
+
+    def _load_stats(self, label: str) -> SkillStats:
+        path = self._skill_dir(label) / "stats.json"
+        if not path.is_file():
+            return SkillStats()
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return SkillStats()
+        return SkillStats(
+            total_recalls=int(data.get("total_recalls", 0)),
+            stage_1=_stage_stats_from_dict(data.get("stage_1", {})),
+            stage_2=_stage_stats_from_dict(data.get("stage_2", {})),
+            stage_3=_stage_stats_from_dict(data.get("stage_3", {})),
+        )
+
+    def list_all(self) -> list[Skill]:
+        """Return every loadable skill, sorted by label."""
+        if not self.root.is_dir():
+            return []
+        out: list[Skill] = []
+        for child in sorted(self.root.iterdir()):
+            if not child.is_dir():
+                continue
+            skill = self.load(child.name)
+            if skill is not None:
+                out.append(skill)
+        return out
+
+    def list_summaries(self) -> list[dict]:
+        """Lightweight listing for prompt-building — label + when_to_use only.
+
+        Avoids reading declarative.md for skills the LLM won't recall this turn.
+        """
+        if not self.root.is_dir():
+            return []
+        out: list[dict] = []
+        for child in sorted(self.root.iterdir()):
+            if not child.is_dir():
+                continue
+            meta_path = child / "meta.json"
+            if not meta_path.is_file():
+                continue
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                continue
+            out.append(
+                {
+                    "label": str(meta.get("label", child.name)),
+                    "name": str(meta.get("name", child.name)),
+                    "when_to_use": str(meta.get("when_to_use", "")),
+                }
+            )
+        return out
+
+    # ── writing ─────────────────────────────────────────────────────
+
+    def save(self, skill: Skill) -> Path:
+        """Write the skill directory to disk. Overwrites in place.
+
+        Returns the directory path. Creates the parent root if needed.
+        Stage 2 and Stage 3 files are NOT touched here — they have their
+        own writers (consolidator, future).
+        """
+        self._ensure_root()
+        d = self._skill_dir(skill.label)
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "meta.json").write_text(
+            json.dumps(skill.to_meta_dict(), indent=2) + "\n",
+            encoding="utf-8",
+        )
+        (d / "declarative.md").write_text(skill.declarative_md, encoding="utf-8")
+        # Only initialize stats.json if it doesn't already exist — we
+        # never want save() to wipe accumulated counts.
+        stats_path = d / "stats.json"
+        if not stats_path.is_file():
+            stats_path.write_text(
+                json.dumps(skill.to_stats_dict(), indent=2) + "\n",
+                encoding="utf-8",
+            )
+        return d
+
+    def delete(self, label: str) -> bool:
+        """Remove a skill directory. Returns True if it existed."""
+        d = self._skill_dir(label)
+        if not d.is_dir():
+            return False
+        shutil.rmtree(d)
+        return True
+
+    # ── stats updates ───────────────────────────────────────────────
+
+    def increment_recommended(self, label: str, *, stage: int = 1) -> None:
+        """Atomic-ish bump of the per-stage `recommended` counter.
+
+        Reads the existing stats.json, mutates the right field, writes
+        back. Best-effort — if the skill doesn't exist or the file is
+        unwritable, silently no-ops. Concurrent writers may race; that's
+        acceptable for a counter that's used for guidance, not billing.
+        """
+        d = self._skill_dir(label)
+        if not d.is_dir():
+            return
+        stats = self._load_stats(label)
+        stats.total_recalls += 1
+        target = self._stage_for(stats, stage)
+        target.recommended += 1
+        target.last_used = datetime.now(timezone.utc).isoformat()
+        try:
+            (d / "stats.json").write_text(
+                json.dumps(
+                    {
+                        "total_recalls": stats.total_recalls,
+                        "stage_1": _stage_stats_to_dict(stats.stage_1),
+                        "stage_2": _stage_stats_to_dict(stats.stage_2),
+                        "stage_3": _stage_stats_to_dict(stats.stage_3),
+                    },
+                    indent=2,
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+        except OSError:
+            pass
+
+    @staticmethod
+    def _stage_for(stats: SkillStats, stage: int) -> StageStats:
+        if stage == 1:
+            return stats.stage_1
+        if stage == 2:
+            return stats.stage_2
+        if stage == 3:
+            return stats.stage_3
+        raise ValueError(f"Unknown stage: {stage}")
+
+    # ── search ──────────────────────────────────────────────────────
+
+    def closest_match(self, bad_label: str, *, cutoff: float = 0.6) -> str | None:
+        """Find the existing label closest to `bad_label`, or None.
+
+        Used by the recall_skill tool to recover from typos and guesses.
+        Cutoff is intentionally generous — we'd rather suggest a wrong
+        match the LLM can reject than return nothing.
+        """
+        bad = slugify(bad_label)
+        candidates = [s["label"] for s in self.list_summaries()]
+        if not candidates:
+            return None
+        if bad in candidates:
+            return bad
+        matches = difflib.get_close_matches(bad, candidates, n=1, cutoff=cutoff)
+        return matches[0] if matches else None
+
+
+__all__ = [
+    "Skill",
+    "SkillStats",
+    "SkillStore",
+    "StageStats",
+    "make_unique_label",
+    "slugify",
+]
diff --git a/anton/core/session.py b/anton/core/session.py
new file mode 100644
index 00000000..74afa0a5
--- /dev/null
+++ b/anton/core/session.py
@@ -0,0 +1,1381 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from anton.core.backends.base import Cell, ScratchpadRuntimeFactory
+from anton.core.backends.local import local_scratchpad_runtime_factory
+from anton.core.datasources.data_vault import DataVault
+from anton.core.llm.prompt_builder import ChatSystemPromptBuilder, SystemPromptContext
+from anton.core.memory.cerebellum import Cerebellum
+from anton.core.memory.skills import SkillStore
+from anton.core.tools.recall_skill import RECALL_SKILL_TOOL
+from anton.core.llm.prompts import RESILIENCE_NUDGE
+from anton.core.llm.provider import (
+    ContextOverflowError,
+    StreamComplete,
+    StreamContextCompacted,
+    StreamEvent,
+    StreamTaskProgress,
+    StreamTextDelta,
+    StreamToolResult,
+    TokenLimitExceeded,
+)
+from anton.core.backends.manager import ScratchpadManager
+from anton.core.tools.registry import ToolRegistry
+from anton.core.tools.tool_defs import (
+    SCRATCHPAD_TOOL,
+    MEMORIZE_TOOL,
+    RECALL_TOOL,
+    ToolDef,
+)
+from anton.core.utils.scratchpad import prepare_scratchpad_exec, format_cell_result
+
+from anton.explainability import ExplainabilityCollector, ExplainabilityStore
+
+from anton.utils.datasources import (
+    build_datasource_context,
+    scrub_credentials,
+)
+from anton.core.settings import CoreSettings
+
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from anton.context.self_awareness import SelfAwarenessContext
+    from anton.chat_ui import EscapeWatcher
+    from anton.core.llm.client import LLMClient
+    from anton.core.memory.cortex import Cortex
+    from anton.core.memory.episodes import EpisodicMemory
+    from anton.memory.history_store import HistoryStore
+    from anton.workspace import Workspace
+
+
+@dataclass
+class ChatSessionConfig:
+    """All construction parameters for a ChatSession.
+
+    Separates configuration assembly (the host app's job) from session
+    orchestration (the core's job). Hosts build this object and pass it
+    to ChatSession — the session never needs to know where values came from.
+    """
+
+    llm_client: LLMClient
+    runtime_factory: ScratchpadRuntimeFactory = field(default=local_scratchpad_runtime_factory)
+    cells: list[Cell] | None = None
+    settings: CoreSettings | None = None
+    self_awareness: SelfAwarenessContext | None = None
+    cortex: Cortex | None = None
+    episodic: EpisodicMemory | None = None
+    system_prompt_context: SystemPromptContext = field(default_factory=SystemPromptContext)
+    workspace: Workspace | None = None
+    data_vault: DataVault | None = None
+    console: Console | None = None
+    initial_history: list[dict] | None = None
+    history_store: HistoryStore | None = None
+    session_id: str | None = None
+    proactive_dashboards: bool = False
+    tools: list[ToolDef] = field(default_factory=list)
+
+
+class ChatSession:
+    """Manages a multi-turn conversation with tool-call delegation."""
+
+    def __init__(self, config: ChatSessionConfig) -> None:
+        s = config.settings or CoreSettings()
+        self._max_tool_rounds = s.max_tool_rounds
+        self._max_continuations = s.max_continuations
+        self._context_pressure_threshold = s.context_pressure_threshold
+        self._max_consecutive_errors = s.max_consecutive_errors
+        self._resilience_nudge_at = s.resilience_nudge_at
+        self._token_status_cache_ttl = s.token_status_cache_ttl
+        self._llm = config.llm_client
+        self._self_awareness = config.self_awareness
+        self._cortex = config.cortex
+        self._episodic = config.episodic
+        self._system_prompt_context = config.system_prompt_context
+        self._proactive_dashboards = config.proactive_dashboards
+        self._extra_tools = config.tools
+        self._workspace = config.workspace
+        self._data_vault = config.data_vault
+        self._console = config.console
+        self._history: list[dict] = (
+            list(config.initial_history) if config.initial_history else []
+        )
+        self._pending_memory_confirmations: list = []
+        self._turn_count = (
+            sum(1 for m in self._history if m.get("role") == "user")
+            if config.initial_history
+            else 0
+        )
+        self._history_store = config.history_store
+        self._session_id = config.session_id
+        self._cancel_event = asyncio.Event()
+        self._escape_watcher: EscapeWatcher | None = None
+        self._active_datasource: str | None = None
+
+        coding_provider = config.llm_client.coding_provider
+        coding_conn = coding_provider.export_connection_info()
+        self._scratchpads = ScratchpadManager(
+            runtime_factory=config.runtime_factory,
+            coding_provider=coding_conn.provider,
+            coding_model=config.llm_client.coding_model,
+            coding_api_key=coding_conn.api_key or "",
+            coding_base_url=coding_conn.base_url or "",
+            workspace_path=config.workspace.base if config.workspace else None,
+        )
+
+        self.tool_registry = ToolRegistry()
+        # Procedural memory: brain-inspired skills (Stage 1 = declarative).
+        # Lives at ~/.anton/skills/<label>/. The recall_skill tool retrieves
+        # entries on demand and increments per-stage usage counters.
+        self._skill_store = SkillStore()
+        # Cerebellum: supervised error learning over scratchpad cells.
+        # Buffers errored/warning cells across the turn, runs one diff
+        # call at end-of-turn, and encodes lessons via cortex.encode().
+        # Wired into the dispatcher's observer list below.
+        self._cerebellum = Cerebellum(
+            cortex=self._cortex,
+            llm=self._llm,
+        )
+        # Scratchpad observers — list of objects with on_pre_execute /
+        # on_post_execute. Fired by handle_scratchpad around pad.execute.
+        # The runtime never sees this list; observation lives at the
+        # dispatcher layer to keep local/remote runtimes interchangeable.
+        self._scratchpad_observers: list = [self._cerebellum]
+        self._explainability_store = (
+            ExplainabilityStore(config.workspace.base) if config.workspace is not None else None
+        )
+        self._active_explainability: ExplainabilityCollector | None = None
+
+    @property
+    def history(self) -> list[dict]:
+        return self._history
+
+    def _apply_error_tracking(
+        self,
+        result_text: str,
+        tool_name: str,
+        error_streak: dict[str, int],
+        resilience_nudged: set[str],
+    ) -> str:
+        """Track consecutive errors per tool and append nudge/circuit-breaker messages."""
+        is_error = any(
+            marker in result_text
+            for marker in (
+                "[error]",
+                "Task failed:",
+                "failed",
+                "timed out",
+                "Rejected:",
+            )
+        )
+        if is_error:
+            error_streak[tool_name] = error_streak.get(tool_name, 0) + 1
+        else:
+            error_streak[tool_name] = 0
+            resilience_nudged.discard(tool_name)
+
+        streak = error_streak.get(tool_name, 0)
+        if streak >= self._resilience_nudge_at and tool_name not in resilience_nudged:
+            result_text += RESILIENCE_NUDGE
+            resilience_nudged.add(tool_name)
+
+        if streak >= self._max_consecutive_errors:
+            result_text += (
+                f"\n\nSYSTEM: The '{tool_name}' tool has failed {self._max_consecutive_errors} times "
+                "in a row. Stop retrying this approach. Either try a completely different "
+                "strategy or tell the user what's going wrong so they can help."
+            )
+
+        return result_text
+
+    def repair_history(self) -> None:
+        """Fix dangling tool_use blocks left by mid-stream cancellation.
+
+        The Anthropic API requires every tool_use to be followed by a
+        tool_result.  If we cancelled mid-turn, the last assistant message
+        may contain tool_use blocks with no corresponding tool_result in
+        the next message.  Append synthetic tool_results so the
+        conversation can continue.
+        """
+        if not self._history:
+            return
+        last = self._history[-1]
+        if last.get("role") != "assistant":
+            return
+        content = last.get("content")
+        if not isinstance(content, list):
+            return
+        tool_ids = [
+            block["id"]
+            for block in content
+            if isinstance(block, dict) and block.get("type") == "tool_use"
+        ]
+        if not tool_ids:
+            return
+        self._history.append(
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tid,
+                        "content": "Cancelled by user.",
+                    }
+                    for tid in tool_ids
+                ],
+            }
+        )
+
+    def _persist_history(self) -> None:
+        """Save current history to disk if a history store is configured."""
+        if self._history_store and self._session_id:
+            self._history_store.save(self._session_id, self._history)
+
+    def _record_cell_explainability(
+        self, *, pad_name: str, description: str, cell
+    ) -> None:
+        if self._active_explainability is None:
+            return
+        if description:
+            self._active_explainability.add_scratchpad_step(description)
+        elif pad_name:
+            self._active_explainability.add_scratchpad_step(
+                f"work in scratchpad {pad_name}"
+            )
+        for query in getattr(cell, "explainability_queries", []) or []:
+            if not isinstance(query, dict):
+                continue
+            self._active_explainability.add_query(
+                datasource=str(query.get("datasource", "")),
+                sql=str(query.get("sql", "")),
+                engine=(
+                    str(query.get("engine"))
+                    if query.get("engine") is not None
+                    else None
+                ),
+                status=str(query.get("status", "ok")),
+                error_message=(
+                    str(query.get("error_message"))
+                    if query.get("error_message") is not None
+                    else None
+                ),
+            )
+        self._active_explainability.add_sources_from_text(
+            getattr(cell, "code", ""),
+            getattr(cell, "stdout", ""),
+            getattr(cell, "logs", ""),
+        )
+        self._active_explainability.add_inferred_queries_from_code(
+            getattr(cell, "code", "")
+        )
+
+    async def _build_system_prompt(self, user_message: str = "") -> str:
+        import datetime as _dt
+
+        _now = _dt.datetime.now()
+        _current_datetime = _now.strftime("%A, %B %d, %Y at %I:%M %p")
+
+        # Inject memory context (replaces old self_awareness)
+        memory_section = ""
+        if self._cortex is not None:
+            memory_section = await self._cortex.build_memory_context(user_message)
+
+        sa_section = ""
+        if self._self_awareness is not None and self._cortex is None:
+            # Fallback for legacy usage (tests, etc.)
+            sa_section = self._self_awareness.build_prompt_section()
+
+        # Inject anton.md project context (user-written takes priority)
+        md_context = ""
+        if self._workspace is not None:
+            md_context = self._workspace.build_anton_md_context()
+
+        # Inject connected datasource context without credentials
+        ds_ctx = build_datasource_context(self._data_vault, active_only=self._active_datasource)
+
+        # Ensure the registry is populated before we extract tool prompts.
+        self._build_tools()
+
+        prompt_builder = ChatSystemPromptBuilder()
+        prompt = prompt_builder.build(
+            current_datetime=_current_datetime,
+            system_prompt_context=self._system_prompt_context,
+            proactive_dashboards=self._proactive_dashboards,
+            tool_defs=self.tool_registry.get_tool_defs(),
+            memory_context=memory_section,
+            project_context=md_context,
+            self_awareness_context=sa_section,
+            datasource_context=ds_ctx,
+            skill_store=self._skill_store,
+        )
+
+        return prompt
+
+    # Packages the LLM is most likely to care about when writing scratchpad code.
+    _NOTABLE_PACKAGES: set[str] = {
+        "numpy",
+        "pandas",
+        "matplotlib",
+        "seaborn",
+        "scipy",
+        "scikit-learn",
+        "requests",
+        "httpx",
+        "aiohttp",
+        "beautifulsoup4",
+        "lxml",
+        "pillow",
+        "sympy",
+        "networkx",
+        "sqlalchemy",
+        "pydantic",
+        "rich",
+        "tqdm",
+        "click",
+        "fastapi",
+        "flask",
+        "django",
+        "openai",
+        "anthropic",
+        "tiktoken",
+        "transformers",
+        "torch",
+        "polars",
+        "pyarrow",
+        "openpyxl",
+        "xlsxwriter",
+        "plotly",
+        "bokeh",
+        "altair",
+        "pytest",
+        "hypothesis",
+        "yaml",
+        "pyyaml",
+        "toml",
+        "tomli",
+        "tomllib",
+        "jinja2",
+        "markdown",
+        "pygments",
+        "cryptography",
+        "paramiko",
+        "boto3",
+    }
+
+    def _build_tools(self) -> list[dict]:
+        if not self.tool_registry:
+            self._build_core_tools()
+            for tool in self._extra_tools:
+                self.tool_registry.register_tool(tool)
+        return self.tool_registry.dump()
+
+    def _build_core_tools(self) -> None:
+        scratchpad_tool = SCRATCHPAD_TOOL
+        pkg_list = self._scratchpads.available_packages
+        if pkg_list:
+            notable = sorted(p for p in pkg_list if p.lower() in self._NOTABLE_PACKAGES)
+            if notable:
+                pkg_line = ", ".join(notable)
+                extra = f"\n\nInstalled packages ({len(pkg_list)} total, notable: {pkg_line})."
+            else:
+                extra = f"\n\nInstalled packages: {len(pkg_list)} total (standard library plus dependencies)."
+            scratchpad_tool.description = scratchpad_tool.description + extra
+
+        # Inject scratchpad wisdom from memory (procedural priming)
+        if self._cortex is not None:
+            wisdom = self._cortex.get_scratchpad_context()
+            if wisdom:
+                scratchpad_tool.description += (
+                    f"\n\nLessons from past sessions:\n{wisdom}"
+                )
+
+        self.tool_registry.register_tool(scratchpad_tool)
+
+        if self._cortex is not None or self._self_awareness is not None:
+            self.tool_registry.register_tool(MEMORIZE_TOOL)
+
+        if self._episodic is not None and self._episodic.enabled:
+            self.tool_registry.register_tool(RECALL_TOOL)
+
+        # Procedural memory retrieval — always available, no-op if no skills.
+        self.tool_registry.register_tool(RECALL_SKILL_TOOL)
+
+    async def close(self) -> None:
+        """Clean up scratchpads and other resources."""
+        await self._scratchpads.close_all()
+
+    async def _summarize_history(self) -> None:
+        """Compress old conversation turns into a summary using the coding model.
+
+        Splits history into old (first 60%) and recent (last 40%), keeping at
+        least 4 recent turns.  The old portion is summarized by the fast coding
+        model and replaced with a single user message.
+        """
+        if len(self._history) < 6:
+            return  # Too short to summarize
+
+        min_recent = 4
+        split = max(int(len(self._history) * 0.6), 1)
+        # Ensure we keep at least min_recent turns
+        split = min(split, len(self._history) - min_recent)
+        if split < 2:
+            return
+
+        # Walk split backward to avoid breaking tool_use / tool_result pairs.
+        # A user message containing tool_result blocks must stay with the
+        # preceding assistant message that contains the matching tool_use.
+        while split > 1:
+            msg = self._history[split]
+            if msg.get("role") != "user":
+                break
+            content = msg.get("content")
+            if not isinstance(content, list):
+                break
+            has_tool_result = any(
+                isinstance(b, dict) and b.get("type") == "tool_result" for b in content
+            )
+            if not has_tool_result:
+                break
+            # This user message has tool_results — keep it (and its paired
+            # assistant message) in the recent portion.
+            split -= 1
+            # Also pull back over the preceding assistant message so the
+            # pair stays together.
+            if split > 1 and self._history[split].get("role") == "assistant":
+                split -= 1
+
+        if split < 2:
+            return
+
+        old_turns = self._history[:split]
+        recent_turns = self._history[split:]
+
+        # Serialize old turns into text for summarization
+        lines: list[str] = []
+        for msg in old_turns:
+            role = msg.get("role", "unknown")
+            content = msg.get("content", "")
+            if isinstance(content, str):
+                lines.append(f"[{role}]: {content[:2000]}")
+            elif isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict):
+                        if block.get("type") == "text":
+                            lines.append(f"[{role}]: {block['text'][:1000]}")
+                        elif block.get("type") == "tool_use":
+                            lines.append(
+                                f"[{role}/tool_use]: {block.get('name', '')}({str(block.get('input', ''))[:500]})"
+                            )
+                        elif block.get("type") == "tool_result":
+                            lines.append(
+                                f"[tool_result]: {str(block.get('content', ''))[:500]}"
+                            )
+
+        old_text = "\n".join(lines)
+        # Cap at ~8000 chars to avoid overloading the summarizer
+        if len(old_text) > 8000:
+            old_text = old_text[:8000] + "\n... (truncated)"
+
+        try:
+            summary_response = await self._llm.code(
+                system=(
+                    "Summarize this conversation history concisely. Preserve:\n"
+                    "- Key decisions and conclusions\n"
+                    "- Important data/results discovered\n"
+                    "- Variable names and values that are still relevant\n"
+                    "- Errors encountered and how they were resolved\n"
+                    "Keep it under 2000 tokens. Use bullet points."
+                ),
+                messages=[{"role": "user", "content": old_text}],
+                max_tokens=2048,
+            )
+            summary = summary_response.content or "(summary unavailable)"
+        except Exception:
+            # If summarization fails, just do a simple truncation
+            summary = f"(Earlier conversation with {len(old_turns)} turns — summarization failed)"
+
+        summary_msg = {
+            "role": "user",
+            "content": f"[Context summary of earlier conversation]\n{summary}",
+        }
+
+        # If the recent portion starts with a user message, insert a minimal
+        # assistant separator to avoid consecutive user messages (API error).
+        if recent_turns and recent_turns[0].get("role") == "user":
+            self._history = [
+                summary_msg,
+                {"role": "assistant", "content": "Understood."},
+                *recent_turns,
+            ]
+        else:
+            self._history = [summary_msg] + recent_turns
+
+    def _compact_scratchpads(self) -> bool:
+        """Compact all active scratchpads. Returns True if any were compacted."""
+        compacted = False
+        for pad in self._scratchpads.pads.values():
+            if pad._compact_cells():
+                compacted = True
+        return compacted
+
+    def _schedule_cerebellum_flush(self) -> None:
+        """Fire the cerebellum's batched diff pass without blocking the turn.
+
+        The cerebellum buffered any errored / warning cells across the
+        turn via its observer hooks. Now we kick off the (at most one)
+        LLM diff call as a background task — the user gets their reply
+        immediately, and any extracted lessons get encoded into the
+        existing wisdom store before the next turn typically begins.
+
+        Best-effort: if there's no buffered work or no event loop, this
+        is a no-op. Exceptions in the background task are swallowed
+        because they're already logged inside cerebellum.flush().
+        """
+        cb = getattr(self, "_cerebellum", None)
+        if cb is None:
+            return
+        if cb.buffered_count == 0:
+            return
+        try:
+            asyncio.create_task(cb.flush())
+        except RuntimeError:
+            # No running loop (e.g. called from a sync context in tests).
+            # Cerebellum learning is best-effort, so just drop the buffer.
+            cb.reset()
+
+    async def turn(self, user_input: str | list[dict]) -> str:
+        self._history.append({"role": "user", "content": user_input})
+
+        user_msg_str = user_input if isinstance(user_input, str) else ""
+        tools = self._build_tools()
+        system = await self._build_system_prompt(user_msg_str)
+
+        try:
+            response = await self._llm.plan(
+                system=system,
+                messages=self._history,
+                tools=tools,
+            )
+        except ContextOverflowError:
+            await self._summarize_history()
+            self._compact_scratchpads()
+            response = await self._llm.plan(
+                system=system,
+                messages=self._history,
+                tools=tools,
+            )
+
+        # Proactive compaction
+        if response.usage.context_pressure > self._context_pressure_threshold:
+            await self._summarize_history()
+            self._compact_scratchpads()
+
+        # Handle tool calls
+        tool_round = 0
+        error_streak: dict[str, int] = {}
+        resilience_nudged: set[str] = set()
+
+        while response.tool_calls:
+            tool_round += 1
+            if tool_round > self._max_tool_rounds:
+                self._history.append(
+                    {"role": "assistant", "content": response.content or ""}
+                )
+                self._history.append(
+                    {
+                        "role": "user",
+                        "content": (
+                            f"SYSTEM: You have used {self._max_tool_rounds} tool-call rounds on this turn. "
+                            "Pause here. Summarize what you have accomplished so far and what remains. "
+                            "If you believe you are on a good track and can finish the task with more steps, "
+                            "tell the user and ask if they'd like you to continue. "
+                            "Do NOT retry automatically — wait for the user's response."
+                        ),
+                    }
+                )
+                response = await self._llm.plan(
+                    system=system,
+                    messages=self._history,
+                )
+                break
+
+            # Build assistant message with content blocks
+            assistant_content: list[dict] = []
+            if response.content:
+                assistant_content.append({"type": "text", "text": response.content})
+            for tc in response.tool_calls:
+                assistant_content.append(
+                    {
+                        "type": "tool_use",
+                        "id": tc.id,
+                        "name": tc.name,
+                        "input": tc.input,
+                    }
+                )
+            self._history.append({"role": "assistant", "content": assistant_content})
+
+            # Process each tool call via registry
+            tool_results: list[dict] = []
+            for tc in response.tool_calls:
+                try:
+                    result_text = await self.tool_registry.dispatch_tool(
+                        self, tc.name, tc.input
+                    )
+                except Exception as exc:
+                    result_text = f"Tool '{tc.name}' failed: {exc}"
+
+                result_text = scrub_credentials(result_text)
+                result_text = self._apply_error_tracking(
+                    result_text,
+                    tc.name,
+                    error_streak,
+                    resilience_nudged,
+                )
+
+                tool_results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tc.id,
+                        "content": result_text,
+                    }
+                )
+
+            self._history.append({"role": "user", "content": tool_results})
+
+            # Get follow-up from LLM
+            try:
+                response = await self._llm.plan(
+                    system=system,
+                    messages=self._history,
+                    tools=tools,
+                )
+            except ContextOverflowError:
+                await self._summarize_history()
+                self._compact_scratchpads()
+                response = await self._llm.plan(
+                    system=system,
+                    messages=self._history,
+                    tools=tools,
+                )
+
+            # Proactive compaction during tool loop
+            if response.usage.context_pressure > self._context_pressure_threshold:
+                await self._summarize_history()
+                self._compact_scratchpads()
+
+        # Text-only response
+        reply = response.content or ""
+        self._history.append({"role": "assistant", "content": reply})
+
+        # Periodic memory vacuum (Systems Consolidation)
+        if self._cortex is not None and self._cortex.mode != "off":
+            self._cortex.maybe_vacuum()
+
+        # Cerebellar consolidation — fire-and-forget so the user gets
+        # their reply immediately while supervised error learning runs
+        # in the background. Brain analogue: cerebellar plasticity
+        # operates in parallel with continued action, not blocking it.
+        self._schedule_cerebellum_flush()
+
+        return reply
+
+    async def turn_stream(
+        self, user_input: str | list[dict]
+    ) -> AsyncIterator[StreamEvent]:
+        """Streaming version of turn(). Yields events as they arrive."""
+        self._history.append({"role": "user", "content": user_input})
+
+        # Log user input to episodic memory
+        if self._episodic is not None:
+            content = (
+                user_input if isinstance(user_input, str) else str(user_input)[:2000]
+            )
+            self._episodic.log_turn(self._turn_count + 1, "user", content)
+
+        user_msg_str = user_input if isinstance(user_input, str) else ""
+        assistant_text_parts: list[str] = []
+        _max_auto_retries = 2
+        _retry_count = 0
+        self._active_explainability = ExplainabilityCollector(
+            self._explainability_store,
+            turn=self._turn_count + 1,
+            user_message=user_msg_str,
+        )
+
+        try:
+            while True:
+                try:
+                    async for event in self._stream_and_handle_tools(user_msg_str):
+                        if isinstance(event, StreamTextDelta):
+                            assistant_text_parts.append(event.text)
+                        yield event
+                    break  # completed successfully
+                except Exception as _agent_exc:
+                    # Token/billing limit — don't retry, let the chat loop handle it
+                    if isinstance(_agent_exc, TokenLimitExceeded):
+                        raise
+                    _retry_count += 1
+                    if _retry_count <= _max_auto_retries:
+                        # Inject the error into history and let the LLM try to recover
+                        self._history.append(
+                            {
+                                "role": "user",
+                                "content": (
+                                    f"SYSTEM: An error interrupted execution: {_agent_exc}\n\n"
+                                    "If you can diagnose and fix the issue, continue working on the task. "
+                                    "Adjust your approach to avoid the same error. "
+                                    "If this is unrecoverable, summarize what you accomplished and suggest next steps."
+                                ),
+                            }
+                        )
+                        # Continue the while loop — _stream_and_handle_tools will be called
+                        # again with the error context now in history
+                        continue
+                    else:
+                        # Exhausted retries — stop and summarize for the user
+                        self._history.append(
+                            {
+                                "role": "user",
+                                "content": (
+                                    f"SYSTEM: The task has failed {_retry_count} times. Latest error: {_agent_exc}\n\n"
+                                    "Stop retrying. Please:\n"
+                                    "1. Summarize what you accomplished so far.\n"
+                                    "2. Explain what went wrong in plain language.\n"
+                                    "3. Suggest next steps — what the user can try (e.g. rephrase, "
+                                    "simplify the request, or ask you to continue from where you left off).\n"
+                                    "Be concise and helpful."
+                                ),
+                            }
+                        )
+                        try:
+                            async for event in self._llm.plan_stream(
+                                system=await self._build_system_prompt(user_msg_str),
+                                messages=self._history,
+                            ):
+                                if isinstance(event, StreamTextDelta):
+                                    assistant_text_parts.append(event.text)
+                                yield event
+                        except Exception:
+                            fallback = f"An unexpected error occurred: {_agent_exc}. Please try again or rephrase your request."
+                            assistant_text_parts.append(fallback)
+                            yield StreamTextDelta(text=fallback)
+                        break
+        finally:
+            if self._active_explainability is not None:
+                self._active_explainability.finalize(
+                    "".join(assistant_text_parts)[:2000]
+                )
+
+        # Log assistant response to episodic memory
+        if self._episodic is not None and assistant_text_parts:
+            self._episodic.log_turn(
+                self._turn_count + 1,
+                "assistant",
+                "".join(assistant_text_parts)[:2000],
+            )
+
+        # Identity extraction (Default Mode Network — every 5 turns)
+        self._turn_count += 1
+        self._persist_history()
+        if self._cortex is not None and self._cortex.mode != "off":
+            if self._turn_count % 5 == 0 and isinstance(user_input, str):
+                asyncio.create_task(self._cortex.maybe_update_identity(user_input))
+            # Periodic memory vacuum (Systems Consolidation)
+            self._cortex.maybe_vacuum()
+
+        # Cerebellar consolidation — same fire-and-forget contract as
+        # the non-streaming turn. Lets the user-facing stream finish
+        # immediately while supervised error learning runs in the background.
+        self._schedule_cerebellum_flush()
+
+    async def _stream_and_handle_tools(
+        self, user_message: str = ""
+    ) -> AsyncIterator[StreamEvent]:
+        """Stream one LLM call, handle tool loops, yield all events."""
+        tools = self._build_tools()
+        system = await self._build_system_prompt(user_message)
+
+        # Guard against summarizing an already-summarized history within the same
+        # turn (e.g. ContextOverflowError on first call + pressure > threshold on
+        # the tool-loop follow-up would previously produce a summary of a summary).
+        _compacted_this_turn = False
+
+        response: StreamComplete | None = None
+
+        try:
+            async for event in self._llm.plan_stream(
+                system=system,
+                messages=self._history,
+                tools=tools,
+            ):
+                yield event
+                if isinstance(event, StreamComplete):
+                    response = event
+        except ContextOverflowError:
+            await self._summarize_history()
+            self._compact_scratchpads()
+            _compacted_this_turn = True
+            yield StreamContextCompacted(
+                message="Context was getting long — older history has been summarized."
+            )
+            async for event in self._llm.plan_stream(
+                system=system,
+                messages=self._history,
+                tools=tools,
+            ):
+                yield event
+                if isinstance(event, StreamComplete):
+                    response = event
+
+        if response is None:
+            return
+
+        llm_response = response.response
+
+        # Detect max_tokens truncation — the LLM was cut off mid-response.
+        # Inject a continuation prompt so it can finish what it was doing.
+        if (
+            llm_response.stop_reason in ("max_tokens", "length")
+            and not llm_response.tool_calls
+        ):
+            self._history.append(
+                {"role": "assistant", "content": llm_response.content or ""}
+            )
+            self._history.append(
+                {
+                    "role": "user",
+                    "content": (
+                        "SYSTEM: Your response was truncated because it exceeded the output token limit. "
+                        "Continue exactly where you left off. If you were about to call a tool, "
+                        "call it now. If the code you were writing was too long, split it into smaller parts."
+                    ),
+                }
+            )
+            response = None
+            try:
+                async for event in self._llm.plan_stream(
+                    system=system,
+                    messages=self._history,
+                    tools=tools,
+                ):
+                    yield event
+                    if isinstance(event, StreamComplete):
+                        response = event
+            except ContextOverflowError:
+                if not _compacted_this_turn:
+                    await self._summarize_history()
+                    self._compact_scratchpads()
+                    _compacted_this_turn = True
+                yield StreamContextCompacted(
+                    message="Context was getting long — older history has been summarized."
+                )
+                async for event in self._llm.plan_stream(
+                    system=system,
+                    messages=self._history,
+                    tools=tools,
+                ):
+                    yield event
+                    if isinstance(event, StreamComplete):
+                        response = event
+
+            if response is None:
+                return
+            llm_response = response.response
+
+        # Proactive compaction
+        if (
+            not _compacted_this_turn
+            and llm_response.usage.context_pressure > self._context_pressure_threshold
+        ):
+            await self._summarize_history()
+            self._compact_scratchpads()
+            _compacted_this_turn = True
+            yield StreamContextCompacted(
+                message="Context was getting long — older history has been summarized."
+            )
+
+        # Tool-call loop with circuit breaker, wrapped in a completion
+        # verification outer loop that can restart the tool loop if the
+        # task isn't actually done yet.
+        continuation = 0
+        _max_rounds_hit = False
+
+        while True:  # Completion verification loop
+            tool_round = 0
+            error_streak: dict[str, int] = {}
+            resilience_nudged: set[str] = set()
+
+            while llm_response.tool_calls:
+                tool_round += 1
+                if tool_round > self._max_tool_rounds:
+                    _max_rounds_hit = True
+                    self._history.append(
+                        {"role": "assistant", "content": llm_response.content or ""}
+                    )
+                    self._history.append(
+                        {
+                            "role": "user",
+                            "content": (
+                                f"SYSTEM: You have used {self._max_tool_rounds} tool-call rounds on this turn. "
+                                "Pause here. Summarize what you have accomplished so far and what remains. "
+                                "If you believe you are on a good track and can finish the task with more steps, "
+                                "tell the user and ask if they'd like you to continue. "
+                                "Do NOT retry automatically — wait for the user's response."
+                            ),
+                        }
+                    )
+                    async for event in self._llm.plan_stream(
+                        system=system,
+                        messages=self._history,
+                    ):
+                        yield event
+                    break
+
+                # Build assistant message with content blocks
+                assistant_content: list[dict] = []
+                if llm_response.content:
+                    assistant_content.append(
+                        {"type": "text", "text": llm_response.content}
+                    )
+                for tc in llm_response.tool_calls:
+                    assistant_content.append(
+                        {
+                            "type": "tool_use",
+                            "id": tc.id,
+                            "name": tc.name,
+                            "input": tc.input,
+                        }
+                    )
+                self._history.append(
+                    {"role": "assistant", "content": assistant_content}
+                )
+
+                # Process each tool call
+                import time as _time
+
+                tool_results: list[dict] = []
+                for tc in llm_response.tool_calls:
+                    if self._episodic is not None:
+                        self._episodic.log_turn(
+                            self._turn_count + 1,
+                            "tool_call",
+                            str(tc.input)[:2000],
+                            tool=tc.name,
+                        )
+
+                    _tool_t0 = _time.monotonic()
+
+                    try:
+                        if tc.name == "scratchpad" and tc.input.get("action") == "exec":
+                            # Inline streaming exec — yields progress events
+                            prep = await prepare_scratchpad_exec(self, tc.input)
+                            if isinstance(prep, str):
+                                result_text = prep
+                            else:
+                                (
+                                    pad,
+                                    code,
+                                    description,
+                                    estimated_time,
+                                    estimated_seconds,
+                                ) = prep
+                                yield StreamTaskProgress(
+                                    phase="scratchpad_start",
+                                    message=description or "Running code",
+                                    eta_seconds=estimated_seconds,
+                                )
+
+                                _sp_t0 = _time.monotonic()
+                                from anton.core.backends.base import Cell
+
+                                cell = None
+                                async for item in pad.execute_streaming(
+                                    code,
+                                    description=description,
+                                    estimated_time=estimated_time,
+                                    estimated_seconds=estimated_seconds,
+                                ):
+                                    if self._cancel_event.is_set():
+                                        await pad.cancel()
+                                        break
+                                    if isinstance(item, str):
+                                        yield StreamTaskProgress(
+                                            phase="scratchpad", message=item
+                                        )
+                                    elif isinstance(item, Cell):
+                                        cell = item
+                                _sp_elapsed = _time.monotonic() - _sp_t0
+                                yield StreamTaskProgress(
+                                    phase="scratchpad_done",
+                                    message=description or "Done",
+                                    eta_seconds=_sp_elapsed,
+                                )
+                                result_text = (
+                                    format_cell_result(cell)
+                                    if cell
+                                    else "No result produced."
+                                )
+                                if cell is not None:
+                                    self._record_cell_explainability(
+                                        pad_name=tc.input.get("name", ""),
+                                        description=description,
+                                        cell=cell,
+                                    )
+                                if self._episodic is not None and cell is not None:
+                                    self._episodic.log_turn(
+                                        self._turn_count + 1,
+                                        "scratchpad",
+                                        (cell.stdout or "")[:2000],
+                                        description=description,
+                                    )
+                        elif tc.name == "connect_new_datasource" or (
+                            tc.name == "publish_or_preview"
+                            and tc.input.get("action") == "publish"
+                        ):
+                            # Interactive tool — pause spinner AND escape watcher
+                            yield StreamTaskProgress(
+                                phase="interactive",
+                                message="",
+                            )
+                            if self._escape_watcher:
+                                self._escape_watcher.pause()
+                            result_text = await self.tool_registry.dispatch_tool(
+                                self, tc.name, tc.input
+                            )
+                            if self._escape_watcher:
+                                self._escape_watcher.resume()
+                            yield StreamTaskProgress(
+                                phase="analyzing",
+                                message="Analyzing results...",
+                            )
+                        else:
+                            # Non-scratchpad, non-interactive tool — track elapsed
+                            yield StreamTaskProgress(
+                                phase="tool_start",
+                                message=tc.name,
+                            )
+                            result_text = await self.tool_registry.dispatch_tool(
+                                self, tc.name, tc.input
+                            )
+                            _tool_elapsed = _time.monotonic() - _tool_t0
+                            yield StreamTaskProgress(
+                                phase="tool_done",
+                                message=tc.name,
+                                eta_seconds=_tool_elapsed,
+                            )
+                            if (
+                                tc.name == "scratchpad"
+                                and tc.input.get("action") == "dump"
+                            ):
+                                yield StreamToolResult(content=result_text)
+                                result_text = (
+                                    "The full notebook has been displayed to the user above. "
+                                    "Do not repeat it. Here is the content for your reference:\n\n"
+                                    + result_text
+                                )
+                    except Exception as exc:
+                        result_text = f"Tool '{tc.name}' failed: {exc}"
+
+                    if self._episodic is not None:
+                        self._episodic.log_turn(
+                            self._turn_count + 1,
+                            "tool_result",
+                            result_text[:2000],
+                            tool=tc.name,
+                        )
+                    result_text = scrub_credentials(result_text)
+                    result_text = self._apply_error_tracking(
+                        result_text, tc.name, error_streak, resilience_nudged
+                    )
+                    tool_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": tc.id,
+                            "content": result_text,
+                        }
+                    )
+
+                self._history.append({"role": "user", "content": tool_results})
+
+                # Signal that tools are done and LLM is now reasoning
+                _reasoning_t0 = _time.monotonic()
+                yield StreamTaskProgress(
+                    phase="reasoning_start", message="Thinking..."
+                )
+
+                # Stream follow-up
+                response = None
+                try:
+                    async for event in self._llm.plan_stream(
+                        system=system,
+                        messages=self._history,
+                        tools=tools,
+                    ):
+                        # Capture reasoning elapsed on first text or tool event
+                        if _reasoning_t0 and isinstance(
+                            event, (StreamTextDelta, StreamComplete)
+                        ):
+                            _reasoning_elapsed = _time.monotonic() - _reasoning_t0
+                            _reasoning_t0 = 0  # only fire once
+                            yield StreamTaskProgress(
+                                phase="reasoning_done",
+                                message="",
+                                eta_seconds=_reasoning_elapsed,
+                            )
+                        yield event
+                        if isinstance(event, StreamComplete):
+                            response = event
+                except ContextOverflowError:
+                    if not _compacted_this_turn:
+                        await self._summarize_history()
+                        self._compact_scratchpads()
+                        _compacted_this_turn = True
+                    yield StreamContextCompacted(
+                        message="Context was getting long — older history has been summarized."
+                    )
+                    async for event in self._llm.plan_stream(
+                        system=system,
+                        messages=self._history,
+                        tools=tools,
+                    ):
+                        yield event
+                        if isinstance(event, StreamComplete):
+                            response = event
+
+                if response is None:
+                    return
+                llm_response = response.response
+
+                # Detect max_tokens truncation inside tool loop
+                if (
+                    llm_response.stop_reason in ("max_tokens", "length")
+                    and not llm_response.tool_calls
+                ):
+                    self._history.append(
+                        {"role": "assistant", "content": llm_response.content or ""}
+                    )
+                    self._history.append(
+                        {
+                            "role": "user",
+                            "content": (
+                                "SYSTEM: Your response was truncated because it exceeded the output token limit. "
+                                "Continue exactly where you left off. If you were about to call a tool, "
+                                "call it now. If the code you were writing was too long, split it into smaller parts."
+                            ),
+                        }
+                    )
+                    response = None
+                    try:
+                        async for event in self._llm.plan_stream(
+                            system=system,
+                            messages=self._history,
+                            tools=tools,
+                        ):
+                            yield event
+                            if isinstance(event, StreamComplete):
+                                response = event
+                    except ContextOverflowError:
+                        if not _compacted_this_turn:
+                            await self._summarize_history()
+                            self._compact_scratchpads()
+                            _compacted_this_turn = True
+                        yield StreamContextCompacted(
+                            message="Context was getting long — older history has been summarized."
+                        )
+                        async for event in self._llm.plan_stream(
+                            system=system,
+                            messages=self._history,
+                            tools=tools,
+                        ):
+                            yield event
+                            if isinstance(event, StreamComplete):
+                                response = event
+
+                    if response is None:
+                        return
+                    llm_response = response.response
+
+                # Proactive compaction during tool loop
+                if (
+                    not _compacted_this_turn
+                    and llm_response.usage.context_pressure
+                    > self._context_pressure_threshold
+                ):
+                    await self._summarize_history()
+                    self._compact_scratchpads()
+                    _compacted_this_turn = True
+                    yield StreamContextCompacted(
+                        message="Context was getting long — older history has been summarized."
+                    )
+
+            # --- Completion verification ---
+            # Only verify when tools were actually used (not for simple Q&A)
+            # and we haven't hit the max-rounds hard stop.
+            if tool_round == 0 or _max_rounds_hit:
+                break
+
+            # Append the assistant's final text so the verifier can see it
+            reply = llm_response.content or ""
+            self._history.append({"role": "assistant", "content": reply})
+
+            if continuation >= self._max_continuations:
+                # Budget exhausted — ask LLM to diagnose and present to user
+                self._history.append(
+                    {
+                        "role": "user",
+                        "content": (
+                            "SYSTEM: You have attempted to complete this task multiple times "
+                            "but verification indicates it is still not done. Do NOT try again. "
+                            "Instead:\n"
+                            "1. Summarize exactly what was accomplished so far.\n"
+                            "2. Identify the specific blocker or failure preventing completion.\n"
+                            "3. Suggest concrete next steps the user can take to unblock this.\n"
+                            "Be honest and specific — do not be vague about what went wrong."
+                        ),
+                    }
+                )
+                yield StreamTaskProgress(
+                    phase="analyzing", message="Diagnosing incomplete task..."
+                )
+                async for event in self._llm.plan_stream(
+                    system=system,
+                    messages=self._history,
+                ):
+                    yield event
+                # Consolidation still runs after diagnosis
+                break
+
+            # Ask the LLM to self-assess completion.
+            # Use a copy of history with a trailing user message so models
+            # that don't support assistant-prefill won't reject the request.
+            verify_messages = list(self._history) + [
+                {
+                    "role": "user",
+                    "content": (
+                        "SYSTEM: Evaluate whether the task the user originally requested "
+                        "has been fully completed based on the conversation above."
+                    ),
+                }
+            ]
+            verification = await self._llm.plan(
+                system=(
+                    "You are a task-completion verifier. Given the conversation, determine "
+                    "whether the user's original request has been fully completed.\n\n"
+                    "Respond with EXACTLY one of these lines, followed by a brief reason:\n"
+                    "STATUS: COMPLETE — <reason>\n"
+                    "STATUS: INCOMPLETE — <reason>\n"
+                    "STATUS: STUCK — <reason>\n\n"
+                    "COMPLETE = the task is done or the response fully answers the question.\n"
+                    "INCOMPLETE = more work can be done to finish the task.\n"
+                    "STUCK = a blocker prevents completion (missing info, permissions, etc).\n\n"
+                    "Be strict: if the user asked for X and only part of X was delivered, "
+                    "that is INCOMPLETE, not COMPLETE. But if the user asked a question "
+                    "and the assistant answered it, that is COMPLETE even without tool use."
+                ),
+                messages=verify_messages,
+                max_tokens=256,
+            )
+
+            status_text = (verification.content or "").strip().upper()
+            if "STATUS: COMPLETE" in status_text:
+                break
+            if "STATUS: STUCK" in status_text:
+                # Stuck — inject diagnosis request and let the LLM explain
+                reason = (verification.content or "").strip()
+                self._history.append(
+                    {
+                        "role": "user",
+                        "content": (
+                            f"SYSTEM: Task verification determined this task is stuck.\n"
+                            f"Verifier assessment: {reason}\n\n"
+                            "Explain to the user what went wrong, what you tried, and "
+                            "suggest specific next steps they can take to unblock this."
+                        ),
+                    }
+                )
+                yield StreamTaskProgress(
+                    phase="analyzing", message="Diagnosing blocked task..."
+                )
+                async for event in self._llm.plan_stream(
+                    system=system,
+                    messages=self._history,
+                ):
+                    yield event
+                break
+
+            # INCOMPLETE — continue working
+            continuation += 1
+            reason = (verification.content or "").strip()
+            self._history.append(
+                {
+                    "role": "user",
+                    "content": (
+                        f"SYSTEM: Task verification determined this task is not yet complete "
+                        f"(attempt {continuation}/{self._max_continuations}).\n"
+                        f"Verifier assessment: {reason}\n\n"
+                        "Continue working on the original request. Pick up where you left off "
+                        "and finish the remaining work. Do not repeat work already done."
+                    ),
+                }
+            )
+            yield StreamTaskProgress(
+                phase="analyzing",
+                message=f"Task incomplete — continuing ({continuation}/{self._max_continuations})...",
+            )
+
+            # Re-enter tool loop: get next LLM response with tools available
+            response = None
+            async for event in self._llm.plan_stream(
+                system=system,
+                messages=self._history,
+                tools=tools,
+            ):
+                yield event
+                if isinstance(event, StreamComplete):
+                    response = event
+            if response is None:
+                return
+            llm_response = response.response
+            # Loop back to the top of the completion verification loop
+
+        # Text-only final response — append to history (if not already appended
+        # by the verification block above).
+        if not self._history or self._history[-1].get("role") != "assistant":
+            reply = llm_response.content or ""
+            self._history.append({"role": "assistant", "content": reply})
+
+        # Consolidation: replay scratchpad sessions to extract lessons
+        if self._cortex is not None and self._cortex.mode != "off":
+            self._maybe_consolidate_scratchpads()
+
+    def _maybe_consolidate_scratchpads(self) -> None:
+        """Check if any scratchpad sessions warrant consolidation and fire it off."""
+        from anton.core.memory.consolidator import Consolidator
+
+        consolidator = Consolidator()
+        for pad in self._scratchpads.pads.values():
+            cells = list(pad.cells)
+            if consolidator.should_replay(cells):
+                asyncio.create_task(self._consolidate(cells))
+
+    async def _consolidate(self, cells: list) -> None:
+        """Run offline consolidation on a completed scratchpad session."""
+        from anton.core.memory.consolidator import Consolidator
+
+        consolidator = Consolidator()
+        engrams = await consolidator.replay_and_extract(cells, self._llm)
+        if not engrams or self._cortex is None:
+            return
+
+        auto_encode = [e for e in engrams if not self._cortex.encoding_gate(e)]
+        needs_confirm = [e for e in engrams if self._cortex.encoding_gate(e)]
+
+        if auto_encode:
+            await self._cortex.encode(auto_encode)
+
+        if needs_confirm:
+            self._pending_memory_confirmations.extend(needs_confirm)
diff --git a/anton/core/settings.py b/anton/core/settings.py
new file mode 100644
index 00000000..ff5186ee
--- /dev/null
+++ b/anton/core/settings.py
@@ -0,0 +1,21 @@
+from pydantic_settings import BaseSettings
+
+
+#
+class CoreSettings(BaseSettings):
+    model_config = {"env_prefix": "ANTON_", "extra": "ignore"}
+
+    # Session orchestration tuning
+    max_tool_rounds: int = 25
+    max_continuations: int = 3
+    context_pressure_threshold: float = 0.7
+    max_consecutive_errors: int = 5
+    resilience_nudge_at: int = 2
+    token_status_cache_ttl: float = 60.0
+
+    # Scratchpad execution tuning
+    cell_timeout_default: int = 120  # Total timeout when no estimate given (s)
+    cell_inactivity_timeout: int = 30  # Max silence between output lines (s)
+    cell_inactivity_after_progress: int = 60  # Grace window after progress() call (s)
+    cell_install_timeout: int = 120  # pip/uv install timeout (s)
+    cell_keep_recent: int = 5  # Recent cells preserved during compaction
diff --git a/anton/core/tools/recall_skill.py b/anton/core/tools/recall_skill.py
new file mode 100644
index 00000000..290e5af1
--- /dev/null
+++ b/anton/core/tools/recall_skill.py
@@ -0,0 +1,130 @@
+"""The `recall_skill` tool — retrieve a procedural skill into working memory.
+
+Brain analogue: prefrontal cortex pulls a stored procedure from
+long-term memory into the working buffer when it recognizes a familiar
+pattern in the current task. The tool is the *retrieval* operation; the
+LLM still has agency about whether (and how literally) to follow the
+recalled procedure.
+
+The classifier signal lives in this tool: every successful invocation
+bumps the skill's `recommended` counter, giving us a precise,
+mechanical signal of "the system thought this skill applied" without
+relying on the LLM to emit a marker or follow any convention.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from anton.core.tools.tool_defs import ToolDef
+
+if TYPE_CHECKING:
+    from anton.core.session import ChatSession
+
+
+_DESCRIPTION = (
+    "Retrieve a procedural skill from long-term memory into your working "
+    "context. Call this when you recognize that one of the skills listed in "
+    "the '## Procedural memory' section of your system prompt applies to the "
+    "user's current request. The tool returns the full step-by-step procedure "
+    "for that skill — follow it as a guide, adapting to the specifics of the "
+    "current task. You may recall multiple skills if the task spans several "
+    "procedures.\n\n"
+    "If you pass a label that doesn't exist, the tool will return the closest "
+    "match (if any) with a warning, or list the available labels if nothing "
+    "is close."
+)
+
+
+_INPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "label": {
+            "type": "string",
+            "description": (
+                "The skill label to recall, e.g. 'csv_summary'. Must come from "
+                "the procedural memory list in your system prompt."
+            ),
+        },
+    },
+    "required": ["label"],
+}
+
+
+def _format_skill_response(skill, *, warning: str = "") -> str:
+    """Render the recall payload sent back to the LLM as a tool result."""
+    parts: list[str] = []
+    if warning:
+        parts.append(warning.strip())
+        parts.append("")  # blank line before the procedure
+    parts.append(f"# Skill: {skill.name}")
+    parts.append("")
+    if skill.description:
+        parts.append(skill.description)
+        parts.append("")
+    parts.append("## Procedure (Stage 1 — declarative)")
+    parts.append("")
+    parts.append(skill.declarative_md.strip())
+    return "\n".join(parts)
+
+
+async def handle_recall_skill(session: "ChatSession", tc_input: dict) -> str:
+    """Look up a skill by label and return its declarative procedure."""
+    label_in = (tc_input.get("label") or "").strip()
+    if not label_in:
+        return (
+            "ERROR: recall_skill requires a non-empty 'label' parameter. "
+            "Pick one from the procedural memory list in your system prompt."
+        )
+
+    store = getattr(session, "_skill_store", None)
+    if store is None:
+        return (
+            "ERROR: no skill store is wired into this session. "
+            "Procedural memory is unavailable right now."
+        )
+
+    skill = store.load(label_in)
+    warning = ""
+    if skill is None:
+        closest = store.closest_match(label_in)
+        if closest is None:
+            available = [s["label"] for s in store.list_summaries()]
+            if not available:
+                return (
+                    f"NO MATCH: no skill named '{label_in}', and the procedural "
+                    f"memory is empty. Proceed without a recalled procedure."
+                )
+            return (
+                f"NO MATCH: no skill named '{label_in}'. Available skills: "
+                f"{', '.join(available)}."
+            )
+        skill = store.load(closest)
+        if skill is None:
+            # Race or filesystem flake — be defensive
+            return (
+                f"NO MATCH: '{label_in}' was not found and the closest "
+                f"candidate '{closest}' could not be loaded."
+            )
+        warning = (
+            f"⚠ No skill named '{label_in}'. Returning the closest match: "
+            f"'{skill.label}'. If that's not what you wanted, ignore the "
+            f"procedure below and proceed without a recalled skill."
+        )
+
+    # Increment the recommended counter for the *resolved* label, not the
+    # input. If the LLM typo'd 'csv_sumary', we credit 'csv_summary'.
+    store.increment_recommended(skill.label, stage=1)
+
+    return _format_skill_response(skill, warning=warning)
+
+
+RECALL_SKILL_TOOL = ToolDef(
+    name="recall_skill",
+    description=_DESCRIPTION,
+    input_schema=_INPUT_SCHEMA,
+    handler=handle_recall_skill,
+)
+
+
+__all__ = ["RECALL_SKILL_TOOL", "handle_recall_skill"]
diff --git a/anton/core/tools/registry.py b/anton/core/tools/registry.py
new file mode 100644
index 00000000..d8b1c605
--- /dev/null
+++ b/anton/core/tools/registry.py
@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from anton.core.session import ChatSession
+    from anton.core.tools.tool_defs import ToolDef
+
+
+class ToolRegistry:
+    """
+    Registry of tools available to the LLM.
+    """
+
+    def __init__(self) -> None:
+        self._tools: list[ToolDef] = []
+
+    def __bool__(self) -> bool:
+        return bool(self._tools)
+
+    def register_tool(self, tool_def: "ToolDef") -> None:
+        """Register a tool. Skips duplicates by name."""
+        if any(t.name == tool_def.name for t in self._tools):
+            return
+        self._tools.append(tool_def)
+
+    def get_tool_defs(self) -> list["ToolDef"]:
+        """Return registered ToolDef objects (for prompt injection, etc.)."""
+        return list(self._tools)
+
+    async def dispatch_tool(
+        self, session: "ChatSession", tool_name: str, tc_input: dict
+    ) -> str:
+        """Dispatch a tool call by name. Returns result text."""
+        tool_def = next((t for t in self._tools if t.name == tool_name), None)
+        if tool_def is None:
+            raise ValueError(f"Tool {tool_name} not found")
+        return await tool_def.handler(session, tc_input)
+
+    def dump(self) -> list[dict]:
+        """
+        Dump the registry as a list of LLM-facing tool schemas.
+        Excludes handler and prompt — those are internal only.
+        """
+        return [
+            {
+                "name": t.name,
+                "description": t.description,
+                "input_schema": t.input_schema,
+            }
+            for t in self._tools
+        ]
diff --git a/anton/core/tools/tool_defs.py b/anton/core/tools/tool_defs.py
new file mode 100644
index 00000000..d4319619
--- /dev/null
+++ b/anton/core/tools/tool_defs.py
@@ -0,0 +1,172 @@
+from anton.core.tools.tool_handlers import (
+    handle_scratchpad,
+    handle_memorize,
+    handle_recall,
+)
+
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+
+@dataclass
+class ToolDef:
+    name: str
+    description: str
+    input_schema: dict
+    handler: Callable  # async (session, tc_input) -> str
+    prompt: Optional[str] = (
+        None  # Optional prompt relevant to the tool to be injected into the system prompt.
+    )
+
+
+SCRATCHPAD_TOOL = ToolDef(
+    name="scratchpad",
+    description=(
+        "Run Python code in a persistent scratchpad. Use this whenever you need to "
+        "count characters, do math, parse data, transform text, or any task that "
+        "benefits from precise computation rather than guessing. Variables, imports, "
+        "and data persist across cells — like a notebook you drive programmatically.\n\n"
+        "Actions:\n"
+        "- exec: Run code in the scratchpad (creates it if needed)\n"
+        "- view: See all cells and their outputs\n"
+        "- reset: Restart the process, clearing all state (installed packages survive)\n"
+        "- remove: Kill the scratchpad and delete its environment\n"
+        "- dump: Show a clean notebook-style summary of cells (code + truncated output)\n"
+        "- install: Install Python packages into the scratchpad's environment. "
+        "Packages persist across resets.\n\n"
+        "Use print() to produce output. Host Python packages are available by default. "
+        "Include a 'packages' array on exec calls for any libraries your code needs — "
+        "they'll be auto-installed before the cell runs (already-installed ones are skipped).\n"
+        "get_llm() returns a pre-configured LLM client (sync) — call "
+        "llm.complete(system=..., messages=[...]) for AI-powered computation.\n"
+        "llm.generate_object(MyModel, system=..., messages=[...]) extracts structured "
+        "data into Pydantic models. Supports single models and list[Model].\n"
+        "agentic_loop(system=..., user_message=..., tools=[...], handle_tool=fn) "
+        "runs a tool-call loop where the LLM reasons and calls your tools iteratively. "
+        "handle_tool(name, inputs) -> str is a plain sync function.\n"
+        "sample(var) inspects any variable with type-aware formatting — DataFrames get "
+        "shape/dtypes/head, dicts get keys/values, lists get length/items. "
+        "Defaults to 'preview' mode (compact); use sample(var, mode='full') for complete dump.\n"
+        "All .anton/.env secrets are available as environment variables (os.environ).\n\n"
+        "IMPORTANT: Cells have an inactivity timeout of 30 seconds — if a cell produces "
+        "no output and no progress() calls for 30s, it is killed and all state is lost. "
+        "For long-running code (API calls, data extraction, heavy computation), call "
+        "progress(message) periodically to signal work is ongoing and reset the timer. "
+        "The total timeout scales from your estimated_execution_time_seconds "
+        "(roughly 2x the estimate). You MUST provide estimated_execution_time_seconds "
+        "for every exec call. For very long operations, provide a realistic estimate "
+        "and use progress() to keep the cell alive."
+    ),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["exec", "view", "reset", "remove", "dump", "install"],
+            },
+            "name": {"type": "string", "description": "Scratchpad name"},
+            "code": {
+                "type": "string",
+                "description": "Python code (exec only). Use print() for output.",
+            },
+            "packages": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Package names needed by this cell (exec or install). "
+                "Listed after code so you know exactly what to include. "
+                "Already-installed packages are skipped automatically.",
+            },
+            "one_line_description": {
+                "type": "string",
+                "description": "Brief description of what this cell does (e.g. 'Scrape listing prices'). Required for exec.",
+            },
+            "estimated_execution_time_seconds": {
+                "type": "integer",
+                "description": "Estimated execution time in seconds. Drives the total timeout (roughly 2x estimate). Use progress() for long cells.",
+            },
+        },
+        "required": ["action", "name"],
+    },
+    handler=handle_scratchpad,
+)
+
+
+MEMORIZE_TOOL = ToolDef(
+    name="memorize",
+    description=(
+        "Encode a rule or lesson into long-term memory for future sessions. "
+        "Use this when you learn something important, discover a useful pattern, "
+        "or the user asks you to remember something.\n\n"
+        "Entry kinds:\n"
+        "- always: Something to always do ('Use httpx instead of requests')\n"
+        "- never: Something to never do ('Never use time.sleep() in scratchpad')\n"
+        "- when: Conditional rule ('If paginated API → use async + progress()')\n"
+        "- lesson: Factual knowledge ('CoinGecko rate-limits at 50/min')\n"
+        "- profile: Fact about the user ('Name: Jorge', 'Prefers dark mode')"
+    ),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "entries": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "text": {
+                            "type": "string",
+                            "description": "The memory to encode",
+                        },
+                        "kind": {
+                            "type": "string",
+                            "enum": ["always", "never", "when", "lesson", "profile"],
+                        },
+                        "scope": {
+                            "type": "string",
+                            "enum": ["global", "project"],
+                        },
+                        "topic": {
+                            "type": "string",
+                            "description": "Topic slug for lessons (e.g. 'api-coingecko')",
+                        },
+                    },
+                    "required": ["text", "kind", "scope"],
+                },
+            },
+        },
+        "required": ["entries"],
+    },
+    handler=handle_memorize,
+)
+
+
+RECALL_TOOL = ToolDef(
+    name="recall",
+    description=(
+        "Search your episodic memory — an archive of past conversations. "
+        "ONLY use this when the user explicitly asks about a previous conversation "
+        "or session (e.g. 'what did we talk about last time?', 'remember when we...', "
+        "'have we discussed X before?'). Do NOT use this for questions about code, "
+        "files, or data in the workspace — use the scratchpad to explore those directly.\n\n"
+        "Returns timestamped episodes matching the query (newest first). "
+        "A single call is enough — do not call multiple times with different queries."
+    ),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Search term to find in past conversations.",
+            },
+            "max_results": {
+                "type": "integer",
+                "description": "Maximum episodes to return (default 20).",
+            },
+            "days_back": {
+                "type": "integer",
+                "description": "Only search episodes from the last N days.",
+            },
+        },
+        "required": ["query"],
+    },
+    handler=handle_recall,
+)
diff --git a/anton/core/tools/tool_handlers.py b/anton/core/tools/tool_handlers.py
new file mode 100644
index 00000000..b16d4f57
--- /dev/null
+++ b/anton/core/tools/tool_handlers.py
@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from anton.core.backends.base import Cell
+from anton.core.utils.scratchpad import prepare_scratchpad_exec, format_cell_result
+
+if TYPE_CHECKING:
+    from anton.chat_session import ChatSession
+
+
+_log = logging.getLogger(__name__)
+
+
+async def _fire_pre_execute(session: "ChatSession", cell: Cell) -> None:
+    """Notify pre-execute observers (e.g. cerebellum) before a cell runs.
+
+    Best-effort: a buggy observer never kills a cell. The list of
+    observers is owned by the session — typically populated in
+    ChatSession.__init__. Empty list (or attribute missing) means no
+    observers and this is a no-op.
+    """
+    observers = getattr(session, "_scratchpad_observers", None) or []
+    for obs in observers:
+        on_pre = getattr(obs, "on_pre_execute", None)
+        if on_pre is None:
+            continue
+        try:
+            await on_pre(cell)
+        except Exception as exc:
+            _log.warning(
+                "scratchpad pre-execute observer %s failed: %s",
+                type(obs).__name__,
+                exc,
+            )
+
+
+async def _fire_post_execute(session: "ChatSession", cell: Cell) -> None:
+    """Notify post-execute observers (e.g. cerebellum) after a cell finishes.
+
+    Same best-effort contract as `_fire_pre_execute`.
+    """
+    observers = getattr(session, "_scratchpad_observers", None) or []
+    for obs in observers:
+        on_post = getattr(obs, "on_post_execute", None)
+        if on_post is None:
+            continue
+        try:
+            await on_post(cell)
+        except Exception as exc:
+            _log.warning(
+                "scratchpad post-execute observer %s failed: %s",
+                type(obs).__name__,
+                exc,
+            )
+
+
+async def handle_recall(session: ChatSession, tc_input: dict) -> str:
+    """Process a recall tool call — search episodic memory."""
+    if session._episodic is None or not session._episodic.enabled:
+        return "Episodic memory is not available."
+
+    query = tc_input.get("query", "")
+    if not query:
+        return "No query provided."
+
+    kwargs: dict = {}
+    if "max_results" in tc_input:
+        kwargs["max_results"] = int(tc_input["max_results"])
+    if "days_back" in tc_input:
+        kwargs["days_back"] = int(tc_input["days_back"])
+
+    return session._episodic.recall_formatted(query, **kwargs)
+
+
+async def handle_memorize(session: ChatSession, tc_input: dict) -> str:
+    """Process a memorize tool call and return a result string.
+
+    Encoding is fire-and-forget so it never blocks scratchpad execution.
+    """
+    import asyncio
+
+    if session._cortex is None:
+        return "Memory system not available."
+
+    if session._cortex.mode == "off":
+        return "Memory encoding is disabled. Change memory mode via /setup to enable."
+
+    from anton.core.memory.hippocampus import Engram
+
+    raw_entries = tc_input.get("entries", [])
+    if not raw_entries:
+        return "No entries provided."
+
+    engrams: list[Engram] = []
+    for entry in raw_entries:
+        if not isinstance(entry, dict) or "text" not in entry:
+            continue
+
+        kind = entry.get("kind", "lesson")
+        if kind not in ("always", "never", "when", "lesson", "profile"):
+            kind = "lesson"
+
+        scope = entry.get("scope", "project")
+        if scope not in ("global", "project"):
+            scope = "project"
+
+        # User-sourced memories (via explicit tool call) get high confidence
+        engrams.append(
+            Engram(
+                text=entry["text"],
+                kind=kind,
+                scope=scope,
+                confidence="high",
+                topic=entry.get("topic", ""),
+                source="user",
+            )
+        )
+
+    if not engrams:
+        return "No valid entries provided."
+
+    # Always encode immediately via fire-and-forget — the LLM explicitly
+    # chose to memorize these, so we never interrupt the user mid-turn
+    # with confirmation prompts.  Confirmations are reserved for the
+    # post-turn consolidator (lessons extracted from scratchpad sessions).
+    async def _encode_bg(cortex, entries):
+        try:
+            await cortex.encode(entries)
+        except Exception:
+            pass  # Best-effort; don't disrupt the conversation
+
+    asyncio.create_task(_encode_bg(session._cortex, engrams))
+
+    descriptions = [f"Encoded {e.kind}: {e.text}" for e in engrams]
+    return "Memory updated: " + "; ".join(descriptions)
+
+
+async def handle_scratchpad(session: ChatSession, tc_input: dict) -> str:
+    """Dispatch a scratchpad tool call by action."""
+    action = tc_input.get("action", "")
+    name = tc_input.get("name", "")
+
+    if not name:
+        return "Scratchpad name is required."
+
+    if action == "exec":
+        result = await prepare_scratchpad_exec(session, tc_input)
+        if isinstance(result, str):
+            return result
+        pad, code, description, estimated_time, estimated_seconds = result
+
+        # Notify pre-execute observers (e.g. cerebellum). The runtime
+        # never sees these — observation is an orchestration concern,
+        # so it lives at the dispatcher layer where the data is most
+        # natural and where local/remote runtimes stay interchangeable.
+        prelim_cell = Cell(
+            code=code,
+            stdout="",
+            stderr="",
+            error=None,
+            description=description,
+            estimated_time=estimated_time or str(estimated_seconds),
+        )
+        await _fire_pre_execute(session, prelim_cell)
+
+        cell = await pad.execute(
+            code,
+            description=description,
+            estimated_time=estimated_time,
+            estimated_seconds=estimated_seconds,
+        )
+        if cell is not None:
+            session._record_cell_explainability(
+                pad_name=name, description=description, cell=cell,
+            )
+            await _fire_post_execute(session, cell)
+        return format_cell_result(cell)
+
+    elif action == "view":
+        pad = session._scratchpads.pads.get(name)
+        if pad is None:
+            return f"No scratchpad named '{name}'."
+        return pad.view()
+
+    elif action == "reset":
+        pad = session._scratchpads.pads.get(name)
+        if pad is None:
+            return f"No scratchpad named '{name}'."
+        await pad.reset()
+        return f"Scratchpad '{name}' reset. All state cleared."
+
+    elif action == "remove":
+        return await session._scratchpads.remove(name)
+
+    elif action == "dump":
+        pad = session._scratchpads.pads.get(name)
+        if pad is None:
+            return f"No scratchpad named '{name}'."
+        return pad.render_notebook()
+
+    elif action == "install":
+        packages = tc_input.get("packages", [])
+        if not packages:
+            return "No packages specified."
+        pad = await session._scratchpads.get_or_create(name)
+        return await pad.install_packages(packages)
+
+    else:
+        return f"Unknown scratchpad action: {action}"
diff --git a/anton/core/utils/__init__.py b/anton/core/utils/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/anton/core/utils/scratchpad.py b/anton/core/utils/scratchpad.py
new file mode 100644
index 00000000..da518ff4
--- /dev/null
+++ b/anton/core/utils/scratchpad.py
@@ -0,0 +1,66 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from anton.core.session import ChatSession
+
+
+async def prepare_scratchpad_exec(session: ChatSession, tc_input: dict):
+    """Validate and prepare a scratchpad exec call.
+
+    Returns (pad, code, description, estimated_time, estimated_seconds) or
+    a str error message if validation fails.
+    """
+    name = tc_input.get("name", "")
+    code = tc_input.get("code", "")
+    if not code or not code.strip():
+        return "No code provided."
+
+    pad = await session._scratchpads.get_or_create(name)
+
+    # Auto-install packages before running the cell
+    packages = tc_input.get("packages", [])
+    if packages:
+        install_result = await pad.install_packages(packages)
+        if "Install failed" in install_result or "timed out" in install_result:
+            return install_result
+
+    description = tc_input.get("one_line_description", "")
+    estimated_seconds = tc_input.get("estimated_execution_time_seconds", 0)
+    if isinstance(estimated_seconds, str):
+        try:
+            estimated_seconds = int(estimated_seconds)
+        except ValueError:
+            estimated_seconds = 0
+
+    estimated_time = f"{estimated_seconds}s" if estimated_seconds > 0 else ""
+    return pad, code, description, estimated_time, estimated_seconds
+
+
+def format_cell_result(cell) -> str:
+    """Format a Cell into a tool result string.
+
+    Every section is labeled so the LLM can tell what came from where:
+    [output] — print() / stdout from the cell code
+    [logs]   — library logging (httpx, urllib3, etc.) captured at INFO+
+    [stderr] — warnings and stderr writes
+    [error]  — Python traceback if the cell raised an exception
+    """
+    parts: list[str] = []
+    if cell.stdout:
+        stdout = cell.stdout
+        if len(stdout) > 10_000:
+            stdout = stdout[:10_000] + f"\n\n... (truncated, {len(stdout)} chars total)"
+        parts.append(f"[output]\n{stdout}")
+    if cell.logs if hasattr(cell, "logs") else False:
+        logs = cell.logs.strip()
+        if len(logs) > 3_000:
+            logs = logs[:3_000] + "\n... (logs truncated)"
+        parts.append(f"[logs]\n{logs}")
+    if cell.stderr:
+        parts.append(f"[stderr]\n{cell.stderr}")
+    if cell.error:
+        parts.append(f"[error]\n{cell.error}")
+    if not parts:
+        return "Code executed successfully (no output)."
+    return "\n".join(parts)
diff --git a/anton/explainability.py b/anton/explainability.py
new file mode 100644
index 00000000..627e9b88
--- /dev/null
+++ b/anton/explainability.py
@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class ExplainabilityQuery:
+    datasource: str
+    sql: str
+    engine: str | None = None
+    status: str = "ok"
+    error_message: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "datasource": self.datasource,
+            "sql": self.sql,
+            "engine": self.engine,
+            "status": self.status,
+            "error_message": self.error_message,
+        }
+
+
+@dataclass
+class ExplainabilityRecord:
+    turn: int
+    created_at: str
+    user_message: str
+    answer_text: str
+    summary: str
+    data_sources: list[dict] = field(default_factory=list)
+    sql_queries: list[dict] = field(default_factory=list)
+    scratchpad_steps: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "turn": self.turn,
+            "created_at": self.created_at,
+            "user_message": self.user_message,
+            "answer_text": self.answer_text,
+            "summary": self.summary,
+            "data_sources": self.data_sources,
+            "sql_queries": self.sql_queries,
+            "scratchpad_steps": self.scratchpad_steps,
+        }
+
+
+class ExplainabilityStore:
+    def __init__(self, workspace_path: Path) -> None:
+        self._dir = workspace_path / ".anton" / "explainability"
+
+    def save(self, record: ExplainabilityRecord) -> None:
+        self._dir.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(record.to_dict(), ensure_ascii=False, indent=2) + "\n"
+        latest = self._dir / "latest.json"
+        latest.write_text(payload, encoding="utf-8")
+        turn_file = self._dir / f"turn-{record.turn:04d}.json"
+        turn_file.write_text(payload, encoding="utf-8")
+
+    def load_latest(self) -> ExplainabilityRecord | None:
+        latest = self._dir / "latest.json"
+        if not latest.is_file():
+            return None
+        try:
+            payload = json.loads(latest.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+        try:
+            return ExplainabilityRecord(
+                turn=int(payload.get("turn", 0)),
+                created_at=str(payload.get("created_at", "")),
+                user_message=str(payload.get("user_message", "")),
+                answer_text=str(payload.get("answer_text", "")),
+                summary=str(payload.get("summary", "")),
+                data_sources=list(payload.get("data_sources", [])),
+                sql_queries=list(payload.get("sql_queries", [])),
+                scratchpad_steps=list(payload.get("scratchpad_steps", [])),
+            )
+        except Exception:
+            return None
+
+
+class ExplainabilityCollector:
+    def __init__(self, store: ExplainabilityStore, *, turn: int, user_message: str) -> None:
+        self._store = store
+        self._turn = turn
+        self._user_message = user_message
+        self._created_at = _utc_now()
+        self._scratchpad_steps: list[str] = []
+        self._queries: list[ExplainabilityQuery] = []
+        self._sources: list[dict[str, str | None]] = []
+
+    def add_scratchpad_step(self, description: str) -> None:
+        cleaned = (description or "").strip()
+        if cleaned and cleaned not in self._scratchpad_steps:
+            self._scratchpad_steps.append(cleaned)
+
+    def add_query(
+        self,
+        *,
+        datasource: str,
+        sql: str,
+        engine: str | None = None,
+        status: str = "ok",
+        error_message: str | None = None,
+    ) -> None:
+        cleaned_sql = (sql or "").strip()
+        cleaned_ds = (datasource or "").strip() or "Unknown datasource"
+        if not cleaned_sql:
+            return
+        entry = ExplainabilityQuery(
+            datasource=cleaned_ds,
+            sql=cleaned_sql,
+            engine=(engine or "").strip() or None,
+            status=status,
+            error_message=(error_message or "").strip() or None,
+        )
+        if any(
+            existing.datasource == entry.datasource
+            and existing.sql == entry.sql
+            and existing.status == entry.status
+            for existing in self._queries
+        ):
+            return
+        self._queries.append(entry)
+        self.add_source(name=cleaned_ds, engine=(engine or "").strip() or None)
+
+    def add_source(self, *, name: str, engine: str | None = None) -> None:
+        cleaned_name = (name or "").strip()
+        if not cleaned_name:
+            return
+        entry = {"name": cleaned_name, "engine": (engine or "").strip() or None}
+        if entry not in self._sources:
+            self._sources.append(entry)
+
+    def add_sources_from_text(self, *texts: str) -> None:
+        for text in texts:
+            if not text:
+                continue
+            for source in _extract_sources_from_text(text):
+                self.add_source(name=source, engine=None)
+
+    def add_inferred_queries_from_code(self, code: str) -> None:
+        if self._queries:
+            return
+        sql_statements = _extract_sql_from_code(code)
+        datasource_names = _extract_datasource_names_from_code(code)
+        datasource = datasource_names[0] if datasource_names else "connected datasource"
+        for sql in sql_statements:
+            self.add_query(
+                datasource=datasource,
+                sql=sql,
+                engine=None,
+                status="ok",
+                error_message=None,
+            )
+
+    def finalize(self, answer_text: str) -> ExplainabilityRecord:
+        data_sources: list[dict] = []
+        seen_sources: set[tuple[str, str | None]] = set()
+        for source in self._sources:
+            key = (str(source.get("name", "")), source.get("engine"))
+            if key in seen_sources:
+                continue
+            seen_sources.add(key)
+            data_sources.append({"name": key[0], "engine": key[1]})
+
+        summary = self._build_summary(answer_text, data_sources)
+        record = ExplainabilityRecord(
+            turn=self._turn,
+            created_at=self._created_at,
+            user_message=self._user_message,
+            answer_text=answer_text.strip(),
+            summary=summary,
+            data_sources=data_sources,
+            sql_queries=[query.to_dict() for query in self._queries],
+            scratchpad_steps=list(self._scratchpad_steps),
+        )
+        if self._store is not None:
+            self._store.save(record)
+        return record
+
+    def _build_summary(self, answer_text: str, data_sources: list[dict]) -> str:
+        if self._queries:
+            source_names = ", ".join(source["name"] for source in data_sources[:3])
+            query_count = len(self._queries)
+            step_text = ""
+            if self._scratchpad_steps:
+                lead = self._scratchpad_steps[0].rstrip(".")
+                step_text = f" I used the scratchpad to {lead.lower()}."
+            return (
+                f"I queried {source_names} with {query_count} SQL "
+                f"{'statement' if query_count == 1 else 'statements'} to gather the data behind this answer."
+                f"{step_text}"
+            )
+        if data_sources:
+            source_names = ", ".join(source["name"] for source in data_sources[:3])
+            if self._scratchpad_steps:
+                lead = self._scratchpad_steps[0].rstrip(".").lower()
+                return (
+                    f"I gathered information from {source_names} and used the scratchpad to "
+                    f"{lead} before drafting the answer."
+                )
+            return f"I gathered information from {source_names} before drafting the answer."
+        if self._scratchpad_steps:
+            primary_step = self._scratchpad_steps[0].rstrip(".").lower()
+            return f"I used the scratchpad to {primary_step} before drafting the answer."
+        if answer_text.strip():
+            return "I answered directly from the conversation context without querying a datasource or generating SQL."
+        return "No explainability details were captured for this answer."
+
+
+_URL_RE = re.compile(r"https?://[^\s)\"'>]+")
+_SQL_LITERAL_RE = re.compile(
+    r"(?P<quote>'''|\"\"\"|'|\")(?P<body>.*?)(?P=quote)",
+    re.DOTALL,
+)
+_DS_PREFIX_RE = re.compile(r"\b(DS_[A-Z0-9_]+)__[A-Z0-9_]+\b")
+
+
+def _extract_sources_from_text(text: str) -> list[str]:
+    sources: list[str] = []
+    for match in _URL_RE.findall(text):
+        parsed = urlparse(match)
+        host = (parsed.hostname or "").lower()
+        host = host.removeprefix("www.")
+        if not host:
+            continue
+        if host not in sources:
+            sources.append(host)
+    return sources
+
+
+def _looks_like_sql(text: str) -> bool:
+    normalized = " ".join(text.strip().split()).upper()
+    if len(normalized) < 12:
+        return False
+    starters = ("SELECT ", "WITH ", "INSERT ", "UPDATE ", "DELETE ", "SHOW ", "DESCRIBE ")
+    if not normalized.startswith(starters):
+        return False
+    return any(keyword in normalized for keyword in (" FROM ", " JOIN ", " INTO ", " TABLE ", "SELECT "))
+
+
+def _extract_sql_from_code(code: str) -> list[str]:
+    sql_statements: list[str] = []
+    for match in _SQL_LITERAL_RE.finditer(code or ""):
+        body = match.group("body").strip()
+        if not _looks_like_sql(body):
+            continue
+        cleaned = "\n".join(line.rstrip() for line in body.splitlines()).strip()
+        if cleaned and cleaned not in sql_statements:
+            sql_statements.append(cleaned)
+    return sql_statements
+
+
+def _extract_datasource_names_from_code(code: str) -> list[str]:
+    names: list[str] = []
+    for prefix in _DS_PREFIX_RE.findall(code or ""):
+        slug = prefix.removeprefix("DS_").lower().replace("_", "-")
+        if slug not in names:
+            names.append(slug)
+    return names
diff --git a/anton/llm/client.py b/anton/llm/client.py
deleted file mode 100644
index a58c2170..00000000
--- a/anton/llm/client.py
+++ /dev/null
@@ -1,112 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import AsyncIterator
-from typing import TYPE_CHECKING
-
-from anton.llm.provider import LLMProvider, LLMResponse, StreamEvent
-
-if TYPE_CHECKING:
-    from anton.config.settings import AntonSettings
-
-
-class LLMClient:
-    def __init__(
-        self,
-        *,
-        planning_provider: LLMProvider,
-        planning_model: str,
-        coding_provider: LLMProvider,
-        coding_model: str,
-        max_tokens: int = 8192,
-    ) -> None:
-        self._planning_provider = planning_provider
-        self._planning_model = planning_model
-        self._coding_provider = coding_provider
-        self._coding_model = coding_model
-        self._max_tokens = max_tokens
-
-    async def plan(
-        self,
-        *,
-        system: str,
-        messages: list[dict],
-        tools: list[dict] | None = None,
-        max_tokens: int | None = None,
-    ) -> LLMResponse:
-        return await self._planning_provider.complete(
-            model=self._planning_model,
-            system=system,
-            messages=messages,
-            tools=tools,
-            max_tokens=max_tokens or self._max_tokens,
-        )
-
-    async def plan_stream(
-        self,
-        *,
-        system: str,
-        messages: list[dict],
-        tools: list[dict] | None = None,
-        max_tokens: int | None = None,
-    ) -> AsyncIterator[StreamEvent]:
-        async for event in self._planning_provider.stream(
-            model=self._planning_model,
-            system=system,
-            messages=messages,
-            tools=tools,
-            max_tokens=max_tokens or self._max_tokens,
-        ):
-            yield event
-
-    @property
-    def coding_provider(self) -> LLMProvider:
-        """The LLM provider used for coding/skill execution."""
-        return self._coding_provider
-
-    @property
-    def coding_model(self) -> str:
-        """The model name used for coding/skill execution."""
-        return self._coding_model
-
-    async def code(
-        self,
-        *,
-        system: str,
-        messages: list[dict],
-        tools: list[dict] | None = None,
-        max_tokens: int | None = None,
-    ) -> LLMResponse:
-        return await self._coding_provider.complete(
-            model=self._coding_model,
-            system=system,
-            messages=messages,
-            tools=tools,
-            max_tokens=max_tokens or self._max_tokens,
-        )
-
-    @classmethod
-    def from_settings(cls, settings: AntonSettings) -> LLMClient:
-        from anton.llm.anthropic import AnthropicProvider
-        from anton.llm.openai import OpenAIProvider
-
-        providers = {
-            "anthropic": lambda: AnthropicProvider(api_key=settings.anthropic_api_key),
-            "openai": lambda: OpenAIProvider(api_key=settings.openai_api_key, base_url=settings.openai_base_url, ssl_verify=settings.minds_ssl_verify),
-            "openai-compatible": lambda: OpenAIProvider(api_key=settings.openai_api_key, base_url=settings.openai_base_url, ssl_verify=settings.minds_ssl_verify),
-        }
-
-        planning_factory = providers.get(settings.planning_provider)
-        coding_factory = providers.get(settings.coding_provider)
-
-        if planning_factory is None:
-            raise ValueError(f"Unknown planning provider: {settings.planning_provider}")
-        if coding_factory is None:
-            raise ValueError(f"Unknown coding provider: {settings.coding_provider}")
-
-        return cls(
-            planning_provider=planning_factory(),
-            planning_model=settings.planning_model,
-            coding_provider=coding_factory(),
-            coding_model=settings.coding_model,
-            max_tokens=getattr(settings, "max_tokens", 8192),
-        )
diff --git a/anton/memory/reconsolidator.py b/anton/memory/reconsolidator.py
index 656d242b..32297e39 100644
--- a/anton/memory/reconsolidator.py
+++ b/anton/memory/reconsolidator.py
@@ -19,7 +19,7 @@
 import json
 from pathlib import Path
 
-from anton.memory.hippocampus import Hippocampus
+from anton.core.memory.hippocampus import Hippocampus
 
 
 def needs_reconsolidation(project_dir: Path) -> bool:
diff --git a/anton/minds_client.py b/anton/minds_client.py
index 3e1a0046..3215e4cc 100644
--- a/anton/minds_client.py
+++ b/anton/minds_client.py
@@ -13,13 +13,12 @@
 import ssl
 import urllib.error
 import urllib.request
-from pathlib import Path
 from typing import TYPE_CHECKING
 
-from anton.llm.openai import build_chat_completion_kwargs
+from anton.core.llm.openai import build_chat_completion_kwargs
 
 if TYPE_CHECKING:
-    from anton.settings import AntonSettings
+    from anton.config.settings import AntonSettings
 
 
 def minds_request(
diff --git a/anton/prompts.py b/anton/prompts.py
new file mode 100644
index 00000000..1a036dde
--- /dev/null
+++ b/anton/prompts.py
@@ -0,0 +1,9 @@
+"""Extra prompts for the open source terminal agent."""
+
+FILE_ATTACHMENTS_PROMPT = """
+FILE ATTACHMENTS:
+- Users can drag files or paste clipboard images. These appear as <file path="..."> tags.
+- For binary files (images, PDFs), use the scratchpad to read and process them.
+- Clipboard images are saved to .anton/uploads/ — open with Pillow, OpenCV, etc.
+"""
+
diff --git a/anton/publisher.py b/anton/publisher.py
index b6bf9738..a978a637 100644
--- a/anton/publisher.py
+++ b/anton/publisher.py
@@ -99,18 +99,26 @@ def publish(
     file_path: Path,
     *,
     api_key: str,
+    report_id: str | None = None,
     publish_url: str = DEFAULT_PUBLISH_URL,
     ssl_verify: bool = True,
 ) -> dict:
     """Zip and upload an HTML file/directory. Returns the upload response dict.
 
-    Response keys: user_prefix, md5, view_url, files
+    Args:
+        report_id: If provided, updates an existing report (new version).
+                   If None, creates a new report.
+
+    Response keys: user_prefix, report_id, md5, view_url, version, files
     """
     if not file_path.exists():
         raise FileNotFoundError(f"Path not found: {file_path}")
 
     zipped = _zip_html(file_path)
-    payload = json.dumps({"file_payload": base64.b64encode(zipped).decode()}).encode()
+    payload_dict: dict = {"file_payload": base64.b64encode(zipped).decode()}
+    if report_id:
+        payload_dict["report_id"] = report_id
+    payload = json.dumps(payload_dict).encode()
 
     url = f"{publish_url.rstrip('/')}/upload"
     raw = minds_request(url, api_key, method="POST", payload=payload, verify=ssl_verify)
diff --git a/anton/scratchpad.py b/anton/scratchpad.py
deleted file mode 100644
index c766d8a6..00000000
--- a/anton/scratchpad.py
+++ /dev/null
@@ -1,959 +0,0 @@
-"""Scratchpad — persistent Python subprocess for stateful, notebook-like execution."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import os
-import shutil
-import sys
-import tempfile
-import venv
-from dataclasses import dataclass, field
-from pathlib import Path
-
-_CELL_TIMEOUT_DEFAULT = 120        # Default total timeout when no estimate given
-_CELL_INACTIVITY_TIMEOUT = 30      # Max silence between output lines before killing
-_CELL_INACTIVITY_AFTER_PROGRESS = 60  # Grace window after a progress() call
-_INSTALL_TIMEOUT = 120
-_MAX_OUTPUT = 10_000
-_PROGRESS_MARKER = "__ANTON_PROGRESS__"
-_KEEP_RECENT = 5  # Number of recent cells to keep during compaction
-
-
-def _compute_timeouts(estimated_seconds: int) -> tuple[float, float]:
-    """Compute (total_timeout, inactivity_timeout) from estimated execution time.
-
-    - If estimate is 0: use defaults (120s total, 30s inactivity).
-    - Otherwise: total = max(estimate * 2, estimate + 30) with no cap.
-      Inactivity = max(estimate * 0.5, 30) — no hard cap, scales with estimate.
-    """
-    if estimated_seconds <= 0:
-        return float(_CELL_TIMEOUT_DEFAULT), float(_CELL_INACTIVITY_TIMEOUT)
-    total = max(estimated_seconds * 2, estimated_seconds + 30)
-    inactivity = max(estimated_seconds * 0.5, 30)
-    return float(total), float(inactivity)
-
-
-_BOOT_SCRIPT_PATH = Path(__file__).parent / "scratchpad_boot.py"
-
-_CELL_DELIM = "__ANTON_CELL_END__"
-_RESULT_START = "__ANTON_RESULT__"
-_RESULT_END = "__ANTON_RESULT_END__"
-
-
-@dataclass
-class Cell:
-    code: str
-    stdout: str
-    stderr: str
-    error: str | None
-    description: str = ""
-    estimated_time: str = ""
-    logs: str = ""
-
-
-@dataclass
-class Scratchpad:
-    name: str
-    cells: list[Cell] = field(default_factory=list)
-    _proc: asyncio.subprocess.Process | None = field(default=None, repr=False)
-    _boot_path: str | None = field(default=None, repr=False)
-    _coding_provider: str = field(default="anthropic", repr=False)
-    _coding_model: str = field(default="", repr=False)
-    _coding_api_key: str = field(default="", repr=False)
-    _coding_base_url: str = field(default="", repr=False)
-    _venv_dir: str | None = field(default=None, repr=False)
-    _venv_python: str | None = field(default=None, repr=False)
-    _installed_packages: set[str] = field(default_factory=set, repr=False)
-    _venvs_base: Path = field(
-        default_factory=lambda: Path("~/.anton/scratchpad-venvs").expanduser(),
-        repr=False,
-    )
-
-    _MAX_VENV_RETRIES = 3
-
-    def _ensure_venv(self) -> None:
-        """Create a lightweight per-scratchpad venv (idempotent).
-
-        Uses system_site_packages=True so the real system packages are visible.
-        If we're running inside a parent venv, we also drop a .pth file so the
-        parent venv's site-packages are visible in the child.
-
-        If a persistent venv already exists on disk it is recycled when healthy.
-        If the venv is broken (stale symlinks, missing Python binary, version
-        mismatch), it is deleted and recreated from scratch. Gives up after
-        _MAX_VENV_RETRIES.
-        """
-        if self._venv_dir is not None and self._verify_venv_python():
-            return
-
-        # Try to recycle a persistent venv from a previous session.
-        venv_path = self._venvs_base / self.name
-        if venv_path.is_dir() and self._try_recycle_venv(venv_path):
-            return
-
-        # Recycling failed or no prior venv — nuke leftovers and create fresh.
-        if venv_path.is_dir():
-            self._nuke_venv()
-
-        last_error: Exception | None = None
-        for attempt in range(1, self._MAX_VENV_RETRIES + 1):
-            try:
-                self._create_venv()
-                if self._verify_venv_python():
-                    self._setup_parent_site_packages()
-                    self._save_python_version()
-                    return
-                # Python binary exists but doesn't run — nuke and retry
-                raise RuntimeError(f"venv Python binary at {self._venv_python} is not functional")
-            except Exception as exc:
-                last_error = exc
-                # Clean up the broken venv before retrying
-                self._nuke_venv()
-
-        raise RuntimeError(
-            f"Failed to create a working Python venv after {self._MAX_VENV_RETRIES} attempts. "
-            f"Last error: {last_error}. "
-            f"Try running: python3 -c 'print(\"ok\")' to verify your Python installation."
-        )
-
-    @staticmethod
-    def _find_uv() -> str | None:
-        """Return the path to the ``uv`` binary, or *None* if unavailable."""
-        # Fast path: already on PATH
-        uv = shutil.which("uv")
-        if uv:
-            return uv
-        # Common install locations
-        if sys.platform == "win32":
-            candidates = (
-                os.path.expanduser("~/.local/bin/uv.exe"),
-                os.path.expanduser("~/.cargo/bin/uv.exe"),
-            )
-        else:
-            candidates = (
-                os.path.expanduser("~/.local/bin/uv"),
-                os.path.expanduser("~/.cargo/bin/uv"),
-            )
-        for candidate in candidates:
-            if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
-                return candidate
-        return None
-
-    def _create_venv(self) -> None:
-        """Allocate a venv directory and create the virtual environment.
-
-        Prefers ``uv venv`` when available — it is faster, more reliable on
-        macOS (doesn't break when Homebrew upgrades Python), and doesn't depend
-        on the ``venv`` stdlib module being functional.  Falls back to
-        ``venv.create()`` when ``uv`` isn't found.
-
-        The venv is persisted at ``{_venvs_base}/{name}`` on all platforms so
-        installed packages survive across sessions.
-        """
-        import subprocess as _sp
-
-        self._venv_dir = str(self._venvs_base / self.name)
-        os.makedirs(self._venv_dir, exist_ok=True)
-
-        uv = self._find_uv()
-        if uv:
-            _sp.run(
-                [uv, "venv", self._venv_dir,
-                 "--python", sys.executable,
-                 "--system-site-packages", "--seed", "--quiet"],
-                check=True,
-                capture_output=True,
-                timeout=30,
-            )
-        else:
-            venv.create(self._venv_dir, system_site_packages=True, with_pip=False, clear=True)
-
-        if sys.platform == "win32":
-            bin_dir = os.path.join(self._venv_dir, "Scripts")
-            self._venv_python = os.path.join(bin_dir, "python.exe")
-            self._add_windows_firewall_rule()
-        else:
-            bin_dir = os.path.join(self._venv_dir, "bin")
-            self._venv_python = os.path.join(bin_dir, "python")
-
-    def _verify_venv_python(self) -> bool:
-        """Check that the venv Python binary exists and can execute."""
-        if self._venv_python is None:
-            return False
-        if not os.path.exists(self._venv_python):
-            return False
-        # Quick smoke test — run python with a trivial command
-        try:
-            import subprocess
-            result = subprocess.run(
-                [self._venv_python, "-c", "print('ok')"],
-                capture_output=True,
-                timeout=5,
-            )
-            return result.returncode == 0 and "ok" in result.stdout.decode()
-        except Exception:
-            return False
-
-    def _nuke_venv(self) -> None:
-        """Delete the venv directory entirely so it can be recreated."""
-        if self._venv_dir is not None:
-            try:
-                shutil.rmtree(self._venv_dir)
-            except OSError:
-                pass
-        self._venv_dir = None
-        self._venv_python = None
-
-    def _add_windows_firewall_rule(self) -> None:
-        """Add a Windows Firewall outbound-allow rule for this venv's python.exe.
-
-        Windows Firewall blocks new executables by default.  Without a rule,
-        scratchpad HTTP calls (httpx, requests, etc.) silently time out.
-        Runs silently — failures are ignored (user can add rules manually).
-        """
-        if self._venv_python is None or not os.path.isfile(self._venv_python):
-            return
-        import subprocess as _sp
-        rule_name = f"Anton Scratchpad - {self.name}"
-        try:
-            _sp.run(
-                [
-                    "netsh", "advfirewall", "firewall", "add", "rule",
-                    f"name={rule_name}", "dir=out", "action=allow",
-                    f"program={self._venv_python}",
-                ],
-                capture_output=True,
-                timeout=10,
-            )
-        except Exception:
-            pass
-        self._installed_packages.clear()
-
-    def _setup_parent_site_packages(self) -> None:
-        """Make parent venv's packages visible in the child venv."""
-        if sys.prefix != sys.base_prefix:
-            import site as _site
-            parent_site = _site.getsitepackages()
-            child_site = None
-            for dirpath, dirnames, _ in os.walk(self._venv_dir):
-                if "site-packages" in dirnames:
-                    child_site = os.path.join(dirpath, "site-packages")
-                    break
-            if child_site and parent_site:
-                pth_path = os.path.join(child_site, "_parent_venv.pth")
-                with open(pth_path, "w") as f:
-                    for sp in parent_site:
-                        f.write(sp + "\n")
-
-    def _try_recycle_venv(self, venv_path: Path) -> bool:
-        """Validate and reuse a persistent venv from a previous session.
-
-        Sets internal paths, verifies the Python binary is functional, checks
-        the Python version matches, loads saved requirements, and refreshes
-        parent-site-packages links.  Returns False on any failure (caller
-        should nuke the directory and create a fresh venv).
-        """
-        try:
-            self._venv_dir = str(venv_path)
-            if sys.platform == "win32":
-                self._venv_python = os.path.join(self._venv_dir, "Scripts", "python.exe")
-            else:
-                self._venv_python = os.path.join(self._venv_dir, "bin", "python")
-
-            if not self._verify_venv_python():
-                return False
-            if not self._check_python_version():
-                return False
-            self._load_requirements()
-            self._setup_parent_site_packages()
-            return True
-        except Exception:
-            return False
-
-    def _save_requirements(self) -> None:
-        """Write installed package names to requirements.txt (best-effort)."""
-        if not self._venv_dir or not self._installed_packages:
-            return
-        try:
-            req_path = os.path.join(self._venv_dir, "requirements.txt")
-            with open(req_path, "w") as f:
-                for pkg in sorted(self._installed_packages):
-                    f.write(pkg + "\n")
-        except OSError:
-            pass
-
-    def _load_requirements(self) -> None:
-        """Read requirements.txt into _installed_packages."""
-        if not self._venv_dir:
-            return
-        req_path = os.path.join(self._venv_dir, "requirements.txt")
-        try:
-            with open(req_path) as f:
-                for line in f:
-                    pkg = line.strip()
-                    if pkg:
-                        self._installed_packages.add(pkg)
-        except FileNotFoundError:
-            pass
-
-    def _save_python_version(self) -> None:
-        """Write the current Python major.minor to .python_version."""
-        if not self._venv_dir:
-            return
-        try:
-            ver_path = os.path.join(self._venv_dir, ".python_version")
-            with open(ver_path, "w") as f:
-                f.write(f"{sys.version_info.major}.{sys.version_info.minor}\n")
-        except OSError:
-            pass
-
-    def _check_python_version(self) -> bool:
-        """Return True if .python_version matches the current Python."""
-        if not self._venv_dir:
-            return False
-        ver_path = os.path.join(self._venv_dir, ".python_version")
-        try:
-            with open(ver_path) as f:
-                saved = f.read().strip()
-            expected = f"{sys.version_info.major}.{sys.version_info.minor}"
-            return saved == expected
-        except FileNotFoundError:
-            # No version file — treat as mismatch so it gets recreated with one.
-            return False
-
-    async def start(self) -> None:
-        """Write the boot script to a temp file and launch the subprocess."""
-        self._ensure_venv()
-
-        boot_code = _BOOT_SCRIPT_PATH.read_text()
-        fd, path = tempfile.mkstemp(suffix=".py", prefix="anton_scratchpad_")
-        os.write(fd, boot_code.encode())
-        os.close(fd)
-        self._boot_path = path
-
-        env = os.environ.copy()
-        if self._coding_model:
-            env["ANTON_SCRATCHPAD_MODEL"] = self._coding_model
-        if self._coding_provider:
-            env["ANTON_SCRATCHPAD_PROVIDER"] = self._coding_provider
-        # Ensure the SDKs can find API keys under their expected names.
-        # Anton stores them as ANTON_*_API_KEY; the SDKs expect *_API_KEY.
-        if "ANTHROPIC_API_KEY" not in env and "ANTON_ANTHROPIC_API_KEY" in env:
-            env["ANTHROPIC_API_KEY"] = env["ANTON_ANTHROPIC_API_KEY"]
-        if "OPENAI_API_KEY" not in env and "ANTON_OPENAI_API_KEY" in env:
-            env["OPENAI_API_KEY"] = env["ANTON_OPENAI_API_KEY"]
-        if "OPENAI_BASE_URL" not in env and "ANTON_OPENAI_BASE_URL" in env:
-            env["OPENAI_BASE_URL"] = env["ANTON_OPENAI_BASE_URL"]
-        # Minds credentials can serve as OpenAI-compatible fallback when
-        # ANTON_OPENAI_* vars aren't persisted (new clean config path).
-        if "OPENAI_API_KEY" not in env and "ANTON_MINDS_API_KEY" in env and self._coding_provider == "openai-compatible":
-            env["OPENAI_API_KEY"] = env["ANTON_MINDS_API_KEY"]
-        if "OPENAI_BASE_URL" not in env and "ANTON_MINDS_URL" in env and self._coding_provider == "openai-compatible":
-            env["OPENAI_BASE_URL"] = f"{env['ANTON_MINDS_URL'].rstrip('/')}/api/v1"
-        # If settings provided an explicit API key (e.g. from ~/.anton/.env or
-        # Pydantic settings), inject it so the subprocess SDK can authenticate.
-        if self._coding_api_key:
-            sdk_key = {
-                "anthropic": "ANTHROPIC_API_KEY",
-                "openai": "OPENAI_API_KEY",
-                "openai-compatible": "OPENAI_API_KEY",
-            }.get(self._coding_provider, "")
-            if sdk_key:
-                env[sdk_key] = self._coding_api_key
-        # For openai-compatible (Minds), force OPENAI_BASE_URL so get_llm()
-        # doesn't default to api.openai.com. The explicit _coding_base_url from
-        # settings takes top priority, then ANTON_OPENAI_BASE_URL from .env.
-        if self._coding_provider in ("openai", "openai-compatible"):
-            base_url = (
-                self._coding_base_url
-                or env.get("ANTON_OPENAI_BASE_URL")
-                or env.get("OPENAI_BASE_URL")
-                or ""
-            )
-            if base_url:
-                env["OPENAI_BASE_URL"] = base_url
-                env["ANTON_OPENAI_BASE_URL"] = base_url
-        # Pass uv path so the boot script can use it for auto-installing
-        # missing modules (same installer that created the venv).
-        uv = self._find_uv()
-        if uv:
-            env["ANTON_UV_PATH"] = uv
-
-        # Ensure the anton package is importable in the subprocess (needed for
-        # get_llm and skill loading). The boot script runs from a temp file, so
-        # the project root isn't on sys.path by default.
-        _anton_root = str(Path(__file__).resolve().parent.parent)
-        python_path = env.get("PYTHONPATH", "")
-        if _anton_root not in python_path:
-            env["PYTHONPATH"] = _anton_root + (os.pathsep + python_path if python_path else "")
-
-        try:
-            self._proc = await asyncio.create_subprocess_exec(
-                self._venv_python, path,
-                stdin=asyncio.subprocess.PIPE,
-                stdout=asyncio.subprocess.PIPE,
-                stderr=asyncio.subprocess.PIPE,
-                env=env,
-                # Own session so os.killpg() kills the whole process tree
-                # (grandchildren spawned by user code, pip installs, etc.)
-                start_new_session=(sys.platform != "win32"),
-            )
-        except (FileNotFoundError, PermissionError, OSError) as exc:
-            # Python binary is missing or broken — nuke venv and raise
-            self._nuke_venv()
-            raise RuntimeError(
-                f"Failed to start scratchpad: {exc}. "
-                f"The Python venv has been deleted and will be recreated on next attempt."
-            ) from exc
-
-    async def execute(
-        self,
-        code: str,
-        *,
-        description: str = "",
-        estimated_time: str = "",
-        estimated_seconds: int = 0,
-    ) -> Cell:
-        """Send code to the subprocess, read the JSON result, return a Cell.
-
-        Backward-compatible wrapper around execute_streaming() that drains
-        all events and returns just the final Cell.
-        """
-        async for item in self.execute_streaming(
-            code,
-            description=description,
-            estimated_time=estimated_time,
-            estimated_seconds=estimated_seconds,
-        ):
-            if isinstance(item, Cell):
-                return item
-        # Should not reach here, but just in case
-        return Cell(code=code, stdout="", stderr="", error="No result produced.")
-
-    async def execute_streaming(
-        self,
-        code: str,
-        *,
-        description: str = "",
-        estimated_time: str = "",
-        estimated_seconds: int = 0,
-        cancel_event: asyncio.Event | None = None,
-    ):
-        """Async generator that sends code and yields progress strings and a final Cell.
-
-        Yields:
-            str — progress messages from progress() calls in the cell code
-            Cell — the final execution result (always the last item)
-        """
-        if self._proc is None or self._proc.returncode is not None:
-            yield Cell(
-                code=code,
-                stdout="",
-                stderr="",
-                error="Scratchpad process is not running. Use reset to restart.",
-                description=description,
-                estimated_time=estimated_time,
-            )
-            return
-
-        payload = code + "\n" + _CELL_DELIM + "\n"
-        self._proc.stdin.write(payload.encode())  # type: ignore[union-attr]
-        await self._proc.stdin.drain()  # type: ignore[union-attr]
-
-        total_timeout, inactivity_timeout = _compute_timeouts(estimated_seconds)
-
-        try:
-            result_data: dict | None = None
-            async for item in self._read_result(
-                total_timeout=total_timeout,
-                inactivity_timeout=inactivity_timeout,
-                cancel_event=cancel_event,
-            ):
-                if isinstance(item, str):
-                    yield item  # progress message
-                else:
-                    result_data = item
-        except (asyncio.TimeoutError, asyncio.CancelledError) as exc:
-            self._kill_tree()
-            try:
-                await asyncio.wait_for(self._proc.wait(), timeout=5)
-            except asyncio.TimeoutError:
-                pass
-            error_msg = (
-                f"{exc}. Process killed — state lost. Use reset to restart.\n\n"
-                "If a database query was running, it may still be executing server-side.\n"
-                "To check and cancel: run SHOW PROCESSLIST (MySQL) or\n"
-                "SELECT * FROM information_schema.processlist WHERE status='running' and cancel with KILL <id>.\n"
-                "For Snowflake: use SHOW RUNNING QUERIES and SELECT SYSTEM$CANCEL_ALL_QUERIES(<session_id>)."
-            )
-            cell = Cell(
-                code=code,
-                stdout="",
-                stderr="",
-                error=error_msg,
-                description=description,
-                estimated_time=estimated_time,
-            )
-            self.cells.append(cell)
-            yield cell
-            return
-        except Exception as exc:
-            # Catch-all for unexpected errors (e.g. JSON parse failures).
-            # The subprocess may still be alive and usable — don't kill it.
-            # Return the error as a Cell so the LLM can see it and recover.
-            cell = Cell(
-                code=code,
-                stdout="",
-                stderr="",
-                error=f"Scratchpad result could not be read: {exc}. The scratchpad is still running — you can retry.",
-                description=description,
-                estimated_time=estimated_time,
-            )
-            self.cells.append(cell)
-            yield cell
-            return
-
-        if result_data is None:
-            result_data = {"stdout": "", "stderr": "", "error": "Process exited unexpectedly."}
-
-        # Track packages that the subprocess auto-installed on ModuleNotFoundError
-        for pkg in result_data.get("auto_installed") or []:
-            self._installed_packages.add(pkg.lower())
-
-        cell = Cell(
-            code=code,
-            stdout=result_data.get("stdout", ""),
-            stderr=result_data.get("stderr", ""),
-            error=result_data.get("error"),
-            description=description,
-            estimated_time=estimated_time,
-            logs=result_data.get("logs", ""),
-        )
-        self.cells.append(cell)
-        yield cell
-
-    async def _read_result(
-        self,
-        *,
-        total_timeout: float = _CELL_TIMEOUT_DEFAULT,
-        inactivity_timeout: float = _CELL_INACTIVITY_TIMEOUT,
-        cancel_event: asyncio.Event | None = None,
-    ):
-        """Async generator that reads lines from stdout until result delimiters.
-
-        Yields:
-            str — progress messages (lines starting with _PROGRESS_MARKER)
-            dict — the final JSON result (always the last item)
-
-        Raises asyncio.TimeoutError with a descriptive message.
-        Raises asyncio.CancelledError if cancel_event is set.
-
-        After a progress() call is received, the inactivity window is extended
-        to _CELL_INACTIVITY_AFTER_PROGRESS (60s) so that long-running work
-        that signals liveness isn't killed prematurely.
-        """
-        import time as _time
-
-        lines: list[str] = []
-        in_result = False
-        start = _time.monotonic()
-        current_inactivity = inactivity_timeout
-
-        while True:
-            if cancel_event is not None and cancel_event.is_set():
-                raise asyncio.CancelledError("Cancelled by user")
-            elapsed = _time.monotonic() - start
-            remaining_total = total_timeout - elapsed
-            if remaining_total <= 0:
-                raise asyncio.TimeoutError(
-                    f"Cell timed out after {total_timeout:.0f}s total"
-                )
-
-            line_timeout = min(current_inactivity, remaining_total)
-            try:
-                raw = await asyncio.wait_for(
-                    self._proc.stdout.readline(),  # type: ignore[union-attr]
-                    timeout=line_timeout,
-                )
-            except asyncio.TimeoutError:
-                # Determine which timeout was hit
-                elapsed_now = _time.monotonic() - start
-                if elapsed_now >= total_timeout - 0.5:
-                    raise asyncio.TimeoutError(
-                        f"Cell timed out after {total_timeout:.0f}s total"
-                    ) from None
-                raise asyncio.TimeoutError(
-                    f"Cell killed after {current_inactivity:.0f}s of inactivity "
-                    f"(no output or progress() calls)"
-                ) from None
-
-            if not raw:
-                yield {"stdout": "", "stderr": "", "error": "Process exited unexpectedly."}
-                return
-
-            line = raw.decode().rstrip("\r\n")
-
-            # Progress marker — yield to caller, don't store.
-            # Extend inactivity window: the cell is actively working.
-            if line.startswith(_PROGRESS_MARKER):
-                current_inactivity = max(
-                    current_inactivity, _CELL_INACTIVITY_AFTER_PROGRESS,
-                )
-                message = line[len(_PROGRESS_MARKER):].strip()
-                yield message
-                continue
-
-            if line == _RESULT_START:
-                in_result = True
-                continue
-            if line == _RESULT_END:
-                break
-            if in_result:
-                lines.append(line)
-
-        raw_text = "\n".join(lines)
-        try:
-            yield json.loads(raw_text)
-        except json.JSONDecodeError:
-            # Try to extract valid JSON by finding the outermost { }
-            try:
-                start = raw_text.index("{")
-                end = raw_text.rindex("}") + 1
-                yield json.loads(raw_text[start:end])
-            except (ValueError, json.JSONDecodeError):
-                yield {
-                    "stdout": raw_text,
-                    "stderr": "",
-                    "logs": "",
-                    "error": "Scratchpad result was malformed (JSON parse failed). Output above may be partial.",
-                }
-
-    def view(self) -> str:
-        """Format all cells with their outputs."""
-        if not self.cells:
-            return f"Scratchpad '{self.name}' is empty."
-
-        parts: list[str] = []
-        for i, cell in enumerate(self.cells):
-            header = f"--- Cell {i + 1}"
-            if cell.description:
-                header += f": {cell.description}"
-            header += " ---"
-            parts.append(header)
-            parts.append(cell.code)
-            if cell.stdout:
-                parts.append(f"[output]\n{cell.stdout}")
-            if cell.logs:
-                parts.append(f"[logs]\n{cell.logs}")
-            if cell.stderr:
-                parts.append(f"[stderr]\n{cell.stderr}")
-            if cell.error:
-                parts.append(f"[error]\n{cell.error}")
-            if not cell.stdout and not cell.logs and not cell.stderr and not cell.error:
-                parts.append("(no output)")
-        return "\n".join(parts)
-
-    @staticmethod
-    def _truncate_output(text: str, max_lines: int = 20, max_chars: int = 2000) -> str:
-        """Truncate output to *max_lines* / *max_chars*, whichever is shorter."""
-        lines = text.split("\n")
-        # Apply line limit
-        if len(lines) > max_lines:
-            kept = "\n".join(lines[:max_lines])
-            remaining = len(lines) - max_lines
-            return kept + f"\n... ({remaining} more lines)"
-        # Apply char limit (don't cut mid-line)
-        if len(text) > max_chars:
-            total = 0
-            kept_lines: list[str] = []
-            for line in lines:
-                if total + len(line) + 1 > max_chars and kept_lines:
-                    break
-                kept_lines.append(line)
-                total += len(line) + 1
-            return "\n".join(kept_lines) + "\n... (truncated)"
-        return text
-
-    def render_notebook(self) -> str:
-        """Return a clean markdown notebook-style summary of all cells."""
-        # Filter out empty/whitespace-only cells
-        numbered: list[tuple[int, Cell]] = []
-        idx = 0
-        for cell in self.cells:
-            idx += 1
-            if not cell.code.strip():
-                continue
-            numbered.append((idx, cell))
-
-        if not numbered:
-            return f"Scratchpad '{self.name}' has no cells."
-
-        parts: list[str] = [f"## Scratchpad: {self.name} ({len(numbered)} cells)"]
-
-        for i, (num, cell) in enumerate(numbered):
-            header = f"\n### Cell {num}"
-            if cell.description:
-                header += f" \u2014 {cell.description}"
-            parts.append(header)
-            parts.append(f"```python\n{cell.code}\n```\n")
-
-            if cell.error:
-                # Show only the last traceback line
-                last_line = cell.error.strip().split("\n")[-1]
-                parts.append(f"**Error:** `{last_line}`")
-                # If there was partial output before the error, show it
-                if cell.stdout:
-                    truncated = self._truncate_output(cell.stdout.rstrip("\n"))
-                    parts.append(f"**Partial output:**\n```\n{truncated}\n```\n")
-            elif cell.stdout:
-                truncated = self._truncate_output(cell.stdout.rstrip("\n"))
-                parts.append(f"**Output:**\n```\n{truncated}\n```\n")
-
-            if cell.logs:
-                truncated_logs = self._truncate_output(cell.logs.rstrip("\n"), max_lines=10, max_chars=1000)
-                parts.append(f"**Logs:**\n```\n{truncated_logs}\n```\n")
-
-            if i < len(numbered) - 1:
-                parts.append("---")
-
-        return "\n".join(parts)
-
-    def _compact_cells(self) -> bool:
-        """Collapse old cells into a single summary cell to reduce context size.
-
-        Keeps the most recent _KEEP_RECENT cells intact.  Older cells are
-        replaced by one summary cell with a one-line-per-cell digest.
-
-        Returns True if compaction actually happened.
-        """
-        if len(self.cells) <= _KEEP_RECENT + 1:
-            return False
-
-        to_compact = self.cells[: -_KEEP_RECENT]
-        recent = self.cells[-_KEEP_RECENT:]
-
-        summary_lines: list[str] = []
-        for i, cell in enumerate(to_compact, 1):
-            status = "error" if cell.error else "ok"
-            desc = cell.description or f"Cell {i}"
-            first_line = ""
-            output = cell.stdout or cell.error or ""
-            if output:
-                first_line = output.strip().split("\n")[0][:120]
-            summary_lines.append(f"  [{status}] {desc}: {first_line}")
-
-        summary_text = (
-            f"# Compacted {len(to_compact)} earlier cells:\n"
-            + "\n".join(summary_lines)
-        )
-        summary_cell = Cell(
-            code="# (compacted — see summary above)",
-            stdout=summary_text,
-            stderr="",
-            error=None,
-            description=f"Summary of cells 1–{len(to_compact)}",
-        )
-        self.cells = [summary_cell] + recent
-        return True
-
-    async def cancel_running(self) -> None:
-        """Kill the current execution and restart the subprocess.
-
-        Called when the user cancels (ESC / Ctrl-C) during a running cell.
-        Kills the entire process tree, records a cancelled cell, then restarts
-        so the scratchpad is ready for the next use.
-        """
-        if self._proc is None or self._proc.returncode is not None:
-            return
-        self._kill_tree()
-        try:
-            await asyncio.wait_for(self._proc.wait(), timeout=5)
-        except asyncio.TimeoutError:
-            pass
-        # Record the cancelled execution
-        self.cells.append(Cell(
-            code="# (cancelled by user)",
-            stdout="",
-            stderr="",
-            error="Cancelled by user.",
-            description="Cancelled",
-        ))
-        # Restart so the pad is usable again
-        self._proc = None
-        await self.start()
-
-    async def _stop_process(self) -> None:
-        """Kill the subprocess and delete the boot script, but keep the venv."""
-        if self._proc is not None and self._proc.returncode is None:
-            try:
-                self._kill_tree()
-                await asyncio.wait_for(self._proc.wait(), timeout=5)
-            except (ProcessLookupError, asyncio.TimeoutError):
-                pass
-        # Close transport pipes to prevent "Event loop is closed" noise
-        # from __del__ during Python shutdown.  Only stdin (a StreamWriter)
-        # has .close(); stdout/stderr are StreamReaders with no close method.
-        if self._proc is not None:
-            pipe = self._proc.stdin
-            if pipe is not None:
-                if hasattr(pipe, "is_closing"):
-                    if not pipe.is_closing():
-                        pipe.close()
-                else:
-                    pipe.close()
-        self._proc = None
-        if self._boot_path is not None:
-            try:
-                os.unlink(self._boot_path)
-            except OSError:
-                pass
-            self._boot_path = None
-
-    def _kill_tree(self) -> None:
-        """Kill the subprocess and all its children via process group."""
-        if self._proc is None or self._proc.returncode is not None:
-            return
-        pid = self._proc.pid
-        if sys.platform != "win32":
-            # Kill the entire process group (subprocess + grandchildren)
-            import signal
-            try:
-                os.killpg(pid, signal.SIGKILL)
-            except (ProcessLookupError, PermissionError):
-                # Fallback: kill just the direct child
-                try:
-                    self._proc.kill()
-                except ProcessLookupError:
-                    pass
-        else:
-            self._proc.kill()
-
-    async def reset(self) -> None:
-        """Kill the process, clear cells, restart.
-
-        If the venv is healthy, it's reused (installed packages survive).
-        If the venv is broken, it's deleted and recreated from scratch.
-        """
-        await self._stop_process()
-        self.cells.clear()
-        # If the venv Python is broken, nuke it so _ensure_venv recreates it
-        if not self._verify_venv_python():
-            self._nuke_venv()
-        await self.start()
-
-    async def close(self) -> None:
-        """Kill the process and clean up the boot script temp file.
-
-        The venv is preserved on disk so installed packages survive across
-        sessions. A ``requirements.txt`` is saved to record what was installed.
-        """
-        await self._stop_process()
-        if self._venv_dir is not None:
-            self._save_requirements()
-            self._venv_dir = None
-            self._venv_python = None
-
-    async def install_packages(self, packages: list[str]) -> str:
-        """Install packages into the scratchpad's venv via pip (or uv pip)."""
-        if not packages:
-            return "No packages specified."
-        # Skip packages we've already installed in this scratchpad
-        needed = [p for p in packages if p.lower() not in self._installed_packages]
-        if not needed:
-            return "All packages already installed."
-        self._ensure_venv()
-
-        uv = self._find_uv()
-        if uv:
-            cmd = [uv, "pip", "install", "--python", self._venv_python, *needed]
-        else:
-            cmd = [self._venv_python, "-m", "pip", "install", "--no-input", *needed]
-
-        proc = await asyncio.create_subprocess_exec(
-            *cmd,
-            stdout=asyncio.subprocess.PIPE,
-            stderr=asyncio.subprocess.STDOUT,
-        )
-        try:
-            stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=_INSTALL_TIMEOUT)
-        except asyncio.TimeoutError:
-            proc.kill()
-            await proc.wait()
-            return f"Install timed out after {_INSTALL_TIMEOUT}s."
-        output = stdout.decode()
-        if proc.returncode != 0:
-            return f"Install failed (exit {proc.returncode}):\n{output}"
-        # Track successfully installed packages
-        for p in needed:
-            self._installed_packages.add(p.lower())
-        return output
-
-
-class ScratchpadManager:
-    """Manages named scratchpad instances."""
-
-    def __init__(
-        self,
-        coding_provider: str = "anthropic",
-        coding_model: str = "",
-        coding_api_key: str = "",
-        coding_base_url: str = "",
-        workspace_path: Path | None = None,
-    ) -> None:
-        self._pads: dict[str, Scratchpad] = {}
-        self._coding_provider: str = coding_provider
-        self._coding_model: str = coding_model
-        self._coding_api_key: str = coding_api_key
-        self._coding_base_url: str = coding_base_url
-        if workspace_path is not None:
-            self._venvs_base = workspace_path / ".anton" / "scratchpad-venvs"
-        else:
-            self._venvs_base = Path("~/.anton/scratchpad-venvs").expanduser()
-        self._available_packages: list[str] = self.probe_packages()
-
-    @staticmethod
-    def probe_packages() -> list[str]:
-        """Return sorted list of installed package distribution names."""
-        from importlib.metadata import distributions
-
-        return sorted({d.metadata["Name"] for d in distributions()})
-
-    async def get_or_create(self, name: str) -> Scratchpad:
-        """Return existing pad or create + start a new one."""
-        if name not in self._pads:
-            pad = Scratchpad(
-                name=name,
-                _coding_provider=self._coding_provider,
-                _coding_model=self._coding_model,
-                _coding_api_key=self._coding_api_key,
-                _coding_base_url=self._coding_base_url,
-                _venvs_base=self._venvs_base,
-            )
-            await pad.start()
-            self._pads[name] = pad
-        return self._pads[name]
-
-    async def remove(self, name: str) -> str:
-        """Kill and fully delete a scratchpad (including its persistent venv)."""
-        pad = self._pads.pop(name, None)
-        if pad is None:
-            return f"No scratchpad named '{name}'."
-        await pad._stop_process()
-        pad._nuke_venv()
-        return f"Scratchpad '{name}' removed."
-
-    def list_pads(self) -> list[str]:
-        return list(self._pads.keys())
-
-    async def cancel_all_running(self) -> None:
-        """Cancel running executions in all scratchpads and restart them."""
-        for pad in self._pads.values():
-            await pad.cancel_running()
-
-    async def close_all(self) -> None:
-        """Cleanup all scratchpads on session end."""
-        for pad in self._pads.values():
-            await pad.close()
-        self._pads.clear()
diff --git a/anton/tools.py b/anton/tools.py
index ca4669cf..cdccb73e 100644
--- a/anton/tools.py
+++ b/anton/tools.py
@@ -1,493 +1,66 @@
-"""Dynamic tool registry — decorator-based registration for chat tools."""
+"""Extra tools for the open source terminal agent."""
 
 from __future__ import annotations
+from typing import TYPE_CHECKING
 
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from anton.core.tools.tool_defs import ToolDef
 
 if TYPE_CHECKING:
-    from anton.chat import ChatSession
-
-
-@dataclass
-class ToolDef:
-    name: str
-    description: str
-    input_schema: dict
-    handler: Callable  # async (session, tc_input) -> str
-    stream_handler: Callable | None = None  # async generator version
-
-
-_registry: dict[str, ToolDef] = {}
-
-
-def tool(name: str, *, description: str, input_schema: dict):
-    """Decorator to register a tool with its handler."""
-    def decorator(fn):
-        _registry[name] = ToolDef(
-            name=name,
-            description=description,
-            input_schema=input_schema,
-            handler=fn,
-        )
-        return fn
-    return decorator
-
-
-def tool_stream(name: str):
-    """Decorator to register a streaming handler for an existing tool."""
-    def decorator(fn):
-        if name in _registry:
-            _registry[name].stream_handler = fn
-        return fn
-    return decorator
-
-
-def get_tool(name: str) -> ToolDef | None:
-    return _registry.get(name)
-
-
-def all_tools() -> list[ToolDef]:
-    return list(_registry.values())
-
-
-def build_tool_schemas(available: list[str]) -> list[dict]:
-    """Build API-ready tool schema dicts for the given tool names."""
-    return [
-        {"name": t.name, "description": t.description, "input_schema": t.input_schema}
-        for t in _registry.values()
-        if t.name in available
-    ]
-
-
-MEMORIZE_TOOL = {
-    "name": "memorize",
-    "description": (
-        "Encode a rule or lesson into long-term memory for future sessions. "
-        "Use this when you learn something important, discover a useful pattern, "
-        "or the user asks you to remember something.\n\n"
-        "Entry kinds:\n"
-        "- always: Something to always do ('Use httpx instead of requests')\n"
-        "- never: Something to never do ('Never use time.sleep() in scratchpad')\n"
-        "- when: Conditional rule ('If paginated API → use async + progress()')\n"
-        "- lesson: Factual knowledge ('CoinGecko rate-limits at 50/min')\n"
-        "- profile: Fact about the user ('Name: Jorge', 'Prefers dark mode')"
-    ),
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "entries": {
-                "type": "array",
-                "items": {
-                    "type": "object",
-                    "properties": {
-                        "text": {
-                            "type": "string",
-                            "description": "The memory to encode",
-                        },
-                        "kind": {
-                            "type": "string",
-                            "enum": ["always", "never", "when", "lesson", "profile"],
-                        },
-                        "scope": {
-                            "type": "string",
-                            "enum": ["global", "project"],
-                        },
-                        "topic": {
-                            "type": "string",
-                            "description": "Topic slug for lessons (e.g. 'api-coingecko')",
-                        },
-                    },
-                    "required": ["text", "kind", "scope"],
-                },
-            },
-        },
-        "required": ["entries"],
-    },
-}
-
-RECALL_TOOL = {
-    "name": "recall",
-    "description": (
-        "Search your episodic memory — an archive of past conversations. "
-        "ONLY use this when the user explicitly asks about a previous conversation "
-        "or session (e.g. 'what did we talk about last time?', 'remember when we...', "
-        "'have we discussed X before?'). Do NOT use this for questions about code, "
-        "files, or data in the workspace — use the scratchpad to explore those directly.\n\n"
-        "Returns timestamped episodes matching the query (newest first). "
-        "A single call is enough — do not call multiple times with different queries."
-    ),
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "query": {
-                "type": "string",
-                "description": "Search term to find in past conversations.",
-            },
-            "max_results": {
-                "type": "integer",
-                "description": "Maximum episodes to return (default 20).",
-            },
-            "days_back": {
-                "type": "integer",
-                "description": "Only search episodes from the last N days.",
-            },
-        },
-        "required": ["query"],
-    },
-}
-
-CONNECT_DATASOURCE_TOOL = {
-    "name": "connect_new_datasource",
-    "description": (
-        "Connect a new data source to Anton's Local Vault. Call this when the user "
-        "asks a question that requires data from a source that isn't connected yet "
-        "(e.g. email, database, CRM, API). This starts an interactive connection flow "
-        "where the user enters their credentials.\n\n"
-        "Pass the datasource type/name (e.g. 'gmail', 'postgres', 'salesforce', 'hubspot'). "
-        "Anton will match it to the right connector and guide the user through setup.\n\n"
-        "Do NOT print any message before calling this tool — it handles the user-facing output."
-    ),
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "engine": {
-                "type": "string",
-                "description": "The datasource type or name (e.g. 'gmail', 'postgres', 'snowflake', 'hubspot')",
-            },
-            "reason": {
-                "type": "string",
-                "description": "Brief explanation of why this datasource is needed",
-            },
-        },
-        "required": ["engine"],
-    },
-}
-
-PUBLISH_TOOL = {
-    "name": "publish_or_preview",
-    "description": (
-        "Call this after generating an HTML dashboard or report in .anton/output/. "
-        "Actions: 'ask' (default) prompts the user to preview/publish/skip interactively. "
-        "'preview' opens the file in the browser immediately. "
-        "'publish' publishes to the web immediately. "
-        "Use 'preview' or 'publish' when the user has already stated their intent. "
-        "Use 'ask' after generating a new dashboard to let the user choose."
-    ),
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "file_path": {
-                "type": "string",
-                "description": "Path to the HTML file (e.g. .anton/output/dashboard.html)",
-            },
-            "title": {
-                "type": "string",
-                "description": "Short title describing the dashboard (e.g. 'BTC & Macro Dashboard')",
-            },
-            "action": {
-                "type": "string",
-                "enum": ["ask", "preview", "publish"],
-                "description": "What to do: 'ask' prompts user, 'preview' opens locally, 'publish' publishes to web",
-            },
-        },
-        "required": ["file_path"],
-    },
-}
-
-
-SCRATCHPAD_TOOL = {
-    "name": "scratchpad",
-    "description": (
-        "Run Python code in a persistent scratchpad. Use this whenever you need to "
-        "count characters, do math, parse data, transform text, or any task that "
-        "benefits from precise computation rather than guessing. Variables, imports, "
-        "and data persist across cells — like a notebook you drive programmatically.\n\n"
-        "Actions:\n"
-        "- exec: Run code in the scratchpad (creates it if needed)\n"
-        "- view: See all cells and their outputs\n"
-        "- reset: Restart the process, clearing all state (installed packages survive)\n"
-        "- remove: Kill the scratchpad and delete its environment\n"
-        "- dump: Show a clean notebook-style summary of cells (code + truncated output)\n"
-        "- install: Install Python packages into the scratchpad's environment. "
-        "Packages persist across resets.\n\n"
-        "Use print() to produce output. Host Python packages are available by default. "
-        "Include a 'packages' array on exec calls for any libraries your code needs — "
-        "they'll be auto-installed before the cell runs (already-installed ones are skipped).\n"
-        "get_llm() returns a pre-configured LLM client (sync) — call "
-        "llm.complete(system=..., messages=[...]) for AI-powered computation.\n"
-        "llm.generate_object(MyModel, system=..., messages=[...]) extracts structured "
-        "data into Pydantic models. Supports single models and list[Model].\n"
-        "agentic_loop(system=..., user_message=..., tools=[...], handle_tool=fn) "
-        "runs a tool-call loop where the LLM reasons and calls your tools iteratively. "
-        "handle_tool(name, inputs) -> str is a plain sync function.\n"
-        "sample(var) inspects any variable with type-aware formatting — DataFrames get "
-        "shape/dtypes/head, dicts get keys/values, lists get length/items. "
-        "Defaults to 'preview' mode (compact); use sample(var, mode='full') for complete dump.\n"
-        "All .anton/.env secrets are available as environment variables (os.environ).\n\n"
-        "IMPORTANT: Cells have an inactivity timeout of 30 seconds — if a cell produces "
-        "no output and no progress() calls for 30s, it is killed and all state is lost. "
-        "For long-running code (API calls, data extraction, heavy computation), call "
-        "progress(message) periodically to signal work is ongoing and reset the timer. "
-        "The total timeout scales from your estimated_execution_time_seconds "
-        "(roughly 2x the estimate). You MUST provide estimated_execution_time_seconds "
-        "for every exec call. For very long operations, provide a realistic estimate "
-        "and use progress() to keep the cell alive."
-    ),
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "action": {"type": "string", "enum": ["exec", "view", "reset", "remove", "dump", "install"]},
-            "name": {"type": "string", "description": "Scratchpad name"},
-            "code": {
-                "type": "string",
-                "description": "Python code (exec only). Use print() for output.",
-            },
-            "packages": {
-                "type": "array",
-                "items": {"type": "string"},
-                "description": "Package names needed by this cell (exec or install). "
-                "Listed after code so you know exactly what to include. "
-                "Already-installed packages are skipped automatically.",
-            },
-            "one_line_description": {
-                "type": "string",
-                "description": "Brief description of what this cell does (e.g. 'Scrape listing prices'). Required for exec.",
-            },
-            "estimated_execution_time_seconds": {
-                "type": "integer",
-                "description": "Estimated execution time in seconds. Drives the total timeout (roughly 2x estimate). Use progress() for long cells.",
-            },
-        },
-        "required": ["action", "name"],
-    },
-}
-
-async def handle_recall(session: ChatSession, tc_input: dict) -> str:
-    """Process a recall tool call — search episodic memory."""
-    if session._episodic is None or not session._episodic.enabled:
-        return "Episodic memory is not available."
-
-    query = tc_input.get("query", "")
-    if not query:
-        return "No query provided."
-
-    kwargs: dict = {}
-    if "max_results" in tc_input:
-        kwargs["max_results"] = int(tc_input["max_results"])
-    if "days_back" in tc_input:
-        kwargs["days_back"] = int(tc_input["days_back"])
-
-    return session._episodic.recall_formatted(query, **kwargs)
-
-
-async def handle_memorize(session: ChatSession, tc_input: dict) -> str:
-    """Process a memorize tool call and return a result string.
-
-    Encoding is fire-and-forget so it never blocks scratchpad execution.
-    """
-    import asyncio
-
-    if session._cortex is None:
-        return "Memory system not available."
-
-    if session._cortex.mode == "off":
-        return "Memory encoding is disabled. Change memory mode via /setup to enable."
-
-    from anton.memory.hippocampus import Engram
-
-    raw_entries = tc_input.get("entries", [])
-    if not raw_entries:
-        return "No entries provided."
-
-    engrams: list[Engram] = []
-    for entry in raw_entries:
-        if not isinstance(entry, dict) or "text" not in entry:
-            continue
-
-        kind = entry.get("kind", "lesson")
-        if kind not in ("always", "never", "when", "lesson", "profile"):
-            kind = "lesson"
-
-        scope = entry.get("scope", "project")
-        if scope not in ("global", "project"):
-            scope = "project"
-
-        # User-sourced memories (via explicit tool call) get high confidence
-        engrams.append(Engram(
-            text=entry["text"],
-            kind=kind,
-            scope=scope,
-            confidence="high",
-            topic=entry.get("topic", ""),
-            source="user",
-        ))
-
-    if not engrams:
-        return "No valid entries provided."
-
-    # Always encode immediately via fire-and-forget — the LLM explicitly
-    # chose to memorize these, so we never interrupt the user mid-turn
-    # with confirmation prompts.  Confirmations are reserved for the
-    # post-turn consolidator (lessons extracted from scratchpad sessions).
-    async def _encode_bg(cortex, entries):
-        try:
-            await cortex.encode(entries)
-        except Exception:
-            pass  # Best-effort; don't disrupt the conversation
-
-    asyncio.create_task(_encode_bg(session._cortex, engrams))
-
-    descriptions = [f"Encoded {e.kind}: {e.text}" for e in engrams]
-    return "Memory updated: " + "; ".join(descriptions)
-
-
-async def prepare_scratchpad_exec(session: ChatSession, tc_input: dict):
-    """Validate and prepare a scratchpad exec call.
-
-    Returns (pad, code, description, estimated_time, estimated_seconds) or
-    a str error message if validation fails.
-    """
-    name = tc_input.get("name", "")
-    code = tc_input.get("code", "")
-    if not code or not code.strip():
-        return "No code provided."
-
-    pad = await session._scratchpads.get_or_create(name)
-
-    # Auto-install packages before running the cell
-    packages = tc_input.get("packages", [])
-    if packages:
-        install_result = await pad.install_packages(packages)
-        if "Install failed" in install_result or "timed out" in install_result:
-            return install_result
-
-    description = tc_input.get("one_line_description", "")
-    estimated_seconds = tc_input.get("estimated_execution_time_seconds", 0)
-    if isinstance(estimated_seconds, str):
-        try:
-            estimated_seconds = int(estimated_seconds)
-        except ValueError:
-            estimated_seconds = 0
-
-    estimated_time = f"{estimated_seconds}s" if estimated_seconds > 0 else ""
-    return pad, code, description, estimated_time, estimated_seconds
-
-
-def format_cell_result(cell) -> str:
-    """Format a Cell into a tool result string.
-
-    Every section is labeled so the LLM can tell what came from where:
-    [output] — print() / stdout from the cell code
-    [logs]   — library logging (httpx, urllib3, etc.) captured at INFO+
-    [stderr] — warnings and stderr writes
-    [error]  — Python traceback if the cell raised an exception
-    """
-    parts: list[str] = []
-    if cell.stdout:
-        stdout = cell.stdout
-        if len(stdout) > 10_000:
-            stdout = stdout[:10_000] + f"\n\n... (truncated, {len(stdout)} chars total)"
-        parts.append(f"[output]\n{stdout}")
-    if cell.logs if hasattr(cell, "logs") else False:
-        logs = cell.logs.strip()
-        if len(logs) > 3_000:
-            logs = logs[:3_000] + "\n... (logs truncated)"
-        parts.append(f"[logs]\n{logs}")
-    if cell.stderr:
-        parts.append(f"[stderr]\n{cell.stderr}")
-    if cell.error:
-        parts.append(f"[error]\n{cell.error}")
-    if not parts:
-        return "Code executed successfully (no output)."
-    return "\n".join(parts)
-
-
-async def handle_scratchpad(session: ChatSession, tc_input: dict) -> str:
-    """Dispatch a scratchpad tool call by action."""
-    action = tc_input.get("action", "")
-    name = tc_input.get("name", "")
-
-    if not name:
-        return "Scratchpad name is required."
-
-    if action == "exec":
-        result = await prepare_scratchpad_exec(session, tc_input)
-        if isinstance(result, str):
-            return result
-        pad, code, description, estimated_time, estimated_seconds = result
-
-        cell = await pad.execute(
-            code,
-            description=description,
-            estimated_time=estimated_time,
-            estimated_seconds=estimated_seconds,
-        )
-        return format_cell_result(cell)
-
-    elif action == "view":
-        pad = session._scratchpads._pads.get(name)
-        if pad is None:
-            return f"No scratchpad named '{name}'."
-        return pad.view()
-
-    elif action == "reset":
-        pad = session._scratchpads._pads.get(name)
-        if pad is None:
-            return f"No scratchpad named '{name}'."
-        await pad.reset()
-        return f"Scratchpad '{name}' reset. All state cleared."
-
-    elif action == "remove":
-        return await session._scratchpads.remove(name)
-
-    elif action == "dump":
-        pad = session._scratchpads._pads.get(name)
-        if pad is None:
-            return f"No scratchpad named '{name}'."
-        return pad.render_notebook()
-
-    elif action == "install":
-        packages = tc_input.get("packages", [])
-        if not packages:
-            return "No packages specified."
-        pad = await session._scratchpads.get_or_create(name)
-        return await pad.install_packages(packages)
-
-    else:
-        return f"Unknown scratchpad action: {action}"
+    from anton.core.session import ChatSession
 
 
 async def handle_connect_datasource(session: ChatSession, tc_input: dict) -> str:
     """Handle connect_new_datasource tool call — interactive connection flow."""
     engine = tc_input.get("engine", "")
-    reason = tc_input.get("reason", "")
     if not engine:
         return "Engine name is required."
 
+    raw_known = tc_input.get("known_variables") or {}
+    known_variables: dict[str, str] = (
+        {str(k): str(v) for k, v in raw_known.items() if v is not None and v != ""}
+        if isinstance(raw_known, dict) else {}
+    )
+
     console = session._console
     if console is None:
         return "Cannot connect datasource — no console available."
 
+    # ── Telemetry: connection attempt ────────────────────────────────
+    _settings = getattr(session, "_settings", None)
+    if _settings is None:
+        try:
+            from anton.config.settings import AntonSettings
+            _settings = AntonSettings()
+        except Exception:
+            _settings = None
+
+    if _settings:
+        from anton.analytics import send_event
+        send_event(_settings, "ds_connect_attempt", engine=engine)
+
     console.print()
     console.print(
         f"[anton.prompt]anton>[/] I can help with that \u2014 let's connect [bold]{engine}[/] to Anton."
     )
 
     from anton.commands.datasource import handle_connect_datasource
-    from anton.utils.prompt import prompt_or_cancel
-    from anton.data_vault import DataVault
 
-    # Check which connections exist before
-    vault = DataVault()
+    from anton.core.datasources.data_vault import LocalDataVault
+    vault = session._data_vault or LocalDataVault()
     before = {f"{c['engine']}-{c['name']}" for c in vault.list_connections()}
 
+    # Clear any stale status from a previous run
+    setattr(session, "_pending_connect_redirect", None)
+    setattr(session, "_pending_connect_status", None)
+
     await handle_connect_datasource(
         console,
         session._scratchpads,
         session,
         prefill=engine,
+        known_variables=known_variables or None,
+        from_tool_call=True,
+        vault=vault,
     )
 
     # Check if a new connection was actually added
@@ -496,35 +69,121 @@ async def handle_connect_datasource(session: ChatSession, tc_input: dict) -> str
 
     if new_connections:
         slug = next(iter(new_connections))
+        # ── Telemetry: connection succeeded ──────────────────────────
+        if _settings:
+            send_event(_settings, "ds_connect_success", engine=engine)
         return (
             f"Successfully connected '{slug}'. The datasource is now available. "
             f"Continue helping the user with their original request using this data source."
         )
-    else:
-        # User cancelled or connection failed — show briefly with spinner
-        # so user knows the agent is picking back up
-        from rich.live import Live
-        from rich.spinner import Spinner
-        from rich.text import Text
-        import asyncio
 
-        console.print()
-        console.print("[anton.muted]  No worries, let's continue where we left off.[/]")
-        with Live(
-            Spinner("dots", text=Text("", style="anton.muted"), style="anton.cyan"),
-            console=console,
-            refresh_per_second=10,
-            transient=True,
-        ):
-            await asyncio.sleep(1.5)
-        console.print()
+    # Did the flow record a mid-flow redirect? Read it from the session
+    # attribute stashed by _build_redirect_message. We CANNOT append to
+    # session._history from within the handler — we're between the
+    # tool_use and tool_result blocks and doing so breaks the Anthropic
+    # API invariant that every tool_use must be immediately followed by
+    # its tool_result.
+    redirect_text = getattr(session, "_pending_connect_redirect", None)
+    if redirect_text:
+        setattr(session, "_pending_connect_redirect", None)
+        return redirect_text
+
+    # No new connection was saved. Distinguish *why* — the LLM should
+    # not be told "user pressed Escape" when really the test failed.
+    status = getattr(session, "_pending_connect_status", None)
+    setattr(session, "_pending_connect_status", None)
+
+    from rich.live import Live
+    from rich.spinner import Spinner
+    from rich.text import Text
+    import asyncio
+
+    console.print()
+    console.print("[anton.muted]  No worries, let's continue where we left off.[/]")
+    with Live(
+        Spinner("dots", text=Text("", style="anton.muted"), style="anton.cyan"),
+        console=console,
+        refresh_per_second=10,
+        transient=True,
+    ):
+        await asyncio.sleep(1.5)
+    console.print()
+
+    if status == "test_failed":
+        # ── Telemetry: connection failed ─────────────────────────────
+        if _settings:
+            from anton.analytics import send_event
+            send_event(_settings, "ds_connect_failed", engine=engine)
         return (
-            f"CANCELLED: The user pressed Escape and cancelled the '{engine}' connection. "
-            f"STOP — do NOT call connect_new_datasource again. Do NOT retry. "
-            f"Acknowledge the cancellation briefly and ask the user what they'd like to do instead. "
-            f"Respond with TEXT ONLY — no tool calls."
+            f"CONNECTION TEST FAILED: The connection test for '{engine}' did not "
+            f"succeed and the user declined to re-enter credentials. Nothing was "
+            f"saved.\n\n"
+            f"You have exactly TWO mutually exclusive options — pick ONE, do NOT "
+            f"mix them:\n\n"
+            f"OPTION A — Retry silently (only if you suspect a transient issue "
+            f"like a network glitch or first-connection cold start):\n"
+            f"  Emit ZERO text in your response. Output ONLY a tool_use block "
+            f"calling connect_new_datasource again with the same known_variables. "
+            f"The user will only see the final result — clean and uncluttered.\n\n"
+            f"OPTION B — Give up and troubleshoot (if you believe the failure is "
+            f"real — bad credentials, wrong host, firewall, etc.):\n"
+            f"  Respond with TEXT ONLY, NO tool calls. Briefly explain what "
+            f"likely went wrong and ask the user what to do.\n\n"
+            f"CRITICAL: Mixing text + a retry tool call in the same response "
+            f"produces a confusing two-message stack for the user (failure text "
+            f"followed by success text). Pick A or B, never both."
         )
 
+    # Default: user cancelled (pressed Escape) at some point
+    return (
+        f"CANCELLED: The user cancelled the '{engine}' connection setup before "
+        f"it completed. Ask the user what they'd like to do instead. "
+        f"Do NOT immediately call connect_new_datasource again unless they "
+        f"explicitly ask for it. Respond with TEXT ONLY — no tool calls."
+    )
+
+
+CONNECT_DATASOURCE_TOOL = ToolDef(
+    name = "connect_new_datasource",
+    description = (
+        "Connect a new data source to Anton's Local Vault. Call this when the user "
+        "asks a question that requires data from a source that isn't connected yet "
+        "(e.g. email, database, CRM, API). This starts an interactive connection flow "
+        "where the user enters their credentials.\n\n"
+        "Pass the datasource type/name (e.g. 'gmail', 'postgres', 'salesforce', 'hubspot'). "
+        "Anton will match it to the right connector and guide the user through setup.\n\n"
+        "If the user has ALREADY mentioned credential values in the conversation "
+        "(e.g. 'connect to dynamodb, my access key is AKIA... and region is us-east-1'), "
+        "pass them as `known_variables` so the user is not asked again.\n\n"
+        "Do NOT print any message before calling this tool — it handles the user-facing output."
+    ),
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "engine": {
+                "type": "string",
+                "description": "The datasource type or name (e.g. 'gmail', 'postgres', 'snowflake', 'hubspot')",
+            },
+            "reason": {
+                "type": "string",
+                "description": "Brief explanation of why this datasource is needed",
+            },
+            "known_variables": {
+                "type": "object",
+                "description": (
+                    "Pre-extracted credential field values from the conversation. "
+                    "Use snake_case field names (e.g. {\"host\": \"db.example.com\", "
+                    "\"port\": \"5432\", \"user\": \"admin\"}). Only pass fields the "
+                    "user actually mentioned — never invent values."
+                ),
+                "additionalProperties": {"type": "string"},
+            },
+        },
+        "required": ["engine"],
+    },
+    handler = handle_connect_datasource,
+)
+
 
 async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str:
     """Interactive preview/publish flow after dashboard creation."""
@@ -568,44 +227,127 @@ async def handle_publish_or_preview(session: ChatSession, tc_input: dict) -> str
             "API key setup flow."
         )
 
+    import json as _json
+
     from rich.live import Live
     from rich.spinner import Spinner
 
-    with Live(Spinner("dots", text="  Publishing...", style="anton.cyan"), console=console, transient=True):
+    # Check if this file was previously published — reuse report_id to
+    # update instead of creating a new report every time.
+    output_dir = file_path.parent
+    published_json = output_dir / ".published.json"
+    published_map: dict = {}
+    try:
+        if published_json.is_file():
+            published_map = _json.loads(published_json.read_text())
+    except Exception:
+        pass
+
+    file_key = file_path.name
+    prev = published_map.get(file_key)
+    report_id = prev.get("report_id") if isinstance(prev, dict) else None
+
+    action_text = "  Updating..." if report_id else "  Publishing..."
+    with Live(Spinner("dots", text=action_text, style="anton.cyan"), console=console, transient=True):
         try:
             result = publish(
                 file_path,
                 api_key=settings.minds_api_key,
+                report_id=report_id,
                 publish_url=settings.publish_url,
                 ssl_verify=settings.minds_ssl_verify,
             )
         except Exception as e:
-            console.print(f"  [anton.error]Publish failed: {e}[/]")
-            console.print()
-            return f"PUBLISH FAILED: {e}"
+            if report_id:
+                # The report may have been deleted server-side — retry
+                # without report_id to create a fresh one.
+                try:
+                    result = publish(
+                        file_path,
+                        api_key=settings.minds_api_key,
+                        publish_url=settings.publish_url,
+                        ssl_verify=settings.minds_ssl_verify,
+                    )
+                except Exception as e2:
+                    console.print(f"  [anton.error]Publish failed: {e2}[/]")
+                    console.print()
+                    return f"PUBLISH FAILED: {e2}"
+            else:
+                console.print(f"  [anton.error]Publish failed: {e}[/]")
+                console.print()
+                return f"PUBLISH FAILED: {e}"
 
     view_url = result.get("view_url", "")
-    console.print(f"  [anton.success]Published![/]")
+    returned_report_id = result.get("report_id", "")
+    version = result.get("version", 1)
+    unchanged = result.get("unchanged", False)
+
+    if unchanged:
+        console.print(f"  [anton.muted]Already up to date (v{version})[/]")
+    elif report_id:
+        console.print(f"  [anton.success]Updated! (v{version})[/]")
+    else:
+        console.print(f"  [anton.success]Published![/]")
     console.print(f"  [link={view_url}]{view_url}[/link]")
     console.print()
 
+    # Persist the mapping so future publishes of the same file update
+    # instead of creating a new report.
+    if returned_report_id:
+        published_map[file_key] = {
+            "report_id": returned_report_id,
+            "url": view_url,
+            "last_md5": result.get("md5", ""),
+        }
+        try:
+            published_json.write_text(_json.dumps(published_map, indent=2))
+        except Exception:
+            pass
+
     if view_url:
         webbrowser.open(view_url)
 
-    return f"Published successfully!\nView URL: {view_url}"
-
-
-async def dispatch_tool(session: ChatSession, tool_name: str, tc_input: dict) -> str:
-    """Dispatch a tool call by name. Returns result text."""
-    if tool_name == "memorize":
-        return await handle_memorize(session, tc_input)
-    elif tool_name == "scratchpad":
-        return await handle_scratchpad(session, tc_input)
-    elif tool_name == "recall":
-        return await handle_recall(session, tc_input)
-    elif tool_name == "connect_new_datasource":
-        return await handle_connect_datasource(session, tc_input)
-    elif tool_name == "publish_or_preview":
-        return await handle_publish_or_preview(session, tc_input)
-    else:
-        return f"Unknown tool: {tool_name}"
+    status = "Updated" if report_id else "Published"
+    return f"{status} successfully!\nView URL: {view_url}"
+
+
+PUBLISH_TOOL = ToolDef(
+    name = "publish_or_preview",
+    description = (
+        "Call this after generating an HTML dashboard or report in .anton/output/. "
+        "Actions: 'ask' (default) prompts the user to preview/publish/skip interactively. "
+        "'preview' opens the file in the browser immediately. "
+        "'publish' publishes to the web immediately. "
+        "Use 'preview' or 'publish' when the user has already stated their intent. "
+        "Use 'ask' after generating a new dashboard to let the user choose."
+    ),
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_path": {
+                "type": "string",
+                "description": "Path to the HTML file (e.g. .anton/output/dashboard.html)",
+            },
+            "title": {
+                "type": "string",
+                "description": "Short title describing the dashboard (e.g. 'BTC & Macro Dashboard')",
+            },
+            "action": {
+                "type": "string",
+                "enum": ["ask", "preview", "publish"],
+                "description": "What to do: 'ask' prompts user, 'preview' opens locally, 'publish' publishes to web",
+            },
+        },
+        "required": ["file_path"],
+    },
+    handler = handle_publish_or_preview,
+    prompt = (
+        "CONTENT SHARING POLICY:\n"
+        "- Publishing dashboards or reports to the web is done ONLY via the `publish_or_preview` tool. \n"
+        "- Do NOT upload, post, or share generated files (HTML, data, images) to external hosting \n"
+        "- services (paste sites, gists, CDNs, file hosts) via scratchpad code — unless the user \n"
+        "- explicitly names the service and confirms. Reading from public APIs and writing to the \n"
+        "- user's connected datasources (databases, CRMs, etc.) is fine — this rule only applies to \n"
+        "- sharing generated output with the public internet."
+    ),
+)
diff --git a/anton/utils/datasources.py b/anton/utils/datasources.py
index 7dd7943d..c027c99e 100644
--- a/anton/utils/datasources.py
+++ b/anton/utils/datasources.py
@@ -5,11 +5,11 @@
 import yaml
 from typing import TYPE_CHECKING
 
-from anton.data_vault import DataVault, _slug_env_prefix
-from anton.datasource_registry import DatasourceRegistry, _YAML_BLOCK_RE
+from anton.core.datasources.data_vault import DataVault, LocalDataVault, _slug_env_prefix
+from anton.core.datasources.datasource_registry import DatasourceRegistry, _YAML_BLOCK_RE
 
 if TYPE_CHECKING:
-    from anton.datasource_registry import DatasourceEngine
+    from anton.core.datasources.datasource_registry import DatasourceEngine
 
 # DS_* var names whose values are known to be secret (passwords, tokens, keys).
 # Populated at startup and after each successful connect.
@@ -105,7 +105,7 @@ def scrub_credentials(text: str) -> str:
     return text
 
 
-def build_datasource_context(active_only: str | None = None) -> str:
+def build_datasource_context(vault: DataVault, active_only: str | None = None) -> str:
     """Build a system-prompt section listing available DS_* env vars by name.
 
     Shows the LLM what data sources are connected and which environment
@@ -114,7 +114,7 @@ def build_datasource_context(active_only: str | None = None) -> str:
     If active_only is set, only the matching slug is included.
     """
     try:
-        vault = DataVault()
+        vault = vault or LocalDataVault()
         conns = vault.list_connections()
     except Exception:
         return ""
@@ -125,7 +125,7 @@ def build_datasource_context(active_only: str | None = None) -> str:
         "Credentials are pre-injected as namespaced DS_<ENGINE_NAME>__<FIELD> "
         "environment variables. Use them directly in scratchpad code "
         "(e.g. DS_POSTGRES_PROD_DB__HOST). "
-        "Never read ~/.anton/data_vault/ files directly.\n"
+        "Never read the data vault files directly.\n"
     )
     for c in conns:
         slug = f"{c['engine']}-{c['name']}"
diff --git a/anton/utils/prompt.py b/anton/utils/prompt.py
index dbb6fa79..14f91bd6 100644
--- a/anton/utils/prompt.py
+++ b/anton/utils/prompt.py
@@ -87,18 +87,18 @@ def _toolbar():
     opts_text = choices_display or ("/".join(choices) if choices else "")
 
     if password:
-        suffix = " (hidden): "
+        suffix = " (hidden):"
     elif opts_text and default:
         suffix = (
             f" <b><ansimagenta>[{opts_text}]</ansimagenta></b>"
-            f" <b><ansicyan>({default})</ansicyan></b>: "
+            f" <b><ansicyan>({default})</ansicyan></b>:"
         )
     elif opts_text:
-        suffix = f" <b><ansimagenta>[{opts_text}]</ansimagenta></b>: "
+        suffix = f" <b><ansimagenta>[{opts_text}]</ansimagenta></b>:"
     elif default:
-        suffix = f" <b><ansicyan>({default})</ansicyan></b>: "
+        suffix = f" <b><ansicyan>({default})</ansicyan></b>:"
     else:
-        suffix = ": "
+        suffix = ":"
 
     pt_session: PromptSession[str] = PromptSession(
         mouse_support=False,
@@ -111,11 +111,12 @@ def _toolbar():
     from anton.channel.theme import get_palette as _get_palette
     _prompt_color = _get_palette().prompt
 
+    space = '\u2009'
     if label.startswith("(anton) "):
         body = label[len("(anton) "):]
-        message = HTML(f"<b><style fg='{_prompt_color}'>(anton)</style></b> {body}{suffix}")
+        message = HTML(f"<b><style fg='{_prompt_color}'>(anton)</style></b> {body}{suffix}{space}")
     else:
-        message = HTML(f"{label}{suffix}")
+        message = HTML(f"{label}{suffix}{space}")
 
     while True:
         _esc = False
diff --git a/pyproject.toml b/pyproject.toml
index d6f4d1e6..ab29c2ea 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -17,6 +17,7 @@ dependencies = [
     "prompt-toolkit>=3.0",
     "packaging>=21.0",
     "pyyaml>=6.0",
+    "dill==0.3.8",
 ]
 
 [project.optional-dependencies]
diff --git a/tests/conftest.py b/tests/conftest.py
index 2c48a014..9fa2287e 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,10 +1,27 @@
 from __future__ import annotations
 
-from unittest.mock import AsyncMock
+from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from anton.llm.provider import LLMResponse, ToolCall, Usage
+from anton.core.llm.provider import LLMResponse, ProviderConnectionInfo, ToolCall, Usage
+
+
+def make_mock_llm() -> AsyncMock:
+    """Return an AsyncMock LLM client with coding_provider configured for sync use.
+
+    ``AsyncMock`` makes all child attributes ``AsyncMock`` too, which means
+    ``coding_provider.export_connection_info()`` would return a coroutine —
+    but ``ChatSession.__init__`` calls it synchronously.  This helper fixes
+    that by explicitly wiring ``coding_provider`` with a plain ``MagicMock``.
+    """
+    mock = AsyncMock()
+    mock.coding_provider = MagicMock()
+    mock.coding_provider.export_connection_info = MagicMock(
+        return_value=ProviderConnectionInfo(provider="anthropic", api_key="test")
+    )
+    mock.coding_model = "claude-sonnet-4-6"
+    return mock
 
 
 @pytest.fixture()
diff --git a/tests/e2e/scenarios/test_error_handling.py b/tests/e2e/scenarios/test_error_handling.py
index 922406ae..731d19f5 100644
--- a/tests/e2e/scenarios/test_error_handling.py
+++ b/tests/e2e/scenarios/test_error_handling.py
@@ -78,6 +78,7 @@ def log_message(self, *_): pass
     assert_not_output(result, "Traceback (most recent call last)")
 
 
+@pytest.mark.stub_only
 def test_large_input_no_crash(cfg, stub, tmp_path):
     stub.queue_text("Got your big message.")
     stub.queue_verification_ok()
diff --git a/tests/test_cerebellum.py b/tests/test_cerebellum.py
new file mode 100644
index 00000000..26894120
--- /dev/null
+++ b/tests/test_cerebellum.py
@@ -0,0 +1,399 @@
+"""Unit tests for `anton.core.memory.cerebellum.Cerebellum`."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from anton.core.backends.base import Cell
+from anton.core.memory.cerebellum import (
+    Cerebellum,
+    CerebellumLesson,
+    _DiffPassResult,
+    _format_cell_for_diff,
+    _LessonDraft,
+)
+from anton.core.memory.hippocampus import Engram
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _cell(
+    code: str = "x = 1",
+    description: str = "",
+    stdout: str = "",
+    stderr: str = "",
+    error: str | None = None,
+) -> Cell:
+    return Cell(
+        code=code,
+        stdout=stdout,
+        stderr=stderr,
+        error=error,
+        description=description,
+    )
+
+
+def _make_llm_returning(*lessons: tuple[str, str]) -> MagicMock:
+    """Build a mock LLMClient whose generate_object returns the given lessons.
+
+    Each lesson is a (text, topic) tuple. Empty argument list means the
+    diff returns no lessons (i.e. the LLM said "nothing to learn here").
+    """
+    drafts = [_LessonDraft(text=text, topic=topic) for text, topic in lessons]
+    result = _DiffPassResult(lessons=drafts)
+    llm = MagicMock()
+    llm.generate_object_code = AsyncMock(return_value=result)
+    return llm
+
+
+def _make_llm_raising(exc: Exception) -> MagicMock:
+    """Build a mock LLMClient whose generate_object raises an exception."""
+    llm = MagicMock()
+    llm.generate_object_code = AsyncMock(side_effect=exc)
+    return llm
+
+
+def _make_cortex() -> MagicMock:
+    """Build a mock Cortex with an awaitable encode() method."""
+    cortex = MagicMock()
+    cortex.encode = AsyncMock(return_value=["encoded ok"])
+    return cortex
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helper functions
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestFormatCellForDiff:
+    def test_basic_cell_renders(self):
+        cell = _cell(
+            code="print(1+1)",
+            description="add two numbers",
+            stdout="2",
+        )
+        out = _format_cell_for_diff(cell, 1)
+        assert "Cell 1" in out
+        assert "add two numbers" in out
+        assert "print(1+1)" in out
+        assert "stdout:" in out
+
+    def test_cell_with_error(self):
+        cell = _cell(
+            code="x = 1/0",
+            description="divide",
+            error="ZeroDivisionError: division by zero",
+        )
+        out = _format_cell_for_diff(cell, 2)
+        assert "ZeroDivisionError" in out
+        assert "Cell 2" in out
+
+    def test_no_description_falls_back(self):
+        cell = _cell(code="x = 1", stdout="")
+        out = _format_cell_for_diff(cell, 1)
+        assert "no description" in out
+
+    def test_truncates_long_code(self):
+        cell = _cell(code="x = 1\n" * 500, description="loop")
+        out = _format_cell_for_diff(cell, 1)
+        assert "[truncated]" in out
+
+    def test_empty_outputs_marker(self):
+        cell = _cell(code="pass", description="pass")
+        out = _format_cell_for_diff(cell, 1)
+        assert "no output produced" in out
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Cheap path: clean cells should never reach the LLM
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestCheapPath:
+    @pytest.mark.asyncio
+    async def test_clean_cell_not_buffered(self):
+        cb = Cerebellum(cortex=_make_cortex(), llm=_make_llm_returning())
+        await cb.on_post_execute(_cell(code="x = 1", stdout="ok"))
+        assert cb.buffered_count == 0
+
+    @pytest.mark.asyncio
+    async def test_clean_cell_with_only_stdout(self):
+        cb = Cerebellum(cortex=_make_cortex(), llm=_make_llm_returning())
+        await cb.on_post_execute(_cell(stdout="2", description="add"))
+        assert cb.buffered_count == 0
+
+    @pytest.mark.asyncio
+    async def test_clean_cell_with_no_output_at_all(self):
+        cb = Cerebellum(cortex=_make_cortex(), llm=_make_llm_returning())
+        await cb.on_post_execute(_cell(code="pass"))
+        assert cb.buffered_count == 0
+
+    @pytest.mark.asyncio
+    async def test_flush_with_no_cells_returns_empty(self):
+        llm = _make_llm_returning()
+        cb = Cerebellum(cortex=_make_cortex(), llm=llm)
+        result = await cb.flush()
+        assert result == []
+        # No LLM call when nothing was buffered
+        llm.generate_object_code.assert_not_called()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Error path: buffer + diff + encode
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestErrorPath:
+    @pytest.mark.asyncio
+    async def test_error_cell_is_buffered(self):
+        cb = Cerebellum(cortex=_make_cortex(), llm=_make_llm_returning())
+        await cb.on_post_execute(
+            _cell(code="x = 1/0", error="ZeroDivisionError")
+        )
+        assert cb.buffered_count == 1
+
+    @pytest.mark.asyncio
+    async def test_stderr_only_cell_is_buffered(self):
+        cb = Cerebellum(cortex=_make_cortex(), llm=_make_llm_returning())
+        # No `error` field but a non-empty stderr — counts as warning
+        await cb.on_post_execute(
+            _cell(code="import x", stderr="DeprecationWarning: ...")
+        )
+        assert cb.buffered_count == 1
+
+    @pytest.mark.asyncio
+    async def test_flush_calls_generate_object_with_buffered_cells(self):
+        llm = _make_llm_returning()
+        cb = Cerebellum(cortex=_make_cortex(), llm=llm)
+        await cb.on_post_execute(
+            _cell(
+                code="x = 1/0",
+                description="divide",
+                error="ZeroDivisionError: division by zero",
+            )
+        )
+        await cb.flush()
+        llm.generate_object_code.assert_called_once()
+        # generate_object_code was called with the _DiffPassResult Pydantic model
+        call_args = llm.generate_object_code.call_args
+        assert call_args.args[0] is _DiffPassResult
+        # The prompt should mention the cell's intent
+        user_msg = call_args.kwargs["messages"][0]["content"]
+        assert "divide" in user_msg
+        assert "ZeroDivisionError" in user_msg
+
+    @pytest.mark.asyncio
+    async def test_flush_clears_buffer(self):
+        cb = Cerebellum(
+            cortex=_make_cortex(),
+            llm=_make_llm_returning(),
+        )
+        await cb.on_post_execute(_cell(error="boom"))
+        assert cb.buffered_count == 1
+        await cb.flush()
+        assert cb.buffered_count == 0
+
+    @pytest.mark.asyncio
+    async def test_extracted_lesson_is_encoded(self):
+        cortex = _make_cortex()
+        cb = Cerebellum(
+            cortex=cortex,
+            llm=_make_llm_returning(
+                ("Use low_memory=False with mixed-dtype CSVs.", "scratchpad")
+            ),
+        )
+        await cb.on_post_execute(_cell(error="dtype error"))
+        result = await cb.flush()
+
+        assert len(result) == 1
+        assert isinstance(result[0], CerebellumLesson)
+        assert "low_memory" in result[0].text
+
+        # Cortex.encode was called with an Engram
+        cortex.encode.assert_awaited_once()
+        engrams = cortex.encode.call_args.args[0]
+        assert len(engrams) == 1
+        assert isinstance(engrams[0], Engram)
+        assert engrams[0].kind == "lesson"
+        assert engrams[0].topic == "scratchpad"
+        assert engrams[0].source == "consolidation"
+        assert engrams[0].scope == "project"
+        assert "low_memory" in engrams[0].text
+
+    @pytest.mark.asyncio
+    async def test_multiple_lessons_encoded_in_one_call(self):
+        cortex = _make_cortex()
+        cb = Cerebellum(
+            cortex=cortex,
+            llm=_make_llm_returning(
+                ("lesson one", "scratchpad"),
+                ("lesson two", "scratchpad"),
+                ("lesson three", "scratchpad"),
+            ),
+        )
+        await cb.on_post_execute(_cell(error="boom"))
+        await cb.flush()
+
+        cortex.encode.assert_awaited_once()
+        engrams = cortex.encode.call_args.args[0]
+        assert len(engrams) == 3
+
+    @pytest.mark.asyncio
+    async def test_max_lessons_caps_extraction(self):
+        cortex = _make_cortex()
+        cb = Cerebellum(
+            cortex=cortex,
+            llm=_make_llm_returning(
+                *((f"lesson {i}", "scratchpad") for i in range(10))
+            ),
+            max_lessons_per_flush=2,
+        )
+        await cb.on_post_execute(_cell(error="boom"))
+        result = await cb.flush()
+        assert len(result) == 2
+
+    @pytest.mark.asyncio
+    async def test_empty_lessons_list_does_not_encode(self):
+        cortex = _make_cortex()
+        cb = Cerebellum(cortex=cortex, llm=_make_llm_returning())
+        await cb.on_post_execute(_cell(error="boom"))
+        result = await cb.flush()
+        assert result == []
+        cortex.encode.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_skips_lessons_with_blank_text(self):
+        cortex = _make_cortex()
+        cb = Cerebellum(
+            cortex=cortex,
+            llm=_make_llm_returning(
+                ("real lesson", "scratchpad"),
+                ("   ", "scratchpad"),  # blank — should be skipped
+            ),
+        )
+        await cb.on_post_execute(_cell(error="boom"))
+        result = await cb.flush()
+        assert len(result) == 1
+        assert result[0].text == "real lesson"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Robustness — bad LLM responses, missing infra
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestRobustness:
+    @pytest.mark.asyncio
+    async def test_llm_network_exception_does_not_crash(self):
+        """Provider/network failure during generate_object → safe no-op."""
+        cortex = _make_cortex()
+        cb = Cerebellum(
+            cortex=cortex,
+            llm=_make_llm_raising(RuntimeError("network down")),
+        )
+        await cb.on_post_execute(_cell(error="boom"))
+        # Must not raise
+        result = await cb.flush()
+        assert result == []
+        cortex.encode.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_llm_validation_error_does_not_crash(self):
+        """If the LLM somehow violates the schema, Pydantic raises and
+        flush() swallows it cleanly. This shouldn't happen in practice
+        because tool_choice is forced, but the safety net is in place."""
+        from pydantic import ValidationError as _PydValidationError
+
+        cortex = _make_cortex()
+        # Construct a real Pydantic validation error to feed in
+        try:
+            _DiffPassResult.model_validate({"lessons": "not a list"})
+        except _PydValidationError as exc:
+            llm = _make_llm_raising(exc)
+
+        cb = Cerebellum(cortex=cortex, llm=llm)
+        await cb.on_post_execute(_cell(error="boom"))
+        result = await cb.flush()
+        assert result == []
+        cortex.encode.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_value_error_from_no_tool_call_does_not_crash(self):
+        """If generate_object raises ValueError because the LLM returned
+        no tool call, flush() swallows it cleanly."""
+        cortex = _make_cortex()
+        cb = Cerebellum(
+            cortex=cortex,
+            llm=_make_llm_raising(ValueError("LLM did not return a tool call")),
+        )
+        await cb.on_post_execute(_cell(error="boom"))
+        result = await cb.flush()
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_cortex_encode_exception_does_not_crash(self):
+        """If cortex.encode itself fails, the cerebellum logs and moves on.
+        The lesson was still extracted (returned to the caller) — only
+        the persistence step failed."""
+        cortex = MagicMock()
+        cortex.encode = AsyncMock(side_effect=RuntimeError("disk full"))
+        cb = Cerebellum(
+            cortex=cortex,
+            llm=_make_llm_returning(("be careful", "scratchpad")),
+        )
+        await cb.on_post_execute(_cell(error="boom"))
+        # Must not raise
+        result = await cb.flush()
+        assert len(result) == 1
+
+    @pytest.mark.asyncio
+    async def test_no_cortex_no_encode(self):
+        cb = Cerebellum(cortex=None, llm=_make_llm_returning())
+        await cb.on_post_execute(_cell(error="boom"))
+        result = await cb.flush()
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_no_llm_no_diff(self):
+        cb = Cerebellum(cortex=_make_cortex(), llm=None)
+        await cb.on_post_execute(_cell(error="boom"))
+        result = await cb.flush()
+        assert result == []
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Reset / lifecycle
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestReset:
+    @pytest.mark.asyncio
+    async def test_reset_clears_buffer_without_encoding(self):
+        cortex = _make_cortex()
+        llm = _make_llm_returning(("x", "scratchpad"))
+        cb = Cerebellum(cortex=cortex, llm=llm)
+        await cb.on_post_execute(_cell(error="boom"))
+        await cb.on_post_execute(_cell(error="boom2"))
+        assert cb.buffered_count == 2
+
+        cb.reset()
+        assert cb.buffered_count == 0
+
+        # After reset, no LLM call happens because buffer is empty
+        await cb.flush()
+        llm.generate_object_code.assert_not_called()
+        cortex.encode.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_pre_execute_increments_counter(self):
+        cb = Cerebellum(cortex=_make_cortex(), llm=_make_llm_returning())
+        await cb.on_pre_execute(_cell(code="x = 1", description="set x"))
+        await cb.on_pre_execute(_cell(code="y = 2", description="set y"))
+        # Internal counter — we don't expose it as a property but reset clears it
+        cb.reset()
+        # No exception means reset worked
diff --git a/tests/test_cerebellum_e2e.py b/tests/test_cerebellum_e2e.py
new file mode 100644
index 00000000..2a4023a8
--- /dev/null
+++ b/tests/test_cerebellum_e2e.py
@@ -0,0 +1,246 @@
+"""End-to-end test of the cerebellum loop.
+
+Verifies the full path with no real LLM and no real subprocess:
+
+1. Build a fake session-like object with a real Cerebellum wired into
+   `_scratchpad_observers`
+2. Drive `handle_scratchpad` with an exec call where the (mocked) pad
+   returns an errored Cell
+3. Confirm the cerebellum's pre+post hooks fired via the dispatcher
+4. Confirm the errored cell was buffered (clean cells would have been
+   skipped via the cheap path)
+5. Call cerebellum.flush() — verify the diff LLM was invoked, the
+   lesson was extracted, and cortex.encode() received an Engram
+6. The end-to-end loop runs without touching the runtime layer at all
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from anton.core.backends.base import Cell
+from anton.core.memory.cerebellum import (
+    Cerebellum,
+    _DiffPassResult,
+    _LessonDraft,
+)
+from anton.core.memory.hippocampus import Engram
+from anton.core.tools.tool_handlers import handle_scratchpad
+
+
+def _build_session_with_cerebellum(
+    *,
+    pad_returns: Cell,
+    lessons: list[tuple[str, str]] | None = None,
+) -> tuple[MagicMock, MagicMock, MagicMock, Cerebellum]:
+    """Construct a fake session with a real Cerebellum wired in.
+
+    Returns (session, mock_cortex, mock_llm, cerebellum) so the test
+    can poke at any of them after the dispatch.
+
+    `lessons` is a list of (text, topic) tuples that the mocked
+    `generate_object` call will return as a `_DiffPassResult`. Empty
+    list means the LLM extracted no lessons from the buffered cells.
+    """
+    cortex = MagicMock()
+    cortex.encode = AsyncMock(return_value=["encoded"])
+
+    drafts = [
+        _LessonDraft(text=text, topic=topic) for text, topic in (lessons or [])
+    ]
+    llm = MagicMock()
+    llm.generate_object_code = AsyncMock(
+        return_value=_DiffPassResult(lessons=drafts)
+    )
+
+    cerebellum = Cerebellum(cortex=cortex, llm=llm)
+
+    session = MagicMock()
+    session._scratchpad_observers = [cerebellum]
+    session._cerebellum = cerebellum
+    session._cortex = cortex
+    session._llm = llm
+    session._record_cell_explainability = MagicMock()
+
+    pad = MagicMock()
+    pad.execute = AsyncMock(return_value=pad_returns)
+    session._scratchpads = MagicMock()
+    session._scratchpads.get_or_create = AsyncMock(return_value=pad)
+
+    return session, cortex, llm, cerebellum
+
+
+@pytest.mark.asyncio
+async def test_full_cerebellum_loop_with_errored_cell():
+    """Errored cell → dispatcher fires hooks → cerebellum buffers → flush
+    runs diff → lesson encoded via cortex."""
+    errored_cell = Cell(
+        code="import pandas as pd\ndf = pd.read_csv('mixed.csv')",
+        stdout="",
+        stderr="",
+        error=(
+            "DtypeWarning: Columns have mixed types. "
+            "Specify dtype option or set low_memory=False."
+        ),
+        description="Load mixed.csv into a DataFrame",
+    )
+    session, cortex, llm, cerebellum = _build_session_with_cerebellum(
+        pad_returns=errored_cell,
+        lessons=[
+            (
+                "When loading CSVs with mixed dtypes, pass low_memory=False to pd.read_csv.",
+                "scratchpad",
+            )
+        ],
+    )
+
+    # Step 1: dispatch the exec call — this exercises the dispatcher's
+    # observer firing path end-to-end
+    result = await handle_scratchpad(
+        session,
+        {
+            "action": "exec",
+            "name": "main",
+            "code": "import pandas as pd\ndf = pd.read_csv('mixed.csv')",
+            "one_line_description": "Load mixed.csv into a DataFrame",
+            "estimated_execution_time_seconds": 2,
+        },
+    )
+    assert isinstance(result, str)
+
+    # Step 2: cerebellum buffered the errored cell (cheap path skipped)
+    assert cerebellum.buffered_count == 1
+
+    # The diff LLM has NOT been called yet — that happens at flush
+    llm.generate_object_code.assert_not_called()
+    cortex.encode.assert_not_called()
+
+    # Step 3: simulate end-of-turn flush
+    lessons = await cerebellum.flush()
+
+    # The diff LLM was called once with the buffered cell, using the
+    # forced-tool-choice path via _DiffPassResult
+    llm.generate_object_code.assert_called_once()
+    call_args = llm.generate_object_code.call_args
+    assert call_args.args[0] is _DiffPassResult
+    diff_prompt = call_args.kwargs["messages"][0]["content"]
+    assert "Load mixed.csv into a DataFrame" in diff_prompt
+    assert "DtypeWarning" in diff_prompt
+
+    # Lesson was extracted
+    assert len(lessons) == 1
+    assert "low_memory" in lessons[0].text
+
+    # And encoded via cortex
+    cortex.encode.assert_awaited_once()
+    engrams = cortex.encode.call_args.args[0]
+    assert len(engrams) == 1
+    assert isinstance(engrams[0], Engram)
+    assert engrams[0].kind == "lesson"
+    assert engrams[0].topic == "scratchpad"
+    assert "low_memory" in engrams[0].text
+
+    # Buffer is now empty
+    assert cerebellum.buffered_count == 0
+
+
+@pytest.mark.asyncio
+async def test_clean_cell_never_triggers_diff():
+    """A successful cell should never reach the cerebellum's LLM diff."""
+    clean_cell = Cell(
+        code="print(1+1)",
+        stdout="2",
+        stderr="",
+        error=None,
+        description="add two",
+    )
+    session, cortex, llm, cerebellum = _build_session_with_cerebellum(
+        pad_returns=clean_cell,
+        lessons=[],
+    )
+
+    await handle_scratchpad(
+        session,
+        {
+            "action": "exec",
+            "name": "main",
+            "code": "print(1+1)",
+            "one_line_description": "add two",
+            "estimated_execution_time_seconds": 1,
+        },
+    )
+
+    # Cell was clean — never buffered
+    assert cerebellum.buffered_count == 0
+
+    # Even if we flush, no LLM call happens because buffer is empty
+    await cerebellum.flush()
+    llm.generate_object_code.assert_not_called()
+    cortex.encode.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_multiple_errored_cells_batched_into_single_diff():
+    """Multiple cells in one turn → ONE diff call at flush, not N."""
+    cell1 = Cell(
+        code="x = bad_func()",
+        stdout="",
+        stderr="",
+        error="NameError: name 'bad_func' is not defined",
+        description="call bad_func",
+    )
+    cell2 = Cell(
+        code="y = 1 / 0",
+        stdout="",
+        stderr="",
+        error="ZeroDivisionError: division by zero",
+        description="divide by zero",
+    )
+    session, cortex, llm, cerebellum = _build_session_with_cerebellum(
+        pad_returns=cell1,  # first call returns cell1
+        lessons=[
+            ("Define functions before calling.", "scratchpad"),
+            ("Guard against division by zero.", "scratchpad"),
+        ],
+    )
+
+    # First exec returns cell1
+    await handle_scratchpad(
+        session,
+        {
+            "action": "exec",
+            "name": "main",
+            "code": "x = bad_func()",
+            "one_line_description": "call bad_func",
+            "estimated_execution_time_seconds": 1,
+        },
+    )
+
+    # Re-mock pad.execute to return cell2 for the second call
+    session._scratchpads.get_or_create.return_value.execute = AsyncMock(
+        return_value=cell2
+    )
+    await handle_scratchpad(
+        session,
+        {
+            "action": "exec",
+            "name": "main",
+            "code": "y = 1 / 0",
+            "one_line_description": "divide by zero",
+            "estimated_execution_time_seconds": 1,
+        },
+    )
+
+    # Two cells buffered, zero LLM calls so far
+    assert cerebellum.buffered_count == 2
+    llm.generate_object_code.assert_not_called()
+
+    # One flush → one generate_object call → both lessons encoded together
+    await cerebellum.flush()
+    llm.generate_object_code.assert_called_once()  # ← THE KEY ASSERTION: batched per turn
+    cortex.encode.assert_awaited_once()
+    engrams = cortex.encode.call_args.args[0]
+    assert len(engrams) == 2
diff --git a/tests/test_chat.py b/tests/test_chat.py
index 42fecc09..de13a815 100644
--- a/tests/test_chat.py
+++ b/tests/test_chat.py
@@ -5,7 +5,9 @@
 import pytest
 
 from anton.chat import ChatSession
-from anton.llm.provider import (
+from anton.core.session import ChatSessionConfig
+from tests.conftest import make_mock_llm
+from anton.core.llm.provider import (
     ContextOverflowError,
     LLMResponse,
     StreamComplete,
@@ -28,10 +30,10 @@ def _text_response(text: str) -> LLMResponse:
 class TestChatSession:
     async def test_conversational_turn(self):
         """Text-only response for casual conversation."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hey! How can I help?"))
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm))
         reply = await session.turn("hi")
 
         assert reply == "Hey! How can I help?"
@@ -39,7 +41,7 @@ async def test_conversational_turn(self):
 
     async def test_history_grows_across_turns(self):
         """Multiple turns accumulate in history."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _text_response("Hi there!"),
@@ -48,7 +50,7 @@ async def test_history_grows_across_turns(self):
             ]
         )
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm))
         await session.turn("hello")
         await session.turn("can you check something")
         await session.turn("the anton repo")
@@ -77,7 +79,7 @@ async def _gen(**kwargs):
 class TestChatSessionStreaming:
     async def test_turn_stream_yields_text_deltas(self):
         """Streaming turn yields text deltas and updates history."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
 
         async def _stream(**kwargs):
             yield StreamTextDelta(text="Hello ")
@@ -86,7 +88,7 @@ async def _stream(**kwargs):
 
         mock_llm.plan_stream = _stream
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm))
         events = []
         async for event in session.turn_stream("hi"):
             events.append(event)
@@ -123,7 +125,7 @@ async def _plan_stream(**kwargs):
                     )
                 )
 
-        session = ChatSession(AsyncMock())
+        session = ChatSession(ChatSessionConfig(llm_client=make_mock_llm()))
         session._llm.plan_stream = _plan_stream
         session._llm.plan = AsyncMock(return_value=_text_response("STATUS: COMPLETE — done"))
         session._summarize_history = AsyncMock()
@@ -144,7 +146,7 @@ async def _plan_stream(**kwargs):
                 )
             )
 
-        session = ChatSession(AsyncMock())
+        session = ChatSession(ChatSessionConfig(llm_client=make_mock_llm()))
         session._llm.plan_stream = _plan_stream
         session._llm.plan = AsyncMock(return_value=_text_response("STATUS: COMPLETE — done"))
         session._summarize_history = AsyncMock()
@@ -165,7 +167,7 @@ async def _plan_stream(**kwargs):
                 )
             )
 
-        session = ChatSession(AsyncMock())
+        session = ChatSession(ChatSessionConfig(llm_client=make_mock_llm()))
         session._llm.plan_stream = _plan_stream
         session._llm.plan = AsyncMock(return_value=_text_response("STATUS: COMPLETE — done"))
         session._summarize_history = AsyncMock()
diff --git a/tests/test_chat_context.py b/tests/test_chat_context.py
index e06f4276..8939c30c 100644
--- a/tests/test_chat_context.py
+++ b/tests/test_chat_context.py
@@ -5,18 +5,21 @@
 import urllib.error
 from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock
+from tests.conftest import make_mock_llm
 
 import pytest
 
 from anton.chat import ChatSession, _handle_connect
+from anton.core.session import ChatSessionConfig
+from anton.core.llm.prompt_builder import SystemPromptContext
 from anton.minds_client import describe_minds_connection_error
 from anton.config.settings import AntonSettings
-from anton.tools import MEMORIZE_TOOL
+from anton.core.tools.tool_defs import MEMORIZE_TOOL
 from anton.context.self_awareness import SelfAwarenessContext
-from anton.llm.provider import LLMResponse, ToolCall, Usage
+from anton.core.llm.provider import LLMResponse, ToolCall, Usage
 from anton.workspace import Workspace
-from anton.memory.cortex import Cortex
-from anton.memory.hippocampus import Hippocampus
+from anton.core.memory.cortex import Cortex
+from anton.core.memory.hippocampus import Hippocampus
 
 
 def _text_response(text: str) -> LLMResponse:
@@ -76,18 +79,18 @@ def memory_dirs(tmp_path):
 @pytest.fixture()
 def cortex(memory_dirs):
     global_dir, project_dir = memory_dirs
-    return Cortex(global_dir=global_dir, project_dir=project_dir, mode="autopilot")
+    return Cortex(global_hc=Hippocampus(global_dir), project_hc=Hippocampus(project_dir), mode="autopilot")
 
 
 class TestMemorizeTool:
     def test_tool_definition_structure(self):
-        assert MEMORIZE_TOOL["name"] == "memorize"
-        props = MEMORIZE_TOOL["input_schema"]["properties"]
+        assert MEMORIZE_TOOL.name == "memorize"
+        props = MEMORIZE_TOOL.input_schema["properties"]
         assert "entries" in props
 
     async def test_memorize_creates_rule(self, cortex, memory_dirs):
         """When LLM calls memorize, a rule is created in memory."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _memorize_response(
@@ -98,7 +101,7 @@ async def test_memorize_creates_rule(self, cortex, memory_dirs):
             ]
         )
 
-        session = ChatSession(mock_llm, cortex=cortex)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, cortex=cortex))
         reply = await session.turn("always use httpx instead of requests")
         await asyncio.sleep(0)  # Let fire-and-forget encode task run
 
@@ -113,7 +116,7 @@ async def test_memorize_creates_rule(self, cortex, memory_dirs):
 
     async def test_memorize_creates_lesson(self, cortex, memory_dirs):
         """When LLM calls memorize with kind=lesson, a lesson is created."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _memorize_response(
@@ -124,7 +127,7 @@ async def test_memorize_creates_lesson(self, cortex, memory_dirs):
             ]
         )
 
-        session = ChatSession(mock_llm, cortex=cortex)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, cortex=cortex))
         await session.turn("coingecko rate limits at 50 per minute")
         await asyncio.sleep(0)  # Let fire-and-forget encode task run
 
@@ -142,10 +145,10 @@ async def test_memory_injected_into_system_prompt(self, cortex, memory_dirs):
         hc = Hippocampus(project_dir)
         hc.encode_rule("Use httpx instead of requests", kind="always", confidence="high", source="user")
 
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hello!"))
 
-        session = ChatSession(mock_llm, cortex=cortex)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, cortex=cortex))
         await session.turn("hi")
 
         call_kwargs = mock_llm.plan.call_args
@@ -155,10 +158,10 @@ async def test_memory_injected_into_system_prompt(self, cortex, memory_dirs):
 
     async def test_no_cortex_excludes_memorize_tool(self):
         """Without cortex or self_awareness, memorize tool is not offered."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hi!"))
 
-        session = ChatSession(mock_llm, self_awareness=None, cortex=None)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, self_awareness=None, cortex=None))
         await session.turn("hello")
 
         call_kwargs = mock_llm.plan.call_args
@@ -169,10 +172,10 @@ async def test_no_cortex_excludes_memorize_tool(self):
 
     async def test_cortex_includes_memorize_tool(self, cortex):
         """With cortex, memorize tool is included."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hi!"))
 
-        session = ChatSession(mock_llm, cortex=cortex)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, cortex=cortex))
         await session.turn("hello")
 
         call_kwargs = mock_llm.plan.call_args
@@ -183,7 +186,7 @@ async def test_cortex_includes_memorize_tool(self, cortex):
 
     async def test_tool_result_in_history(self, cortex, memory_dirs):
         """memorize tool result appears in conversation history."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _memorize_response(
@@ -194,7 +197,7 @@ async def test_tool_result_in_history(self, cortex, memory_dirs):
             ]
         )
 
-        session = ChatSession(mock_llm, cortex=cortex)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, cortex=cortex))
         await session.turn("note this")
 
         tool_result_msgs = [
@@ -211,14 +214,14 @@ async def test_anton_md_injected_into_system_prompt(self, ws, cortex):
         """anton.md content is injected into the system prompt."""
         ws.anton_md_path.write_text("This project uses Django and PostgreSQL")
 
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hello!"))
 
-        session = ChatSession(
-            mock_llm,
+        session = ChatSession(ChatSessionConfig(
+            llm_client=mock_llm,
             cortex=cortex,
             workspace=ws,
-        )
+        ))
         await session.turn("hi")
 
         call_kwargs = mock_llm.plan.call_args
@@ -230,14 +233,14 @@ async def test_empty_anton_md_no_section(self, ws, cortex):
         """Empty anton.md doesn't add a section to the prompt."""
         ws.anton_md_path.write_text("")
 
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hello!"))
 
-        session = ChatSession(
-            mock_llm,
+        session = ChatSession(ChatSessionConfig(
+            llm_client=mock_llm,
             cortex=cortex,
             workspace=ws,
-        )
+        ))
         await session.turn("hi")
 
         call_kwargs = mock_llm.plan.call_args
@@ -248,13 +251,13 @@ async def test_empty_anton_md_no_section(self, ws, cortex):
 class TestRuntimeContext:
     async def test_runtime_context_injected_into_system_prompt(self):
         """Runtime context (provider/model) appears in the system prompt."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hello!"))
 
-        session = ChatSession(
-            mock_llm,
-            runtime_context="- Provider: anthropic\n- Planning model: claude-sonnet-4-6\n- Coding model: claude-opus-4-6",
-        )
+        session = ChatSession(ChatSessionConfig(
+            llm_client=mock_llm,
+            system_prompt_context=SystemPromptContext(runtime_context="- Provider: anthropic\n- Planning model: claude-sonnet-4-6\n- Coding model: claude-opus-4-6"),
+        ))
         await session.turn("hi")
 
         call_kwargs = mock_llm.plan.call_args
@@ -265,13 +268,13 @@ async def test_runtime_context_injected_into_system_prompt(self):
 
     async def test_system_prompt_warns_not_to_ask_about_llm(self):
         """System prompt includes instruction to never ask which LLM to use."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hello!"))
 
-        session = ChatSession(
-            mock_llm,
-            runtime_context="- Provider: anthropic",
-        )
+        session = ChatSession(ChatSessionConfig(
+            llm_client=mock_llm,
+            system_prompt_context=SystemPromptContext(runtime_context="- Provider: anthropic"),
+        ))
         await session.turn("hi")
 
         call_kwargs = mock_llm.plan.call_args
@@ -280,10 +283,10 @@ async def test_system_prompt_warns_not_to_ask_about_llm(self):
 
     async def test_conversation_discipline_in_prompt(self):
         """System prompt includes conversation discipline rules."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hello!"))
 
-        session = ChatSession(mock_llm, runtime_context="")
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, system_prompt_context=SystemPromptContext()))
         await session.turn("hi")
 
         call_kwargs = mock_llm.plan.call_args
diff --git a/tests/test_chat_scratchpad.py b/tests/test_chat_scratchpad.py
index 45926e83..22b43ebb 100644
--- a/tests/test_chat_scratchpad.py
+++ b/tests/test_chat_scratchpad.py
@@ -1,12 +1,24 @@
 from __future__ import annotations
 
+from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock, patch
+from tests.conftest import make_mock_llm
 
 import pytest
 
-from anton.chat import SCRATCHPAD_TOOL, ChatSession
+from anton.core.session import ChatSession, ChatSessionConfig
+from anton.core.tools.tool_defs import SCRATCHPAD_TOOL
 from anton.commands.session import handle_resume
-from anton.llm.provider import LLMResponse, StreamComplete, StreamToolResult, ToolCall, Usage
+from anton.core.llm.provider import LLMResponse, StreamComplete, StreamToolResult, ToolCall, Usage
+
+
+@pytest.fixture()
+def workspace():
+    # Keep scratchpad venvs inside the repo workspace (pytest runs sandboxed and
+    # can't write to the real home directory).
+    base = Path(__file__).resolve().parents[1] / ".pytest-workspace"
+    base.mkdir(parents=True, exist_ok=True)
+    return MagicMock(base=base)
 
 
 def _text_response(text: str) -> LLMResponse:
@@ -39,29 +51,29 @@ def _scratchpad_response(
 
 class TestScratchpadToolDefinition:
     def test_tool_definition_structure(self):
-        assert SCRATCHPAD_TOOL["name"] == "scratchpad"
-        props = SCRATCHPAD_TOOL["input_schema"]["properties"]
+        assert SCRATCHPAD_TOOL.name == "scratchpad"
+        props = SCRATCHPAD_TOOL.input_schema["properties"]
         assert "action" in props
         assert "name" in props
         assert "code" in props
         assert "packages" in props
-        assert SCRATCHPAD_TOOL["input_schema"]["required"] == ["action", "name"]
+        assert SCRATCHPAD_TOOL.input_schema["required"] == ["action", "name"]
 
     def test_tool_has_install_action(self):
-        actions = SCRATCHPAD_TOOL["input_schema"]["properties"]["action"]["enum"]
+        actions = SCRATCHPAD_TOOL.input_schema["properties"]["action"]["enum"]
         assert "install" in actions
 
     def test_packages_property_is_array_of_strings(self):
-        packages_prop = SCRATCHPAD_TOOL["input_schema"]["properties"]["packages"]
+        packages_prop = SCRATCHPAD_TOOL.input_schema["properties"]["packages"]
         assert packages_prop["type"] == "array"
         assert packages_prop["items"] == {"type": "string"}
 
-    async def test_scratchpad_tool_in_tools(self):
+    async def test_scratchpad_tool_in_tools(self, workspace):
         """scratchpad should always be in _build_tools() output."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("Hi!"))
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             await session.turn("hello")
 
@@ -74,9 +86,9 @@ async def test_scratchpad_tool_in_tools(self):
 
 
 class TestScratchpadExecViaChat:
-    async def test_scratchpad_exec_via_chat(self):
+    async def test_scratchpad_exec_via_chat(self, workspace):
         """exec action flows through and returns output."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _scratchpad_response("Let me compute.", "exec", "main", "print(7 * 6)"),
@@ -84,7 +96,7 @@ async def test_scratchpad_exec_via_chat(self):
             ]
         )
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             reply = await session.turn("what is 7 * 6?")
 
@@ -100,9 +112,9 @@ async def test_scratchpad_exec_via_chat(self):
 
 
 class TestScratchpadViewViaChat:
-    async def test_scratchpad_view_via_chat(self):
+    async def test_scratchpad_view_via_chat(self, workspace):
         """view action returns cell history."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _scratchpad_response("Running code.", "exec", "analysis", "x = 10\nprint(x)"),
@@ -111,7 +123,7 @@ async def test_scratchpad_view_via_chat(self):
             ]
         )
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             await session.turn("run and show")
 
@@ -129,9 +141,9 @@ async def test_scratchpad_view_via_chat(self):
 
 
 class TestScratchpadRemoveViaChat:
-    async def test_scratchpad_remove_via_chat(self):
+    async def test_scratchpad_remove_via_chat(self, workspace):
         """remove action cleans up the scratchpad."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _scratchpad_response("Creating.", "exec", "tmp", "print('hi')"),
@@ -140,7 +152,7 @@ async def test_scratchpad_remove_via_chat(self):
             ]
         )
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             await session.turn("create and remove")
 
@@ -155,9 +167,9 @@ async def test_scratchpad_remove_via_chat(self):
 
 
 class TestScratchpadDumpViaChat:
-    async def test_scratchpad_dump_via_chat(self):
+    async def test_scratchpad_dump_via_chat(self, workspace):
         """dump action flows through chat, returns markdown with code fences."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 # First: exec some code
@@ -169,7 +181,7 @@ async def test_scratchpad_dump_via_chat(self):
             ]
         )
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             await session.turn("show me my work")
 
@@ -202,10 +214,10 @@ async def __anext__(self):
 
 
 class TestScratchpadDumpStreaming:
-    async def test_scratchpad_dump_streams_tool_result(self):
+    async def test_scratchpad_dump_streams_tool_result(self, workspace):
         """dump action yields a StreamToolResult for display, but sends a short
         summary back to the LLM to avoid it parroting the full notebook."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("STATUS: COMPLETE — task done"))
 
         call_count = 0
@@ -231,7 +243,7 @@ def fake_plan_stream(**kwargs):
 
         mock_llm.plan_stream = fake_plan_stream
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             events = []
             async for event in session.turn_stream("show work"):
@@ -255,12 +267,12 @@ def fake_plan_stream(**kwargs):
 
 
 class TestScratchpadStreaming:
-    async def test_scratchpad_in_streaming_path(self):
+    async def test_scratchpad_in_streaming_path(self, workspace):
         """scratchpad exec should work in turn_stream() too."""
         tool_response = _scratchpad_response("Computing.", "exec", "s", "print(99)")
         final_response = _text_response("Got 99.")
 
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(return_value=_text_response("STATUS: COMPLETE — task done"))
 
         call_count = 0
@@ -274,7 +286,7 @@ def fake_plan_stream(**kwargs):
 
         mock_llm.plan_stream = fake_plan_stream
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             events = []
             async for event in session.turn_stream("compute 99"):
@@ -294,9 +306,9 @@ def fake_plan_stream(**kwargs):
 
 
 class TestScratchpadInstallViaChat:
-    async def test_install_action_dispatch(self):
+    async def test_install_action_dispatch(self, workspace):
         """install action flows through chat and returns pip output."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _scratchpad_response(
@@ -306,7 +318,7 @@ async def test_install_action_dispatch(self):
             ]
         )
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             reply = await session.turn("install cowsay")
 
@@ -320,9 +332,9 @@ async def test_install_action_dispatch(self):
         finally:
             await session.close()
 
-    async def test_install_empty_packages_via_chat(self):
+    async def test_install_empty_packages_via_chat(self, workspace):
         """install with no packages returns a message without crashing."""
-        mock_llm = AsyncMock()
+        mock_llm = make_mock_llm()
         mock_llm.plan = AsyncMock(
             side_effect=[
                 _scratchpad_response("Installing.", "install", "main", packages=[]),
@@ -330,7 +342,7 @@ async def test_install_empty_packages_via_chat(self):
             ]
         )
 
-        session = ChatSession(mock_llm)
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm, workspace=workspace))
         try:
             await session.turn("install nothing")
 
diff --git a/tests/test_chat_ui.py b/tests/test_chat_ui.py
index 539ab1b3..4ed6d141 100644
--- a/tests/test_chat_ui.py
+++ b/tests/test_chat_ui.py
@@ -2,7 +2,7 @@
 
 from unittest.mock import MagicMock, patch
 
-from anton.chat_ui import PHASE_LABELS, StreamDisplay, _tool_display_text
+from anton.chat_ui import PHASE_LABELS, StreamDisplay, _MAX_DESC, _tool_display_text
 
 
 
@@ -111,7 +111,7 @@ def test_json_delta_accumulation(self, MockLive):
         display.on_tool_use_end("tool_1")
 
         act = display._activities[0]
-        assert act.description == "Scratchpad(exec)"
+        assert act.description == "exec"  # no Scratchpad() wrapper
 
     @patch("anton.chat_ui.Live")
     def test_finish_prints_activity_summary(self, MockLive):
@@ -163,39 +163,44 @@ def test_multiple_tool_calls(self, MockLive):
         display.on_tool_use_end("tool_2")
 
         assert len(display._activities) == 2
-        assert display._activities[0].description == "Scratchpad(exec)"
-        assert display._activities[1].description == "Memory(1 entry/entries)"
+        # Scratchpad now shows just the description (no wrapper)
+        assert display._activities[0].description == "exec"
+        # Memorize now shows a witty phrase (random, so just check it's a string)
+        assert display._activities[1].description  # non-empty
 
     def test_malformed_json_fallback(self):
-        # Bad JSON should not crash, falls back to just the label
+        # Bad JSON should not crash — falls back to a default
         result = _tool_display_text("scratchpad", "{broken json")
-        assert result == "Scratchpad"
+        assert result == "Running code"
 
     def test_tool_display_text_truncation(self):
         long_desc = "a" * 100
         result = _tool_display_text("scratchpad", f'{{"one_line_description": "{long_desc}"}}')
-        assert len(result) <= len("Scratchpad()") + 60
-        assert result.endswith("\u2026)")
+        # No wrapper — just the truncated description
+        assert len(result) <= _MAX_DESC
+        assert result.endswith("\u2026")
 
     def test_tool_display_text_unknown_tool(self):
         result = _tool_display_text("some_new_tool", '{"foo": "bar"}')
-        assert result == "some_new_tool"
+        # Unknown tools get a generic phrase from _GENERIC_TOOL_PHRASES
+        assert isinstance(result, str)
+        assert len(result) > 0
 
     def test_scratchpad_display_uses_one_line_description(self):
-        """one_line_description should be preferred over action for scratchpad."""
+        """one_line_description should be used directly (no Scratchpad() wrapper)."""
         result = _tool_display_text(
             "scratchpad",
             '{"action": "exec", "name": "pad", "one_line_description": "Install packages"}',
         )
-        assert result == "Scratchpad(Install packages)"
+        assert result == "Install packages"
 
     def test_scratchpad_display_falls_back_to_action(self):
-        """Without one_line_description, scratchpad should show action."""
+        """Without one_line_description, scratchpad shows the action."""
         result = _tool_display_text(
             "scratchpad",
             '{"action": "exec", "name": "pad"}',
         )
-        assert result == "Scratchpad(exec)"
+        assert result == "exec"
 
     @patch("anton.chat_ui.Live")
     def test_text_routes_to_initial_before_tools(self, MockLive):
diff --git a/tests/test_client.py b/tests/test_client.py
index 991612a1..0885b6e5 100644
--- a/tests/test_client.py
+++ b/tests/test_client.py
@@ -5,8 +5,8 @@
 import pytest
 
 from anton.config.settings import AntonSettings
-from anton.llm.client import LLMClient
-from anton.llm.provider import LLMProvider, LLMResponse, Usage
+from anton.core.llm.client import LLMClient
+from anton.core.llm.provider import LLMProvider, LLMResponse, Usage
 
 
 @pytest.fixture()
@@ -75,7 +75,7 @@ async def test_plan_passes_tools(self, mock_providers):
 
 class TestLLMClientFromSettings:
     def test_from_settings_creates_client(self):
-        from anton.llm.anthropic import AnthropicProvider
+        from anton.core.llm.anthropic import AnthropicProvider
 
         with patch("anthropic.AsyncAnthropic"):
             settings = AntonSettings(
diff --git a/tests/test_connect_collector.py b/tests/test_connect_collector.py
new file mode 100644
index 00000000..cb938366
--- /dev/null
+++ b/tests/test_connect_collector.py
@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from anton.connect_collector import (
+    ConnectionCollector,
+    ExtractedData,
+    _ExtractionResult,
+    extract_variables,
+)
+from anton.core.datasources.datasource_registry import (
+    AuthMethod,
+    DatasourceEngine,
+    DatasourceField,
+)
+
+
+def _postgres_engine() -> DatasourceEngine:
+    return DatasourceEngine(
+        engine="postgres",
+        display_name="PostgreSQL",
+        fields=[
+            DatasourceField(name="host", required=True, description="hostname"),
+            DatasourceField(
+                name="port", required=True, default="5432", description="port"
+            ),
+            DatasourceField(name="database", required=True, description="db name"),
+            DatasourceField(name="user", required=True, description="username"),
+            DatasourceField(
+                name="password", required=True, secret=True, description="pwd"
+            ),
+            DatasourceField(name="schema", required=False, description="schema"),
+        ],
+    )
+
+
+def _hubspot_choice_engine() -> DatasourceEngine:
+    return DatasourceEngine(
+        engine="hubspot",
+        display_name="HubSpot",
+        auth_method="choice",
+        auth_methods=[
+            AuthMethod(
+                name="pat",
+                display="Personal Access Token",
+                fields=[
+                    DatasourceField(name="access_token", required=True, secret=True)
+                ],
+            ),
+            AuthMethod(
+                name="oauth",
+                display="OAuth2",
+                fields=[
+                    DatasourceField(name="client_id", required=True),
+                    DatasourceField(
+                        name="client_secret", required=True, secret=True
+                    ),
+                ],
+            ),
+        ],
+    )
+
+
+def _mock_session_with_extraction(
+    *,
+    variables: dict[str, str] | None = None,
+    is_redirect: bool = False,
+    redirect_engine: str = "",
+    redirect_reason: str = "",
+) -> MagicMock:
+    """Build a session whose `_llm.generate_object` returns a known result."""
+    extraction = _ExtractionResult(
+        variables=variables or {},
+        is_redirect=is_redirect,
+        redirect_engine=redirect_engine,
+        redirect_reason=redirect_reason,
+    )
+    session = MagicMock()
+    session._llm = MagicMock()
+    session._llm.generate_object = AsyncMock(return_value=extraction)
+    return session
+
+
+def _mock_session_raising(exc: Exception) -> MagicMock:
+    """Build a session whose `_llm.generate_object` raises the given exception."""
+    session = MagicMock()
+    session._llm = MagicMock()
+    session._llm.generate_object = AsyncMock(side_effect=exc)
+    return session
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ConnectionCollector
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestConnectionCollector:
+    def test_initial_state_all_required_missing(self):
+        c = ConnectionCollector(_postgres_engine())
+        assert not c.is_complete
+        assert len(c.missing_required) == 5
+        assert c.next_field is not None
+        assert c.next_field.name == "host"
+
+    def test_fill_simple(self):
+        c = ConnectionCollector(_postgres_engine())
+        assert c.fill("host", "localhost") is True
+        assert c.collected["host"] == "localhost"
+        assert len(c.missing_required) == 4
+        assert c.next_field is not None
+        assert c.next_field.name == "port"
+
+    def test_fill_unknown_field_rejected(self):
+        c = ConnectionCollector(_postgres_engine())
+        assert c.fill("made_up_field", "x") is False
+        assert "made_up_field" not in c.collected
+
+    def test_fill_empty_value_does_nothing(self):
+        c = ConnectionCollector(_postgres_engine())
+        assert c.fill("host", "") is True  # accepted (known field)
+        assert "host" not in c.collected  # but not stored
+
+    def test_fill_many(self):
+        c = ConnectionCollector(_postgres_engine())
+        accepted = c.fill_many(
+            {
+                "host": "db.x",
+                "port": "5432",
+                "user": "admin",
+                "password": "secret",
+                "database": "mydb",
+                "unknown_garbage": "ignored",
+            }
+        )
+        assert set(accepted) == {"host", "port", "user", "password", "database"}
+        assert "unknown_garbage" not in c.collected
+        assert c.is_complete
+
+    def test_complete_when_all_required_filled(self):
+        c = ConnectionCollector(_postgres_engine())
+        c.fill_many(
+            {
+                "host": "x",
+                "port": "5432",
+                "database": "d",
+                "user": "u",
+                "password": "p",
+            }
+        )
+        assert c.is_complete
+        assert c.missing_required == []
+
+    def test_optional_does_not_block_completion(self):
+        c = ConnectionCollector(_postgres_engine())
+        c.fill_many(
+            {
+                "host": "x",
+                "port": "5432",
+                "database": "d",
+                "user": "u",
+                "password": "p",
+            }
+        )
+        assert c.is_complete
+        # schema is optional and unfilled
+        assert any(f.name == "schema" for f in c.missing_optional)
+
+    def test_next_field_falls_back_to_optional_when_required_done(self):
+        c = ConnectionCollector(_postgres_engine())
+        c.fill_many(
+            {"host": "x", "port": "5", "database": "d", "user": "u", "password": "p"}
+        )
+        # All required filled — next_field is the first optional
+        assert c.next_field is not None
+        assert c.next_field.name == "schema"
+
+    def test_auth_method_active_fields(self):
+        engine = _hubspot_choice_engine()
+        pat = engine.auth_methods[0]
+        c = ConnectionCollector(engine, auth_method=pat)
+        # PAT method has only access_token, not client_id/client_secret
+        assert {f.name for f in c.active_fields} == {"access_token"}
+        c.fill("access_token", "abc123")
+        assert c.is_complete
+
+    def test_to_redirect_result(self):
+        c = ConnectionCollector(_postgres_engine())
+        c.fill_many({"host": "db.x", "user": "admin"})
+        c.redirect_message = "actually it's mysql"
+        result = c.to_redirect_result()
+        assert result["status"] == "redirect"
+        assert result["engine"] == "postgres"
+        assert result["engine_display"] == "PostgreSQL"
+        assert result["collected_variables"] == {"host": "db.x", "user": "admin"}
+        assert "port" in result["missing_required"]
+        assert "password" in result["missing_required"]
+        assert result["redirect_message"] == "actually it's mysql"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# extract_variables (LLM-driven)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestExtractVariables:
+    @pytest.mark.asyncio
+    async def test_empty_input_returns_empty(self):
+        engine = _postgres_engine()
+        session = _mock_session_with_extraction()
+        result = await extract_variables(
+            "",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres", "mysql"],
+            session=session,
+        )
+        assert result.variables == {}
+        assert not result.is_redirect
+        # Empty input shouldn't even call the LLM
+        session._llm.generate_object.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_llm_extracts_variables_from_bulk_input(self):
+        engine = _postgres_engine()
+        session = _mock_session_with_extraction(
+            variables={
+                "host": "db.example.com",
+                "port": "5432",
+                "user": "admin",
+            },
+        )
+        result = await extract_variables(
+            "host=db.example.com port=5432 user=admin",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres", "mysql"],
+            session=session,
+        )
+        assert result.variables == {
+            "host": "db.example.com",
+            "port": "5432",
+            "user": "admin",
+        }
+        assert not result.is_redirect
+
+    @pytest.mark.asyncio
+    async def test_passes_extraction_result_schema_to_llm(self):
+        """Verify generate_object was called with the right schema class."""
+        engine = _postgres_engine()
+        session = _mock_session_with_extraction(variables={"host": "db.x"})
+        await extract_variables(
+            "host=db.x",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres"],
+            session=session,
+        )
+        session._llm.generate_object.assert_called_once()
+        call_args = session._llm.generate_object.call_args
+        assert call_args.args[0] is _ExtractionResult
+
+    @pytest.mark.asyncio
+    async def test_llm_parses_connection_string(self):
+        engine = _postgres_engine()
+        session = _mock_session_with_extraction(
+            variables={
+                "host": "db.example.com",
+                "port": "5432",
+                "user": "admin",
+                "password": "secret",
+                "database": "mydb",
+            },
+        )
+        result = await extract_variables(
+            "postgres://admin:secret@db.example.com:5432/mydb",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres"],
+            session=session,
+        )
+        assert result.variables["host"] == "db.example.com"
+        assert result.variables["user"] == "admin"
+        assert result.variables["password"] == "secret"
+        assert result.variables["database"] == "mydb"
+
+    @pytest.mark.asyncio
+    async def test_llm_resolves_aliases(self):
+        engine = _postgres_engine()
+        session = _mock_session_with_extraction(
+            variables={
+                "host": "db.x",
+                "user": "admin",
+                "password": "secret",
+            },
+        )
+        result = await extract_variables(
+            "hostname=db.x username=admin pwd=secret",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres"],
+            session=session,
+        )
+        assert result.variables == {
+            "host": "db.x",
+            "user": "admin",
+            "password": "secret",
+        }
+
+    @pytest.mark.asyncio
+    async def test_llm_detects_redirect(self):
+        engine = _postgres_engine()
+        session = _mock_session_with_extraction(
+            variables={},
+            is_redirect=True,
+            redirect_engine="mysql",
+            redirect_reason="user wants mysql instead",
+        )
+        result = await extract_variables(
+            "actually let's use mysql instead",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres", "mysql"],
+            session=session,
+        )
+        assert result.is_redirect
+        assert result.redirect_engine == "mysql"
+        assert "mysql" in result.redirect_reason
+
+    @pytest.mark.asyncio
+    async def test_llm_ignores_fields_not_in_expected_list(self):
+        engine = _postgres_engine()
+        session = _mock_session_with_extraction(
+            variables={
+                "host": "db.x",
+                "bogus_field": "should be dropped",
+            },
+        )
+        result = await extract_variables(
+            "host=db.x bogus=y",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres"],
+            session=session,
+        )
+        assert result.variables == {"host": "db.x"}
+        assert "bogus_field" not in result.variables
+
+    @pytest.mark.asyncio
+    async def test_llm_exception_returns_empty_result(self):
+        engine = _postgres_engine()
+        session = _mock_session_raising(RuntimeError("network error"))
+        result = await extract_variables(
+            "host=db.x",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres"],
+            session=session,
+        )
+        # Exception is caught → empty result, never crashes the flow
+        assert result.variables == {}
+        assert not result.is_redirect
+
+    @pytest.mark.asyncio
+    async def test_validation_error_returns_empty_result(self):
+        """If generate_object raises a Pydantic ValidationError (rare with
+        forced tool_choice, but possible), we fall back to empty result."""
+        from pydantic import ValidationError as _PVE
+
+        engine = _postgres_engine()
+        try:
+            _ExtractionResult.model_validate({"variables": "not a dict"})
+        except _PVE as exc:
+            session = _mock_session_raising(exc)
+        result = await extract_variables(
+            "anything",
+            expected_fields=engine.fields,
+            current_engine="postgres",
+            current_engine_display="PostgreSQL",
+            known_engine_slugs=["postgres"],
+            session=session,
+        )
+        assert result.variables == {}
+        assert not result.is_redirect
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ExtractedData dataclass sanity
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestExtractedData:
+    def test_default_values(self):
+        e = ExtractedData()
+        assert e.variables == {}
+        assert not e.is_redirect
+        assert e.redirect_engine is None
+        assert e.redirect_reason == ""
diff --git a/tests/test_consolidator.py b/tests/test_consolidator.py
index ffb82d1b..153f741b 100644
--- a/tests/test_consolidator.py
+++ b/tests/test_consolidator.py
@@ -5,7 +5,11 @@
 
 import pytest
 
-from anton.memory.consolidator import Consolidator
+from anton.core.memory.consolidator import (
+    Consolidator,
+    _ConsolidatedLesson,
+    _ConsolidatedLessons,
+)
 
 
 @dataclass
@@ -56,9 +60,18 @@ async def test_extracts_lessons(self, consolidator):
         ]
 
         mock_llm = AsyncMock()
-        mock_llm.code = AsyncMock(return_value=type("R", (), {
-            "content": '[{"text": "Always validate JSON before parsing", "kind": "always", "scope": "global", "confidence": "high"}]'
-        })())
+        mock_llm.generate_object_code = AsyncMock(
+            return_value=_ConsolidatedLessons(
+                items=[
+                    _ConsolidatedLesson(
+                        text="Always validate JSON before parsing",
+                        kind="always",
+                        scope="global",
+                        confidence="high",
+                    )
+                ]
+            )
+        )
 
         engrams = await consolidator.replay_and_extract(cells, mock_llm)
         assert len(engrams) == 1
@@ -69,7 +82,9 @@ async def test_extracts_lessons(self, consolidator):
     async def test_handles_empty_response(self, consolidator):
         cells = [MockCell(), MockCell()]
         mock_llm = AsyncMock()
-        mock_llm.code = AsyncMock(return_value=type("R", (), {"content": "[]"})())
+        mock_llm.generate_object_code = AsyncMock(
+            return_value=_ConsolidatedLessons(items=[])
+        )
 
         engrams = await consolidator.replay_and_extract(cells, mock_llm)
         assert engrams == []
@@ -77,28 +92,39 @@ async def test_handles_empty_response(self, consolidator):
     async def test_handles_llm_failure(self, consolidator):
         cells = [MockCell(), MockCell()]
         mock_llm = AsyncMock()
-        mock_llm.code = AsyncMock(side_effect=Exception("API error"))
+        mock_llm.generate_object_code = AsyncMock(side_effect=Exception("API error"))
 
         engrams = await consolidator.replay_and_extract(cells, mock_llm)
         assert engrams == []
 
-    async def test_handles_markdown_fenced_json(self, consolidator):
-        cells = [MockCell(description="test", error="SomeError")]
+    async def test_skips_blank_text_entries(self, consolidator):
+        """Defensive: even with forced schema, blank text should be skipped."""
+        cells = [MockCell(), MockCell()]
         mock_llm = AsyncMock()
-        mock_llm.code = AsyncMock(return_value=type("R", (), {
-            "content": '```json\n[{"text": "Handle errors gracefully", "kind": "lesson", "scope": "project"}]\n```'
-        })())
+        mock_llm.generate_object_code = AsyncMock(
+            return_value=_ConsolidatedLessons(
+                items=[
+                    _ConsolidatedLesson(text="valid", kind="lesson", scope="global"),
+                    _ConsolidatedLesson(text="   ", kind="lesson", scope="project"),
+                ]
+            )
+        )
 
         engrams = await consolidator.replay_and_extract(cells, mock_llm)
         assert len(engrams) == 1
-        assert engrams[0].text == "Handle errors gracefully"
+        assert engrams[0].text == "valid"
 
-    async def test_invalid_entries_skipped(self, consolidator):
+    async def test_caps_at_five_lessons(self, consolidator):
         cells = [MockCell(), MockCell()]
         mock_llm = AsyncMock()
-        mock_llm.code = AsyncMock(return_value=type("R", (), {
-            "content": '[{"text": "valid", "kind": "lesson", "scope": "global"}, {"bad": "entry"}, "not a dict"]'
-        })())
+        mock_llm.generate_object_code = AsyncMock(
+            return_value=_ConsolidatedLessons(
+                items=[
+                    _ConsolidatedLesson(text=f"lesson {i}")
+                    for i in range(10)
+                ]
+            )
+        )
 
         engrams = await consolidator.replay_and_extract(cells, mock_llm)
-        assert len(engrams) == 1
+        assert len(engrams) == 5
diff --git a/tests/test_cortex.py b/tests/test_cortex.py
index e6f202b8..17288058 100644
--- a/tests/test_cortex.py
+++ b/tests/test_cortex.py
@@ -5,8 +5,8 @@
 
 import pytest
 
-from anton.memory.cortex import Cortex
-from anton.memory.hippocampus import Engram, Hippocampus
+from anton.core.memory.cortex import Cortex
+from anton.core.memory.hippocampus import Engram, Hippocampus
 
 
 @pytest.fixture()
@@ -21,7 +21,7 @@ def dirs(tmp_path):
 @pytest.fixture()
 def cortex(dirs):
     g, p = dirs
-    return Cortex(global_dir=g, project_dir=p, mode="copilot")
+    return Cortex(global_hc=Hippocampus(g), project_hc=Hippocampus(p), mode="copilot")
 
 
 class TestBuildMemoryContext:
@@ -98,7 +98,7 @@ async def test_encode_profile(self, cortex, dirs):
 
     async def test_off_mode_returns_disabled(self, dirs):
         g, p = dirs
-        cortex = Cortex(global_dir=g, project_dir=p, mode="off")
+        cortex = Cortex(global_hc=Hippocampus(g), project_hc=Hippocampus(p), mode="off")
         engram = Engram(text="test", kind="lesson", scope="global")
         actions = await cortex.encode([engram])
         assert any("disabled" in a.lower() for a in actions)
@@ -107,19 +107,19 @@ async def test_off_mode_returns_disabled(self, dirs):
 class TestEncodingGate:
     def test_autopilot_never_confirms(self, dirs):
         g, p = dirs
-        cortex = Cortex(global_dir=g, project_dir=p, mode="autopilot")
+        cortex = Cortex(global_hc=Hippocampus(g), project_hc=Hippocampus(p), mode="autopilot")
         engram = Engram(text="test", kind="lesson", scope="global", confidence="low")
         assert cortex.encoding_gate(engram) is False
 
     def test_off_never_confirms(self, dirs):
         g, p = dirs
-        cortex = Cortex(global_dir=g, project_dir=p, mode="off")
+        cortex = Cortex(global_hc=Hippocampus(g), project_hc=Hippocampus(p), mode="off")
         engram = Engram(text="test", kind="lesson", scope="global", confidence="high")
         assert cortex.encoding_gate(engram) is False
 
     def test_copilot_confirms_low_confidence(self, dirs):
         g, p = dirs
-        cortex = Cortex(global_dir=g, project_dir=p, mode="copilot")
+        cortex = Cortex(global_hc=Hippocampus(g), project_hc=Hippocampus(p), mode="copilot")
         low = Engram(text="test", kind="lesson", scope="global", confidence="medium")
         high = Engram(text="test", kind="lesson", scope="global", confidence="high")
         assert cortex.encoding_gate(low) is True
@@ -148,15 +148,19 @@ async def test_no_llm_does_nothing(self, cortex, dirs):
     async def test_off_mode_does_nothing(self, dirs):
         g, p = dirs
         mock_llm = AsyncMock()
-        cortex = Cortex(global_dir=g, project_dir=p, mode="off", llm_client=mock_llm)
+        cortex = Cortex(global_hc=Hippocampus(g), project_hc=Hippocampus(p), mode="off", llm_client=mock_llm)
         await cortex.maybe_update_identity("I'm Jorge")
-        mock_llm.code.assert_not_called()
+        mock_llm.generate_object_code.assert_not_called()
 
     async def test_extracts_identity(self, dirs):
+        from anton.core.memory.cortex import _IdentityFacts
+
         g, p = dirs
         mock_llm = AsyncMock()
-        mock_llm.code = AsyncMock(return_value=type("R", (), {"content": '["Name: Jorge"]'})())
-        cortex = Cortex(global_dir=g, project_dir=p, mode="copilot", llm_client=mock_llm)
+        mock_llm.generate_object_code = AsyncMock(
+            return_value=_IdentityFacts(facts=["Name: Jorge"])
+        )
+        cortex = Cortex(global_hc=Hippocampus(g), project_hc=Hippocampus(p), mode="copilot", llm_client=mock_llm)
         await cortex.maybe_update_identity("Hi, I'm Jorge")
         assert (g / "profile.md").exists()
         assert "Name: Jorge" in (g / "profile.md").read_text()
diff --git a/tests/test_datasource.py b/tests/test_datasource.py
index 2326513b..e480625c 100644
--- a/tests/test_datasource.py
+++ b/tests/test_datasource.py
@@ -12,6 +12,7 @@
 from anton.chat import (
     ChatSession,
 )
+from anton.core.session import ChatSessionConfig
 from anton.commands.datasource import (
     _PROMPT_RECONNECT_CANCEL,
     handle_add_custom_datasource,
@@ -31,8 +32,8 @@
     parse_connection_slug,
 )
 from anton.cli import app as cli_app
-from anton.data_vault import DataVault, _slug_env_prefix
-from anton.datasource_registry import (
+from anton.core.datasources.data_vault import DataVault, LocalDataVault, _slug_env_prefix
+from anton.core.datasources.datasource_registry import (
     DatasourceEngine,
     DatasourceRegistry,
     _parse_file,
@@ -46,7 +47,7 @@ def vault_dir(tmp_path):
 
 @pytest.fixture()
 def vault(vault_dir):
-    return DataVault(vault_dir=vault_dir)
+    return LocalDataVault(vault_dir=vault_dir)
 
 
 @pytest.fixture()
@@ -142,14 +143,42 @@ def registry(datasources_md):
 
 @pytest.fixture()
 def make_session():
-    """Factory that creates a fresh ChatSession with mocked scratchpads."""
+    """Factory that creates a fresh ChatSession with mocked scratchpads.
+
+    The default `generate_object` dispatcher returns a sensible empty
+    instance for whichever Pydantic schema the production code asks
+    for. Tests that need a non-empty result should override
+    `session._llm.generate_object` after construction.
+    """
 
     def _factory():
+        from anton.connect_collector import _ExtractionResult
+
+        async def _default_generate_object(schema_class, **kwargs):
+            # Known extraction schemas → empty defaults so the call
+            # falls back to "no structured data" behavior. Unknown
+            # schemas → raise so the caller's try/except sees a clear
+            # failure (matching the pre-refactor behavior where
+            # json.loads would fail on the canned "UNKNOWN" content).
+            if schema_class is _ExtractionResult:
+                return _ExtractionResult()
+            raise RuntimeError(
+                f"test mock has no default for {schema_class.__name__}; "
+                "override session._llm.generate_object in this test"
+            )
+
+        from anton.core.llm.provider import ProviderConnectionInfo
         mock_llm = AsyncMock()
         plan_response = MagicMock()
         plan_response.content = "UNKNOWN"
         mock_llm.plan = AsyncMock(return_value=plan_response)
-        session = ChatSession(mock_llm)
+        mock_llm.generate_object = AsyncMock(side_effect=_default_generate_object)
+        mock_llm.coding_provider = MagicMock()
+        mock_llm.coding_provider.export_connection_info = MagicMock(
+            return_value=ProviderConnectionInfo(provider="anthropic", api_key="test")
+        )
+        mock_llm.coding_model = "claude-sonnet-4-6"
+        session = ChatSession(ChatSessionConfig(llm_client=mock_llm))
         session._scratchpads = AsyncMock()
         return session
 
@@ -573,30 +602,31 @@ async def test_unknown_engine_returns_early(
         console = MagicMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=DataVault(vault_dir=vault_dir)),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", return_value="MySQL"),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=LocalDataVault(vault_dir=vault_dir)),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.prompt_or_cancel", return_value="MySQL"),
+            patch("anton.commands.datasource.custom.prompt_or_cancel", return_value="MySQL"),
         ):
             result = await handle_connect_datasource(
                 console, session._scratchpads, session
             )
 
         assert result is session
-        assert DataVault(vault_dir=vault_dir).list_connections() == []
+        assert LocalDataVault(vault_dir=vault_dir).list_connections() == []
 
     @pytest.mark.asyncio
-    async def test_partial_save_on_n_answer(self, registry, vault_dir, make_session):
-        """Answering 'n' saves partial credentials and returns without testing."""
+    async def test_partial_save_on_skip(self, registry, vault_dir, make_session):
+        """Answering 'skip' at the bulk prompt saves partial credentials and returns without testing."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
-        responses = iter(["PostgreSQL", "n", "n", "db.example.com", "", "", "", "", ""])
+        vault = LocalDataVault(vault_dir=vault_dir)
+        responses = iter(["PostgreSQL", "n", "skip"])
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -618,7 +648,7 @@ async def test_successful_connection_saves_and_injects_history(
         """Happy path: test passes, credentials saved, history entry added."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad()
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
@@ -627,21 +657,19 @@ async def test_successful_connection_saves_and_injects_history(
             [
                 "PostgreSQL",
                 "n",
-                "y",
                 "db.example.com",
                 "5432",
                 "prod_db",
                 "alice",
                 "s3cr3t",
-                "",
             ]
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -660,6 +688,246 @@ async def test_successful_connection_saves_and_injects_history(
         assert last["role"] == "assistant"
         assert "postgresql" in last["content"].lower()
 
+    @pytest.mark.asyncio
+    async def test_test_failed_decline_sets_status(
+        self, registry, vault_dir, make_session, make_cell, make_pad
+    ):
+        """When the connection test fails and the user declines to
+        re-enter credentials, the handler should set
+        session._pending_connect_status = 'test_failed' so the tool
+        wrapper can return an accurate (non-misleading) message to the
+        LLM instead of claiming the user pressed Escape.
+        """
+        session = make_session()
+        console = MagicMock()
+        vault = LocalDataVault(vault_dir=vault_dir)
+
+        pad = make_pad(make_cell(stdout="", error="connection refused"))
+        session._scratchpads.get_or_create = AsyncMock(return_value=pad)
+
+        # Engine pick + decline retry after the test fails
+        responses = iter(["PostgreSQL", "n"])
+        _responses_next = lambda *a, **kw: next(responses)
+
+        with (
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch(
+                "anton.commands.datasource.connect.prompt_or_cancel",
+                new=AsyncMock(side_effect=_responses_next),
+            ),
+            patch(
+                "anton.commands.datasource.verify.prompt_or_cancel",
+                new=AsyncMock(side_effect=_responses_next),
+            ),
+        ):
+            await handle_connect_datasource(
+                console,
+                session._scratchpads,
+                session,
+                known_variables={
+                    "host": "db.example.com",
+                    "port": "5432",
+                    "database": "prod_db",
+                    "user": "alice",
+                    "password": "wrong",
+                },
+            )
+
+        # Connection NOT saved
+        assert vault.list_connections() == []
+        # Status correctly marked as test_failed (not "escaped")
+        assert getattr(session, "_pending_connect_status", None) == "test_failed"
+
+    @pytest.mark.asyncio
+    async def test_fully_prefilled_known_variables_skips_help_prompt(
+        self, registry, vault_dir, make_session, make_cell, make_pad
+    ):
+        """When known_variables covers every required field, skip the
+        'Do you need instructions?' prompt entirely and go straight to
+        test + save. The user has already provided everything.
+        """
+        session = make_session()
+        console = MagicMock()
+        vault = LocalDataVault(vault_dir=vault_dir)
+
+        pad = make_pad()
+        session._scratchpads.get_or_create = AsyncMock(return_value=pad)
+
+        # Only the engine selection prompt should fire. After that, the
+        # collector is already complete and the flow proceeds directly
+        # to the connection test.
+        responses = iter(["PostgreSQL"])
+
+        with (
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch(
+                "anton.commands.datasource.connect.prompt_or_cancel",
+                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
+            ),
+        ):
+            await handle_connect_datasource(
+                console,
+                session._scratchpads,
+                session,
+                known_variables={
+                    "host": "db.example.com",
+                    "port": "5432",
+                    "database": "prod_db",
+                    "user": "alice",
+                    "password": "s3cr3t",
+                },
+            )
+
+        conns = vault.list_connections()
+        assert len(conns) == 1
+        saved = vault.load("postgresql", conns[0]["name"])
+        assert saved is not None
+        assert saved["host"] == "db.example.com"
+        assert saved["port"] == "5432"
+        assert saved["database"] == "prod_db"
+        assert saved["user"] == "alice"
+        assert saved["password"] == "s3cr3t"
+
+    @pytest.mark.asyncio
+    async def test_credentials_pasted_at_help_prompt(
+        self, registry, vault_dir, make_session, make_cell, make_pad
+    ):
+        """Pasting credentials at the 'Do you need instructions?' prompt
+        should extract them instead of forcing a re-prompt or re-asking
+        for every field.
+        """
+        session = make_session()
+        console = MagicMock()
+        vault = LocalDataVault(vault_dir=vault_dir)
+
+        # Mock the LLM to return a structured extraction for the paste.
+        # connect_collector.extract_variables now uses generate_object
+        # with a Pydantic schema, so the mock returns the typed object.
+        from anton.connect_collector import _ExtractionResult
+        extract_response = _ExtractionResult(
+            variables={
+                "host": "db.example.com",
+                "port": "5432",
+                "database": "prod_db",
+                "user": "alice",
+                "password": "s3cr3t",
+            },
+            is_redirect=False,
+            redirect_engine="",
+            redirect_reason="",
+        )
+        session._llm.generate_object = AsyncMock(return_value=extract_response)
+
+        pad = make_pad()
+        session._scratchpads.get_or_create = AsyncMock(return_value=pad)
+
+        pasted = (
+            "host: db.example.com\n"
+            "port: 5432\n"
+            "database: prod_db\n"
+            "user: alice\n"
+            "password: s3cr3t"
+        )
+        # Only two user inputs needed: the engine pick, then the paste
+        # at the help prompt. The collector becomes complete immediately
+        # after extraction, so no further prompts are issued.
+        responses = iter(["PostgreSQL", pasted])
+
+        with (
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch(
+                "anton.commands.datasource.connect.prompt_or_cancel",
+                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
+            ),
+        ):
+            await handle_connect_datasource(console, session._scratchpads, session)
+
+        conns = vault.list_connections()
+        assert len(conns) == 1
+        saved = vault.load("postgresql", conns[0]["name"])
+        assert saved is not None
+        assert saved["host"] == "db.example.com"
+        assert saved["port"] == "5432"
+        assert saved["database"] == "prod_db"
+        assert saved["user"] == "alice"
+        assert saved["password"] == "s3cr3t"
+
+    @pytest.mark.asyncio
+    async def test_from_tool_call_does_not_append_to_history(
+        self, registry, vault_dir, make_session, make_cell, make_pad
+    ):
+        """With from_tool_call=True the handler must NOT mutate session._history.
+
+        If it did, the appended assistant message would land between the
+        surrounding tool_use and tool_result blocks, violating the
+        Anthropic API invariant and producing a 400 error on the next
+        LLM call ("tool_use ids were found without tool_result blocks").
+        """
+        session = make_session()
+        # Simulate being mid-tool-call: history already contains an
+        # assistant message with a tool_use that needs a tool_result next.
+        session._history = [
+            {"role": "user", "content": "connect to postgres"},
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "Let me connect you."},
+                    {
+                        "type": "tool_use",
+                        "id": "toolu_test_123",
+                        "name": "connect_new_datasource",
+                        "input": {"engine": "postgres"},
+                    },
+                ],
+            },
+        ]
+        history_len_before = len(session._history)
+
+        console = MagicMock()
+        vault = LocalDataVault(vault_dir=vault_dir)
+        pad = make_pad()
+        session._scratchpads.get_or_create = AsyncMock(return_value=pad)
+
+        responses = iter(
+            [
+                "PostgreSQL",
+                "n",
+                "db.example.com",
+                "5432",
+                "prod_db",
+                "alice",
+                "s3cr3t",
+            ]
+        )
+
+        with (
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch(
+                "anton.commands.datasource.connect.prompt_or_cancel",
+                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
+            ),
+        ):
+            await handle_connect_datasource(
+                console,
+                session._scratchpads,
+                session,
+                from_tool_call=True,
+            )
+
+        # Connection saved successfully...
+        conns = vault.list_connections()
+        assert len(conns) == 1
+        # ...but history MUST be untouched (the tool wrapper appends
+        # the tool_result separately after this returns).
+        assert len(session._history) == history_len_before
+        assert session._history[-1]["role"] == "assistant"
+        assert isinstance(session._history[-1]["content"], list)
+        assert session._history[-1]["content"][-1]["type"] == "tool_use"
+
     @pytest.mark.asyncio
     async def test_failed_test_offers_retry(
         self, registry, vault_dir, make_session, make_cell, make_pad
@@ -667,7 +935,7 @@ async def test_failed_test_offers_retry(
         """Connection test failure prompts for retry; success on second attempt saves."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad(side_effect=[
             make_cell(stdout="", stderr="password authentication failed"),
@@ -679,23 +947,25 @@ async def test_failed_test_offers_retry(
             [
                 "PostgreSQL",
                 "n",
-                "y",
                 "db.example.com",
                 "5432",
                 "prod_db",
                 "alice",
                 "wrongpassword",
-                "",
                 "y",
                 "correctpassword",
             ]
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch(
+                "anton.commands.datasource.connect.prompt_or_cancel",
+                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
+            ),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.verify.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -714,7 +984,7 @@ async def test_failed_test_no_retry_returns_without_saving(
         """Declining retry on failed test leaves vault empty."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad(make_cell(stdout="", error="connection refused"))
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
@@ -723,22 +993,24 @@ async def test_failed_test_no_retry_returns_without_saving(
             [
                 "PostgreSQL",
                 "n",
-                "y",
                 "db.example.com",
                 "5432",
                 "prod_db",
                 "alice",
                 "badpass",
-                "",
                 "n",
             ]
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch(
+                "anton.commands.datasource.connect.prompt_or_cancel",
+                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
+            ),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.verify.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -756,7 +1028,7 @@ async def test_ds_env_injected_after_successful_connect(
         """After a successful connect, namespaced DS_* vars are injected."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad()
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
@@ -765,21 +1037,19 @@ async def test_ds_env_injected_after_successful_connect(
             [
                 "PostgreSQL",
                 "n",
-                "y",
                 "db.example.com",
                 "5432",
                 "prod_db",
                 "alice",
                 "s3cr3t",
-                "",
             ]
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -795,18 +1065,18 @@ async def test_auth_method_choice_selects_fields(
         """Selecting an auth method filters to that method's fields only."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad()
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
 
-        responses = iter(["HubSpot", "1", "n", "y", "pat-na1-abc123"])
+        responses = iter(["HubSpot", "1", "n", "pat-na1-abc123"])
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -822,13 +1092,29 @@ async def test_auth_method_choice_selects_fields(
         assert "client_secret" not in saved
 
     @pytest.mark.asyncio
-    async def test_selective_field_collection(
+    async def test_bulk_key_value_extraction(
         self, registry, vault_dir, make_session, make_cell, make_pad
     ):
-        """Typing 'host,user,password' collects only those three fields."""
+        """A single bulk response with key=value pairs fills multiple fields at once."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
+
+        # Mock the LLM extraction to return a typed Pydantic result
+        # (connect_collector now uses generate_object with a schema).
+        from anton.connect_collector import _ExtractionResult
+        bulk_response = _ExtractionResult(
+            variables={
+                "host": "db.example.com",
+                "port": "5432",
+                "database": "prod_db",
+                "user": "alice",
+            },
+            is_redirect=False,
+            redirect_engine="",
+            redirect_reason="",
+        )
+        session._llm.generate_object = AsyncMock(return_value=bulk_response)
 
         pad = make_pad()
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
@@ -837,18 +1123,16 @@ async def test_selective_field_collection(
             [
                 "PostgreSQL",
                 "n",
-                "host,user,password",
-                "db.example.com",
-                "alice",
-                "s3cr3t",
+                "host=db.example.com port=5432 database=prod_db user=alice",
+                "s3cr3t",  # only password remains → single-field prompt
             ]
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -858,7 +1142,11 @@ async def test_selective_field_collection(
         assert len(conns) == 1
         saved = vault.load("postgresql", conns[0]["name"])
         assert saved is not None
-        assert set(saved.keys()) == {"host", "user", "password"}
+        assert saved["host"] == "db.example.com"
+        assert saved["port"] == "5432"
+        assert saved["database"] == "prod_db"
+        assert saved["user"] == "alice"
+        assert saved["password"] == "s3cr3t"
 
 
 class TestCredentialScrubbing:
@@ -913,7 +1201,7 @@ async def test_register_and_scrub_on_connect(
         self, registry, vault_dir, monkeypatch, make_pad
     ):
         """After _handle_connect_datasource, the new secret var is immediately scrubbed."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         session = MagicMock()
         session._history = []
         session._cortex = None
@@ -926,21 +1214,19 @@ async def test_register_and_scrub_on_connect(
             [
                 "PostgreSQL",
                 "n",
-                "y",
                 "db.host.com",
                 "5432",
                 "mydb",
                 "alice",
                 secret_pw,
-                "public",
             ]
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -994,15 +1280,15 @@ def test_active_datasource_defaults_to_none(self, make_session):
     @pytest.mark.asyncio
     async def test_reconnect_sets_active_datasource(self, vault_dir, make_session):
         """Reconnecting to a slug via prefill sets session._active_datasource."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("hubspot", "2", {"access_token": "pat-xxx"})
 
         session = make_session()
         console = MagicMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry"),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry"),
         ):
             result = await handle_connect_datasource(
                 console, session._scratchpads, session, prefill="hubspot-2"
@@ -1015,7 +1301,7 @@ async def test_reconnect_all_namespaced_vars_available(
         self, vault_dir, make_session
     ):
         """After reconnect, ALL saved connections remain available as namespaced vars."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "oracle",
             "1",
@@ -1032,8 +1318,8 @@ async def test_reconnect_all_namespaced_vars_available(
         console = MagicMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry"),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry"),
         ):
             result = await handle_connect_datasource(
                 console, session._scratchpads, session, prefill="hubspot-2"
@@ -1047,69 +1333,63 @@ async def test_reconnect_all_namespaced_vars_available(
 
     def test_build_datasource_context_no_filter(self, vault_dir):
         """Without active_only, all vault entries appear in the context."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("oracle", "1", {"host": "oracle.host"})
         vault.save("hubspot", "2", {"access_token": "pat-xxx"})
 
-        with patch("anton.utils.datasources.DataVault", return_value=vault):
-            ctx = build_datasource_context()
+        ctx = build_datasource_context(vault)
 
         assert "oracle-1" in ctx
         assert "hubspot-2" in ctx
 
     def test_build_datasource_context_active_only_filters(self, vault_dir):
         """With active_only set, only the matching slug appears."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("oracle", "1", {"host": "oracle.host"})
         vault.save("hubspot", "2", {"access_token": "pat-xxx"})
 
-        with patch("anton.utils.datasources.DataVault", return_value=vault):
-            ctx = build_datasource_context(active_only="hubspot-2")
+        ctx = build_datasource_context(vault, active_only="hubspot-2")
 
         assert "hubspot-2" in ctx
         assert "oracle-1" not in ctx
 
     def test_build_datasource_context_active_only_empty_when_no_match(self, vault_dir):
         """If active_only doesn't match any slug, the section has no entries."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("oracle", "1", {"host": "oracle.host"})
 
-        with patch("anton.utils.datasources.DataVault", return_value=vault):
-            ctx = build_datasource_context(active_only="hubspot-99")
+        ctx = build_datasource_context(vault, active_only="hubspot-99")
 
         assert "oracle-1" not in ctx
 
     def test_build_datasource_context_shows_namespaced_vars(self, vault_dir):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgres", "prod_db", {"host": "pg.example.com", "password": "s3cr3t"}
         )
 
-        with patch("anton.utils.datasources.DataVault", return_value=vault):
-            ctx = build_datasource_context()
+        ctx = build_datasource_context(vault)
 
         assert "DS_POSTGRES_PROD_DB__HOST" in ctx
         assert "DS_POSTGRES_PROD_DB__PASSWORD" in ctx
         assert "DS_HOST" not in ctx
 
     def test_build_datasource_context_shows_slug_and_engine_label(self, vault_dir):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("postgres", "prod_db", {"host": "pg.example.com"})
 
-        with patch("anton.utils.datasources.DataVault", return_value=vault):
-            ctx = build_datasource_context()
+        ctx = build_datasource_context(vault)
 
         assert "postgres-prod_db" in ctx
         assert "(postgres)" in ctx
 
     def test_multi_source_context_shows_both_connections(self, vault_dir):
         """Both connections are visible in the context with their namespaced vars."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("postgres", "prod_db", {"host": "pg.example.com"})
         vault.save("hubspot", "main", {"access_token": "pat-abc"})
 
-        with patch("anton.utils.datasources.DataVault", return_value=vault):
-            ctx = build_datasource_context()
+        ctx = build_datasource_context(vault)
 
         assert "postgres-prod_db" in ctx
         assert "DS_POSTGRES_PROD_DB__HOST" in ctx
@@ -1136,15 +1416,14 @@ def test_command_registered(self, cmd_name):
 class TestHandleListDataSources:
     def test_empty_vault_shows_message(self, vault_dir):
         console = MagicMock()
-        with patch("anton.commands.datasource.DataVault", return_value=DataVault(vault_dir=vault_dir)):
-            handle_list_data_sources(console)
+        handle_list_data_sources(console, vault=LocalDataVault(vault_dir=vault_dir))
         printed = " ".join(str(c) for c in console.print.call_args_list)
         assert "No data sources" in printed or "connect" in printed
 
     def test_complete_connection_shows_saved_with_engine_name(
         self, vault_dir, registry
     ):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1160,11 +1439,8 @@ def test_complete_connection_shows_saved_with_engine_name(
         buf = io.StringIO()
         rich_console = Console(file=buf, highlight=False, markup=False)
 
-        with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-        ):
-            handle_list_data_sources(rich_console)
+        with patch("anton.commands.datasource.manage.DatasourceRegistry", return_value=registry):
+            handle_list_data_sources(rich_console, vault=vault)
 
         output = buf.getvalue()
         assert "postgresql-prod_db" in output
@@ -1172,18 +1448,15 @@ def test_complete_connection_shows_saved_with_engine_name(
         assert "PostgreSQL" in output  # engine display_name shown
 
     def test_incomplete_connection_shows_incomplete(self, vault_dir, registry):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         # Missing required fields: database, user, password
         vault.save("postgresql", "partial", {"host": "db.example.com"})
 
         buf = io.StringIO()
         rich_console = Console(file=buf, highlight=False, markup=False)
 
-        with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-        ):
-            handle_list_data_sources(rich_console)
+        with patch("anton.commands.datasource.manage.DatasourceRegistry", return_value=registry):
+            handle_list_data_sources(rich_console, vault=vault)
 
         output = buf.getvalue()
         assert "incomplete" in output.lower()
@@ -1192,7 +1465,7 @@ def test_incomplete_connection_shows_incomplete(self, vault_dir, registry):
 class TestHandleTestDatasource:
     @pytest.mark.asyncio
     async def test_success_path(self, vault_dir, registry, make_cell, make_pad):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1209,18 +1482,15 @@ async def test_success_path(self, vault_dir, registry, make_cell, make_pad):
         scratchpads = AsyncMock()
         scratchpads.get_or_create = AsyncMock(return_value=pad)
 
-        with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-        ):
-            await handle_test_datasource(console, scratchpads, "postgresql-prod_db")
+        with patch("anton.commands.datasource.verify.DatasourceRegistry", return_value=registry):
+            await handle_test_datasource(console, scratchpads, "postgresql-prod_db", vault=vault)
 
         printed = " ".join(str(c) for c in console.print.call_args_list)
         assert "✓" in printed or "passed" in printed.lower()
 
     @pytest.mark.asyncio
     async def test_failure_path(self, vault_dir, registry, make_cell, make_pad):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1237,26 +1507,20 @@ async def test_failure_path(self, vault_dir, registry, make_cell, make_pad):
         scratchpads = AsyncMock()
         scratchpads.get_or_create = AsyncMock(return_value=pad)
 
-        with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-        ):
-            await handle_test_datasource(console, scratchpads, "postgresql-prod_db")
+        with patch("anton.commands.datasource.verify.DatasourceRegistry", return_value=registry):
+            await handle_test_datasource(console, scratchpads, "postgresql-prod_db", vault=vault)
 
         printed = " ".join(str(c) for c in console.print.call_args_list)
         assert "✗" in printed or "failed" in printed.lower()
 
     @pytest.mark.asyncio
     async def test_unknown_connection(self, vault_dir, registry):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         console = MagicMock()
         scratchpads = AsyncMock()
 
-        with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-        ):
-            await handle_test_datasource(console, scratchpads, "postgresql-ghost")
+        with patch("anton.commands.datasource.verify.DatasourceRegistry", return_value=registry):
+            await handle_test_datasource(console, scratchpads, "postgresql-ghost", vault=vault)
 
         printed = " ".join(str(c) for c in console.print.call_args_list)
         assert "not found" in printed.lower() or "No connection" in printed
@@ -1266,11 +1530,7 @@ async def test_empty_slug_shows_usage(self, vault_dir, registry):
         console = MagicMock()
         scratchpads = AsyncMock()
 
-        with (
-            patch("anton.commands.datasource.DataVault", return_value=DataVault(vault_dir=vault_dir)),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-        ):
-            await handle_test_datasource(console, scratchpads, "")
+        await handle_test_datasource(console, scratchpads, "", vault=LocalDataVault(vault_dir=vault_dir))
 
         printed = " ".join(str(c) for c in console.print.call_args_list)
         assert "Usage" in printed or "test" in printed
@@ -1282,7 +1542,7 @@ async def test_existing_values_loaded(
         self, registry, vault_dir, make_session, make_cell, make_pad
     ):
         """Edit shows existing non-secret values as defaults."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1312,10 +1572,10 @@ async def test_existing_values_loaded(
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(prompt_values)),
             ),
         ):
@@ -1336,7 +1596,7 @@ async def test_enter_preserves_secret_value(
         self, registry, vault_dir, make_session, make_cell, make_pad
     ):
         """Pressing Enter on a secret field keeps the existing value."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         original_pass = "original_secret_pass"
         vault.save(
             "postgresql",
@@ -1367,10 +1627,10 @@ async def test_enter_preserves_secret_value(
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(prompt_values)),
             ),
         ):
@@ -1390,13 +1650,13 @@ async def test_unknown_slug_returns_session(
         self, registry, vault_dir, make_session
     ):
         """Editing a non-existent slug returns the session unchanged."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         session = make_session()
         console = MagicMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
         ):
             result = await handle_connect_datasource(
                 console,
@@ -1417,11 +1677,10 @@ async def test_confirmation_yes_deletes(self, vault, registry):
         console = Console(quiet=True)
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", new=AsyncMock(return_value="y")),
+            patch("anton.commands.datasource.manage.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.manage.prompt_or_cancel", new=AsyncMock(return_value="y")),
         ):
-            await handle_remove_data_source(console, "postgresql-prod_db")
+            await handle_remove_data_source(console, "postgresql-prod_db", vault=vault)
 
         assert vault.load("postgresql", "prod_db") is None
 
@@ -1431,34 +1690,32 @@ async def test_confirmation_no_preserves(self, vault, registry):
         console = Console(quiet=True)
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", new=AsyncMock(return_value="n")),
+            patch("anton.commands.datasource.manage.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.manage.prompt_or_cancel", new=AsyncMock(return_value="n")),
         ):
-            await handle_remove_data_source(console, "postgresql-prod_db")
+            await handle_remove_data_source(console, "postgresql-prod_db", vault=vault)
 
         assert vault.load("postgresql", "prod_db") is not None
 
     @pytest.mark.asyncio
     async def test_unknown_name_shows_message(self, vault_dir, registry):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         console = MagicMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.manage.DatasourceRegistry", return_value=registry),
         ):
-            await handle_remove_data_source(console, "postgresql-ghost")
+            await handle_remove_data_source(console, "postgresql-ghost", vault=vault)
 
         printed = " ".join(str(c) for c in console.print.call_args_list)
         assert "not found" in printed.lower() or "No connection" in printed
 
     @pytest.mark.asyncio
     async def test_invalid_format_shows_warning(self, vault_dir):
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         console = MagicMock()
 
-        with patch("anton.commands.datasource.DataVault", return_value=vault):
+        with patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault):
             await handle_remove_data_source(console, "nohyphen")
 
         printed = " ".join(str(c) for c in console.print.call_args_list)
@@ -1472,7 +1729,7 @@ async def test_connect_clears_previous_ds_vars(
     ):
         """After a successful new connect, stale DS_* vars are cleared."""
         monkeypatch.setenv("DS_ACCESS_TOKEN", "old-token")
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         session = make_session()
         console = MagicMock()
 
@@ -1483,21 +1740,19 @@ async def test_connect_clears_previous_ds_vars(
             [
                 "PostgreSQL",
                 "n",
-                "y",
                 "db.example.com",
                 "5432",
                 "prod_db",
                 "alice",
                 "s3cr3t",
-                "",
             ]
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
         ):
@@ -1511,7 +1766,7 @@ async def test_two_same_type_connections_no_collision(
         self, registry, vault_dir, make_session
     ):
         """Both same-type connections remain available as distinct namespaced vars."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "db1",
@@ -1539,8 +1794,8 @@ async def test_two_same_type_connections_no_collision(
         console = MagicMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
         ):
             await handle_connect_datasource(
                 console,
@@ -1562,8 +1817,8 @@ async def test_test_data_source_no_arg_shows_usage(self, vault_dir, registry):
         scratchpads = AsyncMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=DataVault(vault_dir=vault_dir)),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=LocalDataVault(vault_dir=vault_dir)),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
         ):
             await handle_test_datasource(console, scratchpads, "")
 
@@ -1579,9 +1834,10 @@ async def test_edit_data_source_no_arg_safe(
         console = MagicMock()
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=DataVault(vault_dir=vault_dir)),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", return_value="UnknownEngine"),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=LocalDataVault(vault_dir=vault_dir)),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.prompt_or_cancel", return_value="UnknownEngine"),
+            patch("anton.commands.datasource.custom.prompt_or_cancel", return_value="some description"),
         ):
             updated = await handle_connect_datasource(
                 console,
@@ -1627,7 +1883,7 @@ def test_slug_with_empty_name_part(self):
 
     def test_fallback_to_vault_for_custom_engine(self, tmp_path):
         """Custom engine not in registry is resolved via vault fallback."""
-        vault = DataVault(vault_dir=tmp_path / "vault")
+        vault = LocalDataVault(vault_dir=tmp_path / "vault")
         vault.save("my_custom_db", "prod", {"host": "localhost"})
         result = parse_connection_slug(
             "my_custom_db-prod",
@@ -1638,7 +1894,7 @@ def test_fallback_to_vault_for_custom_engine(self, tmp_path):
 
     def test_registry_match_takes_priority_over_vault(self, tmp_path):
         """Registry prefix match wins even when vault also has the slug."""
-        vault = DataVault(vault_dir=tmp_path / "vault")
+        vault = LocalDataVault(vault_dir=tmp_path / "vault")
         vault.save("postgresql", "prod", {"host": "localhost"})
         result = parse_connection_slug(
             "postgresql-prod",
@@ -1649,7 +1905,7 @@ def test_registry_match_takes_priority_over_vault(self, tmp_path):
 
     def test_no_match_returns_none_with_vault(self, tmp_path):
         """Truly unknown slug returns None even with vault supplied."""
-        vault = DataVault(vault_dir=tmp_path / "vault")
+        vault = LocalDataVault(vault_dir=tmp_path / "vault")
         result = parse_connection_slug(
             "ghost-engine-1",
             known_engines=["postgresql"],
@@ -1681,7 +1937,7 @@ class TestTemporaryFlatExecution:
 
     def test_restore_namespaced_env_clears_flat_and_reinjects(self, vault_dir):
         """_restore_namespaced_env replaces flat vars with namespaced vars."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("postgres", "analytics", {"host": "analytics.example.com"})
 
         vault.inject_env("postgres", "analytics", flat=True)
@@ -1696,7 +1952,7 @@ def test_restore_namespaced_env_clears_flat_and_reinjects(self, vault_dir):
 
     def test_restore_namespaced_env_reinjects_all_connections(self, vault_dir):
         """_restore_namespaced_env restores ALL saved connections, not just one."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("postgres", "prod_db", {"host": "prod.example.com"})
         vault.save("hubspot", "main", {"access_token": "pat-abc"})
 
@@ -1714,7 +1970,7 @@ async def test_test_datasource_injects_flat_then_restores_namespaced(
         self, vault_dir, registry, make_pad
     ):
         """handle_test_datasource uses flat vars during snippet, then restores namespaced."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1745,12 +2001,9 @@ async def capture_execute(snippet):
         scratchpads = AsyncMock()
         scratchpads.get_or_create = AsyncMock(return_value=pad)
 
-        with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-        ):
+        with patch("anton.commands.datasource.verify.DatasourceRegistry", return_value=registry):
             await handle_test_datasource(
-                MagicMock(), scratchpads, "postgresql-prod_db"
+                MagicMock(), scratchpads, "postgresql-prod_db", vault=vault
             )
 
         # During execution: flat var was set, namespaced was absent
@@ -1768,7 +2021,7 @@ class TestStaleDsRegistrationState:
 
     def test_remove_clears_stale_secret_vars(self, vault_dir, registry):
         """After removing a connection, its secret var names leave _DS_SECRET_VARS."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1801,7 +2054,7 @@ def test_remove_clears_stale_secret_vars(self, vault_dir, registry):
 
     def test_edit_connection_refreshes_secret_vars(self, vault_dir, registry):
         """Overwriting a connection via vault.save rebuilds registration without duplication."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1847,7 +2100,7 @@ def test_edit_connection_refreshes_secret_vars(self, vault_dir, registry):
 
     def test_reconnect_no_duplicate_secret_vars(self, vault_dir, registry):
         """Calling _restore_namespaced_env multiple times does not grow _DS_SECRET_VARS."""
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save(
             "postgresql",
             "prod_db",
@@ -1880,11 +2133,19 @@ def test_reconnect_no_duplicate_secret_vars(self, vault_dir, registry):
 class TestAddCustomDatasourceFlow:
     """Tests for _handle_add_custom_datasource field-collection logic."""
 
-    def _make_llm_response(self, fields: list[dict], display_name: str = "MyDB") -> str:
-        """Return a JSON string mimicking the LLM's plan() response."""
-        import json as _json
+    def _make_spec(self, fields: list[dict], display_name: str = "MyDB"):
+        """Return a _CustomDatasourceSpec instance mimicking the LLM's response."""
+        from anton.commands.datasource import (
+            _CustomDatasourceField,
+            _CustomDatasourceSpec,
+        )
 
-        return _json.dumps({"display_name": display_name, "pip": "", "fields": fields})
+        return _CustomDatasourceSpec(
+            display_name=display_name,
+            pip="",
+            test_snippet="",
+            fields=[_CustomDatasourceField(**f) for f in fields],
+        )
 
     def _make_registry(self, tmp_path):
         """Return a minimal registry mock that accepts any slug."""
@@ -1894,12 +2155,10 @@ def _make_registry(self, tmp_path):
         reg.get.return_value = None  # triggers inline fallback
         return reg
 
-    def _make_llm(self, json_text: str):
-        """Return an AsyncMock LLM whose plan() returns json_text."""
+    def _make_llm(self, spec):
+        """Return an AsyncMock LLM whose generate_object() returns the spec."""
         llm = AsyncMock()
-        response = MagicMock()
-        response.content = json_text
-        llm.plan = AsyncMock(return_value=response)
+        llm.generate_object = AsyncMock(return_value=spec)
         return llm
 
     def _mock_ds_path(self, mock_path_cls, tmp_path):
@@ -1913,7 +2172,7 @@ async def test_missing_required_non_secret_field_prompts_user(
         """Required non-secret field without inline value triggers Prompt.ask."""
         session = make_session()
         session._llm = self._make_llm(
-            self._make_llm_response(
+            self._make_spec(
                 [
                     {
                         "name": "host",
@@ -1932,10 +2191,10 @@ async def test_missing_required_non_secret_field_prompts_user(
 
         with (
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.custom.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
-            patch("anton.commands.datasource.Path") as mock_path_cls,
+            patch("anton.commands.datasource.custom.Path") as mock_path_cls,
         ):
             self._mock_ds_path(mock_path_cls, tmp_path)
             result = await handle_add_custom_datasource(
@@ -1953,7 +2212,7 @@ async def test_missing_required_secret_field_prompts_user(
         """Required secret field without inline value triggers password prompt."""
         session = make_session()
         session._llm = self._make_llm(
-            self._make_llm_response(
+            self._make_spec(
                 [
                     {
                         "name": "api_key",
@@ -1972,10 +2231,10 @@ async def test_missing_required_secret_field_prompts_user(
 
         with (
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.custom.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
-            patch("anton.commands.datasource.Path") as mock_path_cls,
+            patch("anton.commands.datasource.custom.Path") as mock_path_cls,
         ):
             self._mock_ds_path(mock_path_cls, tmp_path)
             result = await handle_add_custom_datasource(
@@ -1991,7 +2250,7 @@ async def test_incomplete_custom_datasource_not_saved(self, tmp_path, make_sessi
         """Empty responses for all required fields causes a hard stop (None)."""
         session = make_session()
         session._llm = self._make_llm(
-            self._make_llm_response(
+            self._make_spec(
                 [
                     {
                         "name": "host",
@@ -2017,10 +2276,10 @@ async def test_incomplete_custom_datasource_not_saved(self, tmp_path, make_sessi
 
         with (
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.custom.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
             ),
-            patch("anton.commands.datasource.Path") as mock_path_cls,
+            patch("anton.commands.datasource.custom.Path") as mock_path_cls,
         ):
             self._mock_ds_path(mock_path_cls, tmp_path)
             result = await handle_add_custom_datasource(
@@ -2037,21 +2296,22 @@ class TestCustomDatasourceConnectFlow:
 
     # ── helpers (mirrors TestAddCustomDatasourceFlow) ────────────────────
 
-    def _make_llm_response(
+    def _make_spec(
         self,
         fields: list[dict],
         display_name: str = "My API Service",
         test_snippet: str = "",
-    ) -> str:
-        import json as _json
+    ):
+        from anton.commands.datasource import (
+            _CustomDatasourceField,
+            _CustomDatasourceSpec,
+        )
 
-        return _json.dumps(
-            {
-                "display_name": display_name,
-                "pip": "",
-                "test_snippet": test_snippet,
-                "fields": fields,
-            }
+        return _CustomDatasourceSpec(
+            display_name=display_name,
+            pip="",
+            test_snippet=test_snippet,
+            fields=[_CustomDatasourceField(**f) for f in fields],
         )
 
     def _make_registry(self, tmp_path):
@@ -2064,11 +2324,9 @@ def _make_registry(self, tmp_path):
         reg.get.return_value = None  # triggers inline fallback engine_def
         return reg
 
-    def _make_llm(self, json_text: str):
+    def _make_llm(self, spec):
         llm = AsyncMock()
-        response = MagicMock()
-        response.content = json_text
-        llm.plan = AsyncMock(return_value=response)
+        llm.generate_object = AsyncMock(return_value=spec)
         return llm
 
     def _mock_ds_path(self, mock_path_cls, tmp_path):
@@ -2081,12 +2339,12 @@ async def test_custom_with_test_snippet_success(
         """Custom datasource with test_snippet: test passes → connection saved."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad()
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
         session._llm = self._make_llm(
-            self._make_llm_response(
+            self._make_spec(
                 [
                     {
                         "name": "api_key",
@@ -2104,17 +2362,16 @@ async def test_custom_with_test_snippet_success(
             ["0", "My API Service", "I have an API key", "n", "my_secret_key"]
         )
 
+        poc = AsyncMock(side_effect=lambda *a, **kw: next(responses))
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
             patch(
-                "anton.commands.datasource.DatasourceRegistry",
+                "anton.commands.datasource.connect.DatasourceRegistry",
                 return_value=self._make_registry(tmp_path),
             ),
-            patch(
-                "anton.commands.datasource.prompt_or_cancel",
-                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
-            ),
-            patch("anton.commands.datasource.Path") as mock_path_cls,
+            patch("anton.commands.datasource.connect.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.Path") as mock_path_cls,
         ):
             self._mock_ds_path(mock_path_cls, tmp_path)
             result = await handle_connect_datasource(
@@ -2137,12 +2394,12 @@ async def test_custom_with_test_snippet_fail_no_retry(
         """Custom datasource: test fails and user declines retry → not saved."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad(make_cell(stdout="", stderr="connection refused"))
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
         session._llm = self._make_llm(
-            self._make_llm_response(
+            self._make_spec(
                 [
                     {
                         "name": "api_key",
@@ -2160,17 +2417,17 @@ async def test_custom_with_test_snippet_fail_no_retry(
             ["0", "My API Service", "I have an API key", "n", "bad_key", "n"]
         )
 
+        poc = AsyncMock(side_effect=lambda *a, **kw: next(responses))
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
             patch(
-                "anton.commands.datasource.DatasourceRegistry",
+                "anton.commands.datasource.connect.DatasourceRegistry",
                 return_value=self._make_registry(tmp_path),
             ),
-            patch(
-                "anton.commands.datasource.prompt_or_cancel",
-                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
-            ),
-            patch("anton.commands.datasource.Path") as mock_path_cls,
+            patch("anton.commands.datasource.connect.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.verify.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.Path") as mock_path_cls,
         ):
             self._mock_ds_path(mock_path_cls, tmp_path)
             result = await handle_connect_datasource(
@@ -2187,7 +2444,7 @@ async def test_custom_with_test_snippet_fail_retry_success(
         """Custom datasource: test fails, user retries with corrected creds → saved."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad(side_effect=[
             make_cell(stdout="", stderr="invalid key"),
@@ -2195,7 +2452,7 @@ async def test_custom_with_test_snippet_fail_retry_success(
         ])
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
         session._llm = self._make_llm(
-            self._make_llm_response(
+            self._make_spec(
                 [
                     {
                         "name": "api_key",
@@ -2221,17 +2478,17 @@ async def test_custom_with_test_snippet_fail_retry_success(
             ]
         )
 
+        poc = AsyncMock(side_effect=lambda *a, **kw: next(responses))
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
             patch(
-                "anton.commands.datasource.DatasourceRegistry",
+                "anton.commands.datasource.connect.DatasourceRegistry",
                 return_value=self._make_registry(tmp_path),
             ),
-            patch(
-                "anton.commands.datasource.prompt_or_cancel",
-                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
-            ),
-            patch("anton.commands.datasource.Path") as mock_path_cls,
+            patch("anton.commands.datasource.connect.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.verify.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.Path") as mock_path_cls,
         ):
             self._mock_ds_path(mock_path_cls, tmp_path)
             result = await handle_connect_datasource(
@@ -2252,12 +2509,12 @@ async def test_custom_without_test_snippet_saves(
         """Custom datasource without test_snippet: saves directly, no scratchpad call."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad()
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
         session._llm = self._make_llm(
-            self._make_llm_response(
+            self._make_spec(
                 [
                     {
                         "name": "api_key",
@@ -2273,17 +2530,16 @@ async def test_custom_without_test_snippet_saves(
 
         responses = iter(["0", "My API Service", "I have an API key", "n", "my_key"])
 
+        poc = AsyncMock(side_effect=lambda *a, **kw: next(responses))
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
             patch(
-                "anton.commands.datasource.DatasourceRegistry",
+                "anton.commands.datasource.connect.DatasourceRegistry",
                 return_value=self._make_registry(tmp_path),
             ),
-            patch(
-                "anton.commands.datasource.prompt_or_cancel",
-                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
-            ),
-            patch("anton.commands.datasource.Path") as mock_path_cls,
+            patch("anton.commands.datasource.connect.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.custom.Path") as mock_path_cls,
         ):
             self._mock_ds_path(mock_path_cls, tmp_path)
             await handle_connect_datasource(console, session._scratchpads, session)
@@ -2313,7 +2569,7 @@ async def test_edit_failed_test_does_not_corrupt_vault(
         """edit with bad creds + test fails + user declines retry → original creds intact."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("postgresql", "prod_db", self.OLD_CREDS)
 
         pad = make_pad(make_cell(stdout="", stderr="connection refused"))
@@ -2324,13 +2580,12 @@ async def test_edit_failed_test_does_not_corrupt_vault(
             ["", "", "", "", "bad-pass", "", "n"]
         )  # field values, then retry?
 
+        poc = AsyncMock(side_effect=lambda *a, **kw: next(responses))
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch(
-                "anton.commands.datasource.prompt_or_cancel",
-                new=AsyncMock(side_effect=lambda *a, **kw: next(responses)),
-            ),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.prompt_or_cancel", new=poc),
+            patch("anton.commands.datasource.verify.prompt_or_cancel", new=poc),
         ):
             result = await handle_connect_datasource(
                 console,
@@ -2351,7 +2606,7 @@ async def test_edit_successful_test_persists_new_credentials(
         """edit with valid creds + test passes → new creds saved to vault."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
         vault.save("postgresql", "prod_db", self.OLD_CREDS)
 
         pad = make_pad()
@@ -2369,10 +2624,10 @@ async def test_edit_successful_test_persists_new_credentials(
         )
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(prompt_responses)),
             ),
         ):
@@ -2394,7 +2649,7 @@ async def test_connection_test_error_summary_uses_meaningful_line(
     ):
         """Error display shows last non-empty line (exception msg), not traceback header."""
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         traceback_text = (
             "Traceback (most recent call last):\n"
@@ -2421,9 +2676,9 @@ async def test_connection_test_error_summary_uses_meaningful_line(
         }
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", new=AsyncMock(return_value="n")),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.verify.prompt_or_cancel", new=AsyncMock(return_value="n")),
         ):
             result = await run_connection_test(
                 console,
@@ -2449,12 +2704,12 @@ async def test_esc_on_engine_selection_returns_session_unchanged(
         """Pressing Esc on the engine-selection prompt returns the session with no vault writes."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", new=AsyncMock(return_value=None)),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.prompt_or_cancel", new=AsyncMock(return_value=None)),
         ):
             result = await handle_connect_datasource(
                 console, session._scratchpads, session
@@ -2470,15 +2725,15 @@ async def test_esc_on_retry_does_not_save(
         """Pressing Esc at the retry prompt makes _run_connection_test return False."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         pad = make_pad(make_cell(stdout="", error="bad creds"))
         session._scratchpads.get_or_create = AsyncMock(return_value=pad)
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", new=AsyncMock(return_value=None)),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.verify.prompt_or_cancel", new=AsyncMock(return_value=None)),
         ):
             engine_def = registry.get("postgresql")
             credentials = {
@@ -2507,15 +2762,15 @@ async def test_esc_on_do_you_have_these_returns_session(
         """Pressing Esc after engine selection (on 'do you have these?') returns session."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         poc_calls = iter(["PostgreSQL", None])  # engine selected, then Esc
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
             patch(
-                "anton.commands.datasource.prompt_or_cancel",
+                "anton.commands.datasource.connect.prompt_or_cancel",
                 new=AsyncMock(side_effect=lambda *a, **kw: next(poc_calls)),
             ),
         ):
@@ -2533,7 +2788,7 @@ async def test_fuzzy_match_prompt_has_context_text(
         """The fuzzy-match confirmation prompt includes context text and uses (y/n)."""
         session = make_session()
         console = MagicMock()
-        vault = DataVault(vault_dir=vault_dir)
+        vault = LocalDataVault(vault_dir=vault_dir)
 
         captured_labels: list[str] = []
 
@@ -2542,9 +2797,9 @@ def _capture(label, **kw):
             return None  # Esc on every prompt to bail out
 
         with (
-            patch("anton.commands.datasource.DataVault", return_value=vault),
-            patch("anton.commands.datasource.DatasourceRegistry", return_value=registry),
-            patch("anton.commands.datasource.prompt_or_cancel", new=AsyncMock(side_effect=_capture)),
+            patch("anton.commands.datasource.connect.LocalDataVault", return_value=vault),
+            patch("anton.commands.datasource.connect.DatasourceRegistry", return_value=registry),
+            patch("anton.commands.datasource.connect.prompt_or_cancel", new=AsyncMock(side_effect=_capture)),
         ):
             # "PostgreeSQL" triggers fuzzy match against "PostgreSQL"
             await handle_connect_datasource(
@@ -2569,7 +2824,6 @@ def _capture(label, **kw):
             "(reconnect/cancel)",
             "(anton) Would you like to re-enter your credentials? (y/n)",
             "(anton) Use this datasource? (y/n)",
-            "(anton) Do you have these available? (y/n/<list params>)",
             "(anton) (reconnect/cancel)",
         ],
     )
diff --git a/tests/test_episodes.py b/tests/test_episodes.py
index c4f4187d..977a45c7 100644
--- a/tests/test_episodes.py
+++ b/tests/test_episodes.py
@@ -9,7 +9,7 @@
 
 import pytest
 
-from anton.memory.episodes import Episode, EpisodicMemory
+from anton.core.memory.episodes import Episode, EpisodicMemory
 
 
 @pytest.fixture()
diff --git a/tests/test_explainability.py b/tests/test_explainability.py
new file mode 100644
index 00000000..1897212b
--- /dev/null
+++ b/tests/test_explainability.py
@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock
+
+from anton.commands.ui import handle_explain
+from anton.explainability import ExplainabilityCollector, ExplainabilityStore
+
+
+def test_explainability_store_persists_latest_and_turn_file(tmp_path):
+    store = ExplainabilityStore(tmp_path)
+    collector = ExplainabilityCollector(store, turn=3, user_message="How did revenue change?")
+    collector.add_scratchpad_step("Query monthly revenue")
+    collector.add_query(
+        datasource="warehouse.orders",
+        sql="SELECT month, revenue FROM revenue_by_month",
+        engine="postgres",
+    )
+
+    record = collector.finalize("Revenue increased 12% month over month.")
+
+    latest = tmp_path / ".anton" / "explainability" / "latest.json"
+    turn_file = tmp_path / ".anton" / "explainability" / "turn-0003.json"
+
+    assert latest.is_file()
+    assert turn_file.is_file()
+
+    latest_payload = json.loads(latest.read_text())
+    assert latest_payload["turn"] == 3
+    assert latest_payload["sql_queries"][0]["datasource"] == "warehouse.orders"
+    assert "queried warehouse.orders" in latest_payload["summary"].lower()
+    assert record.summary == latest_payload["summary"]
+
+
+def test_explainability_sql_shape_includes_datasources_and_queries(tmp_path):
+    store = ExplainabilityStore(tmp_path)
+    collector = ExplainabilityCollector(store, turn=4, user_message="What was monthly revenue?")
+    collector.add_scratchpad_step("Query monthly revenue")
+    collector.add_query(
+        datasource="finance.monthly_revenue",
+        sql="SELECT month, revenue FROM monthly_revenue ORDER BY month DESC",
+        engine="snowflake",
+    )
+
+    record = collector.finalize("Revenue rose in March.")
+
+    assert record.data_sources == [{"name": "finance.monthly_revenue", "engine": "snowflake"}]
+    assert record.sql_queries == [
+        {
+            "datasource": "finance.monthly_revenue",
+            "sql": "SELECT month, revenue FROM monthly_revenue ORDER BY month DESC",
+            "engine": "snowflake",
+            "status": "ok",
+            "error_message": None,
+        }
+    ]
+    assert "sql statement" in record.summary.lower()
+
+
+def test_explainability_summary_without_queries_is_direct_answer(tmp_path):
+    store = ExplainabilityStore(tmp_path)
+    collector = ExplainabilityCollector(store, turn=1, user_message="What is Anton?")
+
+    record = collector.finalize("Anton is MindsDB's autonomous AI coworker.")
+
+    assert record.sql_queries == []
+    assert (
+        record.summary
+        == "I answered directly from the conversation context without querying a datasource or generating SQL."
+    )
+
+
+def test_explainability_extracts_non_sql_sources_from_text(tmp_path):
+    store = ExplainabilityStore(tmp_path)
+    collector = ExplainabilityCollector(store, turn=2, user_message="Compare green coffee prices")
+    collector.add_scratchpad_step("Fetch green coffee bean prices and compute roasting cost comparison")
+    collector.add_sources_from_text(
+        'See https://www.happymugcoffee.com/collections/green-coffee and https://burmancoffee.com/'
+    )
+
+    record = collector.finalize("Home roasting is much cheaper.")
+
+    source_names = {source["name"] for source in record.data_sources}
+    assert source_names == {"happymugcoffee.com", "burmancoffee.com"}
+    assert "gathered information from" in record.summary.lower()
+
+
+def test_handle_explain_prints_sections_for_latest_record(tmp_path):
+    store = ExplainabilityStore(tmp_path)
+    collector = ExplainabilityCollector(store, turn=5, user_message="What was revenue?")
+    collector.add_scratchpad_step("Query monthly revenue")
+    collector.add_query(
+        datasource="finance.monthly_revenue",
+        sql="SELECT month, revenue FROM monthly_revenue",
+        engine="postgres",
+    )
+    collector.finalize("Revenue rose.")
+
+    console = MagicMock()
+    handle_explain(console, tmp_path)
+
+    rendered = "\n".join(
+        str(call.args[0]) for call in console.print.call_args_list if call.args
+    )
+    assert "Explain This Answer" in rendered
+    assert "Summary" in rendered
+    assert "Data Sources Used" in rendered
+    assert "Generated SQL" in rendered
+    assert "finance.monthly_revenue" in rendered
+    assert "SELECT month, revenue FROM monthly_revenue" in rendered
+
+
+def test_explainability_infers_sql_and_datasource_from_scratchpad_code(tmp_path):
+    store = ExplainabilityStore(tmp_path)
+    collector = ExplainabilityCollector(store, turn=6, user_message="Average revenue")
+    collector.add_scratchpad_step("Average annual revenue over last 10 years in the dataset")
+    collector.add_inferred_queries_from_code(
+        """
+import os
+sql = \"\"\"
+SELECT EXTRACT(YEAR FROM sale_date) AS year, AVG(revenue) AS avg_revenue
+FROM sales
+GROUP BY 1
+ORDER BY 1
+\"\"\"
+host = os.environ["DS_POSTGRES_PROD_DB__HOST"]
+cur.execute(sql)
+"""
+    )
+
+    record = collector.finalize("Average revenue is stable.")
+
+    assert record.data_sources == [{"name": "postgres-prod-db", "engine": None}]
+    assert len(record.sql_queries) == 1
+    assert "SELECT EXTRACT(YEAR FROM sale_date)" in record.sql_queries[0]["sql"]
+    assert record.sql_queries[0]["datasource"] == "postgres-prod-db"
diff --git a/tests/test_hippocampus.py b/tests/test_hippocampus.py
index 169eb2c5..10241d10 100644
--- a/tests/test_hippocampus.py
+++ b/tests/test_hippocampus.py
@@ -4,7 +4,7 @@
 
 import pytest
 
-from anton.memory.hippocampus import Hippocampus
+from anton.core.memory.hippocampus import Hippocampus
 
 
 @pytest.fixture()
diff --git a/tests/test_llm_client_generate_object.py b/tests/test_llm_client_generate_object.py
new file mode 100644
index 00000000..5f7fc55b
--- /dev/null
+++ b/tests/test_llm_client_generate_object.py
@@ -0,0 +1,320 @@
+"""Tests for `LLMClient.generate_object` — structured output via forced tool_choice."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+from pydantic import BaseModel
+
+from anton.core.llm.client import LLMClient
+from anton.core.llm.provider import LLMProvider, LLMResponse, ToolCall, Usage
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Pydantic schemas used by the tests
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class SimpleAnswer(BaseModel):
+    answer: str
+    confidence: float
+
+
+class Lesson(BaseModel):
+    text: str
+    topic: str = "default"
+
+
+class LessonBatch(BaseModel):
+    lessons: list[Lesson]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fake provider that records calls and returns canned responses
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _FakePlanningProvider(LLMProvider):
+    """Captures `complete` arguments and returns a pre-built LLMResponse."""
+
+    def __init__(self, response: LLMResponse) -> None:
+        self.response = response
+        self.complete_mock = AsyncMock(return_value=response)
+
+    async def complete(self, **kwargs):  # type: ignore[override]
+        return await self.complete_mock(**kwargs)
+
+
+def _make_client(provider: _FakePlanningProvider) -> LLMClient:
+    """Build an LLMClient where the planning provider is our fake."""
+    return LLMClient(
+        planning_provider=provider,
+        planning_model="test-model",
+        coding_provider=provider,  # reuse — we don't exercise the coding path
+        coding_model="test-model",
+        max_tokens=8192,
+    )
+
+
+def _tool_call_response(tool_name: str, payload: dict) -> LLMResponse:
+    """Build an LLMResponse that looks like the LLM made a forced tool call."""
+    return LLMResponse(
+        content="",
+        tool_calls=[ToolCall(id="t1", name=tool_name, input=payload)],
+        usage=Usage(input_tokens=10, output_tokens=20),
+        stop_reason="tool_use",
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Single-model generation
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestSingleModel:
+    @pytest.mark.asyncio
+    async def test_returns_validated_instance(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response(
+                "SimpleAnswer", {"answer": "42", "confidence": 0.95}
+            )
+        )
+        client = _make_client(provider)
+
+        result = await client.generate_object(
+            SimpleAnswer,
+            system="be terse",
+            messages=[{"role": "user", "content": "what's the answer?"}],
+        )
+
+        assert isinstance(result, SimpleAnswer)
+        assert result.answer == "42"
+        assert result.confidence == 0.95
+
+    @pytest.mark.asyncio
+    async def test_forces_tool_choice(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response("SimpleAnswer", {"answer": "x", "confidence": 0.5})
+        )
+        client = _make_client(provider)
+
+        await client.generate_object(
+            SimpleAnswer,
+            system="x",
+            messages=[{"role": "user", "content": "y"}],
+        )
+
+        # Provider was called with tool_choice forcing the SimpleAnswer tool
+        provider.complete_mock.assert_awaited_once()
+        kwargs = provider.complete_mock.call_args.kwargs
+        assert kwargs["tool_choice"] == {"type": "tool", "name": "SimpleAnswer"}
+        # And the tool's schema came from the Pydantic model
+        assert len(kwargs["tools"]) == 1
+        tool = kwargs["tools"][0]
+        assert tool["name"] == "SimpleAnswer"
+        assert "input_schema" in tool
+        # The schema mentions both fields
+        schema_str = str(tool["input_schema"])
+        assert "answer" in schema_str
+        assert "confidence" in schema_str
+
+    @pytest.mark.asyncio
+    async def test_passes_system_and_messages_through(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response("SimpleAnswer", {"answer": "x", "confidence": 0.5})
+        )
+        client = _make_client(provider)
+
+        await client.generate_object(
+            SimpleAnswer,
+            system="custom system",
+            messages=[{"role": "user", "content": "custom user"}],
+        )
+
+        kwargs = provider.complete_mock.call_args.kwargs
+        assert kwargs["system"] == "custom system"
+        assert kwargs["messages"] == [{"role": "user", "content": "custom user"}]
+        assert kwargs["model"] == "test-model"
+
+    @pytest.mark.asyncio
+    async def test_invalid_payload_raises_validation_error(self):
+        # Provider returns a payload missing the required `confidence` field
+        provider = _FakePlanningProvider(
+            _tool_call_response("SimpleAnswer", {"answer": "x"})
+        )
+        client = _make_client(provider)
+
+        with pytest.raises(Exception) as exc_info:
+            await client.generate_object(
+                SimpleAnswer,
+                system="x",
+                messages=[{"role": "user", "content": "y"}],
+            )
+        # Pydantic raises ValidationError, which we want surfaced
+        assert "confidence" in str(exc_info.value).lower()
+
+    @pytest.mark.asyncio
+    async def test_no_tool_call_raises_value_error(self):
+        # Provider returns text-only response — no tool call at all
+        provider = _FakePlanningProvider(
+            LLMResponse(content="just text", tool_calls=[])
+        )
+        client = _make_client(provider)
+
+        with pytest.raises(ValueError, match="did not return a tool call"):
+            await client.generate_object(
+                SimpleAnswer,
+                system="x",
+                messages=[{"role": "user", "content": "y"}],
+            )
+
+    @pytest.mark.asyncio
+    async def test_max_tokens_uses_default_when_not_specified(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response("SimpleAnswer", {"answer": "x", "confidence": 0.5})
+        )
+        client = _make_client(provider)
+
+        await client.generate_object(
+            SimpleAnswer,
+            system="x",
+            messages=[{"role": "user", "content": "y"}],
+        )
+
+        kwargs = provider.complete_mock.call_args.kwargs
+        assert kwargs["max_tokens"] == 8192  # the client default
+
+    @pytest.mark.asyncio
+    async def test_max_tokens_override(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response("SimpleAnswer", {"answer": "x", "confidence": 0.5})
+        )
+        client = _make_client(provider)
+
+        await client.generate_object(
+            SimpleAnswer,
+            system="x",
+            messages=[{"role": "user", "content": "y"}],
+            max_tokens=512,
+        )
+
+        kwargs = provider.complete_mock.call_args.kwargs
+        assert kwargs["max_tokens"] == 512
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# list[Model] generation
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestListModel:
+    @pytest.mark.asyncio
+    async def test_returns_typed_list(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response(
+                "Lesson_array",
+                {
+                    "items": [
+                        {"text": "first lesson", "topic": "scratchpad"},
+                        {"text": "second lesson", "topic": "scratchpad"},
+                    ]
+                },
+            )
+        )
+        client = _make_client(provider)
+
+        result = await client.generate_object(
+            list[Lesson],
+            system="x",
+            messages=[{"role": "user", "content": "y"}],
+        )
+
+        assert isinstance(result, list)
+        assert len(result) == 2
+        assert all(isinstance(item, Lesson) for item in result)
+        assert result[0].text == "first lesson"
+        assert result[1].text == "second lesson"
+
+    @pytest.mark.asyncio
+    async def test_list_uses_array_tool_name(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response("Lesson_array", {"items": []})
+        )
+        client = _make_client(provider)
+
+        await client.generate_object(
+            list[Lesson],
+            system="x",
+            messages=[{"role": "user", "content": "y"}],
+        )
+
+        kwargs = provider.complete_mock.call_args.kwargs
+        assert kwargs["tool_choice"] == {"type": "tool", "name": "Lesson_array"}
+        assert kwargs["tools"][0]["name"] == "Lesson_array"
+
+    @pytest.mark.asyncio
+    async def test_empty_list_is_valid(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response("Lesson_array", {"items": []})
+        )
+        client = _make_client(provider)
+
+        result = await client.generate_object(
+            list[Lesson],
+            system="x",
+            messages=[{"role": "user", "content": "y"}],
+        )
+
+        assert result == []
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Nested model (BaseModel containing list[BaseModel]) — the cerebellum case
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestNestedModel:
+    @pytest.mark.asyncio
+    async def test_lesson_batch_round_trip(self):
+        """The shape the cerebellum will use: a wrapper model with a list."""
+        provider = _FakePlanningProvider(
+            _tool_call_response(
+                "LessonBatch",
+                {
+                    "lessons": [
+                        {
+                            "text": "Use low_memory=False with mixed dtypes.",
+                            "topic": "scratchpad",
+                        }
+                    ]
+                },
+            )
+        )
+        client = _make_client(provider)
+
+        result = await client.generate_object(
+            LessonBatch,
+            system="extract lessons",
+            messages=[{"role": "user", "content": "cell errored"}],
+        )
+
+        assert isinstance(result, LessonBatch)
+        assert len(result.lessons) == 1
+        assert isinstance(result.lessons[0], Lesson)
+        assert "low_memory" in result.lessons[0].text
+
+    @pytest.mark.asyncio
+    async def test_empty_lessons_list_is_valid(self):
+        provider = _FakePlanningProvider(
+            _tool_call_response("LessonBatch", {"lessons": []})
+        )
+        client = _make_client(provider)
+
+        result = await client.generate_object(
+            LessonBatch,
+            system="x",
+            messages=[{"role": "user", "content": "y"}],
+        )
+
+        assert result.lessons == []
diff --git a/tests/test_llm_structured_helper.py b/tests/test_llm_structured_helper.py
new file mode 100644
index 00000000..61549b81
--- /dev/null
+++ b/tests/test_llm_structured_helper.py
@@ -0,0 +1,256 @@
+"""Unit tests for `anton.core.llm.structured` — pure helper functions.
+
+These verify the schema-building and unwrapping logic in isolation,
+without going through any LLM call. Both `LLMClient.generate_object`
+and `_ScratchpadLLM.generate_object` delegate to these functions, so
+locking their contract here is the foundation for both call sites.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel, ValidationError
+
+from anton.core.llm.structured import (
+    build_structured_tool,
+    unwrap_structured_response,
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Pydantic schemas used by the tests
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class Answer(BaseModel):
+    text: str
+    confidence: float
+
+
+class Lesson(BaseModel):
+    text: str
+    topic: str = "default"
+
+
+class WrappedLessons(BaseModel):
+    """A wrapper model with a list field — the cerebellum's exact pattern."""
+
+    lessons: list[Lesson]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# build_structured_tool — single model
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestBuildStructuredToolSingle:
+    def test_returns_three_tuple(self):
+        result = build_structured_tool(Answer)
+        assert isinstance(result, tuple)
+        assert len(result) == 3
+
+    def test_tool_has_required_fields(self):
+        tool, _, _ = build_structured_tool(Answer)
+        assert "name" in tool
+        assert "description" in tool
+        assert "input_schema" in tool
+
+    def test_tool_name_is_class_name(self):
+        tool, _, _ = build_structured_tool(Answer)
+        assert tool["name"] == "Answer"
+
+    def test_input_schema_includes_field_names(self):
+        tool, _, _ = build_structured_tool(Answer)
+        schema_str = str(tool["input_schema"])
+        assert "text" in schema_str
+        assert "confidence" in schema_str
+
+    def test_validator_class_is_input_class(self):
+        _, validator_class, _ = build_structured_tool(Answer)
+        assert validator_class is Answer
+
+    def test_is_list_is_false_for_single_model(self):
+        _, _, is_list = build_structured_tool(Answer)
+        assert is_list is False
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# build_structured_tool — list[Model]
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestBuildStructuredToolList:
+    def test_tool_name_uses_array_suffix(self):
+        tool, _, _ = build_structured_tool(list[Lesson])
+        assert tool["name"] == "Lesson_array"
+
+    def test_validator_class_is_wrapper_not_inner(self):
+        _, validator_class, _ = build_structured_tool(list[Lesson])
+        # Wrapper is a synthetic class — it should NOT be Lesson itself
+        assert validator_class is not Lesson
+        # And it should have an `items` field
+        assert "items" in validator_class.model_fields
+
+    def test_is_list_is_true(self):
+        _, _, is_list = build_structured_tool(list[Lesson])
+        assert is_list is True
+
+    def test_input_schema_has_items_array(self):
+        tool, _, _ = build_structured_tool(list[Lesson])
+        schema_str = str(tool["input_schema"])
+        assert "items" in schema_str
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# build_structured_tool — wrapper model with list field (cerebellum pattern)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestBuildStructuredToolWrapper:
+    def test_wrapper_treated_as_single_model(self):
+        tool, validator_class, is_list = build_structured_tool(WrappedLessons)
+        # WrappedLessons IS a BaseModel that happens to contain a list,
+        # but the helper should treat it as a single model (not list[T])
+        # because the input wasn't a list[X] annotation.
+        assert is_list is False
+        assert validator_class is WrappedLessons
+        assert tool["name"] == "WrappedLessons"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# unwrap_structured_response — single model
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestUnwrapSingleModel:
+    def test_valid_payload_returns_instance(self):
+        _, validator_class, is_list = build_structured_tool(Answer)
+        result = unwrap_structured_response(
+            {"text": "42", "confidence": 0.95},
+            validator_class,
+            is_list,
+        )
+        assert isinstance(result, Answer)
+        assert result.text == "42"
+        assert result.confidence == 0.95
+
+    def test_missing_required_field_raises(self):
+        _, validator_class, is_list = build_structured_tool(Answer)
+        with pytest.raises(ValidationError) as exc_info:
+            unwrap_structured_response(
+                {"text": "no confidence here"}, validator_class, is_list
+            )
+        assert "confidence" in str(exc_info.value).lower()
+
+    def test_wrong_type_raises(self):
+        _, validator_class, is_list = build_structured_tool(Answer)
+        with pytest.raises(ValidationError):
+            unwrap_structured_response(
+                {"text": "x", "confidence": "not a number"},
+                validator_class,
+                is_list,
+            )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# unwrap_structured_response — list[Model]
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestUnwrapList:
+    def test_valid_list_returns_typed_items(self):
+        _, validator_class, is_list = build_structured_tool(list[Lesson])
+        result = unwrap_structured_response(
+            {
+                "items": [
+                    {"text": "first", "topic": "scratchpad"},
+                    {"text": "second", "topic": "default"},
+                ]
+            },
+            validator_class,
+            is_list,
+        )
+        assert isinstance(result, list)
+        assert len(result) == 2
+        assert all(isinstance(item, Lesson) for item in result)
+        assert result[0].text == "first"
+        assert result[1].topic == "default"
+
+    def test_empty_list_returns_empty(self):
+        _, validator_class, is_list = build_structured_tool(list[Lesson])
+        result = unwrap_structured_response(
+            {"items": []}, validator_class, is_list
+        )
+        assert result == []
+
+    def test_missing_items_field_raises(self):
+        _, validator_class, is_list = build_structured_tool(list[Lesson])
+        with pytest.raises(ValidationError):
+            unwrap_structured_response({}, validator_class, is_list)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# unwrap_structured_response — wrapper model with list (cerebellum pattern)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestUnwrapWrapperModel:
+    def test_round_trip(self):
+        _, validator_class, is_list = build_structured_tool(WrappedLessons)
+        result = unwrap_structured_response(
+            {
+                "lessons": [
+                    {"text": "lesson 1", "topic": "scratchpad"},
+                    {"text": "lesson 2", "topic": "scratchpad"},
+                ]
+            },
+            validator_class,
+            is_list,
+        )
+        # Returns the wrapper instance, NOT the items list (because the
+        # original input wasn't a list[T] annotation — it was the
+        # wrapper class directly)
+        assert isinstance(result, WrappedLessons)
+        assert len(result.lessons) == 2
+        assert result.lessons[0].text == "lesson 1"
+
+    def test_empty_lessons_list_is_valid(self):
+        _, validator_class, is_list = build_structured_tool(WrappedLessons)
+        result = unwrap_structured_response(
+            {"lessons": []}, validator_class, is_list
+        )
+        assert isinstance(result, WrappedLessons)
+        assert result.lessons == []
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Round-trip — build then unwrap, mimicking the full flow
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestRoundTrip:
+    def test_single_model_round_trip(self):
+        tool, validator_class, is_list = build_structured_tool(Answer)
+        # Simulate the LLM calling the tool with this input
+        simulated_tool_input = {"text": "yes", "confidence": 0.7}
+        result = unwrap_structured_response(
+            simulated_tool_input, validator_class, is_list
+        )
+        assert result.text == "yes"
+        assert result.confidence == 0.7
+        # Sanity check the tool name was right
+        assert tool["name"] == "Answer"
+
+    def test_list_model_round_trip(self):
+        tool, validator_class, is_list = build_structured_tool(list[Lesson])
+        simulated = {
+            "items": [
+                {"text": "x", "topic": "a"},
+                {"text": "y", "topic": "b"},
+                {"text": "z", "topic": "c"},
+            ]
+        }
+        result = unwrap_structured_response(simulated, validator_class, is_list)
+        assert len(result) == 3
+        assert [l.text for l in result] == ["x", "y", "z"]
+        assert tool["name"] == "Lesson_array"
diff --git a/tests/test_openai_provider.py b/tests/test_openai_provider.py
index 1342ede7..51e42b4d 100644
--- a/tests/test_openai_provider.py
+++ b/tests/test_openai_provider.py
@@ -6,14 +6,14 @@
 import pytest
 
 from anton.config.settings import AntonSettings
-from anton.llm.client import LLMClient
-from anton.llm.openai import (
+from anton.core.llm.client import LLMClient
+from anton.core.llm.openai import (
     OpenAIProvider,
     build_chat_completion_kwargs,
     _translate_messages,
     _translate_tools,
 )
-from anton.llm.provider import LLMProvider
+from anton.core.llm.provider import LLMProvider
 
 
 def _make_mock_response(*, content="Hello", tool_calls=None, prompt_tokens=10, completion_tokens=20, finish_reason="stop"):
@@ -38,7 +38,7 @@ def _make_mock_response(*, content="Hello", tool_calls=None, prompt_tokens=10, c
 
 class TestOpenAIProvider:
     async def test_complete_text_response(self):
-        with patch("anton.llm.openai.openai") as mock_openai:
+        with patch("anton.core.llm.openai.openai") as mock_openai:
             mock_client = AsyncMock()
             mock_openai.AsyncOpenAI.return_value = mock_client
 
@@ -60,7 +60,7 @@ async def test_complete_text_response(self):
             assert result.stop_reason == "stop"
 
     async def test_complete_tool_use_response(self):
-        with patch("anton.llm.openai.openai") as mock_openai:
+        with patch("anton.core.llm.openai.openai") as mock_openai:
             mock_client = AsyncMock()
             mock_openai.AsyncOpenAI.return_value = mock_client
 
@@ -88,7 +88,7 @@ async def test_complete_tool_use_response(self):
             assert result.stop_reason == "tool_calls"
 
     async def test_complete_passes_tool_choice(self):
-        with patch("anton.llm.openai.openai") as mock_openai:
+        with patch("anton.core.llm.openai.openai") as mock_openai:
             mock_client = AsyncMock()
             mock_openai.AsyncOpenAI.return_value = mock_client
 
@@ -223,7 +223,7 @@ def test_translate_messages_with_tool_result(self):
 
 class TestFromSettingsOpenAI:
     def test_from_settings_openai(self):
-        with patch("anton.llm.openai.openai"):
+        with patch("anton.core.llm.openai.openai"):
             settings = AntonSettings(
                 planning_provider="openai",
                 coding_provider="openai",
diff --git a/tests/test_prompt_builder_skills.py b/tests/test_prompt_builder_skills.py
new file mode 100644
index 00000000..6796e16e
--- /dev/null
+++ b/tests/test_prompt_builder_skills.py
@@ -0,0 +1,143 @@
+"""Tests for the procedural-memory section in the chat system prompt."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from anton.core.llm.prompt_builder import ChatSystemPromptBuilder, SystemPromptContext
+from anton.core.memory.skills import Skill, SkillStore
+
+
+@pytest.fixture()
+def empty_store(tmp_path: Path) -> SkillStore:
+    return SkillStore(root=tmp_path / "skills_empty")
+
+
+@pytest.fixture()
+def populated_store(tmp_path: Path) -> SkillStore:
+    s = SkillStore(root=tmp_path / "skills_populated")
+    for label, when in [
+        ("csv_summary", "User asks to explore or summarize a CSV file."),
+        ("web_scraping", "User asks to scrape data from a website."),
+        ("api_fetcher", "User asks to fetch data from a JSON API."),
+    ]:
+        s.save(
+            Skill(
+                label=label,
+                name=label.replace("_", " ").title(),
+                description="",
+                when_to_use=when,
+                declarative_md="step 1\nstep 2",
+                created_at="2026-04-10T12:00:00+00:00",
+                provenance="manual",
+            )
+        )
+    return s
+
+
+def _build_prompt(builder: ChatSystemPromptBuilder, **overrides) -> str:
+    defaults = dict(
+        current_datetime="2026-04-10T12:00:00+00:00",
+        system_prompt_context=SystemPromptContext(runtime_context="test runtime"),
+        proactive_dashboards=False,
+    )
+    defaults.update(overrides)
+    return builder.build(**defaults)
+
+
+class TestProceduralMemorySection:
+    def test_no_store_omits_section(self):
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(builder, skill_store=None)
+        assert "Procedural memory" not in prompt
+
+    def test_empty_store_omits_section(self, empty_store: SkillStore):
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(builder, skill_store=empty_store)
+        assert "Procedural memory" not in prompt
+
+    def test_populated_store_renders_section(self, populated_store: SkillStore):
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(builder, skill_store=populated_store)
+        assert "## Procedural memory" in prompt
+        # All labels are listed
+        assert "`csv_summary`" in prompt
+        assert "`web_scraping`" in prompt
+        assert "`api_fetcher`" in prompt
+        # And their when_to_use
+        assert "explore or summarize a CSV" in prompt
+        assert "scrape data from a website" in prompt
+        assert "fetch data from a JSON API" in prompt
+
+    def test_section_mentions_recall_skill_tool(
+        self, populated_store: SkillStore
+    ):
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(builder, skill_store=populated_store)
+        # The section instructs the LLM how to use them
+        assert "recall_skill" in prompt
+
+    def test_section_appears_after_other_contexts(
+        self, populated_store: SkillStore
+    ):
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(
+            builder,
+            memory_context="\n\n## Memory context\nMEMORY HERE",
+            datasource_context="\n\n## Datasources\nDS HERE",
+            skill_store=populated_store,
+        )
+        # Procedural memory should appear AFTER datasource_context
+        memory_pos = prompt.find("MEMORY HERE")
+        ds_pos = prompt.find("DS HERE")
+        proc_pos = prompt.find("## Procedural memory")
+        assert memory_pos != -1
+        assert ds_pos != -1
+        assert proc_pos != -1
+        assert proc_pos > ds_pos
+        assert proc_pos > memory_pos
+
+    def test_section_is_compact(self, populated_store: SkillStore):
+        """Sanity check: ~50 tokens per skill or less.
+
+        We don't want the procedural memory section to dominate the
+        prompt — it's a navigational index, not the actual procedures.
+        """
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(builder, skill_store=populated_store)
+        section_start = prompt.find("## Procedural memory")
+        section = prompt[section_start:]
+        # Three skills, header + intro + bullets — keep it under ~600 chars
+        assert len(section) < 1000
+
+    def test_handles_skill_without_when_to_use(self, tmp_path: Path):
+        s = SkillStore(root=tmp_path / "skills_partial")
+        s.save(
+            Skill(
+                label="bare",
+                name="Bare",
+                description="",
+                when_to_use="",
+                declarative_md="x",
+                created_at="2026-04-10T12:00:00+00:00",
+                provenance="manual",
+            )
+        )
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(builder, skill_store=s)
+        assert "`bare`" in prompt
+        # No crash, even with no when_to_use
+
+    def test_skip_section_when_store_raises(self, tmp_path: Path, monkeypatch):
+        """If the store blows up at read time, the section is omitted gracefully."""
+        s = SkillStore(root=tmp_path / "skills_broken")
+
+        def boom(self):
+            raise RuntimeError("disk on fire")
+
+        monkeypatch.setattr(SkillStore, "list_summaries", boom)
+        builder = ChatSystemPromptBuilder()
+        prompt = _build_prompt(builder, skill_store=s)
+        assert "Procedural memory" not in prompt
diff --git a/tests/test_provider.py b/tests/test_provider.py
index dece8dc7..0d0ac8a8 100644
--- a/tests/test_provider.py
+++ b/tests/test_provider.py
@@ -2,8 +2,8 @@
 
 from unittest.mock import AsyncMock, MagicMock, patch
 
-from anton.llm.anthropic import AnthropicProvider
-from anton.llm.provider import LLMResponse, ToolCall
+from anton.core.llm.anthropic import AnthropicProvider
+from anton.core.llm.provider import LLMResponse, ToolCall
 
 
 class TestDataclasses:
@@ -16,7 +16,7 @@ def test_llm_response_with_tool_calls(self):
 
 class TestAnthropicProvider:
     async def test_complete_text_response(self):
-        with patch("anton.llm.anthropic.anthropic") as mock_anthropic:
+        with patch("anton.core.llm.anthropic.anthropic") as mock_anthropic:
             mock_client = AsyncMock()
             mock_anthropic.AsyncAnthropic.return_value = mock_client
 
@@ -45,7 +45,7 @@ async def test_complete_text_response(self):
             assert result.stop_reason == "end_turn"
 
     async def test_complete_tool_use_response(self):
-        with patch("anton.llm.anthropic.anthropic") as mock_anthropic:
+        with patch("anton.core.llm.anthropic.anthropic") as mock_anthropic:
             mock_client = AsyncMock()
             mock_anthropic.AsyncAnthropic.return_value = mock_client
 
@@ -78,7 +78,7 @@ async def test_complete_tool_use_response(self):
             assert result.stop_reason == "tool_use"
 
     async def test_complete_passes_tool_choice(self):
-        with patch("anton.llm.anthropic.anthropic") as mock_anthropic:
+        with patch("anton.core.llm.anthropic.anthropic") as mock_anthropic:
             mock_client = AsyncMock()
             mock_anthropic.AsyncAnthropic.return_value = mock_client
 
@@ -110,7 +110,7 @@ async def test_complete_passes_tool_choice(self):
             assert call_kwargs["tools"] == tools
 
     async def test_complete_omits_tool_choice_when_none(self):
-        with patch("anton.llm.anthropic.anthropic") as mock_anthropic:
+        with patch("anton.core.llm.anthropic.anthropic") as mock_anthropic:
             mock_client = AsyncMock()
             mock_anthropic.AsyncAnthropic.return_value = mock_client
 
@@ -137,7 +137,7 @@ async def test_complete_omits_tool_choice_when_none(self):
             assert "tool_choice" not in call_kwargs
 
     async def test_provider_without_api_key(self):
-        with patch("anton.llm.anthropic.anthropic") as mock_anthropic:
+        with patch("anton.core.llm.anthropic.anthropic") as mock_anthropic:
             mock_anthropic.AsyncAnthropic.return_value = AsyncMock()
             provider = AnthropicProvider()
             mock_anthropic.AsyncAnthropic.assert_called_once_with()
diff --git a/tests/test_recall_skill.py b/tests/test_recall_skill.py
new file mode 100644
index 00000000..2f53d693
--- /dev/null
+++ b/tests/test_recall_skill.py
@@ -0,0 +1,218 @@
+"""Tests for the `recall_skill` tool handler."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from anton.core.memory.skills import Skill, SkillStore
+from anton.core.tools.recall_skill import (
+    RECALL_SKILL_TOOL,
+    handle_recall_skill,
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fixtures
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture()
+def store(tmp_path: Path) -> SkillStore:
+    s = SkillStore(root=tmp_path / "skills")
+    s.save(
+        Skill(
+            label="csv_summary",
+            name="CSV Summary",
+            description="Load a CSV, infer schema, compute summary stats.",
+            when_to_use="User asks to explore, summarize, or describe a CSV file.",
+            declarative_md="1. Load the CSV.\n2. Infer types.\n3. Print summary.",
+            created_at="2026-04-10T12:00:00+00:00",
+            provenance="manual",
+        )
+    )
+    s.save(
+        Skill(
+            label="web_scraping",
+            name="Web Scraping",
+            description="Fetch and parse HTML to extract structured data.",
+            when_to_use="User asks to scrape or extract data from a webpage.",
+            declarative_md="1. Fetch the URL.\n2. Parse with BeautifulSoup.\n3. Select elements.",
+            created_at="2026-04-10T12:00:00+00:00",
+            provenance="manual",
+        )
+    )
+    s.save(
+        Skill(
+            label="api_fetcher",
+            name="API Fetcher",
+            description="Call a REST API and normalize the response.",
+            when_to_use="User asks to fetch data from a JSON API.",
+            declarative_md="1. Identify auth.\n2. Call endpoint.\n3. Normalize.",
+            created_at="2026-04-10T12:00:00+00:00",
+            provenance="manual",
+        )
+    )
+    return s
+
+
+def _session_with(store: SkillStore) -> SimpleNamespace:
+    """Build a minimal session-like object exposing only `_skill_store`."""
+    return SimpleNamespace(_skill_store=store)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Tool def basics
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestToolDef:
+    def test_tool_name(self):
+        assert RECALL_SKILL_TOOL.name == "recall_skill"
+
+    def test_required_label_param(self):
+        schema = RECALL_SKILL_TOOL.input_schema
+        assert "label" in schema["properties"]
+        assert schema["required"] == ["label"]
+
+    def test_handler_is_wired(self):
+        assert RECALL_SKILL_TOOL.handler is handle_recall_skill
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Happy path
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestExactMatch:
+    @pytest.mark.asyncio
+    async def test_returns_procedure(self, store: SkillStore):
+        session = _session_with(store)
+        result = await handle_recall_skill(session, {"label": "csv_summary"})
+        assert "CSV Summary" in result
+        assert "Load the CSV" in result
+        assert "Infer types" in result
+        assert "Print summary" in result
+
+    @pytest.mark.asyncio
+    async def test_increments_recommended_counter(self, store: SkillStore):
+        session = _session_with(store)
+        await handle_recall_skill(session, {"label": "csv_summary"})
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 1
+
+    @pytest.mark.asyncio
+    async def test_repeated_calls_accumulate(self, store: SkillStore):
+        session = _session_with(store)
+        for _ in range(3):
+            await handle_recall_skill(session, {"label": "web_scraping"})
+        loaded = store.load("web_scraping")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 3
+        assert loaded.stats.total_recalls == 3
+
+    @pytest.mark.asyncio
+    async def test_does_not_cross_contaminate(self, store: SkillStore):
+        session = _session_with(store)
+        await handle_recall_skill(session, {"label": "csv_summary"})
+        await handle_recall_skill(session, {"label": "csv_summary"})
+        await handle_recall_skill(session, {"label": "web_scraping"})
+        csv = store.load("csv_summary")
+        web = store.load("web_scraping")
+        api = store.load("api_fetcher")
+        assert csv is not None and csv.stats.stage_1.recommended == 2
+        assert web is not None and web.stats.stage_1.recommended == 1
+        assert api is not None and api.stats.stage_1.recommended == 0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Typo fallback
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestTypoFallback:
+    @pytest.mark.asyncio
+    async def test_typo_returns_closest_match(self, store: SkillStore):
+        session = _session_with(store)
+        result = await handle_recall_skill(session, {"label": "csv_sumary"})
+        assert "⚠" in result
+        assert "csv_summary" in result
+        # The full procedure is still included after the warning
+        assert "Load the CSV" in result
+
+    @pytest.mark.asyncio
+    async def test_typo_credits_resolved_label_not_input(self, store: SkillStore):
+        session = _session_with(store)
+        await handle_recall_skill(session, {"label": "csv_sumary"})
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 1
+
+    @pytest.mark.asyncio
+    async def test_dash_to_underscore_recovered(self, store: SkillStore):
+        session = _session_with(store)
+        result = await handle_recall_skill(session, {"label": "web-scraping"})
+        assert "web_scraping" in result
+        # Could match exactly via slugify, in which case there's no warning,
+        # or via fuzzy match. Either way the procedure should be returned.
+        assert "BeautifulSoup" in result
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Unknown / error paths
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestUnknownSlug:
+    @pytest.mark.asyncio
+    async def test_unrelated_returns_no_match_with_listing(
+        self, store: SkillStore
+    ):
+        session = _session_with(store)
+        result = await handle_recall_skill(session, {"label": "xyzzy_quark"})
+        assert "NO MATCH" in result
+        # Should mention all available labels
+        assert "csv_summary" in result
+        assert "web_scraping" in result
+        assert "api_fetcher" in result
+
+    @pytest.mark.asyncio
+    async def test_unrelated_does_not_increment_counters(
+        self, store: SkillStore
+    ):
+        session = _session_with(store)
+        await handle_recall_skill(session, {"label": "xyzzy_quark"})
+        for label in ("csv_summary", "web_scraping", "api_fetcher"):
+            loaded = store.load(label)
+            assert loaded is not None
+            assert loaded.stats.stage_1.recommended == 0
+            assert loaded.stats.total_recalls == 0
+
+    @pytest.mark.asyncio
+    async def test_empty_label_returns_error(self, store: SkillStore):
+        session = _session_with(store)
+        result = await handle_recall_skill(session, {"label": ""})
+        assert "ERROR" in result
+
+    @pytest.mark.asyncio
+    async def test_missing_label_returns_error(self, store: SkillStore):
+        session = _session_with(store)
+        result = await handle_recall_skill(session, {})
+        assert "ERROR" in result
+
+    @pytest.mark.asyncio
+    async def test_no_store_on_session_returns_error(self):
+        session = SimpleNamespace()  # no _skill_store
+        result = await handle_recall_skill(session, {"label": "csv_summary"})
+        assert "ERROR" in result
+
+    @pytest.mark.asyncio
+    async def test_empty_store_unrelated_label(self, tmp_path: Path):
+        store = SkillStore(root=tmp_path / "empty_skills")
+        session = _session_with(store)
+        result = await handle_recall_skill(session, {"label": "anything"})
+        assert "NO MATCH" in result
+        assert "empty" in result.lower()
diff --git a/tests/test_scratchpad.py b/tests/test_scratchpad.py
index e26f3b2c..14fef17c 100644
--- a/tests/test_scratchpad.py
+++ b/tests/test_scratchpad.py
@@ -5,14 +5,40 @@
 
 import pytest
 
-import anton.scratchpad as scratchpad_module
-from anton.scratchpad import Cell, Scratchpad, ScratchpadManager
+from anton.core.backends.base import Cell
+from anton.core.backends.local import LocalScratchpadRuntime
+from anton.core.backends.utils import compute_timeouts as _compute_timeouts
+from anton.core.backends.manager import ScratchpadManager
+from anton.core.backends.local import local_scratchpad_runtime_factory
+
+# Alias for brevity in tests
+Scratchpad = LocalScratchpadRuntime
+
+_SCRATCHPAD_DEFAULTS = dict(
+    coding_provider="anthropic",
+    coding_model="",
+    coding_api_key="",
+    coding_base_url="",
+)
+
+_MANAGER_DEFAULTS = dict(
+    runtime_factory=local_scratchpad_runtime_factory,
+    **_SCRATCHPAD_DEFAULTS,
+)
+
+
+def make_scratchpad(name: str, **kwargs) -> LocalScratchpadRuntime:
+    return Scratchpad(name=name, **{**_SCRATCHPAD_DEFAULTS, **kwargs})
+
+
+def make_manager(**kwargs) -> ScratchpadManager:
+    return ScratchpadManager(**{**_MANAGER_DEFAULTS, **kwargs})
 
 
 class TestScratchpadBasicExecution:
     async def test_basic_execution(self):
         """print(42) should return '42' in stdout."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             cell = await pad.execute("print(42)")
@@ -23,7 +49,7 @@ async def test_basic_execution(self):
 
     async def test_state_persists(self):
         """Variable from cell 1 should be available in cell 2."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             await pad.execute("x = 123")
@@ -35,7 +61,7 @@ async def test_state_persists(self):
 
     async def test_error_captured_process_survives(self):
         """Exception doesn't kill process; next cell works."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             cell1 = await pad.execute("raise ValueError('boom')")
@@ -52,7 +78,7 @@ async def test_error_captured_process_survives(self):
 
     async def test_imports_persist(self):
         """import json in cell 1, json.dumps(...) in cell 2."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             await pad.execute("import json")
@@ -66,7 +92,7 @@ async def test_imports_persist(self):
 class TestScratchpadView:
     async def test_view_history(self):
         """view() should show all cells with outputs."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             await pad.execute("x = 10")
@@ -81,7 +107,7 @@ async def test_view_history(self):
 
     async def test_view_empty(self):
         """view() on empty pad returns a message."""
-        pad = Scratchpad(name="empty")
+        pad = make_scratchpad(name="empty")
         await pad.start()
         try:
             output = pad.view()
@@ -93,7 +119,7 @@ async def test_view_empty(self):
 class TestScratchpadReset:
     async def test_reset_clears_state(self):
         """Variables should be gone after reset."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             await pad.execute("x = 42")
@@ -110,9 +136,9 @@ async def test_reset_clears_state(self):
 class TestScratchpadEdgeCases:
     async def test_timeout_kills_process(self, monkeypatch):
         """Long-running code triggers timeout."""
-        monkeypatch.setattr(scratchpad_module, "_CELL_TIMEOUT_DEFAULT", 1)
-        monkeypatch.setattr(scratchpad_module, "_CELL_INACTIVITY_TIMEOUT", 1)
-        pad = Scratchpad(name="test")
+        monkeypatch.setenv("ANTON_CELL_TIMEOUT_DEFAULT", "1")
+        monkeypatch.setenv("ANTON_CELL_INACTIVITY_TIMEOUT", "1")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             cell = await pad.execute("import time; time.sleep(60)")
@@ -123,7 +149,7 @@ async def test_timeout_kills_process(self, monkeypatch):
 
     async def test_output_truncation(self):
         """stdout exceeding _MAX_OUTPUT is capped in the boot script."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             cell = await pad.execute("print('x' * 20000)")
@@ -135,7 +161,7 @@ async def test_output_truncation(self):
 
     async def test_dead_process_detected(self):
         """If process is dead, execute reports it."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         # Kill the process manually
         pad._proc.kill()
@@ -147,7 +173,7 @@ async def test_dead_process_detected(self):
 
     async def test_stderr_captured(self):
         """stderr output is captured separately."""
-        pad = Scratchpad(name="test")
+        pad = make_scratchpad(name="test")
         await pad.start()
         try:
             cell = await pad.execute("import sys; sys.stderr.write('warn\\n')")
@@ -159,7 +185,7 @@ async def test_stderr_captured(self):
 class TestScratchpadManager:
     async def test_get_or_create(self):
         """Auto-creates a scratchpad on first access."""
-        mgr = ScratchpadManager()
+        mgr = make_manager()
         try:
             pad = await mgr.get_or_create("alpha")
             assert pad.name == "alpha"
@@ -173,7 +199,7 @@ async def test_get_or_create(self):
 
     async def test_remove(self):
         """remove() kills and deletes the scratchpad."""
-        mgr = ScratchpadManager()
+        mgr = make_manager()
         try:
             await mgr.get_or_create("beta")
             result = await mgr.remove("beta")
@@ -184,13 +210,13 @@ async def test_remove(self):
 
     async def test_remove_nonexistent(self):
         """remove() on unknown name returns a message."""
-        mgr = ScratchpadManager()
+        mgr = make_manager()
         result = await mgr.remove("nope")
         assert "nope" in result
 
     async def test_close_all(self):
         """close_all() cleans up everything."""
-        mgr = ScratchpadManager()
+        mgr = make_manager()
         await mgr.get_or_create("a")
         await mgr.get_or_create("b")
         assert len(mgr.list_pads()) == 2
@@ -203,7 +229,7 @@ async def test_close_all_does_not_restart_processes(self):
         cancel_all_running() would leave _proc pointing to a new (orphan-prone)
         process. close_all() must leave _proc as None.
         """
-        mgr = ScratchpadManager()
+        mgr = make_manager()
         pad = await mgr.get_or_create("test")
         try:
             await pad.execute("x = 1")
@@ -216,7 +242,7 @@ async def test_close_all_does_not_restart_processes(self):
 class TestScratchpadRenderNotebook:
     async def test_render_notebook_basic(self):
         """Produces markdown with code blocks and output."""
-        pad = Scratchpad(name="main")
+        pad = make_scratchpad(name="main")
         await pad.start()
         try:
             await pad.execute("x = 1")
@@ -233,7 +259,7 @@ async def test_render_notebook_basic(self):
 
     async def test_render_notebook_empty(self):
         """Empty pad returns a message."""
-        pad = Scratchpad(name="empty")
+        pad = make_scratchpad(name="empty")
         await pad.start()
         try:
             md = pad.render_notebook()
@@ -243,7 +269,7 @@ async def test_render_notebook_empty(self):
 
     async def test_render_notebook_skips_empty_cells(self):
         """Whitespace-only cells are filtered out."""
-        pad = Scratchpad(name="gaps")
+        pad = make_scratchpad(name="gaps")
         await pad.start()
         try:
             await pad.execute("print('a')")
@@ -259,7 +285,7 @@ async def test_render_notebook_skips_empty_cells(self):
 
     async def test_render_notebook_truncates_long_output(self):
         """Long stdout shows 'more lines' indicator."""
-        pad = Scratchpad(name="long")
+        pad = make_scratchpad(name="long")
         await pad.start()
         try:
             await pad.execute("for i in range(50): print(i)")
@@ -270,7 +296,7 @@ async def test_render_notebook_truncates_long_output(self):
 
     async def test_render_notebook_error_summary(self):
         """Only last traceback line shown, not full trace."""
-        pad = Scratchpad(name="err")
+        pad = make_scratchpad(name="err")
         await pad.start()
         try:
             await pad.execute("raise ValueError('boom')")
@@ -284,7 +310,7 @@ async def test_render_notebook_error_summary(self):
 
     async def test_render_notebook_hides_stderr_without_error(self):
         """Warnings (stderr only, no error) are filtered out of output sections."""
-        pad = Scratchpad(name="warn")
+        pad = make_scratchpad(name="warn")
         await pad.start()
         try:
             await pad.execute("import sys; sys.stderr.write('some warning\\n')")
@@ -298,7 +324,7 @@ async def test_render_notebook_hides_stderr_without_error(self):
     async def test_truncate_output_lines(self):
         """Respects line limit."""
         text = "\n".join(f"line {i}" for i in range(50))
-        result = Scratchpad._truncate_output(text, max_lines=10)
+        result = LocalScratchpadRuntime._truncate_output(text, max_lines=10)
         assert "line 0" in result
         assert "line 9" in result
         assert "line 10" not in result
@@ -307,7 +333,7 @@ async def test_truncate_output_lines(self):
     async def test_truncate_output_chars(self):
         """Respects char limit."""
         text = "\n".join("x" * 80 for _ in range(5))
-        result = Scratchpad._truncate_output(text, max_lines=100, max_chars=200)
+        result = LocalScratchpadRuntime._truncate_output(text, max_lines=100, max_chars=200)
         assert "(truncated)" in result
         assert len(result) < len(text)
 
@@ -315,7 +341,7 @@ async def test_truncate_output_chars(self):
 class TestCellMetadata:
     async def test_cell_stores_description_and_estimated_time(self):
         """execute() should store description and estimated_time on the Cell."""
-        pad = Scratchpad(name="meta")
+        pad = make_scratchpad(name="meta")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -331,7 +357,7 @@ async def test_cell_stores_description_and_estimated_time(self):
 
     async def test_cell_defaults_empty_metadata(self):
         """Without arguments, description and estimated_time default to empty."""
-        pad = Scratchpad(name="defaults")
+        pad = make_scratchpad(name="defaults")
         await pad.start()
         try:
             cell = await pad.execute("print(1)")
@@ -342,7 +368,7 @@ async def test_cell_defaults_empty_metadata(self):
 
     async def test_view_shows_description_in_header(self):
         """view() should include description in the cell header."""
-        pad = Scratchpad(name="view-desc")
+        pad = make_scratchpad(name="view-desc")
         await pad.start()
         try:
             await pad.execute("print(1)", description="Count to one")
@@ -353,7 +379,7 @@ async def test_view_shows_description_in_header(self):
 
     async def test_view_without_description(self):
         """view() without description falls back to plain header."""
-        pad = Scratchpad(name="view-plain")
+        pad = make_scratchpad(name="view-plain")
         await pad.start()
         try:
             await pad.execute("print(1)")
@@ -364,7 +390,7 @@ async def test_view_without_description(self):
 
     async def test_render_notebook_shows_description(self):
         """render_notebook() should include description in markdown header."""
-        pad = Scratchpad(name="nb-desc")
+        pad = make_scratchpad(name="nb-desc")
         await pad.start()
         try:
             await pad.execute("print(1)", description="Count to one")
@@ -375,7 +401,7 @@ async def test_render_notebook_shows_description(self):
 
     async def test_render_notebook_without_description(self):
         """render_notebook() without description uses plain header."""
-        pad = Scratchpad(name="nb-plain")
+        pad = make_scratchpad(name="nb-plain")
         await pad.start()
         try:
             await pad.execute("print(1)")
@@ -390,7 +416,7 @@ class TestScratchpadEnvironment:
     async def test_env_vars_accessible(self, monkeypatch):
         """Secrets from .anton/.env (in os.environ) are accessible in scratchpad."""
         monkeypatch.setenv("MY_TEST_SECRET", "s3cret_value")
-        pad = Scratchpad(name="env-test")
+        pad = make_scratchpad(name="env-test")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -402,7 +428,7 @@ async def test_env_vars_accessible(self, monkeypatch):
 
     async def test_get_llm_available_when_model_set(self):
         """get_llm() should be injected when ANTON_SCRATCHPAD_MODEL is set."""
-        pad = Scratchpad(name="llm-test", _coding_model="claude-test-model")
+        pad = make_scratchpad(name="llm-test", coding_model="claude-test-model")
         await pad.start()
         try:
             cell = await pad.execute("llm = get_llm(); print(llm.model)")
@@ -413,7 +439,7 @@ async def test_get_llm_available_when_model_set(self):
 
     async def test_get_llm_not_available_without_model(self):
         """get_llm() should not be in namespace when no model is configured."""
-        pad = Scratchpad(name="no-llm")
+        pad = make_scratchpad(name="no-llm")
         await pad.start()
         try:
             cell = await pad.execute("get_llm()")
@@ -424,7 +450,7 @@ async def test_get_llm_not_available_without_model(self):
 
     async def test_agentic_loop_available_when_model_set(self):
         """agentic_loop() should be injected alongside get_llm()."""
-        pad = Scratchpad(name="agentic-test", _coding_model="claude-test-model")
+        pad = make_scratchpad(name="agentic-test", coding_model="claude-test-model")
         await pad.start()
         try:
             cell = await pad.execute("print(callable(agentic_loop))")
@@ -435,7 +461,7 @@ async def test_agentic_loop_available_when_model_set(self):
 
     async def test_agentic_loop_not_available_without_model(self):
         """agentic_loop() should not be in namespace when no model is configured."""
-        pad = Scratchpad(name="no-agentic")
+        pad = make_scratchpad(name="no-agentic")
         await pad.start()
         try:
             cell = await pad.execute("agentic_loop()")
@@ -446,7 +472,7 @@ async def test_agentic_loop_not_available_without_model(self):
 
     async def test_generate_object_available_when_model_set(self):
         """generate_object() should be available on the LLM wrapper."""
-        pad = Scratchpad(name="genobj-test", _coding_model="claude-test-model")
+        pad = make_scratchpad(name="genobj-test", coding_model="claude-test-model")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -462,7 +488,7 @@ async def test_api_key_bridged(self, monkeypatch):
         monkeypatch.setenv("ANTON_ANTHROPIC_API_KEY", "sk-ant-test-123")
         # Remove ANTHROPIC_API_KEY if set, to test the bridge
         monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
-        pad = Scratchpad(name="key-test", _coding_model="test-model")
+        pad = make_scratchpad(name="key-test", coding_model="test-model")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -476,7 +502,7 @@ async def test_api_key_bridged(self, monkeypatch):
 class TestScratchpadVenv:
     async def test_venv_created_on_start(self):
         """Venv directory should be created when the scratchpad starts."""
-        pad = Scratchpad(name="venv-test")
+        pad = make_scratchpad(name="venv-test")
         await pad.start()
         try:
             assert pad._venv_dir is not None
@@ -488,7 +514,7 @@ async def test_venv_created_on_start(self):
 
     async def test_venv_persisted_on_close(self):
         """Venv directory should be preserved when the scratchpad is closed."""
-        pad = Scratchpad(name="venv-close")
+        pad = make_scratchpad(name="venv-close")
         await pad.start()
         venv_dir = pad._venv_dir
         assert os.path.isdir(venv_dir)
@@ -504,7 +530,7 @@ async def test_venv_persisted_on_close(self):
 
     async def test_venv_persists_across_reset(self):
         """Venv should survive a reset (only the process restarts)."""
-        pad = Scratchpad(name="venv-reset")
+        pad = make_scratchpad(name="venv-reset")
         await pad.start()
         venv_dir = pad._venv_dir
         try:
@@ -516,7 +542,7 @@ async def test_venv_persists_across_reset(self):
 
     async def test_subprocess_uses_venv_python(self):
         """The subprocess should run with the venv's Python executable."""
-        pad = Scratchpad(name="venv-exec")
+        pad = make_scratchpad(name="venv-exec")
         await pad.start()
         try:
             cell = await pad.execute("import sys; print(sys.executable)")
@@ -527,7 +553,7 @@ async def test_subprocess_uses_venv_python(self):
 
     async def test_system_packages_available(self):
         """System site-packages should be accessible (e.g. pydantic from parent env)."""
-        pad = Scratchpad(name="venv-syspkg")
+        pad = make_scratchpad(name="venv-syspkg")
         await pad.start()
         try:
             cell = await pad.execute("import pydantic; print(pydantic.__name__)")
@@ -544,7 +570,7 @@ async def test_venv_recycled_on_restart(self, tmp_path):
         """Close + reopen same name → packages remembered."""
         import shutil
         venvs_base = tmp_path / "venvs"
-        pad = Scratchpad(name="recycle", _venvs_base=venvs_base)
+        pad = make_scratchpad(name="recycle", _venvs_base=venvs_base)
         await pad.start()
         await pad.install_packages(["cowsay"])
         venv_dir = pad._venv_dir
@@ -558,7 +584,7 @@ async def test_venv_recycled_on_restart(self, tmp_path):
             assert "cowsay" in f.read()
 
         # Reopen — should recycle the existing venv
-        pad2 = Scratchpad(name="recycle", _venvs_base=venvs_base)
+        pad2 = make_scratchpad(name="recycle", _venvs_base=venvs_base)
         await pad2.start()
         try:
             assert "cowsay" in pad2._installed_packages
@@ -573,7 +599,7 @@ async def test_venv_nuked_on_version_mismatch(self, tmp_path, monkeypatch):
         """Wrong .python_version → recreates venv."""
         import shutil
         venvs_base = tmp_path / "venvs"
-        pad = Scratchpad(name="ver-mismatch", _venvs_base=venvs_base)
+        pad = make_scratchpad(name="ver-mismatch", _venvs_base=venvs_base)
         await pad.start()
         venv_dir = pad._venv_dir
         await pad.close()
@@ -584,7 +610,7 @@ async def test_venv_nuked_on_version_mismatch(self, tmp_path, monkeypatch):
             f.write("2.7\n")
 
         # Reopen — should detect mismatch, nuke, and recreate
-        pad2 = Scratchpad(name="ver-mismatch", _venvs_base=venvs_base)
+        pad2 = make_scratchpad(name="ver-mismatch", _venvs_base=venvs_base)
         await pad2.start()
         try:
             assert pad2._venv_dir is not None
@@ -601,7 +627,7 @@ async def test_venv_nuked_on_corruption(self, tmp_path):
         """Delete Python binary → recreates venv."""
         import shutil
         venvs_base = tmp_path / "venvs"
-        pad = Scratchpad(name="corrupt", _venvs_base=venvs_base)
+        pad = make_scratchpad(name="corrupt", _venvs_base=venvs_base)
         await pad.start()
         venv_dir = pad._venv_dir
         python_path = pad._venv_python
@@ -611,7 +637,7 @@ async def test_venv_nuked_on_corruption(self, tmp_path):
         os.remove(python_path)
 
         # Reopen — should detect corruption, nuke, and recreate
-        pad2 = Scratchpad(name="corrupt", _venvs_base=venvs_base)
+        pad2 = make_scratchpad(name="corrupt", _venvs_base=venvs_base)
         await pad2.start()
         try:
             assert pad2._venv_dir is not None
@@ -627,10 +653,7 @@ async def test_venv_nuked_on_corruption(self, tmp_path):
     async def test_remove_deletes_persistent_venv(self, tmp_path):
         """ScratchpadManager.remove() fully deletes the persistent venv dir."""
         import shutil
-        venvs_base = tmp_path / "venvs"
-        mgr = ScratchpadManager(workspace_path=tmp_path)
-        # Override base to use our tmp dir
-        mgr._venvs_base = venvs_base
+        mgr = make_manager(workspace_path=tmp_path)
         try:
             pad = await mgr.get_or_create("deleteme")
             venv_dir = pad._venv_dir
@@ -639,13 +662,13 @@ async def test_remove_deletes_persistent_venv(self, tmp_path):
             assert not os.path.exists(venv_dir)
         finally:
             await mgr.close_all()
-            shutil.rmtree(venvs_base, ignore_errors=True)
+            shutil.rmtree(tmp_path / ".anton", ignore_errors=True)
 
     async def test_requirements_saved_on_close(self, tmp_path):
         """requirements.txt is written when pad has installed packages."""
         import shutil
         venvs_base = tmp_path / "venvs"
-        pad = Scratchpad(name="req-save", _venvs_base=venvs_base)
+        pad = make_scratchpad(name="req-save", _venvs_base=venvs_base)
         await pad.start()
         await pad.install_packages(["cowsay"])
         await pad.close()
@@ -661,7 +684,7 @@ async def test_requirements_saved_on_close(self, tmp_path):
 class TestScratchpadInstall:
     async def test_install_packages_success(self):
         """install_packages should install a package into the venv."""
-        pad = Scratchpad(name="install-test")
+        pad = make_scratchpad(name="install-test")
         await pad.start()
         try:
             result = await pad.install_packages(["cowsay"])
@@ -675,7 +698,7 @@ async def test_install_packages_success(self):
 
     async def test_install_empty_list(self):
         """install_packages with empty list returns a message."""
-        pad = Scratchpad(name="install-empty")
+        pad = make_scratchpad(name="install-empty")
         await pad.start()
         try:
             result = await pad.install_packages([])
@@ -685,7 +708,7 @@ async def test_install_empty_list(self):
 
     async def test_install_invalid_package(self):
         """install_packages with a bogus name should report failure."""
-        pad = Scratchpad(name="install-bad")
+        pad = make_scratchpad(name="install-bad")
         await pad.start()
         try:
             result = await pad.install_packages(["this-package-does-not-exist-xyz123"])
@@ -695,7 +718,7 @@ async def test_install_invalid_package(self):
 
     async def test_install_survives_reset(self):
         """Packages installed before a reset should still be available after."""
-        pad = Scratchpad(name="install-reset")
+        pad = make_scratchpad(name="install-reset")
         await pad.start()
         try:
             await pad.install_packages(["cowsay"])
@@ -710,7 +733,7 @@ async def test_install_survives_reset(self):
 class TestProgressAndTimeouts:
     async def test_progress_function_available_in_namespace(self):
         """progress() should be callable in scratchpad code."""
-        pad = Scratchpad(name="progress-ns")
+        pad = make_scratchpad(name="progress-ns")
         await pad.start()
         try:
             cell = await pad.execute("print(callable(progress))")
@@ -721,9 +744,9 @@ async def test_progress_function_available_in_namespace(self):
 
     async def test_progress_resets_inactivity_timeout(self, monkeypatch):
         """Code that calls progress() frequently should survive even with a short inactivity timeout."""
-        monkeypatch.setattr(scratchpad_module, "_CELL_INACTIVITY_TIMEOUT", 2)
-        monkeypatch.setattr(scratchpad_module, "_CELL_TIMEOUT_DEFAULT", 10)
-        pad = Scratchpad(name="progress-keep-alive")
+        monkeypatch.setenv("ANTON_CELL_INACTIVITY_TIMEOUT", "2")
+        monkeypatch.setenv("ANTON_CELL_TIMEOUT_DEFAULT", "10")
+        pad = make_scratchpad(name="progress-keep-alive")
         await pad.start()
         try:
             code = (
@@ -741,9 +764,9 @@ async def test_progress_resets_inactivity_timeout(self, monkeypatch):
 
     async def test_inactivity_timeout_kills_without_progress(self, monkeypatch):
         """Code that sleeps without progress() calls should be killed by inactivity timeout."""
-        monkeypatch.setattr(scratchpad_module, "_CELL_INACTIVITY_TIMEOUT", 2)
-        monkeypatch.setattr(scratchpad_module, "_CELL_TIMEOUT_DEFAULT", 60)
-        pad = Scratchpad(name="no-progress")
+        monkeypatch.setenv("ANTON_CELL_INACTIVITY_TIMEOUT", "2")
+        monkeypatch.setenv("ANTON_CELL_TIMEOUT_DEFAULT", "60")
+        pad = make_scratchpad(name="no-progress")
         await pad.start()
         try:
             cell = await pad.execute("import time; time.sleep(30)")
@@ -754,7 +777,7 @@ async def test_inactivity_timeout_kills_without_progress(self, monkeypatch):
 
     async def test_execute_streaming_yields_progress(self):
         """execute_streaming() should yield progress strings and a final Cell."""
-        pad = Scratchpad(name="streaming")
+        pad = make_scratchpad(name="streaming")
         await pad.start()
         try:
             code = (
@@ -780,14 +803,14 @@ async def test_execute_streaming_yields_progress(self):
 
     async def test_compute_timeouts_no_estimate(self):
         """No estimate should use defaults."""
-        from anton.scratchpad import _compute_timeouts
+        from anton.core.backends.utils import compute_timeouts as _compute_timeouts
         total, inactivity = _compute_timeouts(0)
         assert total == 120.0
         assert inactivity == 30.0
 
     async def test_compute_timeouts_with_estimate(self):
         """Estimate should scale total timeout and inactivity with no hard cap."""
-        from anton.scratchpad import _compute_timeouts
+        from anton.core.backends.utils import compute_timeouts as _compute_timeouts
 
         # Small estimate: max(10*2, 10+30) = max(20, 40) = 40
         total, inactivity = _compute_timeouts(10)
@@ -813,7 +836,7 @@ async def test_compute_timeouts_with_estimate(self):
 class TestSampleFunction:
     async def test_sample_available_in_namespace(self):
         """sample() should be callable in scratchpad code."""
-        pad = Scratchpad(name="sample-ns")
+        pad = make_scratchpad(name="sample-ns")
         await pad.start()
         try:
             cell = await pad.execute("print(callable(sample))")
@@ -824,7 +847,7 @@ async def test_sample_available_in_namespace(self):
 
     async def test_sample_dict_preview(self):
         """sample() on a dict should show keys and truncated values."""
-        pad = Scratchpad(name="sample-dict")
+        pad = make_scratchpad(name="sample-dict")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -841,7 +864,7 @@ async def test_sample_dict_preview(self):
 
     async def test_sample_list_preview(self):
         """sample() on a list should show length and first/last items."""
-        pad = Scratchpad(name="sample-list")
+        pad = make_scratchpad(name="sample-list")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -858,7 +881,7 @@ async def test_sample_list_preview(self):
 
     async def test_sample_string_preview(self):
         """sample() on a string should show length and a preview."""
-        pad = Scratchpad(name="sample-str")
+        pad = make_scratchpad(name="sample-str")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -874,7 +897,7 @@ async def test_sample_string_preview(self):
 
     async def test_sample_full_mode(self):
         """sample(var, mode='full') should show more content."""
-        pad = Scratchpad(name="sample-full")
+        pad = make_scratchpad(name="sample-full")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -890,7 +913,7 @@ async def test_sample_full_mode(self):
 
     async def test_sample_set(self):
         """sample() on a set should show length and items."""
-        pad = Scratchpad(name="sample-set")
+        pad = make_scratchpad(name="sample-set")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -905,7 +928,7 @@ async def test_sample_set(self):
 
     async def test_sample_custom_object(self):
         """sample() on an unknown object should show type and repr."""
-        pad = Scratchpad(name="sample-obj")
+        pad = make_scratchpad(name="sample-obj")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -922,7 +945,7 @@ async def test_sample_custom_object(self):
 
     async def test_sample_bytes(self):
         """sample() on bytes should show length and preview."""
-        pad = Scratchpad(name="sample-bytes")
+        pad = make_scratchpad(name="sample-bytes")
         await pad.start()
         try:
             cell = await pad.execute("sample(b'hello world')")
@@ -934,7 +957,7 @@ async def test_sample_bytes(self):
 
     async def test_sample_named(self):
         """sample() with _name parameter should include the label."""
-        pad = Scratchpad(name="sample-named")
+        pad = make_scratchpad(name="sample-named")
         await pad.start()
         try:
             cell = await pad.execute(
@@ -949,7 +972,7 @@ async def test_sample_named(self):
 
     async def test_sample_empty_dict(self):
         """sample() on an empty dict should not crash."""
-        pad = Scratchpad(name="sample-empty")
+        pad = make_scratchpad(name="sample-empty")
         await pad.start()
         try:
             cell = await pad.execute("sample({})")
@@ -960,7 +983,7 @@ async def test_sample_empty_dict(self):
 
     async def test_sample_empty_list(self):
         """sample() on an empty list should not crash."""
-        pad = Scratchpad(name="sample-empty-list")
+        pad = make_scratchpad(name="sample-empty-list")
         await pad.start()
         try:
             cell = await pad.execute("sample([])")
diff --git a/tests/test_scratchpad_observer_dispatch.py b/tests/test_scratchpad_observer_dispatch.py
new file mode 100644
index 00000000..1a99c4a5
--- /dev/null
+++ b/tests/test_scratchpad_observer_dispatch.py
@@ -0,0 +1,290 @@
+"""Tests for the scratchpad observer dispatch in `handle_scratchpad`.
+
+These tests verify that the observer hooks fire at the right moments
+around `pad.execute()` and that the runtime stays untouched. They use
+a fake observer (not the real Cerebellum) so we can assert exactly
+what was passed and in what order.
+
+The dispatcher pattern: observation is an orchestration concern that
+lives at the dispatcher layer. The runtime is a pure execution engine
+and never sees observers. These tests pin that contract.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from anton.core.backends.base import Cell
+from anton.core.tools.tool_handlers import (
+    _fire_post_execute,
+    _fire_pre_execute,
+    handle_scratchpad,
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fake observer that records the cells it sees
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class _RecordingObserver:
+    def __init__(self, *, pre_raises: Exception | None = None,
+                 post_raises: Exception | None = None) -> None:
+        self.pre_calls: list[Cell] = []
+        self.post_calls: list[Cell] = []
+        self._pre_raises = pre_raises
+        self._post_raises = post_raises
+
+    async def on_pre_execute(self, cell: Cell) -> None:
+        self.pre_calls.append(cell)
+        if self._pre_raises is not None:
+            raise self._pre_raises
+
+    async def on_post_execute(self, cell: Cell) -> None:
+        self.post_calls.append(cell)
+        if self._post_raises is not None:
+            raise self._post_raises
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _fake_session(
+    observers: list | None = None,
+    cell_to_return: Cell | None = None,
+) -> MagicMock:
+    """Build a minimal session-like mock that handle_scratchpad can drive."""
+    session = MagicMock()
+    if observers is not None:
+        session._scratchpad_observers = observers
+    else:
+        session._scratchpad_observers = []
+    session._record_cell_explainability = MagicMock()
+
+    # The cell that pad.execute() will return when called
+    if cell_to_return is None:
+        cell_to_return = Cell(
+            code="print('hi')",
+            stdout="hi",
+            stderr="",
+            error=None,
+            description="say hi",
+        )
+    pad = MagicMock()
+    pad.execute = AsyncMock(return_value=cell_to_return)
+    pad.view = MagicMock(return_value="view output")
+    pad.render_notebook = MagicMock(return_value="notebook")
+    pad.reset = AsyncMock()
+    pad.install_packages = AsyncMock(return_value="installed")
+
+    session._scratchpads = MagicMock()
+    session._scratchpads.get_or_create = AsyncMock(return_value=pad)
+    session._scratchpads.pads = {"main": pad}
+    session._scratchpads.remove = AsyncMock(return_value="removed 'main'.")
+    return session, pad
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# _fire_pre_execute / _fire_post_execute helpers — direct unit tests
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestFireHelpers:
+    @pytest.mark.asyncio
+    async def test_no_observers_is_noop(self):
+        session = SimpleNamespace(_scratchpad_observers=[])
+        cell = Cell(code="x", stdout="", stderr="", error=None)
+        # Should not raise
+        await _fire_pre_execute(session, cell)
+        await _fire_post_execute(session, cell)
+
+    @pytest.mark.asyncio
+    async def test_missing_attribute_is_noop(self):
+        # Session that doesn't have _scratchpad_observers at all
+        session = SimpleNamespace()
+        cell = Cell(code="x", stdout="", stderr="", error=None)
+        await _fire_pre_execute(session, cell)
+        await _fire_post_execute(session, cell)
+
+    @pytest.mark.asyncio
+    async def test_observer_receives_cell(self):
+        obs = _RecordingObserver()
+        session = SimpleNamespace(_scratchpad_observers=[obs])
+        cell = Cell(code="x", stdout="", stderr="", error=None, description="set x")
+        await _fire_pre_execute(session, cell)
+        assert len(obs.pre_calls) == 1
+        assert obs.pre_calls[0].code == "x"
+        assert obs.pre_calls[0].description == "set x"
+
+    @pytest.mark.asyncio
+    async def test_multiple_observers_all_fire(self):
+        obs_a = _RecordingObserver()
+        obs_b = _RecordingObserver()
+        session = SimpleNamespace(_scratchpad_observers=[obs_a, obs_b])
+        cell = Cell(code="y", stdout="", stderr="", error=None)
+        await _fire_post_execute(session, cell)
+        assert len(obs_a.post_calls) == 1
+        assert len(obs_b.post_calls) == 1
+
+    @pytest.mark.asyncio
+    async def test_one_observer_raising_does_not_stop_others(self):
+        bad = _RecordingObserver(pre_raises=RuntimeError("boom"))
+        good = _RecordingObserver()
+        session = SimpleNamespace(_scratchpad_observers=[bad, good])
+        cell = Cell(code="x", stdout="", stderr="", error=None)
+        # Must not raise
+        await _fire_pre_execute(session, cell)
+        # Good observer still fired
+        assert len(good.pre_calls) == 1
+
+    @pytest.mark.asyncio
+    async def test_observer_without_method_is_skipped(self):
+        # Observer with no on_pre_execute/on_post_execute methods
+        bare = SimpleNamespace()
+        session = SimpleNamespace(_scratchpad_observers=[bare])
+        cell = Cell(code="x", stdout="", stderr="", error=None)
+        # Should silently skip — no AttributeError
+        await _fire_pre_execute(session, cell)
+        await _fire_post_execute(session, cell)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# handle_scratchpad: full dispatch flow with observers
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestHandleScratchpadObserverIntegration:
+    @pytest.mark.asyncio
+    async def test_exec_fires_pre_then_post(self):
+        obs = _RecordingObserver()
+        cell = Cell(
+            code="print('hi')",
+            stdout="hi",
+            stderr="",
+            error=None,
+            description="say hi",
+        )
+        session, pad = _fake_session(observers=[obs], cell_to_return=cell)
+
+        await handle_scratchpad(
+            session,
+            {
+                "action": "exec",
+                "name": "main",
+                "code": "print('hi')",
+                "one_line_description": "say hi",
+                "estimated_execution_time_seconds": 1,
+            },
+        )
+
+        # Pre-execute fired with the prelim cell (no outputs yet)
+        assert len(obs.pre_calls) == 1
+        prelim = obs.pre_calls[0]
+        assert prelim.code == "print('hi')"
+        assert prelim.description == "say hi"
+        assert prelim.stdout == ""  # not yet executed
+        assert prelim.error is None
+
+        # Post-execute fired with the actual cell
+        assert len(obs.post_calls) == 1
+        actual = obs.post_calls[0]
+        assert actual.stdout == "hi"
+        assert actual.description == "say hi"
+
+        # The order: pre fires before pad.execute, post fires after
+        pad.execute.assert_awaited_once()
+
+    @pytest.mark.asyncio
+    async def test_exec_passes_error_cell_to_observer(self):
+        obs = _RecordingObserver()
+        cell = Cell(
+            code="x = 1/0",
+            stdout="",
+            stderr="",
+            error="ZeroDivisionError: division by zero",
+            description="divide by zero",
+        )
+        session, _ = _fake_session(observers=[obs], cell_to_return=cell)
+
+        await handle_scratchpad(
+            session,
+            {
+                "action": "exec",
+                "name": "main",
+                "code": "x = 1/0",
+                "one_line_description": "divide by zero",
+                "estimated_execution_time_seconds": 1,
+            },
+        )
+
+        assert len(obs.post_calls) == 1
+        assert obs.post_calls[0].error is not None
+        assert "ZeroDivisionError" in obs.post_calls[0].error
+
+    @pytest.mark.asyncio
+    async def test_exec_with_no_observers_works_unchanged(self):
+        # Empty observer list — exec should still work end-to-end
+        session, _ = _fake_session(observers=[])
+        result = await handle_scratchpad(
+            session,
+            {
+                "action": "exec",
+                "name": "main",
+                "code": "print('hi')",
+                "one_line_description": "say hi",
+                "estimated_execution_time_seconds": 1,
+            },
+        )
+        # Result is whatever format_cell_result returns — non-empty string
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+    @pytest.mark.asyncio
+    async def test_observer_exception_does_not_break_exec(self):
+        # An observer that throws on every call
+        bad = _RecordingObserver(
+            pre_raises=RuntimeError("pre boom"),
+            post_raises=RuntimeError("post boom"),
+        )
+        session, _ = _fake_session(observers=[bad])
+
+        # Exec should still complete and return a result
+        result = await handle_scratchpad(
+            session,
+            {
+                "action": "exec",
+                "name": "main",
+                "code": "print('hi')",
+                "one_line_description": "say hi",
+                "estimated_execution_time_seconds": 1,
+            },
+        )
+        assert isinstance(result, str)
+        # Both observer methods were called even though they raised
+        assert len(bad.pre_calls) == 1
+        assert len(bad.post_calls) == 1
+
+    @pytest.mark.asyncio
+    async def test_non_exec_actions_do_not_fire_observers(self):
+        """view, reset, install, dump, remove should not trigger observers."""
+        obs = _RecordingObserver()
+        session, _ = _fake_session(observers=[obs])
+
+        for action in ("view", "reset", "dump"):
+            await handle_scratchpad(
+                session, {"action": action, "name": "main"}
+            )
+
+        await handle_scratchpad(
+            session,
+            {"action": "install", "name": "main", "packages": ["x"]},
+        )
+        await handle_scratchpad(session, {"action": "remove", "name": "main"})
+
+        assert obs.pre_calls == []
+        assert obs.post_calls == []
diff --git a/tests/test_session_skills_init.py b/tests/test_session_skills_init.py
new file mode 100644
index 00000000..76c584af
--- /dev/null
+++ b/tests/test_session_skills_init.py
@@ -0,0 +1,126 @@
+"""Light wiring tests for skills integration in ChatSession.
+
+These tests don't construct a full ChatSession (it requires a live LLM
+client and many other dependencies). Instead they verify the *contract*
+points where session and skills meet:
+
+- The `recall_skill` tool is exported from its module and registers without error
+- The prompt builder accepts `skill_store` and renders the section
+- The store + tool dispatch round-trip works (this is what session.py wires)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from anton.core.llm.prompt_builder import ChatSystemPromptBuilder, SystemPromptContext
+from anton.core.memory.skills import Skill, SkillStore
+from anton.core.tools.recall_skill import RECALL_SKILL_TOOL, handle_recall_skill
+from anton.core.tools.registry import ToolRegistry
+
+
+@pytest.fixture()
+def store_with_one_skill(tmp_path: Path) -> SkillStore:
+    s = SkillStore(root=tmp_path / "skills")
+    s.save(
+        Skill(
+            label="csv_summary",
+            name="CSV Summary",
+            description="Load a CSV, infer schema, compute stats.",
+            when_to_use="User asks to explore or summarize a CSV file.",
+            declarative_md="1. Load CSV\n2. Describe\n3. Plot",
+            created_at="2026-04-10T12:00:00+00:00",
+            provenance="manual",
+        )
+    )
+    return s
+
+
+class TestRegistryRegistration:
+    def test_recall_skill_registers_without_collision(self):
+        registry = ToolRegistry()
+        registry.register_tool(RECALL_SKILL_TOOL)
+        names = [t.name for t in registry.get_tool_defs()]
+        assert "recall_skill" in names
+
+    def test_double_registration_is_idempotent(self):
+        registry = ToolRegistry()
+        registry.register_tool(RECALL_SKILL_TOOL)
+        registry.register_tool(RECALL_SKILL_TOOL)
+        names = [t.name for t in registry.get_tool_defs()]
+        assert names.count("recall_skill") == 1
+
+    def test_recall_skill_appears_in_dump(self):
+        registry = ToolRegistry()
+        registry.register_tool(RECALL_SKILL_TOOL)
+        dumped = registry.dump()
+        assert any(t["name"] == "recall_skill" for t in dumped)
+
+
+class TestPromptBuilderReceivesStore:
+    def test_section_appears_when_store_passed(
+        self, store_with_one_skill: SkillStore
+    ):
+        builder = ChatSystemPromptBuilder()
+        prompt = builder.build(
+            current_datetime="2026-04-10",
+            system_prompt_context=SystemPromptContext(runtime_context="test"),
+            proactive_dashboards=False,
+            skill_store=store_with_one_skill,
+        )
+        assert "## Procedural memory" in prompt
+        assert "csv_summary" in prompt
+
+    def test_section_omitted_when_no_store(self):
+        builder = ChatSystemPromptBuilder()
+        prompt = builder.build(
+            current_datetime="2026-04-10",
+            system_prompt_context=SystemPromptContext(runtime_context="test"),
+            proactive_dashboards=False,
+            skill_store=None,
+        )
+        assert "Procedural memory" not in prompt
+
+
+class TestDispatchRoundtrip:
+    """The end-to-end path: registry dispatches → handler reads store → counter bumps."""
+
+    @pytest.mark.asyncio
+    async def test_dispatch_recall_skill_through_registry(
+        self, store_with_one_skill: SkillStore
+    ):
+        registry = ToolRegistry()
+        registry.register_tool(RECALL_SKILL_TOOL)
+        # Minimal session-like object — only `_skill_store` is read by the handler.
+        session = SimpleNamespace(_skill_store=store_with_one_skill)
+
+        result = await registry.dispatch_tool(
+            session, "recall_skill", {"label": "csv_summary"}
+        )
+
+        assert "CSV Summary" in result
+        assert "Load CSV" in result
+        loaded = store_with_one_skill.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 1
+
+    @pytest.mark.asyncio
+    async def test_dispatch_unknown_label_through_registry(
+        self, store_with_one_skill: SkillStore
+    ):
+        registry = ToolRegistry()
+        registry.register_tool(RECALL_SKILL_TOOL)
+        session = SimpleNamespace(_skill_store=store_with_one_skill)
+
+        result = await registry.dispatch_tool(
+            session, "recall_skill", {"label": "nonexistent_xyz"}
+        )
+
+        assert "NO MATCH" in result
+        # Counter should NOT have moved
+        loaded = store_with_one_skill.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 0
diff --git a/tests/test_skill_commands.py b/tests/test_skill_commands.py
new file mode 100644
index 00000000..ee38d86f
--- /dev/null
+++ b/tests/test_skill_commands.py
@@ -0,0 +1,409 @@
+"""Tests for the /skill slash-command handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from rich.console import Console
+
+from anton.commands.skills import (
+    _format_history_turns,
+    _format_scratchpad_cells,
+    _gather_session_scratchpad_cells,
+    _SkillDraft,
+    handle_skill_remove,
+    handle_skill_save,
+    handle_skill_show,
+    handle_skills_list,
+)
+from anton.core.memory.skills import Skill, SkillStore
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fixtures
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture()
+def store(tmp_path: Path) -> SkillStore:
+    return SkillStore(root=tmp_path / "skills")
+
+
+@pytest.fixture()
+def console() -> Console:
+    # Capture-friendly console; record=True lets us read output if needed
+    return Console(record=True, width=120)
+
+
+def _fake_cell(code: str, stdout: str = "ok", stderr: str = "", error=None):
+    return SimpleNamespace(
+        code=code, stdout=stdout, stderr=stderr, error=error, description=""
+    )
+
+
+def _make_session(
+    *,
+    draft: _SkillDraft | None = None,
+    raises: Exception | None = None,
+    cells: list | None = None,
+    history: list | None = None,
+) -> MagicMock:
+    """Build a fake session whose `_llm.generate_object()` returns a known draft.
+
+    Pass `draft` to return a specific `_SkillDraft`, or `raises` to make
+    the call raise that exception.
+    """
+    session = MagicMock()
+    session._history = history or []
+    pad = SimpleNamespace(cells=cells or [])
+    session._scratchpads = SimpleNamespace(_pads={"main": pad})
+    session._llm = MagicMock()
+    if raises is not None:
+        session._llm.generate_object = AsyncMock(side_effect=raises)
+    else:
+        session._llm.generate_object = AsyncMock(return_value=draft)
+    return session
+
+
+def _draft(
+    *,
+    label: str = "csv_summary",
+    name: str = "CSV Summary",
+    description: str = "",
+    when_to_use: str = "When summarizing CSV files.",
+    declarative_md: str = "1. Load.\n2. Describe.",
+) -> _SkillDraft:
+    """Convenience constructor for test drafts."""
+    return _SkillDraft(
+        label=label,
+        name=name,
+        description=description,
+        when_to_use=when_to_use,
+        declarative_md=declarative_md,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helper unit tests
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestFormatScratchpadCells:
+    def test_empty(self):
+        assert "no scratchpad" in _format_scratchpad_cells([])
+
+    def test_renders_code_and_output(self):
+        cells = [_fake_cell(code="print(1+1)", stdout="2")]
+        out = _format_scratchpad_cells(cells)
+        assert "print(1+1)" in out
+        assert "2" in out
+        assert "Cell 1" in out
+
+    def test_truncates_long_code(self):
+        long_code = "x = 1\n" * 1000
+        cells = [_fake_cell(code=long_code, stdout="")]
+        out = _format_scratchpad_cells(cells)
+        assert "[truncated]" in out
+
+
+class TestFormatHistoryTurns:
+    def test_empty(self):
+        assert "no conversation" in _format_history_turns([])
+
+    def test_string_content(self):
+        history = [
+            {"role": "user", "content": "hi"},
+            {"role": "assistant", "content": "hello back"},
+        ]
+        out = _format_history_turns(history)
+        assert "hi" in out
+        assert "hello back" in out
+
+    def test_structured_content_with_text_blocks(self):
+        history = [
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "the answer"},
+                    {"type": "tool_use", "id": "x", "name": "y", "input": {}},
+                ],
+            }
+        ]
+        out = _format_history_turns(history)
+        assert "the answer" in out
+
+    def test_skips_empty_turns(self):
+        history = [
+            {"role": "user", "content": ""},
+            {"role": "assistant", "content": "hello"},
+        ]
+        out = _format_history_turns(history)
+        assert "hello" in out
+
+    def test_max_turns_limit(self):
+        history = [
+            {"role": "user", "content": f"msg {i}"} for i in range(20)
+        ]
+        out = _format_history_turns(history, max_turns=3)
+        # Should only include the last 3
+        assert "msg 19" in out
+        assert "msg 17" in out
+        assert "msg 15" not in out
+
+
+class TestGatherSessionCells:
+    def test_collects_from_multiple_pads(self):
+        pad_a = SimpleNamespace(cells=[_fake_cell("a")])
+        pad_b = SimpleNamespace(cells=[_fake_cell("b"), _fake_cell("c")])
+        session = SimpleNamespace(
+            _scratchpads=SimpleNamespace(_pads={"a": pad_a, "b": pad_b})
+        )
+        cells = _gather_session_scratchpad_cells(session)
+        assert len(cells) == 3
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# /skill save
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestSkillSave:
+    @pytest.mark.asyncio
+    async def test_happy_path(self, console, store):
+        session = _make_session(
+            draft=_draft(
+                label="csv_summary",
+                name="CSV Summary",
+                description="Load and summarize a CSV.",
+                when_to_use="User asks to summarize a CSV file.",
+                declarative_md="1. Load.\n2. Describe.\n3. Plot.",
+            ),
+            cells=[_fake_cell("import pandas as pd; df = pd.read_csv('x.csv')")],
+            history=[{"role": "user", "content": "summarize x.csv"}],
+        )
+
+        await handle_skill_save(console, session, store=store)
+
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.name == "CSV Summary"
+        assert loaded.when_to_use == "User asks to summarize a CSV file."
+        assert "Load." in loaded.declarative_md
+        assert loaded.provenance == "manual"
+        assert loaded.created_at  # ISO timestamp set
+
+    @pytest.mark.asyncio
+    async def test_passes_skill_draft_schema_to_llm(self, console, store):
+        """generate_object should be called with the _SkillDraft Pydantic class."""
+        session = _make_session(
+            draft=_draft(),
+            cells=[_fake_cell("x")],
+            history=[{"role": "user", "content": "go"}],
+        )
+        await handle_skill_save(console, session, store=store)
+        session._llm.generate_object.assert_called_once()
+        call_args = session._llm.generate_object.call_args
+        assert call_args.args[0] is _SkillDraft
+
+    @pytest.mark.asyncio
+    async def test_label_collision_appends_number(self, console, store):
+        # Pre-existing skill with the label the LLM will return
+        store.save(
+            Skill(
+                label="csv_summary",
+                name="Existing",
+                description="",
+                when_to_use="",
+                declarative_md="prior",
+                created_at="2026-04-09T00:00:00+00:00",
+                provenance="manual",
+            )
+        )
+        session = _make_session(
+            draft=_draft(
+                label="csv_summary",
+                name="New CSV Summary",
+                description="",
+                when_to_use="User asks for CSV stats.",
+                declarative_md="step 1",
+            ),
+            cells=[_fake_cell("x")],
+            history=[{"role": "user", "content": "go"}],
+        )
+
+        await handle_skill_save(console, session, store=store)
+
+        # Original is unchanged
+        original = store.load("csv_summary")
+        assert original is not None
+        assert original.declarative_md == "prior"
+        # New one was saved with a unique label
+        new = store.load("csv_summary_2")
+        assert new is not None
+        assert new.declarative_md == "step 1"
+
+    @pytest.mark.asyncio
+    async def test_name_hint_is_passed_to_llm(self, console, store):
+        session = _make_session(
+            draft=_draft(
+                label="data_loader",
+                name="Data Loader",
+                when_to_use="User asks to load data.",
+            ),
+            cells=[_fake_cell("x")],
+            history=[{"role": "user", "content": "go"}],
+        )
+
+        await handle_skill_save(
+            console, session, name_hint="data loader", store=store
+        )
+
+        # The hint should appear in the prompt sent to the LLM
+        call_args = session._llm.generate_object.call_args
+        user_msg = call_args.kwargs["messages"][0]["content"]
+        assert "data loader" in user_msg
+
+    @pytest.mark.asyncio
+    async def test_empty_procedure_refuses_save(self, console, store):
+        session = _make_session(
+            draft=_draft(
+                label="empty",
+                name="Empty",
+                when_to_use="x",
+                declarative_md="",  # blank — refuse
+            ),
+            cells=[_fake_cell("x")],
+            history=[{"role": "user", "content": "go"}],
+        )
+        await handle_skill_save(console, session, store=store)
+        assert store.list_all() == []
+
+    @pytest.mark.asyncio
+    async def test_no_work_in_session_aborts(self, console, store):
+        session = _make_session(
+            draft=_draft(),
+            cells=[],
+            history=[],
+        )
+        await handle_skill_save(console, session, store=store)
+        # No LLM call was even made
+        session._llm.generate_object.assert_not_called()
+        assert store.list_all() == []
+
+    @pytest.mark.asyncio
+    async def test_llm_exception_is_caught(self, console, store):
+        session = _make_session(
+            raises=RuntimeError("network down"),
+            cells=[_fake_cell("x")],
+            history=[{"role": "user", "content": "go"}],
+        )
+        # Must not raise
+        await handle_skill_save(console, session, store=store)
+        assert store.list_all() == []
+
+    @pytest.mark.asyncio
+    async def test_validation_error_is_caught(self, console, store):
+        """If the LLM produces output that fails Pydantic validation
+        (rare with forced tool_choice but possible), we surface a
+        warning and don't save anything."""
+        from pydantic import ValidationError as _PVE
+
+        try:
+            _SkillDraft.model_validate({})  # missing required fields
+        except _PVE as exc:
+            session = _make_session(
+                raises=exc,
+                cells=[_fake_cell("x")],
+                history=[{"role": "user", "content": "go"}],
+            )
+        await handle_skill_save(console, session, store=store)
+        assert store.list_all() == []
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# /skills list, /skill show, /skill remove
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestListShowRemove:
+    def test_list_empty(self, console, store):
+        # Should not raise
+        handle_skills_list(console, store=store)
+
+    def test_list_with_skills(self, console, store):
+        store.save(
+            Skill(
+                label="csv_summary",
+                name="CSV Summary",
+                description="",
+                when_to_use="When the user asks about a CSV",
+                declarative_md="step",
+                created_at="2026-04-10T00:00:00+00:00",
+                provenance="manual",
+            )
+        )
+        handle_skills_list(console, store=store)
+        # Sanity-check that the rendered output mentions the label
+        out = console.export_text()
+        assert "csv_summary" in out
+
+    def test_show_existing(self, console, store):
+        store.save(
+            Skill(
+                label="csv_summary",
+                name="CSV Summary",
+                description="A CSV utility.",
+                when_to_use="when needed",
+                declarative_md="1. Load\n2. Describe",
+                created_at="2026-04-10T00:00:00+00:00",
+                provenance="manual",
+            )
+        )
+        handle_skill_show(console, "csv_summary", store=store)
+        out = console.export_text()
+        assert "CSV Summary" in out
+        assert "Load" in out
+
+    def test_show_unknown_suggests_closest(self, console, store):
+        store.save(
+            Skill(
+                label="csv_summary",
+                name="CSV",
+                description="",
+                when_to_use="",
+                declarative_md="x",
+                created_at="2026-04-10T00:00:00+00:00",
+                provenance="manual",
+            )
+        )
+        handle_skill_show(console, "csv_sumary", store=store)  # typo
+        out = console.export_text()
+        assert "csv_summary" in out
+
+    def test_show_no_args(self, console, store):
+        handle_skill_show(console, "", store=store)
+        out = console.export_text()
+        assert "Usage" in out
+
+    def test_remove_existing(self, console, store):
+        store.save(
+            Skill(
+                label="zap",
+                name="Zap",
+                description="",
+                when_to_use="",
+                declarative_md="x",
+                created_at="2026-04-10T00:00:00+00:00",
+                provenance="manual",
+            )
+        )
+        handle_skill_remove(console, "zap", store=store)
+        assert store.load("zap") is None
+
+    def test_remove_unknown(self, console, store):
+        handle_skill_remove(console, "nope", store=store)
+        out = console.export_text()
+        assert "No skill" in out
diff --git a/tests/test_skills_e2e.py b/tests/test_skills_e2e.py
new file mode 100644
index 00000000..3c673ac4
--- /dev/null
+++ b/tests/test_skills_e2e.py
@@ -0,0 +1,186 @@
+"""End-to-end test of the skills loop.
+
+Simulates the full happy path with mocked LLM at each call site:
+
+1. Save a skill from recent work via `/skill save` (mock LLM drafts JSON)
+2. "Restart" by building a fresh prompt — the saved skill appears in the
+   procedural memory section
+3. Simulate the LLM calling `recall_skill(label)` via the tool registry
+4. Verify the tool result + counter increment
+5. Recall again with a typo — closest_match recovers, counter increments
+
+This is the test that proves the loop is wired correctly across all
+prior steps. If it passes, the v1 build is functional end-to-end.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from rich.console import Console
+
+from anton.commands.skills import _SkillDraft, handle_skill_save
+from anton.core.llm.prompt_builder import ChatSystemPromptBuilder, SystemPromptContext
+from anton.core.memory.skills import SkillStore
+from anton.core.tools.recall_skill import RECALL_SKILL_TOOL
+from anton.core.tools.registry import ToolRegistry
+
+
+@pytest.fixture()
+def store_root(tmp_path: Path) -> Path:
+    return tmp_path / "skills"
+
+
+@pytest.fixture()
+def console() -> Console:
+    return Console(record=True, width=120)
+
+
+def _make_session_for_save(
+    store: SkillStore, draft: _SkillDraft, cells: list, history: list
+) -> MagicMock:
+    """A session-like mock with the LLM ready to return `draft`."""
+    session = MagicMock()
+    session._history = history
+    session._skill_store = store
+    pad = SimpleNamespace(cells=cells)
+    session._scratchpads = SimpleNamespace(_pads={"work": pad})
+    session._llm = MagicMock()
+    session._llm.generate_object = AsyncMock(return_value=draft)
+    return session
+
+
+def _fake_cell(code: str, stdout: str = "ok"):
+    return SimpleNamespace(
+        code=code, stdout=stdout, stderr="", error=None, description=""
+    )
+
+
+@pytest.mark.asyncio
+async def test_full_skills_loop(console, store_root):
+    # ── Setup: empty store, simulated session with some scratchpad work ─
+    store = SkillStore(root=store_root)
+    assert store.list_all() == []
+
+    cells = [
+        _fake_cell(
+            "import pandas as pd\n"
+            "df = pd.read_csv('sales_q3.csv')\n"
+            "print(df.shape)",
+            stdout="(12000, 8)",
+        ),
+        _fake_cell(
+            "print(df.describe())\n"
+            "print(df.dtypes)",
+            stdout="<summary statistics>",
+        ),
+        _fake_cell(
+            "df['amount'].plot.hist(bins=30)",
+            stdout="<plot>",
+        ),
+    ]
+    history = [
+        {"role": "user", "content": "take a quick look at sales_q3.csv"},
+        {
+            "role": "assistant",
+            "content": "Loaded the CSV and summarized it. 12k rows, 8 cols.",
+        },
+    ]
+
+    draft = _SkillDraft(
+        label="csv_summary",
+        name="CSV Summary",
+        description="Load a CSV with pandas, print shape/describe/dtypes, plot a histogram.",
+        when_to_use="User asks to explore, summarize, or describe a CSV file.",
+        declarative_md=(
+            "1. Use `pandas.read_csv()` to load the file.\n"
+            "2. Print `df.shape` and `df.dtypes`.\n"
+            "3. Run `df.describe()` for summary stats.\n"
+            "4. For numeric columns of interest, plot a histogram with "
+            "`df[col].plot.hist(bins=30)`."
+        ),
+    )
+    session = _make_session_for_save(store, draft, cells, history)
+
+    # ── Step 1: /skill save ─────────────────────────────────────────────
+    await handle_skill_save(console, session, store=store)
+
+    skills = store.list_all()
+    assert len(skills) == 1
+    saved = skills[0]
+    assert saved.label == "csv_summary"
+    assert saved.name == "CSV Summary"
+    assert "pandas.read_csv" in saved.declarative_md
+    assert saved.stats.stage_1.recommended == 0  # no recalls yet
+
+    # ── Step 2: "restart" — build a fresh system prompt ─────────────────
+    # This simulates a new session reading the same disk store
+    fresh_store = SkillStore(root=store_root)
+    builder = ChatSystemPromptBuilder()
+    prompt = builder.build(
+        current_datetime="2026-04-10T13:00:00+00:00",
+        system_prompt_context=SystemPromptContext(runtime_context="test"),
+        proactive_dashboards=False,
+        skill_store=fresh_store,
+    )
+    assert "## Procedural memory" in prompt
+    assert "`csv_summary`" in prompt
+    assert "explore, summarize, or describe a CSV" in prompt
+
+    # ── Step 3: LLM "decides" to recall the skill via the tool registry ─
+    registry = ToolRegistry()
+    registry.register_tool(RECALL_SKILL_TOOL)
+    fresh_session = SimpleNamespace(_skill_store=fresh_store)
+
+    result = await registry.dispatch_tool(
+        fresh_session, "recall_skill", {"label": "csv_summary"}
+    )
+
+    assert "CSV Summary" in result
+    assert "pandas.read_csv" in result
+    assert "describe" in result
+
+    # Counter incremented to 1
+    after_recall_1 = fresh_store.load("csv_summary")
+    assert after_recall_1 is not None
+    assert after_recall_1.stats.stage_1.recommended == 1
+    assert after_recall_1.stats.total_recalls == 1
+    assert after_recall_1.stats.stage_1.last_used  # ISO timestamp present
+
+    # ── Step 4: Recall again with a typo — closest_match recovers ───────
+    typo_result = await registry.dispatch_tool(
+        fresh_session, "recall_skill", {"label": "csv_sumary"}  # missing 'm'
+    )
+    assert "⚠" in typo_result
+    assert "csv_summary" in typo_result
+    assert "pandas.read_csv" in typo_result  # full procedure still returned
+
+    # Counter is now 2 (typo credited to the resolved label)
+    after_recall_2 = fresh_store.load("csv_summary")
+    assert after_recall_2 is not None
+    assert after_recall_2.stats.stage_1.recommended == 2
+    assert after_recall_2.stats.total_recalls == 2
+
+    # ── Step 5: Disk verification ───────────────────────────────────────
+    skill_dir = store_root / "csv_summary"
+    assert skill_dir.is_dir()
+    assert (skill_dir / "meta.json").is_file()
+    assert (skill_dir / "declarative.md").is_file()
+    assert (skill_dir / "stats.json").is_file()
+
+    stats_on_disk = json.loads((skill_dir / "stats.json").read_text())
+    assert stats_on_disk["total_recalls"] == 2
+    assert stats_on_disk["stage_1"]["recommended"] == 2
+
+    meta_on_disk = json.loads((skill_dir / "meta.json").read_text())
+    assert meta_on_disk["label"] == "csv_summary"
+    assert meta_on_disk["stage_1_present"] is True
+    assert meta_on_disk["stage_2_present"] is False
+    assert meta_on_disk["stage_3_present"] is False
+
+    declarative_on_disk = (skill_dir / "declarative.md").read_text()
+    assert "pandas.read_csv" in declarative_on_disk
diff --git a/tests/test_skills_store.py b/tests/test_skills_store.py
new file mode 100644
index 00000000..f843ce1f
--- /dev/null
+++ b/tests/test_skills_store.py
@@ -0,0 +1,302 @@
+"""Storage-layer tests for `anton.core.memory.skills`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from anton.core.memory.skills import (
+    Skill,
+    SkillStats,
+    SkillStore,
+    StageStats,
+    make_unique_label,
+    slugify,
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fixtures
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture()
+def store_root(tmp_path: Path) -> Path:
+    return tmp_path / "skills"
+
+
+@pytest.fixture()
+def store(store_root: Path) -> SkillStore:
+    return SkillStore(root=store_root)
+
+
+def _make_skill(label: str = "csv_summary", **overrides) -> Skill:
+    base = dict(
+        label=label,
+        name="CSV Summary",
+        description="Load a CSV, infer schema, compute summary stats.",
+        when_to_use="User asks to explore, summarize, or describe a CSV file.",
+        declarative_md="1. Load the CSV.\n2. Infer types.\n3. Print summary.\n",
+        created_at="2026-04-10T12:00:00+00:00",
+        provenance="manual",
+    )
+    base.update(overrides)
+    return Skill(**base)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# slugify / make_unique_label
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestSlugify:
+    def test_simple_lowercase(self):
+        assert slugify("CSV Summary") == "csv_summary"
+
+    def test_strips_special_chars(self):
+        assert slugify("Web Scraping (v2)!") == "web_scraping_v2"
+
+    def test_collapses_underscores(self):
+        assert slugify("foo___bar") == "foo_bar"
+
+    def test_trims_leading_trailing(self):
+        assert slugify("__hello__") == "hello"
+
+    def test_empty_input_falls_back(self):
+        assert slugify("") == "skill"
+        assert slugify("   ") == "skill"
+        assert slugify("!@#$") == "skill"
+
+    def test_dash_to_underscore(self):
+        assert slugify("api-data-fetcher") == "api_data_fetcher"
+
+
+class TestMakeUniqueLabel:
+    def test_returns_base_when_unique(self, store: SkillStore):
+        assert make_unique_label("Brand New", store) == "brand_new"
+
+    def test_appends_number_on_collision(self, store: SkillStore):
+        store.save(_make_skill(label="csv_summary"))
+        assert make_unique_label("CSV Summary", store) == "csv_summary_2"
+
+    def test_chains_numbers(self, store: SkillStore):
+        store.save(_make_skill(label="csv_summary"))
+        store.save(_make_skill(label="csv_summary_2"))
+        store.save(_make_skill(label="csv_summary_3"))
+        assert make_unique_label("CSV Summary", store) == "csv_summary_4"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Save / load round-trip
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestSaveLoadRoundtrip:
+    def test_save_creates_directory_with_required_files(
+        self, store: SkillStore, store_root: Path
+    ):
+        skill = _make_skill()
+        path = store.save(skill)
+        assert path == store_root / "csv_summary"
+        assert (path / "meta.json").is_file()
+        assert (path / "declarative.md").is_file()
+        assert (path / "stats.json").is_file()
+
+    def test_load_after_save_round_trip(self, store: SkillStore):
+        original = _make_skill()
+        store.save(original)
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.label == original.label
+        assert loaded.name == original.name
+        assert loaded.description == original.description
+        assert loaded.when_to_use == original.when_to_use
+        assert loaded.declarative_md == original.declarative_md
+        assert loaded.provenance == "manual"
+
+    def test_load_unknown_returns_none(self, store: SkillStore):
+        assert store.load("does_not_exist") is None
+
+    def test_load_with_corrupt_meta_returns_none(
+        self, store: SkillStore, store_root: Path
+    ):
+        store.save(_make_skill())
+        (store_root / "csv_summary" / "meta.json").write_text("not json{")
+        assert store.load("csv_summary") is None
+
+    def test_save_does_not_wipe_existing_stats(
+        self, store: SkillStore, store_root: Path
+    ):
+        # First save initializes stats.json with zeroes.
+        store.save(_make_skill())
+        # Simulate accumulated counters.
+        store.increment_recommended("csv_summary", stage=1)
+        store.increment_recommended("csv_summary", stage=1)
+        # Saving again (e.g., editing the procedure) must NOT zero them.
+        store.save(_make_skill(declarative_md="updated procedure"))
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 2
+        assert loaded.declarative_md == "updated procedure"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# list_all / list_summaries / delete
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestListing:
+    def test_list_all_empty(self, store: SkillStore):
+        assert store.list_all() == []
+
+    def test_list_summaries_empty(self, store: SkillStore):
+        assert store.list_summaries() == []
+
+    def test_list_all_returns_sorted(self, store: SkillStore):
+        store.save(_make_skill(label="zebra", name="Zebra"))
+        store.save(_make_skill(label="alpha", name="Alpha"))
+        store.save(_make_skill(label="mike", name="Mike"))
+        labels = [s.label for s in store.list_all()]
+        assert labels == ["alpha", "mike", "zebra"]
+
+    def test_list_summaries_skips_malformed(
+        self, store: SkillStore, store_root: Path
+    ):
+        store.save(_make_skill(label="good"))
+        # Create a directory with no meta.json — should be skipped.
+        (store_root / "broken").mkdir()
+        summaries = store.list_summaries()
+        assert [s["label"] for s in summaries] == ["good"]
+
+    def test_list_summaries_lightweight_shape(self, store: SkillStore):
+        store.save(_make_skill())
+        summaries = store.list_summaries()
+        assert len(summaries) == 1
+        assert summaries[0] == {
+            "label": "csv_summary",
+            "name": "CSV Summary",
+            "when_to_use": "User asks to explore, summarize, or describe a CSV file.",
+        }
+
+    def test_delete_removes_directory(self, store: SkillStore, store_root: Path):
+        store.save(_make_skill())
+        assert (store_root / "csv_summary").is_dir()
+        assert store.delete("csv_summary") is True
+        assert not (store_root / "csv_summary").exists()
+
+    def test_delete_unknown_returns_false(self, store: SkillStore):
+        assert store.delete("nope") is False
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Stats increments
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestStatsIncrement:
+    def test_increment_unknown_skill_is_noop(self, store: SkillStore):
+        # Should not raise.
+        store.increment_recommended("not_a_skill", stage=1)
+
+    def test_increment_stage_1(self, store: SkillStore):
+        store.save(_make_skill())
+        store.increment_recommended("csv_summary", stage=1)
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 1
+        assert loaded.stats.stage_1.last_used  # set to a timestamp
+        assert loaded.stats.total_recalls == 1
+
+    def test_increment_multiple_times(self, store: SkillStore):
+        store.save(_make_skill())
+        for _ in range(5):
+            store.increment_recommended("csv_summary", stage=1)
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 5
+        assert loaded.stats.total_recalls == 5
+
+    def test_increment_per_stage_independent(self, store: SkillStore):
+        store.save(_make_skill())
+        store.increment_recommended("csv_summary", stage=1)
+        store.increment_recommended("csv_summary", stage=1)
+        store.increment_recommended("csv_summary", stage=2)
+        loaded = store.load("csv_summary")
+        assert loaded is not None
+        assert loaded.stats.stage_1.recommended == 2
+        assert loaded.stats.stage_2.recommended == 1
+        assert loaded.stats.stage_3.recommended == 0
+        assert loaded.stats.total_recalls == 3
+
+    def test_invalid_stage_raises(self, store: SkillStore):
+        store.save(_make_skill())
+        with pytest.raises(ValueError):
+            store.increment_recommended("csv_summary", stage=4)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# closest_match — typo recovery
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestClosestMatch:
+    def test_empty_store_returns_none(self, store: SkillStore):
+        assert store.closest_match("anything") is None
+
+    def test_exact_match(self, store: SkillStore):
+        store.save(_make_skill(label="csv_summary"))
+        assert store.closest_match("csv_summary") == "csv_summary"
+
+    def test_typo_one_char(self, store: SkillStore):
+        store.save(_make_skill(label="csv_summary"))
+        assert store.closest_match("csv_sumary") == "csv_summary"
+
+    def test_dash_vs_underscore(self, store: SkillStore):
+        store.save(_make_skill(label="web_scraping"))
+        assert store.closest_match("web-scraping") == "web_scraping"
+
+    def test_completely_unrelated_returns_none(self, store: SkillStore):
+        store.save(_make_skill(label="csv_summary"))
+        assert store.closest_match("xyzzy_quark") is None
+
+    def test_picks_closer_of_two_candidates(self, store: SkillStore):
+        store.save(_make_skill(label="csv_summary"))
+        store.save(_make_skill(label="api_fetcher"))
+        # Closer to csv_summary
+        assert store.closest_match("csv_summery") == "csv_summary"
+        # Closer to api_fetcher
+        assert store.closest_match("api_fecher") == "api_fetcher"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Disk format sanity (catches accidental schema drift)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestDiskFormat:
+    def test_meta_json_has_expected_keys(self, store: SkillStore, store_root: Path):
+        store.save(_make_skill())
+        meta = json.loads((store_root / "csv_summary" / "meta.json").read_text())
+        assert set(meta.keys()) >= {
+            "label",
+            "name",
+            "description",
+            "when_to_use",
+            "created_at",
+            "provenance",
+            "stage_1_present",
+            "stage_2_present",
+            "stage_3_present",
+        }
+        assert meta["label"] == "csv_summary"
+
+    def test_stats_json_initial_shape(self, store: SkillStore, store_root: Path):
+        store.save(_make_skill())
+        stats = json.loads((store_root / "csv_summary" / "stats.json").read_text())
+        assert stats["total_recalls"] == 0
+        for stage_key in ("stage_1", "stage_2", "stage_3"):
+            assert stage_key in stats
+            assert stats[stage_key]["recommended"] == 0
+            assert stats[stage_key]["used"] == 0