@zackbart/connecta 0.24.3 → 0.25.0

package/dist/providers/linear.js

@@ -11,7 +11,11 @@ export const LINEAR_MCP_ENDPOINTS = {
     "read-write": "https://mcp.linear.app/mcp",
     "read-only": "https://mcp.linear.app/mcp/readonly",
 };
-/** Reviewed reads; see `documentation/linear.md` and provider convention P5. */
+/**
+ * Reviewed reads, listed by name (P5). The list is a superset: Linear's hosted
+ * `tools/list` varies by plan and enabled features, so a name this workspace
+ * never returns costs nothing while an unlisted new one fails closed.
+ */
 const READ_ONLY_TOOLS = new Set([
     // Issues
     "list_issues",
@@ -73,7 +77,13 @@ const READ_ONLY_TOOLS = new Set([
     // than argues.
     "extract_images",
 ]);
-/** Reviewed writes; `save_*` upsert rationale lives in `documentation/linear.md`. */
+/**
+ * Reviewed writes with their destructive verdict. Every `save_*` is destructive
+ * because Linear's `save_*` tools are upserts: omitting a record id creates,
+ * supplying one overwrites in place, and the schema cannot tell them apart. The
+ * genuine creates — the `create_*_label` and attachment tools — stay additive,
+ * since `readOnlyHint: false` already routes them through the approval path.
+ */
 const WRITE_TOOLS = new Map([
     // Issues
     ["save_issue", "destructive"],
@@ -107,7 +117,7 @@ const WRITE_TOOLS = new Map([
     ["create_attachment_from_upload", "additive"],
     ["create_attachment", "additive"],
     ["delete_attachment", "destructive"],
-    // Explicit issue access
+    // Explicit issue access. Both halves change an existing issue's audience.
     ["share_issue", "destructive"],
     ["unshare_issue", "destructive"],
     // Customer requests (plan-gated)
@@ -116,7 +126,12 @@ const WRITE_TOOLS = new Map([
     ["save_customer_need", "destructive"],
     ["delete_customer_need", "destructive"],
 ]);
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets
+ * and the verdict a check reads can never disagree. Drift must surface as an
+ * unclassified tool on the approval path (P5), never a quiet re-guess.
+ */
 export const LINEAR_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,

package/dist/providers/mixpanel.d.ts

@@ -13,7 +13,10 @@ export interface MixpanelOptions {
     authScope?: "shared" | "personal";
     /** Who should use this account and for what decisions. */
     purpose: string;
-    /** Data residency region; see `documentation/mixpanel.md`. */
+    /**
+     * Data residency region, selecting the matching official endpoint. A wrong
+     * region answers empty rather than wrong, which reads as an empty project.
+     */
     region?: MixpanelRegion;
     /**
      * OAuth by default; static headers support Mixpanel service accounts, and
@@ -25,10 +28,20 @@ export interface MixpanelOptions {
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
-    /** Optional per-runtime policy; see `documentation/mixpanel.md#rate-limits`. */
+    /**
+     * Optional per-runtime policy. There is no default: Mixpanel meters its MCP
+     * server per user per hour, and a per-runtime counter over-counts one runtime
+     * serving many users and under-counts many runtimes sharing one credential.
+     * Only an operator who knows the account can pick a number worth enforcing.
+     */
     callAdmission?: ConnectorCallAdmissionPolicy;
 }
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets
+ * and the verdict a check reads can never disagree. Drift must surface as an
+ * unclassified tool on the approval path (P5), never a quiet re-guess.
+ */
 export declare const MIXPANEL_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained Mixpanel hosted-MCP connection. */
 export declare function mixpanel(id: string, options: MixpanelOptions): Connector;

package/dist/providers/mixpanel.js

@@ -44,7 +44,12 @@ const READ_ONLY_TOOLS = new Set([
     "Get-Feature-Flag-Setup-Guidance",
     "Get-Feature-Flag-Lifecycle-Guidance",
 ]);
-/** Reviewed writes; see provider convention P5. */
+/**
+ * Reviewed writes, each with its destructive verdict (P5). Additive writes stay
+ * `additive` because `readOnlyHint: false` already routes them through the
+ * approval path, and claiming destruction only inflates the copy a host shows a
+ * human. Anything unlisted is not read-only, so a new name fails closed.
+ */
 const WRITE_TOOLS = new Map([
     ["Create-Dashboard", "additive"],
     ["Update-Dashboard", "destructive"],
@@ -74,6 +79,7 @@ const WRITE_TOOLS = new Map([
     ["Update-Experiment", "destructive"],
     ["Create-Feature-Flag", "additive"],
     ["Update-Feature-Flag", "destructive"],
+    // Applies generated names and descriptions to existing Lexicon events.
     ["Fill-Event-Metadata", "destructive"],
 ]);
 /** Live US hosted-MCP schemas reviewed read-only on 2026-08-30 (#395, #512). */
@@ -143,7 +149,12 @@ const MIXPANEL_SCHEMA_DIGESTS = {
     "Update-Lookup-Table": "sha256:ef28f1ec9c9484a7a53b5e2b6659e70f79a8e71e55bda17025aa4ab3c23b6a63",
     "Update-Metric": "sha256:739bb6abdab19282afd4a6644a96183daabe9098a5322c44a77b840608a5ee9d",
 };
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets
+ * and the verdict a check reads can never disagree. Drift must surface as an
+ * unclassified tool on the approval path (P5), never a quiet re-guess.
+ */
 export const MIXPANEL_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,

package/dist/providers/notion.d.ts

@@ -3,7 +3,14 @@ import type { Connector, ConnectorCallAdmissionPolicy } from "../types.js";
 export declare const NOTION_API_BASE_URL = "https://api.notion.com";
 /** Notion's official hosted MCP endpoint. */
 export declare const NOTION_MCP_ENDPOINT = "https://mcp.notion.com/mcp";
-/** See documentation/notion.md#the-pinned-api-version. */
+/**
+ * Pinned with no override. Notion's date-named versions keep working
+ * indefinitely, which makes an override look harmless; it is not. `2026-03-11`
+ * is where databases split into data sources, `archived` became `in_trash`, and
+ * block append took a `position` object instead of an `after` string. Every
+ * projection and write body here assumes those shapes, so an older version would
+ * return quietly wrong results rather than fail loudly.
+ */
 export declare const NOTION_API_VERSION = "2026-03-11";
 interface NotionCommonOptions {
     /** Human-readable display name; defaults identify the selected interface. */

package/dist/providers/notion.js

@@ -7,7 +7,14 @@ import { ConnectorCallError } from "../errors.js";
 export const NOTION_API_BASE_URL = "https://api.notion.com";
 /** Notion's official hosted MCP endpoint. */
 export const NOTION_MCP_ENDPOINT = "https://mcp.notion.com/mcp";
-/** See documentation/notion.md#the-pinned-api-version. */
+/**
+ * Pinned with no override. Notion's date-named versions keep working
+ * indefinitely, which makes an override look harmless; it is not. `2026-03-11`
+ * is where databases split into data sources, `archived` became `in_trash`, and
+ * block append took a `position` object instead of an `after` string. Every
+ * projection and write body here assumes those shapes, so an older version would
+ * return quietly wrong results rather than fail loudly.
+ */
 export const NOTION_API_VERSION = "2026-03-11";
 /** Notion's hard cap on `page_size` for every paginated endpoint. */
 const MAX_PAGE_SIZE = 100;
@@ -15,7 +22,12 @@ const MAX_PAGE_SIZE = 100;
 const DEFAULT_PAGE_SIZE = 25;
 /** Notion's cap on `children` per append, and on blocks per page create. */
 const MAX_CHILDREN_PER_REQUEST = 100;
-/** See documentation/notion.md#rate-limiting. */
+/**
+ * Ceiling on the fetches one `get_page_content` walk may spend. Call admission
+ * meters tool calls, not the requests inside them, so a deep `depth` would
+ * otherwise drain the budget invisibly; the walk stops here and reports
+ * `truncated: true` instead.
+ */
 const MAX_CONTENT_REQUESTS = 20;
 /**
  * The largest response this connection will read.
@@ -26,7 +38,15 @@ const MAX_CONTENT_REQUESTS = 20;
  * a budget any real read has to think about.
  */
 const NOTION_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
-/** See documentation/notion.md#rate-limiting. */
+/**
+ * Notion documents "an average of three requests per second, with some bursts
+ * beyond the average allowed" per connection. 180 calls per minute is that
+ * average over a window short bursts pass and a sustained loop does not, and
+ * `maxConcurrency: 3` is the load-bearing half — an averaged budget cannot stop
+ * forty calls in one tick, and declaring a queue is also what makes the queue
+ * settings legal at construction. Per runtime, and a floor on the real request
+ * rate rather than a ceiling, since one admitted call can spend many fetches.
+ */
 const NOTION_ADMISSION = {
     rules: [
         {
@@ -38,7 +58,18 @@ const NOTION_ADMISSION = {
         },
     ],
 };
-/** See documentation/notion.md#typed-failures. */
+/**
+ * Map to what the caller should do next, not to what Notion's `code` says
+ * happened. The two that are easy to mistranslate:
+ *
+ * - **403 is not an authentication failure.** The token is fine; the integration
+ *   lacks a capability or was never shared the object, and neither
+ *   `authorize_connector` nor a new token can fix it. Non-retryable call failure.
+ * - **404 does not prove absence.** Notion returns `object_not_found` both for an
+ *   object that does not exist and for one never shared with the integration, and
+ *   will not say which — so not `not_found`, which exists to assert absence
+ *   (H11). The message names both possibilities.
+ */
 function notionFailure(status, body, headers) {
     const code = typeof body?.["code"] === "string" ? body["code"] : undefined;
     const detail = typeof body?.["message"] === "string" && body["message"].trim()
@@ -58,7 +89,7 @@ function notionFailure(status, body, headers) {
         return new ConnectorCallError("unavailable", `${labelled} Notion is overloaded; retry after the reported window.`, { retryAfterMs: retryAfter ?? 5_000 });
     }
     if (status === 401) {
-        return new ConnectorCallError("auth_required", `${labelled} The Notion integration token is missing or invalid — an operator must set a valid token on /credentials.`);
+        return new ConnectorCallError("auth_required", `${labelled} The Notion integration token is missing or invalid. Call authorize_connector for recovery options. When available, an operator can set a valid token in this connection in the operator UI.`);
     }
     if (status === 403) {
         return new ConnectorCallError("connector_call_failed", `${labelled} The token is valid but this integration is not allowed to perform this operation. An operator must enable the matching capability on the Notion integration (comment capabilities are off by default) or share the object with it. Re-authorizing will not help.`, { retryable: false });
@@ -82,7 +113,18 @@ function notionFailure(status, body, headers) {
         retryable: false,
     });
 }
-/** See documentation/connectors.md#the-guarded-fetch-transport. */
+/**
+ * The shared transport owns the mechanical, provider-independent guards: path
+ * confinement re-checked after URL normalization, encoded query construction,
+ * credential headers applied last and unshadowable, a refused 3xx (a redirect is
+ * an instruction to re-send the credential to another origin), and a body
+ * abandoned at `maxResponseBytes`. It deliberately owns no meaning — it never
+ * reads a status code, because Notion's 403 is an ungranted capability while
+ * another provider's is a token scope, and those want opposite next moves. The
+ * mapper below supplies that. Note it must re-throw `ConnectorCallError`: a bare
+ * catch around a body read swallows the transport's own refusal and turns a
+ * response nobody was allowed to read into an empty success.
+ */
 const send = guardedFetch({
     provider: "Notion",
     baseUrl: NOTION_API_BASE_URL,
@@ -91,7 +133,7 @@ const send = guardedFetch({
     authenticate: async (ctx) => {
         const token = (await ctx.credential?.get())?.trim();
         if (!token) {
-            throw new ConnectorCallError("auth_required", "No Notion integration token is configured for this connector — an operator must add one on /credentials before any Notion call can run.");
+            throw new ConnectorCallError("auth_required", "No Notion integration token is configured for this connector. Call authorize_connector for recovery options. When available, an operator can add the token in this connection in the operator UI.");
         }
         return { Authorization: `Bearer ${token}` };
     },
@@ -108,7 +150,16 @@ async function notionRequest(ctx, request) {
         return payload ?? {};
     });
 }
-// Projections: documentation/notion.md#lean-projections-and-the-raw-escape-hatch.
+// Projections. Notion wraps every property in a discriminated object, every
+// string in an array of annotated rich-text runs, and every user in a nested
+// object, so a small query is tens of kilobytes of structure around a few
+// hundred bytes of meaning. Every read collapses that to ids, plain text, and
+// flattened values. Nothing is lost for good: the reads that can drop something
+// take `raw: true` and return Notion's untouched response instead.
+//
+// Unknown types unwrap rather than switch exhaustively, because Notion ships
+// additive changes to every pinned version at once — a property type newer than
+// this release degrades to its raw value instead of vanishing.
 /** Concatenate a rich-text array to its plain text. Safe for every variant. */
 function plainText(value) {
     if (!Array.isArray(value))
@@ -292,7 +343,11 @@ function projectPage(page, select) {
         ...(truncated.length ? { truncated_properties: truncated } : {}),
     };
 }
-/** See documentation/notion.md#lean-projections-and-the-raw-escape-hatch. */
+/**
+ * Identity fields only, no properties. A 25-result search across a populated
+ * database would otherwise drag back hundreds of flattened values for results
+ * the agent is about to discard; `get_page` fetches them for the one that hit.
+ */
 function projectSearchHit(hit) {
     if (hit?.object === "data_source") {
         return {
@@ -359,7 +414,9 @@ function projectBlock(block, depth) {
             projected["icon"] = iconRef(payload?.icon);
             break;
         default:
-            // Rationale: documentation/notion.md#lean-projections-and-the-raw-escape-hatch.
+            // A block type this projection does not model keeps its payload verbatim
+            // rather than collapsing to an empty string, so a block type newer than
+            // this release still carries its content.
             if (carriesUnprojectedContent(payload))
                 projected["raw"] = payload;
             break;
@@ -705,6 +762,9 @@ function buildTools(defaultPageSize) {
         },
         {
             name: "get_page_content",
+            // `raw: true` returns the requested level exactly as Notion sent it and
+            // does not walk nested children, so `depth` is ignored alongside it: a
+            // raw read of a deep page yields one level.
             description: "Read a page's body as a flat list of blocks reduced to plain text. Each block keeps its id, type, and depth so it can be quoted, appended after, or drilled into. Nested content requires depth > 0.",
             annotations: { readOnlyHint: true },
             inputSchema: {
@@ -1107,7 +1167,11 @@ function buildTools(defaultPageSize) {
             description: "Create a page, either as a child of another page or as a row in a data source. Notion has no idempotency key: a retried create makes a second page, so confirm with search before repeating one.",
             annotations: { readOnlyHint: false },
             inputSchema: {
-                // See documentation/notion.md#what-this-connection-does-not-do.
+                // A deliberate subset of the 2026-03-11 create contract, reviewed after
+                // the 0.17.0 drift check (#408). Workspace-private pages, templates,
+                // page placement, and the expanded icon/cover forms stay out: they
+                // change ownership, start asynchronous content work, control ordering,
+                // or depend on file surfaces, none of which extend page/row authoring.
                 required: [],
                 type: "object",
                 properties: {
@@ -1263,6 +1327,10 @@ function buildTools(defaultPageSize) {
         },
         {
             name: "update_page_properties",
+            // Deliberately no locking, templates, or `erase_content` (#409): locking
+            // is coordination state, templates finish asynchronously, and
+            // `erase_content` permanently deletes every child block. None belongs
+            // under an approval named for property replacement.
             description: "Overwrite property values on an existing page. Every named property is replaced, not merged, so send a multi_select or relation's complete intended value. Cannot move a page and cannot trash one.",
             // Replaces values that already exist: the host should say so out loud.
             annotations: { readOnlyHint: false, destructiveHint: true },
@@ -1396,7 +1464,12 @@ function buildTools(defaultPageSize) {
 // ---------------------------------------------------------------------------
 // Guide and constructor
 // ---------------------------------------------------------------------------
-/** See documentation/notion.md#databases-contain-data-sources. */
+/**
+ * Marked `required` for one reason: a Notion database is a container, and the
+ * rows and schema live in a data source inside it. The id in a database URL is a
+ * database id, and passing it to `query_data_source` or `create_page` fails —
+ * a trap no input schema can teach, so the guide has to.
+ */
 function apiUsageGuide(purpose, instructions) {
     const accountInstructions = instructions?.trim();
     return `# Notion usage

package/dist/providers/revenuecat.d.ts

@@ -3,7 +3,12 @@ import type { Connector, ConnectorCallAdmissionPolicy } from "../types.js";
 /** RevenueCat publishes one hosted MCP endpoint, streamable HTTP. */
 export declare const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
 export interface RevenueCatOptions {
-    /** Display name; scope defaults are in `documentation/revenuecat.md`. */
+    /**
+     * Display name. It defaults to the credential's scope, because that is what
+     * decides how an agent must address the connector: `RevenueCat (single
+     * project)` for a project-wide `sk_` key, plain `RevenueCat` for an
+     * account-scoped OAuth session that must resolve a `project_id` first.
+     */
     title?: string;
     /** Downstream auth ownership. Defaults to one shared deployment grant. */
     authScope?: "shared" | "personal";
@@ -13,16 +18,37 @@ export interface RevenueCatOptions {
      * so it goes in the guide's first line and its summary.
      */
     purpose: string;
-    /** OAuth or a single-project API v2 key; see `documentation/revenuecat.md`. */
+    /**
+     * OAuth (account-scoped, reaches every project the account can see) or an
+     * API v2 `sk_` secret key, which RevenueCat scopes to exactly one project —
+     * hence one key, one connector, and no `project` option: checking a declared
+     * project against `list-projects` at construction would be the unasked-for
+     * credential test P10 forbids. Nor can Connecta tell a read-only key from a
+     * write-enabled one without spending a call, so every write is offered and a
+     * read-only key's refusal arrives from RevenueCat.
+     */
     auth?: RemoteMcpAuth;
     /** Project-specific conventions appended to the maintained provider guide. */
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
-    /** Optional per-runtime policy; see `documentation/revenuecat.md#rate-limits`. */
+    /**
+     * Optional per-runtime policy. There is no default even though RevenueCat
+     * publishes numbers (API v2, read 2026-08-18): the limit is per minute per
+     * domain — 480 for customer information, virtual currencies, and refunds; 60
+     * for audiences and project configuration; 25 for charts and metrics — and a
+     * policy carries one rule, so any single number is wrong for most tools. The
+     * metering scope is per developer for developer-level keys, which a
+     * per-runtime counter cannot approximate either. The operator picks (P12).
+     */
     callAdmission?: ConnectorCallAdmissionPolicy;
 }
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets
+ * and the verdict a check reads can never disagree. Names and verdicts only —
+ * no schemas are vendored; the live `tools/list` response stays authoritative.
+ */
 export declare const REVENUECAT_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained RevenueCat hosted-MCP connection. */
 export declare function revenuecat(id: string, options: RevenueCatOptions): Connector;

package/dist/providers/revenuecat.js

@@ -3,7 +3,12 @@ import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 import { defined } from "../connectors/api.js";
 /** RevenueCat publishes one hosted MCP endpoint, streamable HTTP. */
 export const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
-/** Reviewed reads; see `documentation/revenuecat.md` and convention P5. */
+/**
+ * Reviewed reads, every `Read` row of RevenueCat's tool reference as read on
+ * 2026-09-21 (P5). The list is a superset: plan, platform, and beta enrollment
+ * gate parts of the catalog, so a name this account never returns costs
+ * nothing while an unlisted new one fails closed.
+ */
 const READ_ONLY_TOOLS = new Set([
     // Projects and apps
     "get-account-billing",
@@ -18,7 +23,11 @@ const READ_ONLY_TOOLS = new Set([
     // Products and prices
     "get-product",
     "get-product-store-state",
+    // Deprecated in RevenueCat's reference — superseded by the plan family's
+    // own read-back below — but still served, so the classification stands.
     "get-product-store-state-operation",
+    "get-product-store-state-plan",
+    "list-product-store-state-plans",
     "list-products",
     // Entitlements
     "get-entitlement",
@@ -70,26 +79,65 @@ const READ_ONLY_TOOLS = new Set([
     // *start* one are writes and sit below.
     "get-paywall-ai-task",
 ]);
-/** Reviewed writes and verb exceptions: `documentation/revenuecat.md`. */
+/**
+ * Reviewed writes with their destructive verdict. Most follow the verb, and
+ * additive writes stay additive because `readOnlyHint: false` already routes
+ * them through the approval path — asserting a destruction that does not happen
+ * only inflates the copy a human reads. The verdicts the verb does not decide
+ * carry their reason on the row.
+ *
+ * `render-paywall-screenshot` is deliberately in neither map: RevenueCat's
+ * reference gives it no access column, so the live annotation stands and a
+ * catalog that omits one fails closed. Guessing from a harmless-sounding name
+ * is what P5 exists to prevent.
+ */
 const WRITE_TOOLS = new Map([
     // Projects and apps
     ["create-app", "additive"],
     ["create-project", "additive"],
     ["update-app", "destructive"],
     ["update-project-ui-config", "destructive"],
+    // Filed `Write` by RevenueCat, so it cannot take the read path, but it leaves
+    // the saved credentials alone and only records a check's outcome.
     ["validate-app-credentials", "additive"],
     // Products and prices
     ["archive-product", "destructive"],
     ["create-product", "additive"],
+    // Named `create-`, but "Configure prices for a product": the price set
+    // already exists, so this overwrites it, and it is money-facing. Deprecated
+    // in RevenueCat's reference; products are priced through the plan family
+    // below, but the tool is still served, so the classification stands.
     ["create-product-prices", "destructive"],
+    // "Fills *missing* App Store subscription territory prices" — by
+    // RevenueCat's own word it writes only where nothing is set. Deprecated in
+    // RevenueCat's reference; still served, so the classification stands.
     ["equalize-subscription-prices", "additive"],
+    // An upsert. Deprecated in RevenueCat's reference — the store-state plan
+    // family below replaces it — but still served, so the classification stands.
     ["set-product-store-state", "destructive"],
+    // Sends products to Apple for review.
     ["submit-products-to-store", "destructive"],
     ["unarchive-product", "destructive"],
     ["update-product", "destructive"],
+    // Reserves a new App Store Connect review screenshot slot; replaces nothing.
+    // Deprecated in RevenueCat's reference; still served, so the classification
+    // stands.
     ["upload-product-store-state-screenshot", "additive"],
+    // Product store state plans, the workflow RevenueCat deprecated
+    // `set-product-store-state` for. Create brings a draft into being and
+    // touches nothing else; plan recomputes an existing plan's proposed change,
+    // overwriting its previous planning; apply pushes the whole plan into
+    // RevenueCat and the app stores; update and discard act on an existing plan
+    // by name. Every step past create is asynchronous.
+    ["create-product-store-state-plan", "additive"],
+    ["plan-product-store-state-plan", "destructive"],
+    ["apply-product-store-state-plan", "destructive"],
+    ["update-product-store-state-plan", "destructive"],
+    ["discard-product-store-state-plan", "destructive"],
     // Entitlements
     ["archive-entitlement", "destructive"],
+    // Attach adds membership and removes nothing; detach is the destructive half.
+    // Filing both destructive would make the pair read identically to a human.
     ["attach-products-to-entitlement", "additive"],
     ["create-entitlement", "additive"],
     ["detach-products-from-entitlement", "destructive"],
@@ -97,6 +145,7 @@ const WRITE_TOOLS = new Map([
     ["update-entitlement", "destructive"],
     // Offerings and packages
     ["archive-offering", "destructive"],
+    // The attach/detach argument again, one level down.
     ["attach-products-to-package", "additive"],
     ["create-offering", "additive"],
     ["create-packages", "additive"],
@@ -107,9 +156,15 @@ const WRITE_TOOLS = new Map([
     // Targeting and audiences
     ["create-audience", "additive"],
     ["update-audience", "destructive"],
+    // Targeting rules follow the verb: create brings one into being, update
+    // and delete act on a rule the project already has.
+    ["create-targeting-rule", "additive"],
+    ["update-targeting-rule", "destructive"],
+    ["delete-targeting-rule", "destructive"],
     // Paywalls
     ["attach-offering-to-paywall", "destructive"],
     ["detach-offering-from-paywall", "destructive"],
+    // Copies an existing paywall's current draft; the original is untouched.
     ["duplicate-paywall", "additive"],
     ["publish-paywall", "destructive"],
     ["unpublish-paywall", "destructive"],
@@ -130,14 +185,23 @@ const WRITE_TOOLS = new Map([
     ["unarchive-virtual-currency", "destructive"],
     ["update-virtual-currency", "destructive"],
     // Integrations and webhooks
+    // Destructive on consequence, not on the verb: no existing integration
+    // changes, but with filters omitted the new one starts delivering every
+    // customer event in the project to a URL the caller typed.
     ["create-webhook-integration", "destructive"],
     ["delete-webhook-integration", "destructive"],
     ["update-webhook-integration", "destructive"],
-    // Paywall editing
+    // Paywall editing. Both start an async task; the difference is what the task
+    // touches — a new paywall, or a draft that already exists.
     ["create-paywall-ai", "additive"],
     ["edit-paywall-ai", "destructive"],
 ]);
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets
+ * and the verdict a check reads can never disagree. Names and verdicts only —
+ * no schemas are vendored; the live `tools/list` response stays authoritative.
+ */
 export const REVENUECAT_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,
@@ -166,7 +230,8 @@ function sharedUsageGuide() {
 - Customer and subscription objects are large, and a customer's history is larger. Page with the cursor the list returned rather than raising the page size, and reduce inside \`execute_code\` — select the fields the question needs and return those, not the whole object.
 - Whether a customer should have access is \`gives_access\` on each subscription from \`list-subscriptions\`, which RevenueCat calls the authoritative flag. \`status\` and \`expires_date\` describe the store-side state and disagree with it during grace periods, billing retries, and promotional grants — answer access questions from \`gives_access\` and say which subscription it came from.
 - \`get-chart-data\` is the metrics path: read \`get-chart-options-schema\` for the chart you want before calling it, rather than guessing an option name. \`get-overview-metrics\` and \`get-revenue-metric\` answer the summary questions in one call.
-- \`create-paywall-ai\`, \`edit-paywall-ai\`, and \`set-product-store-state\` are asynchronous. They return a task or operation id; poll it with \`get-paywall-ai-task\` or \`get-product-store-state-operation\` rather than assuming the work finished when the call returned.
+- \`create-paywall-ai\` and \`edit-paywall-ai\` are asynchronous. Poll the task id they return with \`get-paywall-ai-task\` rather than assuming the work finished when the call returned.
+- Store changes ride the plan workflow, not the deprecated direct tools: \`create-product-store-state-plan\`, then \`plan-product-store-state-plan\`, then \`apply-product-store-state-plan\`. Every step past the create is asynchronous — read the plan back with \`get-product-store-state-plan\` between steps instead of assuming the last one finished.
 - This connection's tool list is not a fixed set. RevenueCat gates parts of its MCP catalog by plan, platform, and beta enrollment — paywall AI editing, benchmarks, experiments, virtual currencies, and the account-billing tools are the usual absentees — so search this connector for what it actually exposes rather than assuming a documented tool is here.
 - \`render-paywall-screenshot\` is unclassified on purpose because RevenueCat's reference gives it no access column. The current server marks it read-only, which Connecta preserves; without that annotation it fails closed onto \`call_destructive_tool\`.
 - RevenueCat meters API v2 per minute and per domain, and the domains differ: 480 requests per minute for customer information and virtual currencies, 60 for project configuration and audiences, 25 for charts and metrics. It answers a breach with \`429\`, a \`Retry-After\` header, and a \`backoff_ms\` field. Back off on that rather than retrying immediately, and expect chart sweeps to hit the ceiling long before customer reads do.

package/dist/providers/stripe.d.ts

@@ -28,8 +28,9 @@ export interface StripeOAuthOptions extends StripeCommonOptions {
  * Static credentials have one fixed mode, including Stripe Connect calls.
  *
  * Both static shapes belong here: a key the deployment supplies as a literal
- * header, and one the operator pastes at `/credentials`. Neither can discover
- * its own mode — a restricted key answers for exactly one — so both declare it.
+ * header, and one the operator pastes into the connection in the operator UI.
+ * Neither can discover its own mode, since a restricted key answers for
+ * exactly one, so both declare it.
  */
 export interface StripeHeaderOptions extends StripeCommonOptions {
     auth: Exclude<RemoteMcpAuth, {
@@ -40,7 +41,13 @@ export interface StripeHeaderOptions extends StripeCommonOptions {
     connectedAccount?: string;
 }
 export type StripeOptions = StripeOAuthOptions | StripeHeaderOptions;
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets and
+ * the verdict a check reads can never disagree. Stripe publishes no stability or
+ * deprecation policy for this tool set, so treat it as unversioned: an
+ * unclassified, unannotated name fails closed onto the approval path (P5).
+ */
 export declare const STRIPE_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained Stripe hosted-MCP connection. */
 export declare function stripe(id: string, options: StripeOptions): Connector;

package/dist/providers/stripe.js

@@ -3,7 +3,14 @@ import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 import { defined } from "../connectors/api.js";
 /** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
-/** Account limits and local concurrency rationale: `documentation/stripe.md`. */
+/**
+ * Stripe documents no MCP-specific limit, so these transcribe the account limit
+ * MCP traffic spends: 100 requests per second live, 25 in a sandbox. OAuth takes
+ * the sandbox rule (`mode ?? "sandbox"` below) because one session can reach
+ * either mode and the policy is fixed before the account-scoped call begins.
+ * The `maxConcurrency` figures are Connecta's own choice — Stripe says
+ * per-account and per-endpoint concurrency limits exist but publishes no number.
+ */
 const STRIPE_ADMISSION = {
     production: {
         rules: [
@@ -47,16 +54,30 @@ const READ_ONLY_TOOLS = new Set([
     "manage_stripe_accounts",
     "search_stripe_documentation",
 ]);
-/** Reviewed writes, including mixed read/create tools: `documentation/stripe.md`. */
+/**
+ * Reviewed writes with their destructive verdict. `stripe_api_write` is the
+ * sibling of `stripe_api_read` and carries every `POST`, `PATCH`, `PUT`, and
+ * `DELETE`. Additive writes leave `destructiveHint` unset: `readOnlyHint: false`
+ * already routes them through the approval path, and asserting destruction they
+ * do not perform would misstate their effect.
+ */
 const WRITE_TOOLS = new Map([
     ["stripe_api_write", "destructive"],
     ["create_refund", "destructive"],
+    // Creates and continues provider-side guide state; destroys nothing.
     ["stripe_implementation_planner", "additive"],
+    // Retrieval mixed with query-run creation behind one tool.
     ["stripe_analytics", "additive"],
     ["stripe_report", "additive"],
     ["send_stripe_mcp_feedback", "additive"],
 ]);
-/** Release-reviewed manifest; see provider conventions P5 and P13. */
+/**
+ * One release-reviewed manifest, used both to classify a live tool and as the
+ * baseline the drift check compares against, so the annotation a caller gets and
+ * the verdict a check reads can never disagree. Stripe publishes no stability or
+ * deprecation policy for this tool set, so treat it as unversioned: an
+ * unclassified, unannotated name fails closed onto the approval path (P5).
+ */
 export const STRIPE_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,
@@ -64,7 +85,12 @@ export const STRIPE_VETTED_CATALOG = vettedCatalog({
 /** Stripe key prefixes carry their own mode; only a clear reading counts. */
 const LIVE_KEY = /\b(?:sk|rk|pk)_live_/;
 const TEST_KEY = /\b(?:sk|rk|pk)_test_/;
-/** Refuse a recognizable key/mode mismatch; see `documentation/stripe.md`. */
+/**
+ * Refuse a recognizable key/mode mismatch. This is the only mode guard Connecta
+ * can offer, and it needs the key as a literal header to read the prefix: an
+ * operator-managed key is not in the deployment file, so its declared mode
+ * stands alone and a key pointed at the other environment fails at Stripe.
+ */
 function assertModeMatchesKey(id, mode, auth) {
     if (auth.type !== "headers")
         return;