docs: expand generated agent variants#4728
Merged
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughThis PR consolidates documentation across the NemoClaw guides to use a unified ChangesUnified CLI documentation and variant generation pipeline
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Contributor
PR Review AdvisorFindings: 0 needs attention, 3 worth checking, 0 nice ideas Review findings🛠️ Needs attention
🔎 Worth checking
🌱 Nice ideas
Since last review detailsCurrent findings:
This is an automated advisory review. A human maintainer must make the final merge decision. |
Contributor
|
🌿 Preview your docs: https://nvidia-preview-pr-4728.docs.buildwithfern.com/nemoclaw |
Contributor
E2E Advisor RecommendationRequired E2E: None Dispatch hint: Full advisor summaryE2E Recommendation AdvisorBase: Required E2E
Optional E2E
New E2E recommendations
Dispatch hint
|
Contributor
E2E Scenario Advisor RecommendationRequired scenario E2E: None Full scenario advisor summaryE2E Scenario AdvisorBase: Required scenario E2E
Optional scenario E2E
Relevant changed files
|
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/reference/commands.mdx (1)
80-1953:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftCLI parity is currently broken by the command heading format.
The docs parity job reports that phase 2 extracted 0 headings from this file while CLI help exposes 58 commands. Please restore heading text to the format the parity extractor recognizes (or update the extractor in the same PR) so command docs are discoverable again.
🤖 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/reference/commands.mdx` around lines 80 - 1953, The command headings in the long commands.mdx block no longer match the parity extractor's expected heading pattern (hence 0 headings found); restore each command heading to the extractor's canonical format (for example lines like "### `$$nemoclaw help`", "### `$$nemoclaw --version`", "### `$$nemoclaw resources`", "### `$$nemoclaw onboard`", etc.), remove or relocate any surrounding markup that breaks heading parsing (inline AgentOnly/Warning blocks or extra blank lines before the ###), and ensure every public command appears as a top-level "### `$$nemoclaw <...>`" heading so the parity job can detect the 58 commands; alternatively, if you intentionally changed the heading syntax, update the parity extractor to accept the new pattern and include tests for headings such as `$$nemoclaw connect`, `$$nemoclaw list`, `$$nemoclaw inference set`, and `$$nemoclaw onboard` to validate detection.
🧹 Nitpick comments (3)
docs/reference/commands.mdx (1)
1513-1513: ⚡ Quick winSplit Line 1513 into one sentence per source line.
This line contains multiple sentences on one line, which violates the docs source-format rule.
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/reference/commands.mdx` at line 1513, The long documentation sentence that begins "When `--sandbox` is supplied explicitly..." should be split so each sentence lives on its own source line to satisfy the "one sentence per line" rule; break the text into separate lines for (1) the behavior when --sandbox (and the env var precedence and flag winning), (2) the requirement that the name match a registered sandbox and appear in the live gateway if `openshell sandbox list` succeeds, (3) the error behavior for unknown/stale names (including reporting the source env var and exiting non-zero and not writing a tarball), and (4) the fallback behavior for no explicit name for `$$nemoclaw debug` (including the warning if the registry default is stale). Ensure each resulting sentence is on its own line and preserves the original wording and referenced symbols (`--sandbox`, `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, `SANDBOX_NAME`, `openshell sandbox list`, `$$nemoclaw debug`).docs/reference/troubleshooting.mdx (2)
933-933: ⚡ Quick winLine 933 should be split into separate sentence lines.
This line contains multiple sentences in one source line.
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/reference/troubleshooting.mdx` at line 933, The single source line that begins "Bot tokens for Telegram (`getUpdates`), Discord (gateway), and Slack (Socket Mode) only allow one active consumer per token..." contains multiple sentences and should be split so each sentence is on its own source line; edit the paragraph (the line starting with "Bot tokens for Telegram (`getUpdates`), Discord (gateway), and Slack (Socket Mode) ...") and break it into separate lines such as one line for the sentence about one active consumer per token, one line for the consequence when two sandboxes use the same token, and one line for the note about `$$nemoclaw status` still reporting the bridge as running.
27-29: ⚡ Quick winUse active voice in this troubleshooting instruction.
Line 28 uses passive voice (“is installed”). Rewrite this sentence in active voice.
As per coding guidelines: “Active voice required. Flag passive constructions.”
🤖 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/reference/troubleshooting.mdx` around lines 27 - 29, Update the passive sentence about the `$$nemoclaw` binary to active voice: replace "The `$$nemoclaw` binary is installed but the shell session does not know where to find it." with an active construction that names the actor (installer or you) and the action, e.g., state that the installer placed the `$$nemoclaw` binary (or "you installed the `$$nemoclaw` binary") and that your current shell session can't find it in PATH; modify the sentence in docs/reference/troubleshooting.mdx where `$$nemoclaw` is mentioned accordingly.
🤖 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/about/release-notes.mdx`:
- Line 35: The release note mixes the variant placeholder and a hardcoded
command which breaks Hermes variants: replace the hardcoded "nemoclaw <name>
skill remove <skill>" string with the variant placeholder "$$nemoclaw <name>
skill remove <skill>" so it matches the other occurrences of "$$nemoclaw" in the
same bullet; search for the exact text "nemoclaw <name> skill remove <skill>"
and update it to use the "$$nemoclaw" prefix, and verify any other commands in
that line also use the "$$nemoclaw" variant placeholder consistently (e.g.,
"$$nemoclaw inference set", "$$nemoclaw <name> status --json", "$$nemoclaw debug
--sandbox").
---
Outside diff comments:
In `@docs/reference/commands.mdx`:
- Around line 80-1953: The command headings in the long commands.mdx block no
longer match the parity extractor's expected heading pattern (hence 0 headings
found); restore each command heading to the extractor's canonical format (for
example lines like "### `$$nemoclaw help`", "### `$$nemoclaw --version`", "###
`$$nemoclaw resources`", "### `$$nemoclaw onboard`", etc.), remove or relocate
any surrounding markup that breaks heading parsing (inline AgentOnly/Warning
blocks or extra blank lines before the ###), and ensure every public command
appears as a top-level "### `$$nemoclaw <...>`" heading so the parity job can
detect the 58 commands; alternatively, if you intentionally changed the heading
syntax, update the parity extractor to accept the new pattern and include tests
for headings such as `$$nemoclaw connect`, `$$nemoclaw list`, `$$nemoclaw
inference set`, and `$$nemoclaw onboard` to validate detection.
---
Nitpick comments:
In `@docs/reference/commands.mdx`:
- Line 1513: The long documentation sentence that begins "When `--sandbox` is
supplied explicitly..." should be split so each sentence lives on its own source
line to satisfy the "one sentence per line" rule; break the text into separate
lines for (1) the behavior when --sandbox (and the env var precedence and flag
winning), (2) the requirement that the name match a registered sandbox and
appear in the live gateway if `openshell sandbox list` succeeds, (3) the error
behavior for unknown/stale names (including reporting the source env var and
exiting non-zero and not writing a tarball), and (4) the fallback behavior for
no explicit name for `$$nemoclaw debug` (including the warning if the registry
default is stale). Ensure each resulting sentence is on its own line and
preserves the original wording and referenced symbols (`--sandbox`,
`NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, `SANDBOX_NAME`, `openshell sandbox
list`, `$$nemoclaw debug`).
In `@docs/reference/troubleshooting.mdx`:
- Line 933: The single source line that begins "Bot tokens for Telegram
(`getUpdates`), Discord (gateway), and Slack (Socket Mode) only allow one active
consumer per token..." contains multiple sentences and should be split so each
sentence is on its own source line; edit the paragraph (the line starting with
"Bot tokens for Telegram (`getUpdates`), Discord (gateway), and Slack (Socket
Mode) ...") and break it into separate lines such as one line for the sentence
about one active consumer per token, one line for the consequence when two
sandboxes use the same token, and one line for the note about `$$nemoclaw
status` still reporting the bridge as running.
- Around line 27-29: Update the passive sentence about the `$$nemoclaw` binary
to active voice: replace "The `$$nemoclaw` binary is installed but the shell
session does not know where to find it." with an active construction that names
the actor (installer or you) and the action, e.g., state that the installer
placed the `$$nemoclaw` binary (or "you installed the `$$nemoclaw` binary") and
that your current shell session can't find it in PATH; modify the sentence in
docs/reference/troubleshooting.mdx where `$$nemoclaw` is mentioned accordingly.
🪄 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: 2984586e-3a57-4131-b7f7-caa2b20e2f64
📒 Files selected for processing (28)
docs/CONTRIBUTING.mddocs/about/overview.mdxdocs/about/release-notes.mdxdocs/deployment/deploy-to-remote-gpu.mdxdocs/get-started/prerequisites.mdxdocs/get-started/windows-preparation.mdxdocs/index.ymldocs/inference/inference-options.mdxdocs/inference/switch-inference-providers.mdxdocs/inference/use-local-inference.mdxdocs/manage-sandboxes/backup-restore.mdxdocs/manage-sandboxes/lifecycle.mdxdocs/manage-sandboxes/messaging-channels.mdxdocs/manage-sandboxes/runtime-controls.mdxdocs/manage-sandboxes/workspace-files.mdxdocs/monitoring/monitor-sandbox-activity.mdxdocs/network-policy/customize-network-policy.mdxdocs/network-policy/integration-policy-examples.mdxdocs/reference/architecture.mdxdocs/reference/cli-selection-guide.mdxdocs/reference/commands-nemohermes.mdxdocs/reference/commands.mdxdocs/reference/network-policies.mdxdocs/reference/troubleshooting.mdxdocs/security/best-practices.mdxdocs/security/credential-storage.mdxscripts/sync-agent-variant-docs.tstest/agent-variant-docs.test.ts
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
scripts/sync-agent-variant-docs.ts (1)
286-304:⚠️ Potential issue | 🟠 Major | ⚡ Quick winKeep rewriting non-route markdown file links.
This change preserves route-style doc links, but it also stops rebasing ordinary markdown links entirely. Shared pages that link to local assets or explicit sibling files with
[text](./file.ext)will now keep the source-relative target after generation, so those links break fromdocs/_build/agent-variants/....Preserve route-style links, but continue rewriting filesystem-backed markdown links alongside images and imports.
🤖 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 `@scripts/sync-agent-variant-docs.ts` around lines 286 - 304, The current rewrite only rebases image links (rewriteRelativeImageLinks) but leaves ordinary markdown links untouched, causing filesystem-backed links like [text](./file.md) to remain source-relative; update the logic so filesystem-backed markdown links are rewritten too while still preserving route-style links detected by shouldKeepLinkTarget. Concretely, either expand rewriteRelativeImageLinks to also match non-image link patterns (change the regex and keep the same shouldKeepLinkTarget check and rewriteRelativeLinkTarget call) or add a new rewriteRelativeMarkdownLinks(body, sourceDirectory, outputDirectory) invoked alongside rewriteRelativeImageLinks and rewriteRelativeImports in rewriteRelativePaths; in both cases ensure you reference and reuse shouldKeepLinkTarget and rewriteRelativeLinkTarget so route-style links stay unchanged and local ./ or sibling markdown/file links are rebased to outputDirectory.
🤖 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.
Outside diff comments:
In `@scripts/sync-agent-variant-docs.ts`:
- Around line 286-304: The current rewrite only rebases image links
(rewriteRelativeImageLinks) but leaves ordinary markdown links untouched,
causing filesystem-backed links like [text](./file.md) to remain
source-relative; update the logic so filesystem-backed markdown links are
rewritten too while still preserving route-style links detected by
shouldKeepLinkTarget. Concretely, either expand rewriteRelativeImageLinks to
also match non-image link patterns (change the regex and keep the same
shouldKeepLinkTarget check and rewriteRelativeLinkTarget call) or add a new
rewriteRelativeMarkdownLinks(body, sourceDirectory, outputDirectory) invoked
alongside rewriteRelativeImageLinks and rewriteRelativeImports in
rewriteRelativePaths; in both cases ensure you reference and reuse
shouldKeepLinkTarget and rewriteRelativeLinkTarget so route-style links stay
unchanged and local ./ or sibling markdown/file links are rebased to
outputDirectory.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 99a37981-a57a-4e7d-8944-9692605813a1
📒 Files selected for processing (10)
docs/CONTRIBUTING.mddocs/about/release-notes.mdxdocs/get-started/prerequisites.mdxdocs/get-started/windows-preparation.mdxdocs/reference/commands.mdxdocs/reference/troubleshooting.mdxdocs/security/best-practices.mdxscripts/sync-agent-variant-docs.tstest/agent-variant-docs.test.tstest/e2e/e2e-cloud-experimental/check-docs.sh
✅ Files skipped from review due to trivial changes (4)
- docs/get-started/windows-preparation.mdx
- docs/get-started/prerequisites.mdx
- docs/about/release-notes.mdx
- docs/reference/troubleshooting.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/reference/commands.mdx
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
ci/platform-matrix.json (1)
1-4:⚠️ Potential issue | 🟠 Major | ⚡ Quick winEnforce SPDX header for
ci/platform-matrix.jsonwithout breaking strict JSON parsing
ci/platform-matrix.jsonhas no// SPDX-FileCopyrightText: .../// SPDX-License-Identifier: Apache-2.0header at the start of the file (lines 1-4 currently begin with{).- The docs generator loads this file as strict JSON:
scripts/generate-platform-docs.py→load_matrix()usesjson.load(f). Adding literal// ...comment header lines would make the file invalid JSON unless the loader is updated (e.g., strip leading comment lines or use a JSONC/comment-capable parser).🤖 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 `@ci/platform-matrix.json` around lines 1 - 4, ci/platform-matrix.json must remain valid JSON, so do not add // SPDX comment lines; instead add SPDX metadata as JSON fields (e.g., a top-level "spdx": { "fileCopyrightText": "...", "license": "Apache-2.0" }) to the existing object so json.load(f) still succeeds. Update the docs loader reference in scripts/generate-platform-docs.py → load_matrix() only if you later decide to accept comment headers; for now modify ci/platform-matrix.json to include the SPDX info as JSON properties and ensure any code that reads matrix keys (in generate-platform-docs.py) uses the new "spdx" object if present.
🤖 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.
Outside diff comments:
In `@ci/platform-matrix.json`:
- Around line 1-4: ci/platform-matrix.json must remain valid JSON, so do not add
// SPDX comment lines; instead add SPDX metadata as JSON fields (e.g., a
top-level "spdx": { "fileCopyrightText": "...", "license": "Apache-2.0" }) to
the existing object so json.load(f) still succeeds. Update the docs loader
reference in scripts/generate-platform-docs.py → load_matrix() only if you later
decide to accept comment headers; for now modify ci/platform-matrix.json to
include the SPDX info as JSON properties and ensure any code that reads matrix
keys (in generate-platform-docs.py) uses the new "spdx" object if present.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 7fe3fe22-e67a-4770-8756-8870d7cf2627
📒 Files selected for processing (2)
ci/platform-matrix.jsonscripts/sync-agent-variant-docs.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- scripts/sync-agent-variant-docs.ts
cv
approved these changes
Jun 3, 2026
12 tasks
This was referenced Jun 4, 2026
cv
pushed a commit
that referenced
this pull request
Jun 5, 2026
## Summary
- Add the v0.0.59 release notes from the GitHub announcement discussion.
- Refresh local inference and credential-storage guidance for the
current release behavior.
- Regenerate the user skills from the updated Fern docs.
- Tighten release-prep and docs review guidance for generated skills, PR
labels, and shared `$$nemoclaw` command placeholders.
## Verification
- `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix
nemoclaw-user --doc-platform fern-mdx`
- `rg "permissive mode|shields down|shields up|shields status|config
rotate-token|rotate-token" --glob '*.{md,mdx}'`
- `git diff --check`
- `npm run docs` (rerun outside sandbox after sandbox-only `tsx` IPC
permission failure)
- `npm run typecheck:cli`
- Pre-commit hooks during commit passed, including markdownlint,
docs-to-skills verification, gitleaks, commitlint, and skills YAML
tests.
## Source Summary
- #3679, #4437, #4681, #4766, #4772, #4775, #4786 ->
`docs/about/release-notes.mdx`, `docs/reference/commands.mdx`,
`docs/reference/troubleshooting.mdx`: Summarize OpenClaw 2026.5.27
compatibility, runtime path pinning, plugin registry recovery, live
gateway reconciliation, and clearer host-alias/startup diagnostics.
- #4332, #4402, #4769, #4776, #4779 -> `docs/about/release-notes.mdx`,
`docs/inference/inference-options.mdx`,
`docs/inference/use-local-inference.mdx`,
`docs/inference/switch-inference-providers.mdx`: Document the release
inference changes covering Local NIM waits, Hermes Anthropic routing,
Nemotron 3 Ultra, the current Ollama starter fallback, and Spark
managed-vLLM context length.
- #4628, #4652, #4733, #4745 -> `docs/about/release-notes.mdx`,
`docs/security/credential-storage.mdx`,
`docs/manage-sandboxes/messaging-channels.mdx`,
`docs/reference/troubleshooting.mdx`: Capture permission healing,
gateway-stored credential reuse, cross-sandbox messaging credential
conflict checks, and CDI preflight diagnostics.
- #4728, #4737, #4743, #4744, #4782 -> `.agents/skills/nemoclaw-user-*`:
Regenerate the user skill references from the updated source docs.
- Follow-up maintenance ->
`.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`,
`.coderabbit.yaml`: Add release-prep area labels for docs and skills
PRs, and teach docs review guidance that `$$nemoclaw` is the correct
shared command placeholder for examples that work across agent aliases.
Note: the `documentation` label was not present in the repository, so
this PR is labeled with `v0.0.59` only.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated default model for local Ollama inference setup to qwen3.5:9b
* Added Nemotron 3 Ultra 550B as an NVIDIA Endpoints model option
* Clarified credential storage and reuse behavior for post-deployment
(day-two) operations
* Added v0.0.59 release notes covering OpenClaw compatibility, inference
options, Hermes messaging sync, and troubleshooting
* Clarified CLI selection guidance and updated OpenClaw version example
in status output
* Revised release-prep instructions and docs review guidance for CLI
alias usage
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
12 tasks
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
3 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
Expands the
$$nemoclawbuild-time placeholder across shared OpenClaw/Hermes docs and derives generated variant pages fromdocs/index.yml. This keeps single-variant pages as source pages while routing shared pages through hidden_build/agent-variantsoutput for Fern rendering.Changes
$$nemoclawplaceholders across the user guide.scripts/sync-agent-variant-docs.tsto generate variants for pages shared by both guide navs and fail if placeholders appear on single-variant pages.docs/index.ymlentries at generated_build/agent-variantspages while leaving OpenClaw-only and Hermes-only pages as source paths.Type of Change
Verification
git commit --no-verifyandgit push --no-verifywere used at the user's request.npx prek run --all-filespassesnpm testpassesnpm run docsbuilds without warnings (doc changes only)Verified locally:
npm test -- test/agent-variant-docs.test.tsnpm run docs(passes with the existing Fern warning)python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx --dry-runbash test/e2e/e2e-cloud-experimental/check-docs.sh --only-links --local-only ...on changed source pages_buildpage link checksgit diff --checkSigned-off-by: Miyoung Choi miyoungc@nvidia.com
Summary by CodeRabbit
Documentation
Chores