@open-everywhere/create 0.1.4 → 0.1.5

package/NOTICE

@@ -8,10 +8,40 @@ This product is licensed under the Apache License, Version 2.0 (see LICENSE).
 Built on Vercel Eve (https://github.com/vercel/eve), licensed under the
 Apache License, Version 2.0.
 
-@open-everywhere/core also ships a patch that modifies Vercel Eve (the file in
-its patches/ directory), with the oe-eve-patch command that applies it to a
-consumer's own installed copy. The patch is licensed under the Apache License,
-Version 2.0. No modified Vercel Eve files are distributed.
+---
+
+Modifications to eve
+
+The @open-everywhere/core package distributes patches/eve+0.54.3.patch. That
+patch file is a modification of eve 0.54.3. Vercel licenses eve 0.54.3 under the
+Apache License, Version 2.0. The copyright notice of eve 0.54.3 reads
+"Copyright 2026 Vercel, Inc. and contributors". The Open Everywhere authors made
+the changes in the patch file.
+
+The patch modifies six files of eve 0.54.3:
+
+  dist/src/context/dynamic-tool-lifecycle.js
+  dist/src/execution/web-fetch/request.js
+  dist/src/harness/tool-loop.js
+  dist/src/internal/authored-package-boundary.js
+  dist/src/protocol/message.d.ts
+  dist/src/tasks/session-index.js
+
+Open Everywhere does not ship the eve package. eve is a peer dependency, so the
+consumer installs eve 0.54.3 from the registry. The patch file carries the
+modified portions of eve. The oe-eve-patch command, which
+@open-everywhere/core ships, applies them to the eve that the consumer
+installed. The command writes no file outside the consumer's own project.
+
+The attribution notice of eve 0.54.3 follows, as section 4(d) of the Apache
+License, Version 2.0 requires. The notices for eve's bundled code-mode runtime
+are not reproduced, because the patch modifies no part of that runtime.
+
+eve
+Copyright 2026 Vercel, Inc. and contributors
+
+This product includes software developed at Vercel, Inc.
+(https://vercel.com/).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-everywhere/create",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "Apache-2.0",
   "type": "module",
   "description": "npx scaffold and setup check for Open Everywhere — one step engine, reported by --check for an agent-led setup.",
@@ -40,14 +40,14 @@
     "test:engine": "tsx scripts/engine-test.ts",
     "test:cli": "tsx scripts/cli-check-test.ts",
     "test": "npm run test:chain",
-    "test:chain": "npm run test:engine && npm run test:scaffold && npm run test:cli && npm run test:env-pipe && npm run test:boot-free",
+    "test:chain": "tsx ../../scripts/chain/run-chain.ts",
     "test:boot-free": "tsx scripts/boot-free-test.ts",
     "test:scaffold": "tsx scripts/scaffold-test.ts",
     "test:env-pipe": "tsx scripts/env-pipe-test.ts"
   },
   "dependencies": {
-    "@open-everywhere/core": "0.1.4",
-    "@open-everywhere/provider-slack": "0.1.4",
+    "@open-everywhere/core": "0.1.5",
+    "@open-everywhere/provider-slack": "0.1.5",
     "tsx": "^4.23.9"
   },
   "devDependencies": {

package/src/steps/roster.ts

@@ -85,6 +85,9 @@ function rosterNext(detail: string): string {
   if (/npm install/.test(detail)) return "npm install";
   if (/UNREVIEWED|missing — nothing has been REVIEWED/.test(detail)) return "review the contribution in roster.config.ts, then `npx oe build --accept` and read the roster.lock.json diff";
   if (/NOT BUILT/.test(detail)) return "npm run build";
+  // OPE-2217: `oe build --check` also proves the overlays hold only data. `oe build` never writes an
+  // overlay, so it cannot clear this red.
+  if (/OVERLAY ·/.test(detail)) return "edit only the data in the named overlay, then `npx oe overlays normalize`";
   return "npx oe build";
 }
 

package/template/AGENTS.md

@@ -35,7 +35,8 @@ Setup is yours to drive, with the user's consent at every command. Use the
   `agent/connections/` and `agent/lib/providers.generated.ts` — `oe build` output. Never edit or
   commit them.
 - `*.generated.ts` — machine-owned overlays that the agent's own approval flows write by pull
-  request. Never edit them by hand.
+  request. Never edit them by hand. `npx oe overlays check` proves each one holds only data, and
+  `npx oe overlays normalize` re-emits them after a data edit.
 - `scripts/ops-mcp.ts` — the ops MCP server. `scripts/env-pipe.mjs` — `npm run -s env:pipe`, which
   pipes one `.env.local` value into `vercel env add`. Always pipe it; never run it bare.
 
@@ -47,6 +48,8 @@ Setup is yours to drive, with the user's consent at every command. Use the
   `npm run dev` and `npm start` run `oe build` first too.
 - `oe build` refuses a contribution the lock has not reviewed. Decide about it in
   `roster.config.ts`, then run `npx oe build --accept`, and review the lock diff.
+- `npx oe build --check` verifies the slot tree without a write, and proves the overlays hold
+  only data. Run it before you merge a pull request that changes an overlay.
 - `npm run typecheck` type-checks the app.
 - Deploy is a separate, explicit step. On the Vercel route that is `npx vercel deploy --prod`; a
   `git push` does NOT deploy.

package/template/README.md

@@ -60,7 +60,8 @@ without a public tunnel.
 `agent/tools/`, `agent/channels/`, `agent/hooks/`, `agent/schedules/`, `agent/skills/`,
 `agent/connections/` and `agent/lib/providers.generated.ts` are `oe build` output. They are not
 committed. The `*.generated.ts` files are machine-owned overlays that the agent's own approval flows
-write by pull request. Do not edit them by hand.
+write by pull request. Do not edit them by hand. `npx oe build --check` (or `npx oe overlays check`)
+proves they hold only data. After a data edit, run `npx oe overlays normalize`.
 
 ## Add a surface
 

package/template/agent/access/credential-bindings.generated.ts

@@ -1,14 +1,15 @@
 // GENERATED + MACHINE-OWNED — DO NOT HAND-EDIT.
 //
 // The credential-bindings overlay: DATA ONLY. Written exclusively by the deterministic codemod
-// (packages/core/agent/access/credential-bindings-codemod.ts) on a bot-PR branch; the PR merge is the approval gate.
+// (@open-everywhere/core/agent/access/credential-bindings-codemod.js) on a bot-PR branch; the PR merge is the approval gate.
 //
 // The codemod re-emits this file from its own parsed content and refuses to rewrite it when the
-// bytes differ, so a hand-edit stops the next machine PR. Before a merge, nothing checks that the
-// file is still data only unless the repository runs its own check: the person who merges the PR
-// is the gate. Read a PR to this file as code, because it is code.
+// data or the import differ, so a hand-edit there stops the next machine PR. Before a merge,
+// nothing checks that the file is still data only unless the repository runs
+// `npx oe build --check` or `npx oe overlays check`: the person who merges the PR is the gate.
+// Read a PR to this file as code, because it is code.
 //
-// To change it by hand, edit only the data below and keep the layout exactly as emitted.
+// To change it by hand, edit only the data below, then run `npx oe overlays normalize`.
 
 import type { CredentialBindingsFile } from "@open-everywhere/core/agent/access/credential-bindings-codemod.js";
 

package/template/agent/access/grants.generated.ts

@@ -1,14 +1,15 @@
 // GENERATED + MACHINE-OWNED — DO NOT HAND-EDIT.
 //
 // The grants overlay: DATA ONLY. Written exclusively by the deterministic codemod
-// (packages/core/agent/access/grants-codemod.ts) on a bot-PR branch; the PR merge is the approval gate.
+// (@open-everywhere/core/agent/access/grants-codemod.js) on a bot-PR branch; the PR merge is the approval gate.
 //
 // The codemod re-emits this file from its own parsed content and refuses to rewrite it when the
-// bytes differ, so a hand-edit stops the next machine PR. Before a merge, nothing checks that the
-// file is still data only unless the repository runs its own check: the person who merges the PR
-// is the gate. Read a PR to this file as code, because it is code.
+// data or the import differ, so a hand-edit there stops the next machine PR. Before a merge,
+// nothing checks that the file is still data only unless the repository runs
+// `npx oe build --check` or `npx oe overlays check`: the person who merges the PR is the gate.
+// Read a PR to this file as code, because it is code.
 //
-// To change it by hand, edit only the data below and keep the layout exactly as emitted.
+// To change it by hand, edit only the data below, then run `npx oe overlays normalize`.
 
 import type { GrantsFile } from "@open-everywhere/core/agent/access/grants-codemod.js";
 

package/template/agent/access/network-access.ts

@@ -3,7 +3,7 @@
 // per scope on the container ladder (org < tenant < domain < surface); an unpinned scope
 // inherits the nearest wider pin, and a scope no pin reaches at all resolves "none" — the same
 // egress posture every scope already has today. See docs/how-it-works/access-and-scoping.md in the Open Everywhere repository
-// (§ Network-access levels) and packages/core/agent/access/network-access.ts for the resolution
+// (§ Network-access levels) and @open-everywhere/core/agent/access/network-access.js for the resolution
 // doctrine and exactly what "trusted" opens.
 //
 // LEFT EMPTY, DELIBERATELY. This ticket adds the CONFIG SHAPE — it does not widen this

package/template/agent/blob/hosting.ts

@@ -1,5 +1,5 @@
 // Blob hosting — config-as-code, the org-level opt-in for PUBLISHING HTML artifacts to a
-// world-readable Vercel Blob URL from the post_file tool (packages/core/agent/tools/post_file.ts).
+// world-readable Vercel Blob URL from the post_file tool (@open-everywhere/core/agent/tools/post_file.js).
 //
 // OFF BY DEFAULT. With `enabled:
 // false` — the shipped default — post_file NEVER hosts: an HTML artifact is attached to the

package/template/agent/identity/groups.generated.ts

@@ -1,14 +1,15 @@
 // GENERATED + MACHINE-OWNED — DO NOT HAND-EDIT.
 //
 // The person-groups overlay: DATA ONLY. Written exclusively by the deterministic codemod
-// (packages/core/agent/identity/groups-codemod.ts) on a bot-PR branch; the PR merge is the approval gate.
+// (@open-everywhere/core/agent/identity/groups-codemod.js) on a bot-PR branch; the PR merge is the approval gate.
 //
 // The codemod re-emits this file from its own parsed content and refuses to rewrite it when the
-// bytes differ, so a hand-edit stops the next machine PR. Before a merge, nothing checks that the
-// file is still data only unless the repository runs its own check: the person who merges the PR
-// is the gate. Read a PR to this file as code, because it is code.
+// data or the import differ, so a hand-edit there stops the next machine PR. Before a merge,
+// nothing checks that the file is still data only unless the repository runs
+// `npx oe build --check` or `npx oe overlays check`: the person who merges the PR is the gate.
+// Read a PR to this file as code, because it is code.
 //
-// To change it by hand, edit only the data below and keep the layout exactly as emitted.
+// To change it by hand, edit only the data below, then run `npx oe overlays normalize`.
 
 import type { GroupsFile } from "@open-everywhere/core/agent/identity/groups-codemod.js";
 

package/template/agent/instructions.md

@@ -81,7 +81,7 @@ for word: names, titles, tokens, times, the exact text to post or to schedule. "
 specified" or "the text they gave" points at nothing the worker can read. You never
 know the id of the page or channel you are on: the channel id is opaque, and a message
 id is not a page id. For a task about "this page", tell the worker to read the current
-page; never put an id you inferred
+page (`page markdown current` on the notion-rest skill); never put an id you inferred
 into the brief. Name an id only when the person named it. Say you have handed it off, and report it done only when the worker's own report says it is done.
 That report can arrive after this turn ends.
 

package/template/agent/lib/register-adapters.ts

@@ -175,7 +175,7 @@ applySubtreeSurfaceClaims();
 // the Neon Marketplace integration sets DATABASE_URL and nothing else, `getOperationalStore()` then
 // resolves to postgres, no client is ever registered, and the first audit append throws. The
 // scaffolded app is dead rather than degraded, and it mounts no status route to say why.
-// `scripts/scaffold-test.ts` reds if this returns to testing the two env names.
+// The Open Everywhere repository's `packages/create/scripts/scaffold-test.ts` reds if this returns to testing the two env names.
 const operationalSelection = resolveOperationalSelection(process.env);
 const postgresSelected =
   resolveMemoryProviderId(process.env) === "postgres" ||

package/template/agent/lib/register-config.ts

@@ -75,6 +75,11 @@ import "../identity/authors.js";
 // import degrades loudly (a routine that names a collector stops being creatable) rather than
 // silently widening anything.
 import "../routines/collectors.js";
+// Side effect: register the deployment-wide half of the SHIPPED MANUAL (OPE-138, OPE-2215) so the
+// read_docs tool serves the configuration reference, the security docs and the how-it-works pages.
+// Each provider package registers its own setup runbook from register<X>Provider() instead. Drop
+// this import and read_docs serves those runbooks and nothing else.
+import "./register-docs.js";
 
 // The BEHAVIOUR half of config-as-code (OPE-371), registered FIRST — before registerConfig, and
 // before the boot-time cross-validations below — because a settings-sensitive gate consulted during

package/template/agent/lib/register-docs.ts

@@ -0,0 +1,17 @@
+// Shipped-manual wiring (OPE-138) — hands core the deployment-wide half of the docs the agent can
+// read about itself. SELF-REGISTERING: importing this module performs the registration, the same
+// shape as agent/identity/surfaces.js (see register-config.ts, which imports both for their
+// side effects, so every process that resolves config also carries the manual).
+//
+// This half is the UNIVERSAL manual. Each provider bundle registers its OWN setup runbook from its
+// register<X>Provider(), so a de-selected bundle's docs are not in the import graph at all.
+//
+// The manual ships INSIDE `@open-everywhere/core` (OPE-2215), so this app serves the pages of the
+// core version it installed, and an upgrade of core upgrades the manual with it. Nothing here is
+// copied at scaffold time. To add your own pages, call registerDocs again with more entries. An
+// entry with the same `path` as a shipped page replaces that page.
+
+import { registerDocs } from "@open-everywhere/core/agent/adapter-api.js";
+import { UNIVERSAL_DOCS } from "@open-everywhere/core/agent/docs/generated/index.js";
+
+registerDocs(UNIVERSAL_DOCS);

package/template/agent/memory/config/agents.generated.ts

@@ -1,14 +1,15 @@
 // GENERATED + MACHINE-OWNED — DO NOT HAND-EDIT.
 //
 // The agents overlay: DATA ONLY. Written exclusively by the deterministic codemod
-// (packages/core/agent/memory/agents-codemod.ts) on a bot-PR branch; the PR merge is the approval gate.
+// (@open-everywhere/core/agent/memory/agents-codemod.js) on a bot-PR branch; the PR merge is the approval gate.
 //
 // The codemod re-emits this file from its own parsed content and refuses to rewrite it when the
-// bytes differ, so a hand-edit stops the next machine PR. Before a merge, nothing checks that the
-// file is still data only unless the repository runs its own check: the person who merges the PR
-// is the gate. Read a PR to this file as code, because it is code.
+// data or the import differ, so a hand-edit there stops the next machine PR. Before a merge,
+// nothing checks that the file is still data only unless the repository runs
+// `npx oe build --check` or `npx oe overlays check`: the person who merges the PR is the gate.
+// Read a PR to this file as code, because it is code.
 //
-// To change it by hand, edit only the data below and keep the layout exactly as emitted.
+// To change it by hand, edit only the data below, then run `npx oe overlays normalize`.
 
 import type { AgentsFile } from "@open-everywhere/core/agent/memory/agents-codemod.js";
 

package/template/agent/sandbox/backend-select.ts

@@ -1,8 +1,8 @@
 // Off-Vercel sandbox backend selection — the app-side re-export of the PURE decision logic.
 //
-// The decision itself lives in core (`packages/core/agent/sandbox/backend-select.ts`) because
+// The decision itself lives in core (`@open-everywhere/core/agent/sandbox/backend-select.js`) because
 // TWO packages need it and a rule has one home: this file wires it into `sandbox.ts`, and the
-// turn-end stop hook (`packages/adapters/agent/sandbox/backend-stop.ts`) reads the SAME answer
+// turn-end stop hook (`@open-everywhere/adapters/agent/sandbox/backend-stop.js`) reads the SAME answer
 // through the adapter-api barrel to pick which backend owns the stop. A second parse of
 // `OE_SANDBOX_BACKEND` would let the backend that runs and the backend that stops disagree.
 

package/template/agent/sandbox/sandbox.ts

@@ -153,7 +153,7 @@ const VERCEL_CREATE_OPTIONS = vercelSandboxCreateOptions({
 // mid-session (the runtime firewall wouldn't allow it; the vendor tools additionally run with
 // autoInstall bound off). Unarmed it is {} — the definition below carries NO bootstrap /
 // revalidationKey property at all, byte-identical to the pre-capability shape. Rationale +
-// fail-closed matrix live in the adapter (packages/adapters/agent/browser/sandbox.ts).
+// fail-closed matrix live in the adapter (@open-everywhere/adapters/agent/browser/sandbox.js).
 const AGENT_BROWSER_BAKE = agentBrowserSandboxHooks();
 
 function selfHostBackend() {

package/template/agent/spend/checkpoints.ts

@@ -13,7 +13,7 @@
 //
 // EMPTY BY DEFAULT — with nothing declared here, nothing is checkpointed (Open Everywhere never
 // invents a threshold). This file is the seam a DB/dashboard would swap behind, same as
-// budgets.ts / memory/config/domains.ts. After adding a checkpoint: `npm run typecheck:all`
+// budgets.ts / memory/config/domains.ts. After adding a checkpoint: `npm run typecheck`
 // (assertSpendCheckpointsValid runs at import time and throws on a malformed entry — bad scope
 // keys, unknown/typo'd fields, non-positive amounts).
 //

package/template/agent/webhooks/hooks.generated.ts

@@ -1,14 +1,15 @@
 // GENERATED + MACHINE-OWNED — DO NOT HAND-EDIT.
 //
 // The webhook-hooks overlay: DATA ONLY. Written exclusively by the deterministic codemod
-// (packages/core/agent/webhooks/hooks-codemod.ts) on a bot-PR branch; the PR merge is the approval gate.
+// (@open-everywhere/core/agent/webhooks/hooks-codemod.js) on a bot-PR branch; the PR merge is the approval gate.
 //
 // The codemod re-emits this file from its own parsed content and refuses to rewrite it when the
-// bytes differ, so a hand-edit stops the next machine PR. Before a merge, nothing checks that the
-// file is still data only unless the repository runs its own check: the person who merges the PR
-// is the gate. Read a PR to this file as code, because it is code.
+// data or the import differ, so a hand-edit there stops the next machine PR. Before a merge,
+// nothing checks that the file is still data only unless the repository runs
+// `npx oe build --check` or `npx oe overlays check`: the person who merges the PR is the gate.
+// Read a PR to this file as code, because it is code.
 //
-// To change it by hand, edit only the data below and keep the layout exactly as emitted.
+// To change it by hand, edit only the data below, then run `npx oe overlays normalize`.
 
 import type { HooksFile } from "@open-everywhere/core/agent/webhooks/hooks-codemod.js";
 

package/template/claude/skills/upgrade-open-everywhere/SKILL.md

@@ -64,6 +64,23 @@ step 3, after the install puts the target's own copy on disk. The same text is i
 **Stop and ask the user** when the window holds a breaking change, an env change or a manual step.
 Those are decisions, not steps.
 
+`--plan` also prints a **template drift** report. It compares every file the scaffold copied into
+this app with the TARGET release's `@open-everywhere/create` template, and lists each one that
+differs, with a one-line size of its diff. An upgrade changes only `package.json`, so a scaffolded
+file stays as the old template wrote it. A stale copy can typecheck and build and still break the
+deployment: the 0.1.2 `agent/lib/register-adapters.ts` registers no Postgres client on a bare
+`DATABASE_URL`, so a Vercel+Neon deployment of 0.1.4 fails at its first write.
+
+| Line | What to do |
+| --- | --- |
+| SYNC | a template-owned file — wiring, a script, `AGENTS.md`, `README.md`, `.env.example`, a skill. Plan to copy the target's file over this one, after you read the diff. |
+| config | the app's own config-as-code. A difference is normal once the app is configured. Merge the template's change by hand only if the user wants it. |
+
+The report never writes a file. If it says the drift check did not run, compare the files with the
+target's template by hand. An installed core without the report prints none: `oe upgrade` runs the
+INSTALLED core's code. So when `--plan` prints no "Template drift" heading, run
+`npx oe upgrade --to <target> --plan` once more after step 3. The target's own code prints the report then.
+
 ## 3. Run the upgrade
 
 ```
@@ -95,10 +112,18 @@ survives `rm -rf node_modules && npm ci`.
 Never delete the marker to make `oe upgrade` say there is nothing to do. It is the only record
 that a run began taking the target and never proved the tree.
 
-**If it refuses with "the release notes name codemods this CLI does not hold":** the codemod ships
-in a newer core than the one you are running. Upgrade in ONE step to a version that holds it, or
-apply those migrations by hand. Do not work around the refusal — it exists because a half-applied
-migration that reports success is worse than a stop.
+**If it refuses with "the release notes name codemods this CLI does not hold":** the running core
+is 0.1.4, and it runs codemods from its own registry. When it stops after the install, the
+target's own `oe` is installed now. Run `oe upgrade` again: the resume marker keeps the window, and
+the target's registry applies the codemod. Apply the migration by hand only if that run refuses
+too. Do not work around the refusal — it exists because a half-applied migration that reports
+success is worse than a stop. A later core only WARNS with that text before the install, because
+the target's own registry decides.
+
+**If it refuses with "the installed core's registry does not hold":** the target release names a
+codemod that it does not ship, and no codemod ran. Run `oe upgrade --to <a later release that holds
+it>`. The resume marker keeps the refused release in that run's window, so that run applies the
+codemod. Do not delete the marker to get past this refusal.
 
 ## 4. Review the diff
 
@@ -115,6 +140,18 @@ is the review surface, and it is the only one.
 Then run the app's own checks once more if anything above was fixed by hand:
 `npm run typecheck && npm run build`.
 
+Then act on the template drift report. A core that carries it prints it again after the install;
+if this run printed no "Template drift" heading, run `npx oe upgrade --to <target> --plan` now to get it. For
+each SYNC line, read the diff against the installed template, for example
+`diff node_modules/@open-everywhere/create/template/agent/lib/register-adapters.ts agent/lib/register-adapters.ts`.
+Keep any edit the user made on purpose, and copy the template's file otherwise. A file under the
+template's `claude/` directory lands in the app's `.claude/`, and the template's `gitignore` is the
+app's `.gitignore`. Name every synced file in the pull request.
+
+Run `npx oe build --check`. It also proves the machine-owned `*.generated.ts` overlays hold only
+data. If it says an overlay has older header text, that is not a failure: run
+`npx oe overlays normalize` and commit the header change with the upgrade.
+
 ## 5. Open a pull request
 
 Commit on a branch, never on the default branch. The body carries:
@@ -124,6 +161,7 @@ Commit on a branch, never on the default branch. The body carries:
 - what changed in `roster.lock.json`, in your own words;
 - **the env names the deployment needs before this merges**, names only;
 - the manual steps, and who does each one.
+- the template files you synced, and each SYNC line you left as it is, with the reason.
 
 Then stop. The admin reviews the lock diff and merges. The merge deploys.