diff --git a/src/plugins/bundle-lsp.ts b/src/plugins/bundle-lsp.ts
index dc7cf87d28b9..a3434f7aeb4d 100644
--- a/src/plugins/bundle-lsp.ts
+++ b/src/plugins/bundle-lsp.ts
@@ -1,3 +1,4 @@
+// Bundles language-server metadata exposed by plugins.
 import fs from "node:fs";
 import path from "node:path";
 import { applyMergePatch } from "../config/merge-patch.js";
diff --git a/src/plugins/bundled-load-path-aliases.ts b/src/plugins/bundled-load-path-aliases.ts
index 6a2c8d79c8e9..38b0714c3df6 100644
--- a/src/plugins/bundled-load-path-aliases.ts
+++ b/src/plugins/bundled-load-path-aliases.ts
@@ -1,3 +1,4 @@
+// Resolves bundled plugin load-path aliases for package output.
 import path from "node:path";
 import { isPathInside } from "./path-safety.js";
 
diff --git a/src/plugins/cli.browser-plugin.integration.test.ts b/src/plugins/cli.browser-plugin.integration.test.ts
index 9c8157b09803..96d2246aa589 100644
--- a/src/plugins/cli.browser-plugin.integration.test.ts
+++ b/src/plugins/cli.browser-plugin.integration.test.ts
@@ -1,3 +1,4 @@
+// Exercises browser plugin CLI integration behavior.
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createBundledBrowserPluginFixture } from "../../test/helpers/browser-bundled-plugin-fixture.js";
diff --git a/src/plugins/config-contract-matches.ts b/src/plugins/config-contract-matches.ts
index 64e6274369cb..5451a20a9548 100644
--- a/src/plugins/config-contract-matches.ts
+++ b/src/plugins/config-contract-matches.ts
@@ -1,3 +1,4 @@
+// Matches plugin config contracts against config paths and values.
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
 import { isRecord } from "../utils.js";
diff --git a/src/plugins/config-schema.ts b/src/plugins/config-schema.ts
index e3d3344f5996..db336000c533 100644
--- a/src/plugins/config-schema.ts
+++ b/src/plugins/config-schema.ts
@@ -1,3 +1,4 @@
+// Builds plugin config schemas from manifest metadata.
 import { z, type ZodTypeAny } from "zod";
 import type { JsonSchemaObject } from "../shared/json-schema.types.js";
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
diff --git a/src/plugins/document-extractor-public-artifacts.ts b/src/plugins/document-extractor-public-artifacts.ts
index 5b11148bfe5b..163644e70ed7 100644
--- a/src/plugins/document-extractor-public-artifacts.ts
+++ b/src/plugins/document-extractor-public-artifacts.ts
@@ -1,3 +1,4 @@
+// Extracts document extractor public artifacts from plugin manifests.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import type {
   DocumentExtractorPlugin,
diff --git a/src/plugins/hooks.correlation.test.ts b/src/plugins/hooks.correlation.test.ts
index 3c015732a6ee..2612ea994c09 100644
--- a/src/plugins/hooks.correlation.test.ts
+++ b/src/plugins/hooks.correlation.test.ts
@@ -1,3 +1,4 @@
+// Verifies correlation metadata for plugin hook execution.
 import { spawnSync } from "node:child_process";
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/plugins/installed-plugin-index-record-cache.ts b/src/plugins/installed-plugin-index-record-cache.ts
index ac23f6c12bf4..76416e791dc7 100644
--- a/src/plugins/installed-plugin-index-record-cache.ts
+++ b/src/plugins/installed-plugin-index-record-cache.ts
@@ -1,3 +1,4 @@
+// Caches installed plugin index records for current process lookups.
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 
 /** Cached installed plugin records for one store/recovery key. */
diff --git a/src/plugins/manifest-model-id-normalization.test.ts b/src/plugins/manifest-model-id-normalization.test.ts
index bba4c9567fb5..1f0552e6686f 100644
--- a/src/plugins/manifest-model-id-normalization.test.ts
+++ b/src/plugins/manifest-model-id-normalization.test.ts
@@ -1,3 +1,4 @@
+// Verifies model IDs declared by plugin manifests are normalized.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/plugins/min-host-version.ts b/src/plugins/min-host-version.ts
index de50c25087aa..11ee73953397 100644
--- a/src/plugins/min-host-version.ts
+++ b/src/plugins/min-host-version.ts
@@ -1,3 +1,4 @@
+// Checks plugin minimum host version compatibility.
 import { isAtLeast, parseSemver } from "../infra/runtime-guard.js";
 
 /** Validation message for plugin minHostVersion manifest fields. */
diff --git a/src/plugins/official-external-plugin-repair-hints.test.ts b/src/plugins/official-external-plugin-repair-hints.test.ts
index c8c5c646a918..1362edc5877e 100644
--- a/src/plugins/official-external-plugin-repair-hints.test.ts
+++ b/src/plugins/official-external-plugin-repair-hints.test.ts
@@ -1,3 +1,4 @@
+// Covers repair hints for official external plugin installs.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { resolveMissingOfficialExternalChannelPluginRepairHint } from "./official-external-plugin-repair-hints.js";
 
diff --git a/src/plugins/plugin-peer-link.test.ts b/src/plugins/plugin-peer-link.test.ts
index 12397bfb2086..45609bbfd02e 100644
--- a/src/plugins/plugin-peer-link.test.ts
+++ b/src/plugins/plugin-peer-link.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin peer linking for development installs.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
diff --git a/src/plugins/provider-auth-env-trust.test.ts b/src/plugins/provider-auth-env-trust.test.ts
index 40afb3de9f6a..f21142849dd9 100644
--- a/src/plugins/provider-auth-env-trust.test.ts
+++ b/src/plugins/provider-auth-env-trust.test.ts
@@ -1,3 +1,4 @@
+// Verifies provider auth environment trust decisions.
 import { describe, expect, it, vi } from "vitest";
 
 const getProviderEnvVars = vi.hoisted(() => vi.fn(() => ["WHISPERX_API_KEY"]));
diff --git a/src/plugins/provider-model-compat.ts b/src/plugins/provider-model-compat.ts
index 5233d56a05b3..ba1270dbb672 100644
--- a/src/plugins/provider-model-compat.ts
+++ b/src/plugins/provider-model-compat.ts
@@ -1,3 +1,4 @@
+// Normalizes provider model compatibility metadata from plugins.
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { detectOpenAICompletionsCompat } from "../agents/openai-completions-compat.js";
 import type { ModelCompatConfig } from "../config/types.models.js";
diff --git a/src/plugins/provider-public-artifacts.test.ts b/src/plugins/provider-public-artifacts.test.ts
index c0bb2b3d92a2..168709f4a1e8 100644
--- a/src/plugins/provider-public-artifacts.test.ts
+++ b/src/plugins/provider-public-artifacts.test.ts
@@ -1,3 +1,4 @@
+// Verifies provider public artifacts extracted from plugin metadata.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/plugins/provider-wizard.test.ts b/src/plugins/provider-wizard.test.ts
index f5e13f408459..73c86936513e 100644
--- a/src/plugins/provider-wizard.test.ts
+++ b/src/plugins/provider-wizard.test.ts
@@ -1,3 +1,4 @@
+// Covers provider setup wizard prompts supplied by plugins.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   buildProviderPluginMethodChoice,
diff --git a/src/plugins/registry-empty.ts b/src/plugins/registry-empty.ts
index f7f2dccb8929..ce8b76131a48 100644
--- a/src/plugins/registry-empty.ts
+++ b/src/plugins/registry-empty.ts
@@ -1,3 +1,4 @@
+// Provides the empty plugin registry used before discovery completes.
 import type { PluginRegistry } from "./registry-types.js";
 
 export function createEmptyPluginRegistry(): PluginRegistry {
diff --git a/src/plugins/runtime-sidecar-paths-baseline.ts b/src/plugins/runtime-sidecar-paths-baseline.ts
index 113d10734aa7..e99c68e4d727 100644
--- a/src/plugins/runtime-sidecar-paths-baseline.ts
+++ b/src/plugins/runtime-sidecar-paths-baseline.ts
@@ -1,3 +1,4 @@
+// Loads runtime sidecar path baselines for bundled plugin checks.
 import fs from "node:fs";
 import path from "node:path";
 import { tryReadJsonSync } from "../infra/json-files.js";
diff --git a/src/plugins/stage-bundled-plugin-runtime.test.ts b/src/plugins/stage-bundled-plugin-runtime.test.ts
index 230f0b790adf..0306684a53f2 100644
--- a/src/plugins/stage-bundled-plugin-runtime.test.ts
+++ b/src/plugins/stage-bundled-plugin-runtime.test.ts
@@ -1,3 +1,4 @@
+// Covers staging bundled plugin runtime files for package output.
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
diff --git a/src/plugins/status-dependencies-core.ts b/src/plugins/status-dependencies-core.ts
index a3dce465c2b3..7f74ed243bc9 100644
--- a/src/plugins/status-dependencies-core.ts
+++ b/src/plugins/status-dependencies-core.ts
@@ -1,3 +1,4 @@
+// Collects core dependency status for plugin diagnostics.
 import fs from "node:fs";
 import path from "node:path";
 
diff --git a/src/plugins/update.test.ts b/src/plugins/update.test.ts
index f65e20ed9d1b..1ccefd1b7099 100644
--- a/src/plugins/update.test.ts
+++ b/src/plugins/update.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin update flows and install record changes.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/plugins/web-content-extractors.runtime.ts b/src/plugins/web-content-extractors.runtime.ts
index e3df3ac55aca..5604a64ce6d9 100644
--- a/src/plugins/web-content-extractors.runtime.ts
+++ b/src/plugins/web-content-extractors.runtime.ts
@@ -1,3 +1,4 @@
+// Runtime bridge for web content extractors supplied by plugins.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveEnabledBundledManifestContractPlugins } from "./bundled-manifest-contract-plugins.js";
 import { loadBundledWebContentExtractorEntriesFromDir } from "./web-content-extractor-public-artifacts.js";
diff --git a/src/plugins/web-provider-resolution-candidates.test.ts b/src/plugins/web-provider-resolution-candidates.test.ts
index 1625cfec71cb..fa75459a4b9f 100644
--- a/src/plugins/web-provider-resolution-candidates.test.ts
+++ b/src/plugins/web-provider-resolution-candidates.test.ts
@@ -1,3 +1,4 @@
+// Covers web provider resolution candidate selection.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
diff --git a/src/plugins/wired-hooks-llm.test.ts b/src/plugins/wired-hooks-llm.test.ts
index 9051821f89f3..16704e40c374 100644
--- a/src/plugins/wired-hooks-llm.test.ts
+++ b/src/plugins/wired-hooks-llm.test.ts
@@ -1,3 +1,4 @@
+// Covers wired plugin hooks around LLM request handling.
 import { describe, expect, it, vi } from "vitest";
 import { createHookRunnerWithRegistry } from "./hooks.test-helpers.js";