docs: document root and music generation helpers

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";

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";

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";
 

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";
 

src/global-state.ts

@@ -1,3 +1,4 @@
+// Stores process-global CLI flags shared by command modules.
 let globalVerbose = false;
 let globalYes = false;
 

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";

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";

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";

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,

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,

src/music-generation/capabilities.ts

@@ -1,3 +1,4 @@
+// Defines capability checks for music generation providers and models.
 import type {
   MusicGenerationEditCapabilities,
   MusicGenerationMode,

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,

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";
 
 /**

src/music-generation/normalization.ts

@@ -1,3 +1,4 @@
+// Normalizes music generation requests into provider-ready payloads.
 import {
   hasMediaNormalizationEntry,
   normalizeDurationToClosestMax,

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";

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";

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";

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 {

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";

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";

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 {

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";

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";
 

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";