@stigmer/react 0.0.70 → 0.0.72

package/src/execution/tool-rendering-primitives.tsx

@@ -14,9 +14,13 @@ export const TRUNCATION_LINE_LIMIT = 10;
 // CollapsibleCode — labeled code block with line-based truncation
 // ---------------------------------------------------------------------------
 
+/** Props for {@link CollapsibleCode}. */
 export interface CollapsibleCodeProps {
+  /** Label displayed above the code block. */
   readonly label: string;
+  /** Code content to render. */
   readonly content: string;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 
@@ -60,8 +64,11 @@ export function CollapsibleCode({ label, content, className }: CollapsibleCodePr
 // CollapsiblePre — raw pre with line-based truncation (no label/border)
 // ---------------------------------------------------------------------------
 
+/** Props for {@link CollapsiblePre}. */
 export interface CollapsiblePreProps {
+  /** Text content to render in the `<pre>` element. */
   readonly content: string;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 
@@ -106,8 +113,11 @@ export function CollapsiblePre({ content, className }: CollapsiblePreProps) {
 // CollapsibleJsonBlock — chevron-toggled JSON section
 // ---------------------------------------------------------------------------
 
+/** Props for {@link CollapsibleJsonBlock}. */
 export interface CollapsibleJsonBlockProps {
+  /** Label displayed as the toggle header text. */
   readonly label: string;
+  /** Pre-formatted JSON content. */
   readonly content: string;
 }
 

package/src/execution/useArtifactContent.ts

@@ -5,6 +5,7 @@ import { create } from "@bufbuild/protobuf";
 import { GetArtifactContentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
 import { useStigmer } from "../hooks";
 
+/** Return value of {@link useArtifactContent}. */
 export interface UseArtifactContentReturn {
   /**
    * Decoded text content of the artifact, or `null` when:

package/src/execution/useCreateAgentExecution.ts

@@ -5,11 +5,17 @@ import type { AttachmentInput, EnvVarInput } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Input for {@link UseCreateAgentExecutionReturn.create}. */
 export interface CreateAgentExecutionInput {
+  /** Organization slug that owns the session. */
   readonly org: string;
+  /** Session to create the execution within. */
   readonly sessionId: string;
+  /** User message that initiates the execution. */
   readonly message: string;
+  /** Override the default model for this execution. */
   readonly modelName?: string;
+  /** Explicit agent ID. When omitted, uses the session's agent instance. */
   readonly agentId?: string;
   /**
    * Execution-scoped secrets and configuration (Execution Flow).
@@ -39,17 +45,25 @@ export interface CreateAgentExecutionInput {
   readonly attachments?: AttachmentInput[];
 }
 
+/** Resolved output of {@link UseCreateAgentExecutionReturn.create}. */
 export interface CreateAgentExecutionResult {
+  /** Server-assigned identifier for the newly created execution. */
   readonly executionId: string;
+  /** Session the execution belongs to (echoed from input). */
   readonly sessionId: string;
 }
 
+/** Return value of {@link useCreateAgentExecution}. */
 export interface UseCreateAgentExecutionReturn {
+  /** Create an execution within a session. Resolves with the new execution ID. */
   readonly create: (
     input: CreateAgentExecutionInput,
   ) => Promise<CreateAgentExecutionResult>;
+  /** `true` while the create RPC is in flight. */
   readonly isCreating: boolean;
+  /** Error from the last failed create attempt, or `null` when healthy. */
   readonly error: Error | null;
+  /** Reset the error state to `null`. */
   readonly clearError: () => void;
 }
 

package/src/execution/useExecutionArtifacts.ts

@@ -4,6 +4,7 @@ import { useMemo } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 
+/** Return value of {@link useExecutionArtifacts}. */
 export interface UseExecutionArtifactsReturn {
   /** Artifacts published by the agent during execution. Ordered by creation time (oldest first). */
   readonly artifacts: readonly ExecutionArtifact[];

package/src/execution/useExecutionStream.ts

@@ -7,6 +7,7 @@ import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 import { isTerminalPhase } from "./execution-phases";
 
+/** Return value of {@link useExecutionStream}. */
 export interface UseExecutionStreamReturn {
   /** Latest full execution snapshot from the stream, or `null` before the first update arrives. */
   readonly execution: AgentExecution | null;

package/src/execution/useSessionVariables.ts

@@ -12,13 +12,19 @@ import type { EnvVarInput } from "@stigmer/sdk";
  * to the user's personal environment for reuse across sessions.
  */
 export interface SessionVariableEntry {
+  /** Unique identifier for this entry (auto-generated). */
   readonly id: string;
+  /** Environment variable name. */
   readonly key: string;
+  /** Environment variable value. */
   readonly value: string;
+  /** Whether the value should be masked in the UI. */
   readonly isSecret: boolean;
+  /** When `true`, persists the value to the user's personal environment on submit. */
   readonly saveForFuture: boolean;
 }
 
+/** Return value of {@link useSessionVariables}. */
 export interface UseSessionVariablesReturn {
   /** Current entries in the editor. */
   readonly entries: readonly SessionVariableEntry[];

package/src/execution/useSubmitApproval.ts

@@ -7,6 +7,7 @@ import { SubmitApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/ag
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Return value of {@link useSubmitApproval}. */
 export interface UseSubmitApprovalReturn {
   /**
    * Submit an approval decision for a specific tool call within an

package/src/execution/useWorkspaceWriteBacks.ts

@@ -4,6 +4,7 @@ import { useMemo } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
 
+/** Return value of {@link useWorkspaceWriteBacks}. */
 export interface UseWorkspaceWriteBacksReturn {
   /** Write-back outcomes for git-backed workspace entries, ordered by workspace entry name. */
   readonly writeBacks: readonly WorkspaceWriteBack[];

package/src/github/GitHubRepoPicker.tsx

@@ -11,6 +11,7 @@ import {
 import { useGitHubRepos, type GitHubRepo, type GitHubBranch } from "./useGitHubRepos";
 import { useGitHubSearch } from "./useGitHubSearch";
 
+/** Props for {@link GitHubRepoPicker}. */
 export interface GitHubRepoPickerProps {
   /** GitHub access token for API calls. */
   readonly token: string;
@@ -18,6 +19,7 @@ export interface GitHubRepoPickerProps {
   readonly onSelect: (repoUrl: string, branch: string) => void;
   /** Called when the user dismisses the picker (Escape key). */
   readonly onCancel?: () => void;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/github/useGitHubConnection.ts

@@ -19,11 +19,15 @@ const POPUP_CLOSE_POLL_MS = 500;
 
 /** Minimal GitHub user profile for display. */
 export interface GitHubUser {
+  /** GitHub username (e.g. `"octocat"`). */
   readonly login: string;
+  /** URL of the user's avatar image. */
   readonly avatarUrl: string;
+  /** Display name, or `null` when the user has not set one. */
   readonly name: string | null;
 }
 
+/** Options for {@link UseGitHubConnectionReturn.connect}. */
 export interface GitHubConnectOptions {
   /**
    * When `true`, open the OAuth authorization page in a popup window
@@ -38,6 +42,7 @@ export interface GitHubConnectOptions {
   readonly popup?: boolean;
 }
 
+/** Return value of {@link useGitHubConnection}. */
 export interface UseGitHubConnectionReturn {
   /** Whether a valid GitHub token exists. */
   readonly isConnected: boolean;

package/src/github/useGitHubRepos.ts

@@ -8,34 +8,53 @@ const PER_PAGE = 100;
 
 /** A GitHub repository from the API. */
 export interface GitHubRepo {
+  /** GitHub-assigned numeric repository ID. */
   readonly id: number;
+  /** Full repository name including the owner (e.g. `"acme/my-repo"`). */
   readonly fullName: string;
+  /** Repository name without the owner prefix. */
   readonly name: string;
+  /** Owner login (user or organization). */
   readonly owner: string;
+  /** Whether the owner is a personal account or an organization. */
   readonly ownerType: "User" | "Organization";
+  /** Web URL for the repository on GitHub. */
   readonly htmlUrl: string;
+  /** HTTPS clone URL. */
   readonly cloneUrl: string;
+  /** Name of the repository's default branch (e.g. `"main"`). */
   readonly defaultBranch: string;
+  /** `true` when the repository is private. */
   readonly isPrivate: boolean;
+  /** ISO 8601 timestamp of the last push or update event. */
   readonly updatedAt: string;
 }
 
 /** A GitHub branch from the API. */
 export interface GitHubBranch {
+  /** Branch name (e.g. `"main"`, `"feat/new-feature"`). */
   readonly name: string;
 }
 
+/** Return value of {@link useGitHubRepos}. */
 export interface UseGitHubReposReturn {
+  /** Repositories matching the current client-side search filter. */
   readonly repos: readonly GitHubRepo[];
+  /** `true` while the first page is being fetched. */
   readonly isLoading: boolean;
-  /** True while additional pages are being fetched after the first page. */
+  /** `true` while additional pages are being fetched after the first page. */
   readonly isBackgroundLoading: boolean;
+  /** Error message from the last failed fetch, or `null` when healthy. */
   readonly error: string | null;
+  /** Current client-side search query. */
   readonly search: string;
+  /** Update the client-side search query to filter repos by name. */
   readonly setSearch: (query: string) => void;
+  /** Whether more pages may be available. */
   readonly hasMore: boolean;
   /** @deprecated Background pagination loads all pages automatically. */
   readonly loadMore: () => void;
+  /** Fetch branches for a specific repository. */
   readonly fetchBranches: (
     owner: string,
     repo: string,

package/src/github/useGitHubSearch.ts

@@ -7,14 +7,23 @@ const GITHUB_SEARCH_API = "https://api.github.com/search/repositories";
 const DEBOUNCE_MS = 350;
 const PER_PAGE = 30;
 
+/** Return value of {@link useGitHubSearch}. */
 export interface UseGitHubSearchReturn {
+  /** Search results for the current debounced query. */
   readonly results: readonly GitHubRepo[];
+  /** `true` while the search request is in flight. */
   readonly isSearching: boolean;
+  /** Error message from the last failed search, or `null` when healthy. */
   readonly error: string | null;
+  /** Current raw search query (not debounced). */
   readonly query: string;
+  /** Update the search query. The actual API call is debounced internally. */
   readonly setQuery: (query: string) => void;
+  /** Total number of repositories matching the query across GitHub. */
   readonly totalCount: number;
+  /** Whether more result pages are available. */
   readonly hasMore: boolean;
+  /** Fetch the next page of results. */
   readonly loadMore: () => void;
 }
 

package/src/internal/CloudFeatureNotice.tsx

@@ -3,9 +3,11 @@
 import type { ReactNode } from "react";
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link CloudFeatureNotice}. */
 export interface CloudFeatureNoticeProps {
   /** Explanation of why the feature is unavailable and what to do instead. */
   readonly children: ReactNode;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/library/ResourceCountCard.tsx

@@ -2,6 +2,7 @@
 
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link ResourceCountCard}. */
 export interface ResourceCountCardProps {
   /**
    * Icon element rendered at the top of the card. Sized by the consumer.

package/src/library/ResourceListView.tsx

@@ -12,6 +12,7 @@ const DEBOUNCE_MS = 300;
 const SKELETON_COUNT = 5;
 const MAX_VISIBLE_TAGS = 3;
 
+/** Props for {@link ResourceListView}. */
 export interface ResourceListViewProps {
   /** Resource entries to display. */
   readonly items: readonly SearchResult[];

package/src/library/ScopeToggle.tsx

@@ -4,6 +4,7 @@ import { useCallback, useRef } from "react";
 import { cn } from "@stigmer/theme";
 import type { ResourceListScope } from "../search";
 
+/** Props for {@link ScopeToggle}. */
 export interface ScopeToggleProps {
   /** The currently selected scope. */
   readonly value: ResourceListScope;

package/src/library/VisibilityToggle.tsx

@@ -4,6 +4,7 @@ import { useCallback, useRef, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 
+/** Props for {@link VisibilityToggle}. */
 export interface VisibilityToggleProps {
   /** Current visibility of the resource. */
   readonly visibility: ApiResourceVisibility;

package/src/library/useApplyResource.ts

@@ -41,6 +41,7 @@ export interface PushSkillParams {
   readonly tag?: string;
 }
 
+/** Return value of {@link useApplyResource}. */
 export interface UseApplyResourceReturn {
   /**
    * Apply a Stigmer resource YAML (Agent or McpServer) to an organization.

package/src/library/useDetectSkillPackage.ts

@@ -11,6 +11,7 @@ import {
 
 const NOT_DETECTED: SkillPackageDetection = { detected: false } as const;
 
+/** Return value of {@link useDetectSkillPackage}. */
 export interface UseDetectSkillPackageReturn {
   /** The detection result — check `detection.detected` to narrow the type. */
   readonly detection: SkillPackageDetection;

package/src/library/useUpdateVisibility.ts

@@ -10,6 +10,7 @@ import { toError } from "../internal/toError";
 /** Resource kinds that support the `updateVisibility` RPC. */
 export type VisibilityResourceKind = "skill" | "agent" | "mcpServer";
 
+/** Return value of {@link useUpdateVisibility}. */
 export interface UseUpdateVisibilityReturn {
   /**
    * Call the `updateVisibility` RPC for the specified resource.

package/src/mcp-server/ApprovalPolicyGeneratorPanel.tsx

@@ -8,6 +8,7 @@ import { MessageThread } from "../execution/MessageThread";
 import { ExecutionProgress } from "../execution/ExecutionProgress";
 import { isTerminalPhase } from "../execution/execution-phases";
 
+/** Props for {@link ApprovalPolicyGeneratorPanel}. */
 export interface ApprovalPolicyGeneratorPanelProps {
   /** The execution ID to stream. */
   readonly executionId: string;

package/src/mcp-server/McpServerConfigPanel.tsx

@@ -58,6 +58,7 @@ export interface McpServerCredentialsProps {
 // Component props
 // ---------------------------------------------------------------------------
 
+/** Props for {@link McpServerConfigPanel}. */
 export interface McpServerConfigPanelProps {
   /** The MCP server resource — used for header display (name, icon, description). */
   readonly mcpServer: McpServer;
@@ -82,7 +83,9 @@ export interface McpServerConfigPanelProps {
   readonly onBack: () => void;
   /** Error to display inline (e.g., from credential submission failure). */
   readonly error?: Error | null;
+  /** Disables all interaction. */
   readonly disabled?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/mcp-server/McpServerDetailView.tsx

@@ -26,6 +26,7 @@ import { Tabs, type TabItem } from "../internal/Tabs";
 
 type CapabilityTab = "tools" | "policies" | "resources";
 
+/** Props for {@link McpServerDetailView}. */
 export interface McpServerDetailViewProps {
   /** Organization slug that owns the MCP server. */
   readonly org: string;

package/src/mcp-server/McpServerPicker.tsx

@@ -68,6 +68,7 @@ export interface McpServerSetupIntegration {
 // Component props
 // ---------------------------------------------------------------------------
 
+/** Props for {@link McpServerPicker}. */
 export interface McpServerPickerProps {
   /** Organization slug used as the default search scope. */
   readonly org: string;
@@ -99,7 +100,9 @@ export interface McpServerPickerProps {
   readonly onChange?: (usages: McpServerUsageInput[]) => void;
   /** Called with the display name when an item is added (for chip rendering). */
   readonly onDisplayNameResolved?: (key: string, name: string) => void;
+  /** Disables all interaction. */
   readonly disabled?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
   /**
    * When provided, enables setup-integrated mode: per-server status

package/src/mcp-server/McpToolSelector.tsx

@@ -7,6 +7,7 @@ import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcps
 import { useScrollShadows } from "../internal/useScrollShadows";
 import { ScrollFade } from "../internal/ScrollFade";
 
+/** Props for {@link McpToolSelector}. */
 export interface McpToolSelectorProps {
   /** Discovered tools from `status.discovered_capabilities.tools`. */
   readonly tools: DiscoveredTool[];
@@ -16,7 +17,9 @@ export interface McpToolSelectorProps {
   readonly enabledTools: string[];
   /** Called when the set of enabled tools changes. */
   readonly onChange: (enabledTools: string[]) => void;
+  /** Disables all interaction. */
   readonly disabled?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/mcp-server/useDiscoverCapabilities.ts

@@ -8,6 +8,7 @@ import type { EnvVarInput } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Return value of {@link useDiscoverCapabilities}. */
 export interface UseDiscoverCapabilitiesReturn {
   /**
    * Trigger server-side MCP discovery for the given MCP server.

package/src/mcp-server/useMcpServer.ts

@@ -6,12 +6,15 @@ import { isNotFound } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Return value of {@link useMcpServer}. */
 export interface UseMcpServerReturn {
   /** The resolved MCP server, or `null` while loading, on error, or when not found. */
   readonly mcpServer: McpServer | null;
+  /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
-  /** Re-fetch the MCP server with the same org and slug. */
+  /** Discard cached data and re-fetch the MCP server from the server. */
   readonly refetch: () => void;
 }
 

package/src/mcp-server/useMcpServerCount.ts

@@ -4,6 +4,7 @@ import { useCallback } from "react";
 import { useStigmer } from "../hooks";
 import { useResourceCount, type ResourceListScope } from "../search";
 
+/** Options for {@link useMcpServerCount}. */
 export interface UseMcpServerCountOptions {
   /** Text query to filter MCP servers before counting. */
   readonly query?: string;
@@ -18,15 +19,18 @@ export interface UseMcpServerCountOptions {
   readonly scope?: ResourceListScope;
 }
 
+/** Return value of {@link useMcpServerCount}. */
 export interface UseMcpServerCountReturn {
   /**
    * Total number of MCP servers matching the current filters. `undefined`
    * until the first successful fetch completes.
    */
   readonly count: number | undefined;
+  /** `true` while the count fetch is in flight. */
   readonly isLoading: boolean;
+  /** Error message from the last failed request, or `null` when healthy. */
   readonly error: string | null;
-  /** Re-fetch the count with the same parameters. */
+  /** Discard cached data and re-fetch the count from the server. */
   readonly refetch: () => void;
 }
 

package/src/mcp-server/useMcpServerCredentials.ts

@@ -8,6 +8,7 @@ import { diffEnvSpec } from "../environment/diffEnvSpec";
 import { SYSTEM_ENV_VAR_KEYS } from "../environment/systemEnvVars";
 import type { EnvVarFormVariable } from "../environment/EnvVarForm";
 
+/** Return value of {@link useMcpServerCredentials}. */
 export interface UseMcpServerCredentialsReturn {
   /**
    * Variables required by the MCP server that are missing from the

package/src/mcp-server/useMcpServerList.ts

@@ -5,6 +5,7 @@ import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
 import { useStigmer } from "../hooks";
 import { useResourceList, type ResourceListScope } from "../search";
 
+/** Options for {@link useMcpServerList}. */
 export interface UseMcpServerListOptions {
   /** Maximum MCP servers per page. @default 20 */
   readonly pageSize?: number;
@@ -23,6 +24,7 @@ export interface UseMcpServerListOptions {
   readonly scope?: ResourceListScope;
 }
 
+/** Return value of {@link useMcpServerList}. */
 export interface UseMcpServerListReturn {
   /** Paginated MCP server entries for the current page. */
   readonly mcpServers: readonly SearchResult[];
@@ -32,9 +34,11 @@ export interface UseMcpServerListReturn {
   readonly totalPages: number;
   /** The current page number (mirrors the `page` option). */
   readonly currentPage: number;
+  /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** Error message from the last failed request, or `null` when healthy. */
   readonly error: string | null;
-  /** Re-fetch the current page with the same parameters. */
+  /** Discard cached data and re-fetch the current page from the server. */
   readonly refetch: () => void;
 }
 

package/src/mcp-server/useMcpServerSearch.ts

@@ -8,7 +8,9 @@ import {
   type UseResourceSearchReturn,
 } from "../search";
 
+/** Options for {@link useMcpServerSearch}. Delegates to the shared resource search options. */
 export type UseMcpServerSearchOptions = UseResourceSearchOptions;
+/** Return value of {@link useMcpServerSearch}. Delegates to the shared resource search return. */
 export type UseMcpServerSearchReturn = UseResourceSearchReturn;
 
 /**

package/src/mcp-server/useMcpServerSetup.ts

@@ -27,6 +27,7 @@ export type {
 
 export { toServerKey } from "./mcpServerSetupReducer";
 
+/** Options for {@link UseMcpServerSetupReturn.submitEnvVars}. */
 export interface SubmitMcpEnvVarsOptions {
   /**
    * When `true` (default), the provided values are saved to the user's
@@ -42,6 +43,7 @@ export interface SubmitMcpEnvVarsOptions {
   readonly saveForFuture?: boolean;
 }
 
+/** Return value of {@link useMcpServerSetup}. */
 export interface UseMcpServerSetupReturn {
   /**
    * Per-server setup state, keyed by `"org/slug"` (see {@link toServerKey}).

package/src/mcp-server/useTriggerApprovalPolicySession.ts

@@ -12,11 +12,15 @@ import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 import { buildPersonalInstanceInput } from "../agent-instance/buildPersonalInstanceInput";
 
+/** IDs of the session and execution created by {@link useTriggerApprovalPolicySession}. */
 export interface TriggerApprovalPolicyResult {
+  /** ID of the newly created agent session. */
   readonly sessionId: string;
+  /** ID of the first execution within the session. */
   readonly executionId: string;
 }
 
+/** Return value of {@link useTriggerApprovalPolicySession}. */
 export interface UseTriggerApprovalPolicySessionReturn {
   /**
    * Create an agent session with the `mcp-server-creator` agent, attach the
@@ -32,9 +36,13 @@ export interface UseTriggerApprovalPolicySessionReturn {
     org: string,
     mcpServerSlug: string,
   ) => Promise<TriggerApprovalPolicyResult>;
+  /** `true` while the session creation and execution trigger are in flight. */
   readonly isTriggering: boolean;
+  /** Error from the last failed trigger, or `null` when healthy. */
   readonly error: Error | null;
+  /** Reset `error` to `null`. */
   readonly clearError: () => void;
+  /** Result from the last successful trigger, or `null`. */
   readonly result: TriggerApprovalPolicyResult | null;
 }
 

package/src/models/ModelSelector.tsx

@@ -16,9 +16,13 @@ const COST_TIER_INDICATOR: Record<string, string> = {
   premium: "$$$",
 };
 
+/** Props for {@link ModelSelector}. */
 export interface ModelSelectorProps {
+  /** Currently selected model ID. Falls back to {@link DEFAULT_MODEL_ID} when omitted. */
   readonly value?: string;
+  /** Called when the user picks a different model. Receives the new `modelId`. */
   readonly onValueChange: (modelId: string) => void;
+  /** Additional CSS class names for the trigger button. */
   readonly className?: string;
   /** When true, disables the selector. */
   readonly disabled?: boolean;

package/src/models/registry.ts

@@ -10,8 +10,20 @@
  * the same.
  */
 
+/**
+ * Pricing bracket for a model.
+ *
+ * - `economy` — lowest-cost models suitable for high-volume or latency-sensitive tasks
+ * - `standard` — balanced cost-to-capability, the default choice for most workloads
+ * - `premium` — highest-capability models for complex reasoning or critical tasks
+ */
 export type CostTier = "economy" | "standard" | "premium";
 
+/**
+ * LLM provider identifier. Each provider maps to a distinct inference
+ * backend. The {@link MODEL_REGISTRY} groups models by provider for
+ * display in {@link ModelSelector}.
+ */
 export type Provider = "anthropic" | "openai" | "ollama";
 
 /**
@@ -28,13 +40,25 @@ export const DISABLED_PROVIDERS: ReadonlySet<Provider> = new Set([
   "ollama",
 ]);
 
+/** UI-relevant metadata for a single platform-supported LLM model. */
 export interface ModelInfo {
+  /** Unique model identifier sent to the backend (e.g. `"claude-sonnet-4.5"`). */
   readonly modelId: string;
+  /** LLM provider that serves this model. */
   readonly provider: Provider;
+  /** Human-readable name shown in the {@link ModelSelector} dropdown. */
   readonly displayName: string;
+  /** Pricing bracket used for cost-tier indicators in the UI. */
   readonly costTier: CostTier;
 }
 
+/**
+ * Static catalog of all platform-supported LLM models.
+ *
+ * Each entry carries the metadata needed for model selection UI.
+ * {@link useModelRegistry} filters out disabled providers and provides
+ * lookup helpers on top of this list.
+ */
 export const MODEL_REGISTRY: readonly ModelInfo[] = [
   // ── Anthropic — Generation 4.6 ────────────────────────────────────
   { modelId: "claude-opus-4.6", provider: "anthropic", displayName: "Claude Opus 4.6", costTier: "premium" },
@@ -71,4 +95,5 @@ export const MODEL_REGISTRY: readonly ModelInfo[] = [
   { modelId: "mistral:7b", provider: "ollama", displayName: "Mistral 7B", costTier: "economy" },
 ] as const;
 
+/** Model ID used when no user preference is set. */
 export const DEFAULT_MODEL_ID = "claude-sonnet-4.5";