docs: Document the boxes

Add a top-level `README.md` mapping the boxes and per-machine docs under
`docs/boxes/` (grouped `colony/`, `home/`, `misc/`), one file per host, VM and
container documenting role, services and networking with source pointers.

Also point `AGENTS.md` at the new docs.

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

.gitea/workflows/ci.yaml

@@ -7,10 +7,10 @@ on:
 jobs:
   check:
     name: Check, build and cache nixfiles
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
-      - uses: cachix/install-nix-action@v27
+      - uses: cachix/install-nix-action@v31
         with:
           # Gitea will supply a token in GITHUB_TOKEN, which this action will
           # try to pass to Nix when downloading from GitHub

AGENTS.md

@@ -0,0 +1,118 @@
+# AGENTS.md
+
+This file provides guidance to coding agents when working with code in this repository.
+
+## Overview
+
+Personal Nix flake managing NixOS systems and home-manager configurations for a set of
+machines ("boxes": servers, home machines, routers). It is built around a **custom module system** layered
+on top of NixOS/home-manager, not the stock flake `nixosConfigurations` pattern.
+
+## Commands
+
+This repo provides a `numtide/devshell` (entered via `direnv` / `use flake`). The shell defines
+named commands — prefer them over raw `nix` invocations. Run a bare command name with no args to
+see its help, or browse `devshell/commands.nix` / `devshell/install.nix` / `devshell/vm-tasks.nix`.
+
+Common ones:
+- `fmt` — format Nix with `nixpkgs-fmt` (the canonical formatter here).
+- `build-system <host> [nix args]` — build a NixOS system's `toplevel`.
+- `build-n-switch <args>` — wraps `doas nixos-rebuild --flake .`.
+- `build-home <name>` / `home-switch` — build / switch a home-manager config.
+- `run-vm <host>` — build & boot a system as a dev VM (installs `.keys/dev.key` into the VM).
+- `build-iso` / `build-kexec` / `build-netboot <host>` — alternate build outputs via `config.my.buildAs.*`.
+- `check-system <host> [nix args]` — evaluate a system (catches eval errors without a full build).
+  **Prefer this over `build-system` to validate a config change** — evaluation surfaces module/option
+  errors quickly and cheaply; only do a full build when you specifically need the built artifact.
+- `deploy <host>` and `deploy-multi <hosts...>` — deploy-rs deployment (uses `.keys/deploy.key`, `--skip-checks`).
+  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).
+- `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`).
+- `ragenix` — edit age secrets using `.keys/dev.key` as identity (see Secrets).
+- `repl` — `nix repl .#`.
+- `update-nixpkgs` / `update-home-manager` — bump pinned inputs.
+
+Check everything (what CI runs): `nix flake check --no-build`.
+CI builds each attr of `.#ci.x86_64-linux` (systems, homes, packages, shell) and pushes to the
+Harmonia binary cache; see `.gitea/workflows/ci.yaml` and `ci/push-to-cache.sh`.
+
+## Architecture
+
+### The custom module system
+`flake.nix` does **not** call `nixosSystem` per host directly. Instead it `evalModules` over
+`./nixos`, `./home-manager`, `./deploy-rs.nix`, and the per-host files listed in the `configs`
+list in `flake.nix`. That evaluation produces a top-level config (`self.nixfiles`) from which the
+real flake outputs are derived:
+- `nixos.systems.<name>` → `nixosConfigurations.<name>`
+- `home-manager.homes.<name>` → `homeConfigurations.<name>`
+- `nixos.modules` / `home-manager.modules` → `nixosModules` / `homeModules`
+- `deploy-rs.rendered` → `deploy`
+
+`nixos/default.nix` and `home-manager/default.nix` define the `systemOpts` / `homeOpts` submodules
+and the `mkSystem` / `mkHome` functions that actually invoke `eval-config.nix` /
+`homeManagerConfiguration`. **To add a new host:** create a box file that sets
+`nixos.systems.<name> = { ... }`, then add its path to the `configs` list in `flake.nix`.
+
+### Multiple nixpkgs channels
+Four pkgs sets are threaded everywhere as `pkgsFlakes` / `pkgs'` (and `hmFlakes` for home-manager):
+`unstable`, `stable`, `mine` (a personal nixpkgs fork), `mine-stable`. Each system/home picks its
+channel via `nixpkgs` / `home-manager` / `hmNixpkgs` options (e.g. `nixpkgs = "mine-stable"`).
+Modules receive `pkgs'` = an attrset of all channels for the current system.
+
+### `lib.my` and the `my` option namespace
+`lib/default.nix` extends `lib` with a `my` attrset (helpers like `mkOpt'`, `mkBoolOpt'`,
+`mkDefault'`, `inlineModule'`, `mkDefaultSystemsPkgs`, `homeStateVersion`). It also pulls in:
+- `lib.my.net` — network/CIDR helpers from the `libnetRepo` input. Used heavily for IP math.
+- `lib.my.c` — shared constants from `lib/constants.nix` (UIDs/GIDs, kernel package selection,
+  nginx snippets, per-network domains/prefixes, etc.). Reuse these rather than hardcoding.
+- `lib.my.dns` — DNS helpers (`lib/dns.nix`).
+
+Custom modules add options under the `my.*` namespace (e.g. `my.secrets`, `my.build`,
+`my.tmproot`, `my.server`). Use `mkOpt'`/`mkBoolOpt'` for option declarations to match style.
+
+### Modules and module lists
+Module sets are registered in `nixos/modules/_list.nix` and `home-manager/modules/_list.nix`
+(name → path), which become `nixos.modules` / `home-manager.modules` and are applied to every
+system/home. To add a shared module, drop the file in `nixos/modules/` (or `home-manager/modules/`)
+and add an entry to the relevant `_list.nix`.
+
+### Network assignments
+Each system declares `assignments.<name>` (in its `nixos.systems.<host>` block) with IPv4/IPv6
+addresses, gateways, domains, MTU, etc. These are aggregated into `allAssignments` (passed to every
+module) and there is an assertion that fails on duplicate IPs. Host networking
+(`networking.hostName`, `domain`) defaults from the `internal` assignment.
+
+### Hosts / "boxes"
+Per-host configs live under `nixos/boxes/<host>` (some are single `.nix` files, some directories
+with nested VMs/containers under e.g. `colony/vms`). Many "systems" are VMs or containers managed
+via the `vms` / `containers` modules and the `l2mesh` VXLAN module.
+
+For a human-readable map of what is actually deployed (per-machine roles, services and networking),
+see `README.md` and the per-machine docs under `docs/boxes/` (grouped `docs/boxes/colony/`,
+`docs/boxes/home/`, `docs/boxes/misc/`). Keep these in sync when adding, removing or repurposing
+a machine or service.
+
+## Secrets
+
+age-encrypted secrets in `secrets/`, managed with **ragenix**. Each module declares
+`my.secrets.files.<name>` and `my.secrets.key` (the host pubkey to encrypt for). `secrets.nix`
+(the ragenix rules file) is generated by reading every system's declared secrets and computing the
+recipient key list (always including `.keys/dev.pub`). Edit secrets with the `ragenix` devshell
+command, which supplies `.keys/dev.key` as the identity. The `.keys/` directory (dev + deploy
+private keys) is required for editing secrets, deploying, and running dev VMs.
+
+## Conventions
+
+- Format with `nixpkgs-fmt` (`fmt`). 2-space indent, `inherit (...)` blocks at the top of `let`.
+- 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.*`.
+- New host → box file under `nixos/boxes/` + entry in the `configs` list in `flake.nix`.
+- Custom packages live in `pkgs/` and are registered in `pkgs/default.nix`; the overlay is exposed
+  as `overlays.default`.
+- In prose and commit messages, quote code-like identifiers (commands, options, paths, package and
+  attribute names) in backticks.

README.md

@@ -0,0 +1,80 @@
+# nixfiles
+
+Personal Nix flake managing every machine I run: hosted servers, home
+infrastructure, routers, a remote site, VPSes and personal workstations. It is
+built around a **custom module system** layered on top of NixOS and
+home-manager rather than the stock per-host `nixosConfigurations` pattern.
+
+For day-to-day commands and a deeper explanation of the module system,
+conventions and secrets, see [`AGENTS.md`](AGENTS.md). This README is the map of
+**what is actually deployed**; the per-machine details live under [`docs/boxes/`](docs/boxes).
+
+> **Note:** This documentation (the README and everything under `docs/`) is a
+> work in progress and was **agent-generated** from the repository. It may be
+> incomplete or out of date — treat the Nix configuration as the source of truth.
+
+## The boxes at a glance
+
+Machines are grouped by deployment/location. Each group has its own directory
+under `docs/boxes/` with a `README.md` overview and one file per machine.
+
+| Group | What it is | Docs |
+| --- | --- | --- |
+| **colony** | Hosted dedicated server in Amsterdam (`ams1`). A VM host running the public-facing infrastructure: routing, web, git, media, object storage, chat, game servers. | [`docs/boxes/colony/`](docs/boxes/colony) |
+| **home** | Home network: a VM host (`palace`), the home routers, storage, Home Assistant, and personal desktops. | [`docs/boxes/home/`](docs/boxes/home) |
+| **misc** | Everything else: edge VPSes (`britway`, `britnet`), the remote `kelder` site, the `tower` workstation, and the installer image. | [`docs/boxes/misc/`](docs/boxes/misc) |
+
+## The "big machine" pattern
+
+The larger sites (`colony`, `home`) all follow the same shape:
+
+```
+physical host (VM host)
+├── VM ── thing impractical to containerise (router, storage, podman host, …)
+├── VM ── container host ──┬── NixOS container ── application
+│                          ├── NixOS container ──┬── application
+│                          │                     ├── application
+│                          │                     └── application
+│                          └── …
+└── VM ── …
+```
+
+- A **physical host** (`colony`, `palace`) does little itself beyond running
+  **VMs** via the custom `my.vms` module (QEMU + systemd units, LVM-backed
+  disks).
+- **VMs** exist for things that are impractical to put in a container — kernel
+  features, separate networking, podman/OCI workloads, foreign OSes.
+- One VM is usually a **container host** (`shill` on colony, `sfh` on home; and
+  `kelder` directly). It runs **NixOS containers** via the custom `my.containers`
+  module (systemd-nspawn based, each with its own address on a bridge).
+- **Most applications live in those NixOS containers.** A container isn't limited
+  to a single application — it commonly hosts a **group of related applications**
+  that belong together (e.g. `jackflix` runs Jellyfin, the *arr stack,
+  Transmission, PhotoPrism and copyparty; `object` runs MinIO, Harmonia, HedgeDoc
+  and wastebin). Each container is a first-class entry in `docs/boxes/`.
+
+Networking between everything is largely defined by per-system `assignments`
+(IPs/prefixes) plus an L2 VXLAN mesh (`my.vpns.l2`, AS211024) that ties the edge
+routers together. See [`AGENTS.md`](AGENTS.md) for the mechanics.
+
+## Repo layout
+
+```
+README.md           <- you are here
+nixos/
+  boxes/            per-machine configuration ("boxes")
+    colony/         colony host + its VMs (vms/) + shill's containers
+    home/           palace host + its VMs, plus stream, castle
+    britway/        britnet.nix, kelder/, tower/, installer.nix …
+  modules/          shared NixOS modules (my.* options); registered in _list.nix
+home-manager/       home-manager modules + configs
+lib/                lib.my helpers, constants (lib.my.c), net/dns helpers
+pkgs/               custom packages (overlays.default)
+secrets/            age-encrypted secrets (ragenix)
+devshell/           devshell commands (build/deploy/check/ssh helpers)
+docs/boxes/         per-machine documentation (colony/, home/, misc/)
+```
+
+A machine is wired into the flake by adding its box file to the `configs` list
+in `flake.nix`. See [`AGENTS.md`](AGENTS.md#architecture) for how `evalModules`
+turns these into `nixosConfigurations`, `homeConfigurations` and `deploy` nodes.

devshell/commands.nix

@@ -48,6 +48,25 @@ in
       help = "Print the ed25519 pubkey for a host";
       command = "${pkgs.openssh}/bin/ssh-keyscan -t ed25519 \"$1\" 2> /dev/null | awk '{ print $2 \" \" $3 }'";
     }
+    {
+      name = "ssh-machine";
+      category = "utilities";
+      help = "SSH to a machine by NixOS system or home-manager config name";
+      command = ''
+        name="$1"
+        shift
+        # Run from the project root so deploy's relative identity path (.keys/deploy.key) resolves
+        cd "$PRJ_ROOT"
+        # deploy-rs node names are the system/home name, with `@` mangled to `-at-`
+        node="''${name//@/-at-}"
+        # Single eval: resolve `user@host` plus merged (global + node) deploy-rs ssh options
+        info="$(nix eval --raw .#deploy --apply 'd: let n = d.nodes."'"$node"'"; in "''${n.sshUser}@''${n.hostname} ''${builtins.concatStringsSep " " (d.sshOpts ++ n.sshOpts)}"')"
+        target="''${info%% *}"
+        opts="''${info#* }"
+        # shellcheck disable=SC2086
+        exec ${pkgs.openssh}/bin/ssh $opts "$target" "$@"
+      '';
+    }
     {
       name = "json2nix";
       category = "utilities";
@@ -73,6 +92,12 @@ in
       help = "Build NixOS configuration";
       command = ''nix build "''${@:2}" ".#nixosConfigurations.\"$1\".config.system.build.toplevel"'';
     }
+    {
+      name = "check-system";
+      category = "utilities";
+      help = "Evaluate NixOS configuration (check validity without building)";
+      command = ''nix eval "''${@:2}" ".#nixosConfigurations.\"$1\".config.system.build.toplevel.drvPath"'';
+    }
     {
       name = "build-n-switch";
       category = "tasks";

docs/boxes/colony/README.md

@@ -0,0 +1,68 @@
+# colony
+
+The hosted dedicated server in Amsterdam (`ams1`). This is the public-facing
+half of the boxes: almost everything reachable from the internet lives here.
+
+- **Internal domain:** `ams1.int.nul.ie`
+- **Public domain:** `nul.ie` (public services are published as `*.nul.ie`)
+- **Source:** [`nixos/boxes/colony/`](../../../nixos/boxes/colony)
+
+## Shape
+
+`colony` is the physical VM host. It runs the VMs below; one of them (`shill`)
+is itself a NixOS container host where most applications run.
+
+```
+colony (physical VM host)
+├── estuary ── edge router / firewall / DNS / BGP
+├── shill ──── NixOS container host ──┬── middleman    (reverse proxy, ACME, SSO)
+│                                     ├── colony-psql  (shared PostgreSQL)
+│                                     ├── vaultwarden  (password manager)
+│                                     ├── chatterbox   (Matrix + bridges)
+│                                     ├── toot         (Mastodon)
+│                                     ├── jackflix     (media stack)
+│                                     ├── object       (MinIO, Nix cache, …)
+│                                     ├── waffletail   (Tailscale subnet router)
+│                                     ├── qclk         (clock service)
+│                                     └── gam          (game servers)
+├── whale2 ─── podman/OCI host (game servers)
+├── git ────── Gitea + Actions runner
+├── mail ───── Debian VM running Mailcow (not NixOS — configured out of repo)
+└── darts ──── third-party/customer VM (opaque to this repo)
+```
+
+## Machines
+
+| Machine | Role | Docs |
+| --- | --- | --- |
+| `colony` | Physical VM host (AMD, LVM-thin, borgthin backups → rsync.net) | [colony.md](colony.md) |
+| `estuary` | Edge router: WAN, firewall/NAT, DNS, BGP, IXP peering, WireGuard | [estuary.md](estuary.md) |
+| `shill` | NixOS container host (see containers below) | [shill.md](shill.md) |
+| `whale2` | podman/OCI host for game servers | [whale2.md](whale2.md) |
+| `git` | Gitea + Gitea Actions runner | [git.md](git.md) |
+
+### shill containers
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `middleman` | Front-end nginx reverse proxy, ACME certs, nginx-sso, librespeed | [middleman.md](middleman.md) |
+| `colony-psql` | Shared PostgreSQL (14) for colony services | [colony-psql.md](colony-psql.md) |
+| `vaultwarden` | Vaultwarden (Bitwarden-compatible password manager) | [vaultwarden.md](vaultwarden.md) |
+| `chatterbox` | Matrix homeserver + bridges (heisenbridge, mautrix-*) | [chatterbox.md](chatterbox.md) |
+| `toot` | Bluesky PDS (Mastodon disabled) | [toot.md](toot.md) |
+| `jackflix` | Media: Jellyfin, *arr stack, Transmission, PhotoPrism, copyparty | [jackflix.md](jackflix.md) |
+| `object` | MinIO (S3), Harmonia (Nix cache), HedgeDoc, wastebin | [object.md](object.md) |
+| `waffletail` | Tailscale subnet router (advertises colony prefixes into the tailnet) | [waffletail.md](waffletail.md) |
+| `qclk` | `qclk` clock service (reachable over WireGuard) | [qclk.md](qclk.md) |
+| `gam` | Game servers (Terraria, …) | [gam.md](gam.md) |
+
+## Non-NixOS VMs
+
+These run on `colony` but are **not** managed by this repo (no NixOS config). The
+QEMU instances are still declared in `colony`'s `my.vms.instances`, and colony's
+networking routes/firewalls traffic to them:
+
+- **`mail`** — a Debian VM running [Mailcow](https://mailcow.email/) (`mail.nul.ie`).
+  ACME certs are pushed to it from `middleman` (see [middleman.md](middleman.md)).
+- **`darts`** — a third-party/customer VM; opaque to this repo, given a routed
+  prefix and otherwise left alone.

docs/boxes/colony/chatterbox.md

@@ -0,0 +1,19 @@
+# chatterbox
+
+The Matrix homeserver (`nul.ie`) and its chat-network bridges.
+
+- **Source:** [`shill/containers/chatterbox.nix`](../../../nixos/boxes/colony/vms/shill/containers/chatterbox.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **Matrix homeserver** for `server_name = "nul.ie"`.
+- **Bridges** to other chat networks:
+  - `heisenbridge` (IRC),
+  - `mautrix-whatsapp` (WhatsApp),
+  - `mautrix-meta` / `mautrix-messenger` (Facebook Messenger / Instagram).
+- Fronted by `middleman` (federation on `:8448`).
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `chatterbox-ctr`).

docs/boxes/colony/colony-psql.md

@@ -0,0 +1,18 @@
+# colony-psql
+
+The shared PostgreSQL instance for colony. Several other containers
+(`middleman`, `chatterbox`, `toot`, `git`, …) connect here rather than each
+running their own database.
+
+- **Source:** [`shill/containers/colony-psql.nix`](../../../nixos/boxes/colony/vms/shill/containers/colony-psql.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **PostgreSQL 14** serving the other colony services over the `ctrs` network.
+  Consumers wait for it to be ready via the `systemdAwaitPostgres` helper.
+- netdata for monitoring.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `colony-psql-ctr`).

docs/boxes/colony/colony.md

@@ -0,0 +1,39 @@
+# colony (host)
+
+The physical dedicated server in Amsterdam and the VM host for everything in
+this group.
+
+- **Source:** [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix)
+  (VM instances in [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix))
+- **nixpkgs:** `mine-stable`
+
+## Role
+
+Bare-metal AMD host. It does little application work itself — its job is to run
+the VMs and provide them with storage, networking and backups.
+
+- **Virtualisation:** QEMU/KVM (`kvm-amd`, IOMMU on) via the `my.vms` module. VM
+  disks are LVM logical volumes (`vm-<name>-<disk>`) in the `main` volume group;
+  `estuary` additionally gets a WAN NIC by PCI passthrough.
+- **Storage:** LVM-thin (`services.lvm.boot.thin`), `/persist` for state,
+  `/mnt/backup` for the local borg repo. `smartd` + `rasdaemon` for health.
+- **Backups:** `my.borgthin` snapshots the persist/data LVs of the host and its
+  VMs into `/mnt/backup/main`, which is then `rsync`'d (along with LVM metadata)
+  to rsync.net (`zh2855.rsync.net`).
+- **Monitoring:** netdata (with freeipmi), smartd.
+
+## Networking
+
+- Two bridges: `base` (the colony "base" network, shared with `estuary`) and
+  `vms` (the VM network). Dummy interfaces keep the bridges up so dependent VMs
+  can start.
+- Default gateway / edge is `estuary`; `colony` itself holds the `routing` and
+  `internal` (a.k.a. `vm`) assignments and routes container/OCI/Tailscale
+  prefixes to `shill` and `whale2`.
+- `my.firewall` trusts the `vms` interface and forwards customer prefixes
+  (`vm-mail`, `vm-darts`) through.
+
+## VMs hosted here
+
+`estuary`, `shill`, `whale2`, `git` (all NixOS, documented in this directory),
+plus the non-NixOS `mail` and `darts` (see [README](README.md#non-nixos-vms)).

docs/boxes/colony/estuary.md

@@ -0,0 +1,41 @@
+# estuary
+
+The colony edge router and firewall — the machine that holds colony's public
+IPs and connects everything else to the internet.
+
+- **Source:** [`nixos/boxes/colony/vms/estuary/`](../../../nixos/boxes/colony/vms/estuary)
+  (`default.nix`, `bgp.nix`, `dns.nix`, `bandwidth.nix`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony` (gets the WAN NIC by PCI passthrough)
+
+## Role
+
+- **Edge routing / firewall / NAT:** owns the colony public IPv4/IPv6
+  (`94.142.241.x` / `2a02:898:0:20::`), does NAT and port-forwarding for the
+  internal services (`my.firewall.nat.forwardPorts` driven by
+  `firewallForwards`). Forwards HTTP/S to `middleman`, git to `git`, game ports
+  to the OCI game servers on `whale2`, etc.
+- **BGP:** runs BIRD2 ([`bgp.nix`](../../../nixos/boxes/colony/vms/estuary/bgp.nix))
+  announcing AS211024, over VLANs on the WAN link:
+  - peers at the IXPs **Frys-IX**, **NL-ix** and **FogIXP**;
+  - plus **iFog transit** (`ifog-transit`) — an upstream transit provider from
+    iFog, **not** an IXP.
+- **DNS:** authoritative/recursive DNS ([`dns.nix`](../../../nixos/boxes/colony/vms/estuary/dns.nix)),
+  redirected to port 5353 locally.
+- **VPNs:**
+  - Part of the AS211024 **L2 VXLAN mesh** (`my.vpns.l2`) with `river`, `stream`
+    and `britway`.
+  - WireGuard endpoints for the remote `kelder` site, `hillcrest`, and
+    `john-valorant`.
+- **Misc:** iperf3 server. (A bandwidth-accounting script,
+  [`bandwidth.py`](../../../nixos/boxes/colony/vms/estuary/bandwidth.py), exists but
+  is **legacy and not currently used**.)
+
+## Networking
+
+- `wan` — the passed-through igb NIC (9000 MTU), carrying the upstream uplink and
+  tagged IXP VLANs (`ifog` 409 → `frys-ix`/`nl-ix`/`fogixp`/`ifog-transit`).
+- `base` — colony base network; sends RAs and provides DNS to the base prefix,
+  routes the VM/container/OCI/Tailscale prefixes back to `colony`.
+- `as211024` — the L2 mesh interface.
+- Assignments: `internal` (public, alt name `fw`), `base`, `as211024`.

