From ecb6779a1632e5e5bb4082010a708a26ed598fcd Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 20:37:28 -0400
Subject: [PATCH] docs: document root test files

---
 test/appcast.test.ts                                 | 1 +
 test/architecture-smells.test.ts                     | 1 +
 test/cli-json-stdout.e2e.test.ts                     | 1 +
 test/extension-import-boundaries.test.ts             | 1 +
 test/extension-package-tsc-boundary.test.ts          | 1 +
 test/extension-test-boundary.test.ts                 | 1 +
 test/gateway.multi.e2e.test.ts                       | 1 +
 test/git-hooks-pre-commit.test.ts                    | 1 +
 test/global-setup.ts                                 | 1 +
 test/image-generation.infer-cli.live.test.ts         | 1 +
 test/image-generation.runtime.live.test.ts           | 1 +
 test/non-isolated-runner.ts                          | 1 +
 test/npm-publish-plan.test.ts                        | 1 +
 test/official-channel-catalog.test.ts                | 1 +
 test/openclaw-launcher.e2e.test.ts                   | 1 +
 test/openclaw-npm-postpublish-verify.test.ts         | 1 +
 test/openclaw-npm-release-check.test.ts              | 1 +
 test/openclaw-prepack.test.ts                        | 1 +
 test/package-manager-config.test.ts                  | 1 +
 test/package-scripts.test.ts                         | 1 +
 test/plugin-clawhub-release.test.ts                  | 1 +
 test/plugin-extension-import-boundary.test.ts        | 1 +
 test/plugin-npm-package-manifest.test.ts             | 1 +
 test/plugin-npm-release.test.ts                      | 1 +
 test/plugin-npm-runtime-build.test.ts                | 1 +
 test/qa-convex-credential-payload-validation.test.ts | 1 +
 test/release-check.test.ts                           | 1 +
 test/setup-home-isolation.test.ts                    | 1 +
 test/setup-openclaw-runtime.ts                       | 1 +
 test/setup.extensions.ts                             | 1 +
 test/setup.shared.ts                                 | 1 +
 test/setup.ts                                        | 1 +
 test/test-env.test.ts                                | 1 +
 test/test-env.ts                                     | 1 +
 test/test-helper-extension-import-boundary.test.ts   | 1 +
 test/ui.presenter-next-run.test.ts                   | 1 +
 test/vitest-boundary-config.test.ts                  | 1 +
 test/vitest-extensions-config.test.ts                | 1 +
 test/vitest-light-paths.test.ts                      | 1 +
 test/vitest-performance-config.test.ts               | 1 +
 test/vitest-projects-config.test.ts                  | 1 +
 test/vitest-scoped-config.test.ts                    | 1 +
 test/vitest-ui-package-config.test.ts                | 1 +
 test/vitest-unit-config.test.ts                      | 1 +
 test/vitest-unit-fast-config.test.ts                 | 1 +
 test/vitest-unit-paths.test.ts                       | 1 +
 test/web-provider-boundary.test.ts                   | 1 +
 47 files changed, 47 insertions(+)

diff --git a/test/appcast.test.ts b/test/appcast.test.ts
index cce46caf054b..40bc17178d75 100644
--- a/test/appcast.test.ts
+++ b/test/appcast.test.ts
@@ -1,3 +1,4 @@
+// Appcast tests validate generated update appcast metadata.
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 import { canonicalSparkleBuildFromVersion } from "../scripts/sparkle-build.ts";
diff --git a/test/architecture-smells.test.ts b/test/architecture-smells.test.ts
index 11239ace5cb2..98717fcc451f 100644
--- a/test/architecture-smells.test.ts
+++ b/test/architecture-smells.test.ts
@@ -1,3 +1,4 @@
+// Architecture smell tests flag unwanted dependency and layout patterns.
 import { describe, expect, it } from "vitest";
 import { collectArchitectureSmells, main } from "../scripts/check-architecture-smells.mjs";
 import { createCapturedIo } from "./helpers/captured-io.js";
