diff --git a/.gitignore b/.gitignore index 8525522..a26036e 100644 --- a/.gitignore +++ b/.gitignore @@ -4,13 +4,8 @@ git/.config/git/config.local # Herdr runtime state (written into the symlinked config dir; only config.toml is tracked) -herdr/.config/herdr/*.log -herdr/.config/herdr/session.json -herdr/.config/herdr/plugins.json -herdr/.config/herdr/.plugins.lock -herdr/.config/herdr/release-notes.json -herdr/.config/herdr/*.sock -herdr/.config/herdr/plugins/* +herdr/.config/herdr/* +!herdr/.config/herdr/config.toml # Nix result diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3369bfc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,134 @@ +# AGENTS.md + +Instructions for AI coding agents working in this repository. Humans should +start with `README`. The guides in `docs/` have the full details. + +## What this repo is + +Personal dotfiles for four platforms. Application config files are shared +across all of them; package management is not. + +| Platform | Packages | Config files linked by | +| --- | --- | --- | +| NixOS WSL2 (`nixos-wsl`, the main machine) | `flake.nix` + integrated Home Manager | `mkOutOfStoreSymlink` in `home/modules/` | +| Native NixOS (`nixos-native`) | `flake.nix` + integrated Home Manager | `mkOutOfStoreSymlink` in `home/modules/` | +| macOS | `Brewfile` | GNU Stow | +| Arch Linux | `pacman-packages.txt` | GNU Stow | + +Nix is used only on NixOS. There is no nix-darwin, no standalone Home Manager +configuration, and no ARM host. + +## Layout + +| Path | What goes there | +| --- | --- | +| `flake.nix` | Inputs, overlays and package pins, `mkSystem`, checks, dev shell | +| `systems/wsl/`, `systems/native/` | NixOS system settings for each host | +| `home/modules/*.nix` | Home Manager packages and config links, one topic per module | +| `home/nixos-wsl.nix`, `home/nixos-native.nix` | Each host's module imports and host-only packages | +| `/.config//` | The application's real config files (Stow package layout) | +| `bash/`, `zsh/` | Shell startup files, linked directly into `$HOME` | +| `docs/` | User documentation describing the current setup | + +## Hard rules + +- **Never change `system.stateVersion` or `home.stateVersion`.** They select + compatibility defaults, not the package release. +- **Keep application config hand-written and Stow-compatible.** macOS and Arch + use the same files without Nix. Don't convert a config to Home + Manager-generated settings (`programs.git.settings`, `programs.zsh`, + `programs.neovim`, `programs..settings`, and so on). Link the repo files + with `config.lib.file.mkOutOfStoreSymlink`, as the existing modules do. +- **Home Manager's shell modules are off** (`programs.zsh` and `programs.bash` + are not enabled). Options that inject into them, such as + `enableZshIntegration` or `home.shellAliases`, do nothing. + `home.sessionVariables` only reaches shells that source `hm-session-vars.sh` + (`bash/.bashrc` does). Put environment variables, aliases and shell + integrations in `zsh/.zshenv` or `zsh/.zshrc`, and mirror them in + `bash/.bashrc`. +- **Shell files must run on NixOS, Arch and macOS**, including macOS's bash + 3.2. Guard optional tools with `command -v`, and never reference + `/nix/store` paths. +- **Don't apply system changes unless the user asks.** That covers + `nixos-rebuild switch|boot|test`, `make switch|upgrade|clean|gc|setup-*`, + `stow`, and anything run with `sudo`. Note that `nixos-rebuild test` does + activate the configuration. +- **Don't update flake inputs unless asked.** Never run a bare + `nix flake update`. Update only the named inputs + (`nix flake update `), and keep `flake.lock` changes in the same + commit as the change that needs them. +- **Never commit secrets.** The `*.local` override files + (`git/.config/git/config.local`, `zsh/.zshenv.local`, `bash/.bashrc.local`) + are gitignored on purpose. +- **Herdr writes into its linked config directory.** Only + `herdr/.config/herdr/config.toml` is tracked, and Herdr itself may edit it. + Don't commit or revert changes there that you didn't make. +- **Neovim plugins are managed by lazy.nvim, not Nix.** Don't hand-edit + `nvim/.config/nvim/lazy-lock.json`. See `nvim/.config/nvim/README.md` before + changing the Neovim setup. + +## Package pins + +- `nixpkgs-azure-cli` is a commit-pinned nixpkgs that deliberately does **not** + follow `nixpkgs`. Don't add `inputs.nixpkgs.follows` to it. +- `copilotOverlay` overrides `github-copilot-cli`. A version bump must update + the version **and both** platform hashes (`x86_64-linux` and + `aarch64-linux`). +- Every other input follows `nixpkgs`. Do the same for new inputs. +- Add new package overrides as overlays in `mkSystem`, so NixOS and Home + Manager (`useGlobalPkgs = true`) see the same package. Record them in + `docs/EXAMPLE-VERSION-PINNING.md`. + +## Nix gotchas + +- The flake only sees files tracked by Git. Run `git add` on a new file before + evaluating or building. It doesn't need to be committed. +- The NixOS hosts are `x86_64-linux` only, but the checks, formatter and dev + shell also cover `aarch64-linux`. Per-platform data such as URLs and hashes + needs entries for both. +- CI runs `deadnix --fail` and `statix`. Remove module arguments (`pkgs`, + `config`, ...) and `let` bindings you stop using. +- Format Nix with `nixfmt` (the flake's formatter), not `nixpkgs-fmt`. +- `systemd.user.startServices = "suggest"` in the WSL home is intentional. It + lets the bootstrap configuration activate before any user session exists. +- The username `user3301` and the checkout path `/home/user3301/dotfiles` are + hard-coded in several files. Don't rename them unless asked; see + `docs/DEPLOYMENT.md` for every place involved. + +## Adding an application config + +1. Put the files in `/.config//`. +2. Link the directory from the matching `home/modules/*.nix` with + `xdg.configFile."".source = config.lib.file.mkOutOfStoreSymlink ...`. +3. If the app is also used on macOS or Arch, add `` to `STOW_PACKAGES` in + `Makefile`, and its package to `Brewfile` or `pacman-packages.txt`. +4. Update the module table and Stow package lists in `docs/`. + +## Validate before finishing + +These commands mirror CI (`.github/workflows/ci.yml`) and need no `sudo`: + +```sh +nix fmt +nix build --no-link \ + .#checks.x86_64-linux.nix-quality \ + .#checks.x86_64-linux.lua-format \ + .#checks.x86_64-linux.zsh-syntax \ + .#checks.x86_64-linux.bash-syntax +nix eval --raw '.#nixosConfigurations.nixos-wsl.config.system.build.toplevel.drvPath' +# CI doesn't evaluate the native host. Do it when you touch shared or native modules: +nix eval --raw '.#nixosConfigurations.nixos-native.config.system.build.toplevel.drvPath' +``` + +Check the output for `evaluation warning:` lines as well as the exit code. +`nix develop` provides nixfmt, statix, deadnix, StyLua and nil. + +## Conventions + +- Commit subjects are imperative and sentence case, with no type prefix, for + example "Add kubectl and kubectx to dev-tools". The default branch is + `master`. +- Pin GitHub Actions to a full commit SHA, with the version in a trailing + comment (`# v7.0.1`). +- `docs/` describes the current setup. When you change behavior, packages, + modules or pins, update the matching doc in the same change. diff --git a/herdr/.config/herdr/config.toml b/herdr/.config/herdr/config.toml index c692858..bee0d83 100644 --- a/herdr/.config/herdr/config.toml +++ b/herdr/.config/herdr/config.toml @@ -7,6 +7,7 @@ onboarding = false agent_panel_sort = "spaces" show_agent_labels_on_pane_borders = true +status_indicators = "symbols" [theme] name = "dracula" auto_switch = false diff --git a/nvim/.config/nvim/lazy-lock.json b/nvim/.config/nvim/lazy-lock.json index ce287e0..909e66d 100644 --- a/nvim/.config/nvim/lazy-lock.json +++ b/nvim/.config/nvim/lazy-lock.json @@ -45,7 +45,7 @@ "render-markdown.nvim": { "branch": "main", "commit": "640a3ec6d538bad17c328be373c7cad0293d9589" }, "rose-pine": { "branch": "main", "commit": "ff483051a47e27d84bdef47703538df1ed9f4a47" }, "roslyn.nvim": { "branch": "main", "commit": "bf1bd4e70bc7068d1b4aebf4ce03cc19a86615be" }, - "smear-cursor.nvim": { "branch": "main", "commit": "f63ff221158b5b0ca9de1d7d1ff2e0dce5649614" }, + "smear-cursor.nvim": { "branch": "main", "commit": "af2e5325760abbdc121ac5a963c8d8ceaa28552a" }, "snacks.nvim": { "branch": "main", "commit": "882c996cf28183f4d63640de0b4c02ec886d01f2" }, "todo-comments.nvim": { "branch": "main", "commit": "31e3c38ce9b29781e4422fc0322eb0a21f4e8668" }, "tokyonight.nvim": { "branch": "main", "commit": "cdc07ac78467a233fd62c493de29a17e0cf2b2b6" },