All examples

4 groups, 18 examples — each one small, self-contained, and regression-checked against the real CLI and library, so what you read is what the tool actually does. Read a group in order, or jump straight to the one you need.

1. Validate from the terminal

5 examples · reference: CLI reference

1. Check a folder of docs — Point validate at a folder and get a verdict: a run summary, findings if any, and a CI-ready exit code.
2. Read a finding, fix the doc — A document that breaks its contract produces a finding pinned to a source line — open the file at that line and fix it.
3. Findings as JSON or SARIF — The same run renders for machines: --format json emits the raw findings array, --format sarif feeds code-scanning uploads.
4. Bind a contract directly, scope the run — No config file needed: --contract binds one contract to a folder, and --include / --exclude narrow any run without touching config.
5. Scaffold the config with init — init reads the markdown you already have, infers the tightest config that accepts it, and doubles as a CI drift guard with --check.

2. Author contracts in YAML

5 examples · reference: Declarative YAML reference

1. Frontmatter and required sections — A complete contract, no code: typed frontmatter fields plus the sections every decision record must carry.
2. Typed tables and checklists — Content leaves put shape requirements inside a section: a table with named, schema-checked columns and a checklist with a minimum length.
3. House rules as text constraints — requires / forbids assert that phrases appear (or never appear) — per section or across the whole document — without writing a rule function.
4. Headings that repeat: changelogs — A counted slot lets one heading legitimately recur as peers — with minContains / maxContains occurrence bounds — instead of tripping the duplicate-section rule.
5. Route a whole tree with one config — A kind: config document maps globs to contracts — by name, by path, or inline — so validating an entire docs tree is configuration.

3. Read markdown as typed data

4 examples · reference: Typed model reference

1. One contract, two doors — The contract that validates a document also types it: validate() returns findings as data, read() returns the typed model or throws.
2. Tables as typed rows — A table leaf with cell schemas reads back as an iterable of typed rows — no cell parsing in the consumer.
3. Anchors make blocks addressable — A line-terminal ^block-id names a block; a contract can require it, and a consumer can resolve it to the block’s typed view.
4. Navigate without a contract — parse() alone projects a document into a positioned section tree — navigation helpers and verbatim table cells, no contract required.

4. Automate and embed

4 examples · reference: Library API reference

1. Embed the corpus runner — Everything the CLI does is one library call: runCorpus routes a tree of files to contracts and returns findings, stats, and an exit code.
2. A CI gate in GitHub Actions — Two workflow steps make the contract a merge gate: validate with SARIF output, then upload the findings to code scanning.
3. Custom rules for cross-cutting policy — When neither plane covers a policy, a named docRule sees the whole typed document — so a frontmatter field can gate a body section.
4. This repo validates its own planning docs — The dogfood proof: this repository’s config maps its planning corpus to six contracts, and CI validates the corpus on every push.