docs: align CLI core guides with 4.0.3 behavior — MCP tool names, version output, inert flags

[bpamiri]

Summary

Final-wave docs fixes from the 2026-06 guide behavioral audit (P2 manifest, group 4: CLI core pages — 7 findings, every claim live-verified against the released brew wheels 4.0.3).

command-line-tools/installation.mdx (installation-01, installation-04)

• The "verifying installation" sample showed a fictional 3-line Wheels / LuCLI 0.3.7 / Java output. Live: wheels --version prints Wheels Version: 4.0.3 + the ASCII banner (no LuCLI/Java lines); wheels version prints Wheels 4.0.3 (stable) + Java 21.0.11. Sample replaced with both real shapes.
• Channel marker ((stable) / (bleeding-edge)) comes from wheels version, not wheels --version — fixed the manual-install Aside bullet to match.
• wheels system env does not exist (wheels system offers inspect/paths/clean/backup/help; env exits 1 with usage). Troubleshooting now points at wheels system paths, which prints the resolved home + source.

command-line-tools/quick-start.mdx (quickstart-04, quickstart-05)

• The scaffold generates PostSpec.cfc (tests/specs/models/) and PostsControllerSpec.cfc (tests/specs/controllers/) — there is no PostsSpec.cfc.
• wheels test posts is a directory scope (tests.specs.posts) that matches neither generated directory on a fresh scaffold, and the generated specs are empty describe stubs — both filtered and unfiltered runs report 0 passed. Narrative rewritten to describe the directory-scope semantics and point at wheels test models / wheels test controllers.

command-line-tools/mcp-integration.mdx (mcp-02, mcp-04)

• Tool names are unprefixed in tools/list on 4.0.3 — re-verified live before editing: 18 tools, analyze … validate, no wheels_* prefix. Intro, "How it works", and the full tool table updated.
• Bare wheels mcp is intercepted by the LuCLI launcher (mcp: missing module name, exit 1) and never reaches the Module's snippet-printing help — the paragraph claiming it "prints the same snippet" now documents that and steers to the existing wheels mcp wheels --once tools/list smoke test.

Collateral non-guide fixes (manifest-sanctioned for mcp-02)

• cli/lucli/Module.cfc mcp() help text: "Tools are prefixed with the module name: wheels_generate, …" → unprefixed names. Output-string-only change; no CLI spec asserts the old string (grepped cli/lucli/tests/ + vendor/wheels/tests/specs/cli/).
• Root CLAUDE.md CLI/MCP section + Development Tools table: same prefix correction (live tool list inlined).

command-line-tools/wheels-commands/testing.mdx (testing-05)

• --verbose and --ci are accepted but currently inert: differential runs show byte-identical output vs a plain invocation, and exit codes are already non-zero on failure without --ci. Flag rows now describe current behavior and cite cli: wheels test --verbose and --ci have no observable effect — docs promise per-spec output and CI tightening #3113 (wiring fix); examples no longer model the inert flags.

Verification

