diff --git a/.agents/skills/nemoclaw-overview/references/how-it-works.md b/.agents/skills/nemoclaw-overview/references/how-it-works.md
index 89d1cd133..42c6d0004 100644
--- a/.agents/skills/nemoclaw-overview/references/how-it-works.md
+++ b/.agents/skills/nemoclaw-overview/references/how-it-works.md
@@ -70,9 +70,9 @@ Respect CLI boundaries
 Supply chain safety
 : Blueprint artifacts are immutable, versioned, and digest-verified before execution.
 
-OpenShell-native for new installs
-: For users without an existing OpenClaw installation, NemoClaw recommends `openshell sandbox create` directly
-  rather than forcing a plugin-driven bootstrap.
+OpenShell-backed lifecycle
+: NemoClaw orchestrates OpenShell resources under the hood, but `nemoclaw onboard`
+  is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes.
 
 Reproducible setup
 : Running setup again recreates the sandbox from the same blueprint and policy definitions.
diff --git a/.agents/skills/nemoclaw-reference/references/commands.md b/.agents/skills/nemoclaw-reference/references/commands.md
index 76a0831f0..0420910f3 100644
--- a/.agents/skills/nemoclaw-reference/references/commands.md
+++ b/.agents/skills/nemoclaw-reference/references/commands.md
@@ -44,6 +44,9 @@ Use this command for new installs and for recreating a sandbox after changes to
 $ nemoclaw onboard [--non-interactive] [--resume] [--from <Dockerfile>]
 ```
 
+> **Warning:** For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.
+> Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`.
+
 The wizard prompts for a provider first, then collects the provider credential if needed.
 Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints.
 Credentials are stored in `~/.nemoclaw/credentials.json`.
diff --git a/README.md b/README.md
index 0451666a7..9be810f9b 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,11 @@ The sandbox image is approximately 2.4 GB compressed. During image push, the Doc
 | Container runtime | Supported runtime installed and running |
 | [OpenShell](https://github.com/NVIDIA/OpenShell) | Installed |
 
+#### OpenShell Lifecycle
+
+For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.
+Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`.
+
 #### Container Runtimes
 
 | Platform | Supported runtimes | Notes |
diff --git a/docs/about/how-it-works.md b/docs/about/how-it-works.md
index 602f4a28e..555e85deb 100644
--- a/docs/about/how-it-works.md
+++ b/docs/about/how-it-works.md
@@ -92,9 +92,9 @@ Respect CLI boundaries
 Supply chain safety
 : Blueprint artifacts are immutable, versioned, and digest-verified before execution.
 
-OpenShell-native for new installs
-: For users without an existing OpenClaw installation, NemoClaw recommends `openshell sandbox create` directly
-  rather than forcing a plugin-driven bootstrap.
+OpenShell-backed lifecycle
+: NemoClaw orchestrates OpenShell resources under the hood, but `nemoclaw onboard`
+  is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes.
 
 Reproducible setup
 : Running setup again recreates the sandbox from the same blueprint and policy definitions.
diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
index 5afded6d9..0102058f0 100644
--- a/docs/get-started/quickstart.md
+++ b/docs/get-started/quickstart.md
@@ -55,6 +55,11 @@ The sandbox image is approximately 2.4 GB compressed. During image push, the Doc
 | Container runtime | Supported runtime installed and running |
 | [OpenShell](https://github.com/NVIDIA/OpenShell) | Installed |
 
+:::{warning} OpenShell lifecycle
+For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.
+Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`.
+:::
+
 ### Container Runtimes
 
 | Platform | Supported runtimes | Notes |
diff --git a/docs/reference/commands.md b/docs/reference/commands.md
index 19fc34f76..4f2c39dec 100644
--- a/docs/reference/commands.md
+++ b/docs/reference/commands.md
@@ -66,6 +66,11 @@ Use this command for new installs and for recreating a sandbox after changes to
 $ nemoclaw onboard [--non-interactive] [--resume] [--from <Dockerfile>]
 ```
 
+:::{warning}
+For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.
+Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`.
+:::
+
 The wizard prompts for a provider first, then collects the provider credential if needed.
 Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints.
 Credentials are stored in `~/.nemoclaw/credentials.json`.