wheels-dev
diff --git a/‎.ai/wheels/testing/browser-testing.md‎
Lines changed: 2 additions & 1 deletion b/‎.ai/wheels/testing/browser-testing.md‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎.ai/wheels/troubleshooting/common-errors.md‎
Lines changed: 20 additions & 0 deletions b/‎.ai/wheels/troubleshooting/common-errors.md‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎.ai/wheels/troubleshooting/shared-dev-databases.md‎
Lines changed: 103 additions & 0 deletions b/‎.ai/wheels/troubleshooting/shared-dev-databases.md‎
Lines changed: 103 additions & 0 deletions
diff --git a/‎.github/RELEASE_PLAYBOOK.md‎
Lines changed: 35 additions & 14 deletions b/‎.github/RELEASE_PLAYBOOK.md‎
Lines changed: 35 additions & 14 deletions
diff --git a/‎.github/workflows/bot-review-a.yml‎
Lines changed: 8 additions & 1 deletion b/‎.github/workflows/bot-review-a.yml‎
Lines changed: 8 additions & 1 deletion
diff --git a/‎.github/workflows/bump-develop-version.yml‎
Lines changed: 5 additions & 0 deletions b/‎.github/workflows/bump-develop-version.yml‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎.github/workflows/release.yml‎
Lines changed: 23 additions & 6 deletions b/‎.github/workflows/release.yml‎
Lines changed: 23 additions & 6 deletions
diff --git a/‎.github/workflows/snapshot.yml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/snapshot.yml‎
Lines changed: 1 addition & 1 deletion
@@ -59,10 +59,11 @@ bash tools/test-local.sh                    # skips browser specs if JARs missin
 
 ## Key gotchas
 
