docs: catch up reference and troubleshooting docs for v0.0.21

[miyoungc]

Summary

Catches up the user-facing reference and troubleshooting docs with the CLI and policy behavior changes that landed in v0.0.21. Drafted via the nemoclaw-contributor-update-docs skill against commits in v0.0.20..v0.0.21, filtered through docs/.docs-skip.

Changes

• docs/reference/commands.md
  • nemoclaw list: session indicator (●) for connected sandboxes (feat(cli): add active session detection before destructive sandbox operations #2117).
  • nemoclaw <name> connect: active-session note; auto-recovery from SSH identity drift after a host reboot (feat(cli): add active session detection before destructive sandbox operations #2117, fix(connect): auto-recover from SSH identity drift after host reboot #2064).
  • nemoclaw <name> status: three-state Inference line (healthy / unreachable / not probed) covering both local and remote providers; new Connected line (fix(cli): show inference health in sandbox status output #2002, feat(cli): add active session detection before destructive sandbox operations #2117).
  • nemoclaw <name> destroy and rebuild: active-session warning with second confirm; rebuild reapplies policy presets to the recreated sandbox (feat(cli): add active session detection before destructive sandbox operations #2117, fix(rebuild): restore policy presets after sandbox rebuild (#1952) #2026).
  • nemoclaw <name> policy-add and policy-remove: positional preset argument and non-interactive flow via --yes/--force/NEMOCLAW_NON_INTERACTIVE=1 (fix(cli): support non-interactive policy preset updates (Fixes #2067) #2070).
  • nemoclaw <name> policy-list: registry-vs-gateway desync detection (fix(policies): cross-reference gateway state in policy-list to detect desync #2089).
• docs/reference/troubleshooting.md
  • Reconnect after a host reboot: now reflects automatic stale known_hosts pruning on connect (fix(connect): auto-recover from SSH identity drift after host reboot #2064).
  • Running multiple sandboxes simultaneously: onboard's forward-port collision guard (fix(onboard): use effectivePort in dashboard wait and guard forward port collision #2086).
  • New section: openclaw config set or unset is blocked inside the sandbox (fix(sandbox): block 'openclaw config set|unset' inside the sandbox #2081).
• docs/network-policy/customize-network-policy.md: non-interactive policy-add/policy-remove form; preset preservation across rebuild (fix(cli): support non-interactive policy preset updates (Fixes #2067) #2070, fix(rebuild): restore policy presets after sandbox rebuild (#1952) #2026).
• docs/inference/use-local-inference.md: NIM section now covers the NGC API key prompt with masked input and docker login nvcr.io --password-stdin behavior (fix: prompt for NGC API key when pulling local NIM images #2043).
• Generated skills regenerated to pick up the source changes (.agents/skills/nemoclaw-user-reference/references/{commands,troubleshooting}.md, plus minor heading-flow deltas elsewhere). The pre-commit Regenerate agent skills from docs hook ran and confirmed source ↔ generated parity.

Commits skipped per docs/.docs-skip or no doc impact: bbbaa0fb (skip-features), 7cb482cb (skip-features), 8dee23fd (skip-terms), plus the usual CI / test / refactor / install-plumbing churn.

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

• npx prek run --all-files passes for the modified files (the one failing test, test/cli.test.ts > unknown command exits 1, also fails on origin/main and is unrelated to these markdown-only changes)
• npm test passes — skipped; same pre-existing CLI-dispatch test failure unrelated to docs
• Tests added or updated for new or changed behavior — n/a, doc-only
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only) — not run locally
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only) — n/a, no new pages

AI Disclosure

• AI-assisted — tool: Claude Code

---

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

Summary by CodeRabbit

• New Features

  • Multi-session SSH connections with concurrent session support.
  • Three-state inference health reporting (healthy/unreachable/not probed) across all providers.
  • Automatic SSH host key rotation detection and recovery.
  • Non-interactive policy preset management via positional arguments.
  • Session indicators in sandbox list view.

• Bug Fixes

  • Protected destructive operations with active-session warnings.
  • Policy presets now preserved during sandbox rebuilds.

• Documentation

  • NGC registry authentication requirements for container images.
  • Multi-sandbox onboarding and reconnection guidance.
  • Troubleshooting updates for port conflicts and SSH issues.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 514d436c-40bf-4a2a-bc28-c42d66c6fe81

📥 Commits

Reviewing files that changed from the base of the PR and between ff18fb8 and 6257a4c.

📒 Files selected for processing (8)

• .agents/skills/nemoclaw-user-configure-inference/SKILL.md
• .agents/skills/nemoclaw-user-manage-policy/SKILL.md
• .agents/skills/nemoclaw-user-reference/references/commands.md
• .agents/skills/nemoclaw-user-reference/references/troubleshooting.md
• docs/inference/use-local-inference.md
• docs/network-policy/customize-network-policy.md
• docs/reference/commands.md
• docs/reference/troubleshooting.md

---

📝 Walkthrough

Walkthrough

Documentation updates across inference configuration, policy management, and CLI commands. Added NGC registry authentication requirements for NIM container images, scripted policy preset management with non-interactive modes, SSH session indicators and automatic host key rotation handling, and enhanced safety confirmations for destructive operations.

Changes

Cohort / File(s)	Summary
NIM/NGC Authentication .agents/skills/nemoclaw-user-configure-inference/SKILL.md, docs/inference/use-local-inference.md	Documented NGC registry authentication requirements for NIM container images on nvcr.io, including Docker login prompting, credential flow, masked input, retry behavior, and non-interactive mode handling.
Policy Management Scripting .agents/skills/nemoclaw-user-manage-policy/SKILL.md, docs/network-policy/customize-network-policy.md	Added documentation for non-interactive policy preset operations: positional preset name arguments, --yes flag, NEMOCLAW_NON_INTERACTIVE=1 environment variable, and preset reapplication during sandbox rebuild.
CLI Command Enhancements .agents/skills/nemoclaw-user-reference/references/commands.md, docs/reference/commands.md	Comprehensive CLI documentation updates for list (SSH session indicator), connect (multi-session support, host key rotation), status (three-state inference health reporting), destroy/rebuild (active-session warnings), policy-add/policy-remove (non-interactive modes), and policy-list (gateway sync checking).
SSH & Connection Management .agents/skills/nemoclaw-user-reference/references/commands.md, docs/reference/commands.md	Documented automatic SSH host key rotation detection via known_hosts pruning, multi-session concurrency tracking, and session count reporting during reconnection scenarios.
Troubleshooting Updates .agents/skills/nemoclaw-user-reference/references/troubleshooting.md, docs/reference/troubleshooting.md	Added guidance for multi-sandbox port conflicts via openshell forward list checks, automatic host key rotation handling, and new section on read-only sandbox configuration with rebuild resolution.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Hops with glee through docs so bright,
NGC keys and presets right,
SSH sessions now shine with dots,
Safe confirmations guard the slots,
A warren of knowledge, clear and light! ✨

🚥 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 title clearly and accurately summarizes the main objective of the PR—updating reference and troubleshooting documentation to reflect v0.0.21 feature changes.
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/v0.0.21-catchup

---

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

[ericksoa]

Docs-only, content accurately reflects v0.0.21 CLI changes. Generated skills in sync. CI green. LGTM.