diff --git a/src/channels/inbound-event/classification.ts b/src/channels/inbound-event/classification.ts
index e4a805675ba8..24d82f17bd4a 100644
--- a/src/channels/inbound-event/classification.ts
+++ b/src/channels/inbound-event/classification.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel inbound event classifier.
+ *
+ * Decides whether group/channel activity should wake the agent or remain a passive room event.
+ */
 import { resolveAgentConfig } from "../../agents/agent-scope.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { ConversationFacts } from "../turn/types.js";
diff --git a/src/channels/inbound-event/context.ts b/src/channels/inbound-event/context.ts
index 0328ca325752..0cd442ca5978 100644
--- a/src/channels/inbound-event/context.ts
+++ b/src/channels/inbound-event/context.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel inbound event context builder.
+ *
+ * Converts route, sender, command, media, and supplemental facts into finalized message context.
+ */
 import {
   commandTurnKindToSource,
   createCommandTurnContext,
diff --git a/src/channels/inbound-event/media.ts b/src/channels/inbound-event/media.ts
index 8df8c214b3f9..65e6e997ccf4 100644
--- a/src/channels/inbound-event/media.ts
+++ b/src/channels/inbound-event/media.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel inbound media normalization.
+ *
+ * Converts plugin attachment metadata into aligned prompt/context media payload fields.
+ */
 import { normalizeOptionalString as normalizeString } from "@openclaw/normalization-core/string-coerce";
 import type { HistoryMediaEntry } from "../../auto-reply/reply/history.types.js";
 import type { InboundMediaFacts } from "../turn/types.js";
diff --git a/src/channels/mention-pattern-policy.ts b/src/channels/mention-pattern-policy.ts
index 6f7480a53705..bb73e5a81a20 100644
--- a/src/channels/mention-pattern-policy.ts
+++ b/src/channels/mention-pattern-policy.ts
@@ -1,3 +1,8 @@
+/**
+ * Mention-pattern policy resolver.
+ *
+ * Applies provider and conversation allow/deny rules to mention pattern matching.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { MentionPatternsMode, MentionPatternsPolicyConfig } from "../config/types.messages.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/channels/message-access/allowlist.ts b/src/channels/message-access/allowlist.ts
index 9369c1175e4b..100cb7ff9752 100644
--- a/src/channels/message-access/allowlist.ts
+++ b/src/channels/message-access/allowlist.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel ingress allowlist diagnostics.
+ *
+ * Merges allowlists, applies mutable identifier policy, and redacts access-graph facts.
+ */
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import type {
   ChannelIngressPolicyInput,
diff --git a/src/channels/message-access/decision.ts b/src/channels/message-access/decision.ts
index 8c9346d607b9..11aa373c488f 100644
--- a/src/channels/message-access/decision.ts
+++ b/src/channels/message-access/decision.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel ingress decision graph builder.
+ *
+ * Evaluates route, sender, command, and mention gates into one admission decision.
+ */
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { resolveCommandAuthorizedFromAuthorizers } from "../command-gating.js";
 import { resolveInboundMentionDecision } from "../mention-gating.js";
diff --git a/src/channels/message-access/dm-allow-state.ts b/src/channels/message-access/dm-allow-state.ts
index 6e14f3a89c9e..af9fc484e65f 100644
--- a/src/channels/message-access/dm-allow-state.ts
+++ b/src/channels/message-access/dm-allow-state.ts
@@ -1,9 +1,12 @@
+/**
+ * Direct-message allowlist audit state.
+ *
+ * Merges configured and persisted allowFrom entries for setup/status prompts.
+ */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { ChannelId } from "../plugins/types.public.js";
 import { readChannelIngressStoreAllowFromForDmPolicy } from "./runtime.js";
 
-// Builds the normalized DM allowlist state used by audits and setup prompts.
-// Config and persisted ingress-store entries are merged before counting users.
 export async function resolveDmAllowAuditState(params: {
   provider: ChannelId;
   accountId: string;
diff --git a/src/channels/message-access/runtime-access-groups.ts b/src/channels/message-access/runtime-access-groups.ts
index 91a07062af9c..63a2120cd987 100644
--- a/src/channels/message-access/runtime-access-groups.ts
+++ b/src/channels/message-access/runtime-access-groups.ts
@@ -1,3 +1,8 @@
+/**
+ * Runtime access-group resolution for channel ingress.
+ *
+ * Preserves symbolic access-group entries until dynamic membership facts are available.
+ */
 import {
   normalizeStringEntries,
   uniqueStrings,
diff --git a/src/channels/message-access/runtime-identity.ts b/src/channels/message-access/runtime-identity.ts
index 3650d656a963..e929e5d14442 100644
--- a/src/channels/message-access/runtime-identity.ts
+++ b/src/channels/message-access/runtime-identity.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel ingress identity adapter helpers.
+ *
+ * Builds stable sender identity descriptors and normalizes matchable allowlist material.
+ */
 import type {
   ChannelIngressAdapter,
   ChannelIngressAdapterEntry,
diff --git a/src/channels/message-access/runtime-types.ts b/src/channels/message-access/runtime-types.ts
index 61bf303e6323..50bede305706 100644
--- a/src/channels/message-access/runtime-types.ts
+++ b/src/channels/message-access/runtime-types.ts
@@ -1,3 +1,8 @@
+/**
+ * Public channel ingress runtime types.
+ *
+ * Defines identity descriptors, resolver inputs, route access, and resolved access results.
+ */
 import type { AccessGroupConfig } from "../../config/types.access-groups.js";
 import type {
   AccessGroupMembershipFact,
diff --git a/src/channels/message-access/runtime.ts b/src/channels/message-access/runtime.ts
index 84d79991e416..65b389f689b3 100644
--- a/src/channels/message-access/runtime.ts
+++ b/src/channels/message-access/runtime.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel ingress runtime resolver.
+ *
+ * Merges route, sender, command, access-group, and pairing-store facts before decision evaluation.
+ */
 import {
   normalizeStringEntries,
   uniqueStrings,
diff --git a/src/channels/message-access/sender-gates.ts b/src/channels/message-access/sender-gates.ts
index 00929f49278a..58c8a7f8df3f 100644
--- a/src/channels/message-access/sender-gates.ts
+++ b/src/channels/message-access/sender-gates.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel ingress sender gate helpers.
+ *
+ * Evaluates DM and group sender policies against normalized allowlists.
+ */
 import {
   allowlistFailureReason,
   applyMutableIdentifierPolicy,
diff --git a/src/channels/message-access/state.ts b/src/channels/message-access/state.ts
index 9f67e626620d..1809ddb16a06 100644
--- a/src/channels/message-access/state.ts
+++ b/src/channels/message-access/state.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel ingress state resolver.
+ *
+ * Normalizes and matches route, sender, command, and access-group allowlists.
+ */
 import {
   normalizeStringEntries,
   uniqueStrings,
diff --git a/src/channels/message-access/types.ts b/src/channels/message-access/types.ts
index adad5f88f11c..b596c845b081 100644
--- a/src/channels/message-access/types.ts
+++ b/src/channels/message-access/types.ts
@@ -1,3 +1,8 @@
+/**
+ * Internal channel ingress access graph types.
+ *
+ * Defines redacted identifiers, allowlist diagnostics, route facts, and decision gates.
+ */
 import type { AccessGroupConfig } from "../../config/types.access-groups.js";
 import type { ChatChannelId } from "../ids.js";
 import type { InboundImplicitMentionKind, InboundMentionFacts } from "../mention-gating.js";
diff --git a/src/channels/message/adapter.ts b/src/channels/message/adapter.ts
index 608a40778d75..482ba4c0934f 100644
--- a/src/channels/message/adapter.ts
+++ b/src/channels/message/adapter.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel message adapter definition helper.
+ *
+ * Supplies manual receive acknowledgement defaults while preserving adapter-specific types.
+ */
 import type {
   ChannelMessageAdapter,
   ChannelMessageAdapterShape,
diff --git a/src/channels/message/capabilities.ts b/src/channels/message/capabilities.ts
index 5749f91048be..2bb40ff27165 100644
--- a/src/channels/message/capabilities.ts
+++ b/src/channels/message/capabilities.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel message capability derivation.
+ *
+ * Computes durable-final delivery requirements from a concrete outbound payload.
+ */
 import type {
   DeriveDurableFinalDeliveryRequirementsParams,
   DurableFinalDeliveryCapability,
diff --git a/src/channels/message/contracts.ts b/src/channels/message/contracts.ts
index 4ad9bea62aa8..fc4bef95b39e 100644
--- a/src/channels/message/contracts.ts
+++ b/src/channels/message/contracts.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel message adapter contract verification helpers.
+ *
+ * Runs proof callbacks for declared durable, live-preview, live-message, and receive capabilities.
+ */
 import type {
   ChannelMessageAdapterShape,
   ChannelMessageLiveCapability,
diff --git a/src/channels/message/durable-receive.ts b/src/channels/message/durable-receive.ts
index 2580e49d2f5c..5674c462858d 100644
--- a/src/channels/message/durable-receive.ts
+++ b/src/channels/message/durable-receive.ts
@@ -1,3 +1,8 @@
+/**
+ * Durable inbound receive journal.
+ *
+ * Tracks accepted, pending, completed, and retryable inbound platform events.
+ */
 import type { PluginStateKeyedStore } from "../../plugin-state/plugin-state-store.types.js";
 import type { ChannelIngressQueue, ChannelIngressQueuePruneOptions } from "./ingress-queue.js";
 
diff --git a/src/channels/message/ingress-queue.ts b/src/channels/message/ingress-queue.ts
index 0b39c7fb8fc0..0eea71f08d09 100644
--- a/src/channels/message/ingress-queue.ts
+++ b/src/channels/message/ingress-queue.ts
@@ -1,3 +1,8 @@
+/**
+ * Durable channel ingress queue.
+ *
+ * Stores, claims, completes, and tombstones inbound channel events in OpenClaw state.
+ */
 import { randomUUID } from "node:crypto";
 import type { DatabaseSync } from "node:sqlite";
 import type { Selectable } from "kysely";
diff --git a/src/channels/message/live.ts b/src/channels/message/live.ts
index 2a555f52a774..797899f16438 100644
--- a/src/channels/message/live.ts
+++ b/src/channels/message/live.ts
@@ -1,3 +1,8 @@
+/**
+ * Live channel message state and preview finalization helpers.
+ *
+ * Tracks draft previews and converts them into finalized message receipts when possible.
+ */
 import type { LiveMessageState, MessageReceipt, RenderedMessageBatch } from "./types.js";
 export type { LiveMessagePhase, LiveMessageState } from "./types.js";
 
diff --git a/src/channels/message/outbound-bridge.ts b/src/channels/message/outbound-bridge.ts
index dfc6ac19889f..a7f1897a1adf 100644
--- a/src/channels/message/outbound-bridge.ts
+++ b/src/channels/message/outbound-bridge.ts
@@ -1,3 +1,8 @@
+/**
+ * Legacy outbound bridge adapter.
+ *
+ * Wraps old channel send functions in the newer channel message adapter contract.
+ */
 import { createMessageReceiptFromOutboundResults } from "./receipt.js";
 import type {
   ChannelMessageAdapterShape,
diff --git a/src/channels/message/receipt.ts b/src/channels/message/receipt.ts
index e1fd23bfe2bb..cda9607351e2 100644
--- a/src/channels/message/receipt.ts
+++ b/src/channels/message/receipt.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel message receipt normalization.
+ *
+ * Builds stable receipts from platform send results and nested adapter receipt data.
+ */
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type {
   MessageReceipt,
diff --git a/src/channels/message/receive.ts b/src/channels/message/receive.ts
index d6677f569240..e77560d149ef 100644
--- a/src/channels/message/receive.ts
+++ b/src/channels/message/receive.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel message receive acknowledgement context.
+ *
+ * Models ack/nack policy and idempotent receive state transitions for inbound events.
+ */
 import type { ChannelMessageReceiveAckPolicy } from "./types.js";
 
 /** Public alias for channel receive acknowledgement policy names. */
diff --git a/src/channels/message/rendered-batch.ts b/src/channels/message/rendered-batch.ts
index 844bbb17aa02..abb48e17d4c2 100644
--- a/src/channels/message/rendered-batch.ts
+++ b/src/channels/message/rendered-batch.ts
@@ -1,3 +1,8 @@
+/**
+ * Rendered channel message batch planner.
+ *
+ * Summarizes reply payloads so delivery can pick adapter paths and recovery metadata.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import type {
   RenderedMessageBatch,
diff --git a/src/channels/message/reply-pipeline.ts b/src/channels/message/reply-pipeline.ts
index e015650a44c9..d11f4a09ec65 100644
--- a/src/channels/message/reply-pipeline.ts
+++ b/src/channels/message/reply-pipeline.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel reply pipeline builder.
+ *
+ * Resolves source delivery mode, reply prefixing, typing callbacks, and payload transforms.
+ */
 import type { SourceReplyDeliveryMode } from "../../auto-reply/get-reply-options.types.js";
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import {
diff --git a/src/channels/message/send.ts b/src/channels/message/send.ts
index f56fa6ebcac3..4d3e832833eb 100644
--- a/src/channels/message/send.ts
+++ b/src/channels/message/send.ts
@@ -1,3 +1,8 @@
+/**
+ * Durable channel message sender.
+ *
+ * Sends rendered reply payloads, records live preview state, and classifies delivery outcomes.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import { formatErrorMessage } from "../../infra/errors.js";
 import type { OutboundDeliveryResult } from "../../infra/outbound/deliver-types.js";
diff --git a/src/channels/message/state.ts b/src/channels/message/state.ts
index 8bc46c965a8d..d154058e3e1a 100644
--- a/src/channels/message/state.ts
+++ b/src/channels/message/state.ts
@@ -1,3 +1,8 @@
+/**
+ * Durable outbound message recovery state.
+ *
+ * Creates and classifies persisted send records after delivery interruptions.
+ */
 import type { DurableMessageSendIntent, MessageReceipt } from "./types.js";
 
 /** Durable send state stored for recovery and operator-visible delivery status. */
diff --git a/src/channels/message/types.ts b/src/channels/message/types.ts
index 44020881f94b..db7d94f75159 100644
--- a/src/channels/message/types.ts
+++ b/src/channels/message/types.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel message adapter and durability types.
+ *
+ * Defines receipts, live-message state, send contexts, and adapter capability contracts.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import type { ReplyToMode } from "../../config/types.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/channels/model-overrides.ts b/src/channels/model-overrides.ts
index d76b02dd003d..e5313fad5304 100644
--- a/src/channels/model-overrides.ts
+++ b/src/channels/model-overrides.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel-scoped model override resolver.
+ *
+ * Matches conversation ids, parent sessions, and wildcard config entries to model overrides.
+ */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
diff --git a/src/channels/native-command-session-targets.ts b/src/channels/native-command-session-targets.ts
index 6b01c1ee7629..0057edcaab8c 100644
--- a/src/channels/native-command-session-targets.ts
+++ b/src/channels/native-command-session-targets.ts
@@ -1,3 +1,8 @@
+/**
+ * Native command session target resolver.
+ *
+ * Chooses storage and command target session keys for channel-native command events.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /**
diff --git a/src/channels/plugins/account-helpers.ts b/src/channels/plugins/account-helpers.ts
index f4eb6ba2aab0..439fea95e49c 100644
--- a/src/channels/plugins/account-helpers.ts
+++ b/src/channels/plugins/account-helpers.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel plugin account helper factory.
+ *
+ * Lists configured accounts and resolves default-account behavior for plugin configs.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/channels/plugins/acp-configured-binding-consumer.ts b/src/channels/plugins/acp-configured-binding-consumer.ts
index 305fe5f8329b..45855653a172 100644
--- a/src/channels/plugins/acp-configured-binding-consumer.ts
+++ b/src/channels/plugins/acp-configured-binding-consumer.ts
@@ -1,3 +1,8 @@
+/**
+ * ACP configured binding consumer.
+ *
+ * Converts channel configured-binding rules into persistent ACP binding records.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,