Add Codex repository guidance and validation

docs/codex/README.md

@@ -0,0 +1,55 @@
+# Codex Workflow
+
+This directory keeps future Codex sessions consistent when working in this infrastructure portfolio.
+
+## How To Start
+
+1. Read [AGENTS.md](../../AGENTS.md).
+2. Inspect the affected tree and nearby README files.
+3. Check `git status --short` so existing user work is preserved.
+4. Decide whether a plan is needed before editing.
+5. Make small, reviewable changes.
+6. Run focused validation plus `./scripts/validate-repo.sh` when practical.
+
+## When To Plan First
+
+Plan before editing when a task touches more than one subsystem, changes operational behavior, adds or modifies destructive actions, changes Ansible targeting, or updates repository conventions.
+
+For small typo fixes, narrow README updates, or obvious syntax fixes, inspect first and then make the change directly.
+
+Use [plans-template.md](./plans-template.md) for larger changes.
+
+## Scoped Tasks
+
+Good tasks name the operational goal, affected directories, constraints, validation commands, and what "done" means. Use [task-template.md](./task-template.md) for reusable prompts.
+
+Keep scope tied to real operations:
+
+- Bash tool: discovery, pre-check, dry-run, execute, post-check, report.
+- Ansible change: inventory target, role/playbook scope, check mode, idempotency, validation.
+- Runbook: incident signal, triage, decision points, rollback, evidence.
+- Lab/platform project: status, prerequisites, validation, limitations.
+
+## Validation
+
+Prefer the repository helpers:
+
+```bash
+./scripts/check-bash.sh
+./scripts/check-ansible.sh
+./scripts/check-docs.sh
+./scripts/validate-repo.sh
+```
+
+If optional tools are missing, report that clearly and continue with available checks. Do not claim skipped checks passed.
+
+## Final Response Format
+
+End with:
+
+1. Summary of what changed.
+2. Files created or modified.
+3. Validation commands run and results.
+4. Skipped checks and why.
+5. Risks or follow-ups.
+6. Whether the repo is ready for future Codex-driven work.

docs/codex/plans-template.md

@@ -0,0 +1,35 @@
+# Implementation Plan Template
+
+Use this for changes that touch multiple files, alter operational behavior, or add new repository conventions.
+
+## Goal
+
+State the operational or maintenance outcome.
+
+## Current State
+
+Summarize the directories and conventions inspected.
+
+## Scope
+
+List files or directories expected to change.
+
+## Non-Goals
+
+Name what will not be redesigned, renamed, deleted, or claimed as complete.
+
+## Plan
+
+1. Inspect relevant scripts, playbooks, docs, and examples.
+2. Make the smallest structural or documentation changes needed.
+3. Update validation or runbook guidance.
+4. Run focused checks.
+5. Summarize residual risk and follow-ups.
+
+## Validation
+
+List commands to run, including fallback behavior for missing tools.
+
+## Risks
+
+Call out destructive operations, platform assumptions, missing lab environments, or checks that require real systems.

docs/codex/review-checklist.md

@@ -0,0 +1,52 @@
+# Review Checklist
+
+Use this checklist for repository reviews and pull requests.
+
+## Safety
+
+- Destructive actions default to dry-run or read-only.
+- Real changes require explicit `--execute` and operator confirmation.
+- Inputs are validated before use.
+- Paths, service names, disks, volumes, and inventory targets are constrained.
+- Rollback or recovery thinking is documented where the operation can change state.
+
+## Bash
+
+- Uses `#!/usr/bin/env bash`.
+- Uses `set -o errexit`, `set -o nounset`, and `set -o pipefail`.
+- Missing commands return a clear warning or invalid-input/dependency exit.
+- Output uses `OK`, `WARNING`, and `CRITICAL` consistently.
+- Exit codes follow repo convention: `0` OK, `1` operational issue, `2` invalid input or missing dependency.
+- Help output exists for scripts that accept arguments.
+
+## Ansible
+
+- Target hosts are explicit and appropriate for the role.
+- Modules are preferred over `shell` or `command`.
+- Check mode and diff mode are considered.
+- Tasks are idempotent or clearly documented when a check is inherently read-only or platform-specific.
+- Handlers, tags, defaults, and validation tasks are used where useful.
+- Inventory, vars, and role defaults do not contain secrets or real environment data.
+
+## Documentation
+
+- README files explain current state without overstating completeness.
+- Runbooks include scope, pre-checks, execution controls, post-checks, and evidence.
+- Docs avoid tutorial filler and fake enterprise complexity.
+- Important limitations are linked or documented.
+- `CHANGELOG.md` is updated for meaningful repo changes.
+
+## Operational Realism
+
+- The change reflects RHEL/Oracle Linux, Debian/Ubuntu, AIX, Veritas, GPFS, Zabbix, ELK, Docker, Kubernetes/K3s, Terraform, VMware, or Proxmox operations accurately.
+- Examples remain sanitized.
+- Placeholder projects are identified as placeholders.
+- There is no unnecessary abstraction or invented complexity.
+
+## Validation
+
+- Changed Bash scripts pass `bash -n`.
+- `shellcheck` was run if available, or its absence was reported.
+- Ansible syntax/lint checks were run if available and relevant.
+- YAML/Markdown sanity checks were run if available.
+- Failures and skipped checks are visible in the final summary.

docs/codex/task-template.md

