docs: add the WSL2 guide on the docs site

[pmoutsias-amd]

Summary

• Adds an Install page, ROCm CLI on WSL2, to the docs site. It single-sources the published sections of docs/wsl.md (prerequisites, ROCDXG install, diagnosing a WSL host, and what rocm examine reports) through anchored includes. The maintainer sections (runtime env design, install UX recommendations, test plans) stay unpublished.
• Copyedits the published sections of docs/wsl.md for the style guide.
• Replaces the hard-coded ROCDXG version and SHA-256 in the by-hand install steps with ROCDXG_VERSION and ROCDXG_SHA256 placeholders, so they can't go stale.
• Marks the four rocm examine items that appear only in --json output: the supported-floor check, WSL major version, Windows host driver version, and HSA_ENABLE_DXG_DETECTION.
• Links the page from the installation page and adds it to _toc.yml.in.
• Moves the rocm diagnose --distro detail out of Prerequisites into a new "Diagnose a distro from Windows" subsection. It defines the host-side form, the WSL catalog, and the four limits of the host-side probe (including that rocminfo is found only on the default PATH), and adds a troubleshooting step for "could not inspect".
• States that fix-wsl-5 also abstains on non-Ubuntu distros and fix-wsl-6 also abstains on WSL 1.
• Adds a "Next steps" section to the install-page wrapper that links to Getting started.
• Rewrites the legacy ROCm / 7.13 paragraph in "Install ROCDXG In WSL". The sentence that TheRock 7.13 and newer should not require HSA_ENABLE_DXG_DETECTION is kept, and setting it on a newer release is described as harmless. The "still useful for compatibility checks" clause is dropped.

Split out of #616 so that PR stays a copyedit.

Test plan

• sphinx-build -W --keep-going -b html in docs/rocm-docs passes. It passed on an earlier head, but it has not been rerun since the --distro subsection and Next steps edits. Confirm with the CI docs job.
• Claims checked against driver_install.rs, fix.rs, diagnose.rs, and examine.rs, and against a live rocm examine and rocm examine --json run on a WSL2 host.
• By-hand install commands (curl, sha256sum -c, apt install) have not been run end to end; the filename and URL match what rocm install driver builds.
• The claim that wsl.exe --exec runs a non-login shell is supported by the source (examine.rs) but was not tested empirically.
• No successful rocm diagnose --distro run has been observed.
• The claim that --distro skips fix-18 and fix-19 is derived from examine.rs and was not observed in a run.
• SME to confirm that TheRock 7.13 and newer should not require HSA_ENABLE_DXG_DETECTION, and whether --distro should collect the fix-18 and fix-19 data.
• Engineering review of the technical claims.

[rominf]

🔴 Automated review · pr-review-watcher · 38aca71

This automation never files a GitHub approval, so no approving review will
appear here whatever the outcome — the merge decision stays with a human
reviewer.

First automated round on this pull request: every finding below is new.

Review — needs work

Full review of the whole change.
No ticket named. The description says the change is split out of #616 and describes it as publishing the WSL2 guide on the docs site plus copyedits to docs/wsl.md.

Blocking

• New cross-links in docs/wsl.md fail the required Markdown links resolve (lychee) check, and are dead anchors on GitHub — docs/wsl.md:52, :161, :201, :224, :272
  CI fails on this head with 5 errors, all "Cannot find fragment": rocm-docs/commands.md#examine (×2), rocm-docs/commands.md#diagnose-and-fix (×2) and rocm-docs/install/installation.md#windows-x86_64-powershell. The same check passes on base c1c2aeb3. Two workers ran lychee --config lychee.toml docs/wsl.md README.md (v0.24.2) and reproduced it locally.
  The cause is that those headings exist only in README.md. commands.md and installation.md are MyST stubs that {include} them. lychee.toml excludes docs/rocm-docs/ only as a link source, so links pointing into it are still fragment-checked. docs/wsl.md is a GitHub-read doc that README links to, so a reader there lands on raw {include} blocks.
  Lychee is the side that governs. It is the repo's link gate for files outside docs/rocm-docs/, and on the site -W already passes.
  Confidence 100 · mechanical · Fix: keep these references as plain text (or as README links) in docs/wsl.md, and add the site links only in the wrapper. The wrapper already does this for the installation-guide sentence. Alternatively add a narrowly scoped lychee remap. Do not point the links at ../README.md#… without checking :relative-docs: on the site, because README is not a site page.
