From 7c1deea5fae07c7e290bcc0701f424d450e24516 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 04:54:37 -0400
Subject: [PATCH] docs: document plugin setup state

---
 src/plugins/activation-planner.test.ts                | 1 +
 src/plugins/bundled-compat.ts                         | 3 +++
 src/plugins/cli-backend.types.ts                      | 1 +
 src/plugins/cli-gateway-nodes-runtime.test.ts         | 1 +
 src/plugins/cli.test.ts                               | 1 +
 src/plugins/config-state.ts                           | 2 ++
 src/plugins/effective-plugin-ids.ts                   | 2 ++
 src/plugins/embedding-provider-runtime-shared.ts      | 1 +
 src/plugins/hook-agent-context.ts                     | 1 +
 src/plugins/host-hook-cleanup.ts                      | 3 +++
 src/plugins/host-hook-runtime.ts                      | 3 +++
 src/plugins/manifest-contract-runtime.test.ts         | 1 +
 src/plugins/manifest-owner-policy.ts                  | 1 +
 src/plugins/memory-state.ts                           | 1 +
 src/plugins/npm-install-security-scan.release.test.ts | 1 +
 src/plugins/plugin-lookup-table.test.ts               | 1 +
 src/plugins/provider-api-key-auth.ts                  | 1 +
 src/plugins/registry.provider-like.test.ts            | 1 +
 src/plugins/setup-registry.runtime.ts                 | 2 ++
 src/plugins/web-search-providers.runtime.test.ts      | 1 +
 20 files changed, 29 insertions(+)

diff --git a/src/plugins/activation-planner.test.ts b/src/plugins/activation-planner.test.ts
index d24ee919193f..2dd6b4a397e1 100644
--- a/src/plugins/activation-planner.test.ts
+++ b/src/plugins/activation-planner.test.ts
@@ -1,3 +1,4 @@
+/** Tests manifest activation planning for commands, providers, channels, and capabilities. */
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
diff --git a/src/plugins/bundled-compat.ts b/src/plugins/bundled-compat.ts
index 179766393e33..e490030bc4d4 100644
--- a/src/plugins/bundled-compat.ts
+++ b/src/plugins/bundled-compat.ts
@@ -1,8 +1,10 @@
+/** Compatibility helpers that auto-enable bundled plugins for legacy and Vitest flows. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { PluginEntryConfig } from "../config/types.plugins.js";
 import { hasExplicitPluginConfig } from "./config-policy.js";
 import { normalizePluginId } from "./config-state.js";
 
+/** Returns config with selected bundled plugins explicitly enabled when compat rules require it. */
 export function withBundledPluginEnablementCompat(params: {
   config: OpenClawConfig | undefined;
   pluginIds: readonly string[];
@@ -57,6 +59,7 @@ export function withBundledPluginEnablementCompat(params: {
   };
 }
 
+/** Enables bundled plugins in Vitest when tests did not provide explicit plugin config. */
 export function withBundledPluginVitestCompat(params: {
   config: OpenClawConfig | undefined;
   pluginIds: readonly string[];
diff --git a/src/plugins/cli-backend.types.ts b/src/plugins/cli-backend.types.ts
index e154d0b67125..8cf042c66e2a 100644
--- a/src/plugins/cli-backend.types.ts
+++ b/src/plugins/cli-backend.types.ts
@@ -1,3 +1,4 @@
+/** Type contracts for plugin-owned CLI backend integrations. */
 import type { CliBackendConfig } from "../config/types.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ContextEngineHostCapability } from "../context-engine/types.js";
diff --git a/src/plugins/cli-gateway-nodes-runtime.test.ts b/src/plugins/cli-gateway-nodes-runtime.test.ts
index b9c6f42cd003..9c49e937f612 100644
--- a/src/plugins/cli-gateway-nodes-runtime.test.ts
+++ b/src/plugins/cli-gateway-nodes-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests plugin CLI node Gateway runtime timeout and invocation behavior. */
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
diff --git a/src/plugins/cli.test.ts b/src/plugins/cli.test.ts
index 6bdda64a196a..f46f73424f81 100644
--- a/src/plugins/cli.test.ts
+++ b/src/plugins/cli.test.ts
@@ -1,3 +1,4 @@
+/** CLI integration coverage for plugin commands, setup, status, and registry flows. */
 import { Command } from "commander";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
diff --git a/src/plugins/config-state.ts b/src/plugins/config-state.ts
index 7df6d7185ff8..3a4d64a22630 100644
--- a/src/plugins/config-state.ts
+++ b/src/plugins/config-state.ts
@@ -1,3 +1,4 @@
+/** Normalizes plugin config and resolves effective enablement, slots, and activation sources. */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -73,6 +74,7 @@ function createScopedPluginIdNormalizer(): NormalizePluginId {
     });
 }
 
+/** Normalizes user/config plugin ids into the canonical lowercase key form. */
 export function normalizePluginId(id: string): string {
   return normalizePluginIdWithLookup(id, getBundledPluginAliasLookup);
 }
diff --git a/src/plugins/effective-plugin-ids.ts b/src/plugins/effective-plugin-ids.ts
index 644c1c4af2d4..b89f98444a33 100644
--- a/src/plugins/effective-plugin-ids.ts
+++ b/src/plugins/effective-plugin-ids.ts
@@ -1,3 +1,4 @@
+/** Resolves effective plugin ids from config, installed records, and activation metadata. */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import {
@@ -140,6 +141,7 @@ function collectSelectedContextEnginePluginIds(config: OpenClawConfig): string[]
   return [pluginId];
 }
 
+/** Lists plugin ids that are effectively enabled for a config/discovery context. */
 export function resolveEffectivePluginIds(params: {
   config: OpenClawConfig;
   env: NodeJS.ProcessEnv;
diff --git a/src/plugins/embedding-provider-runtime-shared.ts b/src/plugins/embedding-provider-runtime-shared.ts
index 52a4d994aa85..29d5cbea0959 100644
--- a/src/plugins/embedding-provider-runtime-shared.ts
+++ b/src/plugins/embedding-provider-runtime-shared.ts
@@ -1,3 +1,4 @@
+/** Shared runtime helpers for embedding provider lookup across core and plugin capabilities. */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/plugins/hook-agent-context.ts b/src/plugins/hook-agent-context.ts
index ead306d05b92..a4befa0f62e7 100644
--- a/src/plugins/hook-agent-context.ts
+++ b/src/plugins/hook-agent-context.ts
@@ -1,3 +1,4 @@
+/** Builds plugin hook agent context snapshots from active session and model state. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { parseRawSessionConversationRef } from "../sessions/session-key-utils.js";
 import type { PluginHookAgentContext } from "./hook-types.js";
diff --git a/src/plugins/host-hook-cleanup.ts b/src/plugins/host-hook-cleanup.ts
index a107cc799b0f..3e07ad2ab10a 100644
--- a/src/plugins/host-hook-cleanup.ts
+++ b/src/plugins/host-hook-cleanup.ts
@@ -1,3 +1,4 @@
+/** Runs plugin cleanup callbacks and clears host-side plugin session/runtime state. */
 import fs from "node:fs";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { getRuntimeConfig } from "../config/config.js";
@@ -17,6 +18,7 @@ import { getActivePluginRegistry } from "./runtime.js";
 import { normalizeSessionEntrySlotKey } from "./session-entry-slot-keys.js";
 
 /** Failure captured while running plugin cleanup hooks. */
+/** Failure captured while running one plugin cleanup callback. */
 export type PluginHostCleanupFailure = {
   pluginId: string;
   hookId: string;
@@ -344,6 +346,7 @@ function collectSessionEntrySlotKeys(
 }
 
 /** Runs persistent and in-memory cleanup for a plugin, session, or host lifecycle event. */
+/** Runs cleanup callbacks for one plugin and returns failures instead of throwing. */
 export async function runPluginHostCleanup(params: {
   cfg?: OpenClawConfig;
   registry?: PluginRegistry | null;
diff --git a/src/plugins/host-hook-runtime.ts b/src/plugins/host-hook-runtime.ts
index bf26723edd35..ad7cba3763e8 100644
--- a/src/plugins/host-hook-runtime.ts
+++ b/src/plugins/host-hook-runtime.ts
@@ -1,3 +1,4 @@
+/** Stores plugin host-hook run context, scheduler jobs, and pending event cleanup state. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { AgentEventPayload } from "../infra/agent-events.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
@@ -168,6 +169,7 @@ function getPluginRunContextNamespaces(params: {
   return namespaces;
 }
 
+/** Stores JSON-compatible plugin run context for one run/plugin/namespace tuple. */
 export function setPluginRunContext(params: {
   pluginId: string;
   patch: PluginRunContextPatch;
@@ -208,6 +210,7 @@ export function setPluginRunContext(params: {
 }
 
 // oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- Run-context JSON reads are caller-typed by namespace.
+/** Reads previously stored plugin run context for one run/plugin/namespace tuple. */
 export function getPluginRunContext<T extends PluginJsonValue = PluginJsonValue>(params: {
   pluginId: string;
   get: PluginRunContextGetParams;
diff --git a/src/plugins/manifest-contract-runtime.test.ts b/src/plugins/manifest-contract-runtime.test.ts
index 3448262f962e..d25e28e6439a 100644
--- a/src/plugins/manifest-contract-runtime.test.ts
+++ b/src/plugins/manifest-contract-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests manifest contract runtime resolution across bundled and installed plugin metadata. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const loadPluginMetadataSnapshot = vi.hoisted(() => vi.fn());
diff --git a/src/plugins/manifest-owner-policy.ts b/src/plugins/manifest-owner-policy.ts
index cff88f95df30..41b7c14241c3 100644
--- a/src/plugins/manifest-owner-policy.ts
+++ b/src/plugins/manifest-owner-policy.ts
@@ -1,3 +1,4 @@
+/** Applies manifest owner policy for plugin availability and activation decisions. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { normalizePluginsConfig, resolveEffectivePluginActivationState } from "./config-state.js";
 import { isPluginEnabledByDefaultForPlatform } from "./default-enablement.js";
diff --git a/src/plugins/memory-state.ts b/src/plugins/memory-state.ts
index 860146f35bd7..cd0eedf4c6b0 100644
--- a/src/plugins/memory-state.ts
+++ b/src/plugins/memory-state.ts
@@ -1,3 +1,4 @@
+/** Registry state for plugin memory runtimes, prompt supplements, and flush planning. */
 import type { MemoryCitationsMode } from "../config/types.memory.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { MemorySearchManager } from "../memory-host-sdk/host/types.js";
diff --git a/src/plugins/npm-install-security-scan.release.test.ts b/src/plugins/npm-install-security-scan.release.test.ts
index 30208142c128..7724d06ecfc2 100644
--- a/src/plugins/npm-install-security-scan.release.test.ts
+++ b/src/plugins/npm-install-security-scan.release.test.ts
@@ -1,3 +1,4 @@
+/** Release-lane coverage for npm plugin install security scanning. */
 import { execFile, spawnSync } from "node:child_process";
 import fs, { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
diff --git a/src/plugins/plugin-lookup-table.test.ts b/src/plugins/plugin-lookup-table.test.ts
index 086b177a611e..d1d411c1bb4c 100644
--- a/src/plugins/plugin-lookup-table.test.ts
+++ b/src/plugins/plugin-lookup-table.test.ts
@@ -1,3 +1,4 @@
+/** Tests plugin lookup table indexing for manifest-owned contribution ids. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveInstalledPluginIndexPolicyHash } from "./installed-plugin-index-policy.js";
diff --git a/src/plugins/provider-api-key-auth.ts b/src/plugins/provider-api-key-auth.ts
index 14d5f59a4677..1edb77678c1e 100644
--- a/src/plugins/provider-api-key-auth.ts
+++ b/src/plugins/provider-api-key-auth.ts
@@ -1,3 +1,4 @@
+/** Builds API-key provider auth methods that write profiles and config updates. */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { upsertAuthProfileWithLock } from "../agents/auth-profiles/profiles.js";
diff --git a/src/plugins/registry.provider-like.test.ts b/src/plugins/registry.provider-like.test.ts
index 00e6c2a72c8b..65215f097846 100644
--- a/src/plugins/registry.provider-like.test.ts
+++ b/src/plugins/registry.provider-like.test.ts
@@ -1,3 +1,4 @@
+/** Verifies provider-like plugin registry entries across capability families. */
 import { describe, expect, it } from "vitest";
 import { createPluginRecord } from "./loader-records.js";
 import { createPluginRegistry } from "./registry.js";
diff --git a/src/plugins/setup-registry.runtime.ts b/src/plugins/setup-registry.runtime.ts
index 3a63a746fad2..0eaadb8aa93d 100644
--- a/src/plugins/setup-registry.runtime.ts
+++ b/src/plugins/setup-registry.runtime.ts
@@ -1,3 +1,4 @@
+/** Runtime lookup helpers for plugin setup CLI backend descriptors. */
 import { createRequire } from "node:module";
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -39,6 +40,7 @@ let setupRegistryRuntimeModule: SetupRegistryRuntimeModule | null | undefined;
 let cachedSetupCliBackendDescriptors: SetupCliBackendDescriptorCache | undefined;
 let cachedBundledSetupCliBackends: SetupCliBackendDescriptorCache | undefined;
 
+/** Test hooks for resetting setup-registry runtime module caches. */
 export const testing = {
   resetRuntimeState(): void {
     setupRegistryRuntimeModule = undefined;
diff --git a/src/plugins/web-search-providers.runtime.test.ts b/src/plugins/web-search-providers.runtime.test.ts
index 87ac5625d441..293ebbc43e0c 100644
--- a/src/plugins/web-search-providers.runtime.test.ts
+++ b/src/plugins/web-search-providers.runtime.test.ts
@@ -1,3 +1,4 @@
+/** Covers runtime loading and sorting for plugin web search providers. */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 type RegistryModule = typeof import("./registry.js");