7: packaging — systemd user unit + Nix modules + README

Ships the daemon as a real installable, not just `cargo build`.

Artifacts

  - `contrib/systemd/headroom.service` — user-scope unit. Type=simple
    (the daemon doesn't fork), After=pipewire.service, Restart=on-
    failure with a 2 s back-off so a crash loop doesn't spam stderr,
    StandardOutput/Error=journal, LimitRTPRIO=20 / LimitNICE=-11 to
    match the rtkit-style grant PipeWire's own unit carries. The
    file is templated with `@bindir@` so the build derivation can
    substitute in an absolute store path at install time, without
    the unit having to rely on whatever `headroom` happens to be on
    PATH.

  - `nix/home-module.nix` — `services.headroom.enable`. Installs the
    package on the user's PATH, symlinks the shipped profiles into
    `$XDG_CONFIG_HOME/headroom/profiles/`, and writes the systemd
    user unit (start After=pipewire.service Requires=pipewire.service
    Wants=wireplumber.service WantedBy=pipewire.service). Knobs:
    `installDefaultProfiles` for users who maintain their own set,
    `extraProfiles` (attrset of filename → path) to drop in personal
    profiles that override shipped ones by name.

  - `nix/nixos-module.nix` — `programs.headroom.enable`. Narrow scope:
    binary on global PATH, the package's `lib/systemd/user/*.service`
    is materialised under `/etc/systemd/user/` via `systemd.packages`,
    and an assertion fires if pipewire isn't enabled (clearer than a
    runtime crash). Per-user defaults (profile install, RT priority
    tuning) live in the Home Manager module; the two compose.

Build derivation

  `postInstall` now installs the unit (with `@bindir@` substituted to
  `$out/bin`) and copies `profiles/*.toml` to
  `$out/share/headroom/profiles/`. The flake's version lookup moved
  from `crates/headroom-cli/Cargo.toml` (where `version.workspace =
  true` evaluates to a table, not a string) to the workspace
  `Cargo.toml`. Modules exposed under `nixosModules.default` and
  `homeModules.default`.

README

  Rewrote the install section: Nix flake-based install with both
  Home Manager and NixOS module examples, plus a from-scratch
  `cargo install` + `install`/`sed` recipe for non-Nix users. Added
  a usage section with the common `headroom` subcommands and bumped
  the status banner from "pre-alpha" to "alpha" (signal chain,
  routing, IPC, monitor TUI, profile reload, and packaging all work
  end-to-end now).

Verified

  - `nix flake check` passes; NixOS module type-checks under
    nixpkgs eval.
  - `nix build .#headroom` produces `bin/headroom`,
    `lib/systemd/user/headroom.service` with the absolute store-path
    ExecStart baked in, and all five shipped profiles under
    `share/headroom/profiles/`.
  - `systemd-analyze verify --user` accepts the unit.
  - 185 workspace tests still pass; clippy clean at -D warnings
    --all-targets; `nix fmt` happy.

nix/nixos-module.nix

@@ -0,0 +1,61 @@
+# NixOS module — system-wide install. Headroom itself is a user-scope
+# daemon (it talks to the user's PipeWire session), so this module's
+# job is narrow:
+#
+#   1. Make the `headroom` binary available on every login's PATH.
+#   2. Drop the systemd user unit into the system-wide location so a
+#      user can `systemctl --user enable --now headroom` without first
+#      having to use Home Manager.
+#   3. Ensure the standard audio stack (PipeWire + WirePlumber) is
+#      enabled, since headroom can't function without them.
+#
+# For per-user defaults — activeProfile, shipped-profile install,
+# RT-priority tuning — use the Home Manager module
+# (`homeModules.default`) instead. The two compose.
+self:
+{ config, lib, pkgs, ... }:
+
+let
+  inherit (lib) mkEnableOption mkOption mkIf types literalExpression;
+
+  cfg = config.programs.headroom;
+in
+{
+  options.programs.headroom = {
+    enable = mkEnableOption "Headroom — PipeWire AGC + compressor + true-peak limiter daemon";
+
+    package = mkOption {
+      type = types.package;
+      default = self.packages.${pkgs.system}.headroom;
+      defaultText = literalExpression "headroom.packages.\${pkgs.system}.headroom";
+      description = ''
+        The headroom package to install system-wide.
+      '';
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # Binary + manpages (when we have them) on the global PATH.
+    environment.systemPackages = [ cfg.package ];
+
+    # Make the shipped systemd user unit discoverable by `systemctl
+    # --user`. Setting `packages` here is the canonical NixOS way to
+    # install user-scope unit files from a package — it materialises
+    # `/etc/systemd/user/headroom.service` pointing at the package's
+    # `lib/systemd/user/headroom.service`.
+    systemd.packages = [ cfg.package ];
+
+    # Headroom requires PipeWire; refuse to evaluate the module if
+    # the user enabled headroom but not pipewire, with a pointer
+    # rather than a confusing runtime failure.
+    assertions = [
+      {
+        assertion = config.services.pipewire.enable;
+        message = ''
+          programs.headroom.enable requires services.pipewire.enable = true;
+          headroom is a PipeWire-only daemon.
+        '';
+      }
+    ];
+  };
+}