@ritualai/cli 0.7.15 → 0.8.0

package/dist/commands/init.js

@@ -39,6 +39,15 @@ const config_1 = require("../lib/config");
 const api_client_1 = require("../lib/api-client");
 const pat_store_1 = require("../lib/pat-store");
 const oidc_1 = require("../lib/oidc");
+const onboarding_state_1 = require("../lib/onboarding-state");
+const persona_picker_1 = require("../lib/persona-picker");
+const workspace_explainer_1 = require("../lib/workspace-explainer");
+const build_flow_explainer_1 = require("../lib/build-flow-explainer");
+const persona_samples_1 = require("../lib/persona-samples");
+const project_config_1 = require("../lib/project-config");
+const repo_name_1 = require("../lib/repo-name");
+const colors_1 = require("../lib/colors");
+const final_cta_box_1 = require("../lib/final-cta-box");
 const detector_1 = require("../lib/agents/detector");
 const providers_1 = require("../lib/agents/providers");
 const configure_mcp_1 = require("../lib/agents/configure-mcp");
@@ -77,6 +86,13 @@ function resolveIssuerForInit(opts) {
     return undefined; // let auth-flow.ts pick from env / default
 }
 async function initCommand(opts = {}) {
+    // --- --re-onboard reset (must happen BEFORE any "shouldShow*"
+    // gate is consulted by the FTUE helpers below, so the screens
+    // re-render). Cheap, idempotent — just rewrites
+    // `~/.config/ritual/onboarding.json` to an empty record.
+    if (opts.reOnboard) {
+        (0, onboarding_state_1.resetOnboardingState)();
+    }
     // --- Welcome banner (TTY only; skipped for --list early-exit) ----
     // Replaces the previous single-line opener. The banner surfaces
     // identity (when signed in), workspace binding, and "what this
@@ -173,7 +189,13 @@ async function initCommand(opts = {}) {
             // who deliberately scoped a previous init with `--agent`.
             const { existsSync } = await Promise.resolve().then(() => __importStar(require('node:fs')));
             const { join } = await Promise.resolve().then(() => __importStar(require('node:path')));
-            refreshTargets = (0, detector_1.detectAgents)().filter((d) => existsSync(join(projectDir, d.provider.projectSkillDir)));
+            refreshTargets = (0, detector_1.detectAgents)().filter((d) => {
+                // MCP-only agents (no projectSkillDir) have nothing to
+                // refresh on the skill side — silently skipped here.
+                if (!d.provider.projectSkillDir)
+                    return false;
+                return existsSync(join(projectDir, d.provider.projectSkillDir));
+            });
             if (refreshTargets.length === 0) {
                 console.log('  No Ritual skill directories found in this project.');
                 console.log('  Run `ritual init` (without --skills-only) to scaffold them first.');
@@ -186,11 +208,20 @@ async function initCommand(opts = {}) {
         for (const t of refreshTargets) {
             const result = (0, skill_copy_1.copySkillsForProvider)(t.provider, projectDir);
             refreshCopyResults.push(result);
-            if (result.copied > 0) {
-                console.log(`    ✓ ${t.name.padEnd(20)} → ${t.provider.projectSkillDir}/ (${result.copied} skill(s))`);
+            if (result.scopes.length === 0) {
+                // MCP-only agent (e.g. Windsurf as of 0.7.16) — no skill
+                // destination at any scope.
+                console.log(`    – ${t.name.padEnd(20)} ${result.reason ?? 'no skill destination'}`);
+                continue;
             }
-            else {
-                console.log(`    ✗ ${t.name.padEnd(20)} ${result.reason ?? 'unknown failure'}`);
+            for (const s of result.scopes) {
+                const tag = s.scope === 'project' ? 'project' : 'global ';
+                if (s.copied > 0) {
+                    console.log(`    ✓ ${t.name.padEnd(20)} [${tag}] → ${s.destination}/ (${s.copied} skill(s))`);
+                }
+                else {
+                    console.log(`    ✗ ${t.name.padEnd(20)} [${tag}] ${s.reason ?? 'unknown failure'}`);
+                }
             }
         }
         console.log('');
@@ -395,8 +426,22 @@ async function initCommand(opts = {}) {
         console.log(`  ✓ Signed in as ${tokenStatus.creds.user?.email ?? tokenStatus.creds.user?.sub ?? 'unknown'}`);
         console.log('');
     }
-    // --- 2. Detect agents (or pick a specific one) -------------------
+    // --- 2. Detect agents (silently — announcement deferred) --------
+    //
+    // We resolve which agents to write to NOW because the build-flow
+    // explainer below names them in its "your coding agent" zone. But
+    // we intentionally suppress the "Detected N coding agents — here
+    // are the config files we're about to touch" announcement and the
+    // connect-all confirmation gate until AFTER the FTUE explainers.
+    //
+    // Narrative reason: the user just learned what Ritual is (workspace
+    // explainer) and what /ritual build does (build-flow explainer).
+    // Only THEN does "OK we're going to wire that up across these N
+    // agents" land in the right context. Otherwise they're being asked
+    // to confirm a list of agent config writes before they know what
+    // Ritual even does.
     let targets;
+    let agentSummaryToPrint = null;
     if (opts.agent) {
         const provider = (0, providers_1.findProviderById)(opts.agent);
         if (!provider) {
@@ -408,7 +453,7 @@ async function initCommand(opts = {}) {
         }
         // Explicit `--agent` overrides detection — the user knows what
         // they want, don't make them install/symlink the binary just
-        // to pass detection.
+        // to pass detection. Nothing to announce; they typed the name.
         targets = [
             {
                 id: provider.id,
@@ -435,73 +480,20 @@ async function initCommand(opts = {}) {
                     provider: claudeProvider,
                 },
             ];
-            console.log('  No coding agents detected locally.');
-            console.log(`  Defaulting to ${claudeProvider.name} (the documented MCP launch partner).`);
-            console.log('');
-            console.log('  Supported agents:');
-            for (const p of providers_1.PROVIDERS) {
-                console.log(`    • ${p.name.padEnd(20)} (--agent ${p.id})`);
-            }
-            console.log('');
+            agentSummaryToPrint = {
+                scenario: 'none-detected',
+                targets,
+                detected: [],
+                notDetected,
+            };
         }
         else if (detected.length === 1) {
-            // Single-detect: lead with what we're about to do, mention
-            // the escape hatch quietly. No menu, no confirmation —
-            // safe default + visible action (per CLI tenet: lead with
-            // single recommended action + escape hatch).
             targets = detected;
-            const t = detected[0];
-            console.log(`  Detected ${t.name} locally — connecting Ritual there.`);
-            if (t.provider.mcpConfigPath) {
-                console.log(`  Config: ${t.provider.mcpConfigPath}`);
-            }
-            else {
-                console.log(`  Config: managed by \`${t.provider.id}\` CLI`);
-            }
-            if (notDetected.length > 0) {
-                console.log('');
-                console.log(`  Also supported (not detected here): ${notDetected.map((d) => d.name).join(', ')}`);
-                console.log('  Connect another with `ritual init --agent <id>`.');
-            }
-            console.log('');
+            agentSummaryToPrint = { scenario: 'single', targets, detected, notDetected };
         }
         else {
-            // Multi-detect: this IS a real decision gate (one agent vs
-            // seven means writing to one config file vs seven). Tell
-            // the user EXACTLY which files we're about to touch, then
-            // pause with a single-keystroke escape hatch. We don't ask
-            // "which agent?" — connecting all detected agents is the
-            // safe recommended default. Power users can scope down by
-            // pressing Ctrl-C and re-running with `--agent <id>`.
             targets = detected;
-            console.log(`  Detected ${detected.length} coding agents locally — Ritual will connect to each:`);
-            for (const d of detected) {
-                const cfg = d.provider.mcpConfigPath
-                    ? d.provider.mcpConfigPath
-                    : `managed by \`${d.provider.id}\` CLI`;
-                console.log(`    • ${d.name.padEnd(20)} ${cfg}`);
-            }
-            if (notDetected.length > 0) {
-                console.log('');
-                console.log(`  Also supported (not detected here): ${notDetected.map((d) => d.name).join(', ')}`);
-            }
-            console.log('');
-            // TTY-only pause. Non-TTY (CI / scripted installs) skips
-            // straight through — we already printed exactly what we're
-            // about to do, and pausing in CI would hang forever.
-            if (process.stdin.isTTY) {
-                try {
-                    await (0, prompt_1.prompt)('  Press Enter to connect all detected agents, or Ctrl-C to abort\n' +
-                        '  (to pick a single agent, abort and re-run with `ritual init --agent <id>`): ');
-                }
-                catch {
-                    console.log('');
-                    console.log('  Aborted.');
-                    process.exitCode = 1;
-                    return;
-                }
-            }
-            console.log('');
+            agentSummaryToPrint = { scenario: 'multi', targets, detected, notDetected };
         }
     }
     // Type guard for the compiler — by this point one of three paths
@@ -532,9 +524,35 @@ async function initCommand(opts = {}) {
         process.exitCode = 1;
         return;
     }
-    printKeyCreatedBlock(pat, (0, oidc_1.webAppUrlFromIssuer)(issuer), targets);
-    console.log('');
-    // --- 3.5 Bind a project workspace --------------------------------
+    // Note: the "✓ MCP key created — stored in: <agent list>" block is
+    // printed AFTER the FTUE explainers + agent-connect confirmation
+    // (see step 3.8.5 below). The mint itself happens here so any
+    // failure short-circuits init before we've spent the user's time
+    // teaching the mental model; we just defer the user-visible noise.
+    // --- 3.4 FTUE persona picker (one-time per machine) --------------
+    // Runs AFTER auth + PAT mint (so all the mechanical "make Ritual
+    // work" friction is behind us — token cap recovery dialogs, etc.,
+    // don't ambush the user mid-onboarding question) and BEFORE the
+    // workspace explainer (so the explainer can render in the
+    // persona's accent color).
+    const pickedPersona = await maybeRunPersonaPicker(opts);
+    const projectDir = opts.cwd ?? process.cwd();
+    // --- 3.5 FTUE workspace explainer (BEFORE bind) -----------------
+    // The user needs to understand what a workspace IS before being
+    // asked to create one. We render with the *detected* name (from
+    // git-remote or cwd-basename) — the same name resolveProjectWorkspace
+    // will offer as the default in the next step. If they accept the
+    // default the displayed name matches what gets bound; if they
+    // rename, no harm done — the explainer was teaching the concept,
+    // not committing the value.
+    //
+    // We use `loadProjectConfig` first so an already-bound repo (where
+    // the explainer would otherwise re-show on a different machine via
+    // onboarding-state) uses the bound name, not a stale detection.
+    const existingBind = (0, project_config_1.loadProjectConfig)(projectDir);
+    const detectedNameForExplainer = existingBind?.workspaceName ?? (0, repo_name_1.detectRepoName)(projectDir).name;
+    maybeShowWorkspaceExplainer(detectedNameForExplainer, pickedPersona);
+    // --- 3.6 Bind a project workspace --------------------------------
     // Project-scoped state — see ./../lib/workspace-flow.ts for the
     // resolution rules. The result is null when:
     //   - .ritual/config.json already exists (no change to make)
@@ -545,12 +563,60 @@ async function initCommand(opts = {}) {
     // We don't fail init when this returns null — the project just
     // doesn't get a default workspace bound, and downstream tools will
     // prompt for one on first use.
-    const projectDir = opts.cwd ?? process.cwd();
+    //
     // Commander semantics: `--no-workspace` sets `opts.workspace=false`.
     // Default (no flag) leaves it `undefined`. Treat anything except
     // explicit false as "go ahead and prompt".
+    let boundWorkspaceName = existingBind?.workspaceName ?? null;
     if (opts.workspace !== false) {
-        await (0, workspace_flow_1.resolveProjectWorkspace)({ api, projectDir });
+        const bound = await (0, workspace_flow_1.resolveProjectWorkspace)({ api, projectDir });
+        boundWorkspaceName = bound?.workspaceName ?? boundWorkspaceName;
+    }
+    // --- 3.7 Persist personaSlug onto the project config -------------
+    // Repo-team-wide default. Per-machine onboarding-state already
+    // holds the user's pick; here we mirror it into .ritual/config.json
+    // so collaborators on the repo who run `ritual init` later inherit
+    // the same default template, and so `/ritual build` in this repo
+    // can read it without touching the user's home directory.
+    //
+    // We only write if (a) we have a slug picked this run AND (b) the
+    // project config either doesn't have one yet or has an explicit
+    // override request via `--persona`. Never overwrite a teammate's
+    // committed pick silently on a routine re-init.
+    if (pickedPersona) {
+        const existing = (0, project_config_1.loadProjectConfig)(projectDir);
+        if (existing) {
+            const shouldUpdate = !existing.personaSlug || (opts.persona && existing.personaSlug !== pickedPersona);
+            if (shouldUpdate) {
+                (0, project_config_1.saveProjectConfig)(projectDir, { ...existing, personaSlug: pickedPersona });
+            }
+        }
+    }
+    // --- 3.8 Announce agent-config writes + gate on Enter ----------
+    // Agent connection is the LAST mechanical setup step before the
+    // build-flow explainer (which sits below as a "here's what
+    // /ritual build will do" payoff). User flow:
+    //   workspace explainer → bind → wire agents → see /ritual build
+    //   shape → "Setup complete" → they run /ritual build.
+    const proceed = await printAgentSummaryAndConfirm(agentSummaryToPrint);
+    if (!proceed) {
+        process.exitCode = 1;
+        return;
+    }
+    // --- 3.9 FTUE build-flow explainer (right before "Setup complete") -
+    // Now that workspace + agents are wired, show the user what
+    // /ritual build will look like — this is the payoff screen, the
+    // last thing before they go run the actual command.
+    maybeShowBuildFlowExplainer(pickedPersona, targets.filter((t) => t.detected).map((t) => t.name));
+    // --- 3.9.5 Print the deferred "MCP key created" block -----------
+    // The PAT was minted silently in step 3; we held the user-visible
+    // summary until here. Only printed in verbose mode — compact mode
+    // (the default) folds this into the "Ready to ship" CTA below
+    // without listing PAT name, scope, expiry, or storage paths
+    // (those live one command away: `ritual init --verbose`).
+    if (opts.verbose) {
+        printKeyCreatedBlock(pat, (0, oidc_1.webAppUrlFromIssuer)(issuer), targets);
+        console.log('');
     }
     // --- 4. Copy skills + register MCP for each target agent ---------
     const copyResults = [];
@@ -571,8 +637,19 @@ async function initCommand(opts = {}) {
     // keeps the .gitignore block aligned with what's on disk. The
     // helper is idempotent: re-runs replace the marker-bracketed block
     // in place rather than appending duplicates.
+    //
+    // We filter on the PROJECT scope's copy count specifically — a
+    // user-global-only landing (e.g. nothing actually written to the
+    // project tree) shouldn't add a .gitignore entry pointing at an
+    // empty directory.
     const scaffoldedProviders = targets
-        .filter((_, i) => copyResults[i]?.copied)
+        .filter((_, i) => {
+        const result = copyResults[i];
+        if (!result)
+            return false;
+        const projectScope = result.scopes.find((s) => s.scope === 'project');
+        return (projectScope?.copied ?? 0) > 0;
+    })
         .map((t) => t.provider);
     // Fail-soft: a .gitignore write failure (filesystem permissions,
     // read-only volume, exotic project layout) must NOT abort init —
@@ -589,36 +666,76 @@ async function initCommand(opts = {}) {
     }
     // --- 5. Summary --------------------------------------------------
     //
-    // Two pieces of feedback the user gets here:
+    // Two render paths, chosen by `--verbose`:
     //
-    //   (a) `Detected coding agents:` — dotted-aligned table of all
-    //       known agents with `configured` / `not detected` / `failed`
-    //       status. Mirrors the legacy CLI's `printSummary` output so
-    //       any user who used the legacy CLI sees a familiar shape.
+    //   COMPACT (default) — a single "Ready to ship" split-column box
+    //     directly after the build-flow explainer above. Left side:
+    //     per-agent restart instructions + the literal command to ask
+    //     the coding agent next (`/ritual build "<your feature>"`).
+    //     Right side: 3 secondary commands the user can invoke if
+    //     they want detail (`ritual init --verbose`, `ritual doctor`,
+    //     `ritual graph status`). The PAT name / scope / expiry,
+    //     per-agent status table, skill copy paths, and verify-then-
+    //     restart ceremony all live behind `--verbose`. Compact is
+    //     the FTUE default: turn the moment into action instead of
+    //     burying the CTA under setup transcript.
     //
-    //   (b) `Next steps:` — verify-then-restart pattern. Crucially,
-    //       if the user ran `ritual init` from inside a Claude Code
-    //       session (detected via env vars), we surface a prominent
-    //       yellow warning that the CURRENT session won't see the
-    //       new MCP server until restart. This was the single biggest
-    //       footgun the legacy CLI surfaced and we want feature parity.
-    printDetectedAgentsBlock(targets, copyResults, registrationResults);
-    // One-liner about the .gitignore touch, only when we actually
-    // wrote something. Silent on no-op (already up to date or no
-    // scaffolded agents) so the summary doesn't get noisy.
-    if (gitignoreResult?.changed) {
-        const verb = gitignoreResult.preExisting ? 'Updated' : 'Created';
-        const count = gitignoreResult.entries.length;
-        const preview = count <= 2
-            ? gitignoreResult.entries.join(', ')
-            : `${gitignoreResult.entries.slice(0, 1).join(', ')} + ${count - 1} more`;
-        console.log(`  ✓ ${verb} .gitignore (added ${preview})`);
-    }
-    printNextStepsBlock({
-        targets,
-        registrationResults,
-        mcpUrl,
-    });
+    //   VERBOSE (--verbose) — legacy 3-block dump:
+    //     (a) `Coding agent status:` — dotted-aligned table of every
+    //         known agent w/ `configured` / `not detected` / `failed`.
+    //     (b) `.gitignore` one-liner — fail-soft surface for the
+    //         scaffolded-paths gitignore update.
+    //     (c) `Next steps:` — verify-then-restart pattern, includes
+    //         the ⚠ inside-Claude warning, `claude mcp list`
+    //         verification, per-agent restart hints, and quick-
+    //         reference command list. This is what a power user
+    //         invokes when they want to see exactly what landed on
+    //         disk. Same detail is also reachable via `ritual doctor`.
+    if (opts.verbose) {
+        printDetectedAgentsBlock(targets, copyResults, registrationResults);
+        if (gitignoreResult?.changed) {
+            const verb = gitignoreResult.preExisting ? 'Updated' : 'Created';
+            const count = gitignoreResult.entries.length;
+            const preview = count <= 2
+                ? gitignoreResult.entries.join(', ')
+                : `${gitignoreResult.entries.slice(0, 1).join(', ')} + ${count - 1} more`;
+            console.log(`  ✓ ${verb} .gitignore (added ${preview})`);
+        }
+        printNextStepsBlock({
+            targets,
+            registrationResults,
+            mcpUrl,
+        });
+    }
+    else {
+        // Compact: render the "Ready to ship" CTA box. The inside-
+        // Claude warning is safety-critical (the CURRENT session
+        // won't see the new MCP server until restart) so it surfaces
+        // in both modes; the CTA box renders it as a bold amber row
+        // above the restart bullets.
+        const wiredAgentNames = targets
+            .filter((t, i) => registrationResults[i]?.success)
+            .map((t) => t.name);
+        const insideClaudeWarning = wiredAgentNames.includes('Claude Code') && isInsideClaudeCode()
+            ? 'inside Claude Code — restart this session first'
+            : '';
+        // Tier the CTA renderer to the terminal's actual width. The
+        // rich split-column box wants ≥ 112 cols (LEFT_W=64 + divider
+        // + ~45-char right column + chrome) — anything narrower would
+        // either truncate the secondary command labels or push the
+        // inner divider out of alignment. Below that, fall through to
+        // the styled vertical stack (still ANSI-color-aware) which
+        // works cleanly at 78+. Below 78 — or non-TTY — colors degrade
+        // to plain via the colors.ts auto-detection.
+        const isTty = !!process.stdout.isTTY;
+        const cols = process.stdout.columns ?? 0;
+        if (isTty && cols >= 112) {
+            (0, final_cta_box_1.printFinalCtaBox)({ wiredAgentNames, insideClaudeWarning });
+        }
+        else {
+            (0, final_cta_box_1.printFinalCtaBoxTerse)({ wiredAgentNames, insideClaudeWarning });
+        }
+    }
 }
 // webAppUrlFromIssuer is exported from lib/oidc.ts — single source of
 // truth so the dev/prod/self-hosted mapping stays consistent across
@@ -719,15 +836,39 @@ function printDetectedAgentsBlock(targets, copyResults, registrationResults) {
         }
     }
     // Per-agent skill copy summary — kept here because users sometimes
-    // scan the dotted table and miss the more detailed counts.
+    // scan the dotted table and miss the more detailed counts. Includes
+    // per-scope detail (project vs user-global) so users can see exactly
+    // where /ritual landed and verify the scope-match invariant: any
+    // session that can reach mcp__ritual__* should also know what
+    // /ritual is. See FTUE analysis 2026-05-19.
     console.log('');
-    console.log('  Skills copied:');
+    console.log('  Skills installed:');
     for (const t of targets) {
         const copy = copyResults.find((r) => r.provider.id === t.provider.id);
-        const status = copy.copied > 0
-            ? `${copy.copied} → ${t.provider.projectSkillDir}/`
-            : `skipped (${copy.reason ?? 'unknown'})`;
-        console.log(`    ${t.provider.name}: ${status}`);
+        if (copy.scopes.length === 0) {
+            // MCP-only agent (Windsurf): MCP tools are configured but
+            // the agent doesn't have a skill-install convention the
+            // CLI populates. Be explicit so the user isn't surprised
+            // that `/ritual` (or its agent-specific equivalent) is
+            // absent — MCP tools still work.
+            console.log(`    ${t.provider.name}: MCP tools only — agent has no skill-install convention this CLI populates`);
+            continue;
+        }
+        for (const s of copy.scopes) {
+            const scopeLabel = s.scope === 'project' ? 'project' : 'user-global';
+            const status = s.copied > 0
+                ? `${s.copied} → ${s.destination}/`
+                : `skipped (${s.reason ?? 'unknown'})`;
+            console.log(`    ${t.provider.name} [${scopeLabel}]: ${status}`);
+        }
+        // Surface the Cursor / Windsurf asymmetry inline so the user
+        // understands why some agents lack a user-global entry. Keep
+        // the note narrow and actionable; full detail lives in
+        // `ritual doctor`.
+        if (!t.provider.userSkillDir && t.provider.projectSkillDir) {
+            console.log(`      note: ${t.provider.name} has no on-disk user-global skill location — ` +
+                `open ${t.provider.name} in this project's directory to use the skill.`);
+        }
     }
 }
 /**
@@ -818,4 +959,223 @@ function isInsideClaudeCode() {
         !!process.env.CLAUDE_CODE_ENTRYPOINT ||
         !!process.env.CLAUDE_CODE_SESSION_ID);
 }
+/**
+ * Render the agent-connection summary (which configs we're about to
+ * touch) and, in the multi-detect case, gate on Enter-to-continue.
+ *
+ * Returns `false` if the user aborted; the caller must short-circuit
+ * the rest of init and set process.exitCode = 1. `true` means proceed.
+ *
+ * For the `explicit` path (--agent <id>) the caller passes null and
+ * we skip this entirely — the user typed the agent name, no surprise
+ * to soften.
+ */
+async function printAgentSummaryAndConfirm(summary) {
+    if (!summary)
+        return true;
+    // Shared 78-char box helpers — same width as the FTUE explainers
+    // so the agent-connect step reads as part of the same visual
+    // family rather than a console dump in the middle of boxed UI.
+    const W = 78;
+    const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, ''); // eslint-disable-line no-control-regex
+    const padded = (content) => {
+        const visLen = stripAnsi(content).length;
+        const pad = ' '.repeat(Math.max(0, W - 2 - visLen));
+        return `│${content}${pad}│`;
+    };
+    const top = (title) => {
+        const visLen = stripAnsi(title).length;
+        const fill = '─'.repeat(Math.max(0, W - visLen - 4));
+        return `╭ ${title} ${fill}╮`;
+    };
+    const bottom = '╰' + '─'.repeat(W - 2) + '╯';
+    const renderBox = (titleBar, bodyLines) => {
+        console.log(top(titleBar));
+        console.log(padded(''));
+        for (const line of bodyLines) {
+            console.log(padded(line));
+        }
+        console.log(padded(''));
+        console.log(bottom);
+    };
+    // ─── scenario: none detected ────────────────────────────────────
+    if (summary.scenario === 'none-detected') {
+        const claude = summary.targets[0];
+        renderBox((0, colors_1.color)(colors_1.RITUAL_TEAL, '─ wire your coding agent '), [
+            `  ${(0, colors_1.dim)('no coding agents detected on this machine — defaulting to:')}`,
+            '',
+            `  ${(0, colors_1.boldColor)(colors_1.RITUAL_TEAL, '✓ ' + claude.name)}   ${(0, colors_1.dim)('(the documented MCP launch partner)')}`,
+            '',
+            `  ${(0, colors_1.dim)('also supported (re-run with --agent <id>):')}`,
+            ...providers_1.PROVIDERS.filter((p) => p.id !== claude.id).map((p) => `    ${(0, colors_1.dim)('·')} ${(0, colors_1.dim)(p.name.padEnd(20))} ${(0, colors_1.dim)('--agent ' + p.id)}`),
+        ]);
+        console.log('');
+        return true;
+    }
+    // ─── scenario: single detected ─────────────────────────────────
+    if (summary.scenario === 'single') {
+        const t = summary.detected[0];
+        const notDetected = summary.notDetected.map((d) => d.name).join(', ');
+        renderBox((0, colors_1.color)(colors_1.RITUAL_TEAL, '─ wire your coding agent '), [
+            `  ${(0, colors_1.dim)('detected one coding agent on this machine — wiring up:')}`,
+            '',
+            `  ${(0, colors_1.boldColor)(colors_1.RITUAL_TEAL, '✓ ' + t.name)}`,
+            '',
+            ...(notDetected
+                ? [
+                    `  ${(0, colors_1.dim)('also supported (not detected here): ' + notDetected)}`,
+                    `  ${(0, colors_1.dim)('connect another with `ritual init --agent <id>`')}`,
+                ]
+                : []),
+        ]);
+        console.log('');
+        return true;
+    }
+    // ─── scenario: multi-detect (real decision gate) ────────────────
+    const notDetectedList = summary.notDetected.map((d) => d.name).join(', ');
+    renderBox((0, colors_1.color)(colors_1.RITUAL_TEAL, '─ wire your coding agents '), [
+        `  ${(0, colors_1.dim)(`detected ${summary.detected.length} coding agents on this machine — wiring up:`)}`,
+        '',
+        ...summary.detected.map((d) => `  ${(0, colors_1.boldColor)(colors_1.RITUAL_TEAL, '✓ ' + d.name)}`),
+        '',
+        ...(notDetectedList
+            ? [`  ${(0, colors_1.dim)('also supported (not detected here): ' + notDetectedList)}`]
+            : []),
+        `  ${(0, colors_1.dim)('config paths: ritual doctor')}`,
+    ]);
+    console.log('');
+    // TTY-only pause. Non-TTY (CI / scripted) skips through — we
+    // already printed exactly what's about to happen, and pausing in
+    // CI would hang forever.
+    if (process.stdin.isTTY) {
+        try {
+            await (0, prompt_1.prompt)(`  ${(0, colors_1.color)(colors_1.RITUAL_TEAL, '›')} press Enter to wire all ${summary.detected.length}, ` +
+                `or Ctrl-C to abort\n` +
+                `  ${(0, colors_1.dim)('(single agent? abort + re-run with `ritual init --agent <id>`)')}: `);
+        }
+        catch {
+            console.log('');
+            console.log('  Aborted.');
+            return false;
+        }
+    }
+    console.log('');
+    return true;
+}
+// ─── FTUE onboarding helpers ────────────────────────────────────────────────
+/**
+ * Coerce a raw `--persona <slug>` CLI value into a known PersonaSlug.
+ * Returns the validated slug on hit, prints a friendly error and
+ * returns undefined on miss. The caller treats "miss" as "abort
+ * init" — silently falling through to the picker would be confusing
+ * when the user clearly intended a specific persona.
+ */
+function validatePersonaFlag(raw) {
+    if (!raw)
+        return undefined;
+    const persona = (0, persona_samples_1.findPersona)(raw);
+    if (!persona) {
+        console.error(`  ✗ Unknown persona: "${raw}".`);
+        console.error('    Run `ritual init --list` for agents; persona slugs live in the CLI docs.');
+        console.error('');
+        return null;
+    }
+    return persona.slug;
+}
+/**
+ * Run the persona-picker screen if the user hasn't been onboarded
+ * yet (or `--re-onboard` is set / `--persona` was passed).
+ *
+ * Returns the resolved persona slug (or null if the user explicitly
+ * skipped). Always updates the per-machine onboarding state with the
+ * outcome so we don't re-prompt next time.
+ *
+ * Non-TTY: respects the `--persona` flag if provided; otherwise
+ * silently no-ops and returns null. We never block scripted/CI init
+ * on a missing persona — downstream tools degrade gracefully via
+ * the generic persona.
+ */
+async function maybeRunPersonaPicker(opts) {
+    const state = (0, onboarding_state_1.readOnboardingState)();
+    // Explicit override via flag — always takes precedence.
+    if (opts.persona) {
+        const slug = validatePersonaFlag(opts.persona);
+        if (slug === null) {
+            // Unknown slug — caller will treat the absence as a soft fail.
+            return null;
+        }
+        if (slug) {
+            (0, onboarding_state_1.updateOnboardingState)({
+                personaPickedAt: new Date().toISOString(),
+                personaSlug: slug,
+            });
+            return slug;
+        }
+    }
+    if (!(0, onboarding_state_1.shouldShowPersonaPicker)(state)) {
+        // Already onboarded — re-use the stored pick. `null` here means
+        // the user explicitly skipped on a previous init; we honor that.
+        return state.personaSlug ?? null;
+    }
+    if (!process.stdin.isTTY) {
+        // Non-TTY first-time init: no picker, no persistence. We don't
+        // mark onboarding as "done" because a future interactive init
+        // can still ask.
+        return null;
+    }
+    try {
+        const result = await (0, persona_picker_1.pickPersona)();
+        (0, onboarding_state_1.updateOnboardingState)({
+            personaPickedAt: new Date().toISOString(),
+            personaSlug: result?.slug ?? null,
+        });
+        return result?.slug ?? null;
+    }
+    catch {
+        // Readline failed for any reason — don't crash init.
+        return null;
+    }
+}
+/**
+ * Show the workspace explainer (screen #2) if the user hasn't seen
+ * it yet on this machine. Marks it seen on first render so we don't
+ * lecture the user on every subsequent `ritual init` in a new repo.
+ *
+ * Falls back to the terse non-TTY printer when stdout isn't a TTY
+ * OR the terminal is narrower than the rich layout assumes (<80
+ * cols), so we still teach the model without busting the wrap.
+ */
+function maybeShowWorkspaceExplainer(workspaceName, personaSlug) {
+    const state = (0, onboarding_state_1.readOnboardingState)();
+    if (!(0, onboarding_state_1.shouldShowWorkspaceExplainer)(state))
+        return;
+    const isTty = !!process.stdout.isTTY;
+    const cols = process.stdout.columns ?? 80;
+    if (isTty && cols >= 80) {
+        (0, workspace_explainer_1.printWorkspaceExplainer)({ workspaceName, personaSlug });
+    }
+    else {
+        (0, workspace_explainer_1.printWorkspaceExplainerTerse)({ workspaceName, personaSlug });
+    }
+    (0, onboarding_state_1.updateOnboardingState)({ workspaceExplainerSeenAt: new Date().toISOString() });
+}
+/**
+ * Show the build-flow explainer (screen #3) if the user hasn't seen
+ * it yet on this machine. Mirrors the workspace explainer's gating
+ * + non-TTY fallback. `detectedAgents` shapes the coding-agent zone.
+ */
+function maybeShowBuildFlowExplainer(personaSlug, detectedAgents) {
+    const state = (0, onboarding_state_1.readOnboardingState)();
+    if (!(0, onboarding_state_1.shouldShowBuildFlowExplainer)(state))
+        return;
+    const isTty = !!process.stdout.isTTY;
+    const cols = process.stdout.columns ?? 80;
+    if (isTty && cols >= 80) {
+        (0, build_flow_explainer_1.printBuildFlowExplainer)({ personaSlug, detectedAgents });
+    }
+    else {
+        (0, build_flow_explainer_1.printBuildFlowExplainerTerse)({ personaSlug, detectedAgents });
+    }
+    (0, onboarding_state_1.updateOnboardingState)({ buildFlowExplainerSeenAt: new Date().toISOString() });
+}
 //# sourceMappingURL=init.js.map