@pinecall/skills 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @pinecall/skills
+
+**Agent Skills for the [Pinecall](https://pinecall.io) SDK.** Drop the Pinecall
+docs into any agent (Claude Code, Google Antigravity, Cursor, GitHub Copilot,
+Codex — anything that speaks the open [Agent Skills](https://github.com/agentskills/agentskills)
+format) so it builds voice & chat agents the right way, offline, with the
+correct defaults.
+
+Each skill is a folder with a `SKILL.md` + a `references/` tree of the real docs
+pages, loaded on demand (progressive disclosure). The whole package is
+**generated from `sdk/docs/`** — one source of truth feeds the docs site, the
+`/ask` knowledge base, and these skills.
+
+## Install
+
+```bash
+# the open installer (softaworks/agent-toolkit) — picks an agent dir + symlinks
+npx skills add pinecall/skills
+```
+
+Or manually copy the skills you want into your agent's skills directory:
+
+| Agent | Directory |
+|-------|-----------|
+| Claude Code | `.claude/skills/` |
+| Google Antigravity | `.agents/skills/` (or the plugin's `skills/`) |
+| Cursor / others | per the agent's docs |
+
+```bash
+cp -R skills/pinecall-guides ~/your-project/.claude/skills/
+```
+
+## What's inside
+
+| Skill | Covers |
+|-------|--------|
+| `pinecall-quickstart` | Install + first voice agent |
+| `pinecall-concepts` | Agents/Channels/Calls, server vs client LLM, hot reload, topologies |
+| `pinecall-guides` | Inbound/outbound, WhatsApp, tools, events, takeover, WebRTC, multi-tenant, testing… |
+| `pinecall-examples` | Copy-paste full agents |
+| `pinecall-sdk-api` | `@pinecall/sdk` API (Pinecall / Agent / Call / ReplyStream) |
+| `pinecall-web-voice` | `@pinecall/web/core` — browser WebRTC voice |
+| `pinecall-web-widget` | `@pinecall/web` React widget |
+| `pinecall-web-chat` | `@pinecall/web/chat` — text chat |
+| `pinecall-web-components` | Framework-agnostic web components |
+| `pinecall-reference` | CLI, STT/TTS/LLM providers, events, limits, REST |
+| `pinecall-security` | Security model |
+
+Every skill carries the **house rules** so the agent never drifts:
+`stt: "deepgram/flux"`, `llm: "openai/gpt-5-chat-latest"`, `voice: "elevenlabs/sarah"`,
+never `nova-2`, and never set `turnDetection`/`vad` by hand.
+
+## Regenerate (keep in sync with the docs)
+
+The `skills/` tree is generated and committed. Whenever `sdk/docs/` changes,
+re-run the generator and commit the result — same flow as re-pushing the docs KB.
+
+```bash
+node build.mjs                      # reads ../sdk/docs by default
+DOCS_DIR=/path/to/sdk/docs node build.mjs
+```
+
+The generator maps each `docs.json` navigation group to one skill, copies that
+group's pages into `references/`, and writes a `SKILL.md` index + the house
+rules. No dependencies.

package/build.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * @pinecall/skills — generator.
+ *
+ * Nourishes an Agent-Skills package straight from the SDK docs.
+ * Reads `sdk/docs/docs.json` + each page's frontmatter and emits one skill per
+ * docs group:  skills/<skill>/SKILL.md  +  skills/<skill>/references/<page>.md
+ *
+ * Re-run whenever `sdk/docs/` changes — same flow as the KB push. Output is
+ * committed (so `npx skills add pinecall/skills` works offline).
+ *
+ *   node build.mjs            # default DOCS_DIR=../sdk/docs
+ *   DOCS_DIR=/path node build.mjs
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = resolve(HERE, process.env.DOCS_DIR || "../sdk/docs");
+const OUT_DIR = join(HERE, "skills");
+
+// --- House rules: injected into every SKILL.md so each skill is self-correcting.
+const HOUSE_RULES = `## House rules — always apply
+
+- **Example defaults** (use these exact strings unless the user asks otherwise):
+  \`stt: "deepgram/flux"\`, \`llm: "openai/gpt-5-chat-latest"\`, \`voice: "elevenlabs/sarah"\`.
+  **NEVER use \`deepgram/nova-2\`** — it is not supported. Use \`deepgram/nova-3\`
+  only for languages Flux doesn't support (e.g. Arabic).
+- **Turn detection & VAD are auto-derived from the STT provider — never set
+  \`turnDetection\` or \`vad\` manually.** Flux → native turns + native VAD;
+  every other STT → \`smart_turn\` + \`silero\`.
+- **Greeting**: inbound → \`greeting\` field in \`pc.agent()\`; outbound → \`greeting\`
+  field in \`agent.dial()\`. It is sugar for \`call.say()\` in \`call.started\`.
+- **Auth**: \`new Pinecall()\` reads \`PINECALL_API_KEY\` from env and auto-connects.
+- Full documentation: <https://docs.pinecall.io>`;
+
+// --- Canonical example every voice skill should anchor on.
+const CANONICAL_EXAMPLE = `\`\`\`typescript
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall(); // reads PINECALL_API_KEY, auto-connects
+
+const agent = pc.agent("mara", {
+  prompt: "You are Mara, a friendly voice assistant. Be concise.",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  language: "en",
+  greeting: "Hello! How can I help?",
+});
+\`\`\``;
+
+// --- docs.json group name -> skill metadata. Unknown groups fall back to slug.
+const GROUP_MAP = {
+  "Get Started": {
+    slug: "pinecall-quickstart",
+    blurb: "Install @pinecall/sdk and build your first voice agent in minutes.",
+    keywords: "install, quickstart, first agent, pc.agent, PINECALL_API_KEY, pinecall run",
+  },
+  Concepts: {
+    slug: "pinecall-concepts",
+    blurb: "The mental model — Pinecall, Agent, Channel, Call; server- vs client-side LLM; hot reload; deployment topologies.",
+    keywords: "agents and channels, server vs client llm, hot reload, deployment, mental model, architecture",
+  },
+  Guides: {
+    slug: "pinecall-guides",
+    blurb: "Task guides for building Pinecall agent features.",
+    keywords: "inbound, outbound, whatsapp, tools, function calling, events, live listening, conversation history, human takeover, webrtc, multi-tenant, dev mode, testing, agent.dial, call.say, tool()",
+  },
+  Examples: {
+    slug: "pinecall-examples",
+    blurb: "Copy-paste recipes — full working agents for common scenarios.",
+    keywords: "example, recipe, sample, outbound dispatch, chat bot, browser widget, multi-channel, headless",
+  },
+  "@pinecall/sdk (Node.js)": {
+    slug: "pinecall-sdk-api",
+    blurb: "@pinecall/sdk API reference — Pinecall, Agent, Call, ReplyStream.",
+    keywords: "api, pc.agent, agent.dial, call object, reply stream, replyStream, server sdk surface",
+  },
+  "@pinecall/web/core (Voice)": {
+    slug: "pinecall-web-voice",
+    blurb: "@pinecall/web/core — browser WebRTC voice (VoiceSession, state & phases, DataChannel protocol).",
+    keywords: "webrtc, voice session, browser voice, datachannel, @pinecall/web/core",
+  },
+  "@pinecall/web (React Widget)": {
+    slug: "pinecall-web-widget",
+    blurb: "@pinecall/web React widget — VoiceWidget props, theming, useVoiceSession hook, client tools.",
+    keywords: "react widget, voicewidget, useVoiceSession, theming, props, client tools, @pinecall/web",
+  },
+  "@pinecall/web/chat (Chat)": {
+    slug: "pinecall-web-chat",
+    blurb: "@pinecall/web/chat — browser text chat (ChatSession, ChatView).",
+    keywords: "chat, chatsession, text chat, @pinecall/web/chat",
+  },
+  "@pinecall/web (Web Components)": {
+    slug: "pinecall-web-components",
+    blurb: "@pinecall/web web components — framework-agnostic custom elements.",
+    keywords: "web components, custom element, framework-agnostic widget",
+  },
+  Reference: {
+    slug: "pinecall-reference",
+    blurb: "Reference tables — CLI commands, STT/TTS/LLM providers, events, session limits, REST API.",
+    keywords: "cli, commands, stt providers, tts providers, llm providers, events, session limits, rest api, reference",
+  },
+};
+
+const slugify = (s) =>
+  "pinecall-" +
+  s.toLowerCase().replace(/@pinecall\/?/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+// Minimal frontmatter reader (title + description), no deps.
+function frontmatter(md) {
+  const m = md.match(/^---\n([\s\S]*?)\n---/);
+  const fm = {};
+  if (m) {
+    for (const line of m[1].split("\n")) {
+      const kv = line.match(/^(\w+):\s*"?(.*?)"?\s*$/);
+      if (kv) fm[kv[1]] = kv[2];
+    }
+  }
+  return fm;
+}
+
+function loadPage(slug) {
+  const file = join(DOCS_DIR, slug.endsWith(".md") ? slug : slug + ".md");
+  if (!existsSync(file)) return null;
+  const md = readFileSync(file, "utf8");
+  const fm = frontmatter(md);
+  return {
+    slug,
+    file,
+    md,
+    title: fm.title || slug.split("/").pop(),
+    description: fm.description || "",
+  };
+}
+
+// --- main
+const docsJson = JSON.parse(readFileSync(join(DOCS_DIR, "..", "docs.json"), "utf8"));
+const groups = docsJson.navigation.groups;
+
+if (existsSync(OUT_DIR)) rmSync(OUT_DIR, { recursive: true });
+mkdirSync(OUT_DIR, { recursive: true });
+
+const built = [];
+for (const group of groups) {
+  const meta = GROUP_MAP[group.group] || { slug: slugify(group.group), blurb: group.group, keywords: "" };
+  const skillDir = join(OUT_DIR, meta.slug);
+  mkdirSync(join(skillDir, "references"), { recursive: true });
+
+  const pages = group.pages.map(loadPage).filter(Boolean);
+
+  // Copy each page into references/, build the index rows.
+  const rows = [];
+  for (const p of pages) {
+    const refRel = join("references", p.slug + ".md");
+    const refAbs = join(skillDir, refRel);
+    mkdirSync(dirname(refAbs), { recursive: true });
+    writeFileSync(refAbs, p.md);
+    rows.push(
+      `| **${p.title}** | ${p.description || "—"} | [\`${refRel}\`](${refRel}) · [docs](https://docs.pinecall.io/${p.slug}) |`
+    );
+  }
+
+  const isVoice = /quickstart|guides|examples|sdk-api/.test(meta.slug);
+  const description =
+    `${meta.blurb} Use when the user is building, configuring, or debugging with @pinecall/sdk. ` +
+    `Keywords: ${meta.keywords}.`;
+
+  const body = `---
+name: ${meta.slug}
+description: >-
+  ${description.replace(/\n/g, " ")}
+license: MIT
+---
+
+# ${group.group}
+
+${meta.blurb}
+
+This skill bundles the official Pinecall documentation for **${group.group}**. The
+table below indexes every page; open the \`references/…\` file for the full text
+(loaded on demand). Source of truth: <https://docs.pinecall.io>.
+
+| Page | What it covers | Open |
+|------|----------------|------|
+${rows.join("\n")}
+
+${isVoice ? "## Canonical agent\n\n" + CANONICAL_EXAMPLE + "\n" : ""}
+${HOUSE_RULES}
+
+---
+*Generated from \`sdk/docs/\` by \`@pinecall/skills\` — do not edit by hand; edit the
+docs and re-run \`node build.mjs\`.*
+`;
+
+  writeFileSync(join(skillDir, "SKILL.md"), body);
+  built.push({ slug: meta.slug, group: group.group, pages: pages.length });
+}
+
+// eslint-disable-next-line no-console
+console.log(`Built ${built.length} skills from ${DOCS_DIR}:`);
+for (const b of built) console.log(`  ${b.slug.padEnd(26)} ${String(b.pages).padStart(2)} pages  (${b.group})`);

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@pinecall/skills",
+  "version": "0.1.0",
+  "description": "Agent Skills for the Pinecall SDK — installable into Claude Code, Antigravity, Cursor, Copilot and any agent that supports the open Skills format.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://docs.pinecall.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pinecall/skills"
+  },
+  "keywords": [
+    "pinecall",
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "antigravity",
+    "voice-ai",
+    "sdk"
+  ],
+  "files": [
+    "skills",
+    "build.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs"
+  }
+}

package/skills/pinecall-concepts/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: pinecall-concepts
+description: >-
+  The mental model — Pinecall, Agent, Channel, Call; server- vs client-side LLM; hot reload; deployment topologies. Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: agents and channels, server vs client llm, hot reload, deployment, mental model, architecture.
+license: MIT
+---
+
+# Concepts
+
+The mental model — Pinecall, Agent, Channel, Call; server- vs client-side LLM; hot reload; deployment topologies.
+
+This skill bundles the official Pinecall documentation for **Concepts**. The
+table below indexes every page; open the `references/…` file for the full text
+(loaded on demand). Source of truth: <https://docs.pinecall.io>.
+
+| Page | What it covers | Open |
+|------|----------------|------|
+| **Philosophy** | Why Pinecall is code-first and what that means for your architecture. | [`references/concepts/philosophy.md`](references/concepts/philosophy.md) · [docs](https://docs.pinecall.io/concepts/philosophy) |
+| **Agents and Channels** | The mental model: how Pinecall, Agent, Channel, and Call fit together. | [`references/concepts/agents-and-channels.md`](references/concepts/agents-and-channels.md) · [docs](https://docs.pinecall.io/concepts/agents-and-channels) |
+| **Server-side vs Client-side LLM** | The single most important architectural decision when building a Pinecall agent. | [`references/concepts/server-vs-client-llm.md`](references/concepts/server-vs-client-llm.md) · [docs](https://docs.pinecall.io/concepts/server-vs-client-llm) |
+| **Hot-Reload** | Change voice, language, prompt, tools — even during an active call. | [`references/concepts/hot-reload.md`](references/concepts/hot-reload.md) · [docs](https://docs.pinecall.io/concepts/hot-reload) |
+| **Deployment Topologies** | Embedded, standalone, or headless — pick the topology that fits your architecture. | [`references/concepts/deployment-topologies.md`](references/concepts/deployment-topologies.md) · [docs](https://docs.pinecall.io/concepts/deployment-topologies) |
+
+
+## House rules — always apply
+
+- **Example defaults** (use these exact strings unless the user asks otherwise):
+  `stt: "deepgram/flux"`, `llm: "openai/gpt-5-chat-latest"`, `voice: "elevenlabs/sarah"`.
+  **NEVER use `deepgram/nova-2`** — it is not supported. Use `deepgram/nova-3`
+  only for languages Flux doesn't support (e.g. Arabic).
+- **Turn detection & VAD are auto-derived from the STT provider — never set
+  `turnDetection` or `vad` manually.** Flux → native turns + native VAD;
+  every other STT → `smart_turn` + `silero`.
+- **Greeting**: inbound → `greeting` field in `pc.agent()`; outbound → `greeting`
+  field in `agent.dial()`. It is sugar for `call.say()` in `call.started`.
+- **Auth**: `new Pinecall()` reads `PINECALL_API_KEY` from env and auto-connects.
+- Full documentation: <https://docs.pinecall.io>
+
+---
+*Generated from `sdk/docs/` by `@pinecall/skills` — do not edit by hand; edit the
+docs and re-run `node build.mjs`.*

package/skills/pinecall-concepts/references/concepts/agents-and-channels.md

@@ -0,0 +1,155 @@
+---
+title: "Agents and Channels"
+description: "The mental model: how Pinecall, Agent, Channel, and Call fit together."
+---
+
+# Agents and Channels
+
+The Pinecall SDK has four nouns. Understanding them is most of understanding the SDK.
+
+## The four nouns
+
+![The four nouns — Pinecall, Agent, Channel, Call](/assets/diagrams/four-nouns-hierarchy.png)
+
+### `Pinecall` — the client
+
+One per process. Owns the WebSocket connection to `voice.pinecall.io`, handles auth and reconnection, and multiplexes events across multiple agents. **Auto-connects on construction.**
+
+```typescript
+const pc = new Pinecall(); // reads PINECALL_API_KEY from env, connects automatically
+```
+
+### `Agent` — a personality
+
+A configured assistant. Has a name (the agent ID), a voice, an STT provider, an LLM config, and a list of tools. Listens for events; owns channels.
+
+```typescript
+const agent = pc.agent("support", {
+  voice: "elevenlabs/sarah",
+  language: "en",
+  llm: "openai/gpt-5-chat-latest",
+  stt: "deepgram/flux",
+  prompt: "...",
+});
+```
+
+You can have many agents on the same `Pinecall` instance — `support`, `sales`, `intake` — each with their own personality and channels.
+
+### `Channel` — a way to reach the agent
+
+A surface through which calls arrive. Some channels need explicit registration; others work automatically:
+
+```typescript
+// Phone number — declared in config
+const agent = pc.agent("support", {
+  phoneNumber: "+13186330963",
+  whatsapp: [{ phoneNumberId: "123", accessToken: "..." }],
+});
+
+// Or imperatively:
+agent.addPhoneNumber("+13186330963");
+agent.addWhatsapp({ phoneNumberId: "123", accessToken: "..." });
+
+// WebRTC + Chat: work via tokens, no registration needed
+const token = await agent.createToken("webrtc");
+```
+
+Channel types:
+
+| Type | Registration | How users connect |
+|---|---|---|
+| `phone` | `phoneNumber: "+1..."` | Call the number |
+| `whatsapp` | `whatsapp: [{...}]` | Send a WhatsApp message |
+| `webrtc` | **None** (automatic) | Browser widget + token |
+| `chat` | **None** (automatic) | WebSocket + token |
+
+### `Call` — a live session
+
+Created automatically when someone connects on a channel. You receive a `Call` object in the `call.started` event. Use it to:
+
+- Speak (`call.say`, `call.reply`, `call.replyStream`)
+- Control the call (`call.hangup`, `call.forward`, `call.hold`)
+- Update mid-call (`call.update`, `call.setPrompt`, `call.addContext`)
+- Read state (`call.transcript`, `call.from`, `call.duration`)
+
+## Creating an agent
+
+### With `phoneNumber` (declarative)
+
+Pass a phone number directly in the config:
+
+```typescript
+const mara = pc.agent("mara", {
+  voice: "elevenlabs/sarah",
+  language: "es",
+  llm: "openai/gpt-5-chat-latest",
+  stt: "deepgram/flux",
+  prompt: "You are Mara. Be concise.",
+  phoneNumber: "+13186330963",
+});
+```
+
+WebRTC and Chat work automatically — no declaration needed. Just create tokens.
+
+### With `agent.addPhoneNumber()` (imperative)
+
+Use `agent.addPhoneNumber()` when you need per-number config overrides:
+
+```typescript
+const mara = pc.agent("mara", {
+  voice: "elevenlabs/sarah",
+  language: "es",
+  llm: "openai/gpt-5-chat-latest",
+  stt: "deepgram/flux",
+  prompt: "You are Mara. Be concise.",
+});
+
+mara.addPhoneNumber("+13186330963", {
+  voice: "elevenlabs/daniel",
+});
+```
+
+## Per-number config overrides
+
+The agent has defaults. Each phone number can override voice, language, and STT. This is how you give the same agent different settings per number:
+
+```typescript
+const agent = pc.agent("support", {
+  llm: "openai/gpt-5-chat-latest",
+  stt: "deepgram/flux",
+  voice: "elevenlabs/sarah",
+  phoneNumber: { number: "+34911234567", voice: "elevenlabs/valentina", language: "es" },
+});
+```
+
+For multiple numbers with different overrides — including STT provider — use `phoneNumbers`:
+
+```typescript
+const agent = pc.agent("global-support", {
+  prompt: "You are a multilingual support agent.",
+  llm: "openai/gpt-5-chat-latest",
+  phoneNumbers: [
+    { number: "+14155551234", language: "en", voice: "elevenlabs/sarah", stt: "deepgram/flux" },
+    { number: "+34612345678", language: "es", voice: "elevenlabs/valentina", stt: "deepgram/flux" },
+    // Arabic requires Nova-3 (Flux doesn't support it)
+    { number: "+972501234567", language: "ar", voice: "elevenlabs/ahmad", stt: "deepgram/nova-3" },
+  ],
+});
+```
+
+The agent's prompt, tools, and LLM stay the same — only the audio surface changes per number. Turn detection and VAD are auto-derived from the STT provider (Flux → native, Nova-3 → smart_turn + silero).
+
+## Why this design
+
+The agent-and-channels split exists because voice agents have two completely different concerns:
+
+1. **Who the agent is** — personality, knowledge, tools, business logic
+2. **How users reach it** — a phone number, a SIP trunk, a browser widget, a WhatsApp chat
+
+Most platforms conflate the two: you build a "Twilio bot" or a "WhatsApp bot." Pinecall keeps them separate so you can build the agent once and expose it through whatever channel you need today (or tomorrow).
+
+## What's next
+
+- [Server-side vs client-side LLM](/concepts/server-vs-client-llm) — the most important architectural decision
+- [Hot-reload](/concepts/hot-reload) — change voice, language, prompt, or tools mid-call
+- [Deployment topologies](/concepts/deployment-topologies) — embedded, standalone, or headless

package/skills/pinecall-concepts/references/concepts/deployment-topologies.md

@@ -0,0 +1,120 @@
+---
+title: "Deployment Topologies"
+description: "Embedded, standalone, or headless — pick the topology that fits your architecture."
+---
+
+# Deployment Topologies
+
+Pinecall agents are just Node.js processes. Where you run them is your choice. There are three common topologies — each is valid, each has tradeoffs.
+
+## The fundamental split
+
+Before topology, understand the two communication patterns:
+
+**1. Backend channels** — phone, SIP, WhatsApp. These talk to your Node.js process via the SDK's WebSocket. Your code receives events through an in-process EventEmitter.
+
+![Backend channels flow](/assets/diagrams/backend-channels-flow.png)
+
+**2. Browser channels** — WebRTC and chat. The browser connects **directly** to `voice.pinecall.io`. Your backend's only job is minting short-lived tokens.
+
+![Browser channels — WebRTC token flow](/assets/diagrams/webrtc-browser-arch.png)
+
+This split is why some topologies support SSE event streaming and others don't — SSE requires the agent to be in the same process as your web server.
+
+## Topology 1: Embedded
+
+Agent runs inside your existing web app (Express, Next.js, Hono, Remix). The web server and the agent share a Node.js process.
+
+![Embedded topology](/assets/diagrams/deployment-embedded.png)
+
+**Pros:**
+- SSE streaming works (you can build live dashboards)
+- One deployment unit — easy ops
+- Token endpoint is one route away from the agent
+
+**Cons:**
+- The agent process restarts every time you deploy the web app
+- Web traffic and voice traffic share resources
+
+**When to use:** small apps, dashboards that need live call event streaming, single-team projects.
+
+## Topology 2: Standalone
+
+Agent runs as a separate process from your web app. The web app handles HTTP, the agent process handles voice.
+
+![Standalone topology](/assets/diagrams/deployment-standalone.png)
+
+**Pros:**
+- Independent deploys — restart the agent without touching the web app
+- Independent scaling — give the agent its own resources
+- Crash isolation — a web bug doesn't kill calls in flight
+
+**Cons:**
+- No SSE — the web app can't stream events from the agent process directly. If you need live dashboards, the agent has to expose its own SSE endpoint or push to a shared bus (Redis, NATS).
+- Two deployments to manage
+
+**When to use:** higher-traffic apps, when ops cares about independent scaling, when you want to avoid the "web deploy kills in-flight calls" problem.
+
+## Topology 3: Headless
+
+No web server at all. Just the agent. Use this when you only need phone/SIP/WhatsApp — no browser channels, no dashboards, no tokens to mint.
+
+```typescript
+// agent/index.js — a complete production agent, no web server needed
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall();
+
+export const agent = pc.agent("support", {
+  prompt: "You are a support agent for an online store...",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  language: "en",
+  phoneNumber: "+13186330963",
+  greeting: "Hi! How can I help?",
+  tools: [lookupOrder, processReturn],
+});
+```
+
+Run it with `pinecall run agent/index.js` for a polished boot banner and live transcript.
+
+**Pros:**
+- Lowest possible complexity
+- No HTTP surface to attack or maintain
+- Easy to ship as a container, a systemd unit, or a serverless function
+
+**Cons:**
+- No browser channels (no WebRTC, no chat) unless someone else mints tokens
+- No SSE
+- No dashboards from this process
+
+**When to use:** IoT devices, intercoms, single-purpose phone bots, WhatsApp-only bots, scheduled outbound campaigns.
+
+## Comparison
+
+| Feature | Embedded | Standalone | Headless |
+|---|---|---|---|
+| SSE (`agent.stream()`) | ✅ | ❌ | ❌ |
+| WebRTC / Chat | ✅ | ✅ (token from web app) | ❌ (or you build it) |
+| Phone / SIP | ✅ | ✅ | ✅ |
+| WhatsApp | ✅ | ✅ | ✅ |
+| Outbound calls | ✅ | ✅ | ✅ |
+| Operational complexity | Medium | Medium | **Lowest** |
+| Independent scaling | ❌ | ✅ | ✅ |
+| Crash isolation | ❌ | ✅ | n/a |
+
+## Which one should you pick?
+
+- **Just starting out** — embedded. Get something running, split later if you need to.
+- **You need browser channels and a dashboard** — embedded.
+- **You're scaling and ops cares** — standalone.
+- **You're shipping a fixed-purpose device or WhatsApp-only bot** — headless.
+
+Migration between topologies is cheap. The agent code is the same in all three. You're just choosing where to run it.
+
+## What's next
+
+- [Multi-tenant dashboards](/guides/multi-tenant) — embed multiple agents, scope events per user
+- [Dev mode](/guides/dev-mode) — run prod and dev agents on the same phone number
+- [SSE streaming reference](/reference/events) — for embedded dashboards