klypix-mcp 1.49.0 → 1.49.2

package/A2A.md

@@ -46,11 +46,13 @@ 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) | the updated `.klypix` |
+| `learn_skill` | Capture a reusable how-to / gotcha as a 🛠 skill card — resurfaces every session | the updated `.klypix` |
 | `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 |
 | `brain_insights` | Hubs / orphans / stale questions in a brain | text |
 | `search_all_brains` | Cross-project memory search (semantic + lexical) | text |
+| `brain_connect` | Find and draw related-but-unlinked cards (proposes before it applies) | text |
 
 ## Talk to it (JSON-RPC 2.0)
 

package/FORMAT.md

@@ -47,7 +47,8 @@ writer guarantees the content-addressed `images/ files/ thumbs/` split.
   "updatedAt": "ISO-8601",
   "title": "My board",
   "stats": { "itemCount": 12, "assetCount": 3, "totalBytes": 0 },
-  "sync": { "enabled": false, "lastSyncRev": null, "lastSyncAt": null, "deviceId": "dev_…" }
+  "sync": { "enabled": false, "lastSyncRev": null, "lastSyncAt": null, "deviceId": "dev_…" },
+  "cloud": { "blobId": "702ecfe0-…", "linkedAt": "ISO-8601", "linkedBy": "Sara Ali" }
 }
 ```
 
@@ -65,6 +66,13 @@ writer guarantees the content-addressed `images/ files/ thumbs/` split.
   `items/`. Never use `stats` as an integrity check.
 - `sync` records whether the file is opted into the app's cloud sync; it carries no
   content and no credentials.
+- **`cloud`** — optional and additive; written by the KLYPIX app when a brain is
+  shared, naming the encrypted cloud copy this file pairs with. It exists so the
+  mapping **travels inside the file**: clone the repo, or email the `.klypix`, and the
+  copy that arrives already knows its cloud twin — no server lookup, works offline.
+  **The encryption key is never here.** The `blobId` alone reaches nothing: the cloud
+  copy is ciphertext, and the key travels only in a share link's URL fragment. A
+  reader that does not care about cloud sync should ignore this object.
 
 ## `canvas.json`
 
@@ -115,13 +123,27 @@ strings: `text`, `box`, `image`, `file`, `container`, `approval`, `link`,
   "border": true,
   "heading": false,
   "createdBy": "agent",
-  "createdVia": "claude-code"
+  "createdVia": "claude-code",
+  "author": "Sara Ali",
+  "updatedAt": 1785500000000
 }
 ```
 
 `createdBy` (`user` | `agent`) and the optional `createdVia` (which agent/channel
 captured it) are the provenance bits the brain surfaces as badges and lenses.
 
+The optional **`author`** answers the question a team actually asks: `createdBy` says
+*what* wrote a card, `author` says *whose*. It is resolved from `git config user.name`
+so brain attribution matches commit attribution with no configuration (override with
+`KLYPIX_AUTHOR`; falls back to the OS user; simply absent if neither resolves).
+
+**`updatedAt` is VOLATILE — never treat it as content.** It is restamped by the act of
+writing, so two copies of an identical card differ in it. Any comparison that decides
+"did this card change" must strip `updatedAt` (and the derived `zIndex` in
+`positions`) before comparing, or a plain re-save reads as an edit. The merge engine
+learned this the hard way: a byte-compare spawned conflict twins for cards nobody
+touched. `mergeBrains` exports `sameMeaning(a, b)` as the single correct comparison.
+
 ## Bytes: when they are embedded vs referenced
 
 **Embedded** — the bytes live inside the ZIP under `assets/`, and the item JSON

package/README.md

@@ -79,7 +79,7 @@ npx klypix-mcp conformance
 
 It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,
 truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.
-It verifies 7 coordination behaviours — not the 18 tools, and not the retrieval engine.
+It verifies 12 required coordination behaviours — not the 18 tools, and not the retrieval engine.
 
 ---
 
@@ -133,9 +133,9 @@ content.
 npx klypix-mcp link --check    # audits without writing; exits non-zero on drift
 ```
 
-> Use that exact form. The standalone `klypix-link` binary currently drops the `--check` flag and
-> writes instead (`bin/klypix-link.mjs:23`). Do not wire `npx -p klypix-mcp klypix-link --check`
-> into CI until that is fixed.
+> Either form works, and both are safe in CI: `npx -p klypix-mcp klypix-link --check` used to
+> drop `--check` and write anyway — fixed, and locked by `test/cli-args.mjs`, which asserts the
+> standalone bin and the dispatcher parse arguments identically.
 
 **Give a project a brain** by dropping a `brain.klypix` into it — the
 [KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*), or
