[AAASM-4310] 📝 (docs): Add mdBook shared metadata generator to prevent docs drift

[Chisanan232]

Description

Adds a shared-metadata generator for the mdBook docs site so high-drift
values (workspace runtime version, wire protocol version, canonical URLs,
one-line installer command) are sourced from a single source of truth
instead of being duplicated across Markdown pages.

Jira: https://lightning-dust-mite.atlassian.net/browse/AAASM-4310

What changed

• New metadata/docs.yaml — the single source of truth for docs values
  that are not already encoded in Cargo.toml (protocol version, canonical
  URLs, installer endpoints).
• New scripts/generate_docs_metadata.py — reads Cargo.toml
[workspace.package].version + metadata/docs.yaml and writes checked-in
  Markdown snippets under docs/src/generated/. Uses only the Python 3.11+
  standard library (tomllib + a tiny scalar-only YAML parser) so docs CI
  does not need PyYAML installed.
• New docs/src/generated/*.md — the generator's initial output. Each file
  starts with a <!-- Generated by ... DO NOT EDIT. --> banner; pages
  consume the value with mdBook's line-anchored include syntax
  (\{{#include generated/version-tag.md:2}}) so the banner is elided from
  the rendered output.
• docs/src/releases.md and docs/src/versioning.md — the "latest tag" and
  "current protocol version" callouts now reference generated snippets
  instead of hard-coded literals. releases.md previously named
  v0.0.1-beta.4 while Cargo.toml was already at 0.0.1-rc.3.
• .github/workflows/docs.yml — adds a drift-check job step that runs the
  generator and fails on any diff in docs/src/generated/. Path filters
  extended to trigger on metadata/**, scripts/generate_docs_metadata.py,
  and Cargo.toml so a bare version bump still runs the check.
• New docs/src/development/shared-docs-metadata.md — maintainer note
  documenting how to add or update a shared value, linked from SUMMARY.md.

Why

Duplicated version / URL literals in docs regularly drift on release. The
existing scripts/check-docs-versions.sh catches drift in a fixed set of
install-example lines when driven from release-tag-cut, but does nothing
for the many other places these values appear. This generator plus the docs
CI drift check makes forgotten updates fail mechanically instead of shipping.

Option A vs Option B

The ticket allows either an mdBook preprocessor (Option A) or a
generated-snippet pipeline (Option B). Option B was chosen because:

1. The docs/book.toml preprocessor chain already contains mdbook-mermaid
   and a custom last-changed preprocessor. Adding a third preprocessor
   would grow that chain's failure surface without giving reviewers a
   diffable artifact.
2. Checked-in snippets make drift visible in code review — reviewers see
   exactly which values changed on a version bump.
3. Docs CI does not need Python to build the site (only to verify
   drift), which keeps mdbook build docs fast and self-contained.
4. The existing docs/theme/last-changed.py preprocessor is single-purpose;
   a "vars" preprocessor would be a second thing to keep in sync with
   mdBook's preprocessor JSON protocol.

Deliberately out of scope

• Historical release notes / changelog values (must preserve historical
  accuracy).
• The install-example pins in installation.md and README.md — those
  are already guarded by scripts/check-docs-versions.sh at release-tag
  cut, and replacing them with includes would break that check.
• The Compatibility Matrix rows in compatibility.md — each row is a
  historical record for one release.

Type of Change

• 📝 Documentation update
• 🔧 Configuration / CI change

Breaking Changes

• No

Related Issues

• Related Jira ticket: AAASM-4310 (Epic AAASM-4309)

Testing

Ran the ticket's validation trio locally:

python3 scripts/generate_docs_metadata.py   # idempotent — no changes
git diff --exit-code                        # clean
mdbook build docs                           # succeeds, no include errors

Also simulated drift by editing metadata/docs.yaml, re-ran the generator,
and confirmed the CI drift check would fail with an actionable message
before mdbook build runs. Reverted the drift test.

• Unit tests added / updated
• Integration tests added / updated
• Manual testing performed (validation trio above)
• No tests required (docs tooling; drift check itself is the guarantee)

Checklist

• Code follows project style guidelines
• Self-review of the diff completed
• Documentation updated (maintainer note added under Development)
• All CI checks passing (pending — this is the first push)
• Commits are small and follow the Gitmoji convention

Closes AAASM-4310

[Chisanan232]

Claude Code review — AAASM-4310

CI status: 9/9 required checks green, 1 skipped (branch-conditional). BLOCKED is branch protection, not a CI failure.

AC coverage vs Jira AAASM-4310:

• Stack-appropriate mdBook metadata adapter — Option B (generated snippets), justified in PR body
• Rust workspace version sourced from Cargo.toml [workspace.package].version via stdlib tomllib (Python 3.11+)
• Repeated values available as generated snippets under docs/src/generated/: version.md, version-tag.md, protocol-version.md, repo-url.md, docs-url.md, install.md
• Historical release/changelog content preserved literal (confirmed by scope of docs/src/releases.md and versioning.md edits)
• mdbook build docs succeeds locally and in CI
• CI fails on stale generated output — .github/workflows/docs.yml runs python3 scripts/generate_docs_metadata.py && git diff --exit-code
• Maintainer note added at docs/src/development/shared-docs-metadata.md, linked from SUMMARY.md

Side-effect assessment: zero runtime code touched — Cargo.toml runtime not modified, no Rust source changed. Only docs/src/**, scripts/, metadata/, and one CI workflow. Include-directive uses line-anchored form (:2) so DO-NOT-EDIT banners do not leak into rendered docs. Install-example pins in installation.md/README.md intentionally NOT touched because they are already grep-checked by scripts/check-docs-versions.sh at release-tag cut — replacing them would break that check. Cross-referenced correctly.

FE validation: N/A — mdBook is a static docs generator with no interactive frontend.

Verdict: Ready to approve and merge. 6 clean atomic gitmoji commits, all AC met.

[Chisanan232]

Claude Code re-review — AAASM-4310 (post canonical-URL fix)

CI status: all 10 required checks green (9 pass, 1 skipped — branch-conditional). mdBook build, drift check, verify-documented-commands, CodeQL (go/js/py/rust), SonarCloud all pass.

New commits since last review (2):

• ad8c21db 🐛 (docs): Point docs_url at canonical docs.agent-assembly.com
• 70e36a6f 📝 (docs): Regenerate docs-url snippet with canonical host

Fixes an issue caught in review: metadata/docs.yaml pointed at the GitHub Pages mirror (ai-agent-assembly.github.io/agent-assembly/latest/). Per ADR-0008 (SaaS host-routing) and root README.md, the canonical published-docs host is docs.agent-assembly.com; the Pages deployment is the upstream mirror the CDN pulls from and MUST NOT be surfaced to readers. The fix updates the source of truth + regenerates the affected snippet. The single remaining ai-agent-assembly.github.io reference in docs/src/adr/0007-public-domain-and-url-contract.md is intentional — it is the ADR narrating the historical/upstream URL contract.

Side effects: none. Only metadata/docs.yaml + one regenerated snippet. Zero runtime/Rust code touched.

FE validation (Playwright, mdBook static site):

• versioning.html: renders correctly; protocol/v1 visible 8 times via the include chain; zero stale Pages URL.
• releases.html: renders 0.0.1-rc.3 once from the version-tag include; zero stale Pages URL.
• Screenshots preserved locally at .validation-artifacts/AAASM-4310-{versioning,releases}-rendered.png.

Verdict: ready to approve and merge. 8 clean atomic gitmoji commits.