docs(issue-42): stages 1-2 - SKILL.md code-block inventory as test data; remove blocks the scripts already do

Stage 1: tests/data/skill_code_blocks.json lists all 37 fenced blocks of the
eight SKILL.md files at base 45d1621 (indented fences count), classed (a)
duplicate of a script, (b) procedure no script offers, (c) example/call/
diagram, with script file:line evidence and recorded mismatches.
tests/test_issue42_skill_blocks.py fails when a block changes without the
inventory, an (a) block comes back, a removed block's entry call is missing,
an exit-code table drifts from the script, or evidence points nowhere.

Stage 2: the five (a) blocks are gone - resume Workflow, stop pre-flight,
create pre-flight / Workflow / manual YAML append - replaced by the
entry-point call with option and exit-code tables. Each exit table has a
catch-all row: under set -e a failing sub-step's code passes through.
create's exit 4 is real (the YAML write raises SystemExit(4) for a duplicate
running row) and is listed as such. Doc-to-script mismatches are fixed in the
doc (resume Case 3 / no attach, stop --purge-conversation --yes, status
--json keys, create cmd_full and the nonexistent yaml-edit script). No
behaviour change, no version bump.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.agents/skills/multi-agent-mux-stop/SKILL.md

@@ -35,32 +35,7 @@ The stop command is always **graceful by default**:
 
 ## Pre-flight
 
-```bash
-SESSION_NAME=<workspace>-creator-<agent>  # convention
-AGENT=claude                              # claude | agy | hermes | grok | opencode | codex — always pass it
-AGENT_SESSIONS_YAML=.mam/agent-sessions.yaml
-
-# 1) Session is registered?
-python3 -c "
-import yaml
-d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
-names = [s['name'] for s in d.get('herdr_sessions', [])]
-if '$SESSION_NAME' not in names:
-    print('NOT in YAML — refusing to stop (no audit trail). Use multi-agent-mux-create first, or pass --force-no-yaml.')
-    raise SystemExit(1)
-"
-
-# 2) Already stopped?
-ALREADY=$(python3 -c "
-import yaml
-d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
-s = [x for x in d['herdr_sessions'] if x['name']=='$SESSION_NAME'][0]
-print(s.get('status', 'unknown'))
-")
-if [ "$ALREADY" = "stopped" ]; then
-  echo "Already stopped."
-fi
-```
+`stop_session.sh` checks this itself: the YAML exists and the session is registered (otherwise exit 1), and a session already `stopped` is a no-op (exit 0).
 
 ## Workflow
 
@@ -76,9 +51,22 @@ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
 # 3. Stop gracefully + clean up on-disk conversation (DANGEROUS)
 #    — this prevents any future resume (status=terminated, resumable=false).
 bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
-  --session "$SESSION_NAME" --agent "$AGENT" --purge-conversation
+  --session "$SESSION_NAME" --agent "$AGENT" --purge-conversation --yes
 ```
 
+`--purge-conversation` cannot be undone. Pass `--yes` only after the user has confirmed it.
+
+| Exit | Meaning |
+|---|---|
+| 0 | Stopped; or already `stopped` (no-op) |
+| 1 | YAML not found, or the session is not registered |
+| 2 | Bad arguments (including the retired `--mode` / `--capture-id` / `--graceful`), or `--agent` omitted and not resolvable |
+| 3 | `--purge-conversation` without `--yes` |
+| 4 | Purge aborted: the herdr session survived the kill chain |
+| other | The registry update after the stop (YAML / DB write) failed and its code is passed through |
+
+Exits 1, 2 and 3 come from checks before anything is stopped, so nothing was changed. On an `other` exit the session may already be down while its row still says `running`: check with `multi-agent-mux-status`, then run the stop again (it is idempotent).
+
 **Idempotency**: if the row is already `status: stopped`, the script prints `already stopped (...)` and exits 0 — re-running is a safe no-op.
 
 **`--agent` is the standard.** Pass it on every invocation. If omitted, the script