@vellumai/assistant 0.4.56 → 0.5.0

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

@@ -13,22 +13,26 @@ metadata:
 
 You are a unified messaging assistant with access to multiple platforms (Slack, Gmail, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
 
+## External Identity
+
+When composing messages on behalf of your user to external recipients, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from USER.md. Don't volunteer that you are an AI unless directly asked.
+
 For Gmail management (archive, label, triage, declutter), load the **gmail** skill. For email sequences, load the **sequences** skill.
 
 ## Email Routing Priority
 
-When the user mentions "email" — sending, reading, checking, decluttering, drafting, or anything else — **always default to the user's own email (Gmail)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's AgentMail address.
+When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email (Gmail)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's AgentMail address.
 
-Do not offer AgentMail as an option or mention it unless the user specifically asks. If Gmail is not connected, guide them through Gmail setup — do not suggest AgentMail as an alternative.
+Do not offer AgentMail as an option or mention it unless the user specifically asks. If Gmail is not connected, guide them through Gmail setup - do not suggest AgentMail as an alternative.
 
 ## Communication Style
 
-- **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox — that's obviously what they want.
-- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" — not "the OAuth2 access token for integration:google has expired."
+- **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox - that's obviously what they want.
+- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" - not "the OAuth2 access token for integration:google has expired."
 - **Show progress.** When running a tool that scans many emails, tell the user what you're doing: "Scanning your inbox for clutter..." Don't go silent.
-- **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do — just do it and narrate lightly.
+- **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do - just do it and narrate lightly.
 
-When a platform is connected (auth test succeeds), always use the messaging API tools for that platform. Never fall back to browser automation, shell commands (bash, curl), or any other approach for operations that messaging tools can handle. The messaging tools handle authentication internally — never try to access tokens or call APIs directly. Browser automation is only appropriate for initial credential setup (OAuth consent screens), not for day-to-day messaging operations.
+When a platform is connected (auth test succeeds), always use the messaging API tools for that platform. Never fall back to browser automation, shell commands (bash, curl), or any other approach for operations that messaging tools can handle. The messaging tools handle authentication internally - never try to access tokens or call APIs directly. Browser automation is only appropriate for initial credential setup (OAuth consent screens), not for day-to-day messaging operations.
 
 ## Connection Setup
 
@@ -40,20 +44,20 @@ Telegram setup requires a publicly reachable URL for webhook delivery. The **pub
 
 ### Email Connection Flow
 
-When the user asks to "connect my email", "set up email", "manage my email", or similar — and has not named a specific provider:
+When the user asks to "connect my email", "set up email", "manage my email", or similar - and has not named a specific provider:
 
 1. **Discover what's connected.** Call `messaging_auth_test` for `gmail` (and any other email-capable platforms). If one succeeds, tell the user it's already connected and proceed with their request.
-2. **If nothing is connected**, ask which provider they use — but keep it brief and conversational (e.g., "Which email do you use — Gmail, Outlook, etc.?"), not a numbered list of options with descriptions.
+2. **If nothing is connected**, ask which provider they use - but keep it brief and conversational (e.g., "Which email do you use - Gmail, Outlook, etc.?"), not a numbered list of options with descriptions.
 3. **Once the provider is known, act immediately.** Don't present setup options or explain OAuth. If it's Gmail, follow the Gmail section below. For any other provider, let the user know that only Gmail is fully supported right now, and offer to set up Gmail instead.
 
 ### Gmail
 
-1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. The tool auto-fills Google's OAuth endpoints and looks up any previously stored client credentials — so this single call may be all that's needed.
+1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. The tool auto-fills Google's OAuth endpoints and looks up any previously stored client credentials - so this single call may be all that's needed.
 2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Load the **google-oauth-applescript** skill:
    - Call `skill_load` with `skill: "google-oauth-applescript"` to load the dependency skill.
    - Tell the user Gmail isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
      - **message:** "Ready to set up Gmail?"
-     - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials — creating a project, enabling APIs, and connecting your account. Takes about 5 minutes."
+     - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials - creating a project, enabling APIs, and connecting your account. Takes about 5 minutes."
      - **confirmLabel:** "Get Started"
      - **cancelLabel:** "Not Now"
    - If the user confirms, briefly acknowledge (e.g., "Setting up Gmail now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
@@ -66,7 +70,7 @@ Slack connects via Socket Mode using a bot token and app-level token (not OAuth)
 - Call `skill_load` with `skill: "slack-app-setup"` to load the dependency skill.
 - Tell the user Slack isn't connected yet and briefly explain what the setup involves, then follow the skill's guided flow.
 
-The slack-app-setup skill handles: manifest-driven app creation, app token and bot token collection via secure prompt (never accept tokens pasted in plaintext chat), token validation, workspace metadata storage, and optional guardian verification. Socket Mode connects automatically once both credentials are stored.
+The slack-app-setup skill handles: manifest-driven app creation, app token and bot token collection via secure prompt (never accept tokens pasted in plaintext chat), and Slack connection setup through the same settings handler used by the Settings UI. That handler validates the bot token, stores workspace metadata, and activates Socket Mode. The skill also covers optional guardian verification.
 
 ### Telegram
 
@@ -75,7 +79,7 @@ Telegram uses a bot token (not OAuth). Load the **telegram-setup** skill (which
 - Call `skill_load` with `skill: "telegram-setup"` to load the dependency skill.
 - 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 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.
+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.
 
 The telegram-setup skill also includes **guardian verification**, which links your Telegram account as the trusted guardian for the bot.
 
@@ -92,7 +96,7 @@ The guardian-verify-setup skill handles the full outbound verification flow for
 When a messaging tool fails with a token or authorization error:
 
 1. **Try to reconnect silently.** Call `credential_store` with `action: "oauth2_connect"` and the appropriate `service`. This often resolves expired tokens automatically.
-2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected — let me set that up") and immediately follow the connection setup flow for that platform (e.g., install and load **google-oauth-applescript** for Gmail). The user came to you to get something done, not to troubleshoot OAuth — make it seamless.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately follow the connection setup flow for that platform (e.g., install and load **google-oauth-applescript** for Gmail). The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
 3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the messaging tools can't do it, the reconnection flow is the answer.
 4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
 
@@ -100,8 +104,8 @@ When a messaging tool fails with a token or authorization error:
 
 - If the user specifies a platform (e.g., "check my Slack"), pass it as the `platform` parameter.
 - If only one platform is connected, it is auto-selected.
-- If multiple platforms are connected and the user doesn't specify, ask which platform they mean — or search across all of them.
-- **Be action-oriented with email.** When the user says "email" and wants to _do_ something (declutter, check, search, send), check what's connected first. If nothing is connected, ask which provider briefly and then go straight into setup — don't present menus, options lists, or explain the setup process. Just do it.
+- If multiple platforms are connected and the user doesn't specify, ask which platform they mean - or search across all of them.
+- **Be action-oriented with email.** When the user says "email" and wants to _do_ something (declutter, check, search, send), check what's connected first. If nothing is connected, ask which provider briefly and then go straight into setup - don't present menus, options lists, or explain the setup process. Just do it.
 
 ## Capabilities
 
@@ -111,21 +115,21 @@ When a messaging tool fails with a token or authorization error:
 - **List Conversations**: Show channels, inboxes, DMs with unread counts
 - **Read Messages**: Read message history from a conversation
 - **Search**: Search messages with platform-appropriate query syntax
-- **Send / Reply**: Send a message or reply in a thread (via `thread_id`). High risk — requires user approval.
+- **Send / Reply**: Send a message or reply in a thread (via `thread_id`). High risk - requires user approval.
 - **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)
+- **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
+- 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:**
 
@@ -136,10 +140,10 @@ Telegram is supported as a messaging provider with limited capabilities compared
 
 - **Add Reaction**: Add an emoji reaction to a message
 - **Leave Channel**: Leave a Slack channel
-- **Edit Message**: `slack_edit_message` — edit a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`) from the original send response. High risk — requires confidence score.
-- **Delete Message**: `slack_delete_message` — delete a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`). High risk — requires confidence score. This is irreversible.
+- **Edit Message**: `slack_edit_message` - edit a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`) from the original send response. High risk - requires confidence score.
+- **Delete Message**: `slack_delete_message` - delete a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`). High risk - requires confidence score. This is irreversible.
 
