klypix-mcp 1.43.1 → 1.45.0

package/FORMAT.md

@@ -5,21 +5,35 @@
 your.klypix`), and parseable with the Apache-2.0 library in this package. You own it;
 any agent or app can read and write it.
 
+Two working examples ship in this package under [`examples/`](examples/). Both are
+text-and-arrows only (14 cards, no `assets/` entry), so they demonstrate the card /
+container / connection model, not the embedded-binary half described below.
+
 ## Container layout
 
 ```
-your.klypix              (a ZIP archive)
-├── manifest.json        metadata + stats
-├── canvas.json          spatial layout: order, positions, connections, lines, strokes, settings
+your.klypix                      (a ZIP archive)
+├── manifest.json                metadata + stats; read FIRST
+├── canvas.json                  spatial layout: order, positions, connections, lines, strokes, view, settings
 ├── items/
-│   └── <2-hex>/<id>.json one file per item (content only; position lives in canvas.json)
-└── assets/
-    └── <assetId>        embedded binaries (images, PDFs, audio, video, files)
+│   └── <shard>/<id>.json        one file per item (content only; geometry lives in canvas.json)
+└── assets/                      embedded binaries — any non-directory entry here is an asset
+    ├── images/<shard>/<sha256>.<ext>
+    ├── files/<shard>/<sha256>.bin
+    └── thumbs/<itemId>.png
 ```
 
-Item files are **sharded** by the first 2 hex chars of the id's random part
-(e.g. `items/a3/txt_a3f9…json`) so a canvas with thousands of items stays fast
-to read partially.
+`<shard>` is the **first two characters of the id (or sha) after its namespace
+prefix is stripped**, lowercased, left-padded with `_` if shorter — e.g.
+`txt_hto5hb3r_0_0` → `items/ht/txt_hto5hb3r_0_0.json`, and sha `a3f9…` →
+`assets/images/a3/a3f9….png`. Ids are base36-ish, not strictly hex, so treat the
+shard as "two characters", not "two hex digits". Sharding bounds files-per-directory
+and lets a canvas with thousands of items be read partially.
+
+Readers should treat the `assets/` sub-layout as **convention, not contract**: this
+package's parser counts and reads *any* non-directory entry under `assets/`, so a
+writer that flattens to `assets/<assetId>` still parses. Only the KLYPIX app's own
+writer guarantees the content-addressed `images/ files/ thumbs/` split.
 
 ## `manifest.json`
 
@@ -28,13 +42,30 @@ to read partially.
   "format": "klypix",
   "version": 4,
   "schemaVersion": 4,
+  "kind": "brain",
   "createdAt": "ISO-8601",
   "updatedAt": "ISO-8601",
   "title": "My board",
-  "stats": { "itemCount": 12, "assetCount": 3, "totalBytes": 0 }
+  "stats": { "itemCount": 12, "assetCount": 3, "totalBytes": 0 },
+  "sync": { "enabled": false, "lastSyncRev": null, "lastSyncAt": null, "deviceId": "dev_…" }
 }
 ```
 
+- `version` — on-disk **layout** version (the container shape).
+- `schemaVersion` — **document** version (item/connection shapes).
+- **`kind: "brain"`** — optional and additive; present only on a **project brain**.
+  A brain is the co-owned agent/human memory file, and it gets stricter write
+  semantics: union-merge-on-save under a capture lock, tombstone-only deletes. It is
+  detected as `manifest.kind === "brain"` **OR** a `brain.*` basename — the filename
+  convention keeps working forever, and the flag makes those semantics survive a
+  rename. Plain canvases omit `kind` entirely, and older readers ignore it.
+- `stats` is **informational only.** `totalBytes` is an uncompressed estimate (the
+  on-disk size depends on compression), and `itemCount` is derived from
+  `canvas.json.order`, which can disagree with the number of files actually under
+  `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.
+
 ## `canvas.json`
 
 ```json
@@ -46,21 +77,34 @@ to read partially.
     "<id>": { "x": 0, "y": 0, "w": 280, "h": 80, "zKey": "a001", "zIndex": 1, "parentId": null }
   },
   "connections": [                                 // arrows between items
-    { "id": "con_…", "fromId": "<id>", "toId": "<id>", "relationship": "leads_to", "arrowHead": true }
+    { "id": "con_…", "fromId": "<id>", "toId": "<id>",
+      "relationship": "conflicts_with", "label": "corrects",   // both optional
+      "arrowHead": true, "width": 2, "color": "#10b981", "style": "solid" }
   ],
   "lines": [], "strokes": [],                      // freehand drawing
