88 lines
4.5 KiB
Markdown
88 lines
4.5 KiB
Markdown
# AGENTS.md
|
|
|
|
## Overview
|
|
|
|
Nix flake — 3 devices (Mac Mini, MacBook Air: aarch64-darwin; WSL: x86_64-linux). Single user `imbytecat`. Uses **Lix**.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
flake.nix
|
|
├── darwinConfigurations.mac-mini (aarch64-darwin)
|
|
├── darwinConfigurations.macbook-air (aarch64-darwin)
|
|
└── nixosConfigurations.wsl (x86_64-linux)
|
|
```
|
|
|
|
- `lib/default.nix` — `mkDarwin`/`mkNixos` builders, `sshKeys` (via `specialArgs`), `homeManagerConfig`
|
|
- `modules/shared/` — cross-platform: Lix, overlays, fonts, fish, openssh, 1password
|
|
- `modules/darwin/` — system preferences, homebrew, user
|
|
- `modules/nixos/` — system packages, locale, docker, user
|
|
- `home/` — home-manager (shared, `useGlobalPkgs`), catppuccin
|
|
- `hosts/*/` — per-host overrides
|
|
- `overlays/` + `pkgs/` — custom packages (`comment-checker`)
|
|
|
|
Flow: `hosts/*` → `modules/*` → `home/*`
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
just rebuild mac-mini # macOS host (darwin-rebuild)
|
|
just rebuild macbook-air
|
|
just rebuild wsl # NixOS host (nixos-rebuild)
|
|
just check # eval without building (platform-aware)
|
|
just update # nix flake update
|
|
just up nixpkgs # update single input
|
|
just clean # nix-collect-garbage -d (user-level only)
|
|
just rollback # NixOS only — rollback to previous generation
|
|
just history # list system profile generations
|
|
just show # nix flake show
|
|
just lsp mac-mini # nixd option completion for VSCode
|
|
```
|
|
|
|
Note: `just check` and `just rebuild` have `[macos]`/`[linux]` variants — the justfile auto-selects by platform.
|
|
|
|
## Gotchas
|
|
|
|
- **Shared settings in `modules/shared/`** — don't re-declare fish/openssh/1password/fonts in platform modules.
|
|
- **`sshKeys` centralized** in `lib/default.nix` via `specialArgs`. Don't hardcode.
|
|
- **WSL aliases force-cleared** — `hosts/wsl/default.nix` uses `lib.mkForce {}`. All aliases via Home Manager only.
|
|
- **Neovim = lazyvim-nix** — `programs.lazyvim` in `home/dev/neovim.nix`. `catppuccin.nvim.enable = false` (LazyVim manages colorscheme). The `lazyvim.homeManagerModules.default` is loaded as a sharedModule in `lib/default.nix`.
|
|
- **catppuccin modules** — `catppuccin.homeModules.catppuccin` (home), `catppuccin.nixosModules.catppuccin` (NixOS). Not the old `homeManagerModules`.
|
|
- **Homebrew `cleanup = "zap"`** — undeclared casks/brews get removed. `greedyCasks = true` upgrades even auto-updating casks. Shared → `modules/darwin/`, host-specific → `hosts/*/`. Tap casks need full path (e.g. `"goooler/repo/fl-clash"`).
|
|
- **Ghostty macOS-only** — `enable = pkgs.stdenv.isDarwin`, `package = null` (Homebrew cask). Terminfo propagated via `ghostty.terminfo` in `modules/nixos/`.
|
|
- **nix-ld on WSL** — `programs.nix-ld.enable = true` for VSCode Remote.
|
|
- **home-manager `backupFileExtension = "bak"`** — set in `lib/default.nix`. Existing dotfiles get `.bak` suffix on conflict.
|
|
- **mise** — runtime version management (`home/dev/languages.nix`). `trusted_config_paths = [ "/" ]` trusts all config files.
|
|
|
|
## Environment
|
|
|
|
1Password CLI secrets are **cached locally** — shell startup reads `~/.cache/op-env/env.fish` (no network).
|
|
|
|
- Template: `home/shell/fish.nix` → `~/.config/op-env/env.tpl` (`op://` refs, safe to commit)
|
|
- Cache: `~/.cache/op-env/env.fish` (plaintext, `chmod 600`, outside git/nix store)
|
|
- Auth: `OP_SERVICE_ACCOUNT_TOKEN` in `~/.config/fish/local.fish` (gitignored)
|
|
- Refresh: user runs `op-env-refresh` manually (needs network). Atomic write (mktemp + mv), failure keeps old cache.
|
|
- Clear: `op-env-clear` removes cache file.
|
|
- `local.fish` is sourced **after** the cache, so it can override env vars per-machine.
|
|
|
|
## Home Manager option API
|
|
|
|
Use the new names:
|
|
- `programs.git.settings.user.{name,email}` (not `userName`/`userEmail`)
|
|
- `programs.git.settings.*` (not `extraConfig`)
|
|
- `programs.delta.{enable,options}` (not `programs.git.delta.*`)
|
|
- `programs.delta.enableGitIntegration = true` (must be explicit)
|
|
- `programs.ssh.matchBlocks."*".addKeysToAgent` (not top-level)
|
|
- `programs.ssh.enableDefaultConfig = false`
|
|
|
|
## Nix tooling
|
|
|
|
- LSP: `nixd`. Formatter: `nixfmt`. Linter: `statix`.
|
|
- All in `home/dev/languages.nix`.
|
|
- `just lsp <host>` generates `.vscode/settings.json` from `.vscode/settings.base.json` (gitignored output).
|
|
|
|
## Tool usage
|
|
|
|
- `opencode.jsonc` configures `just-lsp` (LSP) and `mcp-nixos` (MCP).
|
|
- **Always use `nixos_nix` MCP** to look up nix-darwin/NixOS/home-manager options before writing config. Don't guess option names.
|