`wheels packages install` command does not install packages and conflicts with documentation

[zainforbjs]

Describe the bug

Using the command:

wheels packages install <package-name>

always results in the following error:

No git or extension dependencies to install

However, the command:

wheels packages add <package-name>

works correctly and installs the package successfully.

---

Documentation inconsistency

There are currently two different documentation sources describing package installation using different commands:

wheels packages install

Documentation:
https://packages.wheels.dev/

wheels packages add

Documentation:
https://guides.wheels.dev/v4-0-0-snapshot/digging-deeper/packages/

The issue is that:

• install is documented as the installation command
• but install does not actually install packages
• while add performs the expected installation behavior

---

To Reproduce

Steps to reproduce the behavior:

1. Run:

wheels packages install <package-name>

2. Observe the error:

No git or extension dependencies to install

3. Run:

wheels packages add <package-name>

4. Observe that:
   • package installs successfully
   • package is downloaded correctly

---

Expected behavior

The command:

wheels packages install <package-name>

should:

• download and install the package
• place it in the expected vendor/package-name location
• behave as documented

OR

The documentation should clearly indicate that add is the correct command to use.

---

Actual behavior

• install command does not install packages
• unrelated dependency message is shown
• add performs the actual installation behavior instead

---

Related Links

• https://packages.wheels.dev/
• https://guides.wheels.dev/v4-0-0-snapshot/digging-deeper/packages/
• https://guides.wheels.dev/v4-0-0-snapshot/command-line-tools/commands/packages/install/

---

Desktop

• OS: Any
• Wheels CLI Version: 4.0-SNAPSHOT

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see .ai/wheels/cli/ for canonical patterns. The packages CLI lives at cli/lucli/services/packages/PackagesMainCli.cfc, with public docs under docs/src/command-line-tools/commands/packages/ and the guides site at web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/packages/.

Fix sketch

This is a known LuCLI runtime trap — the comment block at the top of cli/lucli/services/packages/PackagesMainCli.cfc (lines 13-19) already documents it verbatim: wheels packages install <name> never reaches Module.cfc because LuCLI's built-in extension installer intercepts the literal install subcommand across every module and instead runs its dependency installer against lucee.json — which is what emits "No git or extension dependencies to install". add is the canonical install verb (it's the documented verb in CLAUDE.md's packages quick reference). The fix is primarily documentation: the install page under docs/src/command-line-tools/commands/packages/install/ and any matching page under web/sites/guides/.../command-line-tools/commands/packages/install/ should be removed (or replaced with a stub that redirects to add), and packages.wheels.dev content should be updated to use add consistently. A secondary CLI-side improvement is removing or rewording any help text that still advertises install so the surface matches reality.

Confidence: high

The CLI behavior is already documented in-tree as an intentional LuCLI limitation, the root cause is unambiguous, and the fix is a mechanical docs sync with no design trade-offs — no auto-downgrade rules apply (no security, middleware, migrations, deploy, or DI involvement).

<!-- wheels-bot:triage:2610 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:high -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2611

Spec: vendor/wheels/tests/specs/packages/CliTemplateInstallVerbSpec.cfc — failing → passing (three deterministic file-content assertions, verified manually via grep since the wheels CLI was not available in the bot's sandbox)

Implementation:

• cli/lucli/templates/app/_gitignore — drop the misleading wheels install hint
• cli/lucli/templates/app/app/plugins/README.md — point users at wheels packages add wheels-hotwire and call out that the verb is add, not install

Scope notes:

• This is the CLI-side half of the fix. Docs sync (the MDX install.mdx guide page, .ai/wheels/, CLAUDE.md) is handled separately by bot-update-docs.yml per the bot rails.
• Module.cfc already has a case "install" branch that prints a friendly redirect; it's documented in-tree as dead code on the CLI surface because LuCLI intercepts before dispatch. Left as-is.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly.