# Naïve — Agent Setup Manifest (skill.md)

> Naïve is the control plane for agent infrastructure. It gives AI agents real-world identity, payments, communications, and 100+ primitives behind one API key — one bearer token, one credit balance, one CLI. This file tells you how to set it up and what you can do.

## How to use this manifest
1. Get an API key, then install the CLI or SDK (see Onboarding).
2. Pick the primitives you need from Capabilities and call them.
3. Use the Reference links for full request/response schemas before writing integration code.

## Onboarding

### 1. Get authenticated (do this WITH the user — never invent credentials)
You need an API key before any primitive works. Do NOT stop, fail, or improvise probes if one isn't present — walk the user through onboarding interactively, and confirm the details with them before submitting anything:

- **Already have a key?** Ask the user to paste it, then `export NAIVE_API_KEY=nv_sk_live_...` (both the CLI and SDK read this env var). Keys come from https://dashboard.usenaive.ai, look like `nv_sk_live_...`, and are server-side secrets — never log or echo them.
- **New user?** Register a fresh account (includes 20 free credits). Ask the user for their name, email, and a password (8+ chars), confirm, then run `naive register --name "<name>" --email "<email>" --password "<password>"` (saves the key to `~/.naive/config.json`).
- **Existing account, prefer passwordless?** `naive link --email "<email>"`, then `naive verify --email "<email>" --code <6-digit-code>` using the code from their inbox.

Always ask the user for these values — do not guess emails, passwords, or keys.

### 2. Choose a surface

**CLI** (terminal + agentic use — every command returns structured JSON with `next_steps`):
```bash
npm install -g @usenaive-sdk/cli
# authenticate — pick ONE (see step 1):
export NAIVE_API_KEY=nv_sk_live_...                                          # existing key
# or: naive register --name "My Agent" --email me@example.com --password <pw>   # new account
naive status                        # verify auth + credits
```

**SDK** (embed in a multi-tenant backend — Stripe-style scoped client):
```ts
import { Naive } from "@usenaive-sdk/node";
const naive = new Naive({ apiKey: process.env.NAIVE_API_KEY! });
// Solo mode acts on your default user:
await naive.cards.create({ spending_limit_cents: 25000 });
// Multi-tenant: create a user, then scope with forUser(id):
const alice = await naive.users.create({ external_id: "alice_db_uuid" });
await naive.forUser(alice.id).cards.create({ spending_limit_cents: 25000 });
```

**MCP** (hand tools to an MCP-native agent like Claude or Cursor):
- SSE transport at `https://api.usenaive.ai/mcp/sse` with header `Authorization: Bearer nv_sk_...`

**REST** (anything that can hit HTTP):
- Base URL `https://api.usenaive.ai`, header `Authorization: Bearer nv_sk_...`

### 3. Verify connectivity
- No-auth health check: `GET https://api.usenaive.ai/health` → `{"status":"ok"}`. Use this to confirm the network/host is reachable before authenticating.
- Authenticated routes (including the base URL `https://api.usenaive.ai/`) return `403` without a valid key. A bare `403` means you *reached* the server, not that the network is blocked — do not treat it as a connectivity failure or assume a proxy is in the way.
- Once authenticated, `naive status` confirms auth + remaining credits.

## Core concepts
- **Multi-tenant** — every primitive acts on a tenant *user*. Use `naive use <id>` / `--user <id>` (CLI) or `naive.forUser(id)` (SDK) to scope per customer.
- **Account Kits** — per-user whitelists that gate which primitives a tenant can call.
- **One credit balance** — usage is metered per call across every category.
- **Approvals & audit** — sensitive actions can be approval-gated; every action streams to one audit log.

## Capabilities (primitives)

Each row lists a primitive, what it does, and a representative CLI command.

### Identity & Company
- **Verification (KYC)** — Hosted identity verification for founders/members. `naive verification start --members '[...]'`
- **Formation** — Real US LLC formation — submit, track, download docs. `naive formation submit --state WY ...`
- **Connections** — Autonomous OAuth connections to 3rd-party services. `naive connections connect gmail`
- **Browser** — Cloud browser + autonomous signup/login (credentials vaulted). `naive browser signup figma.com https://figma.com/signup`

### Money
- **Cards** — Virtual cards for agent spending with hard limits. `naive cards create --name "Marketing" --spending-limit 5000`
- **Billing** — Your Naïve plan, credit top-ups, transactions. `naive billing topup`

