@zackbart/connecta 0.12.2 → 0.14.0

package/documentation/linear.md

@@ -0,0 +1,144 @@
+# Linear prebuilt connection
+
+Import `linear()` independently from `@zackbart/connecta/providers/linear`. It
+wraps Linear's hosted MCP server with endpoint selection, OAuth by default, a
+task-oriented usage guide, and a vetted safety classification. It adds no
+provider dependency and is not reachable from Connecta's root entry.
+
+```ts
+import { linear } from "@zackbart/connecta/providers/linear";
+
+const tracker = linear("product_tracker", {
+  title: "Product issue tracking",
+  purpose: "Issue and project planning for the platform team",
+  instructions: "File bugs into the Platform team unless the request names another.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Linear workspace or access mode. `purpose` is required because an agent
+choosing between two instances needs to know which workspace answers the
+question. Workspace `instructions` are appended to the maintained guide and
+cannot change the connector's safety classification.
+
+## Access modes
+
+Linear publishes two hosted endpoints, and `access` selects between them:
+
+| `access` | Endpoint | OAuth scopes |
+| --- | --- | --- |
+| `"read-write"` (default) | `https://mcp.linear.app/mcp` | `read`, `write` |
+| `"read-only"` | `https://mcp.linear.app/mcp/readonly` | `read` |
+
+Read-only is not a client-side filter. The endpoint advertises the `read` scope
+alone, so the token minted for it cannot reach Linear's write APIs — a stronger
+guarantee than any annotation Connecta applies. A deployment that only reports
+on delivery should use it, and can run it beside a read-write instance under a
+different id:
+
+```ts
+linear("delivery_reporting", {
+  purpose: "Executive delivery reporting",
+  access: "read-only",
+});
+```
+
+The mode is legible at browse time, not only after the guide is fetched. A
+read-only connection titles itself `Linear (read-only)` unless the operator
+gives a `title`, and its guide opens with the access note rather than the
+workspace purpose — `search_tools` renders a connector's title and guide
+summary but never its description, and the summary is the guide's first content
+line.
+
+Linear's deprecated `/sse` transport is deliberately unreachable from this
+connection; it now answers 404.
+
+## Authentication
+
+OAuth 2.1 with dynamic client registration is the default and keeps each
+connector instance's flow and tokens in its connector-scoped storage. Linear
+also accepts a bearer token or a personal API key passed directly in the
+`Authorization` header, which suits a headless deployment:
+
+```ts
+linear("automation_tracker", {
+  purpose: "Headless release reporting",
+  auth: {
+    type: "headers",
+    headers: { Authorization: env.LINEAR_API_KEY },
+  },
+});
+```
+
+Keep that key in the runtime's secret store; it is a password, not ordinary
+configuration. A personal API key carries the acting user's full workspace
+permissions, so pair it with `access: "read-only"` unless the deployment
+genuinely writes.
+
+## Safety classification
+
+The wrapper classifies Linear's documented `list_*`, `get_*`, and
+`search_documentation` tools as reads, and its `save_*`, `create_*`, `delete_*`,
+`resolve_*`, `submit_*`, and `merge_*` tools as writes. An unfamiliar tool the
+downstream leaves unannotated fails closed onto `call_destructive_tool` until a
+Connecta release reviews it.
+
+That classification is **fill-in only**, and unconditionally so: it supplies
+the annotations Linear leaves unset and contradicts an explicit downstream
+annotation in neither direction. A tool on the read allowlist arriving with
+`destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
+downstream said and stays behind `call_destructive_tool`. A tool on neither
+maintained list arriving with `readOnlyHint: true` keeps that too, and stays
+callable from `execute_code`. Both are the downstream telling you this
+release's allowlist is stale, and on a name no release has reviewed its word is
+the only evidence there is. The one classification that still outranks the
+downstream is a name this release reviewed and filed destructive: a `save_*`
+tool claiming `readOnlyHint: true` is a downstream bug rather than news, and
+stays on the approval path.
+
+One detail of Linear's own design shapes the classification: **`save_*` tools
+are upserts.** Omitting a record id creates; supplying one updates in place.
+Because an upsert can overwrite, every `save_*` is classified destructive even
+though some calls only create. The genuine creates are `create_issue_label` and
+`create_initiative_label`, plus the attachment upload tools, which assert
+`readOnlyHint: false` without claiming a destruction they do not perform.
+
+## The catalog is not a fixed set
+
+Linear's hosted `tools/list` varies by workspace plan and enabled features:
+customer requests, releases, and code review do not appear in every workspace.
+The maintained allowlists are therefore a superset — a classified name a
+workspace never returns costs nothing, and a genuinely new tool fails closed.
+Agents should search this connector's catalog for what the workspace actually
+exposes rather than assuming a tool exists; the usage guide says so explicitly.
+
+## Rate limits
+
+Linear documents no MCP-specific rate limit. The MCP server rides the
+[GraphQL API limits](https://linear.app/developers/rate-limiting), which are
+metered **per user per hour** and shared with everything else that credential
+does. Linear's own page is internally inconsistent on the API-key request
+figure — the prose says 5,000 requests per hour while the table below it says
+2,500 for an API key and 5,000 for an OAuth app, against 600 unauthenticated —
+and limits are raised dynamically for workspace-level OAuth apps using Actor
+Authorization.
+
+For that reason this connection declares **no call-admission budget by
+default**. Connecta's counter is per runtime, not per user, so a hardcoded
+ceiling would either throttle a healthy deployment or fail to protect a busy
+one. An operator who knows their workspace can supply one explicitly:
+
+```ts
+linear("product_tracker", {
+  purpose: "Issue and project planning for the platform team",
+  callAdmission: {
+    rules: [
+      { budget: { kind: "rolling-window", maxCalls: 1_000, windowMs: 3_600_000 } },
+    ],
+  },
+});
+```
+
+A budget-only rule needs no queue. If you add `maxConcurrency` you are asking
+for a queue, and the admission controller then requires the rest of the queue
+settings at construction.

package/documentation/meta-tools.md

@@ -19,6 +19,21 @@ The consolidation removed overlapping routing choices while preserving the
 cheaper direct path for one cold call. The [guest API contract](./code-mode.md)
 is what a program is promised.
 
+The route is chosen before discovery. A result that will be reduced, a call
+whose arguments depend on an earlier result, or work with multiple operations
+starts with one `execute_code` call and keeps discovery, calls, and reduction
+inside it. Distinct operations get distinct short `connecta.search` queries in
+that program. Only one unknown-address read takes the cheaper top-level
+`search_tools` → `call_tool` path; a known address needs only `call_tool`.
+
+That routing is about read-only work, because that is the only work a program
+can do. Anything unannotated, write-capable, or destructive is inadmissible
+inside the sandbox, so multi-step destructive work discovers at the top level
+and runs each step through `call_destructive_tool` — where the host can put the
+question to a human. Telling an agent never to search at the top level for
+multiple calls would close the only route that work has
+([#295](https://github.com/zackbart/connecta/issues/295)).
+
 `execute_code` accepts optional `diagnostics: true` when a caller is measuring
 a workflow. It adds only compact request-local timing and serialized-size
 aggregates; normal calls carry no diagnostics block or response-context cost.
@@ -35,17 +50,23 @@ probing is an operator concern: the operator pages and `/health` own it.
 
 Start an unknown-address lookup with two to four distinctive action/object
 terms, not the full request, and omit `limit` so the default eight-result page
-stays small. Set `safety: "readOnly"` when the result is headed to `call_tool`
-or generated code; `safety: "approvalRequired"` finds the complementary set
-that must cross `call_destructive_tool`. Omitting `safety`, or setting it to
-`"all"`, preserves the complete configured catalog. This is only a discovery
-filter: it neither grants authority nor changes invocation admission.
+stays small. When the integration is obvious, set `connector` to its id: a
+scoped search loads that catalog alone, while an unscoped search must fan out
+across every configured connector. Leave the search unscoped when the right
+integration is genuinely ambiguous. Set `safety: "readOnly"` when the result is
+headed to `call_tool` or generated code; `safety: "approvalRequired"` finds the
+complementary set that must cross `call_destructive_tool`. Omitting `safety`,
+or setting it to `"all"`, preserves the complete configured catalog. This is
+only a discovery filter: it neither grants authority nor changes invocation admission.
 `includeSchemas: "compact"` adds each match's input and any declared output
 shape. Bounded plain-object schemas also expose `inputKeys`,
 `requiredInputKeys`, and `outputKeys`; a truncated shape omits its corresponding
 list rather than repeating a large partial inventory. Matches carry declared
-behavior annotations. When
-that shape is sufficient, call the returned address directly. Reserve schema
+behavior annotations. Lexical rank is only one signal: select a candidate whose
+required inputs are available, whose schema is complete enough for the call,
+and whose safety and declared outputs fit the work. A reducer uses `outputKeys`
+before inspecting the value; it does not assume a collection is named `items`
+or `results`. When that shape is sufficient, call the returned address directly. Reserve schema
 expansion through `connecta.describe` for a search without schemas, an
 ambiguous compact shape, or exact
 constraints that require `format: "json"`.
@@ -60,6 +81,51 @@ types; other shapes become `unknown /* truncated */`. The match also carries
 `includeSchemas: "json"` or use the existing describe path when exact
 constraints matter.
 
+## Connector guide selection
+
+A connector may attach a deployment-owned guide as markdown, preserving the
+original `usageGuide: string` configuration, or as
+`{ content, summary?, required? }`. The structured form does not register a
+connector or create a shared runtime template. `content` remains the markdown
+returned verbatim by `skills`; `summary` is normalized and capped at 120
+characters for discovery. When it is absent, Connecta derives the same bounded
+fallback used by the skills listing: the first meaningful body line, with a
+heading used only when the guide has no body. `required: true` is reserved for generic
+API wrappers and cross-operation conventions a complete downstream schema
+cannot express.
+
+Search and describe results keep the existing `guide: "connector:<id>"`
+pointer and add `guideSummary`. A matching tool also carries
+`guideRequired: true` and `guideRequiredReasons` when Connecta can prove review
+is necessary:
+`connector_required` for the explicit configuration above,
+`approval_required` for an unannotated or write-capable tool, and
+`schema_truncated` when a requested compact input or output shape was capped.
+The boolean is an instruction, not a server-side gate — nothing refuses the
+call, so the agent is told to fetch the guide before making it, for any reason
+listed. `connector_required` and `approval_required` survive exact schema
+expansion; `schema_truncated` is cleared by the describe that returns the exact
+shape, and describe reports whatever reasons remain in the same two fields.
+Otherwise it reads the
+bounded summary: connector-specific sequencing, units, pagination, aliases,
+and generic API conventions still require the guide when they affect the task,
+while a complete and unambiguous one-read schema proceeds directly.
+Guide lookup always uses an exact name returned by `skills({})`, search, or
+describe; callers do not manufacture `connector:<id>` from an unmarked
+connector.
+
+A connector-scoped lexical miss retains that connector's guide metadata under
+`queryAnalysis`. This matters for generic wrappers whose broad tool name does
+not contain endpoint vocabulary: a required guide remains discoverable before
+the caller falls back to an empty-query browse, rather than disappearing with
+the zero-tool page.
+
+The built-in `usage` skill is byte-identical across deployments and says to
+read it at most once per task. Connector guides remain scoped to the deployment
+that listed them, even when two deployments happen to use identical content.
+Deployments without connector guides receive none of the conditional guide
+sentences in their always-loaded tool descriptions.
+
 ## Result representation
 
 For object results, `structuredContent` is the canonical full-fidelity value.
@@ -122,7 +188,24 @@ results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
 configured and recommends refining, connector-scoping, or browsing; when a
 connector catalog was unavailable, the response includes
-`unavailableConnectorCount` instead of making that stronger claim. Analysis
+`unavailableConnectorCount` instead of making that stronger claim. A search
+explicitly scoped to that unavailable connector also receives `catalogError` —
+the bounded classified failure (`code`, `message`, `retryable`, and any
+`retryAfterMs`) so the caller can tell a transient outage from one a deployment
+operator must clear. It carries nothing else the call-path classifier knows: a
+discovery read is not a call. Unscoped searches keep the count only — one
+connector's failure is not another search's context. An empty query browses
+rather than searches, so it reports no term analysis — except when the scope
+itself failed, where the same fields apply. A browse scoped to an unavailable
+connector carries `unavailableConnectorCount`, `catalogError`, and guidance,
+and an unscoped browse again carries the count alone. A browse scoped to an ID
+that is not configured at all carries `connectorScope`, `unknownConnector`, and
+the same omit-the-connector guidance the term-bearing path gives — nothing was
+attempted, so there is no count and no `catalogError` — and it names no
+connector but the one the caller supplied. A connector that correctly exposes
+no tools still reports no analysis, so the two do not serialize alike. The
+advice to browse a connector with an empty query must not land in silence that
+reads like a connector with no tools. Analysis
 from a connector-filtered search includes `connectorScope` and speaks only
 about that connector; `unknownConnector` distinguishes an unconfigured ID from
 a known connector with no match. Analysis covers at most eight distinct terms

package/documentation/mixpanel.md

@@ -0,0 +1,77 @@
+# Mixpanel prebuilt connection
+
+Import `mixpanel()` independently from
+`@zackbart/connecta/providers/mixpanel`. It wraps Mixpanel's hosted MCP server
+with regional endpoint selection, OAuth by default, a provider-rate admission
+budget, a task-oriented usage guide, and a vetted safety classification. It
+adds no provider dependency and is not reachable from Connecta's root entry.
+
+```ts
+import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
+
+const analytics = mixpanel("product_analytics", {
+  title: "Production product analytics",
+  purpose: "Product and growth decisions for the production app",
+  region: "us",
+  instructions: "Use the Core Product project unless the request says otherwise.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Mixpanel account. `purpose` is required because an agent choosing between two
+instances needs to know which account answers the question. Account
+`instructions` are appended to the maintained guide and cannot change the
+connector's safety classification.
+
+`region` accepts `"us"` (the default), `"eu"`, or `"in"` and selects the
+corresponding [official hosted endpoint](https://docs.mixpanel.com/docs/mcp#mcp-server-urls).
+OAuth is the recommended default and keeps each connector instance's flow and
+tokens in its connector-scoped storage. Mixpanel service accounts are also
+supported with an explicit header override:
+
+```ts
+mixpanel("automation_analytics", {
+  purpose: "Headless release-health reporting",
+  auth: {
+    type: "headers",
+    headers: { Authorization: `Bearer Basic ${env.MIXPANEL_SA_TOKEN}` },
+  },
+});
+```
+
+Keep that encoded service-account value in the runtime's secret store; it is a
+password, not ordinary configuration. Mixpanel currently labels service-account
+MCP authentication beta. Prefer OAuth unless the deployment is intentionally
+headless.
+
+The wrapper classifies the documented observational tools as reads and the
+documented create, update, edit, merge, dismiss, duplicate, and delete tools as
+writes. An unfamiliar tool the downstream leaves unannotated fails closed onto
+`call_destructive_tool` until a Connecta release reviews it.
+
+That classification is **fill-in only**, and unconditionally so: it supplies
+the annotations Mixpanel leaves unset and contradicts an explicit downstream
+annotation in neither direction. A tool on the read allowlist arriving with
+`destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
+downstream said and stays behind `call_destructive_tool`. A tool on neither
+maintained list arriving with `readOnlyHint: true` keeps that too, and stays
+callable from `execute_code`. Both are the downstream telling you this
+release's allowlist is stale, and on a name no release has reviewed its word is
+the only evidence there is. The one classification that still outranks the
+downstream is a name this release reviewed and filed destructive: a
+`Delete-Dashboard` claiming `readOnlyHint: true` is a downstream bug rather
+than news, and stays on the approval path. Maintained writes that only create
+something new (`Create-Dashboard`, `Create-Cohort`, `Create-Metric`, and the
+rest) leave `destructiveHint` unset; `readOnlyHint: false` already routes them
+through the destructive path, and asserting destruction only inflates the
+approval copy the host shows a human.
+
+Experiments and Feature Flags — 15 of the 63 classified tools — are Mixpanel
+beta surfaces. Expect their names and schemas to move faster than the rest.
+
+The connection also declares a per-runtime call-admission budget matching
+Mixpanel's documented 600 requests per hour — a best-effort approximation of
+the per-user limit, not an enforcement of it. Each runtime keeps its own
+counter, so N Worker isolates or Node processes serving one deployment can each
+admit up to 600. Discovery traffic is outside connector call admission and
+still needs restrained use.

package/documentation/notion.md

@@ -0,0 +1,233 @@
+# Notion prebuilt connection
+
+Import `notion()` independently from `@zackbart/connecta/providers/notion`. It
+is a hand-written `api()` surface over Notion's public REST API — fifteen
+deliberate tools, lean projections of Notion's famously bloated payloads, typed
+failures, a rate budget matched to the documented limit, and a required usage
+guide. It adds no provider dependency, imports no `node:` builtin, and is not
+reachable from Connecta's root entry.
+
+```ts
+import { notion } from "@zackbart/connecta/providers/notion";
+
+const wiki = notion("engineering_wiki", {
+  title: "Engineering wiki",
+  purpose: "Runbooks, specs, and on-call notes for the platform team",
+  instructions: "Prefer the Runbooks database; specs live under Projects.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Notion workspace. `purpose` is required because an agent choosing between two
+instances needs to know which workspace answers the question. Workspace
+`instructions` are appended to the maintained guide and cannot change the
+connector's safety classification.
+
+## Why this one is `api()` and not `remoteMcp()`
+
+Notion publishes an MCP server, but the interesting problem here is not
+transport — it is shape. A single Notion page returns every property as a
+discriminated wrapper object, every string as an array of rich-text runs each
+carrying its own annotations block, and every user reference as a nested
+object. A twenty-five row database query is tens of kilobytes of structure
+around a few hundred bytes of meaning. Hand-writing the surface is what makes
+the projections possible, and the projections are the point.
+
+## Authentication
+
+One operator-managed credential: an internal integration token from
+[notion.so/profile/integrations](https://www.notion.so/profile/integrations).
+The deployment needs `credentials.encryptionKey` configured, or the token
+cannot be stored and every call fails `auth_required` at use.
+
+Two Notion-specific facts decide whether a working token is enough:
+
+- **Sharing is per object.** A token reaches only what has been explicitly
+  shared with its integration. An unshared page returns 404, not 403.
+- **Capabilities are per integration**, and the comment capabilities are off by
+  default. `list_comments` and `add_comment` fail with 403 until an operator
+  turns them on in Notion.
+
+`/credentials` offers a Test action, which calls `GET /v1/users/me` — the
+cheapest call that proves a token is live — and reports the workspace it
+authenticated into.
+
+## The pinned API version
+
+The connection pins `Notion-Version: 2026-03-11` and offers no override. That
+is deliberate rather than lazy. Notion's versions are date-named and old ones
+keep working indefinitely, so an 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 an `after` string. Every projection and write body here assumes those
+shapes, so a deployment that pinned an older version would get quietly wrong
+results instead of a loud failure.
+
+Notion also ships *additive* changes to every version simultaneously, which is
+why the property and block projections fall back to unwrapping an unknown
+type's payload rather than switching exhaustively. A property type that ships
+after this release degrades to its raw value, and a block type that does keeps
+its payload under `raw`; neither vanishes.
+
+## Tools
+
+Ten reads, all annotated `readOnlyHint: true`:
+
+| Tool | What it is for |
+| --- | --- |
+| `search` | Find pages and data sources by **title**. Never searches content. |
+| `get_page` | One page's metadata and flattened property values. |
+| `get_page_content` | A page's body as flat blocks reduced to plain text. |
+| `get_page_property` | One property in full, past the 25-entry truncation. |
+| `get_database` | A database container and the data sources inside it. |
+| `get_data_source_schema` | Property ids, types, and select/status options. |
+| `query_data_source` | Filtered, sorted rows with properties already flattened. |
+| `list_users` | Workspace users and bots with their ids. |
+| `get_self` | Which integration and workspace this connector authenticates as. |
+| `list_comments` | Unresolved comments as plain text with discussion ids. |
+
+Five writes, none read-only, so all of them route through
+`call_destructive_tool`:
+
+| Tool | Classification |
+| --- | --- |
+| `create_page` | additive |
+| `append_blocks` | additive |
+| `add_comment` | additive |
+| `update_page_properties` | `destructiveHint: true` — replaces existing values |
+| `trash_page` | `destructiveHint: true` — removes a page from reads |
+
+The additive three leave `destructiveHint` unset: `readOnlyHint: false` already
+routes them through the approval path, and claiming a create destroys something
+only inflates the copy a host shows a human. `update_page_properties`
+deliberately has no `in_trash` argument, so an update can never trash a page by
+accident; trashing is its own named, reversible tool.
+
+## Lean projections, and the raw escape hatch
+
+Every read projects. A page becomes ids, plain text, and flattened values:
+`title` and `rich_text` collapse to strings, `select` and `status` to their
+option name, `multi_select` to an array of names, `relation` to an array of
+page ids, `people` to `{ id, name }`, `unique_id` to `"RL-12"`, and
+`formula`/`rollup` to their computed value. No `plain_text` runs, no
+`annotations` blocks, no property wrappers survive.
+
+Two projections are opinionated enough to call out:
+
+- **`search` returns identity fields only** — no properties at all. A
+  twenty-five result search across a populated database would otherwise drag
+  back several hundred flattened values for results the agent is about to
+  discard. `get_page` fetches properties for the one that matched.
+- **`get_page` reports what Notion hid.** Notion paginates four property types
+  — `title`, `rich_text`, `relation`, and `people` — cutting each off at 25
+  entries and signalling it only with a `has_more` flag on the property itself.
+  The projection surfaces those in `truncated_properties` as `{ name, id }`,
+  which is what stops an agent from confidently reasoning about 25 of 300
+  relations. The `id` is there because the handoff needs it: `get_page_property`
+  addresses a property by id, not by name.
+
+Where the dropped detail can matter — `search`, `get_page`, `get_page_content`,
+`get_page_property`, `get_data_source_schema`, `query_data_source`,
+`list_comments` — `raw: true` returns Notion's untouched response instead. It is
+much larger; it exists so a missing field is never a dead end. When the goal is
+*fewer* fields rather than more, `get_page` and `query_data_source` also take a
+`properties` array to project only the named ones.
+
+One caveat with `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, not three.
+Unmodelled *block* types are covered without it — a block whose type this
+projection does not know, and whose payload is not plain rich text, keeps that
+payload verbatim under `raw` on the block, so nothing collapses to an empty
+string.
+
+## Databases contain data sources
+
+This is the trap the guide is marked `required` for. A Notion database is a
+container; the rows and the schema live in a *data source* inside it, and the
+two ids are not interchangeable. The id in a database's URL is a **database
+id**, and passing it to `query_data_source` fails. The sequence is
+`get_database` → `get_data_source_schema` → `query_data_source`; `search`
+returns data sources directly and skips the first step.
+
+`create_page` needs the same distinction: a row is created under
+`parent_data_source_id`, never a database id. Its title also needs
+`title_property` from the schema, because a database's title column is rarely
+called "title".
+
+## Typed failures
+
+The mapping is deliberately not one-to-one with Notion's error codes. Notion's
+`code` says what its API thinks happened; Connecta's says what the caller
+should do next, and two of Notion's are easy to mistranslate.
+
+| Notion | Connecta | Why |
+| --- | --- | --- |
+| 400 (`validation_error`, `invalid_json`, `invalid_request`, `missing_version`, …) | `invalid_args` | every documented 400 is a malformed request |
+| 401 `unauthorized` | `auth_required` | the token is missing or invalid |
+| 403 `restricted_resource` | `connector_call_failed`, non-retryable | **not** `auth_required` |
+| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded; see below |
+| 409 `conflict_error` | `unavailable`, retryable | Notion says to retry |
+| 429 `rate_limited` | `rate_limited` + `retryAfterMs` | `Retry-After` seconds → ms |
+| 529 `service_overload` | `unavailable` + `retryAfterMs` | back off like a 429 |
+| 5xx | `unavailable`, retryable | upstream failure |
+
+The two that matter:
+
+**403 is not an authentication failure.** The token is fine; the integration
+lacks a capability or was never shared the object. Routing it to
+`auth_required` would send an agent to `authorize_connector`, which cannot
+grant a Notion capability or share a page. It is a non-retryable call failure
+whose message says an operator must change it in Notion.
+
+**404 does not prove absence.** Notion returns `object_not_found` both for an
+object that does not exist and for one that exists but has not been shared with
+the integration, and it will not say which. The message says both, because
+treating it as deletion is exactly how an agent concludes a page is gone when
+it was simply never shared.
+
+## Rate limiting
+
+Notion documents "an average of three requests per second, with some bursts
+beyond the average allowed" per connection, plus a separate per-workspace limit
+scaled to the plan. The connection declares a rolling budget of 180 calls per
+minute — the same average expressed over a window short bursts pass and a
+sustained loop does not — **paired with `maxConcurrency: 3`**.
+
+The concurrency cap 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 cap keeps a burst shaped roughly like the one Notion documents.
+Neither half is a guarantee, because admission meters *tool calls* rather than
+requests — a single admitted `get_page_content` can spend twenty fetches, so
+180 calls per minute is a floor on the real request rate, not a ceiling.
+Declaring the cap is also what makes the queue settings legal — the admission
+controller refuses queue settings without a queue at construction.
+
+Like every connector budget this is per-runtime: N Worker isolates or Node
+processes serving one deployment each keep their own counter. It approximates
+the provider's limit; it does not enforce it.
+
+One tool can turn a single agent call into several downstream requests:
+`get_page_content` with `depth > 0` walks nested blocks, and call admission
+meters tool calls, not the fetches inside them. That walk stops at an internal
+ceiling of twenty requests and reports `truncated: true` rather than spending
+the whole budget invisibly.
+
+## Pagination
+
+List-shaped tools take `page_size` (1–100) and `start_cursor`, and return
+`has_more` with `next_cursor`. The default page size is 25 rather than Notion's
+100, because a first read should be cheap; `defaultPageSize` raises it for a
+deployment that pages a lot.
+
+Cursors are opaque. Notion's own versioning page is explicit that they may
+change in length, format, and structure at any time and must be passed back
+verbatim — never parsed, validated, or constructed.
+
+## What this connection does not do
+
+No file uploads, no database or data-source creation, no schema editing, no
+block updates or deletes, no page moves. Those are all real Notion endpoints
+and all deliberately absent: this is a deliberate tool surface, not a mirror of
+the API. Anything missing is reachable through a custom `api()` connector
+beside this one, which remains a first-class path.