@jeffober/thatch 0.1.44 → 0.1.46

package/README.md

@@ -51,6 +51,54 @@ thatch setup --claude --global  # or --cursor --global
 Restart your editor and thatch's tools are available as `mcp__thatch__*`.
 Requires [Bun] on PATH.
 
+The embedding model downloads once at first use. It is cached in the
+platform's per-user cache dir: `~/Library/Caches/thatch/models` on macOS (or
+`$XDG_CACHE_HOME/thatch/models` when `XDG_CACHE_HOME` is set),
+`$XDG_CACHE_HOME/thatch/models` (default `~/.cache/thatch/models`) elsewhere.
+Set `THATCH_MODEL_CACHE` to override the location. The cache survives
+upgrades and works from read-only installs.
+
+### NixOS / Nix
+
+This repo is a flake. The package bundles Bun and the native embedding
+runtime, so you need no global `npm install` and no `bun` on PATH.
+
+Try it without installing:
+
+```bash
+nix run github:sysread/thatch -- --version
+```
+
+Install options:
+
+- **NixOS module** (system-wide, all users):
+
+  ```nix
+  {
+    inputs.thatch.url = "github:sysread/thatch";
+
+    # in your NixOS system's modules:
+    imports = [ inputs.thatch.nixosModules.default ];
+    programs.thatch.enable = true;   # puts `thatch` on PATH for every user
+  }
+  ```
+
+- **Overlay**: add `nixpkgs.overlays = [ inputs.thatch.overlays.default ];`,
+  then `environment.systemPackages = [ pkgs.thatch ];`
+- **Package directly**: add `inputs.thatch.packages.${system}.default` to a
+  `home.packages` or `environment.systemPackages` list
+
+Once `thatch` is on PATH, wire it into your editor as usual:
+
+```bash
+cd /path/to/your/project
+thatch setup --claude --global   # or --cursor
+```
+
+The embedding model still downloads once at first use. Its cache lives in the
+per-user cache dir described above, outside the read-only Nix store, so it
+survives upgrades. `THATCH_MODEL_CACHE` overrides the location.
+
 ### Other MCP-compatible harnesses
 
 ```json
@@ -62,7 +110,7 @@ Requires [Bun] on PATH.
 ```
 
 Include thatch's instructions in your agent's system prompt manually; see
