AI recommended improvements

.gitignore

@@ -3,3 +3,4 @@ gitconfig_local
 *.zwc
 *.swp
 *.pyc
+version_cache.json5

CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a dotfiles management system for Linux environments using Nix and Home Manager for declarative configuration. It supports multiple host types: desktops, servers, and WSL instances.
+
+## Common Commands
+
+### Fresh Install (Primary Method)
+```bash
+./apply.sh --nix-host <host-name>
+# Example: ./apply.sh --nix-host personal-desktop
+```
+Available hosts are defined in `nix/hosts.json`: personal-desktop, work-desktop, personal-wsl, work-wsl, personal-server, work-server.
+
+### Apply Nix Configuration Changes
+```bash
+home-manager switch --flake ~/dot/nix#<host-name>
+```
+
+### Python CLI Tool
+```bash
+dot provision [TAGS]    # Run provisioners
+dot link                # Create symlinks (legacy)
+dot clean               # Remove symlinks
+dot tidy                # Format Python code (black, isort, autoflake)
+```
+
+### Type Checking and Linting
+```bash
+make mypy               # Run mypy on all Python files
+```
+
+### Theming
+```bash
+set-theme <scheme-name>  # Apply base16 color scheme (e.g., outrun-dark)
+flavours update all      # Required first time setup
+```
+
+## Architecture
+
+### Nix Configuration (`nix/`)
+- `flake.nix` - Entry point; generates Home Manager configurations from `hosts.json`
+- `hosts.json` - Defines hosts and their roles (core, desktop, gaming, wsl)
+- `home/roles/` - Host-type configurations (Ansible-style naming):
+  - `core.nix` - Base packages (neovim, git, fzf, tmux, Python tools)
+  - `desktop.nix` - GUI packages (i3, kitty, rofi, mpd, media tools)
+  - `gaming.nix` - Gaming packages
+  - `wsl.nix` - WSL-specific configuration
+- `home/lib/` - Shared modules imported by roles:
+  - `dotfiles-links.nix` - Maps config files from `config/` to home directory
+  - `python-environment.nix` - Builds unified Python environment
+- `home/features/` - Specific feature modules (e.g., docker) that can be shared across roles
+
+### Configuration Files (`config/`)
+Application configs that get linked to home directory via Home Manager:
+- `bash/` - Shell configuration
+- `nvim/` - Neovim configuration
+- `i3`, `sway` - Window manager configs
+- `kitty.conf`, `alacritty/`, `wezterm.lua` - Terminal emulators
+- `flavours/` - Base16 theming (schemes in `schemes/custom/`, templates in `templates/custom/`)
+
+### Python CLI (`cli/`)
+- `dot.py` - Main entry point with argparse
+- `commands/` - Command implementations (provision, link, tidy, lint, etc.)
+- `lib/provision/` - Provisioners for apt, pip, nodejs, docker, neovim, etc.
+- `lib/common/` - Shared utilities (shell, git, logging, file operations)
+
+### Utility Scripts (`bin/`)
+Standalone scripts: `set-theme`, `i3-util.sh`, `startup.sh`, `fuzzy-fm`, etc.
+
+## Key Files
+
+- `apply.sh` - Bootstrap script for fresh installs (installs Nix, applies Home Manager)
+- `links.json` - Legacy dotfile symlink mappings (now mostly handled by `dotfiles-links.nix`)
+- `nix/hosts.json` - Host definitions with roles; drives the entire Nix configuration
+
+## Code Style
+
+Python code uses black, isort, and autoflake. Run `dot tidy` before committing Python changes. Type hints are encouraged; validate with `make mypy`.

GEMINI.md

