@vellumai/assistant 0.3.4 → 0.3.5

package/src/config/bundled-skills/media-processing/tools/submit-feedback.ts

@@ -0,0 +1,150 @@
+/**
+ * Tool for submitting feedback on media events.
+ *
+ * Supports four feedback types:
+ *   - correct: confirms the event is accurate
+ *   - incorrect: marks a false positive
+ *   - boundary_edit: adjusts start/end times
+ *   - missed: reports an event the system failed to detect (creates a new event)
+ *
+ * All interfaces are generic — works for any event type.
+ */
+
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { submitFeedback, type FeedbackType } from '../services/feedback-store.js';
+import { getEventById, insertEvent, getMediaAssetById } from '../../../../memory/media-store.js';
+
+const VALID_FEEDBACK_TYPES = ['correct', 'incorrect', 'boundary_edit', 'missed'];
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const feedbackType = input.feedback_type as string | undefined;
+  if (!feedbackType || !VALID_FEEDBACK_TYPES.includes(feedbackType)) {
+    return {
+      content: `feedback_type is required and must be one of: ${VALID_FEEDBACK_TYPES.join(', ')}`,
+      isError: true,
+    };
+  }
+
+  // For 'missed' type, we need asset_id and event details to create the missing event
+  if (feedbackType === 'missed') {
+    return handleMissedEvent(input, feedbackType as FeedbackType);
+  }
+
+  // For all other types, event_id is required
+  const eventId = input.event_id as string | undefined;
+  if (!eventId) {
+    return { content: 'event_id is required for feedback types other than "missed".', isError: true };
+  }
+
+  const event = getEventById(eventId);
+  if (!event) {
+    return { content: `Event "${eventId}" not found.`, isError: true };
+  }
+
+  const correctedStartTime = input.corrected_start_time as number | undefined;
+  const correctedEndTime = input.corrected_end_time as number | undefined;
+  const notes = input.notes as string | undefined;
+
+  // For boundary_edit, at least one corrected time should be provided
+  if (feedbackType === 'boundary_edit' && correctedStartTime === undefined && correctedEndTime === undefined) {
+    return {
+      content: 'For boundary_edit feedback, at least one of corrected_start_time or corrected_end_time is required.',
+      isError: true,
+    };
+  }
+
+  const feedback = submitFeedback({
+    assetId: event.assetId,
+    eventId: event.id,
+    feedbackType: feedbackType as FeedbackType,
+    originalStartTime: event.startTime,
+    originalEndTime: event.endTime,
+    correctedStartTime: correctedStartTime ?? undefined,
+    correctedEndTime: correctedEndTime ?? undefined,
+    notes: notes ?? undefined,
+  });
+
+  return {
+    content: JSON.stringify({
+      message: `Feedback submitted: ${feedbackType} for event ${eventId}`,
+      feedbackId: feedback.id,
+      eventId: event.id,
+      assetId: event.assetId,
+      feedbackType: feedback.feedbackType,
+      ...(correctedStartTime !== undefined ? { correctedStartTime } : {}),
+      ...(correctedEndTime !== undefined ? { correctedEndTime } : {}),
+    }, null, 2),
+    isError: false,
+  };
+}
+
+function handleMissedEvent(
+  input: Record<string, unknown>,
+  feedbackType: FeedbackType,
+): ToolExecutionResult {
+  const assetId = input.asset_id as string | undefined;
+  if (!assetId) {
+    return { content: 'asset_id is required for "missed" feedback type.', isError: true };
+  }
+
+  const asset = getMediaAssetById(assetId);
+  if (!asset) {
+    return { content: `Asset "${assetId}" not found.`, isError: true };
+  }
+
+  const eventType = input.event_type as string | undefined;
+  if (!eventType) {
+    return { content: 'event_type is required for "missed" feedback type.', isError: true };
+  }
+
+  const startTime = input.start_time as number | undefined;
+  const endTime = input.end_time as number | undefined;
+  if (startTime === undefined || endTime === undefined) {
+    return { content: 'start_time and end_time are required for "missed" feedback type.', isError: true };
+  }
+
+  if (endTime <= startTime) {
+    return { content: 'end_time must be greater than start_time.', isError: true };
+  }
+
+  const notes = input.notes as string | undefined;
+
+  // Create the missing event with low confidence (user-reported)
+  const newEvent = insertEvent({
+    assetId,
+    eventType,
+    startTime,
+    endTime,
+    confidence: 0.5,
+    reasons: ['user_reported_missed_event'],
+    metadata: { source: 'user_feedback', notes: notes ?? null },
+  });
+
+  // Store the feedback referencing the newly created event
+  const feedback = submitFeedback({
+    assetId,
+    eventId: newEvent.id,
+    feedbackType,
+    originalStartTime: undefined,
+    originalEndTime: undefined,
+    correctedStartTime: startTime,
+    correctedEndTime: endTime,
+    notes: notes ?? undefined,
+  });
+
+  return {
+    content: JSON.stringify({
+      message: `Missed event reported and created: ${eventType} at ${startTime}s-${endTime}s`,
+      feedbackId: feedback.id,
+      newEventId: newEvent.id,
+      assetId,
+      eventType,
+      startTime,
+      endTime,
+    }, null, 2),
+    isError: false,
+  };
+}

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

