docs: overhaul repo documentation and workflow guides

infrastructure/terraform/proxmox/README.md

@@ -1,36 +1,44 @@
-# Proxmox Terraform scaffold
+# Terraform Proxmox Inventory Layer
 
-This directory is a **placeholder scaffold** for future Proxmox Terraform adoption.
+This directory codifies existing Proxmox infrastructure using an import-first reconciliation model.
 
-## What this directory is for
+## Purpose
 
-- Prepare provider/version/variable structure now.
-- Delay real Proxmox resource management until import strategy is validated.
+- Track existing Proxmox VMs in Terraform.
+- Reconcile imported VM configuration into maintainable, explicit files.
+- Represent physical host metadata as structured Terraform locals/outputs.
+- Support documentation inventory and future downstream tooling.
 
-## Initialize
+## Current repository status
 
-From this directory:
+This directory already contains imported/reconciled VM resources (for example `docker`, `server-nixos`, `nix-cache`, `pbs`, `pihole`) plus host metadata locals/outputs.
 
-```bash
-terraform init
-```
+This means it is no longer just a scaffold; treat it as active infrastructure inventory code.
 
-## Current status
+## Workflow standard (brownfield)
 
-- No live Proxmox resources are defined yet.
-- Provider auth variables are placeholders only.
-- Import IDs and resource schemas must be verified against provider docs before adding resources.
+1. Import one existing VM at a time.
+2. Confirm provider-specific import ID format.
+3. Inspect state/plan details.
+4. Keep hand-maintained `.tf` files focused and readable.
+5. Use `ignore_changes` only where drift noise is unavoidable.
+6. Stop when plan is sane/no-op for intended scope.
 
-## Future safe workflow
+## File organization expectations
 
-1. Add one resource block for an existing VM/object.
-2. Import it with the provider-specific ID format.
-3. Inspect with `terraform state show`.
-4. Reconcile `.tf` arguments until `terraform plan` is clean.
-5. Repeat incrementally.
+- Prefer one-resource-per-file patterns when practical.
+- Keep shared metadata in `locals`/outputs with clear descriptions.
+- Keep generated comments/config under ongoing cleanup rather than assuming generated output is final.
 
 ## Safety notes
 
-- Do not commit real credentials in `.tf` files or tracked `.tfvars`.
-- State files are ignored by the Terraform-level `.gitignore`.
-- Do not run `terraform apply` until plan is intentionally no-op for existing resources.
+- Do not run broad applies casually.
+- Do not commit real credentials or `.tfstate*`.
+- Keep changes incremental and reviewable.
+
+## Related docs
+
+- [../README.md](../README.md)
+- [../../../docs/source-of-truth.md](../../../docs/source-of-truth.md)
+- [../../../docs/terraform-workflows.md](../../../docs/terraform-workflows.md)
+- [../../../docs/infrastructure-inventory.md](../../../docs/infrastructure-inventory.md)