@pinecall/skills 0.1.0 → 0.1.2

package/README.md

@@ -45,6 +45,7 @@ cp -R skills/pinecall-guides ~/your-project/.claude/skills/
 | `pinecall-web-components` | Framework-agnostic web components |
 | `pinecall-reference` | CLI, STT/TTS/LLM providers, events, limits, REST |
 | `pinecall-security` | Security model |
+| `pinecall-agent-skills` | This package — installing the Pinecall skills into your agent |
 
 Every skill carries the **house rules** so the agent never drifts:
 `stt: "deepgram/flux"`, `llm: "openai/gpt-5-chat-latest"`, `voice: "elevenlabs/sarah"`,

package/build.mjs

@@ -30,6 +30,12 @@ const HOUSE_RULES = `## House rules — always apply
 - **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\`.
+- **TTS model is auto-derived from \`language\`** — non-English agents (e.g.
+  \`language: "es"\`) default ElevenLabs to \`eleven_multilingual_v2\` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on \`eleven_flash_v2_5\`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level \`flash: true\` flag. To pin any model,
+  use \`voice: { ..., model: "..." }\` (explicit model always wins over \`flash\`).
 - **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.
@@ -78,26 +84,31 @@ const GROUP_MAP = {
     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)": {
+  "Voice — core": {
     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)": {
+  "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)": {
+  "Text 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)": {
+  "Web components": {
     slug: "pinecall-web-components",
     blurb: "@pinecall/web web components — framework-agnostic custom elements.",
     keywords: "web components, custom element, framework-agnostic widget",
   },
+  "Agent Skills": {
+    slug: "pinecall-agent-skills",
+    blurb: "@pinecall/skills — install the Pinecall docs as Agent Skills into Claude Code, Cursor, Antigravity, Copilot.",
+    keywords: "agent skills, @pinecall/skills, claude code, cursor, antigravity, copilot, skills add, install skills",
+  },
   Reference: {
     slug: "pinecall-reference",
     blurb: "Reference tables — CLI commands, STT/TTS/LLM providers, events, session limits, REST API.",
@@ -136,9 +147,28 @@ function loadPage(slug) {
   };
 }
 
+// Flatten nested navigation groups into leaf groups (each with only page
+// slugs). A parent group whose `pages` are sub-groups contributes its leaves,
+// not itself — so one skill is still emitted per leaf section.
+function leafGroups(groups) {
+  const out = [];
+  for (const g of groups) {
+    const pages = g.pages || [];
+    const subs = pages.filter((p) => p && typeof p === "object" && Array.isArray(p.pages));
+    const slugs = pages.filter((p) => typeof p === "string");
+    if (subs.length) {
+      out.push(...leafGroups(subs));
+      if (slugs.length) out.push({ group: g.group, pages: slugs });
+    } else {
+      out.push({ group: g.group, pages: slugs });
+    }
+  }
+  return out;
+}
+
 // --- main
 const docsJson = JSON.parse(readFileSync(join(DOCS_DIR, "..", "docs.json"), "utf8"));
-const groups = docsJson.navigation.groups;
+const groups = leafGroups(docsJson.navigation.groups);
 
 if (existsSync(OUT_DIR)) rmSync(OUT_DIR, { recursive: true });
 mkdirSync(OUT_DIR, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinecall/skills",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",

package/skills/pinecall-agent-skills/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pinecall-agent-skills
+description: >-
+  @pinecall/skills — install the Pinecall docs as Agent Skills into Claude Code, Cursor, Antigravity, Copilot. Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: agent skills, @pinecall/skills, claude code, cursor, antigravity, copilot, skills add, install skills.
+license: MIT
+---
+
+# Agent Skills
+
+@pinecall/skills — install the Pinecall docs as Agent Skills into Claude Code, Cursor, Antigravity, Copilot.
+
+This skill bundles the official Pinecall documentation for **Agent Skills**. 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 |
+|------|----------------|------|
+| **Agent Skills (@pinecall/skills)** | Drop the Pinecall docs into Claude Code, Cursor, Antigravity, Copilot or any agent that speaks the open Agent Skills format — so your coding agent builds voice & chat agents the right way, offline, with the correct defaults. | [`references/skills.md`](references/skills.md) · [docs](https://docs.pinecall.io/skills) |
+
+
+## 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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
+- **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-agent-skills/references/skills.md

@@ -0,0 +1,90 @@
+---
+title: "Agent Skills (@pinecall/skills)"
+description: "Drop the Pinecall docs into Claude Code, Cursor, Antigravity, Copilot or any agent that speaks the open Agent Skills format — so your coding agent builds voice & chat agents the right way, offline, with the correct defaults."
+---
+
+# Agent Skills
+
+[`@pinecall/skills`](https://github.com/pinecall/skills) packages the entire
+Pinecall documentation as **[Agent Skills](https://github.com/agentskills/agentskills)** —
+installable into **Claude Code, Google Antigravity, Cursor, GitHub Copilot, Codex**,
+or anything that speaks the open Skills format. Your coding agent then knows how
+to build Pinecall voice & chat agents **with the right defaults**, offline, without
+you pasting docs into the chat.
+
+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 these same docs** (`sdk/docs/`) — one source of truth feeds the
+docs site, the [`/ask` knowledge base](/guides/knowledge-bases), and these skills.
+
+## Install
+
+The open installer picks your agent's skills directory and symlinks the skills in:
+
+```bash
+npx skills add pinecall/skills
+```
+
+Or copy just 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 / Copilot / others | per the agent's docs |
+
+```bash
+cp -R skills/pinecall-guides ~/your-project/.claude/skills/
+```
+
+## What's inside
+
+One skill per docs section — install all of them, or only the ones you need:
+
+| Skill | Covers |
+|-------|--------|
+| `pinecall-quickstart` | Install + your 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 |
+
+## Built-in house rules
+
+Every skill carries the Pinecall **house rules**, so the agent never drifts from
+the supported configuration:
+
+- Example defaults: `stt: "deepgram/flux"`, `llm: "openai/gpt-5-chat-latest"`,
+  `voice: "elevenlabs/sarah"`. Never `deepgram/nova-2`.
+- **Turn detection & VAD are auto-derived from the STT provider — never set
+  `turnDetection` or `vad` by hand.** (Flux → native turns + native VAD; every
+  other STT → `smart_turn` + `silero`.)
+- Greeting: inbound → `greeting` in `pc.agent()`; outbound → `greeting` in
+  `agent.dial()`.
+- Auth: `new Pinecall()` reads `PINECALL_API_KEY` and auto-connects.
+
+## Staying in sync
+
+The `skills/` tree is **generated and committed**, so `npx skills add` works
+offline. Whenever the docs change, the package is regenerated from `sdk/docs/`:
+
+```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.
+
+## Related
+
+- [Quickstart](/quickstart) — build your first agent
+- [Knowledge bases](/guides/knowledge-bases) — the same docs power the `/ask` agent
+- [`@pinecall/sdk` API](/api/pinecall)

package/skills/pinecall-concepts/SKILL.md

@@ -31,6 +31,12 @@ table below indexes every page; open the `references/…` file for the full text
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

package/skills/pinecall-examples/SKILL.md

@@ -49,6 +49,12 @@ const agent = pc.agent("mara", {
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

package/skills/pinecall-guides/SKILL.md

@@ -58,6 +58,12 @@ const agent = pc.agent("mara", {
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

package/skills/pinecall-quickstart/SKILL.md

@@ -44,6 +44,12 @@ const agent = pc.agent("mara", {
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

package/skills/pinecall-reference/SKILL.md

@@ -33,6 +33,12 @@ table below indexes every page; open the `references/…` file for the full text
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

package/skills/pinecall-reference/references/reference/tts-providers.md

@@ -68,7 +68,65 @@ voice: {
 
 Shortcut: `"elevenlabs/sarah"`
 
-The server defaults to `eleven_flash_v2_5` (the fastest model, optimized for real-time streaming). Override it with the optional `model` field (e.g. `model: "eleven_turbo_v2_5"`).
+### Model selection (auto for non-English)
+
+The server picks the ElevenLabs model from your `language`:
+
+| Language | Default model | Why |
+|---|---|---|
+| `en` (or unset) | `eleven_flash_v2_5` | Fastest, optimized for real-time streaming |
+| Any non-English (`es`, `fr`, `de`, …) | `eleven_multilingual_v2` | Flash/Turbo don't normalize text, so Spanish & other languages mispronounce numbers, dates, currency and abbreviations. The multilingual model reads them naturally. |
+
+> `eleven_multilingual_v2` is billed at a higher rate than flash (it's a higher-quality model). If you'd rather keep the faster/cheaper flash model for a non-English agent, use the `flash` shortcut or pin the model explicitly (both below).
+
+#### `flash: true` — keep flash on a non-English agent
+
+The multilingual model trades a little **latency** for much better pronunciation.
+If your non-English agent should prioritize **lowest latency / lowest cost** over
+pronunciation quality, set the top-level `flash` flag — it opts out of the
+multilingual auto-default and keeps `eleven_flash_v2_5`:
+
+```typescript
+const agent = pc.agent("sofia", {
+  prompt: "Sos Sofía, asistente de la clínica.",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/agus",
+  stt: "deepgram/flux",
+  language: "es",
+  flash: true,        // ← stay on eleven_flash_v2_5 despite language: "es"
+});
+```
+
+`flash` is a sibling of `language` (not inside `voice`), so it reads cleanly with
+the rest of the shortcuts. Semantics:
+
+| Config | Resulting ElevenLabs model |
+|---|---|
+| `language: "es"` | `eleven_multilingual_v2` (auto) |
+| `language: "es"`, `flash: true` | `eleven_flash_v2_5` |
+| `language: "en"` (with or without `flash`) | `eleven_flash_v2_5` |
+| `voice: { model: "..." }` (any `flash`/`language`) | the pinned model — explicit always wins |
+
+Notes:
+
+- **ElevenLabs only.** `flash` has no effect on Cartesia or Polly.
+- **No-op for English** — English already defaults to flash.
+- **An explicit `voice: { model }` always wins** over `flash`. Use `flash: true`
+  for the common "I want the cheap fast model" case; use the `model` field when
+  you need a specific model id.
+- Works per-channel too: `phoneNumbers: [{ number, language: "es", flash: true }]`.
+
+**Override the model** with the optional `model` field — it always wins over both the auto-default and `flash`:
+
+```typescript
+voice: {
+  provider: "elevenlabs",
+  voice_id: "JBFqnCBsd6RMkjVDRZzb",
+  model: "eleven_multilingual_v2",  // or "eleven_flash_v2_5" / "eleven_turbo_v2_5"
+}
+```
+
+The model is part of the voice config, so it hot-reloads with it — `agent.update({ voice })` and a same-provider `call.update({ voice })` keep the model/language already in effect unless you pass a new one.
 
 **Tuning notes:**
 

package/skills/pinecall-sdk-api/SKILL.md

@@ -46,6 +46,12 @@ const agent = pc.agent("mara", {
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

package/skills/pinecall-sdk-api/references/api/agent.md

@@ -35,7 +35,8 @@ const agent = pc.agent("my-agent", {
 | Config field | Type | Description |
 |---|---|---|
 | `voice` | `string \| VoiceConfig` | TTS provider — shortcut or full config |
-| `language` | `string` | BCP-47 language code |
+| `language` | `string` | BCP-47 language code. Non-English auto-selects ElevenLabs `eleven_multilingual_v2` |
+| `flash` | `boolean` | Keep ElevenLabs `eleven_flash_v2_5` on a non-English agent (lowest latency/cost) instead of the multilingual auto-default. ElevenLabs-only; see [TTS Providers](/reference/tts-providers) |
 | `stt` | `string \| STTConfig` | STT provider — shortcut or full config |
 | `llm` | `LLMConfig` | LLM provider, model, prompt, enabled flag |
 | `tools` | `Tool[]` | Declarative tools created with `tool()` + Zod schemas (auto-executed) |

package/skills/pinecall-security/SKILL.md

@@ -27,6 +27,12 @@ table below indexes every page; open the `references/…` file for the full text
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

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

@@ -5,11 +5,11 @@ description: >-
 license: MIT
 ---
 
-# @pinecall/web/chat (Chat)
+# Text chat
 
 @pinecall/web/chat — browser text chat (ChatSession, ChatView).
 
-This skill bundles the official Pinecall documentation for **@pinecall/web/chat (Chat)**. The
+This skill bundles the official Pinecall documentation for **Text chat**. The
 table below indexes every page; open the `references/…` file for the full text
 (loaded on demand). Source of truth: <https://docs.pinecall.io>.
 
@@ -28,6 +28,12 @@ table below indexes every page; open the `references/…` file for the full text
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

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

@@ -5,11 +5,11 @@ description: >-
 license: MIT
 ---
 
-# @pinecall/web (Web Components)
+# Web components
 
 @pinecall/web web components — framework-agnostic custom elements.
 
-This skill bundles the official Pinecall documentation for **@pinecall/web (Web Components)**. The
+This skill bundles the official Pinecall documentation for **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>.
 
@@ -27,6 +27,12 @@ table below indexes every page; open the `references/…` file for the full text
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

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

@@ -5,11 +5,11 @@ description: >-
 license: MIT
 ---
 
-# @pinecall/web/core (Voice)
+# Voice — core
 
 @pinecall/web/core — browser WebRTC voice (VoiceSession, state & phases, DataChannel protocol).
 
-This skill bundles the official Pinecall documentation for **@pinecall/web/core (Voice)**. The
+This skill bundles the official Pinecall documentation for **Voice — core**. The
 table below indexes every page; open the `references/…` file for the full text
 (loaded on demand). Source of truth: <https://docs.pinecall.io>.
 
@@ -30,6 +30,12 @@ table below indexes every page; open the `references/…` file for the full text
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.

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

@@ -5,11 +5,11 @@ description: >-
 license: MIT
 ---
 
-# @pinecall/web (React Widget)
+# 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
+This skill bundles the official Pinecall documentation for **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>.
 
@@ -31,6 +31,12 @@ table below indexes every page; open the `references/…` file for the full text
 - **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`.
+- **TTS model is auto-derived from `language`** — non-English agents (e.g.
+  `language: "es"`) default ElevenLabs to `eleven_multilingual_v2` so numbers,
+  dates and currency are pronounced correctly (flash/turbo don't normalize text).
+  English stays on `eleven_flash_v2_5`. To keep flash on a non-English agent
+  (lower latency/cost), set the top-level `flash: true` flag. To pin any model,
+  use `voice: { ..., model: "..." }` (explicit model always wins over `flash`).
 - **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.