### Communications
- **Email** — Custom-domain inboxes, send/receive. `naive email send --from-inbox <uuid> --to ... --subject ... --body ...`
- **Domains** — Auto-provisioned + custom domains, agent DNS editing. `naive domains connect`

### Knowledge
- **Search** — Web search, URL extraction, deep research. `naive search "latest AI agent frameworks"`
- **LLM** — Chat completions across 300+ models via one router. `naive llm chat -m anthropic/claude-sonnet-4.6 "..."`

### Media
- **Images** — Generate AI images and stock photos. `naive images generate "product mockup"`
- **Video** — Generate AI video (Kling, Minimax, Wan). `naive video generate "..."`
- **Clips & Media** — Create/edit clips and manage media assets. `naive clips create / naive media list`

### Distribution
- **Social** — Post & schedule across 10+ platforms, analytics. `naive social post "..." --platforms twitter,linkedin --publish`
- **SEO** — Keyword research, backlinks, competitor analysis. `naive seo keywords google search-volume --keywords "..."`
- **AEO** — AI search optimization + LLM response tracking. `naive aeo llm-responses chatgpt --keyword "..."`

### Market Data
- **E-commerce** — Product listings, pricing, sellers (Google, Amazon). `naive ecommerce google products --keyword "..."`
- **App Data** — App rankings, reviews, metadata (Play, App Store). `naive app-data google app-info --app-id ...`
- **Reviews & Travel** — Reputation, reviews, and hotel/place intelligence. `naive business google reviews / naive business tripadvisor search`

### Build & Cloud Infrastructure
- **Apps** — Vercel-hosted Next.js apps with optional Supabase backend. `naive apps create`
- **Database / Storage / Functions / Auth** — Managed Postgres, storage, edge functions, and end-user auth on a fullstack app. `naive apps db tables <id>`
- **Compute** — Run Docker containers, background workers & scheduled jobs (ECS/Fargate) — services, jobs, schedules, with a shell. `naive compute create --type service --image ...`
- **Queue** — Durable work queues (SQS) for agent pipelines — pairs with compute workers. `naive queue create --name jobs`

### Orchestration
- **CEO** — Persistent gateway that decomposes objectives into tasks. `naive ceo run "..."`
- **Employees** — Hire/configure AI workers. `naive employees hire --role "..."`
- **Tasks & Objectives** — Kanban tasks and strategic goals. `naive tasks create --assignee "..." --title "..."`
- **Cron & Memory** — Scheduled jobs and persistent agent context. `naive cron create / naive memory add`

### Governance
- **Vault** — Per-user encrypted credential storage. `naive vault put instantly.api_key key_xyz`
- **Approvals & Logs** — Human-in-the-loop gates and a unified audit log. `naive approvals list / naive logs`
- **Sessions & Webhooks & Jobs** — Per-user MCP sessions, event webhooks, async tracking. `naive jobs`

## Templates (pre-built starting points)
Apply a pre-built blueprint (agents, tasks, and apps) to bootstrap a working setup in seconds.
```bash
naive templates list
naive templates apply faceless-media-channel
```
- Browse the full catalog: https://usenaive.ai/templates

## Reference material
- Docs home: https://usenaive.ai/docs
- Quickstart: https://usenaive.ai/docs/getting-started/quickstart
- Introduction & primitives overview: https://usenaive.ai/docs/getting-started/introduction
- Authentication: https://usenaive.ai/docs/getting-started/authentication
- Credits & pricing: https://usenaive.ai/docs/getting-started/credits
- API reference: https://usenaive.ai/docs/api-reference/overview
- CLI reference: https://usenaive.ai/docs/cli/overview
- SDK reference: https://usenaive.ai/docs/sdk/overview
- MCP server: https://usenaive.ai/docs/mcp/overview
- Docs index for crawlers: https://usenaive.ai/docs/llms.txt
- Site index: https://usenaive.ai/llms.txt

## Suggested first run
```bash
npm install -g @usenaive-sdk/cli
export NAIVE_API_KEY=nv_sk_live_...   # existing key — or: naive register --name "..." --email ... --password ...
naive status
naive verification start --members '[...]'   # give your agent a real-world identity
naive cards create --name "Ops" --spending-limit 5000   # scoped spending
naive search "..."                          # start calling primitives
```