From 3b4d0020a7a9e955a3693d2a22649504f6c2f1d2 Mon Sep 17 00:00:00 2001
From: Azeez Ishaqui <debaterishaqui@gmail.com>
Date: Sat, 4 Jul 2026 16:52:39 -0400
Subject: [PATCH 1/3] tests: coverage-enforcing serve-matrix release gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

run_all_models.py boots each model×quant and writes per-model JSON but never
exits non-zero on failure — so "verified iff the matrix passes" was a human
reading a table, and a model that crashed at boot (no JSON written) was
invisible. A glob-only scorer would report the survivors green: a false ship.

- run_all_models.py now writes all_models_results/_manifest.json — the roster
  it planned to cover, derived from planned_specs() (SSOT for the roster).
- gate_results.py reads that manifest and fails any planned model with no
  passing result. Missing manifest is a hard FAIL unless --allow-missing-manifest
  is passed (explicit, coverage-unenforced). Exit 0 ships, 1 blocks.
- tests/test_gate_results.py (stdlib unittest, no GPU) locks in the bars and the
  planned-but-absent = FAIL property.
---
 tests/gate_results.py      | 225 +++++++++++++++++++++++++++++++++++++
 tests/run_all_models.py    |  58 ++++++++++
 tests/test_gate_results.py | 137 ++++++++++++++++++++++
 3 files changed, 420 insertions(+)
 create mode 100644 tests/gate_results.py
 create mode 100644 tests/test_gate_results.py

