@jeffober/thatch 0.1.5 → 0.1.8

package/docs/dev/gotchas.md

@@ -0,0 +1,99 @@
+# Gotchas
+
+Non-obvious invariants and footguns. If something behaves strangely, check
+here first. These are the things that have already cost time.
+
+## Embeddings
+
+- **Embedding spaces are discriminated by vector _dimension_, not model tag.**
+  `recall` / `findDuplicates` skip entries whose vector length differs from the
+  query. The `model` column is informational only. Switching `THATCH_MODEL`
+  makes old memories _invisible_ to search (not corrupted, not deleted — just
+  skipped) until re-saved. There is no automatic re-embedding.
+- **Embedding serialization honors `byteOffset`/`byteLength`.** transformers.js
+  can return a `Float32Array` that is a _view_ into a larger tensor buffer.
+  Serializing the whole backing buffer corrupts vectors. Always serialize the
+  view's own bytes, not the underlying buffer.
+- **BGE asymmetric search**: queries get the prefix
+  `"Represent this sentence for searching relevant passages: "`; passages get
+  no prefix. `queryEmbed` vs `passageEmbed` — don't swap them.
+
+## Search vs recall
+
+- **`search` scores; `recall` scores _and_ stamps telemetry.** `search` records
+  no usage. The prompt-aware recall nudge deliberately uses `db.search()` (not
+  `recall`) so nudges don't inflate the "used recently" signal. Only explicit
+  `thatch_memory_recall` / CLI `search` stamp `recall_count`/`last_recalled_at`.
+- **`findSimilar` excludes the slug being written** (self-exclusion on
+  overwrite), so overwriting a memory doesn't warn against itself.
+
+## Writes
+
+- **The write-time similarity warning never blocks the save.** `remember` always
+  proceeds; the warning lists >= 0.85-similar entries and asks the agent to
+  reconcile (merge or `dedup_mark_checked`). Don't add blocking logic here.
+- **`overwrite: true` clears stale dedup verdicts** for that slug. Forgetting an
+  entry clears all verdicts involving it. Both make a pair eligible for
+  re-reporting by `find_duplicates`. This is intended.
+
+## Hooks (opencode)
+
+- **`tool.execute.after` is a plugin hook, NOT a bus event.** It must stay on
+  the hook object returned by `server`. Moving it into the `event` handler
+  (where `session.created` lives) silently never fires it — the event bus has
+  no such event. This was dead for weeks because the failure was invisible.
+- **Hook failures are logged with a `[thatch]` prefix and never swallowed.** Two
+  hooks were dead for weeks before failures were made visible. If you add a
+  hook, log on failure.
+- **`chat.message` has two priority tiers**: extraction nudge first (returns
+  early), then the prompt-aware recall nudge. Don't run both in one turn.
+
+## Hooks (Claude Code / Cursor)
+
+- **`PostToolBatch`/`postToolUse` must be silent** (no stdout). The agent loop
+  must not block on a payload that should be invisible until the next prompt.
+  Only `flush-tools` prints.
+- **The recall nudge arrives at the _start_ of the next turn** in Claude
+  Code/Cursor, not the end of the current one like opencode's `chat.message`. A
+  file-backed queue bridges calls that have no shared state.
+- **Cursor uses `conversation_id`** where Claude Code uses `session_id`.
+  `buffer-tool` normalizes the former to a safe filename and tries multiple
+  field names for the tool response.
+- **`--json` flips the output shape.** `reminder --json` and `flush-tools
+  --json` emit `{ additional_context: "..." }` for Cursor; plain stdout for
+  Claude Code. The flag is baked into the installed hook command.
+
+## Sideband
+
+- **Socket path = SHA-256 of the DB path**, under `os.tmpdir()`. The MCP server
+  and hook processes compute it independently — no out-of-band coordination.
+  Changing `THATCH_DB_PATH` moves the socket; a stale socket from a crash is
+  cleaned up on connection error.
+- **Sideband failure never blocks.** Server down, stale socket, or a >2 s
+  timeout all return `null`, and `flush-tools` falls back to the static write
+  nudge. Never hard-fail the agent over a recall nudge.
+
+## Setup
+
+- **Skills are always user-scoped**, even in project-local setup. The project's
+  `.claude/settings.json` and `CLAUDE.md` stay in the repo, but skills live
+  under `$CLAUDE_CONFIG_DIR/skills/` / `~/.cursor/skills/`. Installing into the
+  worktree would mutate the user's repo.
+- **`appendBlock` leaves content alone if the markers don't parse.** If the
+  start marker is found but the end marker isn't, the whole block is skipped
+  rather than half-replaced. Fix the markers or delete the block manually.
+- **The binary path is baked into installed hook commands.** `thatch setup`
+  resolves `<bin>` from PATH (or the script's absolute path) and writes it into
+  every hook command, so hooks survive after the setup session ends.
+
+## Tests
+
+- **DB tests use real SQLite files in `mkdtempSync`, not `:memory:`.** WAL
+  behavior differs in-memory and would mask bugs. Temp dirs are removed in
+  `afterEach`.
+- **`BgeEmbeddingModel`'s real `PipelineFactory` is untested** — downloading the
+  model violates the no-network rule. Lazy-load and retry logic are tested with
+  an injected mock factory. The real model is exercised only by real use.
+- **`bun test` does not typecheck**, and `tsconfig.json` excludes `tests`. Test
+  type errors are editor-only noise unless you run `tsc` on the test files
+  directly. Keep test files type-clean anyway so the editor stays quiet.

package/docs/dev/mcp-parity.md

@@ -1,27 +1,47 @@
-# MCP Parity: OpenCode Plugin vs Claude Code
+# MCP Parity: OpenCode Plugin vs Claude Code vs Cursor
 
-Thatch supports two integration paths:
+Thatch supports three integration paths sharing one core (`src/tool-defs.ts`):
 
 1. **OpenCode plugin** — runs inside opencode's Bun runtime. Full access to
-   plugin hooks: system prompt injection, session events, tool buffering,
-   compaction context, and skill installation.
+   plugin hooks: system prompt injection, session events, in-process tool
+   buffering, compaction context, and skill installation.
 2. **Claude Code MCP server** — runs as a stdio JSON-RPC process. Tools are
    exposed via MCP `tools/list` + `tools/call`. Session behavior is driven by
-   Claude Code hooks (`SessionStart`, `UserPromptSubmit`).
+   Claude Code hooks (`SessionStart`, `PostToolBatch`, `UserPromptSubmit`).
+3. **Cursor MCP server** — same stdio MCP server as Claude Code. Session
+   behavior is driven by Cursor hooks (`sessionStart`, `postToolUse`,
+   `beforeSubmitPrompt`) in a flat `hooks.json` format.
 
-This document maps the feature parity and documents the gaps.
+This document maps the feature parity and documents the remaining gaps.
 
 ## Parity matrix
 
-| Feature | OpenCode plugin | Claude Code MCP + hooks | Parity |
-|---------|----------------|------------------------|--------|
-| **Tools** (remember, recall, list, show, forget, store_list, find_dup, mark_checked) | Plugin tool registration | MCP `tools/list` + `tools/call` | **Full** |
-| **System prompt** (store names, usage rules, when-to-write) | `experimental.chat.system.transform` — dynamic, repo name baked in at runtime | CLAUDE.md instructions — static text appended by `thatch setup`; repo name auto-detected at runtime by the MCP server | **Approximate** — CLAUDE.md is static but the MCP server resolves the repo at startup, so tool behavior is identical |
-| **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder` command; stdout becomes context for Claude | **Full** |
-| **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | **Gap** — CLAUDE.md persists through compaction, so the agent retains the usage instructions, but the dynamic "re-familiarization" nudge is lost |
-| **Extraction nudge** (buffer tool calls, inject JSON payload for fact extraction) | `tool.execute.after` buffers non-thatch tool calls; `chat.message` flushes the buffer as a synthetic text part with the JSON payload | No clean equivalent. `PostToolUse` fires per-call but can't buffer across calls. A file-based approach (write to temp, flush on `UserPromptSubmit`) was considered but rejected as fragile | **Gap** — the `thatch-fact-extractor` skill is installed but not automatically triggered. Agents can still load it manually when they notice tool interactions worth extracting |
-| **Skills** (fact-extractor, dedup-classifier) | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init | Installed to `~/.claude/skills/` by `thatch setup` | **Full** — same SKILL.md format, different directory |
-| **Store detection** (repo identity from git remote) | `worktree` parameter from opencode plugin | `CLAUDE_PROJECT_DIR` environment variable (set by Claude Code for stdio MCP servers) | **Full** |
+| Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
+|---------|----------------|------------------------|---------------------|--------|
+| **Tools** (8, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
+| **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
+| **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
+| **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
+| **Extraction nudge** (buffer tool calls, inject JSON payload) | `tool.execute.after` buffers non-thatch tool calls in-process; `chat.message` flushes the buffer as a synthetic text part | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` drains the queue and prints the nudge | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Full** (file-backed) — timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor, not at the end of the current one like opencode's `chat.message` |
+| **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
+| **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed to `$CLAUDE_CONFIG_DIR/skills/` by `thatch setup` (shared only) | Installed to `~/.cursor/skills/` by `thatch setup` (shared only) | **Full** — same SKILL.md format; the code-review coordinator is opencode-only (needs sub-agents) |
+| **Store detection** (repo identity from git remote) | `worktree` parameter from the opencode plugin | `CLAUDE_PROJECT_DIR` env (set by Claude Code for stdio MCP servers) | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` then cwd | **Full** |
+| **Hook config format** | n/a — plugin registers hooks in code | Nested: `.claude/settings.json` `{hooks:{Event:{hooks:[{type,command}]}}}` | Flat: `.cursor/hooks.json` `{version:1,hooks:{event:[{command}]}}` | n/a |
+
+## Tool name conventions
+
+The shared tool definitions in `src/tool-defs.ts` use bare names
+(`memory_remember`, `memory_recall`, ...). Each host prefixes them differently:
+
+- **opencode**: `thatch_memory_remember` — the prefix is added by the
+  `tool()` wrapper in `src/tools.ts`.
+- **Claude Code**: `mcp__thatch__memory_remember` — Claude Code auto-prefixes
+  with the server name; the MCP server exposes `memory_remember`.
+- **Cursor**: `mcp__thatch__memory_remember` — same MCP server.
+
+The CLAUDE.md / AGENTS.md instructions generated by `thatch setup` reference
+both forms — the full `mcp__thatch__*` names for the host, and bare names for
+readability.
 
 ## Why the gaps exist
 
@@ -31,56 +51,92 @@ OpenCode's `experimental.session.compacting` hook lets the plugin append text
 to the compaction output — the agent sees a "you are using thatch, here's what
 you've learned" message after compaction. Claude Code's `PostCompact` hook is
 side-effects only (logging, external state); it has no `additionalContext`
-field and no decision control. `PreCompact` can block compaction but also
-can't inject context.
+field and no decision control. Cursor has no equivalent hook.
 
-**Mitigation**: CLAUDE.md is loaded at session start and persists through
-compaction. The agent retains the usage instructions. The `SessionStart` hook
-with `source: "compact"` fires after compaction, so the recall reminder runs
-again — but `thatch reminder` currently doesn't distinguish compaction from
-other session-start sources.
+**Mitigation**: CLAUDE.md / AGENTS.md is loaded at session start and persists
+through compaction, so the agent retains the usage instructions. The
+`SessionStart` / `sessionStart` hook with `source: "compact"` fires after
+compaction in Claude Code, so the recall reminder runs again. There is no
+explicit "re-familiarization" nudge for hosts without a compaction hook.
 
-### Extraction nudge
+### Extraction nudge timing
 
 OpenCode's extraction pipeline works by:
 
 1. `tool.execute.after` buffers every non-thatch tool call into a per-session
-   array (max 20 interactions).
+   in-memory array (max 20 interactions).
 2. On the next `chat.message`, the buffer is flushed and a synthetic text part
-   carrying the JSON payload is injected into the conversation.
-3. The agent sees the nudge, loads the `thatch-fact-extractor` skill, and
-   saves durable facts via `thatch_memory_remember`.
-
-Claude Code hooks fire per-event with no cross-call state. `PostToolUse` can
-inject `additionalContext` alongside a single tool result, but there's no
-mechanism to buffer across multiple tool calls and flush them together. A
-file-based approach (write each interaction to `/tmp/thatch-<session>.jsonl`,
-flush on `UserPromptSubmit`) was considered but rejected because:
-
-- Session tracking is fragile (session IDs from hook input, cleanup on
-  `SessionEnd`).
-- The 10K character cap on `additionalContext` limits the payload size.
-- The `UserPromptSubmit` hook fires before the model processes the prompt,
-  so the nudge would arrive at the start of the next turn, not at the end of
-  the current one — a different timing than opencode's `chat.message`.
-
-**Mitigation**: The `UserPromptSubmit` hook includes a write-nudge that
-reminds the agent to save new knowledge. The `thatch-fact-extractor` skill is
-installed and can be loaded manually. The agent can also call
-`thatch_memory_remember` directly when it recognizes a durable fact, which is
-the core workflow regardless of whether the extraction nudge fires.
+   carrying the JSON payload is injected into the conversation (end of the
+   current turn).
+3. The agent sees the nudge, loads the `thatch-fact-extractor` skill, and saves
+   durable facts via `thatch_memory_remember`.
+
+Claude Code and Cursor use a **file-backed** queue (`src/extract-queue.ts`)
+because hooks fire one-shot with no cross-call state:
+
+1. `PostToolBatch` (Claude Code) / `postToolUse` (Cursor) appends each tool
+   interaction to a per-session JSONL file under `$XDG_CACHE_HOME/thatch/queue/`
+   (max 20, oldest dropped). These commands are silent — no stdout — so the
+   agent loop is not delayed.
+2. `UserPromptSubmit` / `beforeSubmitPrompt` runs `thatch flush-tools`, which
+   drains the queue and prints the JSON payload. This arrives at the **start**
+   of the next turn (before the model processes the prompt), not at the end of
+   the current one.
+
+The two paths produce the same JSON shape via `buildExtractionPayload()`, so
+the fact-extractor skill receives an identical contract regardless of host.
+
+### Recall nudge without a warm model
+
+The prompt-aware recall nudge needs the embedding model to embed the user's
+prompt text. In opencode, the model is warm in-process — the `chat.message`
+hook calls `model.queryEmbed()` directly. In Claude Code/Cursor, hooks are
+one-shot `bun` spawns that can't reach the MCP server's in-memory model.
+
+Loading the ~34 MB model on every `UserPromptSubmit` would add ~300-700 ms to
+every prompt in the critical path before the agent responds. The sideband
+socket eliminates this cost; see the next section.
+
+## Sideband socket architecture
+
+```text
+Claude Code / Cursor session
+├── MCP server (long-lived, warm model)
+│   ├── stdio JSON-RPC (tool calls)
+│   └── Unix socket sideband (embed + search for hooks)
+├── UserPromptSubmit / beforeSubmitPrompt hook → thatch flush-tools [--json]
+│   ├── drains the file-backed extraction queue (existing)
+│   ├── connects to sideband socket
+│   ├── sends prompt text
+│   ├── receives match labels + scores
+│   └── prints recall nudge or falls back to write nudge
+├── PostToolBatch → thatch buffer-batch (Claude Code)
+│   └── postToolUse → thatch buffer-tool (Cursor)
+└── SessionStart / sessionStart hook → thatch reminder [--json]
+```
+
+The socket path is derived from a SHA-256 hash of the DB path — both the MCP
+server and hook processes resolve the same DB path independently (from
+`THATCH_DB_PATH` or the default under `XDG_CONFIG_HOME`), so they arrive at the
+same socket path without out-of-band coordination. The path lives under
+`os.tmpdir()`.
+
+The protocol is newline-delimited JSON: one request per connection, one
+response. Requests are `{"method":"match","text":"...","stores":[...],
+"threshold":N,"limit":N}`. Responses are `{"ok":true,"matches":[...]}` or
+`{"ok":false,"error":"..."}`.
+
+Graceful degradation: if the socket isn't available (MCP server not running,
+old version, stale socket from a crash, or a >2 s timeout), `sidebandMatch`
+returns `null` and `flush-tools` falls back to the static write nudge. The
+recall nudge is best-effort — its absence never blocks the agent's workflow. A
+stale socket file left by a crash is cleaned up on connection error.
 
 ## Architecture implications
 
 The shared tool definitions in `src/tool-defs.ts` are the single source of
-truth for both paths. The opencode plugin wraps them in `tool()` with zod
-schemas; the MCP server wraps them in `z.object()` for validation and
-`z.toJSONSchema()` for the protocol response. Tool names differ:
-
-- **opencode**: `thatch_memory_remember` (prefixed at the wrapper level)
-- **MCP/Claude Code**: `mcp__thatch__memory_remember` (Claude Code auto-prefixes
-  with the server name; the MCP server exposes `memory_remember`)
-
-The `thatch setup` command generates CLAUDE.md instructions that reference
-both forms — the full `mcp__thatch__*` names for Claude Code, and bare names
-for readability.
+truth for all three paths. The opencode plugin wraps them in `tool()` with zod
+schemas and a `thatch_` prefix; the MCP server (used by both Claude Code and
+Cursor) wraps them in `z.object()` for validation and `z.toJSONSchema()` for
+the protocol response. See `docs/dev/setup-and-hooks.md` for the concrete
+files, hook event names, and command shapes each host writes.

package/docs/dev/setup-and-hooks.md

@@ -0,0 +1,134 @@
+# Setup and Hook Configuration
+
+How `thatch setup` wires each host, and which hook events each path relies on.
+For feature parity and gaps, see `mcp-parity.md`. This document is the concrete
+artifact reference.
+
+## OpenCode (plugin)
+
+No `setup` command — opencode loads the plugin from `opencode.json`:
+
+```jsonc
+{ "plugin": ["@jeffober/thatch"] }
+```
+
+The plugin entry (`src/index.ts`) registers these hooks in code:
+
+| Hook | Input | Output | Behavior |
+|------|-------|--------|----------|
+| `experimental.chat.system.transform` | `{}` | `{ system: string[] }` | Pushes the system prompt (store names, usage rules). |
+| `experimental.session.compacting` | `{ sessionID }` | `{ context: string[] }` | Marks the session as compacting, pushes re-familiarization context. |
+| `experimental.compaction.autocontinue` | `{ sessionID }` | `{ enabled: boolean }` | Clears the compacting flag so `chat.message` nudges resume post-compaction. |
+| `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_` tool calls into the in-memory extraction ring buffer (max 20). |
+| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending, else prompt-aware recall nudge. Skipped while the session is compacting. |
+| `event` (`session.created`) | `{ event: { type, properties: { info: { id } } } }` | — | Calls `client.session.prompt` with the reminder + hygiene heartbeat. |
+| `dispose` | — | — | Closes the DB. |
+
+Skills install to `$XDG_CONFIG_HOME/opencode/skills` at plugin init — shared
+**and** opencode-only (the coordinator needs sub-agents).
+
+## Claude Code (MCP server + hooks)
+
+`thatch setup --claude` (project-local) or `thatch setup --claude --global`.
+
+### Artifacts written (Claude Code)
+
+| Artifact | Project-local | Global (`--global`) |
+|----------|--------------|---------------------|
+| MCP config | `.mcp.json` (`mcpServers.thatch`, stdio, `["mcp"]`) | none — prints `claude mcp add --scope user thatch -- <bin> mcp` |
+| Instructions | `CLAUDE.md` (idempotent `appendBlock`) | `$CLAUDE_CONFIG_DIR/CLAUDE.md` |
+| Hooks | `.claude/settings.json` | `$CLAUDE_CONFIG_DIR/settings.json` |
+| Skills | `$CLAUDE_CONFIG_DIR/skills/` (always user-scoped) | same |
+
+`CLAUDE_CONFIG_DIR` overrides the default `~/.claude` for all user-scoped
+paths. Project-local keeps `.mcp.json`, `CLAUDE.md`, and `.claude/settings.json`
+in the repo; only skills are user-scoped.
+
+### Hook events (nested `settings.json`)
+
+```jsonc
+{
+  "hooks": {
+    "SessionStart":     { "hooks": [{ "type": "command", "command": "<bin> reminder" }] },
+    "PostToolBatch":    { "hooks": [{ "type": "command", "command": "<bin> buffer-batch" }] },
+    "UserPromptSubmit": { "hooks": [{ "type": "command", "command": "<bin> flush-tools" }] }
+  }
+}
+```
+
+| Event | Command | Output | Role |
+|-------|---------|--------|------|
+| `SessionStart` | `thatch reminder` | plain text to stdout (becomes context) | Recall instructions + hygiene heartbeat |
+| `PostToolBatch` | `thatch buffer-batch` | **silent** (no stdout) | Appends a batch of tool calls to the file-backed JSONL queue |
+| `UserPromptSubmit` | `thatch flush-tools` | nudge text to stdout | Drains queue (extraction nudge), else recall nudge via sideband, else write nudge |
+
+`PostToolBatch` is silent so the agent loop is not delayed; the buffered
+content is invisible until `UserPromptSubmit` flushes it.
+
+## Cursor (MCP server + hooks)
+
+`thatch setup --cursor` (project-local) or `thatch setup --cursor --global`.
+Cursor uses the same stdio MCP server as Claude Code; only the hooks differ.
+
+### Artifacts written (Cursor)
+
+| Artifact | Project-local | Global (`--global`) |
+|----------|--------------|---------------------|
+| MCP config | `.cursor/mcp.json` | `$CURSOR_CONFIG_DIR/mcp.json` (or `~/.cursor/mcp.json`) |
+| Instructions | `AGENTS.md` (idempotent `appendBlock`, Cursor-marked) | `$CURSOR_CONFIG_DIR/AGENTS.md` |
+| Hooks | `.cursor/hooks.json` (flat) | `$CURSOR_CONFIG_DIR/hooks.json` |
+| Skills | `$CURSOR_CONFIG_DIR/skills/` (shared only) | same |
+
+Cursor has no documented env override like `CLAUDE_CONFIG_DIR`; `CURSOR_CONFIG_DIR`
+is honored for symmetry and forward-compatibility. Cursor has no equivalent of
+`claude mcp add --scope user` — writing `~/.cursor/mcp.json` directly is enough.
+
+### Hook events (flat `hooks.json`)
+
+```jsonc
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart":         [{ "command": "<bin> reminder --json" }],
+    "postToolUse":          [{ "command": "<bin> buffer-tool" }],
+    "beforeSubmitPrompt":   [{ "command": "<bin> flush-tools --json" }]
+  }
+}
+```
+
+| Event | Command | Output | Role |
+|-------|---------|--------|------|
+| `sessionStart` | `thatch reminder --json` | `{ additional_context: "..." }` | Recall + heartbeat, JSON-wrapped for Cursor |
+| `postToolUse` | `thatch buffer-tool` | **silent** | Appends a **single** tool call to the file-backed queue |
+| `beforeSubmitPrompt` | `thatch flush-tools --json` | JSON `additional_context` | Drains queue, else recall via sideband, else write nudge |
+
+Differences from Claude Code:
+
+- **Flat format** (`{version, hooks:{event:[{command}]}}`) vs nested.
+- `postToolUse` fires **per tool** (Cursor has no `PostToolBatch`); `buffer-tool`
+  reads `conversation_id` (vs `session_id`) and normalizes it to a safe filename.
+- `--json` on `reminder` and `flush-tools` so Cursor parses the output as
+  `additional_context`.
+
+## Idempotence and drift
+
+All setup operations are idempotent:
+
+- **Instructions**: `appendBlock` searches for start/end markers and replaces
+  the block between them, so re-running setup updates drifted content without
+  clobbering surrounding text. No marker found → append.
+- **Hooks**: `replaceThatchHooks` / `replaceCursorThatchHooks` filter out any
+  hook group whose command contains `thatch`, then add the current ones. A
+  legacy `thatch echo` hook is replaced with `flush-tools`. Non-thatch hooks are
+  preserved.
+- **MCP config**: existing `mcpServers` are preserved; only the `thatch` entry
+  is set.
+- **Skills**: `installSkills` only writes when on-disk content differs from the
+  definition (drift detection). Skills are plugin-owned — local edits are
+  overwritten on the next plugin init or `thatch setup`.
+
+## Binary resolution
+
+`thatch setup` resolves `<bin>` from PATH, falling back to the absolute path of
+the running script. This is baked into every installed hook command, so the
+hooks keep working after the session that ran setup ends.

package/docs/dev/skills.md

@@ -0,0 +1,109 @@
+# Skills
+
+Thatch installs SKILL.md files that give the agent task-specific workflows. All
+skill content is defined in `src/skills.ts` and installed to a host-specific
+directory. See `mcp-parity.md` for which skills each host gets.
+
+## Skill file format
+
+Each skill is a single `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: thatch-fact-extractor
+description: Extract durable project facts ... Use when ...
+---
+
+<role and instructions>
+```
+
+- `name` must match the directory name (`<skillsDir>/<name>/SKILL.md`).
+- `description` drives when the agent loads the skill (both opencode and
+  Cursor auto-discover skills and use the description for relevance).
+
+## The 11 skills
+
+**Shared (10)** — installed everywhere; no sub-agents required:
+
+| Skill | Role |
+|-------|------|
+| `thatch-fact-extractor` | Turn buffered tool interactions into `thatch_memory_remember` calls. |
+| `thatch-dedup-classifier` | Classify and resolve `find_duplicates` pairs/clusters. |
+| `thatch-project-primer` | Investigate a new project and write foundational memories. |
+| `thatch-review-pedantic` | Mechanical correctness: spelling, naming, doc accuracy, specs, stale artifacts. |
+| `thatch-review-acceptance` | Behavioral/product review: UX, behavioral delta, integration effects. |
+| `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit FSMs, error propagation. |
+| `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
+| `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
+| `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. |
+| `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
+
+**opencode-only (1)** — the coordinator needs sub-agent support:
+
+| Skill | Role |
+|-------|------|
+| `thatch-code-review` | Resolve review target, estimate complexity, partition, dispatch the 5 specialists in parallel, synthesize. |
+
+## REVIEW_COMMON
+
+The five review specialists share a framework interpolated via `${REVIEW_COMMON}`:
+
+- **Static analysis only** — no running tests/linters/compilers.
+- **Scope gathering** — resolve the git range, `git diff --stat`, read changed
+  files in full for context.
+- **Runtime model** — CLI/long-lived server/library/batch — this determines
+  which bug classes are realistic.
+- **Reachability gate** — every finding must describe a concrete normal-usage
+  trigger; "the code allows this" is not enough.
+- **Intent verification** — trace callers, check git history, and `thatch_memory_recall`
+  for design rationale before flagging a behavior as a bug.
+- **Output format** — `[SEVERITY] [CATEGORY] file:line` with finding, evidence
+  (quoted), trigger, reachability, source of truth, producer chain, provenance.
+
+The synthesizer reuses the same verification rigor but has its own structure
+(it does not interpolate `REVIEW_COMMON`).
+
+## The two arrays
+
+```ts
+const SHARED_SKILLS: SkillDef[] = [ /* 10 skills above */ ];
+const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
+```
+
+`installSkills(skillsDir, skills?)` defaults to `SHARED_SKILLS`. The opencode
+plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`; `thatch setup --claude`
+and `--cursor` pass only the shared set.
+
+## Install mechanics
+
+- **Location**: `$XDG_CONFIG_HOME/opencode/skills` (opencode),
+  `$CLAUDE_CONFIG_DIR/skills` (Claude Code), `~/.cursor/skills` (Cursor).
+  Always user-scoped — never into the worktree.
+- **Trigger**: opencode installs at plugin init; Claude Code/Cursor install via
+  `thatch setup`.
+- **Drift detection**: `installSkills` only writes when the on-disk content
+  differs from the definition. This is how skill improvements ship with new
+  versions without users manually deleting files.
+- **Idempotent**: re-running init or setup overwrites drifted content but leaves
+  unrelated skill files alone.
+
+## Adding a skill
+
+1. Write the `SKILL.md` content as a template literal in `src/skills.ts`.
+   Interpolate `${REVIEW_COMMON}` if it's a review specialist.
+2. Add a `{ name, content }` entry to `SHARED_SKILLS` (or `OPENCODE_ONLY_SKILLS`
+   if it needs sub-agents).
+3. If the skill name appears in a tool's expected workflow (e.g. the extraction
+   nudge references `thatch-fact-extractor`), update that prompt in `src/prompts.ts`.
+4. The opencode plugin and `thatch setup` pick it up automatically on next init.
+
+## Memory review skills in practice
+
+- **Quick single lens**: load any specialist directly and point it at a branch.
+- **Full review on opencode**: load `thatch-code-review` — it dispatches all 5
+  specialists in parallel, then synthesizes.
+- **Full review on Claude Code/Cursor**: run each specialist in sequence, then
+  run `thatch-review-synthesizer` to verify and aggregate.
+
+The coordinator is the only skill that can't be used without sub-agents; that's
+why it lives in `OPENCODE_ONLY_SKILLS`.

package/docs/qa/README.md

@@ -24,8 +24,17 @@ network access and no writes outside temp directories.
 ```bash
 bun test          # all tests
 bun test --watch  # watch mode
