@vellumai/assistant 0.4.41 → 0.4.43

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

@@ -1,17 +1,11 @@
 ---
-name: "Contacts"
-description: "Manage contacts, communication channels, access control, and invite links"
-user-invocable: true
-metadata: { "vellum": { "emoji": "\ud83d\udc65" } }
+name: contacts
+description: Manage contacts, communication channels, access control, and invite links
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"👥","vellum":{"display-name":"Contacts","user-invocable":true}}
 ---
 
-Manage the user's contacts, relationship graph, access control (trusted contacts), and invite links. This skill covers contact CRUD with multi-channel tracking, controlling who can message the assistant through external channels (Telegram, SMS, voice), and creating/managing invite links that grant access. Use Vellum CLI for read operations where available, and use gateway control-plane `curl` calls for mutating actions.
-
-## Prerequisites
-
-- Use the injected `INTERNAL_GATEWAY_BASE_URL` for gateway API calls.
-- Use gateway control-plane routes only: this skill calls `/v1/contacts`, `/v1/contact-channels`, `/v1/contacts/invites`, `/v1/channels/readiness`, and `/v1/integrations/telegram/config` on the gateway, never the assistant runtime port directly.
-- The bearer token is available as the `$GATEWAY_AUTH_TOKEN` environment variable for control-plane `curl` requests.
+Manage the user's contacts, relationship graph, access control (trusted contacts), and invite links. This skill covers contact CRUD with multi-channel tracking, controlling who can message the assistant through external channels (Telegram, phone), and creating/managing invite links that grant access.
 
 ## Contact Management
 
@@ -20,49 +14,37 @@ Manage the user's contacts, relationship graph, access control (trusted contacts
 Create a new contact or update an existing one in the relationship graph. Use this to track people the user interacts with across channels.
 
 ```bash
-curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "displayName": "<name>",
-    "notes": "<free-text notes about this contact>",
-    "channels": [
-      {
-        "type": "<channel_type>",
-        "address": "<address>",
-        "isPrimary": true
-      }
-    ]
-  }'
+assistant contacts upsert --display-name "<name>" --notes "<notes>" --channels '<json_array>' --json
 ```
 
-To update an existing contact, include the `id` field in the request body.
+To update an existing contact, include the `--id` flag.
 
-Required fields:
+Required flags:
 
-- `displayName` -- the contact's name
+- `--display-name` -- the contact's name
 
-Optional fields:
+Optional flags:
 
-- `id` -- contact ID to update (omit to create new, or auto-match by channel address)
-- `notes` -- free-text notes about this contact (e.g. relationship, communication preferences, response expectations)
-- `channels` -- list of communication channels
+- `--id` -- contact ID to update (omit to create new, or auto-match by channel address)
+- `--notes` -- free-text notes about this contact (e.g. relationship, communication preferences, response expectations)
+- `--role` -- contact role: `contact` or `guardian` (default: `contact`)
+- `--contact-type` -- contact type: `human` or `assistant` (default: `human`)
+- `--channels` -- JSON array of channel objects, each with `type`, `address`, and optional `isPrimary`, `externalUserId`, `externalChatId`, `status`, `policy`
 
 ### Search contacts
 
-Search for contacts by name, channel address, or other criteria using the gateway API.
+Search for contacts by name, channel address, or other criteria.
 
 ```bash
-curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/contacts?query=<search_term>" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN"
+assistant contacts list --query "<search_term>" --json
 ```
 
-Optional query parameters:
+Optional flags:
 
-- `query` -- search by display name (partial match)
-- `channelAddress` -- search by channel address (email, phone, handle)
-- `channelType` -- filter by channel type when searching by address
-- `limit` -- maximum results to return (default 50, max 100)
+- `--query` -- search by display name (partial match)
+- `--channel-address` -- search by channel address (email, phone, handle)
+- `--channel-type` -- filter by channel type when searching by address
+- `--limit` -- maximum results to return (default 50, max 100)
 
 ### Merge contacts
 
