@pinecall/skills 0.1.0

package/skills/pinecall-web-chat/references/web/chat/chat-session.md

@@ -0,0 +1,178 @@
+---
+title: "ChatSession API"
+description: "Full reference for ChatSession (vanilla) and usePinecallChat (React)."
+---
+
+# `ChatSession` API
+
+The `ChatSession` class is the framework-agnostic core. For React there's also the `usePinecallChat` hook which wraps the same class with `useSyncExternalStore`.
+
+## `ChatSession` (vanilla)
+
+### Constructor
+
+```typescript
+import { ChatSession } from "@pinecall/web/chat";
+
+const chat = new ChatSession({ agent: "florencia" });
+```
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `agent` | `string` | ✅ | Agent slug (e.g. `"florencia"`, `"dev-berna-florencia"`) |
+| `server` | `string` | — | Voice server URL (default: `https://voice.pinecall.io`) |
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `connect()` | Connect — fetches token, opens WebSocket |
+| `disconnect()` | Close the WebSocket connection |
+| `destroy()` | Disconnect + clear all subscribers. Do not reuse. |
+| `send(text)` | Send a text message to the agent |
+| `setContext(key, value)` | Inject / update / clear keyed context in the LLM prompt |
+| `getState()` | Read-only snapshot of current state |
+| `subscribe(cb)` | Subscribe to state changes (returns unsubscribe) |
+
+### Events (`EventTarget`)
+
+| Event | `detail` | When |
+|---|---|---|
+| `status` | `{ status }` | Connection status changed |
+| `message` | `{ message }` | New or updated message |
+| `error` | `{ error }` | Error occurred |
+| `change` | `{ state }` | Any state mutation (most general) |
+| `event` | raw payload | Every raw server event |
+
+### State shape
+
+```typescript
+interface ChatSessionState {
+  status: "idle" | "connecting" | "connected" | "error" | "destroyed";
+  error: string | null;
+  messages: ChatMessage[];
+  typing: boolean;          // true while bot is streaming a response
+  streamingText: string;    // partial text of the current bot response
+  sessionId: string | null;
+}
+
+interface ChatMessage {
+  id: number;
+  role: "user" | "bot";
+  text: string;
+  messageId?: string;       // server-assigned ID (bot messages)
+  isStreaming?: boolean;    // true while bot is still streaming
+}
+```
+
+### Reactive subscribe pattern
+
+Works with any reactive system — MobX, signals, Vue refs, Svelte stores:
+
+```typescript
+const unsubscribe = chat.subscribe(() => {
+  const state = chat.getState();
+  console.log("Messages:", state.messages.length);
+  console.log("Typing:", state.typing);
+});
+
+// clean up
+unsubscribe();
+```
+
+### Injecting dynamic context
+
+Same pattern as `@pinecall/web`'s `setContext()` — inject live UI state into the LLM's system prompt:
+
+```typescript
+chat.setContext("cart", JSON.stringify({
+  items: ["Corte de cabello", "Tinte"],
+  total: 85.00,
+}));
+
+// clear a context key
+chat.setContext("cart", null);
+```
+
+The agent's system prompt picks this up automatically:
+
+```
+## UI Context
+### cart
+{"items":["Corte de cabello","Tinte"],"total":85.00}
+```
+
+## `usePinecallChat` (React)
+
+React-only hook exported from `@pinecall/web/chat/react`. Wraps `ChatSession` with `useSyncExternalStore` for efficient rendering. Session is created once on mount and destroyed on unmount.
+
+### Quick usage
+
+```tsx
+import { usePinecallChat } from "@pinecall/web/chat/react";
+
+function Chat() {
+  const { messages, send, connected, typing, streamingText } = usePinecallChat({
+    agent: "florencia",
+  });
+
+  if (!connected) return <p>Connecting...</p>;
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <p key={m.id}>
+          <strong>{m.role}:</strong> {m.text}
+          {m.isStreaming && "▊"}
+        </p>
+      ))}
+      {typing && <p>Bot is typing: {streamingText}▊</p>}
+      <input
+        placeholder="Type a message..."
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            send(e.currentTarget.value);
+            e.currentTarget.value = "";
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Hook options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `agent` | `string` | **required** | Agent ID |
+| `server` | `string` | `"https://voice.pinecall.io"` | Voice server URL |
+| `autoConnect` | `boolean` | `true` | Connect on mount automatically |
+
+### Hook return
+
+| Field | Type | Description |
+|---|---|---|
+| `messages` | `ChatMessage[]` | All messages in the conversation |
+| `send` | `(text: string) => void` | Send a text message |
+| `connected` | `boolean` | `true` when connected to the server |
+| `typing` | `boolean` | `true` while the bot is streaming |
+| `streamingText` | `string` | Partial text of the current bot response |
+| `error` | `string \| null` | Current error, if any |
+| `setContext` | `(key, value) => void` | Inject dynamic context into the LLM prompt |
+| `connect` | `() => void` | Manually connect (if `autoConnect: false`) |
+| `disconnect` | `() => void` | Manually disconnect |
+
+## Protocol
+
+What happens under the hood:
+
+![Chat WebSocket protocol sequence](/assets/diagrams/chat-protocol-sequence.png)
+
+## Related packages
+
+| Package | Description |
+|---|---|
+| [`@pinecall/sdk`](/api/pinecall) | Server-side SDK — agent, call, tools, channels |
+| [`@pinecall/web/core`](/web/core/overview) | WebRTC voice session (framework-agnostic) |
+| [`@pinecall/web`](/web/widget/overview) | React voice widget with animated orb |

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

@@ -0,0 +1,98 @@
+---
+title: "@pinecall/web/chat"
+description: "Text chat client for Pinecall voice agents. Framework-agnostic core + React hook."
+---
+
+# @pinecall/web/chat
+
+Text chat client for Pinecall agents. The chat counterpart to `@pinecall/web/core` — same agents, same prompts, same tools, but text-only over WebSocket instead of audio over WebRTC.
+
+```bash
+npm install @pinecall/web
+```
+
+> **Browser-only.** Uses native `WebSocket` and `EventTarget` APIs. Works in any modern browser, bundler, or SSR-hydrated app.
+
+## What it does
+
+`@pinecall/web/chat` lets your browser talk to a Pinecall agent in plain text. It:
+
+- Fetches a short-lived token from the voice server
+- Opens a WebSocket to `/chat/ws`
+- Sends user messages, receives streamed bot responses (token-by-token)
+- Exposes the conversation as reactive state + events
+- Supports the same `setContext` mechanism as `@pinecall/web` for syncing UI state
+
+It does **not** include UI. For React you get a hook (`usePinecallChat`). For Vue, Svelte, or vanilla JS you use the `ChatSession` class directly.
+
+## When to use it
+
+| | Use |
+|---|---|
+| You want voice with UI rendering | [`@pinecall/web`](/web/widget/overview) |
+| You want voice with no UI assumptions | [`@pinecall/web/core`](/web/core/overview) |
+| **You want text chat** | **`@pinecall/web/chat`** |
+| You want to embed both voice + chat | Use both packages on the same agent |
+
+The same agent (`pc.agent("florencia", ...)`) can have a `webrtc` channel **and** a `chat` channel — `@pinecall/web/chat` connects to the chat channel. Same prompt, same tools, same conversation logic.
+
+## Quick start (vanilla)
+
+```typescript
+import { ChatSession } from "@pinecall/web/chat";
+
+const chat = new ChatSession({ agent: "florencia" });
+
+chat.addEventListener("message", (e) => {
+  const m = e.detail.message;
+  console.log(`${m.role}: ${m.text}`);
+});
+
+await chat.connect();
+chat.send("Hola, quiero reservar un turno");
+```
+
+## Quick start (React)
+
+```tsx
+import { usePinecallChat } from "@pinecall/web/chat/react";
+
+function Chat() {
+  const { messages, send, connected, typing } = usePinecallChat({ agent: "florencia" });
+
+  if (!connected) return <p>Connecting...</p>;
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <p key={m.id}>
+          <strong>{m.role}:</strong> {m.text}
+          {m.isStreaming && "▊"}
+        </p>
+      ))}
+      {typing && <p>Bot is typing…</p>}
+      <input
+        placeholder="Type a message..."
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            send(e.currentTarget.value);
+            e.currentTarget.value = "";
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+React is an **optional** peer dependency — the React subpath (`@pinecall/web/chat/react`) is only loaded if you import it.
+
+## How it fits with the rest
+
+![Chat architecture](/assets/diagrams/chat-architecture.png)
+
+The agent's chat channel routes through the same LLM pipeline as voice — including tool calling. Anything you've built for the voice agent (tools, prompt, hot-reload, multi-tenant) works on the chat channel without changes.
+
+## What's next
+
+- [`ChatSession` API](/web/chat/chat-session) — full reference for both vanilla and React

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

