@vellumai/assistant 0.3.4 → 0.3.6

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

@@ -20,7 +20,12 @@ Gmail, Slack, and Telegram setup all require a publicly reachable URL for OAuth
 2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Install and load the **google-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "google-oauth-setup"`.
    - Then call `skill_load` with `skill: "google-oauth-setup"`.
-   - Tell the user: *"Gmail isn't connected yet. I've loaded a setup guide that will walk you through creating Google credentials and connecting your account."*
+   - 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 browser where you sign in to Google, then automate everything else — creating a project, enabling APIs, and connecting your account. Takes 2-3 minutes and you can watch in the browser preview panel."
+     - **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.
 3. **If the user provides a client_id directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "gmail"`, and `client_id: "<their value>"`. Include `client_secret` too if they provide one. Everything else is auto-filled.
 
 ### Slack
@@ -28,7 +33,12 @@ Gmail, Slack, and Telegram setup all require a publicly reachable URL for OAuth
 2. **If it fails because no client_id is found:** The user needs to create a Slack App first. Install and load the **slack-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "slack-oauth-setup"`.
    - Then call `skill_load` with `skill: "slack-oauth-setup"`.
-   - Tell the user: *"Slack isn't connected yet. I've loaded a setup guide that will walk you through creating a Slack App and connecting your workspace."*
+   - Tell the user Slack 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 Slack?"
+     - **detail:** "I'll walk you through creating a Slack App and connecting your workspace. The process takes a few minutes, and I'll ask for your approval before each step."
+     - **confirmLabel:** "Get Started"
+     - **cancelLabel:** "Not Now"
+   - Wait for the user to confirm before proceeding with the setup guide. If they decline, acknowledge and let them know they can set it up later.
 3. **If the user provides client_id and client_secret directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "slack"`, `client_id`, and `client_secret`. Everything else is auto-filled. Note: Slack always requires a client_secret.
 
 ### Telegram
@@ -42,14 +52,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 +93,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-analyze-style.ts

@@ -7,12 +7,9 @@ import { memoryItems } from '../../../../memory/schema.js';
 import { enqueueMemoryJob } from '../../../../memory/jobs-store.js';
 import { extractStylePatterns } from '../../../../messaging/style-analyzer.js';
 import { truncate } from '../../../../util/truncate.js';
