docs: overhaul repo documentation and workflow guides

docs/documentation-strategy.md

@@ -0,0 +1,36 @@
+# Documentation Strategy
+
+This repository's documentation should help both humans and Codex agents make safe, accurate changes.
+
+## Principles
+
+1. **Authority first**: identify authoritative files clearly (Compose + `services-up.sh` for runtime; Terraform for structured inventory/reconciliation).
+2. **Task-oriented docs**: include practical workflow steps, not only conceptual text.
+3. **No speculation**: document implemented behavior, not aspirational designs without code evidence.
+4. **Cross-linking**: root README and topic docs should point to each other for discoverability.
+5. **Safety clarity**: explicitly note what should not be committed or applied casually.
+
+## Documentation quality checklist
+
+Before merging doc changes, check:
+
+- Is this statement verifiable from current repo files?
+- Does this conflict with existing docs?
+- Does this clarify source-of-truth boundaries?
+- Does this improve a real workflow for contributors/Codex?
+- Are sensitive details excluded?
+
+## Recommended update cadence
+
+Update docs when any of these change:
+
+- `services-up.sh` composition behavior,
+- major Compose directory or profile structure,
+- Terraform workflow conventions,
+- inventory output shapes,
+- secret handling conventions.
+
+## Audience-specific outcomes
+
+- Humans should quickly understand how to operate the repo safely.
+- Future Codex runs should quickly identify authoritative files, guardrails, and reconciliation workflows.