@kybernesis/create 0.4.0 → 0.5.0

package/dist/doctor.js

@@ -90,24 +90,39 @@ export async function doctor() {
         add("warn", "KYBERNESIS_ISSUER not set", "agent is not control-plane governed");
     }
     // ── slack ──────────────────────────────────────────────────────────────
-    if (env.SLACK_CONNECTOR_UID)
-        add("pass", `Slack connector uid: ${env.SLACK_CONNECTOR_UID}`, "verify trigger path /eve/v1/slack (vercel connect list)");
-    else
-        add("warn", "SLACK_CONNECTOR_UID not set", "vercel connect create slack --triggers");
+    // Only relevant when the agent actually has a Slack channel — a client on
+    // iMessage or Telegram should never be told to create a Slack connector.
+    const hasSlackChannel = existsSync(join(cwd, "agent/channels/slack.ts"));
+    if (hasSlackChannel) {
+        if (env.SLACK_CONNECTOR_UID)
+            add("pass", `Slack connector uid: ${env.SLACK_CONNECTOR_UID}`, "verify trigger path /eve/v1/slack (vercel connect list)");
+        else if (env.SLACK_BOT_TOKEN)
+            add("pass", "Slack via portable credentials (SLACK_BOT_TOKEN)");
+        else
+            add("warn", "Slack channel present but no credentials", "SLACK_CONNECTOR_UID (Vercel) or SLACK_BOT_TOKEN (portable)");
+    }
     // ── engineer layer (optional — checked only when installed) ────────────
     const hasEngineer = Boolean(deps["@kybernesis/engineer"]) || existsSync(join(cwd, "agent/extensions/engineer.ts"));
     if (hasEngineer) {
         add("pass", `@kybernesis/engineer ${deps["@kybernesis/engineer"] ?? "(extension file present)"}`);
-        if (existsSync(join(cwd, "agent/sandbox/sandbox.ts")))
-            add("pass", "workshop sandbox file present");
-        else
-            add("fail", "agent/sandbox/sandbox.ts missing", "eve add @kybernesis/engineer --overwrite writes it");
-        if (env.BLOB_READ_WRITE_TOKEN)
-            add("pass", "file delivery configured (BLOB_READ_WRITE_TOKEN)");
-        else
-            add("warn", "BLOB_READ_WRITE_TOKEN not set — deliver tool will fail", "vercel blob create-store <name>-deliverables --access public --yes");
+        // The workshop may sit on the root OR on the engineer subagent (the
+        // scoped pattern). Either is valid; neither is not.
+        const rootSandbox = existsSync(join(cwd, "agent/sandbox/sandbox.ts"));
+        const builderSandbox = existsSync(join(cwd, "agent/subagents/builder/sandbox/sandbox.ts"));
+        if (rootSandbox || builderSandbox) {
+            add("pass", `workshop sandbox present (${builderSandbox ? "engineer subagent" : "root agent"})`);
+        }
+        else {
+            add("fail", "no workshop sandbox", "the engineer layer needs one — on the root or on agent/subagents/builder/");
+        }
         const vercelConn = join(cwd, "agent/connections/vercel.ts");
-        if (existsSync(vercelConn)) {
+        const selfHostedAgent = Boolean(deps["@kybernesis/exe"]) ||
+            (existsSync(join(cwd, "agent/subagents/builder/sandbox/sandbox.ts")) &&
+                readFileSync(join(cwd, "agent/subagents/builder/sandbox/sandbox.ts"), "utf8").includes("docker("));
+        if (selfHostedAgent && !existsSync(vercelConn)) {
+            add("pass", "no Vercel MCP connection (self-hosted)", "public deploys need the CLIENT's own Vercel token — Vercel Connect does not work off-Vercel");
+        }
+        else if (existsSync(vercelConn)) {
             const src = readFileSync(vercelConn, "utf8");
             const uid = /connect\(\s*"([^"]+)"/.exec(src)?.[1];
             if (uid && uid.includes("/"))
@@ -118,10 +133,12 @@ export async function doctor() {
         else {
             add("warn", "agent/connections/vercel.ts missing — no preview deploys/link-back", "eve add connection/vercel, then vercel connect create + attach");
         }
-        if (env.VERCEL_OIDC_TOKEN || env.VERCEL_TOKEN)
-            add("pass", "Vercel credentials for local hosted sandboxes");
-        else
-            add("warn", "no VERCEL_OIDC_TOKEN — local sandbox/eval runs cannot reach Vercel Sandbox", "vercel link && vercel env pull");
+        if (!selfHostedAgent) {
+            if (env.VERCEL_OIDC_TOKEN || env.VERCEL_TOKEN)
+                add("pass", "Vercel credentials for local hosted sandboxes");
+            else
+                add("warn", "no VERCEL_OIDC_TOKEN — local sandbox/eval runs cannot reach Vercel Sandbox", "vercel link && vercel env pull");
+        }
     }
     // ── dispatch edges (agent-to-agent — checked only when present) ────────
     const subagentsDir = join(cwd, "agent/subagents");
@@ -168,6 +185,69 @@ export async function doctor() {
             add("warn", "@kybernesis/dispatch installed but no edges or dispatch channel found", "see the connect-agents skill");
         }
     }
+    // ── self-hosted agents (host !== Vercel) ───────────────────────────────
+    // Every check here cost a real debugging session on the first exe.dev
+    // deployment. None of them are theoretical.
+    const selfHosted = Boolean(deps["@kybernesis/exe"]) ||
+        existsSync(join(cwd, "agent/sandbox/sandbox.ts")) &&
+            readFileSync(join(cwd, "agent/sandbox/sandbox.ts"), "utf8").includes("docker(");
+    if (selfHosted) {
+        // Vercel Connect needs Vercel OIDC — it CANNOT work off-Vercel, for Slack,
+        // the Vercel MCP connection, or anything else. Every such connection has to
+        // become a static credential the client issues.
+        const connectUsers = [];
+        for (const dir of ["agent/channels", "agent/connections"]) {
+            const full = join(cwd, dir);
+            if (!existsSync(full))
+                continue;
+            for (const f of readdirSync(full)) {
+                const file = join(full, f);
+                if (!f.endsWith(".ts"))
+                    continue;
+                if (readFileSync(file, "utf8").includes("@vercel/connect"))
+                    connectUsers.push(`${dir}/${f}`);
+            }
+        }
+        if (connectUsers.length) {
+            add("fail", `Vercel Connect used off-Vercel: ${connectUsers.join(", ")}`, "Connect authenticates via Vercel OIDC, which does not exist on this host — the agent will fail to boot. Switch to portable/static credentials");
+        }
+        else {
+            add("pass", "no Vercel Connect dependencies (correct for a self-hosted agent)");
+        }
+        // eve start does not read .env.local the way eve dev does.
+        add("warn", "self-hosted: export .env.local into the server process", "eve start does NOT read it; use the supervision script from @kybernesis/exe (scripts/eve-server.sh)");
+        // Prewarm runs in the eve CLI, not the built server.
+        add("warn", "self-hosted: start via `npx eve start`, not `node .output/server/index.mjs`", "sandbox templates are prewarmed by the CLI; starting the server directly skips prewarm and every sandbox tool fails with SandboxTemplateNotProvisionedError");
+    }
+    // ── engineer subagent (build capability scoped to a subagent) ──────────
+    const builderDir = join(cwd, "agent/subagents/builder");
+    if (existsSync(builderDir)) {
+        // Subagents own their sandbox — they do NOT inherit the root's. Without one
+        // the builder gets a bare template and every screenshot fails with
+        // "Cannot find module 'playwright'" while the root's template is fine.
+        if (existsSync(join(builderDir, "sandbox/sandbox.ts"))) {
+            add("pass", "engineer subagent has its own workshop sandbox");
+        }
+        else {
+            add("fail", "engineer subagent has NO sandbox of its own", "subagents do not inherit the root sandbox — add agent/subagents/builder/sandbox/sandbox.ts or the vision loop cannot run");
+        }
+        if (existsSync(join(builderDir, "extensions/engineer.ts"))) {
+            add("pass", "engineer mounted locally on the subagent (root keeps no shell)");
+        }
+        else {
+            add("warn", "engineer extension not mounted on the subagent", "agent/subagents/builder/extensions/engineer.ts");
+        }
+        // Delivery: either storage works, or the agent cannot hand over artifacts.
+        if (env.BLOB_READ_WRITE_TOKEN) {
+            add("pass", "file delivery via Vercel Blob");
+        }
+        else if (env.DELIVER_DIR && env.DELIVER_BASE_URL) {
+            add("pass", `file delivery via host directory (${env.DELIVER_DIR})`);
+        }
+        else {
+            add("warn", "file delivery not configured — the agent cannot hand over artifacts", "set BLOB_READ_WRITE_TOKEN (the CLIENT's blob store) or DELIVER_DIR + DELIVER_BASE_URL");
+        }
+    }
     // ── eve discovery + local port ─────────────────────────────────────────
     const info = capture("npx", ["eve", "info"], cwd);
     if (info === null)

package/dist/init.js

@@ -1,7 +1,7 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { DEFAULT_ISSUER, EVE_VERSION, REGISTRY_URL, ask, bold, closePrompts, dim, green, run, slug, yellow, } from "./util.js";
-import { CHANNEL_KINDS, channelPlan, envExample, evalFileTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
+import { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
 import { suiteDir } from "./skills.js";
 /**
  * The always-installed core. Everything else — channels, subagents, engineer,
@@ -9,11 +9,11 @@ import { suiteDir } from "./skills.js";
  * AND undoes real setup work (an Arcana workspace + scoped key per subagent).
  */
 const CORE_ITEMS = ["enterprise", "arcana", "evals"];
-const ENGINEER_OFFICIAL_ITEMS = [
-    "extension/agent-browser",
-    "extension/github-tools",
-    "connection/vercel",
-];
+// Official eve-registry limbs installed with the engineer subagent.
+// connection/vercel is Vercel-Connect-backed, so it is VERCEL-HOST ONLY: on a
+// self-hosted agent it cannot get an OIDC token and the agent fails to boot.
+const ENGINEER_ITEMS_ALL = ["extension/agent-browser", "extension/github-tools"];
+const ENGINEER_ITEMS_VERCEL = ["connection/vercel"];
 const DEFAULT_MODEL = "anthropic/claude-sonnet-5";
 export async function init(rawName, options = {}) {
     const engineer = options.engineer === true;
@@ -70,10 +70,12 @@ export async function init(rawName, options = {}) {
     for (const item of plan.registryItems) {
         run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
     }
-    if (engineer) {
-        console.log(bold("\n2c   Engineer layer: workshop sandbox + vision dev loop …"));
-        run("npx", ["eve", "add", "@kybernesis/engineer", "--overwrite"], { cwd: dir });
-        for (const item of ENGINEER_OFFICIAL_ITEMS) {
+    const engPlan = engineer ? engineerPlan(host, DEFAULT_MODEL) : null;
+    if (engPlan) {
+        console.log(bold("\n2c   Engineer subagent: workshop sandbox + vision dev loop …"));
+        run("npm", ["install", ...engPlan.deps, "--no-audit", "--no-fund"], { cwd: dir, allowFail: true });
+        const engItems = [...ENGINEER_ITEMS_ALL, ...(host === "vercel" ? ENGINEER_ITEMS_VERCEL : [])];
+        for (const item of engItems) {
             const ok = run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
             if (!ok)
                 console.log(yellow(`  ! ${item} did not install cleanly — re-run: npx eve add ${item}`));
@@ -121,6 +123,13 @@ export async function init(rawName, options = {}) {
             }
         }
     }
+    if (engPlan) {
+        for (const file of engPlan.files) {
+            const full = join(dir, file.path);
+            mkdirSync(join(full, ".."), { recursive: true });
+            writeFileSync(full, file.content);
+        }
+    }
     console.log(bold("\n5/6  Env template + hermetic eval script …"));
     writeFileSync(join(dir, ".env.example"), envExample(name, depts, issuer, plan.env));
     const pkgPath = join(dir, "package.json");
@@ -139,13 +148,14 @@ export async function init(rawName, options = {}) {
         "self-testing (evals)",
         channel === "none" ? null : `${channel} channel`,
         host === "exe" ? "exe.dev host" : null,
-        engineer ? "engineer (workshop + vision loop)" : null,
+        engineer ? "engineer subagent (workshop + vision loop)" : null,
         depts.length ? `${depts.length} dept subagent(s)` : null,
     ].filter(Boolean);
     const steps = [
         `Arcana: create workspaces (${name}-company, ${name}-eval${depts.map((d) => `, ${name}-${d}`).join("")}) + scoped kb_ keys; fill .env.local from .env.example`,
         ...hostSteps(host, name),
         ...plan.steps,
+        ...(engPlan?.steps ?? []),
         `Control plane: register agent "${name}" at ${issuer}/agents + grant the pilot cohort`,
         `npm run eval → green → deploy → live smoke + the revoke demo`,
     ];

package/dist/templates.d.ts

@@ -28,3 +28,12 @@ export declare function channelPlan(kind: ChannelKind, name: string, host: HostK
 export type HostKind = "vercel" | "exe";
 export declare function hostAgentTs(host: HostKind, model: string): string;
 export declare function hostSteps(host: HostKind, name: string): string[];
+export interface EngineerPlan {
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    deps: string[];
+    steps: string[];
+}
+export declare function engineerPlan(host: HostKind, model: string): EngineerPlan;

package/dist/templates.js

@@ -334,3 +334,176 @@ export function hostSteps(host, name) {
         `npx eve deploy`,
     ];
 }
+/** The workshop sandbox, per host. Same recipe; different backend. */
+function workshopSandbox(host) {
+    if (host === "exe") {
+        return `import { defineSandbox } from "eve/sandbox";
+import { docker } from "eve/sandbox/docker";
+
+/**
+ * The engineer workshop, self-hosted: pnpm + Playwright + Chromium baked into
+ * the TEMPLATE so warm sessions run render→screenshot→vision in seconds.
+ *
+ * Docker rather than vercel(): the hosted backend needs Vercel OIDC, which does
+ * not exist off-Vercel.
+ *
+ * HOST PREREQUISITE: some images ship Docker disabled (exe.dev's exeuntu runs
+ * \`systemctl disable docker.service\`). Run \`sudo systemctl enable --now docker\`
+ * or every build fails with SandboxTemplateNotProvisionedError.
+ *
+ * NOTE: Docker sessions do not enforce a domain allowlist the way the hosted
+ * backend does. Egress control is the HOST's responsibility here — a deliberate
+ * difference from the Vercel deployment, not an oversight.
+ */
+export default defineSandbox({
+  backend: docker(),
+  revalidationKey: () => "kybernesis-workshop-v5-docker",
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    await sandbox.run({ command: "apt-get update" });
+    await sandbox.run({ command: "npm install -g pnpm" });
+    await sandbox.run({
+      command:
+        "mkdir -p /workspace/.shot && cd /workspace/.shot && echo '{\\"name\\":\\"kyb-shot\\",\\"private\\":true}' > package.json && npm install playwright",
+    });
+    await sandbox.run({
+      command: "cd /workspace/.shot && npx playwright install --with-deps chromium",
+    });
+  },
+});
+`;
+    }
+    return `import { defineSandbox } from "eve/sandbox";
+import { vercel } from "eve/sandbox/vercel";
+
+/**
+ * The engineer workshop: a warm, safe cloud dev machine.
+ *
+ * TEMPLATE bootstrap (once, inherited by every session): pnpm + Playwright +
+ * Chromium. Prewarm runs at deploy time, so a broken bootstrap fails the build
+ * loudly and warm sessions run the full render→screenshot→vision loop in
+ * seconds. Backend PINNED to Vercel Sandbox — hosted sandboxes even from local
+ * dev (run \`vercel link\` + \`vercel env pull\` first), so evals exercise the
+ * exact production backend. No Docker anywhere.
+ *
+ * All sessions run under a domain ALLOWLIST: an agent that installs arbitrary
+ * npm packages must not have open egress. A blocked domain fails loudly;
+ * treat every addition as a security decision.
+ */
+export default defineSandbox({
+  backend: vercel({
+    resources: { vcpus: 4 },
+    networkPolicy: {
+      allow: [
+        "registry.npmjs.org",
+        "*.npmjs.org",
+        "github.com",
+        "api.github.com",
+        "codeload.github.com",
+        "*.githubusercontent.com",
+        "cdn.playwright.dev",
+        "playwright.azureedge.net",
+        "playwright.download.prss.microsoft.com",
+        "storage.googleapis.com",
+        "archive.ubuntu.com",
+        "security.ubuntu.com",
+        "ports.ubuntu.com",
+        "*.ubuntu.com",
+        "deb.debian.org",
+        "security.debian.org",
+        "*.debian.org",
+        "ai-gateway.vercel.sh",
+        "vercel.com",
+        "*.vercel.app",
+        "fonts.googleapis.com",
+        "fonts.gstatic.com",
+      ],
+    },
+  }),
+  revalidationKey: () => "kybernesis-workshop-v5",
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    // The egress proxy carries HTTPS only; apt defaults to http:// mirrors, so
+    // every index fetch silently fails. Rewrite to https first.
+    await sandbox.run({
+      command:
+        "find /etc/apt -type f \\\\( -name '*.list' -o -name '*.sources' \\\\) -exec sed -i 's|http://|https://|g' {} + && apt-get update",
+    });
+    await sandbox.run({ command: "npm install -g pnpm" });
+    await sandbox.run({
+      command:
+        "mkdir -p /workspace/.shot && cd /workspace/.shot && echo '{\\"name\\":\\"kyb-shot\\",\\"private\\":true}' > package.json && npm install playwright",
+    });
+    await sandbox.run({
+      command: "cd /workspace/.shot && npx playwright install --with-deps chromium",
+    });
+  },
+});
+`;
+}
+export function engineerPlan(host, model) {
+    const onExe = host === "exe";
+    const files = [
+        {
+            path: "agent/subagents/builder/agent.ts",
+            content: onExe
+                ? `import { defineAgent } from "eve";
+import { createOpenAI } from "@ai-sdk/openai";
+import { exeModel } from "@kybernesis/exe";
+
+// The specialist the root agent delegates BUILDING to. \`description\` is what
+// the root routes on — keep it about building, not answering.
+export default defineAgent({
+  description:
+    "Builds and runs software: scaffolds projects, writes code, installs dependencies, runs builds and dev servers, and visually verifies rendered pages. Use when the user asks for something to be BUILT, prototyped, deployed, or fixed in code — not for questions, planning, or scheduling.",
+  model: exeModel({ model: process.env.EXE_MODEL ?? ${JSON.stringify(model)}, createOpenAI }),
+  modelContextWindowTokens: 200_000,
+});
+`
+                : `import { defineAgent } from "eve";
+
+// The specialist the root agent delegates BUILDING to. \`description\` is what
+// the root routes on — keep it about building, not answering.
+export default defineAgent({
+  description:
+    "Builds and runs software: scaffolds projects, writes code, installs dependencies, runs builds and dev servers, and visually verifies rendered pages. Use when the user asks for something to be BUILT, prototyped, deployed, or fixed in code — not for questions, planning, or scheduling.",
+  model: ${JSON.stringify(model)},
+});
+`,
+        },
+        {
+            path: "agent/subagents/builder/extensions/engineer.ts",
+            content: `// Engineer layer mounted LOCALLY on this subagent (eve >=0.30): screenshot,
+// deliver, and the trade-school skills belong to \`builder\` alone. The root
+// agent never gets shell or a browser.
+export { default } from "@kybernesis/engineer";
+`,
+        },
+        {
+            path: "agent/subagents/builder/sandbox/sandbox.ts",
+            content: workshopSandbox(host),
+        },
+    ];
+    if (onExe) {
+        files.push({
+            path: "agent/subagents/builder/tools/preview.ts",
+            content: `export { previewTool as default } from "@kybernesis/exe/preview";
+`,
+        });
+    }
+    return {
+        files,
+        deps: onExe ? ["@kybernesis/engineer", "@kybernesis/exe"] : ["@kybernesis/engineer"],
+        steps: onExe
+            ? [
+                "Enable Docker on the host (some images ship it disabled): sudo systemctl enable --now docker",
+                "Preview server (so the agent can show you what it built):\n       mkdir -p ~/preview && setsid python3 -m http.server 3456 --directory ~/preview &\n       then open https://<vm>.exe.xyz:3456/<file> (account-gated, not public)",
+                "File delivery needs object storage: set BLOB_READ_WRITE_TOKEN (Vercel Blob) or DELIVER_DIR + DELIVER_BASE_URL to serve from this host",
+                "Public deploys need the client's own Vercel token — Vercel Connect does NOT work off-Vercel",
+            ]
+            : [
+                "File delivery: vercel blob create-store <name>-deliverables --access public --yes",
+                "Preview deploys: eve add connection/vercel, then vercel connect create mcp.vercel.com --name vercel && vercel connect attach mcp.vercel.com/vercel --yes",
+            ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",

package/skills/self-hosting/SKILL.md

@@ -0,0 +1,96 @@
+---
+description: Use when deploying an eve agent OFF Vercel — on exe.dev, a VPS, or any client infrastructure — or when a client wants to use their own ChatGPT/LLM subscription. Covers what breaks, what replaces it, and the credential checklist.
+---
+
+# Self-hosted agents (client infrastructure, not Vercel)
+
+The Vercel path is the default and the proven one. Reach for this when the
+client **won't or can't use Vercel**, or wants their agent's inference billed to
+a subscription they already pay for.
+
+**The governing rule: everything must come from the CLIENT's accounts.** If a
+step only works because you happen to hold a credential, that step is a bug in
+the deployment, not a shortcut. It will fail on the real engagement.
+
+## Scaffold
+
+```bash
+kyb init <name> --host=exe --channel=<imessage|slack|telegram|none> --engineer
+```
+
+`--host=exe` swaps the bindings; everything else is the same product. Run
+`kyb doctor` after — it knows the self-hosted failure modes below.
+
+## What Vercel gives you that a client host does not
+
+| Capability | On Vercel | Self-hosted replacement |
+| --- | --- | --- |
+| Model access | AI Gateway | exe.dev LLM integration (`exeModel`) — managed, BYO key, or a **ChatGPT subscription** |
+| Slack/Photon/Linear credentials | Vercel Connect | **Portable/static credentials the client issues** |
+| Sandbox | `vercel()` hosted | `docker()` on the host |
+| File delivery | Vercel Blob | Blob **or** `DELIVER_DIR` + `DELIVER_BASE_URL` |
+| Public URLs | deployments | a deploy target, or an account-gated preview |
+| Secrets | Vercel env | host env + the platform's own secret injection |
+
+**Vercel Connect does not work off-Vercel — at all.** It authenticates via
+Vercel OIDC, which does not exist on another host. That applies to Slack, the
+Vercel MCP connection, Linear, everything. Each becomes a static credential
+someone must issue and rotate. `kyb doctor` fails loudly if a `@vercel/connect`
+import survives into a self-hosted agent.
+
+## The failure modes, each of which cost a real session
+
+- **Docker ships disabled on some images.** exe.dev's exeuntu runs
+  `systemctl disable docker.service`, so `docker --version` works while nothing
+  can run. Every sandbox call fails with `SandboxTemplateNotProvisionedError`.
+  Fix: `sudo systemctl enable --now docker`.
+- **Subagents own their sandbox — they do NOT inherit the root's.** An engineer
+  subagent without its own `sandbox/sandbox.ts` gets a bare template, and the
+  screenshot tool fails with `Cannot find module 'playwright'` while the root's
+  template is fine.
+- **`eve start` does not read `.env.local`** the way `eve dev` does. Export it
+  into the process (`scripts/eve-server.sh` in `@kybernesis/exe` does this).
+- **Prewarm lives in the eve CLI, not the built server.** Starting
+  `node .output/server/index.mjs` directly gives you clean logs but skips
+  template prewarm entirely. Start with `npx eve start`.
+- **`localDev()` never authenticates under `eve start`** — it is a property of
+  the deployment, not the request. A self-hosted agent needs a real
+  authenticator from day one.
+- **`pkill -f <pattern>` over SSH kills your own session** when the pattern
+  appears in the SSH command line — and can take the agent with it. Use a
+  pidfile (`scripts/eve-server.sh`).
+- **Never diagnose "nothing is happening" from a log file.** Count runs on disk:
+  `.eve/.workflow-data/runs/`. A log can look frozen at boot while the agent
+  serves happily.
+
+## Showing the client what the agent built
+
+- **Vercel Blob refuses to serve HTML inline** — it forces a download. Use it
+  for documents and exports, never to show a web page.
+- **exe.dev forwards ports 3000–9999** to `https://<vm>.exe.xyz:<port>/`, but a
+  VM has exactly **one public port** and the agent's webhook already owns it.
+  Alternate ports are account-gated: fine for the client reviewing work, not for
+  the public.
+- **Anything genuinely public needs a deploy target** — the client's own Vercel
+  token, or their hosting. Treat "public" as a deploy step, not a toggle.
+- A sandbox is a container: its ports are not reachable from the host, so a dev
+  server inside it cannot be previewed directly. Copy the artifact out (the
+  `preview` tool in `@kybernesis/exe`) or deploy it.
+
+## Credential checklist — collect ALL of these from the client
+
+Nothing here can be borrowed from another agent or another account.
+
+1. **Host** — VM/server, plus the platform token if the agent provisions anything
+2. **Model source** — their LLM API key, gateway allocation, or connected
+   subscription (exe: `integrations setup chatgpt`, then `integrations edit llm`)
+3. **Channel app** — their Slack app (bot + app token) / Photon project / bot token
+4. **Arcana** — workspaces + scoped `kb_` keys (one per brain, plus `-eval`)
+5. **Storage for deliverables** — their blob store, or a served host directory
+6. **Deploy target** — their Vercel token or hosting, if the agent ships sites
+7. **Control plane** — agent registered and the pilot cohort granted
+
+## Before calling it done
+
+`kyb doctor` green (or every warning consciously accepted), the eval suite green
+against the client's `-eval` workspace, and a live turn on the real surface.