@jeffober/thatch 0.1.28 → 0.1.30

package/docs/user/README.md

@@ -5,6 +5,22 @@ remember information across sessions using local embeddings and SQLite. It
 works with **OpenCode** (as a plugin), **Claude Code** (as an MCP server), and
 **Cursor** (as an MCP server).
 
+## Feature docs
+
+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
+- [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
+- [hygiene.md](hygiene.md): store maintenance signals
+- [deduplication.md](deduplication.md): duplicate detection and resolution
+- [skills.md](skills.md): structured workflow skills
+- [code-review.md](code-review.md): multi-agent code review pipeline
+- [setup.md](setup.md): installation and configuration
+- [cli.md](cli.md): command-line tool reference
+
 ## Installation
 
 ### OpenCode
@@ -26,7 +42,7 @@ For async extraction (child sessions run in the background):
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 ```
 
-Without this env var, extraction still works — the child session runs
+Without this env var, extraction still works. The child session runs
 fire-and-forget instead of asynchronously. Put it in your shell rc,
 `mise.toml` `[env]`, or `.envrc`.
 
@@ -47,8 +63,8 @@ thatch setup --claude            # project-local (writes .mcp.json, CLAUDE.md, .
 thatch setup --claude --global   # user-scoped (~/.claude/)
 ```
 
-`bun` must be on PATH (the thatch binary runs under bun). `setup` is idempotent
-— re-running it updates drifted content without clobbering unrelated config.
+`bun` must be on PATH (the thatch binary runs under bun). `setup` is idempotent.
+Re-running it updates drifted content without clobbering unrelated config.
 For a global install, `setup` prints the `claude mcp add --scope user` command
 to run instead of writing a project `.mcp.json`.
 
@@ -59,7 +75,7 @@ thatch setup --cursor            # project-local (.cursor/mcp.json, AGENTS.md, .
 thatch setup --cursor --global   # user-scoped (~/.cursor/)
 ```
 
-Cursor has no `claude mcp add` equivalent — `setup` writes `~/.cursor/mcp.json`
+Cursor has no `claude mcp add` equivalent. `setup` writes `~/.cursor/mcp.json`
 directly. Hook output is JSON-wrapped (`--json`) so Cursor injects it as
 `additional_context`.
 
@@ -76,7 +92,7 @@ Every git repo gets its own store, named after the repo's remote identity
 (e.g., `sysread/thatch`). There is also a shared `global` store for
 information that applies across all projects.
 
-Stores are created automatically — no setup required.
+Stores are created automatically. No setup required.
 
 ### Memory tools
 
@@ -106,6 +122,7 @@ Stores are created automatically — no setup required.
 | Tool | What it does |
 |------|-------------|
 | `thatch_extraction_done` | Acknowledge extraction buffer work. In the nudge fallback path, quiets the nudge while holding entries until the extractor completes. In a child extractor session, marks entries complete. Called by the model after dispatching the fact-extractor skill. |
+| `thatch_get_extraction_payload` | Retrieve the queued tool interactions for the fact-extractor sub-agent. Fetches by session ID so the full payload stays out of the main session's context window. |
 
 ### Prediction tools
 
@@ -116,6 +133,15 @@ Stores are created automatically — no setup required.
 | `thatch_prediction_list` | List all predictions in a store with matchers, confidence, and provenance. |
 | `thatch_prediction_delete` | Delete a prediction by semantic match. Edges and provenance are cascade-deleted. |
 
+### Behavior tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_behavior_codify` | Codify a self-discipline rule: when situation X arises, the agent should do Y. For the agent's own operational discipline, not user preferences. |
+| `thatch_behavior_feedback` | Record ham/spam feedback on a surfaced behavior. `relevant: true` (ham) confirms the rule applies; `relevant: false` (spam) disconfirms. Trains the classifier. |
+| `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. |
+
 ## Automatic behaviors
 
 Beyond the tools, thatch hooks into opencode itself:
@@ -128,33 +154,42 @@ Beyond the tools, thatch hooks into opencode itself:
   maintenance signals when there are any: duplicate candidates pending review,
   memories neither updated nor recalled in 90+ days, and memories scoped to
   git branches that no longer exist. The agent is asked to tend the store when
-  convenient — thatch never deletes memories on its own.
+  convenient. Thatch never deletes memories on its own.
 - **Write-time similarity warning.** Saving a memory that closely resembles an
   existing one succeeds, but the response warns the agent and lists the
   similar entries so it can merge them or record that they're distinct.
 - **Fact extraction.** Thatch buffers the session's recent tool calls (up
   to 20, per session). When the session goes idle, the plugin creates a
-  child session and prompts it to run the fact-extractor skill directly —
-  no nudge text in your conversation. The child writes memories via
+  child session and prompts it to run the fact-extractor skill directly. No
+  nudge text in your conversation. The child writes memories via
   `thatch_memory_remember` and is cleaned up when it finishes. A toast
   notification shows the results (`[thatch] new: 2, updated: 1`). If the
   direct path fails, a nudge is injected into the next message as a
   fallback. On Claude Code and Cursor, the nudge-and-acknowledge path is
   the only mechanism (no SDK client to create child sessions). The agent
-  does the writing — thatch never saves memories on its own.
-- **Recall and prediction toasts.** When your prompt matches stored
-  memories or learned decision patterns, thatch injects a synthetic nudge
-  (invisible to you, visible to the agent) and fires a toast notification
-  (`[thatch] recalled 3 memories` or `[thatch] 2 predictions surfaced`).
-  The toast is ephemeral — it fades after a few seconds.
+  does the writing. Thatch never saves memories on its own.
+- **Recall, prediction, and behavior toasts.** When your prompt matches stored
+  memories, learned decision patterns, or codified behaviors, thatch injects a
+  synthetic nudge (invisible to you, visible to the agent) and fires a toast
+  notification (`[thatch] recalled 3 memories`, `[thatch] 2 predictions
+  surfaced`, or `[thatch] 1 behavior surfaced`). The toast is ephemeral. It
+  fades after a few seconds.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
 - **Prediction auto-fire.** When a prompt matches learned contexts, thatch
   injects a `User decision model` block alongside the recall nudge. The block
   lists scored predictions (confidence, evidence count) that the agent can
   follow silently (strong prediction), surface to the user (ambiguous), or
-  use to update the model after the user responds. No extra model call —
-  the prediction search reuses the same prompt embedding as the recall nudge.
+  use to update the model after the user responds. No extra model call. The
+  prediction search reuses the same prompt embedding as the recall nudge.
+- **Behavior auto-fire.** When a prompt matches codified behavior matchers,
+  thatch injects a `Situational behaviors` block listing scored rules
+  (confidence, evidence count). The agent evaluates each rule against the
+  current situation: if relevant (ham), it follows the rule and calls
+  `behavior_feedback` with `relevant: true`; if not relevant (spam), it calls
+  `behavior_feedback` with `relevant: false`. This trains the classifier so
+  future nudges are more accurate. No extra model call. It reuses the same
+  embedding as recall and prediction.
 
 ### Setup detection (Claude Code and Cursor)
 
@@ -186,13 +221,15 @@ With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
 
 ### Code review skills
 
-Seven specialist review lenses, each a self-contained static-analysis pass:
+Eight specialist review lenses, plus the synthesizer, context, followup,
+response, walkthrough, and workflow skills that support the review pipeline:
 
 | Skill | Focus |
 |-------|-------|
 | `thatch-review-pedantic` | Mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts. |
 | `thatch-review-acceptance` | Behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions. |
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
+| `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
 | `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. |
@@ -204,6 +241,7 @@ Seven specialist review lenses, each a self-contained static-analysis pass:
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |
 | `thatch-change-walkthrough` | Explains a change to the user as a teaching walkthrough: researches each affected workflow at the merge-base, teaches current behavior, then overlays the modifications with file:line citations. |
 | `thatch-code-walkthrough` | Explains a feature, module, or workflow to the user as a teaching walkthrough with file:line citations. Also used to draft high-level docs for new or undocumented features. |
+| `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
 
 ### Writing skills
 
@@ -224,7 +262,7 @@ Seven specialist review lenses, each a self-contained static-analysis pass:
 | Skill | opencode | Claude Code | Cursor |
 |-------|----------|-------------|--------|
 | Memory skills (4) | Yes | Yes | Yes |
-| Review specialists (7) | Yes | Yes | Yes |
+| Review specialists (8) | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
 | Review context + code archaeology | Yes | Yes | Yes |
 | Review followup | Yes | Yes | Yes |
@@ -333,11 +371,11 @@ No configuration needed. The default behavior:
 
 **Changing `THATCH_MODEL` on an existing database:** memories embedded by a
 model with a different vector dimension are skipped by search (not corrupted,
-not deleted — just invisible) until re-saved. There is no automatic
+not deleted, just invisible) until re-saved. There is no automatic
 re-embedding.
 
 ## Privacy
 
 - All data stays on your machine. No network calls for embeddings or storage.
 - The embedding model is downloaded once from Hugging Face Hub on first use, then cached locally.
