indelible-mcp 5.8.1 → 5.8.3

package/AI_OPERATORS_HANDBOOK.md

@@ -51,16 +51,13 @@ by adversarial review, not by re-reading my own work. That is the method working
 *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
+## 0.1 What `setup` actually does — and what bare `setup` does not
 
-`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:
+The shipped README describes this correctly: its Quick Start points at the wizard (bare `indelible-mcp`),
+and its command table calls `setup` *"Guided setup (recommended — your key is taken at a prompt, never
+written to shell history)"*, with the `--wif=`/`--pin=` form flagged for automation and carrying its own
+shell-history warning. The behavior underneath is still worth knowing, because bare `setup` — run with no
+key — will not configure anything. It returns:
 
 ```json
 {
@@ -72,9 +69,8 @@ indelible-mcp setup          # "generates a BSV keypair locally"
 ```
 
 - **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.
+  **imported** and encrypted!"*. The key comes **from indelible.one**, not from the package — the README
+  now says the same ("takes your private key … then registers your wallet with the Indelible server").
 - **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
@@ -137,12 +133,13 @@ verb: `recall_context` and `diary_recall` are **MCP-only** — there is no `inde
 `✗ 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:
+Two wiring details worth knowing:
 
-- 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.
+- The wizard registers with `claude mcp add --scope user …`, which writes `~/.claude.json`. If config is
+  managed by hand, the entry belongs in `~/.claude.json` or the project's `.mcp.json` — never
+  `settings.json`, which Claude Code does not read MCP servers from.
 - 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.**
+  directories. The docs and the code now agree — both include the flag and say why it matters.
 
 ---
 
@@ -175,9 +172,17 @@ outlives your context window and survives compaction, and that can be snapshotte
 `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.
+no txid; on a genuinely empty wallet it returns *"No UTXOs available. Fund your wallet."* — and since 5.8.x
+an underfunded save answers with a typed refusal instead: `INSUFFICIENT_FUNDS` names the exact need vs.
+what is spendable (a single payment of at least the named amount always suffices), `NO_ECONOMIC_COINS`
+means the wallet holds only dust (add funds in ONE normal-sized payment), `UNECONOMIC_FRAGMENTATION` means
+the wallet HAS enough but spread across too many small coins — the message itself says **do NOT add
+funds**, `TOO_MANY_INPUTS` / `TX_TOO_LARGE` mean the save cannot be built as one transaction (nothing was
+spent; TX_TOO_LARGE says split the content), and `WALLET_VIEW_DEGRADED` means the network's view of the
+wallet is incomplete (offline, or the index catching up) — **do not have the human add funds on that one;
+the message itself says so. Nothing was spent; retry in a few minutes.** Each of these has a row in the
+Part 6 table. 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.
@@ -386,6 +391,12 @@ Learn these and you will stop misreading normal behavior as breakage.
 | `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 |
+| `INSUFFICIENT_FUNDS` | The wallet holds less than this save needs — the message names both numbers. **Nothing was spent** | Fund the wallet — a single payment of at least the named amount always suffices |
+| `NO_ECONOMIC_COINS` | The wallet holds only dust — each coin costs more in fees than it adds. **Nothing was spent** | Add funds in **ONE normal-sized payment**; the small coins remain theirs, just unusable for now |
+| `UNECONOMIC_FRAGMENTATION` | Enough sats in total, but spread across so many small coins the fee would swamp the save. **Nothing was spent** | **Do NOT add funds** — they already have them, and more will not help. The message says to contact support (consolidation is not offered yet) |
+| `TOO_MANY_INPUTS` | The save would need more coins than the one-transaction signing limit. **Nothing was spent** | The message says to contact support |
+| `TX_TOO_LARGE` | The built transaction exceeds the network's byte envelope. **Nothing was spent** | Split the content into smaller saves |
+| `WALLET_VIEW_DEGRADED` | The network's view of the wallet is incomplete — offline, or the index catching up. **Nothing was spent** | **Do not have the human add funds on this message** — it forbids that itself. Retry in a few minutes |
 | `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 |
@@ -434,7 +445,7 @@ see another machine.**
 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.
+> *"…every hook runs 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.**"*
 
@@ -481,9 +492,12 @@ get the prompt. Do not fight that — it is the guardrail working.
 
 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.
+shell history)"*, both setup error messages lead with the wizard, and the README flags the `--wif=` form
+as automation-only with its own shell-history warning. Every shipped surface now steers to the wizard —
+`CLI_HANDBOOK.md` no longer teaches the flag form at all: its command reference lists `setup` as
+*"interactive; the safe path"*, and its troubleshooting table warns outright against passing a key on the
+command line (*"do NOT pass a key on the command line; shells record it"*). There is no longer an
+exception to treat as a doc bug.
 
 **So:**
 
@@ -742,6 +756,13 @@ The pre-compact hook fires and saves the session automatically. **Do not rely on
 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.
 
+A second hook fires at the same moment — the **strongbox** (5.7.4) — and again at session end. It keeps a
+verified local byte-copy of the raw transcript in `~/.indelible/transcript-vault/`, because the host
+deletes raw session files after roughly 30 days by default. `indelible-mcp strongbox` lists what is
+protected; `indelible-mcp strongbox run` protects the current session now (it never guesses — if more
+than one transcript matches, pass `--session <id>`). It is local-only and free — the chain save is the
+provable record, the strongbox is the raw material.
+
 Auto-save is your seatbelt. The daily MD is your actually-arriving-somewhere.
 
 ## 10.2 Bank at milestones, not at the end

