docorbit 0.1.0

package/packages/evaluation/src/version-matcher.ts

@@ -0,0 +1,73 @@
+import type { BenchmarkTaskDef } from './types.ts';
+
+/**
+ * Semantically evaluates whether retrieved documentation content matches
+ * the target version requirements of a benchmark task.
+ *
+ * Rather than looking for an arbitrary literal version string (e.g. "16.12" in HTTP API docs
+ * which only use date versions, or "2.6" in tutorial prose on GitHub main), this inspects
+ * whether the retrieved documentation teaches the correct version-specific API signatures,
+ * syntax, and conventions — and does not teach fatal breaking-change anti-patterns.
+ */
+export function isVersionContentMatch(task: BenchmarkTaskDef, content: string): boolean {
+  if (!content || content.trim().length === 0) return false;
+  const lower = content.toLowerCase();
+
+  switch (task.id) {
+    case 'train_nextjs_14_route_sync':
+      // Next.js 14: route params are synchronous. If doc teaches "await params" or "Promise<{", it's Next.js 15+!
+      if (lower.includes('await params') || lower.includes('params: promise') || lower.includes('promise<{')) {
+        return false;
+      }
+      return lower.includes('14') || lower.includes('params.id') || lower.includes('{ params }') || lower.includes('route handler');
+
+    case 'eval_nextjs_15_async_params':
+      // Next.js 15: route params are asynchronous Promises.
+      return lower.includes('await params') || lower.includes('params: promise') || lower.includes('promise<{') || lower.includes('next.js 15');
+
+    case 'train_stripe_v1_charges':
+      // Legacy Stripe: direct charges endpoint /v1/charges
+      if (lower.includes('payment_intents') && !lower.includes('/v1/charges') && !lower.includes('charges.create')) {
+        return false;
+      }
+      return lower.includes('/v1/charges') || lower.includes('charges.create');
+
+    case 'eval_stripe_payment_intents_2024':
+      // Modern Stripe: PaymentIntents endpoint
+      return lower.includes('payment_intents') || lower.includes('paymentintents');
+
+    case 'train_pydantic_v1_validator':
+      // Pydantic v1: uses @validator. If doc teaches @field_validator, it's Pydantic v2!
+      if (lower.includes('field_validator')) {
+        return false;
+      }
+      return lower.includes('@validator') || lower.includes('validator(');
+
+    case 'eval_pydantic_v2_field_validator':
+      // Pydantic v2: uses @field_validator
+      return lower.includes('field_validator');
+
+    case 'train_fastapi_095_sync_dep':
+      // FastAPI 0.95 dependency injection with Depends
+      return lower.includes('depends(') || lower.includes('depends');
+
+    case 'eval_fastapi_100_lifespan':
+      // FastAPI 0.100+: uses lifespan async context manager
+      return lower.includes('lifespan');
+
+    case 'eval_tokio_postgres_07':
+      // tokio-postgres 0.7: connect + spawn connection task
+      return lower.includes('connect') && (lower.includes('tokio::spawn') || lower.includes('spawn') || lower.includes('connection'));
+
+    case 'eval_gin_gonic_v19':
+      // Gin 1.9+: ShouldBindJSON
+      return lower.includes('shouldbindjson');
+
+    default: {
+      // Fallback: check SemVer major/minor string
+      const parts = task.targetVersion.split('.');
+      const majorMinor = parts.slice(0, 2).join('.');
+      return lower.includes(majorMinor) || lower.includes(`v${parts[0]}`);
+    }
+  }
+}

package/packages/export/src/agents-md.ts

