diff --git a/.sf/wiki/glossary.md b/.sf/wiki/glossary.md
new file mode 100644
index 000000000..54f34b7e4
--- /dev/null
+++ b/.sf/wiki/glossary.md
@@ -0,0 +1,119 @@
+# Glossary
+
+*Generated: 2026-05-11 | Hand-editable — tracked in git*
+
+Project-specific terms only. General software terms not listed.
+
+---
+
+## A
+
+**ADR** — Architecture Decision Record. Promoted from `.sf/DECISIONS.md` to `docs/adr/`. Numbered `0000`, `0001`, … Immutable once accepted.
+
+**Auto-bootstrap context** — The set of files (wiki pages, spec files, CODEBASE.md) injected as initial context for an autonomous run that has no active milestone to draw context from. Built by `auto-bootstrap-context.js` and `headless-context.ts`.
+
+**Autonomous mode** — SF running the full UOK dispatch loop without human confirmation per unit. Enabled via `sf run --autonomous` or the TUI `Ctrl+Y` (YOLO flag). The controller drives planning → implementation → verification non-stop.
+
+---
+
+## B
+
+**Blast radius** — The set of systems, users, or data that a task could affect if it produces a wrong output. One of the eight run-control fields used to determine whether a task requires human confirmation.
+
+**Build mode** — The SF work mode where agent can make file changes. One of two modes (Ask/Build). Toggled via `Shift+Tab`. YOLO is a flag on top of Build, not a third mode.
+
+---
+
+## C
+
+**CODEBASE.md** — Auto-generated file map of the repo. Gitignored. Regenerated by SF on each autonomous run start. Lives at `.sf/CODEBASE.md`.
+
+**Coding agent** (`packages/coding-agent/`) — The Pi SDK package that provides tool execution, model sessions, settings, retry logic, and context management. SF wraps this to run agent units.
+
+**copy-resources** — The npm script (`npm run copy-resources`) that compiles `src/resources/extensions/sf/` TypeScript + copies prompt templates into `dist/resources/`. Required after any edit to extension source files.
+
+---
+
+## D
+
+**DB-first** — The project invariant that all structured state lives in SQLite (`node:sqlite`, `.sf/sf.db`). No file-based fallbacks for state that belongs in the DB. Never use `better-sqlite3`.
+
+---
+
+## E
+
+**Escalation policy** — Tiers of context sources the agent should consult before acting on ambiguity. Tier 1: `.sf/` files, wiki. Tier 2: `docs/adr/`, `docs/specs/`. Tier 3: source code. Defined in `system-context.js`.
+
+---
+
+## F
+
+**FTS5** — SQLite full-text search extension. Used for semantic memory search and session history search in `sf.db`. Queries use `WHERE search_index MATCH 'term OR synonym'` syntax.
+
+---
+
+## H
+
+**Headless mode** — Machine-surface entry point: `sf headless`. JSON I/O. Exit codes: 0 = success, 1 = error, 10 = plan needed, 11 = blocked, 12 = budget exhausted. Not synonymous with JSON output or autonomous mode.
+
+---
+
+## M
+
+**Milestone** — Top-level unit of planned work. Identified as `M001`, `M002`, … Stored in `sf.db`. Rendered as markdown to `.sf/milestones/M001/`. A milestone contains slices; slices contain tasks.
+
+---
+
+## N
+
+**node:sqlite** — Node.js built-in SQLite module (Node 26+). The only allowed SQLite interface in this codebase. Never import `better-sqlite3` or any native SQLite addon.
+
+---
+
+## P
+
+**PDD** — Purpose-Driven Development. The eight fields (intent, value, consumer, falsifier, risk, reversibility, blast-radius, cost/compliance) that define what a task is and how to run it safely.
+
+**Pi SDK** — The underlying agent SDK (`packages/coding-agent`, `packages/ai`, `packages/agent-core`, `packages/tui`, etc.) that SF is built on.
+
+**Promote-only rule** — Runtime agent artifacts (`.sf/milestones/`, `.sf/evals/`, locks, journals) are gitignored and never committed directly. Durable artifacts are promoted to `docs/plans/`, `docs/adr/`, `docs/specs/`.
+
+**Purpose-to-Software Compiler** — The foundational product model (ADR-0000): SF captures bounded intent, translates it into PDD fields, applies run-control policy, generates milestone/slice/task contracts, writes failing tests first, implements the smallest satisfying change, then records evidence and continues.
+
+---
+
+## R
+
+**Run-control policy** — The framework that maps confidence, risk, reversibility, blast radius, cost, compliance, and production impact to a decision on whether to proceed autonomously or ask the human. Part of PDD.
+
+---
+
+## S
+
+**sf.db** — The canonical SQLite database at `.sf/sf.db`. Contains milestones, slices, tasks, memories, schedule entries, session logs, FTS5 search indexes. The single source of truth for all structured SF state.
+
+**Slice** — A scoped, deliverable unit within a milestone. Identified as `S01`, `S02`, … Each slice maps to a coherent set of tasks. Stored in `sf.db`, rendered to `.sf/milestones/M001/S01/`.
+
+**Spec-first TDD** — The project doctrine: write a failing test (the spec) before writing implementation code. `THE TEST IS THE SPEC`. See `docs/SPEC_FIRST_TDD.md`.
+
+---
+
+## T
+
+**Task** — The smallest schedulable work unit. Identified as `T01`, `T02`, … within a slice. Stored in `sf.db`. Each task gets its own agent session context and dispatch lifecycle.
+
+**Tacit knowledge** — Project-specific conventions, patterns, and institutional knowledge stored in `.sf/KNOWLEDGE.md`. Injected into system context before every SF turn.
+
+---
+
+## U
+
+**UOK** — Unified Operation Kernel. The deterministic (non-LLM) controller that reads `sf.db`, selects the next unit, launches a fresh agent session, and records results. Lives in `src/resources/extensions/sf/auto/`.
+
+---
+
+## W
+
+**Wiki** (`.sf/wiki/`) — Human-curated + agent-generated reference pages injected into every SF system context turn. Tracked in git (not gitignored). Hand edits persist across commits and clones. Lowercase filenames (`index.md`, `architecture.md`, etc.).
+
+**YOLO** — A flag on top of Build mode that disables all safety confirmations (no git prompts, no write-gate approvals). Enabled via `Ctrl+Y` or `/mode yolo`. Not a third mode — it does not appear as a `Shift+Tab` stop.
diff --git a/.sf/wiki/subsystems.md b/.sf/wiki/subsystems.md
new file mode 100644
index 000000000..451b44bf7
--- /dev/null
+++ b/.sf/wiki/subsystems.md
@@ -0,0 +1,71 @@
+# Subsystems
+
+*Generated: 2026-05-11 | Hand-editable — tracked in git*
+
+## Core CLI
+
+| Subsystem | Path | Purpose | Tests |
+|-----------|------|---------|-------|
+| Loader / entry | `src/loader.ts` | CLI bootstrap — initialises resources, resolves extension, starts TUI or headless | `tests/smoke/` |
+| Headless driver | `src/headless.ts` | Machine-surface command (`sf headless`), JSON I/O, exit codes 0/1/10/11/12 | `tests/smoke/` |
+| Headless context | `src/headless-context.ts` | Bootstrap context loader for headless runs — wiki, spec files, auto-bootstrap | — |
+
+## SF Extension (`src/resources/extensions/sf/`)
+
+Compiled from TS → JS via `npm run copy-resources`. Edit `.ts`/`.js` source; changes only land in `dist/` after that command.
+
+| Subsystem | Path (relative to extension) | Purpose |
+|-----------|------------------------------|---------|
+| UOK main loop | `auto/loop.js` | Autonomous dispatch loop — tick, gate, recovery |
+| Dispatch | `auto/phases-dispatch.js` | Selects and launches the next unit (research/plan/implement/verify) |
+| Phases helpers | `auto/phases-helpers.js` | Shared helpers for phase state transitions |
+| Unit runner | `auto/run-unit.js` | Executes a single task plan via a fresh agent session |
+| Session state | `auto/session.js` | Runtime session DB model (active unit, locks, lease) |
+| Supervisor | `auto-supervisor.js` | Monitors agent runs, enforces turn/token budgets |
+| Recovery | `auto-recovery.js` | Handles stuck/timeout/crash recovery for units |
+| System context | `bootstrap/system-context.js` | Assembles full system prompt for every SF-managed turn |
+| Auto-bootstrap context | `auto-bootstrap-context.js` | Loads context (wiki, specs, codebase) for headless auto runs with no milestones |
+| DB tools | `bootstrap/db-tools.js` | SF's database query tools exposed to the agent |
+| Query tools | `bootstrap/query-tools.js` | Higher-level query helpers over the DB schema |
+| Memory tools | `bootstrap/memory-tools.js` | Semantic memory read/write over `sf.db` |
+| Ask gate | `bootstrap/ask-gate.js` | Intercepts agent tool calls that need human confirmation |
+| Write gate | `bootstrap/write-gate.js` | Intercepts destructive write operations for approval |
+| Exec tools | `bootstrap/exec-tools.js` | Execution tool registration (shell commands, file ops) |
+| Dynamic tools | `bootstrap/dynamic-tools.js` | Runtime tool registration based on current milestone/slice |
+| Auto-prompts | `auto-prompts.js` | Loads task-execute prompt template and fills variables |
+| Auto-model selection | `auto-model-selection.js` | Picks model for each unit based on capability/cost routing |
+| Auto-budget | `auto-budget.js` | Tracks and enforces token and turn budgets per unit |
+| Runaway guard | `auto-runaway-guard.js` | Detects infinite loop / runaway execution patterns |
+| Abandon detect | `abandon-detect.js` | Detects when an agent unit has stalled or abandoned work |
+| AI memory tools | `ai-memory-tools.js` | Agent-facing memory tools (store/recall facts) |
+| Git runtime patterns | `git-runtime-patterns.js` | Defines which `.sf/` paths are gitignored at runtime |
+| Activity log | `activity-log.js` | Appends structured activity events to `.sf/activity/` |
+| Auto-dashboard | `auto-dashboard.js` | Terminal dashboard rendering during autonomous runs |
+| Completion nudge | `auto-completion-nudge.js` | Prompts agent to finish when near budget limits |
+
+## Packages (`packages/`)
+
+| Package | Path | Purpose | Tests |
+|---------|------|---------|-------|
+| coding-agent | `packages/coding-agent/` | Agent core — tools (bash, grep, read…), models, sessions, settings, retry | `packages/coding-agent/tests/` |
+| ai | `packages/ai/` | LLM provider adapters — Anthropic, OpenAI, Google, Moonshot, etc. | `packages/ai/tests/` |
+| agent-core | `packages/agent-core/` | Shared agent abstractions, message types, streaming | — |
+| tui | `packages/tui/` | Ink-based terminal UI | — |
+| daemon | `packages/daemon/` | Background daemon process for persistent state | — |
+| rpc-client | `packages/rpc-client/` | RPC adapter — JSON-RPC / HTTP wire protocol | — |
+| native | `packages/native/` | Rust N-API bindings — grep, glob, ps, highlight, AST, diff (napi-rs) | `packages/native/tests/` |
+| google-gemini-cli-provider | `packages/google-gemini-cli-provider/` | Gemini CLI Core auth provider (alternative to API key) | — |
+
+## Key Singleton Files
+
+| File | Role |
+|------|------|
+| `.sf/sf.db` | Canonical SQLite state (milestones, slices, tasks, memories, schedule, sessions) |
+| `src/resources/extensions/sf/prompts/system.md` | System prompt template injected at every SF turn |
+| `src/resources/extensions/sf/prompts/execute-task.md` | Per-unit task plan template |
+| `.sf/PROJECT.md` | Hand-authored project identity and goals |
+| `.sf/REQUIREMENTS.md` | Current requirements register |
+| `.sf/DECISIONS.md` | Architecture decision log |
+| `.sf/KNOWLEDGE.md` | Tacit knowledge and conventions |
+| `.sf/CODEBASE.md` | Auto-generated file map (gitignored) |
+| `.sf/wiki/` | Reference wiki — tracked in git, hand-editable |