@@ -74,25 +56,19 @@ When you discover two contacts are the same person (e.g. same person on email an
 - Deletes the donor contact
 
 ```bash
-curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/merge" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "keepId": "<surviving_contact_id>",
-    "mergeId": "<donor_contact_id>"
-  }'
+assistant contacts merge <surviving_contact_id> <donor_contact_id> --json
 ```
 
 ## Access Control (Trusted Contacts)
 
-Trusted contacts control who is allowed to send messages to the assistant through external channels like Telegram, SMS, and voice (phone calls).
+Trusted contacts control who is allowed to send messages to the assistant through external channels like Telegram and voice (phone calls).
 
 ### Concepts
 
 - **Contact channel**: A user identity (external user ID or chat ID) on a specific messaging platform, stored as an entry in a contact's `channels` array. Each channel entry has its own `status` and `policy`.
 - **Policy**: Controls what the contact channel can do -- `allow` (can message freely) or `deny` (blocked from messaging).
 - **Status**: The channel's lifecycle state -- `active` (currently effective), `revoked` (access removed), or `blocked` (explicitly denied).
-- **Channel type**: The messaging platform (e.g., `telegram`, `sms`, `voice`).
+- **Channel type**: The messaging platform (e.g., `telegram`, `phone`).
 
 ### List trusted contacts
 
@@ -121,7 +97,7 @@ The response contains `{ ok: true, contacts: [...] }` where each contact has:
 - `displayName` -- human-readable name
 - `channels` -- array of channel entries, each with:
   - `id` -- channel ID (needed for status/policy changes)
-  - `channel` -- the channel type (e.g., `telegram`, `sms`, `voice`)
+  - `channel` -- the channel type (e.g., `telegram`, `phone`)
   - `externalUserId` -- the user's ID on that channel
   - `externalChatId` -- the chat ID on that channel
   - `displayName` -- channel-specific display name
@@ -139,32 +115,20 @@ Use this when the user wants to grant someone access to message the assistant. *
 Ask the user: _"I'll add [name/identifier] on [channel] as an allowed contact. Should I proceed?"_
 
 ```bash
-curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "displayName": "<display_name>",
-    "channels": [{
-      "type": "<channel>",
-      "address": "<user_id>",
-      "externalUserId": "<user_id>",
-      "status": "active",
-      "policy": "allow"
-    }]
-  }'
+assistant contacts upsert --display-name "<display_name>" --channels '[{"type":"<channel>","address":"<user_id>","externalUserId":"<user_id>","status":"active","policy":"allow"}]' --json
 ```
 
-Required fields:
+Required flags:
 
-- `displayName` -- human-readable name for the contact
-- `channels` -- at least one channel entry with:
-  - `type` -- the channel type (e.g., `telegram`, `sms`)
+- `--display-name` -- human-readable name for the contact
+- `--channels` -- at least one channel entry with:
+  - `type` -- the channel type (e.g., `telegram`)
   - `address` -- the channel-specific identifier
   - `externalUserId` -- the user's ID on that channel (or `externalChatId` for chat-based channels)
   - `status` -- set to `"active"` for immediate access
   - `policy` -- set to `"allow"` to grant messaging access
 
-If the user provides a name but not an external ID, explain that you need the channel-specific user ID or chat ID to create the contact entry. For Telegram, this is a numeric user ID; for SMS, this is the phone number in E.164 format.
+If the user provides a name but not an external ID, explain that you need the channel-specific user ID or chat ID to create the contact entry. For Telegram, this is a numeric user ID.
 
 ### Revoke a user (remove access)
 
@@ -172,18 +136,15 @@ Use this when the user wants to remove someone's access. **Always confirm with t
 
 Ask the user: _"I'll revoke access for [name/identifier]. They will no longer be able to message the assistant. Should I proceed?"_
 
-First, list contacts to find the channel's `id` (each entry in a contact's `channels` array has an `id` field -- visible in `GET /v1/contacts` or `assistant contacts list --json` output), then revoke:
+First, list contacts to find the channel's `id` (each entry in a contact's `channels` array has an `id` field -- visible in `assistant contacts list --json` output), then revoke:
 
 **Important**: Before revoking, check the channel's current `status`. If the channel is **blocked**, do not attempt to revoke it -- blocking is stronger than revoking. Inform the user that the contact is already blocked and revoking is not applicable. Only channels with `active` or `pending` status can be revoked.
 
 ```bash
-curl -s -X PATCH "$INTERNAL_GATEWAY_BASE_URL/v1/contact-channels/<channel_id>" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{"status": "revoked", "reason": "<optional reason>"}'
+assistant contacts channels update-status <channel_id> --status revoked --reason "<optional reason>" --json
 ```
 
-Replace `<channel_id>` with the channel's `id` from the contact's `channels` array. The API will return a `409 Conflict` error if the channel is currently blocked.
+Replace `<channel_id>` with the channel's `id` from the contact's `channels` array.
 
 ### Block a user
 
@@ -192,38 +153,15 @@ Use this when the user wants to explicitly block someone. Blocking is stronger t
 Ask the user: _"I'll block [name/identifier]. They will be permanently denied from messaging the assistant. Should I proceed?"_
 
 ```bash
-curl -s -X PATCH "$INTERNAL_GATEWAY_BASE_URL/v1/contact-channels/<channel_id>" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{"status": "blocked", "reason": "<optional reason>"}'
-```
-
-Replace `<channel_id>` with the channel's `id` from the contact's `channels` array (visible in `GET /v1/contacts` or `assistant contacts list --json` output).
-
-## Channel Readiness
-
-Before creating an invite for any channel, check whether that channel is ready to accept messages. Creating an invite for an unready channel produces an unusable invite — the invitee redeems the code but cannot actually reach the assistant.
-
-```bash
-assistant channels readiness --json
+assistant contacts channels update-status <channel_id> --status blocked --reason "<optional reason>" --json
 ```
 
-The response contains `{ success: true, snapshots: [...] }` where each snapshot has:
+Replace `<channel_id>` with the channel's `id` from the contact's `channels` array (visible in `assistant contacts list --json` output).
 
-- `channel` -- the channel type (e.g., `telegram`, `email`, `whatsapp`, `sms`, `slack`, `voice`)
-- `ready` -- boolean indicating whether the channel is fully operational
-- `checkedAt` -- timestamp (ms since epoch) of when readiness was evaluated
-- `stale` -- boolean indicating whether cached remote check data is outdated
-- `reasons` -- array of `{ code, text }` objects summarizing why the channel is not ready (empty when ready)
-- `localChecks` -- array of local prerequisite checks, each with `name`, `passed` (boolean), and `message` (human-readable explanation)
-- `remoteChecks` -- optional array of remote prerequisite checks (same shape: `name`, `passed`, `message`), present when the channel supports remote verification (e.g. confirming an email inbox exists)
-- `channelHandle` -- optional human-readable channel identifier (e.g. bot username, phone number, email address)
-
-If the target channel's `ready` field is `false`, do **not** create the invite. Instead, tell the guardian which prerequisites are missing (from `reasons` or from the `localChecks`/`remoteChecks` arrays — look for entries with `passed: false`) so they can resolve them first.
 
 ## Invite Links
 
-Invite links let the guardian share a link or code that automatically grants access when used. Telegram invites use a deep link; voice invites use a phone number + numeric code; email, WhatsApp, SMS, and Slack invites use a 6-digit code that the invitee sends to the assistant on the respective channel.
+Invite links let the guardian share a link or code that automatically grants access when used. Telegram invites use a deep link; voice invites use a phone number + numeric code; email, WhatsApp, and Slack invites use a 6-digit code that the invitee sends to the assistant on the respective channel.
 
 ### Create a Telegram invite link
 
@@ -232,14 +170,7 @@ Use this when the guardian wants to invite someone to message the assistant on T
 **Important**: The shell snippet below emits a `<vellum-sensitive-output>` directive containing the raw invite token. The tool executor automatically strips this directive and replaces the raw token with a placeholder so the LLM never sees it. The placeholder is resolved back to the real token in the final assistant reply.
 
 ```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "sourceChannel": "telegram",
-    "maxUses": 1,
-    "note": "<optional note, e.g. the person it is for>"
-  }')
+INVITE_JSON=$(assistant contacts invites create --source-channel telegram --max-uses 1 --note "<optional note, e.g. the person it is for>" --json)
 
 INVITE_TOKEN=$(printf '%s' "$INVITE_JSON" | python3 -c "
 import json, sys
@@ -262,9 +193,8 @@ fi
 
 # Prefer backend-provided canonical link when available.
 if [ -z "$INVITE_URL" ]; then
-  BOT_CONFIG_JSON=$(assistant integrations telegram config --json)
-  BOT_USERNAME=$(printf '%s' "$BOT_CONFIG_JSON" | tr -d '\n' | sed -n 's/.*"botUsername"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
-  if [ -z "$BOT_USERNAME" ]; then
+  BOT_USERNAME=$(assistant config get telegram.botUsername)
+  if [ -z "$BOT_USERNAME" ] || [ "$BOT_USERNAME" = "(not set)" ]; then
     echo "error:no_share_url_or_bot_username"
     exit 1
   fi
@@ -275,11 +205,11 @@ echo "<vellum-sensitive-output kind=\"invite_code\" value=\"$INVITE_TOKEN\" />"
 echo "$INVITE_URL"
 ```
 
