@jskit-ai/connectors-catalog 0.1.1

package/docs/linear.md

@@ -0,0 +1,137 @@
+# Linear
+
+Import `linearProvider` from `@jskit-ai/connectors-catalog/server/linear`.
+This adapter supports a personal API key or project-owned OAuth, with GraphQL reads and Linear MCP tools. Vibe64 edits the project configuration; the generated application owns its runtime and credentials.
+
+## Configure access
+
+1. Select the intended Linear workspace and open **Settings → Account → Security & Access**.
+2. In the personal API-key section, create a key with a descriptive application
+   name. Choose read access and the teams the application needs where these
+   controls are offered.
+3. Enter `env:LINEAR_API_KEY` in API key reference, **Save configuration**, then choose **Set credential in Env** and store the key as `LINEAR_API_KEY`. Return to connect.
+4. Save provider `linear`, mode `shared` or `assistant`, `scopes: ["read"]`, and
+   authentication `{ "method": "api-key", "secretRef": "env:LINEAR_API_KEY" }`.
+5. Call `connectApiKey` to verify the viewer; manage/revoke the key in the same
+   settings section. [Authentication guide](https://linear.app/developers/graphql).
+
+## Runtime and CLI composition
+
+The API is `POST https://api.linear.app/graphql`. Personal keys use the raw
+`Authorization` header, without the OAuth Bearer prefix. `profile.read` selects
+`viewer { id name email }`. `issues.list` accepts `first` (1–100, default 50;
+100 is this fragment's cap) and optional `after`; it returns issue IDs,
+identifiers, titles and `pageInfo`. Continue using `endCursor` only while
+`hasNextPage` is true. [Pagination](https://linear.app/developers/pagination).
+
+Both queries are fixed in the provider module. Input values become GraphQL
+variables, never interpolated query text. Responses with GraphQL errors are
+rejected even when HTTP status is 200 and partial data exists. The application
+must not display that partial data as a successful result.
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md). It leaves
+application authorization with the caller and persists connection state in files.
+
+## Automation and application registrations
+
+Personal key creation uses the interactive settings flow. For OAuth applications,
+Linear supports a JSON application manifest: an AI can fill display information,
+callback URLs and other supported configuration, then prepopulate the app-creation
+page. A person still reviews and creates the application's own registration.
+No unverified unattended registration API is assumed. [Application manifests](https://linear.app/developers/oauth-app-manifests).
+
+Distinct
+names/keys alone do not establish independent organization/user rate limits.
+The application owner supplies the key and controls access to its organization.
+Tests cover fixed queries, variables, pagination, partial errors, persistent
+state, credential changes and isolation without live issue access.
+
+## Project-owned OAuth
+
+1. As a workspace administrator, open **Settings → Administration → API** and
+   create an OAuth application. The direct creation page is
+   <https://linear.app/settings/api/applications/new>. Register the exact
+   **Suggested callback URL** from this project's integration screen.
+2. Copy its Client ID into the form. Save configuration and use the Env links to
+   store `LINEAR_CLIENT_SECRET` and `LINEAR_CALLBACK_URL`. Registering the URL
+   does not implement the application's callback handler.
+3. Keep `read` selected; choose additional permissions only for required features.
+   This adapter uses `actor=user`, including in assistant mode. Service-account
+   actors and client-credentials grants are outside this adapter's flow.
+4. Shared/assistant connections start with **Connect account**. Per-user
+   connections start in the generated application's authenticated account screen.
+   The framework owns login and callback routing; JSKIT supplies the JavaScript
+   lifecycle library. Other frameworks use their own OAuth implementation.
+5. Approve the intended workspace. Verification reads the viewer. Cancel a pending
+   attempt locally if you abandon consent; reconnect starts a new attempt.
+6. Disconnect clears the local grant. For remote revocation, open **Settings →
+   Account → Security & Access → Authorized applications**, hover the application
+   and choose **Revoke access**. Another workspace uses another connection.
+
+Authorization uses comma-separated scopes, S256 PKCE and a project-owned secret
+posted to Linear's token endpoint. Returned space-separated permissions (or
+Linear's documented array form) are normalized before the shared lifecycle stores
+and enforces them. Refresh tokens rotate and remain in the application's encrypted
+connection store. Client secrets and grants are never stored in source.
+[OAuth protocol](https://linear.app/developers/oauth-2-0-authentication),
+[account access controls](https://linear.app/docs/security-and-access).
+
+Use the [OAuth pattern](../patterns/oauth-connection/PATTERN.md), with registration
+`source: "own"`, `tokenEndpointAuthMethod: "client_secret_post"`, the Client ID and
+Env references above. Use provider `linear`, a registration reference in
+`authentication`, and `scopes: ["read"]`. `beginAuthorization`,
+`completeAuthorization`, `invoke`, and `disconnect` retain the same ownership
+contract as other OAuth connectors.
+
+## MCP with the same connection
+
+`tools.list` and `tools.call` use the fixed Streamable HTTP endpoint
+`https://mcp.linear.app/mcp`. Linear explicitly supports reusing an API key or an
+existing Linear OAuth grant for this endpoint, so this path needs no additional
+MCP registration. The adapter supplies raw key authorization to GraphQL and Bearer
+authorization to MCP; OAuth uses Bearer for both. The captured Lovable interactive
+MCP registration flow is a different registration path, not required for this
+project-owned connection. The deprecated `/sse` endpoint is not used.
+
+Tool calls may write when the provider grant allows it. The application must
+approve/authorize the named operation and its arguments; `read` alone cannot
+permit writes at Linear. Discovery does not execute tools. Use `tools.list` to
+obtain available schemas rather than maintaining a second catalogue here.
+[Linear MCP authentication](https://linear.app/docs/mcp).
+
+## Review evidence
+
+The focused fixture tests cover OAuth authorization, cancellation/denial, replay,
+refresh rotation after restart, app/user isolation, lost scopes, raw API-key
+GraphQL authorization and Bearer MCP discovery. No real Linear account, issue,
+consent or tool execution was used. Both credential modes passed a controlled public-editor browser review: configuration survives reload, Env links and provider guides resolve to the intended destinations, and simulated connection controls work. The 496px instruction captures were visually inspected; no live provider consent or fresh phone review is claimed.
+
+## Approved project and issue workflows
+
+The existing MCP transport can discover and invoke the provider's project/issue
+tools with either connection method. Discover `tools.list` (including returned
+cursors), inspect each current input schema, then authorize the tool name and
+arguments against the requesting app user and selected team/project. Supply write
+permissions only when needed. Do not copy fixture tool names into application code.
+
+```js
+const result = await connections.invoke({
+  context: authorizedContext, integrationId: "linear", operation: "tools.call",
+  input: { name: approvedTool.name, arguments: approvedTool.arguments }
+});
+if (result.isError) throw new Error("Linear did not complete the requested action.");
+```
+
+`connections`, authenticated context and `approvedTool` are app-owned composition,
+not exported globals. Use the returned project identifier when creating its issue;
+use the returned issue identifier when updating it. The authorization callback
+must enforce the exact target and write approval before transport. Never blindly
+retry an uncertain create. CLI apps use the same library/configuration/Env; other
+frameworks compose their native MCP client and authorization with those values.
+
+**LIMITATIONS:** No maintained tool catalogue, project-management UI or automatic
+Vibe64 Codex/OpenCode attachment. Example: an app can explicitly run an approved
+issue update, but saving a Linear connection alone does not teach Vibe64's coding
+chat to update that issue. Provider permissions and available tools determine what
+can run. Fixture workflows prove argument/result transport and local denial, not
+actual Linear tool schemas or live execution.

package/docs/linkedin.md

@@ -0,0 +1,196 @@
+# LinkedIn
+
+Import `linkedinProvider` from `@jskit-ai/connectors-catalog/server/linkedin`.
+This adapter reads the connected member's profile through `profile.read` and publishes approved text with `posts.create`.
+Configuration preserves `openid`, `profile`, `email` and `w_member_social`.
+Only OpenID and profile are required and selected by default. Publishing requires the Share on LinkedIn product and a grant with `w_member_social`.
+
+## Register and configure
+
+1. Sign into [LinkedIn Developers](https://www.linkedin.com/developers/apps).
+   Choose **My apps → Create app**. Supply the requested name, LinkedIn Page,
+   privacy-policy URL and logo; complete Page-owner verification when prompted.
+2. Open **Products** and request **Sign In with LinkedIn using OpenID Connect**.
+   Once approved, check **Auth** for `openid`, `profile` and `email`.
+   Email fields may be absent even when profile retrieval succeeds.
+   [Product and profile documentation](https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin-v2).
+3. Open **Auth → OAuth 2.0 settings → Authorized redirect URLs** and add the
+   project's exact **Suggested callback URL**, using HTTPS. Copy **Client ID** into the configuration.
+   Save **Client Secret** only in backend Env as `LINKEDIN_CLIENT_SECRET`.
+   Set `LINKEDIN_CALLBACK_URL` to the registered URL without query or fragment.
+   [Confidential authorization flow](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow).
+4. For text publishing, request **Share on LinkedIn** under Products and
+   confirm `w_member_social` is provisioned in Auth before selecting it.
+   [Share product](https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/share-on-linkedin).
+5. In Vibe64 choose **Add LinkedIn**, enter display name, ownership, Client ID
+   and the two Env references. Open **Permissions** for optional email/publishing.
+   Choose **Save configuration**, then **Set credential in Env** to store the
+   Client Secret. Use **Open Env** to set the same registered callback. Return
+   and choose **Connect account** for shared/assistant access. Each-user access
+   starts in the generated application's authenticated account screen. Its
+   backend must implement the callback; saving fields does not create that route
+   or complete provider consent.
+
+```json
+{
+  "schemaVersion": 1,
+  "integrations": {
+    "linkedin": {
+      "provider": "linkedin",
+      "displayName": "My LinkedIn profile",
+      "accountMode": "per-user",
+      "scopes": ["openid", "profile"],
+      "authentication": { "method": "oauth2", "registrationRef": "linkedin" }
+    }
+  },
+  "registrations": {
+    "linkedin": {
+      "source": "own",
+      "clientId": "YOUR_LINKEDIN_CLIENT_ID",
+      "clientSecretRef": "env:LINKEDIN_CLIENT_SECRET",
+      "callbackUrlRef": "env:LINKEDIN_CALLBACK_URL"
+    }
+  }
+}
+```
+
+## Runtime and AI composition
+
+Use the [OAuth file composition pattern](../patterns/oauth-connection/PATTERN.md)
+with `providers: [linkedinProvider]` and this JSON. Core owns configuration,
+Env resolution, consent attempts, encrypted file storage, refresh and disconnect.
+No generator or editor database is needed.
+
+```js
+import { readFile } from "node:fs/promises";
+import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
+import { createConnectionService, createEnvironmentReferenceResolver } from "@jskit-ai/connectors-core/server";
+import { createFileConnectionStore, createCredentialProtection } from "@jskit-ai/connectors-core/server/file-storage";
+import { linkedinProvider } from "@jskit-ai/connectors-catalog/server/linkedin";
+
+const providers = [linkedinProvider];
+const configuration = parseIntegrationConfiguration(await readFile("integrations.json", "utf8"), { providers });
+const protection = createCredentialProtection({
+  keys: { current: Buffer.from(process.env.CONNECTOR_STORAGE_KEY, "base64") }, activeKeyId: "current"
+});
+const connections = createConnectionService({
+  configuration, providers,
+  store: createFileConnectionStore({ directory: process.env.CONNECTOR_STATE_DIRECTORY, protection }),
+  resolveReference: createEnvironmentReferenceResolver(), authorize: applicationConnectionPolicy
+});
+```
+
+`applicationConnectionPolicy` derives `{ applicationId, subjectId }` from
+trusted app authentication or a CLI operator and checks each requested operation.
+Per-user mode keeps individual grants; shared mode needs a stable shared subject
+and membership checks. Assistant mode requires explicit host authorization too.
+Keep runtime files outside exported source and preserve the encryption key
+across restarts. No client secret or provider token belongs in project JSON.
+
+Call `beginAuthorization({ context, integrationId: "linkedin" })` and open the
+returned URL. Recover the same authenticated owner in the callback, then call
+`completeAuthorization({ context, integrationId: "linkedin", callbackUrl })`.
+Success includes a read-only profile check. Later call
+`invoke({ context, integrationId: "linkedin", operation: "profile.read" })`.
+The operation accepts no input and calls only
+`GET https://api.linkedin.com/v2/userinfo`. It requires a nonempty `sub` and
+accepts absent optional name/email fields. Do not infer a missing email or
+fetch picture URLs automatically.
+
+`cancelAuthorization` abandons a pending attempt; failed replacement consent
+preserves the old grant. `disconnect` removes local access and attempts, not
+provider-wide consent. For provider revocation, open **Me → Settings & Privacy → Data privacy → Other
+applications → Permitted services**, choose **Change**, then **Remove** beside
+the application. [LinkedIn's access-removal instructions](https://www.linkedin.com/help/linkedin/answer/a522690/log-in-with-linkedin-credentials?lang=en).
+
+The provider normalizes the documented omission of `token_type` to Bearer.
+It discards ID tokens and never uses them as proof of application login.
+The host's existing identity implementation remains responsible for login.
+Core sends state and S256 PKCE parameters with confidential Web OAuth; the Web
+flow documentation does not establish PKCE enforcement. LinkedIn's separate
+native flow needs enablement and a loopback callback. It is not implemented
+here; never embed a client secret in an installed editor or browser. CLI users
+can compose the same server runtime with their registered callback owner.
+[Native flow](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow-native).
+
+## Expiry, failures and verification
+
+Ordinary grants may have no refresh token. Expiry then requires reconnect.
+If LinkedIn enables programmatic refresh and supplies a refresh token, core
+serializes refresh under the file lock and retains rotation. Reduced permissions
+never expand during refresh. Approval is provider-controlled; refresh expiry
+or revocation can still require consent again.
+[Refresh availability and protocol](https://learn.microsoft.com/en-us/linkedin/shared/authentication/programmatic-refresh-tokens).
+
+Missing required permissions, invalid responses and failed profile checks prevent
+Connected. API 401 requires reconnect; 403 means permission denied; 429 means
+rate limited. Errors omit provider text. Changing the OAuth client ID invalidates
+access through the previous client. Requests are bounded and cancellable.
+Organization access, analytics and application login are outside this adapter. Focused tests use controlled HTTP and encrypted temporary files,
+including this exact JSON. Editor checks use file-backed browser fixtures.
+No live consent, provider token issuance or generated application is proven.
+
+## Automation and application registrations
+
+An AI can prepare JSON, Env names, callback handlers and runtime wiring. This
+pass established no supported public API for creating developer apps or granting
+product access. Registration, Page verification and approval remain operator
+steps. Do not promise unattended provisioning from a client ID alone.
+
+Each application owns its provider registration, callback route, credentials
+and grants. Hosted and installed editors configure the same app-owned setup;
+neither supplies a shared Vibe64 registration or token gateway. Use the app's
+assigned public URL as the initial callback origin, append the route the backend
+actually implements, and register the exact URL with the provider. Keep the
+client secret and callback binding in the application's Env.
+
+A custom-domain or hosting move that changes the callback requires updating both
+the provider registration and the app's Env. Preserve the application's identity
+and private connection store, validate callback state and initiator, and allow
+only application-approved return destinations. The editor's address is not the
+provider callback. See the [callback contract](../../connectors-core/docs/oauth-callbacks.md)
+and [setup command](../../connectors-core/docs/setup-command.md).
+
+Separate client IDs do not establish independent quotas or permission to serve
+unrelated applications. Register and obtain product approval for the actual app.
+Managed assignments are invalid configuration in this runtime.
+
+
+## Credential guidance review (2026-09-12)
+
+The inline setup steps now name the developer portal, product approval, exact
+callback registration and project Env handoff before connection. Current OIDC,
+authorization-code and refresh documentation were checked. The existing adapter
+was retained; no provider-login or publishing implementation was added. Ten
+focused runtime fixtures pass, including expiry without refresh, approved
+refresh, cancellation/replay, encryption, missing permissions and host isolation.
+The cancellation test now expects the callback URL exposed by connection status,
+while retaining the complete assertion that declined replacement consent keeps
+the previous grant. Rendered guidance passed the controlled public-editor journey: saved Client ID/callback, Env links, reload, simulated consent/cancellation/reconnect and disconnect. All six steps were visually reviewed at 496px width. No live provider consent or fresh phone review is claimed.
+
+## Text publishing acceptance — 2026-09-13
+
+Use `posts.create` with `{ text, visibility: "PUBLIC" }` or `"CONNECTIONS"` after
+app authorization of the exact message and audience. Text is locally limited to
+1–3000 characters. The operation reads the connected member identity, constructs
+the Person URN itself and posts once to `/v2/ugcPosts`. Callers cannot choose a
+different author. The result contains the post URN from the confirmed 201 response.
+[Provider sharing contract](https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/share-on-linkedin).
+
+```js
+const post = await connections.invoke({ context: authorizedContext,
+  integrationId: "linkedin", operation: "posts.create",
+  input: { text: approvedText, visibility: approvedVisibility } });
+```
+
+The app supplies these variables and its approval policy. CLI uses the same config,
+Env and library; other frameworks can implement the same provider request with
+their native HTTP/OAuth tools. Add the provider product, select Publish posts in
+configuration and reconnect before invoking it. No publishing occurs during
+connection verification. Check LinkedIn before manually repeating an uncertain
+request; a timeout does not prove the post was never created.
+
+**LIMITATIONS:** Text only. No images/video, organization posts, scheduling, post
+editing/deletion, analytics or editor-assistant attachment. Example: publish an
+approved announcement, but not a photo campaign. Prior September12 review above
+is historical. Current tests use simulated provider responses, not live publishing.

package/docs/logo-dev.md

@@ -0,0 +1,152 @@
+# Logo.dev
+
+Import `createLogoDevImageUrl` from
+`@jskit-ai/connectors-catalog/client/logo-dev`. This is a library implementation
+for public image URLs, usable in a browser or Node process. The shared catalogue
+exports `logoDevDefinition` for configuration and UI metadata.
+
+## Manual provider setup
+
+1. Sign into [Logo.dev API Keys](https://www.logo.dev/dashboard/api-keys).
+   Copy the publishable `pk_` key.
+2. In Vibe64, add Logo.dev and enter `env:LOGO_DEV_PUBLISHABLE_KEY` in
+   **Publishable key reference**. Choose **Save configuration**, then **Set
+   credential in Env**, and store the actual `pk_` value as
+   `LOGO_DEV_PUBLISHABLE_KEY`. Return after saving Env. The application resolves
+   that one reference for its image rendering code.
+3. For restrictions, turn on **Allowed Domains Only**, enter the domains that
+   load images, one per line, then choose **Save Changes**.
+4. Ensure image requests send an origin referrer. Include development/preview
+   domains deliberately; restrictions also reject requests without a referrer.
+5. Save the source configuration. Key rotation is documented as a support
+   request; replace the environment binding after obtaining the new key.
+
+Publishable keys work on the image CDN. Private `sk_` keys belong to other APIs
+and must not appear in browser image URLs.
+[Key types, restrictions and rotation](https://www.logo.dev/docs/platform/api-keys).
+
+## Portable source and library usage
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "logos": {
+      "provider": "logo-dev",
+      "displayName": "Company logos",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": { "method": "api-key", "secretRef": "env:LOGO_DEV_PUBLISHABLE_KEY" }
+    }
+  }
+}
+```
+
+An application build step, backend or CLI resolves this one configured reference
+using its environment resolver. It then deliberately publishes the `pk_` value
+as browser configuration or includes it in a returned image URL. Keep the
+portable source file reference-only, exactly as the editor writes it. Do not
+dump the environment or substitute a private key.
+
+```js
+import { createLogoDevImageUrl } from "@jskit-ai/connectors-catalog/client/logo-dev";
+
+const imageUrl = createLogoDevImageUrl({
+  publishableKey: publicConfiguration.logoDevKey,
+  domain: "example.com",
+  size: 128,
+  theme: "dark",
+  fallback: "404"
+});
+```
+
+Assign this URL to an image element's `src`, supply meaningful `alt` text and
+an origin-compatible referrer policy, and handle its `error` event with the
+application's own fallback. `createLogoDevImageUrl` performs no HTTP request,
+records no grant and cannot establish Connected. Its metadata explicitly marks
+the runtime as `public-resource`; use the
+[public-image source pattern](../patterns/public-image/PATTERN.md), not the
+server connection-verification API. The browser's load/error events provide
+delivery evidence. They are distinct from saving configuration.
+
+The library validates an ASCII domain (including punycode), the publishable-key
+prefix and image options, then returns a URL on `https://img.logo.dev`. It rejects
+caller destinations, private keys, path/query injection and unsupported fields.
+Inputs are not mutated. Local defaults are size 128, PNG, automatic theme,
+greyscale off, retina off and monogram fallback. Options include JPG/WebP/SVG,
+light/dark/auto themes, sizes 1–800, retina, greyscale and `404` fallback.
+SVG availability depends on the provider plan; URL construction does not
+confirm that entitlement. Width/height overrides, brand-name and crypto lookups are outside this function.
+[Image parameters](https://www.logo.dev/docs/logo-images/get).
+
+The provider can return a monogram with HTTP 200 when a brand logo is missing.
+Use `fallback: "404"` when the application needs to distinguish missing images.
+A URL or successful image load does not prove that a specific brand logo exists.
+[Missing-logo behavior](https://www.logo.dev/docs/logo-images/introduction).
+
+The key is intentionally visible in image requests. Apply the provider's
+attribution and usage requirements in the product; the URL helper does not add
+attribution or authorize image redistribution.
+[Attribution](https://www.logo.dev/docs/platform/attribution),
+[usage policy](https://www.logo.dev/docs/platform/fair-use).
+
+## API provisioning and application ownership
+
+No public account/key provisioning API was verified in the linked documentation.
+An AI can prepare source configuration, rendering and domain instructions;
+dashboard access and support-assisted rotation remain operator work. Do not
+guess internal dashboard endpoints or use a secret key to make the image flow
+look like an authenticated JSON service.
+
+The application owner supplies its provider key and arranges the capacity it
+needs. Configuration labels do not create independent quotas. Customer-owned
+keys remain owned by the customer when exporting or moving an app. This image
+flow creates no OAuth app, user login or per-user mailbox-style grant.
+
+Allowed domains should identify the actual browser app: for example, its
+hosting subdomain, custom domain and intended preview origin. The editor's VM
+domain matters only if it itself loads the images. That differs from an OAuth
+redirect allowlist. Changing application domains can require provider-side
+restriction updates even though the portable reference is unchanged.
+
+## Focused evidence
+
+Node tests cover options, encoding boundaries, private-key rejection, portable
+configuration and the absence of false server verification. The ordinary
+source pattern is checked with a supplied resolver. Editor/browser tests cover
+save/reload, reference validation, actual image loading from a simulated CDN
+and a simulated missing-image failure. No live provider use or generated sample
+application is needed.
+
+
+## Credential guidance review (2026-09-12)
+
+Current provider key and image documentation were checked against the captured
+publishable-key field. The inline instructions now give the direct dashboard
+URL, exact reference and Env handoff, public/private distinction, domain patterns,
+referrer behavior and support-assisted rotation. The existing image library and
+public-image composition pattern remain the owners of URL generation and wiring.
+The first rendered review exposed an account-connect button because the editor
+consumes configurationOnly metadata rather than runtimeKind. Logo.dev now sets
+that existing flag: the editor omits account controls and the server refuses
+setup commands before Env preparation or application execution. Two targeted
+public-editor tests cover this rule for Logo.dev and Google Analytics.
+All four focused library tests passed, including private-key rejection, fixed-origin URL
+construction, portable configuration and selective reference resolution. Rendered guidance and simulated image delivery passed: the actual editor persists the reference through reload, links to Env and the provider guide, and offers no account-connect controls. Browser image load/error and origin-referrer behavior were checked with a simulated CDN. All five steps were visually reviewed at 496px width; no live provider or generated-app claim.
+
+## Lookup coverage — 2026-09-13
+
+Supply exactly one of `domain`, `ticker` or `email` to the same URL helper.
+`{ ticker: "SHEL.L" }` uses the provider's ticker endpoint with an exchange suffix;
+`{ email: "person@example.com" }` extracts `example.com` locally and uses domain
+lookup. The personal part of the email never enters the URL. These are ordinary
+per-image application inputs, not project credential settings. The same source
+pattern resolves the publishable key; other frameworks can construct equivalent
+URLs without a Node runtime or Vibe64 service.
+[Ticker endpoint](https://www.logo.dev/docs/logo-images/ticker).
+
+**LIMITATIONS:** No private brand search/enrichment, crypto or ISIN lookup, avatar
+identification or automatic attribution badge. Example: an address at gmail.com
+returns the email provider logo, not the person's business. Apply plan attribution
+in the app and distinguish image success from real brand-logo availability.

package/docs/mailgun.md

@@ -0,0 +1,153 @@
+# Mailgun
+
+Import `mailgunProvider` from `@jskit-ai/connectors-catalog/server/mailgun`.
+The adapter verifies an account API key, sends transactional messages, creates
+and verifies sending domains, returns their DNS records, and queries delivery logs.
+DNS records are installed at the domain owner’s DNS host, not at Vibe64.
+
+## Configure access
+
+1. Sign into the intended Mailgun account as an administrator. Open the profile
+   menu at the top right, then **API Security → Add new key**.
+2. Enter a description and select **Developer** for sending and domain management. Select **Analyst**
+   only for a deliberately read-only connection. Click **Create Key** and copy the secret while it is visible.
+   Free/Basic accounts expose Admin only; that restriction comes from Mailgun.
+   Existing key roles cannot be edited: create a replacement to change roles.
+   [Key roles and dashboard steps](https://help.mailgun.com/hc/en-us/articles/26016288026907-API-Key-Roles).
+3. Enter `env:MAILGUN_API_KEY` in **API key reference**. Domain Sending
+   Keys and SMTP passwords do not provide this account domain-listing access.
+   [Credential types](https://help.mailgun.com/hc/en-us/articles/203380100-Where-can-I-find-my-API-keys-and-SMTP-credentials).
+4. Save provider `mailgun`, mode `shared` or `assistant`, `scopes: []`, and
+   authentication `{ "method": "api-key", "secretRef": "env:MAILGUN_API_KEY" }`.
+   Choose `settings.region: "us"` (default) or `"eu"`, corresponding to the
+   intended domains. The editor calls this **API region**.
+5. Choose **Save configuration**, then **Set credential in Env**. Store the real
+   account key as `MAILGUN_API_KEY`, return, and choose **Connect account**.
+   CLI apps call `connectApiKey`. Requests use HTTP Basic authentication with username
+   `api` and the resolved key as password. US requests go to
+   `https://api.mailgun.net`; EU requests go to `https://api.eu.mailgun.net`.
+   Changing region requires verification again.
+   [Authentication](https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/).
+
+## Runtime and AI composition
+
+`domains.list` reads `GET /v4/domains`. It accepts `limit` (1–1000, default
+100), `skip` (default 0), optional `state` (`active`, `unverified`, `disabled`),
+`sort` (`name`, `name:asc`, `name:desc`), `search`, and `include_subaccounts`
+(default false). Results contain `items` and `total_count`. Advance `skip` by
+the number of received items to retrieve another page.
+[Domain listing](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domains/get-v4-domains).
+
+Use the [API-key pattern](../patterns/api-key-connection/PATTERN.md) with the file
+store. Application code can use the operations below with the same configured connection. Local disconnect does not revoke the account key. Replace
+the Env value when rotating credentials, and delete obsolete keys in Mailgun.
+Tests cover both regional origins, HTTP Basic headers, pagination, re-verification,
+file restart and rejected responses without accessing a real mailbox or account.
+
+## Automation and application ownership
+
+After administrator credential bootstrap, an AI can automate key creation
+through `POST /v1/keys` using multipart form fields: `kind=user`, a required
+`role` (`basic` is the API value for Analyst), a `description`, and optionally
+positive `expiration` seconds. Persist the returned `key.secret` directly in
+secret storage. The runtime fragment does not expose this administrative
+operation. [Key creation API](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/keys/post-v1-keys).
+
+Each application supplies credentials for its intended Mailgun account. Keys
+within one account may share capacity and billing. The application operator
+owns account selection and budgets; key names alone do not isolate quotas.
+
+
+## Credential guidance review (2026-09-12)
+
+Current provider key-role, credential-type and domain-list documentation were
+checked against the captured private key and US/EU fields. Inline setup now
+explains the exact dashboard flow, admin requirement, Analyst where available,
+one-time secret display, account-key distinction, region and named Env handoff.
+Verification remains a domain-list read; it sends no email and changes no DNS.
+Three focused test cases passed (1.15s), including the shared regional-destination
+regression: changing region requires verification before credentials reach the
+new allowed origin. No runtime change was needed. The controlled browser review passed: the EU region and MAILGUN_API_KEY reference persist after reload, Env and provider guide links are present, and simulated connect/verify/disconnect work. All six steps were visually inspected at 496px width. No live account, email sending or generated application was exercised.
+
+## Sending and domain setup
+
+1. In Mailgun, open **Send → Sending → Domains → Add new domain**. Enter a
+   domain you control, commonly a dedicated subdomain such as `mail.example.com`,
+   and select its region. Alternatively call `domains.create` with `{ domain }`.
+2. Open the domain's **Domain Verification & DNS** page. At your DNS host, add
+   the exact sending records shown by Mailgun. `domains.get` returns the same
+   sending/receiving record sets for application-owned setup screens. Do not
+   invent SPF/DKIM values. Some hosts append your root domain automatically.
+   Receiving MX records are separate from outbound sending: do not replace
+   existing business-mail MX records just to send through Mailgun.
+3. Check DNS status in Mailgun or call `domains.verify` with `{ domain }`.
+   A successful HTTP response can still contain `domain.state: "unverified"`;
+   display each DNS record's status and allow the operator to retry after DNS
+   propagation. A successful key check alone does not prove DNS readiness.
+4. Choose a sender address at that domain in your application's mail settings.
+   Keep recipient selection behind the application's authorization/business rules.
+   Sandbox domains can send only to authorized recipients; use a verified custom
+   domain for production.
+
+[Domain setup](https://documentation.mailgun.com/docs/mailgun/user-manual/domains/domains-custom)
+[DNS verification](https://documentation.mailgun.com/docs/mailgun/user-manual/domains/domains-verify)
+[Domain API](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domains)
+
+The runtime operations accept `{ domain }` for `domains.create`, `domains.get`,
+and `domains.verify`. Creation and verification are explicit mutations; connecting
+never performs them. Developer keys support these operations; Analyst keys do not.
+[Current role matrix](https://documentation.mailgun.com/docs/mailgun/user-manual/api-key-mgmt/rbac-mgmt).
+
+```js
+const queued = await connections.invoke({
+  context, integrationId: "mail", operation: "messages.send",
+  input: {
+    domain: "mail.example.com", from: "Support <support@mail.example.com>",
+    to: ["customer@example.com"], subject: "Your receipt",
+    text: "Thank you for your purchase.", html: "<p>Thank you for your purchase.</p>"
+  }
+});
+```
+
+`messages.send` requires `domain`, `from`, `to`, `subject`, and plain `text`;
+HTML is optional. It sends multipart data to the configured US/EU region and
+returns Mailgun's queued message ID. It does not claim inbox delivery. This
+operation does not support attachments or templates yet. A timeout after sending
+has an uncertain outcome: do not blindly retry or fabricate an idempotency header.
+Keep the queued ID with your application's delivery record when available.
+[Send API](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/messages/post-v3--domain-name--messages).
+
+## Delivery logs and failures
+
+Call `logs.list` with `{ domain, duration: "1d", limit: 50 }`. It queries the
+current `/v1/analytics/logs` API (the older Events API is deprecated). Results
+preserve event type, recipient, severity and delivery status. Pass the returned
+`pagination.next` as `token` to fetch another page. For stable traversal, supply
+an RFC 2822 `end` timestamp on the first request and reuse it for subsequent
+pages. Poll with a bounded schedule owned by your app; retain event IDs to avoid
+processing overlapping results twice. The domain filter is mandatory and
+subaccount aggregation is disabled. A sending key is not sufficient for this
+account-level connector; it requires an account API key.
+
+A queued/accepted event differs from delivered; a temporary failure differs from
+a permanent rejection. Surface the provider's status instead of marking every
+queued message delivered. Log retention and available results depend on the
+Mailgun account. No automatic resend is performed. HTTP 401 requires reconnecting
+with corrected credentials; HTTP 429 should be surfaced for application-managed
+backoff. [Logs API](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/logs).
+
+## Repair proof and remaining acceptance
+
+`test/mailgun.test.js` exercises the actual connection service with controlled HTTP:
+US/EU multipart sends, repeated recipients, domain creation/read/verification,
+DNS status preservation, delivery failures, pagination, app isolation, denied
+operations, invalid inputs, 401/429 and uncertain writes. Three tests pass.
+No Mailgun account or actual email delivery was used. The inline credential guide
+must be reviewed in the public editor before provider acceptance is closed.
+
+**LIMITATIONS:** No attachments, stored templates, campaign/mailing-list UI, inbound
+routes, webhook receiver or editor-assistant attachment. Example: send and track
+a receipt email, but not attach its PDF through this adapter. Application-native
+mail settings/business rules own sender and recipient authorization, content,
+polling and duplicate prevention. CLI apps use the same configuration and Env;
+other frameworks compose these requests with their own HTTP/mail tools.