• The description and commit 8a20779 claim the page says which rocm examine fields are JSON-only, but it does not — docs/wsl.md:272-273
  The description bullet is "Says which rocm examine fields appear only in --json output", and the commit message says "say which rocm examine fields appear only in the JSON output". The text added is only "The text report shows a subset; the rest appear in rocm examine --json."
  By ExamineSummary::render_text (crates/rocm-core/src/host_gpu.rs:1745), four of the listed items are JSON-only: WSL major version, whether the release clears the floor, Windows host driver version, and HSA_ENABLE_DXG_DETECTION.
  This repo builds the squash body from the commit messages, so the overclaim would land in history.
  Confidence 85 · mechanical · Fix: either finish the work by marking those four items in the list, or narrow both the description and the commit message.

Non-blocking

• The "three limits" of --distro miss a fourth: rocminfo is looked up on the non-login PATH — docs/wsl.md:242-258
WSL_REMOTE_PROBE uses command -v rocminfo (crates/rocm-core/src/examine.rs:814) under wsl.exe --exec /bin/sh -c. The default WSL PATH has no /opt/rocm/bin and no TheRock venv. When rocminfo is not found, rocm_sees_gpu is None, and the fix-wsl-6 "plumbing complete but no GPU enumerated" branch cannot fire (crates/rocm-core/src/diagnose.rs:2362-2377).
  So --distro can miss a host-driver fault that an in-distro run reports. The "Fixed ROCm locations" bullet also implies that every ROCm lookup uses the conventional roots, which is not true for rocminfo.
  Confidence 70 · logic · Fix: add the rocminfo/PATH limit, and drop "three".
• "Two entries outside this list also apply" understates what runs on WSL and contradicts the page itself — docs/wsl.md:184-187
CHECKERS also tags fix-1, fix-2, fix-6, fix-8 and fix-16 as "wsl" (crates/rocm-core/src/diagnose.rs:2468-2484). Two paragraphs later the same page names fix-6-path as the one entry the CLI carries out on WSL.
  The code governs. The sentence predates this PR, but the PR rewrote it.
  Confidence 85 · mechanical · Fix: say that the shared environment-driven checks also run on WSL, then name fix-18 and fix-19 as the two non-environment ones.
• README and the CLI's own --distro note now list fewer skipped checks than docs/wsl.md does — README.md:283-288, apps/rocm/src/main.rs:2899-2905
docs/wsl.md now says fix-18-comgr-conflict and fix-19-shm-too-small do not run under --distro. The code agrees: the comgr and shm fields stay at their defaults in a remote examination (diagnose.rs:1733-1739, :1947-1955). README and the printed "Note: … Checks that read the environment … did not run" still list only the environment checks.
  AGENTS.md §5 says to grep each surface a claim repeats on and check it against the code. The gap in those two surfaces existed before this PR, but this PR exposes it.
  Confidence 85 · mechanical · Fix: bring the README bullet and the printed note in line, or record this as a follow-up.
• "Legacy ROCm release (7.2.4 and earlier)" has no source, and leaves 7.2.5–7.12 undefined — docs/wsl.md:124-131
HSA_ENABLE_DXG_DETECTION appears in the repo only in docs/wsl.md and crates/rocm-core/src/examine.rs:34, where it is described as "Legacy ROCm releases". The only 7.2.4 anywhere in the repo is the amdgpu-install repo pin (apps/rocm/src/driver_install.rs:815), which is unrelated.
  The PR also drops the old "setting it is still useful" advice. A reader on 7.5–7.12 now has no guidance.
  The test plan asks an SME to confirm only the 7.13 boundary, not 7.2.4.
  Confidence 70 · logic · Fix: cite where 7.2.4 comes from, or go back to "legacy releases" and keep the "harmless to set" line.
• "The same trust anchor that rocm install driver uses" no longer holds for the manual steps — docs/wsl.md:82-86
  The CLI checks against a digest pinned and reviewed in this repo (ROCDXG_PINNED_DIGESTS, apps/rocm/src/driver_install.rs:528-556). The manual steps now take a digest read from the release page at install time. That catches a corrupted transfer but not a replaced asset.
  The old text was accurate because it carried the pinned 1.2.2 digest. History: that digest was added deliberately in #224 (8788394).
  Confidence 70 · logic · Fix: keep 1.2.2 and its pinned digest as the worked example (pointing at ROCDXG_PINNED_DIGESTS for other versions), or reword the "same trust anchor" claim.
• AI co-author trailers in commit messages that will form the squash body — commits 8a20779, 8b24971, 43bff27, e2c3b29, 598a15f, 43f44fd, b65cd5b, 2986b01
  These carry Co-Authored-By: Claude <noreply@anthropic.com> (e2c3b29 says "Claude Code"). AGENTS.md §11 says "avoid AI-generated boilerplate footers".
  Confidence 85 · mechanical · Fix: drop the trailers when squashing.

Decisions for the author

• One sentence hand-copied into the wrapper, with include boundaries anchored on prose strings — tradeoff
  This retargets one link on the site at the cost of two copies that must change together. The HTML comment documents the coupling. The alternative is restructuring docs/wsl.md so the link-bearing sentence is not needed in the included range. Fixing the first blocking finding with the same pattern would add more copies, which may tip this the other way.
• Placeholders instead of a concrete version and digest in "Doing it by hand" — tradeoff
  Placeholders cannot go stale. A concrete pinned value gives readers a reviewed anchor they can copy (see the trust-anchor finding above). Confirm the choice was deliberate.

Positive signals

• The ci.yml docs: path filter and its comment were extended for the new {include} target, which is the precedent #473 set. Every {include} target under docs/rocm-docs/ is now covered.
• The HTML comment in docs/rocm-docs/install/wsl.md names exactly which strings are anchors and that the maintainer sections are deliberately left out. Every anchor resolves uniquely at this head.

Deployment notes

None

What this covered

Every file in the change was read completely, plus the --distro, examine, diagnose and ROCDXG-install code paths the docs describe (crates/rocm-core/src/{examine,diagnose,fix,host_gpu}.rs, apps/rocm/src/{main,driver_install}.rs), lychee.toml, docs/rocm-docs/conf.py, AGENTS.md, and the PR description. Range c1c2aeb3…38aca714.

Did not run:

• No Sphinx build locally (sphinx-build/myst_parser are not installed). CI's Sphinx docs build (-W) passed on this head and was relied on for whether site links and :relative-docs: resolve.
• No cargo builds or tests, since the change is docs-only.
• The diff adds or changes no tests, and no behaviour changed, so no scenario was needed.

Other notes:

• Fan-out was three independent workers: diagnose claims, examine/install/site claims, and the source-reading passes (instructions, history, prior PRs, comments). The Step 7 design questions were reasoned in the driving context, not by independent workers.
• The failing E2E tests (Strix Halo, Ubuntu) (release) is not attributable to this change. It is a 404 fetching a lemonade-sdk/llama.cpp release asset, and the diff touches no code.
• Not reconciled against any PR discussion.

[rominf]

🔴 Automated review · pr-review-watcher · f763c0e

This automation never files a GitHub approval, so no approving review will
appear here whatever the outcome — the merge decision stays with a human
reviewer.

Second automated round (the first was filed against 38aca71). Every finding below is new this round.

The previous round's two blocking objections were not re-found by this round's blind review. Both are settled and no longer stand. Each was then put to the reviewer as a standing objection; that check is anchored evidence, not a finding. The driver also checked each against the code at f763c0e:

