docs: fast-follow to improve Brev web UI guide and update doc-only PR contribution instruction#3050
Merged
Conversation
Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR moves a Brev Web UI quickstart into a new deployment guide, updates the docs index to the new path, deletes the old quickstart file, adds doc-only PR verification guidance across contributor docs and a skill, updates the PR template placeholder, and configures Sphinx to suppress info logs from the redirect plugin. ChangesDocumentation Reorganization & Verification Guidance
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/deployment/brev-web-ui.md (1)
29-30: 💤 Low valueRephrase to avoid repetition.
The phrase "want to" appears in consecutive sentences.
Consider replacing the second instance to add variety.Example revision:
Use this guide when you want to try NemoClaw without installing the CLI or using a local GPU. -If you want to manage the remote host from a terminal, see [Deploy to a Remote GPU Instance](deploy-to-remote-gpu.md). +To manage the remote host from a terminal, see [Deploy to a Remote GPU Instance](deploy-to-remote-gpu.md).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/deployment/brev-web-ui.md` around lines 29 - 30, The two sentences repeat the phrase "want to"; update the second sentence that begins "If you want to manage the remote host from a terminal..." to avoid repetition — e.g., reword it to "To manage the remote host from a terminal, see [Deploy to a Remote GPU Instance](deploy-to-remote-gpu.md)." — keep the first sentence ("Use this guide when you want to try NemoClaw without installing the CLI or using a local GPU.") unchanged and ensure the replacement removes the duplicate "want to".
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/deployment/brev-web-ui.md`:
- Around line 116-121: Replace the four-colon MyST admonition delimiter
`::::{note}`/`::::` with the correct three-colon form `:::{note}`/`:::` and
split the line that currently contains two sentences ("Wait for about a few
minutes for pairing to finish automatically. Refresh the dashboard to see if the
warning is resolved and the connection is established.") into two separate lines
so each sentence is on its own line; also change "about a few minutes" to "a few
minutes" for clarity.
---
Nitpick comments:
In `@docs/deployment/brev-web-ui.md`:
- Around line 29-30: The two sentences repeat the phrase "want to"; update the
second sentence that begins "If you want to manage the remote host from a
terminal..." to avoid repetition — e.g., reword it to "To manage the remote host
from a terminal, see [Deploy to a Remote GPU
Instance](deploy-to-remote-gpu.md)." — keep the first sentence ("Use this guide
when you want to try NemoClaw without installing the CLI or using a local GPU.")
unchanged and ensure the replacement removes the duplicate "want to".
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: df944f5a-7169-4764-bb33-e408adb41bfe
📒 Files selected for processing (4)
docs/conf.pydocs/deployment/brev-web-ui.mddocs/get-started/brev-web-ui-quickstart.mddocs/index.md
💤 Files with no reviewable changes (1)
- docs/get-started/brev-web-ui-quickstart.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/CONTRIBUTING.md`:
- Around line 114-117: Update the CLI example block in CONTRIBUTING.md to use
the console code fence and add shell prompt prefixes: replace the existing
```bash block with ```console and prefix each command line with "$ " (e.g., "$
npx prek run --all-files" and "$ make docs") so the example follows the required
`console` language tag and prompt convention.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: faa3f8c9-0acc-4cb9-a0e7-12d4826e8908
📒 Files selected for processing (4)
.agents/skills/nemoclaw-contributor-create-pr/SKILL.md.github/PULL_REQUEST_TEMPLATE.mdCONTRIBUTING.mddocs/CONTRIBUTING.md
✅ Files skipped from review due to trivial changes (2)
- .github/PULL_REQUEST_TEMPLATE.md
- CONTRIBUTING.md
Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/deployment/brev-web-ui.md (1)
43-45: ⚡ Quick winAdd a one-sentence intro before section lists.
Both
## Prerequisitesand## Launch NemoClaw from Brevstart directly with list items. Add one introductory sentence under each heading before the list.As per coding guidelines, "Sections use H2 and H3, each starting with an introductory sentence."
Also applies to: 63-66
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/deployment/brev-web-ui.md` around lines 43 - 45, The headings "## Prerequisites" and "## Launch NemoClaw from Brev" (and the section around lines 63-66) begin immediately with lists; add a single introductory sentence under each H2 that briefly describes the purpose of the section before the list items so the section follows the guideline "Sections use H2 and H3, each starting with an introductory sentence." Locate the headings "## Prerequisites" and "## Launch NemoClaw from Brev" and insert one clear, concise sentence under each (e.g., what the reader will need or what the section will show) before the existing bullet lists.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/deployment/brev-web-ui.md`:
- Around line 43-45: The headings "## Prerequisites" and "## Launch NemoClaw
from Brev" (and the section around lines 63-66) begin immediately with lists;
add a single introductory sentence under each H2 that briefly describes the
purpose of the section before the list items so the section follows the
guideline "Sections use H2 and H3, each starting with an introductory sentence."
Locate the headings "## Prerequisites" and "## Launch NemoClaw from Brev" and
insert one clear, concise sentence under each (e.g., what the reader will need
or what the section will show) before the existing bullet lists.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 50b5f64b-6f02-4902-8256-d40657af0a18
📒 Files selected for processing (1)
docs/deployment/brev-web-ui.md
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/deployment/brev-web-ui.md (1)
52-52: ⚡ Quick winSplit Line 52 into one sentence per line.
Line 52 currently contains two sentences on a single source line; split them into separate lines to match docs formatting rules.
As per coding guidelines, “One sentence per line in source (makes diffs readable).”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/deployment/brev-web-ui.md` at line 52, Split the source line that currently reads "If you already have an NVIDIA API key skip this section. Otherwise, follow these steps to generate a new key:" into two separate lines so each sentence is on its own source line; locate the exact string "If you already have an NVIDIA API key skip this section. Otherwise, follow these steps to generate a new key:" and replace it with two lines: one containing "If you already have an NVIDIA API key skip this section." and the next containing "Otherwise, follow these steps to generate a new key:" ensuring trailing punctuation and whitespace are preserved.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/deployment/brev-web-ui.md`:
- Line 52: Split the source line that currently reads "If you already have an
NVIDIA API key skip this section. Otherwise, follow these steps to generate a
new key:" into two separate lines so each sentence is on its own source line;
locate the exact string "If you already have an NVIDIA API key skip this
section. Otherwise, follow these steps to generate a new key:" and replace it
with two lines: one containing "If you already have an NVIDIA API key skip this
section." and the next containing "Otherwise, follow these steps to generate a
new key:" ensuring trailing punctuation and whitespace are preserved.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 73b89393-88ea-4d97-9b7d-f6ea1f9acab1
📒 Files selected for processing (1)
docs/deployment/brev-web-ui.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/deployment/brev-web-ui.md`:
- Around line 18-21: The SPDX header is currently inside a single multi-line
HTML comment; replace it with two separate single-line HTML comments so each
SPDX tag is on its own line: one comment containing "SPDX-FileCopyrightText:
..." and a second comment containing "SPDX-License-Identifier: ..."; update the
block containing SPDX-FileCopyrightText and SPDX-License-Identifier so they
appear as <!-- SPDX-FileCopyrightText: ... --> and <!-- SPDX-License-Identifier:
... --> respectively at the top of the document.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 7bcdff9a-edb7-4a0e-8287-c2ca8ccaf793
📒 Files selected for processing (1)
docs/deployment/brev-web-ui.md
ericksoa
requested changes
May 5, 2026
ericksoa
left a comment
Contributor
There was a problem hiding this comment.
Could we preserve the old published URL for this moved page before merging?
The PR moves docs/get-started/brev-web-ui-quickstart.md to docs/deployment/brev-web-ui.md, but I do not see a corresponding entry in the redirects map in docs/conf.py. Should this move add a redirect such as:
"get-started/brev-web-ui-quickstart": "../deployment/brev-web-ui.html",so existing links to /get-started/brev-web-ui-quickstart.html keep working after the page moves?
I checked the built output locally after make docs-strict: the new page is emitted at deployment/brev-web-ui.html, but get-started/brev-web-ui-quickstart.html is not generated.
Collaborator
Author
|
@ericksoa This is a fast follow after the initial page just merged (NVIDIA/NemoClaw#2563)) a little before this PR. The new page hasn't been published, so no need for a redirect. |
cv
approved these changes
May 5, 2026
ericksoa
approved these changes
May 5, 2026
ericksoa
left a comment
Contributor
There was a problem hiding this comment.
Approved after re-review. The earlier redirect concern is resolved by the fast-follow timing: the moved page has not been published yet, and the new deployment path is linked from the docs index. I also verified the doc build locally and reviewed the current PR checks.
This was referenced May 8, 2026
cv
added a commit
that referenced
this pull request
May 27, 2026
> **Note:** This PR supersedes #3063, which had unsigned commits in its history (a stale local git config in one of my clones — `user.email=test@example.com`, `commit.gpgsign=false` — produced 8 unverified commits I couldn't retroactively sign because the branch ruleset blocks force-push). Net diff vs `main` is unchanged. All commits on this branch are signed and authored by `prekshiv@nvidia.com`. The 8 post-review commits from #3063 are collapsed into a single signed commit; per-commit history for those is preserved in #3063 for reference. --- ## Summary Adds maintainer skill `nemoclaw-maintainer-verify-stale` — automates the manual loop of: spin up a Brev box → install latest NemoClaw → try to reproduce an old bug → comment with findings. Tag-only (never auto-closes); a maintainer pulls the trigger after reviewing. The skill has been driven end-to-end against **9 real candidates** during development, surfacing the gaps and skill changes summarised below. ## Issues tackled | Issue | Reported | Verified | Verdict | Score | What this run surfaced (skill change) | |---|---|---|---|---|---| | [#2791](#2791) | v0.0.21 | v0.0.35 | `wontfix-by-design` | — | By-design prototype. Step 8.5 detection framework (3 signals: maintainer attribution / removal commit / symbol absent). Maintainer reviewed the analysis and **closed the issue manually**. | | [#2168](#2168) | v0.0.21 | v0.0.35 | `wontfix-by-design` (tagged) | — | Repo-label vocabulary mismatch (`status: wont-fix`, not `wontfix`); markdown-linked citations in comments. | | [#2007](#2007) | v0.0.18 | v0.0.35 | `fixed-on-latest` (tagged) | 84/100 | Docker-group `sg`, `brev exec` PATH gotcha, sandbox-build-rot reframe, multi-axis architectural-drift check. | | [#2592](#2592) | v0.0.28 | v0.0.35 | `fixed-on-latest` (tagged) | 84/100 | Sentinel-file SSH-drop guard, `openshell sandbox exec -n NAME --` syntax footgun, reproducer-extraction regex extension (`openclaw\|openshell`). | | [#2519](#2519) | v0.0.26 | v0.0.35 | `fixed-on-latest` (closed by maintainer mid-run) | 84/100 | Step 5 provider classification + API-key prompt, install.sh env-var passthrough, sandbox-name validator. | | [#2604](#2604) | v0.0.28 | v0.0.36 | `fixed-on-latest` (tagged) | 84/100 | **File-based API key propagation** (kill argv exposure local→Brev). 300-word hard ceiling for comments + comment-authoring principle in Step 10. | | [#2611](#2611) | v0.0.28 | v0.0.36 | `fixed-on-latest` (tagged) | 70/100 | **On-box subshell argv leak** (extend file-based pattern to Brev→inner shell). First non-cap-at-84 score (the −30 LLM-synth penalty pushed raw below the cap). | | [#2513](#2513) | v0.0.26 | — | maintainer self-verified mid-batch | — | Gap-queue: skill should re-check `state == OPEN` before posting. Second mid-batch close-by-maintainer (alongside #2519) → promote from queue to a real Step 1/3 check. | | [#2166](#2166) | v0.0.21 | — | still-reproduces (source-only) | — | Gap-queue: when pre-flight is conclusive, allow source-only verdicts to skip Brev entirely (`Verification mode: static analysis at <tag>`). | **Effective touched count: 7 issues with skill-rendered comments + 2 side-discoveries.** Two of the seven landed `wontfix-by-design`, five landed `fixed-on-latest`. Sandbox-build rot capped four of the five at 84 (the modal verdict shape with reporter @-mention). #2611 was the first run to land below the cap, validating the −30 LLM-synth penalty path. ## v1 scope | | | |---|---| | **In** | Linux only (Brev), `bug` issues against CLI / Sandbox / OpenShell / Docker / Getting Started / Ubuntu / DGX Spark / GB10 | | **Out** | macOS, Windows/WSL, integration bugs needing third-party tokens, service-account bots, auto-close | ## Verification flow (one-line per step) | Step | Purpose | |---|---| | 6.5 — Preconditions | Brev auth + install-URL reachability fail-fast (no Brev cost on dead deps) | | 6.7 — Local-first | Pure-CLI bugs (no sandbox/Docker/GPU) run on the maintainer's local install — same evidence, zero cost | | 7 — Reuse-or-provision | `brev ls` → reuse a `verify-stale-*` box if running, else `brev create` with a runtime-picked CPU SKU | | 8 — Validate-on-baseline, verify-on-latest | Install reported version first, confirm the reproducer actually exposes the bug, reset, then install latest | | 8.5 — By-design detection | Three signals (maintainer attribution / removal commit / symbol absent) short-circuit Brev cost on intentional removals | | 9 — Confidence scoring | +50 / +25 / +25 / −30 / −50, clamped to [0,100]. ≥85 silent · 60–84 + reporter @-mention · <60 inconclusive | | 10 — Comment + label | Comprehensive redaction (JWT / NVAPI / PAT / base64 / internal hostnames / emails) with HTML→text pre-pass for QA bodies. 300-word hard ceiling for fixed/wontfix; 30–80 for still-reproduces. | | 11 — Infra failure | Sandbox-build rot is the dominant failure mode for any version >5–7 patches behind; cap-at-84 with reporter @-mention is by design | | 12 — Activity log | Append per-issue + per-session entries to `~/development/daily-rhythm/activity/nemoclaw-verify-stale-log.md` | ## Idempotency Every posted comment carries `<!-- nemoclaw-verify-stale v1 YYYY-MM-DD -->`. Candidate filter excludes any issue whose comments match `<!-- nemoclaw-verify-stale v\d+ YYYY-MM-DD -->` within the last 7 days OR carries `fixed-on-latest` / `verify-inconclusive` / `status: wont-fix`. Release sweep clears the first two on each tag cut. ## Active-discussion handling (two-tier) | Maintainer's unanswered comment age | Skill behaviour | |---|---| | ≤ 7 days | Skip — running on top of fresh discussion would conflict with the maintainer's framing | | > 7 days | Proceed with the **unanswered-question variant**: lead with a markdown link to the unanswered comment, dual @-mention of both maintainer and reporter | ## Companion changes - **`nemoclaw-skills-guide/SKILL.md`** — adds the new skill to the maintainer skills table. - **`nemoclaw-maintainer-cut-release-tag/SKILL.md`** — release-time sweep of `fixed-on-latest` and `verify-inconclusive` from every open issue. Without it, "latest" drifts and verifications go silently stale. Verification records stay in comments; only labels reset. ## CI status | Check | Status | |---|---| | commit-lint, dco-check, installer-hash-check, legacy-path-guard, pr/changes | ✅ | | markdown-links | ✅ after [`3abffd72`](3abffd72) (placeholder `[label](url)` examples in SKILL.md were being parsed as real broken links — restructured as fenced-block templates) and [`dc5d7143`](dc5d7143) (merge of main brought in the deletion of `docs/get-started/brev-web-ui-quickstart.md` per #3050, resolving the merge-side missing-file failure) | ## Test plan - [x] Step 3 candidate filter dry-run against the open-issue list (24 candidates after filtering 105 raw) - [x] By-design detection on #2791 — landed `wontfix-by-design`, maintainer agreed and closed - [x] By-design detection on #2168 — landed `wontfix-by-design`, tagged + open awaiting close - [x] End-to-end Brev runs ×5 (#2007, #2592, #2519, #2604, #2611) — provision → baseline → reset → latest → repro → comment + label - [x] Sandbox-build rot path — 5 of 5 e2e runs hit it; cap-at-84 verdict shape works as designed - [x] HTML body redaction — exercised on every NV-QA-filed issue (all five e2e candidates were NV QA bodies) - [x] Marker idempotency — no double-posts across the seven runs - [x] Hardware-substitution caveat — exercised live on #2611 (`Platform: DGX Spark` label, x86_64 actual) - [ ] Active-discussion two-tier rule — variant code is in skill (`f0ec6b8e`) but **untested against a live candidate** (no qualifying issue in the candidate set yet) - [ ] Local-first short-circuit (Step 6.7) — designed but not yet exercised against a pure-CLI candidate - [ ] Release-tag sweep — companion change in `cut-release-tag` tested at design level only Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * New maintainer skill to verify whether stale bug reports reproduce on the latest release, with interactive reproducer validation and evidence-backed comments/labels. * **Enhancements** * Release-tag workflow now conditionally clears verification labels from open issues when verification is stale or regression risk is detected (preserves labels in specified safe cases). * **Documentation** * Added comprehensive reference guides covering candidate selection, environment/reproducer setup, provisioning, reproduction rubrics, scoring, comments, and logging. <!-- review_stack_entry_start --> [](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/3327?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack) <!-- review_stack_entry_end --> <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com> Signed-off-by: Carlos Villela <cvillela@nvidia.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Test User <test@example.com> Co-authored-by: Carlos Villela <cvillela@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improves the Brev Web UI guide so it matches the current UI flow for deploying the instance, opening the setup page, configuring providers, and handling gateway pairing. Also clarifies that doc-only PRs should use docs and hook verification instead of requiring the full test suite by default.
Related Issue
None.
Changes
docs/deployment/and updates the docs toctree entry.sphinx-reredirectsinfo logs during incremental docs builds while keeping redirect warnings visible.Type of Change
Verification
npx prek run --all-filespassesnpm testpassesmake docsbuilds without warnings (doc changes only)Signed-off-by: Miyoung Choi miyoungc@nvidia.com
Summary by CodeRabbit