diff --git a/packages/media-generation-core/src/catalog.ts b/packages/media-generation-core/src/catalog.ts
index 2619311aff75..2a9c5d53f253 100644
--- a/packages/media-generation-core/src/catalog.ts
+++ b/packages/media-generation-core/src/catalog.ts
@@ -1,12 +1,17 @@
 import { uniqueTrimmedStrings } from "./string.js";
 
+// Shared media-generation catalog contracts and static entry synthesis.
+
+/** Catalog kind for generated media model entries. */
 export type MediaGenerationCatalogKind =
   | "image_generation"
   | "video_generation"
   | "music_generation";
 
+/** Source for a media generation catalog entry. */
 export type MediaGenerationCatalogSource = "static" | "live" | "cache" | "configured";
 
+/** Media generation model catalog entry. */
 export type MediaGenerationCatalogEntry<TCapabilities = unknown> = {
   kind: MediaGenerationCatalogKind;
   provider: string;
@@ -24,6 +29,7 @@ export type MediaGenerationCatalogEntry<TCapabilities = unknown> = {
   warnings?: readonly string[];
 };
 
+/** Provider metadata used to synthesize static media generation catalog entries. */
 export type MediaGenerationCatalogProvider<TCapabilities = unknown> = {
   id: string;
   aliases?: readonly string[];
@@ -33,10 +39,12 @@ export type MediaGenerationCatalogProvider<TCapabilities = unknown> = {
   capabilities: TCapabilities;
 };
 
+/** Return unique configured models with default model first when present. */
 function uniqueModels(provider: { defaultModel?: string; models?: readonly string[] }): string[] {
   return uniqueTrimmedStrings([provider.defaultModel, ...(provider.models ?? [])]);
 }
 
+/** Synthesize static catalog entries from provider metadata. */
 export function synthesizeMediaGenerationCatalogEntries<TCapabilities>(params: {
   kind: MediaGenerationCatalogKind;
   provider: MediaGenerationCatalogProvider<TCapabilities>;
@@ -63,6 +71,7 @@ export function synthesizeMediaGenerationCatalogEntries<TCapabilities>(params: {
   });
 }
 
+/** Return unique model ids exposed by a media generation provider. */
 export function listMediaGenerationProviderModels(provider: {
   defaultModel?: string;
   models?: readonly string[];
diff --git a/packages/media-generation-core/src/index.ts b/packages/media-generation-core/src/index.ts
index a716b439172e..570bd88c9d0e 100644
--- a/packages/media-generation-core/src/index.ts
+++ b/packages/media-generation-core/src/index.ts
@@ -1,3 +1,5 @@
+// Public barrel for media-generation shared model refs and catalog helpers.
+
 export * from "./capability-model-ref.js";
 export * from "./catalog.js";
 export * from "./model-ref.js";
diff --git a/packages/media-generation-core/src/string.ts b/packages/media-generation-core/src/string.ts
index f830769126a8..be51a14206af 100644
--- a/packages/media-generation-core/src/string.ts
+++ b/packages/media-generation-core/src/string.ts
@@ -1,3 +1,6 @@
+// Shared string normalization helpers for media-generation packages.
+
+/** Normalize optional strings, returning undefined for non-strings or empty values. */
 export function normalizeOptionalString(value: unknown): string | undefined {
   if (typeof value !== "string") {
     return undefined;
@@ -6,6 +9,7 @@ export function normalizeOptionalString(value: unknown): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+/** Return unique trimmed strings while preserving first-seen order. */
 export function uniqueTrimmedStrings(values: readonly unknown[]): string[] {
   const seen = new Set<string>();
   const result: string[] = [];
diff --git a/packages/media-understanding-common/src/active-model.ts b/packages/media-understanding-common/src/active-model.ts
index 2782c4702a15..0c52e5fd10e0 100644
--- a/packages/media-understanding-common/src/active-model.ts
+++ b/packages/media-understanding-common/src/active-model.ts
@@ -1,3 +1,6 @@
+// Active media-understanding model selection contract.
+
+/** Provider/model pair selected for one media-understanding request. */
 export type ActiveMediaModel = {
   provider: string;
   model?: string;
diff --git a/packages/media-understanding-common/src/defaults.ts b/packages/media-understanding-common/src/defaults.ts
index 2dc0c119d987..fbb8db16f453 100644
--- a/packages/media-understanding-common/src/defaults.ts
+++ b/packages/media-understanding-common/src/defaults.ts
@@ -1,8 +1,12 @@
 import type { MediaUnderstandingCapability } from "./types.js";
 
+// Shared defaults for media-understanding limits, prompts, and concurrency.
+
 const MB = 1024 * 1024;
 
+/** Default max response characters for bounded text outputs. */
 export const DEFAULT_MAX_CHARS = 500;
+/** Default max response characters by capability. */
 export const DEFAULT_MAX_CHARS_BY_CAPABILITY: Record<
   MediaUnderstandingCapability,
   number | undefined
@@ -11,22 +15,29 @@ export const DEFAULT_MAX_CHARS_BY_CAPABILITY: Record<
   audio: undefined,
   video: DEFAULT_MAX_CHARS,
 };
+/** Default input byte limits by capability. */
 export const DEFAULT_MAX_BYTES: Record<MediaUnderstandingCapability, number> = {
   image: 10 * MB,
   audio: 20 * MB,
   video: 50 * MB,
 };
+/** Default request timeout by capability. */
 export const DEFAULT_TIMEOUT_SECONDS: Record<MediaUnderstandingCapability, number> = {
   image: 60,
   audio: 60,
   video: 120,
 };
+/** Default prompts by capability. */
 export const DEFAULT_PROMPT: Record<MediaUnderstandingCapability, string> = {
   image: "Describe the image.",
   audio: "Transcribe the audio.",
   video: "Describe the video.",
 };
+/** Upper bound for base64-expanded video payloads. */
 export const DEFAULT_VIDEO_MAX_BASE64_BYTES = 70 * MB;
+/** CLI output buffer used by provider child processes. */
 export const CLI_OUTPUT_MAX_BUFFER = 5 * MB;
+/** Default parallel media-understanding request count. */
 export const DEFAULT_MEDIA_CONCURRENCY = 2;
+/** Minimum bytes for audio files before transcription is attempted. */
 export const MIN_AUDIO_FILE_BYTES = 1024;
diff --git a/packages/media-understanding-common/src/errors.ts b/packages/media-understanding-common/src/errors.ts
index e6475f722c7a..06af240e4556 100644
--- a/packages/media-understanding-common/src/errors.ts
+++ b/packages/media-understanding-common/src/errors.ts
@@ -1,3 +1,6 @@
+// Media-understanding skip error used for non-fatal attachment omissions.
+
+/** Reason a media-understanding attachment was skipped. */
 type MediaUnderstandingSkipReason =
   | "maxBytes"
   | "timeout"
@@ -6,6 +9,7 @@ type MediaUnderstandingSkipReason =
   | "blocked"
   | "tooSmall";
 
+/** Error used when a media attachment should be skipped without failing the whole request. */
 export class MediaUnderstandingSkipError extends Error {
   readonly reason: MediaUnderstandingSkipReason;
 
@@ -16,6 +20,7 @@ export class MediaUnderstandingSkipError extends Error {
   }
 }
 
+/** Narrow unknown errors to media-understanding skip errors. */
 export function isMediaUnderstandingSkipError(err: unknown): err is MediaUnderstandingSkipError {
   return err instanceof MediaUnderstandingSkipError;
 }
diff --git a/packages/media-understanding-common/src/index.ts b/packages/media-understanding-common/src/index.ts
index a709601cac9a..4e40d49559cc 100644
--- a/packages/media-understanding-common/src/index.ts
+++ b/packages/media-understanding-common/src/index.ts
@@ -1,3 +1,5 @@
+// Public barrel for media-understanding shared contracts and helpers.
+
 export * from "./active-model.js";
 export * from "./defaults.js";
 export * from "./errors.js";
diff --git a/packages/media-understanding-common/src/openai-compatible-video.ts b/packages/media-understanding-common/src/openai-compatible-video.ts
index d1a43ff36a63..f1579475d4e9 100644
--- a/packages/media-understanding-common/src/openai-compatible-video.ts
+++ b/packages/media-understanding-common/src/openai-compatible-video.ts
@@ -1,3 +1,6 @@
+// OpenAI-compatible video request/response helpers.
+
+/** Minimal OpenAI-compatible video response payload shape. */
 export type OpenAiCompatibleVideoPayload = {
   choices?: Array<{
     message?: {
@@ -7,6 +10,7 @@ export type OpenAiCompatibleVideoPayload = {
   }>;
 };
 
+/** Trim optional strings, falling back when empty. */
 export function resolveMediaUnderstandingString(
   value: string | undefined,
   fallback: string,
@@ -15,6 +19,7 @@ export function resolveMediaUnderstandingString(
   return trimmed || fallback;
 }
 
+/** Coerce text from OpenAI-compatible content or reasoning fields. */
 export function coerceOpenAiCompatibleVideoText(
   payload: OpenAiCompatibleVideoPayload,
 ): string | null {
@@ -40,6 +45,7 @@ export function coerceOpenAiCompatibleVideoText(
   return null;
 }
 
+/** Build an OpenAI-compatible request body with an inline data URL video. */
 export function buildOpenAiCompatibleVideoRequestBody(params: {
   model: string;
   prompt: string;
diff --git a/packages/media-understanding-common/src/output-extract.ts b/packages/media-understanding-common/src/output-extract.ts
index a0f0f391379b..9b7cffea0e14 100644
--- a/packages/media-understanding-common/src/output-extract.ts
+++ b/packages/media-understanding-common/src/output-extract.ts
@@ -1,3 +1,6 @@
+// Output extractors for media-understanding provider CLI responses.
+
+/** Parse the last JSON object in a noisy provider output string. */
 function extractLastJsonObject(raw: string): unknown {
   const trimmed = raw.trim();
   const start = trimmed.lastIndexOf("{");
@@ -12,6 +15,7 @@ function extractLastJsonObject(raw: string): unknown {
   }
 }
 
+/** Extract Gemini CLI-style response text from the last JSON object in output. */
 export function extractGeminiResponse(raw: string): string | null {
   const payload = extractLastJsonObject(raw);
   if (!payload || typeof payload !== "object") {
diff --git a/packages/media-understanding-common/src/provider-id.ts b/packages/media-understanding-common/src/provider-id.ts
index a985603f0d76..f23e3ea8dc72 100644
--- a/packages/media-understanding-common/src/provider-id.ts
+++ b/packages/media-understanding-common/src/provider-id.ts
@@ -1,7 +1,11 @@
+// Provider id normalization for media-understanding config and execution.
+
+/** Normalize a provider id for comparison. */
 function normalizeProviderId(provider: string): string {
   return provider.trim().toLowerCase();
 }
 
+/** Normalize provider aliases to canonical config provider ids. */
 export function normalizeMediaProviderId(id: string): string {
   const normalized = normalizeProviderId(id);
   if (normalized === "gemini") {
@@ -16,6 +20,7 @@ export function normalizeMediaProviderId(id: string): string {
   return normalized;
 }
 
+/** Normalize provider ids while preserving execution-specific regional aliases. */
 export function normalizeMediaExecutionProviderId(id: string): string {
   const normalized = normalizeProviderId(id);
   if (normalized === "minimax-cn" || normalized === "minimax-portal-cn") {
diff --git a/packages/media-understanding-common/src/provider-supports.ts b/packages/media-understanding-common/src/provider-supports.ts
index 60fcb1bd777a..51e3c549cd51 100644
--- a/packages/media-understanding-common/src/provider-supports.ts
+++ b/packages/media-understanding-common/src/provider-supports.ts
@@ -1,5 +1,8 @@
 import type { MediaUnderstandingCapability, MediaUnderstandingProvider } from "./types.js";
 
+// Capability checks for media-understanding provider objects.
+
+/** Return true when a provider exposes the method for a media capability. */
 export function providerSupportsCapability(
   provider: MediaUnderstandingProvider | undefined,
   capability: MediaUnderstandingCapability,
diff --git a/packages/media-understanding-common/src/types.ts b/packages/media-understanding-common/src/types.ts
index b5782d17f100..cd677a7f4e88 100644
--- a/packages/media-understanding-common/src/types.ts
+++ b/packages/media-understanding-common/src/types.ts
@@ -1,10 +1,15 @@
+// Shared media-understanding provider, attachment, output, and capability contracts.
+
+/** Kind of media-understanding output produced for an attachment. */
 export type MediaUnderstandingKind =
   | "audio.transcription"
   | "video.description"
   | "image.description";
 
+/** Capability exposed by a media-understanding provider. */
 export type MediaUnderstandingCapability = "image" | "audio" | "video";
 
+/** Capability registry keyed by provider id. */
 export type MediaUnderstandingCapabilityRegistry = Map<
   string,
   {
@@ -12,6 +17,7 @@ export type MediaUnderstandingCapabilityRegistry = Map<
   }
 >;
 
+/** Media attachment passed to understanding providers. */
 export type MediaAttachment = {
   path?: string;
   url?: string;
@@ -20,6 +26,7 @@ export type MediaAttachment = {
   alreadyTranscribed?: boolean;
 };
 
+/** Normalized text output produced by media understanding. */
 export type MediaUnderstandingOutput = {
   kind: MediaUnderstandingKind;
   attachmentIndex: number;
@@ -28,6 +35,7 @@ export type MediaUnderstandingOutput = {
   model?: string;
 };
 
+/** Provider shape used for capability discovery and dispatch. */
 export type MediaUnderstandingProvider = {
   id: string;
   capabilities?: MediaUnderstandingCapability[];
diff --git a/packages/media-understanding-common/src/video.ts b/packages/media-understanding-common/src/video.ts
index 00773f40ca78..d11d31e1d396 100644
--- a/packages/media-understanding-common/src/video.ts
+++ b/packages/media-understanding-common/src/video.ts
@@ -1,9 +1,13 @@
 import { DEFAULT_VIDEO_MAX_BASE64_BYTES } from "./defaults.js";
 
+// Video payload size helpers for base64-expanded request bodies.
+
+/** Estimate base64 size for a byte count. */
 export function estimateBase64Size(bytes: number): number {
   return Math.ceil(bytes / 3) * 4;
 }
 
+/** Resolve video base64 byte limit from raw byte limit and global cap. */
 export function resolveVideoMaxBase64Bytes(maxBytes: number): number {
   const expanded = Math.floor(maxBytes * (4 / 3));
   return Math.min(expanded, DEFAULT_VIDEO_MAX_BASE64_BYTES);
diff --git a/packages/plugin-sdk/src/browser-config.ts b/packages/plugin-sdk/src/browser-config.ts
index 931df1bfe646..a9715c21519d 100644
--- a/packages/plugin-sdk/src/browser-config.ts
+++ b/packages/plugin-sdk/src/browser-config.ts
@@ -1 +1,3 @@
+// Public package facade for browser config contracts.
+
 export * from "../../../src/plugin-sdk/browser-config.js";
diff --git a/packages/plugin-sdk/src/config-runtime.ts b/packages/plugin-sdk/src/config-runtime.ts
index 32ca4641d683..4fa8c8a13afd 100644
--- a/packages/plugin-sdk/src/config-runtime.ts
+++ b/packages/plugin-sdk/src/config-runtime.ts
@@ -1 +1,3 @@
+// Public package facade for config runtime helpers.
+
 export * from "../../../src/plugin-sdk/config-runtime.js";
diff --git a/packages/plugin-sdk/src/exec-approvals-runtime.ts b/packages/plugin-sdk/src/exec-approvals-runtime.ts
index fa3748763608..176d437dd17f 100644
--- a/packages/plugin-sdk/src/exec-approvals-runtime.ts
+++ b/packages/plugin-sdk/src/exec-approvals-runtime.ts
@@ -1 +1,3 @@
+// Public package facade for exec approval runtime helpers.
+
 export * from "../../../src/plugin-sdk/exec-approvals-runtime.js";
diff --git a/packages/plugin-sdk/src/gateway-method-runtime.ts b/packages/plugin-sdk/src/gateway-method-runtime.ts
index deb78c86c292..a72ddc228dc6 100644
--- a/packages/plugin-sdk/src/gateway-method-runtime.ts
+++ b/packages/plugin-sdk/src/gateway-method-runtime.ts
@@ -1 +1,3 @@
+// Public package facade for gateway method runtime helpers.
+
 export * from "../../../src/plugin-sdk/gateway-method-runtime.js";
diff --git a/packages/plugin-sdk/src/plugin-entry.ts b/packages/plugin-sdk/src/plugin-entry.ts
index 82796abdb21c..dfcd9b9a0f87 100644
--- a/packages/plugin-sdk/src/plugin-entry.ts
+++ b/packages/plugin-sdk/src/plugin-entry.ts
@@ -1 +1,3 @@
+// Public package facade for plugin entry contracts.
+
 export * from "../../../src/plugin-sdk/plugin-entry.js";
diff --git a/packages/plugin-sdk/src/plugin-runtime.ts b/packages/plugin-sdk/src/plugin-runtime.ts
index 3c1559113ec7..7ad5ab7967c8 100644
--- a/packages/plugin-sdk/src/plugin-runtime.ts
+++ b/packages/plugin-sdk/src/plugin-runtime.ts
@@ -1 +1,3 @@
+// Public package facade for plugin runtime helpers.
+
 export * from "../../../src/plugin-sdk/plugin-runtime.js";
diff --git a/packages/plugin-sdk/src/provider-auth-runtime.ts b/packages/plugin-sdk/src/provider-auth-runtime.ts
index aa2127a46c8f..0befbb1eda4f 100644
--- a/packages/plugin-sdk/src/provider-auth-runtime.ts
+++ b/packages/plugin-sdk/src/provider-auth-runtime.ts
@@ -1 +1,3 @@
+// Public package facade for provider auth runtime helpers.
+
 export * from "../../../src/plugin-sdk/provider-auth-runtime.js";
diff --git a/packages/plugin-sdk/src/provider-auth.ts b/packages/plugin-sdk/src/provider-auth.ts
index 0900e0092eb7..0ec301f8285f 100644
--- a/packages/plugin-sdk/src/provider-auth.ts
+++ b/packages/plugin-sdk/src/provider-auth.ts
@@ -1 +1,3 @@
+// Public package facade for provider auth contracts.
+
 export * from "../../../src/plugin-sdk/provider-auth.js";
diff --git a/packages/plugin-sdk/src/provider-entry.ts b/packages/plugin-sdk/src/provider-entry.ts
index 483b35a04a64..515ef0bd519d 100644
--- a/packages/plugin-sdk/src/provider-entry.ts
+++ b/packages/plugin-sdk/src/provider-entry.ts
@@ -1 +1,3 @@
+// Public package facade for provider entry contracts.
+
 export * from "../../../src/plugin-sdk/provider-entry.js";
diff --git a/packages/plugin-sdk/src/provider-http.ts b/packages/plugin-sdk/src/provider-http.ts
index 40363e190988..fca00f849f87 100644
--- a/packages/plugin-sdk/src/provider-http.ts
+++ b/packages/plugin-sdk/src/provider-http.ts
@@ -1 +1,3 @@
+// Public package facade for provider HTTP helpers.
+
 export * from "../../../src/plugin-sdk/provider-http.js";
diff --git a/packages/plugin-sdk/src/provider-model-shared.ts b/packages/plugin-sdk/src/provider-model-shared.ts
index ec731f794b26..52195f5acf37 100644
--- a/packages/plugin-sdk/src/provider-model-shared.ts
+++ b/packages/plugin-sdk/src/provider-model-shared.ts
@@ -1 +1,3 @@
+// Public package facade for provider model shared helpers.
+
 export * from "../../../src/plugin-sdk/provider-model-shared.js";
diff --git a/packages/plugin-sdk/src/provider-model-types.ts b/packages/plugin-sdk/src/provider-model-types.ts
index 8ec2d3239fd1..914a7009d8e1 100644
--- a/packages/plugin-sdk/src/provider-model-types.ts
+++ b/packages/plugin-sdk/src/provider-model-types.ts
@@ -1 +1,3 @@
+// Public package facade for provider model type contracts.
+
 export * from "../../../src/plugin-sdk/provider-model-types.js";
diff --git a/packages/plugin-sdk/src/provider-onboard.ts b/packages/plugin-sdk/src/provider-onboard.ts
index 06835fac8210..4043389209e7 100644
--- a/packages/plugin-sdk/src/provider-onboard.ts
+++ b/packages/plugin-sdk/src/provider-onboard.ts
@@ -1 +1,3 @@
+// Public package facade for provider onboarding contracts.
+
 export * from "../../../src/plugin-sdk/provider-onboard.js";
diff --git a/packages/plugin-sdk/src/provider-stream-shared.ts b/packages/plugin-sdk/src/provider-stream-shared.ts
index e2aa286a97e8..fd5f2de211f2 100644
--- a/packages/plugin-sdk/src/provider-stream-shared.ts
+++ b/packages/plugin-sdk/src/provider-stream-shared.ts
@@ -1 +1,3 @@
+// Public package facade for provider stream shared helpers.
+
 export * from "../../../src/plugin-sdk/provider-stream-shared.js";
diff --git a/packages/plugin-sdk/src/provider-tools.ts b/packages/plugin-sdk/src/provider-tools.ts
index a962aeef2d20..100fb46d78e2 100644
--- a/packages/plugin-sdk/src/provider-tools.ts
+++ b/packages/plugin-sdk/src/provider-tools.ts
@@ -1 +1,3 @@
+// Public package facade for provider tool contracts.
+
 export * from "../../../src/plugin-sdk/provider-tools.js";
diff --git a/packages/plugin-sdk/src/provider-web-search-config-contract.ts b/packages/plugin-sdk/src/provider-web-search-config-contract.ts
index fd39fe300212..b81e51f78a7e 100644
--- a/packages/plugin-sdk/src/provider-web-search-config-contract.ts
+++ b/packages/plugin-sdk/src/provider-web-search-config-contract.ts
@@ -1 +1,3 @@
+// Public package facade for web search provider config contracts.
+
 export * from "../../../src/plugin-sdk/provider-web-search-config-contract.js";
diff --git a/packages/plugin-sdk/src/provider-web-search.ts b/packages/plugin-sdk/src/provider-web-search.ts
index 0748e44d53ef..06b9153260d4 100644
--- a/packages/plugin-sdk/src/provider-web-search.ts
+++ b/packages/plugin-sdk/src/provider-web-search.ts
@@ -1 +1,3 @@
+// Public package facade for web search provider contracts.
+
 export * from "../../../src/plugin-sdk/provider-web-search.js";
diff --git a/packages/plugin-sdk/src/runtime-doctor.ts b/packages/plugin-sdk/src/runtime-doctor.ts
index ef686b2bd447..2eed1e2d45cc 100644
--- a/packages/plugin-sdk/src/runtime-doctor.ts
+++ b/packages/plugin-sdk/src/runtime-doctor.ts
@@ -1 +1,3 @@
+// Public package facade for runtime doctor contracts.
+
 export * from "../../../src/plugin-sdk/runtime-doctor.js";
diff --git a/packages/plugin-sdk/src/runtime-env.ts b/packages/plugin-sdk/src/runtime-env.ts
index 94a7ef641129..98f78c354e21 100644
--- a/packages/plugin-sdk/src/runtime-env.ts
+++ b/packages/plugin-sdk/src/runtime-env.ts
@@ -1 +1,3 @@
+// Public package facade for runtime environment helpers.
+
 export * from "../../../src/plugin-sdk/runtime-env.js";
diff --git a/packages/plugin-sdk/src/secret-input.ts b/packages/plugin-sdk/src/secret-input.ts
index a57ad62fa317..30c46d5026a9 100644
--- a/packages/plugin-sdk/src/secret-input.ts
+++ b/packages/plugin-sdk/src/secret-input.ts
@@ -1 +1,3 @@
+// Public package facade for secret input contracts.
+
 export * from "../../../src/plugin-sdk/secret-input.js";
diff --git a/packages/plugin-sdk/src/security-runtime.ts b/packages/plugin-sdk/src/security-runtime.ts
index 5b6db84a759e..38d08011ac95 100644
--- a/packages/plugin-sdk/src/security-runtime.ts
+++ b/packages/plugin-sdk/src/security-runtime.ts
@@ -1 +1,3 @@
+// Public package facade for security runtime helpers.
+
 export * from "../../../src/plugin-sdk/security-runtime.js";
diff --git a/packages/plugin-sdk/src/testing.ts b/packages/plugin-sdk/src/testing.ts
index d6206c242e4e..115fc8c101cb 100644
--- a/packages/plugin-sdk/src/testing.ts
+++ b/packages/plugin-sdk/src/testing.ts
@@ -1 +1,3 @@
+// Public package facade for plugin SDK testing helpers.
+
 export * from "../../../src/plugin-sdk/testing.js";
diff --git a/packages/plugin-sdk/src/text-runtime.ts b/packages/plugin-sdk/src/text-runtime.ts
index 2f39480c7c33..92808d8d5f35 100644
--- a/packages/plugin-sdk/src/text-runtime.ts
+++ b/packages/plugin-sdk/src/text-runtime.ts
@@ -1 +1,3 @@
+// Public package facade for text runtime helpers.
+
 export * from "../../../src/plugin-sdk/text-runtime.js";
diff --git a/packages/plugin-sdk/src/video-generation.ts b/packages/plugin-sdk/src/video-generation.ts
index da68e6c43ebd..4e540339b65d 100644
--- a/packages/plugin-sdk/src/video-generation.ts
+++ b/packages/plugin-sdk/src/video-generation.ts
@@ -1 +1,3 @@
+// Public package facade for video generation provider contracts.
+
 export * from "../../../src/plugin-sdk/video-generation.js";