title	description	type	status	audience	tags	related	ai_context	retrieval_hooks	not_for	constitutional_basis	provenance	aio_version
AIo — A documentation framework for AI-first consumers	Landing page for the AIo specification: what AIo is, what v0.2 adds, how to adopt it in under five minutes.	explanation	decided	both	aio readme landing overview	SPEC.md constitution.md RATIONALE.md CHANGELOG.md AGENTS.md TRACE-SCHEMA.md	Public landing document for the AIo project. An explanation-type document that frames what AIo is, what changed in v0.2, what lives in the repo, and how a project adopts AIo in under five minutes. Read SPEC.md for normative rules; read constitution.md for project governance; read RATIONALE.md for design reasoning.	What is AIo? What changed in AIo v0.2? How do I adopt AIo in my project? How does AIo compare to Diataxis? Where is the AIo specification?	The normative specification — see SPEC.md The project constitution governing AIo itself — see constitution.md Why AIo exists — see RATIONALE.md	article-1 article-6	editorial_responsibility responsible_party contact jurisdiction wandering-monster info@wanderingmonster.dev EU	0.2.0

▶ animated version

AIo

A documentation framework for projects where AI agents are first-class consumers.

AIo (from Latin aio, "I say / I assert / I affirm") is an extension of Diataxis for documentation that will be read, queried, and acted on by AI agents as well as humans. It adds an explicit type declaration, an executable runbook type, a constitution type for project-wide rules, query hints, explicit negative scope, structured pause conditions, trust-class step tags, a security-pattern declaration, a provenance attestation block, and a versioned schema — without throwing out the parts of Diataxis that already work. It is designed to complement the existing agent-documentation ecosystem (AGENTS.md, SKILL.md / Agent Skills, llms.txt, MCP) rather than replace any of it. The "I/O" reading is a happy accident.

New in v0.2 (additive, non-breaking)

Every v0.1 document continues to parse and validate unchanged. The five additions:

• constitution document type — a project's immutable, RFC 2119 rules, versioned independently of AIo. One per project root. See SPEC.md → The constitution type and this repo's own constitution.md.
• Trust-class step tags — [A] private data, [B] untrusted input, [C] external communication, annotated per runbook step. A trifecta step ([A][B][C]) is rejected unless the runbook declares a compensating pattern:. Implements the Lethal Trifecta / Rule of Two at step granularity. See SPEC.md → Trust-class step tags.
• pattern: on runbooks — declares the security design pattern (Beurer-Kellner et al., arXiv:2506.08837) under which the runbook is safe. Executing harnesses must implement the declared pattern or refuse execution. See SPEC.md → pattern:.
• provenance: attestation block — structured SLSA / in-toto / sigstore hooks plus an editorial_responsibility sub-block operationalising EU AI Act Article 50(4). See SPEC.md → provenance:.
• Trace schema companion spec — TRACE-SCHEMA.md. A minimal JSON shape harnesses use to emit agent-session traces. Not a document type; emitted at runtime.

Full list in CHANGELOG.md. Project governance lives in constitution.md.

Why this exists

Modern agents read prose perfectly well. What they cannot do is enforce writer discipline, filter by type without a model call, reason about execution safety from tone alone, or disclose AI authorship automatically. AIo treats frontmatter as a machine-checkable contract: the writer commits to a single purpose, declares provenance, spells out pause points, tags trust-class-sensitive steps, and names a security pattern — and downstream tooling gets a stable surface to act on.

The full reasoning lives in RATIONALE.md; the governing rules in constitution.md.

What's in this repo

