[codex] add first-run onboarding usage notice

bin/config/onboard-notice.json

@@ -0,0 +1,8 @@
+{
+  "version": "2026-04-01",
+  "title": "Usage Notice",
+  "summary": "NemoClaw can provision local or cloud resources and retrieve external materials that may be governed by separate terms, conditions, and licenses.",
+  "details": "Review the full usage notice and disclaimer before continuing:",
+  "url": "https://docs.nvidia.com/nemoclaw/latest/reference/usage-notice.html",
+  "prompt": "Press Enter to continue onboarding: "
+}

bin/lib/onboard-notice.js

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const DEFAULT_NOTICE_CONFIG_PATH = path.join(__dirname, "..", "config", "onboard-notice.json");
+
+function getOnboardNoticeStatePath() {
+  const home = process.env.HOME || os.homedir() || "/tmp";
+  return (
+    process.env.NEMOCLAW_ONBOARD_NOTICE_STATE || path.join(home, ".nemoclaw", "onboard-notice.json")
+  );
+}
+
+function getOnboardNoticeConfigPath() {
+  return process.env.NEMOCLAW_ONBOARD_NOTICE_CONFIG || DEFAULT_NOTICE_CONFIG_PATH;
+}
+
+function validateNoticeConfig(config, sourcePath) {
+  const requiredFields = ["version", "title", "summary", "details", "url", "prompt"];
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`Invalid onboard notice config: ${sourcePath}`);
+  }
+  for (const field of requiredFields) {
+    if (typeof config[field] !== "string" || config[field].trim().length === 0) {
+      throw new Error(`Invalid onboard notice config field '${field}': ${sourcePath}`);
+    }
+  }
+  return {
+    version: config.version.trim(),
+    title: config.title.trim(),
+    summary: config.summary.trim(),
+    details: config.details.trim(),
+    url: config.url.trim(),
+    prompt: config.prompt,
+  };
+}
+
+function loadOnboardNoticeConfig(configPath = getOnboardNoticeConfigPath()) {
+  const raw = fs.readFileSync(configPath, "utf-8");
+  return validateNoticeConfig(JSON.parse(raw), configPath);
+}
+
+function loadOnboardNoticeState(statePath = getOnboardNoticeStatePath()) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(statePath, "utf-8"));
+    return {
+      lastSeenVersion:
+        typeof raw?.lastSeenVersion === "string" && raw.lastSeenVersion.length > 0
+          ? raw.lastSeenVersion
+          : null,
+      lastSeenAt:
+        typeof raw?.lastSeenAt === "string" && raw.lastSeenAt.length > 0 ? raw.lastSeenAt : null,
+    };
+  } catch {
+    return { lastSeenVersion: null, lastSeenAt: null };
+  }
+}
+
+function shouldShowOnboardNotice(config, state = loadOnboardNoticeState()) {
+  return !config || state.lastSeenVersion !== config.version;
+}
+
+function saveOnboardNoticeState(version, statePath = getOnboardNoticeStatePath()) {
+  const dir = path.dirname(statePath);
+  const tmpPath = path.join(
+    dir,
+    `.onboard-notice.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`,
+  );
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const payload = JSON.stringify(
+    {
+      lastSeenVersion: version,
+      lastSeenAt: new Date().toISOString(),
+    },
+    null,
+    2,
+  );
+  fs.writeFileSync(tmpPath, payload, { mode: 0o600 });
+  fs.renameSync(tmpPath, statePath);
+}
+
+function renderOnboardNoticeLines(config) {
+  return [
+    "",
+    `  ${config.title}`,
+    `  ${"─".repeat(config.title.length)}`,
+    `  ${config.summary}`,
+    `  ${config.details}`,
+    `    ${config.url}`,
+  ];
+}
+
+async function showOnboardNoticeIfNeeded(options = {}) {
+  const config = loadOnboardNoticeConfig(options.configPath);
+  const statePath = options.statePath || getOnboardNoticeStatePath();
+  const state = loadOnboardNoticeState(statePath);
+  if (!shouldShowOnboardNotice(config, state)) {
+    return { shown: false, version: config.version };
+  }
+
+  const writeLine =
+    options.writeLine ||
+    ((line) => {
+      process.stderr.write(`${line}\n`);
+    });
+
+  for (const line of renderOnboardNoticeLines(config)) {
+    writeLine(line);
+  }
+
+  if (options.nonInteractive) {
+    writeLine("  [non-interactive] Continuing after logging the usage notice.");
+  } else {
+    const promptFn = options.promptFn;
+    if (typeof promptFn !== "function") {
+      throw new Error("Interactive onboard notice requires a prompt function.");
+    }
+    await promptFn(`  ${config.prompt}`);
+  }
+
+  try {
+    saveOnboardNoticeState(config.version, statePath);
+  } catch (error) {
+    writeLine(
+      `  Warning: could not persist usage notice state at ${statePath}: ${error?.message || String(error)}`,
+    );
+  }
+
+  return { shown: true, version: config.version };
+}
+
+module.exports = {
+  DEFAULT_NOTICE_CONFIG_PATH,
+  getOnboardNoticeConfigPath,
+  getOnboardNoticeStatePath,
+  loadOnboardNoticeConfig,
+  loadOnboardNoticeState,
+  renderOnboardNoticeLines,
+  saveOnboardNoticeState,
+  shouldShowOnboardNotice,
+  showOnboardNoticeIfNeeded,
+  validateNoticeConfig,
+};

