llms.txt

llms-full.txt

cat docs/**/*.mdx > llms-full.txt

{
  "llms": {
    "enabled": true,
    "output": {
      "compact": "dist/llms.txt",
      "full": "dist/llms-full.txt",
      "manifest": "dist/llms-manifest.json"
    },
    "include": {
      "pages": ["overview", "quickstart", "howTo", "reference", "apiReference"],
      "drafts": false,
      "hidden": false,
      "internal": false,
      "codeSamples": true,
      "apiReference": true,
      "configReference": true,
      "cliReference": true
    },
    "limits": {
      "compactMaxChars": 50000,
      "fullMaxChars": 2000000,
      "pageSummaryMaxChars": 1200,
      "codeSampleLanguages": ["curl", "javascript", "python"]
    },
    "provenance": {
      "includeInline": false,
      "includeManifest": true
    }
  }
}

export type LlmsExportInput = {
  site: SiteMetadata;
  pages: CompiledPage[];
  pageManifest: PageManifest;
  nav: NavTree;
  routeIndex: RouteIndex;
  apiRegistry?: OpenApiRegistry;
  semanticArtifacts: SemanticArtifactIndex;
  codeSamples: GeneratedCodeSample[];
  provenance: ProvenanceStore;
  config: LlmsConfig;
};

export type LlmsExportResult = {
  compact?: LlmsExportFile;
  full?: LlmsExportFile;
  manifest?: LlmsManifest;
  chunks?: LlmsChunkManifest;
  diagnostics: Diagnostic[];
};

export type LlmsExportFile = {
  path: string;
  content: string;
  contentHash: string;
  sizeBytes: number;
};

export function shouldIncludePageInLlms(
  page: CompiledPage,
  config: LlmsConfig
): boolean {
  if (page.frontmatter.draft && !config.include.drafts) return false;
  if (page.frontmatter.hidden && !config.include.hidden) return false;
  if (page.visibility === "internal" && !config.include.internal) return false;
  if (!config.include.pages.includes(page.kind)) return false;
  if (page.provenance?.verificationStatus === "failed") return false;

  return true;
}

do not include failed/unverified generated content in compact export

export function orderPagesForLlms(pages: CompiledPage[], nav: NavTree): CompiledPage[] {
  const navRank = buildNavRank(nav);

  return [...pages].sort((a, b) =>
    (navRank.get(a.id) ?? 999999) - (navRank.get(b.id) ?? 999999)
  );
}

export type ComponentMarkdownExporter = {
  componentName: string;
  toMarkdown(node: ComponentNode, ctx: MarkdownExportContext): string;
};

<Callout type="warning" title="Remote specs">
Remote specs are disabled by default.
</Callout>

> **Warning: Remote specs**
>
> Remote specs are disabled by default.

<Tabs>
  <Tab title="npm">...</Tab>
  <Tab title="pnpm">...</Tab>
</Tabs>

#### npm

...

#### pnpm

...

<Card title="Quickstart" href="/quickstart" />

- [Quickstart](/quickstart)

### Create user

Method: `POST`  
Path: `/users`  
Operation ID: `createUser`  
Auth: Bearer token required  
Request schema: `CreateUserRequest`  
Success response: `201` `User`

See: `/api-reference/users/create-user`

### `docforge build`

Builds the static documentation site.

Common options:
- `--out <dir>`: set output directory
- `--strict`: fail on configured warnings
- `--no-search`: skip search index generation

See: `/reference/cli/build`

### Build configuration

Important fields:
- `build.outputDir`: static build output directory
- `build.basePath`: base path for deployed site
- `search.enabled`: enable static search index

See: `/reference/configuration`

### cURL

```bash
curl -X POST "https://api.example.com/users" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```

{
  "llms": {
    "limits": {
      "codeSampleLanguages": ["curl", "javascript"]
    }
  }
}

{
  "llms": {
    "links": {
      "mode": "route",
      "siteUrl": "https://docs.example.com"
    }
  }
}

