@open-everywhere/create 0.1.4

package/template/agent/sandbox/workspace/.keep

@@ -0,0 +1,6 @@
+This directory is eve's sandbox WORKSPACE SEED: eve copies its whole subtree into /workspace
+inside every sandbox before any code runs. An EMPTY seed mints no sandbox template, so every
+session starts cold. This one file keeps the template, and a dotfile keeps /workspace clean.
+
+Do not put anything here that a running session is supposed to own (memory in particular): the
+seed is static, and the same bytes reach every session.

package/template/agent/settings/settings.ts

@@ -0,0 +1,19 @@
+// This deployment's behaviour settings. Everything the agent can be opinionated about — which walls
+// are up, which apparatus is armed, what the caps are — is typed code here, so a behaviour change
+// is a pull request against this repo.
+//
+// EMPTY IS A REAL ANSWER: with nothing set, you run the shipped defaults. The schema (every
+// setting, its default and its validation) is `@open-everywhere/core/agent/settings/settings.ts`,
+// and docs/deploy/configuration-reference.md in the Open Everywhere repository carries the operator table. `defineSettings` validates
+// at module load, so a typo fails the boot instead of doing nothing.
+//
+// Examples:
+//   identity: { name: "Ada" },        // the name the agent answers to
+//   browser: { enabled: true },       // arm the in-sandbox browser (hosts: agent/access/browser-hosts.ts)
+//
+// Not a secret store. Keys, tokens and database URLs stay in the environment or the encrypted
+// credential store.
+
+import { defineSettings } from "@open-everywhere/core/agent/settings/settings.js";
+
+export const SETTINGS_OVERRIDES = defineSettings({});

package/template/agent/spend/budgets.ts

@@ -0,0 +1,25 @@
+// Spend budgets — monthly caps, as a token count and/or a USD amount, per surface, per workspace,
+// per domain, or as a blanket default. The narrowest entry wins for a scope. Enforcement is
+// pre-flight at every new-spend origin (a mention, a routine fire, a webhook fire): an over-cap
+// scope refuses new work until the month rolls over, the config is raised, or an admin approves a
+// temporary override.
+//
+// EMPTY BY DEFAULT — nothing is capped until you declare a budget. `assertSpendBudgetsValid` runs
+// at import, so `npm run typecheck` plus a boot catches a malformed entry.
+//
+// USD caps price each call by its model's rate in agent/spend/model-pricing.ts. A model with no
+// rate there contributes $0, so give every model you select a rate, or set a token cap as well.
+// See docs/security/spend-and-cost.md in the Open Everywhere repository.
+
+import { defineSpendBudgets, assertSpendBudgetsValid, type SpendBudgets } from "@open-everywhere/core/agent/spend/spend.js";
+
+const budgets: SpendBudgets = defineSpendBudgets({
+  // Example — cap one Slack channel at $20 a month:
+  //   perSurface: { "slack/<team-id>/<channel-id>": { surfaceMonthlyUsd: 20 } },
+});
+
+assertSpendBudgetsValid(budgets);
+
+export function loadSpendBudgets(): SpendBudgets {
+  return budgets;
+}

package/template/agent/spend/checkpoints.ts

@@ -0,0 +1,51 @@
+// Spend checkpoints — config-as-code for the SOFT session cost control (OPE-62,
+// docs/security/spend-and-cost.md in the Open Everywhere repository). Declare per-SESSION thresholds — a token count, a
+// model-call count, and/or an estimated USD amount — per surface, per workspace, per memory
+// domain, or as a blanket default; the narrowest entry wins for a scope, and any component the
+// winning entry sets is checked.
+//
+// DISTINCT FROM budgets.ts (the HARD monthly cap): a budget REFUSES new work outright when a
+// scope is over its monthly total. A checkpoint is softer and per-session — when a single
+// conversation gets expensive it PAUSES only CONSEQUENTIAL actions (PRs, memory writes, skill/
+// routine creation, …) and posts a "keep going?" card. Reads and replies are never blocked, and a
+// member's approval lets the agent resume for the rest of that session. It's a runaway-session
+// circuit-breaker, not a spend ceiling.
+//
+// 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`
+// (assertSpendCheckpointsValid runs at import time and throws on a malformed entry — bad scope
+// keys, unknown/typo'd fields, non-positive amounts).
+//
+// The USD component prices this session's usage_events rows per-row (each row's stamped model ×
+// its verified/catalog rate — the same figure session_cost / spend_report show). A deploy whose
+// models aren't priced (agent/spend/model-pricing.ts) never trips a USD checkpoint;
+// use the token or model-call component there instead.
+
+import { defineSpendCheckpoints, assertSpendCheckpointsValid, type SpendCheckpoints } from "@open-everywhere/core/agent/spend/checkpoint.js";
+
+const checkpoints: SpendCheckpoints = defineSpendCheckpoints({
+  // --- EXAMPLE (illustrative numbers, not recommendations) ---
+  // default: {
+  //   sessionTokens: 5_000_000,       // pause consequential actions after ~5M tokens in one session
+  //   sessionModelCalls: 200,         // …or after ~200 model calls (the closest analogue to "turns")
+  // },
+  // perDomain: {
+  //   // Keyed by a memory DOMAIN name (memory/domain.ts), same resolution as budgets.ts's perDomain.
+  //   public: {
+  //     sessionUsd: 2,                // a guest/externally-shared session: confirm past ~$2
+  //   },
+  // },
+  // perSurface: {
+  //   "slack/<team-id>/<channel-id>": {  // one channel that runs big coding sessions gets a higher bar
+  //     sessionUsd: 10,
+  //   },
+  // },
+});
+
+assertSpendCheckpointsValid(checkpoints);
+
+/** The seam a DB/dashboard would swap behind. Static config for now. */
+export function loadSpendCheckpoints(): SpendCheckpoints {
+  return checkpoints;
+}

package/template/agent/spend/model-pricing.ts

@@ -0,0 +1,25 @@
+// Model pricing — this deployment's $/Mtok table. A USD spend cap (agent/spend/budgets.ts) prices
+// each call by its model's rate. A call with no rate contributes $0, so an unpriced model turns a
+// USD cap into a guard that looks armed but is empty. Give every model your stacks can select a
+// rate here. Core ships the rate of the shipped primary (`openai/gpt-6-luna`), so this file does
+// not restate it.
+//
+// Without `cachedInPerMtok`, a cached read is priced at the full input rate, which can only
+// overstate a cost. `assertModelPricingValid` runs at import.
+
+import { defineModelPricing, assertModelPricingValid, type ModelPricingTable } from "@open-everywhere/core/agent/spend/pricing.js";
+
+const pricing: ModelPricingTable = defineModelPricing({
+  // chinese-open-weights: primary, utility, supervisor and judge.
+  "deepseek/deepseek-v4-flash-0731": { inPerMtok: 0.14, outPerMtok: 0.28 },
+  // chinese-open-weights: vision.
+  "alibaba/qwen3-vl-instruct": { inPerMtok: 0.2, outPerMtok: 0.88 },
+  // american-closed: vision.
+  "google/gemini-3.7-flash": { inPerMtok: 0.75, outPerMtok: 3.75 },
+});
+
+assertModelPricingValid(pricing);
+
+export function loadModelPricing(): ModelPricingTable {
+  return pricing;
+}

package/template/agent/webhooks/hooks-overlay.ts

