llms.txt@docs · git:20261017.45e0bda · 2026-10-17 · sha256 832b2d08044cf859
llms.txt@docs git:20261017.45e0bdaB
Immutable. This exact content never changes and is served at /api/v1/blob/832b2d08044cf859.
# Ma'at > A documentation-as-code framework that keeps a repository's docs, its cross-agent instruction files, and its source code in lockstep — maintainable by AI agents, human developers, and CI alike. This file indexes the project's documentation for AI agents and tools. Each link points to a Markdown document; agents should read the ones relevant to the task before making changes. ## Architecture — how the system is built - [Check engine module](docs/architecture/modules/check.md): The validation rules behind `maat check` — the CI gate. - [Model & generators module](docs/architecture/modules/model-generate.md): Scanning the docs tree into a model and rendering derived artifacts from it. - [Terminal presentation module](docs/architecture/modules/presentation.md): TTY/color detection, Lip Gloss styling, and the Huh init wizard layered on top of the plain-text output every command already produces. - [YAML & front-matter module](docs/architecture/modules/yaml-frontmatter.md): The parsing layer — a hand-rolled YAML subset and Markdown front-matter reading. - [Architecture Overview](docs/architecture/overview.md): How Ma'at is built — the CLI pipeline, the docs model, and the generate/validate split. ## Decisions — why it is built that way (ADRs) - [0001 Record architecture decisions](docs/decisions/0001-record-architecture-decisions.md): We will use Architecture Decision Records to document significant choices. - [0002 Zero runtime dependencies](docs/decisions/0002-zero-dependencies.md): Superseded by ADR 0005. The zero-runtime-dependency goal is preserved by the Go static binary; the stdlib-only-Python mechanism is retired. - [0003 AGENTS.md as source of truth with generated adapters](docs/decisions/0003-agents-md-source-of-truth.md): One canonical instruction file (AGENTS.md); every other agent's file is generated from it and verified in CI. - [0004 Detect staleness via related_code timestamps](docs/decisions/0004-related-code-staleness.md): Superseded by ADR 0012. Staleness now uses git history; the mtime comparison remains only as the fallback for non-git directories. - [0005 Rewrite the CLI in Go, distribute a single static binary](docs/decisions/0005-go-rewrite.md): The CLI is rewritten in Go and shipped as one static binary; the Python reference is retired. Supersedes 0002. - [0006 Distribution and version pinning](docs/decisions/0006-distribution-and-versioning.md): Ma'at is adopted through a CI gate as the authority, a universal curl|sh installer plus published Action/reusable workflow, and an in-config maat_version constraint the released binary self-enforces. - [0007 Agent skills as managed artifacts](docs/decisions/0007-agent-skills-as-managed-artifacts.md): Ma'at ships agent skills as version-stamped copies under .maat/skills/, generated from templates embedded in the binary, kept fresh by sync/check, and discovered through AGENTS.md with optional vendor fan-out. - [0008 Brownfield adoption and BYO-agent retrospection](docs/decisions/0008-brownfield-adoption-byo-agent.md): Adopting Ma'at in an existing repository is non-destructive by default; deriving documentation from an established codebase is delegated to the user's own AI agent via a shipped retrospect skill, with the CLI providing only deterministic facts. - [0009 Maintenance contract as a managed block in the instruction file](docs/decisions/0009-contract-as-managed-block.md): The documentation update protocol, front-matter schema, and skills index are framework invariants, so they are rendered into the managed maat:begin/end block spliced into the instruction file — not hand-written scaffold prose — so a brownfield AGENTS.md that init preserved still gains the contract non-destructively. - [0010 Hand-copy templates live under .maat/, not the repo root](docs/decisions/0010-templates-under-dot-maat.md): init no longer scaffolds a root-level templates/ folder; the redundant ADR copy is dropped in favor of the existing docs/decisions/_template.md, and the module doc template moves to .maat/templates/_module.md, matching the leading-underscore naming already used for the ADR template. - [0011 Build-time Go dependencies are permitted; runtime dependencies are not](docs/decisions/0011-build-time-go-dependencies.md): Go module dependencies that compile statically into the binary (no external runtime process, no network call, no subprocess) are permitted going forward. The Charm libraries (Lip Gloss, Huh, and Bubble Tea transitively via Huh) are the first exercise of this policy, used for terminal styling and an interactive `init` wizard. - [0012 Detect staleness from git history](docs/decisions/0012-git-aware-staleness.md): Staleness compares commit order (and uncommitted changes) via git when available; filesystem mtimes remain only as the fallback for plain directories. - [0013 Typed contract edges in front matter and a generated manifest](docs/decisions/0013-contract-edges-and-manifest.md): Docs declare the contracts they describe (provides) and depend on (consumes); sync generates a machine-readable manifest at .maat/manifest.json; check validates edges within the repo. Groundwork for cross-repo checks. - [Architecture Decision Records](docs/decisions/README.md): Index of ADRs — the append-only log of why the system is the way it is. ## Guides — how to work on it - [Adopting Ma'at in a repository](docs/guides/deployment.md): How to add Ma'at to an existing project and wire it into CI. - [Development guide](docs/guides/development.md): How to set up, run, and contribute to Ma'at locally. - [Testing guide](docs/guides/testing.md): How to run and write Ma'at's tests, and what CI enforces. - [Troubleshooting](docs/guides/troubleshooting.md): Common maat check failures and how to resolve them. ## Reference — factual surface (config, env, API) - [CLI reference](docs/reference/cli.md): Every maat command, flag, and exit code. - [Configuration reference](docs/reference/configuration.md): Every .maat.yml key, its default, and its effect. - [Environment variables](docs/reference/environment.md): Environment variables Ma'at reads. - [Front-matter reference](docs/reference/frontmatter.md): The YAML front-matter schema every doc in docs/ carries. ## Meta — conventions and glossary - [Documentation conventions](docs/meta/conventions.md): The rules this documentation set follows so it stays consistent. - [Glossary](docs/meta/glossary.md): Definitions of Ma'at's domain terms. - [Maintaining the documentation](docs/meta/maintenance.md): How the docs stay in sync with the code — the lifecycle and tooling. ## Entry points - [Ma'at Documentation](docs/index.md): Entry point and map for the Ma'at documentation set.