@productbrain/cli 0.1.0-beta.34 → 0.1.0-beta.36

package/dist/lib/onboarding-phases.js

@@ -0,0 +1,120 @@
+/**
+ * Onboarding conversation phases — the 5-phase arc for first-time setup.
+ * WP-304: Each phase has a directive (what the LLM should do) and exit criteria (what the CLI checks).
+ */
+export const ONBOARDING_PHASES = [
+    {
+        id: 'greet',
+        directive: `Your job: Say hello and ask what they're building. One sentence. No fluff.
+Example: "Hey! What are you building?"
+Do NOT ask multiple questions. Do NOT explain Product Brain yet.`,
+        exitCriteria: [
+            {
+                name: 'greeting_sent',
+                check: (s) => s.phaseExchanges['greet'] !== undefined && (s.phaseExchanges['greet'] ?? 0) >= 0,
+                required: true,
+            },
+        ],
+        maxExchanges: 1,
+    },
+    {
+        id: 'explore',
+        directive: `Your job: Learn what they're building. Get specific.
+If they gave a vague answer ("something big", "a tool", "an app"), pick one concrete detail and dig in.
+Ask who uses it, what it actually does, or how it works today.
+Good questions: "Who's using it?" / "What does it replace?" / "How does that work today?"
+Bad questions: "What domain are you operating in?" / "Can you elaborate on that?"
+Do NOT ask why they're trying Product Brain yet.
+One question only.`,
+        exitCriteria: [
+            {
+                name: 'user_mentioned_product',
+                check: (s) => s.signals.mentionedProduct,
+                required: true,
+            },
+            {
+                name: 'has_substantive_answer',
+                check: (s) => s.signals.hasSubstantiveAnswer,
+                required: true,
+            },
+        ],
+        maxExchanges: 3,
+    },
+    {
+        id: 'deepen',
+        directive: `Your job: Understand what's hard about what they're building.
+Pick ONE specific thing they mentioned and ask what breaks or why it's hard. Be direct and short.
+Good: "What breaks when the agent doesn't have that context?" / "Where does the rework hit hardest?"
+Bad: "What makes it hard to ensure X?" / "Can you tell me more about the challenges?"
+Do NOT ask why they're trying Product Brain yet.
+One question only.`,
+        exitCriteria: [
+            {
+                name: 'user_mentioned_challenge',
+                check: (s) => s.signals.mentionedChallenge,
+                required: false,
+            },
+            {
+                name: 'min_2_substantive_messages',
+                check: (s) => s.signals.substantiveMessageCount >= 2,
+                required: true,
+            },
+        ],
+        maxExchanges: 2,
+    },
+    {
+        id: 'why_pb',
+        directive: `Your job: Ask what made them try Product Brain. Be direct.
+Examples: "What made you try Product Brain?" or "What problem are you hoping Product Brain solves?"
+Do NOT summarize or synthesize yet.
+One question only.`,
+        exitCriteria: [
+            {
+                name: 'user_answered_why_pb',
+                check: (s) => s.signals.mentionedWhyPB,
+                required: false,
+            },
+            {
+                name: 'min_total_words_25',
+                check: (s) => s.totalUserWords >= 25,
+                required: true,
+            },
+            {
+                name: 'min_3_substantive_messages',
+                check: (s) => s.signals.substantiveMessageCount >= 3,
+                required: true,
+            },
+        ],
+        maxExchanges: 2,
+    },
+    {
+        id: 'bridge',
+        directive: `Your job: Bridge the conversation to Product Brain's value. Speak as Product Brain (first person "I").
+Keep it SHORT — 2-3 sentences max. Do NOT list bullet items. The CLI will handle showing examples.
+
+Structure:
+1. One sentence connecting their problem to what you (PB) do. Use first person.
+2. One sentence showing you understood something specific they said.
+
+Good example: "I can remember all of that across your AI sessions — so next time you open Claude or Cursor, it already knows about the decision rot problem and your cashflow automation. No more re-explaining."
+Bad example: "Product Brain can help — it remembers context. Here's what I'd save: * item 1 * item 2 * item 3"
+
+Do NOT list items. Do NOT use bullet points or asterisks. The CLI shows examples separately.
+This is a STATEMENT. Do NOT ask a question. Do NOT end with a question mark.`,
+        exitCriteria: [
+            {
+                name: 'bridge_delivered',
+                check: (s) => (s.phaseExchanges['bridge'] ?? 0) >= 1,
+                required: true,
+            },
+        ],
+        maxExchanges: 1,
+    },
+];
+/** User wants to skip — detected by regex on user input. */
+const SKIP_PATTERNS = [/\b(?:skip|done|that'?s it|wrap up|let'?s go|finish|end)\b/i];
+/** Check if user wants to skip the conversation. */
+export function userWantsToSkip(text) {
+    return SKIP_PATTERNS.some((p) => p.test(text));
+}
+//# sourceMappingURL=onboarding-phases.js.map

package/dist/lib/onboarding-phases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-phases.js","sourceRoot":"","sources":["../../src/lib/onboarding-phases.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAwB;IACpD;QACE,EAAE,EAAE,OAAO;QACX,SAAS,EAAE;;iEAEkD;QAC7D,YAAY,EAAE;YACZ;gBACE,IAAI,EAAE,eAAe;gBACrB,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;gBAC9F,QAAQ,EAAE,IAAI;aACf;SACF;QACD,YAAY,EAAE,CAAC;KAChB;IACD;QACE,EAAE,EAAE,SAAS;QACb,SAAS,EAAE;;;;;;mBAMI;QACf,YAAY,EAAE;YACZ;gBACE,IAAI,EAAE,wBAAwB;gBAC9B,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB;gBACxC,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,IAAI,EAAE,wBAAwB;gBAC9B,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,oBAAoB;gBAC5C,QAAQ,EAAE,IAAI;aACf;SACF;QACD,YAAY,EAAE,CAAC;KAChB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,SAAS,EAAE;;;;;mBAKI;QACf,YAAY,EAAE;YACZ;gBACE,IAAI,EAAE,0BAA0B;gBAChC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB;gBAC1C,QAAQ,EAAE,KAAK;aAChB;YACD;gBACE,IAAI,EAAE,4BAA4B;gBAClC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,uBAAuB,IAAI,CAAC;gBACpD,QAAQ,EAAE,IAAI;aACf;SACF;QACD,YAAY,EAAE,CAAC;KAChB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,SAAS,EAAE;;;mBAGI;QACf,YAAY,EAAE;YACZ;gBACE,IAAI,EAAE,sBAAsB;gBAC5B,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc;gBACtC,QAAQ,EAAE,KAAK;aAChB;YACD;gBACE,IAAI,EAAE,oBAAoB;gBAC1B,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,IAAI,EAAE;gBACpC,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,IAAI,EAAE,4BAA4B;gBAClC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,uBAAuB,IAAI,CAAC;gBACpD,QAAQ,EAAE,IAAI;aACf;SACF;QACD,YAAY,EAAE,CAAC;KAChB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,SAAS,EAAE;;;;;;;;;;;6EAW8D;QACzE,YAAY,EAAE;YACZ;gBACE,IAAI,EAAE,kBAAkB;gBACxB,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;gBACpD,QAAQ,EAAE,IAAI;aACf;SACF;QACD,YAAY,EAAE,CAAC;KAChB;CACF,CAAC;AAEF,4DAA4D;AAC5D,MAAM,aAAa,GAAG,CAAC,4DAA4D,CAAC,CAAC;AAErF,oDAAoD;AACpD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/lib/onboarding.d.ts

