@open-everywhere/create 0.2.1 → 0.4.0

package/README.md

@@ -1,17 +1,46 @@
 # @open-everywhere/create
 
-The scaffold and setup check for Open Everywhere.
+<!-- HERO LINE: Tommy decides -->
 
-Part of [Open Everywhere](https://github.com/open-everywhere/open-everywhere) — an open, self-hostable autonomous teammate you tag where your
-team works. This package is run, not imported, and it does two things: it scaffolds a new app from
+**The scaffold and setup check for Open Everywhere: an open-source AI agent that your team runs on
+its own infrastructure and works with in chat, issues, docs and code.**
+
+```sh
+npm create @open-everywhere my-agent
+```
+
+Then open the new app in your coding agent and ask it to finish the setup.
+
+## What you get
+
+One deployment of Open Everywhere gives your org all of these together:
+
+- **Six platforms.** Slack, Microsoft Teams, Discord, GitHub, Linear and Notion, on one identity model.
+- **One deployment for the whole org.** Each domain names the memory silos it uses and can bind its own credentials.
+- **Changes by pull request.** The agent proposes changes to its own grants, and a human merges each one.
+- **Governance you can verify.** Rules live in your repository, and the audit log is append-only and
+  hash-chained.
+- **Quiet routines.** A condition gate that says no costs no model spend.
+- **Engineering work.** Repository checkout, edits and pull requests behind an approval gate.
+- **Any model.** One setting switches every model role, closed or open-weights.
+
+The [project README](https://github.com/open-everywhere/open-everywhere#how-the-parts-fit) links each
+part to its docs.
+
+## What this package does
+
+This package is run, not imported, and it does two things: it scaffolds a new app from
 the quickstart template, and it reports an existing app's setup status without touching it.
 
 **Setup itself is agent-led.** There is no interactive wizard: you open the scaffolded app in your
 coding agent and ask it to set up Open Everywhere. The agent reads the app's `AGENTS.md`, drives the
-`open-everywhere-ops` MCP server, and reads this command's `--check` report. Two routes are
-supported, and the agent asks which first: **Vercel** (the `vercel` CLI plus Marketplace Neon) or
-**Docker** (a self-hosted container that satisfies the
+`open-everywhere-ops` MCP server, and reads this command's `--check` report. The agent asks which
+route first: **Vercel** (the `vercel` CLI plus Marketplace Neon) or **Docker** (a self-hosted
+container that satisfies the
 [deployment contract](https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/contract.md)).
+Vercel is the one route that the project runs end to end. The Docker route is partly proven, and a
+scaffolded app carries no `Dockerfile`: see the
+[deployment contract](https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/contract.md).
 
 ## Use
 
@@ -27,7 +56,9 @@ npm create @open-everywhere my-agent
 This scaffolds the quickstart app into `./my-agent`, prints the next steps and exits. It never
 prompts. The directory must be new or empty. A fresh clone of an empty repository holds only `.git`,
 and it counts as empty: run `npx @open-everywhere/create .` inside it. The scaffold refuses a
-directory that holds anything else. The app depends on the eight `@open-everywhere/*` libraries at
+directory that holds anything else. Run inside an empty clone named `my-agent`,
+`npx @open-everywhere/create my-agent` would make `my-agent/my-agent/`, so it refuses and prints the
+`.` command instead. To nest on purpose, create the inner directory first. The app depends on the eight `@open-everywhere/*` libraries at
 this CLI's own version — plus this package itself, as a dev dependency, for its `check` script — and
 on `eve` at the pin core declares; its `postinstall` applies the eve patch. Its roster mounts the launch surfaces: Slack, Notion and GitHub. The app carries `AGENTS.md`,
 a `.mcp.json` for the `open-everywhere-ops` MCP server and the `quickstart-open-everywhere` skill,
@@ -42,7 +73,10 @@ npx @open-everywhere/create --check
 `--check` prompts for nothing, changes nothing, sends no telemetry and never scaffolds. It reports
 each setup step with what is missing and the next command for it. Add `--json` for the same report
 as one JSON object, which is what an agent-driven setup reads. `--route docker` judges against the
-Docker route (the default is `vercel`), and `--host https://<host>` probes a deployment.
+Docker route (the default is `vercel`), and `--host https://<host>` probes a deployment. With
+`--host`, the env step also reads the deployment's public status route (`/eve/v1/oe/status`), so a
+value set only on the deployment (in the Vercel dashboard, say) counts. Without it, the step reads
+only `.env.local` and the shell.
 
 Run it from inside an Open Everywhere app — a scaffolded one, or a clone of the repository. From a
 directory that is not an app, it reports an unsatisfied repo step and tells you to scaffold one.
@@ -51,7 +85,13 @@ The same step list written out for a human is
 [Setup steps](https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/setup-steps.md).
 That page is generated from the step list this command reports, so the two cannot drift.
 
-This CLI starts on Node 18 or newer. The app it scaffolds needs Node 24.
+This CLI starts on Node 18 or newer, so `--check` can report an old Node. The app it scaffolds needs
+Node 24, so a scaffold on an older Node exits non-zero and writes nothing.
+
+The scaffolded app sends anonymous usage telemetry when it runs, ON by default. Its `README.md`
+says how to turn it off (`OE_TELEMETRY=off` on the deployment), and the full disclosure is
+[Telemetry](https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/telemetry.md).
+This CLI itself sends none.
 
 ## Docs
 
@@ -61,8 +101,8 @@ This CLI starts on Node 18 or newer. The app it scaffolds needs Node 24.
 
 ## Status
 
-The 0.1 line is the first public release. It is pre-1.0: the API surface is expected to
-change, and a minor release may break you. Pin an exact version.
+This package is pre-1.0: the API surface is expected to change, and a minor release may
+break you. Pin an exact version.
 
 ## Licence
 

package/bin/create-open-everywhere.js

@@ -11,6 +11,10 @@
 // and `npm create @open-everywhere` resolves it there. The bin keeps the command name a scaffolded
 // app's `check` script already runs. One bin is declared, so `npm exec` picks it either way.
 //
+// THE NODE GATE IS NOT HERE. The scaffold refuses a Node below core's range (src/cli.ts
+// `scaffoldNodeRefusal`, OPE-2399), and `--check` must still run on that Node to report it. Both
+// need the parsed argv, so the gate lives in the TS entry, which tsx runs on any Node it supports.
+//
 // WHAT IT WRITES. With a `<dir>` argument it SCAFFOLDS, and that is the only write: it copies the
 // quickstart app (`template/`) into a new or empty `<dir>` (`src/scaffold.ts`) and prints the next
 // steps. With `--check` it only REPORTS on the current directory — every step is a pure `check()`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-everywhere/create",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "type": "module",
   "description": "npx scaffold and setup check for Open Everywhere — one step engine, reported by --check for an agent-led setup.",
@@ -46,8 +46,8 @@
     "test:env-pipe": "tsx scripts/env-pipe-test.ts"
   },
   "dependencies": {
-    "@open-everywhere/core": "0.2.1",
-    "@open-everywhere/provider-slack": "0.2.1",
+    "@open-everywhere/core": "0.4.0",
+    "@open-everywhere/provider-slack": "0.4.0",
     "tsx": "^4.23.9"
   },
   "devDependencies": {

package/src/cli.ts

@@ -5,7 +5,8 @@
 // TWO JOBS, AND NOTHING ELSE (OPE-2233):
 //   1. `<dir>` SCAFFOLDS the quickstart app (scaffold.ts) and prints what to do next.
 //   2. `--check [--json]` REPORTS the setup steps for the current directory. Pure `check()` calls:
-//      no prompts, no writes, no network except the `--host` deploy probe, and no telemetry.
+//      no prompts, no writes, no network except the two `--host` reads (the deploy probe and the
+//      status route), and no telemetry. A scaffold on a Node below core's range is refused (OPE-2399).
 //
 // 🔴 THERE IS NO INTERACTIVE WIZARD, AND THIS CLI SENDS NO TELEMETRY. The TTY wizard is retired:
 // setup is AGENT-LED (open the app in a coding agent, which reads AGENTS.md and drives the
@@ -17,8 +18,9 @@
 import { checkAll, isSetupRoute, SETUP_ROUTES, type SetupRoute, type StepContext } from "./engine.js";
 import { SETUP_STEPS } from "./steps/index.js";
 import { CLI_VERSION } from "./version.js";
-import { initGitRepo, scaffoldApp, ScaffoldRefusal } from "./scaffold.js";
+import { initGitRepo, nestedNameRefusal, scaffoldApp, ScaffoldRefusal } from "./scaffold.js";
 import { resolve } from "node:path";
+import { coreNodeRange, nodeRangeSatisfied } from "@open-everywhere/core/agent/ops/package-info.js";
 import { pathToFileURL } from "node:url";
 import { slackAppNameProblem } from "@open-everywhere/provider-slack/agent/app-manifest.js";
 import { readAppNaming } from "./app-naming.js";
@@ -39,7 +41,8 @@ const USAGE = `create-open-everywhere [<dir>] [--check [--json]] [--route vercel
                  two supported routes. A local run is the development loop
                  after a deploy, never a route.
   --host <url>   The deployment's public origin. The build + deploy step
-                 probes its Slack route.
+                 probes its Slack route, and the env step reads the env
+                 verdicts its status route (/eve/v1/oe/status) reports.
   --app-name <name>
                  The Slack app's name in the manifest the Slack step prints.
                  Default: the app's identity.name setting, else "Open
@@ -181,6 +184,26 @@ function runScaffold(target: string): string | undefined {
   }
 }
 
+/**
+ * The scaffold's Node gate (OPE-2399). The app needs the Node range `@open-everywhere/core` declares,
+ * and a scaffold on an older Node used to succeed with only npm's EBADENGINE warnings, so the person
+ * met the failure later and further from its cause. The gate refuses BEFORE a byte is written.
+ *
+ * It gates the scaffold only. `--check` still runs on an old Node, because its prerequisites step is
+ * the report that says which Node to install. An unreadable range does not block: the
+ * prerequisites step reports that case as "cannot tell".
+ */
+export function scaffoldNodeRefusal(version: string, range: string | undefined): string | undefined {
+  if (range === undefined || nodeRangeSatisfied(range, version) !== false) return undefined;
+  return `refusing to scaffold: Open Everywhere needs Node ${range} (found ${version}). Run \`nvm install 24 && nvm use 24\`, then run this command again.`;
+}
+
+/** What `main` reads from the process, injectable so a test can drive any Node version. */
+export interface MainOptions {
+  readonly nodeVersion?: string;
+  readonly nodeRange?: string;
+}
+
 /** What to do after a scaffold. The scaffold never prompts, so this is always printed. */
 function nextSteps(target: string): string {
   return [
@@ -197,7 +220,7 @@ function nextSteps(target: string): string {
   ].join("\n");
 }
 
-export async function main(argv: readonly string[]): Promise<number> {
+export async function main(argv: readonly string[], options: MainOptions = {}): Promise<number> {
   if (argv.includes("--help") || argv.includes("-h")) {
     console.log(USAGE);
     return 0;
@@ -226,6 +249,16 @@ export async function main(argv: readonly string[]): Promise<number> {
     console.error("--check changes nothing, so it cannot scaffold. Scaffold first, then run --check from inside the app.");
     return 2;
   }
+  const nodeRefusal = scaffoldNodeRefusal(options.nodeVersion ?? process.versions.node, "nodeRange" in options ? options.nodeRange : coreNodeRange());
+  if (nodeRefusal !== undefined) {
+    console.error(nodeRefusal);
+    return 1;
+  }
+  const nested = nestedNameRefusal(target, process.cwd());
+  if (nested !== undefined) {
+    console.error(nested);
+    return 1;
+  }
   const dir = runScaffold(target);
   if (dir === undefined) return 1;
   console.log(nextSteps(target));

package/src/deploy-status.ts

@@ -0,0 +1,84 @@
+// The deployment's own env verdicts — `GET <host>/eve/v1/oe/status` (OPE-2399).
+//
+// `--check` reads `.env.local` and this shell. A Vercel app whose values were set in the dashboard
+// holds them only on the deployment, so the env step read it as all-missing. With `--host`, the env
+// step also reads the deployment's public status route and reports the verdicts the deployment gives
+// for its own environment. The route is unauthenticated by design and carries only closed-vocabulary
+// verdicts plus prose core wrote (packages/core/agent/ops/status.ts), so no secret crosses here.
+//
+// This module imports nothing from core. The route path is a copy of core's `OE_STATUS_PATH`, and
+// scripts/engine-test.ts fails when the two differ: importing `ops/status.ts` would pull the
+// access, sandbox and store resolvers into a CLI that must start before anything is configured.
+
+/** The status route. A COPY of core's `OE_STATUS_PATH` — engine-test.ts pins the two equal. */
+export const DEPLOY_STATUS_PATH = "/eve/v1/oe/status";
+
+/**
+ * The status rows that judge the deployment's ENVIRONMENT, in the order the env step reports them.
+ * `secrets` is the root-of-trust pair (DATABASE_URL and the credential key), `postgres` is the
+ * store selection that DATABASE_URL drives, and `model-route` is the gateway. The other rows (Node,
+ * sandbox, egress, workflow storage, public URL) judge the host, not the env checklist.
+ */
+export const DEPLOYED_ENV_REQUIREMENTS = ["secrets", "postgres", "model-route"] as const;
+
+export type Verdict = "yes" | "no" | "unknown";
+
+export interface DeployedRequirement {
+  readonly id: string;
+  readonly met: Verdict;
+  readonly detail: string;
+}
+
+export type DeployedStatusRead =
+  | { readonly ok: true; readonly url: string; readonly requirements: readonly DeployedRequirement[] }
+  | { readonly ok: false; readonly url: string; readonly detail: string };
+
+const VERDICTS: readonly string[] = ["yes", "no", "unknown"];
+
+/** The rows of a status document, or `undefined` when the body is not one. */
+export function parseStatusRequirements(body: unknown): DeployedRequirement[] | undefined {
+  if (typeof body !== "object" || body === null) return undefined;
+  const rows = (body as { requirements?: unknown }).requirements;
+  if (!Array.isArray(rows)) return undefined;
+  const out: DeployedRequirement[] = [];
+  for (const row of rows) {
+    if (typeof row !== "object" || row === null) return undefined;
+    const { id, met, detail } = row as Record<string, unknown>;
+    if (typeof id !== "string" || typeof met !== "string" || !VERDICTS.includes(met)) return undefined;
+    out.push({ id, met: met as Verdict, detail: typeof detail === "string" ? detail : "" });
+  }
+  return out;
+}
+
+/** Read the deployment's status document. One GET, no retry: the deploy probe owns cold starts. */
+export async function readDeployedStatus(origin: string, fetchImpl: typeof fetch = fetch, timeoutMs = 15_000): Promise<DeployedStatusRead> {
+  const url = `${origin}${DEPLOY_STATUS_PATH}`;
+  let res: Response;
+  try {
+    res = await fetchImpl(url, { method: "GET", signal: AbortSignal.timeout(timeoutMs), redirect: "manual" });
+  } catch (err) {
+    return { ok: false, url, detail: `${url} did not answer (${err instanceof Error ? err.message : String(err)})` };
+  }
+  if (res.status !== 200) return { ok: false, url, detail: `${url} answered ${res.status}, not the status document` };
+  let body: unknown;
+  try {
+    body = JSON.parse(await res.text());
+  } catch {
+    return { ok: false, url, detail: `${url} answered 200, but the body is not JSON` };
+  }
+  const requirements = parseStatusRequirements(body);
+  if (requirements === undefined) return { ok: false, url, detail: `${url} answered 200, but the body is not a status document` };
+  return { ok: true, url, requirements };
+}
+
+/**
+ * The env step's verdict from a status document. Satisfied when the deployment reports `secrets`
+ * as "yes" and no env row as "no". An "unknown" row does not fail the step: the route uses it for
+ * "not measured" (no probe registered), never for "probably not". An absent row counts as unknown.
+ */
+export function deployedEnvVerdict(requirements: readonly DeployedRequirement[]): { satisfied: boolean; summary: string } {
+  const byId = new Map(requirements.map((r) => [r.id, r]));
+  const rows = DEPLOYED_ENV_REQUIREMENTS.map((id) => byId.get(id) ?? { id, met: "unknown" as const, detail: "not in the document" });
+  const satisfied = byId.get("secrets")?.met === "yes" && rows.every((r) => r.met !== "no");
+  return { satisfied, summary: rows.map((r) => `${r.id}=${r.met} (${r.detail})`).join("; ") };
+}

package/src/engine.ts

@@ -6,8 +6,9 @@
 //
 // 🔴 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
+// and runs the commands with the user's consent. The ops MCP server's `scaffold_env` /
+// `scaffold_credential_key` tools and the person's own `oe env set <NAME>` (every secret value,
+// OPE-2396) 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,
@@ -39,7 +40,7 @@ export interface StepContext {
   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. */
+  /** The deployment's public origin (`--host`), for the deploy probe and the env step's status read. */
   readonly host?: string;
   /** The chat app's name (`--app-name`), for the Slack manifest. It wins over {@link agentName}. */
   readonly appName?: string;

package/src/env-file.ts

@@ -1,10 +1,11 @@
 // 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.
+// `automate()` steps called. Setup is agent-led now, and two doors write `.env.local`: the ops MCP
+// server's `scaffold_env` tool (non-secret config) and `oe env set <NAME>` (a secret, typed in the
+// person's own terminal — OPE-2396). Both pass one gate on the target filename, so a value can never
+// land in a tracked file (core agent/ops/quickstart.ts § envFileTargetRefusal). A third 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.
@@ -41,13 +42,14 @@ export function isSet(v: string | undefined): boolean {
 }
 
 /**
- * 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.
+ * What a "missing" detail adds (OPE-2222). Without `--host`, `--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. It names `--host` instead, which reads the
+ * deployment's public status route (OPE-2399, deploy-status.ts).
  */
 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})`;
+  return `Did you set these on ${where} instead? Re-run with --host https://<host>: the env step then also reads the deployment's own verdicts from its status route. Without --host it reads only .env.local and this shell (${list})`;
 }

package/src/scaffold.ts

@@ -99,6 +99,27 @@ export function isScaffoldableDir(dir: string): boolean {
   return readdirSync(dir).every((name) => name === ".git");
 }
 
+/**
+ * The nested-name case (OPE-2399). A person who clones an empty repository named `my-agent`, enters
+ * it, and runs `npx @open-everywhere/create my-agent` gets `my-agent/my-agent/`. The scaffold is
+ * correct, but it is almost never what the person wanted. So when the target is a direct child of
+ * `cwd` with the same name, and `cwd` counts as empty (see {@link isScaffoldableDir}), this returns
+ * a refusal that names the `.` command. A person who does want the nested directory creates it
+ * first: `cwd` then holds it, is no longer empty, and the refusal does not apply.
+ */
+export function nestedNameRefusal(target: string, cwd: string): string | undefined {
+  const dir = resolve(cwd, target);
+  const here = resolve(cwd);
+  if (resolve(dir, "..") !== here || basename(dir) !== basename(here)) return undefined;
+  if (!isScaffoldableDir(here)) return undefined;
+  return [
+    `refusing to scaffold: you are inside an empty directory named "${basename(here)}", so this would create ${basename(here)}/${basename(dir)}/.`,
+    "To scaffold into this directory, run:",
+    "  npx @open-everywhere/create .",
+    `To nest the app on purpose, create the directory first (\`mkdir ${basename(dir)}\`), then run this command again.`,
+  ].join("\n");
+}
+
 /**
  * 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

package/src/steps/database.ts

@@ -30,7 +30,8 @@ function postgresResolution(env: NodeJS.ProcessEnv): { operational: boolean; mem
 
 /** 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';
+  const write =
+    "ask the person to run `npx oe env set DATABASE_URL` in their own terminal and paste the connection string at its hidden prompt — 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}`;
@@ -72,9 +73,9 @@ export const databaseStep: SetupStep = {
       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."
+          ? "`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. The integration can also enable Neon Auth (NEON_AUTH_BASE_URL, VITE_NEON_AUTH_URL): Open Everywhere does not use it, so leave it off, or ignore those two variables."
           : "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.",
+        "Write the same connection string into .env.local with `npx oe env set DATABASE_URL`, run in your own terminal: it reads the value from a hidden prompt. 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, and never pass it to an ops tool.",
         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.",

package/src/steps/env-checklist.ts

@@ -12,22 +12,40 @@
 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";
+import { normalizeHost } from "../deploy-probe.js";
+import { deployedEnvVerdict, readDeployedStatus } from "../deploy-status.js";
 
 export const envChecklistStep: SetupStep = {
   id: "env-checklist",
   title: "Env var checklist",
-  check(ctx: StepContext) {
+  // WITH `--host`, THE DEPLOYMENT'S OWN VERDICT COUNTS TOO (OPE-2399). A Vercel app configured in
+  // the dashboard holds its values only on the deployment, so the local reading alone said
+  // "all missing". The step then reads the public status route (deploy-status.ts). Either reading
+  // can satisfy the step, and the detail names which one did. A status route that cannot be read
+  // leaves the local verdict as it was and says why.
+  async check(ctx: StepContext) {
     const env = mergedEnv(ctx.cwd, ctx.env) as NodeJS.ProcessEnv;
     const route = routeOf(ctx);
     const { checks, ready } = preflight(env, { target: route });
+    if (ready) return { satisfied: true, detail: `all required env vars present for the ${route} 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(" · "),
-    };
+    const localMiss = `missing from .env.local and this shell: ${missing.map((c) => c.name).join(", ")}`;
+    const localNext = missing.map((c) => c.fix).filter((f): f is string => Boolean(f)).join(" · ");
+    const origin = ctx.host === undefined ? undefined : normalizeHost(ctx.host);
+    if (origin === undefined) return { satisfied: false, detail: `${localMiss}. ${missNote(route)}`, next: localNext };
+    const read = await readDeployedStatus(origin);
+    if (!read.ok) return { satisfied: false, detail: `${localMiss}. The deployment's own verdicts could not be read: ${read.detail}`, next: localNext };
+    const deployed = deployedEnvVerdict(read.requirements);
+    return deployed.satisfied
+      ? {
+          satisfied: true,
+          detail: `the deployment reports its env as set (${read.url}): ${deployed.summary}. The local reading differs (${localMiss}); that is expected when the values live only on the deployment`,
+        }
+      : {
+          satisfied: false,
+          detail: `the deployment reports its env as NOT set (${read.url}): ${deployed.summary}. Locally, ${localMiss}`,
+          next: localNext,
+        };
   },
   // 🔴 `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
@@ -48,7 +66,8 @@ export const envChecklistStep: SetupStep = {
           : "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.",
+        "Run `npx @open-everywhere/create --check --json`, or the ops tool `preflight`, for the live verdict per name. Both read .env.local and the shell only.",
+        "Set the values on the deployment instead (the Vercel dashboard, say)? Add `--host https://<host>`: the step then also reads the deployment's own verdicts from its public `/eve/v1/oe/status` route.",
       ],
     };
   },

package/src/steps/slack.ts

@@ -27,6 +27,9 @@ import { isSet, mergedEnv, missNote } from "../env-file.js";
 
 const SLACK_ENV = ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"] as const;
 
+/** The project mark: the agent's default avatar when identity.name is unset (OPE-2408). */
+const PROJECT_MARK_URL = "https://raw.githubusercontent.com/open-everywhere/open-everywhere/main/brand/png/mark-square-1024.png";
+
 export const slackStep: SetupStep = {
   id: "slack",
   title: "Slack app",
@@ -51,7 +54,7 @@ export const slackStep: SetupStep = {
       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`",
+        "returns, then have the person run `npx oe env set SLACK_BOT_TOKEN` and `npx oe env set SLACK_SIGNING_SECRET` in their own terminal",
     };
   },
   guide(ctx: StepContext) {
@@ -75,8 +78,14 @@ export const slackStep: SetupStep = {
               : "the default — set identity.name in agent/settings/settings.ts to name it"
         }). 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.",
+        // OPE-2408: with no name configured the agent presents as the project, so the project mark is its avatar.
+        `Basic Information → Display Information → App icon: ${
+          ctx.appName === undefined && ctx.agentName === undefined
+            ? "upload the project mark"
+            : "upload your own icon, or the project mark"
+        }, ${PROJECT_MARK_URL}. Slack's manifest has no icon field, so this step stays by hand.`,
         "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.",
+        "Write both with `npx oe env set SLACK_BOT_TOKEN` and `npx oe env set SLACK_SIGNING_SECRET`, run in your own terminal: each reads the value from a hidden prompt. Never paste a secret into the chat, and never pass one to an ops tool.",
         "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).",

package/template/.env.example

@@ -18,7 +18,7 @@ AI_GATEWAY_API_KEY=
 # replaced Docker container starts from an empty volume, so without it core throws at the first
 # store or DM-memory use. On the Vercel route add Neon from the Marketplace
 # (`npx vercel install neon`, or project -> Storage -> Neon -> Connect): it sets DATABASE_URL on the
-# project. Copy the same value here so the operator tools (`npx oe secret`, the ops server's
+# project. Copy the same value here (`npx oe env set DATABASE_URL`, in your own terminal) so the operator tools (`npx oe secret`, the ops server's
 # `secret_set`) write the store the deployment reads. A local run needs nothing: it uses an embedded
 # database under .open-everywhere-data/.
 DATABASE_URL=
@@ -38,6 +38,15 @@ DATABASE_URL=
 # whose credential names `broker: "db"` in the encrypted store. The Slack variables and
 # GITHUB_WEBHOOK_SECRET below are read from the ENVIRONMENT only, so they stay environment variables.
 
+# --- Telemetry (https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/telemetry.md) ---
+# The deployed app sends ANONYMOUS USAGE TELEMETRY, ON BY DEFAULT: event names, enums, coarse
+# buckets, public model ids and the app version, with a random per-install id (service.instance.id).
+# Never message or memory content, org names, workspace, channel, user or session ids, or env
+# values. The page above lists every event. To turn it
+# off, set this ON THE DEPLOYMENT (the Vercel project or the container's environment): a value here
+# only reaches a local run, because .env.local never ships. DO_NOT_TRACK=1 does the same.
+# OE_TELEMETRY=off
+
 # --- Slack (https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/surfaces/slack.md) ---
 # Slack app -> OAuth & Permissions -> Bot User OAuth Token (xoxb-…).
 SLACK_BOT_TOKEN=

package/template/AGENTS.md

@@ -17,17 +17,31 @@ Setup is yours to drive, with the user's consent at every command. Use the
 - **Never propose a local run as a setup step.** `npm run dev` is the development loop after the
   deploy — changing tools and skills, evals, debugging a turn. A local run has no public HTTPS URL
   for Slack to reach and a different store, so it proves little about the deployment.
-- **Never ask the user to paste a secret into the chat.** They paste it where a tool reads it; you
-  write it with `scaffold_env`, or mint it with `scaffold_credential_key`, which never prints it.
+- **Never ask the user to paste a secret into the chat, and never pass one to a tool.** The user
+  types each secret into their own terminal with `npx oe env set <NAME>` (a hidden prompt into
+  `.env.local`). You handle names only: `scaffold_env { secretNames }` gives the command per name,
+  and `scaffold_credential_key` mints the store key without printing it.
+- **Tell the user about telemetry before the first deploy.** The deployed app sends anonymous usage
+  telemetry, and it is ON by default: event names, enums, coarse buckets, public model ids and the
+  app version, with a random per-install id (`service.instance.id`). It never sends message or
+  memory content, org names, workspace, channel, user or session ids, or env values. To turn it off, they set `OE_TELEMETRY=off` (or
+  `DO_NOT_TRACK=1`) on the deployment itself. The full list of events is
+  `https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/telemetry.md`. Ask which
+  they want, and do not decide for them.
 - `npx @open-everywhere/create --check --json` is the status report: every step, with `satisfied`,
   `detail` and a `next` command. Add `--route docker` for the Docker route and
-  `--host https://<host>` to probe a deployment. The human-readable version of the same step list is
+  `--host https://<host>` to probe a deployment and read the env verdicts it reports for itself. The human-readable version of the same step list is
   `https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/setup-steps.md`.
 
 ## Where things live
 
 - `roster.config.ts` — what the agent can do. `roster.lock.json` is the reviewed roll-call of every
   contribution. Both are committed.
+- `scripts/goldens/roster-plan.txt` — the roster review surface: one line per slot file `oe build`
+  writes, with the package that mounts it. The slot tree is not committed, so this file is how a
+  pull request shows what the agent gains or loses. `oe build` keeps it current, and
+  `npx oe build --check` fails when it differs from the plan. Commit it, and read its diff with the
+  lock's. Never edit it by hand.
 - `agent/agent.ts` — the eve agent definition.
 - `agent/` — the config: access bundles, identity and trust, memory domains, models, settings, spend
   caps, webhooks. Each file's header says what it controls.