@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/wizard/environment-detection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Environment capability detection for onboarding / `buddy try` / `buddy doctor`.
+ *
+ * The single job of this module: answer "what can this machine talk to RIGHT
+ * NOW, and which of those costs $0?" — so the setup surfaces can default to the
+ * free path (Ollama local, or a signed-in ChatGPT subscription) instead of
+ * asking a newcomer to understand 8 providers and 120 env vars.
+ *
+ * Every probe is best-effort, short-timeout, and never throws — a detection
+ * failure just means "not available", never a crash.
+ */
+export type CapabilityKind = 'local' | 'oauth' | 'api-key';
+/** Metadata returned by Ollama `/api/tags`, retained for safe local-model selection. */
+export interface OllamaModelCandidate {
+    name: string;
+    sizeBytes?: number;
+    family?: string;
+    parameterSize?: string;
+    quantizationLevel?: string;
+}
+export interface DetectedCapability {
+    /** Stable id used by the wizard / try command. */
+    id: string;
+    /** Human-readable label. */
+    label: string;
+    kind: CapabilityKind;
+    /** True when using it has $0 marginal cost (local runtime or a subscription). */
+    free: boolean;
+    /** Whether it is reachable / configured right now. */
+    available: boolean;
+    /** One-line human detail, e.g. "running · 2 models" or "signed in as x@y". */
+    detail: string;
+    /** Installed/served models, when the probe returned them. */
+    models?: string[];
+    /** Ollama model metadata, when the local runtime returned it. */
+    modelDetails?: OllamaModelCandidate[];
+    /** OpenAI-compatible base URL, for local runtimes. */
+    baseURL?: string;
+    /** Command that finishes setup for this capability (login / pull / etc.). */
+    setupCommand?: string;
+}
+export interface EnvironmentSnapshot {
+    capabilities: DetectedCapability[];
+    /** The best AVAILABLE free path, if any (Ollama-with-model → ChatGPT → xAI). */
+    recommendedFree?: DetectedCapability;
+    /** The best available path of any kind (free preferred, else an API key). */
+    recommended?: DetectedCapability;
+    /** True when at least one capability is usable right now. */
+    ready: boolean;
+}
+/** Probe a local Ollama runtime (respects OLLAMA_HOST when set). */
+export declare function detectOllama(): Promise<DetectedCapability>;
+/** Probe a local LM Studio server. */
+export declare function detectLmStudio(): Promise<DetectedCapability>;
+/** Check the ChatGPT (Codex) OAuth credential file. */
+export declare function detectChatGptOAuth(): Promise<DetectedCapability>;
+/** Check the xAI (Grok) OAuth credential file. */
+export declare function detectXaiOAuth(): Promise<DetectedCapability>;
+/** Report API keys present in the environment (not billed to us, so free:false). */
+export declare function detectApiKeys(): DetectedCapability[];
+/**
+ * One call to learn everything the setup surfaces need. Free local/OAuth probes
+ * run in parallel; the API-key scan is synchronous.
+ */
+export declare function detectEnvironment(): Promise<EnvironmentSnapshot>;
+/** Compact human summary of what was detected — used by wizard + doctor. */
+export declare function renderDetectionSummary(snapshot: EnvironmentSnapshot): string;

package/dist/wizard/environment-detection.js

