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

package/commands/explore-opportunity.md

@@ -0,0 +1,172 @@
+---
+name: explore-opportunity
+description: Run the explored-stage analysis chain on a qualified opportunity
+help_jtbd: "Turn a qualified opportunity into a deep-researched, Minto-shaped, evidence-backed analysis."
+argument-hint: "[opportunity]"
+body_shape: E (Action Report)
+hitl_shape: "F.1"
+hitl_why: "Exploration spends navigator-controlled research cost and crosses material gates; explicit per-opportunity trigger only - never auto-fired on qualify."
+# Phase 265-04 reward-before-investment declaration (blocking-gate auto-fix, not
+# the dedicated ~85-command backfill phase named in docs/reward-before-investment-rule.md).
+# Grounded in the shipped chain below: the four analysis legs (web evidence, timing,
+# analogs, demand validation) run and their findings are visible at the material filing
+# gate as a structural preview of the Minto-shaped explored artifact, before the
+# navigator invests in the approve verb that actually files it.
+interactive_first_reward: schema_preview
+serves_jtbd: ["explore"]
+teaching: "A qualified opportunity is still conceptual: a connection without a defined problem. /mos:explore-opportunity runs the analysis chain (deep research, diffusion timing, analogies, web validation) and files a Minto-shaped explored artifact - a governing thought backed by cited sources and typed graph evidence. Opportunities must be researched and explored to become well-defined problems; this is that step, and its cost stays in your hands."
+allowed-tools:
+  - Read
+  - Bash
+  - WebSearch
+  - WebFetch
+  - AskUserQuestion
+# --- Phase 219-05 connector frontmatter (born-wired, Canon Part 11 CIRS R1 / D-10) ---
+connector:
+  connects_to_spine: true
+  sensor_triggers: []
+  reach_id: deep_research
+  sub_mode: explore-opportunity
+  framework: null
+  posture: hold
+  hierarchy_rank: 5
+  filing: none
+  plan_gated: true                 # rides the sanctioned deep_research exception (D-07)
+  web_scope: green
+  surface: F.1
+---
+
+<!-- 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:explore-opportunity -- The Explored-Stage Analysis Chain
+
+> The EXPLICIT [Explore] action on a QUALIFIED opportunity (REQ-4). It NEVER auto-fires on
+> Qualify (navigator cost control, T-219-18): you trigger it per opportunity, and material
+> steps halt at real gates (Canon Part 3). The output must read as ANALYZED - a governing
+> thought with cited web sources and typed graph evidence, never a candidate one-liner.
+
+## How It Works
+
+The chain composes through the SHIPPED machinery only (D-06): framework names resolve to
+registry commands via `lib/workflow/command-resolver.cjs::composeWorkflow` (zero hardcoded
+slugs; a framework with no command degrades honestly to a manual step), and
+`lib/core/chain-executor.cjs::runChain` is the one gated loop. The entry point is
+`lib/core/eureka/explore-chain.cjs::exploreOpportunity(roomDir, opportunityNodeId, opts)`.
+
+The four analysis legs, in order:
+
+| Leg | Framework (registry-resolved) | What it contributes |
+|-----|-------------------------------|---------------------|
+| deep_research | Hypothesis-Driven Problem Solving | web evidence via the FROZEN deep_research reach (generic handles only, Part 8; the framework-runner's existing egress chokepoint - never a raw fetch) |
+| diffusion_timing | Adoption-Capacity Theory | is the window open? (current Track-1-unrewired form, D-07) |
+| analogies | Four Lenses of Innovation | analog domains that solved this shape of problem |
+| web_validation | Jobs to Be Done (JTBD) | demand validation against the customer segment |
+
+### How the four legs dispatch, and what bounds the cost
+
+The four legs are analytically INDEPENDENT: each is a separate framing of the same fixed
+opportunity node (web evidence, timing, analogs, demand validation). No leg consumes another
+leg's output for its own analysis -- the `prev` parameter threaded through `onStep` carries
+provenance plus the offline-degrade and engine_mode stamping, not analytical input. Because of
+that independence, three of the four legs now run **in parallel**: `diffusion_timing`,
+`analogies` and `web_validation` fire concurrently, because there was never a data dependency
+between them to begin with (`lib/core/eureka/explore-chain.cjs::runAnalysisLegsParallel`,
+Phase 265-18). `deep_research` still runs FIRST, alone, as a probe.
+
+**The cost guard -- read this before assuming parallel means "spend everything".** The
+sequential chain's `quality_early_stop` (`lib/core/chain-executor.cjs::runChain`) used to end
+the run the moment a step returned LOW quality, which meant a cold `deep_research` leg
+returning `insufficient_evidence` never spent the other three legs, honoring this command's own
+`hitl_why` commitment that "Exploration spends navigator-controlled research cost." Parallel
+dispatch has no "early" left to stop at once three legs are already firing together -- so the
+guard did NOT get dropped, it moved one step earlier: `resolveExploreCostPolicy` decides the
+mode and `probeClears` evaluates the `deep_research` probe leg with the EXACT SAME quality test
+`quality_early_stop` applied, and the remaining three legs are dispatched only when the probe
+clears. Plainly: a cold corpus still costs one leg, not four.
+
+**The override.** `EXPLORE_COST_MODE` picks the mode: `cost-conscious` (the default) runs the
+probe-first guard above; `all-legs` skips the probe and fans all four legs concurrently
+unconditionally. An unrecognized value falls back to `cost-conscious` -- a typo can never select
+the more expensive path. `EXPLORE_PARALLEL=0` is the operator escape hatch: it forces the
+original sequential `runChain` path regardless of cost mode.
+
+**The fallback, never silent.** If the parallel pre-pass throws, if the engine is absent (the
+D-20 OFFER below), or if `EXPLORE_PARALLEL=0`, the run falls back to the existing sequential
+`runChain` path and reports exactly which path ran and why in the `dispatch` key of
+`exploreOpportunity`'s return (`{mode: 'sequential'|'parallel', reason, ...}`).
+
+**What did not change.** The material filing step still runs through `runChain` with its
+unchanged `gateFn`, so filing still halts for your approve verb and nothing files without it.
+`lib/core/chain-executor.cjs` has zero diff, and the Phase 264 zero-diff gate in
+`tests/run-all-264.sh` (base SHA `c7c33eea449f6f227c4cfbb86f220acaac9b5ab8`) still passes.
+
+The navigator settled parallelizing these legs as `build-now-in-265` (265-04 Task 3); the build
+landed in Phase 265 plan 265-18. This is an in-process `Promise.all` fan-out inside
+`lib/core/eureka/explore-chain.cjs`, not a subagent dispatch, so this command needs no `Task` /
+`Agent` grant in its `allowed-tools` for it.
+
+Then the MATERIAL filing step halts at the gate. On your approve verb:
+
+1. **Research corpus artifact (D-16 item 1):** files nested as
+   `research/<dated-slug>/<dated-slug>.md` with frontmatter (date, url-cited sources with
+   accessed dates, topic handles) and registers as a `memory_artifact` graph citizen.
+2. **Minto explored artifact (D-08):** governing thought + SCQA + MECE sections + citations,
+   validated by `feynman-minto-invariants` BEFORE filing, nested per Decision 16 at
+   `opportunity-bank/<section>/<name>/<name>.md` (real domain-slug section, 216 contract);
+   re-exploration updates in place via the `problem_hash` dedup.
+3. **Graph wiring:** >=2 typed evidence edges (SUPPORTS/INFORMS), lifecycle + stage advance
+   to `explored` through `advanceOpportunityStage` (D-17 append-only stage_history).
+4. **Post-filing extraction (D-16 item 2):** the 218 extractor runs scoped to exactly the
+   new artifact paths (`opts.paths` seam - never a full-room re-extract); extracted entities
+   land proposed with DERIVED_FROM edges to the artifact node. The research is graph-visible
+   to ALL engines at filing time.
+
+## Offline Degrade (D-16 item 3)
+
+When the web leg is unavailable, the chain queries the room's OWN research corpus
+(tri-modal retrieval scoped to `research/` artifacts) with the step provenance
+`web: absent (room-corpus degrade)` and the run typed `web_degraded_local_fallback`.
+A COLD corpus returns `insufficient_evidence` with zero fabricated results and files
+nothing - never a crash, never a silent skip (D-19).
+
+## D-20: The Engine-Unavailable Offer
+
+When a chain step's engine cannot run (probe failures beyond the graceful rungs, crash,
+missing substrate), the chain HALTS at a gate OFFERING **[LLM manual run (high effort)]**:
+the model performs the analysis directly via the frozen deep_research reach + native web
+tools (same Part 8 handles). NEVER the default, NEVER a silent substitution (the corepower
+lesson). Manual output carries `engine_mode: llm_manual_baseline` in the run trace and every
+filed artifact's frontmatter, and is EXCLUDED from calibration sets by that marker.
+
+Test seam: `MINDRIAN_FORCE_ENGINE_ABSENT=1`.
+
+## What This Command Does NOT Do
+
+- It does NOT fire on Qualify. Qualification (`/mos:qualify-opportunity`) and exploration
+  are SEPARATE material decisions; a qualified opportunity waits until you explicitly
+  explore it.
+- It does NOT explore candidates. A non-qualified opportunity is refused with
+  `not_qualified` - the human gate always precedes the spend.
+- It does NOT mint sub-rooms. A promoted opportunity graduating to its own workspace is a
+  follow-on (D-21: sub-room minting is out of v1 scope).
+
+## Canon Compliance
+
+- **Part 3**: the autonomous_safe prefix runs; filing is material and halts at the gate.
+- **Part 8**: the web legs carry generic handles through the existing audited egress
+  chokepoint; all graph writes are LOCAL room.db via navigation.cjs.
+- **Part 9**: extracted entities land `proposed`; only human confirms promote.
+- **Part 11 (CIRS)**: born WIRED - explicit surface, hitl_shape F.1 declared above.
+- **Part 12**: the explored artifact teaches the analysis, not just the verdict.