File	What it is
SPEC.md	The canonical specification — types, frontmatter schema, conformance rules, interop mappings. Read this for the rules.
constitution.md	The AIo project's own constitution. Six articles, RFC 2119. Cited by SPEC and AGENTS via constitutional_basis.
RATIONALE.md	Why AIo exists and the reasoning behind each adaptation. Read this for the why.
TRACE-SCHEMA.md	Companion spec for the v0.2 trace shape. Not a document type — emitted by harnesses at runtime.
PROVENANCE-DISCLOSURE.md	Informative companion — a minimum shape for machine-readable human/AI disclosure in profile bios, PR descriptions, and similar non-document surfaces. Proposed.
AGENTS.md	Conventions for AI tools editing this repo itself.
llms.txt	Machine-discoverable manifest of canonical files.
CHANGELOG.md	Version history.
LICENSE	CC BY-SA 4.0 license text and attribution.
tools/aio-lint.py	Reference linter — optional, single-file Python, validates frontmatter against the conformance rules.
tools/tests/	Linter test suite + per-rule fixture documents.
examples/tutorial-example.md	A worked tutorial — guided walk from blank file to validated AIo document.
examples/howto-example.md	A worked how-to guide demonstrating the howto type.
examples/reference-example.md	A worked reference — lookup of every AIo linter code with example violations and fixes.
examples/explanation-example.md	A worked explanation — why AIo treats frontmatter as a contract rather than a style guide.
examples/runbook-example.md	A worked runbook demonstrating the runbook type with pause conditions, trust-class tags, and pattern:.
examples/constitution-example.md	A worked project constitution adopters can copy and adapt.
examples/document-template.md	Starter template for any new AIo-conforming document.
examples/interop-agents-md.md	Drop-in AGENTS.md for projects adopting AIo.
examples/skill-example/	AIo packaged as a portable Agent Skill bundle.

Five-minute quickstart

1. Read SPEC.md. It is short. The rules fit in one document.
2. Drop an AGENTS.md into your project. Copy examples/interop-agents-md.md and adjust paths. This is what Claude Code, Cursor, Copilot, Codex and others will read on entry.
3. Add AIo frontmatter to one document. Pick the type that fits, declare status and audience, set aio_version: "0.2.0", and add a provenance.editorial_responsibility sub-block naming who stands behind the content.
4. Try writing a runbook. Declare a pattern: the document is safe under, tag steps by trust class ([A], [B], [C]) where applicable, and promote any judgment-dependent step into a structured pause_conditions: entry. If you can't write it cleanly, that is the system telling you the procedure isn't ready to be delegated yet.
5. Optional: run the linter. python tools/aio-lint.py path/to/docs/ validates frontmatter, conformance rules, trust-class tags, and pattern declarations.

Onboarding an AI coding assistant to AIo

Three tiers, depending on how deeply you want AIo integrated:

• Lightest — drop examples/interop-agents-md.md into your repo as AGENTS.md. Every major coding agent reads it automatically.
• Self-contained — also copy SPEC.md and examples/document-template.md into your project. Works offline and pins to a spec version.
• Best for Claude Code — install examples/skill-example/ as an Agent Skill. The skill loads on demand and ships with the linter as a script.

Worked example

A short runbook snippet showing the v0.2 additions in place:

---
title: "Runbook: Export customer records matching a user-supplied filter"
description: "Filter the customer table and export matching records to S3."
type: runbook
status: decided
audience: ai
tags: [export, s3, customer-data]
related:
  - ../reference/data-schemas.md
read_only: false
destructive: false
idempotent: true
pattern: plan-then-execute
constitutional_basis:
  - article-1
provenance:
  editorial_responsibility:
    responsible_party: "Data Platform Team"
    contact: "platform@example.com"
    jurisdiction: EU
aio_version: "0.2.0"
---

## Steps

1. `[A]` Read customer record from the database.
2. `[B]` Parse the user-supplied filter expression.
3. Validate the filter against an allow-list of columns.
4. `[A][C]` Export filtered records to S3.

Step 4 carries two trust classes but not all three — it reads private data ([A]) and communicates externally ([C]) but does not consume untrusted input. Under pattern: plan-then-execute the runbook is valid; make it a trifecta ([A][B][C]) and the linter emits S1 unless the pattern is dual-llm or camel. See examples/runbook-example.md for a complete, executable worked example.

The six document types

Type	Purpose	Reader posture
tutorial	Learning by guided experience	"I am new and want to learn by doing"
howto	Completing a known task	"I have a specific job to finish"
reference	Looking up authoritative facts	"I need a fact, fast"
explanation	Understanding the why	"I want to grasp the reasoning"
runbook	Executing a deterministic procedure	"I am acting under instruction, often as an AI agent"
constitution	Declaring the rules that bind every other document	"I need to know which rules I cannot violate regardless of task"

Plus the informal inbox type for pre-classification raw material (exempt from type discipline; max 90 days before promotion or archival).

The first four are inherited from Diataxis. runbook was introduced in v0.1. constitution is new in v0.2. See SPEC.md → Document types.

Relationship to the rest of the ecosystem

Convention	How AIo relates
Diataxis	Parent framework. Every well-formed AIo document is a valid Diataxis document.
AGENTS.md	AIo projects ship an AGENTS.md that points agents at the AIo spec, the project constitution, and doc directories. Template in examples/interop-agents-md.md.
SKILL.md / Agent Skills	AIo runbooks map onto skills. A runbook can be re-wrapped as a SKILL.md with minor field renaming. Example in examples/skill-example/.
llms.txt	AIo projects maintain an llms.txt manifest. Each entry's description is taken from the corresponding AIo document's description field.
MCP tool annotations	Runbook execution hints (read_only, destructive, idempotent, non_deterministic) use the same semantics as MCP's tool annotations and project directly onto them.
SLSA / in-toto / sigstore	v0.2 adds a provenance.attestations block that carries SLSA / in-toto predicates and sigstore signatures when a project wants them. AIo provides hooks; the supply-chain posture remains the project's decision.

See SPEC.md → Interop for the explicit mappings.

Status

v0.2.0. Additive, non-breaking. Every v0.1.0 document continues to parse and validate under the v0.2 linter, per Article 3 of the project constitution. v0.1.0 was the initial public release.

See CHANGELOG.md for the full list of v0.2 additions and constitution.md for project governance.

Brand assets

  

Asset	Purpose
assets/AIo.jpg	Brand mark — a simple scroll on parchment. Used as the README banner; suitable for social-preview / OG images.
assets/AIo.mp4	Short animated version of the brand mark.
assets/AIo-Hero-2.png	Hero image — the scroll set against the four Diataxis quadrants (tutorials, how-to, reference, explanation).
assets/AIo-Hero-2.mp4	Animated version of the hero image.
assets/aio-scroll-icon.svg	Scalable scroll icon — usable as a favicon or inline mark.

Using the scroll as a favicon. Git forges (Forgejo, Gitea, GitHub, GitLab) render their own favicon on the repository page — a project can't override it there. The SVG is shipped here so downstream docs sites, static-site generators, or forks of AIo can wire it up directly:

<link rel="icon" type="image/svg+xml" href="/assets/aio-scroll-icon.svg">

For the link-preview card that appears when the repository URL is shared on social media or chat, upload assets/AIo.jpg as the repository's social-preview / OpenGraph image (on Forgejo: Settings → Repository; on GitHub: Settings → General → Social preview).

All brand assets in this repository are covered by the same CC BY-SA 4.0 license as the rest of AIo.

Contributing

This is a documentation standard, not a software project. Contributions take the form of:

• Issues — proposals for the next version, questions about ambiguous parts of the spec, suggestions for additional examples.
• Pull requests — clarifications, typo fixes, additional examples, or proposals for the next minor/major version.

When opening an issue or PR, please specify which AIo version you are referring to.

License and provenance

AIo is licensed under CC BY-SA 4.0 — Creative Commons Attribution-ShareAlike 4.0 International. This is the same license used by Diátaxis, the framework AIo extends. Matching the license keeps AIo and Diátaxis in the same family and means that everything built on either can flow freely between them.

AIo is maintained by WanderingMonster. The framework's design is small and concrete enough that no individual claim of authorship is made; the goal is for it to be useful, adopted, and improved by others.

AIo extends Diátaxis by Daniele Procida, also licensed under CC BY-SA 4.0. The four core document types and the central insight that mixing types within a single document is the failure mode are inherited from Diátaxis. The executable runbook type, the constitution type, the frontmatter schema, the query hints, the explicit negative scope, the structured pause conditions, the trust-class step tags, the security-pattern declaration, the provenance attestation block, the trace schema companion spec, the execution hints, the conformance rules, the interop mappings, and the spec versioning are AIo's additions.

See also

• SPEC.md — the normative specification.
• constitution.md — the project constitution this README defers to.
• RATIONALE.md — the design reasoning behind each adaptation.
• CHANGELOG.md — version history, including the full v0.2 delta.
• AGENTS.md — conventions for AI tools editing this repo.
• TRACE-SCHEMA.md — companion spec for runtime trace emission.

Not this document

• The normative specification — see SPEC.md. This README frames what AIo is; SPEC is the contract.
• The project constitution — see constitution.md. The constitution binds every document in this repo, including this one.
• Why AIo exists — see RATIONALE.md. This README summarises; RATIONALE reasons.