skills: retarget spacecraft-cli-preference at the local host

Companion to 6a01665, which did the same for spacecraft-missing-pkg. The
preference stack is unchanged — no tool is re-ranked. What changes is that a
substitution is now conditional on the machine it lands on.

Three gates, applied before anything is emitted:

- Availability (§1.1). Substituting to a tool that isn't installed turns a
  working command into `command not found`. Probe once, then route: present ->
  substitute; preferred absent but legacy present -> legacy plus a
  `# preferred: <tool>` note; both absent -> ephemeral run via
  spacecraft-missing-pkg. On this host that last branch is real: the table
  maps dig -> dog and neither is installed.
- Execution class (§1.2). The agent's shell has no TTY, yet ~20 entries are
  full-screen TUIs. Each now names its headless sibling (bottom -> procs,
  gitui -> git/jj, trip -> trip --mode report) or is marked hand-off. A
  separate class covers system-mutating tools, including two with destructive
  *defaults*: `kondo -a` deletes with no confirmation and `fclones remove`
  deletes files. sudo-rs is never run by the agent.
- Target (§1.0). One table, three audiences: what the agent runs, what gets
  committed to a repo, and what the user is handed to run. A committed `eza`
  breaks the build for everyone without it.

Also:

- Install hints across all 110 reference mastheads rewritten to defer to
  spacecraft-missing-pkg while keeping package identity. They previously
  carried 92 x `cargo install`, 6 x `paru -S`, 3 x `pacman -S`, 3 x
  `npm install -g`, 2 x `pip install`, `nix-env` and `nix profile install` --
  every one of them a prohibition in the sibling skill.
- Shell-integration tools (zoxide, atuin, starship, broot, gitway) route to
  `programs.<tool>.enable`; hand-editing an rc file stays prohibited.
- Package rows gated on host type: paru is Arch-only, and topgrade/omni/zap/am
  drift a declaratively managed host rather than serving it.
- Consent banners added to kondo, fclones, gptman, disktui, topgrade, paru.
- §1.3 separates the shell the agent invokes from the shell a script is
  authored for -- §1.5's Nushell/Ion cascade governs the latter only.

New reference: local-execution.md. Version 1.1, description 985 chars
(cap 1000). Bundles rebuilt at 114 files.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

README.md

@@ -38,7 +38,7 @@ the rules re-attached to every prompt.
 | [`spacecraft-carbon-guidelines`](spacecraft-carbon-guidelines/) | Type-safe highly-interoperable Carbon guidance — introducers (`let`/`var`), null safety (`Optional(T)`), bidirectional C++ interoperability (`import Cpp`), safety build profiles (debug/hardened), and C++ thread/atomic integrations. |
 | [`spacecraft-chez-guidelines`](spacecraft-chez-guidelines/) | Functional, safe, concurrent Chez Scheme guidance — R6RS libraries + Akku, pure-first design, `optimize-level` as the safety lever (level 3 = `unsafe`), hand-built mailboxes/channels over real threads (no Fibers), the FFI + AOT/whole-program compilation, and Guile-habit guardrails. |
 | [`spacecraft-clang-guidelines`](spacecraft-clang-guidelines/) | Memory-safe highly-hardened C guidance — NASA Power of 10 Rules (no runtime heap allocation, bounded loops, small functions, high assertion density), MISRA C safety subsets, CERT C secure coding rules, Clang `-fbounds-safety` compiler extensions, and C11 atomics. |
-| [`spacecraft-cli-preference`](spacecraft-cli-preference/) | Modern CLI substitutions: `eza` for `ls`, `rg` for `grep`, `gitway` for Git SSH, etc. |
+| [`spacecraft-cli-preference`](spacecraft-cli-preference/) | Modern CLI substitutions: `eza` for `ls`, `rg` for `grep`, `gitway` for Git SSH, etc. Conditional on the local host — substitute only when the tool is installed, fall back to the legacy tool with a note when it isn't, never launch a TUI in the agent's TTY-less shell, and get consent before anything that mutates or deletes. |
 | [`spacecraft-cli-standard`](spacecraft-cli-standard/) | Enforces the Spacecraft Software Dual-Mode Self-Documenting CLI Standard (v1.0.0) on every CLI. |
 | [`spacecraft-cli-shell`](spacecraft-cli-shell/) | Syntax-compliance guard for Nushell / Ion / POSIX / Bash commands. |
 | [`spacecraft-clojure-guidelines`](spacecraft-clojure-guidelines/) | Functional, safe-concurrent Clojure guidance — immutable-first design, reference-type decision tree (atoms / refs+STM / agents / core.async), transducers, lazy-seq discipline, ClojureScript and Babashka platform notes, and `standard-clj` formatting. |