package/commands/explore-trends.md

@@ -0,0 +1,78 @@
+---
+name: explore-trends
+description: Push trends to extremes to surface future problems
+help_jtbd: "Surface the macro trends your venture is riding."
+body_shape: "methodology"
+hitl_shape: "F.3"
+hitl_why: "It pushes one trend toward its extreme and asks how far to go, a depth budget."
+serves_jtbd: ["understand-market", "explore"]
+# Phase 265-13 reward-before-investment backfill (field only; grounded in the
+# shipped Session Flow: naming one trend previews the extrapolation-to-absurd
+# structure before the navigator invests in the full push).
+interactive_first_reward: schema_preview
+teaching: "When today's trends could become tomorrow's problems, /mos:explore-trends pushes them to extremes to surface the second-order effects. The future shows up at the edges first."
+# --- Phase 122 workflow-layer frontmatter ---
+kind: methodology
+frameworks: ["S-Curve Analysis"]
+produces: "room/**/trends/*"
+inputs: []
+autonomous_safe: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+# --- Phase 143.3 connector frontmatter ---
+connector:
+  connects_to_spine: true
+  sensor_triggers: [SENS-04]
+  reach_id: context_block
+  sub_mode: trends-scurve
+  framework: "S-Curve Analysis"
+  posture: push_forward
+  hierarchy_rank: 32
+  filing: fileEvidenceWithReadback
+  plan_gated: false
+  web_scope: null
+---
+
+<!-- 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:explore-trends
+
+You are Larry. This command guides the user through the Trending to the Absurd framework.
+
+## Setup
+
+1. Read `${CLAUDE_PLUGIN_ROOT}/references/methodology/explore-trends.md` for framework details
+2. Read `${CLAUDE_PLUGIN_ROOT}/references/personality/voice-dna.md` for Larry's voice
+3. Read `room/STATE.md` for venture context (if exists)
+
+## Session Flow
+
+Ask: "Quick pass or deep dive?"
+
+Then follow the framework phases from the reference file. Start by identifying the trend and its velocity. Then push it to the absurd -- if the scenario feels comfortable, they have not gone far enough.
+
+No solutions before problems. That is not a suggestion. That is the rule.
+
+## When Complete
+
+Create the artifact using the template from the reference file.
+Ask: "File this to market-analysis?" before writing.
+
+If the conversation reveals a connection to another methodology, suggest it:
+"The future you explored connects to /mos:research. Want to explore that next?"

