@jeffober/thatch 0.1.42 → 0.1.44

package/docs/plans/thatch-actions.md

@@ -0,0 +1,144 @@
+# Thatch Actions: Prompt Cores Shared by Nudges and /thatch Commands
+
+## Synopsis
+
+Extract the behavior instructions currently embedded in nudge text into
+prompt-core constants in `src/prompts.ts`, then build `/thatch/*` user-facing
+commands on top of the same constants. The nudge and the command become two
+envelopes around one instruction body: the nudge adds escalation tiers and
+stop-and-wait framing, the command adds user-invocation framing. First
+payoff is `/thatch/defrag`, but the structure covers any behavior the nudges
+currently ask the agent to perform on demand.
+
+## Background
+
+Nudges are instruction-carrying messages injected by hooks. Several encode a
+multi-step behavior the agent must execute (dispatch a sub-agent, fetch the
+extraction payload, run a skill, ack). The same behaviors have no user-facing
+invocation path: the user cannot say "drain the extraction queue now" or
+"consolidate duplicate memories now" -- they can only wait for a nudge or
+describe the desired behavior in prose and hope the agent maps it to the right
+skill + tool sequence.
+
+Two existing pieces make this cheap to add:
+
+- `src/commands.ts` already ships `/thatch/compact` and `/thatch/exit` as
+  markdown command files synced into the opencode config dir, and already
+  composes them from shared fragments (`sharedChecklist`,
+  `userMessageSection`).
+- The "Shared prose sync across prompt variants" problem is documented:
+  prompt prose lives in parallel functions with no single source of truth,
+  and drift in unasserted sections passes tests. This plan makes the shared
+  behavior text a true constant.
+
+## Design: prompt cores and envelopes
+
+A **prompt core** is a constant string in `src/prompts.ts` holding the
+host-agnostic instruction body for one behavior: which tools to call, in what
+order, with what arguments, and what "done" looks like.
+
+An **envelope** wraps a core with delivery-specific framing:
+
+- The nudge envelope adds: escalation tier wording, the load-bearing
+  stop-and-wait ending (see "Extraction nudge stop-and-wait wording is
+  load-bearing" -- the stop-and-wait text is nudge-only and must NOT leak
+  into action envelopes, because an action IS user input), and the
+  "system nudge, not user input" disclaimer.
+- The action envelope adds: frontmatter description, the `# User Message`
+  section with `$ARGUMENTS`, and any greenlight-token mechanics (wrap-up
+  commands only).
+
+Cores are plain string constants, not template functions, so both envelopes
+interpolate them identically. Where a core needs host-specific tool names
+(`thatch_memory_remember` vs `mcp__thatch__memory_remember`), the core takes
+the opencode spelling and MCP consumers apply the documented token
+substitution, matching the existing systemPrompt/mcpInstructions convention.
+
+## Actions v1
+
+| Command | Core behavior | Existing machinery |
+|---|---|---|
+| `/thatch/defrag` | Run `thatch_find_duplicates`, classify each pair with the thatch-dedup-classifier skill, consolidate (remember/overwrite or forget), mark pairs checked | find_duplicates + dedup classifier skill |
+| `/thatch/extract` | Fetch the extraction payload, run the fact-extractor skill, call `extraction_done` | get_extraction_payload + fact-extractor skill |
+| `/thatch/hygiene` | Run the hygiene report, act on stale and orphaned branch-scoped memories | `hygieneReport()` + `/thatch hygiene` CLI |
+| `/thatch/reflect` | Run the session-reflection skill over the current session | thatch-session-reflection skill |
+
+The wrap-up commands (`compact`, `exit`) stay as-is; their checklist text
+becomes a core reused by both templates (already true via `sharedChecklist`).
+
+## Host parity
+
+Commands are markdown or MCP prompts, synced per host. Behavior parity is the
+goal; format differences are documented, not hidden.
+
+- **opencode** (existing): `installOpencodeCommands` syncs markdown to
+  `~/.config/opencode/command/thatch/` on every plugin load.
+- **Claude Code**: native user-level slash commands read markdown from
+  `~/.claude/commands/thatch/` with the same `$ARGUMENTS` substitution.
+  `thatch setup --claude` gains a sync step (idempotent content-compare, same
+  as the opencode installer). Differences: no plugin, so no
+  `command.execute.before` arming -- greenlight-token wrap-up commands do not
+  ship to Claude Code; and tool names use the `mcp__thatch__` prefix.
+- **Cursor**: no file-based commands. The stdio MCP server (`mcp.ts`) gains
+  MCP Prompts support (`prompts/list`, `prompts/get`), which Cursor surfaces
+  as slash commands. Prompt arguments use MCP's
+  `{{argument}}`-style templating, so each action core gets an MCP-prompt
+  rendering alongside the markdown rendering.
+
+README gains "What works in Claude Code" and "What works in Cursor" sections
+listing per-host support without restating the shared docs.
+
+## Session ID plumbing
+
+`get_extraction_payload` and `extraction_done` take `session_id`. Today the
+nudge carries the ID; an action has no way to know it.
+
+- opencode path: the thin wrappers in `tools.ts` receive the invoking
+  session's ID from the host. `session_id` becomes optional there; omitted
+  means "the current session."
+- MCP path: there is no session context in a tool call, so `session_id`
+  stays required. The tool description and docs state this plainly.
+
+The rule the LLM must apply, stated everywhere the tools are described:
+
+> 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 that was
+> dispatched to process another session's extraction queue.
+
+This rule appears in: the tool descriptions in `tool-defs.ts`, the extraction
+prompt core (used by both nudge and action envelopes), the fact-extractor
+skill, and the dev docs. Tests cover both paths: omit-resolves-to-current and
+explicit-parent-ID (the existing sub-agent drain bug's regression path).
+
+## Decisions
+
+- Prompt cores live in `src/prompts.ts`, not a new module; `commands.ts`
+  imports them. One prompt module, consistent with the existing module map.
+- Actions are generated, not hand-written: each action has one core and a
+  per-host renderer, so a wording change cannot drift between nudge and
+  command.
+- No `--dry-run` flag for defrag in v1; the dedup classifier skill already
+  asks for pair-by-pair verdicts, which is the interactive safety net.
+- MCP Prompts for Cursor are additive to `mcp.ts` and do not change the
+  tools/list contract.
+
+## Testing
+
+- `tests/commands.test.ts` (or the existing plugin tests): command-file
+  content assertions per host, including that each action's markdown contains
+  its core text verbatim.
+- MCP tests: `prompts/list` returns every action; `prompts/get` interpolates
+  arguments.
+- Plugin tests: `get_extraction_payload` without `session_id` resolves to the
+  invoking session; with an explicit parent ID, drains the parent's queue.
+- Parity guard: a test asserts every opencode command def has a
+  corresponding MCP prompt (and vice versa) except the documented exclusions
+  (wrap-up greenlight commands on non-opencode hosts).
+
+## Docs
+
+- `docs/dev/commands.md` (two-tier: dev doc + user-facing README section):
+  action list, host parity matrix, session ID rule.
+- README: "What works in Claude Code" / "What works in Cursor" sections.
+- QA use cases: one auto use case for `/thatch/defrag` end-to-end, one for
+  `/thatch/extract` with omitted session ID.

package/docs/user/README.md

@@ -190,8 +190,8 @@ requirements.
 
 | 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_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 pool name 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 grouped into Active and Stale sections (stale = two missed heartbeats, about a minute; its host process has probably stopped), with how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its 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. |
@@ -232,6 +232,21 @@ Beyond the tools, thatch hooks into opencode itself:
   notification (`[thatch] recalled 3 memories`, `[thatch] 2 predictions
   surfaced`, or `[thatch] 1 behavior surfaced`). The toast is ephemeral. It
   fades after a few seconds.
+- **Wrap-up commands.** `/thatch/compact` and `/thatch/exit` (opencode only)
+  run a pre-flight checklist before you compact or close a session: the agent
+  flushes pending fact extraction, finishes any promised memory writes, and
+  surfaces todos or follow-ups it never addressed. The agent ends its
+  response with a greenlight token only when the checklist is clean. Thatch
+  watches for the token and then runs the compaction or exits opencode.
+  Without the token nothing fires -- a toast points you at the items the
+  agent listed, and you re-run the command once they're handled. Text typed
+  after the command reaches the agent first, labeled as a `User Message`
+  section ahead of the checklist (say goodbye or hand off context:
+  `/thatch/exit Good work - see you tomorrow`).
+  A greenlit `/thatch/exit` also unregisters the session from the chat
+  directory, so other sessions stop sending it mail. The commands
+  self-install into `~/.config/opencode/command/thatch/` at plugin startup;
+  a first install becomes available after the next opencode start.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
 - **Prediction auto-fire.** When a prompt matches learned contexts, thatch
@@ -314,6 +329,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
+| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression. |
 
 ### opencode-only skills
 
@@ -430,6 +446,7 @@ Most configuration needs none. Two layers exist:
 | `THATCH_DB_PATH` | `$XDG_CONFIG_HOME/thatch/thatch.db` | Override database location (the config file follows it) |
 | `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Override embedding model |
 | `THATCH_EMBEDDING_BACKEND` | `wasm` | Set to `native` to run embeddings on onnxruntime-node (NAPI) instead of the wasm runtime |
+| `THATCH_DEBUG` | unset (off) | Diagnostic logging to `debug.log` beside the database. `1` logs everything; or a comma-separated list of tags, e.g. `chat` or `chat:startup` |
 
 Unchanged defaults: the database is created automatically, the embedding
 model downloads once and is cached, the store name is auto-detected from

package/docs/user/cli.md

@@ -46,7 +46,7 @@ Read-only access to the chat directory your opencode sessions share
 
 ```bash
 thatch chat list               # who is registered: name, age, project, topic
-thatch chat tail               # follow sent and read events, live
+thatch chat tail               # follow sent and read events, live (JSONL)
 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
@@ -54,41 +54,41 @@ 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:
+`chat list` shows every registered session in two sections, Active and
+Stale, each as aligned columns under a header row: how long since its
+last heartbeat, its status (`fresh` or `stale` for opencode sessions;
+`active` or `idle` for Claude Code and Cursor sessions, which only beat
+when a prompt runs), its project, and its topic (the session's title) -
+the fastest way to answer "which session should I talk to about X?" A
+stale session has missed two heartbeats, about a minute: the opencode
+process hosting it has probably stopped. Color is added only when the
+output is a terminal; a pipe prints plain aligned text.
+
+`chat tail` prints the conversation as a JSONL event log: one JSON
+object per line, one event per line. Sending a message and reading it
+are separate events, linked by the message `id`. Every field is plain
+data: names as registered, each participant's topic, the message body
+exactly as sent, and ISO-8601 UTC timestamps. No color, no markdown
+rendering, no local time; pipe through `jq` for either.
 
 ```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
-____________________________________________________________
+{"event":"sent","at":"2026-09-12T20:02:11Z","id":41,"from":"al-go-rithm-00001","from_topic":"cross-session messaging","to":"brute-the-dream-farrier-00001","to_topic":"diagnosing watcher underuse","broadcast":false,"body":"CI is green on main"}
+{"event":"read","at":"2026-09-12T20:02:40Z","id":41,"reader":"brute-the-dream-farrier-00001","reader_topic":"diagnosing watcher underuse","from":"al-go-rithm-00001","from_topic":"cross-session messaging"}
+{"event":"sent","at":"2026-09-13T03:07:02Z","id":42,"from":"al-go-rithm-00001","from_topic":"cross-session messaging","to":"kurn-the-typechecker-00001","to_topic":"release QA","broadcast":true,"body":"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
+A broadcast is one `sent` event per recipient, each with `broadcast:
+true` and its real `to`, so every copy tracks its own read. Handy
+one-liners:
 
-direct ping
+```bash
+thatch chat tail | jq -r '"\(.at) \(.event) \(.from) -> \(.to // .reader): \(.body // "")"'
+thatch chat tail --once --limit all | jq -c 'select(.event == "read")'
 ```
 
-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
+Follow mode runs until Ctrl-C. The backlog includes the `read` event of
+every message already read; in follow mode, reads appear as inboxes
+drain. 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).
 
@@ -102,10 +102,8 @@ too, so a filtered tail keeps watching the same way:
   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.
+  rendering the tail shows. Broadcast events carry their real recipient,
+  so `--to <name>` finds the fan-out copies that reached them.
 - `--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
@@ -113,9 +111,9 @@ too, so a filtered tail keeps watching the same way:
 
 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.
+the window closes. In the backlog, a hidden message's read is hidden
+with it; in follow mode, a hidden message that gets read still emits
+its read event.
 
 ## Priming a new project
 

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

@@ -1,6 +1,7 @@
 # Cross-Session Chat
 
-Cross-session chat lets your opencode sessions talk to each other. If one
+Cross-session chat lets your agent sessions talk to each other, in
+opencode, Claude Code, and Cursor. 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.
@@ -8,9 +9,9 @@ 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
+moment. Names are assigned by thatch, never chosen: a name drawn from a
+built-in pool plus a counter (`al-go-rithm-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
@@ -19,11 +20,14 @@ 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_list` shows every registered session on the machine, grouped
+  into Active and Stale sections: active sessions can be woken; stale ones
+  have missed two heartbeats, about a minute (the opencode process hosting
+  them has probably stopped). Each row carries how long ago the session last
+  checked in, its project, whether it runs in the project root or a linked
+  git worktree, its topic, and your unread count
 - `thatch_chat_send` delivers a message to another registered session, by
-  name or session id
+  name or session id, and states the recipient's liveness at send time
 - `thatch_chat_read` drains the session's inbox
 - `thatch_chat_broadcast` delivers one message to every other live
   registered session at once
@@ -55,8 +59,12 @@ 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:
+With auto-registration you usually do nothing: a session joins the
+directory when it first goes idle, and a session continued with
+`opencode -s <id>` is registered again the moment its harness starts -
+same session id, same name, reclaimed. The agent gets a quiet toast with
+its assigned name when it first registers. To introduce two sessions,
+just tell each one who to talk to:
 
 > Ask the other session whether the release has shipped; answer its
 > questions directly.
@@ -71,13 +79,68 @@ 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.
 
+## Claude Code and Cursor
+
+Chat works from Claude Code and Cursor through the same MCP server and the
+same shared directory. The seven tools are identical on every host; two
+things differ.
+
+**Identity comes from the hook.** Claude Code and Cursor pass no session
+context to MCP tool calls, so the thatch hook anchors identity instead. It
+registers the conversation under a stable id derived from the host's
+session id, and prints `you are NAME (unread count)` at session start and
+on every prompt. The model passes that name as the `as` argument on the
+chat tools. Without the hook (MCP registered by hand, hooks removed), the
+model can still join: `chat_register` with no arguments mints a fresh
+identity for the conversation, and the model uses the returned name from
+there. That identity does not survive a compacted context - re-register
+then, or prefer the hooked path.
+
+**Delivery model.** Only opencode can start a turn when mail arrives
+while you are away. The other hosts surface mail at their hook points,
+and both wake the agent when a turn ends:
+
+- **Cursor** checks the mailbox when a turn ends (the `stop` hook): unread
+  mail is auto-submitted as a follow-up message, so the agent reads it
+  without you typing anything. The notification is a pointer (sender
+  names + count, never message bodies); bodies flow only through the
+  framed `chat_read`. A loop cap bounds consecutive follow-ups, and an
+  aborted or errored turn is never auto-continued.
+- **Claude Code** also checks at turn end (the `Stop` hook): unread mail
+  arrives as a Stop-hook reminder and the turn continues so the agent
+  reads it. The host's own loop protections plus the delivered stamp
+  bound repeats, and a session paused on background work is not
+  interrupted - the wake lands when that work's turn ends. Mail is also
+  announced at startup and resume (the `SessionStart` hook line) and at
+  every prompt; if an answer is urgent, say so to the agent directly.
+
+Two limits worth knowing:
+
+- Cursor cloud agents run no client-side hooks: no identity anchor, no
+  mail lines. The MCP tools still work, with a self-registered identity.
+- A conversation idle past the prune window (a week) re-registers under a
+  fresh name; mail addressed to the old name is swept.
+
+The terminal view ([cli.md](cli.md)) works the same regardless of which
+host the sessions run in.
+
 ## 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.
+A session shows as fresh while the opencode process hosting it is
+running: hosted sessions keep beating (idle ones included), so the
+freshness is real. When that process dies, its sessions stop beating and
+show as stale about a minute later (two missed heartbeats), grouped into
+a separate Stale section. A laptop that slept reads the same way until
+its processes catch up.
+Messages to a stale session wait in its inbox unread - a dead session
+never reads them, and `chat_send` says so at send time. Continuing a
+session with `opencode -s <id>` reclaims its name and row, and any mail
+that queued while it was down is delivered at startup. Explicitly
+closing a session (deleting it in the TUI) unregisters it immediately,
+and a greenlit `/thatch/exit` unregisters the session too: the wrap-up
+checklist calls `chat_unregister`, and the plugin removes the row itself
+when the exit token passes the greenlight check, so other sessions stop
+addressing mail to a process that is about to vanish.
 
 ## Turning chat off
 
@@ -127,16 +190,26 @@ construction. Three mitigations:
 - **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.
+- **Claude Code identity is anchored by the host process.** Hooks learn
+  the true session id from the host and record which process spawned them;
+  the MCP server resolves its own parent process against that record, so
+  the model cannot claim another session's identity there. On Cursor, chat
+  tools still trust the `as` argument the caller supplies (hooks and MCP
+  servers share one workspace process, so process identity is ambiguous) -
+  a local session that knows a name can act as it. opencode is immune (the
+  host supplies identity). The threat model is one user's machine.
 - **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`).
+- **Idle wake (starting a turn with nobody at the keyboard) is opencode
+  only.** The chat tools work everywhere (other hosts declare their
+  identity with `as`). Cursor and Claude Code additionally wake the agent
+  when a turn ends with mail unread (the `stop`/`Stop` hooks); Claude
+  Code also announces mail at startup and resume, and both see pending
+  mail at prompt time (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.

package/docs/user/skills.md

@@ -68,6 +68,7 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis for scanning. |
 | `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections and bold/italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
+| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression. |
 
 ### Workflow skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/chat-names.ts

@@ -9,8 +9,8 @@
  * unnamed-cast extras). fnord generates its names with an LLM at runtime;
  * thatch bakes the pool in - static contents, no model call.
  *
- * The pool is the fallback base for registrations with no usable session
- * title (ChatStore.register slugifies a random pool name). Pool names are
+ * The pool is the base for every registration (ChatStore.register
+ * slugifies a random pool name and appends a counter). Pool names are
  * case-insensitively distinct from each other; slugify is lossy, but a
  * shared base is harmless - the per-base counter still yields unique
  * names.