@@ -1,19 +1,17 @@
 /**
- * Onboarding conversation — LLM-powered natural conversation for new workspaces.
- * WP-304 Slice 0: Single-turn proof of concept.
- * WP-304 Slice 1: Multi-turn conversation + extraction + auto-capture.
+ * Onboarding conversation — LLM-powered phase-gated conversation for new workspaces.
+ * WP-304: Deterministic Shell (CLI phases), Stochastic Core (LLM content).
  *
  * Uses @clack/prompts (WP-303 S1) and the MCP gateway to call the
  * Convex onboardingChat action for conversation and extraction,
  * then chain.createEntry for batch-capture.
  */
 /**
- * Run the onboarding conversation: multi-turn chat, extraction, and auto-capture.
+ * Run the onboarding conversation: phase-gated chat, extraction, and auto-capture.
  */
 export declare function runOnboardingConversation(workspaceName: string): Promise<void>;
 /**
  * Deterministic fallback when LLM is unavailable.
- * Asks 3 hardcoded questions and maps answers to the same capture pipeline.
  */
 export declare function runFallbackOnboarding(workspaceName: string): Promise<void>;
 //# sourceMappingURL=onboarding.d.ts.map

package/dist/lib/onboarding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/lib/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgLH;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyLpF;AAmCD;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DhF"}
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/lib/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+KH;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4TpF;AAmCD;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmEhF"}

package/dist/lib/onboarding.js

@@ -1,39 +1,36 @@
 /**
- * Onboarding conversation — LLM-powered natural conversation for new workspaces.
- * WP-304 Slice 0: Single-turn proof of concept.
- * WP-304 Slice 1: Multi-turn conversation + extraction + auto-capture.
+ * Onboarding conversation — LLM-powered phase-gated conversation for new workspaces.
+ * WP-304: Deterministic Shell (CLI phases), Stochastic Core (LLM content).
  *
  * Uses @clack/prompts (WP-303 S1) and the MCP gateway to call the
  * Convex onboardingChat action for conversation and extraction,
  * then chain.createEntry for batch-capture.
  */
 import { mcpCall, mcpCallWithSession } from './client.js';
-import { ask, confirm } from './prompts.js';
-import { bold, dim, green, icons } from './style.js';
+import { ask, confirm, select } from './prompts.js';
+import { bold, cyan, dim, green, icons } from './style.js';
 import { trackEvent } from './telemetry.js';
-/** Max conversation exchanges (including the initial greeting). */
-const MAX_TURNS = 5;
-/** Signals that the LLM is ready to synthesize (present in its response). */
-const SYNTHESIS_SIGNALS = [
-    'good picture',
-    'organize what',
-    'let me organize',
-    'enough to get started',
-    'have a good sense',
-    'got a clear picture',
-    'great start',
-    'let me pull',
-    'let me put',
-];
+import { detectSignals, mergeSignals } from './conversation-signals.js';
+import { evaluatePhase, buildPhaseDirective, sanitizeResponse, enforceBridgeIsStatement, isTooSimilar } from './conversation-engine.js';
+import { ONBOARDING_PHASES, userWantsToSkip } from './onboarding-phases.js';
+/** Hard cap on total exchanges across all phases. */
+const MAX_TOTAL_EXCHANGES = 10;
 // ── Extraction → Entries Mapping ────────────────────────────────────────────
 // SYNC: Must match packages/mcp-server/src/tools/start-interview.ts:extractionToBatchEntries
 // Duplicated due to monorepo import boundary (BR-165). TEN tracked for shared-package extraction.
 function truncate(str, maxLen) {
-    return str.length <= maxLen ? str : str.slice(0, maxLen);
+    if (str.length <= maxLen)
+        return str;
+    const truncated = str.slice(0, maxLen);
+    const lastSpace = truncated.lastIndexOf(' ');
+    return lastSpace > maxLen * 0.6 ? truncated.slice(0, lastSpace) : truncated;
 }
 function firstNWords(str, n) {
     return str.split(/\s+/).slice(0, n).join(' ');
 }
+function countWords(text) {
+    return text.trim().split(/\s+/).filter(Boolean).length;
+}
 function extractionToEntries(extracted) {
     const entries = [];
     if (extracted.vision?.trim()) {
@@ -80,7 +77,7 @@ function extractionToEntries(extracted) {
         for (const decision of extracted.keyDecisions) {
             entries.push({
                 collection: 'decisions',
-                name: truncate(decision, 80),
+                name: truncate(decision, 120),
                 description: decision,
             });
         }
@@ -89,7 +86,7 @@ function extractionToEntries(extracted) {
         for (const tension of extracted.tensions) {
             entries.push({
                 collection: 'tensions',
-                name: truncate(tension, 80),
+                name: truncate(tension, 120),
                 description: tension,
             });
         }
@@ -97,119 +94,197 @@ function extractionToEntries(extracted) {
     return entries;
 }
 // ── Display helpers ─────────────────────────────────────────────────────────
-function displayExtraction(extracted) {
-    process.stdout.write(`\n  Here's what I picked up:\n\n`);
-    if (extracted.vision) {
-        process.stdout.write(`  ${green('\u2726')} Your product vision: ${extracted.vision}\n`);
-    }
-    if (extracted.audience) {
-        process.stdout.write(`  ${green('\u2726')} Your audience: ${extracted.audience}\n`);
-    }
-    if (extracted.techStack?.length) {
-        process.stdout.write(`  ${green('\u2726')} Tech stack: ${extracted.techStack.join(', ')}\n`);
-    }
-    if (extracted.keyTerms?.length) {
-        process.stdout.write(`  ${green('\u2726')} Key terms: ${extracted.keyTerms.join(', ')}\n`);
-    }
-    if (extracted.keyDecisions?.length) {
-        process.stdout.write(`  ${green('\u2726')} Key decisions: ${extracted.keyDecisions.join('; ')}\n`);
-    }
-    if (extracted.tensions?.length) {
-        process.stdout.write(`  ${green('\u2726')} Challenges: ${extracted.tensions.join('; ')}\n`);
+/** Collection type labels — human-friendly names for collections. */
+const COLLECTION_LABELS = {
+    strategy: 'Strategy',
+    audiences: 'Audience',
+    architecture: 'Architecture',
+    glossary: 'Term',
+    decisions: 'Decision',
+    tensions: 'Tension',
+};
+/**
+ * Display one entry example with schema structure.
+ * Shows collection type, name, and description in a clean format.
+ */
+function displayEntryExample(entry) {
+    const typeLabel = COLLECTION_LABELS[entry.collection] ?? entry.collection;
+    process.stdout.write(`    ${cyan(typeLabel)}\n`);
+    process.stdout.write(`    ${bold(entry.name)}\n`);
+    if (entry.description !== entry.name) {
+        process.stdout.write(`    ${dim(entry.description)}\n`);
     }
     process.stdout.write('\n');
 }
-function hasSynthesisSignal(text) {
-    const lower = text.toLowerCase();
-    return SYNTHESIS_SIGNALS.some((signal) => lower.includes(signal));
-}
 // ── Main conversation ───────────────────────────────────────────────────────
 /**
- * Run the onboarding conversation: multi-turn chat, extraction, and auto-capture.
+ * Run the onboarding conversation: phase-gated chat, extraction, and auto-capture.
  */
 export async function runOnboardingConversation(workspaceName) {
     trackEvent('setup_started', { mode: 'llm' });
-    const messages = [];
-    // Step 1: Get the LLM's opening greeting
+    // Initialize conversation state
+    const state = {
+        messages: [],
+        userMessageCount: 0,
+        totalUserWords: 0,
+        phaseExchanges: {},
+        completedPhases: new Set(),
+        currentPhaseId: ONBOARDING_PHASES[0].id,
+        signals: detectSignals([]),
+        refusalStreak: 0,
+    };
+    let currentPhaseIndex = 0;
+    let totalExchanges = 0;
+    let emptyAttempts = 0;
+    const recentAssistantMessages = [];
+    const accumulatedFragments = [];
+    // Step 1: Get the LLM's opening greeting (greet phase)
+    const greetPhase = ONBOARDING_PHASES[0];
+    const greetDirective = buildPhaseDirective(greetPhase, 0, ONBOARDING_PHASES.length);
     let greeting;
     try {
         const result = await mcpCall('onboarding.chat', {
             messages: [],
             workspaceName,
+            phaseDirective: greetDirective,
+            turnNumber: 1,
+            totalUserWords: 0,
+            refusalStreak: 0,
         });
         if (!result?.content) {
-            // LLM unavailable — fall back to deterministic conversation
             await runFallbackOnboarding(workspaceName);
             return;
         }
-        greeting = result.content;
+        greeting = sanitizeResponse(result.content);
     }
     catch {
-        // LLM unavailable — fall back to deterministic conversation
         await runFallbackOnboarding(workspaceName);
         return;
     }
-    // Display greeting and start conversation loop
     process.stdout.write(`\n  ${greeting}\n\n`);
-    messages.push({ role: 'assistant', content: greeting });
-    // Step 2: Multi-turn conversation (max MAX_TURNS exchanges total)
-    let turnCount = 1; // greeting counts as turn 1
-    let readyToExtract = false;
-    while (turnCount < MAX_TURNS && !readyToExtract) {
+    state.messages.push({ role: 'assistant', content: greeting });
+    recentAssistantMessages.push(greeting);
+    // Advance past greet phase
+    state.completedPhases.add('greet');
+    state.phaseExchanges['greet'] = 1;
+    currentPhaseIndex = 1;
+    state.currentPhaseId = ONBOARDING_PHASES[1].id;
+    // Step 2: Phase-gated conversation loop
+    while (currentPhaseIndex < ONBOARDING_PHASES.length && totalExchanges < MAX_TOTAL_EXCHANGES) {
+        const phase = ONBOARDING_PHASES[currentPhaseIndex];
         // Get user input
         let userInput;
         try {
             userInput = await ask({
                 message: 'You',
-                placeholder: turnCount === 1 ? 'Tell me about your product...' : 'Continue...',
+                placeholder: totalExchanges === 0 ? 'Tell me about your product...' : '',
             });
         }
         catch {
-            // User cancelled
-            process.stdout.write(`\n  ${dim('No worries! Tell me about your product anytime with')} ${bold('pb capture')}\n\n`);
+            process.stdout.write(`\n  ${dim('No worries! Run')} ${bold('pb capture')} ${dim('anytime to add knowledge.')}\n\n`);
             return;
         }
         if (!userInput.trim()) {
-            process.stdout.write(`\n  ${dim('No worries! Tell me about your product anytime with')} ${bold('pb capture')}\n\n`);
-            return;
+            emptyAttempts++;
+            if (emptyAttempts >= 2) {
+                process.stdout.write(`\n  ${dim('No problem — explore with')} ${bold('pb orient -b')} ${dim('or capture with')} ${bold('pb capture')}\n\n`);
+                return;
+            }
+            process.stdout.write(`  ${dim('Just hit Enter again to skip, or type anything to continue.')}\n\n`);
+            continue;
+        }
+        emptyAttempts = 0;
+        // Check if user wants to skip
+        if (userWantsToSkip(userInput) && state.totalUserWords > 10) {
+            // Skip to extraction with what we have
+            break;
+        }
+        // Update state
+        state.messages.push({ role: 'user', content: userInput });
+        state.userMessageCount++;
+        state.totalUserWords += countWords(userInput);
+        state.phaseExchanges[phase.id] = (state.phaseExchanges[phase.id] ?? 0) + 1;
+        totalExchanges++;
+        // Detect refusals (very short non-answers)
+        const wordCount = countWords(userInput);
+        if (wordCount <= 2) {
+            state.refusalStreak++;
+        }
+        else {
+            state.refusalStreak = 0;
         }
-        messages.push({ role: 'user', content: userInput });
-        turnCount++;
-        // Get LLM response
+        // Update heuristic signals
+        state.signals = detectSignals(state.messages);
+        // Get LLM response with phase directive (bridge gets accumulated fragments)
+        const phaseDirective = buildPhaseDirective(phase, currentPhaseIndex, ONBOARDING_PHASES.length, accumulatedFragments);
         try {
             const result = await mcpCall('onboarding.chat', {
-                messages,
+                messages: state.messages,
                 workspaceName,
+                phaseDirective,
+                turnNumber: totalExchanges + 1,
+                totalUserWords: state.totalUserWords,
+                refusalStreak: state.refusalStreak,
             });
             if (result?.content) {
-                process.stdout.write(`\n  ${result.content}\n\n`);
-                messages.push({ role: 'assistant', content: result.content });
-                // Check if LLM signals readiness to synthesize
-                if (hasSynthesisSignal(result.content)) {
-                    readyToExtract = true;
+                // Merge LLM-reported signals with heuristic signals
+                if (result.signals) {
+                    state.signals = mergeSignals(state.signals, result.signals);
+                    // Accumulate quotable fragments for bridge phase
+                    if (result.signals.quotableFragments?.length) {
+                        for (const frag of result.signals.quotableFragments) {
+                            if (frag.trim() && !accumulatedFragments.includes(frag)) {
+                                accumulatedFragments.push(frag);
+                            }
+                        }
+                    }
                 }
-            }
-            else {
-                // LLM returned nothing — extract what we have
-                readyToExtract = true;
+                // Post-process response
+                let displayMessage = sanitizeResponse(result.content);
+                displayMessage = enforceBridgeIsStatement(displayMessage, phase.id);
+                // Detect repetition — if too similar, add a nudge for next call
+                if (isTooSimilar(displayMessage, recentAssistantMessages)) {
+                    state.refusalStreak++; // Will cause prompt to try different angle
+                }
+                process.stdout.write(`\n  ${displayMessage}\n\n`);
+                state.messages.push({ role: 'assistant', content: displayMessage });
+                recentAssistantMessages.push(displayMessage);
             }
         }
         catch {
-            // LLM call failed — extract what we have
-            readyToExtract = true;
+            // LLM call failed — try to continue with what we have
+            break;
         }
+        // CLI evaluates phase — not the LLM
+        const advance = evaluatePhase(ONBOARDING_PHASES, state);
+        if (advance.complete) {
+            state.completedPhases.add(phase.id);
+            if (advance.readyToExtract) {
+                break; // All phases done — proceed to extraction
+            }
+            if (advance.nextPhase) {
+                currentPhaseIndex++;
+                state.currentPhaseId = advance.nextPhase.id;
+            }
+        }
+        // else: stay in current phase, loop again
+    }
+    // Hard floor: barely any content — offer manual capture
+    if (state.totalUserWords < 10 && state.userMessageCount > 0) {
+        process.stdout.write(`\n  ${dim('No problem — you can add knowledge at your own pace with')} ${bold('pb capture')}\n\n`);
+        trackEvent('setup_completed', { capturedCount: 0, reason: 'insufficient_content' });
+        return;
     }
-    trackEvent('first_capture_prompted', { mode: 'llm', turnCount });
+    trackEvent('first_capture_prompted', { mode: 'llm', exchanges: totalExchanges });
     // Step 3: Extract structured data from conversation
-    if (messages.filter((m) => m.role === 'user').length === 0) {
-        // No user messages — nothing to extract
-        process.stdout.write(`\n  ${dim('No worries! Tell me about your product anytime with')} ${bold('pb capture')}\n\n`);
+    if (state.messages.filter((m) => m.role === 'user').length === 0) {
+        process.stdout.write(`\n  ${dim('No worries! Run')} ${bold('pb capture')} ${dim('anytime to add knowledge.')}\n\n`);
         return;
     }
     let extraction;
     try {
         const result = await mcpCall('onboarding.chat', {
-            messages,
+            messages: state.messages,
             workspaceName,
             mode: 'extract',
         });
@@ -223,29 +298,60 @@ export async function runOnboardingConversation(workspaceName) {
         process.stdout.write(`\n  ${dim("Couldn't organize your answers just yet. Try")} ${bold('pb capture')} ${dim('to add knowledge manually.')}\n\n`);
         return;
     }
-    // Step 4: Display extracted items and ask for approval
-    displayExtraction(extraction);
-    let approved;
-    try {
-        approved = await confirm({
-            message: 'Ready to save these to your product brain?',
-            initialValue: true,
-        });
-    }
-    catch {
-        process.stdout.write(`\n  ${dim('No problem. Your answers are safe — run')} ${bold('pb capture')} ${dim('anytime.')}\n\n`);
+    // Step 4: Filter and cap entries
+    const allEntries = extractionToEntries(extraction);
+    // Filter out junk: single-word names, very short descriptions
+    const entriesToCapture = allEntries
+        .filter((e) => e.name.trim().split(/\s+/).length >= 2 || e.collection === 'glossary')
+        .slice(0, 5);
+    if (entriesToCapture.length === 0) {
+        process.stdout.write(`\n  ${dim('Nothing to save yet. Try')} ${bold('pb capture')} ${dim('to add knowledge manually.')}\n\n`);
         return;
     }
-    if (!approved) {
-        process.stdout.write(`\n  ${dim('No problem. Your answers are safe — run')} ${bold('pb capture')} ${dim('anytime.')}\n\n`);
-        return;
+    // Step 5: Show ONE example with schema, offer to browse more
+    const itemCount = entriesToCapture.length;
+    process.stdout.write(`\n  From this conversation, I'd remember ${bold(String(itemCount))} item${itemCount === 1 ? '' : 's'}.\n`);
+    process.stdout.write(`  Here's an example:\n\n`);
+    displayEntryExample(entriesToCapture[0]);
+    let exampleIndex = 1; // Already showed index 0
+    let shouldSave = false;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const hasMoreExamples = exampleIndex < entriesToCapture.length;
+        const options = [
+            { value: 'save', label: 'Save all to my product brain', hint: `${itemCount} item${itemCount === 1 ? '' : 's'}` },
+        ];
+        if (hasMoreExamples) {
+            options.push({ value: 'another', label: 'Show another example' });
+        }
+        options.push({ value: 'skip', label: 'Not right now' });
+        let choice;
+        try {
+            choice = await select({
+                message: '',
+                options,
+            });
+        }
+        catch {
+            process.stdout.write(`\n  ${dim('No problem — run')} ${bold('pb capture')} ${dim('anytime.')}\n\n`);
+            return;
+        }
+        if (choice === 'skip') {
+            process.stdout.write(`\n  ${dim('No problem — explore with')} ${bold('pb orient -b')} ${dim('or add more with')} ${bold('pb capture')}\n\n`);
+            return;
+        }
+        if (choice === 'save') {
+            shouldSave = true;
+            break;
+        }
+        if (choice === 'another') {
+            displayEntryExample(entriesToCapture[exampleIndex]);
+            exampleIndex++;
+        }
     }
-    // Step 5: Batch-capture entries via chain.createEntry
-    const entriesToCapture = extractionToEntries(extraction);
-    if (entriesToCapture.length === 0) {
-        process.stdout.write(`\n  ${dim('Nothing to save. Try')} ${bold('pb capture')} ${dim('to add knowledge manually.')}\n\n`);
+    if (!shouldSave)
         return;
-    }
+    // Step 6: Batch-capture entries
     let capturedCount = 0;
     const errors = [];
     for (const entry of entriesToCapture) {
@@ -263,22 +369,16 @@ export async function runOnboardingConversation(workspaceName) {
             errors.push(`${entry.name}: ${msg}`);
         }
     }
-    // Step 6: Report results
+    // Step 7: Report results
     if (capturedCount > 0) {
         process.stdout.write(`\n  ${green(icons.pass)} Saved ${capturedCount} item${capturedCount === 1 ? '' : 's'} to your product brain.\n`);
         trackEvent('capture_completed', { mode: 'llm', count: capturedCount });
     }
     if (errors.length > 0) {
-        process.stdout.write(`\n  ${dim(`${errors.length} item${errors.length === 1 ? '' : 's'} couldn't be saved:`)}\n`);
-        for (const err of errors.slice(0, 3)) {
-            process.stdout.write(`    ${dim(err)}\n`);
-        }
+        process.stdout.write(`\n  ${dim(`${errors.length} couldn't be saved.`)}\n`);
     }
-    // Step 7: Auto-retrieval proof (BR-141, PRI-58, FEAT-149)
+    // Step 8: Retrieval proof + closing
     await showRetrievalProof();
-    // Step 8: Closing message with community link
-    process.stdout.write(`  ${dim('Join the community:')} ${bold('community.productbrain.io')}\n`);
-    process.stdout.write(`  ${dim('Your product brain gets smarter every time you capture.')}\n\n`);
     process.stdout.write(`  ${dim('Explore with')} ${bold('pb orient -b')} ${dim('or add more with')} ${bold('pb capture')}\n\n`);
     trackEvent('setup_completed', { capturedCount });
 }
@@ -288,7 +388,7 @@ async function showRetrievalProof() {
         const orient = await mcpCall('orient', { brief: true });
         const items = orient?.sections?.flatMap((s) => s.items ?? []).filter((i) => i.name) ?? [];
         if (items.length > 0) {
-            process.stdout.write(`\n  ${bold('Here\'s how your product brain will use this:')}\n\n`);
+            process.stdout.write(`\n  ${bold("Here's how your product brain will use this:")}\n\n`);
             for (const item of items.slice(0, 5)) {
                 process.stdout.write(`    ${dim(icons.dot)} ${item.name}\n`);
             }
@@ -299,18 +399,17 @@ async function showRetrievalProof() {
         }
     }
     catch {
-        // Retrieval proof is best-effort — never block onboarding
+        // Retrieval proof is best-effort
     }
 }
 // ── Deterministic fallback ────────────────────────────────────────────────
 const FALLBACK_QUESTIONS = [
     { message: 'What are you building?', placeholder: 'A tool for...' },
     { message: 'Who is it for?', placeholder: 'Developers, designers, teams...' },
-    { message: 'What\'s the biggest challenge right now?', placeholder: 'Scaling, onboarding, pricing...' },
+    { message: "What's the biggest challenge right now?", placeholder: 'Scaling, onboarding, pricing...' },
 ];
 /**
  * Deterministic fallback when LLM is unavailable.
- * Asks 3 hardcoded questions and maps answers to the same capture pipeline.
  */
 export async function runFallbackOnboarding(workspaceName) {
     trackEvent('setup_started', { mode: 'fallback' });
@@ -331,13 +430,22 @@ export async function runFallbackOnboarding(workspaceName) {
         return;
     }
     trackEvent('first_capture_prompted', { mode: 'fallback' });
-    // Build extraction from answers
     const extraction = {
         vision: answers[0],
         audience: answers[1] || null,
         tensions: answers[2] ? [answers[2]] : null,
     };
-    displayExtraction(extraction);
+    // Show extraction
+    process.stdout.write('\n');
+    if (extraction.vision)
+        process.stdout.write(`  ${green('\u2726')} ${extraction.vision}\n`);
+    if (extraction.audience)
+        process.stdout.write(`  ${green('\u2726')} ${extraction.audience}\n`);
+    if (extraction.tensions?.length) {
+        for (const t of extraction.tensions)
+            process.stdout.write(`  ${green('\u2726')} ${t}\n`);
+    }
+    process.stdout.write('\n');
     let approved;
     try {
         approved = await confirm({ message: 'Ready to save these to your product brain?', initialValue: true });