feat(nix): add harmonia cache to nix.settings

Configure all NixOS machines to use the internal harmonia binary cache:
- Add nix-cache.johnogle.info as substituter
- Add harmonia signing public key to trusted-public-keys
- Enable fallback for local builds when cache unreachable
- Set 5s connect-timeout for faster fallback

Refs: x-qdkuu

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

.beads/.gitignore

@@ -32,6 +32,11 @@ beads.left.meta.json
 beads.right.jsonl
 beads.right.meta.json
 
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+sync_base.jsonl
+
 # NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
 # They would override fork protection in .git/info/exclude, allowing
 # contributors to accidentally commit upstream issue databases.

.beads/config.yaml

@@ -6,7 +6,7 @@
 # Issue prefix for this repository (used by bd init)
 # If not set, bd init will auto-detect from directory name
 # Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
-# issue-prefix: ""
+issue-prefix: "x"
 
 # Use no-db mode: load from JSONL, no SQLite, write back after each command
 # When true, bd will use .beads/issues.jsonl as the source of truth
@@ -59,4 +59,6 @@ sync-branch: "beads-sync"
 # - linear.url
 # - linear.api-key
 # - github.org
-# - github.repo
+# - github.repo
+
+routing.mode: "explicit"

.beads/metadata.json

@@ -1,4 +0,0 @@
-{
-  "database": "beads.db",
-  "jsonl_export": "sync_base.jsonl"
-}

.gitea/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: https://git.johnogle.info/johno/gitea-actions/nix-setup@v1
+
+      - name: Check flake
+        run: nix flake check
+        env:
+          NIX_CONFIG: "access-tokens = git.johnogle.info=${{ secrets.GITEA_ACCESS_TOKEN }}"

.gitignore

@@ -1,3 +1,8 @@
 result
 thoughts
 .beads
+
+# Gas Town (added by gt)
+.runtime/
+.claude/
+.logs/

.goosehints

@@ -9,7 +9,7 @@ Directory Structure:
 ----------------------
 • packages/      - Custom Nix packages leveraged across various configurations.
 • roles/         - Role-based configurations (e.g., kodi, bluetooth) each with its own module (default.nix) for inclusion in machine setups.
-• machines/      - Machine-specific configurations (e.g., nix-book, z790prors, boxy, wixos) including configuration.nix and hardware-configuration.nix tailored for each hardware.
+• machines/      - Machine-specific configurations (e.g., nix-book, zix790prors, boxy) including configuration.nix and hardware-configuration.nix tailored for each hardware.
 • home/          - Home-manager configurations for personal environments and application settings (e.g., home-nix-book.nix, home-z790prors.nix).
 
 Design Principles:

AGENTS.md

@@ -6,11 +6,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 This is a NixOS configuration repository using flakes, managing multiple machines and home-manager configurations. The repository follows a modular architecture with reusable "roles" that can be composed for different machines.
 
+## Issue Tracking
+
+This repository uses `beads` for issue tracking and management. Run `bd quickstart` to get an overview of the system at the start of every session.
+
 ## Architecture
 
 ### Flake Structure
 - **flake.nix**: Main entry point defining inputs (nixpkgs, home-manager, plasma-manager, etc.) and outputs for multiple NixOS configurations
-- **Machines**: `nix-book`, `boxy`, `wixos` (WSL configuration), `zix790prors`, `live-usb`, `johno-macbookpro` (Darwin/macOS)
+- **Machines**: `nix-book`, `boxy`, `zix790prors`, `live-usb`, `johno-macbookpro` (Darwin/macOS)
 - **Home configurations**: Standalone home-manager configuration for user `johno`
 
 ### Directory Structure
@@ -74,7 +78,6 @@ The repository also uses a modular home-manager role system for user-space confi
 - **nix-book**: Compact laptop → excludes office/media roles due to SSD space constraints
 - **boxy**: Living room media center → optimized for media consumption, excludes sync/office (shared machine)
 - **zix790prors**: All-purpose workstation → full desktop experience with all roles enabled
-- **wixos**: WSL2 development → full desktop experience, inherits from zix790prors Windows host
 - **live-usb**: Temporary environment → only base + desktop roles, no persistent services
 - **johno-macbookpro**: macOS work laptop → Darwin-specific configuration with development tools
 
@@ -107,7 +110,6 @@ darwin-rebuild build --flake .#johno-macbookpro
 - `nix-book`: Compact laptop with storage constraints, uses `home/home-laptop-compact.nix`
 - `boxy`: Shared living room media center/gaming desktop with AMD GPU, uses `home/home-media-center.nix`
 - `zix790prors`: Powerful all-purpose workstation (gaming, 3D modeling, development), dual-boots Windows 11 with shared btrfs /games partition, uses `home/home-desktop.nix`
-- `wixos`: WSL2 development environment running in Windows partition of zix790prors, uses `home/home-desktop.nix`
 - `live-usb`: Bootable ISO configuration, uses `home/home-live-usb.nix`
 - `johno-macbookpro`: macOS work laptop, uses `home/home-darwin-work.nix`
 

build-liveusb.sh

