docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_*

[bpamiri]

Summary

PR #2759 (2026-05-18) renamed the snapshot Linux artifacts to use a wheels-be prefix so the package name itself differentiates the bleeding-edge channel from stable on apt / dnf. The install guides weren't updated alongside that rename, so every documented curl -fsSLO command for Linux bleeding-edge install resolves to a 404 against the actual published assets.

Verified against today's snapshot:

Guide says (broken):   .../wheels_4.0.2.snapshot.1923_amd64.deb        → HTTP 404
Actual published:      .../wheels-be_4.0.2.snapshot.1923_amd64.deb     → HTTP 302

Same problem on the rpm side:

Guide says (broken):   .../wheels-4.0.2.snapshot.1923.x86_64.rpm       → HTTP 404
Actual published:      .../wheels-be-4.0.2.snapshot.1923.x86_64.rpm    → HTTP 302

This PR corrects all six affected pages — three unique pages mirrored across the v4-0-0 (current published) and v4-0-1-snapshot (pre-release preview) doc versions:

Page	Snippets fixed
start-here/installing.mdx	"Want bleeding-edge?" aside with curl/apt/dnf commands
start-here/release-channels.mdx	Main BE install snippets + "Switching channels" snippets + tilde-mangling prose example
command-line-tools/installation.mdx	Bleeding-edge illustrative snippets

Substitutions are scoped to bleeding-edge contexts only (snippets using ${SNAP_FILENAME_VER} and prose wheels_4.0.0.snapshot.* filename examples). Stable-channel snippets are unchanged — they use ${WHEELS_VERSION} and fetch from wheels-dev/wheels (not wheels-snapshots), and correctly retain the bare wheels_ / wheels- prefixes because the stable Linux package is still named just wheels.

Related Issue

No issue tracking this specifically; surfaced while planning the 4.0.2 release readiness around #2773. Without this fix, users on Linux can't follow the documented bleeding-edge install flow to verify develop-only fixes — including the two other in-flight 4.0.2 PRs:

• #2776 — Linux .deb/.rpm framework nesting fix (the actual fix for First 15 Minutes tutorial fails. The key [WO] does not exist. #2773's [wheels.Injector] error)
• #2774 — defensive onError guard

Type of Change

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

Feature Completeness Checklist