package/commands/export.md

@@ -0,0 +1,128 @@
+---
+name: export
+description: Export a Data Room view to De Stijl HTML
+help_jtbd: "Ship investor-ready PDF or Obsidian vault of your room."
+argument-hint: "[hub|thesis|summary|report]"
+disable-model-invocation: true
+body_shape: E (Action Report)
+hitl_shape: "F.1"
+hitl_why: "Export offers a single next move to confirm the export scope."
+# Phase 267.3-06, ruled in 267.3-CLASSIFICATION.md (Row 11, argued in full): first delivery at commands/export.md:68, a filed, shareable HTML artifact of the whole Data Room, the "filed document" leg of live_deliverable's own definition.
+interactive_first_reward: live_deliverable
+serves_jtbd: ["prepare-pitch"]
+teaching: "When you need to share a Data Room view with someone outside the room, /mos:export packages it as a De Stijl HTML artifact. Investor-ready, no install required on their side."
+ui_reference: skills/ui-system/SKILL.md
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+# --- Phase 172-06 CIRS R1 exclude (Canon Part 11) ---
+connector:
+  excluded: true
+  reason: "Render command. Produces an export artifact on explicit navigator request; it serializes existing room state and is not contextually triggered."
+---
+
+<!-- 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 -->
+
+You are Larry, the PWS methodology guide inside MindrianOS. The user wants to export their Data Room work as a professional PDF document.
+
+## Determine Document Type
+
+Parse the user's argument to determine which document type they want. If no argument is provided, or they say "help", show the available types:
+
+**Available export types:**
+
+| Type | Command | What You Get |
+|------|---------|-------------|
+| **hub** | `/mos:export hub` | **DEFAULT.** Single-file De Stijl tabbed hub with all content inline -- the same format as synteris-hub. Shareable, deployable, works offline. |
+| **dashboard** | `/mos:export dashboard` | Interactive Cytoscape.js knowledge graph dashboard -- standalone HTML with graph visualization. Better for small rooms. |
+| **thesis** | `/mos:export thesis` | Investment thesis: multi-page narrative covering your full venture analysis. Includes all populated room sections with De Stijl accent bars and running headers. |
+| **summary** | `/mos:export summary` | Executive summary: dense 1-2 page overview for quick stakeholder review. Two-column layout with financial metrics box. |
+| **report** | `/mos:export report` | Due diligence report: comprehensive numbered sections with table of contents and PDF bookmarks. |
+| **profile** | `/mos:export profile` | PWS Profile: single-page professional profile built from your methodology work -- domain expertise, thinking perspectives, customer understanding, and professional background. |
+| **meeting-report** | `/mos:export meeting-report` | Meeting intelligence report: Minto pyramid structure covering all meetings with speaker attribution, decisions, contradictions, and section-colored filing indicators. |
+
+## Generate Hub Export (DEFAULT)
+
+If the user requests `hub`, or runs `/mos:export` with no argument, or says "export my room":
+
+1. **Check the room exists.** If `room/` directory does not exist, tell the user to run `/mos:new-project`.
+
+2. **Run the hub generator (MANDATORY -- never generate HTML by hand):**
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/generate-hub.cjs" ./room
+   ```
+
+3. **Report the result:**
+   > "Your Data Room snapshot is at `room/exports/hub.html`. Single file -- open it in any browser, send it by email, or deploy to Vercel. Everything is inline."
+
+4. **If `--open` or user says "open it":** Open in browser with OS-appropriate command.
+
+## Generate Dashboard Export
+
+If the user specifically requests `dashboard`:
+
+1. **Check the room exists.** If `room/` directory does not exist, tell the user to run `/mos:new-project`.
+
+2. **Run the standalone generator:**
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/scripts/generate-standalone" ./room
+   ```
+
+3. **Report the result:**
+   > "Your knowledge graph dashboard is at `room/data-room-dashboard.html`. Open it in any browser -- Cytoscape visualization with graph intelligence. Note: for rooms with 30+ artifacts, the hub format (`/mos:export hub`) usually looks better."
+
+## Generate the PDF
+
+If a valid PDF document type is provided:
+
+1. **Check the room exists.** If `room/` directory does not exist, tell the user:
+   > "You don't have a Data Room yet. Run `/mos:new-project` to set one up, then come back for that export."
+
+2. **Run the render script:**
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/render-pdf" {type} --room room/
+   ```
+
+3. **Report the result** in Larry's voice:
+   > "Your {type} is ready! Check `room/exports/` -- I used your {N} room sections to build it."
+
+4. **If some sections are empty**, mention them helpfully:
+   > "A few sections are still empty ({list}). Fill those in and re-export for an even stronger document."
+
+## PWS Profile -- Special Guidance (DOCS-05)
+
+The profile document type is unique -- it pulls from your methodology outputs, not just raw room entries:
+
+- **Domain Expertise** (top-left): Populated from `/mos:explore-domains` outputs
+- **Thinking Perspectives** (top-right): Populated from `/mos:think-hats` outputs
+- **Customer Understanding** (bottom-left): Populated from `/mos:analyze-needs` / JTBD outputs
+- **Professional Background** (bottom-right): Populated from team-execution room entries
+
+If the profile looks sparse, suggest:
+> "Your profile will look sharper with more methodology outputs. Try running `/mos:think-hats` and `/mos:explore-domains` first -- those feed directly into your profile grid."
+
+## Surface Behavior
+
+- **CLI:** The render-pdf script runs directly, generates the PDF, and opens it automatically with the system viewer.
+- **Desktop:** Larry can proactively offer export after key milestones -- "You've filled 5 sections now. Want me to generate a thesis draft so you can see how it's shaping up?"
+- **Cowork:** In shared workspaces, export to `00_Context/exports/` so team members can review. Mention: "I put the export in the shared context folder so your team can see it."
+
+## Error Handling
+
+- If the user provides an invalid document type, show the table above and suggest the closest match.
+- If PDF generation fails, check that font files exist in `assets/fonts/` and suggest re-running `/mos:setup` if needed.
+- If the room has no content at all, guide them to start with a methodology: "Your room is empty -- try `/mos:lean-canvas` or `/mos:explore-domains` to get some content in there first."

package/commands/feynman-timeline-refresh.md

@@ -0,0 +1,102 @@
+---
+description: Refresh FEYNMAN.md ## Timeline (auto) section for one or all room sections
+help_jtbd: "Refresh the human-readable Timeline section in FEYNMAN.md."
+body_shape: E
+hitl_shape: "F.0"
+hitl_why: "It offers a single timeline-refresh action to approve or defer."
+# Phase 267.3-06, ruled in 267.3-CLASSIFICATION.md (Row 12): first delivery at commands/feynman-timeline-refresh.md:49, an F.0 Action Report of sections refreshed/skipped/failed, a regeneration-status report.
+interactive_first_reward: "--none (diagnostic surface)"
+argument-hint: "[--all | --section <slug>]"
+serves_jtbd: ["validate-idea", "audit-room"]
+teaching: "When a section's FEYNMAN.md timeline feels stale, /mos:feynman-timeline-refresh rebuilds the auto-section from the memory event log. Human-authored prose stays byte-preserved."
+disable-model-invocation: false
+allowed-tools: Bash(node *), AskUserQuestion
+kind: utility
+frameworks: []
+produces: "room/*/FEYNMAN.md"
+inputs: []
+autonomous_safe: true
+# --- Phase 172-06 CIRS R1 exclude (Canon Part 11) ---
+connector:
+  excluded: true
+  reason: "Lifecycle command. Regenerates the FEYNMAN.md auto-timeline; a maintenance refresh fired by the session-start cascade or manual run, not a contextual reach."
+---
+
+<!-- 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:feynman-timeline-refresh
+
+Force-refresh the `## Timeline (auto)` sentinel-bounded section in each section's `FEYNMAN.md`. The renderer reads from `room.db` via the Phase 109 `navigation.cjs` chokepoint; the runner writes back atomically with the human-authored body byte-preserved. This is the manual knob the user reaches for when the automatic session-start cascade is not enough -- explicit redraw, ignore the watermark.
+
+## Modes
+
+- `/mos:feynman-timeline-refresh` -- refresh every section in the active room (default; equivalent to `--all`).
+- `/mos:feynman-timeline-refresh --all` -- refresh every section in the active room.
+- `/mos:feynman-timeline-refresh --section <slug>` -- refresh one section.
+
+## Output
+
+F.0 Action Report (Canon Part 3 UI Ruling System; same shape as `/mos:brain-derive`'s Shape E). Three summary rows + a PER SECTION breakdown + a NEXT action footer:
+
+- Sections refreshed: N
+- Sections skipped (watermark fresh): S
+- Sections failed: F
+
+When more than 3 target sections, per-section progress streams to stderr as each completes: `[1/7] market-analysis: refreshed`. The final report renders to stdout at the end.
+
+## Graceful degradation
+
+- **No active room**: exit 1 with "Set one with /mos:rooms switch <slug>".
+- **Invalid section slug**: exit 1 with a pointer to the active room and a hint to list sections.
+- **room.db missing**: single-line "room.db not found for active room; the runner needs the Phase 109 SQL spine" message, exit 0 (soft-fail; the timeline section is enrichment, not a gate).
+- **Runner exception per section**: the failure is logged via `feynman_timeline_refresh_failed` memory_event; the per-section row in the report names the failure; other sections still process.
+
+## Canon references
+
+- **Canon Part 3 (Tri-Context Decision Gate)**: output uses the F.0 / Shape E Action Report so the user sees a LOCAL snapshot of what was refreshed.
+- **Canon Part 7 (Reuse Before Build)**: the command wraps `lib/core/feynman/timeline-runner.cjs` (Plan 124-02). No new render logic at the command layer.
+- **Canon Part 8 (Graph Boundary)**: zero net new Brain surface. The renderer reads ONLY `room.db` via `navigation.cjs`. The runner writes ONLY FEYNMAN.md inside the sentinels.
+- **Canon Part 9 (Memory Locality)**: this is the Larry-explains face of `memory_event` -- the rendered timeline section IS the human-readable view of the SQL log.
+
+## Invocation
+
+Run the dispatcher via Bash:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/feynman-timeline-refresh-command.cjs $ARGUMENTS
+```
+
+## Examples
+
+```
+/mos:feynman-timeline-refresh
+/mos:feynman-timeline-refresh --all
+/mos:feynman-timeline-refresh --section market-analysis
+```
+
+## Exit codes
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Success (including soft-fail paths: room.db missing, every section watermark-skipped) |
+| 1 | Invocation error: no active room, invalid section slug, malformed args |
+
+## Cross-surface adaptation
+
+- **CLI**: full power. Slash command resolves via Claude Code's plugin hook substrate and runs the dispatcher 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 dispatcher is identical.
+- **Cowork**: same as CLI. Team members see the regenerated FEYNMAN.md `## Timeline (auto)` block through the shared `00_Context/` snapshot on their next session-start.
+
+No surface-specific code exists anywhere in the dispatcher.