diff --git a/src/context-engine/context-engine.test.ts b/src/context-engine/context-engine.test.ts
index 95c00bede0e..a41b6b1e5a9 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 abdb517732b..8b3a8155245 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 ea305c9c8db..03ef1bef47b 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 3119cbf0a52..a3200fb719b 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 f835be000b0..d33e4c87d24 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 f3654920fea..80d0744af0b 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 8f01c6e734f..fdd5ad48e3f 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 f9566205548..50424ea5816 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 fe6bdcf46fc..3c784feaf84 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 2a0335758d4..5925548aacc 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 79960743cfb..3bf9e219ea5 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 4fcfe1418ce..a805065a1f6 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 a67c43578bf..ea45be16570 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 0c125e7ef0d..5e2708e2516 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 f3244b0ea83..d06e3392e5f 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 a85035712d1..4aa65df314b 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 aa0895b4af1..88ee9310658 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 6402d104a9f..b7173d3519b 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 446c620edd9..5513808a1dd 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 42b9bd3c4f4..3fd922ca37c 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 f76386f81fe..1df87d31030 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 75f074c29cd..2355da56e3c 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 3135e9b5c15..ca8cd4fa7f0 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 99d48d904af..df8695d6e5d 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 aa1fbb518b3..6a983c7ae48 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 14a2817d73c..bcc113328e2 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 676d7908c5d..4b979bb9c73 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 03b46eab1c7..051128d0f52 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 97a15f7d4a2..cf749c2f725 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 9f28bdac569..6cef7935143 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,