From 0156de5c341fe4bc3201b66b024680e216ba416a Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 18:56:56 -0400
Subject: [PATCH] docs: document command onboarding batch

---
 src/commands/agents.add.test.ts                                | 1 +
 src/commands/auth-choice.apply.plugin-provider.test.ts         | 1 +
 src/commands/channels.logs.test.ts                             | 1 +
 src/commands/daemon-install-helpers.test.ts                    | 1 +
 src/commands/doctor-auth-flat-profiles.test.ts                 | 1 +
 src/commands/doctor-auth-oauth-sidecar.test.ts                 | 1 +
 src/commands/doctor-config-flow.safe-bins.test.ts              | 1 +
 src/commands/doctor-heartbeat-template-repair.test.ts          | 3 +++
 .../doctor-platform-notes.startup-optimization.test.ts         | 1 +
 src/commands/message.test.ts                                   | 1 +
 src/commands/oauth-tls-preflight.doctor.test.ts                | 1 +
 src/commands/onboard-auth.test.ts                              | 1 +
 src/commands/onboard-config.test.ts                            | 1 +
 src/commands/onboard-interactive.test.ts                       | 1 +
 src/commands/onboard.test.ts                                   | 1 +
 src/commands/search-setup-cold-imports.test.ts                 | 1 +
 src/commands/status-json.test.ts                               | 1 +
 src/commands/status-overview-values.test.ts                    | 1 +
 src/commands/status.node-mode.test.ts                          | 1 +
 src/commands/status.scan-result.test.ts                        | 1 +
 20 files changed, 22 insertions(+)

diff --git a/src/commands/agents.add.test.ts b/src/commands/agents.add.test.ts
index 94ab56964a68..2ae5d61ec0fc 100644
--- a/src/commands/agents.add.test.ts
+++ b/src/commands/agents.add.test.ts
@@ -1,3 +1,4 @@
+// Agents add tests cover agent creation, workspace setup, channel binding, and onboarding integration.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/auth-choice.apply.plugin-provider.test.ts b/src/commands/auth-choice.apply.plugin-provider.test.ts
index 6a0a3447147d..ae37d83ad06a 100644
--- a/src/commands/auth-choice.apply.plugin-provider.test.ts
+++ b/src/commands/auth-choice.apply.plugin-provider.test.ts
@@ -1,3 +1,4 @@
+// Auth-choice plugin provider tests cover loaded provider setup, plugin install, and credential routing.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   applyAuthChoiceLoadedPluginProvider,
diff --git a/src/commands/channels.logs.test.ts b/src/commands/channels.logs.test.ts
index 82b8fe1e8c24..3cbc378e3fb2 100644
--- a/src/commands/channels.logs.test.ts
+++ b/src/commands/channels.logs.test.ts
@@ -1,3 +1,4 @@
+// Channels logs tests cover gateway log path resolution and channel log tailing.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/daemon-install-helpers.test.ts b/src/commands/daemon-install-helpers.test.ts
index e1618b307d23..680997aaf60c 100644
--- a/src/commands/daemon-install-helpers.test.ts
+++ b/src/commands/daemon-install-helpers.test.ts
@@ -1,3 +1,4 @@
+// Daemon install helper tests cover install plan construction, tokens, and platform-specific service setup.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor-auth-flat-profiles.test.ts b/src/commands/doctor-auth-flat-profiles.test.ts
index bdf8f6a348cb..4de8cad52643 100644
--- a/src/commands/doctor-auth-flat-profiles.test.ts
+++ b/src/commands/doctor-auth-flat-profiles.test.ts
@@ -1,3 +1,4 @@
+// Doctor flat auth-profile tests cover legacy flat profile repair and persisted auth-profile loading.
 import fs from "node:fs";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { loadPersistedAuthProfileStore } from "../agents/auth-profiles/persisted.js";
diff --git a/src/commands/doctor-auth-oauth-sidecar.test.ts b/src/commands/doctor-auth-oauth-sidecar.test.ts
index 04baa5f89772..cbeff5b89065 100644
--- a/src/commands/doctor-auth-oauth-sidecar.test.ts
+++ b/src/commands/doctor-auth-oauth-sidecar.test.ts
@@ -1,3 +1,4 @@
+// Doctor OAuth sidecar tests cover encrypted sidecar detection and auth repair guidance.
 import { createCipheriv } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/commands/doctor-config-flow.safe-bins.test.ts b/src/commands/doctor-config-flow.safe-bins.test.ts