@@ -0,0 +1,200 @@
+import type {
+  ApiEndpoint,
+  Pitfall,
+  Recipe,
+  ProjectDependency,
+  VersionResolutionResult,
+} from '../../shared/src/index.ts';
+
+export interface AgentsMdExportData {
+  projectDir?: string;
+  docVersion?: string;
+  dependencies: Array<{
+    dep: ProjectDependency;
+    resolution?: VersionResolutionResult;
+  }>;
+  endpoints: ApiEndpoint[];
+  pitfalls: Pitfall[];
+  recipes: Recipe[];
+  sources: string[];
+}
+
+/**
+ * Generates an AGENTS.md document grounded strictly in indexed documentation.
+ * Preserves exact versions, endpoint signatures, critical caveats, and provenance.
+ * Fully deterministic output.
+ */
+export function generateAgentsMd(data: AgentsMdExportData): string {
+  const lines: string[] = [];
+
+  lines.push('# AGENTS.md — Documentation & Version Intelligence Context');
+  lines.push('');
+  lines.push('> [!NOTE]');
+  lines.push('> **Strict Evidence-Grounding**: All API signatures, version constraints, and pitfalls in this document');
+  lines.push('> are extracted deterministically from indexed documentation. External documentation content is treated');
+  lines.push('> as untrusted input (`untrusted: true`).');
+  lines.push('');
+
+  // 1. Version Matrix & Dependencies
+  lines.push('## 1. Project Dependencies & Version Matrix');
+  lines.push('');
+  if (data.dependencies.length > 0) {
+    lines.push('| Dependency | Ecosystem | Requested | Resolved / Doc Version | Match Type | Confidence |');
+    lines.push('| :--- | :--- | :--- | :--- | :--- | :--- |');
+
+    const sortedDeps = [...data.dependencies].sort((a, b) => a.dep.name.localeCompare(b.dep.name));
+    for (const item of sortedDeps) {
+      const dep = item.dep;
+      const res = item.resolution;
+      const resolved = res?.targetVersion || dep.resolvedVersion || 'unresolved';
+      const matchType = res?.matchedBy || (res?.targetVersion ? 'resolved' : 'unresolved');
+      const conf = res ? `${(res.confidence * 100).toFixed(0)}%` : 'N/A';
+      lines.push(`| \`${dep.name}\` | ${dep.ecosystem} | \`${dep.requestedVersion}\` | \`${resolved}\` | \`${matchType}\` | ${conf} |`);
+    }
+    lines.push('');
+  } else if (data.docVersion) {
+    lines.push(`- **Target Documentation Version Filter**: \`${data.docVersion}\``);
+    lines.push('');
+  } else {
+    lines.push('- *No local package manifests detected; using globally indexed documentation.*');
+    lines.push('');
+  }
+
+  // 2. Core API Contracts
+  lines.push('## 2. Core API Contracts & Signatures');
+  lines.push('');
+  if (data.endpoints.length > 0) {
+    const sortedEndpoints = [...data.endpoints].sort((a, b) => {
+      const cmp = a.path.localeCompare(b.path);
+      return cmp !== 0 ? cmp : a.method.localeCompare(b.method);
+    });
+
+    for (const ep of sortedEndpoints) {
+      const depBadge = ep.deprecated ? ' `[DEPRECATED]`' : '';
+      const versionTag = ep.docVersion ? ` (version: \`${ep.docVersion}\`)` : '';
+      lines.push(`### \`${ep.method.toUpperCase()} ${ep.path}\`${depBadge}${versionTag}`);
+      if (ep.summary) {
+        lines.push(`${ep.summary}`);
+      }
+      lines.push('');
+
+      if (ep.parameters && ep.parameters.length > 0) {
+        lines.push('**Parameters:**');
+        const sortedParams = [...ep.parameters].sort((a, b) => a.name.localeCompare(b.name));
+        for (const p of sortedParams) {
+          const req = p.required ? '**required**' : 'optional';
+          const type = p.type || 'string';
+          const desc = p.description ? ` — ${p.description}` : '';
+          lines.push(`- \`${p.name}\` (\`${p.in}\`, ${req}, type: \`${type}\`)${desc}`);
+        }
+        lines.push('');
+      }
+
+      if (ep.requestSchema) {
+        lines.push('**Request Body Schema:**');
+        lines.push('```json');
+        lines.push(JSON.stringify(ep.requestSchema, null, 2));
+        lines.push('```');
+        lines.push('');
+      }
+
+      if (ep.responseSchema) {
+        lines.push('**Response Schema:**');
+        lines.push('```json');
+        lines.push(JSON.stringify(ep.responseSchema, null, 2));
+        lines.push('```');
+        lines.push('');
+      }
+    }
+  } else {
+    lines.push('- *No structured API endpoints indexed for this version/scope.*');
+    lines.push('');
+  }
+
+  // 3. Critical Pitfalls & Breaking Changes
+  lines.push('## 3. Critical Pitfalls & Breaking Changes');
+  lines.push('');
+  if (data.pitfalls.length > 0) {
+    const sortedPitfalls = [...data.pitfalls].sort((a, b) => {
+      const severityOrder: Record<string, number> = { error: 0, warning: 1, info: 2 };
+      const sA = severityOrder[a.severity || 'warning'] ?? 1;
+      const sB = severityOrder[b.severity || 'warning'] ?? 1;
+      if (sA !== sB) return sA - sB;
+      return a.title.localeCompare(b.title);
+    });
+
+    for (const pf of sortedPitfalls) {
+      const kindLabel = pf.kind.toUpperCase().replace('_', ' ');
+      const versionInfo = pf.affectedVersions?.target || pf.docVersion ? ` (Version: \`${pf.affectedVersions?.target || pf.docVersion}\`)` : '';
+      lines.push(`### [${kindLabel}] ${pf.title}${versionInfo}`);
+      lines.push(`- **Severity**: \`${pf.severity || 'warning'}\``);
+      lines.push(`- **Evidence**: ${pf.message}`);
+      if (pf.mitigation) {
+        lines.push(`- **Mitigation**: ${pf.mitigation}`);
+      }
+      if (pf.provenance?.sourceUrl) {
+        lines.push(`- **Provenance**: [${pf.provenance.sourceUrl}](${pf.provenance.sourceUrl})`);
+      }
+      lines.push('');
+    }
+  } else {
+    lines.push('- *No explicit pitfalls or warnings indexed for this version/scope.*');
+    lines.push('');
+  }
+
+  // 4. Grounded Recipes
+  if (data.recipes.length > 0) {
+    lines.push('## 4. Evidence-Grounded Implementation Recipes');
+    lines.push('');
+    for (const r of data.recipes) {
+      lines.push(`### Recipe: ${r.title}`);
+      lines.push(`**Goal**: ${r.goal}`);
+      lines.push('');
+      if (r.prerequisites.length > 0) {
+        lines.push('**Prerequisites:**');
+        for (const pre of r.prerequisites) {
+          const evidenceTag = pre.evidenceLevel === 'documented_fact' ? '`[DOCUMENTED FACT]`' : '`[INFERRED]`';
+          lines.push(`- ${evidenceTag} ${pre.description}`);
+        }
+        lines.push('');
+      }
+
+      if (r.steps.length > 0) {
+        lines.push('**Implementation Steps:**');
+        for (const step of r.steps) {
+          const evidenceTag = step.evidenceLevel === 'documented_fact' ? '`[DOCUMENTED FACT]`' : '`[INFERRED]`';
+          lines.push(`${step.stepNumber}. ${evidenceTag} **${step.title}**: ${step.action}`);
+          if (step.codeSnippet) {
+            lines.push('   ```' + (step.codeSnippet.language || 'typescript'));
+            lines.push(step.codeSnippet.code.trim().split('\n').map(l => '   ' + l).join('\n'));
+            lines.push('   ```');
+          }
+        }
+        lines.push('');
+      }
+
+      if (r.validationSteps.length > 0) {
+        lines.push('**Evidence-Based Validation Steps:**');
+        for (const val of r.validationSteps) {
+          lines.push(`- **Verify**: ${val.assertion} (Expected: \`${val.expectedOutcome}\`)`);
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  // 5. Provenance & Security Notice
+  lines.push('## 5. Indexed Sources & Provenance');
+  lines.push('');
+  if (data.sources.length > 0) {
+    const sortedSources = [...data.sources].sort();
+    for (const src of sortedSources) {
+      lines.push(`- Source: \`${src}\` (Status: \`indexed\`, Security: \`untrusted: true\`)`);
+    }
+  } else {
+    lines.push('- *No sources indexed.*');
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}

package/packages/export/src/claude-md.ts

@@ -0,0 +1,141 @@
+import type {
+  ApiEndpoint,
+  Pitfall,
+  ProjectDependency,
+  VersionResolutionResult,
+} from '../../shared/src/index.ts';
+
+export interface ClaudeMdExportData {
+  projectDir?: string;
+  docVersion?: string;
+  dependencies: Array<{
+    dep: ProjectDependency;
+    resolution?: VersionResolutionResult;
+  }>;
+  endpoints: ApiEndpoint[];
+  pitfalls: Pitfall[];
+  sources: string[];
+}
+
+/**
+ * Generates a CLAUDE.md developer and agent guide tailored for Claude Code.
+ * Extracts deterministic rules, caveats, verification CLI commands, and API signatures.
+ */
+export function generateClaudeMd(data: ClaudeMdExportData): string {
+  const lines: string[] = [];
+
+  lines.push('# CLAUDE.md — Agent Working Rules & Documentation Contracts');
+  lines.push('');
+  lines.push('> [!IMPORTANT]');
+  lines.push('> **Version-Grounded Rules**: This codebase uses DocOrbit for deterministic documentation intelligence.');
+  lines.push('> Never hallucinate or assume unpinned library versions. All rules and caveats below are extracted');
+  lines.push('> from authoritative indexed documentation (`untrusted: true`).');
+  lines.push('');
+
+  // 1. Architecture & Tech Stack
+  lines.push('## 1. Project Architecture & Dependencies');
+  lines.push('');
+  if (data.dependencies.length > 0) {
+    const sortedDeps = [...data.dependencies].sort((a, b) => a.dep.name.localeCompare(b.dep.name));
+    for (const item of sortedDeps) {
+      const dep = item.dep;
+      const res = item.resolution;
+      const ver = res?.targetVersion || dep.resolvedVersion || dep.requestedVersion;
+      const confidence = res ? ` (doc match confidence: ${(res.confidence * 100).toFixed(0)}%)` : '';
+      lines.push(`- **${dep.name}**: \`${ver}\` [${dep.ecosystem}]${confidence}`);
+    }
+    lines.push('');
+  } else if (data.docVersion) {
+    lines.push(`- Pinned Documentation Scope: \`${data.docVersion}\``);
+    lines.push('');
+  } else {
+    lines.push('- *No project manifests detected; relying on indexed documentation.*');
+    lines.push('');
+  }
+
+  // 2. Deterministic Verification Commands
+  lines.push('## 2. DocOrbit Verification Commands');
+  lines.push('');
+  lines.push('Run these commands before committing generated code:');
+  lines.push('```bash');
+  lines.push('# Verify generated code snippet or file against indexed schemas');
+  lines.push('docorbit verify "<code-or-file-path>"');
+  lines.push('');
+  lines.push('# Check documentation diff across versions (e.g. v14 to v15)');
+  lines.push('docorbit diff --from v14 --to v15');
+  lines.push('');
+  lines.push('# Scan project repository for code impacted by API breaking changes');
+  lines.push('docorbit impact --from v14 --to v15 --project .');
+  lines.push('```');
+  lines.push('');
+
+  // 3. Hard Rules & Caveats (From Pitfalls)
+  lines.push('## 3. Hard Rules & Caveats');
+  lines.push('');
+  if (data.pitfalls.length > 0) {
+    const sortedPitfalls = [...data.pitfalls].sort((a, b) => {
+      const severityOrder: Record<string, number> = { error: 0, warning: 1, info: 2 };
+      const sA = severityOrder[a.severity || 'warning'] ?? 1;
+      const sB = severityOrder[b.severity || 'warning'] ?? 1;
+      if (sA !== sB) return sA - sB;
+      return a.title.localeCompare(b.title);
+    });
+
+    for (const pf of sortedPitfalls) {
+      const prefix = pf.kind === 'removed' || pf.kind === 'breaking_change' || pf.severity === 'error' ? 'NEVER' : 'ALWAYS';
+      const versionNote = pf.affectedVersions?.target || pf.docVersion ? ` (Version: \`${pf.affectedVersions?.target || pf.docVersion}\`)` : '';
+      lines.push(`- **${prefix}**: ${pf.title}${versionNote}`);
+      lines.push(`  - Caveat: ${pf.message}`);
+      if (pf.mitigation) {
+        lines.push(`  - Fix: ${pf.mitigation}`);
+      }
+    }
+    lines.push('');
+  } else {
+    lines.push('- *No explicit warnings or pitfalls recorded.*');
+    lines.push('');
+  }
+
+  // 4. Verified API Endpoints
+  lines.push('## 4. Key API Signatures');
+  lines.push('');
+  if (data.endpoints.length > 0) {
+    const sortedEndpoints = [...data.endpoints].sort((a, b) => {
+      const cmp = a.path.localeCompare(b.path);
+      return cmp !== 0 ? cmp : a.method.localeCompare(b.method);
+    });
+
+    for (const ep of sortedEndpoints) {
+      const req = ep.parameters?.filter(p => p.required).map(p => p.name).join(', ') || 'none';
+      const opt = ep.parameters?.filter(p => !p.required).map(p => p.name).join(', ') || 'none';
+      const depNotice = ep.deprecated ? ' *(deprecated)*' : '';
+      lines.push(`- \`${ep.method.toUpperCase()} ${ep.path}\`${depNotice}:`);
+      if (ep.summary) {
+        lines.push(`  - Summary: ${ep.summary}`);
+      }
+      lines.push(`  - Required parameters: \`${req}\``);
+      if (opt !== 'none') {
+        lines.push(`  - Optional parameters: \`${opt}\``);
+      }
+    }
+    lines.push('');
+  } else {
+    lines.push('- *No indexed endpoints.*');
+    lines.push('');
+  }
+
+  // 5. Security & Provenance
+  lines.push('## 5. Provenance Notice');
+  lines.push('');
+  lines.push('All external documentation indexed by DocOrbit is treated as untrusted third-party input.');
+  if (data.sources.length > 0) {
+    const sortedSources = [...data.sources].sort();
+    lines.push('Sources:');
+    for (const s of sortedSources) {
+      lines.push(`- \`${s}\``);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}

package/packages/export/src/docs-map.ts

@@ -0,0 +1,150 @@
+import type {
+  NormalizedPage,
+  DocumentChunk,
+  ApiEndpoint,
+  Pitfall,
+  DiscoveredSource,
+  DocumentationMapNode,
+  DocumentationMapResult,
+} from '../../shared/src/index.ts';
+
+export interface DocsMapInputData {
+  sources: DiscoveredSource[];
+  pages: NormalizedPage[];
+  chunks?: DocumentChunk[];
+  endpoints?: ApiEndpoint[];
+  pitfalls?: Pitfall[];
+  docVersion?: string;
+}
+
+/**
+ * Builds a comprehensive, hierarchical documentation map with token estimates and provenance.
+ * Fully deterministic.
+ */
+export function buildDocumentationMap(data: DocsMapInputData): DocumentationMapResult {
+  const pages = [...data.pages];
+  const sources = [...data.sources];
+  const endpoints = data.endpoints || [];
+  const pitfalls = data.pitfalls || [];
+  const chunks = data.chunks || [];
+
+  // Group chunks by pageId
+  const chunkCountByPage = new Map<string, number>();
+  const tokenEstimateByPage = new Map<string, number>();
+
+  for (const chunk of chunks) {
+    chunkCountByPage.set(chunk.pageId, (chunkCountByPage.get(chunk.pageId) || 0) + 1);
+    const tokens = chunk.tokenEstimate || 0;
+    tokenEstimateByPage.set(chunk.pageId, (tokenEstimateByPage.get(chunk.pageId) || 0) + tokens);
+  }
+
+  // Group endpoints by pageId
+  const apisByPage = new Map<string, string[]>();
+  for (const ep of endpoints) {
+    if (!apisByPage.has(ep.pageId)) {
+      apisByPage.set(ep.pageId, []);
+    }
+    apisByPage.get(ep.pageId)!.push(`${ep.method.toUpperCase()} ${ep.path}`);
+  }
+
+  // Group pitfalls by pageId
+  const pitfallsByPage = new Map<string, number>();
+  for (const pf of pitfalls) {
+    pitfallsByPage.set(pf.pageId, (pitfallsByPage.get(pf.pageId) || 0) + 1);
+  }
+
+  // Build page nodes
+  const sortedPages = pages.sort((a, b) => a.url.localeCompare(b.url));
+  const pageNodes: DocumentationMapNode[] = sortedPages.map(p => {
+    const chunkCount = chunkCountByPage.get(p.id) || (p.headings ? Math.max(1, p.headings.length) : 1);
+    const estimatedTokens = tokenEstimateByPage.get(p.id) || p.estimatedTokens || 150;
+    const pageApis = apisByPage.get(p.id) || [];
+    const pagePitfalls = pitfallsByPage.get(p.id) || 0;
+
+    return {
+      id: p.id,
+      title: p.title || p.url,
+      url: p.url,
+      version: p.provenance?.versionTag || data.docVersion,
+      sourceId: p.sourceId,
+      chunkCount,
+      estimatedTokens,
+      headings: (p.headings || []).map(h => typeof h === 'string' ? h : (h as any).text || ''),
+      apis: pageApis.length > 0 ? pageApis : undefined,
+      pitfallCount: pagePitfalls > 0 ? pagePitfalls : undefined,
+      untrusted: true,
+    };
+  });
+
+  const totalPages = pageNodes.length;
+  const totalChunks = pageNodes.reduce((acc, p) => acc + p.chunkCount, 0);
+  const totalEstimatedTokens = pageNodes.reduce((acc, p) => acc + p.estimatedTokens, 0);
+
+  // Group by source
+  const sourceSummaries = sources.map(s => {
+    const sourcePages = pageNodes.filter(p => p.sourceId === s.id);
+    return {
+      id: s.id,
+      url: s.url,
+      pageCount: sourcePages.length,
+      chunkCount: sourcePages.reduce((acc, p) => acc + p.chunkCount, 0),
+    };
+  });
+
+  // Generate Markdown representation
+  const lines: string[] = [];
+  lines.push('# Documentation Map & Token Footprint');
+  lines.push('');
+  lines.push(`- **Total Indexed Sources**: ${sources.length}`);
+  lines.push(`- **Total Pages**: ${totalPages}`);
+  lines.push(`- **Total Chunks**: ${totalChunks}`);
+  lines.push(`- **Total Estimated Tokens**: ~${totalEstimatedTokens.toLocaleString()}`);
+  lines.push('- **Security Boundary**: `untrusted: true`');
+  lines.push('');
+
+  lines.push('## Documentation Tree');
+  lines.push('');
+
+  for (const s of sources) {
+    lines.push(`### Source: \`${s.url}\``);
+    const sourcePages = pageNodes.filter(p => p.sourceId === s.id);
+    if (sourcePages.length === 0) {
+      lines.push('  - *(No pages indexed under this source)*');
+    } else {
+      for (const p of sourcePages) {
+        const tokenBadge = `~${p.estimatedTokens} tokens`;
+        const chunkBadge = `${p.chunkCount} chunks`;
+        const verBadge = p.version ? ` [version: ${p.version}]` : '';
+        lines.push(`  - **[${p.title}](${p.url})** (${chunkBadge}, ${tokenBadge})${verBadge}`);
+
+        if (p.headings && p.headings.length > 0) {
+          for (const h of p.headings.slice(0, 5)) {
+            lines.push(`    - section: ${h}`);
+          }
+          if (p.headings.length > 5) {
+            lines.push(`    - ... and ${p.headings.length - 5} more sections`);
+          }
+        }
+
+        if (p.apis && p.apis.length > 0) {
+          lines.push(`    - *APIs: ${p.apis.join(', ')}*`);
+        }
+        if (p.pitfallCount) {
+          lines.push(`    - *Warnings/Pitfalls: ${p.pitfallCount} recorded*`);
+        }
+      }
+    }
+    lines.push('');
+  }
+
+  return {
+    totalSources: sources.length,
+    totalPages,
+    totalChunks,
+    totalEstimatedTokens,
+    sources: sourceSummaries,
+    pages: pageNodes,
+    markdownTree: lines.join('\n'),
+    untrusted: true,
+  };
+}

package/packages/export/src/index.ts

@@ -0,0 +1,6 @@
+export * from './agents-md.ts';
+export * from './claude-md.ts';
+export * from './skill-md.ts';
+export * from './llms-txt.ts';
+export * from './docs-map.ts';
+export * from './service.ts';

package/packages/export/src/llms-txt.ts

@@ -0,0 +1,96 @@
+import type {
+  NormalizedPage,
+  ApiEndpoint,
+  Pitfall,
+} from '../../shared/src/index.ts';
+
+export interface LlmsTxtExportData {
+  title?: string;
+  summary?: string;
+  docVersion?: string;
+  pages: NormalizedPage[];
+  endpoints: ApiEndpoint[];
+  pitfalls: Pitfall[];
+  full?: boolean;
+}
+
+/**
+ * Generates an llms.txt (or llms-full.txt) document according to the llms.txt specification.
+ * Fully deterministic output.
+ */
+export function generateLlmsTxt(data: LlmsTxtExportData): string {
+  const lines: string[] = [];
+  const title = data.title || 'Documentation Index';
+  const summary = data.summary || 'Curated machine-readable documentation index generated by DocOrbit.';
+
+  lines.push(`# ${title}`);
+  lines.push('');
+  lines.push(`> ${summary}`);
+  lines.push('');
+
+  if (data.docVersion) {
+    lines.push(`Documentation Version: \`${data.docVersion}\``);
+    lines.push('');
+  }
+
+  // 1. Pages / Core Docs
+  lines.push('## Documentation Pages');
+  lines.push('');
+  if (data.pages.length > 0) {
+    const sortedPages = [...data.pages].sort((a, b) => a.url.localeCompare(b.url));
+    for (const page of sortedPages) {
+      const pageTitle = page.title || page.url;
+      const tokens = page.estimatedTokens ? ` (~${page.estimatedTokens} tokens)` : '';
+      lines.push(`- [${pageTitle}](${page.url})${tokens}`);
+    }
+    lines.push('');
+  } else {
+    lines.push('- *No documentation pages indexed.*');
+    lines.push('');
+  }
+
+  // 2. API Reference
+  if (data.endpoints.length > 0) {
+    lines.push('## API Reference');
+    lines.push('');
+    const sortedEndpoints = [...data.endpoints].sort((a, b) => {
+      const cmp = a.path.localeCompare(b.path);
+      return cmp !== 0 ? cmp : a.method.localeCompare(b.method);
+    });
+
+    for (const ep of sortedEndpoints) {
+      const desc = ep.summary ? `: ${ep.summary}` : '';
+      const provUrl = ep.provenance?.sourceUrl || `#`;
+      lines.push(`- [${ep.method.toUpperCase()} ${ep.path}](${provUrl})${desc}`);
+    }
+    lines.push('');
+  }
+
+  // 3. Pitfalls & Warnings
+  if (data.pitfalls.length > 0) {
+    lines.push('## Critical Caveats & Warnings');
+    lines.push('');
+    const sortedPitfalls = [...data.pitfalls].sort((a, b) => a.title.localeCompare(b.title));
+    for (const pf of sortedPitfalls) {
+      const provUrl = pf.provenance?.sourceUrl || `#`;
+      lines.push(`- [${pf.title}](${provUrl}): ${pf.message}`);
+    }
+    lines.push('');
+  }
+
+  // If full mode requested, append full page text
+  if (data.full) {
+    lines.push('---');
+    lines.push('## Full Documentation Content');
+    lines.push('');
+    const sortedPages = [...data.pages].sort((a, b) => a.url.localeCompare(b.url));
+    for (const page of sortedPages) {
+      lines.push(`### [${page.title || page.url}](${page.url})`);
+      lines.push('');
+      lines.push(page.content.trim());
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}