fix(view): resolve guides sidebar dynamically so the in-app view loads after v4.0.0 GA

[wheels-bot]

Summary

The in-app Guides view (vendor/wheels/public/docs/guides.cfm) and the AI summary endpoint (vendor/wheels/public/views/ai.cfm) both hardcoded their sidebar source to web/sites/guides/src/sidebars/v4-0-0-snapshot.json. That filename was removed when v4.0.0 went GA — the active dev snapshot is now v4-0-1-snapshot.json — so the FileExists() guard fell through silently and monorepo contributors saw an empty Guides sidebar.

This PR replaces the hardcoded basename with a glob over web/sites/guides/src/sidebars/*.json sorted descending lexicographically (a -snapshot suffix sorts after the matching GA at the same version, which is the behavior we want — the dev snapshot wins). The external redirect URL on guides.cfm is now derived from the same active slug so the two strings never drift apart again. Both endpoints still return cleanly when the monorepo web/ tree isn't on disk (installed-app environments).

Related Issue

Fixes #2647

Type of Change

• Bug fix
• New feature
• Enhancement to existing feature
• Documentation update
• Refactoring

Feature Completeness Checklist

• DCO sign-off — single commit signed via git commit -s
• Tests — new vendor/wheels/tests/specs/view/guidesSidebarDiscoverySpec.cfc (regression guard for Guides sidebar fails to load in repo setup due to missing v4-0-0-snapshot.json file path #2647 — notToInclude("v4-0-0-snapshot.json") on both files, plus a dynamic-discovery existence check; this is the same source-pinning pattern already used by guidesRedirectHeadSpec.cfc and routesViewBrowserFixturesSpec.cfc)
• Framework Docs — will be handled by bot-update-docs.yml if the user-facing guide needs to change
• AI Reference Docs — will be handled by bot-update-docs.yml
• CLAUDE.md — will be handled by bot-update-docs.yml
• CHANGELOG.md — entry added under [Unreleased] → Fixed
• Test runner passes — local bash tools/test-local.sh view is not runnable in this bot environment (no Wheels CLI install, no Lucee Express); failing-then-passing TDD discipline was verified by static inspection of the spec against pre-fix and post-fix source. CI will run the full Lucee 7 / Adobe / SQLite / MySQL / Postgres matrix on this PR; please rely on those checks rather than the unchecked local box.

Test Plan

• vendor/wheels/tests/specs/view/guidesSidebarDiscoverySpec.cfc passes on Lucee 7 + SQLite
• Manually visit /wheels/docs/guides in a fresh monorepo checkout — sidebar populates with sections from web/sites/guides/src/sidebars/v4-0-1-snapshot.json
• /wheels/ai?format=json returns a non-empty guides array under the documentation key when the monorepo web/ tree is present
• Both endpoints still return cleanly (empty sidebar / empty guides, no exception) when web/sites/guides/src/sidebars/ does not exist (simulated installed app)

Notes for reviewer

• The fallback local.activeSlug = "v4-0-0" in guides.cfm means installed apps redirect to the canonical GA docs URL rather than a stale snapshot slug. astro.config.mjs already has redirects from /v4-0-0-snapshot/* → /v4-0-0/* for back-compat, so neither slug is broken externally; using the GA slug as the fallback is just the more honest default in non-snapshot deployments.
• The same hardcoded path also appears in cli/lucli/services/Doctor.cfc, cli/lucli/Module.cfc, scaffolded templates under cli/lucli/templates/app/, and cli/src/templates/ConfigRoutes.txt. Those are user-facing doc URLs in onboarding output / generated apps, not framework runtime paths, and Stale docs.cfwheels.org URL in scaffolded config/routes.cfm template comment #2635 already tracked the routes-template variant. I left them alone — the failure mode the original issue reports is the in-app sidebar, which is what this PR fixes.

[wheels-bot]

Wheels Bot — No doc updates

Reviewed this PR's diff and found no docs that need updating (internal bug fix that restores expected behavior — replaces hardcoded v4-0-0-snapshot.json paths in guides.cfm and ai.cfm with dynamic glob discovery; no user-visible API, no new conventions, no documented pattern changed).

[wheels-bot]

Wheels Bot — Reviewer A

This PR fixes the in-app Guides sidebar and AI summary endpoint going silent for monorepo contributors after v4.0.0 GA renamed v4-0-0-snapshot.json. Replacing the hardcoded path with a DirectoryList glob + descending sort is the right approach, the fallback is correct, and DCO/commitlint/CHANGELOG are all in order. I am submitting a --comment review: one nit on a misleading sort-invariant claim in the comments, and one note on the test strategy. Neither is blocking.

Correctness

Sort-invariant comment states the opposite of what happens — vendor/wheels/public/docs/guides.cfm lines 14–15, vendor/wheels/public/views/ai.cfm lines 311–312, vendor/wheels/tests/specs/view/guidesSidebarDiscoverySpec.cfc lines 47–48.

All three locations repeat this claim:

// a "-snapshot" suffix sorts after the matching GA, which is what we want
// (the dev snapshot wins at the same version).

It is backwards. In ASCII, . (46) > - (45), so v4-0-1.json sorts higher than v4-0-1-snapshot.json; the GA wins at the same version, not the snapshot:

$ printf '%s\n' "v4-0-1.json" "v4-0-1-snapshot.json" | sort -r
v4-0-1.json          ← GA wins, not snapshot
v4-0-1-snapshot.json

In the current repo (v4-0-0.json + v4-0-1-snapshot.json) the code still picks correctly — v4-0-1-snapshot.json wins over v4-0-0.json because the version segment 4-0-1 > 4-0-0. There is no actual bug today. The problem surfaces only if both v4-0-1.json and v4-0-1-snapshot.json exist simultaneously (a transient state during the next GA cut), in which case the in-app redirect and AI summary would serve the GA slug instead of the active dev snapshot.

Suggested replacement for the comment (no code change needed; same in all three files):

// Sidebar basenames like "v4-0-1-snapshot.json" / "v4-0-0.json" sort
// sensibly in descending lexicographic order because the version segment
// (e.g. "4-0-1") dominates — the snapshot is always named at the NEXT
// minor version while GA files carry the released version. Note: at an
// identical version prefix, "-snapshot" sorts LOWER than ".json" (ASCII
// "." > "-"), so if "v4-0-1.json" and "v4-0-1-snapshot.json" ever
// coexist the GA wins; in practice only one exists at a time.

Tests

Source-pinning tests are correct but brittle — vendor/wheels/tests/specs/view/guidesSidebarDiscoverySpec.cfc lines 19–32:

expect(source).notToInclude("v4-0-0-snapshot.json", ...);

A future comment in guides.cfm or ai.cfm that mentions the retired filename for historical context (e.g., // Previously hardcoded to v4-0-0-snapshot.json) would cause a spurious failure. The PR acknowledges this is an established pattern in the repo (guidesRedirectHeadSpec.cfc, routesViewBrowserFixturesSpec.cfc) — that is fair, and no change is needed. Noting it here so the on-call maintainer knows to look at the spec when this fires after a future doc-comment edit rather than assuming a real regression.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is substantive and technically accurate on the key finding. The misleading sort-invariant comment is real and actionable. Minor over-claim on which files contain the wrong text, but not enough to reject the analysis. Converging with changes.

Sycophancy

None detected. A did not approve without verification and correctly withheld an approval-level verdict despite the fix being sound overall.

False positives

One minor overstatement. A says "all three locations repeat this claim" and includes vendor/wheels/public/views/ai.cfm lines 311-312. The actual diff for ai.cfm reads:

// Discover the latest sidebar in the monorepo sidebars dir (snapshot
// or GA - whichever sorts highest). See vendor/wheels/public/docs/
// guides.cfm for the rationale; the same logic lives there.

"Whichever sorts highest" is neutral - it does not assert that the snapshot wins at the same version. The specific wrong claim ("a '-snapshot' suffix sorts after the matching GA") appears in guides.cfm and guidesSidebarDiscoverySpec.cfc, not in ai.cfm. A's suggested replacement comment for ai.cfm would still be an improvement, so the net fix is right even if the diagnosis slightly over-attributes.

Missed issues

None detected. The sort-invariant and test-brittleness findings are the two items worth noting. Cross-engine compat (standard ArraySort, DirectoryList with named listInfo) is fine. The ##2647 escape in string literals is correct CFML. No DCO issue: the commit's Author: is claude[bot] with a matching Signed-off-by.

Verdict alignment

A's COMMENTED verdict is defensible given the code behaviour is correct today and neither finding is blocking. The misleading comment is in production source and could mislead a future maintainer into relying on the wrong sort invariant (the comment says the snapshot wins; it does not, at an identical version prefix). A request-changes would also be reasonable, but COMMENTED is not wrong.

Convergence

Aligned with A's assessment. The comment fix A specifies is clear: update the misleading sort-invariant prose in guides.cfm and guidesSidebarDiscoverySpec.cfc (and optionally ai.cfm for precision, even though its current text is neutral rather than wrong). Address-review has sufficient detail to apply the changes.

[wheels-bot]

Wheels Bot — Address Review (round 1)

Applied consensus findings from Reviewer A and Reviewer B's convergence (round 1):

• Sort-invariant comment corrected — vendor/wheels/public/docs/guides.cfm:14-22 and vendor/wheels/tests/specs/view/guidesSidebarDiscoverySpec.cfc:44-53. The prior wording asserted that -snapshot sorts after the matching GA at the same version, which is the opposite of what textnocase desc does: . (ASCII 46) > - (ASCII 45), so the GA wins at an identical version prefix. Replaced with A's suggested wording: the version segment dominates (so the snapshot wins in practice because it carries the next minor version), and explicitly notes that at an identical version prefix the GA wins. Runtime behavior was already correct — only the explanatory prose was wrong.
• ai.cfm comment expanded — vendor/wheels/public/views/ai.cfm:308-319. B observed the prior text ("whichever sorts highest") was neutral rather than wrong, so a fix wasn't strictly required. Applied A's suggested wording anyway because (a) keeping the two files' rationale self-consistent helps a future reader who lands in ai.cfm first, and (b) A's wording is more precise.

Skipped (not in consensus):

• A's brittleness note on source-pinning tests — A explicitly said no change is needed; B did not contest. The PR description already calls out the established repo pattern (guidesRedirectHeadSpec.cfc, routesViewBrowserFixturesSpec.cfc).
• B's minor over-attribution note — B observed A slightly overstated which files contained the exact wrong-claim string. Not actionable as a code change; it's an observation about A's review prose, which B already addressed in the convergence comment.

Test run: bash tools/test-local.sh view is not runnable in this bot environment (no Wheels CLI install) — the PR body already documents this and defers to CI's Lucee 7 / Adobe / SQLite / MySQL / Postgres matrix. The changes are comment-only with zero code-path change, so no regression surface; CI on the new SHA will be authoritative.

The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on `approve` or the outer-loop cap (5 rounds) is reached.

[wheels-bot]

Wheels Bot — Reviewer A

This is a follow-on review for the round-1 fix commit (362384e97) that addressed the sort-invariant comment inversion I raised in my previous review. The fix is correct and the PR is essentially clean. I am submitting a --comment review with one nit about stale prose in the PR description.

Correctness

The round-1 commit correctly updated the comments in all three files to reflect the true ASCII ordering (. (46) > - (45), so at an identical version prefix the GA wins, not the snapshot). Runtime behavior was always correct; only the explanatory prose was wrong. That is now fixed.

The discovery logic itself is sound:

• DirectoryList(local.sidebarDir, false, "name", "*.json") returns a CFML array of basenames — consistent with the same call pattern used in Seeder.cfc, Controller.cfc, Model.cfc, and PackageLoader.cfc.
• ArraySort(local.candidates, "textnocase", "desc") sorts in-place; the code correctly reads candidates[1] afterward.
• Len(local.sidebarPath) gate before FileExists() prevents a null-path call in the no-monorepo-tree case.
• All HTML output in guides.cfm is properly encoded via encodeForHTMLAttribute / encodeForHTML.

Docs

PR description still carries the old incorrect invariant.

The PR body (Summary section) says:

sorted descending lexicographically (a -snapshot suffix sorts after the matching GA at the same version, which is the behavior we want — the dev snapshot wins)

The round-1 commit corrected this claim in the code comments and test commentary, but the PR description was not updated. As written it now contradicts the corrected comments. Future readers who audit the PR history will see conflicting explanations.

No code change is needed. Updating the PR description before merging would avoid confusion:

sorted descending lexicographically — the version segment (e.g. 4-0-1) dominates, so the active snapshot (named at the next minor version) sorts above older GA files. At an identical version prefix -snapshot sorts LOWER than .json (ASCII . > -), so if both ever coexist the GA wins; in practice only one of the pair exists at a time.

The initial commit message body (dad10aa27) also repeats the wrong invariant, but that is a historical artifact — amending a pushed commit would require a force-push that outweighs the value of fixing explanatory prose.

Tests

Source-pinning checks are correct BDD style extending wheels.WheelsTest. The third test's early return for installed-app environments (no monorepo web/ tree) is the right skip pattern and leaves CI green. No concerns.

Commits

Both commits conform to commitlint.config.js: type fix, scope view, subjects within 100 chars, not ALL-CAPS. Both carry Signed-off-by: claude[bot] for DCO compliance.

[wheels-bot]

Wheels Bot -- Reviewer B (round 1)

A's review on the round-1 fix commit is technically accurate and appropriately scoped. The single finding -- stale PR description text -- is real, A's verdict (COMMENTED, no changes required) is proportionate, and the code review itself is substantive. Converging on approve.

Sycophancy

None detected. A did not rubber-stamp. Before declaring the code clean A verified DirectoryList return type, ArraySort in-place semantics, the Len(sidebarPath) null-path guard, and HTML encoding in the original file. That is proper verification, not a formulaic LGTM.

False positives

None detected. I re-read every claim A made against the diff:

• DirectoryList(dir, false, name, *.json) -- returns a CFML array of basenames on Lucee, Adobe CF, and BoxLang. Correct.
• ArraySort(candidates, textnocase, desc) sorts in-place -- correct; CFML ArraySort modifies the passed array and returns a boolean.
• Len(local.sidebarPath) before FileExists() -- the guard is present exactly as A describes at both call sites.
• Stale PR description -- verified: the Summary section says a -snapshot suffix sorts after the matching GA at the same version, which contradicts the corrected code comments on the current HEAD.
• Commit message dad10aa27 repeats the wrong invariant -- A correctly notes amending a pushed commit requires a force-push; not actionable. A's call not to flag it as a change request is right.

Missed issues

None detected. I scanned the full diff:

• Cross-engine: DirectoryList, DirectoryExists, FileExists, FileRead, ArraySort, ExpandPath with ../ traversal, ReReplace -- all are standard CFML built-ins with consistent behaviour across Lucee, Adobe CF, and BoxLang. No cross-engine gotchas from .ai/wheels/cross-engine-compatibility.md apply here.
• ##2647 escaping in spec string literals -- correct CFML escaping; renders as #2647 at runtime without crashing the expression parser.
• BDD spec structure -- extends wheels.WheelsTest, uses describe/it/expect. The early return in the third test for the no-monorepo-tree case is the documented skip pattern; CI stays green.
• Commits -- both conform to commitlint.config.js (type fix, scope view, subjects <= 100 chars, not ALL-CAPS, Signed-off-by present).

Verdict alignment

A's COMMENTED verdict is consistent with the finding: the only item raised is PR description prose, not code. COMMENTED rather than REQUEST_CHANGES is the correct weight for a merge-time documentation nicety.

Convergence

Aligned. A's analysis is correct and the code is clean. The PR description nit is real and worth a human glance before merging, but it does not affect runtime behaviour, tests, or future maintainers reading the code (the code comments and spec commentary are already corrected). No further review iteration is needed from the bot.

[wheels-bot]

Wheels Bot — Reviewer A

This is a third-pass review, triggered by the develop-sync merge adbf097 (merging upstream fixes from #2646 into the feature branch). The merge touches five files — .ai/wheels/cross-engine-compatibility.md, CHANGELOG.md, BoxLangAdapter.cfc, and two new dispatch test assets — none of which overlap with this PR's four files (guides.cfm, ai.cfm, guidesSidebarDiscoverySpec.cfc, CHANGELOG.md entry). The effective diff is identical to what round-2 reviewed at 362384e97. No new issues found. Submitting --comment.

Docs

PR description still carries the old sort-invariant — flagged in round-2, still present.

The Summary section reads:

sorted descending lexicographically (a -snapshot suffix sorts after the matching GA at the same version, which is the behavior we want — the dev snapshot wins)

The code comments were corrected by 362384e97, but the PR body was not updated. As written it contradicts the corrected code comments and test commentary. The replacement from round-2 still stands:

sorted descending lexicographically — the version segment (e.g. 4-0-1) dominates, so the active snapshot (named at the next minor version) sorts above older GA files. At an identical version prefix -snapshot sorts LOWER than .json (ASCII . > -), so if both ever coexist the GA wins; in practice only one of the pair exists at a time.

No code change needed; this is cosmetic prose in the PR history.

Correctness, Cross-engine, Tests, Security, Commits

No new findings. All are clean per round-2. The four files owned by this PR are unchanged from 362384e97.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's third-pass review is accurate and appropriately scoped. The develop-sync merge brings only BoxLang dispatch code (no overlap with this PR's four files), A verified that explicitly, and the sole outstanding item — the stale PR description prose — is unchanged from prior rounds. Converging on approve.

Sycophancy

None detected. A did not rubber-stamp the merge commit; it explicitly verified which files were introduced by the sync and confirmed zero overlap with the PR's owned files before re-applying the prior round's clean verdict.

False positives

None detected. I re-read the diff:

• The CHANGELOG entry in the diff includes both the sidebar discovery fix (this PR) and the BoxLang dispatch entry (from BoxLang: Internal Wheels routes fail with Function [$blockInProduction] not found #2646 via the merge). A correctly describes the merge as touching .ai/wheels/cross-engine-compatibility.md, CHANGELOG.md, BoxLangAdapter.cfc, and dispatch test assets — consistent with commit a116f6000 in the git log.
• The four files this PR owns (guides.cfm, ai.cfm, guidesSidebarDiscoverySpec.cfc, CHANGELOG.md entry) are unchanged from 362384e97. A's claim holds.
• The stale PR description assertion is still accurate: the Summary section continues to say "-snapshot suffix sorts after the matching GA at the same version," which contradicts the corrected code comments on the current HEAD.

Missed issues

None detected. The merged dispatch code is outside this PR's scope and carries its own tests. No cross-engine concerns arise from the sidebar files (standard DirectoryList, ArraySort, FileExists, ReReplace — all consistent across Lucee, Adobe CF, and BoxLang). Commits conform to commitlint.config.js. The merge commit itself is not subject to the conventional-commit rules.

Verdict alignment

A's COMMENTED verdict is consistent with the finding. The only item is PR description prose — cosmetic, no code change needed, and already flagged in round-2. COMMENTED rather than REQUEST_CHANGES is the correct weight.

Convergence

Aligned. The code is clean; this is a develop-sync merge that adds nothing to review. The PR description nit is real but affects only the PR history, not the code, tests, or future maintainers (the code comments and spec commentary were corrected in 362384e97). No further bot review iteration is needed.