diff --git a/.changeset/bright-docs-integrations.md b/.changeset/bright-docs-integrations.md
new file mode 100644
index 000000000..49a927239
--- /dev/null
+++ b/.changeset/bright-docs-integrations.md
@@ -0,0 +1,5 @@
+---
+"@agentskit/integrations": patch
+---
+
+Document the public API.
diff --git a/docs/stability/jsdoc-coverage-v1.json b/docs/stability/jsdoc-coverage-v1.json
index 50ca6d4df..0cfd1b9c7 100644
--- a/docs/stability/jsdoc-coverage-v1.json
+++ b/docs/stability/jsdoc-coverage-v1.json
@@ -547,95 +547,10 @@
       ".::ToolCallStatus",
       ".::ToolDefinition",
       ".::ToolExecutionContext",
-      ".::useChat",
       ".::UseStreamOptions",
       ".::UseStreamReturn"
     ],
     "@agentskit/integrations": [
-      ".::acuityIntegration",
-      ".::airtableIntegration",
-      ".::ApiKeyAuthSpec",
-      ".::apolloIntegration",
-      ".::asanaIntegration",
-      ".::assemblyaiIntegration",
-      ".::attioIntegration",
-      ".::AuthSpec",
-      ".::azureOpenaiIntegration",
-      ".::baserowIntegration",
-      ".::bigcommerceIntegration",
-      ".::boxIntegration",
-      ".::calComIntegration",
-      ".::calendlyIntegration",
-      ".::coingeckoIntegration",
-      ".::confluenceIntegration",
-      ".::createRegistry",
-      ".::deepgramIntegration",
-      ".::discordIntegration",
-      ".::dropboxIntegration",
-      ".::elevenlabsIntegration",
-      ".::EmailAttachment",
-      ".::EmailConfig",
-      ".::emailIntegration",
-      ".::EmailMessage",
-      ".::EmailSendMessage",
-      ".::EmailSendResult",
-      ".::EmailTransport",
-      ".::figmaIntegration",
-      ".::firecrawlIntegration",
-      ".::getIntegration",
-      ".::githubActionsIntegration",
-      ".::githubIntegration",
-      ".::gmailIntegration",
-      ".::googleCalendarIntegration",
-      ".::googleDriveIntegration",
-      ".::HttpJsonRequest",
-      ".::HttpToolOptions",
-      ".::hubspotIntegration",
-      ".::ImapClient",
-      ".::ImapFetchOptions",
-      ".::Integration",
-      ".::IntegrationAction",
-      ".::integrationsByCategory",
-      ".::IntegrationTrigger",
-      ".::intercomIntegration",
-      ".::jiraIntegration",
-      ".::linearIntegration",
-      ".::linearTriageIntegration",
-      ".::listIntegrations",
-      ".::mailchimpIntegration",
-      ".::mapsIntegration",
-      ".::NoAuthSpec",
-      ".::notionIntegration",
-      ".::OAuth2AuthSpec",
-      ".::openaiImagesIntegration",
-      ".::pagerdutyIntegration",
-      ".::pipedriveIntegration",
-      ".::readerIntegration",
-      ".::registerIntegration",
-      ".::RetryableHttpMethod",
-      ".::RetryPolicy",
-      ".::salesforceIntegration",
-      ".::sendgridIntegration",
-      ".::sentryIntegration",
-      ".::shopifyIntegration",
-      ".::SideEffect",
-      ".::slackIntegration",
-      ".::stripeIntegration",
-      ".::TeamsAdaptiveCard",
-      ".::TeamsAdaptiveCardAction",
-      ".::TeamsBotClient",
-      ".::TeamsBotMessage",
-      ".::TeamsBotSendResult",
-      ".::teamsIntegration",
-      ".::TeamsMessageCard",
-      ".::telegramIntegration",
-      ".::twilioIntegration",
-      ".::VerifyResult",
-      ".::weatherIntegration",
-      ".::WebhookInput",
-      ".::WebhookSecretAuthSpec",
-      ".::whatsappIntegration",
-      ".::whisperIntegration",
       "./testing::validateAction",
       "./testing::validateTrigger"
     ],
