Optional shell-tool discovery and first-run setup

[raiseCatError]

Status (updated at the v0.16 feature freeze)

Implemented on the v0.16 branch (PR #303, #307): /tools browser (Discover / Installed / Configure / Errors, categories, search, install previews with default-No confirmation, shared progress), truthful installed/selected-provider evidence, optional first-run browse/skip, supported Starship configuration (#83/#252), consent-based mise awareness (#253), curated catalog additions and integration/recommendation/environment/legacy distinctions (#306).

Remaining scope (why this stays open):

• A small local-facts-only Relevant here group (shell scripts, Git repositories, JavaScript manifests, Kubernetes manifests) reusing existing safe context facts; it must never scan or execute project files. The catalog already carries declarative relevantTo metadata for it.
• Additional package managers beyond Homebrew, and bulk selection.
• Active-hook detection for shell integrations.

Goal

Extend implemented first-run prompt setup with optional shell-tool discovery. Provider selection, Native appearance, composer layout, and /prompt settings are already implemented. Starship remains optional.

First-run flow

• Detect whether zoxide, fzf, and Atuin are installed and whether their zsh integration is active; show truthful status and next steps.
• Offer Recommended, Choose individually, and Skip.
• Explain each integration's changes before acting. Require explicit confirmation immediately before installation or setup modifies the system. Never install or edit shell configuration silently.
• Preserve compatible shell lifecycle hooks; broader real-zsh/plugin interoperability is Safe user zsh config and plugin interoperability #16. Safe completion widgets and fzf-tab remain unresolved in Configured-zsh completion parity and fzf-tab interoperability #52.

Boundaries

• Do not describe zsh-autosuggestions or zsh-syntax-highlighting as required; NMSh provides their UI roles.
• Do not claim native fzf-tab support.
• Keep Starship optional and do not overwrite its configuration.

This issue also owns the curated shell-tool catalog UX, exposed as /tools and from /settings -> Tools. Ordinary shell tools are not plugins.

Tool browser UX

Use a terminal-native, keyboard-first tabbed browser with the shared panel shell from #90:

Tools | Discover | Installed | Configure | Errors

Tabs without backing behavior may be deferred. There is no marketplace tab or third-party plugin marketplace architecture.

• Discover: curated catalog, search/filter, categories, Recommended indicator, installed/missing state, concise description, package-manager/install source, Enter for details, explicit install confirmation, useful multi-select where appropriate, package-manager-aware actions, visible progress/errors, and factual feedback via Reusable long-running task and install progress UI #91.
• Installed: detected tools with ready state and version/source/integration details when safely and cheaply known. Selecting a tool opens details. Show update availability only when factual and safely inexpensive to determine.
• Configure: controls only for actual safe NMSh workflows. Tool configuration center: read/edit supported tool config inside /settings #83 owns the shared configuration architecture; Starship and Powerlevel10k are tracked separately.
• Errors: actionable problems such as missing expected executables, invalid supported configuration, failed setup, or retained installation failure. Calm empty state: "No tool problems detected."

Keep direct commands valid. Search must not change settings or install tools. Never expose or log secret values; treat secret metadata conservatively.

Catalog categories and ordering

• Search & Files
• Git & Development
• Navigation & History
• Data / Structured Text
• Environment & Secrets
• Shell / Workflow
• Containers / Infrastructure
• Project / Language Tooling

Within each category: uninstalled first, alphabetically among uninstalled; installed afterwards, alphabetically among installed.

Conservative recommendations: zoxide, fzf, ripgrep, fd, jq; gh is useful but not required. Atuin, bat, eza, delta, lazygit, yq, direnv, Doppler, pass, stow, tmux, and cloud/Kubernetes tooling remain optional or specialized. Never silently install.

Related: #83 supported configuration, #90 shared panel shell, #91 install/task progress.

Roadmap update: provider install state

This issue remains the home for optional tool discovery and install flows. The provider framework (#134) reuses its detection and install recipes, so provider pickers show installed/missing state and offer install with the same explicit confirmation and progress UI (#91).

Tools that now back planned providers or integrations:

Tool	Used by
Fastfetch (Neofetch, legacy)	#135 Welcome providers
Deja	#139 Deja suggestion provider
Carapace	#142 External completion sources
Atuin	#144 Atuin history provider
zoxide	#147 Directory navigation
fzf, Television	#145 Picker providers
mise	#154 mise integration

Unchanged rule: NMSh never installs software automatically. Every install needs explicit confirmation immediately before it runs, shows progress, and reports failure factually. Detecting a tool never changes a setting.

[raiseCatError]

Summary

• Add configurable NMSh Native prompt appearance, one-line/two-line composer layout, and minimal first-run /prompt settings.
• Add optional Starship provider discovery, invocation, safe config-path/preset guidance, explicit Homebrew installation confirmation, and Native fallback.
• Capture semantic prompt/provider/color snapshots with commands and render them as hue-preserving muted archive headers.
• Put the compact two-color sitting cat at the top of the transcript and preserve follow/detached history behavior.
• Update prompt design docs and ROADMAP.

Verification

• npm run build — passed
• npm run typecheck — passed
• npm test — passed (199 tests)
• git diff --check — passed

Physical terminal validation is still required for onboarding navigation, Starship prompt rendering, segment geometry/palette legibility, resize/history behavior, welcome layout, and Ghostty/Terminal.app keyboard/mouse interaction. Use node --test scripts/slow-tap-fixture.mjs inside NMSh where relevant.

Refs #8
Refs #9
Refs #43
Refs #56
Refs #58

[raiseCatError]

PR #60 (c500f88) merged the onboarding presentation correction. Build, typecheck, 200 automated tests, and Node 22/26 CI passed. Physical validation is still required.

In Ghostty first, run a fresh setup and /prompt:

1. Confirm setup is readable and the normal bottom editor/cursor no longer competes with the clearly labeled preview.
2. Navigate provider, Native gap/end settings, and both composer layouts. Confirm one-line and two-line previews match the live Native prompt, including flat, wedge, fading-flat, and fading-wedge geometry.
3. If Starship is available, select it and check one-line/two-line previews and runtime. Verify NMSh retains layout control and existing config is untouched; verify fallback when Starship is unavailable.

Briefly smoke-check Terminal.app and VS Code integrated terminal. Keep this issue open until this is physically checked.

[raiseCatError]

Moved to v0.4.0. The prompt/provider/layout onboarding is implemented and tracked in v0.3 (#58, #49). This issue covers only optional shell-tool discovery for zoxide, fzf, and Atuin: Install recommended / Choose individually / Skip, per-tool installed/missing/integration state, and explicit confirmation before any installation. zsh-autosuggestions and zsh-syntax-highlighting are not recommended as required plugins, and fzf-tab support is not claimed (#52).

[raiseCatError]

Future direction: categorized tool catalog UI

As this onboarding/discovery flow grows beyond the initial zoxide/fzf/Atuin first-run prompt into a fuller /tools or /settings → Tools catalog, avoid a single flat tool list. Categorize, e.g.:

• Search & Files
• Git & Development
• Navigation & History
• Data / Structured Text
• Environment & Secrets
• Shell / Workflow
• Containers / Infrastructure
• Project / Language Tooling

Within each category, sort: uninstalled first (alphabetical), then installed (alphabetical).

Future catalog UX to design toward: scrolling, search/filter, installed/missing state, a Recommended marker, Enter for details, explicit "Install X? Yes/No" confirmation (never silent installs), multi-select where useful, package-manager-aware installation, and visible install progress/errors.

Keep the basic/recommended bundle conservative — zoxide, fzf, ripgrep/rg, fd, jq. Specialized tools (gh, Atuin, bat, eza, delta, lazygit, yq, direnv, Doppler, pass, stow, tmux, cloud/Kubernetes tooling, etc.) are optional catalog entries, not part of the default bundle just because they're popular.

This is future catalog-UX direction layered on top of the existing first-run flow described above — no implementation change from this comment.