@@ -0,0 +1,34 @@
+// The webhook-hooks OVERLAY loader — the runtime half of the `declare_webhook` flow (OPE-208).
+// `hooks.generated.ts` (next to this file) is a MACHINE-OWNED, DATA-ONLY overlay of extra hook
+// declarations that merges into the config-as-code baseline in `hooks.ts` at load. Nothing edits it
+// by hand in the normal flow: the deterministic codemod (core `webhooks/hooks-codemod.ts`) writes it
+// on a `webhook-declare/<id>` branch, a bot-PR carries the diff, and GitHub's merge button is the
+// approval gate.
+//
+// Deliberately the same shape, the same import style and the same fail-loud posture as
+// `agent/access/grants.ts`, because it is the same flow with a different file: a static import so
+// Eve's bundler inlines the overlay into the deploy artifact (a declaration that merged is a
+// declaration that ships, rather than a file path that could be silently stripped), and STRICT
+// parsing so a malformed overlay refuses to boot rather than loading as "roughly right". Vercel keeps
+// the previous deployment live on a failed build, so the worst case is a red pipeline.
+//
+// The DATA lives in a `.ts` module rather than JSON (OPE-256) — one authoring language for the whole
+// deployer config. That matters most here of the three overlays: a hook is a STANDING UNATTENDED
+// PROMPT, so "the file cannot contain code" is worth something. A module IS executable at load, and
+// the parse below only sees the value, so this loader does not prove the file is data. In this app no
+// check before the merge does: whoever merges the codemod PR is the only gate. Review it as code.
+//
+// 🔴 IT HOLDS NO SECRETS AND CANNOT. Each entry carries `secretRef` + `broker` — a pointer and the
+// home it resolves through. Setting the VALUE is an operator's separate act (an env var, or a write
+// into the deployment's own vault), which is what keeps a webhook's shared secret out of every diff,
+// every transcript and every log.
+
+import { parseHooksFile, type HooksFile } from "@open-everywhere/core/agent/webhooks/hooks-codemod.js";
+import hooksOverlay from "./hooks.generated.js";
+
+const overlay: HooksFile = parseHooksFile(hooksOverlay);
+
+/** The parsed hooks overlay — merged into loadWebhooks() by hooks.ts. */
+export function loadHooksOverlay(): HooksFile {
+  return overlay;
+}

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

@@ -0,0 +1,17 @@
+// 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.
+//
+// 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.
+//
+// To change it by hand, edit only the data below and keep the layout exactly as emitted.
+
+import type { HooksFile } from "@open-everywhere/core/agent/webhooks/hooks-codemod.js";
+
+export default {
+  "hooks": []
+} satisfies HooksFile;

package/template/agent/webhooks/hooks.ts

