wheels packages --help advertises 'install' but the working verb is 'add' — help text drift

[bpamiri]

Severity: docs / discoverability.

Surfaced by: titan Phase 2.1 (Wheels 4.0 upgrade), 2026-05-15. Sibling to #2706 (install is a silent no-op).

Description

wheels packages --help documents:

install <name> [--force]   Install a package

The working command is wheels packages add <name> (which is not in the help output). See #2706 for the install no-op bug.

Even if #2706 is fixed by aliasing install to add, the help text should describe both verbs (or list the canonical one).

Suggested fix

Sync the wheels packages help output with the actual implementation:

• If install is aliased to add (per wheels packages install <name> is a silent no-op — canonical install command in docs doesn't actually install #2706 resolution): document add as canonical, list install as alias.
• If install is removed: just document add.
• Either way: don't ship a verb in --help that doesn't work.

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The wheels packages --help output advertises a verb (install) that does not work — this is observable wrong behavior in shipped help text, not just a docs site gap. The docs label on the issue reflects the surface (help text), but the defect is in the CLI module itself.

Suspected layer

cli — see .ai/wheels/cli/ for canonical patterns; the package dispatcher lives at cli/lucli/Module.cfc:2053 (packages() function) and cli/lucli/services/packages/PackagesMainCli.cfc.

Fix sketch

The packages() function hint at cli/lucli/Module.cfc:2033-2052 already documents add as the canonical verb and explains why install is intercepted by LuCLI's built-in extension installer (same trap that bit wheels browser install → wheels browser setup in #2345). The literal help row install <name> [--force] Install a package reported in the issue doesn't appear verbatim in the source — propose-fix's first task is to locate the help-text generator (most likely LuCLI's introspection of module functions, or a static help table) and sync the verbs. The two plausible resolutions are: (1) drop install from emitted help entirely and document add, or (2) document add as canonical and list install as an intercepted alias with a redirect note. Resolution depends on whether sibling #2706 reclassifies install as a usable alias.

Confidence: medium

Layer is unambiguous (CLI help text), but the help-text emission path needs investigation, and the right wording depends on how #2706 lands.

<!-- wheels-bot:triage:2713 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2729

Spec: cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc — failing → passing
Implementation: cli/lucli/Module.cfc — new $packagesHelp(), short-circuit in packages(), --help / -h parsing in $packagesArgsToOptions and $packagesStripFlags

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.