docs: document flow helpers

src/flows/bundled-health-checks.test.ts

@@ -1,3 +1,4 @@
+// Bundled health check tests cover built-in doctor checks and repair advice.
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";

src/flows/bundled-health-checks.ts

@@ -1,3 +1,4 @@
+// Bundled health checks define built-in doctor checks for runtime readiness.
 import { asOptionalObjectRecord as readRecord } from "@openclaw/normalization-core/record-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { normalizePluginsConfig } from "../plugins/config-state.js";

src/flows/channel-setup.prompts.test.ts

@@ -1,3 +1,4 @@
+// Channel setup prompt tests cover prompt choices and validation.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { ChannelSetupDmPolicy } from "../commands/channel-setup/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/flows/channel-setup.prompts.ts

@@ -1,3 +1,4 @@
+// Channel setup prompt helpers build interactive prompts for channel setup.
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
 import { resolveChannelDefaultAccountId } from "../channels/plugins/helpers.js";
 import { getChannelSetupPlugin } from "../channels/plugins/setup-registry.js";

src/flows/channel-setup.status.test.ts

@@ -1,3 +1,4 @@
+// Channel setup status tests cover status text and docs link rendering.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   makeCatalogEntry,

src/flows/channel-setup.status.ts

@@ -1,3 +1,4 @@
+// Channel setup status helpers format channel setup progress and docs links.
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
 import { sanitizeTerminalText } from "../../packages/terminal-core/src/safe-text.js";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";

src/flows/channel-setup.test-helpers.ts

@@ -1,3 +1,4 @@
+// Channel setup test helpers build channel metadata and prompt fixtures.
 type ChannelMeta = import("../channels/plugins/types.core.js").ChannelMeta;
 type ChannelPluginCatalogEntry = import("../channels/plugins/catalog.js").ChannelPluginCatalogEntry;
 type ResolveChannelSetupEntries =

src/flows/channel-setup.test.ts

@@ -1,3 +1,4 @@
+// Channel setup tests cover setup flow prompts and config output.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   makeCatalogEntry,

src/flows/channel-setup.ts

@@ -1,3 +1,4 @@
+// Channel setup flow configures channels, auth, and workspace bindings.
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { getBundledChannelSetupPlugin } from "../channels/plugins/bundled.js";
 import { resolveChannelDefaultAccountId } from "../channels/plugins/helpers.js";

src/flows/doctor-core-browser-residue-check.test.ts

@@ -1,3 +1,4 @@
+// Browser residue doctor tests cover detection of stale browser state.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { CORE_HEALTH_CHECKS } from "./doctor-core-checks.js";

src/flows/doctor-core-checks.e2e.test.ts

@@ -1,3 +1,4 @@
+// Doctor core check E2E tests cover doctor checks in filesystem-backed scenarios.
 import { promises as fs } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";

src/flows/doctor-core-checks.runtime-errors.test.ts

@@ -1,3 +1,4 @@
+// Doctor runtime error tests cover error handling in core runtime checks.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { AnyAgentTool } from "../agents/tools/common.js";
 import { setPluginToolMeta } from "../plugins/tools.js";

src/flows/doctor-core-checks.runtime.test.ts

@@ -1,3 +1,4 @@
+// Doctor runtime check tests cover runtime-backed doctor checks.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { AnyAgentTool } from "../agents/tools/common.js";
 import { setPluginToolMeta } from "../plugins/tools.js";

src/flows/doctor-core-checks.runtime.ts

@@ -1,3 +1,4 @@
+// Doctor runtime checks inspect tool names, browser residue, and runtime state.
 import { TOOL_NAME_SEPARATOR } from "../agents/agent-bundle-mcp-names.js";
 import {
   type McpToolCatalogDiagnostic,

src/flows/doctor-core-checks.test.ts

@@ -1,3 +1,4 @@
+// Doctor core checks tests cover core doctor checks and repair hints.
 import { promises as fs } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";

src/flows/doctor-core-checks.ts

@@ -1,3 +1,4 @@
+// Doctor core checks collect environment, config, and runtime readiness diagnostics.
 import path from "node:path";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import {

src/flows/doctor-health-contributions.test.ts

@@ -1,3 +1,4 @@
+// Doctor health contribution tests cover plugin-provided health checks.
 import fs from "node:fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { DoctorPrompter } from "../commands/doctor-prompter.js";

src/flows/doctor-health-contributions.ts

@@ -1,3 +1,4 @@
+// Doctor health contribution helpers collect health checks from plugin manifests.
 import fs from "node:fs";
 import type { probeGatewayMemoryStatus } from "../commands/doctor-gateway-health.js";
 import type { DoctorOptions, DoctorPrompter } from "../commands/doctor-prompter.js";

src/flows/doctor-health-conversion-plan.test.ts

@@ -1,3 +1,4 @@
+// Doctor health conversion tests cover converting health checks to repair plans.
 import { describe, expect, it } from "vitest";
 import { CORE_HEALTH_CHECKS } from "./doctor-core-checks.js";
 import { resolveDoctorHealthContributions } from "./doctor-health-contributions.js";

src/flows/doctor-health.ts

@@ -1,3 +1,4 @@
+// Doctor health flow renders interactive health check output.
 import { intro as clackIntro, outro as clackOutro } from "@clack/prompts";
 import { stylePromptTitle } from "../../packages/terminal-core/src/prompt-style.js";
 import type { DoctorOptions } from "../commands/doctor-prompter.js";

src/flows/doctor-lint-flow.test.ts

@@ -1,3 +1,4 @@
+// Doctor lint flow tests cover lint diagnostics surfaced by doctor.
 import { describe, expect, it } from "vitest";
 import { exitCodeFromFindings, runDoctorLintChecks } from "./doctor-lint-flow.js";
 import { normalizeHealthCheck } from "./health-check-adapter.js";

src/flows/doctor-lint-flow.ts

@@ -1,3 +1,4 @@
+// Doctor lint flow runs lint-like doctor checks and formats findings.
 import { scrubDoctorErrorMessage } from "./doctor-error-message.js";
 import { listHealthChecks } from "./health-check-registry.js";
 import {

src/flows/doctor-repair-flow.test.ts

@@ -1,3 +1,4 @@
+// Doctor repair flow tests cover repair plan output and repair execution.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { runDoctorHealthRepairs } from "./doctor-repair-flow.js";

src/flows/doctor-repair-flow.ts

@@ -1,3 +1,4 @@
+// Doctor repair flow builds and runs repair actions for doctor findings.
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { scrubDoctorErrorMessage } from "./doctor-error-message.js";

src/flows/doctor-startup-channel-maintenance.test.ts

@@ -1,3 +1,4 @@
+// Doctor startup maintenance tests cover channel startup maintenance checks.
 import { describe, expect, it } from "vitest";
 import { maybeRunDoctorStartupChannelMaintenance } from "./doctor-startup-channel-maintenance.js";
 

src/flows/doctor-startup-channel-maintenance.ts

@@ -1,3 +1,4 @@
+// Doctor startup channel maintenance runs channel plugin startup repairs.
 import { runChannelPluginStartupMaintenance } from "../channels/plugins/lifecycle-startup.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 

src/flows/doctor-tool-result-cap-advice.test.ts

@@ -1,3 +1,4 @@
+// Tool result cap advice tests cover doctor guidance for capped tool output.
 import { describe, expect, it } from "vitest";
 import { buildToolResultCapDoctorAdvice } from "./doctor-tool-result-cap-advice.js";
 

src/flows/doctor-tool-result-cap-advice.ts

@@ -1,3 +1,4 @@
+// Tool result cap advice helpers format doctor guidance for capped outputs.
 import {
   calculateMaxToolResultCharsWithCap,
   resolveAutoLiveToolResultMaxChars,

src/flows/health-check-adapter.ts

@@ -1,3 +1,4 @@
+// Health check adapter converts plugin health checks into doctor check records.
 import type {
   HealthCheckInput,
   HealthCheckRunResult,

src/flows/health-check-registry.ts

@@ -1,3 +1,4 @@
+// Health check registry stores doctor health checks by identifier.
 import type { HealthCheck } from "./health-checks.js";
 
 // Process-local registry populated by core and plugin doctor checks.

src/flows/health-check-runner-types.ts

@@ -1,3 +1,4 @@
+// Health check runner types describe execution state for doctor health checks.
 import type {
   HealthCheck,
   HealthCheckContext,

src/flows/health-checks.ts

@@ -1,3 +1,4 @@
+// Health check types define doctor checks, results, and repair metadata.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { RuntimeEnv } from "../runtime.js";
 

src/flows/model-picker.provider-catalog.test.ts

@@ -1,3 +1,4 @@
+// Model picker provider catalog tests cover catalog-driven provider options.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ModelDefinitionConfig } from "../config/types.models.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/flows/model-picker.provider-catalog.ts

@@ -1,3 +1,4 @@
+// Model picker provider catalog helpers build provider choices from catalog data.
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { resolveDefaultAgentDir } from "../agents/agent-scope.js";
 import { ensureAuthProfileStoreWithoutExternalProfiles } from "../agents/auth-profiles.js";

src/flows/model-picker.ts

@@ -1,3 +1,4 @@
+// Model picker flow lets users select provider models for config defaults.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { resolveDefaultAgentDir } from "../agents/agent-scope.js";

src/flows/provider-flow.runtime.ts

@@ -1,3 +1,4 @@
+// Provider flow runtime helpers load provider setup behavior behind runtime imports.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import * as providerWizard from "../plugins/provider-wizard.js";

src/flows/provider-flow.test.ts

@@ -1,3 +1,4 @@
+// Provider flow tests cover provider setup prompts and config mutations.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 type ResolveProviderInstallCatalogEntries =

src/flows/provider-flow.ts

@@ -1,3 +1,4 @@
+// Provider setup flow configures provider credentials, models, and defaults.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { normalizePluginsConfig, resolveEffectiveEnableState } from "../plugins/config-state.js";
 import * as providerAuthChoices from "../plugins/provider-auth-choices.js";

src/flows/search-setup.test.ts

@@ -1,3 +1,4 @@
+// Search setup tests cover search provider setup and config changes.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createWizardPrompter } from "../../test/helpers/wizard-prompter.js";
 import { createNonExitingRuntime } from "../runtime.js";

src/flows/search-setup.ts

@@ -1,3 +1,4 @@
+// Search setup flow configures web search providers and defaults.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { resolveDefaultAgentDir } from "../agents/agent-scope-config.js";
 import { hasAuthProfileForProvider } from "../agents/tools/model-config.helpers.js";