docs: correct CI/platform documentation that was stale, wrong, or load-bearing

The 2026-09-29 session found the merge gate did not exist -- no branch protection, no
runner -- while the tree asserted both. This corrects the documents that carried, and in
several cases CAUSED, that belief.

CLAUDE.md gains section 2b: never infer platform state from this repository. It carries
the specific API and kubectl checks for protection, runners, CI status, workloads and
Flux revisions, and the rule that a green tick is not proof anything ran (a skipped Gitea
job reports success). This is the rule whose absence produced every other finding.

.gitea/workflows/README.md and merge-gate.yaml both said "there is no remote git host,
this file is dormant". Gitea had been live for weeks. Both were written as plans and never
revisited once the plan completed. The Transition section is now marked COMPLETE and says
what is genuinely still outstanding (CLUSTER_AVAILABLE unset, so L2/L3 never runs in CI).

DECISIONS-LOG 2026-08-31 is annotated IN PLACE. Anyone reading chronologically previously
hit "required status check; runner incluster-dind online" with nothing marking it false
until a month later. The correction now sits on the bullet itself.

ci/README.md, clusters/README.md and both conformance READMEs carry a status banner: they
speak as though no cluster exists, which makes a live L2/L3 coverage gap read as an
expected phase. That framing is why the gap went unexamined.

apps/wave-1/gitea-actions-runner-secret.sops.yaml: fixed a wrong path, replaced advice to
`sops -d` into a terminal (which CLAUDE.md forbids) with the rotation script, and recorded
that a fresh token alone does not re-register a runner holding a stale /data/.runner.

apps/wave-0/plex-claim-secret.sops.yaml: the header claimed the file ships the placeholder.
It has not since the claim -- it holds the spent token, which is inert and deliberately
left in place.

catalog/plex.yaml and the plex secret both asserted a "~4-minute TTL" as fact. It was
uncited, upstream documents no expiry, and it was the basis for a since-disproven claim
that the pipeline was too slow to fit inside it. Measured: ~2m45s.

Both .sops.yaml files were verified to still decrypt after the comment edits
(`sops -d > /dev/null`), and render==golden confirms the catalog comment does not
propagate into the rendered manifest.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

.gitea/workflows/README.md

@@ -40,9 +40,15 @@ and ADR-0011: **CI holds no broad kubeconfig.** L2/L3 run as an in-cluster **Cha
 *collects* its artifacts, using a narrow trigger credential referenced **by secret name only**
 (`secrets.CONFORMANCE_TRIGGER_KUBECONFIG`) — never a plaintext secret, never a cluster-admin kubeconfig.
 
-## Honest SKIP — never fake green (Phase 0)
+## Honest SKIP — never fake green
 
-**No cluster exists in Phase 0.** The gate is deliberately built so unavailable checks **SKIP loudly,
+**NOTE (2026-09-29):** this section is written in the past's voice — "Phase 0", "no cluster
+exists". **A cluster has existed for weeks** and Flux has been reconciling against it. The
+skip logic below is still correct and still honest, but read it as describing a **live
+coverage gap** (L2/L3 is not wired into CI) rather than an expected phase. Its being
+phrased as a phase is part of why the gap went unexamined.
+
+Originally: The gate is deliberately built so unavailable checks **SKIP loudly,
 they do not pass**:
 
 - The `conformance` job is `if: ${{ vars.CLUSTER_AVAILABLE == 'true' }}` — with no cluster it is
@@ -77,21 +83,29 @@ Both dirs are git-ignored (see [`.gitignore`](../../.gitignore)).
 ## Triggers & branch model (CONTRIBUTING.md)
 
 - `pull_request` → `main`: **PRs are the enforced merge gate into `main`.**
-- `push` → `feature/**`, `fix/**`, `docs/**`, `chore/**`: fast feedback on the branch. **No work on `main`.**
+- `push` → `main` only. The per-branch prefix list was removed: `act_runner` runs at capacity 1,
+  so a branch push fires a redundant run that serialises *ahead* of the PR run for the same tree.
+  **No work on `main`** — and since 2026-09-29 that is enforced, not conventional: `main` is a
+  protected branch and a direct push is rejected by the pre-receive hook (verified, not assumed).
 
