Skip to content

docs: document remaining 0.0.57 behavior changes#4717

Merged
cv merged 2 commits into
mainfrom
docs/0.0.57-refresh-ff
Jun 3, 2026
Merged

docs: document remaining 0.0.57 behavior changes#4717
cv merged 2 commits into
mainfrom
docs/0.0.57-refresh-ff

Conversation

@miyoungc

@miyoungc miyoungc commented Jun 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds the follow-up source documentation that was identified after the 0.0.57 release-docs refresh merged. The PR fills remaining coverage gaps for route reconciliation, re-onboard policy persistence, per-port gateways, stale sandbox recovery, Docker-driver status details, managed vLLM progress, and Slack channel startup behavior.

Related Issue

None.

Changes

  • Documented connect warnings for gateway-vs-registry inference route mismatches, registry-preserving stale sandbox recovery, and inference set registry-first behavior with rebuild guidance.
  • Added source-page coverage for finalized policy preset selections across re-onboard, policy-step cancel rollback, per-port gateway isolation, Docker paused-container status hints, host alias driver support, and status recovery behavior.
  • Updated inference, lifecycle, messaging, troubleshooting, and generated user-skill references so the source docs and generated skill output stay synchronized.

Type of Change

  • Code change (feature, bug fix, or refactor)
  • Code change with doc updates
  • Doc only (prose changes, no code sample modifications)
  • Doc only (includes code sample changes)

Verification

  • python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx
  • npm run docs:sync-agent-variants
  • npm run docs
  • rg "permissive mode|shields down|shields up|shields status|config rotate-token|rotate-token" docs --glob "*.mdx"
  • rg "permissive mode|shields down|shields up|shields status|config rotate-token|rotate-token" .agents/skills --glob "*.md"
  • Commit hooks and pre-push hooks passed, including markdownlint, docs-to-skills verification, gitleaks, NEMOCLAW env-var documentation gate, skills YAML, commitlint, and CLI typecheck.

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

  • Documentation
    • Improved vLLM setup docs with stronger progress monitoring and failure diagnostics (polling/readiness, watchdog, container log tails)
    • Added cross-provider switch guidance with rebuild hints when post-switch sync fails
    • Guidance for running multiple gateways on one host
    • Expanded Slack setup with token validation and credential normalization
    • Clarified CLI behaviors: policy preset persistence, connect realignment, status (dockerPaused) hints, host-alias driver support, and inference registry timing
    • Added troubleshooting for sandboxes registered locally but missing from the gateway

@copy-pr-bot

copy-pr-bot Bot commented Jun 3, 2026

Copy link
Copy Markdown

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

coderabbitai Bot commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b3afc632-4695-4d44-abd1-c29d9a21c9ef

📥 Commits

Reviewing files that changed from the base of the PR and between b7e6125 and 3fb67e7.

📒 Files selected for processing (4)
  • .agents/skills/nemoclaw-user-reference/references/commands-nemohermes.md
  • .agents/skills/nemoclaw-user-reference/references/commands.md
  • docs/reference/commands-nemohermes.mdx
  • docs/reference/commands.mdx

📝 Walkthrough

Walkthrough

This PR updates NemoClaw documentation to reflect behavioral enhancements across onboarding, multi-gateway deployments, connection management, status reporting, and failure handling. Changes span both skill-level and main user documentation to maintain consistency.

Changes

NemoClaw CLI and Infrastructure Documentation

