docs: document config io helpers

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";
 

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";

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";
 

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";
 

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";

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";

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";

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,

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";

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;

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";

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";

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";

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> = {

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";
 

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";

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";

src/config/types.channel-messaging-common.ts

@@ -1,3 +1,4 @@
+// Defines common channel messaging configuration types.
 import type {
   BlockStreamingCoalesceConfig,
   ContextVisibilityMode,

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";
 

src/config/types.msteams.ts

@@ -1,3 +1,4 @@
+// Defines Microsoft Teams channel configuration types.
 import type {
   BlockStreamingCoalesceConfig,
   ChannelPreviewStreamingConfig,

src/config/types.slack.ts

@@ -1,3 +1,4 @@
+// Defines Slack channel configuration types.
 import type {
   ChannelStreamingBlockConfig,
   ChannelStreamingProgressConfig,

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";

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";
 

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";