@pinecall/skills 0.1.0

package/skills/pinecall-web-voice/references/web/core/overview.md

@@ -0,0 +1,70 @@
+---
+title: "@pinecall/web/core"
+description: "Framework-agnostic WebRTC voice session client. Zero dependencies."
+---
+
+# @pinecall/web/core
+
+The browser-side counterpart to `@pinecall/sdk`. A framework-agnostic WebRTC client that handles the audio transport, mic access, and DataChannel events. Works with React, Vue, Svelte, vanilla JS, or any framework.
+
+```bash
+npm install @pinecall/web
+```
+
+> Zero runtime dependencies. Browser-only (requires `RTCPeerConnection` and `getUserMedia`).
+
+## What it does
+
+`@pinecall/web/core` is what the browser uses to talk to a Pinecall agent over WebRTC. It:
+
+- Fetches a short-lived token from your backend (or the voice server, in convenience mode)
+- Requests microphone access via `getUserMedia`
+- Opens a peer connection to `voice.pinecall.io`
+- Exposes the conversation as a reactive state object + an event stream
+
+It does **not** render UI. For a drop-in React widget with an animated orb, use [`@pinecall/web`](/web/widget/overview) (which is built on top of `@pinecall/web/core`).
+
+## Quick start
+
+```typescript
+import { VoiceSession } from "@pinecall/web/core";
+
+const session = new VoiceSession({ agent: "mara" });
+
+session.addEventListener("message", (e) => {
+  console.log(`${e.detail.message.role}: ${e.detail.message.text}`);
+});
+
+await session.connect();
+
+// later
+session.disconnect();
+```
+
+That's it. The session manages the connection lifecycle, mic, and transcript. You get a stream of structured events you can wire into any UI.
+
+## How it fits with the other packages
+
+![Web package architecture](/assets/diagrams/web-package-arch.png)
+
+- **You write**: agent logic in Node.js with `@pinecall/sdk`
+- **You drop in**: `@pinecall/web/core` (or `@pinecall/web`) in the browser
+- **The voice server**: handles the audio pipeline (STT, LLM, TTS, VAD) and forwards events both ways
+
+## Two interfaces: state + events
+
+`@pinecall/web/core` exposes the session two ways. Use whichever fits your framework:
+
+| Style | API | Best for |
+|---|---|---|
+| **Reactive state** | `session.subscribe(cb)` + `session.getState()` | React's `useSyncExternalStore`, Vue's `ref`, Svelte stores |
+| **Event listeners** | `session.addEventListener("message" \| "phase" \| "event" \| ...)` | Vanilla JS, imperative code, observability |
+
+You can mix them in the same app — they share the same underlying state machine.
+
+## What's next
+
+- [`VoiceSession` class](/web/core/voice-session) — constructor, methods, options
+- [State, phases, and transcripts](/web/core/state-and-phases) — the reactive state model
+- [DataChannel protocol](/web/core/datachannel-protocol) — every event the server emits
+- [`@pinecall/web`](/web/widget/overview) — the React widget built on `@pinecall/web/core`

package/skills/pinecall-web-voice/references/web/core/state-and-phases.md