@@ -0,0 +1,133 @@
+// Webhook-trigger configuration — config-as-code, the admin console for the generic
+// inbound-webhook surface (docs/capabilities/proactivity-and-routines.md in the Open Everywhere repository "Inbound
+// webhook triggers"). Declare a hook: which signature scheme its sender uses (`source`),
+// where its shared secret lives (`secretRef` + the `broker` that ref resolves through),
+// which `slack/TEAM/CHANNEL` surface it fires into, and what the agent should do when it
+// fires. Point the provider at `POST /webhooks/<id>` (channels/webhooks.ts).
+//
+// SIGNATURE SCHEME: `source` names the registered verifier. `"oe-standard-webhook"` is
+// OUR own contract — the public standard-webhooks spec (`webhook-id` + `webhook-timestamp`
+// + `webhook-signature: v1,<base64>` over `<id>.<ts>.<rawBody>`, 300s skew) — right for a
+// sender you configure (your CI, a script, a shim), and it has drop-in sender libraries in
+// most languages. A THIRD-PARTY vendor signs in its own scheme and never in ours, so a
+// vendor-fed hook names the vendor instead (`source: "github"`, `"notion"`, …) and is
+// verified exactly the way that vendor signs. The source is DECLARED, never sniffed off
+// the request; an unregistered source is a fail-closed 401 naming the registered set.
+//
+// ⚠️ `source: "oe-hmac"` WAS A SECOND OE-DEFINED SCHEME AND IS GONE (OPE-213). It carried
+// no per-delivery id, so it had no replay defence at all — a captured delivery replayed
+// successfully inside the skew window. Any hook still declaring it now 401s with the
+// registered set named; move the sender to `oe-standard-webhook`.
+//
+// SECRET CUSTODY (OPE-158): `broker: "env"` + a ref that is an env var NAME is the
+// zero-wiring floor. `broker: "db"` instead resolves the ref out of our own AES vault
+// (armed by OE_CREDENTIAL_ENCRYPTION_KEY) — the option to hold a hook's secret somewhere
+// a config diff can't reach it. `secretRef` may also be an ORDERED LIST, current key
+// first: a second entry is a rotation overlap, live until every sender has moved.
+//
+// WHO MAY READ IT (OPE-209): `readableBy` is REQUIRED on every hook and there is no default. It is
+// a list of `access/bundle.ts` `Scope`s — `{ level: "domain", domain: "payments" }` names one domain,
+// several entries are a UNION (many domains may legitimately read one hook), and `{ level: "org" }`
+// means EVERY domain in the org. It is the ENTIRE confidentiality decision for this ingress: what a
+// subscribing routine then ACTS on is that routine's own filter, and anything finer-grained than
+// `readableBy` is a second webhook, not a cleverer grant. There is deliberately no way to omit it —
+// an implicit default is how a hook came to be created readable by nobody, accepting deliveries and
+// refusing every routine forever in silence (OPE-206).
+//
+// HOW MUCH OF THE PAYLOAD REACHES THE MODEL (OPE-214): `posture` is one axis with three points —
+// `"trigger-only"` (nothing the sender wrote reaches the prompt; the instruction runs on the FACT
+// that it fired), `"projection"` (only the field keys listed in `project`, and no entity is
+// refetched), `"content-bearing"` (the entire raw body, as untrusted data, on every delivery,
+// forever). OMITTING IT MEANS `content-bearing`, which is exactly what every config hook did before
+// the field existed — so this was not a behaviour change for anything already deployed. Declare it
+// explicitly on anything new; reach for `"projection"` whenever the instruction needs two fields
+// rather than the whole body. Both of a hook's consequences take the same posture: its own declared
+// fire AND its emission into the event plane, so a hook cannot disclose less where it was declared
+// than in the rooms that subscribed to it. A `content-bearing` or `projection` fire is TAINTED (its
+// prompt carries an outside party's bytes); a `trigger-only` one is not.
+//
+// EMPTY BY DEFAULT — with nothing declared here, every webhook id 404s. This file is
+// the seam a DB/dashboard would swap behind, same as memory/config/domains.ts and access/
+// bundles.ts. After adding a hook: `npm run typecheck` plus a boot (assertWebhooksValid runs
+// at import time and throws on a malformed entry — id collisions, a missing source, a
+// blank/empty secretRef, a missing broker, a target that isn't a well-formed
+// slack/TEAM/CHANNEL triple).
+
+import { defineWebhook, assertWebhooksValid, type WebhookHook } from "@open-everywhere/core/agent/webhooks/config.js";
+import { loadHooksOverlay } from "./hooks-overlay.js";
+import { loadDomains } from "../memory/config/domains.js";
+
+const hooks: WebhookHook[] = [
+  // --- EXAMPLE: a CI pipeline posts a deploy-status summary into a Slack channel ---
+  // defineWebhook({
+  //   id: "deploy-status",                        // POST /webhooks/deploy-status
+  //   source: "oe-standard-webhook",               // OUR contract — a sender you control signs it
+  //   secretRef: "DEPLOY_STATUS_WEBHOOK_SECRET",   // shared secret REF (env var NAME here, not the value)
+  //   broker: "env",                               // the home that ref resolves through ("env" | "db" | ...)
+  //   target: "slack/<team-id>/<channel-id>",         // fully-qualified slack/TEAM/CHANNEL surface
+  //   readableBy: [{ level: "domain", domain: "engineering" }],  // WHO may read its events — REQUIRED, no default
+  //   posture: "projection",                       // HOW MUCH of the payload reaches the model
+  //   project: ["status", "branch"],               // …under "projection": exactly these normalizer field keys
+  //   instruction:
+  //     "A CI deploy-status webhook just fired. Summarise the result for the channel " +
+  //     "in one or two lines; only @-mention the channel if the deploy FAILED.",
+  // }),
+  // --- EXAMPLE: a THIRD-PARTY vendor's webhook, verified in THAT VENDOR's scheme ---
+  // The point of the verifier registry: GitHub signs `X-Hub-Signature-256` and will never
+  // adopt ours, so the hook names GitHub's source and the secret is the one GITHUB minted
+  // when the webhook was created. (Needs the github provider bundle selected — a
+  // de-selected bundle registers no verifier and the hook then 401s, fail-closed.)
+  // defineWebhook({
+  //   id: "gh-deploys",                            // POST /webhooks/gh-deploys
+  //   source: "github",                            // verified as GitHub signs, not as we do
+  //   secretRef: "GH_DEPLOYS_WEBHOOK_SECRET",       // the secret you pasted into GitHub's webhook form
+  //   broker: "env",
+  //   ...
+  // }),
+  // --- EXAMPLE: the SAME hook mid key-rotation, and one whose secret lives in the db vault ---
+  // defineWebhook({
+  //   id: "deploy-status",
+  //   source: "oe-standard-webhook",
+  //   secretRef: ["DEPLOY_STATUS_WEBHOOK_SECRET_V2", "DEPLOY_STATUS_WEBHOOK_SECRET"], // CURRENT FIRST
+  //   broker: "env",                               // ONE home for the whole hook — a rotation never moves custody
+  //   ...
+  // }),
+  // defineWebhook({
+  //   id: "deploy-status",
+  //   source: "oe-standard-webhook",
+  //   secretRef: "deploy-status-hook",             // a stored-credential ref, not an env var
+  //   broker: "db",                                // our own AES vault (needs OE_CREDENTIAL_ENCRYPTION_KEY armed)
+  //   ...
+  // }),
+];
+
+// --- The hooks OVERLAY (declare_webhook flow, OPE-208) -----------------------
+// `agent/webhooks/hooks.generated.ts` is a MACHINE-OWNED, DATA-ONLY overlay of extra declarations that a bot-PR adds and an
+// admin merges (see hooks-overlay.ts). It merges here, and the MERGED list is what
+// `assertWebhooksValid` checks — so a bad overlay (duplicate id, missing readableBy, a target that
+// isn't a well-formed surface) is a fail-loud boot error rather than something that half-loads.
+// Exactly the shape `access/bundles.ts` uses for the grants overlay, for the same reasons.
+const merged: WebhookHook[] = [...hooks, ...loadHooksOverlay().hooks];
+
+// ⭐ THE DOMAIN REGISTRY IS PASSED IN (OPE-215), which is what turns the validator from a SHAPE check
+// into an ACHIEVABILITY check: a grant naming a domain this deployment does not declare is refused
+// here rather than accepted and then silently refusing every routine forever, and a hook whose own
+// target channel is in no domain (or in one the grant does not name) warns in the boot log.
+//
+// A DIRECT IMPORT, NOT `getConfig()`. This file runs at module import, before the app-config seam is
+// necessarily armed; `memory/config/domains.ts` is a sibling static registry with no such ordering hazard.
+// The parameter is optional and the sweep is INERT without it — a deployment that cannot supply the
+// registry gets exactly the pre-OPE-215 validation rather than a boot failure.
+assertWebhooksValid(merged, { domains: loadDomains() });
+
+/** The seam a DB/dashboard would swap behind. Currently static config + the declaration overlay. */
+export function loadWebhooks(): readonly WebhookHook[] {
+  return merged;
+}
+
+/** The CODE-ONLY baseline (overlay EXCLUDED) — what `approvals/webhook-declare.ts` merges a
+ *  CANDIDATE overlay into for pre-PR re-validation, and what tells the codemod which ids a chat
+ *  declaration must not collide with. Not for the route, which uses the merged list above. */
+export function loadBaseWebhooks(): readonly WebhookHook[] {
+  return hooks;
+}

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

