@jeffober/thatch 0.1.40 → 0.1.41

package/docs/dev/features/cli.md

@@ -1,11 +1,9 @@
 # CLI (bin/thatch)
 
-The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, MCP server startup, hook commands for MCP hosts, and the setup installer.
+The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, MCP server startup, hook commands for MCP hosts, the setup installer, session archaeology over the opencode database, and a read-only window on the cross-session chat directory.
 
 ## Subcommands
 
-15 subcommands:
-
 | Command | Args | Flags | Stdin | Purpose |
 |---------|------|-------|-------|---------|
 | `stores` | none | none | none | List all store names |
@@ -22,6 +20,9 @@ The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, M
 | `flush-tools [--json]` | none | `--json` | JSON | Peek queue + extraction/recall/prediction/behavior/write nudge |
 | `flush-predictions [--json]` | none | `--json` | JSON | Standalone prediction-only nudge |
 | `setup --claude [--cursor] [--global]` | none | `--claude`, `--cursor`, `--global` | none | Install config + instructions + hooks + skills |
+| `session list/get/transcript/search` | per subcommand | `-s/--session`, `--id`, `--after`, `--before`, `--regex`, `--limit` | none | Read-only archaeology on the opencode session database (JSONL output) |
+| `chat list` | none | none | none | Registered chat sessions: name, human-readable age, project, topic |
+| `chat tail [--once]` | none | `--once` | none | Follow cross-session chat: sent and read events (`--once` prints the backlog and exits) |
 | (unknown) | none | none | none | Print usage, exit 1 |
 
 ## Global behavior
@@ -41,6 +42,21 @@ Runs the thatch-project-primer skill via an external CLI. Searches `PATH` in ord
 
 Inherits stdio, exits with the child's exit code. Errors and exits 1 if none found.
 
+## chat
+
+Read-only window on the cross-session chat directory ([cross-session-chat.md](cross-session-chat.md)):
+
+- `chat list` renders the roster: display name, human-readable age since the
+  last heartbeat, project, and topic when set.
+- `chat tail [--once]` follows the message stream. Sent lines have the shape
+  `[timestamp] from -> to: body` (broadcast rows render `broadcast` via the
+  `via_broadcast` marker); in follow mode, an inbox drain emits a read line
+  (`[timestamp] ${reader} read a message from ${sender}: preview` — the
+  reader is the recipient draining its inbox). The diff logic is
+  `chatTailDiff()`/`formatChatTailEvent()` in `src/chat.ts`, unit-tested
+  there; `--once` prints one snapshot and exits, because a snapshot has no
+  previous state to diff read events against.
+
 ## Environment variables
 
 | Variable | Purpose | Default |
@@ -59,7 +75,7 @@ Inherits stdio, exits with the child's exit code. Errors and exits 1 if none fou
 
 ## Source files
 
-- `bin/thatch` — the CLI (Bun script, 486 lines)
+- `bin/thatch` — the CLI (Bun script)
 - `bin/release` — release helper (bash, separate from the main CLI)
 
 ## Interactions with other features
@@ -70,6 +86,8 @@ Inherits stdio, exits with the child's exit code. Errors and exits 1 if none fou
 - Extraction ([extraction.md](extraction.md)): `buffer-batch`, `buffer-tool`, `flush-tools` subcommands
 - Hygiene ([hygiene.md](hygiene.md)): `hygiene`, `reminder` subcommands
 - Multi-host ([multi-host.md](multi-host.md)): `mcp` subcommand starts the MCP server for Claude Code and Cursor
+- Session archaeology: the `session` subcommand group (see the table above) reads the opencode session database via `src/session-db.ts`
+- Cross-session chat ([cross-session-chat.md](cross-session-chat.md)): the `chat` subcommand group reads the shared chat directory and inbox
 
 ## Key invariants
 

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

