@zackbart/connecta 0.15.1 → 0.16.1

package/CHANGELOG.md

@@ -2,6 +2,659 @@
 
 All notable changes to this package are documented here.
 
+## 0.16.1 — 2026-08-13
+
+This is the cleanup that follows 0.16.0 out the door: the packaging housekeeping
+the pre-release smoke gauntlet turned up, one provider tool Cloudflare
+deprecated out from under us, a discovery answer that told a plain lie, and the
+upgrade runbook an existing deployment never had. Two things break, both on
+Cloudflare and both named here rather than left to the section below:
+`list_zone_settings` is gone from the `cloudflare()` named surface, and
+Cloudflare's 404 arrives as `not_found` instead of `connector_call_failed`.
+Nothing else does — no wire shape changes, no construction contract moves, no
+other code reclassified, and the per-setting operations `list_zone_settings`
+sat beside are the supported ones and are untouched. A deployment that writes
+no `api()` connectors, branches on no error code, and never asked an agent for
+a whole zone's settings in one call upgrades without reading further.
+
+Three things are additions rather than repairs, and they are the reason this
+release is worth reading rather than just installing: a new
+`ConnectorCallErrorCode` member, `not_found`, with a rule for when a connector
+may mint it; a `"./package.json"` entry in the `exports` map, so the installed
+manifest resolves; and `@cloudflare/codemode` declared as an optional peer at
+`^0.4.4 || ^0.5.0`. Strict semver would read those three as a minor, and would
+read the two Cloudflare changes above as more than that. This ships as a patch
+deliberately: every addition is opt-in at the point a deployment chooses to
+read it, and the tool removal and the 404 reclassification ride along in the
+same patch on purpose — both are scoped to one provider, both have a stated
+replacement, and both carry a version boundary in
+[`documentation/upgrading.md`](./documentation/upgrading.md). Holding them for
+a minor would mean shipping a release that keeps calling an endpoint its
+provider deprecated. The one install-time consequence is spelled out next.
+
+One thing to check before upgrading a Worker: `@cloudflare/codemode` is now a
+declared peer, so if your `package.json` holds it at a version outside
+`^0.4.4 || ^0.5.0` — a `0.3.x`, or a `0.4` below `0.4.4` — npm stops the
+upgrade with an `ERESOLVE` conflict rather than installing. Move it into the
+range this release is tested against, or pass `--legacy-peer-deps` if you have
+a reason to run outside it. A version already inside the range, and a range
+loose enough for npm to pick one that is, both resolve exactly as before.
+
+Alongside it, the upgrade path an existing deployment takes gets written down.
+`connecta init` was the golden path for a new deployment and the whole story
+for an old one, which is a gap with a shape: `init` refuses to merge into an
+existing path — the guard that keeps an initializer from eating a connector
+set — so an agent pointed at a deployment two releases behind had to
+reconstruct the procedure from release prose written for the maintainer. Both
+interesting failures there were silent too. It overwrites the configuration the
+deployment exists for, or it "fixes" a construction throw by weakening a
+fail-closed default and ships something quieter and wrong.
+
+### Added
+
+- **`not_found`, for a downstream that answered and had nothing to give.** A
+  hand-written connector meeting a 404 had exactly one honest code,
+  `connector_call_failed`, which also means "the call blew up" — so a program
+  inside `execute_code` could not tell a clean absence from a broken connector,
+  and a loop over ids had to abort where it should have skipped one. The new
+  code earns its place the way every code has to: it changes what the caller
+  does next. You do not wait, you do not go to `authorize_connector`, you do
+  not repair the arguments — you re-address. It is non-retryable, carries no
+  recovery envelope, derives no activity friction class, and is exported from
+  the root entry as part of `ConnectorCallErrorCode`.
+
+  The qualifier is the interesting half, and it is now written down in
+  [H11](./documentation/provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next):
+  map a status to `not_found` only where the provider tells absence apart from
+  a permission gap. Cloudflare does — a token that may not touch a resource is
+  refused with 401 or 403 — so its 404 is now `not_found` instead of
+  `connector_call_failed`. Notion does not: `object_not_found` means both "it
+  is gone" and "it was never shared with this integration", so it deliberately
+  stays generic with a message that says so. The hosted-MCP proxy path mints
+  the code never, because `P1` forbids re-shaping downstream framing and
+  provider prose is never parsed to invent a classification (#373).
+
+- **An upgrade runbook for existing deployments.**
+  [`documentation/upgrading.md`](./documentation/upgrading.md) is written for
+  the agent sitting inside a generated deployment it did not create: read the
+  exact pin and the template generation it implies, regenerate that generation
+  with `npx @zackbart/connecta@<pin> init` to get a real merge base, three-way
+  reconcile the scaffolding against the current template while `src/index.ts`
+  stays the deployment's own, cross the version boundaries that break
+  construction, and finish where `init` finishes — typecheck, start,
+  `connecta doctor`, then a program that exercises the deployment's *own*
+  connectors, which doctor deliberately knows nothing about. The migration
+  notes are per boundary and derived from this file: the 0.16.0 `api()`
+  construction contract (with the one safe answer for an unannotated tool
+  written down — `readOnlyHint: false`, which is the routing it already had),
+  the `linear()`, `mixpanel()`, and Cloudflare provider changes, redirect
+  refusal and the response ceilings, and the fail-closed shipped defaults; then
+  0.14's annotation-precedence change, 0.13's rewritten guide summaries, the
+  0.11.0 executor requirement, 0.7.0's `verifyState` requirement and
+  core-owned routes for the pre-template deployments that still have to cross
+  them, and every removed option that throws with its migration. It closes with five refusals, because each is somebody's plausible
+  shortcut: no re-init over the top, no weakening a fail-closed default to get
+  green, no pinning back, no vendored internals, no second project shape.
+  Reachable from the README, from `operations.md`, and — absolutely, because
+  that reader has no copy of this repository — from the template's `AGENTS.md`
+  (#380).
+- **A suite that keeps the guide honest.** `test/upgrade-guide.test.ts` pins
+  every claim its reader cannot check: the generated file inventory against
+  `templates/node/`, the seven tool names against the CLI's own list, each
+  named version boundary against a release that shipped, each removed option
+  against the release section that names its issue, the bump target against
+  this package's version, and the three places the guide is linked from. A template that gains a file now fails `npm run check` rather than
+  leaving an agent to guess which of the two is wrong (#380).
+- **`@cloudflare/codemode` is a declared optional peer.** Every Workers
+  deployment installs the executor behind `execute_code` by hand, and until now
+  the only version range anywhere was a devDependency no consumer can read — a
+  fresh install resolved a minor ahead of what this repository tests, silently.
+  The manifest now publishes `^0.4.4 || ^0.5.0` for it, optional like
+  `@clerk/backend` and `quickjs-emscripten`, so a supported version installs in
+  silence and an unsupported one stops the install with something to act on
+  instead of becoming skew a Worker discovers in production. It still installs
+  with nothing: a default `npm install @zackbart/connecta` pulls no executor,
+  and the package smoke proves that, both halves of the range behavior, and
+  that the version this repository develops against stays inside the range it
+  publishes (#376).
+
+### Changed
+
+- **Cloudflare's 404 is `not_found`.** A deployment branching on
+  `connector_call_failed` to detect an unknown zone or account id should read
+  `not_found` instead; retryability, the message, and its pointer to
+  `list_zones` / `list_accounts` are unchanged (#373).
+- `cloudflare()` no longer names a bulk zone-settings read.
+  `GET /zones/{zoneId}/settings` and its `PATCH` sibling are published as
+  `deprecated: true`, Cloudflare offers no bulk replacement, and the tool that
+  wrapped the read projected nothing — it took a zone id and grew the payload
+  by wrapping an unpaginated array in a page object. Read one setting with
+  `get_zone_setting` and write one with `update_zone_setting`, both on the
+  supported `/zones/{zoneId}/settings/{settingId}` operations. An operator who
+  still wants the whole set can name the deprecated path explicitly through
+  `cloudflare_api_get`. The named surface is 47 tools plus the three escape
+  hatches ([#361](https://github.com/zackbart/connecta/issues/361)).
+- The Cloudflare touched-endpoint manifest drops the deprecated row with the
+  tool, so `npm run drift:check -- --specs` is quiet about zone settings
+  because nothing calls the endpoint, not because a maintainer signed off on
+  calling it anyway.
+
+### Fixed
+
+- **A search for a connector's own name stops claiming the deployment has no
+  such capability.** A connector's `id` — the address prefix an agent already
+  holds — and its `title` are displayed, never indexed, so `search_tools({
+  query: "inventory" })` against a connector called `inventory` matched no tool
+  and was answered with "No matching capability is configured in this
+  deployment", which was plainly false. Connector identity stays out of the
+  lexical index, because putting it in would move ranking for every query that
+  already matches tools; instead an unscoped miss whose terms name configured
+  connectors says so, names up to three of them by ID, and sends the caller to
+  a scoped browse. A term that matches nothing in the deployment still gets the
+  original sentence, unchanged. One `queryAnalysis.guidance` string differs; no
+  ranking, result, or field changed (#372).
+- **Every relative link in the shipped Markdown resolves for the reader who
+  installed the package.** Ten of them pointed at `eval/`, `test/`, `scripts/`,
+  and the README hero — repository paths the tarball has never carried and, per
+  #346, should not start carrying. The link gate could not see any of them: it
+  read only `documentation/` targets, so the whole class was invisible and grew
+  with every trim. The policy is now stated once in the operations guide and
+  enforced over *every* relative link in packed Markdown: it either resolves
+  inside the tarball or it is cited as an absolute
+  `https://github.com/zackbart/connecta/blob/main/...` URL, which an outside
+  reader can follow and which `check:docs` resolves back to the checkout, so a
+  citation still fails when the file it names moves. The ten links were
+  rewritten that way, the README hero now loads from
+  `raw.githubusercontent.com` and still renders on npmjs.com, and the
+  repository reader loses no citation (#378).
+- **`@zackbart/connecta/package.json` resolves.** The `exports` map listed
+  every code subpath and nothing else, so a bundler plugin, framework build
+  step, or version probe reaching for the installed manifest — a thing the
+  ecosystem broadly expects to work — got `ERR_PACKAGE_PATH_NOT_EXPORTED`
+  instead of the file. The manifest is now exported. It is a data file, so this
+  widens the published surface by exactly zero code paths: the root entry's
+  Workers purity boundary and the optional-peer subpaths are untouched. The
+  package-surface gate now asserts the whole subpath set, manifest included, so
+  neither this entry nor an unwanted one can arrive unnoticed (#374).
+- **The published-surface rule says what it actually forbids.** `AGENTS.md`
+  claimed platform-specific storage adapters live in `examples/`, "not the
+  package", while the tarball has always carried `examples/worker` — Cloudflare
+  KV and D1 adapters included — because that example is the Workers starting
+  template a consumer copies. The invariant was never in danger: nothing under
+  `examples/` appears in the `exports` map, so those adapters are reference
+  source and not an importable subpath. The wording now draws the line where
+  the gates draw it — a platform-bound adapter must not reach `src/` or the
+  `exports` map — and says why the example ships, in `AGENTS.md`, the
+  operations guide, and the `scripts/check-package.mjs` comment. A new
+  assertion in `test/package-surface.test.ts` holds the instruction file and
+  the exports map to the same story (#377).
+
+## 0.16.0 — 2026-08-12
+
+This is the agent-efficiency refocus. One release, sixteen merges, and a single
+question asked of every tool description, schema, discovery result, and error
+message in the package: what does this cost the model that has to read it?
+Where operator convenience and agent cost disagreed, the agent-facing contract
+won. The work lands on two pillars — excellent curated providers, and a
+footgun-free path for everything else — plus an operator boundary that finally
+describes the surface it guards, exactly two deployment shapes instead of four,
+and an operator UI that is a component app rather than string-built HTML.
+
+What breaks, breaks loudly, and mostly at construction rather than at 2 a.m.
+`api()` now requires a `description` and an explicit
+`annotations.readOnlyHint` on every tool and refuses an `inputSchema` it cannot
+compile; `strictValidation` is gone because fail-closed is the only behavior
+left for it to switch. `linear()` requires an explicit `access` mode.
+`mixpanel()` no longer declares a call-admission budget. `cloudflare()` checks
+an overridden `baseUrl` where it is written. The Cloudflare connection ships 52
+named tools instead of 55, having been measured against its own escape hatches
+rather than assumed to beat them. And Cloudflare and Notion now refuse a
+redirect and cap the response they will read, which is visible only to a
+deployment that was downloading something enormous through a tool call. Each
+of those has a one-line migration, spelled out below.
+
+A deployment that writes no `api()` connectors and runs none of the five
+prebuilt connections can upgrade without editing anything. Nothing in the core
+runtime surface moved: the seven meta-tools, the executor contract, the storage
+interfaces, the route table, and the wire shapes are where they were. The
+tarball is half the size, the guides are all written, and `connecta init` now
+produces a project that runs under `docker compose up` without becoming a
+second project shape.
+
+`api()` stops being forgiving. A hand-written tool now declares what it does
+and whether calling it needs a human, and any `inputSchema` it ships is one
+Connecta can actually enforce — all three checked at construction, where a
+deployment can still refuse to boot, rather than discovered by an agent at
+2 a.m. The warn-once-then-pass-raw-arguments-through behavior behind an
+unenforceable schema is gone, and with it the `strictValidation` option that
+existed only to turn it off.
+
+That construction contract breaks `api()` authors and nobody else. Migration is
+mechanical: give every tool a non-empty `description` and an explicit
+`annotations.readOnlyHint` — `true` for a read, `false` for work that should
+cross `call_destructive_tool` — then delete `strictValidation`, which is now
+the only behavior. A tool that used to ship unannotated becomes
+`readOnlyHint: false`, which is exactly the routing it already got.
+Hosted-MCP proxies are untouched: `remoteMcp()` relays a downstream's names,
+descriptions, schemas, and annotations as they arrive, and an unannotated or
+contradictory downstream tool still fails closed onto `call_destructive_tool`.
+Connecta infers read-only behavior from nothing, anywhere.
+
+The maintained Cloudflare connection ships the second break. Its named surface
+was measured against its own escape hatches instead of being assumed to beat
+them, and three tools came out. Every named tool now carries a recorded `keep`,
+`prune`, or `improve` verdict backed by per-tool numbers: catalog tokens, rank
+in a real `search_tools` call for a representative operator request, whether
+classes of argument mistake are refused before the round trip, and whether the
+handler projects Cloudflare's object or hands it back whole. The evidence, the
+tasks, and the reason for every removal — including the one removed for pair
+symmetry rather than for a measured defect — are in
+[`eval/current-version/results/issue-350-evidence.md`](./eval/current-version/results/issue-350-evidence.md).
+**A deployment that calls `set_r2_cors`, `delete_r2_cors`, or `get_r2_metrics`
+has to change.** No capability is lost: `get_r2_cors` still reads a bucket's
+policy, and the usage guide now names the replacement routes —
+`cloudflare_api_mutate` at
+`PUT`/`DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors`, and
+`cloudflare_api_get` at `/accounts/{accountId}/r2/metrics`. Every other
+Cloudflare tool, argument, projection, and annotation is unchanged.
+
+All five maintained prebuilt connections have been audited against the written
+provider conventions, one report per provider, with a verdict for every
+applicable convention. Nineteen misses were found and fixed. Sixteen of them
+were a guide, a title, or a schema description failing to say something the
+implementation already did correctly — the conventions were mostly not asking
+for different behavior, they were asking for the behavior to reach the agent.
+
+Three of them did change behavior, and two of those break a deployment:
+`linear()` now requires an `access` mode, and `mixpanel()` no longer declares a
+call-admission budget. Both failures are loud — one at construction, one as an
+absent ceiling an operator can restore in one option. Everything else is a
+smaller catalog, a better summary, and a guide that says what it always meant.
+
+Underneath all of that, the two hand-written providers stopped each keeping
+their own copy of the same transport safety machinery. Cloudflare and Notion
+now send every request through one guarded transport that owns URL
+confinement, redirect refusal, bounded response reads, and network-failure
+normalization, and owns no opinion at all about what a status code means.
+
+Consolidating it was not free, and three of the differences are visible from
+outside. A 3xx from either provider is refused now rather than followed, which
+is what both used to do by default — a redirect is an instruction to re-send
+the connector's credential to whatever origin `Location` names, and neither
+API has a legitimate one to send. Both providers now cap what they will read,
+at 8 MiB for Cloudflare and 4 MiB for Notion, so a `cloudflare_api_get`
+downloading an R2 object or a Worker script larger than 8 MiB fails instead of
+returning it. And `cloudflare()`'s optional `baseUrl` is checked where it is
+written: a non-loopback plain-http origin, URL-embedded credentials, or a
+query or fragment throws at construction, so a deployment pointed at an http
+proxy stops booting rather than sending it a token.
+
+The repository now models exactly the two deployments it actually has: a Node
+one and a Worker one. `connecta init` still copies the same template, but that
+template now carries its own `Dockerfile` and `docker-compose.yml`, so the
+generated project runs from `npm start` locally and from `docker compose up`
+in production without becoming a second project shape. The two near-identical
+Node scaffolds that sat beside it — `examples/node` and `examples/docker`, the
+latter of which built the Connecta repository rather than a consumer project —
+are gone. Existing deployments can ignore all of this; nothing in the package's
+runtime surface moved.
+
+The three maintained hosted-MCP connections now notice when the catalog they
+were reviewed against moves. Each ships a vetted manifest — the tool names and
+classifications a release read, plus schema digests once a release records
+them — and compares it with the live listing *inside* a catalog refresh the
+deployment already asked for. Nothing new is requested: no scheduled job, no
+background poll, no credential probe, which is the boundary that keeps this
+from being the proactive liveness checking connecta removed. What comes out is
+four counts — unclassified additions, names no longer served, explicit
+annotation conflicts, schema changes — on connector status, on `/health`, and
+in `connecta doctor`, plus one payload-free activity event per change in those
+counts for stores that implement the new optional `recordCatalogDrift`. The
+observation is per runtime and is not persisted, so status, `/health`, and
+doctor answer for the isolate or process that served the refresh — an empty
+report means that runtime has observed nothing, and the activity event is the
+durable half. A deployment can ignore all of it: an unclassified tool already
+failed closed onto `call_destructive_tool` before anyone counted it.
+
+The other half of that story is a command, not a surface. `npm run drift:check`
+is maintainer tooling — it ships nowhere, runs on a laptop before a release, and
+answers the question the runtime counts deliberately cannot: *which* tool moved.
+It diffs each hosted-MCP catalog against the same vetted manifest the connector
+classifies from, using the maintainer's own credential, and it compares the
+handful of endpoints Cloudflare and Notion actually call against those
+providers' published OpenAPI documents — reporting a gone path, a gone method, a
+new deprecation, or a changed contract, and ignoring the two thousand operations
+connecta never touches. No credential goes near CI, nothing is scheduled,
+nothing files itself, and a published specification is drift evidence only: it
+never generates a tool and never becomes a runtime input.
+
+Both deployment shapes now carry the operator feature set the operator pages
+were built for. A fresh `connecta init` used to produce a deployment with a
+Credentials page and no vault, a Tokens page and no issuance, and an Activity
+page with nothing behind it — pages for things that deployment could not do.
+The Node template now ships sign-in, vault, tokens, and activity as four
+clearly-marked commented blocks in `src/index.ts`, each one an environment
+variable and an uncommented block away, plus a deployment-owned
+`src/file-activity.ts` that is compiled rather than commented. The Worker
+example wires the first three outright and comments the fourth, which needs a
+D1 database nobody can create for you. Existing deployments can ignore this
+entirely: nothing in the package's runtime surface moved, and both READMEs
+walk through the enablement.
+
+Finally, the tarball is half of what it was, and nothing that left it was
+reachable. `exports` resolves only into `dist/`, so the packed `src/` was
+never imported by anything — it was there to back the source and declaration
+maps, and all three went together. Out with them, and out with the 230 KB
+README hero image, which npmjs.com renders from the repository anyway. An
+install unpacks to 1.8 MB instead of 3.8 MB. The code, the types, the CLI, the
+template, the Worker example, and every guide are exactly where they were —
+and there are four more guides than there were mid-release, because the four
+stubs `check:package` had been excluding got written instead.
+
+Which is the quiet half of this release. The five prebuilt connections used to
+encode five sets of private judgment about what a good provider surface looks
+like; that judgment is now two written convention sets, H1–H14 for hand-written
+`api()` surfaces and P1–P13 for `remoteMcp()` proxies, each rule carrying its
+reason and the agent cost it reduces. The placeholder guides in
+`documentation/` — which covered, with some irony, the load-bearing subsystems,
+while the newest features had the best docs — are written against the code as
+it is, and none is left. And the ethos bullet that promised
+"observable, never administrable" was retired for one that is true: operator
+routes manage authentication material for capabilities declared in deployment
+configuration, and a suite now snapshots every declared structure and demands
+it back byte-identical after each operator mutation.
+
+### Added
+
+- **Two written provider convention sets.**
+  [`documentation/provider-conventions.md`](./documentation/provider-conventions.md)
+  states H1–H14 for hand-written `api()` surfaces, where Connecta owns every
+  name, schema, projection, and error, and P1–P13 for `remoteMcp()` proxies,
+  where the downstream owns the catalog and Connecta owns the endpoint,
+  credential, classification, guide, and budget. Every convention carries its
+  rule, its reason, and which of the four agent costs it reduces — discovery
+  tokens, wrong-tool selection, argument retries, result size — and names the
+  budgets at which the surface itself starts dropping characters: 160 for a
+  tool description in search, 240 in describe, 1,024 bytes per compact schema,
+  120 for a guide summary. A description longer than its budget is written for
+  nobody (#339).
+- **The core subsystem guides, written.** `architecture.md`,
+  `request-admission.md`, `call-admission.md`, and `operations.md` were
+  identical seven-line placeholders pointing at git history; they now describe
+  the code as it is — the two lifetimes, the ordered route table and why each position is
+  behavior rather than taste, the import-graph purity rule and what it actually
+  prevents, both admission pools and why `/mcp` admits before it authenticates,
+  and the connector-partitioned downstream policy. `operations.md` also carries
+  the test map AGENTS.md had been deferring since the docs restructure: all 61
+  suites plus the two browser specs, with each Node-only suite's reason for not
+  running in workerd, so "this suite exists" and "this suite is justified" are
+  one lookup. `connector-guides.md` gains the general authoring half #339 left
+  open, including the `required` flag in full. With no stubs left, the four
+  `!documentation/…` negations in `files` went too (#348).
+- **A maintainer-run provider drift check.** `npm run drift:check` diffs the
+  live Linear, Stripe, and Mixpanel catalogs against their vetted manifests by
+  name — added, no longer served, annotation conflicts, and schema changes — and
+  cross-checks its totals against the runtime `detectCatalogDrift()`, because
+  two readings of one manifest that disagree mean one of them is lying. Its
+  second half compares committed touched-endpoint manifests
+  (`scripts/drift/cloudflare-endpoints.json`, `scripts/drift/notion-endpoints.json`:
+  method, path, reviewed spec revision, reviewed deprecation, contract digest)
+  with each provider's published OpenAPI document, and `--record` refreshes
+  them. Deprecation is reported as a transition in either direction, so a
+  reviewed one stops being news. A missing credential, an unreachable
+  specification, or a `--provider` the selected half does not check stops the
+  run and says which one.
+  Written up in
+  [`documentation/provider-conventions.md`](./documentation/provider-conventions.md#the-maintainer-run-drift-check)
+  (#351).
+- **Hosted-provider drift detection at refresh.** Linear, Stripe, and Mixpanel
+  each ship a vetted manifest and compare it with the live catalog while
+  serving a refresh that was going to happen anyway. `ConnectorStatus` gains
+  `catalogDrift` (four counts and the time they were observed), `/health` gains
+  the same per connector, `connecta doctor` reports it without failing on it,
+  and `ActivitySink` gains an optional `recordCatalogDrift` that receives one
+  payload-free event per change in the counts. Both read surfaces report what
+  the answering runtime observed — the observation is isolate-local, not
+  persisted — and both project the counts rather than echo the connector seam.
+  The policy is written up in
+  [`documentation/provider-conventions.md`](./documentation/provider-conventions.md#the-runtime-drift-policy)
+  (#343).
+- **The Node template is Docker-ready.** `Dockerfile`, `docker-compose.yml`,
+  and `.dockerignore` ship with `connecta init`. The image installs
+  `@zackbart/connecta` from the registry like any other consumer, runs as the
+  non-root `node` user with state on a named volume, probes the always-open
+  `/health` route, and keeps Node in the foreground so `compose down` stops it
+  promptly. `PUBLIC_URL` and `CONNECTA_STATE_FILE` now configure the generated
+  `src/index.ts`, which is what makes one source serve both run paths (#344).
+- **The package smoke exercises the generated container.** `check:package`
+  builds and runs the initialized deployment through Compose and points
+  `connecta doctor` at it; it fails rather than skips when Docker is missing
+  in CI (#344).
+- **A deterministic named-surface measurement lane.**
+  `npm --prefix eval/current-version run report:cloudflare-surface` measures the
+  maintained Cloudflare connection one tool at a time and writes a JSON and
+  Markdown artifact. It needs no model, no network, and no credential: the real
+  constructor, schemas, validation path, handlers, and catalog service run, and
+  only `fetch` is a probe that records the request (#350).
+- **Five provider audit reports** in
+  [`documentation/provider-audit.md`](./documentation/provider-audit.md), with
+  a verdict per convention, the fix for every miss, and every accepted
+  exception recorded with its argument (#342).
+- **A convention test over the shipped surface.**
+  `test/provider-conventions.test.ts` walks both `api()` providers on every run
+  and enforces the mechanically checkable bar — naming, description budgets,
+  closed schemas described at every depth, compact-render budgets, declared
+  outputs, structured guides, and credential tests — so a convention met once
+  stays met. The one accepted gap, the undescribed name/value members of
+  Cloudflare's escape-hatch request parts, is listed by path in the suite with
+  its argument rather than left for a shallower check to miss (#342).
+- **Guide coverage the schemas cannot carry.** Stripe and Mixpanel guides now
+  name their id-resolution rules, say the hosted catalog is not a fixed set, and
+  give the `auth_required` → `authorize_connector` recovery route. Notion's
+  guide states that it deliberately has no raw-REST escape hatch (#342).
+- **A guarded fetch transport for hand-written connectors.** One factory
+  supplies the machinery every `api()` HTTP surface was re-deriving: strict
+  base-origin and path confinement checked after URL normalization, encoded
+  query and JSON body construction, `ctx.signal` propagation, a required
+  response-byte ceiling enforced while reading, a flat refusal to follow a
+  redirect or to let a request header shadow an authentication one, and an
+  unreachable provider normalized to a retryable `unavailable`. Authentication
+  and status interpretation stay in provider callbacks — the helper never
+  guesses what a 403 means. Cloudflare and Notion both run on it; it is held
+  internal this release rather than exported, and
+  [`documentation/connectors.md`](./documentation/connectors.md#the-guarded-fetch-transport)
+  records why (#341).
+- **The operator feature set in both deployment shapes.** The Node template
+  gains commented, documented configuration for Clerk operator sign-in, the
+  credential vault, access-token issuance, and payload-free activity, the four
+  environment variables they read (passed through Compose and defaulted in the
+  Dockerfile so the container works the moment a block is uncommented), and
+  `src/file-activity.ts` — a deployment-owned `ActivityStore` that appends one
+  JSON line per call and rewrites the log back down to the newest 5,000 once it
+  runs a slack window past that, repairing a torn trailing line on the way in
+  rather than appending onto it. The Worker example wires the credential vault
+  to a new `CREDENTIAL_ENCRYPTION_KEY` secret beside the Clerk and access-token
+  configuration it already had, and carries the D1 activity wiring and its
+  binding as commented lines rather than as README-only instructions. Both
+  READMEs walk through enabling each half — including the part neither vault
+  can supply, a connector that declares a `credential` slot, which is what puts
+  the Credentials page in the nav — and both say why `connecta doctor` reports
+  none of it: doctor holds a bearer, and a client key does not get to learn a
+  deployment's configuration topology (#345).
+
+### Changed
+
+- **The operator boundary is stated as authentication material.** "Observable,
+  never administrable" had stopped describing the surface — operator routes
+  rotate credentials, issue and revoke access tokens, and drive downstream
+  OAuth, each under its own accepted decision. The ethos bullet, the invariant,
+  and a new decisions row now say the true thing: operator routes may manage
+  authentication material for capabilities *declared* in deployment
+  configuration, and may never change the connector set, the declared tool
+  catalog or annotations, requested OAuth scopes, admission policy,
+  authorization rules, or caller tool scope. The word "declared" is doing work
+  twice over — a broader-scoped replacement token widens downstream reach and
+  no browser page can honestly promise otherwise, and a remote MCP server's
+  catalog is discovered rather than declared, so storing a credential can take
+  an `mcp()` connector from no tools to N. That is discovery arriving, which is
+  exactly why those routes call `invalidateStored()`.
+  `test/operator-boundary.test.ts` snapshots every declared structure, drives
+  each operator mutation route against both a static and a re-listing
+  connector, and requires the snapshot back byte-identical; a second case
+  proves the snapshot can fail. No runtime behavior changed (#338).
+- **The operator UI is a component app.** The hand-written DOM layer is gone,
+  replaced by a small Preact app compiled by the same esbuild step and inlined
+  into a shell that is now a mount point rather than a page. Nothing builds
+  HTML from strings any more, so the escaping every rendered value used to
+  depend on is structural; the served markup is identical on all four pages and
+  still carries no operator data. Credential, token, and OAuth flows gained
+  deliberate loading, error, empty, and success states — a failed save keeps
+  the form and what was typed in it, a failed list offers a retry, and an empty
+  collection says what would fill it. Each connector card also reads the drift
+  the last catalog refresh saw (#343) as four category counts, with `clean`,
+  `warning`, and "not observed in this runtime" kept as three distinct answers
+  — no tool name, schema, or payload rides that panel. Preact rides in as a
+  `devDependency` inlined into the committed bundle and never reaches a
+  deployment's dependency tree (#347).
+
+- **`api()` enforces its construction contract.** Every tool requires a
+  non-empty `description` and an explicit boolean `annotations.readOnlyHint`;
+  a missing or non-boolean classification throws with the address that needs
+  fixing. The classification is never inferred from a tool name, description,
+  schema, HTTP method, or the other annotations (#340).
+- **An unenforceable `inputSchema` fails at construction.** A schema the
+  validator cannot compile throws when the connector is built, whether or not
+  `validateArgs` is on — opting out of enforcement is not opting out of the
+  schema being real. A schema that only reveals itself on first use, such as an
+  unresolvable `$ref`, now fails that call as non-retryable `invalid_args`
+  instead of forwarding raw arguments to the handler (#340).
+- **`linear()` requires `access`.** There is no safe default between Linear's
+  two endpoints: `"read-write"` hands out writes nobody asked for, and
+  `"read-only"` breaks a writing deployment at Linear, at runtime, where no
+  agent can repair it. Construction now throws naming both options. Add
+  `access: "read-write"` to keep an existing deployment's behavior (#342).
+- **`mixpanel()` declares no call-admission budget.** The old hardcoded 600
+  calls per hour transcribed a limit Mixpanel meters *per user*, which a
+  per-runtime counter cannot approximate in either direction. Supply
+  `callAdmission` explicitly if the account needs a ceiling, as Linear already
+  did (#342).
+- **`mixpanel()` titles itself by region.** The default title is now
+  `Mixpanel (us)`, `(eu)`, or `(in)`, and the guide opens with the residency,
+  because a project lives in exactly one and search never shows a description.
+  An unknown region throws at construction (#342).
+- **Provider guides are structured everywhere.** All five declare an explicit
+  `summary` instead of leaning on the guide's first line, which was truncating
+  the routing fact at 120 characters on three of them (#342).
+- **Smaller discovery payloads.** Over-budget tool descriptions
+  (`cloudflare_api_get`, `cloudflare_api_mutate`, `create_dns_record`, Notion's
+  `search`) were trimmed to the 240-character describe budget, and shared
+  property descriptions were cut so `cloudflare_api_upload` and
+  `query_data_source` render inside the 1,024-byte compact budget instead of
+  degrading and costing a describe round trip (#342).
+- **Cloudflare and Notion never follow a redirect.** Both used `fetch`'s
+  default `redirect: "follow"` and now send `redirect: "manual"`; a 3xx fails
+  as non-retryable `connector_call_failed` instead of re-sending the
+  connector's credential to whatever origin the `Location` names (#341).
+- **Cloudflare and Notion bound the response they will read.** 8 MiB and
+  4 MiB respectively, enforced against a declared `Content-Length` before the
+  first byte and again while the body streams. Both are ceilings on absurdity
+  rather than quotas — anything near them was already past whatever
+  `maxResultBytes` the deployment set — but a `cloudflare_api_get` reading an
+  R2 object or Worker script past 8 MiB now fails as non-retryable instead of
+  returning it (#341).
+- **`cloudflare()` checks its `baseUrl` at construction.** A non-loopback
+  plain-http origin, URL-embedded credentials, or a query or fragment throws
+  where the connector is written rather than on the first call. A deployment
+  overriding `baseUrl` with an http proxy must move it to https or bind it to
+  loopback; the default Cloudflare base is unaffected (#341).
+
+### Fixed
+
+- **`connecta doctor` names the sandbox that actually ran the program.** It
+  printed "QuickJS executed" at every deployment it had ever checked, including
+  the Worker example, whose sandbox is a Dynamic Worker — the one field the
+  Worker README says doctor confirms, reported wrong. The deployment now says
+  what its executor is: `/health` carries the configured executor's name when
+  it has one (an explicit `name`, else a class-shaped executor's constructor
+  name), sanitized and bounded because it lands in a public response body and
+  an operator's terminal. Doctor reports that name, and a deployment whose
+  executor identifies as nothing gets `code executed` rather than a guess. The
+  Node template still reads `QuickJS executed`; the Worker example now reads
+  `DynamicWorkerExecutor executed` (#368).
+- **The Node template's `.env.example` ships an empty `CONNECTA_TOKEN`.**
+  `docker-compose.yml` has always promised to refuse a deployment with no
+  inbound auth, but its `${CONNECTA_TOKEN:?…}` guard only fires on unset or
+  empty — and the file it reads shipped `replace-me`, which is neither. Copying
+  `.env.example` and running the README's Docker block therefore produced a
+  healthy, port-published deployment whose bearer token was a string published
+  in this repository. The value is now empty, so both Compose and `npm start`
+  refuse until an operator sets one (#367).
+- **The Worker example names the optional peer it imports.**
+  `examples/worker` wires `clerkAuth` by default and calls itself the starting
+  template for a deployment, but its README listed only `@cloudflare/codemode`
+  as an extra install. `@clerk/backend` is an optional peer that never installs
+  with Connecta, and `auth/clerk` imports it at the top level, so a copied
+  deployment following the README verbatim died at
+  `Could not resolve "@clerk/backend"` before it ever reached Cloudflare. The
+  deploy section now carries the whole install line for a copy in its own
+  repository (#367).
+- **A malformed Clerk publishable key fails like a configuration mistake.**
+  `clerkAuth` derives its Frontend API origin by base64-decoding
+  `publishableKey` and used to hand a bad key straight to `atob`, so the
+  placeholder the Workers example ships raised a bare `InvalidCharacterError`
+  from inside the returned object — and, on a deployment that builds per
+  request, turned every route including `/health` into a 500 whose stack named
+  base64 instead of the environment variable. The key's shape is now checked
+  where `allowedDomains` is, at construction, and the throw names the option.
+  It does not quote the rejected value back: the usual way to land here is
+  pasting the secret key into the publishable slot (#366).
+- **Notion declares the `required` lists it was missing.** `search`,
+  `list_users`, `get_self`, and `create_page` now say which arguments a call
+  must carry, so a malformed call is refused locally instead of at Notion. The
+  fail-closed schema handling those lists rely on is the package default as of
+  #340 (#342).
+- **Cloudflare's cursor pagination says so in the schema.**
+  `list_zone_rulesets`, `list_kv_keys`, `list_r2_buckets`, and
+  `list_r2_objects` now state on both the `cursor` argument and the
+  `nextCursor` result that they page by cursor and return no `page` object —
+  previously only the usage guide said it (#342).
+- **Nested schema properties describe themselves.** The six fields inside
+  `bulk_write_kv_values`'s `entries[]` — including the expiry pair, whose units
+  and 60-second floor were the entire question — and Notion's
+  `sorts[].direction` were shipping bare types, because H5's description rule
+  had only ever been read at the top level (#342).
+
+### Removed
+
+- **`ApiOptions.strictValidation`.** Fail-closed schema handling is the only
+  behavior, so the opt-in has nothing left to switch. Delete the option;
+  nothing else changes (#340).
+- **Three Cloudflare named tools; the connection ships 52, down from 55.**
+  `set_r2_cors` declared a free-form rule body, so its schema validated the ids
+  and waved through the part of the call that fails, and `get_r2_metrics` put
+  one account id into a path and returned the response unprojected — both
+  measurably weaker than the raw call that replaces them. `delete_r2_cors`
+  measured clean and went anyway, to keep the CORS write pair together: with
+  the write unnamed, a named delete would leave half of policy management on
+  each route. All three are one raw call away, and the guide says which one
+  (#350).
+- **`examples/node` and `examples/docker`.** Both were diffs from the
+  template. `examples/` is the Worker deployment now, and the root
+  `.dockerignore` that existed only for the repository-context Docker build
+  went with them (#344).
+- **`src/`, `.js.map`, `.d.ts.map`, and `assets/` — from the tarball only.**
+  All of them are still in the repository; none of them ships. The published
+  package is 167 files and 550 KB, down from 357 and 1.1 MB. The stub guides
+  left with them and came back written (#348), which is why the file count is
+  four higher than the trim alone left it.
+  Stepping into Connecta's TypeScript from an installed copy no longer works;
+  the emitted JavaScript and the `.d.ts` files beside it do. `check:package`
+  now fails on a packed `src/`, `.map`, or `assets/` path, derives the shipped
+  guide list from which guides are still stubs, so filling one in ships it, and
+  refuses a packed document whose relative link lands on a guide the tarball
+  does not carry — the three that pointed at `operations.md` now name it
+  instead (#346).
+
 ## 0.15.1 — 2026-08-12
 
 The Cloudflare connection now supports legacy user-scoped Global API Keys as