@vellumai/assistant 0.4.41 → 0.4.43

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

@@ -1,66 +1,27 @@
 ---
-name: "Phone Calls"
-description: "Set up Twilio for AI-powered voice calls — both outgoing calls on behalf of the user and incoming calls where the assistant answers as a receptionist"
-user-invocable: true
-metadata:
-  { "vellum": { "emoji": "📞", "requires": { "config": ["calls.enabled"] } } }
-includes: ["public-ingress"]
+name: phone-calls
+description: Set up Twilio for AI-powered voice calls — both outgoing calls on behalf of the user and incoming calls where the assistant answers as a receptionist
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"📞","vellum":{"display-name":"Phone Calls","user-invocable":true,"includes":["twilio-setup", "public-ingress","elevenlabs-voice"]}}
 ---
 
 You are helping the user set up and manage phone calls via Twilio. This skill covers enabling the calls feature, placing outbound calls, receiving inbound calls, and interacting with live calls. Twilio credential storage, phone number provisioning, and public ingress are handled by the **twilio-setup** skill.
 
-## Overview
+# Overview
 
 The calling system uses Twilio's ConversationRelay for both **outbound** and **inbound** voice calls with **ElevenLabs** providing the text-to-speech voice. After Twilio setup, the assistant configures ElevenLabs as the TTS provider and prompts the user to choose a voice from a curated list of supported options.
 
-### Outbound calls
+# Initial Setup
 
-When a call is placed:
+Follow the steps below to ensure everything is prepared to make and receive phone calls.
 
-1. The assistant initiates an outbound call via the Twilio REST API
-2. Twilio connects to the gateway's voice webhook, which returns TwiML
-3. Twilio opens a ConversationRelay WebSocket for real-time voice streaming
-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 full transcript is stored in the database for later retrieval
+## Step 1: Twilio Setup
 
-### Inbound calls
-
-When someone dials the assistant's Twilio phone number:
-
-1. Twilio sends a voice webhook to the gateway at `/webhooks/twilio/voice` (no `callSessionId` in the URL)
-2. The gateway resolves which assistant owns the dialed number via `resolveAssistantByPhoneNumber`, falling back to the standard routing chain (chat_id, user_id, default/reject). Unmapped numbers are rejected with TwiML `<Reject>`.
-3. The runtime creates a new session keyed by the Twilio CallSid (`createInboundVoiceSession`)
-4. Twilio opens a ConversationRelay WebSocket. The relay detects the call is inbound when `initiatedFromConversationId == null` and optionally gates the call behind **guardian voice verification** if a pending challenge exists.
-5. Once verified (or if no challenge is pending), the LLM orchestrator greets the caller in a receptionist style: "Hello, this is [user]'s assistant. How can I help you today?"
-6. The assistant converses naturally, using ASK_GUARDIAN to consult the user when needed, just like outbound calls.
-
-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: Verify Twilio Setup
-
-Check whether Twilio credentials, phone number, and public ingress are already configured:
-
-```bash
-assistant config get twilio.accountSid
-assistant credentials inspect twilio:auth_token --json  # check "hasSecret" field
-assistant config get twilio.phoneNumber
-```
-
-```bash
-assistant config get calls.enabled
-```
-
-If `twilio.accountSid` has a value, `hasSecret` is `true`, `twilio.phoneNumber` is set, and `calls.enabled` is `true`, skip to the **Making Outbound Calls** section.
-
-If Twilio is not yet configured, load the **twilio-setup** skill — it handles credential storage, phone number provisioning, and public ingress setup:
-
-- Call `skill_load` with `skill: "twilio-setup"` to load the dependency skill.
-
-Once twilio-setup completes, return here to enable calls.
+Load the `twilio-setup` skill to determine whether Twilio has been fully configured and set it up if not. This is a prerequisite to all subsequent steps.
 
 ## Step 2: Enable Calls
 
-Enable the calls feature:
+Once Twilio is confirmed to be fully configured, enable calls by updating the config:
 
 ```bash
 assistant config set calls.enabled true
@@ -74,220 +35,27 @@ assistant config get calls.enabled
 
 ## Step 3: Choose a Voice
 
-After enabling calls, let the user choose an ElevenLabs voice. Twilio has a native ElevenLabs integration — no separate ElevenLabs account or API key is needed.
-
-### Voice consistency with in-app TTS
-
-The shared config key `elevenlabs.voiceId` is the single source of truth for ElevenLabs voice identity. Both in-app TTS and phone calls read from it (defaulting to **Rachel** — `21m00Tcm4TlvDq8ikWAM`).
-
-Before presenting the voice list, check the current shared voice:
-
-```bash
-assistant config get elevenlabs.voiceId
-```
-
-**If a non-default voice is already set**, the user chose it during voice-setup or a previous session. Tell them:
-
-> "Your assistant currently uses [voice name] for both in-app chat and phone calls. I'll keep the same voice for calls. You can change it if you'd like."
-
-Skip the selection prompt unless the user wants to change.
-
-**If the default (Rachel) is set or no override exists**, present the curated voice list below and let them pick. When they choose, set the shared config so both in-app TTS and phone calls use it:
-
-### Voice selection
-
-Present the user with a list of supported ElevenLabs voices. These are pre-made voices with stable IDs that work with Twilio ConversationRelay out of the box.
-
-**Ask the user: "Which voice would you like your assistant to use on phone calls?"**
-
-Present these voices grouped by category:
-
-#### Female voices
-
-| Voice     | Style                      | Voice ID               |
-| --------- | -------------------------- | ---------------------- |
-| Rachel    | Calm, warm, conversational | `21m00Tcm4TlvDq8ikWAM` |
-| Sarah     | Soft, young, approachable  | `EXAVITQu4vr4xnSDxMaL` |
-| Charlotte | Warm, Swedish-accented     | `XB0fDUnXU5powFXDhCwa` |
-| Alice     | Confident, British         | `Xb7hH8MSUJpSbSDYk0k2` |
-| Matilda   | Warm, friendly, young      | `XrExE9yKIg1WjnnlVkGX` |
-| Lily      | Warm, British              | `pFZP5JQG7iQjIQuC4Bku` |
-
-#### Male voices
-
-| Voice   | Style                           | Voice ID               |
-| ------- | ------------------------------- | ---------------------- |
-| Antoni  | Warm, well-rounded              | `ErXwobaYiN019PkySvjV` |
-| Josh    | Deep, young, clear              | `TxGEqnHWrfWFTfGW9XjX` |
-| Arnold  | Crisp, narrative                | `VR6AewLTigWG4xSOukaG` |
-| Adam    | Deep, middle-aged, professional | `pNInz6obpgDQGcFmaJgB` |
-| Bill    | Trustworthy, American           | `pqHfZKP75CvOlQylNhV4` |
-| George  | Warm, British, distinguished    | `JBFqnCBsd6RMkjVDRZzb` |
-| Daniel  | Authoritative, British          | `onwK4e9ZLuTAKqWW03F9` |
-| Charlie | Casual, Australian              | `IKne3meq5aSn9XLyUdCD` |
-| Liam    | Young, articulate               | `TX3LPaxmHKxFdv7VOQHJ` |
-
-After the user picks a voice, use `voice_config_update` to set the shared voice ID. This writes to the config file (`elevenlabs.voiceId`) for phone calls **and** pushes to the macOS app via IPC (`ttsVoiceId`) for in-app TTS in one call:
-
-```
-voice_config_update setting="tts_voice_id" value="<selected-voice-id>"
-```
-
-**If the user wants a voice not on this list**, they can browse more voices at https://elevenlabs.io/voice-library and provide the voice ID manually.
+Voice selection and tuning are handled by the `elevenlabs-voice` skill. Follow the instructions there to pick a curated voice, optionally set up an ElevenLabs API key for advanced selection, or tune voice parameters.
 
 ## Step 4: Verify Setup (Test Call)
 
-Before making real calls, offer a quick verification:
-
-1. Confirm credentials are stored: `assistant config get twilio.accountSid` should return a value and `assistant credentials inspect twilio:auth_token --json` should show `hasSecret: true`
-2. Confirm phone number is assigned: `assistant config get twilio.phoneNumber` should return a number
-3. Confirm ingress is running: `ingress.publicBaseUrl` must be set and the tunnel active
-4. Confirm calls are enabled: `calls.enabled` must be `true`
-5. Confirm voice is configured: `elevenlabs.voiceId` should be set
-
-Suggest a test call to the user's own phone: **"Want to do a quick test call to your phone to make sure everything works? This is a good way to hear how your chosen voice sounds."**
+Before making real calls, offer a quick verification. Suggest a test call to the user's own phone: **"Want to do a quick test call to your phone to make sure everything works? This is a good way to make sure everything works and that you like the way I sound."**
 
 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."
 
 ## Step 5: Guardian Verification (Optional)
 
-Link the user's phone number as the trusted voice guardian so the assistant can verify inbound callers.
+By going through Guardian Verification, the user will be recognized any time they call the assistant and will be able to interact with the assistant with elevated privileges. You should encourage the user to go through the guardian verification process, but not force it.
 
-Load the guardian-verify-setup skill with `channel: "voice"`:
+Load the `guardian-verify-setup` skill with `channel: "phone"`. The skill handles the full verification flow (outbound call, code entry, confirmation).
 
-```
-skill_load skill=guardian-verify-setup
-```
-
-The skill handles the full verification flow (outbound call, code entry, confirmation). If the user declines, skip this step.
-
-To re-check guardian status later:
+If the user declines, skip this step. To re-check guardian status later:
 
 ```bash
-assistant integrations guardian status --channel voice --json
+assistant channel-verification-sessions status --channel phone --json
 ```
 
-## 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:**
-
-```bash
-assistant config set calls.callerIdentity.userNumber "+14155559999"
-```
-
-**To use it for a specific call**, pass `caller_identity_mode: 'user_number'` when calling `call_start` — see the Making Outbound 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 | _(empty)_ |
-
-## DTMF Callee Verification
-
-An optional verification step where the callee must enter a numeric code via their phone's keypad (DTMF tones) before the call proceeds. This ensures the intended person has answered the phone.
-
-### How it works
-
-1. When the call connects and DTMF verification is enabled, a random numeric code is generated (length configured by `calls.verification.codeLength`).
-2. The verification code is shared with the guardian in the initiating conversation so they know what code was issued.
-3. The AI voice agent speaks the code digit-by-digit to the callee and asks them to enter it on their keypad.
-4. The callee enters the code via DTMF (phone keypad tones).
-5. If the code matches, the call proceeds normally. If the code is incorrect, the agent may re-prompt or end the call depending on configuration.
-
-### Configuration
-
-| Setting                         | Description                               | Default |
-| ------------------------------- | ----------------------------------------- | ------- |
-| `calls.verification.enabled`    | Enable DTMF callee verification           | `false` |
-| `calls.verification.codeLength` | Number of digits in the verification code | `6`     |
-
-## Advanced Voice Configuration
-
-ElevenLabs is the TTS provider for all calls. This section covers advanced voice selection and tuning.
-
-### Changing the voice
-
-To switch to a different voice after initial setup, use `voice_config_update` to set the shared voice ID. This writes to the config file (`elevenlabs.voiceId`) for phone calls **and** pushes to the macOS app via IPC for in-app TTS:
-
-```
-voice_config_update setting="tts_voice_id" value="<new-voice-id>"
-```
-
-Browse more voices at https://elevenlabs.io/voice-library.
-
-### Advanced voice selection with an ElevenLabs account
-
-Users who have an ElevenLabs account and API key (e.g., from the **voice-setup** skill) can go beyond the curated voice list. With an API key, they can:
-
-- **Browse the full ElevenLabs voice library programmatically** — the ElevenLabs API (`GET https://api.elevenlabs.io/v2/voices`) supports searching by name, category, language, and accent. This returns voice IDs, names, labels, and preview URLs.
-- **Use custom or cloned voices** — if the user has created a custom voice or voice clone in their ElevenLabs account, they can use its voice ID here. These voices are available in Twilio ConversationRelay just like pre-made voices.
-- **Preview voices before choosing** — each voice in the API response includes a `preview_url` with an audio sample.
-
-To check if the user has an API key stored:
-
-```bash
-assistant credentials inspect elevenlabs:api_key --json
-```
-
-If they have a key and want to browse voices, fetch the voice list:
-
-```bash
-curl -s "https://api.elevenlabs.io/v2/voices?category=premade&page_size=50" \
-  -H "xi-api-key: $(assistant credentials reveal elevenlabs:api_key)" | python3 -m json.tool
-```
-
-To search for a specific voice style:
-
-```bash
-curl -s "https://api.elevenlabs.io/v2/voices?search=warm+female&page_size=10" \
-  -H "xi-api-key: $(assistant credentials reveal elevenlabs:api_key)" | python3 -m json.tool
-```
-
-After the user picks a voice, set the shared voice ID:
-
-```
-voice_config_update setting="tts_voice_id" value="<selected-voice-id>"
-```
-
-### Voice tuning parameters
-
-Fine-tune how the selected voice sounds. These parameters apply to all ElevenLabs modes:
-
-```bash
-# Playback speed (0.7 = slower, 1.0 = normal, 1.2 = faster)
-assistant config set elevenlabs.speed 1.0
-
-# Stability (0.0 = more expressive/variable, 1.0 = more consistent/monotone)
-assistant config set elevenlabs.stability 0.5
-
-# Similarity boost (0.0 = more creative, 1.0 = closer to original voice)
-assistant config set elevenlabs.similarityBoost 0.75
-```
-
-Lower stability makes the voice more expressive but less predictable — good for conversational calls. Higher stability is better for scripted/formal calls.
-
-### Voice model tuning
-
-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
-assistant config set elevenlabs.voiceModelId "flash_v2_5"
-```
-
-When `voiceModelId` is set, the emitted voice string becomes:
-`voiceId-model-speed_stability_similarity`.
-
-## Making Outbound Calls
+# Making Outbound Calls
 
 Use the `call_start` tool to place outbound calls. Every call requires:
 
@@ -350,7 +118,7 @@ On Twilio trial accounts, outbound calls can ONLY be made to **verified numbers*
 1. Tell the user they need to verify the number at https://console.twilio.com/us1/develop/phone-numbers/manage/verified
 2. Or upgrade to a paid Twilio account to call any number
 
-## Receiving Inbound Calls
+# Receiving Inbound Calls
 
 Once Twilio is configured and the assistant has a phone number, inbound calls work automatically. When someone dials the assistant's number:
 
@@ -365,7 +133,7 @@ No additional configuration is needed beyond Twilio setup and `calls.enabled` be
 
 To set up guardian verification, load the skill: `skill_load skill=guardian-verify-setup`. Once a guardian binding exists, inbound callers may be prompted for verification before calls proceed.
 
-## Interacting with a Live Call
+# Interacting with a Live Call
 
 During an active call, the user can interact with the AI voice agent via the HTTP API endpoints. After placing a call with `call_start`, use `call_status` to poll the call state.
 
@@ -426,212 +194,10 @@ Use `call_end` with the call session ID to terminate an active call:
 call_end call_session_id="<session_id>" reason="User requested to end the call"
 ```
 
-## Retrieving Past Call Transcripts
-
-After a call ends, the full bidirectional transcript (caller speech, assistant responses, tool calls, and tool results) is stored in the SQLite database. The daemon logs (`vellum.log`) only contain caller-side transcripts and lifecycle events at the default log level, so they are **not sufficient** for full transcript reconstruction.
-
-### Finding the conversation
-
-1. **Get the call session ID and voice conversation ID** from `vellum.log` by searching for recent session creation entries:
-
-```bash
-grep "voiceConversationId" ~/.vellum/workspace/data/logs/vellum.log | tail -5
-```
-
-The `voiceConversationId` field in the `Created new inbound voice session` (or outbound equivalent) log line is the key you need.
-
-2. **Query the messages table** in the SQLite database using the voice conversation ID:
-
-```bash
-sqlite3 ~/.vellum/workspace/data/db/assistant.db \
-  "SELECT role, content FROM messages WHERE conversation_id = '<voiceConversationId>' ORDER BY created_at ASC;"
-```
-
-This returns all messages in chronological order with:
-
-- `role: "user"` — caller speech (prefixed with `[SPEAKER]` tags) and system events
-- `role: "assistant"` — assistant responses, including `text` content and any `tool_use`/`tool_result` blocks
-
-### Quick one-liner for the most recent call
-
-```bash
-CONV_ID=$(grep "voiceConversationId" ~/.vellum/workspace/data/logs/vellum.log | tail -1 | python3 -c "import sys,json; print(json.loads(sys.stdin.readline().strip())['voiceConversationId'])")
-
-sqlite3 ~/.vellum/workspace/data/db/assistant.db \
-  "SELECT role, content FROM messages WHERE conversation_id = '$CONV_ID' ORDER BY created_at ASC;"
-```
-
-### Additional tables for call metadata
-
-| Table                     | What it contains                                               |
-| ------------------------- | -------------------------------------------------------------- |
-| `call_sessions`           | Session metadata (start time, duration, phone numbers, status) |
-| `call_events`             | Granular event log for the call lifecycle                      |
-| `notification_decisions`  | Whether notifications were evaluated during the call           |
-| `notification_deliveries` | Notification delivery attempts                                 |
-
-### Key paths
-
-| Resource                                      | Path                                       |
-| --------------------------------------------- | ------------------------------------------ |
-| Assistant logs (caller-side transcripts only) | `~/.vellum/workspace/data/logs/vellum.log` |
-| Full conversation database                    | `~/.vellum/workspace/data/db/assistant.db` |
-| Messages table                                | `messages` (keyed by `conversation_id`)    |
-| Call sessions table                           | `call_sessions`                            |
-| Call events table                             | `call_events`                              |
-
-### Important
-
-`vellum.log` at the default log level does **not** contain assistant responses, TTS text, or LLM completions for voice calls. Always use the `messages` table in `assistant.db` as the source of truth for complete call transcripts.
-
-## Call Quality Tips
-
-When crafting tasks for the AI voice agent, follow these guidelines for the best call experience:
-
-### Writing good task descriptions
-
-- **Be specific about the objective**: "Make a dinner reservation for 2 at 7pm tonight" is better than "Call the restaurant"
-- **Include relevant context**: Names, account numbers, appointment details — anything the agent might need
-- **Specify what information to collect**: "Ask about their return policy and store hours" tells the agent what to gather
-- **Set clear completion criteria**: The agent knows to end the call when the task is fulfilled
-
-### Providing context
-
-The `context` field is powerful — use it to give the agent background that helps it sound natural:
-
-- User's name and identifying details (for making appointments, verifying accounts)
-- Preferences and constraints (dietary restrictions, budget limits, scheduling conflicts)
-- Previous interaction history ("I called last week and spoke with Sarah about...")
-- Special instructions ("If they put you on hold for more than 5 minutes, hang up and we'll try again later")
-
-### Things the AI voice agent handles well
-
-**Outbound calls:**
-
-- Making reservations and appointments
-- Checking business hours, availability, or pricing
-- Confirming or rescheduling existing appointments
-- Gathering information (store policies, product availability)
-- Simple customer service interactions
-- Leaving voicemails (it will speak the message if voicemail picks up)
-
-**Inbound calls:**
-
-- Answering as a receptionist and routing caller requests to the user via ASK_GUARDIAN
-- Taking messages when the user is unavailable
-- Answering questions the assistant already knows from memory/context
-- Screening calls with guardian voice verification
-
-### Things to be aware of
-
-- Calls have a maximum duration (configurable via `calls.maxDurationSeconds`, default: 1 hour)
-- The agent gives a 2-minute warning before the time limit
-- Emergency numbers (911, 112, 999, etc.) are blocked and cannot be called
-- The AI disclosure setting (`calls.disclosure.enabled`) controls whether the agent announces it's an AI at the start of the call
-
-## Configuration Reference
-
-All call-related settings can be managed via `assistant config`:
-
-| Setting                                     | Description                                                                                                                   | Default                                                                                                  |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `calls.enabled`                             | Master switch for the calling feature                                                                                         | `false`                                                                                                  |
-| `calls.provider`                            | Voice provider (currently only `twilio`)                                                                                      | `twilio`                                                                                                 |
-| `calls.maxDurationSeconds`                  | Maximum call length in seconds                                                                                                | `3600` (1 hour)                                                                                          |
-| `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                                                                                   | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
-| `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.language`                      | Language code for TTS and transcription                                                                                       | `en-US`                                                                                                  |
-| `calls.voice.transcriptionProvider`         | Speech-to-text provider (`Deepgram`, `Google`)                                                                                | `Deepgram`                                                                                               |
-| `elevenlabs.voiceId`                        | ElevenLabs voice ID used by both in-app TTS and phone calls. Set during setup from the curated voice list. Defaults to Rachel | `21m00Tcm4TlvDq8ikWAM`                                                                                   |
-| `elevenlabs.voiceModelId`                   | Optional Twilio ConversationRelay model suffix. Leave empty to send bare `voiceId`                                            | _(empty)_                                                                                                |
-| `elevenlabs.speed`                          | Playback speed (`0.7` – `1.2`)                                                                                                | `1.0`                                                                                                    |
-| `elevenlabs.stability`                      | Voice stability (`0.0` – `1.0`)                                                                                               | `0.5`                                                                                                    |
-| `elevenlabs.similarityBoost`                | Voice similarity boost (`0.0` – `1.0`)                                                                                        | `0.75`                                                                                                   |
-
-### Adjusting settings
-
-```bash
-# Increase max call duration to 2 hours
-assistant config set calls.maxDurationSeconds 7200
-
-# Disable AI disclosure (check local regulations first)
-assistant config set calls.disclosure.enabled false
-
-# Custom disclosure message
-assistant config set calls.disclosure.text "Just so you know, this is an assistant calling on behalf of my human."
-
-# Give more time for user consultation
-assistant config set calls.userConsultTimeoutSeconds 300
-```
-
-## Troubleshooting
-
-### "Twilio credentials not configured"
-
-Load the `twilio-setup` skill to store your Account SID and Auth Token.
-
-### "Calls feature is disabled"
-
-Run `assistant config set calls.enabled true`.
-
-### "No public base URL configured"
-
-Run the **public-ingress** skill to set up ngrok and configure `ingress.publicBaseUrl`.
-
-### Call fails immediately after initiating
-
-- Check that the phone number is in E.164 format
-- Verify Twilio credentials are correct (wrong auth token causes API errors)
-- On trial accounts, ensure the destination number is verified
-- Check that the ngrok tunnel is still running (`curl -s http://127.0.0.1:4040/api/tunnels`)
-
-### Call connects but no audio / one-way audio
-
-- The ConversationRelay WebSocket may not be connecting. Check that `ingress.publicBaseUrl` is correct and the tunnel is active
-- Verify the assistant runtime is running
-
-### "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 `assistant 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.
-
-### ngrok tunnel URL changed
-
-If you restarted ngrok, the public URL has changed. Update it:
-
-```bash
-assistant config set ingress.publicBaseUrl "<new-url>"
-```
-
-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 during normal conversation, the agent will ask "Are you still there?" This is expected behavior. During guardian wait states (inbound access-request wait or in-call guardian consultation wait), this generic silence nudge is suppressed — the guardian-wait heartbeat messaging is used instead.
-
-### Call quality sounds off
-
-- Verify `elevenlabs.voiceId` is set to a valid ElevenLabs voice ID
-- Ask for the desired voice style again and try a different voice selection
+# Reference
 