@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-
-# Build Live USB ISO from flake configuration
-# Creates an uncompressed ISO suitable for Ventoy and other USB boot tools
-
-set -e
-
-echo "Building Live USB ISO..."
-nix build .#nixosConfigurations.live-usb.config.system.build.isoImage --show-trace
-
-if [ -f "./result/iso/"*.iso ]; then
-    iso_file=$(ls ./result/iso/*.iso)
-    echo "✅ Build complete!"
-    echo "📁 ISO location: $iso_file"
-    echo "💾 Ready for Ventoy or dd to USB"
-else
-    echo "❌ Build failed - no ISO file found"
-    exit 1
-fi

flake.lock

@@ -8,27 +8,28 @@
         ]
       },
       "locked": {
-        "lastModified": 1767911810,
-        "narHash": "sha256-0L4ATr01UsmBC0rSW62VIMVVSUihAQu2+ZOoHk9BQnA=",
+        "lastModified": 1769840331,
+        "narHash": "sha256-Yp0K4JoXX8EcHp1juH4OZ7dcCmkopDu4VvAgZEOxgL8=",
         "owner": "steveyegge",
         "repo": "beads",
-        "rev": "28ff9fe9919a9665a0f00f5b3fcd084b43fb6cc3",
+        "rev": "93965b4abeed920a4701e03571d1b6bb75810722",
         "type": "github"
       },
       "original": {
         "owner": "steveyegge",
         "repo": "beads",
+        "rev": "93965b4abeed920a4701e03571d1b6bb75810722",
         "type": "github"
       }
     },
     "doomemacs": {
       "flake": false,
       "locked": {
-        "lastModified": 1767773143,
-        "narHash": "sha256-QL/t9v2kFNxBDyNJb/s411o3mxujan+QX5IZglTdpTk=",
+        "lastModified": 1768984347,
+        "narHash": "sha256-VvC4rgAAaFnYLCdcUoz7dTE3kuBNuHIc+GlXOrPCxpg=",
         "owner": "doomemacs",
         "repo": "doomemacs",
-        "rev": "3e15fb36d7f94f0a218bda977be4d3f5da983a71",
+        "rev": "57818a6da90fbef39ff80d62fab2cd319496c3b9",
         "type": "github"
       },
       "original": {
@@ -47,11 +48,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1768011937,
-        "narHash": "sha256-SnU2XTo34vwVaijs+4VwcXTNwMWO4nwzzs08N39UagA=",
+        "lastModified": 1769848312,
+        "narHash": "sha256-ggBocPd1L4l5MFNV0Fw9aSGZZO4aGzCfgh4e6hQ77RE=",
         "owner": "nix-community",
         "repo": "emacs-overlay",
-        "rev": "79abf71d9897cf3b5189f7175cda1b1102abc65c",
+        "rev": "be0b4f4f28f69be61e9174807250e3235ee11d50",
         "type": "github"
       },
       "original": {
@@ -60,22 +61,6 @@
         "type": "github"
       }
     },
-    "flake-compat": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1765121682,
-        "narHash": "sha256-4VBOP18BFeiPkyhy9o4ssBNQEvfvv1kXkasAYd0+rrA=",
-        "owner": "edolstra",
-        "repo": "flake-compat",
-        "rev": "65f23138d8d09a92e30f1e5c87611b23ef451bf3",
-        "type": "github"
-      },
-      "original": {
-        "owner": "edolstra",
-        "repo": "flake-compat",
-        "type": "github"
-      }
-    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
@@ -94,6 +79,22 @@
         "type": "github"
       }
     },
+    "gastown": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1770098007,
+        "narHash": "sha256-CFlN57BXlR5FobTChdE2GgdIGx4xJcFFCk1E5Q98cSQ=",
+        "owner": "steveyegge",
+        "repo": "gastown",
+        "rev": "13461161063bf7b2365fe5fd4df88e32c3ba2a28",
+        "type": "github"
+      },
+      "original": {
+        "owner": "steveyegge",
+        "repo": "gastown",
+        "type": "github"
+      }
+    },
     "google-cookie-retrieval": {
       "inputs": {
         "nixpkgs": [
@@ -101,11 +102,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1761423376,
-        "narHash": "sha256-pMy3cnUFfue4vz/y0jx71BfcPGxZf+hk/DtnzWvfU0c=",
+        "lastModified": 1768846578,
+        "narHash": "sha256-82f/+e8HAwmBukiLlr7I3HYvM/2GCd5SOc+BC+qzsOQ=",
         "ref": "refs/heads/main",
-        "rev": "a1f695665771841a988afc965526cbf99160cd77",
-        "revCount": 11,
+        "rev": "c11ff9d3c67372a843a0fa6bf23132e986bd6955",
+        "revCount": 14,
         "type": "git",
         "url": "https://git.johnogle.info/johno/google-cookie-retrieval.git"
       },
@@ -121,11 +122,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1767514898,
-        "narHash": "sha256-ONYqnKrPzfKEEPChoJ9qPcfvBqW9ZgieDKD7UezWPg4=",
+        "lastModified": 1768949235,
+        "narHash": "sha256-TtjKgXyg1lMfh374w5uxutd6Vx2P/hU81aEhTxrO2cg=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "7a06e8a2f844e128d3b210a000a62716b6040b7f",
+        "rev": "75ed713570ca17427119e7e204ab3590cc3bf2a5",
         "type": "github"
       },
       "original": {
@@ -142,11 +143,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1767556355,
-        "narHash": "sha256-RDTUBDQBi9D4eD9iJQWtUDN/13MDLX+KmE+TwwNUp2s=",
+        "lastModified": 1769397130,
+        "narHash": "sha256-TTM4KV9IHwa181X7afBRbhLJIrgynpDjAXJFMUOWfyU=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "f894bc4ffde179d178d8deb374fcf9855d1a82b7",
+        "rev": "c37679d37bdbecf11bbe3c5eb238d89ca4f60641",
         "type": "github"
       },
       "original": {
@@ -164,11 +165,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1767082077,
-        "narHash": "sha256-2tL1mRb9uFJThUNfuDm/ehrnPvImL/QDtCxfn71IEz4=",
+        "lastModified": 1769273817,
+        "narHash": "sha256-+iyLihi/ynJokMgJZMRXuMuI6DPGUQRajz5ztNCHgnI=",
         "owner": "Jovian-Experiments",
         "repo": "Jovian-NixOS",
-        "rev": "efd4b22e6fdc6d7fb4e186ae333a4b74e03da440",
+        "rev": "98f988ad46e31f9956c5f6874dfb3580a7ff3969",
         "type": "github"
       },
       "original": {
@@ -184,11 +185,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1765066094,
-        "narHash": "sha256-0YSU35gfRFJzx/lTGgOt6ubP8K6LeW0vaywzNNqxkl4=",
+        "lastModified": 1767634391,
+        "narHash": "sha256-owcSz2ICqTSvhBbhPP+1eWzi88e54rRZtfCNE5E/wwg=",
         "owner": "nix-darwin",
         "repo": "nix-darwin",
-        "rev": "688427b1aab9afb478ca07989dc754fa543e03d5",
+        "rev": "08585aacc3d6d6c280a02da195fdbd4b9cf083c2",
         "type": "github"
       },
       "original": {
@@ -206,11 +207,11 @@
         "systems": "systems_2"
       },
       "locked": {
-        "lastModified": 1768034604,
-        "narHash": "sha256-62pIZMvGHhYJmMiiBsxHqZt/dFyENPcFHlJq5NJF3Sw=",
+        "lastModified": 1769849328,
+        "narHash": "sha256-BjH1Ge6O8ObN6Z97un2U87pl4POO99Q8RSsgIuTZq8Q=",
         "owner": "marienz",
         "repo": "nix-doom-emacs-unstraightened",
-        "rev": "9b3b8044fe4ccdcbb2d6f733d7dbe4d5feea18bc",
+        "rev": "fc1d7190c49558cdc6af20d7657075943a500a93",
         "type": "github"
       },
       "original": {
@@ -241,65 +242,13 @@
         "type": "github"
       }
     },
-    "nixos-wsl": {
-      "inputs": {
-        "flake-compat": "flake-compat",
-        "nixpkgs": "nixpkgs"
-      },
-      "locked": {
-        "lastModified": 1765841014,
-        "narHash": "sha256-55V0AJ36V5Egh4kMhWtDh117eE3GOjwq5LhwxDn9eHg=",
-        "owner": "nix-community",
-        "repo": "NixOS-WSL",
-        "rev": "be4af8042e7a61fa12fda58fe9a3b3babdefe17b",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-community",
-        "ref": "main",
-        "repo": "NixOS-WSL",
-        "type": "github"
-      }
-    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1765472234,
-        "narHash": "sha256-9VvC20PJPsleGMewwcWYKGzDIyjckEz8uWmT0vCDYK0=",
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "2fbfb1d73d239d2402a8fe03963e37aab15abe8b",
-        "type": "github"
-      },
-      "original": {
-        "owner": "NixOS",
-        "ref": "nixos-unstable",
-        "repo": "nixpkgs",
-        "type": "github"
-      }
-    },
-    "nixpkgs-unstable": {
-      "locked": {
-        "lastModified": 1767379071,
-        "narHash": "sha256-EgE0pxsrW9jp9YFMkHL9JMXxcqi/OoumPJYwf+Okucw=",
+        "lastModified": 1769089682,
+        "narHash": "sha256-9yA/LIuAVQq0lXelrZPjLuLVuZdm03p8tfmHhnDIkms=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "fb7944c166a3b630f177938e478f0378e64ce108",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nixos",
-        "ref": "nixos-unstable",
-        "repo": "nixpkgs",
-        "type": "github"
-      }
-    },
-    "nixpkgs_2": {
-      "locked": {
-        "lastModified": 1767480499,
-        "narHash": "sha256-8IQQUorUGiSmFaPnLSo2+T+rjHtiNWc+OAzeHck7N48=",
-        "owner": "nixos",
-        "repo": "nixpkgs",
-        "rev": "30a3c519afcf3f99e2c6df3b359aec5692054d92",
+        "rev": "078d69f03934859a181e81ba987c2bb033eebfc5",
         "type": "github"
       },
       "original": {
@@ -309,6 +258,54 @@
         "type": "github"
       }
     },
+    "nixpkgs-qt": {
+      "locked": {
+        "lastModified": 1770464364,
+        "narHash": "sha256-z5NJPSBwsLf/OfD8WTmh79tlSU8XgIbwmk6qB1/TFzY=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "23d72dabcb3b12469f57b37170fcbc1789bd7457",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-unstable": {
+      "locked": {
+        "lastModified": 1769170682,
+        "narHash": "sha256-oMmN1lVQU0F0W2k6OI3bgdzp2YOHWYUAw79qzDSjenU=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "c5296fdd05cfa2c187990dd909864da9658df755",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "perles": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1769460725,
+        "narHash": "sha256-zM2jw+emxe8+mNyR1ebMWkQiEx8uSmhoqqI0IxXLDgs=",
+        "owner": "zjrosen",
+        "repo": "perles",
+        "rev": "57b20413eea461452b59e13f5a4a367953b1f768",
+        "type": "github"
+      },
+      "original": {
+        "owner": "zjrosen",
+        "repo": "perles",
+        "type": "github"
+      }
+    },
     "plasma-manager": {
       "inputs": {
         "home-manager": [
@@ -319,11 +316,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1763909441,
-        "narHash": "sha256-56LwV51TX/FhgX+5LCG6akQ5KrOWuKgcJa+eUsRMxsc=",
+        "lastModified": 1767662275,
+        "narHash": "sha256-d5Q1GmQ+sW1Bt8cgDE0vOihzLaswsm8cSdg8124EqXE=",
         "owner": "nix-community",
         "repo": "plasma-manager",
-        "rev": "b24ed4b272256dfc1cc2291f89a9821d5f9e14b4",
+        "rev": "51816be33a1ff0d4b22427de83222d5bfa96d30e",
         "type": "github"
       },
       "original": {
@@ -342,11 +339,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1763909441,
-        "narHash": "sha256-56LwV51TX/FhgX+5LCG6akQ5KrOWuKgcJa+eUsRMxsc=",
+        "lastModified": 1767662275,
+        "narHash": "sha256-d5Q1GmQ+sW1Bt8cgDE0vOihzLaswsm8cSdg8124EqXE=",
         "owner": "nix-community",
         "repo": "plasma-manager",
-        "rev": "b24ed4b272256dfc1cc2291f89a9821d5f9e14b4",
+        "rev": "51816be33a1ff0d4b22427de83222d5bfa96d30e",
         "type": "github"
       },
       "original": {
@@ -358,15 +355,17 @@
     "root": {
       "inputs": {
         "beads": "beads",
+        "gastown": "gastown",
         "google-cookie-retrieval": "google-cookie-retrieval",
         "home-manager": "home-manager",
         "home-manager-unstable": "home-manager-unstable",
         "jovian": "jovian",
         "nix-darwin": "nix-darwin",
         "nix-doom-emacs-unstraightened": "nix-doom-emacs-unstraightened",
-        "nixos-wsl": "nixos-wsl",
-        "nixpkgs": "nixpkgs_2",
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-qt": "nixpkgs-qt",
         "nixpkgs-unstable": "nixpkgs-unstable",
+        "perles": "perles",
         "plasma-manager": "plasma-manager",
         "plasma-manager-unstable": "plasma-manager-unstable"
       }

flake.nix

@@ -4,8 +4,10 @@
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
     nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";
-    nixos-wsl.url = "github:nix-community/NixOS-WSL/main";
-    
+    # Separate nixpkgs for qt5webengine-dependent packages (jellyfin-media-player, etc.)
+    # Updates on separate Renovate schedule to avoid massive qt rebuilds
+    nixpkgs-qt.url = "github:nixos/nixpkgs/nixos-25.11";
+
     nix-darwin = {
       url = "github:nix-darwin/nix-darwin/nix-darwin-25.11";
       inputs.nixpkgs.follows = "nixpkgs";
@@ -44,10 +46,22 @@
     };
 
     beads = {
-      url = "github:steveyegge/beads";
+      # v0.49.1 has dolt server mode support (gt-1mf.3)
+      # Pinned to 259ddd92 - uses Go 1.24 compatible with nixpkgs
+      url = "github:steveyegge/beads/93965b4abeed920a4701e03571d1b6bb75810722";
       inputs.nixpkgs.follows = "nixpkgs-unstable";
     };
 
+    gastown = {
+      url = "github:steveyegge/gastown";
+      flake = false;  # No flake.nix upstream yet
+    };
+
+    perles = {
+      url = "github:zjrosen/perles";
+      flake = false;  # No flake.nix upstream yet
+    };
+
     nix-doom-emacs-unstraightened = {
       url = "github:marienz/nix-doom-emacs-unstraightened";
       # Don't follow nixpkgs to avoid rebuild issues with emacs-overlay
@@ -55,95 +69,81 @@
     };
   };
 
-  outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, ... } @ inputs: let
+  outputs = { self, nixpkgs, nixpkgs-unstable, ... } @ inputs: let
+    # Shared overlay function to reduce duplication across module sets
+    # Parameters:
+    #   unstableOverlays: Additional overlays to apply when importing nixpkgs-unstable
+    mkBaseOverlay = { unstableOverlays ? [] }: (final: prev: {
+      unstable = import nixpkgs-unstable {
+        system = prev.stdenv.hostPlatform.system;
+        config.allowUnfree = true;
+        overlays = unstableOverlays;
+      };
+      # Separate nixpkgs for qt5webengine-heavy packages to avoid rebuild churn
+      qt-pinned = import inputs.nixpkgs-qt {
+        system = prev.stdenv.hostPlatform.system;
+        config.allowUnfree = true;
+      };
+      custom = prev.callPackage ./packages {};
+      # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
+      bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
+    });
+
+    # Shared home-manager configuration factory
+    # Parameters:
+    #   sharedModules: Additional modules to include in home-manager.sharedModules
+    mkHomeManagerConfig = { sharedModules ? [] }: {
+      home-manager.useGlobalPkgs = true;
+      home-manager.useUserPackages = true;
+      home-manager.sharedModules = sharedModules ++ [
+        inputs.nix-doom-emacs-unstraightened.homeModule
+      ];
+      home-manager.extraSpecialArgs = {
+        globalInputs = inputs;
+      };
+    };
+
+
+    # Shared unstable overlays for custom package builds
+    customUnstableOverlays = [
+      # Override claude-code in unstable to use our custom GCS-based build
+      # (needed for corporate networks that block npm registry)
+      (ufinal: uprev: {
+        claude-code = uprev.callPackage ./packages/claude-code {};
+      })
+    ];
+
     nixosModules = [
       ./roles
-    ] ++ [
       inputs.home-manager.nixosModules.home-manager
       {
-        nixpkgs.overlays = [
-          (final: prev: {
-            unstable = import nixpkgs-unstable {
-              system = prev.stdenv.hostPlatform.system;
-              config.allowUnfree = true;
-            };
-            custom = prev.callPackage ./packages {};
-            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
-            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
-          })
-        ];
-        home-manager.useGlobalPkgs = true;
-        home-manager.useUserPackages = true;
-        home-manager.sharedModules = [
-          inputs.plasma-manager.homeModules.plasma-manager
-          inputs.nix-doom-emacs-unstraightened.homeModule
-        ];
-        home-manager.extraSpecialArgs = {
-          globalInputs = inputs;
-        };
+        nixpkgs.overlays = [ (mkBaseOverlay { unstableOverlays = customUnstableOverlays; }) ];
       }
+      (mkHomeManagerConfig {
+        sharedModules = [ inputs.plasma-manager.homeModules.plasma-manager ];
+      })
     ];
+
     # Modules for unstable-based systems (like nix-deck)
     nixosModulesUnstable = [
       ./roles
-    ] ++ [
       inputs.home-manager-unstable.nixosModules.home-manager
       inputs.jovian.nixosModules.jovian
       {
-        nixpkgs.overlays = [
-          (final: prev: {
-            unstable = import nixpkgs-unstable {
-              system = prev.stdenv.hostPlatform.system;
-              config.allowUnfree = true;
-            };
-            custom = prev.callPackage ./packages {};
-            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
-            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
-          })
-        ];
-        home-manager.useGlobalPkgs = true;
-        home-manager.useUserPackages = true;
-        home-manager.sharedModules = [
-          inputs.plasma-manager-unstable.homeModules.plasma-manager
-          inputs.nix-doom-emacs-unstraightened.homeModule
-        ];
-        home-manager.extraSpecialArgs = {
-          globalInputs = inputs;
-        };
+        nixpkgs.overlays = [ (mkBaseOverlay { unstableOverlays = customUnstableOverlays; }) ];
       }
+      (mkHomeManagerConfig {
+        sharedModules = [ inputs.plasma-manager-unstable.homeModules.plasma-manager ];
+      })
     ];
+
     darwinModules = [
       ./roles/darwin.nix
-    ] ++ [
       inputs.home-manager.darwinModules.home-manager
       {
-        nixpkgs.overlays = [
-          (final: prev: {
-            unstable = import nixpkgs-unstable {
-              system = prev.stdenv.hostPlatform.system;
-              config.allowUnfree = true;
-              overlays = [
-                # Override claude-code in unstable to use our custom GCS-based build
-                # (needed for corporate networks that block npm registry)
-                (ufinal: uprev: {
-                  claude-code = prev.custom.claude-code or (prev.callPackage ./packages {}).claude-code;
-                })
-              ];
-            };
-            custom = prev.callPackage ./packages {};
-            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
-            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
-          })
-        ];
-        home-manager.useGlobalPkgs = true;
-        home-manager.useUserPackages = true;
-        home-manager.sharedModules = [
-          inputs.nix-doom-emacs-unstraightened.homeModule
-        ];
-        home-manager.extraSpecialArgs = {
-          globalInputs = inputs;
-        };
+        nixpkgs.overlays = [ (mkBaseOverlay { unstableOverlays = customUnstableOverlays; }) ];
       }
+      (mkHomeManagerConfig { sharedModules = []; })
     ];
 
   in {
@@ -176,24 +176,10 @@
       ];
     };
 
-    nixosConfigurations.wixos = nixpkgs.lib.nixosSystem rec {
-      system = "x86_64-linux";
-      modules = nixosModules ++ [
-        nixos-wsl.nixosModules.default
-        ./machines/wixos/configuration.nix
-        inputs.home-manager.nixosModules.home-manager
-        {
-          home-manager.users.johno = import ./home/home-desktop.nix;
-          home-manager.extraSpecialArgs = { inherit system; };
-        }
-      ];
-    };
-
     nixosConfigurations.zix790prors = nixpkgs.lib.nixosSystem rec {
       system = "x86_64-linux";
       modules = nixosModules ++ [
         ./machines/zix790prors/configuration.nix
-        inputs.home-manager.nixosModules.home-manager
         {
           home-manager.users.johno = import ./home/home-desktop.nix;
           home-manager.extraSpecialArgs = { inherit system; };
@@ -239,7 +225,7 @@
     };
 
     # Darwin/macOS configurations
-    darwinConfigurations."blkfv4yf49kt7" = inputs.nix-darwin.lib.darwinSystem rec {
+    darwinConfigurations."BLKFV4YF49KT7" = inputs.nix-darwin.lib.darwinSystem rec {
       system = "aarch64-darwin";
       modules = darwinModules ++ [
         ./machines/johno-macbookpro/configuration.nix
@@ -275,6 +261,16 @@
           export PATH="${pkgs.lib.makeBinPath commonDeps}:$PATH"
           ${builtins.readFile ./scripts/upgrade.sh}
         '';
+
+        bootstrap = pkgs.writeShellScriptBin "bootstrap" ''
+          export PATH="${pkgs.lib.makeBinPath commonDeps}:$PATH"
+          ${builtins.readFile ./scripts/bootstrap.sh}
+        '';
+
+        build-liveusb = pkgs.writeShellScriptBin "build-liveusb" ''
+          export PATH="${pkgs.lib.makeBinPath commonDeps}:$PATH"
+          ${builtins.readFile ./scripts/build-liveusb.sh}
+        '';
       in {
         update-doomemacs = {
           type = "app";
@@ -292,6 +288,14 @@
           type = "app";
           program = "${upgrade}/bin/upgrade";
         };
+        bootstrap = {
+          type = "app";
+          program = "${bootstrap}/bin/bootstrap";
+        };
+        build-liveusb = {
+          type = "app";
+          program = "${build-liveusb}/bin/build-liveusb";
+        };
       }
     );
   };

home/home-darwin-work.nix

@@ -107,7 +107,7 @@
     aerospace = {
       enable = true;
       leader = "cmd";
-      ctrlShortcuts.enable = true;
+      ctrlShortcuts.enable = false;
       sketchybar.enable = true;
       # Optional: Add per-machine userSettings overrides
       # userSettings = {

home/home-desktop.nix

@@ -10,6 +10,7 @@
   home.roles = {
     "3d-printing".enable = true;
     base.enable = true;
+    gaming.enable = true;
     desktop.enable = true;
     emacs.enable = true;
     email.enable = true;

home/home-kodi.nix

@@ -12,6 +12,7 @@
   home.roles = {
     base.enable = true;
     plasma-manager-kodi.enable = true;
+    kdeconnect.enable = true;
   };
 
   home.packages = with pkgs; [
@@ -24,5 +25,6 @@
 
   imports = [
     ./roles
+    ./roles/base-linux
   ];
 }

home/home-laptop-compact.nix

@@ -12,6 +12,7 @@
   home.roles = {
     base.enable = true;
     desktop.enable = true;
+    gaming.enable = true;
     development.enable = true;
     communication.enable = true;
     email.enable = true;

home/home-media-center.nix

@@ -12,6 +12,7 @@
   home.roles = {
     base.enable = true;
     desktop.enable = true;
+    gaming.enable = true;
     media.enable = true;
     communication.enable = true;
     kdeconnect.enable = true;

home/home-server.nix

@@ -11,6 +11,7 @@
     base.enable = true;
     development.enable = true;
     emacs.enable = true;
+    kubectl.enable = true;
     starship.enable = true;
     tmux.enable = true;
   };

home/roles/aerospace/default.nix

@@ -632,7 +632,9 @@ in
       text = ''
         #!/bin/bash
 
-        DISK_USAGE=$(df -H / | grep -v Filesystem | awk '{print $5}')
+        # Monitor /System/Volumes/Data which contains user data on APFS
+        # The root / is a read-only snapshot with minimal usage
+        DISK_USAGE=$(df -H /System/Volumes/Data | grep -v Filesystem | awk '{print $5}')
 
         ${pkgs.sketchybar}/bin/sketchybar --set $NAME label="$DISK_USAGE"
       '';

home/roles/base-linux/default.nix

@@ -3,6 +3,7 @@
   # Includes Linux-specific roles that require Linux-only home-manager modules
   imports = [
     ../plasma-manager
+    ../plasma-manager-kodi
     ../i3+sway
   ];
 }

home/roles/base/default.nix

@@ -22,6 +22,7 @@ in
       shellcheck
       tmux
       tree
+      watch
     ];
 
     # Automatic garbage collection for user profile (home-manager generations).

home/roles/communication/default.nix

@@ -4,6 +4,7 @@ with lib;
 
 let
   cfg = config.home.roles.communication;
+  isLinux = pkgs.stdenv.isLinux;
 in
 {
   options.home.roles.communication = {
@@ -12,14 +13,14 @@ in
 
   config = mkIf cfg.enable {
     home.packages = [
-      # Communication apps
+      # For logging back into google chat (cross-platform)
+      globalInputs.google-cookie-retrieval.packages.${system}.default
+    ] ++ optionals isLinux [
+      # Linux-only communication apps (Electron apps don't build on Darwin)
       pkgs.element-desktop
       # Re-enabled in 25.11 after security issues were resolved
       pkgs.fluffychat
       pkgs.nextcloud-talk-desktop
-      
-      # For logging back into google chat
-      globalInputs.google-cookie-retrieval.packages.${system}.default
     ];
   };
 }

home/roles/default.nix

@@ -15,7 +15,6 @@
     ./launchers
     ./media
     ./office
-    ./plasma-manager-kodi
     ./sync
     ./tmux
     ./emacs

home/roles/desktop/default.nix

@@ -4,6 +4,7 @@ with lib;
 
 let
   cfg = config.home.roles.desktop;
+  isLinux = pkgs.stdenv.isLinux;
 in
 {
   options.home.roles.desktop = {
@@ -12,61 +13,63 @@ in
 
   config = mkIf cfg.enable {
     home.packages = with pkgs; [
-      # Desktop applications
+      # Cross-platform desktop applications
       bitwarden-desktop
-      dunst
       keepassxc
+      xdg-utils # XDG utilities for opening files/URLs with default applications
+    ] ++ optionals isLinux [
+      # Linux-only desktop applications
+      dunst
       unstable.ghostty
-      
-      # Desktop utilities
+
+      # Linux-only desktop utilities
       feh # Image viewer and wallpaper setter for X11
       rofi # Application launcher for X11
       solaar # Logitech management software
       waybar
       wofi # Application launcher for Wayland
-      xdg-utils # XDG utilities for opening files/URLs with default applications
-      
-      # System utilities with GUI components
+
+      # Linux-only system utilities with GUI components
       (snapcast.override { pulseaudioSupport = true; })
-      
-      # KDE tiling window management
+
+      # KDE tiling window management (Linux-only)
       kdePackages.krohnkite  # Dynamic tiling extension for KWin 6
-      
-      # KDE PIM applications for email, calendar, and contacts
+
+      # KDE PIM applications for email, calendar, and contacts (Linux-only)
       kdePackages.kmail
       kdePackages.kmail-account-wizard
       kdePackages.kmailtransport
       kdePackages.korganizer
       kdePackages.kaddressbook
       kdePackages.kontact
-      
-      # KDE System components needed for proper integration
+
+      # KDE System components needed for proper integration (Linux-only)
       kdePackages.kded
       kdePackages.systemsettings
       kdePackages.kmenuedit
-      
-      # Desktop menu support
+
+      # Desktop menu support (Linux-only)
       kdePackages.plasma-desktop # Contains applications.menu
-      
-      # KDE Online Accounts support
+
+      # KDE Online Accounts support (Linux-only)
       kdePackages.kaccounts-integration
       kdePackages.kaccounts-providers
       kdePackages.signond
-      
-      # KDE Mapping
+
+      # KDE Mapping (Linux-only)
       kdePackages.marble  # Virtual globe and world atlas
-      
-      # KDE Productivity
+
+      # KDE Productivity (Linux-only)
       kdePackages.kate        # Advanced text editor with syntax highlighting
       kdePackages.okular      # Universal document viewer (PDF, ePub, etc.)
       kdePackages.spectacle   # Screenshot capture utility
       kdePackages.filelight   # Visual disk usage analyzer
-      
-      # KDE Multimedia
+
+      # KDE Multimedia (Linux-only)
       kdePackages.gwenview    # Image viewer and basic editor
       kdePackages.elisa       # Music player
-      
-      # KDE System Utilities  
+
+      # KDE System Utilities (Linux-only)
       kdePackages.ark         # Archive manager (zip, tar, 7z, etc.)
       kdePackages.yakuake     # Drop-down terminal emulator
     ];
@@ -77,61 +80,66 @@ in
 
     programs.spotify-player.enable = true;
 
-    services.gnome-keyring = {
+    # Linux-only: GNOME keyring service
+    services.gnome-keyring = mkIf isLinux {
       enable = true;
     };
 
-    # rbw vault unlock on login and resume from suspend
-    systemd.user.services.rbw-unlock-on-login = {
-      Unit = {
-        Description = "Unlock rbw vault at login";
-        After = [ "graphical-session.target" ];
+    # Linux-only: systemd user services for rbw vault unlock
+    systemd.user.services = mkIf isLinux {
+      # rbw vault unlock on login
+      rbw-unlock-on-login = {
+        Unit = {
+          Description = "Unlock rbw vault at login";
+          After = [ "graphical-session.target" ];
+        };
+        Service = {
+          Type = "oneshot";
+          ExecStart = "${pkgs.rbw}/bin/rbw unlock";
+          Environment = "RBW_AGENT=${pkgs.rbw}/bin/rbw-agent";
+          # KillMode = "process" prevents systemd from killing the rbw-agent daemon
+          # when this oneshot service completes. The agent is spawned by rbw unlock
+          # and needs to persist after the service exits.
+          KillMode = "process";
+        };
+        Install = {
+          WantedBy = [ "graphical-session.target" ];
+        };
       };
-      Service = {
-        Type = "oneshot";
-        ExecStart = "${pkgs.rbw}/bin/rbw unlock";
-        Environment = "RBW_AGENT=${pkgs.rbw}/bin/rbw-agent";
-        # KillMode = "process" prevents systemd from killing the rbw-agent daemon
-        # when this oneshot service completes. The agent is spawned by rbw unlock
-        # and needs to persist after the service exits.
-        KillMode = "process";
-      };
-      Install = {
-        WantedBy = [ "graphical-session.target" ];
+
+      # rbw vault unlock on resume from suspend
+      rbw-unlock-on-resume = {
+        Unit = {
+          Description = "Unlock rbw vault after resume from suspend";
+          After = [ "suspend.target" ];
+        };
+        Service = {
+          Type = "oneshot";
+          ExecStart = "${pkgs.rbw}/bin/rbw unlock";
+          Environment = "RBW_AGENT=${pkgs.rbw}/bin/rbw-agent";
+          # KillMode = "process" prevents systemd from killing the rbw-agent daemon
+          # when this oneshot service completes. The agent is spawned by rbw unlock
+          # and needs to persist after the service exits.
+          KillMode = "process";
+        };
+        Install = {
+          WantedBy = [ "suspend.target" ];
+        };
       };
     };
 
-    systemd.user.services.rbw-unlock-on-resume = {
-      Unit = {
-        Description = "Unlock rbw vault after resume from suspend";
-        After = [ "suspend.target" ];
-      };
-      Service = {
-        Type = "oneshot";
-        ExecStart = "${pkgs.rbw}/bin/rbw unlock";
-        Environment = "RBW_AGENT=${pkgs.rbw}/bin/rbw-agent";
-        # KillMode = "process" prevents systemd from killing the rbw-agent daemon
-        # when this oneshot service completes. The agent is spawned by rbw unlock
-        # and needs to persist after the service exits.
-        KillMode = "process";
-      };
-      Install = {
-        WantedBy = [ "suspend.target" ];
-      };
-    };
-
-    # KDE environment variables for proper integration
-    home.sessionVariables = {
+    # Linux-only: KDE environment variables for proper integration
+    home.sessionVariables = mkIf isLinux {
       QT_QPA_PLATFORMTHEME = "kde";
       KDE_SESSION_VERSION = "6";
     };
 
     xdg = {
       enable = true;
-      
+
       # Ensure desktop files are made available for discovery
       desktopEntries = {};  # This creates the desktop files directory structure
-      
+
       mimeApps = {
         enable = true;
         associations.added = {
@@ -141,13 +149,14 @@ in
           "x-scheme-handler/https" = "firefox.desktop";
         };
         defaultApplications = {
-          # Web browsers
+          # Web browsers (cross-platform)
           "text/html" = "firefox.desktop";
           "x-scheme-handler/http" = "firefox.desktop";
           "x-scheme-handler/https" = "firefox.desktop";
           "x-scheme-handler/about" = "firefox.desktop";
           "x-scheme-handler/unknown" = "firefox.desktop";
-          
+        } // optionalAttrs isLinux {
+          # Linux-only: KDE application associations
           # Documents
           "application/pdf" = "okular.desktop";
           "text/plain" = "kate.desktop";
@@ -155,7 +164,7 @@ in
           "text/x-c" = "kate.desktop";
           "text/x-python" = "kate.desktop";
           "application/x-shellscript" = "kate.desktop";
-          
+
           # Images
           "image/png" = "gwenview.desktop";
           "image/jpeg" = "gwenview.desktop";
@@ -164,25 +173,25 @@ in
           "image/bmp" = "gwenview.desktop";
           "image/tiff" = "gwenview.desktop";
           "image/webp" = "gwenview.desktop";
-          
+
           # Archives
           "application/zip" = "ark.desktop";
           "application/x-tar" = "ark.desktop";
           "application/x-compressed-tar" = "ark.desktop";
           "application/x-7z-compressed" = "ark.desktop";
           "application/x-rar" = "ark.desktop";
-          
+
           # Audio
           "audio/mpeg" = "elisa.desktop";
           "audio/mp4" = "elisa.desktop";
           "audio/flac" = "elisa.desktop";
           "audio/ogg" = "elisa.desktop";
           "audio/wav" = "elisa.desktop";
-          
+
           # Email
           "message/rfc822" = "kmail.desktop";
           "x-scheme-handler/mailto" = "kmail.desktop";
-          
+
           # Calendar
           "text/calendar" = "korganizer.desktop";
           "application/x-vnd.akonadi.calendar.event" = "korganizer.desktop";
@@ -190,9 +199,11 @@ in
       };
     };
 
-    # Fix for KDE applications.menu file issue on Plasma 6
+    # Linux-only: Fix for KDE applications.menu file issue on Plasma 6
     # KDE still looks for applications.menu but Plasma 6 renamed it to plasma-applications.menu
-    xdg.configFile."menus/applications.menu".source = "${pkgs.kdePackages.plasma-workspace}/etc/xdg/menus/plasma-applications.menu";
+    xdg.configFile."menus/applications.menu" = mkIf isLinux {
+      source = "${pkgs.kdePackages.plasma-workspace}/etc/xdg/menus/plasma-applications.menu";
+    };
 
     # Note: modules must be imported at top-level home config
   };

home/roles/development/beads-search-query-optimization.patch

@@ -0,0 +1,44 @@
+diff --git a/internal/storage/dolt/queries.go b/internal/storage/dolt/queries.go
+index 7d8214ee..8acdaae2 100644
+--- a/internal/storage/dolt/queries.go
++++ b/internal/storage/dolt/queries.go
+@@ -212,8 +212,21 @@ func (s *DoltStore) SearchIssues(ctx context.Context, query string, filter types
+ 	}
+ 
+ 	// nolint:gosec // G201: whereSQL contains column comparisons with ?, limitSQL is a safe integer
++	// Performance fix: SELECT all columns directly instead of id-only + WHERE IN (all_ids)
++	// See: hq-ihwsj - bd list uses inefficient WHERE IN (all_ids) query pattern
+ 	querySQL := fmt.Sprintf(`
+-		SELECT id FROM issues
++		SELECT id, content_hash, title, description, design, acceptance_criteria, notes,
++		       status, priority, issue_type, assignee, estimated_minutes,
++		       created_at, created_by, owner, updated_at, closed_at, external_ref,
++		       compaction_level, compacted_at, compacted_at_commit, original_size, source_repo, close_reason,
++		       deleted_at, deleted_by, delete_reason, original_type,
++		       sender, ephemeral, pinned, is_template, crystallizes,
++		       await_type, await_id, timeout_ns, waiters,
++		       hook_bead, role_bead, agent_state, last_activity, role_type, rig, mol_type,
++		       event_kind, actor, target, payload,
++		       due_at, defer_until,
++		       quality_score, work_type, source_system
++		FROM issues
+ 		%s
+ 		ORDER BY priority ASC, created_at DESC
+ 		%s
+@@ -225,7 +238,15 @@ func (s *DoltStore) SearchIssues(ctx context.Context, query string, filter types
+ 	}
+ 	defer rows.Close()
+ 
+-	return s.scanIssueIDs(ctx, rows)
++	var issues []*types.Issue
++	for rows.Next() {
++		issue, err := scanIssueRow(rows)
++		if err != nil {
++			return nil, err
++		}
++		issues = append(issues, issue)
++	}
++	return issues, rows.Err()
+ }
+ 
+ // GetReadyWork returns issues that are ready to work on (not blocked)

home/roles/development/commands/beads_batch_research_plan.md

@@ -0,0 +1,317 @@
+---
+description: Batch research and planning for multiple beads with interactive question review
+model: opus
+---
+
+# Beads Batch Research+Plan
+
+This skill automates the common workflow of:
+1. Running /beads_research in parallel for multiple beads
+2. Presenting open questions interactively for user input (bead-by-bead)
+3. Running /beads_plan for all researched beads (plus any spawned from splits)
+
+## When to Use
+
+- You have multiple beads ready for work
+- You want to research and plan them efficiently before implementation
+- You prefer to batch your question-answering rather than context-switching between skills
+
+## Phase 1: Selection
+
+1. **Get ready beads**: Run `bd ready --limit=20` to list beads with no blockers
+
+2. **Filter already-researched beads**:
+   For each ready bead, check if it already has research:
+   ```bash
+   ls thoughts/beads-{bead-id}/research.md 2>/dev/null
+   ```
+
+   Categorize beads:
+   - **Needs research**: No `research.md` exists
+   - **Has research, needs plan**: `research.md` exists but no `plan.md`
+   - **Already planned**: Both `research.md` and `plan.md` exist
+
+3. **Present selection**:
+   ```
+   Ready beads available for batch research+plan:
+
+   NEEDS RESEARCH:
+   - {bead-id}: {title} (type: {type})
+   - ...
+
+   HAS RESEARCH (plan only):
+   - {bead-id}: {title} (type: {type})
+   - ...
+
+   ALREADY PLANNED (skip):
+   - {bead-id}: {title}
+
+   Which beads would you like to process?
+   ```
+
+4. **Use AskUserQuestion** with `multiSelect: true`:
+   - Include bead ID and title for each option
+   - Separate options by category
+   - Allow selection across categories
+
+## Phase 2: Parallel Research
+
+For each selected bead that NEEDS RESEARCH, launch a research subagent.
+
+### Subagent Instructions Template
+
+```
+Research bead [BEAD_ID]: [BEAD_TITLE]
+
+1. **Load bead context**:
+   ```bash
+   bd show [BEAD_ID]
+   ```
+
+2. **Create artifact directory**:
+   ```bash
+   mkdir -p thoughts/beads-[BEAD_ID]
+   ```
+
+3. **Conduct research** following beads_research.md patterns:
+   - Analyze and decompose the research question
+   - Spawn parallel sub-agent tasks (codebase-locator, codebase-analyzer, etc.)
+   - Synthesize findings
+
+4. **Write research document** to `thoughts/beads-[BEAD_ID]/research.md`:
+   - Include frontmatter with metadata
+   - Document findings with file:line references
+   - **CRITICAL**: Include "## Open Questions" section listing any unresolved items
+
+5. **Return summary**:
+   - Research status (complete/partial)
+   - Number of open questions
+   - Key findings summary (2-3 bullet points)
+   - List of open questions verbatim
+```
+
+### Launching Subagents
+
+Use `subagent_type: "opus"` for research subagents (matches beads_research model setting).
+
+Launch ALL research subagents in a single message for parallel execution:
+```
+<Task calls for each selected bead needing research - all in one message>
+```
+
+### Collecting Results
+
+Wait for ALL research subagents to complete. Collect:
+- Bead ID
+- Research status
+- Open questions list
+- Any errors encountered
+
+## Phase 3: Interactive Question Review
+
+Present each bead's open questions sequentially for user input.
+
+### For Each Bead (in order):
+
+1. **Present research summary**:
+   ```
+   ## Bead {N}/{total}: {bead-id} - {title}
+
+   Research complete. Key findings:
+   - {finding 1}
+   - {finding 2}
+
+   Open questions requiring your input:
+   1. {question 1}
+   2. {question 2}
+
+   Additionally:
+   - Should this bead be split into multiple beads? (y/n)
+   - If split, describe the split:
+   ```
+
+2. **Collect user responses**:
+   - Answers to open questions
+   - Split decision (yes/no)
+   - If split: new bead titles and how to divide the work
+
+3. **Handle splits**:
+   If user indicates a split:
+   ```bash
+   # Create new beads for split work
+   bd create --title="{split title 1}" --type={type} --priority={priority} \
+     --description="{description based on user input}"
+
+   # Update original bead if scope narrowed
+   bd update {original-bead-id} --description="{updated description}"
+   ```
+
+   Track new bead IDs for inclusion in planning phase.
+
+4. **Update research document**:
+   Append user answers to `thoughts/beads-{id}/research.md`:
+   ```markdown
+   ## User Clarifications [{timestamp}]
+
+   Q: {question 1}
+   A: {user answer 1}
+
+   Q: {question 2}
+   A: {user answer 2}
+
+   ## Bead Splits
+   {If split: description of split and new bead IDs}
+   ```
+
+### Progress Tracking
+
+After each bead's questions are answered, confirm before moving to next:
+```
+Questions answered for {bead-id}. {N-1} beads remaining.
+Continue to next bead? (y/n)
+```
+
+### Beads with No Questions
+
+If a bead's research had no open questions:
+```
+## Bead {N}/{total}: {bead-id} - {title}
+
+Research complete with no open questions.
+
+Key findings:
+- {finding 1}
+- {finding 2}
+
+Should this bead be split? (y/n)
+```
+
+## Phase 4: Parallel Planning
+
+After all questions answered, launch planning subagents for all beads.
+
+### Beads to Plan
+
+Include:
+- Original beads that were researched
+- Beads that had existing research (from selection phase)
+- New beads spawned from splits
+
+### Subagent Instructions Template
+
+```
+Create implementation plan for bead [BEAD_ID]: [BEAD_TITLE]
+
+1. **Load context**:
+   ```bash
+   bd show [BEAD_ID]
+   ```
+
+2. **Read research** (it exists and has user clarifications):
+   Read `thoughts/beads-[BEAD_ID]/research.md` FULLY
+
+3. **Create plan** following beads_plan.md patterns:
+   - Context gathering via sub-agents
+   - Design approach based on research findings and user clarifications
+   - **Skip interactive questions** - they were already answered in research review
+
+4. **Write plan** to `thoughts/beads-[BEAD_ID]/plan.md`:
+   - Full plan structure with phases
+   - Success criteria (automated and manual)
+   - References to research document
+
+5. **Update bead**:
+   ```bash
+   bd update [BEAD_ID] --notes="Plan created: thoughts/beads-[BEAD_ID]/plan.md"
+   ```
+
+6. **Return summary**:
+   - Plan status (complete/failed)
+   - Number of phases
+   - Estimated complexity (small/medium/large)
+   - Any issues encountered
+```
+
+### Launching Subagents
+
+Use `subagent_type: "opus"` for planning subagents (matches beads_plan model setting).
+
+Launch ALL planning subagents in a single message:
+```
+<Task calls for each bead to plan - all in one message>
+```
+
+### Handling Beads Without Research
+
+For beads that had existing research but user didn't review questions:
+- Planning subagent reads existing research
+- If research has unresolved open questions, subagent should flag this in its return
+
+## Phase 5: Summary
+
+After all planning completes, present final summary.
+
+### Summary Format
+
+```
+## Batch Research+Plan Complete
+
+### Successfully Processed:
+| Bead | Title | Research | Plan | Phases | Complexity |
+|------|-------|----------|------|--------|------------|
+| {id} | {title} | Complete | Complete | 3 | medium |
+| {id} | {title} | Complete | Complete | 2 | small |
+
+### New Beads (from splits):
+| Bead | Title | Parent | Status |
+|------|-------|--------|--------|
+| {new-id} | {title} | {parent-id} | Planned |
+
+### Failed:
+| Bead | Title | Phase Failed | Error |
+|------|-------|--------------|-------|
+| {id} | {title} | Research | Timeout |
+
+### Next Steps:
+1. Review plans at `thoughts/beads-{id}/plan.md`
+2. Run `/parallel_beads` to implement all planned beads
+3. Or run `/beads_implement {id}` for individual implementation
+
+### Artifacts Created:
+- Research: thoughts/beads-{id}/research.md (x{N} files)
+- Plans: thoughts/beads-{id}/plan.md (x{N} files)
+```
+
+## Error Handling
+
+### Research Subagent Failure
+- Log the failure with bead ID and error
+- Continue with other beads
+- Exclude failed beads from question review and planning
+- Report in final summary
+
+### Planning Subagent Failure
+- Log the failure with bead ID and error
+- Research still valid - can retry planning manually
+- Report in final summary
+
+### User Cancellation During Question Review
+- Save progress to bead notes
+- Report which beads were completed
+- User can resume with remaining beads in new session
+
+### Split Bead Creation Failure
+- Report error but continue with original bead
+- User can manually create split beads later
+
+## Resource Limits
+
+- Maximum concurrent research subagents: 5
+- Maximum concurrent planning subagents: 5
+- If more beads selected, process in batches
+
+## Notes
+
+- This skill is designed for the "research+plan before implementation" workflow
+- Pairs well with `/parallel_beads` for subsequent implementation
+- Run `/reconcile_beads` after implementation PRs merge

home/roles/development/commands/beads_implement.md

@@ -0,0 +1,253 @@
+---
+description: Implement a plan from thoughts/ for a bead issue
+---
+
+# Beads Implement
+
+You are tasked with implementing an approved plan for a bead issue. Plans are stored in `thoughts/beads-{id}/plan.md`.
+
+## Initial Setup
+
+When this command is invoked:
+
+1. **Parse the input for bead ID**:
+   - If a bead ID is provided, use it
+   - If no bead ID, check for beads with plans:
+     ```bash
+     bd list --status=in_progress
+     ```
+     Then check which have plans in `thoughts/beads-{id}/plan.md`
+
+2. **Load bead context**:
+   ```bash
+   bd show {bead-id}
+   ```
+   Note the bead **type** (bug, feature, task) from the output.
+
+3. **Check for plan and handle by type**:
+
+   Check if plan exists:
+   ```bash
+   ls thoughts/beads-{bead-id}/plan.md 2>/dev/null
+   ```
+
+   **If plan exists**: Proceed normally (skip to step 4)
+
+   **If no plan**:
+   - **type=bug**: Proceed without plan (simple bugs can implement directly)
+   - **type=feature or type=task**: Warn and ask:
+     ```
+     No plan found for this {type}.
+
+     Plans help ensure complex work is well-designed and verifiable.
+     Location expected: thoughts/beads-{bead-id}/plan.md
+
+     Options:
+     1. Create a plan first (recommended) - Run /beads_plan {bead-id}
+     2. Proceed without a plan (for simple changes)
+
+     How would you like to proceed?
+     ```
+     Wait for user response before continuing.
+
+4. **Load plan and research context** (if plan exists):
+   - Read `thoughts/beads-{bead-id}/plan.md` FULLY
+   - Check for any existing checkmarks (- [x]) indicating partial progress
+   - Read any research at `thoughts/beads-{bead-id}/research.md`
+   - If plan's Success Criteria references contribution guidelines (e.g., "Per CONTRIBUTING.md:"),
+     verify the original CONTRIBUTING.md still exists and requirements are current
+
+5. **Mark bead in progress** (if not already):
+   ```bash
+   bd update {bead-id} --status=in_progress
+   ```
+
+6. **Respond with**:
+   ```
+   Implementing plan for bead {bead-id}: {bead-title}
+
+   Plan location: thoughts/beads-{bead-id}/plan.md
+   {If partial progress: "Resuming from Phase X - previous phases completed."}
+
+   I'll implement each phase and verify success criteria before proceeding.
+   ```
+
+## Implementation Process
+
+### Step 1: Understand the Plan
+
+1. **Read the plan completely**
+2. **Check for existing progress** (checkmarked items)
+3. **Read all files mentioned in the plan**
+4. **Create a TodoWrite list** tracking each phase
+
+### Step 2: Implement Each Phase
+
+For each phase in the plan:
+
+1. **Announce the phase**:
+   ```
+   ## Starting Phase {N}: {Phase Name}
+
+   This phase will: {overview from plan}
+   ```
+
+2. **Make the changes**:
+   - Follow the plan's specific instructions
+   - Use Edit tool for modifications
+   - Create new files only when specified
+
+3. **Run automated verification**:
+   - Execute each command in "Automated Verification"
+   - Fix any issues before proceeding
+
+4. **Update plan checkboxes**:
+   - Use Edit tool to check off completed items in the plan
+   - This enables resume if session is interrupted
+
+5. **Update bead notes** with progress:
+   ```bash
+   bd update {bead-id} --notes="Phase {N} complete. Automated verification passed."
+   ```
+
+### Step 3: Per-Plan Checkpoint
+
+**CRITICAL**: After completing ALL phases and ALL automated verification:
+
+```
+## Implementation Complete - Ready for Manual Verification
+
+All phases completed and automated verification passed:
+- [ ] Phase 1: {name} - DONE
+- [ ] Phase 2: {name} - DONE
+- [ ] ...
+
+**Automated checks passed:**
+- {List of automated checks that passed}
+
+**Please perform manual verification:**
+- {List manual verification items from plan}
+
+Let me know when manual testing is complete so I can close the bead.
+
+**Contribution guidelines compliance:**
+- {List any contribution guideline requirements that were part of Success Criteria}
+- {Note if any requirements could not be automated and need manual review}
+```
+
+**STOP HERE and wait for user confirmation.**
+
+Do NOT:
+- Close the bead automatically
+- Proceed to "next steps" without confirmation
+- Start additional work
+
+### Step 4: After Manual Verification
+
+When user confirms manual verification passed:
+
+1. **Update plan status**:
+   - Edit the plan's frontmatter: `status: complete`
+
+2. **Close the bead**:
+   ```bash
+   bd close {bead-id} --reason="Implementation complete. All verification passed."
+   ```
+
+3. **Final summary**:
+   ```
+   Bead {bead-id} closed.
+
+   Summary:
+   - {What was implemented}
+   - {Key changes made}
+
+   Artifacts:
+   - Plan: thoughts/beads-{bead-id}/plan.md
+   - {Any other artifacts created}
+   ```
+
+## Handling Issues
+
+### When something doesn't match the plan:
+
+```
+Issue in Phase {N}:
+
+Expected: {what the plan says}
+Found: {actual situation}
+Why this matters: {explanation}
+
+Options:
+1. Adapt the implementation to work with current state
+2. Update the plan to reflect reality
+3. Stop and investigate further
+
+How should I proceed?
+```
+
+### When tests fail:
+
+1. **Analyze the failure**
+2. **Attempt to fix** if the fix is clear and within scope
+3. **If fix is unclear**, report:
+   ```
+   Test failure in Phase {N}:
+
+   Failing test: {test name}
+   Error: {error message}
+
+   I've attempted: {what you tried}
+
+   This may require: {your assessment}
+   ```
+
+### When blocked:
+
+```
+Blocked in Phase {N}:
+
+Blocker: {description}
+Impact: {what can't proceed}
+
+Suggested resolution: {your recommendation}
+```
+
+## Resuming Work
+
+If the plan has existing checkmarks:
+
+1. **Trust completed work** - don't re-verify unless something seems off
+2. **Pick up from first unchecked item**
+3. **Verify previous work only if** current phase depends on it and seems broken
+
+## Important Guidelines
+
+1. **Follow the plan's intent** while adapting to reality
+2. **Implement each phase fully** before moving to next
+3. **Update checkboxes in real-time** as you complete items
+4. **One checkpoint per plan** - not per phase
+5. **Never close bead** without manual verification confirmation
+6. **Keep bead notes updated** with progress
+
+## Session Close Protocol
+
+If you need to end the session before completion:
+
+1. **Update plan** with current progress (checkboxes)
+2. **Update bead notes**:
+   ```bash
+   bd update {bead-id} --notes="In progress: Phase {N} partially complete. Next: {what's next}"
+   ```
+3. **Inform user** of status and how to resume
+
+## Example Invocation
+
+```
+User: /beads:implement nixos-configs-abc123
+Assistant: Implementing plan for bead nixos-configs-abc123...
+
+## Starting Phase 1: Database Schema
+
+This phase will add the new user_preferences table...
+```

home/roles/development/commands/beads_iterate.md

@@ -0,0 +1,214 @@
+---
+description: Iterate on existing implementation plans for a bead issue
+model: opus
+---
+
+# Beads Iterate
+
+You are tasked with updating existing implementation plans based on feedback. Plans are stored in `thoughts/beads-{id}/plan.md`.
+
+## Initial Setup
+
+When this command is invoked:
+
+1. **Parse the input**:
+   - Bead ID (required or ask for it)
+   - Requested changes/feedback (can be provided with command or after)
+
+2. **Handle different scenarios**:
+
+   **No bead ID provided**:
+   ```
+   Which bead's plan would you like to iterate on?
+
+   Recent beads with plans:
+   {list beads that have thoughts/beads-{id}/plan.md}
+   ```
+
+   **Bead ID but no feedback**:
+   ```
+   I've found the plan at thoughts/beads-{bead-id}/plan.md
+
+   What changes would you like to make? For example:
+   - "Add a phase for migration handling"
+   - "Update success criteria to include performance tests"
+   - "Adjust scope to exclude feature X"
+   - "Split Phase 2 into two separate phases"
+   ```
+
+   **Both bead ID and feedback provided**:
+   - Proceed immediately to Step 1
+
+## Iteration Process
+
+### Step 1: Understand Current Plan
+
+1. **Read the existing plan COMPLETELY**:
+   ```bash
+   cat thoughts/beads-{bead-id}/plan.md
+   ```
+   - Understand current structure, phases, scope
+   - Note success criteria and approach
+
+2. **Read the bead for context**:
+   ```bash
+   bd show {bead-id}
+   ```
+
+3. **Understand requested changes**:
+   - Parse what user wants to add/modify/remove
+   - Identify if changes require codebase research
+
+### Step 2: Research If Needed
+
+**Only if changes require new technical understanding:**
+
+1. **Spawn parallel research tasks**:
+   - **codebase-locator**: Find relevant files
+   - **codebase-analyzer**: Understand implementation details
+   - **codebase-pattern-finder**: Find similar patterns
+
+2. **Be specific about directories** in prompts
+
+3. **Wait for ALL tasks** before proceeding
+
+### Step 3: Present Understanding
+
+Before making changes:
+
+```
+Based on your feedback, I understand you want to:
+- {Change 1 with specific detail}
+- {Change 2 with specific detail}
+
+{If research was needed:}
+My research found:
+- {Relevant discovery}
+- {Important constraint}
+
+I plan to update the plan by:
+1. {Specific modification}
+2. {Another modification}
+
+Does this align with your intent?
+```
+
+Get user confirmation before proceeding.
+
+### Step 4: Update the Plan
+
+1. **Make focused, precise edits**:
+   - Use Edit tool for surgical changes
+   - Maintain existing structure unless explicitly changing it
+   - Keep file:line references accurate
+
+2. **Ensure consistency**:
+   - New phases follow existing pattern
+   - Update "What We're NOT Doing" if scope changes
+   - Maintain automated vs manual success criteria distinction
+
+3. **Update plan metadata**:
+   - Update frontmatter `date` to current timestamp
+   - Add `iteration: {N}` to frontmatter
+   - Add `iteration_reason: "{brief description}"` to frontmatter
+
+4. **Preserve completed work**:
+   - Don't uncheck items that were already completed
+   - If changing completed phases, discuss with user first
+
+### Step 5: Save Iteration History (Optional)
+
+For significant changes, save the previous version:
+
+```bash
+cp thoughts/beads-{bead-id}/plan.md thoughts/beads-{bead-id}/plan-v{N}.md
+```
+
+Then update the main plan.
+
+### Step 6: Update Bead
+
+```bash
+bd update {bead-id} --notes="Plan iterated: {brief description of changes}"
+```
+
+### Step 7: Present Changes
+
+```
+I've updated the plan at `thoughts/beads-{bead-id}/plan.md`
+
+Changes made:
+- {Specific change 1}
+- {Specific change 2}
+
+The updated plan now:
+- {Key improvement}
+- {Another improvement}
+
+Would you like any further adjustments?
+```
+
+## Important Guidelines
+
+1. **Be Skeptical**:
+   - Don't blindly accept changes that seem problematic
+   - Question vague feedback - ask for clarification
+   - Point out conflicts with existing phases
+
+2. **Be Surgical**:
+   - Make precise edits, not wholesale rewrites
+   - Preserve good content that doesn't need changing
+   - Only research what's necessary
+
+3. **Be Thorough**:
+   - Read entire plan before making changes
+   - Ensure updated sections maintain quality
+   - Verify success criteria are still measurable
+
+4. **Be Interactive**:
+   - Confirm understanding before making changes
+   - Allow course corrections
+   - Don't disappear into research without communicating
+
+5. **No Open Questions**:
+   - If changes raise questions, ASK
+   - Don't update plan with unresolved questions
+
+## Success Criteria Guidelines
+
+When updating success criteria, maintain two categories:
+
+**Automated Verification**:
+- Commands: `make test`, `npm run lint`
+- Prefer `make` commands when available
+- File existence checks
+
+**Manual Verification**:
+- UI/UX functionality
+- Performance under real conditions
+- Edge cases hard to automate
+
+## Handling Major Changes
+
+If feedback requires significant restructuring:
+
+1. **Discuss scope** before proceeding
+2. **Consider if this should be a new plan** instead of iteration
+3. **Preserve the original** in `plan-v{N}.md`
+4. **Update bead description** if scope changed significantly
+
+## Example Invocations
+
+**With full context**:
+```
+User: /beads:iterate nixos-configs-abc123 - add error handling phase
+Assistant: Based on your feedback, I understand you want to add a new phase for error handling...
+```
+
+**Interactive**:
+```
+User: /beads:iterate nixos-configs-abc123
+Assistant: I've found the plan. What changes would you like to make?
+User: Split Phase 2 into backend and frontend phases
+Assistant: I'll split Phase 2 into two separate phases...
+```

home/roles/development/commands/beads_plan.md

@@ -0,0 +1,306 @@
+---
+description: Create detailed implementation plans for a bead issue
+model: opus
+---
+
+# Beads Plan
+
+You are tasked with creating detailed implementation plans for a bead issue. This skill integrates with the beads issue tracker and stores plans in the `thoughts/` directory.
+
+## Initial Setup
+
+When this command is invoked:
+
+1. **Parse the input for bead ID**:
+   - If a bead ID is provided, use it
+   - If no bead ID, run `bd ready` and ask which bead to plan for
+
+2. **Load bead context**:
+   ```bash
+   bd show {bead-id}
+   ```
+   - Read the bead description for requirements
+   - Check for existing research: `thoughts/beads-{bead-id}/research.md`
+   - Note any dependencies or blockers
+
+3. **Create artifact directory**:
+   ```bash
+   mkdir -p thoughts/beads-{bead-id}
+   ```
+
+4. **Check for existing research**:
+   - If `thoughts/beads-{bead-id}/research.md` exists, read it fully
+   - This research provides crucial context for planning
+
+5. **Respond with**:
+   ```
+   Creating implementation plan for bead {bead-id}: {bead-title}
+
+   {If research exists: "Found existing research at thoughts/beads-{bead-id}/research.md - incorporating findings."}
+
+   Let me analyze the requirements and codebase to create a detailed plan.
+   ```
+
+## Planning Process
+
+### Step 1: Context Gathering
+
+1. **Read all mentioned files FULLY**:
+   - Bead description references
+   - Existing research document
+   - Any linked tickets or docs
+   - Use Read tool WITHOUT limit/offset
+
+2. **Check for contribution guidelines**:
+
+   ```bash
+   # Check standard locations for contribution guidelines
+   for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do
+     if [ -f "$f" ]; then
+       echo "Found: $f"
+       break
+     fi
+   done
+   ```
+
+   If found:
+   - Read the file fully
+   - Extract actionable requirements (testing, code style, documentation, PR conventions)
+   - These requirements MUST be incorporated into the plan's Success Criteria
+
+   If not found, note "No contribution guidelines found" and proceed.
+
+3. **Spawn initial research tasks**:
+   - **codebase-locator**: Find all files related to the task
+   - **codebase-analyzer**: Understand current implementation
+   - **codebase-pattern-finder**: Find similar features to model after
+   - **thoughts-locator**: Find any existing plans or decisions
+
+4. **Read all files identified by research**:
+   - Read them FULLY into main context
+   - Cross-reference with requirements
+
+### Step 2: Present Understanding
+
+Before writing the plan, confirm understanding:
+
+```
+Based on the bead and my research, I understand we need to [accurate summary].
+
+I've found that:
+- [Current implementation detail with file:line reference]
+- [Relevant pattern or constraint discovered]
+- [Potential complexity or edge case identified]
+
+Questions that my research couldn't answer:
+- [Specific technical question requiring human judgment]
+- [Business logic clarification]
+```
+
+Only ask questions you genuinely cannot answer through code investigation.
+
+### Step 3: Research & Discovery
+
+After getting clarifications:
+
+1. **If user corrects any misunderstanding**:
+   - Spawn new research tasks to verify
+   - Read specific files/directories mentioned
+   - Only proceed once verified
+
+2. **Present design options**:
+   ```
+   Based on my research:
+
+   **Current State:**
+   - [Key discovery about existing code]
+   - [Pattern or convention to follow]
+
+   **Design Options:**
+   1. [Option A] - [pros/cons]
+   2. [Option B] - [pros/cons]
+
+   Which approach aligns best?
+   ```
+
+### Step 4: Plan Structure
+
+Once aligned on approach:
+
+```
+Here's my proposed plan structure:
+
+## Overview
+[1-2 sentence summary]
+
+## Implementation Phases:
+1. [Phase name] - [what it accomplishes]
+2. [Phase name] - [what it accomplishes]
+
+Does this phasing make sense?
+```
+
+Get feedback on structure before writing details.
+
+### Step 5: Write the Plan
+
+Write to `thoughts/beads-{bead-id}/plan.md`:
+
+```markdown
+---
+date: {ISO timestamp}
+bead_id: {bead-id}
+bead_title: "{bead title}"
+author: claude
+git_commit: {commit hash}
+branch: {branch name}
+repository: {repo name}
+status: draft
+---
+
+# {Feature/Task Name} Implementation Plan
+
+## Overview
+
+{Brief description of what we're implementing and why}
+
+## Current State Analysis
+
+{What exists now, what's missing, key constraints}
+
+### Key Discoveries:
+- {Finding with file:line reference}
+- {Pattern to follow}
+
+## Desired End State
+
+{Specification of desired end state and how to verify it}
+
+## What We're NOT Doing
+
+{Explicitly list out-of-scope items}
+
+## Implementation Approach
+
+{High-level strategy and reasoning}
+
+## Phase 1: {Descriptive Name}
+
+### Overview
+{What this phase accomplishes}
+
+### Changes Required:
+
+#### 1. {Component/File Group}
+**File**: `path/to/file.ext`
+**Changes**: {Summary}
+
+```{language}
+// Specific code to add/modify
+```
+
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Tests pass: `make test`
+- [ ] Linting passes: `make lint`
+- [ ] Type checking passes: `make typecheck`
+
+#### Manual Verification:
+- [ ] Feature works as expected in UI
+- [ ] Edge cases handled correctly
+
+---
+
+## Phase 2: {Descriptive Name}
+{Similar structure...}
+
+---
+
+## Testing Strategy
+
+### Unit Tests:
+- {What to test}
+- {Key edge cases}
+
+### Integration Tests:
+- {End-to-end scenarios}
+
+### Manual Testing Steps:
+1. {Specific step}
+2. {Another step}
+
+## References
+
+- Bead: {bead-id}
+- Research: `thoughts/beads-{bead-id}/research.md`
+- Similar implementation: {file:line}
+```
+
+### Step 6: Update the bead
+
+```bash
+bd update {bead-id} --notes="Plan created: thoughts/beads-{bead-id}/plan.md"
+```
+
+### Step 7: Create implementation bead (if appropriate)
+
+If the planning bead is separate from implementation:
+
+```bash
+bd create --title="Implement: {feature name}" --type=task --priority=1 \
+  --description="Implement the plan at thoughts/beads-{original-bead-id}/plan.md
+
+See bead {original-bead-id} for planning context."
+
+# Link as dependency
+bd dep add {new-bead-id} {original-bead-id}
+```
+
+### Step 8: Present for Review
+
+```
+I've created the implementation plan at:
+`thoughts/beads-{bead-id}/plan.md`
+
+Please review it and let me know:
+- Are the phases properly scoped?
+- Are the success criteria specific enough?
+- Any technical details that need adjustment?
+- Missing edge cases or considerations?
+```
+
+## Important Guidelines
+
+1. **Be Skeptical**: Question vague requirements, identify potential issues early
+2. **Be Interactive**: Don't write the full plan in one shot, get buy-in at each step
+3. **Be Thorough**: Read all context files COMPLETELY, include specific file:line refs
+4. **Be Practical**: Focus on incremental, testable changes
+5. **No Open Questions**: If you have unresolved questions, STOP and ask
+
+## Success Criteria Guidelines
+
+Always separate into two categories:
+
+**Automated Verification** (run by agents):
+- Commands: `make test`, `npm run lint`, etc.
+- File existence checks
+- Type checking
+
+**Manual Verification** (requires human):
+- UI/UX functionality
+- Performance under real conditions
+- Edge cases hard to automate
+
+**From Contribution Guidelines** (if CONTRIBUTING.md exists):
+- Include any testing requirements specified in guidelines
+- Include any code style/linting requirements
+- Include any documentation requirements
+- Reference the guideline: "Per CONTRIBUTING.md: {requirement}"
+
+## Example Invocation
+
+```
+User: /beads:plan nixos-configs-abc123
+Assistant: Creating implementation plan for bead nixos-configs-abc123...
+```

home/roles/development/commands/beads_research.md

@@ -0,0 +1,222 @@
+---
+description: Research a bead topic comprehensively and store findings in thoughts/
+model: opus
+---
+
+# Beads Research
+
+You are tasked with conducting comprehensive research for a bead issue. This skill integrates with the beads issue tracker and stores findings in the `thoughts/` directory.
+
+## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
+- DO NOT suggest improvements or changes unless the user explicitly asks for them
+- DO NOT perform root cause analysis unless the user explicitly asks for them
+- DO NOT propose future enhancements unless the user explicitly asks for them
+- DO NOT critique the implementation or identify problems
+- ONLY describe what exists, where it exists, how it works, and how components interact
+- You are creating a technical map/documentation of the existing system
+
+## Initial Setup
+
+When this command is invoked:
+
+1. **Parse the input for bead ID**:
+   - If a bead ID is provided (e.g., `nixos-configs-abc123`), use it
+   - If no bead ID provided, run `bd ready --type=research` to find research beads, or ask which bead to research
+
+2. **Load bead context**:
+   ```bash
+   bd show {bead-id}
+   ```
+   - Read the bead description to understand the research question
+   - Note any linked files or references in the bead
+
+3. **Create artifact directory**:
+   ```bash
+   mkdir -p thoughts/beads-{bead-id}
+   ```
+
+4. **Respond with**:
+   ```
+   Starting research for bead {bead-id}: {bead-title}
+
+   Research question: {extracted from bead description}
+
+   I'll analyze this thoroughly and store findings in thoughts/beads-{bead-id}/research.md
+   ```
+
+## Research Process
+
+### Step 1: Read any directly mentioned files
+- If the bead or user mentions specific files, read them FULLY first
+- Use the Read tool WITHOUT limit/offset parameters
+- Read these files yourself in the main context before spawning sub-tasks
+
+### Step 1.5: Check for contribution guidelines
+
+Before spawning sub-agents, check if the repository has contribution guidelines:
+
+```bash
+for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do
+  if [ -f "$f" ]; then echo "Found: $f"; break; fi
+done
+```
+
+If found, read the file and note key requirements. These should be included in the research document under a "## Contribution Guidelines" section if relevant to the research question.
+
+### Step 2: Analyze and decompose the research question
+- Break down the query into composable research areas
+- Identify specific components, patterns, or concepts to investigate
+- Create a research plan using TodoWrite
+- Consider which directories, files, or patterns are relevant
+
+### Step 3: Spawn parallel sub-agent tasks
+
+Use specialized agents for research:
+
+**For codebase research:**
+- **codebase-locator** - Find WHERE files and components live
+- **codebase-analyzer** - Understand HOW specific code works
+- **codebase-pattern-finder** - Find examples of existing patterns
+
+**For thoughts directory:**
+- **thoughts-locator** - Discover what documents exist about the topic
+- **thoughts-analyzer** - Extract key insights from specific documents
+
+**For web research (only if explicitly requested):**
+- **web-search-researcher** - External documentation and resources
+
+Key principles:
+- Run multiple agents in parallel when searching for different things
+- Each agent knows its job - tell it what you're looking for, not HOW to search
+- Remind agents they are documenting, not evaluating
+
+### Step 4: Synthesize findings
+
+Wait for ALL sub-agents to complete, then:
+- Compile all results (codebase and thoughts findings)
+- Prioritize live codebase findings as primary source of truth
+- Connect findings across different components
+- Include specific file paths and line numbers
+- Highlight patterns, connections, and architectural decisions
+
+### Step 5: Gather metadata
+
+```bash
+# Git metadata
+git rev-parse HEAD                    # Current commit
+git branch --show-current             # Current branch
+basename $(git rev-parse --show-toplevel)  # Repo name
+date -Iseconds                        # Current timestamp
+```
+
+### Step 6: Write research document
+
+Write to `thoughts/beads-{bead-id}/research.md`:
+
+```markdown
+---
+date: {ISO timestamp with timezone}
+bead_id: {bead-id}
+bead_title: "{bead title}"
+researcher: claude
+git_commit: {commit hash}
+branch: {branch name}
+repository: {repo name}
+status: complete
+---
+
+# Research: {bead title}
+
+**Bead**: {bead-id}
+**Date**: {timestamp}
+**Git Commit**: {commit hash}
+**Branch**: {branch name}
+
+## Research Question
+{Original question from bead description}
+
+## Summary
+{High-level documentation answering the research question}
+
+## Detailed Findings
+
+### {Component/Area 1}
+- Description of what exists (file.ext:line)
+- How it connects to other components
+- Current implementation details
+
+### {Component/Area 2}
+...
+
+## Code References
+- `path/to/file.py:123` - Description
+- `another/file.ts:45-67` - Description
+
+## Architecture Documentation
+{Current patterns, conventions found in codebase}
+
+## Contribution Guidelines
+{If CONTRIBUTING.md exists, summarize key requirements relevant to the research topic}
+{If no guidelines found, omit this section}
+
+## Historical Context (from thoughts/)
+{Relevant insights from thoughts/ with references}
+
+## Open Questions
+{Any areas needing further investigation}
+```
+
+### Step 7: Update the bead
+
+```bash
+# Add artifact link to bead notes
+bd update {bead-id} --notes="Research complete: thoughts/beads-{bead-id}/research.md"
+```
+
+### Step 8: Autonomy decision
+
+**For research beads (type=research):**
+- If research is complete and comprehensive, close the bead:
+  ```bash
+  bd close {bead-id} --reason="Research complete. See thoughts/beads-{bead-id}/research.md"
+  ```
+- Present summary to user
+
+**For other bead types:**
+- Do NOT close the bead
+- Present findings and ask how to proceed
+
+### Step 9: Handle follow-up questions
+
+If the user has follow-up questions:
+- Append to the same research document
+- Add a new section: `## Follow-up Research [{timestamp}]`
+- Update the bead notes with the new findings
+
+## Important Guidelines
+
+- Always use parallel Task agents to maximize efficiency
+- Always run fresh codebase research - never rely solely on existing documents
+- Focus on finding concrete file paths and line numbers
+- Research documents should be self-contained
+- Document cross-component connections
+- Include temporal context (when research was conducted)
+- Keep the main agent focused on synthesis, not deep file reading
+- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
+- **REMEMBER**: Document what IS, not what SHOULD BE
+
+## Example Invocation
+
+```
+User: /beads:research nixos-configs-abc123
+Assistant: Starting research for bead nixos-configs-abc123: Investigate auth flow
+...
+```
+
+Or without bead ID:
+```
+User: /beads:research
+Assistant: Let me check for research beads...
+[runs bd ready]
+Which bead would you like me to research?
+```

home/roles/development/commands/beads_workflow.md

@@ -0,0 +1,387 @@
+---
+description: Comprehensive guide for the beads + humanlayer integrated workflow
+---
+
+# Beads Workflow Guide
+
+This document describes the integrated workflow combining **beads** (issue tracking) with **humanlayer-style skills** (deep research, planning, implementation).
+
+## Philosophy
+
+### Two Systems, Complementary Purposes
+
+| System | Purpose | Storage |
+|--------|---------|---------|
+| **Beads** | Track WHAT work exists | `.beads/` (git-synced) |
+| **Thoughts** | Store HOW to do the work | `thoughts/` (local or symlinked) |
+
+### Autonomy Model
+
+| Bead Type | Agent Autonomy | Checkpoint |
+|-----------|----------------|------------|
+| `research` | **Full** - agent closes when satisfied | None |
+| `feature`, `task`, `bug` | **Checkpointed** - pause for validation | Per-plan |
+
+**Key insight**: Research produces artifacts. Implementation produces commits. Commits are the review boundary.
+
+## Directory Structure
+
+```
+project/
+├── .beads/                              # Beads database (git-synced)
+│   ├── beads.db
+│   ├── config.yaml
+│   └── issues.jsonl
+├── thoughts/                            # Artifacts (local or symlink)
+│   ├── beads-{id}/                      # Per-bead artifacts
+│   │   ├── research.md
+│   │   ├── plan.md
+│   │   └── plan-v1.md                   # Iteration history
+│   └── shared/                          # Legacy/non-bead artifacts
+│       ├── research/
+│       └── plans/
+└── home/roles/development/skills/       # Skill definitions
+    ├── beads_research.md
+    ├── beads_plan.md
+    ├── beads_implement.md
+    └── beads_iterate.md
+```
+
+## When to Use What
+
+### Use Beads When:
+- Work spans multiple sessions
+- Work has dependencies or blockers
+- You need to track status across interruptions
+- Multiple related tasks need coordination
+- Context recovery after compaction matters
+
+### Use TodoWrite When:
+- Single-session execution tracking
+- Breaking down work within a session
+- Tracking progress on a single bead
+
+### Use Both Together:
+- Beads track the overall work items
+- TodoWrite tracks progress within a session
+- Example: Bead for "Implement auth", TodoWrite for each file being edited
+
+## Workflow Patterns
+
+### Pattern 1: Research-First Approach
+
+```
+1. Create research bead
+   bd create --title="Research auth patterns" --type=research --priority=1
+
+2. Run research
+   /beads:research {bead-id}
+   → Agent researches, writes to thoughts/beads-{id}/research.md
+   → Agent closes bead when satisfied
+
+3. Create implementation bead
+   bd create --title="Implement auth" --type=feature --priority=1
+
+4. Plan the implementation
+   /beads:plan {bead-id}
+   → Agent reads prior research, creates plan
+   → Plan saved to thoughts/beads-{id}/plan.md
+
+5. Implement
+   /beads:implement {bead-id}
+   → Agent follows plan, pauses for manual verification
+   → You validate, agent closes bead
+```
+
+### Pattern 2: Direct Implementation
+
+For well-understood tasks without research:
+
+```
+1. Create bead
+   bd create --title="Fix login bug" --type=bug --priority=0
+
+2. Plan and implement
+   /beads:plan {bead-id}
+   → Quick planning based on bead description
+
+   /beads:implement {bead-id}
+   → Follow plan, pause at checkpoint
+```
+
+### Pattern 3: Iterative Planning
+
+When requirements evolve:
+
+```
+1. Initial plan
+   /beads:plan {bead-id}
+
+2. Iterate based on feedback
+   /beads:iterate {bead-id} - add error handling phase
+
+3. Iterate again if needed
+   /beads:iterate {bead-id} - split phase 2 into backend/frontend
+
+4. Implement when plan is solid
+   /beads:implement {bead-id}
+```
+
+### Pattern 4: Parallel Work
+
+Using parallel_beads skill for multiple independent tasks:
+
+```
+1. Check what's ready
+   bd ready
+
+2. Select multiple beads
+   /parallel_beads
+   → Select beads to work on
+   → Each gets worktree, PR, review
+
+3. Reconcile after PRs merge
+   /reconcile_beads
+```
+
+## Skills Reference
+
+### /beads:research {bead-id}
+- Conducts comprehensive codebase research
+- Uses parallel sub-agents for efficiency
+- Outputs to `thoughts/beads-{id}/research.md`
+- **Autonomy**: Can close research beads automatically
+
+### /beads:plan {bead-id}
+- Creates detailed implementation plans
+- Interactive process with checkpoints
+- Outputs to `thoughts/beads-{id}/plan.md`
+- Can create dependent implementation beads
+
+### /beads:implement {bead-id}
+- Follows plans from thoughts/
+- Updates plan checkboxes for resumability
+- **Checkpoint**: Pauses after plan completion for manual verification
+- Only closes bead after human confirms
+
+### /beads:iterate {bead-id}
+- Updates existing plans based on feedback
+- Preserves plan structure while making targeted changes
+- Saves iteration history as `plan-v{N}.md`
+
+### /parallel_beads
+- Orchestrates parallel bead processing
+- Creates worktrees, PRs, reviews for multiple beads
+- Good for batching independent work
+
+### /reconcile_beads
+- Closes beads whose PRs have merged
+- Run after merging PRs to keep beads in sync
+
+## Session Protocols
+
+### Starting a Session
+
+```bash
+# Check what's available
+bd ready
+
+# Pick work and start
+bd update {bead-id} --status=in_progress
+```
+
+### Ending a Session
+
+```bash
+# Always run this checklist:
+[ ] git status                    # Check changes
+[ ] git add <files>               # Stage code changes
+[ ] bd sync                       # Sync beads
+[ ] git commit -m "..."           # Commit code
+[ ] git push                      # Push to remote
+```
+
+### Resuming Work
+
+```bash
+# Find in-progress work
+bd list --status=in_progress
+
+# Check bead notes for context
+bd show {bead-id}
+
+# Check for partial plan progress
+cat thoughts/beads-{id}/plan.md | grep "\[x\]"
+```
+
+## Thoughts Directory Patterns
+
+### For Work Repos (via symlink)
+```
+project/thoughts → ~/thoughts/repos/{repo-name}/
+```
+- Syncs via codelayer to work remote
+- Shared across projects on same machine
+
+### For Personal Repos (local)
+```
+project/thoughts/  # Regular directory, not symlink
+```
+- Stays local to project
+- Committed with project or gitignored
+
+### Determining Which Pattern
+```bash
+# Check if thoughts is a symlink
+ls -la thoughts
+
+# If symlink, it points to ~/thoughts/repos/{repo}/
+# If directory, it's local to this project
+```
+
+## Best Practices
+
+### 1. Bead Descriptions Matter
+Write clear descriptions - they're the input for research and planning:
+```bash
+bd create --title="Implement user preferences" --type=feature \
+  --description="Add user preferences storage and UI.
+
+Requirements:
+- Store preferences in SQLite
+- Expose via REST API
+- Add settings page in UI
+
+See related: thoughts/shared/research/preferences-patterns.md"
+```
+
+### 2. Link Artifacts in Beads
+Always update bead notes with artifact locations:
+```bash
+bd update {id} --notes="Research: thoughts/beads-{id}/research.md
+Plan: thoughts/beads-{id}/plan.md"
+```
+
+### 3. Use Dependencies
+Structure work with dependencies:
+```bash
+# Research blocks planning
+bd dep add {plan-bead} {research-bead}
+
+# Planning blocks implementation
+bd dep add {impl-bead} {plan-bead}
+```
+
+### 4. Trust the Checkpoint Model
+- Research beads: Let agent close them
+- Implementation beads: Always validate before closing
+- If in doubt, err on the side of checkpoints
+
+### 5. Keep Plans Updated
+- Check off completed items as you go
+- Update notes with progress
+- This enables seamless resume across sessions
+
+## Troubleshooting
+
+### "What bead should I work on?"
+```bash
+bd ready  # Shows unblocked work
+```
+
+### "Where did the research go?"
+```bash
+ls thoughts/beads-{id}/
+bd show {id}  # Check notes for artifact links
+```
+
+### "Plan doesn't match reality"
+```bash
+/beads:iterate {id}  # Update plan based on findings
+```
+
+### "Session ended mid-implementation"
+```bash
+bd show {id}  # Check notes for progress
+cat thoughts/beads-{id}/plan.md | grep "\[x\]"  # See completed items
+/beads:implement {id}  # Resume - will pick up from last checkpoint
+```
+
+### "Bead is blocked"
+```bash
+bd show {id}  # See what's blocking
+bd blocked    # See all blocked beads
+```
+
+## Migration Notes
+
+### From Pure Humanlayer to Beads+Humanlayer
+
+Old pattern:
+```
+thoughts/shared/research/2025-01-01-topic.md
+thoughts/shared/plans/2025-01-01-feature.md
+```
+
+New pattern:
+```
+thoughts/beads-{id}/research.md
+thoughts/beads-{id}/plan.md
+```
+
+The `shared/` structure still works for non-bead artifacts, but prefer per-bead directories for tracked work.
+
+### Existing Content
+- Keep existing `thoughts/shared/` content
+- New bead-tracked work uses `thoughts/beads-{id}/`
+- Reference old research from bead descriptions when relevant
+
+## Design Decisions
+
+### Phase Tracking: Artifacts vs Statuses
+
+**Current approach**: Skills infer workflow phase from artifact presence:
+- Has `research.md` → research done
+- Has `plan.md` → planning done
+- No artifacts → needs research/planning
+
+**Alternative considered**: Explicit phase statuses (`needs_research`, `needs_plan`, `implementing`, etc.)
+
+**Why artifacts win**:
+1. **Single source of truth** - Status can't drift from reality
+2. **Less state to maintain** - No need to update status when creating artifacts
+3. **Works across repos** - No custom status config needed
+4. **Skills already check artifacts** - Natural fit with existing behavior
+
+**When explicit statuses would help**:
+- Pipeline visualization (e.g., `bd list --status=needs_plan`)
+- Agent self-selection by phase
+- Team coordination dashboards
+
+**Recommendation**: Keep artifact-inference as primary mechanism. If pipeline visibility becomes important, consider adding statuses that skills auto-set when creating artifacts (advisory, not enforced).
+
+### One Bead Per Feature (Default)
+
+**Current approach**: File one bead per logical feature. Skills handle phases internally.
+
+**Alternative considered**: Separate beads for research → planning → implementation, linked by dependencies.
+
+**Why single bead wins for most work**:
+1. **Lower friction** - Quick idea dump without filing 3 tickets
+2. **Simpler tracking** - One status to check
+3. **Natural grouping** - Artifacts stay together in `thoughts/beads-{id}/`
+
+**When to split into multiple beads**:
+- Research reveals the work should be multiple features
+- Different phases need different assignees
+- Explicit dependency tracking matters (e.g., "auth must ship before payments")
+
+**The discovered-work pattern**: Start with one bead. If research reveals split work, file additional beads with dependencies. Skills guide this naturally.
+
+### Plan Requirements by Type
+
+**Bug fixes** (`type=bug`): Can proceed without plans - usually well-scoped from bug report.
+
+**Features/tasks** (`type=feature`, `type=task`): Should have plans - helps ensure design is sound before implementation.
+
+This is advisory, not enforced. Skills warn but allow override for simple changes.

home/roles/development/commands/gitea_pr_review.md

@@ -0,0 +1,472 @@
+---
+description: Address Gitea/Forgejo PR review comments with code changes
+---
+
+# Gitea PR Review
+
+You are tasked with **addressing** PR review comments by making code changes, then summarizing what was done. This skill drives PR progress, not just conversation.
+
+## Philosophy
+
+**Comments are work items, not conversation starters.**
+
+When a reviewer leaves a comment, they're identifying something that needs attention. This skill:
+1. Categorizes comments by actionability
+2. Makes code changes to address actionable comments
+3. Commits and pushes those changes
+4. Posts a single summary comment describing what was done
+
+## Prerequisites
+
+- `tea` CLI configured with a Gitea/Forgejo instance
+- Access token from tea config: `~/.config/tea/config.yml`
+- Repository must be a Gitea/Forgejo remote (not GitHub)
+- **Nix users**: All tools available via nixpkgs (`nix run nixpkgs#tea`)
+
+## Initial Setup
+
+When this command is invoked:
+
+1. **Parse the input for PR number**:
+   - If a PR number is provided as argument, use it
+   - If no PR number, detect from current branch (see PR Detection section)
+
+2. **Verify required tools are available**:
+   ```bash
+   which tea
+   ```
+
+   If tea is missing:
+   ```
+   Error: `tea` CLI not found.
+
+   Please install:
+   - Nix: nix run nixpkgs#tea
+   - Other: https://gitea.com/gitea/tea
+   ```
+   **STOP** if tea is missing.
+
+3. **Extract configuration from tea config**:
+   ```bash
+   # Read tea config (it's YAML but simple enough to grep)
+   TEA_CONFIG="$HOME/.config/tea/config.yml"
+   GITEA_URL=$(grep -A1 'logins:' "$TEA_CONFIG" | grep 'url:' | head -1 | sed 's/.*url: //')
+   TOKEN=$(grep -A5 'logins:' "$TEA_CONFIG" | grep 'token:' | head -1 | sed 's/.*token: //')
+   ```
+
+   If config is missing or invalid:
+   ```
+   Error: Could not read tea config at ~/.config/tea/config.yml
+
+   Please ensure `tea` is installed and configured:
+   1. Install tea
+   2. Log in: tea login add --url https://your-gitea-instance --token YOUR_TOKEN
+   ```
+   **STOP** if config is invalid.
+
+4. **Detect repository info from git remote**:
+   ```bash
+   REMOTE_URL=$(git remote get-url origin)
+   # Parse owner and repo from URL (handles both SSH and HTTPS)
+   OWNER=$(echo "$REMOTE_URL" | sed -E 's#.*[:/]([^/]+)/[^/]+\.git$#\1#')
+   REPO=$(echo "$REMOTE_URL" | sed -E 's#.*/([^/]+)\.git$#\1#')
+   ```
+
+5. **Ensure we're on the PR branch**:
+   ```bash
+   CURRENT_BRANCH=$(git branch --show-current)
+   # Verify this branch corresponds to the PR
+   ```
+
+6. **Respond with**:
+   ```
+   Addressing PR review comments for PR #{PR_NUMBER}...
+
+   Repository: {OWNER}/{REPO}
+   Branch: {CURRENT_BRANCH}
+   Gitea URL: {GITEA_URL}
+   ```
+
+## PR Detection
+
+If no PR number is provided, detect from the current branch:
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+tea pr list --fields index,head --output simple | grep "$CURRENT_BRANCH"
+```
+
+If no PR exists for the current branch, use `AskUserQuestion`:
+
+```
+No PR found for branch '{CURRENT_BRANCH}'.
+
+Would you like to:
+1. Enter a PR number manually
+2. Cancel
+```
+
+## Workflow
+
+### Step 1: Fetch and Parse Comments
+
+Fetch all reviews and their comments:
+
+```bash
+# Fetch reviews (filter out dismissed reviews)
+curl -s -H "Authorization: token $TOKEN" \
+  "$GITEA_URL/api/v1/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews" \
+  | jq '[.[] | select(.dismissed != true)]'
+
+# For each review, fetch comments
+curl -s -H "Authorization: token $TOKEN" \
+  "$GITEA_URL/api/v1/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews/$REVIEW_ID/comments"
+```
+
+**Filter resolved comments**: When processing comments, skip any that have been marked as resolved. Check the `resolver` field in the comment response - if it's not null, the comment has been resolved and should be skipped.
+
+```bash
+# Example: Filter to only unresolved comments
+jq '[.[] | select(.resolver == null)]'
+```
+
+If no reviews found or all comments are resolved:
+```
+No unresolved reviews found for PR #{PR_NUMBER}.
+Nothing to address.
+```
+**STOP** here.
+
+### Step 2: Categorize Comments
+
+For each comment, categorize it as one of:
+
+| Category | Description | Action |
+|----------|-------------|--------|
+| **actionable** | Requests a code change, addition, or fix | Launch subagent to make change |
+| **question** | Asks for clarification or explanation | Include answer in summary |
+| **acknowledged** | FYI, self-resolved, or "no action needed" noted | Note in summary |
+| **blocked** | Requires external input or is out of scope | Flag for user |
+
+**Categorization heuristics**:
+- Contains "add", "change", "fix", "update", "consider adding", "should be" → **actionable**
+- Contains "?" or "why", "how", "what" → **question**
+- Contains "no need to update", "will be separate", "acknowledged" → **acknowledged**
+- Contains "discuss", "later", "out of scope", "blocked by" → **blocked**
+
+Display the categorization:
+```
+## Comment Analysis
+
+### Actionable (will make changes):
+1. {file}:{line} - "{comment_summary}" → Will add nix note to prerequisites
+
+### Questions (will answer in summary):
+2. {file}:{line} - "{comment_summary}" → Explain CI token approach
+
+### Acknowledged (no action needed):
+3. {file}:{line} - "{comment_summary}" → Reviewer noted separate skill
+
+### Blocked (needs input):
+(none)
+```
+
+### Step 3: User Confirmation
+
+Use `AskUserQuestion` to confirm the plan:
+
+```
+I've categorized {N} comments. My plan:
+
+**Will make changes for:**
+- {file}:{line}: {planned_change}
+
+**Will explain in summary:**
+- {file}:{line}: {planned_explanation}
+
+**No action needed:**
+- {file}:{line}: {reason}
+
+Proceed with this plan?
+```
+
+Options:
+1. **Proceed** - Execute the plan
+2. **Modify** - Let user adjust categorization
+3. **Cancel** - Exit without changes
+
+### Step 4: Address Actionable Comments (Parallel Subagents)
+
+For each actionable comment, launch a subagent using the Task tool:
+
+```
+Launch Task subagent with:
+- subagent_type: "general-purpose"
+- prompt: |
+    You are addressing a PR review comment. Make the requested change and nothing else.
+
+    **File**: {file_path}
+    **Line**: {line_number}
+    **Comment**: {comment_body}
+    **Diff context**:
+    ```
+    {diff_hunk}
+    ```
+
+    Instructions:
+    1. Read the file to understand context
+    2. Make the minimal change to address the comment
+    3. Do NOT commit - just make the edit
+    4. Report what you changed
+
+    Be precise. Only change what's needed to address this specific comment.
+```
+
+**Important**: Launch actionable comment subagents in parallel when they touch different files. For comments on the same file, run sequentially to avoid conflicts.
+
+Wait for all subagents to complete and collect their results.
+
+### Step 5: Commit and Push
+
+After all subagents complete:
+
+1. **Stage changes**:
+   ```bash
+   git add -A
+   ```
+
+2. **Create commit with summary**:
+   ```bash
+   git commit -m "Address PR review comments
+
+   Changes made:
+   - {file1}: {change_summary}
+   - {file2}: {change_summary}
+
+   Addresses comments from review by {reviewer}"
+   ```
+
+3. **Push to remote**:
+   ```bash
+   git push
+   ```
+
+### Step 6: Post Summary Comment
+
+Post a single comment summarizing all actions taken:
+
+```bash
+tea comment $PR_NUMBER "$(cat <<'EOF'
+## Review Comments Addressed
+
+cc @{reviewer1} @{reviewer2}
+
+**Changes made** (commit {SHORT_SHA}):
+- `{file1}:{line}`: {what_was_changed}
+- `{file2}:{line}`: {what_was_changed}
+
+**Responses to questions**:
+- `{file3}:{line}`: {answer_to_question}
+
+**Acknowledged** (no action needed):
+- `{file4}:{line}`: {reason_no_action}
+
+---
+*Automated response via /gitea_pr_review*
+EOF
+)"
+```
+
+### Step 7: Final Summary
+
+Display to user:
+
+```
+## PR Review Complete
+
+**Commit**: {SHA}
+**Changes**: {N} files modified
+
+### Actions Taken:
+- [x] {file1}:{line} - Added nix prerequisite note
+- [x] {file2}:{line} - Explained CI approach in comment
+- [ ] {file3}:{line} - Acknowledged (separate skill)
+
+**Reviewers tagged**: @{reviewer1}, @{reviewer2}
+**Comment posted**: {comment_url}
+
+PR URL: {GITEA_URL}/{OWNER}/{REPO}/pulls/{PR_NUMBER}
+```
+
+**Note**: When posting the summary comment, tag all reviewers who left comments so they receive notifications about the changes.
+
+## Error Handling
+
+### Subagent failed to make change
+
+If a subagent fails:
+```
+Warning: Could not address comment on {file}:{line}
+
+Reason: {error}
+
+Options:
+1. Skip this comment and continue
+2. Retry with manual guidance
+3. Abort all changes
+```
+
+### Push failed
+
+```
+Error pushing changes: {error}
+
+Your changes are committed locally. You may need to:
+1. Pull and resolve conflicts: git pull --rebase
+2. Push again: git push
+```
+
+### No actionable comments
+
+If all comments are questions/acknowledged:
+```
+No code changes needed.
+
+All comments are either questions or acknowledged items.
+Posting summary comment with explanations...
+```
+
+## API Reference
+
+### Endpoints Used
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| List reviews | GET | `/api/v1/repos/{owner}/{repo}/pulls/{index}/reviews` |
+| Get review comments | GET | `/api/v1/repos/{owner}/{repo}/pulls/{index}/reviews/{id}/comments` |
+| Create issue comment | POST | via `tea comment` |
+
+### Review States
+
+- `PENDING` - Draft review not yet submitted
+- `COMMENT` - General comment without approval/rejection
+- `APPROVE` - Approving the changes
+- `REQUEST_CHANGES` - Requesting changes before merge
+
+## Shell Command Patterns
+
+Claude Code's bash execution has quirks. Use these patterns for reliability:
+
+### curl requests
+
+**DO** - Use single quotes for URL and header separately:
+```bash
+curl -s 'https://git.example.com/api/v1/repos/owner/repo/pulls/1/reviews' \
+  -H 'Authorization: token YOUR_TOKEN_HERE' | jq .
+```
+
+**DON'T** - Variable expansion in `-H` flag often fails:
+```bash
+# This may fail with "blank argument" errors
+curl -s -H "Authorization: token $TOKEN" "$URL"
+```
+
+### Iterating over reviews
+
+**DO** - Run separate commands for each review ID:
+```bash
+echo "=== Review 4 ===" && curl -s 'URL/reviews/4/comments' -H 'Authorization: token ...' | jq .
+echo "=== Review 5 ===" && curl -s 'URL/reviews/5/comments' -H 'Authorization: token ...' | jq .
+```
+
+**DON'T** - For loops with multiline bodies often fail:
+```bash
+# This may cause syntax errors
+for id in 4 5 6; do
+  curl -s "URL/reviews/$id/comments"
+done
+```
+
+### tea comment
+
+**DO** - Use single-quoted string for comment body:
+```bash
+tea comment 26 '## Summary
+
+Changes made:
+- Item 1
+- Item 2'
+```
+
+**DON'T** - Heredocs may hang or timeout:
+```bash
+# This may hang indefinitely
+tea comment 26 "$(cat <<'EOF'
+...
+EOF
+)"
+```
+
+## Limitations
+
+1. **Thread replies**: Gitea API doesn't support inline thread replies. We post a single summary comment instead.
+
+2. **Complex changes**: For comments requiring significant refactoring, the subagent may need guidance. The skill will flag these as "blocked" for user input.
+
+3. **Merge conflicts**: If the branch is behind, you may need to rebase before changes can be pushed.
+
+## Example Session
+
+```
+User: /gitea_pr_review 26
+Assistant: Addressing PR review comments for PR #26...
+
+Repository: johno/nixos-configs
+Branch: bead/nixos-configs-vru
+Gitea URL: https://git.johnogle.info
+
+## Comment Analysis
+
+### Actionable (will make changes):
+1. gitea_pr_review.md:12 - "could we indicate nix+nixpkgs satisfies this?" 
+   → Will add note that nix users can get tools via nixpkgs
+
+### Questions (will answer in summary):
+(none)
+
+### Acknowledged (no action needed):
+2. gitea_pr_review.md:50 - "we eventually want to run this in CI..."
+   → Reviewer noted this will be a separate skill
+
+Proceed with this plan? [Proceed]
+
+Launching subagent to address comment 1...
+[Subagent completes edit]
+
+Committing changes...
+[abc1234] Address PR review comments
+
+Pushing to remote...
+Done.
+
+Posting summary comment...
+
+## PR Review Complete
+
+**Commit**: abc1234
+**Changes**: 1 file modified
+
+### Actions Taken:
+- [x] gitea_pr_review.md:12 - Added nix prerequisite note  
+- [ ] gitea_pr_review.md:50 - Acknowledged (separate skill)
+
+**Comment posted**: https://git.johnogle.info/.../pulls/26#issuecomment-XXX
+
+PR URL: https://git.johnogle.info/johno/nixos-configs/pulls/26
+```
+
+## See Also
+
+- `tea` CLI: https://gitea.com/gitea/tea
+- Gitea API: https://docs.gitea.com/api/
+- `/beads_workflow` for full development workflow

home/roles/development/commands/import_gitea_issues.md

@@ -0,0 +1,130 @@
+---
+description: Import open Gitea issues as beads, skipping already-imported ones
+---
+
+# Import Gitea Issues as Beads
+
+This skill imports open Gitea issues as beads, checking for duplicates to avoid re-importing already tracked issues.
+
+## Prerequisites
+
+- `tea` CLI must be installed and configured for the repository
+- `bd` (beads) CLI must be installed
+- Must be in a git repository with a Gitea/Forgejo remote
+
+## Workflow
+
+### Step 1: Get open Gitea issues
+
+List all open issues using `tea`:
+
+```bash
+tea issues
+```
+
+This returns a table with columns: INDEX, TITLE, LABELS, MILESTONE
+
+### Step 2: Get existing beads
+
+List all current beads to check what's already imported:
+
+```bash
+bd list
+```
+
+Also check bead notes for issue URLs to identify imports:
+
+```bash
+bd list --json | jq -r '.[] | select(.notes != null) | .notes' | grep -oP 'issues/\K\d+'
+```
+
+### Step 3: Check for already-linked PRs
+
+Check if any open PRs reference beads (skip these issues as they're being worked on):
+
+```bash
+tea pr list
+```
+
+Look for PRs with:
+- Bead ID in title: `[nixos-configs-xxx]`
+- Bead reference in body: `Implements bead:` or `Bead ID:`
+
+### Step 4: For each untracked issue, create a bead
+
+For each issue not already tracked:
+
+1. **Get full issue details**:
+   ```bash
+   tea issue [ISSUE_NUMBER]
+   ```
+
+2. **Determine bead type** based on issue content:
+   - "bug" - if issue mentions bug, error, broken, fix, crash
+   - "feature" - if issue mentions feature, add, new, enhancement
+   - "task" - default for other issues
+
+3. **Create the bead**:
+   ```bash
+   bd add "[ISSUE_TITLE]" \
+     --type=[TYPE] \
+     --priority=P2 \
+     --notes="Gitea issue: [ISSUE_URL]
+
+   Original issue description:
+   [ISSUE_BODY]"
+   ```
+
+   Note: The `--notes` flag accepts multi-line content.
+
+### Step 5: Report results
+
+Present a summary:
+
+```
+## Gitea Issues Import Summary
+
+### Imported as Beads
+| Issue | Title | Bead ID | Type |
+|-------|-------|---------|------|
+| #5 | Add dark mode | nixos-configs-abc | feature |
+| #3 | Config broken on reboot | nixos-configs-def | bug |
+
+### Skipped (Already Tracked)
+| Issue | Title | Reason |
+|-------|-------|--------|
+| #4 | Update flake | Existing bead: nixos-configs-xyz |
+| #2 | Refactor roles | PR #7 references bead |
+
+### Skipped (Other)
+| Issue | Title | Reason |
+|-------|-------|--------|
+| #1 | Discussion: future plans | No actionable work |
+```
+
+## Type Detection Heuristics
+
+Keywords to detect issue type:
+
+**Bug indicators** (case-insensitive):
+- bug, error, broken, fix, crash, fail, issue, problem, wrong, not working
+
+**Feature indicators** (case-insensitive):
+- feature, add, new, enhancement, implement, support, request, want, would be nice
+
+**Task** (default):
+- Anything not matching bug or feature patterns
+
+## Error Handling
+
+- **tea not configured**: Report error and exit
+- **bd not available**: Report error and exit
+- **Issue already has bead**: Skip and report in summary
+- **Issue is a PR**: Skip (tea shows PRs and issues separately)
+
+## Notes
+
+- Default priority is P2; adjust manually after import if needed
+- Issue labels from Gitea are not automatically mapped to bead tags
+- Run this periodically to catch new issues
+- After import, use `bd ready` to see which beads can be worked on

home/roles/development/commands/parallel_beads.md

@@ -0,0 +1,409 @@
+---
+description: Orchestrate parallel bead processing with worktrees, PRs, and reviews
+---
+
+# Parallel Beads Workflow
+
+This skill orchestrates parallel bead processing using subagents. Each bead gets its own worktree, implementation, PR, and review.
+
+## Phase 1: Selection
+
+1. **Get ready beads**: Run `bd ready` to list all beads with no blockers
+
+2. **Filter by plan readiness**:
+   For each ready bead, check if it's ready for batch implementation:
+   - **Has plan** (`thoughts/beads-{id}/plan.md` exists): Include
+   - **type=bug** without plan: Include (simple bugs can implement directly)
+   - **type=feature/task** without plan: Exclude with warning
+
+   ```bash
+   # Check for plan existence
+   ls thoughts/beads-{bead-id}/plan.md 2>/dev/null
+   ```
+
+3. **Report skipped beads**:
+   If any beads were skipped, inform the user:
+   ```
+   Skipped beads (no plan):
+   - {bead-id}: {title} (type: feature) - Run /beads_plan {bead-id} first
+   - {bead-id}: {title} (type: task) - Run /beads_plan {bead-id} first
+   ```
+
+4. **Present selection**: Use `AskUserQuestion` with `multiSelect: true` to let the user choose which beads to work on
+   - Include bead ID and title for each option
+   - Only show beads that passed the plan check
+   - Allow selection of multiple beads
+
+Example:
+```
+AskUserQuestion with:
+- question: "Which beads do you want to work on in parallel?"
+- multiSelect: true
+- options from filtered bd ready output
+```
+
+## Phase 2: Worktree Setup
+
+Before launching implementation subagents, create worktrees for all selected beads:
+
+1. **Get repository name**:
+   ```bash
+   REPO_NAME=$(git remote get-url origin | sed 's|.*/||' | sed 's/\.git$//')
+   ```
+
+2. **For each selected bead**, create its worktree:
+   ```bash
+   BEAD_ID="[bead-id]"
+   # Check if worktree already exists
+   if [ -d "$HOME/wt/${REPO_NAME}/${BEAD_ID}" ]; then
+     echo "Worktree already exists: ~/wt/${REPO_NAME}/${BEAD_ID}"
+     # Ask user: remove and recreate, or skip this bead?
+   else
+     git worktree add -b "bead/${BEAD_ID}" "$HOME/wt/${REPO_NAME}/${BEAD_ID}"
+   fi
+   ```
+
+3. **Track created worktrees**:
+   Maintain a list of (bead_id, worktree_path) pairs for use in subagent instructions.
+
+4. **Report status**:
+   ```
+   Created worktrees:
+   - nixos-configs-abc → ~/wt/nixos-configs/nixos-configs-abc (branch: bead/nixos-configs-abc)
+   - nixos-configs-xyz → ~/wt/nixos-configs/nixos-configs-xyz (branch: bead/nixos-configs-xyz)
+
+   Skipped (existing worktree):
+   - nixos-configs-123 → Ask user for resolution
+   ```
+
+**Note**: If a worktree or branch already exists, ask the user before proceeding:
+- Remove existing worktree and branch, then recreate
+- Skip this bead
+- Use existing worktree as-is (risky - branch may have diverged)
+
+## Phase 3: Parallel Implementation
+
+For each selected bead, launch a subagent using the Task tool. All subagents should be launched in parallel (single message with multiple Task tool calls).
+
+### Subagent Instructions Template
+
+Each implementation subagent should receive these instructions:
+
+```
+Work on bead [BEAD_ID]: [BEAD_TITLE]
+
+Worktree path: [WORKTREE_PATH]
+
+## CRITICAL: Branch Verification (MUST DO FIRST)
+
+1. **Navigate to worktree**:
+   ```bash
+   cd [WORKTREE_PATH]
+   ```
+
+2. **Verify branch** (MANDATORY before ANY modifications):
+   ```bash
+   CURRENT_BRANCH=$(git branch --show-current)
+   echo "Current branch: $CURRENT_BRANCH"
+   pwd
+   ```
+
+   **ABORT CONDITIONS** - If ANY of these are true, STOP IMMEDIATELY:
+   - Branch is `main` or `master`
+   - Branch does not match `bead/[BEAD_ID]`
+
+   If you detect any abort condition:
+   ```
+   ABORTING: Branch verification failed.
+   Expected branch: bead/[BEAD_ID]
+   Actual branch: [CURRENT_BRANCH]
+   Working directory: [pwd output]
+
+   DO NOT PROCEED. Report this error to the orchestrator.
+   ```
+
+## After Verification Passes
+
+3. **Review the bead requirements**:
+   - Run `bd show [BEAD_ID]` to understand the acceptance criteria
+   - Note any external issue references (GitHub issues, Linear tickets, etc.)
+
+4. **Extract validation criteria**:
+   - Check for a plan: `thoughts/beads-[BEAD_ID]/plan.md`
+   - If plan exists:
+     - Read the plan and find the "Automated Verification" section
+     - Extract each verification command (lines starting with `- [ ]` followed by a command)
+     - Example: `- [ ] Tests pass: \`make test\`` → extract `make test`
+     - Note any "Per CONTRIBUTING.md:" requirements for additional validation
+     - Also read the "Manual Verification" section from the plan if present
+     - Save manual verification items for inclusion in the PR description (they won't be executed)
+   - If no plan exists, use best-effort validation:
+     - Check if `Makefile` exists → try `make test` and `make lint`
+     - Check if `flake.nix` exists → try `nix flake check`
+     - Check if `package.json` exists → try `npm test`
+     - **Check for CONTRIBUTING.md** → read and extract testing/linting requirements
+       - Track which requirements can be automated vs need manual review
+       - Automated: commands that can be run (e.g., "run `make test`")
+       - Manual: qualitative checks (e.g., "ensure documentation is updated")
+     - If none found, note "No validation criteria found"
+
+5. **Implement the changes**:
+   - Work in the worktree directory
+   - Complete all acceptance criteria listed in the bead
+
+   After implementation, run validation:
+   - Execute each validation command from step 4
+   - Track results in this format:
+     ```
+     VALIDATION_RESULTS:
+     - make test: PASS
+     - make lint: FAIL (exit code 1: src/foo.ts:23 - missing semicolon)
+     - nix flake check: SKIP (not applicable - no flake.nix)
+     - cargo test: ERROR (command not found)
+     ```
+
+   **Status definitions:**
+   - **PASS**: Check executed successfully with no issues
+   - **FAIL**: Check executed but found issues that need attention
+   - **SKIP**: Check not applicable to this project (e.g., no Makefile for `make test`)
+   - **ERROR**: Check could not execute (missing tool, permission error, command not found)
+
+   - If any validation fails:
+     - Continue with PR creation (don't block)
+     - Document failures in bead notes: `bd update [BEAD_ID] --notes="Validation failures: [list]"`
+
+6. **Commit and push**:
+   - Stage all changes: `git add -A`
+   - Create a descriptive commit message
+   - Push the branch: `git push -u origin bead/[BEAD_ID]`
+
+7. **Create a PR**:
+   - Detect hosting provider from origin URL: `git remote get-url origin`
+   - If URL contains `github.com`, use `gh`; otherwise use `tea` (Gitea/Forgejo)
+   - PR title: "[BEAD_ID] [BEAD_TITLE]"
+   - PR body must include:
+     - Reference to bead ID: "Implements bead: [BEAD_ID]"
+     - Any external issue references from the bead (e.g., "Closes #123")
+     - Summary of changes
+   - For GitHub (`gh`):
+     ```bash
+     gh pr create --title "[BEAD_ID] [BEAD_TITLE]" --body "$(cat <<'EOF'
+     ## Summary
+     [Brief description of changes]
+
+     ## Bead Reference
+     Implements bead: [BEAD_ID]
+
+     ## External Issues
+     [Any linked issues from the bead]
+
+     ## Changes
+     - [List of changes made]
+
+     ## Validation Steps Completed
+
+     ### Automated Checks
+     | Check | Status | Details |
+     |-------|--------|---------|
+     | make test | PASS | |
+     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
+     | nix flake check | SKIP | not applicable - no flake.nix |
+     | cargo test | ERROR | command not found |
+
+     ### Manual Verification Required
+     [If plan has Manual Verification items, list them as unchecked boxes:]
+     - [ ] Verify UI changes match design mockups
+     - [ ] Test on mobile viewport sizes
+     [If no manual verification items: "None specified in plan."]
+
+     ### CONTRIBUTING.md Compliance
+     [If CONTRIBUTING.md requirements were extracted:]
+     - [x] Tests pass (verified via `make test`)
+     - [ ] Documentation updated (needs manual review)
+     [If no CONTRIBUTING.md: "No contribution guidelines found."]
+     EOF
+     )"
+     ```
+   - For Gitea (`tea`):
+     ```bash
+     tea pr create --head bead/[BEAD_ID] --base main \
+       --title "[BEAD_ID] [BEAD_TITLE]" \
+       --description "## Summary
+     [Brief description of changes]
+
+     ## Bead Reference
+     Implements bead: [BEAD_ID]
+
+     ## External Issues
+     [Any linked issues from the bead]
+
+     ## Changes
+     - [List of changes made]
+
+     ## Validation Steps Completed
+
+     ### Automated Checks
+     | Check | Status | Details |
+     |-------|--------|---------|
+     | make test | PASS | |
+     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
+     | nix flake check | SKIP | not applicable - no flake.nix |
+     | cargo test | ERROR | command not found |
+
+     ### Manual Verification Required
+     [If plan has Manual Verification items, list them as unchecked boxes:]
+     - [ ] Verify UI changes match design mockups
+     - [ ] Test on mobile viewport sizes
+     [If no manual verification items: None specified in plan.]
+
+     ### CONTRIBUTING.md Compliance
+     [If CONTRIBUTING.md requirements were extracted:]
+     - [x] Tests pass (verified via make test)
+     - [ ] Documentation updated (needs manual review)
+     [If no CONTRIBUTING.md: No contribution guidelines found.]"
+     ```
+
+8. **Update bead status**:
+   - Mark the bead as "in_review": `bd update [BEAD_ID] --status=in_review`
+   - Add the PR URL to the bead notes: `bd update [BEAD_ID] --notes="$(bd show [BEAD_ID] --json | jq -r '.notes')
+
+PR: [PR_URL]"`
+
+9. **Report results**:
+   - Return:
+     - PR URL
+     - Bead ID
+     - Implementation status (success/failure/blocked)
+     - Validation summary: `X passed, Y failed, Z skipped, W errors`
+     - List of any validation failures or errors with details
+   - If blocked or unable to complete, explain what's blocking progress
+   - If validation failed, include the specific failures so the main agent can summarize them for the user
+```
+
+### Launching Subagents
+
+For each bead, substitute into the template:
+- `[BEAD_ID]` - the bead ID
+- `[BEAD_TITLE]` - the bead title
+- `[WORKTREE_PATH]` - the worktree path created in Phase 2
+
+Use `subagent_type: "general-purpose"` for implementation subagents. Launch all selected beads' subagents in a single message for parallel execution:
+
+```
+<Task calls for each selected bead - all in one message>
+```
+
+**Important**: The worktree paths were created in Phase 2. Use the exact paths that were created, e.g.:
+- `~/wt/nixos-configs/nixos-configs-abc`
+- `~/wt/nixos-configs/nixos-configs-xyz`
+
+Collect results from all subagents before proceeding.
+
+## Phase 4: Parallel Review
+
+After all implementation subagents complete, launch review subagents for each PR.
+
+### Review Subagent Instructions Template
+
+```
+Review PR for bead [BEAD_ID]
+
+1. **Detect hosting provider**: Run `git remote get-url origin` - if it contains `github.com` use `gh`, otherwise use `tea`
+
+2. **Read the PR**:
+   - For GitHub: `gh pr view [PR_NUMBER] --json title,body,additions,deletions,files`
+   - For Gitea: `tea pr view [PR_NUMBER]`
+   - View the diff: `git diff main...bead/[BEAD_ID]`
+
+3. **Review against acceptance criteria**:
+   - Run `bd show [BEAD_ID]` to get the acceptance criteria
+   - Verify each criterion is addressed
+
+4. **Leave review comments**:
+   - For GitHub: `gh pr review [PR_NUMBER] --comment --body "[COMMENTS]"`
+   - For Gitea: `tea pr review [PR_NUMBER] --comment "[COMMENTS]"`
+   - Include:
+     - Acceptance criteria checklist (which are met, which might be missing)
+     - Code quality observations
+     - Suggestions for improvement
+
+5. **Return summary**:
+   - Overall assessment (ready to merge / needs changes)
+   - Key findings
+```
+
+Launch all review subagents in parallel.
+
+## Phase 5: Cleanup and Summary
+
+After reviews complete:
+
+1. **Clean up worktrees**:
+   ```bash
+   git worktree remove ~/wt/[REPO_NAME]/[BEAD_ID] --force
+   ```
+   Do this for each bead's worktree.
+
+2. **Provide final summary**:
+   Present a table or list with:
+   - Bead ID
+   - PR URL
+   - Status (success / failed / blocked)
+   - Validation summary (X/Y passed)
+   - Review summary
+   - Any failures or blockers encountered
+
+   If any validation failures occurred, list them in a "Validation Failures" section so the user can address them.
+
+Example output:
+```
+## Parallel Beads Summary
+
+| Bead | PR | Bead Status | Validation | Review |
+|------|-----|-------------|------------|--------|
+| beads-abc | #123 | in_review | 3/3 passed | Approved |
+| beads-xyz | #124 | in_review | 2/3 passed | Needs changes |
+| beads-123 | - | open (failed) | - | Blocked by missing dependency |
+
+### Validation Failures
+- beads-xyz: `make lint` failed - src/foo.ts:23 missing semicolon
+
+### Failures/Blockers
+- beads-123: Could not complete because [reason]
+
+### Next Steps
+- Fix validation failures before merging
+- Review PRs that need changes
+- Address blockers for failed beads
+- Run `/reconcile_beads` after PRs are merged to close beads
+```
+
+## Error Handling
+
+- **Worktree creation failures** (Phase 2):
+  - If `git worktree add` fails (branch exists, path exists), prompt user:
+    - Remove existing and retry
+    - Skip this bead
+    - Use existing (with warning about potential divergence)
+  - Do NOT proceed to subagent launch until worktree is confirmed
+
+- **Branch verification failures** (subagent reports):
+  - If subagent reports it's on `main` or `master`, do NOT retry
+  - Mark bead as failed with reason "Branch verification failed"
+  - Continue with other beads but flag this as a critical issue
+  - Investigation required: the worktree may have been corrupted or not created properly
+
+- **Subagent failures**: If a subagent fails or times out, note it in the summary but continue with other beads
+- **PR creation failures**: Report the error but continue with reviews of successful PRs
+
+## Resource Limits
+
+- Consider limiting concurrent subagents to 3-5 to avoid overwhelming system resources
+- If user selects more beads than the limit, process them in batches
+
+## Notes
+
+- This workflow integrates with the beads system (`bd` commands)
+- Worktrees are created in `~/wt/[REPO_NAME]/` by convention
+- Each bead gets its own isolated branch and worktree
+- PRs automatically reference the bead ID for traceability

home/roles/development/commands/reconcile_beads.md

@@ -4,12 +4,13 @@ description: Reconcile beads with merged PRs and close completed beads
 
 # Reconcile Beads Workflow
 
-This skill reconciles beads that are in `in_review` status with their corresponding PRs. If a PR has been merged, the bead is closed.
+This skill reconciles beads that are in `in_review` status with their corresponding PRs. If a PR has been merged, the bead is closed and any linked Gitea issue is also closed.
 
 ## Prerequisites
 
 - Custom status `in_review` must be configured: `bd config set status.custom "in_review"`
 - Beads in `in_review` status should have a PR URL in their notes
+- `tea` CLI must be configured for closing Gitea issues
 
 ## Workflow
 
@@ -52,6 +53,34 @@ If the PR is merged:
 bd close [BEAD_ID] --reason="PR merged: [PR_URL]"
 ```
 
+### Step 3.1: Close corresponding Gitea issue (if any)
+
+After closing a bead, check if it has a linked Gitea issue:
+
+1. **Check for Gitea issue URL in bead notes**:
+   Look for the pattern `Gitea issue: <URL>` in the notes. Extract the URL.
+
+2. **Extract issue number from URL**:
+   ```bash
+   # Example: https://git.johnogle.info/johno/nixos-configs/issues/16 -> 16
+   echo "$GITEA_URL" | grep -oP '/issues/\K\d+'
+   ```
+
+3. **Close the Gitea issue**:
+   ```bash
+   tea issues close [ISSUE_NUMBER]
+   ```
+
+4. **Handle errors gracefully**:
+   - If issue is already closed: Log warning, continue
+   - If issue not found: Log warning, continue
+   - If `tea` fails: Log error, continue with other beads
+
+   Example warning output:
+   ```
+   Warning: Could not close Gitea issue #16: issue already closed
+   ```
+
 ### Step 4: Report summary
 
 Present results:
@@ -60,10 +89,17 @@ Present results:
 ## Beads Reconciliation Summary
 
 ### Closed (PR Merged)
-| Bead | PR | Title |
-|------|-----|-------|
-| beads-abc | #123 | Feature X |
-| beads-xyz | #456 | Bug fix Y |
+| Bead | PR | Gitea Issue | Title |
+|------|-----|-------------|-------|
+| beads-abc | #123 | #16 closed | Feature X |
+| beads-xyz | #456 | (none) | Bug fix Y |
+
+### Gitea Issues Closed
+| Issue | Bead | Status |
+|-------|------|--------|
+| #16 | beads-abc | Closed successfully |
+| #17 | beads-def | Already closed (skipped) |
+| #99 | beads-ghi | Error: issue not found |
 
 ### Still in Review
 | Bead | PR | Status | Title |
@@ -80,9 +116,14 @@ Present results:
 - **Missing PR URL**: Skip the bead and report it
 - **PR not found**: Report the error but continue with other beads
 - **API errors**: Report and continue
+- **Gitea issue already closed**: Log warning, continue (not an error)
+- **Gitea issue not found**: Log warning, continue (issue may have been deleted)
+- **No Gitea issue linked**: Normal case, no action needed
+- **tea command fails**: Log error with output, continue with other beads
 
 ## Notes
 
 - This skill complements `/parallel_beads` which sets beads to `in_review` status
 - Run this skill periodically or after merging PRs to keep beads in sync
 - Beads with closed (but not merged) PRs are not automatically closed - they may need rework
+- Gitea issues are only closed for beads that have a `Gitea issue: <URL>` in their notes

home/roles/development/default.nix

@@ -5,6 +5,92 @@ with lib;
 let
   cfg = config.home.roles.development;
 
+  # Build beads from flake input with corrected vendorHash
+  # The upstream default.nix has stale vendorHash for commits with server mode
+  beadsRev = builtins.substring 0 8 (globalInputs.beads.rev or "unknown");
+  beadsPackage = pkgs.buildGoModule {
+    pname = "beads";
+    version = "0.49.1-${beadsRev}";
+    src = globalInputs.beads;
+    subPackages = [ "cmd/bd" ];
+    doCheck = false;
+    # Regenerated vendorHash for commit 93965b4a (has dolt server mode, Go 1.24)
+    vendorHash = "sha256-gwxGv8y4+1+k0741CnOYcyJPTJ5vTrynqPoO8YS9fbQ=";
+    nativeBuildInputs = [ pkgs.git ];
+    meta = with lib; {
+      description = "beads (bd) - An issue tracker designed for AI-supervised coding workflows";
+      homepage = "https://github.com/steveyegge/beads";
+      license = licenses.mit;
+      mainProgram = "bd";
+    };
+  };
+
+  # Gastown - multi-agent workspace manager (no upstream flake.nix yet)
+  # Source is tracked via flake input for renovate updates
+  gastownRev = builtins.substring 0 8 (globalInputs.gastown.rev or "unknown");
+  gastownPackage = pkgs.buildGoModule {
+    pname = "gastown";
+    version = "unstable-${gastownRev}";
+    src = globalInputs.gastown;
+    vendorHash = "sha256-ripY9vrYgVW8bngAyMLh0LkU/Xx1UUaLgmAA7/EmWQU=";
+    subPackages = [ "cmd/gt" ];
+    doCheck = false;
+
+    # Must match ldflags from gastown Makefile - BuiltProperly=1 is required
+    # or gt will error with "This binary was built with 'go build' directly"
+    ldflags = [
+      "-X github.com/steveyegge/gastown/internal/cmd.Version=${gastownRev}"
+      "-X github.com/steveyegge/gastown/internal/cmd.Commit=${gastownRev}"
+      "-X github.com/steveyegge/gastown/internal/cmd.BuildTime=nix-build"
+      "-X github.com/steveyegge/gastown/internal/cmd.BuiltProperly=1"
+    ];
+
+    # Bug fixes not yet merged upstream
+    # Each patch is stored in a separate file for clarity and maintainability
+    patches = [
+      # Fix validateRecipient bug: normalize addresses before comparison
+      ./gastown-fix-validate-recipient.patch
+      # Fix agentBeadToAddress to use title field for hq- prefixed beads
+      ./gastown-fix-agent-bead-address-title.patch
+      # Fix crew/polecat home paths: remove incorrect /rig suffix
+      ./gastown-fix-role-home-paths.patch
+      # Fix town root detection: don't map to Mayor (causes spurious mismatch warnings)
+      ./gastown-fix-town-root-detection.patch
+      # Statusline optimization: skip expensive beads queries for detached sessions
+      # Reduces Dolt CPU from ~70% to ~20% by caching and early-exit
+      ./gastown-statusline-optimization.patch
+    ];
+
+    meta = with lib; {
+      description = "Gas Town - multi-agent workspace manager by Steve Yegge";
+      homepage = "https://github.com/steveyegge/gastown";
+      license = licenses.mit;
+      mainProgram = "gt";
+    };
+  };
+
+  # Perles - TUI for beads issue tracking (no upstream flake.nix yet)
+  # Source is tracked via flake input for renovate updates
+  perlesRev = builtins.substring 0 8 (globalInputs.perles.rev or "unknown");
+  perlesPackage = pkgs.buildGoModule {
+    pname = "perles";
+    version = "unstable-${perlesRev}";
+    src = globalInputs.perles;
+    vendorHash = "sha256-JHERJDzbiqgjWXwRhXVjgDEiDQ3AUXRIONotfPF21B0=";
+    doCheck = false;
+
+    ldflags = [
+      "-X main.version=${perlesRev}"
+    ];
+
+    meta = with lib; {
+      description = "Perles - Terminal UI for beads issue tracking";
+      homepage = "https://github.com/zjrosen/perles";
+      license = licenses.mit;
+      mainProgram = "perles";
+    };
+  };
+
   # Fetch the claude-plugins repository (for humanlayer commands/agents)
   # Update the rev to get newer versions of the commands
   claudePluginsRepo = builtins.fetchGit {
@@ -37,14 +123,17 @@ in
 
   config = mkIf cfg.enable {
     home.packages = [
-      globalInputs.beads.packages.${system}.default
+      beadsPackage
+      gastownPackage
+      perlesPackage
       pkgs.unstable.claude-code
       pkgs.unstable.claude-code-router
       pkgs.unstable.codex
+      pkgs.dolt
+      pkgs.sqlite
 
       # Custom packages
       pkgs.custom.tea-rbw
-      pkgs.custom.perles
     ];
 
     # Install Claude Code humanlayer command and agent plugins
@@ -62,12 +151,14 @@ in
         if [ -f "$file" ]; then
           filename=$(basename "$file" .md)
           dest="$HOME/.claude/commands/humanlayer:''${filename}.md"
+          rm -f "$dest" 2>/dev/null || true
 
           # Copy file and conditionally remove the "model:" line from frontmatter
           ${if cfg.allowArbitraryClaudeCodeModelSelection
             then "cp \"$file\" \"$dest\""
             else "${pkgs.gnused}/bin/sed '/^model:/d' \"$file\" > \"$dest\""
           }
+          chmod u+w "$dest" 2>/dev/null || true
         fi
       done
 
@@ -76,17 +167,19 @@ in
         if [ -f "$file" ]; then
           filename=$(basename "$file" .md)
           dest="$HOME/.claude/agents/humanlayer:''${filename}.md"
+          rm -f "$dest" 2>/dev/null || true
 
           # Copy file and conditionally remove the "model:" line from frontmatter
           ${if cfg.allowArbitraryClaudeCodeModelSelection
             then "cp \"$file\" \"$dest\""
             else "${pkgs.gnused}/bin/sed '/^model:/d' \"$file\" > \"$dest\""
           }
+          chmod u+w "$dest" 2>/dev/null || true
         fi
       done
 
-      # Copy local skills from this repo (with retry for race conditions with running Claude)
-      for file in ${./skills}/*.md; do
+      # Copy local commands from this repo (with retry for race conditions with running Claude)
+      for file in ${./commands}/*.md; do
         if [ -f "$file" ]; then
           filename=$(basename "$file" .md)
           dest="$HOME/.claude/commands/''${filename}.md"
@@ -96,14 +189,47 @@ in
             sleep 0.5
             cp "$file" "$dest" || echo "Warning: Failed to copy $filename.md to commands"
           fi
+          chmod u+w "$dest" 2>/dev/null || true
         fi
       done
 
-      $DRY_RUN_CMD echo "Claude Code humanlayer commands and agents installed successfully${
-        if cfg.allowArbitraryClaudeCodeModelSelection
-        then " (model specifications preserved)"
-        else " (model selection removed)"
-      } + local skills"
+      # Copy local skills (reference materials) to skills subdirectory
+      mkdir -p ~/.claude/commands/skills
+      for file in ${./skills}/*.md; do
+        if [ -f "$file" ]; then
+          filename=$(basename "$file" .md)
+          dest="$HOME/.claude/commands/skills/''${filename}.md"
+          rm -f "$dest" 2>/dev/null || true
+          if ! cp "$file" "$dest" 2>/dev/null; then
+            sleep 0.5
+            cp "$file" "$dest" || echo "Warning: Failed to copy $filename.md to skills"
+          fi
+          chmod u+w "$dest" 2>/dev/null || true
+        fi
+      done
+
+      # Copy micro-skills (compact reusable knowledge referenced by formulas)
+      for file in ${./skills/micro}/*.md; do
+        if [ -f "$file" ]; then
+          dest="$HOME/.claude/commands/skills/$(basename "$file")"
+          rm -f "$dest" 2>/dev/null || true
+          cp "$file" "$dest"
+          chmod u+w "$dest" 2>/dev/null || true
+        fi
+      done
+
+      # Install beads formulas to user-level formula directory
+      mkdir -p ~/.beads/formulas
+      for file in ${./formulas}/*.formula.toml; do
+        if [ -f "$file" ]; then
+          dest="$HOME/.beads/formulas/$(basename "$file")"
+          rm -f "$dest" 2>/dev/null || true
+          cp "$file" "$dest"
+          chmod u+w "$dest" 2>/dev/null || true
+        fi
+      done
+
+      $DRY_RUN_CMD echo "Claude Code plugins installed: humanlayer commands/agents + local commands + local skills + formulas"
     '';
 
     # Set up beads Claude Code integration (hooks for SessionStart/PreCompact)
@@ -111,11 +237,51 @@ in
     home.activation.claudeCodeBeadsSetup = lib.hm.dag.entryAfter ["writeBoundary" "claudeCodeCommands"] ''
       # Run bd setup claude to install hooks into ~/.claude/settings.json
       # This is idempotent - safe to run multiple times
-      ${globalInputs.beads.packages.${system}.default}/bin/bd setup claude 2>/dev/null || true
+      ${beadsPackage}/bin/bd setup claude 2>/dev/null || true
 
       $DRY_RUN_CMD echo "Claude Code beads integration configured (hooks installed)"
     '';
 
+    # Beads timer gate checker (Linux only - uses systemd)
+    # Runs every 5 minutes to auto-resolve expired timer gates across all beads projects
+    # This enables self-scheduling molecules (watchers, patrols, etc.)
+    systemd.user.services.beads-gate-check = lib.mkIf pkgs.stdenv.isLinux {
+      Unit = {
+        Description = "Check and resolve expired beads timer gates";
+      };
+      Service = {
+        Type = "oneshot";
+        # Check gates in all workspaces that have running daemons
+        ExecStart = pkgs.writeShellScript "beads-gate-check-all" ''
+          # Get list of workspaces from daemon registry
+          workspaces=$(${beadsPackage}/bin/bd daemon list --json 2>/dev/null | ${pkgs.jq}/bin/jq -r '.[].workspace // empty' 2>/dev/null)
+
+          if [ -z "$workspaces" ]; then
+            exit 0  # No beads workspaces, nothing to do
+          fi
+
+          for ws in $workspaces; do
+            if [ -d "$ws" ]; then
+              cd "$ws" && ${beadsPackage}/bin/bd gate check --type=timer --quiet 2>/dev/null || true
+            fi
+          done
+        '';
+      };
+    };
+
+    systemd.user.timers.beads-gate-check = lib.mkIf pkgs.stdenv.isLinux {
+      Unit = {
+        Description = "Periodic beads timer gate check";
+      };
+      Timer = {
+        OnBootSec = "5min";
+        OnUnitActiveSec = "5min";
+      };
+      Install = {
+        WantedBy = [ "timers.target" ];
+      };
+    };
+
     # Note: modules must be imported at top-level home config
   };
 }

home/roles/development/formulas/quick-fix.formula.toml

@@ -0,0 +1,115 @@
+# Quick Fix Formula
+#
+# Streamlined workflow for well-understood bugs and small fixes.
+# Skips the deep research and planning phases of RPI - get in, fix, get out.
+#
+# Use when:
+#   - Bug is well-understood (you know what's broken)
+#   - Fix is straightforward (no architectural decisions)
+#   - Change is small (< 100 lines)
+#
+# Use RPI instead when:
+#   - Root cause is unclear
+#   - Multiple approaches possible
+#   - Significant design decisions needed
+
+formula = "quick-fix"
+description = """
+Streamlined workflow for bugs and small fixes.
+
+A faster alternative to RPI for well-understood issues:
+1. Quick investigation to confirm understanding
+2. Implement the fix
+3. Verify with tests
+4. Commit and close
+
+No human gates - designed for quick turnaround on obvious fixes.
+"""
+version = 1
+type = "workflow"
+
+# === Variables ===
+
+[vars.title]
+required = true
+description = "Brief description of the bug/fix"
+
+[vars.bead_id]
+description = "Existing bead ID (creates new if not provided)"
+
+[vars.test_cmd]
+default = "make test"
+description = "Command to verify the fix"
+
+# === Steps ===
+
+[[steps]]
+id = "investigate"
+title = "Investigate: {{title}}"
+description = """
+Quick investigation to confirm understanding of the bug.
+
+Goals:
+- Locate the problematic code
+- Confirm root cause matches expectations
+- Identify files that need changes
+
+This is NOT deep research - spend 5-10 minutes max.
+If the bug is more complex than expected, pivot to RPI workflow.
+
+Output: Mental model of what to fix (no artifact needed).
+"""
+
+[[steps]]
+id = "fix"
+title = "Fix: {{title}}"
+needs = ["investigate"]
+description = """
+Implement the fix.
+
+Guidelines:
+- Make minimal changes to fix the issue
+- Follow existing code patterns
+- Add/update tests if appropriate
+- Keep changes focused (no drive-by refactors)
+
+If the fix grows beyond expectations, pause and consider:
+- Should this be an RPI workflow instead?
+- Should we split into multiple changes?
+"""
+
+[[steps]]
+id = "verify"
+title = "Verify fix"
+needs = ["fix"]
+description = """
+Verify the fix works correctly.
+
+Run: {{test_cmd}}
+
+Also check:
+- Bug is actually fixed (manual verification)
+- No obvious regressions introduced
+- Code compiles/builds cleanly
+
+If tests fail, iterate on the fix step.
+"""
+
+[[steps]]
+id = "commit"
+title = "Commit and close"
+needs = ["verify"]
+description = """
+Commit the fix and close the bead.
+
+Actions:
+1. Stage changes: git add -A
+2. Commit with descriptive message: git commit -m "fix: {{title}}"
+3. Push to remote: git push
+4. Close the bead: bd close {{bead_id}}
+
+Commit message should explain:
+- What was broken
+- How it was fixed
+- Any relevant context
+"""

home/roles/development/formulas/rpi.formula.toml

@@ -0,0 +1,124 @@
+# RPI Formula - Research -> Plan -> Implement
+#
+# Universal workflow for feature development with human gates.
+
+formula = "rpi"
+description = """
+Research -> Plan -> Implement workflow.
+
+Usage:
+  bd pour rpi --var title="Add user preferences"
+  bd pour rpi --var title="Auth" --var bead_id="project-abc" --var test_cmd="nix flake check"
+"""
+version = 1
+type = "workflow"
+
+# ─── Variables ───
+
+[vars.title]
+required = true
+description = "What are we building?"
+
+[vars.bead_id]
+description = "Existing bead ID (creates new if not provided)"
+
+[vars.test_cmd]
+default = "make test"
+description = "Command to run tests"
+
+[vars.lint_cmd]
+default = "make lint"
+description = "Command to run linting"
+
+# ─── Research Phase ───
+
+[[steps]]
+id = "research"
+title = "Research: {{title}}"
+skill = "research-agents"
+description = """
+Conduct comprehensive codebase research.
+
+Goals:
+- Understand current implementation
+- Identify patterns to follow
+- Find relevant files and dependencies
+- Document key discoveries
+
+Output: thoughts/beads-{{bead_id}}/research.md
+"""
+
+# ─── Planning Phase ───
+
+[[steps]]
+id = "plan"
+title = "Plan: {{title}}"
+needs = ["research"]
+type = "human"
+skill = "planning"
+description = """
+Create detailed implementation plan based on research.
+
+Goals:
+- Present understanding and clarify requirements
+- Propose design options with tradeoffs
+- Define phases with success criteria
+- Identify what we're NOT doing
+
+Output: thoughts/beads-{{bead_id}}/plan.md
+"""
+
+[steps.gate]
+type = "human"
+reason = "Plan approval before implementation"
+
+# ─── Implementation Phase ───
+
+[[steps]]
+id = "implement"
+title = "Implement: {{title}}"
+needs = ["plan"]
+description = """
+Execute the approved plan phase by phase.
+
+For each phase:
+1. Make the changes
+2. Run verification: {{test_cmd}}, {{lint_cmd}}
+3. Update plan checkboxes for resumability
+
+Stop and ask if encountering unexpected issues.
+"""
+
+# ─── Verification Phase ───
+
+[[steps]]
+id = "verify"
+title = "Manual verification"
+needs = ["implement"]
+type = "human"
+description = """
+Human confirms implementation works correctly.
+
+Check: feature works, edge cases handled, no regressions.
+Tests: {{test_cmd}} | Lint: {{lint_cmd}}
+"""
+
+[steps.gate]
+type = "human"
+reason = "Confirm implementation is correct"
+
+# ─── Completion ───
+
+[[steps]]
+id = "complete"
+title = "Close bead"
+needs = ["verify"]
+skill = "artifact-format"
+description = """
+Mark work as complete.
+
+Actions:
+- bd update {{bead_id}} --notes="Implementation complete"
+- bd close {{bead_id}} --reason="Completed: {{title}}"
+- bd sync && git push
+"""

home/roles/development/gastown-fix-agent-bead-address-title.patch

@@ -0,0 +1,15 @@
+diff --git a/internal/mail/router.go b/internal/mail/router.go
+--- a/internal/mail/router.go
++++ b/internal/mail/router.go
+@@ -315,7 +315,10 @@ func agentBeadToAddress(bead *agentBead) string {
+ 		}
+
+ 		// For other hq- agents, fall back to description parsing
+-		return parseAgentAddressFromDescription(bead.Description)
++		if bead.Title != "" && strings.Contains(bead.Title, "/") {
++			return bead.Title
++		}
++		return parseAgentAddressFromDescription(bead.Description)
+ 	}
+
+ 	// Handle gt- prefixed IDs (legacy format)

home/roles/development/gastown-fix-agent-bead-rig-prefix.patch

@@ -0,0 +1,35 @@
+diff --git a/internal/mail/router.go b/internal/mail/router.go
+--- a/internal/mail/router.go
++++ b/internal/mail/router.go
+@@ -330,8 +330,29 @@ func agentBeadToAddress(bead *agentBead) string {
+ 	}
+ 
+ 	// Handle gt- prefixed IDs (legacy format)
+-	if !strings.HasPrefix(id, "gt-") {
+-		return "" // Not a valid agent bead ID
++	// Handle rig-specific prefixes: <prefix>-<rig>-<role>-<name>
++	// Examples: j-java-crew-americano -> java/crew/americano
++	idParts := strings.Split(id, "-")
++	if len(idParts) >= 3 {
++		for i, part := range idParts {
++			if part == "crew" || part == "polecat" || part == "polecats" {
++				if i >= 1 && i < len(idParts)-1 {
++					rig := idParts[i-1]
++					name := strings.Join(idParts[i+1:], "-")
++					return rig + "/" + part + "/" + name
++				}
++			}
++			if part == "witness" || part == "refinery" {
++				if i >= 1 {
++					return idParts[i-1] + "/" + part
++				}
++			}
++		}
++	}
++
++	// Handle gt- prefixed IDs (legacy format)
++	if !strings.HasPrefix(id, "gt-") {
++		return "" // Not a valid agent bead ID
+ 	}
+ 
+ 	// Strip prefix

home/roles/development/gastown-fix-copydir-symlinks.patch

@@ -0,0 +1,25 @@
+diff --git a/internal/git/git.go b/internal/git/git.go
+--- a/internal/git/git.go
++++ b/internal/git/git.go
+@@ -73,7 +73,19 @@ func copyDir(src, dest string) error {
+ 		srcPath := filepath.Join(src, entry.Name())
+ 		destPath := filepath.Join(dest, entry.Name())
+ 
+-		if entry.IsDir() {
++		// Handle symlinks (recreate them, do not follow)
++		if entry.Type()&os.ModeSymlink != 0 {
++			linkTarget, err := os.Readlink(srcPath)
++			if err != nil {
++				return err
++			}
++			if err := os.Symlink(linkTarget, destPath); err != nil {
++				return err
++			}
++			continue
++		}
++
++		if entry.IsDir() {
+ 			if err := copyDir(srcPath, destPath); err != nil {
+ 				return err
+ 			}
+

home/roles/development/gastown-fix-role-home-paths.patch

@@ -0,0 +1,18 @@
+diff --git a/internal/cmd/role.go b/internal/cmd/role.go
+--- a/internal/cmd/role.go
++++ b/internal/cmd/role.go
+@@ -326,11 +326,11 @@ func getRoleHome(role Role, rig, polecat, townRoot string) string {
+ 		if rig == "" || polecat == "" {
+ 			return ""
+ 		}
+-		return filepath.Join(townRoot, rig, "polecats", polecat, "rig")
++		return filepath.Join(townRoot, rig, "polecats", polecat)
+ 	case RoleCrew:
+ 		if rig == "" || polecat == "" {
+ 			return ""
+ 		}
+-		return filepath.Join(townRoot, rig, "crew", polecat, "rig")
++		return filepath.Join(townRoot, rig, "crew", polecat)
+ 	default:
+ 		return ""
+ 	}

home/roles/development/gastown-fix-town-root-detection.patch

@@ -0,0 +1,18 @@
+diff --git a/internal/cmd/prime.go b/internal/cmd/prime.go
+--- a/internal/cmd/prime.go
++++ b/internal/cmd/prime.go
+@@ -276,11 +276,12 @@ func detectRole(cwd, townRoot string) RoleInfo {
+ 
+ 	// Check for mayor role
+ 	// At town root, or in mayor/ or mayor/rig/
+ 	if relPath == "." || relPath == "" {
+-		ctx.Role = RoleMayor
+-		return ctx
++		return ctx // RoleUnknown - town root is shared space
+ 	}
++
++	// Check for mayor role: mayor/ or mayor/rig/
+ 	if len(parts) >= 1 && parts[0] == "mayor" {
+ 		ctx.Role = RoleMayor
+ 		return ctx
+ 	}

home/roles/development/gastown-fix-validate-recipient.patch

@@ -0,0 +1,13 @@
+diff --git a/internal/mail/router.go b/internal/mail/router.go
+index b864c069..4b6a045b 100644
+--- a/internal/mail/router.go
++++ b/internal/mail/router.go
+@@ -646,7 +646,7 @@ func (r *Router) validateRecipient(identity string) error {
+ 	}
+ 
+ 	for _, agent := range agents {
+-		if agentBeadToAddress(agent) == identity {
++		if AddressToIdentity(agentBeadToAddress(agent)) == AddressToIdentity(identity) {
+ 			return nil // Found matching agent
+ 		}
+ 	}

home/roles/development/gastown-statusline-optimization.patch

@@ -0,0 +1,135 @@
+diff --git a/internal/cmd/statusline.go b/internal/cmd/statusline.go
+index 2edf1be8..00253eea 100644
+--- a/internal/cmd/statusline.go
++++ b/internal/cmd/statusline.go
+@@ -6,6 +6,7 @@ import (
+ 	"path/filepath"
+ 	"sort"
+ 	"strings"
++	"time"
+ 
+ 	"github.com/spf13/cobra"
+ 	"github.com/steveyegge/gastown/internal/beads"
+@@ -14,6 +15,37 @@ import (
+ 	"github.com/steveyegge/gastown/internal/tmux"
+ 	"github.com/steveyegge/gastown/internal/workspace"
+ )
++// statusLineCacheTTL is how long cached status output remains valid.
++const statusLineCacheTTL = 10 * time.Second
++
++// statusLineCachePath returns the cache file path for a session.
++func statusLineCachePath(session string) string {
++	return filepath.Join(os.TempDir(), fmt.Sprintf("gt-status-%s", session))
++}
++
++// getStatusLineCache returns cached status if fresh, empty string otherwise.
++func getStatusLineCache(session string) string {
++	path := statusLineCachePath(session)
++	info, err := os.Stat(path)
++	if err != nil {
++		return ""
++	}
++	if time.Since(info.ModTime()) > statusLineCacheTTL {
++		return ""
++	}
++	data, err := os.ReadFile(path)
++	if err != nil {
++		return ""
++	}
++	return string(data)
++}
++
++// setStatusLineCache writes status to cache file.
++func setStatusLineCache(session, status string) {
++	path := statusLineCachePath(session)
++	_ = os.WriteFile(path, []byte(status), 0644)
++}
++
+ 
+ var (
+ 	statusLineSession string
+@@ -34,6 +66,19 @@ func init() {
+ func runStatusLine(cmd *cobra.Command, args []string) error {
+ 	t := tmux.NewTmux()
+ 
++	// Optimization: skip expensive beads queries for detached sessions
++	if statusLineSession != "" {
++		if !t.IsSessionAttached(statusLineSession) {
++			fmt.Print("○ |")
++			return nil
++		}
++		// Check cache for attached sessions too
++		if cached := getStatusLineCache(statusLineSession); cached != "" {
++			fmt.Print(cached)
++			return nil
++		}
++	}
++
+ 	// Get session environment
+ 	var rigName, polecat, crew, issue, role string
+ 
+@@ -150,7 +195,11 @@ func runWorkerStatusLine(t *tmux.Tmux, session, rigName, polecat, crew, issue st
+ 
+ 	// Output
+ 	if len(parts) > 0 {
+-		fmt.Print(strings.Join(parts, " | ") + " |")
++		output := strings.Join(parts, " | ") + " |"
++		if statusLineSession != "" {
++			setStatusLineCache(statusLineSession, output)
++		}
++		fmt.Print(output)
+ 	}
+ 
+ 	return nil
+@@ -389,7 +438,11 @@ func runMayorStatusLine(t *tmux.Tmux) error {
+ 		}
+ 	}
+ 
+-	fmt.Print(strings.Join(parts, " | ") + " |")
++	output := strings.Join(parts, " | ") + " |"
++	if statusLineSession != "" {
++		setStatusLineCache(statusLineSession, output)
++	}
++	fmt.Print(output)
+ 	return nil
+ }
+ 
+@@ -458,7 +511,11 @@ func runDeaconStatusLine(t *tmux.Tmux) error {
+ 		}
+ 	}
+ 
+-	fmt.Print(strings.Join(parts, " | ") + " |")
++	output := strings.Join(parts, " | ") + " |"
++	if statusLineSession != "" {
++		setStatusLineCache(statusLineSession, output)
++	}
++	fmt.Print(output)
+ 	return nil
+ }
+ 
+@@ -526,7 +583,11 @@ func runWitnessStatusLine(t *tmux.Tmux, rigName string) error {
+ 		}
+ 	}
+ 
+-	fmt.Print(strings.Join(parts, " | ") + " |")
++	output := strings.Join(parts, " | ") + " |"
++	if statusLineSession != "" {
++		setStatusLineCache(statusLineSession, output)
++	}
++	fmt.Print(output)
+ 	return nil
+ }
+ 
+@@ -617,7 +678,11 @@ func runRefineryStatusLine(t *tmux.Tmux, rigName string) error {
+ 		}
+ 	}
+ 
+-	fmt.Print(strings.Join(parts, " | ") + " |")
++	output := strings.Join(parts, " | ") + " |"
++	if statusLineSession != "" {
++		setStatusLineCache(statusLineSession, output)
++	}
++	fmt.Print(output)
+ 	return nil
+ }
+ 

home/roles/development/skills/bd_workflow.md

@@ -0,0 +1,230 @@
+---
+description: How to use the bd (beads) CLI for issue tracking, dependencies, and workflow orchestration
+---
+
+# BD Workflow
+
+The `bd` CLI is a git-backed issue tracker with first-class dependency support. Use it for multi-session work, blocking relationships, and persistent memory across conversation compaction.
+
+## When to Use BD vs TodoWrite
+
+| Use BD | Use TodoWrite |
+|--------|---------------|
+| Work spans multiple sessions | Single-session tasks |
+| Dependencies between tasks | Independent subtasks |
+| Need audit trail in git | Ephemeral tracking |
+| Cross-repo coordination | Local project only |
+| Resuming after compaction | Simple task lists |
+
+## Core Commands
+
+### Creating Issues
+
+```bash
+bd create "Issue title"                          # Basic task
+bd create "Bug title" --type=bug --priority=1    # P1 bug
+bd create "Feature" --type=feature -d "Details"  # With description
+bd q "Quick capture"                             # Output only ID
+```
+
+### Managing Issues
+
+```bash
+bd show <id>                    # View issue details
+bd show <id> --children         # View children of epic
+bd list                         # List open issues (default 50)
+bd list --all                   # Include closed
+bd list -s in_progress          # Filter by status
+bd list -t bug -p 0             # P0 bugs
+bd list --pretty                # Tree format
+```
+
+### Updating Issues
+
+```bash
+bd update <id> --status=in_progress    # Start work
+bd update <id> --status=blocked        # Mark blocked
+bd update <id> --claim                 # Claim atomically
+bd update <id> --add-label=urgent      # Add label
+bd update <id> -d "New description"    # Update description
+```
+
+### Closing Issues
+
+```bash
+bd close <id>                          # Close issue
+bd close <id> --continue               # Auto-advance to next step
+bd close <id> --suggest-next           # Show newly unblocked
+```
+
+## Finding Work
+
+```bash
+bd ready                     # Ready issues (no blockers)
+bd ready --mol <mol-id>      # Ready steps in molecule
+bd ready -n 5                # Limit to 5
+bd ready --assignee me       # Assigned to me
+bd blocked                   # Show blocked issues
+bd blocked --parent <id>     # Blocked within epic
+```
+
+## Dependency Management
+
+### Creating Dependencies
+
+```bash
+bd dep <blocker> --blocks <blocked>    # A blocks B
+bd dep add <blocked> <blocker>         # Same as above
+bd dep relate <id1> <id2>              # Bidirectional link
+```
+
+### Viewing Dependencies
+
+```bash
+bd dep list <id>             # Show dependencies
+bd dep tree <id>             # Dependency tree
+bd dep cycles                # Detect cycles
+```
+
+### Removing Dependencies
+
+```bash
+bd dep remove <blocked> <blocker>      # Remove dependency
+bd dep unrelate <id1> <id2>            # Remove relation
+```
+
+## Sync Workflow
+
+BD syncs issues via git. The daemon handles this automatically, but manual sync is available:
+
+```bash
+bd sync                      # Full sync (pull, merge, push)
+bd sync --flush-only         # Export to JSONL only
+bd sync --import-only        # Import from JSONL only
+bd sync --status             # Show sync branch diff
+bd sync --squash             # Accumulate without commit
+```
+
+## Formula and Molecule Workflow
+
+Formulas are reusable workflow templates. Molecules are instantiated workflows.
+
+### Formulas
+
+```bash
+bd formula list                        # List available formulas
+bd formula list --type=workflow        # Filter by type
+bd formula show <name>                 # Show formula details
+bd cook <formula>                      # Compile to proto (stdout)
+bd cook <formula> --var name=auth      # With variable substitution
+bd cook <formula> --dry-run            # Preview steps
+bd cook <formula> --persist            # Save to database
+```
+
+### Molecules: Pour vs Wisp
+
+| pour (persistent) | wisp (ephemeral) |
+|-------------------|------------------|
+| Feature implementations | Release workflows |
+| Multi-session work | Patrol cycles |
+| Audit trail needed | Health checks |
+| Git-synced | Local only |
+
+```bash
+# Persistent molecule (liquid phase)
+bd mol pour <proto> --var name=auth
+
+# Ephemeral molecule (vapor phase)
+bd mol wisp <proto> --var version=1.0
+bd mol wisp list                       # List wisps
+bd mol wisp gc                         # Garbage collect
+```
+
+### Tracking Molecule Progress
+
+```bash
+bd mol show <mol-id>                   # Show structure
+bd mol show <mol-id> --parallel        # Parallelizable steps
+bd mol current                         # Where am I?
+bd mol current <mol-id>                # Status for molecule
+bd mol progress <mol-id>               # Progress summary + ETA
+```
+
+### Molecule Lifecycle
+
+```bash
+bd mol squash <mol-id>                 # Condense to digest
+bd mol burn <mol-id>                   # Delete wisp
+bd mol distill <epic-id>               # Extract formula from epic
+```
+
+## Gates and Human Checkpoints
+
+Gates are async wait conditions that block workflow steps:
+
+| Gate Type | Wait Condition |
+|-----------|---------------|
+| human | Manual `bd close` |
+| timer | Timeout expires |
+| gh:run | GitHub workflow completes |
+| gh:pr | PR merges |
+| bead | Cross-rig bead closes |
+
+```bash
+bd gate list                           # Show open gates
+bd gate list --all                     # Include closed
+bd gate check                          # Evaluate all gates
+bd gate check --type=bead              # Check bead gates only
+bd gate resolve <id>                   # Close manually
+```
+
+## Common Patterns
+
+### Starting Work on a Bead
+
+```bash
+bd update <id> --status=in_progress
+# ... do work ...
+bd close <id>
+```
+
+### Creating Related Issues
+
+```bash
+bd create "Main task" --deps "blocks:<other-id>"
+bd dep add <new-id> <blocker-id>
+```
+
+### Working Through a Molecule
+
+```bash
+bd mol pour my-workflow --var name=feature
+bd ready --mol <mol-id>                # Find next step
+bd update <step-id> --claim            # Claim step
+# ... do work ...
+bd close <step-id> --continue          # Close and advance
+```
+
+### Quick Status Check
+
+```bash
+bd ready -n 3                          # Top 3 ready items
+bd list -s in_progress                 # What's in flight?
+bd blocked                             # What's stuck?
+```
+
+## Useful Flags
+
+| Flag | Effect |
+|------|--------|
+| `--json` | JSON output for scripting |
+| `--quiet` | Suppress non-essential output |
+| `--dry-run` | Preview without executing |
+| `--pretty` | Tree format display |
+
+## Integration Notes
+
+- BD auto-syncs via daemon (check with `bd info`)
+- Issues stored in `.beads/` directory
+- JSONL files sync through git
+- Use `bd doctor` if something seems wrong

home/roles/development/skills/micro/artifact-format.md

@@ -0,0 +1,123 @@
+---
+description: How to structure research and plan artifacts in thoughts/
+---
+
+# Artifact Format
+
+Standardized format for thoughts/ artifacts. All beads-related artifacts should follow these conventions for consistency and machine parseability.
+
+## Frontmatter (Required)
+
+Every artifact MUST include YAML frontmatter:
+
+```yaml
+---
+date: 2026-01-15T10:00:00-08:00  # ISO 8601 with timezone
+bead_id: project-abc              # Bead identifier
+bead_title: "Title of the bead"   # Human-readable title
+author: claude                    # Who created this
+git_commit: abc123def             # Commit hash at creation
+branch: main                      # Branch name
+repository: repo-name             # Repository name
+status: draft|complete            # Artifact status
+---
+```
+
+### Gathering Metadata
+
+```bash
+git rev-parse HEAD                           # Current commit
+git branch --show-current                    # Current branch
+basename $(git rev-parse --show-toplevel)    # Repo name
+date -Iseconds                               # ISO timestamp
+```
+
+## Research Artifact Structure
+
+Location: `thoughts/beads-{bead-id}/research.md`
+
+```markdown
+# Research: {bead title}
+
+**Bead**: {bead-id}
+**Date**: {timestamp}
+**Git Commit**: {commit hash}
+
+## Research Question
+{Original question from bead description}
+
+## Summary
+{2-3 sentence overview answering the research question}
+
+## Key Discoveries
+- {Finding with file:line reference}
+- {Pattern or convention found}
+- {Architectural decision documented}
+
+## Architecture
+{Current patterns and conventions in the codebase}
+
+## Code References
+- `path/to/file.py:123` - Description of relevance
+- `another/file.ts:45-67` - Description of relevance
+
+## Open Questions
+{Areas needing further investigation or human clarification}
+```
+
+## Plan Artifact Structure
+
+Location: `thoughts/beads-{bead-id}/plan.md`
+
+```markdown
+# {Title} Implementation Plan
+
+## Overview
+{What we're implementing and why - 1-2 sentences}
+
+## Current State
+{What exists now, key constraints discovered}
+
+### Key Discoveries
+- {Finding with file:line reference}
+- {Pattern to follow}
+
+## Desired End State
+{Specification of what success looks like}
+
+## What We're NOT Doing
+{Explicitly list out-of-scope items}
+
+## Phase 1: {Descriptive Name}
+
+### Overview
+{What this phase accomplishes}
+
+### Changes
+- [ ] {Specific change with file path}
+- [ ] {Another change}
+
+### Success Criteria
+
+#### Automated
+- [ ] Tests pass: `{test command}`
+- [ ] Lint passes: `{lint command}`
+
+#### Manual
+- [ ] {Human verification step}
+
+## Phase 2: {Descriptive Name}
+{Repeat structure...}
+
+## References
+- Bead: {bead-id}
+- Research: `thoughts/beads-{bead-id}/research.md`
+```
+
+## Key Principles
+
+1. **Always include file:line references** - Makes artifacts actionable
+2. **Separate automated vs manual verification** - Enables agent autonomy
+3. **Use checkboxes for phases** - Enables resumability after interruption
+4. **Keep frontmatter machine-parseable** - Enables tooling integration
+5. **Link related artifacts** - Research links to plan, plan links to bead

home/roles/development/skills/micro/planning.md

@@ -0,0 +1,121 @@
+---
+description: How to create effective implementation plans with phased delivery and clear success criteria
+---
+
+# Planning
+
+Create implementation plans that enable incremental, verifiable progress.
+
+## Core Principles
+
+1. **Incremental delivery**: Each phase should produce working, testable changes
+2. **Clear checkpoints**: Success criteria that can be verified without ambiguity
+3. **Buy-in before detail**: Confirm understanding and approach before writing specifics
+4. **Explicit scope**: State what we're NOT doing to prevent scope creep
+
+## Plan Document Structure
+
+```markdown
+# {Feature} Implementation Plan
+
+## Overview
+{1-2 sentences: what we're building and why}
+
+## Current State Analysis
+{What exists now, key constraints, file:line references}
+
+## Desired End State
+{Specification of outcome and how to verify it}
+
+## What We're NOT Doing
+{Explicit out-of-scope items}
+
+## Phase 1: {Descriptive Name}
+### Overview
+{What this phase accomplishes - should be independently valuable}
+
+### Changes Required
+{Specific files and modifications with code snippets}
+
+### Success Criteria
+#### Automated Verification
+- [ ] Tests pass: `{test command}`
+- [ ] Lint passes: `{lint command}`
+
+#### Manual Verification
+- [ ] {Human-observable outcome}
+
+## Testing Strategy
+{Unit tests, integration tests, manual testing steps}
+
+## References
+{Links to research, related files, similar implementations}
+```
+
+## Phase Design
+
+Good phases are:
+- **Self-contained**: Completable in one session
+- **Testable**: Has clear pass/fail criteria
+- **Reversible**: Can be rolled back if needed
+- **Incremental**: Builds on previous phases without requiring all phases
+
+Bad phases are:
+- "Refactor everything" (too broad)
+- "Add helper function" (too granular)
+- Phases that only work if ALL phases complete
+
+## Success Criteria Guidelines
+
+**Automated Verification** (agent-runnable):
+- Test commands: `make test`, `npm test`, `nix flake check`
+- Lint/format: `make lint`, `cargo fmt --check`
+- Type checking: `make typecheck`, `tsc --noEmit`
+- Build verification: `make build`, `nix build`
+
+**Manual Verification** (requires human):
+- UI/UX functionality and appearance
+- Performance under realistic conditions
+- Edge cases hard to automate
+- Integration with external systems
+
+**From Contribution Guidelines** (if CONTRIBUTING.md exists):
+- Include any testing requirements specified
+- Reference the guideline: "Per CONTRIBUTING.md: {requirement}"
+
+## Presenting Understanding
+
+Before writing the plan, confirm alignment:
+
+```
+Based on the requirements and my research, I understand we need to [summary].
+
+I've found that:
+- [Current implementation detail with file:line]
+- [Relevant pattern or constraint]
+- [Potential complexity identified]
+
+Questions my research couldn't answer:
+- [Specific technical question requiring judgment]
+```
+
+Only ask questions you genuinely cannot answer through code investigation.
+
+## Design Options Pattern
+
+When multiple approaches exist:
+
+```
+**Design Options:**
+1. [Option A] - [1-sentence description]
+   - Pro: [benefit]
+   - Con: [drawback]
+
+2. [Option B] - [1-sentence description]
+   - Pro: [benefit]
+   - Con: [drawback]
+
+Which approach aligns best with [relevant consideration]?
+```
+
+Get buy-in on approach before detailing phases.

home/roles/development/skills/micro/pr-description.md

@@ -0,0 +1,68 @@
+---
+description: How to write comprehensive PR descriptions that help reviewers understand changes
+---
+
+# PR Description
+
+Write PR descriptions that help reviewers understand what changed and why.
+
+## Structure
+
+Use this standard structure for PR descriptions:
+
+```markdown
+## Summary
+<1-3 bullet points of what changed and why>
+
+## Context
+<Why this change was needed - the problem being solved>
+<Link to related issues/tickets>
+
+## Changes
+<Detailed breakdown by area/component>
+- Area 1: What changed and why
+- Area 2: What changed and why
+
+## Testing
+<How this was verified>
+- Automated: Tests added/updated, CI status
+- Manual: Steps to verify functionality
+
+## Screenshots (if UI changes)
+<Before/after screenshots if applicable>
+```
+
+## Guidelines
+
+### Lead with WHY, not WHAT
+- The diff shows WHAT changed - your description explains WHY
+- Start with the problem being solved
+- Explain the approach chosen and alternatives considered
+
+### Link to context
+- Reference related issues: `Fixes #123` or `Relates to #456`
+- Link to design docs or discussions
+- Mention dependent PRs if any
+
+### Call out review areas
+- Highlight areas needing careful review
+- Note any tricky or non-obvious code
+- Point out architectural decisions
+
+### Note breaking changes prominently
+- Use a dedicated "Breaking Changes" section if applicable
+- Explain migration path for consumers
+- List any deprecations
+
+### Be scannable
+- Use bullet points over paragraphs
+- Keep sections focused and concise
+- Put the most important info first
+
+## Anti-patterns to Avoid
+
+- Empty descriptions or just "fixes bug"
+- Repeating the commit messages verbatim
+- Including irrelevant implementation details
+- Missing context on why the change was made
+- Forgetting to mention breaking changes

home/roles/development/skills/micro/research-agents.md

@@ -0,0 +1,49 @@
+---
+description: How to spawn and coordinate research sub-agents
+---
+
+# Research Agents
+
+Use parallel sub-agents for efficient codebase research.
+
+## Available Agents
+
+| Agent | Purpose |
+|-------|---------|
+| codebase-locator | Find WHERE files and components live |
+| codebase-analyzer | Understand HOW specific code works |
+| codebase-pattern-finder | Find examples of existing patterns |
+| thoughts-locator | Discover relevant documents in thoughts/ |
+
+## Spawning Protocol
+
+1. **Decompose** - Break the research question into 3-5 specific questions
+2. **Spawn parallel** - Use one Task call with multiple agents
+3. **Be specific** - Include directories and file patterns in prompts
+4. **Wait for all** - Do not synthesize until ALL agents complete
+5. **Synthesize** - Combine findings into coherent summary with file:line references
+
+## Example
+
+```
+Task(codebase-locator, "Find all files related to authentication in src/")
+Task(codebase-analyzer, "Explain how JWT tokens are validated in src/auth/")
+Task(codebase-pattern-finder, "Find examples of middleware patterns in src/")
+Task(thoughts-locator, "Find documents about auth design decisions in thoughts/")
+```
+
+## Key Principles
+
+- **Parallel when different** - Run agents in parallel when searching for different things
+- **WHAT not HOW** - Each agent knows its job; tell it what you need, not how to search
+- **Document, don't evaluate** - Agents should describe what exists, not critique it
+- **Specific directories** - Always scope searches to relevant directories
+- **File references** - Include specific file:line references in synthesis
+
+## Agent Prompts
+
+When spawning agents, include:
+- The specific question or goal
+- Relevant directories to search
+- Reminder to document (not evaluate) what they find
+- Request for file:line references in findings

home/roles/development/skills/parallel_beads.md

@@ -1,205 +0,0 @@
----
-description: Orchestrate parallel bead processing with worktrees, PRs, and reviews
----
-
-# Parallel Beads Workflow
-
-This skill orchestrates parallel bead processing using subagents. Each bead gets its own worktree, implementation, PR, and review.
-
-## Phase 1: Selection
-
-1. **Get ready beads**: Run `bd ready` to list all beads with no blockers
-2. **Present selection**: Use `AskUserQuestion` with `multiSelect: true` to let the user choose which beads to work on
-   - Include bead ID and title for each option
-   - Allow selection of multiple beads
-
-Example:
-```
-AskUserQuestion with:
-- question: "Which beads do you want to work on in parallel?"
-- multiSelect: true
-- options from bd ready output
-```
-
-## Phase 2: Parallel Implementation
-
-For each selected bead, launch a subagent using the Task tool. All subagents should be launched in parallel (single message with multiple Task tool calls).
-
-### Subagent Instructions Template
-
-Each implementation subagent should receive these instructions:
-
-```
-Work on bead [BEAD_ID]: [BEAD_TITLE]
-
-1. **Create worktree**:
-   - Branch name: `bead/[BEAD_ID]`
-   - Worktree path: `~/wt/[REPO_NAME]/[BEAD_ID]`
-   - Command: `git worktree add -b bead/[BEAD_ID] ~/wt/[REPO_NAME]/[BEAD_ID]`
-
-2. **Review the bead requirements**:
-   - Run `bd show [BEAD_ID]` to understand the acceptance criteria
-   - Note any external issue references (GitHub issues, Linear tickets, etc.)
-
-3. **Implement the changes**:
-   - Work in the worktree directory
-   - Complete all acceptance criteria listed in the bead
-   - Run any relevant tests or checks
-
-4. **Commit and push**:
-   - Stage all changes: `git add -A`
-   - Create a descriptive commit message
-   - Push the branch: `git push -u origin bead/[BEAD_ID]`
-
-5. **Create a PR**:
-   - Detect hosting provider from origin URL: `git remote get-url origin`
-   - If URL contains `github.com`, use `gh`; otherwise use `tea` (Gitea/Forgejo)
-   - PR title: "[BEAD_ID] [BEAD_TITLE]"
-   - PR body must include:
-     - Reference to bead ID: "Implements bead: [BEAD_ID]"
-     - Any external issue references from the bead (e.g., "Closes #123")
-     - Summary of changes
-   - For GitHub (`gh`):
-     ```bash
-     gh pr create --title "[BEAD_ID] [BEAD_TITLE]" --body "$(cat <<'EOF'
-     ## Summary
-     [Brief description of changes]
-
-     ## Bead Reference
-     Implements bead: [BEAD_ID]
-
-     ## External Issues
-     [Any linked issues from the bead]
-
-     ## Changes
-     - [List of changes made]
-     EOF
-     )"
-     ```
-   - For Gitea (`tea`):
-     ```bash
-     tea pr create --head bead/[BEAD_ID] --base main \
-       --title "[BEAD_ID] [BEAD_TITLE]" \
-       --description "## Summary
-     [Brief description of changes]
-
-     ## Bead Reference
-     Implements bead: [BEAD_ID]
-
-     ## External Issues
-     [Any linked issues from the bead]
-
-     ## Changes
-     - [List of changes made]"
-     ```
-
-6. **Update bead status**:
-   - Mark the bead as "in_review": `bd update [BEAD_ID] --status=in_review`
-   - Add the PR URL to the bead notes: `bd update [BEAD_ID] --notes="$(bd show [BEAD_ID] --json | jq -r '.notes')
-
-PR: [PR_URL]"`
-
-7. **Report results**:
-   - Return: PR URL, bead ID, success/failure status
-   - If blocked or unable to complete, explain what's blocking progress
-```
-
-### Launching Subagents
-
-Use `subagent_type: "general-purpose"` for implementation subagents. Launch all selected beads' subagents in a single message for parallel execution:
-
-```
-<Task calls for each selected bead - all in one message>
-```
-
-Collect results from all subagents before proceeding.
-
-## Phase 3: Parallel Review
-
-After all implementation subagents complete, launch review subagents for each PR.
-
-### Review Subagent Instructions Template
-
-```
-Review PR for bead [BEAD_ID]
-
-1. **Detect hosting provider**: Run `git remote get-url origin` - if it contains `github.com` use `gh`, otherwise use `tea`
-
-2. **Read the PR**:
-   - For GitHub: `gh pr view [PR_NUMBER] --json title,body,additions,deletions,files`
-   - For Gitea: `tea pr view [PR_NUMBER]`
-   - View the diff: `git diff main...bead/[BEAD_ID]`
-
-3. **Review against acceptance criteria**:
-   - Run `bd show [BEAD_ID]` to get the acceptance criteria
-   - Verify each criterion is addressed
-
-4. **Leave review comments**:
-   - For GitHub: `gh pr review [PR_NUMBER] --comment --body "[COMMENTS]"`
-   - For Gitea: `tea pr review [PR_NUMBER] --comment "[COMMENTS]"`
-   - Include:
-     - Acceptance criteria checklist (which are met, which might be missing)
-     - Code quality observations
-     - Suggestions for improvement
-
-5. **Return summary**:
-   - Overall assessment (ready to merge / needs changes)
-   - Key findings
-```
-
-Launch all review subagents in parallel.
-
-## Phase 4: Cleanup and Summary
-
-After reviews complete:
-
-1. **Clean up worktrees**:
-   ```bash
-   git worktree remove ~/wt/[REPO_NAME]/[BEAD_ID] --force
-   ```
-   Do this for each bead's worktree.
-
-2. **Provide final summary**:
-   Present a table or list with:
-   - Bead ID
-   - PR URL
-   - Status (success / failed / blocked)
-   - Review summary
-   - Any failures or blockers encountered
-
-Example output:
-```
-## Parallel Beads Summary
-
-| Bead | PR | Bead Status | Review |
-|------|-----|-------------|--------|
-| beads-abc | #123 | in_review | Approved |
-| beads-xyz | #124 | in_review | Needs changes |
-| beads-123 | - | open (failed) | Blocked by missing dependency |
-
-### Failures/Blockers
-- beads-123: Could not complete because [reason]
-
-### Next Steps
-- Review PRs that need changes
-- Address blockers for failed beads
-- Run `/reconcile_beads` after PRs are merged to close beads
-```
-
-## Error Handling
-
-- **Subagent failures**: If a subagent fails or times out, note it in the summary but continue with other beads
-- **PR creation failures**: Report the error but continue with reviews of successful PRs
-- **Worktree conflicts**: If a worktree already exists, ask the user if they want to remove it or skip that bead
-
-## Resource Limits
-
-- Consider limiting concurrent subagents to 3-5 to avoid overwhelming system resources
-- If user selects more beads than the limit, process them in batches
-
-## Notes
-
-- This workflow integrates with the beads system (`bd` commands)
-- Worktrees are created in `~/wt/[REPO_NAME]/` by convention
-- Each bead gets its own isolated branch and worktree
-- PRs automatically reference the bead ID for traceability

home/roles/emacs/doom/config.el

@@ -53,6 +53,22 @@
 ;; change `org-directory'. It must be set before org loads!
 (setq org-directory "~/org/")
 (after! org
+  ;; Skip recurring events past their CALDAV_UNTIL date
+  ;; org-caldav ignores UNTIL from RRULE, so we store it as a property
+  ;; and filter here in the agenda
+  (defun my/skip-if-past-until ()
+    "Return non-nil if entry has CALDAV_UNTIL and current date is past it."
+    (let ((until-str (org-entry-get nil "CALDAV_UNTIL")))
+      (when (and until-str
+                 (string-match "^\\([0-9]\\{4\\}\\)\\([0-9]\\{2\\}\\)\\([0-9]\\{2\\}\\)" until-str))
+        (let* ((until-year (string-to-number (match-string 1 until-str)))
+               (until-month (string-to-number (match-string 2 until-str)))
+               (until-day (string-to-number (match-string 3 until-str)))
+               (until-time (encode-time 0 0 0 until-day until-month until-year))
+               (today (current-time)))
+          (when (time-less-p until-time today)
+            (org-end-of-subtree t))))))
+
   (setq org-agenda-span 'week
         org-agenda-start-with-log-mode t
         my-agenda-dirs '("projects" "roam")
@@ -61,6 +77,7 @@
                                                                   "\.org$"))
                                                      my-agenda-dirs))
         org-log-done 'time
+        org-agenda-skip-function-global #'my/skip-if-past-until
         org-agenda-custom-commands '(("n" "Agenda"
                                       ((agenda "")
                                        (tags-todo "-someday-recurring")))
@@ -83,25 +100,135 @@
        "d" #'org-agenda-day-view
        "w" #'org-agenda-week-view))
 
-;; (use-package! org-caldav
-;;   :defer t
-;;   :config
-;;   (setq org-caldav-url "https://nextcloud.johnogle.info/remote.php/dav/calendars/johno"
-;;         org-caldav-calendar-id "personal"
-;;         org-icalendar-timezone "America/Los_Angeles"
-;;         org-caldav-inbox "~/org/calendar.org"
-;;         org-caldav-files nil
-;;         org-caldav-sync-direction 'cal->org))
+;; org-caldav: Sync Org entries with Nextcloud CalDAV
+;; Setup requirements:
+;; 1. Create Nextcloud app password: Settings -> Security -> Devices & sessions
+;; 2. Store in rbw: rbw add nextcloud-caldav (put app password as the secret)
+;; 3. Run: doom sync
+;; 4. Test: M-x my/org-caldav-sync-with-rbw (or SPC o a s)
+;;
+;; Note: Conflict resolution is "Org always wins" - treat Org as source of truth
+;; for entries that originated in Org.
 
-(defun my/get-rbw-password (alias)
-  "Return the password for ALIAS via rbw, unlocking the vault only if needed."
-  (let* ((cmd     (format "rbw get %s 2>&1" alias))
-         (output  (shell-command-to-string cmd)))
-    (string-trim output)))
+;; Define sync wrapper before use-package (so keybinding works)
+(defun my/org-caldav-sync-with-rbw ()
+  "Run org-caldav-sync with credentials from rbw embedded in URL."
+  (interactive)
+  (require 'org)
+  (require 'org-caldav)
+  (let* ((password (my/get-rbw-password "nextcloud-caldav"))
+         ;; Embed credentials in URL (url-encode password in case of special chars)
+         (encoded-pass (url-hexify-string password)))
+    (setq org-caldav-url
+          (format "https://johno:%s@nextcloud.johnogle.info/remote.php/dav/calendars/johno"
+                  encoded-pass))
+    (org-caldav-sync)))
+
+(use-package! org-caldav
+  :after org
+  :commands (org-caldav-sync my/org-caldav-sync-with-rbw)
+  :init
+  (map! :leader
+        (:prefix ("o" . "open")
+         (:prefix ("a" . "agenda/calendar")
+          :desc "Sync CalDAV" "s" #'my/org-caldav-sync-with-rbw)))
+  :config
+  ;; Nextcloud CalDAV base URL (credentials added dynamically by sync wrapper)
+  (setq org-caldav-url "https://nextcloud.johnogle.info/remote.php/dav/calendars/johno")
+
+  ;; Timezone for iCalendar export
+  (setq org-icalendar-timezone "America/Los_Angeles")
+
+  ;; Sync state storage (in org directory for multi-machine sync)
+  (setq org-caldav-save-directory (expand-file-name ".org-caldav/" org-directory))
+
+  ;; Backup file for entries before modification
+  (setq org-caldav-backup-file (expand-file-name ".org-caldav/backup.org" org-directory))
+
+  ;; Limit past events to 30 days (avoids uploading years of scheduled tasks)
+  (setq org-caldav-days-in-past 30)
+
+  ;; Sync behavior: bidirectional by default
+  (setq org-caldav-sync-direction 'twoway)
+
+  ;; What changes from calendar sync back to Org (conservative: title and timestamp only)
+  (setq org-caldav-sync-changes-to-org 'title-and-timestamp)
+
+  ;; Deletion handling: never auto-delete to prevent accidental mass deletion
+  (setq org-caldav-delete-calendar-entries 'never)
+  (setq org-caldav-delete-org-entries 'never)
+
+  ;; Enable TODO/VTODO sync
+  (setq org-icalendar-include-todo 'all)
+  (setq org-caldav-sync-todo t)
+
+  ;; Map VTODO percent-complete to org-todo-keywords
+  ;; Format: (PERCENT "KEYWORD") - percent thresholds map to states
+  (setq org-caldav-todo-percent-states
+        '((0 "TODO")
+          (25 "WAIT")
+          (50 "IN-PROGRESS")
+          (100 "DONE")
+          (100 "KILL")))
+
+  ;; Allow export with broken links (mu4e links can't be resolved during export)
+  (setq org-export-with-broken-links 'mark)
+
+  ;; Calendar-specific configuration
+  (setq org-caldav-calendars
+        '(;; Personal calendar: two-way sync with family-shared Nextcloud calendar
+          (:calendar-id "personal"
+           :inbox "~/org/personal-calendar.org"
+           :files ("~/org/personal-calendar.org"))
+
+          ;; Tasks calendar: one-way sync (org → calendar only)
+          ;; SCHEDULED/DEADLINE items from todo.org push to private Tasks calendar.
+          ;; No inbox = no download from calendar (effectively one-way).
+          ;; Note: Create 'tasks' calendar in Nextcloud first, keep it private.
+          (:calendar-id "tasks"
+           :files ("~/org/todo.org"))))
+
+  ;; Handle UNTIL in recurring events
+  ;; org-caldav ignores UNTIL from RRULE - events repeat forever.
+  ;; This advice extracts UNTIL and stores it as a property for agenda filtering.
+  (defun my/org-caldav-add-until-property (orig-fun eventdata-alist)
+    "Advice to store CALDAV_UNTIL property for recurring events."
+    (let ((result (funcall orig-fun eventdata-alist)))
+      (let* ((rrule-props (alist-get 'rrule-props eventdata-alist))
+             (until-str (cadr (assoc 'UNTIL rrule-props)))
+             (summary (alist-get 'summary eventdata-alist)))
+        ;; Debug: log what we're seeing
+        (message "CALDAV-DEBUG: %s | rrule-props: %S | until: %s"
+                 (or summary "?") rrule-props until-str)
+        (when until-str
+          (save-excursion
+            (org-back-to-heading t)
+            (org-entry-put nil "CALDAV_UNTIL" until-str))))
+      result))
+
+  (advice-add 'org-caldav-insert-org-event-or-todo
+              :around #'my/org-caldav-add-until-property)
+  )
+
+(defun my/get-rbw-password (alias &optional no-error)
+  "Return the password for ALIAS via rbw, unlocking the vault only if needed.
+If NO-ERROR is non-nil, return nil instead of signaling an error when
+rbw is unavailable or the entry is not found."
+  (if (not (executable-find "rbw"))
+      (if no-error
+          nil
+        (user-error "rbw: not installed or not in PATH"))
+    (let* ((cmd (format "rbw get %s 2>/dev/null" (shell-quote-argument alias)))
+           (output (string-trim (shell-command-to-string cmd))))
+      (if (string-empty-p output)
+          (if no-error
+              nil
+            (user-error "rbw: no entry found for '%s' - run: rbw add %s" alias alias))
+        output))))
 
 (after! gptel
   :config
-  (setq! gptel-api-key (my/get-rbw-password "openai-api-key-chatgpt-el")
+  (setq! gptel-api-key (my/get-rbw-password "openai-api-key-chatgpt-el" t)
          gptel-default-mode 'org-mode
          gptel-use-tools t
          gptel-confirm-tool-calls 'always
@@ -167,6 +294,20 @@
         claude-code-ide-window-side 'right
         claude-code-ide-window-width 90))
 
+(use-package! beads
+  :commands (beads)
+  :init
+  (map! :leader
+        (:prefix ("o" . "open")
+         (:prefix ("B" . "beads")
+          :desc "List issues"      "B" (cmd! (require 'beads) (beads-list))
+          :desc "Project issues"   "p" (cmd! (require 'beads) (beads-project-list))
+          :desc "Activity feed"    "a" (cmd! (require 'beads) (beads-activity))
+          :desc "Stale issues"     "s" (cmd! (require 'beads) (beads-stale))
+          :desc "Orphaned issues"  "o" (cmd! (require 'beads) (beads-orphans))
+          :desc "Find duplicates"  "d" (cmd! (require 'beads) (beads-duplicates))
+          :desc "Lint issues"      "l" (cmd! (require 'beads) (beads-lint))))))
+
 (after! gptel
   (require 'gptel-tool-library)
   (setq gptel-tool-library-use-maybe-safe t
@@ -211,11 +352,16 @@
         mu4e-headers-time-format "%H:%M")
 
   ;; Sending mail via msmtp
-  (setq message-send-mail-function 'message-send-mail-with-sendmail
-        sendmail-program (executable-find "msmtp")
-        message-sendmail-envelope-from 'header
-        mail-envelope-from 'header
-        mail-specify-envelope-from t))
+  ;; NOTE: message-sendmail-f-is-evil and --read-envelope-from are required
+  ;; to prevent msmtp from stripping the email body when processing headers.
+  ;; Without these, multipart messages (especially from org-msg) may arrive
+  ;; with empty bodies.
+  (setq sendmail-program (executable-find "msmtp")
+        send-mail-function #'message-send-mail-with-sendmail
+        message-send-mail-function #'message-send-mail-with-sendmail
+        message-sendmail-f-is-evil t
+        message-sendmail-extra-arguments '("--read-envelope-from")
+        message-sendmail-envelope-from 'header))
 
 ;; Whenever you reconfigure a package, make sure to wrap your config in an
 ;; `after!' block, otherwise Doom's defaults may override your settings. E.g.

home/roles/emacs/doom/packages.el

@@ -49,7 +49,7 @@
 ;; ...Or *all* packages (NOT RECOMMENDED; will likely break things)
 ;; (unpin! t)
 
-;; (package! org-caldav)
+(package! org-caldav)
 
 ;; Note: Packages with custom recipes must be pinned for nix-doom-emacs-unstraightened
 ;; to build deterministically. Update pins when upgrading packages.

home/roles/email/default.nix

@@ -4,6 +4,7 @@ with lib;
 
 let
   cfg = config.home.roles.email;
+  isLinux = pkgs.stdenv.isLinux;
 in
 {
   options.home.roles.email = {
@@ -89,34 +90,38 @@ in
       account default : proton
     '';
 
-    # Systemd service for mail sync
-    systemd.user.services.mbsync = {
-      Unit = {
-        Description = "Mailbox synchronization service";
-        After = [ "network-online.target" ];
-        Wants = [ "network-online.target" ];
-      };
-      Service = {
-        Type = "oneshot";
-        ExecStart = "${pkgs.bash}/bin/bash -c 'mkdir -p ~/Mail && ${pkgs.isync}/bin/mbsync -a && (${pkgs.mu}/bin/mu info >/dev/null 2>&1 || ${pkgs.mu}/bin/mu init --maildir ~/Mail --personal-address=john@ogle.fyi) && ${pkgs.mu}/bin/mu index'";
-        Environment = "PATH=${pkgs.rbw}/bin:${pkgs.coreutils}/bin";
-        StandardOutput = "journal";
-        StandardError = "journal";
+    # Linux-only: Systemd service for mail sync (Darwin uses launchd instead)
+    systemd.user.services = mkIf isLinux {
+      mbsync = {
+        Unit = {
+          Description = "Mailbox synchronization service";
+          After = [ "network-online.target" ];
+          Wants = [ "network-online.target" ];
+        };
+        Service = {
+          Type = "oneshot";
+          ExecStart = "${pkgs.bash}/bin/bash -c 'mkdir -p ~/Mail && ${pkgs.isync}/bin/mbsync -a && (${pkgs.mu}/bin/mu info >/dev/null 2>&1 || ${pkgs.mu}/bin/mu init --maildir ~/Mail --personal-address=john@ogle.fyi) && ${pkgs.mu}/bin/mu index'";
+          Environment = "PATH=${pkgs.rbw}/bin:${pkgs.coreutils}/bin";
+          StandardOutput = "journal";
+          StandardError = "journal";
+        };
       };
     };
 
-    # Systemd timer for automatic sync
-    systemd.user.timers.mbsync = {
-      Unit = {
-        Description = "Mailbox synchronization timer";
-      };
-      Timer = {
-        OnBootSec = "2min";
-        OnUnitActiveSec = "5min";
-        Unit = "mbsync.service";
-      };
-      Install = {
-        WantedBy = [ "timers.target" ];
+    # Linux-only: Systemd timer for automatic sync
+    systemd.user.timers = mkIf isLinux {
+      mbsync = {
+        Unit = {
+          Description = "Mailbox synchronization timer";
+        };
+        Timer = {
+          OnBootSec = "2min";
+          OnUnitActiveSec = "5min";
+          Unit = "mbsync.service";
+        };
+        Install = {
+          WantedBy = [ "timers.target" ];
+        };
       };
     };
   };

home/roles/gaming/default.nix

@@ -12,9 +12,7 @@ in
 
   config = mkIf cfg.enable {
     home.packages = with pkgs; [
-      # Gaming applications would go here
-      # This role is created for future expansion
-      # moonlight-qt is currently in media role but could be moved here
+      custom.mcrcon-rbw
     ];
   };
 }

home/roles/kdeconnect/default.nix

@@ -4,13 +4,15 @@ with lib;
 
 let
   cfg = config.home.roles.kdeconnect;
+  isLinux = pkgs.stdenv.isLinux;
 in
 {
   options.home.roles.kdeconnect = {
     enable = mkEnableOption "Enable KDE Connect for device integration";
   };
 
-  config = mkIf cfg.enable {
+  # KDE Connect services are Linux-only (requires D-Bus and systemd)
+  config = mkIf (cfg.enable && isLinux) {
     services.kdeconnect = {
       enable = true;
       indicator = true;

home/roles/sync/default.nix

@@ -4,6 +4,7 @@ with lib;
 
 let
   cfg = config.home.roles.sync;
+  isLinux = pkgs.stdenv.isLinux;
 in
 {
   options.home.roles.sync = {
@@ -11,9 +12,10 @@ in
   };
 
   config = mkIf cfg.enable {
-    home.packages = with pkgs; [
+    # Linux-only: syncthingtray requires system tray support
+    home.packages = optionals isLinux (with pkgs; [
       syncthingtray
-    ];
+    ]);
 
     services.syncthing = {
       enable = true;

machines/boxy/configuration.nix

@@ -26,6 +26,7 @@ with lib;
       enable = true;
       autologin = true;
       wayland = true;
+      appLauncherServer.enable = true;
       jellyfinScaleFactor = 1.0;
     };
     nfs-mounts.enable = true;

machines/john-endesktop/configuration.nix

@@ -90,6 +90,8 @@ with lib;
     htop
     tmux
     zfs
+    rclone
+    custom.rclone-torbox-setup  # Helper script to set up TorBox credentials via rbw
   ];
 
   # Enable SSH
@@ -104,6 +106,48 @@ with lib;
   # User configuration
   roles.users.enable = true;
 
+  # Enable as remote builder (similar to zix790prors)
+  roles.remote-build.enableBuilder = true;
+
+  # k3s agent configuration
+  roles.k3s-node = {
+    enable = true;
+    role = "agent";
+    # serverAddr defaults to https://10.0.0.222:6443
+    # tokenFile defaults to /etc/k3s/token
+    extraFlags = [
+      # Node labels for workload scheduling
+      # fast-cpu: This node has a faster CPU than other cluster nodes
+      "--node-label=fast-cpu=true"
+      # fast-storage: This node is the NFS host with fast local storage access
+      "--node-label=fast-storage=true"
+      # k3s-upgrade=disabled: NixOS manages k3s upgrades via Nix, not system-upgrade-controller
+      "--node-label=k3s-upgrade=disabled"
+    ];
+  };
+
+  roles.virtualisation.enable = true;
+
+  # TorBox WebDAV mount for rdt-client and Jellyfin
+  roles.rclone-mount = {
+    enable = true;
+    mounts.torbox = {
+      webdavUrl = "https://webdav.torbox.app";
+      username = "john@ogle.fyi";  # TorBox account email
+      mountPoint = "/media/media/torbox-rclone";
+      environmentFile = "/etc/rclone/torbox.env";
+      vfsCacheMode = "full";  # Best for streaming media
+      dirCacheTime = "5m";
+      extraArgs = [
+        "--buffer-size=64M"
+        "--vfs-read-chunk-size=32M"
+        "--vfs-read-chunk-size-limit=off"
+      ];
+      # Wait for ZFS media pool to be mounted before starting
+      requiresMountsFor = [ "/media" ];
+    };
+  };
+
   # Time zone
   time.timeZone = "America/Los_Angeles"; # Adjust as needed
 

machines/nix-book/configuration.nix

@@ -21,11 +21,18 @@
     };
     nfs-mounts.enable = true;
     printing.enable = true;
-    remote-build.builders = [{
-      hostName = "zix790prors";
-      maxJobs = 16;
-      speedFactor = 3;
-    }];
+    remote-build.builders = [
+      {
+        hostName = "zix790prors.oglehome";
+        maxJobs = 16;
+        speedFactor = 3;
+      }
+      {
+        hostName = "john-endesktop.oglehome";
+        maxJobs = 1;
+        speedFactor = 1;
+      }
+    ];
     spotifyd.enable = true;
     users = {
       enable = true;
@@ -41,14 +48,9 @@
   boot.initrd.luks.devices."luks-b614167b-9045-4234-a441-ac6f60a96d81".device = "/dev/disk/by-uuid/b614167b-9045-4234-a441-ac6f60a96d81";
 
   services.logind.settings.Login = {
-    HandleLidSwitch = "suspend-then-hibernate";
     HandlePowerKey = "hibernate";
     HandlePowerKeyLongPress = "poweroff";
   };
-  systemd.sleep.extraConfig = ''
-    HibernateDelaySec=30m
-    SuspendState=mem
-  '';
 
   networking.hostName = "nix-book"; # Define your hostname.
   # networking.wireless.enable = true;  # Enables wireless support via wpa_supplicant.

machines/nix-deck/configuration.nix

@@ -19,11 +19,18 @@
         desktopSession = "plasma";
       };
     };
-    remote-build.builders = [{
-      hostName = "zix790prors";
-      maxJobs = 16;
-      speedFactor = 4;  # Prefer remote heavily on Steam Deck
-    }];
+    remote-build.builders = [
+      {
+        hostName = "zix790prors.oglehome";
+        maxJobs = 16;
+        speedFactor = 4;
+      }
+      {
+        hostName = "john-endesktop.oglehome";
+        maxJobs = 1;
+        speedFactor = 2;
+      }
+    ];
     users = {
       enable = true;
       extraGroups = [ "video" ];

machines/wixos/configuration.nix

@@ -1,62 +0,0 @@
-# Edit this configuration file to define what should be installed on
-# your system. Help is available in the configuration.nix(5) man page, on
-# https://search.nixos.org/options and in the NixOS manual (`nixos-help`).
-
-# NixOS-WSL specific options are documented on the NixOS-WSL repository:
-# https://github.com/nix-community/NixOS-WSL
-
-{ config, lib, pkgs, ... }:
-
-{
-  imports = [
-  ];
-
-  roles = {
-    audio.enable = true;
-    desktop = {
-      enable = true;
-      wayland = true;
-    };
-    users.enable = true;
-  };
-
-  networking.hostName = "wixos";
-
-  wsl.enable = true;
-  wsl.defaultUser = "johno";
-  wsl.startMenuLaunchers = true;
-  wsl.useWindowsDriver = true;
-  wsl.wslConf.network.hostname = "wixos";
-  wsl.wslConf.user.default = "johno";
-
-  services.xserver.videoDrivers = [ "nvidia" ];
-  hardware.graphics = { 
-    enable = true;
-
-    extraPackages = with pkgs; [
-      mesa
-      libvdpau-va-gl
-      libva-vdpau-driver
-    ];
-  };
-  environment.sessionVariables = {
-    LD_LIBRARY_PATH = [
-      "/usr/lib/wsl/lib"
-      "/run/opengl-driver/lib"
-    ];
-  };
-  hardware.nvidia = {
-    modesetting.enable = true;
-    nvidiaSettings = true;
-    open = true;
-    package = config.boot.kernelPackages.nvidiaPackages.latest;
-  };
-
-  # This value determines the NixOS release from which the default
-  # settings for stateful data, like file locations and database versions
-  # on your system were taken. It's perfectly fine and recommended to leave
-  # this value at the release version of the first install of this system.
-  # Before changing this value read the documentation for this option
-  # (e.g. man configuration.nix or on https://nixos.org/nixos/options.html).
-  system.stateVersion = "24.05"; # Did you read the comment?
-}

machines/zix790prors/configuration.nix

@@ -25,8 +25,12 @@ with lib;
       wayland = true;
       x11 = true;
     };
+    kodi.enable = true;
     nfs-mounts.enable = true;
-    nvidia.enable = true;
+    nvidia = {
+      enable = true;
+      graphics.enable32Bit = true;
+    };
     printing.enable = true;
     remote-build.enableBuilder = true;
     users.enable = true;
@@ -47,27 +51,11 @@ with lib;
   # Fix dual boot clock sync - tell Linux to use local time for hardware clock
   time.hardwareClockInLocalTime = true;
 
-  # NVIDIA Graphics configuration
-  services.xserver.videoDrivers = [ "nvidia" ];
-  hardware.graphics.enable = true;
-  hardware.graphics.enable32Bit = true;
-  
   # Set DP-0 as primary display with 164.90Hz refresh rate
   services.xserver.displayManager.sessionCommands = ''
     ${pkgs.xorg.xrandr}/bin/xrandr --output DP-0 --mode 3440x1440 --rate 164.90 --primary
   '';
 
-  hardware.nvidia = {
-    modesetting.enable = true;
-    nvidiaSettings = true;
-    package = pkgs.linuxPackages.nvidiaPackages.stable;
-    open = true;
-    
-    # For gaming performance
-    powerManagement.enable = false;
-    powerManagement.finegrained = false;
-  };
-
   services.ollama = {
     enable = true;
     acceleration = "cuda";

packages/claude-code/default.nix

@@ -1,28 +1,29 @@
 { lib
 , stdenv
 , fetchurl
-, autoPatchelfHook
+, patchelf
+, glibc
 }:
 
 let
-  version = "2.0.76";
+  version = "2.1.30";
 
   srcs = {
     aarch64-darwin = {
       url = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/${version}/darwin-arm64/claude";
-      sha256 = "b76f6d4d09233e67295897b0a1ed2e22d7afa406431529d8b1b532b63b8cbcbd";
+      sha256 = "3ccc14f322b1e8da0cd58afc254fd5100eee066fa14729f30745e67a3f7979f7";
     };
     x86_64-darwin = {
       url = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/${version}/darwin-x64/claude";
-      sha256 = "9d94582f0af5d2201f1c907bf24ff8d216104b897ee0b24795a6c081f40e08d7";
+      sha256 = "8a083696006483b8382ec0e47cd8f2e3223f3d2cab1a21c524fa08c082b5600e";
     };
     x86_64-linux = {
       url = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/${version}/linux-x64/claude";
-      sha256 = "5dcdb480f91ba0df0bc8bd6aff148d3dfd3883f0899eeb5b9427a8b0abe7a687";
+      sha256 = "ada8f1cf9272965d38b10f1adb6cea885e621c83f7e7bb233008c721f43fad54";
     };
     aarch64-linux = {
       url = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/${version}/linux-arm64/claude";
-      sha256 = "f64a994c8e5bfb84d7242cebbec75d6919db2ee46d50b8fc7a88d5066db193f9";
+      sha256 = "45fbf35a1011b06f86170b20beb64c599db0658aac70e2de2410c45d15775596";
     };
   };
 
@@ -38,8 +39,14 @@ in stdenv.mkDerivation {
 
   dontUnpack = true;
   dontBuild = true;
+  # Bun standalone binaries have JS code appended after the ELF sections
+  # stripping/patching would remove or corrupt this appended data
+  dontStrip = true;
+  dontPatchELF = true;
 
-  nativeBuildInputs = lib.optionals stdenv.isLinux [ autoPatchelfHook ];
+  # Don't use autoPatchelfHook - it rewrites the ELF and strips the appended
+  # bun bundle (the JS code is appended after the ELF sections)
+  nativeBuildInputs = lib.optionals stdenv.isLinux [ patchelf ];
 
   installPhase = ''
     runHook preInstall
@@ -49,6 +56,14 @@ in stdenv.mkDerivation {
     runHook postInstall
   '';
 
+  # Manually patch the interpreter for bun standalone binaries
+  # patchelf --set-interpreter modifies in-place without rewriting the entire ELF,
+  # preserving the appended JS bundle that bun needs at runtime
+  postFixup = lib.optionalString stdenv.isLinux ''
+    interpreter="${glibc}/lib/${if stdenv.hostPlatform.system == "aarch64-linux" then "ld-linux-aarch64.so.1" else "ld-linux-x86-64.so.2"}"
+    patchelf --set-interpreter "$interpreter" $out/bin/claude
+  '';
+
   meta = with lib; {
     description = "Terminal-based AI coding assistant from Anthropic";
     homepage = "https://www.anthropic.com/claude-code";

packages/default.nix

@@ -1,8 +1,8 @@
 { pkgs, ... }:
 {
-  vulkanHDRLayer = pkgs.callPackage ./vulkan-hdr-layer {};
   tea-rbw = pkgs.callPackage ./tea-rbw {};
   app-launcher-server = pkgs.callPackage ./app-launcher-server {};
   claude-code = pkgs.callPackage ./claude-code {};
-  perles = pkgs.callPackage ./perles {};
+  mcrcon-rbw = pkgs.callPackage ./mcrcon-rbw {};
+  rclone-torbox-setup = pkgs.callPackage ./rclone-torbox-setup {};
 }

packages/mcrcon-rbw/default.nix

@@ -0,0 +1,40 @@
+{ pkgs, ... }:
+
+pkgs.writeShellScriptBin "mcrcon" ''
+  set -euo pipefail
+
+  # Configuration - can be overridden with environment variables
+  MINECRAFT_RCON_HOST="''${MCRCON_HOST:-10.0.0.165}"
+  MINECRAFT_RCON_PORT="''${MCRCON_PORT:-25575}"
+  RBW_ENTRY="minecraft-rcon"
+
+  # Check if rbw is available
+  if ! command -v rbw &> /dev/null; then
+    echo "Error: rbw is not available. Please ensure rbw is installed and configured."
+    exit 1
+  fi
+
+  # Retrieve password from Bitwarden
+  if ! MCRCON_PASS=$(rbw get "$RBW_ENTRY" 2>/dev/null); then
+    echo "Error: Failed to retrieve RCON password from rbw entry '$RBW_ENTRY'"
+    echo "Please ensure the entry exists in Bitwarden and rbw is synced."
+    echo ""
+    echo "To create the entry:"
+    echo "  1. Add 'minecraft-rcon' to Bitwarden with the RCON password"
+    echo "  2. Run 'rbw sync' to refresh the local cache"
+    exit 1
+  fi
+
+  # Export for mcrcon
+  export MCRCON_HOST="$MINECRAFT_RCON_HOST"
+  export MCRCON_PORT="$MINECRAFT_RCON_PORT"
+  export MCRCON_PASS
+
+  # If no arguments provided, start interactive terminal mode
+  if [[ $# -eq 0 ]]; then
+    exec ${pkgs.mcrcon}/bin/mcrcon -t
+  fi
+
+  # Execute mcrcon with all provided arguments
+  exec ${pkgs.mcrcon}/bin/mcrcon "$@"
+''

packages/perles/default.nix

@@ -1,26 +0,0 @@
-{ lib, buildGoModule, fetchFromGitHub }:
-
-buildGoModule rec {
-  pname = "perles";
-  version = "unstable-2025-01-09";
-
-  src = fetchFromGitHub {
-    owner = "zjrosen";
-    repo = "perles";
-    rev = "main";
-    hash = "sha256-JgRayb4+mJ1r0AtdnQfqAw2+QRte+licsfZOaRgYqcs=";
-  };
-
-  vendorHash = "sha256-R7UWTdBuPteneRqxrWK51nqLtZwDsqQoMAcohN4fyak=";
-
-  # Tests require a real git repository context
-  doCheck = false;
-
-  meta = with lib; {
-    description = "A TUI for the Beads issue tracking system with BQL query language";
-    homepage = "https://github.com/zjrosen/perles";
-    license = licenses.mit;
-    maintainers = [ ];
-    mainProgram = "perles";
-  };
-}

packages/rclone-torbox-setup/default.nix

@@ -0,0 +1,98 @@
+{ pkgs, ... }:
+
+pkgs.writeShellScriptBin "rclone-torbox-setup" ''
+  set -euo pipefail
+
+  # Default values
+  RBW_ENTRY="''${1:-torbox}"
+  ENV_FILE="''${2:-/etc/rclone/torbox.env}"
+
+  usage() {
+    echo "Usage: rclone-torbox-setup [rbw-entry] [env-file]"
+    echo ""
+    echo "Sets up rclone credentials for TorBox WebDAV mount."
+    echo "Retrieves password from rbw (Bitwarden), obscures it for rclone,"
+    echo "and writes it to the environment file for the systemd service."
+    echo ""
+    echo "Arguments:"
+    echo "  rbw-entry  Name of the Bitwarden entry containing the password (default: torbox)"
+    echo "  env-file   Path to write the environment file (default: /etc/rclone/torbox.env)"
+    echo ""
+    echo "The Bitwarden entry should contain your TorBox password as the password field."
+    echo ""
+    echo "Example:"
+    echo "  rclone-torbox-setup torbox-password /etc/rclone/torbox.env"
+    exit 1
+  }
+
+  if [[ "''${1:-}" == "-h" ]] || [[ "''${1:-}" == "--help" ]]; then
+    usage
+  fi
+
+  echo "rclone TorBox credential setup"
+  echo "=============================="
+  echo ""
+
+  # Check if rbw is available
+  if ! command -v rbw &> /dev/null; then
+    echo "Error: rbw is not available. Please ensure rbw is installed and configured."
+    exit 1
+  fi
+
+  # Check if rclone is available
+  if ! command -v rclone &> /dev/null; then
+    echo "Error: rclone is not available. Please ensure rclone is installed."
+    exit 1
+  fi
+
+  echo "Retrieving password from rbw entry: $RBW_ENTRY"
+
+  # Retrieve password from Bitwarden
+  if ! TORBOX_PASS=$(rbw get "$RBW_ENTRY" 2>/dev/null); then
+    echo ""
+    echo "Error: Failed to retrieve password from rbw entry '$RBW_ENTRY'"
+    echo ""
+    echo "Please ensure:"
+    echo "  1. The entry '$RBW_ENTRY' exists in Bitwarden"
+    echo "  2. rbw is unlocked: rbw unlock"
+    echo "  3. rbw is synced: rbw sync"
+    echo ""
+    echo "To create the entry in Bitwarden:"
+    echo "  - Name: $RBW_ENTRY"
+    echo "  - Password: Your TorBox password"
+    exit 1
+  fi
+
+  echo "Password retrieved successfully"
+
+  # Obscure the password for rclone
+  echo "Obscuring password for rclone..."
+  if ! OBSCURED_PASS=$(echo -n "$TORBOX_PASS" | rclone obscure -); then
+    echo "Error: Failed to obscure password with rclone"
+    exit 1
+  fi
+
+  # Create the directory if needed (requires sudo)
+  ENV_DIR=$(dirname "$ENV_FILE")
+  if [[ ! -d "$ENV_DIR" ]]; then
+    echo "Creating directory $ENV_DIR (requires sudo)..."
+    sudo mkdir -p "$ENV_DIR"
+  fi
+
+  # Write the environment file
+  echo "Writing environment file to $ENV_FILE (requires sudo)..."
+  echo "RCLONE_WEBDAV_PASS=$OBSCURED_PASS" | sudo tee "$ENV_FILE" > /dev/null
+  sudo chmod 600 "$ENV_FILE"
+
+  echo ""
+  echo "Setup complete!"
+  echo ""
+  echo "The environment file has been created at: $ENV_FILE"
+  echo "The rclone-mount-torbox systemd service will use this file."
+  echo ""
+  echo "To activate the mount after NixOS rebuild:"
+  echo "  sudo systemctl start rclone-mount-torbox"
+  echo ""
+  echo "To check status:"
+  echo "  sudo systemctl status rclone-mount-torbox"
+''

packages/vulkan-hdr-layer/default.nix

@@ -1,34 +0,0 @@
-{ lib, stdenv, fetchFromGitHub, meson, pkg-config, vulkan-loader, ninja, writeText, vulkan-headers, vulkan-utility-libraries,  jq, libX11, libXrandr, libxcb, wayland, wayland-scanner }:
-
-stdenv.mkDerivation rec {
-  pname = "vulkan-hdr-layer";
-  version = "63d2eec";
-
-  src = (fetchFromGitHub {
-    owner = "Zamundaaa";
-    repo = "VK_hdr_layer";
-    rev = "869199cd2746e7f69cf19955153080842b6dacfc";
-    fetchSubmodules = true;
-    hash = "sha256-xfVYI+Aajmnf3BTaY2Ysg5fyDO6SwDFGyU0L+F+E3is=";
-  }).overrideAttrs (_: {
-    GIT_CONFIG_COUNT = 1;
-    GIT_CONFIG_KEY_0 = "url.https://github.com/.insteadOf";
-    GIT_CONFIG_VALUE_0 = "git@github.com:";
-  });
-
-  nativeBuildInputs = [ vulkan-headers meson ninja pkg-config jq ];
-
-  buildInputs = [ vulkan-headers vulkan-loader vulkan-utility-libraries libX11 libXrandr libxcb wayland wayland-scanner ];
-
-  # Help vulkan-loader find the validation layers
-  setupHook = writeText "setup-hook" ''
-    addToSearchPath XDG_DATA_DIRS @out@/share
-  '';
-
-  meta = with lib; {
-    description = "Layers providing Vulkan HDR";
-    homepage = "https://github.com/Zamundaaa/VK_hdr_layer";
-    platforms = platforms.linux;
-    license = licenses.mit;
-  };
-}

renovate.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "timezone": "America/Los_Angeles",
+  "gitAuthor": "Renovate Bot <renovate@ogle.fyi>",
+  "nix": {
+    "enabled": true
+  },
+  "github-actions": {
+    "managerFilePatterns": [
+      "/.gitea/workflows/.+\\.ya?ml$/"
+    ]
+  },
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": [
+      "after 2pm and before 4pm on Saturday"
+    ]
+  },
+  "dependencyDashboard": true,
+  "dependencyDashboardAutoclose": false,
+  "dependencyDashboardTitle": "NixOS Configs Dependency Dashboard",
+  "packageRules": [
+    {
+      "description": "Group all GitHub Actions updates",
+      "matchManagers": [
+        "github-actions"
+      ],
+      "groupName": "github-actions"
+    },
+    {
+      "description": "Group stable NixOS ecosystem inputs",
+      "matchManagers": [
+        "nix"
+      ],
+      "groupName": "nix-stable-ecosystem",
+      "matchPackageNames": [
+        "/^nixpkgs$/",
+        "/^home-manager$/",
+        "/^nix-darwin$/"
+      ],
+      "schedule": [
+        "after 2pm and before 4pm on Saturday"
+      ]
+    },
+    {
+      "description": "Group unstable NixOS ecosystem inputs",
+      "matchManagers": [
+        "nix"
+      ],
+      "groupName": "nix-unstable-ecosystem",
+      "matchPackageNames": [
+        "/nixpkgs-unstable/",
+        "/home-manager-unstable/"
+      ],
+      "schedule": [
+        "after 2pm and before 4pm on Saturday"
+      ]
+    },
+    {
+      "description": "nixpkgs-qt updates on Saturday (staggered from main ecosystem)",
+      "matchManagers": [
+        "nix"
+      ],
+      "matchPackageNames": [
+        "/nixpkgs-qt/"
+      ],
+      "schedule": [
+        "after 4pm and before 6pm on Saturday"
+      ]
+    },
+    {
+      "description": "Ignore private Gitea inputs (handle separately)",
+      "matchManagers": [
+        "nix"
+      ],
+      "enabled": false,
+      "matchPackageNames": [
+        "/google-cookie-retrieval/"
+      ]
+    },
+    {
+      "description": "Gastown is under active development - check for updates daily",
+      "matchManagers": [
+        "nix"
+      ],
+      "matchPackageNames": [
+        "/gastown/"
+      ],
+      "schedule": [
+        "before 6am every day"
+      ],
+      "automerge": false
+    },
+    {
+      "description": "Beads is under active development - check for updates daily",
+      "matchManagers": [
+        "nix"
+      ],
+      "matchPackageNames": [
+        "/beads/"
+      ],
+      "schedule": [
+        "before 6am every day"
+      ],
+      "automerge": false
+    }
+  ]
+}

roles/audio/default.nix

@@ -21,17 +21,11 @@ in
 
       services.pipewire = {
         enable = true;
+        alsa.enable = true;
+        alsa.support32Bit = true;
         pulse.enable = true;
       };
 
-      services.pulseaudio = {
-        package = pkgs.pulseaudioFull;
-        extraConfig = ''
-          load-module module-combine-sink
-          load-module module-switch-on-connect
-        '';
-      };
-
       services.squeezelite = {
         #enable = true;
         pulseAudio = true;

roles/common.nix

@@ -12,6 +12,8 @@
       tree
       usbutils
       vim
+    ] ++ lib.optionals pkgs.stdenv.isLinux [
+      ghostty.terminfo  # So tmux works when SSH'ing from ghostty
     ];
 
     nix = {
@@ -21,7 +23,13 @@
         max-jobs = "auto";
         trusted-users = [ "johno" ];
         substituters = [
+          "https://nix-cache.johnogle.info"
         ];
+        trusted-public-keys = [
+          "nix-cache.johnogle.info-1:IC5x8BxnrqkU9XqhMdDnZLtSg9Y3rBJVXhve5DJ92J0="
+        ];
+        fallback = true;
+        connect-timeout = 5;
       };
 
       gc = {

roles/default.nix

@@ -9,10 +9,12 @@ with lib;
     ./bluetooth
     ./btrfs
     ./desktop
+    ./k3s-node
     ./kodi
     ./nfs-mounts
     ./nvidia
     ./printing
+    ./rclone-mount
     ./remote-build
     ./spotifyd
     ./users

roles/k3s-node/default.nix

@@ -0,0 +1,81 @@
+{ lib, config, pkgs, ... }:
+
+with lib;
+
+let
+  cfg = config.roles.k3s-node;
+in
+{
+  options.roles.k3s-node = {
+    enable = mkEnableOption "Enable k3s node";
+
+    role = mkOption {
+      type = types.enum [ "server" "agent" ];
+      default = "agent";
+      description = "k3s role: server (control plane) or agent (worker)";
+    };
+
+    serverAddr = mkOption {
+      type = types.str;
+      default = "https://10.0.0.222:6443";
+      description = "URL of k3s server to join (required for agents, used for HA servers)";
+    };
+
+    tokenFile = mkOption {
+      type = types.path;
+      default = "/etc/k3s/token";
+      description = "Path to file containing the cluster join token";
+    };
+
+    clusterInit = mkOption {
+      type = types.bool;
+      default = false;
+      description = "Initialize a new cluster (first server only)";
+    };
+
+    extraFlags = mkOption {
+      type = types.listOf types.str;
+      default = [];
+      description = "Additional flags to pass to k3s";
+    };
+
+    gracefulNodeShutdown = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Enable graceful node shutdown";
+    };
+
+    openFirewall = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Open firewall ports for k3s";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # k3s service configuration
+    services.k3s = {
+      enable = true;
+      role = cfg.role;
+      tokenFile = cfg.tokenFile;
+      extraFlags = cfg.extraFlags;
+      gracefulNodeShutdown.enable = cfg.gracefulNodeShutdown;
+      serverAddr = if (cfg.role == "agent" || !cfg.clusterInit) then cfg.serverAddr else "";
+      clusterInit = cfg.role == "server" && cfg.clusterInit;
+    };
+
+    # Firewall rules for k3s
+    networking.firewall = mkIf cfg.openFirewall {
+      allowedTCPPorts = [
+        6443  # k3s API server
+        10250 # kubelet metrics
+      ] ++ optionals (cfg.role == "server") [
+        2379  # etcd clients (HA)
+        2380  # etcd peers (HA)
+      ];
+      allowedUDPPorts = [
+        8472  # flannel VXLAN
+      ];
+    };
+  };
+}

roles/kodi/default.nix

@@ -22,7 +22,7 @@ in
     appLauncherServer = {
       enable = mkOption {
         type = types.bool;
-        default = true;
+        default = false;
         description = "Enable HTTP app launcher server for remote control";
       };
       port = mkOption {

roles/nfs-mounts/default.nix

@@ -8,6 +8,21 @@ in
 {
   options.roles.nfs-mounts = {
     enable = mkEnableOption "Enable default NFS mounts";
+    server = mkOption {
+      type = types.str;
+      default = "10.0.0.43";
+      description = "IP address or hostname of the NFS server";
+    };
+    remotePath = mkOption {
+      type = types.str;
+      default = "/media";
+      description = "Remote path to mount from the NFS server";
+    };
+    mountPoint = mkOption {
+      type = types.str;
+      default = "/media";
+      description = "Local mount point for the NFS share";
+    };
     # TODO: implement requireMount
     requireMount = mkOption {
       type = types.bool;
@@ -18,8 +33,8 @@ in
 
   config = mkIf cfg.enable
     {
-      fileSystems."/media" = {
-        device = "10.0.0.43:/media";
+      fileSystems.${cfg.mountPoint} = {
+        device = "${cfg.server}:${cfg.remotePath}";
         fsType = "nfs";
         options = [
           "defaults"

roles/nvidia/default.nix

@@ -8,9 +8,89 @@ in
 {
   options.roles.nvidia = {
     enable = mkEnableOption "Enable the nvidia role";
+
+    # Driver configuration options
+    open = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Use the open source nvidia kernel driver (for Turing and newer GPUs).";
+    };
+
+    modesetting = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Enable kernel modesetting for nvidia.";
+    };
+
+    nvidiaSettings = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Enable the nvidia-settings GUI.";
+    };
+
+    package = mkOption {
+      type = types.enum [ "stable" "latest" "beta" "vulkan_beta" "production" ];
+      default = "stable";
+      description = "The nvidia driver package to use.";
+    };
+
+    powerManagement = {
+      enable = mkOption {
+        type = types.bool;
+        default = false;
+        description = "Enable nvidia power management (useful for laptops, not recommended for desktops).";
+      };
+
+      finegrained = mkOption {
+        type = types.bool;
+        default = false;
+        description = "Enable fine-grained power management for Turing and newer GPUs.";
+      };
+    };
+
+    graphics = {
+      enable = mkOption {
+        type = types.bool;
+        default = true;
+        description = "Enable hardware graphics support.";
+      };
+
+      enable32Bit = mkOption {
+        type = types.bool;
+        default = false;
+        description = "Enable 32-bit graphics libraries (needed for some games).";
+      };
+
+      extraPackages = mkOption {
+        type = types.listOf types.package;
+        default = [];
+        description = "Extra packages to add to hardware.graphics.extraPackages.";
+      };
+    };
   };
 
   config = mkIf cfg.enable {
+    # Set xserver video driver
+    services.xserver.videoDrivers = [ "nvidia" ];
+
+    # Graphics configuration
+    hardware.graphics = {
+      enable = cfg.graphics.enable;
+      enable32Bit = cfg.graphics.enable32Bit;
+      extraPackages = cfg.graphics.extraPackages;
+    };
+
+    # NVIDIA driver configuration
+    hardware.nvidia = {
+      modesetting.enable = cfg.modesetting;
+      nvidiaSettings = cfg.nvidiaSettings;
+      open = cfg.open;
+      package = config.boot.kernelPackages.nvidiaPackages.${cfg.package};
+      powerManagement.enable = cfg.powerManagement.enable;
+      powerManagement.finegrained = cfg.powerManagement.finegrained;
+    };
+
+    # Additional packages for nvidia support
     environment.systemPackages = with pkgs; [
       libva-utils
       nvidia-vaapi-driver

roles/printing/default.nix

@@ -8,6 +8,21 @@ in
 {
   options.roles.printing = {
     enable = mkEnableOption "Enable default printing setup";
+    printerName = mkOption {
+      type = types.str;
+      default = "MFC-L8900CDW_series";
+      description = "Name for the default printer";
+    };
+    printerUri = mkOption {
+      type = types.str;
+      default = "ipp://brother.oglehome/ipp/print";
+      description = "Device URI for the default printer (e.g., ipp://hostname/ipp/print)";
+    };
+    printerModel = mkOption {
+      type = types.str;
+      default = "everywhere";
+      description = "PPD model for the printer (use 'everywhere' for driverless IPP)";
+    };
   };
 
   config = mkIf cfg.enable
@@ -21,11 +36,11 @@ in
       };
 
       hardware.printers.ensurePrinters = [{
-        name = "MFC-L8900CDW_series";
-        deviceUri = "ipp://brother.oglehome/ipp/print";
-        model = "everywhere";
+        name = cfg.printerName;
+        deviceUri = cfg.printerUri;
+        model = cfg.printerModel;
       }];
-      hardware.printers.ensureDefaultPrinter = "MFC-L8900CDW_series";
+      hardware.printers.ensureDefaultPrinter = cfg.printerName;
 
       # Fix ensure-printers service to wait for network availability
       systemd.services.ensure-printers = {

roles/rclone-mount/default.nix

@@ -0,0 +1,149 @@
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+let
+  cfg = config.roles.rclone-mount;
+
+  # Generate systemd service for a single mount
+  mkMountService = name: mountCfg: {
+    description = "rclone mount for ${name}";
+    after = [ "network-online.target" ];
+    wants = [ "network-online.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    # Wait for parent mount points (e.g., ZFS pools) to be available
+    unitConfig = mkIf (mountCfg.requiresMountsFor != []) {
+      RequiresMountsFor = mountCfg.requiresMountsFor;
+    };
+
+    serviceConfig = {
+      Type = "notify";
+      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p ${mountCfg.mountPoint}";
+      ExecStart = concatStringsSep " " ([
+        "${pkgs.rclone}/bin/rclone mount"
+        ":webdav:${mountCfg.remotePath}"
+        "${mountCfg.mountPoint}"
+        "--webdav-url=${mountCfg.webdavUrl}"
+        "--webdav-vendor=${mountCfg.webdavVendor}"
+        "--webdav-user=${mountCfg.username}"
+        "--allow-other"
+        "--vfs-cache-mode=${mountCfg.vfsCacheMode}"
+        "--dir-cache-time=${mountCfg.dirCacheTime}"
+        "--poll-interval=${mountCfg.pollInterval}"
+        "--log-level=${mountCfg.logLevel}"
+      ] ++ mountCfg.extraArgs);
+      ExecStop = "${pkgs.fuse}/bin/fusermount -uz ${mountCfg.mountPoint}";
+      Restart = "on-failure";
+      RestartSec = "10s";
+      EnvironmentFile = mountCfg.environmentFile;
+    };
+  };
+in
+{
+  options.roles.rclone-mount = {
+    enable = mkEnableOption "Enable rclone WebDAV mounts";
+
+    mounts = mkOption {
+      type = types.attrsOf (types.submodule {
+        options = {
+          webdavUrl = mkOption {
+            type = types.str;
+            description = "WebDAV server URL (e.g., https://webdav.torbox.app)";
+          };
+
+          webdavVendor = mkOption {
+            type = types.enum [ "other" "nextcloud" "owncloud" "sharepoint" "sharepoint-ntlm" "fastmail" ];
+            default = "other";
+            description = "WebDAV server vendor for optimizations";
+          };
+
+          username = mkOption {
+            type = types.str;
+            description = "WebDAV username (often email address)";
+          };
+
+          environmentFile = mkOption {
+            type = types.path;
+            description = ''
+              Path to environment file containing RCLONE_WEBDAV_PASS.
+              The password should be obscured using: rclone obscure <password>
+              File format: RCLONE_WEBDAV_PASS=<obscured_password>
+            '';
+          };
+
+          mountPoint = mkOption {
+            type = types.str;
+            description = "Local mount point path";
+          };
+
+          remotePath = mkOption {
+            type = types.str;
+            default = "/";
+            description = "Remote path on WebDAV server to mount";
+          };
+
+          vfsCacheMode = mkOption {
+            type = types.enum [ "off" "minimal" "writes" "full" ];
+            default = "full";
+            description = ''
+              VFS cache mode. For streaming media, 'full' is recommended.
+              - off: No caching (direct reads/writes)
+              - minimal: Cache open files only
+              - writes: Cache writes and open files
+              - full: Full caching of all files
+            '';
+          };
+
+          dirCacheTime = mkOption {
+            type = types.str;
+            default = "5m";
+            description = "Time to cache directory entries";
+          };
+
+          pollInterval = mkOption {
+            type = types.str;
+            default = "1m";
+            description = "Poll interval for remote changes";
+          };
+
+          logLevel = mkOption {
+            type = types.enum [ "DEBUG" "INFO" "NOTICE" "ERROR" ];
+            default = "INFO";
+            description = "rclone log level";
+          };
+
+          extraArgs = mkOption {
+            type = types.listOf types.str;
+            default = [];
+            description = "Extra arguments to pass to rclone mount";
+          };
+
+          requiresMountsFor = mkOption {
+            type = types.listOf types.str;
+            default = [];
+            description = ''
+              List of mount points that must be available before this service starts.
+              Use this when the mount point's parent is on a ZFS pool or other filesystem
+              that may not be mounted at boot time.
+              Example: [ "/media" ] to wait for the media ZFS pool to mount.
+            '';
+          };
+        };
+      });
+      default = {};
+      description = "Attribute set of rclone WebDAV mounts to configure";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # Ensure FUSE is available
+    environment.systemPackages = [ pkgs.rclone pkgs.fuse ];
+    programs.fuse.userAllowOther = true;
+
+    # Create systemd services for each mount
+    systemd.services = mapAttrs' (name: mountCfg:
+      nameValuePair "rclone-mount-${name}" (mkMountService name mountCfg)
+    ) cfg.mounts;
+  };
+}

roles/remote-build/default.nix

@@ -1,3 +1,66 @@
+# Remote Build Role
+#
+# This module configures Nix distributed builds, allowing machines to offload
+# builds to more powerful remote machines.
+#
+# SETUP INSTRUCTIONS
+# ==================
+#
+# 1. BUILDER MACHINE SETUP
+#    On machines that will serve as builders (e.g., zix790prors, john-endesktop):
+#
+#    a) Enable the builder role in configuration.nix:
+#       roles.remote-build.enableBuilder = true;
+#
+#    b) After nixos-rebuild, the nix-builder user is created automatically.
+#       You need to add client SSH public keys to the builder. Either:
+#
+#       Option A - Manual (recommended for initial setup):
+#         sudo mkdir -p /var/lib/nix-builder/.ssh
+#         sudo bash -c 'cat >> /var/lib/nix-builder/.ssh/authorized_keys' << 'EOF'
+#         ssh-ed25519 AAAA... root@client-hostname
+#         EOF
+#         sudo chown -R nix-builder:nix-builder /var/lib/nix-builder/.ssh
+#         sudo chmod 700 /var/lib/nix-builder/.ssh
+#         sudo chmod 600 /var/lib/nix-builder/.ssh/authorized_keys
+#
+#       Option B - Via NixOS config (if you store keys in the repo):
+#         users.users.nix-builder.openssh.authorizedKeys.keys = [
+#           "ssh-ed25519 AAAA... root@client-hostname"
+#         ];
+#
+# 2. CLIENT MACHINE SETUP
+#    On machines that will use remote builders (e.g., nix-book):
+#
+#    a) Configure builders in configuration.nix:
+#       roles.remote-build.builders = [
+#         {
+#           hostName = "zix790prors.oglehome";
+#           maxJobs = 16;      # Number of parallel build jobs
+#           speedFactor = 3;   # Higher = prefer this builder
+#         }
+#         {
+#           hostName = "john-endesktop.oglehome";
+#           maxJobs = 1;       # Conservative for busy machines
+#           speedFactor = 1;
+#         }
+#       ];
+#
+#    b) Generate SSH key for root (if not exists) and copy to builders:
+#       sudo ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519 -N ""
+#       sudo cat /root/.ssh/id_ed25519.pub  # Add this to builder's authorized_keys
+#
+#    c) Accept the builder's host key (as root):
+#       sudo ssh nix-builder@zix790prors echo "Connected!"
+#       sudo ssh nix-builder@john-endesktop echo "Connected!"
+#
+# 3. VERIFY SETUP
+#    Test that distributed builds work:
+#      nix build --rebuild nixpkgs#hello --print-build-logs
+#
+#    Check builder connectivity:
+#      nix store ping --store ssh-ng://nix-builder@zix790prors
+#
 { lib, config, pkgs, ... }:
 
 with lib;

roles/virtualisation/default.nix

@@ -8,6 +8,11 @@ in
 {
   options.roles.virtualisation = {
     enable = mkEnableOption "Enable virtualisation";
+    dockerUsers = mkOption {
+      type = types.listOf types.str;
+      default = [ "johno" ];
+      description = "List of users to add to the docker group";
+    };
   };
 
   config = mkIf cfg.enable
@@ -15,6 +20,6 @@ in
       virtualisation.libvirtd.enable = true;
       programs.virt-manager.enable = true;
       virtualisation.docker.enable = true;
-      users.extraGroups.docker.members = [ "johno" ];
+      users.extraGroups.docker.members = cfg.dockerUsers;
     };
 }

scripts/bootstrap.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # bootstrap.sh
-# Usage: sudo ./bootstrap.sh <hostname>
+# Usage: nix run .#bootstrap -- <hostname>
+# Or: sudo ./scripts/bootstrap.sh <hostname>
 set -euo pipefail
 
 NEW_HOSTNAME="${1:?missing hostname}"
@@ -8,4 +9,3 @@ FLAKE_URI="git+https://git.johnogle.info/johno/nixos-configs.git#${NEW_HOSTNAME}
 
 export NIX_CONFIG="experimental-features = nix-command flakes"
 nixos-rebuild switch --flake "$FLAKE_URI"
-

scripts/build-liveusb.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Build Live USB ISO from flake configuration
+# Creates an uncompressed ISO suitable for Ventoy and other USB boot tools
+# Usage: nix run .#build-liveusb
+# Or: ./scripts/build-liveusb.sh
+
+set -euo pipefail
+
+REPO_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+echo "Building Live USB ISO..."
+nix build "${REPO_ROOT}#nixosConfigurations.live-usb.config.system.build.isoImage" --show-trace
+
+if ls "${REPO_ROOT}/result/iso/"*.iso 1> /dev/null 2>&1; then
+    iso_file=$(ls "${REPO_ROOT}/result/iso/"*.iso)
+    echo "Build complete!"
+    echo "ISO location: $iso_file"
+    echo "Ready for Ventoy or dd to USB"
+else
+    echo "Build failed - no ISO file found"
+    exit 1
+fi

scripts/rotate-wallpaper.sh

@@ -1,6 +1,30 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help|-h)
+            echo "Usage: $0 [OPTIONS]"
+            echo ""
+            echo "Rotate to the next wallpaper in the configured list."
+            echo ""
+            echo "This script increments the currentIndex in home/wallpapers/default.nix,"
+            echo "cycling through available wallpapers. Rebuild your system to apply"
+            echo "the new wallpaper."
+            echo ""
+            echo "Options:"
+            echo "  --help, -h    Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'

scripts/update-doomemacs.sh

@@ -1,6 +1,30 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help|-h)
+            echo "Usage: $0 [OPTIONS]"
+            echo ""
+            echo "Update Doom Emacs to the latest commit from the doomemacs repository."
+            echo ""
+            echo "This script fetches the latest commit SHA from the default branch,"
+            echo "updates the rev and sha256 in home/roles/emacs/default.nix, and"
+            echo "prepares the configuration for a system rebuild."
+            echo ""
+            echo "Options:"
+            echo "  --help, -h    Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'

scripts/upgrade.sh

@@ -1,6 +1,35 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help|-h)
+            echo "Usage: $0 [OPTIONS]"
+            echo ""
+            echo "Perform a major upgrade of the NixOS configuration."
+            echo ""
+            echo "This script runs the following steps:"
+            echo "  1. Update all flake inputs (nix flake update)"
+            echo "  2. Update Doom Emacs to the latest commit"
+            echo "  3. Update Claude Code to the latest version"
+            echo "  4. Rotate to the next wallpaper"
+            echo ""
+            echo "After completion, review changes with 'git diff' and rebuild"
+            echo "your system with 'sudo nixos-rebuild switch --flake .'"
+            echo ""
+            echo "Options:"
+            echo "  --help, -h    Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'