diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8b608bd
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# 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.