npm - bantamkit-mcp - Versions diffs - 0.33.0 → 0.34.1 - Mend

bantamkit-mcp 0.33.0 → 0.34.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md CHANGED Viewed

@@ -1,324 +1,239 @@
-# bantamkit-mcp
-The bantamkit MCP server as a pure-Node package: `npx bantamkit-mcp`, no Python, no
-`uv`, no `pipx`, no interpreter bootstrap. It serves the same twelve tools, the same
-`bantamkit_status` prompt and the same two resource templates as `runtime-py`'s server,
-reads and writes the same memory store, and is checked against the Python server frame by
-frame — 4500+ conformance cases, with every intentional difference written down as a
-ruling. It installs **two** commands, not one — the server and `bantamkit-memory`, the
-operator CLI for memory-store lifecycle; see *The second bin* below.
-Every number on this page was measured on the machine that wrote it, with a command you
-can rerun. Where something was not measured, it says so.
-## Install and run
-```jsonc
-// .mcp.json — project scope
-{
-  "mcpServers": {
-    "bantamkit": {
-      "command": "npx",
-      "args": ["-y", "bantamkit-mcp"]
-    }
-  }
-}
-```
-That is the whole install. No `pip`, no venv, no `PYTHONPATH`. `runtime-ts/mcp.json.example`
-in the repository is the annotated version, with the four forms and the two measured
-questions that decide between them.
+# bantamkit-mcp — memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop
-**Pass `-y`.** `npx` historically prompted before installing a package it had not seen,
-and stdin here is the JSON-RPC channel: a prompt that consumed one frame looks like a
-server that lost a request. npm 11.6.2 was measured sending that prompt to stderr rather
-than reading stdin, but that is version-dependent and `-y` costs nothing.
+**bantamkit-mcp** is a pure-Node **MCP server** that gives coding agents a per-person **memory**
+store, JSON Schema validation and shift-work tools. Install it from **npm** with one `npx`
+command, connect it to **Claude Code**, **Claude Desktop**, **Cursor** or **GitHub Copilot in VS
+Code**, and every later launch starts **offline**. No Python, `pip`, `uv`, `pipx` or venv.
-**Pin the version.** `npx -y bantamkit-mcp` resolves `latest` and caches it, so two
-machines can run different builds from one identical config line. See *Silent version
-float* below — it is the failure this package makes easiest to hit and hardest to see.
+It serves the same twelve tools, `bantamkit_status` prompt and two resource templates as the
+Python server on **PyPI** (`pip install "bantamkit[mcp]"`), and reads and writes the same memory
+store. The two are compared frame by frame: 8,130 conformance cases on 2026-09-15, with every
+intentional difference written down as a ruling.
-### Connect it to a host
+## Contents
-**One command, and it writes the entry for you:**
+| Topic | What you'll find |
+|---|---|
+| [Install the MCP server](#install-the-mcp-server) | Two ways to launch it — pick one |
+| [Install once, run offline (recommended)](#install-once-run-offline) | One command; later launches need no network |
+| [Run with npx at every launch](#run-with-npx-at-every-launch) | The online form, and why it hangs offline |
+| [Connect to a host](#connect-to-a-host) | The same five steps for every host |
+| [Connect to Claude Code](#connect-to-claude-code) | `--install claude`, `claude mcp list`, `claude mcp remove` |
+| [Connect to Claude Desktop](#connect-to-claude-desktop) | `claude_desktop_config.json` per OS |
+| [Connect to Cursor](#connect-to-cursor) | `~/.cursor/mcp.json` |
+| [Connect to VS Code (GitHub Copilot)](#connect-to-vs-code-github-copilot) | `mcp.json` with the `servers` key |
+| [Connect other MCP clients](#connect-other-mcp-clients) | Any stdio host, and a GUI host's PATH |
+| [Updating](#updating) | `--update`, the per-install table, then restart |
+| [Troubleshooting](#troubleshooting) | Connection closed, timeouts, `ENOENT`, refusals, the wrong store |
+| [Configuration](#configuration) | Every flag and environment variable, with its default |
+| [Silent version float](#silent-version-float) | Why two machines run different builds, and `build_identity` |
+| [The operator CLI: `bantamkit-memory`](#the-operator-cli-bantamkit-memory) | The second bin: status, lint, compact, archive, restore |
+| [Memory stores are layered by default](#memory-stores-are-layered-by-default) | Why not to add `--store` by reflex |
+| [The asset pack](#the-asset-pack) | What ships in `assets/` and how it is found |
+| [Sharing a store with the Python server](#sharing-a-store-with-the-python-server) | Concurrent writes, and one hand-edit to avoid |
+| [Development](#development) | Build, test, conformance |
+| [Measurements and history](#measurements-and-history) | Where the measured numbers behind this page live |
+## Install the MCP server
+A host launches the server every session, so what matters is whether each launch needs the
+network. Pick **one** of the two ways below. To just try it: `npx -y bantamkit-mcp --assets-root`.
+### Install once, run offline
+**Recommended.**
 ```bash
-npx -y bantamkit-mcp --install claude          # Claude Code
-npx -y bantamkit-mcp --install claude-desktop  # Claude Desktop
-npx -y bantamkit-mcp --install copilot         # GitHub Copilot in VS Code
-npx -y bantamkit-mcp --install cursor          # Cursor
+npx -y bantamkit-mcp@latest --install claude   # or claude-desktop, copilot, cursor
 ```
-`--install claude` runs `claude mcp add` rather than editing `~/.claude.json` directly:
-that file is the host's, and it carries state that is not MCP configuration. What happens on
-a second run there is Claude Code's decision, not this command's, and `--force` does not
-reach it.
-**For the other three**, which are edited directly: it never prompts. A second run that
-finds its own entry says so and changes nothing; an entry that differs is refused, printed
-beside the one it would write, and replaced only with `--force`. Every write backs the file
-up first as `<name>.backup-<date>`, preserves the file's permissions, and a file that does
-not parse is refused rather than replaced.
-The rest of this section is what those commands write, for anyone who would rather do it by
-hand. Every host runs the same command; only the file and the key around it change.
-**Claude Code** — one command, no file to edit. `-s user` makes it available in every
-project; drop it for this project only.
+From 0.34.0 this runs `npm install --prefix ~/.bantamkit/mcp` once (Windows:
+`%USERPROFILE%\.bantamkit\mcp`, not measured) and records
+`<the node that ran it> ~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js`, both absolute.
+No later launch needs npx, the registry or your PATH. Measured from the published 0.34.0:
+install exit 0 in 8.14 s; the recorded command then served 12 tools in 0.09 s with the network
+cut.
+- **`@latest` matters:** without it npx may reuse an older cached resolve.
+- **It skips npm when the kept install already reports this version or a newer one.** It never
+  downgrades. If npm fails, no host file is read or written and no backup is taken.
+- **Run from any other install** (`npm i -g`, `npm i --prefix`, a checkout), it records that
+  install's own `dist/cli.js` instead.
+- **The recorded node is one version of node.** Switch away from it and re-run with `--force`.
+- **Replacing an old `npx` entry needs `--force`** (Claude Code: `claude mcp remove` first).
+- **Installing into another host while offline:** plain `npx -y` hangs before bantamkit starts.
+  Use `npx --offline -y bantamkit-mcp@0.34.0 --install <host>`, or the kept install's own CLI:
+  `<node> ~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js --install <host>`.
+To make the kept install by hand, install once, then register node and `cli.js` by absolute
+path (`node -p process.execPath` prints the node path). `-s user` makes it available in every
+project; drop it for this project only:
 ```bash
-claude mcp add bantamkit -s user -- npx -y bantamkit-mcp
+npm install --prefix ~/.bantamkit/mcp bantamkit-mcp@latest
+claude mcp add bantamkit -s user -- "$(node -p process.execPath)" ~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js
 ```
-**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
-on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Top-level key
-`mcpServers`; each entry takes `command`, `args` and an optional `env`.
+### Run with npx at every launch
 ```json
 {"mcpServers": {"bantamkit": {"command": "npx", "args": ["-y", "bantamkit-mcp"]}}}
 ```
-**GitHub Copilot in VS Code** — `.vscode/mcp.json` for one workspace, or the user
-profile via the **MCP: Open User Configuration** command. Note the top-level key is
-`servers`, not `mcpServers`.
+One config line (in `.mcp.json` for project scope, or a host's user config) and no install — but it asks the registry on **every** launch. Offline it fails
+silently: with a warm cache, `npx -y bantamkit-mcp`, `npx -y bantamkit-mcp@latest` and
+`npx -y bantamkit-mcp@0.33.0` each hung to the 45 s bound with 0 bytes on stdout, and the host
+reports only its own handshake timeout.
-```json
-{"servers": {"bantamkit": {"type": "stdio", "command": "npx", "args": ["-y", "bantamkit-mcp"]}}}
-```
-There is a CLI equivalent: `code --add-mcp '{"name":"bantamkit","command":"npx","args":["-y","bantamkit-mcp"]}'`.
-**Cursor** — `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` globally. Back
-to `mcpServers`.
+- **Pass `-y`.** stdin is the JSON-RPC channel, and an install prompt that read one frame would
+  look like a server that lost a request.
+- **Pin the version** (`bantamkit-mcp@0.34.0`) or add `@latest`: npx caches what `latest`
+  resolved to. See [Silent version float](#silent-version-float).
+- **`npx --offline -y bantamkit-mcp@<version>`** serves a warm cache without the registry (0.40 s
+  measured), and fails at once with `npm error code ENOTCACHED` on a cache that never saw it.
-```json
-{"mcpServers": {"bantamkit": {"command": "npx", "args": ["-y", "bantamkit-mcp"]}}}
-```
+`runtime-ts/mcp.json.example` in the repository is the annotated version, with five forms.
-**Anything else that speaks MCP over stdio** runs `npx -y bantamkit-mcp` and talks
-JSON-RPC on its stdin and stdout. Nothing about this package is host-specific.
+## Connect to a host
-The Claude Code and Claude Desktop forms were taken from this machine — `claude mcp add
---help` and an existing config file. The VS Code and Cursor forms are from those
-projects' own documentation, not from a host installed here.
+`--install <host>` (`claude`, `claude-desktop`, `copilot`, `cursor`) writes the entry. It never
+prompts, so it behaves the same in a terminal, in CI and inside another agent. For the three
+JSON hosts it backs the file up first as `<name>.backup-<date>`, keeps the file's permissions,
+refuses a file that does not parse, and refuses an entry that differs unless you pass `--force`.
-### Measured: what a cold start costs
+Each host below has the same steps: **1** command, **2** file, **3** entry, **4** confirm,
+**5** undo or re-run. The entry's `command` and `args` depend on the install route:
-`node tools/conformance/npx-cold-start.mjs` in the repo packs the tarball, installs it
-from disk into a cache that has never seen it, and drives a real MCP handshake. On
-node v25.2.1 / npm 11.6.2, macOS (darwin 25.5.0), Apple silicon:
-| | cold cache | warm cache |
-|---|---|---|
-| wall to the first JSON-RPC frame | **3.90 s** and **5.09 s**, two runs | **1.14 s** and **1.11 s** |
-| npm/npx bytes on stderr | 211 (an `npm notice` about npm itself) | 0 |
-Both cold figures are reported rather than averaged, and the two in that column are two
-runs from **one sitting on 2026-08-25** — the column is labelled "two runs" and one
-execution cannot honestly fill it.
-**The spread is bigger than a range would suggest, and it is the network.** Five cold
-runs on that same day, same machine, same commit, measured **3.68 / 3.90 / 4.66 / 5.09 /
-9.66 s**. An earlier revision of this table read "4.13 s and 7.36 s" and called a cold
-start "worth about 4-7 s here"; three of those five runs fall outside that range, so the
-range is dropped rather than re-fitted. What a reader should take from the cold column is
-an ORDER OF MAGNITUDE — seconds, dominated by the registry round trip, worse on a slower
-link — and not a number to compare a future run against. The warm figure is the one that
-is a property of this package, and it is stable across every run above.
-- **92 packages** installed (top-level under `node_modules`, scope-aware); **111**
-  `package.json` **under `node_modules`**, which is the count of packages actually
-  installed:
-  ```
-  find "$BED/cold/cache/_npx/<hash>/node_modules" -type f -name package.json | wc -l   # 111
-  ```
-  Counting from the `_npx/<hash>` directory instead gives **112**, and the extra file is
-  not a package: npx synthesises a `package.json` at that root holding the `file:` spec
-  and an `_npx.packages` array. The method is written down here because the 112 was read
-  once as a drift of one and it is not one — it is a different denominator. Reproduce
-  either with `node tools/conformance/npx-cold-start.mjs --keep`, which prints the scratch
-  path it leaves behind.
-- **15.7 MB** of files under `$npm_config_cache/_npx/<hash>` (26 MB of allocated blocks by
-  `du`), **37.8 MB** for the whole cache including npm's content-addressable store (this
-  read 37.7 until 2026-08-25; all four cold runs that day printed 37.8).
-- `bantamkit-mcp` itself is **0.9 MB** of that (1.2 MB allocated). The rest is
-  `@modelcontextprotocol/sdk@1.30.0`'s dependency tree, which pulls in `express`, `cors`,
-  `body-parser`, `ajv`, `eventsource`, `hono` and `express-rate-limit` — the SDK's HTTP
-  transport, none of which this stdio server uses. That is the SDK's shape, not a choice
-  this package makes; it declares exactly one runtime dependency.
-- The tarball is **~266 KB**, 137 files: 50 in `dist/`, 84 in `assets/`, plus `LICENSE`,
-  `package.json` and this README. (The exact byte count moves whenever this file does;
-  the gate prints it, and `test/packaging.test.mjs` pins the file list.)
-### Measured: what happens when the registry is not reachable
-A cold `npx` start needs the network. Measured with the registry pointed at a closed port
-and at a blackholed address, driving the same handshake:
-| registry | seconds before `npx` gave up | bytes the client saw on stdout |
+| Route | `command` | `args` |
 |---|---|---|
-| connection refused (`http://127.0.0.1:1/`) | **140.3 s** | **0** |
-| packets dropped (`http://192.0.2.1:443/`) | **590.4 s** | **0** |
-**Read that as: the failure is silence.** Nothing appears on the JSON-RPC channel for the
-whole interval, and then the process exits 1. An MCP host does not see "no network"; it
-sees a server that accepted the launch and never answered `initialize`, and it reports its
-own handshake timeout. The npm error text goes to stderr, which most hosts do not surface.
-A warm cache does not have this problem — `npx` runs the cached install without contacting
-the registry — so this bites a new machine, a cleared cache, or a CI runner, which is
-exactly when nobody is watching.
-If offline operation matters, do not use `npx`. Run `npm i -g bantamkit-mcp` once and
-point the config at the installed binary, or keep using `tools/bantamkit-mcp`.
-### Measured: `npx` is not on a login-less PATH
-```sh
-$ env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin sh -c 'command -v npx'
-$ echo $?
-1
-```
-On the machine this was written on, `node`, `npm` and `npx` exist only on the
-mise-injected PATH, and mise is activated from `~/.zshrc` — an **interactive** shell rc.
-`launchctl getenv PATH` is unset, so a GUI-launched application inherits launchd's default
-`/usr/bin:/bin:/usr/sbin:/sbin`, where none of the three is found.
-**What a GUI-launched MCP host actually sees is `ENOENT` on `npx`.** Not a bantamkit
-error, not a bad config — the host reports that it could not spawn the command, which is
-the least informative message in the whole chain. This is the RB-P96 failure class
-relocated: the sh launcher was guaranteed present because it was a file in the repository;
-`npx` is guaranteed present only if the host's *process* environment has it.
-Two ways out, both in `runtime-ts/mcp.json.example`:
+| npm, install once | `/absolute/path/to/node` | `["/Users/you/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]` |
+| Python venv | `/absolute/path/to/env/bin/bantamkit-mcp` | `[]` |
+| npx every launch | `npx` | `["-y", "bantamkit-mcp"]` |
+A JSON file cannot expand `~`, so spell both paths out. To check a recorded command, run it in
+a terminal: with nothing on stdin it prints `usage: bantamkit-mcp …` and exits 0.
+### Connect to Claude Code
+1. **Command:** `npx -y bantamkit-mcp@latest --install claude`
+2. **File:** none edited directly — it runs `claude mcp add bantamkit -s user -- <command> <args>`
+   (user scope, every project). `~/.claude.json` is the host's file, and it holds state that is
+   not MCP configuration.
+3. **Entry:** printed as `ran    : claude mcp add bantamkit -s user -- <node> <cli.js>`.
+4. **Confirm:** `claude mcp list` prints `bantamkit: <node> <cli.js> - ✔ Connected` (Claude Code
+   2.1.272; run it outside a project whose `.mcp.json` also names bantamkit, or it prints
+   `[Conflicting scopes]`). In a session, ask the agent to call `bantamkit_status`.
+5. **Undo / re-run:** `--force` does not reach Claude Code, and a second add fails with
+   `MCP server bantamkit already exists in user config`. Remove first:
+   ```bash
+   claude mcp remove bantamkit -s user
+   npx -y bantamkit-mcp@latest --install claude
+   ```
+### Connect to Claude Desktop
+1. **Command:** `npx -y bantamkit-mcp@latest --install claude-desktop`
+2. **File:** macOS `~/Library/Application Support/Claude/claude_desktop_config.json` ·
+   Windows `%APPDATA%\Claude\claude_desktop_config.json` ·
+   Linux `~/.config/Claude/claude_desktop_config.json`
+3. **Entry** (key `mcpServers`; each entry takes `command`, `args` and an optional `env`):
+   ```json
+   {"mcpServers": {"bantamkit": {"command": "/absolute/path/to/node", "args": ["/Users/you/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]}}}
+   ```
+4. **Confirm:** it prints `installed bantamkit into claude-desktop` with file, key and command.
+   Fully quit and reopen Claude Desktop, then ask it to call `bantamkit_status`.
+5. **Undo / re-run:** there is no uninstall flag — delete the `bantamkit` entry or restore
+   `claude_desktop_config.json.backup-<date>`. A matching re-run prints
+   `bantamkit is already installed in claude-desktop and matches`; a differing entry needs `--force`.
+### Connect to Cursor
+1. **Command:** `npx -y bantamkit-mcp@latest --install cursor`
+2. **File:** `~/.cursor/mcp.json` on every OS (`%USERPROFILE%\.cursor\mcp.json` on Windows);
+   `.cursor/mcp.json` for one project, by hand.
+3. **Entry** (key `mcpServers`):
+   ```json
+   {"mcpServers": {"bantamkit": {"command": "/absolute/path/to/node", "args": ["/Users/you/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]}}}
+   ```
+4. **Confirm:** it prints `installed bantamkit into cursor` and `key    : mcpServers`. Restart
+   Cursor and ask the agent to call `bantamkit_status`.
+5. **Undo / re-run:** delete the entry or restore `mcp.json.backup-<date>`. To replace a
+   differing entry, such as an old `npx` one:
+   ```bash
+   npx -y bantamkit-mcp@latest --install cursor --force
+   ```
+### Connect to VS Code (GitHub Copilot)
+1. **Command:** `npx -y bantamkit-mcp@latest --install copilot`
+2. **File:** macOS `~/Library/Application Support/Code/User/mcp.json` ·
+   Windows `%APPDATA%\Code\User\mcp.json` · Linux `~/.config/Code/User/mcp.json`;
+   `.vscode/mcp.json` for one workspace, or **MCP: Open User Configuration**, by hand.
+3. **Entry** — the key is **`servers`**, not `mcpServers`, plus `"type": "stdio"`. This is the
+   detail that catches people out:
+   ```json
+   {"servers": {"bantamkit": {"type": "stdio", "command": "/absolute/path/to/node", "args": ["/Users/you/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]}}}
+   ```
+   VS Code's own CLI can add an entry too (from VS Code's documentation, not measured here):
+   `code --add-mcp '{"name":"bantamkit","command":"npx","args":["-y","bantamkit-mcp"]}'`.
+4. **Confirm:** it prints `installed bantamkit into copilot` and `key    : servers`. Restart
+   VS Code and ask Copilot to call `bantamkit_status`.
+5. **Undo / re-run:** delete the entry or restore `mcp.json.backup-<date>`; `--force` replaces
+   a differing entry.
+### Connect other MCP clients
+Anything that speaks MCP over stdio runs the same `command`/`args` and talks JSON-RPC on stdin
+and stdout; nothing in this package is host-specific. Codex and a generic JSON config:
+[docs/mcp.md → Client setup](https://github.com/Ink01101011/bantamkit/blob/main/docs/mcp.md#client-setup).
+**A GUI-launched host does not read your shell rc.** If `node` and `npx` come from mise, nvm or
+similar, they are not on its PATH (`/usr/bin:/bin:/usr/sbin:/sbin` on macOS). An `npx` entry then
+fails with `ENOENT`, and a `.bin/bantamkit-mcp` shim exits 127 with
+`env: node: No such file or directory`, because its first line is `#!/usr/bin/env node`. Name
+node by absolute path, as `--install` does.
-```jsonc
-// absolute path to the npx you actually have
-{ "command": "/Users/you/.local/share/mise/installs/node/latest/bin/npx",
-  "args": ["-y", "bantamkit-mcp@0.25.0"] }
-```
+## Updating
-```jsonc
-// or install once and skip npx entirely:  npm i -g bantamkit-mcp
-{ "command": "/usr/local/bin/bantamkit-mcp", "args": [] }
+```bash
+npx -y bantamkit-mcp@latest --update
 ```
-## What `npx` gives up versus `tools/bantamkit-mcp`
-The sh launcher is not obsolete. It guarantees things `npx` cannot, and this table is the
-prep probe's, unsoftened.
-| guarantee | `tools/bantamkit-mcp` | `npx bantamkit-mcp` |
-|---|---|---|
-| present in every checkout **and** every worktree | yes — it is a file in the tree | **gone.** Depends on the host's PATH, not on the project directory |
-| runs *this* checkout's code | yes | **gone for developers too.** Testing a worktree needs an absolute `node <worktree>/dist/cli.js`, or the host silently runs the published build |
-| code from the worktree, deps from the main checkout | yes (`PYTHONPATH` + `PYTHONSAFEPATH`) | **no Node analogue.** `NODE_PATH` is ignored by ESM and there is no `-P`. `npm link` and workspaces are a different failure surface, not the same one solved |
-| stdin is the JSON-RPC channel | yes | yes, with `-y` |
-| names the cause when dependencies are missing | yes | the analogous failure is *no network*, and it has no message at all — see the table above |
-| starts without a network | yes | **no**, on a cold cache |
-| `--which`, for diagnosing which endpoint answered | the flag exists | **not in the npx CLI** — but `tools/bantamkit-mcp-node --which` has it, see below |
-| one config line, no clone, no venv | no | **yes.** This is the whole reason the package exists |
-### `--which` is a launcher flag, not a package flag
-This section previously read "`--which` is deleted, not ported" and said "there is no
-Node `--which`, and none is planned". Both are now false, and the second was made false
-inside this repository: `tools/bantamkit-mcp-node` ships `--which`, and
-`runtime-ts/test/launcher.test.mjs` runs it — including on a checkout that has never been
-built, which is the case the Python flag's `find_spec` was chosen for. It prints
-`checkout=`, `deps_root=`, `runtime=node`, `node=`, `entry=` (suffixed `(missing)` when
-`dist/` is absent) and `sdk=`.
-What is genuinely not ported is `--which` **on the published package**, and the reason is
-the line above it in the table: `npx bantamkit-mcp` does not run a checkout, so
-`checkout=` and `source=` have nothing to report. The question a reader has about an npx
-endpoint is not *where did this resolve* but *which build answered*, and that is
-`build_identity` — a tool on the wire rather than a flag on a launcher, and what the next
-section is about.
-The old wording came from a real defect, which is now closed. `tools/bantamkit-mcp:47`
-used to name `tools/mcpreach/mcpreach.py` as `--which`'s consumer and `docs/mcp.md` used
-to document a five-value exit-code interface for that program (`0` REACHABLE, `1`
-UNREACHABLE, `2` FOREIGN, `3` UNDECLARED, `4` NO_ENV). **That program has never existed** —
-`git log --all --diff-filter=A -- '*mcpreach*'` is empty across every ref in this
-repository, and `docs/eval.md` records the decision not to ship it, the half-built checker
-having "never been seen to fire". Both citations were rewritten on 2026-08-24 to name what
-actually runs, and `runtime-py/tests/test_doc_commands_gate.py` is now red if any fenced
-shell block in the repository names a `tools/` program that is not in the tree.
-## Silent version float, and the instrument for it
-This is the one that will bite a team hardest.
-`npx -y bantamkit-mcp` resolves the dist-tag `latest` and caches the result. Two people
-with byte-identical `.mcp.json` files can be running different builds — one resolved last
-week, one resolved this morning — and nothing in the config, the logs or the tool output
-says so. The sh launcher could not do this: it ran the checkout you were standing in.
-Call `build_identity`. Three fields answer it:
+`--update` — `check the package index and update this install if it differs, then exit` — asks
+the npm registry for `latest` and compares it with the installed version:
-- **`runtime`** — `"node"` here, absent on the Python server. Its *presence* is the
-  discriminator, and it is folded into `build_id` so the two lineages cannot collide even
-  if their code digests agreed.
-- **`assets_digest`** — sha256 over every byte of the asset pack, computed identically in
-  both runtimes and **verified equal**: `sha256:b03141bf…` over 83 files from Python and
-  from Node. This is the cross-runtime instrument; two machines disagreeing here are
-  serving different data.
-- **`code_digest`** / **`build_id`** — over `dist/**/*.js` on this side and `*.py` on the
-  other, so they are *required* to differ across runtimes and required to match across two
-  installs of the same version. `build_id` differing between two teammates on the same
-  version string is the float, caught.
-The output carries a `cross_runtime` sentence saying in plain words which fields are
-comparable. `git_commit` is refused rather than guessed: an installed npm tarball carries
-no repository, and reading a checkout's HEAD would describe the tree rather than the bytes
-that were imported (RB-P84).
-**Pin the version in the config** if you want this to be a non-issue:
-`"args": ["-y", "bantamkit-mcp@0.30.0"]`.
+- **Same version:** prints both numbers and `up to date.`
+- **Behind, on a registry install or a kept install from `--install` (0.34.0+):** runs the
+  matching row below and prints npm's output.
+- **Behind, on any other shape** (a checkout, a linked tree, a local file, an npx cache with no
+  kept install): refuses with exit 1 and names your row. It will not write a registry install
+  into a tree you manage with `git`.
-## Updating
+It is the only network access here — not at startup, not on `bantamkit_status`, not on any tool
+— with a 10-second timeout, and being offline is a named refusal on stderr, never a traceback.
-**There is no `bantamkit-mcp --update`, deliberately.** The package manager that installed
-this is the thing that updates it, and there are five install shapes with five different
-answers. Pick the row you are actually on — and note that **the running server keeps
-serving the code it loaded at startup**, so every row ends with restarting it in the host.
-> **AMENDED 2026-09-11 — there IS a `bantamkit-mcp --update` now, and the paragraph above is
-> kept rather than rewritten because everything in it is still true of what the flag does.**
-> `bantamkit-mcp --update` asks the npm registry for `latest` and compares it to the version
-> that is installed. If they match it prints both numbers and `up to date.` and stops. If the
-> index is ahead **and this is a registry install**, it runs the row below that applies to you
-> and prints what npm said. If the index is ahead and this is any OTHER shape, **it refuses,
-> exits 1, and names the row you are on** — it will not write a registry install into a tree
-> you manage with `git`, and a command that exits 0 having changed nothing is worse than one
-> that says no. Either way it ends by telling you to restart the server, for the reason the
-> paragraph above gives: a successful update does not change the process that is answering
-> you. The flag reaches the network and nothing else here does — not at startup, not on
-> `bantamkit_status`, not on any tool — with a 10-second timeout, and being offline is a named
-> refusal on stderr, never a traceback. The table below is still the reference for what to do
-> by hand, and it is what `--update` prints back at you when it will not act.
-| how it was installed | how to update |
+| How it was installed | How to update |
 |---|---|
-| `npx -y bantamkit-mcp` in the host config | nothing to update — but npx **caches the resolved version**, so add `@latest` (or a pinned `@0.30.0`) or it will keep serving what it resolved weeks ago. `rm -rf ~/.npm/_npx` forces a clean resolve. |
+| `npx -y bantamkit-mcp` in the host config | Nothing to update, but npx **caches the resolved version**: add `@latest` (or pin `@0.34.0`). `rm -rf ~/.npm/_npx` forces a clean resolve |
+| `npx -y bantamkit-mcp --install <host>` from 0.34.0: a kept install at `~/.bantamkit/mcp` | `npx -y bantamkit-mcp@latest --update` patches it in place, or `npm i --prefix ~/.bantamkit/mcp bantamkit-mcp@latest`. The recorded paths do not change. Before 0.34.0, `--update` from an npx cache refuses instead |
 | `npm i -g bantamkit-mcp` | `npm i -g bantamkit-mcp@latest` |
 | `npm i --prefix <dir> bantamkit-mcp` | `npm i --prefix <dir> bantamkit-mcp@latest` |
 | PyPI (`pip install "bantamkit[mcp]"`) | `pip install -U "bantamkit[mcp]"` · pipx: `pipx upgrade bantamkit` · uv: `uv tool upgrade bantamkit` |
-| a checkout, via `tools/bantamkit-mcp-node` | `git pull && npm ci --prefix runtime-ts && npm run build --prefix runtime-ts` — this one never touches a registry, and `runtime-ts/dist/` is build output, so a pull alone changes nothing |
+| a checkout, via `tools/bantamkit-mcp-node` | `git pull && npm ci --prefix runtime-ts && npm run build --prefix runtime-ts` — no registry, and `runtime-ts/dist/` is build output, so a pull alone changes nothing |
-**Then restart the server in your host**, or you will keep talking to the old build. In
-Claude Code that is `/mcp` → reconnect; in Claude Desktop it is a full restart of the app.
-Measured 2026-09-07 (served-tools: dated — the surface was eleven then; 0.30.0's
-`memory_dream` and `repo_map` made it thirteen): a checkout whose `dist/` had just been
-rebuilt at 0.30.0 kept answering `version 0.29.1, serving 11 tools` until the host
-reconnected — the disk was current and the process was not.
+**Then restart the server in your host** — a running server keeps serving the code it loaded at
+startup. In Claude Code: `/mcp` → reconnect. In Claude Desktop: a full restart of the app.
-**Verify with `bantamkit_status`, not with the install log.** It reports the version and
-the `build_id` of *the code that is answering you*:
+**Verify with `bantamkit_status`, not the install log.** It reports the version and the
+`build_id` of *the code that is answering you*:
 ```
 bantamkit Active 🟢
@@ -326,171 +241,138 @@ version 0.30.0, build sha256:4441619d…
 serving 12 tools, 1 prompt, 2 resource templates
 ```
-A version string that moved and a `build_id` that did not means you are reading a config,
-not a process.
-### The failure this table exists for
-Measured on a real machine, 2026-09-07: a Claude Desktop entry pointed at
-`~/.local/share/bantamkit-mcp/node_modules/.bin/bantamkit-mcp`, which was **0.25.0** — five
-releases stale — and its `package.json` declared
-```json
-"bantamkit-mcp": "file:/private/tmp/.../scratchpad/bantamkit-mcp-0.25.0.tgz"
-```
+A version that moved and a `build_id` that did not means you are reading a config, not a process.
-a **local tarball in a temp directory that no longer existed**. `npm update` in that
-directory cannot help: the dependency does not name a registry. The fix is to install over
-it from the registry (`npm i --prefix ~/.local/share/bantamkit-mcp bantamkit-mcp@latest`),
-which restores a normal semver dependency and leaves the host config's path valid.
+**Tested a build from a local `.tgz`? Install over it from the registry afterwards**
+(`npm i --prefix <dir> bantamkit-mcp@latest`). Otherwise that machine stays pinned to a `file:`
+dependency in a temp directory that will be deleted, and `npm update` cannot help.
-If you install from a local `.tgz` to test a build, **install over it from the registry
-afterwards**, or that machine is pinned to a file that will be deleted.
+## Troubleshooting
-## The second bin: `bantamkit-memory`
+| Symptom | Fix |
+|---|---|
+| Connection closed at startup (`CONNECTION_CLOSED`) | Builds before 0.32.1 crashed when a GUI host started them with cwd `/`. Update, then restart the server |
+| The host times out; the server never answers | The entry uses `npx` with a registry spec and the network is down. Use [Install once, run offline](#install-once-run-offline) |
+| `ENOENT` from the host, or `env: node: No such file or directory` | A GUI host does not have your shell's PATH. `--install` records node by absolute path; see [Connect other MCP clients](#connect-other-mcp-clients) |
+| `npm error code ENOTCACHED` | `npx --offline` on a cache that has never seen that spec. Run it once online, or use the kept install |
+| `already has a bantamkit entry with different settings … re-run with --force to replace it` | Re-run with `--force`; the old file is kept as `.backup-<date>` |
+| `MCP server bantamkit already exists in user config` | `claude mcp remove bantamkit -s user`, then install again |
+| The server stopped launching after a node change | `npx -y bantamkit-mcp@latest --install <host> --force` with the node you have now |
+| Two machines with one config run different builds | [Silent version float](#silent-version-float): compare `build_id` |
+| `bantamkit_status` still shows the old version after an update | The host has not reconnected; restart the server |
+| Recall finds nothing, or the wrong store | Set `BANTAMKIT_MEMORY_DIR`; the reply names the store it searched |
+| `malformed fact file …` | A hand-edited fact has a bare non-string field; see [Sharing a store](#sharing-a-store-with-the-python-server) |
+| `AssetNotFound: no assets directory found; set BANTAMKIT_ASSETS` | See [The asset pack](#the-asset-pack) |
+## Configuration
+Flags go in the entry's `args`; environment variables in its `env` block (or
+`claude mcp add -e NAME=value`). Both runtimes print the same `--help`.
+| Setting | What it does | Default | Example |
+|---|---|---|---|
+| `BANTAMKIT_MEMORY_DIR` | Pins the store to one absolute path; a missing or relative path refuses at startup | unset: nearest existing `.bantamkit/memory` at or above the start directory | `"env": {"BANTAMKIT_MEMORY_DIR": "/abs/project/.bantamkit/memory"}` |
+| `--store STORE` | One store, layering off; outranks `BANTAMKIT_MEMORY_DIR` | off (layered) | `"--store", "/abs/store"` |
+| `--start START` | Where store discovery starts; not with `--store` | cwd | `"--start", "/abs/project"` |
+| Layered memory | Recall reads the project store, stores granted in `.bantamkit/config.yaml`, and `~/.bantamkit/memory`; saves go to the project store | on | [Memory stores are layered by default](#memory-stores-are-layered-by-default) |
+| `--k K` | Default recall budget | `3` | `"--k", "5"` |
+| `--index-budget BYTES` | Memory index byte budget | `24000` | `"--index-budget", "32000"` |
+| `BANTAMKIT_EVENT_LOG` | Logs tool outcomes as JSONL | off; `on` → `<store>/events/mcp.jsonl`; other values are a path | `"env": {"BANTAMKIT_EVENT_LOG": "on"}` |
+| `BANTAMKIT_ASSETS` | Your own asset pack (skills, rubrics, schemas) | the pack inside the package | `"env": {"BANTAMKIT_ASSETS": "/abs/my-assets"}` |
+| `BANTAMKIT_HOST_LOG_ROOT` | Where `--mcp-report` finds the host's MCP logs | macOS `~/Library/Caches/claude-cli-nodejs`; elsewhere unset | `BANTAMKIT_HOST_LOG_ROOT=/abs/logs bantamkit-mcp --mcp-report` |
+| `BANTAMKIT_PRICES` | Price table for the token ledger | `pricing/default.json` in the asset pack | `"env": {"BANTAMKIT_PRICES": "/abs/prices.json"}` |
+One-shot commands that print and exit: `--install {claude,claude-desktop,copilot,cursor}` (with
+`--force`), `--update`, `--assets-root`, `--mcp-report`, `--statusline`, `-h`. Typing
+`bantamkit-mcp` at a terminal with nothing after it prints the help and exits 0; a host launch
+down a pipe still starts the server, and `bantamkit-mcp --store /tmp/x` at a terminal still
+serves. `--which` belongs to the checkout launchers `tools/bantamkit-mcp` and
+`tools/bantamkit-mcp-node`, not to this package: an npx install runs no checkout, so ask
+`build_identity` which build answered instead.
+## Silent version float
+`npx -y bantamkit-mcp` resolves the dist-tag `latest` and caches the result. Two people with
+byte-identical `.mcp.json` files can be running different builds — one resolved last week, one
+this morning — and nothing in the config, the logs or the tool output says so. This is the one
+that will bite a team hardest.
+**Fix:** pin the version in the config (`"args": ["-y", "bantamkit-mcp@0.34.0"]`), or use the
+kept install from `--install`, which serves the version in `~/.bantamkit/mcp` until someone runs
+`--update`.
+**Detect it:** call the `build_identity` tool. Three fields answer it:
-`package.json` declares **two** bins, so an install puts two commands on the path. Packed
-and installed into an empty scratch directory, that is what arrives:
+- **`runtime`** — `"node"` here, absent on the Python server. Its *presence* is the
+  discriminator, and it is folded into `build_id` so the two lineages cannot collide.
+- **`assets_digest`** — sha256 over every byte of the asset pack, computed identically in both
+  runtimes and verified equal (`sha256:eb79f9e3…` over 91 files from Python and from Node,
+  `node tools/conformance/run.mjs --all`, 2026-09-15). Two
+  machines disagreeing here are serving different data.
+- **`code_digest`** / **`build_id`** — over `dist/**/*.js` here and `*.py` on the Python side, so
+  they must differ across runtimes and must match across two installs of one version. `build_id`
+  differing between two teammates on the same version string is the float, caught.
+The output carries a `cross_runtime` sentence naming which fields are comparable. `git_commit` is
+refused rather than guessed: an npm tarball carries no repository, and a checkout's HEAD would
+describe the tree, not the bytes that were imported (RB-P84).
+## The operator CLI: `bantamkit-memory`
+The package installs **two** commands: `bantamkit-mcp`, the server, whose stdout is the JSON-RPC
+wire, and `bantamkit-memory`, the operator CLI for memory-store lifecycle, which prints reports.
+It is a second bin rather than a subcommand because report output on the server's stdout would
+corrupt the transport, and `bantamkit-mcp`'s help is byte-compared with
+`python -m bantamkit.mcpserver -h`.
-```console
-$ npm install ./bantamkit-mcp-0.25.0.tgz
-added 95 packages in 5s
-$ ls -l node_modules/.bin/
-bantamkit-mcp    -> ../bantamkit-mcp/dist/cli.js
-bantamkit-memory -> ../bantamkit-mcp/dist/memory/cli.js
+```bash
+npx -y -p bantamkit-mcp bantamkit-memory status   # without installing; -p is required
 ```
-`bantamkit-mcp` is the server the `.mcp.json` line at the top launches, and its stdout is
-the JSON-RPC wire — not a thing you run by hand. `bantamkit-memory` is the operator CLI
-for memory-store lifecycle, and it prints reports. That is the whole reason it is a
-second bin instead of a subcommand: lifecycle output on the server's stdout would corrupt
-the transport, and `bantamkit-mcp`'s help is a byte-compared artifact against
-`python -m bantamkit.mcpserver -h`, which a subparsers action would move.
-**Amendment, 2026-09-11 (J46-26/J46-27).** "Not a thing you run by hand" is now half
-true and the half that changed is worth knowing. Typing `bantamkit-mcp` at a prompt
-with nothing after it no longer opens a mute server and blocks — it prints the help,
-on stdout, exit 0, the same bytes `-h` prints. The discrimination is whether **stdin is
-a terminal** and nothing else, so every host launch is unchanged: `"args": []` down a
-pipe still starts the server and still answers `initialize`. The paragraph above stays
-true of what it was describing — stdout is the wire, and nothing but frames goes down
-it when a host is on the other end. What is new is that typing the command to see what
-it does is now a reasonable thing to do. An argument after the command is an operator
-asking for a configured server and still gets one: `bantamkit-mcp --store /tmp/x` at a
-terminal serves. Compared between the two runtimes by
-`tools/conformance/suites/cli.mjs` (`bare-at-a-tty`, `flagged-at-a-tty`,
-`bare-over-a-pipe`).
-Five subcommands, scoped to the writable **project** layer only — read-only grants and the
-profile store are out of its reach by the code path, not by convention:
-| subcommand | what it does |
+The package name and the bin name differ, so plain `npx bantamkit-memory` would look for a
+package called `bantamkit-memory`.
+| Subcommand | What it does |
 |---|---|
 | `status` | index size, budget, headroom, archive count |
 | `lint` | exit 1 if the store is malformed or over budget |
 | `compact` | archive the stalest facts until the index fits |
 | `archived` | list what compaction has moved out |
+| `archive NAME` | move one named fact out |
 | `restore NAME` | move an archived fact back |
-Each takes `--store PATH` or `--start DIR`; with neither, it resolves the project store
-the way `Memory.layered()` does. Exit codes are `0` success, `1` a failure the operator
-must act on (over budget, a malformed fact, a refused restore), `2` a usage error — so
-`lint` drops into a pre-commit hook or a CI job unchanged.
-Driven off `node_modules/.bin/` from the install above, against a scratch five-fact store:
-```console
-$ bantamkit-memory status --store store
-store: store
-facts: 5
-index: 576 bytes
-budget: 24000
-headroom: 23424
-archived: 0
-$ bantamkit-memory lint --store store --budget 400
-lint: FAIL — index is 576 bytes, budget is 400
-  try: bantamkit-memory compact --store store --budget 400
-$ echo $?
-1
-$ bantamkit-memory compact --store store --budget 400
-compacted 3 fact(s)
-index: 576 -> 236 bytes (budget 400, target 267, reserve 133, headroom 164)
-archived -> store/archive
-  assets-pack-has-eighty-four-files (project, 133 bytes)
-  ci-runner-is-macos-only (project, 97 bytes)
-  conformance-runner-entrypoint (reference, 110 bytes)
-restore one with: bantamkit-memory restore <name> --store store
-$ bantamkit-memory archived --store store
-archived facts: 3 (store/archive)
-  assets-pack-has-eighty-four-files
-  ci-runner-is-macos-only
-  conformance-runner-entrypoint
-$ bantamkit-memory restore ci-runner-is-macos-only --store store
-restored 'ci-runner-is-macos-only' — index now 333/24000 bytes
-```
-`compact` printing every name that left is the point: `archive/` is a directory nothing
-reads back on its own, so a compaction whose output is not shown is a silent deletion as
-far as the operator is concerned.
-Without installing, `npx -p bantamkit-mcp bantamkit-memory status` runs it out of the
-registry. `-p` is not optional — the package name and this bin's name differ, and plain
-`npx bantamkit-memory` would go looking for a package called `bantamkit-memory`. Measured
-here against the local tarball rather than the registry, since this version is not
-published:
-```console
-$ npx -y -p ./bantamkit-mcp-0.25.0.tgz bantamkit-memory status --store npxstore
-store: npxstore
-facts: 0
-index: 0 bytes
-budget: 24000
-headroom: 24000
-archived: 0
-```
-**The Python install does not provide this command**, which is why the two spellings
-exist. Measured against the distribution in this repository's venv:
+Each takes `--store STORE` or `--start START`; with neither, it resolves the project store the way
+`Memory.layered()` does. It reaches the writable **project** layer only — read-only grants and the
+profile store are out of reach by the code path, not by convention. Exit codes: `0` success, `1`
+a failure to act on (over budget, a malformed fact, a refused restore), `2` a usage error, so
+`lint` drops into a pre-commit hook or CI job unchanged. `compact` prints every name it moved,
+because `archive/` is a directory nothing reads back on its own.
-```console
-$ .venv/bin/python -c "from importlib.metadata import distribution; d=distribution('bantamkit'); print(sorted(e.name for e in d.entry_points if e.group=='console_scripts'))"
-['bantamkit-mcp']
-$ env PATH="$PWD/.venv/bin:/usr/bin:/bin" sh -c 'command -v bantamkit-memory'
-$ echo $?
-1
-```
-One console script, and it is the server. The Python operator therefore types
-`python -m bantamkit.memory`, and the two CLIs are identical bytes after substituting one
-for the other — except the wrap, because argparse's hanging indent is
-`len(prefix) + len(prog) + 1`. The reason there is no third spelling both installs could
-use lives in one place, the `prog` row of `docs/porting.md`'s divergence table, and this
-page does not restate it. `docs/memory.md`'s *The operator CLI* is the full reference;
-`tools/conformance/suites/memorycli.mjs` is the gate that compares the two.
+The Python install has no such console script: there the same CLI is
+`python -m bantamkit.memory`, identical bytes apart from the program name and its wrap. Full
+reference: [docs/memory.md → The operator CLI](https://github.com/Ink01101011/bantamkit/blob/main/docs/memory.md#the-operator-cli).
-## The default is layered — do not add `--store` by reflex
+## Memory stores are layered by default
-With **no arguments**, which is what the config above passes and what production runs, the
-server binds `Memory.layered`: the project store discovered from the working directory,
-plus the profile layer, plus any `extra_stores` from `.bantamkit/config.yaml`. Recall lines
-are prefixed with their layer — `[project] `, `[extra:<name>]`, `[profile]`.
+With **no arguments** — what every config above passes, and what production runs — the server
+binds `Memory.layered`: the project store discovered from the working directory, plus the profile
+layer, plus any `extra_stores` from `.bantamkit/config.yaml`. Recall lines are prefixed with their
+layer: `[project] `, `[extra:<name>]`, `[profile]`.
-`--store <path>` binds one store and drops the tag. It is a debugging flag. A recall string
-produced under `--store` is not a string the deployment ever emits, and the cold-start gate
-asserts the layered form specifically for that reason.
+`--store <path>` binds one store and drops the tag. It is a debugging flag: a recall string
+produced under `--store` is not one the deployment ever emits, and the cold-start gate asserts the
+layered form for that reason.
 ## The asset pack
-The pack is language-agnostic data (tool manifests, schemas, skills, rubrics, contract
-wording, eval fixtures) that lives at the **repository root**, one level above this
-package, and is shared verbatim with `runtime-py`. npm cannot reach outside a package
-directory, so `scripts/sync-assets.mjs` vendors it into `runtime-ts/assets/` on `prepack`;
-that directory is generated and git-ignored.
+The pack is language-agnostic data — tool manifests, schemas, skills, rubrics, contract wording,
+eval fixtures — that lives at the **repository root** and is shared verbatim with `runtime-py`.
+npm cannot reach outside a package directory, so `scripts/sync-assets.mjs` vendors it into
+`runtime-ts/assets/` on `prepack`; that directory is generated and git-ignored.
-`build_identity` hashes **every byte of the whole tree**, not just the 20 files the tools
-read, so the pack ships whole — 83 files / 212,480 bytes — or `assets_digest` and
-`build_id` change. `test/packaging.test.mjs` asserts that against what `npm pack` would
-actually put in the tarball, never against the source tree.
+`build_identity` hashes **every byte of the whole tree**, not just the 20 files the tools read, so
+the pack ships whole — 91 files / 238,751 bytes on 2026-09-15 — or `assets_digest` and `build_id` change.
+`test/packaging.test.mjs` asserts that against what `npm pack` would put in the tarball.
 `assetsRoot()` mirrors `runtime-py/src/bantamkit/assets.py` arm for arm:
@@ -501,23 +383,19 @@ actually put in the tarball, never against the source tree.
 ## Sharing a store with the Python server
-Both servers read and write the same memory store, and byte-compatibility is the product,
-not a nice-to-have. Two things to know:
+Both servers read and write the same memory store; byte-compatibility is the product.
 - **Concurrent writes are safe for the memory store and lossy for the checkpoint, in both
-  runtimes.** `index.md` is derived from the `facts/` directory, so the last writer
-  re-enumerates everything and the index self-heals — measured over 8 trials of two
-  processes × 15 saves, zero disagreements between `facts/` and `index.md`. A checkpoint is
-  not derived that way: `shiftwork_clock_out` is read-modify-write and the write depends on
-  the document it read, so two concurrent clock-outs on the *same cursor unit* both answer
-  `ok` and one history entry is lost. Measured 10/10 trials on Node **and** 10/10 on the
-  Python reference — reference behaviour reproduced, not something the port introduced. The
-  cursor check serialises the normal case; only the same-unit collision loses.
+  runtimes.** `index.md` is derived from `facts/`, so the last writer re-enumerates everything
+  and the index self-heals: 8 trials of two processes × 15 saves, zero disagreements. A
+  checkpoint is not: `shiftwork_clock_out` is read-modify-write, so two concurrent clock-outs on
+  the *same cursor unit* both answer `ok` and one history entry is lost — 10/10 trials on Node
+  **and** 10/10 on the Python reference. The cursor check serialises the normal case; only the
+  same-unit collision loses.
 - **Do not hand-edit a fact file's `name`, `description` or `type` to a bare non-string.**
-  `description: 2026` is a YAML integer, not the text `2026`. Python interpolates it and
-  carries on; this port refuses the whole store with `malformed fact file …`. Quote it:
-  `description: '2026'`. Every fact the tools *write* is quoted correctly, so this only
-  reaches you through an editor. See `src/memory/factfile.ts:257`.
+  `description: 2026` is a YAML integer. Python interpolates it and carries on; this port refuses
+  the whole store with `malformed fact file …`. Quote it: `description: '2026'`. Every fact the
+  tools *write* is quoted correctly (`src/memory/factfile.ts:257`).
 ## Development
@@ -531,13 +409,23 @@ npm pack --dry-run # vendors the pack via prepack, lists the tarball
 From the repository root:
 ```sh
-node tools/conformance/run.mjs --all                   # Node vs Python, 4300+ cases
+node tools/conformance/run.mjs --all                   # Node vs Python, 8,130 cases on 2026-09-15
 node tools/conformance/npx-cold-start.mjs              # pack, cold npx, warm npx, PATH
-node tools/conformance/npx-cold-start.mjs --offline    # + the no-registry probe (~2.5 min)
+node tools/conformance/npx-cold-start.mjs --offline    # + the no-network arms (299.94 s on 2026-09-15)
 ```
-The conformance harness shells out to a CPython to produce the reference side. That is a
+The conformance harness shells out to a CPython for the reference side. That is a
 **development-time** dependency of the test tooling; nothing under `tools/` ships, and
-`files: ["dist", "assets"]` is the whole published surface.
-Runtime dependencies: exactly one, `@modelcontextprotocol/sdk`, pinned to `1.30.0`.
+`files: ["dist", "assets"]` is the whole published surface. Runtime dependencies: exactly one,
+`@modelcontextprotocol/sdk`, pinned to `1.30.0`.
+## Measurements and history
+Every number on this page was measured on the machine that wrote it, with a command you can
+rerun. The measurements, dated amendments and transcripts that used to fill this page are in
+[docs/install.md → npm package: measured detail](https://github.com/Ink01101011/bantamkit/blob/main/docs/install.md#npm-package-measured-detail):
+cold-start cost and package size, the registry-unreachable and offline tables, what `--install`
+recorded before and after 0.34.0, `--update` transcripts, the login-less PATH probe, what `npx`
+gives up versus the `tools/bantamkit-mcp` launcher, and the `bantamkit-memory` session
+transcripts. Where the two runtimes deliberately differ:
+[docs/porting.md](https://github.com/Ink01101011/bantamkit/blob/main/docs/porting.md#where-the-two-runtimes-deliberately-differ).