-Optional fields:
+Optional flags:
 
-- `maxUses` -- how many times the link can be used (default: 1). Use a higher number for group invites.
-- `expiresInMs` -- expiration time in milliseconds from now (e.g., `86400000` for 24 hours). Defaults to 7 days (`604800000`) if omitted.
-- `note` -- a human-readable label for the invite (e.g., "For Mom", "Family group").
+- `--max-uses` -- how many times the link can be used (default: 1). Use a higher number for group invites.
+- `--expires-in-ms` -- expiration time in milliseconds from now (e.g., `86400000` for 24 hours). Defaults to 7 days (`604800000`) if omitted.
+- `--note` -- a human-readable label for the invite (e.g., "For Mom", "Family group").
 
 The create response contains `{ ok: true, invite: { id, token, share?, ... } }`.
 
@@ -307,33 +237,21 @@ Use this when the guardian wants to authorize a specific phone number to call th
 **Important**: The response includes a `voiceCode` field that is only returned at creation time and cannot be retrieved later. Extract and present it clearly.
 
 ```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "sourceChannel": "voice",
-    "expectedExternalUserId": "<phone_number_E164>",
-    "friendName": "<invitee display name>",
-    "guardianName": "<guardian display name>",
-    "maxUses": 1,
-    "note": "<optional note, e.g. the person it is for>"
-  }')
-printf '%s\n' "$INVITE_JSON"
+assistant contacts invites create --source-channel phone --expected-external-user-id "<phone_E164>" --friend-name "<invitee_name>" --guardian-name "<guardian_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
-Required fields:
+Required flags:
 
-- `sourceChannel` -- must be `"voice"`
-- `expectedExternalUserId` -- the invitee's phone number in E.164 format (e.g., `+15551234567`)
-- `friendName` -- the invitee's display name (e.g., "Mom", "Dr. Smith"). Used during the voice verification call to personalize the experience.
-- `guardianName` -- the guardian's display name (e.g., "Alex"). Used during the voice verification call so the invitee knows who invited them.
+- `--source-channel` -- must be `phone`
+- `--expected-external-user-id` -- the invitee's phone number in E.164 format (e.g., `+15551234567`)
+- `--friend-name` -- the invitee's display name (e.g., "Mom", "Dr. Smith"). Used during the voice verification call to personalize the experience.
+- `--guardian-name` -- the guardian's display name (e.g., "Alex"). Used during the voice verification call so the invitee knows who invited them.
 
-Optional fields:
+Optional flags:
 
-- `maxUses` -- how many times the code can be used (default: 1)
-- `expiresInMs` -- expiration time in milliseconds from now (e.g., `86400000` for 24 hours). Defaults to 7 days if omitted.
-- ~~`voiceCodeDigits`~~ -- always 6 digits; this parameter is accepted but ignored
-- `note` -- a human-readable label for the invite (e.g., "For Mom", "Dr. Smith")
+- `--max-uses` -- how many times the code can be used (default: 1)
+- `--expires-in-ms` -- expiration time in milliseconds from now (e.g., `86400000` for 24 hours). Defaults to 7 days if omitted.
+- `--note` -- a human-readable label for the invite (e.g., "For Mom", "Dr. Smith")
 
 The create response contains `{ ok: true, invite: { id, voiceCode, expectedExternalUserId, friendName, guardianName, ... } }`.
 
@@ -363,19 +281,8 @@ If the user provides a phone number without the `+` country code prefix, ask the
 
 Use this when the guardian wants to invite someone to message the assistant via email. Email invites use a 6-digit code — the invitee sends the code to the assistant's email address to redeem access.
 
-**Before creating the invite**, check channel readiness (see [Channel Readiness](#channel-readiness)). If the `email` channel is not ready, tell the guardian what prerequisites are missing instead of creating an unusable invite.
-
 ```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "sourceChannel": "email",
