diff --git a/.cursor/rules/llm-wiki.mdc b/.cursor/rules/llm-wiki.mdc
new file mode 100644
index 0000000..fd81792
--- /dev/null
+++ b/.cursor/rules/llm-wiki.mdc
@@ -0,0 +1,18 @@
+---
+description: LLM Wiki — read loops wiki/SCHEMA.md before any wiki operation
+globs:
+  - "loops wiki/**"
+alwaysApply: false
+---
+
+# LLM Wiki
+
+This project's Obsidian vault is **`loops wiki/`** (repository folder name + space + `wiki`).
+
+Before creating, updating, or querying wiki pages, read `loops wiki/SCHEMA.md` for conventions.
+
+The vault uses `[[wikilinks]]` for internal links. Every page has YAML frontmatter.
+
+When the user says "ingest", "add to wiki", "lint wiki", or "query wiki", follow the workflows in SCHEMA.md.
+
+After significant work sessions, suggest filing key decisions and learnings into the wiki (ADRs in `decisions/`, runbooks in `guides/`).
diff --git a/WIKI.md b/WIKI.md
new file mode 100644
index 0000000..7fbadcf
--- /dev/null
+++ b/WIKI.md
@@ -0,0 +1,18 @@
+# Where is the LLM wiki?
+
+The Obsidian vault is **not** a folder named `wiki`.
+
+It lives at:
+
+**`loops wiki/`**
+
+There is a **space** between `loops` and `wiki` (project wiki naming rule: *repository folder name* + space + `wiki`).
+
+- **In Obsidian:** *Open folder as vault* → choose the `loops wiki` directory inside this repo.
+- **In Cursor / Explorer:** expand the repo root and look for **`loops wiki`** (not `wiki` alone).
+
+Start here: **`loops wiki/SCHEMA.md`**.
+
+**After `docs/` ingest:** see **`loops wiki/index.md`** → **Sources** for compiled markdown; originals remain under **`docs/`**.
+
+**Session memory:** dated breadcrumbs live in **`AI_SESSION_MEMORY.md`**; the wiki explains how that relates in **`loops wiki/memories/session-memory-in-wiki.md`**.
diff --git a/loops wiki/.obsidian/app.json b/loops wiki/.obsidian/app.json
new file mode 100644
index 0000000..49fefa6
--- /dev/null
+++ b/loops wiki/.obsidian/app.json	
@@ -0,0 +1,9 @@
+{
+  "useMarkdownLinks": false,
+  "newLinkFormat": "shortest",
+  "strictLineBreaks": true,
+  "attachmentFolderPath": "assets",
+  "showFrontmatter": true,
+  "readableLineLength": true,
+  "defaultViewMode": "preview"
+}
diff --git a/loops wiki/SCHEMA.md b/loops wiki/SCHEMA.md
new file mode 100644
index 0000000..c75d355
--- /dev/null
+++ b/loops wiki/SCHEMA.md	
@@ -0,0 +1,154 @@
+# Wiki Schema
+
+> This file tells the LLM how to maintain this wiki. Read it at the start of every session that touches wiki pages.
+
+## Project
+
+- **Name**: loops
+- **Domain**: Portable workflow playbooks for AI coding agents in **Cursor** and **Claude Code**. Node.js 18+ repo with canonical loop definitions under `loops/`, a dispatcher router, personas, emit/install adapters, and optional LanceDB semantic search. Installed globally (`~/.loops`) or per-project (`.loops/`).
+
+## Directory structure
+
+The vault folder at the project root is **`loops wiki/`** (repository folder basename `loops`, a space, then `wiki`) — not bare `wiki/`.
+
+```
+loops wiki/
+├── SCHEMA.md          ← you are here (LLM instructions)
+├── index.md           ← content catalog, organized by type
+├── log.md             ← chronological operations log
+├── sources/           ← summaries of ingested documents
+├── entities/          ← concrete things (tools, services, APIs, tables, configs)
+├── concepts/          ← patterns, principles, architectural ideas
+├── decisions/         ← architecture decision records (ADRs)
+├── guides/            ← how-tos, runbooks, procedures
+├── memories/          ← session-memory mirrors / archives
+└── assets/            ← images, diagrams, attachments
+```
+
+## Page conventions
+
+### Filenames
+
+- **Kebab-case**, lowercase: `api-rate-limiting.md`, `postgres-connection-pool.md`
+- Singular nouns for entities: `redis-cache.md` not `redis-caches.md`
+- Verb-noun for guides: `deploy-to-production.md`, `rotate-api-keys.md`
+- Decisions use numbered prefix: `0001-use-postgres-over-mysql.md`
+
+### Frontmatter
+
+Every page MUST have YAML frontmatter:
+
+```yaml
+---
+title: Human-Readable Page Title
+type: source | entity | concept | decision | guide
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [relevant, tags]
+aliases: [alternate-name, abbreviation]
+sources: ["[[source-page]]"]
+status: active | draft | superseded | archived
+---
+```
+
+### Links
+
+Use Obsidian-style wikilinks exclusively:
+
+- `[[page-name]]` for standard links
+- `[[page-name|display text]]` for aliased links
+- `[[page-name#section]]` for section links
+- Never use markdown-style `[text](url)` for internal wiki links (reserve for external URLs)
+
+### Page structure
+
+Every page follows this skeleton:
+
+```markdown
+---
+(frontmatter)
+---
+
+# Title
+
+One-paragraph summary of what this page covers.
+
+## Content sections
+(varies by page type)
+
+## Related
+- [[linked-page-1]]
+- [[linked-page-2]]
+```
+
+## Page types
+
+### Source (`sources/`)
+
+Summary of an ingested document, article, file, or conversation.
+
+- **Key points** (bulleted takeaways)
+- **Detailed notes**
+- **Entities mentioned** — `[[wikilinks]]`
+- **Concepts discussed** — `[[wikilinks]]`
+
+### Entity (`entities/`)
+
+A concrete thing: tool, service, API, library, database, config.
+
+- **What it is** / **How it's used in this project** / **Key details** / **Related**
+
+### Concept (`concepts/`)
+
+A pattern, principle, or architectural idea.
+
+- **Definition** / **Application here** / **Tradeoffs** / **Related**
+
+### Decision (`decisions/`)
+
+ADR. Filename: `NNNN-short-title.md`.
+
+- **Status** / **Context** / **Decision** / **Consequences** / **Related**
+
+### Guide (`guides/`)
+
+How-to or runbook.
+
+- **Prerequisites** / **Steps** / **Troubleshooting** / **Related**
+
+## Operations
+
+### Obsidian (human viewer)
+
+Open the folder **`loops wiki/`** as a vault (Obsidian → Open folder as vault). Graph view and backlinks work with wikilinks.
+
+### Ingest
+
+When the user provides a new source: create `sources/…`, update entities/concepts/decisions/guides, refresh `index.md`, append `log.md`.
+
+### Ingest existing docs
+
+Migrate from repo **`docs/`** in batches; synthesize; do **not** delete original `docs/` without human sign-off.
+
+### Query
+
+Read `index.md`, then relevant pages; answer with `[[wikilinks]]`; offer to file synthesis as new pages.
+
+### Lint
+
+Orphans, dead links, index drift, stale frontmatter, thin pages — report as checklist; fix with user approval.
+
+## Style rules
+
+- Clear, direct prose. Prefer concrete paths, commands, and versions.
+- Use loops terminology consistently (loop, dispatcher, persona, emit, `LOOPS_ROOT`, `self_correcting`).
+- Update `updated` in frontmatter when editing a page.
+
+## Relationship to other project files
+
+- **`docs/`**: Raw documentation; ingest into `sources/` + derived pages. Binaries stay in `docs/`.
+- **`AI_SESSION_MEMORY.md`**: Session breadcrumbs; wiki is compiled long-form knowledge. See [[session-memory-in-wiki]].
+- **`MEMORY.md`**: Rolling two-section summary; not duplicated in the vault unless archived.
+- **`AGENTS.md`**: Agent index at repo root (currently bootstrap stub — fill in as the project matures).
+- **`README.md`**: Human-facing install and catalog; ingested into [[readme-project-overview]].
+- **SimpleMem / LanceDB**: Short recall layers; wiki is structured narrative. See [[lancedb-project-knowledge]].
diff --git a/loops wiki/concepts/loop-catalog.md b/loops wiki/concepts/loop-catalog.md
new file mode 100644
index 0000000..3c1e13b
--- /dev/null
+++ b/loops wiki/concepts/loop-catalog.md	
@@ -0,0 +1,51 @@
+---
+title: Loop catalog
+type: concept
+created: 2026-07-30
+updated: 2026-07-30
+tags: [loops, catalog, workflows]
+aliases: [workflows, loop-catalog]
+status: active
+---
+
+# Loop catalog
+
+## Definition
+
+The ten **workflow playbooks** plus the **dispatcher** meta-router. Canonical sources: `loops/<name>/loop.md` + `loop.yaml` under `LOOPS_ROOT` (`~/.loops` or project `.loops/`).
+
+## Application here
+
+| Loop | Use when the user wants to… | Self-correcting |
+|------|----------------------------|-----------------|
+| `plan-and-implement` | Design and build a feature, refactor, or non-trivial change | Yes |
+| `tdd` | Drive change by tests; lock behavior with a suite | Yes |
+| `sar` | Spec → attack with personas → repair; simplest correct | Yes |
+| `adversarial-gate` | Pre-merge review on PR or branch (max 3 rounds) | Yes |
+| `reproduce-and-fix` | Bug → minimal repro → failing test → fix → prove green | Yes |
+| `migrate` | Framework or version upgrade with checklist and rollback | Yes |
+| `explain-codebase` | Onboarding map of an unfamiliar repo | No |
+| `de-ai-ify` | Polish AI-sounding code; minimal-diff cleanup | Yes |
+| `swarm` | Full beginning-to-end ship pipeline (mega-loop) | Nested |
+| `use-the-loop` | Smallest composition when intent is ambiguous | Meta |
+
+**Dispatcher** (`dispatcher/loop.md`) is not in this table — it routes *to* these loops via [[loops-dispatcher]].
+
+### Invocation
+
+- Natural language: "write tests for the parser", "review this PR", "swarm this feature".
+- Claude Code slash commands: `/loops-dispatcher`, `/loops-tdd`, etc.
+- Cursor: awareness rule + emitted `loops-*` skills.
+
+## Tradeoffs
+
+- **Catalog vs custom:** loops are editable markdown — `node adapters/emit.js` after changes.
+- **Swarm vs single loop:** swarm chains phases; higher cost, full pipeline.
+- **use-the-loop:** safety valve for ambiguity; may chain 2 smaller loops.
+
+## Related
+
+- [[loops-dispatcher]]
+- [[loop-personas]]
+- [[self-correcting-contract]]
+- [[readme-project-overview]]
diff --git a/loops wiki/concepts/loop-personas.md b/loops wiki/concepts/loop-personas.md
new file mode 100644
index 0000000..1ee30bc
--- /dev/null
+++ b/loops wiki/concepts/loop-personas.md	
@@ -0,0 +1,55 @@
+---
+title: Loop personas
+type: concept
+created: 2026-07-30
+updated: 2026-07-30
+tags: [personas, review, adversarial]
+aliases: [personas]
+status: active
+---
+
+# Loop personas
+
+## Definition
+
+**Review lenses** — short role prompts the agent adopts for a step inside a loop. Canonical files: `LOOPS_ROOT/personas/<name>.md`. Personas are **not** top-level dispatcher options.
+
+## Application here
+
+### Catalog
+
+| Persona | Lens |
+|---------|------|
+| `skeptic` | Challenge problem statement and assumptions |
+| `security-auditor` | Trust boundaries, injection, authn/z, secrets |
+| `simplicity-advocate` | Removable complexity; simplest correct shape |
+| `perf-critic` | Hot paths, algorithmic waste, scale |
+| `regression-hunter` | Breakage for callers, migrations, behavior changes |
+| `edge-case-analyst` | Boundaries, empty/null, concurrency, malformed input |
+| `a11y-advocate` | Keyboard, focus, semantics, screen readers |
+| `api-contract-guardian` | Breaking changes, versioning, schema drift |
+| `dx-critic` | Errors, docs, onboarding friction, confusing APIs |
+
+### Used by (examples)
+
+| Loop | Persona usage |
+|------|---------------|
+| `sar` | Spec as skeptic; attack rotates security/simplicity/perf; judge bias simplicity |
+| `adversarial-gate` | Rounds: security → regression → edge-case; swap others when warranted |
+| `plan-and-implement` | Spec: simplicity + dx; Judge: regression-hunter |
+| `tdd` / `reproduce-and-fix` | Red/repro personas; Prove: regression-hunter |
+| `de-ai-ify` | Scan: simplicity-advocate; verify: regression-hunter |
+| `migrate` | Inventory: regression-hunter; plan: api-contract-guardian |
+
+**Contract:** `sar` and `adversarial-gate` must **Read** the persona file before adopting that lens — do not improvise from the name alone.
+
+## Tradeoffs
+
+- **Pro:** Structured adversarial review without a separate harness.
+- **Con:** Personas are frames, not execution ground truth — Judge still needs command output for code.
+
+## Related
+
+- [[loops-dispatcher]]
+- [[loop-catalog]]
+- [[self-correcting-contract]]
diff --git a/loops wiki/concepts/self-correcting-contract.md b/loops wiki/concepts/self-correcting-contract.md
new file mode 100644
index 0000000..7e39a96
--- /dev/null
+++ b/loops wiki/concepts/self-correcting-contract.md	
@@ -0,0 +1,53 @@
+---
+title: Self-correcting contract
+type: concept
+created: 2026-07-30
+updated: 2026-07-30
+tags: [quality, builder-judge-manager, contract]
+aliases: [self-correcting, BJM]
+status: active
+---
+
+# Self-correcting contract
+
+## Definition
+
+A shared quality pattern for loops that produce shippable work. Canonical spec: `contracts/self-correcting.md`. Loops with `self_correcting: true` in `loop.yaml` adopt Builder → Judge → Manager roles with structured handoffs and **ground truth outside the Builder's reasoning**.
+
+## Application here
+
+| Role | Job | Does not |
+|------|-----|----------|
+| **Builder** | Produce deliverable; emit structured handoff | Mark task complete |
+| **Judge** | Evaluate against standard + independent ground truth | Rewrite deliverable |
+| **Manager** | Route DELIVER / REVISE / ESCALATE; own stop conditions | Improvise new quality bar mid-loop |
+
+**Loops using it (v0.1.4):** `plan-and-implement`, `tdd`, `reproduce-and-fix`, `sar`, `adversarial-gate`, `de-ai-ify`, `migrate`.
+
+**Skipped for:** typos, pure Q&A, map-only work (`explain-codebase`).
+
+### Ground truth examples
+
+| Task shape | Ground truth |
+|------------|--------------|
+| Code change | Test/lint output; diff vs task; tests not weakened |
+| Design | Written acceptance checks from spec |
+| Content polish | Brief + taxonomy; suite still green |
+| Upgrade | Checklist + verify commands + rollback ref |
+
+### Stop conditions (defaults)
+
+- `self_correcting_max_revisions: 3` — after 3rd failed Judge verdict, **ESCALATE** to user.
+- No "mostly passing" — all checklist items must PASS.
+
+## Tradeoffs
+
+- **Pro:** Separates producing from judging; prevents same-context rationalization.
+- **Pro:** Hard stop avoids infinite revise loops.
+- **Con:** More phases and tokens on non-trivial work — skip for trivial one-liners per loop guidance.
+
+## Related
+
+- [[model-classes]]
+- [[loop-catalog]]
+- [[loop-personas]]
diff --git a/loops wiki/decisions/0001-python-sidecar-lancedb-retrieval.md b/loops wiki/decisions/0001-python-sidecar-lancedb-retrieval.md
new file mode 100644
index 0000000..fbae804
--- /dev/null
+++ b/loops wiki/decisions/0001-python-sidecar-lancedb-retrieval.md	
@@ -0,0 +1,51 @@
+---
+title: Python sidecar LanceDB for retrieval
+type: decision
+created: 2026-07-30
+updated: 2026-07-30
+tags: [adr, lancedb, retrieval]
+aliases: [0001]
+status: active
+---
+
+# Python sidecar LanceDB for retrieval
+
+## Status
+
+**Accepted** — scripts, requirements, always-on rule, and gitignored index store are in the repo.
+
+## Context
+
+loops is a **Node.js** repo (emit, install-global, tests). Standard my-robot LanceDB scaffold is Python-native. Agents need semantic recall over markdown and rules without reading the entire tree each session.
+
+Options documented in [[docs-ai-retrieval]]:
+
+- **A:** Python sidecar (venv + scripts reading repo markdown only)
+- **B:** Cross-repo vault recall (ghembed)
+- **C:** Platform-native retrieval only (Honcho, etc.)
+
+## Decision
+
+Adopt **Option A — Python sidecar** for per-repo semantic search:
+
+- `scripts/search_project_knowledge_lancedb.py`
+- `scripts/index_project_knowledge_lancedb.py`
+- `scripts/project_knowledge_lancedb_common.py`
+- `requirements-lancedb.txt`
+- `.cursor/rules/project-knowledge-lancedb.mdc`
+- Index at `uncommitted/lancedb_project_knowledge/` (gitignored)
+
+Vault recall and platform memory remain valid **fallbacks** in the retrieval order but do not replace the local index on machines that run the sidecar.
+
+## Consequences
+
+- **Positive:** Consistent with apfs-database, marketing, field-herper pattern; works offline; cheap pre-task search.
+- **Positive:** Scripts do not need to run in Node runtime — read-only markdown ingestion.
+- **Negative:** Requires Python venv setup on first use; index must be rebuilt after doc edits.
+- **Operational:** `npm run verify` does not require LanceDB; indexing is agent responsibility at close-out.
+
+## Related
+
+- [[lancedb-project-knowledge]]
+- [[docs-ai-retrieval]]
+- [[documentation-in-repo]]
diff --git a/loops wiki/entities/adapters-emit-and-install-global.md b/loops wiki/entities/adapters-emit-and-install-global.md
new file mode 100644
index 0000000..40106f8
--- /dev/null
+++ b/loops wiki/entities/adapters-emit-and-install-global.md	
@@ -0,0 +1,45 @@
+---
+title: adapters emit and install-global
+type: entity
+created: 2026-07-30
+updated: 2026-07-30
+tags: [emit, install, node, adapters]
+aliases: [emit, install-global]
+status: active
+---
+
+# adapters emit and install-global
+
+## What it is
+
+Two Node.js adapters that turn canonical loop definitions into platform-specific install artifacts:
+
+- **`adapters/emit.js`** — reads `loops/<name>/loop.md` + `loop.yaml`, writes namespaced `loops-*` Cursor rules and Claude skills.
+- **`adapters/install-global.js`** — symlinks global install to `~/.loops`, `~/.cursor/skills/loops-*`, `~/.cursor/rules/loops-*`, and Claude equivalents.
+
+## How it's used in this project
+
+```bash
+node adapters/emit.js              # all loops
+node adapters/emit.js plan-and-implement   # one loop
+node adapters/emit.js --check      # CI: fail if emit would change files
+node adapters/install-global.js
+node adapters/install-global.js --uninstall
+```
+
+When this repo is cloned as **`.loops/`** inside another project, emit writes into the **parent project root** (not inside `.loops/`).
+
+## Key details
+
+- **Prefix:** all emitted skills/rules are `loops-*` to avoid collisions with other skill packs.
+- **Outputs:** `.cursor/rules/loops-<loop>.mdc`, `.claude/skills/loops-<loop>/SKILL.md` + `loop.yaml`.
+- **Awareness rules:** `INSTALL.mdc` → `.cursor/rules/loops.mdc`; `INSTALL-CLAUDE.md` → `.claude/rules/loops.md`.
+- **npm scripts:** `npm run emit`, `npm run emit:check`, `npm run install:global`, `npm test` (includes emit check).
+- **Valid `model_class` values:** `high-reasoning`, `workhorse`, `cheap-fast` (validated at emit time).
+
+## Related
+
+- [[loops-dispatcher]]
+- [[model-classes]]
+- [[global-install-and-update]]
+- [[per-project-install]]
diff --git a/loops wiki/entities/lancedb-project-knowledge.md b/loops wiki/entities/lancedb-project-knowledge.md
new file mode 100644
index 0000000..ee8927c
--- /dev/null
+++ b/loops wiki/entities/lancedb-project-knowledge.md	
@@ -0,0 +1,40 @@
+---
+title: LanceDB project knowledge search
+type: entity
+created: 2026-07-30
+updated: 2026-07-30
+tags: [lancedb, retrieval, semantic-search]
+aliases: [lancedb, project-knowledge]
+status: active
+---
+
+# LanceDB project knowledge search
+
+## What it is
+
+Local **offline semantic index** (LanceDB + sentence-transformers) over repo markdown, rules, and docs. Python sidecar scripts live in `scripts/`; index store is gitignored under `uncommitted/lancedb_project_knowledge/`.
+
+## How it's used in this project
+
+Agents search **before** blind grep when answering "where is X" or recalling decisions:
+
+```bash
+python3 -u scripts/search_project_knowledge_lancedb.py "<question>" --top-k 8
+python3 -u scripts/index_project_knowledge_lancedb.py --apply
+python3 -u scripts/index_project_knowledge_lancedb.py --apply --files AGENTS.md docs/foo.md
+```
+
+Governed by `.cursor/rules/project-knowledge-lancedb.mdc` (always applied). Optional venv: `.venv-lancedb/` + `requirements-lancedb.txt`.
+
+## Key details
+
+- **Adoption:** [[0001-python-sidecar-lancedb-retrieval]] — Option A from [[docs-ai-retrieval]].
+- **Env:** `PROJECT_KNOWLEDGE_LANCEDB_DIR` in `.env` overrides default index path.
+- **Agent duty:** re-index after editing indexed content before close-out; daily cron can rebuild overnight.
+- **Retrieval order** (with SimpleMem if present): SimpleMem → LanceDB → vault → long-term memory.
+
+## Related
+
+- [[docs-ai-retrieval]]
+- [[0001-python-sidecar-lancedb-retrieval]]
+- [[documentation-in-repo]]
diff --git a/loops wiki/entities/loops-dispatcher.md b/loops wiki/entities/loops-dispatcher.md
new file mode 100644
index 0000000..b6a59ed
--- /dev/null
+++ b/loops wiki/entities/loops-dispatcher.md	
@@ -0,0 +1,47 @@
+---
+title: loops dispatcher
+type: entity
+created: 2026-07-30
+updated: 2026-07-30
+tags: [dispatcher, routing, entry-point]
+aliases: [dispatcher]
+status: active
+---
+
+# loops dispatcher
+
+## What it is
+
+The **entry router** for loops. Canonical definition: `dispatcher/loop.md`. When a user says "use the loops" or describes a task without naming a workflow, the dispatcher classifies intent and loads exactly one loop from the catalog.
+
+## How it's used in this project
+
+- **Does not** write code, edit files, or plan — only routes.
+- Resolves `LOOPS_ROOT` from project `.loops/` or global `~/.loops`.
+- Classification stays on the **current session model**; the chosen loop owns `model_class` for its phases.
+- Output contract: `Loop picked: <name>`, `Why: <one sentence>`, then execute that loop's `loop.md`.
+
+## Key details
+
+| Signal | Routes to |
+|--------|-----------|
+| "swarm" / "full pipeline" | `swarm` |
+| "de-ai-ify" / "remove the slop" | `de-ai-ify` |
+| "build" / "implement" / "add" | `plan-and-implement` |
+| "write tests" / "TDD" | `tdd` |
+| "stress-test" / "attack" / "sar" | `sar` |
+| "review PR" / "pre-merge" | `adversarial-gate` |
+| "reproduce" / "this is broken" | `reproduce-and-fix` |
+| "upgrade" / "migrate" | `migrate` |
+| "explain codebase" | `explain-codebase` |
+| Ambiguous / "use the loops" | `use-the-loop` |
+
+**Personas** (`LOOPS_ROOT/personas/`) are review lenses inside `sar` / `adversarial-gate` — **not** dispatcher options.
+
+Emitted as `loops-dispatcher` skill/rule via [[adapters-emit-and-install-global]].
+
+## Related
+
+- [[loop-catalog]]
+- [[loop-personas]]
+- [[readme-project-overview]]
diff --git a/loops wiki/entities/model-classes.md b/loops wiki/entities/model-classes.md
new file mode 100644
index 0000000..e73b509
--- /dev/null
+++ b/loops wiki/entities/model-classes.md	
@@ -0,0 +1,41 @@
+---
+title: model classes (MODEL_CLASSES)
+type: entity
+created: 2026-07-30
+updated: 2026-07-30
+tags: [models, routing, cursor, claude]
+aliases: [MODEL_CLASSES, model-classes]
+status: active
+---
+
+# model classes (MODEL_CLASSES)
+
+## What it is
+
+Portable mapping from loop **phase intent** to **which model tier** to use. Canonical defaults: `adapters/MODEL_CLASSES.md`. Personal overrides: gitignored `adapters/MODEL_CLASSES.local.md` (copy from `.local.example.md`).
+
+## How it's used in this project
+
+Each loop's `loop.yaml` declares `model_class` per phase. After [[loops-dispatcher]] routes, the chosen loop applies class behavior:
+
+| Class | Intent |
+|-------|--------|
+| `high-reasoning` | Planning, specs, adversarial attack, deep review — prefer Task/subagent when available |
+| `workhorse` | Implementation, edits, normal execution — main session |
+| `cheap-fast` | Handoffs, summaries, commit messages — main session, terse |
+
+**Resolution order:** `MODEL_CLASSES.local.md` wins if present; else `MODEL_CLASSES.md`.
+
+## Key details
+
+- **Cursor default:** Auto for all classes unless local override or user request specifies otherwise.
+- **High-reasoning override:** dispatch via Task/subagent to a strong API-pool model when the phase needs deepest reasoning — announce spend in one line.
+- **Claude Code:** classes are **advisory** — often cannot switch mid-session; note once and continue.
+- **Dispatcher** classification may stay on current model; the **chosen loop** owns class behavior for its phases.
+- **Banned on Nous (Hermes routing):** `claude-fable-*` — see loops Hermes adapter docs when running inside that host.
+
+## Related
+
+- [[self-correcting-contract]]
+- [[loop-catalog]]
+- [[adapters-emit-and-install-global]]
diff --git a/loops wiki/entities/my-robot-companion.md b/loops wiki/entities/my-robot-companion.md
new file mode 100644
index 0000000..341b9ee
--- /dev/null
+++ b/loops wiki/entities/my-robot-companion.md	
@@ -0,0 +1,37 @@
+---
+title: my-robot (companion bootstrap)
+type: entity
+created: 2026-07-30
+updated: 2026-07-30
+tags: [my-robot, bootstrap, companion]
+aliases: [my-robot]
+status: active
+---
+
+# my-robot (companion bootstrap)
+
+## What it is
+
+Sibling repository **[noidsoup/my-robot](https://github.com/noidsoup/my-robot)** — an installer that clones a 7-layer AI-first development foundation into any repo via `bootstrap.sh` + `template/`.
+
+## How it's used in this project
+
+README positions loops as the **methodology** and my-robot as the **foundation** loops runs on:
+
+- Verify gate (`.verify.sh`)
+- Memory files (`AI_SESSION_MEMORY.md`, `MEMORY.md`)
+- Semantic search scaffold (LanceDB scripts)
+- Obsidian LLM wiki (`<repo> wiki/`)
+- Agent rules — and **symlinks loops in automatically**
+
+## Key details
+
+- **Relationship:** install my-robot into a target repo → get wiki + memory + verify + loops awareness without separate loops setup.
+- **This repo** is loops itself — it carries its own wiki (`loops wiki/`) and adopted LanceDB sidecar independently.
+- **Template source:** my-robot's `template/wiki/SCHEMA.md` informed this vault's schema conventions.
+
+## Related
+
+- [[readme-project-overview]]
+- [[documentation-in-repo]]
+- [[lancedb-project-knowledge]]
diff --git a/loops wiki/guides/documentation-in-repo.md b/loops wiki/guides/documentation-in-repo.md
new file mode 100644
index 0000000..d2886cd
--- /dev/null
+++ b/loops wiki/guides/documentation-in-repo.md	
@@ -0,0 +1,48 @@
+---
+title: Documentation in the repo vs this wiki
+type: guide
+created: 2026-07-30
+updated: 2026-07-30
+tags: [documentation, onboarding]
+status: active
+---
+
+# Documentation in the repo vs this wiki
+
+This vault (**`loops wiki/`**) holds **compiled, linked knowledge** for humans and LLMs (entities, concepts, ADRs, guides). It does not replace every markdown file at the repo root.
+
+## Canonical repo docs (live outside the vault)
+
+| Location | Role |
+|----------|------|
+| `README.md` | Human install, catalog, companion pointer — ingested as [[readme-project-overview]] |
+| `AGENTS.md` | Always-on agent index (bootstrap stub — fill in stack and invariants) |
+| `AI_SESSION_MEMORY.md` | Dated session log — AI writes at close-out; see [[session-memory-in-wiki]] |
+| `MEMORY.md` | Rolling two-section summary (current / previous session) |
+| `docs/` | Deep docs — **markdown ingested** into `sources/`; originals **not deleted** |
+| `CHANGELOG.md` | Version history (v0.1.4 self-correcting contract, model classes, emit fixes) |
+| `contracts/` | Canonical self-correcting spec — concept page [[self-correcting-contract]] |
+| `loops/<name>/loop.md` | Canonical loop definitions — catalog [[loop-catalog]] |
+| `dispatcher/loop.md` | Canonical dispatcher — entity [[loops-dispatcher]] |
+
+## Docs ingest (batch 2026-07-30)
+
+| Source | Wiki page |
+|--------|-----------|
+| `README.md` | [[readme-project-overview]] |
+| `docs/ai-retrieval.md` | [[docs-ai-retrieval]] |
+
+Non-ingested but referenced: `examples/install-in-fresh-project.md` (covered by [[per-project-install]]), `personas/README.md` (covered by [[loop-personas]]).
+
+## When to add to the wiki
+
+- Cross-cutting **decisions** → `decisions/` (e.g. [[0001-python-sidecar-lancedb-retrieval]])
+- **How-tos** that outgrow README → `guides/`
+- **Systems and tools** (emit, LanceDB, dispatcher) → `entities/`
+- **Patterns** (self-correcting, personas) → `concepts/`
+
+## Related
+
+- [[SCHEMA]]
+- [[session-memory-in-wiki]]
+- [[index]]
diff --git a/loops wiki/guides/global-install-and-update.md b/loops wiki/guides/global-install-and-update.md
new file mode 100644
index 0000000..d43a0d7
--- /dev/null
+++ b/loops wiki/guides/global-install-and-update.md	
@@ -0,0 +1,75 @@
+---
+title: Global install and update
+type: guide
+created: 2026-07-30
+updated: 2026-07-30
+tags: [install, global, onboarding]
+status: active
+---
+
+# Global install and update
+
+Install loops once for **all** Cursor and Claude Code projects on a machine.
+
+## Prerequisites
+
+- Node.js **18+**
+- Git
+- Network access to clone `https://github.com/noidsoup/loops.git`
+
+## Steps
+
+### First install
+
+```bash
+git clone https://github.com/noidsoup/loops.git ~/Code/loops
+cd ~/Code/loops
+node adapters/emit.js
+node adapters/install-global.js
+```
+
+This creates `~/.loops` (symlink to clone), emits `loops-*` skills/rules globally, and installs awareness files.
+
+### Verify
+
+Open any project in Cursor or Claude Code and say:
+
+> use the loops to add a hello world script
+
+Expect [[loops-dispatcher]] to route to `plan-and-implement` or `use-the-loop`.
+
+### Update loops
+
+```bash
+cd ~/.loops && git pull && node adapters/emit.js && node adapters/install-global.js
+```
+
+### Uninstall
+
+```bash
+cd ~/Code/loops   # or ~/.loops
+node adapters/install-global.js --uninstall
+```
+
+### Optional model override
+
+```bash
+cp adapters/MODEL_CLASSES.local.example.md adapters/MODEL_CLASSES.local.md
+```
+
+Edit locally (gitignored). See [[model-classes]].
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Agent doesn't know loops | Check `~/.cursor/rules/loops.mdc` exists; re-run install-global |
+| Stale loop behavior | `git pull` in `~/.loops`, re-emit |
+| Skill name collision | loops always prefixes `loops-*` — see [[adapters-emit-and-install-global]] |
+| Project-local `.loops/` | Per-project clone overrides global `LOOPS_ROOT` — see [[per-project-install]] |
+
+## Related
+
+- [[readme-project-overview]]
+- [[per-project-install]]
+- [[adapters-emit-and-install-global]]
diff --git a/loops wiki/guides/per-project-install.md b/loops wiki/guides/per-project-install.md
new file mode 100644
index 0000000..80ccca2
--- /dev/null
+++ b/loops wiki/guides/per-project-install.md	
@@ -0,0 +1,74 @@
+---
+title: Per-project install (.loops/)
+type: guide
+created: 2026-07-30
+updated: 2026-07-30
+tags: [install, per-project, teammates]
+status: active
+---
+
+# Per-project install (.loops/)
+
+Lock loops to a **single repo** for teammates or pin a specific loops revision — alternative to [[global-install-and-update]].
+
+## Prerequisites
+
+- Node.js 18+
+- Git remote access to `noidsoup/loops`
+- If global install exists (`~/.loops`), agent prefers **project-local** `.loops/` when present
+
+## Steps
+
+```bash
+cd your-project
+git clone https://github.com/noidsoup/loops.git .loops
+node .loops/adapters/emit.js
+mkdir -p .cursor/rules .claude/rules
+cp .loops/INSTALL.mdc .cursor/rules/loops.mdc
+cp .loops/INSTALL-CLAUDE.md .claude/rules/loops.md
+```
+
+### Resulting layout
+
+```
+your-project/
+├── .loops/                         ← canonical loops source
+├── .cursor/rules/loops-*.mdc       ← emitted Cursor rules
+├── .claude/skills/loops-*/         ← emitted Claude skills
+├── .cursor/rules/loops.mdc         ← awareness
+└── .claude/rules/loops.md
+```
+
+### Try it
+
+> use the loops to add a CLI command that prints the current time
+
+### Edit a loop
+
+```bash
+$EDITOR .loops/loops/plan-and-implement/loop.md
+node .loops/adapters/emit.js
+```
+
+### Update
+
+```bash
+cd .loops && git pull && cd ..
+node .loops/adapters/emit.js
+```
+
+Full walkthrough also in `examples/install-in-fresh-project.md` (ingested context in [[readme-project-overview]]).
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Emit wrote into `.loops/` instead of project root | Clone must be named `.loops` exactly |
+| Duplicate global + local rules | Skip awareness copy if global install suffices |
+| Teammates missing loops | Commit `.loops/` as submodule or document clone step |
+
+## Related
+
+- [[global-install-and-update]]
+- [[adapters-emit-and-install-global]]
+- [[documentation-in-repo]]
diff --git a/loops wiki/index.md b/loops wiki/index.md
new file mode 100644
index 0000000..627790a
--- /dev/null
+++ b/loops wiki/index.md	
@@ -0,0 +1,55 @@
+---
+title: Wiki Index
+type: index
+created: 2026-07-30
+updated: 2026-07-30
+---
+
+# Loops Wiki
+
+> Content catalog. The LLM reads this first when answering queries. Conventions: [[SCHEMA]].
+
+## Session memories
+
+| Page | Purpose |
+|------|---------|
+| [[session-memory-in-wiki]] | How `AI_SESSION_MEMORY.md` and `MEMORY.md` relate to the vault. |
+
+## Sources
+
+| Page | Summary | Date |
+|------|---------|------|
+| [[readme-project-overview]] | Install paths, workflow catalog, self-correcting QC, my-robot companion | 2026-07-30 |
+| [[docs-ai-retrieval]] | LanceDB sidecar vs vault recall vs platform retrieval | 2026-07-30 |
+
+## Entities
+
+| Page | What it is |
+|------|------------|
+| [[loops-dispatcher]] | Entry router: classifies intent and loads one loop. |
+| [[adapters-emit-and-install-global]] | `emit.js` + `install-global.js` — platform adapters. |
+| [[model-classes]] | `high-reasoning` / `workhorse` / `cheap-fast` model routing. |
+| [[lancedb-project-knowledge]] | Local semantic index over repo markdown and rules. |
+| [[my-robot-companion]] | Sibling repo: bootstrap foundation loops runs on. |
+
+## Concepts
+
+| Page | Summary |
+|------|---------|
+| [[self-correcting-contract]] | Builder → Judge → Manager with ground truth and hard stops. |
+| [[loop-catalog]] | All ten workflows and when to use each. |
+| [[loop-personas]] | Review lenses used inside loops (not dispatcher options). |
+
+## Decisions
+
+| # | Decision | Status |
+|---|----------|--------|
+| [[0001-python-sidecar-lancedb-retrieval]] | Python sidecar LanceDB for per-repo semantic search | Accepted |
+
+## Guides
+
+| Page | Purpose |
+|------|---------|
+| [[global-install-and-update]] | Clone, emit, install globally; update and uninstall. |
+| [[per-project-install]] | `.loops/` clone for pinned or team-shared installs. |
+| [[documentation-in-repo]] | `README`, `docs/`, memory files vs this vault. |
diff --git a/loops wiki/log.md b/loops wiki/log.md
new file mode 100644
index 0000000..ef22314
--- /dev/null
+++ b/loops wiki/log.md	
@@ -0,0 +1,28 @@
+---
+title: Wiki Log
+type: log
+created: 2026-07-30
+updated: 2026-07-30
+---
+
+# Wiki Log
+
+> Chronological record of wiki operations. Append-only.
+>
+> Format: `## [YYYY-MM-DD] verb | Subject`
+>
+> Verbs: `ingest`, `query`, `lint`, `update`, `create`, `migrate`, `session`
+>
+> Parseable: `grep "^## \[" log.md | tail -10`
+
+## [2026-07-30] create | Initial loops wiki bootstrap
+
+- Created vault at **`loops wiki/`** with SCHEMA, index, log, Obsidian config.
+- Ingested **README.md** → [[readme-project-overview]]; **docs/ai-retrieval.md** → [[docs-ai-retrieval]].
+- Derived entities: [[loops-dispatcher]], [[adapters-emit-and-install-global]], [[model-classes]], [[lancedb-project-knowledge]], [[my-robot-companion]].
+- Derived concepts: [[self-correcting-contract]], [[loop-catalog]], [[loop-personas]].
+- Derived guides: [[global-install-and-update]], [[per-project-install]], [[documentation-in-repo]].
+- ADR: [[0001-python-sidecar-lancedb-retrieval]] (LanceDB sidecar adopted; scripts + rule in repo).
+- Memories: [[session-memory-in-wiki]].
+- Added repo pointer **WIKI.md** and **`.cursor/rules/llm-wiki.mdc`**.
+- Original **`docs/`** files unchanged.
diff --git a/loops wiki/memories/session-memory-in-wiki.md b/loops wiki/memories/session-memory-in-wiki.md
new file mode 100644
index 0000000..0d39dc1
--- /dev/null
+++ b/loops wiki/memories/session-memory-in-wiki.md	
@@ -0,0 +1,41 @@
+---
+title: Session memory in the wiki
+type: guide
+created: 2026-07-30
+updated: 2026-07-30
+tags: [memory, session, continuity]
+status: active
+---
+
+# Session memory in the wiki
+
+## What lives where
+
+| Location | Role |
+|----------|------|
+| **`AI_SESSION_MEMORY.md`** (repo root) | **Dated session log** — AI appends at close-out. Format: shipped, decisions, state, blocked/next. Newest on top. |
+| **`MEMORY.md`** (repo root) | **Rolling summary** — two sections only (`Current session`, `Previous session`). Overwrite, don't append. |
+| **`loops wiki/`** | **Compiled long-form knowledge** — entities, concepts, ADRs, ingested sources. Updated when decisions stabilize or docs are ingested. |
+
+## How they relate
+
+- **Session memory** = breadcrumbs for the *next* agent turn in this repo ("what just happened").
+- **Wiki** = durable reference ("how loops works", "what we decided about retrieval").
+- Do **not** duplicate every session entry into the vault — file wiki pages when a decision or system description outgrows a single log line.
+
+## Agent close-out checklist
+
+1. Append entry to `AI_SESSION_MEMORY.md`
+2. Update `MEMORY.md` (current → previous, write new current)
+3. If docs or decisions changed: update wiki pages + `index.md` + `log.md`
+4. Re-index LanceDB if indexed files changed — [[lancedb-project-knowledge]]
+
+## Privacy
+
+No secrets, tokens, passwords, or PII in any memory file or wiki page.
+
+## Related
+
+- [[documentation-in-repo]]
+- [[SCHEMA]]
+- [[0001-python-sidecar-lancedb-retrieval]]
diff --git a/loops wiki/sources/docs-ai-retrieval.md b/loops wiki/sources/docs-ai-retrieval.md
new file mode 100644
index 0000000..5eeb70e
--- /dev/null
+++ b/loops wiki/sources/docs-ai-retrieval.md	
@@ -0,0 +1,55 @@
+---
+title: docs/ai-retrieval.md (ingested)
+type: source
+created: 2026-07-30
+updated: 2026-07-30
+tags: [retrieval, lancedb, docs]
+aliases: [ai-retrieval]
+sources: ["docs/ai-retrieval.md"]
+status: active
+---
+
+# docs/ai-retrieval.md (ingested)
+
+Compiled from **`docs/ai-retrieval.md`**. This repo is **not Python-native** at the top level, so semantic search uses a sidecar pattern rather than in-app runtime embedding.
+
+## Key points
+
+- **Option A (recommended):** Python sidecar with `scripts/*_project_knowledge_lancedb.py` + `.venv-lancedb` — matches other repos.
+- **Option B:** Cross-repo vault recall (ghembed) when centrally indexed.
+- **Option C:** Platform-native retrieval (Honcho, session search) — avoid a third index when redundant.
+- **This repo adopted Option A** — see [[0001-python-sidecar-lancedb-retrieval]] and [[lancedb-project-knowledge]].
+
+## Detailed notes
+
+### Option A — Python sidecar
+
+```bash
+python3 -m venv .venv-lancedb
+.venv-lancedb/bin/pip install -r requirements-lancedb.txt
+.venv-lancedb/bin/python -u scripts/index_project_knowledge_lancedb.py --apply
+.venv-lancedb/bin/python -u scripts/search_project_knowledge_lancedb.py "<question>"
+```
+
+Add `.venv-lancedb/` and `uncommitted/` to `.gitignore`. Index store defaults to `uncommitted/lancedb_project_knowledge/`.
+
+### Option B — vault recall
+
+If ghembed / vault recall is available, committed markdown may already be indexed centrally — query vault instead of per-repo index.
+
+### Option C — platform retrieval
+
+Prefer Hermes Honcho + session search when the agent platform already provides retrieval.
+
+## Entities mentioned
+
+- [[lancedb-project-knowledge]]
+
+## Concepts discussed
+
+- Pre-task retrieval order (SimpleMem → LanceDB → vault → long-term memory)
+
+## Related
+
+- [[0001-python-sidecar-lancedb-retrieval]]
+- [[documentation-in-repo]]
diff --git a/loops wiki/sources/readme-project-overview.md b/loops wiki/sources/readme-project-overview.md
new file mode 100644
index 0000000..0437b41
--- /dev/null
+++ b/loops wiki/sources/readme-project-overview.md	
@@ -0,0 +1,79 @@
+---
+title: README — project overview (ingested)
+type: source
+created: 2026-07-30
+updated: 2026-07-30
+tags: [readme, install, catalog]
+aliases: [readme]
+sources: ["README.md"]
+status: active
+---
+
+# README — project overview (ingested)
+
+Compiled from repo **`README.md`** (v0.1.4). Playbooks for AI coding agents in Cursor and Claude Code — say **"use the loops"** and the agent picks a workflow.
+
+## Key points
+
+- **No extra app** — install once from GitHub, then invoke from any project.
+- **Node.js 18+** required; primary commands: `node adapters/emit.js`, `node adapters/install-global.js`.
+- **Global install** recommended: clone to `~/Code/loops`, emit, install-global → `~/.loops` symlink + `loops-*` skills/rules.
+- **Ten workflows** plus dispatcher; users describe intent ("write tests for…") rather than naming loops.
+- **Self-correcting QC** — Builder → Judge → Manager on producing loops (see [[self-correcting-contract]]).
+- **Companion:** [my-robot](https://github.com/noidsoup/my-robot) bootstraps verify gate, memory, wiki, and symlinks loops (see [[my-robot-companion]]).
+
+## Detailed notes
+
+### Install (global)
+
+```bash
+git clone https://github.com/noidsoup/loops.git ~/Code/loops
+cd ~/Code/loops
+node adapters/emit.js
+node adapters/install-global.js
+```
+
+Update: `cd ~/.loops && git pull && node adapters/emit.js && node adapters/install-global.js`
+
+Uninstall: `node adapters/install-global.js --uninstall`
+
+### What to say (examples)
+
+| User says | Typical loop |
+|-----------|--------------|
+| "use the loops" | Dispatcher picks best fit |
+| "build a new auth flow" | [[loop-catalog#plan-and-implement]] |
+| "write tests for the parser" | `tdd` |
+| "stress-test this design" | `sar` |
+| "review this PR" | `adversarial-gate` |
+| "reproduce this bug" | `reproduce-and-fix` |
+| "upgrade Next to 15" | `migrate` |
+| "explain this codebase" | `explain-codebase` |
+| "remove the slop" / "de-ai-ify" | `de-ai-ify` |
+| "swarm this" | `swarm` |
+
+### Model stack
+
+Default Cursor stays on **Auto**. Optional personal override: copy `adapters/MODEL_CLASSES.local.example.md` → `MODEL_CLASSES.local.md` (gitignored). Details: [[model-classes]].
+
+### Per-project install
+
+Optional `.loops/` clone for teammates — see [[per-project-install]].
+
+## Entities mentioned
+
+- [[loops-dispatcher]]
+- [[adapters-emit-and-install-global]]
+- [[model-classes]]
+- [[my-robot-companion]]
+
+## Concepts discussed
+
+- [[loop-catalog]]
+- [[self-correcting-contract]]
+
+## Related
+
+- [[global-install-and-update]]
+- [[documentation-in-repo]]
+- [[index]]