skrypt-ai 0.6.1 → 0.8.0

package/dist/config/loader.js

@@ -4,7 +4,7 @@ import yaml from 'js-yaml';
 import { DEFAULT_CONFIG, PROVIDER_ENV_KEYS } from './types.js';
 const VALID_PROVIDERS = ['deepseek', 'openai', 'anthropic', 'google', 'ollama', 'openrouter'];
 const CONFIG_FILENAMES = ['.skrypt.yaml', '.skrypt.yml', 'skrypt.yaml', 'skrypt.yml'];
-export function findConfigFile(dir) {
+function findConfigFile(dir) {
     for (const filename of CONFIG_FILENAMES) {
         const filepath = join(dir, filename);
         if (existsSync(filepath)) {
@@ -61,6 +61,7 @@ function mergeConfig(defaults, overrides) {
             ...defaults.source,
             ...overrides.source
         },
+        sources: overrides.sources,
         output: {
             ...defaults.output,
             ...overrides.output
@@ -74,10 +75,25 @@ function mergeConfig(defaults, overrides) {
 }
 export function validateConfig(config) {
     const errors = [];
-    if (config.version !== 1) {
+    if (config.version !== 1 && config.version !== 2) {
         errors.push(`Unsupported config version: ${config.version}`);
     }
-    if (!config.source.path) {
+    // Validate sources array if present (v2)
+    if (config.sources && config.sources.length > 0) {
+        const labels = new Set();
+        for (const entry of config.sources) {
+            if (!entry.path) {
+                errors.push('Each source entry must have a path');
+            }
+            if (entry.label) {
+                if (labels.has(entry.label)) {
+                    errors.push(`Duplicate source label: "${entry.label}"`);
+                }
+                labels.add(entry.label);
+            }
+        }
+    }
+    else if (!config.source.path) {
         errors.push('source.path is required');
     }
     if (!config.output.path) {
@@ -88,6 +104,26 @@ export function validateConfig(config) {
     }
     return errors;
 }
+/**
+ * Resolve v1 `source` or v2 `sources` into a normalized array of SourceEntry.
+ * Falls back to the single source config if no sources array is defined.
+ */
+export function resolveSourceEntries(config) {
+    if (config.sources && config.sources.length > 0) {
+        return config.sources.map(s => ({
+            path: s.path,
+            label: s.label,
+            include: s.include ?? config.source.include,
+            exclude: s.exclude ?? config.source.exclude,
+        }));
+    }
+    // Backwards compat: single source
+    return [{
+            path: config.source.path,
+            include: config.source.include,
+            exclude: config.source.exclude,
+        }];
+}
 export function checkApiKey(provider) {
     const envKey = PROVIDER_ENV_KEYS[provider];
     // Ollama doesn't need an API key

package/dist/config/types.d.ts

@@ -3,6 +3,12 @@ export interface SourceConfig {
     include?: string[];
     exclude?: string[];
 }
+export interface SourceEntry {
+    path: string;
+    label?: string;
+    include?: string[];
+    exclude?: string[];
+}
 export type LLMProvider = 'deepseek' | 'openai' | 'anthropic' | 'google' | 'ollama' | 'openrouter';
 export interface LLMConfig {
     provider: LLMProvider;
@@ -14,6 +20,7 @@ export declare const DEFAULT_MODELS: Record<LLMProvider, string>;
 export interface Config {
     version: number;
     source: SourceConfig;
+    sources?: SourceEntry[];
     output: {
         path: string;
         format: 'markdown' | 'mdx';

package/dist/generator/agents-md.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AGENTS.md / CLAUDE.md generator
+ *
+ * Generates context files that coding agents (Claude Code, Cursor, GitHub Copilot,
+ * OpenCode) load on every turn. Vercel research: 8KB AGENTS.md = 100% pass rate
+ * vs 79% for skills-based approaches.
+ */
+export interface AgentsMdPage {
+    title: string;
+    path: string;
+    description?: string;
+    category?: string;
+}
+export interface AgentsMdOptions {
+    projectName: string;
+    docsPath: string;
+    baseUrl?: string;
+    pages: AgentsMdPage[];
+    hasLlmsTxt: boolean;
+}
+/**
+ * Generate AGENTS.md content for a project.
+ * Designed to be loaded by coding agents on every turn for instant docs access.
+ */
+export declare function generateAgentsMd(options: AgentsMdOptions): string;

package/dist/generator/agents-md.js

@@ -0,0 +1,122 @@
+/**
+ * AGENTS.md / CLAUDE.md generator
+ *
+ * Generates context files that coding agents (Claude Code, Cursor, GitHub Copilot,
+ * OpenCode) load on every turn. Vercel research: 8KB AGENTS.md = 100% pass rate
+ * vs 79% for skills-based approaches.
+ */
+const MAX_SIZE_BYTES = 8 * 1024; // 8KB — Vercel's optimal size
+/**
+ * Generate AGENTS.md content for a project.
+ * Designed to be loaded by coding agents on every turn for instant docs access.
+ */
+export function generateAgentsMd(options) {
+    const { projectName, docsPath, baseUrl, pages, hasLlmsTxt } = options;
+    let out = `# ${projectName} — Documentation Guide\n\n`;
+    out += `When answering questions about **${projectName}**, consult these docs first.\n\n`;
+    // Access instructions
+    out += `## How to Access Docs\n\n`;
+    if (baseUrl) {
+        out += `- **Browse:** ${baseUrl}\n`;
+        if (hasLlmsTxt) {
+            out += `- **Agent index:** ${baseUrl}/llms.txt (structured summary)\n`;
+            out += `- **Full content:** ${baseUrl}/llms-full.md (all docs in one file)\n`;
+        }
+        out += `- **Markdown variant:** Append \`.md\` to any docs URL, or use \`Accept: text/markdown\` header\n`;
+    }
+    out += `- **Local files:** \`${docsPath}/\` (MDX/Markdown source)\n`;
+    out += `\n`;
+    // Identify entry points
+    const quickstarts = pages.filter(p => isEntryPoint(p, 'quickstart'));
+    const apiRefs = pages.filter(p => isEntryPoint(p, 'api'));
+    const guides = pages.filter(p => isEntryPoint(p, 'guide'));
+    if (quickstarts.length > 0 || apiRefs.length > 0) {
+        out += `## Key Entry Points\n\n`;
+        if (quickstarts.length > 0) {
+            out += `**Getting Started:**\n`;
+            for (const p of quickstarts.slice(0, 3)) {
+                out += formatPageLine(p, baseUrl);
+            }
+        }
+        if (apiRefs.length > 0) {
+            out += `**API Reference:**\n`;
+            for (const p of apiRefs.slice(0, 5)) {
+                out += formatPageLine(p, baseUrl);
+            }
+        }
+        if (guides.length > 0) {
+            out += `**Guides:**\n`;
+            for (const p of guides.slice(0, 5)) {
+                out += formatPageLine(p, baseUrl);
+            }
+        }
+        out += `\n`;
+    }
+    // Page index — compact, one line per page
+    out += `## Documentation Index\n\n`;
+    // Group by category if available
+    const byCategory = groupByCategory(pages);
+    for (const [category, categoryPages] of byCategory) {
+        if (category !== '_default') {
+            out += `### ${category}\n\n`;
+        }
+        for (const page of categoryPages) {
+            out += formatPageLine(page, baseUrl);
+            // Check size — stop adding pages if we're near the limit
+            if (Buffer.byteLength(out, 'utf-8') > MAX_SIZE_BYTES - 200) {
+                const remaining = pages.length - categoryPages.indexOf(page) - 1;
+                if (remaining > 0) {
+                    out += `\n*...and ${remaining} more pages. See ${hasLlmsTxt ? 'llms.txt' : docsPath} for the complete index.*\n`;
+                }
+                return finalize(out);
+            }
+        }
+        out += `\n`;
+    }
+    return finalize(out);
+}
+function finalize(content) {
+    const out = content.trimEnd() + '\n';
+    // Final size check — truncate page index if over limit
+    if (Buffer.byteLength(out, 'utf-8') > MAX_SIZE_BYTES) {
+        // Find the last complete line that fits
+        const lines = out.split('\n');
+        let truncated = '';
+        for (const line of lines) {
+            const next = truncated + line + '\n';
+            if (Buffer.byteLength(next, 'utf-8') > MAX_SIZE_BYTES - 100) {
+                truncated += '\n*Index truncated to fit 8KB limit. See llms.txt for complete listing.*\n';
+                break;
+            }
+            truncated = next;
+        }
+        return truncated;
+    }
+    return out;
+}
+function formatPageLine(page, baseUrl) {
+    const ref = baseUrl ? `${baseUrl}/docs/${page.path}` : page.path;
+    const desc = page.description ? ` — ${page.description}` : '';
+    return `- [${page.title}](${ref})${desc}\n`;
+}
+function isEntryPoint(page, type) {
+    const lower = `${page.title} ${page.path} ${page.category || ''}`.toLowerCase();
+    switch (type) {
+        case 'quickstart':
+            return /quickstart|getting.started|introduction|overview|setup|install/i.test(lower);
+        case 'api':
+            return /api.ref|reference|endpoint|api$/i.test(lower);
+        case 'guide':
+            return /guide|tutorial|how.to|walkthrough/i.test(lower);
+    }
+}
+function groupByCategory(pages) {
+    const groups = new Map();
+    for (const page of pages) {
+        const cat = page.category || '_default';
+        if (!groups.has(cat))
+            groups.set(cat, []);
+        groups.get(cat).push(page);
+    }
+    return groups;
+}

package/dist/generator/generator.js

@@ -68,7 +68,8 @@ export async function generateForElement(element, client, options, onProgress) {
     report('generating');
     try {
         const elementContext = buildElementContext(element, options.externalContext, options.projectContext);
-        const result = await generateDocumentation(client, elementContext, { multiLanguage: useMultiLang });
+        const errorContext = options.previousErrors?.get(element.name);
+        const result = await generateDocumentation(client, elementContext, { multiLanguage: useMultiLang, verify: options.verify, previousError: errorContext });
         report('done');
         return {
             element,

package/dist/generator/index.d.ts

@@ -2,3 +2,5 @@ export * from './types.js';
 export * from './generator.js';
 export * from './writer.js';
 export * from './organizer.js';
+export * from './mdx-serializer.js';
+export * from './agents-md.js';

package/dist/generator/index.js

@@ -2,3 +2,5 @@ export * from './types.js';
 export * from './generator.js';
 export * from './writer.js';
 export * from './organizer.js';
+export * from './mdx-serializer.js';
+export * from './agents-md.js';

package/dist/generator/mdx-serializer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MDX-to-Markdown serializer
+ *
+ * Converts MDX content with JSX components into clean markdown
+ * for agent consumption (llms-full.md, content negotiation, AGENTS.md).
+ */
+/**
+ * Strip MDX/JSX components and convert to clean markdown.
+ * Handles CodeGroup, Callout, Card, Tabs, Steps, Accordion, Screenshot, etc.
+ */
+export declare function serializeMdxToMarkdown(mdx: string): string;

package/dist/generator/mdx-serializer.js

@@ -0,0 +1,135 @@
+/**
+ * MDX-to-Markdown serializer
+ *
+ * Converts MDX content with JSX components into clean markdown
+ * for agent consumption (llms-full.md, content negotiation, AGENTS.md).
+ */
+/** Extract a named attribute value from a JSX attribute string. */
+function attr(attrs, name) {
+    const re = new RegExp(`${name}=["']([^"']+)["']`);
+    const m = attrs.match(re);
+    return m ? m[1] : undefined;
+}
+/**
+ * Strip MDX/JSX components and convert to clean markdown.
+ * Handles CodeGroup, Callout, Card, Tabs, Steps, Accordion, Screenshot, etc.
+ */
+export function serializeMdxToMarkdown(mdx) {
+    let out = mdx;
+    // Remove import statements
+    out = out.replace(/^import\s+.*$/gm, '');
+    // Remove export statements (but not export default with content)
+    out = out.replace(/^export\s+(?!default\s).*$/gm, '');
+    // --- Component conversions (order matters) ---
+    // CodeGroup → flatten to labeled code blocks
+    out = out.replace(/<CodeGroup>\s*([\s\S]*?)\s*<\/CodeGroup>/g, (_match, inner) => {
+        return inner.trim();
+    });
+    // Callout variants: <Callout type="warning">, <Warning>, <Info>, <Note>, <Tip>, <Success>, <Error>
+    const calloutTypes = ['Callout', 'Info', 'Warning', 'Success', 'Error', 'Tip', 'Note'];
+    for (const tag of calloutTypes) {
+        // With type attribute: <Callout type="warning">
+        const typedRegex = new RegExp(`<${tag}\\s+type=["']([^"']+)["'][^>]*>\\s*([\\s\\S]*?)\\s*<\\/${tag}>`, 'g');
+        out = out.replace(typedRegex, (_m, type, content) => {
+            const label = type.charAt(0).toUpperCase() + type.slice(1);
+            return formatBlockquote(label, content.trim());
+        });
+        // Without type attribute: <Warning>content</Warning>
+        const simpleRegex = new RegExp(`<${tag}(?:\\s[^>]*)?>\\s*([\\s\\S]*?)\\s*<\\/${tag}>`, 'g');
+        out = out.replace(simpleRegex, (_m, content) => {
+            const label = tag === 'Callout' ? 'Note' : tag;
+            return formatBlockquote(label, content.trim());
+        });
+    }
+    // CardGroup → unwrap (just keep children)
+    out = out.replace(/<CardGroup[^>]*>\s*/g, '');
+    out = out.replace(/\s*<\/CardGroup>/g, '');
+    // Card with attributes + children (attribute-order-independent)
+    out = out.replace(/<Card\s+([^>]+?)>\s*([\s\S]*?)\s*<\/Card>/g, (_m, attrs, desc) => {
+        const title = attr(attrs, 'title');
+        const href = attr(attrs, 'href');
+        const description = desc.trim().replace(/<[^>]+>/g, '');
+        if (title && href) {
+            return description
+                ? `- **[${title}](${href})** — ${description}`
+                : `- **[${title}](${href})**`;
+        }
+        if (title) {
+            return description ? `- **${title}** — ${description}` : `- **${title}**`;
+        }
+        return description || '';
+    });
+    // Tabs/TabList/TabPanel → headings + content
+    out = out.replace(/<TabList>\s*([\s\S]*?)\s*<\/TabList>/g, '');
+    out = out.replace(/<Tab\s+label=["']([^"']+)["'][^>]*>\s*([\s\S]*?)\s*<\/Tab>/g, (_m, label, content) => `#### ${label}\n\n${content.trim()}\n`);
+    out = out.replace(/<TabPanel[^>]*>\s*([\s\S]*?)\s*<\/TabPanel>/g, (_m, content) => content.trim());
+    out = out.replace(/<Tabs[^>]*>\s*/g, '');
+    out = out.replace(/\s*<\/Tabs>/g, '');
+    // Steps/Step → numbered list
+    out = out.replace(/<Steps>\s*([\s\S]*?)\s*<\/Steps>/g, (_match, inner) => {
+        let stepNum = 0;
+        return inner.replace(/<Step\s*(?:title=["']([^"']+)["'][^>]*)?>?\s*([\s\S]*?)\s*<\/Step>/g, (_m, title, content) => {
+            stepNum++;
+            const heading = title ? `**${title}**` : '';
+            return `${stepNum}. ${heading}\n   ${content.trim()}\n`;
+        });
+    });
+    // Accordion → bold title + content
+    out = out.replace(/<AccordionGroup[^>]*>\s*/g, '');
+    out = out.replace(/\s*<\/AccordionGroup>/g, '');
+    out = out.replace(/<Accordion\s+title=["']([^"']+)["'][^>]*>\s*([\s\S]*?)\s*<\/Accordion>/g, (_m, title, content) => `**${title}**\n\n${content.trim()}\n`);
+    // Screenshot → image (attribute-order-independent)
+    out = out.replace(/<Screenshot\s+([^>]*?)\s*\/?>/g, (_m, attrs) => {
+        const src = attr(attrs, 'src');
+        const alt = attr(attrs, 'alt');
+        return src ? `![${alt || 'Screenshot'}](${src})` : '';
+    });
+    // Also handle <Screenshot>...</Screenshot> (non-self-closing)
+    out = out.replace(/<Screenshot\s+([^>]*?)>[\s\S]*?<\/Screenshot>/g, (_m, attrs) => {
+        const src = attr(attrs, 'src');
+        return src ? `![Screenshot](${src})` : '';
+    });
+    // Frame → unwrap
+    out = out.replace(/<Frame[^>]*>\s*/g, '');
+    out = out.replace(/\s*<\/Frame>/g, '');
+    // DarkImage → image (use light image src)
+    out = out.replace(/<DarkImage\s+(?:[^>]*?src=["']([^"']+)["'][^>]*?)\s*\/?>/g, (_m, src) => `![Image](${src})`);
+    // CodePlayground / PythonPlayground / GoPlayground → extract code
+    for (const tag of ['CodePlayground', 'PythonPlayground', 'GoPlayground']) {
+        const regex = new RegExp(`<${tag}[^>]*>\\s*([\\s\\S]*?)\\s*<\\/${tag}>`, 'g');
+        out = out.replace(regex, (_m, content) => content.trim());
+    }
+    // ParamTable / Schema → pass through content
+    out = out.replace(/<ParamTable[^>]*>\s*([\s\S]*?)\s*<\/ParamTable>/g, (_m, c) => c.trim());
+    out = out.replace(/<Schema[^>]*>\s*([\s\S]*?)\s*<\/Schema>/g, (_m, c) => c.trim());
+    // API badges → inline text
+    out = out.replace(/<MethodBadge\s+method=["']([^"']+)["'][^>]*\s*\/?>/g, '`$1`');
+    out = out.replace(/<StatusBadge\s+code=["']([^"']+)["'][^>]*\s*\/?>/g, '`$1`');
+    out = out.replace(/<Endpoint\s+method=["']([^"']+)["']\s+path=["']([^"']+)["'][^>]*\s*\/?>/g, '`$1 $2`');
+    // LinkPreview → markdown link
+    out = out.replace(/<LinkPreview\s+(?:[^>]*?url=["']([^"']+)["'][^>]*?)(?:\s+title=["']([^"']+)["'])?[^>]*\s*\/?>/g, (_m, url, title) => `[${title || url}](${url})`);
+    // Tooltip → just the text
+    out = out.replace(/<Tooltip\s+[^>]*>\s*([\s\S]*?)\s*<\/Tooltip>/g, (_m, c) => c.trim());
+    // Changelog components → headings
+    out = out.replace(/<Changelog>\s*/g, '');
+    out = out.replace(/\s*<\/Changelog>/g, '');
+    out = out.replace(/<ChangelogEntry\s+(?:[^>]*?date=["']([^"']+)["'][^>]*?)>\s*([\s\S]*?)\s*<\/ChangelogEntry>/g, (_m, date, content) => `### ${date}\n\n${content.trim()}\n`);
+    out = out.replace(/<Change\s+type=["']([^"']+)["'][^>]*>\s*([\s\S]*?)\s*<\/Change>/g, (_m, type, content) => `- **${type}:** ${content.trim()}`);
+    // Mermaid → keep as code block
+    out = out.replace(/<Mermaid\s+chart=["'`]([^"'`]+)["'`][^>]*\s*\/?>/g, (_m, chart) => '```mermaid\n' + chart.trim() + '\n```');
+    // Catch-all: remove any remaining self-closing JSX tags
+    out = out.replace(/<[A-Z][A-Za-z]*\s[^>]*\/>/g, '');
+    // Catch-all: unwrap any remaining JSX component tags (keep children)
+    out = out.replace(/<[A-Z][A-Za-z]*(?:\s[^>]*)?>/g, '');
+    out = out.replace(/<\/[A-Z][A-Za-z]*>/g, '');
+    // Clean up excessive blank lines
+    out = out.replace(/\n{4,}/g, '\n\n\n');
+    // Trim leading/trailing whitespace
+    out = out.trim() + '\n';
+    return out;
+}
+function formatBlockquote(label, content) {
+    const lines = content.split('\n');
+    const quoted = lines.map(line => `> ${line}`).join('\n');
+    return `> **${label}:** ${quoted.replace(/^> /, '')}\n`;
+}

package/dist/generator/organizer.d.ts

@@ -1,4 +1,4 @@
-import { GeneratedDoc, Topic, TopicConfig, CrossReference, NavigationItem } from './types.js';
+import { GeneratedDoc, Topic, TopicConfig, CrossReference } from './types.js';
 /**
  * Default topic configuration with common patterns
  */
@@ -15,18 +15,3 @@ export declare function detectCrossReferences(docs: GeneratedDoc[]): CrossRefere
  * Get cross-references for a specific element
  */
 export declare function getCrossRefsForElement(elementName: string, allRefs: CrossReference[]): CrossReference[];
-/**
- * Build navigation structure from topics
- * @internal
- */
-export declare function buildNavigation(topics: Topic[]): NavigationItem[];
-/**
- * Generate a sidebar configuration (works with multiple doc platforms)
- * @internal
- */
-export declare function generateSidebarConfig(topics: Topic[]): object;
-/**
- * Merge user config with defaults
- * @internal
- */
-export declare function mergeTopicConfig(userConfig: Partial<TopicConfig>, defaults?: TopicConfig): TopicConfig;

package/dist/generator/organizer.js

@@ -1,4 +1,3 @@
-import { slugify } from '../utils/files.js';
 /**
  * Default topic configuration with common patterns
  */
@@ -172,32 +171,6 @@ export function detectCrossReferences(docs) {
 export function getCrossRefsForElement(elementName, allRefs) {
     return allRefs.filter(r => r.fromElement === elementName);
 }
-/**
- * Build navigation structure from topics
- * @internal
- */
-export function buildNavigation(topics) {
-    return topics.map(topic => ({
-        title: topic.name,
-        path: `/${topic.id}`,
-        children: topic.docs.map(doc => ({
-            title: doc.element.name,
-            path: `/${topic.id}#${slugify(doc.element.name)}`
-        }))
-    }));
-}
-/**
- * Generate a sidebar configuration (works with multiple doc platforms)
- * @internal
- */
-export function generateSidebarConfig(topics) {
-    return {
-        navigation: topics.map(topic => ({
-            group: topic.name,
-            pages: topic.docs.map(doc => `${topic.id}/${slugify(doc.element.name)}`)
-        }))
-    };
-}
 /**
  * Convert string to title case
  */
@@ -206,14 +179,3 @@ function titleCase(str) {
         .replace(/-/g, ' ')
         .replace(/\b\w/g, c => c.toUpperCase());
 }
-/**
- * Merge user config with defaults
- * @internal
- */
-export function mergeTopicConfig(userConfig, defaults = DEFAULT_TOPIC_CONFIG) {
-    return {
-        topics: { ...defaults.topics, ...userConfig.topics },
-        rules: [...defaults.rules, ...(userConfig.rules || [])],
-        defaultTopic: userConfig.defaultTopic ?? defaults.defaultTopic
-    };
-}

package/dist/generator/types.d.ts

@@ -33,6 +33,9 @@ export interface GenerationOptions {
     externalContext?: Map<string, string>;
     maxTokens?: number;
     projectContext?: string;
+    verify?: boolean;
+    /** Error context from previous verification failures, keyed by element name */
+    previousErrors?: Map<string, string>;
 }
 /**
  * Result of generating docs for a file

package/dist/generator/writer.js

@@ -4,6 +4,7 @@ import { existsSync } from 'fs';
 import { formatAsMarkdown } from './generator.js';
 import { organizeByTopic, detectCrossReferences, getCrossRefsForElement } from './organizer.js';
 import { slugify } from '../utils/files.js';
+import { serializeMdxToMarkdown } from './mdx-serializer.js';
 /**
  * Generate llms.txt file (Answer Engine Optimization)
  * Format follows https://llmstxt.org convention
@@ -13,36 +14,45 @@ export async function writeLlmsTxt(docs, outputDir, options = {}) {
     const description = options.description || 'API documentation generated by skrypt';
     let content = `# ${projectName}\n\n`;
     content += `> ${description}\n\n`;
-    // Group by file for organization
-    const byFile = new Map();
+    // Check if docs have source labels (multi-source mode)
+    const hasSourceLabels = docs.some(d => d.element.sourceLabel);
+    // Group by source label then by file
+    const bySource = new Map();
     for (const doc of docs) {
+        const sourceKey = doc.element.sourceLabel || '_default';
+        if (!bySource.has(sourceKey))
+            bySource.set(sourceKey, new Map());
+        const sourceMap = bySource.get(sourceKey);
         const file = basename(doc.element.filePath).replace(/\.[^.]+$/, '');
-        if (!byFile.has(file)) {
-            byFile.set(file, []);
-        }
-        const fileDocs = byFile.get(file);
-        if (fileDocs)
-            fileDocs.push(doc);
+        if (!sourceMap.has(file))
+            sourceMap.set(file, []);
+        sourceMap.get(file).push(doc);
     }
+    const totalModules = Array.from(bySource.values()).reduce((sum, m) => sum + m.size, 0);
     // Summary section
     content += `## Overview\n\n`;
-    content += `This project contains ${docs.length} documented API elements across ${byFile.size} modules.\n\n`;
+    content += `This project contains ${docs.length} documented API elements across ${totalModules} modules.\n\n`;
     // Quick reference
     content += `## Quick Reference\n\n`;
-    for (const [file, fileDocs] of byFile) {
-        content += `### ${file}\n\n`;
-        for (const doc of fileDocs) {
-            content += `- \`${doc.element.name}\`: ${doc.element.kind}`;
-            if (doc.markdown) {
-                // Extract first sentence as summary
-                const firstSentence = doc.markdown.split(/\.\s/)[0]?.slice(0, 100);
-                if (firstSentence) {
-                    content += ` - ${firstSentence}`;
+    for (const [sourceLabel, byFile] of bySource) {
+        if (hasSourceLabels && sourceLabel !== '_default') {
+            content += `### ${sourceLabel}\n\n`;
+        }
+        for (const [file, fileDocs] of byFile) {
+            content += `${hasSourceLabels ? '####' : '###'} ${file}\n\n`;
+            for (const doc of fileDocs) {
+                content += `- \`${doc.element.name}\`: ${doc.element.kind}`;
+                if (doc.markdown) {
+                    // Extract first sentence as summary
+                    const firstSentence = doc.markdown.split(/\.\s/)[0]?.slice(0, 100);
+                    if (firstSentence) {
+                        content += ` - ${firstSentence}`;
+                    }
                 }
+                content += '\n';
             }
             content += '\n';
         }
-        content += '\n';
     }
     // Detailed API section
     content += `## API Details\n\n`;
@@ -52,14 +62,14 @@ export async function writeLlmsTxt(docs, outputDir, options = {}) {
         content += `**File:** ${doc.element.filePath}\n\n`;
         content += `\`\`\`\n${doc.element.signature}\n\`\`\`\n\n`;
         if (doc.markdown) {
-            content += doc.markdown.slice(0, 500) + '\n\n';
+            content += serializeMdxToMarkdown(doc.markdown.slice(0, 500)) + '\n\n';
         }
         if (doc.codeExample) {
             content += `**Example:**\n\`\`\`${doc.codeLanguage}\n${doc.codeExample.slice(0, 300)}\n\`\`\`\n\n`;
         }
     }
-    // Write both llms.txt and llms-full.md
-    await writeFile(join(outputDir, 'llms.txt'), content, 'utf-8');
+    // Write both llms.txt and llms-full.md — serialize any JSX for clean agent consumption
+    await writeFile(join(outputDir, 'llms.txt'), serializeMdxToMarkdown(content), 'utf-8');
     // Also write a condensed version (just signatures)
     let condensed = `# ${projectName} API\n\n`;
     condensed += `> ${description}\n\n`;
@@ -67,7 +77,7 @@ export async function writeLlmsTxt(docs, outputDir, options = {}) {
         condensed += `## ${doc.element.name}\n`;
         condensed += `${doc.element.signature}\n\n`;
     }
-    await writeFile(join(outputDir, 'llms-full.md'), condensed, 'utf-8');
+    await writeFile(join(outputDir, 'llms-full.md'), serializeMdxToMarkdown(condensed), 'utf-8');
 }
 /**
  * Write generated docs to output directory
@@ -134,15 +144,38 @@ async function writeIndexFile(results, outputDir, sourceDir) {
     const totalElements = results.reduce((sum, r) => sum + r.docs.length, 0);
     content += '## Summary\n\n';
     content += `- **Total elements:** ${totalElements}\n\n`;
-    // File index
-    content += '## Files\n\n';
-    for (const result of results) {
-        if (result.docs.length === 0)
-            continue;
-        const relPath = relative(sourceDir, result.filePath);
-        const docFileName = relPath.replace(/\.[^.]+$/, '.md');
-        content += `- [${relPath}](./${docFileName})`;
-        content += ` (${result.docs.length} elements)\n`;
+    // Check if any docs have source labels
+    const hasLabels = results.some(r => r.docs.some(d => d.element.sourceLabel));
+    if (hasLabels) {
+        // Group by source label
+        const byLabel = new Map();
+        for (const result of results) {
+            if (result.docs.length === 0)
+                continue;
+            const label = result.docs[0]?.element.sourceLabel || 'Other';
+            if (!byLabel.has(label))
+                byLabel.set(label, []);
+            byLabel.get(label).push(result);
+        }
+        for (const [label, labelResults] of byLabel) {
+            content += `## ${label}\n\n`;
+            for (const result of labelResults) {
+                const relPath = relative(sourceDir, result.filePath);
+                const docFileName = relPath.replace(/\.[^.]+$/, '.md');
+                content += `- [${relPath}](./${docFileName}) (${result.docs.length} elements)\n`;
+            }
+            content += '\n';
+        }
+    }
+    else {
+        content += '## Files\n\n';
+        for (const result of results) {
+            if (result.docs.length === 0)
+                continue;
+            const relPath = relative(sourceDir, result.filePath);
+            const docFileName = relPath.replace(/\.[^.]+$/, '.md');
+            content += `- [${relPath}](./${docFileName}) (${result.docs.length} elements)\n`;
+        }
     }
     await writeFile(join(outputDir, 'README.md'), content, 'utf-8');
 }