@jeffober/thatch 0.1.38 → 0.1.40

package/docs/dev/features/prediction-engine.md

@@ -85,9 +85,12 @@ Runs in a single DB transaction:
 
 1. **Matcher dedup** — finds an existing matcher above cosine 0.85, else
    creates one.
-2. **Prediction dedup** — store-wide search for a near-identical prediction
-   (cosine >= 0.85). If found, links this matcher to it via an edge rather than
-   creating a duplicate row.
+2. **Prediction dedup** — search across the target store AND global for a
+   near-identical prediction (cosine >= 0.85). If found, links this matcher to
+   it via an edge rather than creating a duplicate row. The auto-fire nudge
+   scans both stores, so a prediction saved to both would otherwise surface
+   twice every turn; the write reinforces the existing row in its home store
+   and the result echoes where it landed.
 3. **New prediction with a non-create signal** — applies the signal
    immediately so the first confirm/disconfirm is not lost.
 4. **`create` on an existing prediction** — links the edge and records

package/docs/dev/features/qa-system.md

@@ -1,14 +1,13 @@
 # QA System
 
-Thatch ships 95 QA use cases that verify end-to-end behavior. Each use case is
-a `bun:test` file that runs in an isolated environment — a temp-directory copy
-of the repo, not the working tree itself. Use cases are split into
-**automatable** (no LLM, fast) and **live** (spawns opencode, costs model
-tokens).
+Thatch ships a suite of QA use cases that verify end-to-end behavior. Each use
+case is a `bun:test` file that runs in an isolated environment — a
+temp-directory copy of the repo, not the working tree itself. Use cases are
+split into **automatable** (no LLM, fast) and **live** (spawns opencode, costs
+model tokens).
 
 ## What it does
 
-- 95 use cases: 75 automatable + 20 live
 - Automatable use cases run without an LLM — they test CLI behavior, hooks, DB
   operations, and tool execution directly via bun assertions
 - Live use cases spawn real opencode sessions — they test the full
@@ -39,7 +38,7 @@ registers all use cases in one suite, enabling `--concurrent
 --max-concurrency 5` to run 5 use cases at once (33s vs 88s sequential for the
 auto suite).
 
-### Automatable use cases (73)
+### Automatable use cases
 
 Run without an LLM. Test CLI behavior, hooks, DB operations, and tool
 execution directly via bun assertions. These are fast and run in parallel.
@@ -66,14 +65,15 @@ execution directly via bun assertions. These are fast and run in parallel.
 | UC-027 | behavior-confidence-model | ham/spam adjusts Bayesian confidence |
 | UC-028 | behavior-delete | semantic-match deletion with cascade |
 
-### Live use cases (20)
+### Live use cases
 
 Spawn real opencode sessions. Test the full pipeline with a real model. These
-cost model tokens and have a 20-minute per-use-case timeout. All 20 are marked
-`manualOnly: true` — the opencode binary is not available in CI, and three
-(UC-006, UC-010, UC-013) are manual-only for fundamental reasons (Cursor hook
-lifecycle, nested opencode session timeout, compaction trigger). Run them
-locally with `mise run qa-live`.
+cost model tokens and have a 20-minute per-use-case timeout. Live use cases
+check for `opencode` on PATH at runtime: if it is present they run; if not,
+they skip with `[MANUAL]`. Three (UC-006, UC-010, UC-013) are
+`manualOnly: true` for infrastructure reasons (Cursor hook lifecycle, nested
+opencode session timeout, compaction trigger). Run them locally with
+`mise run qa-live`.
 
 | UC | Name | What it tests |
 |----|------|---------------|
@@ -182,8 +182,8 @@ includes all of `tests/`), just not executed during `check`. See
 | `tests/qa/runner.ts` | `registerUseCase`, `UseCase` type, `ensureMaster`, `createFixture`, `runViaOpencode`, execution logic |
 | `tests/qa/auto/index.test.ts` | Automatable use case barrel — imports all auto use case modules |
 | `tests/qa/live/index.test.ts` | Live use case barrel — imports all live use case modules |
