diff --git a/src/plugins/runtime/index.ts b/src/plugins/runtime/index.ts
index 0fbf6578867a..69d12f2622c4 100644
--- a/src/plugins/runtime/index.ts
+++ b/src/plugins/runtime/index.ts
@@ -1,3 +1,4 @@
+// Plugin runtime entrypoint assembles runtime helpers available to activated plugins.
 import { getRuntimeConfig } from "../../config/config.js";
 import { resolveStateDir } from "../../config/paths.js";
 import {
diff --git a/src/plugins/runtime/load-context.test.ts b/src/plugins/runtime/load-context.test.ts
index 995460552a1b..604af3553157 100644
--- a/src/plugins/runtime/load-context.test.ts
+++ b/src/plugins/runtime/load-context.test.ts
@@ -1,3 +1,4 @@
+// Load context tests cover agent and workspace context resolution for plugin runtimes.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loadConfigMock = vi.fn<typeof import("../../config/config.js").loadConfig>();
diff --git a/src/plugins/runtime/model-auth-types.ts b/src/plugins/runtime/model-auth-types.ts
index 3fedbfb109db..696b2879f343 100644
--- a/src/plugins/runtime/model-auth-types.ts
+++ b/src/plugins/runtime/model-auth-types.ts
@@ -1,3 +1,4 @@
+// Model auth runtime types describe provider auth state exposed to plugin runtimes.
 import type { ResolvedProviderAuth } from "../../agents/model-auth-runtime-shared.js";
 import type { ModelProviderRequestTransportOverrides } from "../../agents/provider-request-config.js";
 
diff --git a/src/plugins/runtime/runtime-config.ts b/src/plugins/runtime/runtime-config.ts
index 03c5bdcd5fc0..5bc7dc37fcbe 100644
--- a/src/plugins/runtime/runtime-config.ts
+++ b/src/plugins/runtime/runtime-config.ts
@@ -1,3 +1,4 @@
+// Runtime config helpers expose scoped OpenClaw config reads to plugin runtimes.
 import { getRuntimeConfig } from "../../config/config.js";
 import {
   mutateConfigFile as mutateConfigFileInternal,
diff --git a/src/plugins/runtime/runtime-events.ts b/src/plugins/runtime/runtime-events.ts
index 91c282a404f2..f132aac7ff84 100644
--- a/src/plugins/runtime/runtime-events.ts
+++ b/src/plugins/runtime/runtime-events.ts
@@ -1,3 +1,4 @@
+// Runtime event helpers bridge core agent events into plugin runtime hooks.
 import { onAgentEvent } from "../../infra/agent-events.js";
 import { onSessionTranscriptUpdate } from "../../sessions/transcript-events.js";
 import type { PluginRuntime } from "./types.js";
diff --git a/src/plugins/runtime/runtime-llm.runtime.test.ts b/src/plugins/runtime/runtime-llm.runtime.test.ts
index 499d2690cc63..fbf18a97e4f5 100644
--- a/src/plugins/runtime/runtime-llm.runtime.test.ts
+++ b/src/plugins/runtime/runtime-llm.runtime.test.ts
@@ -1,3 +1,4 @@
+// Runtime LLM tests cover plugin provider hooks inside the model runtime adapter.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { resolveContextEngineCapabilities } from "../../agents/embedded-agent-runner/context-engine-capabilities.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/plugins/runtime/runtime-media.ts b/src/plugins/runtime/runtime-media.ts
index bde8c1b6c60c..bb20bcb9b925 100644
--- a/src/plugins/runtime/runtime-media.ts
+++ b/src/plugins/runtime/runtime-media.ts
@@ -1,3 +1,4 @@
+// Runtime media helpers load and classify media attachments for plugin runtimes.
 import { mediaKindFromMime } from "@openclaw/media-core/constants";
 import { detectMime } from "@openclaw/media-core/mime";
 import { isVoiceCompatibleAudio } from "../../media/audio.js";
diff --git a/src/plugins/runtime/runtime-model-auth.runtime.ts b/src/plugins/runtime/runtime-model-auth.runtime.ts
index 8575d1fd7c54..22c39127dc81 100644
--- a/src/plugins/runtime/runtime-model-auth.runtime.ts
+++ b/src/plugins/runtime/runtime-model-auth.runtime.ts
@@ -1,3 +1,4 @@
+// Runtime model auth helpers expose provider auth resolution to plugin runtimes.
 import {
   getApiKeyForModel as resolveModelApiKey,
   resolveApiKeyForProvider as resolveProviderApiKey,
diff --git a/src/plugins/runtime/runtime-system.ts b/src/plugins/runtime/runtime-system.ts
index 1006b97ee3f0..52c12dc7088c 100644
--- a/src/plugins/runtime/runtime-system.ts
+++ b/src/plugins/runtime/runtime-system.ts
@@ -1,3 +1,4 @@
+// Runtime system helpers expose host system operations to activated plugin runtimes.
 import { requestHeartbeat } from "../../infra/heartbeat-wake.js";
 import { enqueueSystemEvent } from "../../infra/system-events.js";
 import { runCommandWithTimeout } from "../../process/exec.js";
diff --git a/src/plugins/runtime/runtime-taskflow.types.ts b/src/plugins/runtime/runtime-taskflow.types.ts
index ecf5fd7f56c7..6490d902aea5 100644
--- a/src/plugins/runtime/runtime-taskflow.types.ts
+++ b/src/plugins/runtime/runtime-taskflow.types.ts
@@ -1,3 +1,4 @@
+// Runtime task-flow types describe task-flow hooks and options for plugin runtimes.
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { JsonValue, TaskFlowRecord } from "../../tasks/task-flow-registry.types.js";
 import type {
diff --git a/src/plugins/runtime/runtime-tasks.ts b/src/plugins/runtime/runtime-tasks.ts
index fed143ee07d1..c6eab5c4b54b 100644
--- a/src/plugins/runtime/runtime-tasks.ts
+++ b/src/plugins/runtime/runtime-tasks.ts
@@ -1,3 +1,4 @@
+// Runtime task helpers expose task-flow operations to activated plugin runtimes.
 import { listTasksForFlowId } from "../../tasks/runtime-internal.js";
 import {
   mapTaskFlowDetail,
diff --git a/src/plugins/runtime/runtime-web-channel-plugin.ts b/src/plugins/runtime/runtime-web-channel-plugin.ts
index 7e233ee50331..a134b2d3171c 100644
--- a/src/plugins/runtime/runtime-web-channel-plugin.ts
+++ b/src/plugins/runtime/runtime-web-channel-plugin.ts
@@ -1,3 +1,4 @@
+// Runtime web-channel plugin helpers expose web-channel tools through activated plugin runtimes.
 import type { AgentToolResult } from "../../agents/runtime/index.js";
 import type { ChannelAgentTool } from "../../channels/plugins/types.core.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/plugins/runtime/types-core.ts b/src/plugins/runtime/types-core.ts
index 8b1a0a0cd3d9..aa0404ce4b8e 100644
--- a/src/plugins/runtime/types-core.ts
+++ b/src/plugins/runtime/types-core.ts
@@ -1,3 +1,4 @@
+// Core runtime types define system, config, and task helper contracts for plugins.
 import type { HeartbeatRunResult } from "../../infra/heartbeat-wake.js";
 import type { LogLevel } from "../../logging/levels.js";
 import type { MediaUnderstandingRuntime } from "../../media-understanding/runtime-types.js";
diff --git a/src/plugins/test-helpers/archive-fixtures.test.ts b/src/plugins/test-helpers/archive-fixtures.test.ts
index c6ba76dbe55b..7a5de39cb061 100644
--- a/src/plugins/test-helpers/archive-fixtures.test.ts
+++ b/src/plugins/test-helpers/archive-fixtures.test.ts
@@ -1,3 +1,4 @@
+// Archive fixture tests cover plugin archive fixture creation and cleanup helpers.
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, describe, expect, it } from "vitest";
diff --git a/src/plugins/test-helpers/archive-fixtures.ts b/src/plugins/test-helpers/archive-fixtures.ts
index ac45b3d358b0..60f39a28b2e3 100644
--- a/src/plugins/test-helpers/archive-fixtures.ts
+++ b/src/plugins/test-helpers/archive-fixtures.ts
@@ -1,3 +1,4 @@
+// Archive fixture helpers create compressed plugin archives for install and loader tests.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/plugins/test-helpers/cold-plugin-fixtures.ts b/src/plugins/test-helpers/cold-plugin-fixtures.ts
index 99dfd776b72c..89a666e863e1 100644
--- a/src/plugins/test-helpers/cold-plugin-fixtures.ts
+++ b/src/plugins/test-helpers/cold-plugin-fixtures.ts
@@ -1,3 +1,4 @@
+// Cold plugin fixture helpers create plugin packages for cold import and loader tests.
 import fs from "node:fs";
 import path from "node:path";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/plugins/test-helpers/fs-fixtures.ts b/src/plugins/test-helpers/fs-fixtures.ts
index db00c9cfbe08..58f0ac4c31ab 100644
--- a/src/plugins/test-helpers/fs-fixtures.ts
+++ b/src/plugins/test-helpers/fs-fixtures.ts
@@ -1,3 +1,4 @@
+// Filesystem fixture helpers create plugin filesystem layouts for registry and loader tests.
 import fs from "node:fs";
 import fsPromises from "node:fs/promises";
 import os from "node:os";
diff --git a/src/plugins/test-helpers/managed-npm-plugin.ts b/src/plugins/test-helpers/managed-npm-plugin.ts
index bca627967d69..caaa96a70236 100644
--- a/src/plugins/test-helpers/managed-npm-plugin.ts
+++ b/src/plugins/test-helpers/managed-npm-plugin.ts
@@ -1,3 +1,4 @@
+// Managed npm plugin test helpers create package fixtures for managed plugin tests.
 import fs from "node:fs";
 import path from "node:path";
 import { resolvePluginNpmProjectDir } from "../install-paths.js";
diff --git a/src/plugins/test-helpers/registry-jiti-mocks.ts b/src/plugins/test-helpers/registry-jiti-mocks.ts
index c2534f97eec8..fffdb27134de 100644
--- a/src/plugins/test-helpers/registry-jiti-mocks.ts
+++ b/src/plugins/test-helpers/registry-jiti-mocks.ts
@@ -1,3 +1,4 @@
+// Registry Jiti mock helpers install Vitest mocks for plugin registry import tests.
 import { vi } from "vitest";
 
 const registryJitiMocks = vi.hoisted(() => ({