@@ -1098,7 +1013,6 @@
     "@agentskit/svelte": [
       ".::ChatContainer",
       ".::CodeBlock",
-      ".::createChatStore",
       ".::InputBar",
       ".::Markdown",
       ".::Message",
@@ -1156,16 +1070,6 @@
       "./integrations::cloudflareR2SignedUrl",
       "./integrations::documentParsers",
       "./integrations::DocumentParsersConfig",
-      "./integrations::EmailAttachment",
-      "./integrations::EmailConfig",
-      "./integrations::EmailMessage",
-      "./integrations::EmailSendMessage",
-      "./integrations::EmailSendResult",
-      "./integrations::EmailTransport",
-      "./integrations::HttpJsonRequest",
-      "./integrations::HttpToolOptions",
-      "./integrations::ImapClient",
-      "./integrations::ImapFetchOptions",
       "./integrations::parseDocx",
       "./integrations::parsePdf",
       "./integrations::parseXlsx",
@@ -1181,18 +1085,11 @@
       "./integrations::postgresQuery",
       "./integrations::PostgresRolesConfig",
       "./integrations::R2ClientLike",
-      "./integrations::RetryPolicy",
       "./integrations::s3",
       "./integrations::S3Config",
       "./integrations::s3GetObject",
       "./integrations::s3ListObjects",
       "./integrations::s3PutObject",
-      "./integrations::TeamsAdaptiveCard",
-      "./integrations::TeamsAdaptiveCardAction",
-      "./integrations::TeamsBotClient",
-      "./integrations::TeamsBotMessage",
-      "./integrations::TeamsBotSendResult",
-      "./integrations::TeamsMessageCard",
       "./mcp-devtools::devtoolsTools",
       "./mcp-devtools::EvalResult",
       "./mcp-devtools::EvalSummary",
diff --git a/packages/integrations/src/contract.ts b/packages/integrations/src/contract.ts
index c993c8f74..3ed10feaa 100644
--- a/packages/integrations/src/contract.ts
+++ b/packages/integrations/src/contract.ts
@@ -6,6 +6,7 @@ import type { IntegrationHttp } from './http'
 // Side effects — lets a host enforce an autonomy/approval gate per action.
 // ---------------------------------------------------------------------------
 
+/** Declared blast radius of an integration action. */
 export type SideEffect = 'none' | 'read' | 'write' | 'destructive' | 'external'
 
 // ---------------------------------------------------------------------------
@@ -27,10 +28,12 @@ export interface OAuth2ProviderSpec {
   extraAuthParams?: Record<string, string>
 }
 
+/** OAuth2 authorization configuration for a service integration. */
 export interface OAuth2AuthSpec extends OAuth2ProviderSpec {
   kind: 'oauth2'
 }
 
+/** Header-based API key authentication configuration. */
 export interface ApiKeyAuthSpec {
   kind: 'apiKey'
   /** Header the credential is sent in (e.g. `authorization`). */
@@ -41,16 +44,19 @@ export interface ApiKeyAuthSpec {
   envHint?: string
 }
 
+/** Authentication configuration for verifying inbound webhook signatures. */
 export interface WebhookSecretAuthSpec {
   kind: 'webhookSecret'
   /** Signature scheme used to verify inbound webhooks. */
   scheme: 'hmac-sha256' | 'ed25519' | 'custom'
 }
 
+/** Authentication marker for integrations that require no credentials. */
 export interface NoAuthSpec {
   kind: 'none'
 }
 
+/** Supported declarative authentication configurations for integrations. */
 export type AuthSpec =
   | OAuth2AuthSpec
   | ApiKeyAuthSpec
@@ -86,6 +92,7 @@ export interface IntegrationActionContext {
   config: unknown
 }
 
+/** An executable provider operation that can be projected into a tool. */
 export interface IntegrationAction {
   /** Stable, namespaced id, e.g. `slack_post_message`. */
   name: string
@@ -107,6 +114,7 @@ export interface IntegrationAction {
 // canonical normalized event a host trigger layer can consume.
 // ---------------------------------------------------------------------------
 
+/** Request data supplied to a trigger's webhook verifier. */
 export interface WebhookInput {
   /** Verification secret (signing secret / shared token). */
   secret: string
@@ -118,6 +126,7 @@ export interface WebhookInput {
   requestUrl?: string
 }
 
+/** Result returned by an integration webhook signature verifier. */
 export type VerifyResult = { ok: true } | { ok: false; reason: string }
 
 /** External thread reference — basis for session stitching across turns. */
@@ -136,6 +145,7 @@ export interface NormalizedEvent {
   raw?: unknown
 }
 
+/** Webhook trigger that verifies and normalizes provider events. */
 export interface IntegrationTrigger {
   /** Stable id, e.g. `slack.message`. */
   name: string
@@ -174,6 +184,7 @@ export interface ConfigField {
   placeholder?: string
 }
 
+/** Complete service descriptor shared by integration projections. */
 export interface Integration {
   /** Service slug, e.g. `slack`. */
   name: string
diff --git a/packages/integrations/src/http.ts b/packages/integrations/src/http.ts
index 172985aaa..8f48b8ba1 100644
--- a/packages/integrations/src/http.ts
+++ b/packages/integrations/src/http.ts
@@ -12,6 +12,7 @@ import { composeTimeoutSignal } from './http-timeout'
 export { readResponseBytes, readResponseText } from './http-body'
 export { composeTimeoutSignal } from './http-timeout'
 
+/** Configuration for an authenticated, origin-confined integration HTTP client. */
 export interface HttpToolOptions {
   baseUrl?: string
   /** Header bag merged into every request (auth, user-agent, etc.). */
@@ -32,6 +33,7 @@ export interface HttpToolOptions {
   retry?: RetryPolicy
 }
 
+/** Retry limits and delays for retryable integration HTTP requests. */
 export interface RetryPolicy {
   /** Total attempts, including the first request. Defaults to 1; valid range is 1–100. */
   maxAttempts?: number
@@ -43,10 +45,12 @@ export interface RetryPolicy {
   methods?: RetryableHttpMethod[]
 }
 
+/** HTTP methods for which the integration client can retry requests. */
 export type RetryableHttpMethod = NonNullable<HttpJsonRequest['method']>
 
 const MAX_TIMEOUT_MS = 2_147_483_647
 
+/** Request options accepted by `httpJson` and a bound integration client. */
 export interface HttpJsonRequest {
   /** HTTP method. Defaults to GET. */
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
diff --git a/packages/integrations/src/registry.ts b/packages/integrations/src/registry.ts
index 4b04e79f1..2d9a1ccdb 100644
--- a/packages/integrations/src/registry.ts
+++ b/packages/integrations/src/registry.ts
@@ -16,6 +16,16 @@ export interface IntegrationRegistry {
   byCategory(category: string): Integration[]
 }
 
+/** Creates an isolated in-memory registry seeded with optional descriptors.
+ * @param initial Integrations to register when the registry is created.
+ * @returns A registry with register, lookup, list, and category methods.
+ * @throws {ConfigError} When two initial integrations have the same name.
+ * @example
+ * ```ts
+ * const registry = createRegistry([slackIntegration])
+ * const slack = registry.get('slack')
+ * ```
+ */
 export function createRegistry(initial: Integration[] = []): IntegrationRegistry {
   const map = new Map<string, Integration>()
 
@@ -48,18 +58,33 @@ export function createRegistry(initial: Integration[] = []): IntegrationRegistry
  */
 const defaultRegistry = createRegistry()
 
+/** Adds an integration to the default catalog.
+ * @param integration Descriptor to register.
+ * @throws {ConfigError} When an integration with the same name is registered.
+ */
 export function registerIntegration(integration: Integration): void {
   defaultRegistry.register(integration)
 }
 
+/** Looks up an integration by its service slug in the default catalog.
+ * @param name Integration slug.
+ * @returns The matching descriptor, or `undefined` when not registered.
+ */
 export function getIntegration(name: string): Integration | undefined {
   return defaultRegistry.get(name)
 }
 
+/** Returns all descriptors registered in the default catalog.
+ * @returns A new array of integration descriptors.
+ */
 export function listIntegrations(): Integration[] {
   return defaultRegistry.list()
 }
 
+/** Returns default-catalog integrations that include the requested category.
+ * @param category Category slug to match.
+ * @returns Matching integration descriptors.
+ */
 export function integrationsByCategory(category: string): Integration[] {
   return defaultRegistry.byCategory(category)
 }
diff --git a/packages/integrations/src/services/acuity/index.ts b/packages/integrations/src/services/acuity/index.ts
index 9b5667be7..4ce99ce8f 100644
--- a/packages/integrations/src/services/acuity/index.ts
+++ b/packages/integrations/src/services/acuity/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { acuityActions } from './actions'
 
+/** Descriptor for the Acuity Scheduling service integration. */
 export const acuityIntegration = defineIntegration({
   name: 'acuity',
   displayName: 'Acuity Scheduling',
diff --git a/packages/integrations/src/services/airtable/index.ts b/packages/integrations/src/services/airtable/index.ts
index 80cc9c3e8..935e3078a 100644
--- a/packages/integrations/src/services/airtable/index.ts
+++ b/packages/integrations/src/services/airtable/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { airtableActions } from './actions'
 
+/** Descriptor for the Airtable service integration. */
 export const airtableIntegration = defineIntegration({
   name: 'airtable',
   displayName: 'Airtable',
diff --git a/packages/integrations/src/services/apollo/index.ts b/packages/integrations/src/services/apollo/index.ts
index 8c0580179..1869faffe 100644
--- a/packages/integrations/src/services/apollo/index.ts
+++ b/packages/integrations/src/services/apollo/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { apolloActions } from './actions'
 
+/** Descriptor for the Apollo.io service integration. */
 export const apolloIntegration = defineIntegration({
   name: 'apollo',
   displayName: 'Apollo.io',
diff --git a/packages/integrations/src/services/asana/index.ts b/packages/integrations/src/services/asana/index.ts
index 3e1d24078..57c09484d 100644
--- a/packages/integrations/src/services/asana/index.ts
+++ b/packages/integrations/src/services/asana/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { asanaActions } from './actions'
 
+/** Descriptor for the Asana service integration. */
 export const asanaIntegration = defineIntegration({
   name: 'asana',
   displayName: 'Asana',
diff --git a/packages/integrations/src/services/assemblyai/index.ts b/packages/integrations/src/services/assemblyai/index.ts
index 7553d4c8d..c686840d9 100644
--- a/packages/integrations/src/services/assemblyai/index.ts
+++ b/packages/integrations/src/services/assemblyai/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { assemblyaiActions } from './actions'
 
+/** Descriptor for the AssemblyAI service integration. */
 export const assemblyaiIntegration = defineIntegration({
   name: 'assemblyai',
   displayName: 'AssemblyAI',
diff --git a/packages/integrations/src/services/attio/index.ts b/packages/integrations/src/services/attio/index.ts
index 15cb06256..aa54d85f1 100644
--- a/packages/integrations/src/services/attio/index.ts
+++ b/packages/integrations/src/services/attio/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { attioActions } from './actions'
 
+/** Descriptor for the Attio service integration. */
 export const attioIntegration = defineIntegration({
   name: 'attio',
   displayName: 'Attio',
diff --git a/packages/integrations/src/services/azure-openai/index.ts b/packages/integrations/src/services/azure-openai/index.ts
index 00a11935d..c7fc02c73 100644
--- a/packages/integrations/src/services/azure-openai/index.ts
+++ b/packages/integrations/src/services/azure-openai/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { azureOpenaiActions } from './actions'
 
+/** Descriptor for the Azure OpenAI service integration. */
 export const azureOpenaiIntegration = defineIntegration({
   name: 'azure-openai',
   displayName: 'Azure OpenAI',
diff --git a/packages/integrations/src/services/baserow/index.ts b/packages/integrations/src/services/baserow/index.ts
index d1e91ee83..269671ea5 100644
--- a/packages/integrations/src/services/baserow/index.ts
+++ b/packages/integrations/src/services/baserow/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { baserowActions } from './actions'
 
+/** Descriptor for the Baserow service integration. */
 export const baserowIntegration = defineIntegration({
   name: 'baserow',
   displayName: 'Baserow',
diff --git a/packages/integrations/src/services/bigcommerce/index.ts b/packages/integrations/src/services/bigcommerce/index.ts
index ad82dd46c..f536686e8 100644
--- a/packages/integrations/src/services/bigcommerce/index.ts
+++ b/packages/integrations/src/services/bigcommerce/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { bigcommerceActions } from './actions'
 
+/** Descriptor for the BigCommerce service integration. */
 export const bigcommerceIntegration = defineIntegration({
   name: 'bigcommerce',
   displayName: 'BigCommerce',
diff --git a/packages/integrations/src/services/box/index.ts b/packages/integrations/src/services/box/index.ts
index bf8db5c8b..20df04c90 100644
--- a/packages/integrations/src/services/box/index.ts
+++ b/packages/integrations/src/services/box/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { boxActions } from './actions'
 
+/** Descriptor for the Box service integration. */
 export const boxIntegration = defineIntegration({
   name: 'box',
   displayName: 'Box',
diff --git a/packages/integrations/src/services/cal-com/index.ts b/packages/integrations/src/services/cal-com/index.ts
index e3c08516b..43cb867a6 100644
--- a/packages/integrations/src/services/cal-com/index.ts
+++ b/packages/integrations/src/services/cal-com/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { calComActions } from './actions'
 
+/** Descriptor for the Cal.com service integration. */
 export const calComIntegration = defineIntegration({
   name: 'cal-com',
   displayName: 'Cal.com',
diff --git a/packages/integrations/src/services/calendly/index.ts b/packages/integrations/src/services/calendly/index.ts
index a86fd8f1c..835f8d430 100644
--- a/packages/integrations/src/services/calendly/index.ts
+++ b/packages/integrations/src/services/calendly/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { calendlyActions } from './actions'
 
+/** Descriptor for the Calendly service integration. */
 export const calendlyIntegration = defineIntegration({
   name: 'calendly',
   displayName: 'Calendly',
diff --git a/packages/integrations/src/services/coingecko/index.ts b/packages/integrations/src/services/coingecko/index.ts
index 6e2bfea90..0b361a13c 100644
--- a/packages/integrations/src/services/coingecko/index.ts
+++ b/packages/integrations/src/services/coingecko/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { coingeckoActions } from './actions'
 
+/** Descriptor for the CoinGecko service integration. */
 export const coingeckoIntegration = defineIntegration({
   name: 'coingecko',
   displayName: 'CoinGecko',
diff --git a/packages/integrations/src/services/confluence/index.ts b/packages/integrations/src/services/confluence/index.ts
index ad2a02daa..054bb354f 100644
--- a/packages/integrations/src/services/confluence/index.ts
+++ b/packages/integrations/src/services/confluence/index.ts
@@ -4,6 +4,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { confluenceActions } from './actions'
 
+/** Descriptor for the Confluence service integration. */
 export const confluenceIntegration = defineIntegration({
   name: 'confluence',
   displayName: 'Confluence',
diff --git a/packages/integrations/src/services/deepgram/index.ts b/packages/integrations/src/services/deepgram/index.ts
index 892f58e90..751a783fc 100644
--- a/packages/integrations/src/services/deepgram/index.ts
+++ b/packages/integrations/src/services/deepgram/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { deepgramActions } from './actions'
 
+/** Descriptor for the Deepgram service integration. */
 export const deepgramIntegration = defineIntegration({
   name: 'deepgram',
   displayName: 'Deepgram',
diff --git a/packages/integrations/src/services/discord/index.ts b/packages/integrations/src/services/discord/index.ts
index 70cb9c68a..9219bd07d 100644
--- a/packages/integrations/src/services/discord/index.ts
+++ b/packages/integrations/src/services/discord/index.ts
@@ -4,6 +4,7 @@ import { OAUTH_SPECS } from '../../oauth-specs'
 import { discordActions } from './actions'
 import { discordTriggers } from './triggers'
 
+/** Descriptor for the Discord service integration. */
 export const discordIntegration = defineIntegration({
   name: 'discord',
   displayName: 'Discord',
diff --git a/packages/integrations/src/services/dropbox/index.ts b/packages/integrations/src/services/dropbox/index.ts
index a103a8a1d..ce14c3b02 100644
--- a/packages/integrations/src/services/dropbox/index.ts
+++ b/packages/integrations/src/services/dropbox/index.ts
@@ -3,6 +3,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { dropboxActions } from './actions'
 
+/** Descriptor for the Dropbox service integration. */
 export const dropboxIntegration = defineIntegration({
   name: 'dropbox',
   displayName: 'Dropbox',
diff --git a/packages/integrations/src/services/elevenlabs/index.ts b/packages/integrations/src/services/elevenlabs/index.ts
index f8fcf2b81..e5f95352c 100644
--- a/packages/integrations/src/services/elevenlabs/index.ts
+++ b/packages/integrations/src/services/elevenlabs/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { elevenlabsActions } from './actions'
 
+/** Descriptor for the ElevenLabs service integration. */
 export const elevenlabsIntegration = defineIntegration({
   name: 'elevenlabs',
   displayName: 'ElevenLabs',
diff --git a/packages/integrations/src/services/email/index.ts b/packages/integrations/src/services/email/index.ts
index 1265838f2..ef767754e 100644
--- a/packages/integrations/src/services/email/index.ts
+++ b/packages/integrations/src/services/email/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { emailActions } from './actions'
 
+/** Descriptor for the Email (SMTP/IMAP) service integration. */
 export const emailIntegration = defineIntegration({
   name: 'email',
   displayName: 'Email (SMTP/IMAP)',
diff --git a/packages/integrations/src/services/email/types.ts b/packages/integrations/src/services/email/types.ts
index 9e8d837a7..092bb723e 100644
--- a/packages/integrations/src/services/email/types.ts
+++ b/packages/integrations/src/services/email/types.ts
@@ -1,3 +1,4 @@
+/** File attachment accepted by the email transport. */
 export interface EmailAttachment {
   filename: string
   /** UTF-8 text contents. Use `contentBase64` for binary. */
@@ -6,6 +7,7 @@ export interface EmailAttachment {
   contentType?: string
 }
 
+/** Outbound message data passed to the email transport. */
 export interface EmailSendMessage {
   from: string
   to: string | string[]
@@ -17,16 +19,19 @@ export interface EmailSendMessage {
   attachments?: EmailAttachment[]
 }
 
+/** Provider result returned after sending an email. */
 export interface EmailSendResult {
   messageId: string
   accepted?: string[]
   rejected?: string[]
 }
 
+/** Host-provided transport used by the email integration to send messages. */
 export interface EmailTransport {
   send: (msg: EmailSendMessage) => Promise<EmailSendResult>
 }
 
+/** Email message returned by the IMAP client. */
 export interface EmailMessage {
   id: string
   uid?: number
@@ -40,6 +45,7 @@ export interface EmailMessage {
   attachments?: Array<{ filename: string; contentType: string; size: number }>
 }
 
+/** Filters and result limit for an IMAP message fetch. */
 export interface ImapFetchOptions {
   mailbox?: string
   unseenOnly?: boolean
@@ -51,10 +57,12 @@ export interface ImapFetchOptions {
   limit?: number
 }
 
+/** Host-provided client used to fetch messages from an IMAP mailbox. */
 export interface ImapClient {
   fetch: (opts: ImapFetchOptions) => Promise<EmailMessage[]>
 }
 
+/** Optional send and receive transports used by the email integration. */
 export interface EmailConfig {
   transport?: EmailTransport
   imap?: ImapClient
diff --git a/packages/integrations/src/services/figma/index.ts b/packages/integrations/src/services/figma/index.ts
index 4333b510e..aef092e4b 100644
--- a/packages/integrations/src/services/figma/index.ts
+++ b/packages/integrations/src/services/figma/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { figmaActions } from './actions'
 
+/** Descriptor for the Figma service integration. */
 export const figmaIntegration = defineIntegration({
   name: 'figma',
   displayName: 'Figma',
diff --git a/packages/integrations/src/services/firecrawl/index.ts b/packages/integrations/src/services/firecrawl/index.ts
index 19e3c48a5..1a03dfbd2 100644
--- a/packages/integrations/src/services/firecrawl/index.ts
+++ b/packages/integrations/src/services/firecrawl/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { firecrawlActions } from './actions'
 
+/** Descriptor for the Firecrawl service integration. */
 export const firecrawlIntegration = defineIntegration({
   name: 'firecrawl',
   displayName: 'Firecrawl',
diff --git a/packages/integrations/src/services/github-actions/index.ts b/packages/integrations/src/services/github-actions/index.ts
index 94cabd24a..f215ca1b2 100644
--- a/packages/integrations/src/services/github-actions/index.ts
+++ b/packages/integrations/src/services/github-actions/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { githubActionsActions } from './actions'
 
+/** Descriptor for the GitHub Actions service integration. */
 export const githubActionsIntegration = defineIntegration({
   name: 'github-actions',
   displayName: 'GitHub Actions',
diff --git a/packages/integrations/src/services/github/index.ts b/packages/integrations/src/services/github/index.ts
index c61f30410..a4f7df3c9 100644
--- a/packages/integrations/src/services/github/index.ts
+++ b/packages/integrations/src/services/github/index.ts
@@ -4,6 +4,7 @@ import { OAUTH_SPECS } from '../../oauth-specs'
 import { githubActionsList } from './actions'
 import { githubTriggers } from './triggers'
 
+/** Descriptor for the GitHub service integration. */
 export const githubIntegration = defineIntegration({
   name: 'github',
   displayName: 'GitHub',
diff --git a/packages/integrations/src/services/gmail/index.ts b/packages/integrations/src/services/gmail/index.ts
index 7ca490c32..a1fec7330 100644
--- a/packages/integrations/src/services/gmail/index.ts
+++ b/packages/integrations/src/services/gmail/index.ts
@@ -3,6 +3,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { gmailActions } from './actions'
 
+/** Descriptor for the Gmail service integration. */
 export const gmailIntegration = defineIntegration({
   name: 'gmail',
   displayName: 'Gmail',
diff --git a/packages/integrations/src/services/google-calendar/index.ts b/packages/integrations/src/services/google-calendar/index.ts
index 31910e086..e9d85edb9 100644
--- a/packages/integrations/src/services/google-calendar/index.ts
+++ b/packages/integrations/src/services/google-calendar/index.ts
@@ -3,6 +3,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { googleCalendarActions } from './actions'
 
+/** Descriptor for the Google Calendar service integration. */
 export const googleCalendarIntegration = defineIntegration({
   name: 'google-calendar',
   displayName: 'Google Calendar',
diff --git a/packages/integrations/src/services/google-drive/index.ts b/packages/integrations/src/services/google-drive/index.ts
index d5fe68811..9cd61e1c9 100644
--- a/packages/integrations/src/services/google-drive/index.ts
+++ b/packages/integrations/src/services/google-drive/index.ts
@@ -3,6 +3,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { googleDriveActions } from './actions'
 
+/** Descriptor for the Google Drive service integration. */
 export const googleDriveIntegration = defineIntegration({
   name: 'google-drive',
   displayName: 'Google Drive',
diff --git a/packages/integrations/src/services/hubspot/index.ts b/packages/integrations/src/services/hubspot/index.ts
index c8eb1e858..75146d963 100644
--- a/packages/integrations/src/services/hubspot/index.ts
+++ b/packages/integrations/src/services/hubspot/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { hubspotActions } from './actions'
 
+/** Descriptor for the HubSpot service integration. */
 export const hubspotIntegration = defineIntegration({
   name: 'hubspot',
   displayName: 'HubSpot',
diff --git a/packages/integrations/src/services/intercom/index.ts b/packages/integrations/src/services/intercom/index.ts
index 0bda63c3b..602c70cc7 100644
--- a/packages/integrations/src/services/intercom/index.ts
+++ b/packages/integrations/src/services/intercom/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { intercomActions } from './actions'
 
+/** Descriptor for the Intercom service integration. */
 export const intercomIntegration = defineIntegration({
   name: 'intercom',
   displayName: 'Intercom',
diff --git a/packages/integrations/src/services/jira/index.ts b/packages/integrations/src/services/jira/index.ts
index 27ae41289..1016f0221 100644
--- a/packages/integrations/src/services/jira/index.ts
+++ b/packages/integrations/src/services/jira/index.ts
@@ -4,6 +4,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { jiraActions } from './actions'
 
+/** Descriptor for the Jira service integration. */
 export const jiraIntegration = defineIntegration({
   name: 'jira',
   displayName: 'Jira',
diff --git a/packages/integrations/src/services/linear-triage/index.ts b/packages/integrations/src/services/linear-triage/index.ts
index e8b97c458..cc4ec7bd8 100644
--- a/packages/integrations/src/services/linear-triage/index.ts
+++ b/packages/integrations/src/services/linear-triage/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { linearTriageActions } from './actions'
 
+/** Descriptor for the Linear Triage service integration. */
 export const linearTriageIntegration = defineIntegration({
   name: 'linear-triage',
   displayName: 'Linear Triage',
diff --git a/packages/integrations/src/services/linear/index.ts b/packages/integrations/src/services/linear/index.ts
index 38fef61c5..945cd91e8 100644
--- a/packages/integrations/src/services/linear/index.ts
+++ b/packages/integrations/src/services/linear/index.ts
@@ -4,6 +4,7 @@ import { OAUTH_SPECS } from '../../oauth-specs'
 import { linearActions } from './actions'
 import { linearTriggers } from './triggers'
 
+/** Descriptor for the Linear service integration. */
 export const linearIntegration = defineIntegration({
   name: 'linear',
   displayName: 'Linear',
diff --git a/packages/integrations/src/services/mailchimp/index.ts b/packages/integrations/src/services/mailchimp/index.ts
index 64c454dee..e81b76de0 100644
--- a/packages/integrations/src/services/mailchimp/index.ts
+++ b/packages/integrations/src/services/mailchimp/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { mailchimpActions } from './actions'
 
+/** Descriptor for the Mailchimp service integration. */
 export const mailchimpIntegration = defineIntegration({
   name: 'mailchimp',
   displayName: 'Mailchimp',
diff --git a/packages/integrations/src/services/maps/index.ts b/packages/integrations/src/services/maps/index.ts
index 9091fa6ca..4dd489cbd 100644
--- a/packages/integrations/src/services/maps/index.ts
+++ b/packages/integrations/src/services/maps/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { mapsActions } from './actions'
 
+/** Descriptor for the Maps (OpenStreetMap / Nominatim) service integration. */
 export const mapsIntegration = defineIntegration({
   name: 'maps',
   displayName: 'Maps (OpenStreetMap / Nominatim)',
diff --git a/packages/integrations/src/services/notion/index.ts b/packages/integrations/src/services/notion/index.ts
index c5bb8132c..93b31fc41 100644
--- a/packages/integrations/src/services/notion/index.ts
+++ b/packages/integrations/src/services/notion/index.ts
@@ -3,6 +3,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { notionActions } from './actions'
 
+/** Descriptor for the Notion service integration. */
 export const notionIntegration = defineIntegration({
   name: 'notion',
   displayName: 'Notion',
diff --git a/packages/integrations/src/services/openai-images/index.ts b/packages/integrations/src/services/openai-images/index.ts
index dac0545d9..a8b9dd7ec 100644
--- a/packages/integrations/src/services/openai-images/index.ts
+++ b/packages/integrations/src/services/openai-images/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { openaiImagesActions } from './actions'
 
+/** Descriptor for the OpenAI Images service integration. */
 export const openaiImagesIntegration = defineIntegration({
   name: 'openai-images',
   displayName: 'OpenAI Images',
diff --git a/packages/integrations/src/services/pagerduty/index.ts b/packages/integrations/src/services/pagerduty/index.ts
index 8c495cc2f..a4e55ba7c 100644
--- a/packages/integrations/src/services/pagerduty/index.ts
+++ b/packages/integrations/src/services/pagerduty/index.ts
@@ -5,6 +5,7 @@ import { OAUTH_SPECS } from '../../oauth-specs'
 import { pagerdutyActions } from './actions'
 import { pagerdutyTriggers } from './triggers'
 
+/** Descriptor for the PagerDuty service integration. */
 export const pagerdutyIntegration = defineIntegration({
   name: 'pagerduty',
   displayName: 'PagerDuty',
diff --git a/packages/integrations/src/services/pipedrive/index.ts b/packages/integrations/src/services/pipedrive/index.ts
index f38b2356e..b15746f1b 100644
--- a/packages/integrations/src/services/pipedrive/index.ts
+++ b/packages/integrations/src/services/pipedrive/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { pipedriveActions } from './actions'
 
+/** Descriptor for the Pipedrive service integration. */
 export const pipedriveIntegration = defineIntegration({
   name: 'pipedrive',
   displayName: 'Pipedrive',
diff --git a/packages/integrations/src/services/reader/index.ts b/packages/integrations/src/services/reader/index.ts
index 3d02490ac..7699d20a0 100644
--- a/packages/integrations/src/services/reader/index.ts
+++ b/packages/integrations/src/services/reader/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { readerActions } from './actions'
 
+/** Descriptor for the Jina Reader service integration. */
 export const readerIntegration = defineIntegration({
   name: 'reader',
   displayName: 'Jina Reader',
diff --git a/packages/integrations/src/services/salesforce/index.ts b/packages/integrations/src/services/salesforce/index.ts
index 471b7f504..b52310124 100644
--- a/packages/integrations/src/services/salesforce/index.ts
+++ b/packages/integrations/src/services/salesforce/index.ts
@@ -3,6 +3,7 @@ import { registerIntegration } from '../../registry'
 import { OAUTH_SPECS } from '../../oauth-specs'
 import { salesforceActions } from './actions'
 
+/** Descriptor for the Salesforce service integration. */
 export const salesforceIntegration = defineIntegration({
   name: 'salesforce',
   displayName: 'Salesforce',
diff --git a/packages/integrations/src/services/sendgrid/index.ts b/packages/integrations/src/services/sendgrid/index.ts
index 353017933..c1398ff18 100644
--- a/packages/integrations/src/services/sendgrid/index.ts
+++ b/packages/integrations/src/services/sendgrid/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { sendgridActions } from './actions'
 
+/** Descriptor for the SendGrid service integration. */
 export const sendgridIntegration = defineIntegration({
   name: 'sendgrid',
   displayName: 'SendGrid',
diff --git a/packages/integrations/src/services/sentry/index.ts b/packages/integrations/src/services/sentry/index.ts
index c82c9d39a..32720e7d5 100644
--- a/packages/integrations/src/services/sentry/index.ts
+++ b/packages/integrations/src/services/sentry/index.ts
@@ -4,6 +4,7 @@ import { OAUTH_SPECS } from '../../oauth-specs'
 import { sentryActions } from './actions'
 import { sentryTriggers } from './triggers'
 
+/** Descriptor for the Sentry service integration. */
 export const sentryIntegration = defineIntegration({
   name: 'sentry',
   displayName: 'Sentry',
diff --git a/packages/integrations/src/services/shopify/index.ts b/packages/integrations/src/services/shopify/index.ts
index 371099b74..c46246376 100644
--- a/packages/integrations/src/services/shopify/index.ts
+++ b/packages/integrations/src/services/shopify/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { shopifyActions } from './actions'
 
+/** Descriptor for the Shopify service integration. */
 export const shopifyIntegration = defineIntegration({
   name: 'shopify',
   displayName: 'Shopify',
diff --git a/packages/integrations/src/services/slack/index.ts b/packages/integrations/src/services/slack/index.ts
index 5ff63ed93..f35d595ef 100644
--- a/packages/integrations/src/services/slack/index.ts
+++ b/packages/integrations/src/services/slack/index.ts
@@ -5,6 +5,7 @@ import { slackAuth } from './auth'
 import { slackActions } from './actions'
 import { slackTriggers } from './triggers'
 
+/** Descriptor for the Slack service integration. */
 export const slackIntegration = defineIntegration({
   name: 'slack',
   displayName: 'Slack',
diff --git a/packages/integrations/src/services/stripe/index.ts b/packages/integrations/src/services/stripe/index.ts
index a308d8b50..8e10dafa6 100644
--- a/packages/integrations/src/services/stripe/index.ts
+++ b/packages/integrations/src/services/stripe/index.ts
@@ -5,6 +5,7 @@ import { OAUTH_SPECS } from '../../oauth-specs'
 import { stripeActions } from './actions'
 import { stripeWebhook } from './webhook'
 
+/** Descriptor for the Stripe service integration. */
 export const stripeIntegration = defineIntegration({
   name: 'stripe',
   displayName: 'Stripe',
diff --git a/packages/integrations/src/services/teams/cards.ts b/packages/integrations/src/services/teams/cards.ts
index 6cc17e189..cbd59ab3e 100644
--- a/packages/integrations/src/services/teams/cards.ts
+++ b/packages/integrations/src/services/teams/cards.ts
@@ -1,3 +1,4 @@
+/** Button action rendered in a Teams Adaptive Card. */
 export interface TeamsAdaptiveCardAction {
   type: 'Action.OpenUrl' | 'Action.Submit'
   title: string
@@ -5,6 +6,7 @@ export interface TeamsAdaptiveCardAction {
   data?: Record<string, unknown>
 }
 
+/** Adaptive Card payload supported by the Teams integration. */
 export interface TeamsAdaptiveCard {
   contentType: 'application/vnd.microsoft.card.adaptive'
   content: {
@@ -16,6 +18,7 @@ export interface TeamsAdaptiveCard {
   }
 }
 
+/** Legacy Teams connector message card payload. */
 export interface TeamsMessageCard {
   contentType: 'application/vnd.microsoft.teams.card.o365connector'
   content: {
@@ -71,6 +74,7 @@ export function messageCard(input: {
   }
 }
 
+/** Message accepted by the host-provided Teams bot client. */
 export interface TeamsBotMessage {
   conversationId: string
   serviceUrl?: string
@@ -80,11 +84,13 @@ export interface TeamsBotMessage {
   signal?: AbortSignal
 }
 
+/** Result returned after a Teams bot sends a message. */
 export interface TeamsBotSendResult {
   id: string
   conversationId: string
 }
 
+/** Host-provided client used by the Teams integration to send messages. */
 export interface TeamsBotClient {
   send: (msg: TeamsBotMessage) => Promise<TeamsBotSendResult>
 }
diff --git a/packages/integrations/src/services/teams/index.ts b/packages/integrations/src/services/teams/index.ts
index e22b05243..872ded66a 100644
--- a/packages/integrations/src/services/teams/index.ts
+++ b/packages/integrations/src/services/teams/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { teamsActions } from './actions'
 
+/** Descriptor for the Microsoft Teams service integration. */
 export const teamsIntegration = defineIntegration({
   name: 'teams',
   displayName: 'Microsoft Teams',
diff --git a/packages/integrations/src/services/telegram/index.ts b/packages/integrations/src/services/telegram/index.ts
index d97c00c11..db26f9bdc 100644
--- a/packages/integrations/src/services/telegram/index.ts
+++ b/packages/integrations/src/services/telegram/index.ts
@@ -4,6 +4,7 @@ import { registerIntegration } from '../../registry'
 import { telegramActions } from './actions'
 import { telegramTriggers } from './triggers'
 
+/** Descriptor for the Telegram service integration. */
 export const telegramIntegration = defineIntegration({
   name: 'telegram',
   displayName: 'Telegram',
diff --git a/packages/integrations/src/services/twilio/index.ts b/packages/integrations/src/services/twilio/index.ts
index b3b4df72c..674208c82 100644
--- a/packages/integrations/src/services/twilio/index.ts
+++ b/packages/integrations/src/services/twilio/index.ts
@@ -4,6 +4,7 @@ import { registerIntegration } from '../../registry'
 import { twilioActions } from './actions'
 import { twilioTriggers } from './triggers'
 
+/** Descriptor for the Twilio service integration. */
 export const twilioIntegration = defineIntegration({
   name: 'twilio',
   displayName: 'Twilio',
diff --git a/packages/integrations/src/services/weather/index.ts b/packages/integrations/src/services/weather/index.ts
index a5692d7b7..8916baa94 100644
--- a/packages/integrations/src/services/weather/index.ts
+++ b/packages/integrations/src/services/weather/index.ts
@@ -2,6 +2,7 @@ import { defineIntegration } from '../../contract'
 import { registerIntegration } from '../../registry'
 import { weatherActions } from './actions'
 
+/** Descriptor for the Weather (OpenWeatherMap) service integration. */
 export const weatherIntegration = defineIntegration({
   name: 'weather',
   displayName: 'Weather (OpenWeatherMap)',
diff --git a/packages/integrations/src/services/whatsapp/index.ts b/packages/integrations/src/services/whatsapp/index.ts
index 1f232f333..b2977cf7b 100644
--- a/packages/integrations/src/services/whatsapp/index.ts
+++ b/packages/integrations/src/services/whatsapp/index.ts
@@ -4,6 +4,7 @@ import { registerIntegration } from '../../registry'
 import { whatsappActions } from './actions'
 import { whatsappTriggers } from './triggers'
 
+/** Descriptor for the WhatsApp Cloud API service integration. */
 export const whatsappIntegration = defineIntegration({
   name: 'whatsapp',
   displayName: 'WhatsApp Cloud API',
diff --git a/packages/integrations/src/services/whisper/index.ts b/packages/integrations/src/services/whisper/index.ts
index 7c750616a..7ed6657e7 100644
--- a/packages/integrations/src/services/whisper/index.ts
+++ b/packages/integrations/src/services/whisper/index.ts
@@ -3,6 +3,7 @@ import { CONFIG_FIELDS } from '../../config-fields'
 import { registerIntegration } from '../../registry'
 import { whisperActions } from './actions'
 
+/** Descriptor for the OpenAI Whisper service integration. */
 export const whisperIntegration = defineIntegration({
   name: 'whisper',
   displayName: 'OpenAI Whisper',