From fbea648e8ba63f479dfcdf08d97c93cd1399c6f8 Mon Sep 17 00:00:00 2001 From: 13ernkastel Date: Wed, 1 Apr 2026 11:15:20 +0800 Subject: [PATCH 1/3] add onboarding usage notice --- bin/config/onboard-notice.json | 8 ++ bin/lib/onboard-notice.js | 137 +++++++++++++++++++++++++++++++++ bin/lib/onboard.js | 6 ++ docs/index.md | 1 + docs/reference/commands.md | 2 + docs/reference/usage-notice.md | 47 +++++++++++ test/onboard-notice.test.js | 129 +++++++++++++++++++++++++++++++ test/onboard.test.js | 11 +++ 8 files changed, 341 insertions(+) create mode 100644 bin/config/onboard-notice.json create mode 100644 bin/lib/onboard-notice.js create mode 100644 docs/reference/usage-notice.md create mode 100644 test/onboard-notice.test.js diff --git a/bin/config/onboard-notice.json b/bin/config/onboard-notice.json new file mode 100644 index 000000000..a8a894163 --- /dev/null +++ b/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: " +} diff --git a/bin/lib/onboard-notice.js b/bin/lib/onboard-notice.js new file mode 100644 index 000000000..3f13441df --- /dev/null +++ b/bin/lib/onboard-notice.js @@ -0,0 +1,137 @@ +// 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}`); + } + + saveOnboardNoticeState(config.version, statePath); + return { shown: true, version: config.version }; +} + +module.exports = { + DEFAULT_NOTICE_CONFIG_PATH, + getOnboardNoticeConfigPath, + getOnboardNoticeStatePath, + loadOnboardNoticeConfig, + loadOnboardNoticeState, + renderOnboardNoticeLines, + saveOnboardNoticeState, + shouldShowOnboardNotice, + showOnboardNoticeIfNeeded, + validateNoticeConfig, +}; diff --git a/bin/lib/onboard.js b/bin/lib/onboard.js index 25fd2fb5c..ccd158732 100644 --- a/bin/lib/onboard.js +++ b/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, diff --git a/docs/index.md b/docs/index.md index b95e88a1a..945f2f2f9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -280,6 +280,7 @@ Commands Inference Profiles Network Policies Troubleshooting +Usage Notice ``` ```{toctree} diff --git a/docs/reference/commands.md b/docs/reference/commands.md index f83f7796f..4383f9fcf 100644 --- a/docs/reference/commands.md +++ b/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` diff --git a/docs/reference/usage-notice.md b/docs/reference/usage-notice.md new file mode 100644 index 000000000..25179f4ba --- /dev/null +++ b/docs/reference/usage-notice.md @@ -0,0 +1,47 @@ +--- +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 +--- + + + +# 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. + +```{admonition} Notice and Disclaimer +:class: warning + +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` diff --git a/test/onboard-notice.test.js b/test/onboard-notice.test.js new file mode 100644 index 000000000..ac92aaaf5 --- /dev/null +++ b/test/onboard-notice.test.js @@ -0,0 +1,129 @@ +// 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("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 })).toBe(true); + expect(shouldShowOnboardNotice(config, { lastSeenVersion: config.version })).toBe(false); + }); +}); diff --git a/test/onboard.test.js b/test/onboard.test.js index 20f9a5c61..4b66ddcb2 100644 --- a/test/onboard.test.js +++ b/test/onboard.test.js @@ -1823,4 +1823,15 @@ const { setupInference } = require(${onboardPath}); assert.match(fnBody, /isNonInteractive\(\)/); assert.match(fnBody, /process\.exit\(1\)/); }); + + it("shows the onboarding notice after preflight completes", () => { + const source = fs.readFileSync( + path.join(import.meta.dirname, "..", "bin", "lib", "onboard.js"), + "utf-8", + ); + assert.match( + source, + /onboardSession\.markStepComplete\("preflight"\);[\s\S]*?showOnboardNoticeIfNeeded\(\{/, + ); + }); }); From bda9238ff9249b4e1140b56f77e22468b3c46e3b Mon Sep 17 00:00:00 2001 From: 13ernkastel Date: Wed, 1 Apr 2026 11:41:58 +0800 Subject: [PATCH 2/3] fix: harden onboarding notice persistence --- bin/lib/onboard-notice.js | 13 +++++++++++-- docs/reference/usage-notice.md | 12 +++++++++--- test/onboard-notice.test.js | 29 ++++++++++++++++++++++++++--- 3 files changed, 46 insertions(+), 8 deletions(-) diff --git a/bin/lib/onboard-notice.js b/bin/lib/onboard-notice.js index 3f13441df..c15806369 100644 --- a/bin/lib/onboard-notice.js +++ b/bin/lib/onboard-notice.js @@ -9,7 +9,9 @@ const DEFAULT_NOTICE_CONFIG_PATH = path.join(__dirname, "..", "config", "onboard function getOnboardNoticeStatePath() { const home = process.env.HOME || os.homedir() || "/tmp"; - return process.env.NEMOCLAW_ONBOARD_NOTICE_STATE || path.join(home, ".nemoclaw", "onboard-notice.json"); + return ( + process.env.NEMOCLAW_ONBOARD_NOTICE_STATE || path.join(home, ".nemoclaw", "onboard-notice.json") + ); } function getOnboardNoticeConfigPath() { @@ -119,7 +121,14 @@ async function showOnboardNoticeIfNeeded(options = {}) { await promptFn(` ${config.prompt}`); } - saveOnboardNoticeState(config.version, statePath); + 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 }; } diff --git a/docs/reference/usage-notice.md b/docs/reference/usage-notice.md index 25179f4ba..82fb5823c 100644 --- a/docs/reference/usage-notice.md +++ b/docs/reference/usage-notice.md @@ -23,8 +23,8 @@ status: published 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. -```{admonition} Notice and Disclaimer -:class: warning +:::{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. @@ -32,7 +32,7 @@ You are solely responsible for finding, reviewing and complying with all applica 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 @@ -45,3 +45,9 @@ To supply a different notice without changing JavaScript code, set `NEMOCLAW_ONB - `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. diff --git a/test/onboard-notice.test.js b/test/onboard-notice.test.js index ac92aaaf5..115841a18 100644 --- a/test/onboard-notice.test.js +++ b/test/onboard-notice.test.js @@ -54,7 +54,28 @@ describe("onboard notice", () => { 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."); + 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 () => { @@ -123,7 +144,9 @@ describe("onboard notice", () => { it("tracks whether the current notice version still needs to be shown", () => { const config = loadOnboardNoticeConfig(DEFAULT_NOTICE_CONFIG_PATH); - expect(shouldShowOnboardNotice(config, { lastSeenVersion: null })).toBe(true); - expect(shouldShowOnboardNotice(config, { lastSeenVersion: config.version })).toBe(false); + expect(shouldShowOnboardNotice(config, { lastSeenVersion: null, lastSeenAt: null })).toBe(true); + expect( + shouldShowOnboardNotice(config, { lastSeenVersion: config.version, lastSeenAt: null }), + ).toBe(false); }); }); From 54ab90abbc9404a5d0c1558586c60094a1dd4bd1 Mon Sep 17 00:00:00 2001 From: 13ernkastel Date: Thu, 2 Apr 2026 09:11:21 +0800 Subject: [PATCH 3/3] fix: clean up onboard notice temp files --- bin/lib/onboard-notice.js | 13 +++++++++++-- test/onboard-notice.test.js | 19 ++++++++++++++++++- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/bin/lib/onboard-notice.js b/bin/lib/onboard-notice.js index c15806369..839774c61 100644 --- a/bin/lib/onboard-notice.js +++ b/bin/lib/onboard-notice.js @@ -78,8 +78,17 @@ function saveOnboardNoticeState(version, statePath = getOnboardNoticeStatePath() null, 2, ); - fs.writeFileSync(tmpPath, payload, { mode: 0o600 }); - fs.renameSync(tmpPath, statePath); + try { + fs.writeFileSync(tmpPath, payload, { mode: 0o600 }); + fs.renameSync(tmpPath, statePath); + } catch (error) { + try { + fs.unlinkSync(tmpPath); + } catch { + // Best-effort cleanup; preserve the original write/rename error. + } + throw error; + } } function renderOnboardNoticeLines(config) { diff --git a/test/onboard-notice.test.js b/test/onboard-notice.test.js index 115841a18..c1c5c5db3 100644 --- a/test/onboard-notice.test.js +++ b/test/onboard-notice.test.js @@ -4,7 +4,7 @@ import fs from "node:fs"; import os from "node:os"; import path from "node:path"; -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import { DEFAULT_NOTICE_CONFIG_PATH, @@ -35,6 +35,23 @@ describe("onboard notice", () => { }); }); + it("cleans up the temp state file when the atomic rename fails", () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-onboard-notice-rename-")); + const statePath = path.join(tmpDir, "onboard-notice.json"); + const renameError = new Error("rename failed"); + const renameSpy = vi.spyOn(fs, "renameSync").mockImplementation(() => { + throw renameError; + }); + + try { + expect(() => saveOnboardNoticeState("2026-04-01", statePath)).toThrow(renameError); + expect(fs.existsSync(statePath)).toBe(false); + expect(fs.readdirSync(tmpDir)).toEqual([]); + } finally { + renameSpy.mockRestore(); + } + }); + 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");