docs(web/guides): document wheels upgrade apply verb across upgrade guides

[wheels-bot]

Three guide pages still described wheels upgrade as a check-only command with a manual vendor/wheels/ zip swap. After #3039 introduced wheels upgrade apply (the explicit swap verb with backup-by-default and a pre-swap recovery announcement), those pages were stale. This PR updates all three to document the full two-verb workflow.

Pages updated:

• command-line-tools/wheels-commands/upgrade.mdx — rewrote the frontmatter description and synopsis to cover both verbs; split the flags table to a check-specific section and added a new wheels upgrade apply section covering what it does, the pre-swap announcement, the backup convention, --to as an assertion, --nobackup, a typical upgrade example, and updated rollback instructions for both verbs; updated "What gets updated" from "Nothing" to document the apply swap with CLI upgrade instructions.
• start-here/release-channels.mdx — added wheels upgrade apply to the channel-switch sequence alongside wheels upgrade check --to=<version>.
• upgrading/3x-to-4x.mdx — extended the "Deprecating box wheels upgrade" code block to show check followed by apply.

Fixes #3045

Screenshots needed

None — all changes are text and CLI output.

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR updates three guide pages to document the wheels upgrade apply verb from #3039. The new content is largely faithful to the #3039 implementation (the pre-swap announcement block, safety-check list, --to-as-assertion, --nobackup semantics, and backup naming all verified accurate against cli/lucli/services/FrameworkUpgrader.cfc and runUpgradeApply() on the #3039 branch). However: the feature it documents is not merged — #3039 is open with changes requested, and a competing implementation #3040 has opposite bare-verb semantics — and the rewritten upgrade.mdx leaves three stale passages that contradict its own new sections, plus one sample-output block that doesn't match what the command actually prints. Verdict: request changes (submitted as a comment review — GitHub does not allow a changes-requested event on the bot's own PR). The PR is correctly in draft; the items below should be resolved before it leaves draft.

Correctness

1. Documents an unmerged, contested implementation. The PR body says "After #3039 introduced wheels upgrade apply…", but #3039 is OPEN with CHANGES_REQUESTED reviews, and #3040 ("add apply mode to wheels upgrade") is a competing open implementation in which bare wheels upgrade performs the destructive swap. This page asserts the exact opposite at upgrade.mdx:27:

   Calling wheels upgrade with no subcommand prints concise usage listing both verbs and exits 0.

   That sentence is only true under #3039. If #3040 lands instead, this line would tell users a destructive command is inert. Fix: keep this PR in draft until one implementation merges, then re-verify every behavioral claim (bare-verb behavior, flag spellings, output samples) against the merged surface before marking ready.

2. upgrade.mdx:139-141 — swap-summary sample shows output the command never prints. The doc shows:

   3.5.1 -> 4.0.2
   Backed up to: vendor/wheels.bak-20260611-141502
   

   The #3039 implementation prints Framework upgraded: 3.5.1 -> 4.0.2, Backup: <absolute path>, and a Recover with: rm -rf … && mv … line (runUpgradeApply() in cli/lucli/Module.cfc on the #3039 branch; pinned by UpgradeApplyCommandSpec.cfc:208, which asserts the literal Framework upgraded:). "Illustrative" covers placeholder paths/versions, not invented label text — the adjacent pre-swap block (lines 131–135) reproduces the real strings exactly, so this one should too. Fix: mirror the actual output, including the Recover with: line.

3. upgrade.mdx:82 and upgrade.mdx:93 — stale check sample output. Both sample blocks still end with Upgrade with: brew upgrade wheels. #3039 changes that exact output line to Apply with: wheels upgrade apply (with a code comment noting brew upgrade wheels "only updates the CLI binary, never the app's vendored framework copy"). As written, the samples contradict this page's own "What gets updated" section (lines 167–177). Fix: update both sample blocks to Apply with: wheels upgrade apply when re-verifying against the merged implementation.

4. upgrade.mdx:46 — Prerequisites still describes the manual-swap workflow.

   Commit first. The scanner is read-only, but the actual upgrade (brew upgrade wheels, a fresh vendor/wheels/ drop-in, etc.) will replace framework code.

   The "fresh vendor/wheels/ drop-in" / brew upgrade wheels framing is exactly what issue #3045 asked to remove, and brew upgrade wheels does not replace framework code per this page's own new sections. Fix: name wheels upgrade apply as the thing that replaces framework code.

Docs

5. Unknown-subcommand behavior dropped (upgrade.mdx:27). The old sentence covered "any subcommand other than check"; the new one only covers the bare invocation. Under #3039 a typo'd verb (wheels upgrade chekc) deliberately hard-errors non-zero rather than printing usage and exiting 0 (the dispatch comment in upgrade() calls this out explicitly so scripts fail loudly). Worth one sentence, since "prints usage and exits 0" could otherwise be read as covering typos too. Minor.

What checks out

