Run chiltepin 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, catches duplicate ids, and lints density and prose. Every problem comes with the file, the line, and the offending value. The parser also repairs the one YAML trap agents hit most — an unquoted comma inside an inline map — so label: Hold as BACKORDERED, email ETA means what the author meant.

chiltepin check                       # check all docs
chiltepin check docs/orders-api.md    # check one file or glob
chiltepin 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`.	Run `chiltepin block <type>` for the exact fields and enums. 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.
`W_LENS_REPEAT`	A third `callout`, or a fourth block of the same structural type, in one document.	Vary the lens — the message names the block that usually fits instead.
`W_PROSE_*`	A long sentence, filler, or a paragraph that restates the block below it.	Shorten. `--strict-prose` turns these into errors.

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

chiltepin 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