CLAUDE.md

@@ -0,0 +1,48 @@
+# 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.

README.md

@@ -0,0 +1,46 @@
+# debian-configuration
+
+Configuration, hardening toolsets, and operational docs for Wayne's
+Debian-based LAN machines. Each subdirectory covers a different host or
+service type.
+
+## Layout
+
+```
+proxmox/   Proxmox VE hosts (pve1 production, pve-test sandbox)
+pihole/    Pi-hole DNS/DHCP (config snapshots, pull/apply scripts)
+scripts/   Repo-wide scripts (secret scanning, git hook installer)
+```
+
+## Sections
+
+### `proxmox/`
+
+Base configuration and hardening toolset for Proxmox VE hosts. See
+`proxmox/README.md` for goals, quick-start, and current status.
+
+### `pihole/`
+
+Pi-hole v6 configuration management. Stores a sanitised snapshot of the
+live config and provides scripts to pull from or push to a running
+instance. See `pihole/README.md` for usage.
+
+## Secret scanning
+
+All commits are scanned for secrets by a CI pipeline that runs on both
+GitHub Actions and Gitea Actions. The same scan can be run locally:
+
+```bash
+# One-time setup — installs a pre-commit git hook
+bash scripts/install-hooks.sh
+
+# Manual run against the full git history
+bash scripts/check-secrets.sh
+
+# Requires gitleaks on PATH; falls back to Docker if available
+# https://github.com/gitleaks/gitleaks#installing
+```
+
+`pihole/pull-config.sh` automatically redacts sensitive fields
+(`pwhash`, `totp_secret`, `app_pwhash`) from `pihole.toml` before
+writing it to disk, so the repo stays clean by default.

pihole/README.md

@@ -0,0 +1,67 @@
+# pihole
+
+Pi-hole v6 configuration management for `pihole.sweet.home`.
+
+## What's here
+
+```
+config/
+  pihole.toml                  Pi-hole v6 main config (sanitised snapshot)
+  dnsmasq.d/
+    99-ipxe-chainload.conf     Custom DHCP rules for EFI/BIOS iPXE PXE boot
+pull-config.sh                 Pull live config from a Pi-hole to a local dir
+apply-config.sh                Apply a local config dir to a Pi-hole instance
+sanitize-config.sh             Redact sensitive fields from pihole.toml in-place
+```
+
+## Usage
+
+### Snapshot the live config
+
+```bash
+# Pulls pihole.toml + custom dnsmasq.d/ drop-ins, auto-redacts sensitive fields
+./pull-config.sh root@pihole ./config
+```
+
+### Apply config to a new Pi-hole
+
+```bash
+# Destination must have Pi-hole v6 already installed
+./apply-config.sh ./config root@pihole-new
+```
+
+Both scripts take `<source> <destination>` as positional arguments.
+Source/destination is an SSH target (e.g. `root@pihole`, `root@192.168.2.253`)
+for the live side and a local directory path for the config side.
+
+### Restore blocklists after applying
+
+`apply-config.sh` transfers config only — not the gravity database.
+Run this on the destination after applying to rebuild blocklists:
+
+```bash
+ssh root@pihole-new "pihole updateGravity"
+```
+
+## Notable config
+
+### `dnsmasq.d/99-ipxe-chainload.conf`
+
+Enables architecture-aware PXE boot via DHCP:
+
+| Client | Vendor class | Boot file served |
+|---|---|---|
+| EFI iPXE already running | arch 7 + option 175 | `http://.../boot.ipxe` |
+| BIOS iPXE already running | arch 0 + option 175 | `http://.../boot.ipxe` |
+| EFI, no iPXE yet | `PXEClient:Arch:00007` | `ipxe.efi` via TFTP |
+| BIOS/legacy, no iPXE yet | `PXEClient:Arch:00000` | `undionly.kpxe` via TFTP |
+
+Proxmox EFI VMs also require a **VirtIO RNG device** (gives OVMF
+enough entropy to complete PXE negotiation) and **Secure Boot disabled**
+(`pre-enrolled-keys=0` on the EFI disk, or disabled in UEFI setup).
+
+## Secrets
+
+`pihole.toml` is stored with `pwhash`, `totp_secret`, and `app_pwhash`
+redacted to empty strings. `pull-config.sh` does this automatically.
+To redact manually: `./sanitize-config.sh config/pihole.toml`.

proxmox/README.md

@@ -1,3 +1,5 @@
+> Part of the [debian-configuration](../README.md) repo — see the root README for repo-wide layout and secret-scanning setup.
+
 # Proxmox Configuration
 
 Base configuration and hardening toolset for Proxmox VE hosts, plus planning