Run avo check after every edit and fix what it reports — a change isn't done until the check passes. It validates every block against its schema, checks every doc#id reference, and catches duplicate ids. Every problem comes with the file, the line, and the offending value.

avo check                       # check all docs
avo check docs/orders-api.md    # check one file or glob
avo check --json                # machine-readable output for CI

The error codes

Every message carries a stable code, and every code has a known fix:

Code	What it means	How to fix it
`E_PARSE_YAML`	The YAML didn't parse. Almost always a quoting issue.	Quote the value — see YAML pitfalls. An unquoted `,` or `:` in a `desc` is the usual cause.
`E_SCHEMA`	A field is missing, has the wrong type, or isn't in the schema. The message shows the path, e.g. `sequence: messages.2.kind`.	Compare your YAML with the field contract. Don't add undocumented fields.
`E_DANGLING_REF`	A `ref` points at an id that doesn't exist.	Fix the reference, or add the missing `id:` to the target block.
`E_DUP_ID`	The same `id:` is used in two blocks. The message names both.	Ids are repo-wide. Rename one.
`E_BAD_REF_FORMAT`	A `ref:` isn't shaped like `doc#id` or `#id`.	Match the format exactly.
`W_EMPTY_BLOCK`	A block has no body.	Add fields or remove the block.
`W_SUSPECT_BLOCK`	The fence tag looks like a typo of a real type (e.g. ```sequnce), so it rendered as plain text.	Rename it to the suggested type in the "did you mean" hint.
`W_ALIAS_TYPE`	You used an alias spelling of a block type. Both work.	Nothing — or switch to the suggested canonical name.

E_* codes are errors and fail the check. W_* codes are warnings.

Common schema errors

Symptom	Cause	Fix
`Expected string, received number` on `tech: 16`	YAML read `16` as a number.	Quote it: `tech: "16"`.
`Invalid enum value` on `tone: xyz`	The value isn't one of the allowed options.	Use a documented value (`tone: note\|tip\|warn\|danger`, etc.).
`Unrecognized key(s) in object: 'foo'`	The field isn't in the schema.	Remove it, or use a documented field.
Errors on the `meta` block	`meta` isn't the first block in the file.	Move it to the top.
`Unrecognized key(s)` after a sentence with commas	An unquoted comma split your text into several keys.	Quote the value.

Exit codes

Code	Meaning
0	Everything passed (warnings are fine)
1	At least one error
2	The command was used incorrectly

avo check exits with 1 on any error — use it as a CI gate.

Validation

The error codes

Common schema errors

Exit codes

On this page