• pnpm verify:docs exit 0 on each touched page (installation 1/1, quick-start 2/2, mcp-integration 0 tagged blocks, testing 1/1 tagged blocks passed).
• Live probes this session: wheels mcp wheels --once tools/list (18 unprefixed names), wheels --version, wheels version.
• Module.cfc change is help-text only; the stale local CLI harness (see CLI: commands flatten-and-reparse LuCLI args instead of reading argCollection directly (tech debt behind #2855) #2861-era notes) was not run — CI's CLI suite covers it.

Refs: #3113. Audit catalog: docs/superpowers/audits/2026-06-guide-audit-findings.md (P2).

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR aligns four CLI core guide pages (plus the mcp() help text and the root CLAUDE.md CLI/MCP section) with observed 4.0.3 behavior — unprefixed MCP tool names, real wheels --version / wheels version output shapes, directory-scope test filter semantics, and the inert --verbose/--ci flags. I verified every source-checkable claim against the repo and they all hold. Verdict: comment — no blocking findings, two minor staleness nits the diff leaves behind.

Verification notes (claims checked against source)

• --ci inert — confirmed: ciMode is parsed at cli/lucli/Module.cfc:732, threaded into runTests() (param at cli/lucli/Module.cfc:5095), and never read anywhere after that. #3113 is open and documents the byte-identical live runs for both flags.
• --verbose inert — the module does have display wiring (displayTestResults, cli/lucli/Module.cfc:5413-5424), but cli/CLAUDE.md documents that LuCLI reserves --verbose/-v at the launcher before the module sees them, and #3113's differential runs confirm no observable effect. The "accepted but currently inert" wording is accurate.
• Filter semantics — $normalizeTestFilter (cli/lucli/Module.cfc:754, 760–763) prepends tests.specs. in app mode, so posts → tests.specs.posts exactly as the rewritten quick-start says.
• Scaffold spec filenames — CodeGen.cfc::generateTest (cli/lucli/services/CodeGen.cfc:240-259) writes tests/specs/models/<Name>Spec.cfc and tests/specs/controllers/<Name>ControllerSpec.cfc; for a post scaffold that's PostSpec.cfc + PostsControllerSpec.cfc, no PostsSpec.cfc. The shipped templates (cli/src/templates/tests/model.txt / controller.txt) contain a describe with no it blocks, so the "0 passed on a fresh scaffold" claim holds.
• Bare wheels mcp interception — corroborated by cli/CLAUDE.md ("LuCLI reserves some tokens before the module sees them: … verbs like run/install/mcp").
• Module.cfc change — output-string only (out() calls at cli/lucli/Module.cfc:1387-1388); no cross-engine surface, and I confirmed no spec asserts the old help string.

Docs

1. Stale cross-reference left behind in cli/lucli/Module.cfc:319-323. The comment block above version() still reads: "Emits the three-line wheels --version format the installation guide documents (Wheels Module + LuCLI runtime + JVM). See web/sites/guides/.../command-line-tools/installation.mdx for the canonical output shape". This PR removes the three-line sample from installation.mdx and re-attributes the channel/Java lines to wheels version (not wheels --version), so the comment is now wrong on both the command name and the documented shape — the exact doc↔code drift #2431 was about. Since the PR already touches this file, suggest updating the comment in the same change (e.g. "Emits the wheels version output the installation guide documents — Wheels Module (+ channel), optional LuCLI runtime line, JVM").
2. (Optional, legacy) cli/tests/specs/e2e/McpToolsTest.cfc:29 and the spec title at line 152 ("prefixes tool names with module name (wheels_)") still tell the prefixed-name story. The assertion itself only checks module.json name == "wheels", so nothing fails — but it's now the last place in the CLI tree contradicting the corrected docs. The PR body's grep covered cli/lucli/tests/ but not the legacy cli/tests/ suite. Fine to defer given the suite is CommandBox-era legacy.

Tests

No new tests required — the only code change is a help-text string with no existing assertion on it (verified by grep across cli/lucli/tests/ and vendor/wheels/tests/).

Commits

Single commit conforms: type docs, header 98 chars, body lines under 100, DCO sign-off email matches the author (peter@alurium.com). ✓

Notes on unverifiable-from-source claims

The unprefixed tool names, the 18-tool count, the Wheels Version: 4.0.3 banner shape, and wheels system paths/env behavior live in the LuCLI launcher/runtime, which isn't in this repo — they rest on the PR's documented live probes against the released brew 4.0.3, which the PR body records in reproducible form. The 18-count is consistent with the module surface: 18 command functions remain after mcpHiddenTools() (cli/lucli/Module.cfc:178-197) exclusions, assuming the runtime also skips the convention functions (mcpHiddenTools, mcpToolSpecs) and the reserved version/showHelp verbs.

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: Re-review at head b936f3c08. The delta since my prior review (30f1163) is a single one-line commit fixing a malformed code fence in installation.mdx — the fix is correct, and everything verified in the prior pass still holds at this head. Verdict: comment — no blocking findings; the two minor staleness nits from the prior review remain open (both optional), and one of them turns out to be slightly stronger than I previously stated, though still non-blocking.

Correctness

No findings. The new commit's CommonMark claim is accurate: the info string of a backtick code fence may not contain backticks, so the old info string (which quoted wheels version in backticks) rendered the opening line as a literal paragraph and the intended closing fence opened a runaway block that swallowed the ## Troubleshooting heading. At this head the fence (web/sites/guides/src/content/docs/v4-0-0/command-line-tools/installation.mdx:216) is clean, matches the sibling fence at line 210, and the heading at line 227 sits outside any code block.

Spot re-verification at this head:

• $normalizeTestFilter (cli/lucli/Module.cfc:754, doc at 760–769) confirms the quick-start rewrite: app mode prepends tests.specs., so posts → tests.specs.posts.
• ciMode is parsed (cli/lucli/Module.cfc:732) and threaded into runTests() but never read — the "accepted but currently inert" wording in testing.mdx stands, and #3113 is the right tracking reference.
• No leftovers: wheels system env and the fictional LuCLI 0.3.7 sample have zero remaining matches under web/sites/guides/src/content/docs/v4-0-0/, .ai/, and CLAUDE.md. The only remaining wheels_*-prefixed tool references in guides are under v3-0-0/ (versioned historical docs — correct to leave untouched).
• The 18-row tool table in mcp-integration.mdx matches the 18-name list in the root CLAUDE.md CLI/MCP section exactly. (The unprefixed-name and banner-shape claims live in the LuCLI runtime outside this repo and rest on the PR's documented live probes, as noted in the prior review.)

Tests

Correction to my prior review, still non-blocking. I previously said the legacy cli/tests/specs/e2e/McpToolsTest.cfc only describes the prefixed-name story without asserting it. That was incomplete: cli/tests/specs/e2e/McpToolsTest.cfc:383-387 contains a real assertion —

it("documents tool naming convention (module prefix)", function() {
    expect(variables.moduleSource).toInclude("wheels_generate",
        "mcp() should document the wheels_ prefix naming convention"
    );
});

— where variables.moduleSource is a fileRead() of cli/lucli/Module.cfc (line 26), and this PR removes the last wheels_generate occurrence from that file. So the PR body's blanket "no CLI spec asserts the old string" is true only within its disclosed grep scope (cli/lucli/tests/ + vendor/wheels/tests/specs/cli/).

Why this is non-blocking: that suite demonstrably never runs and was already broken before this PR. The CI/CLI endpoint executes directory = "cli.lucli.tests.specs" only (vendor/wheels/public/views/clitests.cfm:14); no workflow under .github/ references cli/tests/; and McpToolsTest.cfc:362-366 expects 'lucli mcp wheels', a string with zero matches in Module.cfc at the base of this PR — a pre-existing failure that proves the suite is dead. Suggested follow-up (this PR or a separate chore): update or delete cli/tests/specs/e2e/McpToolsTest.cfc so the last in-repo artifact telling the prefixed-name story doesn't contradict the corrected docs.

Docs

1. (Carried over, still open, optional) cli/lucli/Module.cfc:320-324 — the comment above version() still reads "Emits the three-line wheels --version format the installation guide documents (Wheels Module + LuCLI runtime + JVM). See web/sites/guides/.../installation.mdx for the canonical output shape". After this PR the guide documents wheels --version as a one-liner + banner and attributes the channel/Java lines to wheels version, so the cross-reference is now wrong on both the command name and the shape. The code itself (lines 328–347) is fine — only the comment is stale.

Commits

Both commits conform to commitlint.config.js: type docs, headers 98 and 74 chars (≤ 100), bodies wrapped under 100, not ALL-CAPS, and DCO sign-offs (peter@alurium.com) match the author. The PR title equals the first commit header, so the squash-merge lint gate passes. ✓