@jskit-ai/connectors-catalog 0.1.1

package/docs/google-analytics.md

@@ -0,0 +1,202 @@
+# Google Analytics
+
+## Delivery target and current implementation
+
+This connector configures website tracking with an application-owned GA4
+Measurement ID. The definition and editor now accept the public setting without a connection
+command. Controlled shared-form, dashboard and chat checks pass. Generated-application
+wiring and live traffic are not exercised.
+Saving this configuration is not evidence that tracking is installed.
+
+## Get the application's Measurement ID
+
+1. Open [Google Analytics](https://analytics.google.com/) and select the
+   application's Analytics property. Create a property and a Web data stream if
+   the application does not have one yet.
+2. Open **Admin → Data collection and modification → Data streams** and select
+   that web stream. Use the application's published website address when setting
+   up the stream.
+3. Copy the **Measurement ID** from **Stream details**. For this GA4 website
+   configuration, use the stream's `G-` identifier.
+4. Save that public identifier in the integration's Measurement ID field. It is
+   intended to appear in the published website; it is not an API key or proof
+   that the editor owns the Analytics property.
+5. Have the application's framework install the Google tag using that setting.
+   Check the application's existing tag manager first to avoid installing it
+   twice. The application controls when tracking loads and its consent behavior.
+
+Google's [ID instructions](https://support.google.com/analytics/answer/9539598?hl=en)
+and [tag installation instructions](https://support.google.com/analytics/answer/15756615?hl=en-GB)
+are the provider references. This flow does not require a Google OAuth client,
+client secret, callback URL, or Vibe64-owned Google registration.
+
+## Configuration and ownership contract to implement
+
+The intended `integrations.json` slot is:
+
+```json
+{
+  "schemaVersion": 1,
+  "integrations": {
+    "website-analytics": {
+      "provider": "google-analytics",
+      "displayName": "Website analytics",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "none" },
+      "settings": { "measurementId": "G-XXXXXXXXXX" }
+    }
+  },
+  "registrations": {}
+}
+```
+
+The shared field component and CLI validator use this same format. The public ID can live directly in the text configuration; a
+framework can expose it through its normal public build configuration. No
+secret-resolution service is needed.
+
+Vibe64 Public owns the editor experience. Online uses that same experience and
+the selected project's configuration. Saving must report **Configured**, with
+an explanation that application wiring and event delivery are separate. It must
+not start OAuth, call a connection-status command, send a test tracking event,
+or show an account as verified. Changing or removing the setting is an ordinary
+configuration change; it does not revoke a Google account.
+
+JSKIT owns the JavaScript definition, validation, shared form and usage guidance.
+The generated application owns loading the tag, navigation/page-view handling,
+consent behavior, and the lifecycle of its deployed configuration. Laravel uses
+its own layout, asset and configuration tools; it does not need JSKIT at runtime.
+An assistant can wire either framework from the saved public setting. Creating
+or selecting the actual Analytics property requires the owner's access; saving
+this ID does not authorize Admin API calls to do that automatically.
+
+## Framework handoff
+
+The assistant should inspect the application's selected framework and existing
+tracking before editing code. It receives the slot name, not a copied credential.
+Use these steps for the saved `website-analytics` example:
+
+1. Read and validate the application's own `integrations.json` during its normal
+   configuration loading or build. Select
+   `integrations["website-analytics"].settings.measurementId`. A missing slot
+   means tracking is disabled; do not silently substitute another property's ID.
+2. Expose only this public ID to the frontend. Never serialize the whole
+   integrations file or registrations into HTML or a browser bundle.
+3. Wire the ID into the existing Google tag or tag-manager installation. If none
+   exists, use Google's documented tag installation through the framework's
+   normal document/layout entry point. Preserve consent controls and avoid a
+   second installation or duplicate navigation events.
+4. Treat removal as disabling this application's tag configuration on the next
+   application reload/build/deployment, according to its normal configuration
+   lifecycle. It does not delete the Analytics property or historical data.
+   An already-loaded page may need reloading; removing a file entry does not
+   reach into running browsers and undo previously sent events.
+5. Keep controlled tests local: mock the tag boundary and verify the selected ID,
+   consent gating, missing-slot behavior, and no duplicate initialization. Do not
+   send real Analytics events merely to prove that configuration saves.
+
+For Node/JSKIT, import `googleAnalyticsDefinition` from
+`@jskit-ai/connectors-catalog/shared` and validate using
+`validateIntegrationConfiguration` from
+`@jskit-ai/connectors-core/shared/configuration`, registering that definition.
+The framework still owns document rendering, public configuration and navigation.
+No connection service or token store is required for this provider.
+
+For Laravel, read the same project-owned JSON through the application's normal
+configuration/bootstrap code and expose the selected public ID to its Blade or
+frontend entry point. If configuration is cached or assets are built, incorporate
+changes through that existing lifecycle. Use Laravel-native validation and
+rendering; do not install JSKIT or a JavaScript connection daemon just to read
+this setting. Escape any value rendered into HTML or JavaScript with the
+framework's normal safe serialization.
+
+These are implementation instructions. They do not claim that a generated
+application, consent implementation or live Analytics delivery has been tested.
+
+## Delivery checklist
+
+- [x] Replace the unpublished OAuth definition with the public Measurement ID
+  field and no-credential, shared configuration.
+- [x] Make the editor distinguish configured settings from verified accounts,
+  including its automatic status checks and assistant setup request.
+- [x] Remove the mismatched Admin reader and its direct package references,
+  tests and provider instructions without a compatibility alias.
+- [x] Verify UI/CLI round-trip, invalid input, persistence and removal using
+  controlled fixtures. Prove configuration does not initiate provider requests.
+- [x] Provide the framework setup instructions without claiming a generated
+  application or live Analytics traffic has been tested.
+
+For this pre-release migration, existing Admin-reader users must explicitly
+remove or replace that integration. An OAuth registration cannot be converted to
+a Measurement ID. Remove its Env secrets only after checking no other slot uses
+them; revoke any old grant through the existing application before removing its
+runtime. Framework-native Admin API use remains a separate application concern.
+
+
+## Optional JavaScript browser helper
+
+Import `createGoogleAnalytics` from
+`@jskit-ai/connectors-catalog/client/google-analytics` after browser hydration.
+It owns one Measurement ID per page and loads the Google tag only after explicit
+consent. Reusing the same instance/ID does not insert another script or config.
+If the app already has a Google tag or Tag Manager, use that existing owner;
+the helper refuses a competing installation. It does not build a consent banner.
+
+```js
+import { createGoogleAnalytics } from '@jskit-ai/connectors-catalog/client/google-analytics';
+// Expose just this public field from the selected validated integration slot.
+const analytics = createGoogleAnalytics({ measurementId: publicSettings.measurementId });
+function consentChanged(allowed) {
+  analytics.setConsent(allowed);
+  if (allowed) analytics.pageView({ location: location.origin + location.pathname, title: document.title });
+}
+// Call from your framework's completed navigation hook, using redacted URLs.
+function routeChanged(publicUrl, title) {
+  analytics.pageView({ location: publicUrl, title });
+}
+// Call once when the app has confirmed the business event, not on every render.
+function bookingCompleted() { analytics.event('generate_lead'); }
+// On app teardown/removal: unsubscribe the app's route/consent hooks, then:
+// analytics.dispose();
+```
+
+Before consent, no tag loads and events return false. Consent withdrawal sets
+Google's per-property disable flag and stops this helper's events; it does not
+delete existing cookies or erase events already sent. The app's consent manager
+owns that policy. This is basic consent-gated loading, not an implementation of
+advanced Consent Mode or advertising consent. Script blockers/network/CSP can
+prevent delivery even after enabling; no Connected/verified claim is made.
+
+For manual SPA page views, open the GA4 web stream's Enhanced measurement
+settings, Page views, Show advanced settings, and disable **Page changes based
+on browser history events**. The helper already sends `send_page_view: false`;
+that alone does not disable Enhanced Measurement's independent history listener.
+Use exactly one navigation hook. Repeated consecutive views of the same URL are
+suppressed; navigating away and back produces another view.
+
+For a conversion, emit a suitable recommended event such as `generate_lead` or
+`purchase` only when the app confirms that action. In Analytics **Admin → Data
+display → Events**, mark the event as a key event (create the named event there
+if it has not arrived yet). Google Ads conversion import is separate. The helper
+does not enforce paid entitlements, deduplicate business transactions or confirm
+that Google received an event. Do not include emails, message text, sensitive
+query parameters or other personal data in events or page URLs.
+
+Disposal disables this ID and removes the inserted script element. Loaded
+Google code cannot be unloaded and prior events cannot be recalled. Reload the
+page to change properties or reinitialize after disposal. Removing the JSON slot
+must also remove its wiring on the app's next configuration/build/deploy cycle.
+A missing slot must not instantiate a tracker.
+
+Other frameworks use their existing tag/Tag Manager support and native consent
+and route hooks with the same public ID. They do not need the JavaScript helper
+or a Node daemon. The app/framework remains the tracking owner; Vibe64 only edits
+configuration and supplies guidance. See Google's
+[manual page views](https://developers.google.com/analytics/devguides/collection/ga4/views)
+and [disable flag](https://developers.google.com/tag-platform/security/guides/privacy).
+
+**LIMITATIONS:** no reporting/Admin API, property provisioning, consent banner,
+advanced Consent Mode, Ads conversion import or live delivery verification.
+Example: a configured booking app can send a consented page view and generate_lead;
+the owner still marks that event as a key event in Analytics and the framework
+wires navigation/consent. Existing tag installations use their existing tools.

package/docs/google-docs.md

@@ -0,0 +1,105 @@
+# Google Docs 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 Docs API** in APIs & Services → Library and enable
+`docs.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/drive.file` for create-first access. Also enable
+**Google Drive API** (`drive.googleapis.com`) for the blank-ID connection check.
+For read-only access to an existing document, choose `documents.readonly` and
+supply its Document ID. `documents` permits account-accessible document writes.
+Changing selected permissions requires reconnecting. Use External plus explicit
+test users while testing outside an eligible internal Workspace audience.
+
+## Fields and useful fragment
+
+Provider ID: `google-docs`. Import its provider from
+`@jskit-ai/connectors-catalog/server/google-docs`. 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.
+
+Operations: `connection.verify`, `documents.get`, `documents.create`,
+`documents.batchUpdate`. Verification input is optional.
+
+- With the recommended `drive.file`, leave Document ID blank. Verification lists
+  one accessible Drive file's metadata; an empty file list is valid. This creates
+  nothing and proves neither Docs API enablement nor access to every document.
+- With `documents.readonly` or `documents` alone, provide
+  `{ "documentId": "the_id_between_d_and_edit" }` to verify by reading the document.
+  Supplying a file ID does not share it with the app. `drive.file` grants access
+  only to app-created files or files explicitly selected/opened for this app.
+  Google Picker is app-owned wiring, not an embedded editor feature.
+- `documents.get` includes all tabs using includeTabsContent=true. Preserve tab IDs,
+  document content and revisionId in the app; there is no result pagination.
+- `documents.create` accepts `{title}` and returns a blank document. Store its ID
+  under the authorized application user, then call batchUpdate to add content.
+  Do not retry an uncertain creation without reconciling the user's files.
+- `documents.batchUpdate` accepts documentId, 1–100 native Google Docs `requests`
+  within 1 MiB, and optional `requiredRevisionId`. Each request contains one native
+  operation object. Google validates operation names, resource-dependent indices,
+  styles and atomic batch semantics; this adapter validates the envelope, not a
+  duplicate version of Google's request schema. Errors remain errors, not success.
+
+```js
+const created = await connections.invoke({ context, integrationId: "docs",
+  operation: "documents.create", input: { title: "Appointment notes" } });
+await connections.invoke({ context, integrationId: "docs",
+  operation: "documents.batchUpdate", input: {
+    documentId: created.documentId,
+    requests: [{ insertText: { endOfSegmentLocation: {}, text: "Customer notes\n" } }]
+  } });
+```
+
+For a multi-tab document, read tabs first and target the intended tabId in each
+native request. Use UTF-16 indices from Google's document representation; do not
+calculate text positions by byte count. Native requests support insertion,
+replacement/deletion, styles and tables. Fetch a current revision and supply
+requiredRevisionId to reject an edit against a changed document, then refetch and
+review a conflict rather than blindly retrying. The app renders content safely,
+authorizes user/document mappings and reviews destructive edits.
+
+Other frameworks use the same config and private Env references with their
+native Google Docs client or HTTP. No JSKIT requirement or Vibe64 service applies.
+
+**Limitations:** no visual editor, Google Picker component, sharing/Drive exports,
+comment/suggestion review UI, autonomous editing agent or editor chat attachment.
+For example, an app can create a booking report and format its text, but saving
+this connector does not let Vibe64's coding assistant edit the report. Fixtures
+prove request flow, not Google's live document rendering or approval.
+
+References: [create](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/create),
+[batchUpdate](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate),
+[Drive list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list).
+
+## 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
+`docs.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 an optional verification input as described above. The existing application
+owns authenticated callback routes and its permission policy. Configuration,
+OAuth, refresh, provider requests and storage remain library imports.

package/docs/google-drive.md

@@ -0,0 +1,108 @@
+# Google Drive 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 Drive API** in APIs & Services → Library and enable
+`drive.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/drive.file` (required by this connector). The
+captured defaults also select `drive.appdata`, `drive.appfolder` and
+`drive.readonly`; remove optional permissions your application does not need.
+The UI exposes additional documented scopes for applications that need them;
+selecting a scope does not implement every API it permits. Use External plus explicit
+test users while testing outside an eligible internal Workspace audience.
+
+## Fields and useful fragment
+
+Provider ID: `google-drive`. Import its provider from
+`@jskit-ai/connectors-catalog/server/google-drive`. 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: `{}`. Connection checks list metadata without modifying files.
+
+| Operation | Inputs and result |
+| --- | --- |
+| `files.list` | pageSize (1–1000), pageToken, q, optional driveId; returns files and nextPageToken. driveId sets shared-drive corpus/flags. |
+| `files.get` | fileId; returns metadata including parents, capabilities, exportLinks and webViewLink where Google supplies them. |
+| `files.download` | fileId for a stored binary/text file; returns bodyBase64, size and contentType, up to 8 MiB. |
+| `files.export` | fileId of a Workspace document and supported mimeType, e.g. application/pdf; same bounded binary result. Google enforces format and its own export limits. |
+| `files.create` | name, optional parentId, folder=true for a folder; creates metadata, not uploaded content. |
+| `files.upload` | name, contentType, standard padded bodyBase64, optional parentId for a new file or fileId to replace one; one native multipart request, max 5 MB input. Returns file metadata. |
+| `files.update` | fileId and at least one of name, description or trashed; explicit true moves to trash, false restores where permitted. |
+
+`drive.file` permits app-created or explicitly selected files. A copied ID alone
+is not a Google Picker grant. Broad `drive.readonly` can read accessible content;
+metadata-only scopes cannot download it. Writers need drive.file/drive or the
+relevant metadata scope **and** actual file sharing permissions. Reconnect after
+adding scopes. File capabilities and Google errors remain authoritative.
+
+The app resolves the authenticated user's connection and allowed file IDs before
+invoking operations. Never expose all file contents through an unauthenticated
+proxy. Decode bodyBase64 in the framework, preserve its MIME type, and choose safe
+download/content-disposition behavior; do not render arbitrary returned HTML.
+Treat transfer failures as failures. A timed-out upload may have succeeded: inspect
+Drive before retrying to avoid duplicate files or overwritten content. Replacing
+an existing file explicitly replaces its name and data. Moving an existing file
+between folders uses native addParents/removeParents, not upload parentId.
+
+```js
+const file = await connections.invoke({ context, integrationId: "drive",
+  operation: "files.upload", input: { name: "report.txt", contentType: "text/plain",
+    bodyBase64: Buffer.from("Appointment notes").toString("base64") } });
+const downloaded = await connections.invoke({ context, integrationId: "drive",
+  operation: "files.download", input: { fileId: file.id } });
+```
+
+Other frameworks use native Drive clients/HTTP with the same project config and
+private Env. For larger transfers use native resumable upload/streaming, not a
+larger JSON/base64 payload. No Vibe64 gateway receives or stores the content.
+
+**Limitations:** no sync/watch service, embedded Picker, large/resumable transfer,
+sharing administration, permanent deletion, revision history or Workspace-format
+conversion on upload. Activity and app-data scopes do not implement those APIs.
+For example, a generated app can upload a booking report and offer a PDF export,
+but it cannot mirror a whole shared drive automatically. Editor assistant access
+is deferred. Controlled fixtures do not prove live Google sharing or file export.
+
+References: [uploads](https://developers.google.com/workspace/drive/api/guides/manage-uploads),
+[downloads and exports](https://developers.google.com/workspace/drive/api/guides/manage-downloads).
+
+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/workspace/drive/api/reference/rest/v3/files/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
+`drive.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.

package/docs/google-maps-platform.md

@@ -0,0 +1,208 @@
+# Google Maps Platform
+
+Import `googleMapsPlatformProvider` from
+`@jskit-ai/connectors-catalog/server/google-maps-platform`. The runtime uses Geocoding v3, Places API (New) and Routes API. An optional
+browser composition helper uses the Google Maps JavaScript SDK loaded by the app.
+
+## Manual provider setup
+
+1. Sign into Google Cloud Console and select or create the project that will
+   own this application's usage. Link billing for Maps usage.
+2. Open **APIs & Services → Library**, find **Geocoding API**, and choose
+   **Enable**. Enable browser APIs separately if the app will render maps.
+   [API setup](https://developers.google.com/maps/documentation/geocoding/guides-v3/get-api-key),
+   [enabling services](https://docs.cloud.google.com/service-usage/docs/enable-disable).
+3. Open **APIs & Services → Credentials → Create credentials → API key**.
+   Name the key for server geocoding. Edit it, restrict allowed APIs to
+   **Geocoding API**, and configure suitable server IP restrictions. For the
+   additional operations, enable **Places API (New)** and **Routes API** in Library
+   and allow those APIs on this server key as well. Save.
+4. Store that key as `GOOGLE_MAPS_SERVER_KEY`. In Vibe64, add Google Maps
+   Platform and enter `env:GOOGLE_MAPS_SERVER_KEY` in **Server API key reference**.
+5. For browser maps, create a different key, enable only the browser APIs the
+   app uses, and apply **Websites** restrictions for the deployed and preview
+   origins. Store it as `GOOGLE_MAPS_BROWSER_KEY`; enter its optional reference.
+   Server keys must not use browser-referrer restrictions or be published in
+   client code. [Key restrictions](https://developers.google.com/maps/api-security-best-practices).
+6. For advanced map markers enable **Maps JavaScript API**, open **Google Maps
+   Platform → Map management → Create map ID**, select **JavaScript**, create it
+   and copy its public ID into **Map ID**. `DEMO_MAP_ID` is for development only.
+7. Open **Google Maps Platform → Quotas**, select the API and set suitable
+   limits. Save source configuration; actual connection verification is a
+   separate geocoding request and can incur usage charges. After saving, use
+   **Set credential in Env** for `GOOGLE_MAPS_SERVER_KEY`. Save the optional
+   browser key separately in Env. Return, enter **Verification address** and
+   choose **Connect account**.
+   [Quotas and billing](https://developers.google.com/maps/documentation/geocoding/usage-and-billing).
+
+## Portable configuration and runtime
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "maps": {
+      "provider": "google-maps-platform",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:GOOGLE_MAPS_SERVER_KEY"
+      },
+      "settings": { "browserKeyRef": "env:GOOGLE_MAPS_BROWSER_KEY" }
+    }
+  }
+}
+```
+
+Use the [API-key source pattern](../patterns/api-key-connection/PATTERN.md)
+with this provider, the application's authorization policy and its reference
+resolver. File-backed state remains outside source. No database or editor
+process is required for CLI use.
+
+```js
+await connections.connectApiKey({
+  context, integrationId: "maps",
+  verificationInput: { address: "Perth WA, Australia" }
+});
+const locations = await connections.invoke({
+  context, integrationId: "maps", operation: "geocoding.forward",
+  input: { address: "Perth WA, Australia", language: "en", region: "au" }
+});
+const addresses = await connections.invoke({
+  context, integrationId: "maps", operation: "geocoding.reverse",
+  input: { latitude: -31.95, longitude: 115.86 }
+});
+```
+
+Supply the verification address deliberately. There is no hidden default query;
+an omitted address fails before HTTP transport. Verification checks server
+geocoding only. It never resolves or verifies the optional browser key. An app
+that renders browser maps resolves and publishes that separate key explicitly.
+Clearing the optional reference removes it from saved source.
+
+Forward input accepts an address or plus code, optional language and region
+bias. Reverse input accepts latitude/longitude and optional language. The
+adapter preserves the provider result, including components, geometry and
+partial-match indicators. It accepts `ZERO_RESULTS` with an empty list as a
+successful lookup, without claiming an address exists.
+[Forward response](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding),
+[reverse response](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-reverse-geocoding).
+
+Local input limits are 1,000 address characters, latitude ±90 and longitude ±180.
+Language codes and two-letter region codes receive syntax checks; the provider
+decides availability. Advanced filters, extra computations and v4 operations
+are outside this initial adapter.
+
+HTTP-200 `OVER_QUERY_LIMIT`, `REQUEST_DENIED`, `INVALID_REQUEST` and
+`UNKNOWN_ERROR` responses become safe failures. `OVER_DAILY_LIMIT` can mean
+invalid key, missing billing or a usage cap, so its error asks the operator to
+check all three. Provider diagnostic text is not echoed. Ordinary non-2xx errors
+use the common transport handling. An HTTP 401 marks an existing connection
+as requiring reconnection.
+[Status definitions](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding).
+
+## API provisioning and application ownership
+
+An authorized AI can prepare Cloud project creation and API enablement with
+Resource Manager/Service Usage or `gcloud`. Account access, billing authority
+and provider terms remain operator decisions.
+[Project and service preparation](https://docs.cloud.google.com/service-usage/docs/enable-disable).
+
+The API Keys API can create a key at
+`POST /v2/projects/{projectNumber}/locations/global/keys`, configure restrictions,
+and retrieve its key string. Poll the returned operation to completion before
+using the result. This requires authorized Cloud credentials; a Maps API key
+cannot create sibling keys. Save resulting values in secret bindings, not
+configuration files or command output logs. This package does not execute
+provisioning. [API key management](https://docs.cloud.google.com/api-keys/docs/create-manage-api-keys).
+
+The application owner provisions its Cloud project and supplies the appropriate
+keys. Two differently named keys in one project still share its project quota.
+Billing and usage limits remain the application owner's responsibilities.
+[Project quotas](https://developers.google.com/maps/documentation/geocoding/usage-and-billing).
+
+Google additionally recommends separating client and server usage into projects
+when their quota needs differ. Choose the application's projects according to
+its browser/server usage. Website restrictions use
+the application domain, such as its hosting subdomain or custom domain. Server
+restrictions use actual outbound IPs, including any configured proxy egress. A per-user
+editor VM URL does not substitute for either. These API keys are unrelated to
+Google login or OAuth callback registration.
+[Client/server restrictions](https://developers.google.com/maps/api-security-best-practices).
+
+## Focused evidence
+
+Six fixture tests cover explicit verification input, file restart, rotation,
+owner isolation, separate browser references, input bounds, empty responses,
+HTTP-200 errors and transport failures. Editor browser tests cover both
+reference fields, invalid values, reload and optional-field removal. The runtime
+does not automatically retain geocoding results; applications own display and
+retention behavior under the provider's requirements. No live provider use or
+sample-app generation is part of this evidence.
+
+
+## Places, routes and browser composition
+
+- `places.search`: textQuery, optional pageSize (1–20, default 10), pageToken and
+  languageCode. Keep the query the same for subsequent pages. Returns places and
+  nextPageToken; an absent places array is a legitimate empty result.
+- `places.get`: placeId. Both operations request fixed ID, display name, formatted
+  address, location, attribution and Google Maps URI fields. These are **billable
+  fields** (including Pro-tier fields for Text Search); no free-usage assumption
+  or wildcard mask is made. Review current pricing and show required attribution.
+- `routes.compute`: originLatitude/originLongitude and destinationLatitude/
+  destinationLongitude, with DRIVE (default), WALK or BICYCLE. Returns distance,
+  duration and GeoJSON line coordinates. An absent routes array means no route;
+  don't display zero minutes as a successful trip. No traffic, waypoint ordering
+  or turn-by-turn navigation system is supplied.
+
+The app authorizes/rate-limits requests and resolves only its server key for
+backend calls. Places/Routes use a header key; the optional browser key is never
+resolved by these operations. Restrict each key and enabled APIs separately.
+Geocoding verification does not establish that Places, Routes or browser maps work.
+
+For JavaScript frontends import `mountGoogleMap` from
+`@jskit-ai/connectors-catalog/client/google-maps-platform`. First use the
+framework's normal [Google SDK loader](https://developers.google.com/maps/documentation/javascript/load-maps-js-api)
+with the separately resolved **public browser key**. Wait for SDK readiness and
+surface loading/key/billing errors. Give the map container a nonzero height.
+Resolve `settings.mapId` as public text. Never pass the server key to this helper.
+
+```js
+// After the app's loader resolves Google Maps SDK readiness:
+const mounted = await mountGoogleMap({
+  element: document.querySelector("#map"), maps: google.maps,
+  center: { lat: -31.95, lng: 115.86 }, zoom: 12,
+  mapId: configuredMapId,
+  markers: [{ position: { lat: -31.95, lng: 115.86 }, title: "DogAndGroom" }],
+  path: routeCoordinates.map(([lng, lat]) => ({ lat, lng })),
+  signal: componentAbortController.signal
+});
+// On component removal:
+mounted.dispose();
+```
+
+`routeCoordinates` is `routes[0].polyline.geoJsonLinestring.coordinates` when a
+route exists; pass [] otherwise. The helper creates a native interactive map,
+AdvancedMarkerElement markers and an optional route polyline. Marker titles are
+text, not HTML. Limits are 100 markers/10,000 route points. It validates inputs,
+waits for map/marker libraries and removes overlays/listeners on disposal or
+abort. The application owns the container and must dispose before remounting;
+it also owns place selection, viewport/route updates and readable error/empty UI.
+No SDK or API request is made before the app explicitly loads and invokes it.
+
+Other frameworks use their own browser/native Google Maps tools and the same
+config/Env split; they do not need this JavaScript helper or a Vibe64 service.
+Keep Google attribution and data-retention/display requirements intact.
+
+**Limitations:** no embedded map designer, SDK loader, autocomplete/session-token
+widget, Places photos/reviews, route optimization, transit or navigation product.
+For example, a generated app can find a groomer and display its location and a
+route, but cannot provide live voice navigation. Editor assistant attachment is
+deferred. Controlled HTTP/SDK fixtures do not prove live tiles, routes or billing.
+
+Sources: [Places Text Search](https://developers.google.com/maps/documentation/places/web-service/text-search),
+[Routes reference](https://developers.google.com/maps/documentation/routes/reference/rest/v2/TopLevel/computeRoutes),
+[advanced markers](https://developers.google.com/maps/documentation/javascript/advanced-markers/start).