# Home Assistant on Proxmox — Claude Context

## What This Repo Is

Ops/infra repo for installing and maintaining a **Home Assistant OS (HAOS)** VM on the
home Proxmox server (`pve`). HAOS — not Home Assistant Container/Docker — was chosen
deliberately: Container only runs HA Core (no Supervisor, no add-on store, manual
updates), which is the exact feature gap this project exists to avoid. HAOS is an
appliance OS; the VM's OS *is* Home Assistant, not Ubuntu-plus-a-service.

## Shared Proxmox Context

Host-level facts (Proxmox host address, VM inventory, token scoping, backup/snapshot
pattern) and the base safety rules live in the "Proxmox Host — Shared Infrastructure
Context" section of `../CLAUDE.md` (the umbrella file) — it auto-loads for any session in
this directory, so read that first. (Note: `@../` imports don't resolve across sibling
directories in Claude Code, which is why this is inlined in the umbrella file rather than
imported.)

## HAOS-Specific Facts

| Item | Value |
|---|---|
| VM OS | Home Assistant OS (HAOS) — appliance image, not a general Linux install |
| Install method | Official qcow2 disk image, imported on the Proxmox host (`qm importdisk` or equivalent) — **human-in-the-loop step**; the scoped API token has no host shell |
| VM access | No general SSH/apt admin surface — managed via the HA web UI and the HAOS console, unlike hermes01's systemd/apt setup |
| Status | Not yet created — VM import is a manual step performed by the human operator |

## Safety Rules (MUST follow)

Follow the shared host-level rules in the umbrella `../CLAUDE.md` (never touch VM 100, no
host shell, confirm destructive actions, scoped API token only). Additionally:

- VM creation/import for HAOS requires host-shell access the token doesn't have — treat
  as a **human-performed step**, never something Claude executes directly.
- Once the VMID is assigned, add it to the VM Inventory table in the umbrella `../CLAUDE.md`.

## Key Files

| File | Purpose |
|---|---|
| *(to be added as setup docs are written — e.g. a setup checklist mirroring `proxmox-hermes/hermes-on-proxmox-setup-checklist.md`)* | |

## Repo Conventions

- Documentation-first ops repo — no application code to build or test.
- Prefer editing existing files over creating new ones.
- Follow the same CLAUDE.md maintenance discipline as `proxmox-hermes` — see the maintenance
  guide referenced from the umbrella `../CLAUDE.md`'s Repo Conventions section (it resolves
  fine there since it's a subdirectory import, not a `../` cross-sibling one).

## What Claude Should Do When Asked to Help

1. Read the umbrella `../CLAUDE.md`'s "Proxmox Host — Shared Infrastructure Context" section first for host facts and safety rules.
2. Confirm scope before executing anything against live infrastructure.
3. For HA-specific questions, reference: https://www.home-assistant.io/installation/
4. VM creation/import steps are the human's to run — describe the steps, don't attempt them.