@@ -0,0 +1,276 @@
+# Task Templates
+
+Copy the relevant section into a future Codex request and fill in the blanks.
+
+## Operational Bash Tool
+
+### Goal
+
+Build or improve a Bash tool for:
+
+### Context
+
+Affected platform, incident, or operational workflow:
+
+### Constraints
+
+- Default to dry-run/read-only.
+- Require `--execute` for changes.
+- Use `OK`, `WARNING`, and `CRITICAL`.
+- Exit `0` OK, `1` operational issue, `2` invalid input or missing dependency.
+
+### Files/directories to inspect
+
+- `infra-run/scripts/bash/`
+- Relevant runbook or README:
+
+### Implementation steps
+
+1. Inspect neighboring scripts and shared helpers.
+2. Add or adjust usage/help output.
+3. Add discovery, pre-check, guarded change, post-check, and reporting sections where useful.
+4. Update README or runbook notes.
+
+### Validation commands
+
+```bash
+bash -n <script>
+./scripts/check-bash.sh
+```
+
+### Done when
+
+The tool is readable, safe by default, validates inputs, reports clearly, and has updated docs.
+
+## Ansible Playbook/Role
+
+### Goal
+
+Add or improve Ansible automation for:
+
+### Context
+
+Target OS and inventory group:
+
+### Constraints
+
+- Preserve check-mode friendliness.
+- Prefer modules over shell/command.
+- Keep playbooks short.
+- Keep role defaults sanitized.
+
+### Files/directories to inspect
+
+- `infra-run/ansible/README.md`
+- `infra-run/ansible/inventory/`
+- `infra-run/ansible/playbooks/`
+- `infra-run/ansible/roles/`
+
+### Implementation steps
+
+1. Inspect existing role/playbook patterns.
+2. Add defaults, tasks, handlers, and tags only where needed.
+3. Add validation or post-check tasks for operational evidence.
+4. Update role/playbook README.
+
+### Validation commands
+
+```bash
+./scripts/check-ansible.sh
+cd infra-run/ansible && ansible-playbook --syntax-check -i inventory/hosts.yml playbooks/<playbook>.yml
+```
+
+### Done when
+
+The playbook targets the right hosts, is idempotent where practical, supports review with `--check --diff`, and docs explain limitations.
+
+## Runbook
+
+### Goal
+
+Create or improve a runbook for:
+
+### Context
+
+Incident signal, platform, and affected service:
+
+### Constraints
+
+- Include pre-checks, decision points, rollback, post-checks, and evidence.
+- Avoid pretending lab notes are production-certified.
+
+### Files/directories to inspect
+
+- `infra-run/runbooks/`
+- `infra-run/docs/`
+- Related scripts/examples:
+
+### Implementation steps
+
+1. Define scope and assumptions.
+2. Add triage steps and command examples.
+3. Add safe execution gates.
+4. Add validation and handoff notes.
+
+### Validation commands
+
+```bash
+./scripts/check-docs.sh
+```
+
+### Done when
+
+An operator can follow the runbook without guessing the risk, inputs, or success criteria.
+
+## Lab Scenario
+
+### Goal
+
+Add or improve a lab scenario for:
+
+### Context
+
+Technology and local environment:
+
+### Constraints
+
+- Mark lab-only behavior clearly.
+- Keep prerequisites and cleanup explicit.
+
+### Files/directories to inspect
+
+- `labs/`
+- `labs/docs/lab-cheatsheet.md`
+
+### Implementation steps
+
+1. Document prerequisites and topology.
+2. Add setup, validation, failure injection if relevant, and cleanup.
+3. Link related scripts or runbooks.
+
+### Validation commands
+
+```bash
+./scripts/check-docs.sh
+```
+
+### Done when
+
+The lab is reproducible enough to review and does not imply production readiness.
+
+## Platform Project
+
+### Goal
+
+Add or improve a platform project for:
+
+### Context
+
+Monitoring, storage, clustering, virtualization, observability, or related topic:
+
+### Constraints
+
+- Keep status honest: planned, partial, lab-tested, or complete.
+- Prefer operational notes over marketing language.
+
+### Files/directories to inspect
+
+- `platform-projects/`
+- `platform-projects/docs/platform-cheatsheet.md`
+
+### Implementation steps
+
+1. Identify scope and current maturity.
+2. Add design notes, operational workflows, and validation.
+3. Link runbooks, examples, and known limitations.
+
+### Validation commands
+
+```bash
+./scripts/check-docs.sh
+```
+
+### Done when
+
+The project explains what exists, how to validate it, and what remains unproven.
+
+## Documentation Cleanup
+
+### Goal
+
+Clean up documentation for:
+
+### Context
+
+Current confusion, duplication, or missing links:
+
+### Constraints
+
+- Preserve useful operational detail.
+- Avoid tutorial-style filler.
+
+### Files/directories to inspect
+
+- Root `README.md`
+- Section README files
+- Related docs/runbooks:
+
+### Implementation steps
+
+1. Remove duplication where it hurts navigation.
+2. Add links to canonical docs.
+3. Make limitations explicit.
+4. Update changelog if meaningful.
+
+### Validation commands
+
+```bash
+./scripts/check-docs.sh
+```
+
+### Done when
+
+Readers can find the right tool, runbook, or validation command quickly.
+
+## Repository Review
+
+### Goal
+
+Review repository quality for:
+
+### Context
+
+Areas of concern:
+
+### Constraints
+
+- Findings first, ordered by severity.
+- Include file/line references where possible.
+- Do not rewrite unrelated content.
+
+### Files/directories to inspect
+
+- `AGENTS.md`
+- `README.md`
+- `infra-run/`
+- `platform-projects/`
+- `labs/`
+- `scripts/`
+
+### Implementation steps
+
+1. Inspect structure and conventions.
+2. Review safety, validation, docs, and maintainability.
+3. Patch only low-risk issues if requested.
+4. Report risks and follow-ups.
+
+### Validation commands
+
+```bash
+./scripts/validate-repo.sh
+git diff --stat
+```
+
+### Done when
+
+The review identifies practical risks and leaves a clear next action list.