package/CLI_HANDBOOK.md

@@ -23,7 +23,7 @@ You don't have to memorize any of this. In Claude Code you can just say what you
 | `indelible-mcp vault load-file <txid>` | Gets it back, anywhere, forever. |
 | `indelible-mcp diary chat "hello"` | Talks to your diary companion. |
 
-Three things worth knowing, once: **your key stays on your machine** (nothing we run ever sees it) · **reading is always free** (saves cost fractions of a cent in Bitcoin fees) · **your stop button beats everything** (pause works even with no wallet at all).
+Three things worth knowing, once: **you hold your key** (it lives in `~/.indelible/config.json` on your machine — back that file up) · **reading is always free** (saves cost fractions of a cent in Bitcoin fees) · **your stop button beats everything** (pause works even with no wallet at all).
 
 ## Honest Receipts + the Wallet (5.7.0)
 
@@ -55,7 +55,7 @@ your machine picks the new setting up automatically.
 
 Indelible works with Claude Code, with OpenAI's Codex CLI, or with both at once on the same memory.
 
-- **Claude Code:** `claude mcp add indelible -- indelible-mcp`
+- **Claude Code:** `claude mcp add --scope user indelible -- indelible-mcp` (`--scope user` registers it for every project, not just the folder you ran it from)
 - **Codex CLI:** add to `~/.codex/config.toml` and restart Codex:
 
   ```toml
@@ -210,7 +210,7 @@ status                       Show wallet address, API key, last session
 
 ### Code Vault
 ```
-vault save-file <path>                        Save a file (encrypted, chunked if >50KB)
+vault save-file <path>                        Save a file (encrypted; one transaction up to ~10MB, chunked above that)
 vault save-project <dir> [--name=NAME]        Save a project directory
 vault load-file <txid> [--output=path]        Load a file from blockchain
 vault load-project <txid> [--output-dir=dir]  Load a project from blockchain
@@ -221,7 +221,7 @@ vault update-index                            Update on-chain vault index
 
 ### Diary AI (Dual-Agent)
 ```
-diary connect --key=SK [--model=MODEL] [--name=NAME]  Connect OpenAI companion
+diary connect --key=KEY [--model=MODEL] [--name=NAME]  Upgrade the model: xAI Grok (xai-...) or OpenAI (sk-...)
 diary chat "message"                                   Ask the AI companion
 diary save [--summary="..."]                           Save exchange to blockchain
 ```
@@ -229,7 +229,7 @@ diary save [--summary="..."]                           Save exchange to blockcha
 ### Setup & Hooks
 ```
 setup                        Set up your wallet (interactive; the safe path)
-install-hooks                Install auto-save/restore hooks into Claude Code
+install-hooks                Install the Indelible hooks into Claude Code: auto-save before compaction, auto-restore after, your saved style at session start, the credential/destructive-command guard, the Strongbox transcript copies, and a per-turn clock stamp (the wristwatch, in your own timezone)
 hook pre-compact             Auto-save before compaction (called by hook)
 hook post-compact            Auto-restore after compaction (called by hook)
 ```
@@ -251,7 +251,7 @@ The CLI and MCP server are the **same codebase**. They import the same tool func
 |---|---|---|
 | **Location** | `(published package)` | `(core source)` |
 | **Config** | Sync (`readFileSync`/`writeFileSync`) | Async (`await loadConfig()`) |
-| **Fetch** | Native `fetch` (Node 18+) | `node-fetch` package |
+| **Fetch** | Native `fetch` (Node 18+) | Native `fetch` (Node 18+) |
 | **Timeout** | `AbortSignal.timeout(ms)` | Manual `AbortController` + `setTimeout` |
 | **Entry point** | CLI arg parser in `index.js` | JSON-RPC stdin/stdout in `index.js` |
 | **How Claude calls it** | `node src/index.js <command>` | MCP protocol via Claude Code hooks |