spacecraft-cli-preference.skill

@@ -1,26 +1,28 @@
 ---
 name: spacecraft-cli-preference
 description: >
-  Enforces Spacecraft Software's CLI tool preferences. Whenever an agent is about to
-  generate, run, or recommend a shell command — in any context, including
-  bash snippets, scripts, CI, docs, or agentic tool use — the agent must first
-  check the command-mapping table in this skill and substitute the preferred
-  alternative for any legacy tool that has one. Examples: `eza` instead of
-  `ls`, `bat` for `cat`, `rg` for `grep`, `fd` for `find`, `jaq` for `jq`,
-  `xh` for `curl`, `dog` for `dig`, `procs` for `ps`, `bottom` for `top`.
-  Trigger on any mention of shell commands, terminal use, scripting, file
-  search, process inspection, network diagnostics, archive handling, text
-  editing, git, package management, or system monitoring. When invoking a
-  specific alternative, first consult the matching reference file in the
-  references directory for correct flag syntax.
+  Enforces Spacecraft Software's CLI tool preferences. Whenever an agent is
+  about to generate, run, or recommend a shell command — bash snippets,
+  scripts, CI, docs, or agentic tool use — check this skill's command-mapping
+  table first and substitute the preferred alternative for any legacy tool
+  that has one: `eza` for `ls`, `bat` for `cat`, `rg` for `grep`, `fd` for
+  `find`, `jaq` for `jq`, `xh` for `curl`, `dog` for `dig`, `procs` for `ps`,
+  `bottom` for `top`. Trigger on any mention of shell commands, scripting,
+  file search, process inspection, network diagnostics, archive handling,
+  text editing, git, package management, or system monitoring. Consult the
+  matching reference file for flag syntax before invoking.
+  Substitution is conditional on the local host: substitute only when the
+  preferred tool is installed, fall back to the legacy tool with a note when
+  it is not, never launch a TUI in the agent's TTY-less shell, and get
+  consent before any command that mutates or deletes.
 license: GPL-3.0-or-later
 maintainer: Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
 website: https://Construct.SpacecraftSoftware.org/
 ---
 
 # Spacecraft Software CLI Preference — Modern Alternatives over Legacy Tools
 
-**Version:** 1.0 | **Date:** 2026-05-18 | **Author:** Mohamed Hammad
+**Version:** 1.1 | **Date:** 2026-07-24 | **Author:** Mohamed Hammad
 **Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
 **Copyright:** (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
 **Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/)
@@ -45,12 +47,97 @@ a command appears.
 If §3 has no specific row for the legacy tool, apply the cascading fallback in
 §1.5 (`uutils` for GNU coreutils, Brush for Bash-only scripts).
 
-### Shell-syntax awareness
+**This runs on the user's own machine.** The preference stack below is
+unchanged, but on a real host a substitution is only correct if the tool is
+actually installed, the agent's shell can actually execute it, and the command
+does not silently change or delete something. §1.1–§1.3 are those three gates;
+apply them before emitting anything.
 
-Mohamed's primary shells are **Nushell** and **Ion**. Some command patterns
-(piping into `xargs`, command substitution `$(…)`, `&&`/`||` chaining) behave
-differently in those shells. When in doubt, prefer the portable POSIX form,
-but flag it if the user is clearly working inside a specific non-Bash shell.
+### §1.0 — Substitution depends on the target
+
+The same mapping table serves three audiences that need different behaviour:
+
+| Target | Rule |
+|---|---|
+| A command **the agent runs** in its own shell | Substitute only if the tool is present (§1.1), the command is headless-safe (§1.2), and it is non-destructive (§1.2). The agent's shell is a non-interactive Bash with no TTY — regardless of the user's interactive shell. |
+| A command **written into the user's repo** — script, CI job, `Justfile`, docs | Substitute only if the repo's own environment guarantees the tool: a devShell, a documented prerequisite, a CI image that ships it. Otherwise keep the portable form and add `# preferred: <tool>`. A committed `eza` breaks the build for every contributor without it. |
+| A command **suggested for the user to run** interactively | Full preference applies, TUIs included — this is where `gitui`, `yazi`, `bottom`, and `helix` belong. Hand it over with the `!` prefix rather than running it. |
+
+### §1.1 — Check availability before substituting
+
+A substitution to a tool that isn't installed is worse than no substitution:
+it turns a working command into `command not found`. Probe first, then route:
+
+| Preferred | Legacy | Action |
+|---|---|---|
+| present | — | **Substitute.** The happy path. |
+| present | absent | **Substitute** — it is the only option (e.g. `jaq` where `jq` was never installed). |
+| absent | present | **Use the legacy tool** and append `# preferred: <tool> — see references/<tool>.md`. Do not fail, do not silently install. |
+| absent | absent | **Route to `spacecraft-missing-pkg`** for an ephemeral run (`nix run nixpkgs#<pkg> -- …`). Neither form exists, so provisioning is the only way through. |
+
+```sh
+command -v eza >/dev/null 2>&1 && echo substitute || echo fall-back
+```
+
+Probe once per session and reuse the answer — don't re-check before every
+command. `command -v` alone under-reports: Nushell `def`s, Bash functions, and
+non-default bin directories hide installed tools from it. Use
+`spacecraft-missing-pkg`'s Step 0 checklist rather than restating it here.
+
+### §1.2 — Execution classes
+
+Every tool in §3 falls into one of four classes. Detail, per-tool headless
+alternatives, and the destructive-flag catalogue are in
+**[references/local-execution.md](references/local-execution.md)**.
+
+**Headless-safe — the agent may run these directly.**
+`eza`, `bat`, `fd`, `rg`, `sd`, `dust`, `procs`, `jaq`, `ouch`, `delta`,
+`just`, `tokei`, `uutils`, `xh`, `wget2`, `dog`, `monolith`, `lychee`,
+`macchina`, `oxipng`, `gifski`, `rav1e`, `viu`, `yt-dlp`, `jj`, `tokei`,
+`dua` (non-interactive form), `fclones group`.
+
+**Needs a TTY — hand off, or use the headless sibling.** Never launch these in
+the agent's shell; they hang, garble the transcript, or exit with a terminal
+error. Prefer the alternative when the goal is information, hand off when the
+goal is interaction:
+
+`bottom` → `procs` · `dua i` → `dua` · `gitui` → `git` / `jj` ·
+`yazi` / `broot` / `superfile` → `fd` / `eza` · `trip` → `trip --mode report` ·
+`gping` → `ping` · `atuin` TUI → `atuin search` · `zellij`, `kmon`, `impala`,
+`linutil`, editors (`hx`, `amp`, `rsvim`, `msedit`), chat TUIs (`iamb`,
+`rumatui`, `disrust`, `rivetui`), media TUIs (`ncspot`, `termusic`,
+`radio-browser`), `t-rec`, and the agent REPLs → hand off.
+
+**System-mutating or destructive — get consent, or hand off.** State what will
+change and wait:
+
+`topgrade`, `paru`, `omni`, `zap`, `am`, `rustup`, `cargo-update`, `gptman`,
+`disktui`, `nmstate`, `lanzaboote`, `greetd` / `lemurs` / `tuigreet`,
+`xremap`, `iwd`, `dotter`, `podman`. Two have destructive *defaults* worth
+naming: **`kondo -a` deletes build artifacts with no confirmation** and
+**`fclones remove` deletes files**. **`sudo-rs` is never run by the agent** —
+same rule as `sudo`; hand it over.
+
+**Shell-integration — declarative config, never a hand-edited rc.** `zoxide`,
+`atuin`, `starship`, `broot --install`, `gitway --install` all work by writing
+init lines into the user's shell config. Do not edit `.bashrc` / `config.nu` /
+`.profile`. On a managed host these are `programs.<tool>.enable` in Home
+Manager — propose that edit and let the user apply it
+(`spacecraft-missing-pkg` Band C).
+
+### §1.3 — Shell syntax: whose shell?
+
+Two separate questions, routinely conflated:
+
+- **The shell the agent invokes.** Whatever the harness gives it — here a
+  non-interactive Bash. Its commands must be valid *there*, no matter what the
+  user's login shell is.
+- **The shell a script is authored for.** That follows the user's preference
+  and Standard §7 (Nushell, Ion, Brush, and Bash are all first-class); a
+  script committed to a repo stays POSIX unless the repo says otherwise.
+
+`spacecraft-cli-shell` is the syntax authority for both — consult it rather
+than guessing at `^`-prefixes, `$(…)`, or `&&` behaviour per shell.
 
 ---
 
