@kybernesis/create 0.7.1 → 0.7.2

package/dist/cli.js

@@ -6,6 +6,8 @@
  *                         self-testing eve agent (also: npm create @kybernesis)
  *   kyb doctor            preflight an agent project: keys, issuer, envs, discovery
  *   kyb skills [--global] install/refresh the FDE Claude Code skill suite
+ *   kyb register          register this agent with the control plane (device flow)
+ *   kyb deploy            put this repo on its host and restart it, with proof
  *   kyb upgrade           bump @kybernesis/* to latest, gated on the eval suite
  *     --skip-eval           skip the eval gate (not for production changes)
  */
@@ -14,6 +16,8 @@ import { init } from "./init.js";
 import { doctor } from "./doctor.js";
 import { upgrade } from "./upgrade.js";
 import { installSkills } from "./skills.js";
+import { deploy } from "./deploy.js";
+import { register } from "./register.js";
 function flag(rest, key) {
     const hit = rest.find((a) => a.startsWith(`--${key}=`));
     return hit ? hit.slice(key.length + 3) : undefined;
@@ -40,6 +44,12 @@ switch (command) {
     case "skills":
         installSkills({ global: rest.includes("--global") });
         break;
+    case "register":
+        await register({ name: flag(rest, "name"), url: flag(rest, "url") });
+        break;
+    case "deploy":
+        await deploy({ host: flag(rest, "host") });
+        break;
     case "upgrade":
         await upgrade(rest.includes("--skip-eval"));
         break;
@@ -65,6 +75,11 @@ ${bold("kyb")} — Kybernesis agent scaffolder & FDE toolkit
   ${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")}
+  ${bold("kyb register")}        register this agent with the control plane
+      --name=<name>     ${dim("defaults to KYBERNESIS_AGENT in .env.local")}
+      --url=<url>       ${dim("defaults to https://$EXE_VM_NAME.exe.xyz")}
+  ${bold("kyb deploy")}          copy to the host, install, restart, prove it took
+      --host=<target>   ${dim("ssh target; defaults to $EXE_VM_NAME.exe.xyz")}
   ${bold("kyb upgrade")}         bump @kybernesis/* packages, gated on evals
       --skip-eval       ${dim("skip the eval gate")}
 

package/dist/deploy.d.ts

@@ -0,0 +1,4 @@
+export declare function deploy(options: {
+    host?: string;
+    dir?: string;
+}): Promise<void>;

package/dist/deploy.js

@@ -0,0 +1,169 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { bold, dim, green, red, yellow } from "./util.js";
+/**
+ * `kyb deploy` — put this repo on its host and restart it, with proof.
+ *
+ * On Vercel this is `eve deploy` and always was. Off Vercel it was a paragraph
+ * in a skill telling people to rsync and then run a script, which is the sort
+ * of step that gets done differently by each person doing it — and the
+ * differences are exactly where the outages came from.
+ */
+function env(dir) {
+    const out = {};
+    for (const file of [".env.local", ".env"]) {
+        const p = join(dir, file);
+        if (!existsSync(p))
+            continue;
+        for (const line of readFileSync(p, "utf8").split("\n")) {
+            const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+            if (m?.[1] && out[m[1]] === undefined)
+                out[m[1]] = (m[2] ?? "").trim().replace(/^["']|["']$/g, "");
+        }
+    }
+    return out;
+}
+function hostOf(dir) {
+    const pkg = join(dir, "package.json");
+    const deps = existsSync(pkg)
+        ? (JSON.parse(readFileSync(pkg, "utf8")).dependencies ?? {})
+        : {};
+    return deps["@kybernesis/exe"] ? "exe" : "vercel";
+}
+/** The ssh target: an explicit flag, then EVE_SSH_HOST, then the exe VM name. */
+function sshTarget(dir, explicit) {
+    const e = env(dir);
+    if (explicit)
+        return explicit;
+    if (e.EVE_SSH_HOST)
+        return e.EVE_SSH_HOST;
+    if (e.EXE_VM_NAME)
+        return `${e.EXE_VM_NAME}.exe.xyz`;
+    return null;
+}
+export async function deploy(options) {
+    const dir = options.dir ?? process.cwd();
+    if (!existsSync(join(dir, "agent"))) {
+        console.log(red("Not an eve agent project (no agent/ directory)."));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(bold("kyb deploy"));
+    if (hostOf(dir) === "vercel") {
+        console.log(dim("  host: vercel — handing over to eve deploy\n"));
+        const r = spawnSync("npx", ["eve", "deploy"], { cwd: dir, stdio: "inherit" });
+        process.exitCode = r.status ?? 0;
+        return;
+    }
+    const target = sshTarget(dir, options.host);
+    if (!target) {
+        console.log(red("  No host to deploy to."));
+        console.log(dim("  Set EXE_VM_NAME (or EVE_SSH_HOST) in .env.local, or pass --host=<ssh target>."));
+        process.exitCode = 1;
+        return;
+    }
+    const name = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name ?? "agent";
+    const remote = `~/${name}`;
+    console.log(dim(`  host: ${target}   path: ${remote}\n`));
+    const run = (cmd, args) => {
+        const r = spawnSync(cmd, args, { cwd: dir, stdio: "inherit" });
+        return (r.status ?? 1) === 0;
+    };
+    /**
+     * Never copy node_modules, .eve, or a build.
+     *
+     * node_modules is platform-specific and native modules built on a laptop do
+     * not run on the host. `.eve` is the durable store — conversations, turn
+     * history, the workflow queue — and overwriting it with a local copy is how
+     * a deployment eats its own production state.
+     */
+    console.log(bold("1/3  Copying source …"));
+    const ok = run("rsync", [
+        "-az",
+        "--delete",
+        "--exclude",
+        "node_modules",
+        "--exclude",
+        ".eve",
+        "--exclude",
+        ".output",
+        "--exclude",
+        ".git",
+        "--exclude",
+        ".env.local",
+        `${dir}/`,
+        `${target}:${remote}/`,
+    ]);
+    if (!ok) {
+        console.log(red("  rsync failed — is the host reachable, and is the path writable?"));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(bold("\n2/3  Installing dependencies on the host …"));
+    if (!run("ssh", [target, `cd ${remote} && npm install --no-audit --no-fund`])) {
+        console.log(red("  npm install failed on the host."));
+        process.exitCode = 1;
+        return;
+    }
+    /**
+     * Detached, always.
+     *
+     * `ssh host "script"` sends SIGHUP when the connection ends, which kills the
+     * restart halfway — leaving exactly the half-restarted state the script
+     * exists to prevent. setsid + nohup + no stdin is the difference between a
+     * deploy and an outage.
+     */
+    console.log(bold("\n3/3  Restarting (detached) …"));
+    /**
+     * Find the restart script rather than assuming its name.
+     *
+     * `kyb init` installs scripts/eve-server.sh, but agents predating that have
+     * their own — and a deploy that fails on a naming difference is a deploy
+     * people stop using. Falls back to installing the packaged script, so a
+     * project that has none ends up with the hardened one rather than an error.
+     */
+    const remoteScript = [
+        'SCRIPT=""',
+        // A loop, not a chain of `[ -f x ] && echo x || …` — that keeps evaluating
+        // after the first hit and yields every match, so SCRIPT becomes three
+        // filenames and `bash "$SCRIPT"` fails on a name nothing has.
+        "for f in scripts/eve-server.sh scripts/restart.sh eve-server.sh restart.sh; do",
+        '  if [ -f "$f" ]; then SCRIPT="$f"; break; fi',
+        "done",
+        'if [ -z "$SCRIPT" ] && [ -f node_modules/@kybernesis/exe/scripts/eve-server.sh ]; then',
+        "  mkdir -p scripts",
+        "  cp node_modules/@kybernesis/exe/scripts/eve-server.sh scripts/",
+        "  chmod +x scripts/eve-server.sh",
+        '  SCRIPT="scripts/eve-server.sh"',
+        "fi",
+        'if [ -z "$SCRIPT" ]; then echo "FAILED: no restart script on the host"; exit 1; fi',
+        'echo "using $SCRIPT"',
+        'setsid nohup bash "$SCRIPT" > /tmp/kyb-deploy.log 2>&1 < /dev/null &',
+        "sleep 2",
+        "echo started",
+    ].join("\n");
+    run("ssh", [target, `cd ${remote}\n${remoteScript}`]);
+    console.log(dim("\n  Waiting for the restart to report …"));
+    let last = "";
+    for (let i = 0; i < 40; i++) {
+        const out = execFileSync("ssh", [target, `tail -6 /tmp/kyb-deploy.log 2>/dev/null || true`], {
+            encoding: "utf8",
+        });
+        last = out;
+        if (/health:|FAILED/.test(out))
+            break;
+        await new Promise((r) => setTimeout(r, 5000));
+    }
+    const healthy = /health:\s*200/.test(last);
+    console.log(last
+        .split("\n")
+        .filter((l) => /pid=|build:|OK:|health:|FAILED|SOURCE IS NEWER|^built/.test(l))
+        .map((l) => `  ${l}`)
+        .join("\n"));
+    console.log(healthy
+        ? green("\n  ✓ deployed and serving the current build")
+        : yellow("\n  ! the restart did not report health — check /tmp/kyb-deploy.log on the host"));
+    if (!healthy)
+        process.exitCode = 1;
+}

package/dist/register.d.ts

@@ -0,0 +1,5 @@
+export declare function register(options: {
+    name?: string;
+    url?: string;
+    dir?: string;
+}): Promise<void>;

package/dist/register.js

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { bold, dim, green, red, yellow } from "./util.js";
+function envOf(dir) {
+    const out = {};
+    for (const file of [".env.local", ".env"]) {
+        const p = join(dir, file);
+        if (!existsSync(p))
+            continue;
+        for (const line of readFileSync(p, "utf8").split("\n")) {
+            const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+            if (m?.[1] && out[m[1]] === undefined)
+                out[m[1]] = (m[2] ?? "").trim().replace(/^["']|["']$/g, "");
+        }
+    }
+    return out;
+}
+/** Sign in with the device flow and return an identity token. */
+async function signIn(issuer) {
+    const started = await fetch(`${issuer}/api/oauth/device`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ deviceId: `kyb-cli-${process.pid}`, deviceLabel: "kyb CLI" }),
+    }).catch(() => null);
+    if (!started?.ok) {
+        console.log(red(`  Could not start sign-in at ${issuer}.`));
+        return null;
+    }
+    const body = (await started.json());
+    const url = String(body.verification_uri_complete ?? body.verification_uri ?? "");
+    const code = String(body.user_code ?? "");
+    const deviceCode = String(body.device_code ?? "");
+    let interval = Number(body.interval ?? 5) * 1000;
+    const deadline = Date.now() + Number(body.expires_in ?? 600) * 1000;
+    console.log(`\n  Approve this in your browser:\n`);
+    console.log(`    ${bold(url)}`);
+    if (code)
+        console.log(`    code: ${bold(code)}\n`);
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, interval));
+        const res = await fetch(`${issuer}/api/oauth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ device_code: deviceCode }),
+        }).catch(() => null);
+        if (!res)
+            continue;
+        const out = (await res.json().catch(() => ({})));
+        if (res.ok && typeof out.token === "string")
+            return out.token;
+        if (out.error === "slow_down")
+            interval += 5000;
+        // authorization_pending is the normal case; anything else is fatal.
+        if (out.error && out.error !== "authorization_pending" && out.error !== "slow_down") {
+            console.log(red(`  Sign-in failed: ${String(out.error)}`));
+            return null;
+        }
+    }
+    console.log(red("  Sign-in timed out."));
+    return null;
+}
+export async function register(options) {
+    const dir = options.dir ?? process.cwd();
+    const env = envOf(dir);
+    const issuer = (env.KYBERNESIS_ISSUER || "https://agent.kybernesis.ai").replace(/\/$/, "");
+    // The registered name must equal KYBERNESIS_AGENT exactly — it is what the
+    // agent checks grants against, and a mismatch is a 403 with no clue in it.
+    const name = options.name ?? env.KYBERNESIS_AGENT;
+    const url = options.url ??
+        env.EVE_PUBLIC_URL ??
+        (env.EXE_VM_NAME ? `https://${env.EXE_VM_NAME}.exe.xyz` : undefined);
+    console.log(bold("kyb register"));
+    console.log(dim(`  issuer: ${issuer}`));
+    if (!name) {
+        console.log(red("  No agent name. Set KYBERNESIS_AGENT in .env.local, or pass --name=<name>."));
+        process.exitCode = 1;
+        return;
+    }
+    if (!url) {
+        console.log(red("  No deployment URL. Set EXE_VM_NAME in .env.local, or pass --url=<https://…>."));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(dim(`  agent:  ${name}\n  url:    ${url}`));
+    const token = await signIn(issuer);
+    if (!token) {
+        process.exitCode = 1;
+        return;
+    }
+    const res = await fetch(`${issuer}/api/agents/register`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({ name, url }),
+    }).catch(() => null);
+    if (!res?.ok) {
+        const detail = res ? (await res.json().catch(() => ({}))).error : "unreachable";
+        console.log(red(`\n  Registration failed: ${detail ?? res?.status}`));
+        process.exitCode = 1;
+        return;
+    }
+    const out = (await res.json());
+    console.log(green(out.created
+        ? `\n  ✓ registered "${name}" and granted you access`
+        : `\n  ✓ "${name}" already existed — its URL now points at ${url}`));
+    console.log(dim("    Grant others in the admin; they do not inherit yours."));
+    if (!env.KYBERNESIS_AGENT_CREDENTIAL) {
+        console.log(yellow("\n  ! This agent has no credential yet. Turn on 'Work on this computer' in\n" +
+            "    KYBER Studio to mint and install one — do not paste a credential by hand."));
+    }
+}

package/dist/skills.js

@@ -1,6 +1,6 @@
 import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { bold, dim, green } from "./util.js";
 /** The skill suite shipped inside this package (skills/ beside dist/). */
@@ -26,6 +26,18 @@ export function installSkills(opts = {}) {
     const target = opts.global
         ? join(homedir(), ".claude", "skills")
         : join(process.cwd(), ".claude", "skills");
+    /**
+     * Never install the suite into itself.
+     *
+     * Run from inside the package's own skills/ directory, this copies the suite
+     * to skills/.claude/skills — which then ships inside the published tarball,
+     * so every consumer installs a duplicate suite nested one level down. That
+     * happened, got committed, and was one `npm publish` from being everyone's.
+     */
+    if (resolve(target).startsWith(resolve(src))) {
+        console.error("Refusing to install the suite into itself — run kyb skills from an agent repo, not from the package.");
+        process.exit(2);
+    }
     mkdirSync(target, { recursive: true });
     const names = readdirSync(src).filter((n) => !n.startsWith("."));
     for (const name of names) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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

@@ -1804,6 +1804,17 @@ keys of your own.
 
 ### 11.1 Scaffold
 
+The whole path is commands now — there is no step where an FDE is expected to
+improvise a deploy:
+
+```bash
+kyb init <name> --host=exe --channel=none --engineer --studio
+kyb register      # device flow; grants you; idempotent by name
+kyb deploy        # copy + install + restart + prove
+kyb doctor && npm run eval
+```
+
+
 ```bash
 kyb init <name> --host=exe --channel=<imessage|slack|telegram|none> --engineer
 cd <name> && kyb doctor

package/skills/kybernesis-packages/SKILL.md

@@ -86,9 +86,13 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   engineer? })` = smoke + 5 memory + routing per dept + optional vision-loop
   eval. Judge model ≠ model under test. Hermetic runs force all workspaces to
   `<name>-eval` via the npm script.
-- **create** — the `kyb` CLI: `init [--engineer]`, `doctor`, `upgrade`
-  (carries eve to the Kybernesis-CERTIFIED pin, never blind latest),
-  `skills`. Ships THIS skill suite.
+- **create** — the `kyb` CLI, and the whole lifecycle of an agent:
+  `init` (scaffold; `--host=exe` also installs the hardened restart script),
+  `register` (control plane, via device flow — no admin session, no pasted
+  token, grants the person who ran it, idempotent by name),
+  `deploy` (copy + install + restart + PROVE it; `eve deploy` on Vercel),
+  `doctor`, `upgrade` (carries eve to the Kybernesis-CERTIFIED pin, never
+  blind latest), `skills`. Ships THIS skill suite.
 
 ## Gotchas that each cost a real debugging session
 

package/skills/self-hosting/SKILL.md

@@ -15,11 +15,21 @@ 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
+kyb init <name> --host=exe --channel=<imessage|slack|telegram|none> --engineer --studio
+kyb register        # control plane: device flow, grants you, idempotent by name
+kyb deploy          # copy + install + restart, and prove it took
+kyb doctor          # preflight; it knows the self-hosted failure modes below
 ```
 
-`--host=exe` swaps the bindings; everything else is the same product. Run
-`kyb doctor` after — it knows the self-hosted failure modes below.
+`--host=exe` swaps the bindings and installs `scripts/eve-server.sh` — the
+restart script, with every lesson below already in it. `--studio` adds local
+execution and the management routes.
+
+**Deploying is `kyb deploy`, not a hand-rolled rsync.** It refuses to copy
+`node_modules` (native modules built on a laptop do not run on the host) or
+`.eve` (the durable store — copying over it eats production state), restarts
+detached so a dropped connection cannot SIGHUP the restart halfway, and waits
+for the script to report health rather than reporting success on exit code.
 
 ## What Vercel gives you that a client host does not
 

package/skills/.claude/skills/certification/SKILL.md

@@ -1,75 +0,0 @@
----
-description: Use when running evals, certifying an agent or an eve version bump, debugging eval failures, or preparing a release — the Kybernesis QA discipline and its run hygiene.
----
-
-# Certification & eval discipline
-
-The rule: **evals gate every deploy, and the consuming agent's suite is the
-release gate for every package change.** Nothing ships on "it looks right" —
-green suite or it doesn't go.
-
-## The suite
-
-`kybernesisBaseline()` from `@kybernesis/evals` in `evals/kybernesis.eval.ts`:
-smoke (boots, replies, identifies itself), five memory evals (no memory
-thrash on greetings; explicit remember never refused; proactive storage;
-brain-note two-step in order; cross-session unprompted recall), one routing
-eval per department, and with `engineer: true` the vision-loop eval
-(screenshot tool fires and the judge confirms the model SAW the render).
-Judge model is configured in `evals/evals.config.ts` and must NEVER be the
-model under test.
-
-## Run hygiene (each rule ate a real run)
-
-- `npm run eval` — always through the npm script: it forces every Arcana
-  workspace to `<name>-eval` so evals never write into a real brain.
-- **Kill any running dev server first** (`pkill -f "eve dev"`) — eve eval
-  attaches to an existing instance and runs stale code.
-- **Never edit the repo mid-run** — the dev runtime watches `agent/`; an
-  edit breaks the rebuild and kills remaining evals.
-- Engineer eval: hosted Vercel sandbox (no Docker), needs `vercel link` +
-  `vercel env pull` (VERCEL_OIDC_TOKEN). Warm template ≈3–4 min; a
-  pre-first-deploy cold bake is budgeted 20 min.
-- Stale sandbox state (migration errors, re-baking templates):
-  `rm -rf .eve/sandbox-cache .eve/dev-runtime` and rerun.
-- Don't pipe the eval command through `tail` in scripts — it masks the exit
-  code (and `| tail -N` on a backgrounded run destroys the per-eval detail —
-  `tee` to a file instead).
-- **Heavy-model suites: `maxConcurrency: 1` locally.** At 2, long opus turns
-  overload the local world-queue transport (`Queue delivery failed … fetch
-  failed`); crashed deliveries REPLAY subagent steps, surfacing as
-  `lost continuationToken` races and phantom failures that move between runs.
-  The deployed runtime uses real queue infra — this is a local-harness limit.
-- **AI Gateway budget is a silent eval killer**: Vercel applies a default
-  per-project budget (e.g. $10/daily); a suite of real opus turns can exhaust
-  it MID-RUN → `MODEL_CALL_FAILED` on whatever ran last. Check/raise:
-  `vercel ai-gateway budgets list` / `budgets set project <name> --limit 30
-  --refresh-period monthly`.
-- **"run parked on N unanswered input request(s)"** = the agent called a
-  human-in-the-loop tool (`approval: status=pending tool=ask_question` in the
-  turn log) — no one answers in an eval. Usually a behavior finding: the
-  fixture was self-contained and the agent asked instead of acting. Fix the
-  agent's bias-to-act instructions, not the fixture.
-
-## eve version certification
-
-Clients pin the **Kybernesis-certified** eve version (`kyb upgrade` carries
-them there — never blind npm-latest). Certifying a new eve: bump in a branch
-→ typecheck → `npx eve info` → full suite → live smoke on the deployed
-surface → advance the pin in @kybernesis/create → record the certification.
-
-## When an eval fails
-
-Read the eval's transcript before touching fixtures. Order of suspicion:
-(1) environment (stale dev server, missing env, cold template), (2) a real
-behavior regression — fix the agent, (3) only THEN the fixture — and if a
-fixture changes, the reason becomes a comment on it. A failure that reveals
-a new failure mode becomes a new fixture: that is how the suite grew every
-guard it has.
-
-## Release flow (packages)
-
-Edit in `~/platform` → build → bump → human publishes (browser auth) →
-consuming agent bumps → **full suite green** → deploy → registry item update
-+ deploy if install files changed. Then propagate the lesson (see the
-`source-of-truth` skill).

package/skills/.claude/skills/connect-agents/SKILL.md

@@ -1,119 +0,0 @@
----
-description: Use when connecting two deployed eve agents so one can delegate to the other — "connect agent A to agent B", agent-to-agent communication, remote peers, cross-deployment delegation. Wires @kybernesis/dispatch edges end to end.
----
-
-# Connecting two eve agents (@kybernesis/dispatch)
-
-An **edge** lets one deployed eve agent call another as if it were a local
-subagent, with the human's identity carried across the hop. One edge covers a
-full question-and-answer round trip (the caller parks until the peer's callback
-returns). Wire the mirror-image edge only if the other agent should also be
-able to *initiate*.
-
-## Before wiring — gather the facts
-
-1. **Both repos' eve versions must be compatible** (`node_modules/eve/package.json`
-   in each). An old receiver silently drops principal forwarding and runs as
-   service identity — no error. Upgrade both ends together first if they differ.
-2. **Vercel identities** of both projects: team slug + project name as shown in
-   `npx vercel ls <project>` (slugs, not `team_…`/`prj_…` IDs).
-3. **Stable production URL** of the callee: `npx vercel inspect <latest-prod-url>`
-   → Aliases — then **verify the alias is OPEN before wiring it**:
-   `curl -s -o /dev/null -w "%{http_code}" <url>/eve/v1/health` must return
-   **200**. The `<project>-<team>.vercel.app` aliases commonly sit behind
-   Vercel SSO deployment protection (302 → vercel.com/sso-api) and CANNOT
-   receive dispatches; the shorter production alias is usually the open one.
-4. Both repos need `@kybernesis/dispatch` installed (`npm i @kybernesis/dispatch`).
-
-## Caller side — one file
-
-`agent/subagents/<peer-name>.ts` (file name = tool name the model routes to):
-
-```ts
-import { remotePeer } from "@kybernesis/dispatch";
-
-export default remotePeer({
-  envVar: "GTM_AGENT_URL",
-  description: "…",   // see below — this is the whole routing story
-});
-```
-
-**Write the description from the CALLEE's actual capabilities.** Read the peer
-repo's `agent/instructions*`, subagent descriptions, and skills, then write the
-concrete topics people ask about ("posting cadence, open GTM plays, outreach
-targets, content drafting in the house voice") — not a generic blurb. If the
-caller has local subagents with overlapping remits, differentiate explicitly or
-routing will be ambiguous.
-
-Set the env var on the caller's Vercel project:
-`printf "<stable-prod-url>" | npx vercel env add GTM_AGENT_URL production`
-
-## Receiver side — one file
-
-`agent/channels/eve.ts` on the callee:
-
-```ts
-import { dispatchChannel } from "@kybernesis/dispatch";
-
-export default dispatchChannel({
-  trustedPeers: [{ teamSlug: "<caller-team>", projectName: "<caller-project>" }],
-});
-```
-
-If the callee already has an authored `agent/channels/eve.ts` with app auth,
-either migrate it to `dispatchChannel({ trustedPeers, extraAuth: […] })` or add
-the peer by hand to BOTH the `vercelOidc({ subjects })` list and the
-`trustedForwarders` predicate — they must never drift apart. Never write
-`trustedForwarders: () => true`.
-
-## Verify
-
-1. `npx eve info` in both repos: 0 diagnostics; the caller's manifest gains a
-   `remoteAgents` entry (it does NOT appear in the local subagent count).
-2. `npm run typecheck` both.
-3. Deploy BOTH (`npx eve deploy` / git push per repo convention). The edge is
-   live only when both ends are.
-4. Live test from the caller's real surface (e.g. Slack): ask something only
-   the peer knows. Confirm delegation in the caller's reply, then check
-   telemetry (PostHog): the peer-side turn should carry the human's
-   distinct_id, plus the `eve:forwarded-by` attribute naming the caller.
-
-## Failure signatures
-
-- **403 on dispatch** → receiver has no authored eve channel, or the caller
-  isn't in `trustedPeers`. Check team slug/project name spelling — a typo
-  silently rejects everything.
-- **`principal_required` on the peer's user-scoped connections** → forwarding
-  isn't arriving: receiver predates forwarding, or the assertion was dropped.
-- **Peer never gets called** → routing description too vague, or it collides
-  with a local subagent's remit. Rewrite from the callee's real capabilities.
-- **Works locally, 401 in production** → caller's OIDC not accepted: the
-  receiver's `trustedPeers` names the wrong environment (default is
-  production-only) or wrong project.
-
-## Governed mode (control-plane edges — preferred when the client runs the admin)
-
-Instead of hand-enumerated peers, edges are GRANTED in the Kybernesis control
-plane and enforced with 300s A2A tokens. Full lifecycle proven live 2026-08-07
-(grant → dispatch → revoke → refused ≤5 min → re-grant → restored, no deploys).
-
-Setup, per agent (admin UI /agents):
-1. Register both agents as eve deployments — URL must be the OPEN production
-   alias (health 200; forms sanitize pasted punctuation as of this writing).
-2. Grant the edge on the CALLEE's panel ("Agent-to-agent edges" → allow calls
-   from <caller> + purpose; expiry optional — self-destructing edge).
-3. Mint each agent's credential (shown ONCE) → set as Sensitive env
-   `KYBERNESIS_AGENT_CREDENTIAL` on that agent's Vercel project.
-
-Then in code (dispatch ≥0.2.1 + enterprise ≥0.2.0 both installed):
-- caller: `remotePeer({ callee: "<EXACT registered name>", governed: { issuer },
-  envVar, fallbackUrl, description })` — envVar/fallbackUrl kept as overrides;
-  registry supplies the URL when the credential is present.
-- receiver: `dispatchChannel({ governed: { issuer, agent: "<own name>" } })`.
-
-Gotchas: names are case-sensitive ("Kyber" ≠ "kyber" — copy from the admin);
-credentials are one JWS line ~3 segments, an ES256 signature is 86 base64url
-chars — a truncated paste fails verification silently, so length-check it;
-scheduled/cron turns still forward no human (service identity at the peer);
-the deployed agent's model spend shares the project's AI Gateway budget with
-local eval runs — size the budget for BOTH or production goes model-dead.