@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/commands/discover.md

@@ -0,0 +1,221 @@
+---
+name: discover
+description: Discover a client, product, and its users before any build
+help_jtbd: "Run a Larry-led six-movement discovery conversation that lands a scaffolded Data Room plus a Discovery Brief."
+body_shape: B (Semantic Tree)
+hitl_shape: "F.1"
+hitl_why: "Discovery resolves to a single next move the navigator confirms."
+body_shape_detail: Six conversation movements as nested nodes; synthesis as a batch write
+serves_jtbd: ["explore"]
+teaching: "When you have a client or a product and need to understand it before you design or build, /mos:discover runs a guided one-question-at-a-time conversation across six movements and lands a Discovery Brief plus a scaffolded Data Room. It does not design the site; it makes every later decision strategic instead of arbitrary."
+interactive_first_reward: reframe_question
+ui_reference: skills/ui-system/SKILL.md
+# --- Phase 122 workflow-layer frontmatter ---
+kind: methodology
+frameworks: ["Jobs to Be Done (JTBD)"]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - WebFetch
+  - AskUserQuestion
+# --- Phase 143.3 connector frontmatter ---
+connector:
+  connects_to_spine: true
+  sensor_triggers: [SENS-01, SENS-05]
+  reach_id: brain_consult
+  sub_mode: client-product-discovery
+  framework: "Jobs to Be Done (JTBD)"   # MUST match the existing frameworks: value
+  posture: push_forward
+  hierarchy_rank: 7
+  filing: fileEvidenceWithReadback
+  plan_gated: false
+  web_scope: null
+  surface: F.1
+---
+
+# /mos:discover
+
+You are Larry. This command is the conversational front door for a navigator who arrives with a client or a product and needs to understand it before any build. A web/UX firm never starts with pixels; it starts by understanding three souls -- the brand, the product, and the users' jobs -- through a guided, multi-turn conversation, then turns that into a brief that makes every later decision strategic.
+
+`/mos:discover` is ORCHESTRATION, not a new atom (Canon Part 7). It SEQUENCES existing methodology commands; it never duplicates them. It WRAPS `/mos:new-project` and `/mos:onboard` rather than superseding them: it is the conversational front door that calls the scaffold backend. Net-new surface is limited to the flow plus the brief and scaffold synthesis. The methodology already exists; only the SEQUENCING is new.
+
+The design source for this flow is the ported skill at `skills/client-discovery-interview/SKILL.md` (the investigator method, the six movements, the Hooked-twice principle) and `skills/client-discovery-interview/question-bank.md` (the question library, the JTBD job-interview script, the Hooked worksheet, the Discovery Brief template). Read them before running.
+
+**Voice rules (LOCKED):**
+- Conversational, direct, no filler. Signature openers: "Very simply...", "Here's the thing...", "One thing I've learned..."
+- NO emoji anywhere. NO "I'd be happy to help". NO "Great question!". NO sentences starting with "I".
+- Ask-Tell Dial starts at 0.15 (ask-heavy) during discovery -- you ask, the navigator shares. Discovery is an interrogation of the truth, not a delivery of answers.
+- Symbol vocabulary: only these 12 glyphs: ■ ▼ ▶ ▷ |-  \- ✓ • ⚠ ⚡ ⬜ ->
+- Error pattern: 3 lines only -- What / Why: reason / Fix: /mos:command
+- House rule: hyphens only, NO em-dashes anywhere.
+- MindrianOS is infrastructure for ANY domain -- do NOT assume the navigator is a founder or building a venture. The "client" may be a brand, a product, a research program, or the navigator's own work.
+
+**The investigator spirit (from the ported SKILL.md):** One question at a time. Never dump a questionnaire -- the question bank is your back pocket, not your script. Ask your next question from THEIR last answer, not your list. Listen for the three tells: repetition (what they say twice matters most), emotion (where energy spikes or drops), avoidance (what they skip past). Reframe abstract questions into concrete sensory ones to reach the soul. Mirror and confirm: play back what you heard; the correction is the gold. Prefer stories over adjectives. Close every movement with "What have I not asked that I should have?"
+
+## Tri-Polar surface note (DISC-09, CLAUDE.md Tri-Polar rule)
+
+`/mos:discover` is a conversational command, so it works across all three surfaces with surface-specific behavior:
+- **CLI:** full power -- files artifacts via Bash plus the navigation.cjs chokepoint; hooks fire; the F.1 dial renders in the terminal.
+- **Desktop:** Larry-conversational -- the six movements run as a natural dialogue; the navigator talks, Larry investigates.
+- **Cowork:** writes the scaffolded room into shared `00_Context/` state so a team sees the discovery take shape; the brief and personas are visible to every collaborator.
+
+Design every movement so it degrades gracefully on whichever surface is active. No surface-specific methodology.
+
+## Mode Detection (DISC-08: dual entry, tier-aware)
+
+Check the navigator's argument FIRST. A client or product name passed as the argument is a WARM-target hint (the navigator already knows what they are discovering). Then branch on workspace state, mirroring `/mos:new-project` Step 1's three states:
+
+```bash
+ROOMS_HOME="${MINDRIAN_ROOMS_HOME:-$HOME/MindrianRooms}"
+```
+
+- **COLD (Mode A scaffold-from-scratch):** no `$ROOMS_HOME/.rooms/registry.json` AND no legacy `room/` in the workspace. This is a brand-new discovery. Scaffold a fresh discovery room from scratch after the conversation. The registry is created automatically on first room creation.
+- **WARM (Mode A enrich):** the registry exists. Enrich the active room, or the named room if the argument matched one. Tell the navigator: "You already have rooms here -- I'll fold this discovery into [room], or start a fresh one. Which?"
+- **Tier 0 graceful (Mode B):** the Brain is unreachable, or STATE.md is empty (first-session cold start). Still run the full conversation and file everything LOCALLY. Per Canon Part 3 Mode B, render NO RECOMMENDED markers (the >= 0.7 confidence gate is a Brain-only concept). The Navigation Engine and local decision history substitute for Brain ranking. Discovery never blocks on Brain.
+
+The conversation is identical across modes; only the filing target and the option-generation tier differ.
+
+## The Six-Movement Investigation (DISC-02)
+
+Run these as conversation movements ACROSS TURNS, not one survey. **ONE question at a time.** Follow the navigator's energy. Push back on vague answers. Mirror and confirm before moving on. **Adapt the order to what the navigator brings** -- spend more turns where the energy and the ambiguity are. The full question library for each movement is in `skills/client-discovery-interview/question-bank.md`; pull the one question that fits the thread.
+
+Between movements, render a Shape F.1 transition gate (see "F.1 gates" below) so the navigator chooses to go deeper, move on, or branch. Never auto-advance through a wall of prose.
+
+### Movement 1: Warm-up and the real why
+
+Why now? Why does this project exist at all? What happens if it works -- and what happens if nothing changes? Surface the stakes, the urgency, and the internal reality behind the brief.
+
+**Part-7 reuse (DISC-03):** this movement reuses `/mos:beautiful-question` via `commandsForFramework("Beautiful Question Framework")` because a thin orchestration of the shipped atom beats a new atom (Canon Part 7); net-new is the SEQUENCING, not the methodology. Resolve the command through the resolver door -- never hardcode the slug. If the framework resolves to an empty list, degrade to "run it manually" (CONNECTOR-CONTRACT.md section 4).
+
+### Movement 2: The brand's soul
+
+History, mission, the big why, values, what they stand against. Personality and archetype (the 12: Outlaw, Creator, Magician, Hero, Lover, Jester, Everyman, Caregiver, Ruler, Innocent, Sage, Explorer -- pick a primary and a secondary). Voice: how they speak, and the "never says" list. Push past adjectives ("modern, clean, professional") into stories and "never says".
+
+**Part-7 reuse (DISC-03):** this movement reuses `/mos:persona` and `/mos:think-hats` via `commandsForFramework("Six Thinking Hats")` because a thin orchestration of the shipped atom beats a new atom (Canon Part 7); net-new is the SEQUENCING, not the methodology. Route through the resolver door, never a hardcoded slug.
+
+### Movement 3: The product's essence
+
+What it actually is, the one job it does best, what it replaces, the business case (who pays, what has to be true for them to keep paying), the non-negotiable constraints, and what "done well" looks like in measurable terms.
+
+**Part-7 reuse (DISC-03):** this movement reuses the `/mos:new-project` scaffold and `/mos:lean-canvas` via `commandsForFramework("Lean Canvas")` because a thin orchestration of the shipped atom beats a new atom (Canon Part 7); net-new is the SEQUENCING, not the methodology. The scaffold backend is wrapped (OPEN-2), not duplicated.
+
+### Movement 4: The users and their jobs (JTBD)
+
+For each persona: who they are in context (not just demographics) AND why they "hire" this -- the functional job, the emotional job, the social job. What they "fire" (today's alternative and why it falls short, the last straw). The trigger that sends them looking in the first place. Complete the job statement: "When I ___ (situation), I want to ___ (motivation), so I can ___ (expected outcome)."
+
+**Part-7 reuse (DISC-03):** this movement reuses `/mos:analyze-needs`, `/mos:user-needs`, and `/mos:jtbd` via `commandsForFramework("Jobs to Be Done (JTBD)")` because a thin orchestration of the shipped atom beats a new atom (Canon Part 7); net-new is the SEQUENCING, not the methodology. Note: `/mos:jtbd` now resolves under this framework after the FIX-3 route landed (its frontmatter declares `frameworks: ["Jobs to Be Done (JTBD)"]`). Route through the resolver door.
+
+### Movement 5: The competition and the whitespace
+
+Who they admire and why, who they refuse to resemble, and where the whole category looks and sounds the same (the sea of sameness to break). The one true sentence about them that no competitor can honestly say.
+
+**Part-7 reuse (DISC-03):** this movement reuses `/mos:compare-ventures` and `/mos:whitespace` via `commandsForFramework` on their declared frameworks ("PWS Triple Validation Compass" and "HSI Semantic Surprise Analysis Assistant") because a thin orchestration of the shipped atoms beats a new atom (Canon Part 7); net-new is the SEQUENCING, not the methodology. Route through the resolver door, never a hardcoded slug.
+
+### Movement 6: The product as a Hooked loop (DISC-07)
+
+This movement is INLINED, not dispatched -- it is rendered into the brief, not routed to a command. See the DISC-07 section below for the four Hooked stages and the Facilitator ethics check.
+
+## DISC-07: Hooked, used two ways (stages INLINED)
+
+There is no in-repo hooked-model skill directory to read from -- the four Hooked stages are embedded here directly (from the ported `question-bank.md` Hooked worksheet). You MAY name the globally-available hooked-model skill as a runtime reference only; do NOT point a read_first at a non-existent hooked-model skill folder.
+
+### (a) Design the product's habit loop (movement 6, lands in the brief)
+
+Design the loop the finished product should create, not just pages:
+
+- **Trigger.** External: where does the user come from (search, referral, email, ad)? Internal: what emotion or itch does the product attach to so they come back on their own (boredom, anxiety, FOMO, pride, curiosity)?
+- **Action.** The simplest single behavior that delivers value. Apply Fogg B = MAP (motivation x ability x prompt): is there enough Motivation, is the Ability (effort) low enough, is the Prompt clear and present? Reduce effort before adding motivation.
+- **Variable reward.** Which type, and how is it varied (not identical every time)? Tribe (social: validation, belonging, recognition) / Hunt (resources or information: a feed, a search, a deal, a result) / Self (mastery, completion, progress, control).
+- **Investment.** What does the user put in that (a) makes the next visit better for them and (b) loads the next trigger? Data, content, reputation, followers, configuration, skill. Investment is the difference between a visit and a relationship.
+- **Ethics check (Facilitator quadrant).** Does this loop improve the user's life, and would the maker use it themselves? Build for the Facilitator quadrant of the Hooked manipulation matrix, not the Dealer. Flag any loop that fails this check.
+
+### (b) The command's OWN engagement loop
+
+Run the interview with the same psychology that the product's loop will use. A clear prompt (one question), low effort to answer (concrete, not abstract), a small reward (reflect an insight back that makes the navigator feel understood), and investment (each answer visibly builds the brief). Show the brief taking shape as you go -- that visible progress is the investment hook that keeps the navigator generous with the truth. The brief-taking-shape IS the visible investment hook.
+
+## F.1 gates (Canon Part 3 Decision Gate, every choice point)
+
+Render EVERY choice point as a Shape F.1 Next Move selector via AskUserQuestion -- NOT bare prose. This applies to: each movement transition, the post-synthesis "what next", and the deck-on-request gate (DISC-10). Copy the closing-selector surface from `commands/onboard.md` Step 6 verbatim. Rendering recommendations as bare prose is the Cluster 5 audit canon violation.
+
+The selection writes to STATE.md Decisions AND creates a typed graph edge `(navigator) -[CHOSE {verb, reason}]-> (artifact)`. RECOMMENDED marker ONLY at Brain confidence >= 0.7 (Phase 88.2 invariant); in Mode B and Tier 0 render NO RECOMMENDED marker. The canonical minimum F.1 vocabulary is Run Methodology / Defer / Free-Text.
+
+Example transition gate:
+
+```
+[CONTEXT] -- discover -- NEXT MOVE
+LOCAL / BRAIN / SIGNAL
+
+Choose next move:
+
+  1. Run Methodology  -- go deeper on this movement (the resolved command)
+  2. Defer            -- move to the next movement
+  3. Free-Text        -- tell Larry where to dig
+```
+
+## DISC-04: Synthesis (the Discovery Brief + the scaffolded room)
+
+After the conversation, synthesize. Do NOT design the site -- produce the BRIEF and the room that a later build phase consumes.
+
+1. **Write the Discovery Brief** using `templates/discovery/discovery-brief-template.md` (authored in Plan 02; referenced by path here). Sections: Brand soul / Product essence / Personas + JTBD cards / Positioning / Habit loop / Plain-language message / Design implications / Open questions + assumptions.
+2. **Scaffold the Data Room sections** from `skills/client-discovery-interview/discovery-scaffold.json` (authored in Plan 02), writing a `ROOM.md` per section (ICM Layer 0 -- every directory gets an identity file, no exceptions).
+3. **File personas** as `room/team/ai-personas/*` with an embedded JTBD card (OPEN-4): Name + context / Job statement / Functional-Emotional-Social / Fires (current alternative + last straw) / Trigger.
+4. **Mark every guess** as `review_status: proposed` (Canon Part 5 evidence tiering + Part 9 proposed-not-confirmed). Never let a guess harden into a fact.
+5. **File ALL artifacts through `lib/core/navigation.cjs` `fileEvidenceWithReadback`** -- never folder-scan (Canon Part 9: SQL is the local mind; `filing: fileEvidenceWithReadback` is what the connector declares). Obsidian nested rule (CLAUDE.md decision 16): `section/artifact-name/artifact-name.md`, never a bare .md in a section root.
+
+Use the established `node ${CLAUDE_PLUGIN_ROOT}/...` invocation idiom for cjs calls.
+
+## DISC-10: The Feynman bridge (plain-language default, deck on request)
+
+Discovery uncovers the complex truth; this step translates it into plain, compelling language -- the load-bearing handoff from discovery to any website or deck build. After synthesis, run the plain-language bridge over the product essence and the brand soul.
+
+**Default output is the plain-language message:** the "explain it to a smart twelve-year-old" one-liner from the ported `question-bank.md`, sharpened, plus the value-prop ladder. Write it into the brief's **Plain-language message** section. Seed the room's per-section `FEYNMAN.md` from it via the shipped `lib/core/folder-memory.cjs` writer -- never hand-write FEYNMAN.md.
+
+**The reasoning pyramid and the deck are dispatched via the EXISTING Feynman surface, NOT a second connector (FIX 1).** The shipped generator is one-connector-per-file, so `/mos:discover` declares exactly ONE connector (the discovery flow). DISC-10 dispatches via `commandsForFramework("The Pyramid Principle")` (which returns `/mos:mos-reason` and `/mos:structure-argument`) for the reasoning pyramid, and dispatches the `mos-deck-engine` skill for the deck. Those surfaces get their own connector frontmatter in the 144.1 sweep; DISC-10 rides them as a documented sub-step.
+
+**Deck ON REQUEST only (OPEN-5):** render an F.1 gate offering "build the deck", which dispatches `mos-deck-engine` (the canonical Feynman 6-stage engine: reduce to essence, plain language, expose confusion, build the mental model, simplify until it breaks, teach it back). Do NOT re-implement the 6-stage pipeline. Do NOT extend the connector generator parser. The plain-language message is always produced; the deck is produced only when the navigator asks.
+
+## Part-7 reuse map (DISC-03 summary)
+
+Every movement routes to an EXISTING atom through the resolver door `commandsForFramework(framework)` -- never a hardcoded `/mos:` slug. The contract is the framework name; a framework that resolves to an empty list degrades to "run it manually" (CONNECTOR-CONTRACT.md section 4). Net-new is the SEQUENCING, not the methodology (Canon Part 7).
+
+| Movement | Existing atom(s) | Resolver call |
+|----------|------------------|---------------|
+| 1. Warm-up / real why | `/mos:beautiful-question` | `commandsForFramework("Beautiful Question Framework")` |
+| 2. Brand soul | `/mos:persona` + `/mos:think-hats` | `commandsForFramework("Six Thinking Hats")` |
+| 3. Product essence | `/mos:new-project` scaffold + `/mos:lean-canvas` | `commandsForFramework("Lean Canvas")` |
+| 4. Users + JTBD | `/mos:analyze-needs` + `/mos:user-needs` + `/mos:jtbd` | `commandsForFramework("Jobs to Be Done (JTBD)")` |
+| 5. Competition / whitespace | `/mos:compare-ventures` + `/mos:whitespace` | `commandsForFramework(...)` on each declared framework |
+| 6. Hooked loop | (inlined, not dispatched) | rendered into the brief |
+| DISC-10 bridge | `/mos:mos-reason` + `mos-deck-engine` | `commandsForFramework("The Pyramid Principle")` |
+
+## Part-8 boundary (DISC-06)
+
+All discovery content -- brand soul, product essence, persona names, JTBD content, client specifics -- is LOCAL room data. None of it may enter a Brain query (Canon Part 8). The connector's only Brain-bound value is the generic `framework` handle ("Jobs to Be Done (JTBD)"); `web_scope` is `null` (discovery never reaches the web). Movements route through `commandsForFramework` (a framework name, never client content). All artifacts file LOCAL via `navigation.cjs` `fileEvidenceWithReadback`. The DISC-10 plain-language message and any deck derive from LOCAL room artifacts only; the bridge dispatch carries no client strings to Brain or web.
+
+## Routing to /mos:ignite at the birth moment (Phase 155-06)
+
+When the Discovery session reaches the birth moment (the client has committed to creating a room, after DISC-10's plain-language message has been delivered and the Discovery Brief is complete), route to /mos:ignite. Do NOT route to /mos:new-project directly.
+
+Discover is the conversation; ignite is the birth.
+
+Pass the Discovery Brief content in one of two ways:
+- Preferred: pass the brief sha8 reference as `--from-brief <sha8>` if the brief has been filed to `~/.mindrian/mva/briefs/<sha8>.json` (via the Phase 118 pipeline).
+- Fallback: use `--express` and ensure the session context contains the Discovery Brief content. /mos:ignite's B2 gate will use the session context as blueprint input.
+
+The Discovery Brief content (product essence, JTBD, persona, positioning) serves as pre-filled B2 blueprint material. The blueprintFamily from the discovery session (typically 'venture' or 'exploration' depending on how far along the client is) should be determinable from the brief -- pass it as context so /mos:ignite can bypass B1 if appropriate.
+
+## DISC-09 acceptance
+
+On a fixture client, `/mos:discover` produces a valid Discovery Brief plus a scaffolded room (ROOM.md present per folder), the connector registry includes the single `discover` connector, the CONN-03 tripwire is green, and the Part-8 sweep returns zero. The Tri-Polar check (CLI / Desktop / Cowork) passes per the surface note above.
+
+## Error Handling
+
+Follow the 3-line error pattern:
+
+```
+&#10007; [What failed]
+  Why: [specific reason]
+  Fix: [one command to resolve]
+```

package/commands/doctor.md

@@ -0,0 +1,271 @@
+---
+name: doctor
+description: "Diagnose and optionally repair MindrianOS install: install-cache drift, sentinel gaps, active-room guard, surface-verification, ROOM.md drift, UI compliance, statusline visibility, Brain smoke, and a paste-ready command-registration bug report for Anthropic"
+help_jtbd: "Diagnose and optionally repair an off-feeling install."
+argument-hint: "[--fix] [--all] [--cascade-rooms] [--graph-derive-health] [--heal-room] [--verify-surface] [--room-md] [--ui-compliance] [--statusline-visibility] [--card-fire-health] [--install-state] [--stale-first-touch] [--deprecated-usage] [--brain-smoke] [--eureka-smoke] [--drift] [--report-registration-bug] [--acceptance] [--pre-tag] [--pre-flight] [--dogfood-acceptance] [--claims] [--check-rs-engine] [--post-update] [--bind-check] [--simulate-write] [--scan-commands] [--scan-scripts] [--light-npx] [--dry-run] [--json]"
+body_shape: E (Action Report)
+hitl_shape: "F.0"
+hitl_why: "It surfaces one diagnosed repair for a single approve-or-defer decision."
+# Phase 267.3-04, ruled in 267.3-CLASSIFICATION.md (Row 7): first delivery at commands/doctor.md:42, one status row per check plus a tallied summary, which the rule doc names outright as not a reward.
+interactive_first_reward: "--none (diagnostic surface)"
+body_shape_detail: per-class status rows with [before → after] pattern, summary totals, F.1 Next Move selector when drift detected without --fix
+serves_jtbd: ["audit-room"]
+teaching: "When something feels off with the install, /mos:doctor diagnoses install-cache drift, ROOM.md gaps, statusline visibility, and UI compliance. Optionally repairs with --fix."
+allowed-tools:
+  - Bash
+  - Read
+  - AskUserQuestion
+# --- Phase 172-06 CIRS R1 exclude (Canon Part 11) ---
+connector:
+  excluded: true
+  reason: "Utility command. A diagnostics / health-check surface the navigator or release pipeline runs deliberately; it inspects the install, never reacts to a navigator problem-state."
+---
+
+<!-- mos:firing-block v2 -->
+At this command's Decision Gate, when the fork is genuinely unanswered and relevant to the
+current conversation, fire the AskUserQuestion card natively rather than printing a bare
+numbered menu or bullet list. Compose it with the SAME verb/option shape that
+lib/hmi/shape-f1-renderer.cjs (renderShapeF1) produces and that lib/hmi/selector-dispatcher.cjs
+(appendAskUserQuestionTrailer) fires, matching this command's declared hitl_shape. Do NOT fire
+the card when the navigator already answered the question in plain text or the gate has no
+connection to the current conversation: acknowledge the answer and proceed instead. Never
+reproduce the selector as text and never hand-build a bespoke widget (SEED-021): when you do
+fire, call the AskUserQuestion tool in this same response so the navigator picks a move instead
+of re-typing a command. Any text list is preserved only as the non-interactive floor for
+Desktop / Cowork / piped callers.
+<!-- /mos:firing-block -->
+
+# /mos:doctor
+
+Self-service diagnostic for MindrianOS installs. It started as an install-cache drift detector (a real failure mode that happened twice -- see `docs/autopsies/2026-04-13-wrong-workspace-incident.md` and `docs/autopsies/2026-04-28-install-cache-drift-incident.md`) and grew into a family of health checks. As of Phase 217 every check except three carve-outs is a data-driven module: one row in `data/doctor-modules.json` plus one runner file under `lib/core/doctor/`.
+
+## How it works
+
+`scripts/doctor.cjs` keeps only the orchestration: it parses the flags, walks the module registry (`data/doctor-modules.json`), calls each runner's `check(ctx)` (and its `fix(ctx)` under `--fix`), then renders one status row per result and tallies the summary. The per-check logic lives in the runner files, not in the script. Add a new check and the script does not change.
+
+Each registry row carries a `cadence`:
+
+- `cadence: always` -- a per-invocation diagnostic. Its `check()` runs on EVERY `doctor` call and is watermark-immune, so a migrated check never goes silent after the first run. This is the exact silent-diagnostic failure mode Phase 217 killed.
+- `cadence: once` -- a watermark-gated heal (the umbilical module). It runs only while its `introduced_version` sits in the `(applied_through, running]` window and never re-runs once the watermark at `~/.mindrian/doctor-applied.json` advances past it.
+
+Both cadences are also gated by `introduced_version <= running`, so an install is never faulted for an organ it predates, and a future-version module is deferred until the user upgrades.
+
+`--fix` support is declared per module by the boolean `fix_supported` in `data/doctor-modules.json` (never omitted -- silence is not a legal no-fix declaration). Under `--fix`, a fix-supported module whose `check()` surfaced a `warn`/`error` is passed to `fix()`, then `check()` re-runs so the reported row reflects the post-fix state. The completeness of every module's declaration is enforced as a HARD-BLOCKING test by `tests/test-doctor-module-contract-parity.cjs` (the D-03 gate). The doc-vs-code parity of this file is guarded by `tests/test-doctor-doc-parity.cjs`.
+
+### The class-A install-cache check (the original)
+
+Class A still runs on a bare invocation and stays special-cased (one of the three Phase 217 carve-outs, below). It:
+
+1. Reads the live install version at `~/.claude/plugins/mindrian-os/.claude-plugin/plugin.json`.
+2. Enumerates `~/.claude/plugins/cache/mindrian-marketplace/mos/*` and picks the highest semver as "latest".
+3. Reports drift when install < latest.
+
+Under `--fix` it renames the live install to `~/.claude/plugins/mindrian-os.stale-<old-version>-<timestamp>`, copies the latest marketplace cache in via `cp -aT`, and re-reads `plugin.json` to verify the version matches. The backup is preserved indefinitely; after 24 hours of normal use the user can delete it by hand.
+
+## The check inventory
+
+Every check has a stable class letter (or a registry id). The class flag that activates it is in parentheses; check-only means no `--fix` remediation.
+
+- **class A -- install-cache** (bare run; `--fix` supported) -- live-install-vs-marketplace-cache drift, plus recovery.
+- **class B -- cascade-rooms sentinel** (`--cascade-rooms`; `--fix` supported) -- every registered room carries its `.room-root` sentinel. `--fix` CREATES missing sentinels for rooms whose dir exists (dir-missing rooms are suggested, never auto-created). This fix was NEWLY wired in Phase 217 Plan 04 -- before that the class-B `--fix` claim was a false doc promise.
+- **class C -- active-room guard silence** (`--cascade-rooms`; check-only) -- detects when a write to a non-active room would be silenced before the cascade side-channel runs. Shares the `--cascade-rooms` flag with class B.
+- **class D -- verify-surface** (`--verify-surface`; check-only) -- live cascade end-to-end. Spawns the child runner `tests/test-cascade-surface-e2e.cjs` (30s timeout) and asserts its 8-key shape. Self-skips honestly when `bash` or the harness is absent (never faults an install for a missing dev harness).
+- **class E -- room-md** (`--room-md`; `--fix` supported) -- ROOM.md + MINTO.md presence under the active room's `.room-root`. `--fix` invokes `generate-section-intelligence.cjs --recursive`, then re-checks.
+- **class F -- ui-compliance** (`--ui-compliance`; check-only) -- UI Ruling System scan across `commands/*.md` and `scripts/*.cjs` (frontmatter body_shape, forbidden box chars / glyphs, renderer Zone 1 + Zone 4 patterns).
+- **class G -- statusline-visibility** (`--statusline-visibility`; `--fix` supported) -- stale user-settings path / broken plugin install / statusline-mos isolated execution / disableAllHooks. `--fix` removes the stale user-settings statusLine override so the plugin-level config takes effect.
+- **class H -- install-incomplete** (shares `--statusline-visibility`; `--fix` supported) -- missing statusLine block or a halted `.install-receipt.json` tail. `--fix` re-stamps the canonical statusLine block idempotently (the halted-tail case is report-only).
+- **class I -- install-state** (`--install-state`; `--fix` supported) -- install-state record + topology classification + 6-way version-of-record consistency. `--fix` returns MULTIPLE recovery records (session-start record write, LV rewrite, legacy-config reconcile, legacy-clone backup-verify-remove with the dev-clone safety belt). Runs BEFORE class J so J reads its result via `ctx.checks`.
+- **class J -- deployment-surfaces** (shares `--install-state`; `--fix` supported) -- reconciles every owned surface in `data/deployment-surfaces.json` against disk. Reads topology / active-root / active-version from class I's same-invocation result (self-derives via `shared.cjs` when absent). `--fix` re-stamps `ok:false` session-start-owned surfaces and prunes the marketplace cache.
+- **class K -- stale-first-touch-copy** (`--stale-first-touch`; check-only) -- greeting surfaces declared by `data/first-touch-surfaces.json` (banner, splash, onboard, sessionstart, operator-update, larry-extended) scanned for stale version literals and U+2014 em-dash violations. SEED-007 absorption. Also activated by `--all`.
+- **class L -- deprecated-usage** (`--deprecated-usage`; check-only) -- scans the last 7 days of `~/.claude/projects/.../*.jsonl` session transcripts for `/mos:<deprecated>` patterns and surfaces a per-command "use `/mos:<new>` instead" hint. Pure LOCAL scan; zero network, zero Brain. Also activated by `--all`.
+- **class M -- brain-smoke** (`--brain-smoke`; check-only) -- 5-layer Brain end-to-end probe (plugin root resolver, key resolver, HTTPS schema, MCP stdio handshake, e2e brain_schema via the bundled shim). Diagnostic-only; reports the exact failing layer. This is an async runner and stays special-cased (carve-out, below). Activated by `--all`.
+- **class N -- plugin-enabled-state** (no flag; bare run + `--all`; check-only) -- the silent-disable watchdog (DRIFT-12). Reads `~/.claude/settings.json` enabledPlugins + installed_plugins.json; installed && enabled===false is CRITICAL with a re-enable hint. It runs on a bare run and under `--all` precisely because a DISABLED plugin cannot fire its own SessionStart hooks to report itself. LOCAL read only; never writes settings.json.
+- **class P / Q / R -- drift** (`--drift`; opt-in, NOT in `--all`) -- class P is prose-vs-code drift (skill-vs-code + first-touch, report-only even under `--fix`), class Q is gsd-record drift (shells out to `gsd-tools validate health`, parses W007 ROADMAP gaps + I001 missing SUMMARYs; `--fix` writes the DRIFT.md baseline and stubs missing SUMMARYs), class R is runtime-reachability drift (FAILS NON-ZERO when a capability is WIRED in the connector registry but UNREACHABLE by `decide()` at runtime). LOCAL-only, zero network.
+- **class S -- eureka-smoke** (`--eureka-smoke`; check-only) -- 4-layer Eureka local-embedding-stack probe (deps present, vec backend, model cache, graceful degrade). Non-cascading; never downloads a model unless `MINDRIAN_EUREKA_SMOKE_ALLOW_DOWNLOAD=1`; rolls into `--acceptance`. Another async carve-out (below). `--fix eureka` installs the local embedding stack into `~/.mindrian/eureka-deps/` (one-time, about 380 MB), the same action as `/mos:eureka enable`.
+- **card-fire-health** (`--card-fire-health`; check-only; D-05) -- health of the `check-card-fire.cjs` self-diagnostic instrument: intercept log exists / valid JSONL / fresh (`~/.mindrian/card-fire-intercepts.log`), classifier and counter library seams intact, render-coverage registry parses, session store readable. `cadence: always`, LOCAL-only. Activated by `--all`.
+- **graph-derive-health** (`--graph-derive-health`; `--fix` supported, sugar `--heal-room`) -- did this room's SEMANTIC edge layer ever land? A room.db with `BELONGS_TO` edges is a filing cabinet: it knows which artifact sits in which section. A room.db with cascade edges (INFORMS / CONTRADICTS / CONVERGES / INVALIDATES / ENABLES / REFINES / ROOT_CAUSES) additionally knows how the ideas relate. Before Phase 224-02 a failed derivation silently cleared its own retry signal, so a room could end up with the first and never the second. FAIL is exactly that shape (BELONGS_TO present, cascade count zero); WARN is a derive queue entry stuck past 3 days or a recorded `graph-derive-failures.json`. Scopes to the active room by default; add `--cascade-rooms` to sweep every registered room. `--fix` (or `--heal-room`) re-enqueues each affected room through the existing dedup-by-roomDir derive sweep, so re-running never duplicates an entry. LOCAL only: read-only `room.db` reads through the navigation door plus a local JSON queue write, zero network. Closes RCA item 4d. Activated by `--all`.
+- **graph-derive-heal-retrofit** (no flag; `cadence: once`; check-only) -- the one-time automatic repair for rooms damaged BEFORE the Phase 224-02 fix shipped. It fires by itself the first time doctor runs after an update, walks every registered room, reuses the same detection signal as graph-derive-health, and re-enqueues each zero-cascade-edge room. Watermark-gated, so it runs once per version window and never repeats. No flag and no `--fix` needed: a user should not have to know their graph was damaged in order to get it repaired. Closes RCA item 4c.
+- **room-graph-density** (no flag; bare run + `--all`; check-only) -- per-registered-room census of `room.db` `nodes` and `edges` row counts, plus a system-wide total. Reads every room through the read-only navigation door added in Phase 232.1, so the sweep can never migrate or otherwise mutate a room it only measures. A room with no `room.db` reports 0 / 0 and is not an error. `cadence: always`, LOCAL-only. Reports raw counts ONLY: it makes no density, health, or risk claim in either direction (SEED-074's hard guard on downstream claims).
+
+## Step 1: Parse the user's intent
+
+Look at the user's invocation:
+
+- `/mos:doctor` (no flag) -> class A install-cache + class N plugin-enabled-state + the accumulative engine (the `cadence: once` heals like umbilical plus any `flag: null` always-modules). Fast; this is the bare-run surface.
+- `/mos:doctor --all` -> activates B, C, D, E, F, G, H, I, J, K, L, M, and card-fire-health. `--drift` (P/Q/R) and `--eureka-smoke` (S) stay OPT-IN by design and are NOT part of `--all`.
+- `/mos:doctor --cascade-rooms` -> class B (.room-root sentinel) + class C (active-room guard silence)
+- `/mos:doctor --graph-derive-health` -> graph-derive-health (semantic-edge derivation health for the active room; add `--cascade-rooms` to sweep every room)
+- `/mos:doctor --heal-room` -> the same class with `--fix` on: re-enqueues every WARN/FAIL room's derive so the next in-session derive rebuilds its semantic layer
+- `/mos:doctor --verify-surface` -> class D live cascade end-to-end via `tests/test-cascade-surface-e2e.cjs`
+- `/mos:doctor --room-md` -> class E (ROOM.md/MINTO.md presence under `.room-root` subtrees)
+- `/mos:doctor --ui-compliance` -> class F (UI Ruling System scan)
+- `/mos:doctor --statusline-visibility` -> class G (user-settings drift, plugin install integrity, statusline-mos isolated execution) + class H (install-incomplete)
+- `/mos:doctor --card-fire-health` -> card-fire-health module (D-05 instrument-health)
+- `/mos:doctor --install-state` -> class I (install-state + topology + 6-way version-of-record) + class J (deployment-surface reconciliation)
+- `/mos:doctor --stale-first-touch` -> class K
+- `/mos:doctor --deprecated-usage` -> class L
+- `/mos:doctor --brain-smoke` -> class M (5-layer Brain probe)
+- `/mos:doctor --eureka-smoke` -> class S (4-layer Eureka probe; opt-in)
+- `/mos:doctor --drift` -> class P + class Q + class R (opt-in; NOT in `--all`)
+- `/mos:doctor --report-registration-bug` -> READ-ONLY escalation reporter (below). NOT a class flag, NOT part of `--all`, NOT a `--fix`.
+- `/mos:doctor --fix` -> diagnostic + auto-recovery for every class that declares `fix_supported: true`: class A, B, E, G, H, I, J. Fix support is declared per module in `data/doctor-modules.json` and enforced by `tests/test-doctor-module-contract-parity.cjs`.
+- `/mos:doctor --json` -> machine-readable output (for hooks / regression tests)
+- `/mos:doctor --verbose` (or `-v`) -> extra per-check detail in the human render.
+- `/mos:doctor --dry-run` -> `--fix` runners simulate their remediation without mutating disk.
+
+Combine flags freely: `/mos:doctor --all --json --fix`.
+
+### Release-gate and lifecycle flags (separate from the class roster)
+
+These siblings own their own exit contracts and are not part of the class-flag drift roster:
+
+- `--acceptance` -> the release-gate checklist (install-state + deployment-surfaces + version-of-record + verify-release + doctor-all + published + npx-roundtrip). Hard abort on any sub-check failure.
+- `--pre-tag` -> with `--acceptance`, filter to the pre-tag-applicable points (implies `--acceptance`).
+- `--pre-flight` -> the strict-subset tier `release.sh` uses before it mutates the tree (implies `--acceptance`).
+- `--dogfood-acceptance` -> the Canon Part 6 dog-fooding acceptance pass.
+- `--claims` -> the claims-verification leg.
+- `--check-rs-engine` -> the reason-select engine probe (NOT part of `--all`).
+- `--post-update` -> the post-`claude plugin update` confirmation pass.
+- `--bind-check <roomDir>` -> a lightweight LOCAL room-health check run at BIND-TIME (never per-turn, never a Brain call). NEVER-BLOCK: an unhealthy room degrades to an advisory and STILL exits 0.
+- `--light-npx` -> the lighter npx-roundtrip variant for `--acceptance`.
+- `--simulate-write=<path>` -> class C test seam: simulate a write to a specific room path.
+- `--scan-commands=<dir>` / `--scan-scripts=<dir>` -> class F test seams: point the UI scan at scratch directories.
+- `--help` (or `-h`) -> print the usage text and exit 0.
+
+## The `--report-registration-bug` mode (escalation reporter)
+
+When a user reports that `/mos:*` commands do not register despite a valid install, run `/mos:doctor --report-registration-bug`. It is a read-only sibling mode (not a class flag, not part of `--all`, and NOT a `--fix`). It reuses the doctor's existing evidence collectors to prove every locally-checkable cause is CLEAN, then prints a paste-ready bug report for Anthropic. The root cause is a confirmed host-side Claude Code core bug (see `.planning/debug/every-mos-command-unknown.md`), so there is nothing to repair locally; the report is the deliverable the navigator pastes upstream. If a local cause is NOT clean (for example install-cache drift), that line is FLAGGED "fix locally first" and the mode still exits 0. Never a status claim; the report intentionally avoids declaring the install well or repaired.
+
+## Step 2: Execute
+
+Run via Bash:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.cjs" $ARGUMENTS
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unset (older Claude Code versions), fall back to:
+
+```bash
+node ~/.claude/plugins/mindrian-os/scripts/doctor.cjs $ARGUMENTS
+```
+
+## Step 3: Render the output
+
+The script outputs a 4-zone Shape E (Action Report) per skills/ui-system/SKILL.md. The renderer is structural: it prints one row per non-skip `report.checks[<id>]` entry, so a new module gets a row for free. Display the script's stdout directly. Do not re-format. Do not strip ANSI color codes.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Healthy, no drift |
+| 1 | Drift detected (read-only mode, or `--fix` did not run) |
+| 2 | Drift detected and recovered (`--fix` mode) |
+| 3 | Internal error (cannot read directories, no marketplace cache, install in `error` state) |
+| 4 | Recovery attempted but rolled back to the backup state (the D-03 rollback path) |
+
+Two invariants layer on top of the table:
+
+- **Class-flag runs force exit 0.** When any class flag is active (`classFlagsActive`), the run honors the graceful-degradation invariant (Canon Part 8) and exits 0 unless an explicit `--fix` attempt failed. A detected drift is still visible in the rows; it does not abort a scoped scan. Hermetic scratch-registry test runs rely on this.
+- **Two narrow non-zero escalations.** A `--drift` run whose class-R runtime-reachability check returns `warn` exits 1 (a WIRED-but-UNREACHABLE capability is a hard CIRS R9 fail, not a warning). And on a bare / non-class-flag run, the class-N plugin-disabled state (`warn`) exits 1, because that is the one failure mode no SessionStart hook can ever self-report.
+
+## The three Phase 217 carve-outs
+
+Every other check is a registry module; these three are deliberately special-cased in `main()`, each opened with a written `Phase 217 carve-out:` justification comment (loud and auditable, never a silent omission):
+
+1. **class A install-cache** -- its inline drift + atomic recovery + topology guards are positionally coupled to `_finalizeAndExit` (the exit-code chain), and its render is hand-coded; forcing it into the uniform module shape would risk the most-tested path.
+2. **class M brain-smoke** -- an `async` runner; the engine loop is synchronous, so it stays in its own `await` block.
+3. **class S eureka-smoke** -- the same async-vs-sync-engine reason as brain-smoke.
+
+## Extension architecture
+
+A new check is two files and no script edit:
+
+1. One entry in `data/doctor-modules.json`: `{ id, introduced_version, cadence ("always" | "once"), flag (a parseArgs flags key or null), fix_supported (explicit boolean), runner, description }`.
+2. One runner at `lib/core/doctor/<id>-module.cjs` exporting `check(ctx)` -> `{ status: 'ok'|'warn'|'error'|'skip', detail, ...payload }`, and `fix(ctx)` when `fix_supported: true`. Shared helpers and constants live in `lib/core/doctor/shared.cjs`; a runner never back-requires `scripts/doctor.cjs` (that would be a circular require).
+
+The D-03 contract test fails the suite if a module omits `fix_supported`, returns a status outside the vocabulary, forgets its `detail` string, or declares `fix_supported: true` without exporting a `fix` function.
+
+## When to suggest /mos:doctor
+
+Surface this command proactively when:
+
+- A user reports unexpected behavior that might be version-related ("my new feature isn't showing up")
+- After a marketplace update (`/plugin marketplace update` followed by reports of broken commands)
+- During session start if the workspace guard hook reports drift
+- As a follow-up after `claude plugin update` to confirm the update actually landed
+
+## Voice rules (if invoked through Larry)
+
+- No "I" sentences
+- Lead with the script's output, then a one-line interpretation
+- If drift detected without `--fix`: suggest `/mos:doctor --fix` as the next step
+- If drift detected and recovered: confirm the version, mention the backup location, recommend `/clear` and a fresh session
+
+## Example output (healthy)
+
+```
+-- MindrianOS -- doctor -- no-drift --
+
+  ■ install-cache              ✓ healthy (1.12.0)
+  ■ dev-source                 ✓ consistent (1.12.0)
+
+  Summary: 2 healthy / 0 drift / 0 warnings
+
+  ▶ /mos:status                  # room state overview
+  ▷ /mos:doctor --all          # re-run all classes
+  ▷ /mos:doctor --json         # machine-readable output
+```
+
+## Example output (drift detected, no --fix)
+
+```
+-- MindrianOS -- doctor -- drift-detected --
+
+  ■ install-cache              ⚠ drift detected
+     live    1.10.10 → 1.11.0
+
+  Summary: 0 healthy / 1 drift / 0 warnings
+
+  [F.1 Next Move]
+   ▶ Run /mos:doctor --fix
+   ▷ Defer
+   ▷ Free-Text
+
+  ▶ /mos:doctor --fix --all     # auto-recover all drift classes
+  ▷ /mos:rooms                 # inspect known rooms
+  ▷ /mos:doctor --json         # machine-readable output
+```
+
+## Example output (recovery successful)
+
+```
+-- MindrianOS -- doctor -- recovered --
+
+  ■ install-cache              ⚠ drift detected
+     live    1.10.10 → 1.11.0
+     ✓ recovered to 1.11.0
+     backup /home/jsagi/.claude/plugins/mindrian-os.stale-1.10.10-20260428-095548
+
+  Summary: 0 healthy / 0 drift / 0 warnings
+
+  ▶ /mos:status                  # room state overview
+  ▷ /mos:doctor --all          # re-run all classes
+  ▷ /mos:doctor --json         # machine-readable output
+```
+
+After successful recovery, suggest:
+
+```
+Recovery applied. Run /clear to refresh the context window
+so Larry picks up the new plugin code.
+```
+
+Note: per D-19, the renderer above is structural. Larry handles narrative interpretation of any drift finding when surfacing conversationally (e.g., "what does this mean?"). See ${CLAUDE_PLUGIN_ROOT}/references/personality/voice-dna.md for voice patterns.
+
+## Zone 4 (Action Footer)
+
+After presenting results, suggest next actions:
+
+> Want to repair what we found? -> /mos:doctor --fix
+> Want the full picture? -> /mos:status

package/commands/dogfood-flush.md

@@ -0,0 +1,130 @@
+---
+visibility: admin
+description: Drain the dog-food queue into the mindrian room and regenerate ## Live (auto)
+help_jtbd: "Manually flush captured plugin edits into the mindrian dataroom."
+body_shape: E
+hitl_shape: "F.0"
+hitl_why: "It offers one dogfood-flush action to approve or defer."
+# Phase 267.3-06, ruled in 267.3-CLASSIFICATION.md (Row 8): first delivery at commands/dogfood-flush.md:77, an F.0 Action Report of events flushed, the maintainer's own internal bookkeeping.
+interactive_first_reward: "--none (diagnostic surface)"
+argument-hint: ""
+serves_jtbd: ["audit-room"]
+teaching: "When you want the plugin's own venture room to reflect your latest edits immediately, /mos:dogfood-flush drains the PostToolUse queue and regenerates the Live (auto) section in STATE.md. The automatic SessionStart drain handles the steady-state case."
+disable-model-invocation: false
+allowed-tools: Bash(node *), AskUserQuestion
+kind: utility
+frameworks: []
+produces: "~/MindrianRooms/mindrian/STATE.md"
+inputs: []
+autonomous_safe: true
+# --- Phase 172-06 CIRS R1 exclude (Canon Part 11) ---
+connector:
+  excluded: true
+  reason: "Lifecycle command. A dog-fooding maintenance flush the maintainer runs deliberately; an internal upkeep action with no navigator problem-state trigger."
+---
+
+<!-- mos:firing-block v2 -->
+At this command's Decision Gate, when the fork is genuinely unanswered and relevant to the
+current conversation, fire the AskUserQuestion card natively rather than printing a bare
+numbered menu or bullet list. Compose it with the SAME verb/option shape that
+lib/hmi/shape-f1-renderer.cjs (renderShapeF1) produces and that lib/hmi/selector-dispatcher.cjs
+(appendAskUserQuestionTrailer) fires, matching this command's declared hitl_shape. Do NOT fire
+the card when the navigator already answered the question in plain text or the gate has no
+connection to the current conversation: acknowledge the answer and proceed instead. Never
+reproduce the selector as text and never hand-build a bespoke widget (SEED-021): when you do
+fire, call the AskUserQuestion tool in this same response so the navigator picks a move instead
+of re-typing a command. Any text list is preserved only as the non-interactive floor for
+Desktop / Cowork / piped callers.
+<!-- /mos:firing-block -->
+
+# /mos:dogfood-flush
+
+Force-drain the dog-food queue (`~/.mindrian/dogfood-queue.jsonl`) into
+`~/MindrianRooms/mindrian/room.db` via the Phase 109 navigation chokepoint,
+then regenerate the `## Live (auto)` sentinel-bounded section in
+`~/MindrianRooms/mindrian/STATE.md` atomically with the human-authored body
+byte-preserved.
+
+This is the manual knob the user reaches for when the automatic SessionStart
+drain has not run recently -- explicit redraw, drain everything pending right now.
+
+## Admin Identity Check
+
+**A HARD, code-enforced gate already ran before you saw this body.** This command
+carries `visibility: admin`, so the `UserPromptSubmit` hook
+`scripts/admin-command-gate.cjs` (wired in `hooks/hooks.json`) intercepted the
+invocation, ran the deterministic checker `scripts/check-admin-identity.cjs`, and
+BLOCKED (exit 2) any non-admin caller BEFORE this body was expanded. If you are
+reading this, the code gate already PASSED.
+
+Defense in depth (restatement, not the only enforcement): the gate authorizes a
+user when `MOS_ADMIN=true`, when `$USER`/`$USERNAME` contains "jsagi"/"jonathan",
+when `$HOME` is `/home/jsagi`, or when the optional allowlist
+`~/.mindrian/admin-identity.json` names the identity. If, as a soft backstop, none
+of these hold, render `x Command not found: dogfood-flush` and STOP.
+
+## Behavior
+
+Two-step pipeline:
+
+1. `scripts/dogfood-emit.cjs` -- drain the queue file, batch-emit `file_changed`
+   memory_event rows via `lib/core/navigation.cjs::logMemoryEvent`. Truncate
+   the queue on success (atomic .tmp + rename).
+2. `scripts/dogfood-derive.cjs` -- read the last 10 file_changed events,
+   regenerate the `<!-- LIVE_AUTO_START -->` / `<!-- LIVE_AUTO_END -->` block
+   in STATE.md. Log a `feynman_timeline_refreshed` memory_event on success.
+
+## Output
+
+F.0 Action Report:
+
+- **emitted:** N events flushed from the queue.
+- **derived:** STATE.md `## Live (auto)` regenerated at `<iso-timestamp>`.
+- **skipped:** if the target room is missing, both phases soft-warn and exit 0
+  without crashing the parent.
+
+## Invariants
+
+- **Canon Part 8 (Graph Boundary):** zero Brain egress. The grep sweep in
+  `tests/test-dogfood-emit-derive.cjs` is the structural enforcement.
+- **Canon Part 9 (Memory Locality):** every memory_event write goes through
+  `navigation.cjs`. The Phase 109-06 pre-commit hook is the structural
+  enforcement (any direct `require('lib/core/room-db.cjs')` from
+  `dogfood-emit.cjs` / `dogfood-derive.cjs` would fail the hook).
+- **Byte-preservation (Phase 124-02 invariant, reused):** everything in
+  STATE.md outside the sentinel pair has its SHA256 preserved across
+  regeneration (Case A). The integration test
+  (`tests/test-dogfood-emit-derive.cjs`) asserts this.
+
+## Implementation
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/dogfood-emit.cjs
+node ${CLAUDE_PLUGIN_ROOT}/scripts/dogfood-derive.cjs
+```
+
+## Examples
+
+```
+/mos:dogfood-flush
+```
+
+## Exit codes
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Success (including soft-fail paths: room.db missing, empty queue, no STATE.md) |
+
+## Cross-surface adaptation
+
+- **CLI:** full power. Slash command resolves via Claude Code's plugin hook
+  substrate and runs the two scripts through the Bash tool. F.0 report
+  renders in the terminal.
+- **Desktop:** the same slash command runs when the plugin is connected.
+  Larry may narrate the result conversationally; the underlying scripts
+  are identical.
+- **Cowork:** same as CLI. Team members see the regenerated STATE.md
+  `## Live (auto)` block through the shared `~/MindrianRooms/mindrian/`
+  snapshot on their next session-start.
+
+No surface-specific code exists anywhere in either script.