@ritualai/cli 0.7.10 → 0.7.11

package/dist/lib/npm-registry.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLatestNpmVersion = getLatestNpmVersion;
+exports.isNewerVersion = isNewerVersion;
+const node_https_1 = require("node:https");
+/**
+ * Fetch the latest published version of an npm package from the public
+ * registry. Used by `ritual doctor` to surface "you're on 0.7.10 but
+ * 0.7.11 is available."
+ *
+ * Pure HTTPS — no dependency on a registry client library. We hit the
+ * package metadata endpoint and read `dist-tags.latest`, which is what
+ * `npm view <pkg> version` returns.
+ *
+ * Hard timeout because `ritual doctor` runs synchronously in the user's
+ * terminal and a hung network call would hang the diagnostic. Caller
+ * should treat null as "couldn't determine" (e.g. offline, registry
+ * down, corporate proxy) rather than "package doesn't exist."
+ *
+ * Why we don't use `child_process.execSync('npm view ...')`:
+ *   - Shells out to `npm`, which loads ~600ms of Node startup just for
+ *     the registry round-trip.
+ *   - Adds an implicit dependency on `npm` being on PATH (we don't
+ *     enforce that — a user could be on pnpm or yarn).
+ *   - Surfaces npm's stderr noise (deprecation warnings, etc.) to the
+ *     diagnostic output.
+ */
+async function getLatestNpmVersion(packageName, timeoutMs = 2000) {
+    return new Promise((resolve) => {
+        // Encode scoped package names (`@scope/name`) for the URL path.
+        // `encodeURIComponent` turns `@` into `%40` and `/` into `%2F`,
+        // which is the registry's expected form for scoped packages.
+        const encoded = encodeURIComponent(packageName);
+        const url = `https://registry.npmjs.org/${encoded}`;
+        const req = (0, node_https_1.request)(url, {
+            method: 'GET',
+            headers: {
+                // Slim metadata response — full doc is megabytes for
+                // packages with long publish histories. `abbreviated`
+                // returns only the fields we need (~5KB).
+                Accept: 'application/vnd.npm.install-v1+json',
+                'User-Agent': '@ritualai/cli (doctor)',
+            },
+        }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume(); // drain and discard
+                resolve(null);
+                return;
+            }
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                try {
+                    const body = Buffer.concat(chunks).toString('utf-8');
+                    const parsed = JSON.parse(body);
+                    const latest = parsed['dist-tags']?.latest;
+                    resolve(typeof latest === 'string' ? latest : null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+            res.on('error', () => resolve(null));
+        });
+        req.setTimeout(timeoutMs, () => {
+            req.destroy();
+            resolve(null);
+        });
+        req.on('error', () => resolve(null));
+        req.end();
+    });
+}
+/**
+ * Loose semver compare: return true iff `latest` is strictly newer than
+ * `installed`. Tolerates `0.0.0-unknown` (used when we can't read our
+ * own version) by treating it as "always outdated" — which surfaces a
+ * loud error in doctor rather than silently passing.
+ *
+ * We deliberately don't pull in `semver` as a dep here — the cost
+ * (parse error handling, prerelease semantics, range syntax) isn't
+ * justified for a one-call compare. Splitting on '.' and comparing as
+ * numeric tuples is sufficient for our 0.X.Y release line.
+ */
+function isNewerVersion(installed, latest) {
+    if (installed === latest)
+        return false;
+    if (installed === '0.0.0-unknown')
+        return true;
+    const parse = (v) => v
+        .split('-')[0] // strip prerelease (e.g. -beta.1)
+        .split('.')
+        .map((s) => Number.parseInt(s, 10))
+        .map((n) => (Number.isFinite(n) ? n : 0));
+    const a = parse(installed);
+    const b = parse(latest);
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const ai = a[i] ?? 0;
+        const bi = b[i] ?? 0;
+        if (bi > ai)
+            return true;
+        if (bi < ai)
+            return false;
+    }
+    return false;
+}
+//# sourceMappingURL=npm-registry.js.map

package/dist/lib/npm-registry.js.map

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

package/dist/lib/skill-bundles.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findLocalSkillBundles = findLocalSkillBundles;
+exports.findStaleBundles = findStaleBundles;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const providers_1 = require("./agents/providers");
+const skill_manifest_1 = require("./skill-manifest");
+/**
+ * Walk every known provider's `projectSkillDir` under `projectDir` and
+ * collect each child directory as a candidate skill bundle. Reads each
+ * manifest and compares to `cliVersion`.
+ *
+ * Hidden directories (those starting with `.`) are skipped — they're
+ * either dotfiles or our own manifest companions, never skill dirs.
+ *
+ * `cliVersion` is passed in (rather than read from package-info here)
+ * so tests can inject a fixed value.
+ */
+function findLocalSkillBundles(projectDir, cliVersion) {
+    const found = [];
+    for (const provider of providers_1.PROVIDERS) {
+        const skillRoot = (0, node_path_1.join)(projectDir, provider.projectSkillDir);
+        if (!(0, node_fs_1.existsSync)(skillRoot))
+            continue;
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(skillRoot, { withFileTypes: true })
+                .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+                .map((d) => d.name);
+        }
+        catch {
+            continue;
+        }
+        for (const skillName of entries) {
+            const path = (0, node_path_1.join)(skillRoot, skillName);
+            // Defensive: a non-directory slipping through (race, symlink
+            // loop) just gets skipped.
+            try {
+                if (!(0, node_fs_1.statSync)(path).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const manifest = (0, skill_manifest_1.readSkillManifest)(path);
+            const drift = (0, skill_manifest_1.compareToCliVersion)(manifest, cliVersion);
+            found.push({ provider, skillName, path, drift });
+        }
+    }
+    return found;
+}
+/**
+ * Subset of bundles whose drift status indicates a refresh would help.
+ * Both `drift` (manifest present, version mismatch) AND `unknown`
+ * (manifest missing — pre-0.7.11 bundle) are considered actionable:
+ * running `ritual init --skills-only` is the same fix for either case.
+ */
+function findStaleBundles(bundles) {
+    return bundles.filter((b) => b.drift.kind === 'drift' || b.drift.kind === 'unknown');
+}
+//# sourceMappingURL=skill-bundles.js.map

package/dist/lib/skill-bundles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-bundles.js","sourceRoot":"","sources":["../../src/lib/skill-bundles.ts"],"names":[],"mappings":";;AAqCA,sDAgCC;AAQD,4CAEC;AA/ED,qCAA4D;AAC5D,yCAAiC;AACjC,kDAAmE;AACnE,qDAA4F;AAuB5F;;;;;;;;;;GAUG;AACH,SAAgB,qBAAqB,CAAC,UAAkB,EAAE,UAAkB;IAC3E,MAAM,KAAK,GAAuB,EAAE,CAAC;IAErC,KAAK,MAAM,QAAQ,IAAI,qBAAS,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,IAAA,gBAAI,EAAC,UAAU,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAA,oBAAU,EAAC,SAAS,CAAC;YAAE,SAAS;QAErC,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACJ,OAAO,GAAG,IAAA,qBAAW,EAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;iBACvD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;iBACzD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACR,SAAS;QACV,CAAC;QAED,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACxC,6DAA6D;YAC7D,2BAA2B;YAC3B,IAAI,CAAC;gBACJ,IAAI,CAAC,IAAA,kBAAQ,EAAC,IAAI,CAAC,CAAC,WAAW,EAAE;oBAAE,SAAS;YAC7C,CAAC;YAAC,MAAM,CAAC;gBACR,SAAS;YACV,CAAC;YACD,MAAM,QAAQ,GAAG,IAAA,kCAAiB,EAAC,IAAI,CAAC,CAAC;YACzC,MAAM,KAAK,GAAG,IAAA,oCAAmB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACxD,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,OAA2B;IAC3D,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;AACtF,CAAC"}

package/dist/lib/skill-manifest.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANIFEST_FILENAME = void 0;
+exports.writeSkillManifest = writeSkillManifest;
+exports.readSkillManifest = readSkillManifest;
+exports.compareToCliVersion = compareToCliVersion;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.MANIFEST_FILENAME = '.ritual-bundle.json';
+/**
+ * Write a manifest into `dir`. Used by the build-skills script.
+ *
+ * Always overwrites. `dir` must exist — caller is responsible for
+ * mkdir.
+ */
+function writeSkillManifest(dir, manifest) {
+    const path = (0, node_path_1.join)(dir, exports.MANIFEST_FILENAME);
+    (0, node_fs_1.writeFileSync)(path, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Read a manifest from `dir`. Returns `null` if absent or unparseable.
+ *
+ * Never throws — drift checks are best-effort and an unreadable
+ * manifest just means "we can't tell," not "crash the doctor."
+ */
+function readSkillManifest(dir) {
+    const path = (0, node_path_1.join)(dir, exports.MANIFEST_FILENAME);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const raw = (0, node_fs_1.readFileSync)(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.cliVersion !== 'string' || parsed.cliVersion.length === 0) {
+            return null;
+        }
+        if (typeof parsed.builtAt !== 'string' || parsed.builtAt.length === 0) {
+            return null;
+        }
+        return { cliVersion: parsed.cliVersion, builtAt: parsed.builtAt };
+    }
+    catch {
+        return null;
+    }
+}
+function compareToCliVersion(manifest, cliVersion) {
+    if (!manifest)
+        return { kind: 'unknown' };
+    if (manifest.cliVersion === cliVersion) {
+        return { kind: 'in-sync', bundleVersion: manifest.cliVersion };
+    }
+    return { kind: 'drift', bundleVersion: manifest.cliVersion, cliVersion };
+}
+//# sourceMappingURL=skill-manifest.js.map

package/dist/lib/skill-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-manifest.js","sourceRoot":"","sources":["../../src/lib/skill-manifest.ts"],"names":[],"mappings":";;;AA0CA,gDAGC;AAQD,8CAgBC;AAkBD,kDASC;AAhGD,qCAAkE;AAClE,yCAAiC;AAiCpB,QAAA,iBAAiB,GAAG,qBAAqB,CAAC;AAEvD;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,GAAW,EAAE,QAA6B;IAC5E,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,GAAG,EAAE,yBAAiB,CAAC,CAAC;IAC1C,IAAA,uBAAa,EAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,GAAW;IAC5C,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,GAAG,EAAE,yBAAiB,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAA,oBAAU,EAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,IAAA,sBAAY,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiC,CAAC;QAC/D,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7E,OAAO,IAAI,CAAC;QACb,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvE,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAkBD,SAAgB,mBAAmB,CAClC,QAAoC,EACpC,UAAkB;IAElB,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC1C,IAAI,QAAQ,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC;AAC1E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ritualai/cli",
-  "version": "0.7.10",
+  "version": "0.7.11",
   "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

@@ -0,0 +1,4 @@
+{
+  "cliVersion": "0.7.11",
+  "builtAt": "2026-05-14T12:14:29.050Z"
+}

package/skills/claude-code/ritual/references/build-flow.md

@@ -397,7 +397,7 @@ Steps:
      > **{candidate.name}** *(LLM confidence: {Math.round(candidate.llmConfidence * 100)}%)*
      > - *"{candidate.problemStatement first 120 chars, no ellipsis padding}..."*
      > - Why I think it overlaps: {candidate.llmRationale}
-     > - URL: `https://dev.ritualapp.cloud/e/{candidate.explorationId}`
+     > - URL: `https://app.ritualapp.cloud/e/{candidate.explorationId}`
      > {endfor}
      >
      > **Choose:**
@@ -983,7 +983,7 @@ Optimize for:
 
 References:
 - {RB/decision/exploration label} — {one-line meaning}
-  Source: {exploration title or id}{ optional ': https://dev.ritualapp.cloud/e/{exploration_id}' if available}
+  Source: {exploration title or id}{ optional ': https://app.ritualapp.cloud/e/{exploration_id}' if available}
 - {reference}
 
 Reply `use` to use this frame and review discovery questions.
@@ -1040,7 +1040,7 @@ Store `exploration_id`. Move the progress header from Scope to Discovery:
 Ritual build
 ✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
+Exploration created. Track progress at https://app.ritualapp.cloud/e/{exploration_id}
 
 Next: generate discovery questions to resolve the implementation trade-offs.
 ```
@@ -1504,10 +1504,67 @@ If you don't already know the user's role on this workspace, prefer the workspac
 
 ##### 9.1 — Landing screen: grouped category summary + compact scope
 
-The recommendations review is the most-read screen in the whole build flow. Two design rules:
+The recommendations review is the most-read screen in the whole build flow.
 
-1. **Group by `metadata.category.name`.** NEVER show a flat numbered 1..N list. The category is the organizing unit; recommendations are stable `R1..RN` IDs assigned in order of appearance ACROSS categories (top-to-bottom, NOT per-category — so a user can say `detail R7` unambiguously without naming the category).
-2. **Compact scope reference at top.** Show a single-line compressed version of the problem statement so the user can read recommendations against what they were optimized for. Support `show scope` to expand to full.
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 9.1 RENDERING CONTRACT — non-negotiable
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Landing view is for SELECTION, not reading. Full prose belongs in 9.3.
+
+✓ DO:
+- Number categories `1.`, `2.`, `3.` … `K.` in page order
+- Assign recommendations stable `R1`, `R2`, … `RN` IDs GLOBALLY across
+  all categories (NOT restart per-category — so `detail R7` is
+  unambiguous without naming the category)
+- Show recommendation TITLES ONLY at the landing
+- Indent recs 3 spaces under their category
+- One blank line between categories
+- Include compact scope line above the list
+- End with the action block (`accept recommended` etc.)
+
+✗ DO NOT:
+- Do NOT render recs as a flat `1..N` list with no category structure
+- Do NOT use raw numeric rec IDs like `1.`, `2.`, `3.` — use `R1`, `R2`, `R3`
+- Do NOT show recommendation `content` / summary text at the landing
+- Do NOT show acceptance criteria, rationale, tactics, or references at
+  the landing — those are 9.3 detail-card content
+- Do NOT omit category numbering (the prefix is what separates this
+  from a wall-of-text grouped list)
+- Do NOT invent a "raw / deduped" framing line — the API does not return
+  pre-dedup counts. Use `{N} recommendations across {K} categories.`
+
+OBSERVED FAILURE — never render this:
+
+  Recommendations (13)
+
+  1. Backfill legacy data to fail-closed PRIVATE visibility
+     Add a constrained `visibility` field with DB default PRIVATE...
+
+  2. Codify actor-state rights around owner-only mutation
+     Define a single permission matrix across PRIVATE/SHARED/PUBLIC...
+
+  3. Centralize object permissions across storefront and dashboard
+     Reusable `can_view_wishlist` / `can_edit_wishlist` methods...
+
+Why wrong:
+  - Looks grouped only implicitly; categories not visible as headers
+  - Uses `1..N` numeric IDs (should be `R1..RN`)
+  - Dumps `content` summaries — defeats the purpose of a landing view
+  - `detail R7` no longer maps to a stable ID
+
+PREFLIGHT — before printing 9.1 output, self-check:
+  □ Did I group by `metadata.category.name`?
+  □ Did I prefix each category with `1.`, `2.`, … `K.`?
+  □ Did I assign global `R1..RN` IDs across categories?
+  □ Did I show titles only (no summaries / no rationale)?
+  □ Is there a compact scope line above the list?
+  □ Does my action block use `R{N}` references that match the IDs above?
+
+If any answer is no, FIX BEFORE PRINTING.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
 Full rail at the landing (Recommendations stage opens):
 
@@ -1542,7 +1599,11 @@ Pulse: Reasoning Readiness ~88% · Context Debt 12% · +26% (implementation-read
 Recommended: reply `accept recommended` to approve these {N} and generate
 the build brief.
 
-Or reply `detail R7`, `change R3: <edit>`, `drop R8`, `add <topic>`, or `hold`.
+Or reply:
+- `detail R7` to inspect one recommendation
+- `drop R8` to remove one before accepting
+- `change R3: <edit>` to revise one
+- `hold` to stop here
 ```
 
 Notes:
@@ -1551,7 +1612,9 @@ Notes:
 - **One blank line between categories**; titles indent at 3 spaces (so the eye lands on the category name first, then the R-IDs scan down).
 - **Pulse uses full labels** per `references/cli-output-contract.md` § Pulse tier labels.
 - **`accept recommended`** is the visible CTA — NOT `accept all`. "Recommended" frames the action as "the curated set you see on screen"; "all" sounds like a bulk operation over deduped/hidden/raw recs.
-- **`add <topic>`** lets the user request an additional recommendation on the fly (e.g. `add telemetry` → agent calls `regenerate_recommendation` with a new rec hint, or asks the user to clarify what's missing). If the backing API doesn't yet support targeted single-rec addition, prompt the user with: "I can add a rec for `{topic}` by regenerating the full set with that pinned — that takes ~30s. Or hold the current set and add manually via the web UI."
+- **Surface 4 actions at first render — not more.** The four above (`detail R{N}`, `drop R{N}`, `change R{N}: <edit>`, `hold`) cover the decisive cases. Less-frequent actions stay discoverable but off-screen at the landing:
+  - **`add <topic>`** lets the user request an additional recommendation on the fly (e.g. `add telemetry` → agent calls `regenerate_recommendation` with a new rec hint, or asks the user to clarify what's missing). Surface it in `help` or on the 9.3 detail card, NOT in the landing action line — too many actions at once weakens the selection screen. If the backing API doesn't yet support targeted single-rec addition, prompt the user with: "I can add a rec for `{topic}` by regenerating the full set with that pinned — that takes ~30s. Or hold the current set and add manually via the web UI."
+  - **`show scope`** to expand the full problem statement (covered in 9.2).
 
 ##### 9.2 — `show scope` handling
 
@@ -1646,7 +1709,7 @@ Ritual build
 
 Accepted {N} recommendations.
 
-View: https://dev.ritualapp.cloud/e/{exploration_id}
+View: https://app.ritualapp.cloud/e/{exploration_id}
 
 Next: generating the build brief…
 ```
@@ -1783,7 +1846,7 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    ```markdown
    <!--
    Generated by Ritual
-   Exploration: https://dev.ritualapp.cloud/e/{exploration_id}
+   Exploration: https://app.ritualapp.cloud/e/{exploration_id}
    Build brief id: {brief_id}
    Do not remove this header; it preserves implementation lineage.
    -->
@@ -1927,7 +1990,7 @@ feat(<area>): <one-line headline>
 <short body — what changed, why, key trade-off>
 
 Ritual-Exploration: <exploration_id>
-Ritual-Exploration-Url: https://dev.ritualapp.cloud/e/<exploration_id>
+Ritual-Exploration-Url: https://app.ritualapp.cloud/e/<exploration_id>
 Ritual-RBs-Satisfied: RB-1, RB-2, RB-7
 ```
 
@@ -1980,7 +2043,7 @@ If the user says "y" / "push" / "open PR":
 
 ## Exploration
 
-- Exploration: [<exploration name>](https://dev.ritualapp.cloud/e/<exploration_id>)
+- Exploration: [<exploration name>](https://app.ritualapp.cloud/e/<exploration_id>)
 - Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
 - Deferrals intentionally punted: <count, with one-line each>
 

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

@@ -0,0 +1,4 @@
+{
+  "cliVersion": "0.7.11",
+  "builtAt": "2026-05-14T12:14:29.050Z"
+}

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

@@ -397,7 +397,7 @@ Steps:
      > **{candidate.name}** *(LLM confidence: {Math.round(candidate.llmConfidence * 100)}%)*
      > - *"{candidate.problemStatement first 120 chars, no ellipsis padding}..."*
      > - Why I think it overlaps: {candidate.llmRationale}
-     > - URL: `https://dev.ritualapp.cloud/e/{candidate.explorationId}`
+     > - URL: `https://app.ritualapp.cloud/e/{candidate.explorationId}`
      > {endfor}
      >
      > **Choose:**
@@ -983,7 +983,7 @@ Optimize for:
 
 References:
 - {RB/decision/exploration label} — {one-line meaning}
-  Source: {exploration title or id}{ optional ': https://dev.ritualapp.cloud/e/{exploration_id}' if available}
+  Source: {exploration title or id}{ optional ': https://app.ritualapp.cloud/e/{exploration_id}' if available}
 - {reference}
 
 Reply `use` to use this frame and review discovery questions.
@@ -1040,7 +1040,7 @@ Store `exploration_id`. Move the progress header from Scope to Discovery:
 Ritual build
 ✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
+Exploration created. Track progress at https://app.ritualapp.cloud/e/{exploration_id}
 
 Next: generate discovery questions to resolve the implementation trade-offs.
 ```
@@ -1504,10 +1504,67 @@ If you don't already know the user's role on this workspace, prefer the workspac
 
 ##### 9.1 — Landing screen: grouped category summary + compact scope
 
-The recommendations review is the most-read screen in the whole build flow. Two design rules:
+The recommendations review is the most-read screen in the whole build flow.
 
-1. **Group by `metadata.category.name`.** NEVER show a flat numbered 1..N list. The category is the organizing unit; recommendations are stable `R1..RN` IDs assigned in order of appearance ACROSS categories (top-to-bottom, NOT per-category — so a user can say `detail R7` unambiguously without naming the category).
-2. **Compact scope reference at top.** Show a single-line compressed version of the problem statement so the user can read recommendations against what they were optimized for. Support `show scope` to expand to full.
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 9.1 RENDERING CONTRACT — non-negotiable
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Landing view is for SELECTION, not reading. Full prose belongs in 9.3.
+
+✓ DO:
+- Number categories `1.`, `2.`, `3.` … `K.` in page order
+- Assign recommendations stable `R1`, `R2`, … `RN` IDs GLOBALLY across
+  all categories (NOT restart per-category — so `detail R7` is
+  unambiguous without naming the category)
+- Show recommendation TITLES ONLY at the landing
+- Indent recs 3 spaces under their category
+- One blank line between categories
+- Include compact scope line above the list
+- End with the action block (`accept recommended` etc.)
+
+✗ DO NOT:
+- Do NOT render recs as a flat `1..N` list with no category structure
+- Do NOT use raw numeric rec IDs like `1.`, `2.`, `3.` — use `R1`, `R2`, `R3`
+- Do NOT show recommendation `content` / summary text at the landing
+- Do NOT show acceptance criteria, rationale, tactics, or references at
+  the landing — those are 9.3 detail-card content
+- Do NOT omit category numbering (the prefix is what separates this
+  from a wall-of-text grouped list)
+- Do NOT invent a "raw / deduped" framing line — the API does not return
+  pre-dedup counts. Use `{N} recommendations across {K} categories.`
+
+OBSERVED FAILURE — never render this:
+
+  Recommendations (13)
+
+  1. Backfill legacy data to fail-closed PRIVATE visibility
+     Add a constrained `visibility` field with DB default PRIVATE...
+
+  2. Codify actor-state rights around owner-only mutation
+     Define a single permission matrix across PRIVATE/SHARED/PUBLIC...
+
+  3. Centralize object permissions across storefront and dashboard
+     Reusable `can_view_wishlist` / `can_edit_wishlist` methods...
+
+Why wrong:
+  - Looks grouped only implicitly; categories not visible as headers
+  - Uses `1..N` numeric IDs (should be `R1..RN`)
+  - Dumps `content` summaries — defeats the purpose of a landing view
+  - `detail R7` no longer maps to a stable ID
+
+PREFLIGHT — before printing 9.1 output, self-check:
+  □ Did I group by `metadata.category.name`?
+  □ Did I prefix each category with `1.`, `2.`, … `K.`?
+  □ Did I assign global `R1..RN` IDs across categories?
+  □ Did I show titles only (no summaries / no rationale)?
+  □ Is there a compact scope line above the list?
+  □ Does my action block use `R{N}` references that match the IDs above?
+
+If any answer is no, FIX BEFORE PRINTING.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
 Full rail at the landing (Recommendations stage opens):
 
@@ -1542,7 +1599,11 @@ Pulse: Reasoning Readiness ~88% · Context Debt 12% · +26% (implementation-read
 Recommended: reply `accept recommended` to approve these {N} and generate
 the build brief.
 
-Or reply `detail R7`, `change R3: <edit>`, `drop R8`, `add <topic>`, or `hold`.
+Or reply:
+- `detail R7` to inspect one recommendation
+- `drop R8` to remove one before accepting
+- `change R3: <edit>` to revise one
+- `hold` to stop here
 ```
 
 Notes:
@@ -1551,7 +1612,9 @@ Notes:
 - **One blank line between categories**; titles indent at 3 spaces (so the eye lands on the category name first, then the R-IDs scan down).
 - **Pulse uses full labels** per `references/cli-output-contract.md` § Pulse tier labels.
 - **`accept recommended`** is the visible CTA — NOT `accept all`. "Recommended" frames the action as "the curated set you see on screen"; "all" sounds like a bulk operation over deduped/hidden/raw recs.
-- **`add <topic>`** lets the user request an additional recommendation on the fly (e.g. `add telemetry` → agent calls `regenerate_recommendation` with a new rec hint, or asks the user to clarify what's missing). If the backing API doesn't yet support targeted single-rec addition, prompt the user with: "I can add a rec for `{topic}` by regenerating the full set with that pinned — that takes ~30s. Or hold the current set and add manually via the web UI."
+- **Surface 4 actions at first render — not more.** The four above (`detail R{N}`, `drop R{N}`, `change R{N}: <edit>`, `hold`) cover the decisive cases. Less-frequent actions stay discoverable but off-screen at the landing:
+  - **`add <topic>`** lets the user request an additional recommendation on the fly (e.g. `add telemetry` → agent calls `regenerate_recommendation` with a new rec hint, or asks the user to clarify what's missing). Surface it in `help` or on the 9.3 detail card, NOT in the landing action line — too many actions at once weakens the selection screen. If the backing API doesn't yet support targeted single-rec addition, prompt the user with: "I can add a rec for `{topic}` by regenerating the full set with that pinned — that takes ~30s. Or hold the current set and add manually via the web UI."
+  - **`show scope`** to expand the full problem statement (covered in 9.2).
 
 ##### 9.2 — `show scope` handling
 
@@ -1646,7 +1709,7 @@ Ritual build
 
 Accepted {N} recommendations.
 
-View: https://dev.ritualapp.cloud/e/{exploration_id}
+View: https://app.ritualapp.cloud/e/{exploration_id}
 
 Next: generating the build brief…
 ```
@@ -1783,7 +1846,7 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    ```markdown
    <!--
    Generated by Ritual
-   Exploration: https://dev.ritualapp.cloud/e/{exploration_id}
+   Exploration: https://app.ritualapp.cloud/e/{exploration_id}
    Build brief id: {brief_id}
    Do not remove this header; it preserves implementation lineage.
    -->
@@ -1927,7 +1990,7 @@ feat(<area>): <one-line headline>
 <short body — what changed, why, key trade-off>
 
 Ritual-Exploration: <exploration_id>
-Ritual-Exploration-Url: https://dev.ritualapp.cloud/e/<exploration_id>
+Ritual-Exploration-Url: https://app.ritualapp.cloud/e/<exploration_id>
 Ritual-RBs-Satisfied: RB-1, RB-2, RB-7
 ```
 
@@ -1980,7 +2043,7 @@ If the user says "y" / "push" / "open PR":
 
 ## Exploration
 
-- Exploration: [<exploration name>](https://dev.ritualapp.cloud/e/<exploration_id>)
+- Exploration: [<exploration name>](https://app.ritualapp.cloud/e/<exploration_id>)
 - Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
 - Deferrals intentionally punted: <count, with one-line each>
 

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

@@ -0,0 +1,4 @@
+{
+  "cliVersion": "0.7.11",
+  "builtAt": "2026-05-14T12:14:29.050Z"
+}