docs(web/guides): add What's New in 4.0 and URL Rewriting, fix vm-deployment recipe (restructure phase 5)

[bpamiri]

Summary

Phase 5 of the guides restructure driven by discussion #1838 (follows #3275–#3278): upgrade & orientation completion. Two new pages, a repaired VM deploy recipe, the ForgeBox disambiguation, and three Glossary corrections. The Upgrading & Releases group promoted in Phase 1 is now fully populated.

New pages

• What's New in 4.0 (upgrading/whats-new-in-4) — the fast-track feature tour welcome.mdx promised the 3.x-veteran camp but never served: middleware, built-in DI (the WireBox-removal story), query builder/scopes/enums, jobs, packages, auth strategies, SSE/channels, route model binding, WheelsTest, wheels deploy — each with its guide link. Includes the "tooling story, honestly" section (CommandBox keeps working / no tooling required at all / the CLI is an accelerator) for the mikegrogan segment, and breaking changes in one breath. welcome.mdx now links it.
• URL Rewriting (deployment/url-rewriting) — pretty URLs were undocumented anywhere in v4 while every deployment depends on them (blastiko's ask in How to get started with Wheels 3.0 without 'modern tooling' #1838). One page: the On/Partial/Off modes, the rule in words, the concrete rule for Tuckey (shipped urlrewrite.xml), nginx, Apache mod_rewrite, and IIS (cross-linked), plus a 4-step verification checklist.

vm-deployment repairs (all audit-flagged)

• The nginx config never rewrote to /index.cfm — the page's own production checklist said that means "every link breaks." It also had try_files $uri serving .cfm source as static content on direct hits. Replaced with the try_files → @rewrite → CFML-proxy shape, linked to the new URL Rewriting page.
• Deploy step 4 ran wheels migrate latest over SSH on a server where the CLI was never installed — and the staged release has no running app for the CLI to bind to anyway. Rewritten around the in-framework paths: autoMigrateDatabase=true at boot (failure = flip back and restart), or programmatic migrator.migrateToLatest() post-flip, with the backward-compatible-migrations guidance both approaches imply.
• "Zero-downtime" softened to what the recipe delivers: atomic symlink swap, a one-to-two-second Lucee restart, and the two-instance variant noted for true zero.

Other

• packages.mdx: removed the false claim that the debug bar shows a live "Available from registry" table (verified false against the code and debug-panel.mdx); added the ForgeBox vs wheels-packages-registry disambiguation — two registries, different jobs, including the CommandBox-only package install path (extract into vendor/, reload).
• Glossary: three drifted entries corrected — Environment (set in config/environment.cfm; WHEELS_ENV alone doesn't change it — the entry previously planted exactly the misconception the Environments page exists to correct), package.json (requires/replaces/suggests, not the ignored legacy dependencies), Priority queue (cross-queue order is priority DESC, runAt ASC, not --queue list position).

Verification

• astro build passes: 443 pages; 0 sidebar orphans, 0 dangling links, 0 broken internal links.
• Both new pages render; the #nginx-reverse-proxy anchor url-rewriting references confirmed in built HTML.
• Glossary corrections verified against environments-and-configuration.mdx:70, background-jobs.mdx:101, and the packages manifest documentation.

What remains

• Phase 6 (final): dedupe/residue sweep — Kamal table single-sourcing, tutorial author-residue strip, remaining minor cross-page contradictions
• The How to get started with Wheels 3.0 without 'modern tooling' #1838 draft reply (held) — now every page it should link exists

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — Phase 5 of the guides restructure: two new pages (What's New in 4.0, URL Rewriting), a repaired nginx/migration recipe in vm-deployment, a packages-registry disambiguation, and three glossary corrections. The documentation content is excellent and, on verification, factually accurate against the framework — every API name, setting, ordering rule, and internal link I checked resolves. The only issue is a commitlint header-length violation that will fail CI on squash-merge. Verdict: request changes (single, mechanical fix — shorten the title).

Commits

• Header exceeds the 100-char commitlint limit. The PR title / commit subject is 105 characters:

  docs(web/guides): add What's New in 4.0 and URL Rewriting, fix vm-deployment recipe (restructure phase 5)

  commitlint.config.js:27 sets 'header-max-length': [2, 'always', 100] — severity 2 (error), so this fails. Because the repo squash-merges, the PR title becomes the landing commit subject and is the linted gate, so this blocks the merge as written. Trim ~6 chars, e.g.:

  docs(web/guides): add What's New in 4.0 + URL Rewriting, fix vm-deployment recipe (phase 5) (91 chars)

What I verified (all correct — no action needed)

Because this PR makes many concrete framework claims, I checked the load-bearing ones against the code rather than trusting the prose:

• URLRewriting modes "On" / "Partial" / "Off" — all three exist (vendor/wheels/events/onapplicationstart.cfc:261-265).
• set(autoMigrateDatabase=true) at boot — real setting, consumed at onapplicationstart.cfc:482.
• application.wheels.migrator.migrateToLatest() and migrateTo(version) — both public methods (vendor/wheels/Migrator.cfc:209 and :27); the object is wired at onapplicationstart.cfc:465.
• Priority-queue ordering priority DESC, runAt ASC — exact match at vendor/wheels/Job.cfc:243.
• Auth classes wheels.auth.SessionStrategy / TokenStrategy / JwtService — all present under vendor/wheels/auth/.
• application.wirebox → application.wheelsdi — the DI container self-registers at application.wheelsdi (vendor/wheels/Bindings.cfc:53, Global.cfc:1053).
• Glossary "Environment" reversal — accurate: stock config/environment.cfm calls set(environment="development") and never reads WHEELS_ENV, so the "WHEELS_ENV alone doesn't change it" caveat is correct.
• packages.mdx correction — matches debug-panel.mdx:128,140: installed packages show in the Environment panel; registry browsing is the /wheels/packages tool page / CLI, not a live "Available from registry" table in the bar.
• Every internal link target page exists (middleware-pipeline, dependency-injection, authentication-patterns, route-model-binding, working-without-the-cli, choosing-your-tooling, manual-installation, etc.), and both cross-page anchors resolve: basics/migrations.mdx:50 (#running-migrations-without-the-wheels-cli) and vm-deployment.mdx:168 (#nginx-reverse-proxy).

Conventions

• No findings. Sidebar JSON adds the two entries in valid positions (URL Rewriting under the deployment group, What's New first in Upgrading & Releases). No changelog fragment is needed — this is a guides-site docs change, not a framework feat/fix.

Fix the header and this is a clean merge.