docs: overhaul repo documentation and workflow guides

2026-04-21 09:28:55 +10:00
parent 020d6ecb79
commit c7dd9f2229
13 changed files with 539 additions and 174 deletions
@@ -0,0 +1,47 @@
+# Source-of-Truth Boundaries
+
+This repository has multiple layers. Knowing the authority for each layer prevents accidental drift.
+
+## Boundary summary
+
+| Layer | Primary authority | Purpose |
+|---|---|---|
+| Application/runtime container composition | `services-up.sh` + Compose files under `core/`, `apps/`, `monitoring/` | What runs in the Docker environment and how services are wired. |
+| Docker shared baseline inputs | `default-network.yml`, `default-environment.env`, `secrets/stack-secrets.env` | Shared network/env material applied during compose rendering. |
+| Infrastructure inventory and reconciliation | Terraform under `infrastructure/terraform/` | Codified inventory of existing infrastructure and relationships, especially Proxmox VMs and selected Docker mirrors. |
+| Secret policy and inventory | `SECURITY_SECRETS_INVENTORY.md` + local secret files in `secrets/` | What secrets exist and where they are expected. |
+
+## Practical meaning
+
+### Docker runtime decisions
+
+Change Compose files and `services-up.sh` when changing runtime behavior.
+
+Do **not** assume Terraform Docker resources are the deployment source for day-to-day service runtime.
+
+### Infrastructure inventory decisions
+
+Use Terraform when documenting/reconciling existing:
+
+- Proxmox VM config and identifiers.
+- Physical host metadata.
+- Select Docker container details that are intentionally mirrored.
+
+Do **not** treat Terraform as a full replacement for Compose operations in this repo.
+
+## Declared config vs observed/runtime state
+
+- **Declared config**: files in this repository (Compose, Terraform, docs).
+- **Observed/runtime state**: live Docker/Proxmox reality and Terraform state snapshots.
+
+Brownfield workflows reconcile these two safely and incrementally.
+
+## Guardrails for contributors and Codex
+
+- Do not mass-import or mass-reconcile everything at once.
+- Keep imports/reconciliation scoped to one object (or small set) at a time.
+- Keep `ignore_changes` surgical and justified.
+- Prefer shaped outputs (inventory-ready) over raw provider object dumps.
+- Do not commit `.tfstate`, real `.tfvars`, or real secret files.
+
+See [docs/terraform-workflows.md](terraform-workflows.md) for step-by-step procedures.