docs: publish the failure class, not just the working state

[stxkxs]

Closes the last open target in the docs-depth plan (T6). Its gate was that it could not be written ahead of a live campaign — the material is first-hand rather than imagined.

What it is

A page describing how this system fails, stated as design properties. Per the plan's D3, failure modes, not failure history — it reads as "how this behaves", never as a changelog of scars.

The dominant class is not a crash:

every object is valid, every controller is healthy, and the path through them is dead

Nodes Ready, pods Running, Applications Synced, manifests passing schema validation and policy admission — and a credential, a request, a telemetry export or a reconcile does not arrive. It dominates because a manifest gate reads whether an object is well-formed and internally consistent, which is a different question from whether it does anything.

Two properties stated up front, because they are what make it expensive:

• silence is the default symptom — a dropped telemetry export looks exactly like no traffic
• the report names the wrong component — whatever was waiting reports its own subject

The eight shapes

shape	example property
legal in the manifest, illegal where it lands	a label value has a grammar a string-typed schema does not know; a driver can reserve a key prefix
a limit not part of the manifest	an object can be valid and still be refused on grounds it cannot express
a control whose consumer is never installed	half a wiring reads as complete
two controls asserting opposite things	both individually correct, mutually exclusive
a checker reading a narrower slice than the contract	a conformance check is itself a control, and can be wired to the wrong kind
a test that holds the defect in place	assertions written from observed output require that output to stay
a wait that reports its own subject	names the last link, not the broken one
a field with no reader	rejected structurally by the substrate

Each carries what to look at and what healthy looks like, so the page is usable against a cluster rather than only readable.

Also on the page

Commands worth running on a cluster that looks fine — including why --field-selector=status.phase!=Running reports a crashlooping cluster as clean (a CrashLoopBackOff pod is phase Running), and why the state explaining a restart needs --previous.

The fifteen per-repo runbooks are surfaced and cross-linked in one place for the first time, across eks-gitops, eks-agent-platform, eks-fleet, landing-zone and portal.

It ends on the habit that finds this class: ask what would report unhealthy if a thing were wrong; if the answer is nothing, assert the specific value, spelled out independently — because two references to one constant agree with each other no matter what either says. Then prove the check fails, since a gate nobody has watched go red is a comment.

Verification

pnpm build clean — 191 pages. The postbuild gates pass, and the link gate independently verified the runbook links:

vocabulary ok — 55 nanohype.dev name(s) ... across 192 pages
links ok — every internal link and anchor across 192 pages resolves,
           255 link(s) into 10 org repo tree(s) exist

Registered under a new Operating it nav section. Authored, not generated — every other section of the site renders something the org already ships.

https://claude.ai/code/session_012iMnbboJuiUMSvu7n8oRhz