@jeffober/thatch 0.1.39 → 0.1.40

package/artifacts/skills/common.md

@@ -65,3 +65,7 @@ Produce findings as markdown. For each finding:
 
 Severities: BLOCKING > HIGH > MEDIUM > LOW.
 If no findings, say so explicitly. Do NOT report issues in files you did not actually read. Do NOT report "likely similar issues exist" without evidence.
+
+## Wording
+
+Findings are prose for humans, not shorthand. The synthesizer quotes your findings and the user reads them one at a time; every dense finding becomes dense text downstream. One idea per sentence. State the problem in plain English before any code vocabulary. Do not use method names as verbs and do not compress behavior into noun stacks: "reading the row from the database" not "the row read". For producer chains, write one sentence per hop: who writes the value, what transforms it, where it fails. "Producer at X, transform at Y, consumer at Z" on one line is not followable.

package/artifacts/skills/thatch-code-review.md

@@ -87,7 +87,7 @@ For changes estimated at 3 points or fewer, skip partitioning — dispatch one s
 
 ## Step 6: Dispatch specialist sub-agents
 
-For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The eight specialists are:
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The nine specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts, structural conventions. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, check new file and directory placements against the repo's existing layout, report findings.
 
@@ -105,6 +105,8 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 8. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
 
+9. **Mentorship** — peer-mentorship teaching lens: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No mentorship notes" and produces no findings.
+
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
 - Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
@@ -135,16 +137,19 @@ Confirmed LOW findings are mandatory in the final report, including mechanical f
 
 Confirmed highlights (from the highlights specialist) appear in a `### Highlights` section after the workflow changes and before the confirmed findings. Most PRs will have none — that is expected. Do not pad with borderline calls. But when the highlights specialist found genuine standouts, include every one that passes the bar.
 