-[docs/dev/mcp-parity.md](docs/dev/mcp-parity.md) for the prompt text.
+[MCP parity](https://github.com/sysread/thatch/wiki/Mcp-Parity) for the prompt text.
 
 ## What's inside
 
@@ -108,13 +156,17 @@ Thatch gives your agent:
   hostile message cannot impersonate your instructions. Disable the whole
   feature with `chat.enabled: false` in the thatch config (or just the
   auto-joining with `chat.autoRegister: false`).
-- **Wrap-up commands** (opencode only) -- `/thatch/compact` and `/thatch/exit`
-  run a pre-flight checklist before a compaction or an exit: the agent flushes
-  pending fact extraction, finishes promised memory writes, and surfaces
-  todos or follow-ups it never addressed. It ends its response with a
-  greenlight token only when the checklist is clean; thatch then triggers the
-  compaction or quits opencode. With items outstanding, the agent lists them
-  and nothing fires -- you decide when to retry.
+- **Slash commands** -- `/thatch/defrag` (consolidate duplicate memories),
+  `/thatch/extract` (drain the extraction queue now), `/thatch/hygiene`
+  (tend stale and orphaned memories), and `/thatch/reflect` (persist what
+  the session learned) run on demand the same behaviors the nudges run on
+  their own schedule. Plus the opencode-only wrap-ups: `/thatch/compact` and
+  `/thatch/exit` run a pre-flight checklist before a compaction or an exit:
+  the agent flushes pending fact extraction, finishes promised memory
+  writes, and surfaces todos or follow-ups it never addressed. It ends its
+  response with a greenlight token only when the checklist is clean; thatch
+  then triggers the compaction or quits opencode. With items outstanding,
+  the agent lists them and nothing fires -- you decide when to retry.
 - **Notifications + user config** -- the agent can ping you out-of-band when a
   long-running outcome lands: a desktop banner, a spoken voice
   announcement, or both (macOS and Linux). Preferences live in a
@@ -127,10 +179,28 @@ review, review response, change and feature walkthroughs, memory verification,
 knowledge export, and writing tasks
 (PR descriptions, tickets, PR splitting).
 
-See the [user guide](docs/user/README.md) for the full tool list, CLI
+See the [user guide](https://github.com/sysread/thatch/wiki/Guide%3A-Overview) for the full tool list, CLI
 commands, configuration, environment variables, and detailed setup for each
 host.
 
+## What works in Claude Code
+
+The memory tools, prediction and behavior engines, conversation search via
+the `thatch session` CLI, cross-session chat (with stop-hook wake), skills,
+and the on-demand actions `/thatch/defrag`, `/thatch/hygiene`, and
+`/thatch/reflect` (synced by `thatch setup --claude`). Not available: the
+wrap-up commands and `/thatch/extract` (they need the opencode plugin's
+session identity and TUI control routes), live recall/prediction nudges
+beyond the hook-based flow, and toast notifications.
+
+## What works in Cursor
+
+The same core set as Claude Code (memory, predictions, behaviors, chat with
+stop-hook wake, skills, and the `defrag`/`hygiene`/`reflect` actions). Cursor
+has no file-based slash commands, so the actions surface through MCP prompts
+instead. Not available: the wrap-up commands, `/thatch/extract`, and toast
+notifications.
+
 ## Privacy
 
 Everything is local. The embedding model downloads once from Hugging Face Hub
@@ -152,16 +222,19 @@ bun install
 mise run check     # typecheck + bun test + markdownlint (the CI gate)
 ```
 
+On Nix, `nix develop` drops you into a shell with bun, mise, and node already
+on PATH -- no system install needed.
+
 Tests never reach outside the sandbox: temp-directory SQLite files, mock
 embeddings, no network.
 
 ## Docs
 
-- [User guide](docs/user/README.md) -- setup, tools, configuration, CLI
-- [Development](docs/dev/README.md) -- architecture, module responsibilities
-- [MCP parity](docs/dev/mcp-parity.md) -- OpenCode plugin vs MCP feature comparison
-- [QA tests](tests/qa/) -- executable use cases (auto/ and live/ subdirs)
-- [Design docs](docs/plans/) -- design-decision snapshots and in-progress plans
+- [User guide](https://github.com/sysread/thatch/wiki/Guide%3A-Overview) -- setup, tools, configuration, CLI
+- [Development](https://github.com/sysread/thatch/wiki/Developer-Guide) -- architecture, module responsibilities
+- [MCP parity](https://github.com/sysread/thatch/wiki/Mcp-Parity) -- OpenCode plugin vs MCP feature comparison
+- [QA tests](https://github.com/sysread/thatch/tree/main/tests/qa) -- executable use cases (auto/ and live/ subdirs)
+- [Design docs](https://github.com/sysread/thatch/tree/main/docs/plans) -- design-decision snapshots and in-progress plans
 
 ## License
 

package/bin/thatch

@@ -10,7 +10,7 @@ import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
 import { setupClaudeCode, setupCursor, registerClaudeMcpServer } from "../src/setup";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
-import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailJsonl, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, CHAT_STALE_MS, CHAT_RENUDGE_MINUTES, chatLiveness, humanAge, splitChatRoster, mcpSessionID, isoMinutesAgo, renderChatParticipant, resolveRegisteredPredecessor, type ChatSessionRow, type ChatTailFilter } from "../src/chat";
+import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailJsonl, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, CHAT_STALE_MS, CHAT_RENUDGE_MINUTES, chatLiveness, humanAge, splitChatRoster, sortChatRoster, mcpSessionID, isoMinutesAgo, renderChatParticipant, resolveRegisteredPredecessor, type ChatSessionRow, type ChatTailFilter } from "../src/chat";
 import { chatEnabled, loadConfig } from "../src/config";
 import { chatNotificationNudge } from "../src/prompts";
 import { createDebugLog } from "../src/debug";
@@ -49,8 +49,11 @@ function usage(): never {
                                    Full conversation as OpenAI chat-completions JSONL
   thatch session search <query> [--session <id>] [--regex] [--limit N]
                                    JSONL of matching parts across sessions (decoded content)
-  thatch chat list                 Registered chat sessions, grouped Active/Stale:
-                                   name, age, status, project, topic
+  thatch chat list [--stale N|all]  Registered chat sessions, grouped Active/Stale:
+                                    name, age, status, project, topic.
+                                    --stale N (days) hides stale sessions
+                                    older than N; default 1. --stale all
+                                    shows every stale session.
   thatch chat tail [--once] [--limit N|all] [--match RE]
                    [--from NAME] [--to NAME] [--since DT] [--until DT]
                                    Follow cross-session chat as a JSONL
@@ -412,14 +415,17 @@ const CHAT_ROSTER_HEADER = ["NAME", "AGE", "STATUS", "PROJECT", "TOPIC"];
  * an aligned-column table under a header row. Section headers are bold,
  * the stale explainer is muted italic; rows use green names, dim age,
  * green/red status, and a muted italic topic.
+ * staleCapMs bounds how old a stale row is displayed (null = no bound);
+ * rows past the cap collapse into a muted hidden-count note so the reader
+ * knows rows exist that the window left out.
  * Color is applied only when stdout is an interactive terminal (and
  * NO_COLOR is unset), so piped output - grep, redirect, QA runners - stays
  * clean plain text.
  */
-function formatChatRoster(sessions: ChatSessionRow[]): string {
+function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null = null): string {
   const colored = process.stdout.isTTY === true && !process.env.NO_COLOR;
   const paint = (code: string, s: string) => (colored ? `\x1b[${code}m${s}\x1b[0m` : s);
-  const { active, stale } = splitChatRoster(sessions);
+  const { active, stale, staleHidden } = splitChatRoster(sortChatRoster(sessions), Date.now(), staleCapMs);
   const renderTable = (rows: ChatSessionRow[]) => {
     const cells = (r: ChatSessionRow) => [
       r.name,
@@ -449,9 +455,21 @@ function formatChatRoster(sessions: ChatSessionRow[]): string {
   if (active.length > 0) {
     parts.push([paint("1", "# Active Sessions"), renderTable(active)].join("\n"));
   }
-  if (stale.length > 0) {
-    const explainer = `These sessions have missed their heartbeat for over ${Math.round(CHAT_STALE_MS / 1000)} seconds. Their harnesses may no longer be running (stopped, or the machine slept); mail waits until they resume.`;
-    parts.push([paint("1", "# Stale Sessions"), paint("3;90", explainer), renderTable(stale)].join("\n"));
+  if (stale.length > 0 || staleHidden > 0) {
+    const lines = [paint("1", "# Stale Sessions")];
+    if (stale.length > 0) {
+      const explainer = `These sessions have missed their heartbeat for over ${Math.round(CHAT_STALE_MS / 1000)} seconds. Their harnesses may no longer be running (stopped, or the machine slept); mail waits until they resume.`;
+      lines.push(paint("3;90", explainer), renderTable(stale));
+    }
+    if (staleHidden > 0) {
+      lines.push(
+        paint(
+          "3;90",
+          `${staleHidden} older stale session${staleHidden === 1 ? "" : "s"} hidden; --stale N widens the window to N days, --stale all shows everything.`,
+        ),
+      );
+    }
+    parts.push(lines.join("\n"));
   }
   return parts.join("\n\n");
 }
@@ -461,12 +479,26 @@ async function chatCommand(rest: string[]): Promise<void> {
 
   switch (sub) {
     case "list": {
+      // --stale N bounds how old a stale row the roster displays, in days
+      // (fractions allowed); the default of one day keeps long-dead
+      // sessions from burying the fresh signal. --stale all restores the
+      // unbounded view. A bad value dies loudly rather than silently
+      // shrinking the roster.
+      const staleArg = flagValue(restArgs, "--stale");
+      let staleCapMs: number | null = 24 * 60 * 60 * 1000;
+      if (staleArg !== undefined) {
+        if (staleArg === "all") staleCapMs = null;
+        else if (!/^\d+(\.\d+)?$/.test(staleArg) || Number(staleArg) <= 0) {
+          console.error(`error: --stale expects a positive number of days or "all", got "${staleArg}"`);
+          process.exit(1);
+        } else staleCapMs = Number(staleArg) * 24 * 60 * 60 * 1000;
+      }
       const sessions = db.listChatSessions();
       if (sessions.length === 0) {
         console.log("No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register.");
         break;
       }
-      console.log(formatChatRoster(sessions));
+      console.log(formatChatRoster(sessions, staleCapMs));
       break;
     }
 
@@ -831,6 +863,9 @@ switch (command) {
       console.log(`  Instructions:  ${result.claudeMd}`);
       console.log(`  Hooks:         ${result.settings}`);
       printSkills(result);
+      if (result.commands.length > 0) {
+        console.log(`  Commands:      ${result.commands.length} written (${result.commands.map((p) => p.split("/").pop()).join(", ")})`);
+      }
       console.log();
       if (result.mcpAddCommand) {
         // Global setup cannot write ~/.claude.json directly, so run the

package/docs/dev/README.md

@@ -24,7 +24,8 @@ Shared core
   ├── embeddings.ts   → embedding model via transformers.js
   ├── git.ts          → detect repo identity (store name)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
-  ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, CLAUDE.md instructions
+  ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, prompt cores, CLAUDE.md instructions
+  ├── commands.ts     → /thatch slash-command registry: actions from prompt cores + wrap-ups, per-host sync
   ├── sideband.ts     → Unix socket server + client: warm-model semantic match for hook processes
   ├── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
   ├── scoring-engine.ts → generic four-table scoring base (shared by prediction + behavior engines)
@@ -83,7 +84,8 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `chat.ts` | Cross-session chat between opencode sessions on one machine (opencode-only). `ChatStore` holds the shared directory and inbox in SQLite so any process can read/write them; `ChatPoller` heartbeats hosted sessions and delivers wake prompts through an injected callback when the recipient is idle - only the recipient's host process delivers, so there is no cross-process double-delivery. Heartbeat staleness flags crashed sessions; a per-recipient nudge rate cap is the anti-loop hard brake. See [features/cross-session-chat.md](features/cross-session-chat.md). |
 | `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. The pool is the fallback base for registrations with no usable session title. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
-| `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
+| `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. Also the prompt cores (`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) - host-agnostic behavior instruction bodies shared by nudges and `/thatch` commands, parameterized by a `ToolNamer` for per-host tool spellings. See [features/commands.md](features/commands.md). |
+| `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions (defrag, extract, hygiene, reflect) from the prompt cores; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
 | `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |

package/docs/dev/features/README.md

@@ -23,6 +23,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [behavior-engine.md](behavior-engine.md) | Behavior engine (LLM self-discipline rules, ham/spam, auto-fire) |
 | [hygiene.md](hygiene.md) | Hygiene system (duplicate, stale, orphaned branch signals) |
 | [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
+| [commands.md](commands.md) | Slash commands (on-demand actions from shared prompt cores, wrap-ups, host sync) |
 | [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking, wrap-up commands) |

package/docs/dev/features/cicd.md

@@ -5,7 +5,7 @@ Thatch uses GitHub Actions for CI and publishing, plus a local release helper sc
 ## CI pipeline (.github/workflows/ci.yml)
 
 Runs on every push/PR to main. Three jobs:
-1. **Typecheck** — `bunx tsc -p tsconfig.check.json` (includes test files that the build's `tsconfig.json` excludes)
+1. **Typecheck** — `bunx tsc -p tsconfig.check.json` (includes src, tests, and the CI scripts in `.github/scripts`; the build's `tsconfig.json` includes only src)
 2. **Tests** — `bun test` (bun:test framework, no network, `:memory:` DB or temp dirs)
 3. **Markdownlint** — `bunx markdownlint-cli2` on `README.md` and `docs/**/*.md` (excluding `docs/plans/**`)
 
@@ -22,6 +22,14 @@ Key details:
 - npm 12 shipped a sigstore bug that broke OIDC publishing; the pin prevents it
 - The workflow deliberately sets NO `registry-url`, which would write a token-expecting `.npmrc` that preempts the OIDC exchange
 
+## Wiki pipeline (.github/workflows/wiki.yml)
+
+Triggered by pushes to main that touch `docs/**`, the workflow file, or the render script. One-way mirror of `docs/` into the GitHub wiki: renders each doc to a flat wiki page (tiered prefixes `Guide:`, bare, `Feature:`; see `.github/scripts/sync-wiki.ts`), rewrites relative md links, generates `Home.md` + `_Sidebar.md`, wipes and rewrites all wiki pages, then pushes to `sysread/thatch.wiki.git`.
+
+- Uses the `WIKI_TOKEN` Actions secret (classic PAT, `public_repo` scope) because the built-in `GITHUB_TOKEN` cannot push to wiki repos
+- Precondition: the wiki must be initialized once via the UI (GitHub does not auto-create `.wiki.git` repos)
+- `docs/plans/` and `docs/in-progress/` are excluded; duplicate or reserved page names fail the render script
+
 ## Release helper (bin/release)
 
 A bash script (`set -euo pipefail`) that bumps, checks, commits, tags, and pushes.
@@ -45,7 +53,7 @@ Steps:
 | `test` | Run the test suite (`bun test`) |
 | `test-watch` | Run tests in watch mode |
 | `coverage` | Run tests with coverage report |
-| `typecheck` | Typecheck src + tests (`bunx tsc -p tsconfig.check.json`) |
+| `typecheck` | Typecheck src + tests + `.github/scripts` (`bunx tsc -p tsconfig.check.json`) |
 | `lint-md` | Lint markdown docs (`bunx markdownlint-cli2`) |
 | `check` | The CI gate: typecheck + tests + markdownlint |
 | `release` | Bump version, commit, tag, push (args: `patch\|minor\|major`) |
@@ -60,7 +68,7 @@ Steps:
 ## Development tooling
 
 - **Bun 1.3.14** (pinned via mise)
-- **TypeScript** with `tsconfig.check.json` for typecheck (includes test files; build's `tsconfig.json` excludes them)
+- **TypeScript** with `tsconfig.check.json` for typecheck (includes src, tests, and `.github/scripts`; build's `tsconfig.json` includes only src)
 - **bun:test** framework (no network, `:memory:` DB or temp dirs, mock embeddings)
 - **markdownlint-cli2** with custom config (`.markdownlint-cli2.jsonc`): disables MD013 (line length), MD032 (blanks around lists), MD036 (emphasis as heading), MD060 (table alignment). Keeps MD040 (code-block language), MD047 (trailing newline), heading hierarchy.
 - **Zod** for tool schema validation and JSON Schema generation (`src/tool-defs.ts`)
@@ -74,10 +82,11 @@ Steps:
 
 - `.github/workflows/ci.yml` — CI pipeline
 - `.github/workflows/publish.yml` — publish pipeline (OIDC)
+- `.github/workflows/wiki.yml` + `.github/scripts/sync-wiki.ts` — wiki mirror pipeline
 - `bin/release` — release helper script
 - `mise.toml` — task definitions, tool pins, env vars
 - `.markdownlint-cli2.jsonc` — markdownlint config
-- `tsconfig.check.json` — typecheck config (includes tests)
+- `tsconfig.check.json` — typecheck config (includes src, tests, `.github/scripts`)
 
 ## Key invariants
 
@@ -86,4 +95,4 @@ Steps:
 - npm is pinned to 11.x. npm 12 shipped a sigstore bug that broke OIDC publishing.
 - The release helper checks for tagged-but-not-published state (tag exists, npm returns E404) and refuses to proceed with recovery instructions.
 - CI runs on push/PR to main. Publish runs only on `v*` tags. The release helper bridges them: tag + push triggers publish.
-- `tsconfig.check.json` includes test files for typecheck. The build's `tsconfig.json` excludes them.
+- `tsconfig.check.json` includes src, tests, and `.github/scripts` for typecheck. The build's `tsconfig.json` includes only src.

package/docs/dev/features/commands.md

@@ -0,0 +1,74 @@
+# Slash commands: actions and wrap-ups
+
+Thatch's `/thatch/*` commands come in two families:
+
+- **Actions** (`defrag`, `extract`, `hygiene`, `reflect`) — user-invoked
+  wrappers around behaviors the nudges otherwise run on their own schedule.
+- **Wrap-ups** (`compact`, `exit`) — greenlight-gated pre-compaction and
+  pre-exit checklists. opencode only: the greenlight check needs the
+  plugin's `command.execute.before` arming and TUI control routes.
+
+User-facing guide: [../../user/commands.md](../../user/commands.md).
+
+## Prompt cores
+
+Action bodies are **prompt cores**: constants in `src/prompts.ts`
+(`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) that hold the
+host-agnostic instruction text for one behavior. The nudge envelopes wrap
+the same cores with escalation tiers and the stop-and-wait ending; command
+and prompt renderers wrap them with frontmatter and a user-message section.
+The point is drift-proofing: a wording change lands in the nudge and the
+command at once, and a test asserts each rendered file contains its core
+verbatim.
+
+The stop-and-wait ending ("do not advance pending work on this nudge's
+account") is nudge-only by design. A `/thatch` command IS user input, so
+the command envelope must not inherit it.
+
+Cores that name memory tools take a `ToolNamer` because spellings differ
+per host: `thatch_find_duplicates` on opencode, `mcp__thatch__find_duplicates`
+on MCP hosts. Each host's renderer passes its own namer
+(`opencodeToolName` / `mcpToolName`).
+
+## Rendering and sync
+
+`src/commands.ts` is the single registry:
+
+- `actionDefs(tool)` returns the action set with bodies rendered for one
+  host. Actions needing plugin-only capabilities are marked `opencodeOnly`
+  (`extract`: needs session identity via `get_session_info`).
+- `opencodeCommandDefs()` = wrap-up templates + all actions. Synced by the
+  plugin at init into `$XDG_CONFIG_HOME/opencode/command/thatch/`
+  (`installOpencodeCommands`), content-compare, self-healing.
+- `claudeCommandDefs()` = actions minus `opencodeOnly`. Synced by
+  `thatch setup --claude` (`installClaudeCommands`) into
+  `<claudeDir>/commands/thatch/`, reported in the setup output. There is no
+  plugin on this host to sync on load, so setup is the sync point.
+- MCP prompts: `compilePrompts()` in `src/mcp.ts` exposes the same
+  non-opencodeOnly actions through `prompts/list` / `prompts/get`, which
+  Cursor surfaces as slash commands. The optional `focus` argument is
+  appended to the body as a `Focus:` line, standing in for the file
+  commands' `$ARGUMENTS`.
+
+A parity-guard test asserts the three sets are the same actions minus the
+documented exclusions: opencode = Claude Code set + `compact`, `exit`,
+`extract`; MCP prompts = Claude Code's set.
+
+## The extract action and session IDs
+
+`/thatch/extract` runs the extraction flow on demand: learn the session ID
+from `thatch_get_session_info`, dispatch the extractor sub-agent with an
+explicit `session_id`, acknowledge with `thatch_extraction_done`. The
+explicit ID matters because the sub-agent's session differs from the
+parent's — the same reason the extraction nudge passes it.
+
+`get_extraction_payload` accepts an omitted `session_id`: on the opencode
+path the wrapper supplies the invoking session's `HostToolContext.sessionID`.
+The zod arg shape is shared between hosts, so optionality cannot be
+per-host at the schema level; on MCP hosts (no session context) an omitted
+`session_id` returns a clear "pass the parent's session_id" error. The rule
+the model applies, stated in the arg descriptions and the dev docs:
+
+> Omit `session_id` when acting on the session you are running in. Pass the
+> parent session's `session_id` when running inside a sub-agent dispatched
+> to process another session's extraction queue.

package/docs/dev/features/cross-session-chat.md

@@ -58,10 +58,13 @@ outlives a process, so liveness needs a signal beyond process lifetime.
 
 ### Registration and identity
 
-Sessions are auto-registered by the plugin: the first `session.status`
-idle event for a top-level session inserts its directory row, and a
-session continued via `-s <id>` registers at harness start (below);
-both paths are skipped when `chat.autoRegister: false` or when the
+Sessions are auto-registered by the plugin: a top-level session's first
+real user message inserts its directory row (the `chat.message` hook,
+which fires before the model runs - so the session is addressable within
+its very first turn), and the first `session.status` idle event remains a
+backstop that also converges the topic once the auto-titler lands. A
+session continued via `-s <id>` or `-c` registers at harness start
+(below). All paths are skipped when `chat.autoRegister: false` or when the
 session left explicitly (a leave tombstone, see below). Names are assigned, never
 claimed: a pool draw (`CHAT_NAME_POOL`, src/chat-names.ts) plus a
 per-base counter row (`chat_name_counters`, src/db.ts) that only ever
@@ -94,9 +97,14 @@ args=` on macOS) and parses `-s`/`--session` from that.
 Registration is keyed by session id: the row already exists, so the name
 is RECLAIMED (names are owned by the session id, minted once, never
 renamed) and the row's heartbeat is refreshed - hosting is the
-heartbeat, so the serving harness beats and delivers for the row again. `-c/--continue` resolves no id on the
-command line; that
-session registers on its first idle like any other. Asleep-mail: the
+heartbeat, so the serving harness beats and delivers for the row again.
+`-c/--continue` resolves no id on the command line, so the plugin
+resolves the same target the harness does: `client.session.list()`
+(directory-scoped, the plugin's client carries the directory), sorted by
+`time.updated` descending like the TUI does, first row without a
+`parentID`. That registration is not synchronous at init (the list call
+is a server round trip), but it lands within a beat of startup - the
+heartbeat is live long before the first prompt. Asleep-mail: the
 startup path kicks a delivery pass when it finishes, so the continued
 session learns what it missed at startup instead of waiting out the
 first poll cycle.
@@ -118,8 +126,8 @@ publishing `app.exit`, so the roster stops advertising a host that is
 about to vanish; the exit template's checklist step asks the model to do
 the same earlier) - writes a
 `chat_leave_tombstones` row in the same transaction that deletes the
-directory row. The tombstone is what makes a leave stick: both
-registration paths consult it (the plugin's idle auto-registerer is
+directory row. The tombstone is what makes a leave stick: all
+registration paths consult it (the plugin's idle and prompt auto-registerers are
 suppressed outright; the MCP hook's ensure-register prints the leave line
 instead of rejoining), so a leave cannot be silently undone by the next
 idle moment. The gate lives in `ChatStore.register` via `#tombstoneGate`
@@ -187,7 +195,13 @@ and the broadcast skip all call it, so they cannot disagree. `chat_list`
 groups the result into Active and Stale sections - the stale section's
 explainer says what stale means - and `chat_send` states the recipient's
 liveness at send time, so a sender mailing a ghost learns it immediately
-instead of waiting on a wake that will never fire.
+instead of waiting on a wake that will never fire. Both roster surfaces
+order rows with `sortChatRoster` (also src/chat.ts): project first,
+alphabetical, with no-project rows last; most recently seen first within
+a project. The CLI roster bounds
+the stale display to one day by default (`--stale N` in days, `--stale all`
+unbounded), collapsing older rows into a hidden-count note; the tool
+surface stays unbounded so an agent always sees the full directory.
 `session.deleted` is the graceful-exit fast path that unregisters immediately.
 
 ### Delivery, re-nudge, and the rate cap

package/docs/dev/features/extraction.md

@@ -197,6 +197,11 @@ continues working while the child extracts.
 - **opencode**: peeks accepted + pending interactions, builds JSON via
   `buildExtractionPayload`
 - **MCP**: peeks the file-backed queue, builds the same JSON payload
+- `session_id` is optional: omitted, it resolves to the invoking session
+  via `HostToolContext.sessionID` (opencode path). On MCP hosts there is no
+  session context, so an omitted `session_id` returns a "pass the parent
+  session's session_id" error. Explicit IDs always win - that is how a
+  sub-agent drains the parent's queue
 - Returns `null` when no interactions are queued
 - Read-only — it peeks the queue; it does not consume it. Consumption is
   `extraction_done`'s job

package/docs/dev/gotchas.md

@@ -146,6 +146,14 @@ here first. These are the things that have already cost time.
 - **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.
+- **Tool-arg optionality cannot be per-host at the schema level.** The zod
+  arg shape in `TOOL_DEFS` is shared by the opencode plugin and the MCP
+  server, so making an arg optional (e.g. `get_extraction_payload`'s
+  `session_id`) makes it optional everywhere. Per-host enforcement has to
+  happen in the tool's `execute`: fall back to `HostToolContext.sessionID`
+  on the opencode path, return a "pass the parent's session_id" error on
+  MCP hosts, which have no session context. See
+  [features/commands.md](features/commands.md).
 
 ## Tests
 

package/docs/dev/mcp-parity.md

@@ -23,6 +23,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **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 |
 | **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into a TUI action (`session.compact` via `executeCommand`, `app.exit` via `publish`) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and TUI control routes |
+| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
 | **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
 | **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
 | **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 |

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

@@ -50,10 +50,12 @@ the TUI is not connected (headless mode).
 | Instructions | `CLAUDE.md` (idempotent `appendBlock`) | `$CLAUDE_CONFIG_DIR/CLAUDE.md` |
 | Hooks | `.claude/settings.json` | `$CLAUDE_CONFIG_DIR/settings.json` |
 | Skills | `.claude/skills/` (in the repo) | `$CLAUDE_CONFIG_DIR/skills/` |
+| Commands | `.claude/commands/thatch/` (in the repo) | `$CLAUDE_CONFIG_DIR/commands/thatch/` |
 
 `CLAUDE_CONFIG_DIR` overrides the default `~/.claude` for all user-scoped
 paths. Project-local keeps everything in the repo: `.mcp.json`, `CLAUDE.md`,
-`.claude/settings.json`, and `.claude/skills/` (so skills version with the
+`.claude/settings.json`, `.claude/skills/`, and `.claude/commands/thatch/`
+(so skills and commands version with the
 project and every contributor gets them).
 
 ### Hook events (nested `settings.json`)