@vinaes/succ 1.3.19

package/dist/lib/md-fetch.d.ts

@@ -0,0 +1,61 @@
+/**
+ * md.succ.ai client — fetches URLs and converts to clean Markdown.
+ *
+ * Uses the md.succ.ai HTML→Markdown API with Readability content extraction
+ * and optional Playwright fallback for JS-heavy pages.
+ */
+export interface MdFetchResult {
+    title: string;
+    url: string;
+    content: string;
+    excerpt: string;
+    byline: string;
+    siteName: string;
+    tokens: number;
+    tier: string;
+    readability: boolean;
+    method: string;
+    quality: {
+        score: number;
+        grade: string;
+    };
+    time_ms: number;
+    /** LLM-optimized content (only when mode=fit) */
+    fitContent?: string;
+    /** Token count of fit content */
+    fitTokens?: number;
+}
+export interface MdFetchOptions {
+    /** Base URL of md.succ.ai instance (default: config md_api_url or https://md.succ.ai) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Prune boilerplate for LLM context (30-50% fewer tokens) */
+    mode?: 'fit';
+    /** Convert inline links to numbered references with footer */
+    links?: 'citations';
+    /** Truncate output to N tokens (used with mode=fit) */
+    maxTokens?: number;
+}
+/**
+ * Fetch a URL and convert to clean Markdown via md.succ.ai.
+ *
+ * @param url - Target URL to fetch and convert
+ * @param options - Optional base URL and timeout overrides
+ * @returns Parsed conversion result with markdown content and metadata
+ */
+export declare function fetchAsMarkdown(url: string, options?: MdFetchOptions): Promise<MdFetchResult>;
+export interface ExtractResult {
+    valid: boolean;
+    data: Record<string, unknown>;
+    url: string;
+    error?: string;
+}
+/**
+ * Extract structured data from a URL using a JSON schema via md.succ.ai /extract.
+ *
+ * The LLM reads the page content and returns JSON matching the provided schema.
+ * Automatically retries with headless browser for SPA/JS-heavy sites.
+ */
+export declare function extractFromUrl(url: string, schema: Record<string, unknown>, options?: Pick<MdFetchOptions, 'baseUrl' | 'timeout'>): Promise<ExtractResult>;
+//# sourceMappingURL=md-fetch.d.ts.map

package/dist/lib/md-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"md-fetch.d.ts","sourceRoot":"","sources":["../../src/lib/md-fetch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,CAoFxB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,SAAS,CAAC,GACpD,OAAO,CAAC,aAAa,CAAC,CA2CxB"}

package/dist/lib/md-fetch.js

