AI documentation
The AI documentation generator that reads your code
Most AI doc generators are a chat window. You paste code, you get prose, you paste the prose somewhere. Chiltepin puts the generator inside the repository. Your agent reads the codebase, writes Markdown with typed YAML blocks, and chiltepin check validates every block before a human reads the pull request. The output is source, not a screenshot or a wiki page.
What an AI documentation generator gets wrong
Three failures show up in nearly every AI-written document. Know them before you trust a generator with your docs.
- Hallucinated facts. The model writes a status code, a field name, or a retry policy that does not exist. The sentence reads well. That is the problem.
- Unverifiable diagrams. An image of an architecture cannot be diffed, linted, or compared to the code. Nobody can tell if the arrow is right.
- Drift. The doc was correct on the day it was written. The handler changed a month later and the doc did not.
Chiltepin addresses part of this, and it is worth being exact about which part. Validation catches structural errors: a missing field, a reference to a block that does not exist, a duplicate id, a message from an actor the diagram never declared. Validation checks structure, not truth. chiltepin check cannot know whether POST /orders returns 201. Render-by-code fixes the diagram problem: the model writes data and the renderer draws it, so every diagram is text you can review. Source-in-Git addresses drift by putting the doc next to the code it describes, so the same pull request can change both. What remains is the fact check, and that is a job for the reviewer and for an agent that reads the real code before it writes.
The workflow
One prompt to the agent you already use:
Document the orders service in docs/orders.md: an endpoint
card for each route in src/orders/routes.ts, a sequence diagram
of the place-order path, and the error table from the handlers.
Run chiltepin check and fix anything it reports.- Request. You ask for a document in plain words. The agent has the authoring skill, installed once with
npx skills add jdiejim/chiltepin. - The agent reads the code. Routes, handlers, migrations, types. It picks the block types that fit the content: an endpoint card for a route, a sequence diagram for a request path, an ERD for the tables.
- It writes blocks. Each block is a fenced section of Markdown with a type and a YAML body. About a kilobyte of data per diagram.
- Check.
chiltepin checkruns the strict schemas, resolves every reference, and exits non-zero in CI on any error. The agent fixes what it reports before it hands off. - Render. The build draws deterministic SVG and HTML from the data and exports a static site, a standalone HTML file, slides, or a PDF.
- PR review. A person reads the diff. The structure is already verified, so the review is about whether the facts match the code.
In our own generation eval (40 scenarios, September 2026) an agent with the skill chose the right block 39.5 times out of 40. 33 of 40 documents were clean on first write and 40 of 40 at handoff, with 0 render failures, at about 91 seconds per document. The scenarios and scoring are in the repository.
An API doc block, written by the agent, drawn by the renderer
The endpoint block is what the agent writes for one HTTP route. The YAML above is the entire source. The card below is what the build produces from it. No layout instructions, no pixels, no image file.
```endpoint
method: POST
path: /orders
title: Create an order
description: Submit a cart and create a new order.
auth: Bearer token
params:
- { name: idempotency-key, in: header, type: string, desc: Safe-retry key }
body:
- { name: items, type: "Item[]", required: true, desc: Line items }
- { name: coupon, type: string, desc: Optional discount code }
responses:
- { status: 201, desc: Order created }
- { status: 400, desc: Invalid cart }
- { status: 401, desc: Missing or invalid token }
request: |
{ "items": [{ "sku": "A1", "qty": 2 }] }
response: |
{ "id": "ord_123", "status": "pending" }
```The same grammar covers dozens of block types across 13 families: narrative, tables, API, architecture, flows and state, data models, charts, planning, decisions, design systems, algorithms, and AI agents. See the Orders REST API document in the gallery for a full API reference an agent wrote from a codebase, or the outage postmortem for a document that is mostly timeline and decisions. All 40 are at /gallery with their source.
Starting from an existing codebase
Two commands help before the agent writes a line. chiltepin audit scans a codebase and recommends which documents to write first: the API with no reference, the service with no architecture map. chiltepin sync converts what you already have (OpenAPI, SQL, DBML, Prisma, CSV) into blocks, so the generator starts from your schema instead of guessing at it. Studio, a browser editor, is there for the edits that are faster by hand.
All of this is the docs-as-code workflow with one addition: a schema over the structured content, so an agent's output can be checked the way tests check its code. For diagrams specifically, see the AI diagram generator page. For the broader category, including generators that work from code alone, see documentation generators compared.
Frequently asked questions
- What is an AI documentation generator?
- A tool that uses a language model to write technical documentation. Chat tools write from a prompt. Chiltepin is different: the agent you already use (Claude Code, Cursor, Codex, Copilot and others) reads your codebase, writes Markdown with typed YAML blocks into the repository, and a validator checks the result before a human reviews it in a pull request.
- Does the AI generator draw the diagrams?
- No. The model writes data: actors, messages, fields, endpoints. The Chiltepin renderer draws deterministic SVG and HTML from that data at build time. The same block always renders the same picture, and the model never places a pixel.
- Can chiltepin check catch a hallucinated fact?
- No. chiltepin check validates structure: schema fields, references between blocks, duplicate ids. It cannot know whether an endpoint returns 201 or 200. Truth comes from two other places: the agent reads the real code before it writes, and a person reviews the pull request. The validator removes the syntax and structure work from that review so it can focus on facts.
- How much does it cost?
- Chiltepin is MIT-licensed open source. There is no hosted service. Your own agent does the writing and the CLI does the validation and rendering on your machine or in CI.
- What does the generated documentation look like?
- Plain Markdown files with fenced YAML blocks for the structured parts. One command exports them as a static site, a standalone HTML file, a slide deck, or a PDF. The gallery at chiltepin.dev/gallery holds 40 documents an agent wrote with the skill, each with its source.