Add sendspin-cli package with Python dependencies

Integrate sendspin-cli as a custom package using python3.withPackages. Packages aiosendspin from GitHub since it's only available in nixpkgs-unstable. Includes all required dependencies: aiohttp, av, numpy, qrcode, readchar, rich, sounddevice, and native libraries (portaudio, ffmpeg). Adds uv2nix flake inputs for future migration when sendspin-cli adds a uv.lock file.
2025-12-29 23:46:55 -08:00
15 changed files with 853 additions and 878 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -172,32 +172,6 @@ Creates an ISO suitable for Ventoy and other USB boot tools in `./result/iso/`.
 - **Garbage collection**: Automatic, deletes older than 10 days
 - **Unfree packages**: Allowed globally

-## Issue Tracking (Gitea)
-
-**Tea CLI for Gitea:**
-```bash
-# Note: When using tea CLI, you must specify --repo johno/nixos-configs
-# The CLI doesn't automatically detect the repo from git remote
-
-# List all issues (open by default)
-tea issues --repo johno/nixos-configs
-
-# List closed issues
-tea issues --repo johno/nixos-configs --state closed
-
-# View specific issue
-tea issue --repo johno/nixos-configs 2
-
-# Create new issue
-tea issues create --repo johno/nixos-configs --title "Issue title" --body "Description"
-
-# Add comment to issue
-tea comment --repo johno/nixos-configs 2 "Comment text"
-
-# Close issue (note: 'issues' is plural, issue number comes last)
-tea issues close --repo johno/nixos-configs 2
-```
-
 ## Important Notes

 - **Sudo access**: Claude Code does not have sudo access. Ask the user to run elevated commands like `sudo nixos-rebuild switch`
--- a/flake.lock
+++ b/flake.lock
@@ -180,11 +180,11 @@
    },
    "nixpkgs-unstable": {
      "locked": {
-        "lastModified": 1767379071,
-        "narHash": "sha256-EgE0pxsrW9jp9YFMkHL9JMXxcqi/OoumPJYwf+Okucw=",
+        "lastModified": 1766070988,
+        "narHash": "sha256-G/WVghka6c4bAzMhTwT2vjLccg/awmHkdKSd2JrycLc=",
        "owner": "nixos",
        "repo": "nixpkgs",
-        "rev": "fb7944c166a3b630f177938e478f0378e64ce108",
+        "rev": "c6245e83d836d0433170a16eb185cefe0572f8b8",
        "type": "github"
      },
      "original": {
@@ -256,6 +256,52 @@
        "type": "github"
      }
    },
+    "pyproject-build-systems": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "pyproject-nix"
+        ],
+        "uv2nix": [
+          "uv2nix"
+        ]
+      },
+      "locked": {
+        "lastModified": 1763662255,
+        "narHash": "sha256-4bocaOyLa3AfiS8KrWjZQYu+IAta05u3gYZzZ6zXbT0=",
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "rev": "042904167604c681a090c07eb6967b4dd4dae88c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "type": "github"
+      }
+    },
+    "pyproject-nix": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1764134915,
+        "narHash": "sha256-xaKvtPx6YAnA3HQVp5LwyYG1MaN4LLehpQI8xEdBvBY=",
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "rev": "2c8df1383b32e5443c921f61224b198a2282a657",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "type": "github"
+      }
+    },
    "root": {
      "inputs": {
        "google-cookie-retrieval": "google-cookie-retrieval",
@@ -267,7 +313,33 @@
        "nixpkgs": "nixpkgs_2",
        "nixpkgs-unstable": "nixpkgs-unstable",
        "plasma-manager": "plasma-manager",
-        "plasma-manager-unstable": "plasma-manager-unstable"
+        "plasma-manager-unstable": "plasma-manager-unstable",
+        "pyproject-build-systems": "pyproject-build-systems",
+        "pyproject-nix": "pyproject-nix",
+        "uv2nix": "uv2nix"
+      }
+    },
+    "uv2nix": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "pyproject-nix"
+        ]
+      },
+      "locked": {
+        "lastModified": 1766021660,
+        "narHash": "sha256-UUfz7qWB1Rb2KjGVCimt//Jncv3TgJwffPqbzqpkmgY=",
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "rev": "19fa99be3409f55ec05e823c66c9769df7a8dd17",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "type": "github"
      }
    }
  },
--- a/flake.nix
+++ b/flake.nix
@@ -42,9 +42,27 @@
      url = "github:Jovian-Experiments/Jovian-NixOS";
      inputs.nixpkgs.follows = "nixpkgs-unstable";
    };
+
+    pyproject-nix = {
+      url = "github:pyproject-nix/pyproject.nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    uv2nix = {
+      url = "github:pyproject-nix/uv2nix";
+      inputs.pyproject-nix.follows = "pyproject-nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    pyproject-build-systems = {
+      url = "github:pyproject-nix/build-system-pkgs";
+      inputs.pyproject-nix.follows = "pyproject-nix";
+      inputs.uv2nix.follows = "uv2nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
  };

-  outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, ... } @ inputs: let
+  outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, pyproject-nix, uv2nix, pyproject-build-systems, ... } @ inputs: let
    nixosModules = [
      ./roles
    ] ++ [
@@ -56,7 +74,7 @@
              system = prev.stdenv.hostPlatform.system;
              config.allowUnfree = true;
            };
-            custom = prev.callPackage ./packages {};
+            custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
          })
@@ -84,7 +102,7 @@
              system = prev.stdenv.hostPlatform.system;
              config.allowUnfree = true;
            };
-            custom = prev.callPackage ./packages {};
+            custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
          })
@@ -117,7 +135,7 @@
                })
              ];
            };
-            custom = prev.callPackage ./packages {};
+            custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
          })
@@ -152,9 +170,9 @@
      system = "x86_64-linux";
      modules = nixosModules ++ [
        ./machines/boxy/configuration.nix
+        inputs.home-manager.nixosModules.home-manager
        {
          home-manager.users.johno = import ./home/home-media-center.nix;
-          home-manager.users.kodi = import ./home/home-kodi.nix;
          home-manager.extraSpecialArgs = { inherit system; };
        }
      ];
@@ -209,15 +227,6 @@
      ];
    };

-    # ZFS/NFS server configuration
-    nixosConfigurations.john-endesktop = nixpkgs.lib.nixosSystem rec {
-      system = "x86_64-linux";
-      modules = nixosModules ++ [
-        ./machines/john-endesktop/configuration.nix
-        # Minimal server - no home-manager needed
-      ];
-    };
-
    # Darwin/macOS configurations
    darwinConfigurations."blkfv4yf49kt7" = inputs.nix-darwin.lib.darwinSystem rec {
      system = "aarch64-darwin";
--- a/home/home-kodi.nix
+++ b/home/home-kodi.nix
@@ -1,28 +0,0 @@
-{ pkgs, globalInputs, system, ... }:
-
-{
-  # Home Manager configuration for kodi user on boxy
-  # Focused on media center volume control via Home Assistant
-
-  home.username = "kodi";
-  home.homeDirectory = "/home/kodi";
-  home.stateVersion = "24.05";
-
-  # Enable minimal roles for kodi user
-  home.roles = {
-    base.enable = true;
-    plasma-manager-kodi.enable = true;
-  };
-
-  home.packages = with pkgs; [
-    kdePackages.kconfig
-  ];
-
-  targets.genericLinux.enable = true;
-  home.sessionVariables = {};
-  home.sessionPath = [];
-
-  imports = [
-    ./roles
-  ];
-}
--- a/home/roles/default.nix
+++ b/home/roles/default.nix
@@ -15,7 +15,6 @@
    ./launchers
    ./media
    ./office
-    ./plasma-manager-kodi
    ./sync
    ./tmux
    ./emacs
--- a/home/roles/plasma-manager-kodi/default.nix
+++ b/home/roles/plasma-manager-kodi/default.nix
@@ -1,199 +0,0 @@
-{ config, lib, pkgs, ... }:
-
-with lib;
-
-let
-  cfg = config.home.roles.plasma-manager-kodi;
-
-  # Define the volume control scripts as derivations
-  volumeUpScript = pkgs.writeShellScript "avr-volume-up" ''
-    #!/usr/bin/env bash
-
-    # Configuration
-    HA_URL="https://home-assistant.johnogle.info"
-    ENTITY_ID="media_player.denon_avr_s970h_2"
-    MAX_RETRIES=3
-
-    # Read token from KDE Wallet and strip whitespace
-    TOKEN=$(${pkgs.kdePackages.kwallet}/bin/kwallet-query -r ha_avr_token kdewallet -f Passwords 2>/dev/null | tr -d '[:space:]')
-
-    if [ -z "$TOKEN" ]; then
-      ${pkgs.libnotify}/bin/notify-send -u critical "Volume Control Error" "Failed to retrieve Home Assistant token from KDE Wallet"
-      exit 1
-    fi
-
-    # Send volume up command with retry logic
-    for i in $(seq 1 $MAX_RETRIES); do
-      RESPONSE=$(${pkgs.curl}/bin/curl -s -w "\n%{http_code}" -X POST \
-        -H "Authorization: Bearer $TOKEN" \
-        -H "Content-Type: application/json" \
-        -d "{\"entity_id\": \"$ENTITY_ID\"}" \
-        "$HA_URL/api/services/media_player/volume_up" 2>&1)
-
-      HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-
-      if [ "$HTTP_CODE" = "200" ]; then
-        exit 0
-      fi
-
-      # Wait before retry (except on last attempt)
-      if [ $i -lt $MAX_RETRIES ]; then
-        sleep 0.5
-      fi
-    done
-
-    # All retries failed
-    ${pkgs.libnotify}/bin/notify-send -u critical "Volume Control Error" "Failed to increase volume after $MAX_RETRIES attempts"
-    exit 1
-  '';
-
-  volumeDownScript = pkgs.writeShellScript "avr-volume-down" ''
-    #!/usr/bin/env bash
-
-    # Configuration
-    HA_URL="https://home-assistant.johnogle.info"
-    ENTITY_ID="media_player.denon_avr_s970h_2"
-    MAX_RETRIES=3
-
-    # Read token from KDE Wallet and strip whitespace
-    TOKEN=$(${pkgs.kdePackages.kwallet}/bin/kwallet-query -r ha_avr_token kdewallet -f Passwords 2>/dev/null | tr -d '[:space:]')
-
-    if [ -z "$TOKEN" ]; then
-      ${pkgs.libnotify}/bin/notify-send -u critical "Volume Control Error" "Failed to retrieve Home Assistant token from KDE Wallet"
-      exit 1
-    fi
-
-    # Send volume down command with retry logic
-    for i in $(seq 1 $MAX_RETRIES); do
-      RESPONSE=$(${pkgs.curl}/bin/curl -s -w "\n%{http_code}" -X POST \
-        -H "Authorization: Bearer $TOKEN" \
-        -H "Content-Type: application/json" \
-        -d "{\"entity_id\": \"$ENTITY_ID\"}" \
-        "$HA_URL/api/services/media_player/volume_down" 2>&1)
-
-      HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-
-      if [ "$HTTP_CODE" = "200" ]; then
-        exit 0
-      fi
-
-      # Wait before retry (except on last attempt)
-      if [ $i -lt $MAX_RETRIES ]; then
-        sleep 0.5
-      fi
-    done
-
-    # All retries failed
-    ${pkgs.libnotify}/bin/notify-send -u critical "Volume Control Error" "Failed to decrease volume after $MAX_RETRIES attempts"
-    exit 1
-  '';
-
-  volumeMuteScript = pkgs.writeShellScript "avr-volume-mute" ''
-    #!/usr/bin/env bash
-
-    # Configuration
-    HA_URL="https://home-assistant.johnogle.info"
-    ENTITY_ID="media_player.denon_avr_s970h_2"
-    MAX_RETRIES=3
-
-    # Read token from KDE Wallet and strip whitespace
-    TOKEN=$(${pkgs.kdePackages.kwallet}/bin/kwallet-query -r ha_avr_token kdewallet -f Passwords 2>/dev/null | tr -d '[:space:]')
-
-    if [ -z "$TOKEN" ]; then
-      ${pkgs.libnotify}/bin/notify-send -u critical "Volume Control Error" "Failed to retrieve Home Assistant token from KDE Wallet"
-      exit 1
-    fi
-
-    # Get current mute state
-    STATE_RESPONSE=$(${pkgs.curl}/bin/curl -s -H "Authorization: Bearer $TOKEN" \
-      "$HA_URL/api/states/$ENTITY_ID")
-
-    CURRENT_MUTE=$(echo "$STATE_RESPONSE" | ${pkgs.jq}/bin/jq -r '.attributes.is_volume_muted // false')
-
-    # Toggle: if currently muted (true), unmute (false), and vice versa
-    if [ "$CURRENT_MUTE" = "true" ]; then
-      NEW_MUTE="false"
-      NOTIFY_MSG="Unmuted"
-    else
-      NEW_MUTE="true"
-      NOTIFY_MSG="Muted"
-    fi
-
-    # Send mute toggle command with retry logic
-    for i in $(seq 1 $MAX_RETRIES); do
-      RESPONSE=$(${pkgs.curl}/bin/curl -s -w "\n%{http_code}" -X POST \
-        -H "Authorization: Bearer $TOKEN" \
-        -H "Content-Type: application/json" \
-        -d "{\"entity_id\": \"$ENTITY_ID\", \"is_volume_muted\": $NEW_MUTE}" \
-        "$HA_URL/api/services/media_player/volume_mute" 2>&1)
-
-      HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-
-      if [ "$HTTP_CODE" = "200" ]; then
-        exit 0
-      fi
-
-      # Wait before retry (except on last attempt)
-      if [ $i -lt $MAX_RETRIES ]; then
-        sleep 0.5
-      fi
-    done
-
-    # All retries failed
-    ${pkgs.libnotify}/bin/notify-send -u critical "Volume Control Error" "Failed to toggle mute after $MAX_RETRIES attempts"
-    exit 1
-  '';
-in
-{
-  options.home.roles.plasma-manager-kodi = {
-    enable = mkEnableOption "KDE Plasma volume control for kodi user via Home Assistant";
-  };
-
-  config = mkIf cfg.enable {
-    programs.plasma = {
-      enable = true;
-      overrideConfig = true;
-
-      # Disable default kmix volume shortcuts to prevent conflicts
-      shortcuts.kmix = {
-        "increase_volume" = "none";
-        "decrease_volume" = "none";
-        "mute" = "none";
-      };
-
-      # Define custom volume control commands with key bindings
-      hotkeys.commands = {
-        "volume-up-avr" = {
-          name = "Volume Up AVR";
-          key = "Volume Up";
-          command = toString volumeUpScript;
-        };
-
-        "volume-down-avr" = {
-          name = "Volume Down AVR";
-          key = "Volume Down";
-          command = toString volumeDownScript;
-        };
-
-        "volume-mute-avr" = {
-          name = "Mute Toggle AVR";
-          key = "Volume Mute";
-          command = toString volumeMuteScript;
-        };
-      };
-
-      # KDE Settings customization
-      configFile = {
-        # Session restore settings
-        "ksmserverrc"."General"."loginMode" = "emptySession";
-
-        # Screen locking settings
-        "kscreenlockerrc"."Daemon"."Autolock" = false;
-        "kscreenlockerrc"."Daemon"."LockOnResume" = false;
-
-        # Theme settings
-        "kdeglobals"."KDE"."LookAndFeelPackage" = "org.kde.breezedark.desktop";
-      };
-    };
-  };
-}
--- a/machines/boxy/configuration.nix
+++ b/machines/boxy/configuration.nix
@@ -26,20 +26,11 @@ with lib;
      enable = true;
      autologin = true;
      wayland = true;
-      jellyfinScaleFactor = 1.0;
+      jellyfinScaleFactor = 2.5;
    };
-    nfs-mounts.enable = true;
    users.enable = true;
  };

-  # Enable KDE Wallet PAM integration for auto-unlock
-  security.pam.services.sddm = {
-    kwallet = {
-      enable = true;
-      package = pkgs.kdePackages.kwallet-pam;
-    };
-  };
-
  # Use the systemd-boot EFI boot loader.
  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;