+mise run check       # typecheck + bun test + markdownlint (the CI gate)
+mise run typecheck   # tsc alone
+mise run lint-md     # markdownlint only
 ```
 
+`mise run check` is the canonical quality gate (also run by CI on push/PR to
+`main`). Typecheck uses `tsconfig.check.json` (which includes the test files
+that the build's `tsconfig.json` excludes). Markdownlint enforces structural
+correctness on `README.md` and `docs/` excluding `docs/plans/`; see
+`.markdownlint-cli2.jsonc` for rule config.
+
 ## Test files and coverage
 
 ### `tests/db.test.ts`

package/docs/qa/use-cases/README.md

@@ -4,12 +4,28 @@ Manual end-to-end QA scenarios for thatch. Each use case has preconditions,
 steps, and expected results. These cover behavior the automated suite can't:
 real opencode sessions, the real embedding model, and the CLI.
 
+Newer use cases carry an _Automatable_ note flagging which are pure
+file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
+
 | Use case | Covers |
 |----------|--------|
 | [UC-001](UC-001-memory-roundtrip.md) | Remember/recall across sessions, store naming, duplicate rejection |
 | [UC-002](UC-002-dedup-cycle.md) | Full dedup review cycle: find, classify, resolve, mark checked |
 | [UC-003](UC-003-extraction-nudge.md) | Tool buffering → extraction nudge → agent-driven fact saving |
 | [UC-004](UC-004-cli-inspection.md) | CLI commands, arg validation, env overrides |
+| [UC-005](UC-005-setup-install.md) | `thatch setup --claude`/`--cursor`, project-local + `--global`, idempotent re-run, legacy hook migration |
+| [UC-006](UC-006-cursor-hook-lifecycle.md) | Cursor hook lifecycle: `buffer-tool` (`conversation_id`), `flush-tools --json`, queue drain |
+| [UC-007](UC-007-recall-nudge.md) | Prompt-aware recall nudge — opencode in-process + Claude/Cursor sideband paths; no telemetry |
+| [UC-008](UC-008-hygiene-heartbeat.md) | Hygiene heartbeat: stale 90d, orphaned branches, pending dedup; advisory, agent-driven |
+| [UC-009](UC-009-flush-tools-tiers.md) | `flush-tools` three-tier priority (extraction > recall > write) + sideband degradation |
+| [UC-010](UC-010-prime.md) | `thatch prime` CLI dispatch chain (opencode/Cursor/claude), child exit code |
+| [UC-011](UC-011-write-time-similarity-warning.md) | Write-time warning never blocks; merge or mark-distinct reconciliation |
+| [UC-012](UC-012-model-migration.md) | `THATCH_MODEL` change: old memories skipped (not corrupted) until re-saved |
+| [UC-013](UC-013-compaction-context.md) | Compaction context re-familiarization (opencode-only) |
+| [UC-014](UC-014-skill-install-drift.md) | Skill install: 10 shared vs 11 opencode; drift overwritten on re-setup |
+| [UC-015](UC-015-env-override-matrix.md) | `THATCH_DB_PATH`, `XDG_CONFIG_HOME`, `CLAUDE_CONFIG_DIR`, `THATCH_QUEUE_DIR`, `THATCH_RECALL_THRESHOLD`, `THATCH_MODEL` |
+| [UC-016](UC-016-concurrent-session-isolation.md) | Per-session extraction isolation (in-memory + file queue); shared stateless sideband |
+| [UC-017](UC-017-buffer-tool-vs-buffer-batch.md) | `buffer-batch` (Claude, `tool_calls[]`+`session_id`) vs `buffer-tool` (Cursor, single+`conversation_id`) |
 
 ## Template
 

package/docs/qa/use-cases/UC-005-setup-install.md

@@ -0,0 +1,34 @@
+# UC-005: Setup install (Claude Code and Cursor)
+
+**Preconditions**
+- Thatch installed and `bun` on PATH
+- Target config dirs writable (`$XDG_CONFIG_HOME`, `$CLAUDE_CONFIG_DIR`, `~/.cursor`)
+
+**Steps**
+1. From a project root: `thatch setup --claude`
+2. From the same project root: `thatch setup --cursor`
+3. Repeat both commands (re-run idempotence and drift recovery)
+4. Add a non-thatch hook to `.claude/settings.json` and `.cursor/hooks.json`,
+   then re-run setup
+5. From elsewhere: `thatch setup --cursor --global`, then `thatch setup --claude --global`
+
+**Expected**
+- `--claude` project-local writes `.mcp.json` (`mcpServers.thatch`, stdio + `["mcp"]`),
+  appends a thatch block to `CLAUDE.md` bracketed by start/end markers (replaced, not
+  duplicated, on re-run), writes `.claude/settings.json` hooks (`SessionStart` -> `thatch reminder`,
+  `PostToolBatch` -> `thatch buffer-batch`, `UserPromptSubmit` -> `thatch flush-tools`), and installs
+  **10 shared skills** (no code-review coordinator) to `$CLAUDE_CONFIG_DIR/skills/` — user-scoped
+  even in project-local mode.
+- `--cursor` project-local writes `.cursor/mcp.json`, appends to `AGENTS.md`, writes
+  `.cursor/hooks.json` in the **flat format** (`{version:1, hooks:{...}}`): `sessionStart` ->
+  `thatch reminder --json`, `postToolUse` -> `thatch buffer-tool`, `beforeSubmitPrompt` ->
+  `thatch flush-tools --json`; and installs 10 shared skills to `~/.cursor/skills/`.
+- Re-run is idempotent: instructions are not duplicated, thatch hooks are replaced (not appended),
+  and non-thatch hooks are preserved. A legacy `thatch echo` hook is replaced with `flush-tools`.
+- `--global` (Claude) writes `~/.claude/CLAUDE.md` + `~/.claude/settings.json` but **no project
+  `.mcp.json`** — it prints a `claude mcp add --scope user` command instead. `--global` (Cursor)
+  writes `~/.cursor/mcp.json`, `~/.cursor/AGENTS.md`, `~/.cursor/hooks.json`, `~/.cursor/skills/`.
+
+_Automatable: yes — file presence and shape assertions on `.mcp.json`, `hooks.json`,
+`CLAUDE.md`/`AGENTS.md` blocks, and the skills directory. `setup.test.ts` already covers the
+unit contract; this is the end-to-end runbook version._