From 67ddda2a21ff669caf856febdf4f0f8e0b3bcf6c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 10:39:46 -0400
Subject: [PATCH] docs: document channel plugin runtime helpers

---
 src/channels/plugins/doctor-contract-api.ts          |  5 +++++
 src/channels/plugins/exposure.ts                     |  5 +++++
 src/channels/plugins/gateway-auth-bypass.ts          |  5 +++++
 src/channels/plugins/meta-normalization.ts           |  7 +++++--
 src/channels/plugins/module-loader.ts                |  5 +++++
 src/channels/plugins/native-approval-prompt.ts       |  8 +++++---
 src/channels/plugins/outbound.types.ts               |  5 +++++
 src/channels/plugins/outbound/direct-text-media.ts   |  9 +++++----
 src/channels/plugins/outbound/interactive.ts         |  5 +++++
 src/channels/plugins/outbound/load.ts                | 10 +++++-----
 src/channels/plugins/outbound/load.types.ts          |  5 +++++
 src/channels/plugins/outbound/presentation-limits.ts |  5 +++++
 src/channels/plugins/package-state-probes.ts         |  9 +++++----
 src/channels/plugins/pairing-adapters.ts             |  7 ++++---
 src/channels/plugins/pairing.ts                      |  5 +++++
 src/channels/plugins/pairing.types.ts                |  5 +++++
 src/channels/plugins/persisted-auth-state.ts         |  9 +++++----
 src/channels/plugins/read-only-command-defaults.ts   |  9 +++++----
 src/channels/plugins/read-only.ts                    |  5 +++++
 src/channels/plugins/registry-loaded-read.ts         |  9 +++++----
 src/channels/plugins/registry-loaded.ts              |  9 +++++----
 src/channels/plugins/registry-loader.ts              |  9 +++++----
 src/channels/plugins/registry.ts                     |  9 +++++----
 src/channels/plugins/runtime-forwarders.ts           |  7 ++++---
 src/channels/plugins/session-conversation.ts         |  9 +++++----
 src/channels/plugins/session-thread-info-loaded.ts   |  9 +++++----
 src/channels/plugins/setup-group-access-configure.ts |  5 +++++
 src/channels/plugins/setup-group-access.ts           |  9 +++++----
 src/channels/plugins/setup-helpers.ts                |  5 +++++
 src/channels/plugins/setup-promotion-helpers.ts      |  9 +++++----
 src/channels/plugins/setup-registry.ts               |  9 +++++----
 src/channels/plugins/setup-wizard-binary.ts          |  5 +++++
 32 files changed, 158 insertions(+), 68 deletions(-)

diff --git a/src/channels/plugins/doctor-contract-api.ts b/src/channels/plugins/doctor-contract-api.ts
index 9978b17c90c5..eca1f23345e6 100644
--- a/src/channels/plugins/doctor-contract-api.ts
+++ b/src/channels/plugins/doctor-contract-api.ts
@@ -1,3 +1,8 @@
+/**
+ * Bundled channel doctor contract loader.
+ *
+ * Loads public doctor hooks for channel-owned legacy config rules and compatibility repairs.
+ */
 import type { LegacyConfigRule } from "../../config/legacy.shared.js";
 import type { OpenClawConfig } from "../../config/types.js";
 import { loadBundledPluginPublicArtifactModuleSync } from "../../plugins/public-surface-loader.js";