@@ -0,0 +1,82 @@
+# GEMINI.md
+
+This file provides guidance to Gemini when working with code in this repository.
+
+## Project Overview
+
+This is a dotfiles management system for Linux environments using Nix and Home Manager for declarative configuration. It supports multiple host types: desktops, servers, and WSL instances.
+
+## Common Commands
+
+### Fresh Install (Primary Method)
+```bash
+./apply.sh --nix-host <host-name>
+# Example: ./apply.sh --nix-host personal-desktop
+```
+Available hosts are defined in `nix/hosts.json`: personal-desktop, work-desktop, personal-wsl, work-wsl, personal-server, work-server.
+
+### Apply Nix Configuration Changes
+```bash
+home-manager switch --flake ~/dot/nix#<host-name>
+```
+
+### Python CLI Tool
+```bash
+dot provision [TAGS]    # Run provisioners
+dot link                # Create symlinks (legacy)
+dot clean               # Remove symlinks
+dot tidy                # Format Python code (black, isort, autoflake)
+```
+
+### Type Checking and Linting
+```bash
+make mypy               # Run mypy on all Python files
+```
+
+### Theming
+```bash
+set-theme <scheme-name>  # Apply base16 color scheme (e.g., outrun-dark)
+flavours update all      # Required first time setup
+```
+
+## Architecture
+
+### Nix Configuration (`nix/`)
+- `flake.nix` - Entry point; generates Home Manager configurations from `hosts.json`
+- `hosts.json` - Defines hosts and their roles (core, desktop, gaming, wsl)
+- `home/roles/` - Host-type configurations (Ansible-style naming):
+  - `core.nix` - Base packages (neovim, git, fzf, tmux, Python tools)
+  - `desktop.nix` - GUI packages (i3, kitty, rofi, mpd, media tools)
+  - `gaming.nix` - Gaming packages
+  - `wsl.nix` - WSL-specific configuration
+- `home/lib/` - Shared modules imported by roles:
+  - `dotfiles-links.nix` - Maps config files from `config/` to home directory
+  - `python-environment.nix` - Builds unified Python environment
+- `home/features/` - Specific feature modules (e.g., docker) that can be shared across roles
+
+### Configuration Files (`config/`)
+Application configs that get linked to home directory via Home Manager:
+- `bash/` - Shell configuration
+- `nvim/` - Neovim configuration
+- `i3`, `sway` - Window manager configs
+- `kitty.conf`, `alacritty/`, `wezterm.lua` - Terminal emulators
+- `flavours/` - Base16 theming (schemes in `schemes/custom/`, templates in `templates/custom/`)
+
+### Python CLI (`cli/`)
+- `dot.py` - Main entry point with argparse
+- `commands/` - Command implementations (provision, link, tidy, lint, etc.)
+- `lib/provision/` - Provisioners for apt, pip, nodejs, docker, neovim, etc.
+- `lib/common/` - Shared utilities (shell, git, logging, file operations)
+
+### Utility Scripts (`bin/`)
+Standalone scripts: `set-theme`, `i3-util.sh`, `startup.sh`, `fuzzy-fm`, etc.
+
+## Key Files
+
+- `apply.sh` - Bootstrap script for fresh installs (installs Nix, applies Home Manager)
+- `links.json` - Legacy dotfile symlink mappings (now mostly handled by `dotfiles-links.nix`)
+- `nix/hosts.json` - Host definitions with roles; drives the entire Nix configuration
+
+## Code Style
+
+Python code uses black, isort, and autoflake. Run `dot tidy` before committing Python changes. Type hints are encouraged; validate with `make mypy`.

Makefile

@@ -19,3 +19,10 @@ windows:
 mypy:
 	find . -iname '*.py' | xargs mypy --config-file ./mypy.ini
 	mypy --config-file ./mypy.ini ./bin/fzf_cached_wsl
+
+# Run nixfmt on all Nix files
+.PHONY: nixfmt
+nixfmt:
+	# Run this in a nix-shell so we can get the most up-to-date version of
+	# nixfmt since the --indent option was added fairly recently.
+	nix-shell -p nixfmt --run "find . -iname '*.nix' | xargs nixfmt --indent=4"

README.md

@@ -1,154 +1,18 @@
 # Dotfiles
 
-This repository contains my dotfiles!
+This repository contains my dotfiles and uses Nix and Home Manager for
+declarative configuration across my machines.
 
-## Manual Setup
+## Getting Started
 
-A few things I haven't bothered to automate.
+- **Ubuntu Setup Instructions:**
+    - [setup_ubuntu.md](./doc/setup_ubuntu.md)
+- **Windows Setup Instructions:**
+    - [setup_windows.md](./doc/setup_windows.md)
 
-### Git
+## Theme
 
