feat(nix): install packaged shell completions

.github/workflows/ci.yml

@@ -196,6 +196,20 @@ jobs:
           fi
           echo "✅ Build output verified"
 
+      - name: Verify packaged shell completions
+        env:
+          OPENSPEC_TELEMETRY: '0'
+        run: |
+          completion_dir="$(mktemp -d)"
+          trap 'rm -rf "$completion_dir"' EXIT
+          for shell in bash fish zsh; do
+            result/bin/openspec completion generate "$shell" > "$completion_dir/$shell"
+            test -s "$completion_dir/$shell"
+          done
+          cmp "$completion_dir/bash" result/share/bash-completion/completions/openspec.bash
+          cmp "$completion_dir/fish" result/share/fish/vendor_completions.d/openspec.fish
+          cmp "$completion_dir/zsh" result/share/zsh/site-functions/_openspec
+
       - name: Test binary execution
         run: |
           VERSION=$(nix run . -- --version)

docs/cli.md

@@ -1262,10 +1262,21 @@ openspec completion generate bash > ~/.bash_completion.d/openspec
 openspec completion uninstall
 ```
 
-Completions are opt-in. The CLI mentions them once, on stderr, the first time you
-run a command in an interactive terminal, and never again — it also stays quiet
-if you already have completions installed. Set `OPENSPEC_NO_COMPLETIONS=1` to
-suppress that tip entirely.
+Installing completions with this command is opt-in. The CLI mentions them once,
+on stderr, the first time you run a command in an interactive terminal. It stays
+quiet if it detects a user-installed copy. Set `OPENSPEC_NO_COMPLETIONS=1` to
+suppress that tip entirely. This does not disable active completions.
+
+#### Nix completions
+
+Nix packages include Bash, Fish, and Zsh completion files. Your shell's completion
+configuration controls activation and may load them automatically. Installing the
+Nix package does not edit your shell startup files.
+
+`openspec completion install` and `uninstall` manage user-local copies, not files
+in the Nix package. The CLI may still show its installation tip when only packaged
+completions are present. Manage those completions through Nix or your shell's
+configuration.
 
 ---
 

docs/installation.md

@@ -155,6 +155,8 @@ Or add to your development environment in `flake.nix`:
 }
 ```
 
+For shell activation and ownership, see [Nix completions](cli.md#nix-completions).
+
 ## Verify Installation
 
 ```bash

flake.nix

@@ -56,6 +56,7 @@
             };
 
             nativeBuildInputs = with pkgs; [
+              installShellFiles
               nodejs_22
               npmHooks.npmInstallHook
               pnpmConfigHook
@@ -70,6 +71,21 @@
               runHook postBuild
             '';
 
+            postInstall = lib.optionalString (pkgs.stdenv.buildPlatform.canExecute pkgs.stdenv.hostPlatform) ''
+              # Disable telemetry during build-time completion generation.
+              export OPENSPEC_TELEMETRY=0
+
+              # Generate separately so a failure cannot be hidden by process substitution.
+              for shell in bash fish zsh; do
+                "$out/bin/openspec" completion generate "$shell" > "openspec.$shell"
+              done
+
+              installShellCompletion --cmd openspec \
+                --bash openspec.bash \
+                --fish openspec.fish \
+                --zsh openspec.zsh
+            '';
+
             dontNpmPrune = true;
 
             meta = with pkgs.lib; {