@jskit-ai/agent-docs 0.1.154 → 0.1.156

package/skills/jskit/references/patterns/connectors/aws-storage-queries/example/integrations.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "files": {
+      "provider": "aws-s3",
+      "displayName": "Application files",
+      "accountMode": "shared",
+      "scopes": [
+        "read"
+      ],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:AWS_SECRET_ACCESS_KEY"
+      },
+      "settings": {
+        "region": "ap-southeast-2",
+        "bucket": "my-app-files",
+        "accessKeyIdRef": "env:AWS_ACCESS_KEY_ID"
+      }
+    },
+    "queries": {
+      "provider": "aws-athena",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:AWS_SECRET_ACCESS_KEY"
+      },
+      "settings": {
+        "region": "ap-southeast-2",
+        "accessKeyIdRef": "env:AWS_ACCESS_KEY_ID",
+        "workgroup": "reports",
+        "resultLocation": "s3://query-results/reports/"
+      }
+    }
+  }
+}

package/skills/jskit/references/patterns/connectors/aws-storage-queries/example/s3-transfer.js

@@ -0,0 +1,34 @@
+// Application-owned composition: service.authorize must approve this exact key
+// for context. The same function works in a Node CLI or application backend.
+// Pass a bounded signal for both signing and the complete response-body read.
+export async function transferS3Object({ service, context, integrationId, key,
+  direction, body, signal, fetchImpl = globalThis.fetch }) {
+  if (!["download", "upload"].includes(direction)) throw new TypeError("Choose download or upload.");
+  if (!signal) throw new TypeError("Supply a transfer cancellation/timeout signal.");
+  if (direction === "upload" && !(body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body))) {
+    throw new TypeError("Supply a Blob, ArrayBuffer or typed-array upload body.");
+  }
+  signal.throwIfAborted();
+  const signed = await service.invoke({ context, integrationId, signal,
+    operation: direction === "upload" ? "objects.uploadUrl" : "objects.downloadUrl",
+    input: { key } });
+  let response;
+  try {
+    response = await fetchImpl(signed.url, { method: signed.method,
+      ...(direction === "upload" ? { body } : {}), signal,
+      credentials: "omit", redirect: "error" });
+  } catch {
+    // Do not expose the URL through a network error/cause or retry a PUT whose
+    // outcome is unknown. The app decides whether to inspect and retry later.
+    throw new Error(direction === "upload"
+      ? "Upload interrupted; completion is unknown. Check the object before retrying."
+      : "Download interrupted. Request a fresh download when ready.");
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw new Error(`S3 ${direction} failed (HTTP ${response.status}). Check permissions and URL expiry.`);
+  }
+  // Keep binary downloads as a stream; the caller must await its consumption
+  // before announcing completion. Upload success means S3 acknowledged the PUT.
+  return response;
+}

package/skills/jskit/references/patterns/connectors/calendar-cli/PATTERN.md

