diff --git a/src/plugins/bundled-capability-runtime.ts b/src/plugins/bundled-capability-runtime.ts
index d5d772768b4e..e5e705d067d5 100644
--- a/src/plugins/bundled-capability-runtime.ts
+++ b/src/plugins/bundled-capability-runtime.ts
@@ -1,3 +1,4 @@
+/** Loads capability providers from bundled plugin public runtime artifacts. */
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { openRootFileSync } from "../infra/boundary-file-read.js";
diff --git a/src/plugins/bundled-channel-runtime.ts b/src/plugins/bundled-channel-runtime.ts
index 1960cc2ee4bf..dfac7b4eb288 100644
--- a/src/plugins/bundled-channel-runtime.ts
+++ b/src/plugins/bundled-channel-runtime.ts
@@ -1,3 +1,4 @@
+/** Loads bundled channel plugin runtime entries and setup metadata. */
 import fs from "node:fs";
 import path from "node:path";
 import { resolveBundledPluginGeneratedPath } from "./bundled-plugin-metadata.js";
diff --git a/src/plugins/capability-provider-runtime.ts b/src/plugins/capability-provider-runtime.ts
index 27e3ddd2110b..64cc9fcade21 100644
--- a/src/plugins/capability-provider-runtime.ts
+++ b/src/plugins/capability-provider-runtime.ts
@@ -1,3 +1,4 @@
+/** Resolves plugin capability providers through manifest contracts, bundled compat, and runtime registries. */
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { resolveVoiceModelRefs } from "../../packages/speech-core/voice-models.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -99,6 +100,7 @@ function uniqueSorted(values: Iterable<string>): string[] {
   return sortUniqueStrings(values);
 }
 