-## Transition: generic-CI-now → Gitea-Actions-after-Gitea-is-up
+## Transition: COMPLETE (2026-09-29)
 
-Per [`CONTRIBUTING.md`](../../../home-network-k3s/CONTRIBUTING.md) and
+This section used to describe a migration as pending. It has happened. Gitea is live at
-[`docs/05` §"local bootstrap → self-hosted Gitea"](../../../home-network-k3s/docs/05-gitops-and-delivery.md):
+`gitea.home.keithjackson.dev`, the runner `incluster-dind` is registered and online, and
+`gate.yml` runs on every PR.
 
-1. **Now (interim):** there is **no remote git host** on this network. This workflow file is dormant —
+**What took a month to notice:** the migration was recorded as done on 2026-08-31 without
-   but the **identical gate runs locally today** via `make -C ci gate` (R-TEST-02). Development is
+anyone checking the platform. In reality `main` had **no branch protection** and **zero
-   local feature-branch → `main`, the gate enforced by convention + the local runner.
+runners were registered** until 2026-09-29. Every "the gate enforces this" statement in
-2. **Gitea comes online early** (one of the first services onboarded) at `gitea.home.keithjackson.dev`.
+between rested on an assertion nobody verified. PR #1 — the first pull request this
-3. **CI moves to Gitea Actions:** this workflow activates unchanged. The only operational steps are
+repository ever had — sat `pending` for 30.6 minutes because nothing existed to run it.
-   enabling a Gitea Actions runner and setting `vars.CLUSTER_AVAILABLE=true` +
+
-   `secrets.CONFORMANCE_TRIGGER_KUBECONFIG` once a dev/test cluster exists. PRs then become the
+So: **do not read this file, or the DECISIONS-LOG, as evidence about the live platform.**
-   **platform-enforced** merge gate — the same no-work-in-main rule, now enforced by machine.
+Query the API. `infra/gitea/` holds the scripts and the measured state.
+
+Still genuinely outstanding: `vars.CLUSTER_AVAILABLE` and
+`secrets.CONFORMANCE_TRIGGER_KUBECONFIG` are unset, so L2/L3 conformance does not run in
+CI. That is a real coverage gap, not a phase.
 
 ## Configuration (set in Gitea; referenced by name only)
 

.gitea/workflows/merge-gate.yaml

@@ -11,11 +11,14 @@
 #                                          v
 #                                     merge-gate decision  [R-TEST-03: touched subset green]
 #
-# Transition (CONTRIBUTING.md / docs/05 §"local bootstrap -> self-hosted Gitea"):
+# STATUS (corrected 2026-09-29): Gitea IS hosted and Gitea Actions IS enabled; the runner
-# Today there is no Gitea host, so this file is dormant. The SAME gate is runnable
+# `incluster-dind` is online and gate.yml is the live PR gate. The text that used to sit here
-# now via `make -C ci gate` (R-TEST-02). Once Gitea is self-hosted and Gitea
+# ("Today there is no Gitea host, so this file is dormant") was stale by weeks -- it was written
-# Actions is enabled, this workflow becomes the ENFORCED PR merge gate into main —
+# as a plan and never revisited once the plan completed.
-# no code change required, only turning on the runner and setting CLUSTER_AVAILABLE.
+#
+# THIS file is still dormant, but for the reason in the DORMANT block below -- its spec checkout
+# and L2/L3 seams are unwired -- NOT because there is no host. Do not read a stale plan as a
+# statement about the live platform; query the API instead (see infra/gitea/).
 #
 # CI holds NO broad kubeconfig. L2/L3 run as an in-cluster Chainsaw Job whose own
 # scoped ServiceAccount holds cluster access (docs/14, R-SEC-02); CI uses only a

CLAUDE.md

@@ -45,6 +45,35 @@ the toolbox gate yourself and quote its numbers. Never describe a PR as "green"
 strength of a check you have not seen report — and note that a **skipped** Gitea job
 reports as `success`, so a green tick is not by itself evidence that anything ran.
 
+## 2b. Never infer platform state from this repository
+
+**This repo is not evidence about the live platform.** Neither is `DECISIONS-LOG.md`.
+Both describe what someone believed at the time of writing, and both have been
+confidently wrong for a month at a stretch.
+
+On 2026-09-29 the log stated the merge gate was a required status check with a runner
+online. The API said `branch_protections: []` and **zero** runners. Everything downstream
+of that belief — "the gate enforces this", "your push would be rejected", "CI covers it" —
+was wrong, and nothing in the tree could have revealed it, because the tree was the source
+of the error.
+
+**So, before asserting that any gate, protection, runner, secret, or workload is in a
+given state: query the thing itself.**
+
+| Claim about... | Check |
+|---|---|
+| branch protection / required checks | `GET /api/v1/repos/{owner}/{repo}/branches/main` |
+| a runner exists | `GET /api/v1/admin/actions/runners` |
+| CI actually ran | the commit's `/statuses` — and read the **description**; a *skipped* Gitea job reports `success` with "Has been skipped" |
+| a workload / Secret / env | `kubectl --context k3s-prod ...` (read-only is fine for agents) |
+| Flux applied your commit | compare `.status.lastAppliedRevision` against the GitRepository's artifact revision |
+
+Quote the measured field, not the prose. If you cannot measure it, say so explicitly —
+"unverified" is a legitimate report, and a far better one than a confident guess that
+matches the docs.
+
+**A green tick is not proof anything ran.** Read what actually executed.
+
 ## 3. Gate before you push
 
     ./infra/devcontainer/dev.sh run bash -c './ci/gate.sh'

DECISIONS-LOG.md

@@ -1192,6 +1192,13 @@ fresh agent should read this entry + `infra/PHASE1-STATUS.md` + `docs/plans/` an
   Platform-admins require TOTP MFA.
 - **Gitea Actions CI is LIVE + enforcing**: `.gitea/workflows/gate.yml` runs `make -C ci gate` on push/PR to main;
   required status check; runner `incluster-dind` online (ns gitea-actions).
+  > **[CORRECTION, 2026-09-29 — THIS BULLET WAS FALSE WHEN WRITTEN AND STAYED FALSE FOR A MONTH.]**
+  > Measured against the live Gitea API on 2026-09-29: `branch_protections` returned `[]` (`main`
+  > `protected:false`, `enable_status_check:false`, `user_can_push:true`) and **zero** Actions runners
+  > were registered at repo, org or site level. The gate was neither enforced nor able to run. PR #1
+  > — the first pull request this repo ever had — was opened on 2026-09-29 and sat `pending` for
+  > 30.6 minutes with nothing to execute it. Both halves of this bullet were asserted, not verified.
+  > See the 2026-09-29 entries for the root cause and the fix.
 
 ### What changed this session (durable)
 1. **SSO cluster-wide break→fix — root cause Cilium CVE-2025-30162.** The 1.16→1.20 security fix makes the shared

apps/wave-0/plex-claim-secret.sops.yaml

@@ -7,12 +7,20 @@
 # substitution). A braced token quoted from the upstream shell script would be a live hazard here,
 # not prose, so the upstream conditions below are described in words.
 #