@@ -0,0 +1,256 @@
+# Cross-Session Chat
+
+Cross-session chat lets independent opencode sessions on one machine message
+each other through thatch: a session registers in a shared directory, other
+sessions see it in the list, and messages land in its inbox. An idle
+recipient is woken with a prompt when mail arrives, so coordination does not
+route through the human ("ask the other session whether the release is
+green" instead of "Jeff, go ask").
+
+User-facing behavior is documented in
+[docs/user/cross-session-chat.md](../../user/cross-session-chat.md).
+
+## What it does
+
+- `thatch_chat_register` / `thatch_chat_list` / `thatch_chat_send` /
+  `thatch_chat_read` / `thatch_chat_unregister` / `thatch_chat_broadcast`
+  tools (shared across hosts; opencode injects identity, MCP hosts
+  self-declare with the as argument)
+- A shared SQLite directory and inbox in thatch.db, writable by any opencode
+  process on the machine
+- A per-process poller that heartbeats hosted sessions and delivers wake
+  prompts via `client.session.promptAsync` with a synthetic part - the same
+  mechanism watchers use
+- Anti-loop protection at two levels: prompt guidance (messages are
+  informational, no reflexive auto-reply) and a hard per-recipient nudge
+  rate cap
+
+## The shared-state, local-delivery decision
+
+Watchers keep their registry in plugin memory, never SQLite, because the
+process that registered a watcher is the only one that can deliver its
+events (see [watchers.md](watchers.md)). Chat cannot work that way: the
+sender's process and the recipient's process are usually different, so the
+state they coordinate through must be shared.
+
+The split:
+
+- **State is shared.** `chat_sessions` and `chat_messages` live in thatch.db.
+  Every opencode process on the machine reads and writes the same tables.
+  Concurrent access is the already-solved case - multiple sessions share the
+  DB for memories today, under WAL plus a busy timeout.
+- **Delivery is local.** Each process polls the inbox for messages addressed
+  to sessions it hosts (those it has seen `session.status` events for) and
+  prompts them through its own SDK client. A sender never prompts a session
+  in another process.
+
+This preserves the watcher rationale's core property - no process prompts a
+session it does not host - so each message has exactly one possible
+deliverer. There is no claiming logic, no double-delivery race, and no
+orphaned delivery state. The cost is the mirror of watchers': chat state
+outlives a process, so liveness needs a signal beyond process lifetime.
+
+## How it works
+
+### Registration and identity
+
+`chat_register` joins the directory. Without a name it draws one at random
+from the built-in pool (`src/chat-names.ts`): whimsical geek-culture names
+in the style of fnord's Nomenclater, statically baked in so assignment never
+costs a model call. Pool draws redraw on the rare collision a concurrent
+registration can cause, and skip any name a session already claimed by
+custom registration - so the pool is the recommended path. With a name,
+the session claims it as a custom name -
+uniqueness is case-insensitive ("Landru" and "landru" are one name), so two
+visually identical identities cannot coexist, and message addressing follows
+the same rule. Databases created before the case-insensitive constraint are
+rebuilt at schema init (first row wins per case group; message history
+survives because the endpoints are not foreign keys).
+
+Identity is the host session ID, which the model cannot know or forge.
+Re-registering renames. Unregistered sessions are invisible and
+unmessageable in both directions. Only top-level sessions should register -
+sub-agent children are ephemeral - which the tool descriptions and system
+prompt state; there is no mechanical barrier, a documented trust posture.
+
+Names are claimable by any session (no impersonation defense). The trust
+model is the same as the shared memory stores: every agent on this machine
+is the operator's agent.
+
+### Topics
+
+The optional topic is the roster's "who is working on what" signal: with a
+dozen registered sessions, a name like "Kurn the Typechecker" says nothing,
+but `topic:QAing the release` in `chat_list` tells a coordinator which
+session to address. Topics are free text, sanitized to one roster line
+(whitespace runs collapse, 80-character cap, advisory - oversizing degrades
+rather than errors). The null/empty distinction is deliberate: omitting the
+topic on re-register keeps the existing one; an empty topic clears it.
+Broadcast senders benefit most: `chat_broadcast` answers "which of you is
+working on X?" with the roster already in hand.
+
+### Messages
+
+`chat_send` addresses a recipient by display name or session ID. Both
+endpoints must be registered and distinct. `chat_read` drains the calling
+session's inbox oldest-first and stamps rows read. Message history survives
+unregistration; a departed sender degrades to an unknown name in the
+reader's view (the endpoints are deliberately not foreign keys - leaving the
+directory must not be blocked by history).
+
+`chat_broadcast` posts one message to every other registered session at
+once, one inbox row per recipient - the existing wake machinery (grouping,
+gating, rate cap) treats each as ordinary mail. Stale sessions are skipped
+and reported rather than messaged: a host that has stopped heartbeat-ing
+will never read the mail, and dead mail to a dead process is just clutter.
+The sender is excluded. It is a separate tool rather than a magic
+`chat_send` recipient because "send to all" changes the behavior (fan-out,
+stale skipping, no address resolution), and a function that changes
+behavior drastically on a parameter value is two functions.
+
+### Polling, heartbeat, staleness
+
+A `setInterval` loop (default 30s) runs one cycle per process: heartbeat the
+hosted sessions' `last_seen`, then deliver. A crashed process fires no
+`session.deleted`, so `chat_list` marks sessions whose `last_seen` is older
+than the staleness threshold (default 10 minutes) as stale rather than
+hiding them - the operator decides what to do with ghosts. `session.deleted`
+is the graceful-exit fast path that unregisters immediately.
+
+### Delivery, re-nudge, and the rate cap
+
+A message needs a wake prompt when it is unread and either never delivered
+or delivered more than the re-nudge window ago (default 15 minutes).
+Delivery is gated by the same `canDeliver` predicate watchers use - the
+recipient must be idle and not compacting - and the idle event handler
+flushes pending mail directly so it lands promptly instead of waiting for
+the next cycle. Failed deliveries stay pending and retry. Only registered
+recipients are ever selected: unregistering stops wake prompts for
+kept-but-unread mail, which is the `chat_unregister` tool's promise.
+Delivery is at-least-once - a crash after the wake prompt but before the
+delivered_at stamp re-nudges the same batch on the next cycle.
+
+One wake prompt covers all of a recipient's pending messages: sender names
+and a count, pointer-only like watcher notifications, with the model calling
+`chat_read` for content. On success the poller stamps `delivered_at`
+(re-stamping on re-nudges resets the re-nudge timer).
+
+The hard brake: at most a fixed number of wake prompts per recipient per
+hour (default 6, in-memory on purpose - it is a loop guard, not accounting).
+Without it, two agents politely acknowledging each other would ping-pong
+forever, each wake triggering a reply that wakes the other.
+
+### Transcript echo
+
+Plugin tools render in the opencode TUI as muted one-line generic entries,
+with the output block behind a default-off toggle - so without help, a chat
+exchange is invisible to the human watching the session. The plugin's
+`tool.execute.after` hook builds a short echo for the conversational events
+(`chatEchoText()` in `src/prompts.ts`: register, send, read, broadcast) and
+delivers it as a non-synthetic, `noReply` promptAsync part: rendered as a
+visible bubble in the transcript, no model turn started (the server's
+prompt path returns before the completion loop). Failed calls never echo;
+`chat_list` and `chat_unregister` stay on the muted tool line. Broadcasts
+echo their fan-out count with the clipped body.
+
+The trade-off: non-synthetic is what makes the TUI render the part, and it
+also means later turns see the echo in context - a small duplication of the
+tool call it mirrors, accepted for visibility. Echo bodies are clipped
+(send: the body; read: the formatted inbox; broadcast: the body) so a
+bubble stays cheap. Echo delivery is fire-and-forget: a failure must never
+fail the tool call it follows. Because the opencode server fires the
+`chat.message` hook for every prompt part before the `noReply`
+early-return, the plugin's `chat.message` handler skips messages whose
+visible text is entirely `[chat]`-prefixed bubbles (`isChatEchoParts`) -
+otherwise every echo would run the nudge machinery for a message no model
+turn reads. The accepted edge: a real user message whose every visible
+part starts with the prefix is skipped the same way, losing that one turn's
+advisory nudges.
+
+### CLI access
+
+The user watches the conversation without an agent: `thatch chat list`
+renders the roster with human-readable heartbeat ages, and
+`thatch chat tail [--once]` follows the message stream. The tail diffs
+`ChatStore.messageFeed()` snapshots via `chatTailDiff()` (unit-tested in
+`tests/chat.test.ts`): sent lines on first view, then new sends and newly-
+read messages per poll. `chat_messages.via_broadcast` marks fan-out rows so
+the tail renders one `-> broadcast` line per recipient instead of what
+would otherwise look like identical direct sends. The CLI takes no chat
+write actions (the wake machinery owns those paths); the only writes it
+can trigger are the schema migrations that run whenever any thatch
+process opens the database.
+
+## Interactions with other features
+
+- Watchers ([watchers.md](watchers.md)): chat reuses the delivery gate
+  (`canDeliver` over `sessionStatus` + `compacting`), the idle-flush
+  pattern, and the synthetic-part + toast notification shape. The state
+  model is the deliberate opposite - shared SQLite vs process memory - and
+  each feature's doc explains why its side of the split is right for its
+  problem.
+- Session lifecycle ([session-lifecycle.md](session-lifecycle.md)):
+  `session.status` feeds the delivery gate and the hosted-session set;
+  `session.deleted` unregisters.
+- Extraction pipeline ([extraction.md](extraction.md)): chat tool calls
+  are `thatch_*` tools and excluded from buffering like all thatch tools;
+  non-thatch tool calls made during a chat notification turn are buffered
+  and extracted like any other turn's.
+- Multi-host ([multi-host.md](multi-host.md)): the chat tools are shared -
+  MCP hosts register with a self-declared identity (the `as` argument;
+  the stored session ID is synthetic, `mcp_<hash of name>`), and pending
+  mail surfaces at prompt time through the flush-tools hook line and
+  `chat_status`. Wake-up delivery remains opencode-only: no MCP server
+  can start a turn in the client's conversation.
+
+## Multi-host delivery tiers
+
+Chat works on every host. Earlier designs for the MCP path - a JSONL
+temp-file inbox, a socket or daemon - were rejected: the DB already is the
+inbox, and MCP hosts cannot hold connections across turns, so both
+degenerate to the turn-granularity polling the tools already provide. The
+wake analog is the existing hook channel.
+
+| Host        | Send/receive | New-mail signal              | Echo bubbles |
+|-------------|--------------|------------------------------|--------------|
+| opencode    | yes          | promptAsync wake (idle-gated)| yes          |
+| claude code | yes          | flush-tools hook line        | no           |
+| cursor      | yes          | flush-tools hook line        | no           |
+
+MCP identity is the registered name: `chat_register` without a host
+session stores a synthetic `mcp_<sha256(name)[0:12]>` session ID, so the
+identity is stable across the ephemeral sessions those harnesses run.
+`chat_status` is the quiet check (registered flag + pending/total); the
+flush-tools hook line names the addressee sessions and prints nothing
+when the project has no pending chat - absence is silent by construction.
+Staleness semantics differ by kind: an opencode row's stale age means the
+process is gone (broadcast skips it), while an mcp row's age only means
+"between turns" (broadcast always delivers).
+
+## Defaults
+
+Timing constants live in `src/chat.ts`: poll interval 30s, staleness
+threshold 10 minutes, re-nudge window 15 minutes, nudge cap 6 per recipient
+per hour. There are no environment overrides yet; add them the way
+`THATCH_WATCH_POLL_SECONDS` works if a user needs them.
+
+## Source files
+
+- `src/chat.ts` - ChatStore (directory + inbox SQL, pool assignment),
+  ChatPoller (heartbeat, gated delivery, re-nudge, rate cap), staleness
+  helper
+- `src/chat-names.ts` - the static display-name pool (nomenclater style)
+- `src/db.ts` - the chat tables in schema init, the NOCASE collation
+  migration and topic column migration, delegated methods
+- `src/tool-defs.ts` - the chat tool definitions
+- `src/index.ts` - poller construction, delivery closure, idle flush,
+  session.deleted unregister, dispose, transcript echo in
+  tool.execute.after
+- `src/prompts.ts` - `chatNotificationNudge()`, `chatEchoText()` /
+  `isChatEchoParts()`, system prompt Cross-Session Chat section, MCP
+  absent-tools note
+- `tests/chat.test.ts` - store, pool, migration, echo-text, and poller unit
+  tests (temp-dir SQLite, injected delivery)
+- `tests/qa/auto/uc-097-chat.ts` - full lifecycle against a mocked poller
+- `tests/qa/live/uc-098-chat-cross-session.ts` - two real sessions exchange
+  a message through the shared DB