@@ -0,0 +1,141 @@
+/**
+ * md.succ.ai client — fetches URLs and converts to clean Markdown.
+ *
+ * Uses the md.succ.ai HTML→Markdown API with Readability content extraction
+ * and optional Playwright fallback for JS-heavy pages.
+ */
+import { getConfig } from './config.js';
+const DEFAULT_MD_API_URL = 'https://md.succ.ai';
+const DEFAULT_TIMEOUT = 300_000;
+/**
+ * Fetch a URL and convert to clean Markdown via md.succ.ai.
+ *
+ * @param url - Target URL to fetch and convert
+ * @param options - Optional base URL and timeout overrides
+ * @returns Parsed conversion result with markdown content and metadata
+ */
+export async function fetchAsMarkdown(url, options) {
+    let baseUrl = options?.baseUrl;
+    if (!baseUrl) {
+        try {
+            const config = getConfig();
+            baseUrl = config.md_api_url || DEFAULT_MD_API_URL;
+        }
+        catch {
+            baseUrl = DEFAULT_MD_API_URL;
+        }
+    }
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    // Only allow http(s) URLs to prevent SSRF via md.succ.ai
+    if (!/^https?:\/\//i.test(url)) {
+        throw new Error('Only http:// and https:// URLs are supported');
+    }
+    // Ensure base URL has no trailing slash
+    const base = baseUrl.replace(/\/+$/, '');
+    // Encode the target URL as path segment, append API query params
+    const params = new URLSearchParams();
+    if (options?.mode)
+        params.set('mode', options.mode);
+    if (options?.links)
+        params.set('links', options.links);
+    if (options?.maxTokens)
+        params.set('max_tokens', String(options.maxTokens));
+    const qs = params.toString();
+    const apiUrl = `${base}/${encodeURIComponent(url)}${qs ? '?' + qs : ''}`;
+    // Retry with exponential backoff for transient network failures
+    let response;
+    let lastErr;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            response = await fetch(apiUrl, {
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json',
+                },
+                signal: AbortSignal.timeout(timeout),
+            });
+            lastErr = undefined;
+            break;
+        }
+        catch (e) {
+            lastErr = e instanceof Error ? e : new Error(String(e));
+            if (attempt < 2) {
+                await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+            }
+        }
+    }
+    if (!response)
+        throw lastErr ?? new Error('fetch failed after 3 retries');
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`md.succ.ai error: HTTP ${response.status} — ${body.slice(0, 200)}`);
+    }
+    const data = await response.json();
+    // Validate minimum required fields
+    if (!data.content && !data.error) {
+        throw new Error('md.succ.ai returned empty content');
+    }
+    if (data.error) {
+        throw new Error(`md.succ.ai conversion failed: ${data.error}`);
+    }
+    return {
+        title: data.title || '',
+        url: data.url || url,
+        content: data.content || '',
+        excerpt: data.excerpt || '',
+        byline: data.byline || '',
+        siteName: data.siteName || '',
+        tokens: data.tokens || 0,
+        tier: data.tier || 'unknown',
+        readability: data.readability ?? false,
+        method: data.method || 'unknown',
+        quality: data.quality || { score: 0, grade: 'F' },
+        time_ms: data.time_ms || 0,
+        fitContent: data.fit_markdown ?? undefined,
+        fitTokens: data.fit_tokens ?? undefined,
+    };
+}
+/**
+ * Extract structured data from a URL using a JSON schema via md.succ.ai /extract.
+ *
+ * The LLM reads the page content and returns JSON matching the provided schema.
+ * Automatically retries with headless browser for SPA/JS-heavy sites.
+ */
+export async function extractFromUrl(url, schema, options) {
+    let baseUrl = options?.baseUrl;
+    if (!baseUrl) {
+        try {
+            const config = getConfig();
+            baseUrl = config.md_api_url || DEFAULT_MD_API_URL;
+        }
+        catch {
+            baseUrl = DEFAULT_MD_API_URL;
+        }
+    }
+    const timeout = options?.timeout ?? 60_000; // extraction can be slow
+    if (!/^https?:\/\//i.test(url)) {
+        throw new Error('Only http:// and https:// URLs are supported');
+    }
+    const base = baseUrl.replace(/\/+$/, '');
+    const apiUrl = `${base}/extract`;
+    const response = await fetch(apiUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ url, schema }),
+        signal: AbortSignal.timeout(timeout),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`md.succ.ai /extract error: HTTP ${response.status} — ${body.slice(0, 200)}`);
+    }
+    const data = await response.json();
+    if (data.error) {
+        throw new Error(`md.succ.ai extraction failed: ${data.error}`);
+    }
+    return {
+        valid: data.valid ?? true,
+        data: data.data || {},
+        url: data.url || url,
+    };
+}
+//# sourceMappingURL=md-fetch.js.map

package/dist/lib/md-fetch.js.map

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

package/dist/lib/mmr.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Maximal Marginal Relevance (MMR) diversity reranking.
+ *
+ * Re-ranks search results to balance relevance and diversity,
+ * reducing near-duplicate results in recall output.
+ *
+ * Formula: MMR(d) = λ * sim(q, d) - (1 - λ) * max(sim(d, d_selected))
+ *
+ * λ = 1.0: pure relevance (no diversity penalty)
+ * λ = 0.0: pure diversity (maximum distance from selected)
+ * λ = 0.8: conservative default — relevance dominates, mild diversity
+ */
+export interface MMRItem {
+    id: number;
+    similarity: number;
+    embedding?: number[] | null;
+    [key: string]: unknown;
+}
+/**
+ * Apply MMR reranking to search results.
+ *
+ * @param results - Search results with similarity scores and optional embeddings
+ * @param queryEmbedding - The query embedding vector
+ * @param lambda - Balance between relevance (1.0) and diversity (0.0). Default: 0.8
+ * @param limit - Max results to return. Default: results.length
+ * @returns Reranked results with updated similarity scores
+ */
+export declare function applyMMR<T extends MMRItem>(results: T[], queryEmbedding: number[], lambda?: number, limit?: number): T[];
+//# sourceMappingURL=mmr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mmr.d.ts","sourceRoot":"","sources":["../../src/lib/mmr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoBH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EACxC,OAAO,EAAE,CAAC,EAAE,EACZ,cAAc,EAAE,MAAM,EAAE,EACxB,MAAM,GAAE,MAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,CAAC,EAAE,CAsDL"}

package/dist/lib/mmr.js

@@ -0,0 +1,89 @@
+/**
+ * Maximal Marginal Relevance (MMR) diversity reranking.
+ *
+ * Re-ranks search results to balance relevance and diversity,
+ * reducing near-duplicate results in recall output.
+ *
+ * Formula: MMR(d) = λ * sim(q, d) - (1 - λ) * max(sim(d, d_selected))
+ *
+ * λ = 1.0: pure relevance (no diversity penalty)
+ * λ = 0.0: pure diversity (maximum distance from selected)
+ * λ = 0.8: conservative default — relevance dominates, mild diversity
+ */
+/**
+ * Cosine similarity between two vectors.
+ * Returns value in [-1, 1], typically [0, 1] for normalized embeddings.
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/**
+ * Apply MMR reranking to search results.
+ *
+ * @param results - Search results with similarity scores and optional embeddings
+ * @param queryEmbedding - The query embedding vector
+ * @param lambda - Balance between relevance (1.0) and diversity (0.0). Default: 0.8
+ * @param limit - Max results to return. Default: results.length
+ * @returns Reranked results with updated similarity scores
+ */
+export function applyMMR(results, queryEmbedding, lambda = 0.8, limit) {
+    // Nothing to rerank
+    if (results.length <= 1)
+        return results;
+    // Filter to results that have embeddings — skip those without
+    const withEmbedding = results.filter((r) => r.embedding && r.embedding.length > 0);
+    const withoutEmbedding = results.filter((r) => !r.embedding || r.embedding.length === 0);
+    if (withEmbedding.length === 0)
+        return results;
+    const maxResults = limit ?? results.length;
+    const selected = [];
+    const candidates = [...withEmbedding];
+    // Greedily select items using MMR criterion
+    while (selected.length < maxResults && candidates.length > 0) {
+        let bestIdx = -1;
+        let bestScore = -Infinity;
+        for (let i = 0; i < candidates.length; i++) {
+            const candidate = candidates[i];
+            const relevance = candidate.similarity;
+            // Max similarity to any already-selected item
+            let maxSimToSelected = 0;
+            if (selected.length > 0 && candidate.embedding) {
+                for (const sel of selected) {
+                    if (sel.embedding) {
+                        const sim = cosineSimilarity(candidate.embedding, sel.embedding);
+                        if (sim > maxSimToSelected)
+                            maxSimToSelected = sim;
+                    }
+                }
+            }
+            const mmrScore = lambda * relevance - (1 - lambda) * maxSimToSelected;
+            if (mmrScore > bestScore) {
+                bestScore = mmrScore;
+                bestIdx = i;
+            }
+        }
+        if (bestIdx >= 0) {
+            const item = candidates.splice(bestIdx, 1)[0];
+            // Update similarity to reflect MMR score for consistent sorting downstream
+            selected.push({ ...item, similarity: bestScore });
+        }
+        else {
+            break;
+        }
+    }
+    // Append items without embeddings at the end (they couldn't be MMR-ranked)
+    const result = [...selected, ...withoutEmbedding].slice(0, maxResults);
+    return result;
+}
+//# sourceMappingURL=mmr.js.map

package/dist/lib/mmr.js.map

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

package/dist/lib/onboarding/ai-chat.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AI-Powered Onboarding Chat
+ *
+ * Interactive onboarding using an LLM (chat_llm config).
+ * More personalized experience (~3-5 min).
+ */
+/**
+ * Run AI-powered interactive onboarding
+ */
+export declare function runAiOnboarding(): Promise<void>;
+//# sourceMappingURL=ai-chat.d.ts.map

package/dist/lib/onboarding/ai-chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-chat.d.ts","sourceRoot":"","sources":["../../../src/lib/onboarding/ai-chat.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAyErD"}

package/dist/lib/onboarding/ai-chat.js

