diff --git a/.gitignore b/.gitignore
index d7bcb79..abc39c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,11 @@ docs/.vitepress/dist/
 docs/.vitepress/cache/
 .DS_Store
 .mitii
+
+# Mitii local runtime data
+.mitii/
+.mitii-session-export.json
+.mitii-audit-pack.json
+
+modules_explanation
+.vscode
\ No newline at end of file
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index a53ecb6..b646ee6 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -28,6 +28,8 @@ export default defineConfig({
       { text: 'Getting Started', link: '/getting-started/' },
       { text: 'Features', link: '/features/' },
       { text: 'Architecture', link: '/architecture' },
+      { text: 'CLI', link: '/cli/' },
+      { text: 'SDK', link: '/sdk/' },
       { text: 'Website', link: WEBSITE_URL },
       {
         text: 'Community',
@@ -52,8 +54,10 @@ export default defineConfig({
         text: 'Guide',
         items: [
           { text: 'Features', link: '/features/' },
-          { text: 'Configuration', link: '/configuration' },
           { text: 'Architecture', link: '/architecture' },
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'CLI', link: '/cli/' },
+          { text: 'SDK', link: '/sdk/' },
           { text: 'Development', link: '/development' },
         ],
       },
diff --git a/docs/architecture.md b/docs/architecture.md
index 29dc439..e01e870 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,25 +1,47 @@
 # Architecture
 
-Mitii is a VS Code extension with a local agent core — **no central server required**. All workspace intelligence lives in `.mitii/` on your machine.
+Mitii is a **host-neutral coding-agent runtime**. It works the same way whether you're using it from VS Code, a terminal, or a script.
 
-## System diagram
+```text
+Validated Input → Cohesive Pipeline → Validated Result
+```
+
+The core (`@mitii/v8`) is framework-agnostic. Hosts inject ports (filesystem, process, network) and render structured events. All workspace intelligence lives in `.mitii/` on your machine — **no central server, no cloud dependency**.
+
+## How it fits together
 
 ```mermaid
 flowchart TB
-  subgraph VSCode["VS Code"]
-    WV[React Webview UI]
-    TC[ThunderController]
-    WV <-->|postMessage| TC
+  subgraph Host["Host (VS Code / CLI / Daemon)"]
+    UI[UI / Terminal]
+    PORTS["Host Ports: FS, Process, Network, Git"]
+    UI <--> PORTS
   end
 
-  subgraph Core["Agent core"]
-    CO[ChatOrchestrator]
-    AL[AgentLoop]
-    PE[PlanExecutor]
-    TR[ToolRuntime]
-    TPE[ToolPolicyEngine]
-    AQ[ApprovalQueue]
-    TE[ToolExecutor]
+  subgraph SDK["@mitii/sdk"]
+    CLIENT[createMitiiClient]
+    START["client.start / resume"]
+    CLIENT --> START
+  end
+
+  subgraph V8["@mitii/v8 — Agent Runtime"]
+    INTAKE[Request Intake]
+    UNDERSTAND[Request Understanding]
+    DP[Decision Policy]
+    AE[Agent Engine]
+    REPO[Repository State]
+    CTX[Repository Context]
+    SKILLS[Skills]
+    MEM[Memory]
+    PLAN[Planning]
+    PROMPT[Prompt Construction]
+    MODEL[Model Gateway]
+    TR[Tool Runtime]
+    VERIFY[Verification]
+    CI[Change Impact]
+    CN[Code Navigation]
+    BUDGET[Window Budget]
+    TASK[Task List]
   end
 
   subgraph Data["Local data (.mitii/)"]
@@ -28,50 +50,80 @@ flowchart TB
     CP[checkpoints/]
   end
 
-  subgraph Context["Context pipeline"]
-    HR[HybridRetriever]
-    CB[ContextBudgeter]
-    RR[Reranker]
-  end
+  UI --> CLIENT
+  START --> INTAKE --> UNDERSTAND --> DP
+  DP -->|ExecutionDecision| AE
+  AE --> REPO --> CTX
+  AE --> SKILLS
+  AE --> MEM
+  AE --> PLAN
+  AE --> BUDGET
+  AE --> PROMPT --> MODEL
+  MODEL --> AE
+  AE --> TR
+  TR --> PORTS
+  AE --> VERIFY
+  AE --> CI
+  AE --> CN
+  AE --> TASK
+  TR --> SQL
+  AE --> LOGS
+  AE --> CP
+```
 
-  TC --> CO
-  CO --> HR --> RR --> CB
-  CO --> AL
-  CO --> PE
-  AL --> TE --> TPE --> AQ
-  TE --> TR
-  TC --> SQL
-  TC --> MCP[McpManager]
-  TC --> LLM[LlmProviderRegistry]
+## What each module does
+
+| Module | What it does |
+|--------|-------------|
+| **Request Intake** | Validates your input, normalizes attachments and conversation metadata into a clean request envelope |
+| **Request Understanding** | Figures out what you actually want — intent, targets, constraints, scope, risk, and whether clarification is needed |
+| **Decision Policy** | The authority module. Converts understanding into one `ExecutionDecision`: which route to take, how deep to plan, what tools are allowed, and what needs approval |
+| **Agent Engine** | The orchestrator. Sequences every stage of a run, manages the model/tool loop, handles suspension/resume, checkpoints, and emits structured events |
+| **Repository State** | Builds and maintains the single authoritative index of your codebase — discovery, ignore rules, project catalog, FTS, vectors, symbols, and the dependency graph |
+| **Repository Context** | Retrieves the most relevant code for a query within a token budget — hybrid search, deduplication, diversity selection, and safe assembly |
+| **Skills** | Selects and budgets instruction blocks (SKILL.md files) that guide the agent's behavior for the current task |
+| **Memory** | Durable facts scoped to user / workspace / project. Supplies prior preferences and decisions to prompt construction |
+| **Planning** | Drafts a dimension-driven plan (scope, risk, complexity) when the decision calls for it. Validates, compacts, and serializes the result |
+| **Task List** | Maintains a compact working checklist (max 8 items) derived from the plan. Tracks progress without stamping items done prematurely |
+| **Prompt Construction** | Assembles the final model prompt from context, memory, skills, task context, and the window budget — with provenance and an omission report |
+| **Window Budget** | Computes the usable input/output split from the model's context window, reserving space for output, mutations, planning, skills, and compaction |
+| **Model Gateway** | Provider-agnostic LLM streaming (Anthropic, OpenAI, Gemini, OpenAI-compatible). Handles capability negotiation, usage tracking, and retry classification |
+| **Tool Runtime** | The enforcement layer. Validates every tool call against the `ToolGrant`, executes via host ports, sanitizes output, enforces timeouts, and supports mutation rollback |
+| **Verification** | Runs applicable checks (lint, typecheck, tests) after changes. Only Verification can authorize `verified_success` — the model cannot self-certify |
+| **Change Impact** | Blast-radius estimation. Walks the repository graph from a file, symbol, or caret to find affected callers, importers, and package dependents |
+| **Code Navigation** | Read-only source navigation — resolves definitions, references, and hover info via language server or repository graph |
+
+## A run, step by step
+
+1. **You send a prompt** (sidebar, terminal, or SDK `client.start()`)
+2. **Request Intake** validates and normalizes it
+3. **Request Understanding** extracts intent, scope, risk, and clarity
+4. **Decision Policy** emits the `ExecutionDecision` — route, plan depth, tool grants, approval gates
+5. **Agent Engine** pins repository state and coordinates the run
+6. **Repository State** + **Repository Context** provide indexed, budgeted code context
+7. **Skills**, **Memory**, and **Planning** contribute instructions and durable facts
+8. **Window Budget** computes the token split; **Prompt Construction** assembles the final prompt
+9. **Model Gateway** streams the response; tool calls route to **Tool Runtime**
+10. **Tool Runtime** validates, executes, and returns bounded results
+11. **Agent Engine** enforces budgets, persists checkpoints at gates, and emits `RunEvent`s
+12. **Verification** runs checks and produces the final result state
+
+### Run states
+
+```text
+Active:     received → understood → decided → context_ready → model_running ⇄ tool_running → verifying
+Suspended:  clarification_required | approval_required
+Terminal:   completed | approval_denied | cancelled | budget_exhausted | failed
 ```
 
-## Component responsibilities
-
-| Component | Role |
-|-----------|------|
-| **ThunderController** | Central orchestrator — wires services, handles webview messages, workspace reload |
-| **ChatOrchestrator** | Turn pipeline: retrieve → prompt → plan or agent loop → verify |
-| **AgentLoop** | LLM ↔ tool round-trip in Agent mode |
-| **PlanExecutor** | Multi-step planner in Plan mode |
-| **HybridRetriever** | Merges FTS, vectors, rules, git, diagnostics, memory |
-| **ContextBudgeter** | Fits context into model token window |
-| **ToolPolicyEngine** | allow / require_approval / block per tool |
-| **ApprovalQueue** | Pending human approvals |
-| **CheckpointService** | Git-stash or file-copy snapshots |
-| **MemoryService** | Long-term observations store |
-| **McpManager** | Stdio / SSE / HTTP MCP connections |
-| **LlmProviderRegistry** | Resolves provider by type and mode |
-
-## Request lifecycle
-
-1. User sends message in sidebar webview
-2. **ThunderSession** mode (`ask` | `plan` | `agent` | `review`) selects tool policy
-3. **HybridRetriever** gathers context from tiered sources (parallel, 800ms timeout each)
-4. **Reranker** trims candidates; **ContextBudgeter** allocates token budget
-5. **TaskAnalyzer** decides planner vs direct agent path
-6. **resolveProviderForMode** picks plan or act model if configured
-7. **AgentLoop** streams LLM → tool calls → policy → approval → execute → repeat
-8. Results persisted: turns, plans, checkpoints, memory, JSONL logs
+## What V8 deliberately does NOT do
+
+- Treat the model as an authority for permissions or completion
+- Create one module per class, algorithm, or provider
+- Put business logic in host wiring (VS Code, CLI, webview)
+- Assume one language, package manager, or IDE
+- Run all tests or load all context for every request
+- Introduce multi-agent orchestration before one agent is reliable
 
 ## Data storage (`.mitii/`)
 
@@ -88,19 +140,58 @@ flowchart TB
 
 Legacy `.thunder/` paths are ignored for backward compatibility. **Nothing is sent to a Mitii server** — there isn't one.
 
-## Source layout
+## Package layout
+
+| Package | Role |
+|---------|------|
+| `packages/v8/` (`@mitii/v8`) | Core agent runtime — all 17 modules above |
+| `packages/sdk/` (`@mitii/sdk`) | Host-neutral programmatic API — `createMitiiClient()`, `client.start()`, `client.resume()`, `run.events`, `run.result` |
+| `packages/host/` (`@mitii/host`) | Host adapters — filesystem checkpoints, skills catalog, search, indexing, bundled embeddings |
+| `apps/vscode/` | VS Code extension — sidebar webview, inline diff, diff preview, commands, settings UI |
+| `apps/cli/` | Terminal agent — interactive and non-interactive modes |
+| `apps/daemon/` | Background daemon — long-running indexing, session management, MCP server hosting |
+
+Dependency direction: **`apps → sdk → v8`**. V8 never imports host or SDK packages.
+
+## Source layout (V8 core)
+
+All modules live under `packages/v8/src/modules/`:
+
+```text
+packages/v8/src/
+├── modules/
+│   ├── request-intake/
+│   ├── request-understanding/
+│   ├── repository-state/
+│   ├── repository-context/
+│   ├── decision-policy/
+│   ├── prompt-construction/
+│   ├── model-gateway/
+│   ├── tool-runtime/
+│   ├── verification/
+│   ├── agent-engine/
+│   ├── skills/
+│   ├── memory/
+│   ├── planning/
+│   ├── task-list/
+│   ├── code-navigation/
+│   ├── change-impact/
+│   └── window-budget/
+├── engine/
+│   ├── agent-engine/      (runtime orchestration)
+│   └── tool-runtime/      (tool execution)
+└── contracts/             (shared types across modules)
+```
 
-| Directory | Role |
-|-----------|------|
-| `src/extension.ts` | VS Code activation entry |
-| `src/core/` | Agent loop, indexing, retrieval, tools, safety, MCP, memory |
-| `src/core/llm/` | Provider implementations (OpenAI, Anthropic, Gemini, etc.) |
-| `src/core/agent/` | AgentLoop, PlanExecutor, ResearchAgent, compaction |
-| `src/core/indexing/` | SQLite, FTS5, tree-sitter, vectors |
-| `src/core/context/` | HybridRetriever, budgeter, repo map, sources |
-| `src/vscode/` | Commands, webview provider, inline diff, diff preview |
-| `src/webview-ui/` | React sidebar (Vite build → `dist/webview/`) |
-| `src/shared/` | Brand constants |
+Each module follows a consistent internal shape:
+
+```text
+modules/<name>/
+├── contracts/       (input, output, error, port schemas)
+├── pipeline/        (public orchestration)
+├── actions/         (meaningful pipeline steps)
+└── internal/        (private implementation)
+```
 
 ## Webview UI
 
@@ -111,14 +202,14 @@ React app with:
 - Context debugger, memory browser, checkpoint browser
 - Token meter, indexing status, context warnings
 
-Communicates via typed `postMessage` protocol (`messages.ts`).
+Communicates via typed `postMessage` protocol.
 
 ## LLM providers
 
-`LlmProviderRegistry` resolves from `thunder.provider.type`:
+Configured via `mitii.provider.type`:
 
-- Native: **Anthropic** (Messages API), **Gemini** (GenerateContent API)
-- OpenAI-compatible: OpenAI, DeepSeek, Cursor, Codex, Ollama, vLLM
+- **Native**: Anthropic (Messages API), Gemini (GenerateContent API)
+- **OpenAI-compatible**: OpenAI, DeepSeek, Cursor, Codex, Ollama, vLLM
 - **Echo** stub for testing
 
 Optional plan/act model overrides per mode.
@@ -135,9 +226,9 @@ McpManager
 
 ## Safety layer
 
-Every tool call: `ToolExecutor` → `ToolPolicyEngine` → `ApprovalQueue` (if needed) → execute.
+Every tool call goes through **Tool Runtime**: validate against `ToolGrant` → execute via host ports → return bounded `ToolResult`.
 
-Autonomy presets and approval modes compose to control writes, shell, and network.
+Autonomy presets and approval modes compose to control writes, shell, and network. Only **Verification** can declare success — the model proposes, Verification disposes.
 
 ## Build pipeline
 
diff --git a/docs/cli/index.md b/docs/cli/index.md
new file mode 100644
index 0000000..cfc88cf
--- /dev/null
+++ b/docs/cli/index.md
@@ -0,0 +1,137 @@
+# Mitii CLI
+
+Headless Mitii CLI over `@mitii/sdk` → `@mitii/v8` (with `@mitii/host` for indexing, checkpoints, memory, and skills).
+
+## Install
+
+```bash
+npm install -g @mitii/cli
+# or run without installing:
+npx @mitii/cli --help
+```
+
+Requires **Node.js 20+**. Native dependency: `better-sqlite3` (optional LanceDB for vectors). License: **AGPL-3.0-or-later**.
+
+> **Note:** Legacy npm `@mitii/cli@2.7.x` is a different binary stack — prefer versions published from the current monorepo.
+
+For local development from the monorepo:
+
+```bash
+pnpm --filter @mitii/cli build
+node apps/cli/bin/mitii.js --help
+```
+
+## First run
+
+```bash
+mitii --help                 # or: mitii -h
+mitii setup                  # pick provider + write .mitii/config.json
+export ANTHROPIC_API_KEY=…   # or GEMINI_ / OPENAI_ / MITII_API_KEY
+mitii session                # dotted MITII banner + interactive loop
+```
+
+Smoke test without a live model:
+
+```bash
+mitii ask "What is recursion?" --echo
+```
+
+Check what is configured (never prints secrets):
+
+```bash
+mitii setup --show
+mitii -v                     # or: mitii --version / mitii version
+```
+
+## Quick start
+
+```bash
+mitii ask "What is recursion?" --echo
+mitii index
+mitii status --json
+mitii session
+mitii export-session "Summarize this repo" --out session.json --echo
+```
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `setup` | Interactive (or flag-driven) model/provider setup |
+| `ask <prompt>` | SDK ask with streaming, cancel, clarify/approve |
+| `session` | Interactive prompt loop with MITII banner |
+| `index` | Full workspace index + publish repository state |
+| `status` | Show latest persisted repository state |
+| `export-session` | Run ask and write secret-free JSON export |
+| `version` / `help` | Version and usage (`-v` / `--version`, `-h` / `--help`) |
+
+### Modes
+
+| Mode | Behavior |
+|---|---|
+| `ask` | Q&A / explain (default) |
+| `plan` | Read-only plan; no file edits |
+| `agent` | Edit + verify with approvals |
+
+Set with `--mode <mode>` or `defaultMode` in config.
+
+## Setup options
+
+| Option | What it does |
+|---|---|
+| `--show` | Print current config (no secrets) |
+| `--provider <id>` | `ollama`, `anthropic`, `gemini`, `openai`, `deepseek`, … |
+| `--model <id>` | Model id |
+| `--base-url <url>` | OpenAI-compatible base URL |
+| `--global` | Write `~/.mitii/config.json` instead of project `.mitii/` |
+| `--test` | Probe the provider after writing |
+| `--yes` / `-y` | Non-interactive (requires `--provider`) |
+
+```bash
+# Local Ollama
+mitii setup --provider ollama --yes
+
+# Claude, then set the key in the shell
+mitii setup --provider anthropic --model claude-sonnet-4-5 --yes
+export ANTHROPIC_API_KEY=…
+
+# Custom OpenAI-compatible gateway
+mitii setup --provider openai-compatible --base-url http://localhost:1234/v1 --model local-model --yes --test
+```
+
+## Connect a provider
+
+Keys go in the environment. Provider and model go in `.mitii/config.json` or `~/.mitii/config.json` (prefer `mitii setup`).
+
+| Provider | Env var | Config example |
+|---|---|---|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | `{ "provider": "anthropic", "model": "claude-sonnet-4-5" }` |
+| Gemini | `GEMINI_API_KEY` | `{ "provider": "gemini", "model": "gemini-2.5-flash" }` |
+| OpenAI | `OPENAI_API_KEY` | `{ "provider": "openai", "model": "gpt-4o" }` |
+| DeepSeek | `MITII_API_KEY` | `{ "provider": "openai-compatible", "providerPreset": "deepseek", "model": "deepseek-chat", "baseUrl": "https://api.deepseek.com/v1" }` |
+| Ollama / LM Studio | *(none)* | `{ "provider": "openai-compatible", "baseUrl": "http://localhost:11434/v1", "model": "qwen3-coder:30b" }` |
+
+Overrides: `MITII_PROVIDER`, `MITII_MODEL`, `MITII_BASE_URL`, `MITII_API_KEY`.
+
+> Local Ollama / LM Studio do not need a key. Anthropic and Gemini do.
+> Cursor Cloud Agents are a separate agent API, not an LLM endpoint. Point `openai-compatible` at any `/v1/chat/completions` proxy if you need a custom gateway.
+
+## Session UI
+
+`mitii session` prints a dotted **MITII** banner, then workspace / provider / mode, and the `mitii>` prompt. If you are still on the echo provider, the banner reminds you to run `mitii setup`.
+
+## Development (monorepo)
+
+```bash
+pnpm --filter @mitii/cli typecheck
+pnpm --filter @mitii/cli test
+pnpm --filter @mitii/cli build
+node apps/cli/bin/mitii.js ask "ping" --echo --json
+node apps/cli/bin/mitii.js setup --show
+```
+
+## Links
+
+- Repo: [Mitii-dev/Mitii](https://github.com/Mitii-dev/Mitii)
+- SDK: [`@mitii/sdk`](https://github.com/Mitii-dev/Mitii/tree/main/packages/sdk)
+- Host kit: [`@mitii/host`](https://github.com/Mitii-dev/Mitii/tree/main/packages/host)
diff --git a/docs/configuration.md b/docs/configuration.md
index 15d5767..c8f3266 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,127 +1,181 @@
 # Configuration
 
-Mitii settings use the `thunder.*` namespace in VS Code (historical internal name). Configure via the sidebar **Settings** tab or VS Code Settings → **Mitii AI Agent**.
+All Mitii settings live in the **sidebar Settings tab** (or VS Code Settings → *Mitii AI Agent*). They use the `mitii.*` namespace, so you can also edit them directly in `settings.json`.
 
 ## Quick start
 
+A minimal working config for a local Ollama model:
+
 ```json
 {
-  "thunder.provider.type": "openai-compatible",
-  "thunder.provider.baseUrl": "http://localhost:11434/v1",
-  "thunder.provider.model": "qwen3-coder:30b",
-  "thunder.provider.contextWindow": 32768,
-  "thunder.safety.autonomyPreset": "guided",
-  "thunder.agent.checkpointStrategy": "git-stash",
-  "thunder.indexing.autoIndexOnOpen": true,
-  "thunder.indexing.vectorsEnabled": true,
-  "thunder.agent.verifyCommands": ["npm run lint", "npm test"],
-  "thunder.telemetry.sessionLogging": true
+  "mitii.provider.type": "openai-compatible",
+  "mitii.provider.baseUrl": "http://localhost:11434/v1",
+  "mitii.provider.model": "qwen3-coder:30b",
+  "mitii.provider.contextWindow": 32768,
+  "mitii.safety.autonomyPreset": "guided",
+  "mitii.agent.checkpointStrategy": "git-stash",
+  "mitii.indexing.autoIndexOnOpen": true,
+  "mitii.indexing.vectorsEnabled": true,
+  "mitii.agent.verifyCommands": ["npm run lint", "npm test"],
+  "mitii.telemetry.sessionLogging": true
 }
 ```
 
-## Provider
+That's all you need to start. Everything else has sensible defaults.
 
-| Setting | Values | Description |
-|---------|--------|-------------|
-| `thunder.provider.type` | `openai-compatible`, `openai`, `anthropic`, `gemini`, `deepseek`, `cursor`, `codex`, `echo` | LLM provider |
-| `thunder.provider.baseUrl` | URL | API base (provider-specific default) |
-| `thunder.provider.model` | string | Model name |
-| `thunder.provider.contextWindow` | number | Token cap for prompt trimming |
-| API key | — | VS Code SecretStorage (settings UI) |
+---
 
-[Provider guide →](/implementation/providers)
+## Provider
 
-## Plan / Act models
+Which model powers Mitii.
 
-| Setting | Description |
+| Setting | What it does |
 |---------|-------------|
-| `thunder.agent.planModel` | Optional plan-mode model override |
-| `thunder.agent.planBaseUrl` | Optional plan-mode URL override |
-| `thunder.agent.actModel` | Optional agent-mode model override |
-| `thunder.agent.actBaseUrl` | Optional agent-mode URL override |
-| `thunder.agent.orchestrationEnabled` | Multi-step planner in Plan mode (default `true`) |
+| `mitii.provider.type` | Provider family: `openai-compatible`, `openai`, `anthropic`, `gemini`, `deepseek`, `cursor`, `codex`, `echo` |
+| `mitii.provider.baseUrl` | API endpoint (defaults per provider) |
+| `mitii.provider.model` | Model name to send requests to |
+| `mitii.provider.contextWindow` | Token budget — Mitii trims prompts to fit this cap |
+| API key | Stored in VS Code SecretStorage; set via the Settings UI, not `settings.json` |
+
+### Plan / Act model overrides
+
+You can use a different (often cheaper) model for planning vs. acting:
+
+| Setting | Purpose |
+|---------|---------|
+| `mitii.agent.planModel` / `planBaseUrl` | Model used during Plan mode |
+| `mitii.agent.actModel` / `actBaseUrl` | Model used during Act mode |
+| `mitii.agent.orchestrationEnabled` | Enables the multi-step planner (default `true`) |
+
+[Full provider guide →](/implementation/providers)
+
+---
 
 ## Safety
 
-| Setting | Values | Description |
+Controls how much freedom Mitii has before asking you.
+
+| Setting | Values | What it does |
 |---------|--------|-------------|
-| `thunder.safety.autonomyPreset` | `safe`, `guided`, `builder`, `pilot`, `enterprise` | Quick safety profile |
-| `thunder.safety.approvalMode` | `review_all`, `ask_edits`, `ask_deletes`, `ask_commands`, `auto` | Fine-grained approval |
-| `thunder.safety.allowNetwork` | boolean | `fetch_web` access (presets override) |
-| `thunder.safety.allowUntrustedWorkspace` | boolean | Allow writes in untrusted workspaces |
+| `mitii.safety.autonomyPreset` | `safe`, `guided`, `builder`, `pilot`, `enterprise` | One-click safety profile (most common way to configure) |
+| `mitii.safety.approvalMode` | `review_all`, `ask_edits`, `ask_deletes`, `ask_commands`, `auto` | Fine-grained: which actions still need your OK |
+| `mitii.safety.allowNetwork` | `true` / `false` | Whether `fetch_web` is available |
+| `mitii.safety.allowUntrustedWorkspace` | `true` / `false` | Allow writes when the workspace isn't trusted |
+
+The preset sets a baseline; individual settings override it. For example, `guided` asks before edits, but you can flip `approvalMode` to `auto` to skip that.
+
+[Full safety guide →](/implementation/safety)
 
-[Safety guide →](/implementation/safety)
+---
 
-## Agent
+## Agent behaviour
 
-| Setting | Default | Description |
+How Mitii runs, how long it runs, and what it does after.
+
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.agent.maxSteps` | `15` | Max tool rounds per turn |
-| `thunder.agent.autoContinue` | `true` | Continue after step limit |
-| `thunder.agent.maxAutoContinues` | `2` | Max continuation rounds |
-| `thunder.agent.subagentsEnabled` | `true` | Research subagents |
-| `thunder.agent.researchAgentMaxSteps` | `6` | Subagent step limit |
-| `thunder.agent.researchAgentModel` | `""` | Optional subagent model |
-| `thunder.agent.showDiffPreview` | `false` | VS Code diff tabs before writes |
-| `thunder.agent.checkpointStrategy` | `git-stash` | `file-copy`, `git-stash`, `shadow-git` |
-| `thunder.agent.verifyOnActComplete` | `true` | Run verify commands after Act |
-| `thunder.agent.verifyCommands` | `["npm run lint", "npm test"]` | Post-act shell commands |
+| `mitii.agent.maxSteps` | `15` | Max tool-call rounds per turn |
+| `mitii.agent.autoContinue` | `true` | Keep going after hitting the step limit |
+| `mitii.agent.maxAutoContinues` | `2` | How many times it can auto-continue |
+| `mitii.agent.subagentsEnabled` | `true` | Spawn research subagents for parallel exploration |
+| `mitii.agent.researchAgentMaxSteps` | `6` | Step cap for each subagent |
+| `mitii.agent.researchAgentModel` | `""` | Optional cheaper model for subagents |
+| `mitii.agent.showDiffPreview` | `false` | Open VS Code diff tabs before applying writes |
+| `mitii.agent.checkpointStrategy` | `git-stash` | How to snapshot before edits: `file-copy`, `git-stash`, `shadow-git` |
+| `mitii.agent.verifyOnActComplete` | `true` | Run verification commands after Act finishes |
+| `mitii.agent.verifyCommands` | `["npm run lint", "npm test"]` | The commands to run for verification |
+
+---
 
 ## Indexing
 
-| Setting | Default | Description |
+How Mitii builds its understanding of your codebase.
+
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.indexing.enabled` | `true` | Workspace indexing |
-| `thunder.indexing.autoIndexOnOpen` | `true` | Index on folder open |
-| `thunder.indexing.vectorsEnabled` | `true` | Semantic vectors |
-| `thunder.indexing.embeddingProvider` | `minilm` | `minilm` or `hash` |
-| `thunder.indexing.vectorBackend` | `sqlite` | `sqlite` or `lancedb` |
-| `thunder.indexing.treeSitterEnabled` | `true` | WASM symbol extraction |
-| `thunder.indexing.maxConcurrency` | `2` | Parallel index workers |
+| `mitii.indexing.enabled` | `true` | Master switch for workspace indexing |
+| `mitii.indexing.autoIndexOnOpen` | `true` | Index automatically when you open a folder |
+| `mitii.indexing.vectorsEnabled` | `true` | Build semantic vectors for similarity search |
+| `mitii.indexing.embeddingProvider` | `minilm` | Embedding model: `minilm` (quality) or `hash` (fast, no network) |
+| `mitii.indexing.vectorBackend` | `sqlite` | Storage: `sqlite` (default) or `lancedb` (larger corpora) |
+| `mitii.indexing.treeSitterEnabled` | `true` | Use Tree-sitter WASM for symbol extraction |
+| `mitii.indexing.maxConcurrency` | `2` | Parallel index workers |
+
+[Full indexing guide →](/implementation/context-indexing)
 
-## Context
+---
 
-| Setting | Default | Description |
+## Context retrieval
+
+How Mitii picks the most relevant code for each prompt.
+
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.context.rerankerEnabled` | `true` | Rerank retrieval candidates |
-| `thunder.context.rerankerCandidatePool` | `20` | Candidates before rerank |
-| `thunder.context.rerankerTopK` | `8` | Items after rerank |
+| `mitii.context.rerankerEnabled` | `true` | Rerank retrieval candidates before injecting them |
+| `mitii.context.rerankerCandidatePool` | `20` | How many candidates to pull before reranking |
+| `mitii.context.rerankerTopK` | `8` | How many survive into the prompt |
+
+---
 
 ## Memory
 
-| Setting | Default | Description |
+Durable facts Mitii remembers across sessions (preferences, decisions, project context).
+
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.memory.enabled` | `true` | Memory system |
-| `thunder.memory.hybridSearchEnabled` | `true` | FTS + vector hybrid |
-| `thunder.memory.maxItems` | `500` | Max observations |
+| `mitii.memory.enabled` | `true` | Master switch |
+| `mitii.memory.hybridSearchEnabled` | `true` | Combine full-text + vector search |
+| `mitii.memory.maxItems` | `500` | Cap on stored observations |
 
-## MCP
+[Full memory guide →](/implementation/memory-checkpoints)
 
-| Setting | Default | Description |
+---
+
+## MCP (Model Context Protocol)
+
+Connect external tool servers (filesystem, databases, custom APIs).
+
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.mcp.enabled` | `true` | MCP master switch |
-| `thunder.mcp.preloadBuiltin` | `true` | Built-in servers on startup |
-| `thunder.mcp.maxConcurrentStartup` | `4` | Parallel server connections |
-| `thunder.mcp.servers` | `{}` | Custom server definitions |
-| `thunder.mcp.builtinServers` | object | Per-builtin toggles |
+| `mitii.mcp.enabled` | `true` | Master switch |
+| `mitii.mcp.preloadBuiltin` | `true` | Start built-in servers on launch |
+| `mitii.mcp.maxConcurrentStartup` | `4` | Parallel server connections at startup |
+| `mitii.mcp.servers` | `{}` | Custom server definitions (name → command/args) |
+| `mitii.mcp.builtinServers` | object | Per-builtin on/off toggles |
+
+[Full MCP guide →](/implementation/mcp)
 
-[MCP guide →](/implementation/mcp)
+---
 
 ## Telemetry
 
-| Setting | Default | Description |
+Local-only logging. Nothing leaves your machine.
+
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.telemetry.sessionLogging` | `true` | JSONL logs in `.mitii/logs/` |
-| `thunder.telemetry.debugMetrics` | `false` | Extra diagnostics in logs |
+| `mitii.telemetry.sessionLogging` | `true` | Write JSONL session logs to `.mitii/logs/` |
+| `mitii.telemetry.debugMetrics` | `false` | Add extra diagnostic fields to logs |
+
+---
 
 ## Project rules
 
-Auto-loaded methodology files:
+Mitii auto-loads methodology and style files from your repo so it follows your conventions without you repeating them:
 
 - `AGENTS.md`, `CLAUDE.md`, `WARP.md`, `.cursorrules`
-- `.mitii/rules`, `.mitii/agents`, `.mitii/checks`, `.mitii/prompts`
-- `.clinerules`, `.continue/rules`, `.cursor/rules`
+- `.mitii/rules/`, `.mitii/agents/`, `.mitii/checks/`, `.mitii/prompts/`
+- `.clinerules`, `.continue/rules/`, `.cursor/rules/`
+
+Drop a file in any of those locations and Mitii picks it up on the next run.
+
+---
+
+## Developer
+
+Hidden by default. Toggle on in the Settings sidebar for advanced switches (log level, experimental flags, etc.). Leave off unless you're debugging.
+
+---
 
-## Full schema
+## Where to find the full schema
 
-Every key is defined in the extension `package.json` → `contributes.configuration`. Browse the [thunder-ai-agent repo](https://github.com/codewithshinde/thunder-ai-agent) for the authoritative list.
+Every key is declared in the extension's `package.json` → `contributes.configuration`. The sidebar Settings UI is generated from that schema, so what you see in the UI is the complete list.
diff --git a/docs/development.md b/docs/development.md
index 8eb5ae0..6d2f4a4 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -1,62 +1,119 @@
 # Development
 
-Contributions welcome — see [CONTRIBUTING.md](https://github.com/codewithshinde/thunder-ai-agent/blob/main/CONTRIBUTING.md) on GitHub.
+Contributions welcome — see [CONTRIBUTING.md](https://github.com/Mitii-dev/Mitii/blob/main/CONTRIBUTING.md) on GitHub.
+
+## Prerequisites
+
+| Tool | Version |
+|------|---------|
+| VS Code | 1.124+ (Cursor works with the native rebuild below) |
+| Node.js | 20+ |
+| pnpm | 10.13+ |
+| git | any recent version |
+
+Optional for full feature coverage:
+
+- A local Ollama or other OpenAI-compatible endpoint for manual testing
+- `@xenova/transformers` (optional dependency) for vector search
+- `web-tree-sitter` + `tree-sitter-wasms` for symbol extraction
 
 ## Setup
 
 ```bash
-git clone https://github.com/codewithshinde/thunder-ai-agent.git
-cd thunder-ai-agent
-npm install
-npm run compile
+git clone https://github.com/Mitii-dev/Mitii.git
+cd Mitii
+pnpm install
+pnpm run build:all   # packages + Electron better-sqlite3 staged into apps/vscode/dist/native
+```
+
+Or use the one-shot setup scripts:
+
+```bash
+pnpm run setup          # install + Node rebuild + build + Electron rebuild
+pnpm run setup:cursor   # same, but targets Cursor's Electron ABI
+```
+
+Git hooks are installed automatically via `pnpm install` → `prepare` → `scripts/install-git-hooks.mjs`. The pre-commit hook stages version bumps from `scripts/bump-version.mjs`.
+
+### Launch the extension
+
+1. Open the repo root in VS Code / Cursor
+2. Press **F5** (loads `apps/vscode` via `.vscode/launch.json`)
+3. In the Extension Development Host, open a project folder
+4. Click the Mitii icon in the activity bar
+
+Automated F5 gate (no Extension Host): `pnpm run f5:verify`
+
+### Watch mode (day-to-day dev)
+
+```bash
+pnpm --filter @mitii/vscode build
 ```
 
-Press **F5** to launch the Extension Development Host.
+Rebuild the extension package after host changes. Reload the Extension Development Host after rebuilds.
 
 ## Scripts
 
 | Command | Purpose |
 |---------|------|
-| `npm run watch` | Extension + webview hot rebuild |
-| `npm run test` | Vitest unit tests |
-| `npm run lint` | TypeScript typecheck |
-| `npm run package` | Build `.vsix` |
-| `npm run rebuild:native` | Rebuild `better-sqlite3` for VS Code Electron |
+| `pnpm test` | Architecture + selected Vitest suites (auto-heals SQLite ABI) |
+| `pnpm run test:v8` | `@mitii/v8` package tests |
+| `pnpm run test:watch` | Vitest watch mode |
+| `pnpm run typecheck` | TypeScript typecheck across v8 + sdk + cli + vscode |
+| `pnpm run build` | Build all packages |
+| `pnpm run build:all` | Full F5-ready build (packages + Electron native) |
+| `pnpm run package` | Build `.vsix` → `mitii-ai-agent-<version>.vsix` |
+| `pnpm run benchmark` | Run the solid benchmark suite |
+| `pnpm run benchmark:validate` | Validate benchmark fixtures |
+| `pnpm run audit:dependencies` | Dependency audit |
+| `pnpm run audit:dead-code` | Dead-code audit |
+| `pnpm run check:circular-deps` | Circular dependency check |
 
 ## Project layout
 
 ```
-src/
-├── core/           # Agent, indexing, tools, safety, MCP
-├── vscode/         # Extension entry, webview provider
-├── webview-ui/     # React sidebar
-└── shared/         # Brand constants
-test/               # Vitest tests
+Mitii/
+├── packages/v8/                  # @mitii/v8 — host-neutral runtime (17 modules)
+├── packages/sdk/                 # @mitii/sdk — public API over V8
+├── packages/host/                # @mitii/host — shared host kit (indexing, SQLite, ports)
+├── apps/vscode/                  # VS Code extension (webview, settings, MCP)
+├── apps/cli/                     # Headless CLI (@mitii/cli)
+├── tests/                        # Architecture, consumer, solid benchmark
+├── docs/
+├── scripts/
+├── pnpm-workspace.yaml
+└── package.json                  # Private workspace orchestrator
 ```
 
-## Related repositories
-
-| Repo | URL |
-|------|-----|
-| Docs | [github.com/codewithshinde/mitii-docs](https://github.com/codewithshinde/mitii-docs) → docs.mitii.dev |
-| Website | [github.com/codewithshinde/mitii-website](https://github.com/codewithshinde/mitii-website) → mitii.dev |
+**Dependency direction:** `apps → @mitii/host → @mitii/sdk → @mitii/v8`. Hosts use `@mitii/sdk` only — do not import V8 `actions/` or `internal/` directly.
 
 ## Native module note
 
-VS Code and Cursor ship their own Electron runtime:
+VS Code and Cursor ship their own Electron runtime. `better-sqlite3` must be rebuilt for the correct ABI:
 
-```bash
-npm run rebuild:native          # VS Code
-THUNDER_EDITOR=cursor npm run rebuild:native   # Cursor
-npm run rebuild:node            # for local vitest
-```
+| Scenario | Command |
+|----------|---------|
+| Full F5-ready build | `pnpm run build:all` |
+| VS Code extension host | `pnpm run rebuild:native` |
+| Cursor extension host | `MITII_EDITOR=cursor pnpm run rebuild:native` |
+| Local vitest / CLI only | `pnpm run rebuild:node` |
+| Both (Electron staged + Node restored) | `pnpm run rebuild:all` |
+
+`rebuild:native` stages `better_sqlite3.node` into `apps/vscode/dist/native`, then restores the system Node ABI in `node_modules`. If SQLite throws on startup, this is almost always the fix.
 
 ## Branding
 
-Display name constants live in `src/shared/brand.ts`. Keep in sync with `mitii-docs/brand.ts` and `mitii-website/brand.ts`.
+Display name constants live in `apps/vscode/src/shared/brand.ts`. Keep in sync with `mitii-docs/brand.ts` and `mitii-website/brand.ts`.
+
+## Related repositories
+
+| Repo | URL |
+|------|-----|
+| Docs | [github.com/codewithshinde/mitii-docs](https://github.com/codewithshinde/mitii-docs) → docs.mitii.dev |
+| Website | [github.com/codewithshinde/mitii-website](https://github.com/codewithshinde/mitii-website) → mitii.dev |
 
 ## Community
 
-- [GitHub](https://github.com/codewithshinde/thunder-ai-agent)
+- [GitHub](https://github.com/Mitii-dev/Mitii)
 - [Discord](https://discord.gg/sa8rubf6HH)
-- [Issues](https://github.com/codewithshinde/thunder-ai-agent/issues)
+- [Issues](https://github.com/Mitii-dev/Mitii/issues)
diff --git a/docs/features/index.md b/docs/features/index.md
index da4f7a6..dd7c701 100644
--- a/docs/features/index.md
+++ b/docs/features/index.md
@@ -1,124 +1,179 @@
 # Features
 
-Mitii combines **deep workspace indexing** with a **safe Plan/Act agent workflow** — local-first, approval-gated, and auditable.
+Mitii is a **local-first, approval-gated, auditable** coding-agent runtime. It indexes your entire workspace, plans before it acts, and keeps every operation under your control — without sending code to a vendor server.
 
-::: tip New in v2.6
-Context debugger, memory browser, checkpoint panel, 8 LLM providers, plan/act model split, MCP HTTP/SSE, git-stash checkpoints, inline diff accept/reject, **Cursor-style Planner UI**, and **planning skills auto-load**. See [Recent improvements](/implementation/recent-improvements).
-:::
+---
 
-## Why Mitii?
+## Deep Workspace Indexing
 
-[What makes Mitii different →](/why-mitii)
+Mitii builds a multi-layer index of your repository before any agent interaction:
 
-## Context and indexing
+| Layer | What it provides |
+|-------|-----------------|
+| **FTS5** | Fast full-text keyword search across all indexed files |
+| **Tree-sitter** | Symbol extraction (functions, classes, imports) across 100+ languages |
+| **Repo map** | PageRank over import/export edges — surfaces structurally important files |
+| **Vectors** | On-device MiniLM embeddings (384-d, L2-normalized) for semantic similarity search |
+| **Git + LSP** | Uncommitted diffs and live diagnostics injected into context |
+| **Project rules** | Auto-loads `AGENTS.md`, `.cursor/rules`, `.clinerules`, `.mitii/rules` |
 
-- **Workspace scanner** respects `.gitignore` and `.mitiiignore`; auto-indexes on folder open
-- **FTS5 full-text search** with ripgrep fallback for unindexed paths
-- **Tree-sitter WASM** symbol extraction (100+ languages) with regex fallback
-- **PageRank repo map** — surfaces structurally important files
-- **Vector search** — local MiniLM via `@xenova/transformers`; SQLite or LanceDB backend
-- **Hybrid retriever + reranker** — merges search, vectors, rules, mentions, git, LSP, memory
-- **Context debugger** — live budget meters, source breakdown, dropped-item visibility
-- **Pinned `@` context** — explicit file/folder mentions always considered
+A **hybrid retriever** merges all sources, a **reranker** trims noise, and a **context budget** fits the result into your model window. The **context debugger** in the sidebar shows exactly what was included, truncated, or dropped.
 
-[Deep dive: Context & indexing →](/implementation/context-indexing)
+All indexing and embedding runs **on your machine** — no API calls, no network round-trips.
 
-## Agent workflow
+---
 
-- **Ask / Plan / Agent / Review modes** — separate analysis from execution
-- **Plan vs Act models** — optional cheaper planner, stronger implementer
-- **Tool loop** — 20+ built-in tools + dynamic MCP tools
-- **Research subagents** — `spawn_research_agent` for parallel read-only exploration
-- **Task decomposition** — multi-step plans with lifecycle tracking and persistence
-- **Cursor-style Planner panel** — phased steps, requirement analysis, skill chips, expandable step details in Plan mode
-- **Planning skills** — auto-loads `planning-and-task-breakdown` and related playbooks during orchestrated planning
-- **Post-edit verification** — configurable lint/test after Act-mode runs
-- **Skills catalog** — `.mitii/skills/SKILL.md` invoked via `use_skill` and auto-injected during planning
-- **Auto-continue** — agent keeps working across step-limit boundaries
-- **Conversation compaction** — long sessions trimmed intelligently
+## Agent Workflow (Plan / Act)
 
-[Deep dive: Plan / Act →](/implementation/plan-act)
+Mitii separates **thinking** from **doing** with explicit modes:
 
-## Safety and control
+| Mode | Writes | Shell | Purpose |
+|------|--------|-------|---------|
+| **Ask** | Blocked | Read-only | Q&A, exploration, explanation |
+| **Plan** | Blocked | Read-only | Structured plans, audits, impact analysis |
+| **Agent** | With approval | With approval | Implementation with per-step gates |
+| **Review** | Blocked | Read-only | Code review and quality checks |
 
-- **Five autonomy presets** — safe, guided, builder, pilot, enterprise (distinct behavior)
-- **Five approval modes** — review_all, ask_edits, ask_deletes, ask_commands, auto
-- **Dangerous command blocking** — rm -rf, sudo, force-push, etc.
-- **Untrusted workspace blocking** — writes/shell disabled unless opted in
-- **Git-stash checkpoints** — restore from Checkpoints panel
-- **Inline diff** — accept/reject in editor; optional VS Code diff tabs
-- **Approval cards** — approve once, approve for task, or deny
+### Agent tools
 
-[Deep dive: Safety →](/implementation/safety)
+| Tool | Purpose |
+|------|---------|
+| `ask_question` | Clarify ambiguous requests before acting |
+| `propose_plan_mutation` | Propose changes to the current plan mid-run |
+| `propose_file_scope` | Declare candidate file paths before reading or editing (default Act contract) |
+| `mark_step_complete` | Signal step completion for progress tracking |
 
-## Memory and persistence
+---
 
-- **Long-term memory** — `memory_search` / `memory_write` with FTS5 + vector hybrid
-- **Memory panel** — browse and clear observations in sidebar
-- **Post-task extraction** — async summarization after completed work
-- **Session history** — resume from History tab
-- **Plan persistence** — SQLite + `.mitii/tasks/`
-- **JSONL audit logs** — every tool, approval, token event in `.mitii/logs/`
+## Safety & Control
 
-[Deep dive: Memory & checkpoints →](/implementation/memory-checkpoints)
+Two cooperating layers gate every risky operation:
 
-## LLM providers
+| Layer | Role |
+|-------|------|
+| **Decision Policy** | Decides *what* is allowed: execution route, planning depth, tool grant, verification requirements, prompt-injection scan |
+| **Tool Runtime** | Enforces the grant: validates tool name, effect, path scope, command rules, network hosts, output limits, mutation batch limits |
 
-Eight provider types: OpenAI-compatible, OpenAI, Anthropic, Gemini, DeepSeek, Cursor, Codex, Echo.
+### ToolGrant dimensions
 
-- Native Anthropic Messages API and Gemini GenerateContent API
-- Local Ollama/vLLM via OpenAI-compatible endpoint
-- API keys in VS Code SecretStorage
-- Connection test in settings UI
+| Dimension | Controls |
+|-----------|----------|
+| `maximumWorkspaceEffect` | Read-only → write → execute |
+| `allowedTools` | Which tools the model may request |
+| `pathScopes` | Filesystem paths the agent may touch |
+| `commandRules` | Shell command allow/deny patterns |
+| `networkHosts` | Per-endpoint network access |
+| `limits` | Output size, batch size, timeout |
+| `mutationBudget` | Max file mutations per run |
+| `approvalMode` | `when_required` or `always` |
 
-[Deep dive: Providers →](/implementation/providers)
+### Additional safety features
 
-## MCP and integrations
+- **Prompt-injection defense** — Decision Policy scans for injection signals and clamps the ToolGrant before Tool Runtime sees the call
+- **Verification requirements** — agent must produce evidence (test output, typecheck, lint) before claiming success
+- **Mutation rollback** — Tool Runtime can revert a batch of file changes on failure
+- **Audit trail** — every tool call, approval, and rejection is logged (SQLite + JSONL)
+- **MCP Act-mode exclusions** — MCP tools are excluded from Agent mode by default
 
-- **Built-in servers** — filesystem, memory, sequential-thinking (keyless via npx)
-- **Transports** — stdio, HTTP SSE, Streamable HTTP
-- **Remote auth** — bearer tokens in headers
-- **Workspace config** — `.mitii/mcp.json`, `.mcp.json`, VS Code settings
-- **Integrations UI** — toggle builtins, add custom servers, view status
+---
 
-[Deep dive: MCP →](/implementation/mcp)
+## Code Intelligence
 
-## Web fetch
+| Capability | Description |
+|------------|-------------|
+| **Code Navigation** | Resolve definitions, references, and hover info via injected `CodeNavigationPort` |
+| **Change Impact** | Walk the repository graph from a file/symbol/caret seed to estimate blast radius (affected files, packages, truncation signals) |
+| **Repo Graph** | Dependency and dependent edges across files, symbols, and packages |
 
-- **`fetch_web` tool** — HTTP fetch for external docs and API references
-- HTML stripped to plain text; network gated by safety preset
+---
 
-## UI
+## Memory & Context
 
-React sidebar webview:
+- **Hybrid retrieval** — FTS5 keyword + vector semantic search merged and reranked
+- **Access-based retention** — frequently accessed memories are retained longer
+- **Privacy redaction** — hash reinforcement + Jaccard supersede to prevent sensitive data leakage
+- **Checkpoints** — filesystem snapshots for safe rollback of agent changes
+- **Session logs** — JSONL audit trail of every tool call and approval
 
-- Chat with streaming, Shiki code blocks, markdown
-- History, Settings (7 tabs)
-- Plan panel, approval cards, agent activity
-- Context debugger, memory browser, checkpoint browser
-- Pinned context, token meter, indexing status
-- Context warning banner when budget is tight
+---
 
-## Project rules
+## Skills System
 
-Auto-loaded from repo:
+Mitii ships **12 bundled skills** that shape agent behavior:
 
-- `AGENTS.md`, `CLAUDE.md`, `WARP.md`, `.cursorrules`
-- `.mitii/rules`, `.clinerules`, `.cursor/rules`, `.continue/rules`
+| Skill | Focus |
+|-------|-------|
+| `safety-always` | Safety guardrails on every run |
+| `ask-concise` | Concise, direct answers |
+| `bugfix-localize` | Localize bugs before fixing |
+| `planning-default` | Structured planning before action |
+| `planning-and-task-breakdown` | Decompose specs into atomic tasks |
+| `code-review-and-quality` | Review and quality checks |
+| `debugging-and-error-recovery` | Systematic debugging |
+| `git-workflow-and-versioning` | Atomic commits, clear history |
+| `incremental-implementation` | Small, verifiable changes |
+| `security-and-hardening` | OWASP-class risk hardening |
+| `spec-driven-development` | Spec-first implementation |
+| `test-driven-development` | TDD workflow |
 
-## How Mitii compares
+Custom skills can be dropped into `.mitii/skills/` to override or extend bundled behavior.
 
-| Pain point | What Mitii does |
-|------------|------------------|
-| Agent doesn't know the codebase | Background index: FTS, symbols, vectors, repo map |
-| Wrong files in context | Hybrid retrieval + reranker + context debugger |
-| Edits without oversight | Approval queue + inline diff + checkpoints |
-| Plans that never get executed | Plan mode persists steps; Agent mode runs tool loop |
-| Context runs out mid-task | Compaction, auto-continue, task state across approvals |
-| No audit trail | JSONL session logs + approval audit table |
-| Locked into one vendor | 8 provider types + MCP + project rules from any editor |
-| Opaque safety | Named presets + approval modes + policy engine |
+---
 
-## Tool reference
+## Provider Support
 
-[Full built-in tool catalog →](/implementation/tools)
+Mitii is **LLM-agnostic** via the `LlmPort` injection pattern:
+
+| Provider | Notes |
+|----------|-------|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` |
+| Google (Gemini) | `GEMINI_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| DeepSeek | OpenAI-compatible endpoint |
+| Ollama / LM Studio | Local, no key required |
+| Any OpenAI-compatible | Custom base URL |
+
+- **Token budget** — context window drives derived budgets for input/output
+- **Profiles** — `.mitii/profiles.json` for per-project provider/model presets
+- **Secrets stay on the port** — the SDK and V8 never see API keys
+
+---
+
+## MCP (Model Context Protocol)
+
+- **Off by default** (`mitii.mcp.enabled`)
+- **Built-in catalog** — install MCP servers from Settings → Integrations
+- **Act-mode exclusions** — MCP tools are excluded from Agent mode for safety
+- Same approval policy as built-in tools when enabled
+
+---
+
+## Multi-Surface
+
+The same agent core powers three surfaces:
+
+| Surface | Package | Use case |
+|---------|---------|----------|
+| **VS Code Extension** | `apps/vscode` | IDE-integrated agent with sidebar UI, context debugger, approval queue |
+| **CLI** | `@mitii/cli` | Headless terminal agent for CI, scripts, and remote workflows |
+| **SDK** | `@mitii/sdk` | Host-neutral programmatic API for embedding Mitii in custom apps |
+
+All three share the same `@mitii/v8` engine, `@mitii/host` kit, and safety model.
+
+---
+
+## Architecture
+
+```text
+Validated Input → Cohesive Pipeline → Validated Result
+```
+
+| Package | Responsibility |
+|---------|---------------|
+| `@mitii/v8` | Agent engine, decision policy, tool runtime, code navigation, change impact |
+| `@mitii/sdk` | Public host-neutral API (createMitiiClient, run lifecycle, LlmPort injection) |
+| `@mitii/host` | Shared host kit: indexing, bundled embedding, checkpoints, memory, skills catalog |
+| `@mitii/cli` | Headless CLI over SDK |
+| `apps/vscode` | VS Code extension (F5 target, Marketplace: `mitii.mitii-ai-agent`) |
+
+**Forbidden edges:** `host → apps`, `sdk → host`, `v8 → host`.
diff --git a/docs/getting-started/connect-model.md b/docs/getting-started/connect-model.md
index 7533950..6a4974e 100644
--- a/docs/getting-started/connect-model.md
+++ b/docs/getting-started/connect-model.md
@@ -1,6 +1,59 @@
 # Connect a Model
 
-Mitii supports eight provider types. Pick the path that fits your workflow.
+### CLI setup
+
+```bash
+mitii setup                                    # interactive
+mitii setup --provider anthropic --yes         # non-interactive
+mitii setup --provider ollama --yes            # local Ollama
+mitii setup --show                             # verify (no secrets printed)
+mitii ask "ping" --echo                        # smoke test
+```
+
+Config → `.mitii/config.json` (project) or `~/.mitii/config.json` (`--global`). Keys stay in env vars.
+
+Mitii supports eight provider types. Configure once and the same settings work across the VS Code extension, the CLI, and any custom host built on `@mitii/sdk`.
+
+## Quick start (VS Code)
+
+1. Open **Settings → Provider** in the Mitii sidebar (or follow the onboarding prompt).
+2. Pick a **preset** (Ollama, Anthropic, Gemini, …) — it auto-fills base URL and model.
+3. Add your API key if the provider requires one (local hosts usually don't).
+4. Click **Test connection** → **Save**.
+
+The preset is stored in `mitii.provider.preset` and persists across sessions.
+
+## Quick start (CLI)
+
+```bash
+# Interactive setup — writes .mitii/config.json
+mitii setup
+
+# Or set an env var and go
+export ANTHROPIC_API_KEY=sk-ant-...
+mitii session
+
+# Smoke test without a live model
+mitii ask "What is recursion?" --echo
+```
+
+Supported environment variables: `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `MITII_API_KEY`.
+
+## Provider presets
+
+| Preset | Best for | API key | Default base URL |
+|--------|----------|---------|------------------|
+| Ollama | Local, free | None | `http://localhost:11434/v1` |
+| OpenAI-compatible | vLLM, LM Studio, Together, Groq | Optional | — |
+| OpenAI | GPT models | Required | `https://api.openai.com/v1` |
+| Anthropic | Claude | Required | `https://api.anthropic.com` |
+| Gemini | Google Gemini | Required | `https://generativelanguage.googleapis.com` |
+| DeepSeek | DeepSeek Chat | Required | `https://api.deepseek.com/v1` |
+| Cursor | Cursor API | Required | `https://api.cursor.com/v1` |
+| Codex | OpenAI Codex | Required | `https://api.openai.com/v1` |
+| Echo | UI testing (no LLM) | None | N/A |
+
+Pick a preset in **Settings → Provider** and the base URL + model dropdown fill in automatically. You can still override any field manually.
 
 ## Ollama (recommended local)
 
@@ -11,25 +64,27 @@ Mitii supports eight provider types. Pick the path that fits your workflow.
 ollama pull qwen3-coder:30b
 ```
 
-3. In Mitii **Settings → Model**:
+3. In Mitii **Settings → Provider**:
 
 | Field | Value |
 |-------|-------|
-| Provider type | OpenAI-compatible |
+| Preset | Ollama |
 | Base URL | `http://localhost:11434/v1` |
 | Model | `qwen3-coder:30b` |
 
-4. Click **Test connection** → Save
+4. Click **Test connection** → **Save**
+
+No API key needed.
 
 ## vLLM / LM Studio / self-hosted
 
-Set provider type to **OpenAI-compatible**. Point base URL at your server (include `/v1` if required). Add API key if needed.
+Set preset to **OpenAI-compatible**. Point base URL at your server (include `/v1` if required). Add API key if your server needs one.
 
 ## Anthropic (Claude)
 
 | Field | Value |
 |-------|-------|
-| Provider type | Anthropic |
+| Preset | Anthropic |
 | Model | `claude-sonnet-4-20250514` |
 | Context window | `200000` |
 
@@ -39,14 +94,14 @@ Add API key in settings. Mitii uses the native Messages API.
 
 | Field | Value |
 |-------|-------|
-| Provider type | Gemini |
+| Preset | Gemini |
 | Model | `gemini-2.0-flash` |
 
 Add API key in settings.
 
 ## OpenAI / DeepSeek / Cursor / Codex
 
-Select the matching provider type in settings. Defaults fill base URL and model name. Add API key and test connection.
+Select the matching preset in settings. Defaults fill base URL and model name. Add API key and test connection.
 
 ## Cloud OpenAI-compatible
 
@@ -54,21 +109,32 @@ Works with Azure OpenAI, Together, Groq, or any chat-completions API:
 
 ```json
 {
-  "thunder.provider.type": "openai-compatible",
-  "thunder.provider.baseUrl": "https://your-endpoint/v1",
-  "thunder.provider.model": "your-model"
+  "mitii.provider.preset": "openai-compatible",
+  "mitii.provider.baseUrl": "https://your-endpoint/v1",
+  "mitii.provider.model": "your-model"
 }
 ```
 
+## Token limits
+
+| Setting | What it does |
+|---------|-------------|
+| `mitii.provider.contextWindow` | Hard cap for prompt trimming (tokens). `0` = use the model preset default. |
+| `mitii.provider.maximumOutputTokens` | Max tokens per model response. `0` = derive ~20% of context window (min 10 240). |
+
+The settings UI shows a **derived budget** preview: usable input tokens, output reserve, model-call cap, files per mutation batch, and verification checks. It updates live as you change the context window or max output.
+
+Click **Reset budgets to defaults** to clear any custom `mitii.tokenBudget.*` overrides and restore built-in ratios.
+
 ## Plan vs Act models
 
 Use a fast model for planning and a strong model for implementation:
 
 ```json
 {
-  "thunder.provider.model": "qwen3-coder:30b",
-  "thunder.agent.planModel": "qwen3.5:4b",
-  "thunder.agent.actModel": "qwen3-coder:30b"
+  "mitii.provider.model": "qwen3-coder:30b",
+  "mitii.agent.planModel": "qwen3.5:4b",
+  "mitii.agent.actModel": "qwen3-coder:30b"
 }
 ```
 
@@ -76,11 +142,37 @@ Configure in **Settings → Agent**.
 
 ## Echo provider (no LLM)
 
-Set provider type to **Echo** to test UI, approvals, indexing, and tool routing without network calls.
+Set preset to **Echo** to test UI, approvals, indexing, and tool routing without network calls.
+
+CLI equivalent:
+
+```bash
+mitii ask "What is recursion?" --echo
+```
+
+## Profiles
+
+Switch between multiple provider configurations without re-entering settings. Profiles are stored in `.mitii/profiles.json`. Use the profile switcher in the sidebar to jump between, say, a local Ollama setup and a cloud Anthropic key.
+
+## SDK (programmatic)
+
+If you're building a custom host, inject a provider port directly:
+
+```ts
+import { createMitiiClient, AnthropicLlmPort } from '@mitii/sdk';
+
+const client = createMitiiClient({
+  understandingLlm: new AnthropicLlmPort({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  runLlm: new AnthropicLlmPort({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  workspaceRoot: process.cwd(),
+});
+```
+
+Available ports: `AnthropicLlmPort`, `GeminiLlmPort`, `OpenAiCompatibleLlmPort`, `EchoLlmPort`.
 
 ## Privacy
 
-Mitii does not send code to a Mitii server. Traffic goes only to the endpoint you configure. Indexes and logs stay in `.mitii/` on your machine.
+Mitii does not send code to a Mitii server. Traffic goes only to the endpoint you configure. API keys stay in VS Code SecretStorage (or env vars for CLI). Indexes and logs stay in `.mitii/` on your machine.
 
 ## Troubleshooting
 
@@ -88,8 +180,10 @@ Mitii does not send code to a Mitii server. Traffic goes only to the endpoint yo
 |-------|-----|
 | Connection refused | Start Ollama (`ollama serve`) or check base URL |
 | Model not found | `ollama list` — use exact model tag |
-| Anthropic/Gemini auth error | Verify API key in settings |
+| Anthropic/Gemini auth error | Verify API key in settings or env var |
 | Slow responses | Smaller model or GPU for Ollama |
-| Context trimmed | Increase `thunder.provider.contextWindow` |
+| Context trimmed | Increase `mitii.provider.contextWindow` |
+| CLI: no provider configured | Run `mitii setup` or set `ANTHROPIC_API_KEY` / `MITII_API_KEY` |
+| CLI: wrong model | `mitii setup --show` to verify, then re-run `mitii setup` |
 
 [Full provider reference →](/implementation/providers) · [Configuration →](/configuration)
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
index eca7e5c..8cd71ab 100644
--- a/docs/getting-started/index.md
+++ b/docs/getting-started/index.md
@@ -1,12 +1,18 @@
 # Getting Started
 
-Get Mitii AI Agent running in VS Code in a few minutes.
+> **Quick install** — VS Code: Extensions → "Mitii AI Agent" · CLI: `npm install -g @mitii/cli` · SDK: `npm install @mitii/sdk`
+
+Get Mitii AI Agent running in VS Code (or the CLI) in a few minutes.
 
 ## Requirements
 
-- **VS Code** 1.85+ (Cursor, Windsurf, and other forks work)
-- **Node.js** 20+ (for building from source)
-- An LLM endpoint: **Ollama** (recommended local), cloud API, or **Echo** for testing
+| Tool | Version |
+|------|---------|
+| VS Code | 1.124+ (Cursor, Windsurf, and other forks work) |
+| Node.js | 20+ (for building from source or using the CLI) |
+| pnpm | 10.13+ (for building from source) |
+
+You also need an LLM endpoint: **Ollama** (recommended local), a cloud API, or **Echo** for testing.
 
 ## Install from Marketplace
 
@@ -17,36 +23,60 @@ Get Mitii AI Agent running in VS Code in a few minutes.
 
 Or install directly: [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=mitii.mitii-ai-agent)
 
+## Install the CLI
+
+```bash
+npm install -g @mitii/cli
+# or try it without installing
+npx @mitii/cli --help
+```
+
+The CLI is headless — same engine, no UI. Configure it once with `mitii setup` and it works in scripts, CI, and terminals.
+
 ## Install from source
 
 ```bash
-git clone https://github.com/codewithshinde/thunder-ai-agent.git
-cd thunder-ai-agent
-npm install
-npm run rebuild:native   # if better-sqlite3 fails to load
-npm run compile
+git clone https://github.com/Mitii-dev/Mitii.git
+cd Mitii
+pnpm install
+pnpm run build:all
+```
+
+Or use the one-shot setup script (install + native rebuild + build in one step):
+
+```bash
+pnpm run setup          # VS Code
+pnpm run setup:cursor   # Cursor
 ```
 
 Press **F5** to launch the Extension Development Host. Open a project folder, wait for indexing, then chat.
 
 ## Connect a model
 
-1. Open **Settings** in the Mitii sidebar (gear icon)
-2. **Model** tab — pick provider type (Ollama = `openai-compatible`)
-3. Set base URL and model name
-4. Click **Test connection**
-5. Save
+1. Open **Settings → Provider** in the Mitii sidebar (or follow the onboarding prompt)
+2. Pick a **preset** (Ollama, Anthropic, Gemini, …) — it auto-fills base URL and model
+3. Add your API key if the provider requires one (local hosts usually don't)
+4. Click **Test connection** → **Save**
 
 Quick Ollama setup:
 
 ```json
 {
-  "thunder.provider.type": "openai-compatible",
-  "thunder.provider.baseUrl": "http://localhost:11434/v1",
-  "thunder.provider.model": "qwen3-coder:30b"
+  "mitii.provider.preset": "ollama",
+  "mitii.provider.baseUrl": "http://localhost:11434/v1",
+  "mitii.provider.model": "qwen3-coder:30b"
 }
 ```
 
+CLI equivalent:
+
+```bash
+mitii setup              # interactive — writes .mitii/config.json
+# or
+export ANTHROPIC_API_KEY=sk-...
+mitii session
+```
+
 [Detailed model guide →](/getting-started/connect-model) · [All providers →](/implementation/providers)
 
 ## First session
@@ -62,20 +92,26 @@ Quick Ollama setup:
 | Area | What it does |
 |------|----------------|
 | Chat | Messages, streaming, tool activity |
-| Retrieved context | Expand to see context debugger |
+| Retrieved context | Expand to see the context debugger |
 | Memory / Checkpoints | Side tabs below context |
-| Plan panel | Active plan steps |
+| Plan panel | Active plan steps and run state |
 | History | Past conversations |
-| Settings | Model, agent, safety, MCP, context |
+| Settings → Provider | Connect a model, token limits, profiles |
+| Settings → Workspace | Folder + repository index |
+| Settings → Modes | Ask / Plan / Agent defaults and run budget |
+| Settings → Context | What is attached to each turn |
+| Settings → MCP | Optional MCP servers |
+| Settings → Developer | Logging, token-budget tunables, diagnostics |
 
 ## Recommended first settings
 
 ```json
 {
-  "thunder.safety.autonomyPreset": "guided",
-  "thunder.agent.checkpointStrategy": "git-stash",
-  "thunder.indexing.autoIndexOnOpen": true,
-  "thunder.telemetry.sessionLogging": true
+  "mitii.safety.autonomyPreset": "guided",
+  "mitii.agent.checkpointStrategy": "git-stash",
+  "mitii.indexing.autoIndexOnOpen": true,
+  "mitii.indexing.vectorsEnabled": true,
+  "mitii.telemetry.sessionLogging": true
 }
 ```
 
@@ -83,7 +119,9 @@ Quick Ollama setup:
 
 - [Why Mitii?](/why-mitii) — what makes it different
 - [Connect a model](/getting-started/connect-model)
+- [Architecture](/architecture) — how the V8 engine works
 - [Features](/features/)
 - [Plan / Act workflow](/implementation/plan-act)
 - [Configuration](/configuration)
+- [Development](/development) — build from source, run tests
 - [Recent improvements](/implementation/recent-improvements)
diff --git a/docs/implementation/context-indexing.md b/docs/implementation/context-indexing.md
index 7ab1eb7..41bc879 100644
--- a/docs/implementation/context-indexing.md
+++ b/docs/implementation/context-indexing.md
@@ -1,58 +1,87 @@
 # Context & indexing
 
-Mitii builds a local search index so the agent understands your repo before editing.
+Mitii builds a local search index so the agent understands your repo before editing. All indexing runs on your machine — nothing is uploaded to external services.
 
-## Indexing pipeline
+## How it works
 
 ```mermaid
 flowchart TD
-  A[Open workspace] --> B[FileDiscoveryService]
-  B --> C[WorkspaceScanner]
-  C --> D[IndexQueue]
-  D --> E[Chunking + FTS5]
-  D --> F[Symbol extraction]
-  D --> G[Vector embedding]
-  E --> H[mitii.sqlite]
+  A[Open workspace] --> B[File discovery]
+  B --> C[Diff against last index]
+  C --> D[Index queue]
+  D --> E[Chunk + FTS5]
+  D --> F[Symbol extraction via tree-sitter]
+  D --> G[On-device vector embedding]
+  E --> H[.mitii/mitii.sqlite]
   F --> H
-  G --> I[LanceDB optional]
+  G --> H
+  G -.-> I[LanceDB optional]
 ```
 
-1. **Discovery** — scan files respecting `.gitignore` and `.mitiiignore`
-2. **Diff** — compare hash/mtime against SQLite `files` table
-3. **Queue** — parallel workers (default concurrency: 2)
-4. **Per file** — chunk → FTS index → tree-sitter symbols → optional vectors
+1. **Discovery** — scan files, respecting `.gitignore` and `.mitiiignore`
+2. **Diff** — compare hash/mtime against the SQLite `files` table to find what changed
+3. **Queue** — parallel workers (default concurrency: 2) process new/changed files
+4. **Per file** — chunk → full-text index → tree-sitter symbols → optional vectors
+
+## Large-repo indexing
+
+For big repositories the pipeline exposes three explicit phases so the UI can show progress and you can cancel at any time:
+
+| Phase | What happens | Status values |
+|-------|-------------|---------------|
+| **Scan** | File discovery + diff; no indexing yet | `scanning` → `scan_complete` |
+| **Index** | Chunking, FTS, symbols, vectors | `indexing` → `index_complete` |
+| **Cancel** | User-initiated stop | `cancelled` |
+
+If indexing is interrupted or a file exceeds size limits, the index enters **partial-index** status: already-indexed files remain searchable and the agent operates in a "degraded but usable" mode rather than blocking.
+
+## Embeddings
+
+Vector embeddings are produced **on-device** by the bundled embedding host. It generates `EmbeddingProvider` vectors without calling your chat-model provider — no extra API costs, no network round-trips.
+
+| Option | Description |
+|--------|-------------|
+| `minilm` (default) | Small local model; good balance of quality and speed |
+| `hash` | Deterministic fallback when no model is available |
+
+Vector storage backend:
+
+| Backend | Storage |
+|---------|---------|
+| `sqlite` (default) | Vectors stored in `.mitii/mitii.sqlite` |
+| `lancedb` | Vectors stored in `.mitii/lance/` (optional, for very large repos) |
 
 ## Settings
 
-| Setting | Default | Description |
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.indexing.enabled` | `true` | Master switch |
-| `thunder.indexing.autoIndexOnOpen` | `true` | Index on folder open |
-| `thunder.indexing.maxFileSizeBytes` | `512000` | Full index up to this size |
-| `thunder.indexing.hardSkipSizeBytes` | `2000000` | Skip larger files entirely |
-| `thunder.indexing.vectorsEnabled` | `true` | Semantic vectors |
-| `thunder.indexing.embeddingProvider` | `minilm` | `minilm` or `hash` fallback |
-| `thunder.indexing.vectorBackend` | `sqlite` | `sqlite` or `lancedb` |
-| `thunder.indexing.treeSitterEnabled` | `true` | WASM symbol extraction |
+| `mitii.indexing.enabled` | `true` | Master switch for the index |
+| `mitii.indexing.autoIndexOnOpen` | `true` | Index automatically when you open a folder |
+| `mitii.indexing.maxFileSizeBytes` | `512000` | Index files up to this size (~500 KB) |
+| `mitii.indexing.hardSkipSizeBytes` | `2000000` | Skip files larger than this (~2 MB) entirely |
+| `mitii.indexing.vectorsEnabled` | `true` | Enable semantic vector search |
+| `mitii.indexing.embeddingProvider` | `minilm` | `minilm` or `hash` fallback |
+| `mitii.indexing.vectorBackend` | `sqlite` | `sqlite` or `lancedb` |
+| `mitii.indexing.treeSitterEnabled` | `true` | WASM-based symbol extraction |
 
-## Retrieval sources
+## Retrieval
 
-**HybridRetriever** queries sources in parallel (800ms timeout each):
+When the agent needs context, the **Repository Context** module queries multiple sources in parallel (800 ms timeout each):
 
 | Tier | Sources |
 |------|---------|
-| Explicit | Project rules, `@` mentions, skills catalog |
-| Editor | Current file, open files, workspace overview |
-| Workspace | Git diff, LSP diagnostics |
-| Search | FTS, indexed file search, vectors, repo map, memory |
+| **Explicit** | Project rules, `@` mentions, skills catalog |
+| **Editor** | Current file, open files, workspace overview |
+| **Workspace** | Git diff, LSP diagnostics |
+| **Search** | Full-text search, indexed file search, vectors, repo map, memory |
 
-Toggle sources in **Settings → Context**.
+Toggle individual sources in **Settings → Context**.
 
-## Reranker & budgeter
+### Reranking & budgeting
 
-1. **Reranker** — top 20 candidates → top 8 (`thunder.context.rerankerTopK`)
-2. **ContextBudgeter** — allocate tokens per source within model window
-3. **Dropped items** — surfaced in context debugger and warning banner
+1. **Reranker** — narrows top 20 candidates down to top 8 (`mitii.context.rerankerTopK`)
+2. **Window budget** — allocates tokens per source within the model's context window
+3. **Dropped items** — anything that doesn't fit is surfaced in the context debugger with a reason
 
 ## Context debugger
 
@@ -60,47 +89,62 @@ Expand **Retrieved context** in the chat sidebar to see:
 
 - Retrieved vs included token counts
 - Per-source breakdown (FTS, vectors, rules, git, etc.)
-- Included snippets with paths and reasons
+- Included snippets with file paths and inclusion reasons
 - Dropped items with cause (`over_budget`, `not_selected`)
 
 ## Pinned context
 
-- Add files/folders via `@` mentions or context picker
-- Pinned items always considered for retrieval
-- Shown in **Pinned context** panel above chat
+- Add files or folders via `@` mentions or the context picker
+- Pinned items are always considered during retrieval
+- Shown in the **Pinned context** panel above the chat input
 
 ## Built-in retrieval tools
 
-| Tool | Purpose |
-|------|---------|
-| `search` | FTS / ripgrep query |
-| `search_batch` | Multiple queries at once |
-| `retrieve_context` | On-demand hybrid retrieval |
-| `repo_map` | PageRank-weighted file listing |
+The agent can call these tools during a run:
+
+| Tool | What it does |
+|------|-------------|
+| `search` | Full-text / ripgrep query across the workspace |
+| `search_batch` | Run multiple search queries at once |
+| `retrieve_context` | On-demand hybrid retrieval (FTS + vectors) |
+| `repo_map` | PageRank-weighted file listing for structural overview |
 | `list_files` | Directory listing |
-| `read_file` / `read_files` | File contents |
+| `read_file` / `read_files` | Read file contents |
+| `propose_file_scope` | Declare candidate file paths before reading or editing (default in Act mode) |
 
 ## Repo map
 
-PageRank over import/symbol graph highlights structurally central files — useful when the agent doesn't know where to start.
+PageRank over the import/symbol graph highlights structurally central files — useful when the agent doesn't know where to start exploring.
 
 ## Ignore files
 
-- `.gitignore` — respected by default
-- `.mitiiignore` — additional Mitii-specific ignores
-- Legacy `.thunderignore` still honored
+| File | Purpose |
+|------|---------|
+| `.gitignore` | Respected by default |
+| `.mitiiignore` | Additional Mitii-specific ignores |
+| `.thunderignore` | Legacy — still honored for backward compatibility |
 
 ## Manual re-index
 
-- Click indexing status in sidebar toolbar
-- Command: **Mitii: Index Workspace**
-- Force re-index after large refactors
+- Click the indexing status chip in the sidebar toolbar
+- Command palette: **Mitii: Index Workspace**
+- Useful after large refactors or when you add new directories
 
 ## Storage
 
 | Path | Contents |
 |------|----------|
-| `.mitii/mitii.sqlite` | FTS, symbols, vectors (sqlite backend), sessions |
+| `.mitii/mitii.sqlite` | FTS index, symbols, vectors (sqlite backend), sessions |
 | `.mitii/lance/` | Vector data when `vectorBackend: lancedb` |
 
-Nothing is uploaded to external index services.
+Everything stays local. No external index services are called.
+
+## Where it lives in the codebase
+
+| Package | Responsibility |
+|---------|---------------|
+| `@mitii/host` | Filesystem adapters, workspace indexing pipeline, tree-sitter runtime, bundled embeddings |
+| `@mitii/v8` | Repository Context module (retrieval, reranking, budgeting), code-navigation, change-impact |
+| `@mitii/sdk` | Public API surface for custom hosts |
+
+The host owns the "how to scan and index" logic; V8 owns the "how to retrieve and rank" logic. This separation means the same index works across VS Code, CLI, and any custom host built on `@mitii/sdk`.
diff --git a/docs/implementation/mcp.md b/docs/implementation/mcp.md
index c95a616..a0489eb 100644
--- a/docs/implementation/mcp.md
+++ b/docs/implementation/mcp.md
@@ -1,26 +1,37 @@
 # MCP integrations
 
-Mitii implements the [Model Context Protocol](https://modelcontextprotocol.io/) so you can extend the agent with external tools.
+Mitii speaks the [Model Context Protocol](https://modelcontextprotocol.io/) so you can plug in external tools — file access, memory graphs, custom APIs — without writing any code. MCP is an **app-level** feature: the VS Code extension and CLI own the server lifecycle, while the V8 engine enforces every tool call through the same Decision Policy gate as built-in tools.
 
-## Built-in servers
+## Turning MCP on
 
-Preloaded when `thunder.mcp.enabled` and `thunder.mcp.preloadBuiltin` are true:
+MCP is **off by default**. Enable it in **Settings → Integrations**:
 
-| Server | Package | Purpose |
-|--------|---------|---------|
-| `filesystem` | `@modelcontextprotocol/server-filesystem` | Scoped file access |
-| `memory` | `@modelcontextprotocol/server-memory` | Knowledge graph memory |
-| `sequential-thinking` | `@modelcontextprotocol/server-sequential-thinking` | Structured reasoning |
+| Setting | What it does |
+|---------|-------------|
+| `mitii.mcp.enabled` | Master switch. When off, no MCP servers start. |
+| `mitii.mcp.servers` | Your installed server list. Enable, configure, or delete each one here. |
 
-Toggle individual servers in **Settings → Integrations**.
+You can also install servers from the **built-in catalog** — picking one copies its config into your workspace list so you can tweak it.
+
+## Built-in catalog servers
+
+These ship with Mitii and are one click to install:
+
+| Server | What it gives you |
+|--------|-------------------|
+| `filesystem` | Scoped read/write access to a folder you choose |
+| `memory` | A knowledge-graph store the agent can query |
+| `sequential-thinking` | Structured step-by-step reasoning traces |
 
 ## Transport types
 
-| Type | Use case | Required fields |
-|------|----------|-----------------|
-| `stdio` | Local `npx` servers | `command`, `args` |
-| `sse` | Remote SSE endpoint | `url`, optional `headers` |
-| `streamable-http` | MCP Streamable HTTP | `url`, optional `headers` |
+Each server connects over one of three transports:
+
+| Type | When to use | Required fields |
+|------|-------------|-----------------|
+| `stdio` | Local process (e.g. `npx`) | `command`, `args` |
+| `sse` | Remote Server-Sent Events endpoint | `url`, optional `headers` |
+| `streamable-http` | MCP Streamable HTTP (newer spec) | `url`, optional `headers` |
 
 ### Stdio example (`.mitii/mcp.json`)
 
@@ -67,52 +78,58 @@ Toggle individual servers in **Settings → Integrations**.
 }
 ```
 
-## Configuration sources (merged)
+## Where configs are read (merge order)
 
-1. Built-in servers (if preload enabled)
-2. VS Code `thunder.mcp.servers`
-3. Workspace `.mitii/mcp.json`
-4. Workspace `.mcp.json`
+Mitii merges these sources top-to-bottom; later entries override earlier ones with the same server name:
 
-Workspace entries override settings with the same server name.
+1. Built-in catalog (if you installed from it)
+2. VS Code setting `mitii.mcp.servers`
+3. Workspace `.mitii/mcp.json`
+4. Workspace `.mcp.json` (shared with other MCP clients)
 
-## Runtime behavior
+## How MCP tools run
 
-- Tools exposed as `mcp__{server}__{tool}` (max 128 chars)
-- Concurrent startup limit: `thunder.mcp.maxConcurrentStartup` (default 4)
-- MCP tools pass through **ToolPolicyEngine** — same approvals as built-in tools
-- Status shown in **Settings → Integrations** (connected, tool count, errors)
+- Tools are exposed to the model as `mcp__{server}__{tool}` (name capped at 128 chars).
+- Every call passes through **Decision Policy** → **Tool Runtime**, the same enforcement path as built-in tools. The runtime validates the grant, checks path scope, command rules, and output limits, then executes through host ports.
+- In **Act mode**, you can exclude specific MCP tools from being offered to the model ("Act mode MCP exclusions").
+- Concurrent server startup is capped by `mitii.mcp.maxConcurrentStartup` (default **4**).
+- Runtime status (ready / error / disabled) is shown in **Settings → Integrations** for diagnostics.
 
-## OAuth / authentication
+## Authentication
 
 For remote servers:
 
-- Pass bearer token in `headers.Authorization`
-- Or set `oauth.accessToken` in server config (static token provider)
+- Pass a bearer token in `headers.Authorization`, **or**
+- Set `oauth.accessToken` in the server config (static token provider).
 
 Interactive OAuth browser flow is not yet exposed in the UI — use pre-issued tokens.
 
 ## Disabling MCP
 
-```json
-{
-  "thunder.mcp.enabled": false
-}
-```
-
-Or disable built-in preload only:
+Turn off everything:
 
 ```json
-{
-  "thunder.mcp.preloadBuiltin": false
-}
+{ "mitii.mcp.enabled": false }
 ```
 
+Or remove a single server from **Settings → Integrations → Installed servers**.
+
 ## Troubleshooting
 
-| Issue | Fix |
-|-------|-----|
-| Server won't start | Check `npx` is on PATH; read error in Integrations status |
-| Missing tools | Confirm server connected; check `toolCount` in status |
-| Remote 401 | Verify bearer token in headers |
-| Slow startup | Lower `maxConcurrentStartup` or disable unused servers |
+| Issue | What to check |
+|-------|---------------|
+| Server won't start | Is `npx` (or the binary) on PATH? Read the error in Integrations status. |
+| Tools not showing | Confirm the server is **ready** (not error/disabled) and check its tool count. |
+| Remote 401 / 403 | Verify the bearer token in `headers.Authorization`. |
+| Slow startup | Lower `maxConcurrentStartup` or disable servers you don't use. |
+| Tool blocked in Act mode | Check the Act-mode MCP exclusion list in settings. |
+
+## Where MCP lives in the codebase
+
+| Layer | Responsibility |
+|-------|----------------|
+| `apps/vscode` / `apps/cli` | Server lifecycle, settings UI, config merge, status display |
+| `@mitii/host` | Host ports the Tool Runtime uses to execute (filesystem, process, network) |
+| `@mitii/v8` (Tool Runtime + Decision Policy) | Grant validation, enforcement, audit, output sanitisation |
+
+This separation means MCP works identically in VS Code, the CLI, and any custom host built on `@mitii/sdk`.
diff --git a/docs/implementation/memory-checkpoints.md b/docs/implementation/memory-checkpoints.md
index d0b8f42..5c5e9c9 100644
--- a/docs/implementation/memory-checkpoints.md
+++ b/docs/implementation/memory-checkpoints.md
@@ -1,14 +1,26 @@
 # Memory & checkpoints
 
-Mitii persists knowledge and file state so you can recover from mistakes and build on past sessions.
+Mitii persists knowledge and file state so you can recover from mistakes and build on past sessions. The **Memory** module (in `@mitii/v8`) retrieves and commits durable facts scoped to a **user**, **workspace**, or **project**, and supplies relevant prior preferences to Prompt Construction as instruction blocks. Checkpoints (managed by `@mitii/host`) capture file state before approved writes so you can roll back.
+
+---
 
 ## Long-term memory
 
+### What it does
+
+- Retrieves candidate memory facts from an injected store
+- Filters by **scope** (user / workspace / project), **privacy**, **expiry**, and **superseded versions**
+- Ranks with **BM25** fused with file-target hits and an optional embedding port
+- Applies **access-based retention** — cold facts lose rank over time (no hard 30-day delete)
+- Enforces a **token budget** and **max-fact limit**
+- Returns **prompt-ready instruction blocks** that Prompt Construction injects into the next turn
+- Commits new facts after **privacy redaction**, **hash reinforcement**, and **Jaccard supersede** (near-duplicate detection)
+
 ### Tools
 
 | Tool | Purpose |
 |------|---------|
-| `memory_search` | Hybrid FTS5 + optional vector search over observations |
+| `memory_search` | Hybrid BM25 + optional vector search over stored facts |
 | `memory_write` | Store decisions, preferences, bugfixes, architecture notes |
 
 ### Observation types
@@ -17,36 +29,47 @@ Mitii persists knowledge and file state so you can recover from mistakes and bui
 
 ### How memory gets populated
 
-1. **Agent writes** via `memory_write` during tasks
-2. **Post-task extraction** — `MemoryExtractor` summarizes completed work (async)
-3. **Passive injection** — relevant memories auto-injected into new chat context
+1. **Agent writes** — the model calls `memory_write` during a task
+2. **Post-task extraction** — a host capture helper (`buildSyntheticMemoryDraft`) summarizes completed work asynchronously
+3. **Passive injection** — relevant memories are retrieved and injected as instruction blocks into the next chat turn
+
+### Storage
+
+| Location | What lives there |
+|----------|-----------------|
+| `.mitii/memory/facts.json` | Committed memory facts (workspace-scoped) |
+| SQLite `observations` table | VS Code Memento-backed observations (app-level) |
+
+An empty store is a **cold start** (`memory_empty` reason code), not a missing adapter. Reusable facts are only available after a prior run committed them.
 
 ### Settings
 
-| Setting | Default | Description |
+| Setting | Default | What it does |
 |---------|---------|-------------|
-| `thunder.memory.enabled` | `true` | Enable memory system |
-| `thunder.memory.hybridSearchEnabled` | `true` | FTS + vector hybrid search |
-| `thunder.memory.maxItems` | `500` | Max observations |
-| `thunder.memory.summarizeAfterTask` | `true` | Extract memories after tasks |
+| `mitii.memory.enabled` | `true` | Enable the memory system |
+| `mitii.memory.hybridSearchEnabled` | `true` | BM25 + vector hybrid search |
+| `mitii.memory.maxItems` | `500` | Max facts returned per retrieval |
+| `mitii.memory.summarizeAfterTask` | `true` | Extract memories after task completion |
 
 ### Memory panel
 
-The sidebar **Memory** tab lists recent observations. Delete individual items or **Clear all**. Data stored in `mitii.sqlite` → `observations` table.
+The sidebar **Memory** tab lists recent observations. Delete individual items or **Clear all**.
 
 ### Safety
 
-Secret patterns (API keys, tokens) are filtered from memory writes.
+- Secret patterns (API keys, tokens) are **redacted** before commit
+- Privacy level is stored per-fact and enforced at retrieval time
+- Near-duplicate facts are superseded via Jaccard similarity (no unbounded growth)
 
 ---
 
 ## Checkpoints
 
-Checkpoints capture file state **before approved writes** so you can roll back.
+Checkpoints capture file state **before approved writes** so you can roll back. They are part of V8's safety model: "Safe execution with explicit capabilities, approvals, checkpoints, and evidence."
 
 ### Strategies
 
-Set `thunder.agent.checkpointStrategy`:
+Set `mitii.agent.checkpointStrategy`:
 
 | Strategy | Behavior |
 |----------|----------|
@@ -58,7 +81,7 @@ If git stash fails, Mitii falls back to file copy automatically.
 
 ### When checkpoints are created
 
-- Before approved `write_file` or `apply_patch`
+- Before approved `write_file` or `apply_patch` (enforced by the **Tool Runtime**)
 - Metadata includes branch name and diff snapshot when git is available
 
 ### Restore
@@ -67,11 +90,16 @@ If git stash fails, Mitii falls back to file copy automatically.
 2. Click **Restore** on a checkpoint
 3. Files revert via stash apply or file copy
 
-Checkpoint metadata stored in SQLite; file copies in `.mitii/checkpoints/`.
+### Storage
+
+| Location | What lives there |
+|----------|-----------------|
+| SQLite | Checkpoint metadata (id, timestamp, strategy, file list) |
+| `.mitii/checkpoints/<id>/` | File copies (file-copy strategy) |
 
 ### Cleanup
 
-Old checkpoints are pruned after 7 days by default (`CheckpointService.cleanup`).
+Old checkpoints are pruned after **7 days** by default.
 
 ---
 
@@ -79,7 +107,7 @@ Old checkpoints are pruned after 7 days by default (`CheckpointService.cleanup`)
 
 - **History tab** — browse past chat threads (title, message count, token totals)
 - **Resume** — open a thread to continue conversation
-- Stored in SQLite `agent_sessions` / `agent_turns`
+- Stored in SQLite `agent_sessions` / `agent_turns` (injected by the app)
 
 ---
 
@@ -104,3 +132,17 @@ Structured JSONL in `.mitii/logs/<session-id>.jsonl`:
 - Errors and timing
 
 Export via **Mitii: Export Session Log** command.
+
+---
+
+## Codebase location
+
+| Concern | Owner |
+|---------|-------|
+| Memory pipeline (retrieve, rank, commit, budget) | `@mitii/v8` → `memory/` module |
+| Memory store adapter (file-based) | `@mitii/host` → `ports/memory` |
+| VS Code Memento memory | `apps/vscode` |
+| Checkpoint strategies (git-stash, file-copy) | `@mitii/host` → `ports/checkpoints` |
+| Checkpoint enforcement (when to snapshot) | `@mitii/v8` → Tool Runtime |
+| Session / plan persistence (SQLite) | App (injected via `openDatabase` port) |
+| Public API surface | `@mitii/sdk` |
diff --git a/docs/implementation/plan-act.md b/docs/implementation/plan-act.md
index 6f9bb06..253e6ba 100644
--- a/docs/implementation/plan-act.md
+++ b/docs/implementation/plan-act.md
@@ -1,15 +1,33 @@
 # Plan / Act workflow
 
-Mitii separates **analysis** from **execution** so you can review a plan before any file changes.
+Mitii separates **analysis** from **execution** so you can review a plan before any file changes. The V8 engine uses a three-layer architecture:
+
+| Layer | Role |
+|-------|------|
+| **Agent Engine** | Orchestrates the run lifecycle: start, event streaming, checkpointing, suspend/resume, model/tool loop |
+| **Decision Policy** | Converts request evidence into an `ExecutionDecision` — route (Ask / Plan / Act), whether planning is required, and which tools may run |
+| **Tool Runtime** | Enforces every tool call against the current `ToolGrant` (allowed tools, maximum workspace effect, allowed effects) before execution |
+
+## Skill routing
+
+Before executing a plan, the Agent Engine routes the task through a **skill playbook** (`SKILL.md`). Skills are bundled in `packages/sdk/skills/` and loaded via `createFileSystemSkillsCatalog()`; workspace overrides live in `.mitii/skills/`. Each skill defines three phases:
+
+| Phase | What happens |
+|-------|-------------|
+| **Planning** | Discover, decompose, and order tasks with acceptance criteria |
+| **Change** | Implement with minimal, reviewable diffs |
+| **Verify** | Prove the change with tests, typecheck, and lint |
+
+Skills are composable: the agent selects the most relevant skill for the task (by intent, route, and priority) and follows its instruction blocks. Skills in the same `conflictGroup` are mutually exclusive — the highest-priority skill wins.
 
 ## Modes
 
-| Mode | Internal key | Writes | Shell |
-|------|--------------|--------|-------|
-| Ask | `ask` | No | Read-only only |
-| Plan | `plan` | No | Read-only only |
-| Agent | `agent` | Yes (policy) | Yes (policy) |
-| Review | `review` | No | Read-only only |
+| Mode | Route | Writes? | Tool scope |
+|------|-------|---------|------------|
+| **Ask** | `ask` | No | Read-only only |
+| **Plan** | `plan` | No | Read-only + plan tools |
+| **Agent** | `execute` | Yes | Full tool set (gated by `ToolGrant`) |
+| **Review** | `review` | No | Read-only only |
 
 Switch modes from the chat input toolbar. Legacy `act` maps to `agent`.
 
@@ -17,11 +35,13 @@ Switch modes from the chat input toolbar. Legacy `act` maps to `agent`.
 
 ```mermaid
 flowchart LR
-  A[Plan mode] --> B[Review plan]
-  B --> C[Agent mode]
-  C --> D[Approve writes]
-  D --> E[Verify lint/test]
-  E --> F[Review mode optional]
+  A[Plan mode] --> B[Read-only analysis]
+  B --> C[Propose plan]
+  C --> D{User approves?}
+  D -- yes --> E[Agent mode]
+  E --> F[Execute steps]
+  F --> G[Verify: lint / typecheck / test]
+  D -- no --> A
 ```
 
 1. **Plan** — describe the feature; agent retrieves context and outputs a structured plan
@@ -33,77 +53,65 @@ flowchart LR
 
 ## Plan engine
 
-When `thunder.agent.orchestrationEnabled` is true (default):
-
-- **PlanExecutor** runs multi-phase steps: diagnostics → review → execute → verify
+- **Agent Engine** runs multi-phase steps: diagnostics → review → execute → verify
 - Steps have status: `pending`, `running`, `done`, `blocked`, `failed`
 - Plans persist to SQLite `task_plans` and `.mitii/tasks/<id>/plan.json`
 - Plan tools: `mark_step_complete`, `propose_plan_mutation`
+- **Decision Policy** decides whether to use the planner or a faster direct agent path in Agent mode. All tool calls — including plan tools — pass through the **Tool Runtime**, which validates each call against the current `ToolGrant` before execution and returns bounded results.
 
-**Planning skills** — for structured plans, Mitii auto-loads workspace playbooks from `.mitii/skills/`:
+**Planning skills** — for structured plans, Mitii auto-loads bundled skills from `packages/sdk/skills/` (workspace overrides in `.mitii/skills/`):
 
 | Skill | When loaded |
 |-------|-------------|
-| `using-agent-skills` | Every orchestrated plan |
-| `planning-and-task-breakdown` | Every orchestrated plan |
-| `audit-cleanup` | Audit / cleanup tasks |
+| `planning-default` | Every orchestrated plan (baseline) |
+| `planning-and-task-breakdown` | Feature / refactor / multi-step tasks |
+| `safety-always` | Every run (always-apply) |
 | `debugging-and-error-recovery` | Bugfix / debug tasks |
-
-Skill content is injected into discovery, requirement analysis, and isolated plan compilation. The Planner panel shows applied skills, requirement analysis, phased steps, tools, and success criteria (Cursor-style).
-
-**TaskAnalyzer** decides whether to use the planner or a faster direct agent path in Agent mode.
-
-```mermaid
-flowchart TB
-  subgraph planMode [Plan mode pipeline]
-    R[Route intent + scope]
-    S[Load planning skills]
-    D[Read-only discovery]
-    A[Requirement analysis]
-    C[Isolated plan compiler]
-    P[Planner panel + plan.json]
-  end
-  R --> S --> D --> A --> C --> P
-```
+| `code-review-and-quality` | Review / quality tasks |
+| `test-driven-development` | Test-heavy tasks |
 
 ## Plan vs Act models
 
-Use different models for planning and implementation:
-
-```json
-{
-  "thunder.provider.model": "qwen3-coder:30b",
-  "thunder.agent.planModel": "qwen3.5:4b",
-  "thunder.agent.actModel": "qwen3-coder:30b"
-}
-```
-
-Optional `planBaseUrl` / `actBaseUrl` override the main provider URL per mode.
+| Aspect | Plan mode | Agent mode |
+|--------|-----------|------------|
+| Writes files | No | Yes (gated) |
+| Tool scope | Read-only + plan tools | Full set via `ToolGrant` |
+| Approval | User reviews plan | Per-step or batch approval |
+| Checkpoints | N/A | Auto-checkpoint before mutations |
+| Rollback | N/A | Revert to last checkpoint |
 
 ## Orchestration settings
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `thunder.agent.orchestrationEnabled` | `true` | Multi-step planner in Plan mode |
-| `thunder.agent.maxSteps` | `15` | Max tool rounds per agent turn |
-| `thunder.agent.autoContinue` | `true` | Continue after step limit |
-| `thunder.agent.maxAutoContinues` | `2` | Max continuation rounds |
-| `thunder.agent.verifyOnActComplete` | `true` | Run verify commands after Act |
-| `thunder.agent.verifyCommands` | `["npm run lint", "npm test"]` | Commands to run |
+| `mitii.agent.orchestrationEnabled` | `true` | Multi-step planner in Plan mode |
+| `mitii.agent.maxSteps` | `15` | Max tool rounds per agent turn |
+| `mitii.agent.autoContinue` | `false` | Auto-continue after approval |
+| `mitii.agent.verifyCommands` | `["pnpm run lint", "pnpm test"]` | Commands to run |
+| `mitii.agent.checkpointEnabled` | `true` | Auto-checkpoint before mutations |
 
 ## Research subagents
 
-`spawn_research_agent` launches read-only parallel workers for exploration:
+- `spawn_research_agent` — read-only subagent for parallel exploration
+- Subagents inherit the parent `ToolGrant` minus write permissions
+- Results are summarized back into the parent context
+
+## Task state
 
-- Config: `thunder.agent.subagentsEnabled`, `researchAgentMaxSteps`, `researchAgentModel`
-- Useful for broad audits before planning
+- `AgentTaskState` tracks: current step, step status, tool history, checkpoint ID
+- `save_task_state` persists state after each step for suspend/resume
+- State is stored in SQLite and mirrored to `.mitii/tasks/<id>/state.json`
 
-## Task state across approvals
+## Checkpoints and rollback
 
-When the agent pauses for approval:
+- Auto-checkpoint before each mutating tool call (when `checkpointEnabled` is true)
+- Checkpoints capture: file diffs, git HEAD, task state
+- Rollback reverts to the last checkpoint and restores task state
+- Checkpoints are retained for the session lifetime
 
-- **AgentTaskState** preserves progress
-- **Approval checkpoints** inject an LLM summary on resume
-- `save_task_state` tool for explicit mid-task saves
+## Evidence and verification
 
-See [Safety](/implementation/safety) for approval policies.
+- Every step produces evidence: tool output, diagnostics, test results
+- Verification phase runs `verifyCommands` and reports pass/fail per command
+- Failed verification blocks step completion and surfaces the error to the user
+- Evidence is attached to the plan step for audit trail
diff --git a/docs/implementation/providers.md b/docs/implementation/providers.md
index 8b17c0f..b51923f 100644
--- a/docs/implementation/providers.md
+++ b/docs/implementation/providers.md
@@ -1,31 +1,83 @@
 # LLM providers
 
-Mitii supports eight provider types. Configure in the sidebar **Settings → Model** or VS Code settings under `thunder.provider.*`.
+Mitii supports eight provider types. Configure in the sidebar **Settings → Provider** page or VS Code settings under `mitii.provider.*`. The same settings work across VS Code, the CLI (`@mitii/cli`), and any custom host built on `@mitii/sdk`.
 
-## Provider matrix
+Providers plug into the **Agent Engine** (V8 module stack) through the `@mitii/sdk` host-neutral API. The SDK abstracts the transport so the same provider config works everywhere.
 
-| Type | Best for | API key | Default base URL |
-|------|----------|---------|------------------|
-| `openai-compatible` | Ollama, LM Studio, vLLM | Optional | `http://localhost:11434/v1` |
-| `openai` | OpenAI GPT models | Required | `https://api.openai.com/v1` |
-| `anthropic` | Claude | Required | `https://api.anthropic.com` |
-| `gemini` | Google Gemini | Required | `https://generativelanguage.googleapis.com` |
-| `deepseek` | DeepSeek Chat | Required | `https://api.deepseek.com/v1` |
-| `cursor` | Cursor API | Required | `https://api.cursor.com/v1` |
-| `codex` | OpenAI Codex | Required | `https://api.openai.com/v1` |
-| `echo` | UI testing | None | N/A |
+## Presets vs. types
+
+The settings UI uses **presets** as the primary selector. A preset prefills the base URL, default model, and whether an API key is required. Under the hood the wire protocol is still a **type** (`mitii.provider.type`).
+
+| Preset | Type | Best for | API key | Default base URL |
+|--------|------|----------|---------|------------------|
+| Ollama | `openai-compatible` | Local LLMs (Ollama, LM Studio, vLLM) | Optional | `http://localhost:11434/v1` |
+| OpenAI | `openai` | OpenAI GPT models | Required | `https://api.openai.com/v1` |
+| Anthropic | `anthropic` | Claude | Required | `https://api.anthropic.com` |
+| Gemini | `gemini` | Google Gemini | Required | `https://generativelanguage.googleapis.com` |
+| DeepSeek | `deepseek` | DeepSeek Chat | Required | `https://api.deepseek.com/v1` |
+| Cursor | `cursor` | Cursor API | Required | `https://api.cursor.com/v1` |
+| Codex | `codex` | OpenAI Codex | Required | `https://api.openai.com/v1` |
+| Echo | `echo` | UI testing (no network) | None | N/A |
 
 ## Settings
 
-| Setting | Description |
+| Setting | What it does |
 |---------|-------------|
-| `thunder.provider.type` | Provider type (see table) |
-| `thunder.provider.baseUrl` | API base URL |
-| `thunder.provider.model` | Model name in chat requests |
-| `thunder.provider.contextWindow` | Hard cap for prompt trimming (tokens) |
-| API key | Stored in VS Code SecretStorage via settings UI |
+| `mitii.provider.preset` | Preset selector (prefills type, base URL, model) |
+| `mitii.provider.type` | Wire protocol type (see table above) |
+| `mitii.provider.baseUrl` | API base URL (saved as typed) |
+| `mitii.provider.model` | Model name in chat requests (dropdown or custom) |
+| `mitii.provider.contextWindow` | Hard cap for prompt trimming (tokens). `0` = use the model preset default. |
+| `mitii.provider.maximumOutputTokens` | Output reserve. `0` derives ~20% of context window (floored at 10 240). |
+| `mitii.provider.apiKey` | Stored in **VS Code SecretStorage** — never written to settings JSON. |
+
+Use **Test connection** in settings before saving cloud providers. The test is a host probe that shows a status pill only — it is not a persisted setting.
+
+## Token budget
+
+The context window is the only token setting a user needs. Retrieval, compaction, mutation batches, verification checks, and the derived model-call cap all scale from that window.
+
+- **Derived budget** (live preview): usable input, output reserve, model-call cap, files per mutation, verification checks, and a module-share bar. Updates as soon as the context window or max output changes.
+- **Reset budgets to defaults**: clears `mitii.tokenBudget.*` overrides and restores built-in ratios for the current window.
+
+## Profiles
+
+Switch between multiple provider configurations without editing settings each time. Profiles are stored in `.mitii/profiles.json` in your workspace.
+
+## CLI configuration
+
+```bash
+# Interactive setup — writes .mitii/config.json
+mitii setup
+
+# Or set env vars (never printed by --show)
+export ANTHROPIC_API_KEY=sk-ant-...
+export GEMINI_API_KEY=...
+export OPENAI_API_KEY=...
+export MITII_API_KEY=...
 
-Use **Test connection** in settings before saving cloud providers.
+# Smoke test without a live model
+mitii ask "What is recursion?" --echo
+
+# Check current config (no secrets)
+mitii setup --show
+```
+
+CLI flags: `--provider <id>`, `--model <id>`, `--base-url <url>`, `--mode <ask|plan|agent>`.
+
+## SDK (custom hosts)
+
+For custom applications, inject an `LlmPort` implementation via `@mitii/sdk`:
+
+```ts
+import { createMitiiClient, EchoLlmPort, AnthropicLlmPort, GeminiLlmPort, OpenAiCompatibleLlmPort } from "@mitii/sdk";
+
+const client = createMitiiClient({
+  llm: new AnthropicLlmPort({ apiKey: process.env.ANTHROPIC_API_KEY }),
+});
+```
+
+Apps and tests use the SDK instead of importing V8 internals directly.
 
 ## Local: Ollama
 
@@ -36,10 +88,11 @@ ollama serve
 
 ```json
 {
-  "thunder.provider.type": "openai-compatible",
-  "thunder.provider.baseUrl": "http://localhost:11434/v1",
-  "thunder.provider.model": "qwen3-coder:30b",
-  "thunder.provider.contextWindow": 32768
+  "mitii.provider.preset": "ollama",
+  "mitii.provider.type": "openai-compatible",
+  "mitii.provider.baseUrl": "http://localhost:11434/v1",
+  "mitii.provider.model": "qwen3-coder:30b",
+  "mitii.provider.contextWindow": 32768
 }
 ```
 
@@ -47,21 +100,23 @@ ollama serve
 
 ```json
 {
-  "thunder.provider.type": "anthropic",
-  "thunder.provider.model": "claude-sonnet-4-20250514",
-  "thunder.provider.contextWindow": 200000
+  "mitii.provider.preset": "anthropic",
+  "mitii.provider.type": "anthropic",
+  "mitii.provider.model": "claude-sonnet-4-20250514",
+  "mitii.provider.contextWindow": 200000
 }
 ```
 
-Add API key in settings. Mitii uses the native Messages API with streaming and tool calling.
+Add API key in settings (SecretStorage). Mitii uses the native Messages API with streaming and tool calling.
 
 ## Cloud: Gemini
 
 ```json
 {
-  "thunder.provider.type": "gemini",
-  "thunder.provider.model": "gemini-2.0-flash",
-  "thunder.provider.contextWindow": 1000000
+  "mitii.provider.preset": "gemini",
+  "mitii.provider.type": "gemini",
+  "mitii.provider.model": "gemini-2.0-flash",
+  "mitii.provider.contextWindow": 1000000
 }
 ```
 
@@ -69,10 +124,11 @@ Add API key in settings. Mitii uses the native Messages API with streaming and t
 
 ```json
 {
-  "thunder.provider.type": "openai-compatible",
-  "thunder.provider.model": "qwen3-coder:30b",
-  "thunder.agent.planModel": "qwen3.5:4b",
-  "thunder.agent.actModel": "qwen3-coder:30b"
+  "mitii.provider.preset": "ollama",
+  "mitii.provider.type": "openai-compatible",
+  "mitii.provider.model": "qwen3-coder:30b",
+  "mitii.agent.planModel": "qwen3.5:4b",
+  "mitii.agent.actModel": "qwen3-coder:30b"
 }
 ```
 
@@ -82,8 +138,8 @@ Faster model for read-only `spawn_research_agent` workers:
 
 ```json
 {
-  "thunder.agent.researchAgentModel": "qwen3.5:4b",
-  "thunder.agent.researchAgentBaseUrl": ""
+  "mitii.agent.researchAgentModel": "qwen3.5:4b",
+  "mitii.agent.researchAgentBaseUrl": ""
 }
 ```
 
@@ -91,10 +147,19 @@ Empty `researchAgentBaseUrl` uses the main provider URL.
 
 ## Echo provider
 
-Set `thunder.provider.type` to `echo` to test UI, approvals, indexing, and tool routing without network calls.
+Set `mitii.provider.preset` to `echo` to test UI, approvals, indexing, and tool routing without network calls. In the CLI, use the `--echo` flag.
 
 ## Privacy note
 
-Mitii does not operate a central inference server. Chat requests go **only** to the endpoint you configure. Session logs and indexes stay in `.mitii/` on your machine.
+Mitii does not operate a central inference server. Chat requests go **only** to the endpoint you configure. API keys stay in VS Code SecretStorage (or env vars for CLI). Session logs and indexes stay in `.mitii/` on your machine.
+
+## Codebase location
+
+| Concern | Package |
+|---------|--------|
+| Provider transport (HTTP, streaming, tool calling) | `@mitii/sdk` (`LlmPort` implementations) |
+| Provider config persistence | `apps/vscode` (SecretStorage) / `apps/cli` (`.mitii/config.json`) |
+| Agent engine (uses provider output) | `@mitii/v8` |
+| Indexing, checkpoints, memory (host services) | `@mitii/host` |
 
 See [Connect a Model](/getting-started/connect-model) for troubleshooting.
diff --git a/docs/implementation/recent-improvements.md b/docs/implementation/recent-improvements.md
index 9c1057e..9a4be04 100644
--- a/docs/implementation/recent-improvements.md
+++ b/docs/implementation/recent-improvements.md
@@ -1,6 +1,43 @@
 # Recent improvements
 
-This page tracks major capabilities shipped in Mitii AI Agent v2.6.x. Settings use the `thunder.*` namespace in VS Code (historical internal name); the product brand is **Mitii**.
+This page tracks major capabilities shipped in Mitii AI Agent v2.6.x. Settings use the `mitii.*` namespace in VS Code; the product brand is **Mitii**.
+
+## V8 module stack
+
+The agent core is now a modular V8 stack rather than a monolithic `packages/core`:
+
+| Module | What it does |
+|--------|-------------|
+| **Decision Policy** | Converts request evidence into an `ExecutionDecision` (route, planning, tool scope) |
+| **Agent Engine** | Orchestrates the agent loop: prompt construction, LLM calls, tool dispatch |
+| **Tool Runtime** | Executes tools with policy checks, transactions, and approval gates |
+| **Memory** | Retrieves and commits durable facts scoped to user / workspace / project |
+| **Change Impact** | Walks the repository graph to estimate blast radius of a change |
+| **Code Navigation** | Resolves definitions, references, and hover via LSP or repo graph |
+
+The SDK (`@mitii/sdk`) exposes a host-neutral API over V8, so the VS Code extension, CLI, and custom hosts share the same agent core.
+
+## Bundled skills (12 playbooks)
+
+Bundled skills install to `.mitii/skills/` on workspace scaffold. The agent selects the most relevant skill and follows its Planning → Change → Verify phases with acceptance criteria.
+
+| Skill | Focus |
+|-------|-------|
+| `planning-and-task-breakdown` | Decompose specs into atomic tasks with acceptance criteria |
+| `planning-default` | General-purpose planning fallback |
+| `using-agent-skills` | Meta-skill: how to discover and apply skills |
+| `ask-concise` | Short, direct answers without over-explaining |
+| `bugfix-localize` | Isolate root cause before proposing a fix |
+| `code-review-and-quality` | Review diffs for correctness, style, and risk |
+| `debugging-and-error-recovery` | Systematic error triage and recovery |
+| `git-workflow-and-versioning` | Atomic commits, clear history, safe branching |
+| `incremental-implementation` | Small reviewable diffs, one concern at a time |
+| `safety-always` | Safety guardrails applied to every task |
+| `security-and-hardening` | Threat modeling, input validation, hardening |
+| `spec-driven-development` | Implement from specs with explicit acceptance checks |
+| `test-driven-development` | Write tests first, then implement |
+
+Workspace skills (in `.mitii/skills/`) override bundled skills with the same ID.
 
 ## UI panels wired end-to-end
 
@@ -18,25 +55,31 @@ Open them in the chat view below pinned context. Memory and checkpoints share a
 
 Beyond generic OpenAI-compatible endpoints, Mitii now has native paths for:
 
-| Provider | Type key | Notes |
-|----------|----------|-------|
-| OpenAI-compatible | `openai-compatible` | Ollama, LM Studio, vLLM, proxies |
-| OpenAI | `openai` | `api.openai.com` defaults |
-| Anthropic | `anthropic` | Native Messages API + streaming |
-| Google Gemini | `gemini` | Native Gemini API |
-| DeepSeek | `deepseek` | OpenAI-compatible preset |
-| Cursor | `cursor` | OpenAI-compatible preset |
-| OpenAI Codex | `codex` | OpenAI-compatible preset |
-| Echo | `echo` | UI/testing stub |
+| Provider | Preset | Type | Notes |
+|----------|--------|------|-------|
+| OpenAI-compatible | `openai-compatible` | `openai-compatible` | Ollama, LM Studio, vLLM, proxies |
+| OpenAI | `openai` | `openai` | `api.openai.com` defaults |
+| Anthropic | `anthropic` | `anthropic` | Native Messages API + streaming |
+| Google Gemini | `gemini` | `gemini` | Native Gemini API |
+| DeepSeek | `deepseek` | `openai-compatible` | OpenAI-compatible preset |
+| Cursor | `cursor` | `openai-compatible` | OpenAI-compatible preset |
+| OpenAI Codex | `codex` | `openai-compatible` | OpenAI-compatible preset |
+| Echo | `echo` | `echo` | UI/testing stub |
+
+Configure in **Settings → Provider**. Select a **preset** (which sets the type, base URL, and model defaults). Use **Test connection** before saving.
+
+## Token budget & profiles
 
-Configure in **Settings → Model**. Use **Test connection** before saving.
+- **Context window** is the single knob — derived budgets (max output, tool results, system prompt) are computed from it automatically.
+- **Reset budgets to defaults** restores the derived values.
+- **Profiles** (`.mitii/profiles.json`) let you save and switch between provider + model + budget configurations without re-entering settings.
 
 ## Separate Plan vs Act models
 
 Optional overrides in **Settings → Agent**:
 
-- `thunder.agent.planModel` + `planBaseUrl` — cheaper model for planning
-- `thunder.agent.actModel` + `actBaseUrl` — stronger model for implementation
+- `mitii.agent.planModel` + `planBaseUrl` — cheaper model for planning
+- `mitii.agent.actModel` + `actBaseUrl` — stronger model for implementation
 
 Leave blank to use the main provider model for both modes.
 
@@ -53,7 +96,7 @@ Selector available in **Settings → Safety**.
 
 ## MCP remote transports
 
-MCP servers support three transports:
+MCP is **off by default** — enable with `mitii.mcp.enabled`. Servers support three transports:
 
 | Transport | Config |
 |-----------|--------|
@@ -61,11 +104,11 @@ MCP servers support three transports:
 | **sse** | `url`, `headers` (remote SSE) |
 | **streamable-http** | `url`, `headers` (MCP Streamable HTTP spec) |
 
-OAuth / bearer tokens via `headers.Authorization` or `oauth.accessToken` in server config. Edit in **Settings → Integrations**.
+OAuth / bearer tokens via `headers.Authorization` or `oauth.accessToken` in server config. Edit in **Settings → Integrations**. In **Act mode**, certain MCP tools can be excluded via MCP exclusions.
 
 ## Git-stash checkpoints
 
-Checkpoint strategy is configurable (`thunder.agent.checkpointStrategy`):
+Checkpoint strategy is configurable (`mitii.agent.checkpointStrategy`):
 
 - **`git-stash`** (default) — `git stash push` before writes when repo available
 - **`shadow-git`** — shadow stash with distinct message prefix
@@ -79,16 +122,49 @@ When a write or patch awaits approval:
 
 1. **View in editor** on the approval card opens inline decorations
 2. Run **Mitii: Accept Inline Diff** or **Mitii: Reject Inline Diff** from the command palette
-3. Optional **diff preview tabs** still available via `thunder.agent.showDiffPreview`
+3. Optional **diff preview tabs** still available via `mitii.agent.showDiffPreview`
 
 ## Browser tool (`fetch_web`)
 
 HTTP fetch for external docs and API references:
 
 - 30s timeout, 50k char cap, HTML stripped to text
-- Gated by `thunder.safety.allowNetwork` / autonomy preset
+- Gated by `mitii.safety.allowNetwork` / autonomy preset
 - Blocked in **safe** and **enterprise** presets
 
+## Bundled embedding (on-device)
+
+Semantic indexing now uses a **host-owned bundled embedding** — vectors are produced on-device without calling the chat-model provider or any external API:
+
+- No network round-trips, no API costs
+- LanceDB remains optional for vector storage (default: SQLite)
+- `minilm` (quality) or `hash` (speed) backends selectable
+- Works offline; degrades gracefully if the model is unavailable
+
+## Hardened large-repo indexing
+
+Large repositories now index with explicit **scan → index → cancel** phases:
+
+- Partial-index status — usable results while indexing continues
+- Progress detail in the VS Code UI and CLI
+- "Degraded but usable" messaging when the index is incomplete
+- Cancel support without corrupting existing index state
+
+## CLI as first-class app
+
+`@mitii/cli` is a headless CLI over `@mitii/sdk` → `@mitii/v8` (with `@mitii/host` for indexing, checkpoints, memory, and skills):
+
+```bash
+npm install -g @mitii/cli
+# or
+npx @mitii/cli
+```
+
+- `mitii setup` — interactive provider configuration
+- `--echo` flag — test without a real LLM
+- Env vars: `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `MITII_API_KEY`
+- Same agent core, same skills, same safety model as VS Code
+
 ## Workspace path migration: `.thunder/` → `.mitii/`
 
 All new workspace data uses **`.mitii/`**:
@@ -102,6 +178,7 @@ All new workspace data uses **`.mitii/`**:
 | `mcp.json` | Workspace MCP servers |
 | `skills/` | `SKILL.md` skill definitions |
 | `diff-preview/` | Temporary diff preview files |
+| `profiles.json` | Saved provider/model/budget profiles |
 
 Legacy `.thunder/` paths are still ignored for backward compatibility.
 
@@ -134,4 +211,23 @@ Now:
 3. **Plan nudges** mention `use_skill` when grounding is missing
 4. **Quality gate** expects verification-oriented success criteria on multi-step plans
 
-Bundled skills install to `.mitii/skills/` on workspace scaffold (8 playbooks including `planning-and-task-breakdown` and `using-agent-skills`).
+Bundled skills install to `.mitii/skills/` on workspace scaffold (12 playbooks including `planning-and-task-breakdown`, `safety-always`, and `test-driven-development`).
+
+## SDK host-neutral API
+
+`@mitii/sdk` provides a stable, host-neutral surface for custom integrations:
+
+```ts
+import { createMitiiClient } from "@mitii/sdk";
+
+const client = createMitiiClient({
+  llm: myLlmPort, // implement LlmPort
+  // optional: memory, checkpoints, skills adapters
+});
+
+const result = await client.run("Fix the failing test in src/auth.ts");
+```
+
+- No VS Code or Node-specific dependencies in the core path
+- `LlmPort` injection lets you plug in any provider
+- Same safety, memory, and skill system as the apps
diff --git a/docs/implementation/safety.md b/docs/implementation/safety.md
index 26c3b4a..08cb99f 100644
--- a/docs/implementation/safety.md
+++ b/docs/implementation/safety.md
@@ -1,22 +1,41 @@
 # Safety & approvals
 
-Mitii gates every risky operation through a policy engine and human approval queue.
+Mitii gates every risky operation through two cooperating layers:
+
+1. **Decision Policy** (V8's authority module) — converts request evidence into a single `ExecutionDecision` that determines the execution route, planning depth, tool grant, verification requirements, and approval mode.
+2. **Tool Runtime** (V8's enforcement layer) — validates every tool call against the `ToolGrant` and executes through host ports. It never decides whether a tool is allowed; it only enforces the grant it receives.
+
+A human approval queue sits between the two for any action that requires consent.
 
 ## Policy flow
 
 ```
-Tool call → ToolPolicyEngine → allow | require_approval | block
+Tool call → Decision Policy → ExecutionDecision → allow | require_approval | block
                 ↓
          ApprovalQueue (if required)
                 ↓
          User approves / denies
                 ↓
-         ToolExecutor.executeApproved()
+         Tool Runtime validates against ToolGrant
+                ↓
+         Execute through host ports → bounded ToolResult + audit event
 ```
 
+## What Decision Policy decides
+
+| Concern | Detail |
+|---------|--------|
+| Execution route | `execute`, `plan`, or `clarify` |
+| Planning depth | `none`, `light`, `full` |
+| Plan gate | Whether a plan must be approved before execution |
+| Tool grant | Allowed tools, effects, path scopes, command rules, network hosts, limits, mutation budget |
+| Verification | Required evidence (e.g. tests or diagnostics) before the run is considered complete |
+| Prompt-injection scan | Detects injection signals in the request and clamps authority when needed |
+| Reason codes | Structured codes (e.g. `execute_requested`, `localized_change`, `verification_required`) for audit and debugging |
+
 ## Autonomy presets
 
-Quick profiles in **Settings → Safety**:
+Quick profiles in **Settings → Modes**:
 
 | Preset | Writes | Shell | Network | Approval mode |
 |--------|--------|-------|---------|---------------|
@@ -26,11 +45,11 @@ Quick profiles in **Settings → Safety**:
 | `pilot` | Auto | Ask | On | `ask_commands` |
 | `enterprise` | Ask | Ask | **Off** | `review_all` |
 
-Setting: `thunder.safety.autonomyPreset` (default: `guided`)
+Setting: `mitii.safety.autonomyPreset` (default: `guided`)
 
 ## Approval modes
 
-Fine-grained control via `thunder.safety.approvalMode`:
+Fine-grained control via `mitii.safety.approvalMode`:
 
 | Mode | File edits | Shell commands |
 |------|------------|----------------|
@@ -42,6 +61,23 @@ Fine-grained control via `thunder.safety.approvalMode`:
 
 Dangerous commands are **always blocked** regardless of mode.
 
+## Tool grant & mutation budget
+
+Every `ExecutionDecision` carries a `ToolGrant` that the Tool Runtime enforces:
+
+| Field | Purpose |
+|-------|---------|
+| `maximumWorkspaceEffect` | Highest effect allowed (`read`, `write`, `execute`) |
+| `allowedTools` / `allowedEffects` | Which tools and side-effects are permitted |
+| `pathScopes` | Workspace paths the agent may touch |
+| `commandRules` | Allowed / blocked shell command patterns |
+| `networkHosts` | Permitted network endpoints (empty = no network) |
+| `limits` | `maxToolCalls`, `maxWallTimeMs`, `maxOutputBytes` |
+| `mutationBudget` | `maxPatchesPerCall`, `maxUniqueFilesPerCall`, `maxPatchPayloadCharacters`, `requireBatchedExecution` |
+| `approvalMode` | `on_request`, `auto`, or `never` |
+
+The mutation budget prevents a single tool call from rewriting an unbounded number of files or emitting oversized payloads.
+
 ## Blocked command patterns
 
 Examples always blocked:
@@ -51,7 +87,7 @@ Examples always blocked:
 - `git push --force`
 - `npm publish`
 
-Configurable via `thunder.safety.blockDangerousCommands`.
+Configurable via `mitii.safety.blockDangerousCommands`.
 
 ## Read-only tools (auto-allowed)
 
@@ -62,16 +98,24 @@ Exceptions:
 - `fetch_web` — requires `allowNetwork` (off in safe/enterprise)
 - `ask_question` — always requires user response
 
+## Prompt-injection defense
+
+Decision Policy scans the incoming request for prompt-injection signals. When detected, it clamps the resulting `ToolGrant` — reducing allowed effects, narrowing path scopes, or escalating the approval mode — before the Tool Runtime ever sees the call.
+
 ## Untrusted workspaces
 
 VS Code untrusted workspaces block writes and shell unless:
 
 ```json
 {
-  "thunder.safety.allowUntrustedWorkspace": true
+  "mitii.safety.allowUntrustedWorkspace": true
 }
 ```
 
+## MCP tool exclusions
+
+In **Act mode**, certain MCP tools can be excluded from execution via MCP exclusions. The master switch `mitii.mcp.enabled` is **off by default**.
+
 ## Approval UI
 
 - **Approval cards** — Approve, Approve for task, Deny
@@ -92,7 +136,7 @@ Optional VS Code diff tabs before execution:
 
 ```json
 {
-  "thunder.agent.showDiffPreview": true
+  "mitii.agent.showDiffPreview": true
 }
 ```
 
@@ -104,11 +148,32 @@ Auto-checkpoint before approved writes — see [Memory & checkpoints](/implement
 
 ## Audit trail
 
-Every approval decision logged to:
+Every tool call and approval decision produces structured audit data:
+
+- **Tool Runtime audit** — `callId`, `toolName`, `status`, `inputPreview`, `bytesProduced`, `truncated`, `redacted` (emitted per call)
+- **SQLite** — `approval_audit` table
+- **JSONL session log** — `approval_decision` events
+- **Reason codes** — structured codes on every `ExecutionDecision` for traceability
 
-- SQLite `approval_audit` table
-- JSONL session log (`approval_decision` events)
+## Verification requirements
+
+Decision Policy can require evidence before a run is considered complete:
+
+- `minimumEvidence` — e.g. `tests_or_diagnostics`
+- `allowUnavailable` — whether the run can proceed if the evidence source is unavailable
+
+This ensures the agent does not claim success without running applicable checks.
 
 ## Network access
 
-`thunder.safety.allowNetwork` controls `fetch_web`. Autonomy presets set this automatically.
+`mitii.safety.allowNetwork` controls `fetch_web`. Autonomy presets set this automatically. The `ToolGrant.networkHosts` field provides per-endpoint control when network is enabled.
+
+## Codebase location
+
+| Concern | Package |
+|---------|---------|
+| Decision Policy (authority, grants, injection scan) | `@mitii/v8` → `modules/decision-policy/` |
+| Tool Runtime (enforcement, execution, audit) | `@mitii/v8` → `engine/tool-runtime/` |
+| Approval queue & UI | `apps/vscode` (sidebar webview) |
+| Checkpoints & audit persistence | `@mitii/host` |
+| Public safety API (for custom hosts) | `@mitii/sdk` |
diff --git a/docs/implementation/tools.md b/docs/implementation/tools.md
index c2cdbc3..2893c00 100644
--- a/docs/implementation/tools.md
+++ b/docs/implementation/tools.md
@@ -1,23 +1,26 @@
 # Built-in tools
 
-Mitii exposes 20+ tools to the agent. All pass through `ToolPolicyEngine` unless noted.
+Mitii exposes 20+ tools to the agent. Every tool call passes through two layers:
+
+1. **Decision Policy** (V8's authority module) converts request evidence into an `ExecutionDecision` that scopes which tools may run.
+2. **Tool Runtime** (V8's enforcement layer) validates the call against the `ToolGrant`, executes through host ports, sanitizes output, and emits a structured audit event.
+
+The Tool Runtime never decides that a tool should be allowed — it only enforces the grant. If a call violates the grant, it is rejected before execution.
 
 ## Read tools (auto-allowed)
 
 | Tool | Description |
 |------|-------------|
 | `read_file` | Read a single file |
-| `read_files` | Read multiple files (max 12 paths) |
-| `list_files` | List directory contents |
-| `search` | FTS / ripgrep search |
-| `search_batch` | Multiple search queries |
-| `repo_map` | PageRank repo structure |
-| `retrieve_context` | Hybrid context retrieval |
-| `git_diff` | Uncommitted changes |
-| `diagnostics` | LSP errors/warnings |
+| `read_many_files` | Read multiple files in one call (per-file byte caps) |
+| `list_directory` | List directory contents |
+| `glob_files` | Find files by glob pattern (`**/*.ts`) |
+| `search_files` | Literal or regex text search across workspace |
+| `file_metadata` | Size, mtime, kind, sha256 for a path |
+| `read_diagnostics` | LSP errors/warnings (optional path filter) |
+| `read_git_status` | Git status and optional diff summary |
+| `read_package_scripts` | Read scripts from `package.json` |
 | `memory_search` | Search long-term memory |
-| `search_script_catalog` | Find workspace helper scripts |
-| `execute_workspace_script` | Run approved `.mitii` scripts |
 | `use_skill` | Invoke a `SKILL.md` skill |
 
 ## Write tools (approval gated)
@@ -25,29 +28,44 @@ Mitii exposes 20+ tools to the agent. All pass through `ToolPolicyEngine` unless
 | Tool | Description |
 |------|-------------|
 | `write_file` | Write or create a file |
-| `apply_patch` | Search/replace patch |
+| `apply_patch` | Structured oldText/newText patch (transactional) |
+| `delete_file` | Delete a single workspace file |
+| `delete_directory` | Delete a directory (recursive by default) |
+| `move_file` | Move or rename a file/directory |
 | `memory_write` | Store observation (low risk, usually auto) |
 | `save_task_state` | Persist mid-task progress |
 
-Blocked in Ask/Plan/Review modes.
+Blocked in Ask/Plan/Review modes. The Tool Runtime supports **mutation rollback** — if a write fails mid-transaction, prior state is restored.
 
 ## Shell tools
 
 | Tool | Description |
 |------|-------------|
-| `run_command` | Execute shell command in workspace |
-| `execute_workspace_script` | Run checkpoint/read/write scripts |
+| `run_readonly_command` | Read-only command (npm, pnpm, cargo, go, git status, etc.) |
+| `run_command` | Mutating command (requires write grant + approval) |
+
+Read-only commands (`grep`, `npm test`, `git diff`, etc.) may auto-allow depending on approval mode. Mutating commands require explicit approval.
+
+## Navigation & impact tools
+
+| Tool | Description |
+|------|-------------|
+| `goto_definition` | Resolve the definition of a symbol at a file/line/col |
+| `find_references` | Find references and callers for a symbol |
+| `analyze_change_impact` | Blast-radius: who depends on a file/symbol (or what it imports) |
 
-Read-only commands (`grep`, `npm test`, `git diff`, etc.) may auto-allow depending on approval mode.
+These use the language server when available, otherwise the repository graph. `analyze_change_impact` walks callers, importers, references, and package edges.
 
 ## Agent tools
 
 | Tool | Description |
 |------|-------------|
-| `spawn_research_agent` | Parallel read-only subagent |
 | `ask_question` | Clarifying question → approval card |
 | `mark_step_complete` | Advance plan step |
 | `propose_plan_mutation` | Suggest plan changes |
+| `propose_file_scope` | Declare candidate file paths before reading or editing (default Act contract) |
+
+`propose_file_scope` is promoted in the Act-mode prompt so the model scopes its file reads and edits before invoking read/write tools.
 
 ## Web tool
 
@@ -63,16 +81,19 @@ Read-only commands (`grep`, `npm test`, `git diff`, etc.) may auto-allow dependi
 
 Format: `mcp__{server}__{tool}`
 
-Registered at MCP server connect time. Same approval policy as built-in tools.
+- **Off by default** — enable with `mitii.mcp.enabled`
+- Registered at MCP server connect time
+- Pass through the same Tool Runtime enforcement as built-in tools
+- In **Act mode**, specific MCP tools can be excluded via MCP exclusions
 
 ## Tool loop limits
 
 | Setting | Default |
-|---------|---------|
-| `thunder.agent.maxSteps` | 15 |
-| `thunder.agent.autoContinue` | true |
-| `thunder.agent.maxAutoContinues` | 2 |
-| `thunder.agent.researchAgentMaxSteps` | 6 |
+|---------|--------|
+| `mitii.agent.maxSteps` | 15 |
+| `mitii.agent.autoContinue` | true |
+| `mitii.agent.maxAutoContinues` | 2 |
+| `mitii.agent.researchAgentMaxSteps` | 6 |
 
 ## Post-edit validation
 
@@ -82,6 +103,23 @@ After writes, `PostEditValidator` waits for LSP diagnostics. Agent may be blocke
 
 Drop `SKILL.md` files in `.mitii/skills/`. Agent invokes via `use_skill` with skill name and parameters.
 
+**12 bundled skills** ship with the SDK:
+
+| Skill | Purpose |
+|-------|---------|
+| `ask-concise` | Keep answers short and direct |
+| `bugfix-localize` | Isolate the minimal fix |
+| `code-review-and-quality` | Review for correctness, style, and edge cases |
+| `debugging-and-error-recovery` | Systematic debugging workflow |
+| `git-workflow-and-versioning` | Atomic commits, clear history |
+| `incremental-implementation` | Small, verifiable steps |
+| `planning-and-task-breakdown` | Decompose specs into ordered tasks |
+| `planning-default` | Default planning behavior |
+| `safety-always` | Safety-first guardrails |
+| `security-and-hardening` | OWASP-class hardening |
+| `spec-driven-development` | Build from specs, not vibes |
+| `test-driven-development` | Write tests before implementation |
+
 ## Workspace scripts
 
 Approved scripts in `.mitii/` via `execute_workspace_script`:
@@ -96,3 +134,23 @@ Auto-loaded into every session:
 - `.mitii/rules`, `.clinerules`, `.cursor/rules`, `.continue/rules`
 
 Commit these to your repo for consistent agent behavior.
+
+## Tool Runtime guarantees
+
+Every tool call, regardless of type, receives:
+
+- **Grant validation** — rejected if outside the `ToolGrant` scope
+- **Output sanitization** — secrets redacted, output truncated to bounded size
+- **Structured audit** — tool name, args hash, duration, result status logged per call
+- **Mutation rollback** — failed writes restore prior file state
+
+## Codebase location
+
+| Concern | Package |
+|---------|---------|
+| Tool definitions & registry | `@mitii/v8` (`createBuiltinToolRegistry`) |
+| Tool Runtime (enforcement, audit, rollback) | `@mitii/v8` |
+| Decision Policy (authority, grants) | `@mitii/v8` |
+| MCP server lifecycle | `@mitii/host` |
+| Approval UI & settings | `apps/vscode` |
+| Public API surface | `@mitii/sdk` |
diff --git a/docs/sdk/index.md b/docs/sdk/index.md
new file mode 100644
index 0000000..67649a8
--- /dev/null
+++ b/docs/sdk/index.md
@@ -0,0 +1,101 @@
+# Mitii SDK
+
+Host-neutral programmatic API over `@mitii/v8`. Apps and tests use this package instead of importing V8 internals directly.
+
+## Install
+
+```bash
+npm install @mitii/sdk
+```
+
+Requires **Node.js 20+**. Depends on `@mitii/v8`. License: **AGPL-3.0-or-later**.
+
+> **Note:** Legacy npm `@mitii/sdk@2.7.x` is a different API surface. For local development, consume from the workspace (`pnpm --filter @mitii/sdk`).
+
+## Quick start
+
+```ts
+import { createMitiiClient, EchoLlmPort } from '@mitii/sdk';
+import type { LlmPort } from '@mitii/v8';
+
+// Hosts inject real provider ports (AnthropicLlmPort, GeminiLlmPort,
+// OpenAiCompatibleLlmPort). Echo is for local smoke only.
+const understandingLlm: LlmPort = new EchoLlmPort();
+const runLlm = new EchoLlmPort();
+
+const client = createMitiiClient({
+  understandingLlm,
+  runLlm,
+  workspaceRoot: process.cwd(),
+  defaultMode: 'ask',
+});
+
+const run = client.start({
+  prompt: 'What is recursion?',
+  mode: 'ask',
+});
+
+for await (const event of run.events) {
+  if (event.type === 'model_delta' && event.preview) {
+    process.stdout.write(event.preview);
+  }
+}
+
+const result = await run.result;
+// result.status: completed | failed | cancelled | suspended
+```
+
+## Public surface
+
+| API | What it does |
+|---|---|
+| `createMitiiClient(options)` | Compose default V8 facades; inject `LlmPort`s (secrets stay on the port) |
+| `client.start(input)` | Validate intake-facing input → Agent Engine run handle |
+| `run.events` | Async iterable of V8 `RunEvent` |
+| `run.result` | Terminal `AgentRunResult` |
+| `run.cancel()` | Cancel in-flight model/tool work |
+| `client.resume(input)` | Resume after `clarification_required` / `approval_required` |
+| `client.publishRepositoryState(input)` | Optional; calls V8 Repository State facade |
+
+> Filesystem checkpoints, skills catalogs, search, and indexing live in **`@mitii/host`** (or your own port implementations). The SDK stays host-neutral.
+
+## Architecture
+
+```text
+apps/cli | apps/vscode | your app
+        ↓
+  @mitii/host     ← filesystem, indexing, checkpoints, memory, skills
+        ↓
+  @mitii/sdk      ← host-neutral API (this package)
+        ↓
+  @mitii/v8       ← agent engine, decision policy, tool runtime
+```
+
+**Forbidden edges:** `host → apps`, `sdk → host`, `v8 → host`.
+
+## LlmPort injection
+
+The SDK never calls a provider directly. You inject `LlmPort` implementations:
+
+| Port | Use case |
+|---|---|
+| `AnthropicLlmPort` | Claude models |
+| `GeminiLlmPort` | Gemini models |
+| `OpenAiCompatibleLlmPort` | OpenAI, DeepSeek, Ollama, LM Studio, any `/v1/chat/completions` proxy |
+| `EchoLlmPort` | Local smoke tests (no network) |
+
+Secrets (API keys, base URLs) stay on the port — the SDK and V8 never see them.
+
+## Development (monorepo)
+
+```bash
+pnpm --filter @mitii/sdk typecheck
+pnpm --filter @mitii/sdk test
+pnpm --filter @mitii/sdk build
+```
+
+## Links
+
+- Repo: [Mitii-dev/Mitii](https://github.com/Mitii-dev/Mitii)
+- Runtime: [`@mitii/v8`](https://github.com/Mitii-dev/Mitii/tree/main/packages/v8)
+- Host kit: [`@mitii/host`](https://github.com/Mitii-dev/Mitii/tree/main/packages/host)