@@ -0,0 +1,153 @@
+---
+title: "State and Phases"
+description: "The reactive state model: status, phases, transcript messages, and lifecycles."
+---
+
+# State and Phases
+
+The `VoiceSession` exposes a single reactive state object via `getState()`. This page covers what's in it and how it changes over the lifetime of a call.
+
+## State shape
+
+```typescript
+interface VoiceSessionState {
+  status: "idle" | "connecting" | "connected" | "error";
+  error: string | null;
+  isMuted: boolean;
+  phase: "idle" | "listening" | "speaking" | "pause" | "thinking";
+  userSpeaking: boolean;
+  agentSpeaking: boolean;
+  duration: number;             // seconds since connected
+  messages: TranscriptMessage[];
+  toolCalls: ToolUI[];          // active tool UI entries (only for tracked tools)
+  idleWarning: number | null;   // seconds until idle timeout (null = no warning)
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `status` | The connection lifecycle. `idle` → `connecting` → `connected` → (`idle` on disconnect, or `error`). |
+| `error` | Populated when `status === "error"`. Always check this when handling errors. |
+| `isMuted` | Mic state. Mirrors `setMuted()` / `toggleMute()`. |
+| `phase` | What the conversation is doing right now (see below). |
+| `userSpeaking` | `true` between `speech.started` and `speech.ended` events. Use for live waveform UIs. |
+| `agentSpeaking` | `true` while TTS is playing. |
+| `duration` | Seconds since `status` became `connected`. Updates every second. |
+| `messages` | Full transcript — user and bot turns. See [Transcript messages](#transcript-messages) below. |
+| `idleWarning` | When the server emits `session.idleWarning`, this holds the seconds remaining until timeout. `null` when no warning is active. |
+
+## Call phases
+
+`phase` tells you what the conversation is doing **right now**. It's the field you'll bind to UI state most often (orb color, animation, status label).
+
+| Phase | Meaning | Triggered by |
+|---|---|---|
+| `idle` | Not in a call | Initial state, after disconnect |
+| `listening` | Mic is hot, waiting for speech | Connection established; after bot finishes; after `turn.resumed` |
+| `speaking` | Agent is speaking (TTS playing) | First `bot.word` event |
+| `thinking` | Processing user input, waiting for LLM | `user.message` (STT final), `turn.end` |
+| `pause` | Turn detection pause — user may still be talking | `turn.pause` (brief silence detected) |
+
+Typical flow during one exchange:
+
+![Call conversation phases](/assets/diagrams/call-phase-flow.png)
+
+## Transcript messages
+
+The `messages` array contains the full conversation history. Each message is structured:
+
+```typescript
+interface TranscriptMessage {
+  id: number;
+  role: "user" | "bot" | "system";
+  text: string;
+  isInterim?: boolean;     // user only: STT is still processing
+  speaking?: boolean;      // bot only: TTS is playing this message
+  interrupted?: boolean;   // bot only: user barged in
+  messageId?: string;      // bot only: server-assigned ID
+  toolCallId?: string;     // system only: tool call ID (for updating with result)
+}
+```
+
+Messages mutate in place as STT refines, words stream in, and the bot finishes speaking — they don't get replaced. That means if you bind to `messages` reactively, the right entry will update.
+
+### User message lifecycle
+
+```
+user.speaking → { role: "user", text: "Hola",     isInterim: true }
+                                  text updates as STT refines...
+user.speaking → { role: "user", text: "Hola que", isInterim: true }
+user.message  → { role: "user", text: "Hola, ¿qué tal?", isInterim: false }
+```
+
+If you're rendering a transcript, render `isInterim: true` messages with reduced opacity or a "typing" indicator so the user sees that the STT is still processing.
+
+### Bot message lifecycle (word-by-word)
+
+```
+bot.speaking  → { role: "bot", text: "",                 speaking: true, messageId: "abc" }
+bot.word      → text: "Hello"
+bot.word      → text: "Hello there"
+bot.word      → text: "Hello there how"
+bot.word      → text: "Hello there how are"
+bot.word      → text: "Hello there how are you"
+bot.finished  → { speaking: false, text: "Hello there, how are you?" }
+```
+
+`bot.speaking` arrives with the full intended `text`, but the widget intentionally starts with `text: ""` and builds word-by-word so the on-screen captions stay in sync with the audio.
+
+`bot.finished` may include a polished final text (with proper punctuation that the per-word stream doesn't have).
+
+### Interrupted bot
+
+When the user barges in mid-utterance:
+
+```
+bot.word        → text: "Hello there how"
+bot.interrupted → { speaking: false, interrupted: true }
+```
+
+Render interrupted messages with a visual marker (e.g. `⚡` icon, ellipsis, gray border) so users see the bot was cut off rather than just suddenly stopping.
+
+## Subscribing to changes
+
+The state object is **stable by identity** — `getState()` returns the same reference until something changes. This is what makes it safe for React's `useSyncExternalStore`:
+
+```typescript
+session.subscribe(() => {
+  const next = session.getState(); // new reference only if state changed
+  // ...
+});
+```
+
+For more targeted updates, subscribe to specific events:
+
+```typescript
+session.addEventListener("phase", (e) => {
+  // only fires when phase actually changes
+  document.body.dataset.phase = e.detail.phase;
+});
+```
+
+## Driving UI from `phase` and `agentSpeaking`
+
+A common pattern: bind your "orb" or status visual to `phase` for the overall mode, and use `agentSpeaking` for a faster-reacting animation layer.
+
+```typescript
+const orb = document.getElementById("orb");
+
+session.subscribe(() => {
+  const { phase, agentSpeaking, idleWarning } = session.getState();
+
+  orb.dataset.phase = phase;                    // CSS handles per-phase styling
+  orb.classList.toggle("speaking", agentSpeaking);
+  orb.classList.toggle("idle-warning", idleWarning !== null);
+});
+```
+
+The `@pinecall/web` package follows exactly this pattern — see [its theming guide](/web/widget/theming) for the full set of CSS classes.
+
+## What's next
+
+- [DataChannel protocol](/web/core/datachannel-protocol) — the raw events that drive state changes
+- [`VoiceSession` class](/web/core/voice-session) — methods and constructor

package/skills/pinecall-web-voice/references/web/core/voice-session.md

@@ -0,0 +1,279 @@
+---
+title: "VoiceSession"
+description: "The core class: constructor, methods, and framework integration patterns."
+---
+
+# VoiceSession
+
+The main class exported by `@pinecall/web/core`. Manages the WebRTC peer connection, mic stream, DataChannel events, and a reactive state object.
+
+## Constructor
+
+```typescript
+new VoiceSession(options)
+```
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `agent` | `string` | ✅ | Agent ID to connect to |
+| `server` | `string` | — | API base URL (default: `https://voice.pinecall.io`) |
+| `config` | `Record<string, unknown>` | — | Session config overrides (voice, STT, language, greeting) |
+| `metadata` | `Record<string, unknown>` | — | Metadata passed to the agent (visible as `call.metadata` server-side) |
+
+The constructor does **not** open a connection. Call `connect()` when you want the call to start.
+
+```typescript
+const session = new VoiceSession({
+  agent: "mara",
+  config: {
+    voice: "elevenlabs/sarah",
+    stt: { provider: "deepgram", model: "nova-3", language: "es" },
+    language: "es",
+    greeting: "¡Hola! ¿En qué puedo ayudarte?",
+  },
+});
+```
+
+The `config` object uses Pinecall's shortcut syntax — same format the server SDK accepts. See [STT Providers](/reference/stt-providers) and [TTS Providers](/reference/tts-providers).
+
+## Methods
+
+### `connect()`
+
+Opens the WebRTC connection. Returns a `Promise<void>` that resolves when the connection is established.
+
+```typescript
+await session.connect();
+```
+
+Internally it:
+
+1. Fetches a short-lived token from `GET /webrtc/token?agent_id=<agent>`
+2. Fetches ICE servers from `GET /webrtc/ice-servers` (falls back to Google STUN)
+3. Requests microphone access via `getUserMedia`
+4. Creates `RTCPeerConnection`, adds the mic track, opens a DataChannel
+5. Generates an SDP offer, gathers ICE candidates
+6. Sends the offer to `POST /webrtc/offer` with the token
+7. Applies the remote SDP answer → connection established
+
+State transitions: `idle` → `connecting` → `connected` (or `error`).
+
+### `disconnect()`
+
+Closes the connection, stops the mic, clears timers. State returns to `idle`. The `messages` array is preserved.
+
+```typescript
+session.disconnect();
+```
+
+### `toggleMute()` / `setMuted(muted)`
+
+Mute or unmute the mic. Both disable the local audio track **and** send `{ action: "mute" | "unmute" }` over the DataChannel so the server stops processing audio too.
+
+```typescript
+session.toggleMute();
+session.setMuted(true);
+```
+
+### `getState()`
+
+Returns the current state snapshot. The returned object is **stable by identity** — it only changes when state mutates, which makes it safe for React's `useSyncExternalStore`.
+
+```typescript
+const { status, phase, messages, isMuted, duration } = session.getState();
+```
+
+See [State and Phases](/web/core/state-and-phases) for the full shape.
+
+### `subscribe(listener)`
+
+Subscribes to all state changes. Returns an unsubscribe function. Designed to plug directly into reactive frameworks.
+
+```typescript
+const unsubscribe = session.subscribe(() => {
+  console.log(session.getState());
+});
+
+// later
+unsubscribe();
+```
+
+### `destroy()`
+
+Disconnects, clears all subscribers, and marks the instance unusable. Call this on component unmount.
+
+```typescript
+session.destroy();
+```
+
+### `configure(config)`
+
+Sends a mid-call configuration update over the DataChannel. The server hot-swaps providers without disconnecting. Use this for live language/voice/STT switching during an active call.
+
+```typescript
+session.configure({
+  voice: "elevenlabs/george",
+  stt: { provider: "deepgram", model: "nova-3", language: "es" },
+  language: "es",
+});
+```
+
+> Only works on a connected session. For pre-connect config updates use `updateOptions()`.
+
+### `updateOptions(patch)`
+
+Updates options **before** the next `connect()` call. No effect on an already-connected session.
+
+```typescript
+session.updateOptions({
+  config: {
+    voice: "elevenlabs/valentina",
+    language: "es",
+    greeting: "¡Hola!",
+  },
+});
+
+await session.connect(); // uses the new config
+```
+
+## Events (EventTarget)
+
+`VoiceSession` extends `EventTarget`. Listen with `addEventListener`:
+
+| Event | `detail` | When |
+|---|---|---|
+| `status` | `{ status }` | Connection status changed |
+| `phase` | `{ phase }` | Call phase changed (listening, speaking, thinking, etc.) |
+| `message` | `{ message }` | New transcript message added or existing one updated |
+| `error` | `{ error }` | An error occurred |
+| `change` | `{ state }` | Any state mutation (most general) |
+| `event` | raw payload | Every raw DataChannel event from the server |
+
+```typescript
+session.addEventListener("message", (e) => {
+  const msg = e.detail.message;
+  if (msg.role === "user" && !msg.isInterim) console.log("User:", msg.text);
+});
+
+session.addEventListener("event", (e) => {
+  // raw — see DataChannel protocol page for the full catalog
+  if (e.detail.event === "llm.toolCall") {
+    console.log("Tool calls:", e.detail.tool_calls);
+  }
+});
+```
+
+The `event` listener is the power-user escape hatch. Every JSON message from the server's DataChannel is forwarded as-is. Use it for things the state machine doesn't expose: tool calls, audio metrics, custom events.
+
+## Framework patterns
+
+### Vanilla JS
+
+```typescript
+import { VoiceSession } from "@pinecall/web/core";
+
+const session = new VoiceSession({ agent: "florencia" });
+const btn = document.getElementById("call-btn");
+const transcript = document.getElementById("transcript");
+
+btn.onclick = async () => {
+  if (session.getState().status === "connected") {
+    session.disconnect();
+    btn.textContent = "Start Call";
+  } else {
+    await session.connect();
+    btn.textContent = "End Call";
+  }
+};
+
+session.addEventListener("message", (e) => {
+  const msg = e.detail.message;
+  const div = document.createElement("div");
+  div.className = msg.role;
+  div.textContent = `${msg.role}: ${msg.text}`;
+  transcript.appendChild(div);
+});
+
+session.addEventListener("phase", (e) => {
+  document.body.dataset.phase = e.detail.phase;
+});
+```
+
+### React (`useSyncExternalStore`)
+
+```tsx
+import { useSyncExternalStore, useCallback, useState, useEffect } from "react";
+import { VoiceSession } from "@pinecall/web/core";
+
+function useVoiceSession(agent: string) {
+  const [session] = useState(() => new VoiceSession({ agent }));
+
+  const state = useSyncExternalStore(
+    useCallback((cb) => session.subscribe(cb), [session]),
+    () => session.getState(),
+  );
+
+  useEffect(() => () => session.destroy(), [session]);
+
+  return { ...state, session };
+}
+```
+
+> If you're using React and want a ready-made widget instead of building UI, use [`@pinecall/web`](/web/widget/overview) — it wraps this pattern and ships an animated orb UI.
+
+### Vue 3
+
+```typescript
+import { ref, onUnmounted } from "vue";
+import { VoiceSession } from "@pinecall/web/core";
+
+export function useVoiceSession(agent: string) {
+  const session = new VoiceSession({ agent });
+  const state = ref(session.getState());
+
+  session.subscribe(() => {
+    state.value = session.getState();
+  });
+
+  onUnmounted(() => session.destroy());
+
+  return { state, session };
+}
+```
+
+### Svelte
+
+```typescript
+import { readable } from "svelte/store";
+import { VoiceSession } from "@pinecall/web/core";
+
+export function createVoiceSession(agent: string) {
+  const session = new VoiceSession({ agent });
+
+  const state = readable(session.getState(), (set) => {
+    return session.subscribe(() => set(session.getState()));
+  });
+
+  return { state, session };
+}
+```
+
+## TypeScript types
+
+All types are exported from the package:
+
+```typescript
+import type {
+  VoiceSessionOptions,
+  VoiceSessionState,
+  SessionStatus,      // "idle" | "connecting" | "connected" | "error"
+  CallPhase,          // "idle" | "listening" | "speaking" | "pause" | "thinking"
+  TranscriptMessage,
+} from "@pinecall/web/core";
+```
+
+## What's next
+
+- [State and phases](/web/core/state-and-phases) — the reactive state model in detail
+- [DataChannel protocol](/web/core/datachannel-protocol) — every event the server emits
+- [`@pinecall/web`](/web/widget/overview) — the React widget built on top

