# Avodado — authoring guide

This project uses Avodado: documentation-as-code where a doc is Markdown with typed,
fenced YAML blocks, and the files on disk are the single source of truth.

To author or edit anything under docs/**/*.md, follow the Avodado authoring skill —
installed as the `avodado-docs` skill and at `.avodado/skill/SKILL.md`. It defines
the block grammar, every block's fields, and the `doc#id` reference scheme.

- Prose is plain Markdown; structure goes in typed blocks (e.g. sequence, erd,
  table, callout, c4, flow, timeline, userstory). Never paste raw HTML or inline SVG.
- Use only the documented block types and their documented fields — the schemas are
  strict, so an unknown block or field fails validation. Bodies are YAML.
- Give a block an `id:` when it needs to be referenced; reference it as `doc#id`.
- Edit the specific block surgically — don't regenerate whole files.
- Run `avo check` and fix all diagnostics before finishing. A change isn't done
  until it passes.