package/docs/dev/features/database.md

@@ -1,6 +1,6 @@
 # Database
 
-Thatch stores all data in a single SQLite file. The schema is organized around three concerns: memory entries, the prediction engine, and the behavior engine.
+Thatch stores all data in a single SQLite file. The schema is organized around feature concerns: memory entries, the prediction engine, the behavior engine, and cross-session chat.
 
 ## Configuration
 
@@ -10,13 +10,14 @@ Thatch stores all data in a single SQLite file. The schema is organized around t
 
 ## Schema overview
 
-The tables fall into three groups:
+The tables fall into these groups:
 
 | Group | Tables | Purpose |
 |-------|--------|---------|
 | Memory | `stores`, `entries`, `dedup_pairs` | Core memory CRUD + dedup verdicts |
 | Prediction engine | `prediction_matchers`, `predictions`, `prediction_edges`, `prediction_provenance` | User decision model |
 | Behavior engine | `behavior_matchers`, `behaviors`, `behavior_edges`, `behavior_provenance` | LLM self-discipline rules |
+| Cross-session chat | `chat_sessions`, `chat_messages` | Session directory + message inbox (shared across opencode processes) |
 
 The prediction and behavior engines share the same four-table shape (matchers, items, edges, provenance) with different table names. They are separate because the semantics differ: predictions model what the user wants; behaviors model what the LLM should do.
 
@@ -213,6 +214,52 @@ behavior_provenance(
 
 - `signal`: "confirm" (ham), "disconfirm" (spam), or "codify".
 
+## Cross-session chat tables
+
+### chat_sessions
+
+```sql
+chat_sessions(
+  session_id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE COLLATE NOCASE,
+  topic TEXT,
+  project TEXT,
+  registered_at TEXT NOT NULL,
+  last_seen TEXT NOT NULL
+)
+```
+
+- The machine-wide session directory. `last_seen` is the heartbeat: each
+  host process refreshes it for its own sessions every poll cycle, and a
+  stale value marks a crashed or closed process. Name uniqueness is
+  case-insensitive; databases whose chat_sessions table predates the NOCASE
+  constraint are rebuilt at schema init (first row wins per case group).
+
+### chat_messages
+
+```sql
+chat_messages(
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_session TEXT NOT NULL,
+  to_session TEXT NOT NULL,
+  body TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  delivered_at TEXT,
+  read_at TEXT,
+  via_broadcast INTEGER NOT NULL DEFAULT 0
+)
+```
+
+- `delivered_at` is the last wake-prompt stamp (restamped on re-nudges);
+  `read_at` is set when the recipient drains its inbox. `via_broadcast`
+  marks rows a chat_broadcast fan-out created (the CLI tail renders them
+  as `-> broadcast`). The endpoints are
+  plain columns, not foreign keys: unregistering a session must not be
+  blocked by message history, and a departed sender degrades to an unknown
+  name in the reader's view.
+
+See [cross-session-chat.md](cross-session-chat.md) for the delivery model.
+
 ## Schema migration
 
 `recall_count`, `last_recalled_at`, and `archived` are added to pre-existing databases by an idempotent column migration at init. The migration uses `PRAGMA table_info` to check for the column's existence, then `ALTER TABLE ADD COLUMN` if missing. This handles databases created before these columns existed.
@@ -235,8 +282,9 @@ Embeddings are raw Float32Array bytes stored as BLOBs. Serialization honors `byt
 
 - Memory store ([memory-store.md](memory-store.md)): `entries` table is the core; `stores` table is the registry
 - Deduplication ([deduplication.md](deduplication.md)): `dedup_pairs` table tracks reviewed pairs
-- Prediction engine ([prediction-engine.md](prediction-engine.md)): 4 prediction tables
-- Behavior engine ([behavior-engine.md](behavior-engine.md)): 4 behavior tables
+- Prediction engine ([prediction-engine.md](prediction-engine.md)): the prediction tables
+- Behavior engine ([behavior-engine.md](behavior-engine.md)): the behavior tables
+- Cross-session chat ([cross-session-chat.md](cross-session-chat.md)): the chat tables, shared across opencode processes
 - Hygiene ([hygiene.md](hygiene.md)): `staleEntryCount` uses `recall_count` and `last_recalled_at`; `branchesInStore` uses `branch` column
 
 ## Source files

package/docs/dev/features/multi-host.md

@@ -16,11 +16,16 @@ Thatch supports three host agents from a single codebase:
 - **Cursor MCP**---same stdio MCP server, `--json` hook output format,
   `mcp__thatch__` tool prefix, system prompt in AGENTS.md
 
-All three paths share the tool definitions from `src/tool-defs.ts`: 18
-host-agnostic tools plus opencode-only tools (currently seven:
-`get_session_info`, `session_search`/`session_get`, and the
-`watch_create`/`watch_branch_create`/`watch_list`/`watch_cancel` watcher tools), which the MCP server
-filters out. The shared tools take args and a `CoreContext`
+All three paths share the tool definitions from `src/tool-defs.ts`: the
+host-agnostic tools plus the opencode-only tools, which the MCP server
+filters out. The opencode-only set covers host-session capabilities MCP
+hosts lack: `get_session_info`, `session_search`/`session_get` (no session
+concept or session database), the `watch_create`/`watch_branch_create`/
+`watch_list`/`watch_cancel` watcher tools (no poller or proactive-prompt
+channel), and the `chat_register`/`chat_list`/`chat_send`/`chat_read`/
+`chat_unregister`/`chat_broadcast` chat tools (no session identity or
+wake-up channel). The
+shared tools take args and a `CoreContext`
 (`{ db, model, defaultStore }`) and return a string. The host-specific
 wrapping---prefixing, transport, session hooks---lives outside the core.
 
@@ -74,9 +79,10 @@ at session start.
 so the agent sees `mcp__thatch__memory_remember`. Thatch itself does not apply
 this prefix.
 
-**Skills**: installed to `$CLAUDE_CONFIG_DIR/skills/`---shared skills only.
-The code-review coordinator skill is opencode-only because it requires
-sub-agent dispatch, which Claude Code does not support.
+**Skills**: installed to the scope's skills dir (repo `.claude/skills/` for
+project-local setup, `$CLAUDE_CONFIG_DIR/skills/` for `--global`)---shared
+skills only. The code-review coordinator skill is opencode-only because it
+requires sub-agent dispatch, which Claude Code does not support.
 
 **Session behavior**: driven by external CLI hook processes (`bin/thatch`).
 The hooks are registered in `.claude/settings.json` during setup. Each hook
@@ -182,6 +188,8 @@ behavior, with some features having no MCP counterpart.
 | Tool batching | N/A (in-process) | PostToolBatch (batch) | postToolUse (per-tool) |
 | `get_session_info` (session identity) | Yes | No | No |
 | `session_search` / `session_get` (conversation archaeology) | Yes (tools) | CLI only (`thatch session ...`) | CLI only (`thatch session ...`) |
+| `watch_*` (PR and branch watchers) | Yes (tools) | No | No |
+| `chat_*` (cross-session chat) | Yes | No | No |
 
 For the full parity matrix, see [../mcp-parity.md](../mcp-parity.md).
 
@@ -231,4 +239,4 @@ the opencode-only skills require sub-agent dispatch or in-process hooks.
 - The MCP server always exposes bare names. The `mcp__thatch__` prefix is applied by the MCP client, not thatch.
 - The three system prompt variants are independent string constants in `src/prompts.ts` with no shared template. Editing shared prose in one requires mirroring in the other two, or they drift.
 - The tool list line in all three prompts must match `TOOL_DEFS` in `src/tool-defs.ts` (opencode's list includes opencode-only tools; the MCP lists exclude them). The historical failure mode: a tool is added to `TOOL_DEFS` but only two of three prompts are updated.
-- opencode-only features (direct extraction, compaction recovery, code-review coordinator, background sub-agents, TUI toasts, `get_session_info`, `session_search`/`session_get`, PR watchers) have no MCP counterpart. The `thatch session` CLI subcommands work anywhere - they only need an opencode.db file to read.
+- opencode-only features (direct extraction, compaction recovery, code-review coordinator, background sub-agents, TUI toasts, `get_session_info`, `session_search`/`session_get`, PR watchers, cross-session chat) have no MCP counterpart. The `thatch session` CLI subcommands work anywhere - they only need an opencode.db file to read.

package/docs/dev/features/setup.md

@@ -52,8 +52,9 @@ Four artifacts, all idempotent:
    → `thatch reminder`, `PostToolBatch` → `thatch buffer-batch`,
    `UserPromptSubmit` → `thatch flush-tools`. Nested format:
    `{hooks:{Event:{hooks:[{type,command}]}}}`.
-4. **Skills** --- installs to `$CLAUDE_CONFIG_DIR/skills/` (always
-   user-scoped, even for project-local setup). `SHARED_SKILLS` only --- the
+4. **Skills** --- installs to the scope's skills dir: the repo's
+   `.claude/skills/` for project-local, `$CLAUDE_CONFIG_DIR/skills/` for
+   `--global`. `SHARED_SKILLS` only --- the
    code-review coordinator requires sub-agent dispatch, which Claude Code
    does not support.
 
@@ -73,7 +74,9 @@ Four artifacts, same idempotent pattern:
    `{version:1, hooks:{event:[{command}]}}`. Three hooks: `sessionStart`
    → `thatch reminder --json`, `postToolUse` → `thatch buffer-tool`,
    `beforeSubmitPrompt` → `thatch flush-tools --json`.
-4. **Skills** --- installs to `$CURSOR_CONFIG_DIR/skills/` (shared only).
+4. **Skills** --- installs to the scope's skills dir: the repo's
+   `.cursor/skills/` for project-local, `$CURSOR_CONFIG_DIR/skills/` for
+   `--global` (shared only).
 
 ### Marker system (`appendBlock`)
 
@@ -184,8 +187,12 @@ example, an older `thatch echo` hook is replaced with the current
 1. **All operations are idempotent.** Re-running setup updates drifted content
    without clobbering. Instructions use markers, hooks filter by `thatch`
    string, MCP config preserves existing servers, skills diff before writing.
-2. **Skills are always user-scoped**, even in project-local setup. Claude Code
-   and Cursor load skills from the user config dir, not the project.
+2. **Skills follow the setup scope.** Project-local installs write skills to
+   the repo's `.claude/skills/` / `.cursor/skills/` (Claude Code and Cursor
+   both discover project skills there); `--global` writes to the user config
+   dirs. Setup reports the directory plus added/updated/removed/unchanged
+   counts, and notes (without touching) any thatch skills found in the
+   opposite scope.
 3. **`appendBlock` leaves content alone if markers do not parse.** A start
    marker without an end marker means the file was edited externally. Writing
    would risk clobbering content after the start marker.

package/docs/dev/gotchas.md

@@ -124,10 +124,13 @@ here first. These are the things that have already cost time.
 
 ## 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.
+- **Skills follow the setup scope.** Project-local installs write skills to
+  the repo's `.claude/skills/` / `.cursor/skills/` (they version with the
+  project); `--global` writes to `$CLAUDE_CONFIG_DIR/skills/` /
+  `~/.cursor/skills/`. A run never touches the opposite scope: if thatch
+  skills already exist there (e.g. user-scope copies from an older local
+  setup), setup reports them in a note but leaves them alone, so they can
+  drift stale until refreshed or deleted.
 - **`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.

package/docs/dev/mcp-parity.md

@@ -18,7 +18,7 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR and branch watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel |
+| **Tools** (single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR and branch watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel. The `chat_*` tools (cross-session chat) are opencode-only — no host session identity and no wake-up channel |
 | **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 |
@@ -27,7 +27,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **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 |
 | **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
 | **Behavior auto-fire** (self-discipline rules) | `chat.message` hook scores the prompt embedding against behavior matchers; injects a `[thatch] Situational behaviors` nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires behavior query via the sideband socket's `behaviors` method in parallel with recall and predictions | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scoreBehaviorNudge` entry point in both paths |
-| **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) |
+| **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed by `thatch setup` (shared only) to the repo's `.claude/skills/` (local) or `$CLAUDE_CONFIG_DIR/skills/` (global) | Installed by `thatch setup` (shared only) to the repo's `.cursor/skills/` (local) or `~/.cursor/skills/` (global) | **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** |
 | **Setup detection at startup** | n/a — plugin auto-installs at init | `checkSetup` in MCP server: detects missing or broken instructions in CLAUDE.md | Same as Claude Code (checks AGENTS.md) | **Full** — warns the agent to tell the user to run `thatch setup` |
 | **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 |

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

@@ -49,11 +49,12 @@ the TUI is not connected (headless mode).
 | 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 |
+| Skills | `.claude/skills/` (in the repo) | `$CLAUDE_CONFIG_DIR/skills/` |
 
 `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.
+paths. Project-local keeps everything in the repo: `.mcp.json`, `CLAUDE.md`,
+`.claude/settings.json`, and `.claude/skills/` (so skills version with the
+project and every contributor gets them).
 
 ### Hook events (nested `settings.json`)
 
@@ -88,7 +89,7 @@ Cursor uses the same stdio MCP server as Claude Code; only the hooks differ.
 | 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 |
+| Skills | `.cursor/skills/` (in the repo) | `$CURSOR_CONFIG_DIR/skills/` |
 
 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

package/docs/dev/skills.md

@@ -46,7 +46,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
-| `thatch-review-mentorship` | Peer-mentorship lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, verified citations, never blocking. |
+| `thatch-review-technique` | Technique lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, verified citations, never blocking. |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
 | `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
 | `thatch-code-archaeology` | Investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. The research skill; pair with `thatch-coding-workflow`. |
@@ -112,9 +112,10 @@ 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.
+- **Location**: `$XDG_CONFIG_HOME/opencode/skills` (opencode);
+  scope-dependent for MCP hosts — the repo's `.claude/skills/` or
+  `.cursor/skills/` for project-local `thatch setup`, the host config
+  dirs (`$CLAUDE_CONFIG_DIR/skills`, `~/.cursor/skills`) for `--global`.
 - **Trigger**: opencode installs at plugin init; Claude Code/Cursor install via
   `thatch setup`.
 - **Drift detection**: `installSkills` only writes when the on-disk content