@ritualai/cli 0.7.13 → 0.7.15

package/skills/codex/ritual/references/resume-flow.md

@@ -85,25 +85,47 @@ If exactly one in-flight exploration is recent and clearly the likely target, le
 >
 > Resume this? (Y/n, or `list`)
 
-If there are multiple plausible targets, group by state badge and show:
+If there are multiple plausible targets, group by state badge and show. **One picker number per exploration; continuation prose is plain text under it, never its own list item.** Use the exact shape below:
 
 > Here's what you have in flight in **{workspace.name}**:
 >
-> **📍 still in discovery** (1)
-> - **{name}** — {first 80 chars of problemStatement}
->   *Last touched {N} {days/hours} ago. Next: continue sub-problem generation.*
+> **📍 still in discovery** ({count})
 >
-> **💬 waiting on admin to accept recommendations** (2)
-> - **{name}** — {…}
->   *Last touched {N} days ago. Next: admin reviews + accepts in Step 9.*
-> - **{name}** — {…}
->   *…*
+> 1. **{name}** — {first 80 chars of problemStatement}
+>    Last touched {N} {days/hours} ago. Next: continue sub-problem generation.
 >
-> **✅ ready for build brief** (1)
-> - **{name}** — {…}
->   *Last touched {N} days ago. Next: generate the build brief.*
+> **💬 waiting on admin to accept recommendations** ({count})
 >
-> **Which one do you want to resume? (give me the number/name, or "none" to exit)**
+> 2. **{name}** — {…}
+>    Last touched {N} days ago. Next: admin reviews + accepts in Step 9.
+> 3. **{name}** — {…}
+>    Last touched {N} days ago. Next: …
+>
+> **✅ ready for build brief** ({count})
+>
+> 4. **{name}** — {…}
+>    Last touched {N} days ago. Next: generate the build brief.
+>
+> **Which one do you want to resume? Reply with the number, the name, or `none` to exit.**
+
+**Rendering anti-pattern (load-bearing) — observed 2026-05-15:**
+
+- ❌ Numbering the SAME exploration's continuation lines (summary, "Last touched", "Next") as separate numbered items:
+  ```text
+  1. Social shopping — activate wishlist sharing
+  1. Activate dormant wishlist sharing primitives...
+  1. Last touched ~10 min ago. Next: generate the build brief.
+  2. Join while booking — post-order account claim
+  2. Post-checkout account creation flow...
+  2. Last touched ~2 hours ago. Next: admin reviews + accepts.
+  ```
+  Three `1.` lines + three `2.` lines is wrong. **Each exploration gets ONE picker number on its title line. The summary, last-touched, and next-action lines belong to that exploration as indented continuation prose — never their own numbered or bulleted entries.**
+
+- ❌ Using `-` bullets for explorations when the picker tells the user "reply with the number." Bullets have no numbers; the user can't say "I pick `-`."
+
+- ❌ Restarting the picker count at each state bucket (`1.` under "still in discovery", then `1.` again under "waiting on admin"). Numbering is **flat across all buckets** so a single number unambiguously identifies one exploration.
+
+**The correct shape is exactly:** state-bucket header → blank line → `{N}. **{name}** — {summary}` → indented continuation prose (2-space indent, no leading marker) → blank line before next exploration. State-bucket count in parens `({count})` is informational and is NEVER a picker number.
 
 State badge → user-facing label + suggested next step (same table as `/ritual build` Step 1.5):
 

package/skills/codex/ritual/references/status-flow.md