package/skills/pinecall-web-widget/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: pinecall-web-widget
+description: >-
+  @pinecall/web React widget — VoiceWidget props, theming, useVoiceSession hook, client tools. Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: react widget, voicewidget, useVoiceSession, theming, props, client tools, @pinecall/web.
+license: MIT
+---
+
+# @pinecall/web (React Widget)
+
+@pinecall/web React widget — VoiceWidget props, theming, useVoiceSession hook, client tools.
+
+This skill bundles the official Pinecall documentation for **@pinecall/web (React Widget)**. 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 |
+|------|----------------|------|
+| **@pinecall/web** | Drop-in React voice widget with animated orb UI, live transcript, themes, and multi-language support. | [`references/web/widget/overview.md`](references/web/widget/overview.md) · [docs](https://docs.pinecall.io/web/widget/overview) |
+| **Props** | Every prop the VoiceWidget accepts — including token security, tools, theming, and multi-language. | [`references/web/widget/props.md`](references/web/widget/props.md) · [docs](https://docs.pinecall.io/web/widget/props) |
+| **Theming** | Theme presets, CSS variables, and full customization of the orb and transcript UI. | [`references/web/widget/theming.md`](references/web/widget/theming.md) · [docs](https://docs.pinecall.io/web/widget/theming) |
+| **useVoiceSession hook** | Build a fully custom voice UI without giving up the widget's session management. | [`references/web/widget/use-voice-session-hook.md`](references/web/widget/use-voice-session-hook.md) · [docs](https://docs.pinecall.io/web/widget/use-voice-session-hook) |
+| **Tools API** | Render interactive UI in response to LLM tool calls. Buttons, forms, pickers — all synced to the conversation. | [`references/web/widget/tools-api.md`](references/web/widget/tools-api.md) · [docs](https://docs.pinecall.io/web/widget/tools-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`.*

package/skills/pinecall-web-widget/references/web/widget/overview.md

@@ -0,0 +1,67 @@
+---
+title: "@pinecall/web"
+description: "Drop-in React voice widget with animated orb UI, live transcript, themes, and multi-language support."
+---
+
+# @pinecall/web
+
+A React voice widget for Pinecall agents. Animated orb, live transcript, theme presets, multi-language selector, and an interactive tools API for rendering UI in response to LLM tool calls.
+
+```bash
+npm install @pinecall/web react react-dom
+```
+
+> Built on top of [`@pinecall/web/core`](/web/core/overview). React ≥18 is a peer dependency.
+
+## Quick start
+
+```tsx
+import { VoiceWidget } from "@pinecall/web";
+
+export default function App() {
+  return <VoiceWidget agent="mara" name="Mara" />;
+}
+```
+
+That's it. The widget renders a floating orb in the bottom-right corner. Click to start a voice call, click again to end it. The orb animates through phases (idle → connecting → listening → speaking → thinking) and shows a live transcript bubble above.
+
+## What you get out of the box
+
+- **Animated orb** with breathing rings, pulse states, and per-phase colors
+- **Live transcript** rendered as chat bubbles next to the orb
+- **5 theme presets** (`dark`, `midnight`, `aurora`, `sunset`, `light`) — plus full CSS variable overrides
+- **Multi-language pill selector** with hot-swap mid-call
+- **Token security** via `tokenProvider` — API keys never leave your server
+- **Idle warning state** when the user goes silent too long
+- **Interactive Tools API** for rendering UI in response to LLM tool calls
+- **`useVoiceSession()` hook** for building completely custom UIs
+
+## Standalone components
+
+The package also exports standalone components for building custom multi-channel experiences:
+
+| Export | Purpose |
+|---|---|
+| `ContactHub` | Multi-channel contact menu (voice, chat, WhatsApp, Call Me) |
+| `ChatView` | Embedded LLM text chat with streaming markdown |
+| `useVoiceSession()` | Headless hook — build your own UI from scratch |
+| `useAgentInfo()` | Fetch agent channel info for auto-discovery |
+
+These are **not** wired into `<VoiceWidget>` — you compose them yourself in your app's UI.
+
+## When to use what
+
+| You want to... | Use |
+|---|---|
+| Drop a voice button on your site | `<VoiceWidget />` |
+| Build a fully custom UI in React | `useVoiceSession()` hook |
+| Build a fully custom UI in Vue/Svelte/vanilla | [`@pinecall/web/core`](/web/core/overview) directly |
+| Render interactive UI from agent tool calls | `<VoiceWidget>` + `tools` prop or `useVoice()` + `trackedTools` |
+| Add multi-channel contact menu | Import `ContactHub` and compose it in your layout |
+
+## What's next
+
+- [Props reference](/web/widget/props) — every prop with type and default
+- [Theming](/web/widget/theming) — presets, CSS variables, custom themes
+- [`useVoiceSession` hook](/web/widget/use-voice-session-hook) — for custom UIs
+- [Tools API](/web/widget/tools-api) — render interactive components from tool calls