refactor(cli): align public dispatch with oclif conventions

package.json

@@ -29,7 +29,7 @@
     "format:ts": "cd nemoclaw && npm run lint:fix && npm run format",
     "check:installer-hash": "bash scripts/check-installer-hash.sh",
     "typecheck": "tsc -p jsconfig.json",
-    "build:cli": "tsc -p tsconfig.src.json && if find nemoclaw-blueprint/scripts -name '*.ts' -print -quit | grep -q .; then tsc -p nemoclaw-blueprint/tsconfig.json; fi",
+    "build:cli": "tsc -p tsconfig.src.json && node dist/lib/cli/generate-oclif-metadata-manifest.js && if find nemoclaw-blueprint/scripts -name '*.ts' -print -quit | grep -q .; then tsc -p nemoclaw-blueprint/tsconfig.json; fi",
     "typecheck:cli": "tsc -p tsconfig.cli.json",
     "validate:configs": "tsx scripts/validate-configs.ts",
     "type-safety:hotspots": "tsx scripts/type-safety-hotspots.ts",

scripts/checks/layer-import-boundaries.ts

@@ -21,7 +21,7 @@ type ImportRef = {
 };
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-const SRC_LIB_ROOT = path.join(REPO_ROOT, "src", "lib");
+const SRC_ROOT = path.join(REPO_ROOT, "src");
 const SKIP_DIRS = new Set([".git", "coverage", "dist", "node_modules"]);
 
 function toRepoPath(absPath: string): string {
@@ -119,18 +119,14 @@ function isAdapterFile(repoPath: string): boolean {
 }
 
 function isCommandFile(repoPath: string): boolean {
-  return repoPath.startsWith("src/lib/commands/");
+  return repoPath.startsWith("src/commands/");
 }
 
 function isActionFile(repoPath: string): boolean {
   if (repoPath.startsWith("src/lib/actions/")) return true;
   return /(^|\/)[^/]+-actions?\.ts$/.test(repoPath);
 }
 
-function isGeneratedOrRegistryCommandFile(repoPath: string): boolean {
-  return repoPath.endsWith("/common.ts");
-}
-
 function importTargetsForbiddenLayer(
   fromAbsPath: string,
   ref: ImportRef,
@@ -181,7 +177,7 @@ function checkDomainFile(absPath: string, repoPath: string, violations: Violatio
     const target = importTargetsForbiddenLayer(
       absPath,
       ref,
-      ["src/lib/adapters/", "src/lib/commands/", "src/lib/cli/"],
+      ["src/lib/adapters/", "src/commands/", "src/lib/cli/"],
       true,
     );
     if (target) {
@@ -236,7 +232,7 @@ function checkActionFile(absPath: string, repoPath: string, violations: Violatio
 
 function checkAdapterFile(absPath: string, repoPath: string, violations: Violation[]): void {
   for (const ref of collectImportRefs(absPath)) {
-    const target = importTargetsForbiddenLayer(absPath, ref, ["src/lib/commands/"], true);
+    const target = importTargetsForbiddenLayer(absPath, ref, ["src/commands/"], true);
     if (target) {
       addViolation(
         violations,
@@ -251,7 +247,6 @@ function checkAdapterFile(absPath: string, repoPath: string, violations: Violati
 }
 
 function checkCommandFile(absPath: string, repoPath: string, violations: Violation[]): void {
-  if (isGeneratedOrRegistryCommandFile(repoPath)) return;
   const sourceFile = sourceFileFor(absPath);
   let commandClassCount = 0;
 
@@ -286,7 +281,7 @@ function checkCommandFile(absPath: string, repoPath: string, violations: Violati
   }
 }
 
-export function findLayerImportBoundaryViolations(root = SRC_LIB_ROOT): Violation[] {
+export function findLayerImportBoundaryViolations(root = SRC_ROOT): Violation[] {
   const violations: Violation[] = [];
   for (const absPath of walk(root)) {
     const repoPath = toRepoPath(absPath);

src/commands/README.md

@@ -4,18 +4,20 @@
 # `src/commands`
 
 This tree is the oclif discovery surface for the packaged `nemoclaw` CLI.
-Each file is intentionally thin: it exports a command class from `src/lib/commands/**`
-and attaches NemoClaw's public display metadata.
+Command entrypoint files define the oclif command class directly. Do not add new
+public command shims that only re-export from `src/lib/**`, and do not recreate a
+parallel command layer under `src/lib`. Prefer `src/lib/<feature>/**` for shared
+parser helpers.
 
 ```text
 src/commands/<public command path>.ts
-  -> import command implementation from src/lib/commands/**
-  -> wrap with src/lib/cli/command-display.ts metadata
+  -> parse flags/args
+  -> call src/lib/actions/** or small src/lib/<feature> command-support helpers
 ```
 
-Keep behavior out of this tree. Product behavior belongs in `src/lib/actions/**`, pure
-planning and classification belongs in `src/lib/domain/**`, and host/runtime boundaries
-belong in `src/lib/adapters/**`.
+Keep product behavior out of this tree. Command classes should stay thin: product
+behavior belongs in `src/lib/actions/**`, pure planning and classification belongs in
+`src/lib/domain/**`, and host/runtime boundaries belong in `src/lib/adapters/**`.
 
 Hidden `nemoclaw internal ...` entrypoints live under `src/commands/internal/**`; see
 `src/commands/internal/README.md` for their narrower compatibility contract.

src/commands/backup-all.ts

@@ -1,15 +1,20 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import Command from "../lib/commands/maintenance/backup-all";
-import { withCommandDisplay } from "../lib/cli/command-display";
+import { runBackupAllAction } from "../lib/actions/global";
+import { NemoClawCommand } from "../lib/cli/nemoclaw-oclif-command";
 
-export default withCommandDisplay(Command, [
-  {
-    usage: "nemoclaw backup-all",
-    description: "Back up all sandbox state before upgrade",
-    group: "Backup",
-    scope: "global",
-    order: 40,
-  },
-]);
+export default class BackupAllCommand extends NemoClawCommand {
+  static id = "backup-all";
+  static strict = true;
+  static summary = "Back up all sandbox state before upgrade";
+  static description = "Back up registered, running sandbox state before upgrading.";
+  static usage = ["backup-all"];
+  static examples = ["<%= config.bin %> backup-all"];
+  static flags = {};
+
+  public async run(): Promise<void> {
+    await this.parse(BackupAllCommand);
+    runBackupAllAction();
+  }
+}

src/lib/commands/credentials.test.ts → src/commands/credentials.test.ts

@@ -9,8 +9,8 @@ const mocks = vi.hoisted(() => ({
   runOpenshellProviderCommand: vi.fn(),
 }));
 
-vi.mock("../credentials/store", () => ({ prompt: mocks.prompt }));
-vi.mock("../actions/global", () => ({
+vi.mock("../lib/credentials/store", () => ({ prompt: mocks.prompt }));
+vi.mock("../lib/actions/global", () => ({
   recoverNamedGatewayRuntime: mocks.recoverNamedGatewayRuntime,
   runOpenshellProviderCommand: mocks.runOpenshellProviderCommand,
 }));

src/commands/credentials.ts

@@ -1,4 +1,26 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export { default } from "../lib/commands/credentials";
+import { NemoClawCommand } from "../lib/cli/nemoclaw-oclif-command";
+
+import { printCredentialsUsage } from "../lib/credentials/command-support";
+
+export default class CredentialsCommand extends NemoClawCommand {
+  static id = "credentials";
+  static strict = true;
+  static summary = "Manage provider credentials";
+  static description =
+    "List or reset provider credentials registered with the OpenShell gateway.";
+  static usage = ["credentials <list|reset>"];
+  static examples = [
+    "<%= config.bin %> credentials list",
+    "<%= config.bin %> credentials reset nvidia-prod --yes",
+  ];
+  static flags = {
+  };
+
+  public async run(): Promise<void> {
+    await this.parse(CredentialsCommand);
+    printCredentialsUsage(this.log.bind(this));
+  }
+}

src/commands/credentials/list.ts

@@ -1,15 +1,59 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import Command from "../../lib/commands/credentials/list";
-import { withCommandDisplay } from "../../lib/cli/command-display";
-
-export default withCommandDisplay(Command, [
-  {
-    usage: "nemoclaw credentials list",
-    description: "List stored credential keys",
-    group: "Credentials",
-    scope: "global",
-    order: 38,
-  },
-]);
+import { CLI_NAME } from "../../lib/cli/branding";
+import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command";
+
+import { runOpenshellProviderCommand } from "../../lib/actions/global";
+import { OPENSHELL_OPERATION_TIMEOUT_MS } from "../../lib/adapters/openshell/timeouts";
+import { isBridgeProviderName, recoverGatewayOrExit } from "../../lib/credentials/command-support";
+
+export default class CredentialsListCommand extends NemoClawCommand {
+  static id = "credentials:list";
+  static strict = true;
+  static summary = "List stored credential providers";
+  static description = "List provider credentials registered with the OpenShell gateway.";
+  static usage = ["credentials list"];
+  static examples = ["<%= config.bin %> credentials list"];
+  static flags = {
+  };
+
+  public async run(): Promise<void> {
+    await this.parse(CredentialsListCommand);
+    if (!(await recoverGatewayOrExit("query", (lines) => this.failWithLines(lines)))) return;
+
+    const result = runOpenshellProviderCommand(["provider", "list", "--names"], {
+      ignoreError: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: OPENSHELL_OPERATION_TIMEOUT_MS,
+    });
+    if (result.status !== 0) {
+      this.failWithLines([
+        "  Could not query OpenShell gateway. Is it running?",
+        `  Run 'openshell gateway start --name nemoclaw' or '${CLI_NAME} onboard' first.`,
+      ]);
+      return;
+    }
+
+    const allNames = String(result.stdout || "")
+      .split("\n")
+      .map((name) => name.trim())
+      .filter((name) => name.length > 0);
+    const credentialNames = allNames.filter((name) => !isBridgeProviderName(name)).sort();
+    const bridgeNames = allNames.filter((name) => isBridgeProviderName(name));
+
+    if (credentialNames.length === 0) {
+      this.log("  No provider credentials registered.");
+    } else {
+      this.log("  Providers registered with the OpenShell gateway:");
+      for (const name of credentialNames) {
+        this.log(`    ${name}`);
+      }
+    }
+    if (bridgeNames.length > 0) {
+      this.log("");
+      this.log(`  ${String(bridgeNames.length)} per-sandbox messaging bridge(s) are also registered.`);
+      this.log(`  Manage those with \`${CLI_NAME} <sandbox> channels list/remove/stop\` — not this command.`);
+    }
+  }
+}

src/commands/credentials/reset.ts

@@ -1,15 +1,86 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import Command from "../../lib/commands/credentials/reset";
-import { withCommandDisplay } from "../../lib/cli/command-display";
-
-export default withCommandDisplay(Command, [
-  {
-    usage: "nemoclaw credentials reset",
-    description: "Remove a stored credential so onboard re-prompts",
-    group: "Credentials",
-    scope: "global",
-    order: 39,
-  },
-]);
+import { Args } from "@oclif/core";
+import { CLI_NAME } from "../../lib/cli/branding";
+import { yesFlag } from "../../lib/cli/common-flags";
+import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command";
+
+import { runOpenshellProviderCommand } from "../../lib/actions/global";
+import { OPENSHELL_OPERATION_TIMEOUT_MS } from "../../lib/adapters/openshell/timeouts";
+import { isBridgeProviderName, recoverGatewayOrExit } from "../../lib/credentials/command-support";
+import { prompt as askPrompt } from "../../lib/credentials/store";
+
+export default class CredentialsResetCommand extends NemoClawCommand {
+  static id = "credentials:reset";
+  static strict = true;
+  static summary = "Remove a provider credential";
+  static description = "Remove a provider credential so onboard re-prompts for it.";
+  static usage = ["credentials reset <PROVIDER> [--yes]"];
+  static examples = [
+    "<%= config.bin %> credentials reset nvidia-prod",
+    "<%= config.bin %> credentials reset nvidia-prod --yes",
+  ];
+  static args = {
+    provider: Args.string({
+      name: "PROVIDER",
+      description: "OpenShell provider name",
+      required: true,
+    }),
+  };
+  static flags = {
+    yes: yesFlag(),
+  };
+
+  public async run(): Promise<void> {
+    const { args, flags } = await this.parse(CredentialsResetCommand);
+    const key = args.provider;
+
+    if (isBridgeProviderName(key)) {
+      this.failWithLines([
+        `  '${key}' is a per-sandbox messaging bridge, not a credential.`,
+        `  Use \`${CLI_NAME} <sandbox> channels remove <telegram|discord|slack>\` to retire`,
+        "  the integration (it tears down the bridge provider and rebuilds the sandbox),",
+        `  or \`${CLI_NAME} <sandbox> channels stop <…>\` to pause it without clearing tokens.`,
+      ]);
+      return;
+    }
+
+    if (!flags.yes) {
+      const answer = (await askPrompt(`  Remove provider '${key}' from the OpenShell gateway? [y/N]: `))
+        .trim()
+        .toLowerCase();
+      if (answer !== "y" && answer !== "yes") {
+        this.log("  Cancelled.");
+        return;
+      }
+    }
+
+    if (!(await recoverGatewayOrExit("reach", (lines) => this.failWithLines(lines)))) return;
+
+    const result = runOpenshellProviderCommand(["provider", "delete", key], {
+      ignoreError: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: OPENSHELL_OPERATION_TIMEOUT_MS,
+    });
+    if (result.status === 0) {
+      this.log(`  Removed provider '${key}' from the OpenShell gateway.`);
+      this.log(`  Re-run '${CLI_NAME} onboard' to enter a new value.`);
+      return;
+    }
+
+    const lines = [`  Could not remove provider '${key}'.`];
+    if (/^[A-Z][A-Z0-9_]+$/.test(key)) {
+      lines.push(
+        "",
+        `  '${key}' looks like a credential env variable name.`,
+        "  As of this release, 'credentials reset' takes an OpenShell",
+        `  provider name. Run '${CLI_NAME} credentials list' to see the`,
+        "  registered providers, then retry with one of those names.",
+      );
+    }
+    const stderr = String(result.stderr || "").trim();
+    if (stderr) lines.push(`  ${stderr}`);
+    this.failWithLines(lines);
+  }
+}