export function rewriteLinkForLlms(href: string, ctx: LlmsLinkContext): string {
  if (isExternalUrl(href)) return href;

  const route = normalizeInternalHref(href, ctx.currentRoute);

  if (ctx.mode === "absolute" && ctx.siteUrl) {
    return new URL(route, ctx.siteUrl).toString();
  }

  return route;
}

# <Site title>

<Site description>

## How to use these docs

This file is a compact guide for AI assistants. Use links to retrieve full pages when needed.

## Start here

- [Quickstart](/quickstart)
- [Installation](/installation)
- [Configuration](/reference/configuration)

## Common tasks

- Generate API reference from OpenAPI: /guides/openapi-reference
- Build static docs: /reference/cli/build
- Fix MDX errors: /troubleshooting/mdx-errors

## Reference

### CLI

...

### Configuration

...

### API

...

## Troubleshooting

...

# Full documentation export

Generated from <site>.

## Table of contents

...

---

# Quickstart

...

---

# Configuration Reference

...

---

# API Reference: Create user

...

<!-- page: /quickstart title="Quickstart" -->

export function summarizePageForLlms(page: CompiledPage, maxChars: number): string {
  const parts = [
    page.frontmatter.description,
    topHeadings(page).map((h) => `- ${h.text}`).join("\n"),
  ].filter(Boolean);

  return truncate(parts.join("\n"), maxChars);
}

export type AgentTaskMapEntry = {
  task: string;
  route: RoutePath;
  anchors?: string[];
  keywords: string[];
};

## Task map

- To initialize docs, read `/quickstart`.
- To configure OpenAPI ingestion, read `/guides/openapi-reference` and `/reference/configuration#openapi`.
- To troubleshoot MDX component errors, read `/troubleshooting/mdx-errors`.
- To find CLI options, read `/reference/cli`.

## Agent usage rules

- Prefer formal reference pages for API, CLI, and config facts.
- Do not invent CLI flags, config fields, API parameters, or response schemas.
- If a required fact is not present here, say that the docs do not provide it.
- Use code examples only if they appear in the relevant page or API reference.
- Treat deprecated endpoints as deprecated.

export type LlmsManifest = {
  schemaVersion: "llms-manifest/v1";
  generatedAt: string;
  site: SiteMetadata;
  files: LlmsManifestFile[];
  chunks: LlmsManifestChunk[];
};

export type LlmsManifestFile = {
  path: string;
  contentHash: string;
  sizeBytes: number;
  kind: "compact" | "full" | "chunks";
};

export type LlmsManifestChunk = {
  id: string;
  file: string;
  startOffset: number;
  endOffset: number;
  route?: RoutePath;
  pageId?: PageId;
  blockIds: string[];
  sourceRefs: SourceRef[];
  visibility: "public" | "internal";
};

llms-chunks.jsonl

{
  "id": "chunk:quickstart:install",
  "route": "/quickstart",
  "title": "Install DocForge",
  "text": "Install the CLI...",
  "kind": "howTo",
  "tags": ["quickstart", "install"],
  "sourceRefs": []
}

export type LlmsChunk = {
  id: string;
  pageId: PageId;
  route: RoutePath;
  anchor?: string;
  title: string;
  headingPath: string[];
  text: string;
  kind: PageKind;
  tags: string[];
  entities: AgentEntityRef[];
  sourceRefs: SourceRef[];
  contentHash: string;
};

500-1500 tokens

{
  "llms": {
    "chunks": {
      "targetChars": 4000,
      "maxChars": 8000
    }
  }
}

export type AgentEntityRef =
  | { type: "apiOperation"; operationId: string; method: string; path: string }
  | { type: "cliCommand"; command: string }
  | { type: "configField"; field: string }
  | { type: "codeSymbol"; symbolId: string; name: string }
  | { type: "page"; route: RoutePath };

{
  "entities": [
    {
      "type": "configField",
      "field": "build.outputDir"
    }
  ]
}

