@jskit-ai/connectors-catalog 0.1.1

package/docs/inngest.md

@@ -0,0 +1,178 @@
+# Inngest
+
+Import `inngestProvider` from `@jskit-ai/connectors-catalog/server/inngest`.
+This fragment sends one explicitly authorized event and reads registered app
+and function metadata. The UI edits the same portable configuration as a CLI.
+It supports shared and assistant accounts, using the owner's credentials.
+
+## Manual setup
+
+1. Sign into Inngest Cloud and select the intended environment using the
+   environment selector.
+2. Click the adjacent key icon, choose **Event keys**, then **+ Create Event
+   Key**. Set a descriptive name, choose **Save changes**, and use **Copy**.
+   Apply event-name/IP restrictions appropriate to the application's events.
+3. Store that value in the backend environment as `INNGEST_EVENT_KEY`. Enter
+   `env:INNGEST_EVENT_KEY` in the editor's **Event Key reference** field.
+4. In the intended environment's **Signing Key** tab, copy its Signing Key.
+   Store it as `INNGEST_SIGNING_KEY` and enter `env:INNGEST_SIGNING_KEY` in
+   **Signing Key reference**. The two keys have different purposes.
+5. Leave **Branch environment (optional)** empty for ordinary delivery. For
+   branch delivery, enter the intended branch identifier. This field only
+   affects event delivery, not metadata queries.
+6. Save configuration. Choose **Set credential in Env** to save
+   `INNGEST_SIGNING_KEY`; under **Inngest Event Key**, choose **Set credential in Env** to save
+   `INNGEST_EVENT_KEY` separately.
+   Save both values in backend Env, return, and choose **Connect account**.
+   This verifies metadata only. Separately implement and register the
+   application's workflow functions using Inngest's SDK.
+
+[Event Key creation](https://www.inngest.com/docs/events/creating-an-event-key),
+[Signing Key configuration and rotation](https://www.inngest.com/docs/platform/signing-keys).
+Both keys remain secrets. Changing a signing key also affects any application
+serve endpoint using it; coordinate SDK rotation independently of this connector.
+
+## Configuration and runtime
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+The required `eventKeyRef` uses the core's secret-reference grammar. Optional
+`branchEnvironment` accepts 1–255 printable ASCII characters without spaces.
+Strings use shared schema normalization. Clearing the branch removes it from
+the file. Changing either reference or the branch requires verification again.
+
+Compose the provider with the [API-key file-runtime pattern](../patterns/api-key-connection/PATTERN.md).
+The existing connection owner handles authorization, environment resolution,
+file persistence and disconnect. No database or Vibe64 server is required by
+the CLI. The [event-delivery pattern](../patterns/event-delivery/PATTERN.md)
+adds application-owned event authorization and explains the workflow boundary.
+
+| Operation | Input | Effect |
+|---|---|---|
+| `apps.list` | Optional `limit` 1–100, `cursor`, `archived` | Read one app metadata page; defaults to 20 and excludes archived apps. |
+| `functions.list` | Required `appId`; optional `limit` 1–100 and `cursor` | Read one function metadata page for that app. |
+| `events.send` | Required `name` and object `data`; optional `id`, `ts`, `v`, object `user` | Send one event, which may start registered workflows. |
+
+`connectApiKey` calls `apps.list` using the Signing Key as a bearer credential.
+It validates the metadata page before recording a grant. It does not send a
+test event, resolve the Event Key, prove the two keys belong to the same
+environment, or prove a workflow exists. An empty app list is valid.
+
+Metadata uses `https://api.inngest.com/v2/apps` and the app's `/functions`
+endpoint. These endpoints are marked beta in the reviewed
+[official v2 schema](https://api-docs.inngest.com/api-specs/v2.json).
+The provider preserves `data` and `page`, including opaque cursors; requesting
+another page is explicit. Inngest also offers separate v2 API keys, but this
+initial form models the application Signing Key and Event Key pairing.
+[REST authentication](https://api-docs.inngest.com/authentication).
+
+`events.send` resolves the Event Key only after application authorization and
+sends JSON to `https://inn.gs/e/<encoded-key>`. It removes the Signing Key header
+and adds `x-inngest-env` only when a branch is configured. Redirects are rejected;
+the caller cannot supply an alternative destination. The normal Event API is
+used, rather than the low-volume v2 event debugging endpoint.
+[HTTP event delivery](https://www.inngest.com/docs/events).
+
+This fragment accepts one event, not a batch. It bounds names to 255 characters,
+IDs to 512 and versions to 255; `ts` must be integer Unix milliseconds from
+1980 onward within JavaScript's safe-integer range. Unknown fields and invalid
+objects are rejected before HTTP. Application policy receives the event input
+before credentials are resolved. It must authorize the event name, payload and
+tenant, not merely membership in the shared connection.
+
+A successful result requires status 200 and one nonempty event receipt ID.
+That receipt acknowledges delivery, not successful workflow execution. There
+are no automatic retries. A timeout or cancellation can occur after remote
+acceptance, so the application must reconcile before resending. A stable event
+`id` can help Inngest deduplicate function runs within its documented 24-hour
+window; include the event type and business operation in that identifier.
+[Event IDs and deduplication](https://www.inngest.com/docs/events#deduplication).
+Provider failures return safe connector errors without credentials or provider
+response text. Local disconnect neither deletes the provider keys nor cancels
+accepted workflow runs.
+
+## AI automation and application ownership
+
+AI can prepare configuration, reference bindings, JSKIT composition, event
+payloads and SDK function code. An authorized operator can automate supported
+management tasks through the [Inngest CLI](https://www.inngest.com/docs/cli) and
+v2 API after credential bootstrap. The reviewed schema exposes environment
+creation and app metadata operations; that does not establish automated account
+signup or initial credential issuance. Use the dashboard steps above for the
+initial keys and validate the current API before adding provisioning calls.
+
+The application owner supplies its Event and Signing Keys through private Env.
+These are not OAuth registrations. Separate Event Keys support independent rotation and
+attribution, but labels or environments do not establish independent billing
+or quota pools. The application owner must obtain
+the provider capacity it needs. Signing Keys belong in the application backend,
+never the editor binary or browser bundle.
+
+No OAuth callback is involved. The editor VM and published app can have different
+domains. If the app hosts Inngest functions, its SDK endpoint/worker registration
+belongs to that deployed app and must be configured separately. Self-hosted
+Inngest endpoints, OAuth, function registration, schedule management and run
+cancellation are not implemented by this fragment.
+
+## Focused proof
+
+Nine provider tests use simulated HTTP replies and actual temporary encrypted
+JSON files. They cover metadata verification, separate credential destinations,
+encoded Event Keys, branch delivery/removal, payload policy, malformed replies,
+pagination, rotation, ownership, restart, disconnect and cancellation without
+replay. Editor tests cover both references, branch validation, reload and
+optional-field removal. Live provisioning, event delivery, workflow execution
+and generated sample apps are excluded from this proof.
+
+Credential creation and signing-key instructions were rechecked against current
+official documentation on 2026-09-12. The screen now explains both Env entries,
+the optional branch and the limits of connection verification. Updated rendered
+review passed with simulated connection responses; no live event has been sent.
+
+## Native functions and scheduled work
+
+The [event-delivery pattern](../patterns/event-delivery/PATTERN.md#native-functions-and-cron)
+now includes an app-owned function and cron composition using the current native
+Inngest SDK. Install that SDK in the application only when it hosts functions;
+the connector package does not acquire a workflow-engine dependency.
+
+Deploy the native serve handler at the application's `/api/inngest` route. Set
+`INNGEST_SIGNING_KEY` from the same intended environment so the SDK validates
+Inngest requests; do not replace signature verification with a public unguarded
+business action. Other frameworks use a supported native SDK/serve adapter. If
+none exists for that framework, event submission still works, but a separate
+supported function host is an explicit application choice, not a JSKIT sidecar.
+
+In Inngest Cloud select the environment, open Apps, choose Sync App / Sync New
+App, enter the deployed HTTPS serve URL and Sync App. After function changes,
+open that app and Resync. If the domain changes use Override for the new URL,
+keeping the same SDK app ID. The editor does not perform this deployment/sync.
+[Sync guide](https://www.inngest.com/docs/apps/cloud), reviewed 2026-09-13.
+
+**LIMITATIONS:** No automatic SDK installation, function generation/deployment,
+provider app sync, workflow dashboard, run cancellation or self-hosted endpoint
+mode. Example: an app can submit a report event, but a report only runs after
+its own SDK function is deployed and synced. Schedule execution and SDK business
+functions are native application composition, not tested live or through a
+generated app here. Editor-assistant attachment is deferred. The connector's
+metadata check does not prove the Event Key or function availability.

package/docs/klipy.md

@@ -0,0 +1,149 @@
+# KLIPY
+
+Import `klipyProvider` from `@jskit-ai/connectors-catalog/server/klipy`.
+This own-key adapter browses and searches clips, GIFs, stickers and existing AI
+emojis. It does not generate new emojis or implement managed billing.
+
+## Manual provider setup
+
+1. Sign into [Partner Panel](https://partner.klipy.com) and choose **Add Platform**.
+2. Enter the platform name, contact email, company website and product
+   description; accept the API terms and submit.
+3. Create a named API key. Supply its **App URL** when available.
+4. Store the value as `KLIPY_APP_KEY` in the backend environment. In Vibe64,
+   add KLIPY, enter `env:KLIPY_APP_KEY` in **API key reference**, and choose
+   **Save configuration**. Choose **Set credential in Env**, save the real key
+   as `KLIPY_APP_KEY`, then return and choose **Connect account**. This reads
+   trending metadata and consumes an API request; it does not grant production
+   approval. No OAuth callback is required.
+5. When the application is ready, open the key's **⋯ → Request Production**.
+   Supply its category, estimated monthly active users and a screen recording,
+   then choose **Apply**. Provider approval is a separate step.
+
+[Partner Panel setup](https://klipy.com/blog/klipy-partner-panel).
+
+Test keys allow 100 requests per hour. The developer page describes production
+approval and an advertising option in **Update App Details**. Production
+capacity and advertising behavior belong to the provider agreement; this
+adapter makes no unlimited-capacity promise.
+[Developer setup and limits](https://klipy.com/developers).
+
+## Portable configuration and runtime
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "media": {
+      "provider": "klipy",
+      "displayName": "Clip search",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "api-key", "secretRef": "env:KLIPY_APP_KEY" }
+    }
+  }
+}
+```
+
+Compose the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with
+`providers: [klipyProvider]`, application authorization and private file storage.
+The same configuration and runtime calls work from a manually wired CLI. The
+provider module adds no database or Vibe64 service dependency.
+
+```js
+await connections.connectApiKey({ context, integrationId: "media" });
+const clips = await connections.invoke({
+  context, integrationId: "media", operation: "clips.search",
+  input: { q: "happy dog", per_page: 8, locale: "us" }
+});
+```
+
+| Operation | GET path after `/api/v1/<app_key>` | Required input |
+|---|---|---|
+| `clips.trending` (verification) | `/clips/trending` | None |
+| `clips.search` | `/clips/search` | `q` |
+| `gifs.trending`, `gifs.search` | `/gifs/trending`, `/gifs/search` | `q` for search |
+| `stickers.trending`, `stickers.search` | `/stickers/trending`, `/stickers/search` | `q` for search |
+| `emojis.trending`, `emojis.search` | `/emojis/trending`, `/emojis/search` | `q` for search |
+
+The documented Clip API uses a key in the path. Pages start at 1; trending page
+sizes range from 1 to 50 and search sizes from 8 to 50, with 24 as the default.
+Both accept `customer_id`, a two-letter locale and a content-filter level.
+The success envelope contains `result: true` and items in `data.data`.
+[Clip API](https://docs.klipy.com/clips-api).
+
+Local defaults are page 1, 24 items and `content_filter: "high"`. The runtime
+accepts `off`, `low`, `medium` or `high` when explicitly supplied; the filter is
+not a guarantee about every item's suitability. Local bounds cap pages at
+100000, queries at 500 characters and customer identifiers at 256 characters.
+Verification supplies no customer identity. If personalization is needed,
+application code chooses an appropriate stable identifier; the adapter never
+uses an email or account ID implicitly.
+
+The module validates the collection envelope and preserves remaining response
+metadata and media fields. Empty results are valid. Request another page
+explicitly; returned links are not followed with credentials. A false `result`
+does not verify a connection. HTTP authentication failures, permission errors
+and rate limits become shared connector errors; arbitrary error bodies are
+discarded. There is no automatic retry or background synchronization.
+
+The backend encodes the key into the path only after checking the fixed HTTPS
+destination. Logs and tracing must redact authenticated request paths. Source
+and saved connection state contain references, and environment changes take
+effect on the next call. Local disconnect does not revoke the provider key.
+An app key is not a login identity or a per-user OAuth grant.
+
+## API provisioning and application ownership
+
+No public bootstrap API for initial platforms, keys or production approval was
+verified in the linked documentation. An AI can prepare the configuration,
+runtime wiring and approval information; account access and the documented
+Partner Panel steps remain manual. Do not infer a provisioning API from the
+dashboard's internal requests.
+
+Create a key for the application and keep it in private Env. Distinct names alone
+do not establish independent production limits; confirm the required capacity
+with KLIPY. Preserve the customer's key ownership when exporting or moving the
+application. This module consumes an explicitly supplied key.
+
+Outbound reads need no OAuth callback, so VM subdomains and custom deployment
+domains do not alter authentication. Record the intended application URL in
+provider setup and satisfy its content/attribution agreement in the application.
+
+## Focused evidence
+
+Fixtures check trending verification, search encoding, pagination bounds,
+locale/filter errors, unsuccessful envelopes, key rotation, private file-store
+restart, owner isolation and provider failures. Core tests cover path encoding,
+invalid destinations, ambiguous prefixes and error redaction. The editor test
+checks the secret reference, setup link and reload persistence. No live key,
+production approval, media use or generated sample application is exercised.
+
+The official Partner Panel guide was rechecked on 2026-09-12. Expanded screen
+steps cover Env handoff, connection verification, production approval and local
+disconnect. Updated rendered review passed using simulated connection responses.
+
+## Embedding and limits
+
+The application supplies its own picker and native HTTP/runtime wiring in any
+framework, using the same JSON and private Env. Use **Search KLIPY** as the
+search placeholder. Choose an appropriate returned image/video format; preserve
+its complete URL and delivery metadata. Images need meaningful alt text; clips
+need user-controlled playback. Do not download media through this adapter.
+
+Follow [KLIPY integration requirements](https://docs.klipy.com/clips-api): custom
+server-side requests need prior provider approval, including this backend
+integration. Proxying/caching requires separate approval. Preserve ranking,
+reporting and any ad entries and delivery requirements; this reader preserves
+the envelope but does not implement those UI events. Check these requirements
+before shipping. The Partner Panel controls ads and content restrictions.
+
+**LIMITATIONS:** No picker, ad renderer, share/report tracking, caching, new AI
+emoji generation or automatic editor-assistant attachment. Example: a customer
+can search existing dog stickers through app code, but cannot create a new dog
+emoji through this adapter. Public docs advertise generation and status endpoints;
+the request/result contract could not be established from the accessible docs,
+so no guessed generation operation was added. No live/provider approval or
+generated-app execution is claimed. Collection search intentionally uses the
+same conservative local 8–50 item bound across these families.

package/docs/lexware.md

@@ -0,0 +1,144 @@
+# Lexware Office
+
+Import `lexwareProvider` from `@jskit-ai/connectors-catalog/server/lexware`.
+This adapter verifies an API key, reads accounting resources and creates draft invoices. The provider calls this
+its Public API; its bearer key is still a private backend credential.
+
+## Provider setup
+
+1. Sign into the intended Lexware Office account. Public API access requires
+   the XL plan. Open **Erweiterungen → Weitere Apps → Public API**, or
+   [the Public API settings](https://app.lexware.de/addons/public-api).
+2. Select **API-Schlüssel erstellen**. In **Neuen API-Schlüssel erstellen**,
+   select individual permissions and enable contact reading. Add article/document
+   read access and invoice creation only for the operations needed. Choose **WEITER**,
+   give the key a name, then choose **API-Schlüssel erstellen**.
+3. Copy the key before closing the dialog; it is not displayed again. Store it
+   as `LEXWARE_API_KEY` in the backend environment. Add Lexware in Vibe64 and
+   enter `env:LEXWARE_API_KEY` in **API key reference**.
+4. Record the expiry for operations: keys may be valid for up to 24 months.
+   Use the provider's renewal controls before expiry. Changed permissions
+   require a new key; update the environment binding and verify it before
+   retiring the previous key.
+
+[Provider key setup and lifecycle](https://help.lexware.de/de-form/articles/548863-alles-rund-um-public-api).
+
+## Configuration and library calls
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "contacts": {
+      "provider": "lexware",
+      "displayName": "Accounting contacts",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "api-key", "secretRef": "env:LEXWARE_API_KEY" }
+    }
+  }
+}
+```
+
+Compose `providers: [lexwareProvider]` with the
+[API-key pattern](../patterns/api-key-connection/PATTERN.md), environment
+references, an authorized application context and the file connection store.
+Both CLI and editor use this schema. Runtime state uses encrypted JSON outside
+application source; a database is not required.
+
+```js
+await connections.connectApiKey({ context, integrationId: "contacts" });
+const page = await connections.invoke({
+  context, integrationId: "contacts", operation: "contacts.list",
+  input: { page: 0, size: 25, customer: true }
+});
+```
+
+The runtime uses bearer authentication and
+`GET https://api.lexware.io/v1/contacts`. The current origin replaces the old
+Lexoffice API origin. Pages are zero-based; size defaults to 25 with a maximum
+of 250 for contacts. Optional `customer` and `vendor` booleans filter contact
+roles. Results include `content` and page metadata (`first`, `last`, `number`,
+`size`, `totalPages`, `totalElements`, `numberOfElements`).
+[API documentation](https://developers.lexware.io/docs/).
+
+The fragment requires positive integer size and caps the page number at 100000.
+It validates the envelope while preserving contact fields and empty pages.
+Request the next numbered page explicitly until `last` is true. It performs no
+background scan. Name/email searches, sorting and partner OAuth
+are outside this fragment; unsupported input fields are rejected rather than
+forwarded. Provider-specific escaping for text searches therefore needs an
+explicit implementation before those filters can be added.
+
+The key is sent only to the fixed HTTPS API origin; redirects are rejected.
+Changing the environment key takes effect on the next request. A rejected key
+requires verification again. Disconnect deletes the local connection record,
+not the provider key. A contact's email address is not proof of an app user's
+identity; the application owns login and authorization.
+
+## Automation and application ownership
+
+An AI can prepare JSON, secret references, JSKIT composition and contact-reading
+code. The reviewed setup guide describes dashboard key creation, without a
+self-service API for creating customer accounts or their API keys. Treat those
+as manual owner/admin steps. A partner authorization flow would need its own
+documented adapter and agreement; this fragment does not activate one.
+
+The application's key is a credential, not an OAuth app registration. Customer-owned accounting connections require
+customer-owned keys. There is no callback URL, so VM subdomains and deployed
+app domains do not affect this key flow.
+
+Lexware documents a client rate limit of two requests per second across API
+endpoints. The reviewed material does not establish that issuing another key
+provides an independent allowance. Apply usage limits in the application and
+confirm provider capacity before claiming quota isolation.
+[API rate limits](https://developers.lexware.io/docs/).
+
+## Focused evidence
+
+Simulated replies and real temporary file state verify authentication, restart,
+rotation, ownership, disconnect, empty/full contact pages, role filters,
+fractional/oversized input rejection and malformed/provider failures. The
+editor check verifies reference-only storage and persistence after reload.
+Live provider accounts, billing changes and sample-app generation are excluded.
+
+## Accounting operations
+
+`contacts.get`, `articles.get`, `invoices.get`, `vouchers.get` take a resource UUID.
+`articles.list` accepts page/size plus articleNumber, gtin and PRODUCT/SERVICE type.
+`vouchers.list` reads `/v1/voucherlist`: choose voucherType and voucherStatus
+explicitly, optionally contactId/archived/page/size. The invoice type must be
+retrieved with invoices.get; bookkeeping purchase/sales vouchers use vouchers.get.
+Other voucher types require their native endpoint.
+
+`invoices.createDraft` deliberately creates only net-EUR invoices for an existing
+contact, with 1–100 custom lines. It takes contactId, voucherDate, shippingDate,
+shippingType (service/delivery), lineItems and optional title/introduction/remark.
+Each line supplies name, quantity, unitName, netAmount and taxRatePercentage.
+No tax rate is inferred. Review accounting values and authorization in app code.
+Review/finalize the resulting draft in Lexware; there is no send/payment action.
+
+```js
+await connections.invoke({ context, integrationId: "contacts",
+  operation: "invoices.createDraft", input: {
+    contactId: approvedCustomer.lexwareId,
+    voucherDate: approvedInvoice.date, shippingDate: approvedInvoice.serviceDate,
+    shippingType: "service", lineItems: approvedInvoice.lines
+  }
+});
+```
+
+`approvedCustomer` and `approvedInvoice` are app-owned, authorized business data.
+A Laravel or other native backend can use its own HTTP client with the same
+private key/configuration and the documented Lexware endpoint. JSKIT adds no
+accounting database, tax engine or scheduler. A CLI uses the same library call.
+
+**LIMITATIONS:** No contact/article/voucher writes, receipt uploads, PDF downloads,
+quotation workflows, gross/tax-free invoice creation, finalization or event
+subscription receiver. Example: a booking can prepare a draft for an existing
+customer, but cannot ingest an expense receipt or deliver an invoice PDF with
+this adapter. Native app code must cover those features separately. Editor
+assistant attachment is deferred. No live financial action or generated app was
+executed. Failed/uncertain creation is never automatically repeated: inspect
+vouchers first. Provider validation remains authoritative.

package/docs/lightspeed.md

@@ -0,0 +1,193 @@
+# Lightspeed Retail X-Series
+
+Import `lightspeedProvider` from `@jskit-ai/connectors-catalog/server/lightspeed`.
+This first fragment provides OAuth and three read operations through the existing
+connection service and encrypted file store. CLI and editor users share the same
+configuration contract. Saving the file does not connect a store.
+
+## Create the provider registration
+
+1. Open the [X-Series developer portal](https://developers.retail.lightspeed.app/).
+   Register a developer account; a retail-store login is a separate account.
+2. Sign in, open **Applications**, and choose **Create**. Enter the application
+   details requested by the portal and your backend's exact redirect URI.
+3. Copy **Client ID** into the form and **Save configuration**. Use
+   **Set credential in Env** for **Client Secret** and **Set callback in Env**
+   for the exact registered redirect URI. Save Env values, then return to the
+   integration. The application backend must implement that route.
+4. Copy the store prefix from its `https://PREFIX.retail.lightspeed.app` address.
+   Configure that store before starting authorization.
+5. Save the file, call `beginAuthorization`, and open its URL in a system browser.
+   Authorize the intended retailer. Pass the callback to `completeAuthorization`
+   with the same authenticated owner. Use explicit local cancellation if a declined
+   callback lacks state; do not associate it with an arbitrary pending attempt.
+6. New registrations initially allow 30 stores. Request provider approval before
+   operating a public production integration. Personal tokens are a separate
+   option, outside this OAuth fragment. [Authorization](https://x-series-api.lightspeedhq.com/docs/authorization)
+
+## Portable configuration and editor fields
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "lightspeed": {
+      "source": "own",
+      "clientId": "REPLACE_WITH_LIGHTSPEED_CLIENT_ID",
+      "clientSecretRef": "env:LIGHTSPEED_CLIENT_SECRET",
+      "callbackUrlRef": "env:LIGHTSPEED_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "retail": {
+      "provider": "lightspeed",
+      "displayName": "Store inventory",
+      "accountMode": "shared",
+      "authentication": { "method": "oauth2", "registrationRef": "lightspeed" },
+      "settings": { "domainPrefix": "your-store" },
+      "scopes": ["products:read", "customers:read", "outlets:read"]
+    }
+  }
+}
+```
+
+In Vibe64, add **Lightspeed** in **Integrations**, choose the account mode, and
+enter **Client ID**, **Client secret reference**, **Callback URL reference** and
+**Domain prefix**. Edit permissions, then **Save configuration**. The client
+authentication method defaults to `client_secret_post`. Use reference values,
+not raw secrets or a literal callback URL. The domain field accepts a lowercase
+DNS label, not a whole URL. It cannot select arbitrary external hosts.
+
+The initial form includes 49 permission choices and initially selects 16 reads.
+The JSON above narrows access to the three implemented operations. Retain
+`products:read` for connection verification. Other selectable permissions record
+an intended grant; they do not implement additional operations. Provider scopes
+are space-separated and the runtime respects the actual token grant.
+[Scope reference](https://x-series-api.lightspeedhq.com/docs/scopes)
+
+`shared` means the host deliberately authorizes several app users to use one
+store connection. `per-user` gives each authenticated subject a separate grant;
+the configured store still applies to that slot. `assistant` uses the assistant
+owner. The host's `authorize` policy establishes those owners and any narrower
+record permissions. This configuration does not implement app login.
+
+## Runtime and operation contract
+
+| Operation | Required scope | Result |
+| --- | --- | --- |
+| `products.list` | `products:read` | Product page; also used for verification |
+| `customers.list` | `customers:read` | Customer page, preserving nullable fields |
+| `outlets.list` | `outlets:read` | Outlet page |
+
+All three accept `page_size` 1–100 (library default 20), optional integer `after`
+and `before` version bounds, and `deleted` (default false). This fragment bounds
+page size to 100; it does not assert that as the provider's maximum. Version
+numbers must fit JavaScript's safe integer range. A combined lower bound must be
+less than its upper bound. Unknown inputs, arbitrary destinations, name/SKU
+searches and writes are rejected before transport.
+
+Each invocation requests exactly one page and preserves provider records and
+version metadata. The caller chooses whether to request the next version page;
+there is no background traversal. Empty pages use null version bounds. The
+customer reference also permits an absent envelope version; row versions remain
+available. Missing IDs, unsafe versions, contradictory bounds and oversized
+responses fail validation. [Products](https://x-series-api.lightspeedhq.com/reference/listproducts),
+[customers](https://x-series-api.lightspeedhq.com/reference/listcustomers),
+[outlets](https://x-series-api.lightspeedhq.com/reference/listoutlets).
+
+The adapter pins `/api/2026-07/` reads. Lightspeed uses quarterly dated releases
+with at least twelve months of support and can serve an older requested version
+through a supported fallback after expiry. Review this pin against provider
+changes; it is not a promise of an immutable remote API.
+[Version policy](https://x-series-api.lightspeedhq.com/docs/versioning-strategy)
+
+Authorization starts at `https://secure.retail.lightspeed.app/connect`.
+Token exchange uses the configured store's `/api/1.0/token`; callback-supplied
+hosts never choose the credential destination. Successful token responses must
+identify that store and include scopes, expiry and a refresh token. Every rotated
+refresh token is saved before the next read. The shared runtime sends PKCE;
+Lightspeed's reviewed guide does not establish its enforcement. Verify that
+behavior with an approved test registration before production use.
+
+Cancellation reaches transport. Rate limits, missing permissions and revoked
+access have separate errors; calls are not retried automatically. A local
+`disconnect` deletes the stored grant without revoking it at the provider. If
+refresh returns an incomplete grant after consuming the old token, reconnect;
+do not repeatedly retry the spent refresh token.
+
+## Application ownership, callbacks and capacity
+
+The application owner creates the provider registration and stores its secret
+in the application's private Env. Public Vibe64, Vibe64 Online and CLI users use
+this same ownership model. The configuration file holds the client ID and Env
+references; the editor does not own the application's grants.
+
+Register the exact callback implemented by the application. For a hosted project,
+start with its assigned application URL and append the implemented callback path.
+Save that same URL through the application's callback Env reference. On a domain
+or host change, update both the provider registration and callback Env if the URL
+changes. Preserve the application's identity and persistent grant store when
+moving it; neither a new editor URL nor a new hosting address creates a new owner.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md) and
+[application setup command](../../connectors-core/docs/setup-command.md).
+
+The owner must obtain any required Lightspeed approval and retain the configured
+store prefix with the application's connection. Separate registrations alone do
+not prove independent provider quotas; confirm capacity at the provider account
+or store boundary before promising isolation.
+
+## Automation, CLI parity and proof
+
+An AI can write and validate this JSON, compose the JSKIT service and file store,
+wire an authenticated callback and implement explicit page presentation. There
+is no verified public registration-provisioning API in the reviewed material;
+do not invent one. Account creation, store consent and public-app approval remain
+operator/provider steps. Authorized browser assistance can help with available
+portal fields without guaranteeing unattended account creation or approval.
+
+A trusted CLI uses the same library, references and owner policy with a registered
+callback listener. The open-source editor never needs a database to edit this
+file and must not bundle a commercial client secret. Provider setup and runtime
+operations are reusable package code; the app owns routes, rendering and policy.
+
+Local proof uses controlled HTTP responses and temporary encrypted files. It
+covers scopes, store binding, refresh rotation, ownership, pagination, malformed
+responses, cancellation and editor persistence. No live retail account, provider
+registration, consent, data mutation or generated app was used. R-Series,
+K-Series, personal-token mode, webhook setup and additional API operations are
+outside this initial fragment.
+
+Credential instructions were rechecked against the official authorization guide
+on 2026-09-12. Screen steps now name the Env handoff, fixed store slot, shared
+and per-user connection entry points, explicit cancellation and local disconnect.
+Updated rendered review passed with simulated connection responses.
+
+## Inventory and sales reads
+
+`sales.list` uses the same version bounds/page_size as product pages, without
+a deleted filter. It requires sales:read. Correlate customer/outlet/product IDs
+in the returned sale with the app's authorized records. The app owns reporting,
+privacy and any aggregation; this connector installs no dashboard.
+
+`inventory.list` requires inventory:read and POSTs a read request to
+`/api/2026-07/inventory`. Input: after/before version bounds, size (local1–1000,
+default100), include_deleted, sort_direction (defaultasc), product_id and variants.
+Request variants only with a product ID. It returns a flat array, not a data
+wrapper. Preserve current_inventory_level and quantity_to_procure separately.
+Advance an ascending scan explicitly using the maximum returned version; never
+follow a provider-supplied URL with credentials. The app controls polling and
+reconciliation during concurrent stock changes.
+
+[Inventory contract](https://x-series-api.lightspeedhq.com/reference/listinventoryrecords),
+[quantity migration](https://x-series-api.lightspeedhq.com/docs/2026-04-release-notes),
+[sales pages](https://x-series-api.lightspeedhq.com/reference/listsales).
+
+A CLI app uses these same connection operations. Other frameworks implement
+native HTTP calls with their own project-owned OAuth grant and the same JSON/Env
+contract; no Vibe64 runtime or JSKIT sidecar is required.
+
+**LIMITATIONS:** No POS/dashboard UI, customer/product/stock/payment/sale writes,
+gift-card/store-credit workflows, webhook receiver or automatic editor tool
+attachment. Example: an app can report low stock and sales totals, but cannot
+replenish a shelf or charge a customer through this adapter. Adding a write scope
+does not implement a write operation. No live retailer or generated app was used.