docs: add codex setup and maintenance script guidance

README.md

@@ -20,6 +20,11 @@ If you only read one section, read **[Source-of-truth boundaries](docs/source-of
 - Deployment prerequisites and secrets setup: [docs/deployment-prerequisites.md](docs/deployment-prerequisites.md)
 - Secrets inventory: [docs/security-secrets.md](docs/security-secrets.md)
 
+Codex helper scripts:
+
+- Initial Codex environment/bootstrap setup: [scripts/codex-setup.sh](scripts/codex-setup.sh)
+- Codex environment maintenance/refresh: [scripts/codex-maintenance.sh](scripts/codex-maintenance.sh)
+
 Terraform subtrees:
 
 - Terraform root docs: [infrastructure/terraform/README.md](infrastructure/terraform/README.md)
@@ -103,3 +108,21 @@ flowchart TB
 ```
 
 For request-flow and network detail, see [docs/architecture.md](docs/architecture.md).
+
+---
+
+## Codex setup and maintenance scripts
+
+The repository includes helper scripts for Codex sessions that need local tooling and safe placeholder secret material for validation-only workflows:
+
+- `scripts/codex-setup.sh`
+  - Installs baseline CLI dependencies (shell/yaml/terraform/ansible tooling).
+  - Prepares `secrets/stack-secrets.env` from templates and creates dummy file-based secret placeholders based on `secrets/inventory.json`.
+  - Prints installed tool versions for quick verification.
+
+- `scripts/codex-maintenance.sh`
+  - Refreshes Python-based linting/automation tooling.
+  - Reconciles placeholder secret files against current `secrets/inventory.json` (creates missing, removes stale).
+  - Rebuilds `secrets/stack-secrets.env` with dummy values for compose-config validation.
+
+Both scripts are intended for local validation environments and should not be treated as production provisioning automation.