@zackbart/connecta 0.18.3 → 0.20.0

package/dist/providers/linear.d.ts

@@ -17,55 +17,18 @@ export interface LinearOptions {
     title?: string;
     /** Which workspace this is and what decisions it answers. */
     purpose: string;
-    /**
-     * Endpoint selection. Required, and deliberately undefaulted.
-     *
-     * `"read-only"` binds the connection to Linear's read-only endpoint, whose
-     * token is scope-limited downstream — a stronger guarantee than any
-     * annotation Connecta applies. `"read-write"` reaches the full API.
-     *
-     * Neither is a safe default. Defaulting to `"read-write"` hands a deployment
-     * write access it never asked for, and defaulting to `"read-only"` turns a
-     * deployment that does write into one whose every write fails at Linear —
-     * at runtime, where no agent can repair it. So the operator declares it, and
-     * a deployment that forgot fails here instead
-     * ([#342](https://github.com/zackbart/connecta/issues/342)).
-     */
+    /** Required endpoint selection; see `documentation/linear.md`. */
     access: LinearAccess;
-    /**
-     * OAuth by default. A Linear personal API key works either as a literal
-     * header or as an operator-managed credential (`{ type: "credential" }`).
-     * Linear's MCP documentation asks for `Authorization: Bearer <yourtoken>`
-     * for both API keys and OAuth tokens (https://linear.app/docs/mcp), which is
-     * the framing default, so the credential shape needs no `scheme` of its own.
-     */
+    /** OAuth or a personal API key; see `documentation/linear.md`. */
     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 call-admission policy. Deliberately not defaulted:
-     * Linear documents no MCP-specific limit, and the underlying API limit is
-     * per user per hour, varies by credential type, and is raised dynamically
-     * for workspace-level OAuth apps. A hardcoded per-runtime ceiling would
-     * either throttle a healthy deployment or fail to protect a busy one, so
-     * the number stays with the operator who knows the workspace.
-     */
+    /** Optional per-runtime policy; see `documentation/linear.md#rate-limits`. */
     callAdmission?: ConnectorCallAdmissionPolicy;
 }
-/**
- * The manifest this release reviewed: both lists in one place, which is what
- * makes the classification the connector applies and the drift check that runs
- * beside it the same fact (P13). No schema digests yet — no release has read
- * Linear's live schemas and written them down, and an invented digest would
- * report a change that never happened. `npm run drift:check -- --record` reads
- * them from a live workspace and prints the block to paste in
- * ([#351](https://github.com/zackbart/connecta/issues/351)).
- *
- * Exported because the maintainer-run check compares against this manifest and
- * *names* what moved, which the runtime check deliberately cannot.
- */
+/** Release-reviewed manifest; see provider conventions P5 and P13. */
 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

@@ -1,5 +1,6 @@
 import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