export function filterChunkForLlms(
  chunk: LlmsChunk,
  policy: LlmsPrivacyPolicy
): LlmsChunk | undefined {
  if (chunk.visibility === "internal" && !policy.includeInternal) {
    return undefined;
  }

  if (containsSensitiveSourceRefs(chunk.sourceRefs) && !policy.includeSensitive) {
    return undefined;
  }

  return redactChunkSecrets(chunk);
}

export type LlmsPrivacyPolicy = {
  includeInternal: boolean;
  includeSensitive: boolean;
  exposeSourceRefs: boolean;
  redactSecrets: boolean;
};

includeInternal=false
includeSensitive=false
exposeSourceRefs=false
redactSecrets=true

error llms.secret.detected
llms-full.txt contains a secret-like value.

fail for stale public generated content

{
  "llms": {
    "stalePolicy": "fail"
  }
}

includeWithWarning

> Warning: This section may be stale because the source API operation changed.

error llms.privatePageIncluded
Agent export includes private page /internal/runbooks.

warning llms.compact.tooLarge
llms.txt exceeds compact size budget.

export function estimateTokens(text: string): number {
  return Math.ceil(text.length / 4);
}

export type LlmsBudgetAllocation = {
  overview: number;
  taskMap: number;
  quickstart: number;
  guides: number;
  reference: number;
  api: number;
  troubleshooting: number;
};

export function scorePageForCompactLlms(page: CompiledPage): number {
  let score = 0;

  if (page.kind === "quickstart") score += 100;
  if (page.kind === "overview") score += 90;
  if (page.kind === "howTo") score += 70;
  if (page.kind === "reference") score += 60;
  if (page.kind === "apiReference") score += 40;
  if (page.kind === "troubleshooting") score += 50;

  if (page.frontmatter.featured) score += 20;
  if (page.provenance?.verificationStatus === "verified") score += 10;
  if (page.frontmatter.hidden) score -= 1000;

  return score;
}

export async function buildLlmsCompact(input: LlmsExportInput): Promise<LlmsExportFile> {
  const pages = input.pages
    .filter((page) => shouldIncludePageInLlms(page, input.config))
    .sort((a, b) => scorePageForCompactLlms(b) - scorePageForCompactLlms(a));

  const sections = [
    renderLlmsHeader(input.site),
    renderAgentUsageRules(input.config),
    renderTaskMap(input),
    renderStartHere(input, pages),
    renderReferenceSummaries(input),
    renderTroubleshootingSummaries(input, pages),
  ];

  const content = enforceCompactBudget(sections.join("\n\n"), input.config.limits.compactMaxChars);

  return {
    path: input.config.output.compact,
    content,
    contentHash: sha256(content),
    sizeBytes: Buffer.byteLength(content),
  };
}

export async function buildLlmsFull(input: LlmsExportInput): Promise<LlmsExportFile> {
  const pages = orderPagesForLlms(
    input.pages.filter((page) => shouldIncludePageInLlms(page, input.config)),
    input.nav
  );

  const parts = [
    renderFullHeader(input.site),
    renderFullToc(pages),
    ...pages.map((page) => renderPageForLlmsFull(page, input)),
  ];

  const content = parts.join("\n\n---\n\n");

  if (content.length > input.config.limits.fullMaxChars) {
    return applyFullExportBudget(content, input);
  }

  return {
    path: input.config.output.full,
    content,
    contentHash: sha256(content),
    sizeBytes: Buffer.byteLength(content),
  };
}

export function renderPageForLlmsFull(
  page: CompiledPage,
  input: LlmsExportInput
): string {
  const body = page.blocks
    .map((block) => renderBlockToMarkdown(block, {
      componentRegistry: input.config.componentRegistry,
      linkMode: input.config.links.mode,
      currentRoute: page.route,
    }))
    .join("\n\n");

  return [
    `<!-- page: ${page.route} title="${escapeHtmlAttr(page.title)}" -->`,
    `# ${page.title}`,
    "",
    page.description ? `> ${page.description}` : "",
    "",
    body,
  ].filter(Boolean).join("\n");
}