• DCO sign-off — Signed-off-by: trailer present
• Tests — N/A (docs-only, no executable code paths touched)
• Framework Docs — this is the framework docs update
• AI Reference Docs — N/A (.ai/ doesn't reference these snapshot filenames)
• CLAUDE.md — N/A (CLAUDE.md doesn't reference these snapshot filenames)
• CHANGELOG.md — intentionally skipped. This is a pure docs fix for stale URLs; no framework behavior changes. Adding an [Unreleased] entry would also conflict with fix(ci): stop double-nesting framework inside Linux .deb/.rpm packages #2776's entry on the same anchor at merge time.
• Verification — grep sweep confirms: (a) no stale wheels_${SNAP_FILENAME_VER} or wheels-${SNAP_FILENAME_VER}.x86_64.rpm patterns remain anywhere under web/, (b) fixed wheels-be_ / wheels-be- forms present in all six pages, (c) stable-channel wheels_${WHEELS_VERSION} / wheels-${WHEELS_VERSION}.x86_64.rpm snippets untouched.

Test Plan

End-to-end validation (after merge, once next develop snapshot fires):

# On a fresh Ubuntu / Fedora VM, follow the corrected install snippet:
SNAP_TAG=$(curl -fsSL https://api.github.com/repos/wheels-dev/wheels-snapshots/releases \
  | sed -nE 's/.*"tag_name": *"v([^"]+)".*/\1/p' | head -1)
SNAP_FILENAME_VER="${SNAP_TAG//-/.}"
curl -fsSLO "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${SNAP_TAG}/wheels-be_${SNAP_FILENAME_VER}_amd64.deb"
sudo apt install "./wheels-be_${SNAP_FILENAME_VER}_amd64.deb"

# Expect: actual install, not 404
wheels --version    # should report 4.0.2-snapshot.N

Scope clarification — why I'm NOT also fixing

• Phase 2 apt.wheels.dev / yum.wheels.dev install instructions — those aren't live yet; current Phase 1 GitHub-Releases-direct-install is the only path
• Stable-channel snippets — they're correct as-is; the stable package on Linux is still named wheels, not wheels-stable or similar
• Brew / Scoop wheels-be docs — already correct; those formulas use independent install commands that don't reference snapshot artifact filenames

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: This PR fixes the right problem — the bleeding-edge Linux package was renamed wheels-be_* by #2759 and the guides weren't updated — but the fix is incomplete. Two bleeding-edge install snippets in both release-channels.mdx files (inside the Linux Tabs component) were missed and still resolve to 404. The PR's own verification sweep failed to catch them because they use a different bash variable name (WHEELS_FILENAME_VER) than the grep checked (SNAP_FILENAME_VER). Requesting changes to close those two remaining gaps before merge.

---

Correctness

Missed bleeding-edge snippets in release-channels.mdx — both doc versions

web/sites/guides/src/content/docs/v4-0-0/start-here/release-channels.mdx, lines 104–105 and 112:

# Line 104–105 (Debian / Ubuntu (bleeding-edge) tab)
curl -fsSLO "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels_${WHEELS_FILENAME_VER}_amd64.deb"
sudo apt install "./wheels_${WHEELS_FILENAME_VER}_amd64.deb"

# Line 112 (Fedora / RHEL (bleeding-edge) tab)
sudo dnf install "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels-${WHEELS_FILENAME_VER}.x86_64.rpm"

The same stale content appears at the identical line numbers in v4-0-1-snapshot/start-here/release-channels.mdx. These code blocks are titled "Debian / Ubuntu (bleeding-edge)" and "Fedora / RHEL (bleeding-edge)" — they fetch from wheels-dev/wheels-snapshots and need the wheels-be_ / wheels-be- prefix, yet the PR's diff leaves them untouched.

The root cause of the miss: the PR's verification sweep in the checklist checked for patterns containing ${SNAP_FILENAME_VER}, but these snippets bind the tag to WHEELS_FILENAME_VER (a different variable name). A user copying the code from the Linux tab would get a 404, defeating the fix's stated goal of letting users verify develop-only fixes on Linux.

Fix needed in both v4-0-0 and v4-0-1-snapshot:

# Debian / Ubuntu (bleeding-edge)
curl -fsSLO "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels-be_${WHEELS_FILENAME_VER}_amd64.deb"
sudo apt install "./wheels-be_${WHEELS_FILENAME_VER}_amd64.deb"

# Fedora / RHEL (bleeding-edge)
sudo dnf install "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm"

---

Docs

Stale prose on Linux channel naming — release-channels.mdx line 129 (both versions)

On **Linux**, only a single package name (`wheels`) is published per channel today; the channel distinction lives in the source repo

Since #2759 renamed the bleeding-edge artifact to wheels-be, this is no longer accurate — Linux now ships two differently-named packages, just like macOS/Windows. The macOS/Windows paragraph immediately above (line 127) already says "two differently-named packages (wheels vs wheels-be)". The Linux paragraph needs the same update. Suggested wording:

On Linux, two package names are published: wheels (stable, from wheels-dev/wheels) and wheels-be (bleeding-edge, from wheels-dev/wheels-snapshots). Because they are different package names, apt/dnf does not treat the install as an in-place upgrade — see the snippets below.

---

What looks good

The changes that are present are correct and symmetric across v4-0-0 and v4-0-1-snapshot:

• "Switching channels" snippets updated to wheels-be_ / wheels-be- in all four shells.
• "Want bleeding-edge?" Aside in installing.mdx updated consistently.
• Tilde-mangling Aside caution in release-channels.mdx updated.
• command-line-tools/installation.mdx illustrative snippets updated.
• Stable-channel snippets (wheels_${WHEELS_VERSION} from wheels-dev/wheels) correctly untouched.

---

Commits

Single commit docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_* — valid type, descriptive subject, within 100 chars, DCO sign-off present. No issues.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is solid. Both findings are verified against the actual files. The request-changes verdict is correct. There is one additional missed issue: A's suggested prose fix for line 129 directly contradicts an inline comment in the same Switching channels section that A did not flag, and that inconsistency needs to be resolved before address-review applies the consensus.

Sycophancy

None detected. A itemized concrete file locations and line numbers, provided suggested replacements, and correctly resisted approving a doc PR with live 404 snippets.

False positives

None detected.

• Lines 104-105 and 112 in both release-channels.mdx files: Verified in the actual post-merge files. Both v4-0-0 and v4-0-1-snapshot still contain wheels_${WHEELS_FILENAME_VER}_amd64.deb / wheels-${WHEELS_FILENAME_VER}.x86_64.rpm in the primary install Tabs. The diff does not touch those lines. A's claim is accurate.
• Line 129 stale prose: Verified present verbatim in both files. A's identification is correct.

Missed issues

One additional issue A did not flag:

• release-channels.mdx lines 142-143 (both versions) -- "upgrades in place" comment contradicts A's own proposed fix: The Linux stable-to-bleeding-edge code block contains the inline comment: # apt sees a newer version ... and upgrades in place -- no uninstall step needed. That claim was accurate when both channels used the package name wheels (same name = apt in-place upgrade). Now that bleeding-edge is wheels-be, a different package name, apt install ./wheels-be_*.deb installs a new package alongside wheels rather than upgrading it in place -- unless the .deb declares Conflicts: wheels and Replaces: wheels. Critically, A's own suggested prose for line 129 states "Because they are different package names, apt/dnf does not treat the install as an in-place upgrade" -- which directly contradicts the comment in the Switching channels snippet A already touched. Whichever version is accurate, the two statements cannot coexist. A should either (a) confirm the .deb declares Replaces:/Conflicts: and keep the comment, or (b) update both the inline comment at line 142 and the prose at line 129 to consistently say an explicit uninstall/reinstall is needed.

Verdict alignment

A's request-changes verdict is consistent with two live-404 snippets remaining in the primary install section -- correct call.

Convergence

Not aligned yet. A's findings are verified and the request-changes verdict is right, but the contradiction between A's proposed prose for line 129 and the inline comment at line 142 is a concrete inconsistency that address-review would need to resolve. A should clarify whether the stable-to-bleeding-edge switch is an in-place upgrade or a separate-package install, and make the suggestion consistent across both locations before we converge. Once A acknowledges and resolves that single point, B will be aligned on converged-changes.

[wheels-bot]

Wheels Bot — Reviewer A response (round 1)

B's critique is correct on the missed issue: my proposed prose fix for line 129 ("Because they are different package names, apt/dnf does not treat the install as an in-place upgrade") directly contradicts the inline comment at lines 142-143 of the Switching channels snippet ("apt sees a newer version... and upgrades in place — no uninstall step needed."), and I failed to flag that existing comment when reviewing. I concede that finding. My two original findings from the initial review stand — B independently verified both. Verdict remains request-changes, now covering three related items.

Conceded points

• Lines 142-143 (both release-channels.mdx versions) — stale "upgrades in place" comment inconsistent with A's line 129 prose suggestion: B is correct. The "upgrades in place" comment was accurate when both channels published a package named wheels — same name means apt automatically treats the new install as an upgrade. With the PR's rename to wheels-be, apt now sees a different package name and would install wheels-be as a separate, new package alongside wheels (with two competing /usr/bin/wheels binaries) unless the .deb declares Replaces: wheels and Conflicts: wheels in its metadata. I should have flagged lines 142-143 as a related site requiring resolution, and I should not have proposed prose for line 129 that presupposes the answer without checking the package metadata. B caught the gap.

Defended points

• Lines 104-105 and 112 (both doc versions) — primary install Tabs still use wheels_ prefix: Confirmed in the current files; the diff did not touch those lines. Still broken.
• Line 129 (both doc versions) — "only a single package name (wheels)" prose is stale: Confirmed in the current files — this line is unchanged and now factually wrong after the rename. Still needs updating.

Updated verdict

Still request-changes: the PR needs three items resolved. (1) Lines 104-105 and 112 in both doc versions — update to wheels-be_ / wheels-be- prefix. (2) Lines 142-143 and line 129 must be made consistent: the PR author should confirm whether the wheels-be .deb/.rpm declares Replaces: wheels and Conflicts: wheels in its package metadata — if yes, the "upgrades in place" comment at lines 142-143 is still accurate and line 129 should be updated to explain that apt/dnf handles the channel switch via package replacement metadata; if no, lines 142-143 need to drop the "no uninstall step needed" claim and the snippet needs an explicit apt remove wheels step before installing wheels-be. Either way, the two locations must agree.

[bpamiri]

@wheels-bot Reviewer A (initial) — review 4333456257
@wheels-bot Reviewer A response — review 4333483003
@wheels-bot Reviewer B (round 1) — comment 4504221724

All round-1 findings addressed in c36bef6b5 (plus merge of develop in c4287ab10 since #2774 and #2776 both landed while this PR was open).

Acknowledgments first: A and B are both right that my round-0 verification sweep was too narrow — I grep'd for ${SNAP_FILENAME_VER} and missed the same bug in snippets bound to ${WHEELS_FILENAME_VER}. That's exactly the kind of miss a wider regex (or a "no wheels[_-][^b] after a wheels-snapshots URL" check) would have caught. I've added that wider sweep to my pre-commit verification on this push.

Changes pushed

Finding	Action
A Nit 1 — lines 104-105 + 112 in both release-channels.mdx (primary BE install Tabs)	Updated to wheels-be_${WHEELS_FILENAME_VER}_amd64.deb and wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm
A Nit 2 — line 129 stale "only a single package name" prose	Rewritten to describe the new two-package reality, with up-front mention of the asymmetric Replaces: / Conflicts: / Obsoletes: metadata
B's catch — lines 142-143 "upgrades in place" comment contradicting A's proposed prose	Verified against the actual nfpm yamls. The wheels-be .deb declares both Replaces: wheels + Conflicts: wheels, so apt does handle the swap automatically (no separate apt remove needed). The wheels-be .rpm only declares Conflicts: with no Obsoletes:, so dnf users need an explicit dnf remove wheels first. Updated the Debian comment to name the metadata that drives the behavior; added sudo dnf remove wheels to the Fedora snippet with a comment explaining why.

Beyond the explicit findings (scope addition flagged here, not a surprise)

Lines 158-172 (Linux bleeding-edge → stable for both Debian and Fedora) had the same conceptual bug as 142-143 and were inconsistent with whatever resolution we chose there:

• The old Debian snippet used apt install --allow-downgrades — which assumes same package name. With different names, apt would fail with a /usr/bin/wheels file conflict because the stable wheels .deb doesn't declare Replaces: wheels-be. Fixed by adding sudo apt remove wheels-be first and dropping the --allow-downgrades flag.
• The old Fedora snippet used sudo dnf downgrade — same issue. Fixed by adding sudo dnf remove wheels-be first and switching to sudo dnf install.

I made these changes even though the reviewers didn't explicitly flag them, on the principle B used for line 142-143: "the two locations must agree." Listing one direction with Replaces: semantics and the other with stale --allow-downgrades semantics would have left readers with the same kind of cross-snippet contradiction. If the reviewers want this trimmed back to only the two flagged locations, happy to revert, but they have the same root cause and would have been a guaranteed round-2 finding otherwise.

Verification on this push

[1] Any wheels-snapshots URL with non-be filename:        ✓ none
[2] Any bare wheels_4.0.0.snapshot.* prose example:       ✓ none
[3] Any "upgrades in place" / "no uninstall step" /
    "--allow-downgrades" / "dnf downgrade" claims:        ✓ none
[4] Any stale "only a single package name" prose:         ✓ none
[5] Stable wheels_${WHEELS_VERSION} snippets:             ✓ unchanged
[6] New "Replaces: wheels" prose present:                 ✓ both versions

Skipped

Nothing — every flagged item addressed. Convergence-on-approve from reviewers welcome whenever they've re-read the diff.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: This follow-up commit fully resolves all three items from the previous request-changes round — the two missed bleeding-edge install snippets in both release-channels.mdx versions (the WHEELS_FILENAME_VER tabs that were not caught by the initial grep), the stale line-129 prose, and the contradictory line-142/143 comment. The package-metadata-driven rewrite of the Switching channels section is accurate and internally consistent. One minor doc nit on comment accuracy, but nothing that should block merge.

---

Correctness

All three prior findings addressed:

1. Lines 104–105 and 112 (both doc versions) — primary install Tabs with WHEELS_FILENAME_VER: Fixed. Both versions now read wheels-be_${WHEELS_FILENAME_VER}_amd64.deb / wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm.

2. Line 129 prose (both doc versions): Fixed. The old "only a single package name (wheels) is published per channel today" claim is replaced with an accurate description of the asymmetric Replaces: / Conflicts: / Obsoletes: metadata, explaining up front why the stable→BE swap on Debian is automatic while the Fedora direction and both reverse directions need explicit removes.

3. Lines 142–143 "upgrades in place" comment (both doc versions): Fixed. The comment now accurately cites Replaces: wheels + Conflicts: wheels as the mechanism.

The four Linux switching snippets are now consistent with the line-129 prose and with each other.

Minor nit — line 164–165 (both doc versions), "bleeding-edge → stable (Debian / Ubuntu)" comment:

# The stable wheels .deb does not declare Replaces: wheels-be, so apt
# would fail with a /usr/bin/wheels file conflict. Remove wheels-be
# first.

The real failure mode is the package-level Conflicts: wheels already declared by wheels-be — apt would refuse to install wheels while wheels-be is present with a package conflict error, not a dpkg-level file-ownership conflict. The prescription (apt remove wheels-be first) is correct regardless, and an advanced user debugging the error message might be confused by the "file conflict" framing. Suggested wording:

# wheels-be declares Conflicts: wheels, so apt refuses to install wheels
# while wheels-be is present. Remove wheels-be first.

This is a nit — does not block merge.

---

What looks good

• Symmetric across v4-0-0 and v4-0-1-snapshot: all six files updated identically.
• Stable-channel snippets (${WHEELS_VERSION} from wheels-dev/wheels) correctly untouched in both doc versions.
• Removed --allow-downgrades and dnf downgrade from the reverse-direction snippets; replacing them with explicit remove-then-install is the correct approach when two differently-named packages share a binary path.
• No other doc versions (v2-5-0, v3-0-0) contain Linux snapshot install snippets — confirmed from directory listing.

---

Commits

• 78f2910ea docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_* — valid type, subject within 100 chars, DCO sign-off present.
• c4287ab10 Merge remote-tracking branch ... — merge commit, no commitlint requirement.
• c36bef6b5 docs(web/guides): fix release-channels.mdx — missed BE Tab URLs + Linux switching semantics — valid type, subject within 100 chars, DCO sign-off present. Commit body explains the why (missed WHEELS_FILENAME_VER variable, nfpm metadata verification before rewriting switching prose).

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review of the follow-up commit is accurate and well-grounded. All three prior request-changes items are verifiably fixed in the diff. There is one concrete actionable nit — A identified it correctly but called it non-blocking. B concurs on the diagnosis but recommends applying it before merge, since the comment misleads users about the actual apt failure mechanism. Converging on changes for that one-line fix in two files.

Sycophancy

None detected. A used COMMENTED state (not approve) and called out a concrete inaccuracy in the inline comment at lines 164–165, rather than glossing over it.

False positives

None detected.

• Prior findings (lines 104–105 / 112 in both release-channels.mdx versions): Verified in the diff — both v4-0-0 and v4-0-1-snapshot now read wheels-be_${WHEELS_FILENAME_VER}_amd64.deb and wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm. A's claim is accurate.
• Line 129 prose (both versions): Verified in the diff — the old "only a single package name" text is replaced with an accurate description of the asymmetric Replaces: / Conflicts: / Obsoletes: metadata. A's claim is accurate.
• Lines 142–143 comment (both versions): Verified — the "upgrades in place" comment is replaced with the mechanism-citing replacement. A's claim is accurate.
• A's nit at lines 164–165 (both versions): Verified. The current comment reads: "The stable wheels .deb does not declare Replaces: wheels-be, so apt would fail with a /usr/bin/wheels file conflict." A is correct that the actual failure mode is the Conflicts: wheels declaration on wheels-be, which causes apt to refuse at the dependency-resolution stage — before dpkg file ownership is even checked. The comment attributes the refusal to the wrong mechanism. A's suggested replacement is accurate.

Missed issues

None detected. The PR author's proactive fix to the bleeding-edge → stable snippets (lines 158–172, dropping --allow-downgrades / dnf downgrade in favour of explicit remove-then-install) is correct and A acknowledged it under "What looks good." The apt upgrade wheels forward-looking mention in the "repos coming" line is about the future stable apt repo and is correctly left unchanged.

Verdict alignment

A's COMMENTED state is consistent with finding only a non-blocking nit after all substantive issues were resolved — correct call.

Convergence

Aligned. A identified the lines-164–165 comment inaccuracy with a concrete suggested replacement; B agrees it is real and actionable (a two-line change in two mirrored files). The fix is clear: replace the "file conflict" framing with A's suggested wording that names the Conflicts: wheels declaration as the mechanism. Address-review can apply this directly from A's suggestion. Converging on changes.

[bpamiri]

@wheels-bot Reviewer A (round 2) — review 4333693872

Addressed in c73fe8181. You're right — the actual blocker is wheels-be's Conflicts: wheels declaration (apt refuses with a package-conflict error before dpkg ever attempts to unpack files), not a dpkg file-ownership conflict.

• Debian BE → stable comment — rewritten using your suggested framing, naming the Conflicts: wheels declaration as the mechanism. Kept a parenthetical noting the missing Replaces: wheels-be in stable too, since that explains why apt also wouldn't auto-remove (relevant if a reader wonders whether a single command could swap them).
• Fedora BE → stable comment — updated for parallel framing. You only flagged the Debian one, but wheels-be rpm declares Conflicts: wheels the same way (verified in nfpm-wheels-be.yaml), so the same accurate framing applies. Leaving the two snippets with mismatched failure-mode framing would have invited a "two sites must agree" round-3 nit under the same logic that caught round 1's line-142 / line-129 contradiction.

No other staleness from this comment-accuracy class — verified via grep -rn "file conflict\|file-ownership conflict" (returns nothing). Stable-channel snippets and BE-channel install Tabs are unchanged.

[bpamiri]

@wheels-bot Reviewer B (round 1) — comment 4504471195

Already addressed in c73fe8181, pushed before your review landed (your converged-changes marker references c36bef6b5, which is one commit behind HEAD). The fix matches A's suggested wording — Debian comment now reads:

# wheels-be declares Conflicts: wheels, so apt refuses to install wheels
# while wheels-be is present. (Stable wheels .deb also doesn't declare
# Replaces: wheels-be, so apt wouldn't auto-remove either way.) Remove
# wheels-be first.

The Fedora comment got the same parallel framing — your "two sites must agree" principle applies here exactly as it did to round 1's line-142 / line-129 split, so I extended A's Debian-only suggestion to the rpm site as well. Verified via grep -rn "file conflict\|file-ownership conflict" — returns nothing.

PR should be at converged-approve on c73fe8181 once both reviewers re-run against the current HEAD. No further code action expected from me; happy to close the loop here if you agree.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: The final commit (c73fe81) directly and correctly resolves the round-2 nit — the BE→stable (Debian/Ubuntu) comment now names wheels-be declares Conflicts: wheels as the actual blocking mechanism rather than a dpkg file-ownership conflict, and the Fedora comment is updated in parallel for consistency. All three round-1 findings and the round-2 nit are now addressed. The PR is ready to merge.

---

Correctness

All outstanding items from prior rounds are closed:

1. Lines 104–105 and 112 (both doc versions) — WHEELS_FILENAME_VER snippets: Fixed in c36bef6. Both doc versions now emit wheels-be_${WHEELS_FILENAME_VER}_amd64.deb / wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm correctly.

2. Line-129 Linux channel-naming prose (both doc versions): Fixed in c36bef6. The stale "only a single package name" claim is replaced with an accurate description of the package metadata asymmetry (Replaces: + Conflicts: on Debian, Conflicts: only on Fedora).

3. Lines 142–143 "upgrades in place" comment (both doc versions): Fixed in c36bef6. The comment now cites the actual Replaces: wheels + Conflicts: wheels metadata as the mechanism.

4. Round-2 nit — BE→stable (Debian) comment framing (both doc versions): Fixed in c73fe81. The comment now reads:

   # wheels-be declares Conflicts: wheels, so apt refuses to install wheels
   # while wheels-be is present. (Stable wheels .deb also doesn't declare
   # Replaces: wheels-be, so apt wouldn't auto-remove either way.) Remove
   # wheels-be first.

   This correctly names the package-level Conflicts: declaration as the blocker (apt refuses before dpkg attempts file unpacking), rather than the previously misleading "file conflict" framing. The secondary note about missing Replaces: wheels-be in stable is accurate and useful — it answers the natural follow-up question of why a single command cannot swap them automatically.

   The Fedora BE→stable comment was updated with parallel framing as a proactive consistency fix, which is the right call given that the prior round-1 review caught the line-129 / line-142 consistency gap.

The four Linux switching snippets, the line-129 prose, the tilde-mangling Aside, and the comment text are now internally consistent in both doc versions.

---

Commits

All four PR commits conform to commitlint:

• 78f2910ea docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_* — valid type, DCO present.
• c4287ab10 Merge remote-tracking branch ... — merge commit, no commitlint requirement.
• c36bef6b5 docs(web/guides): fix release-channels.mdx — missed BE Tab URLs + Linux switching semantics — valid type, subject within 100 chars, DCO present.
• c73fe8181 docs(web/guides): name the actual Conflicts declaration in BE→stable comments — valid type, subject within 100 chars, DCO present. Commit body explains why the file-conflict framing was wrong and why the Fedora comment was updated proactively.

---

What looks good (overall)

• Symmetric across v4-0-0 and v4-0-1-snapshot throughout.
• Stable-channel snippets (wheels_${WHEELS_VERSION}) correctly untouched.
• Removed --allow-downgrades and dnf downgrade in favor of explicit remove-then-install, which is the correct approach when two differently-named packages compete for /usr/bin/wheels.
• The PR description's scope clarification (Phase 2 apt/yum repos, stable snippets, Brew/Scoop) correctly bounds what is and is not changed.

[wheels-bot]

Wheels Bot — Address Review (round 1)

Consensus findings from Reviewer A and Reviewer B's convergence at c36bef6b5 were already applied by the author in c73fe8181 before this address-review run began. No commit produced — nothing left to change.

Consensus finding (from B's converged-changes marker on c36bef6b5):

• release-channels.mdx lines 164–165, both v4-0-0 and v4-0-1-snapshot — replace the "would fail with a /usr/bin/wheels file conflict" framing (which attributes the apt refusal to a dpkg-level file-ownership conflict) with framing that names the package-level Conflicts: wheels declaration on wheels-be as the actual mechanism.

Verification on current head c73fe8181:

• web/sites/guides/src/content/docs/v4-0-0/start-here/release-channels.mdx:164 now reads # wheels-be declares Conflicts: wheels, so apt refuses to install wheels — matches A's suggested replacement.
• web/sites/guides/src/content/docs/v4-0-1-snapshot/start-here/release-channels.mdx:164 — same fix applied (parallel mirror).
• Both files' Fedora BE → stable comments (line 176) updated for parallel framing — the author noted this proactively, citing the same "two sites must agree" logic that produced the round-1 contradiction.
• grep -rn "file conflict\|file-ownership conflict" web/ returns nothing.

Reviewer A has already submitted an APPROVED review on c73fe8181 (2026-05-21T03:20:57Z), so the convergence loop has effectively already progressed past this stage. Posting this marker for idempotency and to close out address-review at this SHA.

Skipped:

• No consensus findings were skipped — the single converged-changes item is verified applied.
• No fix/bot-* test re-run cited — this is a docs(web/guides) PR; consensus touched only .mdx content under web/sites/guides/.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review of the final commit is clean and well-grounded. All four prior findings are verifiably addressed in the diff. No sycophancy, no false positives, no missed issues. A's APPROVED verdict is correct. Converging on approve.

Sycophancy

None detected. A itemized each round-1 and round-2 item with specific commit hashes, quoted fix text, and line-level citations rather than an unsupported LGTM. The PR touches no security, migration, deploy, or DI subsystems — docs-only approval requires no human gate.

False positives

None detected. Verified each of A's four claims against the actual diff:

• Lines 104–105 and 112 in both release-channels.mdx — confirmed wheels-be_${WHEELS_FILENAME_VER}_amd64.deb and wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm are present in both doc versions.
• Line-129 "only a single package name" prose — confirmed replaced with accurate Replaces: / Conflicts: / Obsoletes: description in both doc versions.
• Lines 142–143 stable → bleeding-edge (Debian) comment — confirmed "upgrades in place" replaced with mechanism-citing text.
• Round-2 nit — BE→stable (Debian) comment — confirmed both doc versions now read wheels-be declares Conflicts: wheels, so apt refuses to install wheels while wheels-be is present... matching A's quoted text exactly.
• Fedora BE→stable parallel update — confirmed; both doc versions carry the parallel framing (Same as Debian above — wheels-be declares Conflicts: wheels...).

Missed issues

None detected. Verified independently:

• All six pages are changed (v4-0-0 and v4-0-1-snapshot for each of the three files). The v4-0-1-snapshot diff is a mirror of v4-0-0.
• Stable-channel package name references (wheels_${WHEELS_VERSION}, wheels-${WHEELS_VERSION}.x86_64.rpm) are untouched throughout.
• The forward-looking apt upgrade wheels line (future apt.wheels.dev repo) is correctly left unchanged.
• The tilde-mangling <Aside> is updated in both doc versions.
• All four commits conform to commitlint (docs type, subjects within 100 chars, DCO trailers present per prior-round verification). Merge commit is exempt.

Verdict alignment

A's APPROVED state is consistent with all prior request-changes items being closed and no new issues found in the final commit — correct call.

Convergence

Aligned on approve. Every finding across all three rounds has been addressed, the diff is internally consistent across both doc versions, and the final commit correctly names the Conflicts: declaration as the apt/dnf refusal mechanism. No further changes needed.