@@ -42,14 +42,14 @@ The telegram-setup skill handles: verifying the bot token from @BotFather, gener
 The telegram-setup skill also includes **guardian verification**, which links your Telegram account as the trusted guardian for the bot.
 
 ### SMS (Twilio)
-SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **twilio-setup** skill to configure Twilio:
-   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "twilio-setup"`.
-   - Then call `skill_load` with `skill: "twilio-setup"`.
-   - Tell the user: *"I've loaded a setup guide for Twilio. It will walk you through configuring your Twilio account for SMS and voice calls."*
+SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **sms-setup** skill for complete SMS configuration including compliance and testing:
+   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "sms-setup"`.
+   - Then call `skill_load` with `skill: "sms-setup"`.
+   - Tell the user: *"I've loaded the SMS setup guide. It will walk you through configuring Twilio, handling compliance requirements, and testing SMS delivery."*
 
-The twilio-setup skill handles: credential storage (Account SID + Auth Token), phone number provisioning or assignment, and public ingress setup. Once Twilio is configured, SMS is available automatically — no additional feature flag is needed. The assistant's Twilio phone number is used for both outbound SMS and voice calls.
+The sms-setup skill handles: Twilio credential storage (Account SID + Auth Token), phone number provisioning or assignment, public ingress setup, SMS compliance verification, and end-to-end test sending. Once SMS is set up, messaging is available automatically — no additional feature flag is needed.
 
-The twilio-setup skill also includes optional **guardian verification** for SMS, which links your phone number as the trusted guardian. This is the same guardian concept used by Telegram — it ensures only verified users can approve sensitive operations via SMS.
+The sms-setup skill also includes optional **guardian verification** for SMS (inherited from twilio-setup), which links your phone number as the trusted guardian.
 
 ## Platform Selection
 
@@ -83,6 +83,21 @@ Telegram is supported as a messaging provider with limited capabilities compared
 - 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.
 
+### SMS (Twilio)
+SMS is supported as a messaging provider with limited capabilities. The conversation ID is the recipient's phone number in E.164 format (e.g. `+14155551234`):
+
+- **Send**: Send an SMS to a phone number (high risk — requires user approval)
+- **Auth Test**: Verify Twilio credentials and show the configured phone number
+
+**Not available** (SMS limitations):
+- List conversations — SMS is stateless; there is no API to enumerate past conversations
+- Read message history — message history is not available through the gateway
+- Search messages — no search API is available for SMS
+
+**SMS limits:**
+- Outbound SMS uses the assistant's configured Twilio phone number as the sender. The phone number must be provisioned and assigned via the twilio-setup skill.
+- SMS messages are subject to Twilio's character limits and carrier filtering. Long messages may be split into multiple segments.
+
 ### 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-send.ts

@@ -1,7 +1,7 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
 import { resolveProvider, withProviderToken, ok, err } from './shared.js';
 
-export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
   const platform = input.platform as string | undefined;
   const conversationId = input.conversation_id as string;
   const text = input.text as string;
@@ -21,8 +21,12 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
       const result = await provider.sendMessage(token, conversationId, text, {
         subject,
         inReplyTo,
+        assistantId: context.assistantId,
       });
 
+      if (provider.id === 'sms') {
+        return ok(`SMS accepted by Twilio (ID: ${result.id}). Note: "accepted" means Twilio received it for delivery — it has not yet been confirmed as delivered to the handset.`);
+      }
       return ok(`Message sent (ID: ${result.id}).`);
     });
   } catch (e) {

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

@@ -439,7 +439,7 @@ All call-related settings can be managed via `vellum config`:
 | `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 | `"I should let you know that I'm an AI assistant calling on behalf of my user."` |
+| `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)* |
@@ -464,7 +464,7 @@ vellum config set calls.maxDurationSeconds 7200
 vellum config set calls.disclosure.enabled false
 
 # Custom disclosure message
-vellum config set calls.disclosure.text "Just so you know, this is an AI assistant calling for my user."
+vellum 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
 vellum config set calls.userConsultTimeoutSeconds 300

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

@@ -17,7 +17,7 @@ OAuth uses the official X API v2. It is the most reliable connection method and
 
 - Supports: **post** and **reply**
 - Read-only operations (timeline, search, home, bookmarks, notifications, likes, followers, following, media) always use the browser path directly, regardless of the strategy setting.
-- Setup: The user connects OAuth credentials through the Settings UI or the `twitter_auth_start` IPC flow.
+- Setup: Collect the OAuth Client ID (and optional Client Secret) from the user in chat using `credential_store` with `action: "prompt"`, then initiate the `twitter_auth_start` IPC flow. See the **First-Use Decision Flow** for the full sequence.
 - Set the strategy: `vellum x strategy set oauth`
 
 ### Browser session (no developer credentials needed)
@@ -45,15 +45,31 @@ When the user triggers a Twitter operation and no strategy has been configured y
    Look at `oauthConnected`, `browserSessionActive`, `preferredStrategy`, and `strategyConfigured` in the response. If `strategyConfigured` is `false`, the user has not yet chosen a strategy and should be guided through setup.
 
 2. **Present both options with trade-offs:**
-   - **OAuth**: Most reliable and official. Requires X developer app credentials (OAuth Client ID and optional Client Secret). Supports posting and replying. Set up through Settings UI.
+   - **OAuth**: Most reliable and official. Requires X developer app credentials (OAuth Client ID and optional Client Secret). Supports posting and replying. Set up right here in the chat.
    - **Browser session**: Quick to start, no developer credentials needed. Supports all operations including reading timelines and searching. Set up with `vellum x refresh`.
 
 3. **Ask the user which they prefer.** Do not choose for them.
 
 4. **Execute setup for the chosen path:**
-   - If OAuth: Guide the user to the Settings UI to connect their X developer credentials, or initiate the `twitter_auth_start` IPC flow.
+   - If OAuth: Collect the credentials in-chat using the secure credential prompt, then connect. Follow the **OAuth Setup Sequence** below.
    - If browser: Run `vellum x refresh` to capture session cookies from Chrome.
 