+/** Loads the manifest snapshot used to resolve capability-provider ownership. */
 export function loadCapabilityManifestSnapshot(params: {
   cfg?: OpenClawConfig;
   workspaceDir?: string;
diff --git a/src/plugins/command-registration.ts b/src/plugins/command-registration.ts
index f762d903a154..1c0c837386cb 100644
--- a/src/plugins/command-registration.ts
+++ b/src/plugins/command-registration.ts
@@ -1,3 +1,4 @@
+/** Validates and registers plugin command definitions into the global command registry. */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
@@ -76,16 +77,19 @@ function getAgentPromptSurfaces(): Set<string> {
   return agentPromptSurfaces;
 }
 
+/** Result returned when a plugin command registration succeeds or fails validation. */
 export type CommandRegistrationResult = {
   ok: boolean;
   error?: string;
 };
 
+/** Returns true when a command name is owned by built-in OpenClaw command handling. */
 export function isReservedCommandName(name: string): boolean {
   const trimmed = normalizeOptionalLowercaseString(name) ?? "";
   return Boolean(trimmed && getReservedCommands().has(trimmed));
 }
 
+/** Validates user-visible command names before plugin registration accepts them. */
 export function validateCommandName(
   name: string,
   opts?: { allowReservedCommandNames?: boolean },
diff --git a/src/plugins/config-contracts.ts b/src/plugins/config-contracts.ts
index 67d8180d66a6..ae711c4d5ac7 100644
--- a/src/plugins/config-contracts.ts
+++ b/src/plugins/config-contracts.ts
@@ -1,3 +1,4 @@
+/** Resolves plugin config contract metadata for scanners and secret/config policy checks. */
 import { normalizeSortedUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { discoverOpenClawPlugins, type PluginDiscoveryResult } from "./discovery.js";
diff --git a/src/plugins/current-plugin-metadata-snapshot.ts b/src/plugins/current-plugin-metadata-snapshot.ts
index 48543bac1460..c9e4736f2e86 100644
--- a/src/plugins/current-plugin-metadata-snapshot.ts
+++ b/src/plugins/current-plugin-metadata-snapshot.ts
@@ -1,3 +1,4 @@
+/** Tracks the current plugin metadata snapshot for control-plane lookups. */
 import { setCurrentManifestModelIdNormalizationRecords } from "@openclaw/model-catalog-core/provider-model-id-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/plugins/hook-runner-global.test.ts b/src/plugins/hook-runner-global.test.ts
index a6e710014175..41e173603fac 100644
--- a/src/plugins/hook-runner-global.test.ts
+++ b/src/plugins/hook-runner-global.test.ts
@@ -1,3 +1,4 @@
+/** Verifies global hook runner sequencing, mutation, and error behavior. */
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createMockPluginRegistry } from "./hooks.test-helpers.js";
 
diff --git a/src/plugins/installed-plugin-index-record-reader.ts b/src/plugins/installed-plugin-index-record-reader.ts
index 848474d99873..bb1a7806137f 100644
--- a/src/plugins/installed-plugin-index-record-reader.ts
+++ b/src/plugins/installed-plugin-index-record-reader.ts
@@ -1,3 +1,4 @@
+/** Reads installed-index records back into manifest registry records. */
 import fs from "node:fs";
 import path from "node:path";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
diff --git a/src/plugins/installed-plugin-index-records.ts b/src/plugins/installed-plugin-index-records.ts
index bb9a5ef46bee..1d8c56430989 100644
--- a/src/plugins/installed-plugin-index-records.ts
+++ b/src/plugins/installed-plugin-index-records.ts
@@ -1,3 +1,4 @@
+/** Builds and compares installed plugin index records for refresh decisions. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import {
diff --git a/src/plugins/loader-cache-state.test.ts b/src/plugins/loader-cache-state.test.ts
index 362bfad281d6..a3baca4b8a2c 100644
--- a/src/plugins/loader-cache-state.test.ts
+++ b/src/plugins/loader-cache-state.test.ts
@@ -1,3 +1,4 @@
+/** Tests plugin loader cache state keys, invalidation, and reset behavior. */
 import { describe, expect, it } from "vitest";
 import { PluginLoaderCacheState, PluginLoadReentryError } from "./loader-cache-state.js";
 
diff --git a/src/plugins/manifest-model-id-normalization.ts b/src/plugins/manifest-model-id-normalization.ts
index 309e92a80ac1..f73cce71eeab 100644
--- a/src/plugins/manifest-model-id-normalization.ts
+++ b/src/plugins/manifest-model-id-normalization.ts
@@ -1,3 +1,4 @@
+/** Applies manifest-declared model-id normalization policies to provider model refs. */
 import {
   collectManifestModelIdNormalizationPolicies,
   normalizeProviderModelIdWithPolicies,
diff --git a/src/plugins/manifest-registry-installed.ts b/src/plugins/manifest-registry-installed.ts
index d24bf7b623ad..6774f3f2eeae 100644
--- a/src/plugins/manifest-registry-installed.ts
+++ b/src/plugins/manifest-registry-installed.ts
@@ -1,3 +1,4 @@
+/** Builds manifest registry records from installed plugin index snapshots. */
 import fs from "node:fs";
 import path from "node:path";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
diff --git a/src/plugins/plugin-control-plane-context.ts b/src/plugins/plugin-control-plane-context.ts
index f281b1146c4a..e293e807e050 100644
--- a/src/plugins/plugin-control-plane-context.ts
+++ b/src/plugins/plugin-control-plane-context.ts
@@ -1,3 +1,4 @@
+/** Tracks control-plane plugin metadata context during registry and status operations. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { hashJson } from "./installed-plugin-index-hash.js";
 import { resolveInstalledPluginIndexPolicyHash } from "./installed-plugin-index-policy.js";
diff --git a/src/plugins/plugin-lookup-table.ts b/src/plugins/plugin-lookup-table.ts
index d2ee874f1630..7ae0a57f1035 100644
--- a/src/plugins/plugin-lookup-table.ts
+++ b/src/plugins/plugin-lookup-table.ts
@@ -1,3 +1,4 @@
+/** Builds plugin lookup tables keyed by manifest ids, channels, providers, and commands. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   createGatewayStartupMetadataPluginIdScope,
diff --git a/src/plugins/plugin-version-drift.test.ts b/src/plugins/plugin-version-drift.test.ts
index 2c0a0a18c297..30a7fc88aa2f 100644
--- a/src/plugins/plugin-version-drift.test.ts
+++ b/src/plugins/plugin-version-drift.test.ts
@@ -1,3 +1,4 @@
+/** Tests plugin version drift detection between package, manifest, and install records. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
diff --git a/src/plugins/provider-auth-choice-preference.ts b/src/plugins/provider-auth-choice-preference.ts
index 9b7baa7c0ce3..c3c4b2e9688e 100644
--- a/src/plugins/provider-auth-choice-preference.ts
+++ b/src/plugins/provider-auth-choice-preference.ts
@@ -1,3 +1,4 @@
+/** Resolves preferred provider auth choices from config and plugin metadata. */
 import { normalizeLegacyOnboardAuthChoice } from "../commands/auth-choice-legacy.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveManifestProviderAuthChoice } from "./provider-auth-choices.js";
diff --git a/src/plugins/provider-auth-input.ts b/src/plugins/provider-auth-input.ts
index d2bb583114e4..30a65b53e220 100644
--- a/src/plugins/provider-auth-input.ts
+++ b/src/plugins/provider-auth-input.ts
@@ -1,3 +1,4 @@
+/** Normalizes provider auth input metadata collected from plugin setup flows. */
 import {
   normalizeOptionalLowercaseString,
   normalizeStringifiedOptionalString,
diff --git a/src/plugins/provider-oauth-flow.ts b/src/plugins/provider-oauth-flow.ts
index d17ea3dafc4b..0ce0930fd46a 100644
--- a/src/plugins/provider-oauth-flow.ts
+++ b/src/plugins/provider-oauth-flow.ts
@@ -1,3 +1,4 @@
+/** Coordinates provider OAuth flows exposed by plugin-owned auth integrations. */
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 
diff --git a/src/plugins/provider-runtime.runtime.ts b/src/plugins/provider-runtime.runtime.ts
index 6315bad39795..92ac06ba9081 100644
--- a/src/plugins/provider-runtime.runtime.ts
+++ b/src/plugins/provider-runtime.runtime.ts
@@ -1,3 +1,4 @@
+/** Runtime-side provider discovery and provider registration resolution helpers. */
 import { createLazyImportLoader } from "../shared/lazy-promise.js";
 
 type ProviderRuntimeModule = typeof import("./provider-runtime.js");
diff --git a/src/plugins/public-surface-runtime.test.ts b/src/plugins/public-surface-runtime.test.ts
index ca211488f85b..9c22fc0aade2 100644
--- a/src/plugins/public-surface-runtime.test.ts
+++ b/src/plugins/public-surface-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Verifies public-surface runtime artifact loading for bundled plugins. */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/plugins/runtime.test.ts b/src/plugins/runtime.test.ts
index a34b37ad05c1..0aa600de5414 100644
--- a/src/plugins/runtime.test.ts
+++ b/src/plugins/runtime.test.ts
@@ -1,3 +1,4 @@
+/** Covers plugin runtime registration API behavior and registry mutation guards. */
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { isPluginRegistryRetired } from "./registry-lifecycle.js";
 import { createEmptyPluginRegistry } from "./registry.js";
diff --git a/src/plugins/schema-validator.test.ts b/src/plugins/schema-validator.test.ts
index c7016bc50214..07dd0592985f 100644
--- a/src/plugins/schema-validator.test.ts
+++ b/src/plugins/schema-validator.test.ts
@@ -1,3 +1,4 @@
+/** Covers plugin schema validation for manifests and exported config schemas. */
 import { Format } from "typebox/format";
 import { describe, expect, it } from "vitest";
 import { validateJsonSchemaValue } from "./schema-validator.js";
diff --git a/src/plugins/session-entry-slot-keys.ts b/src/plugins/session-entry-slot-keys.ts
index ff010b1f8e19..b4753928e297 100644
--- a/src/plugins/session-entry-slot-keys.ts
+++ b/src/plugins/session-entry-slot-keys.ts
@@ -1,3 +1,4 @@
+/** Reserves session-entry keys so plugin extension slots cannot collide with core session state. */
 import type { SessionEntry } from "../config/sessions/types.js";
 
 const SESSION_ENTRY_RESERVED_SLOT_KEY_LIST = [
@@ -134,6 +135,7 @@ type ReservedSessionEntrySlotKey = Extract<
 >;
 type MissingSessionEntryReservedSlotKeys = Exclude<keyof SessionEntry, ReservedSessionEntrySlotKey>;
 type AssertNever<T extends never> = T;
+/** Compile-time guard that every SessionEntry key is excluded from plugin extension slot names. */
 export type _AssertAllSessionEntryKeysAreReserved =
   AssertNever<MissingSessionEntryReservedSlotKeys>;
 
diff --git a/src/plugins/status.test-helpers.ts b/src/plugins/status.test-helpers.ts
index bdf8232b7471..794907821d3f 100644
--- a/src/plugins/status.test-helpers.ts
+++ b/src/plugins/status.test-helpers.ts
@@ -1,3 +1,4 @@
+/** Shared helpers for plugin status tests and installed-index fixture setup. */
 import type { PluginLoadResult } from "./loader.js";
 import type { PluginRecord } from "./registry.js";
 import type { PluginCompatibilityNotice } from "./status.js";