-| `tests/qa/auto/uc-NNN-*.ts` | 75 automatable use case files |
-| `tests/qa/live/uc-NNN-*.ts` | 20 live use case files |
+| `tests/qa/auto/uc-NNN-*.ts` | Automatable use case files, one per use case |
+| `tests/qa/live/uc-NNN-*.ts` | Live use case files, one per use case |
 
 No separate QA docs directory exists. QA use cases live in `tests/qa/` as executable tests, not docs.
 
@@ -191,8 +191,9 @@ No separate QA docs directory exists. QA use cases live in `tests/qa/` as execut
 
 1. **Automatable use cases never spawn an LLM.** They test CLI, hooks, DB, and
    tool execution directly.
-2. **Live use cases spawn real opencode sessions and cost model tokens.** All
-   20 are marked `manualOnly` — the opencode binary is not available in CI.
+2. **Live use cases spawn real opencode sessions and cost model tokens.** They
+   skip with `[MANUAL]` when `opencode` is not on PATH; three are
+   `manualOnly: true` for infrastructure reasons.
 3. **`QA_DRY_RUN=1` lists use cases without executing.** Use this for CI and
    coverage review.
 4. **Each use case follows the structured format**: preconditions, steps,

package/docs/dev/gotchas.md

@@ -146,3 +146,21 @@ here first. These are the things that have already cost time.
 - **`bun test` does not typecheck**, and `tsconfig.json` excludes `tests`. Test
   type errors are editor-only noise unless you run `tsc` on the test files
   directly. Keep test files type-clean anyway so the editor stays quiet.
+
+## Config and notifications
+
+- **Tests touching the config must set `THATCH_DB_PATH`.** The config tools
+  derive the config file path from the environment (`THATCH_DB_PATH`, then the
+  XDG default), not from the test's tempdir `ThatchDB`. A config test that
+  skips this reads and writes the developer's real
+  `~/.config/thatch/config.json`. See `tests/notify.test.ts` for the
+  save-and-restore pattern.
+- **osascript exits 0 even when macOS drops the banner.** Focus/Do Not Disturb
+  or missing notification permission silently swallow it. `notify_user` result
+  text therefore reports command success only; never interpret exit 0 as
+  delivery.
+- **New QA use cases must be imported into the directory's barrel file**
+  (`tests/qa/auto/index.test.ts` or the live one). The `.ts` files are not
+  discovered by bun on their own. UC-095 sat out of the suite for a release
+  cycle and rotted (asserted 3 watch tools when 4 existed) because nobody
+  noticed it never ran.

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** (18 shared + 7 opencode-only, 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 18 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 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 |
 | **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 |

package/docs/dev/skills.md

@@ -29,9 +29,9 @@ description: Extract durable project facts ... Use when ...
   Code, and Cursor all auto-discover skills and use the description for
   relevance).
 
-## The 26 skills
+## The skills
 
-**Shared (25)** — installed everywhere; no sub-agents required:
+**Shared** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -46,6 +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-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`. |
@@ -61,11 +62,11 @@ description: Extract durable project facts ... Use when ...
 | `thatch-memory-verify` | Fact-check a single memory against the current codebase and correct stale claims. Uses git archaeology to preserve historical context when changes were intentional. |
 | `thatch-knowledge-export` | Compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories via `thatch-memory-verify`. |
 
-**opencode-only (1)** — the coordinator needs sub-agent support:
+**opencode-only** — the coordinator needs sub-agent support:
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 8 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
+| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the review specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
 
 ## REVIEW_COMMON
 
@@ -92,6 +93,8 @@ The seven problem-finding review specialists share a framework interpolated via
   ticket is closed or merged.
 - **Output format** — `[SEVERITY] [CATEGORY] file:line` with finding, evidence
   (quoted), trigger, reachability, source of truth, producer chain, provenance.
+- **Wording** — findings are prose for humans, not shorthand: one idea per
+  sentence, no method names as verbs, one sentence per hop for producer chains.
 
 The synthesizer reuses the same verification rigor but has its own structure
 (it does not interpolate `REVIEW_COMMON`).
@@ -99,7 +102,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 26 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* all shared skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -138,7 +141,7 @@ and `--cursor` pass only the shared set.
 ## Memory review skills in practice
 
 - **Quick single lens**: load any specialist directly and point it at a branch.
-- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 8 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
+- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all review specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
 - **Full review on Claude Code/Cursor**: run each specialist in sequence, then
   run `thatch-review-synthesizer` to verify and aggregate.
 - **Follow-up round (re-review)**: load `thatch-review-followup` when the author

package/docs/user/README.md

@@ -12,6 +12,7 @@ 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)
+- [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
 - [default-behaviors.md](default-behaviors.md): what ships automatically
@@ -143,6 +144,22 @@ Stores are created automatically. No setup required.
 | `thatch_behavior_list` | List all codified behaviors with matchers, confidence, and provenance. |
 | `thatch_behavior_delete` | Delete a behavior by semantic match. Edges and provenance are cascade-deleted. |
 
+### Config tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_config_get` | Read the user config (`~/.config/thatch/config.json`), with defaults annotated. The agent manages config through these tools; you can also edit the file by hand. |
+| `thatch_config_set` | Update config fields. Field-level merge: only fields you pass change. Returns the resulting section so the agent can verify. |
+
+### Notification tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_notify_user` | Notify the user out-of-band: desktop banner and/or spoken voice. Use for long-running outcomes worth interrupting for (CI results, deploys, watcher events). macOS and Linux. |
+
+See [notifications.md](notifications.md) for the full behavior and
+configuration.
+
 ### Session tools (opencode only)
 
 | Tool | What it does |
@@ -159,7 +176,8 @@ search` - JSONL output designed for piping to `jq` or `grep`.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
+| `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_list` | List this session's active watchers. |
 | `thatch_watch_cancel` | Cancel one of this session's watchers by id. |
 
@@ -260,6 +278,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-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`. |
@@ -287,14 +306,14 @@ response, walkthrough, and workflow skills that support the review pipeline:
 
 | Skill | opencode | Claude Code | Cursor |
 |-------|----------|-------------|--------|
-| Memory skills (6) | Yes | Yes | Yes |
-| Review specialists (8) | Yes | Yes | Yes |
+| Memory skills | Yes | Yes | Yes |
+| Review specialists | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
 | Review context + code archaeology | Yes | Yes | Yes |
 | Review followup | Yes | Yes | Yes |
 | Review response (author-side) | Yes | Yes | Yes |
-| Walkthrough skills (2) | Yes | Yes | Yes |
-| Writing skills (3) | Yes | Yes | Yes |
+| Walkthrough skills | Yes | Yes | Yes |
+| Writing skills | Yes | Yes | Yes |
 | Code review coordinator | Yes | No (requires sub-agents) | No (requires sub-agents) |
 
 ### Using review skills
@@ -379,19 +398,24 @@ Store defaults to your current git repo.
 
 ## Configuration
 
-No configuration needed. The default behavior:
+Most configuration needs none. Two layers exist:
 