• Lychee fragment failures from the docs/wsl.md cross-links: resolved. 6649870 dropped those links. No rocm-docs/ link remains in docs/wsl.md, and Markdown links resolve (lychee) is green on this head.
• The claim that the page says which rocm examine fields are JSON-only: resolved. docs/wsl.md now marks the four items (--json only), so 8a20779's commit message is true of the squashed result.

This change request replaces the earlier one as this account's complete position. Only the two findings under Blocking below gate the merge.

Review — needs work

Full review of the whole change.
No ticket named. The description says this was split out of #616 so that PR stays a copyedit. It describes the new site page, the copyedits, the --distro subsection, the ROCDXG placeholders and the HSA_ENABLE_DXG_DETECTION rewrite.

Blocking

• (new) The new "shared checks" paragraph misdescribes fix-16 and fix-18 — docs/wsl.md:188-191
  The paragraph says "The shared checks that read the environment or the ROCm install also run on WSL, such as … fix-16-vllm-oom". It then calls fix-18 and fix-19 "not environment checks".

  • The code is the side that governs here, and it contradicts both claims.
  • fix-16 reads neither the environment nor the install. Its checker is fn check_16_vllm_oom(_e: &Examination, symptom: &str), and its doc comment says it is "Keyword-only … e is therefore unused" (crates/rocm-core/src/diagnose.rs:1659).
  • fix-18 does read the environment and the install. Its probe works from LD_LIBRARY_PATH and the resolved ROCm install (crates/rocm-core/src/examine.rs:487-500). This PR's own text at docs/wsl.md:204 names that same "LD_LIBRARY_PATH/loader-cache search".
  • "such as" suggests a longer list than exists. The CHECKERS table tags only 1, 2, 6, 8, 16, 18 and 19 as shared non-WSL entries for the wsl family (diagnose.rs:2467-2506).
  • The paragraph is also published on the site page.

  Confidence 85 · logic · Fix: list the shared entries exactly, without "such as". Describe fix-16 as symptom-driven, and drop the "not environment checks" framing for fix-18.

• (new) :relative-docs: rocm-docs/ has no effect, and a commit message says it does — docs/rocm-docs/install/wsl.md:30, :38, :53, :61; commit 71b7923

  • Why it does nothing: MyST rewrites a link only when destination.startswith(relative_include[0]) (myst_parser/mdit_to_docutils/sphinx_.py, _handle_relative_docs). I checked that source. No link in any included range of docs/wsl.md starts with rocm-docs/. The only relative file link, ../README.md#windows-x86_64-powershell at docs/wsl.md:231, sits in the gap that the site page hand-copies, so it is never included.
  • Why it misleads: no other include in the site uses this option. Commit 71b7923's message says "The includes use :relative-docs: so the links resolve as site pages". Commit 6649870 then dropped those links, which left the option inert.
  • This repo builds the squash commit body from the commit messages, so the squash commit would carry that false claim.

  Confidence 85 · mechanical · Fix: remove the option from all four includes, and reword the 71b7923 message, or keep it out of the squash body.

Non-blocking

• (new) The published manual-install steps no longer give the reader a digest to use — docs/wsl.md:84-94

  • Before: the steps carried the 1.2.2 digest added in #224.
  • Now: they say "For a version listed in ROCDXG_PINNED_DIGESTS, use the pinned digest" and point to it only by the bare path apps/rocm/src/driver_install.rs. A reader of the docs site, on a host "where the CLI is not installed yet", gets no link to that file.
  • The citation rule: AGENTS.md §5 lists only README.md, CONTRIBUTING.md and docs/rocm-docs/ as exceptions to linking repo files. docs/wsl.md is now {include}d into the site in the same way, so a relative link would break sphinx -W.

  Confidence 70 · mechanical · Fix: link the digest list with an absolute GitHub URL. Optionally add docs/wsl.md (and docs/vllm.md) to the §5 exception list.

