Legacy ForgeBox entries (cfwheels-base-template, cfwheels-cli) are broken and unsignposted — `box install cfwheels-base-template` hard-errors on the deleted `cfwheels` slug

[bpamiri]

What a 2.x user experiences today

cfwheels-base-template is still active on ForgeBox with 76,754 installs and is the top search hit for "cfwheels". Running the install it advertises (verified 2026-06-12, CommandBox 6.3.3 in ortussolutions/commandbox:latest):

box install cfwheels-base-template
# → installs 2.5.1+32 (92 files), then:
# Installing package [forgebox:cfwheels]
# ERROR: Error getting ForgeBox entry [cfwheels]
#        The entry slug sent is invalid or does not exist

The template's box.json declares "dependencies": {"cfwheels": "^2.5.1+32"} with "installPaths": {"cfwheels": "wheels/"} — but the cfwheels core slug no longer exists on ForgeBox (confirmed via api/v1/entry/cfwheels and search). The user is left with a skeleton that has no wheels/ framework folder and a hard error.

Compounding signposting problems

• The entry's homeURL is https://cfwheels.org/ — the apex domain does not resolve in DNS at all.
• The README/description on the entry contains zero mention of Wheels 4.x, the rebrand, wheels.dev, deprecation, or migration.
• cfwheels-cli (3.0.3, 3,245 installs) likewise has no 4.x pointer, and its home/source URL github.com/cfwheels/cfwheels-cli returns 404.
• docs.cfwheels.org does 301 to wheels.dev/guides and github.com/cfwheels/cfwheels 301s to wheels-dev/wheels — so the redirects exist elsewhere; only the ForgeBox entries and the apex domain were left behind.

Root cause

The legacy slugs were abandoned during the 3.x→4.x rebrand without tombstoning: the cfwheels core dependency slug was removed (breaking the still-listed template), and the remaining entries were never given a final "this moved" release or description update.

Proposed fix (pick per-slug)

1. cfwheels-base-template: publish a final patch release whose README + ForgeBox description state "CFWheels is now Wheels — see https://wheels.dev; for new apps use wheels new or box install wheels-base-template", and either (a) fix the dependency (restore/alias a cfwheels slug containing the 2.5.x core) so the last 2.x experience actually works, or (b) strip the dead dependency and print pointer-only content. Alternatively unlist the entry if a working 2.x install is no longer a goal.
2. cfwheels-cli: update description/README with the same tombstone + pointer to the v4 CLI install docs; fix the 404 source URL (repo moved).
3. cfwheels.org apex DNS: if the domain is still owned, point it at wheels.dev like the docs. subdomain already is.

Acceptance criteria

• box install cfwheels-base-template either completes with a working 2.5.x app or clearly tells the user where to go — no dead-slug stack trace.
• Both legacy entries' first paragraph on forgebox.io mentions Wheels 4.x / wheels.dev.
• No URL on either entry resolves to NXDOMAIN or 404.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Triage

Classified as other (general discussion / support / docs request).
No further bot action will be taken on this issue.

<!-- wheels-bot:triage:3182 -->
<!-- wheels-bot:triage-class:other -->

[bpamiri]

Deprecation runbook (credentialed maintainer action)

This is the procedure to close out #3182. It requires ForgeBox credentials (wheels-dev account, secrets in op://Wheels/), so it is a manual step for @bpamiri — nothing here has been executed automatically. The publish pipeline is already guarded against ever pushing a 4.0 artifact to a cfwheels-* slug (the slug-allowlist assert in tools/build/scripts/publish-to-forgebox.sh, shipped in PR #3200), so the legacy slugs are frozen — this just caps them with forward-pointing deprecation content.

The four files (two README.md, two box.json) are pre-staged on the maintainer's machine under /tmp/deprecate/{cfwheels-base-template,cfwheels-cli}/ and validated; the runbook below reproduces them so they're recorded here permanently.

Full runbook (click to expand)