+import { clampUnitInterval } from '../../../../memory/validation.js';
 import { resolveProvider, withProviderToken, ok, err } from './shared.js';
 
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}
-
 function upsertMemoryItem(opts: {
   kind: string;
   subject: string;
@@ -35,7 +32,7 @@ function upsertMemoryItem(opts: {
       .set({
         statement: opts.statement,
         status: 'active',
-        importance: Math.max(existing.importance ?? 0, opts.importance),
+        importance: clampUnitInterval(Math.max(existing.importance ?? 0, opts.importance)),
         lastSeenAt: now,
         verificationState: 'assistant_inferred',
       })
@@ -51,7 +48,7 @@ function upsertMemoryItem(opts: {
       statement: opts.statement,
       status: 'active',
       confidence: 0.8,
-      importance: opts.importance,
+      importance: clampUnitInterval(opts.importance),
       fingerprint,
       verificationState: 'assistant_inferred',
       scopeId: opts.scopeId,
@@ -90,7 +87,7 @@ export async function run(input: Record<string, unknown>, context: ToolContext):
 
       for (const pattern of result.stylePatterns) {
         const subject = `${provider.id} writing style: ${pattern.aspect}`;
-        const importance = clamp(pattern.importance ?? 0.65, 0.55, 0.85);
+        const importance = clampUnitInterval(Math.min(0.85, Math.max(0.55, pattern.importance ?? 0.65)));
         upsertMemoryItem({ kind: 'style', subject, statement: pattern.summary, importance, scopeId });
         savedCount++;
       }

package/src/config/bundled-skills/messaging/tools/messaging-reply.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 threadId = input.thread_id as string;
@@ -22,6 +22,7 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
     return withProviderToken(provider, async (token) => {
       const result = await provider.sendMessage(token, conversationId, text, {
         threadId,
+        assistantId: context.assistantId,
       });
 
       return ok(`Reply sent (ID: ${result.id}).`);

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

@@ -1,12 +1,12 @@
 ---
 name: "Phone Calls"
-description: "Set up Twilio for outgoing phone calls and place AI-powered voice calls on behalf of the user"
+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"]
 ---
 
-You are helping the user set up and make outgoing phone calls via Twilio. This skill covers the full lifecycle: Twilio account setup, credential storage, public ingress configuration, enabling the calls feature, placing calls, and monitoring live transcripts.
+You are helping the user set up and manage phone calls via Twilio. This skill covers the full lifecycle: Twilio account setup, credential storage, public ingress configuration, enabling the calls feature, placing outbound calls, receiving inbound calls, and monitoring live transcripts.
 
 ## Prerequisites — Shared Twilio Setup
 
@@ -21,7 +21,9 @@ If Twilio is already configured (check `twilio_config` with `action: "get"`), sk
 
 ## Overview
 
-The calling system uses Twilio's ConversationRelay to place outbound phone calls. Twilio works out of the box as the default voice provider. Optionally, you can enable ElevenLabs integration for higher-quality, more natural-sounding voices — but this is entirely optional.
+The calling system uses Twilio's ConversationRelay for both **outbound** and **inbound** voice calls. Twilio works out of the box as the default voice provider. Optionally, you can enable ElevenLabs integration for higher-quality, more natural-sounding voices — but this is entirely optional.
+
+### Outbound calls
 
 When a call is placed:
 
@@ -31,6 +33,17 @@ When a call is placed:
 4. An LLM-driven orchestrator manages the conversation — receiving caller speech (transcribed by Deepgram), generating responses via Claude, and streaming text back for TTS playback
 5. The transcript is relayed live to the user's conversation thread
 
+### 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.
+
 Three voice quality modes are available:
 - **`twilio_standard`** (default) — Fully supported. Standard Twilio TTS with Google voices. No extra setup required.
 - **`twilio_elevenlabs_tts`** — Fully supported. Uses ElevenLabs voices through Twilio ConversationRelay for more natural speech.
@@ -181,6 +194,25 @@ credential_store action=store service=twilio field=user_phone_number value=+1415
 | `calls.callerIdentity.allowPerCallOverride` | Whether per-call mode selection is allowed | `true` |
 | `calls.callerIdentity.userNumber` | Optional E.164 phone number for user-number mode (alternative to storing via `credential_store`) | *(empty)* |
 
+## 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` |
+
 ## Optional: Higher Quality Voice with ElevenLabs
 
 ElevenLabs integration is entirely optional. The standard Twilio-only setup works unchanged — this section is only relevant if you want to improve voice quality.
@@ -264,7 +296,7 @@ To go back to the default voice at any time:
 vellum config set calls.voice.mode twilio_standard
 ```
 
-## Making Calls
+## Making Outbound Calls
 
 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`)
@@ -319,6 +351,30 @@ 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
+
+Once Twilio is configured and the assistant has a phone number, inbound calls work automatically. When someone dials the assistant's number:
+
+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
+4. The conversation proceeds naturally, with ASK_GUARDIAN dispatches to consult the user when needed
+
+No additional configuration is needed beyond the standard Twilio setup (Steps 1-5 above). As long as `calls.enabled` is `true` and the phone number has been provisioned/assigned, inbound calls are handled automatically.
+
+### Guardian voice verification for inbound calls
+
+Optionally, the user can require callers to verify themselves by entering a six-digit code before the call proceeds. This is managed through the **channel guardian verification** system:
+
+1. The user initiates a verification challenge from the desktop UI for the `voice` channel
+2. A six-digit code is generated and shown to the user
+3. When the next inbound call arrives, the relay server detects the pending challenge and prompts the caller: "Please enter your six-digit verification code using your keypad, or speak the digits now."
+4. The caller enters the code via DTMF (keypad) or by speaking the digits
+5. If the code matches, a guardian binding is created and the call proceeds normally
+6. If verification fails after 3 attempts, the call ends with "Verification failed. Goodbye."
+
+This feature is separate from the outbound DTMF callee verification. It uses the `ChannelGuardianService` challenge system rather than the per-call verification config.
+
 ## Live Call Monitoring
 
 ### Showing the live transcript
@@ -343,37 +399,31 @@ By default, always show the live transcript of the call as it happens. When a ca
 
 ### Interacting with a live call
 
-During an active call, the user can type messages in the chat thread to interact with the AI voice agent in real time. Messages are automatically routed to the call via the call bridge, which decides how to handle them based on the call's current state:
-
-#### Mode 1: Answering questions
+During an active call, the user can interact with the AI voice agent via the HTTP API endpoints:
 
-When the AI voice agent encounters something it needs user input for, a **pending question** appears in the chat. The call status changes to `waiting_on_user`.
+#### Answering questions
 
-1. A **pending question** appears in `call_status` output
-2. Present the question prominently to the user:
+When the AI voice agent encounters something it needs user input for, it dispatches an **ASK_GUARDIAN** request to all configured guardian channels (mac desktop, Telegram, SMS). The call status changes to `waiting_on_user`.
 
-```
-❓ The person on the call asked something the assistant needs your help with:
-   "They're asking if you'd prefer the smoking or non-smoking section?"
-```
-
-3. The user replies directly in the chat — since there is a pending question, the reply is automatically routed as an **answer** to the AI voice agent
-4. The AI voice agent receives the answer and continues the conversation naturally
+1. The question is delivered simultaneously to every configured channel. The first channel to respond wins (first-response-wins semantics) -- once one channel provides an answer, the other channels receive a "already answered" notice.
+2. On the mac desktop, a guardian request thread is created with the question. On Telegram/SMS, the question text and a request code are delivered via the gateway.
+3. If DTMF callee verification is enabled, the callee must enter a verification code before the call proceeds (see the **DTMF Callee Verification** section above).
+4. The guardian provides an answer through whichever channel they prefer. The answer is routed to the AI voice agent, which continues the conversation naturally.
 
 **Important:** Respond to pending questions quickly. There is a consultation timeout (default: 2 minutes). If no answer is provided in time, the AI voice agent will move on.
 
-#### Mode 2: Steering with instructions
+#### Steering with instructions
 
-When there is **no pending question** but the call is still active, any message the user types in the chat is treated as a **steering instruction**. This lets the user proactively guide the call in real time — for example:
+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"
 - "Switch to asking about weekend availability instead"
 - "Be more assertive about getting a discount"
 
-The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly. A confirmation message ("Instruction relayed to active call.") appears in the chat thread.
+The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly.
 
-**The user does not need to do anything special** — just type a message. The system automatically determines whether it should be an answer or an instruction based on whether a question is pending.
+**Note:** Mid-call steering via the desktop chat thread is no longer supported. The desktop thread only receives pointer/status messages about the call. To steer a call, use the HTTP API endpoints directly.
 
 ### Call status values
 
@@ -414,6 +464,7 @@ The `context` field is powerful — use it to give the agent background that hel
 
 ### Things the AI voice agent handles well
 
+**Outbound calls:**
 - Making reservations and appointments
 - Checking business hours, availability, or pricing
 - Confirming or rescheduling existing appointments
@@ -421,6 +472,12 @@ The `context` field is powerful — use it to give the agent background that hel
 - 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)
@@ -439,7 +496,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,12 +521,20 @@ 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
 ```
 
+## Accepted Regressions
+
+The following behavioral changes were introduced with the cross-channel guardian architecture (voice-cross-guardian):
+
+- **No more mid-call steering via desktop chat.** The call bridge that routed desktop chat messages to the active call has been removed. The desktop chat thread only receives pointer/status messages about the call. To steer a call, use the HTTP API endpoints directly (`POST /v1/calls/:id/instruction`).
+- **No live transcript mirror in the initiating chat.** The initiating desktop conversation no longer receives a real-time mirror of the call transcript. The initiating chat only gets pointer/status messages (call started, call ended, question asked, etc.).
+- **Guardian questions are dispatched cross-channel.** Rather than appearing only in the initiating desktop thread, ASK_GUARDIAN questions are now dispatched to all configured guardian channels (mac desktop, Telegram, SMS) simultaneously. The first channel to respond wins.
+
 ## Troubleshooting
 
 ### "Twilio credentials not configured"

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/bundled-skills/twitter/icon.svg

@@ -0,0 +1,14 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+<rect width="16" height="16" fill="#ffffff"/>
+<rect x="2" y="2" width="12" height="12" fill="#000000"/>
+<rect x="4" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="5" y="4" width="1" height="3" fill="#ffffff"/>
+<rect x="6" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="10" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="11" y="4" width="1" height="3" fill="#ffffff"/>
+<rect x="12" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="4" y="9" width="1" height="2" fill="#ffffff"/>
+<rect x="5" y="8" width="6" height="1" fill="#ffffff"/>
+<rect x="11" y="9" width="1" height="2" fill="#ffffff"/>
+<rect x="5" y="11" width="6" height="1" fill="#ffffff"/>
+</svg>