Layer / File(s) Summary
vLLM Managed Container Startup Behavior
.agents/skills/nemoclaw-user-configure-inference/SKILL.md, docs/inference/use-local-inference.mdx
vLLM managed-container startup now polls /v1/models for readiness, introduces a watchdog to stop stalled Docker pulls based on progress, and prints container log tail on failure instead of indefinite waiting.
Cross-Provider Switching Failure Handling
.agents/skills/.../switch-inference-providers.md, docs/inference/switch-inference-providers.mdx
Both OpenClaw and Hermes variants now document warning and recovery guidance when in-sandbox config synchronization fails after gateway route updates.
Multi-Gateway Port Isolation Configuration
.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md, docs/manage-sandboxes/lifecycle.mdx, .agents/skills/.../commands-nemohermes.md, .agents/skills/.../commands.md, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx
Users can run separate OpenShell gateways on the same host by setting different NEMOCLAW_GATEWAY_PORT values before onboarding; NemoClaw isolates gateway name, state, and compatibility containers by port.
Slack Token Validation and Credential Normalization
.agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md, docs/manage-sandboxes/messaging-channels.mdx
Slack setup now validates both required tokens before saving and documents sandbox startup normalization of OpenShell credential placeholders into the Slack runtime environment.
Onboarding Policy Preset Persistence
.agents/skills/.../commands-nemohermes.md, .agents/skills/.../commands.md, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx
NemoClaw records finalized policy preset selections during onboarding and uses them as seeds for subsequent re-onboard runs, preserving intentionally removed presets unless reselected.
Onboarding Cancellation Rollback at Policy Step
.agents/skills/.../commands-nemohermes.md, .agents/skills/.../commands.md, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx
Canceling brand-new onboarding at the policy preset step rolls back the sandbox, registry entry, and session; already-live sandboxes are not deleted.
Connect Command Inference Route Alignment
.agents/skills/.../commands-nemohermes.md, .agents/skills/.../commands.md, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx
connect warns and realigns the shared gateway when live inference routes differ from recorded registry routes; preserves registry metadata when sandbox is missing from gateway.
Status Command Docker Paused and Missing Gateway Handling
.agents/skills/.../commands-nemohermes.md, .agents/skills/.../commands.md, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx
status now reports dockerPaused indicator for paused Docker containers with unpause recovery hint; preserves registry entries when sandbox is locally registered but missing from gateway.
Host Alias Command Support Limitations
.agents/skills/.../commands-nemohermes.md, .agents/skills/.../commands.md, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx
hosts-add is now documented as supported only on Docker-driver and VM-driver sandboxes, not Kubernetes-driver.
Inference Set Registry Update and Sync Failure Handling
.agents/skills/.../commands-nemohermes.md, .agents/skills/.../commands.md, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx
inference set updates the host registry immediately after gateway route changes; on in-sandbox config sync failure, keeps gateway and registry aligned while warning about potential rebuild need.
Troubleshooting Stale Local Sandbox Registry Entries
.agents/skills/.../references/troubleshooting.md, docs/reference/troubleshooting.mdx
New troubleshooting section explains handling of sandboxes in local registry but missing from gateway, with recovery guidance for rebuild --yes or destroy.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

  • NVIDIA/NemoClaw#4676: Updates vLLM managed-container onboarding documentation to match new /v1/models polling readiness, stalled pull watchdog, and tail-logs-on-failure behavior.
  • NVIDIA/NemoClaw#4632: Related changes that refactor inference docs and per-agent variants affecting the same inference documentation and routing/sync text.

Suggested labels

v0.0.57

Suggested reviewers

  • cv

Poem

🐰 Docs hopped in, with clarity bright,
Ports kept apart through morning light,
Presets remembered, status polite,
If vLLM stalls, we tail the night,
NemoClaw's guides now set things right.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The pull request title clearly and directly summarizes the main change: adding documentation for remaining 0.0.57 behavior changes that were identified after the release-docs refresh.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/0.0.57-refresh-ff

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

@github-actions

github-actions Bot commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: None
Optional E2E: docs-validation-e2e

Dispatch hint: docs-validation-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • None. No merge-blocking E2E is recommended because the PR only changes Markdown/MDX documentation and assistant skill reference content. It does not touch installer/onboarding code, sandbox lifecycle implementation, credential handling, network policy assets, inference routing code, deployment scripts, workflows, or runtime user-flow code.

Optional E2E

  • docs-validation-e2e (low): Optional confidence check for CLI/docs parity and repository-local documentation links after broad docs/reference edits. Not merge-blocking because this PR does not change runtime code and lighter PR docs workflows should cover docs validation.

New E2E recommendations

  • agent-skill-guidance (medium): Existing full E2E skill-agent coverage verifies injected sandbox skills, but these .agents/skills documentation changes would benefit from a lightweight, non-runtime validation path for skill frontmatter and local links without running a full sandbox.
    • Suggested test: Add a lightweight PR validation job for .agents/skills changes that runs validate_repo_skills.sh and check-docs.sh --only-links --with-skills --local-only on changed skill Markdown files.