• (new) The CLI's own --distro note was not updated to match — apps/rocm/src/main.rs:2914-2915

  • The PR now says in README.md:287-290 and docs/wsl.md:265-267 that --distro also skips fix-18 and fix-19.
  • The note printed after every --distro run still lists only "Checks that read the environment (HSA_OVERRIDE_GFX_VERSION, PATH, the framework/ROCm pairing)". AGENTS.md §5 asks for the same claim to be synced across docs and printed output.
  • The code supports the docs: fix-18 and fix-19 return zero on None data. The printed note is therefore the stale side.

  The note was already incomplete before this PR, but the PR makes the gap visible. Confidence 70 · logic · Fix: extend the note, in this PR or a named follow-up.

• (new) Eight commits carry AI co-author trailers — 8a20779, 8b24971, 43bff27, e2c3b29, 598a15f, 43f44fd, b65cd5b, 2986b01
  Co-Authored-By: Claude <noreply@anthropic.com> (and one Claude Code) will be carried into the squash commit. AGENTS.md §11 says "avoid AI-generated boilerplate footers". Confidence 70 · mechanical · Fix: drop the trailers when rewording the commits or the squash body.

• (new) The description does not mention all of the changed files

  • It omits the ci.yml docs path-filter addition, the index.rst card entry, and both README edits (the platform-table link move and the fix-18/fix-19 --distro bullet).
  • The commit messages do cover these, and they become the squash body, so nothing is hidden from the merged record. Only the description, which reviewers read first, is short.

  Confidence 70 · mechanical · Fix: add one line per item to the Summary.

Decisions for the author

• One sentence is hand-copied instead of single-sourced — tradeoff
  • For: copying the "To inspect a distro…" lead-in into the site page lets its installation-guide link resolve on the site.
  • Against: it creates a copy that can drift. Edits in the middle of the sentence will not fail the build; only edits to its first or last line will. The page's comment acknowledges this. Confirm the tradeoff is deliberate.
• Only the site page warns that docs/wsl.md headings are include anchors — non-blocking-improvement
  • The warning that its headings and two prose lines are include anchors lives only in docs/rocm-docs/install/wsl.md.
  • Renaming an anchor fails the build loudly. A new ## section added inside an included range, though, would be published under the wrong site heading with no error.
  • A short HTML comment in docs/wsl.md, like README's platform-support-table markers, would warn editors at the source.

Positive signals

• Every {include} start/end anchor resolves to its first occurrence exactly where intended. The near-duplicate line "To check a distro from Windows without…" correctly does not match the end anchor.
• The PR adds docs/wsl.md to the CI docs: path filter, so an edit to the source alone cannot skip the -W site build.
• The four --json-only rocm examine items are exactly right against the text renderer. The new text says has_amd_gpu/gpus are always false/empty on WSL, which matches examine.rs.

Deployment notes

None

What this covered

• What was read: all 7 changed files in full (fe47c48…f763c0e6, first-parent range prw-base...HEAD). I checked the CLI claims against crates/rocm-core/src/{diagnose,examine,fix,host_gpu}.rs, apps/rocm/src/{main,driver_install}.rs and docs/testing.md. I compared the site wiring with the MyST include and relative-docs source and with sibling include pages.
• Passes: three independent workers ran — CLI claims against code, site wiring and links, and instructions/history/comments.
• CI: all checks on f763c0e are green, including the Sphinx -W build and the lychee link check. An offline lychee run with fragment checking was clean apart from one known include-expansion false positive.

Did not run:

• Rust builds and tests: none were run, because disk on the review host is low. The Rust review was static only, and the PR changes no Rust.
• Sphinx: the site was not built locally; I relied on the green CI job.
• Prior-changes pass: not run. Review comments on earlier PRs touching these files were not consulted.
• Tests: none were added, and the change alters no CLI behaviour, so §3 needs no scenario.

Not reconciled against this PR's discussion or earlier reviews.

[jussielo-amd]

Review conducted in an interactive Claude Code session at the maintainer's request (not the automated pr-review-watcher pipeline — posted as a comment-type review by design; it does not approve).

Review — no blocking findings

Full review of the whole change. Docs-only: adds the "ROCm CLI on WSL2" page to the docs site by single-sourcing the published sections of docs/wsl.md through anchored MyST {include} directives, copyedits docs/wsl.md, and links the new page from the install page and TOC. No Rust files are touched.

Blocking

None.

(At initial review, Coverage (rocm-dash crates, ratcheted) was red — Text file busy (os error 26) in an unrelated rocm-engine-vllm install test, clearly a parallel-test-execution flake rather than anything this PR could cause, since the PR touches zero Rust files. Re-checked live against the current head: that check is now green along with the rest of the rollup.)

Non-blocking

• PR #616 is open concurrently and touches two of the same files (README.md, docs/rocm-docs/install/installation.md), though in different regions (its own "Linux/WSL2 heading" and "Uninstall" sections vs. this PR's platform-support-table and diagnose-bullet edits). Low conflict risk, but worth knowing before merge order is decided.

Decisions for the author

None.

Positive signals

• Every non-trivial technical claim in the rewritten docs/wsl.md was checked against the actual code at the PR's base commit and holds up exactly: fix-wsl-5's abstain-on-non-Ubuntu and fix-wsl-6's abstain-on-WSL1 logic in diagnose.rs; the seven non-WSL-specific catalog entries (fix-1, fix-2, fix-6, fix-8, fix-16, fix-18, fix-19) that the CHECKERS table really does tag "wsl"; the --distro host-side probe script (WSL_REMOTE_PROBE) really collecting no environment variables and no comgr/shm data; --model/--report really being refused in combination with --distro; and the could not inspect '<name>'... error message matching examine.rs verbatim.
• The new MyST include anchors in docs/rocm-docs/install/wsl.md are all unambiguous — each :start-after:/:end-before: string occurs exactly once in the rewritten docs/wsl.md, so none of the six includes can silently grab the wrong span. The maintainer-only sections (TheRock runtime env design, install UX recommendations, test plans) are correctly excluded from every include boundary.

Deployment notes

None — docs-only, no migration, no runtime behavior change.

What this covered

Every changed file in full, diffed against the PR head (fe47c489...c794636, fetched read-only, never checked out), plus the source files the new prose makes claims about (crates/rocm-core/src/diagnose.rs, crates/rocm-core/src/examine.rs, apps/rocm/src/main.rs, apps/rocm/src/driver_install.rs) and PR #616's diff for the file-overlap check. Leak-scanned the full diff and the PR title/body for internal references: clean. Read CI's live statusCheckRollup directly rather than re-deriving coverage.

Did not run: a dedicated multi-agent fan-out — the change is small and single-concern, which calls for one thorough pass rather than splitting; a dedicated "prior review comments on this file's history" pass beyond a git log skim. Not reconciled against any other GitHub review thread on this PR.

This review does not include a GitHub approval — per this workflow's policy, approval authority stays with a human reviewer.

[rominf]

🔴 Automated review · pr-review-watcher · c794636

This automation never files a GitHub approval, so no approving review will
appear here whatever the outcome — the merge decision stays with a human
reviewer.

Third automated round (the earlier ones were filed against 38aca71 and f763c0e). Each finding is marked new this round or standing, meaning it was raised as non-blocking at f763c0e.

Nothing in this round gates the merge. Both change requests this automation held on this PR are withdrawn.

• The one item under Blocking below is about the PR description only. The f763c0e round rated the same gap non-blocking. This repository builds the squash commit from the commit messages, not the description, and the commit messages already cover these files. So merging leaves nothing wrong behind, and this round does not gate on it.
• The f763c0e round's two blocking objections were not re-found by this round's blind review. Each was then put to the reviewer as a standing objection. That check is anchored evidence, not a finding. The driver also checked both against the diff since f763c0e:
  • The shared-checks paragraph misdescribed fix-16 and fix-18: resolved by c794636. docs/wsl.md now lists the seven shared entries exactly, with no "such as". It says fix-16 is driven only by --symptom, and the "not environment checks" framing is gone.
  • :relative-docs: was inert, and 71b7923's message says it works: the option is removed from all four includes. 71b7923's sentence still lands in the squash body, but c794636's message, which lands in the same body, states that the option was removed and why. The record on main is therefore correct when read as a whole. What remains is a tidy-up of the squash body at merge, and it is carried below as non-blocking under the commit-messages item.

