@open-everywhere/create 0.1.4

package/src/steps/env-checklist.ts

@@ -0,0 +1,55 @@
+// Step 7 — env var checklist. A rollup, not a new check: it reuses `preflight()` from
+// packages/core/agent/ops/quickstart.ts — the same logic the ops MCP server's `preflight` tool
+// serves — so the two frontends agree on what "ready" means. Reports presence and fix hints ONLY,
+// never a value (AGENTS.md: never log a secret). Purely a report: nothing here writes.
+//
+// THE ROUTE IS THE PREFLIGHT TARGET (OPE-2233). `--route vercel` judges against `target: "vercel"`
+// and `--route docker` against `target: "docker"`. The targets differ on exactly one check — the
+// model route — because only a Vercel deployment authenticates the AI Gateway with OIDC. Passing
+// one target for both would have reported "not needed on Vercel" to a Docker operator, which is
+// the doc-overclaim defect class in a status report.
+
+import { preflight } from "@open-everywhere/core/agent/ops/quickstart.js";
+import { routeOf, type SetupStep, type StepContext } from "../engine.js";
+import { mergedEnv, missNote } from "../env-file.js";
+
+export const envChecklistStep: SetupStep = {
+  id: "env-checklist",
+  title: "Env var checklist",
+  check(ctx: StepContext) {
+    const env = mergedEnv(ctx.cwd, ctx.env) as NodeJS.ProcessEnv;
+    const route = routeOf(ctx);
+    const { checks, ready } = preflight(env, { target: route });
+    const missing = checks.filter((c) => c.status === "missing");
+    return {
+      satisfied: ready,
+      detail: ready
+        ? `all required env vars present for the ${route} route`
+        : `missing from .env.local and this shell: ${missing.map((c) => c.name).join(", ")}. ${missNote(route)}`,
+      next: ready ? undefined : missing.map((c) => c.fix).filter((f): f is string => Boolean(f)).join(" · "),
+    };
+  },
+  // 🔴 `guide()` IS STATIC, AND THAT IS DELIBERATE (OPE-2233). It used to dump the live preflight
+  // rows, which read `process.versions.node` and the operator's `.env.local`. `guide()` is now read
+  // by `scripts/setup-steps-docs.ts` to GENERATE a committed reference page, so a live reading
+  // would make the generator's output depend on the machine that ran it. The live rows are what
+  // `check()` and the ops `preflight` tool are for.
+  guide(ctx: StepContext) {
+    const route = routeOf(ctx);
+    return {
+      summary:
+        "A presence-only checklist (it never prints a value). The full surface is in the configuration reference: " +
+        "https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/configuration-reference.md",
+      instructions: [
+        "Both routes need two values: DATABASE_URL and OE_CREDENTIAL_ENCRYPTION_KEY. DATABASE_URL resolves BOTH stores to postgres on its own (OPE-2230), so there is no provider selector to set — a selector pointing away from postgres is the only thing that breaks it.",
+        "Mint OE_CREDENTIAL_ENCRYPTION_KEY with the ops tool `scaffold_credential_key`: it writes a base64 32-byte AES-256 key into .env.local and never prints it. The encrypted credential store fails closed on every read and write without it.",
+        route === "docker"
+          ? "The Docker route also needs a model route: AI_GATEWAY_API_KEY. There is no OIDC off Vercel. Running a different model backend 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."
+          : "The Vercel route needs NO AI_GATEWAY_API_KEY: a deployed project authenticates to the AI Gateway with OIDC.",
+        "Each chat surface adds its own names — Slack reads SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET from the environment.",
+        "Not needed on a deployment: OE_PUBLIC_BASE_URL (only for a custom domain) and OE_INTAKE_PAGE_SIGNING_KEY (the deployment mints it into the credential store).",
+        "Run `npx @open-everywhere/create --check --json`, or the ops tool `preflight`, for the live verdict per name.",
+      ],
+    };
+  },
+};

package/src/steps/index.ts

@@ -0,0 +1,49 @@
+// The ordered step list — the ONE setup checklist. `@open-everywhere/create --check` reports it,
+// the `quickstart-open-everywhere` skill reads that report, and `scripts/setup-steps-docs.ts`
+// renders it into docs/deploy/setup-steps.md, so the human reference page cannot drift from the
+// checks.
+//
+// Order: prerequisites, repo, roster, Vercel, database, Slack, env checklist, build + deploy,
+// final verification. The ROSTER (OPE-258, config-driven since OPE-375) sits immediately after
+// `repo`, because it is the first thing that needs `node_modules` and the last thing that should
+// be discovered after a deploy: a checkout whose slot tree was never materialised boots fine and
+// silently has no hands.
+//
+// 🔴 THE TELEMETRY-DISCLOSURE STEP IS GONE (OPE-2233). It existed to show a consent prompt, and
+// the interactive wizard was the only surface that could show one. With the wizard retired the
+// `@open-everywhere/create` CLI emits no telemetry at all — see docs/deploy/telemetry.md.
+
+import type { SetupStep } from "../engine.js";
+import { prerequisitesStep } from "./prerequisites.js";
+import { repoStep } from "./repo.js";
+import { rosterStep } from "./roster.js";
+import { vercelStep } from "./vercel.js";
+import { databaseStep } from "./database.js";
+import { slackStep } from "./slack.js";
+import { envChecklistStep } from "./env-checklist.js";
+import { buildDeployStep } from "./build-deploy.js";
+import { verifyStep } from "./verify.js";
+
+export const SETUP_STEPS: readonly SetupStep[] = [
+  prerequisitesStep,
+  repoStep,
+  rosterStep,
+  vercelStep,
+  databaseStep,
+  slackStep,
+  envChecklistStep,
+  buildDeployStep,
+  verifyStep,
+];
+
+export {
+  prerequisitesStep,
+  repoStep,
+  rosterStep,
+  vercelStep,
+  databaseStep,
+  slackStep,
+  envChecklistStep,
+  buildDeployStep,
+  verifyStep,
+};

package/src/steps/prerequisites.ts

