docs: clarify OpenShell compatibility guidance

README.md

@@ -52,6 +52,15 @@ 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 Compatibility
+
+NemoClaw 0.1.0 was validated with OpenShell 0.0.7.
+During onboarding, NemoClaw derives the OpenShell gateway image from the installed `openshell` CLI version, so upgrading OpenShell independently can rebuild the sandbox with a different runtime layout than the current NemoClaw release expects.
+
+| NemoClaw | OpenShell | Notes |
+|----------|-----------|-------|
+| 0.1.0 | 0.0.7 | Use `nemoclaw onboard` to create or recreate NemoClaw-managed sandboxes. 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 re-onboard. |
+
 #### Container Runtimes
 
 | Platform | Supported runtimes | Notes |

bin/lib/onboard.js

@@ -519,6 +519,14 @@ function getStableGatewayImageRef(versionOutput = null) {
   return `ghcr.io/nvidia/openshell/cluster:${version}`;
 }
 
+function getOpenshellCompatibilityNotice(version = null) {
+  const suffix = version ? ` (${version})` : "";
+  return [
+    `  OpenShell compatibility: NemoClaw derives the gateway image from the installed openshell CLI${suffix}.`,
+    "  Use `nemoclaw onboard` to recreate NemoClaw-managed sandboxes, and avoid `openshell self-update`, `openshell gateway start --recreate`, or `openshell sandbox create` directly.",
+  ];
+}
+
 function getOpenshellBinary() {
   if (OPENSHELL_BIN) return OPENSHELL_BIN;
   const resolved = resolveOpenshell();
@@ -2148,6 +2156,9 @@ async function startGatewayWithOptions(_gpu, { exitOnFailure = true } = {}) {
   if (gatewayEnv.OPENSHELL_CLUSTER_IMAGE) {
     console.log(`  Using pinned OpenShell gateway image: ${gatewayEnv.OPENSHELL_CLUSTER_IMAGE}`);
   }
+  for (const line of getOpenshellCompatibilityNotice(gatewayEnv.IMAGE_TAG || null)) {
+    console.log(line);
+  }
 
   // Retry gateway start with exponential backoff. On some hosts (Horde VMs,
   // first-run environments) the embedded k3s needs more time than OpenShell's
@@ -4006,6 +4017,7 @@ module.exports = {
   getGatewayStartEnv,
   getGatewayReuseState,
   getSandboxInferenceConfig,
+  getOpenshellCompatibilityNotice,
   getInstalledOpenshellVersion,
   getRequestedModelHint,
   getRequestedProviderHint,

docs/about/how-it-works.md

@@ -91,9 +91,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.

docs/get-started/quickstart.md

@@ -53,6 +53,15 @@ 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 compatibility
+NemoClaw 0.1.0 was validated with OpenShell 0.0.7.
+During onboarding, NemoClaw derives the OpenShell gateway image from the installed `openshell` CLI version, so upgrading OpenShell independently can rebuild the sandbox with a different runtime layout than the current NemoClaw release expects.
+:::
+
+| NemoClaw | OpenShell | Notes |
+|----------|-----------|-------|
+| 0.1.0 | 0.0.7 | Use `nemoclaw onboard` to create or recreate NemoClaw-managed sandboxes. 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 re-onboard. |
+
 ### Container Runtimes
 
 | Platform | Supported runtimes | Notes |

docs/reference/commands.md

@@ -64,6 +64,11 @@ Use this command for new installs and for recreating a sandbox after changes to
 $ nemoclaw onboard
 ```
 
+:::{warning}
+For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox.
+NemoClaw derives the gateway image from the installed `openshell` CLI version, so `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` can replace the runtime with a different OpenShell release than NemoClaw 0.1.0 was validated against.
+:::
+
 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`.

test/onboard.test.js

@@ -14,6 +14,7 @@ import {
   getGatewayReuseState,
   getPortConflictServiceHints,
   getFutureShellPathHint,
+  getOpenshellCompatibilityNotice,
   getSandboxInferenceConfig,
   getInstalledOpenshellVersion,
   getRequestedModelHint,
@@ -254,6 +255,17 @@ describe("onboard helpers", () => {
     expect(getStableGatewayImageRef("bogus")).toBe(null);
   });
 
+  it("prints a compatibility note when the gateway version is pinned", () => {
+    expect(getOpenshellCompatibilityNotice("0.0.7")).toEqual([
+      "  OpenShell compatibility: NemoClaw derives the gateway image from the installed openshell CLI (0.0.7).",
+      "  Use `nemoclaw onboard` to recreate NemoClaw-managed sandboxes, and avoid `openshell self-update`, `openshell gateway start --recreate`, or `openshell sandbox create` directly.",
+    ]);
+    expect(getOpenshellCompatibilityNotice()).toEqual([
+      "  OpenShell compatibility: NemoClaw derives the gateway image from the installed openshell CLI.",
+      "  Use `nemoclaw onboard` to recreate NemoClaw-managed sandboxes, and avoid `openshell self-update`, `openshell gateway start --recreate`, or `openshell sandbox create` directly.",
+    ]);
+  });
+
   it("treats the gateway as healthy only when nemoclaw is running and connected", () => {
     expect(
       isGatewayHealthy(