docs: copyedit README, CONTRIBUTING, and vLLM; add uninstall and verify guidance

[pmoutsias-amd]

Summary

This PR has fourteen commits: four that add content (1, 5, 6, and 9), two that add or place cross-reference links (7 and 8), three copyedit commits (2 to 4), two that correct commit 9 (10 and 11), one that corrects commits 5 and 6 and the diagnose text (12), one that addresses the automated review (13), and one that rewords the default-version text (14). Commits 2 to 4 add no new facts; commits 1, 5, 6, 9, 10, 11, 12, 13, and 14 do, and are described separately below so they can be reviewed apart from the wording changes.

1. Call out supported ROCm versions (7.14, 10.0, 10.1)

• States that ROCm CLI supports ROCm 7.14, 10.0, and 10.1, and that rocm install sdk currently installs ROCm 7.14 when --version is omitted. The statement appears in the ROCm installation intro and in Getting started (commits 13 and 14 reword it from "default 7.14").
• Explains that ROCm 10.0 or newer needs a --version pin and the exact GPU arch as a raw gfx code through --family, with an example (--version 10.1.0 --family gfx1200).
• Moves the "ROCm 10 and newer" section from the end of "ROCm installation" to just after "Install location". The new intro sentence points readers to that section, so it now sits next to the other install sdk subsections (--devel, approval prompt, install location) and ahead of the unrelated "Driver installation" and "Updates" sections. This is the only block move in the PR, and it belongs with the new pointer sentence: if the pointer goes, the move should go with it.
• Updates the getting-started.md include anchor to match the reworded README sentence.

2. Copyedit README, CONTRIBUTING, and vLLM guide

• Copyedit-only pass on README.md, CONTRIBUTING.md, and docs/vllm.md, which are single-sourced into the docs site.
• Style and consistency changes: removed em dashes and spaced double hyphens, "instead of" and "through" in place of "rather than" and "via", replaced and/or and word slashes, spelled out TUI on first use in each standalone doc, American spellings, split long paragraphs.
• Doc links in README.md and CONTRIBUTING.md now use absolute GitHub URLs so they resolve on the docs site.
• "WSL" is now "WSL2" in the README heading and live-mode note, matching the platform table.
• No new facts, no restructuring, no docs-site wiring changes.

3. Tighten README flag lists and add lead-ins

• Keeps the rocm diagnose flag list tight (one paragraph per bullet) by moving the long --report and --send detail below the list.
• Adds a colon lead-in to the diagnose, fix, dash, and bench load lists.

4. Rejoin prune lock sentence and complete acceptance-script list

• Rejoins "The same lock runs in the other direction..." to the preceding services prune paragraph, so its reference to the wait is not left dangling.
• Moves the two behaviors that sat outside the vLLM acceptance-script list ("rejects external vLLM command overrides", "does not allow CPU fallback") into the list.

5. Add install verification and rocm uninstall guidance (new content)

• Adds a "Verify the installation" section after the install commands: run rocm version, which prints the CLI version (release tag or branch and commit hash), the ROCm SDK this machine would use, and the GPU driver version, or not detected for the last two when none is found.
• Documents rocm uninstall under "Logs and cleanup": what --dry-run, --yes, and each --keep-* flag do (commit 13 adds the default-layout caveat for the --keep-* flags), and a new --force-dev-binaries entry in the usage block.
• Notes what uninstall warns about before it removes anything: shared caches it leaves alone, managed service records (their processes are not stopped), and remote sessions (run rocm remote stop <session> first).
• Statements were checked against the CLI source in apps/rocm/src/main.rs (version(), build_uninstall_plan(), and the Uninstall flag definitions), not copied from the earlier draft; commit 13 corrects one flag claim that this check missed, which said rocm version showed only the CLI version and that uninstall warned about services "still running".
• Needs a content reviewer to confirm. No site wiring: the new verify section is picked up by the existing include on the installation page.

6. Clarify verify and uninstall guidance (new content)

• Verify section: says what a successful rocm version run looks like, that not detected for the SDK and driver is expected before ROCm or a driver is installed, and what to check if rocm is not found.
• Uninstall: names the four categories it removes (binaries, configuration, data, caches) and lists the managed ROCm SDK installs under --keep-data, since they live in the data directory.
• Uninstall warnings: split into a list (managed service records, remote sessions) and a sentence naming the shared caches it leaves in place (the uv package cache and the Hugging Face model cache; commit 12 refines this). Checked against build_uninstall_plan() and shared_cache_candidates().

7. Link install pages to uninstall guidance

• Adds one sentence in the README "ROCm installation" section and one on the site install page (docs/rocm-docs/install/installation.md) pointing to "Logs and cleanup", so readers can find how to remove ROCm CLI. The site-page sentence is first placed directly under Build from source; commit 8 moves it.

