diff --git a/src/agents/gpt5-prompt-overlay.ts b/src/agents/gpt5-prompt-overlay.ts
index a58495ee6b51..87d5b1a2f355 100644
--- a/src/agents/gpt5-prompt-overlay.ts
+++ b/src/agents/gpt5-prompt-overlay.ts
@@ -1,3 +1,8 @@
+/**
+ * Deprecated GPT-5 prompt overlay helpers.
+ * Kept for OpenAI/Codex provider-owned compatibility while prompt behavior
+ * moves toward provider plugin ownership.
+ */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ProviderSystemPromptContribution } from "./system-prompt-contribution.js";
diff --git a/src/agents/model-auth-markers.test.ts b/src/agents/model-auth-markers.test.ts
index 5c47a45ea82f..e8433b135d72 100644
--- a/src/agents/model-auth-markers.test.ts
+++ b/src/agents/model-auth-markers.test.ts
@@ -1,3 +1,7 @@
+/**
+ * Regression coverage for non-secret model-auth marker helpers.
+ * Verifies core, plugin, env-var, OAuth, AWS, and secret-ref marker handling.
+ */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { captureEnv, withEnvAsync } from "../test-utils/env.js";
 
diff --git a/src/agents/model-auth-markers.ts b/src/agents/model-auth-markers.ts
index ae65f055f597..b21abfc9ed97 100644
--- a/src/agents/model-auth-markers.ts
+++ b/src/agents/model-auth-markers.ts
@@ -1,3 +1,8 @@
+/**
+ * Non-secret model-auth marker helpers.
+ * Distinguishes persisted auth markers, env-var placeholders, OAuth markers,
+ * local auth sentinels, and secret-ref header markers without exposing secrets.
+ */
 import {
   normalizeTrimmedStringList,
   uniqueStrings,
@@ -8,14 +13,19 @@ import { listKnownProviderEnvApiKeyNames } from "./model-auth-env-vars.js";
 
 /** @deprecated MiniMax provider-owned marker; do not use from third-party plugins. */
 export const MINIMAX_OAUTH_MARKER = "minimax-oauth";
+/** Prefix for persisted OAuth-backed API-key marker values. */
 export const OAUTH_API_KEY_MARKER_PREFIX = "oauth:";
+/** Marker for local Ollama auth that does not use a real API key. */
 export const OLLAMA_LOCAL_AUTH_MARKER = "ollama-local";
 /** @deprecated Bundled local-provider marker; do not use from third-party plugins. */
 export const CUSTOM_LOCAL_AUTH_MARKER = "custom-local";
 /** @deprecated Codex provider-owned marker; do not use from third-party plugins. */
 export const CODEX_APP_SERVER_AUTH_MARKER = "codex-app-server";
+/** Marker for Google Vertex credentials resolved outside plain API-key env vars. */
 export const GCP_VERTEX_CREDENTIALS_MARKER = "gcp-vertex-credentials";
+/** Marker for a secret-ref-managed credential that is not stored as an env var. */
 export const NON_ENV_SECRETREF_MARKER = "secretref-managed"; // pragma: allowlist secret
+/** Prefix for secret-ref header markers that name an env-backed source. */
 export const SECRETREF_ENV_HEADER_MARKER_PREFIX = "secretref-env:"; // pragma: allowlist secret
 
 const AWS_SDK_ENV_MARKERS = new Set([
@@ -53,6 +63,7 @@ function listKnownEnvApiKeyMarkers(): Set<string> {
   return knownEnvApiKeyMarkersCache;
 }
 
+/** List non-secret auth markers known from core and bundled plugin manifests. */
 export function listKnownNonSecretApiKeyMarkers(): string[] {
   knownNonSecretApiKeyMarkersCache ??= uniqueStrings([
     ...CORE_NON_SECRET_API_KEY_MARKERS,
@@ -65,35 +76,43 @@ export function listKnownNonSecretApiKeyMarkers(): string[] {
   return [...knownNonSecretApiKeyMarkersCache];
 }
 
+/** Return true for AWS SDK env marker values that represent ambient auth. */
 export function isAwsSdkAuthMarker(value: string): boolean {
   return AWS_SDK_ENV_MARKERS.has(value.trim());
 }
 
+/** Return true for recognized env-var API-key placeholders, excluding AWS SDK markers. */
 export function isKnownEnvApiKeyMarker(value: string): boolean {
   const trimmed = value.trim();
   return listKnownEnvApiKeyMarkers().has(trimmed) && !isAwsSdkAuthMarker(trimmed);
 }
 
+/** Build the persisted OAuth marker for one provider id. */
 export function resolveOAuthApiKeyMarker(providerId: string): string {
   return `${OAUTH_API_KEY_MARKER_PREFIX}${providerId.trim()}`;
 }
 
+/** Return true when a marker value points at provider OAuth auth. */
 export function isOAuthApiKeyMarker(value: string): boolean {
   return value.trim().startsWith(OAUTH_API_KEY_MARKER_PREFIX);
 }
 
+/** Resolve the API-key placeholder for a non-env secret-ref source. */
 export function resolveNonEnvSecretRefApiKeyMarker(_source: SecretRefSource): string {
   return NON_ENV_SECRETREF_MARKER;
 }
 
+/** Resolve the header-value placeholder for a non-env secret-ref source. */
 export function resolveNonEnvSecretRefHeaderValueMarker(_source: SecretRefSource): string {
   return NON_ENV_SECRETREF_MARKER;
 }
 
+/** Resolve the header-value placeholder for an env-backed secret-ref source. */
 export function resolveEnvSecretRefHeaderValueMarker(envVarName: string): string {
   return `${SECRETREF_ENV_HEADER_MARKER_PREFIX}${envVarName.trim()}`;
 }
 
+/** Return true for secret-ref placeholders used in auth header values. */
 export function isSecretRefHeaderValueMarker(value: string): boolean {
   const trimmed = value.trim();
   return (
@@ -101,6 +120,7 @@ export function isSecretRefHeaderValueMarker(value: string): boolean {
   );
 }
 
+/** Return true for persisted non-secret placeholders that should not be treated as real keys. */
 export function isNonSecretApiKeyMarker(
   value: string,
   opts?: { includeEnvVarName?: boolean },
diff --git a/src/agents/openclaw-tools.plugin-context.test.ts b/src/agents/openclaw-tools.plugin-context.test.ts
index 16fe755f8e48..33998fea385a 100644
--- a/src/agents/openclaw-tools.plugin-context.test.ts
+++ b/src/agents/openclaw-tools.plugin-context.test.ts
@@ -1,3 +1,7 @@
+/**
+ * Regression coverage for plugin tool context and delivery defaults.
+ * Verifies requester metadata, plugin tool wrapping, and default preservation.
+ */
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import { resolveOpenClawPluginToolInputs } from "./openclaw-tools.plugin-context.js";
diff --git a/src/agents/plugin-tool-delivery-defaults.ts b/src/agents/plugin-tool-delivery-defaults.ts
index bfa2393e9e8f..71ac884b2f64 100644
--- a/src/agents/plugin-tool-delivery-defaults.ts
+++ b/src/agents/plugin-tool-delivery-defaults.ts
@@ -1,3 +1,8 @@
+/**
+ * Plugin tool delivery-default hook.
+ * Centralizes future delivery-context defaults before final effective tool
+ * policy without changing plugin tool identity.
+ */
 import type { DeliveryContext } from "../utils/delivery-context.types.js";
 import type { AnyAgentTool } from "./tools/common.js";
 
diff --git a/src/agents/prompt-overlay-runtime-contract.test.ts b/src/agents/prompt-overlay-runtime-contract.test.ts
index 664d16666359..f9723834830f 100644
--- a/src/agents/prompt-overlay-runtime-contract.test.ts
+++ b/src/agents/prompt-overlay-runtime-contract.test.ts
@@ -1,3 +1,7 @@
+/**
+ * Runtime contract coverage for deprecated GPT-5 prompt overlays.
+ * Keeps provider-owned overlay compatibility aligned with SDK fixture inputs.
+ */
 import {
   GPT5_CONTRACT_MODEL_ID,
   GPT5_PREFIXED_CONTRACT_MODEL_ID,
diff --git a/src/agents/sender-tool-policy.ts b/src/agents/sender-tool-policy.ts
index fe0cecd67487..ec531bc31c68 100644
--- a/src/agents/sender-tool-policy.ts
+++ b/src/agents/sender-tool-policy.ts
@@ -1,3 +1,8 @@
+/**
+ * Sender-scoped sandbox tool policy resolver.
+ * Applies per-agent toolsBySender matches before global sender policy so
+ * channel delivery can narrow tool access by sender identity.
+ */
 import { resolveToolsBySender } from "../config/group-policy.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveAgentConfig } from "./agent-scope.js";
diff --git a/src/agents/workspace-templates.test.ts b/src/agents/workspace-templates.test.ts
index e26735edecb4..8d86f038b7ac 100644
--- a/src/agents/workspace-templates.test.ts
+++ b/src/agents/workspace-templates.test.ts
@@ -1,3 +1,7 @@
+/**
+ * Regression coverage for workspace template directory discovery.
+ * Verifies dev, package, fallback, and docs-template search paths.
+ */
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/agents/workspace-templates.ts b/src/agents/workspace-templates.ts
index 9926a48605c8..2350aec64125 100644
--- a/src/agents/workspace-templates.ts
+++ b/src/agents/workspace-templates.ts
@@ -1,3 +1,8 @@
+/**
+ * Workspace template directory discovery.
+ * Resolves source, docs, package, and fallback template locations with a small
+ * cache so setup flows can find templates in dev and packaged installs.
+ */
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveOpenClawPackageRoot } from "../infra/openclaw-root.js";