docs: resolve maintainer docs gaps - #6213
Conversation
Document missing recovery and reference paths for Windows starter-prompt installs, macOS Colima setup, Kubernetes namespace cleanup, stopped sandbox recovery, host-side state files, and agent install readiness. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughDocumentation-only updates covering macOS Colima/Docker CLI prerequisites, a Windows Cursor install-blocking troubleshooting entry, Kubernetes namespace recovery and gateway startup order guidance, a stepwise sandbox recovery procedure, a new host files reference page with navigation entries, and an AGENTS.md plugin description clarification. ChangesDocumentation and troubleshooting updates
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Code Coverage OverviewLanguages: TypeScript TypeScript / code-coverage/pluginThe overall coverage in the Show a code coverage summary of the most covered files.
TypeScript / code-coverage/cliThe overall coverage in the Show a code coverage summary of the most covered files.
Updated |
|
🌿 Preview your docs: https://nvidia-preview-pr-6213.docs.buildwithfern.com/nemoclaw |
E2E Advisor RecommendationRequired E2E: None Full advisor summaryE2E Recommendation AdvisorBase: Required E2E
Optional E2E
New E2E recommendations
|
E2E Target RecommendationRequired E2E targets: None Full E2E target advisor summaryE2E Target AdvisorBase: Required E2E targets
Optional E2E targets
Relevant changed files
|
PR Review Advisor (Nemotron Ultra) — No blocking findingsMerge posture: No blocking advisor findings Action checklist
Test follow-ups to resolve or justifyIf these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.
This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision. |
|
Addressing PR Review Advisor test follow-ups:
|
PR Review Advisor — No blocking findingsMerge posture: No blocking advisor findings Action checklist
Test follow-ups to resolve or justifyIf these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.
This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision. |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/reference/troubleshooting.mdx (1)
620-637: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider cross-linking
~/.nemoclaw/reference.Line 630 describes what uninstall preserves under
~/.nemoclaw/; this PR also adds a dedicated Host Files and State reference page elsewhere in the stack that documents this directory in detail. Linking here would help readers find the fuller picture without duplicating the file-by-file breakdown.🤖 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 620 - 637, The troubleshooting section for Kubernetes namespace recovery should cross-link the `~/.nemoclaw/` mention to the dedicated Host Files and State reference page instead of leaving it as plain text. Update the prose around the uninstall guidance so readers can jump from the `~/.nemoclaw/` reference to the fuller documentation, using the existing troubleshooting heading and nearby uninstall instructions as the anchor.
🤖 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/reference/host-files-and-state.mdx`:
- Line 50: The backlink in the host-files-and-state reference points to the
wrong section slug, so update the link target to match the actual uninstall
section in Manage Sandbox Lifecycle. Locate the markdown reference in the
host-files-and-state doc and the `Uninstall` section in
`docs/manage-sandboxes/lifecycle.mdx`, then either change the link to the real
generated slug or add a stable explicit anchor and keep both references aligned.
---
Nitpick comments:
In `@docs/reference/troubleshooting.mdx`:
- Around line 620-637: The troubleshooting section for Kubernetes namespace
recovery should cross-link the `~/.nemoclaw/` mention to the dedicated Host
Files and State reference page instead of leaving it as plain text. Update the
prose around the uninstall guidance so readers can jump from the `~/.nemoclaw/`
reference to the fuller documentation, using the existing troubleshooting
heading and nearby uninstall instructions as the anchor.
🪄 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: 5bcd3868-8787-4f68-8b51-d7be8f37967d
📒 Files selected for processing (11)
AGENTS.mdci/platform-matrix.jsondocs/get-started/prerequisites.mdxdocs/get-started/windows-preparation.mdxdocs/index.ymldocs/manage-sandboxes/lifecycle.mdxdocs/reference/host-files-and-state.mdxdocs/reference/platform-support.mdxdocs/reference/troubleshooting.mdxdocs/resources/agent-install-readiness.mdxdocs/resources/agent-skills.mdx
Remove the agent install readiness checklist from this docs cleanup. Keep the PR focused on resolved documentation gaps with concrete page updates. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
Align uninstall fallback docs with the CLI download-review-run boundary and make Windows local-script fallback conditional on policy and user inspection. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
<!-- markdownlint-disable MD041 --> ## Summary This PR prepares the user-facing documentation for v0.0.73 before the release plan is frozen. It adds release notes for the merged runtime changes and closes documentation gaps around DNS-backed HTTPS endpoint validation and LangChain Deep Agents Code proxy recovery. ## Changes - Add the `v0.0.73` release-note section with links to the detailed command, inference, recovery, lifecycle, platform, and setup documentation. - Correct the custom endpoint guidance so DNS-backed HTTPS rejection and the supported alternatives match the fail-closed runtime behavior. - Document the managed `inference.local` proxy boundary and rebuild requirement for existing LangChain Deep Agents Code sandboxes. - Add troubleshooting guidance for the DNS-backed HTTPS validation error. - Validate with `npm run docs:sync-agent-variants` and `npm run docs`; Fern completed with 0 errors and 2 existing warnings. - Source summary: - [#6139](#6139) -> `docs/about/release-notes.mdx`, `docs/inference/inference-options.mdx`, `docs/reference/commands.mdx`, `docs/reference/commands-nemohermes.mdx`, and `docs/reference/troubleshooting.mdx`: Document fail-closed DNS-backed HTTPS endpoint handling and recovery options. - [#6142](#6142) -> `docs/about/release-notes.mdx`: Summarize native OpenShell GPU injection and compatibility-path diagnostics. - [#6197](#6197) -> `docs/about/release-notes.mdx`: Summarize agent-aware messaging preset rejection. - [#6199](#6199) -> `docs/about/release-notes.mdx`: Summarize the unreachable-sandbox backup opt-in, restore behavior, and data-loss boundary. - [#6204](#6204) and [#6206](#6206) -> `docs/about/release-notes.mdx` and `docs/get-started/quickstart-langchain-deepagents-code.mdx`: Document the corrected managed proxy contract and required sandbox rebuild. - [#6213](#6213) -> `docs/about/release-notes.mdx`: Summarize the merged setup, recovery, and host-state documentation. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates <!-- Check all that apply. For any "covered by existing tests", "not applicable", or waiver entry, add a brief justification on the same line or in the Changes section. --> - [ ] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [x] Tests not applicable — justification: documentation-only release preparation; the Fern docs build validates the changed pages and routes. - [x] Docs updated for user-facing behavior changes - [ ] Docs not applicable — justification: - [ ] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [ ] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification <!-- Check each item you ran and confirmed. Leave unchecked items you skipped. Doc-only changes do not require npm test unless you ran it. --> - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Git hooks passed during commit and push, or `npx prek run --from-ref main --to-ref HEAD` passes - [ ] Targeted tests pass for changed behavior - [ ] Full `npm test` passes (broad runtime changes only) - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) --- <!-- DCO sign-off is required in this PR description, and every commit must appear as Verified in GitHub. Run: git config user.name && git config user.email --> Signed-off-by: Carlos Villela <cvillela@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a new **v0.0.73** release notes section with six highlights at the top of the changelog. * Expanded **Custom Endpoint URL Validation** guidance in inference option docs, including explicit acceptance/rejection rules for HTTP vs DNS-backed HTTPS and how validated IPs are stored. * Updated command references (`nemohermes inference set`, `$$nemoclaw inference set`) to match the new validation behavior. * Added troubleshooting documentation for unsupported **DNS-backed HTTPS endpoints**, plus clarified Deep Agents Code routing and post-upgrade sandbox rebuild guidance. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Carlos Villela <cvillela@nvidia.com>
## Summary This PR resolves the maintainer-owned docs gaps behind the noisy contributor PR set without reusing that branch history. It adds missing recovery guidance and a host-side state reference while keeping OpenClaw-only gateway guidance out of the Hermes variant. ## Related Issue Closes NVIDIA#5326 — `docs/get-started/windows-preparation.mdx`: adds Cursor Run Mode / Legacy Terminal Tool troubleshooting for Windows starter-prompt installs, including fallback-file and Docker Desktop readiness guidance. Closes NVIDIA#6027 — `docs/reference/troubleshooting.mdx`: adds `Kubernetes namespace not ready` recovery steps that clean failed setup state before retrying install, with preserved-user-data notes. Closes NVIDIA#6028 — `docs/get-started/prerequisites.mdx`, `docs/reference/troubleshooting.mdx`, `ci/platform-matrix.json`, `docs/reference/platform-support.mdx`: documents that Homebrew Colima users must install both Colima and the Docker CLI and verify `docker info`. Closes NVIDIA#6030 — `AGENTS.md`: clarifies that `nemoclaw/` registers `/nemoclaw` OpenClaw TUI slash commands and that the `openclaw nemoclaw <cmd>` shell subcommand path is descoped. Closes NVIDIA#6031 — `docs/reference/troubleshooting.mdx`: adds OpenShell/OpenClaw gateway startup-order guidance for the OpenClaw variant and replaces stopped-sandbox guidance with a lighter recovery ladder before rebuild. Closes NVIDIA#6088 — `docs/reference/host-files-and-state.mdx`, `docs/manage-sandboxes/lifecycle.mdx`, `docs/index.yml`: adds a unified `~/.nemoclaw/` host files and state reference, including current `sandboxes.json` registry wording and uninstall preservation behavior. ## Changes - Add Windows Cursor recovery guidance to the Windows preparation page instead of expanding the starter prompt. - Document Homebrew Colima needing the Docker CLI, Kubernetes namespace cleanup, OpenShell/OpenClaw gateway order, and `sandbox_container_stopped` recovery. - Add a `Host Files and State` reference page, wire it into both OpenClaw and Hermes navigation, and link related docs. - Clarify the descoped `openclaw nemoclaw <cmd>` path in the agent architecture table. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [x] Doc only (includes code sample changes) ## Quality Gates - [ ] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [x] Tests not applicable — justification: docs-only change; validated with docs generators, link checks, and Fern docs build. - [x] Docs updated for user-facing behavior changes - [ ] Docs not applicable — justification: - [ ] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [ ] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Git hooks passed during commit and push, or `npx prek run --from-ref main --to-ref HEAD` passes - [ ] Targeted tests pass for changed behavior - [ ] Full `npm test` passes (broad runtime changes only) - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [x] New doc pages include SPDX header and frontmatter (new pages only) Commands run: - `python3 scripts/generate-platform-docs.py --check` - `npm run docs:check-agent-variants` - `bash test/e2e/e2e-cloud-experimental/check-docs.sh --only-links --local-only docs/get-started/windows-preparation.mdx docs/resources/agent-skills.mdx docs/reference/troubleshooting.mdx docs/reference/host-files-and-state.mdx` - `git diff --check` - `npm run docs` — passed with 0 errors; Fern reported 1 warning. - `npm run build:cli` — run so the pre-push TypeScript hook could resolve `dist/` imports. --- Signed-off-by: Miyoung Choi <miyoungc@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added a new reference page explaining NemoClaw host-side storage, safe-to-delete items, and how uninstall preserves or destroys data. * Added the new “Host Files and State” page to the user-guide navigation for both agent variants. * **Documentation** * Improved macOS Apple Silicon + Homebrew Colima setup by explicitly requiring the Docker CLI and verifying with `docker info`. * Expanded Windows troubleshooting guidance and added clearer recovery steps for onboarding and stopped sandboxes, including the correct startup order for gateways. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
<!-- markdownlint-disable MD041 --> ## Summary This PR prepares the user-facing documentation for v0.0.73 before the release plan is frozen. It adds release notes for the merged runtime changes and closes documentation gaps around DNS-backed HTTPS endpoint validation and LangChain Deep Agents Code proxy recovery. ## Changes - Add the `v0.0.73` release-note section with links to the detailed command, inference, recovery, lifecycle, platform, and setup documentation. - Correct the custom endpoint guidance so DNS-backed HTTPS rejection and the supported alternatives match the fail-closed runtime behavior. - Document the managed `inference.local` proxy boundary and rebuild requirement for existing LangChain Deep Agents Code sandboxes. - Add troubleshooting guidance for the DNS-backed HTTPS validation error. - Validate with `npm run docs:sync-agent-variants` and `npm run docs`; Fern completed with 0 errors and 2 existing warnings. - Source summary: - [NVIDIA#6139](NVIDIA#6139) -> `docs/about/release-notes.mdx`, `docs/inference/inference-options.mdx`, `docs/reference/commands.mdx`, `docs/reference/commands-nemohermes.mdx`, and `docs/reference/troubleshooting.mdx`: Document fail-closed DNS-backed HTTPS endpoint handling and recovery options. - [NVIDIA#6142](NVIDIA#6142) -> `docs/about/release-notes.mdx`: Summarize native OpenShell GPU injection and compatibility-path diagnostics. - [NVIDIA#6197](NVIDIA#6197) -> `docs/about/release-notes.mdx`: Summarize agent-aware messaging preset rejection. - [NVIDIA#6199](NVIDIA#6199) -> `docs/about/release-notes.mdx`: Summarize the unreachable-sandbox backup opt-in, restore behavior, and data-loss boundary. - [NVIDIA#6204](NVIDIA#6204) and [NVIDIA#6206](NVIDIA#6206) -> `docs/about/release-notes.mdx` and `docs/get-started/quickstart-langchain-deepagents-code.mdx`: Document the corrected managed proxy contract and required sandbox rebuild. - [NVIDIA#6213](NVIDIA#6213) -> `docs/about/release-notes.mdx`: Summarize the merged setup, recovery, and host-state documentation. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates <!-- Check all that apply. For any "covered by existing tests", "not applicable", or waiver entry, add a brief justification on the same line or in the Changes section. --> - [ ] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [x] Tests not applicable — justification: documentation-only release preparation; the Fern docs build validates the changed pages and routes. - [x] Docs updated for user-facing behavior changes - [ ] Docs not applicable — justification: - [ ] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [ ] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification <!-- Check each item you ran and confirmed. Leave unchecked items you skipped. Doc-only changes do not require npm test unless you ran it. --> - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Git hooks passed during commit and push, or `npx prek run --from-ref main --to-ref HEAD` passes - [ ] Targeted tests pass for changed behavior - [ ] Full `npm test` passes (broad runtime changes only) - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) --- <!-- DCO sign-off is required in this PR description, and every commit must appear as Verified in GitHub. Run: git config user.name && git config user.email --> Signed-off-by: Carlos Villela <cvillela@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a new **v0.0.73** release notes section with six highlights at the top of the changelog. * Expanded **Custom Endpoint URL Validation** guidance in inference option docs, including explicit acceptance/rejection rules for HTTP vs DNS-backed HTTPS and how validated IPs are stored. * Updated command references (`nemohermes inference set`, `$$nemoclaw inference set`) to match the new validation behavior. * Added troubleshooting documentation for unsupported **DNS-backed HTTPS endpoints**, plus clarified Deep Agents Code routing and post-upgrade sandbox rebuild guidance. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Carlos Villela <cvillela@nvidia.com>
Summary
This PR resolves the maintainer-owned docs gaps behind the noisy contributor PR set without reusing that branch history. It adds missing recovery guidance and a host-side state reference while keeping OpenClaw-only gateway guidance out of the Hermes variant.
Related Issue
Closes #5326 —
docs/get-started/windows-preparation.mdx: adds Cursor Run Mode / Legacy Terminal Tool troubleshooting for Windows starter-prompt installs, including fallback-file and Docker Desktop readiness guidance.Closes #6027 —
docs/reference/troubleshooting.mdx: addsKubernetes namespace not readyrecovery steps that clean failed setup state before retrying install, with preserved-user-data notes.Closes #6028 —
docs/get-started/prerequisites.mdx,docs/reference/troubleshooting.mdx,ci/platform-matrix.json,docs/reference/platform-support.mdx: documents that Homebrew Colima users must install both Colima and the Docker CLI and verifydocker info.Closes #6030 —
AGENTS.md: clarifies thatnemoclaw/registers/nemoclawOpenClaw TUI slash commands and that theopenclaw nemoclaw <cmd>shell subcommand path is descoped.Closes #6031 —
docs/reference/troubleshooting.mdx: adds OpenShell/OpenClaw gateway startup-order guidance for the OpenClaw variant and replaces stopped-sandbox guidance with a lighter recovery ladder before rebuild.Closes #6088 —
docs/reference/host-files-and-state.mdx,docs/manage-sandboxes/lifecycle.mdx,docs/index.yml: adds a unified~/.nemoclaw/host files and state reference, including currentsandboxes.jsonregistry wording and uninstall preservation behavior.Changes
sandbox_container_stoppedrecovery.Host Files and Statereference page, wire it into both OpenClaw and Hermes navigation, and link related docs.openclaw nemoclaw <cmd>path in the agent architecture table.Type of Change
Quality Gates
Verification
Verifiedin GitHubnpx prek run --from-ref main --to-ref HEADpassesnpm testpasses (broad runtime changes only)npm run docsbuilds without warnings (doc changes only)Commands run:
python3 scripts/generate-platform-docs.py --checknpm run docs:check-agent-variantsbash test/e2e/e2e-cloud-experimental/check-docs.sh --only-links --local-only docs/get-started/windows-preparation.mdx docs/resources/agent-skills.mdx docs/reference/troubleshooting.mdx docs/reference/host-files-and-state.mdxgit diff --checknpm run docs— passed with 0 errors; Fern reported 1 warning.npm run build:cli— run so the pre-push TypeScript hook could resolvedist/imports.Signed-off-by: Miyoung Choi miyoungc@nvidia.com
Summary by CodeRabbit
New Features
Documentation
docker info.