8. Give the install page uninstall pointer its own heading

• On the site install page, moves the uninstall pointer under a new ## Uninstall ROCm CLI heading so it doesn't read as part of Build from source, and keeps the existing Contributing sentence in its original place. This and commit 7 are the only changes in this PR to a site wrapper; neither adds include anchors or alters existing ones.

9. Fix command synopses and document rocm model, rocm chat --provider, and automation modes (new content)

• Synopses: adds --send (requires --report) to rocm diagnose and the positional [QUERY ...] to rocm logs.
• Adds a short "Curated models" section for rocm model [--verbose] (alias rocm models), which the "Will a model run here?" text already referred to, and splits that text's undetermined conditions into a list.
• Chat: replaces the anthropic|openai|... placeholder with local|openai|anthropic, and documents --provider setup (rocm config enable-provider and set-provider-key) and --tools.
• Automations: describes observe, propose, and contained. In contained mode only server-recover acts on its own (restarts a failed managed service); the others stay review-gated or record only, per crates/rocm-core and apps/rocmd/src/watchers.rs. Per-watcher default modes are left out to avoid a table that can drift.
• All checked against apps/rocm/src/main.rs.

10. Clarify that rocm chat --provider applies only to one-prompt use

• In an interactive terminal, rocm chat without --prompt opens the dashboard chat, where you switch providers with /provider <name>. With --prompt or piped input, it sends one prompt and prints the reply.
• Notes that --provider is ignored by the dashboard chat, and that local is the default.
• Checked against the Command::Chat handler in apps/rocm/src/main.rs.

11. Correct contained-mode, chat flag, and model verbose descriptions

• Chat: extends the note to --model and --tools, which the dashboard chat also ignores, and states it once for all three flags.
• Automations: corrects the contained description, which overstated that every watcher applies changes on its own. propose now says it applies to watchers that can make a change.
• rocm model --verbose: describes what it prints (every recipe, including hidden ones, with aliases, data type, minimum GPU memory, and engines) instead of repeating the flag's help text.
• Checked against the Command::Chat handler in apps/rocm/src/main.rs, and against the watcher code in crates/rocm-core and apps/rocmd/src/watchers.rs.

12. Clarify uninstall cache and data scope, add APU case to diagnose

• Uninstall: separates the managed uv cache (under the data directory, controlled by --keep-data) from the shared one (UV_CACHE_DIR or ~/.cache/uv, left in place and reported). Lists downloaded models under --keep-data, since they live in the data directory and uninstall removes them.
• Diagnose: the undetermined conditions now include the APU case, where the CLI can't yet read the memory pool the engine uses. Checked against UndeterminedReason in model_readiness.rs.
• Audit of the rest of the new text against source found no other discrepancies.

13. Address automated review: uninstall default layout, ROCm versions, synopses

• Uninstall: on the default layout the config and data directories are both ~/.rocm and the cache is ~/.rocm/cache, so a single --keep-* flag doesn't protect its files. The intro now says each flag "skips the removal of one category", and a new paragraph says to pass --keep-config and --keep-data together and to run --dry-run first. docs/engine-plugins.md gets the same caveat. The earlier "checked against build_uninstall_plan()" claim had verified each flag in isolation, not the overlapping default layout. The behavior itself is tracked in uninstall: --keep-* flags are ignored when config, data, and cache directories overlap (default layout) #626.
• ROCm versions: reworded as a support statement ("supports ROCm 7.14, 10.0, and 10.1") instead of a hardcoded default. Source has no allow-list or default version. Commit 14 replaces the "latest stable release, currently 7.14" wording, which was wrong because 10.1 is the latest stable release.
• Disk space: the "never removed" claim is narrowed to rocm storage, because rocm uninstall does remove downloaded models unless you pass --keep-data.
• Synopses: rocm diagnose [--symptom TEXT] [--top N] [--json] [--distro [NAME] | --report [--send]] and rocm storage [report [--json]]. The undetermined list now points to rocm model --verbose.
• getting-started.md: resyncs the hand-copied sentence with the README.

14. Avoid calling 7.14 the latest stable release

• ROCm 10.1 is the latest stable release, so the README no longer describes the unpinned result as the "latest stable release". It now says rocm install sdk "currently installs ROCm 7.14" without --version, and that 10.0 or 10.1 need --version and --family.
• The 7.14 default comes from an automated review's dry run (7.14.1), not from source, so it still needs confirmation from the CLI owners.

Test plan

• All 14 {include} directives in docs/rocm-docs/ still find their :start-after: and :end-before: strings, in order, against the edited files.
• Code fences and tables are balanced, intra-doc anchors resolve, and no flags, numbers, or versions were added or removed by the copyedit commits (commits 2 to 4).
• All commits are signed and carry a DCO Signed-off-by trailer.
• New technical claims in commits 5, 6, 9, 10, and 11 were checked by reading the CLI source. The binary was not built or run.
• The docs example rocm install sdk --version 10.1.0 --family gfx1200 --dry-run resolves on WSL2 (run 2026-10-09): ROCm 10.1.0, torch 2.14.0, torchvision 0.28.0, and torchaudio 2.11.0.3, all +rocm10.1.0, with no error. A review dry-run the same day showed an unpinned install picking 7.14.1. The dry-run on WSL2 did not use a gfx1200 GPU. A review dry-run of --version 10.0.0 --family gfx1200 failed on a torchaudio mismatch (it selected the 10.1.0 build).
• Content reviewer confirms three claims: rocm uninstall warns about remote sessions, contained mode acts on its own only for server-recover, and the dashboard chat ignores --model and --tools.
• docs-build passes in CI.
• Spot-check the rendered getting-started, installation, and vLLM pages.

[rominf]

🔴 Automated review · pr-review-watcher · cf49378

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.

Review — needs work

Full review of the whole change.
No ticket named. The description lists twelve commits and covers what the diff does. One of its claims is wrong: it says the uninstall text was "checked against build_uninstall_plan()", and the first blocking finding below shows it was not.

This is the first automated round on this PR, so every finding below is new.

Blocking

• (new) On a default install, the new rocm uninstall text promises that each --keep-* flag keeps its category. It does not. — README.md:924-934; same claim at docs/engine-plugins.md:98; root cause apps/rocm/src/main.rs:21012 (build_uninstall_plan) with crates/rocm-core/src/runtime.rs:215-227

  • By default the config dir and the data dir are both ~/.rocm, and the cache dir is ~/.rocm/cache. The plan deletes each category's directory unless that category's flag is passed.
  • I ran rocm uninstall --dry-run --keep-binaries with a throwaway HOME:
    • --keep-data still plans config: ~/.rocm, which wipes the models, managed SDK installs and uv-cache the README says it keeps.
    • --keep-config still plans data: ~/.rocm, which contains the config.
    • --keep-cache still plans config: ~/.rocm, which contains cache/.
  • "Each --keep-* flag leaves one category in place" is therefore false on the default layout. A user who trusts --keep-data loses every managed runtime and downloaded model.
  • The code decides what actually happens, so the text is the side that is wrong today. The bug underneath is in the code.
  • Confidence 100 · logic · Fix: either make the plan honour a kept category when directories overlap (skip deleting a directory that contains or equals a kept one), or document that on the default layout these flags only work in combination. The code fix is the better one.

• (new) The new ROCm version claims state a moving value as fixed and give a list of installable versions that is wrong today. — README.md:228, README.md:395 (README.md:228 is also included into docs/rocm-docs/getting-started.md)

  • The source has no allow-list of versions. Without --version, therock.rs installs whatever the release index currently lists as latest.
  • I ran dry-runs against the live public index:
    • install sdk --family gfx120X-all --version 7.13.0 --dry-run resolves 7.13.0, which "It can install ROCm 7.14, 10.0, or 10.1" excludes.
    • --version 10.0.0 --family gfx1200 --dry-run fails ("selected torchaudio 2.11.0.3+rocm10.1.0, which does not share ROCm build 10.0.0").
    • The default today picks 7.14.1.
  • "By default … installs ROCm 7.14" becomes wrong at the next release, and install sdk --help says nothing about a default version.
  • Confidence 85 (run-confirmed, but it depends on what the index serves today) · logic · Fix: say "the latest stable release (currently 7.14)". If 7.14, 10.0 and 10.1 are a support statement, call them "supported" rather than "can install", and recheck that 10.0 actually works before listing it.

Non-blocking

• (new) The README now contradicts itself about downloaded models. — README.md:557-562 against README.md:931-932

  • The new uninstall text says --keep-data keeps downloaded models, which is correct: they sit under <data>/models, and uninstall deletes data_dir.
  • The reworded Disk space paragraph, and rocm storage's "Shared with other tools (never removed by ROCm CLI)" heading (apps/rocm/src/storage.rs:508-514), still say they are never removed.
  • The code decides this, so the Disk space sentence and the storage label are the ones to fix. That claim was there before this PR.
  • Confidence 88 · mechanical · Fix: limit "never removed" to the uv and Hugging Face caches, or to rocm storage's commands.

