@jambonz/schema 0.1.6 → 0.2.2

package/AGENTS.md

@@ -35,7 +35,7 @@ The verb schemas and JSON structure are identical in both modes. The difference
 - **Webhook**: Simple IVR, call routing, voicemail, basic gather-and-respond patterns.
 - **WebSocket**: LLM-powered voice agents, real-time audio streaming, complex conversational flows, anything requiring bidirectional communication, or asynchronous logic, or streaming tts.
 
-**IMPORTANT**: Any application that uses a speech-to-speech verb (`openai_s2s`, `google_s2s`, `deepgram_s2s`, `ultravox_s2s`, `elevenlabs_s2s`, `s2s`, or `pipeline`) MUST use WebSocket transport, not webhooks. These verbs require persistent bidirectional communication for real-time audio and events.
+**IMPORTANT**: Any application that uses a speech-to-speech verb (`openai_s2s`, `google_s2s`, `deepgram_s2s`, `ultravox_s2s`, `elevenlabs_s2s`, `s2s`, or `agent`) MUST use WebSocket transport, not webhooks. These verbs require persistent bidirectional communication for real-time audio and events.
 
 ## Schema
 
@@ -62,10 +62,10 @@ Two tools are available:
 - **gather** — Collect speech (STT) and/or DTMF input. The workhorse for interactive menus and voice input.
 
 ### AI & Real-time
