docs: overhaul repo documentation and workflow guides

infrastructure/terraform/docker/README.md

@@ -1,48 +1,43 @@
-# Docker Terraform scaffold
+# Terraform Docker Mirror Layer
 
-This directory is for **incremental, import-first Terraform adoption** of existing Docker containers.
+This directory tracks selected existing Docker containers in Terraform for inventory/documentation purposes.
 
-## What this directory is for
+## Purpose
 
-- Document existing live Docker resources in Terraform.
-- Import containers one-by-one.
-- Reconcile Terraform code with real runtime values until plan is clean.
+- Mirror specific running containers as Terraform resources.
+- Reconcile imported state into maintainable code.
+- Produce structured outputs/reminders that support documentation workflows.
 
-## Initialize
+## Boundary with Docker Compose
 
-From this directory:
+Docker Compose + `services-up.sh` remain runtime composition authority.
 
-```bash
-terraform init
-```
+Terraform resources here are **not** the primary day-to-day deployment mechanism for app services.
 
-## Safe incremental import workflow
+## Current contents
 
-1. Add one `docker_container` resource block in `main.tf` for an already-running container.
-2. Import it into state:
+- `main.tf` — import-first workflow notes and minimal scaffolding.
+- `searxng-webapp.tf` — generated/reconciled example container resource.
+- `outputs.tf` — documentation-oriented reminders/outputs.
+- `terraform.tfvars.example` — safe template for local values.
 
-   ```bash
-   terraform import docker_container.<resource_name> <container_id_or_container_name>
-   ```
+## Import/reconciliation workflow
 
-3. Inspect imported state:
+1. Start with one existing container.
+2. Import with `import {}` block or `terraform import`.
+3. Inspect state / generated config.
+4. Reduce generated attributes to meaningful, stable arguments.
+5. Keep lifecycle `ignore_changes` narrow and justified.
+6. Iterate until plan is clean for the intended resource.
 
-   ```bash
-   terraform state show docker_container.<resource_name>
-   ```
+## Guardrails
 
-4. Copy required/meaningful arguments from state output into `main.tf`.
-5. Run `terraform plan` and refine until there are no unintended changes.
+- Do not attempt to mirror all containers in one pass.
+- Do not commit local state or real credentials.
+- Treat generated config as draft input that needs review.
 
-## Reconciliation guidance
+## Related docs
 
-- Keep one resource block per imported container.
-- Prefer explicit values for arguments that affect recreation.
-- Avoid broad changes; reconcile each container independently.
-- Do **not** run `terraform apply` until plan output is intentionally clean.
-
-## State and secrets handling
-
-- State files are ignored via `../.gitignore` because they may contain environment-specific metadata.
-- Do not commit real `.tfvars` files with machine-specific values.
-- Use `terraform.tfvars.example` as a safe starter template.
+- [../README.md](../README.md)
+- [../../../docs/source-of-truth.md](../../../docs/source-of-truth.md)
+- [../../../docs/terraform-workflows.md](../../../docs/terraform-workflows.md)