@ritualai/cli 0.7.16 → 0.8.0

package/dist/lib/workspace-explainer.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Workspace explainer — onboarding screen #2 of 3.
+ *
+ * Shown once per machine on first `ritual init` (gated by
+ * onboarding-state.ts). Teaches the user the mental model:
+ *
+ *   - Workspace = container for explorations on this codebase
+ *   - Explorations = boxes of work (problem → answers → recs → brief → impl)
+ *   - Context flows between explorations within a workspace
+ *     (decisions, anti-goals, file lineage carry forward)
+ *
+ * Personalized via:
+ *   - Workspace name (git-remote-detected, falls back to cwd basename)
+ *   - Persona slug (when set) → discipline framing + 3 sample
+ *     exploration names from persona-samples.ts
+ *
+ * Non-TTY fallback: terse 3-line summary printed via printTerse().
+ * Caller is expected to check tty + onboarding state before calling
+ * the rich version.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectColorMode = void 0;
+exports.printWorkspaceExplainer = printWorkspaceExplainer;
+exports.printWorkspaceExplainerTerse = printWorkspaceExplainerTerse;
+const colors_1 = require("./colors");
+Object.defineProperty(exports, "detectColorMode", { enumerable: true, get: function () { return colors_1.detectColorMode; } });
+const persona_samples_1 = require("./persona-samples");
+/** Width target. Matches welcome-banner.ts for visual consistency. */
+const BOX_WIDTH = 78;
+/**
+ * Render the workspace explainer to stdout. Always renders (caller
+ * decides whether to skip based on TTY + onboarding-state).
+ *
+ * The rich version assumes ≥80-char terminal width. For narrower
+ * terminals, callers should prefer printTerse().
+ */
+function printWorkspaceExplainer(opts) {
+    const persona = (0, persona_samples_1.findPersona)(opts.personaSlug) ?? persona_samples_1.GENERIC_PERSONA;
+    const accent = persona.accent;
+    const lines = [];
+    // Title bar carries the workspace name + brand-teal accent. The
+    // body BELOW it actually teaches what a workspace IS (replaces an
+    // earlier draft that just labeled "workspace: foo / you build: bar"
+    // without explaining the concept — the visual cards alone weren't
+    // enough to land it).
+    lines.push(box.top(BOX_WIDTH, (0, colors_1.color)(accent, `─ workspace: "${opts.workspaceName}" `)));
+    lines.push(box.padded(BOX_WIDTH, ''));
+    // Value-prop framing — mirrors the developer landing page at
+    // ritual.work/product/developer ("structured discovery, living
+    // specs, plans with less guesswork — so AI agents land changes
+    // you'd actually merge"). One bold opener + two dim continuation
+    // lines so the eye lands on the verb-noun phrases without the
+    // outcome clause getting lost in the wrap.
+    lines.push(box.padded(BOX_WIDTH, `  ${(0, colors_1.boldColor)(accent, 'where structured discovery, living specs, and plans with')}`));
+    lines.push(box.padded(BOX_WIDTH, `  ${(0, colors_1.boldColor)(accent, 'less guesswork come together —')}`));
+    lines.push(box.padded(BOX_WIDTH, `  ${(0, colors_1.dim)('so AI agents land changes you\'d actually merge.')}`));
+    lines.push(box.padded(BOX_WIDTH, ''));
+    // Inner container with 3 exploration cards side-by-side
+    lines.push(box.padded(BOX_WIDTH, '  ' + (0, colors_1.dim)('┌' + '─'.repeat(BOX_WIDTH - 8) + '┐')));
+    lines.push(box.padded(BOX_WIDTH, '  ' + (0, colors_1.dim)('│') + ' '.repeat(BOX_WIDTH - 8) + (0, colors_1.dim)('│')));
+    const cards = renderExplorationCardsRow(persona);
+    for (const cardLine of cards) {
+        lines.push(box.padded(BOX_WIDTH, '  ' + (0, colors_1.dim)('│ ') + cardLine + (0, colors_1.dim)(' │')));
+    }
+    // Down-arrows pointing to shared context
+    const arrowsLine = '       ↓               ↓               ↓';
+    lines.push(box.padded(BOX_WIDTH, '  ' + (0, colors_1.dim)('│   ') + (0, colors_1.dim)(arrowsLine.padEnd(BOX_WIDTH - 16)) + (0, colors_1.dim)('│')));
+    // Shared context strip
+    const contextLines = [
+        '  ┌─ shared context · knowledge graph ' + '─'.repeat(28) + '┐',
+        '  │ • decisions in one carry to the next' + ' '.repeat(28) + '│',
+        '  │ • anti-goals propagate forward' + ' '.repeat(34) + '│',
+        '  │ • file lineage: which exploration shaped this' + ' '.repeat(19) + '│',
+        '  │ • prior implementations inform new explorations' + ' '.repeat(17) + '│',
+        '  └' + '─'.repeat(65) + '┘',
+    ];
+    for (const cl of contextLines) {
+        lines.push(box.padded(BOX_WIDTH, '  ' + (0, colors_1.dim)('│ ') + (0, colors_1.color)(accent, cl) + (0, colors_1.dim)(' │')));
+    }
+    lines.push(box.padded(BOX_WIDTH, '  ' + (0, colors_1.dim)('│') + ' '.repeat(BOX_WIDTH - 8) + (0, colors_1.dim)('│')));
+    lines.push(box.padded(BOX_WIDTH, '  ' + (0, colors_1.dim)('└' + '─'.repeat(BOX_WIDTH - 8) + '┘')));
+    lines.push(box.padded(BOX_WIDTH, ''));
+    // What you'll do here. Kept short: only commands that exist + are
+    // expected to be the first thing the user reaches for. `/ritual
+    // lineage` lived here in the first draft; pulled because it's not
+    // shipping in the same window as this onboarding flow and we
+    // don't want to teach a command that doesn't work yet.
+    lines.push(box.padded(BOX_WIDTH, `  ${(0, colors_1.boldColor)(accent, 'what you\'ll do here:')}`));
+    lines.push(box.padded(BOX_WIDTH, `    ${(0, colors_1.dim)('›')} /ritual build <feature>   ${(0, colors_1.dim)('create an exploration')}`));
+    lines.push(box.padded(BOX_WIDTH, `    ${(0, colors_1.dim)('›')} /ritual resume            ${(0, colors_1.dim)('pick up where you left off')}`));
+    lines.push(box.padded(BOX_WIDTH, ''));
+    lines.push(box.bottom(BOX_WIDTH));
+    for (const line of lines) {
+        process.stdout.write(line + '\n');
+    }
+}
+/**
+ * Terse single-line-per-concept fallback for non-TTY or narrow
+ * terminals. No colors, no boxes — just the teaching.
+ */
+function printWorkspaceExplainerTerse(opts) {
+    // `persona` is intentionally not consulted in the terse path —
+    // the framing line was pulled in favor of an actual definition.
+    // Persona-specific examples still surface in the rich version.
+    void (0, persona_samples_1.findPersona)(opts.personaSlug);
+    process.stdout.write(`\n  workspace: "${opts.workspaceName}"\n`);
+    process.stdout.write('\n');
+    process.stdout.write('  Where structured discovery, living specs, and plans with less\n');
+    process.stdout.write('  guesswork come together — so AI agents land changes you\'d\n');
+    process.stdout.write('  actually merge.\n');
+    process.stdout.write('\n');
+    process.stdout.write('  Use /ritual build <feature> to create an exploration. /ritual resume\n');
+    process.stdout.write('  to pick up where you left off.\n');
+    process.stdout.write('\n');
+}
+// ─── helpers ────────────────────────────────────────────────────────────────
+/**
+ * Render the 3 exploration cards as a single 4-line column-block:
+ * top border with the "exploration" label, two title lines (most
+ * titles wrap to 2; short ones get a blank second line), bottom
+ * border. Lifecycle bullets used to live here; they were dropped
+ * because they teach the SAME thing as the build-flow explainer's
+ * phase chain (which is the right place for that detail). The
+ * workspace explainer should only convey the unit + that multiple
+ * units coexist in a workspace.
+ *
+ * Each card is 18 visible chars wide (`┌─ exploration ──┐`); 3 cards
+ * + 2 separators (2 spaces each) = 18*3 + 4 = 58 chars, well within
+ * the BOX_WIDTH - 8 = 70 inner budget.
+ */
+function renderExplorationCardsRow(persona) {
+    const titles = persona.sampleExplorations;
+    // Card body width (inside the side `│ … │` chars). Matches the
+    // width of the top/bottom borders so all three rows align cleanly.
+    const bodyW = 14;
+    // Wrap each title to 2 lines; pad the second line with empty so
+    // short titles still occupy the full card height.
+    const wrap = (s) => {
+        if (s.length <= bodyW)
+            return [s, ''];
+        const cut = s.slice(0, bodyW).lastIndexOf(' ');
+        if (cut <= 0)
+            return [s.slice(0, bodyW), s.slice(bodyW, 2 * bodyW)];
+        return [s.slice(0, cut), s.slice(cut + 1, cut + 1 + bodyW)];
+    };
+    const wrapped = titles.map(wrap);
+    const pad = (s) => s.padEnd(bodyW, ' ');
+    const top = '┌─ exploration ──┐';
+    const mid = '│';
+    const bot = '└────────────────┘';
+    const lines = [];
+    // Top border × 3
+    lines.push([top, top, top].join('  '));
+    // Title line 1 × 3
+    lines.push([wrapped[0][0], wrapped[1][0], wrapped[2][0]]
+        .map((t) => `${mid} ${pad(t)} ${mid}`)
+        .join('  '));
+    // Title line 2 × 3 (blank for short titles)
+    lines.push([wrapped[0][1], wrapped[1][1], wrapped[2][1]]
+        .map((t) => `${mid} ${pad(t)} ${mid}`)
+        .join('  '));
+    // Bottom border × 3
+    lines.push([bot, bot, bot].join('  '));
+    return lines;
+}
+/**
+ * Minimal box-drawing helpers. Local to this module to keep the
+ * file self-contained; if the workspace + build-flow explainers
+ * grow more shared box logic we can factor into a `box.ts`.
+ */
+const box = {
+    top(width, title) {
+        // Title sits at column 2, padded with ─ to fill width.
+        const stripped = stripAnsi(title);
+        const fillWidth = width - stripped.length - 4;
+        return `╭ ${title} ${'─'.repeat(Math.max(0, fillWidth))}╮`;
+    },
+    bottom(width) {
+        return '╰' + '─'.repeat(width - 2) + '╯';
+    },
+    padded(width, content) {
+        const stripped = stripAnsi(content);
+        const pad = ' '.repeat(Math.max(0, width - 2 - stripped.length));
+        return `│${content}${pad}│`;
+    },
+};
+/** Strip ANSI escape sequences so padding math is correct. */
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+//# sourceMappingURL=workspace-explainer.js.map

