@jskit-ai/connectors-catalog 0.1.1

package/docs/salesforce.md

@@ -0,0 +1,234 @@
+# Salesforce
+
+Use `salesforceProvider` from `@jskit-ai/connectors-catalog/server/salesforce`.
+This initial library connects an org through an own confidential OAuth web
+registration, verifies API access and exposes object metadata and SOQL reads.
+It uses Salesforce REST API v66.0. CLI and editor configuration share one schema;
+the connection service handles consent, encrypted file state and refresh.
+
+## Portable configuration
+
+```json
+{
+  "schemaVersion": 1,
+  "integrations": {
+    "crm": {
+      "provider": "salesforce",
+      "displayName": "Customer CRM",
+      "accountMode": "per-user",
+      "scopes": ["api", "refresh_token"],
+      "settings": {
+        "environment": "production",
+        "accountUrl": "https://acme.my.salesforce.com"
+      },
+      "authentication": { "method": "oauth2", "registrationRef": "salesforce" }
+    }
+  },
+  "registrations": {
+    "salesforce": {
+      "source": "own",
+      "clientId": "replace-with-consumer-key",
+      "clientSecretRef": "env:SALESFORCE_CLIENT_SECRET",
+      "callbackUrlRef": "env:SALESFORCE_CALLBACK_URL"
+    }
+  }
+}
+```
+
+The client ID is public configuration. Resolve secret/callback references from
+Env or the application's secret owner. Never paste a secret or an actual
+callback URL into a reference field. File runtime state belongs outside source,
+protected with a durable operator-owned encryption key. No editor database is
+required. See the packaged `connectors/oauth-connection` AI pattern for the
+shared server/CLI composition and its Salesforce example.
+
+| Input | Stored value and behavior |
+|---|---|
+| Display name | Application-owned label, independent of the provider app name. |
+| Account ownership | `shared`, `per-user` or `assistant`; the host authorizes the real stable subject. |
+| Environment | `production` (default) or `sandbox`. Developer Edition uses Production. |
+| Account URL | Lowercase HTTPS My Domain root. Production accepts `.my.salesforce.com` and `.develop.my.salesforce.com`; Sandbox requires `.sandbox.my.salesforce.com`. An optional trailing slash is preserved. |
+| Client ID | Consumer Key issued to the External Client App. |
+| Client secret reference | Indirect server secret; the runtime uses POST client authentication. |
+| Callback reference | The exact registered backend callback, resolved at runtime. |
+| Permissions | `api` for these operations; `refresh_token` for unattended renewal. |
+
+Paths, query strings, userinfo, ports, generic login/test URLs, other hosts and
+mismatched environments fail validation. Both OAuth endpoints and all API
+requests use the configured My Domain. A token for a different `instance_url`
+is rejected, rather than redirecting credentials to the returned destination.
+Legacy instance hosts, Experience Cloud and sovereign domains are outside this
+fragment. My Domain changes require updating configuration and reconnecting.
+
+The `api` scope can authorize writes according to the Salesforce user's rights;
+it is not a read-only scope. This adapter exposes reads only, and the application
+must authorize the requested objects, fields and queries. `per-user` selects
+individual connection ownership; it does not implement Salesforce login or
+create an application session.
+
+## Create and configure the provider app
+
+Use an org whose edition and user permissions support API access. Current
+Salesforce guidance restricts creation of old Connected Apps; use an External
+Client App for a new integration. Existing registrations can continue subject
+to their policies. [Salesforce's migration notice](https://help.salesforce.com/s/articleView?id=005228017&language=en_US&type=1).
+
+1. Sign into the intended Salesforce org. Open the gear menu, then **Setup**.
+   Enter **My Domain** in Quick Find and copy the current login URL. Use that
+   root in Account URL; select the matching environment.
+2. Search Setup for **External Client App Manager**. Select **New External
+   Client App** (also available through App Manager in supported org UIs).
+   Enter the app name, unique API name and contact email. Add a meaningful
+   description. Keep distribution **Local** for an app used only by this org.
+3. Enable the app's OAuth settings. Enter your backend's exact callback URL;
+   preserve its scheme, host and path. Select **Manage user data via APIs
+   (api)** and **Perform requests at any time (refresh_token, offline_access)**.
+   This configuration requests the `refresh_token` spelling of that permission.
+4. Keep **Require Proof Key for Code Exchange (PKCE)** enabled. Require the
+   secret for **Web Server Flow** and **Refresh Token Flow**. The runtime
+   implements confidential authorization-code exchange with S256 PKCE.
+5. Save/create the app. Open its **Settings**, then **OAuth Settings** and
+   **Consumer Key and Secret**. Complete any email verification Salesforce
+   requires. Copy Consumer Key into Client ID; save Consumer Secret in the
+   secret binding referenced by the configuration.
+6. An org administrator reviews the app's **Policies**: permitted users,
+   session/refresh lifetime, IP restrictions and refresh-token rotation.
+   If admin preauthorization is required, grant the app to the intended users
+   through their permission sets/profiles. Ensure those users have API access
+   and only the object/field/record permissions the application needs.
+7. Set the callback binding to the registered URL. Save `integrations.json`,
+   then begin authorization from the application. Choose the intended Salesforce
+   account and approve access. Verification reads limits; saving the editor form
+   alone never completes consent.
+
+The two responsibilities are separate: app developers control its settings;
+subscriber administrators control their org's policies. A Local app is limited
+to its own org. A distributable External Client App uses **Packaged** distribution
+and a second-generation managed package, installed into each subscriber org.
+[External Client App ownership and distribution](https://trailhead.salesforce.com/content/learn/modules/external-client-app-basics/use-external-client-apps-when-connected-apps-wont-do).
+
+## Operations
+
+| Operation | Input | Result |
+|---|---|---|
+| `limits.read` | `{}` | Current org allocations; also the connection check. |
+| `objects.list` | `{}` | Available object summaries, including queryability. |
+| `objects.describe` | `{ "object": "Account" }` | Fields and metadata for exactly that object API name. Custom names such as `ns__Widget__c` are supported. |
+| `query.read` | `{ "q": "SELECT Id, Name FROM Account ORDER BY Id LIMIT 20" }` | One SOQL result page, preserving records, `totalSize`, `done` and any continuation. |
+| `query.next` | `{ "nextRecordsUrl": "/services/data/v66.0/query/<locator>-2000" }` | One continuation page, with the same configured host and connection. |
+
+Queries are single-line SELECT statements, at most 2,000 characters and 3,000
+UTF-8 bytes. This fragment rejects `FOR UPDATE`, `FOR VIEW` and `FOR REFERENCE`;
+it has no record write, MRU-update or explicit locking operation. The query
+endpoint itself enforces SOQL syntax and user access. Never build SOQL by
+concatenating untrusted request text. Use server-owned queries with deliberately
+validated/escaped values and authorize the complete operation input.
+
+Pages contain at most 2,000 top-level records. Subqueries can contain nested
+records; the host must bound its query and overall rendering/workload. `done`
+controls continuation, not the number of returned records. Only a relative
+v66.0 Query cursor path is accepted; foreign URLs, other API resources, query
+strings and path traversal fail before transport. Keep each cursor associated
+with its originating query and owner in application state. There is no automatic
+crawl. An expired locator returns `connector_cursor_expired`; start an authorized
+query again. [Salesforce query and pagination behavior](https://developer.salesforce.com/blogs/2022/12/processing-large-amounts-of-data-with-apis-part-1-of-2).
+
+## Token lifecycle and errors
+
+Salesforce may omit access-token expiry because session lifetime is controlled
+by org/app policy. For that response, this adapter schedules local renewal after
+five minutes (the core refreshes shortly before that boundary). This is a renewal
+policy, not a promise that the provider session lasts five minutes. An explicit
+`expires_in` is honored. Renewal occurs on the next operation, not from a
+background timer. Rotated refresh tokens persist under the existing file lock;
+a response without a new refresh token retains the previous token. If none was
+granted, renewal requires consent again.
+[Web server flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_web_server_flow.htm&language=en_US&type=5),
+[refresh flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&language=en_US&type=5).
+
+An invalid session or revoked refresh requires reconnecting; operations are not
+automatically replayed. Failed replacement consent preserves a previous grant.
+Org, registration or ownership changes cannot reuse an existing grant. A changed
+secret binding is resolved on the next exchange. Scope reductions remain visible
+and block operations without API permission. Disconnect removes the local
+connection/attempts; revoke provider access separately in Salesforce when needed.
+
+`REQUEST_LIMIT_EXCEEDED` is reported as an org rate limit even when Salesforce
+returns HTTP 403. Other permission failures, invalid queries, missing resources,
+expired cursors and reconnect states remain distinct. Provider error bodies are
+not exposed as user messages. Cancellation/deadlines do not replay a request.
+
+## 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).
+
+For cross-customer org access, package and install the application as described
+above; creating a Local app does not make it universally available. The app owns
+its distribution, secrets and policy decisions, with each Salesforce org granting
+its required access.
+
+Separate client IDs do not divide an org's Daily API Request allowance. Apps
+using the same org share that capacity; no registration name grants extra quota.
+[Salesforce API allocation ownership](https://developer.salesforce.com/blogs/2024/11/api-limits-and-monitoring-your-api-usage).
+
+## Automation feasibility and verification
+
+An AI with authorized Salesforce developer/admin tooling can prepare External
+Client App metadata and deploy it through Salesforce CLI/Metadata API. The
+provider's documented types include `ExternalClientApplication`,
+`ExtlClntAppGlobalOauthSettings` and `ExtlClntAppOauthSettings`. Their settings
+cover distribution, callbacks and scopes; sensitive OAuth settings have separate
+handling. Use an already authorized org and the exact supported metadata version.
+[Salesforce's metadata/CLI walkthrough](https://trailhead.salesforce.com/content/learn/projects/create-an-external-client-app-using-metadata-api/create-an-external-client-app).
+
+The operator still owns account creation, authorization, sensitive consumer-detail
+access, subscriber installation and policies. No unattended signup, approval or
+secret retrieval is promised. Prepare and review the application's metadata
+before an authorized deployment; this adapter performs none of those provisioning
+writes. It does not bypass the restrictions on old Connected App creation.
+
+Automated evidence uses controlled HTTP responses, actual encrypted temporary
+files and the editor form. It covers both environments, PKCE, renewal/rotation,
+owner/org binding, query/cursor limits, malformed replies, cancellation and
+save/reload. Live org access, real consent, queries against
+customer data and application generation are outside this delivery's tests.
+Writes, Bulk API, SOAP, streaming, MCP, client-credentials/JWT grants, identity
+login and additional domains remain outside the initial runtime fragment.
+
+
+## Existing-scope closeout — 13 September 2026
+
+Supported operations are `limits.read`, `objects.list`, `objects.describe`,
+`query.read` and `query.next`, through project-owned confidential OAuth on the
+configured production/developer/sandbox My Domain. Source and offline installed
+public-export tests each pass 13/13, including the packaged configuration example.
+Historical editor form proof is retained; no new browser run or runtime/form
+change was needed for this closeout.
+
+Deferred work and limitations: record create/update/delete and relationship
+mutations, bulk/partial-write handling, SOAP, streaming/events, MCP, automatic
+pagination, query building/parameter binding, client-credentials/JWT or other
+grants, identity login, Experience Cloud/sovereign/legacy instance hosts and API
+versions other than v66.0. Queries are bounded single-line SELECT inputs, not an
+unrestricted query console; host policy must authorize objects, fields and query
+text. The adapter rejects FOR UPDATE/VIEW/REFERENCE effects. It does not provision
+orgs/apps, assign permissions or bypass API capacity. API-limit verification alone
+does not establish access to a particular object or field. A missing token expiry
+uses a five-minute local renewal policy, not a provider lifetime guarantee.
+Disconnect removes local grants only; provider revocation remains an org/admin
+action. Native framework routes, business UI, app sessions and access policy are
+application-owned. Editor coding-agent attachment, live org/consent/data outcomes
+and generated-app execution remain deferred or unverified. The original broader
+CRM checklist stays backlog; this is not full Lovable parity.

package/docs/sanity.md

@@ -0,0 +1,122 @@
+# Sanity assistant MCP connection
+
+Import `sanityProvider` from `@jskit-ai/connectors-catalog/server/sanity`.
+Configure `accountMode: "assistant"`. OAuth uses a project-owned MCP client,
+`global` scope and callback/secret Env references. API-key mode instead uses a
+Sanity token reference. Transport remains fixed at `https://mcp.sanity.io/`;
+this is builder context, not a generated-app login or REST content service.
+
+## OAuth registration and consent
+
+Sanity's public metadata advertises issuer `https://mcp.sanity.io`, resource
+`https://mcp.sanity.io` (no trailing slash), `/authorize`, `/token`, `/register`,
+S256 and the single `global` scope. Keep the resource value exact even though
+MCP transport uses the root URL. Metadata was read without authentication;
+no client or provider account was created during implementation.
+
+In Vibe64 development settings, choose **Register client and connect** after
+setting the suggested callback. The existing owner-authorized action saves the
+client ID in configuration, saves secret/callback/recovery ID in Env and starts
+the application's setup command. It refuses occupied Env keys and stale source.
+An uncertain outcome requires inspection before retrying. This does not register
+a central Vibe64 client.
+
+For manual setup, use the OAuth client registration screen's JSON, or invoke
+`registerSanityClient({ clientName, callbackUrl, scopes: ["global"] })` from
+`@jskit-ai/connectors-catalog/server/sanity` in an authorized CLI. Register once,
+then save the returned client ID and private client secret into your own
+configuration/Env. Investigate an interrupted request before retrying, because
+the provider may already have created the client. Use the exact backend callback
+suggested by your project. No central Vibe64 callback or managed registration.
+
+Connect and consent only after the backend serves that callback. Sanity account
+permissions govern the grant; the host must still authorize project/dataset
+arguments and tools. The single global scope is not a per-project permission UI.
+The token mode below remains an alternative.
+
+## Manual setup
+
+1. Sign in to **sanity.io/manage** and select the project.
+2. Open **Settings → API → Tokens → Add new token** with an appropriate admin
+   role. Set a descriptive name, the required role and optional expiry.
+3. Copy the token once displayed. Store it in Env and enter its reference in
+   the integration's **MCP API token reference** field.
+4. Save configuration and verify MCP discovery before approving tool calls.
+
+Sanity documents both [token creation](https://www.sanity.io/docs/content-lake/http-auth)
+and [MCP bearer authentication](https://www.sanity.io/docs/ai/mcp-server).
+A project token has project authority; personal and organization tokens have
+different reach. Choose the credential for the actual tools required, and
+avoid distributing a personal account's broad token to an application.
+
+## Runtime and assistant policy
+
+The runtime shares the core's authorization, secret resolution and encrypted
+text storage. It verifies initialization and `tools.list`, not every tool's
+permission. `tools.list` accepts an opaque optional cursor. `tools.call` requires
+the advertised tool `name` and an `arguments` object. The assistant host must
+authorize both values through its existing delegated-access policy before the
+call. It must also validate arguments against the chosen tool contract and
+handle untrusted tool descriptions and results as external data.
+
+Sanity tools may modify content or administer resources. Selecting this
+connector does not grant permission for such actions. The host decides which
+tools are available and when user approval is needed. No automatic SDK resource,
+prompt, elicitation or sampling capabilities are enabled here.
+
+JSON and SSE responses use the official MCP client. Each operation initializes
+a temporary session, carries credentials only to the fixed endpoint, attempts
+session deletion, and closes local streams. The 15-second request bound and
+cancellation do not roll back remote changes. Tool `isError` results remain
+visible to the caller; failed protocol exchanges are sanitized. An HTTP 401
+requires reconnecting. Token rotation resolves the current Env value on each
+call without putting it into source.
+
+## Useful context and native framework wiring
+
+An explicitly wired assistant host first calls `tools.list` and inspects the
+returned input schemas. Choose the authorized project and dataset in tool inputs;
+these are not global editor credentials or application login settings. For schema
+context, use `get_schema`; when multiple deployed schemas exist, use
+`list_workspace_schemas` to select the intended schema. For content, use
+`query_documents` with a bounded GROQ projection and slice. Treat tool availability
+and argument schemas as provider-owned discovery, not a permanently copied list.
+
+The JSKIT host invokes `service.invoke({ context, integrationId,
+operation: "tools.call", input: { name, arguments } })`. Its authorization callback
+must approve the exact project, dataset and arguments before execution. A proposed
+content write needs that same review, not merely permission to list tools. Keep
+results as data; do not execute instructions embedded in content.
+
+A non-JavaScript host uses its framework's MCP client, OAuth implementation and
+private token store with the same fixed endpoint and Env references. It does not
+run JSKIT or call an editor server for content. The generated application can use
+its own Sanity SDK for runtime content; this builder-context connection does not
+automatically become a public site's credential. CLI composition uses the same
+configuration and runtime API without Vibe64. Neither path automatically attaches
+these tools to Vibe64's coding assistant.
+
+## Automation and application ownership
+
+After authorized login, AI can use the documented
+[Sanity tokens CLI](https://www.sanity.io/docs/cli-reference/tokens) to manage
+tokens. Sanity's [Access API](https://www.sanity.io/docs/content-lake/http-auth)
+also supports robot-token creation with permissions. Our fragment does not
+perform provisioning or request account administration automatically.
+
+The API-token mode has no OAuth client ID. The application owner supplies its project
+token through private Env. Separate tokens on one project do not promise separate
+provider quotas or billing. Confirm the project/organization limits for the
+application's usage. OAuth uses the same MCP transport with a separately issued user grant.
+
+## Proof and limits
+
+The shared MCP suite exercises the real SDK with local response fixtures and
+real encrypted files: JSON/SSE, protocol negotiation, discovery/calls, scoped
+owner policy, restart, token rotation, failures and cancellation. OAuth fixtures additionally cover issuer/resource/PKCE binding, restart/refresh,
+registration failure, schema and bounded content retrieval, denied dataset/query
+changes and disconnection cleanup. Tool payloads/results are controlled fixtures;
+this does not certify current live Sanity schemas. Editor proof covers token
+reference validation/reload and OAuth registration, cancellation, reconnect and
+disconnect on phone and desktop. Live Sanity access, real OAuth consent,
+automatic assistant attachment and generated applications are not exercised.

package/docs/semrush.md

@@ -0,0 +1,276 @@
+# Semrush
+
+Import `semrushProvider` from `@jskit-ai/connectors-catalog/server/semrush`.
+This adapter manages Projects API V4 records and reads keyword/backlink reports using an application-owned V4 API key.
+It works with the shared CLI/server connection service and encrypted file store;
+Vibe64 edits the same portable configuration. Saving fields does not verify a key.
+
+## Create and configure a key
+
+1. Sign into the Semrush account that will own the usage. Projects API access
+   requires SEO Business and available API units. Check that account's entitlement
+   before provisioning; a key alone does not supply API access.
+2. Open the top-right profile icon. In **My profile**, choose **API Keys**.
+3. Choose **+ Create API key** and create a **V4** key. Give it an application
+   name, select **Read-only** for reads or **Read and write** for creating or
+   renaming or deleting projects, and choose an expiry appropriate for the host.
+4. Copy the value when shown. Store it in the runtime's environment or secret
+   store; configure only its reference below. The full value is shown once.
+5. Save the JSON through the CLI or Vibe64. Explicitly call `connectApiKey` to
+   verify accessible projects. Empty project lists are valid.
+6. For rotation, create a replacement V4 key, update the same binding, verify
+   access, then revoke the old key in the provider portal. Changing just the
+   environment value does not require rewriting source configuration.
+
+Sources: [key creation](https://developer.semrush.com/api/v4/get-started/quick-start/),
+[permissions and expiry](https://developer.semrush.com/api/v4/get-started/authorization/),
+[Projects prerequisites](https://developer.semrush.com/api/v4/projects/overview/).
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "seo": {
+      "provider": "semrush",
+      "displayName": "Marketing projects",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:SEMRUSH_V4_KEY"
+      }
+    }
+  }
+}
+```
+
+`assistant` is also supported when the host authorizes that assistant. Neither
+mode creates individual provider accounts for app users. The current form has
+no client registration, callback or scope checkboxes. API-key permissions are
+chosen in Semrush. V3 keys cannot be substituted for V4 keys; OAuth access tokens
+are another credential type. [API versions](https://developer.semrush.com/api/v4/introduction/api-versions/)
+
+## Runtime operations
+
+| Operation | Input | Result |
+|---|---|---|
+| `projects.list` (verification) | Optional `scope`: `OWN` (default), `ALL`, `SHARED`, `CORPORATE`; `limit`: 1–1000 (default 100); `offset`: nonnegative safe integer (default 0) | Original `meta` and `data` envelope, including total count and project permissions |
+| `projects.get` | Required positive safe-integer `projectId` | Project envelope; returned ID must match the request |
+| `projects.create` | `domain` without a protocol/path and `project_name` | Created project envelope with assigned ID; the name/domain must match the request |
+| `projects.update` | `projectId` and nonempty `project_name` | Renamed project envelope; changing the domain is not supported |
+
+The adapter uses `https://api.semrush.com/apis/v4/projects/v1/projects` and the
+documented `Apikey` header. It makes one explicit request per operation, does
+not follow redirects or fetch later pages, and rejects malformed responses,
+unsafe numeric IDs and mismatched pagination. Project results include provider
+ownership and permission metadata; the host must still authorize the caller
+and the particular project. List scope is an operation filter, not an OAuth scope.
+[Projects API](https://developer.semrush.com/api/v4/projects/projects/)
+
+Creation uses POST; rename uses PATCH. These operations require a provider key
+with Read and write access plus application authorization before key resolution.
+They are never automatic connection checks. Save the returned provider project ID
+in application-owned data. If a request fails after submission, inspect the
+project list/current name before deciding whether to repeat it; a failed response
+is not proof that Semrush made no change. No automatic retry or idempotency
+guarantee is supplied.
+
+`projects.delete({ projectId })` permanently removes the provider project, including
+its tools, settings and history. The application must authorize deletion and obtain
+user confirmation before invoking it. A successful response contains the matching
+project ID. This is separate from disconnecting a local connection. An uncertain
+response is never retried automatically; inspect the provider before proceeding.
+Reports are implemented as described below. OAuth and individual app-user login are not supported; project-owned API keys are the accepted authentication scope.
+
+HTTP-200 error envelopes are failures. Bad-key codes require reconnection;
+disabled access becomes a permission error; exhausted capacity becomes
+`connector_quota_limited`; missing projects become `connector_resource_not_found`.
+Provider error messages are not exposed. HTTP transport failures use the common
+connector errors. An aborted read is not replayed. Local disconnect removes
+connection state; it does not revoke the provider key.
+[Error codes](https://developer.semrush.com/api/v4/projects/overview/)
+
+## Application and callback ownership
+
+The application owner supplies the Semrush account and key. CLI, installed
+editor and hosted editor use the same configuration file and private Env
+reference. The editor does not provide a provider account, retain the key in a
+central connector service or assign capacity based on the editor subscription.
+
+For this V4 key flow, a universal OAuth callback is **not applicable**. VPS
+addresses and custom domains do not change provider key authentication. The
+application owner supplies its authorized key through private Env and retains
+that ownership when moving hosts.
+
+Separate keys on one account share its capacity. The documented general limits
+are per account, including 10 requests per second and 10 simultaneous requests;
+API-unit and subscription limits also apply. Independent capacity needs an
+approved account/subscription arrangement, not just two named keys. The guide
+does not establish permission to redistribute provider data through arbitrary
+customer apps. [Usage restrictions](https://developer.semrush.com/api/v4/introduction/api-usage-restrictions/)
+
+## Captured OAuth variant and automation
+
+The reference UI offered `user.id`, `user.limits`, `url.info`, `domains.info`,
+`backlinks.info`, `subfolders.info`, `projects.info`, and `positiontracking.info`.
+That journey is an explicit accepted limitation of this connector. Semrush now deprecates the previous
+OAuth Projects endpoints and recommends the current V4 API for new integrations.
+Its documented OAuth client credentials require contacting support; device
+authorization is a different flow. Do not invent a universal redirect approval
+or claim that these eight permissions are implemented by the V4 key adapter.
+[OAuth guidance](https://developer.semrush.com/api/v4/get-started/authorization/)
+
+| Task | Automation assessment |
+|---|---|
+| Create or rotate application keys | No general key-provisioning API was found in the reviewed public setup documentation. An authorized browser operator can assist with the portal steps; account access remains required. |
+| Create an application-owned OAuth registration | Provider support is the documented prerequisite. Scope/callback approval and the runtime journey remain unfinished. |
+| Configure a CLI or application | AI can write the JSON, compose the library and wire host authorization using externally supplied references. No generated template is required. |
+| Read provider projects | Implemented through the documented API with controlled local tests. No actual provider account was used. |
+
+## Verification
+
+Fifteen focused runtime tests cover file persistence/restart, ownership, rotation,
+input and response validation, pagination, error codes, transport errors and
+interruption, project creation/rename/deletion, write authorization and no replay after
+uncertain results. All fifteen also pass in an isolated consumer installed from
+the packed catalogue, importing only public package exports. Current phone and
+desktop editor checks cover V4 and optional V3 references, raw-secret rejection,
+ownership, exact file content, setup instructions and reload persistence. The
+phone flow explicitly dismisses the saved notification before its next edit.
+Live registrations, provider data, generated applications and managed onboarding
+have not been tested.
+
+
+## Keyword metrics
+
+Invoke `keywords.metrics` with `keyword` (1–255 characters), uppercase two-letter
+`country` and optional `month` (`YYYY-MM`, 2012-01 through the current month).
+Semrush determines available countries; its documented United Kingdom code is
+`UK`. Omit month for the provider's current snapshot. The adapter requests JSON
+and returns the report envelope, preserving numeric strings such as search volume
+and result counts without precision loss. Framework code owns presentation and
+any caching; the connector does not fetch reports during connection checks.
+V4 keyword reporting is Early Access and consumes account API units. Provider
+entitlement and country availability are checked by Semrush. See the
+[current report contract](https://developer.semrush.com/api/v4/seo/keyword-reports/).
+Domain and position-tracking operations are described below. Captured OAuth and final provider acceptance remain open.
+
+
+## Backlink reports
+
+| Operation | Result |
+|---|---|
+| `backlinks.overview` | Aggregate backlink, referring-domain/page counts and authority score. |
+| `backlinks.list` | Individual backlinks, anchors, source and target URLs and link attributes. |
+| `backlinks.referringDomains` | Referring domains, backlink counts and domain scores. |
+| `backlinks.anchors` | Anchor text, backlink counts and referring-domain counts. |
+
+Supply `url` (domain or URL, at most 2000 characters) and `scope` (`ROOT_DOMAIN`,
+`SUBDOMAIN`, `SUBFOLDER`, `PAGE`). The target is a Semrush query parameter, never
+a destination fetched by this connector. Reports always return JSON and retain
+provider fields. Page operations accept `limit` (default 100, local maximum 1000),
+`offset` (default 0), optional `order_by`, `direction` (`ASC`/`DESC`, default DESC),
+and optional provider `filter` expression (local maximum 4000 characters).
+Semrush validates sort fields and filter syntax. No local filter parser is added.
+All provider fields are requested; selecting columns is left to application code.
+
+A page request makes one API call. The caller owns pagination, cost limits and
+stopping when no further rows are available. Metadata differs between reports;
+anchors may omit totals and page context. The adapter preserves metadata and
+validates supplied pagination values. Empty arrays are valid. Report URLs and
+anchor text are provider data: use the framework's normal escaping when rendering
+and do not interpret them as executable HTML or automatic network destinations.
+
+The V4 reports are Early Access and consume account units. They do not run during
+connection checks. A project-access check does not prove entitlement to every
+report. See [Semrush's current backlink API](https://developer.semrush.com/api/v4/seo/backlinks/).
+
+
+## Domain overview and the separate V3 key
+
+`domains.overview({ domain: "example.com", database: "us" })` retrieves one
+regional domain overview: rank, organic keywords/traffic/cost and paid
+keywords/traffic/cost. It returns `{ columns, rows }`, retaining provider strings
+and decimal precision. No data is `{ columns, rows: [] }`. Quoted CSV is decoded;
+unexpected columns, malformed rows and decoded reports over 2 MB are rejected.
+
+In **My profile > API Keys**, locate the autogenerated **Version 3** key and put
+it in the project's private Env as `SEMRUSH_V3_KEY`. Add
+`settings: { "v3ApiKeyRef": "env:SEMRUSH_V3_KEY" }` to the integration JSON or
+fill **V3 API key reference (optional)** in Vibe64 and use **Set credential in Env**.
+The normal authentication reference still points to the separate V4 key.
+Leave the V3 field empty when using only V4 reports and projects.
+
+This extra key is resolved only for V3 reports after application authorization.
+It travels in the provider-required `key` query parameter over HTTPS; custom
+transport instrumentation must redact query credentials. It is never sent as
+V4 authorization. Connecting still verifies V4 projects; the V3 report itself
+checks its own entitlement and consumes the account's API units. V3 key errors
+do not invalidate a working V4 connection. The editor supplies neither account.
+Other frameworks use the same Env reference and Semrush's native HTTP/CSV contract.
+
+Sources: [V3 key setup](https://developer.semrush.com/api/v3/get-started/quick-start/),
+[V3 authentication](https://developer.semrush.com/api/v3/get-started/authorization/),
+[domain overview](https://developer.semrush.com/api/v3/seo/overview-reports/),
+[report errors](https://developer.semrush.com/api/v3/seo/overview/).
+Position tracking is described below; captured OAuth is outside the accepted API-key scope.
+
+
+## Organic and paid keyword detail
+
+The same optional V3 key powers these explicit report operations:
+
+| Operation pair | Required target |
+|---|---|
+| `domains.organicKeywords`, `domains.paidKeywords` | `domain` |
+| `urls.organicKeywords`, `urls.paidKeywords` | `url` |
+| `subfolders.organicKeywords`, `subfolders.paidKeywords` | `subfolder` |
+
+All require a lowercase regional `database` such as `us`. Use `limit` (1–1000,
+default 100) and `offset` (default 0). The adapter translates them to Semrush's
+`display_limit = offset + limit` contract, bounded by the provider's 4,000,000
+result window. It does not automatically fetch the next page. Optional
+`display_sort` supports position, traffic or volume ascending/descending;
+`display_filter` accepts the provider's expression syntax (up to 4000 characters).
+Optional `display_date` uses `YYYYMM15`; database-specific history and entitlement
+are provider decisions. Historical queries can cost more units than current ones.
+
+Results use `{ columns, rows }` with Keyword, Position, Search Volume, CPC,
+Competition, Traffic (%) and Number of Results. Values remain strings, including
+large counts, decimals and escaped keyword text. No-data responses return an
+empty row list. The application owns cost approval, pagination, presentation and
+additional storage. Vibe64 does not execute keyword reports during connection.
+Other provider columns are not currently exposed by these focused operations.
+
+Sources: [domain keyword reports](https://developer.semrush.com/api/v3/seo/domain-reports/),
+[URL keyword reports](https://developer.semrush.com/api/v3/seo/url-reports/),
+[subfolder keyword reports](https://developer.semrush.com/api/v3/seo/subfolder-reports/).
+
+
+## Position tracking
+
+The optional V3 key also supports `tracking.campaigns({ projectId })`,
+`tracking.dates({ campaignId })`, `tracking.organicPositions` and
+`tracking.paidPositions`. Start with the application-authorized project ID from
+project discovery. Campaign discovery returns campaign IDs, devices, tracked URLs
+and harvesting state. Use that returned campaign ID (for example `123_45`),
+not the project ID, in dates and position reports. Existing configured campaigns
+and harvested data are prerequisites; these operations do not create campaigns.
+
+Position reports accept `campaignId`, optional provider-masked `url` (for example
+`*.example.com/*`), `date_begin`/`date_end` as `YYYYMMDD`, optional provider
+`display_filter`, and `display_limit` (1–1000, default 10)/`display_offset`
+(default 0). These tracking pagination fields are sent directly, unlike SEO CSV
+keyword report pagination. Use `tracking.dates` to discover available snapshots.
+The provider determines availability for a campaign's engine and device.
+
+The JSON response preserves keyword IDs, date-keyed rankings, visibility and
+other provider fields. `data` may be an indexed object rather than a JS array;
+use the framework's object-value iteration when rendering rows. The application
+must authorize project/campaign access, review unit usage and decide whether to
+request another page. Neither Vibe64 nor this adapter automatically polls campaigns.
+Connecting only checks V4 project access. Errors from tracking do not invalidate
+that separate V4 connection. No live campaigns were queried during verification.
+
+[Position-tracking contract](https://developer.semrush.com/api/v3/projects/position-tracking/)