export function apiOperationToLlmsMarkdown(
  operation: NormalizedOperation,
  mode: "compact" | "full"
): string {
  if (mode === "compact") {
    return [
      `### ${operationTitle(operation)}`,
      "",
      `Method: \`${operation.method}\``,
      `Path: \`${operation.path}\``,
      operation.operationId ? `Operation ID: \`${operation.operationId}\`` : undefined,
      operation.summary,
      `Route: ${routeForOperation(operation)}`,
    ].filter(Boolean).join("\n");
  }

  return renderFullApiOperationMarkdown(operation);
}

Schema: `User`

### Schema `User`

| Field | Type | Required | Description |
|---|---|---:|---|
| `id` | string | yes | User ID |
| `email` | string | yes | Email address |

### Request example

```bash
curl ...

## Source of truth priority

When answering:
1. Use API Reference for endpoint methods, paths, parameters, request bodies, and responses.
2. Use Configuration Reference for config fields and defaults.
3. Use CLI Reference for commands and flags.
4. Use Guides for task flow.
5. If references conflict with guides, prefer references and mention the conflict.

error llms.unresolvedConflict
Agent export would include conflicting facts for config field search.enabled.

<!-- generated by DocForge 1.0.0 -->
<!-- docs build: sha256:... -->
<!-- generated at: 2026-07-03T00:00:00Z -->

{
  "llms": {
    "includeGeneratedAt": false
  }
}

dist/
  llms.txt
  llms-full.txt
  llms-manifest.json
  llms-chunks.jsonl

docs/.generated/llms-preview.txt

{
  "chunks": [
    {
      "id": "chunk:quickstart:intro",
      "route": "/quickstart",
      "sourceRefs": []
    }
  ]
}

{
  "sourceRefs": [
    {
      "path": "src/commands/build.ts",
      "range": { "startLine": 12, "endLine": 48 }
    }
  ]
}

{"id":"chunk:quickstart:install","route":"/quickstart","title":"Install DocForge","headingPath":["Quickstart","Install"],"text":"Install the CLI...","kind":"quickstart","tags":["install"],"entities":[{"type":"cliCommand","command":"docforge init"}],"contentHash":"sha256:..."}

export function llmsChunkId(page: CompiledPage, headingPath: string[], index: number): string {
  return `chunk:${page.id}:${slugify(headingPath.join("-"))}:${index}`;
}

export type AgentRouteMapEntry = {
  route: RoutePath;
  title: string;
  kind: PageKind;
  summary: string;
  chunks: string[];
  entities: AgentEntityRef[];
};

export type AgentArtifactMap = {
  apiOperations: Array<{
    operationId: string;
    method: string;
    path: string;
    route: RoutePath;
    chunkIds: string[];
  }>;
  cliCommands: Array<{
    command: string;
    route: RoutePath;
    chunkIds: string[];
  }>;
  configFields: Array<{
    field: string;
    route: RoutePath;
    anchor?: string;
    chunkIds: string[];
  }>;
};

export type AgentAlias = {
  term: string;
  target: {
    route: RoutePath;
    anchor?: string;
    entity?: AgentEntityRef;
  };
  source: "manual" | "generated" | "telemetry" | "eval";
};

{
  "term": "output directory",
  "target": {
    "route": "/reference/configuration",
    "anchor": "build-outputdir"
  }
}

export type LlmsEvalCase = {
  id: string;
  question: string;
  requiredRoutes: RoutePath[];
  requiredFacts: string[];
};

docforge eval run --suite agent-ready

warning llms.component.noMarkdownExport
Component <ApiPlayground> has no Markdown export. Interactive UI will be omitted.

error llms.component.criticalNoMarkdownExport
Critical component <ApiOperation> cannot be exported to agent-readable Markdown.

warning llms.html.omitted
Raw HTML block was omitted from agent export.

{
  "llms": {
    "locales": ["en", "id"],
    "defaultLocale": "en"
  }
}

{
  "locale": "id"
}

/v1/llms.txt
/v2/llms.txt
/llms.txt -> latest stable

export type AgentDocsVersion = {
  version: string;
  routePrefix: string;
  status: "latest" | "stable" | "deprecated" | "preview";
};

Version: 2.0
Status: latest stable

### Deprecated endpoint: Delete legacy user

Status: deprecated  
Replacement: `DELETE /v2/users/{id}`  
Route: `/api-reference/users/delete-legacy-user`

### Error: Unknown MDX component

Symptom:
Build fails with `Unknown component`.

Likely cause:
The page uses a component not registered in the theme.

Fix:
Use an allowed component or register the component in the theme.

See: `/troubleshooting/mdx-components`

## Diagnostic codes

### `link.internal.routeNotFound`

Meaning:
An internal link points to a missing route.

Fix:
Update the link or create the target page.

See: `/troubleshooting/broken-links`

## Command catalog

- `docforge init`: initialize docs project.
- `docforge dev`: run local dev server.
- `docforge build`: build static site.
- `docforge check`: run quality gates.
- `docforge update`: update stale generated docs.

## API catalog

### Users

- `POST /users` — Create user. See `/api-reference/users/create-user`.
- `GET /users/{id}` — Get user. See `/api-reference/users/get-user`.

### Projects

...

## Configuration catalog

### `openapi.specs`

Defines OpenAPI specs to ingest.

Fields:
- `id`
- `path`
- `url`
- `baseRoute`

See: `/reference/configuration#openapi-specs`

