Command inspector: Warp-like cursor-context command/flag intelligence #84

Goal

Explore a future Warp-like command inspector that understands cursor context in the composer — which command, subcommand, flag, or argument the cursor is currently on/near — and can surface an explanation for it. Design/research tracking only; no implementation, UI contract, or knowledge-source commitment here.

Example

rg --hidden foo
   ^

With the cursor on --hidden, the inspector should be able to explain what that flag does for rg.

Possible knowledge sources to investigate

• The user's actual configured zsh completions (ties into Configured-zsh completion parity and fzf-tab interoperability #52's completion-parity investigation).
• Tool-generated completion metadata.
• Local man pages.
• Safe local --help output.
• Structured per-tool adapters (see the adapter hierarchy explored in the tool-configuration-center issue).

Placement invariant

• Composer docked at bottom → inspector renders ABOVE the composer.
• Composer docked at top → inspector renders BELOW the composer.
• Chat presentation (Interaction layout modes: docked, flow, and chat presentation #79) only changes transcript/history layout; it must never implicitly reposition the composer or the inspector's placement relative to it.

Related

• Configured-zsh completion parity and fzf-tab interoperability #52 (configured-zsh completion parity) is a natural source of cursor-context knowledge.
• Configurable one-line and two-line composer layouts #49 (composer placement) and Interaction layout modes: docked, flow, and chat presentation #79 (chat presentation) define the layout axes the placement invariant above depends on.

v0.4 safety and placement decision

Identify command, subcommand, flag, and argument near the caret. Investigate configured zsh completion metadata (#52), generated completion specs, structured tool adapters, local man/whatis, and carefully controlled local help output. Never execute an arbitrary unknown command with --help. Bottom composer places inspector above; top composer places it below. Chat transcript presentation does not move the composer or inspector.

Roadmap update: shared command intelligence

The inspector should share knowledge with the completion system rather than build its own:

• Flag and subcommand documentation from structured completion metadata (Rich completion and CLI IntelliSense system #140, External completion sources: Carapace, Fig-compatible specs and Inshellisense #142: Carapace / Fig-compatible specs) and man/help-derived metadata.
• Contextual descriptions for the token under the cursor (command, subcommand, flag, argument value).
• The same structured candidate model as the completion menu (Structured completion menu: descriptions, groups and fuzzy filtering #141), so one knowledge source serves both.
• Never executes arbitrary partial input. Local --help only for known commands through an explicit allowlist or adapter, bounded and cached.

Placement follows the composer edge: above for Dock Bottom, below for Dock Top (#123). Flow placement follows #132. Still research; no implementation implied.