@@ -0,0 +1,50 @@
+// Step 1 — prerequisites: a Node version inside @open-everywhere/core's `engines.node` range, and
+// `git` on PATH. Guide-only: installing a Node version or git is an OS-level action, so the step
+// states what is needed and the person (or their agent, with their consent) does it.
+//
+// The range is read from core's manifest (the same reader the ops `preflight` uses), so this check
+// and the ops server cannot disagree about the Node floor.
+
+import { execFileSync } from "node:child_process";
+import { coreNodeRange, nodeRangeSatisfied } from "@open-everywhere/core/agent/ops/package-info.js";
+import type { SetupStep } from "../engine.js";
+
+/** Is `git` on PATH? */
+function gitAvailable(): boolean {
+  try {
+    execFileSync("git", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The Node verdict, split out so a test can drive any version against any range. */
+export function nodeVerdict(version: string, range: string | undefined): { ok: boolean; detail: string } {
+  if (range === undefined) return { ok: false, detail: `node ${version} (cannot read @open-everywhere/core's engines.node — run \`npm install\`)` };
+  const ok = nodeRangeSatisfied(range, version);
+  if (ok === undefined) return { ok: false, detail: `node ${version} (cannot parse the engines range "${range}")` };
+  return { ok, detail: ok ? `node ${version}` : `node ${version} (need ${range})` };
+}
+
+export const prerequisitesStep: SetupStep = {
+  id: "prerequisites",
+  title: "Prerequisites (Node 24, git)",
+  check() {
+    const node = nodeVerdict(process.versions.node, coreNodeRange());
+    const git = gitAvailable();
+    const satisfied = node.ok && git;
+    const detail = `${node.detail}${git ? ", git present" : ", git NOT found on PATH"}`;
+    const next = !node.ok ? "nvm install 24 && nvm use 24" : !git ? "install git: https://git-scm.com/downloads" : undefined;
+    return { satisfied, detail, next };
+  },
+  guide() {
+    return {
+      summary: `Open Everywhere needs the Node range @open-everywhere/core declares (${coreNodeRange() ?? "see its engines.node"}) and git.`,
+      instructions: [
+        "Install Node 24: `nvm install 24 && nvm use 24` (or your platform's installer).",
+        "Install git if `git --version` fails (https://git-scm.com/downloads).",
+      ],
+    };
+  },
+};

package/src/steps/repo.ts

@@ -0,0 +1,69 @@
+// Step 2 — repo: are we standing inside an Open Everywhere app with deps installed? The app comes
+// from `npx @open-everywhere/create <dir>` (the scaffold, src/scaffold.ts), or from a clone or fork
+// of the repository. This step never clones anything, and since OPE-2233 it never installs
+// anything either: the agent runs `npm install` in the user's shell, which runs the app's own
+// `postinstall` (`oe-eve-patch`) and patches the installed eve.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SetupStep, StepContext } from "../engine.js";
+
+interface AppState {
+  /** True when the app is here AND its deps are installed — the step's satisfied state. */
+  readonly ok: boolean;
+  /** True when the directory is an Open Everywhere app, installed or not. */
+  readonly app: boolean;
+  readonly detail: string;
+}
+
+/**
+ * What actually makes a directory an Open Everywhere app: eve's agent entry (`agent/agent.ts`
+ * — eve discovers the graph by filesystem convention, so nothing runs without it) plus a
+ * `package.json` that reaches `@open-everywhere/core`, either as a dependency or through the
+ * monorepo's workspaces.
+ *
+ * 🔴 It deliberately does NOT look for `AGENTS.md`. Nothing at runtime reads that file, and it is
+ * the contributor guide, so a scaffolded consumer app or a fork that deleted it would fail. Sniff
+ * for the thing that has to be there for the product to boot.
+ */
+function inspectApp(cwd: string): AppState {
+  const pkgPath = join(cwd, "package.json");
+  const agentEntry = join(cwd, "agent", "agent.ts");
+  if (!existsSync(pkgPath)) return { ok: false, app: false, detail: "no package.json here — not an Open Everywhere app" };
+  if (!existsSync(agentEntry)) {
+    return { ok: false, app: false, detail: "no agent/agent.ts here — not an Open Everywhere app (eve finds the agent graph by convention)" };
+  }
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+      workspaces?: string[];
+    };
+    const hasCoreDep = Boolean(pkg.dependencies?.["@open-everywhere/core"] ?? pkg.devDependencies?.["@open-everywhere/core"]);
+    const hasWorkspaces = Array.isArray(pkg.workspaces) && pkg.workspaces.some((w) => w.includes("packages"));
+    if (!hasCoreDep && !hasWorkspaces) return { ok: false, app: false, detail: "package.json here doesn't reach @open-everywhere/core" };
+  } catch {
+    return { ok: false, app: false, detail: "package.json here is unreadable" };
+  }
+  const installed = existsSync(join(cwd, "node_modules"));
+  return { ok: installed, app: true, detail: installed ? "app found, deps installed" : "app found, but run `npm install`" };
+}
+
+export const repoStep: SetupStep = {
+  id: "repo",
+  title: "Repo (app + install)",
+  check(ctx: StepContext) {
+    const { ok, app, detail } = inspectApp(ctx.cwd);
+    return { satisfied: ok, detail, next: ok ? undefined : app ? "npm install" : "npx @open-everywhere/create my-agent && cd my-agent" };
+  },
+  guide() {
+    return {
+      summary: "Get an Open Everywhere app with deps installed.",
+      instructions: [
+        "Easiest: `npx @open-everywhere/create my-agent` scaffolds the quickstart app into ./my-agent and prints the next steps.",
+        "Or clone the repository: `git clone https://github.com/open-everywhere/open-everywhere && cd open-everywhere && npm install`.",
+        "Then re-run this check FROM inside that app.",
+      ],
+    };
+  },
+};

package/src/steps/roster.ts

@@ -0,0 +1,111 @@
+// Step 3 — the roster: does this checkout declare what its agent can do, and is the materialised
+// eve slot tree in step with that declaration?
+//
+// THIS IS THE SCAFFOLD-TIME HALF of OPE-375 (it replaces OPE-258's shim-counting step). eve
+// discovers tools, channels, hooks, schedules, skills and connections by FILESYSTEM CONVENTION —
+// one file per contribution, named after the file — but those six directories are now BUILD OUTPUT:
+// `oe build` writes them from `roster.config.ts` (the declaration) plus `roster.lock.json` (the
+// reviewed roll-call). Both of those are committed; the tree is gitignored.
+//
+// 🔴 THE FAILURE THIS STEP EXISTS TO CATCH IS SILENT. eve does not error on an empty `agent/tools/`
+// — it mounts nothing and boots green. A fresh clone, a `git clean -xdf`, or a build command that
+// skipped the `prebuild` hook therefore yields an agent with NO HANDS that looks perfectly healthy.
+// So the check is not "does the config exist" alone; it is `oe build --check`, which asserts the
+// on-disk tree byte-equals what the declaration plans.
+//
+// 🔴 THIS STEP NEVER RUNS `oe build --accept`, AND SINCE OPE-2233 IT RUNS NOTHING AT ALL. It
+// reports and hands over the command. `--accept` rewrites the lock, which is the act of REVIEWING
+// a capability: deciding what the agent may do belongs to the operator, never to a setup tool
+// acting on their behalf.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { SetupStep, StepContext } from "../engine.js";
+
+/** What this step knows about a checkout, or why it can't tell. */
+type RosterState =
+  | { readonly kind: "unknown"; readonly detail: string }
+  | { readonly kind: "known"; readonly detail: string; readonly clean: boolean };
+
+/**
+ * The `oe` CLI as installed in the target checkout, as a command and its leading argv; `undefined`
+ * when deps are not installed yet.
+ *
+ * It runs core's declared `oe` bin script with the CURRENT Node, never the `node_modules/.bin` shim.
+ * On Windows that shim is `oe.cmd`, and Node refuses to spawn a `.cmd` without a shell
+ * (CVE-2024-27980), so the check always failed there and the step reported every Windows checkout as
+ * unmaterialised (OPE-2211). Reading the bin from core's own manifest works the same on every platform.
+ */
+function oeBin(cwd: string): { readonly command: string; readonly args: readonly string[] } | undefined {
+  const manifest = join(cwd, "node_modules", "@open-everywhere", "core", "package.json");
+  if (!existsSync(manifest)) return undefined;
+  let rel: unknown;
+  try {
+    const pkg = JSON.parse(readFileSync(manifest, "utf8")) as { bin?: string | Record<string, string> };
+    rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.oe;
+  } catch {
+    return undefined;
+  }
+  if (typeof rel !== "string") return undefined;
+  const script = join(dirname(manifest), rel);
+  return existsSync(script) ? { command: process.execPath, args: [script] } : undefined;
+}
+
+/**
+ * Inspect the roster. Every "cannot tell" outcome is UNKNOWN and unsatisfied — never a pass. A step
+ * that treated a missing CLI as "nothing to do" would report a hands-free checkout as correctly
+ * configured, which is the one answer that must not be reachable.
+ */
+export function inspectRoster(cwd: string): RosterState {
+  if (!existsSync(join(cwd, "roster.config.ts"))) {
+    return { kind: "unknown", detail: "roster.config.ts is missing — every Open Everywhere app declares its roster there" };
+  }
+  if (!existsSync(join(cwd, "roster.lock.json"))) {
+    return {
+      kind: "known",
+      clean: false,
+      detail: "roster.lock.json is missing — nothing has been REVIEWED, so `oe build` will refuse to mount anything",
+    };
+  }
+  const bin = oeBin(cwd);
+  if (bin === undefined) return { kind: "unknown", detail: "the `oe` CLI is not installed — run `npm install` first (the repo step covers this)" };
+  try {
+    execFileSync(bin.command, [...bin.args, "build", "--check"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return { kind: "known", clean: true, detail: "the materialised slot tree matches roster.config.ts + roster.lock.json" };
+  } catch (err) {
+    const e = err as { stdout?: string; stderr?: string };
+    const first = `${e.stderr ?? ""}${e.stdout ?? ""}`.split("\n").find((l) => l.includes("·"))?.trim();
+    return { kind: "known", clean: false, detail: first ?? "`oe build --check` reports the tree does not match the roster declaration" };
+  }
+}
+
+/** The command that clears a roster red, read off the red itself. */
+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";
+  return "npx oe build";
+}
+
+export const rosterStep: SetupStep = {
+  id: "roster",
+  title: "Roster (roster.config.ts → the eve slot tree)",
+  check(ctx: StepContext) {
+    const state = inspectRoster(ctx.cwd);
+    const satisfied = state.kind === "known" && state.clean;
+    return { satisfied, detail: state.detail, next: satisfied ? undefined : rosterNext(state.detail) };
+  },
+  guide() {
+    return {
+      summary: "`roster.config.ts` declares what your agent can do; `oe build` materialises the eve slot tree from it.",
+      instructions: [
+        "roster.config.ts is terse: which packages contribute, which contributions this deployment EXCLUDES (with a reason), and which eve built-ins it takes away.",
+        "roster.lock.json is the expanded, REVIEWED roll-call. Both are committed — the slot tree they generate is not.",
+        "An upgrade that ships a NEW tool fails the build until you decide about it, then `npx oe build --accept` records the decision. There is no bypass flag.",
+        "`npx oe build --show` prints the tree it would write, without writing it; `npm run lint:roster` is the gate.",
+        "eve mounts NOTHING (and still boots) if the tree is missing — so never skip the build step.",
+      ],
+    };
+  },
+};

package/src/steps/slack.ts

@@ -0,0 +1,74 @@
+// Step 6 — Slack app creation. Manifest output plus token-collection guidance (the minimal path
+// from the Slack surface guide). App creation itself is necessarily manual (Slack's UI, and
+// workspace-admin approval), so this step guides and then verifies by env presence.
+//
+// The manifest itself lives in the Slack bundle (OPE-1603) — @open-everywhere/provider-slack/
+// agent/app-manifest.js — so this step and the ops MCP tool `surface_manifest` print the SAME
+// document. The bundle resolves SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET ENV-FIRST (the block
+// below has the second home), so an operator who sets them by hand puts both in `.env.local` and
+// then on the deployment.
+//
+// REQUIRED ON BOTH ROUTES (OPE-2233). The old `local` exemption is gone with the local goal: a
+// deployment with no chat surface configured answers nobody, whichever route it took.
+//
+// 🔴 THERE ARE TWO HOMES SINCE OPE-2231, AND THIS CHECK READS ONE. The bundle resolves both
+// secrets ENV-FIRST and then from the deployment's own encrypted credential store, which is where
+// a `/setup` run puts them — so a deployment configured that way is CORRECT and this step still
+// reports it unsatisfied, because `.env.local` and the shell are all it can read. That makes the
+// wording load-bearing: the detail says "missing from .env.local and this shell", never a bare
+// "missing", and it names `/setup` and the status endpoint as the places that can see the store.
+// This honesty rode the retired `quickstart` plan's Slack step before OPE-2233 retired it; it
+// belongs here now, because this is the one ordering left.
+
+import { SLACK_DEFAULT_APP_NAME, slackAppManifestTemplate } from "@open-everywhere/provider-slack/agent/app-manifest.js";
+import { docUrl } from "@open-everywhere/core/agent/ops/quickstart.js";
+import { routeOf, type SetupStep, type StepContext } from "../engine.js";
+import { isSet, mergedEnv, missNote } from "../env-file.js";
+
+const SLACK_ENV = ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"] as const;
+
+export const slackStep: SetupStep = {
+  id: "slack",
+  title: "Slack app",
+  check(ctx: StepContext) {
+    const env = mergedEnv(ctx.cwd, ctx.env);
+    const missing = SLACK_ENV.filter((name) => !isSet(env[name]));
+    if (missing.length === 0) {
+      return {
+        satisfied: true,
+        detail:
+          "SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET set in the environment. 🔴 Setting these two makes the deployment IGNORE anything " +
+          "/setup stored, and CLOSES /setup: the resolver is env-first, so landing that page cannot change which Slack app a working " +
+          "deployment speaks as",
+      };
+    }
+    return {
+      satisfied: false,
+      detail:
+        `missing from .env.local and this shell: ${missing.join(", ")}. This check reads those two homes only — a deployment ` +
+        "configured by /setup keeps both secrets in its own encrypted credential store, and reports unsatisfied here while working " +
+        `correctly. The status endpoint and /setup itself are what can see the store. ${missNote(routeOf(ctx))}`,
+      next:
+        'open https://<host>/setup once the deployment is up (it creates and installs the Slack app from one pasted configuration ' +
+        'token, with no env var to set), or create the app from the manifest the ops tool `surface_manifest { surface: "slack" }` ' +
+        "returns and write each pasted value with `scaffold_env`",
+    };
+  },
+  guide(ctx: StepContext) {
+    return {
+      summary: "Create a Slack app from the manifest below, then copy its bot token and signing secret.",
+      instructions: [
+        "https://api.slack.com/apps → Create New App → From an app manifest → pick the workspace → JSON → paste:",
+        slackAppManifestTemplate(ctx.appName === undefined ? {} : { appName: ctx.appName }),
+        `The app is named "${ctx.appName ?? SLACK_DEFAULT_APP_NAME}". A second install in one workspace needs its own name: re-run with --app-name "<name>".`,
+        "Install to Workspace, then OAuth & Permissions → copy the Bot User OAuth Token (xoxb-…) = SLACK_BOT_TOKEN.",
+        "Basic Information → App Credentials → copy the Signing Secret = SLACK_SIGNING_SECRET.",
+        "Write both with the ops tool `scaffold_env`. Never paste a secret into the chat: the person pastes it where the tool reads it.",
+        "THE SHORT WAY, once the deployment is up: open https://<host>/setup. It creates the Slack app from this same manifest with one pasted Slack app configuration token, installs it, and keeps every credential in the deployment's own encrypted store — no env var to set. This check cannot see that store, so it still reports this step unsatisfied afterwards; the status endpoint can.",
+        "The manifest's URLs say YOUR-DEPLOY-URL until you deploy. Slack cannot verify Event Subscriptions before a deploy that holds SLACK_SIGNING_SECRET is up. After the deploy, paste the manifest again with your host (App Manifest → Save Changes), then retry the verification under Event Subscriptions.",
+        "Note two ids for the trust edits: the workspace (team) id T… (the segment after /client/ in the workspace URL at https://app.slack.com), and your own member id U… (your Slack profile → ⋮ More → Copy member ID).",
+        `Full walkthrough: ${docUrl("docs/deploy/surfaces/slack.md")}.`,
+      ],
+    };
+  },
+};

package/src/steps/vercel.ts

@@ -0,0 +1,40 @@
+// Step 4 — Vercel project link. `.vercel/project.json` is what `vercel link`/`vercel deploy` writes
+// once a directory is linked to a Vercel project; its presence is a real-world, resumable signal.
+// Guide-only, like every step since OPE-2233: the agent runs `vercel link` in the user's shell.
+//
+// The DOCKER route needs no Vercel project, so the step is satisfied there (docs/deploy/contract.md
+// is that route's reference).
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { routeOf, type SetupStep, type StepContext } from "../engine.js";
+
+export const vercelStep: SetupStep = {
+  id: "vercel",
+  title: "Vercel project link",
+  check(ctx: StepContext) {
+    if (routeOf(ctx) === "docker") return { satisfied: true, detail: "not needed on the Docker route (--route docker)" };
+    const p = join(ctx.cwd, ".vercel", "project.json");
+    if (!existsSync(p)) return { satisfied: false, detail: "no .vercel/project.json — not linked yet", next: "npx vercel link" };
+    try {
+      const linked = JSON.parse(readFileSync(p, "utf8")) as { projectId?: string };
+      return linked.projectId
+        ? { satisfied: true, detail: "linked to a Vercel project" }
+        : { satisfied: false, detail: ".vercel/project.json is malformed", next: "npx vercel link" };
+    } catch {
+      return { satisfied: false, detail: ".vercel/project.json is unreadable", next: "npx vercel link" };
+    }
+  },
+  guide(ctx: StepContext) {
+    if (routeOf(ctx) === "docker") {
+      return {
+        summary: "The Docker route needs no Vercel project.",
+        instructions: ["Nothing to do: `--route docker` skips this step. The deployment contract is the Docker route's reference."],
+      };
+    }
+    return {
+      summary: "Link this app to a Vercel project. Every later `vercel` command acts on the linked project.",
+      instructions: ["`npx vercel link` — follow the prompts (device auth in your browser)."],
+    };
+  },
+};

package/src/steps/verify.ts

@@ -0,0 +1,119 @@
+// Step 9 — final verification. A report, not a new check: it re-runs the substantive steps' own
+// `check()`s (reuse over reimplementation) and rolls them into one go/no-go line, mirroring
+// docs/deploy/setup-runbook.md's own "verify before going live" section. This step's only job is
+// to tell you the truth.
+
+import { routeOf, type SetupStep, type StepContext } from "../engine.js";
+import { prerequisitesStep } from "./prerequisites.js";
+import { repoStep } from "./repo.js";
+import { slackStep } from "./slack.js";
+import { databaseStep } from "./database.js";
+import { buildDeployStep } from "./build-deploy.js";
+import { rosterStep } from "./roster.js";
+import { envChecklistStep } from "./env-checklist.js";
+
+/**
+ * What the DEPLOYMENT's own environment must carry. Named here, in the one step whose job is to
+ * say whether setup is finished, because no `check()` in this engine can observe it: `.env.local`
+ * is gitignored and never ships. DATABASE_URL is on the list because the Vercel route's Neon
+ * integration sets it on the project while the Docker route's operator sets it by hand.
+ *
+ * 🔴 THE TWO STORE SELECTORS ARE NOT ON THIS LIST (OPE-2230). A present `DATABASE_URL` resolves
+ * both stores to postgres on its own, so naming them here would send an operator to set two
+ * variables that change nothing — the exact fix list that ticket removed.
+ */
+const DEPLOYMENT_ENV_NAMES = ["DATABASE_URL", "OE_CREDENTIAL_ENCRYPTION_KEY", "SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"] as const;
+
+/**
+ * The go/no-go rule, split out from `check()` so it can be tested on its own. That split is
+ * not ceremony: every real `check()` in a scratch directory fails on repo/slack/build too, so
+ * a test driven through `verifyStep.check` reports "not ready" no matter what this rule says,
+ * and an assertion on it passes for the wrong reason. Dropping a term here has to be provable.
+ *
+ * `database` earns its seat because a roll-up that omits it can say "ready" about an instance
+ * that loses every memory and every audit row on its next deploy — this check's most
+ * consequential possible lie. Since OPE-2233 both routes need Postgres, so the term bites any
+ * checkout still on the embedded floor.
+ */
+export function verifyVerdict(parts: {
+  readonly prereq: boolean;
+  readonly repo: boolean;
+  readonly slack: boolean;
+  readonly database: boolean;
+  readonly build: boolean;
+  /** The roster tree and the env checklist. Optional so the five-term callers keep their shape. */
+  readonly roster?: boolean;
+  readonly env?: boolean;
+}): { satisfied: boolean; detail: string } {
+  const failing = [
+    !parts.prereq && "prerequisites",
+    !parts.repo && "repo",
+    parts.roster === false && "roster",
+    parts.env === false && "env vars",
+    !parts.slack && "slack (or another surface)",
+    !parts.database && "durable state backing",
+    !parts.build && "build",
+  ].filter((x): x is string => Boolean(x));
+  return {
+    satisfied: failing.length === 0,
+    detail: failing.length === 0
+      ? "ready: every step this check can see is in place"
+      : `not ready yet: ${failing.join(", ")}`,
+  };
+}
+
+export const verifyStep: SetupStep = {
+  id: "verify",
+  title: "Final verification",
+  async check(ctx: StepContext) {
+    const [prereq, repo, roster, slack, database, env, build] = await Promise.all([
+      prerequisitesStep.check(ctx),
+      repoStep.check(ctx),
+      rosterStep.check(ctx),
+      slackStep.check(ctx),
+      databaseStep.check(ctx),
+      envChecklistStep.check(ctx),
+      buildDeployStep.check(ctx),
+    ]);
+    const verdict = verifyVerdict({
+      prereq: prereq.satisfied,
+      repo: repo.satisfied,
+      roster: roster.satisfied,
+      slack: slack.satisfied,
+      database: database.satisfied,
+      env: env.satisfied,
+      build: build.satisfied,
+    });
+    if (!verdict.satisfied) return { ...verdict, next: "follow the `next` of each unsatisfied step above, then re-run this check" };
+    // 🔴 WHAT "READY" DOES NOT MEAN (OPE-2233 review). Every step above reads `.env.local` and this
+    // shell; NONE of them reads the deployment's own environment, and the build+deploy probe passes
+    // on the chat route's own `401 unauthorized`, which that route returns WITHOUT its signing
+    // secret. So a full house here is reachable for a deployment whose credential store fails
+    // closed on every read and whose Slack app can never verify. The retired `quickstart` plan
+    // carried a permanently-`todo` env-push step that said this by construction; a satisfied step
+    // cannot, so the satisfied `next` says it instead.
+    return {
+      ...verdict,
+      next:
+        "set the deployment's OWN environment — this check never reads it: " +
+        `${DEPLOYMENT_ENV_NAMES.join(", ")} (${routeOf(ctx) === "docker" ? "the container's environment" : "the Vercel project's Production environment"}). ` +
+        "Then confirm the Slack app's Event Subscriptions shows the request URL as Verified (that proves SLACK_SIGNING_SECRET on the deployment; this check cannot), and send the app a direct message",
+    };
+  },
+  guide(ctx: StepContext) {
+    const vercel = routeOf(ctx) === "vercel";
+    return {
+      summary: "Before going live, run a real task in a pilot channel and walk the setup runbook's safety checklist (access bundles, egress enforcement, spend caps).",
+      instructions: [
+        `🔴 THIS CHECK NEVER READS THE DEPLOYMENT'S OWN ENVIRONMENT. Every step above reads .env.local and your shell. \`.env.local\` is gitignored and never ships, so the deployment reads only what you set ON it: ${DEPLOYMENT_ENV_NAMES.join(", ")}. A full house here says nothing about any of them.`,
+        vercel
+          ? "Set each one for Production without printing it: `npm run -s env:pipe -- <NAME> | npx vercel env add <NAME> production`. Always pipe it straight into `vercel env add`; never run `env:pipe` bare, because a shell that is not a terminal prints the value. The Neon integration already set DATABASE_URL there, and it selects postgres for both stores on its own — no provider selector to push. A variable added after a deploy reaches the functions only on the NEXT deploy."
+          : "Set each one in the container's environment (a compose file, your orchestrator's secret store — not a tracked file). DATABASE_URL selects postgres for both stores on its own. A variable added after the container starts reaches the app only on the next start.",
+        "Mint OE_CREDENTIAL_ENCRYPTION_KEY with the ops tool `scaffold_credential_key`, which writes it to .env.local and never prints it. Without it the encrypted credential store fails closed on every read and write.",
+        "Not needed on a deployment: the two store selectors (DATABASE_URL resolves both), OE_PUBLIC_BASE_URL (only for a custom domain) and OE_INTAKE_PAGE_SIGNING_KEY (the deployment mints it into the credential store). On the Vercel route, AI_GATEWAY_API_KEY is not needed either — OIDC covers it.",
+        "Send the app a direct message in Slack, then @mention it in a channel you invited it to.",
+        "Safety checklist: https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/setup-runbook.md#safety-checklist-the-anti-footgun-list",
+      ],
+    };
+  },
+};

package/src/version.ts

@@ -0,0 +1,20 @@
+// This package's own version, read from its package.json at runtime (never hand-duplicated) —
+// used by the CLI's `--version` flag, the `--check` report, and the scaffold, which stamps it into
+// every template file that carries the version placeholder. Falls back to "0.0.0" if the read ever
+// fails (a packaged or renamed layout, a missing file) rather than throwing: a version string must
+// never crash a scaffold.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+function readVersion(): string {
+  try {
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
+    return typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export const CLI_VERSION = readVersion();