indelible-mcp 4.9.9 → 5.0.0

package/CLI_HANDBOOK.md

@@ -0,0 +1,251 @@
+# Indelible CLI Handbook
+
+Standalone command-line interface for Indelible blockchain memory. Same wallet, same blockchain, same functions as the MCP server — but runnable directly.
+
+---
+
+## Quick Reference
+
+### Save Session
+```bash
+node C:/Indelible-main/indelible-cli/src/index.js save --summary "what happened"
+```
+
+### Load from Blockchain
+```bash
+node C:/Indelible-main/indelible-cli/src/index.js load --sessions=5
+```
+
+### Check Status
+```bash
+node C:/Indelible-main/indelible-cli/src/index.js status
+```
+
+### Save a File
+```bash
+node C:/Indelible-main/indelible-cli/src/index.js vault save-file /path/to/file.js
+```
+
+### Ask Codex
+```bash
+node C:/Indelible-main/indelible-cli/src/index.js diary chat "How should we architect this?"
+```
+
+---
+
+## All Commands
+
+### Sessions
+```
+save                         Save current session to blockchain
+save --summary "note"        Save with custom summary
+load                         Load context from blockchain (default: 5 sessions)
+load --sessions=10           Load N sessions
+status                       Show wallet address, API key, last session
+```
+
+### Code Vault
+```
+vault save-file <path>                        Save a file (encrypted, chunked if >50KB)
+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
+vault save-style <file> [--name=N] [--desc=D] Save an AI style to blockchain
+vault load-style [txid]                       Load an AI style from blockchain
+vault update-index                            Update on-chain vault index
+```
+
+### Diary AI (Dual-Agent)
+```
+diary connect --key=SK [--model=MODEL] [--name=NAME]  Connect OpenAI companion
+diary chat "message"                                   Ask the AI companion
+diary save [--summary="..."]                           Save exchange to blockchain
+```
+
+### Setup & Hooks
+```
+setup --wif=KEY --pin=PIN    Import and encrypt your private key
+install-hooks                Install auto-save/restore hooks into Claude Code
+hook pre-compact             Auto-save before compaction (called by hook)
+hook post-compact            Auto-restore after compaction (called by hook)
+```
+
+---
+
+## Relationship to MCP
+
+The CLI and MCP server are the **same codebase**. They import the same tool functions (`saveSession`, `loadContext`, `saveFile`, `diaryChat`, etc.) and use the same wallet at `~/.indelible/config.json`.
+
+| | CLI | MCP Server |
+|---|---|---|
+| **Location** | `C:/Indelible-main/indelible-cli/src/` | `C:/bsv-claude-wrapper/mcp-server/` |
+| **Config** | Sync (`readFileSync`/`writeFileSync`) | Async (`await loadConfig()`) |
+| **Fetch** | Native `fetch` (Node 18+) | `node-fetch` package |
+| **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 |
+
+**Sync rule:** Any feature, fix, or change that goes into one MUST go into both. No exceptions. Adapt sync/async config pattern accordingly.
+
+---
+
+## Testing / Dog-Fooding
+
+The CLI is a live test harness for the MCP. When you test a CLI command, you're testing the exact same function the MCP calls.
+
+### Safe tests (no sats spent)
+```bash
+# Config loads correctly
+node C:/Indelible-main/indelible-cli/src/index.js status
+
+# Blockchain read works
+node C:/Indelible-main/indelible-cli/src/index.js load --sessions=1
+
+# Style loads from chain
+node C:/Indelible-main/indelible-cli/src/index.js vault load-style
+```
+
+### Function-level tests (no sats spent)
+```bash
+cd "C:/Indelible-main/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 "C:/Indelible-main/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 "C:/Indelible-main/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
+```
+
+### Live tests (spends sats)
+```bash
+# Session save (delta if prior save exists)
+node C:/Indelible-main/indelible-cli/src/index.js save --summary "test save"
+
+# File save
+node C:/Indelible-main/indelible-cli/src/index.js vault save-file /path/to/small/file.txt
+
+# Style save (auto-prepends core rules via ensureCoreRules)
+node C:/Indelible-main/indelible-cli/src/index.js vault save-style /path/to/rules.txt --name=test
+
+# Diary chat (costs OpenAI tokens, not sats)
+node C:/Indelible-main/indelible-cli/src/index.js 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         Generate BSV keypair, encrypt WIF with 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)
+```
+
+### Key Internal Features
+
+| Feature | What It Does |
+|---|---|
+| **Bridge health tracking** | Tracks success/failure per SPV bridge, skips unhealthy ones |
+| **UTXO chaining** | Back-to-back saves chain change outputs — no mempool conflicts |
+| **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 |
+| **Dashboard sync** | PATCHes indelible.one after every save |
+
+---
+
+## Rebuild the Executable
+
+```bash
+cd "C:/Indelible-main/indelible-cli" && bun build --compile src/index.js --outfile dist/indelible.exe
+```
+
+This creates a standalone `indelible.exe` — no Node.js required on the target machine.
+
+---
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Wallet not configured` | No config.json or no WIF | Run `setup --wif=KEY --pin=PIN` |
+| `No UTXOs available` | Wallet is empty | Send BSV to your address |
+| `Broadcast failed on all bridges` | All 4 SPV relays 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` |
+
+---
+
+## Config File
+
+`C:/Users/oorel/.indelible/config.json` — shared with MCP server.
+
+| Setting | Description |
+|---------|-------------|
+| `wif` or `wif_encrypted` | BSV private key (plaintext or PIN-encrypted) |
+| `address` | BSV address (derived from WIF) |
+| `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) |
+| `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 |
+
+---
+
+## Wallet
+
+- **Address:** shown by `indelible-mcp status` (yours is generated at setup 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.

package/CUSTOMER_AGENT_HANDBOOK.md

@@ -0,0 +1,320 @@
+# Your Agents: The Indelible Handbook
+
+Indelible gives your AI a permanent memory on Bitcoin. It also gives you agents. This is the honest map of what runs on your machine from day one: what fires on its own, what each message means, and what is coming later.
+
+Everything in this handbook describes the software you installed. Nothing here is aspirational. Where a capability belongs to the future, we say so plainly.
+
+---
+
+## 1. What you actually have on day one
+
+Your day-one roster is small and real: two guards, one companion, and one memory.
+
+| Agent | When it fires | What it needs | Free or Pro |
+|---|---|---|---|
+| **Witness** (the guard) | Inside every session save and file save, before anything is broadcast to the chain | Nothing. On by default. | Everyone |
+| **Guardrails** (the immune system) | Before any shell command your AI runs | Nothing. Installed with the hooks. | Everyone |
+| **Diary companion** ("Codex" by default) | When you talk to it (`diary_chat`, `diary_save`) | Nothing to start. Runs free on Groq by default. Want a premium model? Bring an xAI Grok or OpenAI key with `diary_connect`. Persisting rounds on chain uses tiny wallet fees like any save. | Free |
+| **The memory engine** | Auto-save before every compaction, restore at session start, recall on demand | A funded wallet. Session, file, and project saves need Pro. All reads are free. | Mixed |
+
+That is the whole list **for this package**. Your agent crew is a different thing and it lives in the web app: sign in at indelible.one, open the Sanctuary, and birth sixteen agents derived from your own wallet. They are yours today, not a preview. Section 7 walks through it, and section 8 is honest about the two parts that are still unfinished.
+
+### The 25 tools you can call today
+
+Grouped by what they cost:
+
+- **Setup:** `setup_wallet`
+- **Saving to chain (Pro):** `save_session`, `delta_save`, `save_all`, `save_file`, `save_project`, `save_style`, `save_goals_to_chain`, `update_vault_index`
+- **Reading your chain (free):** `load_context`, `load_file`, `load_project`, `load_style`, `recall_context`
+- **Finding your way around it (free, local):** `map_themes` — the table of contents of everything you have saved. It reads the local semantic index and answers with your recurring themes, how recently each was touched, and the sessions inside them, so you can hand those to `recall_context` and go straight to the right one. Nothing leaves your machine.
+- **Diary and Duo (free):** `diary_connect`, `diary_chat`, `diary_save`, `diary_recall`
+- **Goals (free, local-first):** `get_goals`, `manage_goal`
+- **Inner state (free, local):** `get_inner_state`, `update_inner_state`
+- **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.
+
+---
+
+## 2. What fires automatically (the four hooks)
+
+When you ran setup, the installer wired four hooks into Claude Code (`~/.claude/settings.local.json`). 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...` |
+| **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 |
+
+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.
+
+Hook installation is idempotent. If you ever suspect the hooks are missing, run:
+
+```
+indelible-mcp install-hooks
+```
+
+---
+
+## 3. How to read a Witness verdict
+
+The Witness reviews every session save and file save before it is broadcast. The chain is permanent, so this is the one gate that stands between a pasted secret and an immutable public record.
+
+### The anatomy of a block
+
+When the Witness rejects a save, you see a line like this:
+
+```
+[Witness] BLOCKED session 1a2b3c4d — credential_in_content: bsv_wif detected in message 12 (user)
+```
+
+And the tool returns an error shaped like:
+
+```
+Witness rejected save (1 critical issues): credential_in_content: ...
+```
+
+The part after the code is the reason in plain words. The code itself is the part to act on.
+
+### The reason codes you will actually see
+
+| Code | Meaning | Blocks? |
+|---|---|---|
+| `credential_in_content` | A private key, API key, or other credential-shaped string is in the content | **Always blocks.** No setting changes this. |
+| `secret_filename` | The file looks like a secrets file: `.env`, `credentials.json`, `*.pem`, `*.key`, `id_rsa`, a `wif` file, and similar | **Always blocks.** No setting changes this. |
+| `empty_file` | The file is 0 bytes | Observed by default |
+| `oversize` | The payload is over the hard size ceiling | Observed by default |
+| `no_messages` | The session has nothing to commit | Observed by default |
+| `empty_summary` | The save has no summary | Observed by default |
+| `bad_hash` | The file's content hash is missing or invalid | Observed by default |
+| `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).
+
+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.
+
+### What redaction already did for you
+
+For session saves, you get a layer of protection before the gate even runs. If you pasted a key into the conversation, the save engine scrubs credential-shaped strings from the content first, and tells you:
+
+```
+[indelible] redact-on-save: scrubbed 2 credential-shaped string(s) from session content before commit
+```
+
+So most pasted keys save clean, redacted, without you doing anything. The Witness block is the backstop for anything the scrubber misses.
+
+Files are different. Your file bytes are never altered, because the save proves integrity by hash. A credential inside a file cannot be redacted, so it blocks the save outright. Remove the secret from the file, then save again.
+
+### The recovery path
+
+1. Find the flagged content (the verdict names the message or the file).
+2. Remove the secret. If it was a real, live key, **rotate it**. It passed through the conversation, so treat it as exposed.
+3. Save again. The block does not persist; it re-checks fresh every time.
+4. Never paste the key back to "test" it.
+
+### Turning enforcement up
+
+In `~/.indelible/config.json`:
+
+```json
+{ "witness": { "enforce": true } }
+```
+
+- `false` (default): observe only, except the two always-block codes
+- `true`: block on any critical reason
+- `["oversize", "empty_summary"]`: block only the listed codes
+
+There is an escape hatch for false positives: running a save with the environment variable `WITNESS_BYPASS=1` skips the gate. Use it only when you are certain the flagged content is not a real secret. Never use it on an actual credential. The chain does not forget.
+
+### Reading a Guardrails verdict
+
+Guardrails checks shell commands, not saves. Two rules ship:
+
+**credential-pull (blocks).** A command that would print your wallet key or seed into the conversation, such as `cat ~/.indelible/config.json` or reading a `.env` file, is stopped before it runs:
+
+```
+[indelible:credential-pull] BLOCKED: That command would print your wallet key or seed into the conversation...
+```
+
+Why: anything printed into the chat goes to the model and into the saved transcript. If your AI needs a non-secret value from a config file, ask it to read just that field.
+
+**destructive-op (warns, never blocks).** A force-push, `rm -rf`, `git reset --hard`, or recursive force-delete gets a visible advisory before it runs:
+
+```
+[indelible:destructive-op] advisory: This command is irreversible... (not blocked)
+```
+
+Your repo, your machine, your call. The warning just makes the blast radius visible first.
+
+Guardrails fails open: if the guard itself ever errors, your command runs normally. A guard bug will never wedge your tools.
+
+### The diary has its own gate
+
+Diary and Duo saves are checked for credentials too, with a refusal instead of a block:
+
+```
+Refusing to save — credential detected in diary content (bsv_wif). Remove or rotate the secret, then save again. It is NOT on chain.
+```
+
+Same recovery path: remove it, rotate it, save again.
+
+---
+
+## 4. Your memory, whole
+
+Everything in this section is free.
+
+**`load_context`** is the recent view. It restores your last few sessions from chain, and it is what the post-compaction hook calls for you automatically.
+
+**`recall_context`** is the deep view: your entire on-chain history, from your first save to now. Search it by date range, by keyword, or by meaning:
+
+- `depth: "list"` returns dated summaries you can scan
+- `depth: "full"` drills into specific sessions
+- `from_date` / `to_date` take dates or prefixes like `"2026-03"`
+- `ranking` controls how results are ordered:
+  - `"blend"` (default): keyword and meaning-based ranking fused
+  - `"keyword"`: exact terms only
+  - `"semantic"`: meaning only
+
+Recall builds a local index in `~/.indelible/recall-index/` the first time it runs, decrypting your history once so later searches are fast. The index never leaves your machine.
+
+**Meaning-based search needs a one-time download.** The semantic model is about 50 MB, fetched once, hash-verified, and stored locally in `~/.indelible/models/`. After that, nothing ever leaves your machine: no query, no session content, no request of any kind. To enable it:
+
+```
+indelible-mcp semantic-fetch
+```
+
+This fetches the pack and backfills meaning-vectors for your existing history. It is resumable; re-run it if it stops partway. Until you do this, `recall_context` works fine with keyword ranking and tells you the semantic option is available.
+
+**`diary_recall`** is the same power scoped to your companion's own history. `scope: "diary"` for saved diary entries, `"duo"` for live Claude-plus-companion rounds, `"all"` for both.
+
+---
+
+## 5. Your first adversarial habit
+
+You may have read about the adversarial pack: agents that attack a piece of work from different angles before it ships. Honest answer up front: **the pack does not ship in your bundle.** It is the operator's court. You can watch it work in the Sanctuary tab, but you cannot summon it.
+
+Here is what you can do today, and it is genuinely useful:
+
+**1. Ask for the self-review.** Before any big change, tell your Claude: "Before you finalize this, try to refute your own conclusion. What is the failure mode you would be embarrassed to have missed?" One sentence, real results.
+
+**2. Structure it with goals.** `get_goals` and `manage_goal` ship complete: propose, accept, complete, checklists with progress, and claims so parallel sessions do not collide. A goal with explicit success criteria gives the self-review something concrete to check against.
+
+**3. Use Duo as your second opinion.** This is the real one. Duo mode puts a second AI in the room: your companion working live alongside Claude. It runs free on Groq by default, or you can upgrade it to xAI's Grok or an OpenAI model (see below). Ask your companion to critique what Claude proposed, and let Claude defend it. Two different models, two different failure modes, one honest argument. Every round auto-saves to your chain, so the argument itself becomes part of your permanent record.
+
+That is the day-one shape of adversarial work in this package: one reviewer you summon by asking, not a court. The full court, where your own review pack argues a matter out and each seat signs its position, lives with your crew in the web app (section 7).
+
+### Upgrading your companion to Grok (or OpenAI)
+
+Your companion is free on Groq out of the box, no key required. To run a premium model instead, bring your own key. xAI's Grok is a favorite here, and it is worth knowing why: Grok has no lasting memory of its own, so an on-chain diary is the one place it actually remembers you between sessions.
+
+**Getting an xAI Grok key:**
+
+1. Go to **console.x.ai** and sign in with your X account.
+2. Add a few dollars of credits under Settings, then Billing. Grok is pay-as-you-go, and a test costs pennies.
+3. Open **API Keys**, click **Create key**, and copy it. It starts with `xai-` and is shown only once.
+
+**Connecting it:**
+
+- In Claude Code: run `diary_connect` with the key. Provider is detected automatically (`xai-` for Grok, `sk-` for OpenAI).
+- On indelible.one: open the **Diary**, click the **Companion** button in its header, pick **xAI (Grok)**, and paste the key. (The Diary is the one home for your companion — model, keys, and Duo Mode all live there.)
+
+A note on safety: never paste an API key into a chat with your AI. Put it straight into `diary_connect` or the Settings field. Every save is credential-scanned before it touches the chain, so a leaked key gets caught, but the habit is to keep keys out of the conversation entirely.
+
+Once connected, every diary and Duo round runs on Grok and persists to Bitcoin. It remembers after xAI forgets. A Groq (`gsk_`) key is refused on purpose here, because Groq is already your free default; there is nothing to add.
+
+---
+
+## 6. Goals: the board you share with your AI
+
+The goal system is the part of Indelible that turns "my AI helps me" into "my AI works toward something with me." Two rules give it its shape: **your AI proposes, you accept** — nothing becomes active without your say — and **completion requires evidence**: a txid, a commit, a test result. Done means receipts.
+
+**In Claude Code:** `get_goals` shows the board (your Claude reads it at session start and steers toward active goals). `manage_goal` runs the lifecycle: propose, accept (with a 0–100 priority), block with a reason, complete with evidence. Goals live in `~/.indelible/goals.json` on your machine — that file is the source of truth.
+
+**On indelible.one/goals:** the same board, live. From v4.9.5, it syncs automatically whenever you touch goals in Claude Code — no setup. You can also work the board directly on the web: accept, complete, block, drag to reprioritize, propose with the **New goal** button. One honest boundary: your machine wins. Web changes hold until your next goals action in Claude Code pushes the local board up.
+
+**Sealing to Bitcoin:** `save_goals_to_chain` encrypts your entire board with your key and broadcasts it as one transaction — the permanent record of what you set out to do and what you finished. It costs the miner fee (a fraction of a cent for most boards), skips the broadcast for free if nothing changed, and the receipt shows up in the **On chain** card on the Goals tab. Sealing is part of the Pro toolkit; the board itself is free. Re-seal after big changes — over time the chain holds the honest history of your ambition.
+
+The full walkthrough lives at **indelible.one/docs/goals**.
+
+---
+
+## 7. The Sanctuary tab: your city
+
+Sign in at indelible.one and open the Sanctuary tab. You are looking at your own city.
+
+**Birth your crew.** Under Crew & Forge there is one button. Press it and sixteen agents are derived, in your browser, from the key you already hold: the review pack (Goblin, Gremlin, Troll, Ogre) and the Inquisitor who convenes them, the Witness and the Scribe, the Quartermaster, the Bookkeeper, the Calibrator, the Cartographer, and five envoys for the gate.
+
+They are not assigned to you. Nothing is issued. Each one is computed from your wallet, and each has its own Bitcoin address.
+
+**Four generations.** Your wallet derives a master key that exists only for you. The master derives five house keys, one per kind of work: verification, governance, orchestration, support, commerce. Each house derives its own agents. So Witness and Goblin are siblings in verification; Skeptic and Escrow are siblings in commerce. The whole family walks back to one key.
+
+**Check it yourself.** Press "Verify crew" and the browser re-derives all sixteen from your wallet and compares them to what is stored. Close the browser, open it on another machine, unlock, and you get the same sixteen addresses. Nothing is fetched from us to make that happen.
+
+Your crew is also **signed by your wallet**, and the signature is public. Anyone can fetch `/api/sanctuary/crew/<your-address>` with no account and check it offline: every agent is signed, and a separate crew signature commits to the exact set, so nobody can quietly serve someone a shortened version.
+
+**What that does and does not prove.** It proves we did not invent your crew and cannot alter it. It does not prove the agents were derived from your wallet, and nothing ever can: derivation runs on a shared secret, so only someone holding the private key can reproduce it. That is a recovery property, not a proof to strangers. It also does not stop us withholding the record entirely, which is what the on-chain anchor in section 8 is for. Until that lands the app marks every agent unattested, and means it.
+
+**How to read a bust:** the dot is liveness, the number is verdicts on record, the line under the name is the agent's latest real task, and the bar is how recently it fired. A newly born agent reads "at post · awaiting first task", because it has done nothing yet and we would rather say so than animate something.
+
+---
+
+## 8. What is still not done
+
+Your crew exists and is yours. Two things about it are honestly unfinished, and we would rather you read them here than discover them.
+
+**No on-chain anchor yet.** Your crew lives on our server, signed by you. That signature means we cannot forge or alter it, which is the serious half of the problem. The half still open is availability: if we went down, or decided not to serve your record, a stranger would have nowhere to look. Writing a commitment to the chain fixes that, because the record would then exist somewhere we do not control, with a timestamp we cannot move. It is the next piece of work. Until it ships, every agent reads `unattested` in the app, and that word is accurate.
+
+**Earning needs your box running.** The five envoys are commerce agents with their own derived addresses, and payment for their work goes to those addresses, not to us. But an agent can only take a paid order if the machine that can actually run it has checked in recently. Open the Counter with your MCP box running and your agents are deliverable; with the box off, the Counter will not let you open an agent for orders, on purpose. An order nobody can fill is worse than no order.
+
+Timing: we do not put dates on unfinished work, because a date we miss is worse than a roadmap we keep.
+
+---
+
+## 9. When something goes wrong
+
+The short crosswalk from message to fix.
+
+**`[Witness] BLOCKED ...`**
+Not a malfunction. The guard found something that must not reach a permanent chain. Go to section 3: find it, remove it, rotate it if it was real, save again.
+
+**`[indelible:credential-pull] BLOCKED ...`**
+Guardrails stopped a command that would print your wallet key into the conversation. Read only the specific non-secret field you need.
+
+**"Reads are free" / "saving to the blockchain is a Pro feature"**
+You are on the free tier. Reads, diary, Duo, and recall all keep working. To keep sessions permanently, go Pro at indelible.one/pricing.
+
+**"Cannot verify your plan right now"**
+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.
+
+**Restore comes back empty**
+Work the checklist in order:
+1. Have you ever saved? Restore can only return what was written. Free wallets read, but only Pro writes sessions.
+2. Same wallet? Your history lives under one address. Compare `indelible-mcp status` on this machine against Settings on indelible.one.
+3. Just saved? Give the network a minute; propagation is not instant.
+
+**"semantic ranking unavailable (model pack not downloaded)"**
+Recall is working, keyword-ranked. To enable meaning-based search, run `indelible-mcp semantic-fetch` (about 50 MB, one time, local only).
+
+**"Refusing to save" (credential detected in diary content)**
+The diary's own gate. The secret is NOT on chain. Remove it, rotate it, save again.
+
+**Indelible tools do not appear in Claude Code**
+Re-register the MCP server, then restart Claude Code:
+```
+claude mcp add --scope user indelible -- indelible-mcp
+```
+If auto-save or restore is not firing, reinstall the hooks: `indelible-mcp install-hooks`.
+
+**Back up your key.** Your wallet key lives in `~/.indelible/config.json` on this machine, unlocked by your PIN. Your history is encrypted on chain with that key. If this machine dies and you have no copy of the key, the history survives on chain forever, but nothing can decrypt it. Copy your key (indelible.one → Settings → Private Key) somewhere safe today: a password manager, a printed copy, a USB drive in a drawer.
+
+**Still stuck?** Tell your AI to file a bug: the `report_bug` tool sends your description plus machine-gathered facts (version, address, recent save receipts) to our intake. It redacts keys and never sends your session content. You describe the problem; the system supplies the facts.
+
+---
+
+*This handbook ships with your install and describes the code in it. When the product grows, this document grows with it. Receipts over reputation.*

