diff --git a/README.md b/README.md
index fe042c8..4d74547 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,52 @@
-# The Exploded Cluster
+# The Teaching Lab (learn.bztmon.com)
 
-Interactive scroll-driven teardown of Kubernetes / OpenShift / Docker, in the estate's
-Bat-Computer visual world (void `#070b14`, cyan `#3fbaf5` → magenta `#e879f9`).
+A multi-page static technical learning site: scroll-driven teardowns of infrastructure the
+author actually operates. Dark engineering-dossier aesthetic (void `#070b14`, cyan `#3fbaf5`,
+magenta `#e879f9`), dependency-light by design, strict security posture.
 
-- **v2** (tag `v2`) — CSS `preserve-3d` diagrams. Parked: eyeballed px positions, misaligned at some widths.
-- **v3** (in progress) — ships PUBLIC at **learn.bztmon.com**.
-- **v3 build** — Nano Banana 2 exploded hero shots, hand-sliced into `clip-path` parts and
-  scrubbed collapsed → hero with GSAP. Spec: `homelab/specs/SPEC-exploded-cluster-v3.md`.
+## Pages
+| Route | Page | Source |
+|---|---|---|
+| `/` | The Teaching Lab - chapter directory | `pilot/index.tpl.html` |
+| `/cluster` | Chapter 01: The Exploded Cluster - eleven-course container-platform teardown | `pilot/arc.tpl.html` + `pilot/manifest-*.json` |
+| `/mirror` | Chapter 02: The Mirror - a zot pull-through registry, its failure modes and operations | `pilot/mirror.tpl.html` + `pilot/mirror.js` |
+
+## Build
+`bash build.sh` -> `dist/`. The assembler (`pilot/assemble-arc.mjs`, plain node, no
+dependencies) wraps each page in a shared document shell (canonical/OG metadata, build
+revision, skip link), content-fingerprints every file under `/assets/` (immutable-cached
+by nginx), splits page scripts into external fingerprinted files, injects intrinsic image
+dimensions (WebP and JPEG parsed from the actual bytes) with deliberate lazy/eager loading,
+and runs per-page preflight gates: no inline scripts (CSP `script-src 'self'` with no
+exceptions), exactly one `h1`, unique ids, no dangling anchors, no unresolved placeholders,
+and page-specific content assertions. A failed gate fails the build.
+
+Ship: `podman build` (multi-stage: node builds `dist/`, `nginx-unprivileged` serves it,
+both digest-pinned) -> push to the estate registry -> digest-pinned deploy via GitOps.
+`nginx/` carries the runtime config: strict CSP, HSTS, no-cache HTML with immutable
+fingerprinted assets, security headers on every location.
+
+## Accessibility and performance
+Skip link on every page (hidden until keyboard focus), one `h1` per page, stable section
+anchors, reduced-motion honoured live (effects also pause when the tab is hidden or the
+scene is off screen), intrinsic image dimensions to prevent layout shift, below-fold images
+lazy-loaded, system font stacks (CSP permits no third-party fonts).
 
 ## Layout
 | Path | What |
 |---|---|
-| `exploded-cluster.html` | v2 assembled single file (174KB) |
-| `ec2-part1.html` / `ec2-part2.html` | v2 source split — markup+CSS / app JS |
-| `gsap.min.js` · `st.min.js` | GSAP 3.13 + ScrollTrigger, inlined at assemble time |
-| `prompts/` | NB2 prompt contract — master style block + per-scene prompts |
-| `tools/slicer.html` | slice editor: load a hero, tune cut lines, export the manifest |
-| `assets/raw/` | curated NB2 heroes, straight from the generator |
+| `pilot/` | page templates, page scripts, scene manifests, the assembler |
+| `assets/dist/` | production heroes and diagrams for `/cluster` |
+| `assets/mirror/` | plates for `/mirror` |
+| `content/` | course source notes |
+| `nginx/` | runtime config baked into the image |
+| `tools/slicer.html` | slice editor: load a hero, tune cut lines, export a scene manifest |
+| `prompts/` | image prompt contract for the house visual style |
+| `exploded-cluster.html`, `ec2-part*.html` | v2 (parked, superseded by `/cluster`) |
+| `gsap.min.js` / `st.min.js` | GSAP 3.13 + ScrollTrigger, fingerprinted at assemble time |
 
-Rebuild v2: `cat ec2-part1.html <(echo "<script>") gsap.min.js <(echo "</script><script>") st.min.js <(echo "</script>") ec2-part2.html > exploded-cluster.html`
-
-## The slicing rule (load-bearing — read before touching the engine)
-Parts occlude each other in 2D, so every slice carries a hidden notch where the part in front
-covers it. Animating **collapsed → hero** only ever increases occlusion, so notches stay buried.
-**Never overshoot past the hero layout and never fan parts sideways** — either exposes the tears.
-Region boundaries overlap upward by `EPS`; expanding downward would ghost.
+## The slicing rule (load-bearing - read before touching the arc engine)
+Parts occlude each other in 2D, so every slice carries a hidden notch where the part in
+front covers it. Animating **collapsed -> hero** only ever increases occlusion, so notches
+stay buried. **Never overshoot past the hero layout and never fan parts sideways** - either
+exposes the tears. Region boundaries overlap upward by `EPS`; expanding downward would ghost.
diff --git a/pilot/assemble-arc.mjs b/pilot/assemble-arc.mjs
index 7504565..8d0e619 100644
--- a/pilot/assemble-arc.mjs
+++ b/pilot/assemble-arc.mjs
@@ -40,6 +40,30 @@ function webpSize(buf) {
   return null;
 }
 
+// --- intrinsic JPEG dimensions (SOF0/SOF2 markers) for the mirror plates ---
+function jpegSize(buf) {
+  if (buf[0] !== 0xff || buf[1] !== 0xd8) return null;
+  let o = 2;
+  while (o + 9 < buf.length) {
+    if (buf[o] !== 0xff) { o++; continue; }
+    const marker = buf[o + 1];
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      return { h: buf.readUInt16BE(o + 5), w: buf.readUInt16BE(o + 7) };
+    }
+    o += 2 + buf.readUInt16BE(o + 2);
+  }
+  return null;
+}
+
+// skip link: emitted by the shared shell, so its accessibility CSS lives in the shell
+// too - visually hidden until keyboard focus, visible and prominent when focused.
+const SKIP_CSS = `<style>
+a.skip{position:absolute;left:-9999px;top:0;z-index:99}
+a.skip:focus{left:1rem;top:1rem;background:#070b14;color:#3fbaf5;
+  font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.8rem;
+  padding:10px 16px;border:1px solid #3fbaf5;border-radius:6px;outline:none}
+</style>`;
+
 let tpl = readFileSync(join(ROOT, "pilot/arc.tpl.html"), "utf8");
 
 // split the app script (the last <script> block) out of the template
@@ -136,6 +160,7 @@ const shell = ({ title, desc, path, ogImg, scripts, bodyHtml }) => `<!doctype ht
 <meta name="twitter:description" content="${desc}">
 <meta name="twitter:image" content="${ogImg}">
 <link rel="icon" href="${favicon}">
+${SKIP_CSS}
 </head>
 <body>
 <a class="skip" href="#main-content">Skip to content</a>
@@ -157,9 +182,14 @@ const MIRROR_DESC = "A pull-through container registry taken apart: why a lab ru
 let mirror = readFileSync(join(ROOT, "pilot/mirror.tpl.html"), "utf8");
 const mirrorPlates = {};
 for (const n of ["20", "21", "22", "23", "24", "25"]) {
-  const { url } = emit(join(ROOT, "assets/mirror", `${n}.jpg`), `mirror-${n}`, "jpg");
+  const { url, buf } = emit(join(ROOT, "assets/mirror", `${n}.jpg`), `mirror-${n}`, "jpg");
   mirrorPlates[n] = url;
-  mirror = mirror.replace(`__M${n}__`, url);
+  const dims = jpegSize(buf);
+  if (!dims) throw new Error(`mirror plate ${n}: JPEG dimensions unreadable`);
+  // plate 20 is the page's first image (near the fold) -> eager/LCP; the rest lazy.
+  const load = n === "20" ? "eager" : "lazy";
+  mirror = mirror.replace(`__M${n}__`,
+    `${url}" width="${dims.w}" height="${dims.h}" decoding="async" loading="${load}`);
 }
 const mirrorJs = readFileSync(join(ROOT, "pilot/mirror.js"));
 const mirrorJsName = `mirror.${fp(mirrorJs)}.js`;
@@ -206,6 +236,30 @@ for (const [pg, doc] of [["cluster", html], ["mirror", mirrorHtml], ["index", di
     if (m[1] && !pidset.has(m[1])) fail.push(`${pg}: dangling internal link #` + m[1]);
   }
 }