diff --git a/src/channels/plugins/exposure.ts b/src/channels/plugins/exposure.ts
index 1b7587179df9..e9aecd1c0b13 100644
--- a/src/channels/plugins/exposure.ts
+++ b/src/channels/plugins/exposure.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel exposure helpers.
+ *
+ * Resolves whether channel metadata should appear in configured, setup, and docs views.
+ */
 import type { ChannelMeta } from "./types.core.js";
 
 /**
diff --git a/src/channels/plugins/gateway-auth-bypass.ts b/src/channels/plugins/gateway-auth-bypass.ts
index fe199da09eba..b02fba423453 100644
--- a/src/channels/plugins/gateway-auth-bypass.ts
+++ b/src/channels/plugins/gateway-auth-bypass.ts
@@ -1,3 +1,8 @@
+/**
+ * Bundled channel gateway auth bypass loader.
+ *
+ * Reads optional public artifacts that declare unauthenticated Gateway callback paths.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { loadBundledPluginPublicArtifactModuleSync } from "../../plugins/public-surface-loader.js";
 
diff --git a/src/channels/plugins/meta-normalization.ts b/src/channels/plugins/meta-normalization.ts
index 7785f45a048d..6d211f359cd3 100644
--- a/src/channels/plugins/meta-normalization.ts
+++ b/src/channels/plugins/meta-normalization.ts
@@ -1,8 +1,11 @@
+/**
+ * Channel metadata normalizer.
+ *
+ * Recomputes required metadata fields while preserving optional manifest/registry fields.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { ChannelMeta } from "./types.public.js";
 
-// Normalizes partially declared channel metadata while preserving optional
-// extension-owned fields from an existing manifest or registry entry.
 function stripRequiredChannelMeta(meta?: Partial<ChannelMeta> | null) {
   const {
     id: _ignoredId,
diff --git a/src/channels/plugins/module-loader.ts b/src/channels/plugins/module-loader.ts
index 0a3f5c85a7d4..07903852a979 100644
--- a/src/channels/plugins/module-loader.ts
+++ b/src/channels/plugins/module-loader.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel plugin module loader.
+ *
+ * Loads JavaScript or source plugin modules through native require or cached TS loaders.
+ */
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
diff --git a/src/channels/plugins/native-approval-prompt.ts b/src/channels/plugins/native-approval-prompt.ts
index 8ec70801ebe6..7d12847e3bc7 100644
--- a/src/channels/plugins/native-approval-prompt.ts
+++ b/src/channels/plugins/native-approval-prompt.ts
@@ -1,3 +1,8 @@
+/**
+ * Native approval prompt capability helpers.
+ *
+ * Detects loaded or known channels that can render approval prompts natively.
+ */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { resolveChannelApprovalCapability } from "./approvals.js";
 import type { ChannelPlugin } from "./types.plugin.js";
@@ -6,9 +11,6 @@ export const NATIVE_APPROVAL_PROMPT_RUNTIME_CAPABILITY = "nativeApprovals";
 
 const NATIVE_APPROVAL_PROMPT_RUNTIME_CAPABILITY_NORMALIZED = "nativeapprovals";
 
