docs(web/guides): correct production-config claims and stale cites from behavioral audit

[bpamiri]

Summary

Behavioral audit of deployment/production-config.mdx (Lucee 7 + Adobe 2023 dir-mount harness against develop) surfaced seven docs-wrong claims plus a batch of stale framework source citations. This PR fixes only what the audit established. Every line ref below was re-verified against the current develop head (6c5836bd8, i.e. AFTER the #3057/#3058 line shifts).

Corrections (each with evidence cite)

Factual claims

• Empty reloadPassword does NOT disable ?reload= (settings snippet comment + checklist 2). Harness-verified: with reloadPassword="" in production, a bare ?reload=true returned 302 and the app restarted unauthenticated; only URL env-switching is disabled. Evidence: public/Application.cfc:272-277 (|| !Len(application.wheels.reloadPassword) permits the reload) vs vendor/wheels/events/onapplicationstart.cfc:182-190 (env switch requires non-empty password). Docs now state actual behavior and link the contract-drift issue. Refs Reload-password contract drift: empty password leaves ?reload=true open to anonymous restarts, warm-app wrong-password attempts are never logged or rate-limited, and the boot warning misstates behavior #3062.
• wheels dbmigrate latest → wheels migrate latest. No dbmigrate verb exists — CLI errors Component [modules.wheels.Module] has no function with name [dbmigrate]; migrate is at cli/lucli/Module.cfc:592.
• Checklist 5 parenthetical deleted — csrfStore is hardcoded "session" unconditionally (vendor/wheels/events/init/security.cfm:3); nothing flips it by session management. Cookie storage is always an explicit opt-in.
• Checklist 6 wrong-file cite — flash storage selection lives at vendor/wheels/events/init/orm.cfm:57-64 (cookie attrs :69-73), not security.cfm:49-55 (that range is unrelated security settings).
• redirectAfterReload — default false at orm.cfm:26, flipped true for production AND maintenance at orm.cfm:52-54 (guide cited security.cfm:43-45, the CORS block, and omitted maintenance). Harness-verified the 302 strips reload/password and preserves other params.
• wheels doctor scope softened — it checks project structure, required files, write permissions, and datasource presence (cli/lucli/services/Doctor.cfc); it does not audit environment mode, reloadPassword, error-page settings, the CSRF key, error email, or URL rewriting. "Audits most of these" overstated (~1 of 10 checklist items).
• Env-switch no-op note added — switching to the already-active environment is a no-op (fix: make URL environment switching work through the app reload restart redirect #3036 behavior, harness-verified).

Stale source cites refreshed (behavior verified correct; pointers were wrong)

• Settings cascade: onapplicationstart.cfc:325-328 (was :271-274)
• URL env-switch default-disable: resolve call :360-369 + $resolveAllowEnvironmentSwitchViaUrl() :516-524 with the production,testing,maintenance list (was :276-284)
• URL env-switch mechanics: :180-204 (was :147-175)
• Migrate-down gate: :300-304 (was :252-254)
• Settings table: dataSourceName :254-261 (lowercased folder name); reloadPassword orm.cfm:25 (was security.cfm:25); csrfCookieEncryptionSecretKey security.cfm:30 (was :5); URLRewriting :245-252 (was :207-215)
• Dotenv step 5: application.env copy at template Application.cfc:103, inside onApplicationStart() (was :92)
• Constant-time compare: $secureCompare() vendor/wheels/Global.cfc:798, call sites onapplicationstart.cfc:190 + public/Application.cfc:277 (was :157-160)
• Reload rate limit: check :160-178, tracking + logs :207-231 (was :177-192)
• Maintenance mode: EventMethods.cfc:236-258 — 503 + onmaintenance.cfm + ipExceptions (was :173)
• Blank-password boot warning: :371-376 (was :286-291)
• Auto-migrate: flag :282, gate :461-463 (was :244)
• Checklist 5 throw: controller/csrf.cfc:148-157

Not papered over

• Reload-password contract drift: empty password leaves ?reload=true open to anonymous restarts, warm-app wrong-password attempts are never logged or rate-limited, and the boot warning misstates behavior #3062 (empty reload password permits anonymous restarts) is cited as current behavior, not "fixed".
• The reload/env-switch sections describe the post-fix: make URL environment switching work through the app reload restart redirect #3036/fix: anti-pattern-11 url shadowing in $buildRedirectUrl broke every Adobe reload (#3053) #3057/fix(events): defer redirect-after-reload past onApplicationStart so URL env switches persist #3058 world (params preserved through env-switch restarts, switch into production/maintenance sticks, redirect strips params).

Verification

pnpm verify:docs src/content/docs/v4-0-0/deployment/production-config.mdx
→ 3 passed, 0 failed (exit 0)

Refs #3062.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This docs-only PR corrects seven factual claims and refreshes ~20 stale source-line citations in the production-config deployment guide, based on a behavioral audit. I independently re-verified every changed citation and factual claim against the framework source at this PR's head, and all of them check out. Verdict: comment — no blocking findings; one minor pre-existing nit noted below.

Correctness

All verified accurate against source at 93c328f0c:

• Empty reloadPassword does not disable ?reload= — confirmed. public/Application.cfc:272-277 allows the restart when the password is empty (|| !Len(application.wheels.reloadPassword) in the OR chain), while the env-switch gate at vendor/wheels/events/onapplicationstart.cfc:182-190 requires Len(application.$wheels.reloadPassword) (line 188). The old text ("Empty disables ?reload= entirely") was indeed wrong; the new text and the #3062 link state actual behavior.
• csrfStore is hardcoded — confirmed: events/init/security.cfm:3 sets application.$wheels.csrfStore = "session" unconditionally. The deleted parenthetical ("the default when session scope isn't enabled") was wrong; cookie storage is opt-in.
• redirectAfterReload — confirmed: default false at events/init/orm.cfm:26, flipped true for production,maintenance at orm.cfm:52-54 (ListFindNoCase("production,maintenance", ...)). The old cite (security.cfm:43-45) pointed at unrelated code, and the old text omitted maintenance.
• Flash storage — confirmed at orm.cfm:57-64 (session-management branch) with cookie attributes at :69-73; the old security.cfm:49-55 cite was wrong.
• wheels doctor scope — confirmed against cli/lucli/services/Doctor.cfc::runChecks() (checkRequiredDirs, checkRequiredFiles, checkWritePermissions, checkDatabaseConfig, …). Nothing in it audits environment mode, reloadPassword, error-page settings, the CSRF key, error email, or URL rewriting — "audits most of these" was overstated, and the rewrite is accurate.
• wheels migrate latest — confirmed: migrate is the Module.cfc verb; there is no dbmigrate subcommand.
• Env-switch no-op note — consistent with the environmentSwitchAlreadyApplied guard in public/Application.cfc (application.wheels.environment == url.reload short-circuits the restart, per #3036).
• Refreshed line cites — spot-verified all of: settings cascade onapplicationstart.cfc:325-328; env-switch resolve :360-369 + $resolveAllowEnvironmentSwitchViaUrl() :516-524 (with the production,testing,maintenance list at :523); migrate-down gate :300-304; dataSourceName lowercased :254-261 (LCase( at :258); URLRewriting :245-252; blank-password boot warning :371-376; auto-migrate flag :282 + gate :461-463; rate limit :160-178 + :207-231; $secureCompare() Global.cfc:798 with call sites onapplicationstart.cfc:190 and public/Application.cfc:277; maintenance block EventMethods.cfc:236-258 (503 at :249, onmaintenance.cfm at :253-255, ipExceptions via $maintenanceModeExempt); CSRF throw controller/csrf.cfc:148-157 (Throw( at :152); dotenv steps against the scaffold template cli/lucli/templates/app/public/Application.cfc (:52-56, :58-73, :75-81, :84, and the moved :103 application.env = duplicate(this.env) inside onApplicationStart()); reloadPassword default at orm.cfm:25; csrfCookieEncryptionSecretKey at security.cfm:30.

No findings.

Docs

• Minor, non-blocking: the settings table's subpath row (production-config.mdx:93) still cites onapplicationstart.cfc:307-342, which spans the events/init/*.cfm includes (:307-313) and the settings cascade (:325-328) and truncates before the subpath assignment. The subpath detection actually lives at :330-358 (priority comment + detection :337-347, $resolveFrameworkPaths + assignment :348-358). The row is unchanged in this PR and the PR explicitly scopes itself to audit-established corrections, so this is just a leftover worth sweeping in a follow-up since the rest of that table was refreshed.

Commits

• 93c328f0c docs(web/guides): correct production-config claims and stale source cites from behavioral audit — conforms to commitlint.config.js: valid type docs, free-form scope, header under 100 chars, not ALL-CAPS. No issues.

No Correctness, Cross-engine, Security, or Tests findings — this is a docs-only diff with no code changes, and the corrections it makes are all evidence-backed.