docs: prepare v0.0.40 release docs (#3427)

## Summary
- Add v0.0.40 release notes and update docs version metadata.
- Document release-prep behavior changes around onboarding, local
inference, policy preset filtering, and config recovery.
- Refresh generated `nemoclaw-user-*` skills from the source docs.

## Source summary
- #3383 -> `docs/about/release-notes.md`, `docs/reference/commands.md`,
`docs/manage-sandboxes/lifecycle.md`: Reflect macOS Docker-driver
OpenShell gateway onboarding and upgrade behavior.
- #3378 -> `docs/about/release-notes.md`: Capture the Docker-driver
gateway TCP readiness fix and clearer startup failures.
- #3338 -> `docs/about/release-notes.md`,
`docs/inference/use-local-inference.md`: Reflect the Ollama auth proxy
token requirement on native API routes.
- #3420 -> `docs/about/release-notes.md`,
`docs/get-started/prerequisites.md`,
`docs/inference/use-local-inference.md`: Document the Linux Ollama
`zstd` preflight and sudo messaging.
- #3417 -> `docs/about/release-notes.md`,
`docs/inference/inference-options.md`,
`docs/inference/use-local-inference.md`: Reflect detected running vLLM
provider selection.
- #3223 -> `docs/about/release-notes.md`, `docs/reference/commands.md`,
`docs/reference/network-policies.md`, `docs/get-started/quickstart.md`:
Document agent-aware policy preset filtering.
- #3385 -> `docs/about/release-notes.md`: Capture the dashboard forward
TCP reachability check.
- #3160 -> `docs/about/release-notes.md`,
`docs/reference/troubleshooting.md`: Document empty `openclaw.json`
baseline recovery.
- #3367 -> `docs/about/release-notes.md`: Capture OpenClaw plugin
compatibility metadata.

## Test plan
- [x] `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix
nemoclaw-user`
- [x] `make docs`
- [x] `git diff --check`
- [x] Skip-term scan for `docs/.docs-skip` terms

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

# Release Notes v0.0.40

* **New Features**
* Sandbox configuration recovery when inference changes cause data loss
  * Policy presets now intelligently filter based on agent capabilities
  * Enhanced gateway health checks and upgrade reliability

* **Documentation**
* Improved local inference setup instructions with clearer dependency
requirements
  * Clarified vLLM experimental feature availability and prerequisites
  * Reorganized architecture documentation for enhanced clarity
  * Refined security and hardening guidance

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/3427)

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: miyoungc

.agents/skills/nemoclaw-user-configure-inference/SKILL.md

@@ -28,6 +28,9 @@ The onboard wizard detects Ollama automatically when it is installed or running
 If Ollama is installed but not running, NemoClaw starts it for you.
 On macOS and Linux, the wizard can also offer to install Ollama when it is not present.
 On WSL, the wizard can use, start, restart, or install Ollama on the Windows host through PowerShell interop.
+On Debian and Ubuntu, the native Linux install path checks for `zstd` before it runs the Ollama installer.
+If `zstd` is missing, NemoClaw installs it with `apt-get` and explains the sudo prompt before continuing.
+On non-apt Linux distributions, install `zstd` first, then rerun onboarding.
 
 Run the onboard wizard.
 

.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md