@@ -274,28 +274,9 @@ indelible-mcp load --sessions=1
 indelible-mcp vault load-style
 ```
 
-### Function-level tests (no sats spent)
-```bash
-cd /path/to/indelible-cli && node --input-type=module -e "
-import { checkConfirmation } from './src/lib/spv.js';
-const r = await checkConfirmation('TXID_HERE');
-console.log(JSON.stringify(r, null, 2));
-" 2>&1
-
-cd /path/to/indelible-cli && node --input-type=module -e "
-import { checkTier } from './src/lib/api-client.js';
-import { loadConfig } from './src/lib/config.js';
-const config = loadConfig();
-const r = await checkTier(config.api_key);
-console.log(JSON.stringify(r, null, 2));
-" 2>&1
-
-cd /path/to/indelible-cli && node --input-type=module -e "
-import { verifyRecentSaves } from './src/tools/save_file.js';
-const r = await verifyRecentSaves();
-console.log(JSON.stringify(r, null, 2));
-" 2>&1
-```
+(Function-level imports are not possible against the installed package — `src/` ships one
+self-contained bundle, so `./src/lib/*` and `./src/tools/*` do not exist. Confirmation
+checking happens automatically inside every save: committed means mined, since 5.7.0.)
 
 ### Live tests (spends sats)
 ```bash
@@ -305,10 +286,10 @@ indelible-mcp save --summary "test save"
 # File save
 indelible-mcp vault save-file /path/to/small/file.txt
 
-# Style save (auto-prepends core rules via ensureCoreRules)
+# Style save (strips core rules via stripCoreRules; load re-injects the current version's via prependCoreRules)
 indelible-mcp vault save-style /path/to/rules.txt --name=test
 
-# Diary chat (costs OpenAI tokens, not sats)
+# Diary chat (costs provider tokens — Groq is free, xAI/OpenAI are BYOK — not sats)
 indelible-mcp diary chat "hello"
 ```
 
@@ -316,39 +297,9 @@ indelible-mcp diary chat "hello"
 
 ## Architecture
 
-```
-indelible-cli/src/
-├── index.js                    CLI arg parser + MCP JSON-RPC server (dual mode)
-├── lib/
-│   ├── config.js               Sync config: loadConfig(), saveConfig(), getWif()
-│   ├── crypto.js               AES-256-GCM encrypt/decrypt, SHA-256, WIF derivation
-│   ├── spv.js                  Multi-bridge SPV client, UTXO chaining, health tracking
-│   └── api-client.js           commitSession(), getLatestSessions(), checkTier()
-├── tools/
-│   ├── save_session.js         Parse transcript, delta detect, encrypt, broadcast
-│   │                           + getRecentPlans() — scans ~/.claude/plans/
-│   │                           + updateMemory() — MEMORY.md hierarchy enforcement
-│   │                           + dashboard sync — PATCH to indelible.one
-│   ├── load_context.js         Fetch + decrypt + merge deltas + smart format
-│   ├── setup_wallet.js         Set up the wallet, encrypt the key with your PIN
-│   ├── save_file.js            Encrypt + broadcast file (chunked if >50KB)
-│   │                           + cacheTx() — local backup for re-broadcast
-│   │                           + verifyRecentSaves() — check confirmations
-│   ├── save_project.js         Walk dir + save each file + broadcast manifest
-│   │                           + cacheTx() — local backup for re-broadcast
-│   ├── load_file.js            Fetch + decrypt file from blockchain
-│   ├── load_project.js         Fetch manifest + decrypt + restore files
-│   ├── save_style.js           Encrypt style rules + broadcast
-│   │                           + ensureCoreRules() — auto-prepend core rules
-│   ├── load_style.js           Fetch + decrypt style from blockchain
-│   ├── update_vault_index.js   Update on-chain file/project index
-│   ├── diary_connect.js        Store OpenAI API key in config
-│   ├── diary_chat.js           Send message to Codex via OpenAI API
-│   │                           + blockchain history loading (last 3 sessions)
-│   └── diary_save.js           Save diary exchange to blockchain
-└── dist/
-    └── indelible.exe           Compiled standalone (bun build --compile)
-```
+`indelible-cli/src/index.js` — the whole CLI + MCP server, pressed into one self-contained bundle from the Indelible core (arg parser, MCP JSON-RPC dispatch, wallet/config, crypto, SPV client, and all tools). That single file is what the npm package installs (the `files` field ships only `src/` plus the handbooks); per-feature detail lives in the Key Internal Features table below, not in a file map.
+
+Standalone executables for Windows, Linux, and macOS (`indelible.exe`, `indelible-win-x64.exe`, `indelible-linux-x64`, `indelible-darwin-arm64`) are built into the repo's `dist/` via the "Rebuild the Executable" section below and distributed separately from the npm install.
 
 ### Key Internal Features
 
@@ -359,8 +310,8 @@ indelible-cli/src/
 | **Delta saves** | Only commits new messages since last save |
 | **tx-cache** | Caches broadcast payloads to `~/.indelible/tx-cache/` for re-broadcast |
 | **MEMORY.md enforcement** | Strips rules, archives done items, enforces 200-line / 20-line limits |
-| **Core rules injection** | `ensureCoreRules()` auto-prepends infrastructure rules to every style |
-| **Diary history** | `diary chat` loads last 3 blockchain sessions for conversation continuity |
+| **Core rules injection** | Core rules are stripped at save (`stripCoreRules()`) so the stored style is pure user content; `prependCoreRules()` injects the current version's infrastructure rules at every load — updating the package updates the rules |
+| **Diary history** | `diary chat` recalls your prior Duo rounds from the chain (up to 10, within a token budget) for conversation continuity |
 | **Dashboard sync** | PATCHes indelible.one after every save |
 
 ---
@@ -381,13 +332,16 @@ This creates a standalone `indelible.exe` — no Node.js required on the target
 |-------|-------|-----|
 | `Wallet not configured` | No config.json or no WIF | Run `setup` (interactive — do NOT pass a key on the command line; shells record it) |
 | `No UTXOs available` | Wallet is empty | Send BSV to your address |
-| `Broadcast failed on all bridges` | All 7 SPV relays down or rejecting | Check relay health, wait and retry |
+| `WALLET_VIEW_DEGRADED` | The network view of your wallet is offline or incomplete (the message says which: bridges unreachable, or the index catching up) | Retry in a few minutes. Do NOT add funds based on this message — your wallet may hold more than is currently visible; nothing was spent |
+| `INSUFFICIENT_FUNDS` | Spendable coins cannot cover this save (the message names the sats needed; some sats may be temporarily reserved by another agent on this box) | Fund your wallet — a single payment of at least the stated amount always suffices; reserved sats free up shortly |
+| `TOO_MANY_INPUTS` | The save would need more coins than the per-transaction signing limit (rare: heavily fragmented wallets) | Nothing was spent — contact support at indeliblebsv@gmail.com and mention TOO_MANY_INPUTS |
+| `Bridge broadcast failed — all N bridges down` | All SPV relays (7 by default) down or rejecting | Check relay health, wait and retry |
 | `No new messages since last save` | Already saved this transcript | Nothing to do — this is fine |
 | `File not found` | Bad path or backslashes | Use forward slashes: `C:/path/to/file` |
 | `Decrypt failed` | Wrong WIF or tampered data | Check `~/.indelible/config.json` has correct WIF |
 | `txn-mempool-conflict` | Spending already-spent UTXO | UTXO chaining should prevent this — check code |
-| `OpenAI rate limit exceeded` | Too many diary chat calls | Wait a moment and retry |
-| `Diary AI not configured` | No OpenAI key | Run `diary connect --key=SK` |
+| `<provider> rate limit exceeded` | Too many diary chat calls (the message names the provider: Groq, xAI Grok, or OpenAI) | Wait a moment and retry |
+| `Diary AI needs a companion model` | No companion key connected on this box (the keyless free Groq companion lives at indelible.one, not in the CLI) | Use the free companion at indelible.one, or upgrade here with `diary connect --key=...` using an xAI (`xai-...`) or OpenAI (`sk-...`) key — Groq (`gsk_`) keys are refused since Groq is already the free default |
 
 ---
 
@@ -402,22 +356,22 @@ This creates a standalone `indelible.exe` — no Node.js required on the target
 | `spv_bridges` | Array of `{url, name}` relay objects |
 | `api_url` | Indelible web app URL (`https://indelible.one`) |
 | `api_key` | API key for authenticated endpoints |
-| `auto_delta` | Auto-save every N messages (bool) |
-| `auto_delta_interval` | Messages between auto-saves (default: 10) |
+| `auto_delta` | Auto-save on/off (bool) |
+| `auto_delta_interval` | Minutes between auto-saves (default: 15, clamped 1–240) |
 | `file_txids` | *(auto)* Index of files saved to chain |
 | `project_txids` | *(auto)* Index of projects saved to chain |
 | `last_session_id` | *(auto)* Previous session for chaining |
 | `last_tx_id` | *(auto)* Last committed tx |
-| `diary` | `{ apiKey, model, name }` — OpenAI companion config |
+| `diary` | `{ apiKey, provider, model, name }` — companion config (xAI `xai-...` or OpenAI `sk-...` key; Groq is the keyless free default) |
 
 ---
 
 ## Wallet
 
-- **Address:** shown by `indelible-mcp status` (yours is generated at setup and lives in `~/.indelible/config.json` — back that file up)
+- **Address:** shown by `indelible-mcp status` (yours is created at setup — or imported, if you brought your own key — and lives in `~/.indelible/config.json`; back that file up)
 - **Balance:** `indelible-mcp status`, or look your address up in the Chain Browser at indelible.one/explorer
 - **Fund it:** Send BSV to your own address
-- **Cost:** ~$0.21/MB at BSV=$16. Session saves are fractions of a cent.
+- **Cost:** ~$0.03/MB at BSV=$16 (the fee floor is 150 satoshis per kilobyte). Session saves are fractions of a cent.
 
 ---
 

package/CUSTOMER_AGENT_HANDBOOK.md

@@ -32,6 +32,7 @@ Grouped by what they cost:
 - **Inner state (free, local):** `get_inner_state`, `update_inner_state`
 - **Starter recipes (free):** `list_agent_recipes` — eight ready-made blueprints you can hire instead of writing one from a blank page: a copy chief, a researcher, a deal reviewer, a code critic, a devil's advocate, a marshal, a ledger clerk, a negotiator. Birth any of them with `birth_custom_agent` and `recipe: '<id>'`. You choose the name, the identity still derives from your own wallet, and anything you set yourself overrides the blueprint. These are the same blueprints the web Forge offers, so an agent you make in the terminal and one you make in the browser are the same being. (Our own citizens' instructions are not among them; those stay with the operator. What travels is a recipe, never a key.)
 - **Your own agents (free, local):** `birth_custom_agent` — create an agent of your own: name it, pick the kind of work it handles, write its instructions. Its identity derives from your wallet, so it is recoverable from that wallet forever and is never random. · `run_custom_agent` — run one and get back advice signed with that agent's own key, so anyone can verify which agent said it. · `convene_chamber` — put three of your agents in a room to decide something: one proposes, one argues against, a third rules, and each signs its own position. · `transmute_agents` — blend two of your agents into a third. Keys never mix; only the written instructions combine.
+- **Sharing:** `share_session` (send one of your saved sessions to another address — Pro, it is a real on-chain write) · `load_shared` (read what someone shared with you — free)
 - **Everything else:** `x402_fetch` (pays real sats to paid endpoints, capped at 10,000 sats per request unless you raise it), `report_bug`
 
 One important nuance on "free": free means no subscription. On-chain writes still cost miner fees, paid in sats from your own wallet. Each save costs less than a cent. Diary and Duo saves are not Pro-gated; they only need a few sats in the wallet.
@@ -40,21 +41,29 @@ One important nuance on "free": free means no subscription. On-chain writes stil
 
 ## 2. What fires automatically (the hooks)
 
-When you ran setup, the installer wired **six hooks across four events** into Claude Code, in
-`~/.claude/settings.json`: two on PreCompact, two on SessionStart, one on PreToolUse, and one on
-SessionEnd. (`settings.local.json` is the older location the installer migrates *from*.) You can
+When you ran setup, the installer wired **seven hooks across five events** into Claude Code, in
+`~/.claude/settings.json`: two on PreCompact, two on SessionStart, one on PreToolUse, one on
+SessionEnd, and one on UserPromptSubmit — the wristwatch, which stamps the real clock (in your
+system timezone) onto every turn so your AI always knows what time it is.
+(`settings.local.json` is the older location the installer migrates *from*.) You can
 see exactly what is installed at any time with `indelible-mcp install-hooks`, which prints the
-full inventory of every hook it manages before it writes anything. This is what each one does and
-why it is there.
+full inventory of every hook it manages. (Note it is an installer, not a viewer: running it writes
+settings.json and re-adds any Indelible hook that is missing, including one you deliberately
+removed.) This is what each one does and why it is there.
 
 | Hook | Fires | Does |
 |---|---|---|
 | **PreCompact** | Right before Claude Code compacts (summarizes away) your conversation | Saves the new messages of your real transcript to the chain, so nothing is lost to compaction. On success you see a line like `Indelible: Saved 42 messages (delta) tx:a1b2c3d4e5f6...` |
+| **PreCompact (strongbox)** | Right before a compaction | Keeps a verified, byte-exact local copy of your raw transcript in `~/.indelible/transcript-vault/` (see below) |
 | **SessionStart (after compaction)** | Right after a compaction | Restamps the time card (compaction resets the model's sense of time), reloads your saved AI style, and restores your recent sessions from chain so Claude picks up where it left off |
 | **SessionStart** | At the start of every new session | Prints the time card and loads your on-chain AI style rules, if you saved one |
 | **PreToolUse (Bash)** | Before any shell command your AI runs | Runs the Guardrails check: blocks a command that would leak your wallet key, warns on irreversible commands |
+| **SessionEnd (strongbox)** | When a session ends | Takes the same verified local transcript copy at session end, so the strongbox holds the whole session |
+| **UserPromptSubmit (wristwatch)** | On every prompt you submit | Stamps the real clock, in your system timezone, onto the turn so your AI always knows what time it is |
 
-Free tier and the hooks: 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. Your reads, diary, and recall keep working.
+**PreCompact (strongbox)** and **SessionEnd (strongbox)** keep a verified, byte-exact local copy of your raw transcript in `~/.indelible/transcript-vault/` before your host's own cleanup (~30 days by default) can delete it. That is the strongbox: your transcript's local vault, separate from the chain save — free, local, no wallet needed. `indelible-mcp strongbox` shows what it holds; `indelible-mcp strongbox run` protects the current session on demand.
+
+Free tier and the hooks: every hook runs 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. Your reads, diary, and recall keep working.
 
 Hook installation is idempotent. If you ever suspect the hooks are missing, run:
 
@@ -98,7 +107,7 @@ The part after the code is the reason in plain words. The code itself is the par
 | `junk_filename` | Looks like junk (`.DS_Store`, `*.tmp`, swap files) | Warning only |
 | `large_file` | Over 10 MB: many chunks, real cost | Warning only |
 
-"Observed by default" means the verdict is logged to `~/.indelible/witness/` but the save proceeds, unless you turn enforcement on (below).
+"Observed by default" means the Witness reports the verdict as a `[Witness] WOULD BLOCK ...` warning line in the server log (the same place you see `[Witness] BLOCKED ...` lines) but the save proceeds, unless you turn enforcement on (below).
 
 The two hard-block codes are different. `credential_in_content` and `secret_filename` block **regardless of any setting**, because permanent is forever. A leaked key on an immutable public chain cannot be taken back. The Witness would rather fail your save than etch your key.
 
@@ -348,7 +357,10 @@ You are on the free tier. Reads, diary, Duo, and recall all keep working. To kee
 The billing check could not reach indelible.one. Saves fail closed on purpose when your plan cannot be verified. Check your connection and retry.
 
 **"No funds" / "fund to persist"**
-Your wallet has no sats. Chain writes carry a real (tiny) miner fee. Send a small amount of BSV to your address (`indelible-mcp status` shows it). Even one dollar covers hundreds of saves. Duo replies still work with an empty wallet; they just are not persisted until you fund.
+Your wallet has no sats. Chain writes carry a real (tiny) miner fee. Send a small amount of BSV to your address (`indelible-mcp status` shows it). Even one dollar covers hundreds of saves. Duo replies still work with an empty wallet; they just are not persisted until you fund. If the message instead says the network's view of your wallet is incomplete, see the next entry — do not send funds for that one.
+
+**"The network's view of your wallet is temporarily incomplete" / "Cannot reach the network to see your full wallet right now"**
+This is not "no funds" — it is a degraded VIEW. The coins currently visible cannot fund this save, but your wallet may hold more that is not visible yet (the index is catching up, or the bridges are unreachable). Nothing was spent. Retry in a few minutes — do not add funds based on this message; the message itself says so, and adding funds it did not ask for solves nothing. If it persists, check your connection and `indelible-mcp status`.
 
 **Restore comes back empty**
 Work the checklist in order:

package/LICENSE

@@ -15,7 +15,7 @@ Additional Use Grant: You may make use of the Licensed Work for personal,
                       commercial blockchain storage, session saving, or
                       encrypted vault service without written permission
                       from the Licensor.
-Change Date:          August 18, 2030
+Change Date:          August 19, 2030
 Change License:       MIT License
 
 Terms

package/README.md

@@ -12,27 +12,29 @@ Blockchain-backed memory for Claude Code **and OpenAI's Codex CLI**. Save your A
 
 ```bash
 npm install -g indelible-mcp
-indelible-mcp setup
+indelible-mcp
 ```
 
 ## Setup
 
-### 1. Install & Create Wallet
+### 1. Install & Connect Your Wallet
+
+Create your account at [indelible.one](https://indelible.one) first (Pro unlocks saves), then:
 
 ```bash
 npm install -g indelible-mcp
-indelible-mcp setup
+indelible-mcp
 ```
 
-This sets up your wallet and registers it with the Indelible server.
+Run `indelible-mcp` with no arguments — the wizard takes your private key (indelible.one → Settings → Private Key) and a PIN at a prompt, then registers your wallet with the Indelible server. For automation: `indelible-mcp setup --wif=YOUR_KEY --pin=YOUR_PIN` (clear your shell history afterward).
 
 ### 2. Fund Your Wallet
 
-Send a small amount of BSV to the address shown after setup. Any BSV wallet works (HandCash, RelayX, etc.).
+Send a small amount of BSV to the address shown after setup. HandCash or RockWallet both work.
 
 ### 3. Add MCP Config to Claude Code
 
-Run `indelible-mcp --show-config` to get your config, or add this to your Claude Code `settings.json`:
+Run `claude mcp add --scope user indelible -- indelible-mcp` (`--scope user` registers it for every project, not just the current folder — the setup wizard runs this for you). If you manage MCP config by hand, the entry below goes in `~/.claude.json` (user scope) or your project's `.mcp.json` — NOT in `settings.json`, which Claude Code does not read MCP servers from:
 
 ```json
 {
@@ -72,7 +74,10 @@ Indelible automatically saves before Claude Code compacts your context, and rest
 ### CLI Commands
 
 ```
-indelible-mcp setup              Generate wallet & register
+indelible-mcp                    Guided setup (recommended — your key is taken at a prompt,
+                                 never written to shell history)
+indelible-mcp setup --wif=KEY --pin=PIN   Import your key & register — automation only;
+                                 both values land in shell history
 indelible-mcp save               Save current session
 indelible-mcp save --summary XYZ Save with custom summary
 indelible-mcp strongbox          See your protected raw transcripts (the host deletes them ~30 days by default)
@@ -113,7 +118,7 @@ indelible-mcp workshop --status  Which of your agents this box can serve right n
 ## How It Works
 
 1. Your conversation is encrypted locally with your WIF key
-2. A minimal OP_RETURN transaction is built containing only `{protocol, encrypted}` — no metadata leaks
+2. A minimal OP_RETURN transaction is built containing only `{protocol, encrypted, wrap_owner}` — the protocol tag, your encrypted conversation, and an encrypted key-wrap that lets you share the session later. No plaintext metadata on-chain
 3. The signed transaction is broadcast via Indelible's federation bridges
 4. Session metadata is automatically indexed across all federation bridges for fast retrieval
 5. Signing happens locally on your machine
@@ -129,7 +134,7 @@ The federation mesh is powered by [Relay Federation](https://github.com/zcoolz/r
 ## Security
 
 - **Zero-knowledge encryption** - your WIF-derived AES-256-GCM key encrypts all data before it touches the network
-- **Privacy-hardened transactions** - OP_RETURN contains only `{protocol, encrypted}` — no plaintext metadata on-chain
+- **Privacy-hardened transactions** - OP_RETURN carries only the protocol tag, ciphertext, and an encrypted key-wrap — no plaintext metadata on-chain
 - **You hold your key** - the wallet that signs and encrypts your data is yours
 - **Immutable storage** - once on BSV, your data cannot be altered or deleted
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indelible-mcp",
-  "version": "5.8.1",
+  "version": "5.8.3",
   "description": "Blockchain-backed memory and code storage for Claude Code. Save AI conversations and source code permanently on BSV.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -1025,7 +1025,8 @@ function claimRefusalMessage(claim2) {
   if (r === "WALLET_VIEW_DEGRADED") {
     const seen = Number.isFinite(claim2.visibleSats) ? `${claim2.visibleSats} sats` : "the coins known locally";
     const needs = Number.isFinite(claim2.need) ? ` (needs about ${claim2.need} sats)` : "";
-    return `Cannot reach the network to see your full wallet right now. The locally-known coins (${seen}) cannot fund this save${needs}, but your wallet may hold more that is not visible offline. Nothing was spent. Retry when the connection recovers \u2014 do not add funds based on this message.`;
+    const opener = claim2.operator_reason === "INDEX_PARTIAL" ? "The network's view of your wallet is temporarily incomplete (the index is catching up)." : "Cannot reach the network to see your full wallet right now.";
+    return `${opener} The currently-visible coins (${seen}) cannot fund this save${needs}, but your wallet may hold more that is not visible yet. Nothing was spent. Retry in a few minutes \u2014 do not add funds based on this message.`;
   }
   if (r === "NO_COINS") return "No UTXOs available. Fund your wallet.";
   return "No UTXOs available. Fund your wallet.";
@@ -1100,11 +1101,13 @@ async function claimSpendableUtxos(address, bridgeFallback, opts = {}) {
       }
     }
     let _bridgeDegraded = false;
+    let _bridgePartial = null;
     const bridgeView = async () => {
       if (!bridgeFallback) return [];
       try {
         const v = await bridgeFallback(address);
         _bridgeDegraded = false;
+        _bridgePartial = v?.coverage?.known && v.coverage.partial ? v.coverage : null;
         return v;
       } catch {
         _bridgeDegraded = true;
@@ -1121,6 +1124,17 @@ async function claimSpendableUtxos(address, bridgeFallback, opts = {}) {
     } else {
       candidates = unionCandidates(address, await bridgeView());
     }
+    if (_phase === "union" && candidates.length === 0 && (_bridgeDegraded || _bridgePartial)) {
+      return {
+        refused: true,
+        reason: "WALLET_VIEW_DEGRADED",
+        operator_reason: _bridgeDegraded ? "BRIDGE_UNREACHABLE" : "INDEX_PARTIAL",
+        ..._bridgePartial ? { index_holes: _bridgePartial.holes, index_source: _bridgePartial.source } : {},
+        underlying: "NO_COINS",
+        visibleSats: 0,
+        reservedSats: 0
+      };
+    }
     const claimed = await withFileLock(LOCK_PATH, async () => {
       const store = readReservations();
       releaseDeadPreSign(store, now);
@@ -1137,8 +1151,17 @@ async function claimSpendableUtxos(address, bridgeFallback, opts = {}) {
         if (wholeWallet.ok) return { busy: true };
         const { ok: _ok, ...evidence } = selected;
         const reservedSats = (candidates || []).filter((u) => reserved.has(inputKey(u))).reduce((s, u) => s + (u?.value || 0), 0);
-        if (_bridgeDegraded && evidence.reason !== "TX_TOO_LARGE") {
-          return { refused: true, reason: "WALLET_VIEW_DEGRADED", underlying: evidence.reason, need: evidence.need, visibleSats: evidence.available, reservedSats };
+        if ((_bridgeDegraded || _bridgePartial) && evidence.reason !== "TX_TOO_LARGE") {
+          return {
+            refused: true,
+            reason: "WALLET_VIEW_DEGRADED",
+            operator_reason: _bridgeDegraded ? "BRIDGE_UNREACHABLE" : "INDEX_PARTIAL",
+            ..._bridgePartial ? { index_holes: _bridgePartial.holes, index_source: _bridgePartial.source } : {},
+            underlying: evidence.reason,
+            need: evidence.need,
+            visibleSats: evidence.available,
+            reservedSats
+          };
         }
         return { refused: true, ...evidence, reservedSats };
       }
@@ -1597,14 +1620,27 @@ async function checkHealth() {
     return false;
   }
 }
+function coverageFromHeaders(headers) {
+  try {
+    const src = headers?.get?.("x-utxo-source") || null;
+    const holesRaw = headers?.get?.("x-utxo-holes");
+    if (src === null && (holesRaw === null || holesRaw === void 0)) return { known: false, partial: false, source: null, holes: 0 };
+    const holes = Number.parseInt(holesRaw || "0", 10) || 0;
+    const partial = holes > 0 || /partial/i.test(src || "");
+    return { known: true, partial, source: src, holes };
+  } catch {
+    return { known: false, partial: false, source: null, holes: 0 };
+  }
+}
 async function getUtxos(address) {
   const path = `/api/address/${address}/unspent`;
   const res = await spvFetch(path);
   const first = await res.json();
+  const firstCoverage = coverageFromHeaders(res.headers);
   if (Array.isArray(first) && first.length > 0) {
     process.stderr.write(`[MCP] UTXOs from bridge: ${first.length}
 `);
-    return first;
+    return withCoverage(first, firstCoverage);
   }
   let reached = 0;
   try {
@@ -1615,8 +1651,9 @@ async function getUtxos(address) {
         headers: { "X-API-Key": bridge.apiKey }
       });
       if (!r.ok) throw new Error(`HTTP ${r.status}`);
-      return { name: bridge.name, utxos: await r.json() };
+      return { name: bridge.name, utxos: await r.json(), coverage: coverageFromHeaders(r.headers) };
     }));
+    let anyPartial = null;
     for (const s of settled) {
       if (s.status !== "fulfilled") continue;
       reached++;
@@ -1624,8 +1661,14 @@ async function getUtxos(address) {
       if (Array.isArray(u) && u.length > 0) {
         process.stderr.write(`[MCP] UTXOs recovered via fan-out from ${s.value.name}: ${u.length}
 `);
-        return u;
+        return withCoverage(u, s.value.coverage);
       }
+      if (s.value.coverage?.known && s.value.coverage.partial) anyPartial = s.value.coverage;
+    }
+    if (anyPartial) {
+      process.stderr.write(`[MCP] UTXOs: 0 across ${reached} bridge(s), but a bridge reports a PARTIAL index (holes=${anyPartial.holes})
+`);
+      return withCoverage([], anyPartial);
     }
   } catch (e) {
     process.stderr.write(`[MCP] UTXO fan-out error: ${e.message}
@@ -1633,7 +1676,7 @@ async function getUtxos(address) {
   }
   process.stderr.write(`[MCP] UTXOs: 0 across ${reached} bridge(s)
 `);
-  return Array.isArray(first) ? first : [];
+  return withCoverage(Array.isArray(first) ? first : [], firstCoverage);
 }
 async function getAddressHistory(address) {
   const res = await spvFetch(`/api/address/${address}/history`);
@@ -2169,7 +2212,7 @@ function extractEncryptedFromTx(tx) {
   const match = str.match(/([A-Za-z0-9+/=]{12,}):([A-Za-z0-9+/=]{20,}):([A-Za-z0-9+/=]{20,})/);
   return match ? match[0] : null;
 }
-var SEED_BRIDGES, OLD_BRIDGE_IPS, bridgeHealth, HEALTH_CHECK_INTERVAL, MAX_FAILURES, migrationDone, SOURCE_FETCH_CONCURRENCY, ARC_NETWORK_STATUSES, StoredError, _stickyBridge, STICKY_WINDOW_MS;
+var SEED_BRIDGES, OLD_BRIDGE_IPS, bridgeHealth, HEALTH_CHECK_INTERVAL, MAX_FAILURES, migrationDone, withCoverage, SOURCE_FETCH_CONCURRENCY, ARC_NETWORK_STATUSES, StoredError, _stickyBridge, STICKY_WINDOW_MS;
 var init_spv = __esm({
   "mcp-server/lib/spv.js"() {
     init_config_customer();
@@ -2196,6 +2239,13 @@ var init_spv = __esm({
     HEALTH_CHECK_INTERVAL = 6e4;
     MAX_FAILURES = 3;
     migrationDone = false;
+    withCoverage = (utxos, coverage) => {
+      try {
+        Object.defineProperty(utxos, "coverage", { value: coverage, enumerable: false });
+      } catch {
+      }
+      return utxos;
+    };
     SOURCE_FETCH_CONCURRENCY = 8;
     ARC_NETWORK_STATUSES = /* @__PURE__ */ new Set([
       // Tightened 2026-06-17 to match the relay-federation bridge: a node must have
@@ -16058,6 +16108,11 @@ function installHooks() {
     settings.hooks.SessionEnd.push({ hooks: [{ type: "command", command: sbCmd("session-end-strongbox") }] });
     installed.push("SessionEnd:strongbox");
   }
+  if (!hasSb("UserPromptSubmit", "user-prompt-timestamp")) {
+    if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+    settings.hooks.UserPromptSubmit.push({ hooks: [{ type: "command", command: sbCmd("user-prompt-timestamp") }] });
+    installed.push("UserPromptSubmit:wristwatch");
+  }
   writeFileSync18(settingsPath, JSON.stringify(settings, null, 2));
   const inventory = [];
   for (const [event, entries] of Object.entries(settings.hooks || {})) {
@@ -17454,7 +17509,7 @@ Answer THAT message and nothing else \u2014 the wire also carries unrelated conv
 }
 function printHelp() {
   console.log(`
-Indelible MCP \u2014 Blockchain memory for Claude Code (v5.8.1)
+Indelible MCP \u2014 Blockchain memory for Claude Code (v5.8.3)
 
 Setup:
   indelible-mcp                              Set up interactively (recommended \u2014 your key is never written to shell history)
@@ -17783,7 +17838,7 @@ function readStdin() {
 }
 var SERVER_INFO = {
   name: "indelible",
-  version: "5.8.1",
+  version: "5.8.3",
   description: "Blockchain-backed memory and code storage for Claude Code"
 };
 var TOOLS = [
@@ -18915,6 +18970,25 @@ if (args[0] === "hook") {
       }
       process.exit(0);
     })();
+  } else if (args[1] === "user-prompt-timestamp") {
+    try {
+      const stamp = (/* @__PURE__ */ new Date()).toLocaleString(void 0, {
+        weekday: "long",
+        month: "long",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true
+      });
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "UserPromptSubmit",
+          additionalContext: `\u231A NOW: ${stamp} (your machine's clock, verified this turn \u2014 never infer time)`
+        }
+      }));
+    } catch {
+    }
+    process.exit(0);
   } else if (args[1] === "pre-tool-use") {
     runPreToolUseGuard();
   } else if (args[1] === "pre-compact-strongbox" || args[1] === "session-end-strongbox") {
@@ -18957,7 +19031,13 @@ if (args[0] === "hook") {
   printHelp();
 } else if (args[0] === "--show-config") {
   console.log(`
-Add this to your Claude Code settings.json:
+Easiest: run this once and you're registered in every project:
+
+  claude mcp add --scope user indelible -- indelible-mcp
+
+Managing MCP config by hand instead? This entry goes in ~/.claude.json (user scope)
+or your project's .mcp.json \u2014 NOT in settings.json, which Claude Code does not read
+MCP servers from:
 
 {
   "mcpServers": {
@@ -18966,6 +19046,9 @@ Add this to your Claude Code settings.json:
     }
   }
 }
+
+Cursor: the same entry goes in ~/.cursor/mcp.json.
+Codex CLI: add to ~/.codex/config.toml:  [mcp_servers.indelible]  command = "indelible-mcp"
 `);
 } else if (args.length > 0) {
   runCli(args).catch((e) => {