Make numan completions install by default

AGENTS.md

@@ -63,7 +63,7 @@ src/
     remove.rs          — `numan remove [--force] <pkg>`: remove from lockfile + delete payload (Phase 5); `--force` bypasses module activation only (active plugins always gated until deactivate, Issue #22)
     gc.rs              — `numan gc [--dry-run]`: delete orphaned payload directories (Phase 5)
     nupm.rs            — `numan nupm status|inspect|import|diff`: nupm discovery + import + drift (Phase 6.1–6.3)
-    completions.rs     — `numan completions <shell>`: bash/fish/zsh/powershell/nushell scripts (Phase 7.3)
+    completions.rs     — `numan completions <shell>`: install by default (mkdir+write); `--print` for stdout (Phase 7.3)
     setup.rs           — `numan setup nu [VERSION]|remove|path|use <path>` + `setup loader`: Nushell bootstrap + nushell-loader install
     try_cmd.rs         — `numan try [--yes] [--no-activate]`: curated starter install + activate for current Nu
     use_cmd.rs         — `numan use <version>|latest|list`: activates a previously installed managed Nu version (no auto-download); writes the active-version marker after a PreMutation snapshot under the root mutation lock

CHANGELOG.md

@@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Release assets** for `aarch64-unknown-linux-gnu` and `aarch64-pc-windows-msvc` (native ARM runners); `numan update --self` maps those triples
 - **Homebrew** Linux ARM archive support; **winget** verifies and submits both Windows x64 and ARM64 zips
 
+### Changed
+
+- **`numan completions <shell>`** installs by default (creates the target directory if needed). Use `--print` to emit the script on stdout for piping or custom redirects.
+
 ### Fixed
 
 - **`numan setup nu`**: official Nushell 0.114.x release archives exceed the old

README.md

@@ -51,7 +51,7 @@ These workflows are covered by unit tests, hermetic integration tests, and real-
 - **Lifecycle management**: Update, remove, and garbage collection operations recover safely through lifecycle journals.
 - **nupm interoperability**: Use `numan nupm status`, `inspect`, `import`, and `diff` to inspect, migrate, and detect drift in existing [nupm](https://github.com/nushell/nupm) installations.
 - **Health checks**: `numan doctor` diagnoses installation health and applies safe repairs by default. Use `--scan` for report-only mode.
-- **Shell completions**: Generate completions for Bash, Fish, Zsh, PowerShell, and Nushell with `numan completions`.
+- **Shell completions**: Install completions for Bash, Fish, Zsh, PowerShell, and Nushell with `numan completions` (use `--print` to emit the script).
 
 ---
 
@@ -67,8 +67,8 @@ These workflows are covered by unit tests, hermetic integration tests, and real-
 Install-only packages remain inert: numan downloads, verifies, locks, lists,
 removes, and garbage-collects their payloads, but does not execute them or
 modify Nu configuration for them. This is separate from numan's own shell
-completion generator: `numan completions <shell>` is supported for bash, fish,
-zsh, PowerShell, and Nushell (`nu`).
+completion installer: `numan completions <shell>` is supported for bash, fish,
+zsh, PowerShell, and Nushell (`nu`); use `--print` to emit the script instead.
 
 ---
 
@@ -151,33 +151,21 @@ Requires [Rust](https://rustup.rs/) (stable). The installed binary is named `num
 
 ### Shell completions
 
-`numan completions <shell>` prints the script on stdout and a copy-ready install command on stderr.
+`numan completions <shell>` installs to the canonical path and creates parent directories if needed. Use `--print` to emit the script on stdout (pipe-safe; redirect hints go to stderr).
 
 ```bash
-# Bash
-numan completions bash > ~/.local/share/bash-completion/completions/numan
-
-# Zsh
-numan completions zsh > ~/.zfunc/_numan
-
-# Fish
-numan completions fish > ~/.config/fish/completions/numan.fish
-
-# PowerShell (append to $PROFILE; do not use Out-File — that overwrites the profile)
-numan completions powershell | Add-Content -Encoding utf8 $PROFILE
-
-# Nushell (vendor autoload; `nu` is accepted as an alias for `nushell`)
-mkdir ($nu.data-dir | path join vendor/autoload)
-numan completions nushell | save -f ($nu.data-dir | path join vendor/autoload/numan-completions.nu)
+numan completions bash
+numan completions zsh
+numan completions fish
+numan completions nushell
+numan completions powershell   # writes ~/.numan/completions.ps1; dot-source from $PROFILE once
+
+# Advanced: print + redirect / pipe
+numan completions bash --print > ~/.local/share/bash-completion/completions/numan
+numan completions powershell --print | Add-Content -Encoding utf8 $PROFILE
 ```
 
-PowerShell completions are safe to place after other statements in `$PROFILE`. Prefer writing to a dedicated file and dot-sourcing if you want easier updates:
-
-```powershell
-New-Item -ItemType Directory -Force -Path "$HOME\.numan" | Out-Null
-numan completions powershell | Out-File -Encoding utf8 "$HOME\.numan\completions.ps1"
-Add-Content -Path $PROFILE -Value '. $HOME\.numan\completions.ps1'
-```
+PowerShell completions are safe to place after other statements in `$PROFILE`.
 
 
 ---
@@ -374,7 +362,7 @@ Global flag: `--root <path>` — override the numan root directory (all commands
 | `numan nupm import [--as owner/name] [path]` | One-way import into numan |
 | `numan nupm import --manifest file.toml` | Batch import from manifest |
 | `numan nupm diff <owner/name>` | Compare imported payload vs nupm source |
-| `numan completions <shell>` | Generate bash, fish, zsh, powershell, or nushell completions |
+| `numan completions <shell>` | Install shell completions (use `--print` to emit the script) |
 | `numan doctor [--scan] [--json]` | Diagnose root health and repair (use `--scan` for report-only) |
 
 ### Common flags (by command)

src/cli.rs

@@ -52,7 +52,7 @@ pub enum Commands {
     Snapshot(cmd::snapshot::SnapshotCommands),
     /// Read-only nupm discovery and inspection
     Nupm(cmd::nupm::NupmArgs),
-    /// Generate shell completion scripts
+    /// Install shell completions (use `--print` to emit the script)
     Completions(cmd::completions::CompletionsArgs),
     /// Diagnose Numan root health and apply safe repairs (use `--scan` for report-only)
     Doctor(cmd::doctor::DoctorArgs),