docs(explainers): a plain-language entry point for the homelab stack

[openbao-service-broker]

A plain-language entry point for the homelab stack

Every architecture page on this site assumes the reader already knows what a
hypervisor is. These six do not.

They sit directly after Start here in the Overview dropdown, so someone
arriving cold meets them before the technical sections rather than after.

The arc

Dependency-ordered, each page assuming only the one before it: what a
hypervisor is, then clusters and quorum, then what actually happens when a
machine dies, then the two questions people ask as soon as they see a
self-hosted stack — one login across everything, and where the passwords live.

Each page leads with the misconception rather than the definition, because in
this subject the misconceptions are the load-bearing part:

• Adding a second host for redundancy makes a two-node cluster strictly
  worse. A majority is more than half, and two of two is not one.
• Backup, replication and failover solve three different problems. Replication
  copies a mistake faithfully and instantly; only a backup survives one. And a
  replicated guest that nothing promotes is a copy, not a recovery — "it's
  replicated" and "it recovers" are different claims.
• A failover target must already hold the data, so a guest is pinned to the
  hosts that replicate it. Getting that wrong is worse than having no
  automation, because the automation confidently does something broken.
• Single sign-on is safer than per-app logins for precisely the reason it looks
  riskier: exactly one system ever handles a password.
• The identity header a proxy injects has to be stripped from inbound requests
  first. Strip-then-authenticate and authenticate-then-strip look nearly
  identical and differ by a complete authentication bypass.

Placement and scope

New content, not a duplicate — nothing on the site currently explains
virtualization, quorum, hypervisor-level HA, or SSO to a general audience.
Where an existing page already owns a topic concretely it is linked rather than
restated; the node-loss page points at infrastructure/data-platform-resilience
instead of re-explaining it for the database tier.

Names are placeholders throughout, following the site's existing scrubbing
convention. The structure is the teachable part; a real map of a private
network is not.

Verification

• ./scripts/validate-mermaid.sh renders every diagram on the site — exit 0
• The %%{init …}%% directive is byte-identical to the site's single canonical
  line (the uniqueness count CI asserts stays at 1)
• Every diagram is 4–6 nodes against the 12-node cap, each with the required
  self-check comment above the fence
• All eleven internal links resolve to files that exist
• jq empty docs.json passes; the navigation edit is 11 insertions, 0 deletions
• Components limited to those already in use on the site — no Accordion,
  Tabs or Frame