@ritualai/cli 0.7.13 → 0.7.15

package/README.md

@@ -6,6 +6,50 @@ Codex, Kiro, Gemini CLI, Windsurf, etc.) to Ritual Cloud via the
 
 Docs: [ritual.work/ritual-mcp/docs/](https://ritual.work/ritual-mcp/docs/)
 
+## AI coding agents: start here
+
+If you are an AI coding agent and a user asked you to "set up Ritual MCP,"
+"install Ritual," or anything similar, follow this script **verbatim**.
+Do not ask the user about their project, their stack, or where to register
+the MCP server — `ritual init` handles all of that.
+
+```text
+1. Do not scaffold the user's app yet.
+
+2. Install or upgrade the CLI:
+     npm install -g @ritualai/cli
+
+3. From the project root, run:
+     ritual init
+
+4. If `init` opens a browser for sign-in, tell the user to complete
+   it. If they are a brand-new user, they will get a verification email
+   — they must click the link. Keep the terminal open while they do.
+   If the loopback times out, re-run `ritual init` once.
+
+5. After `init` reports success, run:
+     ritual doctor
+
+6. Tell the user to fully close and reopen their coding agent so the
+   newly-registered MCP server comes online. Reload / `/clear` is not
+   enough — the agent caches MCP config at startup.
+
+7. Once the user is back in the agent, verify the `ritual` MCP server
+   is connected (in Claude Code: `/mcp`). Only then offer to start
+   product work — typically by running `/ritual build <feature>`.
+```
+
+**Hard rules until `ritual init` succeeds:**
+- Do not ask the user what kind of project they're building.
+- Do not ask which stack to scaffold against.
+- Do not ask whether to register MCP project-local vs user-global — `ritual init` picks the right scope per agent automatically.
+- Do not edit `~/.claude.json`, `.mcp.json`, `.cursor/mcp.json`, or any other agent config file by hand.
+- Do not paste docs URLs into a fetch tool and ask the user to read the rendered marketing site — the bootstrap script above is the authoritative source.
+
+**Only escape hatch:** if the user explicitly declines Ritual setup, or if
+`ritual init` fails twice in a row with the same error, ask the user how
+they'd like to proceed. Don't surface the escape hatch unsolicited.
+
 ## Install
 
 ```bash

package/dist/commands/status.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusCommand = statusCommand;
+const config_1 = require("../lib/config");
+const api_client_1 = require("../lib/api-client");
+const project_config_1 = require("../lib/project-config");
+const status_formatter_1 = require("../lib/status-formatter");
+async function statusCommand(explorationIdArg, options) {
+    const token = await (0, config_1.getValidAccessToken)();
+    if (token.kind === 'not-signed-in') {
+        console.error('  ✗ Not signed in. Run `ritual login` first.');
+        process.exit(1);
+    }
+    if (token.kind === 're-auth-required') {
+        console.error(`  ✗ Session expired (${token.reason}). Run \`ritual login\` to re-auth.`);
+        process.exit(1);
+    }
+    const api = new api_client_1.ApiClient({
+        issuer: token.creds.issuer,
+        accessToken: token.accessToken,
+    });
+    if (options.watch) {
+        await runWatchLoop(api, explorationIdArg);
+    }
+    else {
+        await runOnce(api, explorationIdArg);
+    }
+}
+async function runOnce(api, explorationIdArg) {
+    const inputs = await fetchStatus(api, explorationIdArg);
+    if (!inputs) {
+        // Already printed a friendly error in fetchStatus.
+        process.exit(1);
+    }
+    console.log((0, status_formatter_1.formatStatus)(inputs));
+}
+/**
+ * --watch loop. Renders the status snapshot every 5s, in-place using
+ * ANSI cursor controls. Exits on:
+ *   - terminal run states (`completed` / `failed` / `cancelled`)
+ *   - the user pressing Ctrl+C
+ *   - 3 consecutive fetch errors (no point thrashing if the API is down)
+ *
+ * Cadence locked at 5s — short enough to feel live, polite enough not
+ * to hammer the API on a long-running poll.
+ */
+async function runWatchLoop(api, explorationIdArg) {
+    let lastRenderedLines = 0;
+    let consecutiveErrors = 0;
+    const POLL_MS = 5000;
+    const stop = (code) => {
+        process.stdout.write('\n');
+        process.exit(code);
+    };
+    process.on('SIGINT', () => stop(130));
+    // First render: print fresh, no clear.
+    while (true) {
+        let inputs = null;
+        try {
+            inputs = await fetchStatus(api, explorationIdArg);
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            consecutiveErrors += 1;
+            if (consecutiveErrors >= 3) {
+                console.error(`\n  ✗ Repeated errors fetching status (${err.message}). Exiting watch.`);
+                process.exit(1);
+            }
+        }
+        if (inputs) {
+            const rendered = (0, status_formatter_1.formatStatus)(inputs);
+            if (lastRenderedLines > 0) {
+                // Move cursor up by the previous render's line count + clear from there.
+                process.stdout.write(`\x1b[${lastRenderedLines}A\x1b[0J`);
+            }
+            process.stdout.write(rendered + '\n');
+            lastRenderedLines = rendered.split('\n').length + 1;
+            // Exit if run reached a terminal state.
+            const status = inputs.run?.status?.toLowerCase();
+            if (status === 'completed' || status === 'completed_with_errors') {
+                process.stdout.write('\n  ✓ Run finished. Exiting watch.\n');
+                process.exit(0);
+            }
+            if (status === 'failed') {
+                process.stdout.write('\n  ✗ Run failed. Exiting watch.\n');
+                process.exit(1);
+            }
+            if (status === 'cancelled') {
+                process.stdout.write('\n  · Run cancelled. Exiting watch.\n');
+                process.exit(0);
+            }
+        }
+        await sleep(POLL_MS);
+    }
+}
+async function fetchStatus(api, explorationIdArg) {
+    let explorationId;
+    if (explorationIdArg) {
+        explorationId = explorationIdArg;
+    }
+    else {
+        // Auto-resolve from .ritual/config.json.
+        const project = (0, project_config_1.loadProjectConfig)(process.cwd());
+        if (!project) {
+            console.error('  ✗ No `.ritual/config.json` in this directory. Either:\n' +
+                '      ritual init                              — bind a workspace to this repo, OR\n' +
+                '      ritual status <exploration-id>           — fetch a specific exploration');
+            return null;
+        }
+        const picked = await pickCurrentExploration(api, project.workspaceId);
+        if (!picked) {
+            console.error(`  ✗ No active or recent explorations found in workspace ${project.workspaceName}.`);
+            return null;
+        }
+        explorationId = picked;
+    }
+    // Fetch exploration shell + agentic-status + run in parallel.
+    const [exp, agenticStatus, runs] = await Promise.all([
+        api
+            .get(`/explorations/${encodeURIComponent(explorationId)}`)
+            .catch((err) => {
+            if (err.status === 404) {
+                console.error(`  ✗ Exploration ${explorationId} not found.`);
+                return null;
+            }
+            throw err;
+        }),
+        api
+            .get(`/explorations/${encodeURIComponent(explorationId)}/agentic-status`)
+            .catch(() => null),
+        api
+            .get(`/agentic-runs?exploration_id=${encodeURIComponent(explorationId)}&status=running`)
+            .catch(() => []),
+    ]);
+    if (!exp)
+        return null;
+    const run = runs && runs.length > 0
+        ? { id: runs[0].agentic_run_id, status: runs[0].status }
+        : null;
+    return {
+        exploration: {
+            id: exp.id,
+            name: exp.name,
+            step: exp.step,
+            updatedAt: exp.updatedAt,
+        },
+        progress: agenticStatus?.progress ?? null,
+        run,
+    };
+}
+/**
+ * Pick the "current" exploration for `ritual status` with no arg.
+ *
+ * Ranking:
+ *   1. Any exploration with a RUNNING agentic run → return its id.
+ *   2. Else most-recently-updated where step != COMPLETED.
+ *   3. Else most-recently-updated full stop.
+ *
+ * Multiple RUNNING runs is uncommon. For v1 we pick whichever the API
+ * returns first (most-recently-started in practice); a multi-run picker
+ * can land in MVP-2 with `ritual status --runs`.
+ */
+async function pickCurrentExploration(api, workspaceId) {
+    const exps = await api.get(`/explorations?workspaceId=${encodeURIComponent(workspaceId)}&withImplementationStatus=true`);
+    if (!exps || exps.length === 0)
+        return null;
+    // Probe for a RUNNING run across explorations. Sorted by updatedAt
+    // desc first so the most recently-touched exploration gets the
+    // first run-probe — usually the right answer in one call.
+    const sorted = [...exps].sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    for (const e of sorted.slice(0, 5)) {
+        try {
+            const runs = await api.get(`/agentic-runs?exploration_id=${encodeURIComponent(e.id)}&status=running`);
+            if (runs && runs.length > 0)
+                return e.id;
+        }
+        catch {
+            // fall through — never block on a probe failure
+        }
+    }
+    // No RUNNING runs — pick most-recently-updated non-completed.
+    const nonComplete = sorted.find((e) => e.step !== 'COMPLETED');
+    if (nonComplete)
+        return nonComplete.id;
+    return sorted[0]?.id ?? null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,6 +8,14 @@ const whoami_1 = require("./commands/whoami");
 const refresh_1 = require("./commands/refresh");
 const init_1 = require("./commands/init");
 const doctor_1 = require("./commands/doctor");
+// 2026-05-15 (PR D) — `ritual status [--watch]` instant snapshot of
+// an in-flight agentic run. Auto-resolves the current exploration
+// from `.ritual/config.json` so the user doesn't have to remember
+// IDs; --watch polls every 5s and redraws in place. Paired with the
+// SKILL Step 8 reframe ("you're unblocked; runs continue server-
+// side") to break the mental model where users feel obligated to
+// stare at the polling loop.
+const status_1 = require("./commands/status");
 const graph_1 = require("./commands/graph");
 const package_info_1 = require("./lib/package-info");
 // 2026-05-15 (PR C) — pre-flight one-line stderr warning when the
@@ -61,6 +69,13 @@ program
     .command('refresh')
     .description('Force-refresh the cached access token using the stored refresh token')
     .action(refresh_1.refreshCommand);
+program
+    .command('status')
+    .description('Show the current agentic run status. With --watch, polls every 5s and redraws in place. ' +
+    'With no exploration ID, auto-resolves the workspace\'s currently-active run.')
+    .argument('[exploration-id]', 'Specific exploration to inspect (defaults to the current run)')
+    .option('--watch', 'Poll every 5s and redraw in place; exits on terminal state or Ctrl+C')
+    .action((explorationId, opts) => (0, status_1.statusCommand)(explorationId, { watch: opts.watch }));
 program
     .command('doctor')
     .description('Sanity check the CLI environment: credentials, endpoints, detected agents')

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/status-formatter.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Pure formatter for `ritual status` output.
+ *
+ * Kept as a side-effect-free function so it can be unit-tested in
+ * isolation without HTTP / filesystem / clock mocks. The command
+ * orchestration in `commands/status.ts` does the fetching; this just
+ * turns shapes into strings.
+ *
+ * Design choices (locked in `backlog_ritual_status_and_unblocked_framing.md`):
+ *
+ *   - Run line first. "RUNNING for 17m 41s" is the headline; exploration
+ *     name is a footer parenthetical, not the lead.
+ *   - Pace + ETA computed only when `completedQuestions >= 3` so the
+ *     average doesn't get whiplashed by the first question's latency.
+ *   - Activity / last-write age is the real "is it actually moving?"
+ *     signal — climbing past ~3 min without `completedQuestions`
+ *     advancing is actionable info, not a snapshot lie.
+ *
+ * The shape this formatter consumes is the merged view (live progress
+ * from `Exploration.agenticProgress` + run id from
+ * `GET /agentic-runs?explorationId=...&status=RUNNING&limit=1`), never
+ * the raw `AgenticJob` row whose `totalQuestions` / `progress.steps`
+ * fields can sit unwritten for entire runs (bug filed
+ * 2026-05-15 — see `backlog_ritual_status_and_unblocked_framing.md`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatStatus = formatStatus;
+exports.humanizeDuration = humanizeDuration;
+function formatStatus(input) {
+    const now = (input.now ?? new Date()).getTime();
+    const lines = [];
+    if (input.run && input.progress) {
+        lines.push(...formatRunSection(input.run, input.progress, input.exploration, now));
+    }
+    else if (input.progress) {
+        lines.push(...formatNoRunButProgress(input.progress, input.exploration, now));
+    }
+    else {
+        lines.push(...formatNoProgress(input.exploration));
+    }
+    lines.push('');
+    lines.push(`(Exploration: ${input.exploration.name})`);
+    lines.push(`  ${input.exploration.id}  ·  step: ${input.exploration.step}`);
+    return lines.join('\n');
+}
+function formatRunSection(run, progress, exploration, now) {
+    const runShort = truncateId(run.id);
+    const ageSec = progress.startedAt
+        ? Math.round((now - new Date(progress.startedAt).getTime()) / 1000)
+        : null;
+    const runLine = ageSec != null
+        ? `Run        ${runShort}  ·  ${run.status.toUpperCase()} for ${humanizeDuration(ageSec)}`
+        : `Run        ${runShort}  ·  ${run.status.toUpperCase()}`;
+    const phaseLine = formatPhaseLine(progress);
+    const questionsLine = formatQuestionsLine(progress);
+    const activityLine = formatActivityLine(exploration.updatedAt, now);
+    const paceLine = formatPaceLine(progress, now);
+    const nextLine = formatNextLine(progress);
+    const out = [runLine, phaseLine];
+    if (questionsLine)
+        out.push(questionsLine);
+    out.push(activityLine);
+    if (paceLine)
+        out.push(paceLine);
+    if (nextLine)
+        out.push(nextLine);
+    return out;
+}
+function formatNoRunButProgress(progress, exploration, now) {
+    // No active run, but agenticProgress on the exploration shows past
+    // activity. Either the run completed or it never started. Either
+    // way, the last-snapshot view is what's useful.
+    const out = [`Run        (no active run)`];
+    out.push(formatPhaseLine(progress));
+    const questionsLine = formatQuestionsLine(progress);
+    if (questionsLine)
+        out.push(questionsLine);
+    out.push(formatActivityLine(exploration.updatedAt, now));
+    return out;
+}
+function formatNoProgress(exploration) {
+    return [
+        `Run        (no run started yet)`,
+        `Phase      —`,
+        `Step       ${exploration.step}`,
+    ];
+}
+function formatPhaseLine(progress) {
+    const phase = progress.phase ?? '—';
+    const pct = typeof progress.percent === 'number' ? `  (${progress.percent}%)` : '';
+    return `Phase      ${phase}${pct}`;
+}
+function formatQuestionsLine(progress) {
+    const total = progress.totalQuestions;
+    const done = progress.completedQuestions;
+    const failed = progress.failedQuestions ?? 0;
+    if (typeof total !== 'number' || typeof done !== 'number')
+        return null;
+    if (total === 0)
+        return null;
+    const failedSegment = failed > 0 ? `  ·  ${failed} failed` : `  ·  0 failed`;
+    return `Questions  ${done} / ${total}${failedSegment}`;
+}
+function formatActivityLine(updatedAt, now) {
+    const ageSec = Math.max(0, Math.round((now - new Date(updatedAt).getTime()) / 1000));
+    return `Activity   last DB write ${humanizeDuration(ageSec)} ago`;
+}
+function formatPaceLine(progress, now) {
+    const done = progress.completedQuestions ?? 0;
+    const total = progress.totalQuestions ?? 0;
+    if (done < 3)
+        return `Pace       warming up — check back in 30s`;
+    if (!progress.startedAt || total <= done)
+        return null;
+    const elapsedSec = (now - new Date(progress.startedAt).getTime()) / 1000;
+    if (elapsedSec <= 0)
+        return null;
+    const secPerQ = elapsedSec / done;
+    const remainingSec = Math.round(secPerQ * (total - done));
+    return `Pace       ~${Math.round(secPerQ)}s/question  ·  ETA ~${humanizeDuration(remainingSec)} remaining`;
+}
+function formatNextLine(progress) {
+    const phase = (progress.phase ?? '').toLowerCase();
+    const nextByPhase = {
+        discovery: 'Accepting questions',
+        accepting: 'Answering',
+        answering: 'Recommendations (auto-advances when questions are done)',
+        submitting: 'Recommendations',
+        recommendations: 'Build brief (after admin review)',
+        complete: '—',
+        failed: '—',
+    };
+    const next = nextByPhase[phase];
+    return next ? `Next       ${next}` : null;
+}
+function humanizeDuration(seconds) {
+    if (seconds < 0)
+        seconds = 0;
+    if (seconds < 60)
+        return `${seconds}s`;
+    const m = Math.floor(seconds / 60);
+    const s = seconds % 60;
+    if (m < 60) {
+        return s === 0 ? `${m}m` : `${m}m ${s}s`;
+    }
+    const h = Math.floor(m / 60);
+    const remM = m % 60;
+    return remM === 0 ? `${h}h` : `${h}h ${remM}m`;
+}
+function truncateId(id) {
+    // "ba4d2b42-…" form — first 8 chars + ellipsis. Matches the agent-
+    // facing copy in the SKILL so users can pattern-match against IDs
+    // they've seen elsewhere. UUIDs slice cleanly at 8 (no trailing
+    // hyphen); for non-UUID inputs we strip a trailing dash so we
+    // don't render "r1-aaaa--…" with double hyphens.
+    if (id.length <= 8)
+        return id;
+    const head = id.slice(0, 8).replace(/-+$/, '');
+    return `${head}-…`;
+}
+//# sourceMappingURL=status-formatter.js.map

package/dist/lib/status-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-formatter.js","sourceRoot":"","sources":["../../src/lib/status-formatter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ritualai/cli",
-	"version": "0.7.13",
+	"version": "0.7.15",
 	"description": "Ritual CLI — scaffold AI coding agent skills + register MCP servers. Connects Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code/Copilot, and Codex to Ritual Cloud.",
 	"private": false,
 	"license": "Apache-2.0",

package/skills/claude-code/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/claude-code/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/claude-code/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/claude-code/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
   }
 ]