eve-registry-porting

---
name: eve-registry-porting
description: >-
  Port a tool, connection or skill from a public eve/Flue agent registry — atomeve.dev,
  evex.sh, agentcn, eveagents.dev, the "shadcn for agents" registries — into a multi-tenant
  eve app WITHOUT adopting the registry's standalone-agent runtime model. Its core is the
  conformance checklist that makes third-party eve code tenant-safe. Use when the user wants
  to "install / use / borrow an agent from atomeve (or evex / agentcn / eveagents)", "add a
  Stripe/PostHog/Sentry/GitHub tool or connection from a registry", "reuse a skill from a
  shadcn-for-agents registry", or asks whether a registry agent is usable and how to adapt it.
  Not for: scaffolding a fresh tool/connection/skill slot (use `eve-agent`), building the
  Next.js app or its pages (use design-md-to-app / screenshot-to-page / module-add), or wiring
  the monorepo (monorepo-bootstrap).
---

# eve-registry-porting — borrow the bricks, not the agent

The eve ecosystem has spawned **"shadcn for agents"** registries — you copy
source, not a dependency. They are a great **catalog + code mine**. But their
unit of distribution is a **standalone agent** (one eve project that runs itself
on a cron or from Slack), which is the **opposite** of a multi-tenant app where
**one interpreter wears profiles from a DB** and delegates in a hierarchy.

So the rule is: **port the components (tool / connection / skill), never the
agent-as-a-runtime**, and rewrite each one to be tenant-safe.

## Where porting sits — the sourcing priority

Porting is **third choice**, not first. Before vendoring third-party source, prefer a maintained option higher up the list:

1. **eve's official integrations** — discover + install from the CLI: **`eve registry search <cap>`** → **`eve add <kind>/<name>`** (catalog at <https://eve.dev/integrations> — 50+ MCP/OpenAPI connections, 11+ channels, official extensions). If the service is there, install and stop — don't port. (`eve-agent` → §Install from the registry FIRST / Connection / Channel.)
2. **Install a third-party registry as a source** — the community registries below are **shadcn-registry format**, so you can register one as an eve source (**`eve registry add @name=https://…/r/{name}.json`**, stored in `package.json#registries`) and pull with **`eve add @name/<slug>`**. That's an *install* (files written, dep tracked) — prefer it over porting whenever you **don't** need to own/modify the source. **The mechanism is verified** against `eve@0.45.0`'s own docs: *"eve stores the mapping in
`package.json#registries`. The `{name}` placeholder becomes the integration name, so `@acme/analytics`
resolves to `https://registry.acme.com/r/analytics.json`."* Narrow a query to one source with
`eve registry list --registry @acme` / `eve registry search <q> --registry @acme`.

**`[VERIFY]` each registry actually serves the shadcn JSON shape** — one `curl` and look at `$schema`;
it must be `https://ui.shadcn.com/schema/registry-item.json`. The four this skill set names were all
checked on **2026-08-26** and all four pass:

| Registry | Item URL pattern | `$schema` |
|---|---|---|
| mapcn (web maps) | `https://mapcn.dev/r/{name}.json` | ✓ shadcn registry-item |
| mapcn-rn (mobile maps) | `https://mapcn-rn.dev/maps/{name}.json` | ✓ shadcn registry-item |
| Coss/UI | `https://coss.com/ui/r/{name}.json` | ✓ shadcn registry-item |
| heroicons-animated | `https://www.heroicons-animated.com/r/{name}.json` | ✓ shadcn registry-item |
| hugeicons-animated | `https://hugeicons-animated.com/r/{name}.json` | ✓ shadcn registry-item — note it also serves a `registry:lib` file (`lib/use-icon-animation.ts`), so an item is not always one file |