docs/boxes/colony/gam.md

@@ -0,0 +1,17 @@
+# gam
+
+A game-server container (the lightweight counterpart to the OCI game servers on
+`whale2`).
+
+- **Source:** [`shill/containers/gam.nix`](../../../nixos/boxes/colony/vms/shill/containers/gam.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Hosts game servers run directly as NixOS services — currently **Terraria**
+  (config/world from secrets). Exposed to the internet via `estuary`'s port
+  forwards (`:7777`).
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `gam-ctr`).

docs/boxes/colony/git.md

@@ -0,0 +1,38 @@
+# git
+
+The Gitea VM — source hosting and CI for the boxes (`git.nul.ie`).
+
+- **Source:** [`nixos/boxes/colony/vms/git/`](../../../nixos/boxes/colony/vms/git)
+  (`default.nix`, `gitea.nix`, `gitea-actions.nix`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony`
+
+## Role
+
+- **Gitea** ([`gitea.nix`](../../../nixos/boxes/colony/vms/git/gitea.nix)) — the Git
+  forge (`git.nul.ie`). PostgreSQL-backed (the shared `colony-psql`), LFS
+  enabled, with object storage backed by MinIO on `object` (a MinIO secret is
+  spliced into `app.ini` at startup).
+- **Gitea Actions runner**
+  ([`gitea-actions.nix`](../../../nixos/boxes/colony/vms/git/gitea-actions.nix)) — a
+  Docker-mode runner (`main-docker`) using podman. Labels provide Debian/node-24
+  (Trixie) and Ubuntu 26.04 images; runner config comes from the upstream
+  module's `settings` option. The Actions cache lives on a dedicated disk
+  (`/var/cache/gitea-runner`). Runs as a fixed `gitea-runner` user (not
+  `DynamicUser`) so it can read its token.
+- **nginx** — terminates TLS for `git.nul.ie` and proxies to Gitea on `:3000`.
+  ACME certs for `nul.ie` / `*.nul.ie` via the Cloudflare DNS challenge.
+- **podman** — also hosts the OCI registry/build images; `/var/lib/containers`
+  is an XFS data disk.
+
+## Networking
+
+- `vms` interface with `routing` / `internal` assignments.
+- HTTP/HTTPS forwarded in from `estuary`; podman default subnet `10.88.0.0/16` is
+  allowed to forward.
+
+## CI
+
+This runner is what executes the repo's own `.gitea/workflows/ci.yaml`, building
+each `.#ci.x86_64-linux` attribute and pushing to the Harmonia binary cache. See
+[`AGENTS.md`](../../../AGENTS.md#commands).

docs/boxes/colony/jackflix.md

@@ -0,0 +1,25 @@
+# jackflix
+
+The media stack — acquisition, library and streaming.
+
+- **Source:** [`shill/containers/jackflix/`](../../../nixos/boxes/colony/vms/shill/containers/jackflix)
+  (`default.nix`, `networking.nix`)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **Streaming:** Jellyfin.
+- **Acquisition (*arr stack):** Transmission, Jackett, FlareSolverr, Radarr,
+  Sonarr, and Jellyseerr (`seerr`) for requests.
+- **Photos:** PhotoPrism (`photos.nul.ie`).
+- **File sharing:** copyparty (`:3923`) serving public + private media volumes.
+- Media lives on the shared `/mnt/media` volume (bind-mounted read-write from
+  `shill`). Downloaders bind to a VPN interface
+  ([`networking.nix`](../../../nixos/boxes/colony/vms/shill/containers/jackflix/networking.nix)),
+  so torrent traffic only flows while `systemd-networkd-wait-online@vpn` is up.
+- A shared `media` group (gid 2000) gives the apps coordinated access.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `jackflix-ctr`), plus its
+  own VPN interface for the download clients.

docs/boxes/colony/middleman.md

@@ -0,0 +1,63 @@
+# middleman
+
+The front-end reverse proxy for all public colony web services — the single
+ingress that `estuary` forwards HTTP/HTTPS to.
+
+- **Source:** [`shill/containers/middleman/`](../../../nixos/boxes/colony/vms/shill/containers/middleman)
+  (`default.nix`, `vhosts.nix`)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **nginx** reverse proxy ([`vhosts.nix`](../../../nixos/boxes/colony/vms/shill/containers/middleman/vhosts.nix)
+  holds the per-service vhosts) with VTS stats, fancyindex, brotli, caching, and
+  a dynamic resolver pointed at `estuary` so upstreams can be re-resolved at
+  runtime. It is the single public ingress for almost every web service — colony,
+  home, and beyond.
+- **ACME** — issues the wildcard certificates that **its own** vhosts are served
+  with (it is not a shared CA for the other boxes; `git`, `britway`, `kelder-spoder`, etc. each
+  run their own ACME):
+  - `nul.ie` / `*.nul.ie` (+ `*.s3.nul.ie`) via the Cloudflare DNS challenge,
+  - the internal `ams1.int.nul.ie` / `*` via an `exec` challenge that calls
+    `estuary`'s pdns over SSH.
+  - As a one-off consumer, it then pushes the public cert to the `mail` (Mailcow)
+    VM via `scp` + a remote `mailcow-ssl-reload`.
+- **nginx-sso** — single-sign-on (`sso.nul.ie`) with Google OAuth and a simple
+  username/password provider; protects the SSO-gated vhosts below.
+- **librespeed** — speed-test frontend + backend (`librespeed.${domain}` /
+  `speed.nul.ie`).
+
+## Published vhosts
+
+All under `*.nul.ie` with the wildcard cert unless noted. Upstreams are addressed
+by their internal container/VM hostnames. "SSO" = gated behind nginx-sso.
+
+| Host(s) | Upstream | Notes |
+| --- | --- | --- |
+| `nul.ie` (default `_`) | static | landing page (CV, SSH pubkey) + Matrix/atproto `.well-known` |
+| `sso.nul.ie` | nginx-sso | SSO endpoint |
+| `pass.nul.ie` | `vaultwarden` | password manager |
+| `matrix.nul.ie` (+`:8448`) | `chatterbox` | Matrix client + federation |
+| `element.nul.ie` | element-web | Matrix web client |
+| `toot.nul.ie` | `toot` :80 | Mastodon (currently disabled — see [toot.md](toot.md)) |
+| `pds.nul.ie` | `toot` :3000 | Bluesky PDS |
+| `jackflix.nul.ie` | `jackflix` Jellyfin | streaming |
+| `torrents` / `jackett` / `radarr` / `sonarr` `.nul.ie` | `jackflix` | *arr stack (**SSO**) |
+| `gib.nul.ie` | `jackflix` Jellyseerr | requests |
+| `photos.nul.ie` | `jackflix` PhotoPrism | |
+| `stuff` / `public` / `p.nul.ie` | `jackflix` copyparty + `/mnt/media` | file sharing / index |
+| `share.nul.ie` | `object` :9090 | |
+| `minio` / `s3` / `*.s3.nul.ie` | `object` MinIO | S3 + console (Docker manifest MIME hack) |
+| `nix-cache.nul.ie` | `object` Harmonia | Nix binary cache (immutable cache headers) |
+| `md.nul.ie` / `pb.nul.ie` | `object` | HedgeDoc / wastebin |
+| `mc-map` / `mc-rail` / `mc-map-kink` `.nul.ie` | `whale2` OCI | Minecraft maps |
+| `netdata-colony.nul.ie` | many hosts :19999 | netdata fan-out (**SSO**) |
+| `pront.nul.ie` | `stream-hi` (home) | print/webcam (**SSO**) |
+| `hass.nul.ie` | `hass` (home) | Home Assistant |
+| `hass-john.nul.ie` | `john-valorant-tun` | remote HASS over WireGuard tunnel |
+
+## Networking
+
+- `internal` assignment on the `ctrs` network; bind-mounts `/mnt/media` for
+  serving static/media content.
+- nginx waits for `colony-psql` before starting (DNS bootstrap hack).

docs/boxes/colony/object.md

@@ -0,0 +1,24 @@
+# object
+
+Object storage and Nix binary cache, plus a couple of small self-hosted web
+apps.
+
+- **Source:** [`shill/containers/object.nix`](../../../nixos/boxes/colony/vms/shill/containers/object.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **MinIO** — S3-compatible object storage (`s3.nul.ie` / `*.s3.nul.ie`). Backs
+  several other services (Gitea LFS/artifacts, social-media uploads, …). Stored on the
+  `/mnt/minio` volume (XFS, bind-mounted from `shill`).
+- **Harmonia** — serves the Nix binary cache for all the boxes (`nix-cache.nul.ie`), backed
+  by the `/mnt/nix-cache` volume.
+- **atticd** — an alternative Nix cache (stores into MinIO/S3). **Currently
+  disabled** — present in the config but not running.
+- **HedgeDoc** — collaborative markdown notes.
+- **wastebin** — pastebin.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `object-ctr`).
+- `/mnt/minio` and `/mnt/nix-cache` bind-mounted read-write from `shill`.

docs/boxes/colony/qclk.md

@@ -0,0 +1,22 @@
+# qclk
+
+The `qclk` service container.
+
+- **Source:** [`shill/containers/qclk/`](../../../nixos/boxes/colony/vms/shill/containers/qclk)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Runs the custom `qclk` service, exposing an API that is reached over a
+  dedicated WireGuard **`management`** network. Managed devices are configured as
+  WireGuard peers (each gets an address in the `qclk` prefix), and AS211024
+  trusted hosts are allowed to reach the API.
+- `shill` routes the `qclk` prefix to this container.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `qclk-ctr`), plus the
+  `management` WireGuard interface carrying the `qclk` prefix.
+
+> Check `qclk/default.nix` for the current peer list and exactly what the service
+> does — this entry intentionally stays high-level.