@@ -0,0 +1,106 @@
+---
+id: connectors/calendar-cli
+title: Google Calendar from an application-owned CLI
+summary: Compose reusable connection libraries with portable configuration, application ownership and durable storage.
+keywords: connectors, integrations, google, calendar, oauth, cli, permissions
+requires: @jskit-ai/connectors-core, @jskit-ai/connector-google-calendar, @jskit-ai/database-runtime-mysql
+---
+
+# Google Calendar from an application-owned CLI
+
+## Use when
+
+Use this pattern for a local operator command that connects an account and reads
+Calendar pages. The example deliberately selects MySQL/MariaDB. A web app should
+use its existing selected database client and authenticated callback routes.
+
+## Do not use when
+
+Do not use the local operator identity or loopback listener as a public web
+application's authentication. Do not use this example for managed gateway
+registrations, native public OAuth clients or service accounts.
+
+## Product decisions
+
+Adapt the example's `integrations.json`, environment bindings, command names,
+ownership policy and output handling. Install its dependencies with ordinary
+`npm install`; no JSKIT CLI, generator or template installation is involved.
+The example's loopback HTTP callback is local command wiring. OAuth exchange,
+PKCE, state checks, refresh, provider requests, encryption and storage remain
+imports from the libraries.
+
+The example trusts the local process owner. `CONNECTOR_APPLICATION_ID` and
+`CONNECTOR_SUBJECT_ID` identify its persistent connection. Do not copy that
+environment-based identity policy into an HTTP API: derive its owner from the
+authenticated user and check membership/operation permissions there.
+
+## Invariants
+
+- One configuration file is read by CLI and UI.
+- Credential values and connection grants stay outside source.
+- The application authorizes owners and executes package-owned migrations.
+- OAuth and persistence machinery is imported from the library.
+- Provider consent and a successful account check precede Connected.
+
+## Framework APIs
+
+The script imports `parseIntegrationConfiguration`, `createConnectionService`,
+`createEnvironmentReferenceResolver`, `createCredentialProtection`,
+`createKnexConnectionStore` and `googleCalendarProvider`. `knexfile.js` uses
+`createKnexMigrationConfigFromApp` with the selected MySQL dialect.
+
+## Example files
+
+`example/integrations.json` is portable source. `example/.env.example` lists
+private runtime bindings. `example/scripts/calendar.js` owns command parsing
+and local callback wiring. `example/package.json` and `example/knexfile.js`
+provide ordinary npm and migration operations.
+
+## Verification
+
+1. Follow the package's provider setup guide. Register the exact loopback URL
+   from `.env.example` on your own Google OAuth web client.
+2. Adapt `example/package.json`, `knexfile.js`, `integrations.json` and
+   `scripts/calendar.js` into your application. Make `.env` from `.env.example`,
+   supply database and provider credentials, and exclude it from Git. Create
+   the application's migration directories with `mkdir -p migrations/constraints`.
+3. Generate a private storage key with
+   `node -e 'console.log(require("node:crypto").randomBytes(32).toString("base64"))'`.
+   Save it as `CONNECTOR_STORAGE_KEY`. Preserve it across restarts and backups.
+4. Run `npm install`, then `npm run db:migrate` against your application's
+   database. Package migrations are discovered directly; do not copy them.
+5. Run `npm run calendar -- validate`. This needs no database or provider
+   credentials and uses exactly the validator used by the UI.
+6. Run `npm run calendar -- connect`, open the displayed URL in your normal
+   browser and approve the account permissions. A local callback completes the
+   command. Ctrl-C cancels the pending attempt.
+7. Run `npm run calendar -- calendars`, then
+   `npm run calendar -- events '{"calendarId":"primary","maxResults":10}'`.
+   The output includes the provider's next-page token when present.
+8. Restart the process and run `npm run calendar -- status`. Run
+   `npm run calendar -- disconnect` to remove this application's local grant.
+
+For command output, apply your application's privacy requirements before
+retaining or sharing calendar data. The example prints operation results, not
+credentials.
+
+## Variation points
+
+Use `createConnectorsFeature()` with the ordinary JSKIT action runtime, or call
+`createConnectionService()` from an existing Feature. Keep business operations
+named, such as `calendar.events.list`. Use the app's authenticated context in
+the authorization policy. A web callback recovers the initiating owner's
+context and passes the full registered callback URL to `completeAuthorization`.
+
+Use `IntegrationConfigurationFields` from `@jskit-ai/connectors-web/client` for
+the form. The parent uses the normal resource/add-edit seam to save the same
+file, detect concurrent edits and expose the existing secret-entry control.
+Saving configuration and connecting an account are different operations.
+
+## Avoid
+
+The source pattern is validated locally; live Google consent still requires
+your credentials and account approval. The initial runtime implements own web
+client registrations. The editor configures the generated application's own registration. Its backend
+resolves the secret from the application environment; never ship a client secret
+inside a desktop binary or browser bundle.

package/skills/jskit/references/patterns/connectors/calendar-cli/example/.env.example

@@ -0,0 +1,6 @@
+DATABASE_URL=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_CALLBACK_URL=http://127.0.0.1:8080/integrations/google/callback
+CONNECTOR_STORAGE_KEY=
+CONNECTOR_APPLICATION_ID=calendar-example-development
+CONNECTOR_SUBJECT_ID=local-operator

