skrypt-ai 0.6.1 → 0.7.0

package/dist/commands/generate.js

@@ -1,15 +1,38 @@
 import { Command } from 'commander';
-import { existsSync, copyFileSync, mkdirSync, readFileSync } from 'fs';
+import { existsSync, copyFileSync, mkdirSync, readFileSync, rmSync } from 'fs';
 import { resolve, basename, dirname, join } from 'path';
-import { loadConfig, validateConfig, checkApiKey } from '../config/index.js';
+import { loadConfig, validateConfig, checkApiKey, resolveSourceEntries } from '../config/index.js';
 import { DEFAULT_MODELS } from '../config/types.js';
 import { scanDirectory } from '../scanner/index.js';
 import { createLLMClient } from '../llm/index.js';
 import { generateForElements, groupDocsByFile, writeDocsToDirectory, writeDocsByTopic, writeLlmsTxt } from '../generator/index.js';
 import { showSecurityNotice } from '../auth/notices.js';
+import { requirePro } from '../auth/index.js';
 import { runQA, printQAReport, fixQAIssues, printFixReport } from '../qa/index.js';
 import { extractDependencyIds, isChubInstalled, fetchContextHubDocs, exportToContextHub } from '../context-hub/index.js';
+import { discoverOrgRepos, cloneRepoToTemp } from '../github/org-discovery.js';
+import { extractSnippets, findDocFiles, runLocally, loadEnvFile } from '../testing/index.js';
+import { writeManifest, buildManifestEntries } from '../refresh/manifest.js';
+import { planSmartStructure, generateWithStructure } from '../structure/index.js';
 import * as readline from 'readline';
+/**
+ * Parse source arguments with optional labels.
+ * e.g. "./api:API" → { path: "./api", label: "API" }
+ * e.g. "./src" → { path: "./src" }
+ */
+export function parseSourceArgs(args) {
+    return args.map(arg => {
+        const colonIdx = arg.lastIndexOf(':');
+        // Only treat as label separator if colon is not part of a path (e.g. C:\)
+        if (colonIdx > 1 && !arg.substring(0, colonIdx).endsWith('\\')) {
+            return {
+                path: arg.substring(0, colonIdx),
+                label: arg.substring(colonIdx + 1),
+            };
+        }
+        return { path: arg };
+    });
+}
 /**
  * Read .skryptignore patterns from source directory
  */
@@ -105,7 +128,7 @@ function shouldExcludeElement(element, patterns) {
 }
 export const generateCommand = new Command('generate')
     .description('Generate documentation with code examples')
-    .argument('<source>', 'Source directory to scan')
+    .argument('[sources...]', 'Source directories to scan (use dir:Label for labels)')
     .option('-o, --output <dir>', 'Output directory')
     .option('-c, --config <file>', 'Config file path')
     .option('--provider <name>', 'LLM provider (deepseek, openai, anthropic, google, ollama, openrouter)')
@@ -119,14 +142,26 @@ export const generateCommand = new Command('generate')
     .option('--exclude <patterns...>', 'Exclude patterns (files, names, or name:pattern)')
     .option('--llms-txt', 'Generate llms.txt for Answer Engine Optimization (AEO)')
     .option('--project-name <name>', 'Project name for llms.txt header')
