docs(web): consolidate 4.0 docs to one v4.0 line, drop stale snapshot

CHANGELOG.md

@@ -18,6 +18,14 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ----
 
+# [Unreleased]
+
+### Changed
+
+- Version switcher now labels the 4.0 stable docs "v4.0 (current)" (was "v4.0.0"); the vestigial pre-GA `v4-0-1-snapshot` guides tree is removed and its one unique page, "Reading the Changelog", is salvaged into `v4-0-0/upgrading/`. Both sites deploy from `develop`, so in-progress patch docs already live in the `v4-0-0` tree; a separate `*-snapshot` tree is only warranted when a different minor/major (e.g. `v4-1-snapshot`) is under development. Courtesy redirects cover the high-traffic `/v4-0-1-snapshot/*` paths (#2827)
+
+----
+
 # [4.0.2](https://github.com/wheels-dev/wheels/releases/tag/v4.0.2) => 2026-05-27
 
 > **Wheels 4.0.2** — second patch on the 4.0 line. Adds shared-development-database migrator reconciliation (`wheels migrate doctor` / `forget` / `pretend`, orphan-version auto-detection, and `name` / `applied_at` enrichment of the `wheels_migrator_versions` tracking table) plus `columnNames` aliases across `t.references()`, `t.primaryKey()`, and the `Migration.cfc` command helpers; ships native GPG-signed Linux package repositories at `apt.wheels.dev` and `yum.wheels.dev` (Cloudflare R2); resolves `BrowserTest` base URLs through a layered instance-time lookup; and greens the compatibility matrix across BoxLang and Adobe ColdFusion 2023/2025. ~30 PRs since the 4.0.1 GA (2026-05-20).

web/packages/ui/src/components/starlight/EditLink.astro

@@ -32,7 +32,7 @@ if (isApiFunction) {
 	}
 } else {
 	// Guides. entry.id already includes the version segment (e.g.
-	// 'v4-0-1-snapshot/basics/associations'), which matches the on-disk layout.
+	// 'v4-0-0/basics/associations'), which matches the on-disk layout.
 	href = `https://github.com/wheels-dev/wheels/edit/develop/web/sites/guides/src/content/docs/${id}.mdx`;
 }
 ---

web/packages/ui/src/components/starlight/PageTitle.astro

