Add example index consistency check

Author: marcofortina

docs/guides/example-indexes.md

@@ -0,0 +1,21 @@
+<!--
+Copyright (C) 2026 Marco Fortina
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Example and index consistency
+
+Automax keeps examples, generated plugin lists, runtime pack definitions and documentation navigation aligned with `scripts/check-example-indexes.sh`.
+
+```bash
+scripts/check-example-indexes.sh
+```
+
+The check verifies:
+
+- plugin smoke runbooks against `examples/runbooks/RUNBOOK_INDEX.md`;
+- the documented builtin plugin list in `docs/plugins/index.md`;
+- guide pages listed in `mkdocs.yml`;
+- required runtime validation pack environment files.
+
+Run it before release when examples or plugin documentation change.

docs/reference/release.md

@@ -41,6 +41,7 @@ The script verifies:
 
 - the `CHANGELOG.md` section for the package version;
 - generated plugin reference freshness;
+- example and documentation indexes through `scripts/check-example-indexes.sh`;
 - plugin smoke runbook index freshness;
 - policy/risk preflight for committed examples;
 - SQLite database smoke through `scripts/database-smoke.sh`;

mkdocs.yml

@@ -75,6 +75,7 @@ nav:
     - Approval Gates: guides/approval-gates.md
     - Runtime Evidence Index: guides/runtime-evidence-index.md
     - Package Release Smoke: guides/package-release-smoke.md
+    - Example Indexes: guides/example-indexes.md
     - Run Event Stream: guides/run-event-stream.md
     - Publishing Documentation: guides/publishing-docs.md
   - Reference:

scripts/check-example-indexes.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Copyright (C) 2026 Marco Fortina
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${ROOT}"
+
+python - <<'PY'
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import yaml
+
+failures: list[str] = []
+
+index_path = Path("examples/runbooks/RUNBOOK_INDEX.md")
+index_text = index_path.read_text(encoding="utf-8")
+indexed = {
+    match.group("file"): int(match.group("count"))
+    for match in re.finditer(
+        r"\| `(?P<file>runbooks/[^`]+[.]check[.]yaml)` \| [^|]+ \| (?P<count>\d+) \|",
+        index_text,
+    )
+}
+actual = {}
+for runbook_path in sorted(Path("examples/runbooks/runbooks").glob("*.check.yaml")):
+    data = yaml.safe_load(runbook_path.read_text(encoding="utf-8"))
+    count = sum(
+        1
+        for task in data.get("tasks", [])
+        for step in task.get("steps", [])
+        for _ in step.get("substeps", [])
+    )
+    actual[f"runbooks/{runbook_path.name}"] = count
+if indexed != actual:
+    failures.append(
+        "examples/runbooks/RUNBOOK_INDEX.md is stale: "
+        f"missing={sorted(set(actual) - set(indexed))} "
+        f"extra={sorted(set(indexed) - set(actual))} "
+        f"stale={sorted(name for name in set(actual) & set(indexed) if actual[name] != indexed[name])}"
+    )
+
+plugin_index = Path("docs/plugins/index.md").read_text(encoding="utf-8")
+listed_plugins = set(re.findall(r"^([a-z][a-z0-9_]*(?:[.][a-z][a-z0-9_]*)+)$", plugin_index, flags=re.MULTILINE))
+from automax.core.engine import AutomaxEngine
+actual_plugins = set(AutomaxEngine().plugin_registry.names())
+if listed_plugins != actual_plugins:
+    failures.append(
+        "docs/plugins/index.md plugin list is stale: "
+        f"missing={sorted(actual_plugins - listed_plugins)} "
+        f"extra={sorted(listed_plugins - actual_plugins)}"
+    )
+
+mkdocs = Path("mkdocs.yml").read_text(encoding="utf-8")
+for path in sorted(Path("docs/guides").glob("*.md")):
+    nav = path.as_posix().removeprefix("docs/")
+    if nav not in mkdocs:
+        failures.append(f"mkdocs.yml does not include guide: {nav}")
+
+pack_dir = Path("examples/runtime-packs")
+required_packs = {"package-only.env", "debian-like.env", "redhat-like.env", "privileged-vm.env"}
+actual_packs = {path.name for path in pack_dir.glob("*.env")}
+if required_packs - actual_packs:
+    failures.append(f"missing runtime pack env files: {sorted(required_packs - actual_packs)}")
+
+for pack in sorted(pack_dir.glob("*.env")):
+    text = pack.read_text(encoding="utf-8")
+    if "AUTOMAX_RUNTIME_PACK_STEPS" not in text:
+        failures.append(f"{pack}: missing AUTOMAX_RUNTIME_PACK_STEPS")
+
+if failures:
+    for failure in failures:
+        print(f"ERROR: {failure}")
+    raise SystemExit(1)
+print("Example and documentation indexes OK")
+PY

scripts/release-check.sh

@@ -96,6 +96,7 @@ PY
 check_release_metadata
 check_generated_plugin_reference
 check_runbook_index
+scripts/check-example-indexes.sh
 scripts/policy-risk-preflight.sh --path examples --fail-on high >/dev/null
 scripts/database-smoke.sh --engine sqlite --output-dir "${TMP_DIR}/database-smoke" >/dev/null
 

tests/test_documentation_and_regressions.py

@@ -2097,6 +2097,25 @@ def test_runtime_evidence_suite_is_documented_and_optional():
     assert "set AUTOMAX_SSH_HOST and AUTOMAX_SSH_USER" in result.stderr
 
 
+def test_example_index_check_is_documented_and_release_wired():
+    script = Path("scripts/check-example-indexes.sh").read_text(encoding="utf-8")
+    release = Path("scripts/release-check.sh").read_text(encoding="utf-8")
+    docs = "\n".join(
+        path.read_text(encoding="utf-8")
+        for path in [
+            Path("docs/guides/example-indexes.md"),
+            Path("docs/reference/release.md"),
+            Path("mkdocs.yml"),
+        ]
+    )
+
+    assert "examples/runbooks/RUNBOOK_INDEX.md" in script
+    assert "docs/plugins/index.md" in script
+    assert "examples/runtime-packs" in script
+    assert "scripts/check-example-indexes.sh" in release
+    assert "Example Indexes: guides/example-indexes.md" in docs
+
+
 def test_package_release_smoke_script_is_documented_and_release_wired():
     script = Path("scripts/package-release-smoke.sh").read_text(encoding="utf-8")
     release = Path("scripts/release-check.sh").read_text(encoding="utf-8")