-// Keep prompt construction lightweight. Full plugin loading is too expensive on
-// prompt-only import paths; plugin-backed checks still cover loaded native
-// channels at runtime.
 const KNOWN_NATIVE_APPROVAL_PROMPT_CHANNELS = new Set([
   "discord",
   "matrix",
diff --git a/src/channels/plugins/outbound.types.ts b/src/channels/plugins/outbound.types.ts
index a347073d3817..9975f19dd70c 100644
--- a/src/channels/plugins/outbound.types.ts
+++ b/src/channels/plugins/outbound.types.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel outbound adapter types.
+ *
+ * Defines text/media/payload/poll contexts, presentation capabilities, and send results.
+ */
 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/plugins/outbound/direct-text-media.ts b/src/channels/plugins/outbound/direct-text-media.ts
index d39568b6d61c..e008a12345cb 100644
--- a/src/channels/plugins/outbound/direct-text-media.ts
+++ b/src/channels/plugins/outbound/direct-text-media.ts
@@ -1,3 +1,8 @@
+/**
+ * Direct text/media outbound adapter helpers.
+ *
+ * Builds lightweight SDK-backed send adapters with chunking, sanitization, and media limits.
+ */
 import { sendTextMediaPayload } from "openclaw/plugin-sdk/reply-payload";
 import { chunkText } from "../../../auto-reply/chunk.js";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
@@ -7,10 +12,6 @@ import type { OutboundMediaAccess } from "../../../media/load-options.js";
 import { resolveChannelMediaMaxBytes } from "../media-limits.js";
 import type { ChannelOutboundAdapter } from "../types.adapters.js";
 
-/**
- * Shared direct text/media outbound adapter factory for SDK-backed channels.
- */
-
 type DirectSendOptions = {
   cfg: OpenClawConfig;
   accountId?: string | null;
diff --git a/src/channels/plugins/outbound/interactive.ts b/src/channels/plugins/outbound/interactive.ts
index c89f9b02d04c..5863da40590c 100644
--- a/src/channels/plugins/outbound/interactive.ts
+++ b/src/channels/plugins/outbound/interactive.ts
@@ -1,3 +1,8 @@
+/**
+ * Interactive outbound compatibility helpers.
+ *
+ * Re-exports presentation adapters and keeps the deprecated interactive reducer available.
+ */
 import type { InteractiveReply, InteractiveReplyBlock } from "../../../interactive/payload.js";
 export {
   adaptMessagePresentationForChannel,
diff --git a/src/channels/plugins/outbound/load.ts b/src/channels/plugins/outbound/load.ts
index f340e8c0cc59..c22c6d51b93a 100644
--- a/src/channels/plugins/outbound/load.ts
+++ b/src/channels/plugins/outbound/load.ts
@@ -1,13 +1,13 @@
+/**
+ * Lazy channel outbound adapter loader.
+ *
+ * Loads only outbound send primitives from the channel registry for cheap delivery paths.
+ */
 import type { ChannelId } from "../channel-id.types.js";
 import type { ChannelOutboundAdapter } from "../outbound.types.js";
 import { createChannelRegistryLoader } from "../registry-loader.js";
 import type { LoadChannelOutboundAdapter } from "./load.types.js";
 
-// Channel docking: outbound sends should stay cheap to import.
-//
-// The full channel plugins (src/channels/plugins/*.ts) pull in status,
-// setup, gateway monitors, etc. Outbound delivery only needs chunking +
-// send primitives, so we keep a dedicated, lightweight loader here.
 const loadOutboundAdapterFromRegistry = createChannelRegistryLoader<ChannelOutboundAdapter>(
   (entry) => entry.plugin.outbound,
 );
diff --git a/src/channels/plugins/outbound/load.types.ts b/src/channels/plugins/outbound/load.types.ts
index 4e5eda26851f..6c354eb7f420 100644
--- a/src/channels/plugins/outbound/load.types.ts
+++ b/src/channels/plugins/outbound/load.types.ts
@@ -1,3 +1,8 @@
+/**
+ * Lazy outbound adapter loader type.
+ *
+ * Describes the minimal async boundary used by channel delivery code.
+ */
 import type { ChannelId } from "../channel-id.types.js";
 import type { ChannelOutboundAdapter } from "../outbound.types.js";
 
diff --git a/src/channels/plugins/outbound/presentation-limits.ts b/src/channels/plugins/outbound/presentation-limits.ts
index 602f3ef9f7ff..bc5df274704a 100644
--- a/src/channels/plugins/outbound/presentation-limits.ts
+++ b/src/channels/plugins/outbound/presentation-limits.ts
@@ -1,3 +1,8 @@
+/**
+ * Presentation limit adapters for channel outbound payloads.
+ *
+ * Truncates and reshapes portable presentation blocks to match per-channel limits.
+ */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { resolveMessagePresentationActionValue } from "../../../interactive/payload.js";
 import type {
diff --git a/src/channels/plugins/package-state-probes.ts b/src/channels/plugins/package-state-probes.ts
index 58b8f9b7da86..62875baa577d 100644
--- a/src/channels/plugins/package-state-probes.ts
+++ b/src/channels/plugins/package-state-probes.ts
@@ -1,3 +1,8 @@
+/**
+ * Bundled channel package-state probes.
+ *
+ * Resolves lightweight configured/auth state checkers from package metadata and source overlays.
+ */
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -17,10 +22,6 @@ import {
 } from "../../plugins/plugin-module-loader-cache.js";
 import { loadChannelPluginModule, resolveExistingPluginModulePath } from "./module-loader.js";
 
-/**
- * Package-state probes for bundled channel configured/auth state metadata.
- */
-
 type ChannelPackageStateChecker = (params: {
   cfg: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
diff --git a/src/channels/plugins/pairing-adapters.ts b/src/channels/plugins/pairing-adapters.ts
index 2672591f0ab7..1cdc491e1dda 100644
--- a/src/channels/plugins/pairing-adapters.ts
+++ b/src/channels/plugins/pairing-adapters.ts
@@ -1,8 +1,9 @@
-import type { ChannelPairingAdapter } from "./types.adapters.js";
-
 /**
- * Shared pairing adapter helpers for channel SDK/runtime facades.
+ * Channel pairing adapter helpers.
+ *
+ * Creates prefix-stripping normalizers and logged/text pairing approval notifiers.
  */
+import type { ChannelPairingAdapter } from "./types.adapters.js";
 
 type PairingNotifyParams = Parameters<NonNullable<ChannelPairingAdapter["notifyApproval"]>>[0];
 
diff --git a/src/channels/plugins/pairing.ts b/src/channels/plugins/pairing.ts
index 4d07c51635a6..7c6af1299f05 100644
--- a/src/channels/plugins/pairing.ts
+++ b/src/channels/plugins/pairing.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel pairing registry facade.
+ *
+ * Lists pairing-capable channels and dispatches approval notifications through adapters.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import type { ChannelId } from "./channel-id.types.js";
diff --git a/src/channels/plugins/pairing.types.ts b/src/channels/plugins/pairing.types.ts
index 238537688917..40ab28e00c7b 100644
--- a/src/channels/plugins/pairing.types.ts
+++ b/src/channels/plugins/pairing.types.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel pairing adapter types.
+ *
+ * Defines setup/allowlist approval hooks used by pairing flows.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { RuntimeEnv } from "../../runtime.js";
 
diff --git a/src/channels/plugins/persisted-auth-state.ts b/src/channels/plugins/persisted-auth-state.ts
index 91c2b43717af..a28fbc889eaa 100644
--- a/src/channels/plugins/persisted-auth-state.ts
+++ b/src/channels/plugins/persisted-auth-state.ts
@@ -1,3 +1,8 @@
+/**
+ * Bundled channel persisted-auth state probes.
+ *
+ * Lists and checks channel package metadata that can report persisted auth state.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { PluginDiscoveryResult } from "../../plugins/discovery.js";
 import {
@@ -5,10 +10,6 @@ import {
   listBundledChannelIdsForPackageState,
 } from "./package-state-probes.js";
 
-/**
- * Persisted-auth state probes backed by bundled channel package metadata.
- */
-
 /**
  * Lists bundled channels that declare persisted-auth state metadata.
  */
diff --git a/src/channels/plugins/read-only-command-defaults.ts b/src/channels/plugins/read-only-command-defaults.ts
index 4a7c92964790..91b7fe3a063f 100644
--- a/src/channels/plugins/read-only-command-defaults.ts
+++ b/src/channels/plugins/read-only-command-defaults.ts
@@ -1,3 +1,8 @@
+/**
+ * Read-only channel command default resolver.
+ *
+ * Reads native command/skill defaults from installed plugin manifests without loading plugins.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { isBlockedObjectKey } from "../../infra/prototype-keys.js";
@@ -6,10 +11,6 @@ import type { PluginManifestRecord } from "../../plugins/manifest-registry.js";
 import { resolvePluginMetadataSnapshot } from "../../plugins/plugin-metadata-snapshot.js";
 import type { ChannelPlugin } from "./types.plugin.js";
 
-/**
- * Read-only command default resolution from installed plugin manifests.
- */
-
 const SAFE_MANIFEST_CHANNEL_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
 
 /**
diff --git a/src/channels/plugins/read-only.ts b/src/channels/plugins/read-only.ts
index 398db19aa439..d1ec2bf73f5d 100644
--- a/src/channels/plugins/read-only.ts
+++ b/src/channels/plugins/read-only.ts
@@ -1,3 +1,8 @@
+/**
+ * Read-only channel plugin discovery.
+ *
+ * Builds lightweight channel plugin views from config, manifests, and setup metadata.
+ */
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
diff --git a/src/channels/plugins/registry-loaded-read.ts b/src/channels/plugins/registry-loaded-read.ts
index 19064c5cf55c..7d861997151e 100644
--- a/src/channels/plugins/registry-loaded-read.ts
+++ b/src/channels/plugins/registry-loaded-read.ts
@@ -1,13 +1,14 @@
+/**
+ * Hot-path loaded channel plugin reader.
+ *
+ * Reads active runtime channel state without materializing the full registry view.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { ActiveChannelPluginRuntimeShape } from "../../plugins/channel-registry-state.types.js";
 import { getActivePluginChannelRegistryFromState } from "../../plugins/runtime-channel-state.js";
 import type { ChannelPlugin } from "./types.plugin.js";
 import type { ChannelId } from "./types.public.js";
 
-/**
- * Minimal loaded-plugin reader for hot outbound/read paths.
- */
-
 function coerceLoadedChannelPlugin(
   plugin: ActiveChannelPluginRuntimeShape | null | undefined,
 ): ChannelPlugin | undefined {
diff --git a/src/channels/plugins/registry-loaded.ts b/src/channels/plugins/registry-loaded.ts
index 385225eae85b..8731dc0464cc 100644
--- a/src/channels/plugins/registry-loaded.ts
+++ b/src/channels/plugins/registry-loaded.ts
@@ -1,3 +1,8 @@
+/**
+ * Loaded channel plugin registry view.
+ *
+ * Normalizes and sorts active plugin runtime state for channel registry callers.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type {
   ActiveChannelPluginRuntimeShape,
@@ -6,10 +11,6 @@ import type {
 import { getActivePluginChannelRegistryFromState } from "../../plugins/runtime-channel-state.js";
 import { CHAT_CHANNEL_ORDER } from "../registry.js";
 
-/**
- * Loaded channel plugin registry view derived from active plugin runtime state.
- */
-
 /**
  * Loaded channel plugin shape after id/meta normalization.
  */
diff --git a/src/channels/plugins/registry-loader.ts b/src/channels/plugins/registry-loader.ts
index 1cb5d6dd03ae..1d6e1c2cf166 100644
--- a/src/channels/plugins/registry-loader.ts
+++ b/src/channels/plugins/registry-loader.ts
@@ -1,11 +1,12 @@
+/**
+ * Lazy channel registry value loader.
+ *
+ * Resolves plugin sub-surfaces from active channel or full plugin registry state.
+ */
 import type { PluginChannelRegistration } from "../../plugins/registry-types.js";
 import { getActivePluginChannelRegistry, getActivePluginRegistry } from "../../plugins/runtime.js";
 import type { ChannelId } from "./channel-id.types.js";
 
-/**
- * Generic channel registry loader for lazily resolved plugin sub-surfaces.
- */
-
 type ChannelRegistryValueResolver<TValue> = (
   entry: PluginChannelRegistration,
 ) => TValue | undefined;
diff --git a/src/channels/plugins/registry.ts b/src/channels/plugins/registry.ts
index 11b5c3ee88c9..b8a377c8b0d0 100644
--- a/src/channels/plugins/registry.ts
+++ b/src/channels/plugins/registry.ts
@@ -1,3 +1,8 @@
+/**
+ * Runtime channel plugin registry facade.
+ *
+ * Lists, resolves, and normalizes active channel plugins with bundled fallback.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeAnyChannelId } from "../registry.js";
 import { getBundledChannelPlugin } from "./bundled.js";
@@ -9,10 +14,6 @@ import {
 import type { ChannelPlugin } from "./types.plugin.js";
 import type { ChannelId } from "./types.public.js";
 
-/**
- * Runtime channel plugin registry facade used by core command/gateway paths.
- */
-
 /**
  * Lists currently loaded channel plugins in registry order.
  */
diff --git a/src/channels/plugins/runtime-forwarders.ts b/src/channels/plugins/runtime-forwarders.ts
index fa8a085e3c22..223763d0eb3b 100644
--- a/src/channels/plugins/runtime-forwarders.ts
+++ b/src/channels/plugins/runtime-forwarders.ts
@@ -1,8 +1,9 @@
-import type { ChannelDirectoryAdapter, ChannelOutboundAdapter } from "./types.adapters.js";
-
 /**
- * Runtime delegate factories for plugin adapters that load heavy runtimes lazily.
+ * Runtime adapter forwarders.
+ *
+ * Creates directory and outbound adapters whose methods delegate to lazily resolved runtimes.
  */
+import type { ChannelDirectoryAdapter, ChannelOutboundAdapter } from "./types.adapters.js";
 
 type MaybePromise<T> = T | Promise<T>;
 
diff --git a/src/channels/plugins/session-conversation.ts b/src/channels/plugins/session-conversation.ts
index 8fba4ff4c797..e9db9e73cb4e 100644
--- a/src/channels/plugins/session-conversation.ts
+++ b/src/channels/plugins/session-conversation.ts
@@ -1,3 +1,8 @@
+/**
+ * Session conversation key helpers.
+ *
+ * Resolves threaded channel session keys through plugin hooks and generic parsing.
+ */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -14,10 +19,6 @@ import {
 import { normalizeChannelId as normalizeChatChannelId } from "../registry.js";
 import { getLoadedChannelPlugin, normalizeChannelId as normalizeAnyChannelId } from "./registry.js";
 
-/**
- * Session-key conversation resolution helpers for threaded channel targets.
- */
-
 /**
  * Normalized conversation id details for one channel raw id.
  */
diff --git a/src/channels/plugins/session-thread-info-loaded.ts b/src/channels/plugins/session-thread-info-loaded.ts
index e002d5203b01..7cf6ce99ae03 100644
--- a/src/channels/plugins/session-thread-info-loaded.ts
+++ b/src/channels/plugins/session-thread-info-loaded.ts
@@ -1,3 +1,8 @@
+/**
+ * Loaded-plugin session thread info resolver.
+ *
+ * Uses only already loaded channel hooks to resolve thread suffix metadata on hot paths.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   parseRawSessionConversationRef,
@@ -6,10 +11,6 @@ import {
 } from "../../sessions/session-key-utils.js";
 import { getLoadedChannelPluginForRead } from "./registry-loaded-read.js";
 
-/**
- * Hot-path thread info resolver that consults only already loaded channel plugins.
- */
-
 type SessionConversationHookResult = {
   id: string;
   threadId?: string | null;
diff --git a/src/channels/plugins/setup-group-access-configure.ts b/src/channels/plugins/setup-group-access-configure.ts
index 8f319aa34510..49133a1c1ab0 100644
--- a/src/channels/plugins/setup-group-access-configure.ts
+++ b/src/channels/plugins/setup-group-access-configure.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel setup group access configurator.
+ *
+ * Applies prompted group policy and allowlist entries through channel-specific hooks.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { WizardPrompter } from "../../wizard/prompts.js";
 import { promptChannelAccessConfig, type ChannelAccessPolicy } from "./setup-group-access.js";
diff --git a/src/channels/plugins/setup-group-access.ts b/src/channels/plugins/setup-group-access.ts
index b00b9d63f338..41cd9c4909e1 100644
--- a/src/channels/plugins/setup-group-access.ts
+++ b/src/channels/plugins/setup-group-access.ts
@@ -1,10 +1,11 @@
+/**
+ * Channel setup group access prompts.
+ *
+ * Prompts and normalizes allowlist/open/disabled group access policy choices.
+ */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { WizardPrompter } from "../../wizard/prompts.js";
 
-/**
- * Shared setup prompts for channel group access allowlists.
- */
-
 /**
  * Group access policy selected during channel setup.
  */
diff --git a/src/channels/plugins/setup-helpers.ts b/src/channels/plugins/setup-helpers.ts
index 84382eb82f7b..a60295b22f7d 100644
--- a/src/channels/plugins/setup-helpers.ts
+++ b/src/channels/plugins/setup-helpers.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel setup config mutation helpers.
+ *
+ * Applies account names and validates setup results for channel onboarding adapters.
+ */
 import { z, type ZodType } from "zod";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../routing/session-key.js";
diff --git a/src/channels/plugins/setup-promotion-helpers.ts b/src/channels/plugins/setup-promotion-helpers.ts
index 5ce7f3331ae4..539518fe7477 100644
--- a/src/channels/plugins/setup-promotion-helpers.ts
+++ b/src/channels/plugins/setup-promotion-helpers.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel setup promotion helpers.
+ *
+ * Moves legacy single-account channel config into account-scoped config records.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../routing/session-key.js";
 import { getBundledChannelPlugin, hasBundledChannelPackageSetupFeature } from "./bundled.js";
@@ -7,10 +12,6 @@ import {
   isCommonSingleAccountPromotionKey,
 } from "./setup-promotion-keys.js";
 
-/**
- * Helpers for promoting legacy single-account channel config into `accounts`.
- */
-
 type ChannelSectionBase = {
   defaultAccount?: string;
   accounts?: Record<string, Record<string, unknown>>;
diff --git a/src/channels/plugins/setup-registry.ts b/src/channels/plugins/setup-registry.ts
index bce3eba9d464..63e3a8767372 100644
--- a/src/channels/plugins/setup-registry.ts
+++ b/src/channels/plugins/setup-registry.ts
@@ -1,3 +1,8 @@
+/**
+ * Channel setup plugin registry.
+ *
+ * Resolves loaded or bundled setup plugins for onboarding flows.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   getActivePluginChannelRegistry,
@@ -8,10 +13,6 @@ import { listBundledChannelSetupPlugins } from "./bundled.js";
 import type { ChannelPlugin } from "./types.plugin.js";
 import type { ChannelId } from "./types.public.js";
 
-/**
- * Setup plugin registry facade for channel onboarding flows.
- */
-
 type ChannelSetupPluginView = {
   sorted: ChannelPlugin[];
   byId: Map<string, ChannelPlugin>;
diff --git a/src/channels/plugins/setup-wizard-binary.ts b/src/channels/plugins/setup-wizard-binary.ts
index d14ff6cc2b2c..29b6cbd15f30 100644
--- a/src/channels/plugins/setup-wizard-binary.ts
+++ b/src/channels/plugins/setup-wizard-binary.ts
@@ -1,3 +1,8 @@
+/**
+ * Setup wizard binary helpers.
+ *
+ * Builds status and text-input helpers for channel setup flows that need local binaries.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { detectBinary as defaultDetectBinary } from "../../plugins/setup-binary.js";
 import type {