+import { defined } from "../connectors/api.js";
 /**
  * Linear publishes two hosted endpoints. `read-only` is not a client-side
  * filter: it advertises the `read` scope alone, so the token minted for it
@@ -10,16 +11,7 @@ export const LINEAR_MCP_ENDPOINTS = {
     "read-write": "https://mcp.linear.app/mcp",
     "read-only": "https://mcp.linear.app/mcp/readonly",
 };
-/**
- * Tools whose contract is observational rather than mutating.
- *
- * Linear's hosted catalog is not a fixed set — it varies by workspace plan and
- * enabled features (customer requests, releases, and code review are gated),
- * so this list is a superset of what any one workspace lists. A name here that
- * the workspace never returns costs nothing; a real read missing from it merely
- * fails closed. Only a write mistakenly listed here would be a safety bug,
- * which is why ambiguous helpers stay out.
- */
+/** Reviewed reads; see `documentation/linear.md` and provider convention P5. */
 const READ_ONLY_TOOLS = new Set([
     // Issues
     "list_issues",
@@ -77,17 +69,7 @@ const READ_ONLY_TOOLS = new Set([
     // than argues.
     "extract_images",
 ]);
-/**
- * The maintained write catalog. `"destructive"` tools modify or remove state
- * that already exists; `"additive"` ones only bring something new into being.
- * Both leave the read-only path — the distinction only decides whether the
- * connection asserts `destructiveHint`, which shapes the host's approval copy.
- *
- * Linear's `save_*` tools are upserts: passing an existing record's id updates
- * it in place. An upsert can therefore overwrite, so every `save_*` is
- * destructive even though some calls only create. The `create_*_label` tools
- * are the genuine creates.
- */
+/** Reviewed writes; `save_*` upsert rationale lives in `documentation/linear.md`. */
 const WRITE_TOOLS = new Map([
     // Issues
     ["save_issue", "destructive"],
@@ -127,18 +109,7 @@ const WRITE_TOOLS = new Map([
     ["save_customer_need", "destructive"],
     ["delete_customer_need", "destructive"],
 ]);
-/**
- * The manifest this release reviewed: both lists in one place, which is what
- * makes the classification the connector applies and the drift check that runs
- * beside it the same fact (P13). No schema digests yet — no release has read
- * Linear's live schemas and written them down, and an invented digest would
- * report a change that never happened. `npm run drift:check -- --record` reads
- * them from a live workspace and prints the block to paste in
- * ([#351](https://github.com/zackbart/connecta/issues/351)).
- *
- * Exported because the maintainer-run check compares against this manifest and
- * *names* what moved, which the runtime check deliberately cannot.
- */
+/** Release-reviewed manifest; see provider conventions P5 and P13. */
 export const LINEAR_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,
@@ -214,12 +185,10 @@ export function linear(id, options) {
             // guide adds cross-tool sequence advice that is worth reading before a
             // write, not worth loading before every read.
         },
-        ...(options.callAdmission !== undefined
-            ? { callAdmission: options.callAdmission }
-            : {}),
-        ...(options.maxResultBytes !== undefined
-            ? { maxResultBytes: options.maxResultBytes }
-            : {}),
+        ...defined({
+            callAdmission: options.callAdmission,
+            maxResultBytes: options.maxResultBytes,
+        }),
     });
     return withVettedCatalog(connector, LINEAR_VETTED_CATALOG);
 }

package/dist/providers/mixpanel.d.ts

@@ -11,12 +11,7 @@ export interface MixpanelOptions {
     title?: string;
     /** Who should use this account and for what decisions. */
     purpose: string;
-    /**
-     * Mixpanel data residency region. Defaults to `"us"`, which is where a
-     * project lives unless it was explicitly created in the EU or India
-     * residency — the other two are opt-in, so `"us"` is the honest default
-     * rather than a convenient one.
-     */
+    /** Data residency region; see `documentation/mixpanel.md`. */
     region?: MixpanelRegion;
     /**
      * OAuth by default; static headers support Mixpanel service accounts, and
@@ -28,27 +23,10 @@ export interface MixpanelOptions {
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
-    /**
-     * Optional per-runtime call-admission policy. Deliberately not defaulted:
-     * Mixpanel meters its MCP server per user per hour, and a per-runtime
-     * counter cannot approximate a per-user quota — one runtime serving several
-     * users under-counts, and several runtimes sharing one user over-counts.
-     * A hardcoded ceiling would therefore either throttle a healthy deployment
-     * or fail to protect a busy one, so the number stays with the operator who
-     * knows the account.
-     */
+    /** Optional per-runtime policy; see `documentation/mixpanel.md#rate-limits`. */
     callAdmission?: ConnectorCallAdmissionPolicy;
 }
-/**
- * The manifest this release reviewed: both lists in one place, which is what
- * makes the classification the connector applies and the drift check that runs
- * beside it the same fact (P13). The 2026-08-13 read-only audit recorded all
- * 63 live US schemas, so a later change is named by the maintainer-run drift
- * check rather than rediscovered in production (#395).
- *
- * Exported because the maintainer-run check compares against this manifest and
- * *names* what moved, which the runtime check deliberately cannot.
- */
+/** Release-reviewed manifest; see provider conventions P5 and P13. */
 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

@@ -1,5 +1,6 @@
 import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
+import { defined } from "../connectors/api.js";
 export const MIXPANEL_MCP_ENDPOINTS = {
     us: "https://mcp.mixpanel.com/mcp",
     eu: "https://mcp-eu.mixpanel.com/mcp",
@@ -43,12 +44,7 @@ const READ_ONLY_TOOLS = new Set([
     "Get-Feature-Flag-Setup-Guidance",
     "Get-Feature-Flag-Lifecycle-Guidance",
 ]);
-/**
- * The maintained write catalog. `"destructive"` tools modify or remove state
- * that already exists; `"additive"` ones only bring something new into being.
- * Both leave the read-only path — the distinction only decides whether the
- * connection asserts `destructiveHint`, which shapes the host's approval copy.
- */
+/** Reviewed writes; see provider convention P5. */
 const WRITE_TOOLS = new Map([
     ["Create-Dashboard", "additive"],
     ["Update-Dashboard", "destructive"],
@@ -145,16 +141,7 @@ const MIXPANEL_SCHEMA_DIGESTS = {
     "Update-Lookup-Table": "sha256:ef28f1ec9c9484a7a53b5e2b6659e70f79a8e71e55bda17025aa4ab3c23b6a63",
     "Update-Metric": "sha256:739bb6abdab19282afd4a6644a96183daabe9098a5322c44a77b840608a5ee9d",
 };
-/**
- * The manifest this release reviewed: both lists in one place, which is what
- * makes the classification the connector applies and the drift check that runs
- * beside it the same fact (P13). The 2026-08-13 read-only audit recorded all
- * 63 live US schemas, so a later change is named by the maintainer-run drift
- * check rather than rediscovered in production (#395).
- *
- * Exported because the maintainer-run check compares against this manifest and
- * *names* what moved, which the runtime check deliberately cannot.
- */
+/** Release-reviewed manifest; see provider conventions P5 and P13. */
 export const MIXPANEL_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,
@@ -237,12 +224,10 @@ export function mixpanel(id, options) {
             // carries the project-then-context sequence, which is worth reading
             // before an analysis rather than before every call.
         },
-        ...(options.callAdmission !== undefined
-            ? { callAdmission: options.callAdmission }
-            : {}),
-        ...(options.maxResultBytes !== undefined
-            ? { maxResultBytes: options.maxResultBytes }
-            : {}),
+        ...defined({
+            callAdmission: options.callAdmission,
+            maxResultBytes: options.maxResultBytes,
+        }),
     });
     return withVettedCatalog(connector, MIXPANEL_VETTED_CATALOG);
 }

package/dist/providers/notion.d.ts

@@ -1,21 +1,7 @@
 import type { Connector } from "../types.js";
 /** Notion's REST origin. Every tool below speaks to exactly this host. */
 export declare const NOTION_API_BASE_URL = "https://api.notion.com";
-/**
- * The API version this connection is written against, pinned deliberately.
- *
- * Notion's versions are date-named and old ones keep working indefinitely, so
- * a version override would look harmless. It is not: `2026-03-11` is the
- * version in which databases split into data sources, `archived` became
- * `in_trash`, and block append took a `position` object instead of `after`.
- * Every projection and every write body below assumes those shapes. A
- * deployment that pinned an older version would get silently wrong results
- * rather than a loud failure, so the option does not exist.
- *
- * Notion also ships additive changes to *every* version at once, which is why
- * the projections below degrade gracefully on unknown property and block types
- * rather than switching exhaustively.
- */
+/** See documentation/notion.md#the-pinned-api-version. */
 export declare const NOTION_API_VERSION = "2026-03-11";
 export interface NotionOptions {
     /** Human-readable display name; defaults to "Notion". */

package/dist/providers/notion.js

@@ -1,23 +1,9 @@
 import { api } from "../connectors/api.js";
-import { guardedFetch } from "../connectors/guarded-fetch.js";
+import { guardedFetch, retryAfterMs, } from "../connectors/guarded-fetch.js";
 import { ConnectorCallError } from "../errors.js";
 /** Notion's REST origin. Every tool below speaks to exactly this host. */
 export const NOTION_API_BASE_URL = "https://api.notion.com";
-/**
- * The API version this connection is written against, pinned deliberately.
- *
- * Notion's versions are date-named and old ones keep working indefinitely, so
- * a version override would look harmless. It is not: `2026-03-11` is the
- * version in which databases split into data sources, `archived` became
- * `in_trash`, and block append took a `position` object instead of `after`.
- * Every projection and every write body below assumes those shapes. A
- * deployment that pinned an older version would get silently wrong results
- * rather than a loud failure, so the option does not exist.
- *
- * Notion also ships additive changes to *every* version at once, which is why
- * the projections below degrade gracefully on unknown property and block types
- * rather than switching exhaustively.
- */
+/** See documentation/notion.md#the-pinned-api-version. */
 export const NOTION_API_VERSION = "2026-03-11";
 /** Notion's hard cap on `page_size` for every paginated endpoint. */
 const MAX_PAGE_SIZE = 100;
@@ -25,15 +11,7 @@ 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;
-/**
- * Ceiling on downstream requests inside one `get_page_content` call.
- *
- * Recursive block traversal is the one tool here that can turn a single agent
- * call into unbounded provider traffic, and call admission meters *tool calls*,
- * not the fetches inside them. A depth-2 walk of a large page would otherwise
- * spend the whole rate-limit budget without ever being rejected. When the walk
- * hits this ceiling it stops and says so in `truncated`.
- */
+/** See documentation/notion.md#rate-limiting. */
 const MAX_CONTENT_REQUESTS = 20;
 /**
  * The largest response this connection will read.
@@ -44,24 +22,7 @@ const MAX_CONTENT_REQUESTS = 20;
  * a budget any real read has to think about.
  */
 const NOTION_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
-/**
- * Approximates Notion's documented limit: "an average of three requests per
- * second, with some bursts beyond the average allowed" — expressed as a
- * rolling minute so short bursts pass and a sustained loop does not.
- *
- * `maxConcurrency` is the load-bearing half. A budget alone is an average, and
- * an averaged budget cannot stop a program from firing forty calls in the same
- * tick; the concurrency cap keeps a burst shaped roughly like the one Notion
- * documents. Neither half is a guarantee: admission meters *tool calls*, and
- * one admitted `get_page_content` can spend up to `MAX_CONTENT_REQUESTS`
- * fetches, so this bounds tool calls rather than requests. Declaring the cap is
- * also what makes the queue settings legal — the admission controller refuses
- * queue settings without a queue at construction.
- *
- * Per-runtime, like every connector budget: N Worker isolates or Node
- * processes serving one deployment each keep their own counter. This
- * approximates the provider's limit; it does not enforce it.
- */
+/** See documentation/notion.md#rate-limiting. */
 const NOTION_ADMISSION = {
     rules: [
         {
@@ -73,49 +34,24 @@ const NOTION_ADMISSION = {
         },
     ],
 };
-/** `Retry-After` is documented as an integer number of seconds, in decimal. */
-function parseRetryAfterMs(header) {
-    if (!header)
-        return undefined;
-    const seconds = Number(header.trim());
-    if (!Number.isFinite(seconds) || seconds < 0)
-        return undefined;
-    return Math.trunc(seconds * 1000);
-}
-/**
- * Map one Notion error response onto connecta's typed failures.
- *
- * The mapping is deliberately not one-to-one. Notion's `code` values describe
- * what its API thinks happened; connecta's codes describe what the *caller*
- * should do next, and two of Notion's are easy to mistranslate:
- *
- * - `restricted_resource` (403) is not `auth_required`. The token is fine; the
- *   integration lacks a capability or was never shared this object. Routing it
- *   to `auth_required` would send an agent to `authorize_connector`, which
- *   cannot fix it. It is a non-retryable call failure with instructions.
- * - `object_not_found` (404) is overloaded by Notion itself — it means "no
- *   such object" *or* "not shared with this integration", and the API will not
- *   say which. The message says both, because treating it as definitive
- *   absence is how an agent concludes a page was deleted when it simply was
- *   never shared.
- */
-function notionFailure(status, body, retryAfterHeader) {
+/** See documentation/notion.md#typed-failures. */
+function notionFailure(status, body, headers) {
     const code = typeof body?.["code"] === "string" ? body["code"] : undefined;
     const detail = typeof body?.["message"] === "string" && body["message"].trim()
         ? body["message"].trim()
         : `Notion returned HTTP ${status}.`;
-    const retryAfterMs = parseRetryAfterMs(retryAfterHeader);
+    const retryAfter = retryAfterMs(headers);
     const labelled = code ? `Notion ${code}: ${detail}` : detail;
     if (status === 429) {
         const additional = body?.["additional_data"];
         const reason = additional && typeof additional === "object"
             ? additional["rate_limit_reason"]
             : undefined;
-        return new ConnectorCallError("rate_limited", `${labelled}${typeof reason === "string" ? ` (limit: ${reason})` : ""} Notion allows roughly three requests per second per integration.`, { retryAfterMs: retryAfterMs ?? 1_000 });
+        return new ConnectorCallError("rate_limited", `${labelled}${typeof reason === "string" ? ` (limit: ${reason})` : ""} Notion allows roughly three requests per second per integration.`, { retryAfterMs: retryAfter ?? 1_000 });
     }
     if (status === 529) {
         // Notion documents 529 alongside 429: back off and respect Retry-After.
-        return new ConnectorCallError("unavailable", `${labelled} Notion is overloaded; retry after the reported window.`, { retryAfterMs: retryAfterMs ?? 5_000 });
+        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.`);
@@ -133,25 +69,16 @@ function notionFailure(status, body, retryAfterHeader) {
         return new ConnectorCallError("invalid_args", labelled);
     }
     if (status === 409) {
-        return new ConnectorCallError("unavailable", `${labelled} Notion reported a write conflict; this is safe to retry.`, { retryAfterMs: retryAfterMs ?? 1_000 });
+        return new ConnectorCallError("unavailable", `${labelled} Notion reported a write conflict; this is safe to retry.`, { retryAfterMs: retryAfter ?? 1_000 });
     }
     if (status >= 500) {
-        return new ConnectorCallError("unavailable", `${labelled} Notion is failing upstream.`, retryAfterMs !== undefined ? { retryAfterMs } : {});
+        return new ConnectorCallError("unavailable", `${labelled} Notion is failing upstream.`, retryAfter !== undefined ? { retryAfterMs: retryAfter } : {});
     }
     return new ConnectorCallError("connector_call_failed", labelled, {
         retryable: false,
     });
 }
-/**
- * The one transport every Notion tool goes through.
- *
- * URL confinement, `ctx.signal`, redirect refusal, bounded reads, and the
- * "could not reach the provider" normalization live in the shared helper. The
- * two things that cannot be shared stay here: the integration token becomes
- * the headers Notion accepts, and `notionFailure` decides what a status means
- * — which is the whole reason a generic HTTP client is the wrong shape, given
- * that Notion's 403 and 404 both mean something no status table would guess.
- */
+/** See documentation/connectors.md#the-guarded-fetch-transport. */
 const send = guardedFetch({
     provider: "Notion",
     baseUrl: NOTION_API_BASE_URL,
@@ -167,36 +94,17 @@ const send = guardedFetch({
 });
 async function notionRequest(ctx, request) {
     return await send(request, ctx, async (response) => {
-        let payload;
-        try {
-            // Notion answers a delete with an empty body and a gateway answers with
-            // HTML; neither is a payload, and neither is worth a different failure.
-            payload = (await response.json());
-        }
-        catch (cause) {
-            // A transport failure is not a parse failure. The connector's byte
-            // ceiling fires from inside this read, and swallowing it would report an
-            // oversized response as an empty success on a 2xx.
-            if (cause instanceof ConnectorCallError)
-                throw cause;
-            payload = undefined;
-        }
+        const parsed = await response.jsonResult();
+        const payload = "value" in parsed
+            ? parsed.value
+            : undefined;
         if (!response.ok) {
-            throw notionFailure(response.status, payload, response.headers.get("Retry-After"));
+            throw notionFailure(response.status, payload, response.headers);
         }
         return payload ?? {};
     });
 }
-// ---------------------------------------------------------------------------
-// Projections
-//
-// Notion's payloads are the reason this connection is hand-written. A single
-// page carries every property as a discriminated wrapper object, every string
-// as an array of rich-text runs each with its own annotations block, and every
-// user reference as a nested object. The projections below reduce that to what
-// an agent reasons about — ids, plain text, and flattened values — and each
-// tool that can lose information this way takes `raw: true` to opt out.
-// ---------------------------------------------------------------------------
+// Projections: documentation/notion.md#lean-projections-and-the-raw-escape-hatch.
 /** Concatenate a rich-text array to its plain text. Safe for every variant. */
 function plainText(value) {
     if (!Array.isArray(value))
@@ -380,14 +288,7 @@ function projectPage(page, select) {
         ...(truncated.length ? { truncated_properties: truncated } : {}),
     };
 }
-/**
- * Search returns pages and data sources; both get the identity fields only.
- *
- * Deliberately omits `properties`. A 25-result search over a populated
- * database would otherwise return several hundred flattened property values
- * for results the agent is about to discard — the exact bloat this connection
- * exists to remove. `get_page` fetches properties for the one that matched.
- */
+/** See documentation/notion.md#lean-projections-and-the-raw-escape-hatch. */
 function projectSearchHit(hit) {
     if (hit?.object === "data_source") {
         return {
@@ -454,12 +355,7 @@ function projectBlock(block, depth) {
             projected["icon"] = iconRef(payload?.icon);
             break;
         default:
-            // Notion adds block types to every API version at once, so an unhandled
-            // type is expected rather than exceptional — `meeting_notes` shipped in
-            // the very version pinned above. A payload built around `rich_text` is
-            // already fully represented by `text`; one that is not would otherwise
-            // project to an empty string and lose its entire body, so it keeps the
-            // payload verbatim. `color` alone is presentation, not content.
+            // Rationale: documentation/notion.md#lean-projections-and-the-raw-escape-hatch.
             if (carriesUnprojectedContent(payload))
                 projected["raw"] = payload;
             break;
@@ -683,6 +579,15 @@ function listEnvelope(payload, results) {
         next_cursor: payload?.next_cursor ?? null,
     };
 }
+function mappedListEnvelope(payload, project) {
+    return listEnvelope(payload, (payload?.results ?? []).map(project));
+}
+function pagination(args, defaultPageSize) {
+    return {
+        page_size: resolvePageSize(args.page_size, defaultPageSize),
+        ...(args.start_cursor ? { start_cursor: args.start_cursor } : {}),
+    };
+}
 /** Exactly-one-of validation, phrased so the agent knows what to send next. */
 function requireExactlyOne(provided, hint) {
     const present = provided.filter(([, value]) => value !== undefined && value !== null && value !== "");
@@ -741,13 +646,9 @@ function buildTools(defaultPageSize) {
                 required: ["id", "object", "title"],
             }),
             handler: async (args, ctx) => {
-                const body = {
-                    page_size: resolvePageSize(args.page_size, defaultPageSize),
-                };
+                const body = pagination(args, defaultPageSize);
                 if (args.query)
                     body["query"] = args.query;
-                if (args.start_cursor)
-                    body["start_cursor"] = args.start_cursor;
                 if (args.object_type) {
                     body["filter"] = { property: "object", value: args.object_type };
                 }
@@ -767,7 +668,7 @@ function buildTools(defaultPageSize) {
                 });
                 if (args.raw)
                     return payload;
-                return listEnvelope(payload, (payload?.results ?? []).map(projectSearchHit));
+                return mappedListEnvelope(payload, projectSearchHit);
             },
         },
         {
@@ -826,14 +727,9 @@ function buildTools(defaultPageSize) {
                 additionalProperties: false,
             },
             outputSchema: {
-                type: "object",
+                ...listOutputSchema(BLOCK_OUTPUT_SCHEMA),
                 properties: {
-                    results: { type: "array", items: BLOCK_OUTPUT_SCHEMA },
-                    has_more: {
-                        type: "boolean",
-                        description: "True when the top level has another page of blocks.",
-                    },
-                    next_cursor: { type: ["string", "null"] },
+                    ...listOutputSchema(BLOCK_OUTPUT_SCHEMA)["properties"],
                     truncated: {
                         type: "boolean",
                         description: "True when the nested walk stopped at its request ceiling. Some descendants are missing; re-read a specific block_id to continue.",
@@ -846,10 +742,7 @@ function buildTools(defaultPageSize) {
                 const top = await notionRequest(ctx, {
                     method: "GET",
                     path: `/v1/blocks/${encodeURIComponent(args.block_id)}/children`,
-                    query: {
-                        page_size: pageSize,
-                        ...(args.start_cursor ? { start_cursor: args.start_cursor } : {}),
-                    },
+                    query: pagination(args, pageSize),
                 });
                 if (args.raw)
                     return top;
@@ -927,10 +820,7 @@ function buildTools(defaultPageSize) {
                 const payload = await notionRequest(ctx, {
                     method: "GET",
                     path: `/v1/pages/${encodeURIComponent(args.page_id)}/properties/${encodeURIComponent(args.property_id)}`,
-                    query: {
-                        page_size: resolvePageSize(args.page_size, defaultPageSize),
-                        ...(args.start_cursor ? { start_cursor: args.start_cursor } : {}),
-                    },
+                    query: pagination(args, defaultPageSize),
                 });
                 if (args.raw)
                     return payload;
@@ -939,7 +829,7 @@ function buildTools(defaultPageSize) {
                         // A list envelope's own `type` is the literal "property_item";
                         // the property's real type sits one level down.
                         type: payload?.property_item?.type ?? payload?.type ?? null,
-                        ...listEnvelope(payload, (payload?.results ?? []).map(projectPropertyItem)),
+                        ...mappedListEnvelope(payload, projectPropertyItem),
                     };
                 }
                 return {
@@ -1105,15 +995,11 @@ function buildTools(defaultPageSize) {
             },
             outputSchema: listOutputSchema(PAGE_OUTPUT_SCHEMA),
             handler: async (args, ctx) => {
-                const body = {
-                    page_size: resolvePageSize(args.page_size, defaultPageSize),
-                };
+                const body = pagination(args, defaultPageSize);
                 if (args.filter)
                     body["filter"] = args.filter;
                 if (args.sorts)
                     body["sorts"] = args.sorts;
-                if (args.start_cursor)
-                    body["start_cursor"] = args.start_cursor;
                 const payload = await notionRequest(ctx, {
                     method: "POST",
                     path: `/v1/data_sources/${encodeURIComponent(args.data_source_id)}/query`,
@@ -1121,7 +1007,7 @@ function buildTools(defaultPageSize) {
                 });
                 if (args.raw)
                     return payload;
-                return listEnvelope(payload, (payload?.results ?? []).map((row) => projectPage(row, args.properties)));
+                return mappedListEnvelope(payload, (row) => projectPage(row, args.properties));
             },
         },
         {
@@ -1142,12 +1028,9 @@ function buildTools(defaultPageSize) {
                 const payload = await notionRequest(ctx, {
                     method: "GET",
                     path: "/v1/users",
-                    query: {
-                        page_size: resolvePageSize(args.page_size, defaultPageSize),
-                        ...(args.start_cursor ? { start_cursor: args.start_cursor } : {}),
-                    },
+                    query: pagination(args, defaultPageSize),
                 });
-                return listEnvelope(payload, (payload?.results ?? []).map(projectUser));
+                return mappedListEnvelope(payload, projectUser);
             },
         },
         {
@@ -1206,13 +1089,12 @@ function buildTools(defaultPageSize) {
                     path: "/v1/comments",
                     query: {
                         block_id: args.block_id,
-                        page_size: resolvePageSize(args.page_size, defaultPageSize),
-                        ...(args.start_cursor ? { start_cursor: args.start_cursor } : {}),
+                        ...pagination(args, defaultPageSize),
                     },
                 });
                 if (args.raw)
                     return payload;
-                return listEnvelope(payload, (payload?.results ?? []).map(projectComment));
+                return mappedListEnvelope(payload, projectComment);
             },
         },
         // --------------------------------------------------------------- writes
@@ -1221,12 +1103,7 @@ 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: {
-                // Empty rather than absent: a parent is required, but *which* parent is
-                // an exclusive choice a plain-object `required` list cannot express,
-                // and the top-level `anyOf` that could would cost the tool its
-                // `inputKeys` in discovery. The choice is stated in both parent
-                // descriptions and enforced locally as `invalid_args` before any round
-                // trip ([#342](https://github.com/zackbart/connecta/issues/342)).
+                // See documentation/notion.md#what-this-connection-does-not-do.
                 required: [],
                 type: "object",
                 properties: {
@@ -1515,13 +1392,7 @@ function buildTools(defaultPageSize) {
 // ---------------------------------------------------------------------------
 // Guide and constructor
 // ---------------------------------------------------------------------------
-/**
- * Only what the schemas cannot carry.
- *
- * Marked `required` because the database/data-source split is a mandatory
- * cross-tool sequence, not advice: a caller who reaches for `query_data_source`
- * with the id in a Notion URL gets a failure no schema warned it about.
- */
+/** See documentation/notion.md#databases-contain-data-sources. */
 function usageGuide(purpose, instructions) {
     const accountInstructions = instructions?.trim();
     return `# Notion usage