# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

NixOS dotfiles using Flakes + Home Manager for a single user (`jashton`) across multiple hosts (`thinkpad`, `desktop`, `framework`). Pinned to `nixos-26.05`.

## Common Commands

```bash
# Rebuild and switch the current system (thinkpad)
sudo nixos-rebuild switch --flake ~/.dotfiles#thinkpad

# Check the flake for errors without applying
nix flake check

# Update flake inputs (e.g. nixpkgs, home-manager)
nix flake update

# Open the flake entrypoint in nvim
enix   # alias: nvim ~/.dotfiles/flake.nix

# Open the home-manager user config in nvim
ehome  # alias: nvim ~/.dotfiles/home/jashton.nix

# List registered ports
ports  # alias: cat ~/.dotfiles/ports.registry
```

## Architecture

The repo is structured as a standard Nix Flakes configuration. `flake.nix` defines `nixosConfigurations` for each host and wires in Home Manager as a NixOS module. Each host's Home Manager is pointed at a single shared user config (`home/jashton.nix`).

```
flake.nix                    # Entrypoint; defines per-host nixosConfigurations
hosts/<host>/default.nix     # Host-specific config (imports hardware.nix + system/)
hosts/<host>/hardware.nix    # nixos-generate-config output (don't manually edit)
system/                      # Shared NixOS system config (all hosts)
  default.nix                # Aggregates: packages, core, network, security, services, virtualisation
  packages.nix               # System-level packages + allowUnfree
  core/                      # Zsh, fonts, nix settings, locale, boot, audio, power
  security/                  # Users, sudo, polkit, TPM2, systemd hardening
  services/                  # Display manager (GDM), Xserver, i3 WM, picom, printing, Bluetooth
  network/                   # Pi-hole config
  virtualisation/            # VM/container support
home/jashton.nix             # Home Manager user config; shared across all hosts
  home/programs/             # Per-program HM config: alacritty, git, nvim
  home/desktop/              # Desktop environment: i3, polybar, rofi, dunst, gnome dconf
```

## Key Design Decisions

- **Dual desktop environment**: Both GNOME (GDM display manager) and i3 (window manager via Xserver) are configured and co-exist. GNOME extensions are declared via `dconf.settings` in `home/desktop/gnome.nix`.
- **Shell scripts as Nix packages**: Custom scripts (`find-open-port`, `lock-screen`, `power-menu`, `weather-cache`) are defined inline in `home/jashton.nix` using `pkgs.writeShellScriptBin` so they are on `$PATH` without a separate scripts directory.
- **Port registry**: `ports.registry` is a plain-text file tracking assigned dev ports 8000–8999. The `find-open-port` script appends to it; don't assign ports manually without checking it first.
- **Zsh configured at system level**: `programs.zsh` (aliases, Oh My Zsh, history) lives in `system/core/env.nix`. The `~/.zshrc` written by Home Manager is intentionally a stub to suppress the zsh-newuser-install prompt.
- **Host hardware files**: `hosts/thinkpad/hardware.nix` is auto-generated by `nixos-generate-config`. Edits here (e.g. Howdy IR camera path `/dev/video66`) are intentional overrides — don't regenerate and overwrite.
- **`stateVersion`**: Both `system.stateVersion` and `home.stateVersion` are set to `"26.05"`. Do not change these.