/llms.txt
/llms-full.txt
/__docforge/llms-manifest.json

docforge llms build
docforge llms inspect
docforge llms chunks
docforge llms validate

llms.txt

Size: 42 KB
Estimated tokens: 10.5k
Pages included: 18
Pages excluded:
- drafts: 2
- hidden: 3
- internal: 4

Diagnostics:
- warning llms.component.noMarkdownExport <ApiPlayground>

docforge llms inspect --route /quickstart

Route: /quickstart
Included in compact: yes
Included in full: yes
Chunks:
- chunk:quickstart:intro
- chunk:quickstart:install
Entities:
- cliCommand: docforge init
- cliCommand: docforge dev

fixtures/llms/
  basic-site/
  hidden-page/
  internal-page/
  api-operation/
  component-tabs/
  private-evidence/
  stale-page/
  huge-api/

it("excludes hidden pages", async () => {
  const result = await buildLlmsFixture("hidden-page");

  expect(result.compact.content).not.toContain("Hidden page title");
});

it("exports ApiOperation as Markdown", async () => {
  const result = await buildLlmsFixture("api-operation");

  expect(result.full.content).toContain("Method: `POST`");
  expect(result.full.content).toContain("Path: `/users`");
});

it("does not expose source refs in public manifest", async () => {
  const result = await buildLlmsFixture("private-evidence", publicPolicy());

  expect(JSON.stringify(result.manifest)).not.toContain("src/internal");
});

it("fails when private page is included", async () => {
  const result = await buildLlmsFixture("internal-page-misconfigured");

  expect(result.diagnostics).toContainEqual(
    expect.objectContaining({ code: "llms.privatePageIncluded" })
  );
});

it("keeps compact export under budget", async () => {
  const result = await buildLlmsFixture("huge-api", {
    compactMaxChars: 50000,
  });

  expect(result.compact.content.length).toBeLessThanOrEqual(50000);
});

packages/agent-docs/
  src/
    config.ts
    input.ts
    export-policy.ts
    markdown/
      render-page.ts
      render-block.ts
      components.ts
      links.ts
    llms/
      compact.ts
      full.ts
      manifest.ts
      chunks.ts
      budget.ts
      task-map.ts
      catalogs/
        api.ts
        cli.ts
        config.ts
        diagnostics.ts
    privacy.ts
    quality.ts
    inspect.ts
    __tests__/
      compact.test.ts
      full.test.ts
      manifest.test.ts
      privacy.test.ts
      budget.test.ts
      components.test.ts