-- **Database**: `~/.config/thatch/thatch.db` (created automatically)
-- **Embedding model**: bge-small-en-v1.5 (downloaded once, cached locally)
-- **Store name**: auto-detected from `git remote get-url origin`
-- **Search scope**: always includes the project store and `global`
-
-### Environment variables
+- **Preferences the agent manages** live in
+  `~/.config/thatch/config.json` (beside the database): notification mode,
+  voice, and sound. Ask your agent ("set notifications to banner only") or
+  edit the file by hand. See [notifications.md](notifications.md).
+- **Environment variables** for infrastructure:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `THATCH_DB_PATH` | `$XDG_CONFIG_HOME/thatch/thatch.db` | Override database location |
+| `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 |
+
+Unchanged defaults: the database is created automatically, the embedding
+model downloads once and is cached, the store name is auto-detected from
+`git remote get-url origin`, and search always includes the project store
+and `global`.
 
 `$XDG_CONFIG_HOME` defaults to `~/.config` when unset.
 

package/docs/user/code-review.md

@@ -1,6 +1,6 @@
 # Code Review
 
-Thatch ships a multi-agent code review pipeline. Eight specialist
+Thatch ships a multi-agent code review pipeline. Nine specialist
 review lenses run in parallel, then a synthesizer verifies and
 deduplicates their findings into a single report.
 
@@ -22,7 +22,7 @@ the review:
 3. **Research affected workflows**: load `thatch-code-archaeology`,
    trace the code paths the change touches.
 4. **Estimate complexity**: partition the diff into review units.
-5. **Dispatch specialists**: fan out the eight specialists as
+5. **Dispatch specialists**: fan out the nine specialists as
    parallel sub-agents, each with the context brief.
 6. **Synthesize**: the synthesizer reads all specialist output,
    verifies each finding (cited text exists, claim is accurate,
@@ -31,7 +31,7 @@ the review:
    re-verifies behavioral findings against current main and reports
    merge-base-only findings as rebase notes rather than defects.
 
-## The eight specialists
+## The nine specialists
 
 | Skill | What it checks |
 |-------|-------------|
@@ -43,6 +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. |
 
 Each specialist is a self-contained static-analysis pass. They can run
 individually or as part of the coordinated review.

package/docs/user/memory.md

@@ -49,6 +49,9 @@ store when recalling.
   (MCP).
 - `THATCH_MODEL`: Hugging Face model name for embeddings. Defaults to
   `Xenova/bge-small-en-v1.5` (34 MB, 384-dimensional).
+- `THATCH_EMBEDDING_BACKEND`: embedding compute backend. Defaults to
+  `wasm` (pure JavaScript/WebAssembly, no native addons). Set to
+  `native` to use the onnxruntime-node addon instead.
 - `THATCH_RECALL_THRESHOLD`: cosine score threshold for the recall
   nudge. Defaults to 0.55. Lower surfaces more matches (noisier);
   higher surfaces fewer (stricter).

package/docs/user/notifications.md

@@ -0,0 +1,84 @@
+# Notifications
+
+Thatch can notify you out-of-band when something happens worth leaving the
+terminal for: a CI run finishing, a merge or deploy completing, a watched PR
+receiving a comment. The notification is a desktop banner, a spoken voice
+announcement, or both, depending on your preferences.
+
+This works on every host (opencode, Claude Code, Cursor) because it is plain
+child processes, not host plumbing.
+
+## The tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_notify_user` | Send a banner and/or spoken notification. |
+| `thatch_config_get` | Read the current config, with defaults annotated. |
+| `thatch_config_set` | Update config fields. Returns the resulting section. |
+
+### notify_user
+
+```text
+thatch_notify_user(message: "CI is green, clear for merge",
+                   source: "PLAT-280")
+```
+
+- **macOS**: banner via Notification Center (with an alert sound) and voice
+  via the built-in `say` command.
+- **Linux**: banner via `notify-send` (libnotify) and voice via
+  `spd-say`/`espeak` when installed. Missing tools are reported, never fatal.
+- **Windows**: not supported. The tool reports this instead of guessing.
+
+The agent includes a `source` label (a ticket number or feature name) so you
+know which of your concurrent sessions is speaking. Voice text spells out
+letter sequences ("C I green", not "CI green") so text-to-speech pronounces
+them.
+
+The tool result reports command success only. macOS focus modes can silently
+swallow banners; if you are not seeing them, check Focus settings and that
+your terminal app has notification permission.
+
+## Configuring notifications
+
+You have two options, and they edit the same file:
+
+1. **Ask your agent.** "Set notifications to banner only" -- the agent reads
+   current values with `config_get`, changes what you asked for with
+   `config_set`, and shows you the result.
+2. **Edit the file yourself.** The config lives at
+   `~/.config/thatch/config.json` (next to `thatch.db`, or under
+   `$XDG_CONFIG_HOME`).
+
+```json
+{
+  "notifications": {
+    "mode": "both",
+    "voice": "Zarvox",
+    "sound": "Submarine"
+  }
+}
+```
+
+| Field | Values | Default | Applies to |
+|-------|--------|---------|------------|
+| `mode` | `both`, `banner`, `voice`, `none` | `both` | Which channels `notify_user` uses. `none` disables notifications entirely; the agent is told it no-opped. |
+| `voice` | any installed voice name | `Zarvox` (macOS) | Spoken announcements. List macOS voices with `/usr/bin/say -v '?'`. |
+| `sound` | any system sound name | `Submarine` (macOS) | Banner alert sound. Sounds live in `/System/Library/Sounds`. |
+
+Fields you leave out fall back to the defaults. Unknown sections or fields
+are rejected when the file is read, and the config is ignored with a warning
+if it cannot be parsed -- a broken hand edit never crashes the agent, it just
+falls back to defaults.
+
+The agent can manage the whole file for you through `config_get` /
+`config_set`; edits merge at the field level, so the agent changing your
+voice cannot wipe your mode.
+
+## Limitations
+
+- Banners are best-effort by nature of the OS. The agent can only report
+  whether the command ran, not whether you saw the banner.
+- Speech is awaited: the tool returns after the sentence finishes. Notifications
+  are short by design.
+- There is no debounce. If an agent polls a status in a tight loop, it should
+  notify once at the end, not per poll.