@@ -0,0 +1,37 @@
+---
+name: pinecall-web-components
+description: >-
+  @pinecall/web web components — framework-agnostic custom elements. Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: web components, custom element, framework-agnostic widget.
+license: MIT
+---
+
+# @pinecall/web (Web Components)
+
+@pinecall/web web components — framework-agnostic custom elements.
+
+This skill bundles the official Pinecall documentation for **@pinecall/web (Web Components)**. 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 |
+|------|----------------|------|
+| **Web Components** | Framework-agnostic <pinecall-orb>, <pinecall-modal> and <pinecall-chat> Custom Elements — voice and text in any framework, no React required. | [`references/web/components/overview.md`](references/web/components/overview.md) · [docs](https://docs.pinecall.io/web/components/overview) |
+
+
+## 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-components/references/web/components/overview.md

@@ -0,0 +1,128 @@
+---
+title: "Web Components"
+description: "Framework-agnostic <pinecall-orb>, <pinecall-modal> and <pinecall-chat> Custom Elements — voice and text in any framework, no React required."
+---
+
+# Web Components
+
+`@pinecall/web` ships native **Custom Elements** so you can drop a Pinecall voice agent into **any** framework — React, Vue, Svelte, Angular, Astro, or plain HTML — with no React dependency. They wrap the same vanilla [`VoiceSession`](/web/core/overview) as the React widget, render in Shadow DOM, and are SSR-safe.
+
+| Import | Element | Needs React |
+|---|---|---|
+| `@pinecall/web/orb` | `<pinecall-orb>` — a click-to-talk voice orb | ❌ |
+| `@pinecall/web/modal` | `<pinecall-modal>` — a glass call modal (orb **or** wave visual, live captions, transcript, text-during-call) | ❌ |
+| `@pinecall/web/chatbox` | `<pinecall-chat>` — a docked chatbox (text chat that can escalate to a voice call) | ❌ |
+| `@pinecall/web/orb/react` | `<Orb>` — thin React wrapper | ✅ |
+| `@pinecall/web/modal/react` | `<CallModal>` — thin React wrapper | ✅ |
+| `@pinecall/web/chatbox/react` | `<ChatBox>` — thin React wrapper | ✅ |
+
+```bash
+npm install @pinecall/web
+```
+
+## Quick start (any framework)
+
+```html
+<pinecall-orb agent="mara" name="Mara" preset="midnight"></pinecall-orb>
+<pinecall-modal agent="mara" name="Mara" visual="wave"></pinecall-modal>
+
+<script type="module">
+  import "@pinecall/web/orb";   // registers <pinecall-orb>
+  import "@pinecall/web/modal"; // registers <pinecall-modal>
+
+  // Functions/objects can't be HTML attributes — set them as PROPERTIES:
+  const modal = document.querySelector("pinecall-modal");
+  modal.tokenProvider = async () => (await fetch("/api/token")).json();
+  modal.addEventListener("pinecall:status", (e) => console.log(e.detail));
+</script>
+```
+
+> Importing the module auto-registers the element (guarded and idempotent; a no-op during SSR). You can also call `definePinecallOrb()` / `definePinecallModal()` explicitly.
+
+## Props, properties & events
+
+**Attributes** (primitives): `agent`, `server`, `name`, `label`, `preset` (`dark` · `midnight` · `aurora` · `sunset` · `light`), `avatar`, and on the modal `visual` (`orb` | `wave`).
+
+**Properties** (functions/objects — set in JS, not as attributes): `config`, `metadata`, `tokenProvider`, `theme`.
+
+**Events**: `pinecall:status` (detail = status), `pinecall:transcript` (detail = messages), `pinecall:error` (detail = message), and on the modal/chatbox `pinecall:open` / `pinecall:close`.
+
+**Imperative API**: `connect()`, `disconnect()`, `toggleMute()`, `setMuted()`, `configure()`, `sendText()`, `getState()`; the modal also has `open()` / `close()`.
+
+## `<pinecall-modal>`
+
+A call modal with a launcher button (FAB). Open it and it starts a WebRTC call.
+
+- **`visual="orb"`** — animated orb + status + a single live caption.
+- **`visual="wave"`** — a waveform driven by **real `audio.metrics`**, a quoted live caption, an activity sub-status (e.g. `transcribing · Deepgram`), and a Ring → Listen → Think → Speak stepper.
+- The **keyboard button** flips to a transcript view: chat bubbles of the whole conversation plus a text input — type during the call and the agent answers in voice and text (via `sendText`).
+- Controls: mute (pauses the local mic), hang up, keyboard.
+
+## `<pinecall-orb>` — `opens`
+
+The orb is a launcher. Its `opens` attribute controls what a click does:
+
+- `opens="inline"` (default) — connect right there, with live captions beside the orb.
+- `opens="modal"` — open a `<pinecall-modal>`.
+- `opens="chat"` — open a `<pinecall-chat>` chatbox.
+
+The launched element's own FAB is suppressed (`no-fab`) so the orb stays the single launcher.
+
+## `<pinecall-chat>` — docked chatbox
+
+A traditional web-chat: a launcher bubble opens a panel with message bubbles and a text input.
+
+- **Text-first** (backed by `ChatSession`) with a **call button** that escalates to a WebRTC voice call (`VoiceSession`) — talk and/or type in the same panel. The conversation **continues** across the switch (the prior transcript is carried into the new session).
+- `greeting` attribute — a first bot bubble shown on open (client-side; text chat has no server-pushed greeting). `auto-call` — start directly in a voice call. `no-call` — hide the call button (pure text chat).
+- Its **`tokenProvider` is channel-aware**: `(channel: "chat" | "webrtc") => { token, server }`, so one backend function mints the right token for each transport.
+
+```html
+<pinecall-chat agent="florencia" name="Florencia" greeting="Hi! How can I help?"></pinecall-chat>
+<script type="module">
+  import "@pinecall/web/chatbox";
+  document.querySelector("pinecall-chat").tokenProvider =
+    async (channel) => (await fetch(`/api/token?channel=${channel}`)).json();
+</script>
+```
+
+> **Chat greeting:** unlike voice, a text chat is not greeted by the server (`call.say` doesn't reach chat WebSocket clients). Use the `greeting` attribute for an instant client-side first message.
+
+## Theming
+
+Theming uses the same `--vw-*` custom properties as the widget (they inherit through the Shadow boundary), plus modal-specific ones. Use the `preset` attribute, the `theme` property, or plain CSS on the element:
+
+```css
+pinecall-modal {
+  --vw-color-accent: 205, 88, 178;   /* magenta — also tints the card */
+  --pm-user: #34d399;                /* your transcript color */
+  --pm-bot: #ffd166;                 /* agent transcript color */
+}
+```
+
+The card gradient and speaker colors derive from the theme accent by default, so each preset themes the whole modal.
+
+## React wrappers
+
+In React, prefer the wrappers — they bind object/function props cleanly (no refs) and map events to callbacks:
+
+```tsx
+import { Orb } from "@pinecall/web/orb/react";
+import { CallModal } from "@pinecall/web/modal/react";
+
+<Orb agent="mara" name="Mara"
+     tokenProvider={async () => (await fetch("/api/token")).json()}
+     onStatus={(s) => console.log(s)} />
+
+<CallModal agent="mara" name="Mara" visual="wave"
+           tokenProvider={async () => (await fetch("/api/token")).json()} />
+```
+
+## Tokens
+
+Same model as everything else — mint a short-lived token from your backend and hand it back via `tokenProvider`. See [WebRTC in the Browser](/guides/webrtc-browser) and [Security](/security).
+
+## Related
+
+- [`@pinecall/web` (React widget)](/web/widget/overview)
+- [`@pinecall/web/core` — VoiceSession](/web/core/overview)
+- [`@pinecall/web/chat` — text chat](/web/chat/overview)

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

@@ -0,0 +1,40 @@
+---
+name: pinecall-web-voice
+description: >-
+  @pinecall/web/core — browser WebRTC voice (VoiceSession, state & phases, DataChannel protocol). Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: webrtc, voice session, browser voice, datachannel, @pinecall/web/core.
+license: MIT
+---
+
+# @pinecall/web/core (Voice)
+
+@pinecall/web/core — browser WebRTC voice (VoiceSession, state & phases, DataChannel protocol).
+
+This skill bundles the official Pinecall documentation for **@pinecall/web/core (Voice)**. 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/core** | Framework-agnostic WebRTC voice session client. Zero dependencies. | [`references/web/core/overview.md`](references/web/core/overview.md) · [docs](https://docs.pinecall.io/web/core/overview) |
+| **VoiceSession** | The core class: constructor, methods, and framework integration patterns. | [`references/web/core/voice-session.md`](references/web/core/voice-session.md) · [docs](https://docs.pinecall.io/web/core/voice-session) |
+| **State and Phases** | The reactive state model: status, phases, transcript messages, and lifecycles. | [`references/web/core/state-and-phases.md`](references/web/core/state-and-phases.md) · [docs](https://docs.pinecall.io/web/core/state-and-phases) |
+| **DataChannel Protocol** | The raw WebRTC DataChannel protocol — every server event and every client command. | [`references/web/core/datachannel-protocol.md`](references/web/core/datachannel-protocol.md) · [docs](https://docs.pinecall.io/web/core/datachannel-protocol) |
+
+
+## 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-voice/references/web/core/datachannel-protocol.md

@@ -0,0 +1,149 @@
+---
+title: "DataChannel Protocol"
+description: "The raw WebRTC DataChannel protocol — every server event and every client command."
+---
+
+# DataChannel Protocol
+
+`VoiceSession` opens an ordered DataChannel named `"events"` over WebRTC. The protocol is plain JSON in both directions. This page documents every message the server sends and every command the client can send.
+
+> Most apps don't need to use the protocol directly — the state machine handles it. Use this when you need to read events the state doesn't expose (tool calls, audio metrics) or when you're sending custom client commands.
+
+## Accessing raw events
+
+Subscribe to the `"event"` listener — every server message is forwarded as-is:
+
+```typescript
+session.addEventListener("event", (e) => {
+  const raw = e.detail; // the parsed JSON from the server
+  console.log(raw.event, raw);
+});
+```
+
+## Server → Client events
+
+### Speech detection (STT)
+
+| Event | Fields | Description |
+|---|---|---|
+| `speech.started` | — | User started physically speaking (VAD detected voice) |
+| `speech.ended` | — | User stopped speaking (VAD silence) |
+| `user.speaking` | `text` | STT partial/interim result — text may change |
+| `user.message` | `text` | STT final result — text is locked, turn is over |
+
+### Turn detection
+
+| Event | Fields | Description |
+|---|---|---|
+| `turn.pause` | — | Brief silence detected — user might still be talking |
+| `turn.end` | — | Silence confirmed — user's turn is over, LLM starts |
+| `turn.resumed` | — | User started speaking again during the pause |
+
+### Bot speech (TTS)
+
+| Event | Fields | Description |
+|---|---|---|
+| `bot.speaking` | `message_id`, `text` | TTS generation started. `text` has the full intended response. The widget intentionally starts empty and builds word-by-word. |
+| `bot.word` | `message_id`, `word`, `word_index` | A single word was spoken by TTS. Arrives in real-time as audio plays. |
+| `bot.finished` | `message_id`, `text` | TTS completed normally. `text` is the polished final response. |
+| `bot.interrupted` | `message_id` | User barged in — TTS was cut short. |
+
+### Audio metrics
+
+When enabled via session config (`analysis.send_audio_metrics`):
+
+| Event | Fields | Description |
+|---|---|---|
+| `audio.metrics` | `source`, `energy_db`, `rms`, `peak`, `is_speech`, `vad_prob` | Server-side audio analysis. `source` is `"user"` or `"bot"`. Sent every ~100ms. |
+
+Use it to build live waveform meters, energy bars, or VAD visualizations.
+
+### LLM / tool events
+
+These events are **not** processed by the state machine but are forwarded through the `"event"` listener. They come from the Pinecall server's LLM handler:
+
+| Event | Fields | Description |
+|---|---|---|
+| `llm.thinking` | — | LLM started generating a response |
+| `llm.toolCall` | `tool_calls[]`, `msg_id`, `call_id` | LLM requested tool/function calls. Each item has `id`, `name`, `arguments` (JSON string). |
+| `llm.tool_result` | `call_id`, `msg_id`, `results[]` | Tool execution results sent back to LLM. Each item has `tool_call_id`, `result`. |
+| `llm.response` | `text`, `finish_reason` | LLM finished generating (text may be empty for tool-only turns) |
+| `llm.error` | `error` | LLM error occurred |
+
+### Session limits
+
+| Event | Fields | Description |
+|---|---|---|
+| `session.idleWarning` | `remaining_seconds` | User hasn't spoken — call will timeout in `remaining_seconds`. Drives the `idleWarning` state field. |
+| `session.timeout` | `reason` | Session timed out (`"idle_timeout"` or `"max_duration"`). The client auto-disconnects. |
+
+## Client → Server commands
+
+The client sends these through the DataChannel:
+
+| Message | Format | Description |
+|---|---|---|
+| Ping | `"ping"` (string) | Keepalive, sent every 1s by the SDK |
+| Mute | `{ "action": "mute" }` | Stop processing user audio server-side |
+| Unmute | `{ "action": "unmute" }` | Resume processing user audio |
+| Configure | `{ "action": "configure", ...config }` | Hot-swap voice, STT, language, or turn detection mid-call |
+| Inject Text | `{ "action": "inject_text", "text": "..." }` | Send text as if the user spoke it (for tool UI interactions) |
+| Set Context | `{ "action": "set_context", "key": "...", "value": "..." }` | Inject/update keyed context in the LLM prompt |
+
+Most of these have helper methods on `VoiceSession` (`toggleMute`, `configure`). The lower-level commands (`inject_text`, `set_context`) are used by `@pinecall/web` to power the [Tools API](/web/widget/tools-api) and dynamic context injection.
+
+## Worked examples
+
+### Monitoring tool calls
+
+```typescript
+session.addEventListener("event", (e) => {
+  const { event, tool_calls, results } = e.detail;
+
+  if (event === "llm.toolCall" && tool_calls) {
+    for (const tc of tool_calls) {
+      console.log(`Agent calling ${tc.name}(${tc.arguments})`);
+    }
+  }
+  if (event === "llm.tool_result") {
+    console.log("Tool results:", results);
+  }
+});
+```
+
+### Custom audio meter from `audio.metrics`
+
+```typescript
+const meter = document.getElementById("meter");
+
+session.addEventListener("event", (e) => {
+  if (e.detail.event === "audio.metrics" && e.detail.source === "user") {
+    meter.style.width = `${e.detail.rms * 100}%`;
+  }
+});
+```
+
+### Injecting text from a button click
+
+If you have UI components that the user can click to "say" something:
+
+```typescript
+// User clicks "Yes, that's right" instead of saying it
+document.getElementById("yes-btn").onclick = () => {
+  session.send(JSON.stringify({ action: "inject_text", text: "Yes, that's right" }));
+};
+```
+
+The `@pinecall/web` exposes this as the `sendText()` helper — see [Tools API](/web/widget/tools-api).
+
+## WebRTC connection flow
+
+For completeness, here's what happens when you call `connect()`:
+
+![WebRTC connection sequence](/assets/diagrams/webrtc-connection-sequence.png)
+
+## What's next
+
+- [`VoiceSession`](/web/core/voice-session) — the high-level API
+- [State and phases](/web/core/state-and-phases) — how raw events map to state
+- [Tools API](/web/widget/tools-api) — building UI that responds to `llm.toolCall`