@kybernesis/create 0.3.2 → 0.5.0

package/dist/cli.js

@@ -14,10 +14,24 @@ import { init } from "./init.js";
 import { doctor } from "./doctor.js";
 import { upgrade } from "./upgrade.js";
 import { installSkills } from "./skills.js";
+function flag(rest, key) {
+    const hit = rest.find((a) => a.startsWith(`--${key}=`));
+    return hit ? hit.slice(key.length + 3) : undefined;
+}
+function initOptions(rest) {
+    const subs = flag(rest, 'subagents');
+    return {
+        engineer: rest.includes('--engineer'),
+        channel: flag(rest, "channel"),
+        host: flag(rest, "host"),
+        subagents: subs === undefined ? undefined : subs.split(',').map((s) => s.trim()).filter(Boolean),
+        yes: rest.includes('--yes') || rest.includes('-y'),
+    };
+}
 const [, , command, ...rest] = process.argv;
 switch (command) {
     case "init":
-        await init(rest.find((a) => !a.startsWith("-")), { engineer: rest.includes("--engineer") });
+        await init(rest.find((a) => !a.startsWith("-")), initOptions(rest));
         break;
     case "doctor":
         await doctor();
@@ -29,19 +43,23 @@ switch (command) {
         await upgrade(rest.includes("--skip-eval"));
         break;
     case undefined:
-        await init(undefined, { engineer: false });
+        await init(undefined, initOptions(rest));
         break;
     default:
         if (!command.startsWith("-")) {
             // `npm create @kybernesis acme-agent` → argv[2] is the name.
-            await init(command, { engineer: rest.includes("--engineer") });
+            await init(command, initOptions(rest));
             break;
         }
         console.log(`
 ${bold("kyb")} — Kybernesis agent scaffolder & FDE toolkit
 
-  ${bold("kyb init [name]")}     scaffold a full Kybernesis eve agent
+  ${bold("kyb init [name]")}     scaffold a Kybernesis eve agent (core: enterprise + arcana + evals)
+      --channel=<kind>  ${dim("none|slack|imessage|telegram|discord|web  (default: none)")}
+      --host=<kind>     ${dim("vercel|exe                                (default: vercel)")}
+      --subagents=a,b   ${dim("department subagents                      (default: none)")}
       --engineer        ${dim("add the engineer layer: workshop sandbox + vision dev loop")}
+      --yes             ${dim("no prompts; take flags and defaults")}
   ${bold("kyb doctor")}          preflight checks (keys, issuer, envs, discovery)
   ${bold("kyb skills")}          install/refresh the FDE skill suite for Claude Code
       --global          ${dim("install to ~/.claude/skills instead of this repo")}

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.d.ts

@@ -1,3 +1,13 @@
-export declare function init(rawName: string | undefined, options?: {
+import { type ChannelKind, type HostKind } from "./templates.js";
+export interface InitOptions {
     engineer?: boolean;
-}): Promise<void>;
+    /** Chat surface. Default "none" — add later with `kyb add channel`. */
+    channel?: ChannelKind;
+    /** Where the agent runs. Default "vercel". */
+    host?: HostKind;
+    /** Department subagents. Default NONE. */
+    subagents?: string[];
+    /** Skip prompts and take the flags/defaults as given. */
+    yes?: boolean;
+}
+export declare function init(rawName: string | undefined, options?: InitOptions): Promise<void>;

package/dist/init.js

@@ -1,86 +1,137 @@
 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, green, run, slug, yellow, } from "./util.js";
-import { envExample, evalFileTs, evalScript, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
+import { DEFAULT_ISSUER, EVE_VERSION, REGISTRY_URL, ask, bold, closePrompts, dim, green, run, slug, yellow, } from "./util.js";
+import { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
 import { suiteDir } from "./skills.js";
-const ITEMS = ["enterprise", "arcana", "multiplayer", "evals"];
-// Official eve-registry limbs installed alongside the engineer layer.
-const ENGINEER_OFFICIAL_ITEMS = ["extension/agent-browser", "extension/github-tools", "connection/vercel"];
-export async function init(rawName, options) {
-    const engineer = options?.engineer === true;
+/**
+ * The always-installed core. Everything else — channels, subagents, engineer,
+ * host bindings — is opt-in, because assuming them means the FDE deletes files
+ * AND undoes real setup work (an Arcana workspace + scoped key per subagent).
+ */
+const CORE_ITEMS = ["enterprise", "arcana", "evals"];
+// 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;
+    const nonInteractive = options.yes === true;
     const name = slug(rawName ?? (await ask("Agent name (kebab-case)?", "acme-agent")));
     if (!name) {
         console.error("An agent name is required.");
         process.exit(1);
     }
-    const displayName = await ask("Display name (what employees call it)?", name);
-    const deptsRaw = await ask("Department subagents (comma-separated, empty for none)?", "finance,marketing,engineering");
-    const depts = deptsRaw
-        .split(",")
-        .map((d) => slug(d))
-        .filter(Boolean);
-    const issuer = await ask("Control-plane issuer?", DEFAULT_ISSUER);
+    const displayName = nonInteractive
+        ? name
+        : await ask("Display name (what employees call it)?", name);
+    // Channel: default NONE. A client on iMessage should never be handed Slack.
+    let channel = options.channel ?? "none";
+    if (!options.channel && !nonInteractive) {
+        const answer = await ask(`Chat surface? (${CHANNEL_KINDS.join(" | ")})`, "none");
+        const picked = answer.trim().toLowerCase();
+        channel = CHANNEL_KINDS.includes(picked) ? picked : "none";
+    }
+    // Host: where it runs. Vercel unless told otherwise.
+    let host = options.host ?? "vercel";
+    if (!options.host && !nonInteractive) {
+        const answer = await ask("Host? (vercel | exe)", "vercel");
+        host = answer.trim().toLowerCase() === "exe" ? "exe" : "vercel";
+    }
+    // Subagents: default NONE. Each one costs a workspace + scoped key.
+    let depts = options.subagents ?? [];
+    if (!options.subagents && !nonInteractive) {
+        const raw = await ask("Department subagents (comma-separated, empty for none)?", "");
+        depts = raw.split(",").map((d) => slug(d)).filter(Boolean);
+    }
+    const issuer = nonInteractive
+        ? DEFAULT_ISSUER
+        : await ask("Control-plane issuer?", DEFAULT_ISSUER);
     closePrompts();
     const dir = resolve(process.cwd(), name);
     if (existsSync(dir)) {
         console.error(`Directory ${name}/ already exists.`);
         process.exit(1);
     }
+    const plan = channelPlan(channel, name, host);
     console.log(bold(`\n1/6  Scaffolding eve agent (eve@${EVE_VERSION}) …`));
     run("npx", [`eve@${EVE_VERSION}`, "init", name]);
-    console.log(bold("\n2/6  Adding the Kybernesis registry + packages …"));
+    console.log(bold("\n2/6  Adding the Kybernesis registry + core packages …"));
     run("npx", ["eve", "registry", "add", `@kybernesis=${REGISTRY_URL}`], { cwd: dir });
-    for (const item of ITEMS) {
+    for (const item of CORE_ITEMS) {
         run("npx", ["eve", "add", `@kybernesis/${item}`, "--overwrite"], { cwd: dir });
     }
-    if (engineer) {
-        console.log(bold("\n2b   Engineer layer: workshop sandbox + vision dev loop …"));
-        run("npx", ["eve", "add", "@kybernesis/engineer", "--overwrite"], { cwd: dir });
-        for (const item of ENGINEER_OFFICIAL_ITEMS) {
-            // Official items may carry their own interactive setup; a failure here
-            // shouldn't kill the scaffold — the FDE can re-run `eve add <item>`.
+    const extraDeps = [...plan.deps, ...(host === "exe" ? ["@kybernesis/exe", "@ai-sdk/openai"] : [])];
+    if (extraDeps.length) {
+        console.log(bold(`\n2b   Installing for ${channel}/${host}: ${extraDeps.join(", ")} …`));
+        run("npm", ["install", ...extraDeps, "--no-audit", "--no-fund"], { cwd: dir, allowFail: true });
+    }
+    for (const item of plan.registryItems) {
+        run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
+    }
+    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}`));
         }
     }