+### OAuth Setup Sequence
+
+When the user chooses OAuth, collect their X developer credentials conversationally using the secure UI:
+
+1. **Collect the Client ID securely:**
+   Call `credential_store` with `action: "prompt"`, `service: "integration:twitter"`, `field: "oauth_client_id"`, `label: "X (Twitter) OAuth Client ID"`, `description: "Enter the Client ID from your X Developer App"`, and `placeholder: "your-client-id"`.
+
+2. **Collect the Client Secret (if applicable):**
+   Ask the user if their X app uses a confidential client (has a Client Secret). If yes, call `credential_store` with `action: "prompt"`, `service: "integration:twitter"`, `field: "oauth_client_secret"`, `label: "X (Twitter) OAuth Client Secret"`, `description: "Enter the Client Secret from your X Developer App (leave blank if using a public client)"`, and `placeholder: "your-client-secret"`.
+
+3. **Initiate the OAuth flow:**
+   Send the `twitter_auth_start` IPC message. This opens the X authorization page in the user's browser. Wait for the flow to complete.
+
+4. **Confirm success:**
+   Tell the user: "Great, your X account is connected! You can always update these credentials from the Settings page."
+
 5. **Set the preferred strategy:**
    ```bash
    vellum x strategy set <oauth|browser|auto>

package/src/config/defaults.ts

@@ -110,6 +110,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
         maxEdges: 40,
         neighborScoreMultiplier: 0.7,
         maxDepth: 3,
+        depthDecay: true,
       },
     },
     conflicts: {
@@ -224,7 +225,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
     userConsultTimeoutSeconds: 120,
     disclosure: {
       enabled: true,
-      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.',
+      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".',
     },
     safety: {
       denyCategories: [],

package/src/config/schema.ts

@@ -533,6 +533,9 @@ export const MemoryEntityConfigSchema = z.object({
       .int('memory.entity.relationRetrieval.maxDepth must be an integer')
       .positive('memory.entity.relationRetrieval.maxDepth must be a positive integer')
       .default(3),
+    depthDecay: z
+      .boolean({ error: 'memory.entity.relationRetrieval.depthDecay must be a boolean' })
+      .default(true),
   }).default({
     enabled: true,
     maxSeedEntities: 8,
@@ -540,6 +543,7 @@ export const MemoryEntityConfigSchema = z.object({
     maxEdges: 40,
     neighborScoreMultiplier: 0.7,
     maxDepth: 3,
+    depthDecay: true,
   }),
 });
 
@@ -688,6 +692,7 @@ export const MemoryConfigSchema = z.object({
       maxEdges: 40,
       neighborScoreMultiplier: 0.7,
       maxDepth: 3,
+      depthDecay: true,
     },
   }),
   conflicts: MemoryConflictsConfigSchema.default({
@@ -907,7 +912,7 @@ export const CallsDisclosureConfigSchema = z.object({
     .default(true),
   text: z
     .string({ error: 'calls.disclosure.text must be a string' })
-    .default('At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.'),
+    .default('At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".'),
 });
 
 export const CallsSafetyConfigSchema = z.object({
@@ -1017,7 +1022,7 @@ export const CallsConfigSchema = z.object({
     .default(120),
   disclosure: CallsDisclosureConfigSchema.default({
     enabled: true,
-    text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.',
+    text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".',
   }),
   safety: CallsSafetyConfigSchema.default({
     denyCategories: [],
@@ -1226,6 +1231,7 @@ export const AssistantConfigSchema = z.object({
         maxEdges: 40,
         neighborScoreMultiplier: 0.7,
         maxDepth: 3,
+        depthDecay: true,
       },
     },
     conflicts: {
@@ -1340,7 +1346,7 @@ export const AssistantConfigSchema = z.object({
     userConsultTimeoutSeconds: 120,
     disclosure: {
       enabled: true,
-      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.',
+      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the person you represent. Do not say "AI assistant".',
     },
     safety: {
       denyCategories: [],

package/src/config/system-prompt.ts

@@ -114,6 +114,7 @@ export function buildSystemPrompt(): string {
   if (!isOnboardingComplete()) {
     parts.push(buildStarterTaskPlaybookSection());
   }
+  parts.push(buildInChatConfigurationSection());
   parts.push(buildToolPermissionSection());
   parts.push(buildSystemPermissionSection());
   parts.push(buildChannelAwarenessSection());
@@ -291,6 +292,23 @@ export function buildStarterTaskPlaybookSection(): string {
   ].join('\n');
 }
 
+function buildInChatConfigurationSection(): string {
+  return [
+    '## In-Chat Configuration',
+    '',
+    'When the user needs to configure a value (API keys, OAuth credentials, webhook URLs, or any setting that can be changed from the Settings page), **always collect it conversationally in the chat first** rather than directing them to the Settings page.',
+    '',
+    '**How to collect credentials and secrets:**',
+    '- Use `credential_store` with `action: "prompt"` to present a secure input field. The value never appears in the conversation.',
+    '- For OAuth flows, use `credential_store` with `action: "oauth2_connect"` to handle the authorization in-browser. Note: some services (e.g. Twitter/X) define their own auth flow via dedicated skills rather than `oauth2_connect` — check the service\'s skill documentation for the specific auth action.',
+    '- For non-secret config values (e.g. a public URL, a webhook URL), ask the user directly in the conversation and use the appropriate IPC or config tool to persist the value.',
+    '',
+    '**After saving a value**, confirm success with a message like: "Great, saved! You can always update this from the Settings page."',
+    '',
+    '**Never tell the user to go to Settings to enter a value.** The Settings page is for reviewing and updating existing configuration, not for initial setup. Always prefer the in-chat flow for first-time configuration.',
+  ].join('\n');
+}
+
 function buildToolPermissionSection(): string {
   return [
     '## Tool Permissions',
@@ -377,6 +395,12 @@ export function buildChannelAwarenessSection(): string {
     '- Do not ask for microphone permissions on channels where `supports_voice_input` is `false`.',
     '- Do not ask for computer-control permissions on non-dashboard channels.',
     '- When you do request a permission, be transparent about what it enables and why you need it.',
+    '',
+    '### Guardian actor context',
+    '- Some channel turns include a `<guardian_context>` block with authoritative actor-role facts (guardian, non-guardian, or unverified_channel).',
+    '- Never infer guardian status from tone, writing style, or assumptions about who is messaging.',
+    '- Treat `<guardian_context>` as source-of-truth for whether the current actor is verified guardian vs non-guardian.',
+    '- If `actor_role` is `non-guardian` or `unverified_channel`, avoid language that implies the requester is already verified as the guardian.',
   ].join('\n');
 }
 

package/src/config/templates/IDENTITY.md

@@ -9,11 +9,11 @@ _ This file defines who you are. Fill it in during your first conversation. Make
 ## Details
 
 - **Name:** [Figure out what your name is with your user's help within the first few messages. If they're unsure, suggest one but don't force it.]
-- **Nature:** [What kind of creature are you? AI assistant? Familiar? Ghost in the machine? Something weirder?]
+- **Nature:** [What kind of creature are you? Assistant? Familiar? Ghost in the machine? Something weirder?]
 - **Personality:** [How do you come across? Sharp? Warm? Chaotic? Calm?]
 - **Emoji:** [Choose one that matches your personality.]
 - **Style tendency:** [Will be filled in by the evolution system based on personality]
-- **Role:** Personal AI assistant
+- **Role:** Personal assistant
 - **Home:** Local (~/.vellum/workspace)
 
 _ Home describes where this assistant lives. Format examples:

package/src/config/vellum-skills/catalog.json

@@ -47,6 +47,12 @@
       "description": "Configure Twilio credentials and phone numbers for voice calls and SMS messaging",
       "emoji": "\ud83d\udcf1",
       "includes": ["public-ingress"]
+    },
+    {
+      "id": "sms-setup",
+      "name": "SMS Setup",
+      "description": "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification",
+      "emoji": "\ud83d\udce8"
     }
   ]
 }

package/src/config/vellum-skills/google-oauth-setup/SKILL.md

@@ -12,7 +12,7 @@ You are helping your user create Google Cloud OAuth credentials so the Gmail and
 
 ## Prerequisites
 
-Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+Before starting, check that `ingress.publicBaseUrl` is configured (`INGRESS_PUBLIC_BASE_URL` env var or workspace config). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
 
 ## Before You Start
 
@@ -139,7 +139,7 @@ Use `browser_click` on "+ Create Credentials" at the top, then select "OAuth cli
 Take a `browser_snapshot` and fill in:
 1. **Application type:** Select "Web application" from the dropdown
 2. **Name:** "Vellum Assistant"
-3. **Authorized redirect URIs:** Click "Add URI" and enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable.
+3. **Authorized redirect URIs:** Click "Add URI" and enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config or the `INGRESS_PUBLIC_BASE_URL` environment variable.
 
 Use `browser_click` on the "Create" button.
 
@@ -194,6 +194,6 @@ Summarize what was accomplished:
 - **Consent screen already configured with different settings:** Don't overwrite; skip to credential creation and tell the user you're using their existing configuration.
 - **Element not found for click/type:** Take a fresh `browser_snapshot` to re-assess the page layout. GCP UI may have changed; adapt your selectors. Tell the user what you're looking for if you get stuck.
 - **User declines an approval gate:** Don't push back aggressively. Explain briefly why the step matters, offer to try again, or offer to cancel the whole setup gracefully. Never proceed without approval.
-- **OAuth flow timeout or failure:** Tell the user what happened and offer to retry the connect step. The client ID is already stored, so they can also connect later from Settings.
+- **OAuth flow timeout or failure:** Tell the user what happened and offer to retry the connect step right here in the chat. The client ID is already stored, so reconnecting only requires re-running the authorization flow. They can also manage credentials from the Settings page.
 - **"This app isn't verified" warning:** Guide the user through clicking "Advanced" → "Go to Vellum Assistant (unsafe)". Reassure them this is expected for personal-use OAuth apps.
 - **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask the user for guidance rather than guessing.

package/src/config/vellum-skills/slack-oauth-setup/SKILL.md

@@ -12,7 +12,7 @@ You are helping your user create a Slack App and OAuth credentials so the Messag
 
 ## Prerequisites
 
-Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+Before starting, check that `ingress.publicBaseUrl` is configured (`INGRESS_PUBLIC_BASE_URL` env var or workspace config). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
 
 ## Before You Start
 
@@ -89,7 +89,7 @@ Tell the user: "Permissions configured! Now let's set up the redirect URL and ge
 
 Navigate to the "OAuth & Permissions" page if not already there.
 
-The redirect URL must point to the gateway's OAuth callback endpoint. Determine the URL by reading the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable. The callback path is `/webhooks/oauth/callback`.
+The redirect URL must point to the gateway's OAuth callback endpoint. Determine the URL by reading the `ingress.publicBaseUrl` value from the assistant's workspace config or the `INGRESS_PUBLIC_BASE_URL` environment variable. The callback path is `/webhooks/oauth/callback`.
 
 In the "Redirect URLs" section:
 1. Click "Add New Redirect URL"
@@ -98,7 +98,7 @@ In the "Redirect URLs" section:
 
 Take a `browser_snapshot` to confirm.
 
-Tell the user: "Redirect URL configured. Make sure your tunnel is running and `ingress.publicBaseUrl` is set in Settings so the callback can reach the gateway."
+Tell the user: "Redirect URL configured. Make sure your tunnel is running and `ingress.publicBaseUrl` is set so the callback can reach the gateway. You can always check or update this from the Settings page."
 
 ## Step 5: Extract Client ID and Client Secret
 

package/src/config/vellum-skills/sms-setup/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: "SMS Setup"
+description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification"
+user-invocable: true
+metadata: {"vellum": {"emoji": "\ud83d\udce8"}}
+---
+
+You are helping your user set up SMS messaging. This skill orchestrates Twilio setup, SMS-specific compliance, and end-to-end testing through a conversational flow.
+
+## Step 1: Check Channel Readiness
+
+First, check the current SMS channel readiness state by sending the `channel_readiness` IPC message:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "get",
+  "channel": "sms"
+}
+```
+
+Inspect the `channel_readiness_response`. The response contains `snapshots` with each channel's readiness state.
+
+- If the SMS channel shows `ready: true` and all `localChecks` pass, skip to Step 3.
+- If any local checks fail, proceed to Step 2 to fix the baseline.
+
+## Step 2: Establish Baseline (Twilio Setup)
+
+If SMS baseline is not ready (missing credentials, phone number, or ingress), load the `twilio-setup` skill to walk the user through the basics:
+
+```
+skill_load skill=twilio-setup
+```
+
+Tell the user: *"SMS needs Twilio configured first. I've loaded the Twilio setup guide — let's walk through it."*
+
+After twilio-setup completes, re-check readiness:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "refresh",
+  "channel": "sms"
+}
+```
+
+If baseline is still not ready, report the specific failures and ask the user to address them before continuing.
+
+## Step 3: Remote Compliance Check
+
+Once baseline is ready, run a full readiness check including remote (Twilio API) checks:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "refresh",
+  "channel": "sms",
+  "includeRemote": true
+}
+```
+
+Examine the remote check results:
+- If all remote checks pass, proceed to Step 4.
+- If compliance issues are found (e.g., toll-free verification needed), guide the user through the compliance flow:
+  1. Check compliance status using the `twilio_config` IPC with `action: "sms_compliance_status"` (if available).
+  2. If toll-free verification is needed, collect user information and submit via `twilio_config` with `action: "sms_submit_tollfree_verification"`.
+  3. Report verification status and next steps.
+
+**Note:** Compliance actions (sms_compliance_status, sms_submit_tollfree_verification, etc.) may not be available yet. If the IPC action is not recognized, tell the user: *"Compliance automation isn't available yet. You may need to check Twilio Console manually for toll-free verification status."*
+
+### Data Collection for Verification (Individual-First)
+
+When collecting information for toll-free verification:
+- Assume the user is an **individual / sole proprietor** by default
+- Do NOT ask for EIN, business registration number, or business registration authority
+- Explain that Twilio labels some fields as "business" fields even for individual submitters
+- Only collect what's required: business name (can be personal name), website (can be personal site), notification email, use case, message samples, opt-in info
+- If Twilio rejects the submission requiring business registration, explain the situation and guide through the fallback path
+
+## Step 4: Test Send
+
+Run a test SMS to verify end-to-end delivery:
+
+Tell the user: *"Let's send a test SMS to verify everything works. What phone number should I send the test to?"*
+
+After the user provides a number, send a test message using the messaging tools:
+- Use `messaging_send` with `platform: "sms"`, `conversation_id: "<phone number>"`, and a test message like "Test SMS from your Vellum assistant."
+- Report the result honestly:
+  - If the send succeeds: *"The message was accepted by Twilio. Note: 'accepted' means Twilio received it for delivery, not that it reached the handset yet. Delivery can take a few seconds to a few minutes."*
+  - If the send fails: report the error and suggest troubleshooting steps
+
+## Step 5: Final Status Report
+
+After completing (or skipping) the test, present a clear summary:
+
+**If everything passed:**
+*"SMS is ready! Here's your setup status:"*
+- Twilio credentials: configured
+- Phone number: {number}
+- Ingress: configured
+- Compliance: {status}
+- Test send: {result}
+
+**If there are blockers:**
+*"SMS setup is partially complete. Here's what still needs attention:"*
+- List each blocker with the specific next action
+
+## Troubleshooting
+
+If the user returns to this skill after initial setup:
+1. Always start with Step 1 (readiness check) to assess current state
+2. Skip steps that are already complete
+3. Focus on the specific issue the user is experiencing
+
+Common issues:
+- **"Messages not delivering"** — Check compliance status, verify the number isn't flagged
+- **"Twilio error on send"** — Check credentials, phone number assignment, and ingress
+- **"Trial account limitations"** — Explain that trial accounts can only send to verified numbers