diff --git a/test/cli-json-stdout.e2e.test.ts b/test/cli-json-stdout.e2e.test.ts
index 4bdfd154694c..53dff52814eb 100644
--- a/test/cli-json-stdout.e2e.test.ts
+++ b/test/cli-json-stdout.e2e.test.ts
@@ -1,3 +1,4 @@
+// CLI JSON stdout E2E tests validate machine-readable CLI output.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
diff --git a/test/extension-import-boundaries.test.ts b/test/extension-import-boundaries.test.ts
index b339db250a0b..e3b5510a6148 100644
--- a/test/extension-import-boundaries.test.ts
+++ b/test/extension-import-boundaries.test.ts
@@ -1,3 +1,4 @@
+// Extension import boundary tests enforce extension/core import rules.
 import { describe, expect, it } from "vitest";
 import { main as extensionPluginSdkMain } from "../scripts/check-extension-plugin-sdk-boundary.mjs";
 import { main as sdkPackageMain } from "../scripts/check-sdk-package-extension-import-boundary.mjs";
diff --git a/test/extension-package-tsc-boundary.test.ts b/test/extension-package-tsc-boundary.test.ts
index 413a9322af3d..14cc1579e2e6 100644
--- a/test/extension-package-tsc-boundary.test.ts
+++ b/test/extension-package-tsc-boundary.test.ts
@@ -1,3 +1,4 @@
+// Extension package TypeScript boundary tests cover package compile isolation.
 import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/test/extension-test-boundary.test.ts b/test/extension-test-boundary.test.ts
index 4bf015b68362..a2a2c37fc0f8 100644
--- a/test/extension-test-boundary.test.ts
+++ b/test/extension-test-boundary.test.ts
@@ -1,3 +1,4 @@
+// Extension test boundary tests enforce extension test layout rules.
 import fs from "node:fs";
 import path from "node:path";
 import { BUNDLED_PLUGIN_PATH_PREFIX } from "openclaw/plugin-sdk/test-fixtures";