@@ -0,0 +1,94 @@
+## /ritual status
+
+Thin in-chat mirror of the terminal CLI command `ritual status [--watch]` (CLI 0.7.14+).
+
+The CLI is the primary affordance for the "I walked away from this run; let me check on it" case — it works from any terminal, survives this agent session closing, and supports `--watch` for live tail. **This SKILL subcommand exists for the orthogonal case:** the user is still in the agent session, wants a quick status snapshot, and doesn't want to context-switch to a separate terminal.
+
+Same content, two surfaces. Pick whichever fits the user's flow.
+
+### When to use this vs. the terminal CLI
+
+| Context | Use |
+|---|---|
+| User is in chat with you and types `/ritual status` | This SKILL subcommand. |
+| User is mid-run and walks away | Tell them about `ritual status --watch` in a separate terminal. Their session can close; the CLI keeps tailing. |
+| User wants to script status / pipe to other tools | Terminal CLI. The SKILL is render-only; the CLI prints to stdout with proper exit codes. |
+| User asks "what's happening?" without typing the slash | Plain English answer — call `mcp__ritual__get_agentic_run` and respond naturally. Don't gratuitously invoke this subcommand. |
+
+### Steps
+
+#### Step S1 — Resolve the run
+
+The subcommand can be invoked three ways:
+
+1. **`/ritual status`** (no arg) — auto-resolve the current run from workspace context:
+   - If `.ritual/config.json` is bound (i.e. `/ritual init` was run in this repo), load `workspaceId` from there.
+   - Call `mcp__ritual__list_explorations(workspace_id)`, sort by `updatedAt` desc.
+   - For each of the top 5 most-recently-updated, call `mcp__ritual__list_agentic_runs(exploration_id, status='RUNNING', limit=1)` until one returns a run.
+   - If none has a RUNNING run, fall back to the most-recently-updated exploration with step != `COMPLETED`.
+   - If no workspace is bound to the project, ask the user for an exploration id or to run `/ritual init` first.
+
+2. **`/ritual status <exploration-id>`** — skip auto-resolve, fetch that exploration directly.
+
+3. **`/ritual status --runs`** — list every RUNNING agentic run across the workspace (multi-run case). Render as a numbered picker.
+
+#### Step S2 — Fetch state
+
+Call in parallel:
+
+- `mcp__ritual__get_exploration(exploration_id)` → exploration name, step, updatedAt, agenticProgress.
+- `mcp__ritual__get_agentic_run(run_id)` IF a RUNNING run was found — gives live progress + run id + status. Read from the **merged view** the MCP tool returns; never from raw `agentic_jobs.totalQuestions` or `agentic_jobs.progress.steps` directly (those fields have a known unwritten-for-`full_exploration_v1` bug).
+
+#### Step S3 — Render the run-first layout
+
+Mirror the terminal CLI exactly. Run line first, exploration name as a footer parenthetical:
+
+```text
+Run        ba4d2b42-…  ·  RUNNING for 17m 41s
+Phase      answering  (58%)
+Questions  42 / 67  ·  0 failed
+Activity   last DB write 1m 12s ago
+Pace       ~14s/question  ·  ETA ~5m 50s remaining
+Next       Recommendations (auto-advances when questions are done)
+
+(Exploration: Join while booking — post-order account claim)
+  51f16182-…  ·  step: DEVELOPING_ANSWERS
+```
+
+Rendering rules:
+
+- **Run line first.** "RUNNING for 17m 41s" is the headline.
+- **Pace + ETA** computed client-side from `(now - run.startedAt) / progress.completedQuestions × (totalQuestions - completedQuestions)`. Only show when `completedQuestions >= 3` — below that, render `Pace       warming up — check back in 30s`.
+- **Activity** is the freshness signal — if `last write` has been climbing past ~3 min without `completedQuestions` advancing, that's actionable info. Surface it plainly; do not invent a "stuck" diagnosis (that's `RecStallSweeper`'s job, server-side).
+- **Next line** is heuristic based on `progress.phase`:
+  - `answering` → `Recommendations (auto-advances when questions are done)`
+  - `submitting` → `Recommendations`
+  - `recommendations` → `Build brief (after admin review)`
+  - `complete` / `failed` → `—`
+  - any unknown → omit the line entirely
+- **No run, but progress data exists** (run completed or never started): render `Run        (no active run)` + phase + Activity. Useful when the user types `/ritual status` after a run finished.
+- **No run, no progress**: render `Run        (no run started yet)` + Step + Activity.
+
+#### Step S4 — Wrap up
+
+After rendering, the agent's job is done. Do NOT auto-poll, do NOT enter a watch loop inside the chat. The CLI's `--watch` is the live-tail surface; this SKILL is a snapshot.
+
+If the user wants to check again, they type `/ritual status` again. The agent re-runs S1–S3 from scratch.
+
+### Tools used
+
+Read-tier subset of the build-flow tools:
+
+1. `mcp__ritual__list_explorations` (auto-resolve)
+2. `mcp__ritual__list_agentic_runs` (find RUNNING)
+3. `mcp__ritual__get_exploration` (S2 — name + step + progress)
+4. `mcp__ritual__get_agentic_run` (S2 — merged live view)
+
+No new MCP tools required. `/ritual status` is a thin orchestration over what already exists.
+
+### Anti-patterns
+
+- **Don't introduce a "watch" mode inside this SKILL.** The terminal CLI's `--watch` is the live-tail surface. Re-implementing it in chat doubles the affordance and creates polling loops that survive past the user's intent.
+- **Don't render raw `agentic_jobs` fields.** `AgenticJob.totalQuestions` and `progress.steps[*].status` are not written for `full_exploration_v1` runs. Reading them directly produces the "all-pending" snapshot lie surfaced 2026-05-15. The merged view returned by `get_agentic_run` is the only correct source.
+- **Don't synthesize ETA from `progress.percent` alone.** Use the question-count math (`completedQuestions / elapsed × remaining`) because it's more accurate than the coarse percent rounded up at major step boundaries.
+- **Don't gratuitously invoke this subcommand.** If the user asks "what's happening?" without typing `/ritual status`, just answer in plain English using `get_agentic_run`. The slash-command is for explicit status snapshots, not for every progress question.

