Your agent writes the content. Chiltepin handles the layout. Compose prose and typed YAML blocks in a .md file. Get consistent diagrams, a document you can share, and a source diff you can review.
npx -y chiltepin@latest demo
Explore the built-in examples without creating a project. Node.js 20+ required.
Agents, architectures, and graphs
Show how an agent acts, where a system begins and ends, or how a graph connects. Chiltepin gives each question its own visual form.
A transport platform, in context. Riders, operators, maps, and live fleet data around one system boundary.
Then zoom into the network. A weighted graph makes connections and alternative routes explicit.
The full research agent document includes the agent loop, a C4 container view, and this illustrative context budget.
One document. The whole design.
An architecture review needs the boundaries, the failure paths, the data, and the release plan. Keep them together.
The checkout example brings these figures together with architecture and prose in one Markdown file:
| What happens when a payment fails? | How do orders and events stay consistent? |
|---|
| |
| An explicit failure path, alongside the successful request. | A transactional outbox, with the constraints visible. |
Open the Markdown source to reproduce the document.
Go deeper on architecture. Describe regions, availability zones, subnets, replicas, and the connections between them.
More complete examples: system design · C4 model · use cases · system context · API reference · ADR · runbook · agent system · slide deck.
Small source. Finished figures.
This is the agent loop in the opening image. The block type selects the renderer; the YAML describes the content.
```agentloop
id: research-agent-loop
title: Research. Verify. Answer.
agent:
name: Research agent
model: Tool-calling LLM
note: "Build a cited answer. Keep uncertainty visible."
env: Researcher
tools:
- { name: search_sources, desc: "Find relevant sources" }
- { name: read_source, desc: "Read the original text" }
- { name: compare_claims, desc: "Find gaps and conflicts" }
memory:
- research question
- source links + excerpts
- unresolved claims
stop: "Return a cited answer after verification, or report gaps after eight tool rounds."
```
No coordinates, drawing instructions, or generated SVG to maintain. Chiltepin owns the geometry, typography, and spacing. Change a tool or a stopping rule in the source and render again.
Every block has a strict schema. Look up its fields and a working example with chiltepin block agentloop.
Quick start
With your AI agent
Install the authoring skill:
npx skills add jdiejim/chiltepin -y
Then ask your agent:
Use Chiltepin to document this project's architecture. Read the code, show the system boundaries and request flow, include the failure path, and validate the document. Export it to HTML.
The skill guides block selection, schema lookup, composition, and validation. You review the technical facts; Chiltepin checks the structure.
In your terminal
Run these commands in your project directory:
npx -y chiltepin@latest init
npx -y chiltepin@latest check
npx -y chiltepin@latest html docs/getting-started.md -p
npx -y chiltepin@latest studio
init creates a config and two starter documents, skipping existing files. html -p opens the rendered page. studio opens the local visual editor.
To pin the CLI in your project:
npm install --save-dev chiltepin
npx chiltepin@latest check
See the getting started guide for the full workflow. chiltepin skill also prints the guide for tools with a system-prompt field.
One source, several ways to share
| You need… | Run | You get |
|---|
| A document to send | chiltepin html docs/design.md | A standalone page with inline CSS and SVG |
| A design review deck | chiltepin slides docs/design.md | A self-contained slide deck organized by headings |
| A printable handoff | chiltepin pdf docs/design.md | A PDF; Chromium downloads once on first use |
| A review before handoff | chiltepin review docs/design.md | Every check finding plus what the reader sees in each block (cut text, overlaps, fit, phone, print), one line per issue with its fix, and a contact sheet of every block |
| Images to review or paste | chiltepin shots docs/design.md | One PNG per diagram, with a note when a drawing scrolls or shrinks on the page |
| A documentation site | chiltepin build | A static site with navigation by folder and tag, search, heading anchors, and working links between documents |
| A place to edit | chiltepin studio | A local visual editor for the same Markdown files |
Dark by default. Set "colorScheme": "light" or "system" in chiltepin.config.json to change the page appearance. Print and PDF use the light palette.
The same source and layout, with a light palette for reading and print.
How Chiltepin works
Geometry is code, never prompt. An agent produces structured content; the same parser and renderers serve the CLI and Studio.
| Layer | Responsibility |
|---|
chiltepin-core | Parse Markdown, validate typed blocks, resolve references, and return diagnostics. Pure: no I/O or DOM. |
chiltepin-render | Turn the parsed document into deterministic HTML and SVG. Own all layout and visual tokens. |
chiltepin-studio | Run the shared pipeline in the browser; edit source files through the local server. |
chiltepin | Read and write files, run checks, export documents, build sites, and serve Studio. |
The block registry connects each type to its schema. Exhaustive TypeScript registries make missing renderers a compile error. Files remain the source of truth across editors and exports.
Read the architecture guide and renderer design rules for the implementation details.
Review the diff. Check the document.
Put the CLI in your project's development dependencies, then add this step after dependency installation in CI:
- name: Validate documentation
run: npx --no-install chiltepin check
chiltepin check validates the configured docs directory. It catches invalid fields, duplicate IDs, and broken references and links across documents. Errors fail the command.
chiltepin check --json # diagnostics for tooling and agents
chiltepin check --strict-prose # also fail on prose warnings
chiltepin review docs/design.md # what the reader sees, block by block (exit 1 on cut or overlapping text)
Warnings flag crowded or too-wide diagrams, unconnected nodes, duplicate edges, unlabelled decision branches, placeholder names, unedited template text, and unclear prose. Validation checks structure and references; it cannot verify your system's technical facts.
Pick the block that answers the question
107 block types across 13 families. Architecture and flows are only the start.
| Reader's question | Reach for |
|---|
| What runs where? | c4, block, cluster, archmap |
| What happens next, or when it fails? | sequence, flow, state, saga |
| What do we store or expose? | erd, endpoint, eventcontract |
| Why this decision? | options, scqa, scorecard, proscons |
| How does this ship? | rollout, roadmap, gantt, steps |
| What did the measurements show? | chart, percentiles, benchmark, slo |
| How does the agent behave? | agentloop, trace, prompt, context |
Run chiltepin block to browse the catalog, or chiltepin demo architecture to render one family.
| For… | Blocks |
|---|
| Architecture & system design | c4 block cluster archmap dfd erd usecase pkg |
| Flows, state, time | sequence flow state swimlane saga spans timing gitgraph cycle |
| Events & messaging | block (preset: event) eventcontract saga — 12 patterns in the skill |
| API reference | endpoint eventcontract packet code |
| Quality, audits, performance | audit checklist perfbudget percentiles threatmodel slo benchmark risk |
| Charts | chart (bar · line · area · scatter · donut · pie · gauge · radar · waterfall · funnel · pareto · histogram · bell · boxplot · bullet · dumbbell) heatmap sankey treemap slopegraph quadrant |
| Decks & decisions | scqa takeaways bignumber options harvey scorecard scenarios chevrons roadmap swot okr wardley |
| Planning | userstory storymap kanban timeline gantt rollout changelog statustable agenda |
| Design systems | wireframe palette typescale dodont inventory frontend felogic |
| Algorithms | |
Typed blocks across 13 families. Every field, enum, and terse form: chiltepin block <type>. Twelve old names (infra event ddd network belogic dag waterfall funnel diff terminal mece tracker) remain permanent aliases.
| Command | What it does |
|---|
chiltepin init | Scaffold chiltepin.config.json + two starter docs (--force overwrites) |
chiltepin new [name] | Scaffold a whole doc (adr, runbook, …) or one block |
chiltepin check [globs] | Validate — schemas, refs, links, ids, density, fit, graph, prose, lens lints (--json) |
chiltepin review <file> | Check one doc and look at every block as the reader sees it: fit, cut, overlap, tiny, print; writes a contact sheet and review.json (-o, --json; exit 1 on an error) |
chiltepin block [type] | The reference: every type on one line, or one type's contract (--json) |
chiltepin demo [family] [-s] | Render the built-in showcase — every block, or one family (-s slides) |
chiltepin html / slides / pdf <in> | Render one doc (-p opens, -o writes) |
chiltepin shots <in> | One PNG per diagram, with a fit note (-o, --json) |
chiltepin <file.md> | Render and open one doc |
chiltepin build | Static site from all docs: shared CSS, search, images copied (--out) |
chiltepin studio | The local editor (--port, --no-open) |
chiltepin audit [path] | Audit a codebase and recommend which docs to write, with evidence |
chiltepin sync openapi|csv|sql|dbml|prisma <file> | Generate blocks or docs from an OpenAPI spec, a CSV, or a schema |
chiltepin skill | Print the skill as one document |
Exit codes: 0 clean · 1 errors · 2 usage error. CHILTEPIN_PLAIN=1 forces plain output.
Contribute
pnpm install
pnpm verify
Read CONTRIBUTING.md to add a block, improve a renderer, or contribute an example. Report a bug with a small Markdown file that reproduces it, or request a block.
The figures in this README come from checked-in source documents. Run pnpm build followed by pnpm screenshots to regenerate them with Playwright and Chromium. The CLI build also syncs the npm README and converts its image and document links to absolute URLs.
Generation evaluations track block selection, validation, and rendering across 40 requests. The results are maintainer-reported development runs; see the method and its reproducibility limits there.
License
MIT
