docs(web/guides): clarify legacy adapter does not shim application.wirebox rename

[wheels-bot]

The upgrade guide's item 10 (application.wirebox → application.wheelsdi) previously said nothing about what wheels-legacy-adapter does and does not cover for this specific rename. A reader following the guide's "install the adapter, ship the upgrade, modernize incrementally" framing could reasonably expect the adapter to handle item 10 — it does not. Apps that bootstrap WireBox directly or read from application.wirebox boot-fail immediately after upgrade, even with the adapter installed.

This PR adds an explicit <Aside type="caution"> to item 10 in both the v4-0-0 and v4-0-1-snapshot upgrade guides, adds a scope table to the Legacy Compatibility Adapter section, and adds a Common Issues entry for the wirebox boot failure.

Changes

• web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx
  • Item 10: added <Aside type="caution"> stating the adapter does not create an application.wirebox alias and does not restore the wirebox.system.ioc.Injector package path
  • Legacy Compatibility Adapter section: added a scope table (covered vs. requires manual remediation) and a second <Aside type="caution"> reinforcing the item 10 gap
  • Common Issues: added a "Boot fails with wirebox package-not-found error" bullet
• web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx — identical changes
• CHANGELOG.md — added ### Documentation entry under [Unreleased]

Screenshots needed

None — this is a prose and table addition with no UI component.

Fixes #2627

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: Pure documentation change — adds an <Aside type="caution"> to upgrade-guide item 10, a scope table to the Legacy Compatibility Adapter section, and a Common Issues bullet for the wirebox boot failure. Applied consistently to both v4-0-0 and v4-0-1-snapshot. No correctness, cross-engine, or security issues. Two minor clarity nits noted below; neither blocks merge.

---

Docs

Nit 1 — "before the upgrade" wording may mislead post-upgrade readers

File: web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx (line 323; identical in v4-0-1-snapshot)

Current:

must update those references before the upgrade — the adapter cannot soften this item.

The Legacy Compatibility Adapter section is also read by developers who have already shipped the upgrade with the adapter installed and are now working through the remaining manual items. "Before the upgrade" implies they missed their window. A wording like the following would serve both audiences:

must update those references manually — the adapter cannot defer or soften this item.

---

Nit 2 — "See item 10" in Common Issues is plain text, not a link

File: web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx (line 370; identical in v4-0-1-snapshot)

Current:

... Replace any `application.wirebox` references with `application.wheelsdi`. See item 10.

All other Common Issues bullets use #nnnn issue references for navigation. Since this one points to a section on the same page, an anchor link would be more useful for readers who land directly on the Common Issues section:

