@jskit-ai/connectors-catalog 0.1.1

package/docs/firebase-cloud-messaging.md

@@ -0,0 +1,262 @@
+# Firebase Cloud Messaging
+
+Import `firebaseCloudMessagingProvider` from
+`@jskit-ai/connectors-catalog/server/firebase-cloud-messaging`.
+The library validates and sends HTTP v1 messages using an explicitly supplied
+service-account credential. Saving configuration does not contact Google.
+Connecting performs a dry-run check; it does not deliver a notification.
+
+## Set up the provider
+
+1. In the [Firebase console](https://console.firebase.google.com/), open the
+   project that will own the receiving installations. For a new project, choose
+   **Create a project**, supply its name and complete the console's setup.
+2. Open the gear beside **Project Overview**, then **Project settings**.
+   Under **General**, copy **Project ID** into the form. This is the lowercase
+   textual identifier, not the display name or numeric project number.
+3. Open **Cloud Messaging**. Ensure **Firebase Cloud Messaging API (V1)** is
+   enabled; use its linked Google Cloud API page to enable it if necessary.
+4. Open **Service accounts**, then **Generate new private key** and
+   **Generate key**. Store the complete downloaded JSON as a private server
+   environment value, for example `FIREBASE_SERVICE_ACCOUNT`. The source file
+   contains only `env:FIREBASE_SERVICE_ACCOUNT`.
+5. For a dedicated sender identity, use Google Cloud **IAM & Admin > Service
+   Accounts**. Create/select the account, then **Keys > Add key > Create new
+   key > JSON > Create**. Give this identity **Firebase Cloud Messaging API
+   Admin** on the target project, or an appropriate custom role. Organization
+   policy can prevent key creation. Do not substitute an unrelated credential.
+6. In Vibe64, enter `env:FIREBASE_SERVICE_ACCOUNT` in **Service-account JSON
+   reference**, then **Save configuration**. Follow **Set credential in Env**
+   and store the complete JSON under `FIREBASE_SERVICE_ACCOUNT`, not a filename
+   or path. Return to the integration and connect. CLI applications supply the
+   same environment value and call `connectServiceAccount` from their authorized
+   server. Verification requests an access token and checks the target project
+   with a validate-only topic message; no notification is delivered.
+7. If verification fails, check the target project ID, enabled API and sender
+   IAM grant. Disconnect removes the application's local connection; it does not
+   delete the Google key. Rotate or delete keys under Google Cloud **IAM & Admin
+   > Service Accounts > your sender > Keys**. Update Env when rotating.
+
+Firebase documents the service-account setup, messaging scope and cross-project
+sender permissions in its [HTTP v1 guide](https://firebase.google.com/docs/cloud-messaging/send/v1-api).
+Google documents the console/API key lifecycle and organization restrictions
+in [service-account key management](https://docs.cloud.google.com/iam/docs/keys-create-delete).
+
+## Optional browser setup
+
+Select **Include web push** to reveal three additional fields:
+
+| Field | Console source | Exposure |
+|---|---|---|
+| Firebase API key | Project settings > General > Your apps > Web app > SDK setup and configuration: `apiKey` | Public |
+| Firebase App ID | Same configuration: `appId` | Public |
+| Web Push VAPID key | Project settings > Cloud Messaging > Web configuration > Web Push certificates | Public key only |
+
+If there is no Web app, click the Web icon under **Your apps**, enter a nickname,
+and choose **Register app**. Firebase Hosting is not required for another host.
+Under **Web Push certificates**, choose **Generate Key Pair** when none exists,
+then copy the public key. Keep these values in the same Firebase project.
+
+The application still needs HTTPS, a service worker, notification permission and
+browser registration. The current Firebase Web API uses `register` and
+`onRegistered` to obtain installation IDs. Existing registration-token APIs are
+deprecated but remain a supported target in this adapter. Do not mix both client
+registration approaches in one app. See [Firebase Web setup](https://firebase.google.com/docs/cloud-messaging/web/get-started).
+
+`firebaseCloudMessagingWebConfiguration(settings)` from
+`@jskit-ai/connectors-catalog/client/firebase-cloud-messaging` returns
+`{ firebaseConfig, vapidKey }`. It validates web mode, projects only public
+fields and derives `messagingSenderId` as text from `appId`. It neither asks for
+notification permission nor loads credentials. Use it with the Firebase SDK
+version installed by the application, whose registration APIs must be verified.
+Switching back to **Server or native only** removes the three web-only settings.
+
+## Portable configuration
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "push": {
+      "provider": "firebase-cloud-messaging",
+      "displayName": "Application notifications",
+      "accountMode": "shared",
+      "scopes": ["https://www.googleapis.com/auth/firebase.messaging"],
+      "authentication": {
+        "method": "service-account",
+        "secretRef": "env:FIREBASE_SERVICE_ACCOUNT"
+      },
+      "settings": {
+        "projectId": "my-notifications-app",
+        "clientMode": "server"
+      }
+    }
+  }
+}
+```
+
+For web push, use `clientMode: "web"` and add `apiKey`, `appId` and `vapidKey`.
+The same schema validates files edited by hand, AI or Vibe64. It accepts
+`shared` and explicitly authorized `assistant` ownership. This service account
+does not represent a separate Google identity for every app user.
+
+The target project setting is explicit even though the credential also contains
+`project_id`: Google supports a sender service account in a different project.
+IAM must grant that sender access to this target. Changing the target, settings,
+scopes or secret reference requires verification again.
+
+## Runtime and useful operations
+
+The provider accepts JSON of type `service_account` with `project_id`,
+`client_email`, `private_key`, `private_key_id`, and Google's fixed `token_uri`.
+An optional `universe_domain` must be `googleapis.com`. It does not load external
+account files, application-default credentials, metadata servers or delegated
+user identities. `jose` signs an RS256 assertion with a one-hour lifetime; the
+fixed Google token endpoint exchanges it for a short-lived access token.
+[Google's service-account protocol](https://developers.google.com/identity/protocols/oauth2/service-account)
+
+The shared core caches the token in the encrypted file store, renews under its
+existing connection lock, resolves credential rotation before the next request,
+and exposes only safe connection metadata. Raw service-account JSON is not
+stored in the connection or sent to the FCM message endpoint.
+
+| Operation | Input | Effect |
+|---|---|---|
+| `connection.check` | `{}` | Fixed topic/data payload with `validate_only: true` |
+| `messages.validate` | `{ message }` | Validates the supplied message without delivery |
+| `messages.send` | `{ message }` | Explicitly submits the supplied message for delivery |
+
+`message` requires exactly one of `fid`, `token`, `topic`, or `condition`, plus
+`notification` and/or `data`. Common notification fields are `title`, `body` and
+an HTTPS `image` URL. Data values must be strings and keys cannot use Firebase's
+reserved prefixes. The adapter bounds the serialized message to 4,096 UTF-8
+bytes for individual targets or 2,048 for topics/conditions. It returns a
+validated `{ name: "projects/.../messages/..." }` receipt; a receipt confirms
+acceptance, not device delivery. No automatic retry or batch fan-out occurs.
+[Message fields](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages),
+[send and validate-only API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages/send)
+
+Example authorized call:
+
+```js
+await connections.invoke({
+  context: trustedContext,
+  integrationId: "push",
+  operation: "messages.validate",
+  input: { message: {
+    fid: installationOwnedByTheRecipient,
+    notification: { title: "Order ready", body: "Your order is ready." },
+    data: { orderId: "42" }
+  } }
+});
+```
+
+The application's policy must authorize the audience and payload before a
+`messages.send` action. A shared service credential grants no user permission
+to send to arbitrary installations or topics. No login functionality is implied.
+
+## Public, Online and custom domains
+
+**Universal OAuth callback URL: not applicable.** Service-account authorization
+is a server-to-server exchange, with no browser redirect to register. A VPS
+address or custom domain does not change the target project or that exchange.
+Browser notification permission, service workers and registrations belong to
+the origin, so register the app on each new custom domain and update its stored
+installation association. Existing cookies or browser permissions do not move
+between unrelated domains.
+
+The application owner supplies the Firebase project and sender credentials.
+Online and installed-editor projects use the same configuration and runtime;
+Vibe64 supplies no shared Firebase project or platform sender key. Two service
+accounts or Web apps inside one project do not split its project quota.
+[FCM quota ownership](https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas)
+
+Keep sender private keys in the application's private Env or credential store.
+The application backend authorizes notification requests and owns installation
+associations. The same source schema remains available to CLI applications;
+editing configuration does not provision a Firebase project or grant IAM access.
+
+## Can AI automate the setup?
+
+| Work | Feasibility and required authority |
+|---|---|
+| Create the application’s Cloud project | Resource Manager `projects.create`; organization policy, project limits and any required billing association still apply |
+| Add Firebase and Web apps | Management API `projects.addFirebase`, `projects.webApps.create` and `projects.webApps.getConfig`; use an authorized management identity and inspect operation completion |
+| Create a sender and key | IAM service-account creation and `projects.serviceAccounts.keys.create`; requires explicit administrative permission, and key creation may be prohibited |
+| Configure target-project IAM | An administrator can grant the sender the required messaging permission; preserve unrelated IAM policy bindings |
+| Web VAPID pair | Console workflow above; this implementation does not claim a verified automation API for it |
+| Device/browser enrollment | Application SDK wiring and the user's notification permission remain necessary |
+
+An AI can prepare calls and configuration when given authorized management
+access; an FCM-only sending credential is insufficient for provisioning.
+No provisioning calls run when saving or connecting this integration.
+[Management API workflow](https://firebase.google.com/docs/projects/api/workflow_set-up-and-manage-project)
+
+## Proof and remaining work
+
+Controlled tests verify real JWT signatures with generated fixture keys, fixed
+destinations, dry-run flags, target/input validation, malformed and denied
+responses, file restart, renewal, rotation, ownership and interruption.
+The browser form checks exercise source persistence and validation, not Google.
+No live project, IAM setup, notification, browser subscription or generated app
+has been exercised. The initial message fragment does not yet expose Android,
+APNs or Webpush override objects, topic subscription administration, delivery
+tracking or retry scheduling. Data-only iOS delivery can require APNs options
+outside this initial fragment. These are explicit limits, not proven workflows.
+
+## Client enrollment and expired recipients
+
+The app owns the registration endpoint and storage. It may use ordinary files or
+its own selected storage; this connector does not add a database to Vibe64. The
+backend authenticates the current user, binds each FID/token to that user and
+device, and updates a server timestamp. Do not accept an arbitrary user ID as
+proof of ownership. Support multiple devices and remove the association on
+logout/unsubscribe as appropriate. Store registrations privately.
+
+For a Firebase Web SDK supporting the current FID APIs, compose your public
+configuration helper with native SDK calls:
+
+```js
+// Application frontend: its installed Firebase SDK owns registration.
+import { initializeApp } from "firebase/app";
+import { getMessaging, onRegistered, register } from "firebase/messaging";
+const messaging = getMessaging(initializeApp(firebaseConfig));
+onRegistered(messaging, installationId => saveRegistrationForCurrentUser(installationId));
+// Call from an explicit user action; create firebase-messaging-sw.js at the origin root.
+if (await Notification.requestPermission() === "granted") {
+  await register(messaging, { vapidKey });
+}
+```
+
+`saveRegistrationForCurrentUser` is an authenticated application endpoint, not a
+JSKIT export. Wire foreground `onMessage` and service-worker background handling
+using the installed Firebase SDK; avoid duplicate notifications if the SDK
+already displays a notification payload. Use HTTPS and feature detection, and
+show permission-denied/unsupported states. Do not mix FID APIs with older
+getToken-based registration in one app. Verify the SDK version exposes the
+selected API. [Web enrollment](https://firebase.google.com/docs/cloud-messaging/web/get-started).
+
+Native Android/Apple apps use their native Firebase SDK and registration-change
+callbacks to upload the current identifier through the same app-owned endpoint.
+Apple apps also need their APNs credential/configuration in Firebase and platform
+notification entitlements; web VAPID does not configure Apple native delivery.
+This provider's common notification/data fields do not expose platform-specific
+APNs/Android overrides; use the native admin client for those advanced payloads.
+
+`connector_recipient_unregistered` means a targeted FID/token received typed FCM
+UNREGISTERED (404). Remove that recipient association; the sender connection
+remains usable. A plain 404 is not enough to remove registrations.
+`connector_message_invalid` means HTTP 400: fix/validate the payload before
+concluding the target is invalid. Never clear all devices or revoke the service
+account for one stale recipient. Other failures keep the existing denied/rate
+limit/provider error behavior, with no automatic send retries.
+[Registration lifecycle](https://firebase.google.com/docs/cloud-messaging/manage-tokens).
+
+**LIMITATIONS:** Configuring the connector does not create a push opt-in UI,
+service worker, device registry or coding-assistant attachment. For example, an
+app can send an order-ready message after enrolling the customer's browser;
+saving the Firebase fields alone does not enroll that browser. The application
+owns those native SDK/UI pieces, delivery observation and any retry scheduling.
+Other frameworks consume the same config/Env using native Google/Firebase tools;
+JSKIT remains optional. No live browser subscription or notification was tested.

package/docs/firecrawl.md

@@ -0,0 +1,137 @@
+# Firecrawl setup and implementation
+
+Documentation checked: 13 September 2026. Signed-in console steps and live
+provider requests have not been exercised. Automated tests simulate the
+provider and do not scrape a real site.
+
+## Capability and input ownership
+
+`credits.read` verifies the team key without starting paid work. The application
+explicitly authorizes each operation below; the runtime never automatically
+replays paid work or polls jobs in the background.
+
+| Operation | Inputs and result |
+|---|---|
+| `pages.scrape` | HTTP(S) URL, optional `onlyMainContent`; Markdown and metadata |
+| `pages.search` | `query`, optional `limit` (1–100, default 5), `includeContent`; web results, optionally scraped Markdown |
+| `sites.map` | URL, required `limit` (1–1000), optional `search`; discovered links |
+| `pages.extract` | URL, required JSON `schema`, optional `prompt`; `data.json` |
+| `crawls.start` | URL, required page `limit` (1–1000), optional `maxDiscoveryDepth` (0–10, default 2); job ID |
+| `crawls.get` | Job `id`, optional returned `next` URL; status, counts, content and next page |
+| `crawls.errors` | Job ID; failed pages and blocked URLs |
+| `crawls.cancel` | Job ID; cancellation acknowledgement |
+
+Crawls exclude external links and subdomains. Store each result page and follow
+`next` until absent: a completed job does not mean the first response contains
+all content. Only next URLs on the exact same Firecrawl job path are accepted.
+Inspect errors before describing an import as complete; cancellation does not
+refund work already performed. The app owns job IDs, its users' authorization,
+recurring schedules, result retention and search/index storage.
+
+| Input | Destination | Rule |
+|---|---|---|
+| Display name | integration `displayName` | Optional, 1–200 characters when present |
+| Own API key | Server environment/secret store | Value never goes into `integrations.json` |
+| API key reference | `authentication.secretRef` | For example `env:FIRECRAWL_API_KEY` |
+| Shared account / assistant | `accountMode` | Caller authorized by application policy |
+| People with access | Host membership/connection grants | Not granted merely by editing application source |
+
+## Manual setup
+
+1. Open [Firecrawl](https://www.firecrawl.dev/) and sign in. Choose the team that
+   should pay for the application's requests. Check its available credits and
+   plan before enabling application operations.
+2. Open [API Keys](https://www.firecrawl.dev/app/api-keys), the direct destination
+   linked from the official introduction, and create or copy a team key. The
+   [introduction](https://docs.firecrawl.dev/introduction) and
+   [authentication guide](https://docs.firecrawl.dev/api-reference/v2-introduction)
+   identify the dashboard as the source of the API key. Exact signed-in menu
+   labels may differ; these have not been inspected for this implementation.
+3. Store the value in the private environment or secret store as
+   `FIRECRAWL_API_KEY`. In the form enter the reference
+   `env:FIRECRAWL_API_KEY`, click **Save configuration**, then follow **Set
+   credential in Env** to store the real key. Return and connect. This saves
+   the same file a CLI user would author, with
+   `authentication.method: "api-key"`, empty scopes and no OAuth registration.
+4. Wire the runtime using the shared API-key pattern. Invoke `connectApiKey`;
+   its [credit-usage read](https://docs.firecrawl.dev/api-reference/endpoint/credit-usage)
+   succeeds when `success` is true and `data.remainingCredits` is numeric. Zero
+   credits still identifies a valid account; it does not promise that a scrape
+   can proceed.
+5. For an explicitly authorized operation call `pages.scrape` with a page URL.
+   The [scrape API](https://docs.firecrawl.dev/api-reference/endpoint/scrape)
+   returns `data.markdown` and metadata. The connector sends the URL as JSON to
+   Firecrawl, not as the destination of the authenticated HTTP request. It
+   rejects non-HTTP URLs and embedded URL credentials locally.
+6. A 401 means the key must be corrected and reconnected; a 403 means denied
+   permissions. Rate limits, exhausted credits, scrape failures and unexpected
+   bodies must remain visible failures. Do not report Connected for an invalid
+   verification result or automatically repeat a paid scrape.
+7. To rotate, create another team key if supported or use the dashboard's key
+   rotation facility; update the secret binding and verify the replacement
+   before removing the old key. Revocation can affect other apps sharing that
+   key. Local disconnect only removes this application's connection state.
+   OAuth consent, redirect URLs, refresh tokens and client IDs do not apply.
+
+## Automation and application credentials
+
+Classification: **console-assisted own-key setup; API provisioning for approved
+partners**. Additional public documentation checked on 9 September 2026:
+[Partner Integration API](https://docs.firecrawl.dev/partner-integration).
+Firecrawl must approve the platform and supply a distinct server-only partner
+key. After the user accepts Firecrawl's terms, an authorized backend can call
+`POST https://integrations.firecrawl.dev/partner/v1/accounts` with their email.
+It returns `apiKey` and `alreadyExisted`; an existing partner team is reused.
+Store the returned key privately, never in chat, source or browser config.
+The same partner API documents key validation and destructive key rotation.
+None of these partner operations is implemented or exercised by this fragment.
+
+An AI can prepare the JSON/environment reference, validate it, compose the
+library calls and check the key through the documented credit endpoint after
+an operator supplies it. Account/team selection, billing and key issuance are
+operator steps for own-key setup. Online can implement partner provisioning
+after approval; a standard API key cannot substitute for the partner key.
+
+The application owner supplies its Firecrawl key through private Env. Keys for
+one team use its shared credits; creating two keys does not split that balance.
+The application owner arranges the required subscription and usage limits.
+This adapter does not sell credits or provision a subscription.
+
+OAuth callback: **not applicable** to these API-key modes. Normal server API
+requests do not use the customer's browser origin. A custom web domain does
+not change the team/key binding; VPS changes must preserve the authorized
+application identity. Follow the [Online setup contract](../../connectors-core/docs/online-setup.md)
+for application-owned readiness and failure states. This fragment does not configure
+crawl/job webhooks; those would require their own verified receiving endpoint.
+
+## CLI and other frameworks
+
+Use the shared API-key runtime pattern with `firecrawlProvider`, the same
+`integrations.json` and private `FIRECRAWL_API_KEY`; Vibe64 is not required.
+After the application has connected and authorized the caller:
+
+```js
+const job = await connections.invoke({ context, integrationId: "firecrawl",
+  operation: "crawls.start", input: { url: "https://example.com", limit: 20 } });
+// Persist job.id with its owner; a later application request checks progress.
+const page = await connections.invoke({ context, integrationId: "firecrawl",
+  operation: "crawls.get", input: { id: job.id } });
+// Persist page.data; if page.next exists, request it with the same job.id.
+```
+
+Other frameworks use their native HTTP client with the same private bearer key
+and [Search](https://docs.firecrawl.dev/api-reference/endpoint/search),
+[Map](https://docs.firecrawl.dev/api-reference/endpoint/map),
+[Scrape](https://docs.firecrawl.dev/api-reference/endpoint/scrape),
+[Crawl](https://docs.firecrawl.dev/api-reference/endpoint/crawl-post),
+[results](https://docs.firecrawl.dev/api-reference/endpoint/crawl-get),
+[errors](https://docs.firecrawl.dev/api-reference/endpoint/crawl-get-errors) and
+[cancel](https://docs.firecrawl.dev/api-reference/endpoint/crawl-delete) endpoints.
+No JSKIT or Vibe64 execution service is required.
+
+**LIMITATIONS:** no managed Firecrawl account/credits provisioning, browser
+sessions, monitor service or editor coding-assistant attachment. For example,
+your app can import twenty documentation pages and display their Markdown;
+automatically refreshing that import every night requires its own scheduler.
+Selecting this connector does not give the editor assistant those documents.
+Own-key setup deliberately requires a Firecrawl account and available credits.

package/docs/fireflies.md

@@ -0,0 +1,95 @@
+# Fireflies
+
+Import `firefliesProvider` from `@jskit-ai/connectors-catalog/server/fireflies`.
+The provider reads the key owner profile, meeting lists, transcript content and summaries, and searches titles/spoken words.
+
+## Configure access
+
+1. Sign into the intended Fireflies account and open **Integrations**, then
+   **Fireflies API**.
+2. Copy the displayed API key into backend Env as `FIREFLIES_API_KEY`. The key
+   follows the user's access and team permissions; admin access may include
+   team data. [Authorization](https://docs.fireflies.ai/fundamentals/authorization).
+3. Save provider `fireflies`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication
+   `{ "method": "api-key", "secretRef": "env:FIREFLIES_API_KEY" }`.
+4. In Vibe64, enter `env:FIREFLIES_API_KEY` as **API key reference**, click
+   **Save configuration**, then **Set credential in Env**. Store the real key
+   as `FIREFLIES_API_KEY` and return to connect. CLI applications invoke
+   `connectApiKey` to verify the profile. Token replacement belongs in Env.
+   Disconnect clears local state; it does not revoke the provider key.
+
+## Runtime and AI composition
+
+All operations POST fixed GraphQL queries to
+`https://api.fireflies.ai/graphql` using Bearer authorization.
+`profile.read` requests `user { user_id name email }` without an ID, so the
+provider returns the key owner's profile.
+[User query](https://docs.fireflies.ai/graphql-api/query/user).
+
+`transcripts.list` requests only `id` and `title`. Inputs are `limit` (1–50,
+default 25), `skip` (nonnegative GraphQL integer, default 0) and `mine`
+(default true). `mine` restricts results to meetings organized by the key owner;
+it does not mean every meeting they attended. Explicit false requests the
+broader set the account is authorized to see. Advance `skip` for another page.
+No transcript audio, recording request or meeting-join mutation is performed.
+[Transcript query](https://docs.fireflies.ai/graphql-api/query/transcripts).
+
+The runtime rejects GraphQL errors even with HTTP 200 and partial data. Queries
+are fixed source; application inputs are variables. Compose the
+[API-key pattern](../patterns/api-key-connection/PATTERN.md) with the private
+JSON store. The application must authorize who may use this shared account.
+
+## Automation and application ownership
+
+An AI can prepare the configuration and query wiring once the owner supplies a
+key. The established bootstrap is the Integrations screen; no API for issuing
+the initial user key was verified. Account and team membership remain provider
+administration tasks.
+
+This credential represents a particular user, not a universal registration for
+every app visitor. The application owner supplies that user's authorized key
+and checks account/team capacity. Two labels do not create independent provider
+budgets. Per-user OAuth remains additional work.
+
+Tests verify query variables, default meeting ownership, integer limits,
+partial errors, HTTP failures, credential rotation, private persistence and
+application isolation. They do not access real meetings.
+
+Setup rechecked against the official authorization and quickstart guides on
+12 September 2026. The captured Lovable form was an empty shell; exact input
+parity remains unproven. No signed-in Fireflies console was inspected.
+
+## Transcript content and search
+
+`transcripts.get({id})` returns sentence text, speaker attribution, timestamps,
+participants, title/date/duration, calendar/meeting links and summary keywords,
+action items, outline and overview. Missing/inaccessible transcripts fail;
+null sentences or summaries remain unavailable content, not a completed
+summary. Fireflies processing and plan permissions determine availability.
+
+`transcripts.search({keyword, scope, limit, skip, mine})` searches `all` by
+default, or `title`/`sentences`. Keyword length is 1–255. Pagination and `mine`
+use the same limits as listing. Retrieve selected IDs with `transcripts.get`.
+The app must restrict which callers can read team meetings even with a valid
+shared key. Do not render returned Markdown as untrusted raw HTML.
+
+CLI apps use the same file and private Env with the API-key pattern. Other
+frameworks use their native HTTP client to POST the fixed query/variables to
+Fireflies; JSKIT and Vibe64 are optional. The app owns its digest schedules,
+cache, task tracking and CRM writes through their respective APIs.
+
+**LIMITATIONS:** editor assistant attachment remains deferred. Example: a
+published app can show a sales call's action items; the Vibe64 coding assistant
+does not gain meeting access from this configuration. Recording, transcript
+mutation, incoming webhooks and per-user OAuth are not supplied (the Lovable
+reference also describes these as excluded). Exact signed-in screen placement
+was not captured; current official instructions establish API-key setup.
+
+Rechecked 13 September 2026 against [transcript detail](https://docs.fireflies.ai/graphql-api/query/transcript),
+[search](https://docs.fireflies.ai/graphql-api/query/transcripts),
+[authorization](https://docs.fireflies.ai/fundamentals/authorization) and
+[Lovable's current fields/capabilities](https://docs.lovable.dev/integrations/fireflies).
+The latter resolves the empty original form: display name and an API key are
+required inputs for its shared connection. Vibe64 stores a private Env reference
+instead of putting the key in the source file. No live meetings were read.

package/docs/fireworks-ai.md

@@ -0,0 +1,53 @@
+# Fireworks AI
+
+Import `fireworksAiProvider` from
+`@jskit-ai/connectors-catalog/server/fireworks-ai`.
+The initial operation lists accessible accounts using a Fireworks API key.
+
+## Configure access
+
+1. Sign into the intended Fireworks account and open [API Keys](https://app.fireworks.ai/settings/users/api-keys).
+   Choose **Create API key** and copy the generated value. The official
+   [quickstart](https://docs.fireworks.ai/getting-started/quickstart) links to this
+   page. Follow any required prompts on that page before copying the issued key.
+   These steps follow the official guide; they have not been tested with a live
+   account. The API's optional expiry field below does not establish a console control.
+2. Store it in backend Env as `FIREWORKS_API_KEY`. The owning user or service
+   account must be allowed to list accounts; an inference-only role may lack
+   that access. This fragment deliberately verifies a management read and does
+   not submit an inference request as a connection test.
+3. Save provider `fireworks-ai`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication `{ "method": "api-key", "secretRef": "env:FIREWORKS_API_KEY" }`.
+   Calls use Bearer authentication and JSON content type at
+   `https://api.fireworks.ai`. [API authentication](https://docs.fireworks.ai/api-reference/introduction).
+4. Call `connectApiKey`. On rotation, replace the Env value. Local disconnect
+   removes connection state; delete the obsolete key in Fireworks to revoke it.
+
+## Runtime and AI composition
+
+`accounts.list` reads `GET /v1/accounts`. It accepts `pageSize` (1–200, default
+50), `pageToken`, and an optional provider filter expression. Results preserve
+`accounts`, `nextPageToken` and `totalSize`. Pass the next token as `pageToken`
+while keeping the filter unchanged. The query uses the documented HTTP field
+names, not the snake_case names sometimes used in SDK descriptions.
+[Account listing](https://docs.fireworks.ai/api-reference/list-accounts).
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) and encrypted
+file store. An AI can use the returned account names for subsequent app-owned
+deployment or billing workflows. Inference, streaming and deployment creation
+are not operations in this fragment. Automated tests simulate provider reads,
+paging, failures, key rotation and persistence across a new service instance.
+
+## Automation and application ownership
+
+After initial authorized access, key creation can be automated with
+`POST /v1/accounts/{account_id}/users/{user_id}/apiKeys`. Its JSON body contains
+`apiKey`, with `displayName` and optional `expireTime`; save the returned `key`
+directly into secret storage. Fireworks also documents `firectl api-key create`.
+These require an existing authorized identity and do not bypass account setup.
+[Key creation API](https://docs.fireworks.ai/api-reference/create-api-key).
+
+The application owner supplies the account and keys, and sets capacity/billing
+controls with Fireworks. Two key names in one account do not establish independent
+quotas. AI can prepare configuration and provision permitted keys after bootstrap;
+the editor does not supply or allocate inference capacity. This fragment makes no live requests during its tests.