From 9572267f64a6d983be7261b9dc136cd2ee2c41f9 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 03:57:07 -0400
Subject: [PATCH] docs: document config recovery helpers

---
 src/config/backup-rotation.ts                  | 1 +
 src/config/config.acp-binding-cutover.test.ts  | 1 +
 src/config/config.web-search-provider.test.ts  | 1 +
 src/config/cron-limits.ts                      | 1 +
 src/config/future-version-guard.test.ts        | 1 +
 src/config/gateway-control-ui-origins.test.ts  | 1 +
 src/config/gateway-control-ui-origins.ts       | 1 +
 src/config/gateway-dispatch-config.ts          | 1 +
 src/config/io.best-effort.test.ts              | 1 +
 src/config/io.clobber-snapshot.ts              | 1 +
 src/config/io.observe-recovery.ts              | 1 +
 src/config/issue-format.ts                     | 1 +
 src/config/merge-patch.ts                      | 1 +
 src/config/normalize-paths.ts                  | 1 +
 src/config/plugin-auto-enable.channels.test.ts | 1 +
 src/config/sessions.cache.test.ts              | 1 +
 src/config/types.discord.ts                    | 1 +
 src/config/types.node-host.ts                  | 1 +
 src/config/types.tools.ts                      | 1 +
 src/config/validation.cold-imports.test.ts     | 1 +
 src/config/version.test.ts                     | 1 +
 src/config/zod-schema.providers-googlechat.ts  | 1 +
 src/config/zod-schema.proxy.test.ts            | 1 +
 src/config/zod-schema.ts                       | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/config/backup-rotation.ts b/src/config/backup-rotation.ts
index a4de6992a527..a6fc3b4ddff1 100644
--- a/src/config/backup-rotation.ts
+++ b/src/config/backup-rotation.ts
@@ -1,3 +1,4 @@
+// Rotates config backup files while preserving recent recovery points.
 import path from "node:path";
 
 const CONFIG_BACKUP_COUNT = 5;
diff --git a/src/config/config.acp-binding-cutover.test.ts b/src/config/config.acp-binding-cutover.test.ts
index cbac3afb4b29..d04e96a3ce31 100644
--- a/src/config/config.acp-binding-cutover.test.ts
+++ b/src/config/config.acp-binding-cutover.test.ts
@@ -1,3 +1,4 @@
+// Regresses ACP binding cutover config compatibility behavior.
 import { describe, expect, it } from "vitest";
 import { OpenClawSchema } from "./zod-schema.js";
 
diff --git a/src/config/config.web-search-provider.test.ts b/src/config/config.web-search-provider.test.ts
index d6cb5303628d..ac9f9e20c1a1 100644
--- a/src/config/config.web-search-provider.test.ts
+++ b/src/config/config.web-search-provider.test.ts
@@ -1,3 +1,4 @@
+// Covers web-search provider config parsing and provider defaults.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { testing as webSearchTesting } from "../agents/tools/web-search.js";
 import { buildWebSearchProviderConfig } from "./test-helpers.js";
diff --git a/src/config/cron-limits.ts b/src/config/cron-limits.ts
index 62977014d270..2cb2c78d5a01 100644
--- a/src/config/cron-limits.ts
+++ b/src/config/cron-limits.ts
@@ -1,3 +1,4 @@
+// Computes cron scheduling limits from config.
 import type { CronConfig } from "./types.cron.js";
 
 /** Default maximum number of cron jobs allowed to run at once. */
