[bpamiri]

Audit-driven corrections to web/sites/guides/src/content/docs/v4-0-0/core-concepts/environments-and-configuration.mdx. Each change is cite-checked against framework source (and live audit probes on lucee7/adobe2023); no editorial rewrites beyond the established findings.

Corrections

1. Config load order reordered — the guide listed settings.cfm before environment.cfm. Actual order: config/app.cfm (Application.cfc pseudo-constructor) → config/environment.cfm → framework defaults → config/settings.cfm → config/<env>/settings.cfm → services.cfm → routes.cfm.
   Evidence: vendor/wheels/events/onapplicationstart.cfc:204 (environment.cfm), :245-313 (framework defaults), :325-328 (settings.cfm + per-env settings), :380-386 (services), :429 (routes); public/Application.cfc:105 (app.cfm include).

2. config/app.cfm "runs once per app start" removed — it is included from the Application.cfc pseudo-constructor and executes on every request; only its this-scope effects apply at app start. Evidence: public/Application.cfc:105; live probe showed 2 executions per plain GET on adobe2023 with zero reloads.

3. WHEELS_ENV detection claim fixed — the scaffold hard-codes set(environment = "development") and neither environment.cfm nor the wheels CLI reads WHEELS_ENV. Documented the two required edits: read it via env("WHEELS_ENV", "development") in environment.cfm AND remove the scaffold .env's WHEELS_ENV=development line (env() checks .env before OS env, so it shadows exports). Evidence: config/environment.cfm:9, cli/lucli/templates/app/config/environment.cfm:9, cli/lucli/templates/app/_env:4; grep -rn WHEELS_ENV cli/lucli hits only generated-app templates; live WHEELS_ENV=production wheels info output byte-identical to plain wheels info.

4. Removed set(environment = ...) from the illustrative settings.cfm block and added a warning — setting the environment there yields a half-switched app (environment reports production while verbose errors, dev caching flags, and allowMigrationDown persist, since boot-derived flags are computed at onapplicationstart.cfc:245-313, before settings.cfm at :325). Live probe confirmed verbose error leakage (boom-marker visible at HTTP 500 while environment=production).

