From edb920b857cecd62a8bebc0e7c8a2c1a3b7211e4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 20:34:26 -0400
Subject: [PATCH] docs: document remaining src helpers

---
 src/context-engine/context-engine.test.ts            | 1 +
 src/context-engine/host-compat.test.ts               | 1 +
 src/i18n/registry.test.ts                            | 1 +
 src/interactive/payload.test.ts                      | 1 +
 src/interactive/payload.ts                           | 1 +
 src/memory-host-sdk/dreaming.test.ts                 | 1 +
 src/memory-host-sdk/dreaming.ts                      | 1 +
 src/memory-host-sdk/events.ts                        | 1 +
 src/memory-host-sdk/host/backend-config.test.ts      | 1 +
 src/plugin-state/plugin-state-store.e2e.test.ts      | 1 +
 src/plugin-state/plugin-state-store.runtime.test.ts  | 1 +
 src/plugin-state/plugin-state-store.sqlite.ts        | 1 +
 src/plugin-state/plugin-state-store.test-helpers.ts  | 1 +
 src/plugin-state/plugin-state-store.test.ts          | 1 +
 src/plugin-state/plugin-state-store.ts               | 1 +
 src/provider-runtime/operation-retry.test.ts         | 1 +
 src/provider-runtime/operation-retry.ts              | 1 +
 src/realtime-transcription/provider-registry.ts      | 1 +
 src/realtime-transcription/provider-types.ts         | 1 +
 src/realtime-transcription/websocket-session.test.ts | 1 +
 src/realtime-transcription/websocket-session.ts      | 1 +
 src/status/agent-runtime-label.ts                    | 1 +
 src/status/fallback-notice-state.ts                  | 1 +
 src/status/status-message.test.ts                    | 1 +
 src/status/status-message.ts                         | 1 +
 src/status/status-text.ts                            | 1 +
 src/status/status-text.types.ts                      | 1 +
 src/web-search/runtime-types.ts                      | 1 +
 src/web-search/runtime.test.ts                       | 1 +
 src/web-search/runtime.ts                            | 1 +
 30 files changed, 30 insertions(+)

diff --git a/src/context-engine/context-engine.test.ts b/src/context-engine/context-engine.test.ts
index 95c00bede0e6..a41b6b1e5a9b 100644
--- a/src/context-engine/context-engine.test.ts
+++ b/src/context-engine/context-engine.test.ts
@@ -1,3 +1,4 @@
+// Context engine tests cover context extraction and prompt context assembly.
 import type { AgentMessage } from "openclaw/plugin-sdk/agent-core";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { MemoryCitationsMode } from "../config/types.memory.js";
