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

docs/compatibility/index.md

@@ -14,9 +14,10 @@ core runtime does a given SDK build talk to?*, and *how do versions and releases
 
 The SDK is **pre-1.0 (`0.x`)**. It is published and usable, but the public API is not yet
 frozen: until `1.0.0`, minor versions may carry breaking changes. If you need a stable
-contract, **pin an exact version** (`agent-assembly==0.0.x`). From `1.0.0` onward the project
-follows [SemVer](https://semver.org/). The canonical version lives in `pyproject.toml`
-(`[project].version`) and is mirrored in `agent_assembly.__version__`.
+contract, **pin an exact version** (`{{ aa.python_sdk.package_name }}=={{ aa.python_sdk.version }}`).
+From `1.0.0` onward the project follows [SemVer](https://semver.org/). The canonical version
+lives in `pyproject.toml` (`[project].version`) and is mirrored in
+`{{ aa.python_sdk.import_name }}.__version__`.
 
 ## Core ↔ SDK compatibility matrix
 

docs/compatibility/release-process.md

@@ -20,8 +20,9 @@ wheel by platform tag, no post-install scripts needed:
 | `agent_assembly-<v>-…-macosx_*_arm64.whl` / `…x86_64.whl` | SDK + macOS `aasm` binary |
 | `agent_assembly-<v>.tar.gz` (sdist) | Pure-Python source |
 
-`pip install agent-assembly` gets the pure-Python client; `pip install 'agent-assembly[runtime]'`
-pulls the platform wheel that bundles the binary. See [Installation](https://github.com/ai-agent-assembly/python-sdk#installation).
+`{{ aa.commands.install_pip }}` gets the pure-Python client;
+`{{ aa.commands.install_pip_runtime }}` pulls the platform wheel that bundles the binary.
+See [Installation]({{ aa.urls.repo }}#installation).
 
 ## Publishing: Trusted Publisher (OIDC)
 
@@ -39,16 +40,16 @@ dry-run without publishing.
 2. Land it on `master` through the normal PR flow.
 3. Push the release tag — the workflow builds every platform wheel + sdist and publishes them
    to PyPI via the Trusted Publisher.
-4. Verify the wheels appear on the [PyPI release page](https://pypi.org/project/agent-assembly/#history)
+4. Verify the wheels appear on the [PyPI release page]({{ aa.urls.pypi }}#history)
    and carry platform tags (`manylinux_*`, `macosx_*`), not `none-any`.
 
 ## Documentation versioning
 
 Docs are versioned with [`mike`](https://github.com/jimporter/mike): every push to `master`
 deploys to **`latest`**, and a release promotes to **`stable`**. Readers switch versions with
-the selector at the top of the [documentation site](https://docs.agent-assembly.com/python-sdk/).
+the selector at the top of the [documentation site]({{ aa.urls.docs }}).
 
 ## Release notes
 
 Release notes are tracked on the [Release notes](release-notes.md) page and the
-[GitHub releases](https://github.com/ai-agent-assembly/python-sdk/releases) feed.
+[GitHub releases]({{ aa.urls.repo }}/releases) feed.

docs/compatibility/runtime.md

@@ -7,7 +7,7 @@ Python versions it supports.
 
 | | |
 | --- | --- |
-| Supported | Python **3.12, 3.13, 3.14** (`requires-python = ">=3.12,<4.0"`) |
+| Supported | Python **3.12, 3.13, 3.14** (`requires-python = "{{ aa.python_sdk.requires_python }}"`) |
 | Tested in CI | 3.12 – 3.14 across Linux and macOS |
 
 The SDK uses modern typing (PEP 695 `type` aliases, PEP 604 unions), so 3.12 is the floor.

docs/development/docs-macros.md

@@ -0,0 +1,119 @@
+{% raw %}
+# Shared metadata macros in the docs
+
+The Python SDK docs use [`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/)
+so that drift-prone factual values — the current package version, the PyPI /
+repo / docs URLs, the import name, the CLI name, and canonical install
+commands — live in **one source of truth** instead of being hand-copied across
+Markdown pages.
+
+This page is the maintainer contract for that macro layer. Read it before
+adding a new shared value or before editing `docs_macros.py`.
+
+## Where the values come from
+
+Every macro variable exposed to Markdown pages is registered in
+[`docs_macros.py`](https://github.com/ai-agent-assembly/python-sdk/blob/master/docs_macros.py)
+at the repo root and is available in Markdown as the top-level `aa` object.
+
+The layout is:
+
+| Section | What lives here | Source |
+| --- | --- | --- |
+| `aa.python_sdk` | Package version, package name, `requires-python`, import name, CLI name | `pyproject.toml` (via `tomllib`) for version / name / `requires-python`; string literals in `docs_macros.py` for the import and CLI names |
+| `aa.urls` | Canonical docs, repo, and PyPI URLs | String literals in `docs_macros.py` |
+| `aa.commands` | Install snippets (`pip install …`, `uv add …`, runtime extra) | String literals in `docs_macros.py` |
+
+The **package version is never hand-maintained in Markdown**. It is read from
+`[project].version` in `pyproject.toml` at every docs build, so a release bump
+to `pyproject.toml` automatically updates every page that references
+`{{ aa.python_sdk.version }}`.
+
+## Adding a new shared value
+
+1. Open `docs_macros.py` at the repo root.
+2. Add the value under the appropriate section of the `aa` dict inside
+   `define_env`:
+      - `python_sdk` — package-authoritative facts (prefer sourcing from
+        `pyproject.toml` where possible).
+      - `urls` — canonical URLs (docs, repo, PyPI, related sites).
+      - `commands` — install and CLI snippets.
+
+    If none of these fit, add a new section rather than overloading an
+    existing one.
+3. Reference it from any Markdown page as `{{ aa.<section>.<key> }}`.
+4. Run `uv run mkdocs build --strict` locally. Because `mkdocs.yml` sets
+   `on_undefined: strict` and `on_error_fail: true`, a typo in the variable
+   path fails the build immediately instead of silently rendering an empty
+   string.
+
+Example — adding a new URL:
+
+```python
+# docs_macros.py
+aa = {
+    ...
+    "urls": {
+        "docs": "https://docs.agent-assembly.com/python-sdk/",
+        "repo": "https://github.com/ai-agent-assembly/python-sdk",
+        "pypi": "https://pypi.org/project/agent-assembly/",
+        # new value:
+        "issues": "https://github.com/ai-agent-assembly/python-sdk/issues",
+    },
+    ...
+}
+```
+
+```markdown
+<!-- in any Markdown page -->
+Report bugs on the [issue tracker]({{ aa.urls.issues }}).
+```
+
+## What NOT to template
+
+- **Historical release notes and per-release adapter tables** — a line like
+  ``| `agent-assembly` | `>=0.0.1rc3` (the release that ships the Haystack
+  adapter) |`` is a **historical fact** about which version first shipped a
+  feature. It must remain a literal so future readers can still see when that
+  feature landed.
+- **Version-range examples** (e.g. `agent-assembly==0.0.x`) that illustrate a
+  pinning pattern rather than the current version.
+- **One-off framework-composed install commands** where the readability cost
+  of `{{ aa.commands.install_pip }} langchain` exceeds the drift risk of
+  `pip install agent-assembly langchain`. Templating everything is not the
+  goal; the goal is to keep the **current-state, high-drift** values in sync.
+
+If in doubt, ask: *"When we cut the next release, will this line become
+wrong if left alone?"* If yes, template it. If no, leave it literal.
+
+## Fail-fast behavior
+
+The plugin is configured in `mkdocs.yml` as:
+
+```yaml
+- macros:
+    module_name: docs_macros
+    on_error_fail: true
+    on_undefined: strict
+```
+
+Combined with the CI job that runs `uv run mkdocs build --strict` in
+`.github/workflows/documentation.yaml`, this means:
+
+- A typo like `{{ aa.python_sdk.versio }}` **fails the docs build** rather
+  than rendering as an empty string.
+- A missing macro function or Python-side exception in `docs_macros.py`
+  **fails the docs build** rather than being logged and skipped.
+
+So CI is the safety net: if a macro reference is broken, the PR cannot merge
+with a green docs check.
+
+## Related files
+
+- `docs_macros.py` — the macros module.
+- `mkdocs.yml` — enables the plugin (search for `- macros:`).
+- `pyproject.toml` — the version / package-name / `requires-python` source of
+  truth read by `docs_macros.py`.
+- `.github/workflows/documentation.yaml` — the CI job that runs
+  `mkdocs build --strict`.
+{% endraw %}

docs/development/index.md

@@ -9,6 +9,7 @@ Agent Assembly Python SDK. Start here when contributing code or operating a rele
 | --- | --- |
 | [CONTRIBUTING.md](https://github.com/ai-agent-assembly/python-sdk/blob/master/CONTRIBUTING.md) | Dev environment setup, framework adapter authoring, test/lint commands, branch naming, PR checklist. |
 | [Architecture](../concepts/architecture.md) | Internals: the adapter/patch layers, the PyO3 FFI layer, and the exact `init_assembly()` bootstrap/teardown order. |
+| [Docs macros (shared metadata)](docs-macros.md) | How the MkDocs macro variables (`aa.*`) work, how to add a new shared value, and what must stay literal. |
 | [Compatibility & Versioning](../compatibility/index.md) | Supported Python versions, core-runtime tracking, and the release process. |
 | [Troubleshooting](../troubleshooting.md) | Common integration errors, what they mean, and how to fix them. |
 

docs/examples/preparing-the-runtime-environment.md

@@ -23,11 +23,11 @@ specific to that example.
 
 ## Install the SDK
 
-Each example declares `agent-assembly` as a dependency, so `uv sync` (below) pulls it in.
-To install the SDK on its own in your own project:
+Each example declares `{{ aa.python_sdk.package_name }}` as a dependency, so `uv sync`
+(below) pulls it in. To install the SDK on its own in your own project:
 
 ```bash
-pip install agent-assembly
+{{ aa.commands.install_pip }}
 ```
 
 Some examples need a framework extra alongside the SDK (for instance LangChain pulls in

docs/quick-start.md

@@ -7,24 +7,26 @@ mock LLM, so you need no API keys and no network access to the outside world.
 ## 1. Install
 
 The package is published on PyPI as
-[`agent-assembly`](https://pypi.org/project/agent-assembly/).
+[`{{ aa.python_sdk.package_name }}`]({{ aa.urls.pypi }}) (current version:
+`{{ aa.python_sdk.version }}`).
 
 === "pip"
 
     ```bash
-    pip install agent-assembly            # pure-Python SDK
-    pip install 'agent-assembly[runtime]' # SDK + bundled aasm runtime binary (platform wheel)
+    {{ aa.commands.install_pip }}            # pure-Python SDK
+    {{ aa.commands.install_pip_runtime }} # SDK + bundled aasm runtime binary (platform wheel)
     ```
 
 === "uv"
 
     ```bash
-    uv add agent-assembly
+    {{ aa.commands.install_uv }}
     ```
 
-`agent-assembly` is the pure-Python client. `agent-assembly[runtime]` additionally pulls a
-platform wheel (`manylinux`, `macosx`) that bundles the `aasm` gateway/runtime binary, so a
-local gateway is available without a separate install.
+`{{ aa.python_sdk.package_name }}` is the pure-Python client.
+`{{ aa.python_sdk.package_name }}[runtime]` additionally pulls a platform wheel
+(`manylinux`, `macosx`) that bundles the `{{ aa.python_sdk.cli_name }}`
+gateway/runtime binary, so a local gateway is available without a separate install.
 
 ## 2. Point the SDK at a gateway
 
@@ -48,7 +50,7 @@ local default port).
 This example imports LangChain alongside the SDK, so install both:
 
 ```bash
-pip install agent-assembly langchain langchain-community
+{{ aa.commands.install_pip }} langchain langchain-community
 ```
 
 Then run:

docs_macros.py

@@ -0,0 +1,69 @@
+"""MkDocs macro adapter for the Python SDK docs (AAASM-4308).
+
+Sources shared, drift-prone metadata (package version, package/import/CLI
+names, canonical URLs, install commands) from a single source of truth and
+exposes it to Markdown pages as an ``aa`` variable via ``mkdocs-macros-plugin``.
+
+The primary source of truth is ``pyproject.toml`` (via :mod:`tomllib`); values
+that are cross-repo product metadata (canonical URLs, install commands, CLI
+name, import name) live in the ``aa`` dict below and are the maintainer-facing
+knob for any new shared value.
+
+Adding a new shared value
+-------------------------
+
+1. Add the value under the appropriate section of ``aa`` in ``define_env``
+   (``python_sdk`` for package-authoritative facts, ``urls`` for canonical
+   URLs, ``commands`` for install / CLI snippets).
+2. Reference it from Markdown as ``{{ aa.<section>.<key> }}``.
+3. Do not template historical release notes / changelog entries — those
+   values are historical facts and must remain literal.
+
+Fail-fast behavior
+------------------
+
+``mkdocs.yml`` enables the macros plugin with ``on_undefined: strict`` and
+``on_error_fail: true`` so an undefined ``{{ aa.* }}`` reference fails the
+docs build under ``mkdocs build --strict`` instead of rendering as an empty
+string.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parent
+
+
+def define_env(env: Any) -> None:
+    """Register the shared ``aa`` metadata variable on the macros env.
+
+    Called by ``mkdocs-macros-plugin`` at build time. See module docstring
+    for the maintainer contract when adding new shared values.
+    """
+    pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
+    project = pyproject["project"]
+
+    aa: dict[str, dict[str, str]] = {
+        "python_sdk": {
+            "package_name": project["name"],
+            "version": project["version"],
+            "requires_python": project["requires-python"],
+            "import_name": "agent_assembly",
+            "cli_name": "aasm",
+        },
+        "urls": {
+            "docs": "https://docs.agent-assembly.com/python-sdk/",
+            "repo": "https://github.com/ai-agent-assembly/python-sdk",
+            "pypi": "https://pypi.org/project/agent-assembly/",
+        },
+        "commands": {
+            "install_uv": "uv add agent-assembly",
+            "install_pip": "pip install agent-assembly",
+            "install_pip_runtime": "pip install 'agent-assembly[runtime]'",
+        },
+    }
+
+    env.variables["aa"] = aa

mkdocs.yml

@@ -80,6 +80,16 @@ theme:
 plugins:
   # Built-in client-side search — restores the search bar in the rendered site.
   - search
+  # AAASM-4308: shared metadata macros. Reads pyproject.toml (via docs_macros.py)
+  # and exposes an `aa` variable to Markdown pages so version/install/URL literals
+  # are sourced from a single place. `on_undefined: strict` + `on_error_fail: true`
+  # makes an unknown `{{ aa.* }}` reference fail the strict build instead of
+  # silently rendering empty. Placed before mkdocstrings so macros are expanded
+  # before docstring blocks render.
+  - macros:
+      module_name: docs_macros
+      on_error_fail: true
+      on_undefined: strict
   # Doc-as-Code — render Python API reference inline from package docstrings.
   - mkdocstrings:
       handlers:
@@ -261,5 +271,6 @@ nav:
   - Troubleshooting: troubleshooting.md
   - Development:
       - development/index.md
+      - Docs macros (shared metadata): development/docs-macros.md
       - ADR:
           - 0001 — Hook architecture: development/adr/0001-hook-architecture.md

pyproject.toml

@@ -138,6 +138,9 @@ docs = [
     "mkdocs-autorefs>=1.0.0,<2",
     "mkdocs-git-revision-date-localized-plugin>=1.2.0,<2",
     "mkdocs-git-authors-plugin>=0.9.0,<1",
+    # AAASM-4308: shared metadata macros for docs pages. Docs-only — MUST NOT
+    # be added to `[project].dependencies` (runtime install stays lean).
+    "mkdocs-macros-plugin>=1,<2",
 ]
 
 [tool.uv]