@getrift/rift 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/src/cli/commands/onboard.js

@@ -24,7 +24,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { CliError, createHttpClient, readToken, resolveBaseUrl, } from "../http-client.js";
 import { issueToken } from "../token.js";
 import { loadConfig } from "../../config/loader.js";
@@ -35,13 +35,30 @@ import { validateVoyageKey } from "../../onboarding/voyage-validate.js";
 import { writeEnvFile } from "../../onboarding/env-file.js";
 import { kickstartDaemon, waitForHealth, } from "../../onboarding/daemon-control.js";
 import { runAutoCapture, resolveCodexCaptureDeps, } from "../../capture/auto-capture.js";
+import { appendAutoCaptureRunRecord, buildAutoCaptureRunRecord, } from "../../capture/observability.js";
+import { DEFAULT_AUTO_CAPTURE_SOURCES } from "../../capture/sources.js";
 import { CodexCliTriageProvider } from "../../capture/codex-cli-triage-provider.js";
 import { discoverClaudeCodeSessions } from "../../ingestion/parsers/claude-code-jsonl.js";
 import { discoverCodexSessions } from "../../ingestion/parsers/codex-jsonl.js";
+import { sniffInboxSource } from "../../ingestion/inbox-core/source-sniffer.js";
 import { writeHookConfig } from "../hooks-writers/index.js";
 import { HooksParseFailedError } from "../hooks-writers/index.js";
 import { pollJob } from "../job-poller.js";
 import { isJobFailure } from "../output.js";
+import * as ui from "../ui.js";
+import { getBuildInfo } from "../../server/build-info.js";
+import { postFeedback } from "../feedback/feedback-relay.js";
+import { parseInvite } from "../feedback/invite.js";
+import { macRelaySecretStore, } from "../feedback/relay-secret-store.js";
+import { LockedKeychainError } from "../../auth/keychain.js";
+/**
+ * Resolve a `--no-<flag>` to a single boolean ("yes, skip this thing").
+ * Commander populates the affirmative key with `false`; programmatic
+ * callers may pass the `no*` key with `true`. Either form wins.
+ */
+export function isOff(opts, affirmative, negative) {
+    return opts[affirmative] === false || opts[negative] === true;
+}
 const SUPPORTED_INGEST_EXTENSIONS = new Set([".json", ".zip"]);
 const DEFAULT_DATA_DIR = path.join(os.homedir(), "Library", "Application Support", "Rift", "data");
 // Inline import is intentionally narrow until Slice 3 lands the real
@@ -52,16 +69,31 @@ export function makeOnboardCommand() {
     return new Command("onboard")
         .description("First-run wizard: validate Voyage key, capture, import, recall test")
         .option("--voyage-key <key>", "Voyage API key (skips paste prompt)")
+        .option("--no-voyage-key", "Finish without a Voyage key — keyword-only (lexical) search; add a key later")
         .option("--voyage-label <label>", "Operator-supplied display label for the Voyage project")
+        .option("--invite <code>", "Accept a feedback invite from Clem (or omit it to paste when asked)")
         .option("--enable-feedback-relay <url>", "Opt into the Rift feedback relay non-interactively (URL required)")
+        .addOption(
+    // Hidden: back-compat operator flag. The secret never appears in
+    // user-facing help; friends use --invite (or the interactive paste).
+    new Option("--relay-secret <secret>", "Back-compat HMAC secret paired with --enable-feedback-relay (stored in the Keychain)").hideHelp())
+        .addOption(
+    // Hidden: dev/operator escape hatch for unsigned local receivers.
+    new Option("--allow-unsigned-feedback-relay", "Dev-only: allow --enable-feedback-relay without a secret (receiver rejects in prod)")
+        .hideHelp()
+        .default(false))
         .option("--no-feedback-relay", "Decline the feedback relay (local-only)")
+        .option("--email <address>", "Opt into beta updates + feedback non-interactively (skips the prompt)")
         .option("--import-export <path>", "Import an export inline (.json or .zip)")
         .option("--no-import-export", "Skip the import-now prompt")
         .option("--reconfigure-voyage", "Recovery flow: replace the Voyage key only", false)
         .option("--yes", "Accept all defaults (non-interactive)", false)
         .option("--skip-capture", "Skip the post-setup capture pass (test-only)", false)
+        .option("--no-codex-capture", "Skip the Codex CLI preflight + disable the capture pass for this run")
         .option("--with-claude-hook", "Install the Rift policy hook into Claude Code without prompting", false)
         .option("--no-claude-hook", "Skip the Claude Code policy-hook prompt entirely")
+        .option("--enable-codex-enrichment", "Opt into Codex AI metadata enrichment (default: AI-free import + keyword search)", false)
+        .option("--enable-capture", "Opt into scheduled chat capture + its Codex preflight (default: capture off, zero Codex calls)", false)
         .action(async (opts, cmd) => {
         const globalOpts = cmd.optsWithGlobals();
         try {
@@ -78,7 +110,9 @@ export function makeOnboardCommand() {
         }
     });
 }
-async function runOnboard(opts, globalOpts) {
+// Exported for orchestrator-level tests (e.g. the capture-without-key gate);
+// `makeOnboardCommand().action` is the only production caller.
+export async function runOnboard(opts, globalOpts) {
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
@@ -89,105 +123,236 @@ async function runOnboard(opts, globalOpts) {
             await reconfigureVoyageFlow(opts, globalOpts, rl);
             return;
         }
-        say("");
-        say("Rift — first-run setup");
-        say("─────────────────────");
+        ui.banner();
         // Step 1 — legacy migration (idempotent).
         const dataDir = await ensureConfigAndDataDir(globalOpts.config, opts, rl);
-        say("");
-        say("Running legacy migration check…");
         const migration = await runLegacyMigration({ dataDir });
         if (migration.migratedCount > 0) {
-            say(`Migrated ${migration.migratedCount} legacy artifact(s).`);
+            ui.step("ok", "Existing data", `carried over ${migration.migratedCount} item(s)`);
         }
         else {
-            say("No legacy artifacts found.");
+            ui.step("ok", "Existing data", "nothing to carry over");
         }
-        // Step 2 — Voyage key + validate + persist + kickstart + smoke.
-        say("");
-        say("Voyage API key");
-        const last4 = await collectAndPersistVoyageKey(opts, globalOpts, rl);
+        // Privacy contract — shown BEFORE the first outbound choice (the
+        // Voyage key, whose snippets leave the machine for embedding). A beta
+        // user should understand what stays local and what leaves before they
+        // paste anything.
+        ui.step("info", "Privacy", "");
+        sayPrivacyContract();
+        // Step 2 — Voyage key + validate + persist env. The daemon kickstart +
+        // smoke is deferred to Step 2e (after the opt-in writes below) so the
+        // respawned daemon boots with the final config.json.
+        const last4 = await collectAndPersistVoyageKey(opts, rl);
         // Step 2b — sanitize + persist optional --voyage-label to config.json
         // (backup first). Invalid labels are dropped without echoing the raw
         // value, so a key-shaped, path-shaped, or legacy-name-shaped label
         // can never leak through stdout or config.json.
         const safeLabel = applyVoyageLabel(opts.voyageLabel, globalOpts.config, say);
-        // Step 3 — Codex CLI preflight.
-        say("");
-        say("Codex CLI preflight…");
-        const codexOk = await codexPreflight();
-        if (!codexOk) {
-            say("Codex CLI is not authenticated. Run: codex login");
-            say("(Auto-capture needs Codex CLI auth. Re-run rift onboard once codex login succeeds.)");
-            throw new CliError("Codex CLI preflight failed.", "validation");
-        }
-        say("Codex CLI ready.");
+        // Step 2c — optional opt-in to Codex AI metadata enrichment. Default is
+        // AI-free import + keyword search (zero Codex calls). Only persisted when
+        // the user explicitly passed --enable-codex-enrichment.
+        applyCodexEnrichmentOptIn(opts.enableCodexEnrichment, globalOpts.config, say);
+        // Step 2d — optional opt-in to scheduled chat capture. Default off, so a
+        // fresh install makes zero Codex calls. Auto-capture embeds each saved
+        // conversation, so it requires a Voyage key; opting in without one would
+        // persist `capture.enabled = true` that the daemon can't honor (it would
+        // wake hourly, find no embedding provider, and save nothing). So we only
+        // persist the opt-in when a key was provided, and warn otherwise.
+        // `captureEnabled` is the single source of truth for the capture lane:
+        // requested AND a key is present. It gates BOTH the persistence here and
+        // the Codex preflight in Step 3 — refusing the opt-in must also skip the
+        // preflight's Codex triage call, or `--enable-capture` without a key would
+        // still leak a Codex call.
+        const captureRequested = opts.enableCapture === true;
+        const captureEnabled = captureRequested && last4 !== null;
+        if (captureRequested && last4 === null) {
+            ui.note("--enable-capture ignored: capture embeds saved conversations and needs a Voyage key. Re-run `rift onboard` with a key to enable it.");
+        }
+        else {
+            applyCaptureOptIn(opts.enableCapture, globalOpts.config, say);
+        }
+        // Step 2e — (re)start the daemon AFTER all config writes so it boots with
+        // the final config.json. The daemon builds its capture loop and metadata
+        // extractor once at boot (src/main.ts), so persisting the opt-ins above
+        // BEFORE this kickstart is what makes --enable-capture /
+        // --enable-codex-enrichment take effect immediately instead of only after
+        // a later restart. Key path only: the smoke asserts voyage_key_present,
+        // and the keyword-only path has no daemon smoke to run (the daemon was
+        // bootstrapped by install.sh and picks up config on its next start).
+        // `not_configured` / `agent_not_loaded` stay recoverable — the daemon
+        // simply isn't running yet on a fresh-Mac install before install.sh
+        // bootstraps the plist.
+        if (last4 !== null) {
+            const refresh = await daemonRefreshFlow(globalOpts);
+            if (!refresh.ok &&
+                refresh.kind !== "not_configured" &&
+                refresh.kind !== "agent_not_loaded") {
+                throw new CliError(`Voyage smoke failed after daemon kickstart: ${refresh.reason}`, "server_error");
+            }
+        }
+        // Step 3 — Codex CLI preflight (capture lane only).
+        //
+        // Capture is OFF by default (trust-first): a fresh install makes zero
+        // Codex calls. The preflight below performs a real Codex triage call,
+        // so it ONLY runs when capture is actually enabled — i.e. `--enable-capture`
+        // AND a Voyage key (see `captureEnabled` above). Without the flag, or with
+        // the flag but no key, the capture lane — and its Codex preflight — is
+        // skipped entirely, and import + keyword search below still work with no
+        // Codex dependency.
+        //
+        // When capture IS enabled, a failed preflight is a warning, not fatal —
+        // onboarding continues and the capture pass is skipped for this run.
+        // `--no-codex-capture` skips the preflight even when capture was enabled
+        // (e.g. enable the daemon schedule but skip the one-shot).
+        let captureDisabled = false;
+        // `codexUnavailable` is set ONLY when capture was enabled and the live
+        // Codex preflight actually failed — i.e. scheduled capture is configured
+        // on but cannot run until Codex is fixed. `--no-codex-capture` is NOT this
+        // case: it only skips the onboarding one-shot, leaving the daemon's
+        // scheduled capture to run normally. Keeping the two apart is what lets the
+        // import-prompt and summary copy stay honest instead of either over- or
+        // under-promising automatic capture.
+        let codexUnavailable = false;
+        if (!captureEnabled) {
+            ui.step("skip", "Chat access", captureRequested
+                ? "capture needs a Voyage key — skipped"
+                : "capture off (default) · enable with --enable-capture");
+            captureDisabled = true;
+        }
+        else if (isOff(opts, "codexCapture", "noCodexCapture")) {
+            ui.step("skip", "Chat access", "skipped (--no-codex-capture) · auto-import off");
+            captureDisabled = true;
+        }
+        else {
+            const codexSpin = new ui.Spinner("Chat access").start();
+            const codexOk = await codexPreflight();
+            if (codexOk) {
+                codexSpin.succeed("Chat access", "ready · Codex CLI");
+            }
+            else {
+                codexSpin.fail("Chat access", "not ready · Codex CLI — auto-import off");
+                ui.note("To enable later: run `codex login`, then re-run `rift onboard`.");
+                captureDisabled = true;
+                codexUnavailable = true;
+            }
+        }
+        // Will the daemon's scheduled auto-capture actually run going forward?
+        // Configured on (requested + Voyage key) AND Codex available. This is the
+        // signal the import prompt and the summary line must use — NOT bare
+        // `captureEnabled`, which is only "configured on" and stays true even after
+        // a failed Codex preflight already told the user auto-import is off.
+        const autoCaptureWillRun = captureEnabled && !codexUnavailable;
         // Step 4 — discover sessions.
-        say("");
         const claudeSessions = safeDiscover(() => discoverClaudeCodeSessions(path.join(os.homedir(), ".claude")));
         const codexSessions = safeDiscover(() => discoverCodexSessions());
-        say(`Found ${claudeSessions} Claude Code session(s) and ${codexSessions} Codex CLI session(s).`);
-        // Step 5 — privacy + feedback opt-in.
-        say("");
-        say("Privacy");
-        sayPrivacyContract();
-        const feedback = await collectFeedbackPreference(opts, rl, dataDir);
-        if (feedback.enabled) {
-            say(`Feedback relay enabled (installation_id: ${feedback.installation_id}).`);
+        ui.step("ok", "Chat history", `${claudeSessions} Claude Code · ${codexSessions} Codex CLI`);
+        // Step 5 — beta opt-in (stay connected: news, pricing, feedback).
+        const feedback = await collectFeedbackPreference(opts, dataDir, rl);
+        if (feedback.email) {
+            ui.step("ok", "Stay connected", `${feedback.email} — opted in (news + feedback)`);
+        }
+        else if (feedback.enabled) {
+            ui.step("ok", "Stay connected", `feedback relay on (installation_id: ${feedback.installation_id})`);
         }
         else {
-            say("Feedback relay off — feedback stays in local JSONL only.");
+            ui.step("ok", "Stay connected", "skipped — nothing shared, feedback stays local");
         }
         // Step 5b — optional Claude Code policy hook.
-        say("");
         await maybeInstallClaudeCodeHook(opts, rl);
         // Step 6 + 7 — watermark current sessions + run one capture pass.
         let captureSaved = 0;
-        if (!opts.skipCapture) {
-            say("");
-            say("Running first capture pass (watermark + scan)…");
-            const captureResult = await runFirstCapturePass(globalOpts.config, dataDir);
-            captureSaved = captureResult.saved;
+        let captureRan = false;
+        if (opts.skipCapture) {
+            ui.step("skip", "Chat import", "skipped (--skip-capture)");
+        }
+        else if (last4 === null) {
+            // Auto-capture saves embed each conversation, so it needs a real
+            // embedding provider. In keyword-only mode it is skipped; import +
+            // search below still work.
+            ui.step("skip", "Chat import", "skipped (no embedding key — capture needs one)");
+        }
+        else if (captureDisabled) {
+            // Capture lane is off — either the default (no --enable-capture) or a
+            // failed/declined Codex preflight. The "Chat access" step above already
+            // printed the specific reason.
+            ui.step("skip", "Chat import", "skipped (capture not enabled)");
         }
         else {
-            say("Skipping capture pass (--skip-capture).");
+            captureRan = true;
+            const captureResult = await runFirstCapturePass(globalOpts.config, dataDir);
+            captureSaved = captureResult.saved;
+            // Per A-1.1/C-1.3: a token-issuance failure during capture-pass
+            // is fatal. The wizard cannot meaningfully continue without auth
+            // (import + recall both need a token), and silently advancing
+            // past it was the original bug.
+            if (captureResult.fatal) {
+                rl.close();
+                return;
+            }
         }
         // Step 8 — optional export import.
-        say("");
         let importSucceeded = false;
-        if (!opts.noImportExport) {
-            const importPath = await collectImportPath(opts, rl);
+        let importAttempted = false;
+        if (isOff(opts, "importExport", "noImportExport")) {
+            ui.step("skip", "File import", "skipped (--no-import-export)");
+        }
+        else {
+            const importPath = await collectImportPath(opts, rl, {
+                willRun: autoCaptureWillRun,
+                configured: captureEnabled,
+            });
             if (importPath) {
+                importAttempted = true;
                 const outcome = await runImport(importPath, globalOpts.config);
                 if (outcome.kind === "imported" || outcome.kind === "duplicate") {
                     importSucceeded = true;
                 }
             }
             else {
-                say("Skipping import. Run rift import <path> --source <name> later.");
+                ui.step("skip", "File import", "none — run `rift import <path> --source <name>` later");
             }
         }
-        else {
-            say("Skipping import (--no-import-export).");
-        }
         // Step 9 — first-recall verification.
-        // Onboarding declares "complete" only when (a) capture or import landed
-        // user data this run, AND (b) a recall query against the daemon returns
-        // at least one hit. Without (a), there is nothing to recall — calling
-        // it "complete" because /search returned 0 rows would be misleading.
-        say("");
+        // A recall check only makes sense once this run actually landed user data.
+        // When nothing was imported or captured (the default, deliberate path), we
+        // skip the search check rather than start a spinner and FAIL it — failing a
+        // check the user opted out of is what made a clean setup feel broken.
         const ingestedAny = captureSaved > 0 || importSucceeded;
-        say(`First-recall sanity check (capture saved ${captureSaved} · import ${importSucceeded ? "ok" : "none"})…`);
-        const recall = ingestedAny
-            ? await firstRecallCheck(globalOpts.config)
-            : { ok: false, reason: "no user data was captured or imported during onboarding" };
+        const ingestAttempted = captureRan || importAttempted;
+        let recall;
+        if (!ingestedAny) {
+            ui.step("skip", "Search check", "nothing imported yet — skipped");
+            recall = { ok: false, reason: "nothing imported yet" };
+        }
+        else {
+            const recallSpin = new ui.Spinner("Search check").start();
+            recall = await firstRecallCheck(globalOpts.config);
+            if (recall.ok && recall.hits > 0) {
+                recallSpin.succeed("Search check", `found ${recall.hits} result(s)`);
+            }
+            else if (recall.ok) {
+                recallSpin.warn("Search check", "no results yet — index is fresh, try a query shortly");
+            }
+            else {
+                recallSpin.fail("Search check", recall.reason);
+            }
+        }
         // Step 10 — next-action card.
-        say("");
-        say("─────────────────────");
-        for (const line of decideOnboardOutcome({ ingestedAny, recall }))
-            say(line);
-        say(`Voyage: key valid (last 4 …${last4})${safeLabel ? ` · label ${safeLabel}` : ""}`);
-        say("");
+        const card = decideOnboardOutcome({ ingestedAny, recall, ingestAttempted });
+        card.push(ui.pc.dim(last4 !== null
+            ? `Voyage: key valid (last 4 …${last4})${safeLabel ? ` · label ${safeLabel}` : ""}`
+            : "Search: keyword-only (no embedding key) — add one later for semantic search"));
+        // One-line "what's on/off" so the friend leaves knowing whether Rift keeps
+        // itself fed. Three honest states: ready (configured + Codex available),
+        // configured-but-not-ready (Codex failed — don't claim it's running), and
+        // off (the default). Capture is off by default (zero-Codex trust default).
+        card.push(ui.pc.dim(autoCaptureWillRun
+            ? "Auto-capture: on — new chats are captured on a schedule."
+            : captureEnabled
+                ? "Auto-capture: configured on, but not ready — Codex CLI isn't available (run `codex login`)."
+                : "Auto-capture: off — enable with: rift onboard --enable-capture"));
+        ui.box(card);
+        ui.line("");
     }
     finally {
         rl.close();
@@ -196,10 +361,11 @@ async function runOnboard(opts, globalOpts) {
 // ----- Step 1: config.json + data dir -----
 async function ensureConfigAndDataDir(configPath, opts, rl) {
     const absoluteConfig = path.resolve(configPath);
+    const shownConfig = absoluteConfig.replace(os.homedir(), "~");
     if (fs.existsSync(absoluteConfig)) {
         const config = loadConfig(absoluteConfig);
-        say(`Using existing config: ${absoluteConfig}`);
-        say(`Data dir: ${config.data_paths.data_dir}`);
+        ui.step("ok", "Settings", shownConfig);
+        ui.note(`data dir: ${config.data_paths.data_dir}`);
         return config.data_paths.data_dir;
     }
     const defaultDataDir = DEFAULT_DATA_DIR;
@@ -222,15 +388,27 @@ async function ensureConfigAndDataDir(configPath, opts, rl) {
         embedding: { provider: "voyage", model: "voyage-3-lite" },
         data_paths: { data_dir: dataDir, jobs_dir: path.join(dataDir, "..", "jobs") },
         rate_limit: { window_ms: 60_000, max_requests: 100 },
-        capture: { enabled: true, interval_seconds: 3600 },
+        // Trust-first default: scheduled chat capture is OFF. The capture lane
+        // runs a Codex CLI triage call, so a fresh install sends no conversation
+        // content off-device, runs no Voyage embedding, and makes no Codex model
+        // call until the user opts in with `--enable-capture` (persisted below).
+        // (The daemon does make a metadata-only npm version check — no content, no
+        // key, no machine info.) The daemon gates auto-capture on `capture.enabled`.
+        capture: { enabled: false, interval_seconds: 3600 },
+        // Trust-first default: AI metadata enrichment is OFF. Import + keyword
+        // search run AI-free (BasicMetadataExtractor) and make no Codex calls,
+        // even on a machine with Codex installed. `--enable-codex-enrichment`
+        // (persisted below) flips this on. The `embedding` block above is a
+        // routing target only — without a Voyage key, search stays lexical.
+        enrichment: { ai_metadata: false },
     };
     fs.mkdirSync(path.dirname(absoluteConfig), { recursive: true });
     fs.writeFileSync(absoluteConfig, JSON.stringify(config, null, 2) + "\n", {
         encoding: "utf8",
         mode: 0o644,
     });
-    say(`Wrote default config: ${absoluteConfig}`);
-    say(`Data dir: ${dataDir}`);
+    ui.step("ok", "Settings", `wrote default · ${shownConfig}`);
+    ui.note(`data dir: ${dataDir}`);
     // Trigger ensureDirectories.
     loadConfig(absoluteConfig);
     return dataDir;
@@ -300,45 +478,135 @@ export function persistVoyageLabel(configPath, label) {
     });
     fs.renameSync(tmp, absolute);
 }
+/**
+ * Persist the Codex AI-metadata-enrichment opt-in into config.json. Default
+ * onboarding leaves `enrichment.ai_metadata = false` (AI-free import + keyword
+ * search, zero Codex calls). When the user passes `--enable-codex-enrichment`,
+ * this flips it to true so the daemon/worker select the Codex-backed extractor.
+ * Backs the file up first, mirroring `persistVoyageLabel`.
+ *
+ * Exported for orchestrator-level tests; `runOnboard` is the only production
+ * caller. Returns true when the flag was set and persisted, false otherwise.
+ */
+export function applyCodexEnrichmentOptIn(enable, configPath, emit) {
+    if (enable !== true)
+        return false;
+    const absolute = path.resolve(configPath);
+    if (!fs.existsSync(absolute)) {
+        throw new CliError(`Cannot persist enrichment opt-in: config not found at ${absolute}`, "validation");
+    }
+    const raw = fs.readFileSync(absolute, "utf8");
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    fs.writeFileSync(`${absolute}.bak.${stamp}`, raw, { encoding: "utf8", mode: 0o600 });
+    const parsed = JSON.parse(raw);
+    const enrichment = parsed["enrichment"] ?? {};
+    enrichment["ai_metadata"] = true;
+    parsed["enrichment"] = enrichment;
+    const tmp = `${absolute}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(parsed, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o644,
+    });
+    fs.renameSync(tmp, absolute);
+    emit("Codex AI metadata enrichment enabled (enrichment.ai_metadata = true).");
+    return true;
+}
+/**
+ * Persist the scheduled-capture opt-in. Default install writes
+ * `capture.enabled = false` (trust-first: zero Codex calls on a fresh
+ * machine). When the user passes `--enable-capture`, this flips it to true
+ * so the daemon runs auto-capture on its interval. Backs the file up first,
+ * mirroring `applyCodexEnrichmentOptIn`.
+ *
+ * Exported for orchestrator-level tests; `runOnboard` is the only production
+ * caller. Returns true when the flag was set and persisted, false otherwise.
+ */
+export function applyCaptureOptIn(enable, configPath, emit) {
+    if (enable !== true)
+        return false;
+    const absolute = path.resolve(configPath);
+    if (!fs.existsSync(absolute)) {
+        throw new CliError(`Cannot persist capture opt-in: config not found at ${absolute}`, "validation");
+    }
+    const raw = fs.readFileSync(absolute, "utf8");
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    fs.writeFileSync(`${absolute}.bak.${stamp}`, raw, { encoding: "utf8", mode: 0o600 });
+    const parsed = JSON.parse(raw);
+    const capture = parsed["capture"] ?? {};
+    capture["enabled"] = true;
+    parsed["capture"] = capture;
+    const tmp = `${absolute}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(parsed, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o644,
+    });
+    fs.renameSync(tmp, absolute);
+    emit("Scheduled chat capture enabled (capture.enabled = true).");
+    return true;
+}
 // ----- Step 2: Voyage key flow -----
-async function collectAndPersistVoyageKey(opts, globalOpts, rl) {
+async function collectAndPersistVoyageKey(opts, rl) {
     const key = await collectVoyageKey(opts, rl);
-    say("Validating with Voyage API…");
+    if (!key) {
+        // No key → keyword-only (lexical) mode. Not a failure; import + search
+        // still work. Skip validation, the env write, and the Voyage smoke.
+        ui.step("info", "Search index", "no key — keyword search (semantic off)");
+        ui.note("Add semantic search later: run `rift onboard` and paste a Voyage key.");
+        return null;
+    }
+    const validateSpin = new ui.Spinner("Search index").start();
     const validation = await validateVoyageKey({ apiKey: key });
     if (!validation.ok) {
+        validateSpin.fail("Search index", "validation failed");
         throw new CliError(`Voyage validation failed: ${validation.reason}`, "validation");
     }
-    say(`Voyage key valid (last 4 …${validation.last4}).`);
+    validateSpin.succeed("Search index", `connected · Voyage · ····${validation.last4}`);
     const envPath = defaultRiftEnvPath();
     const writeResult = writeEnvFile({ filePath: envPath, key: "VOYAGE_API_KEY", value: key });
-    say(writeResult.backedUp
-        ? "Wrote ~/.rift.env (existing file backed up)."
-        : "Wrote ~/.rift.env (mode 0600).");
+    ui.note(writeResult.backedUp
+        ? "wrote ~/.rift.env (existing file backed up)"
+        : "wrote ~/.rift.env (mode 0600)");
     // Refresh process.env so any subsequent in-process Voyage call sees it.
     loadRiftEnv({ filePath: envPath });
-    const refresh = await daemonRefreshFlow(globalOpts);
-    // `not_configured` / `agent_not_loaded` are recoverable — the daemon
-    // simply isn't running yet (typical on fresh-Mac install before
-    // install.sh bootstraps the plist). Onboarding continues without the
-    // post-kickstart smoke; install.sh will pick it up.
-    if (!refresh.ok && refresh.kind !== "not_configured" && refresh.kind !== "agent_not_loaded") {
-        throw new CliError(`Voyage smoke failed after daemon kickstart: ${refresh.reason}`, "server_error");
-    }
+    // NOTE: the daemon kickstart + smoke deliberately does NOT happen here.
+    // It runs in `runOnboard` AFTER the opt-in writes (label/enrichment/
+    // capture) land in config.json, so the respawned daemon boots with the
+    // final config. The daemon builds its capture loop and metadata extractor
+    // once at boot (src/main.ts), so kickstarting before those writes would
+    // leave `--enable-capture` / `--enable-codex-enrichment` inert until a
+    // later restart.
     return validation.last4;
 }
-async function collectVoyageKey(opts, rl) {
-    if (opts.voyageKey)
+/**
+ * Resolve the Voyage key, or `""` to mean "finish without a key" (keyword-only
+ * lexical mode). The key is no longer mandatory: a friend can import and search
+ * first, then add a key later for semantic ranking. Returns `""` on explicit
+ * opt-out (`--no-voyage-key`), on `--yes` with no key available, or when the
+ * interactive prompt is left blank.
+ */
+export async function collectVoyageKey(opts, rl) {
+    if (opts.voyageKey === false || opts.noVoyageKey === true)
+        return "";
+    if (typeof opts.voyageKey === "string" && opts.voyageKey.trim()) {
         return opts.voyageKey.trim();
+    }
     if (process.env["VOYAGE_API_KEY"])
         return process.env["VOYAGE_API_KEY"].trim();
-    if (opts.yes) {
-        throw new CliError("--yes given but no Voyage key found (use --voyage-key or set VOYAGE_API_KEY).", "validation");
-    }
-    const answer = (await ask(rl, "Paste your Voyage API key: ")).trim();
-    if (answer.length === 0) {
-        throw new CliError("Voyage key is required.", "validation");
-    }
-    return answer;
+    // Non-interactive with no key supplied: finish in lexical mode rather than
+    // fail. The friend can run `rift onboard` again with a key anytime.
+    if (opts.yes)
+        return "";
+    // Explain the key BEFORE asking for it — a beta user should know what
+    // they are pasting and why, not be confronted with a bare prompt.
+    ui.detail([
+        "Search index key (optional)",
+        "• What: paste the Voyage key Clem sent you (it won't echo as you type).",
+        "• Why: Voyage adds meaning-based (semantic) search on top of keyword search.",
+        "• Skip: press Enter to finish now with keyword search — add a key later anytime.",
+        "• Privacy: the key is stored locally and only sent to Voyage when Rift calls Voyage; never sent to Clem.",
+    ].join("\n"));
+    const answer = (await ask(rl, "Paste your Voyage API key (or press Enter to skip): ")).trim();
+    return answer; // "" → finish in keyword-only mode
 }
 /**
  * Kickstart, wait for /health, confirm the respawned daemon process has
@@ -351,54 +619,126 @@ async function collectVoyageKey(opts, rl) {
 async function daemonRefreshFlow(globalOpts) {
     const baseUrl = safeResolveBaseUrl(globalOpts.config);
     if (!baseUrl) {
-        say("Daemon not configured yet — skipping kickstart. Bootstrap via install.sh, then re-run rift onboard.");
+        ui.step("skip", "Rift service", "not configured yet — bootstrap via install.sh, then re-run");
         return { ok: false, reason: "daemon not configured", kind: "not_configured" };
     }
+    const daemonSpin = new ui.Spinner("Rift service").start();
     const kick = await kickstartDaemon();
     if (kick.status === "agent_not_loaded") {
-        say(kick.hint);
+        daemonSpin.fail("Rift service", "launchd agent not loaded");
+        ui.note(kick.hint);
         return { ok: false, reason: kick.hint ?? "agent not loaded", kind: "agent_not_loaded" };
     }
     if (kick.status === "failed") {
+        daemonSpin.fail("Rift service", "kickstart failed");
         return {
             ok: false,
             reason: kick.hint ?? "kickstart failed",
             kind: "kickstart_failed",
         };
     }
-    say("Daemon kickstarted.");
     const health = await waitForHealth({ baseUrl });
     if (!health.ok) {
+        daemonSpin.fail("Rift service", "health check failed");
         return { ok: false, reason: health.reason, kind: "health_failed" };
     }
-    say(`Daemon healthy (uptime ${health.uptimeSeconds}s).`);
     if (!health.voyageKeyPresent) {
+        daemonSpin.fail("Rift service", "voyage_key_present=false after kickstart");
         return {
             ok: false,
             reason: "Daemon /health reports voyage_key_present=false after kickstart.",
             kind: "smoke_failed",
         };
     }
-    say("Cloud embedding live (daemon loaded VOYAGE_API_KEY).");
+    daemonSpin.succeed("Rift service", `healthy · daemon · uptime ${health.uptimeSeconds}s`);
     return { ok: true, kickstarted: true };
 }
-// ----- Token helpers -----
-async function ensureToken(configPath) {
-    const existing = await readToken();
-    if (existing)
-        return existing;
+export function classifyTokenFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const lower = message.toLowerCase();
+    // A-1.2: the macOS Keychain prints the same string whether the lock
+    // hits a read or a write. Catch on substring; don't try to inspect
+    // SecKeychain error codes from JS.
+    //
+    // Two shapes can land here:
+    //   1. The raw `security` error from a write path (`issueToken`),
+    //      whose message contains "User interaction is not allowed."
+    //   2. The friendly `CliError` shape that `readToken` now throws
+    //      (post-beta.7) in place of the raw error. Its message starts
+    //      with "Login Keychain is locked" and embeds the
+    //      `security unlock-keychain` recovery command verbatim.
+    // Both must classify as `keychain_locked` so the typed
+    // recovery branch in `runFirstCapturePass` fires correctly.
+    if (lower.includes("user interaction is not allowed") ||
+        lower.includes("login keychain is locked") ||
+        lower.includes("security unlock-keychain")) {
+        return { reason: "keychain_locked", message };
+    }
+    return { reason: "other", message };
+}
+export async function ensureToken(configPath) {
+    // A-1.2: readToken is inside the try — a locked-keychain *read* must
+    // be classified the same as a locked-keychain *write*.
+    try {
+        const existing = await readToken();
+        if (existing)
+            return { ok: true, token: existing, source: "existing" };
+    }
+    catch (err) {
+        const { reason, message } = classifyTokenFailure(err);
+        return { ok: false, reason, message, hint: describeTokenFailure(message) };
+    }
     try {
         const { token } = await issueToken(path.resolve(configPath));
         // Mirror to ~/.rift/token so subsequent CLI calls don't depend on Keychain.
         const tokenPath = path.join(os.homedir(), ".rift", "token");
-        fs.mkdirSync(path.dirname(tokenPath), { recursive: true });
-        fs.writeFileSync(tokenPath, token + "\n", { encoding: "utf8", mode: 0o600 });
-        fs.chmodSync(tokenPath, 0o600);
-        return token;
+        try {
+            fs.mkdirSync(path.dirname(tokenPath), { recursive: true });
+            fs.writeFileSync(tokenPath, token + "\n", {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+            fs.chmodSync(tokenPath, 0o600);
+        }
+        catch (writeErr) {
+            const reason = writeErr instanceof Error ? writeErr.message : String(writeErr);
+            say(`Token issued but mirror to ${tokenPath} failed: ${reason}. Subsequent CLI calls will rely on Keychain only.`);
+        }
+        return { ok: true, token, source: "issued" };
     }
-    catch {
-        return null;
+    catch (err) {
+        const { reason, message } = classifyTokenFailure(err);
+        return { ok: false, reason, message, hint: describeTokenFailure(message) };
+    }
+}
+export function describeTokenFailure(reason) {
+    const lower = reason.toLowerCase();
+    // Two SSH-locked shapes can land here — check both before the generic
+    // Keychain branch so the GUI-only "Keychain Access → File → Unlock"
+    // copy never replaces the SSH-specific `security unlock-keychain`
+    // command: (1) the raw `security` error from the write path, and
+    // (2) the friendly CliError that readToken now emits post-beta.7,
+    // whose message starts with "Login Keychain is locked" and embeds
+    // the unlock command verbatim.
+    if (lower.includes("user interaction is not allowed") ||
+        lower.includes("login keychain is locked") ||
+        lower.includes("security unlock-keychain")) {
+        return "the login Keychain is locked (typical over SSH). Run `security unlock-keychain ~/Library/Keychains/login.keychain-db` (it will prompt for your Mac login password), then re-run `rift onboard`. For local Terminal installs this should not happen.";
+    }
+    if (lower.includes("keychain") || lower.includes("security:")) {
+        return "unlock the login Keychain (Keychain Access → File → Unlock) and re-run, or run from a Terminal session with GUI access (not over SSH).";
+    }
+    if (lower.includes("eacces") || lower.includes("permission denied")) {
+        return "check that `~/.rift/` is writable by your user, then re-run `rift onboard`.";
+    }
+    if (lower.includes("enoent") ||
+        lower.includes("no such file") ||
+        lower.includes("daemon") ||
+        lower.includes("pid file") ||
+        lower.includes("not running")) {
+        return "start the daemon with `launchctl kickstart -k gui/$UID/com.getrift.daemon`, then re-run `rift onboard`.";
     }
+    return "re-run `rift onboard`. If the failure repeats, run `rift feedback --kind=broke --with-status` to ship a diagnostic bundle.";
 }
 // ----- Step 3: Codex preflight -----
 async function codexPreflight() {
@@ -413,33 +753,125 @@ async function codexPreflight() {
         return false;
     }
 }
-async function collectFeedbackPreference(opts, rl, dataDir) {
-    let enabled = false;
+/**
+ * Conservative email check — enough to catch obvious typos at the prompt;
+ * the relay endpoint can re-validate. Returns the normalized (trimmed,
+ * lowercased) address, or undefined if it doesn't look like an email.
+ */
+export function normalizeEmail(raw) {
+    const s = raw.trim().toLowerCase();
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s) ? s : undefined;
+}
+/**
+ * Bundled "stay connected" opt-in. One yes/no that, on yes, collects an
+ * email used for product news, pricing, a leaving-beta heads-up, and a
+ * feedback channel. Opt-in only: `--yes` alone never subscribes (consent
+ * must be active), `--no-feedback-relay` declines, and `--email` subscribes
+ * non-interactively. The relay URL stays operator-only infra; when none is
+ * configured the email is captured locally (sidecar + beta-signups.jsonl)
+ * and reaches the operator once an endpoint is wired.
+ */
+export async function collectFeedbackPreference(opts, dataDir, rl, store = macRelaySecretStore) {
+    const declined = isOff(opts, "feedbackRelay", "noFeedbackRelay");
+    // Relay URL + signing secret come from EITHER an invite code (preferred:
+    // nothing to paste by hand) OR the back-compat operator flags. The secret
+    // never lands in the sidecar — it goes to the Keychain below.
     let url;
-    if (opts.enableFeedbackRelay) {
-        enabled = true;
-        url = opts.enableFeedbackRelay;
+    let secret;
+    if (!declined) {
+        if (opts.invite) {
+            const invite = parseInvite(opts.invite); // throws a friendly CliError if bad
+            url = invite.url;
+            secret = invite.secret;
+        }
+        else {
+            url = opts.enableFeedbackRelay;
+            secret = url ? opts.relaySecret : undefined;
+        }
     }
-    else if (opts.noFeedbackRelay || opts.yes) {
-        enabled = false;
+    // Friend-grade interactive path: when no relay flags were passed, offer to
+    // paste an invite so the bearer code never lands in shell history. Skipped
+    // off a TTY and under --yes (automation). A bad paste warns and skips — it
+    // never aborts onboarding.
+    if (!declined &&
+        !url &&
+        !opts.invite &&
+        !opts.enableFeedbackRelay &&
+        !opts.yes &&
+        process.stdin.isTTY) {
+        // Most friends will NOT have an invite code — make that the obvious,
+        // pressure-free default so the bare prompt doesn't read as "something is
+        // missing". An invite only turns on the direct feedback relay; the email
+        // ask below (and `rift feedback`) work without it.
+        ui.detail([
+            "Feedback channel (optional)",
+            "• Have an invite code from Clem? Paste it to turn on the direct feedback relay.",
+            "• No code? Just press Enter — this is optional, and most people skip it.",
+            "• Either way you can send feedback any time with `rift feedback`.",
+        ].join("\n"));
+        const pasted = (await ask(rl, "Invite code from Clem (or press Enter to skip): ")).trim();
+        if (pasted) {
+            try {
+                const invite = parseInvite(pasted);
+                url = invite.url;
+                secret = invite.secret;
+            }
+            catch {
+                say("  That invite code is not valid — skipping feedback setup.");
+            }
+        }
     }
-    else {
-        const answer = (await ask(rl, "Opt into the Rift feedback relay? [y/N]: ", "n"))
-            .trim()
-            .toLowerCase();
-        enabled = answer === "y" || answer === "yes";
-        if (enabled) {
-            url = (await ask(rl, "Relay URL: ")).trim();
-            if (!url) {
-                say("No URL supplied — keeping relay off.");
-                enabled = false;
-                url = undefined;
+    // Configuring a URL without a signing secret leaves the install "looks
+    // configured, silently dead" — the receiver requires a valid signature.
+    // An invite always carries one; the flag path must pair a secret or
+    // knowingly opt into unsigned mode (dev/local receivers only).
+    if (url && !secret && !opts.allowUnsignedFeedbackRelay) {
+        throw new CliError("Relay needs a signing secret. Use an invite (rift onboard --invite <code>), " +
+            "or pair --enable-feedback-relay with --relay-secret " +
+            "(or --allow-unsigned-feedback-relay for a dev receiver).", "validation");
+    }
+    // Secure the secret BEFORE enabling relay: a write failure must not leave an
+    // enabled config that can't sign. (3a's `rift feedback setup` does the same.)
+    if (secret) {
+        try {
+            await store.write(secret);
+        }
+        catch (err) {
+            if (err instanceof LockedKeychainError) {
+                throw new CliError("Your macOS Keychain is locked. Unlock it and retry: " +
+                    "security unlock-keychain ~/Library/Keychains/login.keychain-db", "validation");
             }
+            throw err;
         }
     }
-    const cfg = enabled && url
-        ? { enabled: true, url, installation_id: crypto.randomUUID() }
+    let email;
+    if (!declined) {
+        if (opts.email) {
+            email = normalizeEmail(opts.email);
+            if (!email) {
+                throw new CliError(`--email "${opts.email}" is not a valid email address.`, "validation");
+            }
+        }
+        else if (!opts.yes && process.stdin.isTTY) {
+            email = await promptStayConnected(rl);
+        }
+        // --yes / non-TTY with no --email: do not auto-subscribe.
+    }
+    const optedIn = email !== undefined || url !== undefined;
+    const cfg = optedIn
+        ? {
+            enabled: true,
+            installation_id: crypto.randomUUID(),
+            ...(email ? { email } : {}),
+            ...(url ? { url } : {}),
+            // url && !secret only happens under --allow-unsigned-feedback-relay
+            // (the guard above throws otherwise): mark it an intentional unsigned
+            // relay so maybeRelay may POST without a secret for THIS install only.
+            ...(url && !secret ? { unsigned: true } : {}),
+        }
         : { enabled: false };
+    // The sidecar holds only non-secret fields; the secret is already in the
+    // Keychain (above).
     fs.mkdirSync(dataDir, { recursive: true });
     const sidecar = path.join(dataDir, "feedback-config.json");
     fs.writeFileSync(sidecar, JSON.stringify(cfg, null, 2) + "\n", {
@@ -447,8 +879,91 @@ async function collectFeedbackPreference(opts, rl, dataDir) {
         mode: 0o600,
     });
     fs.chmodSync(sidecar, 0o600);
+    if (cfg.email && cfg.installation_id) {
+        // Sign the signup POST with the in-hand secret (no Keychain round-trip).
+        await emitBetaSignup(cfg.email, cfg.installation_id, cfg.url, secret, dataDir);
+    }
     return cfg;
 }
+/**
+ * Interactive bundled opt-in. Returns the chosen email, or undefined if the
+ * user declines or skips. Re-prompts up to 3× on a malformed address; an
+ * empty line at any point means "skip".
+ */
+async function promptStayConnected(rl) {
+    ui.detail([
+        "Stay in the loop (optional)",
+        "• Get product news, pricing once we set it, and a heads-up when Rift leaves beta.",
+        "• Gives you a direct line to send feedback any time via `rift feedback`.",
+        "• Opt-in. Stored locally, shared only with Clem — never sold, never spammed.",
+    ].join("\n"));
+    const yn = (await ask(rl, "Share your email to stay connected? [y/N] ")).trim().toLowerCase();
+    if (yn !== "y" && yn !== "yes")
+        return undefined;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const raw = (await ask(rl, "Your email (Enter to skip): ")).trim();
+        if (raw.length === 0)
+            return undefined;
+        const norm = normalizeEmail(raw);
+        if (norm)
+            return norm;
+        say("  That doesn't look like an email address — try again, or press Enter to skip.");
+    }
+    return undefined;
+}
+/**
+ * Record a one-time beta signup. The local JSONL row is canonical (never
+ * lost); the relay POST is best-effort and only fires when an endpoint URL
+ * is configured. Failures are swallowed — onboarding must never break on a
+ * signup hiccup.
+ */
+async function emitBetaSignup(email, installationId, url, hmacSecret, dataDir) {
+    const build = getBuildInfo();
+    const payload = {
+        ts: new Date().toISOString(),
+        event: "beta_signup",
+        email,
+        installation_id: installationId,
+        version: build.version,
+        commit: build.commit,
+        node: build.node,
+    };
+    // Audit invariant: every byte that reaches Clem must exist locally first.
+    // If the canonical row can't be written, we must NOT relay — otherwise a
+    // signup could reach Clem with no local record to audit against.
+    let wroteLocal = false;
+    try {
+        const dir = path.join(dataDir, "observability");
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, "beta-signups.jsonl");
+        fs.appendFileSync(file, `${JSON.stringify(payload)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        wroteLocal = true; // the canonical row is on disk; chmod below is cosmetic
+        try {
+            fs.chmodSync(file, 0o600);
+        }
+        catch {
+            // best-effort permission fix — does not affect the audit invariant
+        }
+    }
+    catch {
+        // Local write failed — don't break onboarding over a signup row, and
+        // (below) don't relay something we couldn't record locally.
+    }
+    if (url && wroteLocal) {
+        try {
+            await postFeedback(payload, {
+                url,
+                ...(hmacSecret ? { hmacSecret } : {}),
+            });
+        }
+        catch {
+            // Best-effort; the canonical row is already on disk.
+        }
+    }
+}
 // ----- Step 5b: Claude Code policy hook (opt-in) -----
 /**
  * Offer to install the Rift policy hook into Claude Code's settings.
@@ -463,7 +978,7 @@ async function collectFeedbackPreference(opts, rl, dataDir) {
  * guardrail, not a correctness requirement.
  */
 async function maybeInstallClaudeCodeHook(opts, rl) {
-    if (opts.noClaudeHook) {
+    if (isOff(opts, "claudeHook", "noClaudeHook")) {
         return;
     }
     const homeDir = os.homedir();
@@ -478,20 +993,22 @@ async function maybeInstallClaudeCodeHook(opts, rl) {
     }
     else if (opts.yes) {
         // Non-interactive default: skip. Operator must opt in with --with-claude-hook.
-        say("Claude Code detected — skipping the policy-hook prompt (pass --with-claude-hook to install non-interactively).");
+        ui.step("skip", "Claude Code", "skipped (pass --with-claude-hook to install non-interactively)");
         return;
     }
     else {
-        say("Claude Code detected.");
-        say("Optional: install a PreToolUse policy hook so Rift retrieval starts with rift_context_pack");
-        say("(prevents broad rift_search dumps from burning context). Disable any time with RIFT_POLICY_DISABLED=1.");
-        const answer = (await ask(rl, "Install Claude Code policy hook? [y/N]: ", "n"))
+        ui.note([
+            "Claude Code detected.",
+            "Optional: install a PreToolUse policy hook so Rift retrieval starts with rift_context_pack",
+            "(prevents broad rift_search dumps from burning context). Disable any time with RIFT_POLICY_DISABLED=1.",
+        ].join("\n"));
+        const answer = (await ask(rl, "  Install Claude Code policy hook? [y/N]: ", "n"))
             .trim()
             .toLowerCase();
         install = answer === "y" || answer === "yes";
     }
     if (!install) {
-        say("Skipping Claude Code policy hook.");
+        ui.step("skip", "Claude Code", "not installed");
         return;
     }
     try {
@@ -501,25 +1018,25 @@ async function maybeInstallClaudeCodeHook(opts, rl) {
             dryRun: false,
         });
         if (outcome.hookEntryAdded) {
-            say("Installed Rift policy hook into Claude Code (PreToolUse entry added).");
+            ui.step("ok", "Claude Code", "connected · auto-recall hook added");
         }
         else if (outcome.hookEntryReplaced || outcome.scriptUpdated) {
-            say("Updated Rift policy hook in Claude Code.");
+            ui.step("ok", "Claude Code", "updated");
         }
         else {
-            say("Rift policy hook already up-to-date in Claude Code.");
+            ui.step("ok", "Claude Code", "already up-to-date");
         }
         if (outcome.backupId) {
-            say(`  Backup ID: ${outcome.backupId}`);
+            ui.note(`backup ID: ${outcome.backupId}`);
         }
-        say("  (Restart Claude Code or open /hooks once for the new entry to load.)");
+        ui.note("(Restart Claude Code or open /hooks once for the new entry to load.)");
     }
     catch (err) {
         if (err instanceof HooksParseFailedError) {
-            say(err.message);
+            ui.step("fail", "Claude Code", err.message);
         }
         else {
-            say(`Claude Code hook install failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+            ui.step("fail", "Claude Code", `install failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }
@@ -527,26 +1044,59 @@ async function maybeInstallClaudeCodeHook(opts, rl) {
 export async function runFirstCapturePass(configPath, dataDir) {
     const baseUrl = safeResolveBaseUrl(configPath);
     if (!baseUrl) {
-        say("Daemon not reachable — skipping capture pass.");
+        ui.step("skip", "Chat import", "daemon not reachable — skipped");
         return { saved: 0, reviewed: 0 };
     }
-    const token = await ensureToken(configPath);
-    if (!token) {
-        say("No auth token — skipping capture pass.");
-        return { saved: 0, reviewed: 0 };
+    // Per A-1.1/C-1.3: token failure here is fatal. The wizard cannot
+    // proceed without a token (capture, import, recall all need auth).
+    // The previous "skipping" path silently broke onboarding.
+    const tokenResult = await ensureToken(configPath);
+    if (!tokenResult.ok) {
+        say("");
+        if (tokenResult.reason === "keychain_locked") {
+            say("Could not issue an auth token: the macOS login keychain is locked.");
+            say("Run this, then re-run `rift onboard`:");
+            say("  security unlock-keychain ~/Library/Keychains/login.keychain-db");
+            say("Note: the wizard will restart from the top. If your Voyage key is in");
+            say("      VOYAGE_API_KEY it won't re-prompt; otherwise you'll re-paste it.");
+        }
+        else {
+            // Per C-1.4 (round-6 fix): the "other" branch must spell out the
+            // manual recovery so the user knows the exit path is `rift token
+            // issue` then re-running onboard. Generic hints alone aren't
+            // enough.
+            say(`Could not issue an auth token: ${tokenResult.message}`);
+            say(`Recover: ${tokenResult.hint}`);
+            say("If the failure persists, run `rift token issue` manually, then re-run `rift onboard`.");
+        }
+        process.exitCode = 1;
+        return { saved: 0, reviewed: 0, fatal: true };
     }
+    const token = tokenResult.token;
     const client = createHttpClient({ baseUrl, token });
     let codexCaptureDeps = {};
+    let enabledSources = DEFAULT_AUTO_CAPTURE_SOURCES;
     try {
         const { loadConfig } = await import("../../config/loader.js");
-        codexCaptureDeps = resolveCodexCaptureDeps(loadConfig(configPath));
+        const cfg = loadConfig(configPath);
+        codexCaptureDeps = resolveCodexCaptureDeps(cfg);
+        enabledSources = cfg.capture.sources;
     }
     catch {
         codexCaptureDeps = {};
     }
+    const startedAt = new Date();
+    const captureSpin = new ui.Spinner("Chat import").start();
     try {
         const report = await runAutoCapture({
             dataDir,
+            // Capture exactly the sources config enables — the same set the
+            // scheduled daemon loop uses (buildDaemonAutoCaptureDeps passes
+            // cfg.capture.sources) and the same set recorded in the ledger row
+            // below. Omitting this falls back to DEFAULT_AUTO_CAPTURE_SOURCES, which
+            // would let onboarding capture sources it never records — a status
+            // ledger that says one thing while capture did another.
+            sources: enabledSources,
             ...codexCaptureDeps,
             saveFn: async (saveOpts) => {
                 const { data } = await client.post("/save", {
@@ -569,21 +1119,82 @@ export async function runFirstCapturePass(configPath, dataDir) {
                 }
             },
         });
-        say(`Capture: discovered ${report.total_discovered}, new ${report.new_conversations}, saved ${report.saved}, review ${report.review}, errors ${report.errors}.`);
+        // Record this onboard run in the health ledger (best-effort). Without
+        // it, a friend who finishes onboarding and immediately runs `rift
+        // status`/`rift doctor` sees "no runs yet" — the exact stale-health
+        // trust break this ledger exists to prevent, at the moment it matters
+        // most. Tagged `onboard` so it sets freshness without ever speaking for
+        // the scheduled daemon loop.
+        try {
+            await appendAutoCaptureRunRecord(dataDir, buildAutoCaptureRunRecord({
+                timestamp: startedAt.toISOString(),
+                enabledSources,
+                durationMs: Date.now() - startedAt.getTime(),
+                report,
+                trigger: "onboard",
+            }));
+        }
+        catch (observabilityErr) {
+            process.stderr.write(`Onboard capture run-record append failed: ${observabilityErr instanceof Error
+                ? observabilityErr.message
+                : String(observabilityErr)}\n`);
+        }
+        const base = `${report.saved} added · ${report.review} to review`;
+        // A preflight failure (Codex health probe) carries 0 per-session errors,
+        // so an `errors > 0` check alone would `succeed()` on a run where triage
+        // never ran — telling a friend everything's fine when it isn't. Treat a
+        // failed probe as a warning too, and surface why.
+        if (!report.preflight_ok) {
+            captureSpin.warn("Chat import", `${base} · Codex preflight failed${report.preflight_error ? ` (${report.preflight_error})` : ""}`);
+        }
+        else if (report.errors > 0) {
+            captureSpin.warn("Chat import", `${base} · ${report.errors} error(s)`);
+        }
+        else {
+            captureSpin.succeed("Chat import", base);
+        }
         return { saved: report.saved, reviewed: report.review };
     }
     catch (err) {
-        say(`Capture pass error (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        captureSpin.fail("Chat import", `error (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
         return { saved: 0, reviewed: 0 };
     }
 }
 // ----- Step 8: import -----
-async function collectImportPath(opts, rl) {
-    if (opts.importExport)
+async function collectImportPath(opts, rl, capture) {
+    // opts.importExport is `string | false | undefined` — Commander writes
+    // `false` when `--no-import-export` was passed, but the caller already
+    // short-circuits in that case. Only a non-empty string is a real path.
+    if (typeof opts.importExport === "string" && opts.importExport.length > 0) {
         return opts.importExport;
+    }
     if (opts.yes)
         return null;
-    const answer = (await ask(rl, "Drop a path to a ChatGPT/Claude/Grok/Gemini export to import now (or `skip`): ", "skip")).trim();
+    // Explain what a path is, where to find the export, why it's optional,
+    // and that ChatGPT is the only inline source — BEFORE the prompt. A beta
+    // user who has never exported a chat archive shouldn't hit a bare
+    // "Drop a path" prompt. The source-sniffer below still fail-fasts a
+    // non-ChatGPT export, but the friend learns the boundary earlier here.
+    //
+    // The "skipping is fine" reassurance MUST match what will actually happen.
+    // Auto-capture is OFF by default, AND can be configured-on-but-not-running
+    // when the Codex preflight failed — promising "new chats get captured
+    // automatically" in either case is the exact trust break this flow removes.
+    // Only promise it when capture will genuinely run; otherwise point at the
+    // real next step (fix Codex if configured, or enable it if off).
+    const whySkip = capture.willRun
+        ? "skipping is fine — new chats get captured automatically."
+        : capture.configured
+            ? "skipping is fine — import later with `rift import` (auto-capture is on but won't run until Codex is ready — see above)."
+            : "skipping is fine — import later with `rift import`, or turn on auto-capture with `rift onboard --enable-capture`.";
+    ui.detail([
+        "Import past chats (optional)",
+        "• What: the file path to a ChatGPT data export (a .zip or .json on your Mac), e.g. ~/Downloads/chatgpt-export.zip.",
+        "• Where: chatgpt.com → Settings → Data controls → Export data, then unzip nothing — just drop the downloaded file's path here.",
+        `• Why: this seeds Rift with your existing ChatGPT history so search works on day one; ${whySkip}`,
+        "• Other tools: Claude/Grok/Gemini exports aren't imported here. Run them later with: rift import <path> --source claude_web|grok_web|gemini_web",
+    ].join("\n"));
+    const answer = (await ask(rl, "Path to a ChatGPT export to import now (or `skip`): ", "skip")).trim();
     if (!answer || answer.toLowerCase() === "skip")
         return null;
     return answer;
@@ -606,18 +1217,27 @@ async function runImport(filePath, configPath) {
         return { kind: "skipped", reason: "unsupported extension" };
     }
     const baseUrl = safeResolveBaseUrl(configPath);
-    const token = await ensureToken(configPath);
-    if (!baseUrl || !token) {
+    const tokenResult = await ensureToken(configPath);
+    if (!baseUrl || !tokenResult.ok) {
         say("Daemon not reachable — cannot import.");
         return { kind: "skipped", reason: "daemon not reachable" };
     }
-    const client = createHttpClient({ baseUrl, token });
+    const client = createHttpClient({ baseUrl, token: tokenResult.token });
     const buf = fs.readFileSync(absolute);
+    // Fail-fast for non-ChatGPT exports: route them to `rift import` with
+    // the right `--source` flag instead of silently feeding them through
+    // the ChatGPT parser. Returns null on "looks like ChatGPT or unknown,"
+    // a concrete provider otherwise.
+    const sniffed = sniffInboxSource(path.basename(absolute), buf);
+    if (sniffed) {
+        say(`Detected a ${sniffed} export — the inline importer is ChatGPT-only.`);
+        say(`Run: rift import "${absolute}" --source ${sniffed}`);
+        return { kind: "skipped", reason: `non-chatgpt export detected: ${sniffed}` };
+    }
     const form = new FormData();
     form.append("source", ONBOARD_INLINE_IMPORT_SOURCE);
     form.append("file", new Blob([buf]), path.basename(absolute));
     say(`Importing ${path.basename(absolute)} as ${ONBOARD_INLINE_IMPORT_SOURCE}…`);
-    say("(For Claude/Grok/Gemini exports, run: rift import <path> --source <name>)");
     const { data } = await client.postMultipart("/ingest", form);
     const resp = data;
     if (resp.duplicate) {
@@ -634,14 +1254,22 @@ async function runImport(filePath, configPath) {
     return { kind: "imported", jobId: resp.job_id };
 }
 /**
- * Pure outcome decision for the next-action card. Onboarding is only
- * "complete" when this run actually ingested user data AND a recall
- * query against the freshly-ingested data returned at least one hit.
- * Smoke is non-indexing (see daemonRefreshFlow), so any hit is real
- * user data, not a leftover probe.
+ * Pure outcome decision for the next-action card.
+ *
+ * "Complete + verified" needs both: this run ingested user data AND a recall
+ * query returned a hit (smoke is non-indexing — see daemonRefreshFlow — so a
+ * hit is real user data, not a leftover probe).
+ *
+ * But an EMPTY archive is not a failure. By default capture is OFF (zero-Codex
+ * trust default) and import is optional, so a friend who simply presses Enter
+ * past the import prompt has finished a valid setup — they just have nothing to
+ * recall yet. That case (`ingestAttempted === false`) is reported as DONE, not
+ * "incomplete". We only flag a retry when an ingest was actually attempted and
+ * still added nothing.
  */
 export function decideOnboardOutcome(input) {
     const { ingestedAny, recall } = input;
+    const ingestAttempted = input.ingestAttempted ?? false;
     if (ingestedAny && recall.ok && recall.hits > 0) {
         return [
             `Setup complete — recall returned ${recall.hits} result(s) from your data.`,
@@ -649,16 +1277,27 @@ export function decideOnboardOutcome(input) {
         ];
     }
     if (!ingestedAny) {
+        if (!ingestAttempted) {
+            // Deliberate empty setup — a finished, valid state, not a failure.
+            return [
+                "Setup complete — nothing imported yet.",
+                "Import later: rift import <path> --source <name>",
+                "Next: rift mcp install --client=claude-desktop",
+            ];
+        }
+        // An ingest ran but landed nothing — honest, calm retry guidance.
         return [
-            "Setup incomplete — no user data was captured or imported during onboarding.",
-            "Next: drop an export at the prompt above and re-run rift onboard,",
-            "      or run: rift import <path> --source <name>",
+            "Setup ready — but capture/import added nothing this run.",
+            "Try: rift import <path> --source <name>",
+            "If it repeats: rift feedback --kind=broke --with-status",
         ];
     }
     if (recall.ok) {
         return [
-            "Setup partially complete — capture+import succeeded but search returned 0 hits.",
-            "Next: rift feedback --kind=broke --with-status \"first-recall returned 0\"",
+            "Setup ready — capture+import succeeded but the generic recall query returned 0 hits.",
+            "Indexing may still be in flight, or this query just didn't match your archive yet.",
+            "Try: rift search \"<a topic you remember discussing>\"",
+            "If repeated tries still return nothing, run: rift feedback --kind=broke --with-status",
         ];
     }
     return [
@@ -669,28 +1308,44 @@ export function decideOnboardOutcome(input) {
 // ----- Step 9: first-recall verification -----
 async function firstRecallCheck(configPath) {
     const baseUrl = safeResolveBaseUrl(configPath);
-    const token = await ensureToken(configPath);
-    if (!baseUrl || !token) {
+    const tokenResult = await ensureToken(configPath);
+    if (!baseUrl || !tokenResult.ok) {
         return { ok: false, reason: "daemon not reachable" };
     }
-    const client = createHttpClient({ baseUrl, token });
+    const client = createHttpClient({ baseUrl, token: tokenResult.token });
     // Generic, content-bearing query — likely to land on captured CLI
     // sessions or imported chat exports without targeting any onboarding
     // marker. The smoke is non-indexing (see daemonRefreshFlow), so any
     // hit returned here is real user data, not a leftover probe.
-    try {
-        const { data } = await client.post("/search", {
-            query: "recent conversation",
-            scope: "all",
-            top_k: 10,
-        });
-        const body = data;
-        const hits = (body.results?.length ?? body.hits?.length ?? 0);
-        return { ok: true, hits };
-    }
-    catch (err) {
-        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    //
+    // Small unusual imports (e.g. one short Claude project export) can
+    // return 0 hits for this generic query even when the data was
+    // indexed correctly. Retry briefly so the post-onboard nudge isn't a
+    // false alarm on slow embedders / sparse archives.
+    const RECALL_RETRY_DELAYS_MS = [0, 5_000];
+    let lastErr = null;
+    for (const delay of RECALL_RETRY_DELAYS_MS) {
+        if (delay > 0)
+            await new Promise((r) => setTimeout(r, delay));
+        try {
+            const { data } = await client.post("/search", {
+                query: "recent conversation",
+                scope: "all",
+                top_k: 10,
+            });
+            const body = data;
+            const hits = (body.results?.length ?? body.hits?.length ?? 0);
+            if (hits > 0)
+                return { ok: true, hits };
+            lastErr = null;
+        }
+        catch (err) {
+            lastErr = err instanceof Error ? err.message : String(err);
+        }
     }
+    if (lastErr)
+        return { ok: false, reason: lastErr };
+    return { ok: true, hits: 0 };
 }
 // ----- Slice 6: --reconfigure-voyage -----
 /**
@@ -795,13 +1450,14 @@ function say(line) {
     process.stdout.write(line + "\n");
 }
 function sayPrivacyContract() {
-    say([
-        "  • Conversation content stays local (LanceDB + raw transcripts).",
-        "  • Content snippets leave the machine for embedding only (Voyage AI).",
-        "  • The Voyage key sits in ~/.rift.env (mode 0600). Never logged, never sent to Clem.",
-        "  • Feedback is stored locally as JSONL. Relay is opt-in: explicit notes only,",
-        "    plus daemon health booleans — no paths, no content, no key bytes.",
-        "  • Full contract: docs/feedback/PRIVACY.md",
+    ui.detail([
+        "• Conversation content stays local (LanceDB + raw transcripts).",
+        "• Content snippets leave the machine for embedding only (Voyage AI).",
+        "• The Voyage key sits in ~/.rift.env (mode 0600), is sent only to Voyage,",
+        "  and is never logged or sent to Clem.",
+        "• Feedback is stored locally as JSONL. Relay is opt-in: explicit notes only,",
+        "  plus daemon health booleans — no paths, no content, no key bytes.",
+        "• Full contract: https://getrift.dev/privacy",
     ].join("\n"));
 }
 function safeDiscover(fn) {