index 524e52bcfdd5..34279273ed02 100644
--- a/src/commands/doctor-config-flow.safe-bins.test.ts
+++ b/src/commands/doctor-config-flow.safe-bins.test.ts
@@ -1,3 +1,4 @@
+// Doctor config-flow safe-bin tests cover executable allowlist validation and repair behavior.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor-heartbeat-template-repair.test.ts b/src/commands/doctor-heartbeat-template-repair.test.ts
index bf0a3896ebdb..9e22ca5cde9d 100644
--- a/src/commands/doctor-heartbeat-template-repair.test.ts
+++ b/src/commands/doctor-heartbeat-template-repair.test.ts
@@ -1,3 +1,4 @@
+// Doctor heartbeat template repair tests cover migration and repair of heartbeat prompt templates.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -208,6 +209,8 @@ Add short tasks below the comments only when you want the agent to check somethi
 
     await expect(fs.readFile(heartbeatPath, "utf-8")).resolves.toBe(
       `${[
+        "<!-- Heartbeat template; comments-only content prevents scheduled heartbeat API calls. -->",
+        "",
         "# Keep this file empty (or with only comments) to skip heartbeat API calls.",
         "",
         "# Add tasks below when you want the agent to check something periodically.",
diff --git a/src/commands/doctor-platform-notes.startup-optimization.test.ts b/src/commands/doctor-platform-notes.startup-optimization.test.ts
index cceb35716f56..23ff1712040d 100644
--- a/src/commands/doctor-platform-notes.startup-optimization.test.ts
+++ b/src/commands/doctor-platform-notes.startup-optimization.test.ts
@@ -1,3 +1,4 @@
+// Doctor platform note tests cover startup optimization hints and note output.
 import { describe, expect, it, vi } from "vitest";
 import { noteStartupOptimizationHints } from "./doctor-platform-notes.js";
 
diff --git a/src/commands/message.test.ts b/src/commands/message.test.ts
index aeb621bc3a52..3b5592681b79 100644
--- a/src/commands/message.test.ts
+++ b/src/commands/message.test.ts
@@ -1,3 +1,4 @@
+// Message command tests cover CLI message sending, environment handling, and runtime dependency wiring.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { CliDeps } from "../cli/deps.js";
 import type { RuntimeEnv } from "../runtime.js";
diff --git a/src/commands/oauth-tls-preflight.doctor.test.ts b/src/commands/oauth-tls-preflight.doctor.test.ts
index 01b014e26e52..20b87fbb7dc7 100644
--- a/src/commands/oauth-tls-preflight.doctor.test.ts
+++ b/src/commands/oauth-tls-preflight.doctor.test.ts
@@ -1,3 +1,4 @@
+// OAuth TLS preflight doctor tests cover certificate warnings and repair notes.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 
diff --git a/src/commands/onboard-auth.test.ts b/src/commands/onboard-auth.test.ts
index eb65590a568a..85a81df87d52 100644
--- a/src/commands/onboard-auth.test.ts
+++ b/src/commands/onboard-auth.test.ts
@@ -1,3 +1,4 @@
+// Onboard auth tests cover provider auth setup, credential persistence, and auth-profile state.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/onboard-config.test.ts b/src/commands/onboard-config.test.ts
index 2954c2fe94d3..b71c64f514fb 100644
--- a/src/commands/onboard-config.test.ts
+++ b/src/commands/onboard-config.test.ts
@@ -1,3 +1,4 @@
+// Onboard config tests cover workspace, bootstrap, and local setup config mutations.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/commands/onboard-interactive.test.ts b/src/commands/onboard-interactive.test.ts
index f8a68495ba68..2dcf4712d4ad 100644
--- a/src/commands/onboard-interactive.test.ts
+++ b/src/commands/onboard-interactive.test.ts
@@ -1,3 +1,4 @@
+// Interactive onboarding tests cover wizard cancellation, setup routing, and runtime output.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RuntimeEnv } from "../runtime.js";
 import { WizardCancelledError } from "../wizard/prompts.js";
diff --git a/src/commands/onboard.test.ts b/src/commands/onboard.test.ts
index f866d5e9c0bb..4d66bbbc3155 100644
--- a/src/commands/onboard.test.ts
+++ b/src/commands/onboard.test.ts
@@ -1,3 +1,4 @@
+// Onboard command tests cover guided setup entrypoints, setup aliases, and CLI messaging.
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { formatCliCommand } from "../cli/command-format.js";
diff --git a/src/commands/search-setup-cold-imports.test.ts b/src/commands/search-setup-cold-imports.test.ts
index 70ec99ada60b..d313eab751de 100644
--- a/src/commands/search-setup-cold-imports.test.ts
+++ b/src/commands/search-setup-cold-imports.test.ts
@@ -1,3 +1,4 @@
+// Search setup cold-import tests guard onboarding search setup against loading heavy runtime modules.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/commands/status-json.test.ts b/src/commands/status-json.test.ts
index aceb6ad6efc1..402a79a2825d 100644
--- a/src/commands/status-json.test.ts
+++ b/src/commands/status-json.test.ts
@@ -1,3 +1,4 @@
+// Status JSON tests cover command output and runtime JSON writes.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { RuntimeEnv } from "../runtime.js";
 import { statusJsonCommand } from "./status-json.js";
diff --git a/src/commands/status-overview-values.test.ts b/src/commands/status-overview-values.test.ts
index 72665c5e1473..edc663d5f8ea 100644
--- a/src/commands/status-overview-values.test.ts
+++ b/src/commands/status-overview-values.test.ts
@@ -1,3 +1,4 @@
+// Status overview value tests cover compact display values for agents, events, tasks, and services.
 import { describe, expect, it } from "vitest";
 import {
   buildStatusAllAgentsValue,
diff --git a/src/commands/status.node-mode.test.ts b/src/commands/status.node-mode.test.ts
index fa3a39ce7af0..4812d7f9b543 100644
--- a/src/commands/status.node-mode.test.ts
+++ b/src/commands/status.node-mode.test.ts
@@ -1,3 +1,4 @@
+// Status node-mode tests cover node host config and node status rendering.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
diff --git a/src/commands/status.scan-result.test.ts b/src/commands/status.scan-result.test.ts
index 3dcdd21ea28e..9152080c4d9c 100644
--- a/src/commands/status.scan-result.test.ts
+++ b/src/commands/status.scan-result.test.ts
@@ -1,3 +1,4 @@
+// Status scan result tests cover cold-start summaries and gateway probe snapshot aggregation.
 import { describe, expect, it } from "vitest";
 import { buildStatusScanResult } from "./status.scan-result.ts";
 import { buildColdStartStatusSummary } from "./status.scan.bootstrap-shared.ts";