diff --git a/src/config/future-version-guard.test.ts b/src/config/future-version-guard.test.ts
index d232955a58a1..9e0a31c6f83e 100644
--- a/src/config/future-version-guard.test.ts
+++ b/src/config/future-version-guard.test.ts
@@ -1,3 +1,4 @@
+// Verifies config loading rejects unsupported future versions.
 import { describe, expect, it } from "vitest";
 import {
   ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS_ENV,
diff --git a/src/config/gateway-control-ui-origins.test.ts b/src/config/gateway-control-ui-origins.test.ts
index e73421158f26..10dee263e2f0 100644
--- a/src/config/gateway-control-ui-origins.test.ts
+++ b/src/config/gateway-control-ui-origins.test.ts
@@ -1,3 +1,4 @@
+// Covers gateway Control UI origin parsing and defaults.
 import { describe, expect, it } from "vitest";
 import { ensureControlUiAllowedOriginsForNonLoopbackBind } from "./gateway-control-ui-origins.js";
 
diff --git a/src/config/gateway-control-ui-origins.ts b/src/config/gateway-control-ui-origins.ts
index 952c9bdb519b..1c4af3320058 100644
--- a/src/config/gateway-control-ui-origins.ts
+++ b/src/config/gateway-control-ui-origins.ts
@@ -1,3 +1,4 @@
+// Resolves allowed Control UI origins for gateway access.
 import { DEFAULT_GATEWAY_PORT } from "./paths.js";
 import type { OpenClawConfig } from "./types.openclaw.js";
 
diff --git a/src/config/gateway-dispatch-config.ts b/src/config/gateway-dispatch-config.ts
index e9be8722be04..cc4f11f54411 100644
--- a/src/config/gateway-dispatch-config.ts
+++ b/src/config/gateway-dispatch-config.ts
@@ -1,3 +1,4 @@
+// Loads gateway dispatch config from runtime state and files.
 import fs from "node:fs";
 import path from "node:path";
 import { parseJsonWithJson5Fallback } from "../utils/parse-json-compat.js";
diff --git a/src/config/io.best-effort.test.ts b/src/config/io.best-effort.test.ts
index dd920aa7a39c..4fd8f08a558a 100644
--- a/src/config/io.best-effort.test.ts
+++ b/src/config/io.best-effort.test.ts
@@ -1,3 +1,4 @@
+// Covers best-effort config IO reads and warning behavior.
 import fs from "node:fs/promises";
 import { describe, expect, it } from "vitest";
 import {
diff --git a/src/config/io.clobber-snapshot.ts b/src/config/io.clobber-snapshot.ts
index 981e5ae26fd9..6deee59f92c6 100644
--- a/src/config/io.clobber-snapshot.ts
+++ b/src/config/io.clobber-snapshot.ts
@@ -1,3 +1,4 @@
+// Detects suspicious config clobbers and finds recovery snapshots.
 import path from "node:path";
 
 /** Maximum retained clobbered-config snapshots per config file. */
diff --git a/src/config/io.observe-recovery.ts b/src/config/io.observe-recovery.ts
index b0a20f9c8a28..094e3d2deb84 100644
--- a/src/config/io.observe-recovery.ts
+++ b/src/config/io.observe-recovery.ts
@@ -1,3 +1,4 @@
+// Observes and recovers config files that appear missing, corrupt, or clobbered.
 import crypto from "node:crypto";
 import path from "node:path";
 import { isRecord } from "../utils.js";
diff --git a/src/config/issue-format.ts b/src/config/issue-format.ts
index 74d468d2d0a5..f34b662bd635 100644
--- a/src/config/issue-format.ts
+++ b/src/config/issue-format.ts
@@ -1,3 +1,4 @@
+// Formats config validation issues for CLI and diagnostics.
 import { sanitizeTerminalText } from "../../packages/terminal-core/src/safe-text.js";
 import type { ConfigValidationIssue } from "./types.js";
 
diff --git a/src/config/merge-patch.ts b/src/config/merge-patch.ts
index 39a53fbd035c..7ffa4901feb6 100644
--- a/src/config/merge-patch.ts
+++ b/src/config/merge-patch.ts
@@ -1,3 +1,4 @@
+// Applies JSON merge-patch updates to config-like objects.
 import { isPlainObject } from "../infra/plain-object.js";
 import { isBlockedObjectKey } from "./prototype-keys.js";
 
diff --git a/src/config/normalize-paths.ts b/src/config/normalize-paths.ts
index 98914d3499b9..239831b0a9ff 100644
--- a/src/config/normalize-paths.ts
+++ b/src/config/normalize-paths.ts
@@ -1,3 +1,4 @@
+// Normalizes path-like config values to canonical user paths.
 import { isPlainObject, resolveUserPath } from "../utils.js";
 import type { OpenClawConfig } from "./types.js";
 
diff --git a/src/config/plugin-auto-enable.channels.test.ts b/src/config/plugin-auto-enable.channels.test.ts
index 29ae5685ac54..0b7368732944 100644
--- a/src/config/plugin-auto-enable.channels.test.ts
+++ b/src/config/plugin-auto-enable.channels.test.ts
@@ -1,3 +1,4 @@
+// Covers channel-driven plugin auto-enable decisions.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/config/sessions.cache.test.ts b/src/config/sessions.cache.test.ts
index a9bb37568006..8c8981deb680 100644
--- a/src/config/sessions.cache.test.ts
+++ b/src/config/sessions.cache.test.ts
@@ -1,3 +1,4 @@
+// Verifies session config cache invalidation and reload behavior.
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/config/types.discord.ts b/src/config/types.discord.ts
index 885f65829883..05c1b7a07121 100644
--- a/src/config/types.discord.ts
+++ b/src/config/types.discord.ts
@@ -1,3 +1,4 @@
+// Defines Discord channel configuration types.
 import type {
   ChannelPreviewStreamingConfig,
   ChannelStreamingProgressConfig,
diff --git a/src/config/types.node-host.ts b/src/config/types.node-host.ts
index 77610a341cbe..3a608d4864f3 100644
--- a/src/config/types.node-host.ts
+++ b/src/config/types.node-host.ts
@@ -1,3 +1,4 @@
+// Defines node-host browser proxy configuration types.
 export type NodeHostBrowserProxyConfig = {
   /** Enable the browser proxy on the node host (default: true). */
   enabled?: boolean;
diff --git a/src/config/types.tools.ts b/src/config/types.tools.ts
index 4f110fe25677..ca4a84cc404f 100644
--- a/src/config/types.tools.ts
+++ b/src/config/types.tools.ts
@@ -1,3 +1,4 @@
+// Defines tool availability and allowlist configuration types.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { ChatType } from "../channels/chat-type.js";
 import type { SafeBinProfileFixture } from "../infra/exec-safe-bin-policy.js";
diff --git a/src/config/validation.cold-imports.test.ts b/src/config/validation.cold-imports.test.ts
index 985e3f86a6df..ab5eeac2a7c8 100644
--- a/src/config/validation.cold-imports.test.ts
+++ b/src/config/validation.cold-imports.test.ts
@@ -1,3 +1,4 @@
+// Guards config validation modules against expensive cold imports.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/config/version.test.ts b/src/config/version.test.ts
index 55da0e691179..bbdacb6e73f5 100644
--- a/src/config/version.test.ts
+++ b/src/config/version.test.ts
@@ -1,3 +1,4 @@
+// Verifies config version handling and future-version guards.
 import { describe, expect, it } from "vitest";
 import {
   compareOpenClawVersions,
diff --git a/src/config/zod-schema.providers-googlechat.ts b/src/config/zod-schema.providers-googlechat.ts
index c7a42e4ccfc9..0474f8699ba0 100644
--- a/src/config/zod-schema.providers-googlechat.ts
+++ b/src/config/zod-schema.providers-googlechat.ts
@@ -1,3 +1,4 @@
+// Defines Google Chat provider schema fragments.
 import { z } from "zod";
 import { ChannelBotLoopProtectionSchema } from "./zod-schema.channels-config.js";
 import { ChannelHealthMonitorSchema } from "./zod-schema.channels.js";
diff --git a/src/config/zod-schema.proxy.test.ts b/src/config/zod-schema.proxy.test.ts
index e84bdb510c9e..b3c2200fbe9a 100644
--- a/src/config/zod-schema.proxy.test.ts
+++ b/src/config/zod-schema.proxy.test.ts
@@ -1,3 +1,4 @@
+// Covers proxy schema parsing and validation behavior.
 import { describe, it, expect } from "vitest";
 import { ProxyConfigSchema } from "./zod-schema.proxy.js";
 
diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts
index 306821a8e525..2415d8620bb5 100644
--- a/src/config/zod-schema.ts
+++ b/src/config/zod-schema.ts
@@ -1,3 +1,4 @@
+// Assembles the canonical Zod schema for OpenClaw config parsing.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeStringifiedOptionalString,