# CLAUDE.md

Guidance for Claude Code working in this repo. IMPORTANT: these
instructions OVERRIDE any default behavior and must be followed exactly
as written.

## Repo purpose

Base configuration/hardening toolset and planning docs for Proxmox VE
hosts (`scripts/`, `config/`, `docs/`) — see `README.md` and
`docs/00-overview.md`. Scripts in this repo are meant to be run **on**
the target Proxmox host itself (as root), not orchestrated remotely.

## Two Proxmox nodes: `pve1` (production) and `pve-test` (sandbox)

Two SSH-reachable Proxmox nodes exist on the LAN. They are **not
interchangeable** — see `docs/05-node-roles.md` for full background on
what each one is and why.

### `pve1` (production — off-limits to Claude by default)

A real, live Proxmox node hosting production VMs/containers (see
`docs/05-node-roles.md` for the current guest list) — not a sandbox, and
not Claude's to touch by default.

- **Off-limits at all times unless the operator has given explicit,
  same-session instructions to act on this specific host.** That
  authorization is scoped to the task it was given for — don't carry it
  forward to unrelated later work in the same conversation, and never
  assume it from a previous session.
- **Read-only for existing state is always fine, authorization or not.**
  SSH in (or use `pvesm`, `qm list`, `pct list`, `qm config`, `pct
  config`, the Proxmox API, etc.) to inspect config, storage, and any
  existing VM/container freely.
- **Never** modify, stop, restart, delete, reconfigure, or create
  anything on this node (`qm set`, `pct set`, `qm destroy`, `pct
  destroy`, `qm stop`, `pct stop`, `qm create`, `pct create`, snapshot
  operations, storage changes, running any script in this repo against
  it, etc.) without that explicit go-ahead. Use `pve-test` for anything
  exploratory instead.
- If a guest on `pve1` is HA-managed, be aware of the self-fence hazard
  described in `docs/05-node-roles.md`'s cluster-teardown section before
  doing anything that could cost the node quorum.

### `pve-test` (sandbox — Claude's default target)

A separate node set aside for testing — safe to create, interrogate, and
destroy scratch VMs/containers on without asking first.

- **Test VMs/containers are allowed, but must be torn down.** Anything
  created this way must be destroyed again in the same session, before
  ending the task. Use an obviously-scratch VMID/name.
- **Node-level config is still not yours to change by default.**
  Creating/destroying your own scratch guests is fine; Proxmox host
  config, storage pools, and networking on `pve-test` itself need the
  operator's explicit go-ahead too, same as on `pve1` — the "sandbox"
  status covers guest-level experimentation, not the host's own
  identity. (`pve-test`'s current network config, `docs/06-pve-test-wifi-network.md`,
  was applied under exactly that kind of explicit, same-session
  authorization — it's not a standing invitation to keep changing it
  further without asking again.)
- **Never re-cluster `pve-test` with `pve1`** without the operator
  explicitly asking for it and being aware of the wifi/corosync
  incompatibility in `docs/06-pve-test-wifi-network.md` — the two were
  deliberately de-clustered for this reason once already.

## Safety rules

- Any script in `scripts/` that isn't `audit.sh` (read-only) makes real
  changes when run for real. Don't run one against `pve1`, or against
  `pve-test`'s node-level config, without the same-session go-ahead
  described above. Running a script *against pve-test's own guests* — a
  scratch VM/CT you created for this task — doesn't need separate
  permission.
- Do not commit secrets: SSH private keys, wifi passphrases, sops/age
  keys, or PVE credentials. `scripts/setup-wifi-bond-network.sh` takes
  the SSID/passphrase via environment variables for exactly this reason
  — never hardcode them into the script or a committed config file.
- Live changes to a node's own management network (the interface/bridge
  carrying the SSH session you're using) can strand the box — see the
  "what went wrong once" section in `docs/06-pve-test-wifi-network.md`
  before touching `pve-test`'s networking again. Prefer applying via
  `ifreload -a` over raw `ip link` surgery, and arm an auto-revert
  watchdog first when acting without someone physically at the console.