docs: document secrets target registry

src/secrets/channel-secret-tts-runtime.ts

@@ -1,3 +1,4 @@
+/** Runtime adapter for channel text-to-speech secret contracts. */
 import type {
   ChannelAccountPredicate,
   ChannelAccountSurface,

src/secrets/command-config.test.ts

@@ -1,3 +1,4 @@
+/** Tests command-specific secret assignment collection from config snapshots. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {

src/secrets/command-config.ts

@@ -1,3 +1,4 @@
+/** Collects and analyzes command-scoped secret assignments from OpenClaw config. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { coerceSecretRef, resolveSecretInputRef } from "../config/types.secrets.js";
 import { getPath } from "./path-utils.js";
@@ -5,6 +6,7 @@ import { isExpectedResolvedSecretValue } from "./secret-value.js";
 import { discoverConfigSecretTargetsByIds } from "./target-registry.js";
 
 /** One resolved SecretRef value ready to inject into a command-scoped config view. */
+/** One command config path whose value can be resolved from a SecretRef. */
 export type CommandSecretAssignment = {
   path: string;
   pathSegments: string[];
@@ -34,6 +36,7 @@ export type AnalyzeAssignmentsFromSnapshotResult = {
 /**
  * Compares source SecretRefs with the active resolved snapshot for command-time assignments.
  */
+/** Analyzes command secret assignments without mutating the source config. */
 export function analyzeCommandSecretAssignmentsFromSnapshot(params: {
   sourceConfig: OpenClawConfig;
   resolvedConfig: OpenClawConfig;

src/secrets/config-io.ts

@@ -1,3 +1,4 @@
+/** Config IO adapter used by secrets apply/configure flows. */
 import { createConfigIO } from "../config/config.js";
 
 const silentConfigIoLogger = {

src/secrets/exec-resolution-policy.ts

@@ -1,3 +1,4 @@
+/** Applies exec-ref resolution policy for audit/apply modes. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { SecretRef } from "../config/types.secrets.js";
 import { formatExecSecretRefIdValidationMessage, isValidExecSecretRefId } from "./ref-contract.js";

src/secrets/json-pointer.test.ts

@@ -1,3 +1,4 @@
+/** Tests JSON Pointer helpers used by file-backed secret refs. */
 import { describe, expect, it } from "vitest";
 import { readJsonPointer } from "./json-pointer.js";
 

src/secrets/legacy-secretref-env-marker.ts

@@ -1,3 +1,4 @@
+/** Detects legacy SecretRef env markers in config values. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   LEGACY_SECRETREF_ENV_MARKER_PREFIX,

src/secrets/path-utils.ts

@@ -1,3 +1,4 @@
+/** Strict dotted-path get/set/delete helpers for secrets migration targets. */
 import { isDeepStrictEqual } from "node:util";
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
 import { isRecord } from "./shared.js";

src/secrets/provider-integrations.ts

@@ -1,3 +1,4 @@
+/** Materializes trusted plugin secret-provider integrations into exec provider configs. */
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -320,6 +321,7 @@ export function isPluginIntegrationSecretProviderConfig(
 }
 
 /** Materializes an active trusted plugin secret-provider integration into an exec provider. */
+/** Resolves a trusted plugin secret-provider integration into executable provider config. */
 export function resolveSecretProviderIntegrationConfig(params: {
   manifestRegistry: Pick<PluginManifestRegistry, "plugins">;
   providerAlias: string;

src/secrets/ref-contract.test.ts

@@ -1,3 +1,4 @@
+/** Tests secret ref id validation, labels, and provider alias contracts. */
 import { describe, expect, it } from "vitest";
 import {
   INVALID_FILE_SECRET_REF_IDS,

src/secrets/runtime-auth-collectors.ts

@@ -1,3 +1,4 @@
+/** Collects auth-profile and OAuth secret refs for runtime preparation. */
 import { assertNoOAuthSecretRefPolicyViolations } from "../agents/auth-profiles/policy.js";
 import type { AuthProfileCredential, AuthProfileStore } from "../agents/auth-profiles/types.js";
 import { resolveSecretInputRef } from "../config/types.secrets.js";

src/secrets/runtime-auth-profiles-oauth-policy.test.ts

@@ -1,3 +1,4 @@
+/** Tests OAuth policy handling while collecting auth-profile secrets. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {

src/secrets/runtime-auth-refresh-failure.test.ts

@@ -1,3 +1,4 @@
+/** Tests secrets runtime refresh failure handling for auth-profile stores. */
 import os from "node:os";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { withTempHome } from "../config/home-env.test-harness.js";

src/secrets/runtime-config-collectors-plugins.test.ts

@@ -1,3 +1,4 @@
+/** Tests plugin-specific runtime config secret collectors. */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type { PluginOrigin } from "../plugins/types.js";

src/secrets/runtime-config-collectors-plugins.ts

@@ -1,3 +1,4 @@
+/** Collects plugin config secret refs from runtime plugin metadata. */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -30,6 +31,7 @@ function parsePluginConfigArrayIndex(segment: string): number | undefined {
  * installed). This prevents resolution failures for SecretRefs belonging to
  * non-loadable plugins from blocking startup or preflight validation.
  */
+/** Collects SecretRef assignments from plugin-owned config contract paths. */
 export function collectPluginConfigAssignments(params: {
   /** Mutable config snapshot whose plugin config values will receive resolved secrets. */
   config: OpenClawConfig;

src/secrets/runtime-config-collectors-tts.ts

@@ -1,3 +1,4 @@
+/** Collects text-to-speech secret refs from runtime config. */
 import {
   collectSecretInputAssignment,
   type ResolverContext,

src/secrets/runtime-core-snapshots.test.ts

@@ -1,3 +1,4 @@
+/** Tests core secrets runtime snapshot preparation and activation behavior. */
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ensureAuthProfileStore } from "../agents/auth-profiles.js";
 import {

src/secrets/runtime-discord-surface.test.ts

@@ -1,3 +1,4 @@
+/** Tests Discord secret surfaces in runtime preparation. */
 import { describe, expect, it } from "vitest";
 import "./runtime-discord.test-support.ts";
 import {

src/secrets/runtime-external-channel-origin-discovery.test.ts

@@ -1,3 +1,4 @@
+/** Tests external channel origin discovery for secrets runtime loading. */
 import { describe, expect, it, vi } from "vitest";
 
 const { loadPluginMetadataSnapshotMock, loadChannelSecretContractApiMock } = vi.hoisted(() => ({

src/secrets/runtime-fast-path.ts

@@ -1,3 +1,4 @@
+/** Detects when secrets runtime preparation can safely use a fast path. */
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
@@ -199,6 +200,7 @@ function hasRuntimeWebToolConfigSurface(config: OpenClawConfig): boolean {
 /**
  * Returns whether a snapshot can skip full SecretRef/web-tool resolution.
  */
+/** Returns whether current config/auth/plugin state allows skipping full secret preparation. */
 export function canUseSecretsRuntimeFastPath(params: {
   sourceConfig: OpenClawConfig;
   authStores: Array<{ agentDir: string; store: AuthProfileStore }>;

src/secrets/runtime-gateway-auth-surfaces.ts

@@ -1,3 +1,4 @@
+/** Collects Gateway auth secret surfaces for secrets runtime preparation. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createGatewayCredentialPlan } from "../gateway/credential-planner.js";
 import type { SecretDefaults } from "./runtime-shared.js";

src/secrets/runtime-shared.ts

@@ -1,3 +1,4 @@
+/** Shared secrets runtime resolver context, assignments, and warning helpers. */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { coerceSecretRef, type SecretRef } from "../config/types.secrets.js";
 import type { PluginManifestRegistry } from "../plugins/manifest-registry.js";

src/secrets/runtime-web-tools.test.ts

@@ -1,3 +1,4 @@
+/** Tests web-tool secret metadata resolution from config and plugins. */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type {

src/secrets/runtime.coverage.test.ts

@@ -1,3 +1,4 @@
+/** Coverage tests for secrets runtime collector breadth and target surfaces. */
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";

src/secrets/runtime.fast-path.test.ts

@@ -1,3 +1,4 @@
+/** Tests secrets runtime fast-path decisions and skip conditions. */
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";

src/secrets/runtime.gateway-auth.integration.test.ts

@@ -1,3 +1,4 @@
+/** Integration tests for Gateway auth secret surfaces in the secrets runtime. */
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

src/secrets/runtime.ts

@@ -1,3 +1,4 @@
+/** Prepares secrets runtime snapshots from config, auth stores, plugins, and env. */
 import { isDeepStrictEqual } from "node:util";
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope-config.js";
@@ -115,6 +116,7 @@ function shouldLoadPluginMetadataForSecrets(config: OpenClawConfig): boolean {
   );
 }
 
+/** Prepares a secrets runtime snapshot and records refresh context for later activation. */
 export async function prepareSecretsRuntimeSnapshot(params: {
   config: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
@@ -250,6 +252,7 @@ export async function prepareSecretsRuntimeSnapshot(params: {
   return snapshot;
 }
 
+/** Activates a prepared secrets runtime snapshot for fast runtime lookup. */
 export function activateSecretsRuntimeSnapshot(snapshot: PreparedSecretsRuntimeSnapshot): void {
   const refreshContext =
     getPreparedSecretsRuntimeSnapshotRefreshContext(snapshot) ??

src/secrets/shared.ts

@@ -1,3 +1,4 @@
+/** Shared parsing and file helpers for secrets migration/runtime code. */
 import fs from "node:fs";
 import path from "node:path";
 import { privateFileStoreSync } from "../infra/private-file-store.js";

src/secrets/target-registry-data.ts

@@ -1,3 +1,4 @@
+/** Builds the static and plugin-derived registry of secret migration targets. */
 import type { PluginManifestRecord } from "../plugins/manifest-registry.js";
 import { resolvePluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import { loadChannelSecretContractApiForRecord } from "./channel-contract-api.js";
@@ -484,11 +485,13 @@ function loadSecretTargetRegistryFromPluginMetadata(params: {
 }
 
 /** Returns only core-owned secret target registry entries. */
+/** Returns static core secret target registry entries without plugin-derived targets. */
 export function getCoreSecretTargetRegistry(): SecretTargetRegistryEntry[] {
   return CORE_SECRET_TARGET_REGISTRY;
 }
 
 /** Returns the process-cached registry including bundled plugin/channel metadata. */
+/** Returns core plus plugin/channel secret target registry entries for the current metadata view. */
 export function getSecretTargetRegistry(): SecretTargetRegistryEntry[] {
   if (cachedSecretTargetRegistry) {
     return cachedSecretTargetRegistry;

src/secrets/target-registry-pattern.test.ts

@@ -1,3 +1,4 @@
+/** Tests secret target registry pattern compile/match/expand behavior. */
 import { describe, expect, it } from "vitest";
 import {
   expandPathTokens,

src/secrets/target-registry-pattern.ts

@@ -1,3 +1,4 @@
+/** Compiles, matches, and expands secret target registry path patterns. */
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
 import { isRecord, parseDotPath } from "./shared.js";
 import type { SecretTargetRegistryEntry } from "./target-registry-types.js";

src/secrets/target-registry.docs.test.ts

@@ -1,3 +1,4 @@
+/** Verifies docs stay aligned with the secret target registry. */
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";

src/secrets/unsupported-surface-policy.ts

@@ -1,3 +1,4 @@
+/** Defines unsupported secret-ref surfaces and operator-facing policy messages. */
 import { GENERATED_BUNDLED_CHANNEL_CONFIG_METADATA } from "../config/bundled-channel-config-metadata.generated.js";
 import { isRecord } from "../utils.js";