⚠️ **Serving the shape is necessary, not sufficient.** `mapcn-rn` serves shadcn-format items *and*
ships its own `mapcn-rn` CLI with a `mapcn.json` of its own — install it the project's way, not through
`eve add`, or you get files without the config that tracks them. Check whether a registry has a first-party
installer before treating it as a plain source.
3. **An extension package** — a versioned npm bundle you install and `pnpm up` (`agent/extensions/<name>.ts`). (`eve-agent` → Extension.)
4. **Port / vendor from a public registry** — *this skill*. Use it when the source **isn't** installable as above (not registry-served) **or** you need to own/modify it. You take on tenant-hardening **and** maintenance by hand.
5. **Hand-write** from scratch — when nothing exists to borrow (`eve-agent` boilerplate).

Go down a rung only when the one above has nothing. Porting trades "no dependency, full control" for "you tenant-harden and maintain it forever" — worth it for the code mine or a source you must modify, not as a default now that `eve registry add` + `eve add` can install directly from shadcn-format registries.

## The registries

| Registry | URL | Install | Registry endpoint (checked 2026-08-26) |
|---|---|---|---|
| Atom Eve | https://www.atomeve.dev | `npx atom-eve create my-agent --agent <slug>` · `npx atom-eve add <slug>` | **no `/r/registry.json`** — own CLI only |
| **evex** | https://www.evex.sh | `npx shadcn add @evex/<slug>` | **`/r/registry.json`, 13 items, `$schema: ui.shadcn.com/schema/registry.json`** — items at `/r/{name}.json`, `type: registry:item` |
| agentcn | https://agentcn.vercel.app | `npx shadcn add <url>` | `/r/registry.json`, 76 items — but **no `$schema` declared**, and item names are namespaced (`eve/claw` → `/r/eve/claw.json`, *not* `/r/claw.json`) |
| eveagents | https://www.eveagents.dev | `npx @bergside/eveagents install <slug>` | not reachable at check time (HTTP 429) — own CLI anyway |

**Only evex declares the shadcn registry schema**, which makes it the one that slots cleanly into
`eve registry add @evex=https://www.evex.sh/r/{name}.json`. agentcn serves registry-shaped JSON without
declaring the schema *and* nests item names, so the `{name}` placeholder does not expand the way the
table above would suggest — install it by URL. The other two ship their own installers, which is a
decision they made, not an oversight to route around.

All community projects, not official Vercel. Framework source of truth:
https://github.com/vercel/eve.

## When this skill applies

- The user names a registry (atomeve / evex / agentcn / eveagents) or "shadcn
  for agents" and wants to use something from it.
- The user wants a capability (Stripe metrics, PostHog, Sentry triage, GitHub
  PRs, website QA) and a registry has an eve implementation to borrow.
- The user asks "can we install this agent / is it useful / how do we adapt it".

If instead the user wants to **author a new** tool/connection/skill from scratch
(no registry involved), use **`eve-agent`**. If they want to run the registry's
`npx … create` to spin up a **brand-new standalone agent project** (not a
multi-tenant app), that's the registry's own flow — this skill is for pulling
pieces INTO an existing multi-tenant eve app.

## Decision: is it portable?

```
Component in the registry
├─ a full standalone agent / schedule / Slack channel  → DO NOT adopt as runtime.
│                                                         Extract its bricks ↓
├─ a tool (defineTool)                → PORT (rewrite tenant-safe)
├─ a connection (OpenAPI / MCP)       → PORT (auth from tenant)
├─ a skill (defineSkill markdown)     → PORT (near drop-in)
└─ instructions / persona             → adapt into profile config (DB seed)
```

## Run the automatic review first

Before reading a registry component by hand, run **`registry-intake`** on it — it is read-only:

```bash
python3 registry-intake/scripts/registry_intake.py review <root> https://agentcn.vercel.app/r/eve/<slug>.json
```

It mechanically finds what this checklist otherwise relies on eyes for: tool keys the **installed** eve
loader rejects (V1), side-effect tools with no working `approval` (V2), global credentials (V3), a
single shared store (V4), US-shaped PII regexes (V5), a whole standalone agent (V6), host process
execution, npm licences and install scripts. A blocked report is usually the signal to **port** rather
than install: rewrite the bricks here, tenant-safe, instead of accepting findings one by one. What it
cannot judge — tenant derivation from the session, per-tenant secrets, the tests — stays below.

