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

---
 src/docs/channel-config-examples.test.ts       | 1 +
 src/docs/clawhub-plugin-docs.test.ts           | 1 +
 src/docs/config-path-docs.test.ts              | 1 +
 src/docs/environment-docs.test.ts              | 1 +
 src/docs/install-cloud-secrets.test.ts         | 1 +
 src/docs/plugin-doc-examples.test.ts           | 1 +
 src/docs/slash-commands-doc.test.ts            | 1 +
 src/scripts/ci-changed-scope.test.ts           | 1 +
 src/scripts/control-ui-i18n-report.test.ts     | 1 +
 src/scripts/control-ui-i18n.test.ts            | 1 +
 src/scripts/docs-link-audit.test.ts            | 1 +
 src/scripts/prepare-codex-ci-auth.test.ts      | 1 +
 src/scripts/prepare-codex-ci-config.test.ts    | 1 +
 src/scripts/sync-plugin-versions.test.ts       | 1 +
 src/scripts/test-live-media.test.ts            | 1 +
 src/scripts/test-projects.test.ts              | 1 +
 src/state/openclaw-agent-db.paths.ts           | 1 +
 src/state/openclaw-agent-db.test.ts            | 1 +
 src/state/openclaw-agent-db.ts                 | 1 +
 src/state/openclaw-state-db.paths.ts           | 1 +
 src/state/openclaw-state-db.test.ts            | 1 +
 src/state/openclaw-state-db.ts                 | 1 +
 src/state/sqlite-schema-shape.test-support.ts  | 1 +
 src/test-helpers/network-interfaces.ts         | 1 +
 src/test-helpers/resolve-target-error-cases.ts | 1 +
 src/test-helpers/ssrf.ts                       | 1 +
 src/test-helpers/state-dir-env.test.ts         | 1 +
 src/test-helpers/state-dir-env.ts              | 1 +
 src/test-helpers/temp-dir.test.ts              | 1 +
 src/test-helpers/temp-dir.ts                   | 1 +
 src/test-helpers/windows-cmd-shim.ts           | 1 +
 src/test-helpers/workspace.ts                  | 1 +
 32 files changed, 32 insertions(+)