package/skills/codex/ritual/references/ui-ux-checklist.md

@@ -0,0 +1,198 @@
+## UX brief review — methodology + output schema
+
+Reference for `/ritual build` Step 10.5 (the opt-in `ux-review` path) and any standalone caller that needs the same shape.
+
+The brief that came out of Step 10 is implementation-ready from a *what* standpoint (RBs, requirements, acceptance criteria). This review is implementation-ready from an *experience* standpoint — the things coding-agent plan mode otherwise interrogates the user for, surfaced and answered with evidence before any code is touched.
+
+The output is a single file, `UX-REVIEW.md`, written alongside `BUILD-BRIEF.md`. It is repo-grounded (every claim cites a brief line or a repo analogue), brief-aware (does not re-derive what the brief already nails), and auditable (gaps and mismatches surface explicitly rather than buried in prose).
+
+---
+
+### Core principle
+
+**Make the coding agent reason about the experience before it reasons about files.**
+
+The plan mode prompt at the end of `UX-REVIEW.md` is the load-bearing artifact. Plan mode reads it on entry instead of inventing its own questions.
+
+---
+
+### Methodology (chain of thought — execute in this order)
+
+Do NOT skip to the output schema. Walk these six steps; the schema only gets filled correctly when the analysis upstream is done.
+
+**1. Read the brief end-to-end first.**
+
+Open `BUILD-BRIEF.md`. Identify what it covers vs what it's silent on. The brief itself is signal:
+
+- An exhaustive states table → most state sections will be "covered in BUILD-BRIEF.md §X; no additions needed."
+- A missing copy section → that's where to focus; copy is high-leverage and almost always under-specified.
+- A "Non-goals" section listing UI surfaces explicitly out of scope → DO NOT add UX recommendations that contradict the non-goals.
+
+Output of this step: a one-line classification of the brief — what's well-covered (skip in the review), what's thin (deep-dive in the review), what's silent (gap-flag in the review).
+
+**2. Identify the UI surfaces the brief implies.**
+
+Pull a list of every screen, component, modal, drawer, form, list, page, route, view, dashboard, panel, toast, banner, etc. that the brief mentions or implies. Be literal — if the brief says "users see a confirmation," that implies at minimum: a confirmation surface + the action that triggered it + the dismissal path.
+
+Output of this step: a flat list of UI surfaces with one-line "purpose" each.
+
+**3. For each implied surface, find existing analogues in the repo.**
+
+Use Grep / Glob / Read. Search by:
+
+- Exact name: `<surface>` (e.g. `ConfirmModal`, `EmptyState`, `DrawerPanel`).
+- Component-library import: imports from the repo's design-system package, `@radix-ui/*`, `shadcn-ui`, `@mui/material`, `@chakra-ui/*`, etc.
+- Route shape: similar `/path/to/feature` routes already in the app.
+- Sibling features: features one directory over that ship the same shape.
+
+Output of this step: for each implied surface from step 2, the closest existing analogue (file path + ~5-10 line excerpt of the relevant pattern) OR `"no analogue found — new pattern needed"`.
+
+**4. Compare brief requirements vs analogue patterns.**
+
+For each (implied surface, analogue) pair, classify:
+
+- **Covered** — brief specifies X, analogue already handles X. Skip in the review or note as "use existing pattern, no decisions needed."
+- **Mismatch** — brief asks for X, analogue does Y. Surface for plan mode: is this intentional (the new feature deliberately diverges) or unintentional (the brief was written without knowing the analogue exists)?
+- **Gap** — brief silent on X, but X is standard in this codebase (the analogue always handles X). Surface for plan mode: the brief should specify, or the agent should follow the codebase default.
+- **New work** — brief specifies X, no analogue. Flag: this surface needs to be designed, not extended.
+
+Output of this step: three lists — mismatches, gaps, new-work surfaces. With evidence (file path / line / brief reference) on each entry.
+
+**5. Fill the 12 sections WITH EVIDENCE.**
+
+Now — and only now — fill the output schema below. Rules:
+
+- Each claim cites either a `BUILD-BRIEF.md §X` line OR a repo file path. Both is better.
+- Sections the brief already covers get one line: *"Covered in BUILD-BRIEF.md §<section>; no additions needed."* Do not re-derive.
+- Sections the brief is silent on but the codebase implies a default for: *"Brief silent. Codebase default (`<path>`): <one-line pattern>. Recommend following the default."*
+- Sections that are real gaps: *"Brief silent. No codebase default. Plan mode must address: <one-line question>."*
+- States that the brief does not require: omit. An empty state entry means "the brief does not require this state and the analogue does not either" — that is a valid signal.
+
+**6. Generate the plan-mode prompt with the surfaced findings.**
+
+The plan-mode prompt is NOT generic. Its first three numbered items are the surfaced mismatches, gaps, and new-work surfaces from step 4. Plan mode then has to address those specifically — not walk a generic 10-step plan.
+
+The plan-mode prompt MUST end with the literal sentence:
+
+> Do not start coding until the plan is approved.
+
+---
+
+### Output schema — `UX-REVIEW.md`
+
+Render exactly the sections below. Every section MUST exist (use the "Covered in BUILD-BRIEF.md" / "Brief silent" patterns rather than skipping). Sub-state entries under "States" are the only optional content.
+
+```markdown
+<!--
+Generated by Ritual — UX brief review
+Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+Source brief: BUILD-BRIEF.md
+Do not remove this header; it preserves implementation lineage.
+-->
+
+# UX Brief Review — {exploration name}
+
+## User Goal
+
+{What the user is trying to accomplish. Cite the brief's Goal section. One paragraph max.}
+
+## Primary Flow
+
+{Step-by-step happy path from the user's perspective. Cite brief lines. If the brief already enumerates this, write "Covered in BUILD-BRIEF.md §<section>" + a one-line summary.}
+
+## Screen / Component Requirements
+
+{What UI needs to exist, including layout, hierarchy, states, and interactions. For each surface: the implied surface from methodology step 2 + its closest repo analogue from step 3 + whether it's covered / mismatch / gap / new work from step 4.}
+
+## Interaction Details
+
+{Clicks, hovers, keyboard behavior, drag/drop, focus, transitions, gestures. Cite the analogue's existing interaction patterns when reusing; specify deliberately when diverging.}
+
+## States
+
+(omit any state the brief does not require AND the analogue does not handle)
+
+- **Empty**: {description + analogue path or "new"}
+- **Loading**: {description + analogue path or "new"}
+- **Error**: {description + analogue path or "new" — include error message tone if the codebase has a convention}
+- **Success**: {description + analogue path or "new"}
+- **Disabled**: {description + analogue path or "new"}
+- **Permission-restricted**: {description + analogue path or "new"}
+- **Mobile / narrow**: {description + breakpoint convention from analogue or "new"}
+
+## UX Risks
+
+{Where the user may get confused, stuck, or surprised. Anchored on the gaps + mismatches from methodology step 4. Each risk one line + one mitigation line.}
+
+## Visual Hierarchy
+
+{What should be most prominent, secondary, hidden, grouped, or de-emphasized. Cite analogue patterns when reusing; flag when the brief implies a hierarchy that conflicts with the codebase.}
+
+## Copy Requirements
+
+{Button labels, helper text, error messages, confirmation text, tooltips. Brief lines if the brief specifies; codebase-convention examples if not; "needs writing" entries flagged for plan mode otherwise.}
+
+## Accessibility Requirements
+
+{Keyboard navigation, focus states, contrast, labels, ARIA expectations, reduced motion. Anchored on the codebase's existing a11y patterns (search for `aria-`, `role=`, `:focus-visible`, `prefers-reduced-motion` in analogues).}
+
+## Responsiveness
+
+{Desktop / tablet / mobile behavior. Use the codebase's breakpoint convention (search tailwind.config / theme files / media queries in analogues). Flag if the brief implies breakpoints that diverge from the convention.}
+
+## Design System Fit
+
+{Existing components to prefer, patterns to reuse, styling constraints to avoid custom one-offs. For each implied surface from methodology step 2: which existing component or token set is the right base, with file paths. When no design system exists in the repo: state that clearly and instruct plan mode to discover patterns or propose an anchor.}
+
+## Acceptance Criteria
+
+{Experiential checks ON TOP OF the brief's RB-level criteria. Per-state, per-viewport, copy correctness, focus order, keyboard nav, reduced-motion, color-contrast. Each criterion concrete enough to verify in QA — no "feels right" entries.}
+
+## Plan Mode Prompt
+
+The agent should paste this verbatim into plan mode (or the agent itself should adopt it as the first instruction when entering plan mode).
+
+```
+You are about to enter plan mode for a UI/UX implementation task.
+
+First, inspect the existing UI patterns, components, routes, design-system conventions, and nearby implementations. Do not edit files yet.
+
+Specifically address before proposing any plan:
+1. {mismatch from methodology step 4 — concrete one-liner}
+2. {gap from methodology step 4 — concrete one-liner}
+3. {new-work surface from methodology step 4 — concrete one-liner}
+   (repeat 4–6 for the next most load-bearing surfaced items)
+
+Then return a plan that includes:
+- Existing patterns you found (cite file paths)
+- User flow summary
+- Components / screens likely affected
+- UI states to implement (referencing the States section of UX-REVIEW.md)
+- Accessibility considerations (referencing the Accessibility Requirements section)
+- Responsive behavior (referencing the Responsiveness section)
+- Copy or microcopy needed (referencing the Copy Requirements section)
+- Risks or ambiguous UX decisions (referencing the UX Risks section)
+- Test/QA plan (referencing the Acceptance Criteria section)
+- Proposed implementation steps
+
+Do not start coding until the plan is approved.
+```
+```
+
+---
+
+### What this review is NOT
+
+- **Not a re-derivation of the brief.** If the brief already specifies a state, the review says so in one line and moves on. The review's value is on the gaps, mismatches, and codebase-grounding — not on rewriting good content.
+- **Not an excuse to expand scope.** Stay within the brief's Goal and Non-goals. UX coverage gaps that fall OUTSIDE the brief's scope go on the deferrals list, not the acceptance criteria.
+- **Not a design tool.** This produces a planning packet, not visual designs. Where the codebase has no design system, the review surfaces that fact and routes back to the user — it does not propose one unilaterally.
+- **Not a check on existing implementations.** Use `/ritual lineage` for "what decisions shaped this code already." This review is forward-looking only.
+
+---
+
+### Failure modes to watch for
+
+- **Generic checklist filling.** Symptom: every section reads the same regardless of the brief / repo. Mitigation: methodology step 1's classification — if the output doesn't reflect what the brief actually covers vs misses, the analysis upstream wasn't done.
+- **Fabricating analogues.** Symptom: review cites file paths that don't exist. Mitigation: every file path claim must come from an actual Grep / Glob / Read result in methodology step 3.
+- **Plan-mode prompt with no surfaced findings.** Symptom: the numbered list at the top of the plan-mode prompt is a generic 10-step plan. Mitigation: methodology steps 4 and 6 — the first 3–6 items must be the actual mismatches, gaps, and new-work surfaces from step 4. If those lists were empty, the brief is unusually complete; the prompt's first three items should reflect that ("Brief is unusually complete; verify each state listed under §X exists in the codebase before extending").
+- **Scope drift.** Symptom: review proposes UI work the brief deliberately excluded under Non-goals. Mitigation: re-read Non-goals before drafting the review; deferrals list is the right destination for out-of-scope UX gaps.

