# Ansible Documentation

This folder contains **Ansible-specific** technical documentation for the homelab automation framework.

## Documentation Organization

The homelab uses a **domain-based separation** for documentation:

### Ansible-Specific Documentation (This Folder)

Documentation about **how Ansible works** in this homelab:

- **[ansible-knowledge/](ansible-knowledge/)** — Ansible syntax, YAML/Jinja2 reference, technical constraints
- **[playbooks/](playbooks/)** — Operational guides for running specific playbooks
- **[playbooks/README.md](playbooks/README.md)** — Playbook runbook index, including Watchtower monitoring onboarding and self-healing
- **[standards/ansible-quality-gates.md](standards/ansible-quality-gates.md)** — Ansible linting rules, security checklist, review workflow

### Homelab-Wide Documentation (Root `/documentation/`)

Documentation about **what the homelab allows** and architectural decisions:

- **[/documentation/architecture/](../../documentation/architecture/)** — Architectural contracts (control-plane, compute-plane, networking, storage, access-identity)
- **[/documentation/standards/](../../documentation/standards/)** — Homelab-wide standards (naming conventions, environment constraints, architecture decisions)
- **[/documentation/policies/](../../documentation/policies/)** — Operational policies (networking policy, etc.)
- **[/documentation/handover.md](../../documentation/handover.md)** — Primary project handover document

## Quick Reference

### When Troubleshooting Ansible Issues

1. **Syntax errors?** → [ansible-knowledge/ansible-syntax.md](ansible-knowledge/ansible-syntax.md)
2. **Playbook not working?** → [playbooks/README.md](playbooks/README.md) for operational guides
3. **Monitoring stack onboarding?** → [playbooks/watchtower-monitoring-onboarding.md](playbooks/watchtower-monitoring-onboarding.md)
4. **Linting failures?** → [standards/ansible-quality-gates.md](standards/ansible-quality-gates.md)

### When Designing Infrastructure

1. **What services can run where?** → [/documentation/architecture/compute-plane.md](../../documentation/architecture/compute-plane.md)
2. **Network topology?** → [/documentation/architecture/networking.md](../../documentation/architecture/networking.md)
3. **Storage architecture?** → [/documentation/architecture/storage.md](../../documentation/architecture/storage.md)
4. **Naming conventions?** → [/documentation/standards/naming-conventions.md](../../documentation/standards/naming-conventions.md)

## Files in This Folder

```text
ansible/documentation/
├── README.md                    # You are here
├── ansible-knowledge/           # Ansible syntax and technical reference
│   └── ansible-syntax.md
├── playbooks/                   # Operational guides for playbooks
│   ├── README.md
│   ├── manage_docker_environment.md
│   ├── mount_nfs_shares.md
│   ├── onboard_new_host.md
│   ├── onboard-ansible-secrets.md
│   └── watchtower-monitoring-onboarding.md
├── reports/                     # Analysis and audit reports
│   └── prompt-analysis-2026-01-09.md
└── standards/                   # Ansible-specific standards
    └── ansible-quality-gates.md
```

## Contributing

When adding new documentation:

- **Ansible-specific content** (syntax, modules, playbook operations) → Add to this folder
- **Homelab-wide content** (architecture, contracts, policies) → Add to `/documentation/` at the repository root

If unsure, ask: "Is this about how Ansible works, or about what the homelab architecture allows?"