From 8c4223af1866b2f16202e6af09185d0943f72f0b Mon Sep 17 00:00:00 2001 From: Jack O'Sullivan Date: Thu, 23 Jul 2026 21:35:50 +0100 Subject: [PATCH] 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 --- AGENTS.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a216842..c9006fd 100644 --- a/AGENTS.md +++ b/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 .#`) — 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 [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 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.*`.