package/skills/cursor/ritual/.ritual-bundle.json

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.7.13",
-  "builtAt": "2026-05-15T14:17:47.561Z"
+  "cliVersion": "0.7.15",
+  "builtAt": "2026-05-19T15:51:30.453Z"
 }

package/skills/cursor/ritual/DESIGN.md

@@ -20,7 +20,7 @@ The split version keeps:
 
 ## Retired `/ritual recon`
 
-`/ritual recon` is intentionally not part of the vNext command surface. Its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and its repo-reading behavior is normal coding-agent behavior in plain English.
+`/ritual recon` is intentionally not part of the Ritual command surface. Its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and its repo-reading behavior is normal coding-agent behavior in plain English.
 
 ## Context packet principle
 

package/skills/cursor/ritual/SKILL.md

@@ -18,6 +18,36 @@ Before executing any subcommand, read and follow:
 
 Do not reintroduce `/ritual recon`. Use plain-language repo inspection, `/ritual resume`, or `/ritual lineage` depending on intent.
 
+## Contract strength — load-bearing for all subcommands
+
+Every section in this SKILL or its reference files labeled **load-bearing**, **forbidden behavior**, **anti-pattern**, **rendering contract**, or **fire-on-trigger** is **contract-strength**, not guidance.
+
+If this SKILL says *"DO NOT do X"*, your default action is to not do X. You may not override based on your in-the-moment assessment that X would be:
+
+- helpful
+- clearer
+- shorter
+- more convenient
+- *"obviously what the user really wants"*
+- *"a small improvement on top of the SKILL's contract"*
+
+When a local example or your own instinct conflicts with a contract-strength rule, **the contract wins.** Re-read the rule. Trust that the prior version of you also thought the override "feels right" — that's exactly the case the contract exists to prevent.
+
+When two contract-strength rules genuinely conflict (rare): **stop, surface the conflict to the user, and ask which to honor.** Do not improvise a resolution.
+
+This rule is the meta-pattern that closes the failure class we kept hitting before 2026-05-15: the SKILL named the right behavior in each step (Step 7 picker, Step 9 preview-verbatim, Step 9 action menu, picker numbering, etc.), but the agent treated the prose as advisory and freelanced anyway. Anti-patterns are **executable constraints, not taste guidance.** When an anti-pattern says "agent must NOT", read it as a hard error, not a preference.
+
+Examples of contract-strength rules currently in force (non-exhaustive):
+
+- `references/build-flow.md` Step 7 transition lock — must NOT skip the Areas picker, must call `accept_discovery_questions` before `start_agentic_run`.
+- `references/build-flow.md` Step 7.3.1 rendering contract — Areas index has NO question previews, single numbering stream.
+- `references/build-flow.md` Step 7.4.5 fire-on-trigger — scope-classification gate is the contract, not a suggestion.
+- `references/build-flow.md` Step 9 action menu lock — blessed set is exactly `accept recommended` / `drop R{N}` / `drill R{N}` / `comment R{N}` / `pause` (+ `request admin review` for collaborators). NO freelance `dedupe` / `open the admin` / invented compound actions.
+- `references/build-flow.md` Step 9 rendering — use the server preview verbatim; no free-form summarization on top.
+- `references/resume-flow.md` § R2 picker rendering — ONE picker number per exploration; continuation prose indented; flat numbering across state buckets.
+
+When you encounter a rule labeled with any of the marker words above, treat it the same way you'd treat a unit-test assertion: violating it is a regression, not a stylistic choice.
+
 ## Routing
 
 Parse the first token of the argument:
