From 54fe5dc8429b9cda2cd4befb3dc1dab6fd991a28 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 03:51:01 -0400
Subject: [PATCH] docs: document config runtime helpers

---
 src/config/bindings.ts                             | 1 +
 src/config/bundled-channel-config-runtime.test.ts  | 1 +
 src/config/commands.test.ts                        | 1 +
 src/config/config-env-vars.ts                      | 1 +
 src/config/config.backup-rotation.test-helpers.ts  | 1 +
 src/config/config.skills-entries-config.test.ts    | 1 +
 src/config/context-visibility.ts                   | 1 +
 src/config/defaults.ts                             | 1 +
 src/config/env-substitution.test.ts                | 1 +
 src/config/io.audit.ts                             | 1 +
 src/config/io.invalid-config.test.ts               | 1 +
 src/config/legacy-config-detection.test-support.ts | 1 +
 src/config/load-channel-config-surface.test.ts     | 1 +
 src/config/mcp-config-normalize.ts                 | 1 +
 src/config/mcp-config.test.ts                      | 1 +
 src/config/plugin-auto-enable.apply.ts             | 1 +
 src/config/plugin-auto-enable.providers.test.ts    | 1 +
 src/config/runtime-snapshot.ts                     | 1 +
 src/config/talk.normalize.test.ts                  | 1 +
 src/config/test-helpers.ts                         | 1 +
 src/config/types.auth.ts                           | 1 +
 src/config/zod-schema.channels-config.ts           | 1 +
 src/config/zod-schema.logging-levels.test.ts       | 1 +
 src/config/zod-schema.proxy.ts                     | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/config/bindings.ts b/src/config/bindings.ts
index a6148375d816..caf8329292ec 100644
--- a/src/config/bindings.ts
+++ b/src/config/bindings.ts
@@ -1,3 +1,4 @@
+// Normalizes agent binding config for channels, routes, and ACP sessions.
 import type { AgentAcpBinding, AgentBinding, AgentRouteBinding } from "./types.agents.js";
 import type { OpenClawConfig } from "./types.openclaw.js";
 
diff --git a/src/config/bundled-channel-config-runtime.test.ts b/src/config/bundled-channel-config-runtime.test.ts
index dac47dfd992c..73969f85444e 100644
--- a/src/config/bundled-channel-config-runtime.test.ts
+++ b/src/config/bundled-channel-config-runtime.test.ts
@@ -1,3 +1,4 @@
+// Verifies bundled channel config runtime loading stays lazy and bounded.
 import { importFreshModule } from "openclaw/plugin-sdk/test-fixtures";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
diff --git a/src/config/commands.test.ts b/src/config/commands.test.ts
index e4535cbb0ea2..b36b086ef283 100644
--- a/src/config/commands.test.ts
+++ b/src/config/commands.test.ts
@@ -1,3 +1,4 @@
+// Covers command config normalization and path validation.
 import path from "node:path";
 import { beforeEach, describe, expect, it } from "vitest";
 import { setActivePluginRegistry } from "../plugins/runtime.js";