docs/boxes/colony/shill.md

@@ -0,0 +1,48 @@
+# shill
+
+The colony **NixOS container host**. Most colony applications run as
+systemd-nspawn containers on `shill`.
+
+- **Source:** [`nixos/boxes/colony/vms/shill/`](../../../nixos/boxes/colony/vms/shill)
+  (`default.nix`, `containers-ext.nix`, `hercules.nix`, `containers/`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony` (large: 12 cores, 40 GiB RAM)
+
+## Role
+
+- Runs the colony NixOS containers via `my.containers.instances`, each attached
+  to the `ctrs` bridge with its own address.
+- Provides shared data volumes to those containers via bind mounts from
+  LVM-backed disks: `/mnt/media` (→ `middleman`, `jackflix`), `/mnt/minio` and
+  `/mnt/nix-cache` (→ `object`).
+- Acts as the router between the `vms` network and the `ctrs` container network
+  (sends RAs on `ctrs`, routes Tailscale prefixes via `waffletail` and the
+  `qclk` prefix via `qclk`). Includes an nftables `ct mark` hack to make
+  internal DNAT return paths work.
+- Tuned sysctls for high connection counts / torrent traffic; netdata.
+
+## Containers
+
+Defined in [`shill/containers/`](../../../nixos/boxes/colony/vms/shill/containers)
+and wired up in `shill`'s `my.containers.instances`:
+
+| Container | Role |
+| --- | --- |
+| [`middleman`](middleman.md) | Front-end nginx reverse proxy, ACME, nginx-sso, librespeed |
+| [`colony-psql`](colony-psql.md) | Shared PostgreSQL |
+| [`vaultwarden`](vaultwarden.md) | Password manager |
+| [`chatterbox`](chatterbox.md) | Matrix homeserver + bridges |
+| [`toot`](toot.md) | Bluesky PDS (Mastodon disabled) |
+| [`jackflix`](jackflix.md) | Media stack |
+| [`object`](object.md) | MinIO / Harmonia / HedgeDoc / wastebin |
+| [`waffletail`](waffletail.md) | Tailscale subnet router |
+| [`qclk`](qclk.md) | Clock service |
+| [`gam`](gam.md) | Game servers |
+
+## Notes
+
+- Container systems set `my.deploy.enable = false` (they are deployed as part of
+  `shill`'s container profiles, not as standalone deploy nodes) and render via
+  `my.asContainer`.
+- `hercules.nix` configures Hercules CI agent bits;
+  `containers-ext.nix` holds extra per-container host wiring.

docs/boxes/colony/toot.md

@@ -0,0 +1,19 @@
+# toot
+
+A federated-social container. Despite the name (Mastodon = "toots"), it currently
+hosts a **Bluesky PDS**; the Mastodon instance is disabled.
+
+- **Source:** [`shill/containers/toot.nix`](../../../nixos/boxes/colony/vms/shill/containers/toot.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **Bluesky PDS** (Personal Data Server) — the active service, published as
+  `pds.nul.ie` (proxied by `middleman` to `:3000`).
+- **Mastodon** — **currently disabled**. The config is still present and
+  `toot.nul.ie` still maps to `:80`, but the instance is not running. (It was
+  backed by the shared `colony-psql` and MinIO/S3 on `object`.)
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `toot-ctr`).

docs/boxes/colony/vaultwarden.md

@@ -0,0 +1,15 @@
+# vaultwarden
+
+[Vaultwarden](https://github.com/dani-garcia/vaultwarden), a Bitwarden-compatible
+password manager.
+
+- **Source:** [`shill/containers/vaultwarden.nix`](../../../nixos/boxes/colony/vms/shill/containers/vaultwarden.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Runs Vaultwarden, fronted by `middleman` and published under `nul.ie`.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `vaultwarden-ctr`).

docs/boxes/colony/waffletail.md

@@ -0,0 +1,19 @@
+# waffletail
+
+The colony Tailscale node / subnet router.
+
+- **Source:** [`shill/containers/waffletail.nix`](../../../nixos/boxes/colony/vms/shill/containers/waffletail.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Joins the Tailscale tailnet (auth key from secrets) and **advertises the colony
+  prefixes** into it, acting as the subnet router so tailnet clients can reach
+  colony services and vice-versa.
+- nftables rules SNAT/forward between `host0` and `tailscale0` for the colony
+  v4/v6 ranges. `shill` routes the Tailscale prefixes here.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `waffletail-ctr`); owns
+  the `tailscale0` interface.

docs/boxes/colony/whale2.md

@@ -0,0 +1,27 @@
+# whale2
+
+A podman/OCI host on colony dedicated to game servers (kept off `shill` so the
+container churn and resource use stay isolated).
+
+- **Source:** [`nixos/boxes/colony/vms/whale2/`](../../../nixos/boxes/colony/vms/whale2)
+  (`default.nix`, `valheim.nix`, `minecraft/`, `enshrouded.nix`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony`
+
+## Role
+
+- Runs OCI containers via **podman** (`virtualisation.oci-containers`, netavark
+  backend) on a dedicated `colony` bridge network (`oci`) with both IPv4 and
+  IPv6, so each game server gets its own routable address.
+- Game servers configured in-repo: **Valheim**, **Minecraft** (several worlds —
+  see `extraAssignments`: `simpcraft`, `simpcraft-staging`, `kevcraft`,
+  `kinkcraft`, `graeme`), and **Enshrouded** (currently commented out).
+- `/var/lib/containers` is an XFS data disk (project quotas).
+
+## Networking
+
+- `vms` interface with `routing` / `internal` (alt name `oci`) assignments.
+- An `oci` bridge carrying the `prefixes.oci` v4/v6 ranges; per-game addresses
+  are handed out via `extraAssignments` (`valheim-oci`, `simpcraft-oci`, …) and
+  exposed to the internet through `estuary`'s port forwards.
+- Firewall trusts the `oci` interface and forwards `vms → oci`.

docs/boxes/home/README.md

@@ -0,0 +1,44 @@
+# home
+
+The home network. A VM host (`palace`), a redundant pair of routers, a storage
+server, Home Assistant, and personal desktops.
+
+- **Domain:** `h.nul.ie`
+- **Source:** [`nixos/boxes/home/`](../../../nixos/boxes/home)
+
+## Shape
+
+```
+palace (physical VM host)
+├── river ──── home router (HA pair with stream)
+├── cellar ── NVMe-oF storage server (SPDK)
+└── sfh ───── NixOS container host ──┬── hass   (Home Assistant)
+                                     └── unifi  (UniFi controller — defined, currently disabled)
+
+stream ── standalone home router (HA pair with river)
+castle ── desktop workstation (boots its disks over NVMe-oF from cellar)
+```
+
+The two routers `river` (a VM on `palace`) and `stream` (standalone hardware)
+share the [`routing-common`](../../../nixos/boxes/home/routing-common) config and
+form a **keepalived/VRRP high-availability pair**: DHCP (kea), router
+advertisements (radvd), DNS with blocklists, NAT, and the AS211024 L2 mesh link
+back to colony.
+
+## Machines
+
+| Machine | Role | Docs |
+| --- | --- | --- |
+| `palace` | Physical VM host | [palace.md](palace.md) |
+| `river` | Home router (VM; VRRP pair with `stream`) | [river.md](river.md) |
+| `cellar` | NVMe-oF storage server (SPDK) | [cellar.md](cellar.md) |
+| `sfh` | NixOS container host | [sfh.md](sfh.md) |
+| `stream` | Home router (standalone hardware; VRRP pair with `river`) | [stream.md](stream.md) |
+| `castle` | Desktop workstation | [castle.md](castle.md) |
+
+### sfh containers
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `hass` | Home Assistant | [hass.md](hass.md) |
+| `unifi` | UniFi network controller (defined, **currently not imported**) | [unifi.md](unifi.md) |

docs/boxes/home/castle.md

@@ -0,0 +1,19 @@
+# castle
+
+A desktop workstation.
+
+- **Source:** [`nixos/boxes/home/castle/default.nix`](../../../nixos/boxes/home/castle/default.nix)
+
+## Role
+
+- AMD desktop running the GUI environment (`my.gui.enable`, Sway / Wayland via
+  home-manager).
+- **Diskless-style boot:** its `/nix`, `/persist` and `/home` are NVMe-oF volumes
+  served by [`cellar`](cellar.md) (`/dev/nvmeof/{nix,persist,home}`). The
+  networking is careful not to drop the IP used for the NVMe-oF connection.
+- Uses the `my.nvme` module for the NVMe-oF client setup.
+
+## Networking
+
+- Sits on the home network; depends on the high-speed link to `cellar` for its
+  root storage.

docs/boxes/home/cellar.md

@@ -0,0 +1,39 @@
+# cellar
+
+The home storage server. Exports fast NVMe storage over the network so other
+machines (notably `castle`) can boot and run from it.
+
+- **Source:** [`nixos/boxes/home/palace/vms/cellar/`](../../../nixos/boxes/home/palace/vms/cellar)
+  (`default.nix`, `spdk.nix`)
+- **Host:** VM on `palace` (NVMe drives passed through)
+- **Deploy address:** `192.168.68.80`
+
+## Role
+
+- Runs **SPDK** ([`spdk.nix`](../../../nixos/boxes/home/palace/vms/cellar/spdk.nix)) as
+  a userspace storage target. The kernel `nvme` driver is blacklisted so SPDK can
+  drive the NVMe devices directly (attached by PCI BDF).
+- Builds a **RAID0** (`NVMeRaid`) across three NVMe drives, partitioned into three
+  namespaces, and exports each as an **NVMe-oF target over RDMA** (port 4420) on
+  the high-speed home network — one namespace per consumer:
+
+  | Namespace | NQN | Consumer |
+  | --- | --- | --- |
+  | `NVMeRaidp1` | `nqn.2016-06.io.spdk:river` | [`river`](river.md) |
+  | `NVMeRaidp2` | `nqn.2016-06.io.spdk:castle` | [`castle`](castle.md) |
+  | `NVMeRaidp3` | `nqn.2016-06.io.spdk:sfh` | [`sfh`](sfh.md) |
+
+  Each client is pinned by `hostnqn`, so `river`, `castle` and `sfh` all run their
+  storage off `cellar` over the network.
+
+## Networking
+
+- Exports on the high-speed home network (`lan-hi` / the `hi` assignment) over
+  RDMA; the SPDK target waits for that link to be online before starting.
+
+## Notes
+
+- The `ublk_*` calls in `my.spdk.debugCommands` are **only a debugging script** —
+  they let you create a local ublk block device to mount and inspect the RAID on
+  `cellar` itself. They are **not** how storage is exported to clients; that is the
+  `nvmf` config above.

docs/boxes/home/hass.md

@@ -0,0 +1,18 @@
+# hass
+
+[Home Assistant](https://www.home-assistant.io/) — home automation.
+
+- **Source:** [`sfh/containers/hass.nix`](../../../nixos/boxes/home/palace/vms/sfh/containers/hass.nix)
+- **Host:** NixOS container on `sfh`
+
+## Role
+
+- Runs Home Assistant plus supporting services in the container. The `hass-cli`
+  is wired up against the local server for convenience.
+- Integrations/automations are configured here (see commit history for things
+  like the "West Wood" integration).
+
+## Networking
+
+- `internal` assignment (alt name `hass-ctr`), plus a loopback assignment
+  (`hass-ctr-lo`) used internally.

docs/boxes/home/palace.md

@@ -0,0 +1,21 @@
+# palace (host)
+
+The physical VM host for the home network — the home equivalent of `colony`.
+
+- **Source:** [`nixos/boxes/home/palace/default.nix`](../../../nixos/boxes/home/palace/default.nix)
+  (VM instances in [`palace/vms/default.nix`](../../../nixos/boxes/home/palace/vms/default.nix))
+
+## Role
+
+- Bare-metal host whose job is to run the home VMs via the `my.vms` module:
+  `river` (router), `cellar` (storage), `sfh` (container host).
+- Provides the bridged networking those VMs sit on and passes through hardware
+  where needed (e.g. NVMe drives to `cellar`, NICs to `river`).
+
+## VMs hosted here
+
+| VM | Role | Docs |
+| --- | --- | --- |
+| `river` | Home router (VRRP pair with `stream`) | [river.md](river.md) |
+| `cellar` | NVMe-oF storage server | [cellar.md](cellar.md) |
+| `sfh` | NixOS container host (Home Assistant, …) | [sfh.md](sfh.md) |

docs/boxes/home/river.md

@@ -0,0 +1,25 @@
+# river
+
+One of the two home routers. `river` is a VM on `palace`; it forms a
+high-availability pair with the standalone `stream`.
+
+- **Source:** [`nixos/boxes/home/palace/vms/river.nix`](../../../nixos/boxes/home/palace/vms/river.nix),
+  built from [`routing-common`](../../../nixos/boxes/home/routing-common) (instance `0`)
+- **Host:** VM on `palace`
+- **Deploy address:** `192.168.68.1`
+
+## Role
+
+Everything in [`routing-common`](../../../nixos/boxes/home/routing-common):
+
+- **VRRP/keepalived** failover with `stream` (`keepalived.nix`) — one router is
+  master at a time, sharing virtual IPs.
+- **DHCP** via kea (`kea.nix`), **router advertisements** via radvd
+  (`radvd.nix`).
+- **DNS** (`dns.nix`) — local resolver with a blocklist
+  (`dns-blocklist.txt`) and a periodic update script.
+- **NAT / firewall** for the home LAN, with policy routing.
+- **AS211024 L2 mesh** link back to colony/`estuary` (and the other edge
+  routers), so home and colony networks interconnect.
+
+See [stream.md](stream.md) for the other half of the pair.

docs/boxes/home/sfh.md

@@ -0,0 +1,24 @@
+# sfh
+
+The home **NixOS container host** ("smart from home" / home services).
+
+- **Source:** [`nixos/boxes/home/palace/vms/sfh/`](../../../nixos/boxes/home/palace/vms/sfh)
+  (`default.nix`, `containers/`)
+- **Host:** VM on `palace`
+
+## Role
+
+- Runs the home NixOS containers via `my.containers.instances`, in the same way
+  `shill` does on colony.
+- Sits on the home network and connects to NVMe-oF storage (`cellar`) where
+  needed.
+
+## Containers
+
+Defined in [`sfh/containers/`](../../../nixos/boxes/home/palace/vms/sfh/containers)
+and imported from its `containers/default.nix`:
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `hass` | Home Assistant | [hass.md](hass.md) |
+| `unifi` | UniFi controller — **defined but currently commented out** of `containers/default.nix` | [unifi.md](unifi.md) |

docs/boxes/home/stream.md

@@ -0,0 +1,19 @@
+# stream
+
+One of the two home routers. `stream` is standalone hardware; it forms a
+high-availability pair with `river` (a VM on `palace`).
+
+- **Source:** [`nixos/boxes/home/stream.nix`](../../../nixos/boxes/home/stream.nix),
+  built from [`routing-common`](../../../nixos/boxes/home/routing-common) (instance `1`)
+- **Deploy address:** `192.168.68.2`
+
+## Role
+
+- Same [`routing-common`](../../../nixos/boxes/home/routing-common) role as
+  [`river`](river.md): keepalived/VRRP, kea DHCP, radvd, DNS + blocklist, NAT and
+  the AS211024 L2 mesh link to colony.
+- Additionally pulls in `mstpd` (`routing-common/mstpd.nix`) for spanning-tree on
+  its bridged ports — `stream` is the one wired into the physical switching, so
+  it manages the L2 topology.
+
+See [river.md](river.md) for the other half of the pair.

docs/boxes/home/unifi.md

@@ -0,0 +1,23 @@
+# unifi
+
+The UniFi network controller.
+
+- **Source:** [`sfh/containers/unifi.nix`](../../../nixos/boxes/home/palace/vms/sfh/containers/unifi.nix)
+- **Host:** NixOS container on `sfh`
+
+## Status
+
+> **Currently disabled.** The system is still defined (`nixos.systems.unifi`),
+> but its import is commented out in
+> [`sfh/containers/default.nix`](../../../nixos/boxes/home/palace/vms/sfh/containers/default.nix),
+> so it is not deployed as a container right now. Re-enable by uncommenting
+> `./unifi.nix` there.
+
+## Role
+
+- Runs the UniFi controller (`services.unifi`) to manage the home UniFi network
+  gear.
+
+## Networking
+
+- `internal` assignment (alt name `unifi-ctr`).

docs/boxes/misc/README.md

@@ -0,0 +1,21 @@
+# misc
+
+Everything that isn't part of the `colony` or `home` sites: the edge VPSes, the
+remote `kelder` site, a workstation, and the installer image.
+
+| Machine | What it is | Docs |
+| --- | --- | --- |
+| `britway` | Vultr VPS (London, `lon1`): Headscale, Tailscale exit node, BGP edge, nginx | [britway.md](britway.md) |
+| `britnet` | VPS (Birmingham, `bhx1`): Tailscale/WireGuard gateway | [britnet.md](britnet.md) |
+| `kelder` | Remote site host (`hentai.engineer`): NixOS container host | [kelder.md](kelder.md) |
+| `tower` | Framework Laptop 13 (12th-gen Intel) workstation | [tower.md](tower.md) |
+| `installer` | Custom NixOS installer image | [installer.md](installer.md) |
+
+## kelder containers
+
+`kelder` is itself a container host (like `shill`/`sfh`):
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `kelder-acquisition` | Media stack (Jellyfin + *arr + Transmission) | [kelder-acquisition.md](kelder-acquisition.md) |
+| `kelder-spoder` | nginx web host | [kelder-spoder.md](kelder-spoder.md) |

docs/boxes/misc/britnet.md

@@ -0,0 +1,21 @@
+# britnet
+
+A VPS in Birmingham (`bhx1`) acting as a Tailscale/WireGuard gateway node.
+
+- **Source:** [`nixos/boxes/britnet.nix`](../../../nixos/boxes/britnet.nix)
+- **Internal domain:** `bhx1.int.nul.ie`
+
+## Role
+
+- **Tailscale node** + **WireGuard** (`wg0`) gateway: provides a second egress /
+  entry point into the boxes' overlay networks.
+- nftables SNATs traffic arriving on `tailscale0` / `wg0` out of the provider
+  interface (`veth0`), using the `allhost` assignment addresses.
+
+## Networking
+
+- Provider uplink with gateways `77.74.199.1` (v4) / `2a12:ab46:5344::1` (v6).
+- `tailscale0` and `wg0` overlay interfaces; `allhost` assignment for SNAT.
+
+> `britnet` is a separate machine from [`britway`](britway.md) — different
+> provider/site, narrower role (gateway rather than control plane + BGP edge).

docs/boxes/misc/britway.md

@@ -0,0 +1,27 @@
+# britway
+
+A Vultr VPS in London (`lon1`) acting as a network edge node: the Tailscale
+control plane, an exit node, and a BGP speaker in the AS211024 mesh.
+
+- **Source:** [`nixos/boxes/britway/`](../../../nixos/boxes/britway)
+  (`default.nix`, `bgp.nix`, `nginx.nix`, `tailscale.nix`)
+- **Internal domain:** `lon1.int.nul.ie`
+
+## Role
+
+- **Headscale** ([`tailscale.nix`](../../../nixos/boxes/britway/tailscale.nix)) — the
+  self-hosted Tailscale control server (`hs.nul.ie`) the rest of the boxes log
+  into.
+- **Tailscale node** — advertises itself as an **exit node** and advertises the
+  tailnet routes, so tailnet clients can egress / reach internal prefixes via
+  britway.
+- **BGP** ([`bgp.nix`](../../../nixos/boxes/britway/bgp.nix)) — part of the AS211024
+  L2 VXLAN mesh (`my.vpns.l2`) alongside `estuary`, `river` and `stream`.
+- **nginx** ([`nginx.nix`](../../../nixos/boxes/britway/nginx.nix)) — reverse proxy /
+  web front-end with ACME certs.
+
+## Networking
+
+- `vultr` assignment on the provider interface; `as211024` on the mesh.
+- A `veth0`/`tailscale0` setup with SNAT so tailnet traffic egresses via the VPS
+  public IP.

docs/boxes/misc/installer.md

@@ -0,0 +1,19 @@
+# installer
+
+The custom NixOS installer image used to bootstrap new boxes.
+
+- **Source:** [`nixos/installer.nix`](../../../nixos/installer.nix)
+
+## Role
+
+- Defines `nixos.systems.installer`, a minimal system whose `my.buildAs.*`
+  outputs produce installable artifacts — primarily a bootable **ISO**
+  (`isoImage`), and the same base is reused for kexec/netboot trees.
+- Build it with the devshell commands (see [`AGENTS.md`](../../../AGENTS.md#commands)):
+  - `build-iso installer`
+  - `build-kexec installer` / `build-netboot installer`
+- A released ISO is what `colony`'s VM definitions reference as install media; the
+  `update-installer` devshell command tags a release to trigger a rebuild.
+
+This is a build target rather than a deployed machine — there is no running
+`installer` host.

docs/boxes/misc/kelder-acquisition.md

@@ -0,0 +1,20 @@
+# kelder-acquisition
+
+The media stack for the `kelder` site — a slimmer cousin of colony's
+[`jackflix`](../colony/jackflix.md).
+
+- **Source:** [`kelder/containers/acquisition/`](../../../nixos/boxes/kelder/containers/acquisition)
+  (`default.nix`, `networking.nix`)
+- **Host:** NixOS container on `kelder`
+
+## Role
+
+- **Jellyfin** for streaming (with hardware transcoding — the `jellyfin` user is
+  in the `render` group, `jellyfin-ffmpeg`).
+- **Acquisition:** Transmission, Jackett, Radarr, Sonarr.
+- Runs under the site's shared `kontent` user.
+
+## Networking
+
+- `internal` assignment (alt name `acquisition-ctr`) on the kelder container
+  network; download client networking in `networking.nix`.

docs/boxes/misc/kelder-spoder.md

@@ -0,0 +1,17 @@
+# kelder-spoder
+
+An nginx web host on the `kelder` site.
+
+- **Source:** [`kelder/containers/spoder/`](../../../nixos/boxes/kelder/containers/spoder)
+  (`default.nix`, `nginx.nix`)
+- **Host:** NixOS container on `kelder`
+
+## Role
+
+- Serves web content via **nginx** ([`nginx.nix`](../../../nixos/boxes/kelder/containers/spoder/nginx.nix)),
+  with ACME-managed certificates (nginx in the `acme` group, reloads on renewal).
+- Runs under the site's shared `kontent` user.
+
+## Networking
+
+- `internal` assignment (alt name `spoder-ctr`) on the kelder container network.

docs/boxes/misc/kelder.md

@@ -0,0 +1,24 @@
+# kelder
+
+A host at a remote site ("kelder" = cellar/basement), linked back to the rest of
+the other boxes over WireGuard. It is itself a **NixOS container host**.
+
+- **Source:** [`nixos/boxes/kelder/`](../../../nixos/boxes/kelder)
+  (`default.nix`, `boot.nix`, `containers/`, `plymouth/`)
+- **Domain:** `hentai.engineer`
+
+## Role
+
+- **Site uplink:** connects to colony's `estuary` over **WireGuard**
+  (`kelder` peer; see [estuary.md](../colony/estuary.md)), so the remote site is
+  reachable through the colony edge. A periodic `dns_update.py` keeps DNS current.
+- **Container host:** runs NixOS containers via `my.containers.instances`
+  (`acquisition`, `spoder`).
+- Custom boot/splash (`boot.nix`, Plymouth theme in `plymouth/`).
+
+## Containers
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `kelder-acquisition` | Media stack (Jellyfin + *arr + Transmission) | [kelder-acquisition.md](kelder-acquisition.md) |
+| `kelder-spoder` | nginx web host | [kelder-spoder.md](kelder-spoder.md) |

docs/boxes/misc/tower.md

@@ -0,0 +1,16 @@
+# tower
+
+A laptop workstation — a Framework Laptop 13 (12th-gen Intel).
+
+- **Source:** [`nixos/boxes/tower/default.nix`](../../../nixos/boxes/tower/default.nix)
+
+## Role
+
+- Framework Laptop 13 (12th-gen Intel) running the GUI environment
+  (`my.gui.enable`) with home-manager on the `mine` channel.
+- Joins the tailnet via the self-hosted Headscale on [`britway`](britway.md)
+  (`tailscale up --login-server=https://hs.nul.ie --accept-routes`).
+- Local virtualisation enabled (`kvm-intel`, IOMMU on).
+
+> Unlike [`castle`](../home/castle.md), `tower` lives outside the `home/` box
+> tree and boots from local disks rather than NVMe-oF.

flake.lock

@@ -8,7 +8,7 @@
           "ragenix",
           "nixpkgs"
         ],
-        "systems": "systems_6"
+        "systems": "systems_7"
       },
       "locked": {
         "lastModified": 1761656077,
@@ -184,7 +184,7 @@
     },
     "devshell-tools": {
       "inputs": {
-        "flake-utils": "flake-utils_9",
+        "flake-utils": "flake-utils_10",
         "nixpkgs": "nixpkgs_5"
       },
       "locked": {
@@ -278,6 +278,24 @@
       "inputs": {
         "systems": "systems_9"
       },
+      "locked": {
+        "lastModified": 1709126324,
+        "narHash": "sha256-q6EQdSeUZOG26WelxqkmR7kArjgWCdw5sfJVHPH/7j8=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "d465f4819400de7c8d874d50b982301f28a84605",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "flake-utils_11": {
+      "inputs": {
+        "systems": "systems_10"
+      },
       "locked": {
         "lastModified": 1705309234,
         "narHash": "sha256-uNRRNRKmJyCRC/8y1RqBkqWBLM034y4qN7EprSdmgyA=",
@@ -292,7 +310,7 @@
         "type": "github"
       }
     },
-    "flake-utils_11": {
+    "flake-utils_12": {
       "locked": {
         "lastModified": 1667395993,
         "narHash": "sha256-nuEHfE/LcWyuSWnS8t12N1wc105Qtau+/OdUAjtQ0rA=",
@@ -408,7 +426,7 @@
     },
     "flake-utils_8": {
       "inputs": {
-        "systems": "systems_7"
+        "systems": "systems_6"
       },
       "locked": {
         "lastModified": 1731533236,
@@ -429,11 +447,11 @@
         "systems": "systems_8"
       },
       "locked": {
-        "lastModified": 1709126324,
+        "lastModified": 1731533236,
-        "narHash": "sha256-q6EQdSeUZOG26WelxqkmR7kArjgWCdw5sfJVHPH/7j8=",
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
         "owner": "numtide",
         "repo": "flake-utils",
-        "rev": "d465f4819400de7c8d874d50b982301f28a84605",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
         "type": "github"
       },
       "original": {
@@ -465,6 +483,27 @@
         "type": "github"
       }
     },
+    "hass-west-wood": {
+      "inputs": {
+        "flake-utils": "flake-utils_7",
+        "nixpkgs": [
+          "nixpkgs-unstable"
+        ]
+      },
+      "locked": {
+        "lastModified": 1781402797,
+        "narHash": "sha256-pBdDca7xv1nuP0kj+gC5g5AcR/DV+9Zy3CS6uDOMdJ4=",
+        "owner": "devplayer0",
+        "repo": "hass-west-wood",
+        "rev": "3e6ef7a9084e4053c82dea20127a775e7bcf77a5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "devplayer0",
+        "repo": "hass-west-wood",
+        "type": "github"
+      }
+    },
     "home-manager": {
       "inputs": {
         "nixpkgs": [
@@ -581,7 +620,7 @@
     },
     "nixGL": {
       "inputs": {
-        "flake-utils": "flake-utils_7",
+        "flake-utils": "flake-utils_8",
         "nixpkgs": [
           "nixpkgs-unstable"
         ]
@@ -781,7 +820,7 @@
       "inputs": {
         "agenix": "agenix",
         "crane": "crane_2",
-        "flake-utils": "flake-utils_8",
+        "flake-utils": "flake-utils_9",
         "nixpkgs": [
           "nixpkgs-unstable"
         ],
@@ -811,6 +850,7 @@
         "devshell": "devshell_3",
         "flake-utils": "flake-utils_6",
         "harmonia": "harmonia",
+        "hass-west-wood": "hass-west-wood",
         "home-manager-stable": "home-manager-stable",
         "home-manager-unstable": "home-manager-unstable",
         "impermanence": "impermanence",
@@ -847,7 +887,7 @@
     },
     "sbt": {
       "inputs": {
-        "flake-utils": "flake-utils_11",
+        "flake-utils": "flake-utils_12",
         "nixpkgs": "nixpkgs_6"
       },
       "locked": {
@@ -867,7 +907,7 @@
     "sharry": {
       "inputs": {
         "devshell-tools": "devshell-tools",
-        "flake-utils": "flake-utils_10",
+        "flake-utils": "flake-utils_11",
         "nixpkgs": [
           "nixpkgs-unstable"
         ],
@@ -902,6 +942,21 @@
         "type": "github"
       }
     },
+    "systems_10": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
     "systems_2": {
       "locked": {
         "lastModified": 1681028828,

flake.nix

@@ -47,6 +47,8 @@
     # borgthin.inputs.nixpkgs.follows = "nixpkgs-mine";
     copyparty.url = "github:9001/copyparty";
     copyparty.inputs.nixpkgs.follows = "nixpkgs-unstable";
+    hass-west-wood.url = "github:devplayer0/hass-west-wood";
+    hass-west-wood.inputs.nixpkgs.follows = "nixpkgs-unstable";
   };
 
   outputs =

home-manager/modules/gui/claude-statusline.sh

@@ -0,0 +1,520 @@
+#!/usr/bin/env bash
+# Source: https://github.com/daniel3303/ClaudeCodeStatusLine
+# Single line: Model | tokens | %used | %remain | think | 5h bar @reset | 7d bar @reset | extra
+
+set -f  # disable globbing
+VERSION="1.4.4"
+
+input=$(cat)
+
+if [ -z "$input" ]; then
+    printf "Claude"
+    exit 0
+fi
+
+# ANSI colors matching oh-my-posh theme
+blue='\033[38;2;0;153;255m'
+orange='\033[38;2;255;176;85m'
+green='\033[38;2;0;160;0m'
+cyan='\033[38;2;46;149;153m'
+red='\033[38;2;255;85;85m'
+yellow='\033[38;2;230;200;0m'
+purple='\033[38;2;167;139;250m'
+white='\033[38;2;220;220;220m'
+dim='\033[2m'
+reset='\033[0m'
+
+# Format token counts (e.g., 50k / 200k)
+format_tokens() {
+    local num=$1
+    if [ "$num" -ge 1000000 ]; then
+        awk "BEGIN {v=sprintf(\"%.1f\",$num/1000000)+0; if(v==int(v)) printf \"%dm\",v; else printf \"%.1fm\",v}"
+    elif [ "$num" -ge 1000 ]; then
+        awk "BEGIN {printf \"%.0fk\", $num / 1000}"
+    else
+        printf "%d" "$num"
+    fi
+}
+
+# Format number with commas (e.g., 134,938)
+format_commas() {
+    printf "%'d" "$1"
+}
+
+# Return color escape based on usage percentage
+# Usage: usage_color <pct>
+usage_color() {
+    local pct=$1
+    if [ "$pct" -ge 90 ]; then echo "$red"
+    elif [ "$pct" -ge 70 ]; then echo "$orange"
+    elif [ "$pct" -ge 50 ]; then echo "$yellow"
+    else echo "$green"
+    fi
+}
+
+# Resolve config directory: CLAUDE_CONFIG_DIR (set by alias) or default ~/.claude
+claude_config_dir="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+
+# Return 0 (true) if $1 > $2 using semantic versioning
+version_gt() {
+    local a="${1#v}" b="${2#v}"
+    local IFS='.'
+    read -r a1 a2 a3 <<< "$a"
+    read -r b1 b2 b3 <<< "$b"
+    a1=${a1:-0}; a2=${a2:-0}; a3=${a3:-0}
+    b1=${b1:-0}; b2=${b2:-0}; b3=${b3:-0}
+    [ "$a1" -gt "$b1" ] 2>/dev/null && return 0
+    [ "$a1" -lt "$b1" ] 2>/dev/null && return 1
+    [ "$a2" -gt "$b2" ] 2>/dev/null && return 0
+    [ "$a2" -lt "$b2" ] 2>/dev/null && return 1
+    [ "$a3" -gt "$b3" ] 2>/dev/null && return 0
+    return 1
+}
+# ===== Extract data from JSON =====
+model_name=$(echo "$input" | jq -r '.model.display_name // "Claude"')
+model_name=$(echo "$model_name" | sed 's/ *(\([0-9.]*[kKmM]*\) context)/ \1/')  # "(1M context)" → "1M"
+
+# Context window
+size=$(echo "$input" | jq -r '.context_window.context_window_size // 200000')
+[ "$size" -eq 0 ] 2>/dev/null && size=200000
+
+# Token usage
+input_tokens=$(echo "$input" | jq -r '.context_window.current_usage.input_tokens // 0')
+cache_create=$(echo "$input" | jq -r '.context_window.current_usage.cache_creation_input_tokens // 0')
+cache_read=$(echo "$input" | jq -r '.context_window.current_usage.cache_read_input_tokens // 0')
+current=$(( input_tokens + cache_create + cache_read ))
+
+used_tokens=$(format_tokens $current)
+total_tokens=$(format_tokens $size)
+
+if [ "$size" -gt 0 ]; then
+    pct_used=$(( current * 100 / size ))
+else
+    pct_used=0
+fi
+pct_remain=$(( 100 - pct_used ))
+
+used_comma=$(format_commas $current)
+remain_comma=$(format_commas $(( size - current )))
+
+settings_path="$claude_config_dir/settings.json"
+effort_level=""
+stdin_effort=$(echo "$input" | jq -r '.effort.level // empty' 2>/dev/null)
+if [ -n "$stdin_effort" ]; then
+    effort_level="$stdin_effort"
+elif [ -n "$CLAUDE_CODE_EFFORT_LEVEL" ]; then
+    effort_level="$CLAUDE_CODE_EFFORT_LEVEL"
+elif [ -f "$settings_path" ]; then
+    effort_val=$(jq -r '.effortLevel // empty' "$settings_path" 2>/dev/null)
+    [ -n "$effort_val" ] && effort_level="$effort_val"
+fi
+[ -z "$effort_level" ] && effort_level="medium"
+
+# ===== Claude CLI version (cached, 1h TTL) =====
+cli_version_cache="/tmp/claude/statusline-cli-version"
+cli_version=""
+cli_version_max_age=3600
+
+if [ -f "$cli_version_cache" ]; then
+    cv_mtime=$(stat -c %Y "$cli_version_cache" 2>/dev/null || stat -f %m "$cli_version_cache" 2>/dev/null)
+    cv_now=$(date +%s)
+    cv_age=$(( cv_now - cv_mtime ))
+    if [ "$cv_age" -lt "$cli_version_max_age" ]; then
+        cli_version=$(cat "$cli_version_cache" 2>/dev/null)
+    fi
+fi
+
+if [ -z "$cli_version" ]; then
+    cli_version=$(claude --version 2>/dev/null | awk '{print $1}')
+    if [ -n "$cli_version" ]; then
+        mkdir -p /tmp/claude 2>/dev/null
+        echo "$cli_version" > "$cli_version_cache"
+    fi
+fi
+
+# ===== Build single-line output =====
+out=""
+out+="${blue}${model_name}${reset}"
+
+# Current working directory
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+if [ -n "$cwd" ]; then
+    display_dir="${cwd##*/}"
+    git_branch=$(git -C "${cwd}" rev-parse --abbrev-ref HEAD 2>/dev/null)
+    out+=" ${dim}|${reset} "
+    out+="${cyan}${display_dir}${reset}"
+    if [ -n "$git_branch" ]; then
+        out+="${dim}@${reset}${green}${git_branch}${reset}"
+        git_stat=$(git -C "${cwd}" diff --numstat 2>/dev/null | awk '{a+=$1; d+=$2} END {if (a+d>0) printf "+%d -%d", a, d}')
+        [ -n "$git_stat" ] && out+=" ${dim}(${reset}${green}${git_stat%% *}${reset} ${red}${git_stat##* }${reset}${dim})${reset}"
+    fi
+fi
+
+out+=" ${dim}|${reset} "
+out+="${orange}${used_tokens}/${total_tokens}${reset} ${dim}(${reset}${green}${pct_used}%${reset}${dim})${reset}"
+out+=" ${dim}|${reset} "
+out+="effort: "
+case "$effort_level" in
+    low)    out+="${dim}${effort_level}${reset}" ;;
+    medium) out+="${orange}med${reset}" ;;
+    high)   out+="${green}${effort_level}${reset}" ;;
+    xhigh)  out+="${purple}${effort_level}${reset}" ;;
+    max)    out+="${red}${effort_level}${reset}" ;;
+    *)      out+="${green}${effort_level}${reset}" ;;
+esac
+
+# ===== Cross-platform OAuth token resolution (from statusline.sh) =====
+# Tries credential sources in order: env var → macOS Keychain → Linux creds file → GNOME Keyring
+get_oauth_token() {
+    local token=""
+
+    # 1. Explicit env var override
+    if [ -n "$CLAUDE_CODE_OAUTH_TOKEN" ]; then
+        echo "$CLAUDE_CODE_OAUTH_TOKEN"
+        return 0
+    fi
+
+    # 2. macOS Keychain (Claude Code appends a SHA256 hash of CLAUDE_CONFIG_DIR to the service name)
+    if command -v security >/dev/null 2>&1; then
+        local keychain_svc="Claude Code-credentials"
+        if [ -n "$CLAUDE_CONFIG_DIR" ]; then
+            local dir_hash
+            dir_hash=$(echo -n "$CLAUDE_CONFIG_DIR" | shasum -a 256 | cut -c1-8)
+            keychain_svc="Claude Code-credentials-${dir_hash}"
+        fi
+        local blob
+        blob=$(security find-generic-password -s "$keychain_svc" -w 2>/dev/null)
+        if [ -n "$blob" ]; then
+            token=$(echo "$blob" | jq -r '.claudeAiOauth.accessToken // empty' 2>/dev/null)
+            if [ -n "$token" ] && [ "$token" != "null" ]; then
+                echo "$token"
+                return 0
+            fi
+        fi
+    fi
+
+    # 3. Linux credentials file
+    local creds_file="${claude_config_dir}/.credentials.json"
+    if [ -f "$creds_file" ]; then
+        token=$(jq -r '.claudeAiOauth.accessToken // empty' "$creds_file" 2>/dev/null)
+        if [ -n "$token" ] && [ "$token" != "null" ]; then
+            echo "$token"
+            return 0
+        fi
+    fi
+
+    # 4. GNOME Keyring via secret-tool
+    if command -v secret-tool >/dev/null 2>&1; then
+        local blob
+        blob=$(timeout 2 secret-tool lookup service "Claude Code-credentials" 2>/dev/null)
+        if [ -n "$blob" ]; then
+            token=$(echo "$blob" | jq -r '.claudeAiOauth.accessToken // empty' 2>/dev/null)
+            if [ -n "$token" ] && [ "$token" != "null" ]; then
+                echo "$token"
+                return 0
+            fi
+        fi
+    fi
+
+    echo ""
+}
+
+# ===== LINE 2 & 3: Usage limits with progress bars =====
+# First, try to use rate_limits data provided directly by Claude Code in the JSON input.
+# This is the most reliable source — no OAuth token or API call required.
+builtin_five_hour_pct=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
+builtin_five_hour_reset=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')
+builtin_seven_day_pct=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
+builtin_seven_day_reset=$(echo "$input" | jq -r '.rate_limits.seven_day.resets_at // empty')
+
+use_builtin=false
+if [ -n "$builtin_five_hour_pct" ] || [ -n "$builtin_seven_day_pct" ]; then
+    use_builtin=true
+fi
+
+# Cache setup — shared across all Claude Code instances to avoid rate limits
+claude_config_dir_hash=$(echo -n "$claude_config_dir" | shasum -a 256 2>/dev/null || echo -n "$claude_config_dir" | sha256sum 2>/dev/null)
+claude_config_dir_hash=$(echo "$claude_config_dir_hash" | cut -c1-8)
+cache_file="/tmp/claude/statusline-usage-cache-${claude_config_dir_hash}.json"
+cache_max_age=60  # seconds between API calls
+mkdir -p /tmp/claude
+
+needs_refresh=true
+usage_data=""
+
+# Always load cache — used as primary source for API path, and as fallback when builtin reports zero
+if [ -f "$cache_file" ] && [ -s "$cache_file" ]; then
+    cache_mtime=$(stat -c %Y "$cache_file" 2>/dev/null || stat -f %m "$cache_file" 2>/dev/null)
+    now=$(date +%s)
+    cache_age=$(( now - cache_mtime ))
+    if [ "$cache_age" -lt "$cache_max_age" ]; then
+        needs_refresh=false
+    fi
+    usage_data=$(cat "$cache_file" 2>/dev/null)
+fi
+
+# When builtin values are all zero AND reset timestamps are missing, it likely indicates
+# an API failure on Claude's side — fall through to cached data instead of displaying
+# misleading 0%. Genuine zero responses (after a billing reset) still include valid
+# resets_at timestamps, so we trust those.
+effective_builtin=false
+if $use_builtin; then
+    # Trust builtin if any percentage is non-zero
+    if { [ -n "$builtin_five_hour_pct" ] && [ "$(printf '%.0f' "$builtin_five_hour_pct" 2>/dev/null)" != "0" ]; } || \
+       { [ -n "$builtin_seven_day_pct" ] && [ "$(printf '%.0f' "$builtin_seven_day_pct" 2>/dev/null)" != "0" ]; }; then
+        effective_builtin=true
+    fi
+    # Also trust if reset timestamps are present — genuine zero responses include valid reset times
+    if ! $effective_builtin; then
+        if { [ -n "$builtin_five_hour_reset" ] && [ "$builtin_five_hour_reset" != "null" ] && [ "$builtin_five_hour_reset" != "0" ]; } || \
+           { [ -n "$builtin_seven_day_reset" ] && [ "$builtin_seven_day_reset" != "null" ] && [ "$builtin_seven_day_reset" != "0" ]; }; then
+            effective_builtin=true
+        fi
+    fi
+fi
+
+# Refresh API cache when stale — runs regardless of builtin rate_limits because
+# extra_usage is only exposed through the OAuth usage endpoint (not stdin JSON).
+# Throttled to cache_max_age and stampede-locked via touch for shared panes.
+if $needs_refresh; then
+    touch "$cache_file"  # stampede lock: prevent parallel panes from fetching simultaneously
+    token=$(get_oauth_token)
+    if [ -n "$token" ] && [ "$token" != "null" ]; then
+        response=$(curl -s --max-time 10 \
+            -H "Accept: application/json" \
+            -H "Content-Type: application/json" \
+            -H "Authorization: Bearer $token" \
+            -H "anthropic-beta: oauth-2025-04-20" \
+            -H "User-Agent: claude-code/2.1.34" \
+            "https://api.anthropic.com/api/oauth/usage" 2>/dev/null)
+        # Only cache valid usage responses (not error/rate-limit JSON)
+        if [ -n "$response" ] && echo "$response" | jq -e '.five_hour' >/dev/null 2>&1; then
+            usage_data="$response"
+            echo "$response" > "$cache_file"
+        fi
+    fi
+    # Remove the stampede sentinel if the fetch failed to produce valid JSON —
+    # otherwise an empty cache file would suppress retries for a full cache_max_age window.
+    [ -f "$cache_file" ] && [ ! -s "$cache_file" ] && rm -f "$cache_file"
+fi
+
+# Cross-platform ISO to epoch conversion
+# Converts ISO 8601 timestamp (e.g. "2025-06-15T12:30:00Z" or "2025-06-15T12:30:00.123+00:00") to epoch seconds.
+# Properly handles UTC timestamps and converts to local time.
+iso_to_epoch() {
+    local iso_str="$1"
+
+    # Try GNU date first (Linux) — handles ISO 8601 format automatically
+    local epoch
+    epoch=$(date -d "${iso_str}" +%s 2>/dev/null)
+    if [ -n "$epoch" ]; then
+        echo "$epoch"
+        return 0
+    fi
+
+    # BSD date (macOS) - handle various ISO 8601 formats
+    local stripped="${iso_str%%.*}"          # Remove fractional seconds (.123456)
+    stripped="${stripped%%Z}"                 # Remove trailing Z
+    stripped="${stripped%%+*}"               # Remove timezone offset (+00:00)
+    stripped="${stripped%%-[0-9][0-9]:[0-9][0-9]}"  # Remove negative timezone offset
+
+    # Check if timestamp is UTC (has Z or +00:00 or -00:00)
+    if [[ "$iso_str" == *"Z"* ]] || [[ "$iso_str" == *"+00:00"* ]] || [[ "$iso_str" == *"-00:00"* ]]; then
+        # For UTC timestamps, parse with timezone set to UTC
+        epoch=$(env TZ=UTC date -j -f "%Y-%m-%dT%H:%M:%S" "$stripped" +%s 2>/dev/null)
+    else
+        epoch=$(date -j -f "%Y-%m-%dT%H:%M:%S" "$stripped" +%s 2>/dev/null)
+    fi
+
+    if [ -n "$epoch" ]; then
+        echo "$epoch"
+        return 0
+    fi
+
+    return 1
+}
+
+# Format ISO reset time to compact local time
+# Usage: format_reset_time <iso_string> <style: time|datetime|date>
+format_reset_time() {
+    local iso_str="$1"
+    local style="$2"
+    { [ -z "$iso_str" ] || [ "$iso_str" = "null" ]; } && return
+
+    # Parse ISO datetime and convert to local time (cross-platform)
+    local epoch
+    epoch=$(iso_to_epoch "$iso_str")
+    [ -z "$epoch" ] && return
+
+    # Format based on style
+    # Try GNU date first (Linux), then BSD date (macOS)
+    # Previous implementation piped BSD date through sed/tr, which always returned
+    # exit code 0 from the last pipe stage, preventing the GNU date fallback from
+    # ever executing on Linux.
+    local formatted=""
+    case "$style" in
+        time)
+            formatted=$(date -d "@$epoch" +"%H:%M" 2>/dev/null) || \
+            formatted=$(date -j -r "$epoch" +"%H:%M" 2>/dev/null)
+            ;;
+        datetime)
+            formatted=$(date -d "@$epoch" +"%a %b %-d, %H:%M" 2>/dev/null) || \
+            formatted=$(date -j -r "$epoch" +"%a %b %-d, %H:%M" 2>/dev/null)
+            ;;
+        *)
+            formatted=$(date -d "@$epoch" +"%b %-d" 2>/dev/null) || \
+            formatted=$(date -j -r "$epoch" +"%b %-d" 2>/dev/null)
+            ;;
+    esac
+    [ -n "$formatted" ] && echo "$formatted"
+}
+
+sep=" ${dim}|${reset} "
+
+# Render extra_usage segment from API usage data (not available via stdin rate_limits).
+# Appends to the global $out. No-op when data is missing or is_enabled is false.
+render_extra_usage() {
+    local data="$1"
+    [ -z "$data" ] && return
+    local enabled
+    enabled=$(echo "$data" | jq -r '.extra_usage.is_enabled // false' 2>/dev/null)
+    [ "$enabled" != "true" ] && return
+
+    local pct used limit
+    pct=$(echo "$data" | jq -r '.extra_usage.utilization // 0' | awk '{printf "%.0f", $1}')
+    used=$(echo "$data" | jq -r '.extra_usage.used_credits // 0' | LC_NUMERIC=C awk '{printf "%.2f", $1/100}')
+    limit=$(echo "$data" | jq -r '.extra_usage.monthly_limit // 0' | LC_NUMERIC=C awk '{printf "%.2f", $1/100}')
+
+    if [ -n "$used" ] && [ -n "$limit" ] && [[ "$used" != *'$'* ]] && [[ "$limit" != *'$'* ]]; then
+        local color
+        color=$(usage_color "$pct")
+        out+="${sep}${white}extra${reset} ${color}\$${used}/\$${limit}${reset}"
+    else
+        out+="${sep}${white}extra${reset} ${green}enabled${reset}"
+    fi
+}
+
+if $effective_builtin; then
+    # ---- Use rate_limits data provided directly by Claude Code in JSON input ----
+    # resets_at values are Unix epoch integers in this source
+    if [ -n "$builtin_five_hour_pct" ]; then
+        five_hour_pct=$(printf "%.0f" "$builtin_five_hour_pct")
+        five_hour_color=$(usage_color "$five_hour_pct")
+        out+="${sep}${white}5h${reset} ${five_hour_color}${five_hour_pct}%${reset}"
+        if [ -n "$builtin_five_hour_reset" ] && [ "$builtin_five_hour_reset" != "null" ]; then
+            five_hour_reset=$(date -j -r "$builtin_five_hour_reset" +"%H:%M" 2>/dev/null || date -d "@$builtin_five_hour_reset" +"%H:%M" 2>/dev/null)
+            [ -n "$five_hour_reset" ] && out+=" ${dim}@${five_hour_reset}${reset}"
+        fi
+    fi
+
+    if [ -n "$builtin_seven_day_pct" ]; then
+        seven_day_pct=$(printf "%.0f" "$builtin_seven_day_pct")
+        seven_day_color=$(usage_color "$seven_day_pct")
+        out+="${sep}${white}7d${reset} ${seven_day_color}${seven_day_pct}%${reset}"
+        if [ -n "$builtin_seven_day_reset" ] && [ "$builtin_seven_day_reset" != "null" ]; then
+            seven_day_reset=$(date -j -r "$builtin_seven_day_reset" +"%a %b %-d, %H:%M" 2>/dev/null || date -d "@$builtin_seven_day_reset" +"%a %b %-d, %H:%M" 2>/dev/null)
+            [ -n "$seven_day_reset" ] && out+=" ${dim}@${seven_day_reset}${reset}"
+        fi
+    fi
+
+    # Render extra_usage from API cache (stdin rate_limits doesn't expose it)
+    render_extra_usage "$usage_data"
+
+    # Cache builtin values so they're available as fallback when API is unavailable.
+    # Convert epoch resets_at to ISO 8601 for compatibility with the API-format cache parser.
+    # Preserve extra_usage from prior API response so we don't clobber it.
+    _fh_reset_json="null"
+    if [ -n "$builtin_five_hour_reset" ] && [ "$builtin_five_hour_reset" != "null" ] && [ "$builtin_five_hour_reset" != "0" ]; then
+        _fh_iso=$(date -u -r "$builtin_five_hour_reset" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || \
+                  date -u -d "@$builtin_five_hour_reset" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null)
+        [ -n "$_fh_iso" ] && _fh_reset_json="\"$_fh_iso\""
+    fi
+    _sd_reset_json="null"
+    if [ -n "$builtin_seven_day_reset" ] && [ "$builtin_seven_day_reset" != "null" ] && [ "$builtin_seven_day_reset" != "0" ]; then
+        _sd_iso=$(date -u -r "$builtin_seven_day_reset" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || \
+                  date -u -d "@$builtin_seven_day_reset" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null)
+        [ -n "$_sd_iso" ] && _sd_reset_json="\"$_sd_iso\""
+    fi
+    _extra_json=$(echo "$usage_data" | jq -c '.extra_usage // null' 2>/dev/null)
+    [ -z "$_extra_json" ] && _extra_json="null"
+    printf '{"five_hour":{"utilization":%s,"resets_at":%s},"seven_day":{"utilization":%s,"resets_at":%s},"extra_usage":%s}' \
+        "${builtin_five_hour_pct:-0}" "$_fh_reset_json" \
+        "${builtin_seven_day_pct:-0}" "$_sd_reset_json" \
+        "$_extra_json" > "$cache_file" 2>/dev/null
+elif [ -n "$usage_data" ] && echo "$usage_data" | jq -e '.five_hour' >/dev/null 2>&1; then
+    # ---- Fall back: API-fetched usage data ----
+    # ---- 5-hour (current) ----
+    five_hour_pct=$(echo "$usage_data" | jq -r '.five_hour.utilization // 0' | awk '{printf "%.0f", $1}')
+    five_hour_reset_iso=$(echo "$usage_data" | jq -r '.five_hour.resets_at // empty')
+    five_hour_reset=$(format_reset_time "$five_hour_reset_iso" "time")
+    five_hour_color=$(usage_color "$five_hour_pct")
+
+    out+="${sep}${white}5h${reset} ${five_hour_color}${five_hour_pct}%${reset}"
+    [ -n "$five_hour_reset" ] && out+=" ${dim}@${five_hour_reset}${reset}"
+
+    # ---- 7-day (weekly) ----
+    seven_day_pct=$(echo "$usage_data" | jq -r '.seven_day.utilization // 0' | awk '{printf "%.0f", $1}')
+    seven_day_reset_iso=$(echo "$usage_data" | jq -r '.seven_day.resets_at // empty')
+    seven_day_reset=$(format_reset_time "$seven_day_reset_iso" "datetime")
+    seven_day_color=$(usage_color "$seven_day_pct")
+
+    out+="${sep}${white}7d${reset} ${seven_day_color}${seven_day_pct}%${reset}"
+    [ -n "$seven_day_reset" ] && out+=" ${dim}@${seven_day_reset}${reset}"
+
+    render_extra_usage "$usage_data"
+else
+    # No valid usage data — show placeholders
+    out+="${sep}${white}5h${reset} ${dim}-${reset}"
+    out+="${sep}${white}7d${reset} ${dim}-${reset}"
+fi
+
+# ===== Update check (cached, 24h TTL) =====
+# Set STATUSLINE_CHECK_UPDATES=false to disable the update check (no network calls).
+update_line=""
+if [ "${STATUSLINE_CHECK_UPDATES:-true}" != "false" ]; then
+    version_cache_file="/tmp/claude/statusline-version-cache.json"
+    version_cache_max_age=86400  # 24 hours
+
+    version_needs_refresh=true
+    version_data=""
+
+    if [ -f "$version_cache_file" ]; then
+        vc_mtime=$(stat -c %Y "$version_cache_file" 2>/dev/null || stat -f %m "$version_cache_file" 2>/dev/null)
+        vc_now=$(date +%s)
+        vc_age=$(( vc_now - vc_mtime ))
+        if [ "$vc_age" -lt "$version_cache_max_age" ]; then
+            version_needs_refresh=false
+        fi
+        version_data=$(cat "$version_cache_file" 2>/dev/null)
+    fi
+
+    if $version_needs_refresh; then
+        touch "$version_cache_file" 2>/dev/null
+        vc_response=$(curl -s --max-time 5 \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/daniel3303/ClaudeCodeStatusLine/releases/latest" 2>/dev/null)
+        if [ -n "$vc_response" ] && echo "$vc_response" | jq -e '.tag_name' >/dev/null 2>&1; then
+            version_data="$vc_response"
+            echo "$vc_response" > "$version_cache_file"
+        elif [ ! -s "$version_cache_file" ]; then
+            rm -f "$version_cache_file" 2>/dev/null
+        fi
+    fi
+
+    if [ -n "$version_data" ]; then
+        latest_tag=$(echo "$version_data" | jq -r '.tag_name // empty')
+        if [ -n "$latest_tag" ] && version_gt "$latest_tag" "$VERSION"; then
+            update_line="\n${dim}Update available: ${latest_tag} → Tell Claude: \"Find my installed status bar and update it\"${reset}"
+        fi
+    fi
+fi
+
+# Append CLI version as last segment
+if [ -n "$cli_version" ]; then
+    out+=" ${dim}|${reset} ${orange}v${cli_version}${reset}"
+fi
+
+# Output
+printf "%b" "$out$update_line"
+
+exit 0

home-manager/modules/gui/default.nix

@@ -155,6 +155,19 @@ in
               };
             };
           };
+
+          claude-code = {
+            enable = true;
+            settings = {
+              model = "opus";
+              theme = "auto";
+              statusLine = {
+                type = "command";
+                command = ./claude-statusline.sh;
+                padding = 0;
+              };
+            };
+          };
         };
       }
 

