feat: chat-based sms-setup skill with catalog wiring

assistant/README.md

@@ -194,7 +194,7 @@ The `/channels/inbound` endpoint requires a valid `X-Gateway-Origin` header to p
 
 ## Twilio Setup Primitive
 
-Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill.
+Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill. For SMS-specific onboarding (including compliance verification and test sending), the `sms-setup` skill provides a guided conversational flow that layers on top of `twilio-setup`.
 
 ### `twilio_config` IPC Contract
 

assistant/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
 

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

@@ -47,6 +47,13 @@
       "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",
+      "includes": ["twilio-setup"]
     }
   ]
 }

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

@@ -0,0 +1,119 @@
+---
+name: "SMS Setup"
+description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification"
+user-invocable: true
+includes: ["twilio-setup"]
+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

skills/catalog.json

@@ -47,6 +47,13 @@
       "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",
+      "includes": ["twilio-setup"]
     }
   ]
 }

skills/sms-setup/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: "SMS Setup"
+description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification"
+user-invocable: true
+includes: ["twilio-setup"]
+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