-- **openai_s2s** / **google_s2s** / **deepgram_s2s** / **ultravox_s2s** — Connect the caller to a vendor-specific LLM for real-time voice conversation. These are the **preferred** verbs when the vendor is known. Each handles the full STT→LLM→TTS pipeline with the vendor pre-set.
+- **openai_s2s** / **google_s2s** / **deepgram_s2s** / **ultravox_s2s** — Connect the caller to a vendor-specific LLM for real-time voice conversation. These are the **preferred** verbs when the vendor is known. Each handles the full STT→LLM→TTS flow with the vendor pre-set.
 - **elevenlabs_s2s** — Connect the caller to an ElevenLabs Conversational AI agent. **Unlike other s2s vendors**, ElevenLabs requires a pre-configured `agent_id` (created in the ElevenLabs dashboard) rather than a model and messages. See [ElevenLabs S2S specifics](#elevenlabs-s2s-specifics) below.
 - **s2s** — Generic LLM voice conversation verb. Use only when the vendor is determined at runtime (e.g. from an env var). Requires `vendor` to be specified.
-- **pipeline** — Higher-level voice AI pipeline with integrated turn detection.
+- **agent** — Higher-level voice AI agent with integrated turn detection. Mix-and-match STT, LLM, and TTS vendors.
 - **dialogflow** — Connect the caller to a Google Dialogflow agent (ES, CX, or CES).
 - **stream** — Stream raw audio to a websocket endpoint for custom processing.
 - **transcribe** — Real-time call transcription sent to a webhook.

package/README.md

@@ -4,7 +4,7 @@ JSON Schema definitions and validation for jambonz verb applications.
 
 ## What's Included
 
-- **33 verb schemas** (`verbs/`) -- every jambonz verb (say, gather, dial, openai_s2s, pipeline, etc.)
+- **33 verb schemas** (`verbs/`) -- every jambonz verb (say, gather, dial, openai_s2s, agent, etc.)
 - **42 component schemas** (`components/`) -- shared types (synthesizer, recognizer, target, actionHook, etc.)
 - **32 callback schemas** (`callbacks/`) -- actionHook payload definitions for each verb
 - **AGENTS.md** -- language-agnostic developer guide covering the verb model, transport modes, and protocol

package/callbacks/{pipeline-turn.schema.json → agent-turn.schema.json}

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://jambonz.org/schema/callbacks/pipeline-turn",
-  "title": "Pipeline EventHook Events",
-  "description": "Events sent to the pipeline verb's eventHook during a conversation. These are sent as 'pipeline:event' messages over the WebSocket connection.",
+  "$id": "https://jambonz.org/schema/callbacks/agent-turn",
+  "title": "Agent EventHook Events",
+  "description": "Events sent to the agent verb's eventHook during a conversation. These are sent as 'agent:event' messages over the WebSocket connection.",
   "type": "object",
   "oneOf": [
     {
@@ -84,7 +84,7 @@
     {
       "properties": {
         "type": {
-          "const": "agent_response",
+          "const": "llm_response",
           "description": "Sent when the LLM has finished generating its response for the current turn. Contains the complete response text."
         },
         "response": {

package/callbacks/call-status.schema.json

@@ -2,12 +2,17 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://jambonz.org/schema/callbacks/call-status",
   "title": "Call Status Webhook Payload",
-  "description": "Payload sent to the call status webhook URL whenever the call state changes (e.g. trying, in-progress, completed). The status webhook is configured at the application level in jambonz. Multiple status events are sent over the life of a call. The final event (completed or failed) includes additional fields like duration and termination cause.",
+  "description": "Payload sent to the call status webhook URL whenever the call state changes (e.g. trying, in-progress, completed). The status webhook is configured at the application level in jambonz. Multiple status events are sent over the life of a call. The final event (completed or failed) includes additional fields like duration and termination cause.\n\n**Capturing B-leg call_sid:** When using the dial verb to bridge calls, status events are sent for both legs. The A-leg (original inbound call) has `direction: 'inbound'`. The B-leg (outbound dialed call) has `direction: 'outbound'`. To capture the B-leg's call_sid for later use (e.g., injecting commands to the B-leg), listen for status events where `direction === 'outbound'` and extract the `call_sid` field.",
   "allOf": [
     { "$ref": "base" }
   ],
   "type": "object",
   "properties": {
+    "direction": {
+      "type": "string",
+      "enum": ["inbound", "outbound"],
+      "description": "Call direction. 'inbound' = A-leg (original incoming call to the application). 'outbound' = B-leg (call placed by the dial verb). Use this field to identify which leg generated the status event, especially when capturing the B-leg's call_sid for mid-call control."
+    },
     "call_termination_by": {
       "type": "string",
       "enum": ["caller", "jambonz"],

package/components/recognizer-assemblyAiOptions.schema.json

@@ -28,15 +28,15 @@
     },
     "minEndOfTurnSilenceWhenConfident": {
       "type": "number",
-      "description": "Minimum silence duration (seconds) to trigger end-of-turn when confidence is met."
+      "description": "Minimum silence duration (milliseconds) to trigger end-of-turn when confidence is met. Default: 400."
     },
     "maxTurnSilence": {
       "type": "number",
-      "description": "Maximum silence duration (seconds) before forcing end-of-turn."
+      "description": "Maximum silence duration (milliseconds) before forcing end-of-turn. Default: 1280."
     },
     "minTurnSilence": {
       "type": "number",
-      "description": "Minimum silence duration (seconds) before allowing end-of-turn."
+      "description": "Minimum silence duration (milliseconds) before allowing end-of-turn."
     },
     "keyterms": {
       "type": "array",

package/docs/guides/bridged-call-patterns.md

@@ -0,0 +1,261 @@
+# Bridged Call Patterns
+
+This guide covers common patterns for building applications that bridge two call legs (A-leg and B-leg) and need to interact with each party independently—such as real-time translation, call coaching, or call monitoring.
+
+## Understanding A-leg and B-leg
+
+When an inbound call arrives and your application uses the `dial` verb to connect the caller to another party:
+
+- **A-leg**: The original inbound call (caller → jambonz)
+- **B-leg**: The outbound call placed by the `dial` verb (jambonz → callee)
+
+Each leg has its own `call_sid` identifier and can receive independent commands.
+
+## Capturing the B-leg call_sid
+
+Many patterns require knowing the B-leg's `call_sid` to inject commands to that leg. Capture it from `call:status` events:
+
+```typescript
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  // B-leg events have direction === 'outbound'
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+    console.log(`B-leg call_sid captured: ${dialCallSid}`);
+  }
+});
+```
+
+**When it fires:** The `call:status` event with `direction: 'outbound'` fires when the dial verb initiates the B-leg call. You'll receive status updates for both legs throughout the call lifecycle.
+
+## Setting Up Transcription on Both Legs
+
+To transcribe both parties separately (e.g., for translation), configure transcription on each leg:
+
+```typescript
+session
+  // Transcribe A-leg (caller)
+  .transcribe({
+    transcriptionHook: '/transcription/caller',
+    channel: 1,  // Near-end = caller's voice
+    recognizer: {
+      vendor: 'deepgram',
+      language: 'en-US',
+      deepgramOptions: { model: 'nova-2' }
+    }
+  })
+  // Bridge to B-leg with separate transcription
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    transcribe: {
+      transcriptionHook: '/transcription/callee',
+      channel: 2,  // Far-end from A-leg = callee's voice
+      recognizer: {
+        vendor: 'deepgram',
+        language: 'es-ES',
+        deepgramOptions: { model: 'nova-2' }
+      }
+    }
+  })
+  .send();
+```
+
+### Channel Values Explained
+
+| Location | Channel | What it captures |
+|----------|---------|------------------|
+| A-leg transcribe | `1` (near-end) | Caller's voice |
+| A-leg transcribe | `2` (far-end) | What caller hears (including B-leg) |
+| dial.transcribe | `2` (far-end) | Callee's voice (B-leg inbound audio) |
+| dial.transcribe | (omitted) | Both parties mixed |
+
+### Identifying the Speaker in Transcription Events
+
+Use the `call_sid` in transcription events to determine who spoke:
+
+```typescript
+session.on('/transcription/caller', (evt: Record<string, any>) => {
+  if (evt.speech?.is_final) {
+    const transcript = evt.speech.alternatives[0].transcript;
+    handleCallerSpeech(transcript);
+  }
+});
+
+session.on('/transcription/callee', (evt: Record<string, any>) => {
+  if (evt.speech?.is_final) {
+    const transcript = evt.speech.alternatives[0].transcript;
+    handleCalleeSpeech(transcript);
+  }
+});
+```
+
+Or with a single hook, use `call_sid` to differentiate:
+
+```typescript
+session.on('/transcription', (evt: Record<string, any>) => {
+  if (!evt.speech?.is_final) return;
+
+  const transcript = evt.speech.alternatives[0].transcript;
+  const speaker = evt.call_sid === dialCallSid ? 'callee' : 'caller';
+
+  console.log(`${speaker}: ${transcript}`);
+});
+```
+
+## Creating Dub Tracks for Audio Injection
+
+To inject audio to each party (e.g., translated speech), create tracks on each leg:
+
+```typescript
+session
+  // Track on A-leg — caller hears it
+  .dub({ action: 'addTrack', track: 'caller-audio' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    // Track on B-leg — callee hears it
+    dub: [
+      { action: 'addTrack', track: 'callee-audio' }
+    ]
+  })
+  .send();
+```
+
+**Track routing rule:** Tracks are heard by the party on whose call leg they exist.
+
+## Injecting Commands to Specific Legs
+
+### Default: Commands go to A-leg
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-audio',
+  say: 'This message is for the caller'
+});
+```
+
+### Targeting B-leg: Pass call_sid as third argument
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-audio',
+  say: 'This message is for the callee'
+}, dialCallSid);  // Third argument routes to B-leg
+```
+
+**Important:** The `call_sid` is passed as a separate third argument, not inside the data object.
+
+## Complete Example: Real-Time Translator
+
+This example bridges an English caller with a Spanish-speaking callee, providing real-time translation in both directions.
+
+```typescript
+import { createEndpoint, Session } from '@jambonz/sdk/websocket';
+import http from 'http';
+
+const server = http.createServer();
+const makeService = createEndpoint({ server, port: 3000 });
+const svc = makeService({ path: '/' });
+
+svc.on('session:new', (session: Session) => {
+  let dialCallSid: string;
+
+  // Capture B-leg call_sid
+  session.on('call:status', (evt: Record<string, any>) => {
+    if (evt.direction === 'outbound') {
+      dialCallSid = evt.call_sid;
+    }
+  });
+
+  // Handle caller's speech (English → Spanish for callee)
+  session.on('/transcription/caller', async (evt: Record<string, any>) => {
+    session.reply();
+    if (!evt.speech?.is_final) return;
+
+    const transcript = evt.speech.alternatives[0].transcript;
+    const translated = await translateToSpanish(transcript);
+
+    // Inject to B-leg track (callee hears it)
+    session.injectCommand('dub', {
+      action: 'sayOnTrack',
+      track: 'callee-audio',
+      say: {
+        text: translated,
+        synthesizer: { vendor: 'elevenlabs', language: 'es-ES' }
+      }
+    }, dialCallSid);
+  });
+
+  // Handle callee's speech (Spanish → English for caller)
+  session.on('/transcription/callee', async (evt: Record<string, any>) => {
+    session.reply();
+    if (!evt.speech?.is_final) return;
+
+    const transcript = evt.speech.alternatives[0].transcript;
+    const translated = await translateToEnglish(transcript);
+
+    // Inject to A-leg track (caller hears it)
+    session.injectCommand('dub', {
+      action: 'sayOnTrack',
+      track: 'caller-audio',
+      say: {
+        text: translated,
+        synthesizer: { vendor: 'elevenlabs', language: 'en-US' }
+      }
+    });
+  });
+
+  // Set up the call
+  session
+    .dub({ action: 'addTrack', track: 'caller-audio' })
+    .transcribe({
+      transcriptionHook: '/transcription/caller',
+      channel: 1,
+      recognizer: { vendor: 'deepgram', language: 'en-US' }
+    })
+    .dial({
+      target: [{ type: 'phone', number: process.env.CALLEE_NUMBER! }],
+      dub: [
+        { action: 'addTrack', track: 'callee-audio' }
+      ],
+      transcribe: {
+        transcriptionHook: '/transcription/callee',
+        channel: 2,
+        recognizer: { vendor: 'deepgram', language: 'es-ES' }
+      }
+    })
+    .send();
+});
+
+async function translateToSpanish(text: string): Promise<string> {
+  // Implement translation logic
+  return text;
+}
+
+async function translateToEnglish(text: string): Promise<string> {
+  // Implement translation logic
+  return text;
+}
+```
+
+## Summary: Key Patterns
+
+| Pattern | Implementation |
+|---------|----------------|
+| Capture B-leg call_sid | Listen for `call:status` where `direction === 'outbound'` |
+| Transcribe caller | `transcribe` with `channel: 1` on A-leg |
+| Transcribe callee | `transcribe` with `channel: 2` nested in `dial` |
+| Audio track for caller | `dub` with `addTrack` on A-leg |
+| Audio track for callee | `dub` with `addTrack` in `dial.dub` array |
+| Inject to A-leg | `session.injectCommand(verb, data)` |
+| Inject to B-leg | `session.injectCommand(verb, data, dialCallSid)` |
+
+## See Also
+
+- `docs/verbs/transcribe.md` - Transcribe verb usage guide
+- `docs/verbs/dub.md` - Dub verb usage guide
+- `docs/guides/session-commands.md` - Session commands reference
+- `callback:call-status` - Call status webhook schema
+- `verb:dial` - Dial verb schema

package/docs/guides/session-commands.md

@@ -143,16 +143,54 @@ For any command not covered by a specific method:
 session.injectCommand('commandName', { ...data });
 ```
 
-## Pipeline Update
+### Targeting Specific Call Legs
 
-The `updatePipeline()` method sends mid-conversation updates to an active `pipeline` verb. Four operation types are supported:
+When bridging calls with the `dial` verb, you may need to inject commands to a specific call leg (A-leg or B-leg). By default, `injectCommand` targets the current session's call (A-leg). To target the B-leg (or any other call), pass the target `call_sid` as the third argument.
+
+**Capturing the B-leg call_sid:**
+
+Listen for `call:status` events with `direction === 'outbound'` to capture the B-leg's call_sid:
+
+```typescript
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+  }
+});
+```
+
+**Injecting commands to specific legs:**
+
+```typescript
+// Target A-leg (current session) — omit the third argument:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-track',
+  say: 'Message for the caller'
+});
+
+// Target B-leg — pass call_sid as third argument:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-track',
+  say: 'Message for the callee'
+}, dialCallSid);
+```
+
+This pattern is essential for applications like real-time translation, where you need to inject translated speech to each party separately based on which leg's audio was transcribed.
+
+## Agent Update
+
+The `updateAgent()` method sends mid-conversation updates to an active `agent` verb. Four operation types are supported:
 
 ### Update Instructions
 
 Replace the LLM system prompt while the conversation is in progress:
 
 ```typescript
