NVIDIA · miyoungc · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -21,7 +21,7 @@ Load the `nemoclaw-skills-guide` skill for a full catalog and quick decision gui
 |------|----------|---------|
 | `bin/` | JavaScript (CJS) | CLI launcher (`nemoclaw.js`) and small compatibility helpers |
 | `src/lib/` | TypeScript | Core CLI logic: onboard, credentials, inference, policies, preflight, runner |
-| `nemoclaw/` | TypeScript | Plugin project (Commander CLI extension for OpenClaw) |
+| `nemoclaw/` | TypeScript | Plugin registering `/nemoclaw` TUI slash commands inside OpenClaw; `openclaw nemoclaw <cmd>` shell subcommand path is descoped |
 | `nemoclaw/src/blueprint/` | TypeScript | Runner, snapshot, SSRF validation, state management |
 | `nemoclaw/src/commands/` | TypeScript | Slash commands, migration state |
 | `nemoclaw/src/onboard/` | TypeScript | Onboarding config |

diff --git a/ci/platform-matrix.json b/ci/platform-matrix.json
@@ -39,7 +39,7 @@
       "status": "caveated",
       "prd_priority": "P0",
       "ci_tested": true,
-      "notes": "Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight."
+      "notes": "Start the container runtime (Colima or Docker Desktop) before running the installer. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight."
     },
     {
       "name": "DGX Spark",

diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx
@@ -57,6 +57,13 @@ sudo apt-get install -y binutils
 
 On macOS, NemoClaw uses the Docker-driver OpenShell gateway path with Docker Desktop or Colima.
 You do not need to install or sign a separate OpenShell VM driver helper for standard macOS onboarding.
+If you use Homebrew Colima, install the Docker CLI package with Colima because `brew install colima` does not provide the `docker` command:
+
+```bash
+brew install colima docker
+colima start --cpu 4 --memory 8
+docker info
+```
 
 <Warning title="OpenShell Lifecycle">
 For NemoClaw-managed environments, use `$$nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.
@@ -81,7 +88,7 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC
 | OS | Container runtime | Status | Notes |
 |----|-------------------|--------|-------|
 | Linux | Docker | Tested | Primary tested path. Ubuntu 24.04 is the validated distro in production source (`DEFAULT_COMPAT_IMAGE` in `src/lib/onboard/docker-driver-gateway-launch.ts:10` and the preflight tests pin 24.04 only); the installer's package-manager probes assume apt-get. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. |
-| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
+| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Start the container runtime (Colima or Docker Desktop) before running the installer. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
 | DGX Spark | Docker | Tested | Use the standard installer and `$$nemoclaw onboard`. For an end-to-end walkthrough with local inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). |
 | Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | Requires WSL2 with Docker Desktop backend. |
 {/* platform-matrix:end */}

diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx
@@ -186,4 +186,20 @@ All NemoClaw commands run inside WSL, not in PowerShell.
 
 ## Troubleshooting
 
+### Cursor blocks the starter prompt install command
+
+Cursor can block Windows terminal automation before NemoClaw runs when the Legacy Terminal Tool is disabled or when Run Mode is locked to **Allowlist with Sandbox**.
+This is a Cursor security restriction, not a NemoClaw installer failure.
+If your AI assistant reports this restriction, use one of these recovery paths:
+
+1. Enable the terminal capability your organization allows, then ask the assistant to retry the approved install command from the starter prompt.
+2. If your organization permits manually created local scripts but not automated terminal execution, ask the assistant to create a local `.bat` or `.ps1` fallback file.
+   The assistant must show you the exact file contents before you run it, and you should inspect and approve those contents first.
+3. Start Docker Desktop and confirm WSL integration before running the fallback file.
+
+Do not paste API keys, bot tokens, or other secrets into chat while using the fallback path.
+Enter credentials only into the local terminal, browser, or secure prompt that needs them.
+Do not embed real credentials in the generated `.bat` or `.ps1` file.
+Docker Desktop must be running before the NemoClaw install command can continue.
+
 For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](../../reference/troubleshooting#windows-subsystem-for-linux) in the Troubleshooting guide.
diff --git a/docs/index.yml b/docs/index.yml
@@ -168,6 +168,9 @@ navigation:
               - page: "CLI Selection Guide"
                 path: _build/agent-variants/reference/cli-selection-guide.openclaw.generated.mdx
                 slug: cli-selection-guide
+              - page: "Host Files and State"
+                path: _build/agent-variants/reference/host-files-and-state.openclaw.generated.mdx
+                slug: host-files-and-state
               - page: "Network Policies"
                 path: _build/agent-variants/reference/network-policies.openclaw.generated.mdx
                 slug: network-policies
@@ -320,6 +323,9 @@ navigation:
               - page: "CLI Selection Guide"
                 path: _build/agent-variants/reference/cli-selection-guide.hermes.generated.mdx
                 slug: cli-selection-guide
+              - page: "Host Files and State"
+                path: _build/agent-variants/reference/host-files-and-state.hermes.generated.mdx
+                slug: host-files-and-state
               - page: "Network Policies"
                 path: _build/agent-variants/reference/network-policies.hermes.generated.mdx
                 slug: network-policies

diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx
@@ -309,6 +309,7 @@ For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY sh
 `--yes` stays non-destructive by design.
 It only acknowledges the global confirmation prompt and never purges preserved user data on its own.
 Full purge always requires an explicit `--destroy-user-data` or the matching env var, so existing automation using `--yes` retains its safe behaviour.
+For a full host-side file reference, see [Host Files and State](../reference/host-files-and-state).
 Refer to the [Commands reference](../reference/commands#$$nemoclaw-uninstall) for the full preservation contract.
 </Note>
 

diff --git a/docs/reference/host-files-and-state.mdx b/docs/reference/host-files-and-state.mdx
@@ -0,0 +1,50 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Host Files and State"
+sidebar-title: "Host Files and State"
+description: "Reference for NemoClaw host-side files and directories under ~/.nemoclaw."
+description-agent: "Lists host-side NemoClaw config and state files under ~/.nemoclaw. Use when identifying config.json, credentials.json, sandboxes.json, onboard-session.json, backup directories, mounts, or local inference adapter files."
+keywords: ["nemoclaw host files", "nemoclaw state directory", "nemoclaw sandboxes json", "nemoclaw credentials json"]
+content:
+  type: "reference"
+---
+
+NemoClaw stores host-side configuration, credentials, registry metadata, transient install state, and local backups under `~/.nemoclaw/`.
+Use this page when you need to identify what a file does before deleting, backing up, or sharing diagnostics.
+
+<Warning>
+Do not paste `credentials.json`, provider tokens, bot tokens, proxy tokens, or debug archives containing them into chat or issue comments.
+Share redacted diagnostics only.
+</Warning>
+
+## Files
+
+| Path | Purpose | Safe to delete |
+|---|---|---|
+| `~/.nemoclaw/config.json` | Host-level CLI configuration and defaults created by onboarding or config commands. | Only if you want NemoClaw to forget host defaults and rebuild them on the next setup. |
+| `~/.nemoclaw/credentials.json` | Host-side provider and integration credential registry. | Only when you intentionally want to re-enter credentials. |
+| `~/.nemoclaw/sandboxes.json` | Current sandbox registry used by `$$nemoclaw list`, default sandbox selection, rebuild, and recovery commands. | No. Deleting it makes the host forget existing sandboxes and can block state-preserving recovery. |
+| `~/.nemoclaw/onboard-session.json` | Resume marker for an onboarding attempt that failed before completion. | Yes, when you intentionally want to discard the failed session and start over. Prefer `$$nemoclaw onboard --fresh` when available. |
+| `~/.nemoclaw/ollama-proxy-token` | Local auth token used by the host-side Ollama auth proxy. | Yes, but re-run onboarding afterward so NemoClaw recreates and registers the proxy token. |
+
+`sandboxes.json` is the current registry file name.
+If you see `registry.json` in older tests, notes, or discussions, treat it as legacy wording for the sandbox registry unless a specific release note says otherwise.
+
+## Directories
+
+| Path | Purpose | Safe to delete |
+|---|---|---|
+| `~/.nemoclaw/rebuild-backups/` | Host-side snapshots written by `backup-all`, `snapshot create`, and rebuild flows. | Only after you no longer need rollback or restore points. |
+| `~/.nemoclaw/backups/` | Workspace backups written by legacy backup helpers and some recovery flows. | Only after confirming you no longer need those workspace archives. |
+| `~/.nemoclaw/mounts/` | Default local mount points created by share or mount commands. | Unmount first, then remove unused directories. |
+| `~/.nemoclaw/blueprints/` | Cached blueprint inputs used by onboarding and sandbox recreation. | Avoid manual deletion unless you plan to rerun onboarding from fresh inputs. |
+
+## Uninstall Behavior
+
+`$$nemoclaw uninstall --yes` removes active NemoClaw runtime resources but preserves the user data needed for recovery by default.
+Preserved entries include `rebuild-backups/`, `backups/`, and `sandboxes.json`.
+Interactive uninstall prompts before removing preserved state.
+For non-interactive runs, pass `--destroy-user-data` only when you accept losing local registry metadata and backups.
+
+For operational uninstall steps, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle#uninstall).
diff --git a/docs/reference/platform-support.mdx b/docs/reference/platform-support.mdx
@@ -79,7 +79,7 @@ For the onboarding-time supported set without deferred rows, refer to [Prerequis
 | OS | Container runtime | Status | PRD priority | CI | Notes |
 |----|-------------------|--------|--------------|----|-------|
 | Linux | Docker | Tested | P0 | Yes | Primary tested path. Ubuntu 24.04 is the validated distro in production source (`DEFAULT_COMPAT_IMAGE` in `src/lib/onboard/docker-driver-gateway-launch.ts:10` and the preflight tests pin 24.04 only); the installer's package-manager probes assume apt-get. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. |
-| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | P0 | Yes | Start the container runtime (Colima or Docker Desktop) before running the installer. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
+| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | P0 | Yes | Start the container runtime (Colima or Docker Desktop) before running the installer. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
 | DGX Spark | Docker | Tested | P1 | Yes | Use the standard installer and `$$nemoclaw onboard`. For an end-to-end walkthrough with local inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). |
 | Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | P1 | No | Requires WSL2 with Docker Desktop backend. |
 | DGX Station | Docker | Deferred | P1 | No | The PRD marks this platform as P1. Workstation form-factor with NVIDIA GPUs and the same Docker + NVIDIA Container Toolkit + CDI requirements as DGX Spark. Onboard path not yet validated end-to-end on the hardware; vLLM defaults to `deepseek-ai/DeepSeek-V4-Flash` for this host class and will move out of `deferred` once the hardware run is signed off. |

diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx
@@ -130,6 +130,19 @@ To avoid these issues, install the prerequisites in the following order before r
 1. Install Xcode Command Line Tools (`xcode-select --install`). These are needed by the installer and Node.js toolchain.
 2. Install and start a supported container runtime (Docker Desktop or Colima). Without a running runtime, the installer cannot connect to Docker.
 
+### `docker` is missing after installing Colima
+
+Homebrew Colima does not install the Docker CLI binary.
+If you install only Colima, `colima start` can succeed while later `docker` commands fail with `command not found`.
+
+Install both packages, start Colima with enough resources for the sandbox image build, and verify Docker before onboarding:
+
+```bash
+brew install colima docker
+colima start --cpu 4 --memory 8
+docker info
+```
+
 ### Permission errors during installation
 
 The NemoClaw installer does not require `sudo` or root.
@@ -604,8 +617,57 @@ As a last resort, you can also delete the session file directly and re-run the i
 rm ~/.nemoclaw/onboard-session.json
 ```
 
+### Kubernetes namespace not ready
+
+If onboarding fails with `Kubernetes namespace not ready`, a previous failed or interrupted setup may have left stale OpenShell or NemoClaw state behind.
+Clean up the failed installation before re-running the installer:
+
+```bash
+$$nemoclaw uninstall --yes
+curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
+```
+
+The normal uninstall path keeps user data under `~/.nemoclaw/`, including sandbox registry metadata, backups, and saved credentials unless you explicitly remove them.
+If `$$nemoclaw uninstall` reports that the local uninstall script is missing, follow the CLI's security boundary: download the versioned NVIDIA/NemoClaw tag URL that it prints, inspect the script locally, run that local copy, and then retry the installer.
+
+```bash
+curl -fsSLo uninstall.sh <versioned-uninstall-url>
+less uninstall.sh
+bash uninstall.sh --yes
+curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
+```
+
 ## Runtime
 
+<AgentOnly variant="openclaw">
+
+### OpenShell gateway and OpenClaw gateway startup order
+
+NemoClaw uses two gateway layers for OpenClaw sandboxes:
+
+- The OpenShell gateway runs on the host side and owns sandbox lifecycle, provider routes, port forwards, and `openshell sandbox list` / `status` queries.
+- The OpenClaw gateway runs inside the sandbox container and serves the OpenClaw dashboard, agent API, and sub-agent WebSocket traffic.
+
+Start and recover them in this order: container runtime, OpenShell gateway, sandbox container, then the in-sandbox OpenClaw gateway.
+
+<Warning>
+Do not start the OpenClaw gateway by hand before the OpenShell gateway is healthy.
+NemoClaw cannot select, inspect, or reconnect the sandbox until OpenShell can see the owning gateway.
+</Warning>
+
+If the host rebooted or the OpenShell gateway is down, first run:
+
+```bash
+$$nemoclaw <name> status
+```
+
+The status command selects or starts the sandbox's recorded OpenShell gateway when possible, then checks whether OpenShell can still see the sandbox.
+If the sandbox container is present but stopped on a Docker-driver host, status can recover the labeled container and then re-query OpenShell.
+After the sandbox is visible again, use `$$nemoclaw <name> recover` only for the in-sandbox OpenClaw gateway and host forwards.
+Use `$$nemoclaw <name> gateway restart` when you intentionally need the in-sandbox gateway to reload supported runtime configuration.
+
+</AgentOnly>
+
 ### Reconnect after a host reboot
 
 After a host reboot, the container runtime, OpenShell gateway, and sandbox may not be running.
@@ -778,8 +840,44 @@ $$nemoclaw <name> rebuild
 
 ### 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.
+When status reports `sandbox_container_stopped`, Docker still has a container for the sandbox, but the container is not running.
+Use the lightest recovery path first instead of rebuilding immediately.
+
+1. Confirm Docker can still see the labeled container.
+
+   ```bash
+   docker ps -a --filter "label=openshell.ai/sandbox-name=<name>"
+   ```
+
+   If a container is listed, start it:
+
+   ```bash
+   docker start <container-name>
+   ```
+
+1. Run status recovery from the host.
+
+   ```bash
+   $$nemoclaw <name> status
+   ```
+
+   On Docker-driver hosts, status also attempts non-destructive recovery when OpenShell reports the sandbox as missing but Docker still has a stopped `openshell.ai/sandbox-name=<name>` container or the latest GPU-backup sibling.
+   A successful recovery prints that the sandbox was recovered from Docker and then shows the refreshed OpenShell state.
+
+1. If the sandbox is running but the agent gateway or dashboard forward is still down, recover the in-sandbox gateway and forwards:
+
+   ```bash
+   $$nemoclaw <name> recover
+   ```
+
+1. Rebuild only if the sandbox cannot be restarted or status still cannot recover it while the local registry entry exists:
+
+   ```bash
+   $$nemoclaw <name> rebuild --yes
+   ```
+
+   Rebuild recreates the sandbox from recorded metadata and preserves supported workspace and agent state.
+   If the sandbox was intentionally deleted and you want a clean setup, run `$$nemoclaw <name> destroy` to remove the stale local entry, then run `$$nemoclaw onboard`.
 
 ### Sandbox is registered locally but missing from the gateway