diff --git a/src/plugins/activation-context.ts b/src/plugins/activation-context.ts
index c833531e7ea1..181cce32d165 100644
--- a/src/plugins/activation-context.ts
+++ b/src/plugins/activation-context.ts
@@ -1,3 +1,4 @@
+// Builds plugin activation context from config, discovery, and manifests.
 import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/plugins/agent-tool-result-middleware.ts b/src/plugins/agent-tool-result-middleware.ts
index f30f4a308cd8..5c6afbf08b65 100644
--- a/src/plugins/agent-tool-result-middleware.ts
+++ b/src/plugins/agent-tool-result-middleware.ts
@@ -1,3 +1,4 @@
+// Applies plugin middleware to agent tool results at runtime boundaries.
 import type {
   AgentToolResultMiddleware,
   AgentToolResultMiddlewareOptions,
diff --git a/src/plugins/bundled-plugin-metadata.ts b/src/plugins/bundled-plugin-metadata.ts
index 04b1add975ce..01e1aa4f4202 100644
--- a/src/plugins/bundled-plugin-metadata.ts
+++ b/src/plugins/bundled-plugin-metadata.ts
@@ -1,3 +1,4 @@
+// Loads bundled plugin metadata without activating plugin runtime code.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/dependency-denylist.test.ts b/src/plugins/dependency-denylist.test.ts
index 2dab1ba91452..17874b13694f 100644
--- a/src/plugins/dependency-denylist.test.ts
+++ b/src/plugins/dependency-denylist.test.ts
@@ -1,3 +1,4 @@
+// Verifies plugin dependency denylist enforcement.
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/plugins/enable.ts b/src/plugins/enable.ts
index 0993fb6421fc..2d99256c3509 100644
--- a/src/plugins/enable.ts
+++ b/src/plugins/enable.ts
@@ -1,3 +1,4 @@
+// Resolves plugin enablement state from config and channel context.
 import { normalizeChatChannelId } from "../channels/ids.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { setPluginEnabledInConfig } from "./toggle-config.js";
diff --git a/src/plugins/installed-plugin-index-records.test.ts b/src/plugins/installed-plugin-index-records.test.ts
index f547931320e1..633c88be5331 100644
--- a/src/plugins/installed-plugin-index-records.test.ts
+++ b/src/plugins/installed-plugin-index-records.test.ts
@@ -1,3 +1,4 @@
+// Covers installed plugin index record parsing and normalization.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/plugins/interactive-shared.ts b/src/plugins/interactive-shared.ts
index 3364fa307a98..bbdbd74c73ce 100644
--- a/src/plugins/interactive-shared.ts
+++ b/src/plugins/interactive-shared.ts
@@ -1,3 +1,4 @@
+// Shares interactive plugin metadata normalization across registries.
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 
 export function toPluginInteractiveRegistryKey(channel: string, namespace: string): string {
diff --git a/src/plugins/loader.prefer-over.test.ts b/src/plugins/loader.prefer-over.test.ts
index 113ed1070bb2..c191736352f1 100644
--- a/src/plugins/loader.prefer-over.test.ts
+++ b/src/plugins/loader.prefer-over.test.ts
@@ -1,3 +1,4 @@
+// Verifies plugin loader prefer-over selection behavior.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/plugins/manifest-contract-eligibility.test.ts b/src/plugins/manifest-contract-eligibility.test.ts
index 289dfba2b6ed..3f469d7d88f6 100644
--- a/src/plugins/manifest-contract-eligibility.test.ts
+++ b/src/plugins/manifest-contract-eligibility.test.ts
@@ -1,3 +1,4 @@
+// Covers manifest contract eligibility decisions.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
diff --git a/src/plugins/memory-state.test.ts b/src/plugins/memory-state.test.ts
index a45cbbd3e639..999cafcf5fd3 100644
--- a/src/plugins/memory-state.test.ts
+++ b/src/plugins/memory-state.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin-backed memory state registration and reset behavior.
 import { afterEach, describe, expect, it } from "vitest";
 import {
   resetMemoryPluginState,
diff --git a/src/plugins/migration-provider-runtime.test.ts b/src/plugins/migration-provider-runtime.test.ts
index 4aa6862b6077..ce3d1f7051f2 100644
--- a/src/plugins/migration-provider-runtime.test.ts
+++ b/src/plugins/migration-provider-runtime.test.ts
@@ -1,3 +1,4 @@
+// Covers migration provider runtime hooks supplied by plugins.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { PluginRegistry } from "./registry-types.js";
diff --git a/src/plugins/plugin-scope.test.ts b/src/plugins/plugin-scope.test.ts
index 5e03c0970c05..78c023a37bbf 100644
--- a/src/plugins/plugin-scope.test.ts
+++ b/src/plugins/plugin-scope.test.ts
@@ -1,3 +1,4 @@
+// Verifies plugin scope parsing and boundary checks.
 import { describe, expect, it } from "vitest";
 import { normalizePluginIdScope } from "./plugin-scope.js";
 
diff --git a/src/plugins/plugin-version-drift.ts b/src/plugins/plugin-version-drift.ts
index 08c1e52447a1..98745ac4e0ac 100644
--- a/src/plugins/plugin-version-drift.ts
+++ b/src/plugins/plugin-version-drift.ts
@@ -1,3 +1,4 @@
+// Detects plugin version drift between config, manifests, and installs.
 import type { OpenClawConfig } from "../config/types.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import { parseClawHubPluginSpec } from "../infra/clawhub-spec.js";
diff --git a/src/plugins/provider-api-key-auth.runtime.ts b/src/plugins/provider-api-key-auth.runtime.ts
index 4b2f2a3ee672..56d9be27620e 100644
--- a/src/plugins/provider-api-key-auth.runtime.ts
+++ b/src/plugins/provider-api-key-auth.runtime.ts
@@ -1,3 +1,4 @@
+// Runtime bridge for provider API-key auth configured by plugins.
 import { applyAuthProfileConfig, buildApiKeyCredential } from "./provider-auth-helpers.js";
 import {
   ensureApiKeyFromOptionEnvOrPrompt,
diff --git a/src/plugins/provider-auth-choice.runtime.ts b/src/plugins/provider-auth-choice.runtime.ts
index 925a2e78a727..6e391a61b872 100644
--- a/src/plugins/provider-auth-choice.runtime.ts
+++ b/src/plugins/provider-auth-choice.runtime.ts
@@ -1,3 +1,4 @@
+// Runtime boundary for resolving provider auth choices from plugins.
 import {
   resolveProviderPluginChoice as resolveProviderPluginChoiceImpl,
   runProviderModelSelectedHook as runProviderModelSelectedHookImpl,
diff --git a/src/plugins/provider-auth-input.test.ts b/src/plugins/provider-auth-input.test.ts
index 83cfde06697f..d899fe44b053 100644
--- a/src/plugins/provider-auth-input.test.ts
+++ b/src/plugins/provider-auth-input.test.ts
@@ -1,3 +1,4 @@
+// Covers provider auth input collection and credential handling.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import {
diff --git a/src/plugins/provider-runtime.test-support.ts b/src/plugins/provider-runtime.test-support.ts
index 93c57de678d5..7993d4358a25 100644
--- a/src/plugins/provider-runtime.test-support.ts
+++ b/src/plugins/provider-runtime.test-support.ts
@@ -1,3 +1,4 @@
+// Provides shared assertions for provider plugin runtime tests.
 import { expect } from "vitest";
 
 const openaiCodexCatalogEntries = [
diff --git a/src/plugins/provider-thinking.ts b/src/plugins/provider-thinking.ts
index 3e92c5609c83..65ed27b9311b 100644
--- a/src/plugins/provider-thinking.ts
+++ b/src/plugins/provider-thinking.ts
@@ -1,3 +1,4 @@
+// Resolves provider thinking-level policy from plugin metadata.
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { resolveBundledProviderPolicySurface } from "./provider-public-artifacts.js";
 import type {
diff --git a/src/plugins/setup-registry.runtime.test.ts b/src/plugins/setup-registry.runtime.test.ts
index 945cfdd2352b..d70d46cac72e 100644
--- a/src/plugins/setup-registry.runtime.test.ts
+++ b/src/plugins/setup-registry.runtime.test.ts
@@ -1,3 +1,4 @@
+// Verifies runtime setup registry loading and lazy boundaries.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   clearCurrentPluginMetadataSnapshot,
diff --git a/src/plugins/status.registry-snapshot.test.ts b/src/plugins/status.registry-snapshot.test.ts
index 9025a9123eb3..6e16d3d3d37c 100644
--- a/src/plugins/status.registry-snapshot.test.ts
+++ b/src/plugins/status.registry-snapshot.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin status snapshots built from registry state.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
diff --git a/src/plugins/tools.optional.test.ts b/src/plugins/tools.optional.test.ts
index 8c848323989f..c4c069081b3e 100644
--- a/src/plugins/tools.optional.test.ts
+++ b/src/plugins/tools.optional.test.ts
@@ -1,3 +1,4 @@
+// Verifies optional plugin tool registration and absence handling.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { DEFAULT_PLUGIN_TOOLS_ALLOWLIST_ENTRY } from "../agents/tool-policy.js";
 import { resetLogger, setLoggerOverride } from "../logging/logger.js";
diff --git a/src/plugins/web-fetch-providers.shared.ts b/src/plugins/web-fetch-providers.shared.ts
index db4da5aee159..f7047cd8ec09 100644
--- a/src/plugins/web-fetch-providers.shared.ts
+++ b/src/plugins/web-fetch-providers.shared.ts
@@ -1,3 +1,4 @@
+// Shares web fetch provider loading helpers across provider plugins.
 import type { PluginLoadOptions } from "./loader.js";
 import type { PluginWebFetchProviderEntry } from "./types.js";
 import {
diff --git a/src/plugins/web-search-credential-presence.test.ts b/src/plugins/web-search-credential-presence.test.ts
index cd7f4f729818..40b3244970ad 100644
--- a/src/plugins/web-search-credential-presence.test.ts
+++ b/src/plugins/web-search-credential-presence.test.ts
@@ -1,3 +1,4 @@
+// Verifies web-search credential presence checks for plugins.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/wired-hooks-inbound-claim.test.ts b/src/plugins/wired-hooks-inbound-claim.test.ts
index 9b84268b708c..e764444c673c 100644
--- a/src/plugins/wired-hooks-inbound-claim.test.ts
+++ b/src/plugins/wired-hooks-inbound-claim.test.ts
@@ -1,3 +1,4 @@
+// Covers wired hook inbound-claim dispatch behavior.
 import { describe, expect, it, vi } from "vitest";
 import { createHookRunnerWithRegistry } from "./hooks.test-helpers.js";