Skip to content

Orientation — first hour in this repo

Dual-site self-hosted Kubernetes managed via ArgoCD + Terraform + Ansible + Packer + Cilium Gateway API. Sites: home (10.1.x.x), office (10.2.x.x).

This page is the reading order and the rules that bite first. It does not replace docs/onboarding/, which covers first-time machine setup (tooling install, Zed, access verification).

Read order

Read these before dispatching work or proposing next steps.

  1. PRINCIPLES.md — hard rules, zero-warnings cascade, testing philosophy, IaC discipline, deep-dive deliverables.
  2. CLAUDE.md — terse operating rules, skills, hooks.
  3. STATE.md — append-only session log. Read the newest entries at the top to pick up where the last session stopped.
  4. .workingdir2/00-INDEX.md — index of the tracked handoff, planning, and investigation area; points at the current authorities (roadmap, execution backlog, audits).
  5. .workingdir2/bugs/08-known-bugs.md — canonical BUG-N catalogue. Read before assigning a bug number or acting on a known defect.
  6. .workingdir2/inventory/04a-cluster-component-inventory.md — point-in-time reconciled Application inventory. Historical evidence: re-read Git and live Argo before acting on it.

For machine setup rather than repo rules, start at docs/onboarding/README.md.

Site self-location

Mandatory at session start. Run the /site-detect skill (.claude/skills/site-detect.md), which is also wired into the session-start hook.

Read the workstation's primary IPv4:

ip -4 addr show | grep -E '^\s+inet '

Then apply the rule:

Primary IPv4 Site
10.1.x.x or 192.168.1.x home
10.2.x.x or 192.168.2.x office
172.28.80.x (Hyper-V) WSL internal — ignore, keep looking
anything else ask; do not guess

Same-site endpoints:

home office
gateway VIP 10.1.30.10 10.2.30.10
coredns-lan VIP 10.1.30.11 10.2.30.11
cloudflared VIP 10.1.30.12 —
API VIP 10.1.20.10:6443 10.2.20.10:6443
API via cloudflared https://k8s-home.infra.cauda.dev https://k8s-office.infra.cauda.dev

The site link between gateway firewalls is always up; cross-site VIPs are reachable over it. Both subnets route freely at the gateway level except wlan-iot / wlan-guest. Do not invent firewall ACLs to "fix" reachability, and do not conclude "cluster offline" from a single failed ping.

The rules that bite first

No direct cluster mutations

All cluster mutations flow through Git → ArgoCD. No kubectl apply, argocd app sync --force, or terraform apply outside a reviewed PR and the ArgoCD flow. The sole documented carve-out is the one-time ArgoCD bootstrap in README.md, which pins a version like every other apply.

Destructive operations — terraform destroy, argocd app delete, kubectl delete, PVE VM/disk mutation (qm clone/set/destroy, disk move/unlink/resize) — need explicit confirmation. The before-bash-destructive hook blocks them; before-write-protected and before-edit-argocd-app warn only.

Zero warnings, no silent suppressions

Every change passes through every layer that applies to it: IDE → pre-commit → pre-push → CI → pre-sync (argocd app diff). See PRINCIPLES.md for what each layer runs.

No //nolint, no # noqa, no # disable= without a justification comment naming the issue and an expiry date.

State hygiene is immediate, not batched

Update STATE.md immediately after any bug is resolved, confirmed, or ruled out. When work materially advances — a PR closes a HANDOFF item, a bug is resolved or found, scope shifts — update the matching file under .workingdir2/ in the same pass, inline in the existing [DONE — PR #N (commit `sha`)] style.

STATE.md is the chronological log; the .workingdir2/ files are the prioritised plan. Both must stay current. Batching to session end loses context and causes re-discovery of already-resolved items.

Live docs over training data

Before configuring any third-party tool, image, chart, or model — flags, supported versions, env vars, model IDs, API shapes — fetch and follow the current upstream docs. Pin to the version those docs validate against, not the newest beta.

Everything pinned, everything sealed

No latest image or chart tags; pin to semver or digest. The narrow carve-out is an upstream-curated stable stream documented by a referenced ADR (see docs/adr/0004-latest-tag-remediation.md). No plaintext secrets outside sealed-secrets/*.tpl templates.

Conventions

Conventional commits, type(scope): subject, with a canonical scope from the list in PRINCIPLES.md. Breaking changes append ! to the type and carry a BREAKING CHANGE: footer plus a Migration: section.

Every commit that changes behaviour updates the relevant docs: manifest change → README / per-app docs; architectural change → ADR in docs/adr/; new module → AGENTS.md; anything noteworthy → STATE.md.

Where to look next