-Create `~/.gitconfig_local` like:
+For details on how theming is set up and how to modify a theme or change the
+current theme, see:
 
-```
-[user]
-	email = paul@foo.com
-	name = Paul Ewing
-```
-
-### Wallpaper Rotater
-
-If using `wpr`, create `~/.config/wpr/config.json` like:
-
-```json
-{
-    "WallpaperDir": "/home/username/Pictures/Wallpapers",
-    "DisplayCount": 1,
-    "Interval":120
-}
-```
-
-### Dual Boot Clock Fix
-
-If dual booting with Windows, set hardware clock to local time:
-
-```bash
-timedatectl set-local-rtc 1
-```
-
-Without this, clock time in Windows will be off.
-
-### Applications to Manually Install
-
-The following aren't in apt and need to be installed manually:
-
-- Chrome
-- Beyond Compare
-- Insync
-- Discord
-- RuneLite
-
-Alacritty is not yet in the default Ubuntu apt repositories:
-
-```bash
-sudo add-apt-repository ppa:mmstick76/alacritty
-sudo apt update
-```
-
-## Theming
-
-To make it easier to re-theme everything at once, I use
-[base16](https://github.com/chriskempson/base16) and
-[flavours](https://github.com/Misterio77/flavours). See:
-
-The tl;dr of `base16` is that it is a system for designing color schemes.
-`base16` schemes consists of a palette of 16 colors - 8 shades and 8 accents.
-Templates can then be created to render the base16 scheme into various config
-formats for different applications.
-
-Due to some [turbulence](https://github.com/tinted-theming/home/issues/51) in
-the `base16` project, I've added my most used schemes directly to my dotfiles
-to avoid things breaking if repositories are ever moved or taken down. I've
-also created my own templates rather than using the defaults.
-
-- [schemes](./config/flavours/schemes/custom)
-- [templates](./config/flavours/templates/custom/templates)
-
-Using the `flavours` application, these templates are rendered directly into my
-dotfiles based on the `flavours` config:
-
-- [flavours/config.toml](./config/flavours/config.toml)
-
-To apply a new color scheme, download and install
-[flavours](https://github.com/Misterio77/flavours/releases/latest).
-
-The first time running, update sources. Even if using schemes/templates
-committed to my dotfiles, this still appears to be necessary:
-
-```bash
-flavours update all
-```
-
-**Note:** We should add flavours installation to the provision script.
-
-Once flavours is installed, set the theme using the
-[set-theme](./bin/set-theme) script. This not only executes `flavours` but also
-reloads config across various applications to smoothly transition themes.
-
-```bash
-set-theme <theme-name>
-```
-
-The name should match the corresponding base16 scheme yaml file without the
-extension. For example:
-
-```bash
-flavours apply outrun-dark
-```
-
-The official lists of templates and schemes supported by flavours live here:
-
-- https://github.com/chriskempson/base16-schemes-source/blob/main/list.yaml
-- https://github.com/chriskempson/base16-templates-source/blob/master/list.yaml
-
-Manual steps after changing themes:
-
-- Reload tmux config
-    - `:source-file ~/.tmux.conf`
-    - We should figure out how to automate this
-
-### TODO
-
-Some remaining items to tackle in regards to theming:
-- Add templates for
-    - sway
-
-## Windows 10
-
-For setup steps on Windows 10, see:
-
-[windows_setup.md](./windows_setup.md)
-
-### WSL
-
-Some useful things to add to `.localrc` in WSL.
-
-Remove the background highlighting of folders in ls:
-
-```bash
-LS_COLORS=$LS_COLORS:'ow=1;34:' ; export LS_COLORS
-```
-
-WezTerm shell integration; this adds some useful features like having new tabs
-open in the same directory as the previous:
-```
-if [ "$TERM_PROGRAM" = "WezTerm" ] && [ -f "$HOME/wezterm.sh" ]; then
-    source "$HOME/wezterm.sh"
-fi
-```
-
-For now just manually create and copy the `wezterm.sh` file from here:
-
-https://raw.githubusercontent.com/wez/wezterm/main/assets/shell-integration/wezterm.sh
-
-We could make this a bit nicer by automatically downloading it.
+[theme.md](./doc/theme.md)