@kybernesis/create 0.7.0 → 0.7.1

package/skills/.claude/skills/kybernesis-packages/SKILL.md

@@ -0,0 +1,148 @@
+---
+description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), engineer (build+ship), dispatch (agent-to-agent), connectors (Gmail/Calendar/remote MCP), local (the user's own machine), manage (Studio→agent), exe (off-Vercel hosting), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
+---
+
+# The Kybernesis packages
+
+Eleven packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
+`KybernesisAI/platform`. Registry: `https://registry.kybernesis.ai`
+(`eve registry add @kybernesis=https://registry.kybernesis.ai/r/{name}.json`,
+then `eve add @kybernesis/<item>`). Each covers one axis:
+
+- **arcana** — memory. Extension mount `arcana({ apiKey, workspace,
+  resolveWorkspace? })`. Workspace-scoped `kb_` keys (403 outside their
+  workspace — one key per brain). `resolveWorkspace` only from VERIFIED
+  session context, never model output, and only key-reachable workspaces.
+  Subagents: local extension mount (`subagents/<id>/extensions/arcana.ts`,
+  eve ≥0.30) or plain connection + skill copies. Header
+  `X-Kyberagent-Agent: <workspace>` required by the MCP.
+- **enterprise** — governance. Plain library (route auth can't ship in an
+  extension). `kybernesisAuth()` admits only control-plane IdentitySessions
+  WITH a grant for this agent (`authorization: Bearer` + `x-kybernesis-bundle`
+  headers; 401 no-creds, 403 agent_not_granted). Lazy JWKS — compiles without
+  KYBERNESIS_ISSUER. See the `control-plane` skill.
+- **multiplayer** — Slack conversation mechanics. `multiplayerSlackChannel()`
+  from `/slack` subpath: thread = shared session with per-speaker verified
+  identity, no-re-mention continuation, dual surface (verified
+  `surface: "channel"|"dm"` attribute + helpers from package root), `/new` DM
+  reset. Slack-only today.
+- **engineer** — build + ship. Extension: `screenshot` (renders in in-sandbox
+  Chromium, returns pixels the model SEES) + `deliver` (sandbox file → public
+  Blob URL; needs BLOB_READ_WRITE_TOKEN — one-liner:
+  `vercel blob create-store <name>-deliverables --access public --yes`) +
+  six skills (dev-loop, scaffold, visual-qa, git-discipline, ship,
+  architecture-notes). The registry item ALSO writes
+  `agent/sandbox/sandbox.ts` — the workshop: Playwright baked into the
+  template at DEPLOY time, backend PINNED to Vercel Sandbox (no Docker
+  anywhere, local runs use hosted sandboxes via `vercel link` + `env pull`),
+  domain allowlist = the client's security posture. Ship loop: preview deploys
+  via the Vercel MCP connection (inline file tree, no git needed, no token in
+  the VM); production promotion is ALWAYS human-approved.
+- **dispatch** — agent-to-agent. `remotePeer({ envVar, description })` under
+  `agent/subagents/` = a separately DEPLOYED eve agent as a callable peer
+  (eve's `defineRemoteAgent` underneath: durable park→callback dispatch);
+  `dispatchChannel({ trustedPeers, extraAuth? })` as `agent/channels/eve.ts` =
+  the receiver, one declaration feeding BOTH the OIDC subjects allowlist and
+  `trustedForwarders`. Principal forwarding ON by default — the peer runs as
+  the human who asked. `() => true` trust is not expressible. Peers are
+  production-environment by default. BOTH ends must run compatible eve
+  versions (old receivers silently drop forwarding → service identity).
+  Composes with enterprise via `extraAuth: [kybernesisAuth(...)]`. See the
+  `connect-agents` skill for the end-to-end wiring flow.
+  **GOVERNED mode (≥0.2.1, proven live 2026-08-07):** `remotePeer({ callee:
+  "<registered-name>", governed: { issuer } })` + `dispatchChannel({ governed:
+  { issuer, agent } })` — edges granted in the control plane, outbound auth =
+  a 300s A2A token minted from POST /api/agent/session with the deployment's
+  `KYBERNESIS_AGENT_CREDENTIAL`, callee URL from the registry (envVar
+  overrides). Revoke in the admin → refused within the token TTL, no
+  redeploy. Names match EXACTLY (case-sensitive: "Kyber" ≠ "kyber").
+  Requires @kybernesis/enterprise ≥0.2.0 installed (optional peer, lazy).
+  0.2.1 lesson: eve resolves remote URLs at BOOT — url() must degrade
+  (env → discovery-if-credentialed → fallbackUrl), never throw on a missing
+  credential, or the whole agent (and its evals) fails to boot.
+- **connectors** — the user's SaaS accounts, brokered. `connectorTools()` is a
+  dynamic resolver: at turn start it asks the control plane which services THIS
+  principal has connected and returns those tools. Composio is the broker; the
+  API key is per-org, held in the control plane (never an env var, never a
+  client's key in our account). Tools are named `<toolkit>_<action>`. Also
+  exports `toolInputSchema` (broker JSON Schema → zod) and a minimal MCP client
+  for `mcp-direct` servers that speaks BOTH JSON and text/event-stream.
+- **local** — the user's own machine, through KYBER Studio. `localShellTool`,
+  `localRead/List/Write/Edit/SearchTool`, plus `localMcpTools()` for MCP servers
+  running on that machine, relayed. Every effect is consented in Studio; the
+  agent never holds a shell. `LOCAL_INSTRUCTIONS` explains the arrangement to
+  the model — mount it or the agent will offer to do things it cannot do.
+- **manage** — the other direction: `manageChannel()` lets Studio install
+  capabilities and write schedules onto a running agent, and `routineTools()`
+  turns "every morning at 8, brief me" into a real schedule file. This is how a
+  routine gets created from chat without anyone touching the repo.
+- **exe** — running off Vercel. `exeModel()` for exe.dev's LLM integration,
+  `grokSubscription()` / `readGrokCredential()` for a SuperGrok or X Premium+
+  login (`grok login` → `~/.grok/auth.json`, a valid bearer for api.x.ai —
+  same shape as eve's `experimental_chatgpt()`), `hostPreflight()`, Photon
+  iMessage credentials, and a `/preview` tool. Subpaths: `/slack`, `/photon`,
+  `/sandbox`, `/preview`. See the `self-hosting` skill.
+- **evals** — QA. `kybernesisBaseline({ agentDisplayName, routing,
+  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.
+
+## Gotchas that each cost a real debugging session
+
+- **Tool names are mount-dependent — ALWAYS suffix-match.** Extension mount →
+  `arcana__memory__arcana_remember`; plain connection → `arcana__arcana_remember`.
+  In approvals/hooks/evals: `toolName.endsWith("arcana_remember")`.
+- **Vercel Connect connectors: use the UID** (`mcp.vercel.com/vercel`), never
+  the short name, in `connect()`. No grant editor exists — changing scope =
+  detach → remove → create (same UID) → attach, then re-auth from a FRESH
+  session (stale sessions error without re-prompting).
+- **Dev servers in the sandbox start DETACHED** (nohup + background + log +
+  curl-poll) — a foreground server blocks the tool call and hangs the turn.
+  Verified-and-unchanged builds deploy WITHOUT re-running a server.
+- **Deliver/file links: post URLs as plain text** — markdown bold glues
+  asterisks onto the URL in Slack and breaks it. Coach agents in prose, not
+  shell (WAFs eat shell-syntax Slack messages).
+- **ESM packaging**: relative imports need `.js` extensions (tsc doesn't
+  rewrite); eve is a peer dep with an explicit range (`>=0.30.0 <0.31.0`),
+  pinned exactly in devDeps.
+- **Eval fixtures are hardened on purpose** — in-test nonces (eve caches
+  compiled eval modules), per-run unique keys (workspaces accumulate),
+  company-general wording (dept-flavored prompts delegate and hide tool
+  calls), no security vocabulary ("canary" triggers refusals), long routing
+  timeouts. Do not "clean up" the odd-looking patterns.
+- **A per-turn dynamic resolver needs a deadline.** `connectorTools()` and
+  `localMcpTools()` run before every turn and reach across a network. Without a
+  budget (6s) and a cache (60s connectors, 5min local discovery) one unreachable
+  laptop makes every turn hang — the agent looks broken and nothing in the log
+  says why.
+- **Composio: one request per toolkit.** Repeating `toolkit_slug` in a single
+  `/api/v3/tools` call returns an EMPTY list, so connecting a second service
+  silently emptied the first. The logo is at `meta.logo`, not `logo`. A 200 can
+  still carry `successful: false` — check the body, not the status.
+- **The broker's entity is the agent's REGISTERED name**, not its UUID.
+  `<agent>:<userId>`. Studio knows agents by id; normalize before you ask the
+  broker, or a connected account looks unconnected.
+- **MCP requires the handshake.** `initialize` AND `notifications/initialized`
+  before `tools/list`, or the server never answers. Spawn through a LOGIN shell
+  (a bare spawn misses the user's PATH and node) and always bind
+  `child.on("error")` — without it a failed spawn is an unhandled rejection
+  that takes the process, not a error message.
+- **Translate the MCP/broker inputSchema — never pass an open object.** A tool
+  with no declared arguments makes the model guess: nine calls to find a
+  `file_id` the server had documented all along. `mcpInputSchema` (local) and
+  `toolInputSchema` (connectors) do this; keep them permissive where the server
+  says nothing.
+- **Never wrap a model object in a Proxy.** The AI SDK's model methods depend on
+  their own `this`; intercepting them detaches it and every call dies inside the
+  SDK on a missing internal. To swap a credential, wrap `fetch` instead — and
+  re-read the credential per request: a Grok login expires in six hours and the
+  CLI refreshes it in place.
+- **Credentials are never a user's problem.** No client ever puts a key in a
+  `.env` — broker keys live per-org in the control plane, encrypted at rest, set
+  through an admin screen. A design that ends in "paste this token" is wrong.
+- **npm**: only the `kybernesis` account creates new packages in the scope;
+  publishes need the human's browser auth; new versions take 1–3 min to
+  propagate to anonymous reads.

package/skills/.claude/skills/self-hosting/SKILL.md

@@ -0,0 +1,206 @@
+---
+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 / Grok 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.
+
+## Running on the client's own subscription
+
+A client who already pays for ChatGPT Plus/Pro or SuperGrok / X Premium+ can
+run the agent on it instead of on metered API billing. Both work the same way:
+a CLI performs a device login on the host, writes a credential to the home
+directory, and that credential is a valid bearer for an OpenAI-compatible
+endpoint. eve ships `experimental_chatgpt()` for the first;
+`@kybernesis/exe` ships `grokSubscription()` for the second.
+
+```bash
+# on the host, as the user the agent runs as
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login          # device flow → ~/.grok/auth.json
+```
+
+```ts title="agent/agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { grokSubscription } from "@kybernesis/exe";
+
+export default defineAgent({
+  model: grokSubscription({ model: "grok-4.6", createOpenAI }),
+  modelContextWindowTokens: 400_000,
+});
+```
+
+What this arrangement costs you, and it is worth saying to the client:
+
+- **It is per-machine and per-user.** The login belongs to the host's home
+  directory. Moving the agent means logging in again; running it as a different
+  unix user means it cannot see the credential at all.
+- **The token expires in hours** (Grok: six) and the CLI refreshes it in place.
+  Read it per request, never once at boot, or the agent works all afternoon and
+  starts failing authentication at dinner for no reason a user can see.
+- **Nobody has proven unattended refresh over days.** If no one runs `grok` on
+  that host, whether the refresh keeps happening is an open question — and it
+  presents as the agent "breaking".
+- **Ask the vendor's terms question before a client demo**, not after.
+
+## 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.
+
+## Third-party APIs: version pinning and spec-derived calls
+
+Two failures here cost most of a day on the first deployment. Both look like
+outages or permission problems and are neither.
+
+**Pin the API version the SPEC describes, not the one in a doc example.**
+Notion's OpenAPI spec describes their current API (`/v1/data_sources/…`), but
+eve's docs example pins `Notion-Version: 2022-06-28`, where that endpoint does
+not exist. The mismatch returns `invalid_request_url`, `service_unavailable`
+(503) on search, and "not shared with the integration" — three different lies,
+none of them about the actual problem. Verify by making the SAME call the agent
+makes, headers included.
+
+**When the agent and your manual test disagree, the difference between the two
+requests IS the bug.** Diff them at the first contradiction. Repeatedly proving
+"the token works" with a hand-written curl while the agent fails proves nothing
+if your curl sends a different version header.
+
+**An agent's error message is a hypothesis, not evidence.** It will confidently
+report an outage or a permissions problem it has not verified. Read the actual
+request and response before acting — and never change a client's permissions on
+an agent's say-so.
+
+**Large specs with ambiguous ID schemes need a purpose-built tool, not a raw
+connection.** Notion's spec is ~1.2MB and splits `database_id` from
+`data_source_id` for the same board; a model deriving calls from it picks the
+wrong one. Pin the endpoint and the IDs in a small tool
+(`agent/tools/<domain>.ts`), keep the generic connection for the long tail, and
+point the instructions at the tool.
+
+**Credential brokering (exe http-proxy) is the right default off-Vercel:**
+
+```
+integrations add http-proxy --name <svc> --target https://api.example.com \
+  --header 'Authorization:Bearer <token>' --header '<Version-Header>:<value>' \
+  --attach vm:<vm>
+```
+
+Use `--header` for the token, not `--bearer=-`: the stdin form mangles it and
+the API answers 401 "token is invalid".
+
+## Restarts must be proven, not assumed
+
+A restart that silently fails leaves the agent serving a stale build — new
+connections, tools, and instructions never appear, and every later test measures
+yesterday's agent. Assert the process started AFTER the build it should serve
+(`scripts/eve-server.sh` and the restart pattern in `@kybernesis/exe` do this).
+Related: a long-lived channel session caches the compiled agent, so start a
+fresh conversation after changing capabilities.
+
+A restart script also has to **serialize** (`flock`, released by the child with
+`9>&-`) and **wait for in-flight turns** — eve does not resume a step killed
+mid-flight, and restarting into a live turn strands the session behind a turn
+that will never finish.
+
+Run restarts **detached** from your ssh connection —
+`setsid nohup bash restart.sh >/tmp/r.log 2>&1 </dev/null &` — or a dropped
+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
+phantom "second server" that `ps -eo pid,ppid,args` would have dismissed
+immediately. Inside a script file it is safe; typed at a shell it is not. List
+the matches before you believe the count.

package/skills/.claude/skills/source-of-truth/SKILL.md

@@ -0,0 +1,60 @@
+---
+description: Use whenever a lesson is learned, a bug is fixed, a package/registry/playbook/doc changes, or something shipped — the checklist that keeps the Kybernesis knowledge system the single source of truth. Also use when unsure where a piece of knowledge belongs.
+---
+
+# Source of truth — and how it stays that
+
+The knowledge system only works if every change lands in the right place the
+same day it happens. This skill is the routing table and the checklist.
+
+## Where truth lives
+
+| Kind of knowledge | Canonical home |
+| --- | --- |
+| How to run an engagement | `packages/create/skills/fde-engagement/references/playbook.md` (THIS package) — the Obsidian copy is a mirror, never edit it first |
+| How to build eve agents / packages / control plane / certification | the sibling skills in `packages/create/skills/` |
+| Package behavior + install steps | each package's README + registry item in `~/platform` |
+| Framework truth | `node_modules/eve/docs/` at the pinned version — never restate at length, point at it |
+| What exists, what's specced, what's parked | the system-overview doc (session-handoff master, Obsidian) |
+| Session-to-session working context | the Claude project memory (`~/.claude/projects/.../memory/`) — pointers and lessons, not content that belongs above |
+
+Secrets live in env managers only. Client-specific facts live in the client's
+repo and brain, never in this suite.
+
+## The propagation checklist — run it whenever any of these happens
+
+**A live failure taught something / a gotcha was paid for:**
+1. Encode it where the next run will hit it: a skill in this suite, a package
+   README, an eval fixture, or a `kyb doctor` check — prefer executable
+   guards (doctor/evals) over prose.
+2. If it changes engagement procedure → edit `references/playbook.md` here,
+   then copy to the Obsidian mirror.
+3. Bump `@kybernesis/create`, build, commit — the human publishes.
+4. Add one line to the Claude project memory if future sessions need it
+   before they'd naturally read this suite.
+
+**A package changed (version, API, install steps):**
+1. README + registry item updated in the same commit as the change.
+2. Consuming agent bumped, suite green (the release gate), deployed.
+3. Version references in the playbook §3.4 pin list + system overview updated.
+4. If install/setup steps changed → the relevant skill here too.
+
+**Something new was built or shipped:**
+1. System overview: move it into "shipped and verified" with the evidence.
+2. Playbook: add the operational steps if an FDE will ever repeat them.
+3. This suite: extend the matching skill (or add one) if Claude needs it.
+
+**A framework (eve) version was certified:**
+1. Advance the pin in `@kybernesis/create` (`EVE_VERSION`).
+2. Check every skill/playbook claim that names framework behavior — versions
+   change what's true (example: "subagents cannot mount extensions" was true
+   on 0.29, false on 0.30, and stale in four places until a maintainer
+   review caught it).
+
+## The standing rule
+
+If you (Claude) finish a piece of work and cannot point at where its lesson
+now lives, the work is not done. When unsure where something belongs, the
+answer is almost always "the most executable place that the next person or
+agent will actually hit" — doctor check > eval fixture > skill > playbook >
+memory, in that order of preference.

package/skills/fde-engagement/references/playbook.md

@@ -2032,6 +2032,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 +2259,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/self-hosting/SKILL.md

@@ -193,6 +193,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