@jskit-ai/connectors-catalog 0.1.1

package/docs/google-oauth.md

@@ -0,0 +1,123 @@
+# Google registrations, configuration and lifecycle
+
+Documentation checked: 12 September 2026. These console steps follow public
+Google documentation; this implementation does not claim signed-in console or
+live-consent verification. Provider tests use simulated HTTP and real temporary
+JSON connection files.
+
+## Shared inputs
+
+| Input | Portable configuration / owner |
+|---|---|
+| Display name | `integrations.<slot>.displayName` |
+| Account use | `accountMode`: shared, per-user or assistant; application policy enforces it |
+| Requested permissions | `scopes`: exact provider scope strings; read defaults are selected |
+| App registration | `authentication.registrationRef`, pointing into `registrations` |
+| Client ID | Registration `clientId`, public web-client identifier |
+| Client secret | Private environment or secret store; registration contains `clientSecretRef` |
+| Callback URL | Full backend route in a private binding referenced by `callbackUrlRef` |
+| People/project access | Application-owned membership and explicit grants, checked before use |
+
+Choosing extra scopes does not install additional business operations. Google
+add-on scopes require an actual add-on context. A Gmail connection is not a
+Google login session for the application; keep login and API grants distinct.
+
+## Manual own-registration setup
+
+1. Sign in to [Google Cloud Console](https://console.cloud.google.com/) using an
+   account authorized to create or administer the application's project.
+2. Use the project selector to choose an existing project, or **New Project**
+   to create one. Record its project ID and quota/billing owner. Choose the
+   organization/location required by the operator's account.
+3. Open **APIs & Services → Library**, find the API named in the provider's
+   guide, and select **Enable**. Enable only APIs required by the app's feature.
+4. Open **Google Auth Platform → Branding**. Enter the public app name, support
+   email and developer contact. Supply the home page, privacy policy, terms and
+   authorized domains required for that application's intended audience.
+5. In **Audience**, choose Internal only for an eligible Workspace organization
+   whose users are the intended audience. Otherwise choose External. While the
+   app is in testing, add the Google accounts that will test the connection via
+   **Audience → Test users → Add users**, then Save. External Testing refresh
+   tokens for these API scopes expire after seven days; reconnect as needed
+   during testing. See [refresh-token expiry](https://developers.google.com/identity/protocols/oauth2#expiration).
+6. In **Data Access**, add the provider guide's recommended read scope. Add more
+   only for operations the app actually implements. Sensitive/restricted scope
+   review depends on the scope and app distribution; follow Google's current
+   [verification requirements](https://developers.google.com/identity/protocols/oauth2/production-readiness/sensitive-scope-verification).
+7. In **Clients**, choose **Create client**, type **Web application**, and give
+   it an environment-specific name. This library implements confidential web
+   clients, including a backend used by a local editor.
+8. Under authorized redirect URIs, add the **exact backend callback URL**, with
+   scheme, host, port when applicable and path. For a local CLI, a registered
+   `http://127.0.0.1:<port>/<callback-path>` is supported. HTTPS is required for
+   remote callbacks. Do not use wildcard VM/project/custom-domain URLs.
+9. Create the client. Copy the Client ID into the registration's `clientId`.
+   Copy or download the secret immediately; it is shown only at creation.
+   Store the secret privately and set `clientSecretRef`, for example
+   `env:GOOGLE_CLIENT_SECRET`. Store the full callback URL under the variable
+   referenced by `callbackUrlRef`. Never put the secret itself into the JSON.
+10. Save `integrations.json`. A CLI uses the same parser and validator as the
+    form. Use encrypted file storage for grants/attempts outside source; there
+    is no database requirement.
+11. The application's trusted owner policy authorizes `beginAuthorization`.
+    For Sheets/Docs/Slides, include the resource ID in `verificationInput` as
+    documented below. Display/open the returned URL in a normal browser.
+12. Recover the initiating authenticated context at the callback and call
+    `completeAuthorization` with the full returned callback URL. The library
+    checks state, PKCE, identity, registration, expiry, granted scopes and a
+    provider read before saving Connected. A denied, expired or repeated
+    callback never creates a successful grant.
+13. Use the named operations from the provider guide. Page tokens and results
+    remain provider data; your application controls caching and presentation.
+14. To replace a lost secret or rotate it, open **Clients**, select the client
+    and choose **Add Secret**. Update the private binding, verify operation,
+    then disable the old secret. See [Google client administration](https://support.google.com/cloud/answer/15549257?hl=en). Replacing the Client ID requires reconnecting. Revoking access
+    from the Google account affects that provider grant; local disconnect
+    removes only the application's stored connection and pending attempts.
+
+## Application and environment boundaries
+
+Each application owns its Google registration, credentials and callback route.
+The same setup applies from a CLI, an installed editor or a hosted editor. There
+is no shared editor registration or universal callback. Set `source` to `own`;
+store the secret in the application's environment and only its reference in JSON.
+
+Use the provider registration that belongs to the application and its intended
+audience. Development and production bindings must resolve to their explicitly
+registered callbacks. When a callback domain changes, update the provider
+registration and environment binding, then reconnect under the new configuration.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md).
+
+The Google Cloud project owns project quotas and billing. Two clients inside
+one Cloud project do not isolate its project quota. Each independent application's
+operator chooses its Cloud project; editor subscription level does not assign
+provider capacity or transfer user grants.
+
+## What an AI can automate
+
+Classification: **assisted API/CLI provisioning**. With authorized Google Cloud
+credentials and sufficient project/organization permissions, an operator can
+use `gcloud projects describe <id>` to check for an existing project and
+`gcloud projects create <id> --name=<name>` when it is absent. Enable the exact
+API with `gcloud services enable <service-name> --project=<id>`; this is a
+repeatable operation. See [project creation](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
+and [Service Usage enablement](https://cloud.google.com/service-usage/docs/enable-disable).
+
+The agent can prepare environment names, JSON references, callback URI lists,
+scope selections and implementation wiring. The established API for managing
+projects is not proof of an API for creating arbitrary Google OAuth web
+clients. This implementation documents client creation and consent branding in
+the console, without inventing an OAuth client-creation endpoint. Billing,
+domain ownership, audience decisions, provider review and user consent require
+the relevant operator/account authority.
+
+## Failure and operation limits
+
+A 401 or invalid refresh grant requires reconnecting. A 403 indicates missing
+scope, provider policy or resource permission; check each rather than silently
+requesting broad permissions. A 429 reports provider limits. Refresh tokens
+are updated under the same connection lock. Removing a configured permission
+blocks operations that depended on it even if an older token had that grant.
+
+No provider calls, sample-app generation or deployment are required by this
+iteration's automated test scope. Real account access remains future acceptance.

package/docs/google-search-console.md

@@ -0,0 +1,124 @@
+# Google Search Console setup and runtime
+
+Documentation checked: 13 September 2026. Automated tests use simulated provider
+responses and real private JSON state; live provider use is outside this delivery.
+
+## Registration and manual setup
+
+Follow all numbered steps in [Google registration setup](google-oauth.md).
+For this connector, choose **Google Search Console API** in APIs & Services → Library and enable
+`searchconsole.googleapis.com` in the selected Cloud project. Create a Web application client
+with the exact backend callback URI. Set the client ID, secret reference and
+callback URL reference in the same registration fields used by the CLI.
+
+In Google Auth Platform → Data Access, select
+`https://www.googleapis.com/auth/webmasters.readonly` for this initial read flow.
+The UI exposes additional documented scopes for applications that need them;
+sitemap writes need `webmasters` and fresh consent. Site Verification scopes
+are for separate native API operations, not implemented here. Use External plus explicit
+test users while testing outside an eligible internal Workspace audience.
+
+## Fields and useful fragment
+
+Provider ID: `google-search-console`. Import its provider from
+`@jskit-ai/connectors-catalog/server/google-search-console`. Display name, scopes, account mode,
+Client ID/secret and callback references follow the shared field mapping.
+Membership and project access are enforced by the host/application policy,
+not by storing untrusted people IDs in application source.
+
+Verification input: `{}`. `sites.list` returns visible property IDs and permission
+levels; an empty list is valid. `sites.get` accepts the exact `siteUrl` identifier.
+Neither operation creates or verifies property ownership.
+
+For a new property open [Search Console](https://search.google.com/search-console),
+choose the property selector and **Add property**. A **Domain** property needs
+Google's displayed DNS TXT record added at your DNS provider, followed by Verify.
+A **URL prefix** property offers methods such as an HTML file or meta tag; keep
+its exact scheme/host/prefix. Follow the method Google displays and retain the
+verification resource. Alternatively an existing owner can use **Settings → Users
+and permissions → Add user**. Client registration and selected scopes do not
+replace those steps. DNS/host changes remain operator-owned actions.
+
+| Operation | Inputs and behavior |
+| --- | --- |
+| `searchAnalytics.query` | siteUrl, inclusive startDate/endDate (`YYYY-MM-DD`), optional dimensions, type, filters, rowLimit and startRow. Finalized data only. |
+| `urlInspection.inspect` | siteUrl, inspectionUrl, optional languageCode; returns Google's indexed snapshot and verdicts, not a live fetch. |
+| `sitemaps.list` / `sitemaps.get` | siteUrl; get also requires the full feedpath URL. Preserve pending/errors/last-download metadata. |
+| `sitemaps.submit` / `sitemaps.delete` | siteUrl and full feedpath. Requires webmasters and applicable property permission. Empty success returns null. |
+
+Performance dates use Google's Pacific-time reporting boundaries. Available
+dimensions are date, country, device, page, query and searchAppearance; duplicates
+are rejected. Type is web, image, video, news, discover or googleNews. Optional
+filters contain dimension/operator/expression and are ANDed. Operators: equals,
+notEquals, contains, notContains, includingRegex and excludingRegex; the provider
+validates RE2 syntax. Date filters use startDate/endDate instead.
+
+rowLimit defaults to 1000 (maximum 25000); increase startRow by returned row count
+until no rows remain. This does not guarantee all underlying traffic rows:
+Google returns top data under its internal limits. Missing rows may mean no
+reportable data, not a broken connection. Return clicks, impressions, CTR and
+position without treating them as proof that all URLs are indexed.
+
+```js
+const report = await connections.invoke({ context, integrationId: "search",
+  operation: "searchAnalytics.query", input: {
+    siteUrl: "sc-domain:example.com", startDate: "2026-09-01", endDate: "2026-09-10",
+    dimensions: ["query"], filters: [{ dimension: "device", operator: "equals", expression: "MOBILE" }]
+  } });
+```
+
+For sitemaps, select **Manage Search Console properties**, add webmasters in Google
+Data Access and reconnect. The app/owner must first publish an accessible sitemap
+file. Submit registers that URL; it neither writes the file nor guarantees Google
+will crawl/index it. Delete removes its Search Console entry, not the hosted file.
+Inspect the entry after an uncertain write before deciding to repeat it.
+
+Other frameworks use the same project config/Env with their native Google client
+or HTTP. The app owns property authorization, report UI, comparisons and indexing
+interpretation; no Vibe64 service receives search data.
+
+**Limitations:** no DNS/HTML ownership deployment, Site Verification API, automated
+indexing requests, sitemap generation, crawler or SEO dashboard. No fresh/hourly
+performance mode or exhaustive traffic export. For example, an app can report
+its popular queries and submit an existing sitemap, but cannot make an unverified
+site appear in Google or guarantee rankings. Editor assistant attachment is
+deferred. Fixtures do not prove live property access or indexing results.
+
+Sources: [performance queries](https://developers.google.com/webmaster-tools/v1/searchanalytics/query),
+[sitemap submission](https://developers.google.com/webmaster-tools/v1/sitemaps/submit),
+[URL inspection](https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect).
+
+The first read must succeed before Connected is returned. Invalid resource
+identifiers fail before opening consent. Denied scopes, wrong account context,
+replayed callbacks and provider rate limits are covered by the automated tests.
+See the [official operation reference](https://developers.google.com/webmaster-tools/v1/sites/list) for the response and resource
+permission requirements; the implementation also checks Google's public API
+discovery document for request paths and supported scope strings.
+
+## Automation and application setup
+
+Classification: **assisted**, as detailed in the common Google guide. An
+operator-authorized AI can check/create the Cloud project and enable
+`searchconsole.googleapis.com` with Service Usage or gcloud. It can prepare this connector's
+JSON and callback/scope values. Web-client creation, branding, audience,
+provider review and account consent remain the documented console/operator
+steps; this adapter does not invent an API for them.
+
+The application owns the Cloud project selection, registration, callback and
+private secret bindings. It uses the same setup from a CLI or either editor.
+Follow the common guide for rotation, revocation, domain changes and recovery.
+Provider quotas belong to the selected Cloud project and resources; editor
+subscription level does not allocate a shared registration.
+
+## AI/CLI wiring
+
+Use the file-store composition from the [connection pattern](../patterns/api-key-connection/PATTERN.md),
+replace the API-key authentication with `oauth2` plus a registrationRef, and
+register this provider. Use beginAuthorization / completeAuthorization instead
+of connectApiKey, with the verification input above. The existing application
+owns authenticated callback routes and its permission policy. Configuration,
+OAuth, refresh, provider requests and storage remain library imports.
+
+## Additional permission choices
+
+The optional `siteverification` and `siteverification.verify_only` choices belong to the separate Site Verification API. They do not authorize Search Console property reads. Applications implementing those operations must enable Site Verification API and wire them separately; this fragment does not change site ownership. See [Site Verification authorization](https://developers.google.com/site-verification/v1/getting_started).

package/docs/google-sheets.md

@@ -0,0 +1,94 @@
+# Google Sheets setup and runtime
+
+Documentation checked: 13 September 2026. Provider responses are simulated;
+no live account, real spreadsheet or generated app has been exercised.
+
+## Registration and connection
+
+1. Follow [Google registration setup](google-oauth.md): select this application's
+   Cloud project, configure Google Auth Platform Branding/Audience and add test users.
+2. APIs & Services → Library → **Google Sheets API** → Enable. For the default
+   create-first connection, also enable **Google Drive API**.
+3. Google Auth Platform → Data Access → Add or Remove Scopes → select
+   `https://www.googleapis.com/auth/drive.file` → Update/Save. This grants only
+   files created by or explicitly opened/selected for this app. An arbitrary
+   spreadsheet ID does not grant access. The app wires Google Picker if needed.
+4. Clients → Create Client → Web application → Authorized redirect URIs → Add URI.
+   Paste the app backend callback displayed in the editor, then Create. Copy the
+   client ID and secret immediately. The common guide explains reviews, Testing
+   token expiry and rotation; the editor address is not the callback.
+5. Save the registration fields in integrations.json. Use **Set credential in Env**
+   and **Set callback in Env** for the private values named by their references.
+   CLI users write the same file and set the same app Env values themselves.
+6. Leave **Spreadsheet ID (optional)** blank to verify accessible Drive metadata.
+   An empty list succeeds without creating a file; this does not prove Sheets API
+   is enabled. To verify an existing file, copy the ID between `/spreadsheets/d/`
+   and `/edit`, not its tab's `gid`. Both the account and app need access.
+7. For read-only existing sheets, choose `spreadsheets.readonly` and supply the ID.
+   `spreadsheets` grants broader writes. Add selected scopes in Data Access and
+   reconnect after changing them. Drive metadata-only permission cannot read cells.
+   Broad Drive access can require restricted-scope review.
+
+## Application operations
+
+Import `googleSheetsProvider` from
+`@jskit-ai/connectors-catalog/server/google-sheets`. Register it with the existing
+connection service/file store; the app authenticates each subject and owns its
+callback, consent, grants and authorization policy. For a shared connection the
+app administrator authorizes once; per-user connections require individual consent.
+Use `beginAuthorization` with `verificationInput: {}` for create-first, then
+`completeAuthorization`. [Connection composition](../patterns/api-key-connection/PATTERN.md)
+shows configuration/storage; substitute OAuth plus registrationRef for API-key auth.
+
+| Operation | Input and effect |
+| --- | --- |
+| spreadsheets.create | title; returns a new spreadsheet and initial sheet. |
+| spreadsheets.get | spreadsheetId; metadata without grid data. |
+| values.get | spreadsheetId, range; optional valueRenderOption FORMATTED_VALUE, UNFORMATTED_VALUE or FORMULA, and dateTimeRenderOption SERIAL_NUMBER or FORMATTED_STRING. |
+| values.update | spreadsheetId, range, values (row matrix); valueInputOption defaults RAW. |
+| values.append | Same fields; insertDataOption defaults INSERT_ROWS, optionally OVERWRITE. Google detects the logical table before appending. |
+| values.clear | spreadsheetId, range; clears values, preserving formatting/validation. |
+| values.batchUpdate | spreadsheetId, data [{range, values}], valueInputOption; writes several ranges. |
+| spreadsheets.batchUpdate | spreadsheetId, requests [{nativeOperation: {...}}]; sheet creation/deletion, formatting and other native updates. Google validates operation semantics. |
+
+```js
+const sheet = await service.invoke({ ...connection, operation: "spreadsheets.create", input: { title: "Bookings" } });
+await service.invoke({ ...connection, operation: "values.update", input: {
+  spreadsheetId: sheet.spreadsheetId, range: "Sheet1!A1:B2",
+  values: [["Customer", "Amount"], ["Example", 40]]
+} });
+```
+
+Use A1 ranges and quote sheet titles with spaces/apostrophes using Google's rules.
+The adapter URL-encodes the whole range. Value matrices use ROWS, finite numbers,
+strings, booleans and null; null skips a cell and an empty string clears it.
+RAW is safe for untrusted strings such as `=IMPORTXML(...)`; USER_ENTERED explicitly
+allows formulas and parses dates/numbers according to spreadsheet locale. Formula
+reads use FORMULA; formatted output is locale-dependent. Empty ranges may omit values.
+
+Each matrix is limited to 10,000 cells/1 MiB; multi-range/native batches to 100
+entries/1 MiB. Native formatting requests use sheet numeric IDs, zero-based grid
+indices and explicit field masks. These differ from the spreadsheet ID/A1 ranges.
+The app owns authorization, conflict detection and any chunking of larger work.
+No automatic retry follows a timeout/503: inspect the spreadsheet before repeating
+an append/create, or duplicate rows/files may result.
+
+Other frameworks use their native Google client or HTTP implementation with the
+same project-owned JSON/Env configuration; JSKIT is optional and requires no Vibe64
+runtime. No PHP code or editor-specific credential service is involved.
+
+## Provisioning and limitations
+
+An authorized AI can enable APIs via gcloud/Service Usage and prepare JSON/Env
+references. Client creation, branding, audience, provider review and consent follow
+the console steps above; credentials do not bypass Google approval.
+
+**LIMITATIONS:** No spreadsheet designer, embedded Picker, background synchronization,
+Apps Script engine or editor-assistant attachment. For example the app can append a
+booking and format its header, but must build its own table UI and ask the user to
+select an existing private spreadsheet. Live Google behavior remains unproven.
+
+References: [values guide](https://developers.google.com/workspace/sheets/api/guides/values),
+[append](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/append),
+[batch updates](https://developers.google.com/workspace/sheets/api/guides/batchupdate),
+[create](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/create).

package/docs/google-slides.md

@@ -0,0 +1,95 @@
+# Google Slides setup and runtime
+
+Documentation checked: 13 September 2026. Tests use simulated HTTP and private
+file storage. No live Google presentation, consent or generated app was exercised.
+
+## Set up the project-owned registration
+
+1. Follow [Google registration setup](google-oauth.md): select this application's
+   Cloud project; Google Auth Platform → Branding/Audience → configure app details
+   and permitted test accounts. Public access requires the applicable review.
+2. APIs & Services → Library → **Google Slides API** → Enable. Also enable
+   **Google Drive API** for create-first connection verification.
+3. Google Auth Platform → Data Access → Add or Remove Scopes → select
+   `https://www.googleapis.com/auth/drive.file` → Update/Save. This permits files
+   created by or explicitly selected/opened for this app. For existing-file
+   selection, the generated app wires Google Picker; typing an ID grants nothing.
+4. Clients → Create Client → Web application → Authorized redirect URIs → Add URI.
+   Paste the app backend callback displayed in the editor, then Create. Copy its
+   client ID and secret immediately. Use the common guide for lost-secret rotation,
+   Testing refresh-token expiry and domain changes.
+5. Enter the client ID and Env references, then Save configuration. **Set credential
+   in Env** stores the secret; **Set callback in Env** stores the exact registered
+   URL. CLI users set the same references/file without Vibe64.
+6. Leave **Presentation ID (optional)** blank to verify accessible Drive metadata.
+   Empty metadata is accepted without creating a deck; it does not verify that
+   Slides API is enabled. For an existing deck, copy the ID between `/presentation/d/`
+   and `/edit`, not a slide object ID. Both user and app must have access.
+7. Read-only existing decks can instead use `presentations.readonly` with that ID.
+   `presentations` permits broader edits; enable selected scopes in Data Access and
+   reconnect after changes. Spreadsheet scopes alone do not grant presentation
+   access. Linked charts may separately require access to their source spreadsheet.
+
+## Runtime and framework ownership
+
+Import `googleSlidesProvider` from `@jskit-ai/connectors-catalog/server/google-slides`.
+Register it with the existing connection service/file store. The application owns
+subject authorization, backend callbacks, consent and credentials. Compose the
+[connection pattern](../patterns/api-key-connection/PATTERN.md) with OAuth and a
+registrationRef, then `beginAuthorization` / `completeAuthorization`; use empty
+verificationInput for create-first or `{ presentationId }` for an existing deck.
+Other frameworks use native Google SDK/HTTP with the same project JSON/Env contract;
+JSKIT is optional and has no dependency on the editor at runtime.
+
+| Operation | Input / useful result |
+| --- | --- |
+| presentations.create | title; creates a blank deck and returns its ID. |
+| presentations.get | presentationId; title, slides, objects and revision. |
+| presentations.batchUpdate | presentationId, requests, optional requiredRevisionId; native slide/text/image/format/duplicate/delete-object changes. |
+| pages.get | presentationId, pageObjectId; one slide/page. |
+| pages.getThumbnail | Same IDs, optional size SMALL/MEDIUM/LARGE; temporary HTTPS contentUrl and dimensions. |
+
+```js
+const deck = await service.invoke({ ...connection, operation: "presentations.create", input: { title: "Bookings" } });
+await service.invoke({ ...connection, operation: "presentations.batchUpdate", input: {
+  presentationId: deck.presentationId,
+  requests: [
+    { createSlide: { objectId: "booking_slide", slideLayoutReference: { predefinedLayout: "BLANK" } } },
+    { createShape: { objectId: "booking_title", shapeType: "TEXT_BOX", elementProperties: {
+      pageObjectId: "booking_slide", size: { width: { magnitude: 400, unit: "PT" }, height: { magnitude: 60, unit: "PT" } },
+      transform: { scaleX: 1, scaleY: 1, translateX: 40, translateY: 40, unit: "PT" }
+    } } },
+    { insertText: { objectId: "booking_title", text: "Bookings this week", insertionIndex: 0 } }
+  ]
+} });
+```
+
+Batches accept 1–100 native request objects within 1 MiB. Google validates request
+semantics; the app supplies object IDs, positions, field masks and permissions.
+Use `requiredRevisionId` from a recent read to reject concurrent changes; stale
+revision returns a provider error instead of being silently overwritten. This
+adapter never retries uncertain creates/edits; inspect the deck before repeating.
+Images must be reachable by Google and meet its image restrictions. Linked-chart
+requests require source access; there is no automatic grant or chart sync worker.
+
+Thumbnail URLs are temporary capabilities: render only to authorized users, avoid
+logging them, and request a fresh thumbnail when expired. The adapter returns the
+URL without downloading it or forwarding tokens to its host. The app owns CSP,
+image rendering and whether to persist a permitted copy. Whole-file copying,
+sharing, export and trash belong to the separately authorized Drive API.
+
+## Automation and limitations
+
+Authorized AI can enable APIs using gcloud/Service Usage and prepare configuration;
+client creation, branding, audience, approval and consent follow the console steps.
+No Vibe64-owned Google registration or gateway is required.
+
+**LIMITATIONS:** No visual slide designer, template library, embedded Picker,
+whole-file sharing/export UI or editor-assistant attachment. For example an app can
+create a booking summary deck and preview a slide, but must provide its own design
+and access controls. Native/live rendering and actual Google approval are unproven.
+
+References: [API methods](https://developers.google.com/workspace/slides/api/reference/rest),
+[batch requests](https://developers.google.com/workspace/slides/api/guides/batch),
+[write control](https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/batchUpdate),
+[thumbnails](https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/getThumbnail).

package/docs/granola.md

@@ -0,0 +1,178 @@
+# Granola
+
+Import `granolaProvider` from `@jskit-ai/connectors-catalog/server/granola`.
+This initial API-key adapter reads notes, folders and transcript pages. It uses
+the shared JSKIT connection service and encrypted file store. CLI and editor
+users own the same JSON; no generated application or database is required.
+
+## Create the provider credential
+
+For a personal key:
+
+1. Open the Granola desktop app, then **Settings → Connectors → API keys**.
+2. Choose **Create new key**. Select the note access scopes, then **Generate
+   API Key**. Store the returned `grn_` value in `GRANOLA_API_KEY` outside source.
+3. In Vibe64 select **Granola** and enter `env:GRANOLA_API_KEY` as the API key
+   reference. Choose the intended owner and **Save configuration**. Use
+   **Set credential in Env** to save the key as `GRANOLA_API_KEY`, then return
+   and choose **Connect account**. CLI users write the JSON below.
+
+For a workspace key, an admin opens **Settings → Connectors → Workspace API
+keys → Create new key**. Workspace keys belong to the workspace. Both key paths
+require Business or Enterprise. Enterprise admins manage member scope access
+under **Settings → Workspace → General → API access for members → Manage**.
+Workspace API access to spaces is controlled separately under **Settings → Spaces**.
+[Key creation and administration](https://docs.granola.ai/help-center/sharing/integrations/granola-api)
+
+Personal keys can include Personal notes and/or Public notes access. Workspace
+keys use the workspace's permitted public notes and spaces. These permissions
+are set in Granola, not in this JSON. They do not mean arbitrary private content
+is accessible. [API access model](https://docs.granola.ai/introduction)
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "meetings": {
+      "provider": "granola",
+      "displayName": "Team meeting notes",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:GRANOLA_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Saving this file only configures the integration. The host calls `connectApiKey`
+to verify access through `notes.list`; a successful empty page is valid. The
+host's `authorize` function must map authenticated callers to the intended stable
+application/subject. Shared mode deliberately shares one key's accessible data;
+assistant mode uses its owner's connection. API-key mode does not offer personal
+OAuth consent; the separate MCP mode below does. A CLI uses a trusted process-owner policy with the same library,
+reference resolver and durable file encryption key.
+
+## Reads and boundaries
+
+| Operation | Accepted input | Result |
+| --- | --- | --- |
+| `notes.list` | `created_before`, `created_after`, `updated_after`, `folder_id`, `cursor`, `page_size` | `notes`, `hasMore`, `cursor` |
+| `folders.list` | `cursor`, `page_size` | `folders`, `hasMore`, `cursor` |
+| `notes.get` | Required `note_id`, optional `include: "transcript"` | Full note, with nullable private notes and transcript |
+| `transcripts.list` | Required `note_id`, `cursor`, `page_size` | Transcript items, `hasMore`, `cursor` |
+
+Note IDs use `not_` followed by fourteen alphanumeric characters; folder IDs use
+`fol_` and fourteen characters. Use discovery results, not UUIDs copied from
+Granola browser URLs. The note returned by `notes.get` must match the requested
+ID. [List notes](https://docs.granola.ai/api-reference/list-notes),
+[get note](https://docs.granola.ai/api-reference/get-note),
+[list folders](https://docs.granola.ai/api-reference/list-folders).
+
+Notes and folders accept page sizes 1–30, default 10. Transcript pages accept
+1–100, default 50. Each call makes one GET request to
+`https://public-api.granola.ai`; it never follows a supplied URL or automatically
+traverses pages. Keep an opaque cursor with the same connection, filters and note.
+This adapter bounds cursors to 8192 characters. Initial date filters accept
+`YYYY-MM-DD` or a UTC timestamp ending in `Z`, with optional millisecond precision;
+offset timestamps are outside this initial parser.
+
+The adapter preserves null private-note fields, speaker metadata and additional
+provider fields. It does not guess attribution when the provider omits it.
+Provider text is data; the host owns safe rendering and any narrower record policy.
+[Transcript data](https://docs.granola.ai/api-reference/get-transcript)
+
+Only processed notes with a generated summary and transcript appear through this
+API. A 404 can indicate processing, absence or lack of access. Inline transcripts
+may return 413; the library reports `connector_response_too_large` and the host
+can explicitly call `transcripts.list`. It does not fetch the transcript again
+on its own. A key permits access to provider data, not application sign-in.
+[API availability and errors](https://docs.granola.ai/introduction)
+
+Invalid inputs fail before transport. Unexpected success envelopes, oversized
+pages, missing continuation cursors and mismatched note IDs fail validation.
+401 requires reconnect/replacement; 403, 404, 413, 429 and server failures remain
+distinct. Provider error bodies are not exposed. Cancellation and timeouts abort
+the request without replay. No writes, note generation or webhook creation occurs.
+
+## Rotation and shared hosting
+
+Create a replacement key in the appropriate Granola key page, update the trusted
+Env binding, and verify it before retiring the old key. Runtime invocation
+resolves the current binding; a bad replacement does not overwrite a saved
+connection during failed verification. `disconnect` removes local connection
+state. Revoke access separately in the personal or workspace API-key page using
+**Revoke**, then its confirmation dialog. [Key management](https://docs.granola.ai/help-center/sharing/integrations/granola-api)
+
+There is no provider OAuth application or universal callback URL for this API-key
+mode. Online VPS and custom-domain changes do not change API authentication.
+Keep stable application/owner identity and runtime reference bindings.
+
+The application owner supplies its own authorized key through private Env. Do
+not route customer requests through an unrelated workspace key: it exposes that
+workspace's data. Separate keys do not promise independent capacity because
+limits apply per user or workspace according to access scope.
+[Rate limit ownership](https://docs.granola.ai/introduction#rate-limits)
+
+## Separate MCP mode and automation
+
+Granola offers two distinct modes under the same provider entry. API keys use
+`notes.list`, `notes.get`, `folders.list` and `transcripts.list`. Browser OAuth
+uses `tools.list` and `tools.call` against `https://mcp.granola.ai/mcp`.
+The runtime rejects calls belonging to the other authentication method before
+refresh or transport. MCP verification lists tools; it does not read a meeting.
+
+For the MCP assistant connection:
+
+1. Select Assistant access and OAuth. Keep `openid`, `profile`, `email` and
+   `offline_access` selected. Free accounts have limited personal-note access;
+   workspace settings and subscription determine the available tools.
+2. Confirm the suggested callback is the exact route served by the assistant
+   host. In Vibe64 choose **Register client and connect**: the existing project
+   registration action stores the client ID in configuration and secret, callback
+   and recovery ID in development Env, then invokes the app-owned setup command.
+   Existing Env values are not replaced; inspect Env after uncertain registration.
+   Alternatively use the screen's OAuth client registration endpoint and JSON request,
+   or call `registerGranolaClient({ clientName, callbackUrl })` from this package's
+   `server/granola` export. Registration is a setup action, never a per-request
+   action. The helper uses Granola's advertised DCR endpoint and confidential
+   `client_secret_post` authentication.
+3. Copy `client_id` into Client ID and save configuration. Use Set credential in
+   Env to store `client_secret` under the displayed reference. Use Set callback
+   in Env to save the same callback used for registration. Preserve the response
+   privately; do not put its secret in configuration or browser source.
+4. Connect account, sign into Granola and approve access. Select the intended
+   active workspace in Granola. The host authorizes each tool and its arguments.
+5. Disconnect removes the local grant. It does not promise provider-wide
+   revocation. Granola's guide does not document a general revocation screen for
+   custom MCP clients; contact `hey@granola.so` when provider assistance is needed.
+
+[Granola MCP](https://docs.granola.ai/help-center/sharing/integrations/mcp) and
+[live OAuth metadata](https://mcp-auth.granola.ai/.well-known/oauth-authorization-server)
+were reviewed on 2026-09-12. Registration, callbacks, tokens and runtime belong
+to the initiating application/assistant host. There is no Vibe64 gateway.
+Granola advertises DCR for compatible clients. The explicit Register client and
+connect action uses its existing helper; plain Connect does not silently create
+registrations. Enterprise-managed authorization is not implemented here.
+
+AI can write and validate the file, compose the existing library, prepare host
+routes and automate the documented read operations after authorised credential
+setup. The reviewed API documentation does not establish an endpoint for creating
+personal/workspace API keys. Key creation, permissions, account sign-in and required
+provider subscription are operator/provider steps. Vibe64 need not gate its own
+form, but cannot remove Granola's subscription or permission requirements.
+
+Focused proof uses controlled HTTP responses and temporary encrypted files,
+including rotation, ownership, pagination, malformed data and interruption.
+No live keys, meetings, provider registrations, generated apps or deployments are
+used. The MCP fixture covers PKCE, verification, restart/refresh, replay rejection and credential-mode isolation. The controlled dual-mode browser journey and rendered setup instructions passed review. No live OAuth client or provider account was used. Webhooks, REST mutations and enterprise-managed authorization are not implemented.
+
+**LIMITATIONS:** The app/assistant host must authorize and attach MCP tools itself.
+Vibe64 coding-assistant attachment is deferred: configuring Granola does not make
+Codex or OpenCode able to answer questions about meetings. For example a generated
+app can read a processed meeting transcript with the API key, but this editor will
+not automatically use it as chat context. No REST note creation, recording engine,
+webhook receiver or enterprise-managed OAuth is installed.