package/docs/user/setup.md

@@ -75,6 +75,7 @@ and `--json` output for hook commands.
 |----------|---------|-----------------|
 | `THATCH_DB_PATH` | `~/.config/thatch/thatch.db` | SQLite database path |
 | `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Hugging Face model name for embeddings |
+| `THATCH_EMBEDDING_BACKEND` | `wasm` | Set to `native` to run embeddings on onnxruntime-node (NAPI) instead of the wasm runtime |
 | `THATCH_RECALL_THRESHOLD` | `0.55` | Cosine threshold for recall nudge |
 | `THATCH_PREDICTION_THRESHOLD` | `0.60` | Cosine threshold for prediction auto-fire |
 | `THATCH_BEHAVIOR_THRESHOLD` | `0.60` | Cosine threshold for behavior auto-fire |
@@ -101,8 +102,9 @@ instructions are deployed without requiring you to manually re-run
   cached in `node_modules/@huggingface/transformers/.cache/`.
 - There is no web UI or dashboard. All interaction is through the
   agent's tool calls and the `thatch` CLI.
-- The MCP server is a long-lived process that holds the warm embedding
-  model in memory. Hook commands connect to it via a Unix domain
+- The MCP server is a long-lived process that keeps the embedding model
+  loaded while it is in use, releases it after 10 idle minutes, and
+  re-loads it on demand. Hook commands connect to it via a Unix domain
   socket (the sideband) to avoid loading the model themselves.
 
 See [memory.md](memory.md) for the memory system,

package/docs/user/skills.md

@@ -20,7 +20,7 @@ becomes part of the agent's context.
 
 ## What ships
 
-26 skills total (25 shared, 1 opencode-only):
+Skills are split into shared (all hosts) and opencode-only:
 
 ### Memory skills
 
@@ -45,6 +45,7 @@ becomes part of the agent's context.
 | `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. |
