@ashlr/hub 2.2.0

package/dist/core/observability/usage-source.js

@@ -0,0 +1,347 @@
+/**
+ * usage-source.ts — local-first UsageEvent collector (M5 observability).
+ *
+ * PRIVACY GUARDRAILS: reads ONLY token counts, model id, timestamp, and the
+ * project path (decoded from the encoded dir name). Never reads or retains
+ * message content, tool args/results, prompts, or completions.
+ *
+ * PERFORMANCE: streams line-by-line; skips files whose mtime is older than
+ * sinceMs; tolerates malformed lines; never throws.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+/** Absolute path to ~/.claude/projects (honors $HOME). */
+export function claudeProjectsDir() {
+    return path.join(os.homedir(), ".claude", "projects");
+}
+/**
+ * Decode an encoded Claude Code project dir name back to an absolute path.
+ *
+ * Claude encodes the absolute path by replacing the leading `/` with a `-`
+ * and then replacing every subsequent `/` with `-`. For example:
+ *   '-Users-you-Desktop-foo' -> '/Users/you/Desktop/foo'
+ *
+ * This is lossy for path segments that naturally contain `-`, but we do
+ * the best-effort reconstruction by:
+ *   1. Stripping the leading `-`
+ *   2. Re-prefixing with `/`
+ *   3. Replacing remaining `-` with `/`
+ *
+ * The result is a plausible absolute path suitable for display/grouping.
+ */
+export function decodeProjectPath(dirName) {
+    // Remove leading dash (represents the leading `/` of an absolute path)
+    const withoutLeadingDash = dirName.startsWith("-")
+        ? dirName.slice(1)
+        : dirName;
+    // Re-add leading slash and replace dashes with path separators
+    return "/" + withoutLeadingDash.replace(/-/g, "/");
+}
+/**
+ * Collapse a real absolute path to the dash-normalized form Claude uses to
+ * encode project dir names: every `/` AND every `-` becomes `-`.
+ *
+ * Both the real path '/Users/x/dev-tools/ashlr-hub' and its lossy decode
+ * '/Users/x/dev/tools/ashlr/hub' normalize to the SAME string
+ * '-Users-x-dev-tools-ashlr-hub'. That makes dashNormalize a reliable join key
+ * between the index's REAL paths and the transcript's MANGLED decoded paths,
+ * which recovers correct grouping/labels for any repo whose name has a dash.
+ */
+export function dashNormalize(absPath) {
+    return absPath.replace(/[/-]/g, "-");
+}
+/**
+ * Resolve a (possibly mangled) decoded project path against known real paths
+ * from the index. Returns the matching real path when the dash-normalized
+ * forms agree, otherwise returns the input unchanged (best-effort decode).
+ *
+ * `realByNorm` maps dashNormalize(realPath) -> realPath and is built once by
+ * the caller so this stays O(1) per event.
+ */
+export function reconcileProjectPath(decodedPath, realByNorm) {
+    const match = realByNorm.get(dashNormalize(decodedPath));
+    return match ?? decodedPath;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Chunk size for the streaming reader (64 KiB). */
+const READ_CHUNK = 64 * 1024;
+/**
+ * Hard cap on bytes scanned per transcript (256 MiB). Transcripts can be
+ * hundreds of MB; this bounds worst-case work while still covering any
+ * realistic session. Peak memory stays ~one chunk + one line regardless.
+ */
+const MAX_BYTES_PER_FILE = 256 * 1024 * 1024;
+/**
+ * Read a file line-by-line with BOUNDED memory, calling cb for each non-empty
+ * line. Instead of readFileSync + split (which loads the whole file as a string
+ * AND a full line array — pathological for 100+ MB transcripts), we pull fixed
+ * 64 KiB chunks via fs.readSync and split on newlines incrementally, carrying a
+ * partial-line buffer across chunk boundaries. Peak memory is ~one chunk plus
+ * one line, not the whole file. Never throws.
+ */
+function eachLine(filePath, cb) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+    }
+    catch {
+        return; // unreadable — skip silently
+    }
+    try {
+        const chunk = Buffer.allocUnsafe(READ_CHUNK);
+        let pending = ""; // partial line carried across chunk boundaries
+        let bytesRead = 0;
+        for (;;) {
+            let n;
+            try {
+                n = fs.readSync(fd, chunk, 0, READ_CHUNK, null);
+            }
+            catch {
+                break; // read error — stop, keep whatever we collected
+            }
+            if (n <= 0)
+                break; // EOF
+            bytesRead += n;
+            pending += chunk.toString("utf8", 0, n);
+            let nl;
+            while ((nl = pending.indexOf("\n")) !== -1) {
+                const line = pending.slice(0, nl).trim();
+                pending = pending.slice(nl + 1);
+                if (line.length > 0)
+                    cb(line);
+            }
+            // Bound total work per file.
+            if (bytesRead >= MAX_BYTES_PER_FILE)
+                break;
+        }
+        // Flush any trailing line without a newline.
+        const last = pending.trim();
+        if (last.length > 0)
+            cb(last);
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/** Extract a UsageEvent from a parsed JSONL line, or null if not applicable. */
+function extractClaudeEvent(raw, project, sinceMs) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const obj = raw;
+    // Only process assistant-type events
+    if (obj["type"] !== "assistant")
+        return null;
+    // Timestamp lives at top level
+    const ts = typeof obj["timestamp"] === "string" ? obj["timestamp"] : null;
+    if (!ts)
+        return null;
+    // Filter by window early
+    try {
+        if (new Date(ts).getTime() < sinceMs)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    // Model and usage are nested under `message`
+    const message = obj["message"];
+    if (typeof message !== "object" || message === null)
+        return null;
+    const msg = message;
+    const model = typeof msg["model"] === "string" ? msg["model"] : "";
+    if (!model)
+        return null;
+    const usage = msg["usage"];
+    if (typeof usage !== "object" || usage === null)
+        return null;
+    const u = usage;
+    // PRIVACY: extract ONLY the four numeric token counts — nothing else
+    const tokensIn = typeof u["input_tokens"] === "number" ? u["input_tokens"] : 0;
+    const tokensOut = typeof u["output_tokens"] === "number" ? u["output_tokens"] : 0;
+    const cacheRead = typeof u["cache_read_input_tokens"] === "number"
+        ? u["cache_read_input_tokens"]
+        : 0;
+    const cacheWrite = typeof u["cache_creation_input_tokens"] === "number"
+        ? u["cache_creation_input_tokens"]
+        : 0;
+    // Skip events with zero useful usage (e.g. pure-tool events)
+    if (tokensIn === 0 && tokensOut === 0)
+        return null;
+    return {
+        ts,
+        project,
+        model,
+        source: "claude",
+        tokensIn,
+        tokensOut,
+        cacheRead,
+        cacheWrite,
+    };
+}
+// ---------------------------------------------------------------------------
+// Claude Code transcript ingestion
+// ---------------------------------------------------------------------------
+function collectClaudeEvents(sinceMs) {
+    const events = [];
+    const projectsRoot = claudeProjectsDir();
+    let projectDirs;
+    try {
+        projectDirs = fs.readdirSync(projectsRoot, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        return events; // ~/.claude/projects doesn't exist or isn't readable
+    }
+    for (const dirName of projectDirs) {
+        const dirPath = path.join(projectsRoot, dirName);
+        const project = decodeProjectPath(dirName);
+        let files;
+        try {
+            files = fs.readdirSync(dirPath, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of files) {
+            if (!entry.isFile() || !entry.name.endsWith(".jsonl"))
+                continue;
+            const filePath = path.join(dirPath, entry.name);
+            // Performance: skip files that haven't been modified since our window
+            try {
+                const stat = fs.statSync(filePath);
+                if (stat.mtimeMs < sinceMs)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            // Stream line-by-line; PRIVACY: parse only; never retain content
+            eachLine(filePath, (line) => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    return; // malformed line — skip silently
+                }
+                const event = extractClaudeEvent(parsed, project, sinceMs);
+                if (event)
+                    events.push(event);
+            });
+        }
+    }
+    return events;
+}
+// ---------------------------------------------------------------------------
+// M4 run record ingestion
+// ---------------------------------------------------------------------------
+function collectRunEvents(sinceMs) {
+    const events = [];
+    const runsDir = path.join(os.homedir(), ".ashlr", "runs");
+    let files;
+    try {
+        files = fs.readdirSync(runsDir);
+    }
+    catch {
+        return events; // no runs dir — fine
+    }
+    for (const name of files) {
+        if (!name.endsWith(".json"))
+            continue;
+        const filePath = path.join(runsDir, name);
+        // Performance: skip files older than window
+        try {
+            const stat = fs.statSync(filePath);
+            if (stat.mtimeMs < sinceMs)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let run;
+        try {
+            run = JSON.parse(raw);
+        }
+        catch {
+            continue; // malformed — skip
+        }
+        if (typeof run !== "object" || run === null)
+            continue;
+        const r = run;
+        // Validate createdAt is within window
+        const ts = typeof r["createdAt"] === "string" ? r["createdAt"] : null;
+        if (!ts)
+            continue;
+        try {
+            if (new Date(ts).getTime() < sinceMs)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const model = typeof r["provider"] === "string" ? r["provider"] : "unknown";
+        // Extract ONLY the numeric usage fields
+        const usage = r["usage"];
+        if (typeof usage !== "object" || usage === null)
+            continue;
+        const u = usage;
+        const tokensIn = typeof u["tokensIn"] === "number" ? u["tokensIn"] : 0;
+        const tokensOut = typeof u["tokensOut"] === "number" ? u["tokensOut"] : 0;
+        if (tokensIn === 0 && tokensOut === 0)
+            continue;
+        events.push({
+            ts,
+            project: null,
+            model,
+            source: "run",
+            tokensIn,
+            tokensOut,
+            cacheRead: 0,
+            cacheWrite: 0,
+        });
+    }
+    return events;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Collect normalized UsageEvents from all local sources with ts >= sinceMs.
+ *
+ * Sources:
+ *   (a) ~/.claude/projects/<encoded-dir>/*.jsonl  — METADATA ONLY
+ *   (b) ~/.ashlr/runs/*.json  — M4 RunState records
+ *
+ * Streams line-by-line; skips files older than sinceMs by mtime; tolerates
+ * malformed lines; never reads message content. Never throws.
+ */
+export function collectUsageEvents(sinceMs) {
+    try {
+        const claude = collectClaudeEvents(sinceMs);
+        const runs = collectRunEvents(sinceMs);
+        return [...claude, ...runs];
+    }
+    catch {
+        return []; // belt-and-suspenders: top-level guard
+    }
+}
+//# sourceMappingURL=usage-source.js.map

package/dist/core/observability/usage-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-source.js","sourceRoot":"","sources":["../../../src/core/observability/usage-source.ts"],"names":[],"mappings":"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"}

package/dist/core/onboard.d.ts

@@ -0,0 +1,27 @@
+/**
+ * core/onboard.ts — one-command idempotent onboarding (M20).
+ *
+ * onboard(cfg, opts): detect + report + safe ensures in a single, NON-TTY-safe
+ * call.  Never hangs on a prompt.  Mutating steps are gated:
+ *   - editor wiring: only when opts.wire
+ *   - model downloads: NEVER (pull stays explicit)
+ *   - shell-profile edits: NEVER
+ *
+ * Returns an OnboardResult with one OnboardStep per step, a ready flag, and
+ * crisp nextSteps guidance.
+ */
+import type { AshlrConfig, OnboardResult } from './types.js';
+/**
+ * Run the complete idempotent onboarding sequence.
+ *
+ * Guaranteed to:
+ *   - Never throw (degrades to 'manual' steps on any error).
+ *   - Never hang (no interactive prompts; safe in non-TTY environments).
+ *   - Never auto-download models.
+ *   - Never touch secrets, shell profiles, or anything outward/network.
+ *   - Be idempotent (safe to re-run).
+ */
+export declare function onboard(cfg: AshlrConfig, opts: {
+    wire: boolean;
+    yes: boolean;
+}): Promise<OnboardResult>;

package/dist/core/onboard.js

@@ -0,0 +1,288 @@
+/**
+ * core/onboard.ts — one-command idempotent onboarding (M20).
+ *
+ * onboard(cfg, opts): detect + report + safe ensures in a single, NON-TTY-safe
+ * call.  Never hangs on a prompt.  Mutating steps are gated:
+ *   - editor wiring: only when opts.wire
+ *   - model downloads: NEVER (pull stays explicit)
+ *   - shell-profile edits: NEVER
+ *
+ * Returns an OnboardResult with one OnboardStep per step, a ready flag, and
+ * crisp nextSteps guidance.
+ */
+import { existsSync, mkdirSync, symlinkSync, readlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { saveConfig, defaultConfig } from './config.js';
+import { listLocalModels, ollamaInstalled } from './run/model-manager.js';
+import { detectEditors, wireEditor } from './integrations/editors.js';
+import { getPhantomStatus } from './phantom.js';
+import { runDoctor } from './doctor.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Produce a passing step — never throws. */
+function step(name, status, detail) {
+    return { name, status, detail };
+}
+// ---------------------------------------------------------------------------
+// Step implementations — each is async, catches all errors, never throws
+// ---------------------------------------------------------------------------
+/** Step 1: ensure ~/.ashlr/config.json exists. */
+async function stepConfig() {
+    try {
+        // Resolve the config path from homedir() at call time so a moving HOME is
+        // honored and matches the path saveConfig()/runDoctor() actually use. The
+        // exported CONFIG_PATH constant is resolved once at module load and would
+        // point at a stale home (breaking onboarding under a relocated/test HOME).
+        const configPath = join(homedir(), '.ashlr', 'config.json');
+        if (existsSync(configPath)) {
+            return step('config', 'ok', `Config present at ${configPath}`);
+        }
+        // Create from defaults via saveConfig (loadConfig already does this, but we
+        // want explicit ensure-only semantics here — never overwrite existing).
+        const defaults = defaultConfig();
+        saveConfig(defaults);
+        return step('config', 'ok', `Created default config at ${configPath}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return step('config', 'manual', `Could not ensure config: ${msg}. Run: ashlr doctor --fix`);
+    }
+}
+/** Step 2: detect local models — report only, NEVER auto-download. */
+async function stepModels(cfg) {
+    try {
+        const models = await listLocalModels(cfg);
+        if (models.length > 0) {
+            const names = models.map((m) => `${m.provider}/${m.name}`).join(', ');
+            return step('models', 'detected', `Local models found: ${names}`);
+        }
+        const ollamaPresent = ollamaInstalled();
+        if (ollamaPresent) {
+            return step('models', 'manual', 'Ollama is installed but no models are loaded. Run: ashlr models pull <model>  (e.g. llama3:8b)');
+        }
+        return step('models', 'manual', 'No local models detected (Ollama/LM Studio not running or not installed). Run: ashlr models pull <model>');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return step('models', 'manual', `Could not probe local models: ${msg}. Run: ashlr models pull <model>`);
+    }
+}
+/** Step 3: detect editors; wire them when opts.wire. */
+async function stepEditors(opts) {
+    try {
+        const editors = detectEditors();
+        if (editors.length === 0) {
+            return step('editors', 'skipped', 'No supported editors detected (claude / codex / cursor)');
+        }
+        if (!opts.wire) {
+            return step('editors', 'detected', `Detected: ${editors.join(', ')}. Re-run with --wire to register the ashlr MCP gateway.`);
+        }
+        // Wire each detected editor — backup-first + idempotent (M18).
+        const results = [];
+        for (const editor of editors) {
+            const target = editor;
+            const r = await wireEditor(target, {});
+            results.push(`${editor}: ${r.detail}`);
+        }
+        return step('editors', 'wired', results.join('; '));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return step('editors', 'manual', `Editor detection/wiring failed: ${msg}. Run: ashlr wire`);
+    }
+}
+/**
+ * Step 4: ensure the ashlr → ~/.local/bin/ashlr symlink.
+ *
+ * Safe ensure: create only when (a) the symlink is missing AND (b) the source
+ * bin/ashlr file can be resolved from this module's location.  Never modifies
+ * shell profiles.  If source cannot be resolved → manual guidance.
+ */
+async function stepSymlink() {
+    const localBin = join(homedir(), '.local', 'bin');
+    const symlinkDest = join(localBin, 'ashlr');
+    try {
+        // Check if already present and correct.
+        if (existsSync(symlinkDest)) {
+            let target;
+            try {
+                target = readlinkSync(symlinkDest);
+            }
+            catch {
+                // Not a symlink (could be a real file installed by npm) — that's fine.
+                return step('symlink', 'ok', `ashlr present at ${symlinkDest}`);
+            }
+            return step('symlink', 'ok', `Symlink present: ${symlinkDest} → ${target}`);
+        }
+        // Attempt to resolve the bin/ashlr source from this module's directory tree.
+        // __dirname equivalent for ESM: walk up from src/core → project root → bin/ashlr.
+        const thisFile = fileURLToPath(import.meta.url);
+        // src/core/onboard.ts → src/core → src → project root
+        const projectRoot = resolve(dirname(thisFile), '..', '..');
+        const binSrc = join(projectRoot, 'bin', 'ashlr');
+        if (!existsSync(binSrc)) {
+            return step('symlink', 'manual', `ashlr not yet in ~/.local/bin. Run: ./install.sh  (from the ashlr-hub repo)`);
+        }
+        // Create ~/.local/bin if absent, then create the symlink.
+        mkdirSync(localBin, { recursive: true });
+        symlinkSync(binSrc, symlinkDest);
+        return step('symlink', 'ok', `Created symlink: ${symlinkDest} → ${binSrc}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return step('symlink', 'manual', `Could not ensure symlink: ${msg}. Run: ./install.sh  (from the ashlr-hub repo)`);
+    }
+}
+/**
+ * Step 5: ensure the genome directory exists (~/.ashlr/genome).
+ * mkdir-only, never seeds/edits entries.
+ */
+async function stepGenome() {
+    const genomeDir = join(homedir(), '.ashlr', 'genome');
+    try {
+        if (existsSync(genomeDir)) {
+            return step('genome', 'ok', `Genome dir present at ${genomeDir}`);
+        }
+        mkdirSync(genomeDir, { recursive: true });
+        return step('genome', 'ok', `Created genome dir at ${genomeDir}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return step('genome', 'manual', `Could not create genome dir: ${msg}. Run: ashlr doctor --fix`);
+    }
+}
+/** Step 6: phantom status — report only, never touches secrets. */
+async function stepPhantom() {
+    try {
+        const status = getPhantomStatus();
+        if (!status.installed) {
+            return step('phantom', 'manual', 'Phantom not installed. Install from https://phantom.sh to enable secrets management.');
+        }
+        if (!status.initialized) {
+            return step('phantom', 'detected', `Phantom v${status.version ?? 'unknown'} installed but vault not initialized. Run: phantom init`);
+        }
+        const count = status.secretNames.length;
+        return step('phantom', 'ok', `Phantom v${status.version ?? 'unknown'} — vault initialized (${count} secret${count !== 1 ? 's' : ''})`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return step('phantom', 'manual', `Phantom status unavailable: ${msg}`);
+    }
+}
+/**
+ * Doctor checks that genuinely block the hub from running. A `fail` on one of
+ * these means setup is NOT ready.
+ *
+ * This set is intentionally EMPTY: config presence — the one true readiness
+ * prerequisite — is gated authoritatively by onboard's own `configStep` (which
+ * resolves the config path at call time), not by doctor's `config` check (which
+ * compares a module-load-time CONFIG_PATH constant and can therefore disagree
+ * under a relocated/test HOME). Every other doctor `fail` (git/ashlr-on-PATH,
+ * provider reachability, MCP wiring, etc.) is environmental/advisory: you can
+ * still `ashlr run` with cloud fallback, install a model later, or fix PATH
+ * later. Those are surfaced as guidance in nextSteps, never a hard readiness
+ * blocker. This matches the contract's `ready` = "config present + doctor has
+ * no fail that blocks running".
+ */
+const BLOCKING_FAIL_IDS = new Set();
+/** Step 7: run doctor and fold roll-up into final OnboardStep. */
+async function stepDoctor(cfg) {
+    try {
+        const report = await runDoctor(cfg);
+        const { pass, warn, fail } = report.summary;
+        const failChecks = report.checks.filter((c) => c.status === 'fail');
+        const blockingFails = failChecks.filter((c) => BLOCKING_FAIL_IDS.has(c.id));
+        const hasBlockingFail = blockingFails.length > 0;
+        const detail = `doctor: ${pass} pass, ${warn} warn, ${fail} fail`;
+        if (hasBlockingFail) {
+            const failLabels = blockingFails.map((c) => c.label).join(', ');
+            return {
+                doctorStep: step('doctor', 'manual', `${detail}. Blocking: ${failLabels}. Run: ashlr doctor --fix`),
+                hasBlockingFail: true,
+            };
+        }
+        // Non-blocking fails are advisory — report them but don't gate readiness.
+        if (failChecks.length > 0) {
+            const failLabels = failChecks.map((c) => c.label).join(', ');
+            return {
+                doctorStep: step('doctor', 'detected', `${detail}. Needs attention: ${failLabels}. Run: ashlr doctor --fix`),
+                hasBlockingFail: false,
+            };
+        }
+        return {
+            doctorStep: step('doctor', warn > 0 ? 'detected' : 'ok', detail),
+            hasBlockingFail: false,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            doctorStep: step('doctor', 'manual', `Doctor check failed: ${msg}. Run: ashlr doctor`),
+            hasBlockingFail: false, // unknown state — don't block if doctor itself errors
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run the complete idempotent onboarding sequence.
+ *
+ * Guaranteed to:
+ *   - Never throw (degrades to 'manual' steps on any error).
+ *   - Never hang (no interactive prompts; safe in non-TTY environments).
+ *   - Never auto-download models.
+ *   - Never touch secrets, shell profiles, or anything outward/network.
+ *   - Be idempotent (safe to re-run).
+ */
+export async function onboard(cfg, opts) {
+    // Run all steps sequentially so each can feed into ready computation.
+    // Steps that are independent in principle are still sequential here to avoid
+    // interleaved output and to keep the order deterministic and predictable.
+    const configStep = await stepConfig();
+    const modelsStep = await stepModels(cfg);
+    const editorsStep = await stepEditors(opts);
+    const symlinkStep = await stepSymlink();
+    const genomeStep = await stepGenome();
+    const phantomStep = await stepPhantom();
+    const { doctorStep, hasBlockingFail } = await stepDoctor(cfg);
+    const steps = [
+        configStep,
+        modelsStep,
+        editorsStep,
+        symlinkStep,
+        genomeStep,
+        phantomStep,
+        doctorStep,
+    ];
+    // ready = config is ok AND no doctor blocking failures.
+    const configOk = configStep.status === 'ok';
+    const ready = configOk && !hasBlockingFail;
+    // Build nextSteps guidance.
+    const nextSteps = [];
+    if (!configOk) {
+        nextSteps.push('Fix config first: ashlr doctor --fix');
+    }
+    if (modelsStep.status === 'manual') {
+        nextSteps.push('Pull a local model: ashlr models pull llama3:8b');
+    }
+    if (editorsStep.status === 'detected' && !opts.wire) {
+        nextSteps.push('Wire your editor: ashlr init --wire');
+    }
+    if (symlinkStep.status === 'manual') {
+        nextSteps.push('Install the CLI symlink: ./install.sh  (from the ashlr-hub repo)');
+    }
+    // Surface doctor guidance for any remaining issues (blocking or advisory) —
+    // doctorStep is 'manual' on a blocking fail and 'detected' when there are
+    // non-blocking fails/warns that still warrant a `doctor --fix` pass.
+    if (doctorStep.status === 'manual' || hasBlockingFail) {
+        nextSteps.push('Fix doctor issues: ashlr doctor --fix');
+    }
+    // Always end with the crisp "you're set up" guidance.
+    nextSteps.push('try: ashlr run / ashlr swarm / ashlr tui');
+    return { steps, ready, nextSteps };
+}
+//# sourceMappingURL=onboard.js.map