Rich completion and CLI IntelliSense system

[raiseCatError]

Goal

A structured completion system with IDE-like CLI IntelliSense:

• subcommands
• flags
• descriptions
• argument/value candidates
• categories/icons
• fuzzy filtering
• keyboard navigation
• fast incremental updates
• current NMSh styling and themes

Why

Completion is one of the places NMSh can be clearly better than a plain shell while keeping its own editor. Descriptions and structure also feed the command inspector (#84) and command correction (#152).

Current state

Candidates come from an isolated zsh -f capture helper (CompletionService + capture.zsh). #52 documents why full configured-zsh parity and fzf-tab are hard; #52 stays parked and is not reopened by this work.

Sources / providers

Source	Status
NMSh / zsh Native	Default; today's capture helper
Carapace	Research — #142
Fig-compatible specs	Research — #142
Inshellisense	Interop/reuse research — #142

Architectural constraints

• One source-independent structured candidate model (value, display, description, kind/category, source), so the UI does not care where candidates come from.
• NMSh keeps the UI. External engines supply data only.
• Completion never executes partial input. Dynamic value generators run only through safe, bounded, explicitly supported paths.
• Tab is never blindly forwarded to the managed shell (Configured-zsh completion parity and fzf-tab interoperability #52 finding).

Children

• Structured completion menu: descriptions, groups and fuzzy filtering #141 Structured completion menu
• External completion sources: Carapace, Fig-compatible specs and Inshellisense #142 External completion sources research

Non-goals

• Claiming fzf-tab support (Configured-zsh completion parity and fzf-tab interoperability #52).
• Predictive ghost text (Suggestion providers and predictive ghost text #137).

Dependencies / related

Part of #134. Related #52 (parked), #84, #145, #152.

[raiseCatError]

Development implementation is reviewable in #233 and #234, with cumulative hardening in #240; final acceptance documentation is #241. These are dependent, unmerged PRs on current dev, with no release/version bump.

The complete code head passed 714 local tests, build, typecheck, benchmark types and diff checks, plus Node 22/26 CI. Architecture and limitations describe what is implemented and deferred. One physical-QA checklist covers the relevant keyboard/layout/provider/privacy checks; it has not been performed.

This issue stays open until release. Project status could not be updated because the available token lacks read:project; active branches/PRs provide durable work status.

[raiseCatError]

Implemented on the v0.16 branch (PR #303, feature/v016-platform-portability-agents). Structured completion system: one candidate model, live shell source, bundled catalog and custom specs, with the menu from #141 and the source research from #142. Native fzf-tab remains a documented non-goal (#52). It was part of the integrated build the maintainer physically validated in the earlier v0.16 QA pass; closing with the implementation.