diff --git a/src/entry.compile-cache.test.ts b/src/entry.compile-cache.test.ts
index c25e8c7025b4..23bca663e9da 100644
--- a/src/entry.compile-cache.test.ts
+++ b/src/entry.compile-cache.test.ts
@@ -1,3 +1,4 @@
+// Tests compile-cache child-process spawning and environment propagation.
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
diff --git a/src/entry.respawn.ts b/src/entry.respawn.ts
index a0d759cda210..9c2e60ccbdc8 100644
--- a/src/entry.respawn.ts
+++ b/src/entry.respawn.ts
@@ -1,3 +1,4 @@
+// Respawns the CLI with adjusted process flags when startup requires it.
 import { spawn, type ChildProcess } from "node:child_process";
 import path from "node:path";
 import { resolveNodeStartupTlsEnvironment } from "./bootstrap/node-startup-env.js";
diff --git a/src/entry.root-help-fast-path.test.ts b/src/entry.root-help-fast-path.test.ts
index 26676214ee94..69812e855513 100644
--- a/src/entry.root-help-fast-path.test.ts
+++ b/src/entry.root-help-fast-path.test.ts
@@ -1,3 +1,4 @@
+// Tests root help fast-path handling before full CLI startup.
 import { describe, expect, it, vi } from "vitest";
 import { tryHandlePrecomputedCommandHelpFastPath, tryHandleRootHelpFastPath } from "./entry.js";
 
diff --git a/src/entry.version-fast-path.test.ts b/src/entry.version-fast-path.test.ts
index b4fd30407690..7f61ef46cf9f 100644
--- a/src/entry.version-fast-path.test.ts
+++ b/src/entry.version-fast-path.test.ts
@@ -1,3 +1,4 @@
+// Tests version fast-path output before the full entrypoint loads.
 import { describe, expect, it, vi } from "vitest";
 import { tryHandleRootVersionFastPath } from "./entry.version-fast-path.js";
 
diff --git a/src/global-state.ts b/src/global-state.ts
index 545783ef0a4a..565b3ffe7e6d 100644
--- a/src/global-state.ts
+++ b/src/global-state.ts
@@ -1,3 +1,4 @@
+// Stores process-global CLI flags shared by command modules.
 let globalVerbose = false;
 let globalYes = false;
 
diff --git a/src/index.ts b/src/index.ts
index 67ad624b5d7a..3d28505fb63b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Package executable entrypoint that forwards to the CLI bootstrap.
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { formatCliFailureLines } from "./cli/failure-output.js";
diff --git a/src/library.ts b/src/library.ts
index 515aec745561..ddd50dce8e93 100644
--- a/src/library.ts
+++ b/src/library.ts
@@ -1,3 +1,4 @@
+// Public library facade for consumers embedding OpenClaw reply runtime APIs.
 import type { getReplyFromConfig as getReplyFromConfigRuntime } from "./auto-reply/reply.runtime.js";
 import { applyTemplate } from "./auto-reply/templating.js";
 import { createDefaultDeps } from "./cli/deps.js";
diff --git a/src/logger.test.ts b/src/logger.test.ts
index e0b9454255cf..8e25c3f585b1 100644
--- a/src/logger.test.ts
+++ b/src/logger.test.ts
@@ -1,3 +1,4 @@
+// Tests root logger formatting and file output behavior.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/logging.ts b/src/logging.ts
index acadd0455c72..adf70e5086c0 100644
--- a/src/logging.ts
+++ b/src/logging.ts
@@ -1,3 +1,4 @@
+// Public logging facade for console logger settings and styling.
 import type { ConsoleLoggerSettings, ConsoleStyle } from "./logging/console.js";
 import {
   enableConsoleCapture,
diff --git a/src/music-generation/capabilities.test.ts b/src/music-generation/capabilities.test.ts
index ce84eb175c55..1777608a8c67 100644
--- a/src/music-generation/capabilities.test.ts
+++ b/src/music-generation/capabilities.test.ts
@@ -1,3 +1,4 @@
+// Tests music generation capability matching and normalization.
 import { describe, expect, it } from "vitest";
 import {
   listSupportedMusicGenerationModes,
diff --git a/src/music-generation/capabilities.ts b/src/music-generation/capabilities.ts
index 4d7b329ca876..38d2ceeaced4 100644
--- a/src/music-generation/capabilities.ts
+++ b/src/music-generation/capabilities.ts
@@ -1,3 +1,4 @@
+// Defines capability checks for music generation providers and models.
 import type {
   MusicGenerationEditCapabilities,
   MusicGenerationMode,
diff --git a/src/music-generation/live-test-helpers.ts b/src/music-generation/live-test-helpers.ts
index 2ed414fd674c..1582d295920b 100644
--- a/src/music-generation/live-test-helpers.ts
+++ b/src/music-generation/live-test-helpers.ts
@@ -1,3 +1,4 @@
+// Live-test helpers for music generation provider configuration.
 import type { OpenClawConfig } from "../config/types.js";
 import {
   parseLiveCsvFilter,
diff --git a/src/music-generation/model-ref.ts b/src/music-generation/model-ref.ts
index 0241ad22ac37..d65c222afe0e 100644
--- a/src/music-generation/model-ref.ts
+++ b/src/music-generation/model-ref.ts
@@ -1,3 +1,4 @@
+// Parses model references for music generation requests.
 import { parseGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js";
 
 /**
diff --git a/src/music-generation/normalization.ts b/src/music-generation/normalization.ts
index fc8766ef2387..af2a194bd629 100644
--- a/src/music-generation/normalization.ts
+++ b/src/music-generation/normalization.ts
@@ -1,3 +1,4 @@
+// Normalizes music generation requests into provider-ready payloads.
 import {
   hasMediaNormalizationEntry,
   normalizeDurationToClosestMax,
diff --git a/src/music-generation/provider-assets.ts b/src/music-generation/provider-assets.ts
index 3786b3e78c9d..509bc65a17c0 100644
--- a/src/music-generation/provider-assets.ts
+++ b/src/music-generation/provider-assets.ts
@@ -1,3 +1,4 @@
+// Validates and normalizes provider asset attachments for music generation.
 import { maxBytesForKind } from "@openclaw/media-core/constants";
 import { extensionForMime } from "@openclaw/media-core/mime";
 import { readResponseWithLimit } from "@openclaw/media-core/read-response-with-limit";
diff --git a/src/music-generation/provider-registry.ts b/src/music-generation/provider-registry.ts
index 6e224943bb75..ea50e4243b43 100644
--- a/src/music-generation/provider-registry.ts
+++ b/src/music-generation/provider-registry.ts
@@ -1,3 +1,4 @@
+// Registers music generation provider runtimes by normalized provider id.
 import { normalizeProviderId } from "../agents/model-selection.js";
 import type { OpenClawConfig } from "../config/types.js";
 import { isBlockedObjectKey } from "../infra/prototype-keys.js";
diff --git a/src/music-generation/runtime-types.ts b/src/music-generation/runtime-types.ts
index 3542f19f3ffc..b1d27d78337a 100644
--- a/src/music-generation/runtime-types.ts
+++ b/src/music-generation/runtime-types.ts
@@ -1,3 +1,4 @@
+// Runtime dependency contracts for music generation provider execution.
 import type { AuthProfileStore } from "../agents/auth-profiles/types.js";
 import type { FallbackAttempt } from "../agents/model-fallback.types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/music-generation/runtime.test.ts b/src/music-generation/runtime.test.ts
index 18595b1d0e92..4366d0fb1208 100644
--- a/src/music-generation/runtime.test.ts
+++ b/src/music-generation/runtime.test.ts
@@ -1,3 +1,4 @@
+// Tests music generation runtime dispatch and provider fallback behavior.
 import { beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.js";
 import {
diff --git a/src/music-generation/runtime.ts b/src/music-generation/runtime.ts
index 2e4c10203e25..b9533866ab7d 100644
--- a/src/music-generation/runtime.ts
+++ b/src/music-generation/runtime.ts
@@ -1,3 +1,4 @@
+// Runs music generation requests through provider runtimes and fallbacks.
 import type { FallbackAttempt } from "../agents/model-fallback.types.js";
 import { resolveAgentModelTimeoutMsValue } from "../config/model-input.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/music-generation/types.ts b/src/music-generation/types.ts
index ce8ff993283b..a59b9b7d8ee7 100644
--- a/src/music-generation/types.ts
+++ b/src/music-generation/types.ts
@@ -1,3 +1,4 @@
+// Shared music generation request, response, and provider type contracts.
 import type { MediaNormalizationEntry } from "../../packages/media-generation-core/src/normalization.js";
 import type { AuthProfileStore } from "../agents/auth-profiles/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/param-key.ts b/src/param-key.ts
index b3bc067a71bb..89cfb70d9d7c 100644
--- a/src/param-key.ts
+++ b/src/param-key.ts
@@ -1,3 +1,4 @@
+// Normalizes parameter keys while preserving user-visible whitespace where needed.
 import { lowercasePreservingWhitespace } from "@openclaw/normalization-core/string-coerce";
 
 function toSnakeCaseKey(key: string): string {
diff --git a/src/plugin-activation-boundary.test.ts b/src/plugin-activation-boundary.test.ts
index 8f371fb92359..55300e08830c 100644
--- a/src/plugin-activation-boundary.test.ts
+++ b/src/plugin-activation-boundary.test.ts
@@ -1,3 +1,4 @@
+// Tests plugin activation boundaries during root package startup.
 import { describe, expect, it, vi } from "vitest";
 import { normalizeModelRef } from "./agents/model-selection-normalize.js";
 import { isStaticallyChannelConfigured } from "./config/channel-configured-shared.js";
diff --git a/src/polls.test.ts b/src/polls.test.ts
index 8d19e132d510..2c1d0da039ea 100644
--- a/src/polls.test.ts
+++ b/src/polls.test.ts
@@ -1,3 +1,4 @@
+// Tests poll input contracts and option defaults.
 import { describe, expect, it } from "vitest";
 import { normalizePollDurationHours, normalizePollInput } from "./polls.js";
 
diff --git a/src/version.ts b/src/version.ts
index f2b9ea4ee8da..4287d121f648 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1,3 +1,4 @@
+// Resolves package version metadata for CLI and library callers.
 import { createRequire } from "node:module";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";