bin/lib/onboard.js

@@ -43,6 +43,7 @@ const {
 } = require("./credentials");
 const registry = require("./registry");
 const nim = require("./nim");
+const { showOnboardNoticeIfNeeded } = require("./onboard-notice");
 const onboardSession = require("./onboard-session");
 const policies = require("./policies");
 const { checkPortAvailable, ensureSwap, getMemoryInfo } = require("./preflight");
@@ -3784,6 +3785,11 @@ async function onboard(opts = {}) {
       onboardSession.markStepComplete("preflight");
     }
 
+    await showOnboardNoticeIfNeeded({
+      nonInteractive: isNonInteractive(),
+      promptFn: prompt,
+    });
+
     const gatewayStatus = runCaptureOpenshell(["status"], { ignoreError: true });
     const gatewayInfo = runCaptureOpenshell(["gateway", "info", "-g", GATEWAY_NAME], {
       ignoreError: true,

docs/index.md

@@ -280,6 +280,7 @@ Commands <reference/commands>
 Inference Profiles <reference/inference-profiles>
 Network Policies <reference/network-policies>
 Troubleshooting <reference/troubleshooting>
+Usage Notice <reference/usage-notice>
 ```
 
 ```{toctree}

docs/reference/commands.md

@@ -75,6 +75,8 @@ Uppercase letters are automatically lowercased.
 
 Before creating the gateway, the wizard runs preflight checks.
 On systems with cgroup v2 (Ubuntu 24.04, DGX Spark, WSL2), it verifies that Docker is configured with `"default-cgroupns-mode": "host"` and provides fix instructions if the setting is missing.
+On first-run onboarding, NemoClaw also shows a usage notice before provisioning starts.
+Set `NEMOCLAW_ONBOARD_NOTICE_CONFIG` to override the bundled JSON notice without changing the CLI code.
 
 ### `nemoclaw list`
 

docs/reference/usage-notice.md

@@ -0,0 +1,53 @@
+---
+title:
+  page: "NemoClaw Usage Notice"
+  nav: "Usage Notice"
+description: "Usage notice and disclaimer shown during NemoClaw onboarding."
+keywords: ["nemoclaw usage notice", "nemoclaw disclaimer", "nemoclaw terms"]
+topics: ["generative_ai", "ai_agents"]
+tags: ["openclaw", "openshell", "nemoclaw", "legal"]
+content:
+  type: reference
+  difficulty: technical_beginner
+  audience: ["developer", "engineer"]
+status: published
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# NemoClaw Usage Notice
+
+NemoClaw shows this notice during first-run onboarding before it provisions a sandbox.
+If the bundled notice version changes, NemoClaw shows the updated notice again on the next onboarding run.
+
+:::{warning}
+Notice and Disclaimer
+
+This software automatically retrieves, accesses or interacts with external materials.
+Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses.
+You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case.
+This software is provided "AS IS", without warranty of any kind.
+The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials.
+Use this software and the retrieved materials at your own risk.
+:::
+
+## Operator Override
+
+The bundled notice config lives in the CLI package.
+To supply a different notice without changing JavaScript code, set `NEMOCLAW_ONBOARD_NOTICE_CONFIG` to a JSON file that contains:
+
+- `version`
+- `title`
+- `summary`
+- `details`
+- `url`
+- `prompt`
+
+## Next Steps
+
+- Review the [`nemoclaw onboard` command reference](commands.md#nemoclaw-onboard) for the full onboarding flow and the `NEMOCLAW_ONBOARD_NOTICE_CONFIG` override.
+- Follow the [Quickstart guide](../get-started/quickstart.md) for installation and first-run onboarding.
+- Use the [Troubleshooting guide](troubleshooting.md) if onboarding or notice display fails on your host.

test/onboard-notice.test.js

@@ -0,0 +1,152 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_NOTICE_CONFIG_PATH,
+  loadOnboardNoticeConfig,
+  loadOnboardNoticeState,
+  renderOnboardNoticeLines,
+  saveOnboardNoticeState,
+  shouldShowOnboardNotice,
+  showOnboardNoticeIfNeeded,
+} from "../bin/lib/onboard-notice";
+
+describe("onboard notice", () => {
+  it("loads the bundled notice config", () => {
+    const config = loadOnboardNoticeConfig(DEFAULT_NOTICE_CONFIG_PATH);
+    expect(config.version).toBeTruthy();
+    expect(config.url).toBe("https://docs.nvidia.com/nemoclaw/latest/reference/usage-notice.html");
+    expect(renderOnboardNoticeLines(config).join("\n")).toContain(config.summary);
+  });
+
+  it("records the last seen notice version", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-state-"));
+    const statePath = path.join(tmpDir, "onboard-notice.json");
+
+    saveOnboardNoticeState("2026-04-01", statePath);
+
+    expect(loadOnboardNoticeState(statePath)).toMatchObject({
+      lastSeenVersion: "2026-04-01",
+    });
+  });
+
+  it("shows the notice once in non-interactive mode and writes to stderr", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-show-"));
+    const statePath = path.join(tmpDir, "onboard-notice.json");
+    const lines = [];
+
+    const first = await showOnboardNoticeIfNeeded({
+      nonInteractive: true,
+      statePath,
+      writeLine: (line) => lines.push(line),
+    });
+    const second = await showOnboardNoticeIfNeeded({
+      nonInteractive: true,
+      statePath,
+      writeLine: (line) => lines.push(line),
+    });
+
+    expect(first).toMatchObject({ shown: true });
+    expect(second).toMatchObject({ shown: false });
+    expect(lines.join("\n")).toContain("Usage Notice");
+    expect(lines.join("\n")).toContain(
+      "[non-interactive] Continuing after logging the usage notice.",
+    );
+  });
+
+  it("warns and continues when notice state cannot be persisted", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-unwritable-"));
+    const stateParent = path.join(tmpDir, "state");
+    const statePath = path.join(stateParent, "onboard-notice.json");
+    const lines = [];
+
+    fs.writeFileSync(stateParent, "not a directory");
+
+    const result = await showOnboardNoticeIfNeeded({
+      nonInteractive: true,
+      statePath,
+      writeLine: (line) => lines.push(line),
+    });
+
+    expect(result).toMatchObject({ shown: true });
+    expect(lines.join("\n")).toContain("Warning: could not persist usage notice state");
+    expect(lines.join("\n")).toContain(statePath);
+  });
+
+  it("re-shows the notice when the configured version changes", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-version-"));
+    const statePath = path.join(tmpDir, "onboard-notice.json");
+    const configPath = path.join(tmpDir, "notice.json");
+
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify({
+        version: "2026-04-01",
+        title: "Usage Notice",
+        summary: "First version.",
+        details: "Review before continuing:",
+        url: "https://example.com/notice",
+        prompt: "Continue: ",
+      }),
+    );
+    await showOnboardNoticeIfNeeded({
+      nonInteractive: true,
+      statePath,
+      configPath,
+      writeLine: () => {},
+    });
+
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify({
+        version: "2026-05-01",
+        title: "Usage Notice",
+        summary: "Updated version.",
+        details: "Review before continuing:",
+        url: "https://example.com/notice",
+        prompt: "Continue: ",
+      }),
+    );
+
+    const shown = await showOnboardNoticeIfNeeded({
+      nonInteractive: true,
+      statePath,
+      configPath,
+      writeLine: () => {},
+    });
+
+    expect(shown).toMatchObject({ shown: true, version: "2026-05-01" });
+  });
+
+  it("blocks in interactive mode until the user acknowledges the notice", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-ack-"));
+    const statePath = path.join(tmpDir, "onboard-notice.json");
+    const prompts = [];
+
+    const result = await showOnboardNoticeIfNeeded({
+      nonInteractive: false,
+      statePath,
+      promptFn: async (question) => {
+        prompts.push(question);
+        return "";
+      },
+      writeLine: () => {},
+    });
+
+    expect(result).toMatchObject({ shown: true });
+    expect(prompts).toEqual(["  Press Enter to continue onboarding: "]);
+  });
+
+  it("tracks whether the current notice version still needs to be shown", () => {
+    const config = loadOnboardNoticeConfig(DEFAULT_NOTICE_CONFIG_PATH);
+    expect(shouldShowOnboardNotice(config, { lastSeenVersion: null, lastSeenAt: null })).toBe(true);
+    expect(
+      shouldShowOnboardNotice(config, { lastSeenVersion: config.version, lastSeenAt: null }),
+    ).toBe(false);
+  });
+});