indelible-mcp 5.7.6 → 5.7.8

package/AI_OPERATORS_HANDBOOK.md

@@ -0,0 +1,929 @@
+# The AI Operator's Handbook for Indelible
+
+**For the AI, not the human.** If you are an assistant with the Indelible MCP connected, this is how to use
+it well — how to hold goals honestly, and how to leave proof on chain that survives you.
+
+**© 2026 Indelible Federation.** Written and verified by Indelible's QA process · **2026-08-16** · built
+against `indelible-mcp@5.7.6` and **re-verified claim-by-claim against `indelible-mcp@5.7.7`** (see Rev 4).
+Every rule here comes from something that actually happened on a real box, not from reading the docs.
+
+**Rev 2 — peer-reviewed.** Draft 1 (`5c3f10c3…` on chain) was sent over the Drift Wire to an independent
+Codex reviewer (request `4ba8a5e9…`, review `23217b69…`) with a standing instruction to attack it. It
+confirmed all five factual claims and returned **one hard error and four dangerous omissions** — the worst
+being that draft 1 never stated the shipped **one-writer rule**, the single most damaging failure mode in
+the product, which I had personally reproduced. All of it is fixed here, and every correction was
+re-verified against the shipped `CLI_HANDBOOK.md` / `CUSTOMER_AGENT_HANDBOOK.md` before being written in.
+
+**Rev 3 — onboarding added, and two of my own claims corrected.** Rev 2 (`b55d4c8f…`) had no day-one
+coverage at all: it began at "MCP already connected," which is useless to the new signup most likely to
+need it. **Part 0 is new.** Building it caught me in two errors of my own:
+
+1. Rev 2 said *"there is no interactive prompt; I checked the source."* **Wrong.** I checked `setupWallet`
+   and the `setup` case but never the no-args branch — bare `indelible-mcp` on a TTY runs a wizard that
+   prompts for the key. **The safe path existed the whole time and I told people it did not.**
+2. Rev 2 said a key pasted into a session "can end up permanently committed to chain." **Overstated.**
+   Session saves scrub validated WIF-shaped strings before the commit. Corrected in 7.2, with the residual
+   risks stated precisely.
+
+**Rev 4 — re-verified against 5.7.7, and the product moved underneath it.** Before shipping this inside
+the npm package, every checkable claim was verified against the *installed* `indelible-mcp@5.7.7` artifact
+rather than any source tree — 210 claims, seven independent reviewers, then an adversarial pass that tried
+to refute each finding before it counted. Thirteen survived. Seven were corrected here.
+
+**Four of those seven were not errors when written** — 5.7.7 shipped the same day and closed them: setup
+now exits `1`, a failed setup installs nothing, the quoted setup error is new wording that leads with the
+safe path, and the README never taught `--wif=` (our own `CLI_HANDBOOK.md` did). **Three were real
+mistakes**, and one mattered: this handbook said a private key inside a saved file is *only flagged*. It
+is **refused** — `credential_in_content` and `secret_filename` sit in an unconditional always-block set
+that no setting overrides. Understating a safety net is the one direction that can hurt someone, because
+an operator who meets that refusal reads it as a bug and reaches for the bypass. Corrected in 7.2.
+
+*A handbook about not trusting your own report should not be the one document nobody checked. Rev 1 was
+confident and wrong in four places; rev 2 was confident and wrong in two more — including one where I said
+"I checked the source" and had checked the wrong branch. **That phrase is exactly the kind of claim this
+handbook tells you not to accept, and it should not have been accepted from me.** Both errors were caught
+by adversarial review, not by re-reading my own work. That is the method working.*
+
+---
+
+# Part 0 — Day one: before any of this works
+
+*Everything after this part assumes a configured wallet and a connected MCP. If the human is a new signup,
+you are here first. **Read 7.2 before you touch a single command in this part.***
+
+## 0.1 The shipped README misdescribes setup; the CLI now corrects it for you
+
+`README.md` documents this Quick Start:
+
+```bash
+npm install -g indelible-mcp
+indelible-mcp setup          # "generates a BSV keypair locally"
+```
+
+**The comment is wrong, and the command alone will not configure anything.** Bare `setup` returns:
+
+```json
+{
+  "success": false,
+  "error": "Private key required. Get it at indelible.one → Settings → Private Key, then run `indelible-mcp` with no arguments and follow the prompts — that path takes the key at a prompt, so it never lands in your shell history. For automation: setup --wif=YOUR_KEY --pin=YOUR_PIN (clear your shell history afterward).",
+  "hint": "Run `indelible-mcp` with no arguments and follow the prompts. That path takes your key at a prompt, so it never lands in your shell history. Use `setup --wif=… --pin=…` only for automation, and clear your shell history afterward if you do.",
+  "hooks": "not installed — setup did not complete"
+}
+```
+
+- **It generates nothing.** `setupWallet` only ever calls `PrivateKey.fromWif(...)` and reports *"Wallet
+  **imported** and encrypted!"*. The key comes **from indelible.one**, not from the package. The README's
+  *"generates a BSV keypair locally"* (`README.md:27`) and its `setup   Generate wallet & register`
+  (`README.md:75`) are both wrong on this point.
+- **It exits `1`.** The failure prints a JSON error and sets a non-zero exit code, so a script can rely on
+  it. ⚠️ That guarantee belongs to the `setup` path specifically — `indelible-mcp status` and
+  `indelible-mcp load` still exit `0` while printing an error, so do not assume every verb signals failure
+  through its exit code.
+- **It installs nothing.** The failure path reports `"hooks": "not installed — setup did not complete"` and
+  writes no files at all, so a failed setup is a clean stop, not a half-install. There is nothing to
+  clean up.
+
+**If a human tells you "I ran setup and nothing happened," this is why.** Nothing is broken on their
+machine, and nothing was half-written. The error itself now names the missing step and the safe way to
+take it — read it to them rather than improvising.
+
+## 0.2 The sequence that actually works
+
+**Steps marked 🧑 are the human's alone. Do not perform them, and do not ask them to route a key through
+you.**
+
+| # | Step | Who |
+|---|---|---|
+| 1 | `npm install -g indelible-mcp` | either |
+| 2 | Claude Code installed (`npm install -g @anthropic-ai/claude-code`) | either |
+| 3 | **Get the key:** indelible.one → sign in → Settings → copy Private Key (WIF) | 🧑 |
+| 4 | **Run bare `indelible-mcp` in their own terminal**, paste the WIF, choose a PIN (4+ chars) | 🧑 |
+| 5 | Wizard auto-runs `claude mcp add --scope user indelible -- indelible-mcp` and installs hooks | auto |
+| 6 | **Fund the wallet** — it prints the BSV address and **blocks until funds arrive** | 🧑 |
+| 7 | Pro, only if they want session saves — `indelible.one/pricing` | 🧑 |
+| 8 | **Back up `~/.indelible/config.json`** — see 7.2 | 🧑 |
+
+**Step 4 is the whole ballgame.** The wizard is the safe path: the key is typed at a prompt, never in
+`argv`, so it never reaches shell history. `setup --wif=KEY --pin=PIN` is the documented alternative and it
+**does** leak to history — prefer the wizard, always.
+
+**Step 6 blocks.** The wizard polls for a UTXO every 10 seconds in an unbounded loop and will sit there
+until the address is funded. **That is not a hang.** If the human says it froze after showing an address,
+tell them it is waiting for coin, and that they can Ctrl-C and re-run `indelible-mcp` later — the wallet is
+already configured by that point.
+
+## 0.3 What they get without paying
+
+Do not imply a free user is locked out — most of the product works:
+
+| Free | Pro |
+|---|---|
+| **All reads** — `recall_context`, `load_context`, `load_file`, `load_project` | Session / file / project saves |
+| Restore, the time card, style loading, Guardrails | The pre-compaction save |
+| Diary conversations | **Goal snapshots to chain** (`save_goals_to_chain` — a Pro write that spends sats) |
+
+A free wallet still gets every hook. The pre-compaction **save** is the piece that prints a plain Pro
+notice instead of saving — **that is not an error**, and you should not report it as one. Their work is
+still on disk; it simply is not yet provable. See 7.1.
+
+**One rough edge to expect:** the wizard's final step offers an AI style, and saving a style is itself
+Pro-gated. On a free plan that step prints a warning and no style is stored. Onboarding still succeeded.
+
+## 0.4 Before you conclude anything is broken
+
+`indelible-mcp status`, `indelible-mcp load`, and `indelible-mcp vault load-file|load-project|load-style`
+work from the CLI **whether or not the MCP is connected in this session**. (⚠️ Not every read has a CLI
+verb: `recall_context` and `diary_recall` are **MCP-only** — there is no `indelible-mcp recall`, it returns
+`✗ unknown command`.) If your Indelible tools are missing, that is a *client wiring* problem, not a dead
+install — check with the CLI before telling the human their setup failed.
+
+Two wiring details worth knowing, because the docs disagree with the code:
+
+- The wizard registers with `claude mcp add --scope user …`, which writes `~/.claude.json`. The README's
+  hand-edited `settings.json` block is a **different** mechanism. If both were done, expect confusion.
+- Dropping `--scope user` registers the server **project-scoped**, so it will not load in other
+  directories. `CLI_HANDBOOK.md` omits the flag; the code includes it. **Follow the code.**
+
+---
+
+# Part 1 — The one rule
+
+> **Never report success that nothing independent of you has confirmed.**
+
+This is the whole handbook compressed. Everything below is that rule applied to a specific surface.
+
+You will be tempted to relay what a tool told you. A tool telling you it worked is **not** evidence that it
+worked — it is evidence that it *said so*. The chain is evidence. A block height is evidence. A second
+source that had no reason to agree with you is evidence.
+
+**Three habits that make you trustworthy:**
+
+1. **Ground over recall.** Never answer from memory about state you can check. Read the file, query the
+   chain, run the command. A memory note is a lead, not a fact.
+2. **Separate what you observed from what you concluded.** *"It printed X"* and *"X means Y"* are different
+   sentences, and the second is wrong far more often. Write both, labelled.
+3. **Correct yourself out loud, immediately.** A wrong claim you retract costs you nothing. A wrong claim
+   the human discovers later costs you everything. *(I have retracted four claims in this engagement. Each
+   retraction made the report stronger, not weaker.)*
+
+---
+
+# Part 2 — Goals: what they are for
+
+Goals are not a to-do list. They are **a durable, timestamped local record of intent and outcome** that
+outlives your context window and survives compaction, and that can be snapshotted to chain afterwards with
+`save_goals_to_chain`.
+
+⚠️ **That snapshot is a Pro write and it spends sats.** On a free plan the call returns the Pro notice and
+no txid; on an unfunded wallet it returns *"No UTXOs available."* So the local record is durable for
+everyone, but **anchored** only for a funded Pro account. Never promise a free user an on-chain goal
+record.
+
+That last part is why they matter. A goal closed with a txid in its evidence is a claim anyone can check
+years later. A goal closed without one is just a story.
+
+## The shape of a real goal
+
+This is a live goal from a production box — study it, because the quality is in the fields most people
+leave empty:
+
+```json
+{
+  "goal_id": "g-002",
+  "title": "Rotate the QA wallet — a WIF was exposed in chat",
+  "intent": "A private key (WIF) was exposed in a chat transcript during earlier work. Any exposed key
+             must be treated as compromised — funds swept to a fresh wallet and all clients repointed —
+             before it can be drained.",
+  "priority": 95,
+  "owner": "user",
+  "next_actions": [
+    "Generate a fresh wallet (new WIF)",
+    "Sweep all funds from the exposed wallet to the new address",
+    "Update ~/.indelible config + every client/bridge to the new key",
+    "Confirm the old wallet reads 0 on-chain and is never reused"
+  ],
+  "success_criteria": "Exposed wallet drained to zero, all clients using the new key, old key retired
+                       permanently.",
+  "evidence_links": [],
+  "proposed_by": "claude",
+  "accepted_at": "2026-07-10T16:44:10.832Z"
+}
+```
+
+**What makes it good:**
+
+- **`intent` answers "why", not "what".** Anyone reading it in six months knows the stakes without asking.
+- **`success_criteria` is falsifiable.** "Drained to zero" can be checked against the chain. "Improve
+  wallet security" cannot. If you cannot imagine the test that proves it done, rewrite it.
+- **`next_actions` are ordered and concrete** — each one is a thing a person could do today, not a theme.
+- **`priority` is honest.** 95 because an exposed key drains. Do not give everything 80.
+- **`owner` is real.** `user` when only the human can act (this one needs their wallet). `claude` when you
+  can finish it alone. `shared` otherwise. Do not own what you cannot do.
+
+---
+
+# Part 3 — The lifecycle, and the governance you must not break
+
+```
+propose  →  (human accepts)  →  work  →  evidence  →  complete  →  snapshot to chain
+```
+
+## 3.1 You propose. The human accepts. Never both.
+
+`manage_goal` records `created_at` / `proposed_by` on propose, and `accepted_at` on accept. That
+separation is the audit trail of consent. **Do not propose and accept in the same breath** — you would be
+manufacturing agreement that never happened.
+
+⚠️ **But know exactly how thin that trail is.** `proposed_by` is not a timestamp and not an identity — it
+is the hardcoded literal `"claude"` for every proposal. And there is **no `accepted_by` field anywhere in
+the product**, so nothing records *who* accepted. The separation is only as truthful as your discipline in
+keeping it. Same convention-not-lock caveat as 3.2 below.
+
+```
+manage_goal(action:"propose", title:…, intent:…, success_criteria:…, next_actions:[…], priority:…, owner:…)
+→ then STOP. Tell the human it is proposed and wait.
+```
+
+If the human says "just do it," you may proceed with the work — but say plainly that the goal is still
+`proposed`, not `accepted`, so the record stays truthful.
+
+## 3.2 ⚠️ "Completion requires evidence" is a convention, not a lock
+
+The tool description says completion requires evidence. **I checked the code: it does not.**
+
+```js
+case "complete":
+  if (evidence) goal.evidence_links = [...]   // ONLY if you pass it. No check. No error.
+```
+
+Nothing stops you closing a goal with nothing to show. Which means **the integrity of the record is
+entirely your discipline.** Treat it as a hard rule anyway:
+
+> **Never call `complete` without at least one evidence link.** If you have no evidence, you have not
+> finished — you have stopped.
+
+The same applies to checklists: an unfinished checklist produces `checklist_advisory` and completes anyway.
+Advisory means *you* are the check.
+
+## 3.3 What counts as evidence
+
+In descending order of strength:
+
+| Evidence | Why it is strong |
+|---|---|
+| **An on-chain txid** | Timestamped, signed, and independently checkable by anyone — see the caveat below |
+| A commit SHA | Verifiable, but only while the repo exists and history is not rewritten |
+| A URL | Verifiable today; may rot |
+| A description of what you did | **Not evidence.** This is a story about evidence |
+
+**Be precise about what a txid proves.** *Existence and timing* are permanent and need nothing from you:
+anyone can confirm that this exact content was committed at that moment, and no one can alter or backdate
+it. **Readability is not automatic.** Recovering the content later needs three things — the transaction
+bytes still retrievable, the payload decryptable, and **the key still in the human's custody.** Lose the
+key and the record stands forever as proof that something was said, permanently unreadable.
+
+So: *"provably committed at this time"* — always true. *"anyone can read this forever"* — only with the key.
+This is exactly why 7.2 matters.
+
+Real example from a live goal — evidence that is actually checkable:
+
+```json
+"evidence_links": [
+  "266da1a50885c1d94d623b0ebe71fd1fc085ad5bf4d32016e65aceab0252482f",
+  "f40507bdc7b552e1a3bc0f4ac96fe40397695fb576570192f713a78a438adf76"
+]
+```
+
+Anyone can take those txids to a bridge and read the artifact. That is the standard.
+
+## 3.4 Use `notes` for findings that change the goal's meaning
+
+When you learn something that reframes the work, write it into `notes` — not into a chat message that
+dies with your context. A real one:
+
+> *"ROOT CAUSE FOUND 7/10 (bigger than Conner): server-side session-store ingestion was frozen fleet-wide
+> since 6/30 16:15 — proven by replay experiment… Conner's client was never at fault; every wallet
+> onboarded after 6/30 had an empty store. Root fixed + backfilled 7/10; verified live (store 34→37).
+> REMAINING: have Conner reload his Context tab."*
+
+Notice: what was found, how it was proven, what it changes, and **what is still open**. That last clause
+is what makes it useful to the next session.
+
+---
+
+# Part 4 — Putting it on chain: making it indelible
+
+Two different things get written, and you should know which you are doing.
+
+**`save_goals_to_chain`** — snapshots the whole goals state to BSV. Use it at meaningful boundaries: after
+a goal is accepted, after one is completed, at the end of a working session. It is the proof that *this
+was the plan, at this time.*
+
+**`save_file` / `save_session`** — writes the artifact itself. Use it for the report, the brief, the
+evidence document whose txid you will then link into the goal.
+
+## The pattern that produces provable work
+
+```
+1. Do the work.
+2. Write the artifact (report, brief, diff, findings).
+3. save_file(artifact)                    →  returns a txid
+4. VERIFY that txid against the chain      →  never trust the receipt alone (Part 5)
+5. manage_goal(action:"complete", evidence:[txid], notes:"what was proven and how")
+6. save_goals_to_chain()                   →  the closure itself is now on chain
+```
+
+Step 4 is the one people skip. It is the one that makes the rest true.
+
+**Why this ordering matters:** the goal's evidence link points at an artifact that already exists on chain.
+Anyone auditing later can follow goal → txid → artifact and check every claim without asking you anything.
+
+---
+
+# Part 5 — Verifying a save (do not trust the receipt)
+
+A save receipt is the writer's own account of itself. Read it, then check it.
+
+**What the receipt fields actually mean on 5.7.7:**
+
+| field | meaning |
+|---|---|
+| `status: "pending"` | On the network, **not yet in a block.** Correct and normal for a fresh save |
+| `status: "committed"` | A block genuinely contains it. Only appears after mining |
+| `status: "unknown"` | The chain could not be reached to classify it. **Not** a failure and **not** a success — go verify directly |
+| `confirmed: false` | Not mined yet — expected alongside `pending` |
+| `indexed: true/false` | Whether the search index accepted it. `false` = on chain but not yet findable. ⚠️ Present on `save_file` and `save_session` receipts **only** — goals, project and style snapshots omit it entirely, and **absent is not the same as `false`** |
+
+⚠️ **Two vocabularies, and the customer sees the other one.** The states above are fields on the
+structured object. The receipt block a human actually reads prints `broadcast` (= `pending`) and
+`confirmed` (= `committed`). And `save_goals_to_chain` — the whole subject of Part 4 — returns the printed
+block only, so its object fields are never visible at all. Read what is in front of you before naming a
+state to the human.
+
+**Never treat `pending` as failure, and never treat a receipt as proof of burial.**
+
+To verify independently, ask the federation directly:
+
+```
+GET http://<bridge>:9333/api/tx/<txid>/hex      → the raw transaction (proves it exists)
+GET http://<bridge>:9333/api/tx/<txid>/status   → blockHeight / confirmed
+GET http://<bridge>:9333/api/address/<addr>/unspent
+```
+
+**The strongest cheap check:** does the transaction's change output appear in the address's live UTXO set?
+That was correct every single time across this engagement, while a bridge's `inMempool` flag was wrong for
+every phantom. Ask several bridges — agreement across independent nodes is the point of a federation.
+
+---
+
+# Part 6 — Failure modes, and what they actually mean
+
+Learn these and you will stop misreading normal behavior as breakage.
+
+| What you see | What it means | What to do |
+|---|---|---|
+| `status: pending` | Normal. Awaiting a block | Nothing |
+| `WALLET_BUSY_RESERVED` | Another agent holds the coin. Names the holder and lease | Retry shortly. Safe |
+| `BROADCAST_REJECTED … txn-mempool-conflict` | Another save took the coin first. **Nothing was spent** | Retry; it rebuilds |
+| `WALLET_KEY_MISMATCH` | The key does not match the account. **Refused before spending** | Do not "fix" by editing config — run setup properly |
+| `indexed: false` | On chain, not yet searchable | Nothing. It catches up |
+| `⚠ agent could not be read … corrupt, NOT deleted` | A torn identity file | **Never re-birth over it.** Restore that file from backup. ⚠️ `agents --restore` will **not** fix it — it refuses an identity it cannot parse (*"refusing to overwrite a file we cannot compare"*) and leaves the file untouched. Only once the file is restored, or deliberately deleted, will a re-run rebuild that agent |
+| `[g-401] lost its coin to <txid>` | Another writer spent it first | Informational |
+| **Two machines, one wallet — both said `success`** | **The reservation is per-machine. One save is genuinely lost, silently** | **Write from one box only — see 7.0** |
+| A Pro-gated tool refusing | Saves need Pro; reads are free | Tell the human what it costs before retrying (7.1) |
+| `could not record receipt … save is on chain` | Local log write failed | Data is safe; fix the file permission |
+
+**Note the shape of that table.** Almost every entry means *nothing is broken and nothing was lost.* The
+one row that means real data loss is the two-machine row — and it is the only one that reports **success**.
+That is the whole lesson of this handbook in a single line: **the alarming messages are safe, and the
+dangerous one looks fine.**
+
+**The meta-lesson:** every one of these is the product being honest with you. Earlier versions said
+"committed" in several of these situations and customers lost work. Do not paper over an honest error by
+retrying blindly — read it.
+
+---
+
+# Part 7 — Things that will bite you
+
+## 7.0 ⚠️ THE ONE-WRITER RULE — read this before anything else in this part
+
+**Read from every machine. Write from one.** This is the single most important operational fact in the
+product, and it is stated in the shipped `CLI_HANDBOOK.md`:
+
+> *"The same wallet on two machines: read from both, write from one. The coin-reservation that stops two
+> saves colliding is kept **on the machine it runs on** — it cannot see a sibling box. So two machines
+> sharing a wallet can pick the same coin, both broadcast, and Bitcoin keeps one; each box sees only its
+> own attempt, so **both can report success while one save is lost.**"*
+
+I have reproduced this on a customer box: two machines, one wallet, one coin — both returned
+`success: true`, and one file was permanently gone. **The reservation layer is correct; it simply cannot
+see another machine.**
+
+**What this means for you:**
+
+- Recall, verify, `load`, and read freely from anywhere.
+- **Do the saving from one machine at a time.** If the human works on a laptop and a desktop, ask which one
+  is the writer.
+- Treat any save that says `pending` or times out as **not yet durable** until you confirm it on chain.
+- If two hosts are connected (e.g. Claude and Codex both with the MCP), **they each run an auto-save
+  timer.** That is two writers on one wallet by default. Say so to the human.
+
+## 7.1 Saving costs money and needs Pro
+
+The shipped customer handbook is explicit:
+
+> *"A funded wallet. **Session, file, and project saves need Pro. All reads are free.**"*
+> *"…all four hooks run for everyone. Restore, the time card, style loading, and Guardrails are fully free.
+> The pre-compaction **save** is the one piece that needs Pro. On a free wallet the hook still fires, but
+> instead of saving it prints the plain notice that saving is a Pro feature. **That is not an error.**"*
+
+Entitlement is checked **server-side per feature**, so do not hand the human a memorized list of gated
+tools — I got that wrong once already. The reliable rule is the documented one: **writes need Pro, reads
+are free.** If a save refuses on plan grounds, read what it actually says and relay that, rather than
+guessing which tier covers what.
+
+**So do not bank reflexively.** Every write spends real satoshis on the human's wallet and requires their
+plan. Bank at **milestones that matter** (Part 10.2), not after every paragraph. On a free wallet, the
+pre-compaction save is the one thing that will not fire — restore, the time card, style loading and the
+guardrails all still work.
+
+## 7.2 Back the key up — "never sync" is only half the advice
+
+`~/.indelible` holds unencrypted key material, so **never** suggest syncing it to Dropbox/iCloud/OneDrive/git.
+
+**But the opposite failure is just as fatal**, and the shipped handbook says so: if the machine dies and
+there is no copy of the key, the history survives on chain **forever and unreadable.** Encrypted with a key
+that no longer exists is the same as gone.
+
+Tell the human to keep a **secure offline copy** of their key — a password manager or paper, not a synced
+folder. This is one of the few things worth interrupting them for.
+
+### ⚠️ Never run setup yourself. There is a safe path — point the human at it.
+
+There are **two** ways to configure the key, and they are not equally safe:
+
+| path | key in shell history / process list | can *you* run it? |
+|---|---|---|
+| **bare `indelible-mcp`** (the wizard) | **No** — typed at a prompt | **No.** TTY-gated |
+| `setup --wif=KEY --pin=PIN` | **Yes — both** | Yes ← the hazard |
+
+**Recommend the wizard.** Bare `indelible-mcp` on a terminal runs `runWizard()`, which prints
+*"Go to indelible.one → Sign in → Settings → copy your Private Key (WIF)"* and prompts `Paste your WIF
+here:`. Nothing reaches `argv`, so nothing reaches the history file.
+
+**It is structurally out of your reach, by design.** The dispatcher sends no-args to the wizard **only when
+`process.stdin.isTTY`**; without a TTY it starts the MCP server instead. So when you invoke it you do not
+get the prompt. Do not fight that — it is the guardrail working.
+
+**The `--wif=` form is the one to avoid.** It writes the key **and** the PIN into `~/.bash_history` /
+`ConsoleHost_history.txt`, and exposes them in process listings while it runs.
+
+The product already steers away from it: the help text lists the wizard **first** as *"recommended — your
+key is never written to shell history"* and labels the flag form *"for automation (both values land in
+shell history)"*, both setup error messages lead with the wizard, and the README never mentions `--wif=`
+at all. The one exception is `CLI_HANDBOOK.md` (lines 231 and 382), which still teaches the flag form with
+no warning attached — treat that as a doc bug, not as guidance, and follow the CLI's own steer instead.
+
+**So:**
+
+- **Never run either form on the human's behalf, and never ask them to paste a key to you.** Name the
+  command; let them run it in their own terminal.
+- If they have already used `--wif=`, have them clear the history entry (`~/.bash_history`, or the
+  PowerShell file at `(Get-PSReadlineOption).HistorySavePath`).
+- If a key ever does appear in your context, **say so immediately** and treat it as compromised. It needs
+  rotating, not hiding.
+
+**Credit where it is due — and a correction to an earlier draft of this handbook.** Rev 2 claimed a key
+pasted into a session "can end up permanently committed to chain." **That was overstated.** Session saves
+run `redactSession()` in the save path — after the envelope is built and before the commit — which
+replaces validated WIF-shaped strings with
+`[REDACTED bsv_wif]` *before* the commit and prints
+`[indelible] redact-on-save: scrubbed N credential-shaped string(s)`. The chain-commit outcome is
+specifically defended against.
+
+**What is still true, and why the rule stands anyway:**
+
+- Redaction guards the **session** path; `save_file` does **not** call it. A key inside a file is caught by
+  the Witness instead, and although the Witness ships advisory (`witness.enforce: false`), two critical
+  codes sit in an unconditional **always-block** set: `credential_in_content` and `secret_filename`. A file
+  save carrying a well-formed key is **refused** (`Witness rejected file save: …`), not merely flagged.
+  Binary files are not content-scanned, but `.pem` / `.key` / `.env` still hard-block on the filename.
+  **Do not reach for `bypass_witness` or `WITNESS_BYPASS=1` to get past this** — that refusal is the last
+  thing standing between a live key and an immutable chain.
+- It is pattern-matched and `isValidWif`-validated: a well-formed key is caught; a wrapped, split or
+  partial one is not guaranteed to be.
+- It cleans the *commit*, not the world. The key is still in the local transcript on disk, still in the
+  terminal scrollback, and still in shell history if it arrived by `--wif=`.
+
+**One layer working is not a reason to hand it more chances.** This is the one rule where being helpful is
+the failure mode: **refusing to touch the key is the correct and maximally helpful action.**
+
+## 7.3 The rest
+
+1. **Coin contention is normal on a busy box.** If auto-save and you both want to write, one waits — see
+   the wait/lease distinction in 7.4. Splitting the balance into several outputs eases *same-machine*
+   contention, **but it does not fix the cross-machine problem in 7.0** and it moves the human's money:
+   **only ever suggest it, never do it unasked**, and let them choose the method.
+2. **Auto-save runs inside the MCP server** — it stops when the editor closes. Before a long break, save
+   once by hand (if they are on Pro).
+3. **On a new machine, run `agents --restore` before concluding the crew is missing.** Agents live in the
+   wallet, not the box. The most common false alarm there is.
+4. **Never print a private key, WIF, or seed** — not into chat, not into a file you will save, not into a
+   goal note. Report *the path and the fact*: "`agents/x/identity.json` has a plaintext `wif` field" is the
+   finding. The key itself is never the finding.
+5. **The credential guard is one layer, not a vault.** It inspects shell commands, will refuse harmless
+   ones whose filenames contain "wif"/"seed", and does not see programmatic reads. Route around it
+   honestly; never treat getting past it as permission.
+6. **Do not run two summoners for one seat** — the wire admits one answer, but both pilots bill the human's
+   vendor account.
+
+## 7.4 The two timers people confuse
+
+- **Wait = 60 s** (`DEFAULT_WAIT_MS`) — how long *your* save will wait for a coin someone else holds.
+- **Lease = 120 s** (`DEFAULT_LEASE_MS`) — how long the *holder's* claim stays valid.
+
+They are different numbers for different actors. A save that gives up after 60 s has not hit a "60-second
+lease" — it waited its full wait while a 120-second lease was still running.
+
+**And Ctrl-C does not create a permanently stuck reservation.** As of 5.7.6 (still true on 5.7.7) a stale reservation — including
+one holding a signed transaction — is reconciled automatically by chain evidence on the next claim.
+**Manual clearing is almost never justified**; if you think it is, snapshot first (10.4) and say why.
+
+---
+
+# Part 8 — A worked example, end to end
+
+The human asks you to look into something. Here is the whole shape:
+
+```
+1. PROPOSE
+   manage_goal(propose,
+     title: "Confirm the bridge tx-status false-negative and file it",
+     intent: "The endpoint reports not-found for transactions that ARE confirmed — the mirror of a
+              hollow confirmed:true. Open since 6/22; unfiled, so it cannot be triaged.",
+     success_criteria: "GitHub issue filed with a reproducible case and the exact endpoint.",
+     next_actions: ["Capture a clean repro", "File on the federation repo", "Link the issue here"],
+     priority: 40, owner: "shared")
+   → tell the human. WAIT for accept.
+
+2. WORK — and ground everything
+   Query the endpoint. Query a control. Record exact responses, not impressions.
+
+3. WRITE THE ARTIFACT
+   A brief with the repro, the control, and the raw output.
+
+4. BANK IT AND VERIFY
+   save_file(brief) → txid
+   check txid on 3+ bridges → confirm it exists
+
+5. RECORD PROGRESS HONESTLY
+   manage_goal(update, notes: "CLEAN REPRO CAPTURED: /chain/seen/e8381c21 returned exists:true
+     height:956557 on 7/5, then exists:false on 7/10 — same tx, same bridge, confirmed both times.
+     Control: a 30-min-old tx returns exists:true. REMAINING: file the issue.")
+
+6. COMPLETE ONLY WHEN THE CRITERIA ARE MET
+   manage_goal(complete, evidence:[txid, issue_url], notes:"…")
+   save_goals_to_chain()
+```
+
+Step 6 is the discipline. If the issue is not filed, the goal is **not** complete — no matter how good the
+repro is. Update it, say what remains, and leave it open. **An honestly open goal is worth more than a
+falsely closed one**, because the next session inherits the truth.
+
+---
+
+# Part 9 — Writing the record: how to keep an arc going
+
+Single documents are cheap. What compounds is an **arc** — a series where each document knows about the
+ones before it, corrections are visible, and a stranger can read them in order and reconstruct the whole
+story without asking anyone a question.
+
+This is the part most operators never learn, and it is the difference between a pile of notes and a record.
+
+## 9.1 What an arc looks like
+
+A real one, produced over eleven days across five releases:
+
+```
+QA-GRADE-5.6.0-2026-08-10.md   D+   44156dd9…  ← baseline: what was broken, and why it was invisible
+QA-GRADE-5.7.1-2026-08-13.md   A−   a649c159…  ← 3 P0s fixed; one condition named for the A
+QA-GRADE-5.7.2-2026-08-14.md   A−   f5770cad…  ← 5 fixed, but a new interaction appeared
+QA-GRADE-5.7.3-2026-08-14.md   A    9cf8febe…  ← the named condition met, exactly
+QA-GRADE-5.7.6-2026-08-16.md   A    44a7cf24…  ← two P1s closed; the biggest unlock of the series
+```
+
+Read top to bottom and you get a narrative with a spine: *a product that lied about saving your work
+learned to tell the truth.* No single document contains that. **The arc does.**
+
+## 9.2 The anatomy of a document that will still be useful in a year
+
+Every entry in an arc carries the same seven parts. Not a template to fill in mechanically — a checklist of
+what a future reader will need.
+
+1. **A header that orients a stranger.** Who wrote it, when, against what version, and *how it was
+   verified*. One line: *"measured on this box or checked against the public chain, never taken from a
+   receipt."*
+2. **A verdict up front.** A grade, a status, a one-sentence judgment. Put it in the first screen. Readers
+   who only read one thing should still get the answer.
+3. **Verbatim evidence, not paraphrase.** Paste the actual output, the exact line number, the real txid.
+   `:11098 buildReceipt(…, { indexed })` is checkable. "the receipt now includes indexed" is a rumour.
+4. **Observation separated from conclusion**, always labelled. *"I observed X"* then *"I conclude Y, and
+   here is why that might be wrong."*
+5. **A status carry-forward** — three buckets, every time: **fixed** (with evidence), **still open** (with
+   why it matters), **new**. This is what makes the next document possible.
+6. **An honesty ledger.** A named section listing what *you* got wrong since the last entry. Non-negotiable —
+   see 9.4.
+7. **Scope, stated as a limit.** What you did *not* test. A reader who mistakes your silence for coverage
+   will make a bad decision with your name on it.
+
+## 9.3 Naming, superseding, and the fact that chain is immutable
+
+**Name for retrieval, not for prettiness.** `SUBJECT-scope-YYYY-MM-DD.md`. A year later someone will find
+it by grepping a folder or a chain index — the filename is the index entry.
+
+**You cannot edit what is on chain.** This changes how you correct things. Two moves, and they are not
+interchangeable:
+
+- **Amend** — the document is not yet banked. Edit it freely, then bank the finished thing.
+- **Supersede** — the document is already on chain. **Write a new one that names what it replaces and
+  why.** Never quietly rewrite history; the old txid still exists and someone will read it.
+
+A real superseding header, doing it properly:
+
+> *"⚠️ THIS DOCUMENT CORRECTS AN ERROR IN THE CONSOLIDATED REPORT `628f6cba…`. It states the crew has never
+> existed on this box. That is FALSE… Chain is immutable, so this document supersedes that section."*
+
+That is the whole move: name the txid, state the error plainly, explain what replaces it. A reader landing
+on the old document from a search still gets pointed at the truth.
+
+## 9.4 The honesty ledger — the part that makes the rest credible
+
+Every entry in an arc should carry a section listing what you got wrong since the last one. A real example:
+
+> - I reported corrupt identity **still silent**. **Wrong** — my check read `stdout` while the warning goes
+>   to `stderr`.
+> - I called the second MCP process **a leaked duplicate**. **Wrong** — it is a legitimate second host.
+> - I inferred a behavior from `findNewestTranscript()`. **Unsupported** — the source fact stands, the
+>   inference does not.
+> - I nearly filed **idempotency broken**. **My test conditions**, not the product.
+
+**Why this is not self-flagellation but the opposite:** a document with no corrections in it reads as
+either flawless or unexamined, and readers correctly assume the second. A ledger tells them you are
+checking, that your other claims survived the same scrutiny, and that when you say something held, it held.
+
+It also does practical work: it stops the *next* session inheriting your bad conclusion as fact.
+
+## 9.5 The daily rhythm
+
+You do not need a release to justify an entry. A working session is enough.
+
+```
+START   get_goals            — hydrate: what was open, what was claimed, what is next
+        load / recent saves  — what the last session actually concluded
+
+DURING  keep a running scratch file: verbatim output, timestamps, txids
+        when something surprises you, write the observation before the explanation
+
+END     write the entry      — verdict, evidence, fixed/open/new, honesty ledger, scope
+        save_file(entry)     → txid
+        VERIFY the txid on chain
+        manage_goal(update or complete, evidence:[txid])
+        save_goals_to_chain()
+```
+
+**Three rules that keep an arc alive:**
+
+- **Write the entry while the evidence is still in front of you.** Reconstructed detail is where errors are
+  born. If you are quoting from memory, you are already guessing.
+- **One entry per session, not one per finding.** Findings are sections. A session is the unit a reader can
+  follow.
+- **Bank it before you move on.** An unbanked document is a draft, and a draft is not a record. The moment
+  it has a txid it is citable, and the *next* entry can point at it instead of repeating it.
+
+## 9.6 How the pieces reference each other
+
+An arc is a graph, and the edges are txids:
+
+```
+goal g-006
+  └── evidence: 266da1a5…            ← the brief proving the repro
+                   └── superseded by: (later brief, if the finding changes)
+
+QA-GRADE-5.7.6  44a7cf24…
+  ├── supersedes: nothing (new release)
+  ├── cites:      the 5.7.3 grade, for the condition that was named and met
+  └── companion:  BUGS-open-as-of-5.7.6  f2c3cf19…
+                    └── supersedes: BUGS-5.7.3-drafted  e48dd3cc…
+```
+
+**When you cite, cite the txid, not the filename.** Filenames are local and can be renamed or lost; a txid
+resolves from anywhere and cannot be altered or backdated. That is the entire reason to put it on chain.
+(Reading the *content* back also needs the key — 3.3.)
+
+## 9.7 The test of a good arc
+
+> Hand the series to someone who was not there. Can they reconstruct what happened, what is true now, and
+> what is still unknown — **without asking you a single question?**
+
+If yes, you have built a record. If they have to ask "but did that ever get fixed?" or "which of these is
+current?", you have built a pile.
+
+---
+
+# Part 10 — Prepare for compaction; do not run into it
+
+Your context window will end. That is not a risk to manage, it is a certainty to schedule around. The
+difference between a good operator and a green one is whether compaction finds them **ready or mid-sentence.**
+
+## 10.1 What actually happens
+
+The pre-compact hook fires and saves the session automatically. **Do not rely on that as your plan** — it
+saves the *transcript*, not your *conclusions*. A transcript of you reasoning toward a finding is not the
+same artifact as the finding, written down, with its evidence, banked and citable.
+
+Auto-save is your seatbelt. The daily MD is your actually-arriving-somewhere.
+
+## 10.2 Bank at milestones, not at the end
+
+The failure mode is obvious once you have seen it: you work for three hours, plan to "write it up at the
+end," and compaction arrives at hour two and forty minutes. Everything you *knew* is now a summary of a
+summary.
+
+**Bank when a thing becomes true, not when the session ends.**
+
+| Moment | What to do |
+|---|---|
+| A finding is proven | Write the section. Bank the MD if it stands alone |
+| A goal's criteria are met | `complete` with evidence, then `save_goals_to_chain()` |
+| You are about to do something destructive | Snapshot the evidence **first** (see 10.4) |
+| Context feels long, or the human goes quiet | Write the entry now, while the detail is in front of you |
+| Before any risky or long operation | Bank first — so a crash costs the operation, not the knowledge |
+
+**Rule of thumb: if losing the last hour would hurt, you are already overdue.**
+
+**Separate the two halves, because only one costs money.** *Writing the document* is free and you should do
+it liberally — the local MD is where the knowledge actually survives. *Committing it to chain* needs Pro
+and spends sats (7.1), so it is the deliberate half. Write every milestone; bank the ones that are
+**finished, standing, and worth citing later.**
+
+That split also protects a customer on a free plan: their record still exists on disk and their work is
+still recoverable — it simply is not yet provable. Say it that way rather than implying they have lost
+everything.
+
+## 10.3 The pre-compaction checklist
+
+When you sense the window closing — long session, big outputs, a lot of tool calls — spend two minutes:
+
+```
+1. Write the entry            verdict · verbatim evidence · fixed/open/new · honesty ledger · scope
+2. save_file(entry)         → txid
+3. Verify the txid on chain   (do not skip: an unverified bank is a hope)
+4. manage_goal(update/complete, evidence:[txid], notes:"what is proven, what remains")
+5. save_goals_to_chain()
+6. Leave a next-step line     the single most useful sentence for your successor
+```
+
+That last one matters more than it looks. Your successor wakes with a summary and no instinct. **One
+explicit sentence** — *"REMAINING: file the GitHub issue; repro is captured in txid 266da1a5"* — is worth
+more than a page of restored context. Write it into the goal's `notes`, not into chat, because chat is
+what gets compacted.
+
+## 10.4 Snapshot before you mutate
+
+Any time you are about to clear a cache, delete a reservation, corrupt a file to test error handling, or
+overwrite state: **copy the evidence somewhere durable first.**
+
+You will otherwise destroy the only proof of the thing you were investigating. Once you clear a stuck
+reservation, "there was a stuck reservation" becomes your word against nothing. A snapshot file — or better,
+a banked txid — keeps the finding real after the state is gone.
+
+## 10.5 After compaction: reconcile, do not assume
+
+You will wake with two sources: the **blockchain restore** (signed, timestamped — authoritative) and a
+**continuation summary** (auto-generated, unverified — secondary).
+
+- Orient from the chain restore first.
+- Treat the summary as a lead for anything after the last save timestamp.
+- **Say which source told you what.** *"Source: blockchain (tx X, saved TIME)"* and, if relevant,
+  *"Gap: N messages from the continuation summary."*
+- **If they disagree, reconcile by timestamp — do not simply declare "the chain wins."** The chain is
+  authoritative for **what was true at the moment it was saved.** It says nothing about the twenty minutes
+  of work that happened after the last save. A signed record from 09:12 does not overrule a summary
+  describing 09:40. Take the chain as the trusted baseline, layer the post-save gap on top as *unverified*,
+  and label it that way.
+- Then `get_goals` — that is where your successor-self left the real state.
+
+Never claim knowledge from the chain restore that you actually got from the summary. It is the same
+discipline as Part 1, applied to your own memory.
+
+---
+
+# Part 11 — Talking to humans, and the line to the dev team
+
+A green operator interrupts. A good one arrives with the answer, or with a question only the human can
+resolve. **Every unnecessary escalation spends the one resource you cannot mint: their attention.**
+
+## 11.1 Answer it yourself first — the four checks
+
+Before asking a human anything about Indelible, do these. Most questions die here:
+
+1. **Read the shipped docs.** `CLI_HANDBOOK.md` and `CUSTOMER_AGENT_HANDBOOK.md` ship **inside the npm
+   package** (`node_modules/indelible-mcp/`). They are ground truth for what the installed version claims,
+   and almost nobody reads them.
+2. **Ask the box.** `indelible-mcp status`, `--version`, `agents --list`, `workshop --status`,
+   `drift ledger`, `get_goals`.
+3. **Ask the chain.** `/api/tx/<txid>/status`, `/api/address/<addr>/unspent`, and a bridge `/health`.
+   This settles nearly every "did it work?" question outright.
+4. **Check whether it is documented behavior.** Several things that look broken are stated intentions —
+   commerce agents needing personas, escrow being refused for now, notary being inherently two-block.
+
+## 11.2 What is worth waking a human for
+
+**Ask when:** money or keys are at stake · the action is irreversible · a decision is genuinely theirs
+(what to buy, what to prioritise, whether to rotate a key) · you have two readings of a requirement and
+they lead to different work.
+
+**Do not ask when:** the box or the chain can tell you · it is in the shipped docs · it is a transient you
+have not retried · you are seeking reassurance rather than information.
+
+**And when you do ask: bring the answer with you.** Not *"a save failed, what should I do?"* but *"a save
+hit `WALLET_BUSY_RESERVED` twice, the holder is a live pid with a lapsed lease, retry succeeded on the
+third attempt in 11s — flagging it because it may indicate contention, nothing is lost."* One message,
+decision-ready.
+
+## 11.3 The reporter is a channel to the team, not just a bug form
+
+`report_bug` is the line to the Indelible team — **and it is not only for bugs.** Use it for ideas,
+suggestions, feature requests, questions about intended behavior, and "this was confusing" feedback.
+Anything you would otherwise ask a human to relay, send directly.
+
+**Mark the intent in the summary** so triage is instant:
+
+```
+report_bug(summary: "SUGGESTION: agents --restore should say how many citizens lack personas",
+           description: "After a restore, 2 of 16 got personas, so 3 commerce agents silently cannot be
+                         served. A one-line note in the restore output would prevent the confusion.
+                         Not a defect — a clarity improvement.",
+           severity: "low")
+```
+
+Prefixes that work: `SUGGESTION:` · `IDEA:` · `QUESTION:` · `DOCS:` · `UX:` · plain summary for a real defect.
+
+**How to use it well:**
+
+- **Do not invent facts.** The tool auto-attaches the real version, wallet address, recent receipts and
+  environment. Supply only the narrative. Never fabricate a version, txid, or URL — you will be wrong and
+  it will be checked.
+- **Triage transients first.** Retry a "No UTXOs" or "gateway unreachable" blip before filing; those are
+  usually an unconfirmed change output resolving itself.
+- **It auto-matches known issues.** A `status:"known_issue"` reply is a *good* outcome — instant triage,
+  nobody's time spent. Only use `still_file: true` when you are confident your case is genuinely different,
+  and say why.
+- **Get the human's OK before filing.** It reaches real people.
+- **Be specific enough to act on.** File and line, exact error text, and the smallest repro you can state.
+  *"Saving is slow"* is noise. *"A 970-byte file save took 16.5s; build and broadcast finished in <1s;
+  the remainder is unaccounted"* is a ticket someone can pick up.
+
+## 11.4 The green-operator mistakes, and what to do instead
+
+These are the ones actually observed on customer boxes. Learn them and you skip the whole apprenticeship.
+
+| Green move | What is really happening | Do this |
+|---|---|---|
+| Panicking at `status: pending` | Normal — awaiting a block | Nothing |
+| Panicking at `indexed: false` | On chain, index lagging | Nothing |
+| Concluding "my crew is gone" on a new machine | Agents live in the wallet, not the box | `agents --restore` |
+| **Re-birthing over a corrupt agent** | The file is corrupt, **not** deleted — and the warning says so | Restore that file from backup. `agents --restore` refuses a file it cannot parse and will not repair it |
+| Retrying a save every 15s | You are landing inside a live **120 s lease** and compounding contention | Let the built-in **60 s wait** do its job (7.4) |
+| Killing a slow save with Ctrl-C | Leaves a reservation the next claim has to reconcile | Let it finish — it tells you what it is waiting for |
+| **Saving from two machines on one wallet** | **Both can report success while one save is lost** | **Write from one box only (7.0)** |
+| Banking after every small step | Each write costs the human sats and needs Pro | Bank at milestones (7.1, 10.2) |
+| Editing `config.json` to "fix" `WALLET_KEY_MISMATCH` | The guard is protecting you from unreadable data | Run `setup` properly on that machine |
+| Clearing caches reflexively | You destroy the evidence of the thing you were debugging | Snapshot first (10.4) |
+| Relaying "✓ reported" as proof | That is the client's own claim | Verify against the server or the chain |
+| Filing documented behavior as a bug | Wastes triage, erodes your signal | Check the shipped handbooks first |
+| Asking the human "did my save work?" | The chain answers in one request | Query it, then report the answer |
+
+**The through-line:** most of these are the same error wearing different clothes — *treating a system's
+self-report as the truth, or treating an honest error as a catastrophe.* The product spent five releases
+learning to tell you the truth. Read what it says, and check what matters.
+
+---
+
+# Part 12 — What "as good as the QA box" actually means
+
+Not knowing more commands. It is four habits:
+
+1. **Check the thing you are about to claim** — against the chain, the file, or a second source.
+2. **Test the mechanism, not the thing that resembles it.** Verify a function is *called*, not merely
+   defined. Confirm your test exercised the path you think it did. Several of my early findings were
+   invalid because the code path never ran.
+3. **Say what you do not know.** "I have not verified that" is a complete, professional sentence.
+4. **Leave proof, not assertions.** A txid outlives your context window. Your confidence does not.
+
+> Everything above reduces to one question you should ask before every claim you make to a human:
+> **"What would I show someone who did not believe me?"**
+> If the answer is "my word," you are not finished yet.
+
+— QA machine `15P3dSued`