docs: overhaul repo documentation and workflow guides

README.md

@@ -1,8 +1,67 @@
-# Docker + Traefik Homelab Stack
+# Homelab Docker + Terraform Inventory Repository
 
-This repository defines a multi-compose Docker environment with Traefik as ingress, app workloads, and a monitoring/alerting plane.
+This repository is both:
 
-## High-Level Architecture
+1. **operational** (Docker Compose application/runtime definition), and
+2. **documentary/inventory-oriented** (Terraform capture of Proxmox VMs, host metadata, and selected Docker objects).
+
+If you only read one section, read **[Source-of-truth boundaries](docs/source-of-truth.md)** first.
+
+---
+
+## Quick navigation
+
+- Architecture overview: [docs/architecture.md](docs/architecture.md)
+- Repository layout: [docs/repo-structure.md](docs/repo-structure.md)
+- Source-of-truth boundaries and guardrails: [docs/source-of-truth.md](docs/source-of-truth.md)
+- Docker environment composition and `services-up.sh`: [docs/docker-environment.md](docs/docker-environment.md)
+- Terraform workflows (brownfield import/reconciliation): [docs/terraform-workflows.md](docs/terraform-workflows.md)
+- Infrastructure inventory intent and outputs: [docs/infrastructure-inventory.md](docs/infrastructure-inventory.md)
+- Deployment prerequisites and secrets setup: [DEPLOYMENT.md](DEPLOYMENT.md)
+- Secrets inventory: [SECURITY_SECRETS_INVENTORY.md](SECURITY_SECRETS_INVENTORY.md)
+
+Terraform subtrees:
+
+- Terraform root docs: [infrastructure/terraform/README.md](infrastructure/terraform/README.md)
+- Terraform Docker mirror: [infrastructure/terraform/docker/README.md](infrastructure/terraform/docker/README.md)
+- Terraform Proxmox inventory: [infrastructure/terraform/proxmox/README.md](infrastructure/terraform/proxmox/README.md)
+
+---
+
+## Operating model
+
+### Docker Compose (runtime authority)
+
+- Compose files under `core/`, `apps/`, and `monitoring/` describe runtime services.
+- `services-up.sh` composes the environment by discovering compose files and applying common env/network inputs.
+- For service runtime behavior, start from Compose files and `services-up.sh` (not Terraform).
+
+### Terraform (inventory and reconciliation authority)
+
+- Terraform under `infrastructure/terraform/` is used to codify and reconcile existing infrastructure.
+- Current repo usage emphasizes **brownfield import-first workflows** and safe reconciliation.
+- Terraform captures:
+  - Proxmox VM configuration for existing VMs.
+  - Physical host metadata in locals/outputs.
+  - Documentation-oriented Docker container mirroring (limited, selective).
+
+Terraform here is **not** a replacement for Docker Compose deployment.
+
+---
+
+## Guardrails
+
+- Do not run destructive Terraform commands casually.
+- Do not treat generated Terraform config as final without manual review.
+- Do not commit real secrets, credentials, or local state.
+- Keep one-resource-per-file patterns where already established in Terraform subdirectories.
+- Prefer shaping outputs for documentation/tooling consumption over dumping raw provider objects.
+
+See [docs/source-of-truth.md](docs/source-of-truth.md) and [docs/terraform-workflows.md](docs/terraform-workflows.md) for concrete do/don't guidance.
+
+---
+
+## High-level architecture
 
 ```mermaid
 flowchart TB
@@ -43,4 +102,4 @@ flowchart TB
   Prometheus --> Gotify
 ```
 
-For a request-flow/network view and architecture notes, see [docs/architecture.md](docs/architecture.md).
+For request-flow and network detail, see [docs/architecture.md](docs/architecture.md).