package/skills/jskit/references/patterns/connectors/calendar-cli/example/integrations.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "integrations": {
+    "calendar": {
+      "provider": "google-calendar",
+      "displayName": "My calendar",
+      "accountMode": "per-user",
+      "scopes": [
+        "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+        "https://www.googleapis.com/auth/calendar.events.readonly"
+      ],
+      "authentication": { "method": "oauth2", "registrationRef": "google" }
+    }
+  },
+  "registrations": {
+    "google": {
+      "source": "own",
+      "clientId": "YOUR_GOOGLE_CLIENT_ID",
+      "clientSecretRef": "env:GOOGLE_CLIENT_SECRET",
+      "callbackUrlRef": "env:GOOGLE_CALLBACK_URL"
+    }
+  }
+}

package/skills/jskit/references/patterns/connectors/calendar-cli/example/knexfile.js

@@ -0,0 +1,5 @@
+import { existsSync } from "node:fs";
+import { createKnexMigrationConfigFromApp } from "@jskit-ai/database-runtime/server/knexMigrationConfig";
+
+if (existsSync(".env")) process.loadEnvFile(".env");
+export default await createKnexMigrationConfigFromApp({ client: "mysql2" });

package/skills/jskit/references/patterns/connectors/calendar-cli/example/package.json

@@ -0,0 +1,16 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "calendar": "node --env-file-if-exists=.env scripts/calendar.js",
+    "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+  },
+  "dependencies": {
+    "@jskit-ai/connectors-core": "0.1.1",
+    "@jskit-ai/connector-google-calendar": "0.1.1",
+    "@jskit-ai/database-runtime": "0.1.184",
+    "@jskit-ai/database-runtime-mysql": "0.1.182",
+    "knex": "^3.1.0"
+  }
+}

package/skills/jskit/references/patterns/connectors/calendar-cli/example/scripts/calendar.js