nixos/boxes/colony/vms/estuary/bgp.nix

@@ -291,6 +291,23 @@ in
             neighbor 2001:7f8:10f::3:3e9b:134 as 212635;
           }
 
+          protocol bgp peer4_nlix_meta1 from peer_bgp4 {
+            description "Meta 1 (on NL-ix, IPv4)";
+            neighbor 193.239.116.147 as 32934;
+          }
+          protocol bgp peer4_nlix_meta2 from peer_bgp4 {
+            description "Meta 2 (on NL-ix, IPv4)";
+            neighbor 193.239.116.148 as 32934;
+          }
+          protocol bgp peer6_nlix_meta1 from peer_bgp6 {
+            description "Meta 1 (on NL-ix, IPv6)";
+            neighbor 2001:7f8:13::a503:2934:1 as 32934;
+          }
+          protocol bgp peer6_nlix_meta2 from peer_bgp6 {
+            description "Meta 2 (on NL-ix, IPv6)";
+            neighbor 2001:7f8:13::a503:2934:2 as 32934;
+          }
+
           protocol bgp peer4_frysix_meta1 from peer_bgp4 {
             description "Meta 1 (on Frys-IX, IPv4)";
             neighbor 185.1.160.225 as 32934;

nixos/boxes/colony/vms/git/gitea-actions.nix

@@ -1,19 +1,7 @@
 { lib, pkgs, config, ... }:
 let
-  inherit (builtins) toJSON;
   inherit (lib) mkForce;
   inherit (lib.my.c) pubDomain;
-
-  cfgFile = pkgs.writeText "gitea-actions-runner.yaml" (toJSON {
-    container = {
-      network = "podman";
-      privileged = true;
-    };
-    cache = {
-      enabled = true;
-      dir = "/var/cache/gitea-runner";
-    };
-  });
 in
 {
   config = {
@@ -30,8 +18,8 @@ in
           enable = true;
           name = "main-docker";
           labels = [
-            "debian-node-bullseye:docker://node:18-bullseye"
+            "debian-node-trixie:docker://node:24-trixie"
-            "ubuntu-22.04:docker://git.nul.ie/dev/actions-ubuntu:22.04"
+            "ubuntu-26.04:docker://git.nul.ie/dev/actions-ubuntu:26.04"
           ];
           url = "https://git.${pubDomain}";
           tokenFile = config.age.secrets."gitea/actions-runner.env".path;
@@ -39,6 +27,14 @@ in
             runner = {
               timeout = "8h";
             };
+            container = {
+              network = "podman";
+              privileged = true;
+            };
+            cache = {
+              enabled = true;
+              dir = "/var/cache/gitea-runner";
+            };
           };
         };
       };
