docs(web/guides): document buttonTo input-prefix convention and schema-cache invalidation

[bpamiri]

Closes two v4 guide gaps surfaced while reviewing recent GitHub Discussions. Docs-only; no changelog fragment (type docs, not fix/feat).

1. buttonTo input-prefix convention — discussion #1352

The input-prefixed attribute convention (inputClass/inputId/inputRel) was documented in the v3 guides but never carried into the v4-0-0 guides during the restructure — a grep for inputClass/inputId across v4-0-0/ returned nothing. Users hit "buttonTo() won't accept id/class" with no doc explaining why.

Added a buttonTo entry to Common view helpers (views-layouts-partials.mdx) explaining that because the button renders inside a <form>, its attributes are input-prefixed, while unprefixed class/id land on the form — and that buttonTo is the only link helper with this split. (The API docstring at vendor/wheels/view/links.cfc already covers it in the function description, so no source change needed.)

2. Schema / model-metadata cache — discussion #1481

The v4 caching guide thoroughly covers application.wheels.cache (action/query/partial), but never the per-model schema cache in application.wheels.models — the column metadata Wheels reads via cfdbinfo at init and holds for the app lifetime. That's the cache that makes a running app throw "column not found" after a live ALTER TABLE, and which $clearCache() / clearQueryCacheOnReload / clearTemplateCacheOnReload do not rebuild.

Added a "Schema and model-metadata cache" section to caching.mdx explaining the cache and the recovery options (migrate + per-node reload, rolling LB restart, off-hours engine restart).

Verification

• Internal link /v4-0-0/basics/migrations/ confirmed to exist.
• <Aside> already imported in caching.mdx; no new component imports.
• Did not run the full Astro build locally.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — Docs-only PR closing two v4 guide gaps: buttonTo's input-prefixed attribute convention (#1352) and the per-model schema/column-metadata cache in application.wheels.models (#1481). Both additions are technically accurate — I verified every claim against the framework source — and the diff is clean. Verdict: approve.

Correctness

Both technical claims check out against vendor/wheels/:

• buttonTo input-prefix split (views-layouts-partials.mdx). The doc states button attributes use inputClass/inputId/inputRel while unprefixed class/id land on the wrapping <form>. This is exactly what buttonTo() does:

  • vendor/wheels/view/links.cfc:143 — local.args = $innerArgs(name = "input", args = arguments); routes input* attrs onto the button.
  • vendor/wheels/view/links.cfc:158 — return $element(name = "form", ..., attributes = arguments); routes the remaining class/id onto the form.
  • The function docstring (links.cfc:83) corroborates it, so no source change was needed — the PR correctly leaves the code alone.

• Schema / model-metadata cache (caching.mdx). The doc claims $clearCache() cannot rebuild the column metadata in application.wheels.models. Confirmed: $clearCache() (Global.cfc:973-979) only ever calls StructClear(application.wheels.cache...). The model schema cache is cleared only by $clearModelInitializationCache() (Global.cfc:1341 -> StructClear(application.wheels.models)), which the reload path invokes (events/EventMethods.cfc:282). The recovery advice ("migrate, then reload") is sound. The two named settings the doc says do not rebuild it — clearQueryCacheOnReload and clearTemplateCacheOnReload — both exist in the codebase, so the doc isn't inventing API names.

Docs

• Internal link /v4-0-0/basics/migrations/ resolves to an existing page (web/sites/guides/src/content/docs/v4-0-0/basics/migrations.mdx).
• <Aside type="caution"> is safe — Aside is already imported at caching.mdx:9, so no new import is required.
• No changelog fragment needed: type docs, not fix/feat. PR body states this correctly.

One minor, non-blocking note: the PR body acknowledges the full Astro build wasn't run locally. The two risks a build would catch — a broken internal link and a missing component import — are both verified above by hand, so residual risk is low.

Commits

docs(web/guides): document buttonTo input-prefix convention and schema cache — valid type, optional scope, header well under 100 chars, sentence-cased. DCO Signed-off-by trailer present. Conforms to commitlint.config.js.

Nicely scoped, accurate documentation. Approving.