Review — needs work

Full review of the whole change.
The change implements what its description sets out: the WSL2 page on the docs site, copyedits, digest placeholders, and the --distro subsection. No ticket is named. It also splits work out of #616, which does not need checking here. The description leaves out several files the change edits (see Blocking).

Blocking

• (standing) The description does not mention three of the changed files — README.md:35-39, README.md:286-290, .github/workflows/ci.yml:204-212, docs/rocm-docs/index.rst:32
  The summary covers the new page, the docs/wsl.md edits, installation.md and _toc.yml.in. It never mentions these four changes:
  • README: the docs/wsl.md link moves out of the platform table and becomes a relative link below it.
  • README: the rocm diagnose --distro bullet now also says fix-18-comgr-conflict and fix-19-shm-too-small are skipped. This changes a user-facing claim about behaviour.
  • ci.yml: the docs-build path filter now includes docs/wsl.md.
  • index.rst: a new Install card entry.
    Readers use the description to decide what to check, so these README and CI edits would go unreviewed. The README claim is accurate (see the second Non-blocking item); only the description is incomplete.
    Confidence 85 · mechanical · Fix: add these four items to the PR description. The change itself does not need to shrink.

Non-blocking

• (standing) The note the CLI prints after a --distro run now says less than the docs — apps/rocm/src/main.rs:2907-2919, against README.md:286-290 and docs/wsl.md:263-269
  • The README bullet and the new docs/wsl.md bullet both say --distro skips fix-18 and fix-19.
  • The note printed after a remote run still names only the environment checks (HSA_OVERRIDE_GFX_VERSION, PATH, the framework/ROCm pairing).
  • AGENTS.md §5 says the same behaviour claim must be kept in step across README, --help, printed CLI output and docs/*.md.
  • The docs side is the correct one. The remote probe collects neither comgr selection nor shm_total_bytes, so check_18 returns zero at crates/rocm-core/src/diagnose.rs:1737 and check_19 at :1954.
  • The note's omission existed before this PR; the PR makes the mismatch visible, so this is not blocking.
    Confidence 85 · mechanical · Fix: extend the printed note to name fix-18 and fix-19, ideally in this PR (it would then contain a code change, with a test asserting the note). Otherwise, record it as a follow-up in the description.
• (standing) The by-hand install steps now point at a bare source path, on a page that is published to the site — docs/wsl.md:84-89, published through docs/rocm-docs/install/wsl.md:28-31
  • The rewrite swaps the inline 1.2.2 digest for a placeholder and adds "ROCDXG_PINNED_DIGESTS in apps/rocm/src/driver_install.rs… use the pinned digest".
  • That is a new citation written as a bare backtick path, which AGENTS.md §5 tells contributors not to do in docs/.
  • A relative link would point outside the Sphinx site, so the bare path is understandable. That is the same reason README is exempt, but the exemption list does not mention files that are {include}d into the site.
  • The practical effect: a site reader is told to use a digest they cannot reach from the page. The concrete digest was added on purpose in #224 (8788394) as the trust anchor for this fallback.
    Confidence 85 · mechanical · Fix: link the table with an absolute GitHub URL, which works in the repo and on the site. Also consider asking for AGENTS.md §5 to list {include}-sourced files like docs/wsl.md and docs/vllm.md among its exceptions.
• (standing) Several commit messages will put wrong statements into the squash body — commits 71b7923, 6649870, f763c0e, b65cd5b, 43bff27
  This repo builds the squash body from the commit messages, and several of them no longer match the final change:
  • 71b7923 says the includes "use :relative-docs:", but c794636 removes that option as having no effect.
  • 6649870 lists the shared checks as "fix-1, fix-2, fix-6, fix-8, fix-16", but c794636 corrects this to seven.
  • f763c0e is a bare Merge remote-tracking branch 'origin/main'.
  • b65cd5b and 43bff27 are subject-only.
  • Ten commits carry Co-Authored-By: Claude trailers, against AGENTS.md §11 "avoid AI-generated boilerplate footers". Main already has four such trailers, so this is a convention point rather than a blocker.
    Confidence 85 · mechanical · Fix: squash or rewrite the history, or edit the squash body at merge, so it describes only the final change.
• (new) The rewritten manual block keeps a predictable /tmp download path and now publishes it — docs/wsl.md:95-100
  • The block still writes to /tmp/rocdxg-roct_${ROCDXG_VERSION}_amd64.deb before running sha256sum -c and sudo apt install on it. Issue #425, still open, is about exactly this pattern.
  • The pattern predates this PR. The PR rewrites the block and puts it on the public docs site.
    Confidence 70 · logic · Fix: download into a mktemp -d directory, or link #425 from the page.

Decisions for the author

• Digest placeholders or an inline pinned digest — tradeoff
  • Placeholders cannot go stale. The old inline digest was never checked against ROCDXG_PINNED_DIGESTS.
  • Placeholders also remove the copy-paste verified path for the default version, which #224 deliberately added. That path does not drift if a check pins the doc digest to the code table.
• Single-sourcing with sentence-text anchors and one hand-copied sentence — tradeoff
  • Includes anchored on prose ("To inspect a distro without installing anything in it", "and run this from PowerShell:") break the docs build when that prose is reworded. That is loud, and CI now rebuilds the docs on docs/wsl.md changes.
  • The hand-copied sentence in install/wsl.md can still drift in wording without anything failing, as long as its last line still matches. The in-file comment covers this, but the guard is only partial.
• "Setting it on a newer release is harmless" (HSA_ENABLE_DXG_DETECTION) — this is a new claim with no source in code or docs. The description already lists it for SME confirmation; settle that before merge.

Positive signals

• The include ranges are cut so that the one repo-only link in the published sections (../README.md#windows-x86_64-powershell) stays off the site. The wrapper carries a retargeted copy of that sentence instead.
• Adding docs/wsl.md to the CI docs path filter means any edit that breaks an include anchor fails the -W docs build, instead of breaking the site silently.
• The four "--json only" markers on the rocm examine items match the text renderer exactly (crates/rocm-core/src/host_gpu.rs render_text).
• The list of seven shared checks also matches the code exactly (diagnose.rs CHECKERS tagged wsl).

Deployment notes

None

What this covered

• Read: every changed file in full, prw-base (9a8c5a0) … c79463601b51.
• Checked against code: the claims in the changed lines, against crates/rocm-core/src/{diagnose,fix,examine,host_gpu}.rs, apps/rocm/src/driver_install.rs and the diagnose/examine paths in apps/rocm/src/main.rs. Every factual claim about --distro, the catalog, abstention, the error text and the --model/--report conflicts was confirmed in code.
• Sphinx includes: the start-after/end-before resolution was traced line by line.
• History: the history of the rewritten regions (#224, #340), and review comments on earlier PRs #224, #340, #384 and #386.
• CI at head: green apart from E2E tests (MI300X), which was still queued. That includes Sphinx docs build (-W) and lychee. The MI300X lane is also queued with no runner on main, so its absence is a runner-availability issue, not a result for this PR.

Did not run:

• Local builds or tests: the change touches docs only and the docs build is green in CI.
• Test verdicts: none apply, because no tests were added or changed.
• Gherkin scenario: none is needed for a documentation-only change, per AGENTS.md §3.
• Design review: done by the driver from the workers' results, not as separate independent workers.

The PR's discussion was not reconciled here. No prompt-injection content was found.

Both objections from the f763c0e round are resolved at c794636: the shared-checks paragraph now lists the seven entries exactly and describes fix-16 and fix-18 correctly, and the inert :relative-docs: option is removed, with c794636's message retracting 71b7923's claim in the same squash body. See review 5500838818.