@@ -31,7 +31,7 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l
 | Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` |
 | Local Ollama | Caveated | Local Ollama API | Available when Ollama is installed or running on the host |
 | Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU |
-| Local vLLM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a server already running on `localhost:8000` |
+| Local vLLM | Experimental | Local OpenAI-compatible | Appears when a vLLM server is already running on `localhost:8000`; managed install/start requires `NEMOCLAW_EXPERIMENTAL=1` |
 <!-- provider-status:end -->
 
 ## Provider Options

.agents/skills/nemoclaw-user-configure-security/references/best-practices.md

@@ -230,21 +230,6 @@ For sensitive workloads, use a reviewed host-side immutability workflow after in
 | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. |
 | Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. |
 
-### Locking Config with Shields
-
-NemoClaw exposes the reviewed host-side immutability workflow through shields commands:
-
-| Command | Purpose |
-|---|---|
-| `nemoclaw <name> shields status` | Show whether the sandbox is in default mutable mode, locked mode, or temporarily unlocked mode. |
-| `nemoclaw <name> shields up` | Opt into lockdown for sensitive workloads by locking config and state entry points with root ownership, read-only modes, and the immutable flag where available. |
-| `nemoclaw <name> shields down --timeout 5m --reason "<reason>"` | Temporarily return a previously locked sandbox to the mutable default for maintenance, then auto-restore lockdown. |
-
-Run shields commands from the host.
-They use privileged OpenShell and Kubernetes paths that do not inherit the sandbox process's Landlock context.
-Landlock itself stays fixed at sandbox creation; `shields up` does not rewrite the Landlock policy.
-Instead, it layers DAC permissions and `chattr +i` over paths that the default Landlock policy intentionally leaves writable.
-
 ### Writable Paths
 
 The agent has read-write access to `/sandbox`, `/tmp`, and `/dev/null`.

.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md

@@ -91,8 +91,6 @@ The agent's home directory (`/sandbox`) is writable by default:
 This writable default is intentional.
 Seeing the sandbox user create files under `/sandbox` or `/sandbox/.openclaw` in a fresh sandbox does not mean Landlock failed.
 Landlock still enforces the fixed read-only system paths below.
-Use `nemoclaw <name> shields up` from the host to opt into config lockdown for sensitive workloads.
-That host-side command layers root ownership, read-only modes, and the immutable flag where available; it does not change the Landlock policy after sandbox creation.
 
 System paths remain read-only to prevent agents from:
 

.agents/skills/nemoclaw-user-get-started/SKILL.md

@@ -272,7 +272,7 @@ For example, Slack bot tokens must start with `xoxb-`.
 ### Choose Network Policy Presets
 
 After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply.
-The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search.
+The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search.
 Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm.
 
 The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference.
@@ -346,9 +346,4 @@ openclaw agent --agent main --local -m "hello" --session-id test
 
 ## Related Skills
 
-- `nemoclaw-user-manage-sandboxes` — Manage NemoClaw sandboxes (use the `nemoclaw-user-manage-sandboxes` skill) for port forwards, rebuilds, upgrades, and uninstall
-- `nemoclaw-user-configure-inference` — Switch inference providers (use the `nemoclaw-user-configure-inference` skill) to use a different model or endpoint
-- `nemoclaw-user-manage-policy` — Approve or deny network requests (use the `nemoclaw-user-manage-policy` skill) when the agent tries to reach external hosts
-- `nemoclaw-user-deploy-remote` — Deploy to a remote GPU instance (use the `nemoclaw-user-deploy-remote` skill) for always-on operation
-- `nemoclaw-user-monitor-sandbox` — Monitor sandbox activity (use the `nemoclaw-user-monitor-sandbox` skill) through the OpenShell TUI
-- `nemoclaw-user-reference` — Consult the troubleshooting guide (use the `nemoclaw-user-reference` skill) for common error messages and resolution steps
+- `nemoclaw-user-overview` — NemoClaw Overview (use the `nemoclaw-user-overview` skill) to learn what NemoClaw is and its capabilities

.agents/skills/nemoclaw-user-get-started/references/prerequisites.md

@@ -25,6 +25,8 @@ The sandbox image is approximately 2.4 GB compressed. During image push, the Doc
 
 On Linux, the installer can install Docker, start the Docker service, and add your user to the `docker` group.
 If the group change is not active in the current shell, the installer exits with `newgrp docker` guidance before it starts onboarding.
+If you choose the native Linux Ollama install path, the onboard wizard also requires `zstd` for Ollama archive extraction.
+On Debian and Ubuntu, NemoClaw installs `zstd` with `apt-get` if it is missing; on other Linux distributions, install `zstd` before onboarding.
 
 :::{warning} OpenShell Lifecycle
 For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.

.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md

@@ -5,7 +5,7 @@
 Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs Hermes instead of the default OpenClaw agent.
 The `nemohermes` command is an alias for `nemoclaw` with the Hermes agent pre-selected.
 
-> **Warning:** The Hermes agent option is experimental.
+> **Experimental Feature:** The Hermes agent option is experimental.
 > Interfaces, defaults, and supported features may change without notice, and it is not recommended for production use.
 
 Review the Prerequisites (use the `nemoclaw-user-get-started` skill) before starting.

.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md

@@ -184,6 +184,9 @@ When a new NemoClaw release becomes available, update the `nemoclaw` CLI on your
 
 Re-run the installer.
 Before it onboards anything, the installer calls `nemoclaw backup-all` (use the `nemoclaw-user-reference` skill) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net.
+If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path.
+The automatic path is offered only when the existing `nemoclaw` CLI supports `backup-all`; older installs must preserve sandbox state manually before retiring the gateway.
+For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all` and `openshell gateway destroy -g nemoclaw || openshell gateway destroy` before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`.
 
 ```console
 $ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash

.agents/skills/nemoclaw-user-overview/references/ecosystem.md

@@ -8,18 +8,8 @@ This page describes how the ecosystem is formed across projects, where NemoClaw
 
 ## How the Stack Fits Together
 
-Three pieces usually appear together in a NemoClaw deployment, each with a distinct scope:
-
-| Project | Scope |
-|---------|--------|
-| [OpenClaw](https://openclaw.ai) | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. |
-| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. |
-| NemoClaw | The NVIDIA reference stack that implements the definition above on the host: `nemoclaw` CLI and plugin, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so OpenClaw runs inside OpenShell in a documented, repeatable way. |
-
-NemoClaw sits above OpenShell in the operator workflow.
-It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw.
-Models and endpoints sit behind OpenShell's inference routing.
-NemoClaw onboarding wires provider choice into that routing.
+There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope.
+The following diagram shows how they fit together.
 
 ```mermaid
 flowchart TB
@@ -42,6 +32,19 @@ flowchart TB
     linkStyle 1 stroke:#76b900,stroke-width:2px
 ```
 
+NemoClaw sits above OpenShell in the operator workflow.
+It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw.
+Models and endpoints sit behind OpenShell's inference routing.
+NemoClaw onboarding wires provider choice into that routing.
+
+The following table shows the scope of each component in the stack.
+
+| Project | Scope |
+|---------|--------|
+| [OpenClaw](https://openclaw.ai) | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. |
+| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. |
+| NemoClaw | The NVIDIA reference stack that implements the definition above on the host: `nemoclaw` CLI and plugin, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so OpenClaw runs inside OpenShell in a documented, repeatable way. |
+
 ## NemoClaw Path versus OpenShell Path
 
 Both paths assume OpenShell can sandbox a workload.

.agents/skills/nemoclaw-user-overview/references/how-it-works.md

@@ -1,70 +1,47 @@
 <!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
-# How NemoClaw Works
+# NemoClaw Architecture Overview
 
-This page explains how NemoClaw operates, which parts run where, how the blueprint drives OpenShell, and how inference and policy attach to the sandbox.
+This page explains how NemoClaw runs OpenClaw inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy.
 
-## How the Pieces Connect
+NemoClaw does not replace OpenClaw or OpenShell.
+It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, plugin configuration, and state helpers.
+You can use that setup directly or adapt it for your own OpenShell integration.
 
-The `nemoclaw` CLI is the primary entrypoint for setting up and managing sandboxed OpenClaw agents.
-It delegates heavy lifting to a versioned blueprint, a Python artifact that orchestrates sandbox creation, policy application, and inference provider setup through the OpenShell CLI.
+## High-Level Flow
 
-Between your shell and the running sandbox, NemoClaw contributes these integration layers:
+NemoClaw keeps the user workflow on the host while OpenShell enforces the sandbox boundary.
+The gateway sits between NemoClaw control, the sandbox, inference providers, and external integrations.
+That placement lets NemoClaw configure the environment without giving the agent direct access to host credentials or uncontrolled network egress.
 
-| Layer | Role in the flow |
+```{figure} images/nemoclaw-highlevel-component-diagram.png
+:alt: NemoClaw High-Level Component Diagram
+:width: 100%
+:align: center
+
+NemoClaw High-Level Component Diagram
+```
+
+The diagram has the following components:
+
+| Component | Role in the flow |
 |-------|------------------|
-| Onboarding | `nemoclaw onboard` validates credentials, selects providers, and drives blueprint execution until the sandbox is ready. |
-| Blueprint | Supplies the hardened image definition, default policies, capability posture, and orchestration steps the runner applies through OpenShell. |
-| State management | Migrates agent state across machines with credential stripping and integrity checks. |
-| Channel messaging | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the agent. NemoClaw enables this through onboarding and blueprint wiring; delivery is not a separate NemoClaw host daemon. |
+| Users and operators | Start from the CLI, installer, dashboard, or an end-user channel. |
+| NemoClaw control | Collects configuration, runs onboarding, prepares the blueprint, and asks OpenShell to create or update resources. |
+| OpenShell gateway | Owns sandbox lifecycle, networking, policy enforcement, inference routing, and integration egress. |
+| NemoClaw sandbox | Runs OpenClaw with the NemoClaw plugin, the selected blueprint contents, and supporting tools. |
+| Inference | Receives model requests through the gateway, using NVIDIA endpoints, NIM, or compatible APIs. |
+| Integrations | Reach messaging services, MCP servers, GitHub, package indexes, or model hubs through gateway-managed egress. |
+| State and artifacts | Store configuration, credentials, logs, workspace files, policies, and transcripts outside the running agent process. |
 
 For repository layout, file paths, and deeper diagrams, see Architecture (use the `nemoclaw-user-reference` skill).
 
-```mermaid
-flowchart TB
-    subgraph Host
-        CMD["nemoclaw onboard"]
-        PLUGIN[nemoclaw plugin]
-        BLUEPRINT[blueprint runner]
-        CLI["openshell CLI sandbox · gateway · inference · policy"]
-
-        CMD --> PLUGIN
-        PLUGIN --> BLUEPRINT
-        BLUEPRINT --> CLI
-    end
-
-    subgraph Sandbox["OpenShell Sandbox"]
-        AGENT[OpenClaw agent]
-        INF[NVIDIA inference, routed]
-        NET[default network policy]
-        FS[filesystem isolation]
-
-        AGENT --- INF
-        AGENT --- NET
-        AGENT --- FS
-    end
-
-    PLUGIN --> AGENT
-
-    classDef nv fill:#76b900,stroke:#333,color:#fff
-    classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a
-    classDef nvDark fill:#333,stroke:#76b900,color:#fff
-
-    class CMD,PLUGIN,BLUEPRINT nvDark
-    class CLI nv
-    class AGENT nv
-    class INF,NET,FS nvLight
-
-    style Host fill:none,stroke:#76b900,stroke-width:2px,color:#1a1a1a
-    style Sandbox fill:#f5faed,stroke:#76b900,stroke-width:2px,color:#1a1a1a
-```
-
 ## Design Principles
 
 NemoClaw architecture follows the following principles.
 
 Thin plugin, versioned blueprint
-: The plugin stays small and stable. Orchestration logic lives in the blueprint and evolves on its own release cadence.
+: The sandbox plugin stays small and stable. Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence.
 
 Respect CLI boundaries
 : The `nemoclaw` CLI is the primary interface for sandbox management.
@@ -79,25 +56,26 @@ OpenShell-backed lifecycle
 Reproducible setup
 : Running setup again recreates the sandbox from the same blueprint and policy definitions.
 
-## Plugin and Blueprint
+## CLI, Plugin, and Blueprint
 
-NemoClaw is split into two parts:
+NemoClaw is split into three integration pieces:
 
-- The *plugin* is a TypeScript package that registers an inference provider and the `/nemoclaw` slash command inside the sandbox.
-  It handles user interaction and delegates orchestration work to the blueprint.
-- The *blueprint* is a versioned Python artifact that contains all the logic for creating sandboxes, applying policies, and configuring inference.
-  The plugin resolves, verifies, and executes the blueprint as a subprocess.
+- The *host CLI* runs onboarding, validates provider choices, stores configuration, and calls OpenShell commands for gateway, provider, sandbox, and policy operations.
+- The *plugin* is a TypeScript package that runs with OpenClaw inside the sandbox.
+  It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks.
+- The *blueprint* is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets.
+  The runner resolves and verifies the blueprint before applying it through OpenShell.
 
-This separation keeps the plugin small and stable while allowing the blueprint to evolve on its own release cadence.
+This separation keeps the sandbox plugin small while allowing host orchestration and blueprint contents to evolve on their own release cadence.
 
 ## Sandbox Creation
 
 When you run `nemoclaw onboard`, NemoClaw creates an OpenShell sandbox that runs OpenClaw in an isolated container.
-The blueprint orchestrates this process through the OpenShell CLI:
+The host CLI and blueprint runner orchestrate this process through the OpenShell CLI:
 
-1. The plugin downloads the blueprint artifact, checks version compatibility, and verifies the digest.
-2. The blueprint determines which OpenShell resources to create or update, such as the gateway, inference providers, sandbox, and network policy.
-3. The blueprint calls OpenShell CLI commands to create the sandbox and configure each resource.
+1. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest.
+2. The onboarding flow determines which OpenShell resources to create or update, such as the gateway, inference providers, sandbox, and network policy.
+3. The runner calls OpenShell CLI commands to create the sandbox and configure each resource.
 
 After the sandbox starts, the agent runs inside it with all network, filesystem, and inference controls in place.