vellum 0.2.12 → 0.2.14

package/src/config/bundled-skills/contacts/tools/contact-merge.ts

@@ -1,9 +1,57 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { executeContactMerge } from '../../../../tools/contacts/contact-merge.js';
+import { mergeContacts, getContact } from '../../../../contacts/contact-store.js';
 
-export async function run(
+export async function executeContactMerge(
   input: Record<string, unknown>,
-  context: ToolContext,
+  _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  return executeContactMerge(input, context);
+  const keepId = input.keep_id as string | undefined;
+  const mergeId = input.merge_id as string | undefined;
+
+  if (!keepId || typeof keepId !== 'string') {
+    return { content: 'Error: keep_id is required', isError: true };
+  }
+  if (!mergeId || typeof mergeId !== 'string') {
+    return { content: 'Error: merge_id is required', isError: true };
+  }
+
+  // Show what will be merged for clarity
+  const keepContact = getContact(keepId);
+  const mergeContact = getContact(mergeId);
+
+  if (!keepContact) {
+    return { content: `Error: Contact "${keepId}" not found`, isError: true };
+  }
+  if (!mergeContact) {
+    return { content: `Error: Contact "${mergeId}" not found`, isError: true };
+  }
+
+  try {
+    const merged = mergeContacts(keepId, mergeId);
+
+    const channelList = merged.channels
+      .map((ch) => `  - ${ch.type}: ${ch.address}${ch.isPrimary ? ' (primary)' : ''}`)
+      .join('\n');
+
+    return {
+      content: [
+        `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
+        ``,
+        `Surviving contact (${merged.id}):`,
+        `  Name: ${merged.displayName}`,
+        `  Importance: ${merged.importance.toFixed(2)}`,
+        `  Interactions: ${merged.interactionCount}`,
+        merged.relationship ? `  Relationship: ${merged.relationship}` : null,
+        merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
+        ``,
+        `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
+      ].filter(Boolean).join('\n'),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
 }
+
+export { executeContactMerge as run };

package/src/config/bundled-skills/contacts/tools/contact-search.ts

@@ -1,9 +1,60 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { executeContactSearch } from '../../../../tools/contacts/contact-search.js';
+import { searchContacts } from '../../../../contacts/contact-store.js';
+import type { ContactWithChannels } from '../../../../contacts/types.js';
 
-export async function run(
+function formatContactSummary(c: ContactWithChannels): string {
+  const parts = [`- **${c.displayName}** (ID: ${c.id})`];
+  if (c.relationship) parts.push(`  Relationship: ${c.relationship}`);
+  parts.push(`  Importance: ${c.importance.toFixed(2)} | Interactions: ${c.interactionCount}`);
+  if (c.channels.length > 0) {
+    const channelList = c.channels
+      .map((ch) => `${ch.type}:${ch.address}${ch.isPrimary ? '*' : ''}`)
+      .join(', ');
+    parts.push(`  Channels: ${channelList}`);
+  }
+  return parts.join('\n');
+}
+
+export async function executeContactSearch(
   input: Record<string, unknown>,
-  context: ToolContext,
+  _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  return executeContactSearch(input, context);
+  const query = input.query as string | undefined;
+  const channelAddress = input.channel_address as string | undefined;
+  const channelType = input.channel_type as string | undefined;
+  const relationship = input.relationship as string | undefined;
+  const limit = input.limit as number | undefined;
+
+  if (!query && !channelAddress && !relationship) {
+    return {
+      content: 'Error: At least one search criterion is required (query, channel_address, or relationship)',
+      isError: true,
+    };
+  }
+
+  try {
+    const results = searchContacts({
+      query,
+      channelAddress,
+      channelType,
+      relationship,
+      limit,
+    });
+
+    if (results.length === 0) {
+      return { content: 'No contacts found matching the search criteria.', isError: false };
+    }
+
+    const lines = [`Found ${results.length} contact(s):\n`];
+    for (const contact of results) {
+      lines.push(formatContactSummary(contact));
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
 }
+
+export { executeContactSearch as run };

package/src/config/bundled-skills/contacts/tools/contact-upsert.ts

@@ -1,9 +1,66 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { executeContactUpsert } from '../../../../tools/contacts/contact-upsert.js';
+import { upsertContact } from '../../../../contacts/contact-store.js';
 
-export async function run(
+function formatContact(c: ReturnType<typeof upsertContact>): string {
+  const lines = [
+    `Contact ${c.id}`,
+    `  Name: ${c.displayName}`,
+  ];
+  if (c.relationship) lines.push(`  Relationship: ${c.relationship}`);
+  lines.push(`  Importance: ${c.importance.toFixed(2)}`);
+  if (c.responseExpectation) lines.push(`  Response expectation: ${c.responseExpectation}`);
+  if (c.preferredTone) lines.push(`  Preferred tone: ${c.preferredTone}`);
+  if (c.interactionCount > 0) lines.push(`  Interactions: ${c.interactionCount}`);
+  if (c.channels.length > 0) {
+    lines.push('  Channels:');
+    for (const ch of c.channels) {
+      const primary = ch.isPrimary ? ' (primary)' : '';
+      lines.push(`    - ${ch.type}: ${ch.address}${primary}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export async function executeContactUpsert(
   input: Record<string, unknown>,
-  context: ToolContext,
+  _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  return executeContactUpsert(input, context);
+  const displayName = input.display_name as string | undefined;
+  if (!displayName || typeof displayName !== 'string' || displayName.trim().length === 0) {
+    return { content: 'Error: display_name is required and must be a non-empty string', isError: true };
+  }
+
+  const importance = input.importance as number | undefined;
+  if (importance !== undefined && (typeof importance !== 'number' || importance < 0 || importance > 1)) {
+    return { content: 'Error: importance must be a number between 0 and 1', isError: true };
+  }
+
+  const rawChannels = input.channels as Array<{ type: string; address: string; is_primary?: boolean }> | undefined;
+  const channels = rawChannels?.map((ch) => ({
+    type: ch.type,
+    address: ch.address,
+    isPrimary: ch.is_primary,
+  }));
+
+  try {
+    const contact = upsertContact({
+      id: input.id as string | undefined,
+      displayName: displayName.trim(),
+      relationship: input.relationship as string | undefined,
+      importance,
+      responseExpectation: input.response_expectation as string | undefined,
+      preferredTone: input.preferred_tone as string | undefined,
+      channels,
+    });
+
+    return {
+      content: `${contact.created ? 'Created' : 'Updated'} contact:\n${formatContact(contact)}`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
 }
+
+export { executeContactUpsert as run };

package/src/config/bundled-skills/messaging/SKILL.md

@@ -37,7 +37,7 @@ Telegram uses a bot token (not OAuth). Install and load the **telegram-setup** s
    - Then call `skill_load` with `skill: "telegram-setup"`.
    - Tell the user: *"I've loaded a setup guide for Telegram. It will walk you through connecting a Telegram bot to your assistant."*
 
-The telegram-setup skill handles: verifying the bot token from @BotFather, generating a webhook secret, registering the webhook with Telegram, registering bot commands, and storing credentials securely.
+The telegram-setup skill handles: verifying the bot token from @BotFather, generating a webhook secret, registering bot commands, and storing credentials securely via the secure credential prompt flow. **Never accept a Telegram bot token pasted in plaintext chat — always use the secure prompt.** Webhook registration with Telegram is handled automatically by the gateway on startup and whenever credentials change.
 
 ## Platform Selection
 
@@ -47,7 +47,7 @@ The telegram-setup skill handles: verifying the bot token from @BotFather, gener
 
 ## Capabilities
 
-### Universal (all platforms)
+### Universal (Slack, Gmail)
 - **Auth Test**: Verify connection and show account info
 - **List Conversations**: Show channels, inboxes, DMs with unread counts
 - **Read Messages**: Read message history from a conversation
@@ -56,6 +56,21 @@ The telegram-setup skill handles: verifying the bot token from @BotFather, gener
 - **Reply**: Reply in a thread (medium risk)
 - **Mark Read**: Mark conversation as read
 
+### Telegram
+Telegram is supported as a messaging provider with limited capabilities compared to Slack and Gmail due to Bot API constraints:
+
+- **Send**: Send a message to a known chat ID (high risk — requires user approval)
+- **Auth Test**: Verify bot token and show bot info
+
+**Not available** (Bot API limitations):
+- List conversations — the Bot API does not expose a method to enumerate chats a bot belongs to
+- Read message history — bots cannot retrieve past messages from a chat
+- Search messages — no search API is available for bots
+
+**Bot-account limits:**
+- The bot can only message users or groups that have previously interacted with it (sent `/start` or been added to a group). Bots cannot initiate conversations with arbitrary phone numbers.
+- Future support for MTProto user-account sessions may lift some of these restrictions.
+
 ### Slack-specific
 - **Add Reaction**: Add an emoji reaction to a message
 - **Leave Channel**: Leave a Slack channel

package/src/config/bundled-skills/messaging/tools/messaging-reply.ts

@@ -20,7 +20,10 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
   try {
     const provider = resolveProvider(platform);
     return withProviderToken(provider, async (token) => {
-      const result = await provider.sendMessage(token, conversationId, text, { threadId });
+      const result = await provider.sendMessage(token, conversationId, text, {
+        threadId,
+      });
+
       return ok(`Reply sent (ID: ${result.id}).`);
     });
   } catch (e) {

package/src/config/bundled-skills/messaging/tools/messaging-send.ts

@@ -18,7 +18,11 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
   try {
     const provider = resolveProvider(platform);
     return withProviderToken(provider, async (token) => {
-      const result = await provider.sendMessage(token, conversationId, text, { subject, inReplyTo });
+      const result = await provider.sendMessage(token, conversationId, text, {
+        subject,
+        inReplyTo,
+      });
+
       return ok(`Message sent (ID: ${result.id}).`);
     });
   } catch (e) {

package/src/config/bundled-skills/messaging/tools/shared.ts

@@ -37,11 +37,16 @@ export function resolveProvider(platformInput?: string): MessagingProvider {
 
 /**
  * Execute a callback with a valid OAuth token for the given provider.
+ * Providers that manage their own auth (e.g. Telegram with a bot token)
+ * expose isConnected() and don't need an OAuth access_token lookup.
  */
 export async function withProviderToken<T>(
   provider: MessagingProvider,
   fn: (token: string) => Promise<T>,
 ): Promise<T> {
+  if (provider.isConnected?.()) {
+    return fn('');
+  }
   return withValidToken(provider.credentialService, fn);
 }
 

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -10,7 +10,9 @@ You are helping the user set up and make outgoing phone calls via Twilio. This s
 
 ## Overview
 
-The calling system uses Twilio's ConversationRelay to place outbound phone calls. When a call is placed:
+The calling system uses Twilio's ConversationRelay to place outbound phone calls. Twilio works out of the box as the default voice provider. Optionally, you can enable ElevenLabs integration for higher-quality, more natural-sounding voices — but this is entirely optional.
+
+When a call is placed:
 
 1. The assistant initiates an outbound call via the Twilio REST API
 2. Twilio connects to the gateway's voice webhook, which returns TwiML
@@ -18,7 +20,14 @@ The calling system uses Twilio's ConversationRelay to place outbound phone calls
 4. An LLM-driven orchestrator manages the conversation — receiving caller speech (transcribed by Deepgram), generating responses via Claude, and streaming text back for TTS playback
 5. The transcript is relayed live to the user's conversation thread
 
-The user's assistant gets its own personal phone number through Twilio.
+Three voice quality modes are available:
+- **`twilio_standard`** (default) — Fully supported. Standard Twilio TTS with Google voices. No extra setup required.
+- **`twilio_elevenlabs_tts`** — Fully supported. Uses ElevenLabs voices through Twilio ConversationRelay for more natural speech.
+- **`elevenlabs_agent`** — **Experimental/restricted.** Full ElevenLabs conversational agent mode. Consultation bridging (`waiting_on_user`) is not yet supported in this mode; the runtime guard blocks it before any ElevenLabs API calls are made. See the "Runtime behavior" section below for fallback and strict-fail details.
+
+You can keep using Twilio only — no changes needed. Enabling ElevenLabs can improve naturalness and quality.
+
+The user's assistant gets its own personal phone number through Twilio. All implicit calls (without an explicit mode) always use this assistant number. Optionally, users can call from their own phone number if it's authorized with the Twilio account — this must be explicitly requested per call via `caller_identity_mode="user_number"`.
 
 ## Step 1: Check Current Configuration
 
@@ -31,11 +40,11 @@ vellum config get calls.enabled
 Also check for existing credentials:
 
 ```bash
-credential_store action=get service=credential:twilio:account_sid
-credential_store action=get service=credential:twilio:auth_token
-credential_store action=get service=credential:twilio:phone_number
+credential_store action=list
 ```
 
+Look for entries with service `twilio` and fields `account_sid`, `auth_token`, and `phone_number`.
+
 If all three credentials exist and `calls.enabled` is `true`, skip to the **Making Calls** section. If credentials are partially configured, skip to whichever step is still needed.
 
 ## Step 2: Create a Twilio Account
@@ -65,26 +74,26 @@ Once the user provides their credentials, store them securely using the `credent
 
 **Account SID:**
 ```
-credential_store action=set service=credential:twilio:account_sid value=<their_account_sid>
+credential_store action=store service=twilio field=account_sid value=<their_account_sid>
 ```
 
 **Auth Token:**
 ```
-credential_store action=set service=credential:twilio:auth_token value=<their_auth_token>
+credential_store action=store service=twilio field=auth_token value=<their_auth_token>
 ```
 
 **Phone Number** (must be in E.164 format, e.g. `+14155551234`):
 ```
-credential_store action=set service=credential:twilio:phone_number value=<their_phone_number>
+credential_store action=store service=twilio field=phone_number value=<their_phone_number>
 ```
 
 After storing, verify each credential was saved:
 ```
-credential_store action=get service=credential:twilio:account_sid
-credential_store action=get service=credential:twilio:auth_token
-credential_store action=get service=credential:twilio:phone_number
+credential_store action=list
 ```
 
+Confirm that entries for service `twilio` with fields `account_sid`, `auth_token`, and `phone_number` appear in the output.
+
 **Important:** Credentials are stored in the OS keychain (macOS Keychain / Linux secret-service) or encrypted at rest. They are never logged or exposed in plaintext.
 
 ## Step 4: Set Up Public Ingress
@@ -130,7 +139,7 @@ vellum config get calls.enabled
 
 Before making real calls, offer a quick verification:
 
-1. Confirm credentials are stored: all three `credential:twilio:*` keys must be present
+1. Confirm credentials are stored: all three Twilio credentials (`account_sid`, `auth_token`, `phone_number`) must be present
 2. Confirm ingress is running: `ingress.publicBaseUrl` must be set and the tunnel active
 3. Confirm calls are enabled: `calls.enabled` must be `true`
 
@@ -138,6 +147,112 @@ Suggest a test call to the user's own phone: **"Want to do a quick test call to
 
 If they agree, ask for their personal phone number and place a test call with a simple task like "Introduce yourself and confirm the call system is working."
 
+## Caller Identity
+
+All implicit calls (calls without an explicit `caller_identity_mode`) always use the assistant's Twilio phone number. This is the number that appears on the recipient's caller ID.
+
+### User-number mode (per-call only)
+
+If the user wants a specific call to appear as coming from their own phone number, they must explicitly pass `caller_identity_mode: 'user_number'` on that call. The user's phone number must be either owned by or verified with the same Twilio account.
+
+**To configure a user phone number:**
+
+```
+credential_store action=store service=twilio field=user_phone_number value=+14155559999
+```
+
+**To use it for a specific call**, pass `caller_identity_mode: 'user_number'` when calling `call_start` — see the Making Calls section for examples. User-number mode cannot be set as a global default; it must be requested explicitly per call.
+
+### Configuration reference
+
+| Setting | Description | Default |
+|---|---|---|
+| `calls.callerIdentity.allowPerCallOverride` | Whether per-call mode selection is allowed | `true` |
+| `calls.callerIdentity.userNumber` | Optional E.164 phone number for user-number mode (alternative to storing via `credential_store`) | *(empty)* |
+
+## Optional: Higher Quality Voice with ElevenLabs
+
+ElevenLabs integration is entirely optional. The standard Twilio-only setup works unchanged — this section is only relevant if you want to improve voice quality.
+
+### Mode: `twilio_elevenlabs_tts`
+
+Uses ElevenLabs voices through Twilio's ConversationRelay. Speech is more natural-sounding than the default Google TTS voices.
+
+**Recommended user-friendly workflow (no technical IDs required):**
+
+1. Ask what kind of voice the user wants (examples: "warm", "professional", "playful", "calm", "deeper", "brighter")
+2. If the user doesn't care, keep `twilio_standard` (simplest path)
+3. If they want higher-quality voice, switch to `twilio_elevenlabs_tts` and choose a matching ElevenLabs voice on their behalf
+
+The user should not need to know what a `voiceId` is unless they explicitly want advanced/manual control.
+
+**Manual/advanced setup (optional):**
+
+```bash
+vellum config set calls.voice.mode twilio_elevenlabs_tts
+vellum config set calls.voice.elevenlabs.voiceId "<your-voice-id>"
+```
+
+By default, the system sends a **bare** `voiceId` to Twilio ConversationRelay (no model/tuning suffix). This is the safest default across voice IDs.
+
+If you want to force Twilio's extended voice spec, you can optionally set a model ID:
+
+```bash
+vellum config set calls.voice.elevenlabs.voiceModelId "flash_v2_5"
+```
+
+When `voiceModelId` is set, the emitted voice string becomes:
+`voiceId-model-speed_stability_similarity`.
+
+### Mode: `elevenlabs_agent` (experimental/restricted)
+
+Full ElevenLabs conversational agent mode. This requires an ElevenLabs account with an agent configured on their platform.
+
+**Restriction:** This mode is currently restricted because consultation bridging (`waiting_on_user`) is not yet supported. A runtime guard in `handleVoiceWebhook` blocks `elevenlabs_agent` before any ElevenLabs API calls are made.
+
+**Setup:**
+
+1. Store your ElevenLabs API key securely:
+
+```
+credential_store action=store service=elevenlabs field=api_key value=<your_api_key>
+```
+
+2. Set the voice mode and agent ID:
+
+```bash
+vellum config set calls.voice.mode elevenlabs_agent
+vellum config set calls.voice.elevenlabs.agentId "<your-agent-id>"
+```
+
+### Fallback behavior and `fallbackToStandardOnError`
+
+By default, `calls.voice.fallbackToStandardOnError` is `true`. This setting controls what happens when an ElevenLabs mode encounters errors or is restricted.
+
+#### Invalid configuration (e.g., missing voiceId or agentId)
+
+- **`true` (default):** The profile resolver silently falls back to `twilio_standard` mode and logs a warning. The call proceeds with standard Twilio TTS.
+- **`false`:** The voice webhook returns **HTTP 500** with the specific configuration error details (e.g., `"Voice quality configuration error: calls.voice.elevenlabs.voiceId is required..."`).
+
+#### `elevenlabs_agent` mode guard (consultation bridging unsupported)
+
+- **`true` (default):** The `elevenlabs_agent` mode is silently downgraded to standard ConversationRelay TwiML with a warning log. The call proceeds normally with standard Twilio TTS. No ElevenLabs API calls are made.
+- **`false`:** The voice webhook returns **HTTP 501** with the message: `"elevenlabs_agent mode is restricted: consultation bridging (waiting_on_user) is not yet supported."`. No ElevenLabs API calls are made.
+
+You can disable fallback if you want strict ElevenLabs-only behavior:
+
+```bash
+vellum config set calls.voice.fallbackToStandardOnError false
+```
+
+### Reverting to standard Twilio
+
+To go back to the default voice at any time:
+
+```bash
+vellum config set calls.voice.mode twilio_standard
+```
+
 ## Making Calls
 
 Use the `call_start` tool to place outbound calls. Every call requires:
@@ -162,6 +277,22 @@ call_start phone_number="+18005551234" task="Check if they have a specific produ
 call_start phone_number="+12125551234" task="Confirm the dentist appointment scheduled for next Tuesday at 2pm" context="The appointment is under the name Jane Doe, DOB 03/15/1990."
 ```
 
+### Caller identity in calls
+
+Implicit calls always use the assistant's Twilio number (`assistant_number`). Only specify `caller_identity_mode` when the user explicitly requests a different identity for a specific call.
+
+**Default call (assistant number):**
+```
+call_start phone_number="+14155551234" task="Check store hours for today"
+```
+
+**Call from the user's own number:**
+```
+call_start phone_number="+14155551234" task="Check store hours for today" caller_identity_mode="user_number"
+```
+
+**Decision rule:** Implicit calls (no explicit mode) always use the assistant's Twilio number. Only use `caller_identity_mode="user_number"` when the user explicitly requests it for a specific call.
+
 ### Phone number format
 
 Phone numbers MUST be in E.164 format: `+` followed by country code and number with no spaces, dashes, or parentheses.
@@ -199,24 +330,40 @@ By default, always show the live transcript of the call as it happens. When a ca
 
 4. Continue monitoring until the call completes or fails
 
-### Handling questions during a call
+### Interacting with a live call
+
+During an active call, the user can type messages in the chat thread to interact with the AI voice agent in real time. Messages are automatically routed to the call via the call bridge, which decides how to handle them based on the call's current state:
 
-The AI voice agent may encounter situations where it needs input from the user. When this happens:
+#### Mode 1: Answering questions
 
-1. The call status changes to `waiting_on_user`
-2. A **pending question** appears in `call_status` output
-3. Present the question prominently to the user:
+When the AI voice agent encounters something it needs user input for, a **pending question** appears in the chat. The call status changes to `waiting_on_user`.
+
+1. A **pending question** appears in `call_status` output
+2. Present the question prominently to the user:
 
 ```
 ❓ The person on the call asked something the assistant needs your help with:
    "They're asking if you'd prefer the smoking or non-smoking section?"
 ```
 
-4. The user can reply directly in the chat — their response is automatically routed to the live call via the call bridge
-5. The AI voice agent receives the answer and continues the conversation naturally
+3. The user replies directly in the chat — since there is a pending question, the reply is automatically routed as an **answer** to the AI voice agent
+4. The AI voice agent receives the answer and continues the conversation naturally
 
 **Important:** Respond to pending questions quickly. There is a consultation timeout (default: 2 minutes). If no answer is provided in time, the AI voice agent will move on.
 
+#### Mode 2: Steering with instructions
+
+When there is **no pending question** but the call is still active, any message the user types in the chat is treated as a **steering instruction**. This lets the user proactively guide the call in real time — for example:
+
+- "Ask them about their cancellation policy too"
+- "Wrap up the call, we have what we need"
+- "Switch to asking about weekend availability instead"
+- "Be more assertive about getting a discount"
+
+The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly. A confirmation message ("Instruction relayed to active call.") appears in the chat thread.
+
+**The user does not need to do anything special** — just type a message. The system automatically determines whether it should be an answer or an instruction based on whether a question is pending.
+
 ### Call status values
 
 - **initiated** — Call is being placed
@@ -282,6 +429,19 @@ All call-related settings can be managed via `vellum config`:
 | `calls.userConsultTimeoutSeconds` | How long to wait for user answers | `120` (2 min) |
 | `calls.disclosure.enabled` | Whether the AI announces itself at call start | `true` |
 | `calls.disclosure.text` | The disclosure message spoken at call start | `"I should let you know that I'm an AI assistant calling on behalf of my user."` |
+| `calls.model` | Override LLM model for call orchestration | *(uses default model)* |
+| `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection | `true` |
+| `calls.callerIdentity.userNumber` | E.164 phone number for user-number mode | *(empty)* |
+| `calls.voice.mode` | Voice quality mode (`twilio_standard`, `twilio_elevenlabs_tts`, `elevenlabs_agent`) | `twilio_standard` |
+| `calls.voice.language` | Language code for TTS and transcription | `en-US` |
+| `calls.voice.transcriptionProvider` | Speech-to-text provider (`Deepgram`, `Google`) | `Deepgram` |
+| `calls.voice.fallbackToStandardOnError` | Auto-fallback to standard Twilio TTS on ElevenLabs errors | `true` |
+| `calls.voice.elevenlabs.voiceId` | Advanced/internal ElevenLabs voice identifier. Usually set by the assistant based on requested voice style | *(empty)* |
+| `calls.voice.elevenlabs.voiceModelId` | Optional Twilio ConversationRelay model suffix. Leave empty to send bare `voiceId` | *(empty)* |
+| `calls.voice.elevenlabs.agentId` | ElevenLabs agent ID (for `elevenlabs_agent` mode) | *(empty)* |
+| `calls.voice.elevenlabs.speed` | Playback speed (`0.7` – `1.2`) | `1.0` |
+| `calls.voice.elevenlabs.stability` | Voice stability (`0.0` – `1.0`) | `0.5` |
+| `calls.voice.elevenlabs.similarityBoost` | Voice similarity boost (`0.0` – `1.0`) | `0.75` |
 
 ### Adjusting settings
 
@@ -320,6 +480,15 @@ Run the **public-ingress** skill to set up ngrok and configure `ingress.publicBa
 - The ConversationRelay WebSocket may not be connecting. Check that `ingress.publicBaseUrl` is correct and the tunnel is active
 - Verify the gateway is running on `http://127.0.0.1:${GATEWAY_PORT:-7830}`
 
+### "Number not eligible for caller identity"
+The user's phone number is not owned by or verified with the Twilio account. The number must be either purchased through Twilio or added as a verified caller ID at https://console.twilio.com/us1/develop/phone-numbers/manage/verified.
+
+### "Per-call caller identity override is disabled"
+The setting `calls.callerIdentity.allowPerCallOverride` is set to `false`, so per-call `caller_identity_mode` selection is not allowed. Re-enable overrides with `vellum config set calls.callerIdentity.allowPerCallOverride true`.
+
+### Caller identity call fails on trial account
+Twilio trial accounts can only place calls to verified numbers, regardless of caller identity mode. The user's phone number must also be verified with Twilio. Upgrade to a paid account or verify both the source and destination numbers.
+
 ### "This phone number is not allowed to be called"
 Emergency numbers (911, 112, 999, 000, 110, 119) are permanently blocked for safety.
 
@@ -332,3 +501,22 @@ Or re-run the public-ingress skill to auto-detect and save the new URL.
 
 ### Call drops after 30 seconds of silence
 The system has a 30-second silence timeout. If nobody speaks for 30 seconds, the agent will ask "Are you still there?" This is expected behavior.
+
+### Call quality didn't improve after enabling ElevenLabs
+- Verify `calls.voice.mode` is set to `twilio_elevenlabs_tts` or `elevenlabs_agent` (not still `twilio_standard`)
+- Ask for the desired voice style again and try a different voice selection
+- If configuring manually: check that `calls.voice.elevenlabs.voiceId` contains a valid ElevenLabs voice ID
+- If mode is `elevenlabs_agent`, ensure `calls.voice.elevenlabs.agentId` is also set
+
+### Twilio says "application error" right after answer
+- This often means ConversationRelay rejected voice configuration after TwiML fetch
+- Keep `calls.voice.elevenlabs.voiceModelId` empty first (bare `voiceId` mode)
+- If you set `voiceModelId`, try clearing it and retesting:
+  `vellum config set calls.voice.elevenlabs.voiceModelId ""`
+
+### ElevenLabs mode falls back to standard
+When `calls.voice.fallbackToStandardOnError` is `true` (the default), the system silently falls back to standard Twilio TTS if ElevenLabs encounters an error or restriction. Check:
+- For `elevenlabs_agent` mode: this mode is currently restricted (consultation bridging not yet supported) and will always fall back to standard when fallback is enabled. If fallback is disabled, the voice webhook returns HTTP 501.
+- For `twilio_elevenlabs_tts` mode: verify `calls.voice.elevenlabs.voiceId` is set to a valid voice ID
+- For invalid configs (missing voiceId/agentId): if fallback is disabled, the voice webhook returns HTTP 500 with the config error
+- Review daemon logs for warning messages about fallback or guard activation