diff --git a/extensions/anthropic/api.ts b/extensions/anthropic/api.ts
index c7733cbd3f4c..b791ee4d212b 100644
--- a/extensions/anthropic/api.ts
+++ b/extensions/anthropic/api.ts
@@ -1,3 +1,7 @@
+/**
+ * Public Anthropic provider API barrel. It exposes provider construction,
+ * Claude CLI helpers, and stream wrappers for config/runtime consumers.
+ */
 export { CLAUDE_CLI_BACKEND_ID, isClaudeCliProvider } from "./cli-shared.js";
 export { buildAnthropicProvider } from "./register.runtime.js";
 export {
diff --git a/extensions/anthropic/claude-model-refs.ts b/extensions/anthropic/claude-model-refs.ts
index ac1f33baa003..2b60a0ba0866 100644
--- a/extensions/anthropic/claude-model-refs.ts
+++ b/extensions/anthropic/claude-model-refs.ts
@@ -1,3 +1,7 @@
+/**
+ * Claude CLI model-ref normalization. It maps family aliases and retired model
+ * ids to current Anthropic runtime refs while preserving auth-profile suffixes.
+ */
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { CLAUDE_CLI_BACKEND_ID, CLAUDE_CLI_MODEL_ALIASES } from "./cli-constants.js";
 
@@ -7,6 +11,7 @@ const DEFAULT_CLAUDE_MODEL_BY_FAMILY: Record<string, string> = {
   haiku: "claude-haiku-4-5",
 };
 
+/** Normalized Claude CLI selection plus runtime refs used by setup migrations. */
 export type ClaudeCliAnthropicModelRefs = {
   selectedRef: string;
   runtimeRefs: string[];
@@ -182,6 +187,7 @@ function upgradeOldClaudeModelId(normalized: string): string | null {
   return null;
 }
 
+/** Resolve a Claude CLI model ref into selected and Anthropic-compatible runtime refs. */
 export function resolveClaudeCliAnthropicModelRefs(
   raw: string,
 ): ClaudeCliAnthropicModelRefs | null {
@@ -214,6 +220,7 @@ export function resolveClaudeCliAnthropicModelRefs(
   };
 }
 
+/** Resolve a known Anthropic/Claude CLI model ref to its current Anthropic model ref. */
 export function resolveKnownAnthropicModelRef(raw?: string): string | null {
   if (!raw) {
     return null;
diff --git a/extensions/anthropic/cli-auth-seam.ts b/extensions/anthropic/cli-auth-seam.ts
index 76a6e7d92bd6..10d1028b0551 100644
--- a/extensions/anthropic/cli-auth-seam.ts
+++ b/extensions/anthropic/cli-auth-seam.ts
@@ -1,13 +1,20 @@
+/**
+ * Claude CLI auth seam. Setup may prompt for keychain-backed credentials while
+ * runtime paths stay non-interactive.
+ */
 import { readClaudeCliCredentialsCached } from "openclaw/plugin-sdk/provider-auth";
 
+/** Read Claude CLI credentials for interactive setup paths. */
 export function readClaudeCliCredentialsForSetup() {
   return readClaudeCliCredentialsCached();
 }
 
+/** Read Claude CLI credentials for setup checks that must not prompt. */
 export function readClaudeCliCredentialsForSetupNonInteractive() {
   return readClaudeCliCredentialsCached({ allowKeychainPrompt: false });
 }
 
+/** Read Claude CLI credentials for runtime without keychain prompts. */
 export function readClaudeCliCredentialsForRuntime() {
   return readClaudeCliCredentialsCached({ allowKeychainPrompt: false });
 }
diff --git a/extensions/anthropic/cli-backend.ts b/extensions/anthropic/cli-backend.ts
index 7b2e402feafb..bc0e14f7e2fd 100644
--- a/extensions/anthropic/cli-backend.ts
+++ b/extensions/anthropic/cli-backend.ts
@@ -1,3 +1,7 @@
+/**
+ * Claude CLI backend descriptor. It configures Claude Code process arguments,
+ * MCP bundling, session handling, environment scrubbing, and watchdog defaults.
+ */
 import type { CliBackendPlugin } from "openclaw/plugin-sdk/cli-backend";
 import {
   CLI_FRESH_WATCHDOG_DEFAULTS,
@@ -13,6 +17,7 @@ import {
   resolveClaudeCliExecutionArgs,
 } from "./cli-shared.js";
 
+/** Build the Claude CLI backend plugin descriptor. */
 export function buildAnthropicCliBackend(): CliBackendPlugin {
   return {
     id: CLAUDE_CLI_BACKEND_ID,
diff --git a/extensions/anthropic/cli-catalog.ts b/extensions/anthropic/cli-catalog.ts
index 0d72225e639b..4bda2bc2709c 100644
--- a/extensions/anthropic/cli-catalog.ts
+++ b/extensions/anthropic/cli-catalog.ts
@@ -1,3 +1,7 @@
+/**
+ * Claude CLI model catalog entries. Subscription-backed CLI models use picker
+ * metadata and do not require API-key auth rows.
+ */
 import type { ModelCatalogEntry } from "openclaw/plugin-sdk/agent-runtime";
 import { CLAUDE_CLI_BACKEND_ID, CLAUDE_CLI_DEFAULT_ALLOWLIST_REFS } from "./cli-constants.js";
 
@@ -39,6 +43,7 @@ function extractClaudeCliModelIds(): string[] {
   return ids;
 }
 
+/** Build catalog entries for the default Claude CLI allowlist. */
 export function buildClaudeCliCatalogEntries(): ModelCatalogEntry[] {
   return extractClaudeCliModelIds().map((id) => {
     return {
diff --git a/extensions/anthropic/cli-constants.ts b/extensions/anthropic/cli-constants.ts
index 9d19d1bb5d74..e31be5db17c0 100644
--- a/extensions/anthropic/cli-constants.ts
+++ b/extensions/anthropic/cli-constants.ts
@@ -1,5 +1,12 @@
+/**
+ * Shared Claude CLI constants. These identify the synthetic backend, default
+ * model refs, aliases, and session-id fields used across runtime and setup.
+ */
+/** Synthetic provider/backend id for Claude Code CLI-backed Anthropic models. */
 export const CLAUDE_CLI_BACKEND_ID = "claude-cli";
+/** Default Claude CLI model ref for agent defaults and live tests. */
 export const CLAUDE_CLI_DEFAULT_MODEL_REF = `${CLAUDE_CLI_BACKEND_ID}/claude-opus-4-8`;
+/** Default Claude CLI models allowed when setup seeds the model allowlist. */
 export const CLAUDE_CLI_DEFAULT_ALLOWLIST_REFS = [
   CLAUDE_CLI_DEFAULT_MODEL_REF,
   `${CLAUDE_CLI_BACKEND_ID}/claude-opus-4-7`,
@@ -7,6 +14,7 @@ export const CLAUDE_CLI_DEFAULT_ALLOWLIST_REFS = [
   `${CLAUDE_CLI_BACKEND_ID}/claude-opus-4-6`,
 ] as const;
 
+/** User-facing Claude CLI model aliases normalized before execution. */
 export const CLAUDE_CLI_MODEL_ALIASES: Record<string, string> = {
   opus: "opus",
   "opus-4.8": "claude-opus-4-8",
@@ -21,6 +29,7 @@ export const CLAUDE_CLI_MODEL_ALIASES: Record<string, string> = {
   haiku: "haiku",
 };
 
+/** JSONL fields that may contain Claude CLI session ids. */
 export const CLAUDE_CLI_SESSION_ID_FIELDS = [
   "session_id",
   "sessionId",
diff --git a/extensions/anthropic/cli-migration.ts b/extensions/anthropic/cli-migration.ts
index 545afd25131c..8e678c9c1f3b 100644
--- a/extensions/anthropic/cli-migration.ts
+++ b/extensions/anthropic/cli-migration.ts
@@ -1,3 +1,7 @@
+/**
+ * Claude CLI setup migration helpers. They rewrite legacy Claude CLI model refs
+ * to Anthropic refs while preserving runtime allowlist entries for CLI execution.
+ */
 import {
   CLAUDE_CLI_PROFILE_ID,
   type OpenClawConfig,
@@ -168,6 +172,7 @@ function modelEntryWithClaudeCliRuntime(entry: unknown): Record<string, unknown>
   return base;
 }
 
+/** Return whether Claude CLI credentials are available for setup migration. */
 export function hasClaudeCliAuth(options?: { allowKeychainPrompt?: boolean }): boolean {
   return Boolean(
     options?.allowKeychainPrompt === false
@@ -209,6 +214,7 @@ function buildClaudeCliAuthProfiles(
   ];
 }
 
+/** Build the config migration result for adopting Claude CLI-backed Anthropic defaults. */
 export function buildAnthropicCliMigrationResult(
   config: OpenClawConfig,
   credential?: ClaudeCliCredential | null,
diff --git a/extensions/anthropic/cli-shared.ts b/extensions/anthropic/cli-shared.ts
index a0865b7ce27a..cf33a35532f4 100644
--- a/extensions/anthropic/cli-shared.ts
+++ b/extensions/anthropic/cli-shared.ts
@@ -1,3 +1,7 @@
+/**
+ * Shared Claude CLI backend normalization. It sanitizes command args, maps
+ * thinking levels, and keeps OpenClaw-managed CLI runs isolated from shell env.
+ */
 import type {
   CliBackendConfig,
   CliBackendNormalizeConfigContext,
@@ -17,6 +21,7 @@ export {
 // consulting its local login state, so inherited shell overrides must not
 // steer OpenClaw-managed Claude CLI runs toward a different provider,
 // endpoint, token source, plugin/config tree, or telemetry bootstrap mode.
+/** Environment variables removed before launching OpenClaw-managed Claude CLI runs. */
 export const CLAUDE_CLI_CLEAR_ENV = [
   "ANTHROPIC_API_KEY",
   "ANTHROPIC_API_KEY_OLD",
@@ -67,6 +72,7 @@ const CLAUDE_BYPASS_PERMISSION_MODE = "bypassPermissions";
 
 type ClaudeCliEffort = "low" | "medium" | "high" | "xhigh" | "max";
 
+/** Return whether a provider id refers to the Claude CLI backend. */
 export function isClaudeCliProvider(providerId: string): boolean {
   return normalizeOptionalLowercaseString(providerId) === CLAUDE_CLI_BACKEND_ID;
 }
@@ -81,6 +87,7 @@ function isOpenClawRequestedYolo(context?: CliBackendNormalizeConfigContext): bo
   return security === "full" && ask === "off";
 }
 
+/** Resolve Claude permission mode from OpenClaw exec security settings. */
 export function resolveClaudePermissionMode(context?: CliBackendNormalizeConfigContext): {
   mode?: string;
   overrideExisting: boolean;
@@ -90,6 +97,7 @@ export function resolveClaudePermissionMode(context?: CliBackendNormalizeConfigC
     : { overrideExisting: false };
 }
 
+/** Normalize Claude permission arguments, removing legacy skip-permissions flags. */
 export function normalizeClaudePermissionArgs(
   args?: string[],
   options?: { mode?: string; overrideExisting?: boolean },
@@ -138,6 +146,7 @@ export function normalizeClaudePermissionArgs(
   return normalized;
 }
 
+/** Ensure Claude CLI setting sources stay restricted to user settings. */
 export function normalizeClaudeSettingSourcesArgs(args?: string[]): string[] | undefined {
   if (!args) {
     return args;
@@ -172,6 +181,7 @@ export function normalizeClaudeSettingSourcesArgs(args?: string[]): string[] | u
   return normalized;
 }
 
+/** Map OpenClaw thinking levels to Claude CLI effort flags for a model id. */
 export function mapClaudeCliThinkingLevelToEffort(
   thinkingLevel?: string | null,
 ): ClaudeCliEffort | undefined {
@@ -216,6 +226,7 @@ function stripClaudeEffortArgs(args: readonly string[]): string[] {
   return normalized;
 }
 
+/** Resolve final Claude CLI execution args for one backend invocation. */
 export function resolveClaudeCliExecutionArgs(
   context: CliBackendResolveExecutionArgsContext,
 ): string[] {
@@ -226,6 +237,7 @@ export function resolveClaudeCliExecutionArgs(
   return [...stripClaudeEffortArgs(context.baseArgs), CLAUDE_EFFORT_ARG, effort];
 }
 
+/** Normalize Claude CLI backend config before registration or execution. */
 export function normalizeClaudeBackendConfig(
   config: CliBackendConfig,
   context?: CliBackendNormalizeConfigContext,
diff --git a/extensions/anthropic/config-defaults.ts b/extensions/anthropic/config-defaults.ts
index 0a7869e0f334..d95212e2c04a 100644
--- a/extensions/anthropic/config-defaults.ts
+++ b/extensions/anthropic/config-defaults.ts
@@ -1,3 +1,7 @@
+/**
+ * Anthropic config defaulting helpers. They seed default Anthropic/Claude CLI
+ * model refs and cache-retention params based on configured auth mode.
+ */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/plugin-entry";
 import {
   isRecord,
@@ -274,6 +278,7 @@ function normalizeAnthropicProviderConfig<T extends { api?: string; models?: unk
   return { ...providerConfig, api: ANTHROPIC_PROVIDER_API };
 }
 
+/** Normalize Anthropic provider config defaults for one provider entry. */
 export function normalizeAnthropicProviderConfigForProvider<
   T extends { api?: string; models?: unknown[] },
 >(params: { provider: string; providerConfig: T }): T {
@@ -284,6 +289,7 @@ export function normalizeAnthropicProviderConfigForProvider<
   return normalizeAnthropicProviderConfig(params.providerConfig);
 }
 
+/** Apply Anthropic and Claude CLI defaults to an OpenClaw config object. */
 export function applyAnthropicConfigDefaults(params: {
   config: OpenClawConfig;
   env: NodeJS.ProcessEnv;
diff --git a/extensions/anthropic/contract-api.ts b/extensions/anthropic/contract-api.ts
index 34f998720bff..015a49213cd9 100644
--- a/extensions/anthropic/contract-api.ts
+++ b/extensions/anthropic/contract-api.ts
@@ -1,3 +1,7 @@
+/**
+ * Contract API barrel for Anthropic stream wrapper helpers. Tests and contract
+ * checks import this lightweight path instead of the full provider entry.
+ */
 export {
   createAnthropicBetaHeadersWrapper,
   createAnthropicFastModeWrapper,
diff --git a/extensions/anthropic/doctor-contract-api.ts b/extensions/anthropic/doctor-contract-api.ts
index 1023a8521d69..dfac75c346d3 100644
--- a/extensions/anthropic/doctor-contract-api.ts
+++ b/extensions/anthropic/doctor-contract-api.ts
@@ -1,7 +1,13 @@
+/**
+ * Doctor contract metadata for Anthropic and Claude CLI state. It declares
+ * session/auth ownership so doctor cleanup can route stale state correctly.
+ */
 import type { DoctorSessionRouteStateOwner } from "openclaw/plugin-sdk/runtime-doctor";
 
+/** Anthropic currently has no legacy config migrations. */
 export const legacyConfigRules = [];
 
+/** Session-route ownership metadata for Anthropic API and Claude CLI sessions. */
 export const sessionRouteStateOwners: DoctorSessionRouteStateOwner[] = [
   {
     id: "anthropic",