Add runtime evidence index and retention

Author: marcofortina

docs/guides/runtime-evidence-index.md

@@ -0,0 +1,78 @@
+<!--
+Copyright (C) 2026 Marco Fortina
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Runtime evidence index and retention
+
+`scripts/runtime-evidence-index.sh` builds a stable JSON index across runtime
+validation pack evidence and SSH runtime evidence.
+
+Build or refresh the index:
+
+```bash
+scripts/runtime-evidence-index.sh
+```
+
+The default index path is:
+
+```text
+dist/runtime-evidence-index.json
+```
+
+## Verification
+
+Use `--verify` to validate every discovered `SHA256SUMS` file before the index is
+written:
+
+```bash
+scripts/runtime-evidence-index.sh --verify
+```
+
+Verification covers runtime validation pack directories under `dist/runtime-packs`
+and SSH runtime evidence files under `dist/runtime-evidence`.
+
+## Retention
+
+Use `--retain N` to keep only the latest N runtime validation pack runs per pack
+and the latest N SSH runtime evidence runs:
+
+```bash
+scripts/runtime-evidence-index.sh --verify --retain 10
+```
+
+Retention rewrites the runtime evidence checksum file after pruning SSH evidence
+files.
+
+## Automatic index updates
+
+`scripts/runtime-validation-packs.sh` and `scripts/runtime-evidence.sh` update the
+index automatically after producing evidence. Disable this only while debugging a
+narrow failure:
+
+```bash
+AUTOMAX_RUNTIME_EVIDENCE_INDEX_UPDATE=0 scripts/runtime-validation-packs.sh --pack package-only
+```
+
+Useful controls:
+
+```bash
+AUTOMAX_RUNTIME_EVIDENCE_INDEX=dist/runtime-evidence-index.json
+AUTOMAX_RUNTIME_EVIDENCE_RETAIN=10
+```
+
+## Index schema
+
+The index has a stable top-level shape:
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-01-01T00:00:00Z",
+  "entry_count": 1,
+  "entries": []
+}
+```
+
+Entries use `type: runtime-pack` or `type: runtime-evidence` and include relative
+paths to manifests, summaries, checksums and evidence files.

docs/guides/runtime-evidence.md

@@ -76,6 +76,19 @@ AUTOMAX_RUNTIME_EVIDENCE_PACKAGE=1 scripts/runtime-evidence.sh
 The package smoke log is stored in the evidence directory and included in
 `SHA256SUMS`.
 
+## Index and retention
+
+The runtime evidence script updates `dist/runtime-evidence-index.json`
+automatically after producing evidence. Set `AUTOMAX_RUNTIME_EVIDENCE_RETAIN` to
+keep only the latest N SSH evidence runs while refreshing the index:
+
+```bash
+AUTOMAX_RUNTIME_EVIDENCE_RETAIN=10 scripts/runtime-evidence.sh
+```
+
+Use `scripts/runtime-evidence-index.sh --verify` to validate existing checksums
+and rebuild the index without running a new SSH smoke.
+
 ## CI behavior
 
 The script exits with code `77` when `AUTOMAX_SSH_HOST` or `AUTOMAX_SSH_USER` is

docs/guides/runtime-validation-packs.md

@@ -68,3 +68,16 @@ logs/<step>.log
 Steps that require unavailable runtime inputs return `skipped` with `rc=77` in
 the manifest. Failed steps stop the pack by default. Use `--keep-going` to collect
 all step outcomes before returning a failing summary.
+
+## Index and retention
+
+Runtime validation packs update `dist/runtime-evidence-index.json` automatically
+after each run. Set `AUTOMAX_RUNTIME_EVIDENCE_RETAIN` to prune older evidence
+runs while updating the index:
+
+```bash
+AUTOMAX_RUNTIME_EVIDENCE_RETAIN=10 scripts/runtime-validation-packs.sh --pack package-only
+```
+
+Use `scripts/runtime-evidence-index.sh --verify` to rebuild the index and verify
+all discovered checksums without running a new pack.

docs/reference/release.md

@@ -75,6 +75,7 @@ Keep the following with the release record:
 - `scripts/release-check.sh` output;
 - runtime evidence from disposable hosts when the release changes runtime
   behavior;
+- `dist/runtime-evidence-index.json` generated with checksum verification;
 - runtime validation pack output from `scripts/runtime-validation-packs.sh`;
 - `automax plugins coverage --strict` output for builtin and release-loaded
   plugins;

mkdocs.yml

@@ -70,6 +70,7 @@ nav:
     - Extended SSH Smoke: guides/ssh-smoke.md
     - Runtime Evidence Suite: guides/runtime-evidence.md
     - Runtime Validation Packs: guides/runtime-validation-packs.md
+    - Runtime Evidence Index: guides/runtime-evidence-index.md
     - Publishing Documentation: guides/publishing-docs.md
   - Reference:
     - CLI: reference/cli.md