diff --git a/src/docs/channel-config-examples.test.ts b/src/docs/channel-config-examples.test.ts
index 54f1e655acf6..5998202e5ba5 100644
--- a/src/docs/channel-config-examples.test.ts
+++ b/src/docs/channel-config-examples.test.ts
@@ -1,3 +1,4 @@
+// Channel config example tests validate channel configuration snippets in docs.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/docs/clawhub-plugin-docs.test.ts b/src/docs/clawhub-plugin-docs.test.ts
index c93f1a2c8ee0..753e099d80e4 100644
--- a/src/docs/clawhub-plugin-docs.test.ts
+++ b/src/docs/clawhub-plugin-docs.test.ts
@@ -1,3 +1,4 @@
+// ClawHub plugin docs tests validate plugin documentation examples.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/docs/config-path-docs.test.ts b/src/docs/config-path-docs.test.ts
index bc8ac4707789..eb4818b93b81 100644
--- a/src/docs/config-path-docs.test.ts
+++ b/src/docs/config-path-docs.test.ts
@@ -1,3 +1,4 @@
+// Config path docs tests validate documented config path references.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/docs/environment-docs.test.ts b/src/docs/environment-docs.test.ts
index 679e7a4ae5fa..51a56b46983c 100644
--- a/src/docs/environment-docs.test.ts
+++ b/src/docs/environment-docs.test.ts
@@ -1,3 +1,4 @@
+// Environment docs tests validate documented environment variable references.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/docs/install-cloud-secrets.test.ts b/src/docs/install-cloud-secrets.test.ts
index cf55fc247c20..b776d6e2f9f8 100644
--- a/src/docs/install-cloud-secrets.test.ts
+++ b/src/docs/install-cloud-secrets.test.ts
@@ -1,3 +1,4 @@
+// Cloud secret install docs tests validate documented cloud secret setup.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/docs/plugin-doc-examples.test.ts b/src/docs/plugin-doc-examples.test.ts
index 12e4dea194ee..4ce794883bcc 100644
--- a/src/docs/plugin-doc-examples.test.ts
+++ b/src/docs/plugin-doc-examples.test.ts
@@ -1,3 +1,4 @@
+// Plugin documentation example tests validate plugin snippets from docs.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/docs/slash-commands-doc.test.ts b/src/docs/slash-commands-doc.test.ts
index 87e5bc702475..f91fd87a7738 100644
--- a/src/docs/slash-commands-doc.test.ts
+++ b/src/docs/slash-commands-doc.test.ts
@@ -1,3 +1,4 @@
+// Slash command docs tests validate documented slash command references.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
diff --git a/src/scripts/ci-changed-scope.test.ts b/src/scripts/ci-changed-scope.test.ts
index 5c6c86a7c787..6e8dceb6513e 100644
--- a/src/scripts/ci-changed-scope.test.ts
+++ b/src/scripts/ci-changed-scope.test.ts
@@ -1,3 +1,4 @@
+// CI changed scope tests cover script detection of changed files and lanes.
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
diff --git a/src/scripts/control-ui-i18n-report.test.ts b/src/scripts/control-ui-i18n-report.test.ts
index 552cb9e556be..1d414be0b099 100644
--- a/src/scripts/control-ui-i18n-report.test.ts
+++ b/src/scripts/control-ui-i18n-report.test.ts
@@ -1,3 +1,4 @@
+// Control UI i18n report tests cover locale report generation.
 import { describe, expect, it } from "vitest";
 import {
   filterRawCopyEntries,
diff --git a/src/scripts/control-ui-i18n.test.ts b/src/scripts/control-ui-i18n.test.ts
index 162ced5c017d..c17caeb6f3da 100644
--- a/src/scripts/control-ui-i18n.test.ts
+++ b/src/scripts/control-ui-i18n.test.ts
@@ -1,3 +1,4 @@
+// Control UI i18n script tests cover locale extraction and validation.
 import { describe, expect, it } from "vitest";
 import {
   findPlaceholderMismatches,
diff --git a/src/scripts/docs-link-audit.test.ts b/src/scripts/docs-link-audit.test.ts
index 3030027fc184..7707d079a231 100644
--- a/src/scripts/docs-link-audit.test.ts
+++ b/src/scripts/docs-link-audit.test.ts
@@ -1,3 +1,4 @@
+// Docs link audit tests cover documentation link validation behavior.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/scripts/prepare-codex-ci-auth.test.ts b/src/scripts/prepare-codex-ci-auth.test.ts
index 644d9c1b2f2c..4f89ca674c2d 100644
--- a/src/scripts/prepare-codex-ci-auth.test.ts
+++ b/src/scripts/prepare-codex-ci-auth.test.ts
@@ -1,3 +1,4 @@
+// Codex CI auth script tests cover generated auth fixture files.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/scripts/prepare-codex-ci-config.test.ts b/src/scripts/prepare-codex-ci-config.test.ts
index d38a35701cb5..61c75f44ad9e 100644
--- a/src/scripts/prepare-codex-ci-config.test.ts
+++ b/src/scripts/prepare-codex-ci-config.test.ts
@@ -1,3 +1,4 @@
+// Codex CI config script tests cover generated CI configuration files.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/scripts/sync-plugin-versions.test.ts b/src/scripts/sync-plugin-versions.test.ts
index 2680b0e959d6..2afe5d27d95c 100644
--- a/src/scripts/sync-plugin-versions.test.ts
+++ b/src/scripts/sync-plugin-versions.test.ts
@@ -1,3 +1,4 @@
+// Plugin version sync tests cover script updates to plugin package versions.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
diff --git a/src/scripts/test-live-media.test.ts b/src/scripts/test-live-media.test.ts
index 52858d338321..7fae8785d114 100644
--- a/src/scripts/test-live-media.test.ts
+++ b/src/scripts/test-live-media.test.ts
@@ -1,3 +1,4 @@
+// Live media script tests cover live media test command construction.
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 const loadShellEnvFallbackMock = vi.fn();
diff --git a/src/scripts/test-projects.test.ts b/src/scripts/test-projects.test.ts
index f12633b40fb6..e379c61c09af 100644
--- a/src/scripts/test-projects.test.ts
+++ b/src/scripts/test-projects.test.ts
@@ -1,3 +1,4 @@
+// Test project script tests cover fixture project discovery and validation.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/state/openclaw-agent-db.paths.ts b/src/state/openclaw-agent-db.paths.ts
index fbeedd723a27..53e4d8e41134 100644
--- a/src/state/openclaw-agent-db.paths.ts
+++ b/src/state/openclaw-agent-db.paths.ts
@@ -1,3 +1,4 @@
+// Agent database path helpers resolve per-agent persisted database paths.
 import path from "node:path";
 import { normalizeAgentId } from "../routing/session-key.js";
 import { resolveOpenClawStateSqliteDir } from "./openclaw-state-db.paths.js";
diff --git a/src/state/openclaw-agent-db.test.ts b/src/state/openclaw-agent-db.test.ts
index b5e8d3a87f1b..5fc40d1fc5f5 100644
--- a/src/state/openclaw-agent-db.test.ts
+++ b/src/state/openclaw-agent-db.test.ts
@@ -1,3 +1,4 @@
+// OpenClaw agent database tests cover agent-scoped DB storage and migrations.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/state/openclaw-agent-db.ts b/src/state/openclaw-agent-db.ts
index d944e53556ea..a5e8058e29fe 100644
--- a/src/state/openclaw-agent-db.ts
+++ b/src/state/openclaw-agent-db.ts
@@ -1,3 +1,4 @@
+// OpenClaw agent database stores agent-scoped persisted runtime state.
 import { chmodSync, existsSync, mkdirSync, statSync } from "node:fs";
 import path from "node:path";
 import type { DatabaseSync } from "node:sqlite";
diff --git a/src/state/openclaw-state-db.paths.ts b/src/state/openclaw-state-db.paths.ts
index 06ad1bdacb35..61c608c0d7c1 100644
--- a/src/state/openclaw-state-db.paths.ts
+++ b/src/state/openclaw-state-db.paths.ts
@@ -1,3 +1,4 @@
+// State database path helpers resolve shared OpenClaw state DB paths.
 import os from "node:os";
 import path from "node:path";
 import { isMainThread, threadId } from "node:worker_threads";
diff --git a/src/state/openclaw-state-db.test.ts b/src/state/openclaw-state-db.test.ts
index ee76d811303f..70b855ca79d4 100644
--- a/src/state/openclaw-state-db.test.ts
+++ b/src/state/openclaw-state-db.test.ts
@@ -1,3 +1,4 @@
+// OpenClaw state database tests cover state DB migrations and persistence.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/state/openclaw-state-db.ts b/src/state/openclaw-state-db.ts
index b7aed8566169..bb80151bffb8 100644
--- a/src/state/openclaw-state-db.ts
+++ b/src/state/openclaw-state-db.ts
@@ -1,3 +1,4 @@
+// OpenClaw state database manages shared persisted state and migrations.
 import { randomUUID } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync } from "node:fs";
 import path from "node:path";
diff --git a/src/state/sqlite-schema-shape.test-support.ts b/src/state/sqlite-schema-shape.test-support.ts
index db076737303c..2fad98197ef6 100644
--- a/src/state/sqlite-schema-shape.test-support.ts
+++ b/src/state/sqlite-schema-shape.test-support.ts
@@ -1,3 +1,4 @@
+// SQLite schema test support reads schema files for shape assertions.
 import { readFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 
diff --git a/src/test-helpers/network-interfaces.ts b/src/test-helpers/network-interfaces.ts
index 9300843c8fcd..0b93f3dae014 100644
--- a/src/test-helpers/network-interfaces.ts
+++ b/src/test-helpers/network-interfaces.ts
@@ -1,3 +1,4 @@
+// Network interface test helpers mock OS network interface state.
 import os from "node:os";
 import type { NetworkInterfacesSnapshot } from "../infra/network-interfaces.js";
 
diff --git a/src/test-helpers/resolve-target-error-cases.ts b/src/test-helpers/resolve-target-error-cases.ts
index 53e0f672d551..acdd344262e4 100644
--- a/src/test-helpers/resolve-target-error-cases.ts
+++ b/src/test-helpers/resolve-target-error-cases.ts
@@ -1,3 +1,4 @@
+// Resolve target error helpers share common route-target validation cases.
 import { expect, it } from "vitest";
 
 // Shared resolve-target negative cases used by messaging/channel tests. The
diff --git a/src/test-helpers/ssrf.ts b/src/test-helpers/ssrf.ts
index 5ed86849b8e9..a0e3bf03c449 100644
--- a/src/test-helpers/ssrf.ts
+++ b/src/test-helpers/ssrf.ts
@@ -1,3 +1,4 @@
+// SSRF test helpers mock network protections for request validation tests.
 import { vi } from "vitest";
 import { normalizeHostname } from "../infra/net/hostname.js";
 import * as ssrf from "../infra/net/ssrf.js";
diff --git a/src/test-helpers/state-dir-env.test.ts b/src/test-helpers/state-dir-env.test.ts
index 81e16913bc66..56b21a6befa4 100644
--- a/src/test-helpers/state-dir-env.test.ts
+++ b/src/test-helpers/state-dir-env.test.ts
@@ -1,3 +1,4 @@
+// State dir environment tests cover isolated state directory env helpers.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/test-helpers/state-dir-env.ts b/src/test-helpers/state-dir-env.ts
index 92d87286ec3c..bab7024e5ecb 100644
--- a/src/test-helpers/state-dir-env.ts
+++ b/src/test-helpers/state-dir-env.ts
@@ -1,3 +1,4 @@
+// State dir environment helpers isolate state paths during tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/test-helpers/temp-dir.test.ts b/src/test-helpers/temp-dir.test.ts
index 078c2894dc4d..4665f09ab646 100644
--- a/src/test-helpers/temp-dir.test.ts
+++ b/src/test-helpers/temp-dir.test.ts
@@ -1,3 +1,4 @@
+// Temporary directory helper tests cover temp directory cleanup behavior.
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
diff --git a/src/test-helpers/temp-dir.ts b/src/test-helpers/temp-dir.ts
index 55b92af95eff..17669c5b58d0 100644
--- a/src/test-helpers/temp-dir.ts
+++ b/src/test-helpers/temp-dir.ts
@@ -1,3 +1,4 @@
+// Temporary directory helpers create and clean up isolated test directories.
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
diff --git a/src/test-helpers/windows-cmd-shim.ts b/src/test-helpers/windows-cmd-shim.ts
index 40a8e09a895c..90f9424f536b 100644
--- a/src/test-helpers/windows-cmd-shim.ts
+++ b/src/test-helpers/windows-cmd-shim.ts
@@ -1,3 +1,4 @@
+// Windows command shim helpers create test shims for Windows command execution.
 import fs from "node:fs/promises";
 import path from "node:path";
 
diff --git a/src/test-helpers/workspace.ts b/src/test-helpers/workspace.ts
index 6df0bf141414..83d6b82748d3 100644
--- a/src/test-helpers/workspace.ts
+++ b/src/test-helpers/workspace.ts
@@ -1,3 +1,4 @@
+// Workspace test helpers build isolated workspace directories for tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";