docs: overhaul repo documentation and workflow guides

infrastructure/terraform/README.md

@@ -1,54 +1,60 @@
-# Terraform foundations
+# Terraform in This Repository
 
-This directory introduces Terraform in a conservative, incremental way for this homelab repo.
+Terraform here is used as a **structured inventory + reconciliation layer** for existing infrastructure.
 
-## Purpose in this repository
+It does **not** replace Docker Compose as runtime deployment authority.
 
-Terraform is used here to **document and gradually adopt management** of existing infrastructure without disrupting running services.
+## What Terraform is currently used for
 
-Current intent:
-- Start with imported live Docker resources so infrastructure is visible and reproducible in code.
-- Add Proxmox inventory/configuration later once provider details and import IDs are confirmed.
-- Keep this phase local-state and learning-oriented (no remote backend yet).
+- Proxmox VM import/reconciliation for existing VMs.
+- Physical host metadata represented in Terraform locals/outputs.
+- Select Docker container mirror resources for documentation-oriented tracking.
+- Outputs that can support documentation and later downstream tooling.
 
-## Tool boundaries
+## What Terraform is not used for (today)
 
-- **Docker Compose**: day-to-day application/service runtime definitions already used by this repo.
-- **Terraform**: infrastructure state capture and controlled resource management (starting with imports).
-- **Ansible**: follow-on host/configuration management after Terraform inventory and targets are stable.
-- **NixOS**: host OS/system-level declarative configuration, separate from per-service compose workflows.
+- Replacing `services-up.sh` / Compose for day-to-day app runtime orchestration.
+- Broad, immediate greenfield provisioning of the whole stack.
+- Casual `apply` operations across all infrastructure.
 
-## Layout
+## Directory map
 
-- `docker/`: Docker provider scaffold and incremental import workflow.
-- `proxmox/`: placeholder scaffold for later Proxmox adoption.
-- `modules/`: placeholder module directories for future shared patterns.
+- `proxmox/` — imported/reconciled VM resources and host metadata outputs.
+- `docker/` — selective Docker container import/mirror resources.
+- `bootstrap/` — backend/provider bootstrap scaffolding.
+- `modules/` — placeholder module directories for future stable abstractions.
+- `scripts/reconcile_from_plan.sh` — helper to convert generated plan config into reviewable draft files.
 
-## Incremental adoption plan
+## Brownfield workflow standard
 
-1. Import Docker containers one-by-one into Terraform state.
-2. Reconcile and stabilize Docker Terraform configuration until `terraform plan` is clean.
-3. Add Proxmox inventory/configuration scaffolding and imports later.
-4. Introduce Ansible workflow after Terraform-managed inventory is trustworthy.
+1. Import one existing object.
+2. Inspect state/plan output.
+3. Reconcile hand-maintained Terraform code.
+4. Keep `ignore_changes` narrowly scoped.
+5. Iterate to no-op/sane plan for intended scope.
+6. Avoid casual apply.
 
+See detailed steps in [../../docs/terraform-workflows.md](../../docs/terraform-workflows.md).
 
-## Plan-to-config helper script
+## Safe validation commands
 
-Use `scripts/reconcile_from_plan.sh` to automate Terraform configuration generation from `terraform plan` output (via Terraform's `-generate-config-out`).
-
-From a Terraform module directory (for example `infrastructure/terraform/docker`):
+From Terraform directories, preferred checks are:
 
 ```bash
-../../scripts/reconcile_from_plan.sh --output-file zz_generated_from_plan.auto.tf
+terraform fmt -check -recursive
+terraform init -backend=false -input=false
+terraform validate
 ```
 
-Notes:
-- Best used with an import-first workflow that already contains `import {}` blocks.
-- The script writes generated config into a `.auto.tf` file and runs `terraform fmt` on it.
-- Always review generated arguments before apply.
+## Secrets and state safety
 
-## Safety notes
+- Do not commit `.tfstate*`.
+- Do not commit real `.tfvars` values.
+- Keep credentials in local, untracked inputs only.
 
-- State files are intentionally gitignored for safety and portability.
-- Do **not** run `terraform apply` until imported resources are fully reconciled and plan output is reviewed as no-op for intended targets.
-- No remote backend is configured yet by design.
+## Related docs
+
+- [../../docs/source-of-truth.md](../../docs/source-of-truth.md)
+- [../../docs/infrastructure-inventory.md](../../docs/infrastructure-inventory.md)
+- [docker/README.md](docker/README.md)
+- [proxmox/README.md](proxmox/README.md)