From 4995907541729c504acdbb09a69fb7d8e695debd Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 19:35:08 -0400
Subject: [PATCH] docs: document cli support tests

---
 src/cli/argv-invocation.test.ts                    | 1 +
 src/cli/argv.test.ts                               | 1 +
 src/cli/banner.test.ts                             | 1 +
 src/cli/channels-cli.test.ts                       | 1 +
 src/cli/command-bootstrap.test.ts                  | 1 +
 src/cli/command-execution-startup.test.ts          | 1 +
 src/cli/command-secret-resolution.coverage.test.ts | 1 +
 src/cli/command-secret-targets.import.test.ts      | 1 +
 src/cli/command-secret-targets.test.ts             | 1 +
 src/cli/command-source.test-helpers.test.ts        | 1 +
 src/cli/command-startup-policy.test.ts             | 1 +
 src/cli/completion-cli.test.ts                     | 1 +
 src/cli/completion-cli.write-state.test.ts         | 1 +
 src/cli/daemon-cli.coverage.test.ts                | 1 +
 src/cli/devices-cli.runtime.timeout.test.ts        | 1 +
 src/cli/exec-approvals-cli.test.ts                 | 1 +
 src/cli/gateway-cli.coverage.test.ts               | 1 +
 src/cli/gateway-rpc.runtime.test.ts                | 1 +
 src/cli/hooks-cli.test.ts                          | 1 +
 src/cli/message-secret-scope.test.ts               | 1 +
 src/cli/models-cli.lazy.test.ts                    | 1 +
 src/cli/nodes-cli.plugin-registration.test.ts      | 1 +
 src/cli/nodes-media-utils.test.ts                  | 1 +
 src/cli/npm-resolution.test.ts                     | 1 +
 src/cli/parse-timeout.test.ts                      | 1 +
 src/cli/plugin-registry-loader.test.ts             | 1 +
 src/cli/plugins-cli.update.test.ts                 | 1 +
 src/cli/plugins-list-format.test.ts                | 1 +
 src/cli/plugins-uninstall-selection.test.ts        | 1 +
 src/cli/plugins-update-selection.test.ts           | 1 +
 src/cli/program.force.test.ts                      | 1 +
 src/cli/program.nodes-media.e2e.test.ts            | 1 +
 src/cli/root-option-value.test.ts                  | 1 +
 src/cli/route.test.ts                              | 1 +
 src/cli/run-main.profile-env.test.ts               | 1 +
 src/cli/skills-cli.commands.test.ts                | 1 +
 src/cli/system-cli.test.ts                         | 1 +
 src/cli/update-cli.test-helpers.test.ts            | 1 +
 src/cli/update-cli.test-helpers.ts                 | 1 +
 src/cli/webhooks-cli.test.ts                       | 1 +
 40 files changed, 40 insertions(+)

diff --git a/src/cli/argv-invocation.test.ts b/src/cli/argv-invocation.test.ts
index 59ab058d880c..29230877ba19 100644
--- a/src/cli/argv-invocation.test.ts
+++ b/src/cli/argv-invocation.test.ts
@@ -1,3 +1,4 @@
+// Argv invocation tests cover CLI argv normalization before command dispatch.
 import { describe, expect, it } from "vitest";
 import { resolveCliArgvInvocation } from "./argv-invocation.js";
 