package/dist/lib/workspace-explainer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-explainer.js","sourceRoot":"","sources":["../../src/lib/workspace-explainer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAsBH,0DAwFC;AAMD,oEAcC;AAhID,qCAA+E;AA0NtE,gGA1NoC,wBAAe,OA0NpC;AAzNxB,uDAAqF;AASrF,sEAAsE;AACtE,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;;;;;GAMG;AACH,SAAgB,uBAAuB,CAAC,IAA+B;IACtE,MAAM,OAAO,GAAG,IAAA,6BAAW,EAAC,IAAI,CAAC,WAAW,CAAC,IAAI,iCAAe,CAAC;IACjE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAE9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,gEAAgE;IAChE,kEAAkE;IAClE,oEAAoE;IACpE,kEAAkE;IAClE,sBAAsB;IACtB,KAAK,CAAC,IAAI,CACT,GAAG,CAAC,GAAG,CACN,SAAS,EACT,IAAA,cAAK,EAAC,MAAM,EAAE,iBAAiB,IAAI,CAAC,aAAa,IAAI,CAAC,CACtD,CACD,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IACtC,6DAA6D;IAC7D,+DAA+D;IAC/D,+DAA+D;IAC/D,iEAAiE;IACjE,8DAA8D;IAC9D,2CAA2C;IAC3C,KAAK,CAAC,IAAI,CACT,GAAG,CAAC,MAAM,CACT,SAAS,EACT,KAAK,IAAA,kBAAS,EAAC,MAAM,EAAE,0DAA0D,CAAC,EAAE,CACpF,CACD,CAAC;IACF,KAAK,CAAC,IAAI,CACT,GAAG,CAAC,MAAM,CACT,SAAS,EACT,KAAK,IAAA,kBAAS,EAAC,MAAM,EAAE,gCAAgC,CAAC,EAAE,CAC1D,CACD,CAAC;IACF,KAAK,CAAC,IAAI,CACT,GAAG,CAAC,MAAM,CACT,SAAS,EACT,KAAK,IAAA,YAAG,EAAC,kDAAkD,CAAC,EAAE,CAC9D,CACD,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAEtC,wDAAwD;IACxD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,GAAG,IAAA,YAAG,EAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACrF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,GAAG,IAAA,YAAG,EAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,IAAA,YAAG,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAE1F,MAAM,KAAK,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACjD,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,GAAG,IAAA,YAAG,EAAC,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAA,YAAG,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,yCAAyC;IACzC,MAAM,UAAU,GAAG,0CAA0C,CAAC;IAC9D,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,GAAG,IAAA,YAAG,EAAC,MAAM,CAAC,GAAG,IAAA,YAAG,EAAC,UAAU,CAAC,MAAM,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC,GAAG,IAAA,YAAG,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAE1G,uBAAuB;IACvB,MAAM,YAAY,GAAG;QACpB,wCAAwC,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG;QAC/D,0CAA0C,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG;QACjE,oCAAoC,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG;QAC3D,mDAAmD,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG;QAC1E,qDAAqD,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG;QAC5E,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG;KAC5B,CAAC;IACF,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,GAAG,IAAA,YAAG,EAAC,IAAI,CAAC,GAAG,IAAA,cAAK,EAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAA,YAAG,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrF,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,GAAG,IAAA,YAAG,EAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,IAAA,YAAG,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC1F,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,GAAG,IAAA,YAAG,EAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACrF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAEtC,kEAAkE;IAClE,gEAAgE;IAChE,kEAAkE;IAClE,6DAA6D;IAC7D,uDAAuD;IACvD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,IAAA,kBAAS,EAAC,MAAM,EAAE,uBAAuB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,IAAA,YAAG,EAAC,GAAG,CAAC,8BAA8B,IAAA,YAAG,EAAC,uBAAuB,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/G,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,IAAA,YAAG,EAAC,GAAG,CAAC,8BAA8B,IAAA,YAAG,EAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC,CAAC;IACpH,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACnC,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,SAAgB,4BAA4B,CAAC,IAA+B;IAC3E,+DAA+D;IAC/D,gEAAgE;IAChE,+DAA+D;IAC/D,KAAK,IAAA,6BAAW,EAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,IAAI,CAAC,aAAa,KAAK,CAAC,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;IAC1F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACvF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0EAA0E,CAAC,CAAC;IACjG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,SAAS,yBAAyB,CAAC,OAAsB;IACxD,MAAM,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAC1C,+DAA+D;IAC/D,mEAAmE;IACnE,MAAM,KAAK,GAAG,EAAE,CAAC;IAEjB,gEAAgE;IAChE,kDAAkD;IAClD,MAAM,IAAI,GAAG,CAAC,CAAS,EAAoB,EAAE;QAC5C,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK;YAAE,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC/C,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;QACpE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAEhD,MAAM,GAAG,GAAG,oBAAoB,CAAC;IACjC,MAAM,GAAG,GAAG,GAAG,CAAC;IAChB,MAAM,GAAG,GAAG,oBAAoB,CAAC;IAEjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,iBAAiB;IACjB,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,mBAAmB;IACnB,KAAK,CAAC,IAAI,CACT,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;SACrC,IAAI,CAAC,IAAI,CAAC,CACZ,CAAC;IACF,4CAA4C;IAC5C,KAAK,CAAC,IAAI,CACT,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;SACrC,IAAI,CAAC,IAAI,CAAC,CACZ,CAAC;IACF,oBAAoB;IACpB,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAEvC,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,GAAG,GAAG;IACX,GAAG,CAAC,KAAa,EAAE,KAAa;QAC/B,uDAAuD;QACvD,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QAC9C,OAAO,KAAK,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC;IAC5D,CAAC;IACD,MAAM,CAAC,KAAa;QACnB,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IAC1C,CAAC;IACD,MAAM,CAAC,KAAa,EAAE,OAAe;QACpC,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACjE,OAAO,IAAI,OAAO,GAAG,GAAG,GAAG,CAAC;IAC7B,CAAC;CACD,CAAC;AAEF,8DAA8D;AAC9D,SAAS,SAAS,CAAC,CAAS;IAC3B,4CAA4C;IAC5C,OAAO,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/lib/workspace-flow.js

