ADR-0028: Keep documentation and release claims tied to supported behavior¶

• Status: Accepted — retrospective baseline.
• Recorded: 2026-09-29. This is the recording date, not an invented original approval date.
• Authority and implementation boundaries: see Evidence below and the register conventions.

Context¶

Examples, skills and error recovery commands are user interfaces. Stale architecture prose can turn intended behavior into a false implementation claim.

Decision¶

Maintain task-oriented docs and reference contracts with executable fictional examples, strict documentation builds and installed-package checks. Document supported syntax/settings only; distinguish stable behavior, candidate target, private prototype and unverified acceptance.

Changelog entries describe user-visible changes; internal refactor/CI/progress evidence belongs in its owning documents. ADRs explain why; specifications and reference docs retain detailed schemas/defaults. Link between them instead of copying evolving settings into many places.

Alternatives and consequences¶

A design page cannot certify a shipped feature. Autogenerated boilerplate or a changelog of every helper obscures the user's migration path. Documentation-only evidence does not enable execution or replace tests.

Evidence¶

Sources: documentation specification, changelog policy, development guide. Executable anchors: documentation tests, installed package, MkDocs configuration.

Revisit when¶

Any changed public workflow must update examples/reference/evidence together; stale historical passages should be marked, not silently reinterpreted.