diff --git a/test/gateway.multi.e2e.test.ts b/test/gateway.multi.e2e.test.ts
index a772f1cf7464..e99aea98a156 100644
--- a/test/gateway.multi.e2e.test.ts
+++ b/test/gateway.multi.e2e.test.ts
@@ -1,3 +1,4 @@
+// Gateway multi E2E tests validate multi-gateway runtime behavior.
 import { afterAll, describe, expect, it } from "vitest";
 import { GatewayClient } from "../src/gateway/client.js";
 import {
diff --git a/test/git-hooks-pre-commit.test.ts b/test/git-hooks-pre-commit.test.ts
index 5777d0210def..d9655d704923 100644
--- a/test/git-hooks-pre-commit.test.ts
+++ b/test/git-hooks-pre-commit.test.ts
@@ -1,3 +1,4 @@
+// Git hook tests validate pre-commit hook behavior and scripts.
 import { execFileSync } from "node:child_process";
 import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
diff --git a/test/global-setup.ts b/test/global-setup.ts
index 289fd877b335..4cb1850f2dc8 100644
--- a/test/global-setup.ts
+++ b/test/global-setup.ts
@@ -1,3 +1,4 @@
+// Global test setup installs shared environment before Vitest projects run.
 import { installTestEnv } from "./test-env";
 
 export default async () => {
diff --git a/test/image-generation.infer-cli.live.test.ts b/test/image-generation.infer-cli.live.test.ts
index 9bbcde8c2daa..ca107292ea7b 100644
--- a/test/image-generation.infer-cli.live.test.ts
+++ b/test/image-generation.infer-cli.live.test.ts
@@ -1,3 +1,4 @@
+// Live image generation CLI tests validate inferred CLI image generation.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
diff --git a/test/image-generation.runtime.live.test.ts b/test/image-generation.runtime.live.test.ts
index 9e1774de5b73..f34ffffcad62 100644
--- a/test/image-generation.runtime.live.test.ts
+++ b/test/image-generation.runtime.live.test.ts
@@ -1,3 +1,4 @@
+// Live image generation runtime tests cover image provider runtime behavior.
 import {
   registerProviderPlugin,
   requireRegisteredProvider,
diff --git a/test/non-isolated-runner.ts b/test/non-isolated-runner.ts
index 8af819d17d1a..4525367b60a4 100644
--- a/test/non-isolated-runner.ts
+++ b/test/non-isolated-runner.ts
@@ -1,3 +1,4 @@
+// Non-isolated runner helps execute tests without Vitest isolation.
 import fs from "node:fs";
 import path from "node:path";
 import { TestRunner, type RunnerTask, type RunnerTestSuite, vi } from "vitest";
diff --git a/test/npm-publish-plan.test.ts b/test/npm-publish-plan.test.ts
index 342890125344..07c648e3fcfe 100644
--- a/test/npm-publish-plan.test.ts
+++ b/test/npm-publish-plan.test.ts
@@ -1,3 +1,4 @@
+// npm publish plan tests validate package publish planning rules.
 import { describe, expect, it } from "vitest";
 import {
   resolveNpmDistTagMirrorAuth,
diff --git a/test/official-channel-catalog.test.ts b/test/official-channel-catalog.test.ts
index c68d1b0626bf..77bba7788f22 100644
--- a/test/official-channel-catalog.test.ts
+++ b/test/official-channel-catalog.test.ts
@@ -1,3 +1,4 @@
+// Official channel catalog tests validate catalog metadata and entries.
 import fs from "node:fs";
 import path from "node:path";
 import { bundledPluginRoot } from "openclaw/plugin-sdk/test-fixtures";
diff --git a/test/openclaw-launcher.e2e.test.ts b/test/openclaw-launcher.e2e.test.ts
index 35f80254b7a5..5439112697b7 100644
--- a/test/openclaw-launcher.e2e.test.ts
+++ b/test/openclaw-launcher.e2e.test.ts
@@ -1,3 +1,4 @@
+// OpenClaw launcher E2E tests validate launcher process behavior.
 import { spawn, spawnSync } from "node:child_process";
 import { once } from "node:events";
 import fs from "node:fs/promises";
diff --git a/test/openclaw-npm-postpublish-verify.test.ts b/test/openclaw-npm-postpublish-verify.test.ts
index cbe355b5243e..30b92b5611ec 100644
--- a/test/openclaw-npm-postpublish-verify.test.ts
+++ b/test/openclaw-npm-postpublish-verify.test.ts
@@ -1,3 +1,4 @@
+// OpenClaw npm postpublish tests validate postpublish verification behavior.
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
diff --git a/test/openclaw-npm-release-check.test.ts b/test/openclaw-npm-release-check.test.ts
index dd78bee8ea71..f18c8a75a016 100644
--- a/test/openclaw-npm-release-check.test.ts
+++ b/test/openclaw-npm-release-check.test.ts
@@ -1,3 +1,4 @@
+// OpenClaw npm release check tests validate package release checks.
 import { execFileSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
diff --git a/test/openclaw-prepack.test.ts b/test/openclaw-prepack.test.ts
index 03d4962ad5c0..b2a8945d0111 100644
--- a/test/openclaw-prepack.test.ts
+++ b/test/openclaw-prepack.test.ts
@@ -1,3 +1,4 @@
+// OpenClaw prepack tests validate package prepack output.
 import { describe, expect, it } from "vitest";
 import {
   collectPreparedPrepackErrors,
diff --git a/test/package-manager-config.test.ts b/test/package-manager-config.test.ts
index 5ca70dc6be8e..9f3701bd6848 100644
--- a/test/package-manager-config.test.ts
+++ b/test/package-manager-config.test.ts
@@ -1,3 +1,4 @@
+// Package manager config tests validate workspace package manager settings.
 import fs from "node:fs";
 import { describe, expect, it } from "vitest";
 import { parse } from "yaml";
diff --git a/test/package-scripts.test.ts b/test/package-scripts.test.ts
index 06ab21db1c1e..e35ed7f64199 100644
--- a/test/package-scripts.test.ts
+++ b/test/package-scripts.test.ts
@@ -1,3 +1,4 @@
+// Package script tests validate root package script invariants.
 import fs from "node:fs";
 import { describe, expect, it } from "vitest";
 
diff --git a/test/plugin-clawhub-release.test.ts b/test/plugin-clawhub-release.test.ts
index ceff98d38eeb..99094c13abc5 100644
--- a/test/plugin-clawhub-release.test.ts
+++ b/test/plugin-clawhub-release.test.ts
@@ -1,3 +1,4 @@
+// Plugin ClawHub release tests validate plugin release metadata and artifacts.
 import { execFileSync } from "node:child_process";
 import { chmodSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { delimiter, join } from "node:path";
diff --git a/test/plugin-extension-import-boundary.test.ts b/test/plugin-extension-import-boundary.test.ts
index b912c9756f03..7c2312070258 100644
--- a/test/plugin-extension-import-boundary.test.ts
+++ b/test/plugin-extension-import-boundary.test.ts
@@ -1,3 +1,4 @@
+// Plugin extension import boundary tests enforce plugin extension import rules.
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/test/plugin-npm-package-manifest.test.ts b/test/plugin-npm-package-manifest.test.ts
index 602b674b39be..01bdaf7af775 100644
--- a/test/plugin-npm-package-manifest.test.ts
+++ b/test/plugin-npm-package-manifest.test.ts
@@ -1,3 +1,4 @@
+// Plugin npm manifest tests validate generated plugin package manifests.
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, win32 } from "node:path";
diff --git a/test/plugin-npm-release.test.ts b/test/plugin-npm-release.test.ts
index 802ccd3596a2..bc0d128bd263 100644
--- a/test/plugin-npm-release.test.ts
+++ b/test/plugin-npm-release.test.ts
@@ -1,3 +1,4 @@
+// Plugin npm release tests validate plugin npm release artifacts.
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { bundledPluginFile, bundledPluginRoot } from "openclaw/plugin-sdk/test-fixtures";
diff --git a/test/plugin-npm-runtime-build.test.ts b/test/plugin-npm-runtime-build.test.ts
index f3eef8f7e208..eaf01fb0c5cb 100644
--- a/test/plugin-npm-runtime-build.test.ts
+++ b/test/plugin-npm-runtime-build.test.ts
@@ -1,3 +1,4 @@
+// Plugin npm runtime build tests validate plugin runtime package builds.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {
diff --git a/test/qa-convex-credential-payload-validation.test.ts b/test/qa-convex-credential-payload-validation.test.ts
index ffcc0db35675..19370393178d 100644
--- a/test/qa-convex-credential-payload-validation.test.ts
+++ b/test/qa-convex-credential-payload-validation.test.ts
@@ -1,3 +1,4 @@
+// QA Convex credential tests validate credential payload shapes.
 import { describe, expect, it } from "vitest";
 import {
   CredentialPayloadValidationError,
diff --git a/test/release-check.test.ts b/test/release-check.test.ts
index dee082a79a62..9233ffd5da3a 100644
--- a/test/release-check.test.ts
+++ b/test/release-check.test.ts
@@ -1,3 +1,4 @@
+// Release check tests cover release validation script behavior.
 import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, win32 } from "node:path";
diff --git a/test/setup-home-isolation.test.ts b/test/setup-home-isolation.test.ts
index 66d5a5e9bd7f..869a1eee6275 100644
--- a/test/setup-home-isolation.test.ts
+++ b/test/setup-home-isolation.test.ts
@@ -1,3 +1,4 @@
+// Home isolation tests validate HOME and state directory isolation.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { createConfigIO } from "../src/config/config.js";
diff --git a/test/setup-openclaw-runtime.ts b/test/setup-openclaw-runtime.ts
index e16d6b65867d..518951dec11f 100644
--- a/test/setup-openclaw-runtime.ts
+++ b/test/setup-openclaw-runtime.ts
@@ -1,3 +1,4 @@
+// OpenClaw runtime test setup installs runtime mocks and cleanup.
 import { afterAll, afterEach, beforeAll, vi } from "vitest";
 import type {
   ChannelId,
diff --git a/test/setup.extensions.ts b/test/setup.extensions.ts
index d27989e8508f..dfbceecd98cb 100644
--- a/test/setup.extensions.ts
+++ b/test/setup.extensions.ts
@@ -1,3 +1,4 @@
+// Extension test setup installs extension-specific mocks and cleanup.
 import { afterAll, beforeEach, vi } from "vitest";
 import { installSharedTestSetup } from "./setup.shared.js";
 
diff --git a/test/setup.shared.ts b/test/setup.shared.ts
index 747e6d4b7c3a..fe75fcbf0f9a 100644
--- a/test/setup.shared.ts
+++ b/test/setup.shared.ts
@@ -1,3 +1,4 @@
+// Shared test setup installs common Vitest mocks and cleanup behavior.
 import { vi } from "vitest";
 
 const openAiCodexTokenRefreshTestHook = "__OPENCLAW_TEST_REFRESH_OPENAI_CODEX_TOKEN__";
diff --git a/test/setup.ts b/test/setup.ts
index 7595d6042a77..4ced73fb100b 100644
--- a/test/setup.ts
+++ b/test/setup.ts
@@ -1,3 +1,4 @@
+// Default test setup installs the shared test environment.
 import { installSharedTestSetup } from "./setup.shared.js";
 
 installSharedTestSetup();
diff --git a/test/test-env.test.ts b/test/test-env.test.ts
index 704690d7b581..6207311f11fe 100644
--- a/test/test-env.test.ts
+++ b/test/test-env.test.ts
@@ -1,3 +1,4 @@
+// Test environment tests validate shared env setup helpers.
 import fs from "node:fs";
 import path from "node:path";
 import { importFreshModule } from "openclaw/plugin-sdk/test-fixtures";
diff --git a/test/test-env.ts b/test/test-env.ts
index 43110a18be8e..a38a09aae20b 100644
--- a/test/test-env.ts
+++ b/test/test-env.ts
@@ -1,3 +1,4 @@
+// Test environment helpers install process env defaults for tests.
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import { createRequire } from "node:module";
diff --git a/test/test-helper-extension-import-boundary.test.ts b/test/test-helper-extension-import-boundary.test.ts
index 510f59e3e0f9..347d928f962a 100644
--- a/test/test-helper-extension-import-boundary.test.ts
+++ b/test/test-helper-extension-import-boundary.test.ts
@@ -1,3 +1,4 @@
+// Test helper extension boundary tests enforce helper import boundaries.
 import { describe, expect, it } from "vitest";
 import {
   collectTestHelperExtensionImportBoundaryInventory,
diff --git a/test/ui.presenter-next-run.test.ts b/test/ui.presenter-next-run.test.ts
index 363cfcdc7b62..69a172f76f9c 100644
--- a/test/ui.presenter-next-run.test.ts
+++ b/test/ui.presenter-next-run.test.ts
@@ -1,3 +1,4 @@
+// UI presenter next-run tests cover presenter scheduling output.
 import { describe, expect, it } from "vitest";
 import { t } from "../ui/src/i18n/index.ts";
 import { formatNextRun } from "../ui/src/ui/presenter.ts";
diff --git a/test/vitest-boundary-config.test.ts b/test/vitest-boundary-config.test.ts
index 0c99d22588e7..c679c6a54e43 100644
--- a/test/vitest-boundary-config.test.ts
+++ b/test/vitest-boundary-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest boundary config tests validate boundary test configuration.
 import { describe, expect, it } from "vitest";
 import { normalizeConfigPath, normalizeConfigPaths } from "./helpers/vitest-config-paths.js";
 import {
diff --git a/test/vitest-extensions-config.test.ts b/test/vitest-extensions-config.test.ts
index c981df968c59..8084c19d3083 100644
--- a/test/vitest-extensions-config.test.ts
+++ b/test/vitest-extensions-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest extensions config tests validate bundled extension test configuration.
 import { bundledPluginFile } from "openclaw/plugin-sdk/test-fixtures";
 import { afterEach, describe, expect, it } from "vitest";
 import { createPatternFileHelper } from "./helpers/pattern-file.js";
diff --git a/test/vitest-light-paths.test.ts b/test/vitest-light-paths.test.ts
index 60f4a6eb133e..b18a91ac5b13 100644
--- a/test/vitest-light-paths.test.ts
+++ b/test/vitest-light-paths.test.ts
@@ -1,3 +1,4 @@
+// Vitest light path tests validate light test include path generation.
 import { describe, expect, it } from "vitest";
 import {
   isCommandsLightTarget,
diff --git a/test/vitest-performance-config.test.ts b/test/vitest-performance-config.test.ts
index 44114e32907b..95023fe8fdb9 100644
--- a/test/vitest-performance-config.test.ts
+++ b/test/vitest-performance-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest performance config tests validate performance test project setup.
 import { describe, expect, it } from "vitest";
 import { loadVitestExperimentalConfig } from "./vitest/vitest.performance-config.ts";
 
diff --git a/test/vitest-projects-config.test.ts b/test/vitest-projects-config.test.ts
index 233031ff7e2b..105061a4975c 100644
--- a/test/vitest-projects-config.test.ts
+++ b/test/vitest-projects-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest project config tests validate aggregate Vitest project wiring.
 import { afterEach, describe, expect, it } from "vitest";
 import { createPatternFileHelper } from "./helpers/pattern-file.js";
 import { normalizeConfigPath, normalizeConfigPaths } from "./helpers/vitest-config-paths.js";
diff --git a/test/vitest-scoped-config.test.ts b/test/vitest-scoped-config.test.ts
index c33a4182800d..e013fa2495f5 100644
--- a/test/vitest-scoped-config.test.ts
+++ b/test/vitest-scoped-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest scoped config tests validate scoped project config generation.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/test/vitest-ui-package-config.test.ts b/test/vitest-ui-package-config.test.ts
index e4f6934bae3a..817658e630c2 100644
--- a/test/vitest-ui-package-config.test.ts
+++ b/test/vitest-ui-package-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest UI package config tests validate UI package test project settings.
 import { describe, expect, it } from "vitest";
 import uiConfig from "../ui/vitest.config.ts";
 import uiNodeConfig from "../ui/vitest.node.config.ts";
diff --git a/test/vitest-unit-config.test.ts b/test/vitest-unit-config.test.ts
index 0a7db4eff54c..66b134e56030 100644
--- a/test/vitest-unit-config.test.ts
+++ b/test/vitest-unit-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest unit config tests validate unit test project configuration.
 import { afterEach, describe, expect, it } from "vitest";
 import { createPatternFileHelper } from "./helpers/pattern-file.js";
 import { normalizeConfigPath, normalizeConfigPaths } from "./helpers/vitest-config-paths.js";
diff --git a/test/vitest-unit-fast-config.test.ts b/test/vitest-unit-fast-config.test.ts
index a27bed028514..93b762948243 100644
--- a/test/vitest-unit-fast-config.test.ts
+++ b/test/vitest-unit-fast-config.test.ts
@@ -1,3 +1,4 @@
+// Vitest unit-fast config tests validate fast unit test project setup.
 import { beforeAll, describe, expect, it } from "vitest";
 import { spawnNodeEvalSync } from "../src/test-utils/node-process.js";
 import { createCommandsLightVitestConfig } from "./vitest/vitest.commands-light.config.ts";
diff --git a/test/vitest-unit-paths.test.ts b/test/vitest-unit-paths.test.ts
index f9b8131bc9dc..97ff4b755758 100644
--- a/test/vitest-unit-paths.test.ts
+++ b/test/vitest-unit-paths.test.ts
@@ -1,3 +1,4 @@
+// Vitest unit path tests validate unit test include and exclude paths.
 import { bundledPluginFile } from "openclaw/plugin-sdk/test-fixtures";
 import { describe, expect, it } from "vitest";
 import { isUnitConfigTestFile } from "./vitest/vitest.unit-paths.mjs";
diff --git a/test/web-provider-boundary.test.ts b/test/web-provider-boundary.test.ts
index 44c5bf4a6742..fab113c76e1b 100644
--- a/test/web-provider-boundary.test.ts
+++ b/test/web-provider-boundary.test.ts
@@ -1,3 +1,4 @@
+// Web provider boundary tests enforce provider import boundaries.
 import { describe, expect, it } from "vitest";
 import {
   collectWebFetchProviderBoundaryViolations,