@zackbart/connecta 0.24.3 → 0.24.4

package/documentation/connectors.md

@@ -1,431 +0,0 @@
-# Connectors
-
-Every connector may set `authScope: "shared" | "personal"`. Shared is the
-default and keeps one deployment-wide downstream grant. Personal auth requires
-a stable human principal and partitions connector state, credentials, OAuth,
-catalogs, and observed shapes by that principal. Connector visibility is a
-separate deployment rule under `identity.connectorAccess`; hiding a connector
-does not change who owns its auth. See [shared and personal auth](./storage-and-credentials.md#shared-and-personal-auth).
-
-`authScope` partitions connecta-owned context, not arbitrary variables captured
-by connector code. A custom personal connector must read auth from
-`ctx.credential` or `ctx.storage`; a secret closed over by its handler remains
-shared JavaScript state. `remoteMcp()` rejects the equivalent mistake when
-literal headers are combined with personal scope.
-
-Connectors are the boundary between Connecta's fixed meta-tool surface and
-downstream capabilities. Prefer a prebuilt connection when Connecta maintains
-one for the provider. Use `api()` to define a deliberate HTTP API surface and
-`remoteMcp()` to aggregate any other MCP endpoint. All three authoring paths
-produce ordinary `Connector` instances and pass through the same catalog,
-read-only admission, credentials, storage, invocation, result-size, and
-activity paths.
-
-Custom HTTP routes belong to the deployment fetch handler. Connectors expose
-tools and the documented OAuth hooks; a removed `handleRequest` declaration
-refuses construction.
-
-Connector instances are deployment configuration. They are not registered or
-reconfigured at runtime. Request-local clients, transports, abort signals, and
-catalogs must be released with the request that created them.
-
-## Prebuilt connections
-
-A prebuilt connection is an independently imported provider constructor, not a
-registry or a second connector interface. It packages behavior Connecta can
-maintain universally: provider endpoints and authentication defaults, tool
-definitions or downstream catalog behavior, schemas and annotations, lean
-result shapes, typed errors, pagination and retry conventions, and a short
-usage guide where schemas cannot carry the advice.
-
-The deployment still supplies the account-specific identity and policy:
-
-- a unique connector `id`, which owns its address, storage, credential,
-  catalog, admission, and activity namespaces;
-- a human-readable `title` and a concrete `purpose` or audience;
-- supported authentication overrides; and
-- account-specific instructions appended to, rather than replacing, the safe
-  provider guidance.
-
-Imports and registration stay explicit and a la carte:
-
-```ts
-import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
-
-const analytics = mixpanel("product_analytics", {
-  title: "Product analytics",
-  purpose: "Production product decisions for the growth team",
-});
-```
-
-The constructor may use `remoteMcp()` or `api()` internally. When a provider's
-official MCP and HTTP API expose materially different capabilities or schema
-ownership, the constructor may offer an explicit deployment-time surface
-choice. It must document the difference, keep a backward-compatible default,
-and never let an agent switch surfaces during a run. The choice grants no
-different runtime privileges. Two instances of the same provider are isolated
-in exactly the same way as two hand-written connectors with different ids.
-
-That choice exists only when the two interfaces are genuinely different:
-
-| Provider | Maintained interfaces | Why |
-| --- | --- | --- |
-| Cloudflare | API and MCP | The API interface has 48 projected named tools plus three safety-split hatches. The official MCP compresses more than 2,500 endpoints into `search` and approval-gated `execute`. |
-| Notion | API and MCP | The API interface has stable lean projections. The official MCP adds Notion-owned live schemas, workspace search, files, views, agents, and sessions. |
-| Vercel | API and MCP | The API interface has projected deployment operations. The official MCP owns a broader, independently changing catalog. |
-| Linear | MCP | Vendoring its GraphQL API would create a second schema system rather than a distinct maintained interface. |
-| Mixpanel | MCP | Its hosted service already joins several Mixpanel APIs; flattening those APIs would recreate the catalog problem. |
-| RevenueCat | MCP | Its official server is generated from API v2, so a second wrapper would duplicate the same contract. |
-| Stripe | MCP | Its official server already exposes both named workflows and supported API methods. A second raw API interface would duplicate it. |
-
-This is not a requirement that every provider have two labels. A second choice
-must change capability, result shape, or schema ownership enough to justify a
-second contract. Otherwise it only gives agents two names for the same thing.
-
-A prebuilt connection's vetted annotations fill in downstream silence and
-otherwise preserve explicit annotations. This includes an explicit
-`destructiveHint: true` or `readOnlyHint: false` on a vetted read, and an
-explicit `readOnlyHint: true` on a name no release has classified. One narrow
-exception stays fail-closed: a release-reviewed destructive classification
-overrides a contradictory `readOnlyHint: true`, because Connecta has
-independently established that the tool mutates existing state. Silence on an
-unclassified name still means not read-only. The authoring path never weakens
-the fail-closed read-only invariant.
-
-Prebuilt means preferred when available, not mandatory. A deployment may mix
-prebuilt connections, custom `remoteMcp()` connections, and custom `api()`
-connections. Connecta makes no completeness promise: providers without a
-maintained prebuilt connection continue to use the public primitives without
-loss of support.
-
-```ts
-import { createConnecta, remoteMcp, api } from "@zackbart/connecta";
-import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
-import { quickJsExecutor } from "@zackbart/connecta/quickjs";
-
-export const connecta = createConnecta({
-  executor: quickJsExecutor(),
-  connectors: [
-    // Maintained prebuilt connection.
-    mixpanel("product_analytics", {
-      purpose: "Production product decisions for the growth team",
-    }),
-    // Custom downstream MCP server, no prebuilt connection needed.
-    remoteMcp("deploy_tools", {
-      url: "https://mcp.internal.example/deploys",
-      description: "In-house deployment and rollback tooling",
-    }),
-    // Deliberate in-house HTTP surface, hand-written tool by hand-written tool.
-    api("billing", {
-      description: "Internal billing reads",
-      credential: { label: "Billing API token" },
-      tools: [
-        {
-          name: "get_invoice",
-          description: "Fetch one invoice by id.",
-          annotations: { readOnlyHint: true },
-          inputSchema: {
-            type: "object",
-            properties: { id: { type: "string" } },
-            required: ["id"],
-          },
-          handler: async ({ id }, ctx) => {
-            const response = await fetch(
-              `https://billing.internal.example/invoices/${id}`,
-              { headers: { Authorization: `Bearer ${await ctx.credential?.get()}` } },
-            );
-            return response.json();
-          },
-        },
-      ],
-    }),
-  ],
-});
-```
-
-All three are ordinary `Connector` instances by the time the registry sees
-them. Nothing in the list is privileged by how it was authored.
-
-What a maintained connection owes an agent is written down rather than
-inherited from whoever wrote it last:
-[provider conventions](./provider-conventions.md), one set for hand-written
-HTTP surfaces and one for hosted-MCP proxies.
-
-Maintained provider guides:
-
-- [Cloudflare](./cloudflare.md)
-- [Linear](./linear.md)
-- [Mixpanel](./mixpanel.md)
-- [Notion](./notion.md)
-- [RevenueCat](./revenuecat.md)
-- [Stripe](./stripe.md)
-- [Vercel](./vercel.md)
-
-## The `api()` construction contract
-
-`api()` is the path every custom integration takes, and whatever it accepts is
-what an agent eventually reads. Three things are refused at construction rather
-than discovered in production
-([#340](https://github.com/zackbart/connecta/issues/340)):
-
-- **A tool with no description.** Discovery has nothing else to route on, and a
-  guess costs a call.
-- **A tool with no explicit boolean `annotations.readOnlyHint`.** `true`
-  declares a read and admits the tool to `call_tool` and `execute_code`;
-  `false` declares work that crosses `call_destructive_tool`, where the host
-  can ask a human. Connecta never infers the classification from a tool name,
-  description, schema, HTTP method, or the other annotations — an unclassified
-  tool is a bug in the deployment, not a puzzle to solve.
-- **An `inputSchema` the validator cannot compile.** Declaring one is optional;
-  declaring one that cannot be enforced is not. A schema that only reveals
-  itself on first use — an unresolvable `$ref`, say — fails that call as
-  non-retryable `invalid_args` rather than forwarding raw arguments to the
-  handler. `validateArgs: false` still opts out of enforcement for deployments
-  that want loose coercion; it does not opt out of the schema being real.
-
-None of this reaches a proxied catalog: hosted-MCP tools arrive as their
-downstream wrote them, and an unannotated or contradictory one stays
-fail-closed onto `call_destructive_tool`. The contract binds the surfaces we
-write, not the catalogs we relay.
-
-An `unavailable` failure can carry `details.host` and `details.code` in its
-classified error. `host` is an HTTP(S) origin, including a non-default port,
-with no userinfo, path, query, or fragment and at most 253 UTF-8 bytes. `code`
-is an allowlisted network errno, an undici transport code, or `timeout`, at
-most 32 bytes. Invalid or oversized fields are omitted, never clipped.
-`remoteMcp()` and the guarded transport know the failed fetch destination;
-`api()` can classify a handler's structured runtime code but cannot recover
-its destination from `ctx.baseUrl`, which names Connecta itself. A handler can
-supply a known URL in a typed `ConnectorCallError` and the constructor reduces
-it to an origin. AbortError and TimeoutError become diagnostic `timeout`;
-workerd outbound denial supplies no errno, so a fetch boundary reports the
-known origin alone. No provider prose supplies a code or retryability.
-These diagnostics belong in tool failures and the bounded warning log, never
-in payload-free activity records.
-
-## The guarded fetch transport
-
-Every hand-written HTTP surface re-derives the same safety machinery, and two
-of them had already derived it slightly differently. `src/connectors/guarded-fetch.ts`
-is that machinery extracted once ([#341](https://github.com/zackbart/connecta/issues/341)):
-one `guardedFetch({ provider, baseUrl, headers, maxResponseBytes, authenticate })`
-factory returning the transport a connector sends every request through.
-
-```ts
-const send = guardedFetch({
-  provider: "Billing",
-  baseUrl: "https://billing.internal.example/v1",
-  maxResponseBytes: 4 * 1024 * 1024,
-  headers: { Accept: "application/json" },
-  authenticate: async (ctx) => {
-    const token = await ctx.credential?.get();
-    if (!token) throw new ConnectorCallError("auth_required", "...");
-    return { Authorization: `Bearer ${token}` };
-  },
-});
-
-const invoice = await send(
-  { method: "GET", path: `/invoices/${id}` },
-  ctx,
-  (response) => {
-    if (!response.ok) throw billingFailure(response.status);
-    return response.json();
-  },
-);
-```
-
-What it owns is mechanical and provider-independent:
-
-- **Confinement.** A request path is provider-relative, carries no query or
-  fragment, and is re-checked against the base origin and path prefix *after*
-  `new URL` normalization — because normalization is how a path escapes a
-  prefix, not something to trust before it.
-- **Construction.** Query parameters are encoded rather than concatenated, a
-  JSON body is serialized with the `Content-Type` to match, and a pre-framed
-  body gets none, so `fetch` still picks the multipart boundary.
-- **Credential forwarding.** `authenticate` is called once per request and its
-  headers are applied last; a request header wearing one of their names is
-  refused rather than allowed to shadow it. A 3xx is refused outright — a
-  redirect is an instruction to re-send the credential to whatever origin the
-  `Location` names, and a confinement a redirect can undo was never one.
-- **Bounded reads.** `maxResponseBytes` is required, not defaulted: what counts
-  as an absurd response is a fact about the API, not about HTTP. A declared
-  `Content-Length` past the ceiling fails before a byte is read, and a
-  streaming body is abandoned at the ceiling rather than buffered past it.
-  Without a body stream, text is measured in UTF-8 bytes before it is accepted;
-  JSON is parsed from that same bounded text. Such runtimes still buffer their
-  read internally, but cannot return an oversized body as a successful result.
-- **Normalization.** An unreachable provider becomes a retryable `unavailable`
-  instead of whatever `TypeError` the runtime threw, and `ctx.signal` rides
-  every request. `Retry-After` hints accept delta-seconds and HTTP dates;
-  a date in the past means no further wait.
-
-What it deliberately does not own is meaning. It never reads a status code and
-never invents an authentication scheme: the provider's `authenticate` callback
-supplies the headers, and the provider's mapper turns one `GuardedResponse`
-into a result or a typed failure. That split is not fastidiousness. Notion's
-403 means a capability the integration was never granted — re-authorizing
-cannot fix it — while Cloudflare's means a token scope, and the two want
-opposite next moves. A helper that guessed would be wrong for one of them.
-
-Cloudflare, Notion, and Vercel run on it. The first two existing suites carried
-over unchanged when the helper was extracted, which proves that migration kept
-the behavior those suites cover — not that nothing changed. Three things did,
-and the changelog names them: a 3xx is refused where both providers used to
-follow it, both now fail past their byte ceiling, and `cloudflare()`'s
-`baseUrl` is validated at construction. Each suite gained one test for the
-ceiling, because the one
-guard the helper was written to add is the one a provider's own mapper can
-most easily disarm: a bare `catch` around `response.json()` swallows the
-transport's refusal along with a parse error, and turns a response nobody was
-allowed to read into an empty success. A mapper re-throws
-`ConnectorCallError` and swallows only what it recognizes.
-
-It is **not exported this release**: the two migrations proved the shape
-preserves behavior for connectors that already had this machinery, not that it
-is the right shape for an author starting from nothing, and an unexported
-symbol costs nothing to reshape while a published one is a promise.
-The provider audit ([#342](https://github.com/zackbart/connecta/issues/342))
-supplies the third caller that would settle it.
-
-## MCP version skew
-
-Connecta deliberately sits between protocol generations
-([full revision inventory](https://github.com/zackbart/connecta/blob/main/records/mcp-2026-07-28.md)):
-
-- **Inbound:** `/mcp` serves both the 2026-07-28 revision and legacy 2025
-  clients. Modern clients negotiate with `server/discover` and do not send
-  `initialize`; legacy clients retain their initialize flow. The endpoint
-  remains stateless in both cases.
-- **Outbound:** `remoteMcp()` probes modern downstreams and falls back to the
-  byte-compatible legacy flow. Legacy downstreams are normal supported
-  deployments, not a temporary exception. Automatic negotiation remains the
-  default. A known-legacy server that crashes or returns a server error for the
-  pre-initialize probe can set `versionNegotiation: "legacy"` on that one
-  connector; Connecta then starts directly with `initialize` and never sends
-  `server/discover`. Keep the default unless the downstream requires this
-  compatibility concession, so modern protocol support is still discovered.
-- **Legacy sessions:** Connecta's own endpoint creates no protocol session, but
-  a stateful legacy downstream can still issue `Mcp-Session-Id`. Closing a
-  request scope, rotating credentials, retiring an OAuth generation, and
-  abandoning a connect all send the legacy DELETE before closing the transport.
-  The DELETE gets at most one second and failures are logged. Rotation and
-  abandoned connects start cleanup without waiting; the connector context has
-  no deferred-work hook. Scope teardown gives its bounded tail back to core,
-  which can attach the runtime's deferred channel. SDK v2 `Client.close()` does
-  not send DELETE on Connecta's behalf.
-- **Modern cache hints:** `tools/list` is deployment-fixed and returns a
-  one-hour private cache hint. Downstream hints do not alter Connecta's existing
-  five-minute fingerprinted catalog cache; that remains gated in
-  [#206](https://github.com/zackbart/connecta/issues/206).
-- **Multi-round-trip results:** a downstream `input_required` result becomes a
-  non-retryable `input_required_unsupported` failure. `call_tool` and the
-  `execute_code` host bridge preserve the structured code. Relaying the
-  opaque `requestState` is architecturally possible but gated until real hosts
-  and downstreams adopt it.
-
-The compatibility policy has no automatic sunset. Dropping a revision,
-session cleanup, or cursor tolerance requires an explicit design decision and
-replacement evidence.
-
-## Catalog contract
-
-A downstream catalog is complete or it is a failure. Follow every page until
-the cursor ends, preserve schemas and annotations, and never cache or serve a
-partial walk. The fixed TTL is paired with a schema fingerprint so a changed
-catalog invalidates persisted results even within the time window.
-
-Agent reads use a complete entry inside `staleCatalogSeconds` immediately and
-defer the refresh that read already demanded. Every live refresh is
-single-flight per connector in one runtime. A blocking operator or direct read
-joins an agent-owned refresh and awaits it; an agent stale read joins an
-operator-owned refresh without awaiting it. The first refresh owns the context
-and deadline. A deferred first refresh owns a fresh scope and signal, then
-closes that scope. Operator status and direct registry reads still await
-freshness. The operator page reports whether the last agent read in this runtime
-was fresh or stale; this payload-free timestamp is not persisted. No timer or
-idle warmup originates downstream traffic.
-
-Tool calls must use the shared invocation path. That keeps direct calls and code-mode host calls aligned on safety, retry hints, admission,
-timeouts, validation, result guards, and typed failures.
-
-That path also learns an observed output schema after a successful explicitly
-read-only call when the catalog declared none. The observation retains field
-names and broad JSON types rather than a result. Object fields stay optional,
-additional fields stay allowed, discovery labels the source `observed`, and any
-later provider declaration wins. Property names can be user-authored data, so
-the bounded cache stays in this process or Worker isolate and expires entries
-after 24 hours. An exact tool-definition comparison rejects stale shapes. This
-does not weaken the catalog completeness rule or the refusal of result sampling:
-no catalog read executes a tool.
-
-Connector usage guides are configuration too. `usageGuide` accepts the
-historical markdown string or `{ content, summary?, required? }`; the latter
-lets discovery explain what the guide covers without loading it. The summary
-is a 120-character routing hint; a longer configured value refuses construction
-instead of being silently shortened. Mark a guide `required` only when no complete
-tool schema can describe correct use, such as a generic operation wrapper or a
-mandatory cross-tool sequence. Mutations and truncated compact schemas already
-produce automatic review requirements. Two deployments may reuse the same
-constant and override its summary or requirement in their own config, but
-Connecta stores no runtime template and never lets one deployment's guide apply
-to another.
-
-For remote MCP tools, that path checks the catalog's advertised `inputSchema`
-before provider dispatch. Supported mismatches become bounded, payload-free
-`invalid_args` findings; a schema the local validator cannot evaluate passes
-through unchanged. Connecta does not parse provider error prose to invent a
-validation classification. A downstream JSON-RPC `-32602` is an explicit
-`invalid_args` refusal, with a bounded server message and no retry. HTTP 4xx
-refusals preserve a bounded JSON `message`, including `error.message`, and are
-non-retryable; 429 becomes `rate_limited` and 408 becomes `timeout`. The SDK
-still owns OAuth challenges and step-up authorization.
-
-## Authentication
-
-OAuth-backed MCP connectors persist their registration and tokens through the
-connector-scoped storage context. Those values are bound to the authorization
-server issuer discovered and validated by the SDK; see
-[storage and credentials](./storage-and-credentials.md#downstream-oauth).
-The callback route validates `state` before passing the complete callback query
-to the SDK so RFC 9207 `iss` validation is not lost.
-
-Within one runtime, overlapping refreshes share one completion gate per
-credential partition and generation. A valid token response is a consumed
-refresh token, so the coordinator keeps that response's tokens on the flight.
-If the owner then fails before the SDK saves them — cancelled, redirected to
-authorization, or invalidated — the host persists the rotation itself, holds
-contenders behind the mutation marker until that write lands, and hands them
-the saved rotation; a retired token is never redeemed twice. A write already
-running in `saveTokens` clears the marker on its own success or failure, and a
-late duplicate save from a detached owner is harmless. Nothing can leave a
-permanent 503 gate ([#526](https://github.com/zackbart/connecta/issues/526)).
-Refresh token response validation
-reads at most 65,536 bytes, and credential reads stop after 64 revision races
-with `temporarily_unavailable` so churn cannot spin indefinitely. Request
-cancellation is checked before each attempt.
-
-A remote MCP connector that authenticates with a static key has two ways to
-receive one. `{ type: "headers", headers }` bakes the literal value into the
-deployment file, which suits a secret the runtime already holds.
-`{ type: "credential" }` declares the slot instead and lets an operator paste
-the key at the connection UI at `/`, where it is encrypted at rest and rotatable without
-a redeploy:
-
-```ts
-remoteMcp("revenuecat_bepresent", {
-  url: "https://mcp.revenuecat.ai/mcp",
-  auth: {
-    type: "credential",
-    credential: { label: "API v2 secret key" },
-  },
-});
-```
-
-Header name and framing are configurable — `header` defaults to
-`Authorization`, `scheme` to `Bearer`, `scheme: null` sends the value bare, and
-a `Basic` framing base64-encodes a `user:secret` pair. Every maintained hosted
-connection takes the shape through its existing `auth` option and fills in its
-own label and framing. The full behavior, including rotation and the empty-slot
-state, is in
-[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).

package/documentation/linear.md

@@ -1,193 +0,0 @@
-# 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",
-  access: "read-write",
-  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. It is
-**required**, with no default:
-
-| `access` | Endpoint | OAuth scopes |
-| --- | --- | --- |
-| `"read-write"` | `https://mcp.linear.app/mcp` | `read`, `write` |
-| `"read-only"` | `https://mcp.linear.app/mcp/readonly` | `read` |
-
-There is no safe default to pick. Defaulting to `"read-write"` hands a
-deployment write access it never asked for; 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 which one this
-is, and a deployment that forgot fails at construction with a message naming
-both options.
-
-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's
-MCP server also "supports passing OAuth token and API keys directly in the
-`Authorization: Bearer <yourtoken>` header instead of using the interactive
-authentication flow" ([Linear MCP docs](https://linear.app/docs/mcp)), which
-suits a headless deployment. Note the framing: the bare-`Authorization`
-convention is Linear's *GraphQL* API, and this endpoint is not that.
-
-```ts
-linear("automation_tracker", {
-  purpose: "Headless release reporting",
-  access: "read-only",
-  auth: {
-    type: "headers",
-    headers: { Authorization: `Bearer ${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.
-
-The same key can arrive from the connection UI at `/` instead, which is what a deployment
-with no secret store — or an operator who rotates keys without a redeploy —
-wants:
-
-```ts
-linear("automation_tracker", {
-  purpose: "Headless release reporting",
-  access: "read-only",
-  auth: { type: "credential" },
-});
-```
-
-The slot renders as "Personal API key" and Connecta sends the stored value as
-`Authorization: Bearer <key>`, the framing Linear's MCP page documents; pass
-`credential` or `scheme` to override either. Until the operator saves a value
-the connector is present and reports `auth_required`. See
-[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
-
-## Safety classification
-
-The wrapper classifies Linear's documented `list_*`, `get_*`, and
-`search_documentation` tools as reads, and its `save_*`, `create_*`, `delete_*`,
-`resolve_*`, `submit_*`, `merge_*`, `share_issue`, and `unshare_issue` tools as
-writes. Sharing changes an existing issue's access, so both halves are
-destructive. An unfamiliar tool the downstream leaves unannotated fails closed
-onto `call_destructive_tool` until a Connecta release reviews it.
-
-That classification fills in downstream silence and otherwise preserves
-explicit annotations. 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. One narrow fail-closed exception applies to 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, code review, templates, and explicit issue sharing
-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",
-  access: "read-write",
-  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.
-
-## Public contract check
-
-`npm run drift:check -- --docs --provider linear` checks Linear's official MCP
-setup page for the read-write endpoint and OAuth support without using a
-credential. Linear does not publish an exact tool inventory there, so the
-command says `setup metadata only` and makes no claim about names or schemas.
-At runtime the live `tools/list` response remains the schema authority and is
-passed through without a vendored replacement.
-
-## Conventions
-
-This connection is audited against
-[the provider conventions](./provider-conventions.md). Its verdict per
-convention, including every recorded exception, is the Linear section of
-[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).