@@ -21,13 +21,14 @@ async function resolveProjectWorkspace(opts) {
         return null;
     }
     const detection = (0, repo_name_1.detectRepoName)(opts.projectDir);
-    console.log('');
-    console.log('  No Ritual workspace is bound to this project yet.');
-    console.log('');
-    console.log('  A workspace is this project\'s persistent memory in Ritual — explorations,');
-    console.log('  decisions, build briefs, and context agents can reuse across sessions.');
-    console.log('');
-    console.log(`  Detected project name: ${detection.name}  (from ${detection.source}${detection.originUrl ? ` — ${detection.originUrl}` : ''})`);
+    // Concept-level "what is a workspace" copy AND the "Detected
+    // project name: foo (from cwd-basename)" line used to live here.
+    // Both moved out: the explainer above teaches the concept and
+    // already renders the workspace name in its title, so repeating
+    // "Detected project name: foo" in this prompt is redundant. The
+    // detected name still appears INSIDE the bind question itself
+    // (`Create new workspace "foo"…?`), which is where the user
+    // actually needs to see it to accept or rename.
     console.log('');
     let answer;
     try {

package/dist/lib/workspace-flow.js.map

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

package/package.json

@@ -1,75 +1,75 @@
 {
-	"name": "@ritualai/cli",
-	"version": "0.7.16",
-	"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",
-	"homepage": "https://ritual.work/ritual-mcp/docs/",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Ritual-Mobile/ritual-enterprise.git",
-		"directory": "apps/cli"
-	},
-	"author": "Ritual",
-	"publishConfig": {
-		"access": "public"
-	},
-	"bin": {
-		"ritual": "./dist/index.js"
-	},
-	"main": "./dist/index.js",
-	"files": [
-		"dist",
-		"skills",
-		"README.md"
-	],
-	"scripts": {
-		"build:skills": "node scripts/build-skills.js",
-		"build:ts": "tsc -p tsconfig.json",
-		"build": "pnpm run build:skills && pnpm run build:ts",
-		"dev": "tsx src/index.ts",
-		"clean": "rm -rf dist skills",
-		"typecheck": "tsc --noEmit -p tsconfig.json",
-		"test": "jest --passWithNoTests",
-		"prepublishOnly": "pnpm run clean && pnpm run build"
-	},
-	"dependencies": {
-		"commander": "^14.0.3",
-		"open": "^10.1.0"
-	},
-	"devDependencies": {
-		"@ritual/shared-types": "workspace:^",
-		"@types/jest": "^29.5.0",
-		"@types/node": "^20.0.0",
-		"jest": "^29.7.0",
-		"ts-jest": "^29.1.0",
-		"tsx": "^4.19.0",
-		"typescript": "^5.0.0"
-	},
-	"engines": {
-		"node": ">=20.0.0"
-	},
-	"keywords": [
-		"ritual",
-		"mcp",
-		"ai-coding-agent",
-		"claude-code",
-		"cursor",
-		"windsurf",
-		"kiro",
-		"gemini-cli",
-		"copilot",
-		"codex"
-	],
-	"jest": {
-		"preset": "ts-jest",
-		"testEnvironment": "node",
-		"roots": [
-			"<rootDir>/src",
-			"<rootDir>/test"
-		],
-		"testMatch": [
-			"**/?(*.)+(spec|test).ts"
-		]
-	}
+  "name": "@ritualai/cli",
+  "version": "0.8.0",
+  "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",
+  "homepage": "https://ritual.work/ritual-mcp/docs/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ritual-Mobile/ritual-enterprise.git",
+    "directory": "apps/cli"
+  },
+  "author": "Ritual",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ritual": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build:skills": "node scripts/build-skills.js",
+    "build:ts": "tsc -p tsconfig.json",
+    "build": "pnpm run build:skills && pnpm run build:ts",
+    "dev": "tsx src/index.ts",
+    "clean": "rm -rf dist skills",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "jest --passWithNoTests",
+    "prepublishOnly": "pnpm run clean && pnpm run build"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@ritual/shared-types": "workspace:^",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "ritual",
+    "mcp",
+    "ai-coding-agent",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "kiro",
+    "gemini-cli",
+    "copilot",
+    "codex"
+  ],
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/src",
+      "<rootDir>/test"
+    ],
+    "testMatch": [
+      "**/?(*.)+(spec|test).ts"
+    ]
+  }
 }

