diff --git a/src/secrets/channel-secret-tts-runtime.ts b/src/secrets/channel-secret-tts-runtime.ts
index f8ce7d020999..3ad9b195c230 100644
--- a/src/secrets/channel-secret-tts-runtime.ts
+++ b/src/secrets/channel-secret-tts-runtime.ts
@@ -1,3 +1,4 @@
+/** Runtime adapter for channel text-to-speech secret contracts. */
 import type {
   ChannelAccountPredicate,
   ChannelAccountSurface,
diff --git a/src/secrets/command-config.test.ts b/src/secrets/command-config.test.ts
index 924bf3eb4ca2..fb4820d3d378 100644
--- a/src/secrets/command-config.test.ts
+++ b/src/secrets/command-config.test.ts
@@ -1,3 +1,4 @@
+/** Tests command-specific secret assignment collection from config snapshots. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/secrets/command-config.ts b/src/secrets/command-config.ts
index 27dee7b75a9d..a50bb7b3d2c1 100644
--- a/src/secrets/command-config.ts
+++ b/src/secrets/command-config.ts
@@ -1,3 +1,4 @@
+/** Collects and analyzes command-scoped secret assignments from OpenClaw config. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { coerceSecretRef, resolveSecretInputRef } from "../config/types.secrets.js";
 import { getPath } from "./path-utils.js";
@@ -5,6 +6,7 @@ import { isExpectedResolvedSecretValue } from "./secret-value.js";
 import { discoverConfigSecretTargetsByIds } from "./target-registry.js";
 
 /** One resolved SecretRef value ready to inject into a command-scoped config view. */
+/** One command config path whose value can be resolved from a SecretRef. */
 export type CommandSecretAssignment = {
   path: string;
   pathSegments: string[];
@@ -34,6 +36,7 @@ export type AnalyzeAssignmentsFromSnapshotResult = {
 /**
  * Compares source SecretRefs with the active resolved snapshot for command-time assignments.
  */
+/** Analyzes command secret assignments without mutating the source config. */
 export function analyzeCommandSecretAssignmentsFromSnapshot(params: {
   sourceConfig: OpenClawConfig;
   resolvedConfig: OpenClawConfig;
diff --git a/src/secrets/config-io.ts b/src/secrets/config-io.ts
index 154857d02c0c..ae9c062c6154 100644
--- a/src/secrets/config-io.ts
+++ b/src/secrets/config-io.ts
@@ -1,3 +1,4 @@
+/** Config IO adapter used by secrets apply/configure flows. */
 import { createConfigIO } from "../config/config.js";
 
 const silentConfigIoLogger = {
diff --git a/src/secrets/exec-resolution-policy.ts b/src/secrets/exec-resolution-policy.ts
index 3586f0f92570..2004a8e7209f 100644
--- a/src/secrets/exec-resolution-policy.ts
+++ b/src/secrets/exec-resolution-policy.ts
@@ -1,3 +1,4 @@
+/** Applies exec-ref resolution policy for audit/apply modes. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { SecretRef } from "../config/types.secrets.js";
 import { formatExecSecretRefIdValidationMessage, isValidExecSecretRefId } from "./ref-contract.js";
diff --git a/src/secrets/json-pointer.test.ts b/src/secrets/json-pointer.test.ts
index 2e20b228d6d7..6b588454f6a5 100644
--- a/src/secrets/json-pointer.test.ts
+++ b/src/secrets/json-pointer.test.ts
@@ -1,3 +1,4 @@
+/** Tests JSON Pointer helpers used by file-backed secret refs. */
 import { describe, expect, it } from "vitest";
 import { readJsonPointer } from "./json-pointer.js";
 
diff --git a/src/secrets/legacy-secretref-env-marker.ts b/src/secrets/legacy-secretref-env-marker.ts
index 4306babdebc6..0a792a2f0876 100644
--- a/src/secrets/legacy-secretref-env-marker.ts
+++ b/src/secrets/legacy-secretref-env-marker.ts
@@ -1,3 +1,4 @@
+/** Detects legacy SecretRef env markers in config values. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   LEGACY_SECRETREF_ENV_MARKER_PREFIX,
diff --git a/src/secrets/path-utils.ts b/src/secrets/path-utils.ts
index 5a1844c6f390..7e96c1cab771 100644
--- a/src/secrets/path-utils.ts
+++ b/src/secrets/path-utils.ts
@@ -1,3 +1,4 @@
+/** Strict dotted-path get/set/delete helpers for secrets migration targets. */
 import { isDeepStrictEqual } from "node:util";
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
 import { isRecord } from "./shared.js";
diff --git a/src/secrets/provider-integrations.ts b/src/secrets/provider-integrations.ts
index 8464465bb205..0ba46bfaf4b6 100644
--- a/src/secrets/provider-integrations.ts
+++ b/src/secrets/provider-integrations.ts
@@ -1,3 +1,4 @@
+/** Materializes trusted plugin secret-provider integrations into exec provider configs. */
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -320,6 +321,7 @@ export function isPluginIntegrationSecretProviderConfig(
 }
 
 /** Materializes an active trusted plugin secret-provider integration into an exec provider. */
+/** Resolves a trusted plugin secret-provider integration into executable provider config. */
 export function resolveSecretProviderIntegrationConfig(params: {
   manifestRegistry: Pick<PluginManifestRegistry, "plugins">;
   providerAlias: string;
diff --git a/src/secrets/ref-contract.test.ts b/src/secrets/ref-contract.test.ts
index 3940b7577d76..5065d4f871c5 100644
--- a/src/secrets/ref-contract.test.ts
+++ b/src/secrets/ref-contract.test.ts
@@ -1,3 +1,4 @@
+/** Tests secret ref id validation, labels, and provider alias contracts. */
 import { describe, expect, it } from "vitest";
 import {
   INVALID_FILE_SECRET_REF_IDS,
diff --git a/src/secrets/runtime-auth-collectors.ts b/src/secrets/runtime-auth-collectors.ts
index 36e5a9cb756d..53527e8874bc 100644
--- a/src/secrets/runtime-auth-collectors.ts
+++ b/src/secrets/runtime-auth-collectors.ts
@@ -1,3 +1,4 @@
+/** Collects auth-profile and OAuth secret refs for runtime preparation. */
 import { assertNoOAuthSecretRefPolicyViolations } from "../agents/auth-profiles/policy.js";
 import type { AuthProfileCredential, AuthProfileStore } from "../agents/auth-profiles/types.js";
 import { resolveSecretInputRef } from "../config/types.secrets.js";
diff --git a/src/secrets/runtime-auth-profiles-oauth-policy.test.ts b/src/secrets/runtime-auth-profiles-oauth-policy.test.ts
index f37465bda151..552c4bc497e1 100644
--- a/src/secrets/runtime-auth-profiles-oauth-policy.test.ts
+++ b/src/secrets/runtime-auth-profiles-oauth-policy.test.ts
@@ -1,3 +1,4 @@
+/** Tests OAuth policy handling while collecting auth-profile secrets. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/secrets/runtime-auth-refresh-failure.test.ts b/src/secrets/runtime-auth-refresh-failure.test.ts
index 793e6a2a0631..a45c27c71544 100644
--- a/src/secrets/runtime-auth-refresh-failure.test.ts
+++ b/src/secrets/runtime-auth-refresh-failure.test.ts
@@ -1,3 +1,4 @@
+/** Tests secrets runtime refresh failure handling for auth-profile stores. */
 import os from "node:os";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { withTempHome } from "../config/home-env.test-harness.js";
diff --git a/src/secrets/runtime-config-collectors-plugins.test.ts b/src/secrets/runtime-config-collectors-plugins.test.ts
index 1fe5c86dea97..d5e1bfde8b73 100644
--- a/src/secrets/runtime-config-collectors-plugins.test.ts
+++ b/src/secrets/runtime-config-collectors-plugins.test.ts
@@ -1,3 +1,4 @@
+/** Tests plugin-specific runtime config secret collectors. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type { PluginOrigin } from "../plugins/types.js";
diff --git a/src/secrets/runtime-config-collectors-plugins.ts b/src/secrets/runtime-config-collectors-plugins.ts
index 6383cad103d0..f7ac75b8e57b 100644
--- a/src/secrets/runtime-config-collectors-plugins.ts
+++ b/src/secrets/runtime-config-collectors-plugins.ts
@@ -1,3 +1,4 @@
+/** Collects plugin config secret refs from runtime plugin metadata. */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -30,6 +31,7 @@ function parsePluginConfigArrayIndex(segment: string): number | undefined {
  * installed). This prevents resolution failures for SecretRefs belonging to
  * non-loadable plugins from blocking startup or preflight validation.
  */
+/** Collects SecretRef assignments from plugin-owned config contract paths. */
 export function collectPluginConfigAssignments(params: {
   /** Mutable config snapshot whose plugin config values will receive resolved secrets. */
   config: OpenClawConfig;
diff --git a/src/secrets/runtime-config-collectors-tts.ts b/src/secrets/runtime-config-collectors-tts.ts
index 12c0c0abc302..866cf1482f90 100644
--- a/src/secrets/runtime-config-collectors-tts.ts
+++ b/src/secrets/runtime-config-collectors-tts.ts
@@ -1,3 +1,4 @@
+/** Collects text-to-speech secret refs from runtime config. */
 import {
   collectSecretInputAssignment,
   type ResolverContext,
diff --git a/src/secrets/runtime-core-snapshots.test.ts b/src/secrets/runtime-core-snapshots.test.ts
index 8769fcd47883..67ee6bfdc6a4 100644
--- a/src/secrets/runtime-core-snapshots.test.ts
+++ b/src/secrets/runtime-core-snapshots.test.ts
@@ -1,3 +1,4 @@
+/** Tests core secrets runtime snapshot preparation and activation behavior. */
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ensureAuthProfileStore } from "../agents/auth-profiles.js";
 import {
diff --git a/src/secrets/runtime-discord-surface.test.ts b/src/secrets/runtime-discord-surface.test.ts
index 1d9db6523b60..a06c8243ecb8 100644
--- a/src/secrets/runtime-discord-surface.test.ts
+++ b/src/secrets/runtime-discord-surface.test.ts
@@ -1,3 +1,4 @@
+/** Tests Discord secret surfaces in runtime preparation. */
 import { describe, expect, it } from "vitest";
 import "./runtime-discord.test-support.ts";
 import {
diff --git a/src/secrets/runtime-external-channel-origin-discovery.test.ts b/src/secrets/runtime-external-channel-origin-discovery.test.ts
index 11addbb152c3..e0aef40785a1 100644
--- a/src/secrets/runtime-external-channel-origin-discovery.test.ts
+++ b/src/secrets/runtime-external-channel-origin-discovery.test.ts
@@ -1,3 +1,4 @@
+/** Tests external channel origin discovery for secrets runtime loading. */
 import { describe, expect, it, vi } from "vitest";
 
 const { loadPluginMetadataSnapshotMock, loadChannelSecretContractApiMock } = vi.hoisted(() => ({
diff --git a/src/secrets/runtime-fast-path.ts b/src/secrets/runtime-fast-path.ts
index 35523bee11d9..972daa4c5268 100644
--- a/src/secrets/runtime-fast-path.ts
+++ b/src/secrets/runtime-fast-path.ts
@@ -1,3 +1,4 @@
+/** Detects when secrets runtime preparation can safely use a fast path. */
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
@@ -199,6 +200,7 @@ function hasRuntimeWebToolConfigSurface(config: OpenClawConfig): boolean {
 /**
  * Returns whether a snapshot can skip full SecretRef/web-tool resolution.
  */
+/** Returns whether current config/auth/plugin state allows skipping full secret preparation. */
 export function canUseSecretsRuntimeFastPath(params: {
   sourceConfig: OpenClawConfig;
   authStores: Array<{ agentDir: string; store: AuthProfileStore }>;
diff --git a/src/secrets/runtime-gateway-auth-surfaces.ts b/src/secrets/runtime-gateway-auth-surfaces.ts
index a9b396ab98ba..3d78d1ab03a6 100644
--- a/src/secrets/runtime-gateway-auth-surfaces.ts
+++ b/src/secrets/runtime-gateway-auth-surfaces.ts
@@ -1,3 +1,4 @@
+/** Collects Gateway auth secret surfaces for secrets runtime preparation. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createGatewayCredentialPlan } from "../gateway/credential-planner.js";
 import type { SecretDefaults } from "./runtime-shared.js";
diff --git a/src/secrets/runtime-shared.ts b/src/secrets/runtime-shared.ts
index 6c007ddd914f..3095c2054bef 100644
--- a/src/secrets/runtime-shared.ts
+++ b/src/secrets/runtime-shared.ts
@@ -1,3 +1,4 @@
+/** Shared secrets runtime resolver context, assignments, and warning helpers. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { coerceSecretRef, type SecretRef } from "../config/types.secrets.js";
 import type { PluginManifestRegistry } from "../plugins/manifest-registry.js";
diff --git a/src/secrets/runtime-web-tools.test.ts b/src/secrets/runtime-web-tools.test.ts
index f664d2bca471..90f9a9e1ead0 100644
--- a/src/secrets/runtime-web-tools.test.ts
+++ b/src/secrets/runtime-web-tools.test.ts
@@ -1,3 +1,4 @@
+/** Tests web-tool secret metadata resolution from config and plugins. */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type {
diff --git a/src/secrets/runtime.coverage.test.ts b/src/secrets/runtime.coverage.test.ts
index ed351c8e24b0..f2440e0b0770 100644
--- a/src/secrets/runtime.coverage.test.ts
+++ b/src/secrets/runtime.coverage.test.ts
@@ -1,3 +1,4 @@
+/** Coverage tests for secrets runtime collector breadth and target surfaces. */
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
diff --git a/src/secrets/runtime.fast-path.test.ts b/src/secrets/runtime.fast-path.test.ts
index f6a2ff3f66d7..f489ee8fcd82 100644
--- a/src/secrets/runtime.fast-path.test.ts
+++ b/src/secrets/runtime.fast-path.test.ts
@@ -1,3 +1,4 @@
+/** Tests secrets runtime fast-path decisions and skip conditions. */
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
diff --git a/src/secrets/runtime.gateway-auth.integration.test.ts b/src/secrets/runtime.gateway-auth.integration.test.ts
index be91e5facc36..1e176dd0517d 100644
--- a/src/secrets/runtime.gateway-auth.integration.test.ts
+++ b/src/secrets/runtime.gateway-auth.integration.test.ts
@@ -1,3 +1,4 @@
+/** Integration tests for Gateway auth secret surfaces in the secrets runtime. */
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/secrets/runtime.ts b/src/secrets/runtime.ts
index 2d7dc4d645aa..6a67dbad8d33 100644
--- a/src/secrets/runtime.ts
+++ b/src/secrets/runtime.ts
@@ -1,3 +1,4 @@
+/** Prepares secrets runtime snapshots from config, auth stores, plugins, and env. */
 import { isDeepStrictEqual } from "node:util";
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope-config.js";
@@ -115,6 +116,7 @@ function shouldLoadPluginMetadataForSecrets(config: OpenClawConfig): boolean {
   );
 }
 
+/** Prepares a secrets runtime snapshot and records refresh context for later activation. */
 export async function prepareSecretsRuntimeSnapshot(params: {
   config: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
@@ -250,6 +252,7 @@ export async function prepareSecretsRuntimeSnapshot(params: {
   return snapshot;
 }
 
+/** Activates a prepared secrets runtime snapshot for fast runtime lookup. */
 export function activateSecretsRuntimeSnapshot(snapshot: PreparedSecretsRuntimeSnapshot): void {
   const refreshContext =
     getPreparedSecretsRuntimeSnapshotRefreshContext(snapshot) ??
diff --git a/src/secrets/shared.ts b/src/secrets/shared.ts
index d5848b1f9e09..b232cb35b17d 100644
--- a/src/secrets/shared.ts
+++ b/src/secrets/shared.ts
@@ -1,3 +1,4 @@
+/** Shared parsing and file helpers for secrets migration/runtime code. */
 import fs from "node:fs";
 import path from "node:path";
 import { privateFileStoreSync } from "../infra/private-file-store.js";
diff --git a/src/secrets/target-registry-data.ts b/src/secrets/target-registry-data.ts
index b9ad8c82537d..ddaa44e0f346 100644
--- a/src/secrets/target-registry-data.ts
+++ b/src/secrets/target-registry-data.ts
@@ -1,3 +1,4 @@
+/** Builds the static and plugin-derived registry of secret migration targets. */
 import type { PluginManifestRecord } from "../plugins/manifest-registry.js";
 import { resolvePluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import { loadChannelSecretContractApiForRecord } from "./channel-contract-api.js";
@@ -484,11 +485,13 @@ function loadSecretTargetRegistryFromPluginMetadata(params: {
 }
 
 /** Returns only core-owned secret target registry entries. */
+/** Returns static core secret target registry entries without plugin-derived targets. */
 export function getCoreSecretTargetRegistry(): SecretTargetRegistryEntry[] {
   return CORE_SECRET_TARGET_REGISTRY;
 }
 
 /** Returns the process-cached registry including bundled plugin/channel metadata. */
+/** Returns core plus plugin/channel secret target registry entries for the current metadata view. */
 export function getSecretTargetRegistry(): SecretTargetRegistryEntry[] {
   if (cachedSecretTargetRegistry) {
     return cachedSecretTargetRegistry;
diff --git a/src/secrets/target-registry-pattern.test.ts b/src/secrets/target-registry-pattern.test.ts
index 908060c0c014..7bf84a1a32ae 100644
--- a/src/secrets/target-registry-pattern.test.ts
+++ b/src/secrets/target-registry-pattern.test.ts
@@ -1,3 +1,4 @@
+/** Tests secret target registry pattern compile/match/expand behavior. */
 import { describe, expect, it } from "vitest";
 import {
   expandPathTokens,
diff --git a/src/secrets/target-registry-pattern.ts b/src/secrets/target-registry-pattern.ts
index ca4976237557..80776c3f1836 100644
--- a/src/secrets/target-registry-pattern.ts
+++ b/src/secrets/target-registry-pattern.ts
@@ -1,3 +1,4 @@
+/** Compiles, matches, and expands secret target registry path patterns. */
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
 import { isRecord, parseDotPath } from "./shared.js";
 import type { SecretTargetRegistryEntry } from "./target-registry-types.js";
diff --git a/src/secrets/target-registry.docs.test.ts b/src/secrets/target-registry.docs.test.ts
index a03719f939b7..4bd752538819 100644
--- a/src/secrets/target-registry.docs.test.ts
+++ b/src/secrets/target-registry.docs.test.ts
@@ -1,3 +1,4 @@
+/** Verifies docs stay aligned with the secret target registry. */
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
diff --git a/src/secrets/unsupported-surface-policy.ts b/src/secrets/unsupported-surface-policy.ts
index 25ebb8034673..d7d842c9cc44 100644
--- a/src/secrets/unsupported-surface-policy.ts
+++ b/src/secrets/unsupported-surface-policy.ts
@@ -1,3 +1,4 @@
+/** Defines unsupported secret-ref surfaces and operator-facing policy messages. */
 import { GENERATED_BUNDLED_CHANNEL_CONFIG_METADATA } from "../config/bundled-channel-config-metadata.generated.js";
 import { isRecord } from "../utils.js";