-    .action(async (source, options) => {
+    .option('--org <name>', 'GitHub organization to discover repos from')
+    .option('--repos <list>', 'Comma-separated list of repos to include (with --org)')
+    .option('--exclude-repos <list>', 'Comma-separated list of repos to exclude (with --org)')
+    .option('--verify', 'Verify generated code examples by running them (Pro)')
+    .option('--env-file <file>', 'Load environment variables for code verification')
+    .option('--smart-structure', 'Organize docs by user journey instead of file structure (Pro)')
+    .option('--max-verify-iterations <n>', 'Max re-generation attempts for failing snippets', '2')
+    .action(async (sources = [], options) => {
     try {
         const startTime = Date.now();
+        // Require at least one source or --org
+        if (sources.length === 0 && !options.org) {
+            console.error('Error: At least one source directory is required (or use --org)');
+            process.exit(1);
+        }
         // Load config (file or defaults)
         const config = loadConfig(options.config);
-        // CLI flags override config
-        if (source)
-            config.source.path = source;
+        // CLI flags override config — first source is used for single-source compat
+        if (sources.length > 0)
+            config.source.path = sources[0];
         if (options.output)
             config.output.path = options.output;
         if (options.provider) {
@@ -160,10 +195,29 @@ export const generateCommand = new Command('generate')
                 process.exit(1);
             }
         }
+        // Pro-gated flags
+        if (options.verify) {
+            if (!await requirePro('generate --verify')) {
+                process.exit(1);
+            }
+        }
+        if (options.smartStructure) {
+            if (!await requirePro('generate --smart-structure')) {
+                process.exit(1);
+            }
+        }
         // First-run security notice
         showSecurityNotice();
         console.log('skrypt generate');
-        console.log(`  source:   ${config.source.path}`);
+        if (options.org) {
+            console.log(`  source:   org:${options.org}`);
+        }
+        else if (sources.length > 1) {
+            console.log(`  sources:  ${sources.join(', ')}`);
+        }
+        else {
+            console.log(`  source:   ${config.source.path}`);
+        }
         console.log(`  output:   ${config.output.path}`);
         console.log(`  provider: ${config.llm.provider}`);
         console.log(`  model:    ${config.llm.model}`);
@@ -185,257 +239,497 @@ export const generateCommand = new Command('generate')
             console.log('  routing:  via Skrypt API proxy');
         }
         console.log('');
-        // Check source exists
-        const sourcePath = resolve(config.source.path);
-        if (!existsSync(sourcePath)) {
-            console.error(`Error: Source directory not found: ${sourcePath}`);
-            process.exit(1);
-        }
-        // Step 1: Scan source code
-        console.log('Step 1: Scanning source code...');
-        const scanResult = await scanDirectory(sourcePath, {
-            include: config.source.include,
-            exclude: config.source.exclude,
-            onProgress: (current, total, file) => {
-                process.stdout.write(`\r  [${current}/${total}] ${file.slice(-50).padStart(50)}`);
+        // Resolve source entries: CLI args, --org, or config file
+        let sourceEntries;
+        const tempDirs = [];
+        if (options.org) {
+            // GitHub org discovery mode
+            const token = process.env.GITHUB_TOKEN;
+            if (!token) {
+                console.error('Error: GITHUB_TOKEN environment variable required for --org');
+                process.exit(1);
             }
-        });
-        console.log('');
-        if (scanResult.errors.length > 0) {
-            console.log('\n  Scan warnings:');
-            scanResult.errors.slice(0, 5).forEach(e => console.log(`    - ${e}`));
-            if (scanResult.errors.length > 5) {
-                console.log(`    ... and ${scanResult.errors.length - 5} more`);
+            console.log(`Discovering repos in org "${options.org}"...`);
+            const repoWhitelist = options.repos ? options.repos.split(',').map(r => r.trim()) : undefined;
+            const repoBlacklist = options.excludeRepos ? options.excludeRepos.split(',').map(r => r.trim()) : undefined;
+            let discoveredRepos = await discoverOrgRepos(options.org, token);
+            if (repoWhitelist) {
+                discoveredRepos = discoveredRepos.filter(r => repoWhitelist.includes(r.name));
             }
-        }
-        console.log(`\n  Found ${scanResult.totalElements} API elements in ${scanResult.files.length} files`);
-        if (scanResult.totalElements === 0) {
-            console.log('  No API elements found. Nothing to generate.');
-            process.exit(0);
-        }
-        // Collect all elements
-        let allElements = [];
-        for (const file of scanResult.files) {
-            for (const el of file.elements) {
-                allElements.push(el);
+            if (repoBlacklist) {
+                discoveredRepos = discoveredRepos.filter(r => !repoBlacklist.includes(r.name));
             }
-        }
-        // Apply privacy filters
-        const initialCount = allElements.length;
-        // 1. --public-only: filter to exported/public APIs only
-        if (options.publicOnly) {
-            allElements = allElements.filter(el => el.isExported === true || el.isPublic === true);
-            console.log(`  --public-only: filtered to ${allElements.length} exported APIs`);
-        }
-        // 2. Load .skryptignore patterns
-        const ignorePatterns = readIgnorePatterns(sourcePath);
-        if (ignorePatterns.length > 0) {
-            console.log(`  .skryptignore: loaded ${ignorePatterns.length} patterns`);
-        }
-        // 3. Combine with --exclude patterns
-        const excludePatterns = [...ignorePatterns, ...(options.exclude || [])];
-        if (excludePatterns.length > 0) {
-            allElements = allElements.filter(el => !shouldExcludeElement(el, excludePatterns));
-            if (options.exclude?.length) {
-                console.log(`  --exclude: applied ${options.exclude.length} additional patterns`);
+            console.log(`  Found ${discoveredRepos.length} repos`);
+            sourceEntries = [];
+            for (const repo of discoveredRepos) {
+                console.log(`  Cloning ${repo.full_name}...`);
+                const tempDir = await cloneRepoToTemp(repo, token);
+                tempDirs.push(tempDir);
+                sourceEntries.push({
+                    path: tempDir,
+                    label: repo.name,
+                    include: config.source.include,
+                    exclude: config.source.exclude,
+                });
             }
         }
-        if (initialCount !== allElements.length) {
-            console.log(`  Filtered: ${initialCount} -> ${allElements.length} elements`);
+        else if (sources.length > 1) {
+            // Multiple CLI args
+            sourceEntries = parseSourceArgs(sources);
         }
-        // Show summary by kind
-        const byKind = {};
-        for (const el of allElements) {
-            byKind[el.kind] = (byKind[el.kind] || 0) + 1;
-        }
-        const pluralize = (word, count) => {
-            if (count === 1)
-                return word;
-            if (word === 'class')
-                return 'classes';
-            return word + 's';
-        };
-        console.log('  ' + Object.entries(byKind).map(([k, v]) => `${v} ${pluralize(k, v)}`).join(', '));
-        // Dry run - stop here
-        if (options.dryRun) {
-            console.log('\n[dry run - stopping before generation]');
-            process.exit(0);
+        else {
+            // Single source or config file sources
+            sourceEntries = resolveSourceEntries(config);
+        }
+        const isMultiSource = sourceEntries.length > 1 || sourceEntries.some(s => s.label);
+        // Check all source paths exist
+        for (const entry of sourceEntries) {
+            const sourcePath = resolve(entry.path);
+            if (!existsSync(sourcePath)) {
+                console.error(`Error: Source directory not found: ${sourcePath}`);
+                process.exit(1);
+            }
         }
-        // Auto-read project context from README for richer doc generation
-        let projectContext;
-        const readmeCandidates = ['README.md', 'README.mdx', 'readme.md', 'README.rst', 'README.txt'];
-        for (const candidate of readmeCandidates) {
-            const readmePath = join(sourcePath, candidate);
-            if (existsSync(readmePath)) {
-                try {
-                    const raw = readFileSync(readmePath, 'utf-8');
-                    // Take the first ~1500 chars (intro/description section, not the whole file)
-                    projectContext = raw.slice(0, 1500);
-                    console.log(`  Project context: loaded from ${candidate}`);
+        // Step 1: Scan source code from all sources
+        console.log('Step 1: Scanning source code...');
+        let allElements = [];
+        let totalFiles = 0;
+        const allScanErrors = [];
+        try {
+            for (const entry of sourceEntries) {
+                const sourcePath = resolve(entry.path);
+                if (isMultiSource) {
+                    console.log(`\n  Scanning ${entry.label || entry.path}...`);
                 }
-                catch {
-                    // Skip if unreadable
+                const scanResult = await scanDirectory(sourcePath, {
+                    include: entry.include || config.source.include,
+                    exclude: entry.exclude || config.source.exclude,
+                    onProgress: (current, total, file) => {
+                        process.stdout.write(`\r  [${current}/${total}] ${file.slice(-50).padStart(50)}`);
+                    }
+                });
+                console.log('');
+                if (scanResult.errors.length > 0) {
+                    allScanErrors.push(...scanResult.errors);
+                }
+                totalFiles += scanResult.files.length;
+                // Tag elements with source metadata
+                for (const file of scanResult.files) {
+                    for (const el of file.elements) {
+                        if (entry.label) {
+                            el.sourceLabel = entry.label;
+                        }
+                        el.sourceRoot = sourcePath;
+                        allElements.push(el);
+                    }
                 }
-                break;
             }
-        }
-        // Also check parent directory (common for monorepos where source is a subdirectory)
-        if (!projectContext) {
-            const parentReadme = join(sourcePath, '..', 'README.md');
-            if (existsSync(parentReadme)) {
-                try {
-                    projectContext = readFileSync(parentReadme, 'utf-8').slice(0, 1500);
-                    console.log('  Project context: loaded from parent README.md');
+            if (allScanErrors.length > 0) {
+                console.log('\n  Scan warnings:');
+                allScanErrors.slice(0, 5).forEach(e => console.log(`    - ${e}`));
+                if (allScanErrors.length > 5) {
+                    console.log(`    ... and ${allScanErrors.length - 5} more`);
                 }
-                catch {
-                    // Skip
+            }
+            console.log(`\n  Found ${allElements.length} API elements in ${totalFiles} files`);
+            if (allElements.length === 0) {
+                console.log('  No API elements found. Nothing to generate.');
+                return;
+            }
+            // Apply privacy filters
+            const initialCount = allElements.length;
+            // 1. --public-only: filter to exported/public APIs only
+            if (options.publicOnly) {
+                allElements = allElements.filter(el => el.isExported === true || el.isPublic === true);
+                console.log(`  --public-only: filtered to ${allElements.length} exported APIs`);
+            }
+            // 2. Load .skryptignore patterns from all source dirs
+            const ignorePatterns = [];
+            for (const entry of sourceEntries) {
+                ignorePatterns.push(...readIgnorePatterns(resolve(entry.path)));
+            }
+            if (ignorePatterns.length > 0) {
+                console.log(`  .skryptignore: loaded ${ignorePatterns.length} patterns`);
+            }
+            // 3. Combine with --exclude patterns
+            const excludePatterns = [...ignorePatterns, ...(options.exclude || [])];
+            if (excludePatterns.length > 0) {
+                allElements = allElements.filter(el => !shouldExcludeElement(el, excludePatterns));
+                if (options.exclude?.length) {
+                    console.log(`  --exclude: applied ${options.exclude.length} additional patterns`);
                 }
             }
-        }
-        // Context Hub enrichment: fetch third-party API docs if chub is installed
-        let externalContext;
-        const allImports = [];
-        for (const el of allElements) {
-            if (el.imports?.length) {
-                allImports.push(...el.imports);
+            if (initialCount !== allElements.length) {
+                console.log(`  Filtered: ${initialCount} -> ${allElements.length} elements`);
             }
-        }
-        const chubIds = extractDependencyIds(allImports);
-        if (chubIds.length > 0 && isChubInstalled()) {
-            console.log(`\n  Context Hub: fetching docs for ${chubIds.length} dependencies...`);
-            externalContext = fetchContextHubDocs(chubIds);
-            if (externalContext.size > 0) {
-                console.log(`  Context Hub: enriching with ${externalContext.size} API references`);
+            // Show summary by kind
+            const byKind = {};
+            for (const el of allElements) {
+                byKind[el.kind] = (byKind[el.kind] || 0) + 1;
             }
-        }
-        // Step 2: Generate docs
-        console.log('\nStep 2: Generating documentation...');
-        const client = createLLMClient({
-            provider: config.llm.provider,
-            model: config.llm.model,
-            baseUrl: config.llm.baseUrl
-        });
-        let lastElement = '';
-        const multiLanguage = options.multiLang ?? false;
-        if (multiLanguage) {
-            console.log('  mode: multi-language (TypeScript + Python)');
-        }
-        const docs = await generateForElements(allElements, client, {
-            multiLanguage,
-            externalContext,
-            projectContext,
-            onProgress: (progress) => {
-                if (progress.element !== lastElement) {
-                    if (lastElement)
-                        console.log('');
-                    lastElement = progress.element;
+            const pluralize = (word, count) => {
+                if (count === 1)
+                    return word;
+                if (word === 'class')
+                    return 'classes';
+                return word + 's';
+            };
+            console.log('  ' + Object.entries(byKind).map(([k, v]) => `${v} ${pluralize(k, v)}`).join(', '));
+            // Dry run - stop here
+            if (options.dryRun) {
+                console.log('\n[dry run - stopping before generation]');
+                return;
+            }
+            // Use first source path as the primary source for context/compat
+            const primarySourcePath = resolve(sourceEntries[0].path);
+            // Auto-read project context from README for richer doc generation
+            let projectContext;
+            const readmeCandidates = ['README.md', 'README.mdx', 'readme.md', 'README.rst', 'README.txt'];
+            for (const candidate of readmeCandidates) {
+                const readmePath = join(primarySourcePath, candidate);
+                if (existsSync(readmePath)) {
+                    try {
+                        const raw = readFileSync(readmePath, 'utf-8');
+                        // Take the first ~1500 chars (intro/description section, not the whole file)
+                        projectContext = raw.slice(0, 1500);
+                        console.log(`  Project context: loaded from ${candidate}`);
+                    }
+                    catch {
+                        // Skip if unreadable
+                    }
+                    break;
                 }
-                process.stdout.write(`\r  [${progress.current}/${progress.total}] ${progress.element}: ${progress.status}`.padEnd(80));
-            }
-        });
-        console.log('\n');
-        // Step 3: Write output
-        console.log('Step 3: Writing documentation...');
-        const outputPath = resolve(config.output.path);
-        let filesWritten;
-        let totalDocs;
-        if (options.byTopic) {
-            console.log('  mode: by-topic (grouped by concept)');
-            const result = await writeDocsByTopic(docs, outputPath);
-            filesWritten = result.filesWritten;
-            totalDocs = result.totalDocs;
-            console.log(`  topics: ${result.topics.map(t => t.name).join(', ')}`);
-        }
-        else {
-            // Default: file-based output
-            const fileResults = groupDocsByFile(docs);
-            const result = await writeDocsToDirectory(fileResults, outputPath, sourcePath);
-            filesWritten = result.filesWritten;
-            totalDocs = result.totalDocs;
-        }
-        const errorCount = docs.filter(d => d.error).length;
-        const duration = Math.round((Date.now() - startTime) / 1000);
-        console.log(`\n  Wrote ${filesWritten} documentation files to ${outputPath}`);
-        // Copy OpenAPI spec (provided or auto-detected)
-        let specPath = options.openapi ? resolve(options.openapi) : null;
-        // Auto-detect if not provided
-        if (!specPath) {
-            const detected = findOpenAPISpec(sourcePath);
-            if (detected) {
-                specPath = detected;
-                console.log(`\n  Auto-detected OpenAPI spec: ${basename(detected)}`);
             }
-        }
-        if (specPath) {
-            if (existsSync(specPath)) {
-                const specFilename = basename(specPath);
-                const contentDir = dirname(outputPath);
-                const destPath = resolve(contentDir, specFilename);
-                mkdirSync(dirname(destPath), { recursive: true });
-                copyFileSync(specPath, destPath);
-                console.log(`  Copied OpenAPI spec: ${specFilename} -> ${destPath}`);
-                console.log('  API Playground will be available at /reference');
+            // Also check parent directory (common for monorepos where source is a subdirectory)
+            if (!projectContext) {
+                const parentReadme = join(primarySourcePath, '..', 'README.md');
+                if (existsSync(parentReadme)) {
+                    try {
+                        projectContext = readFileSync(parentReadme, 'utf-8').slice(0, 1500);
+                        console.log('  Project context: loaded from parent README.md');
+                    }
+                    catch {
+                        // Skip
+                    }
+                }
             }
-            else if (options.openapi) {
-                console.log(`\n  Warning: OpenAPI spec not found: ${specPath}`);
+            // Context Hub enrichment: fetch third-party API docs if chub is installed
+            let externalContext;
+            const allImports = [];
+            for (const el of allElements) {
+                if (el.imports?.length) {
+                    allImports.push(...el.imports);
+                }
             }
-        }
-        // Always generate llms.txt for AEO (Answer Engine Optimization)
-        await writeLlmsTxt(docs, outputPath, {
-            projectName: options.projectName,
-            description: `API documentation for ${options.projectName || basename(sourcePath)}`
-        });
-        console.log(`\n  Generated llms.txt and llms-full.md for AEO`);
-        // Step 4: Embedded QA (auto-fix then check)
-        console.log('\nStep 4: Running QA checks...');
-        const fixReport = fixQAIssues(outputPath);
-        printFixReport(fixReport);
-        const qaReport = runQA(outputPath);
-        printQAReport(qaReport);
-        // Context Hub export prompt (TTY only — skip in CI/piped mode)
-        if (process.stdin.isTTY) {
-            console.log('');
-            console.log('  Context Hub: Make your docs discoverable by AI coding agents.');
-            console.log('  Context Hub is a curated registry by Andrew Ng (7K+ stars)');
-            console.log('  https://github.com/andrewyng/context-hub');
-            console.log('');
-            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-            const answer = await new Promise((resolve) => {
-                rl.question('  Export for Context Hub? (y/N) ', (ans) => {
-                    rl.close();
-                    resolve(ans.trim().toLowerCase());
-                });
+            const chubIds = extractDependencyIds(allImports);
+            if (chubIds.length > 0 && isChubInstalled()) {
+                console.log(`\n  Context Hub: fetching docs for ${chubIds.length} dependencies...`);
+                externalContext = fetchContextHubDocs(chubIds);
+                if (externalContext.size > 0) {
+                    console.log(`  Context Hub: enriching with ${externalContext.size} API references`);
+                }
+            }
+            // Step 2: Generate docs
+            console.log('\nStep 2: Generating documentation...');
+            const client = createLLMClient({
+                provider: config.llm.provider,
+                model: config.llm.model,
+                baseUrl: config.llm.baseUrl
+            });
+            let lastElement = '';
+            const multiLanguage = options.multiLang ?? false;
+            if (multiLanguage) {
+                console.log('  mode: multi-language (TypeScript + Python)');
+            }
+            const genOptions = {
+                multiLanguage,
+                externalContext,
+                projectContext,
+                onProgress: (progress) => {
+                    if (progress.element !== lastElement) {
+                        if (lastElement)
+                            console.log('');
+                        lastElement = progress.element;
+                    }
+                    process.stdout.write(`\r  [${progress.current}/${progress.total}] ${progress.element}: ${progress.status}`.padEnd(80));
+                }
+            };
+            // Step 3: Write output
+            const outputPath = resolve(config.output.path);
+            let filesWritten;
+            let totalDocs;
+            let docs;
+            let errorCount;
+            if (options.smartStructure) {
+                // Smart structure: LLM-planned page organization
+                console.log('  mode: smart-structure (user-journey organization)');
+                console.log('\n  Planning documentation structure...');
+                const structure = await planSmartStructure(allElements, client);
+                console.log(`  Planned ${structure.pages.length} page(s)`);
+                for (const page of structure.pages) {
+                    console.log(`    ${page.category}/${page.slug}: ${page.elements.length} elements`);
+                }
+                console.log('\nStep 3: Generating & writing structured documentation...');
+                const result = await generateWithStructure(structure, client, outputPath, genOptions);
+                filesWritten = result.filesWritten;
+                totalDocs = result.totalDocs;
+                docs = result.docs;
+                errorCount = docs.filter(d => d.error).length;
+            }
+            else {
+                docs = await generateForElements(allElements, client, genOptions);
+                console.log('\n');
+                console.log('Step 3: Writing documentation...');
+                if (options.byTopic) {
+                    console.log('  mode: by-topic (grouped by concept)');
+                    const result = await writeDocsByTopic(docs, outputPath);
+                    filesWritten = result.filesWritten;
+                    totalDocs = result.totalDocs;
+                    console.log(`  topics: ${result.topics.map(t => t.name).join(', ')}`);
+                }
+                else if (isMultiSource) {
+                    // Multi-source: write docs namespaced by source label
+                    filesWritten = 0;
+                    totalDocs = 0;
+                    // Group docs by source label
+                    const bySource = new Map();
+                    for (const doc of docs) {
+                        const label = doc.element.sourceLabel || '_default';
+                        if (!bySource.has(label))
+                            bySource.set(label, []);
+                        bySource.get(label).push(doc);
+                    }
+                    for (const [label, sourceDocs] of bySource) {
+                        const fileResults = groupDocsByFile(sourceDocs);
+                        const sourceOutputDir = label === '_default' ? outputPath : join(outputPath, label.toLowerCase());
+                        const sourceRoot = sourceDocs[0]?.element.sourceRoot || primarySourcePath;
+                        const result = await writeDocsToDirectory(fileResults, sourceOutputDir, sourceRoot);
+                        filesWritten += result.filesWritten;
+                        totalDocs += result.totalDocs;
+                        if (label !== '_default') {
+                            console.log(`  ${label}: ${result.filesWritten} files`);
+                        }
+                    }
+                }
+                else {
+                    // Default: file-based output (single source)
+                    const fileResults = groupDocsByFile(docs);
+                    const result = await writeDocsToDirectory(fileResults, outputPath, primarySourcePath);
+                    filesWritten = result.filesWritten;
+                    totalDocs = result.totalDocs;
+                }
+                errorCount = docs.filter(d => d.error).length;
+            }
+            const duration = Math.round((Date.now() - startTime) / 1000);
+            console.log(`\n  Wrote ${filesWritten} documentation files to ${outputPath}`);
+            // Copy OpenAPI spec (provided or auto-detected)
+            let specPath = options.openapi ? resolve(options.openapi) : null;
+            // Auto-detect if not provided
+            if (!specPath) {
+                const detected = findOpenAPISpec(primarySourcePath);
+                if (detected) {
+                    specPath = detected;
+                    console.log(`\n  Auto-detected OpenAPI spec: ${basename(detected)}`);
+                }
+            }
+            if (specPath) {
+                if (existsSync(specPath)) {
+                    const specFilename = basename(specPath);
+                    const contentDir = dirname(outputPath);
+                    const destPath = resolve(contentDir, specFilename);
+                    mkdirSync(dirname(destPath), { recursive: true });
+                    copyFileSync(specPath, destPath);
+                    console.log(`  Copied OpenAPI spec: ${specFilename} -> ${destPath}`);
+                    console.log('  API Playground will be available at /reference');
+                }
+                else if (options.openapi) {
+                    console.log(`\n  Warning: OpenAPI spec not found: ${specPath}`);
+                }
+            }
+            // Always generate llms.txt for AEO (Answer Engine Optimization)
+            await writeLlmsTxt(docs, outputPath, {
+                projectName: options.projectName,
+                description: `API documentation for ${options.projectName || basename(primarySourcePath)}`
             });
-            if (answer === 'y' || answer === 'yes') {
-                const languages = multiLanguage ? ['typescript', 'python'] : ['typescript'];
-                const projName = options.projectName || basename(sourcePath);
-                const result = exportToContextHub(docs, outputPath, {
-                    projectName: projName,
-                    languages,
-                    description: `API documentation for ${projName}`,
+            console.log(`\n  Generated llms.txt and llms-full.md for AEO`);
+            // Step 4: Verify code examples (if --verify)
+            if (options.verify) {
+                console.log('\nStep 4: Verifying code examples...');
+                let verifyEnvVars = {};
+                if (options.envFile) {
+                    try {
+                        verifyEnvVars = loadEnvFile(resolve(options.envFile));
+                        console.log(`  Loaded ${Object.keys(verifyEnvVars).length} env var(s) from ${options.envFile}`);
+                    }
+                    catch {
+                        console.log(`  Warning: Could not load env file: ${options.envFile}`);
+                    }
+                }
+                const verifyConfig = {
+                    timeout: 15000,
+                    envVars: verifyEnvVars,
+                    installDeps: true,
+                };
+                const maxIterations = Math.max(1, parseInt(options.maxVerifyIterations ?? '2', 10) || 2);
+                let failedCount = 0;
+                let passedCount = 0;
+                let skippedCount = 0;
+                for (let iteration = 1; iteration <= maxIterations; iteration++) {
+                    const docFiles = findDocFiles(outputPath);
+                    const allSnippets = docFiles.flatMap(f => extractSnippets(f));
+                    if (allSnippets.length === 0) {
+                        console.log('  No code snippets found to verify');
+                        break;
+                    }
+                    if (iteration === 1) {
+                        console.log(`  Found ${allSnippets.length} code snippet(s) to verify`);
+                    }
+                    else {
+                        console.log(`\n  Retry ${iteration}/${maxIterations}: re-verifying ${allSnippets.length} snippet(s)...`);
+                    }
+                    failedCount = 0;
+                    passedCount = 0;
+                    skippedCount = 0;
+                    const failedSnippets = [];
+                    const snippetErrors = new Map();
+                    for (const snippet of allSnippets) {
+                        const result = await runLocally(snippet, verifyConfig);
+                        if (result.status === 'pass') {
+                            passedCount++;
+                        }
+                        else if (result.status === 'skip') {
+                            skippedCount++;
+                        }
+                        else {
+                            failedCount++;
+                            failedSnippets.push(snippet);
+                            const errorMsg = result.stderr?.trim().split('\n').slice(0, 5).join('\n') || `Exit code: ${result.exitCode}`;
+                            snippetErrors.set(snippet.filePath + ':' + snippet.lineNumber, errorMsg);
+                            console.log(`  \x1b[31m✗\x1b[0m ${snippet.filePath}:${snippet.lineNumber} [${snippet.language}]`);
+                            if (result.stderr) {
+                                console.log(`    ${result.stderr.trim().split('\n')[0]?.slice(0, 80)}`);
+                            }
+                        }
+                    }
+                    // If all passed or last iteration, stop
+                    if (failedCount === 0 || iteration === maxIterations) {
+                        break;
+                    }
+                    // Re-generate failing docs by re-running generation for elements whose docs had failing snippets
+                    console.log(`\n  Re-generating ${failedSnippets.length} failing snippet(s)...`);
+                    const failedFiles = [...new Set(failedSnippets.map(s => s.filePath))];
+                    for (const failedFile of failedFiles) {
+                        // Find elements that map to this doc file
+                        const fileSnippets = failedSnippets.filter(s => s.filePath === failedFile);
+                        const matchingElements = allElements.filter(el => fileSnippets.some(s => {
+                            // Match element name in the snippet's surrounding code or filename
+                            const elNameLower = el.name.toLowerCase();
+                            return s.code.toLowerCase().includes(elNameLower) ||
+                                failedFile.toLowerCase().includes(elNameLower);
+                        }));
+                        if (matchingElements.length > 0) {
+                            // Build error context map: element name → error message
+                            const previousErrors = new Map();
+                            for (const snippet of fileSnippets) {
+                                const errKey = snippet.filePath + ':' + snippet.lineNumber;
+                                const errMsg = snippetErrors.get(errKey);
+                                if (errMsg) {
+                                    // Map snippet back to element name
+                                    const matchedEl = matchingElements.find(el => snippet.code.toLowerCase().includes(el.name.toLowerCase()));
+                                    if (matchedEl) {
+                                        previousErrors.set(matchedEl.name, errMsg);
+                                    }
+                                }
+                            }
+                            const reDocs = await generateForElements(matchingElements, client, {
+                                ...genOptions,
+                                verify: true,
+                                previousErrors,
+                                onProgress: (p) => {
+                                    process.stdout.write(`\r  Re-generating: ${p.element} ${p.status}`.padEnd(80));
+                                },
+                            });
+                            console.log('');
+                            // Re-write the doc file with updated content
+                            const fileResults = groupDocsByFile(reDocs);
+                            await writeDocsToDirectory(fileResults, dirname(failedFile), primarySourcePath);
+                        }
+                    }
+                }
+                if (failedCount + passedCount + skippedCount > 0) {
+                    console.log(`\n  Verification: ${passedCount} passed, ${failedCount} failed, ${skippedCount} skipped`);
+                }
+            }
+            // Write manifest for staleness detection
+            try {
+                const manifestEntries = buildManifestEntries(allElements, outputPath);
+                writeManifest(outputPath, manifestEntries);
+            }
+            catch {
+                // Non-fatal — manifest is optional
+            }
+            // Step 5: Embedded QA (auto-fix then check)
+            console.log(`\nStep ${options.verify ? '5' : '4'}: Running QA checks...`);
+            const fixReport = fixQAIssues(outputPath);
+            printFixReport(fixReport);
+            const qaReport = runQA(outputPath);
+            printQAReport(qaReport);
+            // Context Hub export prompt (TTY only — skip in CI/piped mode)
+            if (process.stdin.isTTY) {
+                console.log('');
+                console.log('  Context Hub: Make your docs discoverable by AI coding agents.');
+                console.log('  Context Hub is a curated registry by Andrew Ng (7K+ stars)');
+                console.log('  https://github.com/andrewyng/context-hub');
+                console.log('');
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                const answer = await new Promise((resolve) => {
+                    rl.question('  Export for Context Hub? (y/N) ', (ans) => {
+                        rl.close();
+                        resolve(ans.trim().toLowerCase());
+                    });
                 });
-                console.log(`\n  Exported ${result.filesWritten} files to ${result.outputDir}`);
-                console.log('  See context-hub/README.md for submission instructions');
+                if (answer === 'y' || answer === 'yes') {
+                    const languages = multiLanguage ? ['typescript', 'python'] : ['typescript'];
+                    const projName = options.projectName || basename(primarySourcePath);
+                    const result = exportToContextHub(docs, outputPath, {
+                        projectName: projName,
+                        languages,
+                        description: `API documentation for ${projName}`,
+                    });
+                    console.log(`\n  Exported ${result.filesWritten} files to ${result.outputDir}`);
+                    console.log('  See context-hub/README.md for submission instructions');
+                }
             }
+            console.log('\n=== Summary ===');
+            console.log(`  Total elements: ${totalDocs}`);
+            console.log(`  Generated:      ${totalDocs - errorCount}`);
+            if (errorCount > 0) {
+                console.log(`  Errors:         ${errorCount}`);
+            }
+            console.log(`  Duration:       ${duration}s`);
+            console.log(`  Output:         ${outputPath}`);
+            if (errorCount > 0) {
+                console.log('\n  Elements with errors:');
+                docs.filter(d => d.error).slice(0, 10).forEach(d => {
+                    console.log(`    - ${d.element.name}: ${d.error?.slice(0, 50)}`);
+                });
+                if (errorCount > 10) {
+                    console.log(`    ... and ${errorCount - 10} more`);
+                }
+            }
+            console.log('\nDone!');
         }
-        console.log('\n=== Summary ===');
-        console.log(`  Total elements: ${totalDocs}`);
-        console.log(`  Generated:      ${totalDocs - errorCount}`);
-        if (errorCount > 0) {
-            console.log(`  Errors:         ${errorCount}`);
-        }
-        console.log(`  Duration:       ${duration}s`);
-        console.log(`  Output:         ${outputPath}`);
-        if (errorCount > 0) {
-            console.log('\n  Elements with errors:');
-            docs.filter(d => d.error).slice(0, 10).forEach(d => {
-                console.log(`    - ${d.element.name}: ${d.error?.slice(0, 50)}`);
-            });
-            if (errorCount > 10) {
-                console.log(`    ... and ${errorCount - 10} more`);
+        finally {
+            // Clean up temp directories from --org clones
+            for (const dir of tempDirs) {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
             }
         }
-        console.log('\nDone!');
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);