From a87efdd8c23536ad469a4d086cba87c6647f9e2f Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 2 Jul 2026 15:28:13 -0700 Subject: [PATCH 1/3] docs: resolve maintainer docs gaps 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 --- AGENTS.md | 2 +- ci/platform-matrix.json | 2 +- docs/get-started/prerequisites.mdx | 9 +- docs/get-started/windows-preparation.mdx | 14 +++ docs/index.yml | 12 +++ docs/manage-sandboxes/lifecycle.mdx | 1 + docs/reference/host-files-and-state.mdx | 50 +++++++++++ docs/reference/platform-support.mdx | 2 +- docs/reference/troubleshooting.mdx | 100 ++++++++++++++++++++- docs/resources/agent-install-readiness.mdx | 42 +++++++++ docs/resources/agent-skills.mdx | 1 + 11 files changed, 229 insertions(+), 6 deletions(-) create mode 100644 docs/reference/host-files-and-state.mdx create mode 100644 docs/resources/agent-install-readiness.mdx diff --git a/AGENTS.md b/AGENTS.md index afdc5a8c2a4..9df5684d14c 100644 --- 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 ` 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 index 69823f9b65b..da84d3ae0e8 100644 --- 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 index 3d83e382c73..9ed00429729 100644 --- 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 +``` 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 index ada37af72f1..475b931d7e9 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -186,4 +186,18 @@ 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 policy does not allow automated terminal execution, ask the assistant to create a local `.bat` or `.ps1` fallback file and explain exactly what it runs before you execute it. +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. +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 index 4df68ed4499..460fe303066 100644 --- 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 @@ -181,6 +184,9 @@ navigation: - page: "AI Agent Docs" path: _build/agent-variants/resources/agent-skills.openclaw.generated.mdx slug: agent-skills + - page: "Install Readiness" + path: _build/agent-variants/resources/agent-install-readiness.openclaw.generated.mdx + slug: agent-install-readiness - link: "Community Examples" href: https://github.com/NVIDIA/nemoclaw-community - link: "Discord" @@ -320,6 +326,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 @@ -333,6 +342,9 @@ navigation: - page: "AI Agent Docs" path: _build/agent-variants/resources/agent-skills.hermes.generated.mdx slug: agent-skills + - page: "Install Readiness" + path: _build/agent-variants/resources/agent-install-readiness.hermes.generated.mdx + slug: agent-install-readiness - link: "Community Examples" href: https://github.com/NVIDIA/nemoclaw-community - link: "Report Vulnerabilities" diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 814c2a64a10..fee9568c260 100644 --- 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. diff --git a/docs/reference/host-files-and-state.mdx b/docs/reference/host-files-and-state.mdx new file mode 100644 index 00000000000..f5ff4e21694 --- /dev/null +++ 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. + + +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. + + +## 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-nemoclaw). diff --git a/docs/reference/platform-support.mdx b/docs/reference/platform-support.mdx index 4596529e4d2..1b9f163fe68 100644 --- 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 index 81e4425e073..6d03b83cc54 100644 --- 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,55 @@ 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, copy the versioned `uninstall.sh` URL that it prints, review it, run it, and then retry the installer: + +```bash +curl -fsSL | bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + ## Runtime + + +### 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. + + +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. + + +If the host rebooted or the OpenShell gateway is down, first run: + +```bash +$$nemoclaw 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 recover` only for the in-sandbox OpenClaw gateway and host forwards. +Use `$$nemoclaw gateway restart` when you intentionally need the in-sandbox gateway to reload supported runtime configuration. + + + ### Reconnect after a host reboot After a host reboot, the container runtime, OpenShell gateway, and sandbox may not be running. @@ -778,8 +838,44 @@ $$nemoclaw 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=" + ``` + + If a container is listed, start it: + + ```bash + docker start + ``` + +1. Run status recovery from the host. + + ```bash + $$nemoclaw 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=` 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 recover + ``` + +1. Rebuild only if the sandbox cannot be restarted or status still cannot recover it while the local registry entry exists: + + ```bash + $$nemoclaw 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 destroy` to remove the stale local entry, then run `$$nemoclaw onboard`. ### Sandbox is registered locally but missing from the gateway diff --git a/docs/resources/agent-install-readiness.mdx b/docs/resources/agent-install-readiness.mdx new file mode 100644 index 00000000000..87c35f2a776 --- /dev/null +++ b/docs/resources/agent-install-readiness.mdx @@ -0,0 +1,42 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Validate Agent-Supported Install Readiness" +sidebar-title: "Install Readiness" +description: "Checklist for validating that AI coding agents can guide users through NemoClaw installation safely." +description-agent: "Defines a validation checklist for agent-supported NemoClaw installation. Use when proving the starter prompt, docs-routing skill, missing-skill recovery, consent gates, credential handling, and completion evidence." +keywords: ["nemoclaw agent install validation", "nemoclaw starter prompt readiness", "agent-supported install"] +content: + type: "reference" +--- + +Use this checklist when validating whether the agent-supported install path is ready for non-technical users. +The goal is to prove that an AI coding agent can use NemoClaw docs, ask for consent, avoid unsafe credential handling, and reach a concrete completion signal. + +## Workflows to Compare + +Validate both paths: + +- **Baseline docs path.** The agent starts from the published docs without the copied starter prompt. +- **Starter prompt path.** The agent starts from the copied prompt and uses the Markdown docs, docs MCP server, or local `nemoclaw-user-guide` skill when available. + +Record the operating system, coding agent, selected NemoClaw agent, inference provider, and whether Docker or another container runtime was already running. + +## Required Scenarios + +| Scenario | What to verify | +|---|---| +| Skills already available | The agent discovers NemoClaw guidance, chooses the correct OpenClaw or Hermes docs variant, and does not mix agent-specific commands. | +| Skills missing | The agent uses `llms.txt`, Markdown docs, or MCP search instead of guessing from memory. | +| Stale skill or stale docs | The agent refreshes from canonical docs before running install or recovery commands. | +| Privileged or destructive setup | The agent asks before installing software, changing Docker or WSL settings, uninstalling, rebuilding, or destroying state. | +| Credential setup | The agent never asks the user to paste secrets into chat and keeps real values in local prompts, local process environment, or approved app prompts. | +| Completion evidence | The agent finishes with a concrete signal such as `$$nemoclaw list`, `$$nemoclaw status`, dashboard URL, first-prompt instructions, or a clear blocked-state report. | + +## Pass Criteria + +The install path is ready only when every required scenario has evidence. +Evidence can be a transcript excerpt, a scripted smoke result, or a reviewer checklist entry. +Store evidence in the PR, issue, or release validation record that requested the readiness check. + +If a run cannot complete because of host policy, missing Docker, unavailable credentials, or an agent terminal restriction, record the exact blocked state and the documented recovery path the agent offered. diff --git a/docs/resources/agent-skills.mdx b/docs/resources/agent-skills.mdx index 4a1ec7f9431..faa8167fe87 100644 --- a/docs/resources/agent-skills.mdx +++ b/docs/resources/agent-skills.mdx @@ -20,6 +20,7 @@ Use this page when you want your agent to help with installation, inference conf The fastest path is to copy the starter prompt from the NemoClaw home page and paste it into your local coding agent. The prompt tells the agent to use the Markdown docs, ask one question at a time, run commands only with permission, and handle credentials safely. +For validation criteria that maintainers can use to prove this flow, refer to [Validate Agent-Supported Install Readiness](agent-install-readiness). From 8e9477c357ae6af121ae43ed8d898b4e442d9e8d Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 2 Jul 2026 15:44:54 -0700 Subject: [PATCH 2/3] docs: drop install readiness scope 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 --- docs/index.yml | 6 ---- docs/reference/host-files-and-state.mdx | 2 +- docs/resources/agent-install-readiness.mdx | 42 ---------------------- docs/resources/agent-skills.mdx | 1 - 4 files changed, 1 insertion(+), 50 deletions(-) delete mode 100644 docs/resources/agent-install-readiness.mdx diff --git a/docs/index.yml b/docs/index.yml index 460fe303066..8df00650280 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -184,9 +184,6 @@ navigation: - page: "AI Agent Docs" path: _build/agent-variants/resources/agent-skills.openclaw.generated.mdx slug: agent-skills - - page: "Install Readiness" - path: _build/agent-variants/resources/agent-install-readiness.openclaw.generated.mdx - slug: agent-install-readiness - link: "Community Examples" href: https://github.com/NVIDIA/nemoclaw-community - link: "Discord" @@ -342,9 +339,6 @@ navigation: - page: "AI Agent Docs" path: _build/agent-variants/resources/agent-skills.hermes.generated.mdx slug: agent-skills - - page: "Install Readiness" - path: _build/agent-variants/resources/agent-install-readiness.hermes.generated.mdx - slug: agent-install-readiness - link: "Community Examples" href: https://github.com/NVIDIA/nemoclaw-community - link: "Report Vulnerabilities" diff --git a/docs/reference/host-files-and-state.mdx b/docs/reference/host-files-and-state.mdx index f5ff4e21694..b40a4b9f7ea 100644 --- a/docs/reference/host-files-and-state.mdx +++ b/docs/reference/host-files-and-state.mdx @@ -47,4 +47,4 @@ 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-nemoclaw). +For operational uninstall steps, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle#uninstall). diff --git a/docs/resources/agent-install-readiness.mdx b/docs/resources/agent-install-readiness.mdx deleted file mode 100644 index 87c35f2a776..00000000000 --- a/docs/resources/agent-install-readiness.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Validate Agent-Supported Install Readiness" -sidebar-title: "Install Readiness" -description: "Checklist for validating that AI coding agents can guide users through NemoClaw installation safely." -description-agent: "Defines a validation checklist for agent-supported NemoClaw installation. Use when proving the starter prompt, docs-routing skill, missing-skill recovery, consent gates, credential handling, and completion evidence." -keywords: ["nemoclaw agent install validation", "nemoclaw starter prompt readiness", "agent-supported install"] -content: - type: "reference" ---- - -Use this checklist when validating whether the agent-supported install path is ready for non-technical users. -The goal is to prove that an AI coding agent can use NemoClaw docs, ask for consent, avoid unsafe credential handling, and reach a concrete completion signal. - -## Workflows to Compare - -Validate both paths: - -- **Baseline docs path.** The agent starts from the published docs without the copied starter prompt. -- **Starter prompt path.** The agent starts from the copied prompt and uses the Markdown docs, docs MCP server, or local `nemoclaw-user-guide` skill when available. - -Record the operating system, coding agent, selected NemoClaw agent, inference provider, and whether Docker or another container runtime was already running. - -## Required Scenarios - -| Scenario | What to verify | -|---|---| -| Skills already available | The agent discovers NemoClaw guidance, chooses the correct OpenClaw or Hermes docs variant, and does not mix agent-specific commands. | -| Skills missing | The agent uses `llms.txt`, Markdown docs, or MCP search instead of guessing from memory. | -| Stale skill or stale docs | The agent refreshes from canonical docs before running install or recovery commands. | -| Privileged or destructive setup | The agent asks before installing software, changing Docker or WSL settings, uninstalling, rebuilding, or destroying state. | -| Credential setup | The agent never asks the user to paste secrets into chat and keeps real values in local prompts, local process environment, or approved app prompts. | -| Completion evidence | The agent finishes with a concrete signal such as `$$nemoclaw list`, `$$nemoclaw status`, dashboard URL, first-prompt instructions, or a clear blocked-state report. | - -## Pass Criteria - -The install path is ready only when every required scenario has evidence. -Evidence can be a transcript excerpt, a scripted smoke result, or a reviewer checklist entry. -Store evidence in the PR, issue, or release validation record that requested the readiness check. - -If a run cannot complete because of host policy, missing Docker, unavailable credentials, or an agent terminal restriction, record the exact blocked state and the documented recovery path the agent offered. diff --git a/docs/resources/agent-skills.mdx b/docs/resources/agent-skills.mdx index faa8167fe87..4a1ec7f9431 100644 --- a/docs/resources/agent-skills.mdx +++ b/docs/resources/agent-skills.mdx @@ -20,7 +20,6 @@ Use this page when you want your agent to help with installation, inference conf The fastest path is to copy the starter prompt from the NemoClaw home page and paste it into your local coding agent. The prompt tells the agent to use the Markdown docs, ask one question at a time, run commands only with permission, and handle credentials safely. -For validation criteria that maintainers can use to prove this flow, refer to [Validate Agent-Supported Install Readiness](agent-install-readiness). From b7af08ffbc4a2296c8bf16b899e4ae920278a94a Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 2 Jul 2026 16:00:03 -0700 Subject: [PATCH 3/3] docs: clarify fallback trust boundaries 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 --- docs/get-started/windows-preparation.mdx | 4 +++- docs/reference/troubleshooting.mdx | 6 ++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index 475b931d7e9..555301b84ac 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -193,11 +193,13 @@ 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 policy does not allow automated terminal execution, ask the assistant to create a local `.bat` or `.ps1` fallback file and explain exactly what it runs before you execute it. +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/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 6d03b83cc54..9ccfbff8176 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -628,10 +628,12 @@ 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, copy the versioned `uninstall.sh` URL that it prints, review it, run it, and then retry the installer: +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 -fsSL | bash +curl -fsSLo uninstall.sh +less uninstall.sh +bash uninstall.sh --yes curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ```