AGENTS.md: Document switches, deploy --boot, and memory policy

- Note `CLAUDE.md` is a symlink to `AGENTS.md` (edit the real file).
- Policy: prefer recording durable guidance here over agent memory.
- Add the "Home switches" section (`jim`/`dave`/`brian`, access,
  confirm-before-apply) pointing at `home-switches.md`.
- Document `deploy --boot` for staging a config without live-switching.
- Note the `ssh-agent` hang workaround for outbound SSH (`ssh-machine`/`deploy`).
- Add a comment convention: comment where useful, not for trivial code, and
  describe general purpose rather than the one-off reason for a change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

AGENTS.md

@@ -2,6 +2,13 @@
 
 This file provides guidance to coding agents when working with code in this repository.
 
+`CLAUDE.md` at the repo root is a symlink to this file — edit `AGENTS.md`, not the symlink (some
+tools refuse to write through a symlink and will error on `CLAUDE.md`).
+
+**Prefer this file over agent memory.** When you learn something durable about this repo — a
+convention, a workflow gotcha, a design rationale — record it here (or in a repo doc this file points
+to, e.g. `home-switches.md`), not in agent memory. AGENTS.md is versioned and shared; memory is not.
+
 ## Overview
 
 Personal Nix flake managing NixOS systems and home-manager configurations for a set of
@@ -28,11 +35,16 @@ Common ones:
   Pass the flake-qualified node, e.g. `deploy .#git`. The deploy node name is **always** the system
   name (`deploy-rs.nix` keys nodes directly off `nixos.systems` / `home-manager.homes`); a system is
   only a deploy target when `config.my.deploy.enable` is true (defaults true; auto-disabled for dev
-  VMs and containers).
+  VMs and containers). Pass `--boot` to stage a config as the boot default **without** live-switching
+  (`deploy --boot .#<host>`) — the box keeps running its current generation until it reboots. Use this
+  when a live `switch` would break connectivity mid-change (e.g. a router's WAN VLAN rework), then
+  reboot to cut over.
 - `ssh-machine <name> [cmd]` — SSH to a NixOS system or home-manager config by name. Resolves the
   target and ssh options (identity, port) from its deploy-rs node, so it needs `my.deploy.enable`
   (same gate as `deploy`). Boxes default to the `fish` login shell, so pipe multi-statement remote
   scripts through `bash` (e.g. `ssh-machine <name> bash -s < script.sh`) rather than `&&`/`for`.
+  If outbound SSH hangs at the publickey step (flaky `ssh-agent`), disable the agent for the call:
+  `SSH_AUTH_SOCK= ssh-machine …` (or add `-o IdentityAgent=none` to a raw `ssh`).
 - `ragenix` — edit age secrets using `.keys/dev.key` as identity (see Secrets).
 - `repl` — `nix repl .#`.
 - `update-nixpkgs` / `update-home-manager` — bump pinned inputs.
@@ -115,6 +127,20 @@ box file, not `routing-common`.
   easy to mix up. Set an interface MTU via the `.network`'s `linkConfig.MTUBytes` (`[Link]`), not
   `netdevConfig` (`[NetDev]` rejects `MTUBytes`).
 
+### Home switches (`jim` / `dave` / `brian`)
+The home boxes and the Digiweb WAN hang off hand-configured switches that are **not** managed by
+this flake: `jim` and `dave` (MikroTik, RouterOS) and `brian` (Ubiquiti, UniFi). The full topology,
+VLAN map, and the ONT/WAN path live in **`home-switches.md`** at the repo root — read it before
+touching anything WAN/VLAN-related, and update it when the switch layout changes.
+- **Access:** the switches resolve by **short hostname** on the home network (the routers serve
+  their records in the home zone — `routing-common/dns.nix`: `jim`/`dave`/`brian`). From a home box,
+  SSH to the MikroTiks as `admin`/`admin` (e.g. `ssh admin@jim`); `brian` is configured via the
+  UniFi controller, not a CLI.
+- **Changing switch config is out-of-band and hard to revert — always confirm before applying:**
+  print the affected menu, make the change, then re-verify. The nix config and the switches must
+  agree on VLAN numbering (e.g. `lib.my.c.home.vlans`), so a switch-side change usually pairs with a
+  box change; `home-switches.md` documents the switch layout and per-switch config for the WAN design.
+
 ## Secrets
 
 age-encrypted secrets in `secrets/`, managed with **ragenix**. Each module declares
@@ -130,6 +156,9 @@ private keys) is required for editing secrets, deploying, and running dev VMs.
   **Ask before running `fmt`** — some files aren't canonically formatted, so `fmt` can reindent a
   whole file and bury a logical change in whitespace churn. Match the surrounding style by hand and
   leave formatting to the user unless they ask.
+- Comment where it genuinely aids understanding, but not for trivial/obvious code — match the file's
+  existing (fairly sparse) comment density. When adding something general, comment its general
+  purpose, not the specific change or one-off reason it was introduced for.
 - Prefer `lib.my` helpers (`mkOpt'`, `mkBoolOpt'`, `mkDefault'`) and `lib.my.c` constants over
   reimplementing.
 - New shared functionality → a module in `*/modules/` + entry in `_list.nix`, options under `my.*`.