1 files changed, 133 insertions, 0 deletions
diff --git a/nixos/docs/ADDING_PACKAGES.md b/nixos/docs/ADDING_PACKAGES.md
new file mode 100644
index 0000000..a4c0c5a
--- /dev/null
+++ b/nixos/docs/ADDING_PACKAGES.md
@@ -0,0 +1,133 @@
+# Adding Packages
+
+This configuration is composed from `hosts/opus/default.nix` and focused modules
+under `modules/system/` and `modules/features/`. There is no central package list.
+
+## Where a package belongs
+
+| Package type | Module |
+| --- | --- |
+| Terminal | `modules/features/terminals/default.nix` |
+| CLI tool | `modules/features/cli-tools/default.nix` |
+| Editor or IDE | `modules/features/editors/default.nix` |
+| Desktop application | `modules/features/desktop-apps/default.nix` |
+| Compiler, linter, language tool | `modules/features/dev-tools/default.nix` |
+| File manager or archive tool | `modules/features/file-managers/default.nix` |
+| Wayland clipboard, screenshot, or input tool | `modules/features/wayland-tools/default.nix` |
+| Audio application | `modules/features/audio-tools/default.nix` |
+| System monitor or fetch tool | `modules/features/monitoring/default.nix` |
+| Font | `modules/features/fonts/default.nix` |
+| GStreamer plugin | `modules/features/gst-codecs/default.nix` |
+| Runtime library for external binaries | `modules/features/binary-compat/default.nix` |
+
+First use an existing category. Create a new feature module only if the package is
+its own service, subsystem, or a group of related packages without a fitting category.
+
+## Add to an existing module
+
+Add the package to that module's `environment.systemPackages` list:
+
+```nix
+{ pkgs, ... }:
+
+{
+  environment.systemPackages = with pkgs; [
+    existing-package
+    ripgrep
+  ];
+}
+```
+
+Most modules use `with pkgs;`, so use unqualified package names. Use `pkgs.<name>`
+when an explicit path is useful, such as `pkgs.vimPlugins.im-select-nvim`, or when
+applying an override:
+
+```nix
+(emacs.override { withNativeCompilation = true; })
+```
+
+Keep related packages together and follow the local ordering of the file.
+
+## Fonts are different
+
+Fonts belong in `modules/features/fonts/default.nix` under `fonts.packages`, not
+`environment.systemPackages`:
+
+```nix
+fonts.packages = with pkgs; [
+  nerd-fonts.jetbrains-mono
+  noto-fonts-color-emoji
+];
+```
+
+## Create a new feature module
+
+1. Create `modules/features/<category>/default.nix`:
+
+   ```nix
+   { pkgs, ... }:
+
+   {
+     environment.systemPackages = with pkgs; [
+       package-name
+     ];
+   }
+   ```
+
+2. Add its directory to the `imports` list in `hosts/opus/default.nix`:
+
+   ```nix
+   ../../modules/features/<category>
+   ```
+
+3. Put services and program options in the same module when they belong to that
+   feature, as done by `modules/features/mpd/default.nix`.
+
+## Host-only packages
+
+For a package that is truly specific to this desktop, add it to the small
+`environment.systemPackages` list in `hosts/opus/default.nix`. Gaming is the current
+example. If that list starts to represent a reusable category, extract a feature module.
+
+## Packages from flake inputs
+
+Packages provided by a flake input use `inputs` and the host platform, following
+`modules/features/desktop-apps/default.nix`:
+
+```nix
+{ pkgs, inputs, ... }:
+
+{
+  environment.systemPackages = with pkgs; [
+    inputs.helium-browser.packages.${pkgs.stdenv.hostPlatform.system}.helium
+  ];
+}
+```
+
+If an input provides a NixOS module, import it in the feature module, following
+`modules/features/noctalia-greeter/default.nix`:
+
+```nix
+imports = [
+  inputs.some-input.nixosModules.default
+];
+```
+
+The input itself must first be declared in `flake.nix`.
+
+## Build and switch
+
+From the `nixos/` directory, first test that the configuration evaluates and builds:
+
+```bash
+doas nixos-rebuild build --flake .#opus
+```
+
+Then activate it:
+
+```bash
+doas nixos-rebuild switch --flake .#opus
+```
+
+If a terminal's font icons do not update after adding fonts, restart the terminal or
+log out and back in after the switch.