+| `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-synthesizer` | Verifies and synthesizes findings from multiple specialists into a deduplicated, severity-grouped report. |
 | `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work) 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. The research skill; pair with `thatch-coding-workflow`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "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",
@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.0.0",
+    "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
     "zod": "^4.1.0"
   },
   "devDependencies": {

package/src/behavior.ts

@@ -82,7 +82,7 @@ export class BehaviorEngine {
     return this.#engine.createMatcher(store, description, embedding, model);
   }
 
-  findNearestBehavior(store: string, embedding: Float32Array, threshold: number): BehaviorRow | null {
+  findNearestBehavior(store: string | string[], embedding: Float32Array, threshold: number): BehaviorRow | null {
     return this.#engine.findNearestItem(store, embedding, threshold) as BehaviorRow | null;
   }
 

package/src/config.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+// Thatch user config: one JSON file beside thatch.db, hand-editable and
+// managed by the config_get / config_set tools. Sections are strict (unknown
+// keys fail validation instead of being silently dropped) so a hand edit or a
+// newer-version file can never lose data by round-tripping through an older
+// process. config_set merges at the field level: omitted fields keep their
+// values, so a partial section update never wipes sibling preferences.
+
+export const notificationPrefsSchema = z.strictObject({
+  mode: z.enum(["both", "banner", "voice", "none"]).optional(),
+  voice: z.string().optional(),
+  sound: z.string().optional(),
+});
+
+export const configSchema = z.strictObject({
+  notifications: notificationPrefsSchema.optional(),
+});
+
+export type NotificationPrefs = z.infer<typeof notificationPrefsSchema>;
+export type Config = z.infer<typeof configSchema>;
+
+/** Sections in presentation order. config_get / config_set iterate this. */
+export const CONFIG_SECTIONS = ["notifications"] as const;
+export type ConfigSection = (typeof CONFIG_SECTIONS)[number];
+
+/**
+ * Resolves the config file path. By convention it lives next to thatch.db,
+ * so a custom THATCH_DB_PATH moves the config with it. Tests pass an
+ * explicit dbPath to keep writes inside a tempdir.
+ */
+export function configFilePath(dbPath?: string): string {
+  if (dbPath) return join(dirname(dbPath), "config.json");
+  const dir = process.env.THATCH_DB_PATH
+    ? dirname(process.env.THATCH_DB_PATH)
+    : join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "thatch");
+  return join(dir, "config.json");
+}
+
+export interface LoadedConfig {
+  config: Config;
+  /** Non-null when the file exists but is unparseable; the file is ignored. */
+  warning: string | null;
+  path: string;
+}
+
+/** Reads the config file. A missing file is the empty config, not an error. */
+export function loadConfig(dbPath?: string): LoadedConfig {
+  const path = configFilePath(dbPath);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return { config: {}, warning: null, path };
+  }
+  try {
+    const parsed = configSchema.parse(JSON.parse(raw));
+    return { config: parsed, warning: null, path };
+  } catch (err) {
+    return {
+      config: {},
+      warning: `config file at ${path} is invalid and was ignored (${err instanceof Error ? err.message : String(err)})`,
+      path,
+    };
+  }
+}
+
+/**
+ * Writes the config atomically (temp file + rename) so a crash mid-write
+ * cannot leave a truncated file, and concurrent readers never see a partial
+ * document.
+ */
+export function saveConfig(config: Config, dbPath?: string): string {
+  const path = configFilePath(dbPath);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n");
+  renameSync(tmp, path);
+  return path;
+}
+
+/** Field-level merge for one section: omitted fields keep their values. */
+export function mergeNotificationPrefs(
+  current: NotificationPrefs | undefined,
+  patch: NotificationPrefs,
+): NotificationPrefs {
+  return { ...current, ...patch };
+}
+
+/**
+ * Platform fallbacks shown by config_get and applied by notify_user when the
+ * user has not set a preference. Only darwin has opinionated defaults; other
+ * platforms use their tools' own voices and sounds.
+ */
+export function notificationDefaults(): { mode: "both" | "banner" | "voice" | "none"; voice?: string; sound?: string } {
+  if (process.platform === "darwin") {
+    return { mode: "both", voice: "Zarvox", sound: "Submarine" };
+  }
+  return { mode: "both" };
+}

package/src/db.ts

@@ -612,7 +612,7 @@ export class ThatchDB {
     return this.#predictions.createMatcher(store, description, embedding, model);
   }
 
-  findNearestPrediction(store: string, embedding: Float32Array, threshold: number) {
+  findNearestPrediction(store: string | string[], embedding: Float32Array, threshold: number) {
     return this.#predictions.findNearestPrediction(store, embedding, threshold);
   }
 
@@ -672,7 +672,7 @@ export class ThatchDB {
     return this.#behaviors.createBehaviorMatcher(store, description, embedding, model);
   }
 
-  findNearestBehavior(store: string, embedding: Float32Array, threshold: number) {
+  findNearestBehavior(store: string | string[], embedding: Float32Array, threshold: number) {
     return this.#behaviors.findNearestBehavior(store, embedding, threshold);
   }