@kybernesis/create 0.7.1 → 0.7.2

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

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

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

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