docorbit 0.1.0 → 0.1.2

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

@@ -1,73 +0,0 @@
-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

@@ -1,200 +0,0 @@
-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

@@ -1,141 +0,0 @@
-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

@@ -1,150 +0,0 @@
-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/llms-txt.ts

@@ -1,96 +0,0 @@
-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');
-}