-### Twilio says "application error" right after answer
+For detailed information on the following topics, see the reference files:
 
-- This often means ConversationRelay rejected voice configuration after TwiML fetch
-- Keep `elevenlabs.voiceModelId` empty first (bare `voiceId` mode)
-- If you set `voiceModelId`, try clearing it and retesting:
-  `assistant config set elevenlabs.voiceModelId ""`
+- **[Retrieving Past Call Transcripts](references/TRANSCRIPTS.md)** — How to find and query full bidirectional call transcripts from the database
+- **[Configuration Reference & Call Quality Tips](references/CONFIG.md)** — All call-related config settings, defaults, and tips for writing effective call tasks
+- **[Troubleshooting](references/TROUBLESHOOTING.md)** — Common error messages, connectivity issues, and debugging steps

package/src/config/bundled-skills/phone-calls/references/CONFIG.md

@@ -0,0 +1,83 @@
+# Configuration Reference
+
+All call-related settings can be managed via `assistant config`:
+
+| Setting                                     | Description                                                                                                                   | Default                                                                                                  |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `calls.enabled`                             | Master switch for the calling feature                                                                                         | `false`                                                                                                  |
+| `calls.provider`                            | Voice provider (currently only `twilio`)                                                                                      | `twilio`                                                                                                 |
+| `calls.maxDurationSeconds`                  | Maximum call length in seconds                                                                                                | `3600` (1 hour)                                                                                          |
+| `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                                                                                   | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
+| `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.language`                      | Language code for TTS and transcription                                                                                       | `en-US`                                                                                                  |
+| `calls.voice.transcriptionProvider`         | Speech-to-text provider (`Deepgram`, `Google`)                                                                                | `Deepgram`                                                                                               |
+| `elevenlabs.voiceId`                        | ElevenLabs voice ID used by both in-app TTS and phone calls. Set during setup from the curated voice list. Defaults to Rachel | `21m00Tcm4TlvDq8ikWAM`                                                                                   |
+| `elevenlabs.voiceModelId`                   | Optional Twilio ConversationRelay model suffix. Leave empty to send bare `voiceId`                                            | _(empty)_                                                                                                |
+| `elevenlabs.speed`                          | Playback speed (`0.7` – `1.2`)                                                                                                | `1.0`                                                                                                    |
+| `elevenlabs.stability`                      | Voice stability (`0.0` – `1.0`)                                                                                               | `0.5`                                                                                                    |
+| `elevenlabs.similarityBoost`                | Voice similarity boost (`0.0` – `1.0`)                                                                                        | `0.75`                                                                                                   |
+
+## Adjusting settings
+
+```bash
+# Increase max call duration to 2 hours
+assistant config set calls.maxDurationSeconds 7200
+
+# Disable AI disclosure (check local regulations first)
+assistant config set calls.disclosure.enabled false
+
+# Custom disclosure message
+assistant config set calls.disclosure.text "Just so you know, this is an assistant calling on behalf of my human."
+
+# Give more time for user consultation
+assistant config set calls.userConsultTimeoutSeconds 300
+```
+
+# Call Quality Tips
+
+When crafting tasks for the AI voice agent, follow these guidelines for the best call experience:
+
+## Writing good task descriptions
+
+- **Be specific about the objective**: "Make a dinner reservation for 2 at 7pm tonight" is better than "Call the restaurant"
+- **Include relevant context**: Names, account numbers, appointment details — anything the agent might need
+- **Specify what information to collect**: "Ask about their return policy and store hours" tells the agent what to gather
+- **Set clear completion criteria**: The agent knows to end the call when the task is fulfilled
+
+## Providing context
+
+The `context` field is powerful — use it to give the agent background that helps it sound natural:
+
+- User's name and identifying details (for making appointments, verifying accounts)
+- Preferences and constraints (dietary restrictions, budget limits, scheduling conflicts)
+- Previous interaction history ("I called last week and spoke with Sarah about...")
+- Special instructions ("If they put you on hold for more than 5 minutes, hang up and we'll try again later")
+
+## Things the AI voice agent handles well
+
+**Outbound calls:**
+
+- Making reservations and appointments
+- Checking business hours, availability, or pricing
+- Confirming or rescheduling existing appointments
+- Gathering information (store policies, product availability)
+- Simple customer service interactions
+- Leaving voicemails (it will speak the message if voicemail picks up)
+
+**Inbound calls:**
+
+- Answering as a receptionist and routing caller requests to the user via ASK_GUARDIAN
+- Taking messages when the user is unavailable
+- Answering questions the assistant already knows from memory/context
+- Screening calls with guardian voice verification
+
+## Things to be aware of
+
+- Calls have a maximum duration (configurable via `calls.maxDurationSeconds`, default: 1 hour)
+- The agent gives a 2-minute warning before the time limit
+- Emergency numbers (911, 112, 999, etc.) are blocked and cannot be called
+- The AI disclosure setting (`calls.disclosure.enabled`) controls whether the agent announces it's an AI at the start of the call