@pinecall/skills 0.1.0

package/skills/pinecall-quickstart/references/index.md

@@ -0,0 +1,123 @@
+---
+title: "Pinecall SDK"
+description: "Build real-time voice & messaging AI agents in TypeScript."
+---
+
+# Pinecall SDK
+
+**Build real-time voice & messaging AI agents in TypeScript.** One package, one WebSocket connection, all your channels.
+
+```bash
+npm install @pinecall/sdk
+```
+
+Pinecall is **code-first** voice AI: the agent runs inside your app, uses your database, calls your internal APIs, and handles tool calls as local functions. There are no webhooks to expose, no platform dashboard to configure, no JSON tool schemas to maintain separately from your code.
+
+```typescript
+import { Pinecall, tool } from "@pinecall/sdk";
+import { z } from "zod";
+
+const pc = new Pinecall();
+
+const agent = pc.agent("mara", {
+  prompt: "You are Mara, a friendly booking assistant.",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  phoneNumber: "+13186330963",
+  greeting: "Hello! How can I help you today?",
+  tools: [
+    tool({
+      name: "findSlots",
+      description: "Find available appointment slots for a date",
+      schema: z.object({ date: z.string(), service: z.string() }),
+      execute: async ({ date, service }) => calendar.getSlots(date, service),
+    }),
+  ],
+});
+```
+
+That snippet is a production-ready agent. The SDK auto-connects on construction, registers the agent, and starts accepting calls — phone, WebRTC, and chat. No `await pc.connect()` needed. Run it with `pinecall run agent/index.js` for a polished terminal UI.
+
+## What you can build
+
+- **Voice agents** — phone (Twilio), SIP, WebRTC widgets in the browser
+- **Messaging agents** — WhatsApp Cloud API, chat widgets
+- **Multi-channel agents** — the same agent handling phone, WhatsApp, and browser calls simultaneously
+- **Outbound campaigns** — programmatic outbound calls with TTS greetings
+- **Embedded copilots** — voice inside your web app via the React widget
+
+## How the SDK is organized
+
+The library has three core concepts. If you understand these, you understand the whole SDK:
+
+- **`Pinecall`** — the WebSocket client. Manages the connection, multiplexes between agents.
+- **`Agent`** — a configured personality (prompt, voice, LLM). Owns channels and emits events.
+- **`Call`** — a single live session. Created automatically when someone connects. You speak to it, configure it, end it.
+
+![Agent tree — one connection, many agents](/assets/diagrams/agent-tree.png)
+
+A single `Pinecall` instance can host many agents. A single agent can serve many channels. Every channel emits the same events on the agent — your code doesn't care whether the call came from a phone, a browser, or WhatsApp.
+
+## Advanced usage
+
+### Dynamic greetings
+
+The `greeting` config accepts a string, but also a callback that receives the `Call` object — useful for personalized greetings:
+
+```typescript
+const agent = pc.agent("mara", {
+  // ...
+  greeting: async (call) => {
+    const user = await db.findByPhone(call.from);
+    return `Hello ${user.name}! Ready to book?`;
+  },
+});
+```
+
+The `greeting` config is a shorthand. Under the hood it calls `call.say()` when the call connects, which sends text directly to TTS without going through the LLM. You can also use `call.say()` manually in the `call.started` event:
+
+```typescript
+agent.on("call.started", async (call) => {
+  const user = await db.findByPhone(call.from);
+  call.say(`Hello ${user.name}!`, { addToHistory: false });
+});
+```
+
+`addToHistory: false` tells the server to speak the text but not include it in the LLM conversation history — useful for ephemeral messages like "Please hold" or "One moment."
+
+### Multiple phone numbers
+
+Use `phoneNumbers` (plural) to attach several numbers with per-number overrides — ideal for A/B testing, multi-language support, or regional routing:
+
+```typescript
+const agent = pc.agent("mara", {
+  prompt: "You are Mara, a friendly assistant.",
+  llm: "openai/gpt-5-chat-latest",
+  phoneNumbers: [
+    { number: "+14155551234", language: "en", stt: "deepgram/flux", voice: "elevenlabs/sarah" },
+    { number: "+966501234567", language: "ar", stt: "deepgram/nova-3", voice: "elevenlabs/ahmad" },
+    "+13186330963",  // inherits agent defaults
+  ],
+});
+```
+
+Each number can override `language`, `stt`, `voice`, and `ringing`. The agent prompt, LLM, and tools stay the same — only the voice interface changes per number.
+
+## Where to go next
+
+| If you want to... | Read this |
+|---|---|
+| Get a call working in 5 minutes | [Quickstart](/quickstart) |
+| Understand the moving parts | [Concepts → Agents and Channels](/concepts/agents-and-channels) |
+| Build a phone agent | [Guides → Inbound Voice](/guides/inbound-voice) |
+| Build a WhatsApp bot | [Guides → WhatsApp](/guides/whatsapp) |
+| Embed voice in your web app | [Guides → WebRTC in the browser](/guides/webrtc-browser) |
+| Look up a method | [API Reference](/api/pinecall) |
+| Tune STT, TTS, or the LLM | [Reference → Providers](/reference/stt-providers) |
+
+## Philosophy
+
+Pinecall SDK is designed around one idea: **any existing app can add a voice agent without changing its architecture.**
+
+Traditional voice AI platforms make you adapt your app to them. Pinecall adapts to your app — your code stays where it is, your tools are local functions, your data never leaves your process. The voice server handles the hard real-time parts (audio transport, STT, TTS, VAD, turn detection); your code handles everything else (business logic, prompts, history, state).

