diff --git a/src/plugins/capability-runtime-vitest-shims/config-runtime.ts b/src/plugins/capability-runtime-vitest-shims/config-runtime.ts
index 7f68da182aeb..09de4b2f4b6d 100644
--- a/src/plugins/capability-runtime-vitest-shims/config-runtime.ts
+++ b/src/plugins/capability-runtime-vitest-shims/config-runtime.ts
@@ -1,3 +1,4 @@
+// Config-runtime Vitest shims expose lightweight config helpers for capability runtime tests.
 import { resolveActiveTalkProviderConfig } from "../../config/talk.js";
 import type { OpenClawConfig } from "../../config/types.js";
 
diff --git a/src/plugins/capability-runtime-vitest-shims/speech-core.ts b/src/plugins/capability-runtime-vitest-shims/speech-core.ts
index 411668956f48..c3e151bc0b01 100644
--- a/src/plugins/capability-runtime-vitest-shims/speech-core.ts
+++ b/src/plugins/capability-runtime-vitest-shims/speech-core.ts
@@ -1,3 +1,4 @@
+// Speech-core Vitest shims expose speech capability types without loading full runtime code.
 export type {
   SpeechDirectiveTokenParseContext,
   SpeechDirectiveTokenParseResult,
diff --git a/src/plugins/compat/registry.test.ts b/src/plugins/compat/registry.test.ts
index 3baf792e4aab..2cb6a5061c0c 100644
--- a/src/plugins/compat/registry.test.ts
+++ b/src/plugins/compat/registry.test.ts
@@ -1,3 +1,4 @@
+// Plugin compatibility registry tests cover compatibility metadata loading and validation.
 import fs from "node:fs";
 import { beforeAll, describe, expect, it } from "vitest";
 import { listGitTrackedFiles } from "../../test-utils/repo-files.js";
diff --git a/src/plugins/compat/registry.ts b/src/plugins/compat/registry.ts
index 30c1d7953c83..dfd6fb0cc89e 100644
--- a/src/plugins/compat/registry.ts
+++ b/src/plugins/compat/registry.ts
@@ -1,3 +1,4 @@
+// Plugin compatibility registry exposes known plugin compatibility metadata to doctor/update flows.
 import type { PluginCompatRecord } from "./types.js";
 
 const CHANNEL_RUNTIME_SDK_SURFACE = ["openclaw/plugin-sdk/channel", "runtime"].join("-");
diff --git a/src/plugins/compat/types.ts b/src/plugins/compat/types.ts
index 67b3a76de4cb..2be59f68dad2 100644
--- a/src/plugins/compat/types.ts
+++ b/src/plugins/compat/types.ts
@@ -1,3 +1,4 @@
+// Plugin compatibility types describe lifecycle status for plugin migration and deprecation checks.
 export type PluginCompatStatus = "active" | "deprecated" | "removal-pending" | "removed";
 
 export type PluginCompatOwner =
diff --git a/src/plugins/runtime/channel-runtime-contexts.ts b/src/plugins/runtime/channel-runtime-contexts.ts
index 517da9acdad0..78e02e264fbf 100644
--- a/src/plugins/runtime/channel-runtime-contexts.ts
+++ b/src/plugins/runtime/channel-runtime-contexts.ts
@@ -1,3 +1,4 @@
+// Channel runtime context helpers build plugin runtime context for channel execution.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type {
   ChannelRuntimeContextEvent,
diff --git a/src/plugins/runtime/gateway-bindings.ts b/src/plugins/runtime/gateway-bindings.ts
index 1b683cbd1d3e..bd7bf18c9929 100644
--- a/src/plugins/runtime/gateway-bindings.ts
+++ b/src/plugins/runtime/gateway-bindings.ts
@@ -1,3 +1,4 @@
+// Gateway binding helpers expose plugin runtime bindings through gateway-safe singletons.
 import { resolveGlobalSingleton } from "../../shared/global-singleton.js";
 import type { PluginRuntime } from "./types.js";
 
diff --git a/src/plugins/runtime/gateway-request-scope.test.ts b/src/plugins/runtime/gateway-request-scope.test.ts
index 6a291770fe40..f3ffb04ab6ff 100644
--- a/src/plugins/runtime/gateway-request-scope.test.ts
+++ b/src/plugins/runtime/gateway-request-scope.test.ts
@@ -1,3 +1,4 @@
+// Gateway request scope tests cover request-local plugin runtime context propagation.
 import { describe, expect, it, vi } from "vitest";
 import type { PluginRuntimeGatewayRequestScope } from "./gateway-request-scope.js";
 
diff --git a/src/plugins/runtime/gateway-request-scope.ts b/src/plugins/runtime/gateway-request-scope.ts
index 37b76df579df..a0a9914ef117 100644
--- a/src/plugins/runtime/gateway-request-scope.ts
+++ b/src/plugins/runtime/gateway-request-scope.ts
@@ -1,3 +1,4 @@
+// Gateway request scope tracks request-local plugin runtime context across async work.
 import { AsyncLocalStorage } from "node:async_hooks";
 import type {
   GatewayRequestContext,
diff --git a/src/plugins/runtime/index.test.ts b/src/plugins/runtime/index.test.ts
index af4c6339f7b8..6cbfd5599f18 100644
--- a/src/plugins/runtime/index.test.ts
+++ b/src/plugins/runtime/index.test.ts
@@ -1,3 +1,4 @@
+// Plugin runtime index tests cover runtime entrypoint exports and registry setup.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../agents/defaults.js";
 import {
diff --git a/src/plugins/runtime/load-context.ts b/src/plugins/runtime/load-context.ts
index a487ec17fc42..382e25a7e8ef 100644
--- a/src/plugins/runtime/load-context.ts
+++ b/src/plugins/runtime/load-context.ts
@@ -1,3 +1,4 @@
+// Plugin runtime load context helpers resolve agent and workspace facts for runtime activation.
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agents/agent-scope.js";
 import { getRuntimeConfig } from "../../config/config.js";
 import { applyPluginAutoEnable } from "../../config/plugin-auto-enable.js";
diff --git a/src/plugins/runtime/metadata-registry-loader.test.ts b/src/plugins/runtime/metadata-registry-loader.test.ts
index 147aa91c17b7..6d5436b2e335 100644
--- a/src/plugins/runtime/metadata-registry-loader.test.ts
+++ b/src/plugins/runtime/metadata-registry-loader.test.ts
@@ -1,3 +1,4 @@
+// Metadata registry loader tests cover metadata-only plugin registry assembly.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { PluginLoadOptions } from "../loader.js";
 
diff --git a/src/plugins/runtime/metadata-registry-loader.ts b/src/plugins/runtime/metadata-registry-loader.ts
index 69776e6ec6f2..4562bb9c7941 100644
--- a/src/plugins/runtime/metadata-registry-loader.ts
+++ b/src/plugins/runtime/metadata-registry-loader.ts
@@ -1,3 +1,4 @@
+// Metadata registry loader builds plugin metadata registries without activating runtime barrels.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { loadOpenClawPlugins } from "../loader.js";
 import type { PluginManifestRegistry } from "../manifest-registry.js";
diff --git a/src/plugins/runtime/runtime-agent.ts b/src/plugins/runtime/runtime-agent.ts
index 70576a9325bf..6fbe68235306 100644
--- a/src/plugins/runtime/runtime-agent.ts
+++ b/src/plugins/runtime/runtime-agent.ts
@@ -1,3 +1,4 @@
+// Runtime agent helpers resolve agent-scoped directories and config for plugin execution.
 import { resolveAgentDir, resolveAgentWorkspaceDir } from "../../agents/agent-scope.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../agents/defaults.js";
 import { resolveAgentIdentity } from "../../agents/identity.js";
diff --git a/src/plugins/runtime/runtime-channel.test.ts b/src/plugins/runtime/runtime-channel.test.ts
index 90a7aed52d81..0434828c9d50 100644
--- a/src/plugins/runtime/runtime-channel.test.ts
+++ b/src/plugins/runtime/runtime-channel.test.ts
@@ -1,3 +1,4 @@
+// Runtime channel tests cover channel plugin runtime send, reply, and capability behavior.
 import { describe, expect, it, vi } from "vitest";
 import { createRuntimeChannel } from "./runtime-channel.js";
 
diff --git a/src/plugins/runtime/runtime-channel.ts b/src/plugins/runtime/runtime-channel.ts
index be82619782b1..51241b9a3664 100644
--- a/src/plugins/runtime/runtime-channel.ts
+++ b/src/plugins/runtime/runtime-channel.ts
@@ -1,3 +1,4 @@
+// Runtime channel helpers adapt channel plugin APIs into core channel send and reply flows.
 import { convertMarkdownTables } from "../../../packages/markdown-core/src/tables.js";
 import { resolveEffectiveMessagesConfig, resolveHumanDelayConfig } from "../../agents/identity.js";
 import {
diff --git a/src/plugins/runtime/runtime-config.test.ts b/src/plugins/runtime/runtime-config.test.ts
index 07440b55dab1..3a87a9ee54b2 100644
--- a/src/plugins/runtime/runtime-config.test.ts
+++ b/src/plugins/runtime/runtime-config.test.ts
@@ -1,3 +1,4 @@
+// Runtime config tests cover plugin runtime config normalization and lookup.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 
diff --git a/src/plugins/runtime/runtime-llm.runtime.ts b/src/plugins/runtime/runtime-llm.runtime.ts
index 939721cc323b..0b8dc6b1da7a 100644
--- a/src/plugins/runtime/runtime-llm.runtime.ts
+++ b/src/plugins/runtime/runtime-llm.runtime.ts
@@ -1,3 +1,4 @@
+// Runtime LLM helpers adapt plugin provider hooks into the core model runtime.
 import { asFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { modelKey } from "../../agents/model-ref-shared.js";
diff --git a/src/plugins/runtime/runtime-logging.test.ts b/src/plugins/runtime/runtime-logging.test.ts
index 51b247c7675e..3a12079c5742 100644
--- a/src/plugins/runtime/runtime-logging.test.ts
+++ b/src/plugins/runtime/runtime-logging.test.ts
@@ -1,3 +1,4 @@
+// Runtime logging tests cover plugin runtime log routing and verbosity behavior.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loggingMocks = vi.hoisted(() => {
diff --git a/src/plugins/runtime/runtime-logging.ts b/src/plugins/runtime/runtime-logging.ts
index 51bb564b7989..1e3652dcdf6d 100644
--- a/src/plugins/runtime/runtime-logging.ts
+++ b/src/plugins/runtime/runtime-logging.ts
@@ -1,3 +1,4 @@
+// Runtime logging helpers route plugin runtime logs through OpenClaw verbosity controls.
 import { shouldLogVerbose } from "../../globals.js";
 import { getChildLogger } from "../../logging.js";
 import { normalizeLogLevel } from "../../logging/levels.js";
diff --git a/src/plugins/runtime/runtime-model-auth.runtime.test.ts b/src/plugins/runtime/runtime-model-auth.runtime.test.ts
index 77d67b3351d0..d3733b2df30d 100644
--- a/src/plugins/runtime/runtime-model-auth.runtime.test.ts
+++ b/src/plugins/runtime/runtime-model-auth.runtime.test.ts
@@ -1,3 +1,4 @@
+// Runtime model auth tests cover provider auth resolution inside plugin runtime loading.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const hoisted = vi.hoisted(() => ({
diff --git a/src/plugins/runtime/runtime-plugin-boundary.ts b/src/plugins/runtime/runtime-plugin-boundary.ts
index 8a860c5042e4..72e967e2a6eb 100644
--- a/src/plugins/runtime/runtime-plugin-boundary.ts
+++ b/src/plugins/runtime/runtime-plugin-boundary.ts
@@ -1,3 +1,4 @@
+// Runtime plugin boundary helpers enforce package and source boundaries for runtime loading.
 import fs from "node:fs";
 import path from "node:path";
 import { getRuntimeConfig } from "../../config/config.js";
diff --git a/src/plugins/runtime/runtime-registry-loader.test.ts b/src/plugins/runtime/runtime-registry-loader.test.ts
index 43293f2ddbc8..eac61f9dda64 100644
--- a/src/plugins/runtime/runtime-registry-loader.test.ts
+++ b/src/plugins/runtime/runtime-registry-loader.test.ts
@@ -1,3 +1,4 @@
+// Runtime registry loader tests cover plugin runtime assembly and activation boundaries.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createEmptyPluginRegistry } from "../registry.js";
 
diff --git a/src/plugins/runtime/runtime-registry-loader.ts b/src/plugins/runtime/runtime-registry-loader.ts
index 6dc7368e7865..185518546f4b 100644
--- a/src/plugins/runtime/runtime-registry-loader.ts
+++ b/src/plugins/runtime/runtime-registry-loader.ts
@@ -1,3 +1,4 @@
+// Runtime registry loader assembles activated plugin runtimes from config and registry metadata.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { withActivatedPluginIds } from "../activation-context.js";
 import {
diff --git a/src/plugins/runtime/runtime-task-test-harness.ts b/src/plugins/runtime/runtime-task-test-harness.ts
index 678ae144b602..2dcdd65469e2 100644
--- a/src/plugins/runtime/runtime-task-test-harness.ts
+++ b/src/plugins/runtime/runtime-task-test-harness.ts
@@ -1,3 +1,4 @@
+// Runtime task test harness helpers build mocked plugin runtimes for task-flow tests.
 import { vi } from "vitest";
 import { resetDetachedTaskLifecycleRuntimeForTests } from "../../tasks/detached-task-runtime.js";
 import {
diff --git a/src/plugins/runtime/runtime-taskflow.test.ts b/src/plugins/runtime/runtime-taskflow.test.ts
index e5fe7fd5c105..0fd752d97757 100644
--- a/src/plugins/runtime/runtime-taskflow.test.ts
+++ b/src/plugins/runtime/runtime-taskflow.test.ts
@@ -1,3 +1,4 @@
+// Runtime task-flow tests cover plugin task-flow registration and execution behavior.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { getTaskFlowById } from "../../tasks/task-flow-registry.js";
 import { getTaskById } from "../../tasks/task-registry.js";
diff --git a/src/plugins/runtime/runtime-taskflow.ts b/src/plugins/runtime/runtime-taskflow.ts
index 6a9c8529fd19..464fb06a4131 100644
--- a/src/plugins/runtime/runtime-taskflow.ts
+++ b/src/plugins/runtime/runtime-taskflow.ts
@@ -1,3 +1,4 @@
+// Runtime task-flow helpers adapt plugin task descriptors into executable task flows.
 import {
   cancelFlowByIdForOwner,
   getFlowTaskSummary,
diff --git a/src/plugins/runtime/runtime-tasks.test.ts b/src/plugins/runtime/runtime-tasks.test.ts
index 1fe013d3151f..70565a1344e7 100644
--- a/src/plugins/runtime/runtime-tasks.test.ts
+++ b/src/plugins/runtime/runtime-tasks.test.ts
@@ -1,3 +1,4 @@
+// Runtime task tests cover plugin task runtime registration, invocation, and cleanup.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   getDetachedTaskLifecycleRuntime,
diff --git a/src/plugins/runtime/runtime-tasks.types.ts b/src/plugins/runtime/runtime-tasks.types.ts
index 106afd068409..1477f056eb73 100644
--- a/src/plugins/runtime/runtime-tasks.types.ts
+++ b/src/plugins/runtime/runtime-tasks.types.ts
@@ -1,3 +1,4 @@
+// Runtime task types describe plugin task runtime config and invocation options.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { TaskDeliveryState } from "../../tasks/task-registry.types.js";
 import type { OpenClawPluginToolContext } from "../tool-types.js";
diff --git a/src/plugins/runtime/runtime-web-channel-plugin.test.ts b/src/plugins/runtime/runtime-web-channel-plugin.test.ts
index 6962945d37ad..c5f94f272e9a 100644
--- a/src/plugins/runtime/runtime-web-channel-plugin.test.ts
+++ b/src/plugins/runtime/runtime-web-channel-plugin.test.ts
@@ -1,3 +1,4 @@
+// Runtime web-channel plugin tests cover web channel plugin activation and runtime behavior.
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 afterEach(() => {
diff --git a/src/plugins/runtime/standalone-runtime-registry-loader.test.ts b/src/plugins/runtime/standalone-runtime-registry-loader.test.ts
index 5256aee3a0e0..da456ff12d72 100644
--- a/src/plugins/runtime/standalone-runtime-registry-loader.test.ts
+++ b/src/plugins/runtime/standalone-runtime-registry-loader.test.ts
@@ -1,3 +1,4 @@
+// Standalone runtime registry loader tests cover registry loading outside gateway startup.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { clearPluginLoaderCache, testing } from "../loader.js";
 import { createEmptyPluginRegistry } from "../registry-empty.js";
diff --git a/src/plugins/runtime/standalone-runtime-registry-loader.ts b/src/plugins/runtime/standalone-runtime-registry-loader.ts
index 978d113b0c4e..c69487e17d5d 100644
--- a/src/plugins/runtime/standalone-runtime-registry-loader.ts
+++ b/src/plugins/runtime/standalone-runtime-registry-loader.ts
@@ -1,3 +1,4 @@
+// Standalone runtime registry loader builds plugin runtime registries outside gateway startup.
 import {
   type ActiveRuntimePluginRegistrySurface,
   getLoadedRuntimePluginRegistry,
diff --git a/src/plugins/runtime/task-domain-types.ts b/src/plugins/runtime/task-domain-types.ts
index ea8d8f6348b5..793d7f7f2ca1 100644
--- a/src/plugins/runtime/task-domain-types.ts
+++ b/src/plugins/runtime/task-domain-types.ts
@@ -1,3 +1,4 @@
+// Task domain types define plugin task-flow payloads shared by runtime adapters.
 import type { JsonValue } from "../../tasks/task-flow-registry.types.js";
 import type {
   TaskDeliveryStatus,
diff --git a/src/plugins/runtime/types.ts b/src/plugins/runtime/types.ts
index 8c94d5200e97..f4d6633dca94 100644
--- a/src/plugins/runtime/types.ts
+++ b/src/plugins/runtime/types.ts
@@ -1,3 +1,4 @@
+// Plugin runtime types describe activated plugin capabilities exposed to core execution.
 import type { PluginRuntimeChannel } from "./types-channel.js";
 import type { PluginRuntimeCore, RuntimeLogger } from "./types-core.js";