@zackbart/connecta 0.12.2 → 0.14.0

package/dist/types.d.ts

@@ -189,13 +189,17 @@ export interface Connector {
      */
     callAdmission?: ConnectorCallAdmissionPolicy;
     /**
-     * Optional agent-facing usage guide (markdown) for this connector — preferred
-     * tools, address quirks, pagination conventions, rate-limit etiquette, good
-     * query patterns. Listed by the `skills` meta-tool as `connector:<id>` and
-     * returned verbatim by `skills({ name: "connector:<id>" })`. Keep it concise
-     * and imperative; it is read by agents, not operators.
+     * Optional agent-facing usage guide for this connector. A string preserves
+     * the original markdown-only contract. The structured form can add a short
+     * discovery summary and require review when even a complete compact schema
+     * cannot describe correct use (for example a generic API wrapper or a
+     * cross-operation sequencing rule).
+     *
+     * Listed by `skills` as `connector:<id>` and returned verbatim by
+     * `skills({ name: "connector:<id>" })`. The guide remains deployment-owned
+     * configuration; no runtime registration or shared mutable copy exists.
      */
-    usageGuide?: string;
+    usageGuide?: string | ConnectorUsageGuide;
     /** Optional operator-managed credential slot rendered on /credentials. */
     credential?: ConnectorCredentialConfig;
     /** Optional server-side check used by /credentials' Test action. */
@@ -267,6 +271,22 @@ export interface Connector {
      */
     handleRequest?(request: Request, ctx: ConnectorContext): Promise<Response | null>;
 }
+export interface ConnectorUsageGuide {
+    /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
+    content: string;
+    /**
+     * Bounded discovery hint describing the conventions the guide covers. When
+     * omitted, Connecta derives a summary from the guide's first meaningful line.
+     */
+    summary?: string;
+    /**
+     * Require review before every operation on this connector. Reserve this for
+     * cases whose correct arguments or sequence cannot be expressed by the
+     * downstream tool schema; mutations and truncated schemas are required
+     * automatically and do not need this flag.
+     */
+    required?: boolean;
+}
 /** Result of one sandboxed code execution. */
 export interface ExecuteResult {
     result: unknown;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.12.2";
+export declare const CONNECTA_VERSION = "0.14.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.12.2";
+export const CONNECTA_VERSION = "0.14.0";
 //# sourceMappingURL=version.js.map

package/documentation/cloudflare.md

@@ -0,0 +1,268 @@
+# Cloudflare prebuilt connection
+
+Import `cloudflare()` independently from
+`@zackbart/connecta/providers/cloudflare`. It is a deliberate, hand-written
+surface over Cloudflare's v4 REST API — fourteen tools with complete schemas,
+lean projections, typed failures, and a rate-limit budget matching the
+documented one. It adds no provider dependency, imports nothing outside
+Connecta, and is not reachable from Connecta's root entry.
+
+```ts
+import { cloudflare } from "@zackbart/connecta/providers/cloudflare";
+
+const edge = cloudflare("cloudflare_prod", {
+  title: "Production edge",
+  purpose: "DNS and cache administration for the production estate",
+  zoneId: "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
+  accountId: "9f8e7d6c5b4a30291817263544332211",
+  instructions: "Never purge the whole zone during business hours.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Cloudflare account or estate. `purpose` is required because an agent choosing
+between a production and a staging instance needs to know which one answers the
+question. Account `instructions` are appended to the maintained guide and
+cannot change the connector's safety classification.
+
+## No SDK, on purpose
+
+Cloudflare publishes an official `cloudflare` npm SDK, and this connection does
+not use it. The SDK's value is typed request wrappers and pagination helpers.
+Both are things this connection replaces rather than consumes: an agent needs a
+projected result and a `page.hasMore` boolean, not Cloudflare's full response
+object, so the SDK's types would be re-projected away at the boundary. What the
+dependency would cost is real — an optional peer with its own install step and
+version skew, an import that never belongs in the root graph, and a second
+opinion about what a Cloudflare call looks like.
+
+The API itself does not need one. It is Bearer-token JSON over `fetch` with a
+uniform `{ success, errors, messages, result, result_info }` envelope. Writing
+that by hand is about two hundred lines, keeps the provider Workers-clean, and
+means `@zackbart/connecta/providers/cloudflare` installs and runs with nothing
+extra. `test/package-surface.test.ts` pins the claim: the `cloudflare` package
+must not appear in `dependencies`, `peerDependencies`, or `devDependencies`,
+and every import in the provider must be relative.
+
+## Credentials
+
+The connection declares one operator-managed credential: a scoped Cloudflare
+API token, sent as `Authorization: Bearer <token>`. Create it under My Profile →
+API Tokens → Create Token. Do not use a Global API Key — it carries every
+permission on the account and cannot be scoped.
+
+Grant only what the deployment needs:
+
+| Tools | Token permission | Scope |
+| --- | --- | --- |
+| `list_zones`, `get_zone` | Zone Read | Zone |
+| `list_dns_records`, `get_dns_record` | DNS Read | Zone |
+| `create_dns_record`, `update_dns_record`, `delete_dns_record` | DNS Write | Zone |
+| `purge_cache` | Cache Purge | Zone |
+| `list_worker_scripts` | Workers Scripts Read | Account |
+| `list_kv_namespaces` | Workers KV Storage Read | Account |
+| `list_r2_buckets` | Workers R2 Storage Read | Account |
+| `list_pages_projects` | Cloudflare Pages Read | Account |
+
+Those are the names as they appear in the token editor. "Cache Purge" is a
+single permission with no Read/Write split, and Cloudflare's own reference
+renders a few labels differently between its Dashboard and API tabs — if a name
+above does not match what you see, look for the same noun with the other verb.
+
+`verify_api_token` needs no permission beyond the token existing, which is what
+makes it the right first call when something fails. The `/credentials` Test
+action runs the same verification against the candidate token before it is
+stored.
+
+Cloudflare rate-limits *authentication failures* aggressively and separately
+from the global limit: a few requests with a bad token return HTTP 429 with
+code `10502`, "Too many authentication failures". That surfaces here as
+`rate_limited`, not `auth_required`, which is correct — the token may well be
+fine by the time the window clears — but it means a broken token should be
+diagnosed once with `verify_api_token` rather than by retrying real calls.
+
+## Scoping
+
+`zoneId` and `accountId` are deployment defaults, not restrictions. When a
+default is set, the corresponding argument drops out of the tool's `required`
+list and calls that omit it use the default; a call may still pass a different
+id. When no default is set, the argument is required and the schema's own
+description names the discovery tool that produces it — `list_zones` for a
+zone, `list_accounts` for an account.
+
+That is the discovery flow worth knowing: Cloudflare addresses almost
+everything by an opaque 32-character id, and an agent that only knows a domain
+name must call `list_zones` with `name: "example.com"` first. Configuring
+`zoneId` removes that hop entirely for a single-zone deployment.
+
+`list_zones` is the one tool a configured `accountId` deliberately does *not*
+reach. It is the discovery step, and a default that quietly filtered it would
+be a restriction in all but name — one with no argument that escapes it, since
+an empty `accountId` would fall back to the default again. A deployment that
+wants zones from one account passes `accountId` explicitly, and the property
+says so.
+
+## Tools
+
+Ten reads, all annotated `readOnlyHint: true` and therefore admissible from
+`call_tool` and `execute_code`:
+
+`verify_api_token`, `list_accounts`, `list_zones`, `get_zone`,
+`list_dns_records`, `get_dns_record`, `list_worker_scripts`,
+`list_kv_namespaces`, `list_r2_buckets`, `list_pages_projects`.
+
+Four writes, all routed through `call_destructive_tool`:
+
+- `create_dns_record` is additive and leaves `destructiveHint` unset —
+  `readOnlyHint: false` already routes it for approval, and asserting
+  destruction only inflates the copy a human sees.
+- `update_dns_record`, `delete_dns_record`, and `purge_cache` change or discard
+  live state and are annotated `destructiveHint: true`.
+
+Every tool carries a complete hand-written input schema: closed
+(`additionalProperties: false`), with an accurate `required` list, an `enum` on
+every constrained field, per-endpoint `perPage` bounds, and a description on
+every property — the last of which `test/cloudflare-provider.test.ts` asserts
+rather than leaves as a claim. This is the point of the connection. A generated
+wrapper around the same API exposed `arguments?: {}[]` in its compact schema and
+pushed the real parameter list into operation documentation, so an agent had to
+read a doc page before it could make a call. Here the compact schema is enough.
+
+### Where the `perPage` bounds come from
+
+`strictValidation` is on, so an out-of-range `perPage` is refused locally
+before it reaches Cloudflare. That is only a favor when the bound is really
+Cloudflare's, so the schemas record which ones are and the descriptions say so
+out loud:
+
+| Tool | `perPage` | Default | Whose bound |
+| --- | --- | --- | --- |
+| `list_accounts`, `list_zones` | 5–50 | 20 | Cloudflare's, as documented |
+| `list_kv_namespaces` | 1–1000 | 20 | Cloudflare's, as documented |
+| `list_dns_records` | 1–1000 | 100 | Cloudflare's minimum; the ceiling is ours |
+| `list_pages_projects` | 1–100 | — | Ours entirely |
+
+Two need the note. Cloudflare's schema documents `per_page` on
+`/zones/{id}/dns_records` as 1 to **5,000,000** — a nominal ceiling no listing
+will honor — so this connection caps it at 1,000, the same conservative-reading
+move as the [one-variant purge rule](#cache-purging): a local cap an agent is
+told about beats a page size that fails somewhere inside Cloudflare. And
+`/accounts/{id}/pages/projects` documents no bounds and no default at all, so
+1 to 100 is a choice made here and labeled as one.
+
+### DNS record types
+
+Cloudflare accepts 21 record types, exported as `CLOUDFLARE_DNS_RECORD_TYPES`.
+Eight of them take a single `content` string; the other thirteen (CAA, CERT,
+DNSKEY, DS, HTTPS, LOC, NAPTR, SMIMEA, SRV, SSHFP, SVCB, TLSA, URI) take a
+per-type structured `data` object with its own field set.
+
+`list_dns_records` filters on all 21. `create_dns_record` and
+`update_dns_record` accept only the eight content-based types, exported as
+`CLOUDFLARE_CONTENT_DNS_RECORD_TYPES`. Supporting the rest would mean either a
+free-form `data` passthrough — the untyped `{}` this connection exists to
+avoid — or thirteen more hand-written schemas for record types that are rare in
+day-to-day zone administration. Structured-data records stay fully readable;
+only creating and updating them is out of scope, and the enum says so rather
+than letting the call reach Cloudflare and 400.
+
+### Cache purging
+
+`purge_cache` takes exactly one variant per call: `everything: true`, or one of
+`files`, `tags`, `hosts`, or `prefixes`. Cloudflare caps a purge at 100
+operations per request (500 files on Enterprise), and all four targeted methods
+are available on every plan — tag, host, and prefix purging is no longer
+Enterprise-only.
+
+The one-variant rule is this connection's contract, not a documented API
+restriction. Cloudflare's schema models the body as `anyOf`, which does not
+forbid combining, and the only explicit exclusivity statement in its
+documentation is about the Workers cache binding rather than the REST endpoint.
+Refusing a combined call locally is the conservative reading: an agent gets a
+clear `invalid_args` naming the conflict instead of a purge whose actual scope
+is ambiguous. If a future deployment needs combined tag-and-prefix purging,
+that is a deliberate change to make here, not something to discover in
+production.
+
+## Results
+
+Reads return Cloudflare's `result` unwrapped and projected: identity and
+description fields kept, plan/permission/meta noise dropped, `snake_case`
+renamed to `camelCase`. A zone comes back as `id`, `name`, `status`, `paused`,
+`type`, `accountId`, `accountName`, `plan`, `nameServers`, and timestamps —
+not the forty-field object Cloudflare sends.
+
+Paginated lists add a `page` object derived from `result_info`:
+`{ page, perPage, count, totalCount, totalPages, hasMore }`. `hasMore` is the
+field to branch on.
+
+Two endpoints do not work that way, and the schemas say so rather than leaving
+an agent to discover it. `list_r2_buckets` paginates by cursor: its
+`result_info` carries only a cursor, so it returns `nextCursor` instead of
+`page`, and the next call passes it back as `cursor`. `list_worker_scripts`
+reports no counters at all and omits `page` entirely.
+
+Every read accepts `raw: true`, which returns the unprojected result for the
+case where a dropped field genuinely matters. It is an escape hatch, not a
+default: the raw shapes are large enough to hit a deployment's result cap.
+
+## Typed failures
+
+Cloudflare's error envelope carries an array of `{ code, message }` entries and
+sometimes a nested `error_chain`; the connection flattens the whole chain into
+the failure message so the provider's own code number survives to the agent.
+
+| Cloudflare | Connecta failure | Agent behavior |
+| --- | --- | --- |
+| 429 | `rate_limited`, retryable | Waits `retryAfterMs` — the `retry-after` header when present, otherwise the full five-minute window |
+| 401 or 403 | `auth_required`, not retryable | Stops and reports which permission is missing |
+| 400 with a credential-shaped code (1001, 6003, 6111, 9103, 9106, 9107) | `auth_required`, not retryable | Stops; the header or key is malformed, not the arguments |
+| 400, 409, 422 | `invalid_args`, not retryable | Repairs the arguments |
+| 404 | `connector_call_failed`, not retryable | Re-runs discovery for the id |
+| 5xx or a transport error | `unavailable`, retryable | Retries |
+
+The six credential-shaped codes deserve a caveat: Cloudflare publishes no
+official table mapping error codes to causes, so that set is assembled from
+community reports and probing, not from documentation. The same goes for the
+claim below that `10000` is overloaded — that is an observation about responses
+seen in practice. Treat both as well-supported readings that Cloudflare could
+invalidate without notice, and prefer `verify_api_token` over the code list
+when a diagnosis actually matters.
+
+Two ordering decisions are deliberate. The 429 branch is checked before the
+authentication codes, because Cloudflare reuses the generic `10000` code on
+throttled responses and reading a rate limit as an auth failure would tell an
+agent to stop when it should wait. And `10000` is *not* itself treated as an
+auth code: Cloudflare returns it for "Authentication error" but also for
+ordinary validation failures like "Invalid pagination cursor" and
+"domain_name is required", so routing on it would tell an agent its token was
+broken when its arguments were. Genuine `10000` auth failures arrive with 401
+or 403 and are caught by status.
+
+Because the connection declares an operator-managed credential rather than an
+OAuth flow, an `auth_required` failure resolves to the `operator_config`
+recovery mode — the fix is a human updating the token, not an authorization
+URL the agent can open. A missing token fails that way before any request is
+made.
+
+Some failures never reach Cloudflare at all. A blank scope id, a `purge_cache`
+call with no variant or two, and an `update_dns_record` with nothing to change
+are all refused locally as `invalid_args` with a validation issue attached,
+because a round trip that can only 400 is a wasted call and a worse
+explanation.
+
+## Rate limits
+
+Cloudflare documents a global limit of
+[1,200 requests per five minutes per user](https://developers.cloudflare.com/fundamentals/api/reference/limits/),
+counted cumulatively across the dashboard, API keys, and API tokens. The
+connection declares a matching rolling-window admission budget plus a
+`maxConcurrency` of 6, overridable with the `maxConcurrency` option.
+
+The budget is 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 1,200 — and the
+dashboard traffic of a human sharing the account is counted by Cloudflare but
+not by Connecta. `maxConcurrency` is the bound that actually protects a shared
+token, because a single `execute_code` program can fan out far faster than the
+window notices.

package/documentation/code-mode.md

@@ -209,7 +209,7 @@ documented functions as the whole surface.
 ```js
 const page = await connecta.search({
   query: "pipeline run job logs",   // 2–4 distinctive action/object terms
-  connector: "ci",                  // optional single-connector filter
+  connector: "ci",                  // load one obvious connector, not every catalog
   safety: "readOnly",               // or "approvalRequired" / "all"
   limit: 8,                         // 1–100, default 8
   offset: 0,
@@ -221,12 +221,12 @@ const page = await connecta.search({
 
 **S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Each entry in `tools` carries `address`, `name`, and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes; capped shapes remain structurally valid with `unknown` types plus `/* truncated */`, and carry `inputSchemaTruncated` or `outputSchemaTruncated`. Use `connecta.describe` (or JSON search) for omitted exact constraints.
 
-**S1a.** `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. This filters rows only: it grants no authority and changes no admission decision.
+**S1a.** `connector` loads only the named catalog; omit it only when the integration is ambiguous, because an unscoped search fans out across every configured connector. `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. These filters grant no authority and change no admission decision.
 
-**S2.** With schemas requested, a match whose input (or output) schema resolves
-to an object shape also carries `inputKeys`, `requiredInputKeys`, and
-`outputKeys`: the same names the rendered schema shows, ready to check before
-building arguments. A schema that is not an object shape — a union, an array, an
+**S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`, and `outputKeys`:
+the same names the rendered schema shows, ready to check before
+building arguments. Match inputs, truncation, safety, and outputs, not lexical
+rank; search distinct operations separately and use `outputKeys`, not guessed roots. A non-object schema — a union, an array, an
 unresolvable `$ref` — carries no lists rather than empty ones, because absent
 means "read the schema" where `[]` would claim the tool takes no fields. The
 lists come from the same walk that renders the compact schema, so a top-level

package/documentation/connectors.md

@@ -1,15 +1,122 @@
 # Connectors
 
 Connectors are the boundary between Connecta's fixed meta-tool surface and
-downstream capabilities. `api()` defines a deliberate HTTP API surface;
-`remoteMcp()` aggregates another MCP endpoint. Both publish the same tool
-definitions and pass through the same catalog, read-only admission, invocation,
-result-size, and activity paths.
+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.
 
 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. Callers should not
+need to care which transport gives the better agent-facing surface, and the
+choice does not grant the connection different runtime privileges. Two
+instances of the same provider are isolated in exactly the same way as two
+hand-written connectors with different ids.
+
+A prebuilt connection's vetted annotations are fill-in only. They classify what
+the downstream leaves unannotated and do not argue with what it states — not an
+explicit `destructiveHint: true` or `readOnlyHint: false` on a name the
+connection files as a read, nor an explicit `readOnlyHint: true` on a name no
+release has classified at all. Silence on an unclassified name still means not
+read-only, so catalog drift fails closed. The fail-closed read-only invariant
+is unchanged by the authoring path.
+
+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.
+
+Maintained provider guides:
+
+- [Cloudflare](./cloudflare.md)
+- [Linear](./linear.md)
+- [Mixpanel](./mixpanel.md)
+- [Notion](./notion.md)
+- [Stripe](./stripe.md)
+
 ## MCP version skew
 
 Connecta deliberately sits between protocol generations
@@ -53,6 +160,17 @@ Tool calls must use the shared invocation path. That keeps direct calls, batch
 children, and code-mode host calls aligned on safety, retries, admission,
 timeouts, validation, result guards, and typed failures.
 
+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 only a bounded routing hint. 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