See [item 10](#10-applicationwirebox-renamed-to-applicationwheelsdi).

Verify the Starlight-generated anchor slug before landing — it may differ slightly depending on the MDX heading renderer.

---

Commits

Single commit 0d27237 — type docs, scope web/guides, subject well under 100 chars, not ALL-CAPS. DCO Signed-off-by trailer present. Clean.

---

Tests

No specs expected or needed — pure prose and Markdown table addition.

---

No blocking issues found. The core information (adapter does not shim the wirebox rename, users must fix both application.wirebox references and the new wirebox.system.ioc.Injector bootstrap call regardless of adapter installation) is accurate, prominently placed, and consistent across both versioned guides. CHANGELOG [Unreleased] entry is present and correctly scoped to ### Documentation.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

Critiquing review 4277718938 by wheels-bot[bot] on commit 0d27237.

---

Overall assessment

Reviewer A's classification (pure documentation change, no code paths touched, no specs needed) is correct. The two nits are valid and well-located. No false positives found.

---

Sycophancy check

Review state is COMMENTED, not APPROVED. Reviewer A declined to render a verdict and instead listed two nits without blocking. That is the right posture for a docs-only PR with minor wording issues — not sycophantic.

---

False positive check

Nit 1 line reference (line 323): Confirmed correct in both v4-0-0 and v4-0-1-snapshot. The text "must update those references before the upgrade" is exactly at line 323 in both files.

Nit 2 line reference (line 370): Confirmed correct. "See item 10." appears at line 370 in both files.

Anchor slug suggestion: Reviewer A suggested #10-applicationwirebox-renamed-to-applicationwheelsdi and explicitly caveated "Verify the Starlight-generated anchor slug before landing." The actual heading is ### 10. application.wirebox renamed to application.wheelsdi (with backtick-enclosed names) — Starlight's remark slug renderer strips backticks and the trailing period, producing something close to the suggested slug, but the dots inside application.wirebox are ambiguous. The caveat was appropriate; no false positive.

---

Missed issues

One gap worth noting: the scope table added in this PR lists six items as "Covered by the adapter":

• renderPage() to renderView() shim
• renderPageToString() shim
• $legacySendEmail() argument remap
• $legacyAppScopeGet(key) opt-in helper
• Migration scanner
• Deprecation call logger

The wheels-legacy-adapter package is a standalone external repo (wheels-dev/wheels-legacy-adapter) and is not present in vendor/ in this working tree. None of these claimed features can be verified against actual adapter source code from this repo. Reviewer A accepted the scope table as accurate without flagging this. The risk is low for a first-party package authored by the same team, but a reader linking to the adapter GitHub repo for confirmation is the right verification step before merge. Not a blocker, but worth a note to the PR author to confirm the table reflects the current adapter release.

No other missed issues. The CHANGELOG entry is under ### Documentation in [Unreleased] — correct section. Commit 0d27237 has type docs, scope web/guides, subject well within 100 chars, DCO trailer present. No .ai/wheels/ updates are needed since this is user-facing upgrade guide prose, not framework internals documentation.

---

Convergence

Aligned with Reviewer A. The two nits ("before the upgrade" wording and the plain-text "See item 10") are both actionable and neither is a blocker. The unverifiable scope table is the only additional concern, and it is minor given the first-party provenance of the adapter package.

[wheels-bot]

Wheels Bot — Reviewer A response (round 1)

B's critique aligns with my initial read on all points. No false positives were identified in either nit, and both line references were confirmed accurate. The one gap B added — the unverifiable adapter scope table — is valid: since wheels-legacy-adapter lives in a standalone external repo and is absent from vendor/, the six "Covered by the adapter" claims in the new table rest on authorial assertion rather than source-verifiable fact. I'm conceding this as a worthwhile note to the PR author. My overall position is unchanged: docs-only PR, no blocking issues, three nits (two original plus the adapter table note).

Conceded points

• The scope table's six "Covered by the adapter" claims cannot be verified against adapter source code from this repo. B is correct that the PR author should confirm the table reflects the current release of wheels-dev/wheels-legacy-adapter before merge. I accepted the table at face value without flagging the external provenance gap.

Defended points

• Nit 1 ("before the upgrade" wording, line 323): B confirmed the line reference and the concern. Wording misleads post-upgrade readers who have already shipped and are working through remaining manual items. Stands.
• Nit 2 ("See item 10" plain text, line 370): B confirmed the line reference and the concern. An anchor link would serve readers who land directly on the Common Issues section. Anchor slug caveat was appropriate given Starlight's MDX rendering. Stands.
• COMMENT state: B agreed this posture is correct for a docs-only PR with nits only — not sycophantic, not a false approval. No change.

Updated verdict

Still COMMENT — no blocking issues. The PR may merge once the author addresses (or consciously declines) the three nits: the "before the upgrade" wording, the plain-text "See item 10" cross-reference, and a confirmation that the adapter scope table reflects the actual current release of wheels-dev/wheels-legacy-adapter.

[bpamiri]

@claude can you fix the failing ci steps

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: This is the follow-up commit addressing both nits from the prior round (SHA 0d27237). Nit 1 ("before the upgrade" wording) and Nit 2 ("See item 10" plain text) have both been resolved cleanly. The anchor slug #10-applicationwirebox-renamed-to-applicationwheelsdi matches the actual heading at line 155. One residual informational note from the prior round remains: the scope table's "Covered by the adapter" rows cannot be verified against wheels-dev/wheels-legacy-adapter source from this repo. Not a blocker, but worth a confirmation from the PR author before merge. No correctness, cross-engine, or security issues. COMMENT verdict.

---

Docs

Prior Nit 1 — resolved. The wording at web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx line 323 (identical in v4-0-1-snapshot) now reads:

must update those references manually — the adapter cannot defer or soften this item.

The "before the upgrade" phrasing that misleads post-upgrade readers is gone. Clean.

---

Prior Nit 2 — resolved. The Common Issues bullet at line 370 (identical in v4-0-1-snapshot) is now:

See [item 10](#10-applicationwirebox-renamed-to-applicationwheelsdi).

The target heading at line 155 is:

### 10. `application.wirebox` renamed to `application.wheelsdi`

Starlight/remark-slug strips backticks, lowercases, and replaces spaces with hyphens, yielding #10-applicationwirebox-renamed-to-applicationwheelsdi. The anchor is correct.

---

Residual note — scope table not source-verifiable (carried from Reviewer B, prior round)

File: web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx lines 310–321 (identical in v4-0-1-snapshot)

The scope table's six "Covered by the adapter" rows:

| renderPage() → renderView() shim           | ...
| renderPageToString() shim                  | ...
| $legacySendEmail() argument remap          | ...
| $legacyAppScopeGet(key) opt-in helper      | ...
| Migration scanner                          | ...
| Deprecation call logger                    | ...

wheels-legacy-adapter lives in the external wheels-dev/wheels-legacy-adapter repo and is not present in vendor/ here, so these claims can't be verified against source from this PR. The PR author should confirm the table accurately reflects the current published release of wheels-dev/wheels-legacy-adapter before merge. Not a blocker — just an authorial confirmation request.

---

Commits

Single commit d430ea3 — type docs, scope web/guides, subject 62 chars, not ALL-CAPS. Signed-off-by trailer present. Clean.

---

Tests

No specs needed or expected — pure prose, table addition, and anchor-link fix.

---

Both nits from the prior round are resolved. The scope table provenance note is the only remaining item, and it is informational. COMMENT verdict; safe to merge once the adapter scope table is confirmed by the PR author.

[bpamiri]

Scope-table verification

The "Covered by the adapter" rows were verified against the published wheels-dev/wheels-legacy-adapter@v1.0.0 release before push:

Row	Verified against
renderPage() → renderView() shim	LegacyAdapter.cfc:86
renderPageToString() shim	LegacyAdapter.cfc:100
$legacySendEmail() argument remap	LegacyAdapter.cfc:116
$legacyAppScopeGet(key) opt-in helper	LegacyAdapter.cfc:137
Migration scanner	MigrationScanner.cfc (repo root)
Deprecation call logger	DeprecationLogger.cfc (repo root)

Method names match the rows exactly; the standalone MigrationScanner.cfc and DeprecationLogger.cfc files exist at the adapter repo root. Table is accurate against the current published release.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

Critiquing review 4278358305 by wheels-bot[bot] on commit d430ea351.

A's review is accurate across all claims. Both prior nits are confirmed resolved in the diff, the anchor slug logic is sound, and the commit is clean. No sycophancy, no false positives, and no missed issues.

---

Sycophancy

None detected. A rendered a COMMENT verdict (not APPROVE) despite the PR being functionally merge-ready, citing one unverifiable external claim. That is not sycophantic — it is appropriately cautious.

---

False positives

None detected.

Nit 1 resolution ("before the upgrade" wording): A claims the v4-0-0 and v4-0-1-snapshot files now read "must update those references manually — the adapter cannot defer or soften this item." Confirmed from the diff: the second <Aside type="caution"> in the scope-table block contains exactly that text.

Nit 2 resolution ("See item 10."): A claims the Common Issues bullet is now See [item 10](#10-applicationwirebox-renamed-to-applicationwheelsdi). Confirmed from the diff.

Anchor slug claim: A asserts that Starlight/remark-slug processes ### 10. application.wirebox renamed to application.wheelsdi into #10-applicationwirebox-renamed-to-applicationwheelsdi. The logic holds: remark-slug strips backtick delimiters (the identifier text remains), lowercases, removes dots (punctuation), and replaces spaces with hyphens, yielding the slug used in the link. Correct.

Commit metadata: A claims type docs, scope web/guides, subject 62 chars, not ALL-CAPS, and Signed-off-by trailer present. All confirmed. The commit is authored by claude[bot] with trailer Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> — the trailer matches the commit author, so the DCO check passes.

---

Missed issues

None detected. CI is all green (Deploy guides, Visual regression, Lucee 7 + SQLite, Validate Commit Messages all pass). The collaborator comment about failing CI was posted before A's review; those issues were resolved before A ran.

---

Verdict alignment

A's COMMENT verdict is consistent with the findings. The only outstanding item — confirming the scope table against the external wheels-dev/wheels-legacy-adapter repo — is a human/author task, not a blocker. COMMENT rather than APPROVE is defensible and not an error.

---

Convergence

Aligned with Reviewer A. No bot-driven changes are needed. The PR is technically correct: both prior nits are resolved, the anchor link is valid, and CI is clean. The remaining item (scope table confirmation) is an informational note for the PR author, not a requested change. Safe to merge once the author confirms the table reflects the current adapter release and a human reviewer approves.