@@ -66,7 +62,6 @@ in
           DynamicUser = mkForce false;
           User = "gitea-runner";
           Group = "gitea-runner";
-          ExecStart = mkForce "${config.services.gitea-actions-runner.package}/bin/act_runner -c ${cfgFile} daemon";
         };
       };
     };

nixos/boxes/home/castle/default.nix

@@ -230,12 +230,15 @@ in
                 ];
               };
 
+              programs = {
+                claude-code = {
+                  enable = true;
+                };
+              };
+
               services = {
                 blueman-applet.enable = true;
-                easyeffects = {
+                easyeffects.enable = true;
-                  enable = true;
-                  preset = "moar-bass";
-                };
               };
 
               wayland.windowManager.sway = {

nixos/boxes/home/palace/vms/sfh/containers/hass.nix

@@ -210,6 +210,7 @@ in
             customComponents = with pkgs.home-assistant-custom-components; [
               alarmo
               frigate
+              west_wood_club
             ];
 
             configWritable = false;

nixos/modules/common.nix

@@ -82,6 +82,7 @@ in
           # inputs.borgthin.overlays.default
           inputs.boardie.overlays.default
           inputs.copyparty.overlays.default
+          inputs.hass-west-wood.overlays.default
         ];
         config = {
           allowUnfree = true;