@@ -292,12 +292,43 @@ Apache-2.0 and work with no app installed. The app's interface is available in E
 
 ## Git and concurrency
 
-One file in your repo, committed with your code — versioned, branchable, portable.
+One file in your repo, committed with your code — versioned, branchable, portable. So two
+developers already share one brain the way they share code: clone, branch, pull.
 
-Be precise about what git does here: `brain.klypix` is a binary ZIP. Git shows
-`Bin 1308328 -> 1309005 bytes`, produces zero line diffs, and a merge conflict on it is an
-all-or-nothing take-ours or take-theirs. You cannot review a brain change in a PR diff. **All
-card-level merge safety comes from the KLYPIX engine, not from git.**
+Be precise about what git does on its own: `brain.klypix` is a binary ZIP. Git shows
+`Bin 1308328 -> 1309005 bytes` and produces zero line diffs, so out of the box a conflict on it is
+an all-or-nothing take-ours or take-theirs, and a reviewer sees nothing. **Card-level merge safety
+comes from the KLYPIX engine** — but since 1.48.0 you can hand that engine to git and read its
+output in a PR:
+
+```bash
+npx klypix-mcp git-driver install     # once per clone, in any repo
+```
+
+That registers a merge driver for `*.klypix` (a per-machine git config line plus a `.gitattributes`
+rule you commit) and provisions the engine it needs. When two people change the brain and one
+pulls, git calls the engine instead of stopping: new cards from both sides are kept, a card only
+one side edited takes that edit, and a card edited differently on both sides keeps **both**
+versions — the second as a linked twin, never a silent overwrite. Before returning, the merge
+asserts it still contains every surviving card from both sides and refuses rather than hand back a
+result that lost one.
+
+The honest boundary: a machine that has not run `git-driver install` simply gets the old binary
+conflict — safe degradation, not corruption — and git keeps both parents of every merge, so even a
+merge you dislike is reconstructable. It is a merge *on pull*, not live sync.
+
+For review, two commands turn a binary blob into something a human can read:
+
+```bash
+npx klypix-mcp diff main            # card-level: what was added / updated / removed
+npx klypix-mcp pr-brief origin/main # the brain cards that reference this PR's changed files
+```
+
+`diff` compares meaning rather than bytes (a re-save restamps timestamps; that is not a change).
+`pr-brief` matches a card's `#file-…` evidence anchors against the changed paths, so a reviewer
+sees the decisions already recorded about the code in front of them. `examples/github/brain-pr.yml`
+wires both into a sticky pull-request comment using nothing but the checkout and the default
+`GITHUB_TOKEN` — no KLYPIX service in the path.
 
 Concurrent sessions serialize behind a capture lock, and each write is a temp file plus an atomic
 rename, so a crash mid-write leaves the previous good file intact. The lock is advisory with a
@@ -307,6 +338,24 @@ was judged worse — but it is a real limit, not a guarantee.
 
 ---
 
