Command Discovery

Command discovery starts from the executable command graph. Metadata describes how a command is discovered; it does not execute product behavior or maintain a second command catalog.

Trigger

A user, script, or generated reference asks what the CLI can run, which options a command accepts, or how commands are nested.

Actors

• the recursive command registration graph;
• Effect CLI help and completion handling;
• generated command-reference consumers;
• users and automation reading those surfaces.

Discovery Flow

1. Each command module exports one behavior-free declaration containing its name, group, summary, options, examples, interaction requirement, and supported output modes.
2. A pure Effect CLI adapter applies declaration summaries to commands, examples, and flags while preserving each command's parsing, defaults, aliases, and handler.
3. The recursive registry pairs executable commands with their declarations. It derives paths from graph position and flattens the resolved graph into reference metadata without reading Effect CLI internals.
4. Root help, nested help, command listings, examples, and generated reference views therefore consume the same colocated facts.
5. A command addition, rename, removal, or option change reaches every discovery surface through its declaration and graph registration. Packaged public-output tests compare summaries, option descriptions, and examples against the resolved reference.

The implemented graph contains ten root commands:

check      ensure      init        operator    report
scaffold   skills      tools       update      upgrade

Its six nested command paths are:

operator status      operator install
operator update      operator migrate
skills rename        tools ensure

init and scaffold are root commands. They have no scaffold children. Baseline-aware commands retain the current stable, bundled, and exact-version selectors introduced by IP323.

Outcome

Executable discovery and generated reference data agree on the current graph. Metadata remains behavior-free, the registry does not introspect Effect commands, and no documentation page becomes a command registry.

Validation

The focused recursive registry/reference suite proves the exact ten roots and six nested paths. Packaged help and public-output tests remain the closeout signal for the shipped executable.

Next, see CLI Presentation Contract for how a selected command's semantic result reaches interactive, plain, or JSON output.