docs: overhaul repo documentation and workflow guides

docs/terraform-workflows.md

@@ -0,0 +1,78 @@
+# Terraform Workflows (Brownfield / Reconciliation)
+
+Terraform in this repository is primarily used for **importing and reconciling existing infrastructure**.
+
+This is a brownfield workflow: real infrastructure exists first, then code/state are brought into alignment.
+
+## Core workflow pattern
+
+1. Define/import one existing object.
+2. Inspect current provider state.
+3. Reconcile hand-maintained `.tf` configuration.
+4. Use targeted `ignore_changes` only when necessary.
+5. Iterate until plan is sane/no-op for intended scope.
+6. Avoid casual apply operations.
+
+## Docker mirror workflow (documentation-oriented)
+
+Directory: `infrastructure/terraform/docker/`
+
+Use when intentionally mirroring selected running containers as structured documentation.
+
+### Steps
+
+1. Add minimal `docker_container` resource block (or uncomment/import-ready block).
+2. Add `import {}` block or run `terraform import` for the container.
+3. Run plan and inspect generated/state values.
+4. Keep only meaningful, maintainable arguments in hand-edited files.
+5. Use generated files as draft input, not final truth.
+6. Re-run plan until intended scope is clean.
+
+## Proxmox VM workflow
+
+Directory: `infrastructure/terraform/proxmox/`
+
+Use for existing Proxmox VMs and metadata reconciliation.
+
+### Steps
+
+1. Add/import one VM resource at a time.
+2. Confirm provider import ID format and vm/node mapping.
+3. Inspect with `terraform state show` / plan output.
+4. Move useful arguments into stable hand-maintained files.
+5. Keep lifecycle ignore rules narrow and explicit.
+6. Iterate per VM until plan stabilizes.
+
+## Physical host metadata workflow
+
+Physical host metadata currently lives in Proxmox Terraform locals/outputs and is used as documentation inventory context.
+
+When updating:
+
+1. update locals with factual host metadata,
+2. ensure outputs remain documentation-friendly,
+3. avoid leaking sensitive internal data not needed for repository goals.
+
+## Generated config guidance
+
+`infrastructure/terraform/scripts/reconcile_from_plan.sh` can generate Terraform draft configuration via `-generate-config-out`.
+
+Treat generated files as:
+
+- a starting point,
+- reviewed manually,
+- reduced to meaningful attributes,
+- reformatted and split into maintainable files.
+
+## Safety reminders
+
+- Do not commit `.tfstate*` or real `.tfvars`.
+- Do not commit credentials.
+- Do not run `terraform apply`/`destroy` casually.
+- Keep changes incremental and reviewable.
+
+## Related docs
+
+- [docs/source-of-truth.md](source-of-truth.md)
+- [docs/infrastructure-inventory.md](infrastructure-inventory.md)
+- [infrastructure/terraform/README.md](../infrastructure/terraform/README.md)