From 99aaf3cf58b037da6cf03b272c036b469ebc5e4f Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Sun, 30 Aug 2026 18:13:54 -0400
Subject: [PATCH] docs: migrate dotfiles agent instructions

---
 AGENTS.md               | 31 +++++++++++++++++++++------
 configs/nixos/AGENTS.md | 46 +++++++++++++++++++++++++++++++++++++++++
 src/dotfiles/AGENTS.md  |  9 ++++++++
 3 files changed, 80 insertions(+), 6 deletions(-)
 create mode 100644 configs/nixos/AGENTS.md
 create mode 100644 src/dotfiles/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
index 2e4b418..7357351 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,15 +1,34 @@
-# Repository instructions
+# Alexion's Monorepo
 
 ## Commit convention
 
-Use Conventional Commits for all commit messages.
-Before writing a commit message, read `docs/conventional-commits.md`.
-Do not add agent attribution or co-author trailers.
+- Use Conventional Commits for all commit messages.
+  Before writing a commit message, read `docs/conventional-commits.md`.
+- Keep commit messages about the Git history, not the forge workflow.
+  Include external references only when they are stable context for the change.
+- Do not add agent attribution or co-author trailers.
 
 ## Technical writing
 
-Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose.
-Use the nearest project dictionary for project-specific domain language.
+- Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose.
+  Use the nearest project dictionary for project-specific domain language.
+
+## Pull requests
+
+- During pull-request development, add follow-up commits instead of amending existing commits.
+  Preserve review history until the pull request is ready to merge.
+
+## Forge workflow
+
+- Use `gitea-axi` for Gitea issues, pull requests, labels, reviews, comments, and milestones.
+  It resolves this repository from the `origin` remote inside the checkout.
+
+## Tooling
+
+- When a command is missing from the ordinary environment, prefer running it through Nix instead of installing it ad hoc.
+  For example, use `nix shell nixpkgs#python3 -c python3 <script>` for one-off Python commands.
+- Stage new files that Nix discovers through flake evaluation before testing.
+  Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before `nixos-rebuild --flake` can see them.
 
 ## Gotchas
 
diff --git a/configs/nixos/AGENTS.md b/configs/nixos/AGENTS.md
new file mode 100644
index 0000000..787d496
--- /dev/null
+++ b/configs/nixos/AGENTS.md
@@ -0,0 +1,46 @@
+# NixOS configuration instructions
+
+## Desktop
+
+- TODO: Verify this path after the NixOS configuration is migrated.
+  When adding a graphical application, add a `window-rewrite` icon mapping in `modules/desktop/session/waybar.nix`.
+  The workspace indicator uses this mapping to show an application icon instead of the generic default glyph.
+  Match the mapping on the window class.
+  Run `hyprctl clients -j | jq -r '.[].class' | sort -u` to list classes in the running session.
+- TODO: Verify this path after the NixOS configuration is migrated.
+  Set Hyprland session environment variables in `modules/desktop/session/hyprland/default.nix` with `env = KEY,VALUE`.
+  `home.sessionVariables` do **not** reach the Hyprland session because UWSM does not source `hm-session-vars.sh`.
+  Source cursor values from `config.stylix.cursor`.
+  Set `XCURSOR_*` and `HYPRCURSOR_*` to the same theme for Bibata.
+
+## Firefox
+
+- Manage Firefox search engines through `programs.firefox.search` with `force = true`.
+  Hide built-in engines with `<engine>.metaData.hidden = true` because omission does not remove them.
+  Use current engine ids, such as `default = "ddg"` instead of `"DuckDuckGo"`.
+  Decode the built `search.json.mozlz4` with `mozlz4a -d <search.json.mozlz4>` to check the result.
+- Avoid Home Manager Firefox extension settings unless the whole profile can use the legacy extension-storage backend.
+  Any non-empty `profiles.<name>.extensions.settings.<id>.settings` sets `extensions.webextensions.ExtensionStorageIDB.enabled = false` for the whole profile.
+
+## Neovim
+
+- Nixvim's flake input follows the root nixpkgs source, but its Home Manager module does not reuse the host's `pkgs` instance.
+  Keep `programs.nixvim.nixpkgs.useGlobalPackages = true`.
+  That setting makes Nixvim use the shared package set without warning that its source default changed.
+
+## AI tooling
+
+- Use produced literals for Herdr key names that include shifted punctuation.
+  For example, use `prefix+<` instead of `prefix+shift+comma`.
+- Treat Home Manager-managed Pi extension, prompt, and skill directories as generated output.
+  Do not edit those directories except for throwaway development or local experiments.
+  Promote finished work into the NixOS configuration before treating it as deployed.
+
+## Gotchas
+
+- Guest modules are host-agnostic wiring, while host files own deployment-specific service configuration such as served volumes and host paths.
+  For example, `guests/copyparty.nix` should expose options and translate them into guest mounts/service settings, while `hosts/pikachu/default.nix` chooses `/inbox`, `/media`, and their backing paths.
+  Guest addresses and routes are host-level configuration because a guest module can be used on multiple hosts.
+- `sops.secrets.<name>.owner` must name a user known on the decrypting host.
+  Do not set the owner to a guest-only service user unless the host also declares that user.
+  Use a host-visible owner plus a shared group mode when the guest service can read the decrypted secret file through its group.
diff --git a/src/dotfiles/AGENTS.md b/src/dotfiles/AGENTS.md
new file mode 100644
index 0000000..ad50820
--- /dev/null
+++ b/src/dotfiles/AGENTS.md
@@ -0,0 +1,9 @@
+# Dotfiles instructions
+
+## Gotchas
+
+- The registry collector reads only top-level host `config.registry` declarations.
+  Registry declarations inside guest interiors live under `config.containers.<guest>.config.registry`.
+  The collected registry does not include those guest-interior declarations.
+  Publish guest values from host-side code.
+  See http://git.alexion.dev/alexion/dotfiles/issues/65.