klypix-mcp 1.106.2 → 1.107.2

package/A2A.md

@@ -55,7 +55,7 @@ the skills below.
 |---|---|---|
 | `make_board` | Create a new `.klypix` from cards + connections | a `.klypix` **FilePart** + summary |
 | `remember` | Append cards/decisions to an existing canvas (positions preserved) | result summary; flat card appends also return a `.klypix` FilePart |
-| `learn_skill` | Capture a reusable how-to / gotcha as a 🛠 skill card — resurfaces every session | result summary |
+| `learn_skill` | Capture a reusable how-to / gotcha as a 🛠 skill card — kept until corrected; shown first to sessions that touch the files it names | result summary |
 | `recall` | Search card text/titles/`#tags` across the vault | matching cards (text) |
 | `read_canvas` | Read one canvas (cards, graph, `[[links]]`) + its images | markdown + image FileParts |
 | `list_canvases` | List canvases with counts | text |

package/README.md

@@ -56,8 +56,8 @@ You need **Node.js 20 or newer** (`node -v`).
   `brain_sync` in other hosts. A correction replaces the old decision, and the old card stays as
   history.
 - **A heads-up when work overlaps.** Each session says what it is doing and which files it expects
-  to touch. When two sessions name the same file, both are warned. KLYPIX warns; it never blocks an
-  edit. This works on one computer. With [KLYPIX network](https://klypix.com/network)
+  to touch. When two sessions name the same file, both are warned. For overlapping work KLYPIX
+  warns; it never blocks an edit. This works on one computer. With [KLYPIX network](https://klypix.com/network)
   installed on both computers (klypix-mcp 1.106.0 or later), it also lists sessions in the same
   project on a teammate's computer.
 - **Notes and handoffs between sessions.** An agent can leave a note for another session, even one
@@ -69,6 +69,11 @@ You need **Node.js 20 or newer** (`node -v`).
   git command that would sweep another live session's uncommitted work into your commit is stopped.
   A command that would throw work away saves a rescue copy first, then asks you. It covers git
   commands run through Claude Code's tools, on one computer.
+- **Lessons that catch the repeat mistake.** A lesson the brain recorded can become a project rule
+  that a person approves: a check of the diff, with no AI at check time. A rule warns when a session
+  plans its files, while it edits and at commit. Only a rule the person approves as blocking stops
+  the work: Claude Code before it writes the forbidden line (Codex is warned), and an opt-in git
+  hook at commit, for any tool or person. Rules check the diff; they do not run your tests.
 - **A file you own.** The brain is one `.klypix` file in your repo: a plain ZIP, versioned with
   Git. The engine is Apache-2.0, runs on your machine, and works without the KLYPIX app or an
   account. Brain data stays in your files; your agent's model provider still receives what the
@@ -88,7 +93,7 @@ has the details.
 | **Claude Desktop** | A one-time config entry | The KLYPIX app's Settings, or by hand |
 | **Claude, as a plugin** | One pinned version, keyword search, no hooks | [klypix-plugin](https://github.com/dahshanlabs/klypix-plugin) |
 
-klypix-mcp 1.106.0 has 26 MCP tools on Linux and macOS and 27 on Windows, where `show_in_klypix` is
+klypix-mcp has 27 MCP tools on Linux and macOS and 28 on Windows, where `show_in_klypix` is
 added. `npx klypix-mcp doctor` shows the count for your install.
 
 > **One project. Many agents. One current understanding.**
@@ -118,14 +123,15 @@ tool's official documentation and says that KLYPIX wrote it) · [klypix.com/klyp
 - **[Reference](#reference):** [How the brain works](#how-the-brain-works) ·
   [Supported hosts](#supported-hosts-and-their-integration-level) ·
   [Running as a Claude plugin](#running-as-a-claude-plugin) · [Task briefing](#task-briefing) ·
-  [Capture and corrections](#capture-and-corrections) · [Presence and task intent](#presence-and-task-intent) ·
+  [Capture and corrections](#capture-and-corrections) · [Project rules](#project-rules-lessons-that-stop-the-repeat) ·
+  [Presence and task intent](#presence-and-task-intent) ·
   [Overlap warnings](#overlap-warnings) ·
   [Teammates on other computers](#teammates-on-other-computers-klypix-network) ·
   [Handoffs and messages](#handoffs-and-messages) · [Evidence-gated completion](#evidence-gated-completion) ·
   [Human control in KLYPIX](#human-control-in-klypix) · [Measure it yourself](#measure-it-yourself) ·
   [Git and concurrency](#git-and-concurrency) ·
   [The git guard for a shared checkout](#whose-is-this-the-git-guard-for-a-shared-checkout) ·
-  [The command line](#the-command-line) · [The verbs](#the-verbs-26-and-27-on-windows) ·
+  [The command line](#the-command-line) · [The verbs](#the-verbs-27-and-28-on-windows) ·
   [One file you can hold](#one-file-you-can-hold) · [Use it as a library](#use-it-as-a-library) ·
   [A2A](#also-speaks-a2a-protocol-v030--experimental) ·
   [Updates](#updates--the-propagation-contract) · [Security and permissions](#security-and-permissions) ·
@@ -561,9 +567,9 @@ on cards, and, on a call that needs the running app, the app's bridge token (abo
 
 | Where | What | Why |
 |---|---|---|
-| Your project | Only what a tool call asks for: `brain.klypix` (`brain_note` and the other brain tools), canvases (`create_canvas`, `add_to_canvas`), `klypix-map/graph.json` when `project_map_scan` is called, and `.klypix/claims/<owner>.json` when `brain_sync` is asked to publish a release claim. During a brain write it holds `.claude/brain-capture.lock`, creating the `.claude/` folder if the project has none. The lock file is deleted after the write; the folder stays. Creating a canvas briefly holds `.klypix-create.lock` in the folder. | The KLYPIX app and every other session that writes the brain use the same locks, so two writers never overwrite each other. |
+| Your project | Only what a tool call asks for: `brain.klypix` (`brain_note` and the other brain tools), canvases (`create_canvas`, `add_to_canvas`), `klypix-map/graph.json` when `project_map_scan` is called, `.klypix/claims/<owner>.json` when `brain_sync` is asked to publish a release claim, and `.klypix/rules.json` when `brain_rules` adds, approves or retires a rule. Only when you run `npx klypix-mcp check --install-hook`: a marked block in `.git/hooks/pre-commit`, `pre-push` and `post-commit`; `npx klypix-mcp rules allow` keeps its one-hour exception in `.git/klypix-rules-allow.json`. During a brain write it holds `.claude/brain-capture.lock`, creating the `.claude/` folder if the project has none. The lock file is deleted after the write; the folder stays. Creating a canvas briefly holds `.klypix-create.lock` in the folder. | The KLYPIX app and every other session that writes the brain use the same locks, so two writers never overwrite each other. |
 | The plugin's data folder (`KLYPIX_PLUGIN_DATA`) | Connection receipts (`.supervisors/`), the running-server heartbeat (`.running-servers.json`), the list of projects whose brains you used (`registry.json`, which `search_all_brains` reads), and the last version and git tag seen in each project (`ship-observations/`). Also `extracted/`: copies of the PDFs, Office and other files `read_card_contents` hands to your AI tool as a local path, taken from the canvas you asked about. | Only this server uses these files. If `KLYPIX_PLUGIN_DATA` is not set, or still contains a `${...}` that was never filled in, it uses `CLAUDE_PLUGIN_DATA`. If neither is usable, the files go in `~/.claude/project-brain`, except `extracted/`, which then goes in `<system temp>/klypix-mcp/extracted` (where it always goes outside plugin mode). |
-| `~/.claude/project-brain` (shared) | Presence lanes (`sessions/`), write locks (`locks/`), restore points (`history/`), and small records built from your brain: `.capture-gap.json`, and `enrichment/`, `provenance/`, `.brief-cache-*` and `.guards-*` when the tools that use them run. | Your other KLYPIX sessions on this computer (Claude Code, Codex, Cursor, the app) use the same files on purpose. Through them, a plugin session and a terminal session on the same project see each other, get warnings when they plan to edit the same files, and pass notes. Restore points are kept here so that `npx klypix-mcp brain-history` can still undo a brain write after you remove the plugin. |
+| `~/.claude/project-brain` (shared) | Presence lanes (`sessions/`), write locks (`locks/`), restore points (`history/`), and small records built from your brain: `.capture-gap.json`, and `enrichment/`, `provenance/`, `.brief-cache-*` and `.guards-*` when the tools that use them run. `rules/` counts how often each project rule fired, blocked or was overridden on this computer. | Your other KLYPIX sessions on this computer (Claude Code, Codex, Cursor, the app) use the same files on purpose. Through them, a plugin session and a terminal session on the same project see each other, get warnings when they plan to edit the same files, and pass notes. Restore points are kept here so that `npx klypix-mcp brain-history` can still undo a brain write after you remove the plugin. |
 
 **`brain_reopen`.** Sometimes a session leaves a note for another session that has already closed.
 An agent can then call `brain_reopen`, and KLYPIX asks you first: in chat with *Reopen* and *Not
@@ -586,7 +592,10 @@ Every other host gets a bounded ~2.8KB task capsule from one `brain_sync` call,
 always-loaded `AGENTS.md` block that tells the agent to make that call at task start, when scope
 changes, and on completion. The gateway capsule is lexical-fast by design. A newly captured open
 gap can claim a labeled `RECENT OPEN` slot only after clearing the normal lexical-relevance floor,
-so fresh relevant findings are not crowded out by older area vocabulary.
+so fresh relevant findings are not crowded out by older area vocabulary. When the call declares
+`files`, the lessons that name those files come first, under "Lessons for your files": at most
+four, ranked exact path, then file name, glob and folder. The Claude Code brief does the same for
+the files the checkout is changing (uncommitted, and the last three commits), then lists the newest.
 
 Briefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —
 there are no lifecycle hooks on those hosts.
@@ -648,7 +657,9 @@ On Claude Code, decisions are captured automatically at turn end from inline `
 markers in the transcript, deduped, under a capture lock.
 
 A marker can end with optional suffixes, in any order: `closes: <card title or [[wikilink]]>`,
-`ev: <file[:line]>, PR#<n>`, `verify: <command>` and `q: <the question this answers?>`. They count
+`ev: <file[:line]>, PR#<n>`, `verify: <command>`, `q: <the question this answers?>` and
+`rule: <glob>[,<glob>] never "<text>"` (or `never /<regex>/`, `must "<text>"`,
+`listed-in <file>[,<file>]`, `keep-eol`, `costly`). They count
 only as one run at the end of the line, written lowercase as `key: value`, and each value must
 have its key's shape: references for `ev:`, a command for `verify:`, a question (question word
 first, `?` last) for `q:`. Anything else is kept as card text, so "a Q: and A: layout", "the ev:
@@ -663,6 +674,13 @@ content words and under half the card's) is appended to that card as a dated `(~
 instead. The card keeps its date, colour and probe, and previews show the newest amendment first.
 The correction lands and nothing is lost.
 
+A `rule:` suffix makes a new lesson (a decision, `+` or `!`) rule-ready. Its globs must name files
+tracked in the repository and a `/regex/` must compile; the rule lands as a visible
+`⚙ rule candidate:` line on a 🛠️ card, and `brain_rules` propose reads it before any prose. It
+checks nothing until a person approves the rule. A rule that fails those checks is not recorded,
+the lesson is, and the hook says why on the next prompt. `brain_note` takes the same suffix at the
+end of its text.
+
 The Stop hook reads the whole transcript every time, so a `~` or `✓` line applies once. A marker
 that an older hook (1.85 or 1.86.0) already captured is not captured again after an upgrade. If
 1.86.0 cut the note short, the stub is restored to the full text in place. When a marker does not
@@ -684,6 +702,28 @@ only (explicit correction cues, opposite-polarity pairs), never mere topical sim
 means no contradiction signal was found — not verified consistency. A memory that cannot disagree
 with you is flattery.
 
+### Project rules: lessons that stop the repeat
+
+Some lessons can be checked in a diff: *every new route must also be in the route list*, *tests
+in this folder must import shared code relatively*, *this file's line endings must not change*. `brain_rules` turns those
+lessons into rules in `.klypix/rules.json`, each citing the card it came from. A person approves
+each rule with a code only they can print (`npx klypix-mcp rules code promote <ids>`). Until then
+the rule is a candidate and checks nothing.
+
+An active rule runs in three places: `brain_sync` names the rules for a session's files, the edit
+hook reports findings to Claude Code and Codex as they edit, and the opt-in git hooks
+(`npx klypix-mcp check --install-hook`) print them at commit and push. Rules warn by default. A
+rule the person approves with `--block` stops the commit or push for any tool or person, and stops
+Claude Code before it writes a forbidden line; Codex is only warned, because its hooks cannot
+deny. A check is glob, regex and line-ending work over the diff: it takes
+milliseconds, runs offline and uses no model. Overrides, bypasses and false alarms are recorded in
+the brain, and `npx klypix-mcp rules` shows each rule's blocks, overrides and false alarms.
+
+How to write, approve and retire rules: [docs/brain-rules.md](docs/brain-rules.md). To see what a
+set of rules would have flagged on a repository's own history, `scripts/brain-rules-proof.mjs`
+replays them over its pull requests and failed Actions logs, with what those runs cost.
+A walk-through for teams: [Stop AI agents repeating the same mistakes](https://klypix.com/guides/stop-agents-repeating-mistakes).
+
 ### Presence and task intent
 
 An active session means an authorized MCP connection or host lifecycle adapter that heartbeated
@@ -842,6 +882,22 @@ record and every list say the session wrote none. If the session resumes and com
 the drafted card is archived at the next pass. Three drafts per pass at most; a draft can never
 fail the sync that triggered it.
 
+**Conversation coverage.** A card and the automatic reply tail can miss a later request.
+Taking a card now checks its source conversation and reports `needs-review`, `reviewed`, or
+`unknown`. `brain_handoff {action:"review", id}` returns paginated Claude Code or Codex
+conversation turns, including user requests with no reply. Follow `nextCursor` with the returned
+`revision`; after reading every page, acknowledge the final `reviewToken` with a `summary` of
+completed and still-pending requests. Session-only takeovers use `review` with `session` to create
+a reviewable draft first. The first review covers the whole conversation, including requests
+that predate the card; changed source bytes invalidate the review and require another pass.
+The saved review is an agent attestation, not proof of task completion. It never closes work.
+Transcripts stay on this machine and are read only from the supported hosts' transcript folders.
+Missing, malformed, ambiguous, oversized, or unsupported sources report `unknown`; an attachment
+placeholder requires checking the original media. The reader is bounded to 128 MiB per transcript,
+16 MiB per JSONL record, 8 MiB of conversation text, and 12,000 discovery entries. A limit never
+silently drops turns or certifies coverage. Reconcile the card's Next list with the conversation
+and repository evidence before continuing.
+
 Durable decisions still go in the brain as cards — a handoff is the one card about *work in
 flight*, and it closes when the work lands.
 
@@ -1164,10 +1220,12 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `npx klypix-mcp diff [ref]` | Card-level brain diff against a git ref, as markdown |
 | `npx klypix-mcp pr-brief [ref]` | Brain cards referencing the files changed since a ref, as markdown |
 | `npx klypix-mcp garden-code` | Print the human approval code `brain_garden` requires |
+| `npx klypix-mcp check` | Run this project's rules (`.klypix/rules.json`) on the working tree, `--staged`, or `--base <ref>`; `--install-hook` wires the opt-in pre-commit, pre-push and post-commit hooks |
+| `npx klypix-mcp rules` | The person's side of project rules: per-rule counts and suggestions, `code promote\|retire <ids>` (the approval code), `allow <id> --reason` (one hour), `false-alarm <id> --reason` |
 | `npx klypix-mcp rescue` | Rescue copies the git guard saved before a discard: `list`, `show <id>`, `restore <id> [paths…]`, `prune` |
 | `npx klypix-mcp sessions` | This project's closed sessions and the notes waiting for them; `sessions reopen <id>` reopens one |
 
-### The verbs: 26, and 27 on Windows
+### The verbs: 27, and 28 on Windows
 
 | Tool | What it does |
 |---|---|
@@ -1178,6 +1236,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
 | `brain_lens` | Machine-readable freshness, provenance, activity, timeline, orrery and unresolved views; on a canvas open in KLYPIX (Windows), the first five come from KLYPIX's own lens code |
 | `brain_garden` | Maintenance pass — proposes first; consolidation cannot apply without an approval code the human generates. The separate `repair:"duplicate-partials"` pass is dry-run first and needs no code (it removes only exact repeats and archives nothing) |
+| `brain_rules` | Project rules made from the brain's lessons: `propose` routes each lesson to rule, instruction or note; `add` writes candidates to `.klypix/rules.json`; `promote` and `retire` need the person's approval code, and a rule warns unless the person approved it with `--block`; `check` runs the rules on a diff; `status` shows blocks, overrides, false alarms and retirement suggestions. No AI at check time ([docs/brain-rules.md](docs/brain-rules.md)) |
 | `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, tool count, projection drift |
 | `brain_message` | Session-to-session coordination notes — to a live session, or queued for one that is not running until it next starts — with a fixed send-time audience and per-recipient pending / offer / acknowledgement / consumption / failure receipts (a directed note is kept 7 days, a broadcast 24h; never written into the brain) |
 | `brain_message_receipt` | Explicitly record model-side consumption using the exact message id and per-recipient offer token; acknowledgement alone never consumes a note |
@@ -1199,7 +1258,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `add_to_canvas` | Append cards/connections (positions preserved), bordered and readable on KLYPIX's dark and Paper themes; a card's `group` puts it in that titled box. On a canvas open in KLYPIX (Windows) the cards go to KLYPIX itself: live, attributed, one undo. When KLYPIX cannot take them it refuses (`OPEN_IN_APP`, `ACCESS_OFF`, `BLOCKED`), a box locked from AI tools (`SCOPE_LOCKED`) or a frozen box (`FROZEN`), and writes nothing; project brains are the exception to the first. Returns the new card ids |
 | `list_canvases` | List every `.klypix` in the vault |
 
-Exactly 26 on Linux and macOS and 27 on Windows, where `show_in_klypix` is registered; machine-verifiable with `npx klypix-mcp doctor`, whose TOOLS line applies the same rule and whose App bridge line says whether KLYPIX is running, with access on or off.
+Exactly 27 on Linux and macOS and 28 on Windows, where `show_in_klypix` is registered; machine-verifiable with `npx klypix-mcp doctor`, whose TOOLS line applies the same rule and whose App bridge line says whether KLYPIX is running, with access on or off.
 
 > **`canvas_view`:** no MCP Apps host has been observed rendering the UI resource yet — there is no
 > screenshot and no host-level test. Hosts without the extension get clean text, which is the path
@@ -1413,6 +1472,11 @@ Read this section before you build on any of it.
   `src/auth/token.ts` does not match a rename. Folder overlap is advisory. The merge test sees
   committed work only, needs git 2.38 or newer, and runs only for sessions on different local
   branches of the same repository.
+- **Project rules check the diff, not behaviour.** They see file names, added lines, line endings
+  and paths; they do not run code or tests. They warn unless the person approved them with
+  `--block`; Codex is warned, not stopped, while it edits, and the commit hooks are opt-in per
+  clone. The approval code and the refusal inside agent shells prevent accidents; they do not stop
+  a deliberate workaround.
 - **Overlap warnings are advisory.** Nothing is blocked. One severity string in the payload reads
   `blocking`; the mechanism is not.
 - **Codex has no automatic capture**, with or without `--codex-hooks`. The Codex hook never writes

package/bin/klypix-a2a.mjs

@@ -132,7 +132,7 @@ function agentCard(publicUrl) {
     {
       id: 'learn_skill',
       name: 'Learn a reusable skill (how-to / gotcha)',
-      description: 'Record a 🛠️ SKILL — a reusable how-to, gotcha, or convention ("always dedup zKeys before REORDER") that should resurface every session and never age out, distinct from a one-time decision. Routes through the capture engine with the "+" marker. A delegating agent uses this to teach the shared brain how work is done here, so every future agent inherits it. Plain "remember" auto-promotes to a skill when the text reads as a general rule.',
+      description: 'Record a 🛠️ SKILL — a reusable how-to, gotcha, or convention ("always dedup zKeys before REORDER") that is kept until corrected and shown first to sessions that touch the files it names, distinct from a one-time decision. Routes through the capture engine with the "+" marker. A delegating agent uses this to teach the shared brain how work is done here, so every future agent inherits it. Plain "remember" auto-promotes to a skill when the text reads as a general rule.',
       tags: ['memory', 'skill', 'how-to', 'procedure', 'brain', 'learn'],
       examples: ['Learn this gotcha: never set backgroundThrottling false — it breaks visibility detection', 'Remember the convention: Electron main imports must stay at top'],
       inputModes: ['text/plain', 'application/json'],

package/bin/klypix-conformance.mjs

@@ -134,7 +134,8 @@ try {
   metrics.startAttempts = { first: aStarted.attempt, second: bStarted.attempt };
   const aStructured = aStart.structuredContent || {};
   const bStructured = bStart.structuredContent || {};
-  checks.taskMemory = Array.isArray(aStructured.context?.hits) && aStructured.context.hits.length > 0;
+  checks.taskMemory = (Array.isArray(aStructured.context?.hits) && aStructured.context.hits.length > 0)
+    || (Array.isArray(aStructured.context?.fileLessons) && aStructured.context.fileLessons.length > 0);
   checks.truthfulTaskCount = bStructured.counts?.activeTasks === 2
     && bStructured.peers?.length === 1;
   checks.exactBlockingOverlap = bStructured.conflicts?.length === 1

package/bin/klypix-install.mjs

@@ -349,7 +349,9 @@ const flatten = (code) => code
     // app bridge, which imports the protocol.
     // session-handoff (1.99.1): the worker's brain_sync imports CONTINUE_RE and
     // formatHandoffCards from it directly (1.99.0 only reached it via core).
-    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|capture-gap|enrichment|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|repo-state|semantic-memory|runtime-inspector|project-graph|git-capture-install|app-lease|app-tools|app-bridge-protocol|app-bridge-client|session-handoff)\.mjs/g, './$1.mjs')
+    // brain-rules (project rules): the worker's brain_rules tool and the
+    // dispatcher's `check` / `rules` verbs import it lazily.
+    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|capture-gap|enrichment|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|repo-state|semantic-memory|runtime-inspector|project-graph|git-capture-install|app-lease|app-tools|app-bridge-protocol|app-bridge-client|session-handoff|brain-rules)\.mjs/g, './$1.mjs')
     .replace(/klypix-worker\.mjs/g, 'klypix-mcp-worker.mjs')
     .replace(/const PKG_VERSION = \(\(\) => \{[\s\S]*?\}\)\(\);/, `const PKG_VERSION = '${VERSION}'; // baked at install (flat layout has no package.json)`);
 
@@ -495,7 +497,7 @@ try {
     // a newer klypix-format cannot. merge-brains and the driver ship here so
     // brain-history's restore merge, the KLYPIX core and the git driver all
     // find one engine in this directory.
-    for (const f of ['global-brain-hook.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'app-lease.mjs', 'klypix-core.mjs', 'app-bridge-protocol.mjs', 'app-bridge-client.mjs', 'app-tools.mjs', 'card-files.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'network-bridge.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'session-handoff.mjs', 'live-projection.mjs', 'whose.mjs', 'whose-classify.mjs', 'whose-ledger.mjs', 'whose-rescue.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'app-lease.mjs', 'klypix-core.mjs', 'app-bridge-protocol.mjs', 'app-bridge-client.mjs', 'app-tools.mjs', 'card-files.mjs', 'brain-write-lock.mjs', 'brain-rules.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'network-bridge.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'session-handoff.mjs', 'live-projection.mjs', 'whose.mjs', 'whose-classify.mjs', 'whose-ledger.mjs', 'whose-rescue.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [
@@ -572,7 +574,9 @@ try {
         // Guard cards (2026-08-24): pre-action lane. Fast path — reads only the
         // compiled guard sidecar; 'warn' injects context, 'block' denies with
         // the card's message. Absent guards = stat + one tiny read, then no-op.
-        ['PreToolUse', { matcher: 'Bash|PowerShell|Edit|Write', hooks: [{ type: 'command', command: brainCmd('--guard'), timeout: 10 }] }],
+        // Project rules (.klypix/rules.json) ride the same lane for edits: a
+        // forbidden line is denied before it is written (MultiEdit included).
+        ['PreToolUse', { matcher: 'Bash|PowerShell|Edit|Write|MultiEdit', hooks: [{ type: 'command', command: brainCmd('--guard'), timeout: 10 }] }],
         // Session end (1.105.0): a closed or cut-off Claude Code session leaves
         // the lane at once. Before this, only the 10-minute TTL removed it, so the
         // next session read a dead peer as "live" and refused to continue its

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'brain-deleted', 'orphans', 'diff', 'pr-brief', 'uninstall', 'bench', 'sessions', 'rescue']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'brain-deleted', 'orphans', 'diff', 'pr-brief', 'uninstall', 'bench', 'sessions', 'rescue', 'check', 'rules']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -36,6 +36,11 @@ const USAGE = [
   '  bench [--quick] [--json] [--out F]  reproducible benchmark: concurrent-write safety, latency, soak, crash',
   '  init                                seed a starter ./brain.klypix + print an MCP config',
   '  garden-code [brain]                 print the human approval code for brain_garden',
+  '  check [--staged|--base B|--range A..B] [--strict] [--json]',
+  '                                      run this project\'s rules (.klypix/rules.json) on a diff — milliseconds, no install/tests',
+  '  check --install-hook|--remove-hook  opt-in git pre-commit/pre-push/post-commit hooks for those rules',
+  '  rules [list|code promote|retire <ids>|promote|retire <ids> --code C|allow <id> --reason R|false-alarm <id> --reason R]',
+  '                                      the human side of rules: approval codes, one-hour overrides, false alarms',
   '  uninstall [--check|--yes|unlink]    remove this install from the machine (--check inventories first; never deletes a .klypix)',
   '  git-driver [install|status] [repo]  register the card-level .klypix merge driver for a repo (zero-command teams)',
   '  git-hook [install|remove|status]    wire the agent-neutral commit-capture hook (any agent/branch/worktree → brain cards)',
@@ -78,6 +83,9 @@ if (verb === 'bench') {
   console.log(process.argv.includes('--json') ? JSON.stringify(report, null, 2) : markdown);
   const c = report.scenarios?.concurrentWriters;
   process.exit(c?.verdict === 'no-loss' ? 0 : 1);
+} else if (verb === 'check' || verb === 'rules') {
+  const { runRulesCli } = await import('../src/brain-rules.mjs');
+  process.exit(await runRulesCli(verb === 'rules' ? process.argv.slice(2) : process.argv.slice(3)));
 } else if (verb === 'runtime') {
   process.argv.splice(2, 1);
   await import('./klypix-runtime.mjs');

package/bin/klypix-worker.mjs

@@ -228,7 +228,7 @@ if (process.argv[2] === 'init') {
       { title: 'Goal', cards: [{ text: '❓ What is this project for, and for whom?\nAgent: survey the repo on your first session and replace this with the real goal.' }] },
       { title: 'Architecture', cards: [{ text: '❓ Key components and how they fit.\nAgent: record the actual shape from the repo — only what a new session must know.' }] },
       { title: 'Decisions', cards: [{ text: 'Decisions land here automatically: agents emit `🧠 BRAIN [Area]: …` markers; a new decision that replaces an old one archives it (superseded). Resolve finished items with `✓`, correct in place with `~`. Drag any card into 📌 Focus to make it lead every session brief.' }] },
-      { title: '🛠️ Skills', cards: [{ text: '🛠️ Reusable how-tos, gotchas & conventions land here — emit `🧠 BRAIN [Area] +: <skill>` (or just state a rule like "always X / never Y" and it auto-promotes). Skills resurface every session and never age out, unlike one-time decisions. This is "how we work here", inherited by every future agent.' }] },
+      { title: '🛠️ Skills', cards: [{ text: '🛠️ Reusable how-tos, gotchas & conventions land here — emit `🧠 BRAIN [Area] +: <skill>` (or just state a rule like "always X / never Y" and it auto-promotes). Skills are kept until corrected and shown first to sessions that touch the files they name, unlike one-time decisions. This is "how we work here", inherited by every future agent.' }] },
       { title: 'Pending / next', cards: [{ text: 'What is in flight and what comes next. Close finished items with the ✓ marker.' }] },
       { title: 'Open questions', cards: [{ text: 'Unresolved questions (the ❓ marker) live here — the session brief surfaces them first.' }] },
       { title: '📌 Focus', cards: [{ text: 'Drag any card into this area to make it lead every session brief — steer your agent by moving cards.' }] },
@@ -812,7 +812,7 @@ try {
 
 server.registerTool('brain_note', {
   title: 'Write a deliberate note to the project brain (decision / question / milestone / skill / resolve / update)',
-  description: 'Record something in the project brain ON DEMAND — the agent-neutral twin of the Claude-Code capture hook, so any client (Cursor / Cline / Desktop) can write the brain, not just read it. Unlike add_to_canvas (a flat append), this routes through the brain\'s capture engine, so a new decision SUPERSEDES a heavily-overlapping older one, ✓ RESOLVES/archives a matching card, closes: resolves the strategy/question a milestone fulfils, and ~ UPDATES a card in place — the full decision lifecycle, with dedup. Use marker "+" to record a 🛠️ SKILL — a reusable how-to/gotcha/convention ("always dedup zKeys before REORDER") that should resurface every session and never age out, distinct from a one-time decision. Use it to remember a decision, ask an open question, mark a milestone, log a skill, resolve a finished item, or correct a card. Defaults to the project brain ("brain").',
+  description: 'Record something in the project brain ON DEMAND — the agent-neutral twin of the Claude-Code capture hook, so any client (Cursor / Cline / Desktop) can write the brain, not just read it. Unlike add_to_canvas (a flat append), this routes through the brain\'s capture engine, so a new decision SUPERSEDES a heavily-overlapping older one, ✓ RESOLVES/archives a matching card, closes: resolves the strategy/question a milestone fulfils, and ~ UPDATES a card in place — the full decision lifecycle, with dedup. Use marker "+" to record a 🛠️ SKILL — a reusable how-to/gotcha/convention ("always dedup zKeys before REORDER") kept until corrected and shown first to sessions that touch the files it names, distinct from a one-time decision. When the mistake is mechanical, end the text with a `rule:` suffix to make the lesson RULE-READY: repo globs, then `never "<text>"`, `never /<regex>/`, `must "<text>"`, `listed-in <file>[,<file>]`, `keep-eol` or `costly` — e.g. `rule: web/tests/**/*.test.ts never "from \'@/"`. The globs must name tracked files; it lands as a visible "⚙ rule candidate" line that nothing checks until brain_rules adds it and a person approves it. Use it to remember a decision, ask an open question, mark a milestone, log a skill, resolve a finished item, or correct a card. Defaults to the project brain ("brain").',
   inputSchema: {
     text: z.string().describe('The note — one concise idea; the first line becomes the card title.'),
     marker: z.enum(['', '?', '!', '+', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · +=🛠️ skill (reusable how-to/gotcha; always resurfaces, never ages out) · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
@@ -1089,7 +1089,10 @@ server.registerTool('brain_handoff', {
     openWorldHint: false,
   },
   inputSchema: {
-    action: z.enum(['write', 'take', 'done', 'list']).optional().describe('write (default): record a handoff card. take: claim a handoff card (id) or unfinished work (session) before continuing it. done: mark it finished. list: every open handoff card and every unfinished session on this project.'),
+    action: z.enum(['write', 'take', 'done', 'list', 'review']).optional().describe('write: record a handoff. take: claim it and check conversation freshness. review: read source conversation pages, then acknowledge the final reviewToken with a summary of pending requests. done: mark finished. list: open handoffs and unfinished sessions.'),
+    cursor: z.number().int().min(0).optional().describe('review: nextCursor from the preceding page; omit to start.'),
+    revision: z.string().max(64).optional().describe('review: exact transcript revision from the preceding page.'),
+    reviewToken: z.string().max(64).optional().describe('review: acknowledge only AFTER reading every conversation page; supply the final token and a summary including outstanding requests. New source activity invalidates this token.'),
     project: z.string().optional().describe('Absolute project root containing brain.klypix. Defaults to this connection\'s project.'),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
     title: z.string().max(120).optional().describe('write: the work, in a few words ("Drive upload: the Place-it-now chooser").'),
@@ -1102,9 +1105,9 @@ server.registerTool('brain_handoff', {
     reason: z.enum(['context_limit', 'usage_limit', 'end_of_session', 'blocked', 'switching_tool', 'other']).optional().describe('write: why the work stops here.'),
     area: z.string().max(40).optional().describe('write: the brain area (titled box) the card goes into. Defaults to "Handoff".'),
     continues: z.string().max(64).optional().describe('write: the id of an earlier handoff card this one continues — it is closed as "continued by" this one.'),
-    id: z.string().max(64).optional().describe('take / done: the handoff card id (from brain_sync, the session-start brief, or list).'),
-    session: z.string().max(160).optional().describe('take / done: the session id (or a unique prefix of 8+ characters) from the unfinished-work list, when the work has no card.'),
-    summary: z.string().max(400).optional().describe('done: what was finished, in one or two sentences. take: an optional note.'),
+    id: z.string().max(64).optional().describe('take / done / review: the handoff card id (from brain_sync, the session-start brief, or list).'),
+    session: z.string().max(160).optional().describe('take / done / review: the session id (or a unique prefix of 8+ characters) from the unfinished-work list, when the work has no card. Review creates a reviewable draft if needed.'),
+    summary: z.string().max(400).optional().describe('done: what was finished. take: optional note. review acknowledgement: required account of completed and still-pending requests after reading all conversation pages.'),
   },
 }, async ({ action, project, canvas, ...rest }, extra) => {
   const identity = extra?.klypixRequestIdentity || {};
@@ -1456,6 +1459,7 @@ server.registerTool('brain_sync', {
           // record is announced as such — a lead to verify, not the session's words.
           drafted.length ? `🤝 KLYPIX drafted ${drafted.length} handoff card${drafted.length > 1 ? 's' : ''} just now from the record of a session that stopped without writing one: ${drafted.map((d) => `[${d.id}] “${d.title}”`).join('; ')}. A drafted card is a lead, not a verified state — confirm it with git before relying on it.` : '',
           formatHandoffCards(cards, { now, max: 5 }),
+          cards.length ? 'Saved handoffs are not verified conversation coverage. On takeover call brain_handoff review and check later/unanswered requests before trusting Next; missing transcripts mean UNKNOWN.' : '',
           formatUnfinishedWork(lane, { now, max: 4, ranked: wantsContinue && words.size > 0 }),
         ].filter(Boolean).join('\n\n');
         handoffData = {
@@ -1540,6 +1544,38 @@ server.registerTool('brain_sync', {
   };
 });
 
+server.registerTool('brain_rules', {
+  title: 'Project rules from the brain\'s lessons — enforced before CI, with no AI at check time',
+  description: 'Turns lessons this brain recorded ("every new route must also be in PRIVATE_ROUTES", "a new *.test.ts must be listed in package.json", "this file is mixed CRLF/LF") into DETERMINISTIC diff checks, versioned in the repo as .klypix/rules.json, each citing the card it came from. Checked before the code reaches CI: brain_sync shows the rules for the files you declare; the edit hook (Claude Code; Codex gets the same) and an opt-in git pre-commit/pre-push hook report findings. Rules WARN by default; only a rule the human approved with --block stops an edit (Claude Code) or a commit, and a commit that skips a blocking rule (--no-verify) is recorded. Actions: "propose" routes each lesson to rule / instruction / note and drafts the checkable ones; "add" writes completed drafts as CANDIDATES (inert); "promote" and "retire" need the human\'s 8-character approval code (`npx klypix-mcp rules code promote|retire <ids>` — never shown to you, never guess it; a rule that blocks you is lifted only by the human); "check" runs the rules on the working tree, the staged change, or a range (include_candidates:true tests candidates before approval); "status" lists rules with fires / blocks / overrides / false alarms and retirement suggestions; "false_alarm" records that a finding was wrong (it does not lift the rule). Kinds: listed-in, forbid-pattern, preserve-eol, cloud-required. Checks are string/glob/regex work over the diff — milliseconds, offline; the project\'s own tests stay with its CI.',
+  inputSchema: {
+    action: z.enum(['propose', 'add', 'check', 'status', 'promote', 'retire', 'false_alarm']).describe('What to do. Default flow: propose → add → (human) promote; check any time; status for counts and suggestions.'),
+    project: z.string().optional().describe('Absolute project root (the folder holding brain.klypix and .klypix/). Defaults to this session\'s project brain.'),
+    query: z.string().optional().describe('propose: only lessons containing this text.'),
+    limit: z.number().int().min(1).max(100).optional().describe('propose: at most this many lessons (default 30).'),
+    rules: z.array(z.record(z.string(), z.any())).max(32).optional().describe('add: complete rules — {id, kind, severity, why, fix, source:{card}, files:[globs], …kind fields}. listed-in: when "added-files"|"added-lines", registry:[files], needle (template: {file} {basename} {name} {relpath} {1}), pattern for added-lines (capture group 1 = the value to find). forbid-pattern: pattern. preserve-eol: files only. cloud-required: files, severity "advise".'),
+    ids: z.array(z.string()).max(32).optional().describe('promote / retire / false_alarm: rule ids.'),
+    approve: z.string().optional().describe('promote / retire: the human\'s 8-character code. Never guess or fabricate it.'),
+    reason: z.string().max(300).optional().describe('retire / false_alarm: why, in one line.'),
+    mode: z.enum(['worktree', 'staged', 'range']).optional().describe('check: the working tree vs HEAD (default), the staged change, or a commit range (with base).'),
+    base: z.string().optional().describe('check: base ref for a range (merge-base with head is used).'),
+    head: z.string().optional().describe('check: head ref for a range (default HEAD).'),
+    files: z.array(z.string()).max(50).optional().describe('check: just list the rules these files fall under (no diff).'),
+    include_candidates: z.boolean().optional().describe('check: also run candidate rules — to see what a rule would catch before the human approves it.'),
+    block: z.boolean().optional().describe('promote: true only when the human printed the code with --block, making these rules stop an edit or a commit instead of warning. Rules warn by default.'),
+  },
+}, async ({ action, project, query, limit, rules, ids, approve, reason, mode, base, head, files, include_candidates, block }, extra) => {
+  try {
+    const { brainRulesTool } = await import('../src/brain-rules.mjs');
+    const brainPath = project ? path.join(path.resolve(project), 'brain.klypix') : (mcpPresence.brainPath || path.join(mcpPresence.vault, 'brain.klypix'));
+    return toContent(await brainRulesTool({
+      projectRoot: path.dirname(brainPath), brainPath, action, query, limit, rules, ids, approve, reason, mode, base, head, files,
+      includeCandidates: include_candidates === true, block: block === true, pluginMode: PLUGIN_MODE, proposedBy: extra?.klypixClientName || '',
+    }));
+  } catch (error) {
+    return toContent({ blocks: [{ kind: 'text', text: `brain_rules failed: ${error?.message || error}` }], isError: true });
+  }
+});
+
 server.registerTool('brain_doctor', {
   title: 'Brain doctor — is this brain current, wired, and in sync?',
   description: 'Read-only self-check of the installed klypix brain, as ONE verdict: VERSION (deployed brain-core + optional npm currency), CLAUDE (existing 5-hook capture readiness), CODEX (automatic MCP presence plus optional enhanced-hook status), TOOLS (discoverable MCP verbs), SESSIONS (all active presence-adapter sessions across hosts, never recent-chat history), and HARNESS (projection drift). Use to answer "is my brain current, correctly installed, in sync, and who is actually live?" without file-spelunking. Never writes: the only side effects are read-only subprocess queries (git rev-parse / tag --list / log / merge-base with fixed argument arrays, and `npm view` only when check_npm is true) — it creates, edits, and deletes nothing. SCOPE: only CLAUDE and CODEX get behavioural verdicts. HARNESS classifies the projected config/rules FILES on disk — a project can read fully ok while no other host has ever actually loaded them, so do not report a clean HARNESS as "Cursor/Cline/Windsurf/Copilot is working". The MCP-callable twin of `npx klypix-mcp doctor`. Besides the text, the result carries structuredContent {verdict, layers, version, autoUpdate, supervisors, readinessWarnings, actions}: the same verdict as data, including when the next automatic update check runs and what it will do.',
@@ -1808,6 +1844,43 @@ server.server.oninitialized = () => {
 };
 server.server.onclose = stopRuntimePresence;
 process.once('exit', stopRuntimePresence);
+// Published tool schemas are a compatibility contract: a running supervisor
+// compares them byte for byte before it hot-swaps a worker, and the frozen
+// snapshots in test/fixtures pin them. zod 4.6 writes a union of plain types as
+// `type: ["number","string"]` where every snapshot and every supervisor already
+// running knows `anyOf: [{type:"number"},{type:"string"}]` — the same meaning in
+// other bytes. Rewrite each type list back into anyOf, FIRST in its object as
+// zod 4.4 wrote it (before description), so a zod bump never drifts a frozen
+// schema.
+const isTypeList = (value) => Array.isArray(value) && value.length > 1 && value.every((t) => typeof t === 'string');
+function frozenSchemaShape(node) {
+  if (Array.isArray(node)) return node.map(frozenSchemaShape);
+  if (!node || typeof node !== 'object') return node;
+  const out = {};
+  if (isTypeList(node.type)) out.anyOf = node.type.map((type) => ({ type }));
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'type' && isTypeList(value)) continue;
+    out[key] = frozenSchemaShape(value);
+  }
+  return out;
+}
+const sdkListTools = server.server._requestHandlers?.get?.('tools/list');
+if (typeof sdkListTools === 'function') {
+  server.server._requestHandlers.set('tools/list', async (request, extra) => {
+    const result = await sdkListTools(request, extra);
+    if (!result || !Array.isArray(result.tools)) return result;
+    return {
+      ...result,
+      tools: result.tools.map((tool) => ({
+        ...tool,
+        ...(tool.inputSchema ? { inputSchema: frozenSchemaShape(tool.inputSchema) } : {}),
+        ...(tool.outputSchema ? { outputSchema: frozenSchemaShape(tool.outputSchema) } : {}),
+      })),
+    };
+  });
+} else {
+  log('tools/list schema shaping unavailable in this SDK; published schemas follow zod as-is');
+}
 await server.connect(transport);
 // Most sessions use brain_sync/presence and should not pay for a private model
 // they never query. Legacy mode restores the old eager lifecycle immediately.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.106.2",
+  "version": "1.107.2",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Shared project memory for Claude Code, Codex and Cursor: decisions, corrections, overlap warnings.",
   "type": "module",
@@ -33,7 +33,10 @@
     "team-memory",
     "decision-log",
     "overlap-warnings",
-    "agent-collaboration"
+    "agent-collaboration",
+    "ci",
+    "git-hooks",
+    "code-review"
   ],
   "homepage": "https://klypix.com/klypix-mcp",
   "repository": {
@@ -97,7 +100,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/session-handoff.mjs && node test/lock-notes.mjs && node test/whose-classify.mjs && node test/whose-ledger.mjs && node test/whose-rescue.mjs && node test/whose-hook.mjs && node test/live-projection.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/network-bridge.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-preparation.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/marker-after-colon.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/overlap-tiers.mjs && node test/coordination-bench.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/results-not-manifests.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/current-first.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/session-handoff.mjs && node test/handoff-freshness.mjs && node test/lock-notes.mjs && node test/whose-classify.mjs && node test/whose-ledger.mjs && node test/whose-rescue.mjs && node test/whose-hook.mjs && node test/live-projection.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/network-bridge.mjs && node test/brain-rules.mjs && node test/brain-recall.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-preparation.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/marker-after-colon.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/overlap-tiers.mjs && node test/coordination-bench.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/results-not-manifests.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/current-first.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",
@@ -111,7 +114,7 @@
     "fractional-indexing": "^3.2.0",
     "jpeg-js": "^0.4.4",
     "jszip": "^3.10.1",
-    "zod": "^4.3.6"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@huggingface/transformers": "^4.2.0"

package/src/app-tools.mjs

@@ -66,7 +66,7 @@ import {
   appToolsPlatform, appVaultSetting, canonicalCanvasPath, isOpenInApp, pathHash, readEndpoint, sharedCanvasesDir,
   tellUser, TELL_USER, APP_BRIDGE_PROTOCOL, LEASE_SINCE_APP_VERSION,
 } from './app-lease.mjs';
-import { brainTarget, canvasTitleOf, resolveCanvasDetailed, walkVault } from './klypix-core.mjs';
+import { brainTarget, canvasTitleOf, closestCanvases, notFoundText, resolveCanvasDetailed, walkVault } from './klypix-core.mjs';
 import {
   classifyLinkTier, derivedReading, DOCUMENT_TEXT_KIND, escapeInstructionLines, fenceContent, parseKlypix, readManifestCheap, recordedAuthor, savedReadingIndex, scopeLockedView,
 } from './klypix-format.mjs';
@@ -491,10 +491,12 @@ export async function readCardContents({ vault, canvas, card_ids, read_new, refr
   const resolved = resolveCanvasDetailed(vault, canvas);
   if (!resolved.file) {
     const sentence = tellUser('NOT_FOUND');
+    const closest = resolved.ambiguous ? [] : closestCanvases(vault, canvas);
     const first = resolved.ambiguous
       ? `More than one canvas is titled "${canvas}" — pass one of these paths:\n${resolved.ambiguous.map(p => `  - ${p}`).join('\n')}`
-      : `Canvas not found: ${canvas}. Names match a file name or the title KLYPIX shows.`;
-    return envelope({ ok: false, code: 'NOT_FOUND', tell_user: sentence, text: first, structured: resolved.ambiguous ? { candidates: resolved.ambiguous } : {} });
+      : notFoundText(canvas, null, closest);
+    return envelope({ ok: false, code: 'NOT_FOUND', tell_user: sentence, text: first,
+      structured: resolved.ambiguous ? { candidates: resolved.ambiguous } : { closest: closest.map((c) => c.path), maybe_cloud_space: true } });
   }
   const file = resolved.file;
   let parsed;