-session.updatePipeline({
+session.updateAgent({
   type: 'update_instructions',
   instructions: 'You are now a billing support agent. Help the caller with invoice questions.',
 });
@@ -163,7 +201,7 @@ session.updatePipeline({
 Append messages to the LLM conversation history (e.g. CRM data retrieved after the call started):
 
 ```typescript
-session.updatePipeline({
+session.updateAgent({
   type: 'inject_context',
   messages: [
     { role: 'system', content: 'Customer account #12345: Gold tier, 3 open tickets.' },
@@ -176,7 +214,7 @@ session.updatePipeline({
 Replace the tool set available to the LLM:
 
 ```typescript
-session.updatePipeline({
+session.updateAgent({
   type: 'update_tools',
   tools: [
     {
@@ -193,24 +231,24 @@ session.updatePipeline({
 
 ### Generate Reply
 
-Prompt the LLM to generate a new response. If the pipeline is not idle, the request is queued and executes when the current turn completes. Use `interrupt: true` to cancel the current response and generate immediately.
+Prompt the LLM to generate a new response. If the agent is not idle, the request is queued and executes when the current turn completes. Use `interrupt: true` to cancel the current response and generate immediately.
 
 ```typescript
 // Simple prompt
-session.updatePipeline({
+session.updateAgent({
   type: 'generate_reply',
   user_input: 'The customer just entered their account number: 12345',
 });
 
 // With one-shot instructions
-session.updatePipeline({
+session.updateAgent({
   type: 'generate_reply',
   user_input: 'Customer is asking about refunds',
   instructions: 'Be empathetic and offer a 20% discount before processing a refund.',
 });
 
 // Interrupt current response and generate a new one
-session.updatePipeline({
+session.updateAgent({
   type: 'generate_reply',
   user_input: 'Urgent: supervisor override',
   interrupt: true,
@@ -219,7 +257,7 @@ session.updatePipeline({
 
 ## LLM Tool Output
 
-When using the `pipeline` verb with a `toolHook`, tool call requests arrive as events. Return results with:
+When using the `agent` verb with a `toolHook`, tool call requests arrive as events. Return results with:
 
 ```typescript
 session.on('/tool-hook', (evt: Record<string, any>) => {
@@ -237,7 +275,7 @@ The result is stringified and fed back to the LLM as the tool response.
 
 ## Building a Cascaded Voice AI Agent
 
-The **pipeline** verb is the simplest way to build a voice AI agent — jambonz manages everything. But when you need full control over the LLM interaction (custom tool handling, conversation history management, multiple LLM providers, etc.), build a **cascaded agent**: your app handles STT transcripts and LLM calls directly, piping responses back via TTS token streaming.
+The **agent** verb is the simplest way to build a voice AI agent — jambonz manages everything. But when you need full control over the LLM interaction (custom tool handling, conversation history management, multiple LLM providers, etc.), build a **cascaded agent**: your app handles STT transcripts and LLM calls directly, piping responses back via TTS token streaming.
 
 ### Architecture
 
@@ -257,9 +295,9 @@ User speaks again → bargeIn fires → repeat
 
 The key mechanism is the `bargeIn` actionHook on the `config` verb. When enabled with `sticky: true`, it persists across all verbs. Whenever the caller speaks, the `/speech-detected` hook fires with the speech transcript — even while TTS is playing (which triggers an interruption). Your app then calls the LLM and streams the response back.
 
-### When to Use Cascaded vs Pipeline
+### When to Use Cascaded vs Agent
 
-| | Pipeline verb | Cascaded agent |
+| | Agent verb | Cascaded agent |
 |---|---|---|
 | **STT/LLM/TTS** | jambonz orchestrates all three | App owns the LLM; jambonz handles STT and TTS |
 | **Turn detection** | Built-in (Krisp or STT-native) | App manages via bargeIn actionHook |

package/docs/verbs/{pipeline.md → agent.md}

@@ -1,8 +1,8 @@
 ## Overview
 
-The pipeline verb orchestrates a complete voice AI agent by wiring together three separate components — STT, LLM, and TTS — with integrated turn detection. Unlike the s2s verbs (where a single vendor handles everything), pipeline lets you mix and match: e.g. Deepgram for STT, Anthropic for the LLM, and Cartesia for TTS.
+The agent verb orchestrates a complete voice AI agent by wiring together three separate components — STT, LLM, and TTS — with integrated turn detection. Unlike the s2s verbs (where a single vendor handles everything), the agent verb lets you mix and match: e.g. Deepgram for STT, Anthropic for the LLM, and Cartesia for TTS.
 
-Pipeline manages the full conversational turn cycle:
+The agent manages the full conversational turn cycle:
 1. User speaks → STT produces a transcript
 2. Turn detection decides the user is done speaking
 3. Transcript is sent to the LLM
@@ -12,7 +12,7 @@ Pipeline manages the full conversational turn cycle:
 
 ## Turn detection
 
-The `turnDetection` property controls how the pipeline decides the user has finished speaking.
+The `turnDetection` property controls how the agent decides the user has finished speaking.
 
 **`"stt"` (default)** — Uses the STT vendor's native end-of-utterance signal. For most vendors this is silence-based. Some vendors have smarter built-in turn detection:
 - **deepgramflux** — Acoustic + semantic turn detection (Deepgram's "Flux" model)
@@ -105,15 +105,15 @@ The `eventHook` receives real-time events during the conversation. In WebSocket
 | Event type | Description | Key fields |
 |---|---|---|
 | `user_transcript` | User speech recognized | `transcript` |
-| `agent_response` | Assistant reply text | `response` |
+| `llm_response` | Assistant reply text | `response` |
 | `user_interruption` | User barged in | — |
 | `turn_end` | End-of-turn summary | `transcript`, `response`, `interrupted`, `latency` |
 
-The `turn_end` event is the most useful for observability. It includes per-component latency metrics (STT, LLM, TTS) in milliseconds. See the `callback:pipeline-turn` schema for the full payload structure.
+The `turn_end` event is the most useful for observability. It includes per-component latency metrics (STT, LLM, TTS) in milliseconds. See the `callback:agent-turn` schema for the full payload structure.
 
 ## toolHook (function calling)
 
-When the LLM requests a tool/function call, the pipeline sends a request to the `toolHook` with:
+When the LLM requests a tool/function call, the agent sends a request to the `toolHook` with:
 
 ```json
 {
@@ -131,11 +131,11 @@ The `arguments` field is already parsed (an object, not a JSON string).
 
 ## MCP servers (external tools)
 
-Instead of (or in addition to) defining tools inline via `llmOptions.tools` and handling them with `toolHook`, you can connect to external MCP servers. The pipeline connects to each server at startup via SSE transport, discovers available tools, and makes them available to the LLM alongside any inline tools.
+Instead of (or in addition to) defining tools inline via `llmOptions.tools` and handling them with `toolHook`, you can connect to external MCP servers. The agent connects to each server at startup via SSE transport, discovers available tools, and makes them available to the LLM alongside any inline tools.
 
 ```json
 {
-  "verb": "pipeline",
+  "verb": "agent",
   "mcpServers": [
     {
       "url": "https://livescoremcp.com/sse"
@@ -155,7 +155,7 @@ Instead of (or in addition to) defining tools inline via `llmOptions.tools` and
 }
 ```
 
-The [LiveScore MCP server](https://livescoremcp.com/) is a free, public MCP server that exposes tools for live football scores, fixtures, team stats, and player data. The pipeline discovers these tools automatically at startup — no need to define tool schemas in `llmOptions.tools`. A caller can simply ask "what football matches are on right now?" and the LLM will use the `get_live_scores` tool to fetch real-time data.
+The [LiveScore MCP server](https://livescoremcp.com/) is a free, public MCP server that exposes tools for live football scores, fixtures, team stats, and player data. The agent discovers these tools automatically at startup — no need to define tool schemas in `llmOptions.tools`. A caller can simply ask "what football matches are on right now?" and the LLM will use the `get_live_scores` tool to fetch real-time data.
 
 If an MCP server requires authentication, pass credentials in the `auth` property:
 
@@ -172,13 +172,13 @@ If an MCP server requires authentication, pass credentials in the `auth` propert
 }
 ```
 
-**How tool dispatch works**: When the LLM requests a tool call, the pipeline checks MCP servers first. If the tool name matches one discovered from an MCP server, the call is dispatched there directly and the result is fed back to the LLM. If no MCP server provides the tool, it falls through to the `toolHook` webhook. You can use both MCP servers and `toolHook` together — MCP handles the tools it knows about, and `toolHook` handles the rest.
+**How tool dispatch works**: When the LLM requests a tool call, the agent checks MCP servers first. If the tool name matches one discovered from an MCP server, the call is dispatched there directly and the result is fed back to the LLM. If no MCP server provides the tool, it falls through to the `toolHook` webhook. You can use both MCP servers and `toolHook` together — MCP handles the tools it knows about, and `toolHook` handles the rest.
 
-**TypeScript example** — a pipeline agent with the LiveScore MCP server:
+**TypeScript example** — an agent with the LiveScore MCP server:
 
 ```typescript
 session
-  .pipeline({
+  .agent({
     stt: { vendor: 'deepgram', language: 'en-US' },
     tts: { vendor: 'cartesia', voice: 'sonic-english' },
     llm: {
@@ -196,18 +196,18 @@ session
       // { url: 'https://mcp.example.com/sse', auth: { apiKey: 'your-key' } },
     ],
     turnDetection: 'krisp',
-    actionHook: '/pipeline-complete',
+    actionHook: '/agent-complete',
   })
   .send();
 ```
 
 ## Mid-conversation updates
 
-The pipeline supports asynchronous updates while a conversation is in progress. These let you change the agent's behavior, inject new context, modify available tools, or trigger a new LLM response — without interrupting the current verb stack.
+The agent supports asynchronous updates while a conversation is in progress. These let you change the agent's behavior, inject new context, modify available tools, or trigger a new LLM response — without interrupting the current verb stack.
 
 Updates can be sent via:
-- **WebSocket**: `session.updatePipeline(data)` (sends a `pipeline:update` command)
-- **REST API**: `client.calls.updatePipeline(callSid, data)` (sends `pipeline_update` in the PUT body)
+- **WebSocket**: `session.updateAgent(data)` (sends an `agent:update` command)
+- **REST API**: `client.calls.updateAgent(callSid, data)` (sends `agent_update` in the PUT body)
 
 ### update_instructions
 
@@ -215,13 +215,13 @@ Replace the LLM system prompt mid-conversation. Useful when the conversation tra
 
 ```typescript
 // WebSocket
-session.updatePipeline({
+session.updateAgent({
   type: 'update_instructions',
   instructions: 'You are now a billing support agent. Help the caller with invoice questions.',
 });
 
 // REST
-await client.calls.updatePipeline(callSid, {
+await client.calls.updateAgent(callSid, {
   type: 'update_instructions',
   instructions: 'You are now a billing support agent. Help the caller with invoice questions.',
 });
@@ -232,7 +232,7 @@ await client.calls.updatePipeline(callSid, {
 Append messages to the LLM conversation history. Useful for injecting CRM data, call notes, or other context retrieved after the call started.
 
 ```typescript
-session.updatePipeline({
+session.updateAgent({
   type: 'inject_context',
   messages: [
     { role: 'system', content: 'Customer account #12345: Gold tier, 3 open tickets.' },
@@ -245,7 +245,7 @@ session.updatePipeline({
 Replace the tool set available to the LLM. The new tools take effect on the next LLM turn.
 
 ```typescript
-session.updatePipeline({
+session.updateAgent({
   type: 'update_tools',
   tools: [
     {
@@ -262,26 +262,26 @@ session.updatePipeline({
 
 ### generate_reply
 
-Prompt the LLM to generate a new response. If the pipeline is currently idle, the prompt executes immediately. If the pipeline is busy (e.g. the assistant is speaking), the request is queued and executes when the current turn completes.
+Prompt the LLM to generate a new response. If the agent is currently idle, the prompt executes immediately. If the agent is busy (e.g. the assistant is speaking), the request is queued and executes when the current turn completes.
 
 Use `interrupt: true` to cancel the current response and generate immediately — useful for supervisor overrides or urgent context changes.
 
 ```typescript
 // Simple prompt
-session.updatePipeline({
+session.updateAgent({
   type: 'generate_reply',
   user_input: 'The customer just entered their account number: 12345',
 });
 
 // With one-shot instructions
-session.updatePipeline({
+session.updateAgent({
   type: 'generate_reply',
   user_input: 'Customer is asking about refunds',
   instructions: 'Be empathetic and offer a 20% discount before processing a refund.',
 });
 
 // Interrupt current response
-session.updatePipeline({
+session.updateAgent({
   type: 'generate_reply',
   user_input: 'Urgent: supervisor override',
   interrupt: true,
@@ -326,11 +326,11 @@ For Anthropic models, use `"vendor": "anthropic"` and structure messages accordi
 
 ## Greeting
 
-By default (`greeting: true`), the pipeline prompts the LLM to generate an initial greeting before the user speaks. Set `greeting: false` if you want the agent to wait silently for the user to speak first.
+By default (`greeting: true`), the agent prompts the LLM to generate an initial greeting before the user speaks. Set `greeting: false` if you want the agent to wait silently for the user to speak first.
 
 ## Complete example (TypeScript)
 
-A pipeline voice agent using Deepgram STT, OpenAI LLM, and Cartesia TTS with Krisp turn detection. Exposes multiple endpoints with different STT/TTS combinations:
+A voice agent using Deepgram STT, OpenAI LLM, and Cartesia TTS with Krisp turn detection. Exposes multiple endpoints with different STT/TTS combinations:
 
 ```typescript
 import * as http from 'node:http';
@@ -354,19 +354,19 @@ function handleSession(session: Session) {
   const model = session.data.env_vars?.OPENAI_MODEL || 'gpt-4.1-mini';
   const systemPrompt = session.data.env_vars?.SYSTEM_PROMPT || envVars.SYSTEM_PROMPT.default;
 
-  session.on('/pipeline-event', (evt: Record<string, unknown>) => {
+  session.on('/agent-event', (evt: Record<string, unknown>) => {
     if (evt.type === 'turn_end') {
       const { transcript, response, interrupted, latency } = evt as Record<string, unknown>;
       console.log('turn_end', JSON.stringify({ transcript, response, interrupted, latency }, null, 2));
     }
   });
 
-  session.on('/pipeline-complete', () => {
+  session.on('/agent-complete', () => {
     session.hangup().reply();
   });
 
   session
-    .pipeline({
+    .agent({
       stt: {
         vendor: 'deepgram',
         language: 'multi',
@@ -386,8 +386,8 @@ function handleSession(session: Session) {
       turnDetection: 'krisp',
       earlyGeneration: true,
       bargeIn: { enable: true },
-      eventHook: '/pipeline-event',
-      actionHook: '/pipeline-complete',
+      eventHook: '/agent-event',
+      actionHook: '/agent-complete',
     })
     .send();
 }
@@ -426,19 +426,19 @@ function handleSession(session) {
   const model = session.data.env_vars?.OPENAI_MODEL || 'gpt-4.1-mini';
   const systemPrompt = session.data.env_vars?.SYSTEM_PROMPT || envVars.SYSTEM_PROMPT.default;
 
-  session.on('/pipeline-event', (evt) => {
+  session.on('/agent-event', (evt) => {
     if (evt.type === 'turn_end') {
       const { transcript, response, interrupted, latency } = evt;
       console.log('turn_end', JSON.stringify({ transcript, response, interrupted, latency }, null, 2));
     }
   });
 
-  session.on('/pipeline-complete', () => {
+  session.on('/agent-complete', () => {
     session.hangup().reply();
   });
 
   session
-    .pipeline({
+    .agent({
       stt: {
         vendor: 'deepgram',
         language: 'multi',
@@ -458,8 +458,8 @@ function handleSession(session) {
       turnDetection: 'krisp',
       earlyGeneration: true,
       bargeIn: { enable: true },
-      eventHook: '/pipeline-event',
-      actionHook: '/pipeline-complete',
+      eventHook: '/agent-event',
+      actionHook: '/agent-complete',
     })
     .send();
 }

package/docs/verbs/dub.md

@@ -0,0 +1,219 @@
+# Dub Verb Usage Guide
+
+The `dub` verb manages auxiliary audio tracks that are mixed into the call audio. Tracks can play background music, coaching whispers, or inject synthesized speech—useful for real-time translation, agent assistance, or audio overlays.
+
+## Track Routing: Who Hears What
+
+**Critical concept:** Dub tracks are heard by the party on whose call leg they are created.
+
+| Where track is created | Who hears it |
+|------------------------|--------------|
+| Main verb stack (A-leg) | Caller |
+| Nested in dial verb's `dub` array | Callee |
+
+When using `injectCommand` to play/say on a track, the command routes to the call leg where the track was created—unless you specify a different `call_sid` as the third argument.
+
+## Basic Usage
+
+### Creating Tracks
+
+Create a track before playing audio on it:
+
+```typescript
+// Track on A-leg (caller hears it)
+session
+  .dub({ action: 'addTrack', track: 'caller-audio' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    dub: [
+      // Track on B-leg (callee hears it)
+      { action: 'addTrack', track: 'callee-audio' }
+    ]
+  })
+  .send();
+```
+
+### Playing Audio on Tracks
+
+```typescript
+// Play audio file
+session
+  .dub({
+    action: 'playOnTrack',
+    track: 'bgm',
+    play: 'https://example.com/music.mp3',
+    loop: true,
+    gain: -15  // Reduce volume by 15dB
+  })
+  .send();
+
+// Synthesize and play speech
+session
+  .dub({
+    action: 'sayOnTrack',
+    track: 'coach',
+    say: 'Ask about their timeline'
+  })
+  .send();
+```
+
+### Controlling Tracks
+
+```typescript
+// Silence a track (mute without removing)
+session.dub({ action: 'silenceTrack', track: 'bgm' }).send();
+
+// Remove a track entirely
+session.dub({ action: 'removeTrack', track: 'bgm' }).send();
+```
+
+## Mid-Call Audio Injection with injectCommand
+
+The most powerful use of dub tracks is injecting audio mid-call via `injectCommand`. This is how you implement real-time features like translation or coaching.
+
+### Injecting to the Current Call Leg (A-leg)
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-audio',
+  say: 'Translated text for the caller'
+});
+```
+
+### Injecting to a Specific Call Leg (B-leg)
+
+When the target track exists on a different call leg, pass the target `call_sid` as the third argument:
+
+```typescript
+// First, capture the B-leg call_sid from call:status events
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+  }
+});
+
+// Then inject to the B-leg
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-audio',
+  say: 'Translated text for the callee'
+}, dialCallSid);
+```
+
+**Important:** The third argument is the `call_sid` of the call leg where the track exists, not part of the data object.
+
+## Common Use Cases
+
+### Real-Time Translation
+
+Set up tracks for each party, then inject translated speech based on transcriptions:
+
+```typescript
+session
+  .dub({ action: 'addTrack', track: 'caller-translation' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    dub: [
+      { action: 'addTrack', track: 'callee-translation' }
+    ],
+    transcribe: {
+      transcriptionHook: '/transcription',
+      recognizer: { vendor: 'deepgram' }
+    }
+  })
+  .send();
+
+// When callee speaks, translate and play to caller:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-translation',
+  say: { text: translatedText, synthesizer: { language: 'en-US' } }
+});
+
+// When caller speaks, translate and play to callee:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-translation',
+  say: { text: translatedText, synthesizer: { language: 'es-ES' } }
+}, dialCallSid);
+```
+
+### Agent Coaching / Whisper
+
+Play prompts only the agent hears (A-leg is the agent):
+
+```typescript
+session
+  .dub({ action: 'addTrack', track: 'coach' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }]
+  })
+  .send();
+
+// Supervisor sends a coaching message:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'coach',
+  say: 'Offer them a 20% discount'
+});
+```
+
+### Background Music / Hold Music
+
+```typescript
+session
+  .dub({ action: 'addTrack', track: 'bgm' })
+  .dub({
+    action: 'playOnTrack',
+    track: 'bgm',
+    play: 'https://example.com/hold-music.mp3',
+    loop: true,
+    gain: -20
+  })
+  .send();
+```
+
+## Say Configuration Object
+
+The `say` property can be a string or a configuration object for more control:
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'translation',
+  say: {
+    text: 'Hello, how can I help you?',
+    synthesizer: {
+      vendor: 'elevenlabs',
+      voice: 'EXAVITQu4vr4xnSDxMaL',
+      language: 'en-US'
+    }
+  }
+});
+```
+
+## Gain Control
+
+Use the `gain` property to adjust track volume in dB:
+
+- Negative values reduce volume (e.g., `-15` for quiet background music)
+- Positive values increase volume (use carefully to avoid clipping)
+- `0` is the default (no change)
+
+```typescript
+session.dub({
+  action: 'playOnTrack',
+  track: 'bgm',
+  play: 'https://example.com/music.mp3',
+  gain: -15
+}).send();
+```
+
+## See Also
+
+- `verb:dub` - Full schema with all properties
+- `docs/guides/session-commands.md` - injectCommand documentation
+- `docs/guides/bridged-call-patterns.md` - Complete guide to bridged call scenarios

package/docs/verbs/transcribe.md

@@ -0,0 +1,167 @@
+# Transcribe Verb Usage Guide
+
+The `transcribe` verb enables real-time speech-to-text on a call. Transcription runs as a background process—subsequent verbs execute immediately while transcription continues. Results are streamed to your `transcriptionHook` webhook as they are produced.
+
+## Basic Usage
+
+```typescript
+session
+  .transcribe({
+    transcriptionHook: '/transcription',
+    recognizer: {
+      vendor: 'deepgram',
+      language: 'en-US',
+      deepgramOptions: {
+        model: 'nova-2',
+        smartFormatting: true
+      }
+    }
+  })
+  .dial({ target: [{ type: 'phone', number: '+15551234567' }] })
+  .send();
+```
+
+## Channel Isolation for Bridged Calls
+
+When transcribing a bridged call (A-leg connected to B-leg via `dial`), you can isolate which party's audio to transcribe using the `channel` property:
+
+| Channel | Description |
+|---------|-------------|
+| (omitted) | Both parties' audio, mixed |
+| `1` | Near-end audio (local party—caller on A-leg, callee on B-leg) |
+| `2` | Far-end audio (remote party) |
+
+### Transcribing Both Legs Separately
+
+To get separate transcriptions for each party in a bridged call:
+
+```typescript
+session
+  .transcribe({
+    transcriptionHook: '/transcription/caller',
+    channel: 1,  // Caller's audio (A-leg near-end)
+    recognizer: { vendor: 'deepgram', language: 'en-US' }
+  })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    transcribe: {
+      transcriptionHook: '/transcription/callee',
+      channel: 2,  // Callee's audio (B-leg far-end from A-leg perspective)
+      recognizer: { vendor: 'deepgram', language: 'es-ES' }
+    }
+  })
+  .send();
+```
+
+**Important:** When `transcribe` is nested in the `dial` verb, channel 2 isolates the B-leg's inbound audio (what the callee is saying).
+
+## Transcription Hook Payload
+
+Your webhook receives transcription results with these key fields:
+
+```typescript
+session.on('/transcription', (evt: Record<string, any>) => {
+  const {
+    call_sid,           // Which call leg generated this transcript
+    speech,             // Speech recognition results
+    is_final,           // true for final results, false for interim
+    transcription_sid,  // Unique ID for this transcription session
+  } = evt;
+
+  if (speech?.is_final) {
+    const { transcript, confidence } = speech.alternatives[0];
+    console.log(`[${call_sid}] ${transcript} (${confidence})`);
+  }
+});
+```
+
+## Identifying Which Party Spoke
+
+The `call_sid` in transcription events identifies which call leg generated the transcript. If you're tracking the B-leg's call_sid (captured from `call:status` events), you can identify the speaker:
+
+```typescript
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+  }
+});
+
+session.on('/transcription', (evt: Record<string, any>) => {
+  const speaker = evt.call_sid === dialCallSid ? 'callee' : 'caller';
+  console.log(`${speaker}: ${evt.speech?.alternatives[0]?.transcript}`);
+});
+```
+
+## Nested Transcribe in Config vs Dial
+
+You can enable transcription in two places:
+
+### In the main verb stack (or config)
+
+Transcribes the A-leg. Without `channel`, captures caller audio. With `channel: 2`, captures far-end (what caller hears).
+
+```typescript
+session
+  .config({
+    transcribe: {
+      enable: true,
+      transcriptionHook: '/transcription',
+      recognizer: { vendor: 'deepgram' }
+    }
+  })
+  .send();
+```
+
+### Nested in dial
+
+Transcribes during the bridged call. Without `channel`, captures both parties mixed. With `channel: 2`, isolates B-leg audio.
+
+```typescript
+session
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    transcribe: {
+      transcriptionHook: '/transcription',
+      channel: 2,  // Just the callee's voice
+      recognizer: { vendor: 'deepgram', language: 'es-ES' }
+    }
+  })
+  .send();
+```
+
+## Interim vs Final Results
+
+Most STT vendors provide both interim (partial) and final transcription results:
+
+- **Interim results** (`is_final: false`): Real-time partial transcripts that update as speech continues. Useful for live displays.
+- **Final results** (`is_final: true`): Complete utterance transcripts after the speaker pauses. Use these for processing/translation.
+
+```typescript
+session.on('/transcription', (evt: Record<string, any>) => {
+  if (evt.speech?.is_final) {
+    // Process complete utterance
+    processTranscript(evt.speech.alternatives[0].transcript);
+  }
+  // Optionally handle interim results for live display
+});
+```
+
+## Enabling/Disabling Transcription
+
+Use `enable: false` to stop background transcription:
+
+```typescript
+session
+  .config({
+    transcribe: { enable: false }
+  })
+  .send();
+```
+
+## See Also
+
+- `callback:transcribe` - Full transcription webhook payload schema
+- `component:recognizer` - STT configuration options per vendor
+- `docs/guides/bridged-call-patterns.md` - Complete guide to bridged call scenarios

package/jambonz-app.schema.json

@@ -28,7 +28,7 @@
         { "$ref": "verbs/deepgram_s2s" },
         { "$ref": "verbs/ultravox_s2s" },
         { "$ref": "verbs/dialogflow" },
-        { "$ref": "verbs/pipeline" },
+        { "$ref": "verbs/agent" },
         { "$ref": "verbs/conference" },
         { "$ref": "verbs/transcribe" },
         { "$ref": "verbs/enqueue" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jambonz/schema",
-  "version": "0.1.6",
+  "version": "0.2.2",
   "description": "JSON Schema definitions and validation for jambonz verb applications",
   "main": "index.js",
   "scripts": {

package/verbs/{pipeline.schema.json → agent.schema.json}

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://jambonz.org/schema/verbs/pipeline",
+  "$id": "https://jambonz.org/schema/verbs/agent",
   "minVersion": "10.1.0",
-  "title": "Pipeline",
-  "description": "Configures a complete STT → LLM → TTS voice AI pipeline with integrated turn detection. Provides a higher-level abstraction than manually orchestrating the individual components. Optimized for building voice AI agents with proper turn-taking behavior.",
+  "title": "Agent",
+  "description": "Configures a complete voice AI agent by wiring together STT → LLM → TTS with integrated turn detection. Provides a higher-level abstraction than manually orchestrating the individual components. Optimized for building voice AI agents with proper turn-taking behavior.",
   "type": "object",
   "properties": {
     "verb": {
-      "const": "pipeline"
+      "const": "agent"
     },
     "id": {
       "type": "string",
@@ -15,11 +15,11 @@
     },
     "stt": {
       "$ref": "../components/recognizer",
-      "description": "Speech-to-text configuration for the pipeline."
+      "description": "Speech-to-text configuration for the agent."
     },
     "tts": {
       "$ref": "../components/synthesizer",
-      "description": "Text-to-speech configuration for the pipeline."
+      "description": "Text-to-speech configuration for the agent."
     },
     "turnDetection": {
       "oneOf": [
@@ -53,7 +53,7 @@
         }
       ],
       "default": "stt",
-      "description": "Turn detection strategy. Controls when the pipeline decides the user has finished speaking. STT vendors with native turn-taking (deepgramflux, assemblyai, speechmatics) always use their built-in detection regardless of this setting."
+      "description": "Turn detection strategy. Controls when the agent decides the user has finished speaking. STT vendors with native turn-taking (deepgramflux, assemblyai, speechmatics) always use their built-in detection regardless of this setting."
     },
     "bargeIn": {
       "type": "object",
@@ -86,16 +86,16 @@
     },
     "llm": {
       "type": "object",
-      "description": "LLM configuration for the pipeline. See the 'llm' verb schema for details.",
+      "description": "LLM configuration for the agent. See the 'llm' verb schema for details.",
       "additionalProperties": true
     },
     "actionHook": {
       "$ref": "../components/actionHook",
-      "description": "A webhook invoked when the pipeline ends."
+      "description": "A webhook invoked when the agent ends."
     },
     "eventHook": {
       "$ref": "../components/actionHook",
-      "description": "A webhook invoked for pipeline events. Receives event types: 'user_transcript' (user speech recognized), 'agent_response' (assistant reply), 'user_interruption' (barge-in detected), and 'turn_end' (end-of-turn summary with transcript, response, and latency metrics)."
+      "description": "A webhook invoked for agent events. Receives event types: 'user_transcript' (user speech recognized), 'llm_response' (assistant reply), 'user_interruption' (barge-in detected), and 'turn_end' (end-of-turn summary with transcript, response, and latency metrics)."
     },
     "toolHook": {
       "$ref": "../components/actionHook",
@@ -171,7 +171,7 @@
         },
         "required": ["url"]
       },
-      "description": "External MCP servers that provide tools to the LLM. The pipeline connects at startup via SSE, discovers available tools, and makes them callable by the LLM."
+      "description": "External MCP servers that provide tools to the LLM. The agent connects at startup via SSE, discovers available tools, and makes them callable by the LLM."
     }
   },
   "required": [
@@ -179,7 +179,7 @@
   ],
   "examples": [
     {
-      "verb": "pipeline",
+      "verb": "agent",
       "stt": {
         "vendor": "deepgram",
         "language": "en-US"
@@ -201,10 +201,10 @@
         }
       },
       "turnDetection": "stt",
-      "actionHook": "/pipeline-complete"
+      "actionHook": "/agent-complete"
     },
     {
-      "verb": "pipeline",
+      "verb": "agent",
       "stt": {
         "vendor": "deepgram",
         "language": "en-US"
@@ -234,7 +234,7 @@
         "minSpeechDuration": 0.3,
         "sticky": false
       },
-      "actionHook": "/pipeline-complete"
+      "actionHook": "/agent-complete"
     }
   ]
 }

package/verbs/dub.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://jambonz.org/schema/verbs/dub",
   "minVersion": "0.9.6",
   "title": "Dub",
-  "description": "Manages audio dubbing tracks on a call. Allows adding, removing, and controlling auxiliary audio tracks that are mixed into the call audio. Used for background music, coaching whispers, or injecting audio from external sources.",
+  "description": "Manages audio dubbing tracks on a call. Allows adding, removing, and controlling auxiliary audio tracks that are mixed into the call audio. Used for background music, coaching whispers, or injecting audio from external sources.\n\n**Track Routing:** Tracks are heard by the party on whose call leg they are created. A dub verb in the main verb stack (A-leg) creates tracks heard by the caller. A dub verb nested in the dial verb's `dub` array creates tracks heard by the callee. When using injectCommand to play/say on a track from a different call leg, pass the target call's `call_sid` as the third argument to `session.injectCommand()` to route the command to the correct leg.",
   "type": "object",
   "properties": {
     "verb": {

package/verbs/transcribe.schema.json

@@ -37,7 +37,8 @@
     },
     "channel": {
       "type": "number",
-      "description": "Specific audio channel to transcribe."
+      "enum": [1, 2],
+      "description": "Specific audio channel to transcribe. Channel 1 = near-end (local party's audio, i.e. caller on A-leg or callee on B-leg). Channel 2 = far-end (remote party's audio). When transcribe is nested in the dial verb, omitting channel captures both legs mixed; specifying channel: 2 isolates the B-leg's inbound audio."
     }
   },
   "examples": [