-    console.log(bold("\n2c   Seeding the FDE Claude Code skill suite (.claude/skills) …"));
+    console.log(bold("\n2d   Seeding the FDE Claude Code skill suite (.claude/skills) …"));
     try {
         cpSync(suiteDir(), join(dir, ".claude/skills"), { recursive: true });
     }
     catch {
         console.log(yellow("  ! skill suite not found — run kyb skills inside the repo later"));
     }
-    console.log(bold("\n3/6  Writing agent identity, memory mount, and eval wiring …"));
+    console.log(bold("\n3/6  Writing identity, model config, memory mount, and evals …"));
     mkdirSync(join(dir, "agent/instructions"), { recursive: true });
     writeFileSync(join(dir, "agent/instructions/identity.md"), identityMd(displayName, depts));
-    // The scaffold ships a flat agent/instructions.md; the directory form wins,
-    // so remove the flat file to avoid ambiguity.
     try {
         unlinkSync(join(dir, "agent/instructions.md"));
     }
     catch { }
+    writeFileSync(join(dir, "agent/agent.ts"), hostAgentTs(host, DEFAULT_MODEL));
     writeFileSync(join(dir, "agent/extensions/arcana.ts"), rootArcanaTs());
     writeFileSync(join(dir, "evals/kybernesis.eval.ts"), evalFileTs(displayName, depts));
