Two remaining pieces from the original report, both explicitly signed
off on:
1. Wire cargo run -p xtask -- check-docs into dev-release.yml as a
fail-fast step ahead of the release build/test, so drift between
api-schema.toml and the real API surface now fails CI instead of
relying on local discipline.
2. Extend api-schema.toml and check-docs to cover the bread CLI's
command surface (bread-cli/src/main.rs's Commands/ModulesCommand/
HooksCommand enums) against README.md's "CLI reference" section,
not just Lua bindings/IPC methods against Documentation.md. This
was the specific blind spot that let modules audit, hooks
install-shell/install-git, and events --tree drift out of README
in the first place -- check-docs would not have caught that fix
without this extension, since its prior scope never touched the
CLI-vs-README relationship at all.
Extraction reuses the same deliberate-textual-scanning approach as
the existing Lua/IPC extractors: depth-tracked enum variant scanning,
clap's PascalCase->kebab-case rename convention, and a hardcoded
(TABLE_VARS-style) map of which top-level Commands variants delegate
to a nested subcommand enum (Modules->ModulesCommand,
Hooks->HooksCommand), producing dotted names like modules.audit.
CLI commands are versioned against the package version (Cargo.toml),
not API_VERSION, since the CLI was never part of that versioned
contract -- documented in api-schema.toml's header.
Verified check-docs actually catches CLI/README drift, not just
passes: temporarily deleted the "bread modules audit" line from
README.md, confirmed check-docs failed with the exact right message,
restored it. 4 new unit tests cover the extraction and cross-check
logic (11 total in xtask, up from 7).
Documentation.md's Lua API and IPC protocol sections are hand-written
prose and have drifted from the actual bread.* binding / IPC method
surface before. This adds a checked-in registry (api-schema.toml) of
every current Lua binding and IPC method, plus a new xtask crate
(`cargo run -p xtask -- check-docs`) that cross-checks it against
breadd/src/lua/mod.rs, breadd/src/ipc/mod.rs, and Documentation.md
itself, failing loudly on any mismatch. It's a drift detector, not a
doc generator — Documentation.md's prose is untouched except for one
genuine gap the bootstrap surfaced: bread.hyprland.eval had no mention
anywhere in the docs, now given a one-line example alongside its
siblings.
CONTRIBUTING.md documents the resulting contributor workflow.