+## The command line
+
+The MCP verbs below are what agents call. These are what **you** call:
+
+| Command | What it does |
+|---|---|
+| `npx klypix-mcp init` | Seed a starter `brain.klypix` here and print an MCP config |
+| `npx klypix-mcp install` | Install the engine + Claude Code hooks on this machine (see Quick start) |
+| `npx klypix-mcp link` | Wire this project for Cursor, Cline, Windsurf, Copilot, Gemini CLI, Aider (`--check` audits) |
+| `npx klypix-mcp doctor` | One verdict: version, hosts, live sessions, tool count, drift. Exits non-zero — usable as a CI gate |
+| `npx klypix-mcp conformance` | Launch two real MCP clients against this build and verify coordination behaviour |
+| `npx klypix-mcp git-driver` | Register the lossless `.klypix` merge driver for a repo (`status` to check) |
+| `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 |
+
+---
+
 ## The 18 verbs
 
 | Tool | What it does |
@@ -445,7 +494,10 @@ Read this section before you build on any of it.
 
 - **Coordination is machine-local and OS-user-local.** The presence lane is a file in your home
   directory. Two developers on two machines do not see each other's sessions, peers, overlaps or
-  messages. There is no cross-machine or cross-team coordination today.
+  messages. This package ships the cross-machine presence *core* (`./presence-relay` — versioned
+  metadata-only frames, a symmetric default-off consent gate, loop prevention and message dedup),
+  but no transport: carrying frames between machines is the desktop app's job. With `klypix-mcp`
+  alone, coordination is machine-local.
 - **Overlap matching is exact-path, and both sides must declare.** A session that never declares
   its expected files is invisible to overlap detection, and `src/auth/token.ts` does not match a
   rename or a parent directory.
@@ -453,10 +505,9 @@ Read this section before you build on any of it.
   `blocking`; the mechanism is not.
 - **Codex has no automatic capture**, with or without `--codex-hooks`. The Codex hook never writes
   the brain.
-- **There is no uninstall command.** Removing Klypix means hand-editing `~/.claude/settings.json`,
-  `~/.codex/config.toml` and `~/.codex/hooks.json`, deleting `~/.claude/project-brain`, and
-  deleting the 14 per-project files. The removal primitives exist in the source but no CLI reaches
-  them yet.
+- **Uninstall does not remove per-project files.** `npx klypix-mcp uninstall` handles the
+  machine-global install; the 14 files `link` wrote into each project are listed by
+  `npx klypix-mcp link --check` and removed by `uninstall unlink` **per project**, one at a time.
 - **Drift detection is single-host and opt-in per card.** It needs an `ev:` anchor written by the
   card's author, and it runs only in the Claude Code hook path — the MCP tools do not compute
   freshness.
@@ -468,8 +519,10 @@ Read this section before you build on any of it.
 - **A fresh `npx klypix-mcp install` gets lexical retrieval.** The optional on-device model is
   deliberately not installed.
 - **The capture lock is fail-open** past ~3.6 seconds of contention (see *Git and concurrency*).
-- **Tests are developer-run, not CI-gated.** The npm publish workflow runs no tests, and `test/` is
-  not in the published tarball.
+- **`test/` is not in the published tarball.** Run the suite from a clone. The publish workflow
+  *does* gate on it — a `gate` job runs `npm ci`, asserts the test chain is intact, runs `npm test`,
+  validates the version/tag, and checks the packed tarball; `publish` declares `needs: gate`, so a
+  red gate means npm never sees a tarball.
 - **`canvas_view`'s MCP Apps UI has never been verified on a real Apps host.**
 
 ## Numbers and methodology
@@ -477,9 +530,9 @@ Read this section before you build on any of it.
 Every number here is measured on our own project brain. Nothing below is published, benchmarked or
 independently validated.
 
-- **Dogfood scale.** KLYPIX itself is built with its own brain: **1,523 cards and 1,404
+- **Dogfood scale.** KLYPIX itself is built with its own brain: **1,645 cards and 1,521
   connections**, written by multiple concurrent agent sessions, receipts in the file. Current as of
-  2026-07-30.
+  2026-08-01.
 - **Recall.** 73% of past decisions recovered with one search round, 55% brief-only, 0% cold.
   Caveat that travels with it: n=20, our own brain, self-authored questions, LLM-judged.
 - **Ranker.** recall@5 of the true source card went **15% → 40%** across two upgrades (n=20 frozen
@@ -487,31 +540,33 @@ independently validated.
   experiment that *regressed* — contextual prefixes on short cards — is recorded next to the wins.
 - **What we do not publish.** No download count: this package's own 24-hour auto-updater generates
   most of it, so it is not a user count. No adoption, team or customer figures. No brief-token
-  figure — the last one was measured at ~600 cards and is stale at 1,523.
+  figure — the last one was measured at ~600 cards and is stale at 1,645.
 - **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
   numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.
 
 ## Uninstall
 
-There is no uninstall command yet. To remove Klypix by hand:
-
 ```bash