@@ -14,7 +14,7 @@ const frontmatterCategory = (entry.data as { category?: string }).category;
 let eyebrow: string | null = frontmatterCategory ?? null;
 
 if (!eyebrow) {
-	// id looks like 'v4-0-1-snapshot/command-line-tools/quick-start'.
+	// id looks like 'v4-0-0/command-line-tools/quick-start'.
 	// Strip the version prefix, then take the first segment.
 	const withoutVersion = id.replace(/^v[^/]+\//, '');
 	const firstSegment = withoutVersion.split('/')[0] ?? '';

web/packages/ui/src/data/versions.ts

@@ -31,15 +31,14 @@ export interface VersionMeta {
 
 /** Wheels Guides — the narrative docs at guides.wheels.dev. */
 export const GUIDES_VERSIONS: VersionMeta[] = [
-	{ slug: 'v4-0-1-snapshot', label: 'v4.0.1-SNAPSHOT', sidebarLabel: 'v4.0.1-SNAPSHOT (dev)', collapsed: false, status: 'snapshot' },
-	{ slug: 'v4-0-0', label: 'v4.0.0', sidebarLabel: 'v4.0.0 (current)', collapsed: false, status: 'current' },
+	{ slug: 'v4-0-0', label: 'v4.0', sidebarLabel: 'v4.0 (current)', collapsed: false, status: 'current' },
 	{ slug: 'v3-0-0', label: 'v3.0.0', collapsed: true, status: 'archived' },
 	{ slug: 'v2-5-0', label: 'v2.5.0', collapsed: true, status: 'archived' },
 ];
 
 /** Wheels API Reference — function-level docs at api.wheels.dev. */
 export const API_VERSIONS: VersionMeta[] = [
-	{ slug: 'v4-0-0', label: 'v4.0.0', sidebarLabel: 'v4.0.0 (current)', collapsed: false, status: 'current' },
+	{ slug: 'v4-0-0', label: 'v4.0', sidebarLabel: 'v4.0 (current)', collapsed: false, status: 'current' },
 	{ slug: 'v3-0-0', label: 'v3.0.0', collapsed: true, status: 'archived' },
 	{ slug: 'v2-5-0', label: 'v2.5.0', collapsed: true, status: 'archived' },
 	{ slug: 'v2-4-0', label: 'v2.4.0', collapsed: true, status: 'archived' },
@@ -127,7 +126,7 @@ interface CollectionEntry {
  *
  * Caller provides `entries` from `await getCollection('docs')` so this
  * function stays framework-agnostic and testable. `entryId` is the
- * current route's entry id (e.g., 'v4-0-1-snapshot/start-here/installing/
+ * current route's entry id (e.g., 'v4-0-0/start-here/installing/
  * beginner-tutorial-hello-world').
  *
  * Returns { options, currentVersion } or null if we couldn't resolve

web/sites/guides/STYLE.md

@@ -1,6 +1,6 @@
 # Wheels Guides — Writing Style Guide
 
-Governs every page in `src/content/docs/v4-0-1-snapshot/`. Contributors writing or reviewing docs treat it as enforceable.
+Governs every page in `src/content/docs/v4-0-0/`. Contributors writing or reviewing docs treat it as enforceable.
 
 ## Voice & tone
 
@@ -53,7 +53,7 @@ Every page frontmatter carries `type: tutorial | howto | concept | reference`. A
 
 ## Linking discipline
 
-- Internal links relative to site root: `/v4-0-1-snapshot/core-concepts/request-lifecycle/`.
+- Internal links relative to site root: `/v4-0-0/core-concepts/request-lifecycle/`.
 - External links checked by the link checker in CI.
 - Every CLI command links to its reference page the first time it appears in a page.
 

web/sites/guides/astro.config.mjs

@@ -89,6 +89,21 @@ export default defineConfig({
 		'/v4-0-0-snapshot/cli-reference/info': '/v4-0-0/command-line-tools/',
 		'/v4-0-0/cli-reference': '/v4-0-0/command-line-tools/',
 		'/v4-0-0/cli-reference/info': '/v4-0-0/command-line-tools/',
+		// The pre-GA `v4-0-1-snapshot` dev channel was retired when the 4.0 docs
+		// consolidated onto a single `v4-0-0` line (4.0.x is documented as one
+		// version — see web/packages/ui/src/data/versions.ts). Same Astro
+		// static-redirect limitation as the GA rename above: high-traffic landings
+		// get explicit redirects, deep links fall through. The dev channel carried
+		// little backlink equity.
+		'/v4-0-1-snapshot': '/v4-0-0/',
+		'/v4-0-1-snapshot/': '/v4-0-0/',
+		'/v4-0-1-snapshot/start-here/installing': '/v4-0-0/start-here/installing/',
+		'/v4-0-1-snapshot/start-here/first-15-minutes': '/v4-0-0/start-here/first-15-minutes/',
+		'/v4-0-1-snapshot/start-here/tutorial': '/v4-0-0/start-here/tutorial/',
+		'/v4-0-1-snapshot/start-here/release-channels': '/v4-0-0/start-here/release-channels/',
+		'/v4-0-1-snapshot/start-here/cfml-engines': '/v4-0-0/start-here/cfml-engines/',
+		'/v4-0-1-snapshot/command-line-tools': '/v4-0-0/command-line-tools/',
+		'/v4-0-1-snapshot/command-line-tools/installation': '/v4-0-0/command-line-tools/installation/',
 		// Astro/Starlight slugs the dotted filename `3.0.0-config-migration.md`
 		// down to `300-config-migration` (github-slugger strips dots). The file
 		// was renamed to `3-0-0-config-migration.md` so the URL matches every

web/sites/guides/scripts/verify-docs/verify-docs.mjs

@@ -8,7 +8,7 @@ import { runCompile } from './drivers/compile.mjs';
 import { TutorialSession } from './drivers/tutorial.mjs';
 import { enrichWithSidebarOrder, partitionAndOrder } from './lib/orchestrator.mjs';
 
-const DEFAULT_TARGET = 'src/content/docs/v4-0-1-snapshot';
+const DEFAULT_TARGET = 'src/content/docs/v4-0-0';
 
 async function collectMdx(target) {
   const s = await stat(target);

web/sites/guides/src/content/docs/index.md

@@ -8,8 +8,7 @@ or use the search bar (top right) to find a topic across all versions.
 
 ## Available versions
 
-- **[v4.0.0 (current release)](/v4-0-0/)** — stable guides for the Wheels 4.0 release
-- [v4.0.1-SNAPSHOT (dev)](/v4-0-1-snapshot/) — in-progress guides, synced from the `develop` branch
+- **[v4.0 (current release)](/v4-0-0/)** — stable guides for the Wheels 4.0 line
 - [v3.0.0](/v3-0-0/) — archived guides for the Wheels 3.0 release
 - [v2.5.0](/v2-5-0/) — frozen snapshot for the 2.5 release
 

web/sites/guides/src/content/docs/v4-0-0/contributing/writing-docs.mdx

@@ -24,7 +24,7 @@ The v4 guides live in `web/sites/guides/` as a Starlight site. Every page is an
 
 ## Site layout
 
-Every published page lives under a versioned content folder. The v4.0.0 stable docs are at `v4-0-0/`; the next in-development snapshot, `v4-0-1-snapshot/` (cloned from `v4-0-0/` at GA time, diverges as fixes/features land), sits beside it.
+Every published page lives under a versioned content folder. The 4.0 line's docs live at `v4-0-0/`. Because the site deploys from the `develop` branch, in-progress edits for the next 4.0.x patch land directly in that folder and promote to `main` at release — there is no parallel snapshot folder for a patch. A separate `*-snapshot/` folder appears only when a *different* minor or major (e.g. `v4-1-snapshot/`) is under development.
 
 <FileTree>
 - web/sites/guides/

web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/changelog.mdx → web/sites/guides/src/content/docs/v4-0-0/upgrading/changelog.mdx

@@ -114,6 +114,6 @@ Changes merged to `develop` but not yet tagged appear under `## [Unreleased]` at
 
 ## Related guides
 
-- [Upgrading Wheels](/v4-0-1-snapshot/upgrading/) — versioning policy and release cadence
-- [3.x to 4.x](/v4-0-1-snapshot/upgrading/3x-to-4x/) — every breaking change in 4.0 with before/after examples
-- [Release Channels](/v4-0-1-snapshot/start-here/release-channels/) — stable vs bleeding-edge, and how to switch
+- [Upgrading Wheels](/v4-0-0/upgrading/) — versioning policy and release cadence
+- [3.x to 4.x](/v4-0-0/upgrading/3x-to-4x/) — every breaking change in 4.0 with before/after examples
+- [Release Channels](/v4-0-0/start-here/release-channels/) — stable vs bleeding-edge, and how to switch