docs(readme): document Nix installation, modules and the flake dev shell

README.md

@@ -46,6 +46,69 @@ as you type. Press `p` to switch catalogue without restarting.
 
 ## Installation
 
+### Nix
+
+The flake builds the package, runs the test suite and wraps everything the app
+calls at runtime (`mpv`, `ffmpeg`, and PulseAudio's `parec`/`pactl` — PipeWire
+speaks the same protocol):
+
+```bash
+nix run git+https://tildeforge.dev/beefcarver/beefy-player              # try it
+nix profile install git+https://tildeforge.dev/beefcarver/beefy-player  # install it
+```
+
+In a NixOS configuration:
+
+```nix
+{
+  inputs.beefy-player.url = "git+https://tildeforge.dev/beefcarver/beefy-player";
+
+  outputs = { nixpkgs, beefy-player, ... }: {
+    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
+      modules = [
+        beefy-player.nixosModules.default
+        {
+          programs.beefy-player.enable = true;
+        }
+      ];
+    };
+  };
+}
+```
+
+Or, for a single user with Home Manager:
+
+```nix
+{
+  inputs.beefy-player.url = "git+https://tildeforge.dev/beefcarver/beefy-player";
+
+  outputs = { home-manager, beefy-player, ... }: {
+    homeConfigurations.me = home-manager.lib.homeManagerConfiguration {
+      modules = [
+        beefy-player.homeModules.default
+        {
+          programs.beefy-player.enable = true;
+        }
+      ];
+    };
+  };
+}
+```
+
+Both modules add one option, `programs.beefy-player.package`, so a pinned or
+overridden build can be substituted for the flake's own. The raw package
+(`packages.${system}.default`) and an overlay (`overlays.default`) are exported
+too. From a checkout, `nix develop` gives you `uv`, `ruff` and the audio tools
+for the usual `uv sync` / `uv run pytest` workflow; `nix build` builds and
+tests the package.
+
+### From source
+
+```bash
+uv sync
+uv run beefy-player
+```
+
 ## Usage
 
 ```bash
@@ -179,8 +242,8 @@ uvx ruff check .        # lint
 
 Each catalogue is a self-contained provider module under
 `beefy_player/providers/`; `base.py` documents the interface. `tools/ansi_art.py`
-converts a PNG logo into half-block ANSI art. On NixOS, `shell.nix` provides an
-FHS shell for the same `uv sync` / `uv run` workflow.
+converts a PNG logo into half-block ANSI art. On NixOS, `nix develop` (or the
+older `shell.nix`) provides the same `uv sync` / `uv run` workflow.
 
 ## Licence