diff --git a/tests/gate_results.py b/tests/gate_results.py
new file mode 100644
index 000000000..1e687e7af
--- /dev/null
+++ b/tests/gate_results.py
@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Serve-matrix release gate — turn single_gpu_suite.py outputs into a PASS/FAIL.
+
+`tests/run_all_models.py` boots each model×quant and writes one
+`tests/all_models_results/<label>.json` per model (the schema emitted by
+`tests/single_gpu_suite.py`). That orchestrator never exits non-zero on a test
+failure — it only persists JSON. This script is the missing verdict: it reads
+those results, applies explicit per-model bars, and exits 0 (ship) or 1 (block).
+
+    python3 tests/run_all_models.py                 # produce results + _manifest.json
+    python3 tests/gate_results.py                   # the gate — exit 0/1
+
+Coverage is enforced, not assumed. run_all_models.py writes `_manifest.json`
+listing every model the run *intended* to cover. This gate checks that roster:
+a planned model that never booted writes no `<label>.json`, and that MISSING
+result is a FAIL — not silently absent. Without this, a glob-only gate would
+score the survivors and report a false green when half the matrix crashed at
+boot. ("Serve all" means all planned, not all-that-happened-to-write.)
+
+Design (see .claude/skills/atlas-release/references/verify-matrix.md §Gate):
+  * SBIO — the decision logic here is pure over the results JSON; the only I/O is
+    reading the files. No server/host/port is baked in.
+  * PCND — every bar is an explicit constant chosen up front, with a rationale.
+    No implicit "looks close enough"; no implicit "coverage was probably fine."
+    A missing manifest is a hard FAIL unless coverage is explicitly waived.
+  * SSOT — the roster lives in run_all_models.py (the manifest); this gate
+    derives from it and never re-lists models.
+A model "verifies" iff it is in the manifest AND its results file exists (it
+booted past the /v1/models health check — single_gpu_suite exits before writing
+if the server is unreachable) AND it clears every bar below.
+"""
+
+import argparse
+import glob
+import json
+import os
+import sys
+
+MANIFEST_NAME = "_manifest.json"
+
+# ── Per-model bars (PCND: explicit, rationale inline) ────────────────────────
+COHERENCE_MIN_PASS = 2   # of 3 probes (factual + reasoning + creative); >=2 tolerates
+                         #   the one temp>0 creative probe occasionally missing.
+FIB_MIN_PASS = 1         # the fibonacci codegen smoke must exec-verify.
+# Tools: known-gap parsers score every tool test "N/A" and must NOT fail the gate.
+# A model whose parser IS wired up must land at least one real PASS — a result
+# that is all WARN/FAIL (parser supposedly supported but never produced a call)
+# is a regression.
+
+
+def _status_pass(s):
+    return "PASS" in (s or "")
+
+
+def _status_na(s):
+    return "N/A" in (s or "")
+
+
+def verdict(model_result):
+    """Pure: return the list of bar names this model FAILED (empty == verified)."""
+    fails = []
+
+    coh = model_result.get("coherence", []) or []
+    coh_pass = sum(1 for r in coh if _status_pass(r.get("status")))
+    if coh and coh_pass < COHERENCE_MIN_PASS:
+        fails.append(f"coherence({coh_pass}/{len(coh)})")
+
+    fib = model_result.get("fibonacci", []) or []
+    fib_pass = sum(1 for r in fib if _status_pass(r.get("status")))
+    if fib and fib_pass < FIB_MIN_PASS:
+        fails.append("fibonacci")
+
+    tc = model_result.get("tool_calls", []) or []
+    if tc:
+        any_pass = any(_status_pass(r.get("status")) for r in tc)
+        all_na = all(_status_na(r.get("status")) for r in tc)
+        if not any_pass and not all_na:
+            fails.append("tool_calls")
+
+    tps = [r.get("tps") for r in (model_result.get("tps", []) or [])
+           if isinstance(r.get("tps"), (int, float))]
+    if tps and (sum(tps) / len(tps)) <= 0:
+        fails.append("tps(0)")
+
+    return fails
+
+
+def _is_model_result(obj):
+    return isinstance(obj, dict) and "coherence" in obj and "model" in obj
+
+
+def load_result_file(path):
+    """Read one <label>.json. Return (model_result | None, error_str | None).
+
+    A per-model file is written directly by single_gpu_suite.py, so it should be
+    a flat model-result shape. Tolerate the historical dict-of-results aggregate
+    by descending one level.
+    """
+    try:
+        with open(path) as f:
+            obj = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        return None, str(e)
+    if _is_model_result(obj):
+        return obj, None
+    if isinstance(obj, dict):
+        for v in obj.values():
+            if _is_model_result(v):
+                return v, None
+    return None, "malformed: no coherence/model fields"
+
+
+def load_manifest(results_dir, manifest_path):
+    """Return the planned [(label, model)] roster, or None if no manifest."""
+    path = manifest_path or os.path.join(results_dir, MANIFEST_NAME)
+    if not os.path.isfile(path):
+        return None
+    with open(path) as f:
+        man = json.load(f)
+    return [(e["label"], e.get("model", e["label"])) for e in man.get("labels", [])]
+
+
+def gate_manifest(results_dir, roster):
+    """Coverage-enforcing gate. Every planned label must have a passing result.
+
+    Returns (verified_count, total, failures) where failures is
+    [(label_or_model, [reasons])]. A planned model with no result file is a
+    failure ("did not boot / no results"), which is the whole point.
+    """
+    failures = []
+    for label, model in roster:
+        name = model or label
+        path = os.path.join(results_dir, f"{label}.json")
+        if not os.path.isfile(path):
+            print(f"  [FAIL] {name}  <- no result (did not boot / never wrote {label}.json)")
+            failures.append((name, ["no-result"]))
+            continue
+        result, err = load_result_file(path)
+        if result is None:
+            print(f"  [FAIL] {name}  <- unreadable: {err}")
+            failures.append((name, [f"unreadable: {err}"]))
+            continue
+        bars = verdict(result)
+        mark = "PASS" if not bars else "FAIL"
+        print(f"  [{mark}] {name}" + ("" if not bars else f"  <- {', '.join(bars)}"))
+        if bars:
+            failures.append((name, bars))
+    return len(roster) - len(failures), len(roster), failures
+
+
+def gate_glob(results_dir):
+    """Coverage-UNENFORCED fallback: score whatever <label>.json files exist.
+
+    Only reachable with --allow-missing-manifest. Cannot catch a model that
+    crashed at boot (no file). Prints a loud warning so a green here is never
+    mistaken for full-matrix coverage.
+    """
+    print("[gate] WARNING: no manifest — coverage is NOT enforced. A model that "
+          "crashed at boot is invisible here. Pass a real run's _manifest.json "
+          "for a trustworthy verdict.", file=sys.stderr)
+    failures = []
+    seen = 0
+    for path in sorted(glob.glob(os.path.join(results_dir, "*.json"))):
+        if os.path.basename(path) == MANIFEST_NAME:
+            continue
+        result, err = load_result_file(path)
+        if result is None:
+            continue  # aggregate/partial files, not per-model results
+        seen += 1
+        name = result.get("model", os.path.basename(path))
+        bars = verdict(result)
+        mark = "PASS" if not bars else "FAIL"
+        print(f"  [{mark}] {name}" + ("" if not bars else f"  <- {', '.join(bars)}"))
+        if bars:
+            failures.append((name, bars))
+    return seen - len(failures), seen, failures
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Serve-matrix release gate (exit 0=ship, 1=block).")
+    ap.add_argument("--results-dir", default=os.path.join(os.path.dirname(__file__), "all_models_results"),
+                    help="dir of per-model single_gpu_suite.py JSON outputs")
+    ap.add_argument("--manifest", default=None,
+                    help=f"path to the run manifest (default <results-dir>/{MANIFEST_NAME})")
+    ap.add_argument("--allow-missing-manifest", action="store_true",
+                    help="score only the files present (coverage NOT enforced). "
+                         "Explicit opt-out — the default is to FAIL without a manifest.")
+    args = ap.parse_args()
+
+    if not os.path.isdir(args.results_dir):
+        print(f"[gate] FAIL: no results dir {args.results_dir} — run tests/run_all_models.py first", file=sys.stderr)
+        return 1
+
+    roster = load_manifest(args.results_dir, args.manifest)
+    if roster is None:
+        if not args.allow_missing_manifest:
+            print(f"[gate] FAIL: no {MANIFEST_NAME} in {args.results_dir}. Run "
+                  f"tests/run_all_models.py (it writes the coverage manifest), or "
+                  f"pass --allow-missing-manifest to score present files without "
+                  f"coverage enforcement.", file=sys.stderr)
+            return 1
+        verified, total, failed = gate_glob(args.results_dir)
+    else:
+        if not roster:
+            print("[gate] FAIL: manifest lists zero planned models.", file=sys.stderr)
+            return 1
+        verified, total, failed = gate_manifest(args.results_dir, roster)
+
+    if total == 0:
+        print(f"[gate] FAIL: no per-model results found in {args.results_dir}", file=sys.stderr)
+        return 1
+
+    print(f"\n[gate] {verified}/{total} models verified"
+          + ("" if roster is None else " (full planned coverage)") + ".")
+    if failed:
+        print(f"[gate] FAIL — do not ship this image. {len(failed)} model(s) below bar:", file=sys.stderr)
+        for name, bars in failed:
+            print(f"         {name}: {', '.join(bars)}", file=sys.stderr)
+        return 1
+    print("[gate] PASS — serve matrix clean; image is shippable.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tests/run_all_models.py b/tests/run_all_models.py
index b1142da5c..396ced057 100644
--- a/tests/run_all_models.py
+++ b/tests/run_all_models.py
@@ -691,6 +691,51 @@ def run_ep2_round(spec: TestSpec) -> Optional[dict]:
     return {"label": spec.label, "mtp": spec.mtp, "data": data, "ep2": True}
 
 
+# ─── Coverage manifest ─────────────────────────────────────────────────
+
+MANIFEST_PATH = os.path.join(RESULTS_DIR, "_manifest.json")
+
+
+def planned_specs(run_singlegpu, skip, only_round,
+                  run_ep2, run_tp2, run_tpep, run_ep4):
+    """Return the ordered [(label, model)] this run intends to cover.
+
+    Mirrors the exact phase-selection logic in main(); it is the single source
+    of truth for the roster so the gate never re-lists models. A spec appears
+    here iff the run would attempt to boot it.
+    """
+    planned = []
+    if run_singlegpu:
+        for idx, pairs in enumerate(ROUNDS, start=1):
+            if only_round is not None and idx != only_round:
+                continue
+            if idx in skip:
+                continue
+            for _host, spec in pairs:
+                if spec is not None:
+                    planned.append((spec.label, spec.model))
+    if run_ep2:
+        planned += [(s.label, s.model) for s in EP2_ROUNDS]
+    if run_tp2:
+        planned += [(s.label, s.model) for s in TP2_ROUNDS]
+    if run_tpep:
+        planned += [(s.label, s.model) for s in TPEP_ROUNDS]
+    if run_ep4:
+        planned += [(s.label, s.model) for s in EP4_ROUNDS]
+    return planned
+
+
+def write_manifest(**flags):
+    planned = planned_specs(**flags)
+    manifest = {
+        "generated_by": "tests/run_all_models.py",
+        "labels": [{"label": label, "model": model} for label, model in planned],
+    }
+    with open(MANIFEST_PATH, "w") as f:
+        json.dump(manifest, f, indent=2)
+    print(f"[manifest] {len(planned)} model(s) planned this run -> {MANIFEST_PATH}")
+
+
 # ─── Main ──────────────────────────────────────────────────────────────
 
 def main():
@@ -718,6 +763,19 @@ def main():
     run_ep2 = (not args.skip_ep2) and (args.only_round is None) and (not only_phase_active)
     run_tp2 = (not args.skip_tp2) and (args.only_round is None) and (not args.only_tpep)
     run_tpep = (not args.skip_tpep) and (args.only_round is None) and (not args.only_tp2)
+    run_ep4 = bool(EP4_ROUNDS) and os.environ.get("ATLAS_ENABLE_EP4") == "1"
+
+    # Declare intent up front: the set of (label, model) this run is *supposed*
+    # to cover, given the phase flags above. Written before any container boots
+    # so it survives a total-crash run. tests/gate_results.py reads this to make
+    # "serve matrix passes" mean *every planned model produced a passing result*
+    # — a model that never booted writes no <label>.json and would otherwise be
+    # invisible to a glob-only gate (false green). SSOT for the roster is this
+    # planner; the gate derives coverage from it, it does not re-list models.
+    write_manifest(
+        run_singlegpu=run_singlegpu, skip=skip, only_round=args.only_round,
+        run_ep2=run_ep2, run_tp2=run_tp2, run_tpep=run_tpep, run_ep4=run_ep4,
+    )
 
     if run_singlegpu:
         for idx, pairs in enumerate(ROUNDS, start=1):
diff --git a/tests/test_gate_results.py b/tests/test_gate_results.py
new file mode 100644
index 000000000..90ae7621d
--- /dev/null
+++ b/tests/test_gate_results.py
@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Self-test for tests/gate_results.py — the serve-matrix release gate.
+
+Pure stdlib (unittest); no server, no GPU. Validates the two properties that
+matter: the per-model bars, and — the reason this gate exists — that a planned
+model which never produced a result FAILS coverage instead of being invisible.
+
+    python3 -m unittest tests.test_gate_results        # from repo root
+    python3 tests/test_gate_results.py                 # direct
+"""
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import gate_results as G  # noqa: E402
+
+
+def _model_result(model, *, coh=("PASS", "PASS", "PASS"),
+                  fib=("PASS",), tools=("PASS",), tps=(42.0,)):
+    return {
+        "model": model,
+        "coherence": [{"status": s} for s in coh],
+        "fibonacci": [{"status": s} for s in fib],
+        "tool_calls": [{"status": s} for s in tools],
+        "tps": [{"tps": v} for v in tps],
+    }
+
+
+class VerdictBars(unittest.TestCase):
+    def test_clean_pass(self):
+        self.assertEqual(G.verdict(_model_result("m")), [])
+
+    def test_creative_probe_may_miss(self):
+        # 2/3 coherence still passes (tolerates the temp>0 creative probe).
+        self.assertEqual(G.verdict(_model_result("m", coh=("PASS", "PASS", "FAIL"))), [])
+
+    def test_coherence_below_bar(self):
+        self.assertIn("coherence(1/3)", G.verdict(_model_result("m", coh=("PASS", "FAIL", "FAIL"))))
+
+    def test_fibonacci_must_exec(self):
+        self.assertIn("fibonacci", G.verdict(_model_result("m", fib=("FAIL",))))
+
+    def test_known_gap_tools_all_na_pass(self):
+        # A parser that is a known gap scores every tool test N/A — must not fail.
+        self.assertEqual(G.verdict(_model_result("m", tools=("N/A", "N/A"))), [])
+
+    def test_supported_parser_all_fail_is_regression(self):
+        self.assertIn("tool_calls", G.verdict(_model_result("m", tools=("FAIL", "WARN"))))
+
+    def test_zero_tps_fails(self):
+        self.assertIn("tps(0)", G.verdict(_model_result("m", tps=(0.0,))))
+
+
+class Coverage(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+
+    def _write(self, label, result):
+        with open(os.path.join(self.tmp, f"{label}.json"), "w") as f:
+            json.dump(result, f)
+
+    def _manifest(self, labels):
+        man = {"generated_by": "test", "labels": [{"label": l, "model": m} for l, m in labels]}
+        with open(os.path.join(self.tmp, G.MANIFEST_NAME), "w") as f:
+            json.dump(man, f)
+
+    def test_full_coverage_passes(self):
+        self._manifest([("a", "M/a"), ("b", "M/b")])
+        self._write("a", _model_result("M/a"))
+        self._write("b", _model_result("M/b"))
+        roster = G.load_manifest(self.tmp, None)
+        verified, total, failed = G.gate_manifest(self.tmp, roster)
+        self.assertEqual((verified, total, failed), (2, 2, []))
+
+    def test_missing_model_is_a_failure(self):
+        # 'b' was planned but never booted -> no b.json. This MUST fail.
+        self._manifest([("a", "M/a"), ("b", "M/b")])
+        self._write("a", _model_result("M/a"))
+        roster = G.load_manifest(self.tmp, None)
+        verified, total, failed = G.gate_manifest(self.tmp, roster)
+        self.assertEqual(total, 2)
+        self.assertEqual(verified, 1)
+        self.assertEqual([f[0] for f in failed], ["M/b"])
+        self.assertIn("no-result", failed[0][1])
+
+    def test_present_but_below_bar_fails(self):
+        self._manifest([("a", "M/a")])
+        self._write("a", _model_result("M/a", fib=("FAIL",)))
+        roster = G.load_manifest(self.tmp, None)
+        verified, total, failed = G.gate_manifest(self.tmp, roster)
+        self.assertEqual((verified, total), (0, 1))
+        self.assertIn("fibonacci", failed[0][1])
+
+    def test_no_manifest_returns_none(self):
+        self.assertIsNone(G.load_manifest(self.tmp, None))
+
+
+class MainExit(unittest.TestCase):
+    """Exercise the process-level contract: exit 0 ships, exit 1 blocks."""
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+
+    def _run(self, extra=()):
+        argv = sys.argv
+        sys.argv = ["gate_results.py", "--results-dir", self.tmp, *extra]
+        try:
+            return G.main()
+        finally:
+            sys.argv = argv
+
+    def test_no_manifest_blocks_by_default(self):
+        self.assertEqual(self._run(), 1)  # PCND: no silent pass without coverage
+
+    def test_missing_results_dir(self):
+        argv = sys.argv
+        sys.argv = ["gate_results.py", "--results-dir", os.path.join(self.tmp, "nope")]
+        try:
+            self.assertEqual(G.main(), 1)
+        finally:
+            sys.argv = argv
+
+    def test_full_pass_ships(self):
+        man = {"labels": [{"label": "a", "model": "M/a"}]}
+        with open(os.path.join(self.tmp, G.MANIFEST_NAME), "w") as f:
+            json.dump(man, f)
+        with open(os.path.join(self.tmp, "a.json"), "w") as f:
+            json.dump(_model_result("M/a"), f)
+        self.assertEqual(self._run(), 0)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

From 85544ca1d01f8ce148afa353717348e37fdcff2c Mon Sep 17 00:00:00 2001
From: Azeez Ishaqui <debaterishaqui@gmail.com>
Date: Sat, 4 Jul 2026 16:52:57 -0400
Subject: [PATCH 2/3] docs: GB10 deployment guide, atlas-release skill, CI/CLA
 convergence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two contributor-facing deliverables plus the low-risk convergence they exposed.

GB10 deployment & compatibility guide (docs/GB10_DEPLOYMENT_GUIDE.md):
the one page to read before picking a model — model×quant matrix (single-node +
scale-out), goal→recipe picker, weight/KV quant + OOM ladder, consolidated
known-issues, EP=2 troubleshooting, and what "verified" means. Routes to the
recipes/QUICKSTART/DEPLOYMENT rather than duplicating them; recipe defaults stay
the serve-config SSOT. Linked from the README as the welcoming first-read.

atlas-release skill (.claude/skills/atlas-release/): the build → verify → image →
publish pipeline + upstream-sync PR automation, grounded in the real commands,
containers, tags, and gates already in-tree. De-personalized so any contributor
can run it. (Under .claude/, which is gitignored — force-added so reviewers see
it; drop the path if skills should stay out of the tree.)

Convergence the above surfaced, applied where unambiguous:
- scripts/check-license-headers.sh — the script AGENTS.md / PR template / book
  all referenced but that never existed; thin wrapper over the same
  skywalking-eyes engine CI runs.
- docker/gb10/Dockerfile — ARG ATLAS_GIT_SHA + revision LABEL so the image
  records its commit (release.sh already passed the build-arg into a no-op).
- .github/workflows/cla.yml — allowlist maintainer identities so AI-authored
  maintainer PRs skip the CLA ceremony (external contributors still covered).
- AGENTS.md — file-size cap 250→500 to match the CI SSOT; clippy/license lines
  aligned to CI; model-matrix pointer → the new guide.
- Dead docs/EP2-TROUBLESHOOTING.md links (DEPLOYMENT, book, adr/0007) repointed
  to the guide §7; CONTRIBUTING notes CI-green ≠ shippable; docs/releases/ stub.
---
 .claude/skills/atlas-release/SKILL.md         | 181 +++++++++++
 .../atlas-release/references/pipeline.md      | 141 +++++++++
 .../atlas-release/references/pr-and-ci.md     | 129 ++++++++
 .../atlas-release/references/verify-matrix.md | 123 ++++++++
 .github/workflows/cla.yml                     |   8 +-
 AGENTS.md                                     |  18 +-
 CONTRIBUTING.md                               |  14 +-
 README.md                                     |   2 +
 book/src/operations/multi-gpu.md              |   2 +-
 docker/gb10/Dockerfile                        |   6 +
 docs/DEPLOYMENT.md                            |  11 +-
 docs/GB10_DEPLOYMENT_GUIDE.md                 | 293 ++++++++++++++++++
 docs/adr/0007-tp-ep-composition.md            |   2 +-
 docs/releases/README.md                       |  15 +
 scripts/check-license-headers.sh              |  28 ++
 15 files changed, 959 insertions(+), 14 deletions(-)
 create mode 100644 .claude/skills/atlas-release/SKILL.md
 create mode 100644 .claude/skills/atlas-release/references/pipeline.md
 create mode 100644 .claude/skills/atlas-release/references/pr-and-ci.md
 create mode 100644 .claude/skills/atlas-release/references/verify-matrix.md
 create mode 100644 docs/GB10_DEPLOYMENT_GUIDE.md
 create mode 100644 docs/releases/README.md
 create mode 100755 scripts/check-license-headers.sh

diff --git a/.claude/skills/atlas-release/SKILL.md b/.claude/skills/atlas-release/SKILL.md
new file mode 100644
index 000000000..e95a810c1
--- /dev/null
+++ b/.claude/skills/atlas-release/SKILL.md
@@ -0,0 +1,181 @@
+---
+name: atlas-release
+description: The Atlas build → verify → image → publish pipeline, plus the upstream-sync PR automation. Turns a merged commit into a serve-matrix-verified `avarok/atlas-gb10` image that users can pull. Use when cutting an image, closing the main→:latest staleness gap, wiring the release gate, or auto-syncing the fork and opening a MODEL.toml enablement PR. Codifies the REAL commands, containers, tags, and gates already in-tree — it does not invent a new release system.
+argument-hint: <build | verify | image | publish | gate | sync-pr> [target]
+allowed-tools: Bash, Read, Write, Grep, Glob, Agent, Edit
+---
+
+# /atlas-release — Atlas build → verify → ship pipeline
+
+One entry point for turning **merged code into a pullable, verified image**. The
+gap this closes: today `avarok/atlas-gb10:latest` is cut by hand on a GB10 build
+host and drifts weeks behind `main` because nothing rebuilds/re-verifies/re-tags on merge.
+This skill makes each stage explicit, gated, and reproducible so a new image can
+ship in minutes with proof it works.
+
+Four stages, each gates the next. **A stage's output is only valid if the prior
+stage passed its written bar.**
+
+| Stage | Question it answers | Produces | SSOT |
+|-------|--------------------|----------|------|
+| **1. Build** | Does the target(s) compile into one `spark` binary? | `spark` (PTX embedded) | `docker/gb10/Dockerfile`, `crates/atlas-kernels/build.rs` |
+| **2. Verify** | Does every model×quant boot, stay coherent, and hold the signals? | pass/fail verdict + results JSON | `tests/run_all_models.py`, `references/verify-matrix.md` |
+| **3. Image** | Package the *verified* binary, tag it to its exact source. | `avarok/atlas-gb10:<sha>` (+ `.tar` via `docker save`) | `docker/gb10/Dockerfile`, `references/pipeline.md` |
+| **4. Publish** | Make it pullable — **human-gated push** (never automated). | pushed `:sha`/`:dev`/`:latest` + recorded shipped SHA | maintainer runs `docker push`; `references/pipeline.md` |
+
+**Iron rule of this skill: no image is tagged shippable until the serve matrix
+passes.** `run_all_models.py` only writes per-model JSON — so **`tests/gate_results.py`**
+is the verdict: a pure scorer that turns those results into a real PASS/FAIL exit
+code. Crucially it enforces **full coverage** — `run_all_models.py` writes a
+`_manifest.json` of every model the run planned, and the gate fails any planned
+model that produced no result (a boot crash writes no JSON and would otherwise be
+an invisible false-green). `tests/test_gate_results.py` locks this behavior in.
+`references/verify-matrix.md` specifies the bars and the run order.
+
+**Two hard constraints, honored everywhere in this skill:**
+- **Never advance the shippable surface without a human gate.** No `docker push`
+  of any `avarok/atlas-gb10` tag and no moving of `:latest`/`:dev`/`:nightly` — the
+  pipeline builds, verifies, tags, and `docker save`s, and *prepares* the final
+  `docker push` for a maintainer to run (Stage 4 stops there). What ships to users
+  is a human decision on a verified artifact. **Additive git pushes are fine:**
+  `sync-pr` may push an enablement *branch* and open its PR — that is not a
+  shippable-surface change.
+- **No takeover PRs.** Sync-pr opens *enablement* PRs (MODEL.toml, new target) on
+  the fork, or pushes a trivial fix to an existing branch — never a parallel
+  reimplementation of someone's in-flight work. Contribute to the author's branch;
+  reference and comment rather than fork their work (see `CONTRIBUTING.md`).
+
+---
+
+## Commands
+
+### `/atlas-release build [<model-slug> | *]`  (default `*`)
+Compile the `spark` binary. `*` bakes **all** kernel targets into one multi-model
+binary (what `:latest` ships); a slug bakes one slim single-model binary.
+
+```bash
+# Multi-model sweep (the shippable binary). Host-native — the '38s incremental'.
+ATLAS_TARGET_HW=gb10 ATLAS_TARGET_MODEL='*' ATLAS_TARGET_QUANT='*' \
+  cargo build --release -p spark-server
+
+# Or inside the pinned builder image (what the Docker image does):
+docker build -f docker/gb10/Dockerfile -t atlas-gb10:build .
+```
+
+- `ATLAS_TARGET_MODEL` selects which `kernels/gb10/<model>/<quant>/` PTX + which
+  `MODEL.toml` sampling/behavior presets are **embedded** in the binary. It does
+  **not** bake weights — those always load at runtime from HF cache or
+  `--model-from-path`. Runtime picks the right target from the model's
+  `config.json` (`model_type` + `hidden_size`).
+- **Footgun (PCND):** a bare `cargo build` with the env vars *unset* defaults to
+  `qwen3-next-80b-a3b/nvfp4` **only** — not a sweep. The `*` is mandatory and
+  easy to forget. Always pass all three explicitly.
+- The "38s" figure is a **host cargo incremental** rebuild after Rust-only edits
+  (build.rs `rerun-if-changed` gating + its in-build nvcc dedup cache). A *Docker*
+  build is clean each time (~2–3 min; no BuildKit cache mount / sccache in-tree).
+- Full command reference, container split, and toolchain pins: `references/pipeline.md`.
+
+### `/atlas-release verify <image-or-url>`
+Run the **serve matrix** — the gate. A binary/image is "verified" only if it
+passes. Cheapest-sufficient path:
+
+1. **Single-model quick gate** (one model, one box) before the full matrix:
+   `scripts/dev/test_all_models.sh <hf-id> 8888` (boots the image, curls 6 fixed
+   coherence probes). Or the richer `tests/single_gpu_suite.py`.
+2. **Full serve matrix** across all model×quant rounds (head + optional worker):
+   `ATLAS_IMAGE=<tag> python3 tests/run_all_models.py`.
+3. **Coherence gate** (the `webserver_ok` idea, generalized): determinism (5×
+   temp=0 identical), tool reliability ≥8/10, no CJK/Cyrillic/`<think>`/
+   `<tool_call>` leak, streaming envelope valid — via `scripts/test_coherence.py`
+   and the parked `bench/fp8_dgx2_drift/harness` agentic probe.
+4. **Gate + record.** Compute a real pass/fail (Stage 2 in `references/verify-matrix.md`
+   turns the JSON into an exit code) and write the verdict next to the image tag.
+
+> Hand the numerical/behavioral faithfulness question to **`/coherence-parity
+> gate-release`** — that skill owns the KL / argmax / drift thresholds. This skill
+> owns the *operational* gate: does every model in the matrix boot and stay sane.
+
+### `/atlas-release image <git-sha>`
+Build the runtime image from the **verified** binary and tag it to its exact
+source. **Refuses if Stage 2 didn't pass for this SHA.**
+
+```bash
+SHA=$(git rev-parse --short=7 HEAD)
+docker build -f docker/gb10/Dockerfile \
+  --build-arg ATLAS_GIT_SHA="$SHA" \
+  -t avarok/atlas-gb10:"$SHA" .
+docker save avarok/atlas-gb10:"$SHA" | zstd -o atlas-gb10-"$SHA".tar.zst   # offline distribution
+```
+
+- Tag with the **git SHA first** — it is the only identifier that answers "is
+  `:latest` the merged code?" (Today three schemes drift: crate `0.1.0`, image
+  `alpha-2.x`/`3.0.0`, distro `vX.Y.Z`. The SHA tag is the anchor; moving tags
+  point at it.) See the version-provenance note in `references/pipeline.md`.
+- `--build-arg ATLAS_GIT_SHA` now stamps `org.opencontainers.image.revision` into
+  the image (the Dockerfile `ARG`+`LABEL` were added by this pass) — so
+  `docker inspect` answers "which commit is `:latest`?" directly. See
+  `references/pipeline.md` §Provenance.
+
+### `/atlas-release publish <tag>`  (human-gated)
+Move the moving tags onto a verified SHA image and **prepare** the push. This
+command does **not** run `docker push` — it prints the exact commands for the
+maintainer to run (or `docker save`s for offline transfer).
+
+```bash
+# Prepared for the maintainer to execute (all three moving tags advance together
+# onto the same verified SHA — see references/pipeline.md §Publish):
+docker tag avarok/atlas-gb10:$SHA avarok/atlas-gb10:nightly
+docker tag avarok/atlas-gb10:$SHA avarok/atlas-gb10:dev
+docker tag avarok/atlas-gb10:$SHA avarok/atlas-gb10:latest
+docker push avarok/atlas-gb10:$SHA && \
+  docker push avarok/atlas-gb10:nightly && \
+  docker push avarok/atlas-gb10:dev && \
+  docker push avarok/atlas-gb10:latest
+```
+
+After the maintainer pushes, record the shipped SHA (so "what's in `:latest`?"
+is answerable) — a one-line append to `docs/releases/` or the image label.
+
+### `/atlas-release gate`
+Standalone: run only the release gate (serve matrix + coherence probe) against a
+running image and return **PASS/FAIL** + the results table. This is the check
+that must be green before `publish`. `references/verify-matrix.md` is its spec.
+
+### `/atlas-release sync-pr`
+The upstream→fork automation. Watch `monumental/main` (upstream) for merges →
+fast-forward `origin` (Avarok fork) → build → verify → **if** the merge enables a
+new model (new `kernels/gb10/<model>/MODEL.toml` or loader), open the enablement
+PR. AI-attributed, CLA-clean, CI-green **before** submit. Full runbook incl. the
+remotes, the CLA allowlist cleanup, and the CI-green preflight: `references/pr-and-ci.md`.
+
+---
+
+## Operating principles
+- **SSOT:** serve config is owned by `atlas-recipes` recipe `defaults:` (not
+  hand-copied into every doc); the model registry is `kernels/gb10/<model>/MODEL.toml`;
+  the CI cap is `file-size-cap.yml` (≤500 LoC). Derive from these — never
+  restate a value that lives in one of them.
+- **PCND:** no stage runs on an implicit default. `ATLAS_TARGET_MODEL='*'` is
+  explicit; the verify bar is written before the run; the image tag is the SHA.
+  A bare `cargo build` (single-model default) is a bug, not a shortcut.
+- **SBIO:** the gate's decision logic (pass/fail from the results table) is pure;
+  the I/O is the results JSON + the container boot. Don't bake a host/port/tag
+  into the gate — pass them in (`ATLAS_IMAGE`, `--base-url`).
+- **CBD:** when the matrix fails, don't reship-and-pray — bisect. Which model,
+  which round, which signal (coherence vs tool vs determinism vs OOM). The
+  smoking gun is usually one model×quant, one signal. Hand numeric drift to
+  `/coherence-parity diagnose-drift`.
+- **Verify before publish, always.** A green CI (fmt/clippy/test) proves the code
+  compiles GPU-free; it does **not** prove the image serves. Only the serve
+  matrix does. CI-green ≠ shippable.
+
+## Integration
+- **`/coherence-parity`** owns numerical faithfulness (KL/argmax/drift + the
+  `gate-release` thresholds). `/atlas-release verify` calls it for the numeric
+  question and owns the operational "does it boot and stay sane" question.
+- **`/hypercompile`** produces the kernels this pipeline ships. A hypercompile
+  iteration isn't done until `/atlas-release verify` passes on the resulting image.
+- **`atlas-recipes`** is where a winning serve config lands as a recipe; this
+  pipeline ships the *engine* those recipes pin
+  (`container: avarok/atlas-gb10:latest`). Keeping the image fresh is what keeps
+  every `sparkrun run @atlas/*` honest.
diff --git a/.claude/skills/atlas-release/references/pipeline.md b/.claude/skills/atlas-release/references/pipeline.md
new file mode 100644
index 000000000..c8224b23b
--- /dev/null
+++ b/.claude/skills/atlas-release/references/pipeline.md
@@ -0,0 +1,141 @@
+# references/pipeline.md — build → image → publish, exact contract
+
+Everything `/atlas-release build`, `image`, and `publish` do, grounded in the
+real files. Nothing here is aspirational unless flagged **[TODO]**.
+
+## 1. Build
+
+### The binary
+```bash
+# The shippable multi-model sweep (host-native; the "38s incremental" path):
+ATLAS_TARGET_HW=gb10 ATLAS_TARGET_MODEL='*' ATLAS_TARGET_QUANT='*' \
+  cargo build --release -p spark-server
+# -> target/release/spark   (PTX for every kernels/gb10/<model>/<quant>/ embedded)
+```
+
+- **Target selection** is three env vars read in `crates/atlas-kernels/build.rs`
+  (defaults if unset: `gb10` / `qwen3-next-80b-a3b` / `nvfp4`). `*` = "every
+  subdir with a `MODEL.toml`". `build.rs` compiles each `.cu` to PTX with
+  `nvcc --ptx -arch=sm_121f` (arch from `kernels/gb10/HARDWARE.toml`) and emits
+  `OUT_DIR/target_ptx.rs`; a content-addressed dedup cache turns ~1100 naive
+  nvcc calls into ~170 unique compiles + copies, run across cores.
+- **Weights are never compiled in.** `MODEL.toml` contributes sampling presets +
+  behavior + the `(model_type, hidden_size)` match table, not weights.
+- **PCND footgun:** unset env → single-model `qwen3-next-80b-a3b` binary, *not* a
+  sweep. `/atlas-release build` always passes all three explicitly.
+- **Incrementality:** `build.rs` emits `cargo:rerun-if-changed` on every consumed
+  `.cu`/`.toml` and `rerun-if-env-changed` on the three `ATLAS_TARGET_*`. Touch
+  only Rust → build.rs doesn't rerun, PTX is reused, ~38s relink. Touch a kernel
+  or flip a target env → PTX recompiles for the affected targets.
+- **Fast Rust-only loop (no nvcc, no kernels):** set `ATLAS_SKIP_BUILD=1
+  CUDARC_CUDA_VERSION=13000` (exactly what CI uses) — `atlas-kernels/build.rs` and
+  `spark-runtime/build.rs` emit a PTX stub, so `cargo check`/clippy run without
+  nvcc. This is a hygiene loop, **not** a runnable binary. **[TODO]** `scripts/check.sh`
+  currently exports `SKIP_ATLAS_BUILD` (no `ATLAS_` prefix) + `CUDARC_CUDA_VERSION=12000`;
+  that name is honored only by `spark-storage/build.rs`, so it does *not* stub the
+  kernel crates. Prefer the `ATLAS_SKIP_BUILD` form until check.sh is fixed.
+
+### The container split (`docker/gb10/Dockerfile`, multi-stage)
+- **builder:** `nvidia/cuda:13.0.0-devel-ubuntu24.04` (digest-pinned). Installs
+  rust + `cmake clang libclang-dev` (vendored xgrammar-rs), sets
+  `ATLAS_TARGET_HW=gb10 ATLAS_TARGET_MODEL=* ATLAS_TARGET_QUANT=*`, runs
+  `cargo build --release -p spark-server`.
+- **runtime:** `nvidia/cuda:13.0.0-runtime-ubuntu24.04` (digest-pinned). Installs
+  `libnccl2` (**fail-fast asserts NCCL ≥ 2.28** for symmetric-memory
+  `ncclMemAlloc`) + RDMA userspace (`libibverbs1 librdmacm1 ibverbs-providers`).
+  Then **`COPY --from=builder /build/target/release/spark /usr/local/bin/spark`**
+  + `jinja-templates/` + LICENSE/README. `ENTRYPOINT ["spark"]`, `EXPOSE 8888`.
+- **"Mount the result into a runtime container" is a multi-stage `COPY`, not a
+  volume mount.** The binary is baked at build time. No nvcc in the runtime image
+  — the host driver re-JITs the embedded PTX → SASS for the running SM (ADR-0009).
+- **Toolchain hazard [TODO]:** the sweep Dockerfile sets `RUSTUP_TOOLCHAIN=stable`
+  to override the `rust-toolchain.toml` pin (`1.93.1`); the single-model
+  Dockerfiles don't. Two image families can build under different rustc. Pin both
+  to the same toolchain for reproducibility.
+
+### Model images
+- `docker/gb10/Dockerfile` = the **all-models** image (`avarok/atlas-gb10:*`).
+- `docker/gb10/<model>/nvfp4/Dockerfile` = per-model slim images (10 exist). Each
+  hardcodes `ATLAS_TARGET_MODEL=<slug> ATLAS_TARGET_QUANT=nvfp4`. Note only a
+  `nvfp4/` subdir exists per model — the nvfp4 bundle carries the FP8 + BF16 code
+  paths, so FP8 models (`qwen3.6-27b`, `qwen3.6-35b-a3b`) live under `nvfp4/` too.
+- **COPY-set divergence [TODO]:** the sweep Dockerfile COPYs `vendor/` (required —
+  `Cargo.toml` has `[patch.crates-io] cudarc = { path = "vendor/cudarc" }`) and
+  `jinja-templates/`; the single-model `qwen3.5-35b-a3b` Dockerfile COPYs neither.
+  Verify single-model images still build before relying on them.
+
+## 2. Image — tag to the source
+
+```bash
+SHA=$(git rev-parse --short=7 HEAD)
+docker build -f docker/gb10/Dockerfile --build-arg ATLAS_GIT_SHA="$SHA" \
+  -t avarok/atlas-gb10:"$SHA" .
+```
+
+**Always tag with the git SHA first.** It is the only identifier that answers
+"is `:latest` the merged code?" The moving tags (`:dev`, `:nightly`, `:latest`)
+are *pointers* moved onto a verified `:sha` in Stage 4 — never built independently.
+
+### Provenance — now stamped into the image
+`scripts/release.sh` and `/atlas-release image` pass `--build-arg ATLAS_GIT_SHA=...`.
+The runtime stage of `docker/gb10/Dockerfile` now declares the matching `ARG` +
+`LABEL org.opencontainers.image.revision` (added by this pass), so the SHA is
+recorded in the image. Answer the staleness question directly:
+
+```bash
+docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}' avarok/atlas-gb10:latest
+```
+
+(The per-model single-model Dockerfiles don't yet carry the `ARG` — add the same
+two lines there if you ship a per-model image and want its provenance.)
+
+### Offline distribution (`docker save`)
+```bash
+docker save avarok/atlas-gb10:"$SHA" | zstd -T0 -o atlas-gb10-"$SHA".tar.zst
+# receiver:  zstd -dc atlas-gb10-<sha>.tar.zst | docker load
+```
+Use this when there's no registry access, or to hand a verified image to a user
+directly (RoCE-copy dgx1→dgx2, or attach to a GitHub Release alongside the distro
+tarballs).
+
+## 3. Publish — human-gated (never automated)
+
+The pipeline stops here and **prepares** the push. The maintainer runs it. All
+moving tags (`:dev`, `:nightly`, `:latest`) advance together onto the same
+verified `:sha` — they are never built independently.
+
+```bash
+for T in nightly dev latest; do docker tag avarok/atlas-gb10:"$SHA" avarok/atlas-gb10:"$T"; done
+for T in "$SHA" nightly dev latest; do docker push avarok/atlas-gb10:"$T"; done
+```
+
+Preconditions the skill enforces before printing this:
+1. Stage 2 verify **passed** for exactly this `$SHA` (not a different tree).
+2. The build came from the intended ref — **build from `main` tip**, not whatever
+   branch happens to be checked out on the build host (a real past footgun; that
+   checkout is often a feature branch). Verify: `git rev-parse --short=7 origin/main == $SHA`.
+3. Docker is logged in as `avarok` on the pushing host.
+
+After push, **record the shipped SHA** so `:latest`'s provenance is durable — append
+to `docs/releases/` or rely on the image label from the ARG fix above.
+
+## Closing the main→:latest gap (why this pipeline exists)
+
+Today, three things are all manual and none are chained:
+1. Nothing rebuilds the image on merge to `main`.
+2. Nothing verifies an image before it's tagged `:latest`.
+3. The push is a human running `docker build && docker push` by hand from an
+   arbitrary branch.
+
+`release.yml` automates **only** the relocatable **tarball** distros on a `v*`
+tag (via `scripts/package-distro.sh` on self-hosted `[gb10]`/`[strix]` runners) —
+it never touches the Docker image. So the image path has zero automation.
+
+**The minimum viable close** (respecting no-auto-push): a self-hosted-runner
+workflow on `push: [main]` that runs Stage 1 (build) + Stage 2 (verify serve
+matrix) + Stage 3 (build + tag `:sha` + `docker save` as an artifact), and
+**stops** — surfacing a green "ready to publish `<sha>`" the maintainer promotes
+with one `docker push`. That turns weeks of drift into a one-command publish of a
+pre-verified image, while keeping the decision to ship to users in human hands.
+See `references/pr-and-ci.md` for the self-hosted-runner shape (the release-distros
+job already proves self-hosted GB10 runners work).
diff --git a/.claude/skills/atlas-release/references/pr-and-ci.md b/.claude/skills/atlas-release/references/pr-and-ci.md
new file mode 100644
index 000000000..575746208
--- /dev/null
+++ b/.claude/skills/atlas-release/references/pr-and-ci.md
@@ -0,0 +1,129 @@
+# references/pr-and-ci.md — sync-pr automation, CI-green preflight, CLA/CI cleanup
+
+## Remotes (know which is which)
+```
+origin      https://github.com/Avarok-Cybersecurity/atlas.git   # the fork we ship (maintainer pushes here)
+monumental  https://github.com/MonumentalSystems/atlas.git       # upstream
+```
+Sync direction: **upstream `monumental/main` → fork `origin/main`.** Never the
+reverse without intent. `sparkrun` recipes and `avarok/atlas-gb10` are built from
+`origin`.
+
+## `/atlas-release sync-pr` — the loop
+1. **Detect:** `git fetch monumental && git log --oneline origin/main..monumental/main`.
+   If empty, nothing to do.
+2. **Sync (fast-forward only):** advance `origin/main` to `monumental/main`. If it
+   won't fast-forward, **stop and report** — a diverged fork is a human decision,
+   not an auto-merge.
+3. **Build + verify:** `/atlas-release build *` → `/atlas-release verify`. A sync
+   that fails the serve matrix is a blocker to surface, not to ship past.
+4. **Enablement PR (only if warranted):** if the merge added a new
+   `kernels/gb10/<model>/MODEL.toml` or a new loader that needs a
+   `MODEL.toml`/`factory.rs`/docker stanza to be *deployable*, open **that**
+   enablement PR on `origin`. Otherwise there is no PR — a plain engine sync just
+   feeds the next image cut.
+5. **Preflight (below) must be green before submit.** AI-attributed, CLA-clean.
+
+**No-takeover rule:** sync-pr opens *additive* enablement PRs or pushes a trivial
+fix to an existing branch. It never opens a parallel reimplementation of someone's
+in-flight work — reference their branch and comment instead. Contribute to the
+author's work, don't fork around it.
+
+**Attribution:** commit as the contributing maintainer; state AI authorship in the
+PR body per `CONTRIBUTING.md` §Authorship (this is an AI-first repo — AI authorship
+is the norm), not as a tool/bot signature trailer in the commit.
+
+## CI-green preflight — run locally before every PR
+CI is **entirely GPU-free** (stubs `libcuda`/`libnccl` so no-GPU runners link).
+The kernel work happens on your box; CI only proves the Rust compiles + hygiene.
+Run exactly what CI runs, in this order — a red preflight is a red PR:
+
+```bash
+# 1. fmt          (ci.yml: fmt)
+cargo fmt --all -- --check
+# 2. clippy       (ci.yml: clippy — deny warnings comes from [workspace.lints], so no -Dwarnings needed)
+ATLAS_SKIP_BUILD=1 CUDARC_CUDA_VERSION=13000 cargo clippy --workspace --tests
+# 3. license hdrs (SPDX AGPL-3.0-only line 1 of every new .rs/.cu/.cuh/.h/.hpp/.cpp;
+#    wraps the same apache/skywalking-eyes engine ci.yml runs against .licenserc.yaml)
+bash scripts/check-license-headers.sh
+# 4. typos        (ci.yml: typos)
+typos                                   # cargo install typos-cli
+# 5. unit tests   (ci.yml: test — non-#[ignore] only, GPU-free)
+ATLAS_SKIP_BUILD=1 CUDARC_CUDA_VERSION=13000 cargo test --workspace --locked
+# 6. file-size    (file-size-cap.yml: ≤500 LoC per crates/**/*.rs, allow-list aside)
+find crates -name '*.rs' -not -name '*.bak' -not -path '*/target/*' | xargs wc -l | awk '$1>500 && $2!="total"'
+# 7. deny         (security.yml: cargo-deny)
+cargo deny check advisories licenses sources bans
+```
+
+CI job → check map (so a red check tells you which command to rerun):
+`fmt` · `clippy` · `license-headers` (skywalking-eyes, `.licenserc.yaml`) ·
+`typos` · `test` · `test-macos-metal` (asserts the metal binary links **neither**
+libcuda nor libnccl) · `File size cap` · `Security Audit` (weekly + on Cargo.*
+changes) · `Docs` · `Site`.
+
+⚠️ **CI-green ≠ shippable.** None of the above boots a model. Only
+`/atlas-release verify` (the serve matrix) proves the image serves. Keep the two
+gates distinct in your head and in PR descriptions.
+
+## CLA cleanup — "the CLA check isn't ideal, clean this up"
+
+### What it does today (`cla.yml`)
+`contributor-assistant/github-action@v2.6.1` posts a comment on any PR whose
+author is neither an existing signer (`signatures/version1/cla.json` on the
+`cla-signatures` branch) nor in the `allowlist`, and sets a **failing status
+check that blocks merge** until they reply with the exact phrase
+`I have read the CLA Document and I hereby sign the CLA`. A custom "Prepare Dynamic
+Signature Match" pre-step scrapes PR comment history via `gh api` to re-inject the
+signature on `synchronize`/push so re-pushes don't wipe it.
+
+### Why it's friction for an AI-first repo
+- The repo philosophy is "**all PRs are AI-generated**" — yet the CLA gates every
+  PR whose author isn't allowlisted, adding a manual comment ceremony to
+  automation the maintainer owns.
+- The `allowlist` originally covered only **bots** (`dependabot[bot]`,
+  `renovate[bot]`, `google-labs-jules[bot]`, `claude[bot]`, plus bare
+  `google-labs-jules`/`claude`). The maintainer's own human accounts (`AzeezIsh`,
+  `tbraun96`) were **not** on it — so their AI PRs depended on the mutable
+  signature-state file rather than a stable rule.
+- The dynamic-signature bolt-on is a maintenance smell: it papers over the
+  ceremony not persisting across re-pushes, depends on comment order (`.[-1]`) and
+  heredoc delimiters, and `cla.json` was hand-seeded with synthetic timestamps.
+
+### The cleanup
+1. **✅ Applied — allowlist the maintainer-controlled identities.** This pass added
+   `AzeezIsh,tbraun96` to `cla.yml`'s `allowlist` so their (AI-generated) PRs never
+   touch the CLA path. Rationale: the maintainers already own the copyright and have
+   signed — the gate adds nothing on their own PRs, and the allowlist is a stable
+   rule where the `cla.json` state is a mutable file on a side branch. (Left in the
+   working tree for maintainer review before commit — `cla.yml` is a
+   `pull_request_target` security surface, so it does not auto-push.)
+2. **Optional — make the CLA informational, not required.** Keep the bot's comment
+   but drop the CLA status from the required-checks set, so it never *blocks* an AI
+   PR — external human contributors still get asked, and the record is still written.
+3. **Optional — retire the dynamic-signature bolt-on.** Now that maintainer
+   identities are allowlisted they no longer hit that gated path; it remains only to
+   survive re-pushes for external first-time human contributors. Keep it (with the
+   note added to `cla.yml`) or remove it if (2) lands.
+
+Whichever path: keep external first-time human contributors covered (the CLA is a
+real legal instrument — `CLA.md` grants the Enterprise-Edition re-license right,
+and the signing ceremony is the only recorded consent). The goal is to stop
+gating the maintainer's own automation, not to remove the CLA.
+
+## CI convergence — the drift to reconcile
+The maintainer flagged "our PRs and CI are all over the place." The concrete,
+low-risk reconciliations (the convergence pass applies the unambiguous ones to the
+working tree, unpushed, for review):
+
+| Drift | SSOT / fix |
+|-------|-----------|
+| **File-size cap: 250 vs 500.** `AGENTS.md` + the global guide say "≤250 lines"; `CONTRIBUTING.md` + `file-size-cap.yml` enforce **≤500 LoC**. | CI is SSOT → **500**. Fix `AGENTS.md` to `≤500` and cross-reference the workflow. (Applied.) |
+| **Dead links.** `docs/EP2-TROUBLESHOOTING.md` (never created) was referenced by `docs/DEPLOYMENT.md`, `book/src/operations/multi-gpu.md`, and `docs/adr/0007-tp-ep-composition.md`. | All three repointed to `docs/GB10_DEPLOYMENT_GUIDE.md` §7. (Applied.) |
+| **Dead script.** `AGENTS.md`, `.github/pull_request_template.md`, and `book/src/project/contributing.md` all told contributors to run `scripts/check-license-headers.sh`, which didn't exist — CI uses `apache/skywalking-eyes`. | Created `scripts/check-license-headers.sh` as a thin wrapper over that same engine, so all three references now resolve. (Applied.) |
+| **Image provenance.** `release.sh`/`release.yml` pass `--build-arg ATLAS_GIT_SHA` but the Dockerfile had no `ARG`, so it was dropped. | `ARG`+`LABEL org.opencontainers.image.revision` added to `docker/gb10/Dockerfile`. (Applied.) |
+| **Action-version drift.** `release.yml` uses `checkout@v4` + `upload-artifact@v4`; the rest use `checkout@v6` / `upload-artifact@v7` / `download-artifact@v8`. | Pin all workflows to one major per action. (Recommend — touch when next editing release.yml.) |
+| **`cap` is eroding.** The allow-list has grown to ~40 files, several far over 500 (metal_backend 734), which only warn. | Machine-enforce the "rationale + tracking issue per addition" policy, or schedule splits. (Recommend.) |
+| **No image in CI.** `release.yml` ships tarballs only; the image is manual. | The Stage-1→3 self-hosted workflow in `references/pipeline.md` §Closing the gap. |
+| **Required-check trap.** `security.yml`/`docs.yml` deliberately drop the PR path filter so kernel-only PRs aren't left permanently "expected"; `site.yml` still has one. | If `Site / Build` is ever made required, give it the same no-path-filter treatment. (Recommend.) |
+| **Version scheme ×3.** crate `0.1.0` vs image `alpha-2.x`/`3.0.0` vs distro `vX.Y.Z`. | Anchor the image to the git SHA tag (`references/pipeline.md` §Image); let moving tags point at it. |
diff --git a/.claude/skills/atlas-release/references/verify-matrix.md b/.claude/skills/atlas-release/references/verify-matrix.md
new file mode 100644
index 000000000..7fe9d6889
--- /dev/null
+++ b/.claude/skills/atlas-release/references/verify-matrix.md
@@ -0,0 +1,123 @@
+# references/verify-matrix.md — the serve-matrix gate
+
+What "the serve matrix passes" actually means, grounded in the real scripts, plus
+how to make it a **binary pass/fail** (today it isn't — see §Gate).
+
+## The orchestrator: `tests/run_all_models.py`
+Enumerates model×quant as **hand-authored `TestSpec` rounds** (not a cross-product):
+9 single-GPU rounds (each a head/worker pair run in parallel), `EP2_ROUNDS` (122B
+±MTP, 80B-MTP, nemotron-super-120B), `TPEP_ROUNDS` (minimax-m2.7 tp2/ep2),
+`EP4_ROUNDS` (397B, skipped by default). Per spec it:
+
+```bash
+ATLAS_IMAGE=<tag> ATLAS_HEAD_IP=127.0.0.1 python3 tests/run_all_models.py 2>&1 | tee /tmp/atlas-full-run.log
+```
+
+1. **Boot:** `sudo docker run -d --name atlas-test-<label> --gpus all --ipc=host
+   -p PORT:PORT -v <hf>:/root/.cache/huggingface <IMAGE> serve <model>
+   --scheduling-policy slai --max-seq-len 32768 --kv-cache-dtype <fp8|nvfp4>
+   [--speculative --mtp-quantization <q>]`.
+2. **Readiness:** polls `docker logs` every 10s for the substring `Listening on`
+   (600s timeout). ⚠️ It only fails fast if **both** `Error:` *and* `ERROR` appear
+   — a panic with a different string hangs to timeout.
+3. **Warmup:** one throwaway `curl` (HTTP code captured but **ignored** — non-fatal).
+4. **Suite:** `python3 tests/single_gpu_suite.py --base-url <url> --model <m>
+   --output <label>.json [--skip-longctx]`.
+5. Aggregates all JSON into `tests/all_models_results/all_results.json`.
+   **Individual failures do not abort the run** (by design).
+
+## What the suite checks (`tests/single_gpu_suite.py`)
+- **Health** = `GET /v1/models` returns parseable JSON (`Server OK`). On any
+  exception → `[FATAL] Server not reachable`, `exit(1)`. ⚠️ This is the real
+  "health" check — **not** a `GET /health` nor an explicit 200 assert. (Among the
+  serve-matrix suite scripts, only `scripts/dev/coherence_test.py` hits `/health`;
+  several benchmark scripts do too, but the matrix itself uses `/v1/models`.)
+- **Coherence** (`run_coherence_tests`): factual "capital of Japan"→`tokyo`
+  (temp 0), reasoning "120/2"→`60 km/h` (temp 0, LaTeX-regex fallback), creative
+  haiku → repetition-loop check. PASS/FAIL per prompt, repetition-loop = FAIL.
+- **Smoke / codegen** (`run_fibonacci_test`): extract the ```python block, exec in
+  a subprocess, assert first 10 Fibonacci == `[0,1,1,2,3,5,8,13,21,34]`;
+  plain-text fallback. ⚠️ **There is no literal "2+2=4" in the serve matrix** —
+  the maintainer's "2+2=4 smoke" actually lives in `scripts/dev/coherence_test.py`
+  and in `bench/fp8_dgx2_drift/harness/run_tier.sh` (which `exit 4`s if the
+  response lacks `4`). Use the fibonacci exec as the matrix's codegen smoke.
+- **Tool calls** (`run_tool_call_tests`): Weather/Search → assert
+  `message.tool_calls` present and arguments parse as JSON. Known-gap parsers →
+  `N/A` (never hard-fail). ⚠️ Even on supported models a miss is `WARN`, not FAIL.
+- **TPS** (`run_tps_benchmark`): 50/150/300/500 tok, pass if tps>0 and not error.
+- **Long context** (`run_long_context_tests`): needle `PURPLE-DOLPHIN-42` at
+  4k/8k/16k. ⚠️ Returns **PASS even if the needle is missed** — it's an
+  infra-survival check, not a retrieval-accuracy gate.
+
+## The four quality signals (what "verified" should mean to users)
+The serve matrix is the *operational* gate. The **quality** claim behind an image
+rests on four signals; know where each lives and which are in-repo:
+
+| Signal | Script (in-repo unless noted) | Bar |
+|--------|------------------------------|-----|
+| **Coherence** | `scripts/test_coherence.py` (14 sections, `exit 1` on any FAIL: no CJK/Cyrillic, no `<think>`/tool-tag leak, determinism 5×`7*8` byte-identical, tool reliability ≥8/10) · `scripts/dev/coherence_test.py` (10 tests incl. `/health`, 2+2, Paris, temp-diversity, streaming envelope `[DONE]`+`time_to_first_token_ms`, Korean+emoji no U+FFFD) | both `exit 0` |
+| **Agentic** | `scripts/dev/agentic_test.py` (real write/read/run loop → `python3 -m unittest` == ok) · `scripts/test_multiturn_agentic.py` (5-turn w/ opencode+claude-code system prompts from `scripts/fixtures/`) | `exit 0` |
+| **KL-divergence** | `bench/fp8_dgx2_drift/c1_final_logit_overlap.py` (KL nats + top-1 argmax agree + top-K Jaccard) · `tests/metal_kv_kld_compare.py` | offline, needs pre-captured logit dumps — owned by **`/coherence-parity`** |
+| **ST-subset accuracy** (BFCL ST-995) | ⚠️ **NOT in this repo.** External gorilla/`spark-arena-v2` harness. Only in-repo trace is a comment in `kernels/gb10/qwen3.6-27b/MODEL.toml`. | tiny BFCL subset for config A/Bs; full ST-995 only for milestones |
+
+**[TODO / convergence]** ST-subset and the "core-8 trading eval" the maintainer
+named have **no artifact in this repo** (grep for `core-8`/`trading`/
+`st-995` → registry comment only). To make "verified" reproducible by the
+community, either check a thin BFCL/core-8 driver into `tests/` or document the
+external harness + its expected numbers in the deployment guide's methodology
+section. Right now no one can reproduce the accuracy claim from the repo alone.
+
+## The `webserver_ok` gate (the parked coherence gate)
+`webserver_ok` is **not** part of `run_all_models.py`. It's the outcome metric of
+the FP8 agentic-drift harness (`bench/fp8_dgx2_drift/harness/`):
+`score_run.py::webserver_test()` has an agent (opencode / `--claude-code`) write a
+Rust/Axum project, then `cargo build --release`, `cargo run` on an ephemeral port,
+poll `/ping` for ≤15s, and sets `webserver_ok=true` iff the body contains `pong`.
+It **gates** via `run_tier.sh --bail` (`exit 5` on first `cargo_valid!=true` OR
+`webserver_ok!=true`) and `aggregate.py` (exit = `cargo_failures + webserver_failures`).
+
+It is the strongest *agentic* coherence gate the codebase actually enforces, but
+it's coupled to one model (`Qwen/Qwen3.6-35B-A3B-FP8`), the agent binaries, and a
+live container. **To automate it as the release gate**, generalize it into a
+per-image probe: build the standard project once, `curl /ping`→`pong`, over the
+flagship model in the image. Wire its exit code into the Stage-2 verdict below.
+
+## Gate — "verified" as a real exit code, over the *whole* matrix
+`run_all_models.py` **never `exit`s non-zero on a test failure** — it only writes
+per-model JSON to `tests/all_models_results/`. That's why "verified iff the matrix
+passes" used to be a human reading the table. **`tests/gate_results.py`** closes
+it: a pure SBIO scorer that reads those JSON files, applies explicit PCND bars,
+prints a per-model PASS/FAIL, and **exits 0 (ship) / 1 (block)**.
+
+**Coverage is enforced — the gate serves *all*, not just the survivors.** A model
+that crashes at boot writes **no** `<label>.json` (the suite `exit`s before writing
+when the server is unreachable). A glob-only gate would never see it and would
+score the survivors green — a false ship. So `run_all_models.py` writes
+`all_models_results/_manifest.json` (the roster it *planned* to cover, from its
+`planned_specs()` — SSOT), and the gate fails any planned model with no passing
+result. Missing manifest ⇒ hard FAIL unless you pass `--allow-missing-manifest`
+(explicit, loud, coverage-unenforced). `tests/test_gate_results.py` locks the
+"planned-but-absent = FAIL" property in.
+
+The per-model bars (constants at the top of the script, chosen up front):
+- **present** — the model is in the manifest **and** has a results file (booted
+  past the `/v1/models` health check).
+- **coherence** ≥ 2 of 3 probes PASS (tolerates the one temp>0 creative probe).
+- **codegen** — the fibonacci exec smoke PASS.
+- **tools** — at least one real PASS, **or** all `N/A` (known-gap parser). An
+  all-WARN/FAIL result on a supported parser fails.
+- **tps** — mean > 0 (the server produced tokens, not errors).
+
+Validated against fixtures (full-pass / planned-but-missing / below-bar /
+known-gap-all-N/A) in `tests/test_gate_results.py`. Run order for
+`/atlas-release gate`:
+```bash
+ATLAS_IMAGE=<tag> python3 tests/run_all_models.py               # boots + probes matrix -> *.json + _manifest.json
+python3 scripts/test_coherence.py --url http://localhost:8888   # leak/determinism/tools, exit 1 on fail
+python3 tests/gate_results.py                                   # coverage-enforcing verdict, exit 0/1
+```
+All three green = shippable. Record the verdict + the results table next to the
+image tag (`docs/releases/<sha>.md`). **A gate with an unrecorded number is not a
+gate.** (Still parked: folding the `webserver_ok` agentic probe and a per-model
+determinism/leak check directly into `gate_results.py` so one command is the whole
+gate — today `test_coherence.py` covers leak/determinism separately.)
diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml
index 56ea61c60..b2f257b55 100644
--- a/.github/workflows/cla.yml
+++ b/.github/workflows/cla.yml
@@ -16,6 +16,9 @@ jobs:
       statuses: write
       actions: write
     steps:
+      # Retained for EXTERNAL first-time human contributors only: it re-injects a
+      # prior signature comment on re-push so the CLA doesn't have to be re-signed.
+      # Maintainer-controlled identities are allowlisted above and never reach here.
       - name: "Prepare Dynamic Signature Match"
         if: (contains(github.event.comment.body, 'recheck') || contains(github.event.comment.body, 'I have read the CLA Document and I hereby sign the CLA')) || github.event_name == 'pull_request_target'
         env:
@@ -63,7 +66,10 @@ jobs:
           path-to-signatures: 'signatures/version1/cla.json'
           path-to-document: 'https://github.com/${{ github.repository }}/blob/main/CLA.md'
           branch: 'cla-signatures'
-          allowlist: dependabot[bot],renovate[bot],google-labs-jules[bot],claude[bot],google-labs-jules,claude
+          # Maintainer-controlled identities are allowlisted: they own the copyright
+          # and have already signed, so gating their own (AI-generated) PRs adds only
+          # friction. External first-time contributors are still asked to sign.
+          allowlist: dependabot[bot],renovate[bot],google-labs-jules[bot],claude[bot],google-labs-jules,claude,AzeezIsh,tbraun96
           lock-pullrequest-aftermerge: false
           create-file-commit-message: 'chore: setup CLA signatures file'
           signed-commit-message: 'chore: $contributorName signed the CLA in PR #$pullRequestNo'
diff --git a/AGENTS.md b/AGENTS.md
index 37c1dd558..c6e612432 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -35,9 +35,11 @@ release notes in `docs/releases/`.
 - **License is AGPL-3.0-only.** Don't mix in permissive-only code without
   confirming compatibility. `deny.toml` controls what dependency licenses
   are allowed.
-- **Don't regress on models already in the support matrix.** 13 models
-  across Qwen3/Qwen3.5/Qwen3-VL, Nemotron-H, Mistral-Small-4, Gemma-4,
-  MiniMax M2/M2.7. See QUICKSTART.md for the current list.
+- **Don't regress on models already in the support matrix** — Qwen3/Qwen3.5/
+  Qwen3.6/Qwen3-Next/Qwen3-VL, Nemotron-3, Mistral-Small-4, Gemma-4, MiniMax-M2.7.
+  The complete, current model×quant matrix (the SSOT for what's supported) is
+  [`docs/GB10_DEPLOYMENT_GUIDE.md`](docs/GB10_DEPLOYMENT_GUIDE.md) §2; the
+  per-model kernel registry is `kernels/gb10/<model>/MODEL.toml`.
 
 ## Local checks before a PR
 
@@ -47,10 +49,12 @@ The commands CI will run:
 # 1. Formatting
 cargo fmt --all -- --check
 
-# 2. Lints (the build-script gate lets clippy run without CUDA on the host)
-ATLAS_SKIP_BUILD=1 cargo clippy --workspace --tests --all-features -- -Dwarnings
+# 2. Lints (the build-script gate lets clippy run without CUDA on the host;
+#    matches ci.yml — deny-warnings comes from [workspace.lints], not a flag)
+ATLAS_SKIP_BUILD=1 CUDARC_CUDA_VERSION=13000 cargo clippy --workspace --tests
 
-# 3. License headers
+# 3. License headers (SPDX AGPL-3.0-only line 1; wraps the same apache/skywalking-eyes
+#    engine CI runs against .licenserc.yaml):
 bash scripts/check-license-headers.sh
 
 # 4. Typos
@@ -147,7 +151,7 @@ To ensure high code quality, all agents contributing to Atlas must strictly adhe
 ### Core Directives
 - **Minimal Edits:** Make the smallest edit necessary—sufficient but not excessive.
 - **TDD & Testing:** Test-driven development is required. Minimize test mocking; maximize production code coverage. Never add test-specific workarounds to production paths.
-- **File Size:** Keep files ≤250 lines. Split larger files via exact piecewise copy when necessary.
+- **File Size:** Keep Rust source files ≤500 LoC — this is the CI-enforced cap (`.github/workflows/file-size-cap.yml` is the SSOT). Split larger files into sub-modules per the Atlas idiom (see `crates/spark-model/src/layers/qwen3_attention/` for the compute-heavy template, `crates/spark-model/src/weight_loader/` for the variant-dispatch template).
 - **Security:** Write secure code adhering to OWASP, CWE, and NIST standards.
 
 ### The "Big Three" Invariants (Always Apply)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d84c286b5..810305dd0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,8 +70,18 @@ cargo bench -p atlas-spark-bench
 
 CI enforces (all GPU-free): `fmt`, `clippy`, `cargo test --workspace`
 (unit tests + non-`#[ignore]` integration tests), license-headers,
-typo check, `cargo-deny`, file-size cap. PRs fail without an authoring
-maintainer needing GPU access — the kernel work happens locally.
+typo check, `cargo-deny`, file-size cap (≤500 LoC per `crates/**/*.rs`).
+PRs fail without an authoring maintainer needing GPU access — the kernel
+work happens locally.
+
+**CI-green is not the same as shippable.** The GPU-free CI proves the code
+compiles and is hygienic; it does *not* boot a model. An image is only
+"verified" once it passes the **serve matrix** (`tests/run_all_models.py` +
+the coherence gate). Deploying on GB10? Read
+[`docs/GB10_DEPLOYMENT_GUIDE.md`](docs/GB10_DEPLOYMENT_GUIDE.md) for the model
+compatibility matrix, quant selection, and known-issue workarounds. Cutting an
+image? The build → verify → publish pipeline is the `atlas-release` skill
+(`.claude/skills/atlas-release/`).
 
 ### Code Formatting
 
diff --git a/README.md b/README.md
index 9798af8c7..434b2ecb0 100644
--- a/README.md
+++ b/README.md
@@ -241,6 +241,8 @@ We have to walk before we can run. Today's Atlas is targeted at a single hardwar
 
 This is a starting point, not a destination. The plug-and-play design above exists precisely so that AMD, Apple Silicon, Intel, and the next round of Blackwell parts can land here as community contributions, and so that the Llama 4s and DeepSeek V4s of next quarter slot in the same way the Qwens did this quarter. We did the hard part — bolting in the abstractions while bringing up the first twelve targets — so that adding the thirteenth is a weekend, not a quarter.
 
+> **New to Atlas on a Spark?** The [**GB10 Deployment & Compatibility Guide**](docs/GB10_DEPLOYMENT_GUIDE.md) is the one page to read first: which model and quant fit your box and your goal, what to do when it OOMs, the known gotchas, and what "verified" means — then it hands you the exact recipe. If you're deciding *what to run*, start there.
+
 <a id="performance"></a>
 
 ## ⚡ Performance
diff --git a/book/src/operations/multi-gpu.md b/book/src/operations/multi-gpu.md
index ac89d251b..f6a06c6dc 100644
--- a/book/src/operations/multi-gpu.md
+++ b/book/src/operations/multi-gpu.md
@@ -162,4 +162,4 @@ TP for dense models on future multi-GPU hardware is on the roadmap; today there'
 - `crates/spark-model/src/layers/minimax_moe.rs` (EP=2 dispatch example).
 - `kernels/gb10/minimax-m2-229b/nvfp4/moe_dispatch.cu` — kernel.
 - `docs/design/ep2-token-dispatch-design.md` — design note.
-- `docs/EP2-TROUBLESHOOTING.md` — field-tested troubleshooting.
+- `docs/GB10_DEPLOYMENT_GUIDE.md` §7 — field-tested EP=2 troubleshooting.
diff --git a/docker/gb10/Dockerfile b/docker/gb10/Dockerfile
index 65e4aa922..884a027d5 100644
--- a/docker/gb10/Dockerfile
+++ b/docker/gb10/Dockerfile
@@ -46,6 +46,12 @@ FROM nvidia/cuda:13.0.0-runtime-ubuntu24.04@sha256:95318efecfd68ab3d109da5277863
 
 LABEL org.opencontainers.image.licenses="AGPL-3.0-only"
 
+# Stamp the source commit into the image so ":latest" provenance is answerable:
+#   docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}' <tag>
+# Passed by scripts/release.sh and the atlas-release skill via --build-arg ATLAS_GIT_SHA.
+ARG ATLAS_GIT_SHA=unknown
+LABEL org.opencontainers.image.revision="${ATLAS_GIT_SHA}"
+
 # NCCL for multi-GPU (EP=2), RDMA userspace for RoCE transport.
 # NCCL ≥ 2.28 is required for `ncclMemAlloc`/`ncclMemFree` symmetric memory
 # windows (substrate for device-API fused allreduce kernels). The base
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 34bcf69ca..9f0e65903 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -99,7 +99,14 @@ For long contexts (>32K tokens) the on-device KV cache fills fast. Atlas
 can evict cold blocks to NVMe and stream them back as needed:
 
 ```bash
-docker run ... avarok/atlas-gb10:latest \
+# High-speed swap uses io_uring — it REQUIRES the two container flags below
+# (--security-opt seccomp=unconfined --ulimit memlock=-1). Without them the
+# io_uring setup fails and swap silently does nothing.
+docker run -d --gpus all --ipc=host -p 8888:8888 \
+  --security-opt seccomp=unconfined --ulimit memlock=-1 \
+  -v ~/.cache/huggingface:/root/.cache/huggingface \
+  -v /mnt/fast-nvme/atlas-kv:/mnt/fast-nvme/atlas-kv \
+  avarok/atlas-gb10:latest \
   serve <model> \
     --max-seq-len 65536 \
     --high-speed-swap \
@@ -151,5 +158,5 @@ you build one — happy to merge.
 ## See also
 
 - [`QUICKSTART.md`](../QUICKSTART.md) — copy-paste recipes for each supported model.
-- [`docs/EP2-TROUBLESHOOTING.md`](EP2-TROUBLESHOOTING.md) — diagnosing multi-rank issues.
+- [`docs/GB10_DEPLOYMENT_GUIDE.md`](GB10_DEPLOYMENT_GUIDE.md) — §7 diagnoses multi-rank (EP=2) issues; §2 is the model×quant compatibility matrix; §4 is the OOM / context ladder.
 - [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) — what's running inside the binary.
diff --git a/docs/GB10_DEPLOYMENT_GUIDE.md b/docs/GB10_DEPLOYMENT_GUIDE.md
new file mode 100644
index 000000000..9521d7423
--- /dev/null
+++ b/docs/GB10_DEPLOYMENT_GUIDE.md
@@ -0,0 +1,293 @@
+# Atlas on DGX Spark GB10 — Deployment & Compatibility Guide
+
+New to Atlas on a Spark? Start here. Read this **before** you pick a model: which
+model and quant fit your box and your goal, what to do when it OOMs, and the
+gotchas that cost an evening — then it points you at the exact copy-paste recipe.
+
+Selection + troubleshooting only. It doesn't repeat runtime mechanics documented
+elsewhere:
+
+| For… | Read |
+|------|------|
+| Copy-paste per-model `docker run` recipes | [`QUICKSTART.md`](../QUICKSTART.md) · the `@atlas` [recipe registry](https://github.com/Avarok-Cybersecurity/atlas-recipes) |
+| Deployment *modes* (single-GPU, EP=2/TP=2, NVMe swap) | [`docs/DEPLOYMENT.md`](DEPLOYMENT.md) |
+| The native binary (no Docker) | [`docs/DISTRIBUTION.md`](DISTRIBUTION.md) |
+| Adding a new model/hardware target | [`docs/HARDWARE.md`](HARDWARE.md) · [`AGENTS.md`](../AGENTS.md) |
+
+**Serve config SSOT:** the `defaults:` block of the matching
+[`atlas-recipes`](https://github.com/Avarok-Cybersecurity/atlas-recipes) recipe is
+the authoritative launch config for each model — continuously tuned, pinning the
+flags that hold the quality gates. **If a flag here and a recipe disagree, the
+recipe wins.** This guide is the *why*; the recipe is the exact *what*.
+
+---
+
+## 1. The box
+
+| | |
+|---|---|
+| GPU | NVIDIA GB10 (Grace-Blackwell), compute capability **sm_121** (12.1) |
+| GPU memory | **119.7 GB** unified (LPDDR5X, ~273 GB/s) |
+| CPU arch | aarch64 |
+| **Min driver** | **580** (CUDA 13.0). The engine embeds PTX and re-JITs to your SM at launch — no `nvcc` at runtime, but the driver floor is hard. |
+| Multi-node | 2× DGX Spark over RoCEv2 (`enp1s0f0np0`) for EP=2 |
+| Image | `avarok/atlas-gb10:latest` — one **multi-model** binary; the right kernel set is auto-selected at startup from the model's `config.json` |
+
+**Prerequisites**, in order:
+1. NVIDIA driver ≥ 580 — verify: `nvidia-smi` shows CUDA 13.0+. (Native binary
+   fails fast below the floor; bypass at your own risk with `ATLAS_SKIP_DRIVER_CHECK=1`.)
+2. NVIDIA Container Toolkit (for the Docker path).
+3. A clean GPU before launch: `nvidia-smi` should show no other process holding
+   VRAM. Atlas sizes its KV cache from *free* memory at boot.
+4. HuggingFace cache mounted (`-v ~/.cache/huggingface:/root/.cache/huggingface`).
+   Weights download on first run — **plan disk**: checkpoints range ~15 GB (27–35B
+   NVFP4) to ~81 GB (122B). See §5 for the one download gotcha.
+5. EP=2 only: passwordless SSH between the two nodes and the RoCE NIC up (§7).
+
+---
+
+## 2. Model × quant compatibility matrix
+
+Every model below runs on the **same** `avarok/atlas-gb10:latest` image. "Quant"
+is the **weight** format of the HuggingFace checkpoint you point `serve` at; the
+nvfp4 kernel bundle carries native FP8 and BF16 paths too, so an FP8 checkpoint
+serves correctly on the same image (runtime gate:
+`nvfp4↔nvfp4 · nvfp4→fp8 · nvfp4→bf16`).
+
+`tok/s` is a single-stream p50 approximation (ISL≈128, conc=1) from the recipe
+catalogue — a feel, not a benchmark. "Ctx" is a **practical** single-Spark ceiling
+at conc=1; it trades against batch size and KV dtype (see §4).
+
+### Single-node (fits one GB10)
+
+| Model | HuggingFace id | Params (total/active) | Weight quant | Architecture | ~tok/s | Practical ctx | Notes |
+|-------|----------------|----------------------|--------------|--------------|--------|---------------|-------|
+| **Qwen3.6-35B-A3B** ⭐ | `Qwen/Qwen3.6-35B-A3B-FP8` | 35B / 3B | FP8 | hybrid SSM (GDN) + attn + MoE | ~157 (nvfp4) | **64K** | **Daily-driver / agentic coding.** MTP K=2, DFlash drafter `z-lab/…-DFlash`, live tool-call streaming |
+| **Qwen3.6-27B** | `Qwen/Qwen3.6-27B-FP8` | 27B dense | FP8 | hybrid attn + GDN + dense FFN | ~15 | 24K | Dense reasoning; MTP off; DFlash `z-lab/Qwen3.6-27B-DFlash` |
+| **Qwen3.5-35B-A3B** | `Sehyo/Qwen3.5-35B-A3B-NVFP4` | 35B / 3B | NVFP4 | hybrid GDN + attn + MoE | ~131 | 24K | MTP K=2. (⚠️ HF-id drift — see below) |
+| **Qwen3.5-27B** | `Kbenkhaled/Qwen3.5-27B-NVFP4` | 27B dense | NVFP4 | hybrid attn + SSM, dense FFN | ~14 | 24K | Dense; MTP off |
+| **Qwen3-Next-80B-A3B** | `nvidia/Qwen3-Next-80B-A3B-Instruct-NVFP4` | 80B / 3B | NVFP4 | hybrid SSM + MoE (512 experts) | ~74–104 | 8K | MTP; NVIDIA reference checkpoint |
+| **Qwen3-Coder-Next** | `Qwen/Qwen3-Coder-Next-FP8` | 80B / 3B | FP8 | hybrid GDN + attn + MoE (same as Qwen3-Next) | ~58 | 16K | **Coding-specialized.** `--kv-cache-dtype bf16` (FP8 KV incompatible), `--ssm-cache-slots 0`, `--oom-guard-mb 1024`, `qwen3_coder` parser. Agentic quality degrades after ~5–8 tool turns (model limitation) |
+| **Qwen3-VL-30B-A3B** | `ig1/Qwen3-VL-30B-A3B-Instruct-NVFP4` | 30B / 3B | NVFP4 | **vision** + full-attn MoE | ~97 | 32K | Image input; no thinking mode; MTP off |
+| **Nemotron-3-Nano-30B-A3B** | `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-NVFP4` | 30B / 3.5B | NVFP4 (mixed) | mamba2 + MoE + attn | ~88 | 16K | ModelOpt mixed-precision (nvfp4 + few FP8) |
+| **Nemotron-3-Super-120B-A12B** | `nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4` | 120B / 12B | NVFP4 (mixed) | mamba2 + latent-MoE + attn | ~24 | 64K | LatentMoE; loop-watchdog on. Fits one GB10 |
+| **Mistral-Small-4-119B** | `mistralai/Mistral-Small-4-119B-2603-NVFP4` | 119B / 6.5B | NVFP4 | MLA + MoE | ~33 | 8K | **`--kv-cache-dtype bf16` required** (FP8/NVFP4 KV breaks the MLA latent); tool parser is a known gap; registry-only |
+| **Gemma-4-31B** | `nvidia/Gemma-4-31B-IT-NVFP4` | 31B dense | NVFP4 | dense, sliding+full attn | ~9 | 16K | Vision; `gemma4` tool parser; registry-only (no per-model image) |
+| **Gemma-4-26B-A4B** | `bg-digitalservices/Gemma-4-26B-A4B-it-NVFP4A16` | 26B / 4B | **NVFP4A16** | MoE GeGLU | ~67 | 16K | 4-bit weights / 16-bit activations; registry-only |
+
+### Large models (single-node tight, or scale out to EP=2 / EP=4)
+
+| Model | HuggingFace id | Params (total/active) | Quant | Topology | ~tok/s | Notes |
+|-------|----------------|----------------------|-------|----------|--------|-------|
+| **Qwen3.5-122B-A10B** | `Sehyo/Qwen3.5-122B-A10B-NVFP4` | 122B / 10B | NVFP4 | single (tight) **or** EP=2 | ~33 single / ~51 EP=2 | 256 experts; MTP K=2. Single-node needs the tight-KV recipe (§4) |
+| **MiniMax-M2.7** | `lukealonso/MiniMax-M2.7-NVFP4` | 229B / ~10B | NVFP4 | **EP=2** (2 nodes, TP=1) | — | 256-expert sigmoid MoE; BF16 KV bring-up, no MTP; registry-only |
+| **Qwen3.5-397B-A17B** | `nvidia/Qwen3.5-397B-A17B-NVFP4` | 397B / 17B | NVFP4 | **EP=4 (4 nodes) only** | — | ~200 GB weights; single/2-node OOM at preflight |
+
+**"registry-only"** = the kernels are in the multi-model image and it serves fine,
+but there's no turnkey per-model `docker/gb10/<m>/` Dockerfile — run it against
+`avarok/atlas-gb10:latest` with the recipe flags.
+
+**⚠️ SSOT drifts to be aware of** (registry `MODEL.toml` vs the deployable recipe
+id; tracked for reconciliation — the recipe id is what to pull):
+- **Qwen3.5-35B:** registry says `Sehyo/…`, one Dockerfile example says
+  `Kbenkhaled/…`. Both are NVFP4 35B-A3B builds; prefer the recipe's id — if one
+  404s, try the other.
+- **Qwen3.6-27B:** registry `MODEL.toml` says `Qwen/Qwen3.6-27B`, but the recipe
+  and Dockerfile serve `Qwen/Qwen3.6-27B-FP8` — pull the `-FP8` checkpoint.
+- **MiniMax-M2.7:** registry `MODEL.toml` (`minimax-m2-229b`) points at the base
+  `MiniMaxAI/MiniMax-M2.7`, while the recipe uses the quantized
+  `lukealonso/MiniMax-M2.7-NVFP4` — use the recipe's NVFP4 id.
+- **`qwen3.6-*` folders say `nvfp4/` but ship FP8 checkpoints** — harmless (the
+  nvfp4 bundle runs FP8), but don't let the folder name mislead you.
+
+**"Practical ctx"** is a conc=1 comfort ceiling — deliberately different from
+[`QUICKSTART.md`](../QUICKSTART.md)'s conservative maxima and from the higher
+`--max-seq-len` some recipes set (the flagship pushes 64K). Gauge headroom with it;
+launch with the recipe's `max_model_len`; trade context against batch/KV via §4.
+
+---
+
+## 3. Pick your recipe (goal → model)
+
+| Your goal | Start with | Why |
+|-----------|-----------|-----|
+| **Agentic coding, tool use, daily driver** | `Qwen3.6-35B-A3B-FP8` | 64K ctx, MTP K=2, live tool-call streaming, `qwen3_coder` parser — the tuned flagship |
+| **Max single-stream throughput** | `Qwen3.6-35B-A3B` (nvfp4, ~157) or `Qwen3.5-35B-A3B-NVFP4` (~131) | NVFP4 weights hit GB10's native FP4 MMA; MTP amplifies |
+| **Vision / image input** | `Qwen3-VL-30B-A3B-Instruct-NVFP4` | The vision model; ~97 tok/s |
+| **Biggest quality you can host** | `Qwen3.5-122B-A10B-NVFP4` on **EP=2** (2 Sparks) | 122B/10B across two nodes, ~51 tok/s |
+| **Long context on one box** | `Qwen3.6-35B-A3B-FP8` @ 64K, add NVMe swap for more | FP8 KV + `--kv-high-precision-layers auto` fits 64K; swap extends it (§4) |
+| **Smallest / dense reasoning** | `Qwen3.5-27B-NVFP4` or `Qwen3.6-27B-FP8` | Dense hybrids; ~14–15 tok/s, low VRAM |
+
+Then copy that model's recipe from [`QUICKSTART.md`](../QUICKSTART.md) or run
+`sparkrun run @atlas/<recipe-stem>`. Deviate from the flagship only with a reason —
+the recipe defaults encode gate-passing choices.
+
+---
+
+## 4. Quant selection & the OOM / context ladder
+
+### Weight quant — which checkpoint to pull
+| Weight quant | What it is | Choose when |
+|--------------|-----------|-------------|
+| **NVFP4** | 4-bit (E2M1) weights + FP8 block scales; native GB10 FP4 MMA | Default. Fastest decode; smallest weights. Most models ship NVFP4. |
+| **FP8** | 8-bit weights, native on GB10 | Higher-precision path; the `qwen3.6` flagship line. Slightly larger, very stable. |
+| **NVFP4A16** | 4-bit weights, **16-bit activations** | Only where the checkpoint ships it (Gemma-4-26B). Higher activation precision, a touch slower. |
+| **BF16** | reference | Rarely — largest footprint; a numeric reference, not a deployment target. |
+
+You don't choose weight quant with a flag — you choose it by which **HuggingFace
+checkpoint** you point `serve` at (the id in §2). The image serves all three.
+
+### KV-cache dtype — `--kv-cache-dtype` (independent of weight quant)
+KV precision trades context length / batch against fidelity. Six options:
+
+| `--kv-cache-dtype` | Bits/elem | Notes |
+|--------------------|-----------|-------|
+| `bf16` | 16 | Reference precision; most KV memory. Bring-up default for new models. |
+| `fp8` | 8 | The workhorse. Pair with `--kv-high-precision-layers auto` to keep the sensitive layers in bf16. Flagship uses this at 64K. |
+| `turbo8` | 8 | FP8 variant with a different scale layout. |
+| `nvfp4` | 4 | Half the memory of fp8 — the throughput recipes (35B) use this. |
+| `turbo4` / `turbo3` | 4 / ~3 | Aggressive low-bit KV; most context per GB, most fidelity risk. |
+
+Rule of thumb: **`fp8` + `--kv-high-precision-layers auto`** for quality-sensitive
+/ long-context work; **`nvfp4`** when you're chasing tok/s or context and the model
+tolerates it (the 35B NVFP4 recipes do). New/unproven model → start `bf16`, then
+tighten.
+
+### If you OOM — the lever ladder (apply in order)
+A GB10 has ~120 GB. Budget ≈ *weights + CUDA/NCCL workspace + dequant scratch + KV
+(grows with `max-seq-len × max-num-seqs`)*. When boot fails to allocate or you see
+**`KV cache can hold at most 0 concurrent sequence(s)`**, walk this ladder:
+
+1. **Lower `--gpu-memory-utilization`** first if it fails *during* boot (workspace
+   starve): `0.85` default → `0.70`. If you have headroom and nothing else on the
+   GPU, raise toward `0.92` for more KV.
+2. **Cut `--max-seq-len`** — KV scales linearly with it (64K → 16K is a 4× KV cut).
+3. **Cut `--max-num-seqs`** — fewer concurrent sequences = less KV. On the tight
+   122B single-node recipe this is `--max-num-seqs 4`.
+4. **Drop KV to a lower-bit dtype** — `fp8` → `nvfp4` halves KV memory.
+5. **Free SSM slots** — `--ssm-cache-slots 0` reclaims the Mamba/GDN state pool on
+   hybrid models when you need the last GB (tight 122B recipe uses this).
+6. **`--oom-guard-mb 1024`** — reserves a guard band so the allocator fails clean
+   instead of the driver killing the process mid-run.
+7. **Still short? Go multi-node (EP=2)** for the 120B-class models, or **NVMe
+   high-speed swap** to spill cold KV to disk (§`DEPLOYMENT.md` §3 — remember the
+   container flags in §5 below).
+
+---
+
+## 5. Known issues & workarounds (consolidated)
+
+The gotchas that cost people an evening, in one place:
+
+1. **"No MTP weights found" / missing `extra_weights.safetensors` (35B under a
+   mounted HF cache).** Volume-mounting `~/.cache/huggingface` can break the
+   symlinked extra-weights file. **Fix:** download to a real dir and serve from a
+   path:
+   ```bash
+   huggingface-cli download Sehyo/Qwen3.5-35B-A3B-NVFP4 --local-dir /models/qwen3.5-35b
+   docker run ... -v /models/qwen3.5-35b:/model avarok/atlas-gb10:latest \
+     serve --model-from-path /model --speculative --num-drafts 1
+   ```
+2. **High-speed swap silently does nothing / permission errors.** `io_uring`
+   needs relaxed container security. Add **`--security-opt seccomp=unconfined
+   --ulimit memlock=-1`** to the `docker run` (this is required for
+   `--high-speed-swap`, and is easy to miss — it's not in `DEPLOYMENT.md §3`).
+3. **EP=2 crashes with an SSM intermediate-buffer error.** Rank 0 and rank 1 must
+   launch with **identical** `--speculative` / `--mtp-quantization` / `--num-drafts`
+   flags — otherwise rank 0's verify lands on a layer rank 1 never allocated for.
+   `scripts/start-ep2.sh` mirrors them; if you hand-write two `docker run`s, copy
+   the spec flags verbatim. (See §7.)
+4. **Native binary: "driver too old" / glibc errors.** The tarball fails fast below
+   driver 580 (CUDA 13.0) and is built against glibc 2.39 (Ubuntu 24.04). Older
+   distro → use the Docker image. Emergency bypass: `ATLAS_SKIP_DRIVER_CHECK=1`.
+5. **First request hangs for 5–30 s.** That's cold-start CUDA-graph capture +
+   autotuner + prefix-cache init, not a hang. Eliminate it with `--warmup-prompt`.
+6. **Garbage / incoherent output.** Two usual causes: (a) **tool-parser mismatch** —
+   the parser must match the model (`qwen3_coder` for Qwen3.5/3.6, `hermes` for
+   some, `gemma4` for Gemma-4); pass `--tool-call-parser` explicitly in production
+   rather than relying on auto-resolution. (b) an aggressive **KV dtype** the model
+   doesn't tolerate — step it up (`turbo3`→`nvfp4`→`fp8`). If neither, it's a bug —
+   **never assume the model is at fault; file it** (`AGENTS.md` failure-modes).
+7. **`KV cache can hold at most 0 concurrent sequence(s)`.** You asked for more KV
+   than fits — walk the §4 ladder (this fires most on single-node 122B).
+
+---
+
+## 6. Health, observability & a working smoke test
+
+```bash
+curl http://localhost:8888/v1/models        # loaded model — the liveness check the test suite uses
+curl http://localhost:8888/health           # liveness
+curl http://localhost:8888/metrics          # Prometheus exposition
+# Coherence smoke — deterministic, should print exactly "4":
+curl -s http://localhost:8888/v1/chat/completions -H 'Content-Type: application/json' -d \
+  '{"model":"atlas","messages":[{"role":"user","content":"What is 2+2? Reply with just the number."}],"max_tokens":16,"temperature":0}'
+```
+Logs go to stdout (`docker logs <container>`); `RUST_LOG` controls verbosity
+(`info` default, `debug` for kernel traces).
+
+---
+
+## 7. EP=2 multi-node troubleshooting
+
+(This section is the target of the `DEPLOYMENT.md` cross-reference.) Two GB10
+Sparks, one OpenAI endpoint on rank 0. Launch via the canonical launcher:
+
+```bash
+HEAD_IP=10.10.10.1 WORKER_IP=10.10.10.2 \
+  bash scripts/start-ep2.sh Sehyo/Qwen3.5-122B-A10B-NVFP4
+```
+
+What it sets (and you must replicate if you hand-roll `docker run`s):
+- `NCCL_SOCKET_IFNAME=enp1s0f0np0` — the GB10 RoCE NIC. **Change this for
+  non-DGX-Spark hardware** or NCCL binds the wrong interface and hangs.
+- `NCCL_NVLS_ENABLE=0` (no NVLink), `NCCL_NET_GDR_LEVEL=0` / `NCCL_NET_GDR_C2C=0` /
+  `NCCL_DMABUF_ENABLE=0` (GB10 has no GDS), `NCCL_PROTO=Simple`, `NCCL_ALGO=Ring`.
+- Rank 0 → `HEAD_IP:8888`, rank 1 → `WORKER_IP:8889`, both `--master-addr HEAD_IP
+  --master-port 29500`.
+
+Failure modes:
+| Symptom | Cause / fix |
+|---------|-------------|
+| Boot hangs at "waiting for worker" | Passwordless SSH between nodes not set up, or worker container never started. Check `docker logs` on **both** ranks. |
+| NCCL init timeout / `unhandled system error` | `NCCL_SOCKET_IFNAME` wrong for your NIC, or the RoCE fabric down (`ibstat`, `ip link`). Confirm both nodes see `10.10.10.x`. |
+| SSM intermediate-buffer / verify-layer error | Spec-decode flag asymmetry between ranks — see Known Issue #3. |
+| Rank 1 serves nothing on 8889 | Expected — the API is served **only** from rank 0. Point clients at `HEAD_IP:8888`. |
+| Port already in use | A stale container/`spark serve` on 8888/8889/29500. `docker ps`, stop it, retry. |
+
+Topology quick pick: **EP=2** (`--ep-size 2 --tp-size 1`) for MoE expert sharding
+across two nodes — this is what the 122B and MiniMax-M2.7 recipes use. **TP+EP**
+(`--tp-size 2 --ep-size 2`, a 4-rank layout) is only for a model that must shard
+*both* attention and experts; none of the current 2-node recipes need it. Pure TP=2
+is rare and OOM-prone for these models. The 397B needs **EP=4** (4 nodes).
+
+---
+
+## 8. What "verified" means (so you can trust an image)
+
+An Atlas image is only cut after it passes the **serve matrix** — every model×quant
+in §2 boots, stays coherent, and holds four quality signals. If you're evaluating
+Atlas or reproducing a claim, these are the signals and where they live:
+
+| Signal | What it proves | How it's checked |
+|--------|----------------|------------------|
+| **Coherence** | No CJK/tag leakage, greedy determinism, tool reliability ≥8/10, valid streaming | `scripts/test_coherence.py`, `scripts/dev/coherence_test.py` |
+| **Agentic** | Real multi-turn tool loops build & pass unit tests | `scripts/dev/agentic_test.py`, `scripts/test_multiturn_agentic.py` |
+| **KL-divergence** | Logits stay faithful to a BF16 reference (argmax agreement, KL nats) | `bench/fp8_dgx2_drift/` + the `/coherence-parity` skill |
+| **ST-subset accuracy** | Tool-calling accuracy on a BFCL single-turn subset | external gorilla / `spark-arena` harness (see note) |
+
+The full gate spec — exactly what each script asserts, and how the release
+pipeline turns it into a pass/fail before an image ships — is in the maintainer
+`atlas-release` skill (`references/verify-matrix.md`). *Note:* the ST-subset /
+BFCL accuracy harness currently runs outside this repo; reproducing that specific
+number needs the external gorilla setup. Everything else in the table runs from a
+clean checkout against a running server.
+
+---
+
+## See also
+- [`QUICKSTART.md`](../QUICKSTART.md) — the copy-paste recipes this guide routes to.
+- [`docs/DEPLOYMENT.md`](DEPLOYMENT.md) — deployment modes + NVMe swap internals.
+- [`docs/DISTRIBUTION.md`](DISTRIBUTION.md) — the native (no-Docker) binary.
+- [`CONTRIBUTING.md`](../CONTRIBUTING.md) · [`AGENTS.md`](../AGENTS.md) — building & contributing.
+- [`atlas-recipes`](https://github.com/Avarok-Cybersecurity/atlas-recipes) — the serve-config SSOT (`sparkrun run @atlas/<recipe>`).
diff --git a/docs/adr/0007-tp-ep-composition.md b/docs/adr/0007-tp-ep-composition.md
index 8dddbbf3c..00ede34e4 100644
--- a/docs/adr/0007-tp-ep-composition.md
+++ b/docs/adr/0007-tp-ep-composition.md
@@ -53,7 +53,7 @@ Implementation:
 - The launcher (`scripts/start-ep2.sh`) sets the NCCL env identically on
   both ranks. Mismatched flags between rank 0 and rank 1 (e.g. one rank
   enables `--speculative` and the other doesn't) produce SSM
-  intermediate-buffer errors at runtime — see `docs/EP2-TROUBLESHOOTING.md`.
+  intermediate-buffer errors at runtime — see `docs/GB10_DEPLOYMENT_GUIDE.md` §7.
 
 The EP+TP overlap case (TP=2, EP=2) shipped in `project_tp_phase8a_complete`
 with the unified-layout MoE rewrite, gated behind
diff --git a/docs/releases/README.md b/docs/releases/README.md
new file mode 100644
index 000000000..ad84a5821
--- /dev/null
+++ b/docs/releases/README.md
@@ -0,0 +1,15 @@
+# Release notes & shipped-image record
+
+One file per shipped image so `:latest`'s provenance is answerable at a glance.
+When `/atlas-release publish` promotes a verified image (see
+[`.claude/skills/atlas-release`](../../.claude/skills/atlas-release/SKILL.md)),
+record it here as `docs/releases/<git-sha>.md` with:
+
+- the **git SHA** the image was built from (also stamped into the image as
+  `org.opencontainers.image.revision` — `docker inspect` it),
+- the moving tags it received (`:latest` / `:dev` / `:nightly` / `:<semver>`),
+- the **serve-matrix verdict** (`tests/gate_results.py` PASS + the results table),
+- notable engine changes since the previous shipped SHA.
+
+This closes the "is `:latest` the merged code?" gap: the answer is the newest file
+here, cross-checked against the image's revision label.
diff --git a/scripts/check-license-headers.sh b/scripts/check-license-headers.sh
new file mode 100755
index 000000000..e4ccaa3f1
--- /dev/null
+++ b/scripts/check-license-headers.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# SPDX license-header check — the SAME engine CI runs, locally.
+#
+# CI (.github/workflows/ci.yml, job `license-headers`) uses the
+# apache/skywalking-eyes `header` action against `.licenserc.yaml` (SSOT for the
+# checked paths + the required `SPDX-License-Identifier: AGPL-3.0-only` line).
+# This wrapper invokes that same engine via its published container image so a
+# local pass matches CI exactly — no separate rule to drift.
+#
+# Usage:
+#   bash scripts/check-license-headers.sh          # check (fails on missing headers)
+#   bash scripts/check-license-headers.sh fix      # insert missing headers in place
+set -euo pipefail
+
+MODE="${1:-check}"          # check | fix
+IMAGE="ghcr.io/apache/skywalking-eyes/license-eye"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "error: docker is required to run the skywalking-eyes license engine." >&2
+  echo "       Install docker, or run the check in CI. The rule (SSOT): every" >&2
+  echo "       crates/**/*.rs and kernels|cuda_kernels/**/*.{cu,cuh,h,hpp,cpp}" >&2
+  echo "       must start with 'SPDX-License-Identifier: AGPL-3.0-only'." >&2
+  exit 2
+fi
+
+exec docker run --rm -v "${REPO_ROOT}:/repo" -w /repo \
+  "${IMAGE}" -c .licenserc.yaml header "${MODE}"

From f87bcfa71955cfd839841d6705395b72871993cb Mon Sep 17 00:00:00 2001
From: Azeez Ishaqui <debaterishaqui@gmail.com>
Date: Sun, 5 Jul 2026 15:54:17 -0400
Subject: [PATCH 3/3] tests: baseline-managed tps regression bar in the release
 gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The gate's tps bar was liveness-only (avg > 0), so a real perf regression
(e.g. tps dropping 40%) passed as long as the number stayed positive. Add a
committed-baseline regression check: tests/baselines/<label>.json records the
blessed tokens/sec, and a run more than TPS_TOLERANCE (10%) below it fails.

- verdict() stays pure — takes the baseline dict as an argument (SBIO).
- No baseline for a label => liveness-only with a loud note, not a silent pass;
  --require-baselines makes a missing baseline a hard fail for a milestone (PCND:
  the stricter bar is explicit opt-in, mirroring --allow-missing-manifest).
- gate_results.py --update-baselines writes {"tps": avg} per label from the
  present results for a deliberate, reviewed refresh (exit 0, no gating).
- Roster stays the single manifest SSOT in run_all_models.py; baselines key to
  those labels — no second matrix.
- tests/test_gate_results.py extended to 23 tests (regression / within-tolerance
  / no-baseline / require-baselines / dead-server-first / update round-trip).

Baseline-snapshot approach proposed by @Sujimoshi in #253; folded into the
existing gate to keep one SSOT rather than a parallel pytest suite.

Co-Authored-By: Igor Solomakha <sujimoshi@users.noreply.github.com>
---
 .../atlas-release/references/verify-matrix.md |  14 +-
 tests/baselines/.gitkeep                      |   0
 tests/baselines/README.md                     |  20 +++
 tests/gate_results.py                         | 150 ++++++++++++++++--
 tests/test_gate_results.py                    |  70 ++++++++
 5 files changed, 235 insertions(+), 19 deletions(-)
 create mode 100644 tests/baselines/.gitkeep
 create mode 100644 tests/baselines/README.md

diff --git a/.claude/skills/atlas-release/references/verify-matrix.md b/.claude/skills/atlas-release/references/verify-matrix.md
index 7fe9d6889..5dcbb10e5 100644
--- a/.claude/skills/atlas-release/references/verify-matrix.md
+++ b/.claude/skills/atlas-release/references/verify-matrix.md
@@ -106,15 +106,21 @@ The per-model bars (constants at the top of the script, chosen up front):
 - **codegen** — the fibonacci exec smoke PASS.
 - **tools** — at least one real PASS, **or** all `N/A` (known-gap parser). An
   all-WARN/FAIL result on a supported parser fails.
-- **tps** — mean > 0 (the server produced tokens, not errors).
+- **tps** — liveness (mean > 0) **plus** a regression bar: if a blessed
+  `tests/baselines/<label>.json` exists, a run > `TPS_TOLERANCE` (10%) below it
+  fails; without a baseline it's liveness-only (loud note) unless
+  `--require-baselines`. Refresh deliberately: `gate_results.py --update-baselines`
+  writes `{"tps": avg}` per label, then review + commit the diff. (Baseline-snapshot
+  approach proposed by @Sujimoshi in #253; folded into the gate here to keep one
+  roster/SSOT rather than a parallel suite.)
 
 Validated against fixtures (full-pass / planned-but-missing / below-bar /
-known-gap-all-N/A) in `tests/test_gate_results.py`. Run order for
-`/atlas-release gate`:
+known-gap-all-N/A / tps-regression / no-baseline / require-baselines) in
+`tests/test_gate_results.py` (23 tests). Run order for `/atlas-release gate`:
 ```bash
 ATLAS_IMAGE=<tag> python3 tests/run_all_models.py               # boots + probes matrix -> *.json + _manifest.json
 python3 scripts/test_coherence.py --url http://localhost:8888   # leak/determinism/tools, exit 1 on fail
-python3 tests/gate_results.py                                   # coverage-enforcing verdict, exit 0/1
+python3 tests/gate_results.py                                   # coverage + regression verdict, exit 0/1
 ```
 All three green = shippable. Record the verdict + the results table next to the
 image tag (`docs/releases/<sha>.md`). **A gate with an unrecorded number is not a
diff --git a/tests/baselines/.gitkeep b/tests/baselines/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/baselines/README.md b/tests/baselines/README.md
new file mode 100644
index 000000000..df2f6bdeb
--- /dev/null
+++ b/tests/baselines/README.md
@@ -0,0 +1,20 @@
+# tps baselines
+
+One `<label>.json` per serve-matrix spec (e.g. `35B-nvfp4.json`), each holding
+`{"tps": <blessed tokens/sec>}`. `tests/gate_results.py` fails a model whose
+measured tps drops more than `TPS_TOLERANCE` (10%) below its baseline — the
+regression check that `tps > 0` alone can't give.
+
+Regenerate deliberately, never implicitly:
+
+```bash
+python3 tests/run_all_models.py                    # measure on real GB10 hardware
+python3 tests/gate_results.py --update-baselines    # write {"tps": avg} per label
+git diff tests/baselines                            # review, then commit
+```
+
+Labels match the manifest roster in `tests/run_all_models.py`. A model with no
+baseline is checked for liveness only (with a note) until one is blessed; pass
+`--require-baselines` to make a missing baseline a hard fail for a milestone.
+
+Credit: baseline-snapshot approach proposed by @Sujimoshi in #253.
diff --git a/tests/gate_results.py b/tests/gate_results.py
index 1e687e7af..242eab339 100644
--- a/tests/gate_results.py
+++ b/tests/gate_results.py
@@ -9,6 +9,13 @@
 
     python3 tests/run_all_models.py                 # produce results + _manifest.json
     python3 tests/gate_results.py                   # the gate — exit 0/1
+    python3 tests/gate_results.py --update-baselines # bless current tps (review+commit)
+
+Beyond liveness (tps>0), the gate catches perf *regressions*: a committed
+`tests/baselines/<label>.json` records the blessed tokens/sec, and a run more
+than TPS_TOLERANCE below it fails. Models without a baseline are checked for
+liveness only (with a loud note) until one is blessed — pass --require-baselines
+to make a missing baseline a hard fail for a release milestone.
 
 Coverage is enforced, not assumed. run_all_models.py writes `_manifest.json`
 listing every model the run *intended* to cover. This gate checks that roster:
@@ -37,11 +44,18 @@
 import sys
 
 MANIFEST_NAME = "_manifest.json"
+BASELINE_DIR = os.path.join(os.path.dirname(__file__), "baselines")
 
 # ── Per-model bars (PCND: explicit, rationale inline) ────────────────────────
 COHERENCE_MIN_PASS = 2   # of 3 probes (factual + reasoning + creative); >=2 tolerates
                          #   the one temp>0 creative probe occasionally missing.
 FIB_MIN_PASS = 1         # the fibonacci codegen smoke must exec-verify.
+TPS_TOLERANCE = 0.10     # tps regression bar. A committed tests/baselines/<label>.json
+                         #   records the blessed tokens/sec; a run >10% below it is a
+                         #   regression. With NO baseline the gate can only check
+                         #   liveness (tps>0) and says so — never a silent pass, but
+                         #   not a hard block unless --require-baselines (the stricter
+                         #   bar is opt-in for a milestone, not the default).
 # Tools: known-gap parsers score every tool test "N/A" and must NOT fail the gate.
 # A model whose parser IS wired up must land at least one real PASS — a result
 # that is all WARN/FAIL (parser supposedly supported but never produced a call)
@@ -56,8 +70,23 @@ def _status_na(s):
     return "N/A" in (s or "")
 
 
-def verdict(model_result):
-    """Pure: return the list of bar names this model FAILED (empty == verified)."""
+def _avg_tps(model_result):
+    """Mean measured tokens/sec across the tps probes, or None if none numeric."""
+    vals = [r.get("tps") for r in (model_result.get("tps", []) or [])
+            if isinstance(r.get("tps"), (int, float))]
+    if not vals:
+        return None
+    return sum(vals) / len(vals)
+
+
+def verdict(model_result, baseline=None, require_baseline=False):
+    """Pure: return the list of bar names this model FAILED (empty == verified).
+
+    `baseline` is the {"tps": <blessed tok/s>} dict for this label (or None). The
+    tps bar is: dead server (avg<=0) always fails; if a baseline exists, falling
+    >TPS_TOLERANCE below it is a regression; if none exists it fails only when
+    `require_baseline` is set (else liveness-only, surfaced as a note by caller).
+    """
     fails = []
 
     coh = model_result.get("coherence", []) or []
@@ -77,10 +106,16 @@ def verdict(model_result):
         if not any_pass and not all_na:
             fails.append("tool_calls")
 
-    tps = [r.get("tps") for r in (model_result.get("tps", []) or [])
-           if isinstance(r.get("tps"), (int, float))]
-    if tps and (sum(tps) / len(tps)) <= 0:
-        fails.append("tps(0)")
+    avg = _avg_tps(model_result)
+    if avg is not None:
+        if avg <= 0:
+            fails.append("tps(0)")
+        elif baseline and isinstance(baseline.get("tps"), (int, float)) and baseline["tps"] > 0:
+            floor = baseline["tps"] * (1 - TPS_TOLERANCE)
+            if avg < floor:
+                fails.append(f"tps({avg:.1f}<{floor:.1f})")
+        elif require_baseline:
+            fails.append("tps(no-baseline)")
 
     return fails
 
@@ -110,6 +145,45 @@ def load_result_file(path):
     return None, "malformed: no coherence/model fields"
 
 
+def load_baseline(label, baseline_dir):
+    """Return the {"tps": ...} baseline for a label, or None if not committed."""
+    path = os.path.join(baseline_dir, f"{label}.json")
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def write_baseline(label, data, baseline_dir):
+    """Merge `data` into tests/baselines/<label>.json (create dir if needed)."""
+    os.makedirs(baseline_dir, exist_ok=True)
+    path = os.path.join(baseline_dir, f"{label}.json")
+    existing = {}
+    if os.path.isfile(path):
+        with open(path) as f:
+            existing = json.load(f)
+    existing.update(data)
+    with open(path, "w") as f:
+        json.dump(existing, f, indent=2)
+        f.write("\n")
+
+
+def _score_one(label, name, result, baseline_dir, require_baseline):
+    """(bars, note): score a loaded result against its baseline; note flags a
+    positive-tps model with no baseline (liveness-only, not a block by default)."""
+    baseline = load_baseline(label, baseline_dir)
+    bars = verdict(result, baseline=baseline, require_baseline=require_baseline)
+    note = ""
+    avg = _avg_tps(result)
+    if avg and avg > 0 and not (baseline and isinstance(baseline.get("tps"), (int, float))) \
+            and not require_baseline:
+        note = "  (no tps baseline — liveness only; run --update-baselines)"
+    return bars, note
+
+
 def load_manifest(results_dir, manifest_path):
     """Return the planned [(label, model)] roster, or None if no manifest."""
     path = manifest_path or os.path.join(results_dir, MANIFEST_NAME)
@@ -120,7 +194,7 @@ def load_manifest(results_dir, manifest_path):
     return [(e["label"], e.get("model", e["label"])) for e in man.get("labels", [])]
 
 
-def gate_manifest(results_dir, roster):
+def gate_manifest(results_dir, roster, baseline_dir=BASELINE_DIR, require_baseline=False):
     """Coverage-enforcing gate. Every planned label must have a passing result.
 
     Returns (verified_count, total, failures) where failures is
@@ -140,15 +214,15 @@ def gate_manifest(results_dir, roster):
             print(f"  [FAIL] {name}  <- unreadable: {err}")
             failures.append((name, [f"unreadable: {err}"]))
             continue
-        bars = verdict(result)
+        bars, note = _score_one(label, name, result, baseline_dir, require_baseline)
         mark = "PASS" if not bars else "FAIL"
-        print(f"  [{mark}] {name}" + ("" if not bars else f"  <- {', '.join(bars)}"))
+        print(f"  [{mark}] {name}" + ("" if not bars else f"  <- {', '.join(bars)}") + note)
         if bars:
             failures.append((name, bars))
     return len(roster) - len(failures), len(roster), failures
 
 
-def gate_glob(results_dir):
+def gate_glob(results_dir, baseline_dir=BASELINE_DIR, require_baseline=False):
     """Coverage-UNENFORCED fallback: score whatever <label>.json files exist.
 
     Only reachable with --allow-missing-manifest. Cannot catch a model that
@@ -167,15 +241,44 @@ def gate_glob(results_dir):
         if result is None:
             continue  # aggregate/partial files, not per-model results
         seen += 1
-        name = result.get("model", os.path.basename(path))
-        bars = verdict(result)
+        label = os.path.splitext(os.path.basename(path))[0]
+        name = result.get("model", label)
+        bars, note = _score_one(label, name, result, baseline_dir, require_baseline)
         mark = "PASS" if not bars else "FAIL"
-        print(f"  [{mark}] {name}" + ("" if not bars else f"  <- {', '.join(bars)}"))
+        print(f"  [{mark}] {name}" + ("" if not bars else f"  <- {', '.join(bars)}") + note)
         if bars:
             failures.append((name, bars))
     return seen - len(failures), seen, failures
 
 
+def update_baselines(results_dir, roster, baseline_dir):
+    """Write tests/baselines/<label>.json = {"tps": <avg>} from present results.
+
+    Roster (label, model) list if a manifest exists, else every present result
+    file. Only positive tps is recorded. Returns [(label, avg)] written.
+    """
+    if roster is None:
+        items = [(os.path.splitext(os.path.basename(p))[0], None)
+                 for p in sorted(glob.glob(os.path.join(results_dir, "*.json")))
+                 if os.path.basename(p) != MANIFEST_NAME]
+    else:
+        items = roster
+    written = []
+    for label, _ in items:
+        path = os.path.join(results_dir, f"{label}.json")
+        if not os.path.isfile(path):
+            continue
+        result, _err = load_result_file(path)
+        if result is None:
+            continue
+        avg = _avg_tps(result)
+        if avg is None or avg <= 0:
+            continue
+        write_baseline(label, {"tps": round(avg, 2)}, baseline_dir)
+        written.append((label, avg))
+    return written
+
+
 def main():
     ap = argparse.ArgumentParser(description="Serve-matrix release gate (exit 0=ship, 1=block).")
     ap.add_argument("--results-dir", default=os.path.join(os.path.dirname(__file__), "all_models_results"),
@@ -185,6 +288,14 @@ def main():
     ap.add_argument("--allow-missing-manifest", action="store_true",
                     help="score only the files present (coverage NOT enforced). "
                          "Explicit opt-out — the default is to FAIL without a manifest.")
+    ap.add_argument("--baseline-dir", default=BASELINE_DIR,
+                    help="dir of committed per-label tps baselines (tests/baselines)")
+    ap.add_argument("--update-baselines", action="store_true",
+                    help="write current tps as the new baseline instead of gating "
+                         "(deliberate, reviewed refresh — commit the diff). Exits 0.")
+    ap.add_argument("--require-baselines", action="store_true",
+                    help="a planned model with no committed tps baseline FAILS "
+                         "(stricter milestone bar; default warns + liveness-only).")
     args = ap.parse_args()
 
     if not os.path.isdir(args.results_dir):
@@ -192,6 +303,15 @@ def main():
         return 1
 
     roster = load_manifest(args.results_dir, args.manifest)
+
+    if args.update_baselines:
+        written = update_baselines(args.results_dir, roster, args.baseline_dir)
+        for label, avg in written:
+            print(f"  [baseline] {label} <- {avg:.1f} tok/s")
+        print(f"[gate] wrote {len(written)} baseline(s) to {args.baseline_dir}. "
+              f"Review the diff and commit.")
+        return 0
+
     if roster is None:
         if not args.allow_missing_manifest:
             print(f"[gate] FAIL: no {MANIFEST_NAME} in {args.results_dir}. Run "
@@ -199,12 +319,12 @@ def main():
                   f"pass --allow-missing-manifest to score present files without "
                   f"coverage enforcement.", file=sys.stderr)
             return 1
-        verified, total, failed = gate_glob(args.results_dir)
+        verified, total, failed = gate_glob(args.results_dir, args.baseline_dir, args.require_baselines)
     else:
         if not roster:
             print("[gate] FAIL: manifest lists zero planned models.", file=sys.stderr)
             return 1
-        verified, total, failed = gate_manifest(args.results_dir, roster)
+        verified, total, failed = gate_manifest(args.results_dir, roster, args.baseline_dir, args.require_baselines)
 
     if total == 0:
         print(f"[gate] FAIL: no per-model results found in {args.results_dir}", file=sys.stderr)
diff --git a/tests/test_gate_results.py b/tests/test_gate_results.py
index 90ae7621d..49a1542ad 100644
--- a/tests/test_gate_results.py
+++ b/tests/test_gate_results.py
@@ -54,6 +54,27 @@ def test_supported_parser_all_fail_is_regression(self):
     def test_zero_tps_fails(self):
         self.assertIn("tps(0)", G.verdict(_model_result("m", tps=(0.0,))))
 
+    def test_no_baseline_liveness_only_passes(self):
+        # Positive tps, no baseline, not required -> pass (liveness only).
+        self.assertEqual(G.verdict(_model_result("m", tps=(30.0,)), baseline=None), [])
+
+    def test_no_baseline_required_fails(self):
+        v = G.verdict(_model_result("m", tps=(30.0,)), baseline=None, require_baseline=True)
+        self.assertIn("tps(no-baseline)", v)
+
+    def test_tps_within_tolerance_passes(self):
+        # 46 vs baseline 50 -> 8% down, inside the 10% band.
+        self.assertEqual(G.verdict(_model_result("m", tps=(46.0,)), baseline={"tps": 50.0}), [])
+
+    def test_tps_regression_fails(self):
+        # 30 vs baseline 50 -> 40% down, a real regression tps(0) can't catch.
+        v = G.verdict(_model_result("m", tps=(30.0,)), baseline={"tps": 50.0})
+        self.assertTrue(any(b.startswith("tps(") and "<" in b for b in v), v)
+
+    def test_dead_server_beats_baseline_check(self):
+        # avg<=0 is tps(0) even when a baseline exists — liveness first.
+        self.assertIn("tps(0)", G.verdict(_model_result("m", tps=(0.0,)), baseline={"tps": 50.0}))
+
 
 class Coverage(unittest.TestCase):
     def setUp(self):
@@ -99,6 +120,55 @@ def test_no_manifest_returns_none(self):
         self.assertIsNone(G.load_manifest(self.tmp, None))
 
 
+class Baselines(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+        self.bdir = tempfile.mkdtemp()
+
+    def _write(self, label, result):
+        with open(os.path.join(self.tmp, f"{label}.json"), "w") as f:
+            json.dump(result, f)
+
+    def _manifest(self, labels):
+        man = {"labels": [{"label": l, "model": m} for l, m in labels]}
+        with open(os.path.join(self.tmp, G.MANIFEST_NAME), "w") as f:
+            json.dump(man, f)
+
+    def test_update_writes_avg_and_gate_then_passes(self):
+        self._manifest([("a", "M/a")])
+        self._write("a", _model_result("M/a", tps=(40.0, 60.0)))  # avg 50
+        roster = G.load_manifest(self.tmp, None)
+        written = G.update_baselines(self.tmp, roster, self.bdir)
+        self.assertEqual(written, [("a", 50.0)])
+        self.assertEqual(G.load_baseline("a", self.bdir), {"tps": 50.0})
+        # Re-run the SAME result against the fresh baseline -> clean pass.
+        _, _, failed = G.gate_manifest(self.tmp, roster, self.bdir)
+        self.assertEqual(failed, [])
+
+    def test_update_skips_dead_server(self):
+        self._manifest([("a", "M/a")])
+        self._write("a", _model_result("M/a", tps=(0.0,)))
+        roster = G.load_manifest(self.tmp, None)
+        self.assertEqual(G.update_baselines(self.tmp, roster, self.bdir), [])
+
+    def test_regression_caught_by_gate(self):
+        self._manifest([("a", "M/a")])
+        G.write_baseline("a", {"tps": 50.0}, self.bdir)
+        self._write("a", _model_result("M/a", tps=(30.0,)))  # 40% down
+        roster = G.load_manifest(self.tmp, None)
+        _, _, failed = G.gate_manifest(self.tmp, roster, self.bdir)
+        self.assertEqual([f[0] for f in failed], ["M/a"])
+
+    def test_require_baselines_blocks_unblessed_model(self):
+        self._manifest([("a", "M/a")])
+        self._write("a", _model_result("M/a", tps=(50.0,)))  # healthy but no baseline
+        roster = G.load_manifest(self.tmp, None)
+        _, _, ok = G.gate_manifest(self.tmp, roster, self.bdir, require_baseline=False)
+        self.assertEqual(ok, [])                       # default: liveness-only pass
+        _, _, blocked = G.gate_manifest(self.tmp, roster, self.bdir, require_baseline=True)
+        self.assertEqual([f[0] for f in blocked], ["M/a"])
+
+
 class MainExit(unittest.TestCase):
     """Exercise the process-level contract: exit 0 ships, exit 1 blocks."""