docs(web/guides): document wheels-websockets package; correct legacy ForgeBox guidance

[bpamiri]

What / why

Two verified-stale docs truth-ups in the v4-0-0 guides:

A) WebSocket story (Refs #3292) — digging-deeper/channels.mdx still said "Wheels does not
ship WebSocket support" and pointed readers at roadmap issue #2962; server-sent-events.mdx
said "Wheels itself ships no WebSocket layer" with no alternative. The first-party
wheels-websockets package shipped at v0.2.0
and is installable via wheels packages add wheels-websockets (registry entry merged
wheels-dev/wheels-packages#13). Both pages now document the package — engine matrix (RustCFML
native since v0.1.0; Lucee 6.2+ verified live; Lucee 7 needs 7.0.2.7+ and a jakarta-compatible
websocket-extension release that isn't published yet; Adobe/BoxLang demand-gated on discussion
#3286), graceful SSE fallback, and the WheelsRealtime client's automatic WheelsSSE
fallback — instead of denying it exists. This brings both pages in line with
start-here/why-wheels.mdx, which already says WebSocket support is available.

B) Legacy ForgeBox slugs (Refs #3182) — start-here/installing-with-commandbox.mdx claimed
cfwheels-base-template "still resolves on ForgeBox but errors on its missing cfwheels core
dependency". The slug is now fully unlisted: box install cfwheels-base-template fails with
entry slug invalid or does not exist. The Aside now says so, and the old-to-new slug mapping
gains a cfwheels-cli entry pointing readers at the standalone wheels CLI (noting the renamed
wheels-cli ForgeBox slug is itself the deprecated legacy CommandBox module).

Docs are carefully worded per the assessment risks: stock Lucee 7 is NOT claimed to work (Lucee
6.2 is the verified stock path), and Adobe/BoxLang SSE-only degradation is stated explicitly.

Approach

Facts cross-checked against the wheels-dev/wheels-websockets README (v0.2.0) and the issue
assessments. Acceptance check: grep -ri "does not ship WebSocket" web/sites/guides and
grep -ri "still resolves on ForgeBox" web/sites/guides both return nothing; channels.mdx names
the package and install command.

Test evidence

Docs-only change — three .mdx files under web/sites/guides/; zero executable code paths
touched (no vendor/wheels/, app/, or cli/ changes), so the core suite does not apply per
the repo test matrix. The core suite could not be run locally regardless: the orchestrator-mandated
PORT=0 is rejected by the CLI ("Cannot start server - port conflicts detected") and other ports
were off-limits to this agent. The guides site build in CI validates the MDX.

Residual scope (this PR closes neither issue)

• package: wheels-websockets — opt-in realtime WS transport (RustCFML native, Lucee emulated) #3292: maintainer close-out remains — tick the P1 checkbox, close citing wheels-websockets
  v0.2.0 + registry PR Issue 784 #13, and re-home the live external dependencies (jakarta websocket-extension
  release watch, RustCFML channel-dir ask, LuCLI#8 bundled-engine bump) so they aren't lost.
• Legacy ForgeBox entries (cfwheels-base-template, cfwheels-cli) are broken and unsignposted — box install cfwheels-base-template hard-errors on the deleted cfwheels slug #3182: the credentialed ForgeBox runbook remains — manual box publish of deprecation
  revisions to the cfwheels-cli slug from the wheels-dev account (op://Wheels/ secrets), plus the
  optional cfwheels.org apex DNS record. Only a maintainer can execute those.

Refs #3292, Refs #3182

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — This is a docs-only truth-up of three v4-0-0 guide pages: it documents the first-party wheels-websockets package in channels.mdx / server-sent-events.mdx (replacing the stale "Wheels does not ship WebSocket support" claim), and corrects the ForgeBox legacy-slug guidance in installing-with-commandbox.mdx. The diff is clean, internally consistent, and well-worded. Verdict: comment (approve-quality on everything I can verify; the only reason I stop short of approve is that the external wheels-websockets engine-support matrix lives in another repo and I cannot independently verify it).

Correctness

No code paths touched — three .mdx files only. Verified the mechanical correctness of the internal references:

• Anchor #not-supported-via-commandbox-the-wheels-cli-feature-set resolves to the real heading ## Not supported via CommandBox: the + "wheels" + CLI feature set (installing-with-commandbox.mdx:101).
• Anchor #supported-install-the-framework resolves to ## Supported: install the framework (line 46).
• Links /v4-0-0/start-here/installing/ and /v4-0-0/digging-deeper/channels/ point at existing pages, and the trailing-slash style matches the 15+ other internal links in the same file.
• grep confirms no stale does not ship WebSocket / still resolves on ForgeBox text remains; the surviving "framework core ships no WebSocket layer" wording in server-sent-events.mdx:33 is the intended, correctly-qualified replacement.
• The new claim is consistent with start-here/why-wheels.mdx:101 ("WebSocket support is available").

Conventions

• The install snippet uses the canonical CLI verb wheels packages add wheels-websockets (matches CLAUDE.md Package System — add is the canonical verb). Good.
• Minor, non-blocking nit: the code fence is titled title="illustrative — install the package", but the command itself is real and correct, not illustrative. Consider title="install the package" (or dropping the label) so readers do not read the working command as pseudo-code. Not a blocker.

Docs

• Docs-only docs-type change — no changelog.d/ fragment required (fragments are for user-facing fix/feat). Correct to omit.
• Engine matrix, SSE-fallback behavior, and version claims (RustCFML native since v0.1.0; Lucee 6.2+ verified; Lucee 7 gated on 7.0.2.7+ / jakarta extension; Adobe/BoxLang SSE-only) are appropriately hedged and, per the PR body, cross-checked against the wheels-websockets v0.2.0 README. I cannot verify these against the external repo from here, so flagging as the one unverified surface — recommend a maintainer familiar with the package confirm the matrix before merge. No wording concern: the claims are carefully scoped (stock Lucee 7 is explicitly NOT claimed to work).

Commits

docs(web/guides): document wheels-websockets package; correct legacy ForgeBox guidance — valid type, sensible monorepo scope, header well under 100 chars, not ALL-CAPS. Conforms to commitlint.

No blocking findings. Once a maintainer confirms the external engine matrix, this is ready to merge.