package/README.md

@@ -2,6 +2,8 @@
 
 Blockchain-backed memory for Claude Code. Save your AI conversations permanently on BSV via a federated mesh of SPV bridges.
 
+> **New here?** Two guides ship with this package: **CUSTOMER_AGENT_HANDBOOK.md** (your agents on day one — the Witness, the Scribe, what runs for you) and **CLI_HANDBOOK.md** (every command + common errors). They are in the package install folder, or on indelible.one/docs.
+
 ## Quick Start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indelible-mcp",
-  "version": "4.9.9",
+  "version": "5.0.0",
   "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",
@@ -8,7 +8,9 @@
     "indelible-mcp": "src/index.js"
   },
   "files": [
-    "src/"
+    "src/",
+    "CUSTOMER_AGENT_HANDBOOK.md",
+    "CLI_HANDBOOK.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",

package/src/index.js

@@ -6989,6 +6989,79 @@ import { homedir as homedir12 } from "os";
 init_utxo_cache();
 init_api_client();
 init_save_log();
+
+// mcp-server/lib/reconcile.js
+function payloadContentKey(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  if (payload.protocol === "indelible.project-bundle" && Array.isArray(payload.files)) {
+    const hashes = payload.files.map((f) => f && f.content_hash).filter(Boolean);
+    return hashes.length ? `bundle:${hashes.join(",")}` : null;
+  }
+  if (payload.content_hash) return String(payload.content_hash).replace(/^sha256:/, "");
+  return null;
+}
+async function findByContentKey({
+  address,
+  targetKey,
+  getHistory,
+  fetchPayload,
+  excludeTxids = [],
+  maxScan = 400,
+  confirmedOnly = false,
+  stopAtFirst = true,
+  matchCap = 10
+}) {
+  if (!address || !targetKey) return { matches: [], scanned: 0, truncated: false, fetchFailures: 0, classification: "absent" };
+  const exclude = new Set(excludeTxids.map((t) => String(t).toLowerCase()));
+  let history = [];
+  try {
+    history = await getHistory(address);
+  } catch {
+    return { matches: [], scanned: 0, truncated: false, fetchFailures: 0, classification: "inconclusive-history-unreachable", error: "history-unreachable" };
+  }
+  if (!Array.isArray(history)) return { matches: [], scanned: 0, truncated: false, fetchFailures: 0, classification: "absent" };
+  const ordered = [...history].sort((a, b) => (b.height || 0) - (a.height || 0));
+  const truncated = ordered.length > maxScan;
+  const candidates = ordered.slice(0, maxScan);
+  const matches = [];
+  let scanned = 0;
+  let fetchFailures = 0;
+  let confirmedFound = false;
+  for (const h of candidates) {
+    const txid = (h.tx_hash || h.txid || "").toString();
+    if (!txid || exclude.has(txid.toLowerCase())) continue;
+    if (confirmedOnly && !(h.height > 0)) continue;
+    scanned++;
+    let payload = null;
+    try {
+      payload = await fetchPayload(txid);
+    } catch {
+      fetchFailures++;
+      continue;
+    }
+    if (payloadContentKey(payload) === targetKey) {
+      const height = h.height || null;
+      matches.push({ txid, height });
+      if (height > 0) confirmedFound = true;
+      if (stopAtFirst && confirmedFound) break;
+      if (matches.length >= matchCap) break;
+    }
+  }
+  matches.sort((a, b) => {
+    const ac = a.height > 0 ? 1 : 0, bc = b.height > 0 ? 1 : 0;
+    if (ac !== bc) return bc - ac;
+    return (b.height || 0) - (a.height || 0);
+  });
+  const result = stopAtFirst && matches.length ? [matches[0]] : matches;
+  let classification;
+  if (result.length) classification = "found";
+  else if (truncated) classification = "inconclusive-truncated";
+  else if (fetchFailures > 0) classification = "inconclusive-fetch-degraded";
+  else classification = "absent";
+  return { matches: result, scanned, truncated, fetchFailures, classification };
+}
+
+// mcp-server/tools/save_project.js
 var TX_CACHE_DIR2 = join12(homedir12(), ".indelible", "tx-cache");
 async function cacheTx2(txId, payload) {
   try {
@@ -7169,7 +7242,7 @@ async function saveProject(dirPath, options = {}) {
     } catch {
     }
     const receipt = buildReceipt(_wr, { txId, fee, txSize });
-    appendReceipt(receipt, { trigger: "interactive", saveType: "project" });
+    appendReceipt(receipt, { trigger: "interactive", saveType: "project", contentHash: payloadContentKey(payload) });
     return {
       success: true,
       txId,
@@ -7200,79 +7273,6 @@ import { existsSync as existsSync11 } from "fs";
 import { dirname as dirname3, join as join13 } from "path";
 import { homedir as homedir13 } from "os";
 import { Transaction as Transaction6, PrivateKey as PrivateKey8, CompletedProtoWallet as CompletedProtoWallet3 } from "@bsv/sdk";
-
-// mcp-server/lib/reconcile.js
-function payloadContentKey(payload) {
-  if (!payload || typeof payload !== "object") return null;
-  if (payload.protocol === "indelible.project-bundle" && Array.isArray(payload.files)) {
-    const hashes = payload.files.map((f) => f && f.content_hash).filter(Boolean);
-    return hashes.length ? `bundle:${hashes.join(",")}` : null;
-  }
-  if (payload.content_hash) return String(payload.content_hash).replace(/^sha256:/, "");
-  return null;
-}
-async function findByContentKey({
-  address,
-  targetKey,
-  getHistory,
-  fetchPayload,
-  excludeTxids = [],
-  maxScan = 400,
-  confirmedOnly = false,
-  stopAtFirst = true,
-  matchCap = 10
-}) {
-  if (!address || !targetKey) return { matches: [], scanned: 0, truncated: false, fetchFailures: 0, classification: "absent" };
-  const exclude = new Set(excludeTxids.map((t) => String(t).toLowerCase()));
-  let history = [];
-  try {
-    history = await getHistory(address);
-  } catch {
-    return { matches: [], scanned: 0, truncated: false, fetchFailures: 0, classification: "inconclusive-history-unreachable", error: "history-unreachable" };
-  }
-  if (!Array.isArray(history)) return { matches: [], scanned: 0, truncated: false, fetchFailures: 0, classification: "absent" };
-  const ordered = [...history].sort((a, b) => (b.height || 0) - (a.height || 0));
-  const truncated = ordered.length > maxScan;
-  const candidates = ordered.slice(0, maxScan);
-  const matches = [];
-  let scanned = 0;
-  let fetchFailures = 0;
-  let confirmedFound = false;
-  for (const h of candidates) {
-    const txid = (h.tx_hash || h.txid || "").toString();
-    if (!txid || exclude.has(txid.toLowerCase())) continue;
-    if (confirmedOnly && !(h.height > 0)) continue;
-    scanned++;
-    let payload = null;
-    try {
-      payload = await fetchPayload(txid);
-    } catch {
-      fetchFailures++;
-      continue;
-    }
-    if (payloadContentKey(payload) === targetKey) {
-      const height = h.height || null;
-      matches.push({ txid, height });
-      if (height > 0) confirmedFound = true;
-      if (stopAtFirst && confirmedFound) break;
-      if (matches.length >= matchCap) break;
-    }
-  }
-  matches.sort((a, b) => {
-    const ac = a.height > 0 ? 1 : 0, bc = b.height > 0 ? 1 : 0;
-    if (ac !== bc) return bc - ac;
-    return (b.height || 0) - (a.height || 0);
-  });
-  const result = stopAtFirst && matches.length ? [matches[0]] : matches;
-  let classification;
-  if (result.length) classification = "found";
-  else if (truncated) classification = "inconclusive-truncated";
-  else if (fetchFailures > 0) classification = "inconclusive-fetch-degraded";
-  else classification = "absent";
-  return { matches: result, scanned, truncated, fetchFailures, classification };
-}
-
-// mcp-server/tools/load_file.js
 var TX_CACHE_DIR3 = join13(homedir13(), ".indelible", "tx-cache");
 var SAVE_LOG_PATH = join13(homedir13(), ".indelible", "save-log.jsonl");
 async function contentKeyFromSaveLog(txid) {
@@ -9331,7 +9331,7 @@ Commands:
 }
 function printHelp() {
   console.log(`
-Indelible MCP \u2014 Blockchain memory for Claude Code (v4.9.9)
+Indelible MCP \u2014 Blockchain memory for Claude Code (v5.0.0)
 
 Setup:
   indelible-mcp setup --wif=KEY --pin=PIN    Import and encrypt your private key
@@ -9638,7 +9638,7 @@ function readStdin() {
 }
 var SERVER_INFO = {
   name: "indelible",
-  version: "4.9.9",
+  version: "5.0.0",
   description: "Blockchain-backed memory and code storage for Claude Code"
 };
 var TOOLS = [
@@ -10010,7 +10010,7 @@ async function handleMcpRequest(request) {
           }
         };
       case "tools/list":
-        return { jsonrpc: "2.0", id, result: { tools: TOOLS.filter((t) => !["share_session", "load_shared"].includes(t.name)) } };
+        return { jsonrpc: "2.0", id, result: { tools: TOOLS.filter((t) => !["share_session", "load_shared", "birth_custom_agent", "run_custom_agent", "convene_chamber", "transmute_agents"].includes(t.name)) } };
       case "tools/call": {
         const { name, arguments: args2 } = params;
         let result;