+- **`this.browser` is not wired in plain `describe()` blocks.** Calling any DSL method on `this.browser` outside a `browserDescribe()` block throws `Wheels.BrowserTest.NotWired` (message names `browserDescribe()` as the fix; `detail` names the method that was called). The sentinel `UnwiredBrowserGuard` is installed at construction and after each `$endBrowserContext()` teardown.
 - **`##` in selectors** — CFML requires `##` to emit literal `#`. `"##email"` → `"#email"` at runtime.
 - **`client` is a Lucee reserved scope.** `var client = ...` in a closure throws "client scope is not enabled". Use `var c = ...` or `var bc = ...`. (Generalized rule: see CLAUDE.md anti-pattern #11.)
 - **Data URLs work for most tests** — no server needed for ~95% of DSL coverage. Full HTTP integration (cookies, form submits, redirects) needs a running fixture app; that wiring is the same as Wheels Web app bootstrap (separate server + baseUrl).
 - **`this.browserTestSkipped`** — when Playwright JARs aren't installed (fresh CI, clean machine), `beforeAll` sets this flag and `browserDescribe`'s hooks short-circuit. All `it`s should check `if (this.browserTestSkipped) return;` to stay green on CI.
-- **CI runs browser tests** — `pr.yml` and `snapshot.yml` install Playwright JARs + Chromium (cached via `browser-manifest.json` hash). Browser specs run as part of the normal test suite. `WHEELS_BROWSER_TEST_BASE_URL=http://localhost:60007` is set automatically.
+- **CI runs browser tests** — `pr.yml` and `snapshot.yml` install Playwright JARs + Chromium (cached via `browser-manifest.json` hash). Browser specs run as part of the normal test suite. `WHEELS_BROWSER_TEST_BASE_URL=http://localhost:60007` is set automatically. The base URL is resolved at instance time through a layered lookup (`this.baseUrl` → Wheels setting → JVM property `wheels.browserTest.baseUrl` → env var → CGI auto-detect → `http://localhost:8080`); per-spec `this.baseUrl` takes priority over the env var. Set `this.baseUrl` in the component pseudo-constructor (outside any function), not inside `beforeAll()` — `super.beforeAll()` calls `$resolveBaseUrl()` and caches the result, so a `this.baseUrl =` assignment that runs after `super.beforeAll()` is silently ignored.
 - **Fixture routes** — `/_browser/login-as` and `/_browser/logout` are mounted automatically in test mode. They must come before `.wildcard()` in routes.cfm. In the Routes UI (`/wheels/routes`) all `/_browser/*` routes appear under the **Internal** tab, not Application.
 - **Dialogs are Lucee-only** — `acceptDialog`, `dismissDialog`, `dialogMessage` use `createDynamicProxy` which is Lucee-specific. Specs skip gracefully on other engines.
@@ -9,6 +9,26 @@ Frequent issues encountered when developing Wheels applications and their soluti
 - Association syntax has specific Wheels conventions
 - Migration parameter binding can be unreliable
 
+## Startup / Initialization Errors
+
+### "Application Error — Wheels failed to initialize"
+**Error (on-page):**
+```
+Application Error
+Wheels failed to initialize. Check the server log for details.
+<pre>could not find component or class with name [wheels.Injector]</pre>
+```
+
+**Cause:** `onApplicationStart` threw before `application.wo` was assigned — typically because the `/wheels` CFML mapping points to a directory that doesn't contain `Injector.cfc`. The `onError` handler now surfaces the original exception text instead of cascading into "The key [WO] does not exist" (fixed in [#2774](https://github.com/wheels-dev/wheels/pull/2774)).
+
+**Resolution:**
+1. Read the `<pre>` block — it contains the original error (missing class, path mismatch, etc.).
+2. Check the server log for the full stack trace from `onApplicationStart`.
+3. Verify the `/wheels` mapping resolves: on a fresh install, `vendor/wheels/Injector.cfc` must exist. If it doesn't, re-run `wheels new` or copy the framework files manually.
+4. Run `wheels reload` (or stop/start the server) to pick up the corrected mapping.
+
+**Note:** Before the #2774 fix, this failure cascaded into a second `[WO] does not exist` exception that hid the real cause. If you see the old cascade on a version that predates this fix (i.e. 4.0.1 or earlier), the underlying cause is always a failed `onApplicationStart` — see above.
+
 ## Common Association Errors
 
 ### "Missing argument name" in hasMany()
 
@@ -0,0 +1,103 @@
+# Shared Development Databases
+
+Short reference for the orphan-migration case. User-facing version lives at
+`web/sites/guides/src/content/docs/v4-0-0/basics/shared-development-databases.mdx`.
+
+## What's an orphan?
+
+A row in `wheels_migrator_versions` whose `version` timestamp has no matching
+file in `app/migrator/migrations/`. Common cause: shared dev DB, peer ran
+their migration first against the shared DB before their file was merged.
+
+## Detection
+
+`Migrator.cfc::$getOrphanVersions()` — returns an array of orphan version
+strings, sorted ascending. Excludes the sentinel `"0"` returned when the
+tracking table is empty.
+
+## Display
+
+`wheels migrate info` marks orphan rows with `[?]` and the literal
+`********** NO FILE **********` (Rails-style). Includes a footer
+explaining the cause. Rendering logic lives in
+`Migrator.cfc::$buildInfoOutput()` so it's unit-testable without the HTTP
+dispatcher.
+
+## Behavior in `migrateTo()`
+
+If `currentVersion > target` ONLY because of orphans (no local file with
+version > target marked migrated), the down branch is skipped. Either:
+
+- Pending local migrations exist → fall through to up branch with a
+  warning naming the orphans
+- Nothing pending → emit "Nothing to do" naming current vs target and
+  return immediately
+
+If SOME DB versions > target are orphans and SOME have local files, the
+down branch runs as usual but emits a warning naming the orphans (they
+get skipped by the existing loop because it iterates files only).
+
+## Schema enrichment (Plan 3)
+
+`wheels_migrator_versions` carries two extra columns added in 4.0.x:
+`name VARCHAR(255) NULL` and `applied_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP`
+(`TEXT` on SQLite — DEFAULT not supported on existing-table ADD COLUMN).
+Added automatically on first migrator call via `$ensureTrackingColumns()`,
+gated by `application[appKey].$trackingColumnsEnsured` cache so the ALTER
+runs once per app process. Failure is non-fatal (legacy schema still works).
+
+Populated by `$setVersionAsMigrated(version, migrationName)` when:
+- The enriched columns flag is set, AND
+- The caller passes a non-empty `migrationName`
+
+Read by `$getOrphanVersionsWithMeta()` → array of `{version, name, appliedAt}`
+structs. Falls back to bare-version structs when columns aren't ensured
+or the SELECT fails (e.g. concurrent connection hasn't committed the ALTER).
+
+Display via `$buildInfoOutput()` and `cli.cfm`'s `doctor` case render:
+- `[x] <version> <name>` for applied local-file rows (timestamps are only
+  surfaced on orphan rows because `getAvailableMigrations()` doesn't
+  re-query the tracking table for applied_at on local files)
+- `[?] <version> ********** NO FILE **********` for legacy NULL orphans
+- `[?] <version> <name> (applied <timestamp>)` for enriched orphans
+
+Existing rows (pre-enrichment) get NULL for both columns. Going-forward-only;
+no backfill at bootstrap time.
+
+## Reconciliation commands
+
+Three CLI subcommands for manual reconciliation against the tracking
+table (Flyway `validate` / `repair` / `SkipExecutingMigrations`
+analogues):
+
+- `wheels migrate doctor` — comprehensive health report. Reads
+  `Migrator.doctor()`. Pure read; no mutation. Reports orphans,
+  pending, and applied counts with a human-readable summary.
+- `wheels migrate forget <version> --yes` — removes a single row
+  from `wheels_migrator_versions`. Requires `--yes`. Refuses if the
+  version has a matching local file (use `migrate down` instead) or
+  if it's not in the tracking table.
+- `wheels migrate pretend <version> --yes` — inserts a row without
+  running `up()`. Requires `--yes`. Refuses if already applied or
+  if no local file matches.
+
+Implementation:
+- `Migrator.cfc::doctor()`, `forgetVersion()`, `pretendVersion()`
+- `cli.cfm` cases: `doctor`, `forgetVersion`, `pretendVersion`
+- `Module.cfc::runForgetOrPretend()` handles `--yes` gating
+- Tests: `vendor/wheels/tests/specs/migrator/MigratorReconciliationSpec.cfc`
+
+## Related
+
+- Issue #2780 (the original report)
+- PR #2798 (orphan detection + info display + docs, merged 2026-05-22)
+- `vendor/wheels/Migrator.cfc::$getOrphanVersions()`
+- `vendor/wheels/Migrator.cfc::$buildInfoOutput()`
+- `vendor/wheels/Migrator.cfc::doctor()`
+- `vendor/wheels/Migrator.cfc::forgetVersion()`
+- `vendor/wheels/Migrator.cfc::pretendVersion()`
+- `vendor/wheels/tests/specs/migrator/OrphanDetectionSpec.cfc`
+- `vendor/wheels/tests/specs/migrator/MigratorInfoSpec.cfc`
+- `vendor/wheels/tests/specs/migrator/MigratorReconciliationSpec.cfc`
+- Follow-up work (separate PR):
+  - Schema enrichment of `wheels_migrator_versions` (add `name` and `applied_at` columns)
@@ -29,25 +29,45 @@ on them is green. ~5 minutes/day max.
 
 1. **Cherry-pick or merge stabilization commits to `release/X.Y.Z`** if using a
    release-branch workflow. Skip this if cutting directly from develop.
-2. **Update `CHANGELOG.md`** with the release date (replace `=> TBD` for the
-   target version). `release.yml` will refuse to publish if it sees TBD on the
-   target version.
-3. **Verify `box.json` version** matches what you want to release. After the
-   last GA, the `bump-develop-version.yml` workflow set it to next-patch; if
-   you're shipping a bigger bump, update it manually.
+2. **Update `CHANGELOG.md`**: rename `# [Unreleased]` to
+   `# [X.Y.Z](...) => YYYY-MM-DD` with the real release date (replace any
+   `=> TBD`). Then confirm the separator line directly below the renamed
+   section is exactly `---` (three dashes), NOT `----`. `release.yml` refuses
+   to publish if it sees TBD on the target version, and also fails if a `----`
+   separator would make the release-notes awk bleed into the previous version's
+   notes (recurring footgun — see #2606, #2768; now guarded in `release.yml`).
+3. **Verify `wheels.json` version** matches what you want to release.
+   `wheels.json` is the canonical version source since the 4.0 rebrand (the
+   workflows read it; `box.json` is legacy and may be absent or empty). After
+   the last GA, the `bump-develop-version.yml` workflow set it to next-patch;
+   if you're shipping a bigger bump, update it manually.
 
 ### Release day
 
-```bash
-# 1. On main, fast-forward from the release branch.
-git checkout main
-git merge --ff-only release/X.Y.Z   # (or develop, if no release branch)
+`main` has a **"PRs only" ruleset** — `git push origin main` is rejected with
+`GH013`. You also never tag manually: `release.yml` auto-creates the tag via
+`softprops/action-gh-release` once the merge lands on main.
 
-# 2. Tag and push. release.yml fires automatically.
-git tag -a vX.Y.Z -m "Release X.Y.Z"
-git push origin main --tags
+```bash
+# 1. Open a PR into main from a release branch. (Cutting from develop directly
+#    is fine — just branch off develop so the PR has a head ref to merge.)
+git checkout develop && git pull
+git checkout -b release/X.Y.Z-to-main
+git push -u origin release/X.Y.Z-to-main
+gh pr create --base main --head release/X.Y.Z-to-main \
+  --title "Release X.Y.Z" --body "Cut X.Y.Z. See CHANGELOG."
+
+# 2. Merge with "Create a merge commit" (NOT squash — preserves develop
+#    history on main).
+gh pr merge --merge --delete-branch
 ```
 
+The push-to-main from that merge triggers `release.yml`, which builds the
+artifacts and calls `softprops/action-gh-release` with `tag_name: vX.Y.Z`,
+creating the tag at main HEAD automatically. Do **not** run `git tag` /
+`git push --tags` — the legacy `git push origin main --tags` flow is rejected
+by the ruleset anyway.
+
 The tag push triggers:
 - `release.yml` builds artifacts, publishes to `wheels-dev/wheels/releases`
 - `release.yml`'s "Dispatch downstream package managers" step then fires
@@ -149,7 +169,8 @@ If any pin to `<X.Y.Z`, open issues on those repos to widen the constraint.
 | Symptom | Cause | Fix |
 |---|---|---|
 | `release.yml` fails: "CHANGELOG contains TBD" | Forgot to update changelog | Add release date to `# [X.Y.Z]` line, push, re-run workflow |
-| `release.yml` fails: "version contains -SNAPSHOT" | `box.json` has `-SNAPSHOT` suffix on main | Strip suffix, push (release.yml asserts clean main versions) |
+| `release.yml` fails: "release-notes range … bleeds into a later version section" | Separator below the target version is `----` (4 dashes), not `---` — the awk extraction overruns into the previous version | Change that separator line to exactly `---`, push, re-run |
+| `release.yml` fails: "version contains -SNAPSHOT" | `wheels.json` has a `-snapshot` suffix on main | Strip the suffix in `wheels.json`, push (release.yml asserts clean main versions) |
 | brew tap PR doesn't open after release | `DOWNSTREAM_DISPATCH_TOKEN` expired or unset | Rotate token in repo secrets; re-run `release.yml` workflow_dispatch |
 | develop-bump PR doesn't open after GA | `DOWNSTREAM_DISPATCH_TOKEN` expired/unset, OR the `bump-develop` dispatch step warned and exited 0 | Fire it manually: Actions → "Bump Develop Version" → "Run workflow" → enter the just-released version (e.g. `4.0.0`). The workflow has a `workflow_dispatch` fallback for exactly this case. |
 | `brew install wheels` post-release fails | Formula sha256 mismatch | Re-run the tap bump workflow with `workflow_dispatch` to recompute |
 
@@ -143,9 +143,16 @@ jobs:
         run: |
           set -euo pipefail
 
+          # Allow-list APPROVED and CHANGES_REQUESTED only: those are the
+          # exclusive set of states that (a) GitHub's dismiss API accepts and
+          # (b) gate merging. Feeding the dismiss API any other state returns
+          # HTTP 422 — e.g. "Can not dismiss a commented pull request review"
+          # for COMMENTED, the same shape for PENDING — which would fail this
+          # step and red-X the check. Originally observed on PR #2795 commit
+          # 0db188a5 when a COMMENTED placeholder leaked through.
           reviews=$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews" --paginate \
             | jq -c --arg sha "$HEAD_SHA" \
-                '[.[] | select(.user.login == "wheels-bot[bot]") | select(.commit_id == $sha) | select(.state != "DISMISSED")]')
+                '[.[] | select(.user.login == "wheels-bot[bot]") | select(.commit_id == $sha) | select(.state == "APPROVED" or .state == "CHANGES_REQUESTED")]')
 
           count=$(echo "$reviews" | jq 'length')
           if [[ "$count" == "0" ]]; then
 
@@ -61,6 +61,11 @@ jobs:
         with:
           ref: develop
           fetch-depth: 1
+          # Don't persist GITHUB_TOKEN as a git extraheader — peter-evans/create-pull-request
+          # below sets its own Authorization, and two simultaneous extraheaders make GitHub
+          # reject git operations with "Duplicate header: Authorization" → HTTP 400.
+          # First hit on the v4.0.1 GA (run 26173817714); manual workaround was #2770.
+          persist-credentials: false
 
       - name: Compute next snapshot target
         run: |
 
@@ -23,7 +23,7 @@ on:
       DOWNSTREAM_DISPATCH_TOKEN:
         required: false
       # Optional — when present, the build job's "Dispatch Linux repo buckets"
-      # step fires repository_dispatch on apt-wheels-dev / yum-wheels-dev so
+      # step fires repository_dispatch on apt-wheels / yum-wheels so
       # their metadata regen workflows pick up the new .deb/.rpm and republish
       # apt.wheels.dev / yum.wheels.dev within minutes. When absent, the step
       # skips silently — the bucket repos can be populated manually via each
@@ -105,6 +105,23 @@ jobs:
             exit 1
           fi
 
+          # Check that the CHANGELOG separator below this version is exactly
+          # '---' (3 dashes). The release-notes extraction step below uses the
+          # awk range /^# \[VERSION\]/,/^---$/, which terminates ONLY on a line
+          # of exactly three dashes; a '----' (4-dash) separator silently
+          # extends the range into the PREVIOUS version's notes. We mirror that
+          # exact awk here and fail if the extracted range pulls in another
+          # version heading. (Recurring footgun — see #2606, #2768.)
+          VERSION_PATTERN=$(echo "${WHEELS_VERSION%+*}" | sed 's/\./\\./g')
+          BLED=$(awk '/^# \['"${VERSION_PATTERN}"'\]/,/^---$/ {print}' CHANGELOG.md \
+            | tail -n +2 | grep -cE '^# \[' || true)
+          if [ "${BLED}" -ne 0 ]; then
+            echo "ERROR: CHANGELOG release-notes range for [${WHEELS_VERSION%+*}] bleeds into a later version section."
+            echo "The separator directly below the [${WHEELS_VERSION%+*}] block must be exactly '---' (3 dashes), not '----'."
+            echo "This check mirrors the awk extraction used to build the GitHub Release notes."
+            exit 1
+          fi
+
           # Check that source version in wheels.json is clean (no -snapshot suffix).
           # The workflow injects -snapshot.N for develop builds automatically.
           BASE_VERSION=$(jq -r '.version' wheels.json)
@@ -306,7 +323,7 @@ jobs:
         # CHANNEL derives from the version so develop snapshots produce the
         # `wheels-be` package (which the Phase 2 bleeding-edge receiver
         # downloads) instead of `wheels`. Without this, the snapshot release
-        # ships `wheels_<v>_amd64.deb` and the apt-wheels-dev / yum-wheels-dev
+        # ships `wheels_<v>_amd64.deb` and the apt-wheels / yum-wheels
         # receiver workflow 404s on its `wheels-be_<v>_amd64.deb` fetch.
         # RC builds keep CHANNEL=stable — RCs aren't fanned out to apt/yum
         # (see release.yml § "Dispatch Linux repo buckets").
@@ -588,8 +605,8 @@ jobs:
       #############################################
       # Dispatch Linux repo buckets (apt.wheels.dev / yum.wheels.dev)
       #
-      # Fires repository_dispatch on wheels-dev/apt-wheels-dev and
-      # wheels-dev/yum-wheels-dev so their metadata-regen workflows pick up
+      # Fires repository_dispatch on wheels-dev/apt-wheels and
+      # wheels-dev/yum-wheels so their metadata-regen workflows pick up
       # the new .deb / .rpm asset and republish apt.wheels.dev /
       # yum.wheels.dev within minutes. See issue #2605.
       #
@@ -616,7 +633,7 @@ jobs:
           fi
 
           # Same channel derivation as the homebrew/scoop dispatch.
-          # apt-wheels-dev / yum-wheels-dev route on `channel` in the payload
+          # apt-wheels / yum-wheels route on `channel` in the payload
           # to slot the .deb/.rpm into the right pool (stable vs bleeding-edge).
           # RC releases aren't currently published to apt/yum, so we skip them.
           if echo "${WHEELS_RELEASE_VERSION}" | grep -qiE '\-snapshot[\.\+]'; then
@@ -632,7 +649,7 @@ jobs:
           # Static event type, fixed repo list — no untrusted input flows into
           # the curl arguments. WHEELS_RELEASE_VERSION is generated earlier in
           # the same workflow from wheels.json + run number.
-          for repo in apt-wheels-dev yum-wheels-dev; do
+          for repo in apt-wheels yum-wheels; do
             echo "Dispatching wheels-released to wheels-dev/${repo}..."
             http_status=$(curl -sS -o /tmp/linux-dispatch-resp.txt -w "%{http_code}" \
               -X POST \
 
@@ -215,7 +215,7 @@ jobs:
       FORGEBOX_PASS: ${{ secrets.FORGEBOX_PASS }}
       DOWNSTREAM_DISPATCH_TOKEN: ${{ secrets.DOWNSTREAM_DISPATCH_TOKEN }}
       # Optional: when present, the build job's "Dispatch Linux repo buckets"
-      # step fires repository_dispatch on apt-wheels-dev / yum-wheels-dev so
+      # step fires repository_dispatch on apt-wheels / yum-wheels so
       # the bleeding-edge channel of apt.wheels.dev / yum.wheels.dev tracks
       # every develop push. When absent, the step skips silently. See #2605.
       LINUX_REPO_DISPATCH_TOKEN: ${{ secrets.LINUX_REPO_DISPATCH_TOKEN }}