docs(web/guides): correct start-here guide drift from the 2026-06 behavioral audit

[bpamiri]

Final-wave docs fixes from the 2026-06 guide behavioral audit — manifest group 1 (start-here, non-tutorial). Six findings, six files, all under web/sites/guides/src/content/docs/v4-0-0/start-here/. Every fix describes verified current behavior of the released 4.0.3 CLI / framework.

Fixes

Claim	File	Fix
index-01	index.mdx	The section grid listed 6 of 7 pages — added the missing Release Channels LinkCard (placed per sidebar order 5).
welcome-01	welcome.mdx	"Runs on Lucee and Adobe ColdFusion" omitted BoxLang, contradicting cfml-engines.mdx (Production-supported: Yes) and the CI compat matrix (compat-matrix.yml engines incl. boxlang).
whywheels-01	why-wheels.mdx	The Rails-comparison Jobs row cited wheels jobs work, which does not exist (Module.cfc has no jobs function; released 4.0.3 errors "has no function with name [jobs]"). Now describes the real surface — built-in DB-backed queue via wheels.Job / processQueue() — and cites #3090 for the worker CLI.
installing-03	installing.mdx	Removed the 3 identical "Multiple version surfaces during 4.0-SNAPSHOT" asides ("will converge before 4.0 GA") — 4.0 GA shipped 2026-06-09; the pre-release framing is stale. The surrounding "any non-empty version output means the CLI is wired up" guidance stands on its own.
rc-01	release-channels.mdx	The channel parenthetical comes from wheels version, not wheels --version. Verified against the released CLI: wheels --version → Wheels Version: 4.0.3 + ASCII art, no channel; wheels version → Wheels 4.0.3 (stable) + Java 21.0.11. Fixed the at-a-glance row, the "How to tell" command + samples, and added a note distinguishing the two forms.
engines-04	cfml-engines.mdx	"Generators are pure file-system operations" now carries the one exception: wheels generate admin introspects the project schema through a running project-bound server and refuses to run without one (Module.cfc write-side guard / $requireRunningServer(requireProjectConfig=true)). Applied to both the Adobe CF and BoxLang asides.

Verification

