docs(book): a Conformity Checks chapter teaches the reference language step by step

[bmscomp]

A new Guide chapter, Conformity Checks (docs/book/conformity.md), in Part V after the Deployment Guide. It follows the book's running example: the architecture the payments workload needs from krafter.

How it reads, easiest first

1. Your First Reference. minimal.yaml (3 rules), linted and checked.
2. Why Conformity. Drift between the design, the config and the running cluster. A table places conformity next to cluster check, detect, security audit and scenario gates. A Mermaid figure shows how a check runs, then statuses, the overall result and exit codes.
3. Writing Constraints. Bare vs map form, value kinds and quoted versions. Sizing the brokers, with a real FAIL and the fix.
4. Placement. zones, skew, perNode, antiAffinity and dedicated, with a real FAIL. Lint's cross-rule checks (even quorum, zones that can't be reached).
5. Kafka Settings and Monitoring. rackAwareness, authorization, listeners and config, kafka.source cr vs brokers, and per-topic rules.
6. When the Cluster Falls Short. Waivers vs severity: warn, the waiver lifecycle, and the complete payments-krafter.yaml.
7. Running It in a Pipeline. fmt --check, lint, check --output-junit, and -o json with jq.
8. The Language at a Glance and Limits.

Captured, not invented. Every check result was captured on panda. A throwaway harness, not committed, ran ConformityCheck against krafter the way ConformityLiveTest does, and the real CLI rendered each report through a local stub. Lint and fmt output come from the real CLI. The lab has no Kates API deployed, so a live kates conformity check wasn't possible. The two real gaps panda showed became the chapter's teaching cases: broker anti-affinity is preferred, and Kafka Exporter is off on Kind.

The final reference is a tested example. cli/examples/conformity/payments-krafter.yaml is picked up by the schema, lint, fmt and strict-reader example tests, so it can't drift.

Wiring

• _quarto.yml order, the Part V page bullets and counts, and the Deployment Guide's handoff.
• The book README.
• A CONCEPTS registry row, and the payments-krafter.yaml name in the Names table.
• Glossary entries for Conformity Check, KafkaReference and Waiver, plus the conformity exit codes under Exit Code.

Reference fixes found while researching

• The CLI Reference's family table had no Conformity row.
• The Conformity section said "two examples" (there are four now).
• The API's read scope row left out POST /api/conformity/check.

Checked locally

• scripts/check-book-style.sh: style and ratchet OK, and the new page is at 0 on every count.
• book_metrics.py: 0 of 152 sentences are over 40 words.
• prepare-book-render.sh + quarto render --to html in a scratch copy: 40 chapters. check-book-fragments.py: all 7,736 fragment links land.
• check-mermaid.sh: 157 diagrams parse.
• Go example tests (TestConformityExamplesMatchTheirSchema, TestExamplesAreFormatted, TestExamplesCompileClean, TestFormatIsIdempotentAndKeepsTheMeaning) and Java KafkaReferenceExamplesTest (5/5) pass.

Not checked: lychee (not installed locally; CI runs it), the PDF render, and the page's look in a browser.

Commands documented are in cli/cmd/conformity.go and cli/cmd/conformity_lint.go. The endpoint is kates/src/main/java/com/bmscomp/kates/api/ConformityResource.java.