-- Your memories are stored in a local SQLite database — nothing is sent to any service.
+- Your memories are stored in a local SQLite database. Nothing is sent to any service.

package/docs/user/behavior-engine.md

@@ -0,0 +1,85 @@
+# Behavior Engine
+
+Thatch lets your agent codify self-discipline rules: "when situation X
+arises, I should do Y." These are the agent's own operational rules,
+not your preferences (those are predictions). The agent grades its own
+rules with ham/spam feedback.
+
+## How it works
+
+Each behavior has two parts:
+
+- **Matcher**: a description of the situation that triggers the
+  rule ("about to commit changes to the repo"). Embedded and matched
+  against your prompt.
+- **Behavior**: the rule itself ("run mise run check before
+  committing"). What the agent reads and follows.
+
+When your prompt matches a behavior matcher above the threshold
+(default 0.60), thatch injects a `Situational behaviors` block into
+the agent's context. The block looks like:
+
+```text
+[thatch] Situational behaviors
+- [0.58 conf, 1 tests] When about to commit changes to the repo:
+  do Run mise run check (tsc + bun test + markdownlint) before
+  committing. Never commit code that fails the quality gate.
+```
+
+The agent evaluates each surfaced rule against the current situation.
+If relevant (ham), it follows the rule and calls `behavior_feedback`
+with `relevant: true`. If not relevant (spam), it calls
+`behavior_feedback` with `relevant: false`. This trains the classifier
+so future nudges are more accurate.
+
+## Default behaviors
+
+Thatch auto-seeds a set of default behaviors into the global store on
+first run. These fire across all projects without manual setup:
+
+| Rule | Fires on | What it does |
+|------|----------|-------------|
+| Session wrap-up | "wrapping up," "loose ends," "signing off" | Check git status, untracked files, stale artifacts before the session ends. Read-only. |
+| Work finalization | "committing," "merging," "closing out," "ready to merge" | Check git status, branch memory consolidation, follow-up TODOs. Read-only. |
+| Research new project | "new project," "unfamiliar codebase," "new ticket" | Check coverage, naming drift, migration evidence, load archaeology skill. |
+| Day turnover (coding) | "continuing from yesterday," "picking up where I left off" | Check how far origin/main moved since merge-base, suggest rebase. |
+| Day turnover (PR) | "continuing the PR," "picking up the branch" | Check for new upstream review comments on the open PR. |
+| Day turnover (review) | "continuing the review," "picking up the review" | Check for new upstream comments and responses to our comments. |
+| Snag or dead end | "dead end," "red herring," "that did not work" | Save a memory about the wrong path so future sessions skip it. Save-only. |
+| Debugging archaeology | "debugging," "why is this broken," "what changed" | Git archaeology before proposing a fix, look for orphaned code from removed behavior. |
+| Planning archaeology | "planning a change," "how should we approach" | Git archaeology to understand design intent before proposing changes. |
+
+Default behaviors are plugin-owned. The agent can ham/spam them
+(adjust confidence, controls whether they fire) but cannot change the
+behavior text or trigger. When thatch updates a default behavior in a
+new release, the old version is automatically replaced on next startup.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_behavior_codify` | Create a self-discipline rule: situation, behavior, rationale. |
+| `thatch_behavior_feedback` | Record ham/spam feedback on a surfaced behavior. `relevant: true` confirms; `relevant: false` disconfirms. |
+| `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. |
+
+## Configuration
+
+- `THATCH_BEHAVIOR_THRESHOLD`: cosine score threshold for behavior
+  auto-fire. Defaults to 0.60. Same rationale as prediction threshold.
+
+## Limitations
+
+- Behaviors are the agent's own rules, not your preferences. Use
+  `thatch_prediction_update` for user preferences instead.
+- The agent creates behaviors based on its own judgment. Thatch never
+  creates behaviors on its own (except the default seeds).
+- Ham/spam feedback adjusts confidence but never reaches 0 or 1.
+  Delete a wrong behavior with `thatch_behavior_delete`.
+- Behaviors are per-store. The default behaviors live in the global
+  store (shared across projects). Agent-codified behaviors default to
+  the project store.
+
+See [memory.md](memory.md) for the base memory system and
+[prediction-engine.md](prediction-engine.md) for the user decision
+model.

package/docs/user/cli.md

@@ -0,0 +1,98 @@
+# CLI
+
+Thatch ships with a command-line tool for inspecting memories and
+running maintenance tasks outside the agent. It requires `bun` on your
+PATH.
+
+## Memory inspection
+
+```bash
+thatch stores                  # list all stores
+thatch list [store]            # list memory labels in a store
+thatch show <label> [store]    # display one memory by label
+thatch forget <label> [store]  # delete one memory by label
+thatch search <query> [store]  # semantic search (cosine similarity)
+```
+
+Store defaults to your current git repo (detected from `git remote
+get-url origin`). Use `global` for the shared global store. Use `all`
+with `search` to search the project store and `global` together.
+
+`search` uses the same cosine-similarity search as
+`thatch_memory_recall`. Results include a similarity score for each
+match. Limited to 10 results.
+
+## Maintenance
+
+```bash
+thatch hygiene                 # print the hygiene report
+thatch reminder [--json]       # print the session-start reminder
+```
+
+`hygiene` prints the standalone hygiene report (duplicate candidates,
+stale entries, orphaned branch memories). See
+[hygiene.md](hygiene.md).
+
+`reminder` prints the full session-start reminder including the
+hygiene report. The `--json` flag wraps the output as
+`{"additional_context": "..."}` for Cursor's hook format. These
+commands are normally called by hooks, not by hand, but you can run
+them to see what the agent sees at session start.
+
+## Priming a new project
+
+```bash
+thatch prime
+```
+
+Runs the `thatch-project-primer` skill via an external CLI. Thatch
+searches your PATH for `opencode`, `agent` (Cursor CLI), or `claude`
+in that order. The first one found is used to run the primer, which
+investigates the codebase from multiple angles and writes foundational
+memories.
+
+This is the same skill the agent can load manually, but `thatch prime`
+runs it in a dedicated session focused on project investigation.
+
+## Infrastructure commands
+
+These commands are called by hooks installed by `thatch setup`. You
+should not need to run them by hand.
+
+```bash
+thatch mcp                      # start the stdio MCP server
+thatch buffer-batch             # append tool batch to queue (Claude Code hook)
+thatch buffer-tool              # append single tool to queue (Cursor hook)
+thatch flush-tools [--json]     # peek queue + print nudges (hook)
+thatch flush-predictions [--json]  # prediction-only nudge (hook)
+thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
+```
+
+## Environment variables
+
+| Variable | Default | What it controls |
+|----------|---------|-----------------|
+| `THATCH_DB_PATH` | `~/.config/thatch/thatch.db` | SQLite database path |
+| `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Embedding model name |
+| `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 |
+| `CLAUDE_PROJECT_DIR` | `process.cwd()` | Claude Code project directory |
+| `CURSOR_PROJECT_DIR` | (falls through) | Cursor project directory |
+| `CLAUDE_CONFIG_DIR` | `~/.claude` | Claude Code config directory |
+| `CURSOR_CONFIG_DIR` | `~/.cursor` | Cursor config directory |
+
+## Limitations
+
+- Requires `bun` on PATH. Thatch does not bundle its own runtime.
+- `search` is limited to 10 results. There is no pagination.
+- `prime` requires an external CLI (`opencode`, `agent`, or `claude`)
+  on PATH. If none is found, it exits with an error.
+- Infrastructure commands (`mcp`, `buffer-batch`, `buffer-tool`,
+  `flush-tools`, `flush-predictions`) are meant for hooks, not manual
+  use. Running them by hand can produce confusing output.
+- There is no web UI or dashboard. All inspection is through the CLI
+  or the agent's tool calls.
+
+See [setup.md](setup.md) for installation and [memory.md](memory.md)
+for the memory system.

package/docs/user/code-review.md

@@ -0,0 +1,73 @@
+# Code Review
+
+Thatch ships a multi-agent code review pipeline. Eight specialist
+review lenses run in parallel, then a synthesizer verifies and
+deduplicates their findings into a single report.
+
+## How it works
+
+The coordinator skill (`thatch-code-review`, opencode-only) orchestrates
+the review:
+
+1. **Resolve the target**: fetch origin, compute merge-base against
+   `origin/main`, support branch/PR/explicit range.
+2. **Gather project context**: PR descriptions, git archaeology,
+   ticket references, TODO markers, prior reviews, project memory.
+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
+   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,
+   severity is justified), deduplicates by root cause, and produces
+   the final report.
+
+## The eight specialists
+
+| Skill | What it checks |
+|-------|-------------|
+| `thatch-review-pedantic` | Spelling, naming, doc accuracy, specs, guidelines, stale artifacts, structural conventions (file/directory placement). |
+| `thatch-review-acceptance` | UX coherency, behavioral delta, integration effects, user assumptions. |
+| `thatch-review-state-flow` | Module boundaries, implicit state machines, error propagation, separation of concerns. |
+| `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
+| `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
+| `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. |
+
+Each specialist is a self-contained static-analysis pass. They can run
+individually or as part of the coordinated review.
+
+## Follow-up rounds
+
+After the author responds or pushes changes, `thatch-review-followup`
+verifies whether prior findings were adequately addressed before
+deciding whether to re-run the full review. The author must either
+fix the code, prove the finding is not a concern with a checkable
+argument, or file a follow-up ticket with a risk explanation.
+
+## Author-side response
+
+When you receive review comments on your own PR,
+`thatch-review-response` helps you triage findings (legitimate,
+intentional, false positive, unlikely edge case), fix bugs one by
+one, reply on each thread, and post a top-level summary comment.
+
+## Limitations
+
+- The coordinator (`thatch-code-review`) is opencode-only. It
+  requires sub-agent support to dispatch parallel specialists. On
+  Claude Code or Cursor, run specialists individually instead.
+- The review quality depends on the model. Weak models may
+  hallucinate findings or miss subtle issues.
+- The synthesizer verifies cited text exists, but it does not
+  re-run the specialist's analysis. A specialist that cites
+  correctly but reasons incorrectly will pass verification.
+- The review covers the diff (merge-base..HEAD). It does not
+  review the entire codebase. Pre-existing bugs are only found
+  if the change makes them more reachable.
+
+See [skills.md](skills.md) for the full skill list and
+[default-behaviors.md](default-behaviors.md) for the review-adjacent
+behavior rules (day-turnover-review, planning-git-archaeology).

package/docs/user/deduplication.md

@@ -0,0 +1,70 @@
+# Deduplication
+
+When two memories are very similar, thatch surfaces them as duplicate
+candidates. The agent decides whether to merge, keep both, or mark
+them as distinct. Thatch never merges or deletes memories on its own.
+
+## How it works
+
+The dedup cycle is agent-driven:
+
+1. **Find pairs.** `thatch_find_duplicates` searches for memory pairs
+   whose cosine similarity exceeds the threshold (default 0.85). Pairs
+   already reviewed via `thatch_dedup_mark_checked` are skipped. Related
+   pairs are grouped into clusters: a cluster of 3+ labels usually
+   means one topic fragmented across entries that should be consolidated.
+
+2. **Classify.** The agent loads the `thatch-dedup-classifier` skill,
+   reads both memories, and decides the relationship:
+   - **Duplicate**: same information, merge into one.
+   - **Supplement**: related but distinct, keep both.
+   - **Contradiction**: conflicting information, resolve.
+   - **Unrelated**: similar wording, different topic, mark and ignore.
+
+3. **Reconcile.** For duplicates, the agent merges by updating one
+   memory with `overwrite: true` and deleting the other with
+   `thatch_memory_forget`. For contradictions, the agent resolves the
+   conflict and updates. For supplements and unrelated pairs, no
+   changes needed.
+
+4. **Record verdict.** The agent calls `thatch_dedup_mark_checked` with
+   the pair labels and the verdict. This stops `find_duplicates` from
+   re-reporting the pair.
+
+## Verdict lifecycle
+
+Verdicts are not permanent. Overwriting either memory with
+`overwrite: true` clears all verdicts involving that memory.
+Deleting a memory with `thatch_memory_forget` also clears its
+verdicts. This means a merged pair can re-flag if the merge creates
+a new similarity with a different memory.
+
+This is intended. A merge changes the content, which may create new
+duplicate relationships that should be reviewed.
+
+## When it fires
+
+The dedup cycle is not automatic. It fires when:
+
+- The agent calls `thatch_find_duplicates` directly (you ask, or the
+  hygiene report motivates it).
+- The hygiene report at session start shows duplicate candidates,
+  prompting the agent to run `find_duplicates` and work through them.
+- The write-time similarity warning fires on `thatch_memory_remember`,
+  alerting the agent to near-duplicate entries.
+
+## Limitations
+
+- Similarity is cosine only. Two memories can say the same thing in
+  different words and not be flagged. Two memories with similar wording
+  but different meaning can false-flag.
+- The 0.85 threshold is hardcoded. There is no configuration for it.
+- The agent drives the cycle. Thatch never merges or deletes memories
+  on its own. If the agent does not call `thatch_find_duplicates`,
+  duplicates accumulate.
+- Verdicts are cleared when either memory is updated. A merged pair can
+  re-flag if the merge creates a new similarity with a different memory.
+  This is intended, but it means dedup is not a one-time fix.
+
+See [hygiene.md](hygiene.md) for the hygiene report and
+[memory.md](memory.md) for the memory tools.

package/docs/user/default-behaviors.md

@@ -0,0 +1,75 @@
+# Default Behaviors
+
+Thatch auto-seeds a set of default behaviors into the global store on
+first run. These are self-discipline rules the agent follows when your
+prompt matches the trigger context. They fire across all projects
+without manual setup.
+
+## How it works
+
+Default behaviors use the behavior engine (see
+[behavior-engine.md](behavior-engine.md)). On every prompt, thatch
+embeds the text and searches for matching behavior matchers. If a
+matcher scores above the threshold (default 0.60), the behavior is
+injected as a `Situational behaviors` nudge.
+
+The rules are plugin-owned. The agent can ham/spam them (adjust
+confidence, controls whether they fire) but cannot change the behavior
+text or trigger. When thatch updates a default behavior in a new
+release, the old version is automatically replaced on next startup.
+
+## What ships
+
+| Rule | Fires on | What it does |
+|------|----------|-------------|
+| Session wrap-up | "wrapping up," "loose ends," "signing off," "clean up" | Check git status, untracked files, stale artifacts before the session ends. Read-only. |
+| Work finalization | "committing," "merging," "closing out," "ready to merge," "shipping" | Check git status, branch memory consolidation, follow-up TODOs. Read-only. |
+| Research new project | "new project," "unfamiliar codebase," "new ticket" | Check coverage, naming drift, migration evidence. Load archaeology skill. |
+| Day turnover (coding) | "continuing from yesterday," "picking up where I left off" | Check how far origin/main moved since merge-base, suggest rebase. |
+| Day turnover (PR) | "continuing the PR," "picking up the branch" | Check for new upstream review comments on the open PR. |
+| Day turnover (review) | "continuing the review," "picking up the review" | Check for new upstream comments and responses to our comments. |
+| Snag or dead end | "dead end," "red herring," "that did not work" | Save a memory about the wrong path so future sessions skip it. Save-only. |
+| Debugging archaeology | "debugging," "why is this broken," "what changed" | Git archaeology before proposing a fix. Look for orphaned code from removed behavior. |
+| Planning archaeology | "planning a change," "how should we approach" | Git archaeology to understand design intent before proposing changes. |
+
+## Version-gated updates
+
+Each default behavior carries a version stamp in its rationale text.
+On startup, thatch compares the stored stamp against the current
+package version. If they differ (the behavior was seeded by an older
+release), the old behavior is deleted and the new one is created
+with the updated content. This mirrors how stale skill cleanup
+works: updating a behavior in a new release automatically replaces
+the old version on every install.
+
+## Customizing
+
+You cannot edit the default behaviors directly (they are
+plugin-managed). But you can:
+
+- **Ham/spam them**: Call `thatch_behavior_feedback` with
+  `relevant: true` or `relevant: false` when a default behavior
+  surfaces. This adjusts confidence and controls whether it fires
+  in future sessions.
+- **Add your own**: Call `thatch_behavior_codify` to add custom
+  rules for situations the defaults don't cover. Custom behaviors
+  coexist with the defaults.
+- **Delete a default**: Call `thatch_behavior_delete` with the
+  behavior statement text. This removes it, but it will re-seed on
+  next startup if it's still in the defaults list. To permanently
+  remove a default, it must be removed from the thatch source code.
+
+## Limitations
+
+- Default behaviors live in the global store. They fire across all
+  projects. There is no per-project default behavior.
+- The trigger is semantic (cosine on the situation text), not keyword
+  matching. A prompt that means the same thing but uses different
+  words will still match. A prompt that uses the same words but means
+  something different may false-fire.
+- The 0.60 threshold is tuned to reduce false fires. If you see
+  unwanted behavior nudges, ham them (relevant: false) to lower
+  confidence. If you see missing nudges, check the threshold.
+
+See [behavior-engine.md](behavior-engine.md) for the full engine
+documentation and [skills.md](skills.md) for the skill system.

package/docs/user/extraction.md

@@ -0,0 +1,74 @@
+# Fact Extraction
+
+Thatch buffers your session's tool calls and extracts durable facts from
+them into memories. This happens automatically, without any prompt from
+you.
+
+## How it works
+
+1. **Buffering**: As the session runs, thatch records tool calls (read,
+   edit, bash, grep, etc.) in an in-memory ring buffer (up to 20 per
+   session). The buffer is a parallel data structure, not derived from
+   conversation history.
+
+2. **Extraction**: When the session goes idle (after the agent's turn
+   completes), the plugin creates a child session and prompts it to run
+   the `thatch-fact-extractor` skill. The child fetches the buffered
+   tool interactions via `thatch_get_extraction_payload`, extracts
+   durable facts, and writes them as memories via
+   `thatch_memory_remember`.
+
+3. **Cleanup**: When the child finishes, the parent's buffer is
+   drained and a toast notification shows the results (`[thatch] new: 2,
+   updated: 1`). The child session is deleted.
+
+You see the toast. You do not see the nudge or the child session. The
+extraction runs in the background and does not interrupt your
+conversation.
+
+## Fallback path (Claude Code and Cursor)
+
+On MCP hosts (Claude Code, Cursor), there is no SDK client to create
+child sessions. The extraction nudge is injected into the next user
+message instead. The agent dispatches a sub-agent to run the
+fact-extractor skill, then calls `thatch_extraction_done` to acknowledge.
+
+## What gets extracted
+
+The fact-extractor skill decides what is worth saving. It looks for:
+
+- Durable project facts (architecture, conventions, design decisions)
+- Non-obvious gotchas and footguns
+- Data model relationships
+- User preferences and corrections
+
+It does NOT save:
+
+- Point-in-time facts (current file locations, line numbers, function
+  names)
+- Commit hashes or branch-specific history
+- Anything re-derivable from the codebase faster than recalling it
+
+## Configuration
+
+- `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`: enables async
+  extraction (child sessions run in the background, fire-and-forget).
+  Without this, extraction still works but the child session runs
+  synchronously (blocking the turn briefly). Put it in your shell rc,
+  `mise.toml [env]`, or `.envrc`. OpenCode only; not needed for
+  Claude Code or Cursor.
+
+## Limitations
+
+- The buffer caps at 20 tool interactions per session. If the session
+  runs long, older interactions are dropped before the extraction fires.
+- Extraction only runs when the session goes idle. If the agent is
+  continuously active, the buffer grows until 20 and then stops
+  recording.
+- The fact-extractor is an LLM. Its quality depends on the model.
+  Weak models may miss durable facts or save point-in-time noise.
+- Compaction does not affect the buffer. The buffer is a parallel
+  data structure that survives conversation compaction.
+
+See [memory.md](memory.md) for the memory system the extractor
+writes to.