docs(web/guides): add Installing with CommandBox support-tier page#3198
Merged
Conversation
…3183) The v4-0-0 guides contained zero `box install` mentions, leaving CommandBox-centric 2.x/3.x teams with no answer to "what is my supported workflow now?" despite release.yml publishing four ForgeBox packages on every stable release. Add a new start-here page that states the support tier explicitly: - Supported: install the framework via ForgeBox (`box install wheels-base-template` -> wheels-core in vendor/wheels/) and serve it (`box server start`, reload URL, engine pinning). - Not supported via CommandBox: the `wheels` CLI feature set (generators, migrate, test, console, MCP, packages registry, deploy) — install the LuCLI `wheels` binary from brew/scoop/apt/yum for those. - Legacy-slug note: `wheels-cli` ForgeBox module is deprecated (removal in v5); points at the 4.x slugs. - 2.x/3.x box-workflow -> 4.0 mapping table. Written to the campaign target end-state (assumes #3176/#3173 keystone template fix and #3177 core box.json fix land — #3177 already on develop: core box.json uses directory=vendor + packageDirectory=wheels, base template installPaths puts wheels-core in vendor/wheels/). Box command blocks are marked illustrative (untagged) per the {test:*} policy — the verify-docs harness only runs the `wheels` binary, not `box`, so they are correctly ignored. Adds the sidebar entry and cross-links from installing.mdx and cfml-engines.mdx. pnpm verify:docs on the page exits 0 (0 tagged blocks). Fixes #3183. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Peter Amiri <peter@alurium.com>
bpamiri
added a commit
that referenced
this pull request
Jun 24, 2026
…ect to wheels-base-template (#3253) The Installing with CommandBox page existed to give 2.x/3.x CommandBox teams a clear Wheels 4 answer, but it never mentioned the slug a migrating 2.x user actually has in muscle memory: `box install cfwheels-base-template`. That pre-rebrand slug still resolves on ForgeBox (76,754 installs, top 'cfwheels' search hit) but errors on its missing `cfwheels` core dependency and leaves an unrunnable skeleton. Worse, the 2.x/3.x migration table claimed `box install wheels-base-template` + `wheels-core` was 'Unchanged' — inaccurate for a genuine 2.x user, whose slug DID change (cfwheels-base-template -> wheels-base-template). The row now reads 'Slug changed' and a caution Aside maps the dead cfwheels- prefixed slugs to the supported 4.x slugs (cfwheels-base-template -> wheels-base-template, cfwheels -> wheels-core). Refs #3198 (post-merge review finding) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Peter Amiri <petera@pai.com> Co-authored-by: Peter Amiri <petera@pai.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a new v4-0-0 guides page, Installing with CommandBox (
web/sites/guides/src/content/docs/v4-0-0/start-here/installing-with-commandbox.mdx), plus sidebar entry and cross-links. Part of the ForgeBox/CommandBox path-repair campaign.Why
The v4 guides contained zero
box installmentions (verified:grep -rl 'box install' .../v4-0-0/→ 0 files), even thoughrelease.ymlpublishes four ForgeBox packages (wheels-base-template,wheels-core,wheels-cli,wheels-starter-app) on every stable release. CommandBox-centric 2.x/3.x teams had no answer to "what is my supported workflow on Wheels 4?"What the page states (the support tier, explicitly)
box install wheels-base-templatepullswheels-coreintovendor/wheels/;box server startserves it; reload URL + engine pinning documented.box install wheels-corefor vendoring/upgrading an existing app.wheelsCLI feature set — generators,migrate,test,console, MCP, the packages registry (CLI-only, not ForgeBox), deploy — install the LuCLIwheelsbinary (brew/scoop/apt/yum/manual JAR) for those.wheels-cliForgeBox module is deprecated (removal in v5), points at the 4.x slugs andwheels new.Written to the campaign target end-state (assumes keystone template fix #3176/#3173 and core fix #3177 land). #3177 is already on develop —
tools/build/core/box.jsonusesdirectory=vendor+packageDirectory=wheels, and the base template'sinstallPathsputswheels-coreinvendor/wheels/.{test:*} policy
The verify-docs harness only spawns the
wheelsbinary — it cannot runbox. Per the policy (harness ignores any block without a{test:*}meta flag;lib/extract.mjsif (!parsed) continue;), allboxcommand blocks are marked illustrative (untagged with descriptive titles). Verified against the same approach already used bycfml-engines.mdx.Evidence
grep -rl 'box install' web/sites/guides/src/content/docs/v4-0-0/→ 0 files before this change.pnpm verify:docs(vianode scripts/verify-docs/verify-docs.mjs <new page>): EXIT=0,0 passed, 0 failed,found 0 tagged block(s)— box blocks correctly ignored as illustrative.installing.mdx+cfml-engines.mdx: 1 passed, 0 failed (the 1 is the pre-existingwheels --version{test:cli}block ininstalling.mdx).json.loadafter the edit.upgrading/3x-to-4x/,digging-deeper/packages/,command-line-tools/installation/#manual-jar-install).No changelog fragment — docs-only change (build-pipeline + CI + docs changes get none).
Fixes #3183.
Refs #3176, #3173, #3177.
🤖 Generated with Claude Code