• pnpm verify:docs run per touched page from web/sites/guides — all exit 0 (installing.mdx's {test:cli} block: 1 passed).
• wheels version / wheels --version output shapes re-confirmed live against brew wheels 4.0.3 before documenting.

Evidence source: P2 audit manifest (/tmp/p2-docs-manifest.md, group 1) + verifier evidence in the audit task output; catalog at docs/superpowers/audits/2026-06-guide-audit-findings.md.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR fixes six verified drift findings in the start-here guides from the 2026-06 behavioral audit. Five of the six fixes check out cleanly against the code — each claim verified at its source (Module.cfc, the CI compat matrix, CLAUDE.md / issue 3090, sidebar frontmatter). One fix introduces a new piece of drift while removing the old one: the added note in release-channels.mdx claims wheels --version shows no channel parenthetical, but two in-repo distribution sources (the Linux deb/rpm wrapper and the Homebrew bleeding-edge formula) print exactly that parenthetical from --version. Verdict: request changes — one small, well-scoped wording fix.

Correctness

web/sites/guides/src/content/docs/v4-0-0/start-here/release-channels.mdx:45 — the absolute "no channel parenthetical" claim about wheels --version is wrong for two documented install paths.

The added note reads:

Note the command is wheels version (no dashes). The flag form wheels --version prints a Wheels Version: <version> line plus ASCII art, with no channel parenthetical.

That matches the Homebrew stable install the PR was verified against (LuCLI absorbs the flag and prints its banner — consistent with command-line-tools/installation.mdx:248: "LuCLI handles that flag before dispatching to the module"). But it is contradicted by the packaging sources in this repo:

• deb/rpm wrapper — tools/distribution-drafts/linux-packages/build-linux-packages.sh generates the /usr/bin/wheels wrapper, which short-circuits --version / -v: it reads the channel from /opt/wheels/.channel (defaulting to stable) and prints a single line of the form wheels <installed-version> (<channel>) — channel included, and no ASCII art either. This is shipped behavior, not a draft artifact: command-line-tools/installation.mdx:71 documents /opt/wheels/.channel being "read by the wrapper for wheels --version", and the wrapper comment cites issue 2700 (a live bug where missing stamp files made --version print "unknown (stable)").
• Homebrew bleeding-edge formula — tools/distribution-drafts/homebrew/wheels-be.rb:101-102 short-circuits the same flags and prints wheels <version> (bleeding-edge), and the formula test (lines 155-156) asserts that bleeding-edge appears in wheels --version output. So a bleeding-edge brew user — the exact audience of the page sample showing (bleeding-edge) — sees the channel right there in --version, directly contradicting the note.

The core fix on this page is right and should stay: wheels version (the subcommand, cli/lucli/Module.cfc:328) always appends the channel tag and is the reliable form on every install. Only the unqualified negative in the note needs scoping. Suggested replacement for line 45:

Note the command is wheels version (no dashes). The flag form wheels --version varies by install method — Homebrew stable and manual JAR installs print a Wheels Version: <version> banner plus ASCII art with no channel, while the apt/yum and Homebrew bleeding-edge package wrappers print a one-line wheels <version> (<channel>). wheels version is the form that reports the channel reliably everywhere.

Whichever wording lands, note that command-line-tools/installation.mdx:194 currently attributes the channel parenthetical to wheels --version for all packaged installs — the follow-up audit group covering command-line-tools should be synced to the same story so the two pages stop contradicting each other.

Docs

Non-blocking observations (no change requested in this PR):

• All five other fixes verified clean: the wheels generate admin exception matches the write-side guard at cli/lucli/Module.cfc:3636 (requireRunningServer with requireProjectConfig set to true); the Jobs-row fix matches reality (Module.cfc has no jobs function; the worker CLI is issue 3090); BoxLang in welcome.mdx matches cfml-engines.mdx and the CI compat matrix; the Release Channels LinkCard placement matches its sidebar order 5 frontmatter; and the removed 4.0-SNAPSHOT asides are clearly stale post-GA, with the surrounding steps intact.
• The doc comment above the version function at cli/lucli/Module.cfc:320 still says it emits "the three-line wheels --version format" — it is actually the wheels version subcommand, the very confusion this PR untangles. Worth a one-line cleanup in a future code PR.

Commits

Single commit — docs(web/guides): correct start-here guide drift from the 2026-06 behavioral audit — valid type, header under 100 chars, subject explains the why. No changelog fragment needed for a docs change.

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: Re-review at head 535ec20d5. The previous round's single blocking finding — the unqualified claim that wheels --version shows no channel parenthetical — is resolved by the new commit, which scopes the claim by install method. I re-verified every clause of the rewritten note against the actual packaging sources (including the external Homebrew tap), and the five other audit fixes remain verified clean. Verdict: approve — this supersedes my earlier CHANGES_REQUESTED review on 77a2c4405, which is now fully addressed.

Previously blocking finding — resolved

release-channels.mdx:45 — "wheels --version prints … no channel parenthetical" (absolute claim, contradicted by the deb/rpm wrapper and Homebrew bleeding-edge formula).

Resolved by 535ec20d5 ("docs(web/guides): scope the --version channel claim by install method"). The note now reads:

The flag form wheels --version varies by install method — Homebrew stable and manual JAR installs print a Wheels Version: <version> banner plus ASCII art with no channel, while the apt/yum and Homebrew bleeding-edge package wrappers print a one-line wheels <version> (<channel>). wheels version is the form that reports the channel reliably everywhere.

Each clause verified against source in this session:

• apt/yum wrapper includes the channel — tools/distribution-drafts/linux-packages/build-linux-packages.sh (wrapper --version|-v case): echo "wheels ${INSTALLED_VERSION} (${CHANNEL})", channel read from /opt/wheels/.channel defaulting to stable. ✓
• Homebrew bleeding-edge includes the channel — tools/distribution-drafts/homebrew/wheels-be.rb:101-102: echo "wheels #{version} (bleeding-edge)"; the formula test (lines 155-156) asserts bleeding-edge appears in wheels --version output. ✓
• Homebrew stable shows no channel — verified against the live tap (wheels-dev/homebrew-wheels Formula/wheels.rb, --version|-v short-circuit): prints Wheels Version: $ver, ASCII art, and the homepage URL — no channel anywhere in the block. ✓
• wheels version reports the channel reliably everywhere — cli/lucli/Module.cfc:328-333 always appends the channel tag, and cli/lucli/services/ReleaseChannel.cfc::classify() returns a named channel for every version shape (development / release-candidate / bleeding-edge / stable fallback), so the parenthetical never goes missing. The page's existing (development) caveat matches the classify() dev-checkout branch. ✓

The at-a-glance table row and both sample blocks were already corrected in the first commit and stand.

Docs

Non-blocking observations, no change requested:

• The five other audit fixes re-confirmed clean: the wheels generate admin exception matches the write-side guard at cli/lucli/Module.cfc:3636 ($requireRunningServer(... requireProjectConfig = true), with the schema-introspection rationale in the adjacent comment); the Jobs-row fix matches reality (no jobs function in Module.cfc; worker CLI tracked in #3090); BoxLang in welcome.mdx matches cfml-engines.mdx and the CI compat matrix; the Release Channels LinkCard placement in index.mdx matches its order: 5 sidebar frontmatter (between First 15 Minutes at 4 and CFML Engines at 6); the removed 4.0-SNAPSHOT asides in installing.mdx are stale post-GA, with the surrounding steps intact.
• Carried over from the previous round: the doc comment above version() at cli/lucli/Module.cfc:320 still says it emits "the three-line wheels --version format" — it is the wheels version subcommand. Worth a one-line cleanup in a future code PR.
• New, external-repo: the stable tap formula's per-subcommand help (wheels-dev/homebrew-wheels Formula/wheels.rb, the version) help case) says wheels version is "Same as 'wheels --version'" — which this PR now correctly documents as not the same on that install. Out of scope here; flagging for whoever next touches the tap.

Commits

Two commits, both docs(web/guides): ... — valid type, headers under 100 chars, subjects state the why. Docs-only change, so no changelog fragment is required.