Add phase-1 Ansible foundation and validation scaffolding

README.md

@@ -17,6 +17,7 @@ If you only read one section, read **[Source-of-truth boundaries](docs/source-of
 - Docker environment composition and `services-up.sh`: [docs/docker-environment.md](docs/docker-environment.md)
 - Terraform workflows (brownfield import/reconciliation): [docs/terraform-workflows.md](docs/terraform-workflows.md)
 - Infrastructure inventory intent and outputs: [docs/infrastructure-inventory.md](docs/infrastructure-inventory.md)
+- Ansible bootstrap workflows: [docs/ansible-workflows.md](docs/ansible-workflows.md)
 - Deployment prerequisites and secrets setup: [docs/deployment-prerequisites.md](docs/deployment-prerequisites.md)
 - Secrets inventory: [docs/security-secrets.md](docs/security-secrets.md)
 
@@ -25,8 +26,9 @@ 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:
+Infrastructure subtrees:
 
+- Ansible foundation docs: [infrastructure/ansible/README.md](infrastructure/ansible/README.md)
 - Terraform root docs: [infrastructure/terraform/README.md](infrastructure/terraform/README.md)
 - Terraform Docker mirror: [infrastructure/terraform/docker/README.md](infrastructure/terraform/docker/README.md)
 - Terraform Proxmox inventory: [infrastructure/terraform/proxmox/README.md](infrastructure/terraform/proxmox/README.md)
@@ -41,6 +43,13 @@ Terraform subtrees:
 - `services-up.sh` composes the environment by discovering compose files and applying common env/network inputs.
 - For service runtime behavior, start from Compose files and `services-up.sh` (not Terraform).
 
+
+### Ansible (bootstrap foundation)
+
+- Ansible under `infrastructure/ansible/` is a phase-1 foundation for inventory/configuration scaffolding.
+- It supports safe validation (inventory parsing and playbook syntax checks) while hosts/devices are onboarded gradually.
+- It does not replace Compose runtime authority or Terraform reconciliation authority at this stage.
+
 ### Terraform (inventory and reconciliation authority)
 
 - Terraform under `infrastructure/terraform/` is used to codify and reconcile existing infrastructure.
@@ -118,11 +127,14 @@ The repository includes helper scripts for Codex sessions that need local toolin
 - `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`.
+  - Installs/refreshed baseline Ansible collections when `infrastructure/ansible/collections/requirements.yml` is present.
+  - Runs safe Ansible bootstrap checks (version, inventory parse, playbook syntax check) without live connectivity operations.
   - 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.
+  - Refreshes Ansible collections and repeats safe inventory/syntax validation checks.
 
 Both scripts are intended for local validation environments and should not be treated as production provisioning automation.