package/skills/claude-code/ritual/.ritual-bundle.json

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.7.16",
-  "builtAt": "2026-05-19T17:40:19.161Z"
+  "cliVersion": "0.8.0",
+  "builtAt": "2026-05-21T08:38:33.187Z"
 }

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

@@ -121,7 +121,7 @@ Store `workspace_id` for the rest of the flow.
 
 If you created a new workspace, persist the binding to `.ritual/config.json` so future runs in this repo skip the workspace-selection prompt. Write it yourself if you have filesystem write access; otherwise show the user the JSON and have them save it.
 
-**`.ritual/config.json` is committed to the repo — it is shared, not per-user.** Same model as `.eslintrc.json` or `tsconfig.json`: it binds this codebase to a Ritual workspace + pins team-level defaults (workspaceId, defaultTemplateId). Everyone working on this repo wants the same values. Per-user state (PATs, auth tokens) lives in `~/.config/ritual/` and never in this file.
+**`.ritual/config.json` is committed to the repo — it is shared, not per-user.** Same model as `.eslintrc.json` or `tsconfig.json`: it binds this codebase to a Ritual workspace + pins team-level defaults (`workspaceId`, `personaSlug` — set by `ritual init`'s FTUE — or the legacy `defaultTemplateId`). Everyone working on this repo wants the same values. Per-user state (PATs, auth tokens) lives in `~/.config/ritual/` and never in this file.
 
 When you write the config, also write `.ritual/.gitignore` if it doesn't already exist so any future per-user state files in this directory get ignored while `config.json` itself stays tracked:
 
@@ -446,16 +446,48 @@ Templates shape the structure of considerations, the problem statement, and the
 
 Resolution order:
 
-1. **Project-pinned default (preferred).** Check `.ritual/config.json` for a `defaultTemplateId` field. If present, the project has a pinned team template — use it without pausing.
+1. **Persona-pinned default (preferred — FTUE-set).** Check `.ritual/config.json` for a `personaSlug` field. If present, that slug **is the template id** (Engineering template families are seeded with `schema.id === <slug>` — see `apps/cli/src/lib/persona-samples.ts`). Use it directly as `template_id` without calling `mcp__ritual__list_templates` and without pausing. This is the common case: the user picked a persona during `ritual init`'s FTUE, the slug was persisted to `.ritual/config.json`, and `/ritual build` should respect that pick.
 
-   User-visible:
+   **Frame this as a persona + scope-of-work confirmation, not a template confirmation.** "Template" is an internal noun the user hasn't seen — they picked a *persona* during FTUE and what they care about now is "is the persona right + what does that mean for this feature?" Use the `PERSONA_DISPLAY` table below to look up the friendly label from the slug.
 
-   > Template
-   > Using **{templateName}**, pinned in `.ritual/config.json`.
-   > Ritual will use this to turn the candidate into implementation-ready sub-problems, recommendations, and a build brief for the coding agent.
-   > Override anytime with `template: list` or `template: {name}`.
+   User-visible (one short pause that confirms persona + lists the scope sections, NOT a tool-call prompt):
+
+   > You're set up as **{personaLabel}**.
+   >
+   > For this feature, we'll work through: scope · non-goals · requirements · acceptance criteria · dependencies · metrics · open questions.
+   >
+   > Sound right? Reply `go` to continue, or `change role` to pick a different persona.
+
+   Do **NOT** call `mcp__ritual__list_templates` in this branch. It's wasted ceremony — both for latency (round-trip + LLM context bloat) and for UX (pre-FTUE this step was a real decision; with `personaSlug` already pinned it's a confirmation prompt the user can't meaningfully act on).
+
+   **`PERSONA_DISPLAY` lookup table** (slug → label, mirrors `apps/cli/src/lib/persona-samples.ts#PERSONA_SAMPLES`). If the slug isn't here (a custom or future persona), fall back to humanizing the slug (e.g. `frontend-web` → `Frontend Web`):
+
+   | slug | label |
+   | --- | --- |
+   | backend-services | Backend Services |
+   | frontend-web | Frontend Web |
+   | data-engineering | Data Engineering |
+   | ml-engineering | ML Engineering |
+   | platform-engineering | Platform Engineering |
+   | security-engineering | Security Engineering |
+   | developer-tooling | Developer Tooling |
+   | embedded-firmware | Embedded / Firmware |
+   | game-development | Game Development |
+   | smart-contracts | Smart Contracts |
+   | desktop-apps | Desktop Apps |
+   | qa-engineering | QA Engineering |
 
-2. **Pick a recommended default + offer alternatives.** If no `.ritual/config.json` pin exists, call `mcp__ritual__list_templates`. From the response, pick the first template matching this fallback chain:
+   **If user replies `change role`** (or `template: list`, retained as a power-user alias): fall through to Branch 3 (`list_templates`). Otherwise treat any non-empty reply that isn't a recognized override command as `go`.
+
+2. **Legacy template pin.** If `personaSlug` is missing but `.ritual/config.json` has the legacy `defaultTemplateId` field (older inits before FTUE), use that as `template_id` without pausing. Same confirmation shape as Branch 1, but the role name comes from the template — call `mcp__ritual__list_templates` ONCE to resolve the display name (the legacy pin gave us an id, not a label), then show:
+
+   > You're set up with **{templateName}**.
+   >
+   > For this feature, we'll work through: scope · non-goals · requirements · acceptance criteria · dependencies · metrics · open questions.
+   >
+   > Sound right? Reply `go` to continue, or `change role` to pick a different persona.
+
+3. **No pin — pick a recommended default + offer alternatives.** Only when neither `personaSlug` nor `defaultTemplateId` is set, call `mcp__ritual__list_templates`. From the response, pick the first template matching this fallback chain:
    - Name matches `/Feature Specification.*Agentic Coding/i` — canonical default for code-aware builds
    - Name matches `/Technical Detail PRD/i`
    - Name matches `/Engineering Spec|Technical (Detail|Spec)/i`
@@ -468,13 +500,13 @@ Resolution order:
    >
    > Reply `go`, `list`, or `template: {name}`.
 
-3. **If the user types `list`:** present a numbered menu of all SYSTEM-type templates. Skip CUSTOM templates by default to avoid menu sprawl unless the user gives a specific custom id/name. Each line: `{N}. {name} — {short description}`. Wait for a number selection.
+4. **If the user types `list`** (in any branch, override path): call `mcp__ritual__list_templates` if you haven't yet, then present a numbered menu of all SYSTEM-type templates. Skip CUSTOM templates by default to avoid menu sprawl unless the user gives a specific custom id/name. Each line: `{N}. {name} — {short description}`. Wait for a number selection.
 
-4. **If the user types `template: {name}` or picks one by name:** find the case-insensitive partial match in the template list. If ambiguous, show only the matching options and ask which one. If no match, show the SYSTEM template menu.
+5. **If the user types `template: {name}` or picks one by name:** call `mcp__ritual__list_templates` if you haven't yet, then find the case-insensitive partial match. If ambiguous, show only the matching options and ask which one. If no match, show the SYSTEM template menu.
 
-5. **Remember `template_id`.** It passes through every subsequent phase — `generate_considerations`, `refine_considerations`, `generate_problem_statement`, `refine_problem_statement`, and ultimately `create_exploration`. The API uses it to load template-specific anti-patterns + focus keywords into the LLM prompt, so it materially shapes output quality.
+6. **Remember `template_id`.** It passes through every subsequent phase — `generate_considerations`, `refine_considerations`, `generate_problem_statement`, `refine_problem_statement`, and ultimately `create_exploration`. The API uses it to load template-specific anti-patterns + focus keywords into the LLM prompt, so it materially shapes output quality.
 
-6. **Track role silently.** Infer `role` from the selected template and carry it forward for:
+7. **Track role silently.** Infer `role` from the selected template and carry it forward for:
    - recommendation tone
    - sibling exploration cap
    - Step 8 run-mode default
@@ -501,11 +533,15 @@ Resolution order:
 
    If the user corrects the role (e.g. "actually I'm building a PRD"), update internal role tracking. Do **not** re-pick the template unless the user explicitly asks to change it.
 
-7. **Suggest persistence only when useful.** If you picked a default from the template list and the user accepted with `go` rather than choosing a different one, suggest:
+8. **Suggest persistence only when useful.** If you got here via Branch 3 (no pinned default, you picked one from the list), AND the user accepted with `go` rather than picking a different one, suggest:
 
    > Want me to pin this template for future `/ritual build` runs in this repo? I can add `"defaultTemplateId": "{id}"` to `.ritual/config.json`.
 
-   If the user says yes, write the field while preserving existing keys. This is a TEAM pin — `.ritual/config.json` is committed to the repo per Step 1, so the whole team picks up the same default.
+   If the user says yes, write the field while preserving existing keys. Use the `defaultTemplateId` field (not `personaSlug`) when the user picked a template directly — `personaSlug` is reserved for the FTUE persona pick (where the slug semantically maps to one of the 12 Engineering personas). The SKILL reads `personaSlug` first, then `defaultTemplateId`, so either field works as a pin; the distinction is provenance.
+
+   This is a TEAM pin — `.ritual/config.json` is committed to the repo per Step 1, so the whole team picks up the same default.
+
+   **Do NOT suggest persistence in Branches 1 or 2** (persona-pinned or legacy-pinned). The pin already exists; offering to write it would be confusing.
 
 Proceed to Step 3 once a template is selected. No extra confirmation is required after a pinned template or an accepted default.
 
@@ -1061,6 +1097,7 @@ Call `mcp__ritual__create_exploration` with:
 - `workspace_id`
 - `name`
 - `problem_statement` (the scope from Step 5)
+- `template_id` — **REQUIRED.** Pass the same `template_id` used in Steps 4 and 5 (the one established in Step 2 from `personaSlug` / `defaultTemplateId` / picker). The exploration must carry this forward so downstream `start_agentic_run`, `get_recommendations`, and `generate_build_brief` load the right template-specific anti-patterns + focus keywords into the LLM prompts. Skipping `template_id` here silently falls back to the API default, which produces generic recs that don't match the persona's scope contract — the symptom is brief sections that don't align with what the user was promised at Step 2 ("For this feature, we'll work through: scope · non-goals · requirements …"). Always include it; the MCP tool accepts it (see `apps/mcp/src/mcp/tools/create-exploration.tool.ts:78`).
 - `agentic: false` — **do NOT** pass `agentic: true`. We want explicit per-step control so the user gets to pick discovery questions in Step 7. Auto-agentic skips that.
 
 Store `exploration_id`. Move the progress header from Scope to Discovery:

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

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.7.16",
-  "builtAt": "2026-05-19T17:40:19.161Z"
+  "cliVersion": "0.8.0",
+  "builtAt": "2026-05-21T08:38:33.187Z"
 }