docs(web/guides): correct debug-panel guide against live framework behavior

[bpamiri]

Cite-checked corrections for the Debug Panel guide from the 2026-06 guide behavioral audit (Lucee 7 / development unless noted). Each fix below lists the framework-source evidence.

Corrections

1. Overrides belong in config/settings.cfm, not config/environment.cfm. Both code blocks retitled and a warning added: environment.cfm is included in the environment-selection block of vendor/wheels/events/onapplicationstart.cfc (line ~205) before the framework defaults (events/init/*.cfm) and $includeConfig(/config/settings.cfm) run, so any non-environment set() there is clobbered. Verified live: set(showDebugInformation=false) in environment.cfm left the bar rendering; the same line in settings.cfm removed it.
2. Git branch detection is web-root based. vendor/wheels/events/onrequestend/debug.cfm:37-39 checks GetDirectoryFromPath(GetBaseTemplatePath()) & ".git" — the web root (public/), and requires a directory. In a standard wheels new layout (.git at project root) the branch never appears. Both "when Wheels detects a .git directory" and "when the app root contains a .git directory" corrected.
3. Timing panel: real phase names, no percentage text. Replaced the invented (model, queries, template rendering, etc.) with the actual $debugPoint() phases (setup, requestStart, beforeFilters, action, afterFilters, view, requestEnd — vendor/wheels/Dispatch.cfc:342,388, controller/processing.cfc:36-127, controller/rendering.cfc:31,77, EventMethods.cfc:160-308). The percentage exists only as the bar's CSS width (debug.cfm:62,252); no % figure is printed. The 80% tip rewritten around action/view dominating.
4. Removed the per-action query-count claim. /wheels/routes (vendor/wheels/public/views/routes.cfm:50-51) shows tab route counts and Name/Method/Pattern/Controller/Action columns — no query counts exist on the page.
5. Environment dot colors stated directly. debug.cfm:41-49: development green #28a745, testing orange #fd7e14, maintenance yellow #ffc107, production red #dc3545 — testing's orange is not in the timing badge palette, so "matching the timing badge palette" was wrong.
6. Quick-switch links documented as currently dead. URL environment switching requires a configured reloadPassword + matching password param (onapplicationstart.cfc:181-205, hardening from fix(config): require non-empty reload password for environment switching #2082), but the bar's links render only when no password is set (debug.cfm:304-311) — clicking one just restarts the same environment. Documented the working flow instead (?reload=<env>&password=...), the allowEnvironmentSwitchViaUrl gate ($resolveAllowEnvironmentSwitchViaUrl(), onapplicationstart.cfc:516-525: explicit boolean honored everywhere, unset defaults to false in production/testing/maintenance — fix(events): honor explicit set(allowEnvironmentSwitchViaUrl=true) in production-like envs #3038), the same-environment no-op and post-switch param stripping (fix: make URL environment switching work through the app reload restart redirect #3036/fix(events): defer redirect-after-reload past onApplicationStart so URL env switches persist #3058). Dead links tracked in Debug bar renders environment quick-switch links only in the configuration where switching is impossible (dead links since #2082) #3060; the anonymous ?reload=true restart with an empty password is called out with a caution and tracked in 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.
7. Removed the nonexistent "Available from registry" table. debug.cfm:328-356 renders only the installed table + failed list; the registry browser lives on the /wheels/packages page (vendor/wheels/public/views/packagelist.cfm). The discovery/registry-refresh tip now points at that page and the CLI.
8. "since Wheels 4.0.3" → "since Wheels 4.0.4". Released 4.0.3's Public.cfc::$shouldBlockInProduction() blocked only production; the development-only allowlist landed in fix(dispatch): block /wheels/* dev UI unless environment is development #2903 (cb6241c1e), which is not an ancestor of the v4.0.3 tag.
9. New section: IP-based debug access outside development. Documents allowIPBasedDebugAccess / debugAccessIPs / debugAccessTrustProxy (defaults false / [] / false, vendor/wheels/events/init/security.cfm:53-57). For allowed IPs in non-development environments, public/Application.cfc:218-250 re-enables showDebugInformation, enablePublicComponent, and showErrorInformation per request (verified live on Lucee 7 and Adobe 2023 in production), while /wheels/* tool pages still 404 outside development.

Both retitled config blocks are now {test:compile}-tagged; pnpm verify:docs src/content/docs/v4-0-0/digging-deeper/debug-panel.mdx passes (2/2 blocks).

Refs #3060, #3062.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR corrects nine factual claims in the debug-panel guide against live framework behavior, and every correction checks out against the framework source at this head. I independently verified each claim (details below) and found no correctness, cross-engine, or security issues; commit message, DCO sign-off, and conventions are all clean. One minor, non-blocking docs note about the forward-dated "since Wheels 4.0.4" label. Verdict: comment (no changes required).

Verification notes

I re-derived each correction from source rather than trusting the PR body:

• Config include order — config/environment.cfm is included at vendor/wheels/events/onapplicationstart.cfc:204, before the framework defaults (events/init/*.cfm, lines 307–313) and the config/settings.cfm include (line 325). A non-environment set() in environment.cfm is indeed clobbered, so the retitled code blocks and the new warning are accurate.
• Git branch detection — vendor/wheels/events/onrequestend/debug.cfm:37-39 uses DirectoryExists(GetDirectoryFromPath(GetBaseTemplatePath()) & ".git"), i.e. the web root (public/), and requires a directory. The "web root" correction and the "row does not appear in a standard layout" caveat are both right.
• Timing phases — action is recorded via the comma-list form ($debugPoint("beforeFilters,action") at controller/processing.cfc:50, "action,afterFilters" at line 119), and the full set at head matches the guide's list. The percentage exists only as CSS width (debug.cfm:252); only milliseconds are printed inside the bar (line 253). "No percentage figure is displayed" is accurate.
• Routes page — vendor/wheels/public/views/routes.cfm:50-51 shows tab route counts only; no per-action query counts exist, so removing that claim is correct.
• Environment dot colors — debug.cfm:41-49 confirms production #dc3545, testing #fd7e14, maintenance #ffc107, else #28a745, exactly as now documented.
• Quick-switch links — render only when reloadPassword is empty (debug.cfm:304-312), while the environment switch requires a configured password, so the links are dead as described. The anonymous-restart caution is also accurate: with an empty reloadPassword, any ?reload=... request reaches $handleRestartAppRequest() (public/Application.cfc:268-288).
• allowEnvironmentSwitchViaUrl — $resolveAllowEnvironmentSwitchViaUrl() (onapplicationstart.cfc:516-524) honors an explicit boolean everywhere and defaults to false only in production,testing,maintenance when unset — matches the new paragraph.
• Packages section — debug.cfm:328-356 renders only the installed table plus the failed-packages list; the removed "Available from registry" table does not exist in the panel. Pointing readers at /wheels/packages and the CLI is the right replacement.
• Version gate — v4.0.3's $shouldBlockInProduction() returns true only for environment == "production"; at this head it is the fail-closed != "development" allowlist from #2903. The old "since Wheels 4.0.3" was definitively wrong.
• IP-based debug access — defaults confirmed at vendor/wheels/events/init/security.cfm:53-57 (false / [] / false); the per-request override of showDebugInformation, enablePublicComponent, and showErrorInformation, the exact-match arrayContains, the rightmost ListLast(CGI.HTTP_X_FORWARDED_FOR) under debugAccessTrustProxy, and the non-development-only condition all match public/Application.cfc:218-250. The note that /wheels/* tool pages still 404 outside development (environment-based allowlist, not bypassed by the IP override) is consistent with Public.cfc::$shouldBlockInProduction(). The trust-proxy caution is a good security call-out.
• {test:compile} blocks — both new blocks are tag-wrapped (<cfset set(...)>); the compile driver's sniffKind() classifies them as tag and parse-checks them via the <cfif false> wrap (web/sites/guides/scripts/verify-docs/drivers/compile.mjs:83-88,209-211), so the tagging is supported by the verifier shipped in the parent commit. I could not execute pnpm verify:docs in this sandbox; the PR body reports 2/2 passing and CI will confirm.

Docs

• Forward-dated version label (non-blocking). debug-panel.mdx line 184 now reads "since Wheels 4.0.4 (#2903)", but no v4.0.4 tag exists yet — git tag tops out at v4.0.3, and the #2903 change sits on develop unreleased. "4.0.4" is the natural label for the next patch release and is strictly better than the wrong "4.0.3", but if the next release ships under a different number (e.g. 4.1.0) this line will need a touch-up. Worth a quick confirm at release cut; no change needed now.

Commits

Clean: docs(web/guides): correct debug-panel guide against live framework behavior — valid type, 76-char header, sentence case, DCO sign-off present and matching the author. No changelog fragment is required for a docs-type change.