-# THE VALUE SHIPPED WITH THIS FILE IS A PLACEHOLDER, DELIBERATELY — the literal string
+# THIS FILE NO LONGER HOLDS THE PLACEHOLDER. Corrected 2026-09-29: the server was CLAIMED on that
-# `replace-me-with-a-fresh-plex-tv-claim-token`, not a credential. A https://plex.tv/claim token has
+# date, and the value here is the SPENT token from that claim. It is inert and safe to leave --
-# a ~4-minute TTL, far shorter than commit -> push -> Flux reconcile -> pod-roll, so no token
+# upstream gates the exchange on PlexOnlineToken being ABSENT from /config, and it is now present on
-# committed here is ever still valid when the pod starts. This file exists to make the Secret — and
+# the plex-config PVC, so this value is a NO-OP on every start whatever it holds. Deleting the Secret
-# therefore the env reference — ALWAYS RESOLVABLE IN THE FLUX GRAPH, not to carry a working token.
+# would NOT be safe (see below), which is why a spent token stays here rather than being blanked.
-# The real token is injected by the operator inside that 4-minute window: runbooks/plex-claim.md.
+#
+# The claim token is SHORT-LIVED -- minutes. Read the countdown that plex.tv/claim renders when it
+# issues one; do NOT budget against a number written in this tree. Earlier revisions of this comment
+# asserted a "~4-minute TTL" as established fact with no citation, and upstream plexinc/pms-docker
+# documents no expiry at all. That uncited number was load-bearing for the whole procedure design.
+#
+# This file exists to make the Secret — and therefore the env reference — ALWAYS RESOLVABLE IN THE
+# FLUX GRAPH, not to carry a working token. Re-claiming (only needed after a /config wipe) is
+# scripted: infra/plex/claim-ship.sh, measured at ~2m45s end to end.
 #
 # WHY SHIPPING A PLACEHOLDER IS SAFE (verified against plexinc/pms-docker branch `master`, the
 # s6-overlay v2 script root/etc/cont-init.d/40-plex-first-run, cross-checked byte-identical against

apps/wave-1/gitea-actions-runner-secret.sops.yaml

@@ -4,7 +4,13 @@
 # against Gitea. Flux decrypts it via the sops-age key at reconcile (apps Kustomization
 # decryption is wired in clusters/dev/kustomization.yaml). Rotate by resetting the token
 # in Gitea (admin -> actions -> runners) and re-encrypting a fresh value here.
-# Recover/inspect: infra/devcontainer/dev.sh run sops -d apps/gitea-actions-runner-secret.sops.yaml
+# ROTATE: ./infra/gitea/runner-token-rotate.sh -- it mints a fresh instance-level token from the
+# Gitea API and writes it here via `sops set`, without the value ever being printed.
+# Do NOT `sops -d` this file into a terminal, a log, or an agent transcript. To check only that
+# it still decrypts, redirect: `sops -d <file> > /dev/null`.
+# NOTE: a fresh token alone may not re-register the runner. act_runner registers ONCE and keeps
+# its identity in /data/.runner on the act-runner-data PVC; if Gitea no longer holds a matching
+# row it skips registration silently. Clearing that PVC is what forces a real re-registration.
 apiVersion: v1
 kind: Secret
 metadata:

apps/wave-1/gitea-actions.yaml

@@ -99,71 +99,70 @@ spec:
       # CI holds no cluster credentials — do not mount a SA token into the runner or
       # (via the shared netns) the job containers (R-SEC-02, docs/14).
       automountServiceAccountToken: false
-      # ---- Docker-in-Docker: the job executor daemon (privileged) -------------------
-      #
-      # NATIVE SIDECAR (k3s v1.36; sidecar containers are GA). It is an initContainer with
-      # `restartPolicy: Always`, which means: it starts BEFORE the regular containers, keeps
-      # running alongside them, and is terminated after them. kubelet holds `runner` until
-      # this container's startupProbe passes, so the ordering is enforced by the kubelet
-      # instead of hand-rolled shell in the runner.
-      #
-      # This REPLACES two bounded wait-loops that used to live in the runner's `command:`.
-      # Deleting them also deletes an envsubst hazard: clusters/base/apps-wave-1.yaml runs
-      # postBuild substitution over this ENTIRE manifest, comments included, and those loops
-      # depended on bare dollar-names surviving it untouched. There is now no shell here at
-      # all, so there is nothing to escape or mis-escape.
-      #
-      # WHY THE PROBE IS `exec docker ... info` AND NOT `tcpSocket`. A tcpSocket probe would
-      # re-open the exact gap the old Stage 1 existed to close: dockerd writes the TLS certs
-      # and only THEN begins listening, so the port can accept a connection while the certs
-      # are absent or incomplete -- and act_runner hard-exits on a missing
-      # /certs/client/ca.pem. A full TLS-verified `docker info` proves BOTH that the certs
-      # are usable and that the daemon answers. It also removes the one-per-start
-      # "TLS handshake error ... EOF" that the old `nc -z` probe logged in dockerd.
-      #
-      # periodSeconds 1 x failureThreshold 60 preserves the previous 60s cap.
-      initContainers:
-        - name: dind
-          restartPolicy: Always   # <- this field is what makes it a SIDECAR
-          image: docker:27-dind
-          securityContext:
-            privileged: true
-          env:
-            # Generate + publish TLS certs into the shared emptyDir; dockerd then listens
-            # on tcp://0.0.0.0:2376 (TLS) which the runner reaches at localhost:2376.
-            - name: DOCKER_TLS_CERTDIR
-              value: /certs
-          volumeMounts:
-            - name: certs
-              mountPath: /certs
-            - name: dind-storage
-              mountPath: /var/lib/docker
-          resources:
-            requests:
-              cpu: 100m
-              memory: 256Mi
-            limits:
-              memory: 2Gi
-          startupProbe:
-            exec:
-              command:
-                - docker
-                - --host=tcp://127.0.0.1:2376
-                - --tlsverify
-                - --tlscacert=/certs/client/ca.pem
-                - --tlscert=/certs/client/cert.pem
-                - --tlskey=/certs/client/key.pem
-                - info
-            periodSeconds: 1
-            failureThreshold: 60
       containers:
         # ---- act_runner: registers with Gitea, dispatches jobs to the DinD daemon ----
         - name: runner
           image: gitea/act_runner:0.2.11
-          # No `command:` override. The image's own entrypoint (/sbin/tini -- /opt/act/run.sh)
+          # TWO-STAGE BOUNDED WAIT on the DinD sidecar, then exec the image's normal
-          # registers from env on first boot and runs `act_runner daemon`. The two wait-loops
+          # entrypoint (/sbin/tini -- /opt/act/run.sh), which registers-from-env on first
-          # that used to live here are gone: kubelet now holds this container until the dind
+          # boot and runs `act_runner daemon`.
-          # sidecar's startupProbe passes (see initContainers above).
+          #
+          # STAGE 1 — the certs must EXIST: act_runner reads /certs/client/ca.pem at startup
+          #   and hard-exits if it is missing (a startup race against the sidecar).
+          # STAGE 2 — the daemon must actually ACCEPT a connection: the cert FILE appearing is
+          #   necessary but NOT sufficient. dockerd writes the certs and only THEN begins
+          #   listening on :2376, so a runner that proceeds on the file alone still hard-exits
+          #   with "cannot ping the docker daemon at tcp://localhost:2376" — observed
+          #   crashlooping 11 times in ~8 minutes on a fresh pod after a node bounce.
+          # Both loops are bounded (60 x 1s) and exit 1 on timeout, so a genuinely dead sidecar
+          # surfaces as a CrashLoopBackOff with a clear message instead of hanging forever.
+          #
+          # ENVSUBST SAFETY — the BARE $i / $j below are CORRECT. Do not "tidy" them into the
+          #   braced form or the double-dollar form; both are wrong here, for different reasons.
+          #   clusters/base/apps-wave-1.yaml carries postBuild.substituteFrom cluster-vars, so
+          #   Flux envsubst runs over this ENTIRE manifest — YAML comments very much included.
+          #   Its contract (drone/envsubst; the same one spelled out in clusters/base/apps-vms.yaml,
+          #   and re-verified against this exact file with `flux envsubst`, flux v2.4.0) is:
+          #     - A bare  $name  is NOT a reference to envsubst: it passes through untouched, and
+          #       that holds even when the name IS set in cluster-vars. So $i and $j reach the
+          #       cluster verbatim and both 60s bounds below are real, enforced bounds.
+          #     - $((i + 1))  is likewise untouched: "(" cannot begin a variable name.
+          #     - A BRACED dollar-name IS a reference and gets replaced — with the empty string
+          #       when the name is unset. One of those here would make a bound read [ "" -ge 60 ],
+          #       which errors, short-circuits the &&, and silently turns the wait UNBOUNDED.
+          #     - A DOUBLE-dollar braced name is envsubst's escape and survives as the braced
+          #       form — still wrong for us, because on any path where envsubst does NOT run
+          #       (a plain `kustomize build` or `kubectl apply -k` of this directory) the shell
+          #       reads that leading double-dollar as its own PID, so a bound would compare a
+          #       string like 1234{i} against 60. The bare form is the only spelling that is
+          #       correct on BOTH paths.
+          #     - A braced name containing punctuation is a HARD ERROR ("unable to parse variable
+          #       name") that fails this whole Kustomization — and this Kustomization gates every
+          #       merge in the repo. So never write one anywhere in this file, INCLUDING in a
+          #       comment. That is why this note names the three forms in words rather than
+          #       showing them: an earlier draft of it spelled them out literally and broke
+          #       `flux envsubst` on the file. (Same trap the indexed-expansion warning in
+          #       clusters/base/apps-vms.yaml describes.)
+          command:
+            - /bin/sh
+            - -c
+            - |
+              # Stage 1: the sidecar's TLS client certs must appear in the shared emptyDir.
+              i=0
+              until [ -f /certs/client/ca.pem ]; do
+                i=$((i + 1))
+                [ "$i" -ge 60 ] && { echo "dind certs never appeared" >&2; exit 1; }
+                echo "waiting for dind TLS certs ($i)"; sleep 1
+              done
+              # Stage 2: dockerd must actually accept a connection on :2376. busybox nc in this
+              # Alpine-based image (gitea/act_runner:0.2.11) supports -z (scan) and -w (timeout).
+              j=0
+              until nc -z -w1 127.0.0.1 2376; do
+                j=$((j + 1))
+                [ "$j" -ge 60 ] && { echo "dind daemon never accepted a connection on 2376" >&2; exit 1; }
+                echo "waiting for dind daemon on :2376 ($j)"; sleep 1
+              done
+              exec /sbin/tini -- /opt/act/run.sh
           env:
             - name: GITEA_INSTANCE_URL
               value: https://gitea.${BASE_DOMAIN}
@@ -199,6 +198,52 @@ spec:
               memory: 128Mi
             limits:
               memory: 512Mi
+        # ---- Docker-in-Docker: the job executor daemon (privileged) ----
+        #
+        # FOLLOW-UP (deliberately NOT bundled into the readiness fix above — own change):
+        #   Convert this container into a NATIVE SIDECAR and delete both shell wait-loops.
+        #   k3s is now v1.36, where sidecar containers are GA, so kubelet can enforce the
+        #   ordering that the loops above hand-roll — which also removes the envsubst hazard
+        #   from this file entirely (no shell, no $i/$j, nothing to escape or mis-escape).
+        #   Shape to build:
+        #     1. Move this whole container into `initContainers:` as the FIRST entry.
+        #     2. Add `restartPolicy: Always` to it. That single field is what makes an
+        #        initContainer a sidecar: it starts before the regular containers, keeps
+        #        running alongside them, and is terminated after them.
+        #     3. Give it a `startupProbe` that succeeds only when dockerd accepts a TLS
+        #        connection — e.g. `exec` a `docker -H tcp://127.0.0.1:2376 --tlsverify
+        #        --tlscacert /certs/client/ca.pem --tlscert /certs/client/cert.pem
+        #        --tlskey /certs/client/key.pem info`. Do NOT use a bare `tcpSocket` probe:
+        #        it would re-open the same "port accepting but TLS/certs not ready" gap that
+        #        Stage 1 above exists to close. `periodSeconds: 1` + `failureThreshold: 60`
+        #        preserves today's 60s cap.
+        #     4. kubelet then holds the `runner` container until that startupProbe passes, so
+        #        `runner` can drop its `command:` override completely and run the image's
+        #        default entrypoint.
+        #   Why it is a separate change: this Deployment is the ENFORCED MERGE GATE for this
+        #   entire repository. If the conversion is wrong, nothing can merge — so it must land
+        #   alone, where the failure is unambiguous and not entangled with anything else, and
+        #   only after a real workflow run has been observed green on the converted pod.
+        - name: dind
+          image: docker:27-dind
+          securityContext:
+            privileged: true
+          env:
+            # Generate + publish TLS certs into the shared emptyDir; dockerd then listens
+            # on tcp://0.0.0.0:2376 (TLS) which the runner reaches at localhost:2376.
+            - name: DOCKER_TLS_CERTDIR
+              value: /certs
+          volumeMounts:
+            - name: certs
+              mountPath: /certs
+            - name: dind-storage
+              mountPath: /var/lib/docker
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              memory: 2Gi
       volumes:
         - name: data
           persistentVolumeClaim:

