@kybernesis/create 0.7.0 → 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/doctor.js

@@ -247,7 +247,11 @@ export async function doctor() {
         // deployment is incomplete. This is NOT a value to go and set by hand: the
         // switch in Studio installs it, and a missing one means nobody has turned
         // local access on yet.
-        if (process.env.KYBERNESIS_AGENT_CREDENTIAL) {
+        // `env`, not `process.env`: every other check reads the merged view, and
+        // reading the bare environment here reported a missing credential on an
+        // agent whose .env.local had one two lines above. A preflight tool that
+        // cries wolf is a preflight tool people learn to skip.
+        if (env.KYBERNESIS_AGENT_CREDENTIAL) {
             add("pass", "local execution can identify this agent to the control plane");
         }
         else {
@@ -257,7 +261,7 @@ export async function doctor() {
     if (hasManage) {
         // manage authorizes with the caller's control-plane grant, so it needs to
         // know which agent it IS before it can check one.
-        if (process.env.KYBERNESIS_AGENT) {
+        if (env.KYBERNESIS_AGENT) {
             add("pass", "management routes can resolve this agent's grants");
         }
         else {

package/dist/init.js

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, 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, engineerPlan, envExample, evalFileTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
@@ -111,6 +111,31 @@ export async function init(rawName, options = {}) {
     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));
+    /**
+     * A self-hosted agent gets its restart script installed, not described.
+     *
+     * There is no deploy pipeline off Vercel, so restarting IS the release — and
+     * the script that does it carries every lesson that path has cost: serialize
+     * concurrent restarts, build when the source moved, wait for in-flight turns,
+     * and count servers by what they are rather than by who mentions them.
+     *
+     * It used to ship inside @kybernesis/exe with a line in the docs telling
+     * people where to find it, which means a new deployment starts with none of
+     * that and rediscovers it one outage at a time.
+     */
+    if (host === "exe") {
+        const source = join(dir, "node_modules/@kybernesis/exe/scripts/eve-server.sh");
+        const target = join(dir, "scripts/eve-server.sh");
+        try {
+            mkdirSync(join(dir, "scripts"), { recursive: true });
+            copyFileSync(source, target);
+            chmodSync(target, 0o755);
+            console.log(dim("     scripts/eve-server.sh — restart with proof (serialized, builds if stale)"));
+        }
+        catch {
+            console.log(yellow("  ! could not install scripts/eve-server.sh — copy it from node_modules/@kybernesis/exe/scripts/"));
+        }
+    }
     if (plan.file) {
         console.log(bold(`\n4/6  Channel: ${channel} …`));
         mkdirSync(join(dir, "agent/channels"), { recursive: true });

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.0",
+  "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
@@ -2032,6 +2043,14 @@ because the session is stranded rather than stuck. Poll
 wait for it to clear — with a cap, so a wedged turn cannot block the restart
 that would clear it.
 
+*And build before you restart.* Proving the process started after the BUILD says
+nothing about whether the build reflects the SOURCE. A production agent ran for a
+day on a build ten hours older than its files, reporting "OK: serving the current
+build" every time. Worse, `@kybernesis/manage` calls the restart script after
+writing files — so **every capability installed from Studio reported success and
+changed nothing.** Build when the source has moved, and refuse to restart into a
+build that failed.
+
 *And measure it correctly.* `pgrep -f 'server/index.mjs'` run over ssh matches
 **the shell running the pgrep** — the pattern is in its own command line — so it
 reports two servers when there is one. An entire investigation went into hunting
@@ -2251,6 +2270,46 @@ The things that cost real sessions here:
   reach across a network to a laptop that might be shut. Budgeted at 6s with a
   five-minute cache; without that, one closed lid makes every turn hang.
 
+### 12.9 Rooms — several agents in one conversation
+
+A client with a planner, a designer, and an engineer agent can put all three in
+one room and work with them the way they would with people. The room lives
+entirely in the desktop app: each member keeps its own session with its own
+deployment, and the app is what puts a message in front of all of them. **No
+agent needs to know the feature exists**, which is what makes it work with an
+agent the client wrote themselves.
+
+**Addressing is the routing, and it is worth teaching in one line.** Name a
+member and only they answer. `@everyone` addresses the room. Name nobody and
+the room's lead answers — the first member — who brings the others in. Matching
+is literal and requires the `@`, because an agent called Design must not be
+summoned by the word "design" in an ordinary sentence.
+
+**Hand-offs are how work moves.** An agent's reply reaches another agent only
+when it names them, and whoever is brought in receives what they missed since
+they last spoke. Without that catch-up a hand-off is incoherent: the engineer is
+asked to "build this" having never seen what "this" is.
+
+Say these plainly to a client, because all three will come up:
+
+- **Every hop is a billed turn** on a deployed agent. A three-agent hand-off
+  chain is three turns, and there is a depth cap so a pair that keeps addressing
+  each other cannot run away.
+- **The convention is a prompt, not a protocol.** Each turn carries a line
+  telling the agent it is in a room and how to hand off. A well-behaved agent
+  follows it; nothing enforces it. A misbehaving one is ignored rather than able
+  to start a cascade — agent-to-agent relay has NO policy fallback, precisely so
+  one reply cannot become a reply from everyone.
+- **A relayed message runs under the human's identity.** When the planner hands
+  to the engineer, the engineer acts with that person's authority on another
+  agent's say-so. Among a client's own agents that is usually what they want.
+  It is still a governance decision, and it should be made rather than
+  discovered.
+
+What NOT to promise: emergent self-organisation. The chain works when someone —
+a person or an agent — explicitly hands off. It is a room where people and
+agents talk, not an autonomous workflow engine.
+
 ## 13. Known gaps — state these plainly, do not sell around them
 
 Being straight about these is a feature. Clients have met vendors who were not.

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
 
@@ -193,6 +203,11 @@ Run restarts **detached** from your ssh connection —
 connection SIGHUPs the script halfway through and leaves exactly the mess it
 exists to prevent.
 
+**Build before you restart.** Proving the process started after the build says
+nothing about whether the build reflects the source — an agent served a build ten
+hours older than its files while reporting success. It also breaks installs:
+`@kybernesis/manage` writes files and then calls the restart script.
+
 **And measure it correctly.** `pgrep -f 'server/index.mjs'` typed over ssh
 matches the shell running it: the pattern is in that shell's own command line,
 so it reports two servers when there is one. A whole investigation went into a