-  "settings": { "background": "#0a0a0f" }
+  "nextGroupNumber": 4,                            // container auto-naming counter
+  "settings": { "background": "#0a0a0f", "gridStyle": "dots", "gridColor": "…" }  // all optional
 }
 ```
 
 Position/geometry is kept in `canvas.json.positions`, **not** in the item file —
 so moving an item never rewrites its content, and the spatial layout can be read
-without loading every item.
+without loading every item. `zKey` is a fractional index and is the source of truth
+for z-order; `zIndex` is a numeric cache kept in step with the `order[]` index.
+`settings` is optional and captures the *sender's* visual context, so a recipient
+does not see someone else's canvas in their own theme.
+
+`order` and `positions` are the two indexes a reader walks. A tolerant reader skips
+an `order` entry with no `positions` row and an entry with no file under `items/`
+(this package's parser does both) — but note that a writer which then re-serializes
+that state can make the omission permanent.
 
 ## Item files — `items/<shard>/<id>.json`
 
-Content only (no x/y/w/h). Common types: `text`, `box`, `image`, `file`,
-`code`, `video`, `audio`, `link`, `canvasLink`, `container`. Example text item:
+Content only — no `id` (it is in the path) and no `x/y/w/h/zIndex/zKey/parentId`
+(those are in `canvas.json.positions`). The `type` field is one of exactly eleven
+strings: `text`, `box`, `image`, `file`, `container`, `approval`, `link`,
+`canvas-link`, `video`, `audio`, `code`. Example text item:
 
 ```json
 {
@@ -70,12 +114,44 @@ Content only (no x/y/w/h). Common types: `text`, `box`, `image`, `file`,
   "color": "#e8e8ed",
   "border": true,
   "heading": false,
-  "createdBy": "agent"
+  "createdBy": "agent",
+  "createdVia": "claude-code"
 }
 ```
 
-Items can reference an embedded binary in `assets/` (e.g. an `image`/`file`/
-`video`/`audio` item points at its asset id).
+`createdBy` (`user` | `agent`) and the optional `createdVia` (which agent/channel
+captured it) are the provenance bits the brain surfaces as badges and lenses.
+
+## Bytes: when they are embedded vs referenced
+
+**Embedded** — the bytes live inside the ZIP under `assets/`, and the item JSON
+references them by key/sha:
+
+| Item type | What is embedded |
+|---|---|
+| `image` | the original image (plus an optional downscaled `thumbnailAssetId`). Non-destructive crop/rotate/annotation data lives in the item JSON; the original asset stays canonical. |
+| `file` | the original file bytes. A **folder card** (`isFolder: true`) embeds the whole directory as one ZIP asset, with a `folderManifest` listing what's inside so the card renders without unzipping. |
+| `video`, `audio` | the media bytes, streamed from the asset at render time rather than loaded whole. |
+
+**Referenced, never embedded** — nothing is copied into the file:
+
+| Item type | What it points at |
+|---|---|
+| `link` | a remote `url` (+ cached Open Graph title/description; the OG image is fetched live, not stored) |
+| `canvas-link` | another `.klypix` file by **absolute path on disk** — so it breaks if you email the file alone |
+| `text`, `code`, `box`, `container`, `approval` | content is inline in the item JSON; there is no asset at all |
+
+`file` / `video` / `audio` items may also carry `originalPath` — a convenience
+pointer for "open in the OS app". The bytes are still embedded; the path is not the
+source of truth.
+
+Legacy files may carry an `image` item's bytes as an inline base64 `src` data URL
+instead of an asset. New writers use `assetId` and leave `src` empty.
+
+**This package reads assets but does not create them.** `create_canvas`,
+`add_to_canvas` and `buildKlypix` write `manifest.json`, `canvas.json` and item
+files — cards and arrows. Embedding binaries is done by the KLYPIX app when you drop
+a file onto a canvas.
 
 ## Connections, links, tags
 
@@ -85,10 +161,56 @@ Items can reference an embedded binary in `assets/` (e.g. an `image`/`file`/
 - **`[[wikilinks]]`** inside text content cross-link cards (and auto-draw edges).
 - **`#tags`** inside text content group cards.
 
