From c7332786665575ed8e96807792308043236c7872 Mon Sep 17 00:00:00 2001
From: "K. Isom" <kyle@imap.cc>
Date: Tue, 15 Sep 2026 23:20:55 -0700
Subject: [PATCH] Add AGENTS.md.

---
 AGENTS.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2926584
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+A flake-based NixOS configuration managing 8 hosts (all x86_64-linux). Pinned to nixpkgs `nixos-26.05`, with `nixos-unstable` available as a secondary input for select packages.
+
+## Common Commands
+
+- **Build/deploy locally**: `rebuild-nixos` (installed to `~/.local/bin` via `make`)
+  - This runs on the target machine: pulls from local git remote, then `doas nixos-rebuild switch --flake .`
+- **Build a specific host** (dry run): `nixos-rebuild build --flake .#<hostname>`
+- **Flash a remote machine**: `./script/flash.sh <config-name> <ssh-address>` (uses nixos-anywhere)
+- **Check if reboot needed**: `./script/check-restart.sh`
+- **Install the rebuild script**: `make`
+
+## Architecture
+
+### Flake Structure
+
+All hosts are generated via `lib.genAttrs` in `flake.nix`. Each host gets:
+- `disko` module (declarative disk management)
+- `nix-index-database` with comma
+- Host-specific config from `./hw/<hostname>/`
+- Shared base from `./configuration.nix`
+
+Custom packages `ke` and `kte` are flake inputs from `git.wntrmute.dev/kyle/`.
+
+### Host Layout
+
+Each host has a directory under `hw/<hostname>/` containing:
+- `default.nix` — imports hardware-config and (for desktops) desktop/qemu modules
+- `hardware-configuration.nix` — auto-generated hardware config
+- `disk-config.nix` — disko disk layout (where applicable)
+
+Full desktop hosts (imladris, ono-sendai, straylight) import `configs/desktop.nix`; vade is a lightweight desktop importing `configs/desktop-light.nix`. Most desktops also import `configs/qemu.nix`.
+Server hosts (orion, rift, sk, svc) have no desktop environment; sk is minimal (hardware config + disk config only).
+Hosts participating in the MCP (Metacircular Control Plane) import `configs/mcp.nix` and `configs/mcpkg.nix`; straylight is becoming the core MCP host.
+
+### Shared Modules (`configs/`)
+
+- `pkgs.nix` — system-wide packages
+- `desktop.nix` — full desktop (builds on desktop-light.nix)
+- `desktop-light.nix` — baseline lightweight desktop
+- `desktop-packages-full.nix` / `desktop-packages-light.nix` — GUI applications
+- `git.nix` — git identity config
+- `qemu.nix` — QEMU/KVM virtualization
+- `mcp.nix` / `mcpkg.nix` — MCP agent user/service and MCP packages
+
+### Key Design Decisions
+
+- **No home-manager** — all config is system-level NixOS modules
+- **No overlays** — packages are used directly; `allowUnfree = true`
+- **No secrets manager** — SSH keys via gpg-agent, `doas` (not sudo) for privilege escalation
+- **Podman** with Docker compatibility enabled on all hosts
+- **Tailscale** and **Syncthing** enabled on all hosts
+- **LUKS encryption** on most hosts (all except sk and svc)
+- `inputs` are passed to modules via `specialArgs`