@zackbart/connecta 0.15.1 → 0.16.1

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
 
@@ -77,11 +83,18 @@ Two boundaries CI enforces that are not obvious from reading a file:
   and fails otherwise. Need a Node API? It goes behind an explicit Node-only
   subpath (`/node` or `/quickjs`), never the root.
 - **The published surface.** Platform-specific storage adapters live in
-  `examples/`, not the package. `@clerk/backend` and `quickjs-emscripten` are
-  optional peers behind the `./auth/clerk` and `./quickjs` subpaths and must
-  never become dependencies or install with core. Enforced by
-  `test/package-surface.test.ts` and `scripts/check-package.mjs`. Anything
-  heavyweight or platform-bound gets a subpath and an optional peer.
+  `examples/worker/`, never in `src/` and never in the `exports` map. That
+  example does ship in the tarball, Cloudflare KV and D1 adapters included —
+  it is the Workers starting template a consumer copies, and copying it is the
+  point — but every `exports` target resolves into `dist/`, so those adapters
+  are readable reference source and not an importable subpath. What is
+  forbidden is a platform-bound adapter becoming importable from the package,
+  not a file appearing in the artifact. `@clerk/backend` and
+  `quickjs-emscripten` are optional peers behind the `./auth/clerk` and
+  `./quickjs` subpaths and must never become dependencies or install with
+  core. Enforced by `test/package-surface.test.ts` and
+  `scripts/check-package.mjs`. Anything heavyweight or platform-bound gets a
+  subpath and an optional peer.
 
 ## Where new tests go
 
@@ -91,9 +104,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 +122,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