docs: rename user-facing lucli references to wheels in CLAUDE.md, test-local, guides (#2544)

Wheels is built on the LuCLI runtime, but the rebranded `wheels` binary
is the only thing end users install. The codebase still has historical
mentions of `lucli` as the user-facing command — left over from the
period when the project was migrating off CommandBox onto LuCLI. The
mismatch confused at least one Claude Code session: a recent agent
followed `tools/test-local.sh`'s "brew install lucli" docstring instead
of using the `wheels` command that was actually on PATH, then concluded
LuCLI was uninstallable and gave up running the test suite locally.

Surgical scope, not a blanket find-and-replace:
- CLAUDE.md gets an explicit "wheels IS the CLI" callout in the testing
  section so future sessions don't repeat the mistake. Updated install
  instructions to recommend `brew install wheels`, `wheels server run`,
  `~/.wheels/express`.
- tools/test-local.sh switches `lucli` → `wheels` for command
  invocations and prerequisites; falls back to scanning both
  `~/.wheels/express` and `~/.lucli/express` for the JDBC lib so the
  script keeps working through the rename for older installs.
- web/sites/guides/.../testing/browser-tests.mdx and
  running-tests-locally.mdx fix the user-facing "brew install lucli"
  and `lucli server run` directions.
- CHANGELOG entry under [Unreleased] / Changed.

References to LuCLI as the upstream runtime project (installation docs
that explain how the rebrand works, runtime-specific env vars like
`LUCLI_HOME`, dotted CFC paths like `cli.lucli.services.X`, filesystem
paths under `cli/lucli/`, framework-dev tooling that genuinely tests
the LuCLI module distribution flow) are intentionally retained — they
are accurate context, not user instructions.

Closes the loose end from PR #2543's review thread.

Author: bpamiri

CHANGELOG.md

@@ -108,6 +108,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ### Changed
 
+- Project-level docs and the `tools/test-local.sh` script now refer to the CLI as `wheels` rather than `lucli`. Wheels is built on the LuCLI runtime, but the rebranded `wheels` binary is the only thing end users install — `brew install wheels`, `wheels server run`, `~/.wheels/express`. CLAUDE.md adds an explicit "wheels IS the CLI" callout so future Claude sessions and new contributors don't go looking for a separate `lucli` install when `tools/test-local.sh` fails. References to LuCLI as the upstream runtime project (e.g. installation docs explaining the relationship, runtime-specific env vars like `LUCLI_HOME`) are intentionally retained.
 - **Breaking:** CORS middleware default changed from wildcard `*` to deny-all. Apps must explicitly configure `allowOrigins` or set an explicit wildcard. (#2039)
 - **Breaking:** `viteStrictManifest` defaults to `true` — a missing Vite manifest entry now throws `Wheels.ViteAssetNotFound` in production instead of silently falling back (3.x behavior). Rebuild Vite assets during the upgrade window; to retain 3.x silent behavior, `set(viteStrictManifest=false)`. (#2133)
 - **Breaking:** `allowEnvironmentSwitchViaUrl` defaults to `false` in production (#2076)

CLAUDE.md

@@ -510,23 +510,25 @@ component extends="wheels.WheelsTest" {
 - **`Left(str, 0)` crashes Lucee 7**: Use a ternary guard: `local.match.pos[1] > 1 ? Left(str, local.match.pos[1] - 1) : ""`
 - Run with MCP `wheels_test()` or CLI `wheels test run`
 
-## Running Tests Locally (LuCLI — Recommended)
+## Running Tests Locally (Wheels CLI — Recommended)
 
 **IMPORTANT: Always run the test suite before pushing.** Do not rely on CI alone.
 
+> **`wheels` IS the CLI.** Wheels is built on the LuCLI runtime, but we ship the runtime under the `wheels` brand. End users only ever interact with the CLI as `wheels` — there is no separate `lucli` binary on a normal install. When older docs or scripts mention "install LuCLI" or invoke `lucli`, they pre-date the rebrand and are being migrated to `wheels`.
+
 ### Fastest method: one command
 ```bash
 bash tools/test-local.sh              # run all core tests
 bash tools/test-local.sh model        # run model tests only
 bash tools/test-local.sh security     # run security tests only
 ```
 
-The script handles everything: creates SQLite DBs, starts a LuCLI server if needed, runs tests, reports results, cleans up. No Docker required.
+The script handles everything: creates SQLite DBs, starts a Wheels CLI server if needed, runs tests, reports results, cleans up. No Docker required.
 
 ### Prerequisites (one-time setup)
 ```bash
-# Install LuCLI (0.3.3+ recommended)
-brew install lucli    # or download from GitHub releases
+# Install the Wheels CLI (4.0.0+ recommended)
+brew install wheels   # or download from GitHub releases
 # Java 21 required
 brew install openjdk@21
 ```
@@ -536,7 +538,7 @@ brew install openjdk@21
 cd /path/to/wheels
 sqlite3 wheelstestdb.db "SELECT 1;"
 sqlite3 wheelstestdb_tenant_b.db "SELECT 1;"
-lucli server run --port=8080
+wheels start --port=8080
 
 # In another terminal:
 curl -s "http://localhost:8080/?reload=true&password=wheels"
@@ -670,7 +672,7 @@ journal format. Output is directly comparable to fresh-VM run reports.
 |---|---|---|
 | 1 | Setup isolated `LUCLI_HOME`, framework path, Lucee Express symlink | — |
 | 2 | `wheels new` (no duplicate `create` lines, file tree, no `bundleName`) | F1, F3, F4 |
-| 3 | Server boot via `lucli server run` + sqlite-jdbc shim | (formula simulation) |
+| 3 | Server boot via `wheels start` + sqlite-jdbc shim | (formula simulation) |
 | 4 | Migration cliff — verify the actual sqlite db has tables, not just exit 0 | F2, F5 |
 | 5 | Seed (cfscript wrapper + `seedOnce` idempotency) | F3-orig |
 | 6 | CRUD walkthrough (tutorial chapters 2-3 happy path) | tutorial verification |
@@ -743,15 +745,15 @@ seedOnce(modelName="User", uniqueProperties="email", properties={
 });
 ```
 
-**CLI** (LuCLI canonical form; `wheels db:seed` is the legacy CommandBox alias — prefer the short form):
+**CLI** (canonical Wheels CLI form; `wheels db:seed` is the legacy CommandBox alias — prefer the short form):
 ```bash
 wheels seed                             # Run convention seeds (auto-detect env)
 wheels seed --environment=production    # Seed for specific environment
 wheels seed --generate                  # Legacy: random test data
 wheels generate seed                    # Create app/db/seeds.cfm
 wheels generate seed --all              # Create seeds.cfm + dev/prod stubs
 ```
-Note: the `--count` / `--models` / `--dataFile` flags on `--generate` only exist on the legacy CommandBox `wheels db:seed` surface; LuCLI's `wheels seed` ignores them.
+Note: the `--count` / `--models` / `--dataFile` flags on `--generate` only exist on the legacy CommandBox `wheels db:seed` surface; the Wheels CLI's `wheels seed` ignores them.
 
 **`seedOnce()`** — idempotent: checks `uniqueProperties` via `findOne()`, creates only if not found. Re-running seeds is always safe.
 
@@ -990,7 +992,7 @@ Deeper documentation lives in `.ai/` — Claude will search it automatically whe
 - `.ai/wheels/configuration/` — routing, environments, settings, DI container, multi-tenancy, security
 - `.ai/wheels/middleware/` — pipeline structure, rate limiting, tenant resolver
 - `.ai/wheels/jobs/` — background job queue, retries, priority queues
-- `.ai/wheels/mcp/` — AI agent integration via LuCLI stdio MCP (setup, tool reference, auto-discovery)
+- `.ai/wheels/mcp/` — AI agent integration via the Wheels CLI's stdio MCP (setup, tool reference, auto-discovery)
 - `.ai/wheels/packages/` — first-party packages (sentry, hotwire, basecoat) + activation model
 - `.ai/wheels/cli/` — generators (model, controller, scaffold, admin, migrations)
 - `.ai/wheels/testing/` — WheelsTest BDD, browser testing, browser automation patterns, **onboarding harness** (fresh-install simulation for cliff fixes)
@@ -1072,7 +1074,7 @@ The project name is **Wheels** (not "CFWheels"). The rebrand happened at v3.0. A
 
 ## MCP Server
 
-**Canonical surface (Wheels 4.0+):** LuCLI stdio MCP at `wheels mcp wheels`. Configure your AI IDE with:
+**Canonical surface (Wheels 4.0+):** the Wheels CLI's stdio MCP server at `wheels mcp wheels`. Configure your AI IDE with:
 
 ```json
 {"mcpServers":{"wheels":{"command":"wheels","args":["mcp","wheels"]}}}

tools/test-local.sh

@@ -1,10 +1,13 @@
 #!/usr/bin/env bash
-# Run Wheels core tests locally via LuCLI + SQLite (no Docker required)
+# Run Wheels core tests locally via Wheels CLI + SQLite (no Docker required)
 #
 # Prerequisites:
-#   - LuCLI 0.3.3+ installed (brew install lucli or download from GitHub)
+#   - Wheels CLI installed (brew install wheels or download from GitHub releases)
+#     Wheels is built on the LuCLI runtime; we ship the runtime under the
+#     `wheels` brand. There is no separate `lucli` binary on a normal install.
 #   - Java 21+ installed
-#   - SQLite JDBC driver in ~/.lucli/express/*/lib/ext/ (auto-installed by LuCLI 0.2.66+)
+#   - SQLite JDBC driver in ~/.wheels/express/*/lib/ext/ (auto-installed by recent
+#     Wheels CLI releases; older releases may use ~/.lucli/express/*/lib/ext/)
 #
 # Usage:
 #   bash tools/test-local.sh              # run all core tests
@@ -14,7 +17,7 @@
 #
 # Browser-test behavior:
 #   Browser specs (BrowserDialog/Login/Route) run against the local
-#   LuCLI server via Playwright. Requires Playwright JARs installed in
+#   Wheels CLI server via Playwright. Requires Playwright JARs installed in
 #   ~/.wheels/browser/lib/ — run `wheels browser:install` once if not.
 #   WHEELS_BROWSER_TEST_BASE_URL is auto-set to match the local PORT so
 #   specs hit the right server; CI sets its own override before invoking
@@ -29,7 +32,7 @@ DB="${DB:-sqlite}"
 PASSWORD="wheels"
 RESULT_FILE="/tmp/wheels-local-test-results.json"
 
-# Browser specs call back into the local LuCLI server — point Playwright
+# Browser specs call back into the local Wheels CLI server — point Playwright
 # at the right port. CI sets this explicitly before invoking the script;
 # the ${VAR:-default} preserves the CI override.
 export WHEELS_BROWSER_TEST_BASE_URL="${WHEELS_BROWSER_TEST_BASE_URL:-http://localhost:${PORT}}"
@@ -40,11 +43,11 @@ cd "$PROJECT_ROOT"
 sqlite3 wheelstestdb.db "SELECT 1;" 2>/dev/null || true
 sqlite3 wheelstestdb_tenant_b.db "SELECT 1;" 2>/dev/null || true
 
-# ── Resolve {project} placeholder if LuCLI doesn't support it yet ──
-# Check if lucee.json has {project} and LuCLI version < 0.2.66
+# ── Resolve {project} placeholder if the Wheels CLI doesn't support it yet ──
+# Check if lucee.json has {project} and the runtime version is too old to
+# resolve the placeholder.
 if grep -q '{project}' lucee.json 2>/dev/null; then
-  LUCLI_VER=$(lucli --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "0.0.0")
-  # Simple version check: if version starts with 0.2. or 0.3. and < 0.2.66
+  WHEELS_VER=$(wheels --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "0.0.0")
   # For safety, always create a resolved copy for the server
   cp lucee.json lucee.json.bak
   sed -i '' "s|{project}|${PROJECT_ROOT}|g" lucee.json
@@ -60,7 +63,7 @@ cleanup() {
   if [ "${STARTED_SERVER:-false}" = "true" ]; then
     echo "Stopping test server..."
     kill "$SERVER_PID" 2>/dev/null || true
-    lucli server stop 2>/dev/null || true
+    wheels server stop 2>/dev/null || true
   fi
 }
 trap cleanup EXIT
@@ -70,17 +73,19 @@ STARTED_SERVER=false
 if curl -s -o /dev/null --connect-timeout 2 --max-time 3 "http://localhost:${PORT}/" 2>/dev/null; then
   echo "Using existing server on port ${PORT}"
 else
-  echo "Starting LuCLI server on port ${PORT}..."
+  echo "Starting Wheels CLI server on port ${PORT}..."
 
-  # Ensure SQLite JDBC is installed
-  LUCEE_LIB=$(find ~/.lucli/express -path "*/lib/ext" -type d 2>/dev/null | head -1)
+  # Ensure SQLite JDBC is installed. Recent Wheels CLI releases extract
+  # Lucee Express to ~/.wheels/express/; older releases used ~/.lucli/express/.
+  # Search both so this script keeps working through the rename.
+  LUCEE_LIB=$(find ~/.wheels/express ~/.lucli/express -path "*/lib/ext" -type d 2>/dev/null | head -1)
   if [ -n "$LUCEE_LIB" ] && ! ls "$LUCEE_LIB"/sqlite-jdbc*.jar 1>/dev/null 2>&1; then
     echo "Downloading SQLite JDBC driver..."
     curl -sL "https://repo1.maven.org/maven2/org/xerial/sqlite-jdbc/3.49.1.0/sqlite-jdbc-3.49.1.0.jar" \
       -o "$LUCEE_LIB/sqlite-jdbc-3.49.1.0.jar"
   fi
 
-  nohup lucli server run --port="$PORT" --force > /tmp/wheels-test-server.log 2>&1 &
+  nohup wheels server run --port="$PORT" --force > /tmp/wheels-test-server.log 2>&1 &
   SERVER_PID=$!
   STARTED_SERVER=true
 

web/sites/guides/src/content/docs/v4-0-0-snapshot/testing/browser-tests.mdx

@@ -316,7 +316,7 @@ When a spec fails, the `aroundEach` hook captures a screenshot and HTML dump to
 
 The CI workflow sets `WHEELS_CI=true`, which `BrowserTest.beforeAll` interprets as an opt-out from running browser specs (they're skipped via `this.browserTestSkipped = true`). To run browser specs in CI, also set `WHEELS_BROWSER_CI_ENABLE=true` and ensure Playwright is installed on the runner. CI caches the Playwright JARs and Chromium via the `browser-manifest.json` hash; first runs pay the download cost once.
 
-Set `WHEELS_BROWSER_TEST_BASE_URL` so `visit("/path")` resolves to the right origin on the CI runner. For local work, the default `http://localhost:8080` matches `lucli server run --port=8080`. See [CI Integration](/v4-0-0-snapshot/testing/ci-integration/) for the full workflow.
+Set `WHEELS_BROWSER_TEST_BASE_URL` so `visit("/path")` resolves to the right origin on the CI runner. For local work, the default `http://localhost:8080` matches `wheels server run --port=8080`. See [CI Integration](/v4-0-0-snapshot/testing/ci-integration/) for the full workflow.
 
 ## When to skip browser tests
 

web/sites/guides/src/content/docs/v4-0-0-snapshot/testing/running-tests-locally.mdx

@@ -29,7 +29,7 @@ Before either path works, you need a handful of tools on `PATH`:
 
 - **Java 21+** — `brew install openjdk@21` on macOS, your distro's OpenJDK package on Linux, Adoptium on Windows.
 - **`JAVA_HOME` set** — LuCLI's preflight refuses to start if this is unset and points you at Adoptium. Set it in your shell profile (`export JAVA_HOME=$(/usr/libexec/java_home -v 21)` on macOS).
-- **The `wheels` CLI** — `brew install lucli`, `choco install lucli`, or the install script on Linux. This gives you the `wheels` command that wraps the LuCLI runtime.
+- **The `wheels` CLI** — `brew install wheels`, `choco install wheels`, or the install script on Linux. The Wheels CLI is built on the LuCLI runtime; we ship the runtime under the `wheels` brand so you only ever invoke it as `wheels`.
 - **SQLite** — usually pre-installed; `brew install sqlite` if not. Needed for the default test database.
 - **Docker Desktop or Docker Engine** — only if you're running the cross-engine matrix.