AI Docs Standard

Ship documentation your users' AI agents can actually act on.

Software now has two readers: the person deciding whether to use it, and the agent that will install, configure, and call it on that person's behalf. The AI Docs Standard is a simple, open convention for the second reader — a single machine-first file, documentation.ai.md, that an LLM or coding agent can load and use to run your product without guessing.

• 📄 The spec: SPEC.md
• 🔥 The why: MANIFESTO.md
• 🧩 A skeleton to copy: examples/TEMPLATE.md
• 🌐 Canonical page: iwasoft.com/standards/ai-docs
• 🤖 Live index (dogfood): iwasoft.com/llms.txt
• 🧭 Sibling standard: AI Manifest Standard — presents a site to AI (this presents a product)
• 📜 License: CC BY 4.0 — free to adopt with attribution

---

The idea in one paragraph

A human document earns trust by explaining why — the design, the tradeoffs, the story. An agent doesn't need to be persuaded; it needs the port number, the exact environment variable, the real response shape. Blend the two and you serve neither. So write two documents, for two readers, honestly. A fact an agent has to infer is a fact you failed to state.

The file

ai is a reader, not a spoken language — it never goes in your site's language switcher.

Adopt it in three steps

1. Add documentation.ai.md next to your product's docs, following the required sections: identity → install → configuration → interface quickstart → admin surface → architecture facts → links.
2. Keep it correct per release — every version ships its own, verified against the real product.
3. Make it discoverable — link it from your site's llms.txt, and add the badge below.

[![AI Docs Standard](https://img.shields.io/badge/docs-AI%20Docs%20Standard-5850ec)](https://github.com/iwasoftcom/ai-docs-standard)

What goes in it

The document must be self-sufficient: an agent that has read only this file can install, call, and configure the product — no human docs, no source repo, no guessing. Dense over prose; tables over paragraphs; every command copy-pasteable and verified; absolute honesty about status. Full requirements in SPEC.md.

Relationship to llms.txt

Complementary, not competing. llms.txt is a site-root index of a website's content; documentation.ai.md is a per-product, per-release operational manual (closer to llms-full.txt). A site's llms.txt can link to each product's documentation.ai.md. Adopt either independently.

Reference implementations

Every iwasoft product ships a documentation.ai.md with each release — real, published examples of the standard in practice.

See a real documentation.ai.md:

• Kivi — an event-ledger database
• Vesta — S3-compatible object storage

More:

• Canonical write-up: iwasoft.com/standards/ai-docs
• Live index of every product's AI doc: iwasoft.com/llms.txt
• Or browse the products on iwasoft.com — each product's Documentation panel includes an AI / LLM entry.

Contributing

The standard evolves in the open — see CONTRIBUTING.md. Open an issue to discuss a change; send a PR to propose one.

About

The AI Docs Standard is authored and stewarded by iwasoft and released under CC BY 4.0: adopt it, adapt it, build on it — just keep the attribution. Canonical write-up: iwasoft.com/standards/ai-docs.