@zackbart/connecta 0.15.0 → 0.16.0

package/AGENTS.md

@@ -42,18 +42,21 @@ exports.
   before building something new; "we already decided not to" is a real answer
   there, and its removed/provisional verdicts override anything staler.
 - [`documentation/`](./documentation/) — per-subsystem guides for agents
-  working on the repo. **Currently stubs**: the old manual (`docs/`) was
-  retired in the phase-1 docs restructure and each guide is being rewritten as
-  the ideas settle. Until a guide is filled in, the subsystem's prior manual
-  text lives in git history (`docs/<name>.md`) — consult it there when you need
-  the old rationale, but treat `ethos.md` as the authority where they disagree.
+  working on the repo. All of them are written now
+  ([#348](https://github.com/zackbart/connecta/issues/348)); the retired manual
+  (`docs/<name>.md`) survives only in git history, which is worth mining for
+  rationale a rewrite dropped and worth nothing where it disagrees with
+  `ethos.md`. Start with `architecture.md`, then the guide for the subsystem
+  you are changing.
 - [`README.md`](./README.md) — the human-facing overview.
 - [`templates/node/`](./templates/node/) — the one standalone Node deployment
-  shape copied by `connecta init`. Keep it small and prescribed; examples may
-  demonstrate alternatives, but they must not become competing scaffolds.
+  shape copied by `connecta init`, Docker-ready rather than Docker-only. Keep
+  it small and prescribed. There are exactly two deployment shapes, this one
+  and [`examples/worker/`](./examples/worker/); a third scaffold that is a
+  diff away from one of them is the shape
+  [#344](https://github.com/zackbart/connecta/issues/344) deleted.
 
-**Read `ethos.md` and the subsystem's guide (or its git-history predecessor)
-before changing a subsystem.**
+**Read `ethos.md` and the subsystem's guide before changing a subsystem.**
 
 ## Deployment setup
 
@@ -61,9 +64,12 @@ before changing a subsystem.**
 pins the generated deployment to the CLI package's exact version, restores the
 template `.gitignore`, and refuses to merge into an existing path.
 `connecta doctor` verifies a running deployment's health, executor, and exact
-seven-tool surface. Setup changes must keep the root README, template, Docker
-example, and `scripts/check-package.mjs` smoke aligned; do not add a second
-initializer or another “recommended” project shape.
+seven-tool surface. The template carries its own `Dockerfile` and
+`docker-compose.yml`, so the generated project is the container: setup changes
+must keep the root README, the template (source, container files, and README),
+and the `scripts/check-package.mjs` smoke — which builds and runs that
+container when Docker is available — aligned. Do not add a second initializer,
+a second container recipe, or another “recommended” project shape.
 
 ## Where new code goes
 
@@ -91,9 +97,9 @@ in `WORKERS_SUITES`, Node-bound suites in `NODE_ONLY_SUITES` with a reason. The
 `node` project runs both lists; the `workers` project re-runs the portable list
 inside workerd. `test/suite-partition.test.ts` walks the directory and fails on
 an unclassified, double-classified, stale, or reasonless entry. New behavior
-also gets a row in the test map in
-[`documentation/operations.md`](./documentation/operations.md) once that guide
-is rewritten; until then the row waits with the guide.
+also gets a row in the test map in `documentation/operations.md`, which
+classifies every suite — one missing from it is either new and undocumented or
+dead, and neither is a state to leave the repository in.
 
 ## Conventions
 
@@ -109,6 +115,13 @@ is rewritten; until then the row waits with the guide.
 - **CHANGELOG.** Each release opens with a narrative paragraph — what this
   release is, what breaks, what a deployment can ignore — then
   `### Added` / `### Changed` / `### Fixed`.
+- **Provider drift.** Before tagging a release, run `npm run drift:check` with
+  local provider credentials exported. It diffs each hosted-MCP catalog against
+  its vetted manifest and each hand-written provider's touched endpoints against
+  the provider's published OpenAPI document. Findings are read by a human and
+  become GitHub issues — no credential goes near CI, and nothing files itself.
+  See
+  [`documentation/provider-conventions.md`](./documentation/provider-conventions.md#the-maintainer-run-drift-check).
 - **Releases.** `npm run release:check`, tag `v<version>` matching
   `package.json` exactly (the publish workflow verifies this and fails
   otherwise), and publishing fires on GitHub **Release publication**, not on the

package/CHANGELOG.md

@@ -2,6 +2,499 @@
 
 All notable changes to this package are documented here.
 
+## 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
+an explicit authentication mode. Scoped API tokens remain the default. The
+three guarded raw tools still cover the full v4 path space without adding one
+tool per endpoint, and ordinary JSON responses such as GraphQL results now
+survive that path intact.
+
+Nothing breaks for existing deployments. They keep their current API token,
+credential form, verification tool, and 55-tool surface. A deployment that
+needs the legacy scheme opts in and stores the Cloudflare user email and Global
+API Key as separate encrypted fields.
+
+### Added
+
+- **Legacy Cloudflare Global API Key authentication.** Set
+  `authentication: "globalApiKey"` to send operator-managed `X-Auth-Email` and
+  `X-Auth-Key` headers. `verify_global_api_key` checks the pair through
+  Cloudflare's authenticated user endpoint, and raw calls cannot replace either
+  connector-owned header.
+
+### Fixed
+
+- **Raw Cloudflare calls preserve non-envelope JSON.** Endpoints such as
+  `/graphql` return their complete JSON document instead of an undefined
+  `result`.
+
 ## 0.15.0 — 2026-08-10
 
 Discovery now keeps strong action/object near-matches visible beside complete

package/README.md

@@ -57,8 +57,12 @@ Point an MCP client at `http://localhost:8787/mcp` with
 ```text
 my-connecta/
 ├── src/index.ts       # connectors, auth, storage, public URL
+├── src/file-activity.ts # deployment-owned activity store, wired on request
 ├── package.json       # exact Connecta and QuickJS versions
 ├── tsconfig.json
+├── Dockerfile         # the same source, containerized
+├── docker-compose.yml # one service, state on a named volume
+├── .dockerignore
 ├── .env.example
 ├── .gitignore
 ├── AGENTS.md
@@ -66,6 +70,13 @@ my-connecta/
 └── README.md
 ```
 
+The same project runs as a long-lived container without changing a line of it:
+
+```sh
+cp .env.example .env    # set CONNECTA_TOKEN
+docker compose up -d --build
+```
+
 For an agent setting this up, the contract is:
 
 1. Edit `src/index.ts`; do not copy Connecta internals into the deployment.
@@ -81,6 +92,12 @@ For an agent setting this up, the contract is:
    the exact seven-tool model-facing surface, then executes a harmless sandbox
    program. The bearer stays in the environment rather than command history.
 
+The operator surface is the same in both shapes and off until you say so:
+Clerk sign-in, the credential vault, access-token issuance, and payload-free
+activity ship as commented configuration, each one a variable and an
+uncommented block away. The generated `README.md` walks through all four, and
+the [Worker example](./examples/worker/) does the same for KV and D1.
+
 The template refuses to merge into an existing directory, so initialization
 cannot overwrite another project. Its generated programs have no filesystem,
 environment, arbitrary network, imports, or timers; only explicitly read-only
@@ -88,11 +105,9 @@ connector tools are reachable. Unannotated or write-capable calls stay
 individual and cross `call_destructive_tool`, where the MCP host can ask the
 operator for approval.
 
-Other supported deployment shapes:
+There are two deployment shapes and no others:
 
-- [Prescribed Node template](./templates/node/)
-- [Node repository example](./examples/node/)
-- [Code-first Docker deployment (repository-only)](https://github.com/zackbart/connecta/tree/main/examples/docker)
+- [Node, local or Docker](./templates/node/) — what `init` copies
 - [Cloudflare Worker deployment](./examples/worker/)
 - [Subsystem documentation](./documentation/)