5. Environments table rows replaced with real framework defaults — testing row claimed "Clean DB reset per spec, shorter timeouts, deterministic time" (no such code paths exist); production row claimed "caches warmed, log rotation, HTTPS enforced" (caching is merely enabled outside development, vendor/wheels/events/init/caching.cfm:15-21; log rotation/HTTPS are not framework settings anywhere in vendor/wheels). Now lists: debug UI off, /wheels/* public component disabled, caching on, URL env-switch blocked by default — with a note pointing log rotation/HTTPS to the web server / SecurityHeaders middleware.

6. New "Switching environments at runtime" section (previous docs gap) — documents ?reload=<environment>&password=<reloadPassword> (params preserved through the restart redirect, fix: make URL environment switching work through the app reload restart redirect #3036), ?reload=<current-env> as a no-op vs ?reload=true for a plain restart, switches into production/maintenance sticking with params stripped afterward (fix(events): defer redirect-after-reload past onApplicationStart so URL env switches persist #3058), and the allowEnvironmentSwitchViaUrl gate: explicit boolean honored in every environment; unset defaults to false in production/testing/maintenance and true elsewhere (fix(events): honor explicit set(allowEnvironmentSwitchViaUrl=true) in production-like envs #3038, vendor/wheels/events/onapplicationstart.cfc:501-509 + $resolveAllowEnvironmentSwitchViaUrl).

7. Open-issue caveats cited instead of papered over:

   • Blank reloadPassword currently permits anonymous ?reload=true restarts (public/Application.cfc:272-277) — 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.
   • Debug-bar environment quick-switch links broken — Debug bar renders environment quick-switch links only in the configuration where switching is impossible (dead links since #2082) #3060.
   • wheels reload CLI can report false success — wheels reload reports "Application reloaded successfully." when the HTTP reload request fails (4xx/5xx) #3059.

Verification

• pnpm verify:docs src/content/docs/v4-0-0/core-concepts/environments-and-configuration.mdx → exit 0 (all code blocks on this page are title="illustrative — ..." config fragments per the writing-docs tagging policy; none are tagged {test:*}).

Refs #3036, #3038, #3058, #3059, #3060, #3062

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR corrects the environments-and-configuration guide to match audited framework behavior — config load order, config/app.cfm per-request execution, WHEELS_ENV non-detection on stock apps, the set(environment=...) half-switch trap, real per-environment framework defaults, and a new runtime env-switch section documenting the allowEnvironmentSwitchViaUrl gate. I independently re-verified every factual claim against framework source at this head SHA and found no discrepancies. Verdict: approve.

Verification (claim-by-claim, against 73393c8c7)

• Load order — config/environment.cfm included at vendor/wheels/events/onapplicationstart.cfc:204; environment-derived defaults (enablePublicComponent, allowMigrationDown, caching/debugging includes) computed at :245-313; config/settings.cfm + per-env settings at :325-328; services.cfm and routes.cfm after that. The guide's reordered bullet list (environment.cfm before settings.cfm) is correct; the old order was wrong.
• config/app.cfm per-request — include "../config/app.cfm"; sits in the public/Application.cfc pseudo-constructor (line 105, outside any function), so it executes on every request. The old "runs once per app start" claim was wrong; the replacement text is accurate.
• WHEELS_ENV — config/environment.cfm:9 (and the cli/lucli/templates/app/config/environment.cfm scaffold) hard-code set(environment = "development"). grep -rn WHEELS_ENV cli/lucli hits only generated-app templates, confirming the CLI ignores it. In the template public/Application.cfc:57-81, the variable's only effect is selecting the .env.<name> overlay — exactly as the guide now says.
• .env shadowing — env() at vendor/wheels/Global.cfc:597-607 checks application.env (populated from .env) before server.system.environment, so the scaffold's WHEELS_ENV=development line (cli/lucli/templates/app/_env:4) does shadow OS exports. The two-edit instruction is correct and necessary.
• set(environment=...) in settings.cfm warning — defaults like allowMigrationDown (onapplicationstart.cfc:300-304), enablePublicComponent (:274-279), showErrorInformation/showDebugInformation (vendor/wheels/events/init/debugging.cfm:22-28), and the caching flags (vendor/wheels/events/init/caching.cfm:15-21) are all derived before settings.cfm loads at :325, so the half-switched-app description is accurate.
• Environments table — testing/production rows now match real code: debug UI off outside development (debugging.cfm:26-28), errors hidden only in production (debugging.cfm:22-25), /wheels/* public component development-only (onapplicationstart.cfc:276-279), caching on outside development (caching.cfm:15-21). The removed "clean DB reset / deterministic time / caches warmed / log rotation / HTTPS" claims have no corresponding code paths — good removals.
• Runtime switch section — $resolveAllowEnvironmentSwitchViaUrl (onapplicationstart.cfc:516-524) returns any explicit boolean as-is and otherwise !ListFindNoCase("production,testing,maintenance", environment), matching the documented defaults exactly. The same-environment no-op is enforced by the environmentSwitchAlreadyApplied short-circuit in public/Application.cfc.
• #3062 caveat — confirmed: the reload condition in public/Application.cfc (~:268-277) passes when !Len(application.wheels.reloadPassword), so a blank password does permit anonymous restarts. Citing the open issue rather than papering over it is the right call.

Docs

All four code blocks on the page carry title="illustrative — ..." and none are {test:*}-tagged, consistent with the page's pre-existing pattern, so the pnpm verify:docs exit-0 claim is consistent. No v4-0-0-snapshot docs tree exists at this head, so no parallel page needs updating. No changelog fragment is required for a docs-type change per CLAUDE.md.

Commits

Single commit docs(web/guides): correct environments guide to audited config load order and env-switch behavior — valid type, 97-char header, subject describes the why. Conforms to commitlint.config.js.

No correctness, convention, cross-engine, test, or security findings. This is what a docs-audit PR should look like: every assertion carries a source citation, and the citations check out.