@jskit-ai/connectors-catalog 0.1.1

package/docs/chargebee.md

@@ -0,0 +1,192 @@
+# Chargebee
+
+Import `chargebeeProvider` from `@jskit-ai/connectors-catalog/server/chargebee`.
+This adapter manages customers and Product Catalog 2.0 subscriptions, reads catalogue
+and invoice data, and creates provider-hosted checkout and customer portal sessions.
+Payment details stay in Chargebee-hosted screens. It does not implement OAuth.
+
+## Manual site and credential setup
+
+1. Sign into the Chargebee site as its owner or an administrator. Select the
+   intended test or live environment. Copy the site name from its address:
+   for `https://acme-test.chargebee.com`, use `acme-test`.
+2. Open **Settings → Configure Chargebee → API Keys and Events → API keys**.
+   Some documentation/views label the section **API Keys and Webhooks**.
+3. Choose **+ Add API Key**. For reads, choose **Read-Only Key** with transactional
+   and product-catalog access, or **Read-only: All**. For customer/subscription
+   changes, checkout and portal sessions, choose **Full-Access Key**, subtype
+   **Write** (create/read/update, without deletion). Name it and choose
+   **Create Key**, then retain the issued key securely. A publishable key or
+   a key restricted to product-catalog reads is insufficient for this fragment.
+4. Store the key under `CHARGEBEE_API_KEY` in the backend environment. Enter
+   `env:CHARGEBEE_API_KEY` in Vibe64's API-key reference field and the site name
+   in **Site name**. Save the configuration, then choose **Set credential in Env**,
+   enter the issued key as `CHARGEBEE_API_KEY`, and save it. Return to the
+   integration and choose **Connect account** or **Verify again**. **Check connection**
+   only reads saved status. No OAuth callback is required.
+
+Test and live sites use distinct keys. API keys apply to a site, rather than
+being restricted to one business entity within it.
+[Key types and creation](https://www.chargebee.com/docs/billing/2.0/site-configuration/api_keys).
+
+## Portable configuration and runtime
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "billing": {
+      "provider": "chargebee",
+      "displayName": "Customer directory",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:CHARGEBEE_API_KEY"
+      },
+      "settings": { "siteName": "acme-test" }
+    }
+  }
+}
+```
+
+The same shared schema validates CLI edits and the UI form. `siteName` accepts
+one DNS label, 1–63 letters/digits/hyphens, with a letter or digit at each end.
+The operation normalizes its host to lowercase. Full URLs, `.chargebee.com`,
+paths, ports, spaces and embedded credentials are rejected. Changing the site
+or credential reference requires a fresh runtime verification.
+
+Use the [API-key composition pattern](../patterns/api-key-connection/PATTERN.md)
+with `providers: [chargebeeProvider]`, environment-reference resolution and
+the file connection store. Configuration and runtime state are text files; the
+CLI application does not need an editor or a database. Authorize the requested
+application/team context before access to the shared billing connection.
+
+```js
+await connections.connectApiKey({ context, integrationId: "billing" });
+const page = await connections.invoke({
+  context, integrationId: "billing", operation: "customers.list",
+  input: { limit: 25, include_deleted: false }
+});
+// The application can request another page explicitly using page.next_offset.
+```
+
+Requests use HTTP Basic authentication with the API key as username and an
+empty password. The runtime only sends credentials to the exact configured
+`https://<site>.chargebee.com` origin and rejects redirects. Keys remain outside
+the portable file and runtime connection records. Rotation updates the
+environment binding; a provider rejection marks the connection for verification
+again. Disconnect removes local state, not the site's provider key.
+[Authentication example](https://www.chargebee.com/docs/billing/2.0/site-configuration/api_keys).
+
+`customers.list` performs `GET /api/v2/customers`. It accepts `limit` from 1–100
+(default 10), optional opaque `offset` up to 1000 characters and
+`include_deleted` (default false). It returns the provider's `list` entries and
+optional `next_offset`. Pass that cursor unchanged for the next page. Empty
+lists are valid. Deleted customers are returned only when explicitly requested.
+The provider describes this listing as eventually consistent.
+[Customer listing](https://apidocs.chargebee.com/docs/api/customers/list-customers).
+
+The fragment preserves customer data and any accompanying resource fields,
+checks the response envelope, and does not automatically traverse pages.
+The additional operations below supply customer-filtered billing reads and explicit
+writes. Sorting and entity-specific access remain native application concerns. The application's policy must control who may read the customer
+directory; knowing a Chargebee customer ID is not an authenticated login.
+
+## Automation and application credentials
+
+An AI can prepare the configuration, environment reference, JSKIT composition
+and customer-reading code. The reviewed setup documentation describes key
+creation through the dashboard; it does not establish a public self-service API
+for creating operator accounts, sites or API keys. Treat initial provisioning
+as an owner/admin step and do not invent a registration endpoint. A separate
+partner arrangement may offer capabilities that are not covered here.
+
+Create an application-specific key on the appropriate Chargebee site. This is
+a credential, not an OAuth app registration. When connecting a customer's own billing
+system, use its site and authorized key; an operator key cannot access every
+customer's Chargebee account. No callback URL is required for this flow, so
+editor VM and deployed application domains do not affect registration.
+
+API rate and concurrency limits apply to the site. A second key on the same
+site does not create an independent quota. Chargebee returns HTTP 429 when
+limits are exceeded; its documentation describes plan-dependent site limits
+and a support route for increases.
+[Rate limits](https://apidocs.chargebee.com/docs/api/error-handling).
+The application owns its credential selection and usage policy. Separate
+provider capacity requires the appropriate site/account arrangement. A test
+site is not additional production capacity.
+
+## Focused evidence
+
+Six tests use simulated Chargebee replies and real temporary encrypted JSON
+files. They cover Basic authentication, file restart, rotation, ownership,
+disconnect, unsafe site/credential rejection, site changes, cursors, deleted
+records, page-size limits and failures. The editor check covers site validation,
+reference-only storage and persistence after reload. Provider signup, live API
+requests, billing changes and sample-app generation are excluded.
+
+## Billing operations and recovery
+
+| Operations | Result / boundary |
+| --- | --- |
+| `customers.list/get/create/update` | Customer directory and profile fields; never raw card details |
+| `itemFamilies.list`, `items.list/get`, `itemPrices.list/get` | Product Catalog 2.0 products and configured prices |
+| `subscriptions.list/get/create` | Customer-linked subscriptions; direct creation requires explicit auto_collection and invoice_immediately |
+| `subscriptions.updateAtTermEnd` | Schedule selected item/quantity changes; explicit replace_items_list controls replacement |
+| `subscriptions.cancelAtTermEnd` | Non-renewal at billing term end; does not immediately cancel service |
+| `invoices.list/get/pdf` | Invoice/status/line-item data and an expiring PDF link |
+| `hostedPages.checkoutNew/checkoutExisting/get` | Hosted new/changed subscription checkout, then authoritative completion details |
+| `portalSessions.create` | Customer-authenticated hosted billing management session |
+| `events.list/get` | Provider events for application-owned reconciliation |
+
+Inputs use resource IDs as `resource`. New customer creation optionally accepts `id`.
+List operations accept limit/offset; subscription and invoice lists accept
+`customer_id[is]`, and invoices also accept `subscription_id[is]`. Preserve opaque
+pagination offsets. Subscription item arrays contain `{ item_price_id, quantity }`;
+the first item must be a plan price in hosted checkout. The adapter encodes Chargebee's
+indexed form fields server-side. Product Catalog 1.0 requires native older endpoints.
+
+Every supplied POST requires `idempotencyKey`, a unique application intent identifier
+(up to 100 letters/digits/underscores/hyphens). Persist it with the exact intended
+request before submitting. The provider's idempotency window is 30 minutes, and the
+same key requires the same path, body and headers. The adapter never automatically
+replays an uncertain request. After a timeout or beyond that window, reconcile the
+customer/subscription/page/event before deciding whether a new request is appropriate.
+Do not generate a fresh key for a blind retry. Provider errors remain errors; this
+adapter does not expose the response's idempotency-replayed header.
+
+Example flow for DogAndGroom: authenticate the customer in the app, resolve their
+server-owned Chargebee customer ID, select a configured recurring item price, then
+create hosted checkout with that customer and the app's allowlisted return/cancel URLs.
+Keep the hosted page ID bound to that local customer. Send the returned URL to their
+browser. After return, retrieve the stored page ID server-side, verify `succeeded`,
+its customer/subscription association and actual invoice/subscription state. A query
+string saying success and even a succeeded checkout do not independently prove that
+an invoice is paid. Offline or deferred collection can leave payment due. The app
+must decide access policy and reconcile later events. Never trust a browser-supplied
+customer ID to issue a portal session: that URL grants billing-account access.
+
+Use the same service.invoke operations in a standalone Node/CLI application;
+Vibe64 only edits the portable configuration. Other frameworks use native Chargebee
+SDK/HTTP with these Env bindings, indexed form fields and app-owned intent state.
+No Node bridge or Vibe64 server is needed. The existing owner authorization callback
+must approve customer, subscription, return destination and financial intent.
+
+**LIMITATIONS:** Editor coding-assistant attachment is deferred. For example, an app
+can launch customer checkout and show invoices, but Vibe64's Codex/OpenCode cannot
+inspect the billing site through this saved connection. This is a connector, not the
+Stripe/Paddle payments product: product authoring, entitlement/credit engines,
+webhook receivers, immediate/prorated changes, refunds, contract-term cancellation,
+advanced tax/coupon/metered billing and multi-entity controls use native app wiring.
+Configure catalogue/prices, payment gateway and portal in Chargebee. No live billing,
+provider signup or generated app was exercised. Creating keys does not isolate site quotas.
+
+Sources checked 12 September 2026:
+[idempotency](https://apidocs.chargebee.com/docs/api/idempotency),
+[hosted checkout](https://apidocs.chargebee.com/docs/api/hosted_pages/create-checkout-for-a-new-subscription),
+[subscription creation](https://apidocs.chargebee.com/docs/api/subscriptions/create-subscription-for-items),
+[scheduled changes](https://apidocs.chargebee.com/docs/api/subscriptions/update-subscription-for-items),
+[cancellation](https://apidocs.chargebee.com/docs/api/subscriptions/cancel-subscription-for-items),
+[portal sessions](https://apidocs.chargebee.com/docs/api/portal_sessions/create-a-portal-session).

package/docs/clay.md

@@ -0,0 +1,194 @@
+# Clay Public API
+
+Reviewed against Clay's API documentation on 12 September 2026. Import
+`clayProvider` from `@jskit-ai/connectors-catalog/server/clay`. This adapter verifies user/workspace identity, searches people and companies,
+runs enrichment routines, reads results and queries Enterprise tables. It uses a Public API key, not a legacy workspace key.
+
+## Manual setup
+
+1. Sign into the Clay account with access to the intended workspace. Open
+   **Settings → Account → API keys (beta)**, or follow the official guide's
+   [direct API-key settings link](https://app.clay.com/workspaces/~/settings/account?accountTab=api-keys-beta).
+2. Create a Public API key. Copy the newly issued value
+   into the backend environment as `CLAY_PUBLIC_API_KEY`.
+3. In Vibe64, open **Integrations → Add Clay**. Enter a display name and
+   `env:CLAY_PUBLIC_API_KEY` in **Public API key reference**. Choose shared
+   application access or assistant access for the intended owner, then save.
+4. The host explicitly calls `connectApiKey`. Its `GET /public/v0/me` check
+   verifies both user and workspace identity without starting a search.
+5. For rotation, create a replacement key, update the existing Env binding and
+   verify it before retiring the old key in Clay. Disconnecting the application
+   removes local connection state; it does not revoke the provider key.
+
+The provider documents the account navigation and `clay-api-key` header in its
+[authentication guide](https://developers.clay.com/public-api/authentication).
+The [identity endpoint](https://developers.clay.com/api-reference/me/get-the-authenticated-user)
+returns the account and workspace associated with that key. Their names may be
+null; a successful check does not prove search capacity or access to every table.
+These console instructions are documented, not verified through a live account.
+The official guide establishes the destination and key type. Dialog labels may
+change; use the Public API key creation action on that page, not the legacy
+workspace-key flow. If this page is unavailable to your account, resolve Public
+API access with Clay before configuring this connector.
+
+## Portable source and CLI
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "prospects": {
+      "provider": "clay",
+      "displayName": "Clay prospect search",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:CLAY_PUBLIC_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Compose this file with `providers: [clayProvider]`, an authorization policy and
+the encrypted file connection store as in the
+[API-key pattern](../patterns/api-key-connection/PATTERN.md). A CLI uses these
+same library methods. Vibe64 writes the same source file and supplies no separate
+database requirement.
+
+```js
+await connections.connectApiKey({ context, integrationId: "prospects" });
+const search = await connections.invoke({
+  context, integrationId: "prospects", operation: "searches.create",
+  input: { query: approvedQuery }, signal
+});
+// Bind this returned ID to the authenticated connection in application state.
+const page = await connections.invoke({
+  context, integrationId: "prospects", operation: "searches.next",
+  input: { searchId: search.search_id, limit: 20 }, signal
+});
+```
+
+`approvedQuery` must follow Clay's current grammar and the application's policy.
+Clay publishes that grammar through authenticated
+`GET https://api.clay.com/public/v0/search/query-mode/reference`; retrieve it
+with the same private header before authoring queries. Use `searches.reference` to retrieve the current grammar. The query endpoint supports people
+and companies, excluding count queries and jobs.
+[Query guidance](https://developers.clay.com/searches/advanced),
+[search creation](https://developers.clay.com/api-reference/search/create-a-search-from-a-clay-search-query).
+
+`searches.next` calls `POST /public/v0/search/query-mode/{search_id}/run`.
+The default limit is 20, with provider bounds of 1–500. Responses preserve
+`data`, `source_type`, `has_more`, and available exhaustion/quota metadata.
+Each call advances the provider's iterator; the adapter never fetches another
+page automatically. An interrupted request may already have advanced it.
+Authorize the exact search ID and volume, retain the ID under its connection,
+and request another page deliberately. Do not replay it as an ordinary GET.
+[Iterator contract](https://developers.clay.com/api-reference/search/run-the-query-mode-iterator-and-return-the-next-page-of-results).
+
+Local validation caps query text at 16,000 characters and search IDs at 1,024
+ASCII letters, digits, underscores or hyphens. It does not reimplement Clay's
+query grammar. API keys stay in the header on the fixed `api.clay.com` origin;
+returned links and input values cannot select another credential destination.
+
+## Application credentials and automation
+
+This API-key flow has **no OAuth callback**, so there is no universal callback
+URL to register for Clay. VM addresses and custom application domains do not
+change its authentication.
+
+The application owner supplies its authorized Clay key through private Env.
+Two keys alone do not establish separate quota or billing pools; confirm the
+provider's capacity terms. The application must not silently substitute an
+unrelated Clay workspace for the customer's. See the
+[application setup contract](../../connectors-core/docs/online-setup.md).
+
+AI can generate the portable file, environment wiring, query operations and
+tests. The documentation reviewed exposes key creation through the console,
+not a verified public provisioning API. Account access, key issuance and any
+required provider plan approval remain operator actions. A bootstrap script
+must not pretend those actions have been automated.
+
+## Routines and table queries
+
+For custom functions, open [Functions](https://app.clay.com/functions), create or
+select a function, open **Details**, enable **API**, and copy its `t_...` function
+ID. Prefix it with `function:`. Supply the exact inputs defined by that function.
+For Clay-managed routines, use the published routine ID and input contract from
+[Clay-managed functions](https://developers.clay.com/routines/clay-managed-functions).
+There is no public routine-discovery operation in this adapter.
+
+```js
+const run = await connections.invoke({
+  context, integrationId: "prospects", operation: "routines.run",
+  input: { routineId: "function:t_example", items: [
+    { id: "row-1", inputs: { domain: "example.com" } }
+  ] }, signal
+});
+// Persist run.routine_run_id under this connection. Later, explicitly poll:
+const progress = await connections.invoke({
+  context, integrationId: "prospects", operation: "routines.results",
+  input: { routineId: run.routine_run_id, limit: 20 }, signal
+});
+```
+
+The results operation's `routineId` is the **run ID returned by the start request**,
+not the function ID. Starts accept 1–100 items with caller-owned IDs (1–64 chars)
+and an optional existing `webhook_id`. The adapter does not register webhooks.
+An `in_progress` response is not success for the enrichment; preserve status,
+progress, each item's output/error and any cursor. Run completion does not mean
+all items succeeded. No automatic polling, pagination or replay is performed.
+Authorize exact inputs, routine and volume; runs can consume credits. The optional
+`credits.balance` read reports current balance, not a price quote or reservation.
+After an uncertain start, investigate in Clay before repeating it: no idempotency
+guarantee is claimed. [Routine API](https://developers.clay.com/routines/api),
+[function exposure](https://developers.clay.com/routines/custom-functions).
+
+`tables.query` requires **Enterprise** and known table IDs. Open the target Clay
+table and copy the ID after `/tables/` in its URL. No public list-tables endpoint
+exists. For example:
+
+```js
+await connections.invoke({ context, integrationId: "prospects", operation: "tables.query",
+  input: { query: { tables: [{ id: "t_example" }], field_mode: "names",
+    select: [{ field: "Domain", as: "domain" }],
+    filter: { field: "Domain", op: "is_not_empty" }
+  }, limit: 20 }, signal });
+```
+
+The adapter validates the query envelope, known top-level fields, table IDs,
+collection bounds and a limit of 1–100. Clay validates its provider-owned nested
+filter/select/join/order grammar; the adapter does not translate SQL or invent
+fields. Use [Clay's table query guide](https://developers.clay.com/tables)
+for exact field and filter syntax. Returned data, field metadata, cursor and
+`truncated` are preserved. Scans can repeat records updated during pagination:
+deduplicate by record ID. Grouping/aggregation/custom ordering cannot always
+produce cursors; `truncated: true` without a cursor requires narrowing the query,
+not treating that response as the full dataset.
+
+Current query-mode handles search criteria; legacy filters-mode is deprecated
+and is intentionally absent. Native frameworks can use these same fixed Public
+API endpoints with `clay-api-key` from private Env and their own HTTP client;
+JSKIT and Vibe64 are not required for execution.
+
+## Focused proof and limitations
+
+Controlled HTTP tests with real temporary file state cover verification, restart,
+rotation, ownership, search paging, routine start/progress/item errors, table
+queries/truncation, invalid input, denied writes, billing/rate/provider failures,
+and interrupted iterators without replay. The rendered editor check covers the
+Public API key label, raw-secret rejection, reference persistence, function API
+enablement, Enterprise prerequisite and local-disconnect explanation.
+No live provider calls or generated applications are part of this proof.
+
+**LIMITATIONS:** Automatic Vibe64 coding-assistant attachment is deferred. For
+example, saving Clay here does not let you ask the Vibe64 chat to enrich leads;
+the generated app or explicitly wired assistant host can invoke these operations.
+Clay's workflow/function authoring UI, large JSONL batch uploads, webhook
+provisioning/verification and automatic key issuance remain provider/native app
+work. For example, create and enable a custom function in Clay first; this adapter
+can run it but cannot build it from a canvas. HTTP 402 is a sanitized provider
+failure, never a successful empty search. Key-dialog instructions follow official
+docs; no signed-in console or paid-plan capability was verified.

package/docs/clickhouse.md

@@ -0,0 +1,242 @@
+# ClickHouse
+
+Import `clickhouseProvider` from `@jskit-ai/connectors-catalog/server/clickhouse`.
+This fragment verifies an HTTPS database endpoint, discovers tables and columns,
+and reads bounded pages. The application owns access to this shared database.
+A database connection does not sign users into the application.
+
+## Manual setup
+
+1. In ClickHouse Cloud, select your organization and service, then choose
+   **Connect → HTTPS**. Copy the host and port from its connection example.
+   Put the full `https://host:port` address in **HTTP Interface URL**. For a
+   self-hosted server, obtain its HTTPS query endpoint from its administrator;
+   a reverse-proxy path is supported. Native TCP connection strings do not work.
+   [Connection details](https://clickhouse.com/docs/products/cloud/guides/sql-console/connection-details).
+2. Open the service's **SQL Console**, create a query using **+**, and have a
+   database administrator create a dedicated application user and grant SELECT
+   only on the intended tables. Use SQL `CREATE USER` and `GRANT SELECT`, with a
+   private password supplied through your administration process. Cloud console
+   accounts and database users are separate. Do not place a Cloud management
+   API key in this integration's password field.
+   [SQL Console](https://clickhouse.com/docs/products/cloud/features/sql-console-features/sql-console),
+   [database users and permissions](https://clickhouse.com/docs/concepts/features/security/access-rights).
+3. Select **Settings → Security → IP access list → Add IPs** for the service.
+   Choose access from specific locations, add the application backend's source
+   IP/CIDR and save. Include an administrator's authorized access path when
+   needed. Requests originate from the server running this adapter; the
+   application's browser domain is not the source IP.
+   [IP filters](https://clickhouse.com/docs/products/cloud/guides/security/connectivity/setting-ip-filters).
+4. Select **Username and password** in the integration form. Enter the database
+   username. Enter `env:CLICKHOUSE_PASSWORD` in **Password reference
+   (optional)**, then save configuration. Choose **Set credential in Env**, paste
+   the password as `CLICKHOUSE_PASSWORD`, and save it there. CLI users set the
+   same variable in their backend environment. The form stores a reference, not the
+   password. The backend resolves it when verifying and reading.
+5. Verify using `connectApiKey` as shown below, then exercise the particular
+   table operation your application needs. A successful `SELECT 1` proves
+   endpoint access, not permission to read every table.
+
+The database administrator must allow the adapter's fixed query settings:
+`max_execution_time=10`, `max_result_rows=100`, `max_result_bytes=5242880`, and
+`result_overflow_mode=throw`. A user profile that forbids these settings will
+reject the request; the adapter does not retry without bounds. Configure
+compatible settings constraints for a user with `readonly=1`.
+[Query permissions](https://clickhouse.com/docs/concepts/features/configuration/settings/permissions-for-queries).
+
+## Credential choices
+
+| Configuration | HTTP behavior |
+|---|---|
+| `api-key`, username and password reference | Basic authentication with that database user and resolved password |
+| `api-key`, username omitted | Basic authentication as `default` |
+| `api-key`, password reference omitted | Basic authentication with an empty password |
+| `api-key`, reference resolves to an empty string | An explicitly configured empty password |
+| `api-key`, reference missing or invalid | Local binding error; no database request |
+| `none` | No Authorization header and no credential resolution |
+
+Use **No credentials** only for an endpoint intentionally configured to permit
+that access. ClickHouse otherwise uses its default user and an empty password;
+the database's permissions still apply. Switching modes clears the username and
+password reference that no longer apply. Both modes require verification and
+the application's ordinary authorization policy.
+[HTTP authentication](https://clickhouse.com/docs/concepts/features/interfaces/http#authentication).
+
+## Portable configuration and CLI wiring
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "warehouse": {
+      "provider": "clickhouse",
+      "displayName": "Reporting database",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:CLICKHOUSE_PASSWORD"
+      },
+      "settings": {
+        "httpUrl": "https://warehouse.example:8443/",
+        "username": "report_reader"
+      }
+    }
+  }
+}
+```
+
+Compose the [API-key source pattern](../patterns/api-key-connection/PATTERN.md)
+with `providers: [clickhouseProvider]`. Use `createFileConnectionStore` for
+encrypted JSON runtime state outside source. The CLI and editor use the same
+parser, fields and runtime; no application generator or local SQL store is
+needed. Supply authenticated application context and its authorization policy.
+
+```js
+await connections.connectApiKey({ context, integrationId: "warehouse" });
+const tables = await connections.invoke({
+  context, integrationId: "warehouse", operation: "tables.list",
+  input: { database: "reports", limit: 20 }
+});
+const columns = await connections.invoke({
+  context, integrationId: "warehouse", operation: "columns.list",
+  input: { database: "reports", table: "orders" }
+});
+const rows = await connections.invoke({
+  context, integrationId: "warehouse", operation: "rows.list",
+  input: { database: "reports", table: "orders", orderBy: "id", limit: 25, offset: 0 }
+});
+```
+
+For no credentials, replace authentication with `{ "method": "none" }`, remove
+`settings.username`, and use `connectWithoutCredentials` instead of
+`connectApiKey`. The remaining configuration and invocation APIs are identical.
+An existing grant cannot survive a change of mode, endpoint, username or
+password reference without verification. Rotating the environment value takes
+effect on the next call. Disconnect removes local state; revoke the database
+user or change its password separately when appropriate.
+
+## Operations and result handling
+
+| Operation | Inputs | Result |
+|---|---|---|
+| `connection.check` | None | `SELECT 1 AS ok, currentUser() AS user` |
+| `tables.list` | Optional database; limit, offset | Database, table name and engine from `system.tables` |
+| `columns.list` | Database and table; limit, offset | Column type, position and default metadata from `system.columns` |
+| `rows.list` | Database and table; optional orderBy; limit, offset | One page of table rows |
+| `queries.read` | SELECT/WITH SQL and optional named string parameters | Bounded analytical result with column metadata/statistics |
+
+Names are nonempty strings of up to 256 characters without control characters.
+Table/database names and the optional ascending sort column use ClickHouse
+typed parameters, including `Identifier`; they are never inserted into SQL
+text. Quotes, dots and backslashes remain parameter values. `orderBy` denotes
+one column name, not an expression. The discovery operations use fixed SELECT queries. `queries.read` accepts an
+application-approved SELECT/WITH query; endpoint and HTTP setting overrides are
+not accepted as operation inputs.
+[Typed parameters](https://clickhouse.com/docs/reference/syntax#defining-and-using-query-parameters).
+
+For analytical queries, use a backend-owned template and typed placeholders:
+
+```js
+await connections.invoke({ context, integrationId: "warehouse", operation: "queries.read",
+  input: { sql: "SELECT toStartOfMonth(booked_at) AS month, count() AS bookings FROM {db:Identifier}.{table:Identifier} WHERE tenant = {tenant:String} GROUP BY month ORDER BY month LIMIT 100",
+    parameters: { db: "reports", table: "bookings", tenant: authorizedTenantId }
+  } });
+```
+
+The operation accepts one SELECT/WITH query, up to 16,000 characters, without a
+semicolon or trailing FORMAT clause (the adapter appends FORMAT JSON). Up to 100
+parameters use identifier names and string values up to 16,000 characters, without
+control characters. Encode numeric/date values as strings for their declared
+ClickHouse types. Parameter values stay separate from SQL; they cannot override
+HTTP settings. Arrays/complex values require ClickHouse's typed literal syntax.
+
+This is **not a SQL sandbox**. The initial keyword check is input guidance, not a
+security boundary. Database grants, read-only profiles, row policies and server
+setting constraints must enforce permitted reads, tenant isolation and resource
+budgets. SELECT can access table functions or external sources where the database
+allows them. Prefer fixed approved templates; never let an untrusted frontend
+choose arbitrary queries/table functions or omit its required tenant filter.
+Read-only HTTP and result bounds do not make arbitrary SQL safe or inexpensive.
+SQL and parameter values are in the request URL; redact proxy/access logs.
+Other frameworks use the same HTTPS endpoint and typed `param_name` contract with
+their native HTTP/database tools, and read the same Env/configuration values.
+
+Limit is 1–100, default 20; offset is 0–1000000, default 0. Calls never fetch
+another page automatically. Offset paging can repeat or skip rows as data
+changes. Rows have no guaranteed ordering without `orderBy`; even with it,
+choose a stable unique column for predictable paging. A small result limit
+does not guarantee a cheap scan or sort. The database administrator owns scan,
+memory, thread and quota constraints.
+
+The adapter returns the parsed `FORMAT JSON` envelope unchanged: `meta`, `data`,
+`rows` and any provider statistics. It accepts empty pages and validates the
+envelope before success. It does not convert strings into numbers or dates;
+preserve large integer strings and consult `meta` for column types. Provider
+format settings determine decimal/large-number encoding, so do not assume
+JavaScript numbers can represent every value exactly.
+[JSON format](https://clickhouse.com/docs/reference/formats/JSON/JSON).
+
+Requests ask for response buffering with `wait_end_of_query=1`. ClickHouse can
+still report an execution exception after sending HTTP 200; incomplete JSON or
+an exception envelope is an error, never a successful partial page. HTTP errors
+and timeouts are surfaced without replay. Cancellation ends the local request;
+it does not prove the database query stopped. The fixed execution-time setting
+limits server work, subject to ClickHouse's execution checks.
+[HTTP buffering and error behavior](https://clickhouse.com/docs/concepts/features/interfaces/http).
+
+The configured endpoint may be private and may include a port or proxy path.
+Validation rejects HTTP, embedded credentials, queries, fragments and parent
+path segments. It does not resolve DNS or impose network policy. The host must
+restrict configuration editing and its backend's network access. Redirects are
+rejected; credentials never go in the URL or browser configuration.
+
+## Automation and Online ownership
+
+An AI can prepare portable JSON and wire the library. With an authorized
+database administrator connection, it can provision users, grants, profiles and
+quotas using SQL. A self-hosted administrator can also use ClickHouse access
+configuration files. These are separate administrative operations; this adapter
+does not execute them.
+
+Cloud service provisioning is also programmable using ClickHouse's management
+API. An organization operator first opens **API Keys → New API Key**, sets the
+name, roles, expiration and allowed IPs, and chooses **Generate API Key**.
+Store the displayed Key ID/secret privately. Authorized automation can then use
+the API with those management credentials. Account setup, billing access and
+required administrative permission remain operator responsibilities. Management
+credentials belong to provisioning, not the application's database connection.
+[Cloud API keys](https://clickhouse.com/docs/products/cloud/features/admin-features/api/openapi).
+
+**Universal callback: not applicable.** This mode has no OAuth registration or
+provider redirect. Each customer supplies their database endpoint and access.
+An editor VM or app custom-domain change needs no new callback. If backend
+egress changes, update the database IP allowlist. If the database URL changes,
+update `httpUrl` and verify again.
+
+The database owner can create separate application users with distinct grants and
+quota profiles. Two usernames alone do not isolate CPU, memory or storage;
+independent capacity requires appropriate budgets or separate compute. Each
+application stores its own credential in private Env and enforces its access and
+network policy. The [application setup contract](../../connectors-core/docs/online-setup.md)
+also applies when the application moves hosts.
+
+## Focused proof and remaining work
+
+Tests use controlled HTTP and real encrypted temporary files. They cover Basic
+and no-credential modes, default users, empty/missing passwords, rotation,
+restart, isolation, changed bindings, typed query parameters, page bounds,
+malformed replies, HTTP-200 exceptions, errors and cancellation without replay.
+The shared form tests cover mode changes, hidden-field removal, locking, CLI
+import and remount at 390, 820 and 1440 pixels. Public-editor cases cover phone
+and desktop file persistence. These checks do not execute SQL on a live server.
+
+**LIMITATIONS:** Automatic Vibe64 coding-assistant attachment remains deferred.
+For example, the app can show monthly booking totals through `queries.read`, but
+saving this configuration does not enable Vibe64 chat to query that database.
+Writes, database provisioning/administration and per-user database identity
+management remain native work; use an administrator outside this connector to
+create a reporting user and its row/resource policies. There is no query-builder
+canvas or SQL sandbox. Controlled query tests exercise both credential modes;
+no live SQL service, provisioning or generated application is claimed.