docs: document cli utility helpers

src/cli/deps.ts

@@ -1,3 +1,4 @@
+// Default CLI dependency surface with lazy outbound channel send adapters.
 import { normalizeChannelId } from "../channels/registry.js";
 import type { OutboundSendDeps } from "../infra/outbound/send-deps.js";
 import { createLazyRuntimeSurface } from "../shared/lazy-runtime.js";
@@ -76,6 +77,7 @@ function createLazySender(
 }
 
 export function createDefaultDeps(): CliDeps {
+  // Proxy lookup preserves the historic deps.channelName shape without eagerly importing plugins.
   const deps: CliDeps = {};
   const resolveSender = (channelId: string) =>
     createLazySender(channelId, async () => {

src/cli/devices-cli.runtime.ts

@@ -1,3 +1,4 @@
+// Device pairing runtime commands for gateway and loopback-local fallback operations.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
@@ -155,6 +156,7 @@ function resolveLocalPairingFallback(
   opts: DevicesRpcOpts,
   error: unknown,
 ): { details: ConnectPairingRequiredDetails } | null {
+  // Local fallback is only safe for implicit loopback gateway URLs.
   const message = normalizeLowercaseStringOrEmpty(normalizeErrorMessage(error));
   const details = readConnectPairingRequiredMessage(message);
   if (!details) {

src/cli/devices-cli.ts

@@ -1,3 +1,4 @@
+// Commander registration for device pairing and auth-token commands.
 import type { Command } from "commander";
 import { applyParentDefaultHelpAction } from "./program/parent-default-help.js";
 
@@ -22,6 +23,7 @@ type DevicesRuntimeModule = typeof import("./devices-cli.runtime.js");
 let devicesRuntimePromise: Promise<DevicesRuntimeModule> | undefined;
 
 function loadDevicesRuntime(): Promise<DevicesRuntimeModule> {
+  // Keep device-pairing crypto/table dependencies out of root help startup.
   return (devicesRuntimePromise ??= import("./devices-cli.runtime.js"));
 }
 

src/cli/dns-cli.ts

@@ -1,3 +1,4 @@
+// DNS setup helper for wide-area discovery using Tailscale addresses and CoreDNS.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -35,6 +36,7 @@ function run(cmd: string, args: string[], opts?: RunOpts): string {
 }
 
 function writeFileSudoIfNeeded(filePath: string, content: string): void {
+  // Zone/CoreDNS paths may be root-owned; fall back to sudo tee only after normal write fails.
   try {
     fs.writeFileSync(filePath, content, "utf-8");
     return;

src/cli/docs-cli.ts

@@ -1,3 +1,4 @@
+// Commander registration for live OpenClaw docs search.
 import type { Command } from "commander";
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
 import { theme } from "../../packages/terminal-core/src/theme.js";

src/cli/exec-approvals-cli.ts

@@ -1,3 +1,4 @@
+// CLI for reading and mutating exec approval allowlists locally, via gateway, or via node.
 import fs from "node:fs/promises";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { Command } from "commander";
@@ -132,6 +133,7 @@ async function loadWritableSnapshotTarget(opts: ExecApprovalsCliOpts): Promise<{
   targetLabel: string;
   baseHash: string;
 }> {
+  // Writes carry the base hash so gateway/node updates can reject stale snapshots.
   const { snapshot, nodeId, source } = await loadSnapshotTarget(opts);
   if (source === "local") {
     defaultRuntime.log(theme.muted("Writing local approvals."));

src/cli/exec-policy-cli.ts

@@ -1,3 +1,4 @@
+// CLI for showing and applying exec policy presets across config and approvals.
 import crypto from "node:crypto";
 import type { Command } from "commander";
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
@@ -128,6 +129,7 @@ function sanitizeExecPolicyMessage(value: unknown): string {
 }
 
 function hashExecApprovalsFile(file: ExecApprovalsFile): string {
+  // Match the persisted formatting hash so restore/set operations can detect drift.
   const raw = `${JSON.stringify(file, null, 2)}\n`;
   return crypto.createHash("sha256").update(raw).digest("hex");
 }

src/cli/failure-output.ts

@@ -1,3 +1,4 @@
+// Shared root CLI failure formatting with debug stack gating and recovery hints.
 import { isTruthyEnvValue } from "../infra/env.js";
 import { formatErrorMessage, formatUncaughtError } from "../infra/errors.js";
 import { formatCliCommand } from "./command-format.js";
@@ -27,6 +28,7 @@ function pushPrefixed(out: string[], value: string): void {
 }
 
 export function formatCliFailureLines(options: FormatCliFailureOptions): string[] {
+  // Default output stays terse; stack traces require explicit debug intent.
   const env = options.env ?? process.env;
   const lines = [
     `[openclaw] ${options.title}`,

src/cli/gateway-cli/call.ts

@@ -1,3 +1,4 @@
+// Shared gateway RPC command options and progress-wrapped CLI call helper.
 import type { Command } from "commander";
 import {
   GATEWAY_CLIENT_MODES,

src/cli/gateway-cli/dev.ts

@@ -1,3 +1,4 @@
+// Dev gateway bootstrap for a local loopback config and seeded dev workspace.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -15,6 +16,7 @@ const DEV_IDENTITY_EMOJI = "🤖";
 const DEV_AGENT_WORKSPACE_SUFFIX = "dev";
 
 async function loadDevTemplate(name: string, fallback: string): Promise<string> {
+  // Template frontmatter is metadata only; workspace files receive the body content.
   try {
     const templateDirs = await resolveWorkspaceTemplateSearchDirs();
     for (const templateDir of templateDirs) {