fix(docs): stale literals + extend rivet docs check with EmbeddedVersionLiterals / EmbeddedFlagReferences / EmbeddedTodoMarkers (#247)

[avrabe]

Closes #247.

Summary

Fixes four stale literals shipped in 0.7.0 docs and extends rivet docs check with three new invariants that scan the embedded rivet docs <topic> bodies — the strings printed by the binary, not files on disk — so this class of drift surfaces at CI time instead of via user reports.

Per-fix walkthrough

Part A — stale literal fixes

• B1 rivet docs quickstart step 1 — replaced the rivet 0.5.0 expectation with version-agnostic prose (rivet + any version). rivet-cli/src/quickstart.md.
• B2 rivet docs mcp serverInfo example — changed the hard-coded \"version\":\"0.5.0\" to \"<rmcp-version>\" and added a note explaining the field reflects the underlying rmcp crate, not rivet's release line. rivet-cli/src/docs.rs.
• B3 schemas/eu-ai-act.yaml (drives rivet docs schema/eu-ai-act) — flipped the single-schema usage line from rivet init --schema eu-ai-act to rivet init --preset eu-ai-act. Multi-schema bridge examples (--schema eu-ai-act,stpa) are valid uses of the existing flag and stay.
• B4 schemas/dev.yaml (drives rivet docs schema/dev) — dropped the docs/agent-pipelines.md (TODO) cross-reference to a non-existent topic.
• Bonus rivet docs impact example used a stale tag literal v0.5.0; replaced with the placeholder vX.Y.Z.
• Bonus Caught a stale rivet export --gherkin flag in schemas/dev.yaml (flag is --format gherkin, not --gherkin); also fixed the matching comment in rivet-cli/src/main.rs.

Part B — three new invariants in rivet-core/src/doc_check.rs

• EmbeddedVersionLiterals — every vX.Y.Z / X.Y.Z token in a topic body must equal the workspace version OR be in rivet.yaml docs-check.allowed-version-literals. Allowlist entries without a v prefix also match the v-prefixed form (single source of truth).
• EmbeddedFlagReferences — every rivet <subcmd> --<flag> token in a topic body must reference a flag declared on that subcommand in the live clap tree. Walks parent-up so root-level globals (--project, --verbose) and intermediate flags resolve. When the subcommand itself is unknown we defer to SubcommandReferences, not double-report.
• EmbeddedTodoMarkers — TODO / FIXME / XXX in topic bodies are author markers that must not ship in a release binary. Inline meta-references like `TODO` are skipped so docs-about-the-invariant stay legal.

Wiring

• docs::topic_bodies() exposes (slug, body) pairs for the engine.
• build_subcommand_flag_map() walks Cli::command() and collects long flags per slash-separated path, seeded with root-level globals and the clap built-ins (--help, --version).
• cmd_docs_check populates embedded_topics, subcommand_flags, and allowed_version_literals on the DocCheckContext.
• DocsCheckConfig::allowed_version_literals (the docs-check: block in rivet.yaml).

New topic

Added a docs-check reference topic that lists both the markdown invariants and the new embedded-doc invariants, plus the allowlist syntax.

Tests

• 10 new unit tests in doc_check::tests exercise each new invariant plus the no-topics-disabled smoke (existing engine consumers that do not populate the field still pass).
• All existing tests still pass (cargo test --workspace).

CI

The CI step cargo run --release -p rivet-cli -- docs check picks the new invariants up automatically via default_invariants() — no workflow change needed.

Test plan

• cargo build clean
• cargo clippy --workspace --all-targets -- -D warnings clean
• cargo fmt --all -- --check clean
• cargo test --workspace clean (912 unit tests + integration tests)
• cargo test -p rivet-core --lib doc_check — 36 passing (10 new)
• rivet docs check — clean against rivet repo (47 files scanned, 0 violations)
• Smoke: deliberately introduced a stale literal in a topic body — each new invariant fires; reverted
• rivet validate — no new errors (6 errors, 140 warnings — pre-existing baseline)

[github-actions]

📐 Rivet artifact delta

No artifact changes in this PR. Code-only changes (renderer, CLI wiring, tests) don't touch the artifact graph.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: aab831d	Previous: b7a17be	Ratio
store_insert/10000	13830587 ns/iter (± 2010754)	10641021 ns/iter (± 264093)	1.30
link_graph_build/10000	28082563 ns/iter (± 1315562)	22660622 ns/iter (± 884929)	1.24
validate/10000	18217281 ns/iter (± 2968178)	12248917 ns/iter (± 180828)	1.49

This comment was automatically generated by workflow using github-action-benchmark.

[codecov]

Codecov Report

❌ Patch coverage is 99.37107% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
rivet-core/src/doc_check.rs	99.37%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!