@@ -28,9 +58,10 @@ Parse the first token of the argument:
 | `resume` | `references/resume-flow.md` | "Pick up where I left off." Lists in-flight explorations with state badges and jumps to the right step. |
 | `lineage` | `references/lineage-flow.md` | Paste a file path (or set of paths); see every prior exploration / decision / deferral that touched those files. |
 | `context-pulse` | `references/context-pulse-flow.md` | Score readiness / context debt for a feature ask or exploration. Can seed a `CONTEXT-<feature>.md` file with relevant codebase + KG context that `/ritual build` picks up automatically. Also surfaces inline during build so the user watches debt drop. |
+| `status` | `references/status-flow.md` | Read-only mirror of the `ritual status` terminal CLI command (CLI 0.7.14+) for users who want a quick run-progress check inside the agent session instead of in a separate terminal. Calls `mcp__ritual__get_agentic_run` + renders the same run-first layout the CLI uses. |
 | (anything else, OR no subcommand) | default to `build` and treat the entire argument as the problem statement | |
 
-The vNext CLI surface is intentionally **just these four**. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `status`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "status of exp-Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired in this PR because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
+The Ritual CLI surface is intentionally narrow: `build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
 
 
 ## Subcommand reference files
@@ -67,5 +98,31 @@ When the user says things like *"what's the status of exp-X?"*, *"show me the re
 | Kick off / re-run the agentic pipeline | `mcp__ritual__start_agentic_run(exploration_id, …)` |
 | Did anyone implement something on these files? | `mcp__ritual__query_knowledge_graph(sources=[…])` — same plumbing as `/ritual lineage` |
 
-This is intentional. Legacy exposed each of these as its own slash-command (`/ritual status`, `/ritual recs`, `/ritual run`) and the surface area ballooned without adding agent value. In vNext we keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`) and let the agent fluently call MCP tools for everything else. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+This is intentional. Legacy exposed each of these as its own slash-command (`/ritual recs`, `/ritual run`, etc.) and the surface area ballooned without adding agent value. We keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror) and let the agent fluently call MCP tools for everything else. Note: `/ritual status` is the one deliberate exception — it exists as a thin SKILL mirror of the terminal CLI command so users who want an in-chat status check don't have to context-switch to a separate terminal. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+
+---
+
+## Before this skill is installed — bootstrap context
+
+This SKILL only governs behavior **after** `ritual init` has run and the
+`/ritual` skill has been copied into the agent's skills directory. Before
+that, the agent has no Ritual-specific instructions in scope.
+
+If you are reading this file by browsing the repo, or as part of a
+post-mortem on why a user's "set up Ritual MCP" request went sideways:
+the **pre-install** instruction surface lives in three places, in priority
+order:
+
+1. **`learn.ritual.work/llms.txt`** — canonical machine-readable bootstrap script. Served as plain text. WebFetch-safe.
+2. **`ritual.work/llms.txt`** — identical bytes to (1). Served from the marketing site so an agent handed any `ritual.work/...` URL can find it without knowing about `learn.ritual.work`.
+3. **`apps/cli/README.md`** in this repo (ships to npmjs.com via `@ritualai/cli`) — has the same "AI coding agents: start here" block at the top.
+
+All three sources must say the same thing. The canonical content is the
+7-step `npm install -g @ritualai/cli` → `ritual init` → `ritual doctor`
+→ restart-agent → verify-MCP → `/ritual build` flow, with explicit
+"do not ask the user about their project until init succeeds" rules.
+
+When updating one, update all three. The cross-repo sync is intentional
+duplication — agents need the bootstrap visible at whichever URL they
+happen to be handed.
 