• Pre-swap announcement block (upgrade.mdx:131-135) matches the implementation string-for-string (Backing up vendor/wheels -> vendor/<backup>, If this is interrupted, restore with:, the rm -rf … && mv … one-liner built from the reserved path).
• Safety-check list (upgrade.mdx:144-147) accurately summarizes FrameworkUpgrader.looksLikeWheelsFramework() (source+target sniff), the source==target canonical-path refusal, and the missing-vendor/wheels/ refusal.
• --to documented as an assertion, not a download trigger (upgrade.mdx:153) — matches the hard error in runUpgradeApply() when the bundled version differs.
• --nobackup (upgrade.mdx:154) is the documented spelling in the implementation; delete-before-copy semantics match applyUpgrade().
• release-channels.mdx and 3x-to-4x.mdx edits are accurate under #3039, and dropping the redundant brew upgrade wheels immediately after brew install in 3x-to-4x.mdx is an improvement.
• Changelog fragment changelog.d/3045-upgrade-apply-docs.changed.md follows the fragment convention (no direct CHANGELOG.md edit). ✓
• Single commit docs(web/guides): document wheels upgrade apply verb across upgrade guides conforms to commitlint (valid type, subject under 100 chars). ✓

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: Re-review at head b54aeba8f. Since the previous review, #3039 has merged into develop (52be83e18), this branch merged develop in, and the head commit resolves all four accuracy items plus the docs nit from the previous round. I re-verified every behavioral claim in the rewritten upgrade.mdx line-by-line against the merged implementation in cli/lucli/Module.cfc and cli/lucli/services/FrameworkUpgrader.cfc — the page is now faithful to what shipped. One new minor docs nit below (the help verb), nothing blocking. Verdict: comment.

Previously-flagged findings — all resolved

1. Documents an unmerged, contested implementation — resolved. #3039 merged as 52be83e18 (feat(cli): wheels upgrade applies the framework swap from the CLI bundle); the competing #3040 semantics did not land (bare wheels upgrade is inert per Module.cfc:2941-2943, exactly as upgrade.mdx:27 says). The PR also correctly left draft only after the merge.
2. Swap-summary sample showed invented label text — resolved. upgrade.mdx:140-144 now prints Framework upgraded: 3.5.1 -> 4.0.2, Backup: …, and the Recover with: rm -rf … && mv … line, matching runUpgradeApply() at Module.cfc:4990-4996 string-for-string.
3. Stale Upgrade with: brew upgrade wheels in both check samples — resolved. Both blocks (upgrade.mdx:82, upgrade.mdx:94) now end with Apply with: wheels upgrade apply, which runUpgradeCheck() prints unconditionally in human mode before any throw (Module.cfc:4844-4848). The same-major sample's Same major version — no known breaking changes. / Scanning for opt-in recommendations... lines match Module.cfc:4384-4385 exactly.
4. Prerequisites still described the manual-swap workflow — resolved. upgrade.mdx:46 now names wheels upgrade apply as the thing that replaces framework code and correctly notes brew upgrade wheels only updates the CLI binary.
5. Unknown-subcommand behavior undocumented (minor, previous round) — resolved. upgrade.mdx:27 now documents that a typo'd verb prints usage and hard-errors non-zero, matching the deliberate throw at Module.cfc:2951-2958.

Verified accurate against the merged implementation

• Pre-swap announcement block (upgrade.mdx:132-136) matches Module.cfc:4961-4963 exactly.
• Refusal behavior (upgrade.mdx:146): validateSwap() runs before the plan is announced (Module.cfc:4941-4945), so a refusal prints no backup path and no restore command — as documented.
• Safety-check list (upgrade.mdx:148-151): framework sniff on source and target (FrameworkUpgrader.cfc:115-116,150-152), source==target canonical-path refusal naming the wheels-repo-checkout case (FrameworkUpgrader.cfc:137-139), missing-vendor/wheels/ refusal (Module.cfc:4901-4908).
• --to as assertion, not download trigger (upgrade.mdx:157): hard error when the bundled version differs (Module.cfc:4923-4932).
• --nobackup delete-before-copy (upgrade.mdx:158): directoryDelete() before the copy (FrameworkUpgrader.cfc:213).
• Backup naming vendor/wheels.bak-<yyyymmdd>-<HHmmss> (FrameworkUpgrader.cfc:250-258) matches every sample path.
• Bare wheels upgrade prints a usage steer listing both verbs and exits 0 ($printUpgradeUsageSteer(), Module.cfc:3053-3066).
• scoop update wheels (upgrade.mdx:179) is the spelling the implementation itself suggests (Module.cfc:4926).
• release-channels.mdx and 3x-to-4x.mdx edits accurately reflect the merged two-verb workflow.

Docs

• Minor: upgrade.mdx:27 says "Any other subcommand — a typo like wheels upgrade chekc — prints the usage and then hard-errors with a non-zero exit." That's overbroad by one case: wheels upgrade help (and -h) is a recognized verb that prints full usage and exits 0 (parseUpgradeArgs sets wantsHelp for sub == "help", Module.cfc:2871; short-circuit at Module.cfc:2927-2929). The bare-invocation steer even tells users to run wheels upgrade help. Suggest: "Any other subcommand (apart from help) — a typo like wheels upgrade chekc — …" or a one-line mention that wheels upgrade help prints full usage. Not blocking.

Commits

• 623de1faf docs(web/guides): document wheels upgrade apply verb across upgrade guides ✓ and b54aeba8f docs(web/guides): fix four review accuracy items against the merged upgrade apply implementation ✓ — both conform to commitlint (valid type, header ≤ 100 chars). The intermediate Merge remote-tracking branch … commit is commitlint-exempt as a merge commit.

Docs & metadata

• Changelog fragment changelog.d/3045-upgrade-apply-docs.changed.md follows the fragment convention; no direct CHANGELOG.md edit. ✓