package/skills/pinecall-quickstart/references/quickstart.md

@@ -0,0 +1,185 @@
+---
+title: "Quickstart"
+description: "From zero to a working voice agent in under 5 minutes."
+---
+
+# Quickstart
+
+Get a Pinecall voice agent answering calls in under 5 minutes.
+
+## 1. Install
+
+```bash
+npm install @pinecall/sdk
+```
+
+> Node.js ≥ 18. The only runtime dependency is `ws`.
+
+## 2. Get an API key
+
+Sign up at [pinecall.io](https://pinecall.io), grab your API key from the dashboard, and export it:
+
+```bash
+export PINECALL_API_KEY=pk_...
+```
+
+## 3. Create your agent
+
+Create `agent/index.js`:
+
+```typescript
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall();
+
+export 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?",
+});
+```
+
+## 4. Run it
+
+```bash
+pinecall run agent/index.js
+```
+
+You should see:
+
+```
+  ⚡ booting mara  ·  gpt-5-chat-latest · elevenlabs/sarah
+  ☎ listening (no phone — webrtc/chat only)
+```
+
+That's a running voice agent. It's connected to Pinecall's voice server, it has a personality, and it's waiting for someone to call.
+
+## 5. Talk to it
+
+The fastest way to test your agent — chat from the terminal:
+
+```bash
+pinecall chat mara
+```
+
+```
+  ⚡ Connected to mara
+
+  you › What can you help me with?
+  mara › I can help with all sorts of things! What do you need?
+```
+
+This uses the same LLM, prompt, and tools as a voice call — just over text.
+
+### From the browser
+
+For voice, connect from the browser using the [`@pinecall/web`](https://github.com/pinecall/web):
+
+```bash
+npm install @pinecall/web
+```
+
+```tsx
+import { VoiceWidget } from "@pinecall/web";
+
+export default function App() {
+  return (
+    <VoiceWidget
+      agent="mara"
+      tokenProvider={async () => {
+        const res = await fetch("/api/token");
+        return res.json();
+      }}
+    />
+  );
+}
+```
+
+You'll need a tiny backend endpoint to mint the token:
+
+```typescript
+app.get("/api/token", async (req, res) => {
+  const token = await mara.createToken("webrtc");
+  res.json(token);
+});
+```
+
+Click the widget, talk to Mara. She'll respond.
+
+## What just happened
+
+You created an agent (`mara`), gave her a personality, and connected a browser to her via WebRTC. The server handles STT (you speak → text), runs the LLM (text → response), and handles TTS (response → voice). WebRTC works automatically via tokens — no channel declaration needed.
+
+You didn't write a single line of WebSocket code, audio handling, or VAD logic. The SDK and the Pinecall server handle all of that.
+
+## Add a phone number
+
+Want Mara to answer phone calls too? Add `phoneNumber`:
+
+```typescript
+const mara = pc.agent("mara", {
+  // ...same as before
+  phoneNumber: "+13186330963",
+});
+```
+
+Now the same agent serves browser **and** phone calls. The events are identical — your code doesn't need to know which transport the call came in over.
+
+### Multiple numbers with per-number config
+
+Use `phoneNumbers` (plural) to attach multiple numbers with per-number overrides — ideal for A/B testing, multi-language support, or regional routing:
+
+```typescript
+const mara = pc.agent("mara", {
+  prompt: "You are Mara, a friendly voice assistant.",
+  llm: "openai/gpt-5-chat-latest",
+  phoneNumbers: [
+    // US number: English, fast native turns
+    { number: "+14155551234", language: "en", stt: "deepgram/flux", voice: "elevenlabs/sarah" },
+    // Saudi number: Arabic, requires Nova (Flux doesn't support Arabic)
+    { number: "+966501234567", language: "ar", stt: "deepgram/nova-3", voice: "elevenlabs/ahmad" },
+    // Simple — just a number, inherits agent defaults
+    "+13186330963",
+  ],
+});
+```
+
+Each number can override `language`, `stt`, `voice`, and `ringing`. The agent prompt, LLM, and tools stay the same — only the voice interface changes per number. This lets you test different STT providers, voices, or languages on the same agent without deploying separate instances.
+
+## Add a tool
+
+Tools are local functions with Zod schemas — auto-executed by the SDK:
+
+```typescript
+import { Pinecall, tool } from "@pinecall/sdk";
+import { z } from "zod";
+
+const lookupOrder = tool({
+  name: "lookupOrder",
+  description: "Look up an order by ID",
+  schema: z.object({ orderId: z.string() }),
+  execute: async ({ orderId }) => await db.orders.findOne(orderId),
+});
+
+const mara = pc.agent("mara", {
+  prompt: "You are Mara. Look up orders when asked.",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  language: "en",
+  greeting: "Hello! How can I help?",
+  tools: [lookupOrder],
+});
+```
+
+No webhook URL to expose. No manual event handler. Just a function that runs in your process.
+
+## Where to go next
+
+- **Build a real phone agent** → [Guides → Inbound Voice](/guides/inbound-voice)
+- **Build a WhatsApp bot** → [Guides → WhatsApp](/guides/whatsapp)
+- **Understand the architecture** → [Concepts → Agents and Channels](/concepts/agents-and-channels)
+- **Look up every method** → [API Reference](/api/pinecall)

package/skills/pinecall-reference/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pinecall-reference
+description: >-
+  Reference tables — CLI commands, STT/TTS/LLM providers, events, session limits, REST API. Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: cli, commands, stt providers, tts providers, llm providers, events, session limits, rest api, reference.
+license: MIT
+---
+
+# Reference
+
+Reference tables — CLI commands, STT/TTS/LLM providers, events, session limits, REST API.
+
+This skill bundles the official Pinecall documentation for **Reference**. 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 |
+|------|----------------|------|
+| **CLI** | Inspect agents, chat, test with specs, browse voices, and manage billing from the terminal. | [`references/reference/cli.md`](references/reference/cli.md) · [docs](https://docs.pinecall.io/reference/cli) |
+| **Events** | Every event the SDK emits, with payload shapes and timing. | [`references/reference/events.md`](references/reference/events.md) · [docs](https://docs.pinecall.io/reference/events) |
+| **STT Providers** | Speech-to-text providers, models, and tuning parameters. | [`references/reference/stt-providers.md`](references/reference/stt-providers.md) · [docs](https://docs.pinecall.io/reference/stt-providers) |
+| **TTS Providers** | Text-to-speech providers, voices, and tuning parameters. | [`references/reference/tts-providers.md`](references/reference/tts-providers.md) · [docs](https://docs.pinecall.io/reference/tts-providers) |
+| **LLM Providers** | Server-side LLM providers and configuration. | [`references/reference/llm-providers.md`](references/reference/llm-providers.md) · [docs](https://docs.pinecall.io/reference/llm-providers) |
+| **Session Limits** | Safety limits to prevent runaway sessions. | [`references/reference/session-limits.md`](references/reference/session-limits.md) · [docs](https://docs.pinecall.io/reference/session-limits) |
+| **REST API** | Static helpers for the Pinecall management API. No WebSocket needed. | [`references/reference/rest-api.md`](references/reference/rest-api.md) · [docs](https://docs.pinecall.io/reference/rest-api) |
+
+
+## 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`.*