Dispatch hint

  • Workflow: .github/workflows/nightly-e2e.yaml
  • jobs input: docs-validation-e2e

@github-actions

github-actions Bot commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

  • None. Docs and agent skill reference content only; no changes under test/e2e-scenario/, scenario workflows, scenario metadata, expected-state contracts, suites, runtime, suite scripts, or onboarding/install helper code that would affect scenario E2E behavior.

Optional scenario E2E

  • None.

Relevant changed files

  • None.

@miyoungc miyoungc changed the title docs: fill 0.0.57 source coverage gaps docs: document remaining 0.0.57 behavior changes Jun 3, 2026
@miyoungc miyoungc marked this pull request as ready for review June 3, 2026 16:55
@miyoungc miyoungc added documentation v0.0.58 Release target area: docs Documentation, examples, guides, or docs build labels Jun 3, 2026
@github-actions

github-actions Bot commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor

Findings: 0 needs attention, 1 worth checking, 0 nice ideas
Top item: PR review advisor unavailable

Review findings

🛠️ Needs attention

  • None.

🔎 Worth checking

  • PR review advisor unavailable: The automated advisor could not complete: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt
    • Recommendation: Re-run the PR Review Advisor or perform a manual review.
    • Evidence: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt

🌱 Nice ideas

  • None.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
docs/inference/use-local-inference.mdx (1)

376-376: ⚡ Quick win

Format the CLI command as inline code.

Use docker pull instead of plain text in this sentence to match docs command-formatting rules.

As per coding guidelines, "CLI commands, file paths, flags, parameter names, and values must use inline code formatting."

🤖 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/inference/use-local-inference.mdx` at line 376, Update the sentence that
currently reads "If Docker pull output stops making progress..." to format the
CLI command as inline code: replace the plain text docker pull with inline
`docker pull` so it follows the docs' CLI command formatting rules.
🤖 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/manage-sandboxes/lifecycle.mdx`:
- Around line 175-176: The docs mention using NEMOCLAW_GATEWAY_PORT to run
separate OpenShell gateways but the sample onboarding commands don't set it;
update the example commands (the ones that call onboard/onboarding) to
explicitly set NEMOCLAW_GATEWAY_PORT=<port> before each run (e.g.,
NEMOCLAW_GATEWAY_PORT=8001 ... onboard and NEMOCLAW_GATEWAY_PORT=8002 ...
onboard) so readers see concrete per-port onboarding usage and understand ports
isolate gateway name and local state.

---

Nitpick comments:
In `@docs/inference/use-local-inference.mdx`:
- Line 376: Update the sentence that currently reads "If Docker pull output
stops making progress..." to format the CLI command as inline code: replace the
plain text docker pull with inline `docker pull` so it follows the docs' CLI
command formatting rules.
🪄 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: 4ecab909-8419-4b86-aaa0-ddae5bcae08c

📥 Commits

Reviewing files that changed from the base of the PR and between be33a6a and b7e6125.

📒 Files selected for processing (14)
  • .agents/skills/nemoclaw-user-configure-inference/SKILL.md
  • .agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md
  • .agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md
  • .agents/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md
  • .agents/skills/nemoclaw-user-reference/references/commands-nemohermes.md
  • .agents/skills/nemoclaw-user-reference/references/commands.md
  • .agents/skills/nemoclaw-user-reference/references/troubleshooting.md
  • docs/inference/switch-inference-providers.mdx
  • docs/inference/use-local-inference.mdx
  • docs/manage-sandboxes/lifecycle.mdx
  • docs/manage-sandboxes/messaging-channels.mdx
  • docs/reference/commands-nemohermes.mdx
  • docs/reference/commands.mdx
  • docs/reference/troubleshooting.mdx

Comment thread docs/manage-sandboxes/lifecycle.mdx
@cv cv enabled auto-merge (squash) June 3, 2026 17:18
@cv cv merged commit 02cd77a into main Jun 3, 2026
27 of 28 checks passed
@cv cv deleted the docs/0.0.57-refresh-ff branch June 3, 2026 17:22
@wscurran wscurran added the chore Build, CI, dependency, or tooling maintenance label Jun 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance v0.0.58 Release target

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants