From 7fdade9e33a9a52ab3a825d7939346d9575f9031 Mon Sep 17 00:00:00 2001 From: anisha-amd Date: Tue, 25 Aug 2026 15:06:28 -0400 Subject: [PATCH] Editorial pass and review of docs Editorial style pass on docs folder: sentence-case headings, updated References/Sources sections for better headings, replaced em dashes and prose slashes in excessive usage, fixing spelling, meaningful link anchors, env-var placeholder definitions and language fixes. Signed-off-by: anisha-amd --- docs/automations.md | 6 +-- docs/ci-hardware-testing.md | 44 ++++++++++----------- docs/commit-signatures.md | 23 +++++------ docs/demos.md | 2 + docs/engine-plugins.md | 8 ++-- docs/llm-tool-use.md | 18 +++++---- docs/manual-testing.md | 20 +++++----- docs/release-trust.md | 19 ++++----- docs/rocm-docs/install/installation.md | 2 +- docs/testing.md | 55 +++++++++++++------------- docs/ux-guidelines.md | 18 +++++++-- docs/vllm.md | 22 ++++++----- docs/wsl.md | 16 ++++---- 13 files changed, 136 insertions(+), 117 deletions(-) diff --git a/docs/automations.md b/docs/automations.md index 34ef93b0c5..ce6b3b0046 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -10,7 +10,7 @@ rocm-cli automations are local watcher events routed through explicit watcher policy. A webhook payload is an event input, not an execution API: it cannot grant a new action, choose a tool, override watcher mode, or run shell. -## Local Webhook Source +## Local webhook source Start the persistent watcher loop with a loopback-only webhook source: @@ -58,7 +58,7 @@ The listener only binds to `127.0.0.1`. There is no LAN or cloud webhook listener, and local webhook events still dispatch through the configured `observe`, `propose`, or `contained` policy for the target watcher. -## Restricted Tool API +## Restricted tool API Automation actions never receive arbitrary shell access. Reviewed requests and contained watcher work can only call this restricted tool surface: @@ -163,7 +163,7 @@ Invoke-RestMethod ` http://127.0.0.1:18080/automation-events ``` -## Artifact Prefetch Action +## Artifact prefetch action The reviewed artifact-prefetch action keeps downloads disabled unless the caller explicitly approves a source policy: diff --git a/docs/ci-hardware-testing.md b/docs/ci-hardware-testing.md index c5886620f3..2ce80edcc6 100644 --- a/docs/ci-hardware-testing.md +++ b/docs/ci-hardware-testing.md @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# CI hardware (GPU / WSL) testing +# CI hardware (GPU and WSL) testing The hosted CI (`ubuntu-latest`, `windows-latest`) builds and unit-tests every shipping target natively, but GitHub-hosted runners have no AMD GPU. A @@ -16,8 +16,8 @@ separate from the main `ci.yml`. The split is deliberate: a job queued on an **offline** self-hosted runner cannot be cancelled by GitHub, so if it shared `ci.yml`'s concurrency group a superseded run would hold that group and the newer run's merge-required (GitHub-hosted) checks would sit pending forever -(observed on PR #138). Giving the self-hosted lanes their own workflow — and -thus their own concurrency group — means an offline runner can only ever stall +(observed on PR #138). Giving the self-hosted lanes their own workflow, and +thus their own concurrency group, means an offline runner can only ever stall that workflow's own supersession, never `ci.yml`'s required checks. See `EAI-7548`. @@ -26,7 +26,7 @@ that workflow's own supersession, never `ci.yml`'s required checks. See The E2E suite (BDD scenarios in Gherkin `.feature` files backed by Rust step functions) runs as one job per platform. Each job's harness resolves every scenario to pass / xfail / skip for that host from its `@id` and -`@requires-*` tags, a capability probe, and `expectations.toml` — there is no +`@requires-*` tags, a capability probe, and `expectations.toml`; there is no separate tier flag or tag filter to maintain. | Job | Workflow | Platform | Runner labels | @@ -72,8 +72,8 @@ workspace; the lane installs them itself where it has passwordless sudo, and otherwise fails with the list of what is missing rather than hanging on a password prompt. -GPU coverage additionally needs ROCm's WSL passthrough to be complete — -`/dev/dxg` and dxcore alone are not enough, `librocdxg.so` and its ldconfig +GPU coverage additionally needs ROCm's WSL passthrough to be complete: +`/dev/dxg` and dxcore alone are not enough; `librocdxg.so` and its ldconfig entry must be present too. `rocm examine` reports the verdict as `driver_status: wsl_rocdxg_ready`; anything else (`wsl_rocdxg_missing`, `wsl_gpu_plumbing_missing`) means the runtime cannot reach the device even @@ -88,13 +88,13 @@ covers the mock platform; `e2e-selfhosted.yml`'s `e2e-report` covers the GPU platforms; `nightly.yml`'s `e2e-report-nightly` covers the same platforms with the `@nightly` scenarios included. Each joins its platforms' -reports — including partial or failed runs — by scenario id into one HTML report +reports, including partial or failed runs, by scenario id into one HTML report and GitHub step summary. The lane artifacts are named canonically (`e2e-report`, `e2e-gpu-report`, `e2e-gpu-rad3-report`, `e2e-gpu-strix-ubuntu-report`, `e2e-gpu-strix-windows-report`, `e2e-gpu-strix-wsl-report`) in every workflow, because the report derives each -platform's name and OS from the artifact name. An unrecognised name renders as a +platform's name and OS from the artifact name. An unrecognized name renders as a guessed platform on Linux, which would report a Windows lane as Linux; `xtask`'s `every_uploaded_e2e_artifact_has_a_name_the_report_can_label` guards against it. @@ -103,15 +103,15 @@ guessed platform on Linux, which would report a Windows lane as Linux; `xtask`'s The GPU jobs (in `e2e-selfhosted.yml`) run automatically on `push`, `pull_request`, and `merge_group` when the workflow's own `changes` job's `serve` path filter is `true`. `serve` is narrower than `heavy`: it matches only -paths that can change serve *behaviour* or the GPU E2E harness (the engines, the +paths that can change serve *behavior* or the GPU E2E harness (the engines, the serve code path in `apps/rocm`/`apps/rocmd`, `rocm-core`, the e2e-cucumber crate, plus broad-dependency safety nets), **not** a blanket `**/*.rs`. So a Rust change -that cannot affect serving — e.g. a dashboard-only or unrelated-crate PR — skips +that cannot affect serving (for example, a dashboard-only or unrelated-crate PR) skips the heavy GPU matrix, while compile coverage for every crate still runs on `ci.yml`'s always-on build/test lanes. Off `pull_request` (push/merge_group) the filter is forced `true`, so the full matrix always runs there. Unlike the pre-split layout the GPU jobs do **not** gate on the hosted `build-and-test` job -— cross-workflow `needs` is not possible, so each GPU job builds the `rocm` +(cross-workflow `needs` is not possible), so each GPU job builds the `rocm` binary itself as its first real step (a broken build fails that job fast and non-fatally). `ci.yml`'s required `build-and-test` and mock `e2e` remain the authoritative pre-merge build gate. @@ -120,16 +120,16 @@ They can also be triggered manually via `e2e-selfhosted.yml`'s `workflow_dispatch`, independent of the `serve` gate, with these inputs: - `platform` (choice: `all`, `app-dev-gpu`, `strix-ubuntu`, `strix-windows`, - `strix-wsl`, `rad3`) — which self-hosted job(s) to run. `app-dev-gpu` maps to + `strix-wsl`, `rad3`): which self-hosted job(s) to run. `app-dev-gpu` maps to `e2e-gpu`, `strix-ubuntu` to `e2e-gpu-strix-ubuntu`, `strix-windows` to `e2e-gpu-strix-windows`, `strix-wsl` to `e2e-wsl`, and `rad3` to `e2e-gpu-rad3`. (The mock lane has its own `platform` input on `ci.yml`; it is not part of this workflow.) -- `name_filter` (string) — a scenario-name regex forwarded to the cucumber +- `name_filter` (string): a scenario-name regex forwarded to the cucumber harness (`cargo xtask e2e -- --name `) so a dispatch can run a single scenario instead of the full suite. Empty runs everything applicable to the selected platform(s). -- `include_nightly` (boolean, default `false`) — opts a dispatch into +- `include_nightly` (boolean, default `false`): opts a dispatch into `@nightly`-tagged scenarios (e.g. large-model serves, cold installs) that are otherwise skipped on a normal push/PR run to keep it fast. @@ -178,14 +178,14 @@ the pre-warm block is duplicated across multiple jobs in two shells; ## Blocking vs. non-blocking -The self-hosted jobs — `e2e-gpu`, `e2e-gpu-strix-ubuntu`, -`e2e-gpu-strix-windows`, `e2e-wsl`, and `e2e-gpu-rad3` — all run with `continue-on-error: true`, so a +The self-hosted jobs (`e2e-gpu`, `e2e-gpu-strix-ubuntu`, +`e2e-gpu-strix-windows`, `e2e-wsl`, and `e2e-gpu-rad3`) all run with `continue-on-error: true`, so a hardware failure that RUNS never gates a PR merge. Their results still surface in the self-hosted consolidated report for visibility. ### Timeouts on the shared Strix box -Three of those lanes — the two native Strix ones and `e2e-wsl` — run on the same +Three of those lanes (the two native Strix ones and `e2e-wsl`) run on the same physical machine and can be in flight together, so a wait that is comfortable on an idle runner can expire while a sibling lane loads a model. Two budgets are raised there rather than letting contention read as a product failure: @@ -196,12 +196,12 @@ genuine hang still fails, just later. **Required-check caveat.** These three job names (plus, historically, a consolidated-report name) are still in `main`'s required-status-check list. `continue-on-error` neutralizes a job that ran and failed, but a required check -that *never reports* — because its self-hosted runner is offline — is treated as +that *never reports* (because its self-hosted runner is offline) is treated as missing and still blocks the merge. The workflow split removes the catastrophic concurrency stall (an offline runner can no longer freeze `ci.yml`'s hosted required checks), but fully unblocking merges while a runner is offline -additionally requires removing these self-hosted checks from the required list — -a branch-protection change tracked separately from the workflow split. +additionally requires removing these self-hosted checks from the required list +(a branch-protection change tracked separately from the workflow split). ## Fork safety @@ -218,8 +218,8 @@ which requires write access to trigger). not performance, so this is not a performance benchmark. Release-fidelity, `manylinux2014` (glibc 2.17) packaging validation is handled separately by the nightly/release pipeline. -- Each workflow's `e2e-report` job collects whatever ran in that workflow — - including partial results from a cancelled or failed job — and renders one +- Each workflow's `e2e-report` job collects whatever ran in that workflow, + including partial results from a cancelled or failed job, and renders one HTML report plus a step summary. `download-artifact@v8` flattens a single-match download straight into the artifacts directory (it uses the root path when exactly one artifact matches, regardless of the pattern), so after diff --git a/docs/commit-signatures.md b/docs/commit-signatures.md index fc9315c446..a9a1c4c6f7 100644 --- a/docs/commit-signatures.md +++ b/docs/commit-signatures.md @@ -4,20 +4,20 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# Commit Signatures and Sign-off +# Commit signatures and sign-off Every commit that lands in this repository must be: -1. **Cryptographically signed** — so authorship is verifiable and history +1. **Cryptographically signed**, so authorship is verifiable and history cannot be silently forged or impersonated. -2. **Signed-off** — a DCO `Signed-off-by:` trailer, certifying you have the +2. **Signed-off**: a DCO `Signed-off-by:` trailer, certifying you have the right to submit the change under the project license. Both requirements are **enforced**, not advisory: local git hooks reject non-conforming commits before they leave your machine, and a blocking CI gate rejects them on every pull request. -## Setting Up Signing +## Setting up signing You can sign with SSH (simplest if you already have an SSH key) or GPG. @@ -50,7 +50,7 @@ To add sign-off to a range of existing commits: git rebase --signoff ``` -## Registering Your Key on GitHub (required for CI) +## Registering your key on GitHub (required for CI) CI uses **strict** verification: it asks GitHub whether each commit's signature is `verified`. For GitHub to report a commit as **Verified** you must: @@ -63,7 +63,7 @@ is `verified`. For GitHub to report a commit as **Verified** you must: If either is missing, the signature exists but GitHub will not mark it "Verified", and the CI gate will fail. -## How Enforcement Works +## How enforcement works ### Local hooks (prek) @@ -74,10 +74,10 @@ prek install # pre-commit prek install -t pre-push # pre-push ``` -- **pre-commit**: `cargo xtask verify-commits --check-config` — a fast check +- **pre-commit**: `cargo xtask verify-commits --check-config`, a fast check that commit signing is enabled (`commit.gpgsign`, in any of git's truthy spellings) and `user.signingkey` is set, with remediation if not. -- **pre-push**: `cargo xtask verify-commits` — verifies every outgoing commit +- **pre-push**: `cargo xtask verify-commits`, which verifies every outgoing commit in `origin/main..HEAD` is signed (signature present and not bad) and signed-off. The base is fixed at `origin/main`, so keep it fetched (`git fetch origin main`); on a branch targeting a different base, run the @@ -96,13 +96,14 @@ cargo xtask verify-commits --base origin/ --require-verified CLI). The job checks out with `fetch-depth: 0` so the base ref and all PR commits are available. On a `merge_group` event it verifies the queued commits against the queue's base (`merge_group.base_sha..head_sha`) instead of a PR -base — so the check still runs in the queue and can safely be made *required* +base, so the check still runs in the queue and can safely be made *required* without stalling it. Mark it as a required check in branch protection / your repository ruleset so it blocks merges. ### The xtask check -`cargo xtask verify-commits` is the single source of truth for the logic: +`cargo xtask verify-commits` is the single source of truth for the logic. Its +flags are: | Flag | Meaning | | ------------------- | ---------------------------------------------------------------- | @@ -112,7 +113,7 @@ repository ruleset so it blocks merges. An empty commit range is treated as success. -## Native GitHub Ruleset (Complementary) +## Native GitHub ruleset (complementary) GitHub can natively **require signed commits** via a repository ruleset. Enable it as defense-in-depth alongside the in-repo check: diff --git a/docs/demos.md b/docs/demos.md index 6e33f26f42..dd630e67e7 100644 --- a/docs/demos.md +++ b/docs/demos.md @@ -19,6 +19,8 @@ to source branches; the README references them by absolute raw URL. ## Layout +The demo pipeline uses these paths and jobs: + | Path | Purpose | | --- | --- | | `docs/tapes/cli.tape` | CLI first-use journey. | diff --git a/docs/engine-plugins.md b/docs/engine-plugins.md index b2909eaaba..e59bb9ed37 100644 --- a/docs/engine-plugins.md +++ b/docs/engine-plugins.md @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# Engine Plugins +# Engine plugins rocm-cli discovers serving engine adapters as executable files. @@ -15,10 +15,10 @@ Search order: 3. Packaged sibling binaries installed beside `rocm` The first directory is the preferred location for external adapters. Use a -binary name in the form `rocm-engine-` on Linux/WSL and +binary name in the form `rocm-engine-` on Linux or WSL and `rocm-engine-.exe` on Windows. -Packaged first-party adapters are `lemonade` and `vllm`. Linux/WSL-only ROCm GPU +Packaged first-party adapters are `lemonade` and `vllm`. Linux or WSL-only ROCm GPU adapters (such as `vllm`) fail explicitly on native Windows instead of selecting a CPU fallback. @@ -35,7 +35,7 @@ unsupported. rocm-cli does not use a CPU fallback for this path. ## Pinned runtime versions The versions of the third-party runtimes rocm-cli downloads are pinned in -`runtime-deps.toml` at the repository root — one `[runtime.]` table per +`runtime-deps.toml` at the repository root: one `[runtime.]` table per runtime. That file is the only place a runtime version is written down: archive names, download URLs, and the dashboard's offline fallback are all derived from it, so a bump is a one-line edit and the tree cannot end up diff --git a/docs/llm-tool-use.md b/docs/llm-tool-use.md index d32905f81c..f473a1f606 100644 --- a/docs/llm-tool-use.md +++ b/docs/llm-tool-use.md @@ -4,11 +4,11 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# LLM Tool Use +# LLM tool use rocm-cli local assistants use structured tools, not shell commands. -## Design Rules +## Design rules - The model chooses a tool call from a schema. rocm-cli validates the arguments before anything runs. @@ -28,7 +28,7 @@ rocm-cli local assistants use structured tools, not shell commands. serving, but it should not switch its own built-in chat engine away from Lemonade. - On native Windows, vLLM live serving/install checks are skipped. The assistant - should direct those requests to WSL/Linux and should not suggest CPU fallback. + should direct those requests to WSL or Linux and should not suggest CPU fallback. This follows the same shape described by current tool-use docs: the application defines tool schemas, the model requests a tool, the application executes the @@ -36,7 +36,7 @@ tool, and the result is returned to the model for the next response. MCP tool annotations such as `readOnlyHint` and `destructiveHint` are useful UI hints, but rocm-cli still enforces approval in code. -## Local Assistant Examples +## Local assistant examples The assistant can inspect ComfyUI state: @@ -104,8 +104,10 @@ tries to open the browser: {"name":"rocm_command","arguments":{"args":["comfyui","start"]}} ``` -## Sources +## Related documentation -- OpenAI Function Calling guide: https://platform.openai.com/docs/guides/function-calling -- Anthropic Tool Use guide: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use -- Model Context Protocol tool annotations: https://modelcontextprotocol.io/specification/draft/schema#toolannotations +These upstream guides describe the tool-use patterns rocm-cli follows: + +- [OpenAI function calling guide](https://platform.openai.com/docs/guides/function-calling) +- [Anthropic tool use guide](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use) +- [Model Context Protocol tool annotations](https://modelcontextprotocol.io/specification/draft/schema#toolannotations) diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 4add0a28d9..713e6ebadd 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# Developer Manual QA +# Developer manual QA Use this checklist to verify rocm-cli behavior as a developer or release tester. On Windows, run these commands from PowerShell. On Linux or WSL, use @@ -21,7 +21,7 @@ cargo build --workspace --release ``` This writes `target/release/rocm.exe` on Windows and `target/release/rocm` on -Linux/WSL. Run the binary directly on each platform. On WSL/Linux the examine +Linux or WSL. Run the binary directly on each platform. On WSL or Linux the examine output must report `os: linux` and `wsl: true`. Do not set `ROCM_CLI_THEROCK_FAMILY` during normal setup tests. rocm-cli should @@ -53,7 +53,7 @@ packages; set `ROCM_CLI_UV_CACHE_DIR` to a folder on the prefix filesystem to restore hardlinking. Making `--prefix` do this automatically is tracked separately. -## 1. First-Time Setup +## 1. First-time setup Start rocm-cli: @@ -106,7 +106,7 @@ Expected result: - `rocm runtimes list` shows the runtime key for the installed TheRock venv. - The active runtime is ready, or the output gives one clear next command. -## 2. TheRock SDK Command-Line Install +## 2. TheRock SDK command-line install This tests the command-line install path without using the TUI: @@ -143,7 +143,7 @@ python scripts\therock_sdk_install_test.py --dry-run --family gfx120X-all Use `--family` only when a test needs a fixed package family. Do not use it for normal user setup. -## 3. Lemonade GPU Verification +## 3. Lemonade GPU verification Lemonade is the default local assistant/server engine. Serve a small assistant model with the managed runtime: @@ -162,13 +162,13 @@ Expected result: While the log stream is attached, verify detach and stop behave differently: - Press `Ctrl+D`. The stream ends and the shell prompt returns, printing a - "detached — server still running" note with the service id. Confirm the server + "detached: server still running" note with the service id. Confirm the server is still up: `rocm services` lists it and the endpoint still answers a chat request. Stop it afterward with `rocm services stop --yes`. - Re-run the serve command and press `Ctrl+C` instead. The server shuts down and `rocm services` no longer lists it as running. -## 4. Local Server Records +## 4. Local server records After a managed or foreground serve attempt, inspect local server records: @@ -191,7 +191,7 @@ rocm services stop --yes rocm services restart --yes ``` -## 5. ComfyUI Verification +## 5. ComfyUI verification ComfyUI is managed as an app surface. It should start a local web server and show the URL to open: @@ -219,7 +219,7 @@ python scripts\comfyui_therock_gpu_test.py This test may download a small checkpoint and submit a cat image workflow through the ComfyUI HTTP API. -## 6. Optional Cloud Provider Key +## 6. Optional cloud provider key Local ROCm use does not need a cloud provider key. If you want to test OpenAI or Anthropic provider setup, save the key through stdin so it does not land in @@ -244,7 +244,7 @@ To remove the saved key: rocm config clear-provider-key openai ``` -## 7. Optional Provider-Assisted Planning +## 7. Optional provider-assisted planning Most users should leave this off. To test ambiguity resolution with an already running local provider service: diff --git a/docs/release-trust.md b/docs/release-trust.md index 1294749b7a..9283393c7d 100644 --- a/docs/release-trust.md +++ b/docs/release-trust.md @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# Release Trust +# Release trust rocm-cli release packages are protected in two layers: @@ -13,7 +13,7 @@ rocm-cli release packages are protected in two layers: 2. Release packaging can emit detached RSA/SHA-256 `.sig` files, and release and nightly CI now require those signatures for published assets. -## Signing Inputs +## Signing inputs Release packaging is produced by `cargo xtask package `, a cross-platform command that builds the bundle (`.tar.gz` on Unix, `.zip` on @@ -75,7 +75,7 @@ The opt-in `@lifecycle` install-lifecycle E2E scenarios cover both path and PEM signing inputs with generated local keys. Those keys are test material only; they are not trust roots. -## Installer Verification +## Installer verification Installers always verify checksums. Signature verification runs when a public key is supplied or `ROCM_CLI_REQUIRE_SIGNATURE=1` is set. @@ -116,20 +116,21 @@ happen before activation. Run the current host's set with `E2E_INCLUDE_LIFECYCLE=1 E2E_ONLY_LIFECYCLE=1 cargo xtask e2e` (see `docs/testing.md`). -## WSL ROCDXG Package Verification +## WSL ROCDXG package verification `scripts/wsl_setup_rocdxg.sh` does not bake in a production checksum for the ROCDXG `.deb`. Operators can require verification by providing the expected -digest: +digest, where `<64_hex_sha256_digest>` is the trusted 64-character SHA-256 +digest for that package: ```bash -ROCDXG_SHA256=<64-hex-sha256> bash scripts/wsl_setup_rocdxg.sh +ROCDXG_SHA256=<64_hex_sha256_digest> bash scripts/wsl_setup_rocdxg.sh ``` When `ROCDXG_SHA256` is set, the script verifies the downloaded `.deb` before `apt install` and fails on malformed or mismatched digests. -## Runtime Metadata Verification +## Runtime metadata verification The Rust metadata cache can verify detached metadata signatures when a metadata public key is configured: @@ -149,7 +150,7 @@ metadata fetch fails and does not use unsigned data. Developer tests cover this path with generated local RSA keys and tampered payload rejection; see `docs/testing.md`. -## Model Recipe Index Verification +## Model recipe index verification rocm-cli can read an externally configured model recipe index only when it is signed with a detached signature and a local public key is provided: @@ -185,7 +186,7 @@ sha256 and size metadata, Hugging Face host scoping, Hugging Face token approval, or manual-only blocking. Existing signed indexes without `source_policy` keep the older explicit-review behavior. -## Remaining Owner Step +## Remaining owner step The repo still needs a real project-owned public signing key and matching private release secret, plus the public metadata and model recipe index keys, diff --git a/docs/rocm-docs/install/installation.md b/docs/rocm-docs/install/installation.md index 8739cfc0c6..5f1cb3dc86 100644 --- a/docs/rocm-docs/install/installation.md +++ b/docs/rocm-docs/install/installation.md @@ -15,7 +15,7 @@ ROCm CLI ships as a single prebuilt binary. Platform support: Live dashboard telemetry requires Linux or WSL2 (see [Interactive interfaces](../getting-started.md#interactive-interfaces)). vLLM -serving is Linux/WSL2 only (see `docs/vllm.md`). +serving is Linux or WSL2 only (see `docs/vllm.md`). ```{include} ../../../README.md :start-after: "## Installation" diff --git a/docs/testing.md b/docs/testing.md index 3dc8256dbf..9595fbf834 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -8,7 +8,7 @@ SPDX-License-Identifier: MIT This page collects developer verification commands. The README stays focused on quick-start usage. -## Local Verification +## Local verification Run the Rust test suite: @@ -37,7 +37,7 @@ python scripts/smoke_local.py --skip-build ## CI test selection On pull requests, CI does not test the whole workspace. The `test` job runs -`cargo nextest run` over only the crates a change can reach — the changed crates +`cargo nextest run` over only the crates a change can reach (the changed crates plus their transitive dependents, derived from the workspace dependency graph by: ```bash @@ -49,7 +49,7 @@ or nothing when no crate is affected). It falls back to `--workspace` for any change that can't be confined to specific crates (the lockfile, the toolchain file, the workspace root manifest, or CI config). On `main` and in the merge queue the full workspace always runs. For local verification, keep using -`cargo test --workspace --all-targets` above — `affected` is a CI optimization. +`cargo test --workspace --all-targets` above; `affected` is a CI optimization. The smoke path is the cross-platform local no-fallback acceptance surface. It uses an isolated config/data/cache root, does not install TheRock wheels, does @@ -84,7 +84,7 @@ cargo build --workspace --release cargo test --workspace ``` -On WSL/Linux, build and run the native Linux binary directly. The examine +On WSL or Linux, build and run the native Linux binary directly. The examine output on WSL must include `os: linux` and `wsl: true`, and must not include `os: windows`. @@ -148,7 +148,7 @@ cargo test -p rocm --bin rocm http_header_value rocm install sdk --channel release --format wheel --dry-run ``` -## TheRock SDK Install Test +## TheRock SDK install test The live SDK acceptance test creates an isolated test root under `target/`, creates a local bootstrap Python venv, runs: @@ -200,7 +200,7 @@ selection: python scripts/therock_sdk_install_test.py --root .rocm-work/tests/therock-sdk-install --fresh --family gfx120X-all ``` -## ComfyUI TheRock GPU Acceptance +## ComfyUI TheRock GPU acceptance This opt-in test verifies that rocm-cli can install or reuse its managed ComfyUI app, start it through the active TheRock ROCm runtime, reach the local @@ -276,7 +276,7 @@ python3 scripts/comfyui_therock_gpu_test.py \ --generate-cat ``` -## Runtime Selection And Activation +## Runtime selection and activation List registered managed or read-only runtimes and their exact side-by-side keys: @@ -347,7 +347,7 @@ cargo test -p rocmd event_collector cargo test -p rocmd event_dispatcher ``` -## Provider-Assisted Planning +## Provider-assisted planning The deterministic planner remains the default. Optional LLM/provider ambiguity resolution is only used after a user configures a planner provider: @@ -405,10 +405,10 @@ Engine inventory smoke on native Windows: rocm engines list ``` -The packaged Linux/WSL-only vLLM adapter should render +The packaged Linux or WSL-only vLLM adapter should render `runtime: unsupported_native_windows`, not `runtime: not found`. The vLLM live GPU acceptance script should return a clean skip on native -Windows. It remains a strict GPU-required test on Linux/WSL. +Windows. It remains a strict GPU-required test on Linux or WSL. Serve resolver focused tests: @@ -442,7 +442,7 @@ API key: pass one with `--api-key` / the `ROCM_SERVE_API_KEY` environment variable, or let one be generated. The key is handed to the engine via a 0600 key file (never argv), persisted as a 0600 per-service file (not the OS keychain, which is unavailable on headless serving hosts), and printed once as client -configuration — it must never appear in `rocm services`, `rocm logs`, or the +configuration; it must never appear in `rocm services`, `rocm logs`, or the audit log. Verifying that the running server actually *rejects* an unauthenticated request requires a live engine; that end-to-end assertion is a deferred follow-up and is **not yet** exercised by the GPU acceptance scripts @@ -454,9 +454,9 @@ recorded *host*, not to the key file: a service recorded on a public host refuse to respawn once its key is gone, rather than coming back unauthenticated. That covers `rocm services restart` and `rocmd`'s recovery supervisor, and the refusal happens before anything is stopped, so it cannot take down a running service. A -stop therefore drops the key only once it has confirmed the engine is gone — -otherwise the CLI would lock itself out of a service that is still running and -still enforcing the key — and the deferred cleanup lands on the liveness refresh +stop therefore drops the key only once it has confirmed the engine is gone +(otherwise the CLI would lock itself out of a service that is still running and +still enforcing the key), and the deferred cleanup lands on the liveness refresh that later observes the process dead. There is no e2e coverage of `services stop`/`restart` or endpoint auth; these paths are unit-tested only. @@ -551,7 +551,7 @@ rocmd sandbox-run list_servers --allow-native-fallback rocmd sandbox-run notify_user --message "ROCm check complete" --allow-native-fallback ``` -On Linux/WSL with `bubblewrap` installed, these commands should report +On Linux or WSL with `bubblewrap` installed, these commands should report `isolation: bubblewrap`; on native Windows they should report `isolation: native_restricted`. @@ -760,8 +760,8 @@ self-test before the install-lifecycle E2E scenarios. ### Packaging `cargo xtask package [output-dir] [--target ]` builds the -release distribution bundle in pure Rust — a `.tar.gz` on Unix and a `.zip` on -Windows — with a `sha256` sidecar and, when a signing key is configured, a +release distribution bundle in pure Rust (a `.tar.gz` on Unix and a `.zip` on +Windows, with a `sha256` sidecar and, when a signing key is configured, a detached `.sig`. It replaces the former `scripts/package-{linux,windows}-release` scripts and produces the same external artifact contract (bundle layout, checksum syntax, signature presence, and installer compatibility). Signing @@ -772,8 +772,8 @@ inputs come from the environment for parity with those scripts: ### Install lifecycle (opt-in `@lifecycle` E2E) -The full install lifecycle — packaging, signature-verified install, tamper -rejection, reinstall, PATH handling, and uninstall — is expressed as +The full install lifecycle (packaging, signature-verified install, tamper +rejection, reinstall, PATH handling, and uninstall) is expressed as `@lifecycle` scenarios in the [E2E cucumber suite](../tests/e2e-cucumber/README.md) (`features/install_lifecycle.feature`). They drive `cargo xtask package`, the real root installer (`install.sh` / `install.ps1`), and the installed binaries @@ -804,14 +804,14 @@ directory smoke checks (`rocm examine` must read only the isolated config/data/cache, never the real user `.rocm` state); and full-purge uninstall. Each scenario generates its own local keys, package, and install root under a per-scenario temp directory, so they are independent and use generated local -keys only — project-owned production signing keys remain an owner-controlled +keys only; project-owned production signing keys remain an owner-controlled release step. If the host does not have `libcap-dev` or `libssl-dev`, run `bash scripts/setup-wsl-portable-build-deps.sh` first: it downloads the Ubuntu development packages into `.rocm-work/tools/wsl-build-deps`, extracts only the headers, libraries, and pkg-config metadata there, and points -`PKG_CONFIG_PATH`/`PKG_CONFIG_SYSROOT_DIR` at that local copy — no sudo required. +`PKG_CONFIG_PATH`/`PKG_CONFIG_SYSROOT_DIR` at that local copy (no sudo required). Run `bash scripts/setup-wsl-portable-build-deps.sh --self-test` to verify the portable sysroot normalization path without apt, network access, or a real WSL package download. @@ -900,7 +900,7 @@ cargo test -p rocm-engine-vllm resolve_model_omits_gpu_memory_utilization_defaul python -m py_compile scripts/vllm_therock_gpu_test.py python scripts/vllm_therock_gpu_test.py --self-test -# On Linux/WSL with vLLM installed in the active rocm-cli managed TheRock venv: +# On Linux or WSL with vLLM installed in the active rocm-cli managed TheRock venv: python3 scripts/vllm_therock_gpu_test.py \ --engine /home/user/.cache/rocm-cli-target/debug/rocm-engine-vllm \ --model facebook/opt-125m @@ -914,10 +914,10 @@ TheRock SDK wheel directories. For TheRock 7.13, patch vLLM's GPTQ ROCm compatibility guard to include HIP 7.13 before building from source; otherwise `q_gemm.hip` can fail on missing `half`/`half2` `atomicAdd` overloads. -On native Windows this script prints a JSON skip result; run it from WSL/Linux +On native Windows this script prints a JSON skip result; run it from WSL or Linux for live ROCm GPU acceptance. -## Windows Tool Notes +## Windows tool notes The TheRock SDK wheel install path should not require users to install global Python or curl. rocm-cli uses Rust-native HTTP downloads and can bootstrap a @@ -930,7 +930,7 @@ SDK wheel setup should avoid global source-build tools. Reference: [TheRock Windows install tools](https://github.com/ROCm/TheRock/blob/main/docs/development/windows_support.md#install-tools) -## WSL Preflight +## WSL preflight Read-only WSL/ROCDXG preflight: @@ -952,8 +952,9 @@ python scripts/wsl_preflight.py --require-ready ``` To require checksum verification for the downloaded ROCDXG `.deb`, provide the -expected package digest from a trusted release source: +expected package digest from a trusted release source, where +`<64_hex_sha256_digest>` is the trusted 64-character SHA-256 digest: ```bash -ROCDXG_SHA256=<64-hex-sha256> bash scripts/wsl_setup_rocdxg.sh +ROCDXG_SHA256=<64_hex_sha256_digest> bash scripts/wsl_setup_rocdxg.sh ``` diff --git a/docs/ux-guidelines.md b/docs/ux-guidelines.md index 69321fcb25..5eb996225b 100644 --- a/docs/ux-guidelines.md +++ b/docs/ux-guidelines.md @@ -4,19 +4,23 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# ROCm CLI UX Guidelines +# ROCm CLI UX guidelines These guidelines are project constraints for user-facing ROCm CLI flows. ## Audience +Write for users who may not be familiar with ROCm internals. + - Assume most users are non-technical Windows users. - Treat Linux users as non-technical unless a workflow explicitly targets developer/debug usage. - Use simple English. Avoid runtime, wheel, environment, adapter, and command jargon in first-run UI unless there is no simpler accurate wording. -## First-Time Setup +## First-time setup + +First-run flows should feel guided and deterministic. - First-time setup must be a dedicated setup prompt/screen before the main TUI. - Do not require users to know or type slash commands to complete setup. @@ -35,6 +39,8 @@ These guidelines are project constraints for user-facing ROCm CLI flows. ## Persistence +Saved setup choices must survive restarts. + - First-time setup choices must persist across runs. - Store user-facing setup settings in JSON under the user's home `.rocm` directory, for example `~/.rocm/config.json`. @@ -42,6 +48,8 @@ These guidelines are project constraints for user-facing ROCm CLI flows. ## Permissions +Approval and full-access modes must be explicit and reversible. + - Default mode asks before changing local state. - Full access mode is explicit opt-in, explained in plain English, and resettable at any time with `/permissions`. @@ -50,8 +58,10 @@ These guidelines are project constraints for user-facing ROCm CLI flows. ## Main TUI +These rules apply to the primary full-screen interface after setup. + - The normal TUI should be useful after setup, not a setup command cheat sheet. -- The default feel should be a friendly control room for laymen, not a dry log +- The default feel should be a friendly control room for non-technical users, not a dry log viewer. Use plain labels, color, motion/progress, and focused review cards to make the next action obvious. - Verbosity is a hard no. First-view command output should be minimal and @@ -135,7 +145,7 @@ These guidelines are project constraints for user-facing ROCm CLI flows. or stopped history belongs behind explicit logs/details or a non-TUI `--all` style command. -## Command Navigability Baseline +## Command navigability baseline All advertised slash commands should either perform a clear immediate action (`/clear`, `/quit`, `/exit`) or open exactly one focused TUI surface. They must diff --git a/docs/vllm.md b/docs/vllm.md index 04fbd71caf..3704a66ad5 100644 --- a/docs/vllm.md +++ b/docs/vllm.md @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# vLLM Adapter +# vLLM adapter `rocm-engine-vllm` is a first-party adapter around an existing vLLM installation. It is intended for Linux and WSL ROCm GPU serving. @@ -43,7 +43,7 @@ python3 scripts/vllm_therock_gpu_test.py \ --model facebook/opt-125m ``` -The acceptance script is Linux/WSL only. It requires vLLM to be discoverable +The acceptance script is Linux or WSL only. It requires vLLM to be discoverable through a rocm-cli managed TheRock runtime manifest, launches with `gpu_required`, checks `/health` and `/v1/completions`, and verifies loaded ROCm libraries come from the managed TheRock SDK wheel directories. It rejects @@ -93,12 +93,12 @@ multiple GPUs is not supported. ### GPU memory -vLLM claims a fixed fraction of each GPU's **total** VRAM — not of the free -VRAM, and not scaled to the model — for weights plus KV cache. On a large card +vLLM claims a fixed fraction of each GPU's **total** VRAM (not of the free +VRAM, and not scaled to the model) for weights plus KV cache. On a large card a small model therefore still reserves a large slice. rocm-cli sets no `--gpu-memory-utilization` of its own, so vLLM's own default -applies unless a value comes from somewhere else — either a model's catalog +applies unless a value comes from somewhere else: either a model's catalog recipe or, taking precedence over it, the flag below: ```bash @@ -107,7 +107,7 @@ rocm serve --engine vllm --gpu-memory-utilization 0.3 --managed The value is a fraction in `(0, 1]` of total device VRAM. Lower it to leave room for a display, another workload, or a second server; raise it to give a large -model more KV cache. Applies to vLLM only — it is ignored, with a note in the +model more KV cache. Applies to vLLM only; it is ignored, with a note in the serve output, for other engines. An out-of-range or unparsable value fails the command rather than falling back silently. @@ -136,10 +136,12 @@ model-specific, so rocm-cli never guesses one: default, and applies to vLLM only. Common values: `hermes`, `llama3_json`, `mistral`. Without it, plain chat still works but tool calls return HTTP 400. -Native Windows vLLM serving is skipped in this adapter. Use WSL/Linux for vLLM +Native Windows vLLM serving is skipped in this adapter. Use WSL or Linux for vLLM ROCm serving, or choose a different engine explicitly. No CPU fallback is used. -References: +## Related documentation -- vLLM ROCm installation: https://docs.vllm.ai/en/stable/getting_started/installation/gpu/ -- AMD ROCm vLLM guidance: https://rocmdocs.amd.com/en/latest/how-to/rocm-for-ai/inference/deploy-your-model.html +For upstream vLLM and ROCm serving guidance, see: + +- [vLLM ROCm installation](https://docs.vllm.ai/en/stable/getting_started/installation/gpu/) +- [AMD ROCm vLLM guidance](https://rocmdocs.amd.com/en/latest/how-to/rocm-for-ai/inference/deploy-your-model.html) diff --git a/docs/wsl.md b/docs/wsl.md index 1b9a90a169..5e5156e98d 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -4,7 +4,7 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# WSL Support Notes +# WSL support notes This note tracks the WSL path for `rocm-cli` with TheRock-managed Python virtual environments and ROCDXG (`librocdxg`). @@ -32,7 +32,7 @@ From Windows PowerShell, target a specific distro: python scripts\wsl_preflight.py --distro Ubuntu ``` -## Install ROCDXG In WSL +## Install ROCDXG in WSL Install build/runtime prerequisites: @@ -58,11 +58,11 @@ python scripts/wsl_preflight.py --require-ready ``` To require checksum verification before installing the downloaded `.deb`, set -`ROCDXG_SHA256` to the trusted 64-character SHA-256 digest for that exact -ROCDXG package: +`ROCDXG_SHA256=<64_hex_sha256_digest>`, where `<64_hex_sha256_digest>` is the +trusted 64-character SHA-256 digest for that exact ROCDXG package: ```bash -ROCDXG_SHA256=<64-hex-sha256> bash scripts/wsl_setup_rocdxg.sh +ROCDXG_SHA256=<64_hex_sha256_digest> bash scripts/wsl_setup_rocdxg.sh ``` The wrapper intentionally does not guess or embed a production checksum. If @@ -100,7 +100,7 @@ export HSA_ENABLE_DXG_DETECTION=1 ROCK/TheRock 7.13 and newer should not require that variable, but setting it is still useful for compatibility checks while the WSL path is being hardened. -## TheRock Runtime Env In WSL +## TheRock runtime env in WSL `rocm-cli` should continue to own the Python venv. Do not rely on an externally created venv such as `D:\ROCm\venv`. @@ -124,7 +124,7 @@ For `rocm-cli`, the command itself should resolve the managed runtime manifest and apply that environment before launching HIP apps such as Lemonade's bundled `llama.cpp` backend. Users should not have to hand-export these values. -## Examine And Install UX Recommendations +## Examine and install UX recommendations `rocm examine` should detect WSL cheaply and report: @@ -157,7 +157,7 @@ and apply that environment before launching HIP apps such as Lemonade's bundled 5. Install a serving engine (Lemonade or vLLM). 6. Run a tiny GPU smoke test with CPU fallback disabled. -## Non-Destructive Tests +## Non-destructive tests Safe tests that do not mutate global WSL state: