# CLAUDE.md - Project context for AI assistants

## What this repository is

A collection of peripheral tools, scripts, and snippets for working with
Incus, IncusOS, and the broader ecosystem (Operations Center, Migration Manager).
Primarily targeting home lab environments but aiming for production-quality scripts.

## Repository structure

```
incus-contrib/
├── CLAUDE.md              # This file -- behavioral rules + project overview
├── .claude/rules/         # Topic-specific context (auto-loaded by paths:)
├── .claude/skills/        # Slash commands: /screenshot, /proxmox-api
├── README.md              # Main overview
├── .gitignore
├── ansible/               # Ansible playbooks for AWX/Aether lifecycle hooks
│   ├── ansible.cfg
│   └── playbooks/
│       ├── post-deploy.yml    # Runs after Aether creates an instance
│       └── decommission.yml   # Runs before Aether deletes an instance
├── incusos/               # IncusOS installation tooling
│   ├── README.md
│   ├── incusos-iso        # ISO/IMG builder (wraps flasher-tool)
│   ├── incusos-seed       # Seed archive generator (Linux + macOS)
│   ├── incusos-proxmox    # Declarative Proxmox VM deployment + lab lifecycle
│   ├── deploy-awx         # AWX deployment + management on Incus cluster
│   ├── awx-manifests/     # K8s manifests for AWX Operator + instance
│   ├── helpers/
│   │   ├── proxmox-screenshot  # VMID -> PNG console screenshot
│   │   └── proxmox-api         # Authenticated API calls (handles ! in token)
│   ├── lab-test           # Guided lab validation (12 test phases)
│   ├── observe-deploy     # Single-VM deploy with console screenshots
│   ├── proxmox.yaml       # Proxmox connection (gitignored)
│   ├── TESTING.md
│   └── examples/          # Example seed + Proxmox YAML files
├── env                    # PROXMOX_TOKEN_SECRET + PROXMOX_ROOT_PASSWORD (gitignored)
└── notes/                 # Reference guides (clustering, networking, OC, AWX, etc.)
```

## Capabilities you have

### Proxmox VM screenshots
Take console screenshots during deploys to see boot progress or errors:
```
incusos/helpers/proxmox-screenshot VMID [/tmp/output.png]
```
Use the Read tool on the PNG to view it. **USE THIS PROACTIVELY** during
deploy scenarios to monitor boot progress, diagnose hangs, and verify installs.

### Proxmox API calls
Make authenticated API calls (handles the `!` in `automation@pve!deploy`):
```
incusos/helpers/proxmox-api GET /nodes/pve/qemu/900/status/current --json
incusos/helpers/proxmox-api GET /nodes/pve/status --json
incusos/helpers/proxmox-api POST /nodes/pve/qemu/900/status/stop
```

### Live AWX job output
Capture output while a job is running (don't just poll status):
```bash
curl -sk http://192.168.102.161:30080/api/v2/jobs/{JOB_ID}/stdout/?format=txt \
  -H "Authorization: Bearer $AWX_TOKEN"
```

## Critical safety rules

- **Proxmox SSH is screenshots-only.** Full rules in `.claude/rules/proxmox-ssh-rules.md`.
- **Never hard-stop VMs during first boot** -- corrupts TPM permanently.
- **Boot timeout is 180s** -- do not reduce (sysext download takes 30-120s).
- **No `force_reboot` in seeds for Proxmox** -- causes crontab race condition.
- **VMID ranges**: 400-499 (OC), 800-809 (single), 900-939 (clusters).

## Coding conventions

- **Shell**: bash with `set -euo pipefail`
- **Arithmetic**: `var=$((var + 1))` not `((var++))` (set -e safety)
- **Colors**: support `NO_COLOR=1` and `TERM=dumb`; use `setup_colors()` pattern
- **Flags**: both short (`-d`) and long (`--defaults`)
- **Defaults**: useful behavior with zero flags
- **Dry run**: all scripts support `--dry-run`
- **Cert detection**: files on disk first (`~/.config/incus/client.crt`), CLI second
- **Errors**: include actionable remediation steps
- **No hardcoded package managers**: say "install the Incus client" with a link

## Technical context loading

Detailed technical context loads automatically from `.claude/rules/` based on
which files are being edited:

| Rule file | Loads when editing |
|---|---|
| `incusos-scripts.md` | incusos-iso, incusos-seed, incusos-proxmox, helpers |
| `proxmox-deployment.md` | incusos-proxmox, observe-deploy, helpers, examples |
| `clustering.md` | lab-test, incusos-proxmox, clustering/production guides |
| `operations-center.md` | OC guide, incusos-proxmox, OC example configs |
| `networking-storage.md` | networking, storage, migration, UTM guides |
| `awx-integration.md` | ansible/, deploy-awx, awx-manifests, AWX guide |
| `proxmox-ssh-rules.md` | **Always loaded** (no paths filter) |
| `lab-infrastructure.md` | incusos-proxmox, lab-test, examples |

For deep reference, see the guides in `notes/`.

## Git workflow

- **Main branch**: `master`
- **Remotes**:
  - `origin`: `ssh://git@192.168.1.200:2222/maarten/incus-contrib.git` (private Gitea)
  - `aether`: `_gitea@code.sovereignprivatecloud.nl:maarten/incus-contrib.git`
- Push to **both remotes** when committing
- Development happens on feature branches