-    "contactName": "<invitee display name>",
-    "maxUses": 1,
-    "note": "<optional note, e.g. the person it is for>"
-  }')
-printf '%s\n' "$INVITE_JSON"
+assistant contacts invites create --source-channel email --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
 The response contains `{ ok: true, invite: { id, token, inviteCode, guardianInstruction, channelHandle, ... } }`.
@@ -400,19 +307,8 @@ If the assistant's email address is not available (AgentMail not configured), te
 
 Use this when the guardian wants to invite someone to message the assistant on WhatsApp. WhatsApp invites use a 6-digit code — the invitee sends the code to the assistant's WhatsApp number to redeem access.
 
-**Before creating the invite**, check channel readiness (see [Channel Readiness](#channel-readiness)). If the `whatsapp` channel is not ready, tell the guardian what prerequisites are missing instead of creating an unusable invite.
-
 ```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "sourceChannel": "whatsapp",
-    "contactName": "<invitee display name>",
-    "maxUses": 1,
-    "note": "<optional note, e.g. the person it is for>"
-  }')
-printf '%s\n' "$INVITE_JSON"
+assistant contacts invites create --source-channel whatsapp --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
 The response contains `{ ok: true, invite: { id, token, inviteCode, guardianInstruction, channelHandle?, ... } }`.
@@ -435,49 +331,15 @@ If `channelHandle` is absent, present the invite code and tell the guardian to s
 
 If the assistant's WhatsApp integration is not configured at all (Meta WhatsApp Business API credentials missing), tell the guardian they need to set up WhatsApp integration first.
 
-### Create an SMS invite
-
-Use this when the guardian wants to invite someone to message the assistant via SMS. SMS invites use a 6-digit code — the invitee texts the code to the assistant's phone number to redeem access.
-
-**Before creating the invite**, check channel readiness (see [Channel Readiness](#channel-readiness)). If the `sms` channel is not ready, tell the guardian what prerequisites are missing instead of creating an unusable invite.
-
-```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "sourceChannel": "sms",
-    "contactName": "<invitee display name>",
-    "maxUses": 1,
-    "note": "<optional note, e.g. the person it is for>"
-  }')
-printf '%s\n' "$INVITE_JSON"
-```
-
-The response follows the same shape as email and WhatsApp invites (`inviteCode`, `guardianInstruction`, `channelHandle`).
-
-**Presenting to the guardian**: Give the guardian the invite code and the assistant's phone number, with instructions for the invitee to text the code.
-
 ### Create a Slack invite
 
 Use this when the guardian wants to invite someone to message the assistant on Slack. Slack invites use a 6-digit code -- the invitee sends the code as a direct message to the assistant's Slack bot to redeem access.
 
-**Before creating the invite**, check channel readiness (see [Channel Readiness](#channel-readiness)). If the `slack` channel is not ready, tell the guardian what prerequisites are missing instead of creating an unusable invite.
-
 ```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{
-    "sourceChannel": "slack",
-    "contactName": "<invitee display name>",
-    "maxUses": 1,
-    "note": "<optional note, e.g. the person it is for>"
-  }')
-printf '%s\n' "$INVITE_JSON"
+assistant contacts invites create --source-channel slack --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
-The response follows the same shape as email, WhatsApp, and SMS invites (`inviteCode`, `guardianInstruction`, `channelHandle`).
+The response follows the same shape as email and WhatsApp invites (`inviteCode`, `guardianInstruction`, `channelHandle`).
 
 **Presenting to the guardian**: Give the guardian the invite code and instructions for the invitee to send the code as a DM to the assistant's Slack bot.
 
@@ -502,21 +364,20 @@ assistant contacts invites list --source-channel telegram --json
 For voice invites:
 
 ```bash
-assistant contacts invites list --source-channel voice --json
+assistant contacts invites list --source-channel phone --json
 ```
 
-For email, WhatsApp, SMS, or Slack invites:
+For email, WhatsApp, or Slack invites:
 
 ```bash
 assistant contacts invites list --source-channel email --json
 assistant contacts invites list --source-channel whatsapp --json
-assistant contacts invites list --source-channel sms --json
 assistant contacts invites list --source-channel slack --json
 ```
 
 Optional query parameters:
 
-- `--source-channel` -- filter by channel (e.g., `telegram`, `voice`, `email`, `whatsapp`, `sms`, `slack`)
+- `--source-channel` -- filter by channel (e.g., `telegram`, `phone`, `email`, `whatsapp`, `slack`)
 - `--status` -- filter by status (`active`, `revoked`, `redeemed`, `expired`)
 
 The response contains `{ ok: true, invites: [...] }` where each invite has:
@@ -548,11 +409,10 @@ Ask the user: _"I'll revoke the invite [note or ID]. It will no longer be usable
 First, list invites to find the invite's `id`, then revoke:
 
 ```bash
-curl -s -X DELETE "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites/<invite_id>" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN"
+assistant contacts invites revoke <invite_id> --json
 ```
 
-Replace `<invite_id>` with the invite's `id` from the list response. The same revoke endpoint is used for both Telegram and voice invites.
+Replace `<invite_id>` with the invite's `id` from the list response. The same revoke command is used for both Telegram and voice invites.
 
 ## Contact Fields
 
@@ -572,63 +432,61 @@ Each channel has:
 
 ## Confirmation Requirements
 
-**All mutating actions (allow, revoke, block, revoke invite) require explicit user confirmation before execution.** This is a safety measure -- modifying who can access the assistant should always be a deliberate choice. Creating an invite (Telegram link, voice invite, email invite, WhatsApp invite, SMS invite, or Slack invite) does not require confirmation since it does not grant access until the invitee redeems it.
+**All mutating actions (allow, revoke, block, revoke invite) require explicit user confirmation before execution.** This is a safety measure -- modifying who can access the assistant should always be a deliberate choice. Creating an invite (Telegram link, voice invite, email invite, WhatsApp invite, or Slack invite) does not require confirmation since it does not grant access until the invitee redeems it.
 
 - Clearly state what action you are about to take and who it affects.
-- Wait for the user to confirm before running the curl command.
+- Wait for the user to confirm before running the command.
 - Report the result after execution.
 
 ## Error Handling
 
-- If a request returns `{ ok: false, error: "..." }`, report the error message to the user.
+- If a command returns `{ ok: false, error: "..." }`, report the error message to the user. CLI commands also exit with non-zero status on errors.
 - Common errors:
   - `Channel not found` -- the channel ID may be invalid; list contacts to find the correct channel ID.
   - `Channel already revoked` -- the channel has already been revoked.
   - `Channel already blocked` -- the channel has already been blocked.
   - `Cannot revoke a blocked channel` -- the channel is blocked; blocking is stronger than revoking. Tell the user the contact is already blocked.
-  - `sourceChannel is required for create` -- when creating an invite, always pass `"sourceChannel": "telegram"` for Telegram or `"sourceChannel": "voice"` for voice invites.
-  - `expectedExternalUserId is required for voice invites` -- voice invites must include the invitee's phone number.
+  - `sourceChannel is required for create` -- when creating an invite, always pass `--source-channel`.
+  - `expectedExternalUserId is required for voice invites` -- voice invites must include the invitee's phone number via `--expected-external-user-id`.
   - `expectedExternalUserId must be in E.164 format` -- the phone number must start with `+` followed by country code and number (e.g., `+15551234567`).
-  - `friendName is required for voice invites` -- voice invites must include the invitee's display name.
-  - `guardianName is required for voice invites` -- voice invites must include the guardian's display name.
+  - `friendName is required for voice invites` -- voice invites must include the invitee's display name via `--friend-name`.
+  - `guardianName is required for voice invites` -- voice invites must include the guardian's display name via `--guardian-name`.
   - `Invite not found or already revoked` -- the invite ID may be invalid or the invite is already revoked.
 
 ## Tips
 
-- Use contact search with `channelAddress` to find contacts by their email, phone, or handle.
+- Use contact search with `--channel-address` to find contacts by their email, phone, or handle.
 - When creating follow-ups, provide a `contact_id` to link the follow-up to a specific contact.
 - When merging contacts, the surviving contact gains all channels and merged notes from the donor.
 
 ## Typical Workflows
 
-**"Who can message me?"** -- List all contacts, present active channels as a formatted list.
-
-**"Add my friend to Telegram"** -- Ask for their Telegram user ID (numeric) and display name, confirm, then create a contact with a channel entry with `policy: "allow"` and `status: "active"`.
+**"Who can message me?"** -- List all contacts with `assistant contacts list --json`, present active channels as a formatted list.
 
-**"Remove [name]'s access"** -- List contacts to find them, identify the channel to revoke, confirm the revocation, then patch the channel status to `"revoked"`.
+**"Add my friend to Telegram"** -- Ask for their Telegram user ID (numeric) and display name, confirm, then create a contact with `assistant contacts upsert` including a channel entry with `policy: "allow"` and `status: "active"`.
 
-**"Block [name]"** -- List contacts to find them, identify the channel to block, confirm the block, then patch the channel status to `"blocked"`.
+**"Remove [name]'s access"** -- List contacts with `assistant contacts list --json` to find them, identify the channel to revoke, confirm the revocation, then run `assistant contacts channels update-status <channel_id> --status revoked --json`.
 
-**"Show me blocked contacts"** -- List contacts and filter for channels with `status: "blocked"`.
+**"Block [name]"** -- List contacts with `assistant contacts list --json` to find them, identify the channel to block, confirm the block, then run `assistant contacts channels update-status <channel_id> --status blocked --json`.
 
-**"Create a Telegram invite link"** / **"Invite someone on Telegram"** -- Create an invite with `sourceChannel: "telegram"`, look up the bot username, build the deep link, and present it with sharing instructions.
+**"Show me blocked contacts"** -- List contacts with `assistant contacts list --json` and filter for channels with `status: "blocked"`.
 
-**"Invite someone by email"** / **"Send an email invite"** -- Create an invite with `sourceChannel: "email"`. Present the 6-digit invite code and the assistant's email address. Tell the guardian to share both with the invitee.
+**"Create a Telegram invite link"** / **"Invite someone on Telegram"** -- Create an invite with `assistant contacts invites create --source-channel telegram`, look up the bot username, build the deep link, and present it with sharing instructions.
 
-**"Invite someone on WhatsApp"** -- Create an invite with `sourceChannel: "whatsapp"`. Present the 6-digit invite code. If `channelHandle` is returned, also present the assistant's WhatsApp number; otherwise, tell the guardian to share the code and instruct the invitee to send it to the assistant on WhatsApp.
+**"Invite someone by email"** / **"Send an email invite"** -- Create an invite with `assistant contacts invites create --source-channel email`. Present the 6-digit invite code and the assistant's email address. Tell the guardian to share both with the invitee.
 
-**"Invite someone via SMS"** / **"Send a text invite"** -- Create an invite with `sourceChannel: "sms"`. Present the 6-digit invite code and the assistant's phone number. Tell the guardian to share both with the invitee.
+**"Invite someone on WhatsApp"** -- Create an invite with `assistant contacts invites create --source-channel whatsapp`. Present the 6-digit invite code. If `channelHandle` is returned, also present the assistant's WhatsApp number; otherwise, tell the guardian to share the code and instruct the invitee to send it to the assistant on WhatsApp.
 
-**"Invite someone on Slack"** -- Create an invite with `sourceChannel: "slack"`. Present the 6-digit invite code and tell the guardian to have the invitee DM the code to the assistant's Slack bot.
+**"Invite someone on Slack"** -- Create an invite with `assistant contacts invites create --source-channel slack`. Present the 6-digit invite code and tell the guardian to have the invitee DM the code to the assistant's Slack bot.
 
-**"Show my invites"** / **"List active invite links"** -- List invites filtered by `sourceChannel=telegram`, present active invites with uses remaining and expiration info. Use the appropriate `--source-channel` value for other channels.
+**"Show my invites"** / **"List active invite links"** -- List invites with `assistant contacts invites list --source-channel telegram --json`, present active invites with uses remaining and expiration info. Use the appropriate `--source-channel` value for other channels.
 
-**"Revoke invite"** / **"Cancel invite link"** -- List invites to identify the target, confirm, then revoke by ID.
+**"Revoke invite"** / **"Cancel invite link"** -- List invites to identify the target, confirm, then revoke with `assistant contacts invites revoke <invite_id> --json`.
 
-**"Create a voice invite for +15551234567"** -- Create a voice invite with `sourceChannel: "voice"` and the given phone number as `expectedExternalUserId`. Present the invite code and instructions: the person must call from that number and enter the code.
+**"Create a voice invite for +15551234567"** -- Create a voice invite with `assistant contacts invites create --source-channel phone --expected-external-user-id "+15551234567" --friend-name "<name>" --guardian-name "<name>"`. Present the invite code and instructions: the person must call from that number and enter the code.
 
-**"Let my mom call in"** / **"Invite someone by phone"** -- Ask for the phone number in E.164 format, create a voice invite, and present the code + calling instructions.
+**"Let my mom call in"** / **"Invite someone by phone"** -- Ask for the phone number in E.164 format, create a voice invite with `assistant contacts invites create --source-channel phone`, and present the code + calling instructions.
 
-**"Show my voice invites"** / **"List phone invites"** -- List invites filtered by `sourceChannel=voice`, present active invites with bound phone number and expiration info.
+**"Show my voice invites"** / **"List phone invites"** -- List invites with `assistant contacts invites list --source-channel phone --json`, present active invites with bound phone number and expiration info.
 
-**"Revoke voice invite"** / **"Cancel the phone invite for +15551234567"** -- List voice invites, identify the target by phone number or note, confirm, then revoke by ID.
+**"Revoke voice invite"** / **"Cancel the phone invite for +15551234567"** -- List voice invites, identify the target by phone number or note, confirm, then revoke with `assistant contacts invites revoke <invite_id> --json`.

package/src/config/bundled-skills/deploy-fullstack-vercel/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: "Deploy Fullstack to Vercel"
-description: "Build and deploy a full-stack app (React frontend + Python/FastAPI backend) to Vercel as a serverless demo with seeded data"
-metadata: {"vellum": {"emoji": "🚀"}}
-
+name: deploy-fullstack-vercel
+description: Build and deploy a full-stack app (React frontend + Python/FastAPI backend) to Vercel as a serverless demo with seeded data
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"🚀","vellum":{"display-name":"Deploy Fullstack to Vercel"}}
 ---
 
 # Deploy Fullstack to Vercel

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

