docs(web/guides): add the no-CLI path and five-journey front door (restructure phase 3)

[bpamiri]

Summary

Phase 3 of the guides restructure driven by discussion #1838 — the phase that directly answers the thread. Six new pages plus the journey-based front door. Every claim in the new pages was verified against the real 4.0.5 release zips (downloaded and inspected) or framework source before writing. Follows #3275 (nav) and #3276 (trust repair).

The six new pages

Page	What it delivers
Manual Installation (zip / GitHub)	The #1 ask in #1838, restored and better than the 3.x version ever was: verified against the actual artifacts, 4.0 needs exactly two zips and zero external dependencies — the built-in Injector.cfc replaces WireBox and the built-in wheelstest/ replaces TestBox. The infamous 3.x WireBox/TestBox-plus-four-hidden-modules layering appears only as a labeled historical aside. Includes the git-clone alternative with the honest @build.version@ caveat.
Choosing Your Tooling	The decision page built from the glossary andoradmiraal's team wrote for themselves — corrected (the wheels CLI is LuCLI rebranded, not a thing LuCLI installs; "binary"/"JAR"/"bucket" demystified; Chocolatey marked retired). Explicitly answers "do CommandBox shops have to switch?" (no) and "is a plain GitHub download supported?" (yes). Bolded "if unsure, use the wheels CLI" keeps the default path the default.
Working Without the CLI	Task-equivalents hub with a per-equivalent availability column. Verified against Public.cfc: the /wheels/* browser surfaces are development-only via a hard allowlist since 4.0.4 (#2903) regardless of enablePublicComponent — so the production-safe column points at the programmatic calls (application.wheels.migrator.migrateToLatest(), seeder.runSeeds(), both verified) and the password-gated URL reload.
Anatomy of a Wheels App	The directory map previously only learnable by running wheels new mid-tutorial, including the 2.x→4.0 mental mapping and the six-mapping contract from public/Application.cfc.
Upgrading Without the CLI	The vendor/wheels/ swap recipe (what wheels upgrade apply automates) for patch bumps and the 3.x→4.0 jump; opens with the two-pass pointer for 2.x apps; honest aside on wheels upgrade check including its two known false spots (#3115).
IIS and Windows Deployment	⚠️ Needs a hand-test on a real IIS box before merge (see below). IIS site rooted at public\, wsconfig/BonCode connector steps, a web.config translation of the shipped Tuckey rules, the CF-Administrator datasource requirement, and the MySQL 8 nullCatalogMeansCurrent=true metadata gotcha — all from the community-verified setup in #1838, adapted to the 4.0 layout.

The front door

• v4-0-0/index.mdx is now five journey cards — I'm new / I have a 2.x-3.x app / I don't use CLI tooling / I'm a CommandBox shop / I'm deploying to my own servers — plus a full section map. All five cards' gating pages exist in this PR, satisfying the proposal's hold-back rule.
• start-here/index.mdx mirrors the journeys: orientation → the three install paths under one heading → learn-it.
• installing.mdx gains a "Don't want a CLI at all?" aside; the sidebar gains all six pages in their proposed positions.

Verification

• astro build passes: 440 pages (434 + 6); all six new pages render; journey cards confirmed in built HTML.
• 0 sidebar orphans, 0 dangling sidebar links, 0 broken internal links (script-checked).
• Ground-truth checks: release zips inspected (base-template ships empty vendor/; core zip is a bare wheels/ folder; box.json confirms no WireBox/TestBox deps), Public.cfc dev-only allowlist confirmed, Migrator.cfc/Seeder.cfc programmatic APIs confirmed, app/migrator/migrations/ path confirmed in the shipped template.

Review flags

• IIS page: hand-test on a real Windows/IIS + Adobe CF box before or shortly after merge — the page itself carries a "verify on your box" caution and invites discussion feedback, but a maintainer pass is the bar the proposal set.
• After merge, the draft reply to How to get started with Wheels 3.0 without 'modern tooling' #1838 (Appendix B of the proposal doc) can be updated to link the live Manual Installation and Choosing Your Tooling pages — strongest possible answer to the thread.

Follow-ups (later phases)

• Phase 4: dual-path rewrites of Migrations, Seeding, Running Tests Locally, CI Integration, Datasources
• Phase 5: What's New in 4.0 + URL Rewriting pages, vm-deployment nginx fix, Glossary corrections
• Template bug spotted during research (outside this repo's docs): the shipped config/settings.cfm in the base template links the dead v4-0-0-snapshot guides URL

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — Phase 3 of the guides restructure: six new no-CLI/onboarding pages plus a five-journey front door, all under web/sites/guides/. This is a docs-only change (494 additions, no framework/app/CLI code touched), so there are no cross-engine, code-correctness, or security surfaces to break. I independently verified every falsifiable technical claim in the new pages against framework source, and they all check out; internal links and the sidebar entries all resolve. Verdict: comment — no blocking findings, a couple of minor verification notes below that a maintainer may want to confirm before/at merge.

Docs

Ground-truth checks I ran against vendor/wheels/ and the base template — all confirmed accurate:

• Programmatic migrator/seeder APIs (working-without-the-cli.mdx, manual-upgrades.mdx): application.wheels.migrator.migrateToLatest(), .migrateTo(version), .getCurrentMigrationVersion(), and application.wheels.seeder.runSeeds() all exist and are public — Migrator.cfc:209/27/225, Seeder.cfc:46. The application.wheels.migrator / .seeder objects are wired at events/onapplicationstart.cfc:465/470.
• application.$wheels.version (manual-installation.mdx:97, manual-upgrades.mdx): real and populated at onapplicationstart.cfc:105 from BuildInfo. Consistent with the existing upgrading/changelog.mdx and upgrading/index.mdx usage.
• Six mappings (app-structure.mdx, manual-installation.mdx): /app, /vendor, /wheels, /tests, /config, /plugins match cli/lucli/templates/app/public/Application.cfc:25-30 exactly (the base-template Application.cfc, which is the reader's context).
• Injector.cfc and wheelstest/ (no WireBox/TestBox dependency): both present — vendor/wheels/Injector.cfc, vendor/wheels/wheelstest/.
• .env vars (manual-installation.mdx:427): WHEELS_ENV, WHEELS_DATASOURCE, WHEELS_RELOAD_PASSWORD match the template at cli/lucli/templates/app/_env.
• Settings autoMigrateDatabase and reloadPassword are real (onapplicationstart.cfc:482, Global.cfc:684); the /wheels/* dev-only allowlist claim matches Public.cfc:12-27 and #2903.
• Browser surfaces /wheels/migrator, /wheels/routes, /wheels/info, /wheels/app/tests all back onto existing views (public/views/migrator.cfm, routes.cfm, info.cfm, tests.cfm).
• Internal links & anchor: spot-checked every cross-referenced page (welcome, upgrading, 2x/3x guides, installing-with-commandbox, deployment index/vm/docker, security-hardening, packages, changelog, glossary, database-and-multiple-datasources, tutorial, etc.) — all resolve. The security-hardening/#reload-password anchor matches the ## Reload password heading at line 153. Sidebar entries in v4-0-0.json are all backed by files in this PR.

Two minor notes (non-blocking, no change required):

• app-structure.mdx:44-49 presents the mappings as this.mappings["/app"] = expandPath("../app/") literals. The shipped template routes these through intermediate vars (this.appDir = expandPath("../app/"), this.wheelsDir = this.vendorDir & "wheels/", Application.cfc:21-27). The effective paths are identical, so the sample is accurate as an explanation — just flagging that a reader diffing against the real file will see a slightly different shape.
• manual-installation.mdx:419 and iis-and-windows.mdx:67 reference an env.example file in the extracted base template. In-repo the template ships cli/lucli/templates/app/_env (installed as .env); I couldn't confirm from source that the base-template zip contains a file literally named env.example. The PR states zip contents were inspected against 4.0.5 — worth a maintainer double-check, since it's the file new users are told to copy from.
• iis-and-windows.mdx correctly self-flags as needing a real-Windows/IIS hand-test, matching the PR's own review checklist. Good practice; no action needed in-diff.

Commits

Single commit dfe9fb37c — docs(web/guides): add the no-CLI path and five-journey front door (restructure phase 3). Valid type (docs), optional scope (web/guides), header ~86 chars (< 100), not ALL-CAPS. Matches the PR title, which is the linted squash-merge gate. Conforms.

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — Phase 3 of the guides restructure: six new no-CLI/onboarding pages (manual-installation, choosing-your-tooling, working-without-the-cli, app-structure, manual-upgrades, iis-and-windows), a five-journey front door on index.mdx, sidebar wiring, and a refreshed visual baseline — all under web/sites/guides/. Docs-only. I spot-checked every concrete framework claim against source rather than trusting the prose, and they hold up. Verdict: comment — the diff is clean and unusually well-grounded; one non-blocking completeness nit on the IIS web.config rule.

Docs

Verified against framework source (all confirmed accurate):

• app-structure.mdx / manual-installation.mdx — the six-mapping contract (/app, /vendor, /wheels, /tests, /config, /plugins) matches public/Application.cfc:22-27. Injector.cfc and wheelstest/ both exist under vendor/wheels/, so "zero external dependencies / no WireBox / no TestBox" is correct.
• working-without-the-cli.mdx — application.wheels.migrator.migrateToLatest() / .migrateTo() / .getCurrentMigrationVersion() all exist (vendor/wheels/Migrator.cfc:209,27,225; wired at onapplicationstart.cfc:465,483). seeder.runSeeds() confirmed (Seeder.cfc:46). autoMigrateDatabase confirmed (onapplicationstart.cfc:482). The #2903 dev-only allowlist and "enablePublicComponent=true cannot open these outside development" claim is backed by the Public.cfc:19-27 comments.
• manual-installation.mdx / manual-upgrades.mdx — application.$wheels.version is the real property (onapplicationstart.cfc:105), used consistently in both pages.
• All internal cross-links resolve — every linked page (installing-with-commandbox, security-hardening, production-config, vm-deployment, 2x-to-3x, 3x-to-4x, changelog, release-channels, packages, conventions-over-configuration, the tutorial chapters, all section indexes) exists, and the #reload-password anchor matches the ## Reload password heading in security-hardening.mdx:153. type: frontmatter values (howto/explanation/landing/section) are all already established in the corpus.

Nit (non-blocking) — deployment/iis-and-windows.mdx:40-61: the web.config translates only the primary "Wheels pretty URLs" rule from public/urlrewrite.xml. The shipped Tuckey file has a second rule ("Convert dot to format parameter", ^/(.*)\.(\w+)$ → ?format=$2) that isn't reflected here, so IIS readers relying on /posts/1.json-style format negotiation won't get the same behavior. The page text says "translation of the same rule" (singular) and carries a "verify on your box" caution, so this is a completeness note, not an inaccuracy — worth a one-line aside that the extension-to-format convenience rule isn't carried over.

Commits

Both conform to commitlint.config.js: docs(web/guides): … and chore(web): refresh visual baseline(s) (all) — valid types, scoped, subjects under 100 chars. The binary guides.png baseline refresh is the expected consequence of the landing-page change.

Nice work — the "verified against the real 4.0.5 zips / framework source before writing" discipline shows. The IIS page's own caution banner correctly flags it as the one section still wanting a hand-test on a real Windows/IIS box, which matches the PR's review-flag checklist.