-When sending a Slack message, retain the `ts` (message timestamp) from the send response — it is needed to edit or delete that message later. Only messages sent by the assistant's bot can be edited or deleted.
+When sending a Slack message, retain the `ts` (message timestamp) from the send response - it is needed to edit or delete that message later. Only messages sent by the assistant's bot can be edited or deleted.
 
 ## Slack Search Syntax
 
@@ -183,7 +187,7 @@ Medium and high risk tools require a confidence score between 0 and 1:
 When a user asks to declutter, clean up, or organize their email:
 
 - **Gmail connected**: Load the **gmail** skill, which has the full decluttering workflow with `gmail_sender_digest`, `gmail_archive`, `gmail_unsubscribe`, and `gmail_filters`.
-- **Non-Gmail email connected**: Use the generic tools (`messaging_sender_digest`, `messaging_archive_by_sender`) — they work with any provider that supports these operations. Skip unsubscribe and filter offers since they are Gmail-specific.
+- **Non-Gmail email connected**: Use the generic tools (`messaging_sender_digest`, `messaging_archive_by_sender`) - they work with any provider that supports these operations. Skip unsubscribe and filter offers since they are Gmail-specific.
 - **Nothing connected**: Ask which email provider they use. If it's Gmail, go straight into the Gmail connection flow. For other providers, let the user know only Gmail is supported right now and offer to set up Gmail instead. Don't present a menu of options or explain what OAuth is.
 
 ### Non-Gmail Decluttering Workflow
@@ -191,7 +195,7 @@ When a user asks to declutter, clean up, or organize their email:
 1. **Scan**: Call `messaging_sender_digest`. Default query targets promotions from the last 90 days.
 2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
    - **Columns (exactly 2)**: Sender, Emails Found
-   - **Pre-select all rows** (`selected: true`) — users deselect what they want to keep
+   - **Pre-select all rows** (`selected: true`) - users deselect what they want to keep
    - **Caption**: Data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep."
    - **Action button (exactly 1)**: "Archive Selected" (primary). **NEVER offer Delete, Trash, or any destructive action.**
 3. **Wait for user action**: Stop and wait. Do NOT proceed until the user clicks the action button.

package/src/config/bundled-skills/messaging/TOOLS.json

@@ -17,7 +17,7 @@
             "type": "string",
             "description": "Email address of the account to use. Required when multiple accounts are connected for the same platform. If omitted, uses the most recently connected account."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -54,7 +54,7 @@
             "type": "number",
             "description": "Maximum number of conversations to return (default 200)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -91,7 +91,7 @@
             "type": "number",
             "description": "Maximum number of messages to return (default 50)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -125,7 +125,7 @@
             "type": "number",
             "description": "Maximum number of results to return (default 20)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -182,7 +182,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -216,7 +216,7 @@
             "type": "string",
             "description": "Specific message ID to mark as read (optional)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -250,7 +250,7 @@
             "type": "string",
             "description": "Optional search filter (e.g. 'to:alice@example.com' for Gmail, 'from:@me' for Slack)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -296,7 +296,7 @@
             "type": "string",
             "description": "Draft ID (for delete)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -336,9 +336,9 @@
           },
           "page_token": {
             "type": "string",
-            "description": "Resume token from a previous scan (rarely needed — scans now cover up to 5,000 messages in a single call)"
+            "description": "Resume token from a previous scan (rarely needed - scans now cover up to 5,000 messages in a single call)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -371,7 +371,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }

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

@@ -58,7 +58,7 @@ export async function run(
     // Gmail: create a draft instead of sending directly
     if (provider.id === "gmail") {
       const gmailConn = conn as OAuthConnection;
-      // Reply mode: thread_id provided — create a threaded draft with reply-all recipients
+      // Reply mode: thread_id provided - create a threaded draft with reply-all recipients
       if (threadId) {
         // Fetch thread messages to extract recipients and threading headers
         const list = await listMessages(gmailConn, `thread:${threadId}`, 10);

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

@@ -130,7 +130,7 @@ export async function resolveProvider(
  * for the given messaging provider.
  *
  * Non-OAuth providers (e.g. Telegram) use isConnected() and don't need
- * tokens — they receive an empty string which the string overload handles.
+ * tokens - they receive an empty string which the string overload handles.
  */
 export async function getProviderConnection(
   provider: MessagingProvider,

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

@@ -17,15 +17,15 @@ Use `send_notification` for user-facing alerts and notifications. This tool rout
 
 ## Deduplication (`dedupe_key`)
 
-- `dedupe_key` suppresses duplicate signals **permanently**. A second notification with the same key is **dropped entirely** for the lifetime of the assistant's event store. Once a key has been used, it cannot be reused — any future notification with the same key will be silently discarded.
+- `dedupe_key` suppresses duplicate signals **permanently**. A second notification with the same key is **dropped entirely** for the lifetime of the assistant's event store. Once a key has been used, it cannot be reused - any future notification with the same key will be silently discarded.
 - Never reuse a `dedupe_key` across logically distinct notifications, even if they are related. The key means "this exact event already fired," not "these events are in the same category."
 - If you omit `dedupe_key`, the LLM decision engine may generate one automatically based on signal context. This means even keyless signals can be deduplicated if the engine considers them duplicates of a recent event.
 
 ## Conversation Grouping
 
-Conversation grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to conversation X" parameter — conversation reuse is inferred, not commanded.
+Conversation grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to conversation X" parameter - conversation reuse is inferred, not commanded.
 
-**How it works:** The engine evaluates recent notification conversation candidates and decides whether a new signal is a continuation of an existing conversation based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies — the engine groups by semantic relatedness, not string matching.
+**How it works:** The engine evaluates recent notification conversation candidates and decides whether a new signal is a continuation of an existing conversation based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies - the engine groups by semantic relatedness, not string matching.
 
 **`source_event_name` is the primary grouping signal.** Use a stable event name for notifications that belong to the same logical stream (e.g. `dog.news.thread.reply` for all replies in a thread). Use a distinct event name when the notification represents a genuinely different kind of event.
 

package/src/config/bundled-skills/notifications/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "send_notification",
-      "description": "Send a notification through the unified notification router. The router decides channels/copy from preferences and urgency hints. Include a confidence score (0-1).",
+      "description": "Send an immediate notification. Fires instantly with no delay capability. For one-time future alerts, use schedule_create with fire_at. For recurring alerts, use schedule_create with expression (cron/RRULE). The router decides channels/copy from preferences and urgency hints. Include a confidence score (0-1).",
       "category": "notifications",
       "risk": "medium",
       "input_schema": {
@@ -66,7 +66,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }

package/src/config/bundled-skills/notifications/tools/send-notification.ts

@@ -110,14 +110,14 @@ export async function run(
     asNonEmptyString(input.source_event_name) ?? "user.send_notification";
   const requestedConversationId =
     asNonEmptyString(input.conversation_id) ?? context.conversationId;
-  const sourceSessionId = requestedConversationId ?? context.conversationId;
+  const sourceContextId = requestedConversationId ?? context.conversationId;
   const title = asNonEmptyString(input.title);
   const dedupeKey = asNonEmptyString(input.dedupe_key);
 
   const contextPayload: Record<string, unknown> = {
     requestedMessage: message,
     requestedByTool: "send_notification",
-    requestedBySessionId: context.conversationId,
+    requestedByContextId: context.conversationId,
   };
   if (title) contextPayload.requestedTitle = title;
   if (requestedConversationId)
@@ -130,7 +130,7 @@ export async function run(
     await emitNotificationSignal({
       sourceEventName,
       sourceChannel: "assistant_tool",
-      sourceSessionId,
+      sourceContextId,
       attentionHints: {
         requiresAction: parseBool(input.requires_action, true),
         urgency,

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

@@ -22,7 +22,7 @@ Use `swarm_delegate` when facing complex multi-part tasks that benefit from para
 
 ## When NOT to use
 
-- Simple single-step requests — just do them directly.
+- Simple single-step requests - just do them directly.
 - Tasks that are inherently sequential (each step depends on the previous result).
 - Requests where the user is asking for a quick answer, not a deep workflow.
 

package/src/config/bundled-skills/orchestration/TOOLS.json

@@ -21,7 +21,7 @@
             "type": "number",
             "description": "Maximum concurrent workers (1-6, default from config)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of what you are doing and why, shown to the user as a status update. Use simple language a non-technical person would understand."
           }

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

@@ -1,6 +1,6 @@
 ---
 name: phone-calls
-description: "Make outgoing phone calls, receive incoming calls, and pull up past call transcripts. Everything needed for your assistant to act as an AI receptionist."
+description: "Make outgoing phone calls, receive incoming calls, and pull up past call transcripts"
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "📞"
@@ -19,6 +19,10 @@ metadata:
 
 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.
 
+## External Identity
+
+When speaking on behalf of your user during calls, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from USER.md. Don't volunteer that you are an AI unless directly asked.
+
 # 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.
@@ -80,7 +84,7 @@ After they are verified, ask them what they think of your voice and offer to let
 Use the `call_start` tool to place outbound calls. Every call requires:
 
 - **phone_number**: The number to call in E.164 format (e.g. `+14155551234`)
-- **task**: What the call should accomplish — this becomes the AI voice agent's objective
+- **task**: What the call should accomplish - this becomes the AI voice agent's objective
 - **context** (optional): Additional background information for the conversation
 
 ### Example calls:
@@ -144,7 +148,7 @@ Once Twilio is configured and the assistant has a phone number, inbound calls wo
 
 1. The gateway resolves the assistant by phone number and forwards to the runtime
 2. A new voice session is created, keyed by the Twilio CallSid
-3. The LLM-driven orchestrator answers in receptionist mode — greeting the caller warmly and asking how it can help
+3. The LLM-driven orchestrator answers in receptionist mode - greeting the caller warmly and asking how it can help
 4. The conversation proceeds naturally, with ASK_GUARDIAN dispatches to consult the user when needed
 
 No additional configuration is needed beyond Twilio setup and `calls.enabled` being `true`. As long as the phone number has been provisioned/assigned, inbound calls are handled automatically.
@@ -185,7 +189,7 @@ The follow-up flow works across all guardian channels. The guardian can receive
 
 #### Steering with instructions
 
-When there is **no pending question** but the call is still active, the user can send steering instructions via the HTTP API (`POST /v1/calls/:id/instruction`) to proactively guide the call in real time — for example:
+When there is **no pending question** but the call is still active, the user can send steering instructions via the HTTP API (`POST /v1/calls/:id/instruction`) to 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"
@@ -198,13 +202,13 @@ The instruction is injected into the AI voice agent's conversation context as hi
 
 ### Call status values
 
-- **initiated** — Call is being placed
-- **ringing** — Phone is ringing on the other end
-- **in_progress** — Call is connected, conversation is active
-- **waiting_on_user** — AI agent needs input from the user (check pending question)
-- **completed** — Call ended successfully
-- **failed** — Call failed (check lastError for details)
-- **cancelled** — Call was manually cancelled
+- **initiated** - Call is being placed
+- **ringing** - Phone is ringing on the other end
+- **in_progress** - Call is connected, conversation is active
+- **waiting_on_user** - AI agent needs input from the user (check pending question)
+- **completed** - Call ended successfully
+- **failed** - Call failed (check lastError for details)
+- **cancelled** - Call was manually cancelled
 
 ### Ending a call early
 
@@ -218,6 +222,6 @@ call_end call_session_id="<session_id>" reason="User requested to end the call"
 
 For detailed information on the following topics, see the reference files:
 
-- **[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
+- **[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/TOOLS.json

@@ -26,7 +26,7 @@
             "enum": ["assistant_number", "user_number"],
             "description": "Which phone number to use as the caller ID. assistant_number uses the AI assistant's Twilio number; user_number uses the user's verified personal number."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -48,7 +48,7 @@
             "type": "string",
             "description": "Specific call session ID to check. If omitted, checks for an active call in the current conversation."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -74,7 +74,7 @@
             "type": "string",
             "description": "Reason for ending the call"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }

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

@@ -44,13 +44,13 @@ When crafting tasks for the AI voice agent, follow these guidelines for the best
 ## 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
+- **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:
+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)

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

@@ -21,8 +21,8 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 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
+- `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
 

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

@@ -52,7 +52,7 @@ 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.
+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
 

package/src/config/bundled-skills/playbooks/TOOLS.json

@@ -34,7 +34,7 @@
             "type": "number",
             "description": "Relative priority \u2014 higher numbers take precedence. Defaults to 0."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -60,7 +60,7 @@
             "type": "string",
             "description": "Filter by category (e.g. \"scheduling\", \"triage\"). Omit to show all."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -106,7 +106,7 @@
             "type": "number",
             "description": "Updated priority"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -128,7 +128,7 @@
             "type": "string",
             "description": "ID of the playbook to delete (from playbook_list results)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }