docs: document onboarding helper comments

src/commands/onboard-channels.ts

@@ -1,3 +1,4 @@
+/** Re-export seam for channel onboarding flow helpers. */
 export {
   createChannelOnboardingPostWriteHook,
   createChannelOnboardingPostWriteHookCollector,

src/commands/onboard-config.ts

@@ -1,11 +1,15 @@
+/** Shared config mutations used by interactive and non-interactive onboarding. */
 import { setConfigValueAtPath } from "../config/config-paths.js";
 import type { DmScope } from "../config/types.base.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ToolProfileId } from "../config/types.tools.js";
 
+/** Default DM scoping selected during local onboarding. */
 export const ONBOARDING_DEFAULT_DM_SCOPE: DmScope = "per-channel-peer";
+/** Default tool profile selected during local onboarding. */
 export const ONBOARDING_DEFAULT_TOOLS_PROFILE: ToolProfileId = "coding";
 
+/** Applies local gateway/workspace defaults without overwriting explicit user defaults. */
 export function applyLocalSetupWorkspaceConfig(
   baseConfig: OpenClawConfig,
   workspaceDir: string,
@@ -34,6 +38,7 @@ export function applyLocalSetupWorkspaceConfig(
   };
 }
 
+/** Marks default agents to skip bootstrap file creation. */
 export function applySkipBootstrapConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = structuredClone(cfg);
   setConfigValueAtPath(

src/commands/onboard-core-auth-flags.ts

@@ -1,3 +1,4 @@
+/** Core auth flag registry for onboarding CLI help and routing. */
 import type { AuthChoice, OnboardOptions } from "./onboard-types.js";
 
 type OnboardCoreAuthOptionKey = Extract<keyof OnboardOptions, string>;
@@ -10,4 +11,5 @@ type OnboardCoreAuthFlag = {
   description: string;
 };
 
+/** Auth-related CLI flags owned by core onboarding rather than provider plugins. */
 export const CORE_ONBOARD_AUTH_FLAGS: ReadonlyArray<OnboardCoreAuthFlag> = [];

src/commands/onboard-helpers.ts

@@ -1,3 +1,4 @@
+/** Shared helpers for onboarding, reset, gateway checks, and wizard output. */
 import fs from "node:fs/promises";
 import path from "node:path";
 import { inspect } from "node:util";
@@ -42,6 +43,7 @@ export { detectBinary };
 export { detectBrowserOpenSupport, openUrl, resolveBrowserOpenCommand };
 export { resolveControlUiLinks };
 
+/** Handles Clack cancellation by exiting through the runtime. */
 export function guardCancel<T>(value: T | symbol, runtime: RuntimeEnv): T {
   if (isCancel(value)) {
     cancel(stylePromptTitle("Setup cancelled.") ?? "Setup cancelled.");
@@ -51,6 +53,7 @@ export function guardCancel<T>(value: T | symbol, runtime: RuntimeEnv): T {
   return value;
 }
 
+/** Summarizes existing config values before onboarding overwrites or reuses them. */
 export function summarizeExistingConfig(config: OpenClawConfig): string {
   const rows: string[] = [];
   const defaults = config.agents?.defaults;
@@ -127,6 +130,7 @@ function formatGatewayBind(value: string | undefined): string | undefined {
   }
 }
 
+/** Normalizes gateway token prompts while rejecting JS stringification sentinels. */
 export function normalizeGatewayTokenInput(value: unknown): string {
   if (typeof value !== "string") {
     return "";
@@ -140,6 +144,7 @@ export function normalizeGatewayTokenInput(value: unknown): string {
   return trimmed;
 }
 
+/** Validates gateway password prompt input. */
 export function validateGatewayPasswordInput(value: unknown): string | undefined {
   if (typeof value !== "string") {
     return "Required";
@@ -154,6 +159,7 @@ export function validateGatewayPasswordInput(value: unknown): string | undefined
   return undefined;
 }
 
+/** Prints the onboarding banner. */
 export function printWizardHeader(runtime: RuntimeEnv) {
   const bannerWidth = 54;
   const icon = decorativeEmoji("🦞");
@@ -172,6 +178,7 @@ export function printWizardHeader(runtime: RuntimeEnv) {
   runtime.log(header);
 }
 
+/** Records wizard provenance metadata on config writes. */
 export function applyWizardMetadata(
   cfg: OpenClawConfig,
   params: { command: string; mode: OnboardMode },
@@ -191,6 +198,7 @@ export function applyWizardMetadata(
   };
 }
 
+/** Formats the no-GUI SSH tunnel hint for opening the Control UI remotely. */
 export function formatControlUiSshHint(params: {
   port: number;
   basePath?: string;
@@ -226,6 +234,7 @@ function resolveSshTargetHint(): string {
   return `${user}@${host}`;
 }
 
+/** Ensures workspace bootstrap files and session transcript directories exist. */
 export async function ensureWorkspaceAndSessions(
   workspaceDir: string,
   runtime: RuntimeEnv,
@@ -246,6 +255,7 @@ export async function ensureWorkspaceAndSessions(
   runtime.log(`Sessions OK: ${shortenHomePath(sessionsDir)}`);
 }
 
+/** Returns package manager choices offered by onboarding. */
 export function resolveNodeManagerOptions(): Array<{
   value: NodeManagerChoice;
   label: string;
@@ -257,6 +267,7 @@ export function resolveNodeManagerOptions(): Array<{
   ];
 }
 
+/** Moves a path to Trash when it exists, logging a manual-delete fallback on failure. */
 export async function moveToTrash(pathname: string, runtime: RuntimeEnv): Promise<void> {
   if (!pathname) {
     return;
@@ -297,6 +308,7 @@ async function resolveMoveToTrashAllowedRoots(targetPath: string): Promise<strin
   return uniqueStrings(allowedRoots);
 }
 
+/** Deletes onboarding-managed state according to the selected reset scope. */
 export async function handleReset(scope: ResetScope, workspaceDir: string, runtime: RuntimeEnv) {
   await moveToTrash(resolveConfigPath(), runtime);
   if (scope === "config") {
@@ -316,6 +328,7 @@ export async function handleReset(scope: ResetScope, workspaceDir: string, runti
   }
 }
 
+/** Runs a single lightweight gateway probe for onboarding readiness checks. */
 export async function probeGatewayReachable(params: {
   url: string;
   token?: string;
@@ -340,6 +353,7 @@ export async function probeGatewayReachable(params: {
   }
 }
 
+/** Polls gateway reachability until success or deadline. */
 export async function waitForGatewayReachable(params: {
   url: string;
   token?: string;
@@ -395,4 +409,5 @@ function summarizeError(err: unknown): string {
   return line.length > 120 ? `${line.slice(0, 119)}…` : line;
 }
 
+/** Default workspace path shown by onboarding prompts. */
 export const DEFAULT_WORKSPACE = DEFAULT_AGENT_WORKSPACE_DIR;

src/commands/onboard-hooks.ts

@@ -1,3 +1,4 @@
+/** Interactive onboarding step for enabling workspace hooks. */
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { formatCliCommand } from "../cli/command-format.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -6,6 +7,7 @@ import type { RuntimeEnv } from "../runtime.js";
 import { t } from "../wizard/i18n/index.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 
+/** Prompts for loadable internal hooks and writes selected hook entries. */
 export async function setupInternalHooks(
   cfg: OpenClawConfig,
   _runtime: RuntimeEnv,
@@ -21,7 +23,8 @@ export async function setupInternalHooks(
     t("wizard.hooks.introTitle"),
   );
 
-  // Discover available hooks using the hook discovery system
+  // Discover hooks through the same status path used by hook commands so setup
+  // only offers entries that would be loadable after onboarding finishes.
   const workspaceDir = resolveAgentWorkspaceDir(cfg, resolveDefaultAgentId(cfg));
   const report = buildWorkspaceHookStatus(workspaceDir, { config: cfg });
 
@@ -50,7 +53,7 @@ export async function setupInternalHooks(
     return cfg;
   }
 
-  // Enable selected hooks using the new entries config format
+  // Use entries format so per-hook enablement survives future global defaults.
   const entries = { ...cfg.hooks?.internal?.entries };
   for (const name of selected) {
     entries[name] = { enabled: true };