@ritualai/cli 0.36.38 → 0.36.39

package/dist/lib/telemetry.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFirstRun = isFirstRun;
+exports.isEnabled = isEnabled;
+exports.setOptOut = setOptOut;
+exports.describeStatus = describeStatus;
+exports.capture = capture;
+exports.identify = identify;
+exports.maybeShowFirstRunNotice = maybeShowFirstRunNotice;
+exports.flush = flush;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const config_1 = require("./config");
+const credentials_backup_1 = require("./credentials-backup");
+const package_info_1 = require("./package-info");
+/**
+ * Anonymous, opt-out usage analytics for the Ritual CLI.
+ *
+ * Design goals:
+ *   - Never blocks a command. Every send is fire-and-forget with a hard
+ *     timeout; failures are swallowed. This is load-bearing for `login`,
+ *     whose browser-loopback must not wait on a telemetry POST.
+ *   - Anonymous until you sign in. A random install id (in
+ *     ~/.config/ritual/telemetry.json) is the distinct_id pre-login; on
+ *     login we $identify it to the Keycloak `sub` so the pre-login funnel
+ *     stitches to the account (and to the marketing-site signup, which
+ *     uses the same PostHog project).
+ *   - Easy to turn off: DO_NOT_TRACK, RITUAL_TELEMETRY=0, or
+ *     `ritual telemetry off`. Always skipped in CI.
+ *
+ * Same PostHog project as ritual.work so the web + CLI funnels are one
+ * graph. Key + host are overridable for self-hosters / tests.
+ */
+const POSTHOG_HOST = (process.env.RITUAL_POSTHOG_HOST || 'https://us.i.posthog.com').replace(/\/$/, '');
+const POSTHOG_KEY = process.env.RITUAL_POSTHOG_KEY || 'phc_nNH8wifJVxDrCfAUabmwni44genZggRTT52CBdtQS4w4';
+// Hard cap on how long a single send can hang. Reachable PostHog answers in
+// ~100-300ms; this only bites when the host is firewalled/black-holed, and it
+// bounds the worst-case latency a telemetry POST can add to a command's exit.
+const SEND_TIMEOUT_MS = 800;
+function statePath() {
+    return (0, node_path_1.join)((0, config_1.configDir)(), 'telemetry.json');
+}
+let cachedState = null;
+const pending = [];
+function isCI() {
+    const e = process.env;
+    return !!(e.CI ||
+        e.CONTINUOUS_INTEGRATION ||
+        e.GITHUB_ACTIONS ||
+        e.GITLAB_CI ||
+        e.CIRCLECI ||
+        e.TRAVIS ||
+        e.BUILDKITE ||
+        e.TF_BUILD ||
+        e.JENKINS_URL);
+}
+function envDisabled() {
+    const e = process.env;
+    if (e.DO_NOT_TRACK === '1' || e.DO_NOT_TRACK === 'true')
+        return true;
+    const t = (e.RITUAL_TELEMETRY || '').toLowerCase();
+    if (t === '0' || t === 'false' || t === 'off' || t === 'no')
+        return true;
+    return false;
+}
+/** True only the very first time the CLI runs on this machine. */
+function isFirstRun() {
+    return !(0, node_fs_1.existsSync)(statePath());
+}
+function readStateRaw() {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(statePath(), 'utf-8'));
+        if (parsed && typeof parsed.installId === 'string')
+            return parsed;
+    }
+    catch {
+        /* missing / corrupt — caller decides */
+    }
+    return null;
+}
+/** Load (and create on first ever call) the telemetry state. */
+function loadState() {
+    if (cachedState)
+        return cachedState;
+    const existing = readStateRaw();
+    if (existing) {
+        cachedState = existing;
+        return existing;
+    }
+    const fresh = {
+        installId: (0, node_crypto_1.randomUUID)(),
+        firstRunAt: new Date().toISOString(),
+    };
+    saveState(fresh);
+    return fresh;
+}
+function saveState(state) {
+    cachedState = state;
+    try {
+        (0, node_fs_1.mkdirSync)((0, config_1.configDir)(), { recursive: true });
+        // Same 0600 create-with-mode helper the credentials store uses —
+        // the install id is low-sensitivity, but keep it owner-only anyway.
+        (0, credentials_backup_1.writeFileMode0600)(statePath(), JSON.stringify(state, null, 2));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Is telemetry on? Env / CI checks come first so opted-out and CI users
+ * never even get an install id written to disk.
+ */
+function isEnabled() {
+    if (envDisabled() || isCI())
+        return false;
+    return !loadState().optedOut;
+}
+/** Persist an explicit opt-in/opt-out (for `ritual telemetry on|off`). */
+function setOptOut(optedOut) {
+    saveState({ ...loadState(), optedOut });
+}
+/** Current opt-out posture for `ritual telemetry status`. */
+function describeStatus() {
+    if (envDisabled())
+        return { enabled: false, reason: 'disabled via DO_NOT_TRACK / RITUAL_TELEMETRY', installId: '—' };
+    if (isCI())
+        return { enabled: false, reason: 'CI environment detected', installId: '—' };
+    const s = loadState();
+    return {
+        enabled: !s.optedOut,
+        reason: s.optedOut ? 'disabled via `ritual telemetry off`' : 'enabled',
+        installId: s.installId,
+    };
+}
+function baseProps() {
+    return {
+        $lib: 'ritual-cli',
+        cli_version: (0, package_info_1.readPackageVersionSafe)(),
+        os: (0, node_os_1.platform)(),
+        arch: process.arch,
+        node_version: process.version,
+        is_ci: isCI(),
+    };
+}
+/** sub once signed in (stitched on $identify), else the anonymous install id. */
+function distinctId() {
+    try {
+        const creds = (0, config_1.loadCredentials)();
+        if (creds?.user?.sub)
+            return creds.user.sub;
+    }
+    catch {
+        /* ignore */
+    }
+    return loadState().installId;
+}
+async function send(body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+    try {
+        await fetch(`${POSTHOG_HOST}/capture/`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        /* network down / aborted / blocked — never surface to the user */
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Fire-and-forget event. No-op when disabled. */
+function capture(event, properties = {}) {
+    if (!isEnabled())
+        return;
+    pending.push(send({
+        api_key: POSTHOG_KEY,
+        event,
+        distinct_id: distinctId(),
+        properties: { ...baseProps(), ...properties },
+        timestamp: new Date().toISOString(),
+    }));
+}
+/**
+ * Link the anonymous install id to the signed-in user (Keycloak sub) and
+ * set durable person properties. Call once, right after a successful login.
+ */
+function identify(sub, person = {}) {
+    if (!isEnabled())
+        return;
+    const installId = loadState().installId;
+    if (!sub || sub === installId)
+        return;
+    pending.push(send({
+        api_key: POSTHOG_KEY,
+        event: '$identify',
+        distinct_id: sub,
+        properties: {
+            $anon_distinct_id: installId, // merges prior anonymous events into the person
+            $set: { ...baseProps(), ...person },
+        },
+        timestamp: new Date().toISOString(),
+    }));
+}
+/**
+ * One-time disclosure. Printed to stderr so it never pollutes stdout that
+ * a script might parse. No-op in CI / when disabled / after first shown.
+ */
+function maybeShowFirstRunNotice() {
+    if (envDisabled() || isCI())
+        return;
+    const s = loadState();
+    if (s.noticeShownAt || s.optedOut)
+        return;
+    saveState({ ...s, noticeShownAt: new Date().toISOString() });
+    process.stderr.write('\n  Ritual CLI collects anonymous usage analytics to help improve the product.\n' +
+        '  Opt out anytime: `ritual telemetry off` (or set RITUAL_TELEMETRY=0).\n\n');
+}
+/** Await in-flight sends (bounded) so events leave before the process exits. */
+async function flush(timeoutMs = SEND_TIMEOUT_MS + 250) {
+    if (pending.length === 0)
+        return;
+    const inFlight = pending.splice(0);
+    await Promise.race([
+        Promise.allSettled(inFlight),
+        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/lib/telemetry.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ritualai/cli",
-  "version": "0.36.38",
+  "version": "0.36.39",
   "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,5 +1,5 @@
 {
-  "cliVersion": "0.36.38",
-  "builtAt": "2026-06-20T13:35:23.818Z",
-  "skillsHash": "ca720305a0e1"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }

package/skills/claude-code/ritual/SKILL.md

@@ -3,8 +3,8 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: ca720305a0e1
-cli_version: 0.36.38
+stamp: 283d2c7cc43e
+cli_version: 0.36.39
 ---
 
 # /ritual

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

@@ -620,12 +620,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

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

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 251c9793521c8486 -->
+<!-- source-sha: 294b970c48a237b5 -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -712,12 +712,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.38",
-  "builtAt": "2026-06-20T13:35:23.818Z",
-  "skillsHash": "ca720305a0e1"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }

package/skills/codex/ritual/SKILL.md

@@ -3,8 +3,8 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: ca720305a0e1
-cli_version: 0.36.38
+stamp: 283d2c7cc43e
+cli_version: 0.36.39
 ---
 
 # /ritual

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

@@ -620,12 +620,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

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

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 251c9793521c8486 -->
+<!-- source-sha: 294b970c48a237b5 -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -712,12 +712,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.38",
-  "builtAt": "2026-06-20T13:35:23.818Z",
-  "skillsHash": "ca720305a0e1"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }

package/skills/cursor/ritual/SKILL.md

@@ -3,8 +3,8 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: ca720305a0e1
-cli_version: 0.36.38
+stamp: 283d2c7cc43e
+cli_version: 0.36.39
 ---
 
 # /ritual

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

@@ -620,12 +620,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

package/skills/cursor/ritual/references/lite-flow.md

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 251c9793521c8486 -->
+<!-- source-sha: 294b970c48a237b5 -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -712,12 +712,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.38",
-  "builtAt": "2026-06-20T13:35:23.818Z",
-  "skillsHash": "ca720305a0e1"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }

package/skills/gemini/ritual/SKILL.md

@@ -3,8 +3,8 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: ca720305a0e1
-cli_version: 0.36.38
+stamp: 283d2c7cc43e
+cli_version: 0.36.39
 ---
 
 # /ritual

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

@@ -620,12 +620,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

package/skills/gemini/ritual/references/lite-flow.md

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 251c9793521c8486 -->
+<!-- source-sha: 294b970c48a237b5 -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -712,12 +712,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.38",
-  "builtAt": "2026-06-20T13:35:23.818Z",
-  "skillsHash": "ca720305a0e1"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }

package/skills/kiro/ritual/SKILL.md

@@ -3,8 +3,8 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: ca720305a0e1
-cli_version: 0.36.38
+stamp: 283d2c7cc43e
+cli_version: 0.36.39
 ---
 
 # /ritual

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

@@ -620,12 +620,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

package/skills/kiro/ritual/references/lite-flow.md

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 251c9793521c8486 -->
+<!-- source-sha: 294b970c48a237b5 -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -712,12 +712,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.38",
-  "builtAt": "2026-06-20T13:35:23.818Z",
-  "skillsHash": "ca720305a0e1"
+  "cliVersion": "0.36.39",
+  "builtAt": "2026-06-20T13:46:17.028Z",
+  "skillsHash": "283d2c7cc43e"
 }