@@ -61,14 +148,20 @@ tool that has no explicit row, or a context where a shell has to be chosen.
 In both cases apply the cascade below — **always go as far up the list as
 possible** before dropping to the next tier.
 
-### Shells (when the AI picks or emits shell syntax)
+### Shells (when the AI **authors** a script or code example for the user)
+
+This cascade governs what the agent *writes*, not what it *runs* — see §1.3.
+
 1. **Nushell** 🦀 or **Ion** 🦀 — both are Mohamed's primaries, both are Rust.
    Default to one of these for any new script, one-liner, or code example.
 2. **Brush** 🦀 — only when Bash-compatibility is strictly required (e.g. a
    script must run under a `bash` interpreter and Nushell/Ion aren't options).
 3. **Plain Bash / POSIX `sh`** — last resort, only when the target environment
    hard-requires it (CI runner defaults, portability to unknown systems).
 
+A script **committed to a repo** inverts this: portability wins, so POSIX `sh`
+is the default there unless the repo already standardises on another shell.
+
 ### GNU utilities (when substituting a legacy coreutils binary)
 1. **Specific Rust alternative from §3** — `rg`, `fd`, `eza`, `bat`, `sd`,
    `procs`, `dust`, `jaq`, etc. Always check §3 first.
@@ -162,6 +255,17 @@ Read files with a plain file-view operation — each is short (typically 40–12
 
 ### Package & system management
 
+> **Gate.** These rows say *which* manager is preferred, not that the agent may
+> run it. Provisioning policy belongs to **`spacecraft-missing-pkg`**: prefer
+> an ephemeral run, put persistent tools in the host's declarative config, and
+> get consent before any durable install. Never run a system-wide update
+> unprompted.
+>
+> **Host-appropriateness matters.** `paru` is Arch-only; `topgrade`, `omni`,
+> `zap`, and `am` fight a declaratively managed host (NixOS, Home Manager,
+> Guix) by installing outside its config. On such a host the answer is the
+> host's own manager, not a row from this table.
+
 | Use case            | Prefer                | Ref file                      | Notes                                     |
 |---------------------|-----------------------|-------------------------------|-------------------------------------------|
 | universal package mgr | `omni` 🦀           | `references/omni.md`          | Cross-distro bridge                       |
@@ -302,13 +406,39 @@ procs rustc
 xh https://api.github.com/repos/UnbreakableMJ/Understand-Anything
 ```
 
+### When the gates change the answer
+
+```bash
+# Preferred tool absent, legacy present → fall back and note it
+dig +short example.com A        # preferred: dog — see references/dog.md
+
+# Both absent → ephemeral run via spacecraft-missing-pkg, not a failing command
+nix run nixpkgs#dog -- example.com A
+
+# TTY-class tool, agent needs the information → headless sibling
+procs rustc                     # not `btm`, which needs a terminal
+
+# TTY-class tool, user wants the interaction → hand off
+! gitui
+
+# Destructive default → propose, don't run
+#   kondo -a would delete target/ and node_modules/ under ~/projects — confirm?
+```
+
 ---
 
 ## §5 — When NOT to Substitute
 
+- **The preferred tool isn't installed** (§1.1). Fall back to the legacy tool
+  with a note — never emit a command that will fail.
+- **The command would run in the agent's shell but needs a TTY** (§1.2). Use
+  the headless sibling, or hand the TUI to the user.
+- **The command mutates or deletes** (§1.2) and consent hasn't been given.
 - **Explicit user request** for the legacy tool ("show me the raw `grep` command").
 - **Portable scripts** the user will run on systems without the Rust stack
   installed (document the alternative as a comment but keep the portable form).
+  This includes anything **committed to a repo** whose environment doesn't
+  guarantee the tool.
 - **Compatibility-critical pipelines** where a specific tool's exact output
   format is required by downstream tooling.
 - **The legacy tool is already the Spacecraft Software-sanctioned choice** for that slot
@@ -325,7 +455,7 @@ Each file in `references/` follows this structure:
 ```markdown
 # <tool>
 
-**Replaces:** <legacy tool(s)> | **Language:** 🦀/⚡/🐹/🐍/(λ)/⚠️ | **Install:** <package hint>
+**Replaces:** <legacy tool(s)> | **Language:** 🦀/⚡/🐹/🐍/(λ)/⚠️ | **Install:** via `spacecraft-missing-pkg` (<upstream package identity>)
 
 ## Purpose
 <One paragraph — what it does and when to reach for it.>
@@ -343,6 +473,12 @@ Each file in `references/` follows this structure:
 - <edge cases, non-POSIX behaviour, config requirements, etc.>
 ```
 
+The `**Install:**` field names *what* the tool is published as — a crate, an
+npm package, a distro package, an upstream release — and defers the *how* to
+`spacecraft-missing-pkg`. It never carries a runnable install command:
+`cargo install`, `paru -S`, `npm install -g`, `pip install`, `nix-env`, and
+`nix profile install` are prohibited there, as they are everywhere else.
+
 ---
 
 ## §7 — Attribution

spacecraft-cli-preference.zip

@@ -1,6 +1,6 @@
 # AdGuard VPN CLI
 
-**Replaces:** manual VPN dial-up | **Language:** 🐹 Go | **Install:** AdGuard official installer
+**Replaces:** manual VPN dial-up | **Language:** 🐹 Go | **Install:** via `spacecraft-missing-pkg` (upstream installer (AdGuard official))
 
 ## Purpose
 Command-line client for AdGuard VPN. Manage connection, protocols, DNS, split-tunnel.

spacecraft-cli-preference/SKILL.md

@@ -1,6 +1,6 @@
 # aichat
 
-**Replaces:** multiple per-vendor LLM CLIs | **Language:** 🦀 Rust | **Install:** `cargo install aichat`
+**Replaces:** multiple per-vendor LLM CLIs | **Language:** 🦀 Rust | **Install:** via `spacecraft-missing-pkg` (upstream crate: `aichat`)
 
 ## Purpose
 Universal LLM REPL + CLI. One tool for OpenAI, Claude, Gemini, local Ollama, llama.cpp, Azure, Bedrock, and more. Supports RAG, agents, function-calling.

spacecraft-cli-preference/references/adguardvpn-cli.md

@@ -1,6 +1,6 @@
 # am (AppMan)
 
-**Replaces:** manual AppImage management | **Language:** ⚠️ Bash | **Install:** upstream install script
+**Replaces:** manual AppImage management | **Language:** ⚠️ Bash | **Install:** via `spacecraft-missing-pkg` (upstream install script)
 
 ## Purpose
 Bash-based AppImage manager. Lightweight, no daemon, extensive catalog. Secondary choice after `zap`.

spacecraft-cli-preference/references/aichat.md

@@ -1,6 +1,6 @@
 # amp
 
-**Replaces:** `vim` (minimal alternative) | **Language:** 🦀 Rust | **Install:** `cargo install amp`
+**Replaces:** `vim` (minimal alternative) | **Language:** 🦀 Rust | **Install:** via `spacecraft-missing-pkg` (upstream crate: `amp`)
 
 ## Purpose
 Vi-inspired terminal editor. Smaller footprint than Helix, simpler than Vim, no plugin system.

spacecraft-cli-preference/references/am.md

@@ -1,6 +1,6 @@
 # atuin
 
-**Replaces:** native shell history, `fc`, reverse-i-search (Ctrl+R) | **Language:** 🦀 Rust | **Install:** `cargo install atuin`
+**Replaces:** native shell history, `fc`, reverse-i-search (Ctrl+R) | **Language:** 🦀 Rust | **Install:** via `spacecraft-missing-pkg` (upstream crate: `atuin`)
 
 ## Purpose
 SQLite-backed shell history with fuzzy full-text search, per-directory/host/session context, optional end-to-end encrypted sync across machines.

spacecraft-cli-preference/references/amp.md

@@ -1,6 +1,6 @@
 # bandwhich
 
-**Replaces:** `iftop`, `nethogs` | **Language:** 🦀 Rust | **Install:** `cargo install bandwhich`
+**Replaces:** `iftop`, `nethogs` | **Language:** 🦀 Rust | **Install:** via `spacecraft-missing-pkg` (upstream crate: `bandwhich`)
 
 ## Purpose
 Per-process/per-connection bandwidth monitor. Shows which process is using how much in real time.