docs: document doctor plugin checks

steipete · steipete · commit 9d6e8b872ac3 · 2026-06-04T12:04:28.000-04:00
diff --git a/src/commands/doctor-lint.ts b/src/commands/doctor-lint.ts
@@ -1,3 +1,4 @@
+/** CLI entrypoint for non-mutating doctor lint health checks. */
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { readConfigFileSnapshot } from "../config/config.js";
 import { registerBundledHealthChecks } from "../flows/bundled-health-checks.js";
@@ -33,6 +34,12 @@ function detectMode(opts: DoctorLintCliOptions): "human" | "json" {
   return process.stdout.isTTY ? "human" : "json";
 }
 
+/**
+ * Runs registered doctor health checks in human or JSON mode and returns the lint exit code.
+ *
+ * Invalid config is reported before regular health checks because most checks need a parsed config
+ * and workspace root.
+ */
 export async function runDoctorLintCli(
   runtime: RuntimeEnv,
   opts: DoctorLintCliOptions,
diff --git a/src/commands/doctor-memory-search.ts b/src/commands/doctor-memory-search.ts
@@ -1,3 +1,4 @@
+/** Doctor diagnostics and repairs for memory search config, providers, and recall artifacts. */
 import fsSync from "node:fs";
 import {
   findNormalizedProviderValue,
@@ -248,6 +249,7 @@ function buildDreamingArtifactIssueNote(audit: DreamingArtifactsAuditSummary): s
   ].join("\n");
 }
 
+/** Emits memory recall and dreaming artifact warnings for the active memory backend. */
 export async function noteMemoryRecallHealth(cfg: OpenClawConfig): Promise<void> {
   try {
     const context = await resolveRuntimeMemoryAuditContext(cfg);
@@ -279,6 +281,7 @@ export async function noteMemoryRecallHealth(cfg: OpenClawConfig): Promise<void>
   }
 }
 
+/** Repairs fixable recall/dreaming artifacts after runtime repair confirmation. */
 export async function maybeRepairMemoryRecallHealth(params: {
   cfg: OpenClawConfig;
   prompter: DoctorPrompter;
@@ -390,10 +393,10 @@ function hasActiveAlternateMemoryPluginSlot(cfg: OpenClawConfig): boolean {
 }
 
 /**
- * Check whether memory search has a usable embedding provider.
- * Runs as part of `openclaw doctor` — config-only checks where possible;
- * may spawn a short-lived probe process when `memory.backend=qmd` to verify
- * the configured `qmd` binary is available.
+ * Checks whether memory search has a usable backend and embedding provider.
+ *
+ * Config-only checks are preferred, but QMD backends may spawn a short-lived probe process to
+ * verify the configured binary from the agent workspace.
  */
 export async function noteMemorySearchHealth(
   cfg: OpenClawConfig,
diff --git a/src/commands/doctor-platform-notes.ts b/src/commands/doctor-platform-notes.ts
@@ -1,3 +1,4 @@
+/** Platform-specific doctor notes for macOS gateway launchd state and startup tuning. */
 import { execFile } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
@@ -18,6 +19,7 @@ function resolveHomeDir(): string {
   return process.env.HOME ?? os.homedir();
 }
 
+/** Returns the macOS marker warning when LaunchAgent writes are locally disabled. */
 export function collectMacLaunchAgentOverrideWarning(deps?: {
   platform?: NodeJS.Platform;
   homeDir?: string;
@@ -42,13 +44,15 @@ export function collectMacLaunchAgentOverrideWarning(deps?: {
   ].join("\n");
 }
 
+/** Emits the macOS LaunchAgent override warning when present. */
 export async function noteMacLaunchAgentOverrides() {
   const warning = collectMacLaunchAgentOverrideWarning();
   if (warning) {
     note(warning, "Gateway (macOS)");
   }
 }
 
+/** Returns a warning for stale OpenClaw updater launchd jobs left after interrupted updates. */
 export async function collectMacStaleOpenClawUpdateLaunchdJobsWarning(deps?: {
   platform?: NodeJS.Platform;
   findJobs?: typeof findStaleOpenClawUpdateLaunchdJobs;
@@ -80,6 +84,7 @@ export async function collectMacStaleOpenClawUpdateLaunchdJobsWarning(deps?: {
   ].join("\n");
 }
 
+/** Emits stale updater launchd job notes using the gateway service environment when available. */
 export async function noteMacStaleOpenClawUpdateLaunchdJobs(deps?: {
   platform?: NodeJS.Platform;
   findJobs?: typeof findStaleOpenClawUpdateLaunchdJobs;
@@ -122,6 +127,7 @@ function hasConfigGatewayCreds(cfg: OpenClawConfig): boolean {
   );
 }
 
+/** Returns a warning for host-wide launchctl gateway auth env overrides. */
 export async function collectMacLaunchctlGatewayEnvOverrideWarning(
   cfg: OpenClawConfig,
   deps?: {
@@ -171,6 +177,7 @@ export async function collectMacLaunchctlGatewayEnvOverrideWarning(
     .join("\n");
 }
 
+/** Emits macOS launchctl gateway auth override warnings. */
 export async function noteMacLaunchctlGatewayEnvOverrides(
   cfg: OpenClawConfig,
   deps?: {
@@ -200,6 +207,7 @@ async function resolveGatewayServiceEnvForPlatformNotes(deps?: {
     : baseEnv;
 }
 
+/** Collects all macOS gateway platform warnings without emitting notes. */
 export async function collectMacGatewayPlatformWarnings(
   cfg: OpenClawConfig,
   deps?: {
@@ -246,6 +254,7 @@ function isTmpCompileCachePath(cachePath: string): boolean {
   );
 }
 
+/** Emits startup tuning hints for low-power Linux hosts when env settings are suboptimal. */
 export function noteStartupOptimizationHints(
   env: NodeJS.ProcessEnv = process.env,
   deps?: {
diff --git a/src/commands/doctor-plugin-manifests.ts b/src/commands/doctor-plugin-manifests.ts
@@ -1,3 +1,4 @@
+/** Doctor migration for legacy plugin manifest capability keys into contracts.* fields. */
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -90,6 +91,7 @@ function buildLegacyManifestContractMigration(params: {
   };
 }
 
+/** Collects manifest rewrites needed to move legacy top-level capability keys under contracts. */
 export function collectLegacyPluginManifestContractMigrations(params?: {
   config?: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
@@ -150,6 +152,7 @@ export function collectLegacyPluginManifestContractMigrations(params?: {
   return migrations.toSorted((left, right) => left.manifestPath.localeCompare(right.manifestPath));
 }
 
+/** Prompts and rewrites legacy plugin manifest contract fields when doctor repair is enabled. */
 export async function maybeRepairLegacyPluginManifestContracts(params: {
   config?: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
diff --git a/src/commands/doctor-plugin-registry.ts b/src/commands/doctor-plugin-registry.ts
@@ -1,3 +1,4 @@
+/** Doctor repairs for stale plugin registry entries, managed npm shadows, and peer links. */
 import fs from "node:fs";
 import path from "node:path";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
@@ -246,6 +247,7 @@ function removeManagedNpmPackageLockDependency(params: {
   }
 }
 
+/** Removes managed npm packages that shadow current bundled plugins when repair is enabled. */
 export function maybeRepairStaleManagedNpmBundledPlugins(
   params: PluginRegistryDoctorRepairParams,
 ): boolean {
@@ -285,6 +287,7 @@ export function maybeRepairStaleManagedNpmBundledPlugins(
   return true;
 }
 
+/** Removes local install records that shadow current bundled plugin sources. */
 export async function maybeRepairStaleLocalBundledPluginInstallRecords(
   params: PluginRegistryDoctorRepairParams,
 ): Promise<string[]> {
@@ -315,6 +318,7 @@ export async function maybeRepairStaleLocalBundledPluginInstallRecords(
   return stale.map((record) => record.pluginId);
 }
 
+/** Relinks managed npm plugin packages to the current OpenClaw host packages. */
 export async function maybeRepairManagedNpmOpenClawPeerLinks(
   params: PluginRegistryDoctorRepairParams,
 ): Promise<boolean> {
@@ -382,6 +386,12 @@ async function loadInstallRecordsWithoutPluginIds(
   return records;
 }
 
+/**
+ * Runs plugin registry doctor repairs and refreshes the persisted plugin index when needed.
+ *
+ * Stale bundled shadows are removed before registry migration so the rebuilt index resolves the
+ * current bundled source instead of an obsolete managed/local install record.
+ */
 export async function maybeRepairPluginRegistryState(
   params: PluginRegistryDoctorRepairParams,
 ): Promise<OpenClawConfig> {
diff --git a/src/commands/doctor-post-upgrade.ts b/src/commands/doctor-post-upgrade.ts
@@ -1,3 +1,4 @@
+/** Post-upgrade validation probes for persisted plugin index and package extension entries. */
 import crypto from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
@@ -147,6 +148,7 @@ async function sha256OfFile(absPath: string): Promise<string | null> {
   }
 }
 
+/** Runs post-upgrade plugin probes and returns structured findings for the caller to render. */
 export async function runPostUpgradeProbes(params: {
   installsPath?: string;
   stateDir?: string;

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Post-upgrade validation probes for persisted plugin index and package extension entries. */`
`1`	`2`	`import crypto from "node:crypto";`
`2`	`3`	`import fsSync from "node:fs";`
`3`	`4`	`import fs from "node:fs/promises";`
`@@ -147,6 +148,7 @@ async function sha256OfFile(absPath: string): Promise<string \| null> {`
`147`	`148`	`}`
`148`	`149`	`}`
`149`	`150`
	`151`	`+/** Runs post-upgrade plugin probes and returns structured findings for the caller to render. */`
`150`	`152`	`export async function runPostUpgradeProbes(params: {`
`151`	`153`	`installsPath?: string;`
`152`	`154`	`stateDir?: string;`