• (new) Two --help texts now contradict the README this PR corrected (AGENTS.md §5: check the same claim on every surface). — apps/rocm/src/main.rs:299-302, apps/rocm/src/main.rs:185-195

  • rocm chat --help still says it "Reads the prompt from --prompt or, if omitted, from standard input". The README now correctly says an interactive run without --prompt opens the dashboard chat (main.rs:2226).
  • rocm diagnose --help describes --send as a "prefilled issue form" that "reaches the tracker". The README correctly describes a prefilled mail (report_delivery.rs).
  • Both were stale before this PR.
  • Confidence 85 · mechanical · Fix: update both doc comments to match the README.

• (new) The pointer from diagnose --model's undetermined list to rocm model is incomplete. — README.md:594-595

  • The new Curated models section (README.md:607-610) says the default list hides some recipes, and only --verbose shows them.
  • assess_model_readiness matches against every recipe, hidden ones included.
  • Confidence 75 · mechanical · Fix: point at rocm model --verbose.

• (new) Synopsis errors that predate this PR survive a commit titled "fix command synopses". All confirmed against the built binary's --help or by a run.

  • README.md:533, rocm storage [report] [--json]: rocm storage --json fails with "unexpected argument '--json'". It should read rocm storage [report [--json]].
  • README.md:298: the edited [--distro [NAME]] [--report [--send]] implies the two can be combined, but the CLI rejects --report with --distro.
  • README.md:617-626: the rocm serve synopsis omits --gpu-memory-utilization, --tool-call-parser, --api-key and --require-api-key.
  • README.md:568: the rocm engines install synopsis omits --yes.
  • Confidence 100 · mechanical · Fix: correct the synopses, or narrow what the commit claims to fix.

• (new) The hand-copied sentence on the docs site was not updated with its README original. — docs/rocm-docs/getting-started.md:35-37

  • The README now reads "GGUF versus safetensors rule, because which…", but the copy still says "GGUF-vs-safetensors rule, since which…".
  • The include anchor is unaffected, so this is wording drift only.
  • Confidence 85 · mechanical · Fix: copy the new wording over.

Decisions for the author

• Absolute blob/main links instead of relative ones — tradeoff
  • In favour: CONTRIBUTING.md and the README "More docs" list are pulled into the Sphinx site, where relative docs/… links would break. The files already use this pattern.
  • Against: those links are no longer checked by the offline docs-links (lychee) job. On a versioned docs site they always point at main, not the release being read.

Positive signals

• Every {include} slice in docs/rocm-docs/ still resolves to a unique, intended span. The only changes against the base are the intended content. A local sphinx-build -W passed, and CI's Sphinx and lychee jobs are green.
• The new undetermined bullets, including the APU case, match UndeterminedReason::UnifiedMemoryUnreadable in model_readiness.rs exactly.
• The rocm chat text now describes the code's real split between the interactive dashboard chat and the one-prompt form (main.rs:2226).
• The docs/vllm.md restructure keeps every qualifier and condition. Each technical claim in it was confirmed against engines/vllm/src/install.rs, and the (0, 1] range check was confirmed by a run.

Deployment notes

None

What this covered

• Read: every changed file in full, against 2c37f5bc…cf49378a (base merge-base 7f72556d → head), using the PR's three-dot diff. That is README.md, CONTRIBUTING.md, docs/vllm.md, docs/rocm-docs/getting-started.md and docs/rocm-docs/install/installation.md.
• Also read: every docs/rocm-docs include wrapper, and the CLI source behind each new claim (main.rs, therock.rs, storage.rs, model_readiness.rs, runtime.rs, apps/rocmd/src/watchers.rs, engines/vllm/src/install.rs).
• Ran: the CLI built from this head, for --help and dry-runs, with throwaway HOME dirs. CI status was read for head cf49378: all checks green, GPU lanes skipped as docs-only. The --keep-data dry-run in the first blocking finding was re-run independently before filing.
• Fan-out: five independent workers. Three covered disjoint README ranges plus include integrity, one covered CONTRIBUTING.md and docs/vllm.md, and one ran agent-instruction adherence, history, code comments, prior-PR review comments (#473, #396, #311, #579) and commit quality.
• Did not run: the version findings depend on the live package index on 2026-10-09.
• Not reconciled against any discussion on this PR.

[randyh62]

Maybe this could simply have a rocm uninstall command example, and then point to Logs and Cleanup?

[randyh62]

This starts with installing a rocm sdk, but shouldn't it start by checking if the needed sdk is available using rocm examine? Then if you need a different version of configuration you would run rocm install sdk?

[randyh62]

Suggested change

	first, because the new install takes over as the active default; see
	Running _rocm install sdk_ when a managed runtime is already active prompts for confirmation first, because the new install takes over as the active default; see

[randyh62]

Suggested change

	moved to the SDK's *build* of the torch *release* that the engine pins: the release

[randyh62]

Is it most SDK versions or 7.14?

[randyh62]

Maybe break this sentence into two or three sentences?