{
  "id": "agent-interface",
  "title": "Agent interfaces",
  "description": "Retrieve documentation through llms.txt and the JSON API without scraping the rendered site.",
  "type": "reference",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "llms",
    "api",
    "agents"
  ],
  "related": [
    "home",
    "content-model",
    "publishing"
  ],
  "sourceRefs": [
    "../../core/build.mjs",
    "../../AGENTS.md"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Start at the published entry points\n\nAfter `build`, an agent reads `dist/llms.txt` to discover the subject, then `dist/api/manifest.json` to learn the API version and published paths.\n\n## Retrieve structured documents\n\n`dist/api/index.json` lists documents. Every `dist/api/documents/{id}.json` record includes metadata, sections, relationships, and `sourceRefs`. Use `dist/api/graph.json` to traverse related pages and `dist/api/search.json` to retrieve by topic.\n\nFor linear context, `dist/llms-full.txt` concatenates the Markdown sources. Human-readable Markdown copies live in `dist/markdown/{id}.md`.\n\nVisual records live at `dist/api/diagrams/{id}.json`. Authored HTML is not duplicated into that JSON; agents receive the visual `kind`, a standalone `summary`, structured `data`, provenance, dimensions, and `renderMode`. Markdown projections expand real diagram directives into readable descriptions while preserving directive examples inside fenced code blocks.\n\n## Do not infer facts from a drawing\n\nHTML and diagrams are reading projections. The JSON API and declared `sourceRefs` are the contracts for traceable facts. This lets an agent answer precisely without depending on browser layout or SVG geometry.",
  "sections": [
    {
      "id": "start-at-the-published-entry-points",
      "level": 2,
      "title": "Start at the published entry points",
      "text": "After `build`, an agent reads `dist/llms.txt` to discover the subject, then `dist/api/manifest.json` to learn the API version and published paths.",
      "line": 1
    },
    {
      "id": "retrieve-structured-documents",
      "level": 2,
      "title": "Retrieve structured documents",
      "text": "`dist/api/index.json` lists documents. Every `dist/api/documents/{id}.json` record includes metadata, sections, relationships, and `sourceRefs`. Use `dist/api/graph.json` to traverse related pages and `dist/api/search.json` to retrieve by topic.  For linear context, `dist/llms-full.txt` concatenates the Markdown sources. Human-readable Markdown copies live in `dist/markdown/{id}.md`.  Visual records live at `dist/api/diagrams/{id}.json`. Authored HTML is not duplicated into that JSON; agents receive the visual `kind`, a standalone `summary`, structured `data`, provenance, dimensions, and `renderMode`. Markdown projections expand real diagram directives into readable descriptions while preserving directive examples inside fenced code blocks.",
      "line": 5
    },
    {
      "id": "do-not-infer-facts-from-a-drawing",
      "level": 2,
      "title": "Do not infer facts from a drawing",
      "text": "HTML and diagrams are reading projections. The JSON API and declared `sourceRefs` are the contracts for traceable facts. This lets an agent answer precisely without depending on browser layout or SVG geometry.",
      "line": 13
    }
  ],
  "sourcePath": "content/agent-interface.md",
  "visuals": [],
  "apiVersion": 1
}