diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 5e8df63..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,71 +0,0 @@ -# AGENTS.md - -## Overview -This repository contains NixOS configurations for multiple machines using flakes, home-manager, and sops-nix for secrets. - -## Working with this Repository - -### DO -- Use `nix fmt` or `nix fmt .` to format files before committing (uses nixfmt-tree) -- Test builds with `nix build .#nixosConfigurations..config.system.build.toplevel` -- Use the included devShell run `nix develop` to get formatting and linting tools -- When adding packages, check both overlays in `flake.nix` and `home/programs/` -- Follow the directory structure: `hosts/` for system configs, `home/` for home-manager configs -- **CRITICAL: When adding NEW files, run `git add ` BEFORE building. Nix flakes ignore untracked files in the build context, so newly added files won't be copied and builds will fail until they're git-tracked** - -### DON'T -- Don't work directly on master branch, always create a new branch if editing something -- Don't run `nix flake update` to update inputs, this should only be done by the user manually -- Don't directly edit files in `secrets/` - they should be manually managed by the user -- Don't add secrets to Git -- Don't format with tools other than `nix fmt` (the formatter is defined in flake.nix) -- Don't modify `.sops.yaml` or any secrets, ask the user to do it manually -- Don't use `nix-shell` directly - use `nix develop` for the devShell environment -- Don't skip builds after configuration changes - test before pushing -- Don't mix stable and unstable packages arbitrarily in the same expression -- Don't commit without running `nix fmt` - formatted Nix is required -- **Don't try to build with newly created but untracked files - `nix build` will fail to find them** - -## Specific Patterns - -### Adding a New Program -- DO add to `home/packages` if no nixos or home-manager options are used. -- DO create a subdirectory in `home/programs/` if nixos or home-manager options are used. -- DO `git add` the new configuration files before attempting to build -- DON'T add programs directly to user configs unless absolutely necessary - -### Modifying System Configuration -- DO check `system/` for shared configs across hosts -- DO check individual `hosts//` for host-specific overrides -- DON'T duplicate configuration - use `system/` modules for shared settings - -### Working with Secrets -- DON'T add unencrypted secrets to the repository -- DON'T commit decrypted secrets -- DON'T add secrets, ask the user do it themselves - -### Testing -- DO run `nix build .#nixosConfigurations..config.system.build.toplevel` to test -- DON'T push untested configuration changes -- DON'T attempt to build configurations with newly added but untracked files - -### Git -If change is small, and can be described sufficiently in the summary, dont add a long -body to the commit, prefer just the summary if sufficient. - -Commits should match the format: -`topic: description of change` - -Some examples: -- hyprland: convert deprecated windowrules -- packages: nixfmt-rfc-style renamed -- gunter: use beta nvidia driver - - -## Repository Structure Guide -- `flake.nix` - Entrypoint, inputs, overlays, and configurations -- `hosts/` - System-level NixOS configs per host -- `home/` - Home-manager configs (programs, editor, window managers) -- `system/` - Shared system modules (fonts, security, services) -- `secrets/` - Encrypted secrets (managed by sops-nix) -- `scripts/` - Utility scripts diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..18e8b54 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,135 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +This is a NixOS configuration repository using flakes for managing multiple machines (gunter, magicman). It uses home-manager for user configurations and sops-nix for secrets management. Custom packages from private git repositories are integrated via flake inputs and overlays. + +## Essential Commands + +### Formatting +```bash +nix fmt # Format all Nix files (uses nixfmt-tree) +nix fmt . # Same as above +``` + +### Building & Testing +```bash +# Test build a specific host configuration +nix build .#nixosConfigurations.gunter.config.system.build.toplevel +nix build .#nixosConfigurations.magicman.config.system.build.toplevel + +# Enter development shell (includes act, actionlint, yamllint) +nix develop +``` + +If config clearly only affects one host, bulding for just the relevant host is enough. +Otherwise, build both. + +### Common Operations +```bash +# Check flake without building +nix flake check + +# Show flake outputs +nix flake show +``` + +## Architecture + +### Flake Structure +- **Inputs**: Uses both stable (nixos-25.05) and unstable nixpkgs channels +- **Overlays**: `overlay-stable` provides `pkgs.stable` for stable packages; custom overlays integrate private packages (ghettoptt, huecli, nixprstatus, natstonotify, nix-packages) +- **System**: x86_64-linux primary, with multi-platform devShell support + +### Directory Organization +``` +├── flake.nix # Main entrypoint with overlays and host definitions +├── hosts/ # Per-host system configurations +│ ├── gunter/ # Desktop with multi-monitor, nvidia, steam +│ └── magicman/ # Laptop configuration +├── home/ # Home-manager user configurations +│ ├── hosts/ # Per-host user settings (imports packages + programs) +│ ├── editor/ # Neovim configuration +│ ├── hyprland/ # Wayland compositor with custom options +│ ├── packages/ # Simple packages (no options) +│ ├── programs/ # Programs with home-manager options (dunst, git, firefox, etc.) +│ ├── services/ # User services (backup, ghettoptt, natstonotify) +│ ├── scripts/ # User scripts +│ ├── sops/ # User secrets configuration +│ ├── ssh/ # SSH configuration +│ └── zsh/ # Shell configuration +├── system/ # Shared system-level modules +│ ├── monitoring/ # logs.nix, metrics.nix +│ ├── fonts.nix # Font configuration +│ ├── locale.nix # Localization settings +│ ├── users.nix # User account definitions +│ └── ... # Other system modules +└── secrets/ # SOPS-encrypted secrets (don't modify) +``` + +### Configuration Pattern +- Each host's `default.nix` imports: `configuration.nix`, `hardware-configuration.nix`, host-specific modules, `../../system`, and `../../home/hosts/` +- Home-manager imports are in `home/hosts//default.nix` which imports editor, hyprland, packages, programs, services, etc. +- Shared system config goes in `system/`, host-specific overrides in `hosts//` + +### Hyprland Custom Options +The hyprland module in `home/hyprland/default.nix` provides custom options: +- `hyprland.monitors`: List of monitor configurations +- `hyprland.extraEnv`: Environment variables +- `hyprland.extraKeybinds`: Additional keybindings +- `hyprland.extraWorkspaces`: Named workspace definitions +- `hyprland.monitorVariables`: Monitor name variables (e.g., `$mon_left`) +- `hyprland.enableGrimblast`, `hyprland.enableWacom`, `hyprland.cursorNoHardware`: Feature flags + +## Critical Workflow Rules + +### Git Tracking for New Files +**CRITICAL**: Nix flakes ignore untracked files. When adding new files, run `git add ` BEFORE attempting to build. Builds will fail with "file not found" errors until files are git-tracked. + +### Branching +Always create a new branch for changes. Never work directly on master branch. + +### Formatting +Always run `nix fmt` before committing. Formatted Nix code is required. + +### Commit Messages +Format: `topic: description` + +Examples: +- `hyprland: convert deprecated windowrules` +- `packages: nixfmt-rfc-style renamed` +- `gunter: use beta nvidia driver` + +Keep summaries concise. Only add commit body if needed for context. + +### Forbidden Operations +- Don't run `nix flake update` (user manages input updates) +- Don't edit files in `secrets/` directory +- Don't modify `.sops.yaml` +- Don't use `nix-shell` (use `nix develop` instead) +- Don't mix stable/unstable packages arbitrarily +- Don't skip builds after configuration changes + +### Adding Programs +- If no NixOS/home-manager options needed: add to `home/packages` +- If using options: create subdirectory in `home/programs/` +- Remember to `git add` new files before building + +## Package Management + +### Using Stable Packages +The `overlay-stable` provides access to stable nixpkgs via `pkgs.stable`: +```nix +environment.systemPackages = [ pkgs.stable.somePackage ]; +``` +Do not use packages from stable unless explicitly requested. + +### Custom Packages +Custom packages from private repos are available via overlays: +- `pkgs.ghettoptt` +- `pkgs.huecli` +- `pkgs.nixprstatus` +- `pkgs.natstonotify` +- Plus packages from `nix-packages` overlay