+## Versioning — and a real limitation
+
+`manifest.version` is the layout version and `manifest.schemaVersion` the document
+version. Both are `4` today.
+
+**There is no migration path registered for v4, and the v4 load path does not run
+one.** Be precise about what that means, because it is a live limitation, not a
+to-do that is quietly handled:
+
+- The migration framework exists and works, but its table contains exactly two
+  steps, `1 → 2` and `2 → 3`. Only the legacy `.any` (v1–v3) read path walks it; the
+  v4 path never enters the migration runner.
+- Both this package's parser and the KLYPIX app's v4 reader treat
+  `manifest.version >= 4` as "this is v4" and dispatch on nothing else — the app's
+  deserializer never reads `manifest.version`, `manifest.schemaVersion` or
+  `canvas.json.version` at all.
+- So a hypothetical v5 or v6 file **opens as v4**: fields the reader does not know
+  are dropped, with no "this build is too old to open it" error anywhere. Saving it
+  from the app then rewrites `version: 4` — a silent downgrade. (This package's
+  `appendToKlypix` is non-destructive by construction: it mutates the parsed
+  manifest and `canvas.json` in place and leaves every existing item file byte-for-byte
+  untouched, so unknown fields survive a round trip through it.)
+
+Consequences for anyone implementing against this format: do not assume a future
+version will be rejected for you, and if you write `.klypix` files, do not bump
+`manifest.version` past 4 expecting existing readers to refuse them safely. If you
+extend the format, prefer **additive** optional fields (the way `manifest.kind` was
+added) over a version bump.
+
 ## Legacy `.any` (v1–v3)
 
 Older files keep an inline `items` array at the root of `canvas.json` instead of
-the `items/` folder + `positions` map. The parser in this package handles both.
+the `items/` folder + `positions` map. The parser in this package handles both, and
+detects the older shape by the absence of `positions` even if the manifest is
+missing. Legacy files are migrated `1 → 2 → 3` on open by the app.
+
+## Practical size limits
+
+The format itself imposes no size limit — a `.klypix` is a ZIP. The limits below are
+**guards in the KLYPIX app**, not properties of the format, and this package's
+parser enforces none of them:
+
+| Limit | Value | Where it applies |
+|---|---|---|
+| Per-file (leaf) on folder ingest | **200 MB** | a single file inside a dropped folder; anything larger is skipped and recorded in the card's `folderSkipped` list so you can see what was left out |
+| Per folder card, total | **1 GB** | ingestion stops once a dropped folder would push the card past this |
+| Per cloud share | **50 MB** | sharing a canvas through the app's cloud; a larger canvas is refused with a `too-large` result rather than truncated |
+
+Nothing stops you writing a larger file locally with this library; expect the app's
+share and folder-ingest paths to refuse it.
 
 ## Read / write it
 
@@ -102,4 +224,11 @@ const buf = await buildKlypix({ title: 'Plan', cards: [{ text: 'kickoff' }] });
 fs.writeFileSync('plan.klypix', buf);
 ```
 
+Or from a shell, against one of the examples in the tarball:
+
+```bash
+npm i klypix-mcp
+npx klypix-read node_modules/klypix-mcp/examples/showcase-brain.klypix
+```
+
 That's the whole contract: **a ZIP you own, that any model can read and write.**

package/NOTICE

@@ -0,0 +1,6 @@
+klypix-mcp
+Copyright 2026 Abdullah Aldahshan — Dahshan Labs
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+Prior published versions (<= 1.28.0) were released under the MIT License and
+remain available under those terms.

package/README.md

@@ -85,16 +85,28 @@ It verifies 7 coordination behaviours — not the 18 tools, and not the retrieva
 
 ## Quick start
 
-**Claude Code + Codex — one machine-global command:**
+**Claude Code + Codex:**
 
 ```bash
 npx klypix-mcp install
 ```
 
 This copies the engine and a local MCP runtime into `~/.claude/project-brain`, wires Claude Code's
-four lifecycle hooks, and wires Codex's project MCP connection. It is machine-global: every project
-on that machine with a `./brain.klypix` is covered. It does **not** set up Cursor, Cline, Windsurf,
-Copilot, Gemini CLI or Aider — those need `link`.
+four lifecycle hooks, writes Codex's global `~/.codex/AGENTS.md` guidance block, and wires Codex's
+MCP connection **for the project you run it in**.
+
+Be precise about what "machine-global" covers:
+
+- **Machine-global** — the engine + runtime in `~/.claude/project-brain`, the four Claude Code
+  hooks in `~/.claude/settings.json`, and the `~/.codex/AGENTS.md` guidance. Claude Code is
+  therefore covered in every project on that machine that has a `./brain.klypix`.
+- **Per project** — Codex's MCP connection. `install` writes it into `<cwd>/.codex/config.toml`,
+  only when that directory has a `brain.klypix`, and it deliberately **removes** any *global*
+  `~/.codex/config.toml` KLYPIX entry (a global entry resolves its `--vault` from the wrong
+  directory and binds the wrong brain). Run `install` — or `link` — once inside each brain project
+  you want Codex wired to.
+
+It does **not** set up Cursor, Cline, Windsurf, Copilot, Gemini CLI or Aider — those need `link`.
 
 Optional, opt-in, and approved inside Codex itself:
 
@@ -174,8 +186,9 @@ behaviour is unverified.
 | **Aider** | Rules file only (no MCP) | `link` | CLI path: `npx klypix-read` | CLI path: `npx klypix-append` | — |
 | **Claude Desktop** | One-time manual config edit | you | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
 
-`install` and `link` are different things and are not interchangeable: `install` is machine-global
-and only touches Claude Code and Codex; `link` is per project and is what wires everything else.
+`install` and `link` are different things and are not interchangeable: `install` only touches Claude
+Code and Codex, and is machine-global for everything except Codex's MCP connection, which it writes
+per project (see *Quick start*); `link` is per project and is what wires everything else.
 
 **Claude Desktop** — add this to `claude_desktop_config.json` by hand; nothing writes that file
 for you:
@@ -329,10 +342,12 @@ Exactly 18, machine-verifiable with `npx klypix-mcp doctor`.
 
 ## One file you can hold
 
-The whole brain — layout, cards, arrows, and the actual bytes (images, PDFs, audio, code) — is a
+The whole brain — layout, cards, arrows, and the actual bytes (images, PDFs, audio, video) — is a
 single `.klypix` file: a plain ZIP with `manifest.json`, `canvas.json`, one JSON file per card, and
 an `assets/` folder. Email it. Git it. Hand it to an agent. A folder of markdown points at its
-attachments; this file carries them.
+attachments; this file carries them. (Binaries are embedded by the **KLYPIX app** when you drop a
+file onto a canvas; this package's `create_canvas` / `add_to_canvas` / `buildKlypix` write cards and
+arrows, not assets — they read assets fine, they just don't create them.)
 
 The parser is this package, Apache-2.0, so any tool or agent can read and write the format. Full
 spec: [FORMAT.md](FORMAT.md).
@@ -341,14 +356,24 @@ Markdown export, JSON Canvas 1.0 export and direct opening of Obsidian `.canvas`
 of the **KLYPIX desktop app**, not of this package — there is no export command among this
 package's binaries.
 
-**"Project" means any project.** Two showcase brains ship in the GitHub repo under
-[`examples/`](examples/), identical in engine, different in life:
+**"Project" means any project.** Two showcase brains ship in the npm package *and* the GitHub repo
+under [`examples/`](examples/), identical in engine, different in life:
 [`showcase-brain.klypix`](examples/showcase-brain.klypix) is *Aurora*, a fictional weather app
 mid-build (radar tiles, API caps, a correction with its receipt), and
 [`showcase-wedding.klypix`](examples/showcase-wedding.klypix) is *Our Wedding* (venue, vendors,
 guest list, the same correction machinery pointed at a caterer). Same 📌 Focus, same arrows, same
 brief. If it has decisions worth keeping, it gets a brain.
 
+They ship inside the tarball, so you can read one straight out of `node_modules`:
+
+```bash
+npm i klypix-mcp
+npx klypix-read node_modules/klypix-mcp/examples/showcase-brain.klypix
+```
+
+Both are text-and-arrows only — 14 cards, 4 arrows, no `assets/` entry — so they demonstrate the
+card / container / connection model, not the embedded-binaries half of the format.
+
 ## Use it as a library
 
 ```js
@@ -407,9 +432,11 @@ entirely.
 - **Coordination state is local files.** The brain is a file in your repo; the presence lane is a
   file under your home directory. Nothing is uploaded.
 - **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
