Add README files and diagrams across repository

infra-run/ansible/README.md

@@ -0,0 +1,29 @@
+# infra-run/ansible
+
+This directory reserves the Ansible automation area for future infrastructure-as-code content. It is organized around the standard separation of inventory, roles, playbooks, collections, and tests.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["ansible"] --> B["collections"]
+  A --> C["inventory"]
+  A --> D["playbooks"]
+  A --> E["roles"]
+  A --> F["tests"]
+  C --> C1["group_vars"]
+  C --> C2["host_vars"]
+```
+
+## Scope
+
+- `collections` - vendored or custom Ansible collections.
+- `inventory` - environment inventory definitions and variables.
+- `playbooks` - executable playbooks for repeatable operations.
+- `roles` - reusable automation roles.
+- `tests` - validation and test harnesses for Ansible content.
+
+## Notes
+
+- The directory layout is already prepared for growth even where content is still placeholder-only.
+- This keeps the repository ready for automation expansion alongside the existing script toolkits.

infra-run/ansible/collections/README.md

@@ -0,0 +1,23 @@
+# infra-run/ansible/collections
+
+This folder is reserved for Ansible collections used by the `infra-run` automation area. It is intended for dependencies or custom collections that support playbooks and roles.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["collections"] --> B["External or custom collections"]
+  B --> C["Modules"]
+  B --> D["Plugins"]
+  B --> E["Roles integration"]
+```
+
+## Scope
+
+- Store collection dependencies close to the operational automation they support.
+- Keep collection usage explicit for repeatable execution in controlled environments.
+
+## Notes
+
+- The directory currently contains only a placeholder file.
+- A local README helps preserve intent before real collection content is added.

infra-run/ansible/inventory/README.md

@@ -0,0 +1,23 @@
+# infra-run/ansible/inventory
+
+This directory is intended for Ansible inventory definitions. It separates shared variables from host-specific values to support clean environment modeling and safer automation.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["inventory"] --> B["group_vars"]
+  A --> C["host_vars"]
+  B --> D["Shared environment variables"]
+  C --> E["Per-host overrides"]
+```
+
+## Scope
+
+- `group_vars` - variables applied at group or environment level.
+- `host_vars` - variables tailored to individual nodes.
+
+## Notes
+
+- The structure is present even though the repository currently keeps this area sanitized and mostly empty.
+- This is the natural companion to future playbooks and roles under `infra-run/ansible`.

infra-run/ansible/inventory/group_vars/README.md

@@ -0,0 +1,17 @@
+# infra-run/ansible/inventory/group_vars
+
+This folder is reserved for shared Ansible variables applied to inventory groups. It is the right place for environment defaults, role inputs, and group-level operational settings.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["group_vars"] --> B["Environment defaults"]
+  A --> C["Role parameters"]
+  A --> D["Shared operational values"]
+```
+
+## Notes
+
+- Use this layer when multiple hosts should inherit the same configuration.
+- The directory is currently a placeholder and does not expose environment-specific data.

infra-run/ansible/inventory/host_vars/README.md

@@ -0,0 +1,17 @@
+# infra-run/ansible/inventory/host_vars
+
+This folder is intended for host-specific Ansible variables. It complements `group_vars` by capturing node-level differences that should not be shared across an entire inventory group.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["host_vars"] --> B["Host A overrides"]
+  A --> C["Host B overrides"]
+  A --> D["Per-node secrets or tuning"]
+```
+
+## Notes
+
+- Use this area when operational differences are specific to one server.
+- The directory is intentionally empty in the sanitized portfolio state.

infra-run/ansible/playbooks/README.md

@@ -0,0 +1,18 @@
+# infra-run/ansible/playbooks
+
+This directory is intended for executable Ansible playbooks that coordinate roles, inventories, and operational tasks. In the current portfolio state it acts as a prepared entry point for future automation runs.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["playbooks"] --> B["Provisioning flows"]
+  A --> C["Hardening flows"]
+  A --> D["Patch workflows"]
+  A --> E["Decommission workflows"]
+```
+
+## Notes
+
+- Playbooks belong here when the repository expands beyond script-first operations.
+- The directory currently contains only placeholder content.

infra-run/ansible/roles/README.md

@@ -0,0 +1,18 @@
+# infra-run/ansible/roles
+
+This folder is reserved for reusable Ansible roles. Roles make it possible to organize configuration logic into predictable, testable units that can be shared across playbooks.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["roles"] --> B["common"]
+  A --> C["monitoring"]
+  A --> D["storage"]
+  A --> E["security"]
+```
+
+## Notes
+
+- The role layout is not yet populated, but the structure is in place for future automation modules.
+- Keeping a README here documents intent even before role code exists.

infra-run/ansible/tests/README.md

@@ -0,0 +1,17 @@
+# infra-run/ansible/tests
+
+This directory is reserved for validation of Ansible content. It represents the testing layer that would support inventories, roles, and playbooks as the automation footprint grows.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["tests"] --> B["Syntax checks"]
+  A --> C["Molecule or scenario tests"]
+  A --> D["Post-run validation"]
+```
+
+## Notes
+
+- The folder is currently a placeholder.
+- Its presence reflects a design goal of keeping automation testable, not just executable.