## Standards

### Ansible + YAML conventions

- **Indentation**: 2 spaces (no tabs)
- **Task naming**: every task should include a clear `name:`
- **Play-level privilege**: prefer `become: true` at play level when most tasks need sudo
- **Modules**:
  - Prefer native modules over `shell`/`command`
  - Use **fully qualified collection names** (FQCN), e.g. `ansible.builtin.apt`, `community.general.ufw`
- **Handlers**: use handlers for restarts/reloads
- **Idempotency**:
  - If `shell`/`command` is unavoidable, set `changed_when:` / `creates:` / `removes:` appropriately

### Role structure

Roles should follow:

```
roles/<role_name>/
├── defaults/main.yml
├── handlers/main.yml
├── tasks/main.yml
├── templates/
├── files/
└── README.md
```

### Variable naming

- **snake_case** everywhere
- Vault-backed variables are prefixed with **`vault_`**

### Secrets / Vault

- Never commit plaintext secrets.
- Use Ansible Vault for credentials:
  - `inventories/production/group_vars/all/vault.yml` (encrypted)
- Local vault password file is expected at `~/.ansible-vault-pass`.

### Makefile-first workflow

- Prefer `make ...` targets over direct `ansible-playbook` commands for consistency.

### Linting

- `ansible-lint` is the primary linter.
- `.ansible-lint` excludes vault-containing inventory paths to keep linting deterministic without vault secrets.