@@ -0,0 +1,102 @@
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { once } from "node:events";
+import createKnex from "knex";
+import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
+import { createConnectionService, createEnvironmentReferenceResolver } from "@jskit-ai/connectors-core/server";
+import { createCredentialProtection, createKnexConnectionStore } from "@jskit-ai/connectors-core/server/storage";
+import { googleCalendarProvider } from "@jskit-ai/connector-google-calendar/server";
+
+// A local operator command owns this HTTP listener; web apps use authenticated routes.
+async function connectInBrowser(service, context) {
+  const callback = new URL(process.env.GOOGLE_CALLBACK_URL);
+  if (callback.protocol !== "http:" || callback.hostname !== "127.0.0.1" || !callback.port) {
+    throw new Error("This CLI requires a registered http://127.0.0.1:PORT callback.");
+  }
+  let state;
+  let finish;
+  let fail;
+  let completed = false;
+  const controller = new AbortController();
+  const finished = new Promise((resolve, reject) => { finish = resolve; fail = reject; });
+  const outcome = finished.then((result) => ({ result }), (error) => ({ error }));
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, callback.origin);
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("Cache-Control", "no-store");
+    if (request.method !== "GET" || url.pathname !== callback.pathname || !state || url.searchParams.get("state") !== state) {
+      response.writeHead(400).end("This is not the pending authorization callback.");
+      return;
+    }
+    try {
+      const result = await service.completeAuthorization({ context, integrationId: "calendar", callbackUrl: url.href, signal: controller.signal });
+      completed = true;
+      response.end("Connected. You can close this window.");
+      finish(result);
+    } catch (error) {
+      response.writeHead(400).end("Connection failed. Return to the terminal.");
+      fail(error);
+    }
+  });
+  server.listen(Number(callback.port), "127.0.0.1");
+  await once(server, "listening");
+  const cancel = () => { controller.abort(); fail(new Error("Authorization cancelled.")); };
+  process.once("SIGINT", cancel);
+  const timeout = setTimeout(cancel, 10 * 60 * 1000);
+  try {
+    const start = await service.beginAuthorization({ context, integrationId: "calendar", signal: controller.signal });
+    state = new URL(start.authorizationUrl).searchParams.get("state");
+    console.log(`Open this URL in your browser:\n${start.authorizationUrl}`);
+    const completed = await outcome;
+    if (completed.error) throw completed.error;
+    return completed.result;
+  } finally {
+    clearTimeout(timeout);
+    process.off("SIGINT", cancel);
+    try {
+      if (state && !completed) await service.cancelAuthorization({ context, integrationId: "calendar", state });
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  }
+}
+
+async function main() {
+  const command = process.argv[2] || "validate";
+  const configuration = parseIntegrationConfiguration(await readFile("integrations.json", "utf8"), { providers: [googleCalendarProvider] });
+  if (command === "validate") {
+    console.log("Integration configuration is valid.");
+    return;
+  }
+  if (!["connect", "status", "calendars", "events", "disconnect"].includes(command)) {
+    throw new Error("Use validate, connect, status, calendars, events or disconnect.");
+  }
+  for (const name of ["DATABASE_URL", "CONNECTOR_STORAGE_KEY", "CONNECTOR_APPLICATION_ID", "CONNECTOR_SUBJECT_ID"]) {
+    if (!process.env[name]) throw new Error(`Set ${name} before using connections.`);
+  }
+  const context = { applicationId: process.env.CONNECTOR_APPLICATION_ID, subjectId: process.env.CONNECTOR_SUBJECT_ID };
+  const protection = createCredentialProtection({ keys: { current: Buffer.from(process.env.CONNECTOR_STORAGE_KEY, "base64") }, activeKeyId: "current" });
+  const knex = createKnex({ client: "mysql2", connection: process.env.DATABASE_URL });
+  try {
+    const service = createConnectionService({
+      configuration, providers: [googleCalendarProvider],
+      store: createKnexConnectionStore({ knex, protection }),
+      resolveReference: createEnvironmentReferenceResolver(process.env),
+      authorize: async () => context
+    });
+    const request = { context, integrationId: "calendar" };
+    let result;
+    if (command === "connect") result = await connectInBrowser(service, context);
+    else if (command === "status") result = await service.status(request);
+    else if (command === "disconnect") result = await service.disconnect(request);
+    else result = await service.invoke({ ...request, operation: command === "events" ? "events.list" : "calendars.list", input: JSON.parse(process.argv[3] || "{}") });
+    console.log(JSON.stringify(result, null, 2));
+  } finally { await knex.destroy(); }
+}
+
+main().catch((error) => {
+  console.error(error.code || "calendar_command_failed");
+  if (error.fieldErrors) console.error(JSON.stringify(error.fieldErrors));
+  else if (!error.code) console.error(error.message);
+  process.exitCode = 1;
+});

package/skills/jskit/references/patterns/connectors/event-delivery/PATTERN.md

@@ -0,0 +1,151 @@
+---
+id: connectors/event-delivery
+title: Authorized Inngest event delivery with portable files
+summary: Compose the shared connector runtime for event delivery while leaving workflow code and event policy with the application.
+keywords: connectors, integrations, inngest, events, workflows, files, cli
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Authorized Inngest event delivery with portable files
+
+## Use when
+
+An existing application or CLI must send an event to Inngest and inspect app
+metadata using separately owned Signing and Event Keys.
+
+## Do not use when
+
+This fragment does not execute or register workflow functions, implement an
+Inngest serve endpoint, configure schedules or provide application-user login.
+Those concerns belong to the app and its chosen Inngest SDK integration.
+
+## Product decisions
+
+Choose the connection owner, allowed event names, payload schema and stable
+business operation ID. Decide which authenticated users may trigger each event.
+Determine how the app will reconcile delivery uncertainty and report workflow
+progress independently of the connector's delivery receipt.
+
+## Invariants
+
+- Configuration and connection state remain text files.
+- Signing and Event Key values remain environment bindings, outside source.
+- Metadata verification never sends an event or verifies the Event Key.
+- Authorization sees the requested event before its Event Key is resolved.
+- An accepted event does not prove a function completed.
+- A cancelled request must not automatically replay a possibly accepted event.
+
+## Framework APIs
+
+Use the `api-key-connection` pattern's existing composition with
+`providers: [inngestProvider]`, imported from
+`@jskit-ai/connectors-catalog/server/inngest`. The JSKIT library owns validated
+requests, credential selection, responses, cancellation and file grants.
+
+## Example files
+
+`example/integrations.json` supplies the shared `workflows` slot. Provision
+`INNGEST_SIGNING_KEY` and `INNGEST_EVENT_KEY` in the backend environment and
+use the existing file-store protection and authenticated connection context.
+
+```js
+async function applicationConnectionPolicy(context, request) {
+  const owner = await workflowAccess.requireConnectionOwner(context, request.integrationId);
+  if (request.operation === "events.send") {
+    await workflowAccess.requireEventPermission(context, request.input);
+  }
+  return owner;
+}
+```
+
+`workflowAccess` is application-owned policy, not a JSKIT API. It must validate
+allowed names and payload ownership against authenticated state. It must also
+authorize connection management and metadata reads. Return a stable trusted
+`applicationId` and `subjectId`; do not trust owner IDs supplied by a browser.
+
+```js
+await connections.connectApiKey({ context, integrationId: "workflows" });
+// In an authorized application action, after validating report ownership:
+const receipt = await connections.invoke({
+  context, integrationId: "workflows", operation: "events.send", signal,
+  input: {
+    name: "app/report.requested",
+    id: `app/report.requested:${reportRequestId}`,
+    data: { reportRequestId }
+  }
+});
+// Record receipt.ids[0] as delivered; track workflow completion separately.
+```
+
+The application supplies `reportRequestId` from its validated business request.
+Inngest's deduplication window is finite; a stable ID is not a permanent
+exactly-once guarantee. Within an Inngest function, use the SDK's documented
+step event-sending primitive so delivery participates in durable execution.
+Do not replace SDK function orchestration with connector calls.
+
+## Variation points
+
+`settings.branchEnvironment` routes event delivery to a branch and does not
+change metadata query selection. `accountMode: "assistant"` requires the host's
+delegated event authority, including any explicit approval. A trusted operator
+CLI uses the same JSON and library without depending on editor storage.
+
+## Verification
+
+The provider's focused tests simulate metadata and event replies and use real
+encrypted file storage. The public-editor test exercises the same reference
+and branch settings. This source pattern does not generate or run a sample app;
+live event delivery and SDK function execution remain separate acceptance work.
+
+## Avoid
+
+Do not expose either key in browser code, send events as a connection probe,
+interpret delivery as completed work, permit arbitrary events through a shared
+public route, or retry after an ambiguous network failure without reconciliation.
+
+## Native functions and cron
+
+App-owned composition, using the native SDK's current `triggers` option
+([functions](https://www.inngest.com/docs/learn/inngest-functions),
+[cron](https://www.inngest.com/docs/guides/scheduled-functions),
+[serve adapters](https://www.inngest.com/docs/learn/serving-inngest-functions);
+reviewed 2026-09-13). Add `inngest` to the consuming application, not to JSKIT's
+connector package. Resolve the JSON slot's Env references before constructing
+its SDK client; standard names below match the example configuration.
+
+```js
+import { Inngest } from "inngest";
+import { fastifyPlugin } from "inngest/fastify";
+
+const workflows = new Inngest({ id: "reports", eventKey: process.env.INNGEST_EVENT_KEY });
+const report = workflows.createFunction(
+  { id: "requested-report", triggers: { event: "app/report.requested" } },
+  async ({ event, step }) => {
+    const id = event.data.reportRequestId;
+    if (typeof id !== "string" || !id) throw new Error("Missing report request ID");
+    return step.run("render-and-store", () => reports.renderRequestedReport(id));
+  }
+);
+const reconcile = workflows.createFunction(
+  { id: "reconcile-reports", triggers: { cron: "TZ=UTC 0 * * * *" } },
+  async ({ step }) => step.run("reconcile-due", () => reports.reconcileDueRequests())
+);
+// `fastify` is the app's existing server. The SDK validates signed requests
+// using INNGEST_SIGNING_KEY from the deployed application's environment.
+await fastify.register(fastifyPlugin, { client: workflows, functions: [report, reconcile] });
+```
+
+`reports` is the application's business service, not a library API. It loads
+persisted, previously authorized requests, enforces tenant boundaries and makes
+writes safe to retry. Do not trust an event's arbitrary user/tenant identifier
+as authorization. `step.run` may retry failed work; a durable step is not a
+substitute for idempotent business writes. Cron timezone is explicit; choose
+schedules with awareness of daylight-saving behavior.
+
+Expose the SDK route through the app's normal server composition, then deploy
+and sync its HTTPS `/api/inngest` URL in the selected Inngest environment.
+Keep the Signing Key private and let the native adapter verify signatures.
+JSKIT CLI users follow the same steps without Vibe64. Other stacks use native
+SDKs where available and the same event name/payload/Env contract; this example
+does not promise an SDK in every language. No function execution, cloud sync
+or generated application is performed by this reference pattern.

package/skills/jskit/references/patterns/connectors/event-delivery/example/integrations.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "workflows": {
+      "provider": "inngest",
+      "displayName": "Report workflows",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:INNGEST_SIGNING_KEY"
+      },
+      "settings": { "eventKeyRef": "env:INNGEST_EVENT_KEY" }
+    }
+  }
+}

