@jskit-ai/connectors-catalog 0.1.1

package/docs/hex.md

@@ -0,0 +1,161 @@
+# Hex assistant connection
+
+Import `hexProvider` and `registerHexClient` from
+`@jskit-ai/connectors-catalog/server/hex`. This initial library connects an
+assistant owner to remote MCP and exposes `tools.list` and `tools.call`.
+It reuses the OAuth state, refresh and encrypted file-store implementations.
+
+## Provider setup
+
+1. Check the intended Hex workspace endpoint and account. Hex documents MCP on
+   Team and Enterprise plans with an Explorer or higher role.
+2. Choose Standard, Europe or HIPAA in the Vibe64 **Hex workspace endpoint**
+   field. Single-tenant custom Hex domains are not supported by this fragment.
+3. Confirm **Suggested callback URL** is the route your host will serve. Choose
+   **Register client and connect** to register at the selected fixed authority.
+   The public editor saves the ID in project configuration and the secret, callback
+   and recovery ID in development Env, then starts the app-owned setup command.
+   Existing Env values are not replaced. Alternatively in
+   **OAuth client registration**, copy the endpoint and JSON request body into
+   your HTTP client and send one POST with Content-Type application/json.
+   This endpoint changes with the selected Hex region. Register once; the
+   provider guide does not establish a developer-console creation screen.
+4. For manual registration, copy `client_id` into **Client ID** and **Save configuration**. Choose
+   **Set credential in Env** to save `client_secret` under the displayed reference.
+   Choose **Set callback in Env** to save the same callback used for registration.
+   Return to the form after saving Env. Keep the full registration response private.
+5. Select identity/profile/email/refresh permissions and save configuration.
+   Saving does not register a client or connect the account. The host must open
+   `beginAuthorization`'s URL and complete the callback under the same owner.
+6. In the provider browser flow, sign in, choose the workspace when prompted
+   and approve consent. Verification discovers tools without starting a Thread.
+
+Hex documents project search, Thread creation/retrieval/continuation and project editing tools. Editing requires Editor or higher and the specific project permission.
+Its workspace API-access switch does not revoke MCP access. Sensitive data
+connection controls live under **Settings → Integrations → Configure sensitive
+data connections for external integrations**, or the data source's **Access**
+tab. These settings remain under the workspace administrator's control.
+[Hex MCP guide](https://learn.hex.tech/docs/api-integrations/mcp-server).
+
+## Explicit registration and automation
+
+Public metadata was rechecked on 12 September 2026 for all three endpoints. The
+resource is `https://<host>/mcp`; its issuer is `https://auth.<host>`. The issuer
+advertises `/oauth2/authorize`, `/oauth2/token` and `/oauth2/register`, S256,
+code/refresh grants and `client_secret_post` authentication among its options.
+Its scopes are `openid`, `profile`, `email` and `offline_access`.
+[Standard resource metadata](https://app.hex.tech/.well-known/oauth-protected-resource/mcp),
+[standard OAuth metadata](https://auth.app.hex.tech/.well-known/oauth-authorization-server),
+[EU metadata](https://auth.eu.hex.tech/.well-known/oauth-authorization-server),
+[HIPAA metadata](https://auth.hc.hex.tech/.well-known/oauth-authorization-server).
+
+After the setup caller has authorization to create a provider client:
+
+```js
+const registration = await registerHexClient({
+  endpoint: "standard",
+  clientName: "My assistant",
+  callbackUrl: "https://assistant.example/connections/hex/callback",
+  scopes: ["openid", "profile", "email", "offline_access"]
+});
+// Persist registration.clientSecret through the existing secret owner.
+// Save registration.clientId in configuration; never log the whole result.
+```
+
+The helper uses the MCP SDK with one exact callback, code/refresh grants and
+`client_secret_post`. It validates returned client and redirect metadata and
+returns `clientId`, `clientSecret` and any `clientSecretExpiresAt`. HTTPS and
+HTTP loopback callbacks are accepted; credentials, query and fragment are not.
+The host owns authorization to invoke this helper and storing its result.
+
+An AI with an authorized setup API can prepare configuration and call this
+helper. It cannot complete human consent, change provider entitlements or
+promise registration acceptance from metadata alone. No live registration was
+performed. Failed or interrupted registration must not be automatically retried;
+the provider might already have created a client. The equivalent manual HTTP
+operation is a JSON POST to the selected issuer's `/oauth2/register` with the
+helper's `client_name`, `redirect_uris`, `token_endpoint_auth_method`,
+`grant_types`, `response_types` and space-delimited `scope` fields.
+
+## Portable configuration and runtime
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "hex": {
+      "source": "own",
+      "clientId": "assigned-client-id",
+      "clientSecretRef": "env:HEX_CLIENT_SECRET",
+      "callbackUrlRef": "env:HEX_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "analysis": {
+      "provider": "hex",
+      "accountMode": "assistant",
+      "scopes": ["openid", "profile", "email", "offline_access"],
+      "authentication": { "method": "oauth2", "registrationRef": "hex" },
+      "settings": { "endpoint": "standard" }
+    }
+  }
+}
+```
+
+CLI and UI validate the same configuration. `endpoint` defaults to `standard`;
+`eu` and `hipaa` select their respective fixed MCP/issuer pair. No arbitrary
+provider URL is accepted. Changing endpoint invalidates a pending attempt and
+requires reconnecting an existing grant. Configuration stores references;
+runtime grants and attempts use the host-selected file store.
+
+Compose the existing `oauth-connection` and `assistant-mcp-oauth` patterns with
+this provider. Both operations require granted `openid`. All four permissions
+are selected initially; profile/email/refresh can be omitted. Identity scopes
+are not a read-only tool boundary. The host must authorize the exact tool name,
+arguments, workspace and intended effect. Obtain argument schemas from
+`tools.list`, which accepts an explicit cursor; do not guess Thread fields.
+`tools.call` preserves the result and `isError` flag. Listing tools does not
+grant permission to run an analysis or consume credits.
+
+The library does not automatically poll a Thread, fetch all discovery pages,
+retry a call or attach tools to an AI. The host schedules any explicit follow-up
+read and displays its status. Disconnect removes the local grant, not provider
+work already accepted. OAuth here does not implement login to an application.
+
+## Connection ownership and callbacks
+
+This fragment is for an explicitly configured assistant host. That host owns its
+client registration, callback, private credentials and grants; it may be an
+application-owned assistant or an opt-in editor tool. Merely adding the provider
+to a project does not authorize the editor's coding assistant. It does not supply
+published app-user login. The host's callback may differ from the published app's
+domain, but it must match that host's real route and registered redirect URI.
+
+Register this host's actual callback for the selected Standard, Europe or HIPAA
+endpoint. Its selected endpoint and credentials belong to this connection; keep
+runtime records bound to that owner. Update registration and callback Env when
+the actual callback changes. Separate clients do not establish separate Hex
+workspace credits or capacity. Provider accounts, plans and workspace permissions
+still apply. Selecting the HIPAA endpoint is a routing choice, not a compliance
+certification for JSKIT, Vibe64 or a generated application. The explicit registration and controlled connection UI have been reviewed.
+The explicit Register client and connect action supports DCR; ordinary Connect
+does not silently create another registration.
+
+## Focused verification and limits
+
+The controlled tests exercise selected endpoints, PKCE/resource binding,
+registration request/response validation, file restart and encryption, refresh,
+owner and tool policy, consent/permission failures, pagination, redacted errors
+and interruption without replay. Browser proof covers endpoint/permission and
+reference persistence. Live registrations, consent, actual Hex tool calls,
+single-tenant hosts, provider billing and real generated applications are not
+part of that proof. The separate Hex REST API/token mode is not implemented.
+
+**LIMITATIONS:** Editor coding-assistant attachment and notebook/Thread widgets
+are deferred. For example an app-owned MCP host can call Hex project or Thread
+tools after its own permission checks, but adding this form does not let Vibe64
+Codex/OpenCode analyze the workspace. The app owns tool discovery/schema use,
+status polling, output rendering, sensitive data policy and credit approval.
+Single-tenant custom hosts, REST/token mode and live Hex execution remain outside
+this adapter. Other frameworks use their native MCP client and the same project
+configuration/Env; they do not need JSKIT or a Node sidecar.

package/docs/heygen.md

@@ -0,0 +1,124 @@
+# HeyGen
+
+Import `heygenProvider` from `@jskit-ai/connectors-catalog/server/heygen`.
+This fragment uses the v3 API to read the current profile and voice catalogue.
+
+## Configure access
+
+1. Sign into the intended HeyGen account. Open the
+   [API dashboard](https://app.heygen.com/home?from=&nav=API), also linked from
+   the provider guide, and generate an API key.
+2. Restrict the key to `account:read` for profile verification and `voices:read`
+   for voice listing. Copy it into backend Env as `HEYGEN_API_KEY`. API-key billing and
+   subscription OAuth are separate arrangements; use a key for the REST mode.
+   [Key setup](https://developers.heygen.com/docs/api-key).
+3. Save provider `heygen`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication `{ "method": "api-key", "secretRef": "env:HEYGEN_API_KEY" }`.
+4. In the screen, Save configuration, choose Set credential in Env, save the
+   actual key as `HEYGEN_API_KEY`, then return and choose Connect account.
+   CLI applications run `connectApiKey`. The verifier calls `GET /v3/users/me`, which returns
+   profile and billing fields under `data`. Replace the provider key in Env
+   when rotating it; local disconnect does not revoke remote access.
+   [Profile endpoint](https://developers.heygen.com/reference/get-current-user).
+
+## Runtime and AI composition
+
+`profile.read` accepts no inputs. `voices.list` reads `GET /v3/voices` and
+accepts `limit` (1–100, default 20), `token`, `type` (`public` by default or
+`private`), `engine`, `language` and `gender` (`male` or `female`). Pass the
+returned `next_token` as `token` when `has_more` is true. These calls use
+`x-api-key` against `https://api.heygen.com`; neither creates speech or video.
+[Voice endpoint](https://developers.heygen.com/reference/list-voices).
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with this
+provider and the private JSON store. AI-written applications can select voice
+IDs from the catalogue; generation, consent to cloning, billing and job handling
+remain additional application work. No arbitrary endpoint is accepted as input.
+
+## Automation and application ownership
+
+The verified key bootstrap is the API dashboard. An AI can prepare JSON and
+library composition afterwards; this pass does not establish a key-creation API.
+The application owner supplies its key through private Env and arranges provider
+billing/capacity. Two named keys alone do not create independent budgets.
+Subscription provisioning remains provider-owned. Browser OAuth is available through the separate MCP mode below.
+
+Tests cover profile verification, voice filters, paging, defaults, private-file
+restart, key replacement, isolation, disconnect and provider errors. They use
+simulated responses and do not create media or access a real HeyGen account.
+
+
+## MCP OAuth connection
+
+The captured Lovable chat connection opened HeyGen OAuth. The current
+[MCP guide](https://developers.heygen.com/mcp/overview) still describes browser
+OAuth at `https://mcp.heygen.com/mcp/v1/`, drawing on the connected account's
+plan. The same provider now exposes that path as OAuth with `tools.list` and
+`tools.call`. The runtime rejects cross-method operations before refresh or
+transport. Neither current authentication mode is retired.
+
+On 2026-09-12, the MCP host's authorization-server metadata redirected to
+`https://api2.heygen.com/.well-known/oauth-authorization-server`. That published
+metadata advertises issuer `https://api2.heygen.com`, authorization/token/client
+registration at `/v1/oauth/authorize`, `/v1/oauth/token`, `/v1/oauth/register`,
+S256, code/refresh grants, resource indicators and identity scopes `openid`,
+`profile`, `email`. It supports confidential and public client authentication.
+The protected-resource metadata identifies `https://mcp.heygen.com` as the
+OAuth resource, distinct from the transport endpoint's `/mcp/v1/` path. The
+adapter uses that root resource in authorization and token requests and reuses
+the existing MCP transport and method-specific connection lifecycle. No live
+client was registered or account connected during this inspection.
+
+To configure the OAuth assistant connection:
+
+1. Select Assistant access and OAuth. Keep `openid`, `profile`, `email` selected.
+2. Confirm Suggested callback URL is the route the host will serve. Choose
+   Register client and connect: the public editor invokes the fixed-authority
+   helper and saves ID, secret and callback in project configuration/private Env.
+   Manual fallback: send one POST to the displayed endpoint with its JSON body
+   and Content-Type application/json. CLI users can call
+   `registerHeyGenClient({ clientName, callbackUrl })`, exported beside the provider.
+3. For manual registration, copy `client_id` into Client ID and Save configuration. Use Set credential in
+   Env to save `client_secret` under the displayed reference; use Set callback
+   in Env to save the exact registered callback. Keep the response private.
+4. Return, save and Connect account. Sign into HeyGen and approve consent.
+   Verification lists tools and creates no media. The host must authorize each
+   tool name and arguments; tools can incur credits and change or delete content.
+5. Reconnect repeats consent. Disconnect removes local state, does not undo work
+   and does not promise provider-wide revocation.
+
+The application/assistant host owns its registration, callback, Env and grants.
+There is no Vibe64 gateway. Ordinary Connect never silently registers a client;
+the explicit Register client and connect action uses the existing helper. Metadata
+advertises a revocation endpoint, but this adapter's Disconnect remains local;
+no provider-wide revocation claim is made. Both credential instruction screens were rendered and reviewed with controlled
+connection fixtures on 2026-09-12. Live provider authorization remains untested.
+
+[API-key permission mapping](https://developers.heygen.com/docs/api-key-permissions)
+confirms the read scopes required by this REST fragment. Provider keys and MCP
+grants remain distinct; do not send one credential type to the other service.
+
+## Media tools and limits
+
+Use `tools.list` to obtain the connected account's current tool names and input
+schemas; the [MCP guide](https://developers.heygen.com/mcp/overview) describes
+video creation/status, avatars, speech and translation (reviewed 2026-09-13).
+The host invokes `tools.call` with the discovered schema, checks `isError`, and
+polls the corresponding status tool for asynchronous work. API-key profile/voice
+reads are not a substitute for these OAuth media tools. Identity scopes do not
+make tool calls read-only: the application must authorize the exact tool and
+arguments before calling, and confirm chargeable/destructive operations. Do not
+retry an uncertain creation blindly; reconcile its session/job ID first.
+
+**LIMITATIONS:** No editor-assistant attachment, video editor, automatic media-job
+worker or API-key media generation is included. Example: an authorized MCP host
+can submit a video request and retrieve its status, but this form alone does not
+make Codex create a video or render progress. The app owns polling, downloads,
+user consent, content rights and credit limits. Fixtures prove transport and
+host policy, not actual media generation or current plan entitlement.
+
+CLI Node applications use the same exported provider and registration helper,
+JSON and Env without Vibe64. Other frameworks use their native MCP/OAuth client
+with those same project-owned configuration values; no JSKIT runtime or Node
+sidecar is required. Select tools from discovery rather than hard-coding this
+module's example catalogue as permanent provider API contracts.

package/docs/hubspot.md

@@ -0,0 +1,142 @@
+# HubSpot
+
+Import `hubspotProvider` from `@jskit-ai/connectors-catalog/server/hubspot`.
+The adapter manages contacts, deals and their relationships using a private/static token or a project-owned OAuth
+registration. Each-user connections are isolated by application subject identity.
+
+## Configure access through the console
+
+1. As a HubSpot super admin, select the account that owns the CRM data.
+2. Open **Development → Legacy apps → Create legacy app → Private**.
+3. In **Basic Info**, enter an identifying name and description.
+4. Open **Scopes → Add new scope**, find `crm.objects.contacts.read`, select
+   it, and click **Update**. For writes add `crm.objects.contacts.write`; for deals/pipelines add
+   `crm.objects.deals.read`, and for deal writes/relationships add
+   `crm.objects.deals.write`. Match the selected permissions in configuration.
+5. Click **Create app**, then **Continue creating**. Open the app's **Auth** tab
+   and use **Show token → Copy**. Store the token in backend Env.
+6. In `integrations.json`, use provider `hubspot`, mode `shared` or `assistant`,
+   `scopes: ["crm.objects.contacts.read"]`, and authentication `{ "method": "api-key", "secretRef":
+   "env:HUBSPOT_API_KEY" }`. Verify through `connectApiKey`.
+7. Use the Auth tab to rotate/revoke the token and update its Env value.
+   [Private-app console guide](https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview).
+
+## Runtime and AI composition
+
+`contacts.list` calls `GET https://api.hubapi.com/crm/objects/2026-09/contacts`
+with a Bearer token. Inputs: `limit` (1–100, default 20), optional `after`,
+and `archived` (default false). Results include `results` and optional
+`paging.next.after`, which the caller passes to the next request. This operation
+also verifies the credential. See the [contacts contract](https://developers.hubspot.com/docs/api-reference/latest/crm/objects/contacts/guide).
+
+Compose the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with
+this provider. A new-platform static token uses the same authentication mechanism;
+OAuth consent and refresh use the existing connection lifecycle.
+
+## Provisioning automation and quota separation
+
+HubSpot's current developer platform supports CLI provisioning after account
+authentication. An AI can prepare distinct app UIDs, scopes and configuration,
+then use the documented `hs project create` and upload workflow. Choose private
+distribution/static authentication for one account, or an appropriate OAuth
+distribution for multiple accounts. Operator account authorization and installation
+still occur. The legacy console route above is available without requiring this
+developer-project workflow.
+[CLI app creation](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app),
+[authentication modes](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/overview).
+
+Create a private app and credentials for the application owner. Private-app burst
+limits may be app-specific while daily limits are account-wide; two private apps
+in one account therefore do not fully isolate capacity. Application usage must
+respect both boundaries. Tests simulate pagination, file persistence, key rotation,
+cross-app isolation, bad credentials and rate limits. No CRM account was contacted.
+
+## OAuth registration and project setup
+
+1. Follow the [developer-project guide](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app)
+   to authenticate HubSpot CLI and run `hs project create`. Select App and OAuth.
+2. Configure `src/app/app-hsmeta.json`: `config.auth.type` is `oauth`,
+   `redirectUrls` contains this project's exact Suggested callback URL, and
+   `requiredScopes` includes `oauth` and `crm.objects.contacts.read`. Upload with
+   `hs project upload`. The callback belongs to the application backend.
+3. Run `hs project open`, choose the app under Project Components, and open
+   **Auth → Client credentials**. Copy Client ID into the integration form.
+   Save configuration, use **Set credential in Env** for the client secret, and
+   **Set callback in Env** for the exact registered callback.
+4. Keep both permissions selected. Shared access connects from project settings;
+   per-user access connects from the application's account screen. Application
+   login is separate. Tokens and refresh credentials stay in its private store.
+5. Disconnect deletes the local grant. Remove the installation in HubSpot
+   separately when provider access must end. No provider-wide revocation is
+   implemented here.
+
+Private OAuth distribution is limited to ten allowlisted HubSpot accounts; use
+HubSpot's marketplace distribution process for broader distribution. See the
+[authentication overview](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/overview).
+The normal installation is account-level: a per-user local grant does not promise
+that HubSpot restricts records to that person's ownership. The app must enforce
+business authorization. See [app access configuration](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration).
+
+The [current token API](https://developers.hubspot.com/docs/api-reference/latest/authentication/manage-oauth-tokens)
+uses `https://api.hubspot.com/oauth/2026-09/token` for code and refresh exchanges.
+Client credentials are form-body values; the documented confidential flow does
+not use PKCE. Authorization opens `https://app.hubspot.com/oauth/authorize`.
+The adapter converts the response's `scopes` array into the shared runtime's
+permission format and rejects malformed grants. Missing contact permission
+prevents contact reads even after refresh. There is no central token gateway.
+
+Three OAuth cases and two API-key cases passed with controlled fixtures. Both
+credential screens were rendered and reviewed on 2026-09-12. No live installation,
+CRM request or generated-app execution is claimed.
+
+## Lead-to-deal workflow
+
+The current [contact](https://developers.hubspot.com/docs/api-reference/latest/crm/objects/contacts/guide),
+[deal](https://developers.hubspot.com/docs/api-reference/latest/crm/objects/deals/guide),
+[association](https://developers.hubspot.com/docs/api-reference/latest/crm/associations/associate-records/guide)
+and [pipeline](https://developers.hubspot.com/docs/api-reference/latest/crm/pipelines/guide)
+contracts were reviewed 2026-09-13. Operations use the documented 2026-09 routes.
+
+`contacts` and `deals` each expose `.list`, `.get`, `.create`, `.update`.
+Lists accept limit/after, archived, comma-separated properties and associations;
+get takes numeric-string `id` plus those read fields except limit/after. Writes
+accept a `properties` object of 1–100 string values, at most 100KB. Empty string
+clears a value. Contact creation requires email, firstname or lastname. Deal
+creation requires dealname and the internal dealstage ID; set pipeline when the
+account has multiple pipelines. `.update` requires `id` and does not replace
+unspecified properties. HubSpot validates property types and business rules.
+
+`pipelines.list` returns deal pipeline/stage IDs. `deals.associateContact` takes
+numeric-string `dealId` and `contactId`, creating the default unlabeled relation.
+It requires both contact and deal write permissions. Object reads/writes require
+the corresponding `crm.objects.contacts|deals.read|write` scope. Update provider
+permissions and consent as needed; ticking this screen cannot grant provider access.
+
+```js
+// `connection`, `context` and integrationId come from the app-owned runtime.
+const call = (operation, input = {}) => connection.invoke({ context, integrationId, operation, input });
+const pipelines = await call("pipelines.list");
+// Select the intended pipeline and stage from returned IDs; never assume a label.
+const pipeline = pipelines.results.find(item => item.id === selectedPipelineId);
+const contact = await call("contacts.create", { properties: { email: customer.email, firstname: customer.name } });
+const deal = await call("deals.create", { properties: {
+  dealname: "Grooming booking", pipeline: pipeline.id, dealstage: selectedStageId, amount: "80.00"
+} });
+await call("deals.associateContact", { contactId: contact.id, dealId: deal.id });
+// On the app's authorized booking-confirmed event:
+await call("deals.update", { id: deal.id, properties: { dealstage: confirmedStageId } });
+```
+
+The application owns triggering events, record access checks and duplicate
+prevention. Persist returned IDs; reconcile partial/uncertain writes instead of
+blindly retrying creation. The library performs no hidden workflow or sync.
+CLI JSKIT apps use the same JSON/Env and exported provider without the editor;
+other frameworks use their native HTTP/HubSpot client with the same project
+configuration and operation sequence. Keys and tokens stay server-side.
+
+**LIMITATIONS:** No CRM dashboard, workflow designer/engine, webhook receiver,
+bulk import/sync, custom association labels, company/ticket API or archive/delete
+operations. Example: a booking app can create a linked deal and advance its stage,
+but it must supply the trigger and cannot import an entire CRM automatically.
+Editor-assistant attachment is deferred. Fixture success does not prove live CRM
+installation, property availability, subscription features or generated-app use.

package/docs/incident-io.md

@@ -0,0 +1,118 @@
+# incident.io
+
+Import `incidentIoProvider` from
+`@jskit-ai/connectors-catalog/server/incident-io`.
+The adapter reads and manages incidents, follow-ups and catalogue entries,
+resolves alerts and reads schedules using an organization's API key.
+
+## Configure access
+
+1. Select the intended incident.io organization. Open **Settings**, then
+   **API keys**, and create a key named for this application.
+2. Grant `viewer` access to the relevant incidents. Review account and team
+   permissions before creating the key; for writes add Create incidents / Edit incidents, for alert/schedule
+   reads choose View on-call resources / Read schedules, and for catalogue
+   access choose View catalog / Manage catalog. Inspect each permission
+   scopes badge: follow-up writes require `follow_ups.create` and
+   `follow_ups.update`; alert resolution requires `alerts.resolve`. Restrict
+   team-scoped permissions to intended teams. The token cannot exceed your
+   own authority.
+3. Copy its value into backend Env as `INCIDENT_IO_API_KEY`.
+4. Save provider `incident-io`, mode `shared` or `assistant`, `scopes: []`,
+   authentication
+   `{ "method": "api-key", "secretRef": "env:INCIDENT_IO_API_KEY" }`.
+5. In the form Save configuration, choose Set credential in Env and store the
+   key, then return to Connect account. CLI apps run `connectApiKey`. It verifies incident access by reading the list, not by
+   creating an incident. Manage or revoke the provider key from API keys;
+   local disconnect does not revoke it remotely.
+   [API introduction](https://docs.incident.io/api-reference/introduction).
+
+## Runtime and AI composition
+
+`incidents.list` uses `GET https://api.incident.io/v2/incidents` with Bearer
+authorization. Inputs are `page_size` (1–500, default 25), optional `after`,
+and `sort_by` (`created_at_newest_first`, the default, or
+`created_at_oldest_first`). The response retains incident records and optional
+`pagination_meta`. Pass its `after` value for the next page; absence of paging
+metadata is valid. The fragment does not implement all server-side filters.
+[Endpoint schema](https://docs.incident.io/openapi/tags/incidents-v2.json).
+
+The [API-key pattern](../patterns/api-key-connection/PATTERN.md) supplies
+configuration, connection-service and JSON file-store composition for CLI or
+editor consumers. The application decides which users can read its shared
+incident data.
+
+## Automation and application ownership
+
+After an administrator creates a bootstrap key with `api_keys_manage`, an AI
+can provision additional keys through `POST /v1/api_keys`. Supply a name,
+account `role_names`, and any intended team IDs/team roles. The caller may
+delegate only a subset of its own authority; the API cannot delegate
+`api_keys_manage`. Capture the returned secret in the backend environment.
+Key creation is an administrative action, not part of connection verification.
+[Key API schema](https://docs.incident.io/openapi/tags/api-keys-v1.json).
+
+Application keys can be provisioned and revoked independently, but shared
+provider limits may still apply. Renaming keys is insufficient proof of isolated
+capacity. The application owner supplies its authorized key through private Env.
+
+Tests cover ordering, paging, omitted metadata, malformed results, restart,
+rotation, isolation and 401/403/429 failures without live incident access.
+
+## Incident recovery and catalogue operations
+
+Contracts reviewed 2026-09-13 from the provider's OpenAPI:
+[incidents](https://docs.incident.io/openapi/tags/incidents-v2.json),
+[follow-ups](https://docs.incident.io/openapi/tags/follow-ups-v2.json),
+[alerts](https://docs.incident.io/openapi/tags/alerts-v2.json),
+[schedules](https://docs.incident.io/openapi/tags/schedules-v2.json),
+[catalogue](https://docs.incident.io/openapi/tags/catalog-v3.json).
+
+- `incidents.get({id})`, `.create({idempotency_key, visibility, name?, summary?,
+  severity_id?, incident_status_id?, incident_type_id?, mode?})`; mode defaults
+  to standard. Set public/private visibility explicitly. Standard incidents can
+  create Slack announcements. Retain the event's idempotency key across retries.
+- `incidents.update({id, incident, notify_incident_channel})` edits only supplied
+  name, summary, severity_id or incident_status_id. The notification choice is
+  mandatory. Copy status/severity IDs from your account's records/API, not labels.
+- `followUps.list({incident_id?, incident_mode?, assignee_team_id?})`, `.get({id})`,
+  `.create({incident_id,title,description?,assignee_id?,assignee_team_id?,
+  follow_up_category_id?,follow_up_priority_option_id?})`; `.update` takes `id`,
+  required current title and status, plus those optional editable fields.
+  Status is outstanding/completed/deleted/not_doing. Fetch the current record
+  before updating; this is the provider's PUT contract, not a partial PATCH.
+- `alerts.list({page_size?,after?})` (maximum 50), `.get({id})`, `.resolve({id})`.
+  Already-resolved alerts are a provider no-op. Externally resolved sources can
+  return 422; resolve those in their source system. Private alerts need provider
+  permission and may otherwise appear as 404.
+- `schedules.list({page_size?,after?})` caps pages at 25 to retain next_shifts;
+  `.get({id})` reads a schedule. No rota creation or override management.
+- `catalog.types()`, `.list({catalog_type_id,page_size?,after?,identifier?})`
+  (maximum 250), `.get({id})`, `.create({catalog_type_id,name,attribute_values,
+  external_id?})`, `.update({id,name,attribute_values,external_id?})`.
+  Bind attribute IDs to `{value:{literal:"..."}}` or
+  `{array_value:[{literal:"..."}]}`. Maximum 250 attributes / 100KB, with up to
+  100 array values. Fetch existing values and send the intended full map when
+  updating. Matching external_id/catalog_type_id on creation can update an
+  existing entry; authorize that target first. Provider schemas determine which
+  attribute IDs/types are valid.
+
+For example, an app receives its own outage event, creates an incident with a
+stable idempotency key, assigns a follow-up, reads the next on-call shift and
+updates the recovery summary. After recovery it explicitly resolves an eligible
+alert and marks the follow-up completed. All triggers, authorization, correlation
+IDs and retry/reconciliation decisions belong to that app. The connector performs
+one requested operation at a time; verification never creates incidents.
+
+The UI, CLI and AI-written Node apps use the same JSON/Env and exported runtime.
+Other frameworks use their native HTTP client with the same configuration and
+provider contracts. No editor or JSKIT process is required in their deployment.
+No OAuth registration/callback is needed. AI may prepare configuration and key
+provisioning after an authorized bootstrap key; the owner supplies initial access.
+
+**LIMITATIONS:** No incident dashboard, scheduling/paging engine, alert ingestion,
+workflow engine, webhook receiver, postmortem importer, custom-field/role editing,
+catalogue schema editing or bulk synchronizer. Example: an app can show the next
+shift and resolve an alert, but cannot generate a rota or start monitoring servers
+just by connecting. Editor-assistant attachment is deferred. Fixture tests do not
+prove live delivery, role entitlement or provider-side workflow effects.