docs: document doctor config preflight checks

steipete · steipete · commit 688777ca79cc · 2026-06-04T11:59:11.000-04:00
diff --git a/src/commands/doctor-config-audit-scrub.ts b/src/commands/doctor-config-audit-scrub.ts
@@ -1,3 +1,4 @@
+/** Doctor repair for redacting historical config audit log argv records. */
 import fs from "node:fs/promises";
 import os from "node:os";
 import { note } from "../../packages/terminal-core/src/note.js";
@@ -9,6 +10,12 @@ function formatEntryCount(count: number): string {
   return `${count} ${count === 1 ? "entry" : "entries"}`;
 }
 
+/**
+ * Scrubs pre-redactor config audit records or previews the number of affected entries.
+ *
+ * The rewrite aborts if new records are appended while doctor is processing the JSONL file, so
+ * live gateways do not lose audit entries during cleanup.
+ */
 export async function maybeScrubConfigAuditLog(params: {
   shouldRepair: boolean;
   env?: NodeJS.ProcessEnv;
diff --git a/src/commands/doctor-config-flow.ts b/src/commands/doctor-config-flow.ts
@@ -1,3 +1,4 @@
+/** Main doctor config flow: preflight, migrations, previews, repairs, and final write decision. */
 import path from "node:path";
 import { note } from "../../packages/terminal-core/src/note.js";
 import { formatCliCommand } from "../cli/command-format.js";
@@ -103,6 +104,12 @@ async function refreshGatewayAuthStateAfterAuthProfileRepair(): Promise<void> {
   }
 }
 
+/**
+ * Loads config, runs doctor migrations/repairs, and returns the config write plan.
+ *
+ * This is the config-side orchestration boundary for doctor; it keeps preview notes, repair
+ * mutations, gateway auth refreshes, and final write confirmation in one ordered flow.
+ */
 export async function loadAndMaybeMigrateDoctorConfig(params: {
   options: DoctorOptions;
   confirm: (p: { message: string; initialValue: boolean }) => Promise<boolean>;
diff --git a/src/commands/doctor-config-preflight.ts b/src/commands/doctor-config-preflight.ts
@@ -1,3 +1,4 @@
+/** Config preflight for doctor: legacy config/state migration, recovery, and snapshot loading. */
 import fs from "node:fs/promises";
 import path from "node:path";
 import { note } from "../../packages/terminal-core/src/note.js";
@@ -92,6 +93,7 @@ function addDoctorLegacyIssues(
   return { ...snapshot, legacyIssues };
 }
 
+/** Returns true during updater-managed config rewrites where plugin validation may be stale. */
 export function shouldSkipPluginValidationForDoctorConfigPreflight(
   env: NodeJS.ProcessEnv = process.env,
 ): boolean {
@@ -107,6 +109,12 @@ function noteStateMigrationResult(result: { changes: string[]; warnings: string[
   }
 }
 
+/**
+ * Runs early doctor config checks before the main config repair flow.
+ *
+ * It may migrate legacy state/config paths, recover corrupt target config when requested, and
+ * returns the best-effort config snapshot used by later doctor checks.
+ */
 export async function runDoctorConfigPreflight(
   options: {
     migrateState?: boolean;
diff --git a/src/commands/doctor-cron.ts b/src/commands/doctor-cron.ts
@@ -1 +1,2 @@
+/** Re-exports cron doctor checks from the grouped doctor/cron implementation. */
 export * from "./doctor/cron/index.js";
diff --git a/src/commands/doctor-device-pairing.ts b/src/commands/doctor-device-pairing.ts
@@ -1,3 +1,4 @@
+/** Doctor diagnostics for pending, paired, and locally cached device auth state. */
 import path from "node:path";
 import { normalizeUniqueSingleOrTrimmedStringList } from "@openclaw/normalization-core/string-normalization";
 import { note } from "../../packages/terminal-core/src/note.js";
@@ -466,6 +467,7 @@ function collectLocalDeviceAuthIssues(snapshot: DoctorPairingSnapshot): string[]
       role,
     ]);
     const gatewayIssuedAtMs = pairedToken.rotatedAtMs ?? pairedToken.createdAtMs;
+    // Local device auth survives gateway restarts; compare timestamps to catch stale cached tokens.
     if (entry.updatedAtMs < gatewayIssuedAtMs) {
       lines.push(
         `- Local cached ${role} device token for ${deviceLabel} predates the gateway rotation. This is a stale device-token pattern and can fail with device token mismatch. Reconnect with shared gateway auth to refresh it, or rotate again with ${rotateCommand}.`,
@@ -488,6 +490,12 @@ function formatPairingStoreReadIssue(error: JsonFileReadError): string {
   return `- Device pairing store ${error.filePath} ${problem}. OpenClaw refused to treat it as empty to avoid overwriting approved pairings. Fix the JSON or file permissions, or move it aside and re-pair devices.`;
 }
 
+/**
+ * Emits device pairing repair guidance from live gateway state or local pairing files.
+ *
+ * Remote gateways only report through the gateway API; local gateways can fall back to on-disk
+ * pairing state when the gateway is down.
+ */
 export async function noteDevicePairingHealth(params: {
   cfg: OpenClawConfig;
   healthOk: boolean;
diff --git a/src/commands/doctor-disk-space.ts b/src/commands/doctor-disk-space.ts
@@ -1,9 +1,10 @@
+/** Doctor contribution for low disk space around the OpenClaw state directory. */
 import os from "node:os";
+import { note } from "../../packages/terminal-core/src/note.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveStateDir } from "../config/paths.js";
-import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { tryReadDiskSpace } from "../infra/disk-space.js";
-import { note } from "../../packages/terminal-core/src/note.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { shortenHomePath } from "../utils.js";
 
 // 100 MB — below this, config writes and session transcripts are likely to

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
	`1`	`+/** Re-exports cron doctor checks from the grouped doctor/cron implementation. */`
`1`	`2`	`export * from "./doctor/cron/index.js";`