@@ -0,0 +1,210 @@
+/**
+ * Environment capability detection for onboarding / `buddy try` / `buddy doctor`.
+ *
+ * The single job of this module: answer "what can this machine talk to RIGHT
+ * NOW, and which of those costs $0?" — so the setup surfaces can default to the
+ * free path (Ollama local, or a signed-in ChatGPT subscription) instead of
+ * asking a newcomer to understand 8 providers and 120 env vars.
+ *
+ * Every probe is best-effort, short-timeout, and never throws — a detection
+ * failure just means "not available", never a crash.
+ */
+const OLLAMA_DEFAULT_HOST = 'http://localhost:11434';
+const LMSTUDIO_DEFAULT_HOST = 'http://localhost:1234';
+async function fetchJson(url, timeoutMs = 1500) {
+    try {
+        const res = await fetch(url, { method: 'GET', signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeHost(raw) {
+    let host = raw.trim();
+    if (!/^https?:\/\//i.test(host))
+        host = `http://${host}`;
+    return host.replace(/\/+$/, '');
+}
+/** Probe a local Ollama runtime (respects OLLAMA_HOST when set). */
+export async function detectOllama() {
+    const host = normalizeHost(process.env.OLLAMA_HOST || OLLAMA_DEFAULT_HOST);
+    const body = (await fetchJson(`${host}/api/tags`));
+    const base = {
+        id: 'ollama',
+        label: 'Ollama (local, $0)',
+        kind: 'local',
+        free: true,
+        available: false,
+        detail: 'not running',
+        baseURL: `${host}/v1`,
+        setupCommand: 'ollama serve',
+    };
+    if (!body)
+        return base;
+    const modelDetails = (body.models ?? [])
+        .map((model) => {
+        const name = model.name || model.model || '';
+        if (!name)
+            return null;
+        return {
+            name,
+            ...(typeof model.size === 'number' && Number.isFinite(model.size) && model.size > 0
+                ? { sizeBytes: model.size }
+                : {}),
+            ...(model.details?.family ? { family: model.details.family } : {}),
+            ...(model.details?.parameter_size ? { parameterSize: model.details.parameter_size } : {}),
+            ...(model.details?.quantization_level
+                ? { quantizationLevel: model.details.quantization_level }
+                : {}),
+        };
+    })
+        .filter((model) => model !== null);
+    const models = modelDetails.map((model) => model.name);
+    return {
+        ...base,
+        available: true,
+        models,
+        modelDetails,
+        detail: models.length
+            ? `running · ${models.length} model${models.length === 1 ? '' : 's'}`
+            : 'running · no model pulled yet (run: ollama pull qwen2.5-coder:7b)',
+        setupCommand: models.length ? undefined : 'ollama pull qwen2.5-coder:7b',
+    };
+}
+/** Probe a local LM Studio server. */
+export async function detectLmStudio() {
+    const host = normalizeHost(process.env.LMSTUDIO_HOST || LMSTUDIO_DEFAULT_HOST);
+    const body = (await fetchJson(`${host}/v1/models`));
+    const base = {
+        id: 'lmstudio',
+        label: 'LM Studio (local, $0)',
+        kind: 'local',
+        free: true,
+        available: false,
+        detail: 'not running',
+        baseURL: `${host}/v1`,
+        setupCommand: 'Start the LM Studio local server',
+    };
+    if (!body)
+        return base;
+    const models = (body.data ?? []).map((m) => m.id).filter(Boolean);
+    return {
+        ...base,
+        available: models.length > 0,
+        models,
+        detail: models.length ? `running · ${models.length} model${models.length === 1 ? '' : 's'}` : 'running · no model loaded',
+    };
+}
+/** Check the ChatGPT (Codex) OAuth credential file. */
+export async function detectChatGptOAuth() {
+    const base = {
+        id: 'chatgpt',
+        label: 'ChatGPT subscription (OAuth, $0)',
+        kind: 'oauth',
+        free: true,
+        available: false,
+        detail: 'not signed in',
+        setupCommand: 'buddy login',
+    };
+    try {
+        const { hasCodexCredentials, getChatGptAuth } = await import('../providers/codex-oauth.js');
+        if (!hasCodexCredentials())
+            return base;
+        const auth = await getChatGptAuth().catch(() => null);
+        const who = auth?.email ? `signed in as ${auth.email}` : 'signed in';
+        return { ...base, available: true, detail: who, setupCommand: undefined };
+    }
+    catch {
+        return base;
+    }
+}
+/** Check the xAI (Grok) OAuth credential file. */
+export async function detectXaiOAuth() {
+    const base = {
+        id: 'xai',
+        label: 'Grok / xAI subscription (OAuth, $0)',
+        kind: 'oauth',
+        free: true,
+        available: false,
+        detail: 'not signed in',
+        setupCommand: 'buddy login xai',
+    };
+    try {
+        const { hasXaiCredentials } = await import('../providers/xai-oauth.js');
+        if (!hasXaiCredentials())
+            return base;
+        return { ...base, available: true, detail: 'signed in', setupCommand: undefined };
+    }
+    catch {
+        return base;
+    }
+}
+const API_KEY_PROVIDERS = [
+    { id: 'grok', label: 'Grok / xAI API key', envVars: ['GROK_API_KEY', 'XAI_API_KEY'] },
+    { id: 'openai', label: 'OpenAI API key', envVars: ['OPENAI_API_KEY'] },
+    { id: 'anthropic', label: 'Anthropic Claude API key', envVars: ['ANTHROPIC_API_KEY'] },
+    { id: 'gemini', label: 'Google Gemini API key', envVars: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'] },
+    { id: 'openrouter', label: 'OpenRouter API key', envVars: ['OPENROUTER_API_KEY'] },
+];
+/** Report API keys present in the environment (not billed to us, so free:false). */
+export function detectApiKeys() {
+    return API_KEY_PROVIDERS.map((spec) => {
+        const hit = spec.envVars.find((v) => Boolean(process.env[v]));
+        return {
+            id: spec.id,
+            label: spec.label,
+            kind: 'api-key',
+            free: false,
+            available: Boolean(hit),
+            detail: hit ? `${hit} set` : 'not set',
+        };
+    });
+}
+/**
+ * One call to learn everything the setup surfaces need. Free local/OAuth probes
+ * run in parallel; the API-key scan is synchronous.
+ */
+export async function detectEnvironment() {
+    const [ollama, lmstudio, chatgpt, xai] = await Promise.all([
+        detectOllama(),
+        detectLmStudio(),
+        detectChatGptOAuth(),
+        detectXaiOAuth(),
+    ]);
+    const apiKeys = detectApiKeys();
+    const capabilities = [ollama, lmstudio, chatgpt, xai, ...apiKeys];
+    // Free path priority: a local Ollama that actually has a model → ChatGPT
+    // subscription → xAI subscription → LM Studio with a model. A running Ollama
+    // with zero models is NOT recommendable (nothing to chat with yet).
+    const ollamaReady = ollama.available && (ollama.models?.length ?? 0) > 0;
+    const lmReady = lmstudio.available && (lmstudio.models?.length ?? 0) > 0;
+    const freeOrder = [
+        ollamaReady ? ollama : undefined,
+        chatgpt.available ? chatgpt : undefined,
+        xai.available ? xai : undefined,
+        lmReady ? lmstudio : undefined,
+    ];
+    const recommendedFree = freeOrder.find(Boolean) ?? undefined;
+    const anyApiKey = apiKeys.find((k) => k.available);
+    const recommended = recommendedFree ?? anyApiKey ?? undefined;
+    return {
+        capabilities,
+        ...(recommendedFree ? { recommendedFree } : {}),
+        ...(recommended ? { recommended } : {}),
+        ready: Boolean(recommended),
+    };
+}
+/** Compact human summary of what was detected — used by wizard + doctor. */
+export function renderDetectionSummary(snapshot) {
+    const lines = ['  Detected on this machine:'];
+    for (const cap of snapshot.capabilities) {
+        const mark = cap.available ? '✓' : '○';
+        const cost = cap.available && cap.free ? '  ($0)' : '';
+        lines.push(`    ${mark} ${cap.label} — ${cap.detail}${cost}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=environment-detection.js.map

package/dist/wizard/onboarding.d.ts

@@ -1,3 +1,4 @@
+import { type EnvironmentSnapshot } from './environment-detection.js';
 export interface OnboardingResult {
     provider: string;
     apiKey: string;
@@ -7,6 +8,12 @@ export interface OnboardingResult {
     authMode?: OnboardingAuthMode;
     recommendedNextCommands?: string[];
 }
+export declare const NON_INTERACTIVE_ONBOARDING_MESSAGE: string;
+export declare function isInteractiveTerminal(input: {
+    isTTY?: boolean;
+}, output: {
+    isTTY?: boolean;
+}): boolean;
 export type OnboardingAuthMode = 'oauth' | 'api-key' | 'local';
 export interface OnboardingProviderGuide {
     id: string;
@@ -43,8 +50,21 @@ export declare const ONBOARDING_PHASES: OnboardingPhase[];
  * All writes are best-effort; the wizard summary still prints on failure.
  */
 export declare function persistProviderSelection(guide: OnboardingProviderGuide, model: string, apiKey: string): Promise<void>;
+export declare const PROJECT_FOLDER_QUESTION = "Which project folder should Code Buddy use?";
+export declare function resolveOnboardingProjectDir(answer: string, cwd?: string): string;
+export declare function applyOnboardingProjectConfig(projectDir: string, result: OnboardingResult): void;
 export declare function writeConfig(configDir: string, result: OnboardingResult): void;
 export declare function getProviderGuide(provider: string): OnboardingProviderGuide;
 export declare function buildRecommendedNextCommands(result: Pick<OnboardingResult, 'provider' | 'model' | 'apiKey'>): string[];
 export declare function renderOnboardingRoadmap(result?: Pick<OnboardingResult, 'provider' | 'model' | 'apiKey'>): string;
-export declare function runOnboarding(): Promise<OnboardingResult>;
+/**
+ * A light "what's enabled now / add later" capability snapshot for the closing
+ * summary — the Hermes-style reassurance that the agent is ready, derived from
+ * env vars actually present. Kept deliberately minimal (getting-started scope).
+ */
+export declare function renderCapabilitiesFooter(): string;
+/** Reorder the provider menu so detected/available options come first, with the
+ *  recommended free path at index 0. Availability annotations are appended to
+ *  the label so the newcomer sees "(detected)" without extra prose. */
+export declare function orderGuidesByDetection(snapshot: EnvironmentSnapshot): OnboardingProviderGuide[];
+export declare function runOnboarding(): Promise<OnboardingResult | null>;

package/dist/wizard/onboarding.js

@@ -1,7 +1,20 @@
 import * as readline from 'readline';
+import { spawn } from 'child_process';
 import { mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { isAbsolute, join, resolve } from 'path';
 import { getValidationConfigForGuide, validateProviderKey, } from './provider-onboarding.js';
+import { detectEnvironment, renderDetectionSummary, } from './environment-detection.js';
+export const NON_INTERACTIVE_ONBOARDING_MESSAGE = [
+    'Code Buddy onboarding needs an interactive terminal.',
+    '',
+    'Run `buddy onboard` from a terminal (not a pipe or CI job), or configure a provider non-interactively:',
+    '  buddy login',
+    '  buddy doctor',
+    '  buddy try',
+].join('\n');
+export function isInteractiveTerminal(input, output) {
+    return input.isTTY === true && output.isTTY === true;
+}
 export const PROVIDER_ENV_MAP = {
     chatgpt: '',
     grok: 'GROK_API_KEY',
@@ -13,13 +26,13 @@ export const PROVIDER_ENV_MAP = {
     lmstudio: '',
 };
 export const PROVIDER_DEFAULT_MODEL = {
-    chatgpt: 'gpt-5.5',
+    chatgpt: 'gpt-5.6-sol',
     grok: 'grok-3',
     claude: 'claude-sonnet-4-20250514',
     gemini: 'gemini-2.0-flash',
     openai: 'gpt-4o',
     openrouter: 'openai/gpt-4o',
-    ollama: 'llama3',
+    ollama: 'qwen2.5-coder:7b',
     lmstudio: 'default',
 };
 export const PROVIDER_AUTH_MODE = {
@@ -35,14 +48,25 @@ export const PROVIDER_AUTH_MODE = {
 export const PROVIDER_GUIDES = [
     {
         id: 'chatgpt',
-        label: 'ChatGPT subscription (OAuth)',
+        label: 'ChatGPT subscription — recommended (OAuth, no API key, $0 marginal cost)',
         authMode: 'oauth',
         envVar: '',
-        defaultModel: 'gpt-5.5',
+        defaultModel: 'gpt-5.6-sol',
         setupCommand: 'buddy login',
         verifyCommand: 'buddy whoami',
         help: 'One browser login unlocks the ChatGPT-backed Codex route; no OPENAI_API_KEY is required.',
     },
+    {
+        id: 'ollama',
+        label: 'Ollama local model — free and private',
+        authMode: 'local',
+        envVar: '',
+        defaultModel: 'qwen2.5-coder:7b',
+        baseURL: 'http://localhost:11434/v1',
+        setupCommand: 'ollama serve',
+        verifyCommand: 'curl http://localhost:11434/api/tags',
+        help: 'Run Ollama locally and pull a coding model, for example: ollama pull qwen2.5-coder:7b',
+    },
     {
         id: 'grok',
         label: 'Grok / xAI API key',
@@ -93,17 +117,6 @@ export const PROVIDER_GUIDES = [
         verifyCommand: 'buddy doctor',
         help: 'Set OPENROUTER_API_KEY (https://openrouter.ai/keys).',
     },
-    {
-        id: 'ollama',
-        label: 'Ollama local model',
-        authMode: 'local',
-        envVar: '',
-        defaultModel: 'llama3',
-        baseURL: 'http://localhost:11434/v1',
-        setupCommand: 'ollama serve',
-        verifyCommand: 'curl http://localhost:11434/api/tags',
-        help: 'Run Ollama locally and pull the model you selected.',
-    },
     {
         id: 'lmstudio',
         label: 'LM Studio local server',
@@ -134,8 +147,8 @@ export const ONBOARDING_PHASES = [
         id: 'first-chat',
         title: 'Run a verifiable first chat',
         hermesPhase: 'Start the CLI/TUI and ask a specific prompt with observable success.',
-        codeBuddyAction: 'Run buddy with a repo summary prompt.',
-        successCheck: 'the answer names files or tools from the current workspace.',
+        codeBuddyAction: 'With ChatGPT or Ollama, run buddy try for the one-minute coding demo.',
+        successCheck: 'FizzBuzz and its test are created in isolation, then node --test passes.',
     },
     {
         id: 'session-resume',
@@ -152,7 +165,7 @@ export const ONBOARDING_PHASES = [
         successCheck: 'the selected layer has a doctor/status command or a focused smoke prompt.',
     },
 ];
-const TTS_PROVIDERS = ['edge-tts', 'espeak', 'audioreader'];
+const TTS_PROVIDERS = ['pocket', 'elevenlabs', 'piper'];
 function ask(rl, question, defaultValue) {
     return new Promise((resolve) => {
         const suffix = defaultValue ? ` [${defaultValue}]` : '';
@@ -212,6 +225,7 @@ export async function persistProviderSelection(guide, model, apiKey) {
             provider: guide.id,
             defaultModel: model,
             model,
+            models: [model],
             ...(guide.baseURL ? { baseURL: guide.baseURL } : {}),
         });
     }
@@ -229,6 +243,14 @@ export async function persistProviderSelection(guide, model, apiKey) {
         process.env.OLLAMA_HOST = 'http://localhost:11434';
     }
 }
+export const PROJECT_FOLDER_QUESTION = 'Which project folder should Code Buddy use?';
+export function resolveOnboardingProjectDir(answer, cwd = process.cwd()) {
+    const raw = answer.trim() || cwd;
+    return isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+}
+export function applyOnboardingProjectConfig(projectDir, result) {
+    writeConfig(join(projectDir, '.codebuddy'), result);
+}
 export function writeConfig(configDir, result) {
     mkdirSync(configDir, { recursive: true });
     const authMode = result.authMode ?? getProviderGuide(result.provider).authMode;
@@ -257,7 +279,7 @@ export function getProviderGuide(provider) {
             label: 'ChatGPT subscription (OAuth)',
             authMode: 'oauth',
             envVar: '',
-            defaultModel: 'gpt-5.5',
+            defaultModel: 'gpt-5.6-sol',
             setupCommand: 'buddy login',
             verifyCommand: 'buddy whoami',
             help: 'Use ChatGPT OAuth.',
@@ -282,7 +304,12 @@ export function buildRecommendedNextCommands(result) {
     else {
         commands.push(guide.verifyCommand);
     }
-    commands.push(`buddy --model ${result.model} -p "Summarize this repo in 5 bullets and name the main entry point."`);
+    if (guide.id === 'chatgpt' || guide.id === 'ollama') {
+        commands.push('buddy try');
+    }
+    else {
+        commands.push(`buddy --model ${result.model} -p "Summarize this repo in 5 bullets and name the main entry point."`);
+    }
     commands.push('buddy --continue');
     commands.push('buddy --init');
     return Array.from(new Set(commands));
@@ -371,19 +398,148 @@ async function selectModel(rl, guide, availableModels) {
  * summary — the Hermes-style reassurance that the agent is ready, derived from
  * env vars actually present. Kept deliberately minimal (getting-started scope).
  */
-function renderCapabilitiesFooter() {
+export function renderCapabilitiesFooter() {
     const has = (vars) => vars.some((v) => Boolean(process.env[v]));
     const webSearch = has(['BRAVE_API_KEY', 'EXA_API_KEY', 'PERPLEXITY_API_KEY', 'TAVILY_API_KEY']);
+    const tts = has(['ELEVENLABS_API_KEY'])
+        ? '    ✓ Text-to-speech (ElevenLabs key detected; Pocket TTS / Piper as local fallback)'
+        : '    ○ Text-to-speech — Pocket TTS (`buddy speak --engine pocket`), Piper, or ELEVENLABS_API_KEY';
     return [
         '  Capabilities:',
         '    ✓ Code tools — file edit, shell, search',
-        '    ✓ Text-to-speech (edge-tts, offline fallback)',
+        tts,
         webSearch
             ? '    ✓ Web search'
             : '    ○ Web search — add BRAVE_API_KEY or EXA_API_KEY to enable',
     ].join('\n');
 }
+/** Reorder the provider menu so detected/available options come first, with the
+ *  recommended free path at index 0. Availability annotations are appended to
+ *  the label so the newcomer sees "(detected)" without extra prose. */
+export function orderGuidesByDetection(snapshot) {
+    const availableIds = new Set(snapshot.capabilities.filter((c) => c.available).map((c) => c.id));
+    const recommendedId = snapshot.recommended?.id;
+    const annotate = (g) => availableIds.has(g.id) ? { ...g, label: `${g.label} — detected ✓` } : g;
+    const scored = PROVIDER_GUIDES.map(annotate);
+    return scored.sort((a, b) => {
+        const rank = (g) => {
+            if (g.id === recommendedId)
+                return 0;
+            if (availableIds.has(g.id))
+                return 1;
+            return 2;
+        };
+        return rank(a) - rank(b);
+    });
+}
+/** Pull an Ollama model, streaming progress to the console. Resolves to the
+ *  model name on success, or null on failure (never throws). */
+async function pullOllamaModel(model) {
+    return new Promise((resolve) => {
+        try {
+            console.log(`\n  Pulling ${model} with Ollama (this can take a few minutes)…\n`);
+            const child = spawn('ollama', ['pull', model], { stdio: 'inherit' });
+            child.on('error', () => resolve(null));
+            child.on('close', (code) => resolve(code === 0 ? model : null));
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+/**
+ * Offer to start the newcomer on the best detected $0 path with a single "yes"
+ * — no provider menu, no key to paste. Returns a completed OnboardingResult when
+ * the fast path was taken, or null to fall through to the full manual wizard.
+ *
+ * Priority (mirrors detectEnvironment): a live local Ollama/LM Studio with a
+ * model → a signed-in ChatGPT/xAI subscription. When Ollama is running but has
+ * no model, we offer to pull a small coding model so the free path still works.
+ */
+async function runQuickStart(rl, snapshot, projectDir) {
+    const free = snapshot.recommendedFree;
+    const ollama = snapshot.capabilities.find((c) => c.id === 'ollama');
+    // Case A: a ready free path exists — offer it directly.
+    if (free) {
+        const answer = (await ask(rl, `Start now on ${free.label} — free, no API key needed? (Y/n)`, 'y')).toLowerCase();
+        if (answer === 'y' || answer === 'yes' || answer === '') {
+            const guide = getProviderGuide(free.id);
+            if (free.id === 'ollama' || free.id === 'lmstudio') {
+                const model = await selectModel(rl, guide, free.models);
+                await persistProviderSelection({ ...guide, baseURL: free.baseURL ?? guide.baseURL }, model, '');
+                return finishQuickStart(free.id, model, free.baseURL, projectDir);
+            }
+            // OAuth path (chatgpt / xai) — already signed in, just persist the choice.
+            const model = guide.defaultModel;
+            await persistProviderSelection(guide, model, '');
+            return finishQuickStart(free.id, model, guide.baseURL, projectDir);
+        }
+        return null; // user declined the fast path → full menu
+    }
+    // Case B: Ollama is running but empty — offer to pull a model, then use it.
+    if (ollama?.available && !(ollama.models?.length)) {
+        const DEFAULT_PULL = 'qwen2.5-coder:7b';
+        const answer = (await ask(rl, `Ollama is running but has no model. Pull ${DEFAULT_PULL} now (free, ~4.5 GB)? (Y/n)`, 'y')).toLowerCase();
+        if (answer === 'y' || answer === 'yes' || answer === '') {
+            const pulled = await pullOllamaModel(DEFAULT_PULL);
+            if (pulled) {
+                const guide = getProviderGuide('ollama');
+                await persistProviderSelection({ ...guide, baseURL: ollama.baseURL ?? guide.baseURL }, pulled, '');
+                return finishQuickStart('ollama', pulled, ollama.baseURL, projectDir);
+            }
+            console.log('  ⚠️ Pull did not complete — falling back to the full setup menu.');
+        }
+    }
+    return null;
+}
+/** Persist config.json + build the OnboardingResult for a fast-path selection. */
+function finishQuickStart(provider, model, baseURL, projectDir) {
+    const guide = getProviderGuide(provider);
+    const result = {
+        provider,
+        apiKey: '',
+        model,
+        ttsEnabled: false,
+        authMode: guide.authMode,
+        recommendedNextCommands: buildRecommendedNextCommands({ provider, apiKey: '', model }),
+    };
+    applyOnboardingProjectConfig(projectDir, result);
+    console.log('');
+    console.log('  ✅ You\'re set — no environment variable needed.');
+    console.log('');
+    console.log(`  Provider:  ${provider}${baseURL ? ` (${baseURL})` : ''}`);
+    console.log(`  Model:     ${model}`);
+    console.log('');
+    return result;
+}
+/** Offer to run the isolated 60-second demo right after setup — ending the
+ *  wizard on proof (a green test), not prose. */
+async function offerTry(rl) {
+    const answer = (await ask(rl, 'Run the 60-second demo now to confirm it works? (Y/n)', 'y')).toLowerCase();
+    if (answer === 'y' || answer === 'yes' || answer === '') {
+        try {
+            const { runTryDemo } = await import('../commands/try.js');
+            rl.pause();
+            await runTryDemo();
+            rl.resume();
+        }
+        catch {
+            console.log('\n  Run it yourself anytime with:  buddy try\n');
+        }
+    }
+    else {
+        console.log('\n  When you\'re ready:  buddy try\n');
+    }
+}
 export async function runOnboarding() {
+    if (!isInteractiveTerminal(process.stdin, process.stdout)) {
+        console.error(NON_INTERACTIVE_ONBOARDING_MESSAGE);
+        return null;
+    }
+    // 0. Detect what's already usable BEFORE opening readline — the probes are
+    //    async (~1.5s), and holding an open readline across them can race a
+    //    piped/non-interactive stdin to EOF. Detection needs no input anyway.
+    const snapshot = await detectEnvironment();
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
@@ -396,10 +552,25 @@ export async function runOnboarding() {
         console.log('');
         console.log('  This wizard will help you configure Code Buddy.');
         console.log('');
+        console.log(renderDetectionSummary(snapshot));
+        console.log('');
+        const folderAnswer = await ask(rl, PROJECT_FOLDER_QUESTION, process.cwd());
+        const projectDir = resolveOnboardingProjectDir(folderAnswer);
+        console.log(`  Project folder: ${projectDir}`);
+        console.log('');
+        const quick = await runQuickStart(rl, snapshot, projectDir);
+        if (quick) {
+            console.log(renderCapabilitiesFooter());
+            console.log('');
+            await offerTry(rl);
+            return quick;
+        }
         console.log(renderOnboardingRoadmap());
         console.log('');
-        // 1. Provider selection
-        const provider = await askChoice(rl, 'Which AI provider do you want to use?', PROVIDER_GUIDES.map((guide) => `${guide.id} — ${guide.label}`), 0).then((choice) => choice.split(/\s+—\s+/)[0] ?? choice);
+        // 1. Provider selection — detected/free options float to the top, and the
+        //    default lands on the recommended free path when there is one.
+        const orderedGuides = orderGuidesByDetection(snapshot);
+        const provider = await askChoice(rl, 'Which AI provider do you want to use?', orderedGuides.map((guide) => `${guide.id} — ${guide.label}`), 0).then((choice) => choice.split(/\s+—\s+/)[0] ?? choice);
         const guide = getProviderGuide(provider);
         const validationConfig = getValidationConfigForGuide(provider);
         // 2. Authentication — captured AND verified inline so you leave the wizard
@@ -480,8 +651,8 @@ export async function runOnboarding() {
             recommendedNextCommands: buildRecommendedNextCommands({ provider, apiKey, model }),
             ...(ttsProvider ? { ttsProvider } : {}),
         };
-        // 6. Write project config
-        writeConfig(join(process.cwd(), '.codebuddy'), result);
+        // 6. Write project config into the folder the user chose
+        applyOnboardingProjectConfig(projectDir, result);
         // 7. Summary
         const ready = verified || (guide.authMode === 'api-key' && Boolean(apiKey));
         console.log('');
@@ -515,6 +686,10 @@ export async function runOnboarding() {
         console.log('');
         console.log(renderOnboardingRoadmap(result));
         console.log('');
+        // Close with a real, runnable test so the wizard ends on proof, not prose.
+        if (ready) {
+            await offerTry(rl);
+        }
         return result;
     }
     finally {