onadit 0.0.1 → 1.0.0

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

@@ -0,0 +1,1873 @@
+/**
+ * `onadit onboard` — first-run wizard.
+ *
+ * Walks a friend from "fresh install + Voyage key in hand" to "first
+ * useful recall against their freshly-imported data". Step ordering
+ * matches Slice 4 in the friend-beta plan; each step is idempotent and
+ * `--yes` accepts every prompt's default.
+ *
+ * Flags worth pointing out:
+ *   --voyage-key <key>        non-interactive key entry
+ *   --voyage-label <label>    operator-supplied display label (no inference)
+ *   --enable-feedback-relay <url>
+ *                             opt into the Clem-side relay non-interactively
+ *   --import-export <path>    import an export inline; `--no-import-export`
+ *                             skips the prompt entirely
+ *   --reconfigure-voyage      Slice 6 recovery flow — skip everything
+ *                             except validate + write key + kickstart + smoke
+ *   --yes                     accept all defaults (used by install scripts)
+ *   --skip-capture            suppress the post-onboarding capture pass
+ *                             (useful in tests / CI dry-runs)
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+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";
+import { defaultRiftEnvPath, loadRiftEnv, } from "../../runtime/rift-env.js";
+import { resolveVoyageKeySource, readSavedVoyageKey, voyageKeySourceLines, } from "../../runtime/voyage-key-source.js";
+import { runLegacyMigration } from "../../runtime/legacy-migration.js";
+import { sanitizeProjectLabel } from "../../runtime/legacy-name-guard.js";
+import { validateVoyageKey } from "../../onboarding/voyage-validate.js";
+import { useVoyageOwnEndpoint } from "../../onboarding/search-by-meaning.js";
+import { writeCaptureEnabled } from "../../onboarding/capture-switch.js";
+import { writeEnvFile } from "../../onboarding/env-file.js";
+import { kickstartDaemon, waitForHealth, } from "../../onboarding/daemon-control.js";
+import { runAutoCapture, resolveCodexCaptureDeps, resolveCursorCaptureDeps, } from "../../capture/auto-capture.js";
+import { appendAutoCaptureRunRecord, buildAutoCaptureRunRecord, } from "../../capture/observability.js";
+import { DEFAULT_AUTO_CAPTURE_SOURCES, CLAUDE_DESKTOP_CAPTURE_SOURCE, CURSOR_CAPTURE_SOURCE, } from "../../capture/sources.js";
+import { createTriageProvider, resolveTriageProviderName, setConfiguredTriageProviderName, triageWorkerLabel, } from "../../capture/triage-provider-factory.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;
+}
+/**
+ * True when this `onadit onboard` invocation asks to CHANGE something — set a key,
+ * enable a lane, import, opt into feedback, install a hook. Absence marks a
+ * "passive" re-run (the user just ran the command again), which on an
+ * already-onboarded install should report state instead of redoing first-time
+ * setup or gating on the stored Voyage key. `--yes`, `--skip-capture`, and the
+ * `--no-*` declines are NOT mutations; `--reconfigure-voyage` has its own flow
+ * and is handled before this is consulted.
+ *
+ * Exported for testing — it gates the idempotent short-circuit in `runOnboard`.
+ */
+export function hasOnboardMutationIntent(opts) {
+    return ((typeof opts.voyageKey === "string" && opts.voyageKey.trim().length > 0) ||
+        opts.voyageLabel !== undefined ||
+        opts.enableCapture === true ||
+        opts.enableCoworkCapture === true || opts.enableGrokCapture === true ||
+        opts.enableCodexEnrichment === true ||
+        opts.enableClaudeEnrichment === true ||
+        (typeof opts.importExport === "string" && opts.importExport.length > 0) ||
+        opts.invite !== undefined ||
+        opts.enableFeedbackRelay !== undefined ||
+        opts.email !== undefined ||
+        opts.withClaudeHook === true);
+}
+const SUPPORTED_INGEST_EXTENSIONS = new Set([".json", ".zip"]);
+const DEFAULT_DATA_DIR = path.join(os.homedir(), "Library", "Application Support", "Rift", // rename:keep data folder name
+"data");
+// Inline import is intentionally narrow until Slice 3 lands the real
+// `onadit import` flow with structural sniffing per source. ChatGPT exports
+// are the most common friend handoff and we route them straight through.
+const ONBOARD_INLINE_IMPORT_SOURCE = "chatgpt_web";
+/** Only explicit feature opt-ins open the longer configuration flow. */
+export function usesAdvancedOnboarding(opts) {
+    return opts.advanced === true || opts.reconfigureVoyage === true ||
+        (typeof opts.voyageKey === "string" && !!opts.voyageKey.trim()) ||
+        opts.voyageLabel !== undefined || opts.enableCapture === true ||
+        opts.enableCoworkCapture === true || opts.enableGrokCapture === true || opts.enableCodexEnrichment === true ||
+        opts.enableClaudeEnrichment === true || opts.invite !== undefined ||
+        opts.enableFeedbackRelay !== undefined || opts.email !== undefined ||
+        opts.withClaudeHook === true;
+}
+export function makeOnboardCommand() {
+    return new Command("onboard")
+        .description("Add an archive, find a memory, connect your AI tool")
+        .option("--query <words>", "Find a real topic after import")
+        .addOption(new Option("--source <name>", "Archive source (detected when possible)").choices(["chatgpt_web", "claude_web", "gemini_web", "grok_web"]))
+        .addOption(new Option("--client <name>", "Connect this AI tool after recall").choices(["claude-desktop", "claude-code", "codex", "cursor"]))
+        .option("--advanced", "Configure optional cloud search, capture, and feedback", false)
+        .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 Onadit 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 product 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 triage-worker preflight + disable the capture pass for this run")
+        .option("--with-claude-hook", "Install the Onadit 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-claude-enrichment", "Opt into Claude Code AI metadata enrichment (digests/compaction stay off until Claude digest support ships; mutually exclusive with --enable-codex-enrichment)", false)
+        .option("--enable-capture", "Opt into scheduled chat capture + its triage-worker preflight (Codex by default, or Claude Code via capture.triage.provider; default: capture off, zero AI-worker calls)", false)
+        .option("--enable-grok-capture", "Opt into existing and future Grok CLI sessions (adds grok_cli to capture.sources and enables scheduled capture)")
+        .option("--enable-cowork-capture", "Opt into Claude Desktop agent/Cowork capture (adds claude_desktop_sessions to capture.sources and enables scheduled capture)", false)
+        .action(async (opts, cmd) => {
+        const globalOpts = cmd.optsWithGlobals();
+        try {
+            if (usesAdvancedOnboarding(opts))
+                await runOnboard(opts, globalOpts);
+            else {
+                const { runFirstRun } = await import("./onboard-first-run.js");
+                await runFirstRun(opts, globalOpts);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof CliError
+                ? err.message
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            process.stderr.write(`onboard failed: ${msg}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+// 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,
+        terminal: !!process.stdin.isTTY,
+    });
+    try {
+        // Fail fast, before any config write: the two enrichment opt-ins pick
+        // different metadata workers (Codex vs Claude), so passing both is an
+        // ambiguous request, not a mergeable one. Reject it up front rather than
+        // letting last-writer-wins silently decide which provider you got.
+        if (opts.enableCodexEnrichment === true && opts.enableClaudeEnrichment === true) {
+            throw new CliError("Pass only one of --enable-codex-enrichment or --enable-claude-enrichment — they select different metadata workers.", "validation");
+        }
+        if (opts.reconfigureVoyage) {
+            await reconfigureVoyageFlow(opts, globalOpts, rl);
+            return;
+        }
+        // Idempotent re-run. An already-onboarded install + a passive invocation
+        // (no flag asking to change anything) + a Voyage key already on disk must
+        // NOT redo first-time setup or GATE on that stored key. Re-validating the
+        // saved key as a first-time gate is exactly the beta.25 bug: a re-run on an
+        // expired key ended with "onboard failed". Instead, report "already set up"
+        // with a NON-FATAL key health check and exit clean. A keyword-only install
+        // (no key) falls through so the normal flow can still offer to add one.
+        if (!hasOnboardMutationIntent(opts)) {
+            const absoluteConfig = path.resolve(globalOpts.config);
+            const onboarded = readOnboardedState(absoluteConfig);
+            const keyRes = resolveOnboardVoyageKeySource(absoluteConfig);
+            if (onboarded && keyRes.key) {
+                await reportAlreadyOnboarded(keyRes);
+                return;
+            }
+        }
+        ui.banner();
+        // Step 1 — legacy migration (idempotent).
+        const dataDir = await ensureConfigAndDataDir(globalOpts.config, opts, rl);
+        const migration = await runLegacyMigration({ dataDir });
+        if (migration.migratedCount > 0) {
+            ui.step("ok", "Existing data", `carried over ${migration.migratedCount} item(s)`);
+        }
+        else {
+            ui.step("ok", "Existing data", "nothing to carry over");
+        }
+        // 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.
+        //
+        // A key this install already has stays as it is: the user's own, or the
+        // one Onadit provided (Search by meaning). Asking for a key again made a
+        // lane opt-in (`--enable-capture`) depend on pasting a second one, and a
+        // user on an Onadit-provided key has none to paste. Changing the key is
+        // `--voyage-key` or `--reconfigure-voyage`.
+        const savedLast4 = savedVoyageKeyToKeep(opts, path.resolve(globalOpts.config));
+        if (savedLast4 !== null) {
+            ui.step("ok", "Search index", `using the key already set up · ····${savedLast4}`);
+        }
+        const last4 = savedLast4 ?? (await collectAndPersistVoyageKey(opts, rl));
+        // A pasted key is the user's own Voyage key: stop pointing at the
+        // endpoint of a key Onadit provided earlier (Search by meaning).
+        if (savedLast4 === null && last4 !== null && useVoyageOwnEndpoint(path.resolve(globalOpts.config))) {
+            say("Search index now uses your own Voyage key instead of the one Onadit provided.");
+        }
+        // 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 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);
+        applyClaudeEnrichmentOptIn(opts.enableClaudeEnrichment, 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 || opts.enableCoworkCapture === true || opts.enableGrokCapture === true;
+        const captureEnabled = captureRequested && last4 !== null;
+        if (captureRequested && last4 === null) {
+            const ignoredFlag = opts.enableCoworkCapture === true && opts.enableCapture !== true
+                ? "--enable-cowork-capture"
+                : opts.enableGrokCapture === true && opts.enableCapture !== true
+                    ? "--enable-grok-capture" : "--enable-capture";
+            ui.note(`${ignoredFlag} ignored: capture embeds saved conversations and needs a Voyage key. Re-run \`onadit onboard\` with a key to enable it.`);
+        }
+        else {
+            applyCaptureOptIn(captureRequested, globalOpts.config, say);
+            applyCoworkCaptureOptIn(opts.enableCoworkCapture, globalOpts.config, say);
+            applyGrokCaptureOptIn(opts.enableGrokCapture, 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 — triage-worker 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;
+        // Resolve the configured triage worker so the preflight probes (and labels)
+        // the worker the daemon will actually use, and record it process-wide so
+        // the first-capture pass below inherits the same selection. Unreadable
+        // config falls back to codex_cli — byte-for-byte the prior default.
+        let triageWorkerName = "codex_cli";
+        try {
+            triageWorkerName = resolveTriageProviderName(loadConfig(path.resolve(globalOpts.config)));
+        }
+        catch {
+            triageWorkerName = "codex_cli";
+        }
+        setConfiguredTriageProviderName(triageWorkerName);
+        const workerLabel = triageWorkerLabel(triageWorkerName);
+        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 preflightSpin = new ui.Spinner("Chat access").start();
+            const preflightOk = await triagePreflight(triageWorkerName);
+            if (preflightOk) {
+                preflightSpin.succeed("Chat access", `ready · ${workerLabel}`);
+            }
+            else {
+                preflightSpin.fail("Chat access", `not ready · ${workerLabel} — auto-import off`);
+                ui.note(triageWorkerName === "claude_code"
+                    ? "To enable later: run `claude` once and sign in, then re-run `onadit onboard`."
+                    : "To enable later: run `codex login`, then re-run `onadit 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.
+        const claudeSessions = safeDiscover(() => discoverClaudeCodeSessions(path.join(os.homedir(), ".claude")));
+        const codexSessions = safeDiscover(() => discoverCodexSessions());
+        ui.step("ok", "Chat history", `${claudeSessions} Claude Code · ${codexSessions} Codex CLI`);
+        // Set the expectation honestly up front: auto-capture covers the CLI agents,
+        // not every AI app on the Mac. The Claude/ChatGPT desktop + web apps keep
+        // their history server-side, so those chats arrive via export → onadit import.
+        // `ui.detail` (legible, not dimmed) because this is trust-critical copy.
+        //
+        // The CLI-agent line is gated on `autoCaptureWillRun`: "captured
+        // automatically" is only true once capture is enabled AND the worker
+        // preflight passed. On a default/off or not-ready install (we just printed
+        // "capture off"/"not ready" above) we describe ELIGIBILITY instead, so the
+        // block never contradicts the gate it sits under.
+        const cliAgentsLine = autoCaptureWillRun
+            ? "  • Claude Code + Codex CLI — captured automatically\n"
+            : "  • Claude Code + Codex CLI — eligible for auto-capture once capture is enabled and chat access is ready\n";
+        ui.detail("Auto-capture covers your terminal AI agents — not every AI app on your Mac:\n" +
+            cliAgentsLine +
+            "  • Cursor — only if you turn it on (add cursor_composer to capture.sources)\n" +
+            "  • Grok CLI sessions — opt in with: onadit onboard --enable-grok-capture (existing and future sessions)\n" +
+            "  • Claude Desktop Cowork / agent sessions — opt in with: onadit onboard --enable-cowork-capture\n" +
+            "  • Claude Desktop normal chats / ChatGPT / web chats — NOT automatic; export them, then:\n" +
+            "      onadit import <file> --source claude_web   (or chatgpt_web)");
+        // 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 {
+            ui.step("ok", "Stay connected", "skipped — nothing shared, feedback stays local");
+        }
+        // Step 5b — optional Claude Code policy hook.
+        await maybeInstallClaudeCodeHook(opts, rl);
+        // Step 6 + 7 — watermark current sessions + run one capture pass.
+        let captureSaved = 0;
+        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 {
+            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.
+        let importSucceeded = false;
+        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,
+                workerLabel,
+            });
+            if (importPath) {
+                importAttempted = true;
+                const outcome = await runImport(importPath, globalOpts.config);
+                if (outcome.kind === "imported" || outcome.kind === "duplicate") {
+                    importSucceeded = true;
+                }
+            }
+            else {
+                ui.step("skip", "File import", "none — run `onadit import <path> --source <name>` later");
+            }
+        }
+        // Step 9 — first-recall verification.
+        // 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;
+        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.
+        const card = decideOnboardOutcome({ ingestedAny, recall, ingestAttempted });
+        card.push(ui.pc.dim(last4 !== null
+            ? `Voyage: key ${savedLast4 !== null ? "already set up" : "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 Onadit keeps
+        // itself fed. Three honest states: ready (configured + worker available),
+        // configured-but-not-ready (preflight failed — don't claim it's running),
+        // and off (the default). Capture is off by default (zero-egress 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 — ${workerLabel} isn't available (${triageWorkerName === "claude_code"
+                    ? "run `claude` and sign in"
+                    : "run `codex login`"}).`
+                : "Auto-capture: off — enable with: onadit onboard --enable-capture"));
+        ui.box(card);
+        ui.line("");
+    }
+    finally {
+        rl.close();
+    }
+}
+// ----- Idempotent re-run: "already set up" report -----
+/**
+ * An install is "already onboarded" once its config.json exists and the data
+ * dir it points at is present. Returns the data dir, or null when this looks
+ * like a fresh install (no config, unreadable config, or a missing data dir) —
+ * in which case the caller runs the normal first-time flow.
+ */
+function readOnboardedState(absoluteConfig) {
+    if (!fs.existsSync(absoluteConfig))
+        return null;
+    try {
+        const cfg = loadConfig(absoluteConfig);
+        const dataDir = cfg.data_paths.data_dir;
+        return fs.existsSync(dataDir) ? { dataDir } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the key an installed Onadit CLI would use for an already-onboarded
+ * report — AND where it came from. The shell `$VOYAGE_API_KEY` wins (it
+ * overrides in-process checks); the saved `~/.rift.env` is read only when the
+ * config path is the canonical installed Onadit config under that same home, so
+ * custom/test `--config` runs never read the developer machine's real env file.
+ * When both exist and differ, the resolution flags the shadow so we can warn.
+ */
+function resolveOnboardVoyageKeySource(absoluteConfig) {
+    const shellKey = (process.env["VOYAGE_API_KEY"] ?? "").trim() || null;
+    const homeDir = homeDirForInstalledRiftConfig(absoluteConfig);
+    const fileKey = homeDir ? readSavedVoyageKey(defaultRiftEnvPath(homeDir)) : null;
+    return resolveVoyageKeySource(shellKey, fileKey);
+}
+/**
+ * Last-4 of the Voyage key already saved for this install, when this run
+ * should keep using it: no key was passed to replace it, and the shell does
+ * not export a different one. Null otherwise, and the key step runs as usual.
+ * The key is not re-validated here: the engine's own health check after the
+ * restart says whether it loaded one.
+ */
+function savedVoyageKeyToKeep(opts, absoluteConfig) {
+    if (typeof opts.voyageKey === "string" && opts.voyageKey.trim())
+        return null;
+    const homeDir = homeDirForInstalledRiftConfig(absoluteConfig);
+    const saved = homeDir ? readSavedVoyageKey(defaultRiftEnvPath(homeDir)) : null;
+    if (!saved)
+        return null;
+    const shell = (process.env["VOYAGE_API_KEY"] ?? "").trim();
+    if (shell && shell !== saved)
+        return null;
+    return resolveVoyageKeySource(null, saved).last4;
+}
+function homeDirForInstalledRiftConfig(absoluteConfig) {
+    const suffix = path.join("Library", "Application Support", "Rift", // rename:keep data folder name
+    "data", "config.json");
+    const marker = `${path.sep}${suffix}`;
+    if (!absoluteConfig.endsWith(marker))
+        return null;
+    const homeDir = absoluteConfig.slice(0, -marker.length);
+    return homeDir.length > 0 ? homeDir : null;
+}
+/**
+ * Passive-re-run summary for an already-onboarded install. Validates the stored
+ * Voyage key ONLY to report its health — never to gate. The three outcomes are
+ * all clean exits (this function never throws, which is the whole point):
+ *   - valid    → "you're all set"
+ *   - rejected → "key expired/revoked, replace it" (degraded, not broken)
+ *   - probe error (offline/timeout) → "couldn't check, run doctor if search is off"
+ *
+ * Throwing here is the beta.25 bug: a re-run on an expired key ended the whole
+ * command with "onboard failed" even though the install was fine.
+ *
+ * Exported for testing; `runOnboard` is the only production caller.
+ */
+export async function reportAlreadyOnboarded(keyRes, deps = {}) {
+    const validate = deps.validate ?? validateVoyageKey;
+    ui.step("ok", "Onadit", "already set up");
+    // Be explicit about WHICH key this check used (shell env vs ~/.rift.env) and
+    // warn when a shell value shadows the saved key — so a stale shell export
+    // can't make a healthy install look broken without explanation.
+    for (const line of voyageKeySourceLines(keyRes))
+        ui.note(line);
+    const storedKey = keyRes.key ?? "";
+    const spin = new ui.Spinner("Search index").start();
+    let result;
+    try {
+        result = await validate({ apiKey: storedKey });
+    }
+    catch {
+        // A probe error (offline, timeout) is not a setup failure — the key may be
+        // fine. Don't fail the command; point at doctor for a deeper check.
+        spin.warn("Search index", "couldn't reach Voyage to check the key");
+        ui.note("Your install is set up. If semantic search seems off, run `onadit doctor`.");
+        return;
+    }
+    if (result.ok) {
+        spin.succeed("Search index", `Voyage key valid · ····${result.last4}`);
+        ui.note('You\'re all set. Search: `onadit search "<query>"`. Re-check anytime: `onadit doctor`.');
+        return;
+    }
+    // Key present but rejected (expired/revoked): semantic search is degraded, not
+    // broken. Point to repair; never throw.
+    spin.warn("Search index", "stored Voyage key was rejected");
+    ui.note("Your install is set up, but Voyage rejected the saved key (expired or revoked). " +
+        "Semantic search is degraded until you replace it:\n" +
+        "  • Replace the key:  onadit onboard --reconfigure-voyage\n" +
+        "  • Diagnose search:  onadit doctor");
+}
+// ----- Step 1: config.json + data dir -----
+export 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);
+        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;
+    const dataDir = opts.yes
+        ? defaultDataDir
+        : (await ask(rl, `Data dir [${defaultDataDir}]: `, defaultDataDir)).trim() ||
+            defaultDataDir;
+    fs.mkdirSync(dataDir, { recursive: true });
+    const inboxDir = path.join(dataDir, "inbox");
+    fs.mkdirSync(inboxDir, { recursive: true });
+    const config = {
+        sources: [
+            {
+                path: inboxDir,
+                extraction: "cloud",
+                mode: "watch",
+                scope: "project",
+            },
+        ],
+        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 },
+        // 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,
+    });
+    ui.step("ok", "Settings", `wrote default · ${shownConfig}`);
+    ui.note(`data dir: ${dataDir}`);
+    // Trigger ensureDirectories.
+    loadConfig(absoluteConfig);
+    return dataDir;
+}
+// ----- Step 2a: persist --voyage-label to config.json -----
+/**
+ * Sanitize a raw `--voyage-label`, persist it when valid, and return the
+ * string the caller should use for display. Invalid labels are dropped
+ * with a generic notice that never echoes the raw value — so a
+ * key-shaped, path-shaped, or legacy-name-shaped label cannot leak
+ * through stdout or `config.json`. Returns `null` when the input was
+ * absent or rejected.
+ *
+ * Exported for orchestrator-level tests; `runOnboard` is the only
+ * production caller.
+ */
+export function applyVoyageLabel(rawLabel, configPath, emit) {
+    if (rawLabel === undefined)
+        return null;
+    const sanitized = sanitizeProjectLabel(rawLabel);
+    if (!sanitized) {
+        // Generic message: never echo the raw value. Anything we say here
+        // also has to land in the friend's terminal, so it must not name
+        // the rejected token.
+        emit("Ignoring --voyage-label: must be 1–32 chars of letters, digits, '-' or '_' " +
+            "(no paths, secrets, or legacy product names).");
+        return null;
+    }
+    persistVoyageLabel(configPath, sanitized);
+    emit(`Stored Voyage label: ${sanitized}`);
+    return sanitized;
+}
+/**
+ * Merge `voyage.project_label` into the config file. The file is
+ * backed up to `<file>.bak.<iso>` first so an interrupted write or a
+ * future operator typo can be undone. Display only — never sent to the
+ * relay, never inferred from the key bytes.
+ *
+ * Defensively re-runs `sanitizeProjectLabel` even though the standard
+ * `applyVoyageLabel` caller has already validated: a future programmer
+ * who reaches for this export directly still cannot land an unsafe
+ * string in the file.
+ */
+export function persistVoyageLabel(configPath, label) {
+    const sanitized = sanitizeProjectLabel(label);
+    if (!sanitized) {
+        throw new CliError("Refusing to persist Voyage label: not a valid label " +
+            "(1–32 chars of letters, digits, '-' or '_'; no paths, secrets, or legacy names).", "validation");
+    }
+    const absolute = path.resolve(configPath);
+    if (!fs.existsSync(absolute)) {
+        // ensureConfigAndDataDir always writes config.json before this runs;
+        // a missing file here means the caller bypassed step 1.
+        throw new CliError(`Cannot persist Voyage label: 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 voyage = parsed["voyage"] ?? {};
+    voyage["project_label"] = sanitized;
+    parsed["voyage"] = voyage;
+    const tmp = `${absolute}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(parsed, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o644,
+    });
+    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 AND pins `enrichment.metadata.provider = "codex_cli"` so
+ * the daemon/worker select the Codex-backed extractor — overriding any prior
+ * `claude_code` pin rather than silently leaving Claude selected. 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;
+    // Pin the metadata worker to Codex explicitly. Setting only `ai_metadata`
+    // would leave a pre-existing `metadata.provider = "claude_code"` in place, so
+    // "use Codex" would silently keep routing metadata through Claude (and keep
+    // digests off). Codex opt-in must win the provider selection, not just the gate.
+    const metadata = enrichment["metadata"] ?? {};
+    metadata["provider"] = "codex_cli";
+    enrichment["metadata"] = metadata;
+    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, metadata.provider = codex_cli).");
+    return true;
+}
+/**
+ * Persist the Claude-Code AI-metadata-enrichment opt-in into config.json. Like
+ * `applyCodexEnrichmentOptIn` it flips `enrichment.ai_metadata = true`, but it
+ * ALSO pins `enrichment.metadata.provider = "claude_code"` so the daemon/worker
+ * route metadata through the `claude` CLI instead of Codex. Backs the file up
+ * first, mirroring the Codex opt-in. Callers must reject the combination of
+ * both enrichment flags before reaching here (see `runOnboard`).
+ *
+ * Discloses the one capability this does NOT turn on: there is no Claude digest
+ * worker yet and we will not silently borrow Codex for it, so digests/
+ * compaction stay off until a dedicated digest-provider slice ships. Saying so
+ * here prevents a silent capability loss for a user who switches to Claude.
+ *
+ * Exported for orchestrator-level tests; `runOnboard` is the only production
+ * caller. Returns true when the flag was set and persisted, false otherwise.
+ */
+export function applyClaudeEnrichmentOptIn(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;
+    const metadata = enrichment["metadata"] ?? {};
+    metadata["provider"] = "claude_code";
+    enrichment["metadata"] = metadata;
+    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("Claude metadata enrichment enabled. Digests/compaction stay off until Claude digest support ships.");
+    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");
+    }
+    writeCaptureEnabled(absolute, true);
+    emit("Scheduled chat capture enabled (capture.enabled = true).");
+    return true;
+}
+/**
+ * Persist the Claude Desktop agent/Cowork capture opt-in into config.json.
+ * This adds `claude_desktop_sessions` to `capture.sources` without making it a
+ * default for fresh installs. Existing Cowork history is still privacy-safe:
+ * the first capture run bootstraps/watermarks already-present sessions instead
+ * of importing them as new.
+ *
+ * Exported for focused tests; `runOnboard` is the production caller.
+ */
+export function applyCoworkCaptureOptIn(enable, configPath, emit) {
+    if (enable !== true)
+        return false;
+    const absolute = path.resolve(configPath);
+    if (!fs.existsSync(absolute)) {
+        throw new CliError(`Cannot persist Cowork 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"] ?? {};
+    const currentSources = Array.isArray(capture["sources"])
+        ? capture["sources"].filter((s) => typeof s === "string" &&
+            (s === "claude_code" ||
+                s === "codex_cli" ||
+                s === CURSOR_CAPTURE_SOURCE ||
+                s === CLAUDE_DESKTOP_CAPTURE_SOURCE || s === "grok_cli"))
+        : [...DEFAULT_AUTO_CAPTURE_SOURCES];
+    if (!currentSources.includes(CLAUDE_DESKTOP_CAPTURE_SOURCE)) {
+        currentSources.push(CLAUDE_DESKTOP_CAPTURE_SOURCE);
+    }
+    capture["sources"] = currentSources;
+    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("Claude Desktop Cowork capture enabled (capture.sources includes claude_desktop_sessions). Existing Cowork sessions are baselined on first run; new sessions are captured after that.");
+    return true;
+}
+export function applyGrokCaptureOptIn(enable, configPath, emit) {
+    if (enable !== true)
+        return false;
+    const absolute = path.resolve(configPath);
+    if (!fs.existsSync(absolute)) {
+        throw new CliError(`Cannot persist Grok CLI 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"] ?? {};
+    const currentSources = Array.isArray(capture["sources"])
+        ? capture["sources"].filter((s) => typeof s === "string" &&
+            (s === "claude_code" ||
+                s === "codex_cli" ||
+                s === CURSOR_CAPTURE_SOURCE ||
+                s === CLAUDE_DESKTOP_CAPTURE_SOURCE || s === "grok_cli"))
+        : [...DEFAULT_AUTO_CAPTURE_SOURCES];
+    if (!currentSources.includes("grok_cli")) {
+        currentSources.push("grok_cli");
+    }
+    capture["sources"] = currentSources;
+    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("Grok CLI capture enabled (capture.sources includes grok_cli). Existing and future local CLI sessions are captured. Grok Bot is not captured.");
+    return true;
+}
+// ----- Step 2: Voyage key flow -----
+async function collectAndPersistVoyageKey(opts, rl) {
+    const key = await collectVoyageKey(opts, rl);
+    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 `onadit 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");
+    }
+    validateSpin.succeed("Search index", `connected · Voyage · ····${validation.last4}`);
+    const envPath = defaultRiftEnvPath();
+    const writeResult = writeEnvFile({ filePath: envPath, key: "VOYAGE_API_KEY", value: key });
+    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 });
+    // 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;
+}
+/**
+ * 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();
+    // Non-interactive with no key supplied: finish in lexical mode rather than
+    // fail. The friend can run `onadit 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 Onadit 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
+ * VOYAGE_API_KEY loaded. The smoke is fully non-indexing — `/health`
+ * exposes `voyage_key_present` so we never write a row to LanceDB just to
+ * prove the daemon read its env file. That keeps first-recall results
+ * free of an "onboarding probe" hit that would otherwise satisfy the
+ * completion check without any real user data being present.
+ */
+async function daemonRefreshFlow(globalOpts) {
+    const baseUrl = safeResolveBaseUrl(globalOpts.config);
+    if (!baseUrl) {
+        ui.step("skip", "Onadit 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("Onadit service").start();
+    const kick = await kickstartDaemon();
+    if (kick.status === "agent_not_loaded") {
+        daemonSpin.fail("Onadit 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("Onadit service", "kickstart failed");
+        return {
+            ok: false,
+            reason: kick.hint ?? "kickstart failed",
+            kind: "kickstart_failed",
+        };
+    }
+    const health = await waitForHealth({ baseUrl });
+    if (!health.ok) {
+        daemonSpin.fail("Onadit service", "health check failed");
+        return { ok: false, reason: health.reason, kind: "health_failed" };
+    }
+    if (!health.voyageKeyPresent) {
+        daemonSpin.fail("Onadit service", "voyage_key_present=false after kickstart");
+        return {
+            ok: false,
+            reason: "Daemon /health reports voyage_key_present=false after kickstart.",
+            kind: "smoke_failed",
+        };
+    }
+    daemonSpin.succeed("Onadit service", `healthy · daemon · uptime ${health.uptimeSeconds}s`);
+    return { ok: true, kickstarted: true };
+}
+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");
+        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 (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 `onadit 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 `onadit 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 `onadit onboard`.";
+    }
+    return "re-run `onadit onboard`. If the failure repeats, run `onadit feedback --kind=broke --with-status` to ship a diagnostic bundle.";
+}
+// ----- Step 3: triage-worker preflight -----
+/**
+ * Live triage probe for the CONFIGURED worker (Codex CLI by default, or Claude
+ * Code when `capture.triage.provider = claude_code`). Routing through the
+ * factory — not a hardcoded CodexCliTriageProvider — is what stops a Claude
+ * Code user who deliberately picked `claude_code` from being failed by a Codex
+ * probe they never asked for.
+ */
+async function triagePreflight(name) {
+    try {
+        await createTriageProvider(name, { timeoutMs: 120_000 }).triage({
+            content: "User: Onadit onboarding preflight.\n\nAssistant: Ready.",
+        });
+        return true;
+    }
+    catch {
+        return 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;
+    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;
+        }
+    }
+    // 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 `onadit 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 `onadit 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.");
+            }
+        }
+    }
+    // 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 (onadit 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 `onadit 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;
+        }
+    }
+    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", {
+        encoding: "utf8",
+        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, and pricing once we set it.",
+        "• Gives you a direct line to send feedback any time via `onadit 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 Onadit policy hook into Claude Code's settings.
+ *
+ * Only runs when `~/.claude/settings.json` looks plausible (the dir
+ * exists). Honors `--with-claude-hook` (force install, no prompt) and
+ * `--no-claude-hook` (skip silently). Default `--yes` declines unless
+ * `--with-claude-hook` is also set, so non-interactive operators never
+ * silently get a global hook installed.
+ *
+ * Failures are non-fatal — onboarding continues. The hook is a quality
+ * guardrail, not a correctness requirement.
+ */
+async function maybeInstallClaudeCodeHook(opts, rl) {
+    if (isOff(opts, "claudeHook", "noClaudeHook")) {
+        return;
+    }
+    const homeDir = os.homedir();
+    const claudeDir = path.join(homeDir, ".claude");
+    const claudeCodeDetected = fs.existsSync(claudeDir);
+    if (!claudeCodeDetected) {
+        return;
+    }
+    let install = false;
+    if (opts.withClaudeHook) {
+        install = true;
+    }
+    else if (opts.yes) {
+        // Non-interactive default: skip. Operator must opt in with --with-claude-hook.
+        ui.step("skip", "Claude Code", "skipped (pass --with-claude-hook to install non-interactively)");
+        return;
+    }
+    else {
+        ui.note([
+            "Claude Code detected.",
+            "Optional: install a PreToolUse policy hook so Onadit retrieval starts with onadit_context_pack",
+            "(prevents broad onadit_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) {
+        ui.step("skip", "Claude Code", "not installed");
+        return;
+    }
+    try {
+        const outcome = writeHookConfig({
+            client: "claude-code",
+            homeDir,
+            dryRun: false,
+        });
+        if (outcome.hookEntryAdded) {
+            ui.step("ok", "Claude Code", "connected · auto-recall hook added");
+        }
+        else if (outcome.hookEntryReplaced || outcome.scriptUpdated) {
+            ui.step("ok", "Claude Code", "updated");
+        }
+        else {
+            ui.step("ok", "Claude Code", "already up-to-date");
+        }
+        if (outcome.backupId) {
+            ui.note(`backup ID: ${outcome.backupId}`);
+        }
+        ui.note("(Restart Claude Code or open /hooks once for the new entry to load.)");
+    }
+    catch (err) {
+        if (err instanceof HooksParseFailedError) {
+            ui.step("fail", "Claude Code", err.message);
+        }
+        else {
+            ui.step("fail", "Claude Code", `install failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+// ----- Step 6 + 7: capture pass -----
+export async function runFirstCapturePass(configPath, dataDir) {
+    const baseUrl = safeResolveBaseUrl(configPath);
+    if (!baseUrl) {
+        ui.step("skip", "Chat import", "daemon not reachable — skipped");
+        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 `onadit 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 `onadit 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 `onadit token issue` manually, then re-run `onadit onboard`.");
+        }
+        process.exitCode = 1;
+        return { saved: 0, reviewed: 0, fatal: true };
+    }
+    const token = tokenResult.token;
+    const client = createHttpClient({ baseUrl, token });
+    let codexCaptureDeps = {};
+    let cursorCaptureDeps = {};
+    // Onboarding is a config-driven capture path, so it must honor the Cursor
+    // opt-in exactly like the daemon: if `cursor_composer` is in
+    // `config.capture.sources`, this first pass authorizes Cursor discovery +
+    // persistence WITHOUT the env flags (which exist only for ad-hoc dogfood
+    // runs). Without this, onboarding would record cursor_composer in its ledger
+    // row yet runAutoCapture would treat Cursor as disabled — capturing nothing.
+    let cursorConfigEnabled = false;
+    let enabledSources = DEFAULT_AUTO_CAPTURE_SOURCES;
+    // Worker name for the honest preflight-failed warning below (defaults to the
+    // codex_cli label until config resolves).
+    let captureWorkerLabel = triageWorkerLabel("codex_cli");
+    try {
+        const { loadConfig } = await import("../../config/loader.js");
+        const cfg = loadConfig(configPath);
+        // Route this first capture pass through the configured triage worker —
+        // runAutoCapture builds its provider from the process-wide configured name,
+        // so without this a claude_code user's onboarding pass would silently fall
+        // back to Codex. (Step 3 already set it; re-assert here so this function is
+        // correct independent of call order.)
+        const captureWorkerName = resolveTriageProviderName(cfg);
+        setConfiguredTriageProviderName(captureWorkerName);
+        captureWorkerLabel = triageWorkerLabel(captureWorkerName);
+        codexCaptureDeps = resolveCodexCaptureDeps(cfg);
+        cursorCaptureDeps = resolveCursorCaptureDeps(cfg);
+        cursorConfigEnabled = cfg.capture.sources.includes(CURSOR_CAPTURE_SOURCE);
+        enabledSources = cfg.capture.sources;
+    }
+    catch {
+        codexCaptureDeps = {};
+        cursorCaptureDeps = {};
+        cursorConfigEnabled = false;
+    }
+    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,
+            ...cursorCaptureDeps,
+            cursorConfigEnabled,
+            saveFn: async (saveOpts) => {
+                const { data } = await client.post("/save", {
+                    source: saveOpts.source,
+                    summary: saveOpts.summary,
+                    content: saveOpts.content,
+                    topics: saveOpts.topics,
+                    ...(saveOpts.decisions?.length
+                        ? { decisions: saveOpts.decisions, user_statements_seal: saveOpts.user_statements_seal }
+                        : {}),
+                    domain: saveOpts.domain,
+                    idempotency_key: saveOpts.idempotency_key,
+                    ...(saveOpts.replace_idempotency_key
+                        ? { replace_idempotency_key: saveOpts.replace_idempotency_key }
+                        : {}),
+                });
+                const resp = data;
+                if (resp.duplicate)
+                    return;
+                const result = await pollJob({ get: client.get.bind(client), jobId: resp.job_id });
+                if (isJobFailure(result.job, result.timedOut)) {
+                    throw new Error(`Save job failed: ${result.job.error ?? "unknown"}`);
+                }
+            },
+        });
+        // Record this onboard run in the health ledger (best-effort). Without
+        // it, a friend who finishes onboarding and immediately runs `rift
+        // status`/`onadit 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 (triage-worker 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} · ${captureWorkerLabel} 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) {
+        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, 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;
+    // 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 triage-worker 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 the triage worker 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 \`onadit import\` (auto-capture is on but won't run until ${capture.workerLabel} is ready — see above).`
+            : "skipping is fine — import later with `onadit import`, or turn on auto-capture with `onadit 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 Onadit 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: onadit 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;
+}
+/**
+ * Inline import is intentionally narrow: ChatGPT exports only.
+ * Friends importing Claude / Grok / Gemini exports during onboarding
+ * are pointed at the standalone `onadit import <path> --source <name>`
+ * command (Slice 3), which adds structural sniffing per source.
+ */
+export async function runImport(filePath, configPath, source) {
+    const unquoted = filePath.trim().replace(/^(["'])(.*)\1$/, "$2");
+    const absolute = path.resolve(unquoted.startsWith("~/") ? path.join(os.homedir(), unquoted.slice(2)) : unquoted);
+    if (!fs.existsSync(absolute)) {
+        say(`Import file not found: ${absolute}`);
+        return { kind: "skipped", reason: "file not found" };
+    }
+    const ext = path.extname(absolute).toLowerCase();
+    if (!SUPPORTED_INGEST_EXTENSIONS.has(ext)) {
+        say(`Unsupported file extension "${ext}". Allowed: .json, .zip.`);
+        return { kind: "skipped", reason: "unsupported extension" };
+    }
+    const baseUrl = safeResolveBaseUrl(configPath);
+    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: tokenResult.token });
+    const buf = fs.readFileSync(absolute);
+    // Fail-fast for non-ChatGPT exports: route them to `onadit 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 && !source) {
+        say(`Detected a ${sniffed} export — the inline importer is ChatGPT-only.`);
+        say(`Run: onadit import "${absolute}" --source ${sniffed}`);
+        return { kind: "skipped", reason: `non-chatgpt export detected: ${sniffed}` };
+    }
+    const form = new FormData();
+    const importSource = source === "auto" ? sniffed ?? ONBOARD_INLINE_IMPORT_SOURCE : source ?? ONBOARD_INLINE_IMPORT_SOURCE;
+    form.append("source", importSource);
+    form.append("file", new Blob([buf]), path.basename(absolute));
+    say(`Importing ${path.basename(absolute)} as ${importSource}…`);
+    const { data } = await client.postMultipart("/ingest", form);
+    const resp = data;
+    if (resp.duplicate) {
+        say(`Import already submitted (job ${resp.job_id}).`);
+    }
+    const result = await pollJob({ get: client.get.bind(client), jobId: resp.job_id });
+    if (result.timedOut) {
+        return { kind: "failed", reason: `Import is still running. Check its status with: onadit status (job ${resp.job_id}). Do not start another import.` };
+    }
+    if (isJobFailure(result.job, false)) {
+        const reason = result.job.error ?? "unknown";
+        say(`Import failed: ${reason}`);
+        return { kind: "failed", reason };
+    }
+    say(`Import complete (job ${resp.job_id}).`);
+    return { kind: "imported", jobId: resp.job_id, ...(result.job.import_summary ? { summary: result.job.import_summary } : {}) };
+}
+/**
+ * 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.`,
+            "Next: onadit mcp install --client=claude-desktop",
+        ];
+    }
+    if (!ingestedAny) {
+        if (!ingestAttempted) {
+            // Deliberate empty setup — a finished, valid state, not a failure.
+            return [
+                "Setup complete — nothing imported yet.",
+                "Import later: onadit import <path> --source <name>",
+                "Next: onadit mcp install --client=claude-desktop",
+            ];
+        }
+        // An ingest ran but landed nothing — honest, calm retry guidance.
+        return [
+            "Setup ready — but capture/import added nothing this run.",
+            "Try: onadit import <path> --source <name>",
+            "If it repeats: onadit feedback --kind=broke --with-status",
+        ];
+    }
+    if (recall.ok) {
+        return [
+            "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: onadit search \"<a topic you remember discussing>\"",
+            "If repeated tries still return nothing, run: onadit feedback --kind=broke --with-status",
+        ];
+    }
+    return [
+        `Setup partially complete — recall check failed: ${recall.reason}`,
+        "Next: onadit status   (then: onadit feedback --kind=broke --with-status)",
+    ];
+}
+// ----- Step 9: first-recall verification -----
+async function firstRecallCheck(configPath) {
+    const baseUrl = safeResolveBaseUrl(configPath);
+    const tokenResult = await ensureToken(configPath);
+    if (!baseUrl || !tokenResult.ok) {
+        return { ok: false, reason: "daemon not reachable" };
+    }
+    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.
+    //
+    // 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 -----
+/**
+ * Reconfigure the Voyage key. ALL of (kickstart succeeds, /health 200,
+ * smoke `voyage_key_present=true`) must pass; any failure rolls back the
+ * env file AND restores the previous in-process VOYAGE_API_KEY so a
+ * caller is never left with a half-replaced credential. `agent_not_loaded`
+ * counts as a failure here (unlike initial onboard) because reconfigure
+ * is, by definition, called against a daemon that should already be
+ * running — if the launchd label is gone, we don't trust the new key.
+ */
+async function reconfigureVoyageFlow(opts, globalOpts, rl) {
+    say("Reconfiguring Voyage key…");
+    const key = await collectVoyageKey(opts, rl);
+    await performVoyageReconfigure({
+        key,
+        envPath: defaultRiftEnvPath(),
+        refresh: () => daemonRefreshFlow(globalOpts),
+    });
+}
+/**
+ * Core reconfigure logic, extracted so tests can drive every failure
+ * branch (validate fail, kickstart agent_not_loaded, /health fail,
+ * voyage_key_present=false) without spinning up a real daemon.
+ *
+ * Contract: ALL of {validate ok, daemonRefresh ok} must succeed; any
+ * failure rolls back the env file AND restores the previous in-process
+ * VOYAGE_API_KEY. agent_not_loaded counts as a failure here — the call
+ * site only invokes this when the daemon should already be running.
+ */
+export async function performVoyageReconfigure(deps) {
+    const validate = deps.validate ?? validateVoyageKey;
+    const write = deps.write ?? writeEnvFile;
+    const loadEnv = deps.loadEnv ?? loadRiftEnv;
+    const emit = deps.emit ?? say;
+    const validation = await validate({ apiKey: deps.key });
+    if (!validation.ok) {
+        throw new CliError(`Voyage validation failed: ${validation.reason}`, "validation");
+    }
+    emit(`Voyage key valid (last 4 …${validation.last4}).`);
+    const previousInProcessKey = process.env["VOYAGE_API_KEY"];
+    const writeResult = write({
+        filePath: deps.envPath,
+        key: "VOYAGE_API_KEY",
+        value: deps.key,
+    });
+    loadEnv({ filePath: deps.envPath });
+    const refresh = await deps.refresh();
+    if (refresh.ok) {
+        emit(`Voyage reconfigured (last 4 …${validation.last4}).`);
+        return;
+    }
+    rollbackVoyageEnv(deps.envPath, writeResult, previousInProcessKey);
+    throw new CliError(`Reconfigure failed — restored previous Voyage key (reason: ${refresh.reason}).`, "server_error");
+}
+/**
+ * Restore a Voyage env file + in-process VOYAGE_API_KEY after a failed
+ * write. Exported for testing — `reconfigureVoyageFlow` is the only
+ * production caller. When `writeResult.backedUp` is true, the prior
+ * env-file contents are copied back at mode 0600; when false (no prior
+ * file existed), the file we just wrote is removed so we don't leave
+ * a key paired with a now-rejected daemon respawn.
+ */
+export function rollbackVoyageEnv(envPath, writeResult, previousInProcessKey) {
+    // 1. Env file.
+    if (writeResult.backedUp && writeResult.backupPath) {
+        try {
+            fs.copyFileSync(writeResult.backupPath, envPath);
+            fs.chmodSync(envPath, 0o600);
+        }
+        catch {
+            say("Reconfigure rollback: env-file restore failed — ping Clem for recovery.");
+        }
+    }
+    else {
+        // No prior env file — best effort: drop the line we just wrote so we
+        // don't leave a key paired with a now-rejected daemon respawn.
+        try {
+            fs.rmSync(envPath, { force: true });
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    // 2. In-process VOYAGE_API_KEY — restore prior value or delete.
+    if (typeof previousInProcessKey === "string" && previousInProcessKey.length > 0) {
+        process.env["VOYAGE_API_KEY"] = previousInProcessKey;
+    }
+    else {
+        delete process.env["VOYAGE_API_KEY"];
+    }
+}
+// ----- Helpers -----
+function ask(rl, question, fallback) {
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            resolve(answer || fallback || "");
+        });
+    });
+}
+function say(line) {
+    process.stdout.write(line + "\n");
+}
+function sayPrivacyContract() {
+    ui.detail([
+        "• Conversation content stays local (LanceDB + raw transcripts).",
+        "• Indexed conversation text — and your search queries — leave the machine",
+        "  for embedding only when a Voyage key is configured (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://onadit.com/privacy",
+    ].join("\n"));
+}
+function safeDiscover(fn) {
+    try {
+        return fn().length;
+    }
+    catch {
+        return 0;
+    }
+}
+function safeResolveBaseUrl(configPath) {
+    try {
+        return resolveBaseUrl(configPath);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=onboard.js.map