@@ -0,0 +1,85 @@
+/**
+ * AI-Powered Onboarding Chat
+ *
+ * Interactive onboarding using an LLM (chat_llm config).
+ * More personalized experience (~3-5 min).
+ */
+import * as readline from 'readline';
+import { ONBOARDING_SYSTEM_PROMPT } from '../../prompts/index.js';
+import { callLLMChat } from '../llm.js';
+import { markOnboardingCompleted } from '../config.js';
+import { logError } from '../fault-logger.js';
+function createReadline() {
+    return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+async function prompt(rl, question) {
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Run AI-powered interactive onboarding
+ */
+export async function runAiOnboarding() {
+    const rl = createReadline();
+    try {
+        console.clear();
+        console.log('Starting AI-powered onboarding...\n');
+        console.log('Type "done", "skip", or "exit" at any time to finish.\n');
+        console.log('---\n');
+        const messages = [{ role: 'system', content: ONBOARDING_SYSTEM_PROMPT }];
+        // Get initial greeting from AI
+        try {
+            const greeting = await callLLMChat(messages, { timeout: 30000 });
+            console.log(`succ: ${greeting}\n`);
+            messages.push({ role: 'assistant', content: greeting });
+        }
+        catch (error) {
+            logError('onboarding', 'Failed to connect to LLM, falling back to static wizard', error instanceof Error ? error : undefined);
+            rl.close();
+            // Import dynamically to avoid circular dependency
+            const { runStaticWizard } = await import('./wizard.js');
+            await runStaticWizard();
+            return;
+        }
+        // Chat loop
+        let turnCount = 0;
+        const maxTurns = 15; // Prevent infinite loops
+        while (turnCount < maxTurns) {
+            const userInput = await prompt(rl, 'You: ');
+            // Check for exit commands
+            if (['done', 'skip', 'exit', 'quit', 'q'].includes(userInput.toLowerCase())) {
+                console.log('\nGreat! Moving on to setup...\n');
+                break;
+            }
+            // Check for empty input
+            if (!userInput) {
+                continue;
+            }
+            messages.push({ role: 'user', content: userInput });
+            try {
+                const response = await callLLMChat(messages, { timeout: 30000 });
+                console.log(`\nsucc: ${response}\n`);
+                messages.push({ role: 'assistant', content: response });
+            }
+            catch (error) {
+                logError('onboarding', 'Error getting response', error instanceof Error ? error : undefined);
+            }
+            turnCount++;
+        }
+        if (turnCount >= maxTurns) {
+            console.log('\nOnboarding session limit reached. Moving on to setup...\n');
+        }
+        // Mark completed
+        markOnboardingCompleted('ai-chat');
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=ai-chat.js.map

package/dist/lib/onboarding/ai-chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-chat.js","sourceRoot":"","sources":["../../../src/lib/onboarding/ai-chat.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,7 @@
+/**
+ * Onboarding Module Exports
+ */
+export { runStaticWizard } from './wizard.js';
+export { runAiOnboarding } from './ai-chat.js';
+export { ONBOARDING_SYSTEM_PROMPT } from '../../prompts/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/onboarding/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/lib/onboarding/index.js

@@ -0,0 +1,7 @@
+/**
+ * Onboarding Module Exports
+ */
+export { runStaticWizard } from './wizard.js';
+export { runAiOnboarding } from './ai-chat.js';
+export { ONBOARDING_SYSTEM_PROMPT } from '../../prompts/index.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/onboarding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/onboarding/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,11 @@
+/**
+ * Static Onboarding Wizard
+ *
+ * Quick interactive onboarding (~2 min) using predefined screens.
+ * For users who don't want AI-powered chat or don't have LLM configured.
+ */
+/**
+ * Run the static onboarding wizard
+ */
+export declare function runStaticWizard(): Promise<void>;
+//# sourceMappingURL=wizard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.d.ts","sourceRoot":"","sources":["../../../src/lib/onboarding/wizard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6CH;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAyErD"}

package/dist/lib/onboarding/wizard.js

@@ -0,0 +1,104 @@
+/**
+ * Static Onboarding Wizard
+ *
+ * Quick interactive onboarding (~2 min) using predefined screens.
+ * For users who don't want AI-powered chat or don't have LLM configured.
+ */
+import * as readline from 'readline';
+import { WIZARD_INTRO, WIZARD_DISCOVERY_PROJECT, WIZARD_DISCOVERY_FRUSTRATION, WIZARD_SOLUTION_MAP, WIZARD_CONCEPTS_OVERVIEW, WIZARD_HANDS_ON_PROMPT, WIZARD_CHEATSHEET, WIZARD_DONE, } from '../../prompts/index.js';
+import { markOnboardingCompleted } from '../config.js';
+function createReadline() {
+    return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+async function prompt(rl, question) {
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            resolve(answer.trim());
+        });
+    });
+}
+async function waitForEnter(rl) {
+    await prompt(rl, '\nPress Enter to continue...');
+}
+async function selectOption(rl, options) {
+    while (true) {
+        const answer = await prompt(rl, '\nYour choice (1-' + options.length + '): ');
+        const num = parseInt(answer, 10);
+        if (num >= 1 && num <= options.length) {
+            return num;
+        }
+        console.log('Please enter a number between 1 and ' + options.length);
+    }
+}
+/**
+ * Run the static onboarding wizard
+ */
+export async function runStaticWizard() {
+    const rl = createReadline();
+    try {
+        // Screen 1: Intro
+        console.clear();
+        console.log(WIZARD_INTRO);
+        await waitForEnter(rl);
+        // Screen 2: Project type discovery
+        console.clear();
+        console.log(WIZARD_DISCOVERY_PROJECT);
+        const projectOptions = [
+            'Web application',
+            'CLI tool / library',
+            'Mobile app',
+            'Something else',
+        ];
+        const projectChoice = await selectOption(rl, projectOptions);
+        const projectType = projectOptions[projectChoice - 1];
+        // Screen 3: Frustration discovery
+        console.clear();
+        console.log(WIZARD_DISCOVERY_FRUSTRATION);
+        const frustrationOptions = [
+            'Forgets context between sessions',
+            "Doesn't know my codebase patterns",
+            'I have to repeat decisions',
+            'Takes time to explain project structure',
+        ];
+        const frustrationChoice = await selectOption(rl, frustrationOptions);
+        // Screen 4: Solution mapping based on frustration
+        console.clear();
+        const frustrationKeys = ['forgets', 'codebase', 'repeat', 'structure'];
+        const frustrationKey = frustrationKeys[frustrationChoice - 1];
+        console.log(`\nGreat! You're building a ${projectType.toLowerCase()}.\n`);
+        console.log(WIZARD_SOLUTION_MAP[frustrationKey]);
+        await waitForEnter(rl);
+        // Screen 5: Concepts overview
+        console.clear();
+        console.log(WIZARD_CONCEPTS_OVERVIEW);
+        await waitForEnter(rl);
+        // Screen 6: Hands-on (optional)
+        console.clear();
+        console.log(WIZARD_HANDS_ON_PROMPT);
+        const decision = await prompt(rl, '> ');
+        if (decision) {
+            console.log('\nNice! Once setup is complete, this will be stored as:');
+            console.log('');
+            console.log(`  succ_remember content="${decision}" type="decision"`);
+            console.log('');
+            console.log('The AI will be able to recall this in future sessions!');
+            await waitForEnter(rl);
+        }
+        // Screen 7: Cheatsheet
+        console.clear();
+        console.log(WIZARD_CHEATSHEET);
+        await waitForEnter(rl);
+        // Screen 8: Done
+        console.clear();
+        console.log(WIZARD_DONE);
+        // Mark completed
+        markOnboardingCompleted('wizard');
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=wizard.js.map

package/dist/lib/onboarding/wizard.js.map

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

package/dist/lib/ort-provider.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ONNX Runtime Execution Provider auto-detection.
+ *
+ * Selects the best provider per platform:
+ * - Windows: dml (DirectML, any GPU vendor, bundled)
+ * - macOS arm64: coreml (Apple Silicon, bundled)
+ * - Linux: cuda (requires user-installed CUDA 12)
+ * - All platforms: cpu as fallback (4.6x faster than WASM)
+ *
+ * Note: onnxruntime-node 1.25+ uses short backend names ('cpu', 'dml', 'cuda', 'coreml')
+ * instead of legacy 'CPUExecutionProvider', 'DmlExecutionProvider', etc.
+ */
+export interface OrtProviderOptions {
+    gpu_enabled?: boolean;
+    gpu_device?: 'cuda' | 'directml' | 'coreml' | 'webgpu' | 'cpu';
+    arch?: string;
+}
+export interface OrtProviderResult {
+    /** Primary provider to try first */
+    provider: string;
+    /** Full fallback chain including primary, ending with cpu */
+    fallbackChain: string[];
+    /** Warning message if the requested config can't be honored */
+    warning?: string;
+}
+export declare function detectExecutionProvider(platform: string, options?: OrtProviderOptions): OrtProviderResult;
+//# sourceMappingURL=ort-provider.d.ts.map

package/dist/lib/ort-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ort-provider.d.ts","sourceRoot":"","sources":["../../src/lib/ort-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAqCnB"}