diff --git a/src/cli/argv.test.ts b/src/cli/argv.test.ts
index b582b0e68fef..e34bd950ba10 100644
--- a/src/cli/argv.test.ts
+++ b/src/cli/argv.test.ts
@@ -1,3 +1,4 @@
+// Argv tests cover CLI argument parsing helpers and platform-specific normalization.
 import { describe, expect, it } from "vitest";
 import {
   buildParseArgv,
diff --git a/src/cli/banner.test.ts b/src/cli/banner.test.ts
index 53346c4d7b18..dcf842aa9b71 100644
--- a/src/cli/banner.test.ts
+++ b/src/cli/banner.test.ts
@@ -1,3 +1,4 @@
+// Banner tests cover CLI banner rendering and suppression behavior.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { formatCliBannerLine } from "./banner.js";
 
diff --git a/src/cli/channels-cli.test.ts b/src/cli/channels-cli.test.ts
index 8cbc3bd23ad1..0d67cf1d27f9 100644
--- a/src/cli/channels-cli.test.ts
+++ b/src/cli/channels-cli.test.ts
@@ -1,3 +1,4 @@
+// Channels CLI tests cover channel command registration and option parsing.
 import { Command } from "commander";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { PluginPackageChannel } from "../plugins/manifest.js";
diff --git a/src/cli/command-bootstrap.test.ts b/src/cli/command-bootstrap.test.ts
index 0ebe9469b3d8..9aefeaa0d9b6 100644
--- a/src/cli/command-bootstrap.test.ts
+++ b/src/cli/command-bootstrap.test.ts
@@ -1,3 +1,4 @@
+// Command bootstrap tests cover CLI command bootstrap sequencing and side effects.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const ensureConfigReadyMock = vi.hoisted(() => vi.fn(async () => {}));
diff --git a/src/cli/command-execution-startup.test.ts b/src/cli/command-execution-startup.test.ts
index 5656ce82f140..5d346eabf0e8 100644
--- a/src/cli/command-execution-startup.test.ts
+++ b/src/cli/command-execution-startup.test.ts
@@ -1,3 +1,4 @@
+// Command execution startup tests cover startup behavior before CLI command execution.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const emitCliBannerMock = vi.hoisted(() => vi.fn());
diff --git a/src/cli/command-secret-resolution.coverage.test.ts b/src/cli/command-secret-resolution.coverage.test.ts
index d7d3abe68fde..97742893a0ed 100644
--- a/src/cli/command-secret-resolution.coverage.test.ts
+++ b/src/cli/command-secret-resolution.coverage.test.ts
@@ -1,3 +1,4 @@
+// Command secret resolution coverage tests cover plugin secret resolution branches.
 import { bundledPluginFile } from "openclaw/plugin-sdk/test-fixtures";
 import { describe, expect, it } from "vitest";
 import { readCommandSource } from "./command-source.test-helpers.js";
diff --git a/src/cli/command-secret-targets.import.test.ts b/src/cli/command-secret-targets.import.test.ts
index acfc86525470..30a026882f0e 100644
--- a/src/cli/command-secret-targets.import.test.ts
+++ b/src/cli/command-secret-targets.import.test.ts
@@ -1,3 +1,4 @@
+// Command secret target import tests cover lazy import safety for secret target metadata.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 describe("command secret targets module import", () => {
diff --git a/src/cli/command-secret-targets.test.ts b/src/cli/command-secret-targets.test.ts
index 1e9b35bbb394..208847c71ae1 100644
--- a/src/cli/command-secret-targets.test.ts
+++ b/src/cli/command-secret-targets.test.ts
@@ -1,3 +1,4 @@
+// Command secret target tests cover CLI secret target mapping and validation.
 import { describe, expect, it, vi } from "vitest";
 
 const REGISTRY_IDS = [
diff --git a/src/cli/command-source.test-helpers.test.ts b/src/cli/command-source.test-helpers.test.ts
index f4857527ffd5..3c5305bb1263 100644
--- a/src/cli/command-source.test-helpers.test.ts
+++ b/src/cli/command-source.test-helpers.test.ts
@@ -1,3 +1,4 @@
+// Command source test-helper tests cover fixture helpers for command source checks.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/cli/command-startup-policy.test.ts b/src/cli/command-startup-policy.test.ts
index f5949ce1bb20..011a582e3870 100644
--- a/src/cli/command-startup-policy.test.ts
+++ b/src/cli/command-startup-policy.test.ts
@@ -1,3 +1,4 @@
+// Command startup policy tests cover which CLI commands require startup side effects.
 import { describe, expect, it } from "vitest";
 import {
   resolveCliStartupPolicy,
diff --git a/src/cli/completion-cli.test.ts b/src/cli/completion-cli.test.ts
index 5ec2b1a5117b..e00f90c36bdd 100644
--- a/src/cli/completion-cli.test.ts
+++ b/src/cli/completion-cli.test.ts
@@ -1,3 +1,4 @@
+// Completion CLI tests cover shell completion command generation and install output.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
diff --git a/src/cli/completion-cli.write-state.test.ts b/src/cli/completion-cli.write-state.test.ts
index 9a9b1cf4d812..2f78ad67e284 100644
--- a/src/cli/completion-cli.write-state.test.ts
+++ b/src/cli/completion-cli.write-state.test.ts
@@ -1,3 +1,4 @@
+// Completion write-state tests cover shell completion state file writes.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/cli/daemon-cli.coverage.test.ts b/src/cli/daemon-cli.coverage.test.ts
index 2c9e0154788f..a916cd3ea44c 100644
--- a/src/cli/daemon-cli.coverage.test.ts
+++ b/src/cli/daemon-cli.coverage.test.ts
@@ -1,3 +1,4 @@
+// Daemon CLI coverage tests cover daemon command branches and output behavior.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/cli/devices-cli.runtime.timeout.test.ts b/src/cli/devices-cli.runtime.timeout.test.ts
index 632342e2b9e6..284519d7e180 100644
--- a/src/cli/devices-cli.runtime.timeout.test.ts
+++ b/src/cli/devices-cli.runtime.timeout.test.ts
@@ -1,3 +1,4 @@
+// Devices CLI runtime timeout tests cover device command timeout handling.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const callGatewayMock = vi.fn(async () => ({ pending: [], paired: [] }));
diff --git a/src/cli/exec-approvals-cli.test.ts b/src/cli/exec-approvals-cli.test.ts
index 07e4cf7ff411..1b35bf5a4e57 100644
--- a/src/cli/exec-approvals-cli.test.ts
+++ b/src/cli/exec-approvals-cli.test.ts
@@ -1,3 +1,4 @@
+// Exec approvals CLI tests cover approval command registration and output handling.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import * as execApprovals from "../infra/exec-approvals.js";
diff --git a/src/cli/gateway-cli.coverage.test.ts b/src/cli/gateway-cli.coverage.test.ts
index 9813f0b40b4f..1e011a7c0c28 100644
--- a/src/cli/gateway-cli.coverage.test.ts
+++ b/src/cli/gateway-cli.coverage.test.ts
@@ -1,3 +1,4 @@
+// Gateway CLI coverage tests cover gateway command branches and output modes.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/cli/gateway-rpc.runtime.test.ts b/src/cli/gateway-rpc.runtime.test.ts
index 0e3e1a8a0148..405631c1ccb0 100644
--- a/src/cli/gateway-rpc.runtime.test.ts
+++ b/src/cli/gateway-rpc.runtime.test.ts
@@ -1,3 +1,4 @@
+// Gateway RPC runtime tests cover CLI gateway RPC calls and runtime error handling.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const callGatewayMock = vi.fn(async () => ({ ok: true }));
diff --git a/src/cli/hooks-cli.test.ts b/src/cli/hooks-cli.test.ts
index e57efc89b84a..1895b299bc40 100644
--- a/src/cli/hooks-cli.test.ts
+++ b/src/cli/hooks-cli.test.ts
@@ -1,3 +1,4 @@
+// Hooks CLI tests cover hook command registration and output behavior.
 import { describe, expect, it } from "vitest";
 import type { HookStatusReport } from "../hooks/hooks-status.js";
 import { formatHookInfo, formatHooksCheck, formatHooksList } from "./hooks-cli.js";
diff --git a/src/cli/message-secret-scope.test.ts b/src/cli/message-secret-scope.test.ts
index eb8081ecf35b..df03c5129084 100644
--- a/src/cli/message-secret-scope.test.ts
+++ b/src/cli/message-secret-scope.test.ts
@@ -1,3 +1,4 @@
+// Message secret scope tests cover CLI secret scoping for message commands.
 import { describe, expect, it } from "vitest";
 import { resolveMessageSecretScope } from "./message-secret-scope.js";
 
diff --git a/src/cli/models-cli.lazy.test.ts b/src/cli/models-cli.lazy.test.ts
index e6bac999d011..a511731b47c5 100644
--- a/src/cli/models-cli.lazy.test.ts
+++ b/src/cli/models-cli.lazy.test.ts
@@ -1,3 +1,4 @@
+// Models CLI lazy tests cover lazy model command imports and registration.
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
diff --git a/src/cli/nodes-cli.plugin-registration.test.ts b/src/cli/nodes-cli.plugin-registration.test.ts
index 2167c9c108d6..eb62c3f730b1 100644
--- a/src/cli/nodes-cli.plugin-registration.test.ts
+++ b/src/cli/nodes-cli.plugin-registration.test.ts
@@ -1,3 +1,4 @@
+// Nodes CLI plugin registration tests cover node command plugin registration.
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { loggingState } from "../logging/state.js";
diff --git a/src/cli/nodes-media-utils.test.ts b/src/cli/nodes-media-utils.test.ts
index 59bb9c59371f..3b26438c000f 100644
--- a/src/cli/nodes-media-utils.test.ts
+++ b/src/cli/nodes-media-utils.test.ts
@@ -1,3 +1,4 @@
+// Nodes media utility tests cover media argument helpers for node CLI commands.
 import { describe, expect, it } from "vitest";
 import {
   asBoolean,
diff --git a/src/cli/npm-resolution.test.ts b/src/cli/npm-resolution.test.ts
index c22c9260afcb..99608ac2f6a0 100644
--- a/src/cli/npm-resolution.test.ts
+++ b/src/cli/npm-resolution.test.ts
@@ -1,3 +1,4 @@
+// npm resolution tests cover CLI plugin package resolution from installed roots.
 import { installedPluginRoot } from "openclaw/plugin-sdk/test-fixtures";
 import { describe, expect, it } from "vitest";
 import {
diff --git a/src/cli/parse-timeout.test.ts b/src/cli/parse-timeout.test.ts
index 3c48c32a4431..b81187a65113 100644
--- a/src/cli/parse-timeout.test.ts
+++ b/src/cli/parse-timeout.test.ts
@@ -1,3 +1,4 @@
+// Parse timeout tests cover CLI timeout argument parsing and validation.
 import { describe, expect, it } from "vitest";
 import { parseTimeoutMs, parseTimeoutMsWithFallback } from "./parse-timeout.js";
 
diff --git a/src/cli/plugin-registry-loader.test.ts b/src/cli/plugin-registry-loader.test.ts
index 7bf7de33e4f8..9c2b7396b8e9 100644
--- a/src/cli/plugin-registry-loader.test.ts
+++ b/src/cli/plugin-registry-loader.test.ts
@@ -1,3 +1,4 @@
+// Plugin registry loader tests cover CLI plugin registry loading and cache reset behavior.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const ensurePluginRegistryLoadedMock = vi.hoisted(() => vi.fn());
diff --git a/src/cli/plugins-cli.update.test.ts b/src/cli/plugins-cli.update.test.ts
index 73dd9880e460..c9a23a8c6db5 100644
--- a/src/cli/plugins-cli.update.test.ts
+++ b/src/cli/plugins-cli.update.test.ts
@@ -1,3 +1,4 @@
+// Plugins CLI update tests cover plugin update command behavior and output.
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
diff --git a/src/cli/plugins-list-format.test.ts b/src/cli/plugins-list-format.test.ts
index 786e89d693ce..3860a3d23b40 100644
--- a/src/cli/plugins-list-format.test.ts
+++ b/src/cli/plugins-list-format.test.ts
@@ -1,3 +1,4 @@
+// Plugin list format tests cover installed plugin table and JSON formatting.
 import { describe, expect, it } from "vitest";
 import { createPluginRecord } from "../plugins/status.test-helpers.js";
 import { formatPluginLine } from "./plugins-list-format.js";
diff --git a/src/cli/plugins-uninstall-selection.test.ts b/src/cli/plugins-uninstall-selection.test.ts
index c91f20f07aad..66a17216158f 100644
--- a/src/cli/plugins-uninstall-selection.test.ts
+++ b/src/cli/plugins-uninstall-selection.test.ts
@@ -1,3 +1,4 @@
+// Plugin uninstall selection tests cover CLI uninstall target matching.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolvePluginUninstallId } from "./plugins-uninstall-selection.js";
diff --git a/src/cli/plugins-update-selection.test.ts b/src/cli/plugins-update-selection.test.ts
index 722640c703b8..f42c5f776d77 100644
--- a/src/cli/plugins-update-selection.test.ts
+++ b/src/cli/plugins-update-selection.test.ts
@@ -1,3 +1,4 @@
+// Plugin update selection tests cover CLI plugin update target selection.
 import { describe, expect, it } from "vitest";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import { resolvePluginUpdateSelection } from "./plugins-update-selection.js";
diff --git a/src/cli/program.force.test.ts b/src/cli/program.force.test.ts
index 6b9ef933fe04..63e1e774f7f4 100644
--- a/src/cli/program.force.test.ts
+++ b/src/cli/program.force.test.ts
@@ -1,3 +1,4 @@
+// Program force tests cover root force flag behavior and command propagation.
 import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 
 vi.mock("node:child_process", async () => {
diff --git a/src/cli/program.nodes-media.e2e.test.ts b/src/cli/program.nodes-media.e2e.test.ts
index adad1c4685f4..dc1d96c2d673 100644
--- a/src/cli/program.nodes-media.e2e.test.ts
+++ b/src/cli/program.nodes-media.e2e.test.ts
@@ -1,3 +1,4 @@
+// Program nodes media e2e tests cover media-oriented node commands through the full CLI program.
 import * as fs from "node:fs/promises";
 import { Command } from "commander";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/cli/root-option-value.test.ts b/src/cli/root-option-value.test.ts
index 63c445f80b18..c2d9ac09845b 100644
--- a/src/cli/root-option-value.test.ts
+++ b/src/cli/root-option-value.test.ts
@@ -1,3 +1,4 @@
+// Root option value tests cover root CLI option parsing and inherited values.
 import { describe, expect, it } from "vitest";
 import { takeCliRootOptionValue } from "./root-option-value.js";
 
diff --git a/src/cli/route.test.ts b/src/cli/route.test.ts
index 627783d654f2..178e0534756e 100644
--- a/src/cli/route.test.ts
+++ b/src/cli/route.test.ts
@@ -1,3 +1,4 @@
+// Route CLI tests cover route command registration, channel routing, and output.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const emitCliBannerMock = vi.hoisted(() => vi.fn());
diff --git a/src/cli/run-main.profile-env.test.ts b/src/cli/run-main.profile-env.test.ts
index fc5b248aadc8..8f31e0596cc9 100644
--- a/src/cli/run-main.profile-env.test.ts
+++ b/src/cli/run-main.profile-env.test.ts
@@ -1,3 +1,4 @@
+// Run-main profile env tests cover profile environment handling in the CLI entrypoint.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const fileState = vi.hoisted(() => ({
diff --git a/src/cli/skills-cli.commands.test.ts b/src/cli/skills-cli.commands.test.ts
index 58b6938f2aa7..0fba01f34bd7 100644
--- a/src/cli/skills-cli.commands.test.ts
+++ b/src/cli/skills-cli.commands.test.ts
@@ -1,3 +1,4 @@
+// Skills CLI command tests cover skill command registration and subcommand behavior.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { registerSkillsCli } from "./skills-cli.js";
diff --git a/src/cli/system-cli.test.ts b/src/cli/system-cli.test.ts
index ad69e8bb7609..7d682e2d8424 100644
--- a/src/cli/system-cli.test.ts
+++ b/src/cli/system-cli.test.ts
@@ -1,3 +1,4 @@
+// System CLI tests cover system command registration and status output.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createCliRuntimeCapture } from "./test-runtime-capture.js";
diff --git a/src/cli/update-cli.test-helpers.test.ts b/src/cli/update-cli.test-helpers.test.ts
index 6c1c8a8663a1..eff8cbdad345 100644
--- a/src/cli/update-cli.test-helpers.test.ts
+++ b/src/cli/update-cli.test-helpers.test.ts
@@ -1,3 +1,4 @@
+// Update CLI test-helper tests cover helper fixtures used by update command tests.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { isOwningNpmCommand } from "./update-cli.test-helpers.js";
diff --git a/src/cli/update-cli.test-helpers.ts b/src/cli/update-cli.test-helpers.ts
index 1685b961a192..a99998f7bdfb 100644
--- a/src/cli/update-cli.test-helpers.ts
+++ b/src/cli/update-cli.test-helpers.ts
@@ -1,3 +1,4 @@
+// Update CLI test helpers provide shared fixtures and path helpers for update tests.
 import path from "node:path";
 
 function isPathInsideRoot(candidate: string, root: string): boolean {
diff --git a/src/cli/webhooks-cli.test.ts b/src/cli/webhooks-cli.test.ts
index 35e0c934db05..de77dd49695b 100644
--- a/src/cli/webhooks-cli.test.ts
+++ b/src/cli/webhooks-cli.test.ts
@@ -1,3 +1,4 @@
+// Webhooks CLI tests cover webhook command registration and option parsing.
 import { Command } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { registerWebhooksCli } from "./webhooks-cli.js";