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

bpamiri · claude · web-flow · commit bb98ffecd820 · 2026-06-12T09:18:51.000-07:00
* docs(web/guides): correct start-here guide drift from the 2026-06 behavioral audit Six audit findings across the non-tutorial start-here pages (audit group p2-1, claims index-01 / welcome-01 / whywheels-01 / installing-03 / rc-01 / engines-04): - index.mdx: add the missing Release Channels LinkCard to the section grid - welcome.mdx: include BoxLang in the supported-engine list (matches cfml-engines.mdx and the CI compat matrix) - why-wheels.mdx: the Rails Jobs row cited a nonexistent worker CLI (wheels jobs work); describe the real programmatic surface and cite ##3090 for the worker CLI - installing.mdx: drop the 3x stale 'Multiple version surfaces during 4.0-SNAPSHOT' asides (4.0 GA shipped 2026-06-09) - release-channels.mdx: the channel parenthetical comes from 'wheels version' (Wheels 4.0.3 (stable) + Java line), not 'wheels --version' (no channel info); fix the at-a-glance row and the how-to-tell sample, verified against the released 4.0.3 CLI - cfml-engines.mdx: 'generators are pure file-system operations' gains the 'wheels generate admin' exception (requires a running project-bound server; Module.cfc write-side guard) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Peter Amiri <peter@alurium.com> * docs(web/guides): scope the --version channel claim by install method The unqualified 'no channel parenthetical' note was wrong for two shipped install paths: the deb/rpm wrapper and the Homebrew bleeding-edge formula both short-circuit --version and print 'wheels <version> (<channel>)'. Reviewer-supplied wording; the installation.mdx cross-page sync rides with the cliref audit group. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Peter Amiri <peter@alurium.com> --------- Signed-off-by: Peter Amiri <peter@alurium.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
diff --git a/web/sites/guides/src/content/docs/v4-0-0/start-here/cfml-engines.mdx b/web/sites/guides/src/content/docs/v4-0-0/start-here/cfml-engines.mdx
@@ -68,7 +68,7 @@ Two routes, depending on what you already have installed.
 If you already have Adobe CF installed (e.g. the dev edition from [coldfusion.adobe.com](https://www.adobe.com/products/coldfusion-family.html)), point its web root at your Wheels app's `public/` directory and configure the datasource through the CF Administrator. The framework requires no engine-specific setup beyond having a registered datasource.
 
 <Aside type="note">
-The `wheels start`, `wheels stop`, `wheels reload`, and `wheels test` commands all assume the Lucee Express bundled with the CLI. On Adobe CF you'll use `box server start/stop/restart` instead, and reload via `?reload=true&password=<your-password>` directly. Generators (`wheels generate ...`) are pure file-system operations and work the same regardless of engine.
+The `wheels start`, `wheels stop`, `wheels reload`, and `wheels test` commands all assume the Lucee Express bundled with the CLI. On Adobe CF you'll use `box server start/stop/restart` instead, and reload via `?reload=true&password=<your-password>` directly. Generators (`wheels generate ...`) are pure file-system operations and work the same regardless of engine — with one exception: `wheels generate admin` introspects your database schema through a running server bound to the project, and refuses to run without one.
 </Aside>
 
 ## Running Wheels on BoxLang
@@ -82,7 +82,7 @@ box server start cfengine=boxlang@latest port=8080
 ```
 
 <Aside type="note">
-The `wheels start`, `wheels stop`, `wheels reload`, and `wheels test` commands all assume the Lucee Express bundled with the CLI — they do not interact with BoxLang. BoxLang developers manage their server through CommandBox (`box server start/stop/restart`) and reload via `?reload=true&password=<your-password>` directly. Generators (`wheels generate ...`) are pure file-system operations and work the same regardless of engine.
+The `wheels start`, `wheels stop`, `wheels reload`, and `wheels test` commands all assume the Lucee Express bundled with the CLI — they do not interact with BoxLang. BoxLang developers manage their server through CommandBox (`box server start/stop/restart`) and reload via `?reload=true&password=<your-password>` directly. Generators (`wheels generate ...`) are pure file-system operations and work the same regardless of engine — with one exception: `wheels generate admin` introspects your database schema through a running server bound to the project, and refuses to run without one.
 </Aside>
 
 Wheels' BoxLang compatibility is verified per release in the same CI matrix as Lucee and Adobe CF. Cross-engine gotchas worth knowing about live in [`.ai/wheels/cross-engine-compatibility.md`](https://github.com/wheels-dev/wheels/blob/develop/.ai/wheels/cross-engine-compatibility.md) — most are about minor differences in struct/array semantics under closures.
diff --git a/web/sites/guides/src/content/docs/v4-0-0/start-here/index.mdx b/web/sites/guides/src/content/docs/v4-0-0/start-here/index.mdx
@@ -15,6 +15,7 @@ The entry path for new Wheels developers. Follow it top to bottom.
   <LinkCard title="Why Wheels?" href="/v4-0-0/start-here/why-wheels/" />
   <LinkCard title="Installing Wheels" href="/v4-0-0/start-here/installing/" />
   <LinkCard title="Your First 15 Minutes" href="/v4-0-0/start-here/first-15-minutes/" />
+  <LinkCard title="Release Channels" href="/v4-0-0/start-here/release-channels/" />
   <LinkCard title="Tutorial: Build a Blog" href="/v4-0-0/start-here/tutorial/" />
   <LinkCard title="CFML Engines" href="/v4-0-0/start-here/cfml-engines/" />
 </CardGrid>
diff --git a/web/sites/guides/src/content/docs/v4-0-0/start-here/installing.mdx b/web/sites/guides/src/content/docs/v4-0-0/start-here/installing.mdx
@@ -105,10 +105,6 @@ The two are mutually exclusive — both expose the `wheels` binary. You install
 
    You should see a `Wheels Version: <version>` line followed by ASCII art. A `Lucee Version: <version>` line may also appear once Lucee Express has been downloaded (typically on first `wheels start`). Any non-empty version output means the CLI is wired up correctly.
 
-   <Aside type="note" title="Multiple version surfaces during 4.0-SNAPSHOT">
-   During the 4.0 pre-release, three places report a Wheels version: the package-manager formula (e.g. `brew info wheels`), `wheels --version` (CLI runtime), and the dev-mode debug bar shown on every rendered page (framework). They may currently disagree — the framework still reports `0.0.0-dev` even when the CLI reports a real version. This is tracked and will converge before 4.0 GA. If your CLI version output is non-empty and roughly matches the formula, your install is fine.
-   </Aside>
-
 </Steps>
 
 </TabItem>
@@ -155,10 +151,6 @@ The legacy `wheels` package on chocolatey.org is the CommandBox-based v1.x relea
 
    You should see a `Wheels Version: <version>` line followed by ASCII art. A `Lucee Version: <version>` line may also appear once Lucee Express has been downloaded (typically on first `wheels start`). Any non-empty version output means the CLI is wired up correctly.
 
-   <Aside type="note" title="Multiple version surfaces during 4.0-SNAPSHOT">
-   During the 4.0 pre-release, three places report a Wheels version: the package-manager formula (e.g. `brew info wheels`), `wheels --version` (CLI runtime), and the dev-mode debug bar shown on every rendered page (framework). They may currently disagree — the framework still reports `0.0.0-dev` even when the CLI reports a real version. This is tracked and will converge before 4.0 GA. If your CLI version output is non-empty and roughly matches the formula, your install is fine.
-   </Aside>
-
 </Steps>
 
 Pick LuCLI and Wheels Module versions that are known to be paired — see [CLI Installation → Manual JAR install](/v4-0-0/command-line-tools/installation/#manual-jar-install) for the canonical version-pairing source.
@@ -217,10 +209,6 @@ The apt and yum repos are GPG-signed with the Wheels Distribution key (fingerpri
 
    You should see a `Wheels Version: <version>` line followed by ASCII art. A `Lucee Version: <version>` line may also appear once Lucee Express has been downloaded (typically on first `wheels start`). Any non-empty version output means the CLI is wired up correctly.
 
-   <Aside type="note" title="Multiple version surfaces during 4.0-SNAPSHOT">
-   During the 4.0 pre-release, three places report a Wheels version: the package-manager formula (e.g. `brew info wheels`), `wheels --version` (CLI runtime), and the dev-mode debug bar shown on every rendered page (framework). They may currently disagree — the framework still reports `0.0.0-dev` even when the CLI reports a real version. This is tracked and will converge before 4.0 GA. If your CLI version output is non-empty and roughly matches the formula, your install is fine.
-   </Aside>
-
 </Steps>
 
 </TabItem>
diff --git a/web/sites/guides/src/content/docs/v4-0-0/start-here/release-channels.mdx b/web/sites/guides/src/content/docs/v4-0-0/start-here/release-channels.mdx
@@ -20,26 +20,30 @@ Wheels ships on two parallel channels. Pick the one that matches how much churn
 | Source repo | [`wheels-dev/wheels`](https://github.com/wheels-dev/wheels) | [`wheels-dev/wheels-snapshots`](https://github.com/wheels-dev/wheels-snapshots) |
 | Best for | Production apps, teams that want predictability | Framework contributors, early adopters, validating fixes before they GA |
 | Version string shape | `4.0.0`, `4.1.0` | `4.0.1-snapshot.1700` |
-| `wheels --version` reports | `(stable)` | `(bleeding-edge)` |
+| `wheels version` reports | `(stable)` | `(bleeding-edge)` |
 
 ## How to tell which channel you're on
 
 ```bash title="your shell"
-wheels --version
+wheels version
 ```
 
 The output's parenthetical tells you the channel:
 
 ```
-Wheels Version: 4.0.0 (stable)
+Wheels 4.0.3 (stable)
+Java 21.0.11
 ```
 
 …or:
 
 ```
-Wheels Version: 4.0.0-snapshot.1787 (bleeding-edge)
+Wheels 4.0.0-snapshot.1787 (bleeding-edge)
+Java 21.0.11
 ```
 
+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.
+
 If you see `(development)` instead, you're running from a dev checkout (cloned source repo) rather than an installed package — which is its own thing and not covered here.
 
 ## Installing each channel
diff --git a/web/sites/guides/src/content/docs/v4-0-0/start-here/welcome.mdx b/web/sites/guides/src/content/docs/v4-0-0/start-here/welcome.mdx
@@ -22,7 +22,7 @@ A two-minute orientation before you write any code.
 
 ## What Wheels is
 
-Wheels is a full-stack web framework for CFML. It runs on Lucee (open source) and Adobe ColdFusion (commercial). It gives you an ActiveRecord-style ORM, a request pipeline with middleware, a convention-driven file layout, and a scaffold generator that writes working code from a model name. You spend your time on the interesting parts of your app.
+Wheels is a full-stack web framework for CFML. It runs on Lucee (open source), Adobe ColdFusion (commercial), and BoxLang. It gives you an ActiveRecord-style ORM, a request pipeline with middleware, a convention-driven file layout, and a scaffold generator that writes working code from a model name. You spend your time on the interesting parts of your app.
 
 The `wheels` CLI is the only tool you need. It creates apps, runs migrations, generates scaffolds, starts the dev server, runs tests, and ships your code. Under the hood it wraps a Java-based CFML runtime; you rarely think about that.
 
diff --git a/web/sites/guides/src/content/docs/v4-0-0/start-here/why-wheels.mdx b/web/sites/guides/src/content/docs/v4-0-0/start-here/why-wheels.mdx
@@ -43,7 +43,7 @@ Closest conceptual neighbor. Both descended from the same Rails-era design.
 | View layer | ERB / Haml / etc. | `.cfm` templates (inline expressions via `#...#`) |
 | Hotwire | Bundled (Turbo Drive / Frames / Streams) | Via `wheels-hotwire` package (opt-in activation) |
 | Testing | Minitest / RSpec | WheelsTest (BDD, `describe`/`it`) |
-| Jobs | Active Job + Sidekiq/etc. | Built-in job queue (`wheels jobs work`) |
+| Jobs | Active Job + Sidekiq/etc. | Built-in DB-backed job queue (`wheels.Job` / `processQueue()`); worker CLI tracked in [#3090](https://github.com/wheels-dev/wheels/issues/3090) |
 
 If you know Rails, the tutorial will feel familiar in pacing and idioms. The differences that bite most often:
 