-  `~/.claude/settings.json` (four hooks — written even if Claude Code is not installed) and Codex
-  config. **`link` writes 14 files inside the project** you run it in; `link --check` audits them
-  without writing.
+  `~/.claude/settings.json` (four hooks — written even if Claude Code is not installed),
+  `~/.codex/AGENTS.md` (guidance block), and with `--codex-hooks`, `~/.codex/hooks.json`. It also
+  writes `<cwd>/.codex/config.toml` **inside the project** you run it in, and removes any KLYPIX
+  entry from the global `~/.codex/config.toml`. **`link` writes 14 files inside the project** you
+  run it in; `link --check` audits them without writing.
 - **Codex hooks require Codex's own trust approval** and are opt-in via `--codex-hooks`.
 
 ## Current limitations
@@ -498,5 +525,15 @@ and write.
 
 ---
 
-Apache-2.0 © [Dahshan Labs](https://klypix.com). The KLYPIX desktop app is a separate, proprietary
-product — the format and this server are fully open and work without it.
+## Licence
+
+This package — the MCP server, the agent hooks and the `.klypix` format parser — is
+**Apache-2.0** ([`LICENSE`](LICENSE), attribution in [`NOTICE`](NOTICE)). Versions up to and
+including **1.28.0** were published under MIT and remain available under those terms; **1.29.0** was
+the first Apache-2.0 release.
+
+The KLYPIX desktop app and the klypix.com web app are **separate, proprietary products** — their
+source is not public, and their terms do not restrict anything Apache-2.0 grants you here. This
+package works with no app installed.
+
+Apache-2.0 © [Dahshan Labs](https://klypix.com).

package/bin/klypix-conformance.mjs

@@ -17,6 +17,10 @@ import { LoggingMessageNotificationSchema } from '@modelcontextprotocol/sdk/type
 import { buildKlypixMap } from '../src/klypix-core.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
+// ARGV: flag lookup is position-independent, so this file is already correct for
+// both `klypix-conformance --json` and `klypix-mcp conformance --json` (the
+// dispatcher splices its verb out — see bin/klypix-worker.mjs runVerb). Kept as
+// `includes` deliberately; test/cli-args.mjs asserts the two forms stay identical.
 const jsonMode = process.argv.includes('--json');
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const PKG_VERSION = (() => {

package/bin/klypix-doctor.mjs

@@ -13,12 +13,21 @@
 //
 // Synchronous-ish top-level by design: the dispatcher does `await import(this);
 // process.exit(...)`, so all work completes during module evaluation.
+import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
 import { inspect, render, inspectAll } from '../src/brain-doctor.mjs';
 
+// ARGV: same dual shape as klypix-link — this file is both `klypix-doctor` and the
+// target of `klypix-mcp doctor` (the dispatcher splices its verb out first, see
+// bin/klypix-worker.mjs runVerb). slice(2) is the one correct shape; the strip is
+// belt-and-braces for a dispatcher that did not splice, and refuses to eat a
+// directory actually named ./doctor.
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
 try {
-  const argv = process.argv.slice(2);
+  const raw = process.argv.slice(2);
+  const argv = (raw[0] === 'doctor' && !isDir(path.resolve(raw[0]))) ? raw.slice(1) : raw;
   const has = (f) => argv.includes(f);
   const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined; };
   const color = !has('--no-color') && process.stdout.isTTY !== false;

package/bin/klypix-install.mjs

@@ -34,6 +34,11 @@ const PKG_ROOT = path.resolve(__dirname, '..');
 const SRC = path.join(PKG_ROOT, 'src');
 const BIN = path.join(PKG_ROOT, 'bin');
 const VERSION = (() => { try { return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version || ''; } catch { return ''; } })();
+// ARGV: flag lookup is position-independent, so this file is correct for both
+// `klypix-install --force` and `klypix-mcp install --force` (the dispatcher splices
+// its verb out before importing — see bin/klypix-worker.mjs runVerb). It takes no
+// positional argument; if one is ever added, read process.argv.slice(2) so both
+// invocation shapes stay identical (locked by test/cli-args.mjs).
 const FORCE = process.argv.includes('--force');
 const CODEX_HOOKS = process.argv.includes('--codex-hooks');
 const RUNTIME_ONLY = process.argv.includes('--runtime-only');

package/bin/klypix-link.mjs

@@ -16,11 +16,24 @@
 //
 // Synchronous top-level by design: the dispatcher does `await import(this); process.exit(0)`,
 // so all work (and its logs) must complete during module evaluation, before exit.
+import fs from 'fs';
 import path from 'path';
 import { compactAgentsBrief, linkProject } from '../src/agent-rules.mjs';
 
+// ARGV: this file is BOTH `klypix-link` (its own published bin) and the target of
+// `klypix-mcp link` (the dispatcher splices its verb out of process.argv before
+// importing us — see bin/klypix-worker.mjs runVerb). slice(2) is therefore the ONE
+// correct shape for both. It used to be slice(3), which is right only via the
+// dispatcher: as a standalone bin `klypix-link --check` silently dropped --check
+// and WROTE all 14 managed files with exit 0, and `klypix-link <dir>` wrote into
+// the cwd instead of <dir>. The strip below is belt-and-braces for a dispatcher
+// that did not splice, and it refuses to eat a project folder actually named
+// ./link.
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
 try {
-  const args = process.argv.slice(3);
+  const raw = process.argv.slice(2);
+  const args = (raw[0] === 'link' && !isDir(path.resolve(raw[0]))) ? raw.slice(1) : raw;
   const check = args.includes('--check');
   const dirArg = args.find(a => !a.startsWith('-'));
   const projectDir = path.resolve(dirArg || process.cwd());
@@ -56,6 +69,20 @@ try {
   }
 
   const changed = [...rules, ...mcp, compactBrief].filter(r => r.action && !['unchanged', 'skipped'].includes(r.action)).length;
+  // A SKIPPED target is not wired (invalid MCP JSON left untouched, or a Codex
+  // TOML write that failed). Write mode used to filter those out of the count,
+  // print the blanket "every agent … now reads + captures" line anyway, and exit
+  // 0 — while `--check` on the same project correctly reported drift and exited 1.
+  // Report the truth and fail, so the two modes agree.
+  const skipped = [...rules, ...mcp].filter(r => r.action === 'skipped');
+  const managed = rules.length + mcp.length;
+  if (skipped.length) {
+    console.log(`\n✗ ${skipped.length} target(s) could not be wired:`);
+    for (const r of skipped) console.log(`    ⚠ ${r.tool.padEnd(26)} ${r.file}${r.why ? ' — ' + r.why : ''}`);
+    console.log(`\n  wired ${managed - skipped.length} of ${managed} managed file(s) (${changed} written/updated this run).`);
+    console.log('  Fix the file(s) above (or move them aside) and re-run `npx klypix-mcp link`.');
+    process.exit(1);
+  }
   console.log(`\n✓ ${changed} file(s) written/updated — every agent opened in this project now reads + captures ./brain.klypix.`);
   console.log('  Codex, Cline, Gemini/Antigravity, Cursor, and VS Code get project MCP configs; Windsurf uses its global MCP plus project rules.');
   console.log('  Verify anytime with `npx klypix-mcp link --check` (or `npx klypix-mcp doctor`).');

package/bin/klypix-mcp.mjs

@@ -20,7 +20,38 @@ const PKG_VERSION = (() => {
 })();
 
 const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init']);
-if (DIRECT.has(process.argv[2])) {
+
+const USAGE = [
+  `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
+  '',
+  'Verbs:',
+  '  install [--force] [--codex-hooks]   install/update this machine\'s brain engine + Claude Code hooks',
+  '  link [dir] [--check]                project this project\'s 14 managed agent config files (--check audits, writes nothing, exits 1 on drift)',
+  '  doctor [--npm] [--all] [--json]     read-only self-check; exits 1 on drift',
+  '  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',
+  '',
+  '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];
+if (verb === '--help' || verb === '-h' || verb === 'help') {
+  console.log(USAGE);
+  process.exit(0);
+}
+// A bare unknown WORD used to fall through to the stdio server, which then sat
+// waiting on a stdin that no host was driving — so `npx klypix-mcp uninstall`
+// (or any typo) printed nothing and exited 0, indistinguishable from success.
+// Only non-dash tokens are rejected: a real host launch is `--vault <dir>`,
+// and the local-bundle launch form puts '--vault' at argv[2] too.
+if (verb && !verb.startsWith('-') && !DIRECT.has(verb)) {
+  console.error(`klypix-mcp: unknown command "${verb}".\n\n${USAGE}`);
+  process.exit(2);
+}
+
+if (DIRECT.has(verb)) {
   await import('./klypix-worker.mjs');
 } else {
   const { runMcpSupervisor } = await import('../src/mcp-supervisor.mjs');