From 96e319043e1f1315883b86261e5868163420bcac Mon Sep 17 00:00:00 2001
From: Kyle Isom <kyle@imap.cc>
Date: Fri, 25 Sep 2026 21:02:32 -0700
Subject: [PATCH] runbook: the M5a memory entries as the plan gave them

Found in the M5a review: task 13 renamed core-memory-unreadable to
memory-unavailable but kept its body, which still described
memory/core.md, and appended a memory-index-damaged entry of its own that
names a pointer memoryd never prints and leaves out `bxctl reindex`. Its
log row says both fragments were copied. Both entries are now the plan's
fragments, verbatim.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/runbook.md | 54 +++++++++++++++++++++----------------------------
 1 file changed, 23 insertions(+), 31 deletions(-)

diff --git a/docs/runbook.md b/docs/runbook.md
index 56e3864..75c1f15 100644
--- a/docs/runbook.md
+++ b/docs/runbook.md
@@ -397,24 +397,25 @@ the cache was lost, which `loopd` logs as a cache loss.
 
 ## memory-unavailable
 
-**What you see.** Starting a new session fails with an error naming `memory/core.md`, and this
-entry. Existing sessions still work: they use the baseline saved when they started.
+**What you see.** Starting a new session fails with a line naming `memoryd` or a file under
+`memory/`, and this entry. Existing sessions still work: they use the baseline saved when they
+started.
 
-**Why.** `memory/core.md` exists but cannot be read. A missing file is fine, but starting without
-memory you wrote, and without telling you, is not.
+**Why.** A new session's baseline takes the memory block from `memoryd` (`soul.md`, `memory.md`,
+`user.md`), and `loopd` could not get it: `memoryd` is not running or not listening at
+`<home>/run/loop-memory/memory.sock` (or `[memory] socket` in `loopd.toml`), or it refused because
+a file is unreadable or over its limit (`soul.md` 4,000 characters, `memory.md` 2,200, `user.md`
+1,375; an owner's edit can put it over). Starting without the memory the agent is, and without
+telling you, is what this prevents.
 
-**Confirm.**
+**Confirm.** `pgrep -x memoryd`; the line names the file or the socket. For a file,
+`wc -m <home>/memory/<file>`.
 
-```sh
-ls -l "$BOXMAKER_HOME/memory/core.md"; head -c 100 "$BOXMAKER_HOME/memory/core.md"
-```
+**Fix.** Start `memoryd serve --config <path>`, or shorten the file (for `memory.md` and `user.md`,
+move entries to `notes.md` by hand: an entry under a line `§ moved <time> from memory.md in session
+owner`).
 
-Look for wrong ownership or mode, or a file that is not UTF-8 text.
-
-**Fix.** Make it readable by the user `loopd` runs as (`chmod 0600` and `chown` to that user), or
-save it again as UTF-8.
-
-**Check.** A new session starts, and its `0.baseline.json` contains the text.
+**Check.** Start a new conversation; it answers.
 
 ## gatewayd-start-failed
 
@@ -638,24 +639,15 @@ listening elsewhere, or is stuck.
 
 ## memory-index-damaged
 
-**What you see.** `memoryd` exits 1 at start with `index: <reason>` naming its index file, then
-this entry.
+**What you see.** `recall` fails with a line starting `index:`, or `memoryd` logs one at start.
 
-**Why.** The index is the fast path to memory. If `memoryd` cannot read it, it does not know what
-it has stored, so it stops rather than guess. A missing file is a first start and is fine.
+**Why.** `index/memory.sqlite3` could not be read or written. It is disposable: everything in it
+comes from `sessions/` and `memory/notes.md`.
 
-**Confirm.**
+**Confirm.** `ls -l <home>/index/`; the end of `memoryd`'s log.
 
-```sh
-ls -l "$BOXMAKER_HOME/index/memory.sqlite3"
-python3 -c 'import sqlite3; sqlite3.connect("<path>").execute("SELECT count(*) FROM sqlite_master")'
-```
+**Fix.** `bxctl reindex`, which builds a new index beside the old one and replaces it. If that
+fails too, stop `memoryd`, move `index/memory.sqlite3` aside, and start `memoryd`, which rebuilds
+it.
 
-**Fix.** Move it aside and start `memoryd`, which rebuilds it:
-
-```sh
-mv "$BOXMAKER_HOME/index/memory.sqlite3" "$BOXMAKER_HOME/index/memory.sqlite3.damaged"
-memoryd serve --config <path>
-```
-
-**Check.** `memoryd serve --config <path>` prints `memoryd: serving`, and a `recall` call answers.
+**Check.** `bxctl reindex` prints how many logs, records and notes it read.