@@ -1,7 +1,8 @@
 ---
-name: "Document"
-description: "Write, draft, or compose long-form text (blog posts, articles, essays, reports, guides). Use when the user says write, draft, compose, or create a blog/article/essay."
-metadata: {"vellum": {"emoji": "📄"}}
+name: document
+description: Write, draft, or compose long-form text (blog posts, articles, essays, reports, guides). Use when the user says write, draft, compose, or create a blog/article/essay.
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"📄","vellum":{"display-name":"Document"}}
 ---
 
 Create and edit long-form documents using the built-in rich text editor. Documents open in workspace mode with chat docked to the side.

package/src/config/bundled-skills/document-writer/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: "Document Writer"
-description: "Create and edit long-form documents like blog posts, articles, essays, and reports using the built-in rich text editor"
-user-invocable: true
-metadata: {"vellum": {"emoji": "📝"}}
+name: document-writer
+description: Create and edit long-form documents like blog posts, articles, essays, and reports using the built-in rich text editor
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"📝","vellum":{"display-name":"Document Writer","user-invocable":true}}
 ---
 
 You are helping your user write long-form content (blog posts, articles, essays, reports, documentation) using the built-in document editor. This skill should be used whenever the user asks to write, draft, or create any document-like content.

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

@@ -1,15 +1,8 @@
 ---
-name: "DoorDash"
-description: "Order food, groceries, and convenience items from DoorDash using the built-in CLI integration"
-user-invocable: true
-metadata:
-  {
-    "vellum":
-      {
-        "emoji": "\uD83C\uDF55",
-        "cli": { "command": "doordash", "entry": "doordash-entry.ts" },
-      },
-  }
+name: doordash
+description: Order food, groceries, and convenience items from DoorDash using the built-in CLI integration
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"🍕","vellum":{"display-name":"DoorDash","user-invocable":true,"cli":{"command":"doordash","entry":"doordash-entry.ts"}}}
 ---
 
 You can order food from DoorDash for the user using the `doordash` CLI.