# 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.