package/skills/jskit/references/patterns/connectors/firebase-messaging/PATTERN.md

@@ -0,0 +1,156 @@
+---
+id: connectors/firebase-messaging
+title: Firebase messaging from a CLI or application backend
+summary: Wire service-account grants, file storage, explicit message actions and public browser settings without generating an application.
+keywords: connectors, integrations, firebase, fcm, service-account, jwt, notifications, push, vapid, cli, files
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Firebase messaging from a CLI or application backend
+
+## Use when
+
+Use this pattern for an application's Firebase sender. The provider package
+implements the service-account protocol and messaging operations; the core
+implements token persistence, renewal and ownership. The application supplies
+its existing authenticated identity, authorization, runtime directory and Env
+bindings. The CLI uses these same libraries. Do not copy their token manager
+or introduce an editor database.
+
+Read the packaged `docs/firebase-cloud-messaging.md` before provisioning. No
+OAuth callback exists for this credential mode. The application owner supplies
+the Firebase project and service account through its own Env bindings.
+
+## Do not use when
+
+Use another provider contract for Firebase Authentication, Firestore or Cloud
+Storage. This fragment does not provide those services or managed provisioning.
+
+## Product decisions
+
+Choose the target project, who may send which notifications, and whether the
+application needs browser enrollment or only existing targets. Decide where
+recipient/device associations belong in the application's existing storage.
+
+## Invariants
+
+Private service-account JSON remains on the server. Configuration stores its
+reference, stable project identity and public settings. Verify before reporting
+Connected; authorize every audience before sending. Preserve the existing file
+store and token lock instead of copying the grant implementation.
+
+## Framework APIs
+
+Use `parseIntegrationConfiguration`, `createConnectionService`,
+`createEnvironmentReferenceResolver`, `createFileConnectionStore`,
+`createCredentialProtection` and `firebaseCloudMessagingProvider` as shown below.
+The public helper is `firebaseCloudMessagingWebConfiguration`; the standard
+Feature action is `connectors.verifyServiceAccount`.
+
+## Example files
+
+The example module and inline fragments adapt to the application's existing
+source files. They are source guidance, not a generated application or template
+installation.
+
+Adapt this source fragment to the application's existing startup owner:
+
+[server/notifications.js](example/server/notifications.js) exports
+`openNotificationConnections({ configurationPath, runtimeDirectory, credentialKey, environment, authorizeConnectionOperation })`.
+It composes the existing libraries and returns the ordinary connection service.
+
+`credentialKey` is a private 32-byte `Uint8Array`, loaded from the application's
+secret owner, not a literal in generated source. `runtimeDirectory` is an
+absolute private path outside the repository. `environment` contains the
+service-account JSON string referenced by `integrations.json`; a path to that
+JSON file is not the credential value. An application with its own secret store
+can supply an equivalent `resolveReference` implementation.
+
+`authorizeConnectionOperation(context, request)` must obtain the real owner
+from trusted identity and return `{ applicationId, subjectId }` only after
+checking access. Shared senders use an authorized shared subject. Every
+`messages.send` requires checking `request.input.message` against the allowed
+recipient and content. A signed-in user or assistant must not gain arbitrary
+topic broadcasts merely by accessing this integration. Keep public and paid
+project assignments in host policy.
+
+## Explicit actions
+
+From the existing CLI command or server action, verify the configured sender:
+
+```js
+await connections.connectServiceAccount({
+  context: trustedContext, integrationId: "push", signal
+});
+```
+
+This checks a fixed topic with `validate_only: true`. It does not send a test
+notification. For an actual application message, build a bounded typed payload
+and authorize it before invoking the send operation:
+
+```js
+const message = {
+  fid: recipientInstallationId,
+  notification: { title: "Order ready", body: "Your order is ready." },
+  data: { orderId: String(order.id) }
+};
+await connections.invoke({ context: trustedContext, integrationId: "push",
+  operation: "messages.validate", input: { message }, signal });
+// Use the application's explicit send action and its authorization policy.
+await connections.invoke({ context: trustedContext, integrationId: "push",
+  operation: "messages.send", input: { message }, signal });
+```
+
+Validation does not authorize the later send and is not a delivery guarantee.
+Use exactly one target: `fid`, existing `token`, `topic` or `condition`. Prefer
+installation IDs when using the current Firebase SDK. Keep the installed SDK's
+enrollment contract consistent; do not mix registration-token and installation
+APIs. No automatic retry should wrap an ambiguous timed-out send. If the product
+needs retry scheduling, implement that behavior in its existing delivery owner.
+
+The standard JSKIT Feature is also available through
+`createConnectorsFeature(options)` and `connectors.verifyServiceAccount`.
+Product message operations belong in application actions that call `invoke`;
+never expose an arbitrary authenticated URL or unconstrained provider operation.
+
+## Variation points
+
+### Browser composition
+
+For a configuration with `clientMode: "web"`, use the pure library projection:
+
+```js
+import { firebaseCloudMessagingWebConfiguration } from "@jskit-ai/connectors-catalog/client/firebase-cloud-messaging";
+const { firebaseConfig, vapidKey } = firebaseCloudMessagingWebConfiguration(publicPushSettings);
+```
+
+Supply `firebaseConfig` to the application's Firebase initialization and
+`vapidKey` to its SDK registration call. Current documentation uses
+`register(messaging, { vapidKey })` and `onRegistered(messaging, callback)`;
+verify those exports against the version actually installed before wiring them.
+The callback passes the installation ID to an authenticated app endpoint that
+associates it with the correct user/device. Serve the service worker at the
+app's origin and request notification permission through an explicit UI action.
+The public configuration contains no private service-account data.
+
+On a custom-domain change, register the browser on the new origin and replace
+its installation association through the same authorized endpoint. Keep the
+stable application identity and project assignment. The server token exchange
+does not acquire a new OAuth callback just because an app uses another domain.
+
+## Verification
+
+Use a generated test key and an injected `fetchImpl` fixture. Verify JWT issuer,
+audience, expiry, scope and signature; inspect `validate_only` and payload
+targets; cover missing permissions, malformed receipts and cancellation. Use
+the actual file store to test restart and rotation. Form tests must check
+server/web mode changes, reference rejection, public values and file reload.
+These checks do not prove live delivery or browser subscription. Do not create
+a real project, key, subscription or notification as an incidental test.
+
+## Avoid
+
+Do not expose service-account JSON to the browser, confuse Firebase API keys
+with private service credentials, or choose the paid project from caller input.
+Do not treat an accepted message receipt as device delivery or automatically
+retry a send whose outcome is unknown.