docs: refresh doc and start collecting troubleshooting items in a singular place

README.md

@@ -60,6 +60,9 @@ The script installs Node.js if it is not already present, then runs the guided o
 $ curl -fsSL https://nvidia.com/nemoclaw.sh | bash
 ```
 
+If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH.
+If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/.zshrc` for zsh) or open a new terminal.
+
 When the install completes, a summary confirms the running environment:
 
 ```
@@ -191,6 +194,7 @@ Refer to the documentation for more information on NemoClaw.
 - [Inference Profiles](https://docs.nvidia.com/nemoclaw/latest/reference/inference-profiles.html): NVIDIA cloud inference configuration
 - [Network Policies](https://docs.nvidia.com/nemoclaw/latest/reference/network-policies.html): egress control and policy customization
 - [CLI Commands](https://docs.nvidia.com/nemoclaw/latest/reference/commands.html): full command reference
+- [Troubleshooting](https://docs.nvidia.com/nemoclaw/latest/reference/troubleshooting.html): common issues and resolution steps
 
 ## License
 

docs/index.md

@@ -236,6 +236,7 @@ Architecture <reference/architecture>
 Commands <reference/commands>
 Inference Profiles <reference/inference-profiles>
 Network Policies <reference/network-policies>
+Troubleshooting <reference/troubleshooting>
 ```
 
 ```{toctree}

docs/monitoring/monitor-sandbox-activity.md

@@ -47,7 +47,7 @@ Key fields in the output include the following:
 - Blueprint run ID, which is the identifier for the most recent blueprint execution.
 - Inference provider, which shows the active provider, model, and endpoint.
 
-If you run `openclaw nemoclaw status` from inside the sandbox, the command detects the sandbox context and reports it. Host-level sandbox and inference details are not available from within the sandbox. Run `openshell sandbox status` on the host for full host-side details.
+If you run `openclaw nemoclaw status` from inside the sandbox, the command detects the sandbox context and reports it. Host-level sandbox and inference details are not available from within the sandbox. Run `openshell sandbox list` on the host to check the underlying sandbox state.
 
 ## View Blueprint and Sandbox Logs
 
@@ -108,21 +108,9 @@ If the request fails, check the following:
 2. Run `openclaw nemoclaw logs -f` to view error messages from the blueprint runner.
 3. Verify that the inference endpoint is reachable from the host.
 
-## Common Issues
-
-The following table lists common problems and their resolution steps:
-
-| Symptom | Resolution |
-|---|---|
-| Sandbox shows as stopped | Run `nemoclaw onboard` to recreate the sandbox. |
-| Inference requests time out | Verify the provider endpoint is reachable. Check `openclaw nemoclaw status` for the active endpoint. |
-| Agent cannot reach an external host | Open the TUI with `openshell term` and approve the blocked request, or add the endpoint to the policy. |
-| Blueprint run failed | Run `openclaw nemoclaw logs --run-id <id>` to view the error output for the failed run. |
-| cgroup v2 error during onboard | On Ubuntu 24.04, DGX Spark, or WSL2, Docker requires `"default-cgroupns-mode": "host"` in `/etc/docker/daemon.json`. Run `nemoclaw setup-spark` to apply this fix, then retry `nemoclaw onboard`. |
-| Status shows "not running" inside sandbox | This is expected. The status command cannot query host-level state from within the sandbox. Run `openshell sandbox status` on the host instead. |
-
 ## Related Topics
 
+- [Troubleshooting](../reference/troubleshooting.md) for common issues and resolution steps.
 - [Commands](../reference/commands.md) for the full CLI reference.
 - [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests.md) for the operator approval flow.
 - [Switch Inference Providers](../inference/switch-inference-providers.md) to change the active provider.

docs/reference/commands.md

@@ -63,7 +63,9 @@ $ openclaw nemoclaw status [--json]
 `--json`
 : Output as JSON for programmatic consumption.
 
-When you run `status` inside an active OpenShell sandbox, host-level commands like `openshell sandbox status` are unavailable. The status command detects this and reports the sandbox context instead of showing false negatives. Run `openshell sandbox status` on the host for full details.
+When running inside an active OpenShell sandbox, the status command detects the sandbox context and reports "active (inside sandbox)" instead of false negatives.
+Host-side sandbox state and inference configuration are not inspectable from inside the sandbox.
+Run `openshell sandbox list` on the host to check the underlying sandbox state.
 
 ### `openclaw nemoclaw logs`
 
@@ -106,13 +108,12 @@ $ nemoclaw onboard
 
 The first run prompts for your NVIDIA API key and saves it to `~/.nemoclaw/credentials.json`.
 
-The onboard wizard runs a preflight check before creating the gateway. On systems with cgroup v2, such as Ubuntu 24.04 and DGX Spark, the preflight verifies that Docker is configured with `"default-cgroupns-mode": "host"` in `/etc/docker/daemon.json`. If this setting is missing, `nemoclaw onboard` exits with an error and directs you to run `nemoclaw setup-spark` to apply the fix.
+The wizard prompts for a sandbox name.
+Names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character.
+Uppercase letters are automatically lowercased.
 
-By default, the onboard menu shows NVIDIA cloud inference options only. To enable experimental local inference options (NIM, vLLM, Ollama), set the `NEMOCLAW_EXPERIMENTAL` environment variable before running onboard:
-
-```console
-$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard
-```
+Before creating the gateway, the wizard runs preflight checks.
+On systems with cgroup v2 (Ubuntu 24.04, DGX Spark, WSL2), it verifies that Docker is configured with `"default-cgroupns-mode": "host"` and provides fix instructions if the setting is missing.
 
 ### `nemoclaw list`
 
@@ -228,3 +229,8 @@ $ nemoclaw status
 Set up NemoClaw on DGX Spark.
 This command applies cgroup v2 and Docker fixes required for Ubuntu 24.04.
 Run with `sudo` on the Spark host.
+After the fixes complete, the script prompts you to run `nemoclaw onboard` to continue setup.
+
+```console
+$ sudo nemoclaw setup-spark
+```

docs/reference/troubleshooting.md

@@ -0,0 +1,126 @@
+---
+title:
+  page: "NemoClaw Troubleshooting Guide"
+  nav: "Troubleshooting"
+description: "Diagnose and resolve common NemoClaw installation, onboarding, and runtime issues."
+keywords: ["nemoclaw troubleshooting", "nemoclaw debug sandbox issues"]
+topics: ["generative_ai", "ai_agents"]
+tags: ["openclaw", "openshell", "troubleshooting", "nemoclaw"]
+content:
+  type: reference
+  difficulty: technical_beginner
+  audience: ["developer", "engineer"]
+status: published
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Troubleshooting
+
+This page covers common issues you may encounter when installing, onboarding, or running NemoClaw, along with their resolution steps.
+
+## Installation
+
+### `nemoclaw` not found after install
+
+If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH.
+The `nemoclaw` binary is installed but the shell session does not know where to find it.
+
+Run `source ~/.bashrc` (or `source ~/.zshrc` for zsh), or open a new terminal window.
+
+### Installer fails on unsupported platform
+
+The installer checks for a supported OS and architecture before proceeding.
+NemoClaw requires Linux Ubuntu 22.04 LTS or later.
+If you see an unsupported platform error, verify that you are running on a supported Linux distribution.
+
+## Onboarding
+
+### Cgroup v2 errors during onboard
+
+On Ubuntu 24.04, DGX Spark, and WSL2, Docker may not be configured for cgroup v2 delegation.
+The onboard preflight check detects this and fails with a clear error message.
+
+Run the Spark setup script to fix the Docker cgroup configuration, then retry onboarding:
+
+```console
+$ sudo nemoclaw setup-spark
+$ nemoclaw onboard
+```
+
+### Invalid sandbox name
+
+Sandbox names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character.
+Uppercase letters are automatically lowercased.
+
+If the name does not match these rules, the wizard exits with an error.
+Choose a name such as `my-assistant` or `dev1`.
+
+### Sandbox creation fails on DGX
+
+On DGX machines, sandbox creation can fail if the gateway's DNS has not finished propagating or if a stale port forward from a previous onboard run is still active.
+
+Run `nemoclaw onboard` to retry.
+The wizard cleans up stale port forwards and waits for gateway readiness automatically.
+
+### Colima socket not detected (macOS)
+
+Newer Colima versions use the XDG base directory (`~/.config/colima/default/docker.sock`) instead of the legacy path (`~/.colima/default/docker.sock`).
+NemoClaw checks both paths.
+If neither is found, verify that Colima is running:
+
+```console
+$ colima status
+```
+
+## Runtime
+
+### Sandbox shows as stopped
+
+The sandbox may have been stopped or deleted.
+Run `nemoclaw onboard` to recreate the sandbox from the same blueprint and policy definitions.
+
+### Status shows "not running" inside the sandbox
+
+This is expected behavior.
+When running `openclaw nemoclaw status` inside an active sandbox, host-side sandbox state and inference configuration are not inspectable.
+The status command detects the sandbox context and reports "active (inside sandbox)" instead.
+
+Run `openshell sandbox list` on the host to check the underlying sandbox state.
+
+### Inference requests time out
+
+Verify that the inference provider endpoint is reachable from the host.
+Check the active provider and endpoint:
+
+```console
+$ openclaw nemoclaw status
+```
+
+If the endpoint is correct but requests still fail, check for network policy rules that may block the connection, and verify that your NVIDIA API key is valid.
+
+### Agent cannot reach an external host
+
+OpenShell blocks outbound connections to hosts not listed in the network policy.
+Open the TUI to see blocked requests and approve them:
+
+```console
+$ openshell term
+```
+
+To permanently allow an endpoint, add it to the network policy.
+Refer to [Customize the Network Policy](../network-policy/customize-network-policy.md) for details.
+
+### Blueprint run failed
+
+View the error output for the failed blueprint run:
+
+```console
+$ openclaw nemoclaw logs --run-id <id>
+```
+
+If the run ID is unknown, omit `--run-id` to view logs from the most recent run.
+Use `--follow` to stream logs in real time while debugging.