@jeffober/thatch 0.1.40 → 0.1.42

package/docs/dev/features/watchers.md

@@ -3,10 +3,11 @@
 Watchers are the general mechanism for event-driven notifications from
 external sources: the model registers a watch on something outside the
 session, thatch polls it in the background, and the plugin prompts the
-session when a watched event happens. Two sources ship: GitHub pull
-requests (source `pr`) and GitHub branches (source `branch`, for
-watching CI and workflow runs on main). The registry, poller, and
-delivery are source-agnostic - a new source adds a fetch-and-diff
+session when a watched event happens. Three sources ship: GitHub pull
+requests (source `pr`), GitHub branches (source `branch`, for watching
+CI and workflow runs on main), and local shell commands (source
+`command`, for waiting on arbitrary conditions). The registry, poller,
+and delivery are source-agnostic - a new source adds a fetch-and-diff
 function pair and event types.
 
 User-facing behavior is documented in [docs/user/watchers.md](../../user/watchers.md).
@@ -14,13 +15,16 @@ User-facing behavior is documented in [docs/user/watchers.md](../../user/watcher
 ## What it does
 
 - `thatch_watch_create` (PRs) / `thatch_watch_branch_create` (branches) /
-  `thatch_watch_list` / `thatch_watch_cancel` tools (all opencode-only)
+  `thatch_watch_command_create` (commands) / `thatch_watch_list` /
+  `thatch_watch_cancel` tools (all opencode-only)
 - A background poller in the plugin process diffs each watcher's target
   against its last-seen state
 - Delivery prompts the session with a synthetic part - the same
   mechanism opencode uses for background task completions
-- Notifications carry pointer data only (author, URL, counts); the
-  model fetches content on demand with `gh`
+- Notifications carry pointer data plus machine status (author, URL,
+  check names and conclusions, exit codes); external content is fetched
+  on demand with `gh` or by re-running a watched command, never
+  delivered
 
 ## The process-lifetime decision
 
@@ -72,6 +76,12 @@ attempt delivery. Poll errors are per-watcher; one bad PR never
 blocks the others. The diff is a pure function, so it is unit-tested
 without any network access.
 
+The interval is surfaced to the model through the registry's
+`pollSeconds` getter: watch-creation output states when the first
+poll lands, and notifications carry a cadence line, so a model
+choosing between a watcher and an in-turn poll compares real numbers
+even when `THATCH_WATCH_POLL_SECONDS` overrides the default.
+
 Event detection:
 
 - comments by id monotonicity (fetch is sorted descending)
@@ -89,6 +99,57 @@ Event detection:
 A diff emits at most 10 events per watcher per cycle, so comment
 floods collapse into one batch.
 
+### One-shot watches
+
+`watch_create` and `watch_branch_create` accept `once: true`. The
+watcher cancels itself when its first matching event is detected, not
+when it is delivered - the event still queues and delivers through the
+normal pending path, so a session busy at fire time does not lose the
+notification. Cancellation at detection time is what keeps a "tell me
+when this run finishes" request from leaving a standing watch polling
+a target nobody is waiting on. `watch_list` marks one-shot watchers
+with a `[once]` tag, and the registration output states the mode.
+
+### Command watches
+
+The command source stretches the fetch/diff recipe in two ways:
+
+1. **The fetch has side effects.** `runWatchedCommand()` executes the
+   watched command via `bash -c` in the project directory each cycle.
+   This is the point - the command IS the condition - but it means
+   command watchers must not block: the tool description and system
+   prompt state the contract (fast, idempotent status check; never
+   `gh run watch` or `tail -f`), and a per-run kill timeout
+   (default 30s, `THATCH_WATCH_COMMAND_TIMEOUT_SECONDS`) bounds a
+   hung command's cost to one partial poll cycle - other watchers
+   wait out the kill rather than stalling, but a blocking command
+   still burns its timeout slice every cycle. A timed-out run means
+   "not done yet": the last-seen exit is left untouched and the watch
+   keeps polling.
+2. **The diff is a trivial exit-code check.** The command is a
+   condition variable, not a data pipe: stdout is drained (a full
+   pipe buffer would deadlock the child) but discarded, and stderr is
+   kept only for registration-time error messages. The notification
+   carries the exit code and duration; command output can be external
+   content, so it never rides a notification. This is the strictest
+   application of the notification content rule. The pipe drains are also
+   raced against a hard deadline, because a
+   command that backgrounds a long-lived child leaves a grandchild
+   holding the pipe write-ends past the kill - without the race, the
+   drains never resolve and the shared poll cycle stalls forever.
+
+`createCommand()` runs the command once at registration as baseline
+validation, like `createPr()`'s baseline fetch: exit 0 at baseline
+means the condition is already met (refused, so the caller proceeds
+now), exit 127 means the command does not exist (refused with the
+stderr tail), and a spawn failure fails registration with a real
+error. A baseline run that times out records the 124 sentinel as the
+last-seen exit - the killed process may have exited 0 while dying, and
+the watcher's first real exit 0 must fire. Registered command
+watchers carry `once: true` inherently - "run until it returns 0,
+then notify, then stop" is the whole concept. The `CommandRunner` is
+injectable like `GhRunner`, so tests never spawn processes.
+
 ### Delivery
 
 Events queue in an in-memory pending map keyed by session. Delivery
@@ -101,9 +162,15 @@ on the session with a synthetic text part built by
 `watcherNotificationNudge()`. This triggers a full model turn - the
 model reads the notification and decides whether to act. The
 notification text borrows the background-task-completion framing
-(system event, not user input, not approval to advance other work),
-following the same load-bearing wording discipline as the extraction
-nudge.
+(system event, not user input, not approval to advance other work)
+with one carve-out: a watch registered to gate work the user already
+greenlit (for example "wait for CI, then merge") makes the
+notification the continuation signal for exactly that work. The
+carve-out lives in the nudge itself, not only the system prompt,
+because the nudge is what the model reads at the act-or-wait decision
+point. The wrapper also states that check-run and workflow
+conclusions are already in the event summaries, so gh fetches are
+needed only for logs and bodies.
 
 Failed or gated deliveries stay pending and retry on the next poll
 cycle or when the session next goes idle (the event hook calls
@@ -114,7 +181,10 @@ cycle or when the session next goes idle (the event hook calls
 `pr_comment`, `pr_review_comment`, `pr_review_reply`,
 `pr_review_resolved`, `pr_commit`, `pr_status`, `pr_description`,
 `pr_ci`. The tool's `events` argument selects a subset; the default is
-all eight.
+all eight. Branch watchers add `branch_commit`, `branch_ci`, and
+`branch_workflow` (the full vocabulary is `WATCHER_EVENT_TYPES` in
+src/watchers.ts, test-enforced); command watchers register the single
+`command_success` type.
 
 ## Interactions with other features
 
@@ -134,28 +204,48 @@ all eight.
 - `THATCH_WATCH_POLL_SECONDS` - poll interval (default 60)
 - `THATCH_WATCH_TTL_MINUTES` - watcher time-to-live (default 480)
 - `THATCH_WATCH_MAX_PER_SESSION` - active watchers per session
-  (default 5)
+  (default 5; all sources share the budget)
+- `THATCH_WATCH_COMMAND_TIMEOUT_SECONDS` - per-run kill timeout for
+  watched commands (default 30)
 
 ## Source files
 
-- `src/watchers.ts` - registry, poller, gh CLI runner, diff functions
-- `src/tool-defs.ts` - the three watch tool definitions
+- `src/watchers.ts` - registry, poller, gh CLI runner, command runner,
+  diff functions
+- `src/tool-defs.ts` - the watch tool definitions (see `TOOL_DEFS`)
 - `src/index.ts` - registry construction, delivery closure,
   session.status tracking, session.deleted cleanup, dispose
 - `src/prompts.ts` - `watcherNotificationNudge()`, system prompt
   Watchers section
 - `tests/watchers.test.ts` - registry, poll, and diff unit tests
-  (mocked gh, no network)
+  (mocked gh and command runners, no network)
+- `tests/tool-defs.test.ts` - watch tool execute-function tests
 - `tests/qa/auto/uc-095-watchers.ts` - end-to-end lifecycle against a
   mocked gh runner
+- `tests/qa/auto/uc-101-command-watchers.ts` - command-watch lifecycle
+  against a mocked command runner
 
 ## Adding a new source type
 
-The registry is a discriminated union over sources: `PrWatcher` and
-`BranchWatcher` implement the same lifecycle (id, session, repo,
-events, expiry, snapshot), and `poll()` dispatches to the source's
-fetch/diff pair. Adding a third source means: new event types, a
-`fetchXState`/`diffXState` pair, a new arm of the `Watcher` union, a
-`#pollOne` branch, and the tool surface for registering it. Keep the
-pointer-only notification rule: external content enters the context on
-explicit fetch, never via notification.
+The registry is a discriminated union over sources: `PrWatcher`,
+`BranchWatcher`, and `CommandWatcher` implement the same lifecycle
+(id, session, events, expiry, snapshot), and `poll()` dispatches to
+the source's fetch/diff pair. Adding a new source means: new event
+types, a fetch function and diff (or a trivial inline diff like the
+command source's), a new arm of the `Watcher` union, a `#pollOne`
+branch, and the tool surface for registering it. Keep the
+notification content rule: external content enters the context on
+explicit fetch, never via notification. Machine status fields (names,
+conclusions, counts, exit codes) come from the API rather than
+user-written text and belong in event summaries.
+
+Two caveats from the command source, worth carrying to future
+sources:
+
+- If the source's fetch does anything beyond reading an API, inject a
+  runner (like `GhRunner`/`CommandRunner`) so tests never spawn real
+  work, and bound it with a timeout so a hung fetch cannot stall the
+  shared sequential poll cycle.
+- If the source has no natural URL (a local command has none), emit
+  an empty `url` in the event; `watcherNotificationNudge()` omits
+  empty URLs rather than rendering a dangling space.

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, branch, and command 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

package/docs/user/README.md

@@ -11,7 +11,8 @@ This README is the overview. Each feature has its own guide:
 
 - [memory.md](memory.md): persistent memory store
 - [extraction.md](extraction.md): automatic fact extraction from tool calls
-- [watchers.md](watchers.md): event-driven notifications (PR and branch watching)
+- [watchers.md](watchers.md): event-driven notifications (PR, branch, and command watching)
+- [cross-session-chat.md](cross-session-chat.md): sessions messaging each other on one machine
 - [notifications.md](notifications.md): banner and voice notifications, user config
 - [prediction-engine.md](prediction-engine.md): user decision model
 - [behavior-engine.md](behavior-engine.md): agent self-discipline rules
@@ -178,12 +179,27 @@ search` - JSONL output designed for piping to `jq` or `grep`.
 |------|-------------|
 | `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, thread resolutions, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
 | `thatch_watch_branch_create` | Watch a GitHub branch (typically main) for commit landings, CI check-run completions, and workflow runs, with an optional workflow-name filter. |
+| `thatch_watch_command_create` | Wait on any local condition via a shell command that exits 0 when the wait is over. One-shot: one notification on the first exit 0, then it cancels itself. |
 | `thatch_watch_list` | List this session's active watchers. |
 | `thatch_watch_cancel` | Cancel one of this session's watchers by id. |
 
 See [watchers.md](watchers.md) for the full behavior, lifetime, and
 requirements.
 
+### Chat tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_chat_register` | Join the cross-session chat directory, so other sessions on this machine can message you. Display names are assigned by thatch, never chosen (a slug plus a never-reused counter), so a name always refers to the same session. Call with no arguments to join, rejoin after unregistering, or check your name. On hosts without session context (Claude Code, Cursor), pass the name your thatch hook printed as `as`. |
+| `thatch_chat_list` | List registered sessions with a liveness marker (fresh = its process is alive, stale = likely gone), each session's project and topic, and your unread count. |
+| `thatch_chat_send` | Send a message to another registered session, by name or session id. The recipient is nudged when its session is idle. |
+| `thatch_chat_read` | Drain your inbox: all unread messages oldest-first, marked read. Senders identified by display name. |
+| `thatch_chat_unregister` | Leave the chat directory. |
+| `thatch_chat_broadcast` | Send one message to every other live registered session at once. Stale sessions (dead host processes) are skipped and reported. Use sparingly: every live session pays a model turn for a broadcast. |
+
+See [cross-session-chat.md](cross-session-chat.md) for the full behavior,
+liveness model, and limitations.
+
 ## Automatic behaviors
 
 Beyond the tools, thatch hooks into opencode itself:
@@ -248,9 +264,12 @@ agent can tell the user to run `thatch setup`.
 
 On startup thatch installs [skills] into your global opencode config
 (`~/.config/opencode/skills/`, or `$XDG_CONFIG_HOME/opencode/skills`).
-With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
-`$CLAUDE_CONFIG_DIR/skills/`); with `thatch setup --cursor`, to
-`~/.cursor/skills/`.
+With `thatch setup --claude`, skills follow the install scope: the
+repo's `.claude/skills/` for project-local, `~/.claude/skills/` (or
+`$CLAUDE_CONFIG_DIR/skills/`) for `--global`. `thatch setup --cursor`
+works the same way with `.cursor/skills/` and `~/.cursor/skills/`.
+Setup reports the skills directory and how many skills were added,
+updated, removed, or already current.
 
 ### Memory skills
 
@@ -265,7 +284,7 @@ With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
 
 ### Code review skills
 
-Eight specialist review lenses, plus the synthesizer, context, followup,
+Nine specialist review lenses, plus the synthesizer, context, followup,
 response, walkthrough, and workflow skills that support the review pipeline:
 
 | Skill | Focus |
@@ -278,7 +297,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's 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, 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, never blocking. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then highlights, then deduplicated severity-grouped findings. |
 | `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, linked docs/tickets, memory) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. Pairs with `thatch-coding-workflow`. |

package/docs/user/cli.md

@@ -39,6 +39,84 @@ hygiene report. The `--json` flag wraps the output as
 commands are normally called by hooks, not by hand, but you can run
 them to see what the agent sees at session start.
 
+## Cross-session chat
+
+Read-only access to the chat directory your opencode sessions share
+(see [cross-session-chat.md](cross-session-chat.md)):
+
+```bash
+thatch chat list               # who is registered: name, age, project, topic
+thatch chat tail               # follow sent and read events, live
+thatch chat tail --once        # print the last 20 messages and exit
+thatch chat tail --once --limit 50   # a longer backlog (or --limit all)
+thatch chat tail --match "rebase" --match "payments"   # body must match both
+thatch chat tail --from al --to bob        # substring match on names
+thatch chat tail --since 2026-09-12 --until "2026-09-13 09:00"   # a window
+```
+
+`chat list` shows every registered session with how long since its last
+heartbeat (a large age means the session's process is probably gone), its
+project, and the topic it registered with - the fastest way to answer
+"which session should I talk to about X?"
+
+`chat tail` prints the conversation as styled chat cards (labels on a
+colored background, names in color, timestamps dimmed; a drawn rule
+separates cards, with blank lines on either side). After each name, the
+session's registered topic appears in muted italics - so the tail tells
+you not just who is talking but what they are working on:
+
+```text
+ From   Al Go Rithm <cross-session messaging between opencode sessions>
+ To     Brute the Dream Farrier <diagnosing watcher underuse>
+ When   2026-09-12 14:02 America/Denver
+
+CI is green on main
+____________________________________________________________
+
+ To     broadcast
+ When   2026-09-12 21:07 America/Denver
+
+rebasing payments, hold off
+____________________________________________________________
+
+ From   Kurn the Typechecker <release QA>
+ read Marlowe the Cherry Picker <payments refactor>
+ When   2026-09-12 21:08 America/Denver
+
+direct ping
+```
+
+Follow mode runs until Ctrl-C. Read events appear only in follow mode
+(they fire when an inbox is drained after the tail started). When
+timestamps are in your local timezone. The chat itself flows through the
+agents (the CLI never sends, reads, or registers on a session's behalf;
+that happens from opencode sessions via the `thatch_chat_*` tools).
+
+The backlog shows the last 20 messages before follow mode takes over.
+When messages are hidden, tail prints a one-line note on stderr saying
+how many there were; `--limit N` raises or lowers the backlog and
+`--limit all` shows everything. All the filters apply to live events
+too, so a filtered tail keeps watching the same way:
+
+- `--match PATTERN` filters message bodies. Repeat it to AND patterns
+  together: every one must match the message body.
+- `--from NAME` and `--to NAME` match participant names (case doesn't
+  matter). A departed sender can only be found as the `unknown`
+  rendering the tail shows. Broadcast cards say `broadcast` in the To
+  slot, but the row underneath keeps the real recipient: `--to <name>`
+  finds the fan-out rows that reached them, while `--to broadcast`
+  matches nothing.
+- `--since DT` and `--until DT` bound the window; a message counts if
+  it was sent at or after `--since` and before `--until`. The date
+  format is `YYYY-MM-DD` with an optional `HH:MM` in your local
+  timezone.
+
+A `--until` already in the past exits after the backlog (a closed
+window has nothing left to follow); one in the future follows until
+the window closes. Note that the limit hides sent cards, not their
+reads: a hidden message that gets read during follow mode still emits
+its read card.
+
 ## Priming a new project
 
 ```bash

package/docs/user/code-review.md

@@ -43,7 +43,7 @@ the review:
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's 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: clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
-| `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, 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, never blocking. |
 
 Each specialist is a self-contained static-analysis pass. They can run
 individually or as part of the coordinated review.

package/docs/user/cross-session-chat.md

@@ -0,0 +1,150 @@
+# Cross-Session Chat
+
+Cross-session chat lets your opencode sessions talk to each other. If one
+session is QAing a release and another is planning a feature, the second can
+ask the first "is the release green yet?" instead of you relaying messages
+between tabs all afternoon.
+
+## What it does
+
+opencode sessions join the directory automatically, on their first idle
+moment. Names are assigned by thatch, never chosen: a lowercase slug of the
+session's title plus a counter (a session titled "Fix auth bug" becomes
+`fix-auth-bug-00001`). The counter only ever increments, so a name is
+minted exactly once per machine - pruning an old session never reissues its
+name to someone else, and the same name always refers to the same session.
+The live title rides along as the session's topic (refreshed as the
+auto-titler converges), so the roster reads as a who-is-working-on-what
+board without anyone filling in forms. A session can also join or rejoin
+explicitly with `thatch_chat_register` (no arguments) - useful after
+`chat_unregister`, or just to check your assigned name. Once registered:
+
+- `thatch_chat_list` shows every registered session on the machine, with a
+  liveness marker (fresh or stale), its project, its topic, and your unread
+  count
+- `thatch_chat_send` delivers a message to another registered session, by
+  name or session id
+- `thatch_chat_read` drains the session's inbox
+- `thatch_chat_broadcast` delivers one message to every other live
+  registered session at once
+- `thatch_chat_unregister` leaves the directory
+
+When mail arrives for an idle session, thatch wakes it with a notification -
+the agent gets a model turn even with nobody at the keyboard, reads its
+inbox, and decides what to do. The notification names the senders and the
+count only; the agent reads the actual messages itself.
+
+Broadcasts are for announcements and open questions ("which of you is
+working on the payments code?", "main just moved, rebase if you are based
+on it"). Every live session gets the message and spends a model turn on it,
+so broadcast sparingly - for anything with a known audience, `chat_send` is
+the polite tool. Stale sessions are skipped and reported: a dead session
+never reads a broadcast.
+
+## Watching the conversation
+
+Chat activity is visible in each session's transcript: registering,
+sending, reading, and broadcasting echo back as `[chat]` bubbles, so you
+can watch the exchange happen in either tab without leaning over the
+agent's shoulder. Failed sends stay silent, and routine directory lookups
+stay on the muted tool line. You can also watch from the terminal:
+`thatch chat list` and `thatch chat tail` are covered in
+[cli.md](cli.md). (Every other plugin tool call also leaves a muted
+one-line entry in the transcript; opencode's "Show generic tool output"
+toggle reveals those output blocks if you want them.)
+
+## How to use it
+
+With auto-registration you usually do nothing: both sessions are already
+in the directory. To introduce them, just tell each session who to talk to:
+
+> Ask the other session whether the release has shipped; answer its
+> questions directly.
+
+Sessions find each other with `thatch_chat_list` and address each other by
+their assigned names.
+
+Received messages are treated as informational, not as your instructions: an
+agent that gets mail will not treat it as approval to start work, and it
+will not auto-reply unless the message bears on something it is already
+doing. When in doubt it summarizes the mail for you and waits. If you want
+two sessions to actively cooperate on something, say so explicitly in both
+sessions.
+
+## Liveness
+
+A session shows as fresh while its opencode process is running. A crashed
+or closed process stops heartbeat-ing, and the session shows as stale in
+`thatch_chat_list` after ten minutes. Messages to a stale session wait in
+its inbox unread - a dead session never reads them. Explicitly closing a
+session (deleting it in the TUI) unregisters it immediately.
+
+## Turning chat off
+
+Set `chat.enabled: false` in the thatch config file
+(`~/.config/thatch/config.json`) - or ask an agent:
+`config_set with chat: { enabled: false }`. When off:
+
+- every chat tool refuses, stating that chat is disabled and how to
+  re-enable it
+- the poller never starts, so nothing is woken or heartbeated
+- the system prompt omits the chat section entirely, and the hook lines
+  print nothing - the feature stops existing as far as any agent can tell
+
+Takes effect for the tools immediately (they re-read the config per
+call); a restart applies it to the poller and prompt. Delete the setting
+(or set it true) to turn chat back on.
+
+## Turning auto-registration off
+
+Set `chat.autoRegister: false` in the same config file when you want the
+old opt-in behavior: opencode sessions stay out of the directory until
+they call `chat_register`. (The Claude Code / Cursor hook still ensures
+its conversation's identity is registered on each prompt - that is the
+host's identity anchor, not auto-joining; remove the hook with
+`thatch setup` if you want those hosts out too.) Wake delivery for
+registered sessions still works; there is just no automatic joining.
+
+## Leaving the directory
+
+`chat_unregister` is a real exit on every host: a leave tombstone
+suppresses re-joining (auto-registration on opencode, the hook's ensure on
+other hosts) until the session explicitly calls `chat_register` again.
+Without the tombstone, the next idle moment would silently re-register the
+session under a fresh name and undo the leave. Rejoining mints a new name
+(assigned names are never reused, even by the same session).
+
+## Security model
+
+Chat messages are text written by OTHER agent sessions, delivered into a
+reading agent's context verbatim - a prompt-injection surface by
+construction. Three mitigations:
+
+- **Framed at read time.** `chat_read` wraps its output in an explicit
+  untrusted-content frame (begin/end fences with a do-not-follow warning).
+  The frame exists only in the tool output; the persisted messages are
+  untouched.
+- **Names are assigned, not claimed.** Display names are minted by thatch
+  with a never-reused counter, so a name cannot be grabbed by an unrelated
+  session and an old name cannot be resurrected by an impersonator.
+- **No external content via wake.** The wake notification names senders
+  and counts only - bodies flow exclusively through the framed
+  `chat_read` surface.
+
+## Requirements and limitations
+
+- **Wake-up delivery is opencode only.** The chat tools work everywhere
+  (other hosts declare their identity with `as`), but only opencode can
+  start a turn when a message arrives; Claude Code and Cursor see pending
+  mail at their next prompt (the flush-tools hook line, or `chat_status`).
+- **Same machine only.** The directory and inbox live in thatch's local
+  database. There is no network relay.
+- **Opt-in.** Unregistered sessions cannot be messaged and cannot send.
+  Sub-agent sessions should not register.
+- **Loop safety.** Thatch caps wake prompts per recipient per hour, so two
+  agents acknowledging each other cannot ping-pong forever even if both
+  models decide to be chatty.
+- **Message retention.** Messages are kept as history; unregistering does
+  not delete them. Auto-registered sessions whose host has been gone for a
+  week are pruned from the directory (their names are never reused), and
+  unread mail addressed to them is removed on a later sweep.