Add phase-1 Ansible foundation and validation scaffolding

docs/ansible-workflows.md

@@ -0,0 +1,72 @@
+# Ansible Workflows (Bootstrap / Phase 1)
+
+Ansible is being introduced as a minimal, maintainable foundation for host/device inventory and future configuration workflows.
+
+## Why introduce Ansible now
+
+- The repository already has strong runtime and infrastructure boundaries (Compose + Terraform).
+- A small Ansible baseline allows gradual host onboarding without forcing immediate large-scale automation.
+- It enables safe validation workflows (`inventory --list`, playbook syntax checks) before real execution.
+
+## What Ansible is for in this repository (right now)
+
+- YAML inventory structure for hosts/devices to be onboarded over time.
+- Group and host variable scaffolding for future incremental adoption.
+- Validation-oriented starter playbook and local tooling checks.
+
+## What Ansible is not for yet
+
+- Replacing Docker Compose runtime authority.
+- Replacing Terraform inventory/reconciliation authority.
+- Becoming the current source of truth for NixOS host management.
+- Becoming the current source of truth for all network automation.
+
+## Directory layout
+
+- `infrastructure/ansible/ansible.cfg`
+- `infrastructure/ansible/inventory/hosts.yml`
+- `infrastructure/ansible/inventory/group_vars/`
+- `infrastructure/ansible/inventory/host_vars/`
+- `infrastructure/ansible/playbooks/ping.yml`
+- `infrastructure/ansible/collections/requirements.yml`
+
+## Add a host (gradual onboarding)
+
+1. Open `infrastructure/ansible/inventory/hosts.yml`.
+2. Add the host under an appropriate group (`linux`, `network`, `virtualization`, or `nixos`).
+3. Add non-sensitive defaults under group vars only when shared across hosts.
+4. Add host-specific values in `inventory/host_vars/<hostname>.yml`.
+5. Keep secrets out of committed files.
+
+Example pattern:
+
+```yaml
+linux:
+  hosts:
+    my-host:
+      ansible_host: my-host.local
+```
+
+## Validation commands
+
+Run from repository root:
+
+```bash
+ansible --version
+ansible-lint --version
+ansible-inventory -i infrastructure/ansible/inventory/hosts.yml --list
+ansible-playbook -i infrastructure/ansible/inventory/hosts.yml infrastructure/ansible/playbooks/ping.yml --syntax-check
+```
+
+Install/update baseline collections:
+
+```bash
+ansible-galaxy collection install -r infrastructure/ansible/collections/requirements.yml -p infrastructure/ansible/collections
+```
+
+## Guardrails for future expansion
+
+- Keep changes incremental (one host/group/playbook change at a time).
+- Prefer simple playbooks before introducing roles.
+- Add network-platform/NixOS-specific logic only when those boundaries are explicitly adopted.
+- Keep documentation aligned with source-of-truth boundaries when Ansible authority evolves.

docs/infrastructure-inventory.md

@@ -25,11 +25,18 @@ This is currently the most structured host/VM inventory in the repo.
 
 These resources should match existing running containers, not redefine runtime composition strategy.
 
-### 3) Compose runtime definitions
+
+### 3) Ansible bootstrap layer
+
+`infrastructure/ansible/` provides an emerging inventory/configuration scaffold for hosts and devices.
+
+Current scope is intentionally limited to structure, variables scaffolding, and safe validation workflows.
+
+### 4) Compose runtime definitions
 
 Compose files define intended service runtime composition, networking, labels, and integration.
 
-### 4) Architecture docs
+### 5) Architecture docs
 
 `docs/architecture.md` provides a human-readable topology view based on repository configuration and observed runtime signals.
 
@@ -46,6 +53,7 @@ When adding Terraform outputs for documentation/tooling:
 
 - No full generated inventory document pipeline is present yet.
 - Some Terraform files still include generated boilerplate comments requiring ongoing cleanup.
-- Ansible/NixOS operational layers are not yet implemented in a way that provides authoritative inventory in this repo.
+- Ansible is currently a bootstrap inventory/configuration layer and is not authoritative for full operations yet.
+- NixOS operational management is not yet implemented as an Ansible authority in this repo.
 
 These limitations are expected for the current adoption stage.

docs/repo-structure.md

@@ -8,6 +8,7 @@ This page explains where to find authoritative files quickly.
 - `apps/` — user/business applications (Nextcloud, Passbolt, Gitea, Gramps, SearXNG).
 - `monitoring/` — observability and operational tooling (Prometheus, Grafana, InfluxDB, Node-RED, etc.).
 - `infrastructure/terraform/` — brownfield Terraform inventory/reconciliation layers.
+- `infrastructure/ansible/` — phase-1 Ansible inventory/configuration scaffold and validation playbooks.
 - `docs/` — repository-level architecture and workflow documentation.
 - `archive/` — historical compose/config artifacts not part of active runtime composition.
 - `secrets/` — local secret material and templates; never commit real values.
@@ -18,7 +19,7 @@ This page explains where to find authoritative files quickly.
 - `default-network.yml` — shared docker network definitions used across compose files.
 - `default-environment.env` — non-secret default env values for compose rendering.
 - `scripts/codex-setup.sh` — Codex/bootstrap helper to install validation tooling and prepare dummy secret material.
-- `scripts/codex-maintenance.sh` — Codex maintenance helper to refresh tooling and reconcile dummy secret material.
+- `scripts/codex-maintenance.sh` — Codex maintenance helper to refresh tooling, reconcile dummy secret material, and run safe Ansible validation checks.
 - `docs/deployment-prerequisites.md` — prerequisite setup before runtime operations.
 - `docs/security-secrets.md` — secrets documentation and inventory model.
 
@@ -37,3 +38,5 @@ This page explains where to find authoritative files quickly.
 3. Read [docs/docker-environment.md](docker-environment.md).
 4. Read [docs/terraform-workflows.md](terraform-workflows.md).
 5. Only then edit Compose/Terraform files.
+
+6. For Ansible bootstrap changes, validate inventory and playbook syntax checks only.

docs/source-of-truth.md

@@ -10,6 +10,7 @@ This repository has multiple layers. Knowing the authority for each layer preven
 | Docker shared baseline inputs | `default-network.yml`, `default-environment.env`, `secrets/stack-secrets.env` | Shared network/env material applied during compose rendering. |
 | Infrastructure inventory and reconciliation | Terraform under `infrastructure/terraform/` | Codified inventory of existing infrastructure and relationships, especially Proxmox VMs and selected Docker mirrors. |
 | Secret policy and inventory | `docs/security-secrets.md` + `secrets/inventory.json` + local secret files in `secrets/` | What secrets exist, where they are expected, and what automation should parse. |
+| Host/device configuration bootstrap (emerging) | Ansible under `infrastructure/ansible/` | Gradual inventory/configuration layer for hosts/devices; validation-first at current stage. |
 
 ## Practical meaning
 
@@ -29,6 +30,17 @@ Use Terraform when documenting/reconciling existing:
 
 Do **not** treat Terraform as a full replacement for Compose operations in this repo.
 
+
+### Ansible bootstrap decisions
+
+Use Ansible under `infrastructure/ansible/` to build inventory and configuration structure incrementally.
+
+At the current stage:
+
+- Do **not** treat Ansible as replacement authority for Docker runtime operations.
+- Do **not** treat Ansible as replacement authority for Terraform inventory/reconciliation.
+- NixOS remains outside Ansible authority unless explicitly adopted in a later phase.
+
 ## Declared config vs observed/runtime state
 
 - **Declared config**: files in this repository (Compose, Terraform, docs).