bankrupt/CLAUDE.md

# CLAUDE.md

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

## What This Is

A batteries-loaded macOS rice — cross-platform Nix configuration (nix-darwin + NixOS + home-manager) for user `df`. The active system is `m2n1` — an Apple Silicon Mac running nix-darwin.

## Philosophy

This repo strives for the **best possible macOS setup** with seamless UX:

- **Better defaults everywhere** — keyboard, trackpad, Dock, Finder, screenshots, window management, etc. If macOS has a bad default, override it.
- **Batteries included** — tools, shell plugins, keybindings, and integrations should work out of the box. No manual post-install steps.
- **Rice it** — the setup should look and feel polished. Consistent theming, clean status bars, good typography.
- **Research before implementing** — when adding or changing something, check the internet for the best current practices, latest options, and what power users recommend. Don't guess.
- **Test it works** — after making changes, run `darwin-rebuild switch` and verify the setting actually took effect (e.g. `defaults read` for macOS prefs, `which <pkg>` for packages, checking service status for daemons). Never assume a fix works — always confirm.
- **Teach debugging** — always explain *how* you verified something works and *how* the user can check it themselves. Show the proof: the command to run, what the output should look like, and what it means. The user should learn to debug and verify on their own, not just trust the output.
- **Stay current** — nix-darwin, home-manager, and macOS evolve. When touching a module, check if there are newer/better options available.
- **Nix-only** — never use `brew install`, `nix-env -i`, or any imperative package management. Everything goes through the flake: system packages in `darwin/configuration.nix`, user packages in `home-manager/modules/`. If it's not declared in Nix, it doesn't exist.

## Build Commands

```bash
# Primary build+switch for macOS (requires sudo)
sudo darwin-rebuild build --flake ~/bankrupt/#m2n1
sudo darwin-rebuild switch --flake ~/bankrupt/#m2n1

# Or via Makefile (auto-detects hostname)
make darwin-switch

# Update flake inputs
make update

# Format nix files
nix fmt

# Validate flake
nix flake check
```

## Architecture

```
flake.nix                    # Entry point: inputs, overlays, system configs
├── common.nix               # Shared nix settings (caches, overlays, GC)
├── darwin/configuration.nix  # m2n1 system config (imports yabai.nix, skhd.nix)
├── nixos/configuration.nix   # Template NixOS config
├── overlays/default.nix      # Package overlays (emacs, unstable, custom)
└── home-manager/
    ├── home.nix             # Imports all modules below
    ├── common.nix           # Base home-manager settings
    ├── platform/            # darwin.nix / linux.nix (conditional via stdenv.isDarwin)
    └── modules/             # Feature modules: git, shells, fish, tmux, kitty, neovim, doom-emacs
        └── inbox/           # packages.nix (large package list), inbox.nix (dev tools)
```

## Key Patterns

- **Platform conditionals**: `lib.mkIf pkgs.stdenv.isDarwin` / `lib.mkIf pkgs.stdenv.isLinux`
- **Flake inputs**: nixpkgs 25.05, home-manager release-25.05, nix-darwin darwin-25.05
- **Determinate Nix**: `nix.enable = false` in darwin config (conflicts with nix-darwin's daemon)
- **Overlays** in `overlays/default.nix` feed into `common.nix` and are applied system-wide

## Workflow Notes

- To add a new package: edit `home-manager/modules/inbox/packages.nix` (user-level) or `darwin/configuration.nix` (system-level)
- To add a new tool module: create `home-manager/modules/<tool>.nix` and import it in `home-manager/home.nix`
- When build fails, read the error output carefully — common issues are hash mismatches (run `nix flake update`) or missing inputs
- **After changing `system.defaults`**: run `darwin-rebuild switch`, then verify with `defaults read <domain> <key>`. Some settings need a logout/restart to take effect.
- **When adding a new default or tool**: search the web for current best practices before implementing. Check nix-darwin options, popular dotfile repos, and macOS power-user guides.