Legacy ForgeBox Slug Deprecation Runbook (Refs #3182)

Audience: Peter (the only ForgeBox-credentialed maintainer)
Status: Manual, credentialed action. NOTHING here has been executed by the agent.
Goal: Cap the two deprecated 2.x ForgeBox slugs with a deprecation README +
description that redirect users to the 4.x slugs and wheels.dev, so a 2.x user
running box install cfwheels-base-template today (currently lands a broken
2.5.1 install) instead sees a clear "this is frozen, here's where to go" message.

---

Background / why this is needed

box publish derives the published slug from the package's box.json["slug"],
not from any CLI argument. The 4.0 release pipeline only ever publishes the
wheels-* slugs (wheels-base-template, wheels-core, wheels-cli,
wheels-starter-app) — verified, and now guarded by a slug-allowlist assert in
tools/build/scripts/publish-to-forgebox.sh (PART A of #3182). So the legacy
slugs will never receive a 4.0 artifact; they are simply frozen at their last
2.x version.

Two legacy slugs are affected:

Legacy slug (FROZEN)	Replacement 4.x slug	Notes
cfwheels-base-template	wheels-base-template	~76k installs — highest-traffic slug
cfwheels-cli	wheels-cli	CommandBox CLI module

A user box install-ing either gets the last-published 2.x build, which no
longer works end-to-end. We cannot delete a ForgeBox slug (and shouldn't — the
install count and inbound links have SEO/discovery value), so we instead publish
a final, clearly-deprecated revision whose README + description point forward.

---

Decision: two viable approaches

ForgeBox lets you change a package's description without re-publishing, and
the README is whatever ships in the latest published version's
README.md / readme field. Pick ONE:

• Approach A (recommended): publish a final deprecation revision. Bump the
  version on each legacy slug and publish a tiny package whose only meaningful
  content is the deprecation README below. This is what users see on the
  ForgeBox web UI and what box install pulls. Most durable.
• Approach B (lighter): update the ForgeBox description/metadata only. Fast,
  no new artifact, but box install still pulls the old broken code. Use only if
  you can't cut a fresh artifact right now. Run the box forgebox describe
  commands in step 4 and stop there.

The rest of this runbook assumes Approach A and falls back to B at the end.

---

Step 1 — DEPRECATION README content

Create this file as README.md in each legacy package's publish directory.
(Two near-identical copies — one per slug. The only differences are the slug name
and the replacement slug.)

cfwheels-base-template → README.md

# ⚠️ DEPRECATED — `cfwheels-base-template` is frozen

**This ForgeBox slug is no longer maintained and will not receive updates.**

`box install cfwheels-base-template` installs an old, end-of-life Wheels 2.x
base template that no longer works with current tooling. It is preserved only so
existing references don't 404.

## What to use instead

Wheels 4.x is distributed under the **`wheels-*`** slugs and through the official
`wheels` CLI:

- New apps: install the CLI and run `wheels new`, or `box install wheels-base-template`
- Framework core: `wheels-core`
- CLI commands module: `wheels-cli`
- Starter app: `wheels-starter-app`

## Getting started with Wheels 4.x

Follow the current install + quick-start guide at **https://wheels.dev**.

The recommended path is the `wheels` CLI (Homebrew / Scoop / apt / yum — see
https://wheels.dev for your platform), then:

```bash
wheels new myapp
cd myapp
wheels start

Why the rename?

The project rebranded from "CFWheels" to Wheels at v3.0. The cfwheels-*
slugs predate that rebrand. All current packages live under wheels-*.

Questions / issues: https://github.com/wheels-dev/wheels/issues

### `cfwheels-cli` → `README.md`

```markdown
# ⚠️ DEPRECATED — `cfwheels-cli` is frozen

**This ForgeBox slug is no longer maintained and will not receive updates.**

`box install cfwheels-cli` installs the old CommandBox-based Wheels 2.x CLI,
which cannot drive Wheels 4.x.

## What to use instead

Wheels 4.x ships its own first-party CLI (the `wheels` binary, built on the LuCLI
runtime — no CommandBox required). Install it from your platform's package
manager (Homebrew / Scoop / apt / yum) as documented at **https://wheels.dev**.

If you specifically need the ForgeBox CommandBox module for a 4.x project, it is
published under the **`wheels-cli`** slug.

## Getting started

```bash
# install the wheels CLI (see https://wheels.dev for your platform)
wheels new myapp
cd myapp
wheels start

Questions / issues: https://github.com/wheels-dev/wheels/issues

---

## Step 2 — minimal `box.json` for each deprecation revision

Keep the package empty except for the README and a small, clearly-deprecated
description. The `version` MUST be higher than the slug's current latest so
ForgeBox accepts the publish and serves it as "current". Check the current
latest first (step 3) and bump accordingly. Suggested versions assume the
legacy slugs are at 2.x — use a clearly-final marker.

### `cfwheels-base-template` → `box.json`

```json
{
    "name": "CFWheels Base Template (DEPRECATED — use wheels-base-template)",
    "slug": "cfwheels-base-template",
    "version": "2.5.2",
    "author": "Wheels Core Team and Community",
    "shortDescription": "DEPRECATED. Frozen Wheels 2.x base template. Use the wheels-* slugs / the wheels CLI for 4.x — see https://wheels.dev",
    "location": "forgeboxStorage",
    "type": "cfwheels-templates",
    "homepage": "https://wheels.dev/",
    "documentation": "https://wheels.dev/docs",
    "repository": { "type": "git", "URL": "https://github.com/wheels-dev/wheels" },
    "bugs": "https://github.com/wheels-dev/wheels/issues",
    "keywords": ["deprecated", "wheels", "cfwheels", "mvc"],
    "private": false,
    "license": [
        { "type": "Apache License 2.0", "URL": "https://github.com/wheels-dev/wheels/blob/main/LICENSE" }
    ]
}

cfwheels-cli → box.json

{
    "name": "CFWheels CLI (DEPRECATED — use the wheels CLI / wheels-cli)",
    "slug": "cfwheels-cli",
    "version": "2.5.2",
    "author": "Wheels Core Team and Community",
    "shortDescription": "DEPRECATED. Frozen Wheels 2.x CommandBox CLI. Use the first-party wheels CLI for 4.x — see https://wheels.dev",
    "location": "forgeboxStorage",
    "type": "commandbox-modules",
    "homepage": "https://wheels.dev/",
    "documentation": "https://wheels.dev/docs",
    "repository": { "type": "git", "URL": "https://github.com/wheels-dev/wheels" },
    "bugs": "https://github.com/wheels-dev/wheels/issues",
    "keywords": ["deprecated", "wheels", "cfwheels", "cli"],
    "private": false,
    "license": [
        { "type": "Apache License 2.0", "URL": "https://github.com/wheels-dev/wheels/blob/main/LICENSE" }
    ]
}

NOTE: 2.5.2 is a placeholder bump above the assumed last-published 2.5.1.
Confirm the real current version in step 3 and set version to the next patch
above it. If the current latest is NOT 2.5.1, adjust both files.

---

Step 3 — check current published versions FIRST

# What does ForgeBox currently serve for each legacy slug?
box forgebox show cfwheels-base-template
box forgebox show cfwheels-cli

Note the "Latest Version" / "Latest Stable" reported for each. Your deprecation
box.json version must be strictly greater than that, or ForgeBox will reject
the publish (or not promote it to current). Adjust the version fields in step 2
to be <currentLatest> + one patch.

---

Step 4 — publish the deprecation revisions (Approach A)

Run from a clean scratch directory per slug. Each directory should contain ONLY
the README.md (step 1) and box.json (step 2) for that slug.

# --- log in once (use the wheels-dev ForgeBox account) ---
box forgebox login
#   username: wheels-dev
#   password: <FORGEBOX_PASS — from op://Wheels/ , the same secret release.yml uses>

# --- cfwheels-base-template ---
mkdir -p /tmp/deprecate/cfwheels-base-template
cd /tmp/deprecate/cfwheels-base-template
#   ... drop README.md + box.json here (from steps 1 & 2) ...
box publish --force

# --- cfwheels-cli ---
mkdir -p /tmp/deprecate/cfwheels-cli
cd /tmp/deprecate/cfwheels-cli
#   ... drop README.md + box.json here (from steps 1 & 2) ...
box publish --force

# --- log out ---
box forgebox logout

--force is required because we are re-publishing an existing slug. box publish
reads box.json["slug"] from the current directory, so make absolutely sure you
are inside the correct per-slug directory before each publish.

Optional: also set the short description without re-publishing (Approach B / belt-and-suspenders)

If your CommandBox version exposes the metadata-update verb, you can also push the
description directly (this updates the ForgeBox listing text immediately, even
before the new README propagates):

box forgebox describe slug=cfwheels-base-template \
  description="DEPRECATED. Frozen Wheels 2.x base template. Use wheels-base-template / the wheels CLI for 4.x — see https://wheels.dev"

box forgebox describe slug=cfwheels-cli \
  description="DEPRECATED. Frozen Wheels 2.x CLI. Use the first-party wheels CLI for 4.x — see https://wheels.dev"

If box forgebox describe is not available in your CommandBox build, use the
ForgeBox web UI: log in at https://forgebox.io, open each package's Edit page,
and paste the same description + README. The ForgeBox REST API equivalent is
PUT https://forgebox.io/api/v1/entry/<slug> with an
Authorization: Bearer <FORGEBOX_API_TOKEN> header and a JSON body
{ "description": "...", "summary": "..." } (token = op://Wheels/...,
the FORGEBOX_API_TOKEN release secret).

---

Step 5 — verify

# Web listing should now show the DEPRECATED name + description:
box forgebox show cfwheels-base-template
box forgebox show cfwheels-cli

# A fresh install should pull the deprecation README, not the broken 2.5.1 app:
mkdir -p /tmp/verify-deprecation && cd /tmp/verify-deprecation
box install cfwheels-base-template
cat cfwheels-base-template/README.md   # expect the ⚠️ DEPRECATED text

Confirm:

• ForgeBox listing for both slugs shows the "DEPRECATED — use …" name + description.
• box install cfwheels-base-template lands the deprecation README (not a 2.5.1 app).
• box install cfwheels-cli lands the deprecation README.
• The 4.x wheels-* slugs are unaffected (box forgebox show wheels-base-template still current).

---

Credentials reference

• ForgeBox account: wheels-dev
• FORGEBOX_PASS and FORGEBOX_API_TOKEN: live in op://Wheels/ (the wheels.dev
  personal 1Password vault — NOT op://Infrastructure/). These are the same
  secrets release.yml consumes.

Rollback

These publishes are additive (a new version on an existing slug). If anything
looks wrong, you can publish another revision with corrected content. You cannot
un-publish a version, so double-check the README text before box publish.