klypix-mcp 1.49.1 → 1.50.0

package/A2A.md

@@ -1,4 +1,4 @@
-# KLYPIX speaks A2A
+# KLYPIX speaks A2A protocol v0.3.0
 
 KLYPIX is the **shared, human-owned memory node** for a multi-agent stack.
 **A2A moves the messages between agents; `.klypix` holds the context they read
@@ -23,11 +23,13 @@ KLYPIX_VAULT=./canvases KLYPIX_A2A_PORT=41241 npx -p klypix-mcp klypix-a2a
 ```
 
 Flags / env: `--vault` (`KLYPIX_VAULT`), `--port` (`KLYPIX_A2A_PORT`, default
-`41241`), `--host` (`KLYPIX_A2A_HOST`, default `127.0.0.1`).
+`41241`), `--host` (`KLYPIX_A2A_HOST`, loopback only), and
+`--allow-cross-project` (opt in to machine-wide registered-brain search).
 
-It is **local-first**: it binds loopback and needs no auth, because the file
-lives on your disk. To expose it, set `--host 0.0.0.0` behind a reverse proxy
-that terminates TLS and adds authentication.
+It is **local-only**: it binds loopback and needs no auth because callers are on
+the same machine. Non-loopback `--host` values are refused. Remote exposure is
+unsupported until authentication, TLS, a real identity model, and cross-process
+write coordination exist together.
 
 ## Discover it
 
@@ -45,12 +47,14 @@ the skills below.
 | Skill `id` | Does | Returns |
 |---|---|---|
 | `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` |
+| `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 |
 | `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 |
+| `search_all_brains` | Cross-project memory search (semantic + lexical); advertised only with `--allow-cross-project` | text |
+| `brain_connect` | Find and draw related-but-unlinked cards (proposes before it applies) | text |
 
 ## Talk to it (JSON-RPC 2.0)
 
@@ -84,7 +88,8 @@ POST /
 
 The result is an A2A `Task` whose `artifacts[0].parts` contains a
 `{ kind: "file", file: { mimeType: "application/vnd.klypix+zip", bytes } }` — the
-board itself.
+board itself. If `configuration.acceptedOutputModes` excludes that MIME type,
+the server honors the negotiation and does not send the FilePart.
 
 **Free-text invocation** — a plain message is routed by intent (a convenience
 for chat-style callers):
@@ -107,11 +112,27 @@ server resumes it with a stable id and accumulated history).
   returns a terminal `Task`. `message/stream` emits a **monotonic** lifecycle in
   one burst — a non-terminal `Task` (`submitted`), then (for completed work) an
   `artifact-update`, then exactly one terminal `status-update` with `final:true`.
-- The server binds loopback and exposes no auth; the A2A face additionally
-  refuses any `canvas` reference that resolves **outside the vault** (absolute or
-  `..` paths), even though the underlying engine would allow it for the trusted
-  MCP/stdio caller.
-- Provenance: writes are stamped with the calling agent's name when supplied via
-  `message.metadata.agentName` (or a `DataPart` `agentName`), else `a2a`.
-- The A2A and MCP faces share one engine (`src/klypix-core.mjs`); neither can
-  corrupt the other, and both operate only on the `.klypix` files in the vault.
+- The server validates the request `Host`, rejects foreign browser `Origin`
+  headers, accepts only `application/json` POST bodies (maximum 1 MiB), and emits
+  no permissive CORS header. The Agent Card and health endpoint do not disclose
+  the local vault path.
+- For every caller-supplied canvas reference — including a path supplied in a
+  text part — the server resolves the effective target once, follows symlinks,
+  and refuses it if the resulting file is outside the configured vault. The
+  project brain selected by the operator's launch `cwd` remains a separate,
+  intentional default for brain-specific operations.
+- Provenance is a claim, not authentication: supplied agent names are bounded,
+  slugged, and stamped as `a2a:<name>` so they cannot render like an attested
+  local `createdVia` identity.
+- `search_all_brains` is absent from the default Agent Card and rejected unless
+  the operator starts the server with `--allow-cross-project`; it intentionally
+  reads the machine-wide brain registry and cannot be made vault-scoped.
+- A2A writes are serialized **within the server process only**. The desktop app,
+  hooks, and other processes are not coordinated by that lock. Any move off
+  loopback or to concurrent multi-process callers requires the shared
+  cross-process lock first. Do not describe this as conflict-free or lossless
+  across processes.
+- A2A does not provide `brain_sync`, presence registration, `brain_message`, or
+  `brain_garden` apply. HTTP has no reliable session-close lifecycle for presence,
+  messaging would be send-only, and garden's out-of-band human approval gate must
+  not be weakened for protocol symmetry.

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
@@ -435,20 +435,21 @@ echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
   | npx -p klypix-mcp klypix-write --out plan.klypix
 ```
 
-## Also speaks A2A (Agent-to-Agent) — experimental
+## Also speaks A2A protocol v0.3.0 — experimental
 
 ```bash
 npx -p klypix-mcp klypix-a2a --vault ./canvases     # 127.0.0.1:41241
 # Agent Card: http://127.0.0.1:41241/.well-known/agent-card.json
 ```
 
-Nine skills: `make_board`, `remember`, `learn_skill`, `recall`, `read_canvas`, `list_canvases`,
-`brain_insights`, `search_all_brains`, `brain_connect`. Unlike a typical A2A agent that returns
-text, KLYPIX returns the `.klypix` board itself as a multimodal artifact. Details:
+Eight vault/project skills by default: `make_board`, `remember`, `learn_skill`, `recall`,
+`read_canvas`, `list_canvases`, `brain_insights`, `brain_connect`. Machine-wide
+`search_all_brains` is a ninth, explicit opt-in via `--allow-cross-project`. Unlike a typical A2A
+agent that returns text, KLYPIX returns the `.klypix` board itself as a multimodal artifact. Details:
 [A2A.md](A2A.md).
 
-Treat this as a preview: the A2A smoke test is not in the default `npm test` chain, and it has not
-been exercised against a third-party A2A client.
+Treat this as a preview: the adversarial A2A smoke test runs in the default `npm test` chain, but
+the server has not been exercised against a third-party A2A client.
 
 ## Updates — the propagation contract
 
@@ -494,7 +495,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.
@@ -502,10 +506,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.
@@ -517,8 +520,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
@@ -542,25 +547,27 @@ independently validated.
 
 ## 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