minnimemory 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -1,13 +1,23 @@
 # MinniMemoryMCP
 
 **Curated memory for AI agents, served over MCP.** Your AI coding agent re-reads its entire
-project memory file on every turn. MinniMemoryMCP is an MCP server whose tools audit that file,
-compile it into a small AlwaysOnMemory body plus OnDemandMemory files loaded only when
-relevant, and serve it back on demand. The `minnimemory` command line underneath is the build layer those tools call;
-it is documented further down for maintainers.
+project memory file on every turn. MinniMemoryMCP audits that file, compiles it into a small
+AlwaysOnMemory body plus OnDemandMemory files loaded only when relevant, and can undo the
+whole thing in one step. Four verbs, the same in Claude Code and in the terminal: `doctor`,
+`init`, `apply`, `undo`. No model, no key, no network; the MCP server never writes your disk.
 
 Built by MinniAI.
 
+**Quick start**
+
+```bash
+npx -y minnimemory install        # registers the MCP server for Claude Code, once per machine
+```
+
+Restart Claude Code, open your project, and say "run doctor on my memory file", then "apply
+it". Or from a terminal in the project: `npx -y minnimemory doctor`, then `npx -y minnimemory
+apply`. Full steps under [Install](#install) and [Use it](#use-it).
+
 ```
 BEFORE                                  AFTER
 CLAUDE.md     689 tokens                CLAUDE.md      282 tokens   <- every turn
@@ -17,28 +27,22 @@ CLAUDE.md     689 tokens                CLAUDE.md      282 tokens   <- every tur
 
 Those are real numbers from `examples/CLAUDE.md` in this package, default settings, offline
 tokenizer (`approx-v2`, calibrated against a real BPE encoder, see
-[Measurement policy](#measurement-policy)). Rerun them yourself (after the build in
-[Install](#install)): `npx minnimemory init node_modules/minnimemory/examples/CLAUDE.md`.
+[Measurement policy](#measurement-policy)). See them for your own file with
+`npx -y minnimemory init` in your project; it prints the plan and writes nothing.
 
 The classifier was validated on 23 real `CLAUDE.md` and `AGENTS.md` files from public
 repositories on 2026-09-02: every one compiled losslessly, and every one landed inside the
 2,000-token always-loaded budget afterwards.
 
-Deterministic, lossless, offline. No LLM, no API key, no network. `doctor`, `init`, and `bench`
-have no runtime dependencies; only `mcp` pulls in the MCP SDK.
-
-> **Status: 1.0.0-beta.1, prepared for a public beta; not yet on npm (2026-09-16).** `doctor`, `init`, and `bench` are implemented and tested from the
-> CLI. `mcp` is the product and still early: it works, is tested in-process, and `recall` (only, not the other tools)
-> has been exercised in a second host (Claude Code loading it as an external MCP server). The
-> default client surface is `--profile basic`: `check` before the workspace is compiled and
-> `recall` after, chosen from the workspace at launch; `optimize` and `sync` (same split) are
-> opt-in behind `--allow-write`, back up before every write, and have not yet been exercised
-> outside this project's own test corpus. The original nine tools stay
-> available, unchanged, under `--profile full` for maintainers and for an agent driving a folder
-> reorganization directly. `bench` reports exact session bounds and, given a workload, an
-> explicitly-labelled model of a session; it does not measure a live agent by itself, though a
-> separate internal harness has now measured the memory layer live on two real project files (see
-> [Measurement policy](#measurement-policy)). See [Roadmap](#roadmap).
+Deterministic, lossless, offline. No LLM, no API key, no network. The four verbs have no
+runtime dependencies; only `mcp` pulls in the MCP SDK.
+
+> **Status: public beta.** `1.0.0-beta.1` has been on npm since 2026-09-17; `1.0.0-beta.2`
+> (this README) is on `main` and publishes next. The four verbs are tested from the CLI and
+> over MCP in Claude Code; other hosts are supported by the standard config below but have not
+> been exercised by us yet. Maintainers get nine more tools, `recall` included, under
+> `--profile full` ([Profiles](#profiles)); `recall` joins the public surface once the
+> converter has proven itself ([Roadmap](#roadmap)).
 
 ---
 
@@ -95,14 +99,20 @@ three copies of the test command, and a changelog nobody reads.
 
 ## What it does
 
-Two commands do the work, plus an optional read-only MCP server for hosts that need one.
+Four commands do the work, the same four in the terminal and over MCP.
 
 **`doctor`** audits your current setup and tells you what it is costing. It changes nothing, needs
 no install, and takes about a second.
 
-**`init`** compiles your memory file into a small AlwaysOnMemory body plus OnDemandMemory files
+**`init`** shows what a compile would do: which sections stay always-on, which become
+OnDemandMemory files, and the prefix before and after. It never writes.
+
+**`apply`** compiles your memory file into a small AlwaysOnMemory body plus OnDemandMemory files
 the agent loads only when they are relevant, and rewrites your memory file as a compact stub.
-Your original is backed up first, and every line of it survives into the output.
+Your original is backed up first, and every line of it survives into the output. Run it again
+after a hand edit and it re-applies, keeping the edit.
+
+**`undo`** puts your original memory file back and removes `.minnimemory/`.
 
 Splitting is by **how often content is needed** and **how often it changes**:
 
@@ -113,27 +123,28 @@ Splitting is by **how often content is needed** and **how often it changes**:
 
 ## Install
 
-Requires Node 18 or later. The package is `minnimemory` on npm; nothing else to download.
-
-**Claude Code**, from inside the repo whose memory you want served (read-only: `check` until
-the memory is compiled, `recall` once it is):
+One line. Requires Node 18 or later and the `claude` CLI on `PATH`. Nothing is downloaded
+except the npm package, and the server never writes your disk.
 
 ```bash
-claude mcp add minnimemory -- npx -y minnimemory mcp
+npx -y minnimemory install
 ```
 
-Add `--allow-write` to let the agent also compile and maintain the file (`optimize` before the
-compile, `sync` after; every write is backed up first), and `--include-auto-memory` to include Claude Code's own
-auto-memory folder for this project:
+That registers the MCP server for every project on this machine (it runs
+`claude mcp add minnimemory -s user -- npx -y minnimemory mcp` and prints exactly that line).
+Restart Claude Code. Done. Running it again is safe: it tells you it is already registered.
 
-```bash
-claude mcp add minnimemory -- npx -y minnimemory mcp --allow-write --include-auto-memory
-```
+Useful variants:
 
-Use `-s user` to register it once for every project instead of the current one. Restart Claude
-Code, then ask it to run `check`.
+| you want | run |
+|---|---|
+| this repo only, not every project | `npx -y minnimemory install --scope project` |
+| see the command without running it | `npx -y minnimemory install --dry-run` |
+| re-register over an existing entry | `npx -y minnimemory install --force` |
+| the config snippet for Cursor, Windsurf or another host | `npx -y minnimemory install --host cursor` (or `windsurf`, `json`) |
 
-**Any other MCP host** (Cursor, Windsurf, Claude Desktop, an SDK client), in its MCP config:
+**Any other MCP host** (Cursor, Windsurf, Claude Desktop, an SDK client): put this in its MCP
+config. The path is optional; without it the server uses its working directory.
 
 ```json
 {
@@ -146,23 +157,48 @@ Code, then ask it to run `check`.
 }
 ```
 
-The path is optional; without it the server uses its working directory.
-
-**Command line**, for the `doctor`/`init`/`bench` commands below: `npx minnimemory doctor`, or
-`npm install -g minnimemory` for a `minnimemory` binary. Maintainers working on the compiler
-itself clone the repo, `npm ci && npm run build`, and run `node dist/cli.js` in place of `npx
-minnimemory`.
+**No MCP at all**: every verb below also runs from a terminal as `npx -y minnimemory <verb>`,
+with nothing installed. `npm install -g minnimemory` gives you a `minnimemory` binary if you
+prefer. Maintainers working on the compiler itself clone the repo, `npm ci && npm run build`,
+and run `node dist/cli.js` in place of `npx minnimemory`.
 
 ## Use it
 
-Every block below is the real output of that command against
-`examples/CLAUDE.md`, a 75-line memory file for a fictional bookkeeping API, shipped in this
-package.
+Four verbs, the same four whether your agent calls them or you type them:
+
+| verb | what it does | writes anything? |
+|---|---|---|
+| `doctor` | audits your memory file: findings, how many tokens load every turn, drift since the last apply | no |
+| `init` | shows the plan: what stays always-on, what becomes an OnDemandMemory file, the prefix before and after | no |
+| `apply` | compiles (or re-applies after you edit a file), original backed up first | terminal: yes, to disk. MCP: returns the files and your agent writes them |
+| `undo` | puts your original memory file back and removes `.minnimemory/` | terminal: yes. MCP: returns the original and what to delete |
+
+The order is always the same: `doctor`, `init`, `apply`, then `doctor` again whenever you edit
+a memory file by hand (it reports drift and `apply` brings it current). `undo` at any time.
 
-### 1. Find out what your setup costs
+### In Claude Code (agentic)
+
+After the install, open Claude Code in your project and say what you want in plain words. The
+server tells the agent the loop on connect, so these four requests are all it takes:
+
+| you say | the agent calls | what you see |
+|---|---|---|
+| "run doctor on my memory" | `doctor` | the findings and the always-loaded token count |
+| "show me the plan" | `init` | the split and the before/after, nothing written |
+| "apply it" | `apply` | the files to write; the agent writes each one and Claude Code shows it to you as a diff to approve. Your original is the first file written, to `.minnimemory/original/` |
+| "undo the memory compile" | `undo` | the original file written back and `.minnimemory/` removed, again as approved writes |
+
+Every write goes through your own tool's approval prompt. The MCP server itself only reads.
+
+### In the terminal
+
+Every block below is the real output against `examples/CLAUDE.md`, a 75-line memory file for
+a fictional bookkeeping API, shipped in this package.
+
+**1. `doctor`: what is it costing?**
 
 ```
-$ npx minnimemory doctor
+$ npx -y minnimemory doctor
 
   MM003  "Current status" (lines 6-11) holds a status heading and   high
          dated entries and status language in the always-loaded
@@ -190,15 +226,13 @@ $ npx minnimemory doctor
 
 Every finding names a rule id, a file, a line range, and what to do about it. Nothing is changed.
 
-### 2. Preview the compile
+**2. `init`: what would a compile do?**
 
-`init` is a **dry run by default**. It prints the full plan and writes nothing. The plan carries
-the decision as well as the shape: exact session bounds, a plain verdict, and the `doctor`
-findings `init` will not act on. If the verdict is "leave this file as it is", `--write` refuses
-unless you pass `--force`: the tool will not quietly make a file more expensive.
+`init` never writes; that is `apply`'s job. If the verdict is "leave this file as it is",
+`apply` refuses unless you pass `--force`: the tool will not quietly make a file more expensive.
 
 ```
-$ npx minnimemory init
+$ npx -y minnimemory init
 
   source: CLAUDE.md (689 tokens)
 
@@ -236,30 +270,55 @@ $ npx minnimemory init
     create    .minnimemory/OnDemandMemory/memory_write_protocol.md
     overwrite CLAUDE.md
 
-  dry run, nothing written. Pass --write to apply.
+  dry run, nothing written. Run "minnimemory apply" to compile.
 ```
 
-### 3. Apply it
+**3. `apply`: do it**
 
-```bash
-npx minnimemory init --write
 ```
+$ npx -y minnimemory apply
 
-Your original is copied verbatim to `.minnimemory/original/` before anything is touched.
+  ...the same file list as the plan, written...
+    create    .minnimemory/OnDemandMemory/memory_write_protocol.md
+    overwrite CLAUDE.md
+```
 
-### 4. Check the result
+Your original is copied verbatim to `.minnimemory/original/CLAUDE.md.bak` before anything
+else is touched. Run `doctor` again and it says "no drift since init".
 
-```bash
-npx minnimemory doctor
+**4. After a hand edit: `doctor`, then `apply` again**
+
+Edit any file under `.minnimemory/OnDemandMemory/` or the stub freely. `doctor` reports what
+moved; `apply` re-applies and keeps your edit.
+
+```
+$ npx -y minnimemory doctor
+  MM010  .minnimemory/OnDemandMemory/changelog.md was edited since  med
+  drift: 1 file changed since init (MM010). Re-apply with: minnimemory apply
+
+$ npx -y minnimemory apply
+    overwrite .minnimemory/manifest.json
+    overwrite CLAUDE.md
 ```
 
-### 5. Keep it honest in CI
+**5. `undo`: back to where you started**
+
+```
+$ npx -y minnimemory undo
+
+  restored CLAUDE.md from .minnimemory/original/CLAUDE.md.bak
+  deleted: .minnimemory
+```
+
+The result is byte-identical to the file you started with.
+
+### Keep it honest in CI
 
 `doctor` exits non-zero when findings reach the threshold, so memory bloat fails the build the
 same way a lint error does.
 
 ```yaml
-- run: npx minnimemory doctor --ci --fail-on med
+- run: npx -y minnimemory doctor --ci --fail-on med
 ```
 
 Exit codes: `0` clean, `1` findings at or above `--fail-on`, `2` execution error.
@@ -322,28 +381,54 @@ Audits. Never modifies anything. Works on a repo, a directory of memory files, o
 
 ### `minnimemory init [path]`
 
-Compiles. **Dry run by default.**
+Previews. **Never writes** - `init` and `apply` are the same four-verb loop (`doctor`, `init`,
+`apply`, `undo`) the MCP basic profile uses, and the CLI's only difference from MCP is who
+writes: the CLI writes to disk itself, from `apply`; the MCP tools return the files for the
+agent to write. Passing `--write` or `--update` to `init` prints one line ("init never writes;
+use apply") and exits.
 
 | flag | effect |
 |---|---|
-| `--write` | actually apply. Without it, prints the plan and exits |
-| `--force` | overwrite an existing `.minnimemory/`, and compile a file the plan's verdict says to leave alone |
-| `--update` | recompile a compiled workspace from its stub and the OnDemandMemory files on disk, keeping hand edits. See [Keeping it current](#keeping-it-current) |
+| `--force` | on a compiled workspace with no drift, preview the re-apply plan anyway; also previews compiling a file the plan's verdict says to leave alone |
 | `--budget <n>` | always-loaded token budget AlwaysOnMemory must fit. AlwaysOnMemory-like sections that do not fit are routed to OnDemandMemory and listed in the plan. Default 2000 |
 | `--profile <name>` | how much guidance to embed: `auto`, `none`, `routing`, `full`. Default `auto`: `none` when the source is under the budget, `routing` at or over it |
-| `--allow-secrets` | compile even when the source holds a credential-shaped string. Without it, `--write` refuses |
+| `--allow-secrets` | preview as if a credential-shaped source were allowed through |
 
-`init` follows a pointer: if `CLAUDE.md` is only `@AGENTS.md` or "See `AGENTS.md`", it compiles
-`AGENTS.md`. It never follows a symlink, in either direction.
+### `minnimemory apply [path]`
+
+Writes. Looks at the workspace and does the right thing: an uncompiled compilable file gets a
+fresh compile; a compiled workspace with drift gets re-applied, keeping every hand edit; a
+compiled workspace with no drift prints "nothing to apply" and changes nothing. Same backups
+(`.minnimemory/original/`, `.minnimemory/previous/`), refusals and flags as the old `init
+--write`/`init --update --write` had:
+
+| flag | effect |
+|---|---|
+| `--force` | compile a file the plan's verdict says to leave alone |
+| `--budget <n>` | always-loaded token budget AlwaysOnMemory must fit. Default 2000 |
+| `--profile <name>` | how much guidance to embed: `auto`, `none`, `routing`, `full`. Default `auto` |
+| `--allow-secrets` | compile even when the source holds a credential-shaped string. Without it, `apply` refuses |
+
+`init`/`apply` follow a pointer: if `CLAUDE.md` is only `@AGENTS.md` or "See `AGENTS.md`", they
+compile `AGENTS.md`. Neither follows a symlink, in either direction.
+
+### `minnimemory undo [path]`
+
+Restores. Writes the host memory file back from `.minnimemory/original/<name>.bak` and removes
+`.minnimemory/` (only after confirming it still holds a `manifest.json` - a cheap check that
+this is really a minnimemory workspace). Restores the original always: the file as it was
+before the first `apply`, whatever re-applies happened since. "nothing to undo" when not
+compiled; a clear error when the original copy is missing (`doctor` reports that as a finding
+before it matters). No flags.
 
 ### `minnimemory mcp [path]`
 
-Starts an MCP server, `--profile basic` (four verbs, two registered per launch) by default, for hosts that cannot hold the
-OnDemandMemory list in their own prefix or that have no memory file at all. `mcp`'s `--profile`
-picks the tool surface (`basic`/`full`); it is a different flag from `init`'s `--profile`
-(`auto`/`none`/`routing`/`full`, [below](#profiles)), which picks how much discipline guidance
-gets embedded in a compile - same word, two unrelated knobs on two different commands. Register
-it with your agent rather than running it by hand:
+Starts an MCP server, `--profile basic` (the same four verbs, always registered) by default,
+for hosts that cannot hold the OnDemandMemory list in their own prefix or that have no memory
+file at all. `mcp`'s `--profile` picks the tool surface (`basic`/`full`); it is a different
+flag from `init`'s `--profile` (`auto`/`none`/`routing`/`full`, [below](#profiles)), which
+picks how much discipline guidance gets embedded in a compile - same word, two unrelated knobs
+on two different commands. Register it with your agent rather than running it by hand:
 
 ```bash
 claude mcp add minnimemory -- npx -y minnimemory mcp
@@ -351,66 +436,55 @@ claude mcp add minnimemory -- npx -y minnimemory mcp
 
 Other hosts: see [Install](#install).
 
-#### The basic profile (default): `check`, `optimize`, `sync`, `recall`
+### `minnimemory install`
 
-Four verbs, two registered per launch. Which two follows from the workspace on disk, with no
-flag to set: the server looks once, at launch, for a `.minnimemory/` directory under its root.
+Registers minnimemory with the current host in one command instead of the manual `claude mcp
+add` line above. With the `claude` CLI on PATH:
 
-| workspace at launch | read-only | with `--allow-write` |
-|---|---|---|
-| not compiled (no `.minnimemory/`) | `check` | `check`, `optimize` |
-| compiled | `recall` | `recall`, `sync` |
-| a memory directory (Layout B, no manifest) | `check`, `recall` | `check`, `recall`, `optimize` |
+```bash
+npx -y minnimemory install
+```
 
-`recall` cannot answer without a manifest, and `check`/`optimize` have no first compile left to
-plan once one exists, so registering the other half would charge its definition every turn for
-a tool that session could not use. The surface is fixed for the life of the process: a session
-that compiles mid-way (`optimize` says so in its response) relaunches to get `recall` and `sync`.
-One consequence: compiling a second, uncompiled file under a root that already holds a
-`.minnimemory/` directory is not reachable over MCP on this profile; the CLI's `init` covers it.
+| flag | effect |
+|---|---|
+| `--scope <name>` | `user`, `project`, or `local`, same meaning as `claude mcp add -s`. Default `user` |
+| `--write` | append `--allow-write` to the served command |
+| `--auto-memory` | append `--include-auto-memory` to the served command |
+| `--dry-run` | print the command without running it, exit 0 |
+| `--force` | remove an existing registration first, then re-add |
+| `--host <name>` | `cursor`, `windsurf`, or `json`: print the `mcpServers` JSON snippet for that host and its usual config path, write nothing, exit 0 |
+
+Idempotent: an existing registration is reported, with the command to change it, not duplicated.
+Without the `claude` CLI on PATH it prints the manual line and the JSON snippet instead, and
+exits 2. If `claude` itself errors, its stderr is printed and it exits 1.
+
+Also the default when `minnimemory` runs with no subcommand and no terminal attached (see
+[`mcp`](#minnimemory-mcp-path) above): a bare `minnimemory` prints this usage text at a real
+terminal, and serves the MCP server otherwise, which is how a host that just spawned it always
+looks.
+
+#### The basic profile (default): `doctor`, `init`, `apply`, `undo` (DESIGN.md 6.7)
+
+A one-time converter: four read-only tools, all always registered - no phase probe, no
+`--allow-write` gate. The server never writes the user's disk on this profile: `apply` returns
+the exact files a compile or re-apply would write, `undo` returns the original file to restore
+and the paths to delete, and the calling agent writes them itself, through its own host's
+diff-and-approve. `--allow-write` has no effect here (it still gates `full`'s three write
+tools, below) and just prints one line saying so.
 
 | tool | returns |
 |---|---|
-| `check(target?, budget?, format?)` | audit findings, always-loaded token count against budget, drift since init for an already-compiled target, and - when `target` is a single compilable file - the compile plan: AlwaysOnMemory/OnDemandMemory split, session bounds, compile-or-leave verdict. When `target` is a memory directory, already compiled, or an index file, the plan half is left out and one line says why plus what to call instead. `format: "json"` returns `{ doctor, plan, planUnavailableReason }` |
-| `optimize(target?, budget?, force?, ops?)` | write. A compilable file: compiles it, or - already compiled - re-applies it instead and says so. A memory directory: with no `ops`, returns `scan`-shape facts plus an instruction block describing the op shapes to propose; with `ops`, applies them (`write_file`/`delete_file`/`rename_file`), backing up every `.md` file first. `force` forwards to the compile path's own force. Needs `--allow-write` |
-| `sync(target?, budget?, force?)` | write. Checks a compiled `target` for drift (MM010) and, only if something drifted, re-applies it, keeping hand edits. Changes nothing when there is no drift unless `force: true`, a deliberate re-apply (on a compiled target this is the same operation as `optimize`, which is not registered on the compiled surface); never compiles a fresh target. Needs `--allow-write` |
-| `recall(query?, file?, headingsOnly?, maxTokens?)` | `query` given: the memory sections most relevant to it, content inline, best first, under a token cap, restricted to `file` when given. `query` omitted: the OnDemandMemory routing list, no content. `headingsOnly: true` with `file`: that file's headings only. `headingsOnly` without `file` is an error. When its index rebuild finds an OnDemandMemory file changed since `init` wrote it (MM010, the same hash `check`/`doctor` use), the response names the drifted files and points at `sync()`, or at the CLI when `--allow-write` is off |
-
-A `recall()` query that matches nothing does not just say so: the response inlines the same
-routing list `query` omitted returns, so the caller lands on the right `file` without a second
-round trip, followed by "No file matched; pick from the list above and call recall() with file
-set." (`module` on the full profile's `recall`).
-
-`check`/`optimize`/`sync` accept the literal `"auto-memory"` as `target` where it makes sense
-(needs `--include-auto-memory`), the same resolution `scan`/`reorganize` use in the full profile,
-below. None of the four take `profile`, `episodicJson` or `allowSecrets` over MCP - the CLI keeps
-those for maintainers; the MCP tools always compile with `profile: "auto"` and refuse rather than
-override.
-
-#### Memory folders without compiling (2026-09-16)
-
-A third launch shape, alongside "not compiled" and "compiled" above: a memory directory an index
-file (`MEMORY.md`, `index.md`, `INDEX.md`, or `README.md`) plus topic `.md` files, or a Claude
-Code auto-memory folder, with no `.minnimemory/` at all. On that shape the server registers
-`recall` alongside `check` (and `optimize` with `--allow-write`), backed by `recallDir` instead
-of a manifest: it builds the same section-level units `recall` builds from a compiled workspace's
-OnDemandMemory files, straight off the topic files on disk, and ranks them the same way (stemmed
-BM25, `router.ts`). An index file's hook lines ("`- [Title](file.md) - hook text`") count as
-triggers, the same way `Research/Pipeline/replay_ranker.mjs` already treats them for its own
-offline replay. It is lexical and fully offline - no embeddings, no model call, no compile step -
-so it works on a repo you have not run `init` against at all, and on Claude Code's own
-OS-level auto-memory folder unmodified. `README.md` and any `archive/` subfolder are never
-treated as topic files. The same command is available from the CLI:
-
-```bash
-minnimemory recall <path> <query...>            # full section content, best first
-minnimemory recall <path> <query...> --headings # just "file > heading path (n tokens)" lines
-```
-
-Real per-turn cost of the two tools together, `Research/TokenTest/tool_cost.mjs`
-(`Research/docs/2026-09-16-tool-cost.md`; see the table under
-[When the MCP route pays off](#when-the-mcp-route-pays-off)): 740 tokens read-only, 1,397 with
-`--allow-write`.
+| `doctor(target?, budget?, format?)` | audit findings, always-loaded token count against budget, and - for an already-compiled target - drift since the last `apply` (MM010), plus one finding when the original backup `undo` needs is missing |
+| `init(target?, budget?, force?, format?)` | never writes: on an uncompiled compilable file, the compile plan - AlwaysOnMemory/OnDemandMemory split, session bounds, compile-or-leave verdict; on a compiled workspace, the re-apply plan when `doctor` would report drift, else "nothing to re-apply" (`force: true` previews it anyway); on a memory directory, the audit findings plus one line that folder reorganization is `--profile full`'s job (`scan` then `reorganize`) |
+| `apply(target?, budget?, force?, format?)` | the files a compile or re-apply would write, as `{ path, content }` pairs, backup first, for the agent to write itself. First compile: `.minnimemory/original/<name>.bak`, then the stub, `AlwaysOnMemory.md`, every OnDemandMemory file, `manifest.json`, `original/.gitignore`. Drifted workspace: `.minnimemory/previous/<name>.bak`, then only the files whose content changed. No drift: "nothing to write", no files. Refused (no files) on a credential-shaped source (MM008, no override over MCP) or a leave-verdict compile unless `force: true`. `format: "json"` returns `{ files?, instructions? }` |
+| `undo(target?, format?)` | the restore set: the dev's original memory file, from `.minnimemory/original/<name>.bak`, to write back over the stub, and the paths to delete (`.minnimemory/`), for the agent to write and delete itself. Restores the original always - the file as it was before the first `apply`, whatever re-applies happened since. No compiled workspace: "nothing to undo". Backup missing: says so and points at `doctor`. `format: "json"` returns `{ files?, delete?, instructions? }` |
+
+`doctor` and `init` accept the literal `"auto-memory"` as `target` where it makes sense (needs
+`--include-auto-memory`), the same resolution `scan`/`reorganize` use in the full profile,
+below; `apply` and `undo` on a memory directory answer that reorganization lives under
+`--profile full`. None of the four tools take `profile`, `episodicJson` or `allowSecrets` over
+MCP - the CLI keeps those for maintainers; `apply` always compiles with `profile: "auto"` and
+refuses rather than override.
 
 #### Claude Code hook (experimental, 2026-09-16)
 
@@ -435,15 +509,15 @@ Cost: about the size of the printed block (600 tokens by default, `--headings` f
 heading-path lines), added to the transcript on every turn the hook fires - not a one-time
 `tools/list` charge like the MCP tools above, so start with `--headings` and widen only if the
 heading line alone is not enough to decide whether to open the file. This is experimental until
-the gate in `Research/FlagShipInterfaces/README.md` part (c) runs (a live Pipeline run measuring
-it against a real session, not the offline unit tests in `tests/hook.test.ts`).
+it has been measured in a live session, not only by its offline unit tests.
 
 #### The full profile (`--profile full`): today's nine, for maintainers
 
 `--profile full` registers the original nine tools, unchanged in name, schema and behaviour, so
 anything already built against them keeps working. Use it for the session where you are
-maintaining the compiler itself, or driving a memory-directory reorganization directly rather than
-through `optimize`'s facts-then-ops loop.
+maintaining the compiler itself, for per-turn `recall` retrieval, or for driving a
+memory-directory reorganization directly with `scan` and `reorganize` (basic profile only
+audits a memory directory, via `doctor`/`init`).
 
 | tool | returns |
 |---|---|
@@ -453,111 +527,137 @@ through `optimize`'s facts-then-ops loop.
 | `doctor(target?, budget?, only?, ignore?, format?)` | audit findings, always-loaded token count against budget, and (for a compiled target) drift since init. `format: "json"` returns the machine-readable report instead of text |
 | `plan(target?, update?, budget?, format?)` | what compiling `target` would do - AlwaysOnMemory, OnDemandMemory, session bounds, the compile-versus-leave verdict - without writing anything. `format: "json"` returns a compact summary object instead of the rendered report |
 | `scan(target?, detail?, files?)` | structured inventory of memory files: frontmatter, sections, volatility evidence, keywords, cross-file duplicates. `target` is a path, or the literal `"auto-memory"` (needs `--include-auto-memory`). `detail: "summary"` (default) returns per-file counts and rollups; `"full"` returns every section. `files` restricts to exact rel matches, with unmatched names in `unknownFiles`. |
-| `apply(target?, budget?)` | compiles `target`, same as `init --write`. Refuses an already-compiled target - call `update()` instead - and a compile that would not shrink the prefix or holds a credential-shaped string, with no override over MCP. Needs `--allow-write` |
-| `update(target?, budget?)` | recompiles an already-compiled `target` from its stub and OnDemandMemory files, same as `init --update`. Needs `--allow-write` |
+| `apply(target?, budget?)` | compiles `target`, same as the CLI's `apply` on an uncompiled file. Refuses an already-compiled target - call `update()` instead - and a compile that would not shrink the prefix or holds a credential-shaped string, with no override over MCP. Needs `--allow-write` |
+| `update(target?, budget?)` | recompiles an already-compiled `target` from its stub and OnDemandMemory files, same as the CLI's `apply` on a drifted workspace. Needs `--allow-write` |
 | `reorganize(target?, ops)` | applies `write_file` / `delete_file` / `rename_file` operations to `target` (default: this server's root, or `"auto-memory"`, needs `--include-auto-memory`). Needs `--allow-write` |
 
 `recall`/`modules`/`outline` need a compiled workspace. `doctor`/`plan`/`scan` do not: they work
-on any target, compiled or not. `apply`/`update` are the single-file compile path (what the CLI's
-`init` and `init --update` do); `reorganize` is the multi-file path.
+on any target, compiled or not. `apply`/`update` are the single-file compile path (what the
+CLI's `apply` does on an uncompiled file or a drifted workspace, respectively); `reorganize` is
+the multi-file path.
+
+A `recall()` query that matches nothing does not just say so: the response inlines the routing
+list a query-less call returns, so the caller lands on the right `module` without a second
+round trip, followed by "No file matched; pick from the list above and call recall() with
+module set."
+
+Recall over a memory folder with no `.minnimemory/` manifest at all - an index file (`MEMORY.md`,
+`index.md`, `INDEX.md`, or `README.md`) plus topic `.md` files, or a Claude Code auto-memory
+folder - is backed by `recallDir` instead: it builds the same section-level units `recall` builds
+from a compiled workspace's OnDemandMemory files, straight off the topic files on disk, and ranks
+them the same way (stemmed BM25, `router.ts`). An index file's hook lines
+("`- [Title](file.md) - hook text`") count as triggers, the same way recall over a compiled
+workspace treats manifest triggers. It is lexical and fully offline - no embeddings, no model
+call, no compile step - so it works on a repo you have not run `init`/`apply` against at all,
+and on Claude Code's own OS-level auto-memory folder unmodified. `README.md` and any `archive/`
+subfolder are never treated as topic files. The same ranking is available from the CLI, with no
+profile flag needed:
+
+```bash
+minnimemory recall <path> <query...>            # full section content, best first
+minnimemory recall <path> <query...> --headings # just "file > heading path (n tokens)" lines
+```
 
 #### The loop
 
-Point a client at the basic profile and the intended flow is: **check, then optimize, then
-sync**, with **recall** in between turns once something is compiled.
+Point a client at the basic profile and the intended flow is: **doctor, then init, then
+apply**, with **doctor again** whenever a memory file changes, and **undo** to get the
+original back.
 
 ```
-check()      - what does this file/directory cost, and what would compiling it do?
-             - (show the person the result before doing anything)
-optimize()   - compile it (or apply a reorganize plan you both approved)
-recall()     - per-turn retrieval against the compiled workspace, in later turns
-sync()       - after someone hand-edits a memory file, catch the workspace back up
+doctor()                - what does this file/directory cost right now?
+                         - (show the person the result before doing anything)
+init()                  - what would a compile (or, later, a re-apply) do? preview only
+apply()                 - get the files a compile (or re-apply) would write
+                         - (write them yourself, original first, through your own diff/approve)
+doctor()                - after someone hand-edits a memory file, this reports drift
+apply()                 - get the re-apply files again
+undo()                  - get the original memory file back, and what to delete
 ```
 
-**The server only advertises the tools you asked for, and the basic profile only the half the
-workspace can use.** Every tool definition is charged to the client's prefix on every turn,
-called or not. Real costs (`Research/TokenTest/tool_cost.mjs`, `approx-v2` tokenizer; full table
-and what the number is: `Research/docs/2026-09-16-tool-cost.md`):
+**All four tools are always registered, and every tool definition is charged to the client's
+prefix on every turn, called or not.** Measured costs (`approx-v2` tokenizer, an offline
+estimate, 2026-09-17):
 
-| launch | workspace | tools advertised | prefix cost |
-|---|---|---|---|
-| `mcp` (default, basic, read-only) | not compiled | `check` | 364 tokens |
-| `mcp --allow-write` (basic) | not compiled | `check`, `optimize` | 1,021 tokens |
-| `mcp` (default, basic, read-only) | compiled | `recall` | 329 tokens |
-| `mcp --allow-write` (basic) | compiled | `recall`, `sync` | 620 tokens |
-| `mcp` (default, basic, read-only) | memory directory | `recall`, `check` | 740 tokens |
-| `mcp --allow-write` (basic) | memory directory | `recall`, `check`, `optimize` | 1,397 tokens |
-| `mcp --profile full` (read-only) | any | `recall`, `modules`, `outline`, `scan`, `doctor`, `plan` | 1,666 tokens |
-| `mcp --profile full --allow-write` | any | + `apply`, `update`, `reorganize` | 2,668 tokens |
-
-The compiled rows are what a working session holds - well under this tool's own 2,000-token
-always-loaded budget. A tool that was not registered is absent from `tools/list` and answers
-"tool not found" if called; nothing is present-and-refusing, because a refusing tool still costs
-its definition every turn.
-
-Ranking (`recall`) is whole-word keyword overlap against the triggers `init` computed. No
-embeddings, no model call, no network. A query that shares no vocabulary with an OnDemandMemory
-file's triggers will not find it, and that is a deliberate trade for determinism, not a bug.
+| launch | tools advertised | prefix cost |
+|---|---|---|
+| `mcp` (default, basic) | `doctor`, `init`, `apply`, `undo` | 812 tokens |
+| `mcp --allow-write` (basic, no effect) | `doctor`, `init`, `apply`, `undo` | 812 tokens |
+| `mcp --profile full` (read-only) | `recall`, `modules`, `outline`, `scan`, `doctor`, `plan` | 1,666 tokens |
+| `mcp --profile full --allow-write` | + `apply`, `update`, `reorganize` | 2,670 tokens |
+
+A tool that was not registered is absent from `tools/list` and answers "tool not found" if
+called; nothing is present-and-refusing, because a refusing tool still costs its definition
+every turn - the reason the basic profile stays at four tools rather than growing back toward
+the full profile's nine. `recall` is not one of the four: with it gone, nothing runs per turn on
+this profile, and the compiled stub's own OnDemandMemory list still routes the agent to the
+right file in any host, no tool needed. `recall` returns to the basic profile as the "live
+agent" once the converter is proven (DESIGN.md 6.7); for now it stays under `--profile full`.
 
 #### When the MCP route pays off
 
-The cost that matters is the compiled one, because setup happens once: a working session on a
-compiled workspace holds `recall` for 329 tokens of definitions per turn, or `recall` and `sync`
-for 620 with `--allow-write`. The setup surface (`check` 364, `check` and `optimize` 1,021) is
-paid only by the session that does the first compile, and that session relaunches afterwards.
-The shipped `examples/CLAUDE.md` breaks even at 407 tokens per turn (see [Use it](#use-it)). The
-read-only definitions alone sit under that, but they are not the whole bill: every `recall`
-answer adds the sections it returns, up to 1,500 tokens by default, so one routed answer on that
-example costs more than the compile saved on that turn. The MCP route pays for itself when the
-per-turn prefix saving is bigger than the definition cost plus whatever `recall` returns for a
-typical query - in practice, a memory whose always-loaded prefix sits well above the 2,000-token
-budget, where the alternative `recall` is replacing is an agent reading the whole file on every
-task rather than a routed section. A small memory file is cheaper served the way this README's
-own examples are: compiled once, read directly by the agent, no server attached.
-
-#### Single-file compile (`check` + `optimize`, or `doctor` + `plan` + `apply` + `update` under `--profile full`)
-
-The CLI's `init`/`init --update`, over MCP, so an agent applies the interface without shelling
-out. `target` is a path relative to the server's root (default: the root itself); it is confined
-to the root the same way `reorganize`'s paths are - no absolute paths, no `..` segments, no
-escaping via a symlink.
-
-- `check` never writes; it is registered whenever the root is not yet compiled, with or
-  without `--allow-write`. It audits (`doctor`) and, when `target` is a compilable file,
-  previews the compile (`plan`) in the same response. Accepts `format: "json"`
-  for a machine-readable shape instead of the rendered report.
-- `optimize` is gated behind `--allow-write`, same as `sync`. On a compilable file it refuses a
-  compile that would not shrink the always-loaded prefix, refuses a source holding a
-  credential-shaped string, and - on an already-compiled target - re-applies it instead of
-  refusing outright, saying so in the response (`--profile full`'s `apply` refuses that case
-  and points at `update()`; `optimize` just does what `update()` would). `sync` only ever
-  re-applies, and only when `doctor`'s MM010 drift check finds something to re-apply or the
-  call passes `force: true` (a deliberate recompile, reachable on the compiled surface where
-  `optimize` is not registered); it keeps hand edits to AlwaysOnMemory text and OnDemandMemory
-  file content, and backs up the pre-update stub first.
-
-#### Multi-file reorganization (`optimize` with `ops`, or `scan` + `reorganize` under `--profile full`)
+The basic profile's 812 tokens is a flat cost, paid every turn regardless of workspace state -
+no setup/compiled split to average over, and no per-turn retrieval cost either, since `recall`
+is not part of this profile. The shipped `examples/CLAUDE.md` breaks even at 407 tokens per turn
+(see [Use it](#use-it)); the tool definitions alone sit above that, but `apply`/`undo` are a
+one-time cost at compile and restore time, not paid every turn a session runs long. For per-turn
+retrieval against a large memory (`--profile full`'s `recall`), the route pays off on a memory
+whose always-loaded prefix sits well above the 2,000-token budget, where `recall` replaces an
+agent reading the whole file on every task rather than a routed section. A small memory file is
+cheaper served the way this README's own examples are: compiled once, read directly by the
+agent, no server attached.
+
+#### The lifecycle tools (`doctor`/`init`/`apply`/`undo` on basic, or `doctor` + `plan` + `apply` + `update` under `--profile full`)
+
+The CLI's `doctor`/`init`/`apply`/`undo`, over MCP, so an agent applies the interface without
+shelling out - except the write itself, which is the agent's, not the server's. `target` is a
+path relative to the server's root (default: the root itself); it is confined to the root the
+same way `reorganize`'s paths are - no absolute paths, no `..` segments, no escaping via a
+symlink.
+
+- `doctor` and `init` never write. `doctor` audits; `init` previews the compile plan on an
+  uncompiled file, or the re-apply plan on a drifted compiled workspace.
+- `apply` returns the files a fresh compile, or a re-apply (only the files that changed), would
+  write, as `{ path, content }` pairs, for the agent to write itself - backed up first, original
+  before anything else, exactly as `applyPlan` orders them. Accepts `format: "json"` for a
+  machine-readable shape (`{ files?, instructions? }`) instead of the rendered report.
+- `apply` is refused - no files, one line why - on a source holding a credential-shaped string
+  (MM008; no `allowSecrets` override over MCP, same as the full profile's `apply()`), and on a
+  compile that would not shrink the always-loaded prefix unless `force: true` is passed. Neither
+  refusal changes what `doctor`/`init` report: the findings and the verdict are always there.
+- On an already-compiled workspace with no drift, `apply` returns `files: undefined` and the
+  response says "nothing to write".
+- `undo` returns the dev's original file (from `.minnimemory/original/<name>.bak`) and the paths
+  to delete. No backup present: says so and points at `doctor`, which flags a missing backup as
+  a finding before it matters.
+
+#### Multi-file reorganization (`--profile full`: `scan` + `reorganize`)
 
 `init` compiles one host file. A Claude Code auto-memory folder is a different shape: an
 OnDemandMemory-style list plus dozens of topic files, already multi-file, needing content moved
-*between* files rather than split out of one. `optimize`, pointed at a memory directory, splits
-the work along the same deliberate line the full profile's `scan`/`reorganize` pair always has:
-
-- **Facts first, and only facts.** With no `ops`, `optimize` returns `scan`-shape structure:
-  frontmatter (`name`/`description`/`metadata.type`), section boundaries, which sections carry
-  volatility evidence and why, candidate routing keywords, and blocks duplicated across files. It
-  never classifies, merges, or decides on its own.
+*between* files rather than split out of one. LLM-authored reorganize ops on a folder like that
+wait for the answer-quality harness (DESIGN.md 6.6, point 4), so this is a `--profile full`
+capability for now, not part of the basic profile's `doctor`/`init`/`apply`/`undo` surface:
+
+- **Facts first, and only facts.** `scan` returns structure: frontmatter
+  (`name`/`description`/`metadata.type`), section boundaries, which sections carry volatility
+  evidence and why, candidate routing keywords, and blocks duplicated across files. It never
+  classifies, merges, or decides on its own.
 - **The calling agent makes the judgment.** Which sections are semantic vs episodic vs
   procedural, what merges, what is stale, where content belongs under O1-O5. That reasoning is
-  the agent's, done in the agent's own session, from the facts `optimize` just handed it.
-- **Then `optimize` again, with `ops`, executes.** The same explicit `write_file` / `delete_file`
-  / `rename_file` operations `reorganize` takes, applied the same way.
+  the agent's, done in the agent's own session, from the facts `scan` just handed it.
+- **Then `reorganize` executes** the explicit `write_file` / `delete_file` / `rename_file`
+  operations the agent proposed.
+
+`doctor`/`init` on a memory directory still audit it and say, in one line, that reorganization
+lives under `--profile full`.
 
-Both take a `target`: a path relative to the server root (default: the root itself), or the
-literal `"auto-memory"`, which resolves to the operator's OS-level Claude Code auto-memory folder
-for this root - a real directory outside the server root, so it only resolves when the server is
-launched with `--include-auto-memory`; without the flag, `"auto-memory"` is refused with a clear
-error rather than silently falling back to the server root.
+Both `scan` and `reorganize` take a `target`: a path relative to the server root (default: the
+root itself), or the literal `"auto-memory"`, which resolves to the operator's OS-level Claude
+Code auto-memory folder for this root - a real directory outside the server root, so it only
+resolves when the server is launched with `--include-auto-memory`; without the flag,
+`"auto-memory"` is refused with a clear error rather than silently falling back to the server
+root.
 
 No LLM is embedded in this package and none is called by it. `init`, `doctor` and `scan` stay
 fully deterministic and offline. The intelligence is the agent already driving the tools, not an
@@ -576,13 +676,14 @@ Safety, non-negotiable and not skippable:
 - **Every `write_file`/`delete_file`/`rename_file` path must end in `.md`.** Containment alone
   still let a write land on an extensionless file like `.git/hooks/pre-commit` inside a confined
   root; this operates on memory files, not arbitrary files a confined write could otherwise reach.
-- **Write access is opt-in per launch.** Without `--allow-write` the server is read-only:
-  `optimize`/`sync` (basic) and `apply`/`update`/`reorganize` (full) are not registered at all,
-  so a client cannot call them.
+- **The basic profile is read-only by construction.** The server never writes the user's disk on
+  it; the agent writes what `apply()`/`undo()` return, through its own host's diff-and-approve.
+  `apply`/`update`/`reorganize` (full profile only) are still gated behind `--allow-write` and are
+  not registered at all without it, so a client cannot call them.
 
 In Claude Code the file-based route is usually enough, because the agent can read an
 OnDemandMemory file directly. MCP tool definitions themselves cost prefix tokens on every turn, which is why the
-server registers only the profile you launch it with; weigh even the default two-tool basic
+server registers only the profile you launch it with; weigh even the default four-tool basic
 profile before registering the server on a repo with only a few OnDemandMemory files.
 
 ### `minnimemory bench [path]`
@@ -676,8 +777,8 @@ OnDemandMemory files on disk. Edit either freely.
 
 **Coming back to a memory you optimised earlier? Start with `doctor`.** On a compiled workspace
 it reports whether anything has drifted from what `init` wrote, and names the command to fix it
-(over MCP, `check` does the same on a compiled target, and on the basic profile's compiled
-surface, where `check` is absent, `recall` reports drift itself when it rebuilds its index):
+(over MCP, `doctor` does the same on a compiled target, and also flags a compiled workspace
+whose `.minnimemory/original/` backup is missing, so `undo` cannot restore it):
 
 ```
 $ npx minnimemory doctor
@@ -685,14 +786,14 @@ $ npx minnimemory doctor
   ...findings...
 
   compiled workspace: 4 OnDemandMemory files in .minnimemory/
-  drift: 1 file changed since init (MM010). Re-apply with: minnimemory init --update
+  drift: 1 file changed since init (MM010). Re-apply with: minnimemory apply
 ```
 
 When there is nothing to do it says so plainly ("no drift since init ... Nothing to re-apply"),
 so a re-run costs you one second and no thinking. `doctor` never writes. To apply:
 
 ```bash
-npx minnimemory init --update
+npx minnimemory apply
 ```
 
 It strips the generated parts of the stub, routes anything you appended to it the same way a
@@ -721,19 +822,21 @@ body, so a `project` file that blends current state with a changelog compiles in
 OnDemandMemory files, and an episodic section is never merged into a neighbour. `scan` reports the kind for every section
 of a memory directory too.
 
-With **`init --episodic-json`** (O3, opt in), an episodic OnDemandMemory file is written as
-`OnDemandMemory/<name>.json`: the heading, any preamble, and one entry per dated bullet with its
-continuation lines, all verbatim, so the markdown rebuilds byte for byte. `recall`, `outline`,
-`bench`, `doctor` and `init --update` read JSON OnDemandMemory files as the markdown they stand for. The
-point is Anthropic's documented finding that a model is less likely to rewrite or summarize
-JSON it was only meant to append to. Off by default until it has run in a second host.
+With **`--episodic-json`** (O3, opt in, on `init`'s preview and `apply`'s write), an episodic
+OnDemandMemory file is written as `OnDemandMemory/<name>.json`: the heading, any preamble, and
+one entry per dated bullet with its continuation lines, all verbatim, so the markdown rebuilds
+byte for byte. `recall`, `outline`, `bench`, `doctor`, and a re-applied workspace, read JSON
+OnDemandMemory files as the markdown they stand for. The point is Anthropic's documented
+finding that a model is less likely to rewrite or summarize JSON it was only meant to append
+to. Off by default until it has run in a second host.
 
-`init` also emits one OnDemandMemory file the source did not contain:
+`init`/`apply` also plan/emit one OnDemandMemory file the source did not contain:
 **`OnDemandMemory/memory_write_protocol.md`**, the eleven-item memory write protocol (O9),
 routed by the OnDemandMemory list under `memory, remember, save, write, note, changelog`, so the
-agent opens it when a task is about saving memory and is never charged for it otherwise.
-`init --update` re-emits it, so a protocol change reaches every workspace on the next update. It
-accounts for one OnDemandMemory list line in the prefix figures above.
+agent opens it when a task is about saving memory and is never charged for it otherwise. A
+re-apply (`apply` on a drifted workspace) re-emits it, so a protocol change reaches every
+workspace on the next apply. It accounts for one OnDemandMemory list line in the prefix figures
+above.
 
 OnDemandMemory paths are relative to the file the list sits in: `OnDemandMemory/<name>.md`
 inside `.minnimemory/AlwaysOnMemory.md`, and `.minnimemory/OnDemandMemory/<name>.md` in the stub
@@ -742,10 +845,10 @@ the bare path from the stub, missing, and giving up; the stub has named the full
 
 ## Security
 
-- `doctor`, `init`, and `mcp` make no network calls and never run a subprocess.
-- `init` refuses a symlinked source and refuses to write through a symlink, so a cloned repo
-  cannot point `CLAUDE.md` or an OnDemandMemory file at a file outside the checkout.
-- `init` refuses `--write` when the source holds a credential-shaped string, unless you pass
+- `doctor`, `init`, `apply`, `undo`, and `mcp` make no network calls and never run a subprocess.
+- `init`/`apply` refuse a symlinked source and refuse to write through a symlink, so a cloned
+  repo cannot point `CLAUDE.md` or an OnDemandMemory file at a file outside the checkout.
+- `apply` refuses to write when the source holds a credential-shaped string, unless you pass
   `--allow-secrets`. The verbatim backup in `.minnimemory/original/` ships with a `.gitignore`
   so it stays local.
 - The MCP server validates `manifest.json` and only serves files that resolve inside
@@ -769,11 +872,11 @@ verbatim, the original never destroyed.
 See [`docs/DESIGN.md` section 2, "What it is not"](docs/DESIGN.md#2-what-it-is-not): not a
 conversation compressor, not a RAG index over your code, not a proxy or model router, not a
 summariser. One addition specific to this package: **not a compiler for a memory routing list.**
-`init` refuses `MEMORY.md`, or any file that is mostly links to topic files beside it, with no
-override - compiling a routing list re-files its hook lines as content and orphans every topic
-file. A memory directory is `check`'s job to audit and `optimize`'s (`mcp --allow-write`: facts
-first, then `ops`, backup first) to restructure. Auditing alone needs no write access - `check`
-is registered by default.
+`init`/`apply` refuse `MEMORY.md`, or any file that is mostly links to topic files beside it,
+with no override - compiling a routing list re-files its hook lines as content and orphans
+every topic file. A memory directory is `doctor`/`init`'s job to audit (registered by default,
+no write access needed) and `--profile full`'s `scan`/`reorganize` job to restructure (facts
+first, then `ops`, backup first).
 
 ## Measurement policy
 
@@ -814,7 +917,7 @@ has been exercised end to end, and this README will not claim otherwise until th
 
 Moved to [`docs/DESIGN.md` section 11, "Milestones"](docs/DESIGN.md#11-milestones) (2026-09-16):
 merged with that section's own milestone table, which had drifted out of date. Publish state
-lives there too (as of 2026-09-16 the package is prepared but not yet on npm).
+lives there too (`1.0.0-beta.1` has been on npm since 2026-09-17).
 
 ## License