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

---
 src/config/config-paths.ts                                       | 1 +
 src/config/config.identity-avatar.test.ts                        | 1 +
 ...fig.legacy-config-detection.rejects-routing-allowfrom.test.ts | 1 +
 src/config/config.meta-timestamp-coercion.test.ts                | 1 +
 src/config/io.clobber-snapshot.test.ts                           | 1 +
 src/config/io.compat.test.ts                                     | 1 +
 src/config/io.observe-recovery.test.ts                           | 1 +
 src/config/io.owner-display-secret.test.ts                       | 1 +
 src/config/io.write-prepare.ts                                   | 1 +
 src/config/legacy.shared.ts                                      | 1 +
 src/config/plugin-auto-enable.prefer-over.test.ts                | 1 +
 src/config/schema-base.ts                                        | 1 +
 src/config/schema.base.generated.test.ts                         | 1 +
 src/config/schema.labels.ts                                      | 1 +
 src/config/schema.shared.test.ts                                 | 1 +
 src/config/state-dir-dotenv.test.ts                              | 1 +
 src/config/state-dir-dotenv.ts                                   | 1 +
 src/config/types.channel-messaging-common.ts                     | 1 +
 src/config/types.messages.ts                                     | 1 +
 src/config/types.msteams.ts                                      | 1 +
 src/config/types.slack.ts                                        | 1 +
 src/config/validation.allowed-values.test.ts                     | 1 +
 src/config/validation.legacy-rules-fast-path.test.ts             | 1 +
 src/config/zod-schema.post-compaction-guard.test.ts              | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/config/config-paths.ts b/src/config/config-paths.ts
index d6e672588540..22e3a14410cf 100644
--- a/src/config/config-paths.ts
+++ b/src/config/config-paths.ts
@@ -1,3 +1,4 @@
+// Resolves and classifies config paths for reads, writes, and metadata.
 import { isPlainObject } from "../utils.js";
 import { isBlockedObjectKey } from "./prototype-keys.js";
 
diff --git a/src/config/config.identity-avatar.test.ts b/src/config/config.identity-avatar.test.ts
index 08e85d62ed0c..2fef4ec90eb1 100644
--- a/src/config/config.identity-avatar.test.ts
+++ b/src/config/config.identity-avatar.test.ts
@@ -1,3 +1,4 @@
+// Covers identity avatar config normalization and file-path handling.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { withTempHome } from "./test-helpers.js";
diff --git a/src/config/config.legacy-config-detection.rejects-routing-allowfrom.test.ts b/src/config/config.legacy-config-detection.rejects-routing-allowfrom.test.ts
index 88f3fbb08b75..80d76502d26b 100644
--- a/src/config/config.legacy-config-detection.rejects-routing-allowfrom.test.ts
+++ b/src/config/config.legacy-config-detection.rejects-routing-allowfrom.test.ts
@@ -1,3 +1,4 @@
+// Regresses rejection of legacy routing allowFrom config.
 import { describe, expect, it } from "vitest";
 import { validateConfigObject } from "./validation.js";
 
diff --git a/src/config/config.meta-timestamp-coercion.test.ts b/src/config/config.meta-timestamp-coercion.test.ts
index d1e6107c95d4..1c184acd868e 100644
--- a/src/config/config.meta-timestamp-coercion.test.ts
+++ b/src/config/config.meta-timestamp-coercion.test.ts
@@ -1,3 +1,4 @@
+// Verifies config metadata timestamp coercion behavior.
 import { describe, expect, it } from "vitest";
 import { validateConfigObject } from "./validation.js";
 
