@kybernesis/create 0.6.0 → 0.7.1

package/dist/doctor.js

@@ -242,20 +242,26 @@ export async function doctor() {
     const hasLocal = existsSync(join(cwd, "agent/tools/local_shell.ts"));
     const hasManage = existsSync(join(cwd, "agent/channels/kyb.ts"));
     if (hasLocal) {
-        // Without the relay secret the tools compile, appear in the tool list, and
-        // fail at the moment the user asks for something — the worst time to learn
-        // a deployment is incomplete.
-        if (process.env.LOCAL_EXEC_AGENT_SECRET) {
-            add("pass", "local execution is configured (LOCAL_EXEC_AGENT_SECRET set)");
+        // Without a credential the tools compile, appear in the tool list, and fail
+        // at the moment the user asks for something — the worst time to learn a
+        // 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.
+        // `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 {
-            add("fail", "local execution has no LOCAL_EXEC_AGENT_SECRET", "the local_* tools will be offered to the model and fail on first use; set the shared secret the control-plane relay expects");
+            add("warn", "local execution is installed but this agent has no credential yet", "turn on 'Work on this computer' in the agent's settings in KYBER Studio — it mints and installs one; do not paste a credential by hand");
         }
     }
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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/.claude/skills/certification/SKILL.md

@@ -0,0 +1,75 @@
+---
+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

@@ -0,0 +1,119 @@
+---
+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.

package/skills/.claude/skills/control-plane/SKILL.md

@@ -0,0 +1,80 @@
+---
+description: Use when registering an agent with the Kybernesis control plane, granting/revoking user access, wiring kybernesisAuth, running the governance E2E check, or debugging 401/403s from a governed agent.
+---
+
+# The Kybernesis control plane (agent.kybernesis.ai)
+
+The control plane governs WHO may talk to which agent. It is an OIDC-style
+issuer (per-org ES256 keys at `/api/jwks`) minting **IdentitySessions**
+`{ issuer, token, bundle, jwks }`; the policy bundle carries
+`agentGrants[{agent, level}]`. Agents verify OFFLINE via
+`kybernesisAuth()` from `@kybernesis/enterprise` — no callback to the plane
+on each request.
+
+## Wiring a governed agent
+
+Env: `KYBERNESIS_ISSUER=https://agent.kybernesis.ai` and
+`KYBERNESIS_AGENT=<agent-name>` (must equal the name registered in the
+admin). The registry item writes the route-auth file; `kyb doctor` checks
+JWKS reachability. Callers send `authorization: Bearer <token>` +
+`x-kybernesis-bundle: <bundle>`. Expected failures: 401 = no/bad
+credentials; 403 `agent_not_granted` = valid user, no grant for THIS agent.
+
+## Admin flow (browser, agent.kybernesis.ai)
+
+Register the agent under Agents (runtime: ▲ eve + deployment URL — the row
+shows a health probe). Grant users under their profile (grants resolve at
+MINT time). Users page also links/revokes chat identities (Slack ↔ user).
+Sign-in for humans is RFC 8628 device flow (user code, e.g. ABCD-EFGH).
+
+## Timing semantics (the support-ticket section)
+
+Token TTL defaults to 1h — that IS the revocation SLA for already-minted
+sessions. Suspension blocks new mints immediately; revocation of a grant
+takes effect at next mint. Tune `IDENTITY_TOKEN_TTL_SECONDS` to the client's
+appetite and tell them the number.
+
+## The governance E2E check (run before any client demo)
+
+1. Call the governed agent with no credentials → expect 401.
+2. Mint via device flow WITHOUT a grant → call → expect 403 agent_not_granted.
+3. Grant the user in the admin → re-mint → call → expect 200/202.
+4. Revoke the grant → old token still works until TTL; re-mint refused.
+5. Suspend the user → mint refused immediately; restore → mint works.
+
+This exact sequence was verified against production 2026-08-05. The demo
+moment for clients is step 3→4 — access appearing and disappearing from the
+admin screen.
+
+## It also brokers connectors and the user's own machine
+
+Governance was the first job; the plane now also holds the two things an agent
+cannot hold itself.
+
+**Connectors** (`/api/connectors`, `link`, `disconnect`, `tools`, `execute`,
+`custom`, `mcp`, `mcp/test`). Each ORG holds its own broker (Composio) API key,
+encrypted at rest with `SECRET_ENCRYPTION_KEY` (AES-256-GCM,
+`v1:<iv>:<tag>:<ct>`), set
+through the admin — never an env var, never our key used for a client. The
+agent asks the plane which services the CURRENT principal has connected;
+`@kybernesis/connectors` turns the answer into tools for that turn only. The
+broker's entity is `<registered-agent-name>:<userId>` — the registered NAME,
+not the agent's UUID.
+
+**Local access** (`/api/local-exec/*`). A device enrolls, the user grants it
+once, and that grant is STANDING — no expiry. Requests and responses are relayed
+as frames; the plane never executes anything. See `@kybernesis/local`.
+
+**A client must refresh on the earlier of the token and the bundle.** They have
+independent lifetimes: a token with 57 minutes left and a bundle with 12 will
+start returning 401 while every dashboard says the session is fine. This cost a
+full day, presented to the user as "log out and log back in", and the fix is one
+line — `Math.min(tokenExpiry, bundleExpiry)`. On a 401, force a refresh and
+retry ONCE before showing a human anything.
+
+## Boundaries to state plainly
+
+Control-plane grants govern the HTTP/desktop doors — NOT the Slack door
+(Slack access = workspace membership). Person-scoped approvals and
+`governedSlackChannel()` are specced, not built. HITL approvals are
+session-scoped; any thread member can click them.

package/skills/.claude/skills/eve-building/SKILL.md

@@ -0,0 +1,106 @@
+---
+description: Use when building out an eve agent — adding channels (Slack, iMessage, Telegram, Discord…), connections to client systems, agent skills, model pinning, instructions, or testing in eve dev. The how-to for every eve authoring surface.
+---
+
+# Building eve agents
+
+**The prime rule: read the pinned docs before writing eve code.** The
+installed framework docs are the source of truth for THIS project's version:
+`node_modules/eve/docs/` (README.md indexes them). Never author a channel,
+connection, sandbox, or schedule from memory — read its doc page first.
+Fallback when docs are absent: https://eve.dev/docs.
+
+## The loop
+
+`read the doc → write the file → npx eve info (0 diagnostics) → test a turn
+in npx eve dev → eval`. Every authoring task follows it.
+
+## Model (agent/agent.ts)
+
+`defineAgent({ model })`. No agent.ts → defaults to anthropic/claude-sonnet-5;
+once the file exists, `model` is required. String = Vercel AI Gateway id
+(`anthropic/claude-opus-4.8`, dot version) — the client-deploy default.
+Direct provider: install `@ai-sdk/<provider>`, pass `anthropic("claude-opus-4-8")`
+(hyphen version) + provider key in env. Dynamic per-principal selection via
+`defineDynamic({ fallback, events })` — prefer `session.started` scope (prompt
+caches are per model). Docs: `agent-config.md`.
+
+## Channels (agent/channels/, one file per surface)
+
+Filename = channel id. eve normalizes every surface into one runtime — tools/
+instructions/memory never change per channel. Available: Slack, Photon
+(iMessage), Telegram, Discord, Teams, Twilio (SMS/voice), GitHub, Linear,
+web (eve HTTP + useEveAgent), custom (`defineChannel`). Install:
+`eve add channel/<name>` (e.g. `channel/photon-imessage`, `channel/telegram`).
+
+Setup is always three steps: (1) the channel file, (2) provider-side
+credentials in env — the HUMAN runs anything with a browser login, (3) point
+the provider at the mounted route (`/eve/v1/<channel>`). Each channel's doc
+page (`docs/channels/<name>.mdx`) has the complete recipe including webhook
+registration and HITL behavior. For Kybernesis Slack deploys use
+`@kybernesis/multiplayer` (group semantics) — see the `kybernesis-packages`
+skill.
+
+## Connections (agent/connections/)
+
+Search before writing: `eve registry list` / `search <term>` / `view <item>`
+/ `add <item>` (setup flows resume via `eve add <item> --skip-install`).
+Hand-author only for client-internal services. Two shapes: MCP server →
+`defineMcpClientConnection`; OpenAPI 3.x doc → `defineOpenAPIConnection`.
+Four auth modes: static token (`auth.getToken` from env — pilot default),
+Vercel Connect user-scoped (`connect("<connector-UID>")` — UID not short
+name; first use posts an OAuth link in-thread, turn parks + resumes), Connect
+app-scoped (`connect({connector, principalType:"app"})` — non-interactive),
+or none. Connector provisioning is CLI-able:
+`vercel connect create <service> --name <n>` + `vercel connect attach <uid> --yes`.
+Subagents have NO user principal — static or app-scoped only. Write the
+connection `description` as a capability naming the systems; decide surface
+gating (fail-closed) and `approval` gates per connection at install time.
+Docs: `docs/connections/*`.
+
+## Skills (agent/skills/)
+
+On-demand procedures (model calls `load_skill` when the description matches).
+Forms: flat `.md` (first line = routing description) → packaged dir with
+`SKILL.md` (+`references/`, description frontmatter required) → `defineSkill`
+(only for typed/generated content). The description is a ROUTING HINT — write
+it as the triggering task ("Use when…") and test by asking without naming the
+skill. Scoped per agent: subagents need their own copies (or subagent-local
+extension mounts that ship them). Community marketplace: skills.sh — included
+in `eve registry search`; install `eve add @skills/<owner>/<repo>/<name>`;
+ALWAYS review the diff before running. Docs: `docs/skills.mdx`.
+
+## Instructions (agent/instructions.md or instructions/)
+
+Always-on context: identity, tone, standing rules ONLY — procedures go in
+skills. Directory entries combine alphabetically (root file first); `.ts`
+entries wrap `defineInstructions` (compile-time) or `defineDynamic`
+(per-session, e.g. surface-aware greetings). Draft with Claude from discovery
+notes, then judge by test (eve dev turns + evals), never by reading.
+
+## Subagents (agent/subagents/<id>/)
+
+Inherit NOTHING. Own tools/skills/connections/instructions/sandbox; on eve
+≥0.30 also OWN extension mounts (`subagents/<id>/extensions/` — mounts only
+into that subagent). No channels/schedules; no user principal; whole job must
+fit one delegation call. Docs: `docs/subagents.mdx`.
+
+**Sandbox layout trap:** a FLAT `agent/sandbox.ts` is discovered but scopes to
+the ROOT agent only — subagents silently fall back to the default backend
+chain (Docker → microsandbox → just-bash), which surfaces as
+`opening sandbox session "subagents/<id>" on backend "docker"` in eval logs.
+Use the directory form `agent/sandbox/sandbox.ts` — that one is app-level and
+subagents get it free. (Cost a debugging session on eve-gtm, 2026-08-07.)
+
+**Parallel same-subagent delegation collides** (`Session … lost
+continuationToken … to session …`, failed subagent-result actions): two
+delegations to the SAME subagent fired in one step race on child sessions.
+Instruct serial delegation ("one draft at a time, wait for each result").
+
+## Test in eve dev
+
+`npx eve dev` boots the local runtime + chat TUI. Walk: identity → skill
+routing (watch load_skill) → delegation → memory round-trip → (engineer)
+screenshot turn. Local principal counts as a DM surface. Kill the dev server
+before `npm run eval`. The TUI is NOT the deployed agent — redeploy after
+every change.

package/skills/.claude/skills/fde-engagement/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Use when running or planning a Kybernesis FDE client engagement — pilot phases, discovery questions, day-by-day plan, demo script, handover. The operating manual for deploying an eve agent at a client.
+---
+
+# Kybernesis FDE engagement
+
+Kybernesis forward-deploys engineers into companies to agentify them: we build
+eve-framework agents the client reaches on surfaces they already use (Slack,
+iMessage, Telegram, web…), wired to their systems, governed by our control
+plane (agent.kybernesis.ai), remembering through Arcana, and quality-gated by
+evals. You (Claude) are the FDE's co-builder for all of it.
+
+The complete engagement runbook is `references/playbook.md` — READ THE PHASE
+YOU ARE IN before acting. Map of the playbook:
+
+- **Fast path**: `npm create @kybernesis <name> -- [--engineer]` scaffolds the
+  entire baseline (governance + memory + multiplayer Slack + evals, optional
+  engineer layer). `kyb doctor` checks wiring at any point.
+- **Phase 1–2**: pre-engagement checklist; the discovery conversation (agent
+  name, departments, SURFACES — never assume Slack, §2.3 — cohort, data
+  sensitivities). Leave discovery with the §2.6 table filled in.
+- **Phase 3**: environment setup — scaffold, `vercel link`, registry, version
+  pins (eve pinned to the Kybernesis-CERTIFIED version, never blind latest).
+- **Phase 4**: the build — model pinning (§4.0b), our packages (§4.1–4.3b),
+  channels/connections/skills for the client's stack (§4.3c–e), instructions
+  (§4.4), `eve dev` test-drive (§4.4b), subagents (§4.5), evals (§4.8).
+- **Phase 5–6**: deploy + control-plane registration and grants.
+- **Phase 7–9**: pilot onboarding, the acceptance demo script, handover.
+- **§10**: troubleshooting appendix — check it before debugging from scratch.
+- **§11**: known gaps — state them plainly to the client, never sell around.
+
+Non-negotiables that survive every engagement: production promotion is
+human-approved; evals gate every deploy; secrets live in env (Vercel
+Sensitive), never in code or memory; every live failure becomes a playbook or
+skill edit the same day (see the `source-of-truth` skill).