docs: improve JSDoc comments for exported appkit types

Add meaningful descriptions to execution, cache, plugin, and telemetry
types that were previously missing or too vague in the public API surface.

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>

Author: pkosiec

docs/docs/api/appkit/Interface.CacheConfig.md

@@ -1,6 +1,6 @@
 # Interface: CacheConfig
 
-Configuration for caching
+Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
 
 ## Indexable
 

docs/docs/api/appkit/Interface.StreamExecutionSettings.md

@@ -1,6 +1,6 @@
 # Interface: StreamExecutionSettings
 
-Configuration for streaming execution with default and user-scoped settings
+Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
 
 ## Properties
 

docs/docs/api/appkit/TypeAlias.PluginData.md

@@ -8,6 +8,8 @@ type PluginData<T, U, N> = {
 };
 ```
 
+Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`.
+
 ## Type Parameters
 
 | Type Parameter |

docs/docs/api/appkit/TypeAlias.ToPlugin.md

@@ -4,6 +4,8 @@
 type ToPlugin<T, U, N> = (config?: U) => PluginData<T, U, N>;
 ```
 
+Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple.
+
 ## Type Parameters
 
 | Type Parameter |

docs/docs/api/appkit/index.md

@@ -31,7 +31,7 @@ plugin architecture, and React integration.
 | Interface | Description |
 | ------ | ------ |
 | [BasePluginConfig](Interface.BasePluginConfig.md) | Base configuration interface for AppKit plugins |
-| [CacheConfig](Interface.CacheConfig.md) | Configuration for caching |
+| [CacheConfig](Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. |
 | [DatabaseCredential](Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
 | [GenerateDatabaseCredentialRequest](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
 | [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
@@ -42,7 +42,7 @@ plugin architecture, and React integration.
 | [ResourceEntry](Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
 | [ResourceFieldEntry](Interface.ResourceFieldEntry.md) | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key). |
 | [ResourceRequirement](Interface.ResourceRequirement.md) | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union. |
-| [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Configuration for streaming execution with default and user-scoped settings |
+| [StreamExecutionSettings](Interface.StreamExecutionSettings.md) | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. |
 | [TelemetryConfig](Interface.TelemetryConfig.md) | OpenTelemetry configuration for AppKit applications |
 | [ValidationResult](Interface.ValidationResult.md) | Result of validating all registered resources against the environment. |
 
@@ -52,9 +52,9 @@ plugin architecture, and React integration.
 | ------ | ------ |
 | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
 | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
-| [PluginData](TypeAlias.PluginData.md) | - |
+| [PluginData](TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
-| [ToPlugin](TypeAlias.ToPlugin.md) | - |
+| [ToPlugin](TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. |
 
 ## Variables
 

packages/appkit/src/telemetry/config.ts

@@ -6,6 +6,7 @@ export interface TelemetryProviderConfig {
   logs: boolean;
 }
 
+/** Converts a TelemetryOptions value (boolean, object, or undefined) into a fully resolved config with explicit traces/metrics/logs flags. Defaults to all enabled. */
 export function normalizeTelemetryOptions(
   config?: TelemetryOptions,
 ): TelemetryProviderConfig {

packages/shared/src/cache.ts

@@ -32,7 +32,7 @@ export interface CacheStorage {
   close(): Promise<void>;
 }
 
-/** Configuration for caching */
+/** Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. */
 export interface CacheConfig {
   /** Whether caching is enabled */
   enabled?: boolean;

packages/shared/src/execute.ts

@@ -1,5 +1,6 @@
 import type { CacheConfig } from "./cache";
 
+/** SSE stream configuration for `executeStream()`. Controls buffer sizes, heartbeat interval, and cleanup behavior. */
 export interface StreamConfig {
   userSignal?: AbortSignal;
   streamId?: string;
@@ -12,19 +13,22 @@ export interface StreamConfig {
   maxActiveStreams?: number;
 }
 
+/** Retry configuration for the RetryInterceptor. Uses exponential backoff between attempts. */
 export interface RetryConfig {
   enabled?: boolean;
   attempts?: number;
   initialDelay?: number;
   maxDelay?: number;
 }
 
+/** Telemetry configuration for the TelemetryInterceptor. Controls span creation and custom attributes. */
 export interface TelemetryConfig {
   enabled?: boolean;
   spanName?: string;
   attributes?: Record<string, any>;
 }
 
+/** Options passed to `Plugin.execute()` and `Plugin.executeStream()` to configure the interceptor chain (cache, retry, telemetry, timeout). */
 export interface PluginExecuteConfig {
   cache?: CacheConfig;
   retry?: RetryConfig;
@@ -35,17 +39,18 @@ export interface PluginExecuteConfig {
   [key: string]: unknown;
 }
 
+/** Default and user-scoped execution settings for a plugin. The `user` config, when present, overrides `default` for on-behalf-of requests. */
 export interface PluginExecutionSettings {
   default: PluginExecuteConfig;
   user?: PluginExecuteConfig;
 }
 
-// stream execute handler can be a promise or a generator
+/** Handler function for `executeStream()`. Can return a Promise (single result) or an AsyncGenerator (chunked streaming). */
 export type StreamExecuteHandler<T> =
   | ((signal?: AbortSignal) => Promise<T>)
   | ((signal?: AbortSignal) => AsyncGenerator<T, void, unknown>);
 
-/** Configuration for streaming execution with default and user-scoped settings */
+/** Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. */
 export interface StreamExecutionSettings {
   default: PluginExecuteConfig;
   user?: PluginExecuteConfig;

packages/shared/src/plugin.ts

@@ -186,7 +186,9 @@ export type PluginMap<
   >;
 };
 
+/** Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. */
 export type PluginData<T, U, N> = { plugin: T; config: U; name: N };
+/** Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. */
 export type ToPlugin<T, U, N extends string> = (
   config?: U,
 ) => PluginData<T, U, N>;