package/skills/cursor/ritual/manifest.json

@@ -1,13 +1,13 @@
 [
   {
     "path": "DESIGN.md",
-    "lines": 36,
-    "bytes": 2226
+    "lines": 35,
+    "bytes": 2227
   },
   {
     "path": "SKILL.md",
-    "lines": 72,
-    "bytes": 5915
+    "lines": 102,
+    "bytes": 9156
   },
   {
     "path": "agents/openai.yaml",
@@ -21,8 +21,13 @@
   },
   {
     "path": "references/build-flow.md",
-    "lines": 1519,
-    "bytes": 88142
+    "lines": 2652,
+    "bytes": 165455
+  },
+  {
+    "path": "references/brief-verification-checklist.md",
+    "lines": 169,
+    "bytes": 10820
   },
   {
     "path": "references/cli-output-contract.md",
@@ -46,12 +51,22 @@
   },
   {
     "path": "references/resume-flow.md",
-    "lines": 157,
-    "bytes": 9950
+    "lines": 225,
+    "bytes": 14048
   },
   {
     "path": "references/scoring-fallback.md",
     "lines": 126,
     "bytes": 6494
+  },
+  {
+    "path": "references/status-flow.md",
+    "lines": 94,
+    "bytes": 6096
+  },
+  {
+    "path": "references/ui-ux-checklist.md",
+    "lines": 198,
+    "bytes": 12167
   }
 ]