diff --git a/src/config/io.clobber-snapshot.test.ts b/src/config/io.clobber-snapshot.test.ts
index f1424208d6a0..a08e73f65f44 100644
--- a/src/config/io.clobber-snapshot.test.ts
+++ b/src/config/io.clobber-snapshot.test.ts
@@ -1,3 +1,4 @@
+// Covers config IO clobber snapshot handling during writes.
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
diff --git a/src/config/io.compat.test.ts b/src/config/io.compat.test.ts
index 33eb727de903..d9eeea70f6b2 100644
--- a/src/config/io.compat.test.ts
+++ b/src/config/io.compat.test.ts
@@ -1,3 +1,4 @@
+// Verifies config IO compatibility loading and migration behavior.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/config/io.observe-recovery.test.ts b/src/config/io.observe-recovery.test.ts
index 07ea6a7b7db2..922cfda5312d 100644
--- a/src/config/io.observe-recovery.test.ts
+++ b/src/config/io.observe-recovery.test.ts
@@ -1,3 +1,4 @@
+// Covers config IO recovery observation after corrupt or missing files.
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
diff --git a/src/config/io.owner-display-secret.test.ts b/src/config/io.owner-display-secret.test.ts
index 8dac53cf3fc5..2ec2555c1892 100644
--- a/src/config/io.owner-display-secret.test.ts
+++ b/src/config/io.owner-display-secret.test.ts
@@ -1,3 +1,4 @@
+// Verifies owner display secrets stay redacted in config IO paths.
 import { describe, expect, it } from "vitest";
 import {
   type OwnerDisplaySecretRuntimeState,
diff --git a/src/config/io.write-prepare.ts b/src/config/io.write-prepare.ts
index 0b6b2ff544e4..32900fa922ac 100644
--- a/src/config/io.write-prepare.ts
+++ b/src/config/io.write-prepare.ts
@@ -1,3 +1,4 @@
+// Prepares config writes by diffing current state and preserving metadata.
 import { isDeepStrictEqual } from "node:util";
 import { normalizeConfiguredProviderCatalogModelId } from "@openclaw/model-catalog-core/provider-model-id-normalization";
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
diff --git a/src/config/legacy.shared.ts b/src/config/legacy.shared.ts
index db1b7ce06358..3833ff5edce4 100644
--- a/src/config/legacy.shared.ts
+++ b/src/config/legacy.shared.ts
@@ -1,3 +1,4 @@
+// Defines shared legacy config rule contracts for detection and migration.
 export type LegacyConfigRule = {
   path: string[];
   message: string;
diff --git a/src/config/plugin-auto-enable.prefer-over.test.ts b/src/config/plugin-auto-enable.prefer-over.test.ts
index d64564cda9ee..e3a544853243 100644
--- a/src/config/plugin-auto-enable.prefer-over.test.ts
+++ b/src/config/plugin-auto-enable.prefer-over.test.ts
@@ -1,3 +1,4 @@
+// Verifies plugin auto-enable prefer-over precedence rules.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/config/schema-base.ts b/src/config/schema-base.ts
index ebfdf2b09d1b..a1eef38cb7bc 100644
--- a/src/config/schema-base.ts
+++ b/src/config/schema-base.ts
@@ -1,3 +1,4 @@
+// Builds base config schema metadata shared across generated config surfaces.
 import { isSensitiveUrlConfigPath } from "@openclaw/net-policy/redact-sensitive-url";
 import { VERSION } from "../version.js";
 import { FIELD_HELP } from "./schema.help.js";
diff --git a/src/config/schema.base.generated.test.ts b/src/config/schema.base.generated.test.ts
index c1e4ee194287..2a1fc750477c 100644
--- a/src/config/schema.base.generated.test.ts
+++ b/src/config/schema.base.generated.test.ts
@@ -1,3 +1,4 @@
+// Verifies generated base config schema snapshots and sensitive redaction.
 import { SENSITIVE_URL_HINT_TAG } from "@openclaw/net-policy/redact-sensitive-url";
 import { describe, expect, it } from "vitest";
 import { computeBaseConfigSchemaResponse } from "./schema-base.js";
diff --git a/src/config/schema.labels.ts b/src/config/schema.labels.ts
index 475738d12b19..03947211776e 100644
--- a/src/config/schema.labels.ts
+++ b/src/config/schema.labels.ts
@@ -1,3 +1,4 @@
+// Defines user-facing config field labels used by schema metadata.
 import { MEDIA_AUDIO_FIELD_LABELS } from "./media-audio-field-metadata.js";
 
 export const FIELD_LABELS: Record<string, string> = {
diff --git a/src/config/schema.shared.test.ts b/src/config/schema.shared.test.ts
index d566bfd55f5a..30414298af3b 100644
--- a/src/config/schema.shared.test.ts
+++ b/src/config/schema.shared.test.ts
@@ -1,3 +1,4 @@
+// Covers shared config schema fragments and defaults.
 import { describe, expect, it } from "vitest";
 import { findWildcardHintMatch, schemaHasChildren } from "./schema.shared.js";
 
diff --git a/src/config/state-dir-dotenv.test.ts b/src/config/state-dir-dotenv.test.ts
index c5a131866a83..4fb4718eea1e 100644
--- a/src/config/state-dir-dotenv.test.ts
+++ b/src/config/state-dir-dotenv.test.ts
@@ -1,3 +1,4 @@
+// Covers state-directory dotenv discovery, parsing, and merge behavior.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/config/state-dir-dotenv.ts b/src/config/state-dir-dotenv.ts
index cd228e79333a..9de891417715 100644
--- a/src/config/state-dir-dotenv.ts
+++ b/src/config/state-dir-dotenv.ts
@@ -1,3 +1,4 @@
+// Loads state-directory dotenv entries used by config and runtime startup.
 import fs from "node:fs";
 import path from "node:path";
 import dotenv from "dotenv";
diff --git a/src/config/types.channel-messaging-common.ts b/src/config/types.channel-messaging-common.ts
index 91688c16bdb4..fb1ef8b7927a 100644
--- a/src/config/types.channel-messaging-common.ts
+++ b/src/config/types.channel-messaging-common.ts
@@ -1,3 +1,4 @@
+// Defines common channel messaging configuration types.
 import type {
   BlockStreamingCoalesceConfig,
   ContextVisibilityMode,
diff --git a/src/config/types.messages.ts b/src/config/types.messages.ts
index 325705a1870b..7e6353688a53 100644
--- a/src/config/types.messages.ts
+++ b/src/config/types.messages.ts
@@ -1,3 +1,4 @@
+// Defines message queue and delivery configuration types.
 import type { QueueDropPolicy, QueueMode, QueueModeByProvider } from "./types.queue.js";
 import type { TtsConfig } from "./types.tts.js";
 
diff --git a/src/config/types.msteams.ts b/src/config/types.msteams.ts
index 8cbba2285171..c2a7a556f135 100644
--- a/src/config/types.msteams.ts
+++ b/src/config/types.msteams.ts
@@ -1,3 +1,4 @@
+// Defines Microsoft Teams channel configuration types.
 import type {
   BlockStreamingCoalesceConfig,
   ChannelPreviewStreamingConfig,
diff --git a/src/config/types.slack.ts b/src/config/types.slack.ts
index 3cdbfee76d73..f96c49801c57 100644
--- a/src/config/types.slack.ts
+++ b/src/config/types.slack.ts
@@ -1,3 +1,4 @@
+// Defines Slack channel configuration types.
 import type {
   ChannelStreamingBlockConfig,
   ChannelStreamingProgressConfig,
diff --git a/src/config/validation.allowed-values.test.ts b/src/config/validation.allowed-values.test.ts
index e16390231d20..cf21e48fd926 100644
--- a/src/config/validation.allowed-values.test.ts
+++ b/src/config/validation.allowed-values.test.ts
@@ -1,3 +1,4 @@
+// Verifies config validation rejects unsupported enumerated values.
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
 import { testing, validateConfigObjectRaw } from "./validation.js";
diff --git a/src/config/validation.legacy-rules-fast-path.test.ts b/src/config/validation.legacy-rules-fast-path.test.ts
index 220f3b7ba961..8b9b03f000e0 100644
--- a/src/config/validation.legacy-rules-fast-path.test.ts
+++ b/src/config/validation.legacy-rules-fast-path.test.ts
@@ -1,3 +1,4 @@
+// Verifies legacy-rule validation uses the fast path for known config shapes.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { LegacyConfigRule } from "./legacy.shared.js";
 
diff --git a/src/config/zod-schema.post-compaction-guard.test.ts b/src/config/zod-schema.post-compaction-guard.test.ts
index 9ad73816fb08..f0f5c7f853c2 100644
--- a/src/config/zod-schema.post-compaction-guard.test.ts
+++ b/src/config/zod-schema.post-compaction-guard.test.ts
@@ -1,3 +1,4 @@
+// Guards post-compaction config schema behavior against regressions.
 import { describe, expect, it } from "vitest";
 import { ToolsSchema } from "./zod-schema.agent-runtime.js";
 import { OpenClawSchema } from "./zod-schema.js";