@zackbart/connecta 0.24.2 → 0.24.4

package/dist/providers/cloudflare.js

@@ -1,4 +1,14 @@
-/** See documentation/cloudflare.md#no-sdk-on-purpose. */
+/**
+ * No official `cloudflare` SDK on purpose. What the SDK sells — typed request
+ * wrappers and pagination helpers — is what this connection replaces: an agent
+ * gets a projected result and a `page.hasMore` boolean, so the SDK's types
+ * would be re-projected away at the boundary, and the dependency would cost an
+ * optional peer, an install step, and an import that never belongs in the root
+ * graph. Cloudflare's v4 API is authenticated `fetch` over a uniform
+ * `{ success, errors, messages, result, result_info }` envelope, so Web APIs
+ * alone keep this provider Workers-clean. `test/package-surface.test.ts` pins
+ * it: no `cloudflare` package in any dependency field, every import relative.
+ */
 import { api, defined } from "../connectors/api.js";
 import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
@@ -8,7 +18,11 @@ import { ConnectorCallError } from "../errors.js";
 export const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4";
 /** Cloudflare's official whole-API hosted MCP endpoint. */
 export const CLOUDFLARE_MCP_ENDPOINT = "https://mcp.cloudflare.com/mcp";
-/** See documentation/cloudflare.md#dns-record-types. */
+/**
+ * The 21 record types Cloudflare accepts. Eight carry a single `content`
+ * string; the other thirteen carry a per-type structured `data` object.
+ * `list_dns_records` filters on all 21 because reading them costs nothing.
+ */
 export const CLOUDFLARE_DNS_RECORD_TYPES = [
     "A",
     "AAAA",
@@ -32,7 +46,15 @@ export const CLOUDFLARE_DNS_RECORD_TYPES = [
     "TXT",
     "URI",
 ];
-/** Content-valued types only; see documentation/cloudflare.md#dns-record-types. */
+/**
+ * Content-valued types only, and the only types `create_dns_record` and
+ * `update_dns_record` accept. Covering the thirteen structured-`data` types
+ * would mean either a free-form `data` passthrough — the untyped body this
+ * connection exists to avoid — or thirteen more hand-written schemas for record
+ * types that are rare in day-to-day zone administration. They stay fully
+ * readable; writing one goes through the approval-gated raw mutation tool with
+ * Cloudflare's documented per-type `data` body.
+ */
 export const CLOUDFLARE_CONTENT_DNS_RECORD_TYPES = [
     "A",
     "AAAA",
@@ -43,7 +65,17 @@ export const CLOUDFLARE_CONTENT_DNS_RECORD_TYPES = [
     "PTR",
     "TXT",
 ];
-/** See documentation/cloudflare.md#rate-limits. */
+/**
+ * Cloudflare documents a global limit of 1,200 requests per five minutes per
+ * user, counted cumulatively across the dashboard, API keys, and API tokens
+ * (developers.cloudflare.com/fundamentals/api/reference/limits/). The matching
+ * rolling window here is a best-effort approximation, not an enforcement: each
+ * runtime keeps its own counter, so N isolates or processes can each admit
+ * 1,200, and a human's dashboard traffic counts for Cloudflare but not for us.
+ * `maxConcurrency` is the bound that actually protects a shared credential,
+ * because one `execute_code` program can fan out faster than the window
+ * notices.
+ */
 function admissionPolicy(maxConcurrency) {
     return {
         rules: [
@@ -155,7 +187,17 @@ function errorCodes(errors) {
  * would risk telling an agent its token was broken when its arguments were.
  * Genuine 10000 auth failures arrive with 401 or 403 and are caught by status.
  *
- * See documentation/cloudflare.md#typed-failures for provenance and routing.
+ * Provenance worth knowing before editing this set: Cloudflare publishes no
+ * official table mapping error codes to causes, so these six — and the 10000
+ * observation above — come from community reports and probing rather than
+ * documentation. They are well-supported readings Cloudflare could invalidate
+ * without notice; prefer `verify_api_token` or `verify_global_api_key` when a
+ * diagnosis actually matters.
+ *
+ * Cloudflare also rate-limits authentication failures separately from the
+ * global limit: a few requests with a bad token return 429 with code 10502.
+ * That is one more reason to diagnose a broken token once with a verify tool
+ * rather than by retrying real calls.
  */
 const AUTH_ERROR_CODES = new Set([1001, 6003, 6111, 9103, 9106, 9107]);
 /**
@@ -169,7 +211,9 @@ const AUTH_ERROR_CODES = new Set([1001, 6003, 6111, 9103, 9106, 9107]);
 function failureFor(status, headers, errors) {
     const detail = describeErrors(errors);
     const codes = errorCodes(errors);
-    // Ordering rationale: documentation/cloudflare.md#typed-failures.
+    // 429 is checked before the authentication codes on purpose: Cloudflare
+    // reuses the generic 10000 code on throttled responses, and reading a rate
+    // limit as an auth failure would tell an agent to stop when it should wait.
     if (status === 429) {
         const wait = retryAfterMs(headers);
         return new ConnectorCallError("rate_limited", `Cloudflare rate limit reached (HTTP 429). ${detail} The documented limit is 1,200 requests per five minutes per user, counted across the dashboard and every token.`, 
@@ -184,7 +228,10 @@ function failureFor(status, headers, errors) {
     if (status === 400 || status === 409 || status === 422) {
         return new ConnectorCallError("invalid_args", `Cloudflare rejected the request (HTTP ${status}). ${detail}`);
     }
-    // 404 rationale: documentation/cloudflare.md#typed-failures.
+    // Cloudflare refuses a token that may not touch a resource with 401 or 403,
+    // so a 404 here is a real absence rather than a permission gap wearing a
+    // miss — the unambiguous case `not_found` exists for, and something an agent
+    // can act on by re-running discovery for the id.
     if (status === 404) {
         return new ConnectorCallError("not_found", `Cloudflare found no such resource (HTTP 404). ${detail} Confirm the zone or account id with list_zones or list_accounts.`);
     }
@@ -576,7 +623,17 @@ const RAW_INPUT_PROPERTY = {
     type: "boolean",
     description: "Return Cloudflare's unprojected result instead of the lean shape. Use only when a field the projection drops is genuinely needed; the raw shape is much larger.",
 };
-/** Bound provenance: documentation/cloudflare.md#where-the-perpage-bounds-come-from. */
+/**
+ * Local enforcement of a `perPage` range is only a favor when the bound is
+ * really Cloudflare's, so `bounds` decides what the description admits to.
+ * `list_accounts`/`list_zones` (5–50) and `list_kv_namespaces` (1–1000) are
+ * Cloudflare's documented bounds. `list_dns_records` takes Cloudflare's
+ * minimum but is `clamped` at 1,000: Cloudflare's schema documents `per_page`
+ * on `/zones/{id}/dns_records` up to 5,000,000, a nominal ceiling no listing
+ * will honor, and a local cap an agent is told about beats a page size that
+ * fails somewhere inside Cloudflare. `list_pages_projects` is `undocumented` —
+ * Cloudflare publishes no bounds and no default for it, so 1–100 is ours.
+ */
 function pagingInputProperties(minPerPage, maxPerPage, options = {}) {
     const { defaultPerPage, bounds = "cloudflare" } = options;
     const defaultNote = defaultPerPage === undefined
@@ -601,7 +658,12 @@ function pagingInputProperties(minPerPage, maxPerPage, options = {}) {
         },
     };
 }
-/** Cursor convention: documentation/cloudflare.md#results. */
+/**
+ * Four endpoints — `list_zone_rulesets`, `list_r2_buckets`, `list_r2_objects`,
+ * `list_kv_keys` — page by cursor and get no `page` object. Both the argument
+ * and the result say so, so the loop condition is legible from either end of
+ * one tool rather than only to a reader who compared all of them.
+ */
 const CURSOR_INPUT_PROPERTY = {
     type: "string",
     description: "Opaque cursor from a previous call's nextCursor. This endpoint pages by cursor, not page number.",
@@ -1013,7 +1075,12 @@ const QUERY_INPUT_PROPERTY = {
         additionalProperties: false,
     },
 };
-// Header boundary: documentation/cloudflare.md#the-whole-v4-escape-hatch.
+// Connector-owned and refused: Authorization, Cookie, Host, Content-Length,
+// Content-Type, Transfer-Encoding — authentication, host selection, content
+// type, and request framing are not the caller's to set. That list stays out of
+// this description on purpose: the compact renderer inlines a shared property
+// description once per tool, and spelling the six out three times pushed
+// cloudflare_api_upload's compact input past the 1,024-byte discovery budget.
 const HEADERS_INPUT_PROPERTY = {
     type: "array",
     description: "Endpoint headers as name/value pairs, e.g. cf-r2-jurisdiction or Range. Connector-owned headers are refused.",
@@ -1412,7 +1479,11 @@ function buildTools(scope, authentication) {
                 path: "/zones",
                 query: {
                     name: optionalString(args, "name"),
-                    // Undefaulted on purpose — see documentation/cloudflare.md#scoping.
+                    // Undefaulted on purpose: list_zones is the discovery step,
+                    // and quietly filtering it by a configured accountId would
+                    // be a restriction in all but name — one with no argument
+                    // that escapes it, since an empty accountId would fall back
+                    // to the default again.
                     "account.id": optionalString(args, "accountId"),
                     status: optionalString(args, "status"),
                     page: optionalNumber(args, "page"),
@@ -1424,7 +1495,13 @@ function buildTools(scope, authentication) {
         cfTool("get_zone", "Fetch one zone's settings summary by id: status, plan, name servers, and owning account.", readOnly, "zoneId", scope.zoneId, {
             raw: RAW_INPUT_PROPERTY
         }, [], ZONE_SCHEMA, getResult(send, (args) => ({ method: "GET", path: `/zones/${encodeURIComponent(zoneArg(args))}` }), (result, args) => args["raw"] === true ? result : projectZone(result))),
-        // Removed tools: documentation/cloudflare.md#what-the-named-surface-deliberately-leaves-out.
+        // No bulk `list_zone_settings` on purpose (#361): Cloudflare's published
+        // document marks GET /zones/{zoneId}/settings and its PATCH sibling
+        // deprecated with no bulk replacement, and the tool projected nothing while
+        // *growing* the payload 22.7% by wrapping an unpaginated settings array in a
+        // page object. Read one setting here; an operator who genuinely wants the
+        // whole set names /zones/{zoneId}/settings through cloudflare_api_get, at
+        // the caller's risk rather than promised by connecta's catalog.
         cfTool("get_zone_setting", "Get one zone setting by its Cloudflare setting id, such as ssl, always_use_https, min_tls_version, brotli, or development_mode.", readOnly, "zoneId", scope.zoneId, {
             settingId: SETTING_ID_PROPERTY,
             raw: RAW_INPUT_PROPERTY
@@ -2019,8 +2096,18 @@ function buildTools(scope, authentication) {
             path: `/accounts/${encodeURIComponent(accountArg(args))}/r2/buckets/${encodeURIComponent(requireString(args, "bucketName"))}/objects/${encodeObjectKey(objectKey)}`,
             headers: r2Headers(args),
         }))),
-        // No `get_r2_metrics`, `set_r2_cors`, or `delete_r2_cors` on purpose (#350) —
-        // see documentation/cloudflare.md#what-the-named-surface-deliberately-leaves-out.
+        // No `get_r2_metrics`, `set_r2_cors`, or `delete_r2_cors` on purpose (#350).
+        // A named tool is a permanent line item in every deployment's catalog, and
+        // these lost the comparison against the escape hatches: `get_r2_metrics`
+        // took an account id, put it in a path, and returned the response untouched,
+        // which `cloudflare_api_get` at /accounts/{accountId}/r2/metrics already
+        // does. `set_r2_cors` declared its rule list as free-form objects — the
+        // untyped body refused everywhere else — and returned Cloudflare's response
+        // unprojected, so it beat the raw route on nothing. `delete_r2_cors`
+        // validated fine and went anyway, because naming only the delete would mean
+        // one CORS policy is set through the raw route and cleared through a named
+        // tool. Read with `get_r2_cors`; write with `cloudflare_api_mutate` at
+        // PUT/DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors.
         cfTool("get_r2_cors", "Get the browser CORS rules configured on an R2 bucket.", readOnly, "accountId", scope.accountId, {
             bucketName: R2_BUCKET_NAME_PROPERTY,
             jurisdiction: R2_JURISDICTION_PROPERTY
@@ -2342,8 +2429,12 @@ function buildTools(scope, authentication) {
             const zoneId = zoneArg(args);
             const targeted = ["files", "tags", "hosts", "prefixes"].filter((key) => Array.isArray(args[key]) && args[key].length > 0);
             const everything = args["everything"] === true;
-            // Cloudflare's purge body accepts exactly one variant. Refusing here
-            // turns a confusing provider 400 into a schema-shaped failure.
+            // One variant per call is this connection's contract, not a
+            // documented API restriction: Cloudflare's schema models the body as
+            // `anyOf`, which does not forbid combining. Refusing locally gives an
+            // agent `invalid_args` naming the conflict instead of a purge whose
+            // actual scope is ambiguous. Combined purging would be a deliberate
+            // change here.
             if (everything && targeted.length > 0) {
                 throw new ConnectorCallError("invalid_args", "purge_cache takes either everything: true or one targeted list, never both.", {
                     validation: {

package/dist/providers/linear.d.ts

@@ -19,18 +19,40 @@ export interface LinearOptions {
     authScope?: "shared" | "personal";
     /** Which workspace this is and what decisions it answers. */
     purpose: string;
-    /** Required endpoint selection; see `documentation/linear.md`. */
+    /**
+     * Endpoint selection, required with no default. Linear's read-only endpoint
+     * advertises the `read` scope alone, so its token cannot reach the write APIs
+     * — a stronger guarantee than any annotation. Neither default is safe:
+     * read-write hands out access nobody asked for, and read-only breaks a
+     * writing deployment at runtime, where no agent can repair it.
+     */
     access: LinearAccess;
-    /** OAuth or a personal API key; see `documentation/linear.md`. */
+    /**
+     * OAuth 2.1 with dynamic client registration by default. Linear's MCP server
+     * also accepts a personal API key in `Authorization: Bearer` — note this is
+     * the MCP endpoint's own documented contract, not the GraphQL API convention.
+     * A personal key carries the acting user's full permissions, so pair it with
+     * `access: "read-only"` unless the deployment genuinely writes.
+     */
     auth?: RemoteMcpAuth;
     /** Workspace-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/linear.md#rate-limits`. */
+    /**
+     * Optional per-runtime policy. There is no default: Linear documents no
+     * MCP-specific limit, the GraphQL limits it rides are metered per user per
+     * hour (and its own page disagrees with itself on the API-key figure), and
+     * Connecta's counter is per runtime. Only the operator knows the workspace.
+     */
     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 LINEAR_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained Linear hosted-MCP connection. */
 export declare function linear(id: string, options: LinearOptions): Connector;

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()
@@ -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,
@@ -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;