From 81eee470451d6039f899e52397111eea19926d80 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 19:44:23 -0400
Subject: [PATCH] docs: document doctor command tests

---
 src/commands/doctor/channel-capabilities.test.ts                 | 1 +
 .../cron/dreaming-payload-migration.constants-drift.test.ts      | 1 +
 src/commands/doctor/cron/dreaming-payload-migration.test.ts      | 1 +
 src/commands/doctor/cron/index.test.ts                           | 1 +
 src/commands/doctor/cron/legacy-delivery.test.ts                 | 1 +
 src/commands/doctor/cron/store-migration.test.ts                 | 1 +
 src/commands/doctor/emit-notes.test.ts                           | 1 +
 src/commands/doctor/finalize-config-flow.test.ts                 | 1 +
 src/commands/doctor/repair-sequencing.test.ts                    | 1 +
 src/commands/doctor/shared/active-tool-schema-warnings.test.ts   | 1 +
 src/commands/doctor/shared/allowfrom-fallback-migration.test.ts  | 1 +
 src/commands/doctor/shared/allowlist-policy-repair.test.ts       | 1 +
 src/commands/doctor/shared/allowlist.test.ts                     | 1 +
 src/commands/doctor/shared/bundled-plugin-load-paths.test.ts     | 1 +
 src/commands/doctor/shared/channel-doctor.test.ts                | 1 +
 src/commands/doctor/shared/channel-legacy-config-migrate.test.ts | 1 +
 src/commands/doctor/shared/channel-plugin-blockers.test.ts       | 1 +
 src/commands/doctor/shared/codex-native-assets.test.ts           | 1 +
 src/commands/doctor/shared/codex-route-warnings.test.ts          | 1 +
 src/commands/doctor/shared/config-flow-steps.test.ts             | 1 +
 src/commands/doctor/shared/config-mutation-state.test.ts         | 1 +
 src/commands/doctor/shared/context-engine-host-compat.test.ts    | 1 +
 src/commands/doctor/shared/deprecation-compat.test.ts            | 1 +
 src/commands/doctor/shared/empty-allowlist-policy.test.ts        | 1 +
 src/commands/doctor/shared/empty-allowlist-scan.test.ts          | 1 +
 src/commands/doctor/shared/exec-safe-bins.test.ts                | 1 +
 src/commands/doctor/shared/hooks-token-reuse-repair.test.ts      | 1 +
 src/commands/doctor/shared/invalid-plugin-config.test.ts         | 1 +
 .../doctor/shared/legacy-config-migrate.provider-shapes.test.ts  | 1 +
 src/commands/doctor/shared/legacy-config-migrate.test.ts         | 1 +
 .../doctor/shared/legacy-config-migrate.validation.test.ts       | 1 +
 .../shared/legacy-config-migrations.runtime.models.test.ts       | 1 +
 src/commands/doctor/shared/legacy-config-write-ownership.test.ts | 1 +
 src/commands/doctor/shared/legacy-models-add-metadata.test.ts    | 1 +
 src/commands/doctor/shared/legacy-oauth-sidecar.test.ts          | 1 +
 src/commands/doctor/shared/legacy-tools-by-sender.test.ts        | 1 +
 src/commands/doctor/shared/legacy-web-fetch-migrate.test.ts      | 1 +
 src/commands/doctor/shared/legacy-web-search-migrate.test.ts     | 1 +
 src/commands/doctor/shared/legacy-x-search-migrate.test.ts       | 1 +
 .../doctor/shared/missing-configured-plugin-install.test.ts      | 1 +
 src/commands/doctor/shared/open-policy-allowfrom.test.ts         | 1 +
 src/commands/doctor/shared/plugin-dependency-cleanup.test.ts     | 1 +
 src/commands/doctor/shared/plugin-registry-migration.test.ts     | 1 +
 .../doctor/shared/plugin-tool-allowlist-warnings.test.ts         | 1 +
 src/commands/doctor/shared/preview-warnings.test.ts              | 1 +
 .../doctor/shared/release-configured-plugin-installs.test.ts     | 1 +
 src/commands/doctor/shared/stale-oauth-profile-shadows.test.ts   | 1 +
 src/commands/doctor/shared/stale-plugin-config.test.ts           | 1 +
 src/commands/doctor/shared/stale-subagent-allowlist.test.ts      | 1 +
 src/commands/doctor/shared/update-phase.test.ts                  | 1 +
 50 files changed, 50 insertions(+)

diff --git a/src/commands/doctor/channel-capabilities.test.ts b/src/commands/doctor/channel-capabilities.test.ts
index 7015d33efc84..091d7c266e2a 100644
--- a/src/commands/doctor/channel-capabilities.test.ts
+++ b/src/commands/doctor/channel-capabilities.test.ts
@@ -1,3 +1,4 @@
+// Doctor channel capability tests cover channel capability inspection and diagnostics.
 import { describe, expect, it } from "vitest";
 import { getDoctorChannelCapabilities } from "./channel-capabilities.js";
 
diff --git a/src/commands/doctor/cron/dreaming-payload-migration.constants-drift.test.ts b/src/commands/doctor/cron/dreaming-payload-migration.constants-drift.test.ts
index 6f2392f97b75..b2bda80900c8 100644
--- a/src/commands/doctor/cron/dreaming-payload-migration.constants-drift.test.ts
+++ b/src/commands/doctor/cron/dreaming-payload-migration.constants-drift.test.ts
@@ -1,3 +1,4 @@
+// Dreaming payload constant-drift tests cover cron doctor migration fixture drift.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/commands/doctor/cron/dreaming-payload-migration.test.ts b/src/commands/doctor/cron/dreaming-payload-migration.test.ts
index 444d014c6085..4e6ecad4c443 100644
--- a/src/commands/doctor/cron/dreaming-payload-migration.test.ts
+++ b/src/commands/doctor/cron/dreaming-payload-migration.test.ts
@@ -1,3 +1,4 @@
+// Dreaming payload migration tests cover cron doctor repair of old dreaming payloads.
 import { describe, expect, it } from "vitest";
 import {
   countStaleDreamingJobs,
diff --git a/src/commands/doctor/cron/index.test.ts b/src/commands/doctor/cron/index.test.ts
index 7087e7d0b961..cbf740a954b8 100644
--- a/src/commands/doctor/cron/index.test.ts
+++ b/src/commands/doctor/cron/index.test.ts
@@ -1,3 +1,4 @@
+// Doctor cron index tests cover cron doctor checks and repair entrypoints.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor/cron/legacy-delivery.test.ts b/src/commands/doctor/cron/legacy-delivery.test.ts
index 8cdba4de5fa6..00e8fe74eb13 100644
--- a/src/commands/doctor/cron/legacy-delivery.test.ts
+++ b/src/commands/doctor/cron/legacy-delivery.test.ts
@@ -1,3 +1,4 @@
+// Legacy delivery tests cover cron doctor repair of old delivery state.
 import { describe, expect, it } from "vitest";
 import {
   buildDeliveryFromLegacyPayload,
diff --git a/src/commands/doctor/cron/store-migration.test.ts b/src/commands/doctor/cron/store-migration.test.ts
index 97502a4d1167..9af09819b3f2 100644
--- a/src/commands/doctor/cron/store-migration.test.ts
+++ b/src/commands/doctor/cron/store-migration.test.ts
@@ -1,3 +1,4 @@
+// Cron store migration tests cover doctor migration of persisted cron stores.
 import { describe, expect, it } from "vitest";
 import { DEFAULT_TOP_OF_HOUR_STAGGER_MS } from "../../../cron/stagger.js";
 import { normalizeStoredCronJobs } from "./store-migration.js";
diff --git a/src/commands/doctor/emit-notes.test.ts b/src/commands/doctor/emit-notes.test.ts
index 49dd18228f3b..9fdc291f5e30 100644
--- a/src/commands/doctor/emit-notes.test.ts
+++ b/src/commands/doctor/emit-notes.test.ts
@@ -1,3 +1,4 @@
+// Doctor emit-note tests cover terminal note output and doctor issue formatting.
 import { describe, expect, it, vi } from "vitest";
 import { emitDoctorNotes } from "./emit-notes.js";
 
diff --git a/src/commands/doctor/finalize-config-flow.test.ts b/src/commands/doctor/finalize-config-flow.test.ts
index 3320d3fa0bf1..8b32d50154ec 100644
--- a/src/commands/doctor/finalize-config-flow.test.ts
+++ b/src/commands/doctor/finalize-config-flow.test.ts
@@ -1,3 +1,4 @@
+// Doctor finalize config-flow tests cover final repair summaries and config mutation completion.
 import { describe, expect, it, vi } from "vitest";
 import { finalizeDoctorConfigFlow } from "./finalize-config-flow.js";
 
diff --git a/src/commands/doctor/repair-sequencing.test.ts b/src/commands/doctor/repair-sequencing.test.ts
index a7bce34fd296..0e02dafead66 100644
--- a/src/commands/doctor/repair-sequencing.test.ts
+++ b/src/commands/doctor/repair-sequencing.test.ts
@@ -1,3 +1,4 @@
+// Doctor repair sequencing tests cover ordered repair execution and dependency handling.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import { runDoctorRepairSequence } from "./repair-sequencing.js";
diff --git a/src/commands/doctor/shared/active-tool-schema-warnings.test.ts b/src/commands/doctor/shared/active-tool-schema-warnings.test.ts
index 479596411d96..4897b5df668c 100644
--- a/src/commands/doctor/shared/active-tool-schema-warnings.test.ts
+++ b/src/commands/doctor/shared/active-tool-schema-warnings.test.ts
@@ -1,3 +1,4 @@
+// Active tool schema warning tests cover doctor warnings for active tool schema drift.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { createOpenClawCodingTools } from "../../../agents/agent-tools.js";
 import type { AnyAgentTool } from "../../../agents/tools/common.js";
diff --git a/src/commands/doctor/shared/allowfrom-fallback-migration.test.ts b/src/commands/doctor/shared/allowfrom-fallback-migration.test.ts
index 016a785b9d1a..a6d2b0a908d9 100644
--- a/src/commands/doctor/shared/allowfrom-fallback-migration.test.ts
+++ b/src/commands/doctor/shared/allowfrom-fallback-migration.test.ts
@@ -1,3 +1,4 @@
+// Allow-from fallback migration tests cover doctor repair of legacy sender allowlists.
 import { describe, expect, it, vi } from "vitest";
 import { maybeRepairGroupAllowFromFallback } from "./allowfrom-fallback-migration.js";
 
diff --git a/src/commands/doctor/shared/allowlist-policy-repair.test.ts b/src/commands/doctor/shared/allowlist-policy-repair.test.ts
index d4c6dc0c3877..11911b7fb32d 100644
--- a/src/commands/doctor/shared/allowlist-policy-repair.test.ts
+++ b/src/commands/doctor/shared/allowlist-policy-repair.test.ts
@@ -1,3 +1,4 @@
+// Allowlist policy repair tests cover doctor repair of unsafe or stale allowlist policy.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { maybeRepairAllowlistPolicyAllowFrom } from "./allowlist-policy-repair.js";
 
diff --git a/src/commands/doctor/shared/allowlist.test.ts b/src/commands/doctor/shared/allowlist.test.ts
index 832bcdce426e..5391b27e294e 100644
--- a/src/commands/doctor/shared/allowlist.test.ts
+++ b/src/commands/doctor/shared/allowlist.test.ts
@@ -1,3 +1,4 @@
+// Allowlist tests cover doctor allowlist diagnostics and repair helpers.
 import { describe, expect, it } from "vitest";
 import { hasAllowFromEntries } from "./allowlist.js";
 
diff --git a/src/commands/doctor/shared/bundled-plugin-load-paths.test.ts b/src/commands/doctor/shared/bundled-plugin-load-paths.test.ts
index 1096243331d4..d7f237a1e8d1 100644
--- a/src/commands/doctor/shared/bundled-plugin-load-paths.test.ts
+++ b/src/commands/doctor/shared/bundled-plugin-load-paths.test.ts
@@ -1,3 +1,4 @@
+// Bundled plugin load-path tests cover doctor validation of bundled plugin paths.
 import path from "node:path";
 import { bundledDistPluginRootAt, bundledPluginRootAt } from "openclaw/plugin-sdk/test-fixtures";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/commands/doctor/shared/channel-doctor.test.ts b/src/commands/doctor/shared/channel-doctor.test.ts
index 1d067f0ec98c..5aa35559b62b 100644
--- a/src/commands/doctor/shared/channel-doctor.test.ts
+++ b/src/commands/doctor/shared/channel-doctor.test.ts
@@ -1,3 +1,4 @@
+// Channel doctor tests cover shared channel health checks and repair hints.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   collectChannelDoctorCompatibilityMutations,
diff --git a/src/commands/doctor/shared/channel-legacy-config-migrate.test.ts b/src/commands/doctor/shared/channel-legacy-config-migrate.test.ts
index 64bc827d3a38..f730d18c14dc 100644
--- a/src/commands/doctor/shared/channel-legacy-config-migrate.test.ts
+++ b/src/commands/doctor/shared/channel-legacy-config-migrate.test.ts
@@ -1,3 +1,4 @@
+// Channel legacy config migration tests cover doctor repair of old channel config shapes.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const { applyPluginDoctorCompatibilityMigrations, collectRelevantDoctorPluginIds } = vi.hoisted(
diff --git a/src/commands/doctor/shared/channel-plugin-blockers.test.ts b/src/commands/doctor/shared/channel-plugin-blockers.test.ts
index 623d554cb27f..a2058c66f95b 100644
--- a/src/commands/doctor/shared/channel-plugin-blockers.test.ts
+++ b/src/commands/doctor/shared/channel-plugin-blockers.test.ts
@@ -1,3 +1,4 @@
+// Channel plugin blocker tests cover doctor diagnostics for blocked channel plugin setup.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import * as manifestRegistry from "../../../plugins/manifest-registry.js";
 import { scanConfiguredChannelPluginBlockers } from "./channel-plugin-blockers.js";
diff --git a/src/commands/doctor/shared/codex-native-assets.test.ts b/src/commands/doctor/shared/codex-native-assets.test.ts
index 1f4b6c5ec156..a0c0f11248f4 100644
--- a/src/commands/doctor/shared/codex-native-assets.test.ts
+++ b/src/commands/doctor/shared/codex-native-assets.test.ts
@@ -1,3 +1,4 @@
+// Codex native asset tests cover doctor detection of native Codex asset state.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor/shared/codex-route-warnings.test.ts b/src/commands/doctor/shared/codex-route-warnings.test.ts
index eeaebb24dcd0..6a736e1ba840 100644
--- a/src/commands/doctor/shared/codex-route-warnings.test.ts
+++ b/src/commands/doctor/shared/codex-route-warnings.test.ts
@@ -1,3 +1,4 @@
+// Codex route warning tests cover doctor diagnostics for Codex route configuration.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { resolveAgentHarnessPolicy } from "../../../agents/harness/policy.js";
 import type { SessionEntry } from "../../../config/sessions/types.js";
diff --git a/src/commands/doctor/shared/config-flow-steps.test.ts b/src/commands/doctor/shared/config-flow-steps.test.ts
index 509fbce82ae9..14dae063046d 100644
--- a/src/commands/doctor/shared/config-flow-steps.test.ts
+++ b/src/commands/doctor/shared/config-flow-steps.test.ts
@@ -1,3 +1,4 @@
+// Config-flow step tests cover doctor repair step ordering and mutation planning.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import type { DoctorConfigPreflightResult } from "../../doctor-config-preflight.js";
diff --git a/src/commands/doctor/shared/config-mutation-state.test.ts b/src/commands/doctor/shared/config-mutation-state.test.ts
index 42c5cfa92a26..a42bff5fd45f 100644
--- a/src/commands/doctor/shared/config-mutation-state.test.ts
+++ b/src/commands/doctor/shared/config-mutation-state.test.ts
@@ -1,3 +1,4 @@
+// Config mutation state tests cover doctor mutation tracking and final state reporting.
 import { describe, expect, it } from "vitest";
 import { applyDoctorConfigMutation } from "./config-mutation-state.js";
 import type { DoctorConfigMutationState } from "./config-mutation-state.js";
diff --git a/src/commands/doctor/shared/context-engine-host-compat.test.ts b/src/commands/doctor/shared/context-engine-host-compat.test.ts
index fc715b669248..b55b5fdd5267 100644
--- a/src/commands/doctor/shared/context-engine-host-compat.test.ts
+++ b/src/commands/doctor/shared/context-engine-host-compat.test.ts
@@ -1,3 +1,4 @@
+// Context engine host compatibility tests cover doctor warnings for host/context mismatches.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import { registerContextEngine } from "../../../context-engine/registry.js";
diff --git a/src/commands/doctor/shared/deprecation-compat.test.ts b/src/commands/doctor/shared/deprecation-compat.test.ts
index 1a9bfd00527c..c3f5c82dffd8 100644
--- a/src/commands/doctor/shared/deprecation-compat.test.ts
+++ b/src/commands/doctor/shared/deprecation-compat.test.ts
@@ -1,3 +1,4 @@
+// Deprecation compatibility tests cover doctor warnings and repairs for deprecated config.
 import fs from "node:fs";
 import { describe, expect, it } from "vitest";
 import {
diff --git a/src/commands/doctor/shared/empty-allowlist-policy.test.ts b/src/commands/doctor/shared/empty-allowlist-policy.test.ts
index 0d9e1d9c9f83..a2f1863d1094 100644
--- a/src/commands/doctor/shared/empty-allowlist-policy.test.ts
+++ b/src/commands/doctor/shared/empty-allowlist-policy.test.ts
@@ -1,3 +1,4 @@
+// Empty allowlist policy tests cover doctor policy behavior when allowlists are empty.
 import { describe, expect, it, vi } from "vitest";
 import { collectEmptyAllowlistPolicyWarningsForAccount } from "./empty-allowlist-policy.js";
 
diff --git a/src/commands/doctor/shared/empty-allowlist-scan.test.ts b/src/commands/doctor/shared/empty-allowlist-scan.test.ts
index 8526025cccb1..af0ded6de3de 100644
--- a/src/commands/doctor/shared/empty-allowlist-scan.test.ts
+++ b/src/commands/doctor/shared/empty-allowlist-scan.test.ts
@@ -1,3 +1,4 @@
+// Empty allowlist scan tests cover doctor detection of unconfigured sender allowlists.
 import { describe, expect, it, vi } from "vitest";
 import { scanEmptyAllowlistPolicyWarnings } from "./empty-allowlist-scan.js";
 
diff --git a/src/commands/doctor/shared/exec-safe-bins.test.ts b/src/commands/doctor/shared/exec-safe-bins.test.ts
index 83974a6e6551..677bdb8b3a78 100644
--- a/src/commands/doctor/shared/exec-safe-bins.test.ts
+++ b/src/commands/doctor/shared/exec-safe-bins.test.ts
@@ -1,3 +1,4 @@
+// Exec safe-bin tests cover doctor validation of executable helper paths.
 import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { delimiter, join } from "node:path";
diff --git a/src/commands/doctor/shared/hooks-token-reuse-repair.test.ts b/src/commands/doctor/shared/hooks-token-reuse-repair.test.ts
index 0560d99107d7..86b291221931 100644
--- a/src/commands/doctor/shared/hooks-token-reuse-repair.test.ts
+++ b/src/commands/doctor/shared/hooks-token-reuse-repair.test.ts
@@ -1,3 +1,4 @@
+// Hooks token reuse repair tests cover doctor repairs for reused gateway hook tokens.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import { repairHooksTokenReuseGatewayAuth } from "./hooks-token-reuse-repair.js";
diff --git a/src/commands/doctor/shared/invalid-plugin-config.test.ts b/src/commands/doctor/shared/invalid-plugin-config.test.ts
index 4a20a60c3163..49f235b484ac 100644
--- a/src/commands/doctor/shared/invalid-plugin-config.test.ts
+++ b/src/commands/doctor/shared/invalid-plugin-config.test.ts
@@ -1,3 +1,4 @@
+// Invalid plugin config tests cover doctor diagnostics for malformed plugin configuration.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 
diff --git a/src/commands/doctor/shared/legacy-config-migrate.provider-shapes.test.ts b/src/commands/doctor/shared/legacy-config-migrate.provider-shapes.test.ts
index 59d3bc30c719..7923329a216b 100644
--- a/src/commands/doctor/shared/legacy-config-migrate.provider-shapes.test.ts
+++ b/src/commands/doctor/shared/legacy-config-migrate.provider-shapes.test.ts
@@ -1,3 +1,4 @@
+// Legacy provider-shape migration tests cover doctor repair of old provider config shapes.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/types.js";
 import { LEGACY_CONFIG_MIGRATIONS_RUNTIME_TTS } from "./legacy-config-migrations.runtime.tts.js";
diff --git a/src/commands/doctor/shared/legacy-config-migrate.test.ts b/src/commands/doctor/shared/legacy-config-migrate.test.ts
index acddd500892d..c0c1d9cd6dc8 100644
--- a/src/commands/doctor/shared/legacy-config-migrate.test.ts
+++ b/src/commands/doctor/shared/legacy-config-migrate.test.ts
@@ -1,3 +1,4 @@
+// Legacy config migration tests cover generic doctor repair of old config layouts.
 import { describe, expect, it } from "vitest";
 import { findLegacyConfigIssues } from "../../../config/legacy.js";
 import type { OpenClawConfig } from "../../../config/types.js";
diff --git a/src/commands/doctor/shared/legacy-config-migrate.validation.test.ts b/src/commands/doctor/shared/legacy-config-migrate.validation.test.ts
index 65523f1aec9f..a9f91851310f 100644
--- a/src/commands/doctor/shared/legacy-config-migrate.validation.test.ts
+++ b/src/commands/doctor/shared/legacy-config-migrate.validation.test.ts
@@ -1,3 +1,4 @@
+// Legacy config migration validation tests cover schema validation after doctor migrations.
 import { beforeAll, describe, expect, it } from "vitest";
 import { migrateLegacyConfig } from "./legacy-config-migrate.js";
 
diff --git a/src/commands/doctor/shared/legacy-config-migrations.runtime.models.test.ts b/src/commands/doctor/shared/legacy-config-migrations.runtime.models.test.ts
index dd8876d2689b..792570523189 100644
--- a/src/commands/doctor/shared/legacy-config-migrations.runtime.models.test.ts
+++ b/src/commands/doctor/shared/legacy-config-migrations.runtime.models.test.ts
@@ -1,3 +1,4 @@
+// Runtime model migration tests cover doctor legacy config migrations for model runtime shape.
 import { describe, it, expect } from "vitest";
 import { LEGACY_CONFIG_MIGRATIONS_RUNTIME_MODELS } from "./legacy-config-migrations.runtime.models.js";
 
diff --git a/src/commands/doctor/shared/legacy-config-write-ownership.test.ts b/src/commands/doctor/shared/legacy-config-write-ownership.test.ts
index f7294cfd933b..c721d91b0bbd 100644
--- a/src/commands/doctor/shared/legacy-config-write-ownership.test.ts
+++ b/src/commands/doctor/shared/legacy-config-write-ownership.test.ts
@@ -1,3 +1,4 @@
+// Legacy config write ownership tests cover doctor ownership boundaries for migrations.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/commands/doctor/shared/legacy-models-add-metadata.test.ts b/src/commands/doctor/shared/legacy-models-add-metadata.test.ts
index 2a65aa84991b..164d699a2585 100644
--- a/src/commands/doctor/shared/legacy-models-add-metadata.test.ts
+++ b/src/commands/doctor/shared/legacy-models-add-metadata.test.ts
@@ -1,3 +1,4 @@
+// Legacy model metadata tests cover doctor migration that adds model metadata.
 import { describe, expect, it } from "vitest";
 import type { ModelDefinitionConfig } from "../../../config/types.models.js";
 import { isLegacyModelsAddCodexMetadataModel } from "./legacy-models-add-metadata.js";
diff --git a/src/commands/doctor/shared/legacy-oauth-sidecar.test.ts b/src/commands/doctor/shared/legacy-oauth-sidecar.test.ts
index 1637325fe96c..705adf1edcc4 100644
--- a/src/commands/doctor/shared/legacy-oauth-sidecar.test.ts
+++ b/src/commands/doctor/shared/legacy-oauth-sidecar.test.ts
@@ -1,3 +1,4 @@
+// Legacy OAuth sidecar tests cover doctor repair and warnings for old OAuth sidecar state.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { resetLogger, setLoggerOverride } from "../../../logging/logger.js";
 import { loggingState } from "../../../logging/state.js";
diff --git a/src/commands/doctor/shared/legacy-tools-by-sender.test.ts b/src/commands/doctor/shared/legacy-tools-by-sender.test.ts
index 292c8cc719a2..a007d1d52558 100644
--- a/src/commands/doctor/shared/legacy-tools-by-sender.test.ts
+++ b/src/commands/doctor/shared/legacy-tools-by-sender.test.ts
@@ -1,3 +1,4 @@
+// Legacy tools-by-sender tests cover doctor migration of sender-scoped tool config.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import {
diff --git a/src/commands/doctor/shared/legacy-web-fetch-migrate.test.ts b/src/commands/doctor/shared/legacy-web-fetch-migrate.test.ts
index de9c7da6fd2e..e0db5256d8c3 100644
--- a/src/commands/doctor/shared/legacy-web-fetch-migrate.test.ts
+++ b/src/commands/doctor/shared/legacy-web-fetch-migrate.test.ts
@@ -1,3 +1,4 @@
+// Legacy web-fetch migration tests cover doctor repair of old web fetch config.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import {
diff --git a/src/commands/doctor/shared/legacy-web-search-migrate.test.ts b/src/commands/doctor/shared/legacy-web-search-migrate.test.ts
index b7b15f125f11..ab168a34220a 100644
--- a/src/commands/doctor/shared/legacy-web-search-migrate.test.ts
+++ b/src/commands/doctor/shared/legacy-web-search-migrate.test.ts
@@ -1,3 +1,4 @@
+// Legacy web-search migration tests cover doctor repair of old web search config.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import {
diff --git a/src/commands/doctor/shared/legacy-x-search-migrate.test.ts b/src/commands/doctor/shared/legacy-x-search-migrate.test.ts
index 31539c0469a2..44e676e25cbc 100644
--- a/src/commands/doctor/shared/legacy-x-search-migrate.test.ts
+++ b/src/commands/doctor/shared/legacy-x-search-migrate.test.ts
@@ -1,3 +1,4 @@
+// Legacy X search migration tests cover doctor repair of old X search config.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import {
diff --git a/src/commands/doctor/shared/missing-configured-plugin-install.test.ts b/src/commands/doctor/shared/missing-configured-plugin-install.test.ts
index 94e4bb42ef61..a6a797669085 100644
--- a/src/commands/doctor/shared/missing-configured-plugin-install.test.ts
+++ b/src/commands/doctor/shared/missing-configured-plugin-install.test.ts
@@ -1,3 +1,4 @@
+// Missing configured plugin install tests cover doctor diagnostics for absent plugin installs.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor/shared/open-policy-allowfrom.test.ts b/src/commands/doctor/shared/open-policy-allowfrom.test.ts
index 440996175f98..2b664a7e3e0f 100644
--- a/src/commands/doctor/shared/open-policy-allowfrom.test.ts
+++ b/src/commands/doctor/shared/open-policy-allowfrom.test.ts
@@ -1,3 +1,4 @@
+// Open policy allow-from tests cover doctor handling of open allowlist policy.
 import { describe, expect, it, vi } from "vitest";
 import {
   collectOpenPolicyAllowFromWarnings,
diff --git a/src/commands/doctor/shared/plugin-dependency-cleanup.test.ts b/src/commands/doctor/shared/plugin-dependency-cleanup.test.ts
index 5fefff982394..6475522bdcde 100644
--- a/src/commands/doctor/shared/plugin-dependency-cleanup.test.ts
+++ b/src/commands/doctor/shared/plugin-dependency-cleanup.test.ts
@@ -1,3 +1,4 @@
+// Plugin dependency cleanup tests cover doctor cleanup of stale plugin dependencies.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor/shared/plugin-registry-migration.test.ts b/src/commands/doctor/shared/plugin-registry-migration.test.ts
index 377842f1ab84..bdaa4cea6af4 100644
--- a/src/commands/doctor/shared/plugin-registry-migration.test.ts
+++ b/src/commands/doctor/shared/plugin-registry-migration.test.ts
@@ -1,3 +1,4 @@
+// Plugin registry migration tests cover doctor repair of persisted plugin registry state.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/commands/doctor/shared/plugin-tool-allowlist-warnings.test.ts b/src/commands/doctor/shared/plugin-tool-allowlist-warnings.test.ts
index e65b2af00f54..2bd7424947a2 100644
--- a/src/commands/doctor/shared/plugin-tool-allowlist-warnings.test.ts
+++ b/src/commands/doctor/shared/plugin-tool-allowlist-warnings.test.ts
@@ -1,3 +1,4 @@
+// Plugin tool allowlist warning tests cover doctor warnings for stale tool allowlists.
 import { describe, expect, it } from "vitest";
 import type { PluginManifestRegistry } from "../../../plugins/manifest-registry.js";
 import { collectPluginToolAllowlistWarnings } from "./plugin-tool-allowlist-warnings.js";
diff --git a/src/commands/doctor/shared/preview-warnings.test.ts b/src/commands/doctor/shared/preview-warnings.test.ts
index 5dc3f7757307..80fae4fe1c0c 100644
--- a/src/commands/doctor/shared/preview-warnings.test.ts
+++ b/src/commands/doctor/shared/preview-warnings.test.ts
@@ -1,3 +1,4 @@
+// Preview warning tests cover doctor warnings for preview or experimental config state.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor/shared/release-configured-plugin-installs.test.ts b/src/commands/doctor/shared/release-configured-plugin-installs.test.ts
index da2699cd9d02..8839f35ff2ba 100644
--- a/src/commands/doctor/shared/release-configured-plugin-installs.test.ts
+++ b/src/commands/doctor/shared/release-configured-plugin-installs.test.ts
@@ -1,3 +1,4 @@
+// Release configured plugin install tests cover doctor checks for release-time plugin installs.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
diff --git a/src/commands/doctor/shared/stale-oauth-profile-shadows.test.ts b/src/commands/doctor/shared/stale-oauth-profile-shadows.test.ts
index 976a684c5008..d4e53ce1db5b 100644
--- a/src/commands/doctor/shared/stale-oauth-profile-shadows.test.ts
+++ b/src/commands/doctor/shared/stale-oauth-profile-shadows.test.ts
@@ -1,3 +1,4 @@
+// Stale OAuth profile shadow tests cover doctor detection of shadowed auth profiles.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/commands/doctor/shared/stale-plugin-config.test.ts b/src/commands/doctor/shared/stale-plugin-config.test.ts
index a61e4116ad21..882268cdf4be 100644
--- a/src/commands/doctor/shared/stale-plugin-config.test.ts
+++ b/src/commands/doctor/shared/stale-plugin-config.test.ts
@@ -1,3 +1,4 @@
+// Stale plugin config tests cover doctor cleanup and warnings for obsolete plugin config.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../../config/config.js";
 import type { PluginInstallRecord } from "../../../config/types.plugins.js";
diff --git a/src/commands/doctor/shared/stale-subagent-allowlist.test.ts b/src/commands/doctor/shared/stale-subagent-allowlist.test.ts
index b8841ff89cf9..8a7de8101673 100644
--- a/src/commands/doctor/shared/stale-subagent-allowlist.test.ts
+++ b/src/commands/doctor/shared/stale-subagent-allowlist.test.ts
@@ -1,3 +1,4 @@
+// Stale subagent allowlist tests cover doctor warnings for obsolete subagent allowlists.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
 import {
diff --git a/src/commands/doctor/shared/update-phase.test.ts b/src/commands/doctor/shared/update-phase.test.ts
index b6058c1ba1c5..f244e995b042 100644
--- a/src/commands/doctor/shared/update-phase.test.ts
+++ b/src/commands/doctor/shared/update-phase.test.ts
@@ -1,3 +1,4 @@
+// Update phase tests cover doctor behavior during staged update phases.
 import { describe, expect, it } from "vitest";
 import {
   UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR_ENV,