# CLAUDE.md

Guidance for Claude Code working in this repo. These instructions
OVERRIDE any default behaviour and must be followed exactly.

## Repo purpose

Configuration toolsets and docs for Wayne's Debian-based LAN machines.
Two sections currently exist: `proxmox/` (Proxmox VE hosts) and
`pihole/` (Pi-hole DNS/DHCP). Each has its own README.

## Safety rules (apply everywhere in this repo)

- **Never commit secrets.** SSH private keys, passwords, hashes, TOTP
  seeds, API tokens, or wifi passphrases must not appear in committed
  files. The CI pipeline (`scripts/check-secrets.sh`) enforces this on
  every push; the pre-commit hook (`scripts/install-hooks.sh`) catches
  it locally before it reaches the remote.
- **`pihole/pull-config.sh` auto-sanitises** sensitive fields from
  `pihole.toml` on every pull. If you write config to `pihole/config/`
  by any other means, run `pihole/sanitize-config.sh` on the result
  before committing.
- **Scripts that SSH into live machines make real changes.** Don't run
  `pihole/apply-config.sh` against a production Pi-hole, or any script
  in `proxmox/scripts/` against `pve1`, without an explicit same-session
  go-ahead from the operator. The section-specific CLAUDE.md files
  spell out the per-host guardrails in detail.

## Section-specific guidance

- **Proxmox:** see `proxmox/CLAUDE.md` — covers `pve1` (production,
  off-limits by default) vs. `pve-test` (sandbox, Claude's default
  target), per-host authorisation scope, and network-surgery hazards.
- **Pi-hole:** `pihole/` has no live-host guardrails beyond the secret
  rules above. `apply-config.sh` is the only script that touches a live
  host; treat its `<dest-host>` argument as production unless you're
  explicitly testing on a throwaway instance.

## Adding a new machine type

Create a new top-level directory (e.g. `nginx/`, `wireguard/`) with:
- `README.md` — purpose, quick-start, and current status
- `CLAUDE.md` — host-specific guardrails (which hosts are production,
  what requires explicit authorisation, what must never be committed)
- `scripts/` and/or `config/` as needed

Update the root `README.md` layout table and this file's
"Section-specific guidance" list when you do.