-    console.log(bold(`\n4/6  Generating ${depts.length} department subagent(s) …`));
-    const skillsSource = join(dir, "node_modules/@kybernesis/arcana/dist/extension/skills");
-    for (const dept of depts) {
-        const base = join(dir, "agent/subagents", dept);
-        mkdirSync(join(base, "connections"), { recursive: true });
-        writeFileSync(join(base, "agent.ts"), subagentAgentTs(dept));
-        writeFileSync(join(base, "instructions.md"), subagentInstructionsMd(dept));
-        writeFileSync(join(base, "connections/arcana.ts"), subagentArcanaTs(dept));
-        // Subagents inherit nothing: copy the memory skills from the installed
-        // arcana package so each specialist carries the playbooks.
-        if (existsSync(skillsSource)) {
-            cpSync(skillsSource, join(base, "skills"), { recursive: true });
+    if (plan.file) {
+        console.log(bold(`\n4/6  Channel: ${channel} …`));
+        mkdirSync(join(dir, "agent/channels"), { recursive: true });
+        writeFileSync(join(dir, "agent/channels", plan.file), plan.content);
+    }
+    else {
+        console.log(bold(`\n4/6  Channel: ${channel} (no channel file) …`));
+    }
+    if (depts.length) {
+        console.log(bold(`\n4b   Generating ${depts.length} department subagent(s) …`));
+        const skillsSource = join(dir, "node_modules/@kybernesis/arcana/dist/extension/skills");
+        for (const dept of depts) {
+            const base = join(dir, "agent/subagents", dept);
+            mkdirSync(join(base, "connections"), { recursive: true });
+            writeFileSync(join(base, "agent.ts"), subagentAgentTs(dept));
+            writeFileSync(join(base, "instructions.md"), subagentInstructionsMd(dept));
+            writeFileSync(join(base, "connections/arcana.ts"), subagentArcanaTs(dept));
+            if (existsSync(skillsSource)) {
+                cpSync(skillsSource, join(base, "skills"), { recursive: true });
+            }
+            else {
+                console.log(yellow(`  ! arcana skills not found at ${skillsSource} — copy them manually`));
+            }
         }
-        else {
-            console.log(yellow(`  ! arcana skills not found at ${skillsSource} — copy them manually`));
+    }
+    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));
+    writeFileSync(join(dir, ".env.example"), envExample(name, depts, issuer, plan.env));
     const pkgPath = join(dir, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
     pkg.scripts = { ...pkg.scripts, eval: evalScript(name, depts) };
@@ -88,34 +139,33 @@ export async function init(rawName, options) {
     console.log(bold("\n6/6  Verifying (typecheck + eve discovery) …"));
     const tsOk = run("npm", ["run", "typecheck"], { cwd: dir, allowFail: true });
     const infoOk = run("npx", ["eve", "info"], { cwd: dir, allowFail: true, quiet: true });
-    console.log(tsOk && infoOk ? green("  ✓ typecheck + discovery clean") : yellow("  ! verify manually: npm run typecheck && npx eve info"));
+    console.log(tsOk && infoOk
+        ? green("  ✓ typecheck + discovery clean")
+        : yellow("  ! verify manually: npm run typecheck && npx eve info"));
+    const parts = [
+        "governed (enterprise)",
+        "remembering (arcana)",
+        "self-testing (evals)",
+        channel === "none" ? null : `${channel} channel`,
+        host === "exe" ? "exe.dev host" : 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`,
+    ];
     console.log(`
-${green("✓")} ${bold(name)} scaffolded: governed (enterprise) · remembering (arcana) · multiplayer (slack) · self-testing (evals)${engineer ? " · engineer (workshop + vision loop)" : ""}${depts.length ? ` · ${depts.length} dept subagent(s)` : ""}${engineer ? `
-
-${bold("Engineer notes:")}
-  · The workshop sandbox (agent/sandbox/sandbox.ts) bakes Playwright into the
-    template at DEPLOY time — a broken bootstrap fails the Vercel build loudly.
-    Deployed sessions run under a domain allowlist; extend it deliberately in
-    that file when a project needs another host.
-  · Vercel connection (preview deploys + link-back), after \`vercel link\`:
-      vercel connect create mcp.vercel.com --name vercel
-      vercel connect attach mcp.vercel.com/vercel --yes
-    then set connect("mcp.vercel.com/vercel") — the UID, not the short name —
-    in agent/connections/vercel.ts. First tool use posts an OAuth link in the
-    thread (user-scoped); grant "All projects" so the agent can create new ones,
-    then narrow the grant in the dashboard once the project exists.
-  · File delivery (the deliver tool needs it):
-      vercel blob create-store ${name}-deliverables --access public --yes
-    links the store and injects BLOB_READ_WRITE_TOKEN automatically.
-  · agent-browser / github-tools may need their Connect setup flows — run
-    their printed setup commands if tools 401.` : ""}
+${green("✓")} ${bold(name)} scaffolded: ${parts.join(" · ")}
 
 ${bold("Human steps (in order) — the FDE playbook covers each in detail:")}
-  1. Arcana: create workspaces (${name}-company, ${name}-eval${depts.map((d) => `, ${name}-${d}`).join("")}) + scoped kb_ keys; fill .env.local from .env.example
-  2. Vercel: \`vercel link\` in ${name}/ (client's team), add envs (prod/preview Sensitive)
-  3. Slack: \`vercel connect create slack --triggers --name ${name}\` → detach → re-attach with --trigger-path /eve/v1/slack
-  4. Control plane: register agent "${name}" (runtime: ▲ eve) at ${issuer}/agents + grant the pilot cohort
-  5. \`npm run eval\` → green → \`npx eve deploy\` → live Slack smoke + the revoke demo
+${steps.map((s, i) => `  ${i + 1}. ${s}`).join("\n")}
+
   Run ${bold("kyb doctor")} inside ${name}/ any time to check the wiring.
+${dim("  Add more later: kyb add channel <kind> · kyb add subagent <name>")}
 `);
 }

package/dist/templates.d.ts

@@ -7,5 +7,33 @@ export declare function subagentInstructionsMd(dept: string): string;
 export declare function subagentArcanaTs(dept: string): string;
 export declare function rootArcanaTs(): string;
 export declare function evalFileTs(displayName: string, depts: string[]): string;
-export declare function envExample(name: string, depts: string[], issuer: string): string;
+export declare function envExample(name: string, depts: string[], issuer: string, channelEnv?: string[]): string;
 export declare function evalScript(name: string, depts: string[]): string;
+export type ChannelKind = "none" | "slack" | "imessage" | "telegram" | "discord" | "web";
+export declare const CHANNEL_KINDS: ChannelKind[];
+export interface ChannelPlan {
+    /** File written under agent/channels/, or null for `none`. */
+    file: string | null;
+    content: string;
+    /** npm deps this channel needs beyond eve. */
+    deps: string[];
+    /** Registry items to `eve add` (interactive setup flows live there). */
+    registryItems: string[];
+    /** Env lines appended to .env.example. */
+    env: string[];
+    /** Human setup steps printed after scaffolding. */
+    steps: string[];
+}
+export declare function channelPlan(kind: ChannelKind, name: string, host: HostKind): ChannelPlan;
+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

@@ -120,7 +120,7 @@ export default kybernesisBaseline({
 ${depts.length ? `  routing: [\n${routing}\n  ],\n` : ""}});
 `;
 }
-export function envExample(name, depts, issuer) {
+export function envExample(name, depts, issuer, channelEnv = []) {
     const deptVars = depts
         .map((d) => {
         const upper = d.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
@@ -135,10 +135,7 @@ export function envExample(name, depts, issuer) {
 KYBERNESIS_ISSUER="${issuer}"
 KYBERNESIS_AGENT="${name}"
 
-# Slack (@kybernesis/multiplayer) — Vercel Connect connector UID
-# SLACK_CONNECTOR_UID="slack/${name}"
-
-# Arcana memory (@kybernesis/arcana) — one workspace + scoped kb_ key per brain
+${channelEnv.length ? `# Channel\n${channelEnv.join("\n")}\n\n` : ""}# Arcana memory (@kybernesis/arcana) — one workspace + scoped kb_ key per brain
 # ARCANA_API_KEY="kb_..."
 # ARCANA_COMPANY_WORKSPACE="${name}-company"
 # ARCANA_DM_WORKSPACE="${name}-company"
@@ -154,3 +151,359 @@ export function evalScript(name, depts) {
     ];
     return `${overrides.join(" ")} eve eval`;
 }
+export const CHANNEL_KINDS = [
+    "none",
+    "slack",
+    "imessage",
+    "telegram",
+    "discord",
+    "web",
+];
+export function channelPlan(kind, name, host) {
+    const onExe = host === "exe";
+    switch (kind) {
+        case "slack":
+            return {
+                file: "slack.ts",
+                content: onExe
+                    ? `import { multiplayerSlackChannel } from "@kybernesis/multiplayer/slack";
+import { forwardedSocketVerifier } from "@kybernesis/exe/slack";
+
+// Slack on a self-hosted (exe.dev) host.
+// Inbound: a forwarder holds the exe-brokered Socket Mode connection and POSTs
+// events here; the verifier authenticates them on SLACK_SOCKET_FORWARDING_SECRET.
+// Outbound: SLACK_BOT_TOKEN must be on the host — eve's SlackChannelCredentials
+// has no apiUrl, so calls can't route through the exe integration yet.
+export default multiplayerSlackChannel({
+  credentials: {
+    botToken: process.env.SLACK_BOT_TOKEN!,
+    webhookVerifier: forwardedSocketVerifier(),
+  },
+});
+`
+                    : `import { connectSlackCredentials } from "@vercel/connect/eve";
+import { multiplayerSlackChannel } from "@kybernesis/multiplayer/slack";
+
+// Shared threads with per-speaker verified identity, attributed context, and
+// dual surface (channel vs DM). Credentials are brokered by Vercel Connect.
+export default multiplayerSlackChannel({
+  credentials: connectSlackCredentials(process.env.SLACK_CONNECTOR_UID!),
+});
+`,
+                deps: ["@kybernesis/multiplayer", ...(onExe ? ["@kybernesis/exe"] : ["@vercel/connect"])],
+                registryItems: [],
+                env: onExe
+                    ? [
+                        `SLACK_BOT_TOKEN="xoxb-..."   # outbound; from Slack OAuth & Permissions`,
+                        `SLACK_SOCKET_FORWARDING_SECRET="$(openssl rand -hex 24)"`,
+                    ]
+                    : [`SLACK_CONNECTOR_UID="slack/${name}"`],
+                steps: onExe
+                    ? [
+                        `Create a Slack app (Socket Mode on; scopes: app_mentions:read, chat:write, channels:history, groups:history, im:history, users:read)`,
+                        `Hold its tokens off-host: ssh exe.dev integrations add slack --name ${name} --bot-token=- --app-token=-`,
+                        `Run the forwarder (scripts/slack-forwarder.py in @kybernesis/exe) with EXE_SLACK_GW set`,
+                        `After ANY scope change, reinstall the app — a stale token silently stops receiving events`,
+                    ]
+                    : [
+                        `vercel connect create slack --triggers --name ${name}`,
+                        `vercel connect detach <uid> --yes && vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes`,
+                    ],
+            };
+        case "imessage":
+            return {
+                file: "photon.ts",
+                content: `import { photonIMessageChannel } from "eve/channels/photon";
+${onExe ? `import { photonEnvCredentials } from "@kybernesis/exe/photon";\n` : ""}
+// iMessage via Photon. Inbound is a plain webhook at /eve/v1/photon; the Photon
+// signing secret takes precedence over the default Vercel-OIDC verifier, so this
+// works on any host with a public HTTPS URL.
+export default photonIMessageChannel({
+${onExe
+                    ? `  credentials: photonEnvCredentials(),`
+                    : `  async credentials() {
+    const projectId = process.env.IMESSAGE_PROJECT_ID;
+    const projectSecret = process.env.IMESSAGE_PROJECT_SECRET;
+    if (!projectId || !projectSecret) throw new Error("Photon project credentials are required.");
+    return { projectId, projectSecret };
+  },`}
+  webhookSecret: process.env.IMESSAGE_WEBHOOK_SECRET,
+});
+`,
+                deps: onExe ? ["@kybernesis/exe"] : [],
+                registryItems: [],
+                env: [
+                    `IMESSAGE_PROJECT_ID="..."`,
+                    `IMESSAGE_PROJECT_SECRET="..."`,
+                    `IMESSAGE_WEBHOOK_SECRET="..."   # Photon webhook signing secret`,
+                ],
+                steps: [
+                    `Create a Photon project and register the phone number (npx eve add channel/photon-imessage walks it)`,
+                    onExe
+                        ? `Make the host public FIRST — webhooks need anonymous access:\n       ssh exe.dev share port <vm> 8000 && ssh exe.dev share set-public <vm>`
+                        : `Deploy so the public URL exists`,
+                    `Register a Photon webhook for https://<your-host>/eve/v1/photon and copy its signing secret to IMESSAGE_WEBHOOK_SECRET`,
+                ],
+            };
+        case "telegram":
+            return {
+                file: "telegram.ts",
+                content: `import { telegramChannel } from "eve/channels/telegram";
+
+// Telegram. Register the webhook against your public URL after deploying.
+export default telegramChannel({ botToken: process.env.TELEGRAM_BOT_TOKEN! });
+`,
+                deps: [],
+                registryItems: [],
+                env: [`TELEGRAM_BOT_TOKEN="..."   # from @BotFather`],
+                steps: [
+                    `Create a bot with @BotFather and copy its token`,
+                    `After deploy: curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" -d "url=https://<host>/eve/v1/telegram"`,
+                ],
+            };
+        case "discord":
+            return {
+                file: "discord.ts",
+                content: `import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel({ botToken: process.env.DISCORD_BOT_TOKEN! });
+`,
+                deps: [],
+                registryItems: [],
+                env: [`DISCORD_BOT_TOKEN="..."`],
+                steps: [`Create a Discord application + bot, invite it, set DISCORD_BOT_TOKEN`],
+            };
+        case "web":
+            return {
+                file: null,
+                content: "",
+                deps: [],
+                registryItems: [],
+                env: [],
+                steps: [
+                    `The eve channel (agent/channels/eve.ts) already serves HTTP; build a frontend with useEveAgent`,
+                ],
+            };
+        case "none":
+        default:
+            return {
+                file: null,
+                content: "",
+                deps: [],
+                registryItems: [],
+                env: [],
+                steps: [`No chat surface yet — add one later with: kyb add channel <slack|imessage|telegram|discord|web>`],
+            };
+    }
+}
+export function hostAgentTs(host, model) {
+    if (host === "exe") {
+        return `import { defineAgent } from "eve";
+import { createOpenAI } from "@ai-sdk/openai";
+import { exeModel } from "@kybernesis/exe";
+
+// Model served by the exe.dev LLM integration — no provider key on the host.
+// exe injects the credential (managed gateway, your API key, or a connected
+// ChatGPT subscription) server-side.
+export default defineAgent({
+  model: exeModel({ model: process.env.EXE_MODEL ?? ${JSON.stringify(model)}, createOpenAI }),
+  modelContextWindowTokens: 200_000,
+});
+`;
+    }
+    return `import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: ${JSON.stringify(model)},
+});
+`;
+}
+export function hostSteps(host, name) {
+    if (host === "exe") {
+        return [
+            `Create the VM:  ssh exe.dev new --name ${name}`,
+            `Attach an LLM integration (ChatGPT subscription, your API key, or exe's gateway):`,
+            `    ssh exe.dev integrations setup chatgpt --name work   # once, device-code`,
+            `    ssh exe.dev integrations edit llm --openai=chatgpt --openai-account=work`,
+            `Install Node 24 + deps on the VM, then: npx eve build && bash scripts/eve-server.sh start`,
+            `\`eve start\` does NOT read .env.local — scripts/eve-server.sh loads it for you`,
+        ];
+    }
+    return [
+        `vercel link  (the client's team), then set envs (prod/preview Sensitive)`,
+        `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.3.2",
+  "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/fde-engagement/references/playbook.md

@@ -904,6 +904,21 @@ Client-conversation rules of thumb:
   product conversation — purpose-scoped grants, §2.5 disclosures. Don't wire
   one as if it were internal.
 
+**Governed mode (dispatch ≥0.2.1 + enterprise ≥0.2.0 + the client's control
+plane) — the preferred form.** Edges become GRANTS in the admin instead of
+code: register both agents (/agents, OPEN production alias, health 200), grant
+the edge on the CALLEE's panel (caller + purpose + optional expiry), mint each
+agent's credential (shown once) into KYBERNESIS_AGENT_CREDENTIAL on its
+deployment. Code shrinks to remotePeer({ callee: "<EXACT registered name —
+case-sensitive>", governed: { issuer }, envVar, fallbackUrl }) and
+dispatchChannel({ governed: { issuer, agent } }). Outbound auth is a 300 s A2A
+token minted per edge; the callee URL comes from the registry (discovery), env
+var still wins. THE DEMO: revoke the edge in the admin → the caller is refused
+(edge_not_granted) within 5 minutes, no redeploy; re-grant → restored. Run it
+for the client — it's the whole governance story in one minute. Full lifecycle
+proven live 2026-08-07 (kyber ↔ eve-gtm). Budget note: the deployed agent and
+local eval runs share the project's AI Gateway budget — size it for both.
+
 ### 4.4 Author the agent's identity and instructions
 
 How instructions work in eve (30 seconds of mechanics): a flat

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.