docs(web/guides): fix caching guide cache categories, finder-cache store, and invalidation claims

[bpamiri]

Audit-driven corrections to the Caching guide (digging-deeper/caching.mdx). Four claims in the page were verified wrong against framework source (and live probes on Lucee 7); each fix below cites the source of truth.

Corrections

1. caches() time default is a hardcoded 60, not defaultCacheTime.
   The page attributed the 60-minute default to defaultCacheTime. In fact caches() carries its own literal default — application.$wheels.functions.caches = {time = 60, static = false} (vendor/wheels/events/init/functions.cfm:25). defaultCacheTime governs cache=true finders and renderView()/renderPartial() fallbacks (vendor/wheels/Global.cfc:808-828, vendor/wheels/controller/rendering.cfc:453,479, vendor/wheels/model/read.cfc:339-341), so set(defaultCacheTime=15) would not change caches(). The bullet now says so.

2. Real cache-struct categories; finder results don't live in application.wheels.cache.
   The page listed 5 categories (action, partial, query, image, main). The struct is actually initialized with 7 — sql, image, main, action, page, partial, query (vendor/wheels/events/onapplicationstart.cfc:123-131) — and nothing in the framework ever writes the query category (writers: read.cfc:288 → sql, view/assets.cfc:154 → image, controller/processing.cfc:57 + rendering.cfc:52 → action, rendering.cfc:547 → partial). Added the explicit caveat that findAll(cache=N)/findByKey(cache=N) results are stored in the CFML engine's native query cache via cachedWithin (vendor/wheels/model/read.cfc:341), with only the SQL shell in the sql category.

3. Invalidation Option 3 rewritten — $clearCache(category="query") is a no-op for finder caches.
   Live-verified: stale finder results survived $clearCache(category="query") because they live in the engine's query cache, not the Wheels struct. The working blunt instruments are ?reload=true&password=... — which rotates the cache-key SQL comment embedded in every cached query (vendor/wheels/databaseAdapters/Base.cfc:813-817), invalidating all engine-cached results — or an application restart. The option now says exactly that.

4. Per-environment config path corrected.
   config/environments/development.cfm is never read; per-environment overrides load from config/<environment>/settings.cfm (vendor/wheels/events/onapplicationstart.cfc:326-328). Also clarified that cacheActions=false is the framework-set development default (vendor/wheels/events/init/caching.cfm:10) — no config file involved.

5. Current reload-password behavior noted (open issue).
   Since the page recommends ?reload=true&password=... for cache busting, added a note that an empty reloadPassword currently allows anonymous ?reload=true restarts, per the open contract-drift issue.

Refs #3062

Verification

• pnpm verify:docs src/content/docs/v4-0-0/digging-deeper/caching.mdx — 10 tagged blocks, 10 passed, exit 0.
• All source citations re-checked against current develop in this branch.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR makes five audit-driven corrections to the caching guide (web/sites/guides/src/content/docs/v4-0-0/digging-deeper/caching.mdx), and I verified every one of them against framework source on this branch — all five are accurate. Verdict: comment. No blocking findings; two minor non-blocking nits below (one wording suggestion, one commit-hygiene note).

Correctness (of the doc claims — all verified, no findings)

Each correction was re-checked against the framework source at this PR's head:

1. caches() hardcoded 60 — confirmed. vendor/wheels/events/init/functions.cfm:25 sets application.$wheels.functions.caches = {time = 60, static = false}, and caches() pulls it via $args(args = arguments, name = "caches", ...) (vendor/wheels/controller/caching.cfc:14). defaultCacheTime is consumed by $timeSpanForCache() for cache=true finders (vendor/wheels/Global.cfc:810, vendor/wheels/model/read.cfc:339-341) and by the $renderViewAndAddToCache / $renderPartialAndAddToCache fallbacks (vendor/wheels/controller/rendering.cfc:452-455, 477-481) — so set(defaultCacheTime=15) indeed does not touch caches().
2. Seven cache categories — confirmed at vendor/wheels/events/onapplicationstart.cfc:123-131 (sql, image, main, action, page, partial, query). Writers verified: read.cfc:288 → sql, view/assets.cfc:154 → image, controller/processing.cfc:57 and controller/rendering.cfc:52 → action, rendering.cfc:547 → partial, $addToCache default → main (Global.cfc:837). Nothing writes query.
3. Finder results live in the engine query cache — confirmed: read.cfc:341 sets cachedWithin on the query execution; only the SQL shell is stored under sql (read.cfc:288).
4. Reload rotates the cache-key comment — confirmed: onapplicationstart.cfc:389-390 regenerates application.$wheels.cacheKey = Hash(CreateUUID()) (clearQueryCacheOnReload defaults true at events/init/caching.cfm:29, and on a full applicationStop() restart the key never exists, so rotation always happens), and databaseAdapters/Base.cfc embeds cachekey:#$get("cacheKey")# as a comment in every cachedwithin query, so rotation invalidates all engine-cached results.
5. Config path + dev default + reload-password note — confirmed: per-environment overrides load from /config/#environment#/settings.cfm (onapplicationstart.cfc:326-328; no code path reads config/environments/), cacheActions = false is the framework's development default (events/init/caching.cfm:10), and the empty-reloadPassword anonymous-reload behavior is real (the template's reload gate at cli/lucli/templates/app/public/Application.cfc:263-272 allows the restart when !Len(application.wheels.reloadPassword)), matching open issue #3062.

Docs

• Nit — page is as unwritten as query (caching.mdx:145, the "Where cache entries live" paragraph). The new text singles out query as "a legacy query category that nothing writes to," which implies the other six are written. But no framework code writes the page category either — page caching gated on cachePages stores under action (vendor/wheels/controller/rendering.cfc:51-52: local.category = "action" inside the $get("cachePages") branch), and a repo-wide grep finds no category = "page" writer. Suggest: "…plus legacy page and query categories that nothing writes to (page-cached output lands in action)". Non-blocking — the sentence as written is literally true about query; this just closes the same class of implied-accuracy gap the PR is fixing.

Commits

• Nit — branch commit header is 109 chars. docs(web/guides): correct caching guide — cache categories, finder-cache store, clearCache scope, config path exceeds commitlint's header-max-length of 100 (commitlint.config.js:27). Not blocking: the repo squash-merges and the PR title is the linted gate, and the PR title (docs(web/guides): fix caching guide cache categories, finder-cache store, and invalidation claims) is 97 chars and a valid conventional-commit header. DCO sign-off present and matches the author email.

Tests

Docs-only change; no spec changes required. The edited lines are prose (no {test:compile} blocks were added or modified), and the PR reports pnpm verify:docs passing 10/10 tagged blocks. No changelog fragment is required for a docs-type PR (fragments are for user-facing fix/feat).