wheels packages install <name> is a silent no-op — canonical install command in docs doesn't actually install

[bpamiri]

Severity: high — anyone following the canonical install instructions silently fails. Bad first impression for the entire 4.0 package system.

Surfaced by: titan Phase 2.1 (Wheels 4.0 upgrade), 2026-05-15.

Repro

$ wheels packages install wheels-sentry
Reading lucee.json...
Resolving dependencies...
ℹ️  No git or extension dependencies to install
$ echo $?
0

Exits 0. Reports success. Nothing was installed. vendor/wheels-sentry/ does not exist after the call.

The actual working command is wheels packages add wheels-sentry.

Two bugs in one

1. install is a no-op pointing at the lucee.json dep-resolver instead of the registry installer. wheels packages install <name> is what every doc surface tells users to run:

   • wheels packages --help shows install <name> [--force]
   • PLAN.md-style upgrade guides
   • User muscle memory from npm/pip/etc.

   But the implementation routes install to the lucee.json resolver, which finds no git/extension deps to install, and exits cleanly.

2. add works but isn't documented in wheels packages --help.

Suggested fix

One of:

• Alias install to add (preferred — least breakage, matches docs).
• Make install <name> fail loudly with an error pointing at add <name>.
• Update --help to remove install and document add instead.

File: cli/lucli/Module.cfc (or wherever Module.packages action dispatch lives).

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — dispatch in cli/lucli/Module.cfc and the top-level help string.

Fix sketch

The root cause is already documented in cli/lucli/Module.cfc:2084-2097: the case "install": block is dead code because LuCLI's built-in extension installer intercepts the literal verb install before dispatch reaches Module.packages(). That's the same picocli-token-interception trap that hit wheels browser install (renamed to wheels browser setup per #2345) and the wheels deploy server|secrets collisions documented in CLAUDE.md § "Critical gotchas" #7 and #8. The reporter's first suggested fix (alias install to add) won't work for the same reason — install never reaches the dispatcher to be aliased. The viable fixes are option 3 of the report (and arguably option 2 if a pre-dispatch hook exists): update cli/lucli/Module.cfc:223 (the top-level help line "Install, update, search Wheels packages") plus the packages subcommand hint at Module.cfc:2034 to stop advertising install, and audit docs/superpowers/specs/2026-04-23-wheels-packages-phase4-ui-design.md plus any user-facing guide that emits wheels packages install <name> (e.g. the copy-to-clipboard snippet at line 221 and 56 of that spec) and replace with wheels packages add <name>. If a pre-dispatch fail-loud is feasible without forking LuCLI, that would be the better UX but is a larger change.

Confidence: medium

Issue is reproducible and the suspected file is unambiguous, but the reporter explicitly lists three alternative fix shapes and the right one depends on whether LuCLI offers any pre-interception hook — that's a design call propose-fix needs to make, not a mechanical one-liner.

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

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2723

Spec: vendor/wheels/tests/specs/cli/PackagesCommandHelpSpec.cfc — failing → passing
Implementation: cli/lucli/Module.cfc (the top-level showHelp() summary line for packages)

The triage comment's option 3 was the only viable path — install is intercepted by LuCLI before Module.cfc dispatches, so neither aliasing nor a fail-loud branch can reach the verb. The summary line now leads with Add (the canonical verb already named in the hint: docblock) and parenthesises the gotcha so the doc surface stops contradicting the runtime.

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.