@kybernesis/create 0.7.1 → 0.7.2

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).