@jskit-ai/connectors-catalog 0.1.1

package/docs/gatewayapi.md

@@ -0,0 +1,113 @@
+# GatewayAPI
+
+Import `gatewayApiProvider` from
+`@jskit-ai/connectors-catalog/server/gatewayapi`.
+Connection verification reads credit/currency without sending. Explicit application operations send single or batched SMS/RCS through the current Messaging API.
+
+## Configure access
+
+1. Sign into the intended Global or EU GatewayAPI account. In the left menu,
+   choose **API → API Keys → ADD API KEY** and give the credential a name.
+   Copy its API token into backend Env as `GATEWAYAPI_TOKEN`.
+   [Dashboard instructions](https://gatewayapi.com/help-center/webhooks-and-api-keys/).
+2. Save provider `gatewayapi`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication `{ "method": "api-key", "secretRef": "env:GATEWAYAPI_TOKEN" }`.
+3. Set `settings.region` to `global` (default) or `eu`, matching the platform
+   that issued the token. The form labels this **API domain** and limits it to
+   `gatewayapi.com` and `gatewayapi.eu`. The EU platform uses a different host;
+   changing hosts requires verification again.
+   [Platform routing](https://gatewayapi.com/docs/apis/legacy/rest/).
+4. In Vibe64 enter `env:GATEWAYAPI_TOKEN` as **API key reference**, click
+   **Save configuration**, then **Set credential in Env**. Store the real token
+   as `GATEWAYAPI_TOKEN` and return to connect. CLI apps call `connectApiKey`.
+   Requests use `Authorization: Token <token>`.
+   A legacy OAuth key/secret pair is a different credential. No webhook or
+   callback registration is needed for this read operation.
+   [Token authentication](https://gatewayapi.com/docs/authentication/).
+
+## Runtime and AI composition
+
+`balance.read` accepts no operation inputs and reads `GET /rest/me`. The result
+contains the integer account `id`, string `credit` and string `currency`.
+Retain credit as a decimal string when displaying or processing it; avoid
+rounding through binary floating-point arithmetic in financial workflows.
+[Balance endpoint](https://gatewayapi.com/docs/apis/prices-balance/).
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with the file
+store. `messages.send` submits a single message and `messages.sendBatch` accepts 1–1000 `messages`. Each needs sender, integer recipient (international country code, no plus), message and an app-owned reference. Optional label and normal/urgent priority are supported. Sender is 3–11 alphanumeric or 3–15 numeric characters. Save each returned msg_id and reference: HTTP acceptance is not delivery. Batches preserve individual receipts; do not automatically retry an uncertain send. RCS routing and SMS fallback depend on the account, approved agent and recipient.
+
+## Automation and application ownership
+
+The documented bootstrap creates an account and provides dashboard token
+management. This research does not establish a public API for creating the
+initial account or issuing tokens. An AI can prepare Env references, configuration
+and library wiring after the account owner supplies access.
+
+Keys in one account can share its credit and limits. Use the
+provider's account arrangements and explicit spending controls when provisioning
+independent pools; selecting Global versus EU is a hosting choice, not a quota
+partition. The application owner supplies its authorized key through private Env.
+
+Replace the Env token on rotation and revoke the obsolete token in the dashboard.
+Local disconnect removes local state only. Tests cover both fixed hosts, verified
+state across restarts, changed-region re-verification and provider errors, using
+simulated HTTP and no message delivery.
+
+## Delivery and inbound replies: application-owned webhook
+
+Official API checked 13 September 2026:
+[Messaging API](https://gatewayapi.com/docs/message/overview/) and
+[OpenAPI](https://messaging.gatewayapi.com/openapi.json).
+Messaging requests use `messaging.gatewayapi.com` or `.eu`; balance reads use
+the existing account host. Sending is billed by GatewayAPI. Check sender
+registration, destination restrictions and credits in the account; arrange an
+approved RCS agent with GatewayAPI before expecting RCS delivery. Urgent SMS
+may have a higher price. The current API chooses the transport, not the app.
+
+1. Add a public HTTPS route to the generated application, for example
+   `/integrations/gatewayapi/webhook`. Preserve its raw request bytes.
+2. In the matching Global/EU dashboard open API webhook settings, create the
+   callback, paste that application URL, select delivery/incoming events and
+   configure a private authentication/signature secret. Save the same secret
+   in application Env as `GATEWAYAPI_WEBHOOK_SECRET` (not the API token).
+3. Current Messaging callbacks use **Signature: v1=<HMAC-SHA256 hex>**. This
+   differs from the legacy REST `X-Gwapi-Signature` JWT described by older
+   guidance, including the current Lovable page. Do not mix verifiers.
+4. Use `verifyGatewayApiEvent` below, then transactionally persist each event
+   once using `event_id` as a unique key. For delivery events verify `msg_id`,
+   recipient and reference against an app-owned send record. Inbound messages
+   have no existing send reference; route them only to the configured leased
+   number or RCS agent. Never authorize them through arbitrary claimed users.
+5. Acknowledge with 2xx after persistence, promptly (within 5 seconds). Provider
+   retries must not create duplicate inbox messages or repeated side effects.
+   Apply your retention/replay policy to timestamp and stored event IDs; do not
+   discard legitimate delayed delivery simply using a tiny timestamp window.
+6. Incoming SMS needs the required leased number/keyword and callback routing;
+   RCS inbound needs agent configuration. The app owns these provider steps.
+
+```js
+import { verifyGatewayApiEvent } from "@jskit-ai/connectors-catalog/server/gatewayapi";
+const event = verifyGatewayApiEvent({ rawBody, signature: request.headers.signature,
+  secret: process.env.GATEWAYAPI_WEBHOOK_SECRET });
+// Your framework validates destination ownership and atomically inserts event_id.
+// Only after that transaction commits, acknowledge the callback.
+```
+
+The verifier authenticates up to 1 MiB of raw bytes and checks the common event
+envelope. It does not store, deduplicate or apply business state transitions.
+Unknown valid event types should be persisted/ignored safely; native status
+and text/location/file payloads remain available in `event`. Avoid fetching
+untrusted file URLs automatically. The current API offers no status polling;
+keep webhook history if the app needs delivery reporting.
+
+CLI apps use identical configuration, Env and these optional Node exports.
+Other frameworks use native HTTP and HMAC-SHA256 verification of raw bytes;
+no Vibe64 service is required. Disconnect does not remove provider webhooks;
+deactivate them in GatewayAPI when retiring the application.
+
+**LIMITATIONS:** no automatic webhook registration, number leasing, RCS agent
+approval or editor assistant attachment. Example: sending a booking reminder
+is provided; its delivered badge needs the app's webhook route and durable event
+store. That is also the ownership described in Lovable's connector guidance.
+Advanced RCS cards and an inbox UI are not supplied. Tests use controlled HTTP
+and signed callback fixtures, not real messages or provider provisioning.

package/docs/gemini-enterprise.md

@@ -0,0 +1,224 @@
+# Gemini Enterprise
+
+Initial fragment: Google OAuth, engine metadata and document search. The editor
+and CLI use the same file, validation and runtime. Saving configuration makes no
+Google requests. These operations use the connected Google account's permissions;
+shared and assistant ownership do not establish an identity for each app user.
+
+## Configuration
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "google-search": {
+      "source": "own",
+      "clientId": "example.apps.googleusercontent.com",
+      "clientSecretRef": "env:GEMINI_ENTERPRISE_SECRET",
+      "callbackUrlRef": "env:GEMINI_ENTERPRISE_CALLBACK"
+    }
+  },
+  "integrations": {
+    "enterprise-search": {
+      "provider": "gemini-enterprise",
+      "displayName": "Company search",
+      "accountMode": "shared",
+      "settings": {
+        "projectId": "my-gcp-project",
+        "location": "global",
+        "engineId": "my-search-engine"
+      },
+      "scopes": ["https://www.googleapis.com/auth/cloud-platform"],
+      "authentication": { "method": "oauth2", "registrationRef": "google-search" }
+    }
+  }
+}
+```
+
+`projectId` is the project identifier, not a numeric project number. `engineId`
+is 1–63 lowercase letters, digits, underscores or hyphens, starting with a letter
+or digit. `location` defaults to `global` and supports `us` and `eu`. The engine
+must already exist under `default_collection`; searches use
+`default_serving_config`. Other collections, serving configurations and locations
+are not included in this fragment. The editor renders location as a select to
+prevent unsupported values. The display name only labels this connection.
+
+The captured Cloud Platform permission is broad. Both implemented operations
+require it locally, while Google separately checks IAM and source permissions.
+The implementation exposes no resource writes despite the scope. Narrower Google
+scope variants and per-user connections are not yet provided. The host's
+`authorize` callback must control access to the shared connection and its results.
+Never accept a shared subject or application ID directly from an untrusted caller.
+
+## Provider setup: clicks and responsibilities
+
+1. Sign into [Google Cloud Console](https://console.cloud.google.com/) using the
+   account authorized to administer the target project. Select the project in
+   the top project picker. Confirm the project ID and billing with its owner.
+2. Open **APIs & Services → Library**, search for **Discovery Engine API**, open
+   it and click **Enable** if needed. This is `discoveryengine.googleapis.com`.
+3. Open **Gemini Enterprise → Apps**. Select the existing search app. If an
+   appropriate app does not exist, use **Create app**, choose the search setup,
+   enter its name, review the generated app ID, select its location and click
+   **Create**. Configure the intended data stores separately. Use Google's
+   [app creation instructions](https://docs.cloud.google.com/gemini/enterprise/docs/create-app)
+   for the applicable edition. Copy the engine/app ID and location, not its title.
+   Importing source content, configuring identities and any required licenses are
+   separate prerequisites; creating an OAuth client does not complete them.
+4. In **IAM & Admin**, have the project administrator create or select a role
+   with `discoveryengine.engines.get` and
+   `discoveryengine.servingConfigs.search`, and grant it to the Google account
+   that will connect. Apply the intended source permissions as well. Avoid
+   granting project Owner merely to make connection checking pass.
+5. Open **Google Auth Platform**. Configure **Branding**, **Audience** and
+   **Data Access** for this application's actual users. Add
+   `https://www.googleapis.com/auth/cloud-platform`. For an external application
+   in testing, add the connecting account under test users. Publishing or
+   verification, and organization restrictions, remain operator/provider work.
+6. Open **Clients → Create Client**, choose **Web application**, give it a name
+   and add the exact backend callback under **Authorized redirect URIs**. Click
+   **Create** and securely save the displayed client ID and secret. Enter only
+   the ID and secret reference in the integration file. Google documents this
+   confidential flow in its [web-server OAuth guide](https://developers.google.com/identity/protocols/oauth2/web-server).
+7. In Vibe64, copy **Suggested callback URL** into the Google redirect URI
+   registration. **Save configuration**, then use the Env links for the secret
+   and callback references. For the example above, set `GEMINI_ENTERPRISE_SECRET`
+   and `GEMINI_ENTERPRISE_CALLBACK` in the
+   application's server environment. The callback handler must already exist
+   and call the shared connection service; a value in a file creates no route.
+8. Save the configuration. In the application, start OAuth, choose the intended
+   Google account and approve access. The runtime verifies `engine.get` before
+   storing the connection. A successful metadata check does not prove search
+   permission, source ingestion, relevance or app-user access isolation.
+
+Google describes [engine access](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/projects.locations.collections.engines/get),
+[search permissions](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/projects.locations.collections.engines.servingConfigs/search)
+and [source access control](https://docs.cloud.google.com/generative-ai-app-builder/docs/data-source-access-control)
+separately. This fragment sends the shared account's OAuth token; it supplies no
+caller-selected source identity, impersonation header or Workforce Identity 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).
+
+Record the target engine's Google Cloud project as well as the registration's
+project. Two client IDs in one project do not isolate project quotas. Engine
+consumption and billing depend on the project hosting that engine; changing the
+OAuth registration does not move the engine's costs or capacity. The application
+owner supplies the registration and target-project permissions needed for its
+own users and resources.
+
+## AI-assisted provisioning
+
+An authorized AI can prepare JSON, IAM role definitions and API enablement steps,
+and can use Google resource APIs/CLI for permitted project and engine operations.
+For example, the engine [create API](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/projects.locations.collections.engines/create)
+exists. Provisioning must be explicitly authorized; this adapter exposes no such
+write operation. It can inspect supplied identifiers and help troubleshoot
+configuration without reading documents.
+
+Plan on operator setup for the standard Google Auth Platform web clients,
+branding/audience, verification, billing and source-identity decisions. This
+fragment provides no OAuth-client provisioning API or claim that an AI can
+complete those controls unattended. Prepare an application-owned registration
+and callback for each independent application; hosted and installed editors use
+the same ownership model. Copying IDs does not duplicate user consent or source
+permissions. Keep secrets out of chat, examples and source control.
+
+## Runtime and CLI wiring
+
+```js
+import { geminiEnterpriseProvider } from "@jskit-ai/connectors-catalog/server/gemini-enterprise";
+// Include geminiEnterpriseProvider in createConnectionService({ providers, ... }).
+const page = await connections.invoke({
+  context,
+  integrationId: "enterprise-search",
+  operation: "search",
+  input: { query: "holiday policy", pageSize: 10 }
+});
+```
+
+The app supplies configuration loading, reference resolution, authorization,
+encrypted file storage and callback routes, as described in the core package.
+`engine.get` accepts no input. `search` accepts a required nonempty `query`
+(adapter limit 4096 characters), `pageSize` 1–25 (default 10) and an optional
+`pageToken` (adapter limit 16000 characters). Reuse the same query and page size
+when requesting the next page. No automatic pagination occurs. The 25-result
+limit works across Google's documented search data types.
+
+The runtime uses Google's standard authorization and token endpoints with S256
+PKCE, offline consent and confidential client authentication. API requests use
+`discoveryengine.googleapis.com`, `us-discoveryengine.googleapis.com` or
+`eu-discoveryengine.googleapis.com` according to the configured location; see
+[Google's locations](https://docs.cloud.google.com/gemini/enterprise/docs/locations).
+Engine changes require reconnection. OAuth refresh, local disconnect, cancellation
+and bounded transport errors are owned by the existing core service.
+
+The original JSON search envelope is returned, including result document fields,
+attribution and pagination. Empty protobuf JSON result arrays may be omitted.
+A provider `redirectUri` is returned as data and is never followed; the consuming
+app must decide how to present it. Treat document text, URLs and snippets as
+untrusted content. See [SearchResponse](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/SearchResponse)
+and [SearchResult](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/SearchResult).
+
+No standalone answer API, chat sessions, ingestion, API-key search, service accounts,
+Workforce Identity Federation, per-user Google identity, widget or application
+login is implemented here. Disconnect removes the local grant; it does not call
+Google's revocation endpoint. Controlled fixtures cover protocol and file/UI
+behavior; real IAM, licenses, consent, source ACLs and search quality are untested.
+
+## Optional snippets and cited summaries
+
+The search operation now accepts the documented `contentSearchSpec` subset:
+
+```js
+const result = await connections.invoke({ context, integrationId: "enterprise-search",
+  operation: "search", input: { query: "How do I request leave?", pageSize: 10,
+    contentSearchSpec: {
+      snippetSpec: { returnSnippet: true },
+      summarySpec: { summaryResultCount: 3, includeCitations: true }
+    }
+  }
+});
+// Render result.summary.summaryText as escaped text/sanitized Markdown.
+// Keep the returned result order: Google's [1] citation refers to result 1.
+// Show summarySkippedReasons when no summary was generated.
+```
+
+Summary count is 1–10. Citation inclusion and filters for adversarial,
+non-summary and low-relevance queries default true for this option. Omitting
+`summarySpec` does not request generation; verification never requests it.
+The engine's Google project pays applicable search/generation costs. The app
+must authorize that use and source disclosure. A shared connection does not
+provide per-visitor source ACLs. Do not pass a visitor's email as an invented
+impersonation identity or assume administrator-visible documents are public.
+
+Snippets are in document-derived fields; preserve their status, source links
+and attribution. If Google cannot provide a snippet, display that absence.
+The app may instead send permitted snippets to its own chosen native AI
+library, with its own credentials and data-sharing policy. This connector
+neither chooses that library nor operates an inference gateway.
+
+Other frameworks POST the same JSON body to the region's Discovery Engine
+search endpoint using the application's stored OAuth grant. The administrator
+still owns ingestion, source permissions and licensing. JSKIT is optional.
+
+Checked against [Google ContentSearchSpec](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/ContentSearchSpec)
+on 13 September 2026. **LIMITATIONS:** no source provisioning, per-user source
+identity, standalone chat UI or editor assistant attachment. Example: an
+internal app can answer leave-policy questions with Google citations, but
+configuring it does not import company files or grant every employee access.
+Controlled fixtures prove request/response handling; real ACLs, licensing,
+relevance and summary quality remain untested.

package/docs/github-api.md

@@ -0,0 +1,133 @@
+# GitHub API
+
+Import `githubApiProvider` from `@jskit-ai/connectors-catalog/server/github-api`.
+This GitHub.com adapter supports personal access tokens (PAT) and an
+application-owned OAuth app. GitHub App installation tokens and Enterprise
+Server hosts are not implemented here. It does not replace the editor's repository login.
+
+## Set up access
+
+1. Open your GitHub **Settings → Developer settings → Personal access tokens →
+   Fine-grained tokens**.
+2. Choose **Generate new token**. Enter its name, expiration, and resource owner.
+3. Select the repositories the application needs. Metadata read access covers
+   the repository-list operation. Add Contents read for file/commit/release access, Actions read for workflow runs, Issues read/write and Pull requests read/write only as needed for the app operations.
+4. Complete any organization approval or account verification. A pending token
+   may identify its user without accessing the intended private repositories.
+5. Generate/copy the token, then keep it outside source as `GITHUB_API_KEY`.
+   Configure provider `github-api`, account mode `shared` or `assistant`, empty
+   `scopes`, and the `api-key` secret reference `env:GITHUB_API_KEY`.
+6. Call `connectApiKey`, then list repositories to check the intended access.
+   See [GitHub PAT management](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+## Runtime and AI composition
+
+`account.read` calls `GET /user`. `repositories.list` calls `GET /user/repos`
+with `per_page` (1–100, default 30), `page` (starting at 1), `sort` and `direction`.
+The caller advances the page number. The library returns the response array;
+it does not expose the HTTP Link header. A short page indicates completion;
+a full final page can be followed by an empty one.
+
+Requests use Bearer authentication, a User-Agent, GitHub's JSON media type and
+API version `2026-03-10`. See [Authenticated user](https://docs.github.com/en/rest/users/users#get-the-authenticated-user)
+and [Repositories](https://docs.github.com/en/rest/repos/repos#list-repositories-for-the-authenticated-user).
+Apply the [API-key source pattern](../patterns/api-key-connection/PATTERN.md)
+with this provider. The application supplies its own repository-access policy.
+
+## Provisioning automation and capacity
+
+An AI can prepare token settings and library configuration, then use approved
+API access. Ordinary PAT issuance remains a console action in this guide; no
+automated equivalent was verified. A GitHub App manifest is a different future
+registration flow and must not be described as an installed PAT feature.
+
+Two PATs issued by one user share relevant user limits. The application owner
+supplies its authorized PAT through private Env; separate tokens or application
+names do not create independent capacity. GitHub Apps are a separate option for
+installation-based distribution, requiring their own adapter and permissions.
+
+Tests use simulated API responses and real temporary runtime files to verify
+headers, paging, restart, rotation, disconnect and owner isolation.
+
+## OAuth setup
+
+Open GitHub Settings > Developer settings > OAuth Apps > New OAuth App. Set the
+name and application homepage, and copy Vibe64's Suggested callback URL into
+Authorization callback URL. Register the app, copy Client ID, and generate a
+client secret. Save configuration and follow the Env links for client secret
+and callback references. The application owns the callback route and grants.
+Use shared ownership for an administrator connection or per-user ownership for
+connections started inside each application's account screen. This connects API
+access; the framework still owns application login and account linking.
+
+The captured scope choices are available; request only required permissions.
+Optional offline_access requests expiring access with refresh credentials on
+GitHub.com. The adapter normalizes comma-separated returned scopes without
+changing authorization-request scope formatting. OAuth API requests retain the
+same GitHub headers as PAT requests. Disconnect is local; revoke authorization
+in GitHub separately. The app's OAuth registration, secret and provider quotas
+are not supplied by Vibe64.
+
+Focused OAuth fixtures cover confidential S256 exchange, cancellation,
+denial, replay, refresh rotation, file restart, PAT coexistence, per-user and
+application isolation, non-expiring grants and malformed scope responses.
+Controlled editor review covers OAuth/PAT switching, connection controls and
+the per-user setup boundary. No live GitHub consent or generated app was tested.
+
+## Repository and collaboration operations
+
+All targeted operations require `owner` and `repo`. The application authorizes
+these values against its allowed repositories before invoking the shared
+connection; a valid shared token alone must not authorize an arbitrary visitor.
+
+| Operation | Additional inputs and result |
+|---|---|
+| `repositories.get` | Repository metadata |
+| `branches.list`, `commits.list`, `releases.list` | `page`, `per_page`; arrays |
+| `workflows.runs` | Pagination; workflow_runs and total_count |
+| `contents.get` | Repository-relative `path`, optional branch/tag/commit `ref`; file envelope or directory entries |
+| `issues.list`, `pulls.list` | Pagination and open/closed/all `state` |
+| `issues.get`, `pulls.get` | `number`; full issue/PR including body/state |
+| `issues.comments`, `pulls.reviews` | `number` and pagination; comments/review states |
+| `issues.create` | `title`, optional `body`; created issue |
+| `issues.update`, `pulls.update` | `number` and at least one of title/body/state |
+| `pulls.create` | title/head/base, optional body/draft; created PR |
+
+Page size is 1–100, default 30. Follow pages until a short/empty result. GitHub's
+issue list also includes pull requests: filter entries with `pull_request` if
+the app wants issues only. PR head/base refer to existing branches; this does
+not create commits or synchronize code. Creation is not retried automatically
+on uncertain network outcomes; reconcile against the repository before retrying.
+
+Small file content is returned in GitHub's base64 envelope. Decode only when
+`encoding === "base64"`; large files may have unavailable content, and directory
+listing has provider limits. Do not blindly fetch a returned download URL with
+the account token. Display unavailable/large-file state or use the native GitHub
+file/media API with the correct resource policy. Never treat Markdown as trusted
+HTML. Review and workflow status are provider data, not proof it is safe to merge.
+
+```js
+const issue = await connections.invoke({ context, integrationId: "github",
+  operation: "issues.create", input: { owner: "my-org", repo: "feedback",
+    title: "Booking feedback", body: "The app-authorized feedback text" } });
+// Persist issue.number/html_url with the originating app record.
+```
+
+CLI users use the same JSON, Env and optional Node provider. Other frameworks
+use native HTTP with their OAuth grant/PAT against the documented
+[issues](https://docs.github.com/en/rest/issues/issues),
+[pulls](https://docs.github.com/en/rest/pulls/pulls),
+[contents](https://docs.github.com/en/rest/repos/contents) and
+[workflow runs](https://docs.github.com/en/rest/actions/workflow-runs) endpoints.
+OAuth `repo` covers private repository operations; `public_repo` can cover
+public-only writes. Fine-grained PAT permissions are configured in GitHub,
+not granted by an empty local scopes array. Account verification alone does
+not establish access to a selected repository.
+
+**LIMITATIONS:** no GitHub App installation flow, Enterprise Server API host,
+repository synchronization, automatic merges or editor assistant attachment.
+Example: the generated app can create a feedback issue and show PR review
+status; adding this connector does not sync the app's source or let the editor
+assistant inspect GitHub. Branch creation, file writes and workflow dispatch
+remain native app operations beyond this subset. Existing OAuth/PAT UI and
+private configuration are shared across these operations.

package/docs/gitlab-api.md

@@ -0,0 +1,138 @@
+# GitLab API
+
+Import `gitlabApiProvider` from `@jskit-ai/connectors-catalog/server/gitlab-api`.
+This fragment supports access tokens and confidential OAuth using a configured
+HTTPS GitLab origin (GitLab.com by default). CI job tokens, subpath installations
+and DPoP proof generation are not implemented. Configuration and connection
+screens were reviewed with simulated setup responses; no live GitLab access
+or generated application was used.
+
+## Configure an access token
+
+Set **Instance URL** to the HTTPS origin of the trusted GitLab server that issued
+the token; leave `https://gitlab.com` for GitLab.com. This destination receives
+the credential. Do not include a path, query, fragment or URL credentials.
+
+1. On that GitLab instance, open your avatar and choose **Edit profile**.
+2. Select **Access → Personal access tokens → Generate token → Legacy token**.
+3. Enter a name, optional description and expiration date. Select `read_api`
+   for projects and `read_user` for the profile verifier.
+4. Generate the token and copy it while visible. Save it in backend Env as
+   `GITLAB_API_KEY`.
+5. Save provider `gitlab-api`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication `{ "method": "api-key", "secretRef": "env:GITLAB_API_KEY" }`.
+6. Verify with `connectApiKey`. Rotate or revoke through the token list's menu;
+   update Env when rotating. [Token instructions](https://docs.gitlab.com/user/profile/personal_access_tokens/),
+   [scope meanings](https://docs.gitlab.com/security/tokens/access_token_scopes/).
+
+## Runtime and AI composition
+
+The API origin comes from `settings.instanceUrl`, defaulting to
+`https://gitlab.com`. Token requests use `PRIVATE-TOKEN`; OAuth uses Bearer.
+`profile.read` calls `/api/v4/user`. `projects.list` calls `/api/v4/projects`
+with `per_page` (1–100, default 20), `page` (starting at 1), and fixed true
+`membership` and `simple` flags. It returns a compact array of member projects.
+Continue numbered pages until a short/empty page. This fragment does not expose
+response pagination headers or support traversing beyond the provider's offset
+pagination ceiling. [Projects API](https://docs.gitlab.com/api/projects/).
+
+Compose the [API-key pattern](../patterns/api-key-connection/PATTERN.md); no
+Git repository clone or application generation is required. Files hold portable
+configuration and private runtime metadata separately.
+
+## Automation and application registrations
+
+An AI can prepare a token-creation URL with name, description and scopes already
+filled; the user still creates the personal token. GitLab documents administrator
+token provisioning for self-managed systems and separate service-account token
+APIs, but those privileges must not be inferred for ordinary GitLab.com users.
+The setup guide above links these supported alternatives.
+
+The application owner supplies its authorized personal key through private Env.
+Two keys owned by one user do not establish separate capacity. OAuth registration
+is another credential mode. Tests cover profile validation, restricted project
+queries, pagination, file persistence, rotation, isolation and provider errors.
+## Configure OAuth
+
+1. Set **Instance URL** to your trusted GitLab HTTPS origin. On that same
+   instance, open `/user_settings/applications` to register an application.
+2. Give it a recognizable name, keep **Confidential** selected, and register
+   the exact **Suggested callback URL** shown for this project. Choose
+   `read_user` and `read_api` for this fragment's profile and project reads.
+   [GitLab application registration](https://docs.gitlab.com/integration/oauth_provider/).
+3. Select **OAuth** in the connector form. Copy the registration's Application
+   ID into **Client ID**. Keep the secret and callback as Env references;
+   save configuration, then use **Set credential in Env** for the secret
+   and callback values. The callback value must equal the registered URL.
+4. Choose **One shared account** for a project business account, or
+   **Each app user's own account** when individuals authorize their own access.
+   Shared setup uses **Connect account** after the app backend is running.
+   Per-user setup requires the application's own authenticated connection screen;
+   the editor does not connect all users on their behalf.
+5. The app implements the callback with the shared
+   [OAuth connection pattern](../patterns/oauth-connection/PATTERN.md), binds it
+   to its authenticated user and completes the original attempt. Its backend
+   owns the tokens and refresh lifecycle. Laravel uses its own framework;
+   this JavaScript runtime does not introduce a Vibe64 dependency.
+6. Verify the profile. After changing the instance, client or callback,
+   reconnect. **Disconnect** removes the local connection; revoke the grant
+   in GitLab as well when provider-side revocation is intended.
+
+Refresh includes the original redirect URI and uses the shared runtime's token
+rotation. Changing `settings.instanceUrl` invalidates the existing connection
+before credentials can be sent to the new origin. OAuth grant handling is
+separate from the editor's Git repository authentication.
+
+## Project content and collaboration
+
+All targeted operations take `project`: a numeric ID as a string or full
+`group/subgroup/project` path. The entire path is URL-encoded as one project
+identifier. The app must authorize this target for its caller before using a
+shared connection. Item `iid` is the issue/MR's project-local number, not its
+global `id`.
+
+| Operation | Additional inputs |
+|---|---|
+| `projects.get` | None; full project metadata |
+| `branches.list`, `commits.list`, `pipelines.list` | `page`, `per_page` |
+| `files.get` | `filePath`, `ref` (branch/tag/commit); base64 file envelope |
+| `issues.list` | Pagination, opened/closed/all `state`, optional `search` |
+| `mergeRequests.list` | Pagination, opened/closed/merged/all `state` |
+| `issues.get`, `mergeRequests.get` | `iid`; full content |
+| `issues.notes`, `mergeRequests.notes` | `iid` and pagination; comments |
+| `issues.create` | `title`, optional `description` |
+| `mergeRequests.create` | `title`, `source_branch`, `target_branch`, optional `description` |
+| `issues.update`, `mergeRequests.update` | `iid`, at least one title/description/state_event (close/reopen) |
+
+Reads use `read_api` and profile verification `read_user`. **Writes need `api`
+and the appropriate project role**. Select that scope in OAuth and reconnect;
+for a token, issue the appropriate token in GitLab and update private Env.
+Local configuration cannot expand a token's provider permissions. No operation
+writes during verification. Existing source/target branches are required for
+MR creation; this connector does not create commits, merge or run pipelines.
+
+```js
+const issue = await connections.invoke({ context, integrationId: "gitlab",
+  operation: "issues.create", input: { project: "team/feedback",
+    title: "Booking feedback", description: "App-authorized feedback" } });
+// Store issue.iid and web_url against the initiating app record.
+```
+
+Page size defaults to 20 and is bounded to 100. Continue until a short/empty
+page, respecting the instance's offset limits. Decode files only with a supported
+encoding and handle provider size limits. Treat Markdown as untrusted content.
+A write may succeed before a network failure: no automatic replay occurs;
+reconcile with the project's issue/MR list before retrying.
+
+CLI users use the same configuration and Env with the optional Node runtime.
+Other frameworks use native HTTP and their own grants against GitLab's
+[issues](https://docs.gitlab.com/api/issues/),
+[merge requests](https://docs.gitlab.com/api/merge_requests/) and
+[repository files](https://docs.gitlab.com/api/repository_files/) APIs.
+
+**LIMITATIONS:** no source synchronization, automatic merges, pipeline execution,
+file writes or editor assistant attachment. CI tokens, DPoP and subpath instances
+remain unsupported. Example: an app can create feedback issues and show MR
+comments and pipeline status; it does not push its own code or start CI jobs.
+Controlled tests cover content, writes and OAuth/token lifecycle; live GitLab
+and generated-app execution remain untested.