docs: overhaul repo documentation and workflow guides

docs/infrastructure-inventory.md

@@ -0,0 +1,51 @@
+# Infrastructure Inventory Model
+
+This repository treats infrastructure inventory as first-class documentation.
+
+## Intent
+
+The goal is not only deployment configuration, but also a maintainable map of:
+
+- what hosts/VMs exist,
+- how they are identified,
+- what selected runtime objects are mirrored into Terraform,
+- what outputs can be consumed by docs and future tooling.
+
+## Current inventory sources
+
+### 1) Terraform Proxmox layer
+
+`infrastructure/terraform/proxmox/` contains imported/reconciled VM resources and local metadata for physical hosts.
+
+This is currently the most structured host/VM inventory in the repo.
+
+### 2) Terraform Docker layer
+
+`infrastructure/terraform/docker/` contains selective Docker container resources used as documentation-oriented mirrors.
+
+These resources should match existing running containers, not redefine runtime composition strategy.
+
+### 3) Compose runtime definitions
+
+Compose files define intended service runtime composition, networking, labels, and integration.
+
+### 4) Architecture docs
+
+`docs/architecture.md` provides a human-readable topology view based on repository configuration and observed runtime signals.
+
+## Output shaping expectations
+
+When adding Terraform outputs for documentation/tooling:
+
+- prefer concise inventory maps/lists,
+- include stable identifiers and roles,
+- avoid raw giant provider objects where possible,
+- include descriptions so future consumers understand intent.
+
+## Limitations today
+
+- No full generated inventory document pipeline is present yet.
+- Some Terraform files still include generated boilerplate comments requiring ongoing cleanup.
+- Ansible/NixOS operational layers are not yet implemented in a way that provides authoritative inventory in this repo.
+
+These limitations are expected for the current adoption stage.