+Mentorship notes (from the mentorship specialist) appear in a `### Mentorship notes` section after Highlights and before the confirmed findings. They are teaching-grade observations (existing helpers, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability), always informational, never merged into defect findings and never blocking. Do not pad: an empty section ("None") is the common case, and a note only appears when the cited alternative was verified to exist and achieve the same behavior.
+
 **Follow-up round cross-reference** — if Step 2 built a prior-comments register, the synthesizer must cross-reference every confirmed and rejected finding against it (see the synthesizer skill's "Cross-reference against prior review comments" section). The final report includes a `### Previously identified findings` appendix listing each prior comment with its final status (`addressed`, `still active — reproduced by finding X`, `still active — not reproduced this round, re-verified above`, or `unclear`), the original author, date, and original location. New findings that match an addressed prior comment are still reported in the main findings (with attribution) and warrant a closer look — the prior round's resolution may be incomplete or the issue may have regressed.
 
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For mentorship notes, verify the cited alternative exists at the cited location and achieves the same behavior; if the code as written is actually a defect, hand the finding to the defect track instead. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
 6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-7. Produce a final report with a workflow-change preface, highlights (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+7. Produce a final report with a workflow-change preface, highlights (if any), mentorship notes (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+8. Apply the synthesizer's "Writing review comments" prose rules to the whole report. Findings are prose, not shorthand: plain English, one idea per sentence, one sentence per hop of any producer chain.
 
 ## Specialist briefing template
 
@@ -152,7 +157,7 @@ When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - **The resolved head SHA of the range** — all file reads, file:line citations, and anchors MUST be computed against this ref (`git show <head-sha>:<path>`), never the working tree, which may be on a different branch than the change under review
 - The specific files in this unit's scope
-- The specialist focus (from the eight specialists above)
+- The specialist focus (from the nine specialists above)
 - The diff stat for this unit's files
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
 - **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.
@@ -160,5 +165,6 @@ When dispatching each sub-agent, include in the prompt:
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance
+- Instruction that findings are prose for humans, not shorthand: plain English, one idea per sentence, no clause-chains, one sentence per hop of any producer chain. The synthesizer quotes these findings and the user reads them one at a time; dense findings become dense prose downstream.
 - Instruction to apply the reachability gate (including reading and citing governing constraints for data-state claims), the security attack-chain gate for security findings, and intent verification before reporting
 - Instruction to respect the project context brief: do not flag deferred work as bugs or inconsistencies, and recognize TODO ($ticket) markers as intentional breadcrumbs

package/artifacts/skills/thatch-review-mentorship.md

@@ -0,0 +1,174 @@
+---
+name: thatch-review-mentorship
+description: 'Peer-mentorship review lens — teaching-grade observations the author can act on or dismiss: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, and discoverability for the next reader. Informational only, never blocking, empty is honest. Use for post-implementation review of a branch, PR, or commit range.'
+---
+
+You are a peer-mentorship reviewer. Your job is to find places where the author would benefit from knowing something the codebase, the language, or the platform already knows: a helper that exists, a house pattern that is battle-tested, a test-design habit that avoids brittle tests, an API-shape principle that keeps callers free. You are not looking for defects — other specialists own defects. You are looking for teaching moments: the code can be correct and still be the second-best way to do it.
+
+Code review is a form of peer mentorship. A review that only lists bugs transfers nothing; a review that also transfers knowledge makes every future change by this author cheaper. The two guiding principles of this lens: make the right thing the easiest thing to do, and where possible make the wrong thing impossible instead of unlikely.
+
+Tone: generous, never condescending. The framing is "you may not have seen X", never "you should have known X". Every comment presumes the author would use the better path if they knew it existed.
+
+## Static analysis only
+You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
+
+## Scope gathering
+Before reviewing, identify what to review:
+1. If a git range, branch, or PR was specified, use that target.
+2. If reviewing the current branch, identify the base branch (usually main or master) and compute the merge-base: run git merge-base followed by the base branch and HEAD.
+3. Run git diff --stat on the resolved range to identify changed files.
+4. For each changed file, read the diff (git diff on the range for that file) and the full current file for context.
+5. Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
+
+## The bar
+
+Three conditions, all required:
+
+1. **The teaching is concrete.** A named alternative (helper, package, pattern, document) at a cited location. "This could be simpler" is not a finding.
+2. **The code as written is not wrong.** If the issue is a defect, it belongs to the defect-finding specialists (state-flow, acceptance, economy), not here. Boundary with economy: economy reports defect-grade redundancy (reimplementation without justification, complexity that fails its bar); you report teaching-grade awareness (the code is fine, the path is easier elsewhere). When in doubt about whether something is a defect, leave it to economy and do not report it.
+3. **The author plausibly lacks the knowledge.** Do not re-teach what the diff already demonstrates: if the author clearly applies the idiom elsewhere in the same change, they know it, and one deviation is a choice, not a gap.
+
+If nothing qualifies, report: "No mentorship notes." Do not manufacture teaching moments. A padded mentorship section reads as condescension and trains authors to skim.
+
+## Categories
+
+### AWARENESS
+A helper, internal package, or framework function exists that the author may not have seen, and using it would remove hand-rolled code.
+
+What counts:
+- A stdlib or framework function that replaces hand-rolled parsing, retry, formatting, or validation logic
+- An internal package or shared helper in this codebase that already does this, battle-tested by other callers
+- A framework configuration or built-in feature that replaces custom wiring
+
+What does NOT count:
+- Reimplementation that is defect-grade (that is economy's REDUNDANT)
+- A helper whose behavior differs from the hand-rolled code in any way the change relies on
+
+Evidence: cite the helper at `path:line` (internal) or a documentation link (external). Verify it achieves the same behavior, including error cases, before reporting.
+
+### PAIRED_TECHNIQUE
+The technique in the diff has a well-known companion that materially improves it, and the diff does not include the companion.
+
+What counts:
+- Unbounded fan-out (one goroutine/task per item, no concurrency cap) where the singleflight pattern or a bounded worker pool is the standard companion once load arrives
+- Retry or backoff without jitter in code that will run under contention
+- A value recomputed per call where a small memoization cache is the standard companion
+- Event-driven paths where debounce or throttling is the usual pairing
+
+What does NOT count:
+- Asserting the load will happen. Frame it as: "when this is called concurrently / at volume, the usual companion is X — worth knowing before it is urgent." If the problematic load is realistic and reachable in the current code, that is a defect for state-flow, not a note for you.
+
+### INTERNAL_PATTERN
+The codebase has an established, battle-tested way of doing this thing, and the change does it a different way.
+
+What counts:
+- House ownership conventions: where responsibility lives (caller versus callee, which unit keeps its own consistency)
+- "Solve it once": the change applies a fix in a second place when a central fix exists or is the house pattern. Production code only — see TEST_CRAFT for the test-code exception.
+- The house security posture: strictness even on internal boundaries, when the change relaxes it
+- Established error-classification, logging, or context-propagation conventions the change does not follow
+
+Evidence: cite the sibling usage (`path:line`) that establishes the house pattern. If no sibling exists, there is no house pattern and no finding.
+
+### IDIOM
+A language or library practice the author may not know, where following it is the mark of fluency.
+
+What counts:
+- Error-handling hygiene: not logging AND returning the same error; sentinel errors; wrapping errors with context instead of discarding them
+- Language features that replace verbose constructs with clearer ones (range-over-int, slice-comparison helpers, typed enumeration constants)
+- Library conventions: context propagation rules, interface-compliance assertions
+
+Evidence: cite a documentation page (language specification, effective guide, stdlib doc) or a sibling file. Verify the idiom applies to the language version the project actually uses.
+
+### TEST_CRAFT
+Test design teaching. The tests pass; the design makes them expensive to trust or maintain.
+
+The lens positions on test design (apply when test code in the change deviates):
+- **Repetition is fine in tests.** Each test should read standalone. Do not flag duplicated setup as a DRY issue.
+- **Shared setup is fine up to a point of diminishing returns.** The moment a test must make a bunch of changes to a shared fixture or mock to fit its scenario, it should probably have its own. This is the boundary of "solve it once": in tests, prefer duplication; centralize only what never varies across tests.
+- **Branches and loops inside a single test body are brittle.** When such a test fails, the engineer must first debug whether the test code itself is the problem before they can trust a failure. Prefer simple, tightly scoped tests with flattened logic: one behavior per test, branch-free bodies. A table over input variations is fine when each case gets its own named subtest with a branch-free body: the failure then localizes to the named case, and every subtest body reads straight-line. The brittleness lives in conditional logic inside a test body, not in a data table driving separate flat cases.
+
+What counts:
+- Test bodies that branch or loop over scenarios where inlining each case as its own flat test would read clearly
+- Shared mocks or fixtures heavily customized by individual tests
+- Harness complexity that would be the first suspect on any failure — if a test fails, is the failure clearly in the code under test?
+
+What does NOT count:
+- Test coverage gaps (out of scope for this lens)
+- Table-driven tests where they are the repo's enforced house style. Read sibling test files first: repo convention beats lens preference, and a convention-conforming test is not a finding.
+- A table of input variations where each case runs in its own named subtest with a branch-free body: failures localize to the case name, so the brittleness the lens targets is absent.
+
+### MISUSE_PROOFING
+An API or interface the change introduces could be shaped so misuse is impossible rather than discouraged.
+
+What counts:
+- A stringly-typed parameter where a typed enum or distinct type would foreclose invalid values
+- A "remember to call X first" ordering where a constructor or builder would make the un-initialized state unrepresentable
+- A public surface where the compiler or linter could enforce the contract that documentation currently enforces
+
+Framing: the current design works; the pattern makes the wrong thing impossible instead of unlikely, and usually makes the right thing the easiest thing at the same time.
+
+What does NOT count:
+- Requiring a redesign of a stable, widely-called existing API (that is economy's TRADEOFF territory)
+- Speculative hardening of internal-only code with a single caller
+
+### NEXT_READER
+The code is clear, but the intent lives at a distance: a future engineer doing a focused task would not find it.
+
+What counts:
+- A named constant or term that one switch or code path depends on, defined far away from it, where moving or linking them saves the next dev a hunt
+- Overloaded terms left unflagged for readers (two meanings of "envelope" in one system)
+- Documentation for a feature that is not linked from the places an integrating engineer would actually land: what will they grep for, is the doc there, is it linked from the package root or README?
+- A public function whose usage is non-obvious with no example at the likely landing spots
+
+Framing: you are arming the next reader. Cite the specific hunt the future engineer would face.
+
+What does NOT count:
+- Comment narrative quality (breadcrumbs owns that)
+- Naming accuracy, spelling, or doc correctness (pedantic owns that)
+
+### API_SHAPE
+Interface-design teaching, for package APIs and external HTTP APIs alike: do not impose structure on the caller.
+
+What counts:
+- An interface that forces callers through structure that serves the implementation, not the caller: a parameter that exists only for internal bookkeeping, a required wrapper, a fixed call order. "Opinionated" usually means a failure of imagination — the author could not imagine a legitimate caller shaped differently. Name the caller shape the interface forecloses.
+- Strictness in the wrong place. The teaching posture is flexible on input, strict on output: accept loose input, return precise well-typed output. Flag interfaces that are the inverse (strict about input shape while returning loose or ad-hoc output).
+- A boundary that leaks the implementation's internal structure onto callers. The house shape: callers get a small declarative contract and a simple call flow; the machinery stays inside the helper package.
+
+Evidence: cite the interface at `path:line` and describe the caller-imposition concretely ("every caller must now know X to do Y").
+
+What does NOT count:
+- Defect-grade coupling findings (economy's TRADEOFF)
+- Interface shape dictated by an external contract (wire format, framework requirement)
+
+## What NOT to report
+
+- Code that is correct, conventional, and already the easiest path (that is the baseline — an empty report is the common case)
+- Anything that is a defect; hand it to the defect specialists instead
+- Style preferences with no teaching content
+- Teaching the author something their own diff already demonstrates they know
+- Condescension in any form: the register is "you may not have seen this", and if a note cannot survive that register, it is not a mentorship note
+
+## Method
+
+1. Use the diff stat from scope gathering to identify changed files. For each, read the diff and the full current version.
+2. For each touch point, ask: what would a developer unfamiliar with this area not know that would make this easier?
+3. Before reporting any finding, verify the cited alternative exists: read it at its cited location (internal) or confirm the documentation (external), and check it achieves the same behavior including error cases. If the current code relies on a difference, there is no finding.
+4. Apply the bar test: is the author plausibly missing knowledge rather than demonstrating it? Is the teaching concrete and cited? Is the code still correct as written?
+5. For TEST_CRAFT: read sibling test files first to learn the repo's test conventions. Repo convention beats lens preference.
+6. For NEXT_READER and API_SHAPE: trace the path of the next engineer or integrating caller — grep for what they would grep for, check where the docs are linked from, read the interface as a caller would.
+
+Do NOT report on files you did not actually read.
+
+## Output format
+
+Produce mentorship notes as markdown. For each note:
+
+### [CATEGORY] — file:line
+- **Observation**: what the code does now, stated neutrally
+- **The easier path**: the named alternative, with its citation
+- **Why it matters**: the concrete benefit (less code to own, a bug class foreclosed, the next dev finds it faster) in one or two sentences
+- Optionally close with a probe: "Would `<alternative>` work here, or is there a reason to rule it out?" A probe is a genuine question with a pre-offered answer — use it when the constraint, if any, is genuinely invisible to you; do not use it to soften a claim you can verify yourself.
+
+All mentorship notes are informational. They ride along with any review verdict and never block a merge.
+
+If there are no notes, say so explicitly: "No mentorship notes." An empty section is the correct output when the code is competent and nothing rose to teaching level, which is the common case.

package/artifacts/skills/thatch-review-synthesizer.md

@@ -3,7 +3,7 @@ name: thatch-review-synthesizer
 description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights, mentorship). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -48,6 +48,14 @@ For each finding from the specialists:
    - For CLEANUP highlights: verify the bad code existed in the before-state (use git show with the base commit). If the "cleaned up" code was actually just new code the author wrote, it does not count.
    Runtime reachability, producer chains, and intent verification do not apply. A highlight is not a bug and does not need a trigger scenario.
 
+4i. **Mentorship verification (mentorship).** For mentorship notes, verification means:
+   - The cited alternative exists at the cited location (`path:line` read directly; documentation links confirmed, not assumed). A note citing a helper that does not exist is rejected outright.
+   - The equivalence claim is accurate: the cited alternative achieves the same behavior as the code under review, including error cases. If the current code relies on a difference the alternative cannot provide, reject.
+   - The code as written is not a defect. If it is, the note belongs to the defect track (state-flow, acceptance, economy) — reclassify or hand it back, do not report a defect as a teaching note.
+   - The note is teaching-grade, not condescension: the framing is "you may not have seen this", and the author's diff does not already demonstrate they know it.
+   - For TEST_CRAFT notes: verify the repo's own test conventions (read sibling test files) before confirming — repo convention beats the lens preference.
+   Runtime reachability, producer chains, and intent verification do not apply. A mentorship note is not a bug and does not need a trigger scenario. All mentorship notes are informational and never blocking.
+
 4e. **Economy verification (economy).** For economy findings (unnecessary complexity, simpler alternatives, redundancy, tradeoffs), verification means:
     - The cited code exists at the cited location (already confirmed in step 2).
     - For OVERENGINEERED and SIMPLER_AVAILABLE findings: the simpler alternative is concretely identified (the specialist named a specific approach, not a vague "this could be simpler"), the simpler alternative achieves the same behavior (read the cited code and reason about whether the simpler approach handles the same inputs, error cases, and edge cases — if it changes behavior, reject), and the complexity is not constraint-driven (check the context brief, workflow guide, and callers — if a constraint explains it, reject).
@@ -57,8 +65,8 @@ For each finding from the specialists:
     Runtime reachability, producer chains, and intent verification do not apply. An economy finding is a design observation, not a user-triggered bug.
 
 7. **Classify:**
-    - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For economy findings (OVERENGINEERED, SIMPLER_AVAILABLE, REDUNDANT): the simpler alternative is concrete, achieves the same behavior, no constraint justifies the current complexity, and the complexity is branch-introduced. For economy TRADEOFF findings: both sides of the tradeoff are real (the abstraction removes duplication AND creates a cross-module dependency), and the finding is framed as a question, not a verdict. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence.
-    - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding. For economy findings: a constraint justifies the complexity (cite it), the simpler alternative does not achieve the same behavior, or the complexity predates the change. For economy TRADEOFF findings: only one side of the tradeoff is real (e.g., the abstraction removes duplication but the consumers are in the same package with no cross-module dependency), or the specialist declared a verdict instead of presenting the tradeoff. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR).
+    - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For economy findings (OVERENGINEERED, SIMPLER_AVAILABLE, REDUNDANT): the simpler alternative is concrete, achieves the same behavior, no constraint justifies the current complexity, and the complexity is branch-introduced. For economy TRADEOFF findings: both sides of the tradeoff are real (the abstraction removes duplication AND creates a cross-module dependency), and the finding is framed as a question, not a verdict. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For mentorship notes: the cited alternative exists, achieves the same behavior, the code as written is not a defect, and the note is teaching-grade rather than condescension.
+    - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding. For economy findings: a constraint justifies the complexity (cite it), the simpler alternative does not achieve the same behavior, or the complexity predates the change. For economy TRADEOFF findings: only one side of the tradeoff is real (e.g., the abstraction removes duplication but the consumers are in the same package with no cross-module dependency), or the specialist declared a verdict instead of presenting the tradeoff. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR). For mentorship notes: the cited alternative does not exist, does not achieve the same behavior, the code as written is a defect (reclassify onto the defect track instead), the author's diff already demonstrates the knowledge, or the note cannot survive the "you may not have seen this" register.
     - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. A data-shape finding that lacks the governing-constraint citation is UNVERIFIABLE, not CONFIRMED. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED. Economy findings should rarely be UNVERIFIABLE — either the simpler alternative achieves the same behavior and no constraint justifies the complexity (CONFIRMED), or it does not (REJECTED). Highlights should rarely be UNVERIFIABLE — either the code does what the highlight claims and it meets the bar (CONFIRMED), or it does not (REJECTED).
 
 ## Deduplication
@@ -107,6 +115,8 @@ Confirmed LOW findings are mandatory. Do not summarize them away or omit them fo
 
 Confirmed highlights are optional in the sense that most PRs will have none. Do not pad the section with borderline calls. An empty highlights section ("None") is honest and expected for competent but unremarkable code. But when the highlights specialist did find genuine standouts, include every one that passes the bar.
 
+Mentorship notes follow the same rule: most PRs will have none, an empty section ("None") is the expected outcome, and every included note must have passed verification. They are informational and never merged into the defect findings.
+
 The report is user-facing. Start by teaching the changed workflows before listing findings. Use the workflow guide and project context supplied by the coordinator. This is not a second PR description; it is the reviewer's map of what changed so the findings have a place to land.
 
 For each affected workflow, use the same before/now shape as PR descriptions:
@@ -120,8 +130,12 @@ Apply the same clarity rules as the writing skills: prefer concrete terms over a
 
 ### Writing review comments
 
-The author is already holding the bug mechanics, the state flow, and the
-code context in their head when they read your comment. Write so the
+The author has the diff open at your cited lines. They can see what
+those lines do. What they may not have in front of them is one hop out:
+the caller, the callee, the guard, the other writer of the same field.
+That hop is the comment's context budget. Do not re-explain the visible
+lines and do not reach for project-wide background either; spend the
+words on what the cited lines cannot show. Write so the
 prose itself takes no effort to parse. The author should spend their
 slow deliberate thinking on the bug, not on decoding your sentences.
 
@@ -159,6 +173,31 @@ Rules:
   insight itself: a sharp technical observation that happens to be
   funny. Not a joke next to the insight. Not sycophancy. Not "great
   catch!" The playfulness signals engagement, not approval.
+- **Clarity wins over compression.** To shorten a comment, drop a whole
+  claim. Never tighten a surviving sentence into a clause-chain; every
+  sentence you keep keeps its full grammar. Brevity means fewer claims,
+  not denser ones.
+- **Literal phrasing beats compressed idiom.** Do not use method names
+  as verbs and do not compress behavior into noun stacks. "reading the
+  row from the database" not "the row read". If a phrase sounds like it
+  belongs in source code, rewrite it as a sentence.
+- **Explain operations before naming them.** A process word (refresh,
+  coalesce, reconcile, fan out) is not an explanation. Name the object,
+  the action, and the effect: "the worker waits up to 5 seconds, then
+  reloads each stale key once".
+- **Show the middle step.** A sentence with "so", "because", or
+  "prevents" hides its mechanism unless the step between cause and
+  effect is visible. A producer-transform-consumer chain is one
+  sentence per hop, not one line for the whole chain.
+- **Prefer concrete over ambiguous.** If a word can be read two ways in
+  this context, qualify it or replace it with the concrete behavior.
+  Ordinary words count: claim, owner, current, resolve, scope.
+
+These rules govern the whole report, not only comments posted after it.
+The Finding, Evidence, and Trigger/Proof fields are prose. A
+Trigger/Proof field that crams producer, transform, and consumer into
+one line is the densest text in the report and the first thing the
+author fails to parse. One sentence per hop.
 
 ### Author sensitivity
 
@@ -234,6 +273,18 @@ For each highlight:
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
 6. **Why it stands out**: what makes this above the bar — be specific
 
+### Mentorship notes
+
+Teaching-grade observations for the author: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Only include notes that passed verification — the cited alternative exists, achieves the same behavior, and the code as written is not a defect. These are informational and never blocking. If none, write "None."
+
+For each note:
+1. **Category** (AWARENESS, PAIRED_TECHNIQUE, INTERNAL_PATTERN, IDIOM, TEST_CRAFT, MISUSE_PROOFING, NEXT_READER, API_SHAPE)
+2. **Source**: mentorship specialist
+3. **Location**: file:line
+4. **Observation**: what the code does now, stated neutrally
+5. **The easier path**: the named alternative with its citation
+6. **Why it matters**: the concrete benefit in one or two sentences
+
 ### Confirmed findings
 
 For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each finding MUST include all of these fields:
@@ -242,7 +293,7 @@ For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each fin
 3. **Location**: file:line
 4. **Finding**: what the problem is
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
-6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified
+6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified. One sentence per hop; do not cram the chain into one line.
 7. **Provenance**: branch-introduced or pre-existing. If the finding matches a prior review comment, append `; previously identified by @author, PR #N, DATE` to this field. For findings matching an `addressed` prior comment, also add a one-line note on why the finding persists so the user can investigate whether the prior resolution is incomplete or the issue has regressed.
 
 ### Rejected findings (appendix, brief)

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

@@ -78,9 +78,11 @@ Runs in a single DB transaction:
 
 1. **Matcher dedup** — finds an existing behavior matcher above cosine 0.85,
    else creates one.
-2. **Behavior dedup** — store-wide search for a near-identical behavior
-   (cosine >= 0.85). If found, links this matcher to it via an edge rather
-   than creating a duplicate row.
+2. **Behavior dedup** — search across the target store AND global for a
+   near-identical behavior (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 the write reinforces the existing row in its home
+   store and the result echoes where it landed.
 3. **New behavior** — creates behavior + edge + provenance entry tagged
    `codify`.
 4. Returns `[codified]` for a new behavior or `[linked]` for an existing one

package/docs/dev/features/memory-store.md

@@ -41,6 +41,19 @@ The "global" store always exists — it is inserted at schema init (`INSERT OR I
 - Output is a `Float32Array`.
 - `MockEmbeddingModel` is available for tests.
 - The model can be overridden via the `THATCH_MODEL` environment variable.
+- Backend: runs on onnxruntime-web's pure-JS/wasm runtime by default. Before
+  transformers initializes, `configureBackend()` pins
+  `globalThis[Symbol.for("onnxruntime")]` to onnxruntime-web, so no
+  onnxruntime-node NAPI wrap finalizers exist to panic Bun at process
+  teardown (oven-sh/bun#34664). `THATCH_EMBEDDING_BACKEND=native` opts back
+  into onnxruntime-node. Wasm runs single-threaded and uses
+  `device: "auto"` with an explicit `wasm` execution provider (the override
+  branch leaves transformers' device allowlist empty, so named devices throw).
+- Native-memory hygiene: each embed copies the vector out of the output
+  tensor, then disposes the tensor; after 10 idle minutes the pipeline's
+  native sessions are released (an embed lazily re-loads). The plugin's
+  `dispose` hook releases them at shutdown. All release paths are
+  best-effort and never throw.
 
 ### Write path (memory_remember)
 

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/skills.md

@@ -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`. |
@@ -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`).

package/docs/user/README.md

@@ -278,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`. |
@@ -409,6 +410,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 |
 
 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/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/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

@@ -45,6 +45,7 @@ Skills are split into shared (all hosts) and opencode-only:
 | `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.39",
+  "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/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);
   }
 

package/src/embeddings.ts

@@ -25,11 +25,99 @@ export interface EmbeddingModel {
  */
 export type PipelineFactory = (modelName: string) => Promise<any>;
 
+/**
+ * Embedding backend mode. "wasm" runs the ONNX model on onnxruntime-web's
+ * pure-JS/wasm runtime; "native" runs it on onnxruntime-node's NAPI addon.
+ */
+export type EmbeddingBackendMode = "wasm" | "native";
+
+/**
+ * Reads the backend override. Only "native" opts out; any other value,
+ * including unset, selects the wasm default. Exported for tests.
+ */
+export function backendMode(): EmbeddingBackendMode {
+  return process.env.THATCH_EMBEDDING_BACKEND === "native" ? "native" : "wasm";
+}
+
+const ORT_SYMBOL = Symbol.for("onnxruntime");
+
+let backendConfigured: Promise<EmbeddingBackendMode> | null = null;
+
+/**
+ * Chooses the ONNX backend before transformers initializes. Memoized: the
+ * choice is made once at transformers' module init and cannot be changed
+ * afterwards. Exported for tests.
+ *
+ * "wasm" mode pins globalThis[Symbol.for("onnxruntime")] to onnxruntime-web
+ * so transformers' node build creates sessions on its pure-JS/wasm runtime
+ * instead of the onnxruntime-node NAPI addon. The NAPI addon leaves wrap
+ * finalizers that panic Bun at process teardown (oven-sh/bun#34664); the wasm
+ * runtime creates none. A backend already chosen by the host (symbol present)
+ * is respected, never clobbered. A failed onnxruntime-web import falls back
+ * to native rather than blocking embedding.
+ */
+export async function configureBackend(): Promise<EmbeddingBackendMode> {
+  backendConfigured ??= (async () => {
+    const mode = backendMode();
+    if (mode === "native" || ORT_SYMBOL in globalThis) return mode;
+    try {
+      const ort = await import("onnxruntime-web");
+      (globalThis as Record<symbol, unknown>)[ORT_SYMBOL] = ort;
+      // Single-threaded wasm: deterministic, and avoids worker_threads,
+      // where Bun has known shutdown crashes. Latency at one thread is fine
+      // for background embedding.
+      ort.env.wasm.numThreads = 1;
+    } catch {
+      // onnxruntime-web unavailable - native sessions still work.
+    }
+    return mode;
+  })();
+  return backendConfigured;
+}
+
+/**
+ * Test hook: clears the configureBackend memo and unpins the onnxruntime
+ * global, so a test can exercise the pinning path itself. Needed because the
+ * test process is shared across files: initializing the plugin server seeds
+ * behaviors, which embeds, which runs configureBackend and pins the symbol
+ * as a side effect. Whether that happened before a given test file runs
+ * depends on bun's file order, which differs between machines.
+ */
+export function resetBackendForTests(): void {
+  backendConfigured = null;
+  delete (globalThis as Record<symbol, unknown>)[ORT_SYMBOL];
+}
+
 const defaultPipelineFactory: PipelineFactory = async (modelName) => {
+  const mode = await configureBackend();
   const { pipeline } = await import("@huggingface/transformers");
-  return pipeline("feature-extraction", modelName);
+  if (mode === "native") {
+    return pipeline("feature-extraction", modelName);
+  }
+  // The ORT_SYMBOL override branch leaves transformers' device allowlist
+  // empty, so any named device throws; "auto" bypasses the check and the
+  // explicit execution provider does the real work.
+  return pipeline("feature-extraction", modelName, {
+    device: "auto",
+    session_options: { executionProviders: ["wasm"] },
+  });
 };
 
+/**
+ * How long a loaded pipeline may sit unused before its native ONNX sessions
+ * are released while the runtime is still healthy. Long enough to span the
+ * gap between extraction bursts, short enough to matter before process exit.
+ */
+const DEFAULT_IDLE_TTL_MS = 10 * 60 * 1000;
+
+export interface BgeEmbeddingModelOptions {
+  /**
+   * Idle milliseconds before the pipeline's native sessions are released.
+   * A later embed lazily re-loads. 0 disables idle release.
+   */
+  idleTtlMs?: number;
+}
+
 /**
  * Lazy-loads an embedding model via @huggingface/transformers.
  * Model files (~34 MB for the default) are downloaded once and cached by HF Hub.
@@ -37,12 +125,19 @@ const defaultPipelineFactory: PipelineFactory = async (modelName) => {
 export class BgeEmbeddingModel implements EmbeddingModel {
   #modelName: string;
   #pipelineFactory: PipelineFactory;
+  #idleTtlMs: number;
   #pipe: any = null;
   #loading: Promise<void> | null = null;
+  #idleTimer: ReturnType<typeof setTimeout> | null = null;
 
-  constructor(modelName = "Xenova/bge-small-en-v1.5", pipelineFactory?: PipelineFactory) {
+  constructor(
+    modelName = "Xenova/bge-small-en-v1.5",
+    pipelineFactory?: PipelineFactory,
+    options: BgeEmbeddingModelOptions = {},
+  ) {
     this.#modelName = modelName;
     this.#pipelineFactory = pipelineFactory ?? defaultPipelineFactory;
+    this.#idleTtlMs = options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
   }
 
   get loaded(): boolean {
@@ -75,12 +170,31 @@ export class BgeEmbeddingModel implements EmbeddingModel {
   }
 
   async #embed(text: string): Promise<Float32Array> {
-    await this.load();
-    const output = await this.#pipe(text, {
-      pooling: "mean",
-      normalize: true,
-    });
-    return output.data as Float32Array;
+    // Clear any pending idle timer before touching the pipeline. The timer
+    // must never fire while an embed is in flight - its callback releases
+    // the pipeline this call is about to use.
+    this.#clearIdleTimer();
+    try {
+      await this.load();
+      const pipe = this.#pipe;
+      const output = await pipe(text, {
+        pooling: "mean",
+        normalize: true,
+      });
+      // Copy the vector before releasing the tensor: the real Tensor's data
+      // getter exposes memory the disposer frees.
+      const data = new Float32Array(output.data);
+      if (typeof output?.dispose === "function") {
+        try {
+          await output.dispose();
+        } catch {
+          // Tensor release is best-effort; the copied data is already valid.
+        }
+      }
+      return data;
+    } finally {
+      this.#armIdleTimer();
+    }
   }
 
   /**
@@ -89,11 +203,16 @@ export class BgeEmbeddingModel implements EmbeddingModel {
    * the runtime is still alive. If instead they survive to Bun's worker
    * teardown, Bun panics creating their errors (oven-sh/bun#34664).
    *
+   * The idle timer releases on the same principle during normal operation:
+   * the plugin's dispose hook is best-effort because opencode can exit
+   * without running it, so sessions are also freed after a quiet period.
+   *
    * Best-effort by design: dispose never throws, and a failed release is
    * indistinguishable from never loading. An embed call after dispose just
    * lazily re-loads the model.
    */
   async dispose(): Promise<void> {
+    this.#clearIdleTimer();
     // An in-flight load memoizes a rejecting promise on failure. Await it
     // defensively so its error neither escapes dispose nor kills the teardown.
     if (this.#loading) {
@@ -103,6 +222,10 @@ export class BgeEmbeddingModel implements EmbeddingModel {
         // Load failed - nothing was loaded, so nothing to release.
       }
     }
+    await this.#release();
+  }
+
+  async #release(): Promise<void> {
     const pipe = this.#pipe;
     this.#pipe = null;
     this.#loading = null;
@@ -110,7 +233,27 @@ export class BgeEmbeddingModel implements EmbeddingModel {
     try {
       await pipe.dispose();
     } catch {
-      // Best-effort - see doc comment above.
+      // Best-effort - see dispose's doc comment.
+    }
+  }
+
+  #armIdleTimer(): void {
+    if (this.#idleTtlMs <= 0) return;
+    this.#clearIdleTimer();
+    this.#idleTimer = setTimeout(() => {
+      this.#idleTimer = null;
+      this.#release().catch(() => {
+        // Idle release is best-effort; a failed release retries on dispose.
+      });
+    }, this.#idleTtlMs);
+    // Never hold the host process open for an idle timer.
+    this.#idleTimer.unref?.();
+  }
+
+  #clearIdleTimer(): void {
+    if (this.#idleTimer) {
+      clearTimeout(this.#idleTimer);
+      this.#idleTimer = null;
     }
   }
 }

package/src/prediction.ts

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

package/src/prompts.ts

@@ -338,7 +338,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
 - \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
-- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-economy\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` - eight specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-economy\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` / \`-mentorship\` - nine specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
 - \`thatch-project-primer\` - investigate a new project and write foundational memories.
 - \`thatch-session-reflection\` - record what you learned at end of session.
 - \`thatch-fact-extractor\` - extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).

package/src/scoring-engine.ts

@@ -118,7 +118,7 @@ export class ScoringEngine {
     const rows = this.#db
       .query(
         `SELECT p.id, p.statement, p.rationale, p.confidence, p.confirm_count, p.disconfirm_count,
-                e.matcher_id, e.weight
+                p.embedding, e.matcher_id, e.weight
          FROM ${edgesTable} e
          JOIN ${itemsTable} p ON e.${itemForeignKey} = p.id
          WHERE e.matcher_id IN (${placeholders})
@@ -128,6 +128,7 @@ export class ScoringEngine {
 
     const matcherMap = new Map(matchers.map((m) => [m.id, m]));
     const scored: ScoredItem[] = [];
+    const embeddings = new Map<string, Float32Array>();
     for (const r of rows) {
       const matcher = matcherMap.get(r.matcher_id);
       if (!matcher) continue;
@@ -135,6 +136,7 @@ export class ScoringEngine {
       const confidence = r.confidence as number;
       const evidence = Math.round(r.confirm_count + r.disconfirm_count);
       const score = matcher.score * (r.weight as number) * confidence;
+      if (r.embedding) embeddings.set(r.id as string, blobToVector(r.embedding));
       scored.push({
         matcher_id: r.matcher_id,
         matcher_description: matcher.description,
@@ -153,9 +155,25 @@ export class ScoringEngine {
     // so the nudge does not repeat the same item with different matcher
     // contexts.
     const seen = new Set<string>();
+    // Semantic dedup across stores: the same preference saved to both the
+    // project and global stores has different row ids but near-identical
+    // embeddings. Without this, the multi-store nudge scan surfaces it
+    // twice every turn. Sorted by score descending, so the first occurrence
+    // (highest-scoring copy) wins.
+    const SEMANTIC_DEDUP_COSINE = 0.85;
+    const seenEmbeddings: Float32Array[] = [];
     return scored.filter((s) => {
       if (seen.has(s.item_id)) return false;
       seen.add(s.item_id);
+      const emb = embeddings.get(s.item_id);
+      if (emb) {
+        for (const other of seenEmbeddings) {
+          if (other.length === emb.length && cosineSimilarity(other, emb) >= SEMANTIC_DEDUP_COSINE) {
+            return false;
+          }
+        }
+        seenEmbeddings.push(emb);
+      }
       return true;
     });
   }
@@ -219,18 +237,21 @@ export class ScoringEngine {
   }
 
   findNearestItem(
-    store: string,
+    store: string | string[],
     embedding: Float32Array,
     threshold: number,
   ): ItemRow | null {
     const { itemsTable } = this.#cfg;
+    const stores = Array.isArray(store) ? store : [store];
+    if (stores.length === 0) return null;
+    const placeholders = stores.map(() => "?").join(", ");
     const rows = this.#db
       .query(
         `SELECT id, store, statement, rationale, confidence, confirm_count, disconfirm_count, created_at, updated_at, embedding
          FROM ${itemsTable}
-         WHERE store = ? AND embedding IS NOT NULL`,
+         WHERE store IN (${placeholders}) AND embedding IS NOT NULL`,
       )
-      .all(store) as any[];
+      .all(...(stores as [string, ...string[]])) as any[];
 
     let best: { row: any; score: number } | null = null;
     for (const r of rows) {

package/src/skills.ts

@@ -41,6 +41,7 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-review-breadcrumbs",
     "thatch-review-mark-and-sweep",
     "thatch-review-highlights",
+    "thatch-review-mentorship",
     "thatch-review-synthesizer",
     "thatch-review-context",
     "thatch-code-archaeology",

package/src/tool-defs.ts

@@ -23,6 +23,26 @@ const MATCHER_DEDUP_COSINE = 0.85;
 const PREDICTION_DEDUP_COSINE = 0.85;
 const BEHAVIOR_DEDUP_COSINE = 0.85;
 
+/**
+ * Resolves the write target for a store-scoped tool. detectRepo falls back
+ * to "unknown" when it cannot name a repo; rows written to a store called
+ * "unknown" are invisible to every auto-fire scan (which reads the project
+ * store and "global"), so an unidentified context falls back to global.
+ */
+function resolveStore(args: Record<string, unknown>, ctx: CoreContext): string {
+  const store = (args.store as string) || ctx.defaultStore;
+  return store === "unknown" ? "global" : store;
+}
+
+/**
+ * The stores whose items a write must dedup against: the target store plus
+ * global, matching the stores the auto-fire nudge scans. A duplicate in
+ * either store would otherwise surface twice every turn.
+ */
+function dedupScanStores(store: string): string[] {
+  return store === "global" ? ["global"] : [store, "global"];
+}
+
 // Minimum matcher cosine to consider a prediction relevant. Matches the
 // auto-fire threshold in index.ts (PREDICTION_THRESHOLD). The query tool
 // should not return predictions from near-zero-similarity matchers that
@@ -192,7 +212,7 @@ const rememberDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const label = args.label as string;
     const content = `# ${label}\n\n${args.content as string}`;
     const embedding = await ctx.model.passageEmbed(content);
@@ -276,7 +296,7 @@ const listDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const entries = ctx.db.listEntries(store);
 
     if (entries.length === 0) return `No memories in "${store}".`;
@@ -306,7 +326,7 @@ const showDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const entry = ctx.db.showEntry(store, args.label as string);
 
     if (!entry) return `No memory labeled "${args.label as string}" found in store "${store}".`;
@@ -327,7 +347,7 @@ const forgetDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const deleted = ctx.db.forgetEntry(store, args.label as string);
 
     if (!deleted) return `No memory labeled "${args.label as string}" found in store "${store}".`;
@@ -366,7 +386,7 @@ const findDuplicatesDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const threshold = (args.threshold as number) ?? 0.85;
     const candidates = ctx.db.findDuplicates(store, threshold);
 
@@ -394,7 +414,7 @@ const markCheckedDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     ctx.db.markPairChecked(
       store,
       ctx.db.slugify(args.label_a as string),
@@ -551,7 +571,7 @@ const predictionUpdateDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const matcherText = args.matcher as string;
     const predictionText = args.prediction as string;
     const signal = args.signal as "confirm" | "disconfirm" | "soft" | "create";
@@ -565,20 +585,23 @@ const predictionUpdateDef: ToolDef = {
     // entire operation rather than leaving orphans (matcher without
     // prediction, prediction without edge, edge without confidence).
     return ctx.db.transaction(() => {
+      // Cross-store dedup: search the target store AND global for a
+      // near-identical prediction. The auto-fire nudge scans both stores,
+      // so two copies would surface twice every turn. When the prediction
+      // already exists in the other store, that store becomes the write
+      // target ("home") and the result echoes where it landed.
+      const existing = ctx.db.findNearestPrediction(dedupScanStores(store), predEmbed, PREDICTION_DEDUP_COSINE);
+      const home = existing?.store ?? store;
+      const storeTag = home === store ? "" : ` in ${home}`;
+
       // Dedup matchers: find an existing matcher above the cosine threshold
       // rather than always creating a new one.
-      let matcherId = ctx.db.findNearestMatcher(store, matcherEmbed, MATCHER_DEDUP_COSINE)?.id;
-      if (!matcherId) matcherId = ctx.db.createMatcher(store, matcherText, matcherEmbed, ctx.model.name);
-
-      // Store-wide dedup: search the entire store for a near-identical
-      // prediction, not just this matcher's edges. If found, link this
-      // matcher to the existing prediction via an edge rather than
-      // creating a second row with the same statement.
-      let predictionId = ctx.db.findNearestPrediction(store, predEmbed, PREDICTION_DEDUP_COSINE)?.id;
+      let matcherId = ctx.db.findNearestMatcher(home, matcherEmbed, MATCHER_DEDUP_COSINE)?.id;
+      if (!matcherId) matcherId = ctx.db.createMatcher(home, matcherText, matcherEmbed, ctx.model.name);
 
-      if (!predictionId) {
+      if (!existing) {
         // No near-identical prediction exists; create one and link it.
-        predictionId = ctx.db.createPrediction(store, predictionText, rationale, predEmbed, ctx.model.name);
+        const predictionId = ctx.db.createPrediction(home, predictionText, rationale, predEmbed, ctx.model.name);
         ctx.db.createEdge(matcherId, predictionId, 1.0);
 
         // When the signal is confirm/disconfirm/soft (not create), apply
@@ -593,9 +616,11 @@ const predictionUpdateDef: ToolDef = {
           return `[created + ${signal}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
         }
         ctx.db.addProvenance(predictionId, "create", rationale);
-        return `[created] ${store} :: "${predictionText}" for "${matcherText}"`;
+        return `[created] ${home} :: "${predictionText}" for "${matcherText}"`;
       }
 
+      const predictionId = existing.id;
+
       // Ensure an edge links this matcher to the existing prediction.
       // createEdge uses ON CONFLICT DO NOTHING, so existing edge weights
       // are preserved.
@@ -607,8 +632,8 @@ const predictionUpdateDef: ToolDef = {
       // confidence-neutral, not a disconfirm.
       if (signal === "create") {
         ctx.db.addProvenance(predictionId, "create", rationale);
-        const existing = ctx.db.getPrediction(predictionId);
-        return `[linked] "${existing?.statement ?? predictionText}" for "${matcherText}" confidence=${(existing?.confidence ?? 0).toFixed(2)} (${existing?.confirm_count ?? 0}/${existing?.disconfirm_count ?? 0})`;
+        const existingItem = ctx.db.getPrediction(predictionId);
+        return `[linked${storeTag}] "${existingItem?.statement ?? predictionText}" for "${matcherText}" confidence=${(existingItem?.confidence ?? 0).toFixed(2)} (${existingItem?.confirm_count ?? 0}/${existingItem?.disconfirm_count ?? 0})`;
       }
 
       // Signal is confirm, disconfirm, or soft. Map the tool's 4-value
@@ -616,7 +641,7 @@ const predictionUpdateDef: ToolDef = {
       ctx.db.adjustConfidence(predictionId, signal === "soft" ? "soft" : signal === "confirm" ? "confirm" : "disconfirm");
       ctx.db.addProvenance(predictionId, signal, rationale);
       const updated = ctx.db.getPrediction(predictionId);
-      return `[${signal}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
+      return `[${signal}${storeTag}] "${updated?.statement ?? predictionText}" confidence=${(updated?.confidence ?? 0).toFixed(2)} (${updated?.confirm_count ?? 0}/${updated?.disconfirm_count ?? 0})`;
     });
   },
 };
@@ -628,13 +653,15 @@ const predictionListDef: ToolDef = {
     "confidence, and evidence count. For inspection and debugging.",
   args: {
     store: z.string().optional().describe(
-      "Which store to list. Defaults to the project store.",
+      "Which store to list. Defaults to the project store and global.",
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
-    const predictions = ctx.db.listPredictions(store);
-    if (predictions.length === 0) return `No predictions in "${store}".`;
+    const stores = args.store
+      ? [args.store as string]
+      : [ctx.defaultStore, "global"];
+    const predictions = stores.flatMap((s) => ctx.db.listPredictions(s));
+    if (predictions.length === 0) return `No predictions in "${stores.join('", "')}".`;
     return predictions.map((p) => {
       const matchers = p.matchers.map((m) => `    - "${m.description}" (w:${m.weight})`).join("\n");
       const provenance = ctx.db.getProvenance(p.id);
@@ -662,7 +689,7 @@ const predictionDeleteDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const statementText = args.statement as string;
     const predEmbed = await ctx.model.passageEmbed(statementText);
     const prediction = ctx.db.findNearestPrediction(store, predEmbed, PREDICTION_DEDUP_COSINE);
@@ -705,7 +732,7 @@ const behaviorCodifyDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const situationText = args.situation as string;
     const behaviorText = args.behavior as string;
     const rationale = args.rationale as string;
@@ -714,21 +741,28 @@ const behaviorCodifyDef: ToolDef = {
     const behaviorEmbed = await ctx.model.passageEmbed(behaviorText);
 
     return ctx.db.transaction(() => {
-      let matcherId = ctx.db.findNearestBehaviorMatcher(store, matcherEmbed, BEHAVIOR_DEDUP_COSINE)?.id;
-      if (!matcherId) matcherId = ctx.db.createBehaviorMatcher(store, situationText, matcherEmbed, ctx.model.name);
+      // Cross-store dedup: same rationale as prediction_update. The
+      // auto-fire nudge scans the target store and global, so a duplicate
+      // in either store would surface twice every turn.
+      const existing = ctx.db.findNearestBehavior(dedupScanStores(store), behaviorEmbed, BEHAVIOR_DEDUP_COSINE);
+      const home = existing?.store ?? store;
+      const storeTag = home === store ? "" : ` in ${home}`;
 
-      let behaviorId = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE)?.id;
+      let matcherId = ctx.db.findNearestBehaviorMatcher(home, matcherEmbed, BEHAVIOR_DEDUP_COSINE)?.id;
+      if (!matcherId) matcherId = ctx.db.createBehaviorMatcher(home, situationText, matcherEmbed, ctx.model.name);
+
+      let behaviorId = existing?.id;
       if (!behaviorId) {
-        behaviorId = ctx.db.createBehavior(store, behaviorText, rationale, behaviorEmbed, ctx.model.name);
+        behaviorId = ctx.db.createBehavior(home, behaviorText, rationale, behaviorEmbed, ctx.model.name);
         ctx.db.createBehaviorEdge(matcherId, behaviorId, 1.0);
         ctx.db.addBehaviorProvenance(behaviorId, "codify", rationale);
-        return `[codified] ${store} :: "${behaviorText}" for "${situationText}"`;
+        return `[codified] ${home} :: "${behaviorText}" for "${situationText}"`;
       }
 
       ctx.db.createBehaviorEdge(matcherId, behaviorId, 1.0);
       ctx.db.addBehaviorProvenance(behaviorId, "codify", rationale);
-      const existing = ctx.db.getBehavior(behaviorId);
-      return `[linked] "${existing?.statement ?? behaviorText}" for "${situationText}" confidence=${(existing?.confidence ?? 0).toFixed(2)} (${existing?.confirm_count ?? 0}/${existing?.disconfirm_count ?? 0})`;
+      const behavior = ctx.db.getBehavior(behaviorId);
+      return `[linked${storeTag}] "${behavior?.statement ?? behaviorText}" for "${situationText}" confidence=${(behavior?.confidence ?? 0).toFixed(2)} (${behavior?.confirm_count ?? 0}/${behavior?.disconfirm_count ?? 0})`;
     });
   },
 };
@@ -761,7 +795,7 @@ const behaviorFeedbackDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const behaviorText = args.behavior as string;
     const relevant = args.relevant as boolean;
     const contextText = args.context as string;
@@ -787,13 +821,15 @@ const behaviorListDef: ToolDef = {
     "evidence count. For inspection and debugging.",
   args: {
     store: z.string().optional().describe(
-      "Which store to list. Defaults to the project store.",
+      "Which store to list. Defaults to the project store and global.",
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
-    const behaviors = ctx.db.listBehaviors(store);
-    if (behaviors.length === 0) return `No behaviors in "${store}".`;
+    const stores = args.store
+      ? [args.store as string]
+      : [ctx.defaultStore, "global"];
+    const behaviors = stores.flatMap((s) => ctx.db.listBehaviors(s));
+    if (behaviors.length === 0) return `No behaviors in "${stores.join('", "')}".`;
     return behaviors.map((b) => {
       const matchers = b.matchers.map((m) => `    - "${m.description}" (w:${m.weight})`).join("\n");
       const provenance = ctx.db.getBehaviorProvenance(b.id);
@@ -822,7 +858,7 @@ const behaviorDeleteDef: ToolDef = {
     ),
   },
   async execute(args, ctx) {
-    const store = (args.store as string) || ctx.defaultStore;
+    const store = resolveStore(args, ctx);
     const statementText = args.statement as string;
     const behaviorEmbed = await ctx.model.passageEmbed(statementText);
     const behavior = ctx.db.findNearestBehavior(store, behaviorEmbed, BEHAVIOR_DEDUP_COSINE);