@@ -0,0 +1,167 @@
+---
+name: quickstart-open-everywhere
+description: Set up, configure or deploy an Open Everywhere app — from a fresh scaffold to an agent that answers in Slack. Use when the user wants to set up Open Everywhere, deploy it, or connect Slack, Notion or GitHub. Two routes are supported, Vercel and Docker, and step 1 is to ask which. Drives the open-everywhere-ops MCP server (preflight, surface_manifest, scaffold_env, scaffold_credential_key, secret_set/list/rm) and the `@open-everywhere/create --check --json` status report.
+---
+
+# Quickstart Open Everywhere
+
+This directory is an **Open Everywhere app** — either a scaffolded app (it depends on the
+`@open-everywhere/*` npm packages and holds only configuration) or a clone of the Open Everywhere
+repository, which contains those packages and is itself an app. `AGENTS.md` describes which one you
+are in. Its `.mcp.json` gives you the `open-everywhere-ops` MCP server. You supply the judgement,
+and you run commands **with the user's consent**.
+
+🔴 **Two commands differ between the two homes.** In a scaffolded app, run
+`npx @open-everywhere/create --check --json` and `npm run -s env:pipe`. In a clone of the
+repository, run `node packages/create/bin/create-open-everywhere.js --check --json` (the checkout's
+own CLI, not the published one) and use the `grep`/`cut` form of the env push given in step 9 —
+that repository ships no `env:pipe` script. Everything else is the same.
+
+## Golden rules
+
+- The ops MCP tools check and scaffold. **You** run install, build and deploy commands in the
+  user's shell: show the command, get a yes, then run it. Never run a deploy, create a cloud
+  resource, or write a secret without explicit confirmation.
+- **Never ask the user to paste a secret into the chat, and never echo or commit one.** They paste
+  it where a tool reads it; you write it to the gitignored `.env.local` with `scaffold_env`, then
+  forget it. Mint the credential-store key with `scaffold_credential_key`, which never prints it.
+- **Never propose a local run as a setup step.** `npm run dev` is the development loop AFTER the
+  deploy. A local run has no public HTTPS URL for Slack to reach and keeps its state in a different
+  store, so it proves little about the deployment. See "Develop locally" below.
+- **Where each secret lives.** The deployment reads `DATABASE_URL`,
+  `OE_CREDENTIAL_ENCRYPTION_KEY`, `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET` and
+  `GITHUB_WEBHOOK_SECRET` from its **environment**: the Slack bundle and the GitHub webhook check
+  never read the credential store. So these go in `.env.local`, and then into the deployment's own
+  environment. `secret_set` is for a credential whose `broker` is `"db"` (and
+  `NOTION_WEBHOOK_SECRET`). It needs `DATABASE_URL` and the key in `.env.local` first. Nothing
+  reads a stored secret back out (`secret_list` returns names only).
+- Every command runs from the app root.
+
+## Step 1 — ask which route
+
+**Two routes are supported. Ask the user to pick one before anything else.**
+
+- **Vercel** — on rails: the `vercel` CLI plus Marketplace Neon. The deployment authenticates to
+  the AI Gateway with OIDC, so it needs no gateway key.
+- **Docker** — self-host a container that satisfies the **deployment contract**
+  (`https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/contract.md`). Off
+  Vercel there is no OIDC, so the model route needs `AI_GATEWAY_API_KEY`. Running a different model
+  backend instead is an adapter swap in app code, not an env setting
+  (`https://github.com/open-everywhere/open-everywhere/blob/main/docs/extending/adapter-model.md`),
+  and `--check` cannot see it.
+
+Nothing beyond these two is supported. For any other host, read the contract and follow the Docker
+route; do not invent a recipe.
+
+## Status, at every step
+
+- `npx @open-everywhere/create --check --json` — the step list as data: `satisfied`, `detail`, and a
+  `next` command per unsatisfied step. It changes nothing. Pass `--route docker` on the Docker
+  route, and `--host https://<host>` once a deployment exists. In a clone of the repository, run
+  `node packages/create/bin/create-open-everywhere.js --check --json` instead.
+- The `preflight` tool — the env verdict per name. Pass `target: "vercel"` or `target: "docker"`.
+
+Re-run both after each step. They are the only answer to "what is left to do": there is no plan
+tool. The same step list, written for a human, is
+`https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/setup-steps.md`.
+
+## The Vercel route
+
+1. **Install.** If `node_modules` is missing: `npm install`. Its `postinstall` runs `oe-eve-patch`,
+   which patches the installed `eve`. The app refuses to boot without the patch.
+2. **Link.** `npx vercel link` (interactive: the user signs in). Every later `vercel` command acts
+   on the linked project.
+3. **Database.** `npx vercel install neon` provisions a Neon database and connects it to the linked
+   project, which sets `DATABASE_URL` there. (`vercel install` is an alias of
+   `vercel integration add`; the Marketplace slug is `neon`.) The dashboard path — project →
+   **Storage → Neon → Connect** — does the same thing. Then get the same value into `.env.local`
+   for the operator tools, either with `npx vercel env pull` (it writes the project's environment
+   into `.env.local`, overwriting it, so pull before you add anything local) or by asking the user
+   for the connection string and writing it with `scaffold_env`. **That one value is the whole
+   step:** it resolves both the operational store and the memory backing to postgres on its own, so
+   set no provider selector. A selector pointing AWAY from postgres is the only thing that breaks
+   it.
+4. **Key.** `scaffold_credential_key`.
+5. **Slack app.** Call `surface_manifest { surface: "slack" }` and hand the user the manifest and
+   the steps it returns. Before the first deploy the manifest keeps `YOUR-DEPLOY-URL`. The user
+   creates and installs the app, then pastes `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET`: write
+   both with `scaffold_env`.
+6. **Vouch the workspace.** Ask for the team id (`T…`: the segment after `/client/` in the
+   workspace URL at app.slack.com). In `agent/identity/surfaces.ts` add
+   `defineSurface({ key: "slack/<team-id>", trust: "internal" })`.
+7. **Admin.** Ask for the user's member id (`U…`: Slack profile → ⋮ More → Copy member ID). In
+   `agent/memory/config/domains/org.ts` set `admins: ["slack/<team-id>/<member-id>"]`. Offer to
+   commit both edits. They take effect on the next deploy, so make them before it.
+8. **Build.** `npm run build`. It must pass.
+9. **Deployment env.** `.env.local` never ships, so the deployment reads only what you set ON it.
+   The names are `OE_CREDENTIAL_ENCRYPTION_KEY`, `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET`. The
+   Neon integration already set `DATABASE_URL` there, and that one value resolves both stores — so
+   there is no `OE_OPERATIONAL_PROVIDER` or `OE_MEMORY_PROVIDER` to push.
+   Confirm each command first, and **never let a value reach your own output.**
+   - **In a scaffolded app:** `npm run -s env:pipe -- <NAME> | npx vercel env add <NAME> production`.
+     Always pipe `env:pipe` straight into `vercel env add`, as written. Never run it bare: your
+     shell is never a terminal, so a bare run prints the secret into your output. `env:pipe`
+     refuses a file or a terminal, but it cannot tell a pipe into your own shell from a pipe into
+     `vercel`.
+   - **In a clone of the repository** (it ships no `env:pipe`):
+     `grep "^<NAME>=" .env.local | cut -d= -f2- | tr -d '\n' | npx vercel env add <NAME> production`.
+     Same rule: the value only ever crosses a pipe.
+   Do not push `AI_GATEWAY_API_KEY` (OIDC covers it), `OE_PUBLIC_BASE_URL` (only for a custom
+   domain) or `OE_INTAKE_PAGE_SIGNING_KEY` (the deployment mints it). A variable added after a
+   deploy reaches the functions only on the NEXT deploy.
+10. **Deploy.** `npx vercel deploy --prod` (confirm first). Note the production host it prints. A
+    `git push` does NOT deploy.
+11. **Slack URLs.** Call `surface_manifest { surface: "slack", baseUrl: "https://<host>" }`. The
+    user pastes it under the Slack app's **App Manifest** and saves. Slack verifies the Event
+    Subscriptions URL. If it fails, the user chooses **Retry** under Event Subscriptions.
+12. **Prove it.** `npx @open-everywhere/create --check --json --host https://<host>`. The
+    `build-deploy` step is satisfied only when the deployed Slack route answers an unsigned request
+    with its own `401 unauthorized`. That proves boot and routing, not `SLACK_SIGNING_SECRET`: ask
+    the user to confirm Event Subscriptions shows **Verified**.
+13. **Hello.** Ask the user to send the app a direct message in Slack.
+
+## The Docker route
+
+Read the deployment contract first: it states what a running Open Everywhere needs — Node 24, a
+public HTTPS URL, Postgres, a sandbox backend, egress control, a model route, and the secrets list.
+Then:
+
+1. **Install and build.** `npm install`, then `npm run build`.
+2. **Postgres.** Provision one the container can reach, and `scaffold_env` its `DATABASE_URL`. That
+   one value resolves both stores to postgres; set no provider selector.
+3. **Key.** `scaffold_credential_key`.
+4. **Model route.** There is no OIDC off Vercel, so the user supplies `AI_GATEWAY_API_KEY` (Vercel
+   → AI Gateway → API Keys issues one for any host). Running a different model backend instead is
+   an **adapter swap in app code**
+   (`https://github.com/open-everywhere/open-everywhere/blob/main/docs/extending/adapter-model.md`),
+   which `--check` cannot see: that step stays `missing` on the Docker route either way, so read it
+   and move on rather than chasing a green it cannot give.
+5. **Slack app.** Exactly as steps 5–7 of the Vercel route.
+6. **Run it.** Build the image and run it on the server, with the contract's environment set and a
+   public HTTPS URL in front. The Open Everywhere repository's own `Dockerfile` and
+   `docker-compose.yml` are the starting point
+   (`https://github.com/open-everywhere/open-everywhere`); a scaffolded app ships neither, so copy
+   them from there.
+7. **Prove it, then the Slack URLs and the hello.** As steps 11–13 of the Vercel route, with
+   `--route docker --host https://<host>`.
+
+## Develop locally
+
+Only when the user asks to change or debug the agent — never as a setup step. Write
+`AI_GATEWAY_API_KEY` with `scaffold_env` (the user creates it: Vercel → AI Gateway → API Keys),
+then `npm run dev`. A local run keeps its state in an embedded database under
+`.open-everywhere-data/`, and Slack cannot reach it without a public tunnel.
+
+## Notes
+
+- `roster.config.ts` decides what the agent can do. After any change to it, or after a package
+  upgrade, run `npx oe build --accept` and show the user the `roster.lock.json` diff: accepting it
+  is their review decision.
+- `.env.example` names every variable this app reads. Read it when unsure what a key does.
+- The deployment's own identity (`deploymentIdentity`) is code in `agent/identity/surfaces.ts`, not
+  env.
+- `@open-everywhere/create` has no interactive wizard and sends no telemetry. It scaffolds
+  (`npx @open-everywhere/create <dir>`) and reports status (`--check`). Nothing else.
+- 🔴 **`--check` reads `.env.local` and your shell, never the deployment's own environment.** A
+  "9/9 satisfied" is not proof that the deployment holds the credential key or the Slack secrets:
+  step 9 is the only thing that puts them there, and nothing can observe it from here.