+// mirror-page content gates: retired claims may be DISCUSSED as corrections, so these
+// target the assertive phrasings and internal production jargon, not the topic words.
+const mirrorBanned = [
+  [/never leaves the building/i, "retired absolute cache claim"],
+  [/up to twelve|twelve tries|12 attempts/i, "stale retry arithmetic (correct figure: sixteen)"],
+  [/plate-level/i, "internal production note leaked to readers"],
+  [/&middot; motion:/i, "art-direction caption leaked to readers"],
+  [/Phase B/, "internal phase jargon without explanation"],
+  [/RAID .*(is|are) (a )?backup/i, "snapshots/RAID-as-backup claim"],
+];
+for (const [re, msg] of mirrorBanned) if (re.test(mirrorHtml)) fail.push("mirror: " + msg);
+const mirrorRequired = [
+  ["zotregistry.dev", "primary zot references missing"],
+  ["keepUntagged", "version-gated retention discussion missing"],
+  ["/livez", "real health endpoints missing"],
+  ['id="refs"', "references section missing"],
+  ['id="open"', "open-verification register missing"],
+  ['width="1600" height="872"', "plate intrinsic dimensions missing/incorrect"],
+];
+for (const [needle, msg] of mirrorRequired) if (!mirrorHtml.includes(needle)) fail.push("mirror: " + msg);
+must((mirrorHtml.match(/width="1600" height="872"/g) || []).length === 6, "mirror: expected six correctly-dimensioned plates");
+must(!/100vw/.test(mirrorHtml), "mirror: viewport-width unit reintroduces scrollbar overflow");
+must(!mirrorHtml.includes("gsap"), "mirror: unexpected animation library reference");
+
 // banned / obsolete strings (user-visible copy)
 const banned = [
   [/ArgoCD/, "user-visible 'ArgoCD' (use 'Argo CD')"],
diff --git a/pilot/index.tpl.html b/pilot/index.tpl.html
index 9c7d0c5..850e26a 100644
--- a/pilot/index.tpl.html
+++ b/pilot/index.tpl.html
@@ -34,9 +34,6 @@ h1 em{color:var(--cyan);font-style:normal}
 footer{border-top:1px solid var(--line);padding:1.4rem 0 3rem;color:var(--dim);
   font-family:var(--mono);font-size:.82rem}
 footer a{color:var(--cyan)}
-a.skip{position:absolute;left:-9999px}
-a.skip:focus{left:1rem;top:1rem;background:var(--void);color:var(--cyan);
-  font-family:var(--mono);font-size:.8rem;padding:10px 16px;border:1px solid var(--cyan);border-radius:6px}
 :focus-visible{outline:2px solid var(--cyan);outline-offset:2px}
 @media (max-width:640px){.card{grid-template-columns:1fr}.card .thumb{max-height:170px}}
 </style>
diff --git a/pilot/mirror.js b/pilot/mirror.js
index 4c7f61c..af81736 100644
--- a/pilot/mirror.js
+++ b/pilot/mirror.js
@@ -1,39 +1,104 @@
-(function(){
-  var rm = matchMedia('(prefers-reduced-motion: reduce)').matches;
-  var bar = document.getElementById('bar');
-  var s20 = document.querySelector('#s20 img');
-  var ring = document.getElementById('ring');
-  var glows = [].slice.call(document.querySelectorAll('.s22-glow'));
-  var s24 = document.querySelector('#s24 img');
-  function prog(el){
-    var r = el.getBoundingClientRect(), vh = innerHeight;
-    return Math.max(0, Math.min(1, (vh - r.top) / (vh + r.height)));
-  }
-  function onScroll(){
-    var d = document.documentElement;
-    bar.style.width = (100 * d.scrollTop / (d.scrollHeight - innerHeight)) + '%';
-    if (rm) return;
-    var p20 = prog(s20);                       /* dock-and-stow: assembles inward */
-    s20.style.transform = 'scale(' + (1.07 - 0.07 * Math.min(1, p20 * 1.6)) + ') translateY(' + (26 - 26 * Math.min(1, p20 * 1.6)) + 'px)';
-    var p21 = prog(ring);                      /* ring-walk: the cycle turns */
-    ring.style.transform = 'rotate(' + (p21 * 300) + 'deg)';
-    glows.forEach(function(g, i){              /* checkpoint procession: three beats */
-      var p = prog(g.parentElement);
-      var band = 0.18 + i * 0.22;
-      g.style.opacity = Math.max(0, Math.min(0.85, (p - band) * 6));
+// The Mirror - scroll effects. External file: script-src 'self' holds, no inline JS.
+// Design constraints: no perpetual work - scroll reads are coalesced into a single rAF,
+// per-scene work only runs while that scene intersects the viewport, the pulse loop
+// runs only while its scene is visible AND the tab is visible AND motion is allowed,
+// and a change to prefers-reduced-motion takes effect live without a reload.
+(function () {
+  "use strict";
+  var motionQuery = matchMedia("(prefers-reduced-motion: reduce)");
+  var bar = document.getElementById("bar");
+  var s20 = document.querySelector("#s20 img");
+  var ring = document.getElementById("ring");
+  var s22 = document.getElementById("s22");
+  var glows = s22 ? [].slice.call(s22.querySelectorAll(".s22-glow")) : [];
+  var s24 = document.querySelector("#s24 img");
+  var pulse = document.getElementById("pulse");
+
+  // visibility ledger: IntersectionObserver marks which scenes are on screen
+  var visible = {};
+  var watched = [
+    ["s20", s20 && s20.closest(".scene")],
+    ["s21", ring && ring.closest(".scene")],
+    ["s22", s22 && s22.closest(".scene")],
+    ["s23", pulse && pulse.closest(".scene")],
+    ["s24", s24 && s24.closest(".scene")],
+  ].filter(function (w) { return w[1]; });
+  var io = new IntersectionObserver(function (entries) {
+    entries.forEach(function (e) {
+      var hit = watched.find(function (w) { return w[1] === e.target; });
+      if (hit) visible[hit[0]] = e.isIntersecting;
     });
-    var p24 = prog(s24);                       /* two-plane parallax */
-    s24.style.transform = 'translateY(' + ((p24 - 0.5) * -26) + 'px) scale(1.03)';
+    if (visible.s23) startPulse(); // (re)arm the breather when its scene returns
+  }, { rootMargin: "10% 0px" });
+  watched.forEach(function (w) { io.observe(w[1]); });
+
+  // progress of an element through the viewport, guarded against zero heights
+  function prog(el) {
+    var r = el.getBoundingClientRect();
+    var span = innerHeight + r.height;
+    if (!span) return 0;
+    return Math.max(0, Math.min(1, (innerHeight - r.top) / span));
   }
-  addEventListener('scroll', onScroll, {passive: true});
-  addEventListener('resize', onScroll);
-  onScroll();
-  if (!rm){                                    /* the jam breathes; nothing else does */
-    var pulse = document.getElementById('pulse'), t0 = null;
-    requestAnimationFrame(function breathe(t){
+
+  // scroll work: one rAF per burst, only touching scenes that are on screen
+  var ticking = false;
+  function frame() {
+    ticking = false;
+    var d = document.documentElement;
+    var denom = d.scrollHeight - innerHeight;
+    if (bar) bar.style.width = (denom > 0 ? (100 * d.scrollTop / denom) : 0) + "%";
+    if (motionQuery.matches) return;
+    if (visible.s20 && s20) {
+      var p20 = Math.min(1, prog(s20) * 1.6);
+      s20.style.transform = "scale(" + (1.07 - 0.07 * p20) + ") translateY(" + (26 - 26 * p20) + "px)";
+    }
+    if (visible.s21 && ring) ring.style.transform = "rotate(" + (prog(ring) * 300) + "deg)";
+    if (visible.s22 && glows.length) {
+      var p22 = prog(s22);
+      glows.forEach(function (g, i) {
+        g.style.opacity = Math.max(0, Math.min(0.85, (p22 - (0.18 + i * 0.22)) * 6));
+      });
+    }
+    if (visible.s24 && s24) s24.style.transform = "translateY(" + ((prog(s24) - 0.5) * -26) + "px) scale(1.03)";
+  }
+  function onScroll() {
+    if (!ticking) { ticking = true; requestAnimationFrame(frame); }
+  }
+  addEventListener("scroll", onScroll, { passive: true });
+  addEventListener("resize", onScroll);
+
+  // the jam's breathing glow: runs only while worth running, stops itself otherwise
+  var breathing = false;
+  function startPulse() {
+    if (breathing || !pulse || motionQuery.matches || document.hidden || !visible.s23) return;
+    breathing = true;
+    var t0 = null;
+    requestAnimationFrame(function breathe(t) {
+      if (motionQuery.matches || document.hidden || !visible.s23) {
+        breathing = false;
+        pulse.style.opacity = 0.25;
+        return;
+      }
       if (t0 === null) t0 = t;
       pulse.style.opacity = 0.18 + 0.2 * (0.5 + 0.5 * Math.sin((t - t0) / 520));
       requestAnimationFrame(breathe);
     });
   }
+  document.addEventListener("visibilitychange", function () { if (!document.hidden) { startPulse(); onScroll(); } });
+
+  // live preference change: clear transforms so the page settles to its static state
+  function motionChanged() {
+    if (motionQuery.matches) {
+      [s20, ring, s24].forEach(function (el) { if (el) el.style.transform = ""; });
+      glows.forEach(function (g) { g.style.opacity = 0.35; });
+      if (pulse) pulse.style.opacity = 0.25;
+    } else {
+      startPulse();
+      onScroll();
+    }
+  }
+  if (motionQuery.addEventListener) motionQuery.addEventListener("change", motionChanged);
+
+  startPulse();
+  onScroll();
 })();
diff --git a/pilot/mirror.tpl.html b/pilot/mirror.tpl.html
index 4878b76..0a49287 100644
--- a/pilot/mirror.tpl.html
+++ b/pilot/mirror.tpl.html
@@ -1,80 +1,106 @@
 <style>
-  /* Committed single-theme: a dark cinema world. Ground painted explicitly. */
   :root{
-    --void:#070b14; --void-2:#0a0f1b; --ink:#dfe6f0; --ink-dim:#8b95a7;
-    --cyan:#3fbaf5; --magenta:#e879f9; --line:#1c2434; --card:#0d1424;
+    --void:#070b14; --void-2:#0a0f1b; --ink:#dfe6f0; --ink-dim:#98a2b4;
+    --cyan:#3fbaf5; --magenta:#e879f9; --amber:#e8b44a; --line:#1c2434; --card:#0d1424;
+    --good:#7fe0a7; --bad:#ff8fa3;
     --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
     --sans:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
   }
   *{box-sizing:border-box}
   html{scroll-behavior:smooth}
   body{margin:0;background:var(--void);color:var(--ink);
-    font-family:var(--sans);font-size:1.06rem;line-height:1.65}
+    font-family:var(--sans);font-size:1.05rem;line-height:1.65}
   #bar{position:fixed;top:0;left:0;height:2px;width:0;background:linear-gradient(90deg,var(--cyan),var(--magenta));z-index:9}
-  .wrap{max-width:46rem;margin:0 auto;padding:0 1.25rem}
-  header.hero{min-height:92vh;display:flex;flex-direction:column;justify-content:center;padding:4rem 0 2rem}
+  /* full-bleed via named grid lines - no viewport units, so the vertical scrollbar
+     can never make the document wider than the visible viewport */
+  .layout{display:grid;
+    grid-template-columns:[full-start] minmax(1.25rem,1fr) [main-start] min(46rem,calc(100% - 2.5rem)) [main-end] minmax(1.25rem,1fr) [full-end]}
+  .layout>*{grid-column:main}
+  .layout>.scene{grid-column:full}
+  header.hero{min-height:70vh;display:flex;flex-direction:column;justify-content:center;padding:4.5rem 0 1.5rem;position:relative}
   .eyebrow{font-family:var(--mono);font-size:.78rem;letter-spacing:.22em;color:var(--cyan);text-transform:uppercase}
-  h1{font-family:var(--sans);font-stretch:semi-condensed;font-weight:700;font-size:clamp(3rem,9vw,5.2rem);
-    line-height:.95;margin:.5rem 0 1rem;text-wrap:balance;letter-spacing:.01em}
-  .outcome{max-width:34rem;color:var(--ink-dim);font-size:1.12rem}
+  h1{font-family:var(--sans);font-weight:750;font-size:clamp(2.8rem,8vw,4.6rem);
+    line-height:.98;margin:.5rem 0 1rem;text-wrap:balance;letter-spacing:-.01em}
+  .outcome{max-width:36rem;color:var(--ink-dim);font-size:1.12rem}
   .outcome b{color:var(--ink);font-weight:600}
-  .cue{margin-top:3rem;font-family:var(--mono);font-size:.75rem;color:var(--ink-dim);letter-spacing:.15em}
-  .cue::after{content:"";display:block;width:1px;height:56px;margin-top:.6rem;
-    background:linear-gradient(var(--cyan),transparent)}
-  h2{font-family:var(--sans);font-weight:600;font-size:2rem;letter-spacing:.02em;
-    margin:4.5rem 0 1rem;text-wrap:balance}
-  h2 .n{color:var(--cyan);font-family:var(--mono);font-size:1.05rem;vertical-align:.35em;margin-right:.6rem;letter-spacing:.1em}
-  h3{font-family:var(--sans);font-weight:600;font-size:1.3rem;margin:2.2rem 0 .6rem}
+  .backlink{font-family:var(--mono);font-size:.75rem;letter-spacing:.1em;margin-bottom:2rem}
+  .backlink a{color:var(--cyan);text-decoration:none}
+  .backlink a:hover{text-decoration:underline}
+  h2{font-family:var(--sans);font-weight:700;font-size:1.85rem;letter-spacing:0;
+    margin:4.2rem 0 1rem;text-wrap:balance;scroll-margin-top:2.5rem}
+  h2 .n{color:var(--cyan);font-family:var(--mono);font-weight:500;font-size:1rem;vertical-align:.35em;margin-right:.65rem;letter-spacing:.1em}
+  h3{font-weight:650;font-size:1.28rem;margin:2.2rem 0 .6rem;scroll-margin-top:2.5rem}
   p{margin:.9rem 0}
-  .scene{margin:3rem calc(50% - 50vw);width:100vw;overflow:hidden;position:relative}
+  code,.mono{font-family:var(--mono);font-size:.92em}
+  .scene{margin:3rem 0;overflow:hidden;position:relative}
   .scene .inner{max-width:72rem;margin:0 auto;padding:0 1rem;position:relative}
   .scene img{width:100%;height:auto;display:block;border-radius:.4rem}
-  .scene .cap{font-family:var(--mono);font-size:.72rem;color:var(--ink-dim);
-    letter-spacing:.14em;text-transform:uppercase;text-align:center;margin-top:.7rem}
+  .scene .cap{font-family:var(--mono);font-size:.74rem;color:var(--ink-dim);
+    letter-spacing:.1em;text-align:center;margin-top:.7rem;padding:0 1rem}
   .sayit{border-left:3px solid var(--magenta);margin:2rem 0;padding:.4rem 0 .4rem 1.1rem;
-    font-size:1.28rem;font-family:var(--sans);font-weight:600;line-height:1.35;color:#fff}
-  .sayit .k{display:block;font-family:var(--mono);font-size:.7rem;letter-spacing:.2em;color:var(--magenta);margin-bottom:.3rem}
+    font-size:1.26rem;font-weight:650;line-height:1.35;color:#fff}
+  .sayit .k{display:block;font-family:var(--mono);font-size:.7rem;letter-spacing:.2em;color:var(--magenta);margin-bottom:.3rem;font-weight:500}
   .note{background:var(--card);border:1px solid var(--line);border-left:3px solid var(--cyan);
     border-radius:.45rem;padding:1rem 1.2rem;margin:1.6rem 0;font-size:.98rem}
   .note .k{font-family:var(--mono);font-size:.72rem;letter-spacing:.18em;color:var(--cyan)}
+  .note.warn{border-left-color:var(--amber)}
+  .note.warn .k{color:var(--amber)}
   .clause{background:linear-gradient(135deg,rgba(232,121,249,.07),transparent 60%);
     border:1px solid var(--line);border-radius:.45rem;padding:1rem 1.2rem;margin:1.6rem 0;font-size:.98rem}
   .clause .k{font-family:var(--mono);font-size:.72rem;letter-spacing:.18em;color:var(--magenta)}
   pre{background:#050810;border:1px solid var(--line);border-radius:.5rem;padding:1rem 1.1rem;
     overflow-x:auto;font-family:var(--mono);font-size:.83rem;line-height:1.55;color:#c8d2e0}
   pre.pane{border-left:3px solid var(--cyan)}
-  pre .cm{color:#5a6478}
-  pre .good{color:#7fe0a7}
-  pre .bad{color:#ff8fa3}
+  pre .cm{color:#8a95ab}
+  pre .good{color:var(--good)}
+  pre .bad{color:var(--bad)}
   .pane-k{font-family:var(--mono);font-size:.72rem;letter-spacing:.18em;color:var(--ink-dim);
     text-transform:uppercase;margin:1.6rem 0 .4rem}
   .diagram{background:var(--card);border:1px solid var(--line);border-radius:.55rem;
     padding:1.2rem;margin:2rem 0;overflow-x:auto}
   .diagram .k{font-family:var(--mono);font-size:.72rem;letter-spacing:.18em;color:var(--cyan);display:block;margin-bottom:.8rem}
-  .diagram svg{width:100%;height:auto;display:block}
+  .diagram svg{width:100%;height:auto;display:block;min-width:560px}
   .diagram .why{font-size:.9rem;color:var(--ink-dim);margin:.8rem 0 0}
-  ol{padding-left:1.3rem}
-  ol li{margin:.7rem 0}
-  ul{padding-left:1.2rem}
-  ul li{margin:.55rem 0}
-  em{color:#fff;font-style:italic}
+  .diagram .legend{font-family:var(--mono);font-size:.72rem;color:var(--ink-dim);margin:.6rem 0 0}
+  table{border-collapse:collapse;width:100%;font-size:.88rem;margin:1.4rem 0}
+  .tablewrap{overflow-x:auto;margin:1.4rem 0}
+  .tablewrap table{margin:0;min-width:640px}
+  th,td{border:1px solid var(--line);padding:.5rem .65rem;text-align:left;vertical-align:top}
+  th{font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;text-transform:uppercase;color:var(--cyan);background:var(--void-2)}
+  td .st{font-family:var(--mono);font-size:.7rem;letter-spacing:.06em;padding:.05rem .4rem;border-radius:.25rem;border:1px solid var(--line);white-space:nowrap}
+  .st.ok{color:var(--good);border-color:rgba(127,224,167,.4)}
+  .st.open{color:var(--amber);border-color:rgba(232,180,74,.4)}
+  .st.prop{color:var(--magenta);border-color:rgba(232,121,249,.4)}
+  .facts{border:1px solid var(--line);border-radius:.55rem;background:var(--card);
+    padding:1.1rem 1.3rem;margin:2.2rem 0;font-size:.92rem}
+  .facts dl{display:grid;grid-template-columns:max-content 1fr;gap:.35rem 1.2rem;margin:0}
+  .facts dt{font-family:var(--mono);font-size:.72rem;letter-spacing:.12em;text-transform:uppercase;color:var(--ink-dim);padding-top:.15rem}
+  .facts dd{margin:0}
+  .toc{border:1px solid var(--line);border-radius:.55rem;padding:1rem 1.3rem;margin:2rem 0;background:var(--void-2)}
+  .toc .k{font-family:var(--mono);font-size:.72rem;letter-spacing:.18em;color:var(--cyan);text-transform:uppercase}
+  .toc ol{margin:.6rem 0 0;padding-left:1.4rem;columns:2;column-gap:2.5rem;font-size:.92rem}
+  .toc li{margin:.3rem 0;break-inside:avoid}
+  .toc a{color:var(--ink);text-decoration:none}
+  .toc a:hover{color:var(--cyan)}
+  @media (max-width:640px){.toc ol{columns:1}}
+  ol{padding-left:1.3rem} ol li{margin:.6rem 0}
+  ul{padding-left:1.2rem} ul li{margin:.5rem 0}
+  em{color:#fff}
   .traps p{margin:1.1rem 0}
-  .traps b{color:#fff}
+  .traps b,strong{color:#fff}
   footer{margin:5rem 0 4rem;border-top:1px solid var(--line);padding-top:1.4rem;
     color:var(--ink-dim);font-size:.88rem;font-family:var(--mono)}
   a{color:var(--cyan)}
   :focus-visible{outline:2px solid var(--cyan);outline-offset:2px}
   .s21-ring{position:absolute;inset:0;pointer-events:none;mix-blend-mode:screen;opacity:.5;
-    background:conic-gradient(from 0deg at 50% 50%, transparent 0deg, rgba(63,186,245,.28) 24deg, transparent 60deg);}
+    background:conic-gradient(from 0deg at 50% 50%, transparent 0deg, rgba(63,186,245,.28) 24deg, transparent 60deg)}
   .s22-glow{position:absolute;width:24%;aspect-ratio:1;border-radius:50%;pointer-events:none;
     mix-blend-mode:screen;opacity:0;background:radial-gradient(circle,rgba(63,186,245,.5),transparent 65%)}
   .s23-pulse{position:absolute;left:34%;top:44%;width:26%;aspect-ratio:1;border-radius:50%;pointer-events:none;
     mix-blend-mode:screen;opacity:.25;background:radial-gradient(circle,rgba(232,121,249,.55),transparent 62%)}
-  .cursor::after{content:"_";color:var(--cyan);animation:blink 1.1s steps(1) infinite}
-  @keyframes blink{50%{opacity:0}}
+  .refs li{margin:.45rem 0;font-size:.92rem}
   @media (prefers-reduced-motion: reduce){
     html{scroll-behavior:auto}
-    .cursor::after{animation:none}
     .s21-ring,.s23-pulse{display:none}
     .s22-glow{opacity:.35}
   }
@@ -82,43 +108,76 @@
 
 <div id="bar"></div>
 
-<header class="hero wrap">
-  <nav style="position:absolute;top:1.2rem;left:1.25rem;font-family:var(--mono);font-size:.75rem"><a href="/" style="text-decoration:none">&larr; index</a></nav>
-  <div class="eyebrow">Dossier / 005 &middot; The Teaching Lab</div>
+<div class="layout">
+
+<header class="hero">
+  <p class="backlink"><a href="/">&larr; The Teaching Lab</a></p>
+  <p class="eyebrow">Dossier / 005 &middot; operations</p>
   <h1>The Mirror</h1>
-  <p class="outcome"><b>Outcome</b> &mdash; a teardown of a pull-through container registry:
-  why a homelab runs its own mirror, the four chicken-and-egg loops hiding inside it,
-  and the scars that taught each rule. Everything on this page is running, or broke,
-  in the lab that published it.</p>
-  <div class="cue">SCROLL</div>
+  <p class="outcome"><b>Outcome</b> &mdash; a pull-through OCI registry taken apart: why this
+  lab runs its own mirror, what the deployed version actually guarantees, the retention trap
+  that quietly evicts digest-pinned content, and how each lesson translates into production
+  platform engineering. Claims are labelled: observed here, documented upstream, or not yet
+  verified.</p>
 </header>
 
-<div class="wrap">
+<div class="facts">
+  <dl>
+    <dt>Registry</dt><dd>zot v2.1.17 (digest-pinned image; latest upstream release at last check: v2.1.20)</dd>
+    <dt>Platform</dt><dd>Talos Linux v1.13.4, containerd 2.2.4, single-node Kubernetes</dd>
+    <dt>Upstreams</dt><dd>5 (Docker Hub, GHCR, Quay, registry.k8s.io, NGC), all on-demand pull-through</dd>
+    <dt>Storage</dt><dd>50Gi local PVC; dedupe on, GC on (1h delay / 24h interval); no retention config</dd>
+    <dt>Auth state</dt><dd>anonymous read enabled; per-node pull credentials staged, not yet enforced</dd>
+    <dt>Fallback</dt><dd>origin fallback ON (platform default; deliberately not disabled)</dd>
+    <dt>Validated</dt><dd>2026-08-25 (live config read + upstream doc/source verification)</dd>
+    <dt>Open items</dt><dd>digest-entry retention (needs v2.1.19+), auth canary negative test, upstream namespace prefixes, disconnected-serve drill</dd>
+  </dl>
+</div>
 
-<h2><span class="n">00</span>Cold open &mdash; the build that "hung"</h2>
+<nav class="toc" aria-labelledby="toc-h">
+  <p class="k" id="toc-h">Contents</p>
+  <ol>
+    <li><a href="#incident">The build that "hung"</a></li>
+    <li><a href="#anatomy">What the mirror actually does</a></li>
+    <li><a href="#routing">Request routing and five upstreams</a></li>
+    <li><a href="#bootstrap">Bootstrap, fallback and failure modes</a></li>
+    <li><a href="#digests">Digests, manifests and supply chain</a></li>
+    <li><a href="#retention">Retention, GC and the digest-only trap</a></li>
+    <li><a href="#auth">The authentication migration</a></li>
+    <li><a href="#observability">Observability that means something</a></li>
+    <li><a href="#production">The production translation</a></li>
+    <li><a href="#verified">Verified, open and references</a></li>
+  </ol>
+</nav>
+
+<h2 id="incident"><span class="n" aria-hidden="true">01</span>The build that "hung"</h2>
 
 <div class="scene" id="s20"><div class="inner">
-  <img src="__M20__" alt="An armoured way-station machine exploded into seven floating parts: hexagonal hull, roof plate, cassette shelf of glowing bricks, three intake pods, an output nozzle." width="1600" height="873" decoding="async">
-  <div class="cap">Scene 20 &middot; the way-station &middot; motion: dock-and-stow (assembles as you scroll)</div>
+  <img src="__M20__" alt="An armoured way-station machine exploded into parts: hexagonal hull, roof plate, a shelf of glowing bricks, intake pods and an output nozzle - the mirror as a physical machine.">
+  <div class="cap">The mirror as a machine: upstream intakes, one cache shelf, one serving nozzle.</div>
 </div></div>
 
-<p>Nobody sets out to run a registry. You inherit the need the day a CI build stalls
-for no reason you can see.</p>
-<p>The lab's website builds from an ordinary Dockerfile. One base image came from
-Docker Hub, pulled anonymously, and one evening the build simply... sat there. No
-error visible. No progress. Here is the accurate version: the registry does not go
-silent when it rate-limits you &mdash; it answers loudly, with an explicit 429 and the
-string <code style="font-family:var(--mono)">toomanyrequests</code>. The <em>silence</em>
-was manufactured closer to home, by a retry layer swallowing that answer and trying
-again, backoff stacked on backoff, until a routine build read like a hung machine.
-The swallower, recovered from the build script's own history, was a double retry
-stack: an outer shell wrapper allowing four attempts with a growing backoff, wrapped
-around the build tool's own three retries &mdash; up to twelve tries before anything
-surfaced. It was added, in fairness, to ride out transient 502s; nets that catch 502s
-catch 429s too, and a limit is not transient.</p>
+<p>Nobody sets out to run a registry. You inherit the need the day a CI build stalls for no
+reason you can see.</p>
 
-<div class="pane-k">Read-only pane &middot; receipt 00a &middot; the silence, as committed to the repo</div>
-<pre class="pane cursor">retry() {
+<p>This site's own build pulls one base image from Docker Hub, anonymously. One evening the
+build sat there - no visible error, no progress. The accurate version of that story: Docker
+Hub does not go silent when it limits you. It answers with an explicit HTTP 429 and the error
+code <code>toomanyrequests</code>; under the current published limits, anonymous pulls get
+100 manifest requests per six hours per IPv4 address, and the accounting is per manifest
+<code>GET</code>. The <em>silence</em> was manufactured on my side, by retries swallowing
+that answer.</p>
+
+<p>The swallower, recovered from the build script's git history, was a double retry stack: an
+outer shell wrapper allowing four attempts, wrapped around <code>buildah build --retry 3</code>.
+Buildah's flag counts <em>retries</em>, not attempts - one initial try plus up to three
+retries, and it applies to registry push/pull operations. Four outer attempts, each
+containing up to four inner attempts: <strong>up to sixteen requests</strong> for one
+consistently failing pull, each one billed against the same rate limit it was trying to
+outlast. Retry amplification turns a throttle into an outage and hides the evidence.</p>
+
+<div class="pane-k">Receipt &middot; the retry stack, as committed to the repo</div>
+<pre class="pane">retry() {
   local n=0 max=4
   until "$@"; do
     n=$((n+1)); [ "$n" -ge "$max" ] &amp;&amp; { echo "&gt;&gt; failed after ${max} attempts" &gt;&amp;2; return 1; }
@@ -126,46 +185,38 @@ catch 429s too, and a limit is not transient.</p>
   done
 }
 retry buildah build --retry 3 --retry-delay 5s ...
-<span class="cm"># four attempts, each containing three - the 429 answered every one of them</span></pre>
+<span class="cm"># --retry 3 = one attempt + three retries; the wrapper multiplies that by four.</span>
+<span class="cm"># A 429 answered every one of them, and the backoffs read as a hang.</span></pre>
 
-<p>The cause was boring and invisible: anonymous pulls from the world's most popular
-registry are rate-limited, and the base image tag was not pinned, so every single
-build asked Docker Hub the same question again. The fix for THAT bug is nearly one
-line &mdash; pin the digest. Nearly, because pinning only ends the conversation when a
-local cache already holds the answer; an ephemeral runner with a cold store still
-asks Hub for the manifest behind that digest every time. The pin stops the
-re-resolution, not the round-trip. Which surfaced the sharper question:</p>
+<p>The immediate fix was to pin the base image by digest - which stops tag re-resolution, but
+does not remove the network round-trip: an ephemeral runner with a cold local store still
+fetches the manifest behind that digest every build. The durable answer is structural:</p>
 
-<div class="sayit"><span class="k">SAY IT</span>Why does a fleet of machines ask the
-public internet for the same bytes, hundreds of times, forever?</div>
+<div class="sayit"><span class="k">SAY IT</span>Why does a fleet of machines ask the public
+internet for the same bytes, hundreds of times, forever?</div>
 
-<p>The answer a production platform gives is a mirror: one machine that fetches an
-image once, caches it, and serves every later request from the shelf. The lab built
-one. This dossier takes it apart.</p>
+<p>A production platform answers with a mirror: one registry that fetches once and serves the
+estate. The lab built one. This page takes it apart - including the parts that turned out
+not to work the way I first believed.</p>
 
-<div class="note"><span class="k">FIELD NOTE</span><br>The mirror did not fix the red X
-in CI. That red turned out to be a separate upstream bug in the CI system's log
-finalise step &mdash; cosmetic, tolerated, documented. Two problems, one symptom.
-Diagnose them separately or you will "fix" the wrong one and declare victory.</div>
+<div class="note"><span class="k">FIELD NOTE</span><br>The mirror did not fix the red X in
+CI. That red was a separate upstream bug in the CI system's log-finalise step - cosmetic,
+tolerated, documented. Two problems, one symptom. Diagnose them separately or you will fix
+the wrong one and declare victory.</div>
 
-<h2><span class="n">01</span>Anatomy &mdash; one cache, five upstreams</h2>
+<h2 id="anatomy"><span class="n" aria-hidden="true">02</span>What the mirror actually does</h2>
 
-<p>The mirror here is zot: a single OCI registry, one namespace on the platform, one
-50-gigabyte cache volume, digest-pinned like everything else in the fleet. It fronts
-five public registries &mdash; Docker Hub, GitHub's, Quay, the Kubernetes project
-registry, and NVIDIA's &mdash; and it works in one of three modes per upstream:</p>
-<ul>
-<li><b>onDemand</b> &mdash; pure pull-through. A miss fetches from upstream, caches, serves.
-The second pull is instant and never leaves the building.</li>
-<li><b>polled sync</b> &mdash; cache plus refresh on an interval, bounded by tag filters so a
-poll cannot drag a whole vendor catalogue into the shelf.</li>
-<li><b>pre-seed</b> &mdash; sync-only, for images that must be present before anything asks.</li>
-</ul>
-<p>Docker Hub gets onDemand ONLY. It has no catalogue API worth polling and the rate
-limits that started this story punish enthusiasm.</p>
-<p>The storage settings are not defaults; each one bought something:</p>
+<p>The mirror is zot: a single OCI registry in its own namespace, one 50Gi cache volume,
+running the same digest-pinned deployment discipline as everything it serves. It fronts five
+public registries in <strong>on-demand pull-through</strong> mode: a miss fetches from
+upstream and caches; a hit serves from the shelf. zot also supports polled mirroring
+(periodic full sync of matching content) and pre-seeding; Docker Hub is on-demand only -
+upstream documentation is explicit that polled mirroring should not be pointed at Hub.</p>
+
+<p>The storage block, from the live config:</p>
 
 <pre>"storage": {
+  "rootDirectory": "/var/lib/registry",
   "commit": true,
   "dedupe": true,
   "gc": true,
@@ -173,32 +224,47 @@ limits that started this story punish enthusiasm.</p>
   "gcInterval": "24h"
 }</pre>
 
-<p><code style="font-family:var(--mono)">commit</code> forces writes to disk before
-acknowledging &mdash; crash-safety for a box that might lose power.
-<code style="font-family:var(--mono)">dedupe</code> hard-links identical layers, which
-matters enormously when five upstreams ship the same base layers under different
-names. Garbage collection is delayed so a slow client mid-pull never watches its
-blobs vanish.</p>
+<p><code>commit</code> fsyncs writes before acknowledging - crash safety. <code>dedupe</code>
+hard-links identical blobs, which pays for itself when five upstreams ship the same base
+layers under different names. And <code>gc</code> with its two timers looks innocuous here;
+section 06 is about why it is the most consequential block on this page.</p>
 
-<p>The consumers point at the mirror in their runtime config. On this platform that
-is a machine-level mirror list &mdash; and the FALLBACK SEMANTICS hiding behind this
-short stanza are the most load-bearing thing in the whole dossier. Hold that thought
-for chapter 02.</p>
-
-<div class="diagram"><span class="k">Diagram D1 &middot; the pull path</span>
-<svg viewBox="0 0 760 240" role="img" aria-label="Pull path: node asks mirror; hit serves from cache; miss fetches upstream then caches; mirror down falls through to origin">
-  <defs><marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#3fbaf5"/></marker>
-  <marker id="am" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#e879f9"/></marker></defs>
-  <rect x="10" y="95" width="120" height="50" rx="8" fill="none" stroke="#3fbaf5"/><text x="70" y="125" fill="#dfe6f0" font-size="15" text-anchor="middle" font-family="IBM Plex Mono">node</text>
-  <rect x="300" y="95" width="150" height="50" rx="8" fill="none" stroke="#3fbaf5"/><text x="375" y="118" fill="#dfe6f0" font-size="15" text-anchor="middle" font-family="IBM Plex Mono">mirror</text><text x="375" y="136" fill="#8b95a7" font-size="11" text-anchor="middle" font-family="IBM Plex Mono">(the shelf)</text>
-  <rect x="600" y="30" width="150" height="50" rx="8" fill="none" stroke="#8b95a7"/><text x="675" y="60" fill="#dfe6f0" font-size="15" text-anchor="middle" font-family="IBM Plex Mono">origin</text>
-  <line x1="130" y1="120" x2="295" y2="120" stroke="#3fbaf5" marker-end="url(#a)"/><text x="210" y="110" fill="#8b95a7" font-size="12" text-anchor="middle" font-family="IBM Plex Mono">pull</text>
-  <path d="M450 108 Q 520 70 595 58" fill="none" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#a)"/><text x="520" y="62" fill="#8b95a7" font-size="12" text-anchor="middle" font-family="IBM Plex Mono">miss: fetch + cache</text>
-  <path d="M375 145 Q 375 190 320 190 L 150 190 Q 130 190 130 150" fill="none" stroke="#3fbaf5" marker-end="url(#a)"/><text x="255" y="210" fill="#8b95a7" font-size="12" text-anchor="middle" font-family="IBM Plex Mono">hit: served from cache</text>
-  <path d="M120 100 Q 300 20 595 42" fill="none" stroke="#e879f9" stroke-dasharray="3 5" marker-end="url(#am)"/><text x="300" y="30" fill="#e879f9" font-size="12" text-anchor="middle" font-family="IBM Plex Mono">mirror down: implicit fallback (skipFallback: false)</text>
+<div class="diagram"><span class="k">Diagram A &middot; system context</span>
+<svg viewBox="0 0 860 400" role="img" aria-labelledby="da-t da-d">
+  <title id="da-t">System context: consumers, the mirror, its storage, five upstreams, and the trust boundaries between them</title>
+  <desc id="da-d">CI and Kubernetes nodes pull from the zot mirror over the LAN. The mirror stores content on a 50Gi volume and syncs on demand from five upstream registries across the internet boundary. Anonymous read is currently allowed inbound; outbound upstream credentials live in one mounted secret. The origin-fallback path from nodes directly to upstreams is shown dashed.</desc>
+  <defs><marker id="da-a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#3fbaf5"/></marker>
+  <marker id="da-m" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#e879f9"/></marker></defs>
+  <g font-family="ui-monospace,Menlo,monospace" font-size="12" text-anchor="middle">
+    <rect x="12" y="60" width="150" height="52" rx="8" fill="none" stroke="#3fbaf5"/><text x="87" y="82" fill="#dfe6f0">CI (buildah)</text><text x="87" y="99" fill="#98a2b4">bastion host</text>
+    <rect x="12" y="150" width="150" height="52" rx="8" fill="none" stroke="#3fbaf5"/><text x="87" y="172" fill="#dfe6f0">k8s nodes</text><text x="87" y="189" fill="#98a2b4">containerd + local store</text>
+    <rect x="300" y="95" width="180" height="72" rx="8" fill="none" stroke="#dfe6f0"/><text x="390" y="122" fill="#dfe6f0">zot v2.1.17</text><text x="390" y="139" fill="#98a2b4">anon read (today)</text><text x="390" y="156" fill="#98a2b4">sync: onDemand x5</text>
+    <rect x="322" y="205" width="136" height="46" rx="8" fill="none" stroke="#98a2b4"/><text x="390" y="224" fill="#dfe6f0">50Gi PVC</text><text x="390" y="241" fill="#98a2b4">dedupe + GC 1h/24h</text>
+    <line x1="390" y1="167" x2="390" y2="200" stroke="#98a2b4"/>
+    <rect x="660" y="14" width="186" height="40" rx="8" fill="none" stroke="#98a2b4"/><text x="753" y="39" fill="#dfe6f0">docker.io</text>
+    <rect x="660" y="82" width="186" height="40" rx="8" fill="none" stroke="#98a2b4"/><text x="753" y="107" fill="#dfe6f0">ghcr.io</text>
+    <rect x="660" y="150" width="186" height="40" rx="8" fill="none" stroke="#98a2b4"/><text x="753" y="175" fill="#dfe6f0">quay.io</text>
+    <rect x="660" y="218" width="186" height="40" rx="8" fill="none" stroke="#98a2b4"/><text x="753" y="243" fill="#dfe6f0">registry.k8s.io</text>
+    <rect x="660" y="286" width="186" height="40" rx="8" fill="none" stroke="#98a2b4"/><text x="753" y="311" fill="#dfe6f0">nvcr.io</text>
+    <line x1="162" y1="86" x2="295" y2="115" stroke="#3fbaf5" marker-end="url(#da-a)"/>
+    <line x1="162" y1="176" x2="295" y2="145" stroke="#3fbaf5" marker-end="url(#da-a)"/>
+    <line x1="480" y1="110" x2="655" y2="40" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#da-a)"/>
+    <line x1="480" y1="120" x2="655" y2="100" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#da-a)"/>
+    <line x1="480" y1="131" x2="655" y2="168" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#da-a)"/>
+    <line x1="480" y1="142" x2="655" y2="235" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#da-a)"/>
+    <line x1="480" y1="153" x2="655" y2="300" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#da-a)"/>
+    <path d="M162 200 Q 390 330 660 315" fill="none" stroke="#e879f9" stroke-dasharray="2 6" marker-end="url(#da-m)"/>
+    <text x="360" y="322" fill="#e879f9">origin fallback (dashed = only when the mirror cannot serve)</text>
+    <line x1="580" y1="8" x2="580" y2="345" stroke="#1c2434"/>
+    <text x="580" y="368" fill="#98a2b4">internet boundary - outbound creds in ONE mounted secret</text>
+    <text x="230" y="45" fill="#98a2b4">LAN - anonymous read today; per-node creds staged</text>
+  </g>
 </svg>
-<p class="why">The decision this explains: the fallback is the platform's implicit
-default &mdash; the design choice is refusing to disable it.</p></div>
+<p class="legend">solid = normal pull path &middot; dashed cyan = on-demand sync on miss &middot; dashed magenta = origin fallback</p>
+<p class="why">The decision this explains: one cache serves two consumer classes, and the
+two credential domains (nodes-to-mirror, mirror-to-upstreams) never mix.</p></div>
+
+<p>Consumers reach the mirror through the platform's machine-level registry config:</p>
 
 <pre>machine:
   registries:
@@ -210,110 +276,364 @@ default &mdash; the design choice is refusing to disable it.</p></div>
         endpoints:
           - https://zot.bztmon.org</pre>
 
-<p>Read that carefully: the mirror is the ONLY listed endpoint, and that is still not
-a hard dependency &mdash; because this platform falls back to the origin registry
-IMPLICITLY unless you set <code style="font-family:var(--mono)">skipFallback: true</code>.
-The lab's first version of this config listed the upstream as an explicit second
-endpoint; the same-day refinement removed it after realising it merely rendered a
-duplicate of what the default already guaranteed. The lesson generalises: know which
-of your safety nets are things you built, and which are defaults you merely have not
-broken.</p>
+<p>The mirror is the only listed endpoint, and that is still not a hard dependency, because
+Talos documents an implicit final fallback: endpoints are tried in order, "and by default
+the last implicit endpoint is the original upstream registry", unless
+<code>skipFallback: true</code> says otherwise. The lab's first version listed the upstream
+as an explicit second endpoint; the refinement that removed it came from reading the
+behaviour properly - the default already guaranteed it. Know which of your safety nets you
+built, and which are defaults you merely have not broken.</p>
 
-<p>Upstream credentials &mdash; a Docker Hub login to lift rate limits, a vendor key for
-the GPU registry &mdash; live in ONE mounted secret, delivered by the cluster's secret
-operator under logical names, never in the runtime config. That split is not
-tidiness; it follows a reload asymmetry worth stating precisely. On this platform,
-the mirror ENDPOINT list hot-reloads &mdash; apply it and the runtime picks it up live,
-no reboot. Node-level registry AUTH does not: credentials in the machine config take
-effect only after a reboot. The mounted secret rotates with a restart of one pod. So
-endpoints and pod-side secrets can move cheaply; node auth is the expensive one &mdash;
-and that asymmetry, not neatness, decides where each credential lives and the whole
-rollout order in chapter 02. Both behaviours were observed on Talos v1.13.4 with
-containerd 2.2.4 (June&ndash;July 2026); treat the exact split as version-dependent and
-re-test on upgrades.</p>
+<p>One asymmetry decides the whole rollout order in section 07: registry <em>auth</em> in
+the machine config is documented by Talos as requiring a reboot before the CRI picks it up.
+Mirror <em>endpoint</em> changes applied live in this lab (observed on Talos v1.13.4 /
+containerd 2.2.4; the docs are silent on this half, so treat it as an observation, not a
+guarantee). Credentials the registry consumes from a mounted secret rotate with a pod
+restart. Put each credential on the side that can move.</p>
 
-<div class="clause"><span class="k">THE HOMELAB CLAUSE</span><br>In production this is
-not one pod with a volume. The mirror sits on dedicated storage &mdash; a NAS-class
-array or object store &mdash; sized for the whole estate's catalogue, and it is itself
-backed up, because in a disconnected site the mirror IS the software supply. The
-lab's 50Gi local volume with a nightly backup is the same organ, one size smaller.</div>
+<div class="clause"><span class="k">THE HOMELAB CLAUSE</span><br>One pod, one PVC, one node
+is an accepted failure domain, not a pattern. Section 09 covers what changes when the
+requirements change - and what genuinely does not.</div>
 
-<h2><span class="n">02</span>Chicken and egg &mdash; four loops, four answers</h2>
+<h2 id="routing"><span class="n" aria-hidden="true">03</span>Request routing and five upstreams</h2>
+
+<p>Five registries feed one endpoint, which raises a question the first version of this page
+skated past: when a node asks the mirror for <code>pause:3.10</code>, how does the mirror
+know whether that means Docker Hub, GHCR, Quay, registry.k8s.io or NGC?</p>
+
+<p>Three facts, all verified:</p>
+
+<ol>
+<li><strong>containerd tells the mirror where the request came from</strong> - a mirror
+request carries the original registry as a query parameter:
+<code>/v2/pause/manifests/3.10?ns=registry.k8s.io</code>. That is documented containerd
+behaviour.</li>
+<li><strong>zot v2.1.17 ignores it.</strong> There is no handling of the <code>ns</code>
+parameter in the deployed version's request path, and using it for upstream selection is an
+open upstream feature request (zot issue 4187) with, at last check, no maintainer response.
+The URL path alone selects the local repository.</li>
+<li><strong>This deployment has no per-upstream prefixes.</strong> The live sync config
+gives all five upstreams <code>prefix: "**"</code> and no <code>destination</code> - one
+flat namespace. On a miss, zot tries the configured upstreams in order until one has the
+path. Upstream documentation's own multi-registry example instead gives each upstream a
+distinct <code>destination</code> so the requested path selects the origin.</li>
+</ol>
+
+<div class="tablewrap"><table>
+<caption class="mono" style="text-align:left;color:var(--ink-dim);font-size:.78rem;padding-bottom:.4rem">Upstream map - observed configuration</caption>
+<tr><th>Origin</th><th>Local namespace</th><th>Outbound auth</th><th>Sync mode</th><th>Digest preserved</th><th>On miss</th><th>Status</th></tr>
+<tr><td>docker.io</td><td rowspan="5">flat (no prefix - collision-ambiguous by construction)</td><td>Hub login (rate-limit lift)</td><td>onDemand</td><td>yes</td><td rowspan="5">upstreams tried in config order; first that resolves the path wins</td><td><span class="st ok">observed</span></td></tr>
+<tr><td>ghcr.io</td><td>none</td><td>onDemand</td><td>yes</td><td><span class="st ok">observed</span></td></tr>
+<tr><td>quay.io</td><td>none</td><td>onDemand</td><td>yes</td><td><span class="st ok">observed</span></td></tr>
+<tr><td>registry.k8s.io</td><td>none</td><td>onDemand</td><td>yes</td><td><span class="st ok">observed</span></td></tr>
+<tr><td>nvcr.io</td><td>$oauthtoken + key</td><td>onDemand</td><td>yes</td><td><span class="st ok">observed</span></td></tr>
+</table></div>
+
+<p>Why has the flat namespace not bitten? Because the five origins use largely disjoint path
+conventions - Hub's official images live under <code>library/</code> (the implicit prefix
+behind bare names like <code>alpine</code>), NGC content sits under <code>nvidia/</code>,
+registry.k8s.io has its own layout. "Largely disjoint" is a probability, not a guarantee: an
+organisation name that exists on both GHCR and Quay would collide silently, and the winner
+would be config order. That is an accepted risk in a lab; it is not a design.</p>
+
+<div class="note warn"><span class="k">PROPOSED - NOT YET DEPLOYED</span><br>The safer shape,
+verified against the documentation of both halves but not yet applied here: give each
+upstream a distinct <code>destination</code> prefix in zot
+(<code>/docker</code>, <code>/ghcr</code>, ...), and point each Talos mirror at the
+prefixed path with <code>overridePath: true</code> (which stops the automatic
+<code>/v2</code> append so the prefix survives). Then the requested path itself names the
+origin, and collisions become impossible rather than improbable. The migration cost: every
+cached repository changes its local path, so the cache re-warms.</div>
+
+<div class="diagram"><span class="k">Diagram B &middot; request flow</span>
+<svg viewBox="0 0 860 330" role="img" aria-labelledby="db-t db-d">
+  <title id="db-t">Request flow from a node through containerd to the mirror, with hit, miss, revalidation and fallback branches</title>
+  <desc id="db-d">A pull begins at the node's local content store. On local miss, containerd asks the mirror. A cached digest request is served from mirror storage without upstream contact. A tag request is revalidated against the upstream even when cached, on the deployed version. A storage miss triggers on-demand sync from the matching upstream. If the mirror cannot serve, containerd falls back to the origin registry.</desc>
+  <defs><marker id="db-a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#3fbaf5"/></marker>
+  <marker id="db-m" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#e879f9"/></marker>
+  <marker id="db-g" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#7fe0a7"/></marker></defs>
+  <g font-family="ui-monospace,Menlo,monospace" font-size="12" text-anchor="middle">
+    <rect x="10" y="30" width="170" height="46" rx="8" fill="none" stroke="#3fbaf5"/><text x="95" y="49" fill="#dfe6f0">node content store</text><text x="95" y="66" fill="#98a2b4">hit = no network at all</text>
+    <rect x="10" y="130" width="170" height="40" rx="8" fill="none" stroke="#3fbaf5"/><text x="95" y="155" fill="#dfe6f0">containerd -&gt; mirror</text>
+    <rect x="300" y="40" width="200" height="44" rx="8" fill="none" stroke="#7fe0a7"/><text x="400" y="58" fill="#dfe6f0">digest request, cached</text><text x="400" y="75" fill="#7fe0a7">served locally (verified)</text>
+    <rect x="300" y="120" width="200" height="44" rx="8" fill="none" stroke="#e8b44a"/><text x="400" y="138" fill="#dfe6f0">tag request, cached</text><text x="400" y="155" fill="#e8b44a">still revalidates upstream</text>
+    <rect x="300" y="200" width="200" height="44" rx="8" fill="none" stroke="#3fbaf5"/><text x="400" y="218" fill="#dfe6f0">storage miss</text><text x="400" y="235" fill="#98a2b4">on-demand sync + cache</text>
+    <rect x="640" y="120" width="200" height="44" rx="8" fill="none" stroke="#98a2b4"/><text x="740" y="138" fill="#dfe6f0">origin registry</text><text x="740" y="155" fill="#98a2b4">rate limits live here</text>
+    <line x1="95" y1="76" x2="95" y2="125" stroke="#3fbaf5" marker-end="url(#db-a)"/><text x="150" y="105" fill="#98a2b4">local miss</text>
+    <line x1="180" y1="140" x2="295" y2="66" stroke="#7fe0a7" marker-end="url(#db-g)"/>
+    <line x1="180" y1="150" x2="295" y2="142" stroke="#e8b44a" marker-end="url(#db-a)"/>
+    <line x1="180" y1="160" x2="295" y2="218" stroke="#3fbaf5" marker-end="url(#db-a)"/>
+    <line x1="500" y1="142" x2="635" y2="142" stroke="#e8b44a" stroke-dasharray="5 4" marker-end="url(#db-a)"/>
+    <line x1="500" y1="222" x2="640" y2="158" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#db-a)"/>
+    <path d="M95 170 Q 95 300 400 300 L 660 300 Q 740 300 740 168" fill="none" stroke="#e879f9" stroke-dasharray="2 6" marker-end="url(#db-m)"/>
+    <text x="400" y="290" fill="#e879f9">containerd fallback: mirror endpoints exhausted -&gt; origin direct</text>
+  </g>
+</svg>
+<p class="legend">green = fully local &middot; amber = the surprising branch on v2.1.17 &middot; magenta = fallback</p>
+<p class="why">The amber branch is section 04's punchline: a warm cache does not mean the
+network is out of the story.</p></div>
+
+<h2 id="bootstrap"><span class="n" aria-hidden="true">04</span>Bootstrap, fallback and failure modes</h2>
 
 <div class="scene" id="s21"><div class="inner">
-  <img src="__M21__" alt="Six machine parts arranged on an invisible ring around empty centre - a large cyan way-station at twelve o'clock and a quarter-scale magenta replica of it among the orbiting parts." width="1600" height="893" decoding="async">
+  <img src="__M21__" alt="Six machine parts arranged in a ring around an empty centre; one of them is a quarter-scale replica of the large way-station machine, representing the mirror's own image passing through the mirror.">
   <div class="s21-ring" id="ring"></div>
-  <div class="cap">Scene 21 &middot; the loop &middot; motion: ring-walk (the cycle turns as you scroll)</div>
+  <div class="cap">The dependency ring: one of the orbiting parts is the mirror itself - its own image is served through the thing it is.</div>
 </div></div>
 
-<p>Every infrastructure service eventually meets the question: what do you depend on,
-and what happens when you ARE the dependency? The mirror has four of these loops, and
-each one got a different answer. This chapter is the reason this page exists.</p>
+<p>Every infrastructure service eventually meets the question: what do you depend on, and
+what happens when you ARE the dependency? The mirror has four such loops, and each got a
+different answer.</p>
 
-<h3>Loop 1 &mdash; the mirror's own image comes through the mirror</h3>
-<p>zot runs as a container. That container's image lives on one of the very
-registries zot mirrors. So when the node that hosts zot boots, it asks... zot. Which
-is not running, because the node is booting.</p>
-<p>The answer is the fallback you met in chapter 01: <b>mirror listed, origin
-implicit</b>. The runtime tries the mirror, fails fast, and falls through to the real
-registry because nobody set <code style="font-family:var(--mono)">skipFallback: true</code>.
-The loop breaks itself, and the thing that breaks it is a platform default doing
-quiet duty as a bootstrap protocol &mdash; the design decision here is the restraint of
-not turning it off.</p>
+<h3 id="loop1">Loop 1 - the mirror's own image comes through the mirror</h3>
+<p>zot runs as a container whose image lives on a registry zot mirrors. When the hosting
+node boots, it asks the mirror - which is not running, because the node is booting. The
+loop breaks on the documented fallback: mirror endpoints exhaust, containerd falls through
+to the origin. The design decision is restraint - <em>not</em> setting
+<code>skipFallback: true</code>.</p>
 
-<div class="sayit"><span class="k">SAY IT</span>The fallback is not a compromise. The
-fallback IS the design.</div>
+<div class="note"><span class="k">FIELD NOTE &middot; OBSERVED</span><br>Proven by accident:
+a config change shipped with <code>preserveDigest</code> enabled but without its mandatory
+partner <code>http.compat</code> - a pairing the registry refuses to start without (the
+documentation is explicit; so was the crashloop). The mirror went down; the fleet quietly
+fell through to upstream and nothing user-visible broke. An unplanned failover exercise,
+passed. The standing rule it bought: validate the config with the registry's own
+<code>verify</code> in a throwaway pod before merging, every time.</div>
 
-<div class="note"><span class="k">FIELD NOTE</span><br>This was proven by accident. A
-config change shipped with a flag the registry refused to start with
-(<code style="font-family:var(--mono)">preserveDigest</code> demands
-<code style="font-family:var(--mono)">http.compat</code> &mdash; a real pairing rule,
-learn it from this page instead of from the crash). The mirror crashlooped. And
-nothing else broke: every node quietly fell through to upstream and the fleet never
-noticed. An unplanned failover test, passed. The postmortem produced the standing
-rule: run <code style="font-family:var(--mono)">zot verify</code> on the config BEFORE
-merging, in a throwaway pod, every time.</div>
+<h3 id="loop2">Loop 2 - the recovery tooling deliberately ignores the mirror</h3>
+<p>The fleet's rescue tooling could pull its execution image through the mirror like
+everything else. It does not: its image is cached on the operations host, outside the
+cluster. A recovery tool that depends on the thing it recovers is not a recovery tool.</p>
 
-<h3>Loop 2 &mdash; the recovery tooling deliberately ignores the mirror</h3>
-<p>The fleet's rescue tooling &mdash; the automation that health-checks and rebuilds the
-platform &mdash; could pull its execution image through the mirror like everything else.
-It does not. Its image is cached on the operations box, outside the cluster entirely.</p>
-<p>Because a recovery tool that depends on the thing it recovers is not a recovery
-tool. It is a passenger.</p>
+<h3 id="loop3">Loop 3 - authentication cannot flip everywhere at once</h3>
+<p>Covered properly in section 07; the loop shape: enforcing auth requires every node to
+carry credentials that only apply after a reboot, so anonymous read must survive until the
+last node is proven, and the proof itself must be designed not to lie.</p>
 
-<h3>Loop 3 &mdash; you cannot turn authentication on everywhere at once</h3>
+<h3 id="loop4">Loop 4 - the mirror's host is also the mirror's customer</h3>
+<p>The node hosting the mirror boots its own workloads through it - including the tunnel
+that serves this very page. "Restart the mirror's node" therefore carries a blast radius
+far beyond the mirror, and the runbook for that reboot lists every public-facing thing
+riding on it and the order they return. Draw the dependency arrows for your own estate; the
+ones that surprise you are the ones that will page you.</p>
 
-<div class="scene" id="s22"><div class="inner" style="position:relative">
-  <img src="__M22__" alt="Four parts left to right: a waiting keyed cartridge, a small glowing key wedge, a tall gate frame with cyan inner glow, and a cartridge beyond the gate with its keyway lit." width="1600" height="873" decoding="async">
+<div class="diagram"><span class="k">Diagram D &middot; two bootstrap worlds</span>
+<svg viewBox="0 0 860 300" role="img" aria-labelledby="dd-t dd-d">
+  <title id="dd-t">Connected fail-open bootstrap versus disconnected preseeded bootstrap, as separate paths</title>
+  <desc id="dd-d">Left: the connected lab path - node boots, mirror miss, implicit fallback to origin, mirror comes up afterwards. Right: the disconnected path - no origin exists; the registry image and release set must be preseeded onto the host or imported from disk before anything else can start.</desc>
+  <g font-family="ui-monospace,Menlo,monospace" font-size="12" text-anchor="middle">
+    <text x="215" y="28" fill="#3fbaf5">CONNECTED LAB - FAIL-OPEN (observed)</text>
+    <rect x="60" y="50" width="310" height="38" rx="8" fill="none" stroke="#3fbaf5"/><text x="215" y="74" fill="#dfe6f0">node boots, asks mirror: down</text>
+    <rect x="60" y="112" width="310" height="38" rx="8" fill="none" stroke="#e879f9"/><text x="215" y="136" fill="#dfe6f0">implicit fallback -&gt; origin serves boot images</text>
+    <rect x="60" y="174" width="310" height="38" rx="8" fill="none" stroke="#3fbaf5"/><text x="215" y="198" fill="#dfe6f0">mirror starts (its image came via fallback)</text>
+    <rect x="60" y="236" width="310" height="38" rx="8" fill="none" stroke="#7fe0a7"/><text x="215" y="260" fill="#dfe6f0">estate converges back onto the mirror</text>
+    <line x1="215" y1="88" x2="215" y2="108" stroke="#98a2b4"/><line x1="215" y1="150" x2="215" y2="170" stroke="#98a2b4"/><line x1="215" y1="212" x2="215" y2="232" stroke="#98a2b4"/>
+    <text x="645" y="28" fill="#e8b44a">DISCONNECTED SITE - PRESEEDED (design, not deployed here)</text>
+    <rect x="490" y="50" width="310" height="38" rx="8" fill="none" stroke="#e8b44a"/><text x="645" y="74" fill="#dfe6f0">no origin exists - fallback is not a plan</text>
+    <rect x="490" y="112" width="310" height="38" rx="8" fill="none" stroke="#e8b44a"/><text x="645" y="136" fill="#dfe6f0">registry image preseeded / imported from disk</text>
+    <rect x="490" y="174" width="310" height="38" rx="8" fill="none" stroke="#e8b44a"/><text x="645" y="198" fill="#dfe6f0">release set, trust roots, creds staged locally</text>
+    <rect x="490" y="236" width="310" height="38" rx="8" fill="none" stroke="#7fe0a7"/><text x="645" y="260" fill="#dfe6f0">site serves itself; syncs on a schedule</text>
+    <line x1="645" y1="88" x2="645" y2="108" stroke="#98a2b4"/><line x1="645" y1="150" x2="645" y2="170" stroke="#98a2b4"/><line x1="645" y1="212" x2="645" y2="232" stroke="#98a2b4"/>
+    <line x1="430" y1="40" x2="430" y2="285" stroke="#1c2434"/>
+  </g>
+</svg>
+<p class="legend">left = this lab, observed &middot; right = the airgap translation, a design requirement not a deployed claim</p>
+<p class="why">Loop 1's trick assumes an upstream exists to fall through to. The airgap
+deletes that assumption, and forces Loop 2's discipline onto the mirror itself.</p></div>
+
+<p><strong>Fallback is a policy decision, not a universal win.</strong> This lab keeps it on:
+better bootstrap survivability, availability through mirror outages, and the cost is real -
+pulls can silently bypass the mirror (losing cache benefit and any future policy point) and
+land on origin rate limits. A regulated or disconnected estate makes the opposite call:
+<code>skipFallback: true</code>, egress restrictions, preseeded release stock, and a tested
+recovery path, because silent bypass is the failure mode there, not the safety net.</p>
+
+<p>And "fails fast" is not one behaviour. The failure modes differ in symptom, path and
+consequence:</p>
+
+<div class="tablewrap"><table>
+<tr><th>Failure</th><th>User-visible symptom</th><th>Request path</th><th>Fallback?</th><th>Detection</th><th>Security consequence</th></tr>
+<tr><td>Mirror pod down</td><td>none (pulls slower)</td><td>node -&gt; origin</td><td>yes, immediate</td><td>mirror probes red; origin egress rises</td><td>policy/audit bypass while down</td></tr>
+<tr><td>Mirror up, sync wedged</td><td>pulls hang up to sync timeout</td><td>node -&gt; mirror (blocked)</td><td>only after timeout</td><td>manifest probe stalls while /v2/ still answers</td><td>availability, not integrity</td></tr>
+<tr><td>Upstream 429</td><td>miss/tag pulls fail or crawl</td><td>mirror -&gt; origin refused</td><td>fallback hits the same limit</td><td>zot logs; retry storms amplify</td><td>none; self-inflicted DoS via retries</td></tr>
+<tr><td>Upstream down, digest cached</td><td>none</td><td>mirror serves locally</td><td>not needed</td><td>-</td><td>none (verified behaviour)</td></tr>
+<tr><td>Upstream down, tag cached</td><td>fails/stalls on v2.1.17</td><td>mirror insists on revalidating</td><td>origin also down</td><td>the test matrix in section 08</td><td>availability surprise - the trap of assuming "cached = offline-safe"</td></tr>
+<tr><td>PVC full</td><td>new pulls fail, cached OK-ish</td><td>mirror 5xx on writes</td><td>yes for missing content</td><td>capacity metrics (proposed)</td><td>availability; GC pressure</td></tr>
+<tr><td>Digest entry GC-evicted</td><td>silent re-fetch on next pull</td><td>mirror -&gt; origin re-sync</td><td>n/a</td><td>upstream egress for "cached" content</td><td>rate-limit exposure returns (section 06)</td></tr>
+<tr><td>Node auth wrong (post-flip)</td><td>ImagePullBackOff</td><td>mirror 401; fallback unreliable on 401</td><td>unreliable</td><td>the canary gate (section 07)</td><td>the outage the gate exists to prevent</td></tr>
+</table></div>
+
+<h2 id="digests"><span class="n" aria-hidden="true">05</span>Digests, manifests and the supply chain</h2>
+
+<p>Precision matters here, because half the traps on this page come from conflating these
+objects:</p>
+
+<ul>
+<li>A <strong>tag</strong> is a mutable, human-readable pointer. Zero, one or many tags can
+reference one manifest.</li>
+<li>A <strong>manifest digest</strong> identifies exact manifest bytes. A multi-platform
+<strong>index</strong> has its own digest; each platform manifest has another; layers and
+config blobs have their own again.</li>
+<li><code>name:tag@digest</code> is client-side grammar, not wire protocol: the OCI
+distribution spec takes a tag <em>or</em> a digest in the URL. Clients resolve the digest
+and ignore the tag (Kubernetes documents exactly this), so digest-pinned pulls are immune
+to tag moves - a fact this page once mislearned as a cache trap and later retested: the
+historical zot rejection of combined references did not reproduce on v2.1.17. Traps are
+perishable; retest your scars.</li>
+<li>Digest pinning provides <strong>content integrity</strong> - not provenance, not
+authorisation, not availability, and not freedom from network fetches on a cold store.</li>
+</ul>
+
+<p>For a mirror, digests carry one sharp operational rule, learned here as a crashloop:
+zot converts Docker-schema manifests to OCI by default, and conversion changes the digest -
+silently breaking every digest pin and signature downstream. The pairing that prevents it
+(<code>preserveDigest: true</code> per upstream, with <code>http.compat: ["docker2s2"]</code>)
+is mandatory in both directions: the registry refuses to start with one and not the other.
+This deployment runs both, on all five upstreams - observed in the live config.</p>
+
+<p>Preserving digests does <em>not</em> mean the supply chain travels whole. OCI 1.1
+referrers - signatures, SBOMs, attestations attached via the <code>subject</code> field and
+served by the referrers API - are separate objects with their own discovery path. A
+pull-through cache that mirrors manifests and blobs does not automatically carry them.
+Nothing here verifies signatures today; if it did, disconnected verification would also
+need the trust material carried locally (a public key, or a trusted-root bundle for a
+private signing stack). That is stated as a boundary, not an aspiration.</p>
+
+<div class="clause"><span class="k">THE HOMELAB CLAUSE</span><br>Production estates promote
+releases by digest between registries - a tag is a suggestion, a digest is a fact - and
+decide explicitly whether referrers travel with them. The lab runs the digest half of that
+discipline; the referrer half is future work and labelled as such.</div>
+
+<h2 id="retention"><span class="n" aria-hidden="true">06</span>Retention, GC and the digest-only trap</h2>
+
+<div class="scene" id="s23"><div class="inner">
+  <img src="__M23__" alt="A stuck intake pod ringed in magenta with three glowing cargo bricks queued behind it - cached content waiting on a jammed process.">
+  <div class="s23-pulse" id="pulse"></div>
+  <div class="cap">Cached bricks queued behind a jammed intake: availability problems here are quiet, not loud.</div>
+</div></div>
+
+<p>This section corrects the largest error in this page's own first edition. I wrote:
+"no retention config means keep everything". That is true for tags, and dangerously false
+for everything else - and "everything else" includes precisely the content this mirror
+exists to hold.</p>
+
+<p>The verified semantics, from upstream documentation and the deployed version's source:</p>
+
+<ul>
+<li>With no retention configuration, <strong>all tags are retained</strong> - and
+<strong>all untagged manifests are deleted</strong> by garbage collection (unless referenced
+by an index or artifact) once they are older than <code>gcDelay</code>. This deployment's
+delay is the 1-hour default, with GC sweeping daily.</li>
+<li><strong>Digest-only pull-through entries are stored as untagged manifests.</strong>
+That is the exact wording of the upstream fix's problem statement: pull an image through
+the mirror by digest, and the cache entry has no tag to protect it.</li>
+</ul>
+
+<div class="sayit"><span class="k">SAY IT</span>A digest-pinned fleet, pulling through a
+mirror whose GC treats digest-only entries as garbage: the cache evicts exactly what the
+estate is built on.</div>
+
+<p>Put the pieces together with section 04's revalidation fact and the deployed behaviour
+is this: <em>tag</em> pulls are cached but always phone upstream anyway; <em>digest</em>
+pulls are served locally but their cache entries are eligible for eviction within hours.
+On v2.1.17, this mirror is a rate-limit shield and a latency win - it is <strong>not yet a
+disconnection shelf</strong>, and the first edition of this page was wrong to imply
+otherwise.</p>
+
+<div class="diagram"><span class="k">Diagram C &middot; what keeps an object alive</span>
+<svg viewBox="0 0 860 360" role="img" aria-labelledby="dc-t dc-d">
+  <title id="dc-t">The OCI object graph and which references protect content from garbage collection</title>
+  <desc id="dc-d">A tag points to an index; the index references platform manifests; manifests reference layers and a config blob. Referrers attach to a manifest via a subject field. A separate digest-only manifest sits with no tag pointing at it; it is eligible for garbage collection after the delay on the deployed version. Retention rules that keep tags do not protect the untagged manifest.</desc>
+  <defs><marker id="dc-a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#3fbaf5"/></marker>
+  <marker id="dc-b" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#98a2b4"/></marker></defs>
+  <g font-family="ui-monospace,Menlo,monospace" font-size="12" text-anchor="middle">
+    <rect x="30" y="30" width="150" height="40" rx="8" fill="none" stroke="#7fe0a7"/><text x="105" y="55" fill="#dfe6f0">tag: v1.2</text>
+    <rect x="240" y="30" width="170" height="40" rx="8" fill="none" stroke="#3fbaf5"/><text x="325" y="49" fill="#dfe6f0">index (multi-arch)</text><text x="325" y="64" fill="#98a2b4">own digest</text>
+    <rect x="470" y="10" width="170" height="40" rx="8" fill="none" stroke="#3fbaf5"/><text x="555" y="35" fill="#dfe6f0">manifest amd64</text>
+    <rect x="470" y="62" width="170" height="40" rx="8" fill="none" stroke="#3fbaf5"/><text x="555" y="87" fill="#dfe6f0">manifest arm64</text>
+    <rect x="700" y="10" width="140" height="40" rx="8" fill="none" stroke="#98a2b4"/><text x="770" y="35" fill="#dfe6f0">layers + config</text>
+    <rect x="700" y="62" width="140" height="40" rx="8" fill="none" stroke="#98a2b4"/><text x="770" y="87" fill="#dfe6f0">layers + config</text>
+    <rect x="470" y="130" width="170" height="40" rx="8" fill="none" stroke="#e879f9" stroke-dasharray="4 3"/><text x="555" y="149" fill="#dfe6f0">referrer (sig/SBOM)</text><text x="555" y="164" fill="#e879f9">subject -&gt; manifest</text>
+    <line x1="180" y1="50" x2="235" y2="50" stroke="#7fe0a7" marker-end="url(#dc-a)"/>
+    <line x1="410" y1="42" x2="465" y2="30" stroke="#3fbaf5" marker-end="url(#dc-a)"/>
+    <line x1="410" y1="58" x2="465" y2="80" stroke="#3fbaf5" marker-end="url(#dc-a)"/>
+    <line x1="640" y1="30" x2="695" y2="30" stroke="#98a2b4" marker-end="url(#dc-b)"/>
+    <line x1="640" y1="82" x2="695" y2="82" stroke="#98a2b4" marker-end="url(#dc-b)"/>
+    <line x1="555" y1="130" x2="555" y2="106" stroke="#e879f9" stroke-dasharray="4 3" marker-end="url(#dc-a)"/>
+    <text x="105" y="120" fill="#7fe0a7">a tag is a keep-alive</text>
+    <rect x="30" y="215" width="280" height="52" rx="8" fill="none" stroke="#e8b44a"/><text x="170" y="236" fill="#dfe6f0">digest-only cached manifest</text><text x="170" y="253" fill="#e8b44a">NO tag references it</text>
+    <rect x="380" y="215" width="220" height="52" rx="8" fill="none" stroke="#ff8fa3"/><text x="490" y="236" fill="#dfe6f0">GC after gcDelay (1h here)</text><text x="490" y="253" fill="#ff8fa3">deleteUntagged default: true</text>
+    <line x1="310" y1="241" x2="375" y2="241" stroke="#ff8fa3" marker-end="url(#dc-a)"/>
+    <text x="430" y="310" fill="#98a2b4">keepTags rules protect TAGS in their repo. Nothing on v2.1.17/18 protects the amber box;</text>
+    <text x="430" y="330" fill="#98a2b4">pull-aware keepUntagged ships in v2.1.19 (2026-08-04). Node-local caches can mask the eviction for days.</text>
+  </g>
+</svg>
+<p class="legend">green = protected by a tag &middot; amber/red = the eviction path &middot; dashed magenta = referrers (separate lifecycle)</p>
+<p class="why">The lesson: reachability, not existence, is what GC respects - and a
+pull-through cache full of digest pulls is a graveyard of unreachable-by-tag objects.</p></div>
+
+<p>Retention policy semantics, stated precisely because two nearby systems use opposite
+rules:</p>
+
+<ul>
+<li>Retention policies match per repository, <strong>first match wins</strong> - order the
+list most-specific-first. A repository matching no policy keeps its tags.</li>
+<li>Within a matched repository, one <code>keepTags</code> rule inverts the default:
+non-matching tags in <em>that repository</em> become deletable. The inversion is scoped to
+the repository, not global - the first edition of this page overstated it.</li>
+<li>Untagged manifests are governed separately (<code>deleteUntagged</code>, default true),
+and on the deployed version no retention rule can protect them. Pull-aware
+<code>keepUntagged</code> exists upstream from v2.1.19.</li>
+<li>Authorisation policies (section 07) use <strong>longest match</strong>, not first
+match. Two adjacent config blocks, two opposite precedence rules. Label which one you are
+reasoning about.</li>
+</ul>
+
+<p><strong>Mitigations, honestly ranked:</strong> upgrade to v2.1.19+ and configure
+<code>keepUntagged</code> with pull-activity rules (the designed fix); until then, widen
+<code>gcDelay</code>/<code>retention.delay</code> so eviction pressure drops (the upstream
+maintainer's own interim suggestion), or set <code>deleteUntagged: false</code> and accept
+that the cache only grows - a capacity trade, not a free lunch. Disabling GC entirely
+trades eviction for guaranteed storage exhaustion with no reclaim path; it is listed here
+to be argued against.</p>
+
+<div class="note warn"><span class="k">SAFE VALIDATION - PROPOSED, NOT YET RUN</span><br>
+The eviction claim above is documented upstream and consistent with this config; it has not
+been reproduced in this lab yet. The safe reproduction, for a <em>disposable</em> zot
+instance only: record version + sanitised config; pull an image by digest through it;
+confirm on the registry side that the stored manifest is untagged; shorten GC timers (in
+the disposable instance only); observe the manifest before and after the sweep; then block
+upstream and repeat the pull from a clean runtime store, recording whether the mirror
+serves or re-fetches. Two warnings from upstream documentation: the retention verification
+tool executes orphan-blob GC for real even in dry-run, and on local storage it requires the
+registry stopped. Never point retention experiments at live storage.</div>
+
+<h2 id="auth"><span class="n" aria-hidden="true">07</span>The authentication migration</h2>
+
+<div class="scene" id="s22"><div class="inner">
+  <img src="__M22__" alt="Four parts left to right: a waiting keyed cartridge, a key wedge, a tall gate frame, and a cartridge beyond the gate with its keyway lit - per-node credentials proven at a checkpoint.">
   <div class="s22-glow" style="left:16%;top:30%" data-band="0"></div>
   <div class="s22-glow" style="left:44%;top:28%" data-band="1"></div>
   <div class="s22-glow" style="left:70%;top:26%" data-band="2"></div>
-  <div class="cap">Scene 22 &middot; the proving gate &middot; motion: checkpoint procession (three beats, left to right)</div>
+  <div class="cap">The proving gate: a node counts as migrated when an authenticated pull succeeds where an anonymous one cannot.</div>
 </div></div>
 
-<p>The target state is a mirror that refuses anonymous pulls. The path there is a
-sequencing puzzle:</p>
-<ol>
-<li>Auth in the node's registry config requires a REBOOT to take effect &mdash; mirror
-endpoints reload live, credentials do not. (Asymmetries like this decide rollout
-order; find them before you start.)</li>
-<li>The runtime's fall-back-on-401 behaviour is unreliable enough to carry open
-upstream issues &mdash; so a node whose auth is wrong does not gracefully degrade, it
-just fails to pull.</li>
-<li>Therefore: anonymous read STAYS ON while every node gets its auth config and its
-reboot, and each node must PROVE itself before it counts. And here the gate hides a
-trap of its own: while anonymous read is still on, pulling an ordinary repo proves
-NOTHING about auth &mdash; a node whose credentials never applied sends no
-authorisation header at all, the mirror happily serves it as an anonymous reader,
-and the gate false-passes the exact node it exists to catch. The canary must
-therefore live in a repo whose access policy DENIES anonymous read, so a successful
-pull can only mean an authenticated pull. Pass THAT, and the node is trusted. Only
-when every node has passed does anonymous flip off fleet-wide.</li>
-</ol>
+<p>Target state: the mirror refuses anonymous pulls. Current state: anonymous read on, with
+per-node credentials staged in machine configs (inert until each node's reboot - the
+documented behaviour). The migration is a sequencing problem with one trap at its centre:</p>
 
-<p>The lab's live policy today is the pre-flip shape &mdash; one glob, anonymous read on
-&mdash; and the canary repo gets its own entry carrying NO anonymous policy, so its
-pulls demand credentials while the rest of the shelf stays open:</p>
+<p><strong>While anonymous read is on, an ordinary pull proves nothing about auth.</strong>
+A node whose credentials never applied sends no authorisation header, gets served as an
+anonymous reader, and false-passes the gate. The canary must live in a repository that
+denies anonymous read, so a successful pull can only mean an authenticated pull.</p>
+
+<p>That design is now upstream-validated rather than assumed: zot authorisation resolves
+per-repository policies by <strong>longest match</strong> - the most specific path pattern
+wins, and <code>**</code> is explicitly the default policy for anything unmatched. A
+<code>canary/**</code> entry that grants named identities read and carries no
+<code>anonymousPolicy</code> therefore denies anonymous on that path while the glob keeps
+the rest of the shelf open. Maintainer guidance confirms anonymous and authenticated access
+are evaluated independently. The staged policy:</p>
 
 <pre>"accessControl": {
   "repositories": {
@@ -332,207 +652,223 @@ pulls demand credentials while the rest of the shelf stays open:</p>
   }
 }</pre>
 
-<p>That per-node proof is a hard gate precisely because the failure mode is silent. A
-node that looks fine and cannot pull is a time bomb with a pleasant dashboard.</p>
+<div class="note"><span class="k">CLIENT CAVEAT &middot; DOCUMENTED</span><br>Mixed
+anonymous/authenticated policies trigger a Docker-client-specific workaround present in
+this exact version: <code>/v2/</code> returns 401 to Docker user agents so the Docker CLI
+sends credentials, meaning anonymous <em>docker</em> users must log in even for anonymous
+repos. Podman and containerd are unaffected. This estate pulls with containerd, podman and
+buildah, so the caveat is noted rather than felt.</div>
 
-<div class="diagram"><span class="k">Diagram D2 &middot; the auth-flip ladder</span>
-<svg viewBox="0 0 760 200" role="img" aria-label="Five rungs: anonymous on, auth staged, reboot, authenticated canary proof, anonymous off. A failing node loops from the proof rung back to reboot.">
-  <defs><marker id="b" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#3fbaf5"/></marker>
-  <marker id="bm" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#e879f9"/></marker></defs>
-  <g font-family="IBM Plex Mono" font-size="11" text-anchor="middle">
-  <rect x="8"   y="70" width="128" height="46" rx="8" fill="none" stroke="#8b95a7"/><text x="72"  y="90" fill="#dfe6f0">anon read ON</text><text x="72" y="105" fill="#8b95a7">baseline</text>
-  <rect x="163" y="70" width="128" height="46" rx="8" fill="none" stroke="#3fbaf5"/><text x="227" y="90" fill="#dfe6f0">auth staged</text><text x="227" y="105" fill="#8b95a7">inert in config</text>
-  <rect x="318" y="70" width="128" height="46" rx="8" fill="none" stroke="#3fbaf5"/><text x="382" y="90" fill="#dfe6f0">node reboots</text><text x="382" y="105" fill="#8b95a7">auth goes live</text>
-  <rect x="473" y="70" width="128" height="46" rx="8" fill="none" stroke="#e879f9"/><text x="537" y="90" fill="#dfe6f0">canary pull</text><text x="537" y="105" fill="#e879f9">MUST authenticate</text>
-  <rect x="628" y="70" width="124" height="46" rx="8" fill="none" stroke="#3fbaf5"/><text x="690" y="90" fill="#dfe6f0">all proven:</text><text x="690" y="105" fill="#8b95a7">anon OFF</text>
-  <line x1="136" y1="93" x2="158" y2="93" stroke="#3fbaf5" marker-end="url(#b)"/>
-  <line x1="291" y1="93" x2="313" y2="93" stroke="#3fbaf5" marker-end="url(#b)"/>
-  <line x1="446" y1="93" x2="468" y2="93" stroke="#3fbaf5" marker-end="url(#b)"/>
-  <line x1="601" y1="93" x2="623" y2="93" stroke="#3fbaf5" marker-end="url(#b)"/>
-  <path d="M537 116 Q 537 165 460 165 L 420 165 Q 382 165 382 121" fill="none" stroke="#e879f9" stroke-dasharray="4 4" marker-end="url(#bm)"/>
-  <text x="462" y="185" fill="#e879f9">401: back to the reboot rung</text></g>
+<p>The gate, per node, and what each step proves:</p>
+
+<ol>
+<li>Stage credentials in the node's machine config (inert; documented as requiring reboot).</li>
+<li>Reboot the node at a planned window.</li>
+<li><strong>Prove identity:</strong> pull the protected canary through the node's own
+runtime. Success = authenticated (anonymous cannot); failure = 401, back to step 1. The
+expected split, to be confirmed against observed responses when the test runs: 401 for
+missing/wrong credentials, 403 for a valid identity lacking the action - upstream docs
+state the 403 case explicitly only for OIDC identities, so the basic-auth 403 boundary is
+listed in the open-verification register rather than asserted.</li>
+<li><strong>Prove interception separately:</strong> the canary pull is a direct reference
+to the mirror, so it cannot prove that <code>docker.io/...</code> references are being
+routed through the mirror at all. That second proof needs an original-upstream reference
+pulled on the node <em>plus</em> the mirror's request log showing it arrive - and a cold
+runtime store, because node-local content will satisfy the pull without any network and
+fake a pass.</li>
+<li>Only when every node passes both proofs does <code>anonymousPolicy</code> come off the
+glob. Rollback is the previous config commit, and it is named before the flip, not after.</li>
+</ol>
+
+<div class="diagram"><span class="k">Diagram E &middot; the migration ladder</span>
+<svg viewBox="0 0 860 210" role="img" aria-labelledby="de-t de-d">
+  <title id="de-t">The authentication migration ladder with its per-node proof gate and rollback point</title>
+  <desc id="de-d">Five stages: anonymous baseline, credentials staged inert, node reboot, the two-part proof - authenticated canary pull plus logged mirror interception - and the final anonymous-off flip with a named rollback commit. A failing node loops from the proof back to staging.</desc>
+  <defs><marker id="de-a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#3fbaf5"/></marker>
+  <marker id="de-m" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#e879f9"/></marker></defs>
+  <g font-family="ui-monospace,Menlo,monospace" font-size="11" text-anchor="middle">
+    <rect x="10"  y="70" width="140" height="48" rx="8" fill="none" stroke="#98a2b4"/><text x="80"  y="90" fill="#dfe6f0">anon read ON</text><text x="80" y="106" fill="#98a2b4">baseline (today)</text>
+    <rect x="180" y="70" width="140" height="48" rx="8" fill="none" stroke="#3fbaf5"/><text x="250" y="90" fill="#dfe6f0">creds staged</text><text x="250" y="106" fill="#98a2b4">inert in config</text>
+    <rect x="350" y="70" width="140" height="48" rx="8" fill="none" stroke="#3fbaf5"/><text x="420" y="90" fill="#dfe6f0">node reboots</text><text x="420" y="106" fill="#98a2b4">auth goes live</text>
+    <rect x="520" y="70" width="160" height="48" rx="8" fill="none" stroke="#e879f9"/><text x="600" y="86" fill="#dfe6f0">two-part proof</text><text x="600" y="100" fill="#e879f9">canary + logged</text><text x="600" y="113" fill="#e879f9">interception</text>
+    <rect x="710" y="70" width="140" height="48" rx="8" fill="none" stroke="#7fe0a7"/><text x="780" y="90" fill="#dfe6f0">anon OFF</text><text x="780" y="106" fill="#98a2b4">rollback = prior commit</text>
+    <line x1="150" y1="94" x2="175" y2="94" stroke="#3fbaf5" marker-end="url(#de-a)"/>
+    <line x1="320" y1="94" x2="345" y2="94" stroke="#3fbaf5" marker-end="url(#de-a)"/>
+    <line x1="490" y1="94" x2="515" y2="94" stroke="#3fbaf5" marker-end="url(#de-a)"/>
+    <line x1="680" y1="94" x2="705" y2="94" stroke="#3fbaf5" marker-end="url(#de-a)"/>
+    <path d="M600 118 Q 600 175 480 175 L 320 175 Q 250 175 250 122" fill="none" stroke="#e879f9" stroke-dasharray="4 4" marker-end="url(#de-m)"/>
+    <text x="440" y="196" fill="#e879f9">401: node loops back - it does not count</text>
+  </g>
 </svg>
-<p class="why">The decision this explains: the gate is per-node, never fleet-wide &mdash;
-one unproven node under a fleet-wide flip is an outage wearing a green tick.</p></div>
+<p class="legend">the flip is per-fleet; the proof is per-node - one unproven node under a fleet-wide flip is an outage wearing a green tick</p>
+<p class="why">Why two proofs: identity and interception fail independently, and each has a
+false-pass mode the other cannot detect.</p></div>
 
-<div class="pane-k">Read-only pane &middot; replay 23a &middot; the crictl gate, two different nodes</div>
-<pre class="pane">node A (auth applied, rebooted):
-  $ crictl pull zot.bztmon.org/canary/prompt-forge:0726R1
-  <span class="good">Image is up to date for sha256:...</span>      <span class="cm">&lt;- authenticated pull; node A is trusted</span>
-node B (auth staged in config, no reboot yet):
-  $ crictl pull zot.bztmon.org/canary/prompt-forge:0726R1
-  <span class="bad">E... failed to pull ...: 401 Unauthorized</span>
-                                          <span class="cm">&lt;- node B reboots before it counts</span></pre>
+<p>Behind the gate sit five separate trust domains, deliberately not shared: node pull
+credentials (machine config, reboot-bound), CI push credentials (human-held login), the
+mirror's own upstream credentials (one mounted secret, pod-restart-bound), TLS trust
+(estate wildcard, standard roots), and human admin access (SSO in front of the UI). The
+push credential carries this page's oldest scar: its hash and plaintext once drifted apart,
+rotation became impossible, and pushes stayed dead for twelve days until the rebuilt flow
+landed - three applications shipped the same day it came back. Hash and plaintext now live
+side by side, rotated together by a human, and the automation identity that syncs secrets
+is read-only by design so it can never half-rotate them again.</p>
 
-<h3>Loop 4 &mdash; the mirror's host is also the mirror's customer</h3>
-<p>The node that hosts the mirror boots its own workloads through it &mdash; including,
-in this lab, the tunnel that serves the public website. So "restart the mirror's
-node" carries a blast radius far beyond the mirror. The runbook for that reboot
-lists every public-facing thing that rides on it, and the order they come back.</p>
-<p>Draw the dependency arrows for your own estate. The ones that surprise you are
-the ones that will page you. Sequencing, here, is a first-class engineering
-artefact.</p>
+<h2 id="observability"><span class="n" aria-hidden="true">08</span>Observability that means something</h2>
 
-<div class="clause"><span class="k">THE HOMELAB CLAUSE</span><br>Production separates
-these concerns physically: the mirror on its own storage appliance, per-site edge
-nodes pulling FROM it, no workload sharing its host. The lab collapses them onto one
-node and manages the consequence with sequencing and runbooks. Same physics,
-different budget.</div>
+<p>"The registry is up" is the least useful sentence in this page. The worst incident in
+this mirror's life: an in-flight sync wedged, every pull from that upstream hung, and the
+health endpoint returned 200 throughout. The log line was almost poetic:</p>
 
-<h2><span class="n">03</span>The traps &mdash; each rule has a scar</h2>
-
-<div class="scene" id="s23"><div class="inner" style="position:relative">
-  <img src="__M23__" alt="A serene queue: a stuck intake pod with a magenta ring, three cyan cargo bricks waiting in a diagonal line, and a small healthy pod far away." width="1600" height="873" decoding="async">
-  <div class="s23-pulse" id="pulse"></div>
-  <div class="cap">Scene 23 &middot; the jammed intake &middot; motion: the only breathing still on the page</div>
-</div></div>
-
-<div class="traps">
-<p><b>"The registry is up" is not "the mirror works."</b> The worst incident in this
-mirror's life: an in-flight upstream sync wedged, and from then on EVERY pull of ANY
-image from that upstream hung &mdash; while the registry's health endpoint returned 200
-the entire time. The log line, when found, was almost poetic:</p>
-</div>
-
-<div class="pane-k">Read-only pane &middot; replay 23b &middot; the deadlock</div>
+<div class="pane-k">Replay &middot; observed 2026-07-07 &middot; the stalled sync</div>
 <pre class="pane">"image already demanded, waiting on channel"
-$ kubectl -n zot rollout restart deploy zot   <span class="cm">&lt;- the fix, instantly effective</span>
-<span class="cm"># probe an actual manifest, not the health endpoint:</span>
-$ curl -sI https://zot.bztmon.org/v2/library/busybox/manifests/latest
-<span class="good">HTTP/2 200</span>                                    <span class="cm">&lt;- THIS is "the mirror works"</span></pre>
+$ kubectl -n zot rollout restart deploy zot   <span class="cm">&lt;- recovery action (not a root cause)</span>
+<span class="cm"># probe an actual manifest, not the process's opinion of itself:</span>
+$ curl -sfS --max-time 10 -o /dev/null -w '%{http_code}\n' \
+    https://zot.bztmon.org/v2/library/busybox/manifests/latest \
+    -H 'Accept: application/vnd.oci.image.index.v1+json'
+<span class="good">200</span>                                           <span class="cm">&lt;- THIS is "the mirror works"</span></pre>
 
-<div class="traps">
-<p>Monitor the thing you actually need &mdash; a manifest fetch &mdash; not the process's
-opinion of itself.</p>
-<p><b>Digests can change in transit.</b> A mirror that converts image formats on sync
-breaks every digest pin and signature downstream of it &mdash; silently. The pairing
-that prevents it (<code style="font-family:var(--mono)">preserveDigest</code> +
-<code style="font-family:var(--mono)">http.compat</code>) is exactly the pairing from
-the chapter-02 crashloop. One decision, two scars.</p>
-<p><b>The cache grows until the disk ends.</b> onDemand means every image anyone ever
-pulls joins the shelf, and this registry does not evict least-recently-used blobs on
-its own &mdash; garbage collection reclaims orphaned data, not old-but-valid images.
-The receipt from the lab's live config: the storage section carries gc settings and
-NO retention section at all. That is a real answer &mdash; the current policy is "keep
-everything", chosen implicitly, and the 50-gigabyte volume has never yet been pushed
-to its high-water mark, so what happens there remains genuinely unobserved. A volume
-size is a budget, not a policy, and the two retention behaviours on this page &mdash;
-this one and the keep-rule inversion below &mdash; are ONE open policy decision: say
-explicitly what is kept, what is deletable, and what happens when the disk fills,
-before the disk answers for you.</p>
-<p><b>Retention flips its meaning on the first rule.</b> No retention policy: keep
-everything. ONE keep-rule on one repo: everything not matching is now DELETABLE.
-Adding a policy is not narrowing &mdash; it is inverting. Write explicit keep coverage
-per repo pattern, or write none &mdash; and read this trap together with the
-cache-growth one above; they are the two halves of the same unanswered question.</p>
-<p><b>Dedupe is not a toggle.</b> Flipping it on existing storage triggers a full
-relink pass under lock &mdash; pushes can hang half an hour behind it. Maintenance
-window, or leave it alone.</p>
-<p><b>A tag and a digest in the same reference used to miss the cache &mdash; and this
-trap carries its own moral about traps.</b> The historical mechanism: the runtime
-routes to mirrors by HOST, so the combined reference reached the mirror, which
-rejected it as unresolvable ("repository name not known", upstream issue zot 2584),
-and the runtime fell through to the origin &mdash; the fallback that saves chapter 02
-quietly defeating the cache. Re-tested against this lab's current registry on
-2026-08-24: the combined reference now pulls clean; the failure did not reproduce on
-v2.1.17. The rule survives in weaker form &mdash; prefer one reference form, know your
-version &mdash; but the stronger lesson is that a trap list is perishable. Re-run your
-own scars occasionally; some of them have healed.</p>
-<p><b>Credentials drift when the hash and the plaintext live apart.</b> The push
-credential is stored hashed; the drift surfaced on the first of July &mdash; plaintext
-lost, hash still standing &mdash; and with no way to prove or re-mint the pair, pushes
-stayed dead until the rebuilt rotation flow landed on the thirteenth. Twelve days.
-The receipt that it worked: three separate applications shipped to the fleet the
-SAME day the credential came back. Now hash and plaintext live side by side in the
-secret store, rotated together, by a human &mdash; the sync identity is deliberately
-read-only and CANNOT write secrets, so no automation can half-rotate them again.</p>
-<p><b>The cache is invisible in the UI.</b> The web interface shows pushed
-repositories only; on-demand cached images do not appear. Cosmetic &mdash; but the
-first time you look, you will conclude the mirror is empty. Verify with the API
-(<code style="font-family:var(--mono)">/v2/&lt;name&gt;/tags/list</code>), not the browser.</p>
-</div>
+<p>Honesty about that incident, upgraded by reading the source: the log line is
+<em>coalescing by design</em> - concurrent requests for one image join the first sync
+rather than duplicating it, and since the deployed version syncs run on a detached
+background context with a three-hour default timeout, surviving client disconnects.
+Waiters blocking on a genuinely stalled sync until that timeout is consistent with what we
+saw; the restart was a recovery action, and the root cause was never isolated. Two knobs
+this config does not currently set - sync <code>maxRetries</code> (disabled by default
+upstream) and a tighter <code>syncTimeout</code> - are the first things a recurrence should
+change.</p>
 
-<h2><span class="n">04</span>The prod translation &mdash; same organ, grown up</h2>
+<p>What this deployment actually exposes, verified against the running version's source:
+<code>/livez</code>, <code>/readyz</code> and <code>/startupz</code> exist as real health
+endpoints (absent from the docs at this version - a documentation gap, not an invention),
+alongside the spec's <code>/v2/</code>. The Prometheus metrics extension exists upstream
+(real series names include <code>zot_http_requests_total</code>,
+<code>zot_repo_storage_bytes</code>, <code>zot_repo_downloads_total</code>,
+<code>zot_storage_lock_latency_seconds</code>) - and is <strong>not enabled in this
+deployment</strong>. Wiring it, with scrape auth, is on the open list; no dashboard here
+pretends otherwise.</p>
+
+<p>The layered checks that would actually mean something, each answering one question:</p>
+
+<div class="tablewrap"><table>
+<tr><th>Check</th><th>Question it answers</th><th>Status here</th></tr>
+<tr><td><code>/livez</code> / <code>/readyz</code></td><td>is the process up / initialised</td><td><span class="st ok">available</span></td></tr>
+<tr><td>authenticated manifest GET of a local-only canary</td><td>can the right identity read real content from local storage</td><td><span class="st prop">proposed</span></td></tr>
+<tr><td>anonymous GET of the canary expecting 401</td><td>is the protection actually protecting</td><td><span class="st prop">proposed</span></td></tr>
+<tr><td>original-reference pull on a cold node + mirror log line</td><td>is the runtime actually routed through the mirror</td><td><span class="st prop">proposed</span></td></tr>
+<tr><td>digest pull with upstream blocked (disposable env)</td><td>does "cached" mean "served locally"</td><td><span class="st open">open - section 06</span></td></tr>
+<tr><td>PVC usage + growth, GC activity, sync latency</td><td>when does capacity or eviction become the story</td><td><span class="st prop">needs metrics ext</span></td></tr>
+<tr><td>certificate expiry, credential age</td><td>what breaks on a schedule</td><td><span class="st prop">proposed</span></td></tr>
+</table></div>
+
+<p>The test matrix for the caching claims - each cell is an experiment, not an assumption
+(status: the two digest rows are documented upstream and consistent with observed
+behaviour here; the disconnected rows have not been run in this lab):</p>
+
+<div class="tablewrap"><table>
+<tr><th>Scenario</th><th>Expected on v2.1.17</th><th>What proves it</th></tr>
+<tr><td>cached tag, upstream reachable</td><td>served; upstream contacted anyway (revalidation)</td><td>zot log shows upstream request; latency includes round-trip</td></tr>
+<tr><td>cached tag, upstream unreachable</td><td>fails or stalls until timeout, then local fallback path</td><td>pull timing vs sync timeout; error text</td></tr>
+<tr><td>cached digest, upstream reachable</td><td>served locally, no upstream contact</td><td>absence of upstream request in zot logs during the pull</td></tr>
+<tr><td>cached digest, upstream unreachable</td><td>served locally - IF the entry survived GC</td><td>the section-06 disposable-instance drill</td></tr>
+<tr><td>cold node, warm mirror</td><td>mirror serves; node store fills</td><td>mirror log + no origin egress</td></tr>
+<tr><td>warm node, evicted mirror entry</td><td>pull succeeds from node store - masking the eviction</td><td>this is the false-pass: only mirror-side inspection reveals it</td></tr>
+<tr><td>multi-arch index + child manifests</td><td>index and per-platform manifests are separate cache entries</td><td>per-digest existence checks on the mirror</td></tr>
+</table></div>
+
+<h2 id="production"><span class="n" aria-hidden="true">09</span>The production translation</h2>
 
 <div class="scene" id="s24"><div class="inner">
-  <img src="__M24__" alt="A monolithic armoured vault with a glowing wall of bricks visible through its parted door, attended by four small self-sufficient way-stations each holding its own bricks." width="1600" height="873" decoding="async">
-  <div class="cap">Scene 24 &middot; the vault and the way-stations &middot; motion: two-plane parallax, calm authority</div>
+  <img src="__M24__" alt="A monolithic vault with a wall of glowing bricks visible through its door, attended by four smaller self-sufficient way-stations - a central release source and site-local mirrors.">
+  <div class="cap">A central curated source and site-local registries: each site holds its own shelf, so a cut WAN idles nothing.</div>
 </div></div>
 
-<p>Everything above is one lab, one node, one cache. Scale the pattern honestly and
-it becomes the supply chain of every disconnected or edge estate:</p>
+<p>The first edition of this section asserted what "production" does. That was the wrong
+register: production chooses from patterns against requirements. The honest version:</p>
+
 <ul>
-<li><b>The mirror lives on real storage</b> &mdash; an appliance with parity and
-snapshots, because at a disconnected site the mirror is not an optimisation, it is
-the only source of software that exists.</li>
-<li><b>Each remote site runs its OWN small node</b>, pulling from the central mirror
-on a schedule, so a site survives its WAN link dying with its full catalogue local.</li>
-<li><b>Authentication is day one</b>, not phase two &mdash; the lab's staged flip is
-what retrofitting looks like; greenfield does not get that luxury or that risk.</li>
-<li><b>Promotion is by digest, not by tag.</b> Production estates rewrite image
-references to pinned digests and promote by copying digests between registries &mdash;
-a tag is a suggestion, a digest is a fact. The lab's digest-pinning discipline is
-the same muscle at one-tenth the ceremony.</li>
+<li><strong>Single registry, accepted failure domain</strong> - exactly this lab's shape.
+Legitimate wherever a mirror outage degrades to origin pulls (fallback on) or to a paused
+deploy window (fallback off) and that cost is accepted in writing.</li>
+<li><strong>Sync-based HA</strong> - upstream documents active/standby and active/active
+pairs of <em>independent</em> zot instances, each with its own storage, mirroring each
+other behind a load balancer; the documented caveat is the synchronisation window between
+polls, which bounds what a failover can lose.</li>
+<li><strong>Scale-out clustering</strong> - upstream's other documented shape: instances
+shard repositories by hash and proxy to the owner, classically over shared S3-compatible
+storage. That is horizontal scale for load; the shared storage is then the availability
+story, which is a different property than the HA pair above. Naming which property you are
+buying is the design act.</li>
+<li><strong>Edge estates</strong> - a central curated source promotes releases by digest;
+each site runs a small local registry holding its release set, synced on a schedule, so a
+severed WAN idles nothing at pull time. A disconnection claim is only valid when the
+required content, its referrers if policy demands them, trust roots, credentials and the
+registry's own bootstrap image are already local - the checklist from diagram D, applied
+per site.</li>
 </ul>
 
-<div class="note"><span class="k">FIELD NOTE &middot; LOOP 1 DOES NOT SURVIVE THE AIRGAP</span><br>
-The lab's prettiest trick &mdash; mirror listed, origin implicit, the loop that breaks
-itself &mdash; assumes an upstream EXISTS to fall through to. At a genuinely
-disconnected site there is no second endpoint; if the mirror's own image is not
-already on the host, nothing will ever fetch it. Production answers this the
-unglamorous way: the mirror's image is pre-seeded into the host's local image store
-at provisioning time (or run as a static workload imported straight from disk), or
-Loop 2's recovery-box pattern is applied to the mirror itself &mdash; its image kept
-OFF the platform it serves. Loop 1's implicit fallback is a connected-world luxury;
-the airgap makes you choose Loop 2's discipline whether you like it or not.</div>
+<p>Whatever the topology: recovery time and recovery point get numbers before an incident
+provides them; backups are restore-tested copies off the failure domain (array snapshots
+and RAID protect against disks, not against the array, the site, or an operator error -
+they are inputs to a backup strategy, not the strategy); capacity is planned against the
+retention policy from section 06, because "how big does the cache get" is a policy output,
+not a guess; and the circular dependencies from section 04 are drawn per site, because
+every one of them exists at every scale - the only thing that changes is how expensive
+they are to ignore.</p>
 
-<div class="diagram"><span class="k">Diagram D3 &middot; hub and spokes, WAN cut</span>
-<svg viewBox="0 0 760 230" role="img" aria-label="A central vault serving three sites; one site's WAN link is severed and that site still serves locally from its own shelf.">
-  <defs><marker id="c" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#3fbaf5"/></marker></defs>
-  <g font-family="IBM Plex Mono" font-size="11" text-anchor="middle">
-  <rect x="320" y="20" width="120" height="60" rx="8" fill="none" stroke="#e879f9"/><text x="380" y="46" fill="#dfe6f0">central</text><text x="380" y="62" fill="#dfe6f0">vault</text>
-  <rect x="60"  y="150" width="130" height="52" rx="8" fill="none" stroke="#3fbaf5"/><text x="125" y="172" fill="#dfe6f0">site A node</text><text x="125" y="188" fill="#8b95a7">own shelf</text>
-  <rect x="315" y="150" width="130" height="52" rx="8" fill="none" stroke="#3fbaf5"/><text x="380" y="172" fill="#dfe6f0">site B node</text><text x="380" y="188" fill="#8b95a7">own shelf</text>
-  <rect x="570" y="150" width="130" height="52" rx="8" fill="none" stroke="#3fbaf5"/><text x="635" y="172" fill="#dfe6f0">site C node</text><text x="635" y="188" fill="#8b95a7">own shelf</text>
-  <line x1="340" y1="80" x2="150" y2="145" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#c)"/>
-  <line x1="380" y1="80" x2="380" y2="145" stroke="#3fbaf5" stroke-dasharray="5 4" marker-end="url(#c)"/>
-  <line x1="420" y1="80" x2="600" y2="140" stroke="#e879f9" stroke-dasharray="2 6"/>
-  <text x="540" y="100" fill="#e879f9" font-size="14">&#10007;</text><text x="560" y="118" fill="#e879f9">WAN cut</text>
-  <text x="635" y="222" fill="#7fe0a7">still serving, local shelf</text>
-  <text x="230" y="120" fill="#8b95a7">scheduled sync</text></g>
-</svg>
-<p class="why">The decision this explains: per-site nodes exist so a cut link idles
-NOTHING &mdash; pulls never cross the WAN at pull time at all.</p></div>
-
-<div class="clause"><span class="k">THE HOMELAB CLAUSE, INVERTED</span><br>The lab is
-not a toy version of production. It is production with one of everything. The loops
-in chapter 02 exist at every scale; the only thing that changes is how expensive
-they are to ignore.</div>
-
-<h2><span class="n">05</span>Close &mdash; the canary</h2>
+<h2 id="verified"><span class="n" aria-hidden="true">10</span>Verified, open, and where the claims come from</h2>
 
 <div class="scene" id="s25"><div class="inner">
-  <img src="__M25__" alt="A wide flat node slab in the lower third of an otherwise empty void; a single luminous brick hovers midway in its descent toward the slab; a small pod watches from the edge." width="1600" height="873" decoding="async">
-  <div class="cap">Scene 25 &middot; the canary &middot; motion: none. Deliberately.</div>
+  <img src="__M25__" alt="A wide flat node slab in an otherwise empty void; a single luminous brick hovers midway in its descent toward the slab - one small transfer of bytes as proof of life.">
+  <div class="cap">Proof of life is one authenticated byte transfer through the real path - not a status page.</div>
 </div></div>
 
-<p>The mirror's proof-of-life is not a dashboard. When a node powers on, the fleet's
-gate makes it pull one known, first-party, mirror-only image through its own runtime
-&mdash; the same path a real workload would take, auth and all. Pass, and the node is a
-member of the fleet. Fail, and it is a machine that happens to be switched on.</p>
+<p>When a node powers on, this fleet's gate makes it pull one known, first-party image
+through its own runtime before it counts as a member. That gate is the whole page in
+miniature: prove the path, not the process.</p>
 
-<div class="sayit"><span class="k">SAY IT</span>A node is not "up" when it pings. A
-node is up when it can feed itself.</div>
+<div class="tablewrap"><table>
+<caption class="mono" style="text-align:left;color:var(--ink-dim);font-size:.78rem;padding-bottom:.4rem">Architecture decisions</caption>
+<tr><th>Decision</th><th>Chosen</th><th>Why</th><th>Trade-off</th><th>Rollback / alternative</th><th>Status</th></tr>
+<tr><td>Origin fallback</td><td>ON (default kept)</td><td>bootstrap survivability, Loop 1</td><td>silent mirror bypass possible</td><td>skipFallback:true + preseed (airgap shape)</td><td><span class="st ok">observed</span></td></tr>
+<tr><td>Sync mode</td><td>onDemand, all upstreams</td><td>cache follows real usage; Hub-safe</td><td>tag pulls revalidate upstream; digest entries untagged</td><td>polled sync for a curated release set</td><td><span class="st ok">observed</span></td></tr>
+<tr><td>Digest preservation</td><td>preserveDigest + docker2s2, x5</td><td>digest pins + signatures survive mirroring</td><td>mandatory config pairing (crashloop scar)</td><td>none - non-negotiable for digest-pinned estates</td><td><span class="st ok">observed</span></td></tr>
+<tr><td>Namespace layout</td><td>flat (no destinations)</td><td>simplicity at build time</td><td>ordered-trial upstream selection; theoretical collisions</td><td>per-origin destinations + overridePath</td><td><span class="st prop">redesign proposed</span></td></tr>
+<tr><td>Retention</td><td>none configured</td><td>predates understanding the untagged rule</td><td>digest-only entries evict within hours</td><td>v2.1.19+ keepUntagged; interim wider gcDelay</td><td><span class="st open">correction owed</span></td></tr>
+<tr><td>Auth</td><td>anonymous read until per-node proof</td><td>containerd 401-fallback unreliability makes big-bang flips dangerous</td><td>window with no pull auth</td><td>staged flip w/ canary gate + named rollback</td><td><span class="st open">in flight</span></td></tr>
+<tr><td>Metrics</td><td>not enabled</td><td>minimal first deployment</td><td>capacity/eviction invisible</td><td>metrics extension + scrape auth</td><td><span class="st prop">proposed</span></td></tr>
+</table></div>
 
-<p>That is the whole dossier in one sentence. A platform is a chain of machines
-feeding each other bytes, and the mirror is the pantry. Stock it deliberately, prove
-it constantly, and never let the recovery crew depend on it for lunch.</p>
+<h3 id="open">Open verification register</h3>
+<ol>
+<li>Digest-entry eviction reproduction in a disposable instance (section 06 procedure).</li>
+<li>Canary repo negative test: anonymous 401 on <code>canary/**</code> while anonymous
+read elsewhere still succeeds; observed 401-vs-403 boundaries recorded.</li>
+<li>Mirror interception proof: original-reference pull on a cold node correlated with the
+mirror's request log.</li>
+<li>Disconnected-serve drill: cached digest pull with upstream blocked, disposable
+environment first.</li>
+<li>Upgrade evaluation: v2.1.19/v2.1.20 for <code>keepUntagged</code>, with the retention
+config written and reviewed before the upgrade, not after.</li>
+<li>Namespace redesign migration plan (per-origin destinations + overridePath), including
+cache re-warm cost.</li>
+</ol>
+
+<h3 id="refs">Verified against</h3>
+<ul class="refs">
+<li>zot documentation (versioned): <a href="https://zotregistry.dev/v2.1.18/articles/retention/">retention</a> &middot; <a href="https://zotregistry.dev/v2.1.18/articles/storage/">storage</a> &middot; <a href="https://zotregistry.dev/v2.1.18/articles/mirroring/">mirroring</a> &middot; <a href="https://zotregistry.dev/v2.1.18/articles/authn-authz/">authn/authz</a> &middot; <a href="https://zotregistry.dev/v2.1.18/articles/high-availability/">high availability</a> &middot; <a href="https://zotregistry.dev/v2.1.18/articles/scaleout/">scale-out</a></li>
+<li>zot upstream issues/PRs: <a href="https://github.com/project-zot/zot/issues/4148">4148 digest-only eviction</a> &middot; <a href="https://github.com/project-zot/zot/pull/4191">4191 keepUntagged (v2.1.19)</a> &middot; <a href="https://github.com/project-zot/zot/issues/4128">4128 tag revalidation</a> &middot; <a href="https://github.com/project-zot/zot/issues/4187">4187 containerd ns param</a> &middot; <a href="https://github.com/project-zot/zot/issues/2928">2928 mixed anonymous auth</a> &middot; <a href="https://github.com/project-zot/zot/issues/2505">2505 demand coalescing</a></li>
+<li>Talos: <a href="https://docs.siderolabs.com/talos/v1.13/configure-your-talos-cluster/images-container-runtime/pull-through-cache">pull-through registry cache (v1.13)</a> &middot; containerd: <a href="https://github.com/containerd/containerd/blob/main/docs/hosts.md">registry hosts and the ns parameter</a></li>
+<li>OCI: <a href="https://github.com/opencontainers/distribution-spec/blob/main/spec.md">distribution spec</a> &middot; <a href="https://opencontainers.org/posts/blog/2024-03-13-image-and-distribution-1-1/">image/distribution 1.1 (referrers)</a> &middot; signing: <a href="https://docs.sigstore.dev/cosign/verifying/verify/">cosign verify</a></li>
+<li>Docker Hub <a href="https://docs.docker.com/docker-hub/usage/">usage and limits</a> &middot; buildah <a href="https://github.com/containers/buildah/blob/main/docs/buildah-build.1.md">build --retry semantics</a></li>
+</ul>
 
 <footer>
-  DOSSIER / 005 &middot; rev 3 &middot; source of truth: the running lab &middot; one open
-  verification: negative-test the canary repo before Phase B leans on it. Motion is
-  plate-level v1; per-part sliced animation arrives in a later revision.
-  <a href="/">Back to the index</a>
+  DOSSIER / 005 &middot; last validated 2026-08-25 against the running estate and the
+  sources above &middot; corrections in this revision: retention/GC semantics, warm-cache
+  guarantees, retry arithmetic, upstream namespace routing &middot;
+  <a href="/">The Teaching Lab</a> &middot; <a href="https://git.bztmon.com/jwright/exploded-cluster">source</a>
 </footer>
 
 </div>