diff --git a/src/config/config-env-vars.ts b/src/config/config-env-vars.ts
index 1c425f8a8f9c..066b3308b1c8 100644
--- a/src/config/config-env-vars.ts
+++ b/src/config/config-env-vars.ts
@@ -1,3 +1,4 @@
+// Defines environment-variable config metadata and preservation rules.
 import {
   isDangerousHostEnvOverrideVarName,
   isDangerousHostEnvVarName,
diff --git a/src/config/config.backup-rotation.test-helpers.ts b/src/config/config.backup-rotation.test-helpers.ts
index e9e7045770c1..fd24073d4bd7 100644
--- a/src/config/config.backup-rotation.test-helpers.ts
+++ b/src/config/config.backup-rotation.test-helpers.ts
@@ -1,3 +1,4 @@
+// Provides fixture helpers for config backup rotation tests.
 import path from "node:path";
 import { expect } from "vitest";
 
diff --git a/src/config/config.skills-entries-config.test.ts b/src/config/config.skills-entries-config.test.ts
index 9eff1b6bcdde..ab782fba0fce 100644
--- a/src/config/config.skills-entries-config.test.ts
+++ b/src/config/config.skills-entries-config.test.ts
@@ -1,3 +1,4 @@
+// Covers skills entry config parsing and defaults.
 import { describe, expect, it } from "vitest";
 import { OpenClawSchema } from "./zod-schema.js";
 
diff --git a/src/config/context-visibility.ts b/src/config/context-visibility.ts
index 9e3b5248311d..3d2a08e4400e 100644
--- a/src/config/context-visibility.ts
+++ b/src/config/context-visibility.ts
@@ -1,3 +1,4 @@
+// Resolves context visibility policy for accounts and sessions.
 import { resolveAccountEntry } from "../routing/account-lookup.js";
 import { normalizeAccountId } from "../routing/session-key.js";
 import type { OpenClawConfig } from "./config.js";
diff --git a/src/config/defaults.ts b/src/config/defaults.ts
index c3d4eeb29912..60a0f98544ad 100644
--- a/src/config/defaults.ts
+++ b/src/config/defaults.ts
@@ -1,3 +1,4 @@
+// Provides canonical default config values and model/provider defaults.
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import {
   collectManifestModelIdNormalizationPolicies,
diff --git a/src/config/env-substitution.test.ts b/src/config/env-substitution.test.ts
index 90db6a5e0e74..e4e43b43eab9 100644
--- a/src/config/env-substitution.test.ts
+++ b/src/config/env-substitution.test.ts
@@ -1,3 +1,4 @@
+// Covers config environment-variable substitution behavior.
 import { describe, expect, it } from "vitest";
 import {
   type EnvSubstitutionWarning,
diff --git a/src/config/io.audit.ts b/src/config/io.audit.ts
index e1420ab1e7b0..2c1740d60aad 100644
--- a/src/config/io.audit.ts
+++ b/src/config/io.audit.ts
@@ -1,3 +1,4 @@
+// Audits config paths and values for diagnostics and safety checks.
 import path from "node:path";
 import { redactSecrets, redactToolPayloadText } from "../logging/redact.js";
 import { resolveStateDir } from "./paths.js";
diff --git a/src/config/io.invalid-config.test.ts b/src/config/io.invalid-config.test.ts
index bade63a7653d..a83b7c0f5489 100644
--- a/src/config/io.invalid-config.test.ts
+++ b/src/config/io.invalid-config.test.ts
@@ -1,3 +1,4 @@
+// Verifies invalid-config errors include stable codes and details.
 import { describe, expect, it, vi } from "vitest";
 import {
   createInvalidConfigError,
diff --git a/src/config/legacy-config-detection.test-support.ts b/src/config/legacy-config-detection.test-support.ts
index 8403cd7f3ee8..87ab16c0f804 100644
--- a/src/config/legacy-config-detection.test-support.ts
+++ b/src/config/legacy-config-detection.test-support.ts
@@ -1,3 +1,4 @@
+// Provides assertions for legacy config detection tests.
 import { expect } from "vitest";
 
 type SchemaParseResult<TData = unknown> =
diff --git a/src/config/load-channel-config-surface.test.ts b/src/config/load-channel-config-surface.test.ts
index 3238330cf2d9..0e5fade4c0dc 100644
--- a/src/config/load-channel-config-surface.test.ts
+++ b/src/config/load-channel-config-surface.test.ts
@@ -1,3 +1,4 @@
+// Verifies channel config loading surfaces visible plugin settings.
 import fs from "node:fs";
 import path from "node:path";
 import type { createJiti as createJitiType } from "jiti";
diff --git a/src/config/mcp-config-normalize.ts b/src/config/mcp-config-normalize.ts
index 3de88f90c4f7..54062c49f93a 100644
--- a/src/config/mcp-config-normalize.ts
+++ b/src/config/mcp-config-normalize.ts
@@ -1,3 +1,4 @@
+// Normalizes MCP config records into canonical runtime shape.
 import { isRecord } from "../utils.js";
 
 type ConfigMcpServers = Record<string, Record<string, unknown>>;
diff --git a/src/config/mcp-config.test.ts b/src/config/mcp-config.test.ts
index 8c0df95e3683..ef35b406a5b8 100644
--- a/src/config/mcp-config.test.ts
+++ b/src/config/mcp-config.test.ts
@@ -1,3 +1,4 @@
+// Covers MCP config normalization, validation, and serialization.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { withTempHome } from "openclaw/plugin-sdk/test-env";
diff --git a/src/config/plugin-auto-enable.apply.ts b/src/config/plugin-auto-enable.apply.ts
index 3486a86ab640..b01c9181fe68 100644
--- a/src/config/plugin-auto-enable.apply.ts
+++ b/src/config/plugin-auto-enable.apply.ts
@@ -1,3 +1,4 @@
+// Applies plugin auto-enable decisions to normalized config objects.
 import type { PluginDiscoveryResult } from "../plugins/discovery.js";
 import type { PluginManifestRegistry } from "../plugins/manifest-registry.js";
 import { detectPluginAutoEnableCandidates } from "./plugin-auto-enable.detect.js";
diff --git a/src/config/plugin-auto-enable.providers.test.ts b/src/config/plugin-auto-enable.providers.test.ts
index 52284c90764d..2f6803a67c97 100644
--- a/src/config/plugin-auto-enable.providers.test.ts
+++ b/src/config/plugin-auto-enable.providers.test.ts
@@ -1,3 +1,4 @@
+// Covers provider-driven plugin auto-enable decisions.
 import { afterAll, describe, expect, it } from "vitest";
 import {
   applyPluginAutoEnable,
diff --git a/src/config/runtime-snapshot.ts b/src/config/runtime-snapshot.ts
index 410bd83b9035..089d22cdbd03 100644
--- a/src/config/runtime-snapshot.ts
+++ b/src/config/runtime-snapshot.ts
@@ -1,3 +1,4 @@
+// Produces redacted runtime config snapshots for diagnostics and UI surfaces.
 import { createHash } from "node:crypto";
 import type { OpenClawConfig } from "./types.js";
 
diff --git a/src/config/talk.normalize.test.ts b/src/config/talk.normalize.test.ts
index efc4d7597750..36f35054a1a8 100644
--- a/src/config/talk.normalize.test.ts
+++ b/src/config/talk.normalize.test.ts
@@ -1,3 +1,4 @@
+// Verifies talk-mode config normalization behavior.
 import { describe, expect, it } from "vitest";
 import { TALK_TEST_PROVIDER_ID } from "../test-utils/talk-test-provider.js";
 import { buildTalkConfigResponse, normalizeTalkSection } from "./talk.js";
diff --git a/src/config/test-helpers.ts b/src/config/test-helpers.ts
index 20ca08317f8e..9542ca53afa4 100644
--- a/src/config/test-helpers.ts
+++ b/src/config/test-helpers.ts
@@ -1,3 +1,4 @@
+// Provides config test helpers for temporary homes and fixture writes.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { withTempHome as withTempHomeBase } from "openclaw/plugin-sdk/test-env";
diff --git a/src/config/types.auth.ts b/src/config/types.auth.ts
index e60390493c92..ec365337efa1 100644
--- a/src/config/types.auth.ts
+++ b/src/config/types.auth.ts
@@ -1,3 +1,4 @@
+// Defines auth profile configuration types.
 export type AuthProfileConfig = {
   /** Provider id this auth profile can satisfy. */
   provider: string;
diff --git a/src/config/zod-schema.channels-config.ts b/src/config/zod-schema.channels-config.ts
index 4be1cd6aff13..1981270e0869 100644
--- a/src/config/zod-schema.channels-config.ts
+++ b/src/config/zod-schema.channels-config.ts
@@ -1,3 +1,4 @@
+// Defines Zod schema fragments for channel configuration.
 import { z } from "zod";
 import type { ChannelsConfig } from "./types.channels.js";
 import { ChannelHeartbeatVisibilitySchema } from "./zod-schema.channels.js";
diff --git a/src/config/zod-schema.logging-levels.test.ts b/src/config/zod-schema.logging-levels.test.ts
index 7769433fd346..9c9aa7c66287 100644
--- a/src/config/zod-schema.logging-levels.test.ts
+++ b/src/config/zod-schema.logging-levels.test.ts
@@ -1,3 +1,4 @@
+// Verifies logging-level schema parsing and defaults.
 import { describe, expect, it } from "vitest";
 import { OpenClawSchema } from "./zod-schema.js";
 
diff --git a/src/config/zod-schema.proxy.ts b/src/config/zod-schema.proxy.ts
index cf1bdf3e5911..9be4ec695912 100644
--- a/src/config/zod-schema.proxy.ts
+++ b/src/config/zod-schema.proxy.ts
@@ -1,3 +1,4 @@
+// Defines proxy-related Zod schema fragments for config parsing.
 import { z } from "zod";
 import { sensitive } from "./zod-schema.sensitive.js";