@kybernesis/create 0.7.1 → 0.7.3

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

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

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

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

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

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