diff --git a/src/context-engine/host-compat.test.ts b/src/context-engine/host-compat.test.ts
index abdb517732b0..8b3a8155245e 100644
--- a/src/context-engine/host-compat.test.ts
+++ b/src/context-engine/host-compat.test.ts
@@ -1,3 +1,4 @@
+// Context engine host compatibility tests cover host API compatibility behavior.
 import { describe, expect, it } from "vitest";
 import {
   assertContextEngineHostSupport,
diff --git a/src/i18n/registry.test.ts b/src/i18n/registry.test.ts
index ea305c9c8dbf..03ef1bef47bf 100644
--- a/src/i18n/registry.test.ts
+++ b/src/i18n/registry.test.ts
@@ -1,3 +1,4 @@
+// I18n registry tests cover locale bundle lookup and fallback behavior.
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
diff --git a/src/interactive/payload.test.ts b/src/interactive/payload.test.ts
index 3119cbf0a527..a3200fb719b6 100644
--- a/src/interactive/payload.test.ts
+++ b/src/interactive/payload.test.ts
@@ -1,3 +1,4 @@
+// Interactive payload tests cover validation of interactive response payloads.
 import { describe, expect, it } from "vitest";
 import {
   hasReplyChannelData,
diff --git a/src/interactive/payload.ts b/src/interactive/payload.ts
index f835be000b03..d33e4c87d243 100644
--- a/src/interactive/payload.ts
+++ b/src/interactive/payload.ts
@@ -1,3 +1,4 @@
+// Interactive payload helpers normalize structured interactive UI payloads.
 import { asOptionalRecord as toRecord } from "@openclaw/normalization-core/record-coerce";
 import {
   normalizeOptionalLowercaseString,
diff --git a/src/memory-host-sdk/dreaming.test.ts b/src/memory-host-sdk/dreaming.test.ts
index f3654920fea9..80d0744af0b9 100644
--- a/src/memory-host-sdk/dreaming.test.ts
+++ b/src/memory-host-sdk/dreaming.test.ts
@@ -1,3 +1,4 @@
+// Memory host dreaming tests cover dreaming artifact persistence and lookup.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/memory-host-sdk/dreaming.ts b/src/memory-host-sdk/dreaming.ts
index 8f01c6e734fa..fdd5ad48e3f4 100644
--- a/src/memory-host-sdk/dreaming.ts
+++ b/src/memory-host-sdk/dreaming.ts
@@ -1,3 +1,4 @@
+// Memory host dreaming helpers record and load memory dreaming artifacts.
 import path from "node:path";
 import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";
 import {
diff --git a/src/memory-host-sdk/events.ts b/src/memory-host-sdk/events.ts
index f95662055481..50424ea58168 100644
--- a/src/memory-host-sdk/events.ts
+++ b/src/memory-host-sdk/events.ts
@@ -1,3 +1,4 @@
+// Memory host event helpers append and read memory host event logs.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { appendRegularFile } from "../infra/fs-safe.js";
diff --git a/src/memory-host-sdk/host/backend-config.test.ts b/src/memory-host-sdk/host/backend-config.test.ts
index fe6bdcf46fc8..3c784feaf845 100644
--- a/src/memory-host-sdk/host/backend-config.test.ts
+++ b/src/memory-host-sdk/host/backend-config.test.ts
@@ -1,3 +1,4 @@
+// Memory host backend config tests cover backend configuration normalization.
 import { describe, expect, it } from "vitest";
 import { resolveMemoryBackendConfig as packageResolveMemoryBackendConfig } from "../../../packages/memory-host-sdk/src/host/backend-config.js";
 import { resolveMemoryBackendConfig } from "./backend-config.js";
diff --git a/src/plugin-state/plugin-state-store.e2e.test.ts b/src/plugin-state/plugin-state-store.e2e.test.ts
index 2a0335758d40..5925548aacc3 100644
--- a/src/plugin-state/plugin-state-store.e2e.test.ts
+++ b/src/plugin-state/plugin-state-store.e2e.test.ts
@@ -1,3 +1,4 @@
+// Plugin state store E2E tests cover persisted plugin state across runtime calls.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
 import {
diff --git a/src/plugin-state/plugin-state-store.runtime.test.ts b/src/plugin-state/plugin-state-store.runtime.test.ts
index 79960743cfbe..3bf9e219ea50 100644
--- a/src/plugin-state/plugin-state-store.runtime.test.ts
+++ b/src/plugin-state/plugin-state-store.runtime.test.ts
@@ -1,3 +1,4 @@
+// Plugin state runtime tests cover runtime-backed plugin state storage.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resolveStateDir } from "../config/paths.js";
 import type { PluginRecord } from "../plugins/registry-types.js";
diff --git a/src/plugin-state/plugin-state-store.sqlite.ts b/src/plugin-state/plugin-state-store.sqlite.ts
index 4fcfe1418cec..a805065a1f6b 100644
--- a/src/plugin-state/plugin-state-store.sqlite.ts
+++ b/src/plugin-state/plugin-state-store.sqlite.ts
@@ -1,3 +1,4 @@
+// Plugin state SQLite helpers persist plugin state in the OpenClaw state database.
 import type { DatabaseSync } from "node:sqlite";
 import { resolveExpiresAtMsFromDurationMs } from "@openclaw/normalization-core/number-coercion";
 import type { Insertable, Selectable } from "kysely";
diff --git a/src/plugin-state/plugin-state-store.test-helpers.ts b/src/plugin-state/plugin-state-store.test-helpers.ts
index a67c43578bf5..ea45be16570b 100644
--- a/src/plugin-state/plugin-state-store.test-helpers.ts
+++ b/src/plugin-state/plugin-state-store.test-helpers.ts
@@ -1,3 +1,4 @@
+// Plugin state test helpers seed SQLite plugin state fixtures.
 import { seedPluginStateDatabaseEntriesForTests } from "./plugin-state-store.sqlite.js";
 
 // Test-only seed helpers for plugin state. Values are serialized through the
diff --git a/src/plugin-state/plugin-state-store.test.ts b/src/plugin-state/plugin-state-store.test.ts
index 0c125e7ef0d9..5e2708e25167 100644
--- a/src/plugin-state/plugin-state-store.test.ts
+++ b/src/plugin-state/plugin-state-store.test.ts
@@ -1,3 +1,4 @@
+// Plugin state store tests cover per-plugin persisted state reads and writes.
 import { rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion";
diff --git a/src/plugin-state/plugin-state-store.ts b/src/plugin-state/plugin-state-store.ts
index f3244b0ea83d..d06e3392e5fb 100644
--- a/src/plugin-state/plugin-state-store.ts
+++ b/src/plugin-state/plugin-state-store.ts
@@ -1,3 +1,4 @@
+// Plugin state store exposes persisted per-plugin state operations.
 import { closeOpenClawStateDatabaseForTest } from "../state/openclaw-state-db.js";
 import {
   clearPluginStateDatabaseForTests,
diff --git a/src/provider-runtime/operation-retry.test.ts b/src/provider-runtime/operation-retry.test.ts
index a85035712d1c..4aa65df314b6 100644
--- a/src/provider-runtime/operation-retry.test.ts
+++ b/src/provider-runtime/operation-retry.test.ts
@@ -1,3 +1,4 @@
+// Provider operation retry tests cover retry timing and abort behavior.
 import { describe, expect, it, vi } from "vitest";
 import {
   executeProviderOperationWithRetry,
diff --git a/src/provider-runtime/operation-retry.ts b/src/provider-runtime/operation-retry.ts
index aa0895b4af15..88ee93106585 100644
--- a/src/provider-runtime/operation-retry.ts
+++ b/src/provider-runtime/operation-retry.ts
@@ -1,3 +1,4 @@
+// Provider operation retry helpers run retryable provider operations with backoff.
 import { sleepWithAbort } from "../infra/backoff.js";
 import { formatErrorMessage } from "../infra/errors.js";
 
diff --git a/src/realtime-transcription/provider-registry.ts b/src/realtime-transcription/provider-registry.ts
index 6402d104a9fb..b7173d3519bc 100644
--- a/src/realtime-transcription/provider-registry.ts
+++ b/src/realtime-transcription/provider-registry.ts
@@ -1,3 +1,4 @@
+// Realtime transcription provider registry stores transcription provider factories.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   resolvePluginCapabilityProvider,
diff --git a/src/realtime-transcription/provider-types.ts b/src/realtime-transcription/provider-types.ts
index 446c620edd9d..5513808a1ddc 100644
--- a/src/realtime-transcription/provider-types.ts
+++ b/src/realtime-transcription/provider-types.ts
@@ -1,3 +1,4 @@
+// Realtime transcription provider types describe streaming transcription providers.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
 // Public contracts for realtime transcription provider plugins and sessions.
diff --git a/src/realtime-transcription/websocket-session.test.ts b/src/realtime-transcription/websocket-session.test.ts
index 42b9bd3c4f49..3fd922ca37c3 100644
--- a/src/realtime-transcription/websocket-session.test.ts
+++ b/src/realtime-transcription/websocket-session.test.ts
@@ -1,3 +1,4 @@
+// Realtime transcription websocket tests cover websocket session lifecycle.
 import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/realtime-transcription/websocket-session.ts b/src/realtime-transcription/websocket-session.ts
index f76386f81fe3..1df87d310303 100644
--- a/src/realtime-transcription/websocket-session.ts
+++ b/src/realtime-transcription/websocket-session.ts
@@ -1,3 +1,4 @@
+// Realtime transcription websocket session streams audio to transcription providers.
 import { randomUUID } from "node:crypto";
 import WebSocket, { type RawData } from "ws";
 import { createDebugProxyWebSocketAgent, resolveDebugProxySettings } from "../proxy-capture/env.js";
diff --git a/src/status/agent-runtime-label.ts b/src/status/agent-runtime-label.ts
index 75f074c29cd7..2355da56e3c8 100644
--- a/src/status/agent-runtime-label.ts
+++ b/src/status/agent-runtime-label.ts
@@ -1,3 +1,4 @@
+// Agent runtime label helpers format provider, model, and runtime labels.
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
diff --git a/src/status/fallback-notice-state.ts b/src/status/fallback-notice-state.ts
index 3135e9b5c156..ca8cd4fa7f0c 100644
--- a/src/status/fallback-notice-state.ts
+++ b/src/status/fallback-notice-state.ts
@@ -1,3 +1,4 @@
+// Fallback notice state helpers track fallback notices shown to users.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { areRuntimeModelRefsEquivalent } from "../agents/model-runtime-aliases.js";
 import type { SessionEntry } from "../config/sessions.js";
diff --git a/src/status/status-message.test.ts b/src/status/status-message.test.ts
index 99d48d904af5..df8695d6e5dc 100644
--- a/src/status/status-message.test.ts
+++ b/src/status/status-message.test.ts
@@ -1,3 +1,4 @@
+// Status message tests cover status message formatting and persistence.
 import { describe, expect, it } from "vitest";
 import { formatFastModeLabel } from "./status-labels.js";
 
diff --git a/src/status/status-message.ts b/src/status/status-message.ts
index aa1fbb518b38..6a983c7ae483 100644
--- a/src/status/status-message.ts
+++ b/src/status/status-message.ts
@@ -1,3 +1,4 @@
+// Status message helpers read and format stored status messages.
 import fs from "node:fs";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/status/status-text.ts b/src/status/status-text.ts
index 14a2817d73c8..bcc113328e24 100644
--- a/src/status/status-text.ts
+++ b/src/status/status-text.ts
@@ -1,3 +1,4 @@
+// Status text helpers render runtime status summaries for CLI output.
 import os from "node:os";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import {
diff --git a/src/status/status-text.types.ts b/src/status/status-text.types.ts
index 676d7908c5d0..4b979bb9c73d 100644
--- a/src/status/status-text.types.ts
+++ b/src/status/status-text.types.ts
@@ -1,3 +1,4 @@
+// Status text types describe runtime status records used by status rendering.
 import type {
   ElevatedLevel,
   ReasoningLevel,
diff --git a/src/web-search/runtime-types.ts b/src/web-search/runtime-types.ts
index 03b46eab1c78..051128d0f522 100644
--- a/src/web-search/runtime-types.ts
+++ b/src/web-search/runtime-types.ts
@@ -1,3 +1,4 @@
+// Web search runtime types describe search provider factories and dependencies.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type {
   PluginWebSearchProviderEntry,
diff --git a/src/web-search/runtime.test.ts b/src/web-search/runtime.test.ts
index 97a15f7d4a24..cf749c2f725f 100644
--- a/src/web-search/runtime.test.ts
+++ b/src/web-search/runtime.test.ts
@@ -1,3 +1,4 @@
+// Web search runtime tests cover provider resolution and search execution.
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/web-search/runtime.ts b/src/web-search/runtime.ts
index 9f28bdac569d..6cef7935143c 100644
--- a/src/web-search/runtime.ts
+++ b/src/web-search/runtime.ts
@@ -1,3 +1,4 @@
+// Web search runtime resolves configured search providers and executes searches.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,