docs: document plugin catalog install helpers

src/plugins/api-facades.ts

@@ -4,6 +4,7 @@ type PluginApiFacadeFields = Pick<
   OpenClawPluginApi,
   "agent" | "lifecycle" | "runContext" | "session"
 >;
+/** Plugin API shape without nested facade namespaces attached. */
 export type OpenClawPluginApiWithoutFacades = Omit<OpenClawPluginApi, keyof PluginApiFacadeFields>;
 type PluginApiFacadeSource = Pick<
   OpenClawPluginApi,
@@ -23,6 +24,7 @@ type PluginApiFacadeSource = Pick<
   | "unscheduleSessionTurnsByTag"
 >;
 
+/** Attaches nested facade namespaces to the flat plugin API implementation. */
 export function attachPluginApiFacades<T extends object>(
   api: T & PluginApiFacadeSource & Partial<PluginApiFacadeFields>,
 ): T & PluginApiFacadeFields {

src/plugins/clawhub-install-records.ts

@@ -1,6 +1,7 @@
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import type { ClawHubPackageChannel, ClawHubPackageFamily } from "../infra/clawhub.js";
 
+/** Install record fields captured for ClawHub plugin installs. */
 export type ClawHubPluginInstallRecordFields = {
   source: "clawhub";
   clawhubUrl: string;
@@ -22,6 +23,7 @@ export type ClawHubPluginInstallRecordFields = {
   clawpackSize?: number;
 };
 
+/** Builds plugin install record fields from resolved ClawHub package metadata. */
 export function buildClawHubPluginInstallRecordFields(
   fields: ClawHubPluginInstallRecordFields,
 ): Pick<

src/plugins/installed-plugin-index-registry.ts

@@ -8,6 +8,7 @@ import { loadInstalledPluginIndexInstallRecordsSync } from "./installed-plugin-i
 import type { LoadInstalledPluginIndexParams } from "./installed-plugin-index-types.js";
 import { loadPluginManifestRegistry, type PluginManifestRegistry } from "./manifest-registry.js";
 
+/** Resolves discovery candidates and manifest registry for installed plugin index loading. */
 export function resolveInstalledPluginIndexRegistry(params: LoadInstalledPluginIndexParams): {
   registry: PluginManifestRegistry;
   candidates: readonly PluginCandidate[];

src/plugins/model-catalog-registration.ts

@@ -7,13 +7,13 @@ import {
   type MediaGenerationCatalogKind,
   type MediaGenerationCatalogProvider,
 } from "../../packages/media-generation-core/src/catalog.js";
+import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
+import { uniqueValues } from "../../packages/normalization-core/src/string-normalization.js";
 import {
   synthesizeVoiceModelCatalogEntries,
   type VoiceModelCapabilities,
   type VoiceModelProvider,
 } from "../../packages/speech-core/voice-models.js";
-import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js";
-import { uniqueValues } from "../../packages/normalization-core/src/string-normalization.js";
 import type { PluginDiagnostic } from "./manifest-types.js";
 import { projectProviderCatalogResultToUnifiedTextRows } from "./provider-catalog-unified-text.js";
 import type { PluginRecord, PluginRegistry } from "./registry-types.js";
@@ -58,6 +58,7 @@ function mergeModelCatalogHooks(
   };
 }
 
+/** Creates handlers that register plugin model catalog providers into a registry. */
 export function createModelCatalogRegistrationHandlers(params: {
   registry: PluginRegistry;
   pushDiagnostic: (diagnostic: PluginDiagnostic) => void;

src/plugins/openai-compatible-embedding-provider.ts

@@ -11,9 +11,11 @@ import type {
   EmbeddingProviderCreateOptions,
 } from "./embedding-provider-types.js";
 
+/** Provider id for OpenAI-compatible remote embedding servers. */
 export const OPENAI_COMPATIBLE_EMBEDDING_PROVIDER_ID = "openai-compatible";
 const OPENAI_COMPATIBLE_MODEL_APIS = new Set(["openai-completions", "openai-responses"]);
 
+/** Normalized OpenAI-compatible embedding client configuration. */
 export type OpenAICompatibleEmbeddingClient = {
   baseUrl: string;
   headers: Record<string, string>;
@@ -326,6 +328,7 @@ async function postEmbeddingRequest(params: {
   }
 }
 
+/** Creates a normalized OpenAI-compatible embedding client from runtime config. */
 export async function createOpenAICompatibleEmbeddingClient(
   options: EmbeddingProviderCreateOptions,
 ): Promise<OpenAICompatibleEmbeddingClient> {
@@ -362,6 +365,7 @@ export async function createOpenAICompatibleEmbeddingClient(
   };
 }
 
+/** Creates an OpenAI-compatible embedding provider and its backing client. */
 export async function createOpenAICompatibleEmbeddingProvider(
   options: EmbeddingProviderCreateOptions,
 ): Promise<{
@@ -398,6 +402,7 @@ export async function createOpenAICompatibleEmbeddingProvider(
   };
 }
 
+/** Embedding provider adapter for OpenAI-compatible remote embedding APIs. */
 export const openAICompatibleEmbeddingProviderAdapter: EmbeddingProviderAdapter = {
   id: OPENAI_COMPATIBLE_EMBEDDING_PROVIDER_ID,
   transport: "remote",

src/plugins/provider-install-catalog.ts

@@ -24,6 +24,7 @@ import {
   type ProviderAuthChoiceMetadata,
 } from "./provider-auth-choices.js";
 
+/** Provider setup choice paired with install metadata for the owning plugin. */
 export type ProviderInstallCatalogEntry = ProviderAuthChoiceMetadata & {
   label: string;
   origin: PluginOrigin;
@@ -369,6 +370,7 @@ function resolveOfficialExternalProviderInstallCatalogEntries(params: {
   return entries;
 }
 
+/** Lists install catalog entries for provider setup choices. */
 export function resolveProviderInstallCatalogEntries(
   params?: ProviderInstallCatalogParams,
 ): ProviderInstallCatalogEntry[] {
@@ -411,6 +413,7 @@ export function resolveProviderInstallCatalogEntries(
   );
 }
 
+/** Resolves one provider install catalog entry by setup choice id. */
 export function resolveProviderInstallCatalogEntry(
   choiceId: string,
   params?: ProviderInstallCatalogParams,

src/plugins/provider-model-primary.ts

@@ -15,6 +15,7 @@ function resolvePrimaryModel(model?: AgentModelListConfig | string): string | un
   return undefined;
 }
 
+/** Applies an agent default primary model and reports whether config changed. */
 export function applyAgentDefaultPrimaryModel(params: {
   cfg: OpenClawConfig;
   model: string;
@@ -49,6 +50,7 @@ export function applyAgentDefaultPrimaryModel(params: {
   };
 }
 
+/** Applies a primary model to agent defaults while preserving model fallback metadata. */
 export function applyPrimaryModel(cfg: OpenClawConfig, model: string): OpenClawConfig {
   const normalizedModel = normalizeAgentModelRefForConfig(model);
   const defaults = cfg.agents?.defaults;

src/plugins/validation-diagnostics.ts

@@ -1,5 +1,6 @@
 import type { PluginDiagnostic } from "./manifest-types.js";
 
+/** Pushes a normalized plugin validation diagnostic. */
 export function pushPluginValidationDiagnostic(params: {
   level: PluginDiagnostic["level"];
   pluginId: string;