[AAASM-4308] 📝 (docs): Add MkDocs shared metadata macros to prevent docs drift

[Chisanan232]

Description

Adds a MkDocs shared-metadata / macros layer so the Python SDK docs source
drift-prone factual values — the current SDK version, PyPI / repo / docs URLs,
import and CLI names, and canonical install commands — from one place
(pyproject.toml + docs_macros.py) instead of being hand-copied across
Markdown pages.

Implementation:

1. mkdocs-macros-plugin added to the docs dependency group only in
   pyproject.toml (not runtime).
2. docs_macros.py at the repo root reads pyproject.toml via tomllib
   and exposes an aa object to Markdown pages, with subsections for
   package facts, canonical URLs, and install commands.
3. mkdocs.yml enables the macros plugin with on_undefined: strict and
   on_error_fail: true, so an undefined {{ aa.* }} reference fails
   mkdocs build --strict instead of rendering as an empty string. CI
   already runs uv run mkdocs build --strict in
   .github/workflows/documentation.yaml, so the strict guard is the
   PR check.
4. Highest-drift user-facing pages (quick-start.md, compatibility/index.md,
   compatibility/release-process.md, examples/preparing-the-runtime-environment.md)
   now go through macros for the current SDK version, PyPI URL, docs URL,
   repo URL, import name, CLI name, and pip / uv install commands.
5. Historical release notes and per-release adapter tables are left literal —
   they describe historical facts, not current state.
6. New maintainer doc docs/development/docs-macros.md describes the macro
   contract: where each value comes from, how to add a new one, and what
   must stay literal. Linked from the Development index and nav.

Type of Change

• 📚 Documentation update

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-4308
• Related GitHub issues: N/A

Before / After examples

Package version — docs/quick-start.md

Before:

The package is published on PyPI as
[`agent-assembly`](https://pypi.org/project/agent-assembly/).

After:

The package is published on PyPI as
[`{{ aa.python_sdk.package_name }}`]({{ aa.urls.pypi }}) (current version:
`{{ aa.python_sdk.version }}`).

The version now flows from pyproject.toml → docs_macros.py → the rendered
page automatically at every build.

Install command — docs/quick-start.md

Before:

=== "uv"

    ```bash
    uv add agent-assembly
    ```

After:

=== "uv"

    ```bash
    {{ aa.commands.install_uv }}
    ```

The install snippet is now a single source of truth in docs_macros.py.

Testing

• Manual testing performed
• uv sync --group docs succeeds
• uv run mkdocs build --strict succeeds locally (strict-mode zero
  warnings after the branch was committed)
• rg "0\.0\.1rc3" docs/ shows only historical / adapter-release
  references and the maintainer-doc's own quoted example — no
  current-state page still hardcodes the version
• .github/workflows/documentation.yaml already runs
  uv run mkdocs build --strict, so an undefined-macro typo will fail
  CI

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation updated (new maintainer doc + updated user-facing pages)
• All tests passing (docs build strict)
• No runtime dependency added — mkdocs-macros-plugin is docs-only

How to verify locally

uv sync --group docs
uv run mkdocs build --strict

Then open site/quick-start/index.html and confirm the install snippets
and current version are rendered from pyproject.toml (currently
0.0.1rc3), and that the new maintainer page at
site/development/docs-macros/index.html renders correctly.

Coverage audit follow-up

A read-only coverage audit flagged three additional literals that still
appear inside the drift-prone value set. Their disposition:

1. README.md install snippets — pip install agent-assembly and
   uv add agent-assembly in the "Installation" and quick-start sections
   (HIGH). Deferred. README.md is rendered by GitHub, not by
   mkdocs-macros-plugin, so raw {{ aa.* }} Jinja would render as
   literal {{ }} on the repo landing page. There is no existing
   README.md.j2 template or scripts/render_readme.py generator in the
   repo, so templating the README would require a separate render step
   outside the mkdocs pipeline. Out of scope for this PR; can be filed
   as a follow-up ticket if we decide to keep the README's install
   snippet in lockstep with docs_macros.py.
2. README.md line ~130 quick-start install (HIGH). Deferred for the
   same reason as (1).
3. docs/compatibility/runtime.md — requires-python = ">=3.12,<4.0"
   literal in the "Python versions" table (MEDIUM). Fixed in commit
   46c5979 — replaced the literal with
   {{ aa.python_sdk.requires_python }} so the compatibility page reads
   the range from pyproject.toml via the shared macros. Verified with
   uv run mkdocs build --strict and by inspecting the rendered HTML.

Closes AAASM-4308.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Chisanan232]

Claude Code review — AAASM-4308

CI status: all 22 required checks green (unit + integration tests, CodeQL, docs strict build, SonarCloud, codecov, pip-audit). mergeStateStatus: BLOCKED is branch protection (review requirement), not a CI failure.

AC coverage vs Jira AAASM-4308:

• mkdocs-macros-plugin added to docs dep group only (pyproject.toml, uv.lock)
• mkdocs.yml enables macros with on_error_fail: true + on_undefined: strict
• docs_macros.py exposes aa variable, sourced from pyproject.toml via tomllib
• Version, package name, requires-python, import name, CLI name, docs/repo/PyPI URLs, install commands all available as aa.*
• Main user-facing pages migrated: quick-start.md, compatibility/index.md, compatibility/release-process.md, examples/preparing-the-runtime-environment.md
• Historical release/changelog content left literal (confirmed via rg "0\.0\.1rc3" docs/ — only historical adapter-release rows remain)
• uv sync --group docs + uv run mkdocs build --strict pass (documentation CI green on PR)
• Maintainer note added: docs/development/docs-macros.md, linked from nav
• PR body includes before/after examples

Side-effect assessment: additive-only. Runtime [project].dependencies untouched. Only file categories changed: docs Markdown, docs_macros.py (docs-time only), mkdocs.yml, pyproject.toml docs group, uv.lock. Zero risk to SDK runtime.

FE validation: N/A — MkDocs Material builds a static site; no interactive frontend behavior added/changed.

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

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

Claude Code re-review — AAASM-4308 (post coverage-audit follow-up)

CI status: all 29 required checks green (22 pass, 7 skipped — branch-conditional).

New commits since last review (1):

• 46c5979 📝 (docs): Template requires-python literal in compatibility/runtime.md — closes 1 of 3 audit gaps

Coverage-audit disposition confirmed:

• Gap 3 (MEDIUM) — Fixed. docs/compatibility/runtime.md now uses {{ aa.python_sdk.requires_python }}.
• Gaps 1 & 2 (README install snippets) — Deferred with justification: README.md is GitHub-rendered, outside the mkdocs macro pipeline. Templating it would require a separate render step (a new generator, e.g. README.md.j2) — out of scope for this PR.

Side effects: none. Additive-only, docs-only. mkdocs build --strict green.

FE validation: N/A — mkdocs Material builds a static site; no interactive frontend touched.

Verdict: ready to approve and merge.