⚠️ **Verified 2026-09-15: agentcn's eve tools do not load on eve.** All 30 declare
`needsApproval: always()/never()`; eve's key is `approval`, and its loader throws on unknown keys
(eve 0.34, 0.51, 0.55). Porting one means renaming the key **and** re-deciding the gate: the five with
`always()` (`post_message`, `update_range`, `write_file`, `run_shell`, `generate_image`) are exactly
the ones that must ask, and `claw/run_shell` runs `node:child_process` on the host, not in eve's sandbox.

## Conformance checklist (the whole point)

Every ported component MUST pass these before merge. In a multi-tenant eve app
this is non-negotiable — registry code assumes single-tenant/global env.

- [ ] **Tenant from the verified session, never from model input.** Derive the
      tenant id from the session principal (in AgentOS:
      `sessionIdentity(ctx.session.auth)` → `companyId`), never from a Zod input
      field.
- [ ] **Tenant id in EVERY query** — no DB read/write without the tenant filter.
- [ ] **Per-tenant, encrypted secrets.** No global `process.env.<KEY>` for
      credentials: fetch the key from the tenant's connection, decrypted at
      runtime (AgentOS: `getConnectionSecret(companyId, provider)`), encrypted at
      rest (AES-256-GCM). Not connected → fail honest (e.g. 401), never fall back
      to a shared key.
- [ ] **No unverified npm deps.** Prefer plain `fetch` over adding a package;
      verify anything a component pulls in before installing. Never `pnpm add`
      unverified packages, especially not inside a subagent.
- [ ] **Sensitive actions gated.** A tool that acts in the world (email, shell,
      spend, open-PR) goes into the gated set + per-role grants + human approval
      where appropriate. For the concrete syntax/pattern — `approval: always()` /
      `once()` from `eve/tools/approval`, custom input-dependent policies, and why
      gating a side effect on approval is also what makes it replay-safe under
      eve's durable-workflow re-run semantics — see
      `eve-agent/references/eve-conventions.md` → "Durability & idempotency (the
      rule scaffolds get wrong)". Apply that pattern directly; don't reopen
      `eve-agent` to rediscover it. **The key is `approval`** — a registry tool
      written with `needsApproval` (the AI SDK's name) is rejected by eve's loader,
      so its gate never existed.
- [ ] **Framework hygiene.** Correct import paths (in a monorepo: `drizzle-orm`
      directly only in the agent, never in the web app); valid eve file names
      (tool files start with a letter).
- [ ] **License** of the individual component checked (registries are community,
      quality/licence vary per agent).
- [ ] **Verify via eve logs**, not just typecheck — read `eve dev` error logs
      after any agent change; eve has discovery/bundle rules `tsc` won't catch.

## Porting procedure

1. **Read the registry component's `SETUP`/source**: env, endpoints, deps.
2. **Classify** it (tool / connection / skill; if "whole agent", extract bricks).
3. **Rewrite into the target slot** applying the checklist — tenant from session,
   secrets per-tenant, queries filtered, no new unverified deps.
4. **Register a connection provider** if needed (connect/disconnect + encryption),
   and add it to the app's connections catalog.
5. **Gate sensitive tools** (tool-catalog + governance + approval).
6. **Add/extend tests** — tenant isolation + component logic.
7. **Verify**: eve error logs clean → typecheck → commit.

For the slot boilerplate itself (how a `defineTool`/`defineOpenAPIConnection`/
`defineSkill` is written and discovered), hand off to **`eve-agent`**.

## Project-specific reference

When working inside **AgentOS**, the concrete mapping (slots, provider
registration files, governance files, worked examples) lives in
`docs/eve-registries.md` in that repo — read it first; this skill is the
portable, project-agnostic version of the same discipline.