docs/ — Authority and navigation

authority-manifest.json is the machine-readable authority map for every tracked path below docs/. Local ADRs, runbooks, operating contracts and integration deltas remain repository authority. Fetched upstream prose is observation-only and must not silently become local authority.

Curated for this repo

Path	Purpose
onboarding/	First-time setup for a new workstation or contributor (human or AI). Start here.
runbooks/	Operational runbooks (Synology NAS, etc.).
adr/	Architecture Decision Records (MADR format).
TOOLING.md	Canonical tool + version matrix.
ORIENTATION.md	Reading order for the first hour in this repo, and the rules that bite first.
GLOSSARY.md	Repo-specific terms, hostnames, gateway VIPs and abbreviations.
PROMQL-COOKBOOK.md	Verified PromQL queries against metrics this cluster actually exposes.
ai/, jellyfin/, sabnzbd/	Distilled local digests written for this repo (not fetched mirrors).

Legacy upstream mirrors

The remaining component directories are legacy mirrors fetched by fetch-docs.sh. They track mutable upstream branches and are classified as candidate-for-removal, not as current RAG/MCP-backed content. The suspended legacy indexer selects only local ADRs, runbooks, TOOLING.md, and .workingdir2/**/*.md; it does not select these generic mirrors.

Do not add new upstream prose here. Register an exact upstream source and keep only the local delta or pointer. A still-used mirror may be deleted only after its manifest entry proves an immutable, byte-identical replacement and a verified retrieval locator. A blocked upstream candidate-for-removal that is genuinely unneeded may instead use the separate retired-unneeded gate, but only after a retained, reviewed commit proves that the component is neither deployed/configured nor accepted/planned. The gate preserves and binds the candidate's identity, source, paths, ownership and policy. Local authority and local deltas cannot use this lane; the 21 eligible upstream subjects are also bound to a code-reviewed identity/path/repository hash. Every current mirror family has an active repository/config or Cluster 2 planning reference, so none currently qualifies for retirement.

Component	Upstream source	Fetched ref
alloy	grafana/alloy	main
app-template	bjw-s-labs/helm-charts	main
argocd	argoproj/argo-cd	master
authentik	goauthentik/authentik	main
cert-manager	cert-manager/website	master
cilium	cilium/cilium	main
cloudflared	cloudflare/cloudflared	master
cloudnative-pg	cloudnative-pg/cloudnative-pg	main
collabora	CollaboraOnline/online	master
descheduler	kubernetes-sigs/descheduler	master
external-dns	kubernetes-sigs/external-dns	master
gitea	go-gitea/gitea	main
kube-prometheus-stack	prometheus-community/helm-charts	main
kured	kubereboot/kured	main
kyverno	kyverno/kyverno	main
loki	grafana/loki	main
longhorn	longhorn/website	master (1.12.0 subtree)
sealed-secrets	bitnami-labs/sealed-secrets	main
trivy-operator	aquasecurity/trivy-operator	main
velero	vmware-tanzu/velero	main
vpa	kubernetes/autoscaler	master

Refresh

./docs/fetch-docs.sh                    # uses `gh auth status` for the API token
GH_TOKEN=ghp_… ./docs/fetch-docs.sh     # explicit token override

Refreshing mutates the observation copies; it does not admit, sign or publish a retrieval generation. Diffs against deployed chart/application versions are therefore expected.

Authority gate

python3 tools/repository-docs/check_doc_authority.py
python3 tools/repository-docs/check_doc_authority.py --base-ref origin/main

The branch-base form is required for deletions. It fails closed unless a removed path has either a ready byte-identical replacement and verified retrieval locator, or a ready retired-unneeded gate bound to the exact prior review commit. retired-unneeded is restricted to an unchanged, source-bearing upstream candidate. Retirement requires explicit aliases/patterns, the exact candidate commit, existing documentation during review, no inbound links, no active or accepted/planned references, and complete deletion of the reviewed set in one change. Local ADRs, runbooks, operating contracts and integration deltas remain authority and cannot be reclassified into this deletion lane.

Notes

• MetalLB is not used — Cilium LB-IPAM handles load balancing.
• Some projects host canonical docs outside GitHub; their legacy mirrors here are intentionally incomplete and never substitute for the official channel.
• The former duplicate Cilium deep-dive is canonical under .workingdir2/research/24-cilium-gateway/ — a research-time snapshot that records the chart pin as 1.19.4; the current pin is 1.19.6 in argocd-apps/infra/cilium.yaml.
• For the canonical Cluster API / Gateway / DNS / VLAN architecture, see onboarding/network.md and the per-module AGENTS.md files (e.g., cilium-lb, gateway).