--- a/machines/john-endesktop/MIGRATION_PLAN.md
+++ b/machines/john-endesktop/MIGRATION_PLAN.md
@@ -1,423 +0,0 @@
-# Migration Plan: Arch Linux to NixOS on john-endesktop (ZFS/NFS Server)
-
-## Overview
-This document outlines the plan to migrate the john-endesktop server from Arch Linux to NixOS while maintaining the existing ZFS pools and NFS exports that serve your k3s cluster.
-
-## Current System State
-
-### Hardware
- **Boot disk**: nvme0n1
-  - nvme0n1p3: 1000M EFI partition (UUID: F5C6-D570)
-  - nvme0n1p4: 120GB ext4 / (current Arch root)
-  - nvme0n1p5: 810GB - **Target for NixOS** (being removed from media pool)
- **Network**: enp0s31f6 @ 10.0.0.43/24 (DHCP)
-
-### ZFS Pools
- **media**: ~3.5TB JBOD pool (2 drives after nvme0n1p5 removal)
-  - wwn-0x50014ee2ba653d70-part2
-  - ata-WDC_WD20EZBX-00AYRA0_WD-WX62D627X7Z8-part2
-  - Contains: /media/media/nix (bind mounted to /nix on Arch)
-  - NFS: Shared to 10.0.0.0/24 via ZFS sharenfs property
-
- **swarmvols**: 928GB mirror pool - **PRODUCTION DATA**
-  - wwn-0x5002538f52707e2d-part2
-  - wwn-0x5002538f52707e81-part2
-  - Contains: iocage jails and k3s persistent volumes
-  - NFS: Shared to 10.0.0.0/24 via ZFS sharenfs property
-  - Backed up nightly to remote borg
-
-### Services
- NFS server exporting /media and /swarmvols to k3s cluster
- ZFS managing pools with automatic exports via sharenfs property
-
-## Prerequisites
-
-### Before Starting
-1. ✅ Ensure nvme0n1p5 removal from media pool is complete
-   ```bash
-   ssh 10.0.0.43 "zpool status media"
-   # Should show no "removing" devices
-   ```
-
-2. ✅ Verify recent backups exist
-   ```bash
-   # Verify swarmvols backup is recent (< 24 hours)
-   # Check your borg backup system
-   ```
-
-3. ✅ Notify k3s cluster users of planned maintenance window
-   - NFS shares will be unavailable during migration
-   - Estimate: 30-60 minutes downtime
-
-4. ✅ Build NixOS configuration from your workstation
-   ```bash
-   cd ~/nixos-configs
-   nix build .#nixosConfigurations.john-endesktop.config.system.build.toplevel
-   ```
-
-## Migration Steps
-
-### Phase 1: Prepare NixOS Installation Media
-
-1. **Download NixOS minimal ISO**
-   ```bash
-   wget https://channels.nixos.org/nixos-25.11/latest-nixos-minimal-x86_64-linux.iso
-   ```
-
-2. **Create bootable USB**
-   ```bash
-   # Identify USB device (e.g., /dev/sdb)
-   lsblk
-   # Write ISO to USB
-   sudo dd if=latest-nixos-minimal-x86_64-linux.iso of=/dev/sdX bs=4M status=progress
-   sudo sync
-   ```
-
-### Phase 2: Backup and Shutdown
-
-1. **On the server, verify ZFS pool status**
-   ```bash
-   ssh 10.0.0.43 "zpool status"
-   ssh 10.0.0.43 "zfs list"
-   ```
-
-2. **Export ZFS pools cleanly**
-   ```bash
-   ssh 10.0.0.43 "sudo zpool export media"
-   ssh 10.0.0.43 "sudo zpool export swarmvols"
-   ```
-
-3. **Shutdown Arch Linux**
-   ```bash
-   ssh 10.0.0.43 "sudo shutdown -h now"
-   ```
-
-### Phase 3: Install NixOS
-
-1. **Boot from NixOS USB**
-   - Insert USB drive
-   - Power on and select USB in boot menu
-
-2. **Connect to network**
-   ```bash
-   # If DHCP doesn't work automatically:
-   sudo systemctl start dhcpcd
-   ip a  # Verify you have 10.0.0.43 or another IP
-   ```
-
-3. **Enable SSH for remote installation (recommended)**
-   ```bash
-   # Set password for nixos user
-   sudo passwd nixos
-   # Start SSH
-   sudo systemctl start sshd
-   # From your workstation:
-   ssh nixos@10.0.0.43
-   ```
-
-4. **Partition nvme0n1p5 with btrfs**
-   ```bash
-   # Verify the device is clear
-   lsblk
-   sudo wipefs -a /dev/nvme0n1p5
-
-   # Create btrfs filesystem
-   sudo mkfs.btrfs -L nixos /dev/nvme0n1p5
-
-   # Mount and create subvolumes
-   sudo mount /dev/nvme0n1p5 /mnt
-   sudo btrfs subvolume create /mnt/@
-   sudo btrfs subvolume create /mnt/@home
-   sudo btrfs subvolume create /mnt/@nix
-   sudo btrfs subvolume create /mnt/@log
-   sudo umount /mnt
-
-   # Mount root subvolume
-   sudo mount -o subvol=@,compress=zstd,noatime /dev/nvme0n1p5 /mnt
-
-   # Create mount points
-   sudo mkdir -p /mnt/{boot,home,nix,var/log}
-
-   # Mount other subvolumes
-   sudo mount -o subvol=@home,compress=zstd,noatime /dev/nvme0n1p5 /mnt/home
-   sudo mount -o subvol=@nix,compress=zstd,noatime /dev/nvme0n1p5 /mnt/nix
-   sudo mount -o subvol=@log,compress=zstd,noatime /dev/nvme0n1p5 /mnt/var/log
-
-   # Mount EFI partition
-   sudo mount /dev/nvme0n1p3 /mnt/boot
-   ```
-
-5. **Import ZFS pools**
-   ```bash
-   # Import pools (should be visible)
-   sudo zpool import
-
-   # Import with force if needed due to hostid
-   sudo zpool import -f media
-   sudo zpool import -f swarmvols
-
-   # Verify pools are mounted
-   zfs list
-   ls -la /media /swarmvols
-   ```
-
-6. **Generate initial hardware configuration**
-   ```bash
-   sudo nixos-generate-config --root /mnt
-   ```
-
-7. **Get the new root filesystem UUID**
-   ```bash
-   blkid /dev/nvme0n1p5
-   # Note the UUID for updating hardware-configuration.nix
-   ```
-
-8. **Copy your NixOS configuration to the server**
-   ```bash
-   # From your workstation:
-   scp -r ~/nixos-configs/machines/john-endesktop/* nixos@10.0.0.43:/tmp/
-
-   # On server:
-   sudo mkdir -p /mnt/etc/nixos
-   sudo cp /tmp/configuration.nix /mnt/etc/nixos/
-   sudo cp /tmp/hardware-configuration.nix /mnt/etc/nixos/
-
-   # Edit hardware-configuration.nix to update the root filesystem UUID
-   sudo nano /mnt/etc/nixos/hardware-configuration.nix
-   # Change: device = "/dev/disk/by-uuid/CHANGE-THIS-TO-YOUR-UUID";
-   # To:     device = "/dev/disk/by-uuid/[UUID from blkid]";
-   ```
-
-9. **Install NixOS**
-   ```bash
-   sudo nixos-install
-
-   # Set root password when prompted
-   # Set user password
-   sudo nixos-install --no-root-passwd
-   ```
-
-10. **Reboot into NixOS**
-    ```bash
-    sudo reboot
-    # Remove USB drive
-    ```
-
-### Phase 4: Post-Installation Verification
-
-1. **Boot into NixOS and verify system**
-   ```bash
-   ssh johno@10.0.0.43
-
-   # Check NixOS version
-   nixos-version
-
-   # Verify hostname
-   hostname  # Should be: john-endesktop
-   ```
-
-2. **Verify ZFS pools imported correctly**
-   ```bash
-   zpool status
-   zpool list
-   zfs list
-
-   # Check for hostid mismatch warnings (should be gone)
-   # Verify both pools show ONLINE status
-   ```
-
-3. **Verify NFS exports are active**
-   ```bash
-   sudo exportfs -v
-   systemctl status nfs-server
-
-   # Should see /media and /swarmvols exported to 10.0.0.0/24
-   ```
-
-4. **Test NFS mount from another machine**
-   ```bash
-   # From a k3s node or your workstation:
-   sudo mount -t nfs 10.0.0.43:/swarmvols /mnt
-   ls -la /mnt
-   sudo umount /mnt
-
-   sudo mount -t nfs 10.0.0.43:/media /mnt
-   ls -la /mnt
-   sudo umount /mnt
-   ```
-
-5. **Verify ZFS sharenfs properties preserved**
-   ```bash
-   zfs get sharenfs media
-   zfs get sharenfs swarmvols
-
-   # Should show: sec=sys,mountpoint,no_subtree_check,no_root_squash,rw=@10.0.0.0/24
-   ```
-
-6. **Check swap device**
-   ```bash
-   swapon --show
-   free -h
-   # Should show /dev/zvol/media/swap
-   ```
-
-### Phase 5: Restore k3s Cluster Access
-
-1. **Restart k3s nodes or remount NFS shares**
-   ```bash
-   # On each k3s node:
-   sudo systemctl restart k3s  # or k3s-agent
-   ```
-
-2. **Verify k3s pods have access to persistent volumes**
-   ```bash
-   # On k3s master:
-   kubectl get pv
-   kubectl get pvc
-   # Check that volumes are bound and accessible
-   ```
-
-## Rollback Plan
-
-If something goes wrong during migration, you can roll back to Arch Linux:
-
-### Quick Rollback (If NixOS won't boot)
-
-1. **Boot from NixOS USB (or Arch USB)**
-
-2. **Import ZFS pools**
-   ```bash
-   sudo zpool import -f media
-   sudo zpool import -f swarmvols
-   ```
-
-3. **Start NFS manually (temporary)**
-   ```bash
-   sudo mkdir -p /media /swarmvols
-   sudo systemctl start nfs-server
-   sudo exportfs -o rw,sync,no_subtree_check,no_root_squash 10.0.0.0/24:/media
-   sudo exportfs -o rw,sync,no_subtree_check,no_root_squash 10.0.0.0/24:/swarmvols
-   sudo exportfs -v
-   ```
-   This will restore k3s cluster access immediately while you diagnose.
-
-4. **Boot back into Arch Linux**
-   ```bash
-   # Reboot and select nvme0n1p4 (Arch) in GRUB/boot menu
-   sudo reboot
-   ```
-
-5. **Verify Arch boots and services start**
-   ```bash
-   ssh johno@10.0.0.43
-   zpool status
-   systemctl status nfs-server
-   ```
-
-### Full Rollback (If needed)
-
-1. **Follow Quick Rollback steps above**
-
-2. **Re-add nvme0n1p5 to media pool (if desired)**
-   ```bash
-   # Only if you want to restore the original configuration
-   sudo zpool add media /dev/nvme0n1p5
-   ```
-
-3. **Clean up NixOS partition**
-   ```bash
-   # If you want to reclaim nvme0n1p5 for other uses
-   sudo wipefs -a /dev/nvme0n1p5
-   ```
-
-## Risk Mitigation
-
-### Data Safety
- ✅ **swarmvols** (production): Mirrored + nightly borg backups
- ⚠️  **media** (important): JBOD - no redundancy, but not catastrophic
- ✅ **NixOS install**: Separate partition, doesn't touch ZFS pools
- ✅ **Arch Linux**: Remains bootable on nvme0n1p4 until verified
-
-### Service Continuity
- Downtime: 30-60 minutes expected
- k3s cluster: Will reconnect automatically when NFS returns
- Rollback time: < 10 minutes to restore Arch
-
-### Testing Approach
-1. Test NFS exports from NixOS live environment before installation
-2. Test single NFS mount from k3s node before full cluster restart
-3. Keep Arch Linux boot option until 24-48 hours of stable NixOS operation
-
-## Post-Migration Tasks
-
-After successful migration and 24-48 hours of stable operation:
-
-1. **Update k3s NFS mounts (if needed)**
-   - Verify no hardcoded references to old system
-
-2. **Optional: Repurpose Arch partition**
-   ```bash
-   # After you're confident NixOS is stable
-   # You can wipe nvme0n1p4 and repurpose it
-   ```
-
-3. **Update documentation**
-   - Update infrastructure docs with NixOS configuration
-   - Document any deviations from this plan
-
-4. **Consider setting up NixOS remote deployment**
-   ```bash
-   # From your workstation:
-   nixos-rebuild switch --target-host johno@10.0.0.43 --flake .#john-endesktop
-   ```
-
-## Timeline
-
- **Preparation**: 1-2 hours (testing config build, downloading ISO)
- **Migration window**: 1-2 hours (installation + verification)
- **Verification period**: 24-48 hours (before removing Arch)
- **Total**: ~3 days from start to declaring success
-
-## Emergency Contacts
-
- Borg backup location: [Document your borg repo location]
- K3s cluster nodes: [Document your k3s nodes]
- Critical services on k3s: [Document what's running that depends on these NFS shares]
-
-## Checklist
-
-Pre-migration:
- [x] nvme0n1p5 removal from media pool complete
- [ ] Recent backup verified (< 24 hours)
- [ ] Maintenance window scheduled
- [ ] NixOS ISO downloaded
- [ ] Bootable USB created
- [ ] NixOS config builds successfully
-
-During migration:
- [ ] ZFS pools exported
- [ ] Arch Linux shutdown cleanly
- [ ] Booted from NixOS USB
- [ ] nvme0n1p5 formatted with btrfs
- [ ] Btrfs subvolumes created
- [ ] ZFS pools imported
- [ ] NixOS installed
- [ ] Root password set
-
-Post-migration:
- [ ] NixOS boots successfully
- [ ] ZFS pools mounted automatically
- [ ] NFS server running
- [ ] NFS exports verified
- [ ] Test mount from k3s node successful
- [ ] k3s cluster reconnected
- [ ] Persistent volumes accessible
- [ ] No hostid warnings in zpool status
- [ ] Arch Linux still bootable (for rollback)
-
-Final verification (after 24-48 hours):
- [ ] All services stable
- [ ] No unexpected issues
- [ ] Performance acceptable
- [ ] Ready to remove Arch partition (optional)
- [ ] Ready to remove /swarmvols/media-backup (optional)
--- a/machines/john-endesktop/configuration.nix
+++ b/machines/john-endesktop/configuration.nix
@@ -1,112 +0,0 @@
-# NixOS configuration for john-endesktop (ZFS/NFS server)
-# Migrated from Arch Linux to provide ZFS pools via NFS to k3s cluster
-
-{ config, lib, pkgs, ... }:
-
-with lib;
-
-{
-  imports = [
-    ./hardware-configuration.nix
-  ];
-
-  # Boot configuration
-  boot.loader.systemd-boot.enable = true;
-  boot.loader.efi.canTouchEfiVariables = true;
-
-  # ZFS support
-  boot.supportedFilesystems = [ "zfs" ];
-  boot.zfs.forceImportRoot = false;
-  boot.zfs.extraPools = [ "media" "swarmvols" ];
-
-  # Set ZFS hostid to match current system (from Arch Linux)
-  # This resolves the hostid mismatch warnings
-  networking.hostId = "007f0101";
-
-  # Hostname
-  networking.hostName = "john-endesktop";
-
-  # Network configuration - using DHCP on enp0s31f6
-  networking.useDHCP = false;
-  networking.interfaces.enp0s31f6.useDHCP = true;
-
-  # NFS Server configuration
-  services.nfs.server = {
-    enable = true;
-
-    # NFS protocol versions
-    # v3 for broader compatibility, v4 for better performance
-    exports = ''
-      # These are managed by ZFS sharenfs properties
-      # but we enable the NFS server here
-    '';
-  };
-
-  # Enable NFS4 with proper configuration
-  services.rpcbind.enable = true;
-
-  # Firewall configuration for NFS
-  networking.firewall = {
-    enable = true;
-    allowedTCPPorts = [
-      111   # rpcbind
-      2049  # nfs
-      4000  # nfs callback
-      4001  # nlockmgr
-      4002  # mountd
-      20048 # mountd
-    ];
-    allowedUDPPorts = [
-      111   # rpcbind
-      2049  # nfs
-      4000  # nfs callback
-      4001  # nlockmgr
-      4002  # mountd
-      20048 # mountd
-    ];
-    # Allow NFS from local network
-    extraCommands = ''
-      iptables -A nixos-fw -p tcp -s 10.0.0.0/24 -j ACCEPT
-      iptables -A nixos-fw -p udp -s 10.0.0.0/24 -j ACCEPT
-    '';
-  };
-
-  # ZFS maintenance
-  services.zfs = {
-    autoScrub = {
-      enable = true;
-      interval = "monthly";
-    };
-    trim = {
-      enable = true;
-      interval = "weekly";
-    };
-  };
-
-  # Basic system packages
-  environment.systemPackages = with pkgs; [
-    vim
-    git
-    htop
-    tmux
-    zfs
-  ];
-
-  # Enable SSH
-  services.openssh = {
-    enable = true;
-    settings = {
-      PermitRootLogin = "no";
-      PasswordAuthentication = true;
-    };
-  };
-
-  # User configuration
-  roles.users.enable = true;
-
-  # Time zone
-  time.timeZone = "America/Los_Angeles"; # Adjust as needed
-
-  # NixOS version
-  system.stateVersion = "25.11";
-}
--- a/machines/john-endesktop/hardware-configuration.nix
+++ b/machines/john-endesktop/hardware-configuration.nix
@@ -1,48 +0,0 @@
-# Hardware configuration for john-endesktop
-# This file should be regenerated after NixOS installation using:
-# nixos-generate-config --show-hardware-config
-
-{ config, lib, pkgs, modulesPath, ... }:
-
-{
-  imports = [
-    (modulesPath + "/installer/scan/not-detected.nix")
-  ];
-
-  # Boot configuration
-  boot.initrd.availableKernelModules = [ "xhci_pci" "ahci" "nvme" "usbhid" "usb_storage" "sd_mod" ];
-  boot.initrd.kernelModules = [ ];
-  boot.kernelModules = [ "kvm-intel" ];
-  boot.extraModulePackages = [ ];
-
-  # File systems - these will need to be updated after installation
-  # The nvme0n1p5 partition will be formatted as btrfs for NixOS root
-  fileSystems."/" = {
-    # Update this device path after installation
-    device = "/dev/disk/by-uuid/CHANGE-THIS-TO-YOUR-UUID";
-    fsType = "btrfs";
-    options = [ "subvol=@" "compress=zstd" "noatime" ];
-  };
-
-  fileSystems."/boot" = {
-    # This should match your current EFI partition
-    device = "/dev/disk/by-uuid/F5C6-D570";
-    fsType = "vfat";
-    options = [ "fmask=0022" "dmask=0022" ];
-  };
-
-  # ZFS pools - these are imported by ZFS, not managed by fileSystems
-  # The pools should be imported automatically via boot.zfs.extraPools
-  # /media and /swarmvols will be mounted by ZFS
-
-  # Swap - using ZFS zvol
-  swapDevices = [
-    { device = "/dev/zvol/media/swap"; }
-  ];
-
-  # CPU microcode
-  hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;
-
-  # Networking
-  networking.useDHCP = lib.mkDefault true;
-}
--- a/machines/nix-book/configuration.nix
+++ b/machines/nix-book/configuration.nix
@@ -39,16 +39,6 @@
  boot.loader.efi.canTouchEfiVariables = true;

  boot.initrd.luks.devices."luks-b614167b-9045-4234-a441-ac6f60a96d81".device = "/dev/disk/by-uuid/b614167b-9045-4234-a441-ac6f60a96d81";
-
-  # S3 deep sleep broken on Alder Lake - use direct hibernate on lid close
-  services.logind.settings.Login = {
-    HandleLidSwitch = "hibernate";
-    HandleLidSwitchExternalPower = "hibernate";
-    HandleLidSwitchDocked = "hibernate";
-    HandlePowerKey = "hibernate";
-    HandlePowerKeyLongPress = "poweroff";
-  };
-
  networking.hostName = "nix-book"; # Define your hostname.
  # networking.wireless.enable = true;  # Enables wireless support via wpa_supplicant.

--- a/packages/default.nix
+++ b/packages/default.nix
@@ -1,7 +1,8 @@
-{ pkgs, ... }:
+{ pkgs, uv2nix ? null, pyproject-nix ? null, pyproject-build-systems ? null, ... }:
 {
  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 {};
+  sendspin-cli = pkgs.callPackage ./sendspin-cli { inherit uv2nix pyproject-nix pyproject-build-systems; };
 }
--- a/packages/sendspin-cli/default.nix
+++ b/packages/sendspin-cli/default.nix
@@ -0,0 +1,91 @@
+{ pkgs
+, lib
+, fetchFromGitHub
+, uv2nix ? null
+, pyproject-nix ? null
+, pyproject-build-systems ? null
+}:
+
+# Simple package build
+# Note: uv2nix would be ideal but requires uv.lock which sendspin-cli doesn't have yet
+let
+  # Package aiosendspin from GitHub since it's only in nixpkgs-unstable
+  aiosendspin = pkgs.python312Packages.buildPythonPackage rec {
+    pname = "aiosendspin";
+    version = "1.2.0";
+    pyproject = true;
+
+    src = fetchFromGitHub {
+      owner = "Sendspin";
+      repo = "aiosendspin";
+      rev = version;
+      sha256 = "sha256-3vTEfXeFqouPswRKST/9U7yg9ah7J9m2KAMoxaBZNR0=";
+    };
+
+    build-system = with pkgs.python312Packages; [
+      hatchling
+      setuptools
+    ];
+
+    dependencies = with pkgs.python312Packages; [
+      aiohttp
+      av
+      mashumaro
+      orjson
+      pillow
+      zeroconf
+    ];
+
+    pythonImportsCheck = [ "aiosendspin" ];
+
+    meta = {
+      description = "Async Python implementation of the Sendspin Protocol";
+      homepage = "https://github.com/Sendspin-Protocol/aiosendspin";
+      license = lib.licenses.asl20;
+    };
+  };
+
+  python = pkgs.python312.withPackages (ps: with ps; [
+    # Core dependencies from pyproject.toml
+    aiosendspin
+    av
+    numpy
+    qrcode
+    readchar
+    rich
+    sounddevice
+    setuptools
+  ]);
+in
+pkgs.stdenv.mkDerivation rec {
+  pname = "sendspin-cli";
+  version = "0.0.0";
+
+  src = fetchFromGitHub {
+    owner = "Sendspin";
+    repo = "sendspin-cli";
+    rev = "main";
+    sha256 = "sha256-z8ieaDHv4C6WNLpPGybhcfB+E6Jj/rCc7zSRpL6vdk0=";
+  };
+
+  buildInputs = [ python pkgs.portaudio pkgs.ffmpeg ];
+
+  installPhase = ''
+    mkdir -p $out/bin $out/lib
+    cp -r sendspin $out/lib/
+    cat > $out/bin/sendspin <<EOF
+#!/bin/sh
+export PYTHONPATH="$out/lib:\$PYTHONPATH"
+export LD_LIBRARY_PATH="${pkgs.portaudio}/lib:${pkgs.ffmpeg}/lib:\$LD_LIBRARY_PATH"
+exec ${python}/bin/python3 -m sendspin.cli "\$@"
+EOF
+    chmod +x $out/bin/sendspin
+  '';
+
+  meta = {
+    description = "Synchronized audio player for Sendspin servers";
+    homepage = "https://github.com/Sendspin/sendspin-cli";
+    license = lib.licenses.asl20;
+    platforms = lib.platforms.linux;
+  };
+}
--- a/roles/desktop/gaming.nix
+++ b/roles/desktop/gaming.nix
@@ -22,8 +22,6 @@ in
        # indiviudal cores
        #retroarch-full
        ryubing
-
-        yarg
      ];

      programs.steam = {
--- a/thoughts/shared/plans/2025-12-29-sendspin-cli-integration.md
+++ b/thoughts/shared/plans/2025-12-29-sendspin-cli-integration.md
@@ -0,0 +1,660 @@
+# Sendspin-CLI Integration Implementation Plan
+
+## Overview
+
+Integrate sendspin-cli (https://github.com/Sendspin/sendspin-cli) into the NixOS configuration using uv2nix for Python packaging. Provide a flexible systemd service template that runs as the graphical user, supporting multiple use cases: standalone media centers (like `boxy` running as `kodi` user) and desktop workstations (like `zix790prors` running as `johno` user).
+
+## Current State Analysis
+
+**Existing Infrastructure:**
+- Custom package system using overlays at flake.nix:54-59
+- Packages defined in `packages/default.nix` and exposed as `pkgs.custom.<name>`
+- Role-based configuration system with audio role at roles/audio/default.nix:1-41
+- User-level systemd services pattern demonstrated in machines/zix790prors/virtual-surround.nix:79-103
+- Python packaging pattern using `python3.withPackages` at packages/app-launcher-server/default.nix:1-10
+
+**Sendspin-CLI Analysis:**
+- Python 3.12+ application with setuptools build system
+- Entry point: `sendspin.cli:main` (sendspin-cli/sendspin/cli.py:143)
+- Dependencies: aiosendspin, av, numpy, qrcode, readchar, rich, sounddevice (sendspin-cli/pyproject.toml:16-23)
+- Native dependencies needed: portaudio (for sounddevice), ffmpeg (for av)
+- Supports headless mode via `--headless` flag (sendspin-cli/sendspin/cli.py:115-117)
+- Device selection via `--audio-device <index|name>` (sendspin-cli/sendspin/cli.py:96-102)
+- Device discovery via `--list-audio-devices` (sendspin-cli/sendspin/cli.py:15-34)
+- Auto-discovers servers via mDNS unless `--url` specified (sendspin-cli/sendspin/cli.py:69-71)
+- No `uv.lock` file currently in repository (only `pyproject.toml`)
+
+**Gap:**
+- No uv2nix flake inputs (pyproject-nix, uv2nix, pyproject-build-systems)
+- No sendspin-cli package definition
+- No sendspin role or systemd service configuration
+
+## Desired End State
+
+After implementation completion:
+1. **Package available**: `pkgs.custom.sendspin-cli` builds successfully with all dependencies
+2. **Role available**: `roles.sendspin.enable = true` provides sendspin with configurable service
+3. **Service template**: Systemd user service runs as graphical session user with configurable audio device
+4. **Audio device compatibility**: Uses sendspin's native device specification (index or name prefix)
+5. **Flexible user context**: Service can run as kodi, johno, or any graphical session user
+
+### Verification Commands:
+```bash
+# Package builds successfully
+nix build .#nixosConfigurations.zix790prors.config.environment.systemPackages --no-link | grep sendspin-cli
+
+# Package contains working executable
+$(nix-build -E '(import <nixpkgs> {}).callPackage ./packages/sendspin-cli {}')/bin/sendspin --help
+
+# Service template is generated
+nixos-rebuild dry-build --flake .#zix790prors 2>&1 | grep sendspin
+```
+
+## Key Discoveries
+
+### uv2nix Integration Points
+- **No lock file**: sendspin-cli has `pyproject.toml` but no `uv.lock` - uv2nix will resolve from pyproject.toml
+- **Native dependencies**: sounddevice and av require portaudio and ffmpeg in buildInputs
+- **Workspace loading**: uv2nix.lib.workspace.loadWorkspace works with pyproject.toml-only projects
+- **Build system**: Uses setuptools (declared in pyproject.toml:1-3)
+
+### Service Architecture
+- **User services**: Must use `systemd.user.services` (not system services) for audio access
+- **Automatic user detection**: User services run in the logged-in graphical user's session
+- **PipeWire dependency**: Service must start after `pipewire.service` and `wireplumber.service`
+- **Auto-restart**: Use `Restart=always` for persistent background operation
+
+### Audio Device Handling
+- **Native format**: Sendspin expects device index (0, 1, 2) or name prefix ("AmazonBasics")
+- **Discovery**: `sendspin --list-audio-devices` shows available devices
+- **PipeWire independence**: No need to use PipeWire node names; sendspin queries via sounddevice library
+
+## What We're NOT Doing
+
+To prevent scope creep:
+
+1. **Not creating uv.lock**: Using pyproject.toml directly; lock file can be added upstream later
+2. **Not implementing multi-instance configuration**: Providing single-instance template; machines can extend for multiple instances
+3. **Not configuring specific machines**: Template only; zix790prors multi-instance setup is future work
+4. **Not creating home-manager module**: Using system-level role with user services
+5. **Not implementing server mode**: Client-only integration; `sendspin serve` can be added later
+6. **Not auto-detecting graphical user**: Relying on systemd user service behavior; explicit user selection can be added later
+7. **Not packaging dev dependencies**: Only runtime dependencies; test tools (mypy, ruff) excluded
+
+## Implementation Approach
+
+Use uv2nix to package sendspin-cli from its GitHub repository, accessing pyproject.toml for dependency resolution. Create a NixOS role following the spotifyd pattern with a systemd user service template. The service runs in the logged-in user's session (automatic user detection) and can be configured per-machine for different audio devices.
+
+**Key Technical Decisions:**
+1. **uv2nix over python3.withPackages**: Better maintainability, automatic dependency resolution, aligns with upstream development
+2. **System-level role with user services**: Follows existing patterns (virtual-surround.nix), enables per-user configuration
+3. **Headless mode default**: Services always use `--headless`; TUI available via manual `sendspin` command
+4. **mDNS discovery default**: No `--url` by default; let sendspin auto-discover servers on the network
+
+---
+
+## Phase 1: Add uv2nix Flake Inputs
+
+### Overview
+Add pyproject-nix, uv2nix, and pyproject-build-systems as flake inputs and thread them through to package definitions.
+
+### Changes Required
+
+#### 1. Flake Inputs
+**File**: `flake.nix`
+**Changes**: Add new inputs after existing inputs (after line 44)
+
+```nix
+pyproject-nix = {
+  url = "github:pyproject-nix/pyproject.nix";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+
+uv2nix = {
+  url = "github:pyproject-nix/uv2nix";
+  inputs.pyproject-nix.follows = "pyproject-nix";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+
+pyproject-build-systems = {
+  url = "github:pyproject-nix/build-system-pkgs";
+  inputs.pyproject-nix.follows = "pyproject-nix";
+  inputs.uv2nix.follows = "uv2nix";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+```
+
+#### 2. Outputs Signature
+**File**: `flake.nix`
+**Changes**: Update outputs function signature (line 47)
+
+```nix
+# Before
+outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, ... } @ inputs:
+
+# After
+outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, pyproject-nix, uv2nix, pyproject-build-systems, ... } @ inputs:
+```
+
+#### 3. Pass Inputs to Packages
+**File**: `flake.nix`
+**Changes**: Update custom package overlay (line 59 and 87)
+
+```nix
+# Before
+custom = prev.callPackage ./packages {};
+
+# After
+custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
+```
+
+#### 4. Update Packages Default.nix Signature
+**File**: `packages/default.nix`
+**Changes**: Accept new parameters
+
+```nix
+# Before
+{ pkgs, ... }:
+
+# After
+{ pkgs, uv2nix ? null, pyproject-nix ? null, pyproject-build-systems ? null, ... }:
+```
+
+**Note**: Parameters are optional to maintain compatibility with direct `nix-build` calls.
+
+### Success Criteria
+
+#### Automated Verification:
+- [x] Flake evaluation succeeds: `nix flake check`
+- [x] Custom packages still build: `nix build .#nixosConfigurations.zix790prors.config.environment.systemPackages`
+- [x] No evaluation errors: `nixos-rebuild dry-build --flake .#zix790prors`
+
+#### Manual Verification:
+- [x] Flake inputs show pyproject-nix, uv2nix, and pyproject-build-systems: `nix flake metadata`
+- [x] Existing machines still build without errors
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation before proceeding to Phase 2.
+
+---
+
+## Phase 2: Create Sendspin-CLI Package
+
+### Overview
+Create uv2nix-based package for sendspin-cli that handles Python dependencies and native libraries (portaudio, ffmpeg).
+
+### Changes Required
+
+#### 1. Package Definition
+**File**: `packages/sendspin-cli/default.nix`
+**Changes**: Create new file
+
+```nix
+{ pkgs
+, uv2nix ? null
+, pyproject-nix ? null
+, pyproject-build-systems ? null
+, lib
+, fetchFromGitHub
+}:
+
+# Fallback to simple package if uv2nix not available
+if uv2nix == null || pyproject-nix == null || pyproject-build-systems == null then
+  let
+    python = pkgs.python312.withPackages (ps: with ps; [
+      # Core dependencies from pyproject.toml
+      # Note: aiosendspin may need to be packaged separately if not in nixpkgs
+      av
+      numpy
+      qrcode
+      readchar
+      rich
+      sounddevice
+      # Build dependencies
+      setuptools
+    ]);
+  in
+  pkgs.stdenv.mkDerivation rec {
+    pname = "sendspin-cli";
+    version = "0.0.0-fallback";
+
+    src = fetchFromGitHub {
+      owner = "Sendspin";
+      repo = "sendspin-cli";
+      rev = "main";
+      sha256 = lib.fakeSha256;  # Replace with actual hash after first build
+    };
+
+    buildInputs = [ python pkgs.portaudio pkgs.ffmpeg ];
+
+    installPhase = ''
+      mkdir -p $out/bin $out/lib
+      cp -r sendspin $out/lib/
+      cat > $out/bin/sendspin <<EOF
+#!/bin/sh
+export PYTHONPATH="$out/lib:\$PYTHONPATH"
+exec ${python}/bin/python3 -m sendspin.cli "\$@"
+EOF
+      chmod +x $out/bin/sendspin
+    '';
+
+    meta = {
+      description = "Synchronized audio player for Sendspin servers (fallback build)";
+      homepage = "https://github.com/Sendspin/sendspin-cli";
+      license = lib.licenses.asl20;
+    };
+  }
+else
+  let
+    # Fetch sendspin-cli source
+    src = fetchFromGitHub {
+      owner = "Sendspin";
+      repo = "sendspin-cli";
+      rev = "main";  # TODO: Pin to specific release tag
+      sha256 = lib.fakeSha256;  # Replace with actual hash after first build
+    };
+
+    # Load workspace from pyproject.toml
+    workspace = uv2nix.lib.workspace.loadWorkspace {
+      workspaceRoot = src;
+    };
+
+    # Create overlay from pyproject.toml dependencies
+    overlay = workspace.mkPyprojectOverlay {
+      sourcePreference = "wheel";  # Prefer wheels for faster builds
+    };
+
+    # Build Python package set with native dependency overrides
+    pythonSet = (pkgs.callPackage pyproject-nix.build.packages {
+      python = pkgs.python312;
+    }).overrideScope (lib.composeManyExtensions [
+      pyproject-build-systems.overlays.default
+      overlay
+      # Override for packages with native dependencies
+      (final: prev: {
+        # sounddevice needs portaudio
+        sounddevice = prev.sounddevice.overrideAttrs (old: {
+          buildInputs = (old.buildInputs or []) ++ [ pkgs.portaudio ];
+          nativeBuildInputs = (old.nativeBuildInputs or []) ++ [ pkgs.portaudio ];
+        });
+        # av (PyAV) needs ffmpeg
+        av = prev.av.overrideAttrs (old: {
+          buildInputs = (old.buildInputs or []) ++ [ pkgs.ffmpeg ];
+          nativeBuildInputs = (old.nativeBuildInputs or []) ++ [ pkgs.pkg-config ];
+        });
+      })
+    ]);
+
+    # Create virtual environment with all dependencies
+    venv = pythonSet.mkVirtualEnv "sendspin-cli-env" workspace.deps.default;
+  in
+  pkgs.stdenv.mkDerivation {
+    pname = "sendspin-cli";
+    version = "0.0.0";
+    inherit src;
+
+    buildInputs = [ venv pkgs.portaudio pkgs.ffmpeg ];
+
+    installPhase = ''
+      mkdir -p $out/bin
+      # Copy virtual environment
+      cp -r ${venv} $out/venv
+      # Create wrapper script
+      cat > $out/bin/sendspin <<EOF
+#!/bin/sh
+export LD_LIBRARY_PATH="${pkgs.portaudio}/lib:${pkgs.ffmpeg}/lib:\$LD_LIBRARY_PATH"
+exec $out/venv/bin/sendspin "\$@"
+EOF
+      chmod +x $out/bin/sendspin
+    '';
+
+    meta = {
+      description = "Synchronized audio player for Sendspin servers";
+      homepage = "https://github.com/Sendspin/sendspin-cli";
+      license = lib.licenses.asl20;
+      platforms = lib.platforms.linux;
+    };
+  }
+```
+
+#### 2. Register Package
+**File**: `packages/default.nix`
+**Changes**: Add sendspin-cli to exports (after line 6)
+
+```nix
+{ pkgs, uv2nix ? null, pyproject-nix ? null, pyproject-build-systems ? null, ... }:
+{
+  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 {};
+  sendspin-cli = pkgs.callPackage ./sendspin-cli { inherit uv2nix pyproject-nix pyproject-build-systems; };
+}
+```
+
+### Success Criteria
+
+#### Automated Verification:
+- [x] Package builds successfully: `nix build .#nixosConfigurations.zix790prors.pkgs.custom.sendspin-cli`
+- [x] Binary exists in output: `nix path-info .#nixosConfigurations.zix790prors.pkgs.custom.sendspin-cli`
+- [x] No build errors in dry-run: `nixos-rebuild dry-build --flake .#zix790prors`
+
+#### Manual Verification:
+- [ ] Help text displays correctly: `$(nix-build '<nixpkgs>' -A custom.sendspin-cli)/bin/sendspin --help`
+- [ ] List audio devices works: `$(nix-build '<nixpkgs>' -A custom.sendspin-cli)/bin/sendspin --list-audio-devices`
+- [ ] Version information is correct: `$(nix-build '<nixpkgs>' -A custom.sendspin-cli)/bin/sendspin --version` (if supported)
+- [ ] Dependencies are bundled: Check that output closure contains portaudio and ffmpeg libraries
+
+**Implementation Note**: The first build will fail with `lib.fakeSha256` error. Copy the actual hash from the error message and replace `lib.fakeSha256` with the real hash. After completing this phase and all automated verification passes, pause here for manual confirmation before proceeding to Phase 3.
+
+---
+
+## Phase 3: Create Sendspin Role with Service Template
+
+### Overview
+Create NixOS role that provides sendspin-cli package and configurable systemd user service template for running sendspin as a background service.
+
+### Changes Required
+
+#### 1. Role Definition
+**File**: `roles/sendspin/default.nix`
+**Changes**: Create new file
+
+```nix
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+let
+  cfg = config.roles.sendspin;
+in
+{
+  options.roles.sendspin = {
+    enable = mkEnableOption "Enable the sendspin role";
+
+    audioDevice = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Audio output device by index (e.g., "0", "1") or name prefix (e.g., "AmazonBasics").
+        Use `sendspin --list-audio-devices` to see available devices.
+        If null, uses system default audio device.
+      '';
+      example = "0";
+    };
+
+    clientName = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Friendly name for this Sendspin client.
+        Defaults to hostname if not specified.
+      '';
+      example = "Living Room Speakers";
+    };
+
+    clientId = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Unique identifier for this Sendspin client.
+        Defaults to sendspin-cli-<hostname> if not specified.
+      '';
+      example = "sendspin-livingroom";
+    };
+
+    serverUrl = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        WebSocket URL of the Sendspin server.
+        If null, auto-discovers servers via mDNS.
+      '';
+      example = "ws://192.168.1.100:8927";
+    };
+
+    staticDelayMs = mkOption {
+      type = types.float;
+      default = 0.0;
+      description = ''
+        Extra playback delay in milliseconds applied after clock sync.
+        Useful for compensating audio latency differences between devices.
+      '';
+      example = 50.0;
+    };
+
+    logLevel = mkOption {
+      type = types.enum [ "DEBUG" "INFO" "WARNING" "ERROR" "CRITICAL" ];
+      default = "INFO";
+      description = "Logging level for sendspin service";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # Ensure audio infrastructure is available
+    roles.audio.enable = true;
+
+    # Make sendspin-cli available system-wide
+    environment.systemPackages = with pkgs; [
+      custom.sendspin-cli
+    ];
+
+    # Systemd user service for running sendspin in headless mode
+    systemd.user.services.sendspin = {
+      description = "Sendspin Audio Sync Client";
+      documentation = [ "https://github.com/Sendspin/sendspin-cli" ];
+
+      # Start after audio services are ready
+      after = [ "pipewire.service" "wireplumber.service" ];
+      requires = [ "pipewire.service" "wireplumber.service" ];
+
+      # Auto-start with pipewire (which starts with graphical session)
+      wantedBy = [ "pipewire.service" ];
+
+      serviceConfig = {
+        Type = "simple";
+        Restart = "always";
+        RestartSec = "5s";
+
+        # Build command with configured options
+        ExecStart = pkgs.writeShellScript "sendspin-start" ''
+          exec ${pkgs.custom.sendspin-cli}/bin/sendspin \
+            --headless \
+            --log-level ${cfg.logLevel} \
+            ${optionalString (cfg.audioDevice != null) "--audio-device '${cfg.audioDevice}'"} \
+            ${optionalString (cfg.clientName != null) "--name '${cfg.clientName}'"} \
+            ${optionalString (cfg.clientId != null) "--id '${cfg.clientId}'"} \
+            ${optionalString (cfg.serverUrl != null) "--url '${cfg.serverUrl}'"} \
+            ${optionalString (cfg.staticDelayMs != 0.0) "--static-delay-ms ${toString cfg.staticDelayMs}"}
+        '';
+      };
+    };
+
+    # Open firewall for mDNS discovery
+    networking.firewall.allowedUDPPorts = [ 5353 ];
+  };
+}
+```
+
+#### 2. Register Role
+**File**: `roles/default.nix`
+**Changes**: Add sendspin to imports (after line 16)
+
+```nix
+imports = [
+  ./audio
+  ./bluetooth
+  ./btrfs
+  ./desktop
+  ./kodi
+  ./nfs-mounts
+  ./nvidia
+  ./printing
+  ./remote-build
+  ./sendspin
+  ./spotifyd
+  ./users
+  ./virtualisation
+];
+```
+
+### Success Criteria
+
+#### Automated Verification:
+- [ ] Configuration evaluates: `nixos-rebuild dry-build --flake .#zix790prors`
+- [ ] Service unit is generated: `nixos-rebuild dry-build --flake .#zix790prors 2>&1 | grep -i sendspin`
+- [ ] No syntax errors: `nix eval .#nixosConfigurations.zix790prors.config.roles.sendspin.enable`
+
+#### Manual Verification:
+- [ ] Role can be enabled in machine config without errors
+- [ ] Service dependencies are correct (after pipewire/wireplumber)
+- [ ] Firewall rule for mDNS is present
+- [ ] Sendspin-cli is in system packages when role is enabled
+- [ ] All configuration options (audioDevice, clientName, etc.) are exposed
+- [ ] Service starts successfully after enabling role and rebuilding
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation. Test the service by adding `roles.sendspin.enable = true;` to a machine configuration, rebuilding, and verifying the service runs as the logged-in user.
+
+---
+
+## Testing Strategy
+
+### Unit Tests (Per-Phase)
+
+**Phase 1 (Flake Inputs):**
+```bash
+# Verify flake is valid
+nix flake check
+
+# Verify inputs are available
+nix flake metadata | grep -E "(pyproject-nix|uv2nix|pyproject-build-systems)"
+
+# Verify existing builds still work
+nix build .#nixosConfigurations.zix790prors.config.system.build.toplevel
+```
+
+**Phase 2 (Package):**
+```bash
+# Build package
+nix build .#nixosConfigurations.zix790prors.pkgs.custom.sendspin-cli
+
+# Test executable
+result/bin/sendspin --help
+result/bin/sendspin --list-audio-devices
+
+# Verify dependencies
+nix-store --query --requisites result | grep -E "(portaudio|ffmpeg)"
+```
+
+**Phase 3 (Role):**
+```bash
+# Evaluate with role enabled
+nix eval .#nixosConfigurations.zix790prors.config.roles.sendspin.enable
+
+# Check service definition
+nixos-rebuild dry-build --flake .#zix790prors
+systemctl --user cat sendspin.service  # After rebuild
+
+# Verify audio device option works
+nix eval '.#nixosConfigurations.zix790prors.config.roles.sendspin.audioDevice'
+```
+
+### Integration Tests
+
+**Basic Service Test:**
+1. Enable role on a test machine: `roles.sendspin.enable = true;`
+2. Rebuild system: `make switch`
+3. Check service status: `systemctl --user status sendspin.service`
+4. Verify logs show connection attempts: `journalctl --user -u sendspin -f`
+5. Run server locally: `sendspin serve --demo`
+6. Verify client connects and plays audio
+
+**Multi-Device Test (Future - zix790prors):**
+1. Create multiple service instances with different audio devices
+2. Verify each instance targets correct device
+3. Test audio sync between devices
+
+**User Context Test:**
+1. Test on `boxy` running as `kodi` user
+2. Test on `zix790prors` running as `johno` user
+3. Verify service runs in correct user session
+
+### Manual Testing Steps
+
+1. **Package Installation:**
+   ```bash
+   # As root
+   nix-shell -p 'pkgs.custom.sendspin-cli'
+   sendspin --list-audio-devices
+   ```
+
+2. **Service Functionality:**
+   ```bash
+   # After enabling role and rebuilding
+   systemctl --user status sendspin
+   journalctl --user -u sendspin -n 50
+   ```
+
+3. **Audio Device Selection:**
+   ```bash
+   # Configure specific device
+   roles.sendspin.audioDevice = "0";
+   # Rebuild and verify service uses correct device
+   ```
+
+4. **Server Discovery:**
+   ```bash
+   # Without serverUrl, verify mDNS discovery
+   sendspin --list-servers
+   ```
+
+5. **Delay Calibration:**
+   ```bash
+   # Test delay configuration
+   roles.sendspin.staticDelayMs = 50.0;
+   # Verify in service logs
+   ```
+
+## Performance Considerations
+
+**Build Time:**
+- uv2nix initial build may take 5-10 minutes (Python dependency resolution)
+- Subsequent builds use Nix cache
+- Consider using binary cache if building on multiple machines
+
+**Runtime:**
+- Sendspin client is lightweight (~20-50 MB memory)
+- CPU usage minimal when not playing audio
+- Network: Uses mDNS (UDP 5353) and WebSocket connection to server
+
+**Storage:**
+- Package closure size: ~200-300 MB (Python + dependencies + libraries)
+- No persistent cache by sendspin-cli itself
+
+## Migration Notes
+
+**For Existing Systems:**
+1. Add role to machine configuration
+2. Configure audio device if not using default
+3. Rebuild and enable service
+4. No data migration needed (stateless service)
+
+**For Multi-Instance Setups (Future):**
+When implementing multiple instances for zix790prors:
+1. Disable default service: `systemd.user.services.sendspin.wantedBy = lib.mkForce [];`
+2. Create per-device service instances manually
+3. Each instance needs unique `--id` and `--audio-device`
+
+## References
+
+- Original research: `thoughts/shared/research/2025-12-29-sendspin-cli-integration.md`
+- Sendspin-CLI source: `~/src/sendspin-cli/` (GitHub: https://github.com/Sendspin/sendspin-cli)
+- Sendspin pyproject.toml: `~/src/sendspin-cli/pyproject.toml`
+- Sendspin CLI implementation: `~/src/sendspin-cli/sendspin/cli.py:143-222`
+- Custom packages pattern: `packages/default.nix:1-7`
+- Python package pattern: `packages/app-launcher-server/default.nix:1-10`
+- Audio role pattern: `roles/audio/default.nix:1-41`
+- Service role pattern: `roles/spotifyd/default.nix:1-40`
+- User service pattern: `machines/zix790prors/virtual-surround.nix:79-132`
+- Flake overlay: `flake.nix:54-59`
+- uv2nix documentation: https://pyproject-nix.github.io/uv2nix/
+- uv2nix getting started: https://pyproject-nix.github.io/uv2nix/usage/getting-started.html