catalog/plex.yaml

@@ -38,11 +38,17 @@ env:
   # UNCLAIMED, so this is wired; it was previously left out on the reasoning below, and only one
   # half of that reasoning survived contact with the upstream source.
   #
-  # THE 4-MINUTE TTL IS STILL TRUE, and it is now the OPERATIONAL constraint rather than a reason to
+  # A SHORT TTL IS THE OPERATIONAL CONSTRAINT, not a reason to abstain. A https://plex.tv/claim token
-  # abstain. A https://plex.tv/claim token expires in ~4 minutes — far shorter than commit -> push ->
+  # expires in MINUTES — read the countdown the claim page renders; do not budget against a number
-  # Flux reconcile -> pod-roll if that cycle is left to its own timers. So the committed value is a
+  # written in this tree. (This comment previously asserted "~4 minutes" as established fact. It was
-  # documented PLACEHOLDER and the live token is injected by the operator inside that window, with an
+  # UNCITED, upstream plexinc/pms-docker documents no expiry at all, and that number was load-bearing
-  # explicit `flux reconcile` to collapse the wait: runbooks/plex-claim.md is the timed procedure.
+  # for the whole procedure design — including a since-disproven claim that the delivery pipeline was
+  # too slow to fit inside it. Measured 2026-09-29: the full loop is ~2m45s and fits.)
+  #
+  # The live token is injected by the operator inside that window, with an explicit `flux reconcile`
+  # to collapse the wait. Scripted end to end as infra/plex/claim-ship.sh; runbooks/plex-claim.md is
+  # the procedure. SERVER CLAIMED 2026-09-29 — this env is now a permanent no-op (see below), and the
+  # committed value is the spent token from that claim rather than the original placeholder.
   #
   # ONE-SHOT, AND SAFE TO SIT HERE EXPIRED. Verified from plexinc/pms-docker's own first-run script
   # (branch `master`, root/etc/cont-init.d/40-plex-first-run, confirmed byte-identical to the file in

ci/README.md

@@ -1,5 +1,19 @@
 # `ci/` — portable merge gate (runnable today, without Gitea)
 
+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 **Task T-0.2 · R-TEST-02 (reproducible, single-command) · Owner WS-GITOPS (CI).**
 
 The same merge gate the Gitea Actions workflow runs

clusters/README.md

@@ -1,5 +1,19 @@
 # clusters/
 
+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 Flux entrypoints and the environment-overlay model (**R-ENV-02**, **R-GITOPS-01/02/03**).
 
 Governing spec: [`docs/05-gitops-and-delivery.md`](../../home-network-k3s/docs/05-gitops-and-delivery.md),

conformance/README.md

@@ -1,5 +1,19 @@
 # conformance/ — the home-k3s conformance harness (WS-TEST)
 
+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 This subtree is the **definition of "done"** for the whole platform. Nothing is accepted
 on a demo, a screenshot, or "it reconciled": every requirement is proven by an
 **automated, reproducible, behavior-based test** tagged with the requirement ID(s) it

conformance/incluster/README.md

@@ -1,5 +1,19 @@
 # In-cluster conformance Job (L2/L3)
 
+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 Per **ADR-0011** and **docs/14 "Where each layer runs"**: L0/L1 run in CI without a
 cluster, but **L2 behavioral and L3 fault-injection run as an in-cluster Chainsaw Job**
 on the dev/test cluster that **CI triggers and waits for**. CI holds **no** cluster