-rm -rf ~/.claude/project-brain
-# then remove the klypix hook entries from ~/.claude/settings.json
-# and the klypix MCP entry from ~/.codex/config.toml (and ~/.codex/hooks.json if you used --codex-hooks)
-npx klypix-mcp link --check      # lists the 14 managed files in a project, so you know what to delete
+npx klypix-mcp uninstall --check   # full inventory — writes nothing
+npx klypix-mcp uninstall           # asks, then removes the machine-global install
+npx klypix-mcp uninstall unlink    # run inside a project: removes the files `link` wrote there
 ```
 
+It strips only KLYPIX's own entries — every other hook and setting in
+`~/.claude/settings.json` stays — backs up each file it edits, and **never deletes a `.klypix`**.
+`--yes` skips the prompt for scripted removal.
+
 Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.
 
 ## Contributing
 
 Issues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
 
-The repository carries 28 test files covering the presence lane, Context Gateway, supervisor
-hot-swap, auto-update, retrieval quality, decay, challenge, lenses and conformance. Run them with
-`npm test` from a clone — they are not in the published tarball and the publish workflow does not
-run them. There is a known intermittent Windows `EPERM` flake on rename in
+The repository carries 38 test files, 34 of them in the `npm test` chain, covering the presence
+lane and its cross-machine relay, the Context Gateway, supervisor hot-swap, auto-update, retrieval
+quality, decay, challenge, lenses, the format guard, the git tools (including a real `git merge`
+through the merge driver), uninstall, and conformance. Run them with `npm test` from a clone — they
+are not in the published tarball, though the publish workflow does run them as a gate. There is a known intermittent Windows `EPERM` flake on rename in
 `test/mcp-supervisor.mjs`.
 
 ## Why this exists

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init', 'git-driver', 'diff', 'pr-brief']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init', 'git-driver', 'diff', 'pr-brief', 'uninstall']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -31,12 +31,12 @@ const USAGE = [
   '  conformance [--json]                launch two real MCP clients against this build',
   '  init                                seed a starter ./brain.klypix + print an MCP config',
   '  garden-code [brain]                 print the human approval code for brain_garden',
+  '  uninstall [--check|--yes|unlink]    remove this install from the machine (--check inventories first; never deletes a .klypix)',
   '  git-driver [install|status] [repo]  register the lossless .klypix merge driver for a repo (zero-command teams)',
   '  diff [ref] [--brain <path>]         readable brain diff vs a git ref (default HEAD) — markdown to stdout',
   '  pr-brief [baseRef] [--brain <path>] brain decisions touching the files changed since baseRef — PR-comment markdown',
   '',
   'With no verb (or any --flag, e.g. --vault <dir>) it runs as an MCP stdio server.',
-  'There is no uninstall command — removal is manual (see README).',
 ].join('\n');
 
 const verb = process.argv[2];

package/bin/klypix-worker.mjs

@@ -110,6 +110,13 @@ await runVerb('git-driver', './klypix-git-driver.mjs');
 await runVerb('diff', './klypix-diff.mjs');
 await runVerb('pr-brief', './klypix-pr-brief.mjs');
 
+// `npx klypix-mcp uninstall` — the machine-global removal tool. `--check` prints a full
+// inventory and writes nothing; every write is backed up; a `.klypix` brain is never
+// touched. Wired into the dispatcher 2026-08-01: it shipped as a bin-only verb, so
+// `npx klypix-mcp uninstall` answered "unknown command" while the README (and this
+// CLI's own --help) said no uninstall existed at all.
+await runVerb('uninstall', './klypix-uninstall.mjs');
+
 // `npx klypix-mcp garden-code` — the HUMAN half of the garden approval gate.
 // brain_garden's apply requires an 8-char code derived from the exact dormant
 // candidate set + day; the agent is deliberately never shown it. The human runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.49.0",
+  "version": "1.49.2",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",

package/src/klypix-format.mjs

@@ -126,12 +126,27 @@ export async function parseKlypix(buffer) {
     // (merge, arrange, capture) a structure it does not understand. The merge
     // driver inherits this automatically: the throw exits it non-zero, which
     // degrades to a normal manual git conflict.
+    // Both dimensions, or the guard has a hole: `version` is the CONTAINER shape and
+    // `schemaVersion` is the DOCUMENT (item/connection) shape, and they move
+    // independently. The desktop codec already refused a future value of either
+    // (klypixFormatV4.ts assertManifestReadable); checking only `version` here left
+    // {version:4, schemaVersion:5} parsed by this engine and refused by the app —
+    // the asymmetric case, where merge/git-driver/capture would happily write back a
+    // document they did not understand. Found by the 2026-08-01 doc audit.
     const KLYPIX_FORMAT_CEILING = 4;
-    if (manifest && manifest.format === 'klypix' && Number(manifest.version) > KLYPIX_FORMAT_CEILING) {
-        throw new Error(
-            `This .klypix was saved by a newer format (v${manifest.version}); this engine reads up to v${KLYPIX_FORMAT_CEILING}. ` +
-            'Update KLYPIX / klypix-mcp instead of parsing it — a blind read could damage it.'
+    if (manifest && manifest.format === 'klypix') {
+        const layout = Number(manifest.version);
+        const schema = Number(manifest.schemaVersion);
+        const tooNew = Math.max(
+            Number.isFinite(layout) ? layout : 0,
+            Number.isFinite(schema) ? schema : 0,
         );
+        if (tooNew > KLYPIX_FORMAT_CEILING) {
+            throw new Error(
+                `This .klypix was saved by a newer format (v${tooNew}); this engine reads up to v${KLYPIX_FORMAT_CEILING}. ` +
+                'Update KLYPIX / klypix-mcp instead of parsing it — a blind read could damage it.'
+            );
+        }
     }
     const canvas = JSON.parse(canvasRaw);
     // v4 manifests are {format:"klypix", version:4}; positions presence is the