@jskit-ai/connectors-catalog 0.1.1

package/docs/slack.md

@@ -0,0 +1,257 @@
+# Slack
+
+## Delivered connector
+
+Import `slackProvider` from `@jskit-ai/connectors-catalog/server/slack`.
+It completes an own-registration OAuth flow as either the connecting person or
+an installed bot, then reads channel lists, message history and user profiles, and posts text messages. The
+shared library owns consent, token selection, refresh, operation validation and
+encrypted file persistence. Application code supplies authenticated ownership,
+reference resolution and callback routes. No database is required.
+
+The configuration form retains the captured 57 distinct permissions: 52 apply to
+users and 49 to bots. Its initial selection is `channels:read` and
+`channels:history`; only `channels:read` is needed for the implemented connection
+check. Keep history when using channels.history; deselect it for list-only applications. Saving another permission does not
+implement its operation. Switching actor removes incompatible permissions and
+preserves compatible selections; switching back does not restore removed ones.
+
+`settings.actor` and `accountMode` answer different questions. Actor selects the
+Slack identity, while account mode controls ownership in the application. An
+individually owned bot connection still acts as the installed workspace bot;
+it does not become a personal Slack account. Host membership checks remain
+necessary before exposing a shared connection. This adapter implements neither
+application login nor workspace-member administration.
+
+## Manual provider setup
+
+1. Open [Your Apps](https://api.slack.com/apps), select **Create New App**, then
+   **From scratch**. Enter an **App Name**, select the **Development Workspace**,
+   and create it. Use an account authorized to manage that workspace's apps.
+2. Open **OAuth & Permissions**. Under **Redirect URLs**, choose **Add New Redirect
+   URL**, enter the backend's complete HTTPS callback, and save the URLs. A plain
+   HTTP localhost callback is not accepted by Slack. A CLI can use its own HTTPS
+   backend or an HTTPS development tunnel; the editor is not required.
+3. Under **Scopes**, add `channels:read` in **User Token Scopes** for a connected
+   user or **Bot Token Scopes** for an installed bot. Add the other read scopes
+   from the operation table only when needed. Configure a bot identity under
+   **App Home** if the dashboard requests it for a bot installation.
+4. In **Basic Information → App Credentials**, copy **Client ID** into the
+   registration. Keep **Client Secret** outside source, under the referenced
+   environment variable. Supply the same callback URL through its reference.
+
+See Slack's [OAuth installation guide](https://docs.slack.dev/authentication/installing-with-oauth/)
+and [app credential details](https://docs.slack.dev/authentication/using-token-rotation/).
+
+5. For new rotating grants, enable token rotation under **OAuth & Permissions**
+   before installation. Published apps use **Published App Settings**. Slack
+   makes this setting irreversible. The fragment supports both rotating and
+   non-rotating new grants; converting an existing long-lived grant with
+   `oauth.v2.exchange` is not implemented.
+   [Rotation setup](https://docs.slack.dev/authentication/using-token-rotation/).
+6. To install outside the development workspace, open **Manage Distribution →
+   Share Your App with Other Workspaces**, complete the displayed checklist,
+   then choose **Activate Public Distribution**. Slack directs commercially
+   distributed apps through Marketplace review. Workspace administrators can
+   require approval or restrict installation to listed apps.
+   [Distribution and approval](https://docs.slack.dev/app-management/distribution/).
+7. Save the application configuration below, start its separate consent flow,
+   choose a workspace, and approve the requested permissions. Saving a form
+   alone does not install anything or report a connected account.
+
+## Portable configuration
+
+The same `integrations.json` is usable by CLI code and Vibe64's form. Replace
+the Client ID placeholder and supply the two referenced environment values.
+No client secret, access token or refresh token belongs in this file.
+
+```json
+{
+  "schemaVersion": 1,
+  "integrations": {
+    "slack": {
+      "provider": "slack",
+      "displayName": "Team Slack",
+      "accountMode": "per-user",
+      "settings": { "actor": "user" },
+      "scopes": ["channels:read"],
+      "authentication": { "method": "oauth2", "registrationRef": "slack" }
+    }
+  },
+  "registrations": {
+    "slack": {
+      "source": "own",
+      "clientId": "replace-with-your-client-id",
+      "clientSecretRef": "env:SLACK_CLIENT_SECRET",
+      "callbackUrlRef": "env:SLACK_CALLBACK_URL"
+    }
+  }
+}
+```
+
+Set `actor` to `bot` for installation as a bot. Use `shared` only when the host's
+policy maps authorized workspace members to the intended shared subject.
+`assistant` ownership is also available; it does not bypass application policy.
+The [OAuth connection pattern](../patterns/oauth-connection/PATTERN.md) shows
+parsing, service composition, encrypted file storage and callback handling.
+Use `slackProvider` in its provider array. Keep runtime state outside exported
+source and retain its encryption key across restarts.
+
+## Operations and errors
+
+| Operation | Required permission | Result |
+|---|---|---|
+| `auth.test` | No additional scope | Connected Slack team and user identity |
+| `channels.list` | `channels:read` | Public-channel metadata; also the connection check |
+| `groups.list` | `groups:read` | Private-channel metadata visible to this identity |
+| `directMessages.list` | `im:read` | Direct-message conversation metadata |
+| `groupMessages.list` | `mpim:read` | Group direct-message conversation metadata |
+
+Every list accepts optional `limit` (integer 1–200, default 100), `cursor`
+(opaque nonempty string) and `exclude_archived` (boolean, default false).
+It returns one provider page. Pass `response_metadata.next_cursor` to continue,
+including after an empty filtered page. No automatic paging occurs. Callers
+cannot supply `types`, `team_id`, another API origin or a raw token. This is a
+workspace-installation fragment; organization-wide installation needs additional
+team-selection handling. [Conversation lists](https://docs.slack.dev/reference/methods/conversations.list/),
+[identity check](https://docs.slack.dev/reference/methods/auth.test/).
+
+Consent uses `user_scope` for the person and `scope` for the bot. Code exchange
+selects only the requested identity; it cannot silently substitute the other
+token in a response containing both. Refresh validates the same identity.
+Slack's `ok:false` bodies are failures even with HTTP 200. The adapter maps
+revocation, missing permissions, rate limits and malformed replies into bounded
+errors without exposing provider bodies. [OAuth token response contract](https://docs.slack.dev/reference/methods/oauth.v2.access/).
+
+The shared service refreshes expiring grants before data requests, serializes
+refresh under the connection lock, and stores new credentials before reuse.
+It starts no background scheduler. Non-expiring grants do not invent an expiry.
+Actor or registration changes invalidate existing attempts and connections.
+Cancelled attempts cannot be completed later. Disconnect removes local access;
+it does not uninstall the Slack app or revoke every grant in that workspace.
+
+Socket mode, slash commands, organization-wide
+installs, GovSlack and Sign in with Slack are outside this initial fragment.
+
+## Online, public editor and automation
+
+Each application owns its provider registration, callback route, credentials
+and grants. Hosted and installed editors configure the same app-owned setup;
+neither supplies a shared Vibe64 registration or token gateway. Use the app's
+assigned public URL as the initial callback origin, append the route the backend
+actually implements, and register the exact URL with the provider. Keep the
+client secret and callback binding in the application's Env.
+
+A custom-domain or hosting move that changes the callback requires updating both
+the provider registration and the app's Env. Preserve the application's identity
+and private connection store, validate callback state and initiator, and allow
+only application-approved return destinations. The editor's address is not the
+provider callback. See the [callback contract](../../connectors-core/docs/oauth-callbacks.md)
+and [setup command](../../connectors-core/docs/setup-command.md).
+
+Provider distribution approval and workspace administrator decisions apply to
+the actual application. Separate app registrations cannot bypass them.
+
+Slack generally meters Web API traffic by method, workspace and app. Callers sharing one registration and Slack workspace share its method allowance. Message delivery and other features have additional limits.
+Application scheduling should respect those actual keys and
+`Retry-After`; this fragment reports throttling without replay or a scheduler.
+Commercial non-Marketplace history/reply access has additional restrictions, so
+future message-reading work must use the then-current method limits.
+[Rate-limit ownership](https://docs.slack.dev/apis/web-api/rate-limits/).
+
+**API-assisted registration is possible after operator authorization.** On
+**Your Apps**, locate **Your App Configuration Tokens → Generate Token**. This
+credential is bound to an operator and development workspace, not one app. Keep
+it in the provisioning service; never give it to customer apps. It expires after
+12 hours and has its own `tooling.tokens.rotate` flow, separate from the runtime
+OAuth refresh implemented here. [Manifest API credentials](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/).
+
+An AI-assisted provisioning tool can prepare each app manifest, validate it
+through `apps.manifest.validate`, create it with `apps.manifest.create`, and
+update it with `apps.manifest.update`. The manifest holds the display name,
+redirect URLs, user/bot scopes and desired rotation setting. Create each product
+registration separately and record the returned `app_id`, `credentials.client_id`
+and secret through protected operator storage. Check `ok` and validation errors
+before marking provisioning complete. The create response contains secrets and
+must not be logged or copied into a project JSON file.
+[Creation API](https://docs.slack.dev/reference/methods/apps.manifest.create/).
+
+The operator still supplies ownership, distribution information, approval and
+consent. This package documents that automation path; it does not ship or run a
+registration provisioner. For a manual manifest path, select **Create New App →
+From a manifest**, select the workspace, paste JSON/YAML, review and create.
+[Manifest UI](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/).
+
+## Verification boundary
+
+Controlled local tests exercise both identities, encrypted file restart,
+rotating and non-rotating grants, scope restrictions, cancellation, actor changes,
+bounded paging, HTTP-200 failures, malformed responses and interruption. Shared
+form tests and Vibe64 browser tests cover conditional scopes and file round trips.
+No live Slack registration, provider consent, customer data or generated app is
+part of this proof. Current controlled source and installed-package suites each pass 17/17.
+Current-source compact and expanded editor cases pass separately, including
+actor/scope persistence, signing-secret reference, inline guidance, per-user
+connection instructions and shared connect/cancel/disconnect controls. Registration
+provisioning remains an operator action; editor coding-assistant attachment is
+deferred.
+
+
+## Message operations
+
+- `channels.history`, `groups.history`, `directMessages.history` and
+  `groupMessages.history` take `channel`, optional `cursor`, `oldest`, `latest`
+  and `inclusive`. Each requires its matching `*:history` scope. A request reads
+  one page, at most 15 entries; callers explicitly request subsequent pages.
+  This bound accommodates the restricted commercially distributed app allowance.
+  Slack still enforces actual channel membership and method rate limits.
+- `users.info({ user })` requires `users:read`. It returns a profile; email needs
+  an additional provider permission and is not promised by this operation.
+- `messages.send({ channel, text, thread_ts? })` requires `chat:write` and posts
+  as the connected actor. Text is bounded to 4,000 characters; link/media unfurls
+  default off. A thread timestamp is optional. No automatic mutation retry occurs:
+  after an uncertain response, inspect the conversation before retrying.
+
+In **OAuth & Permissions**, add the corresponding scope under the selected
+user or bot token section, update project configuration and reconnect. Invite
+bots to the intended channel. Application code must authorize which local users
+can invoke a shared grant before calling these operations. This does not add
+Sign in with Slack or automatically expose all workspace messages.
+
+Method references: [history](https://docs.slack.dev/reference/methods/conversations.history/),
+[posting](https://docs.slack.dev/reference/methods/chat.postMessage/),
+[user profiles](https://docs.slack.dev/reference/methods/users.info/).
+These operations use the same application-owned connection as channel discovery.
+
+
+## Incoming events and interactions
+
+Set optional `settings.signingSecretRef` to `env:SLACK_SIGNING_SECRET`; supply the
+value from **Basic Information → App Credentials → Signing Secret** in the app
+Env. This is a separate credential from the OAuth client secret. Implement an
+HTTPS application event route, then enable **Event Subscriptions**, set its
+**Request URL**, subscribe to needed bot/user events and reinstall when scopes
+change. For buttons/views, enable **Interactivity & Shortcuts** and supply an
+application interaction route. These are not OAuth redirect URLs.
+
+Import `verifySlackRequest` from the same provider export. Pass `rawBody` as
+unmodified bytes before JSON/form parsing, `signature` from `X-Slack-Signature`,
+`timestamp` from `X-Slack-Request-Timestamp`, `contentType`, resolved `secret`,
+and the installation's expected `appId` and `teamId`. Header lookup must be
+case-insensitive. The verifier enforces Slack's five-minute timestamp window,
+HMAC signature and installation identity, then returns the authenticated JSON
+or form-encoded interaction payload. It supports event callbacks, URL challenge,
+block actions, view submission/close and shortcuts/message actions.
+
+The route returns the authenticated URL challenge when requested. Otherwise,
+acknowledge within three seconds and use application-owned processing. Deduplicate
+events by `event_id`; freshness alone does not prevent replay within the window.
+Authorize `user.id`, action identifiers and business-object access before changing
+anything. Persist action idempotency where duplicates would matter. A signed
+request establishes Slack origin, not permission to act on arbitrary app data.
+Do not fetch payload `response_url` or execute arbitrary payload actions blindly.
+Enterprise-wide installs without a concrete team identity are outside this helper.
+CLI applications use this same code without the editor; other frameworks can use
+native Slack verification support with the same Env and route contract.
+
+[Slack signature contract](https://docs.slack.dev/authentication/verifying-requests-from-slack/).

package/docs/snowflake.md

@@ -0,0 +1,271 @@
+# Snowflake
+
+The initial `snowflakeProvider` connects a custom Snowflake OAuth client and
+lists database metadata. JSKIT owns the configuration, field metadata, OAuth
+exchange, refresh and file-backed connection state. The application supplies
+its authenticated ownership policy and secret-reference resolver. The editor
+stores the same JSON a CLI user writes. Saving configuration contacts no provider.
+
+## Configuration
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "snowflake": {
+      "source": "own",
+      "clientId": "client-id-from-your-security-integration",
+      "clientSecretRef": "env:SNOWFLAKE_SECRET",
+      "callbackUrlRef": "env:SNOWFLAKE_CALLBACK"
+    }
+  },
+  "integrations": {
+    "warehouse": {
+      "provider": "snowflake",
+      "accountMode": "per-user",
+      "settings": {
+        "accountUrl": "https://myorg-myaccount.snowflakecomputing.com",
+        "role": "VIBE64_READER"
+      },
+      "scopes": ["refresh_token", "session:role:VIBE64_READER"],
+      "authentication": { "method": "oauth2", "registrationRef": "snowflake" }
+    }
+  }
+}
+```
+
+`shared` uses one grant under the application's shared owner; `assistant` uses
+the assistant owner's grant; `per-user` keeps each user's grant separate. The
+host must authorize those owners. None of these modes implements application
+login or automatically grants workspace members access.
+
+Set `SNOWFLAKE_SECRET` in the host's established secret store and
+`SNOWFLAKE_CALLBACK` to the exact route handled by the backend. Values stay out
+of this file. `client_secret_post` is the default. To use HTTP Basic, explicitly
+set registration `tokenEndpointAuthMethod` to `client_secret_basic`.
+
+The account URL accepts HTTPS account-name, locator/region and PrivateLink
+addresses under `snowflakecomputing.com`, with an optional trailing slash.
+Use the address reported by the account; paths, credentials, ports and query
+strings are rejected. PrivateLink also needs reachable private DNS/networking;
+validation does not create that connectivity. See [account URL formats](https://docs.snowflake.com/en/user-guide/organizations-connect).
+
+Role is optional in this initial form for every ownership mode. For a shared
+connection, assign a dedicated role. Use exact case from `SHOW ROLES`, without
+surrounding quotes. This fragment accepts ASCII names up to 255 characters,
+excluding double quotes/backslashes and the four privileged administrator
+roles. Spaces and punctuation use Snowflake's encoded role scope. Non-ASCII
+role names are not implemented. The UI updates the required role permission
+when the role changes; CLI users must update `scopes` too.
+
+For the default user role, omit `settings.role` and use `["refresh_token"]`.
+For a named role, refresh permission is optional and the role permission is
+required. The current shared schema requires at least one permission, so the
+blank-role form keeps refresh selected. A user who declines offline access can
+still connect, but must reconnect after the access token expires. Changing the
+account or role invalidates saved access and pending consent.
+
+## Create the provider registration
+
+1. Sign into the target account in Snowsight. Open the account menu/details and
+   copy its **Account URL**, rather than the current browser address. Confirm
+   the account before continuing.
+2. Select an administrator role with `CREATE INTEGRATION`. Open **Projects →
+   Worksheets**, choose **+ → SQL Worksheet**, or open an existing SQL worksheet.
+   In accounts using the newer Workspaces navigation, create a SQL file there.
+   The SQL operations below are the stable setup contract when labels differ.
+3. Have the account administrator choose or create a dedicated reader role,
+   grant it the necessary database visibility, and grant it to intended users.
+   Registration permission and data access are separate. The runtime's first
+   read can succeed with an empty list; that does not prove table access.
+4. Edit the following SQL with the real callback and approved role. Execute it
+   in that account. Use a fresh integration name; do not replace an existing
+   production integration as a shortcut.
+
+```sql
+CREATE SECURITY INTEGRATION DOGANDGROOM_READER
+  TYPE = OAUTH
+  ENABLED = TRUE
+  OAUTH_CLIENT = CUSTOM
+  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
+  OAUTH_REDIRECT_URI = 'https://your-app.example/integrations/snowflake/callback'
+  OAUTH_ENFORCE_PKCE = TRUE
+  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
+  OAUTH_REFRESH_TOKEN_VALIDITY = 86400
+  OAUTH_USE_SECONDARY_ROLES = NONE;
+
+DESC SECURITY INTEGRATION DOGANDGROOM_READER;
+SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('DOGANDGROOM_READER');
+```
+
+5. Copy `OAUTH_CLIENT_ID` into **Client ID**. Save one returned client secret in
+   the host's secret store and enter only its reference in **Client secret
+   reference**. Treat the SQL result as secret material; do not paste it into
+   AI chat, source files or logs. Confirm the allowed OAuth endpoints in the
+   `DESC` result match the account URL.
+6. Enter **Account URL**, optional **Role**, **Callback URL reference** and
+   ownership in the editor, or write the JSON above. Configure the callback
+   handler before starting consent. Use the system browser, select the intended
+   Snowflake user and approve the requested role/offline access.
+7. Verify using `databases.list`, then inspect an intentionally small page.
+   Lack of database visibility requires changing Snowflake grants, not changing
+   the app user's identity or requesting administrator roles.
+
+The callback above is an illustrative placeholder. Substitute the application's
+actual implemented backend callback before running the SQL. For local HTTP loopback development, Snowflake additionally needs
+`OAUTH_ALLOW_NON_TLS_REDIRECT_URI = TRUE`; use a separate development integration.
+Keep production HTTPS. PKCE is supported with confidential clients. See the
+[registration SQL reference](https://docs.snowflake.com/en/sql-reference/sql/create-security-integration-oauth-snowflake).
+
+## Connection ownership and callbacks
+
+Register the real callback implemented by the runtime that owns this connection.
+For an application integration, use the application's assigned hosting URL as
+the initial origin and its implemented callback path. Store the exact callback
+in its Env reference and provider registration. A domain change requires updating
+both values if the callback URL changes; retain the application identity and its
+persistent grants when moving hosts. Public Vibe64, Online and CLI users supply
+their own registrations through this same contract.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md).
+
+A Snowflake security integration belongs to one Snowflake account. Separate
+security integrations produce independent client credentials; they do not split
+that account's compute costs or guarantee independent provider quotas. Another
+customer's account needs its own integration. A single registration cannot
+unlock arbitrary accounts. Store each application's client secret in private Env.
+Snowflake's `PUBLIC` client type is a separate credential mode; that native
+public-client flow is not included by this confidential-client adapter.
+
+## What AI can automate
+
+With an already authorized administrator connection, AI can prepare and execute
+registration SQL using Snowflake CLI or the SQL API, inspect integration
+properties and configure the application's registration in its account. An operator must
+approve the account, roles, network policy and callback ownership and arrange
+secret capture directly into the secret store. Account enrollment, administrator
+access and user consent are not supplied by this adapter. There is no named OAuth-registration provisioning operation. General statement
+submission can execute only SQL permitted by the configured Snowflake role and
+application policy; do not grant registration administration to an ordinary
+application reader.
+
+For manual work use the worksheet steps above. For CLI work use the same SQL
+and portable configuration; there is no separate editor-only format. The host
+owns provisioning authority, not an implicitly elevated runtime OAuth grant.
+
+## Runtime contract and limits
+
+Import `snowflakeProvider` from `@jskit-ai/connectors-catalog/server/snowflake` and
+register it with `createConnectionService`. Call `beginAuthorization`, return the
+provider callback to `completeAuthorization`, and invoke `databases.list` through
+the authenticated application's owner context. See the packaged OAuth AI pattern
+and `@jskit-ai/connectors-core` guide for file-store and resolver wiring.
+
+The reader makes `GET /api/v2/databases`. It accepts `showLimit` (1–1000, default
+20; an adapter cap), optional `like`, `startsWith`, `fromName` (1–255 characters)
+and `history` (default false). It returns the provider's array of database
+records. Request the next page explicitly with the last name as `fromName` and
+the same filters; there is no background crawl or arbitrary continuation URL.
+See the [Database API reference](https://docs.snowflake.com/en/developer-guide/snowflake-rest-api/reference/database)
+and its [OpenAPI response schema](https://github.com/snowflakedb/snowflake-rest-api-specs/blob/main/specifications/database.yaml).
+
+Each request uses an OAuth bearer token, token-type header and, when configured,
+an exact quoted role header. Snowflake enforces the token's permitted role;
+a caller cannot override it through operation input. See [REST authentication](https://docs.snowflake.com/en/developer-guide/snowflake-rest-api/authentication)
+and [role context](https://docs.snowflake.com/en/developer-guide/snowflake-rest-api/setting-context).
+
+OAuth uses the account's `/oauth/authorize` and `/oauth/token-request`, state and
+S256 PKCE. The callback must contain an unambiguous scope value. Token lifetimes
+and optional refresh fields are validated; refresh rotations are stored before
+subsequent reads. Missing refresh or revoked grants require reconnecting.
+See [Snowflake's custom OAuth flow](https://docs.snowflake.com/en/user-guide/oauth-custom).
+
+The reader validates completed JSON pages, rejects oversized/malformed results
+and fails explicitly on HTTP 202 rather than treating pending work as success.
+This restriction applies to database listing; SQL operations below explicitly
+handle pending responses. External OAuth, key-pair/PAT mode and provider
+revocation are not implemented. Disconnect removes local state; revoke delegated authorization in
+Snowflake separately when required. Errors are sanitized; cancellation and
+timeouts are bounded. Automated tests use controlled protocol fixtures only.
+
+
+## SQL context
+
+Optional `settings.warehouse`, `settings.database` and `settings.schema` retain
+exact case-sensitive names in portable configuration. Snowflake uses the connected
+user's defaults when these are omitted. These defaults are not an access-control
+boundary; the user's role grants remain authoritative. Statement submission, polling, partition retrieval and cancellation now exist;
+warehouse actions also use that lifecycle. The application explicitly invokes each operation.
+
+Find the warehouse in Snowsight's warehouse administration and database/schema
+names in its database explorer, or ask the account administrator for the exact
+names. The role needs warehouse USAGE and applicable database/schema/object
+permissions. Query execution may resume a suspended warehouse and incur compute
+charges; no live execution is part of implementation verification.
+
+Use `statements.submit({ statement, requestId, bindings?, timeout? })` for a
+single parameterized statement. The UUID request ID is explicit; timeout defaults
+to 60 seconds and is bounded to 1–3600. Numbered bindings carry a Snowflake type
+and string/null value, preserving numeric precision. The operation uses configured
+warehouse/database/schema/role, sets single-statement mode and requests async
+execution. It returns pending/completed with a handle.
+
+Use `statements.get({ handle, partition? })` to poll or read one result partition.
+Completed results retain `data` as string/null rows and `metadata` when supplied;
+retain the first partition’s row types when subsequent partitions omit metadata.
+Use `statements.cancel({ handle })` to explicitly cancel. Requests construct the
+account URL from configuration; returned status links are never followed. The application owns operation authorization,
+query selection, polling and uncertain-request recovery. Multi-statement execution
+and raw end-user SQL must not be silently enabled.
+
+[Snowflake SQL API contract](https://docs.snowflake.com/en/developer-guide/sql-api/reference).
+
+
+The application must authorize the statement text and handle before invocation.
+Do not expose arbitrary SQL to untrusted visitors. Namespace settings are defaults,
+not a SQL sandbox; fully qualified SQL can name any resource the Snowflake role
+can access. Keep grants narrow and maintain application ownership of handles.
+A transport timeout is not proof the query stopped. Keep the request ID, consult
+Snowflake query history and reconcile before submitting another mutation; this
+adapter never retries submission automatically. Controlled tests cover asynchronous rejection, malformed results and uncertain
+submission without replay. Live provider execution remains untested.
+
+
+## Warehouse actions
+
+`warehouses.create({ name, size, requestId })` creates a standard warehouse,
+initially suspended, with auto-resume disabled and 60-second auto-suspend.
+`warehouses.resize({ name, size, requestId })` changes its size. Accepted sizes
+are XSMALL, SMALL, MEDIUM, LARGE, XLARGE, XXLARGE, XXXLARGE, X4LARGE, X5LARGE
+and X6LARGE; availability depends on the account.
+
+`warehouses.resume`, `warehouses.suspend` and `warehouses.delete` each accept
+`{ name, requestId }`. Names are exact case-sensitive identifiers, quoted by
+the adapter; do not enter surrounding SQL quotes. Each action returns the same
+pending/completed handle result as SQL submission. Poll through statements.get.
+The application must authorize the named warehouse and action, present billing
+implications before resume/resize, and confirm deletion. Role grants are enforced
+by Snowflake. Creation does not replace an existing warehouse; deletion is explicit.
+These helpers do not manage multi-cluster scaling, resource monitors or grants.
+
+See [CREATE WAREHOUSE](https://docs.snowflake.com/en/sql-reference/sql/create-warehouse),
+[ALTER WAREHOUSE](https://docs.snowflake.com/en/sql-reference/sql/alter-warehouse)
+and [DROP WAREHOUSE](https://docs.snowflake.com/en/sql-reference/sql/drop-warehouse).
+
+Responses are read with a 16 MiB limit before JSON parsing. A larger partition
+returns connector_response_too_large; reduce the query projection/result or use
+Snowflake's native streaming facilities in the chosen framework. SQL is not
+resubmitted on that error. Keep the handle to reconcile existing execution.
+
+Controlled source and installed-package verification each pass 17 focused tests,
+including interrupted oversized response streams and application resource policy.
+Expanded configuration and compact configuration/lifecycle checks pass, including
+SQL-default persistence, rendered setup instructions and consent cancellation/
+disconnect. No live account, SQL compute or generated application was exercised.
+
+
+For another framework, use its native OAuth client and Snowflake SQL client with
+the same account URL, callback Env, exact role and namespace defaults. Implement
+the confidential-client/PKCE consent and refresh lifecycle there; JSKIT is not a
+remote service. Preserve string-valued numeric results, one explicit statement
+request ID, partition polling and cancellation. Apply the same application
+policy to SQL text, handles and warehouse names before invoking the provider.

package/docs/storyblok.md

@@ -0,0 +1,130 @@
+# Storyblok
+
+Import `storyblokProvider` from `@jskit-ai/connectors-catalog/server/storyblok`.
+The fragment reads Content Delivery API space metadata and stories. It supports
+the Public and Preview token types and all five standard space regions.
+
+## Configure access
+
+1. Sign into Storyblok and select the space whose content the application uses.
+   Open **Settings → Access Tokens**.
+2. Create a named **Public** token for published content, or a **Preview** token
+   for draft and published content. Copy its value into backend Env as
+   `STORYBLOK_TOKEN`. Keep Preview tokens on the server. Management API personal
+   tokens, Asset tokens and Release tokens serve different purposes.
+   [Token types and settings](https://www.storyblok.com/docs/concepts/access-tokens).
+3. Add this integration to the ordinary `integrations.json` document. The UI
+   edits the same fields; only the reference goes in source:
+
+   ```json
+   {
+     "provider": "storyblok",
+     "displayName": "Website content",
+     "accountMode": "shared",
+     "scopes": [],
+     "authentication": { "method": "api-key", "secretRef": "env:STORYBLOK_TOKEN" },
+     "settings": { "region": "eu" }
+   }
+   ```
+
+4. Set **Space region** to match the space: `eu` (default), `us`, `ca`, `ap`, or
+   `cn`. Their API hosts are `api.storyblok.com`, `api-us.storyblok.com`,
+   `api-ca.storyblok.com`, `api-ap.storyblok.com`, and `app.storyblokchina.cn`.
+   All use `/v2/cdn`. Enterprise-specific hosts are not part of this fragment.
+   [Content Delivery endpoints](https://www.storyblok.com/docs/api/content-delivery/v2).
+5. Use `connectApiKey` to verify space access. A region or reference change
+   requires verification again. Local disconnect removes the runtime connection;
+   revoke an obsolete token in Storyblok when it should stop working everywhere.
+
+## Runtime and AI composition
+
+Compose the provider with the [API-key pattern](../patterns/api-key-connection/PATTERN.md)
+and file store. `space.read` calls `GET /v2/cdn/spaces/me`, returning the space's
+ID, name, languages and available cache-version metadata. Verification proves
+space access; it does not establish that the token can read drafts.
+[Space endpoint](https://www.storyblok.com/docs/api/content-delivery/v2/spaces/retrieve-current-space).
+
+`stories.list` calls `GET /v2/cdn/stories`. Inputs are `version` (`published` by
+default or explicit `draft`), `page` (starting at 1), `per_page` (1–100, default
+25), optional `starts_with`, `search_term`, `content_type`, `language`, and `cv`.
+Results retain the stories and other response-body metadata. Increment page
+until a short or empty page; this runtime does not expose the API's pagination
+headers. Draft access requires a Preview token; it never falls back silently
+to published content. Content writing is outside this Delivery API connector. The application owns
+rendering and cache policy.
+[Story listing](https://www.storyblok.com/docs/api/content-delivery/v2/stories/retrieve-multiple-stories).
+
+The core inserts the resolved token into the authenticated query string. Do not
+pass tokens as operation inputs or log full request URLs in application HTTP
+instrumentation. Preview content also needs application access controls; selecting
+`shared` makes the credential shared, not the resulting content public.
+
+## Automation and application ownership
+
+After an authorized human supplies Management API access, an AI can create
+Content Delivery tokens with `POST /v1/spaces/{space_id}/api_keys/` on the
+appropriate Management API host. The request body includes
+`api_key: { access: "public", name: "Application content" }`, and the result
+contains `api_key`. EU management uses `mapi.storyblok.com`. This is a setup API,
+not an operation exposed by this read fragment.
+[Token creation](https://www.storyblok.com/docs/api/management/access-tokens/create-an-access-token).
+
+Space creation and configuration are also available through the Management API;
+account creation, billing and initial authorization still require the account
+owner. [Space APIs](https://www.storyblok.com/docs/api/management/spaces).
+
+The application owner supplies a token for its Storyblok space. Two token names
+in one space do not guarantee quota isolation; confirm space/organization plan
+limits. This Content Delivery flow needs no OAuth client ID or callback, so
+editor VM and hosted-application domains need no per-domain OAuth registrations.
+
+Automated tests use simulated responses: all five destinations, published/draft
+selection, page limits, encoded credentials, rotation, file-store restart,
+authorization isolation, invalid responses and failures. No live space was
+created or read, and no sample application was generated or executed.
+
+
+## Page retrieval and rendering
+
+`stories.get({ id, find_by?, version?, language?, cv?, resolve_relations?,
+resolve_links?, resolve_assets? })` reads one page by numeric ID or full slug.
+Pass a UUID with `find_by: "uuid"`. Slugs are encoded as path segments; do not
+pass an API URL. Relative or empty path segments are rejected.
+
+Both get and list accept `resolve_relations` as comma-separated component.field
+names, `resolve_links` as url/link/story, and `resolve_assets` as 0/1. The response
+retains relation, link and asset metadata. Additional relations beyond the
+provider's expansion limit require explicit subsequent reads; no automatic crawl
+or remote asset fetch occurs. Use asset filename and alt values when rendering
+approved images; private asset access still follows Storyblok's access policy.
+[Single story contract](https://www.storyblok.com/docs/api/content-delivery/v2/stories/retrieve-a-single-story).
+
+An application-owned page route maps its slug to stories.get and supplies an
+authenticated owner context. Render content.component through an explicit map
+of framework components; render field strings as escaped text. Use the chosen
+framework's Storyblok rich-text renderer for rich-text documents, with reviewed
+link and embedded-component rules. Do not inject arbitrary content as HTML.
+Return an ordinary not-found page when published content is absent. JSKIT
+provides data operations, not a page builder or preview-editor subsystem.
+
+Use a Public token for public routes. If the project also needs preview, keep
+a Preview token in a separate server-side integration, require editor access
+before requesting draft, and mark preview responses private/no-store. The
+application policy receives the requested version before provider transport.
+Never let an unauthenticated request parameter select the preview integration.
+Cache published pages by space/integration, language, slug, version and cache
+version; do not mix draft and published results. Use returned cv consistently
+while paginating and refresh the space version when revalidating after publish.
+The app owns its revalidation trigger and scheduler.
+
+A CLI-only or non-JSKIT app uses the same token Env and region with its native
+HTTP/Storyblok client. Keep the same published-default and preview authorization
+rules; it does not need Vibe64 or a JSKIT server.
+
+Current focused source proof: four Storyblok cases pass, covering all regions,
+credential rotation/restart, page/list results, linked content and assets,
+invalid paths/results, policy-denied draft access and provider failures. No
+live space or generated application was used. The same four cases pass through
+installed package exports in a disposable CLI consumer. Public configuration and
+API-key connection/disconnect checks pass at compact, medium and expanded widths,
+including region persistence, inline instructions and horizontal-overflow checks.