@open-everywhere/create 0.1.4

package/src/deploy-probe.ts

@@ -0,0 +1,99 @@
+// The deploy probe — the one deployment fact the setup check can observe without credentials.
+//
+// It sends an unsigned POST to the deployment's Slack route. The Slack bundle answers an unsigned
+// body with exactly `401 unauthorized` (slack-front.ts), and it can do so only when the function
+// booted and the route is mounted. So:
+//   • 401 with that body  → the function is up and refuses unsigned input: satisfied;
+//   • 401/403 with another body → something in FRONT of the function answered (Vercel Deployment
+//     Protection is the usual one) — Slack is blocked too, so this is NOT satisfied;
+//   • 404 → the route is not on this deployment;  5xx → the function failed;  no answer → unreachable.
+// A 5xx or no answer gets ONE retry with a longer timeout, because the first request to a fresh
+// deployment boots the function (see probeDeployment).
+// It proves boot and routing. It does not prove that the deployment holds SLACK_SIGNING_SECRET: the
+// route answers an unsigned body with the same 401 when the secret is unset. Slack's own Event
+// Subscriptions "Verified" is the check that proves the secret. It does not prove the stores or the
+// model either.
+
+/** The route the probe posts to. The quickstart app mounts Slack. */
+export const DEPLOY_PROBE_PATH = "/eve/v1/slack";
+
+export interface ProbeResult {
+  readonly ok: boolean;
+  readonly detail: string;
+}
+
+/** Normalise `--host` to an origin: scheme optional, path and trailing slash dropped. */
+export function normalizeHost(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (trimmed === "") return undefined;
+  try {
+    const url = new URL(/^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`);
+    return url.origin;
+  } catch {
+    return undefined;
+  }
+}
+
+/** One attempt's verdict. `retry` marks a failure a cold function can cause: no answer, or a 5xx. */
+interface Attempt extends ProbeResult {
+  readonly retry: boolean;
+  /** The outcome in a few words, for the cold-start note. */
+  readonly brief: string;
+}
+
+async function probeOnce(url: string, fetchImpl: typeof fetch, timeoutMs: number): Promise<Attempt> {
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(timeoutMs),
+      redirect: "manual",
+    });
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return { ok: false, retry: true, brief: `no answer within ${timeoutMs / 1000}s`, detail: `${url} did not answer (${why})` };
+  }
+  const body = (await res.text().catch(() => "")).trim();
+  if (res.status === 401 && body === "unauthorized") {
+    return {
+      ok: true,
+      retry: false,
+      brief: "401 unauthorized",
+      detail: `${url} answered 401 unauthorized to an unsigned request: the function booted and the Slack route is mounted. This does NOT prove the deployment holds SLACK_SIGNING_SECRET (the route answers the same without it). Slack proves that: Event Subscriptions shows the request URL as Verified`,
+    };
+  }
+  const fail = (detail: string, retry = false): Attempt => ({ ok: false, retry, brief: `${res.status}`, detail });
+  if (res.status === 401 || res.status === 403) {
+    return fail(
+      `${url} answered ${res.status}, but not from the Slack route — Vercel Deployment Protection (or a proxy) blocks it, and it blocks Slack too. Vercel project → Settings → Deployment Protection`,
+    );
+  }
+  if (res.status === 404) return fail(`${url} answered 404: the Slack route is not on this deployment (wrong host, or the roster does not mount Slack)`);
+  if (res.status >= 500) return fail(`${url} answered ${res.status}: the function failed — read the deployment's logs (\`npx vercel logs <host>\`)`, true);
+  return fail(`${url} answered ${res.status}: expected 401 to an unsigned request`);
+}
+
+/**
+ * Probe the deployment's Slack route, with ONE retry for a cold start.
+ *
+ * The first request to a fresh deployment boots the function. That boot can outlast the first
+ * timeout, or answer 5xx, and a practice install met both (OPE-2222). So a timeout, a network
+ * error or a 5xx gets one more attempt with the longer `retryTimeoutMs`. A pass on the retry says
+ * "cold start", so the operator knows the first failure was the boot. A non-Slack 401/403, a 404 or
+ * any other status is never retried: a second request cannot change it.
+ */
+export async function probeDeployment(
+  origin: string,
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = 10_000,
+  retryTimeoutMs = 30_000,
+): Promise<ProbeResult> {
+  const url = `${origin}${DEPLOY_PROBE_PATH}`;
+  const first = await probeOnce(url, fetchImpl, timeoutMs);
+  if (first.ok || !first.retry) return { ok: first.ok, detail: first.detail };
+  const second = await probeOnce(url, fetchImpl, retryTimeoutMs);
+  if (second.ok) return { ok: true, detail: `cold start: the first request got ${first.brief}, and the retry passed. ${second.detail}` };
+  return { ok: false, detail: `${second.detail} (after one retry; the first request got ${first.brief})` };
+}

package/src/engine.ts

@@ -0,0 +1,106 @@
+// The setup engine — ONE step-driven checklist that the `@open-everywhere/create` CLI's `--check`
+// mode reports, the `quickstart-open-everywhere` skill reads, and `scripts/setup-steps-docs.ts`
+// renders into the human reference page (docs/deploy/setup-steps.md). A step is data:
+// { id, title, check(), guide() } — see `SetupStep` below. This module owns the TYPES and the
+// ORCHESTRATOR only; it never touches stdin/stdout, so a test drives it exactly as the CLI does.
+//
+// 🔴 THERE IS NO INTERACTIVE WIZARD (OPE-2233). The TTY wizard, its `WizardIO` prompt surface and
+// every step's `automate()` are retired: setup is AGENT-LED. The agent reads this engine's report
+// and runs the commands with the user's consent, and the ops MCP server's `scaffold_env` /
+// `scaffold_credential_key` tools do the writes a step's `automate()` used to do. So this engine
+// is READ-ONLY by construction: `check()` inspects, `guide()` describes, and nothing writes.
+//
+// Resumability is structural, not a bookkeeping flag: `check()` inspects the REAL WORLD (env vars,
+// files, `.vercel/project.json`, node version), so a re-run after a stop picks up exactly where it
+// left off — a step is only "already done" because the thing it checks for is actually true.
+
+/**
+ * The deployment route the steps judge against. TWO routes are supported, and the user picks one
+ * FIRST (OPE-2228): `vercel` (on rails — the Vercel CLI plus Marketplace Neon) and `docker`
+ * (self-host against the deployment contract, docs/deploy/contract.md). Nothing else is supported,
+ * and a local run is NEVER a route: `npm run dev` is the development loop AFTER a deploy, because
+ * a local success proves nothing about a deployment (no public HTTPS URL for a chat vendor to
+ * reach, and a different store).
+ */
+export type SetupRoute = "vercel" | "docker";
+
+/** Every supported route, in the order the setup guidance offers them. */
+export const SETUP_ROUTES: readonly SetupRoute[] = ["vercel", "docker"];
+
+/** Is this string one of the two supported routes? */
+export function isSetupRoute(value: string): value is SetupRoute {
+  return (SETUP_ROUTES as readonly string[]).includes(value);
+}
+
+export interface StepContext {
+  /** Directory the check is running in (the target project checkout). */
+  readonly cwd: string;
+  /** Process env — a param (not a bare `process.env` read) so tests can inject one. */
+  readonly env: NodeJS.ProcessEnv;
+  /** The route the steps judge against. Absent means `vercel`. */
+  readonly route?: SetupRoute;
+  /** The deployment's public origin (`--host`), for the deploy probe. */
+  readonly host?: string;
+  /** The chat app's name (`--app-name`), for the Slack manifest. Absent means the default name. */
+  readonly appName?: string;
+}
+
+/** The route a context judges against. */
+export function routeOf(ctx: StepContext): SetupRoute {
+  return ctx.route ?? "vercel";
+}
+
+export interface StepCheckResult {
+  readonly satisfied: boolean;
+  /** One line, human-readable — NEVER a secret value (see AGENTS.md security rules). */
+  readonly detail: string;
+  /** The command (or the one action) that moves an unsatisfied step forward. */
+  readonly next?: string;
+}
+
+export interface StepGuide {
+  readonly summary: string;
+  readonly instructions: readonly string[];
+}
+
+export interface SetupStep {
+  readonly id: string;
+  readonly title: string;
+  check(ctx: StepContext): Promise<StepCheckResult> | StepCheckResult;
+  guide(ctx: StepContext): StepGuide;
+}
+
+export interface StepRunResult {
+  readonly step: SetupStep;
+  readonly check: StepCheckResult;
+}
+
+export interface SetupCheckSummary {
+  readonly results: readonly StepRunResult[];
+  readonly satisfiedCount: number;
+  readonly total: number;
+  readonly allSatisfied: boolean;
+}
+
+/**
+ * The status report — no prompts, no automation, no side effects. This is what `--check` mode (and
+ * the skill, through it) calls: run every step's `check()` and report satisfied/unsatisfied. Safe
+ * to call as often as you like.
+ *
+ * Never throws: a step whose `check()` rejects is reported as unsatisfied rather than aborting the
+ * whole run, so one bad step cannot hide the rest of the checklist.
+ */
+export async function checkAll(steps: readonly SetupStep[], ctx: StepContext): Promise<SetupCheckSummary> {
+  const results: StepRunResult[] = [];
+  for (const step of steps) {
+    let check: StepCheckResult;
+    try {
+      check = await step.check(ctx);
+    } catch (err) {
+      check = { satisfied: false, detail: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    results.push({ step, check });
+  }
+  const satisfiedCount = results.filter((r) => r.check.satisfied).length;
+  return { results, satisfiedCount, total: steps.length, allSatisfied: satisfiedCount === steps.length };
+}

package/src/env-file.ts

@@ -0,0 +1,53 @@
+// Thin .env.local helpers for the setup steps' `check()`s.
+//
+// 🔴 READ-ONLY SINCE OPE-2233. This module used to carry `writeEnvLocal`, which the wizard's
+// `automate()` steps called. Setup is agent-led now, and the ONE door that writes `.env.local` is
+// the ops MCP server's `scaffold_env` tool — which gates the target filename, so a value can never
+// land in a tracked file (agent/ops/server.ts § envTargetRefusal). A second writer here would be a
+// second gate to keep right.
+//
+// SECURITY: nothing here ever returns a secret VALUE to a caller for printing — `mergedEnv` and
+// `isSet` are presence checks only. See AGENTS.md's "never log secrets" rule.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SetupRoute } from "./engine.js";
+
+export function envLocalPath(cwd: string): string {
+  return join(cwd, ".env.local");
+}
+
+function readEnvLocal(cwd: string): Record<string, string> {
+  const p = envLocalPath(cwd);
+  if (!existsSync(p)) return {};
+  const text = readFileSync(p, "utf8");
+  const out: Record<string, string> = {};
+  for (const line of text.split("\n")) {
+    const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+/** Merged view: `.env.local` overlaid with `process.env` (a shell-exported var
+ *  wins over the file — mirrors how a real boot resolves config), so `check()`
+ *  reflects what actually happens at runtime, not just what's on disk. */
+export function mergedEnv(cwd: string, processEnv: NodeJS.ProcessEnv): Record<string, string | undefined> {
+  return { ...readEnvLocal(cwd), ...processEnv };
+}
+
+export function isSet(v: string | undefined): boolean {
+  return v !== undefined && v.trim() !== "";
+}
+
+/**
+ * What a "missing" detail adds (OPE-2222). `--check` reads `.env.local` and the shell, and NEVER
+ * the deployment's own environment. Setting a value on the deployment instead is a normal thing to
+ * do, so a miss here can be a value the deployment already holds. The check does not call a vendor
+ * CLI to find out: that needs a login and a network round trip.
+ */
+export function missNote(route: SetupRoute): string {
+  const where = route === "docker" ? "the container's environment" : "the Vercel project";
+  const list = route === "docker" ? "`docker inspect` lists the names there" : "`npx vercel env ls production` lists the names there";
+  return `Did you set these on ${where} instead? Then ignore this miss: the check reads only .env.local and this shell, never the deployment's own env (${list})`;
+}

package/src/scaffold.ts

@@ -0,0 +1,188 @@
+// THE SCAFFOLD — `npx @open-everywhere/create <dir>` copies the quickstart app (this package's
+// `template/` directory) into a new or empty `<dir>`, and then prints the next steps.
+//
+// The template is a minimal npm-consumer app: the eight `@open-everywhere/*` libraries and `eve`,
+// a roster of the launch surfaces (Slack, Notion, GitHub), and the agent config. Every
+// `@open-everywhere/*` dependency, `@open-everywhere/create` itself, and the versions in
+// `roster.lock.json` carry the {@link VERSION_PLACEHOLDER}. The scaffold replaces it with this
+// CLI's own version: all nine packages publish in lockstep, so this CLI's version IS the version
+// of every library it installs.
+//
+// THREE PACKING RULES SHAPE THE TEMPLATE:
+//   • npm never packs a file named `.gitignore`. The template carries it as `gitignore`, and the
+//     scaffold renames it.
+//   • The publish preview refuses any `.claude/` path in a tarball (rule `harness-tree`, which
+//     guards every package). The template carries the app's Claude Code skill under `claude/`, and
+//     the scaffold renames the directory to `.claude/`.
+//   • The scaffold refuses a directory that holds anything. It never merges into, or overwrites,
+//     existing files.
+//
+// This module imports nothing from core. The scaffold must run before anything is installed, and
+// the boot-free test (scripts/boot-free-test.ts) holds every `src/` file to that.
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { EOL } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+/** Replaced by this CLI's own version in every template file that carries it. */
+export const VERSION_PLACEHOLDER = "{{OE_VERSION}}";
+
+/** Replaced by the npm package name derived from the target directory's name. */
+export const NAME_PLACEHOLDER = "{{APP_NAME}}";
+
+/**
+ * Template paths stored under another name because the tarball may not carry the real one, renamed
+ * on copy. Keys are template-relative paths, values are the scaffolded paths. A key that ends in `/`
+ * renames a whole directory.
+ */
+export const RENAMED_ON_COPY: Readonly<Record<string, string>> = { gitignore: ".gitignore", "claude/": ".claude/" };
+
+/** The scaffolded path of one template file. */
+export function scaffoldPathFor(rel: string): string {
+  const exact = RENAMED_ON_COPY[rel];
+  if (exact !== undefined) return exact;
+  for (const [from, to] of Object.entries(RENAMED_ON_COPY)) {
+    if (from.endsWith("/") && rel.startsWith(from)) return to + rel.slice(from.length);
+  }
+  return rel;
+}
+
+/** The `.gitignore` lines the Vercel CLI appends when the file lacks them, exactly as it writes
+ *  them: `vercel link` adds `.vercel`, and `vercel env pull` (which `vercel link` can run) adds
+ *  `.env*`. The template carries both, so the CLI finds them and changes nothing. */
+export const VERCEL_GITIGNORE_LINES: readonly string[] = [".vercel", ".env*"];
+
+/** `text` with every line ending replaced by `eol`. */
+export function withGitignoreEol(text: string, eol: string): string {
+  return text.replace(/\r?\n/g, eol);
+}
+
+/** The template that ships inside this package. */
+export function defaultTemplateDir(): string {
+  return fileURLToPath(new URL("../template/", import.meta.url));
+}
+
+/** An npm-valid package name from a directory name: lower case, `[a-z0-9._-]`, no leading `.`/`_`. */
+export function packageNameFor(dir: string): string {
+  const cleaned = basename(resolve(dir))
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[._-]+/, "")
+    .replace(/-+$/, "");
+  return cleaned.length > 0 ? cleaned.slice(0, 214) : "open-everywhere-app";
+}
+
+export class ScaffoldRefusal extends Error {}
+
+export interface ScaffoldResult {
+  /** The absolute path of the scaffolded app. */
+  readonly dir: string;
+  /** Every file written, relative to `dir`, with `/` separators, sorted. */
+  readonly files: readonly string[];
+}
+
+/** Every file under `root`, relative to it, with `/` separators. */
+export function listFiles(root: string, at = root): string[] {
+  return readdirSync(at).flatMap((name) => {
+    const p = join(at, name);
+    return statSync(p).isDirectory() ? listFiles(root, p) : [relative(root, p).split("\\").join("/")];
+  });
+}
+
+/**
+ * Does this directory count as empty for a scaffold? A directory that holds only `.git` counts:
+ * that is a fresh clone of an empty repository, so `npx @open-everywhere/create .` works inside one.
+ */
+export function isScaffoldableDir(dir: string): boolean {
+  return readdirSync(dir).every((name) => name === ".git");
+}
+
+/**
+ * Copy the template into `targetDir`. Creates the directory when it is absent. Throws a
+ * {@link ScaffoldRefusal} when it exists and is not an empty directory. A directory that holds only
+ * `.git` counts as empty (see {@link isScaffoldableDir}).
+ */
+export function scaffoldApp(options: {
+  readonly targetDir: string;
+  readonly version: string;
+  readonly templateDir?: string;
+  /** The line ending the app's `.gitignore` gets. Default: this platform's `os.EOL`. */
+  readonly eol?: string;
+}): ScaffoldResult {
+  const dir = resolve(options.targetDir);
+  const templateDir = options.templateDir ?? defaultTemplateDir();
+  // `0.0.0` is src/version.ts's fallback when it cannot read this package's own manifest. No release
+  // carries it, so pinning it would only fail the app's first `npm install`.
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(options.version) || options.version === "0.0.0") {
+    throw new ScaffoldRefusal(`refusing to scaffold: "${options.version}" is not a release version, so the app's dependencies could not be pinned`);
+  }
+  if (!existsSync(join(templateDir, "package.json"))) {
+    throw new ScaffoldRefusal(`refusing to scaffold: the quickstart template is missing from this package (${templateDir})`);
+  }
+  if (existsSync(dir)) {
+    if (!statSync(dir).isDirectory()) throw new ScaffoldRefusal(`refusing to scaffold: ${dir} exists and is not a directory`);
+    if (!isScaffoldableDir(dir)) {
+      throw new ScaffoldRefusal(`refusing to scaffold: ${dir} is not empty — choose a new directory name, or empty this one first`);
+    }
+  }
+  mkdirSync(dir, { recursive: true });
+
+  const name = packageNameFor(dir);
+  const written: string[] = [];
+  for (const rel of listFiles(templateDir)) {
+    const out = scaffoldPathFor(rel);
+    const target = join(dir, ...out.split("/"));
+    mkdirSync(join(target, ".."), { recursive: true });
+    const source = join(templateDir, ...rel.split("/"));
+    const bytes = readFileSync(source);
+    const text = bytes.toString("utf8");
+    if (out === ".gitignore") {
+      // 🔴 THE PLATFORM'S LINE ENDING, SO `vercel link` LEAVES THE FILE ALONE (OPE-2222). The
+      // Vercel CLI appends `.vercel` (on link) and `.env*` (on env pull) unless the file already
+      // holds that exact line. It splits the file on `\r\n` when the file holds one, and on
+      // `os.EOL` otherwise. On Windows `os.EOL` is `\r\n`, so an LF-only file reads as ONE line,
+      // and the CLI appends lines the template already carries. See withGitignoreEol.
+      writeFileSync(target, withGitignoreEol(text, options.eol ?? EOL));
+    } else if (text.includes(VERSION_PLACEHOLDER) || text.includes(NAME_PLACEHOLDER)) {
+      writeFileSync(target, text.split(VERSION_PLACEHOLDER).join(options.version).split(NAME_PLACEHOLDER).join(name));
+    } else {
+      copyFileSync(source, target);
+    }
+    written.push(out);
+  }
+  return { dir, files: written.sort() };
+}
+
+/** What {@link initGitRepo} did, and why. */
+export interface GitInitResult {
+  readonly initialized: boolean;
+  readonly detail: string;
+}
+
+/** Run git with argv, never a shell. Returns `undefined` when git cannot be spawned at all. */
+export type GitRunner = (args: readonly string[], cwd: string) => { readonly status: number | null } | undefined;
+
+const realGit: GitRunner = (args, cwd) => {
+  const r = spawnSync("git", [...args], { cwd, stdio: "ignore" });
+  return r.error !== undefined ? undefined : { status: r.status };
+};
+
+/**
+ * Make the scaffolded app its own git repository. The app's files are its configuration, and every
+ * change to `roster.config.ts` and `roster.lock.json` is a review decision, so the history starts at
+ * the scaffold. It skips, and says why, when git is absent or the directory is already inside a
+ * work tree (a monorepo, for one): a nested repository there would hide the app from the outer one.
+ * It never commits, because a commit needs the person's git identity.
+ */
+export function initGitRepo(dir: string, git: GitRunner = realGit): GitInitResult {
+  const version = git(["--version"], dir);
+  if (version === undefined || version.status !== 0) return { initialized: false, detail: "git is not on PATH — run `git init` yourself once it is installed" };
+  const inside = git(["rev-parse", "--is-inside-work-tree"], dir);
+  if (inside !== undefined && inside.status === 0) return { initialized: false, detail: "the directory is already inside a git work tree, so no new repository was made" };
+  const init = git(["init", "-q"], dir);
+  return init !== undefined && init.status === 0
+    ? { initialized: true, detail: "initialised a git repository (nothing committed yet)" }
+    : { initialized: false, detail: "`git init` failed — run it yourself" };
+}

package/src/steps/build-deploy.ts

@@ -0,0 +1,78 @@
+// Step 8 — build + deploy, judged against the route.
+//
+// Satisfied only when a build output exists AND the deployment answers the probe (deploy-probe.ts)
+// at the host the operator names with `--host` (or OE_PUBLIC_BASE_URL in the env). A build
+// directory alone NEVER satisfies this step: it says nothing about a deployment. That rule is the
+// same on both routes — what differs is the command that deploys, and the probe does not care.
+//
+// Guide-only since OPE-2233: this step used to offer to run `npm run build`. The agent runs it in
+// the user's shell now, with the user's consent, and `vercel deploy --prod` was never automated —
+// deploy is a separate, explicit, human-confirmed step, and "git push does not deploy" is exactly
+// the footgun this check exists to catch.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { routeOf, type SetupStep, type StepContext } from "../engine.js";
+import { mergedEnv } from "../env-file.js";
+import { normalizeHost, probeDeployment } from "../deploy-probe.js";
+
+function nonEmptyDir(p: string): boolean {
+  try {
+    return existsSync(p) && readdirSync(p).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Is there a build output? A presence check: it can go stale after a source edit. */
+function buildOutputPresent(cwd: string): boolean {
+  return nonEmptyDir(join(cwd, ".output")) || nonEmptyDir(join(cwd, ".vercel", "output"));
+}
+
+/** The deployment origin the probe uses: `--host`, else OE_PUBLIC_BASE_URL. */
+function deployOrigin(ctx: StepContext): string | undefined {
+  if (ctx.host !== undefined) return normalizeHost(ctx.host);
+  const fromEnv = mergedEnv(ctx.cwd, ctx.env).OE_PUBLIC_BASE_URL;
+  return fromEnv ? normalizeHost(fromEnv) : undefined;
+}
+
+/** The command that deploys, per route. */
+function deployCommand(ctx: StepContext): string {
+  return routeOf(ctx) === "docker"
+    ? "build the image and run it on your server (the deployment contract states what it must satisfy)"
+    : "npx vercel deploy --prod";
+}
+
+export const buildDeployStep: SetupStep = {
+  id: "build-deploy",
+  title: "Build + deploy",
+  async check(ctx: StepContext) {
+    if (!buildOutputPresent(ctx.cwd)) return { satisfied: false, detail: "not built yet", next: "npm run build" };
+    const origin = deployOrigin(ctx);
+    if (origin === undefined) {
+      return {
+        satisfied: false,
+        detail: "built. The deploy is unproven: no host to probe",
+        next: `${deployCommand(ctx)}, then re-run with --host https://<host>`,
+      };
+    }
+    const probe = await probeDeployment(origin);
+    return probe.ok
+      ? { satisfied: true, detail: probe.detail }
+      : { satisfied: false, detail: probe.detail, next: `${deployCommand(ctx)}, then re-run this check` };
+  },
+  guide(ctx: StepContext) {
+    const vercel = routeOf(ctx) === "vercel";
+    return {
+      summary: "Build before you deploy — a broken build must never be promoted.",
+      instructions: [
+        "`npm run build` (= `oe build`, then `eve build`) — must be green.",
+        vercel
+          ? "Deploy is a SEPARATE, explicit step: `npx vercel deploy --prod` (confirm the scope and team first). A `git push` does NOT deploy."
+          : "Deploy is a SEPARATE, explicit step: build the image and run it on your server, with the contract's environment set. See https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/contract.md.",
+        "Then re-run `npx @open-everywhere/create --check --host https://<host>`: it probes the deployed Slack route.",
+        "The probe passes on the route's own `401 unauthorized`, which proves the function booted and the route is mounted. It does NOT prove the deployment holds SLACK_SIGNING_SECRET: the route answers the same without it. Only Event Subscriptions showing **Verified** in the Slack console proves that.",
+      ],
+    };
+  },
+};

package/src/steps/database.ts

@@ -0,0 +1,85 @@
+// Step 5 — database (Postgres). REQUIRED ON BOTH ROUTES (OPE-2233): the deployment contract names
+// Postgres, and a local run is no longer a setup route, so there is no embedded-floor exemption to
+// judge. On Vercel a function's disk is ephemeral — core throws at the first operational-store use
+// and at the first DM or personal memory call on an embedded floor. In Docker the same store has to
+// outlive the container.
+//
+// 🔴 IT ASKS THE RUNTIME'S OWN RULE, NOT FOR THREE ENV NAMES (OPE-2230). A bare `DATABASE_URL`
+// resolves BOTH stores to postgres by itself, so the two selectors are not demanded beside it: an
+// operator who had already connected Neon used to meet a red check and a fix list naming two
+// variables that now change nothing. A selector is still honoured — one pointing AWAY from postgres
+// is what this check refuses, and that is a different fix from a missing value, so it gets its own
+// clause rather than being folded into a "missing variables" list it does not belong in.
+//
+// The step reads the OPERATOR's env (`.env.local` or the shell): that is the state in which the
+// operator tools (`oe secret`, the ops server's `secret_set`) write the store the deployment reads.
+// It cannot read the deployment's own environment, and its detail says so — a ✓ here never claims
+// the deployment holds the same value.
+
+import { isSet, mergedEnv, missNote } from "../env-file.js";
+import { routeOf, type SetupRoute, type SetupStep, type StepContext } from "../engine.js";
+import { resolveOperationalSelection } from "@open-everywhere/core/agent/operational/selection.js";
+import { resolveMemoryProviderId } from "@open-everywhere/core/agent/memory/backing-selection.js";
+import { OWNER_URL_ENV, RUNTIME_ROLE_NAME } from "@open-everywhere/core/agent/ops/two-role.js";
+
+/** Which stores this env resolves to postgres, by the runtime's own two rules. */
+function postgresResolution(env: NodeJS.ProcessEnv): { operational: boolean; memory: boolean } {
+  const op = resolveOperationalSelection(env);
+  return { operational: op.id === "postgres" && op.floor === "none", memory: resolveMemoryProviderId(env) === "postgres" };
+}
+
+/** The next action for an unsatisfied database step, per route. */
+function nextFor(route: SetupRoute): string {
+  const write = 'write it with the ops MCP tool `scaffold_env { values: { DATABASE_URL: "<the connection string>" } }` — it selects postgres for both stores on its own';
+  return route === "vercel"
+    ? `add Neon from the Vercel Marketplace (\`npx vercel install neon\`, or the project's Storage → Neon → Connect; either sets DATABASE_URL on the project), then ${write}`
+    : `provision a Postgres the container can reach (the deployment contract names it), then ${write}`;
+}
+
+export const databaseStep: SetupStep = {
+  id: "database",
+  title: "Database (Postgres)",
+  check(ctx: StepContext) {
+    const env = mergedEnv(ctx.cwd, ctx.env) as NodeJS.ProcessEnv;
+    const route = routeOf(ctx);
+    const resolved = postgresResolution(env);
+    if (isSet(env.DATABASE_URL) && resolved.operational && resolved.memory) {
+      return {
+        satisfied: true,
+        detail:
+          "DATABASE_URL is set locally and selects postgres for both stores. This check cannot read the deployment's own " +
+          "environment: the same connection string must reach it too",
+      };
+    }
+    const pointedAway = [
+      ...(resolved.operational || !isSet(env.OE_OPERATIONAL_PROVIDER) ? [] : ["OE_OPERATIONAL_PROVIDER"]),
+      ...(resolved.memory || !isSet(env.OE_MEMORY_PROVIDER) ? [] : ["OE_MEMORY_PROVIDER"]),
+    ];
+    return {
+      satisfied: false,
+      detail:
+        "a deployment needs Postgres on both routes. " +
+        (isSet(env.DATABASE_URL)
+          ? `DATABASE_URL is set, but a selector points away from postgres: ${pointedAway.join(", ")}. Remove it, or set it to postgres. `
+          : "Missing from .env.local and this shell: DATABASE_URL — it selects postgres for both stores on its own. ") +
+        missNote(route),
+      next: nextFor(route),
+    };
+  },
+  guide(ctx: StepContext) {
+    const vercel = routeOf(ctx) === "vercel";
+    return {
+      summary: "Both routes need Postgres: an ephemeral disk (Vercel) or a replaced container (Docker) loses every local store.",
+      instructions: [
+        vercel
+          ? "`npx vercel install neon` provisions Neon and connects it to the linked project, which sets DATABASE_URL there. The project's Storage → Neon → Connect does the same thing."
+          : "Provision a Postgres the container can reach (Neon, RDS, or your own server). The deployment contract states what it must satisfy.",
+        "Write the same connection string into .env.local with the ops tool `scaffold_env`. It selects postgres for the operational store and the memory backing on its own — no provider selector needed. Never paste a connection string into the chat.",
+        vercel
+          ? "The deployment needs it too: the Neon integration already set DATABASE_URL on the Vercel project."
+          : "The deployment needs it too: DATABASE_URL is part of the container's environment.",
+        `Harden later: the two-role split parks the owner credential as ${OWNER_URL_ENV} and runs the app as the non-owner "${RUNTIME_ROLE_NAME}" role, which the owner-DDL escape cannot reach. It is MANUAL — nothing provisions it for you. See https://github.com/open-everywhere/open-everywhere/blob/main/docs/extending/database.md.`,
+      ],
+    };
+  },
+};