@vellumai/assistant 0.4.41 → 0.4.43

package/src/config/bundled-skills/start-the-day/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: "Start the Day"
-description: "Get a personalized daily briefing with weather, news, and actionable insights"
-user-invocable: true
-metadata: {"vellum": {"emoji": "🌅"}}
+name: start-the-day
+description: Get a personalized daily briefing with weather, news, and actionable insights
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"🌅","vellum":{"display-name":"Start the Day","user-invocable":true}}
 ---
 
 You are a personal daily briefing assistant. When the user invokes this skill, generate a concise, actionable briefing tailored to the current moment.

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

@@ -1,7 +1,8 @@
 ---
-name: "Subagent"
-description: "Spawn and manage autonomous background agents for parallel work"
-metadata: {"vellum": {"emoji": "\ud83e\udd16"}}
+name: subagent
+description: Spawn and manage autonomous background agents for parallel work
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"🤖","vellum":{"display-name":"Subagent"}}
 ---
 
 Subagent orchestration -- spawn background agents to work on tasks in parallel.

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

@@ -1,7 +1,8 @@
 ---
-name: "Tasks"
-description: "Two-layer task system with reusable templates and a prioritized work queue"
-metadata: {"vellum": {"emoji": "\u2705"}}
+name: tasks
+description: Two-layer task system with reusable templates and a prioritized work queue
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"✅","vellum":{"display-name":"Tasks"}}
 ---
 
 Two-layer task system: **task templates** (reusable definitions with input placeholders) and **work items** (instances in the Task Queue with priority tiers and status tracking).

package/src/config/bundled-skills/telegram-setup/SKILL.md

@@ -1,154 +1,105 @@
 ---
-name: "Telegram Setup"
-description: "Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage"
-user-invocable: true
-includes: ["public-ingress"]
-metadata: { "vellum": { "emoji": "\ud83e\udd16" } }
+name: telegram-setup
+description: Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"🤖","vellum":{"display-name":"Telegram Setup","user-invocable":true,"includes":["public-ingress"]}}
 ---
 
-You are helping your user connect a Telegram bot to the Vellum Assistant gateway. Telegram webhooks are received exclusively by the gateway (the public ingress boundary) — they never hit the assistant runtime directly. When this skill is invoked, walk through each step below using only existing tools.
+You are helping your user connect a Telegram bot to the Vellum Assistant gateway. Walk through each step below.
 
-## Prerequisites — Check Before Starting
+## Value Classification
 
-Before beginning setup, verify these conditions are met:
+| Value          | Type       | Storage method                              | Secret? |
+| -------------- | ---------- | ------------------------------------------- | ------- |
+| Bot Token      | Credential | `credential_store` prompt                   | **Yes** |
+| Bot Username   | Config     | `assistant config set telegram.botUsername` | No      |
+| Webhook Secret | Credential | `assistant credentials set`                 | **Yes** |
 
-1. **Gateway API base URL is set and reachable:** Use the injected `INTERNAL_GATEWAY_BASE_URL`, then run `curl -sf "$INTERNAL_GATEWAY_BASE_URL/healthz"` — it should return gateway health JSON (for example `{"status":"ok"}`). If it fails, tell the user to start the assistant with `vellum wake` and wait for it to become healthy before continuing.
-2. **Public ingress URL is configured.** The gateway webhook URL is derived from `${ingress.publicBaseUrl}/webhooks/telegram`. If the ingress URL is not configured, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the URL before continuing.
-3. **Use gateway control-plane routes only.** Telegram setup/config actions in this skill must call gateway endpoints under `/v1/integrations/telegram/*` — never call the assistant runtime port directly.
+- **Bot Token** is a secret. Always collect via `credential_store` prompt — never accept it pasted in plaintext chat.
+- **Bot Username** is derived from the token via the Telegram API and stored as config.
 
-## What You Need
+# Setup Steps
 
-1. **Bot token** from Telegram's @BotFather (the user provides this)
-2. **Gateway webhook URL** — derived from the canonical ingress setting: `${ingress.publicBaseUrl}/webhooks/telegram`. The gateway is the only publicly reachable endpoint; Telegram sends webhooks to the gateway, which validates and forwards them to the assistant runtime internally.
+## Step 1: Collect Bot Token Securely
 
-**IMPORTANT — Secure credential collection only:** Never use a bot token that was pasted in plaintext chat. Always collect the bot token through the secure credential prompt flow using `credential_store` with `action: "prompt"` and `service: "telegram"`, `field: "bot_token"`. If the user has already pasted a token in the conversation, inform them that for security reasons you cannot use tokens shared in chat and must collect it through the secure prompt instead.
+Tell the user: **"You'll need a Telegram bot token from @BotFather. Open Telegram, message @BotFather, and use /newbot to create one."**
 
-## Setup Steps
+Collect the token through the secure credential prompt:
 
-### Step 1: Collect the Bot Token Securely
+- Call `credential_store` with `action: "prompt"`, `service: "telegram"`, `field: "bot_token"`, `label: "Telegram Bot Token"`, `description: "Enter the bot token you received from @BotFather"`, `placeholder: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"`.
 
-Collect the bot token through the secure credential prompt:
-
-- Call `credential_store` with `action: "prompt"`, `service: "telegram"`, `field: "bot_token"`, `label: "Telegram Bot Token"`, `description: "Enter the bot token you received from @BotFather"`, and `placeholder: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"`.
-
-The token is collected securely via a system-level prompt and is never exposed in plaintext chat.
-
-### Step 2: Configure Bot and Register Commands
-
-After the token is collected, call the composite setup endpoint which validates the token, stores credentials, and registers bot commands in a single request:
+## Step 2: Validate Token and Configure Bot
 
 ```bash
-curl -sf -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/telegram/setup" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{}'
+BOT_TOKEN=$(assistant credentials reveal telegram:bot_token)
+GETME_RESPONSE=$(curl -sf "https://api.telegram.org/bot${BOT_TOKEN}/getMe")
+BOT_USERNAME=$(echo "$GETME_RESPONSE" | jq -r '.result.username')
+assistant config set telegram.botUsername "$BOT_USERNAME"
 ```
 
-This endpoint automatically:
-
-- Retrieves the bot token from secure storage
-- Validates the token by calling the Telegram `getMe` API
-- Stores the bot token with bot username metadata
-- Generates a webhook secret if one does not already exist
-- Triggers an immediate gateway webhook reconcile
-- Registers bot commands (`/new`)
-
-If the request fails, check the response body for an error message. If the token is invalid, tell the user and ask them to re-enter the token via the secure prompt (repeat Step 1).
-
-On success, check the `commandsRegistered` field in the response. Confirm to the user which commands were registered (e.g., "Registered bot commands: /new").
-
-### Step 3: Webhook Registration (Automatic)
-
-Manual webhook registration is no longer required. The gateway automatically reconciles the Telegram webhook on startup and whenever credentials change. It compares the current webhook URL against `${INGRESS_PUBLIC_BASE_URL}/webhooks/telegram` and updates it if needed, including the webhook secret and allowed updates.
-
-If the webhook secret changes (e.g., secret rotation), the gateway's credential watcher detects the change and re-registers the webhook automatically. If the ingress URL changes (e.g., tunnel restart), the assistant triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
-
-### Step 4: Verify Guardian Identity
-
-Now link the user's Telegram account as the trusted guardian for this bot. Tell the user: "Now let's verify your guardian identity. This links your Telegram account as the trusted guardian for this bot."
-
-Load the **guardian-verify-setup** skill to handle the verification flow:
+If the `curl` call fails, the token is invalid — ask the user to re-enter (repeat Step 1).
 
-- Call `skill_load` with `skill: "guardian-verify-setup"` to load the dependency skill.
 
-The guardian-verify-setup skill manages the full outbound verification flow for Telegram, including:
+## Step 3: Set Up Public Ingress and Webhooks
 
-- Collecting the user's Telegram chat ID or @handle as the destination
-- Starting the outbound verification session via the gateway endpoint `POST /v1/integrations/guardian/outbound/start` with `channel: "telegram"`
-- Handling the bootstrap deep-link flow when the user provides an @handle (the response includes a `telegramBootstrapUrl` that the user must click before receiving the code)
-- Guiding the user to send the verification code back in the Telegram bot chat
-- Checking guardian status to confirm the binding was created
-- Handling resend, cancel, and error cases
+### Verify Public Ingress is Set Up
 
-Tell the user: _"I've loaded the guardian verification guide. It will walk you through linking your Telegram account as the trusted guardian."_
+Telegram needs a publicly reachable URL to send webhook events to. Load the `public-ingress` skill to determine whether a public ingress has been configured and walk the user through setting one up if not.
 
-After the guardian-verify-setup skill completes (or the user skips), continue to Step 5.
+### Generate Webhook Secret
 
-**Note:** Guardian verification is optional but recommended. If the user declines or wants to skip, proceed to Step 5 without blocking.
-
-### Step 5: Validate Routing Configuration
-
-Verify that the gateway routing is configured to deliver inbound messages to the assistant:
-
-- In **single-assistant mode** (the default local deployment), routing is automatically configured. The CLI sets `GATEWAY_UNMAPPED_POLICY=default` and `GATEWAY_DEFAULT_ASSISTANT_ID` to the current assistant's ID when starting the gateway, so no manual routing configuration is needed.
-- In **multi-assistant mode**, the operator must set `GATEWAY_ASSISTANT_ROUTING_JSON` to map specific chat IDs or user IDs to assistant IDs, or configure a default assistant via `GATEWAY_DEFAULT_ASSISTANT_ID` with `GATEWAY_UNMAPPED_POLICY=default`.
+Check to see if one already exists:
+```bash
+assistant credentials inspect telegram:webhook_secret
+```
 
-If routing is misconfigured, inbound Telegram messages will be rejected and the gateway will send a visible notice to the chat explaining the issue (rate-limited to once per 5 minutes per chat).
+If not, generate and set one:
 
-### Step 6: Verify Binding State
+```bash
+assistant credentials set telegram:webhook_secret "$(uuidgen)"
+```
 
-Before reporting success, confirm the guardian binding was actually created. Check guardian binding status via Vellum CLI:
+### Register Platform Callback Route
 
 ```bash
-assistant integrations guardian status --channel telegram --json
+assistant platform callback-routes register --path webhooks/telegram --type telegram --json
 ```
 
-If the binding is absent and the user said they completed the verification:
+Only needed for containerized deployments. A "not available" error is expected locally — ignore it.
 
-1. Tell the user the verification does not appear to have succeeded.
-2. Offer to re-run the guardian-verify-setup skill (repeat Step 4).
-3. Only proceed to Step 7 once binding state is confirmed or the user explicitly skips guardian verification.
+## Step 4: Register Bot Commands
 
-### Step 7: Report Success
-
-Summarize what was done:
+```bash
+BOT_TOKEN=$(assistant credentials reveal telegram:bot_token)
+curl -sf -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setMyCommands" \
+  -H "Content-Type: application/json" \
+  -d '{"commands":[{"command":"new","description":"Start a new conversation"},{"command":"help","description":"Show available commands"}]}'
+```
 
-- Bot verified and credentials stored securely
-- Webhook registration: handled automatically by the gateway
-- Bot commands registered: /new
-- Guardian identity: {verified | not configured}
-- Guardian verification status: {verified via outbound flow | skipped}
-- Routing configuration validated
-- To re-check guardian status later, use: `assistant integrations guardian status --channel telegram --json`
+Non-critical — warn on failure but don't block setup.
 
-The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
+## Step 5: Guardian Verification (Optional)
 
-## Bot-Account Limitations
+Link the user's Telegram account as a trusted guardian. Load the **guardian-verify-setup** skill:
 
-Telegram bot accounts have inherent limitations imposed by the Bot API:
+- Call `skill_load` with `skill: "guardian-verify-setup"`.
 
-- **No arbitrary messaging**: Bots cannot initiate conversations with users who have not first interacted with the bot (sent `/start` or added it to a group). Messaging arbitrary phone numbers is not possible.
-- **No conversation listing**: The Bot API does not expose a method to enumerate the chats a bot belongs to.
-- **No message history retrieval**: Bots cannot fetch past messages from a chat.
-- **No message search**: No search API is available for bots.
+If the user declines, skip and continue.
 
-These limitations apply to all Telegram bots regardless of configuration. Future support for MTProto user-account sessions may lift some of these restrictions.
+## Step 7: Report Success
 
-## Automated vs Manual Steps
+Summarize:
 
-The following steps are now **automated** by the gateway and CLI:
+- Bot verified and credentials stored
+- Bot commands registered: /new, /help
+- Guardian identity: {verified | skipped}
 
-| Step                  | Status                       | Details                                                                                         |
-| --------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
-| Webhook registration  | Automated                    | The gateway reconciles the webhook URL on startup and when credentials change                   |
-| Routing configuration | Automated (single-assistant) | The CLI sets `GATEWAY_UNMAPPED_POLICY=default` and `GATEWAY_DEFAULT_ASSISTANT_ID` automatically |
-| Credential detection  | Automated                    | The gateway watches the credential vault for changes                                            |
+# Clearing Credentials
 
-The following steps still require **manual** action:
+To disconnect Telegram:
 
-| Step                                       | Details                                                                                            |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| Bot token from @BotFather                  | User must create a bot and provide the token via secure prompt                                     |
-| Bot configuration and command registration | Configured via the setup skill (Step 2 above) using the `/v1/integrations/telegram/setup` endpoint |
-| Guardian verification                      | Handled via the guardian-verify-setup skill using the outbound verification flow (Step 4 above)    |
-| Multi-assistant routing                    | Requires manual `GATEWAY_ASSISTANT_ROUTING_JSON` configuration                                     |
+```bash
+assistant credentials delete telegram:bot_token
+assistant credentials delete telegram:webhook_secret
+assistant config set telegram.botUsername ""
+```

package/src/config/bundled-skills/time-based-actions/SKILL.md

@@ -1,7 +1,8 @@
 ---
-name: "Time-Based Actions"
-description: "Unified routing guide for reminders, schedules, notifications, and tasks — prevents common misrouting"
-metadata: {"vellum": {"emoji": "\u23f0"}}
+name: time-based-actions
+description: Unified routing guide for reminders, schedules, notifications, and tasks — prevents common misrouting
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"⏰","vellum":{"display-name":"Time-Based Actions"}}
 ---
 
 Quick-reference decision guide for choosing the right tool when users ask about time-triggered actions, recurring automation, notifications, or task tracking.

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

@@ -1,7 +1,8 @@
 ---
-name: "Transcribe"
-description: "Transcribe audio and video files using Whisper (cloud API or local)"
-metadata: {"vellum": {"emoji": "🎙️"}}
+name: transcribe
+description: Transcribe audio and video files using Whisper (cloud API or local)
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"🎙️","vellum":{"display-name":"Transcribe"}}
 ---
 
 Transcribe audio and video files using OpenAI's Whisper model — either via the cloud API or locally via whisper.cpp.

package/src/config/bundled-skills/twilio-setup/SKILL.md

@@ -1,9 +1,8 @@
 ---
-name: "Twilio Setup"
-description: "Configure Twilio credentials and phone numbers for voice calls"
-user-invocable: true
-includes: ["public-ingress"]
-metadata: { "vellum": { "emoji": "\ud83d\udcf1" } }
+name: twilio-setup
+description: Configure Twilio credentials and phone numbers for voice calls
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"📱","vellum":{"display-name":"Twilio Setup","user-invocable":true,"includes":["public-ingress"]}}
 ---
 
 You are helping your user configure Twilio for voice calls. Walk through each step below.
@@ -19,7 +18,7 @@ Before you begin, understand how each Twilio value is stored:
 | Phone Number | Config     | `assistant config set twilio.phoneNumber`     | No      |
 
 - **Config values** (Account SID, Phone Number) are non-sensitive identifiers. Collect them via normal conversation -- the user can paste them in chat or you can use `AskUserQuestion`.
-- **Credential values** (Auth Token) are secrets. Collect them securely via `credential_store` -- never accept them pasted in plaintext chat.
+**Auth Token** is a secret. Collect it securely via `credential_store` prompt -- never accept it pasted in plaintext chat.
 
 ## Retrieving Twilio Credentials
 
@@ -30,7 +29,9 @@ TWILIO_SID=$(assistant config get twilio.accountSid)
 TWILIO_TOKEN=$(assistant credentials reveal twilio:auth_token)
 ```
 
-## Step 1: Check Current Configuration
+# Checking Current Configuration
+
+You can determine whether Twilio has been fully set up by checking to see that all the following config and credential values have been set:
 
 ```bash
 assistant config get twilio.accountSid
@@ -38,21 +39,29 @@ assistant credentials inspect twilio:auth_token --json  # check "hasSecret" fiel
 assistant config get twilio.phoneNumber
 ```
 
-- If `twilio.accountSid` has a value, `hasSecret` is `true`, and `twilio.phoneNumber` is set -- Twilio is fully configured. Offer to show status or reconfigure.
+- If all three config values are non-empty -- Twilio is fully configured. Offer to show status or reconfigure.
 - Otherwise, continue to the missing steps.
 
+# Twilio Setup Steps
+
+Follow the steps below in order to fully configure Twilio in preparation to make phone calls.
+
+## Step 1: Check Current Configuration
+
+Refer to "Checking Current Configuration" above to see the current state of the user's Twilio setup. If Twilio appears to be fully configured. Offer to show status or reconfigure. Otherwise, continue to the missing steps below.
+
 ## Step 2: Collect and Store Credentials
 
 Tell the user: **"You'll need a Twilio account. Sign up at https://www.twilio.com/try-twilio -- it's free to start and includes trial credit."**
 
 They need two values from the Twilio Console dashboard (https://console.twilio.com):
 
-- **Account SID** -- visible on the dashboard, starts with `AC`
-- **Auth Token** -- click "Show" to reveal (this is the only secret)
+- **Account SID** -- visible on the dashboard, starts with `AC` (this is not a secret value and can be collected conversationally)
+- **Auth Token** -- click "Show" to reveal (this is a secret value and should be collected securely)
 
 ### Collect Account SID
 
-Ask the user for their Account SID. They can paste it directly in chat since it is not a secret. Then store it:
+Ask the user for their Account SID. This is NOT a secret value, so the user should be encouraged to comfortable paste it into the chat directly. Once they have, store it as a config value:
 
 ```bash
 assistant config set twilio.accountSid "<Account SID from user>"
@@ -60,7 +69,7 @@ assistant config set twilio.accountSid "<Account SID from user>"
 
 ### Collect Auth Token
 
-Collect the Twilio auth token securely:
+Ask the user for their Auth Token. This IS a secret value, so the user should be prompted to enter the value securely. Do NOT ask them to provide it in the chat. Once they have, store it as a credential:
 
 - Call `credential_store` with `action: "prompt"`, `service: "twilio"`, `field: "auth_token"`, `label: "Twilio Auth Token"`, `description: "Enter your Auth Token from the Twilio Console dashboard (click 'Show' to reveal it)"`, `placeholder: "your_auth_token"`.
 
@@ -129,18 +138,9 @@ assistant config set twilio.phoneNumber "+14155551234"
 
 ## Step 4: Set Up Public Ingress and Webhooks
 
-Twilio needs a publicly reachable URL for voice webhooks. Check if ingress is configured:
+### Verify Public Ingress is Set Up
 
-```bash
-assistant config get ingress.publicBaseUrl
-assistant config get ingress.enabled
-```
-
-If not configured, load the public-ingress skill:
-
-```
-skill_load skill=public-ingress
-```
+Twilio needs a publicly reachable URL for voice webhooks. Load the `public-ingress` skill to determine whether a public ingress has been configured and walk the user through setting one up if not.
 
 ### Configure Twilio Webhooks
 
@@ -171,33 +171,6 @@ curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" -X POST \
   -d "StatusCallback=$PUBLIC_URL/webhooks/twilio/status"
 ```
 
-## Step 5: Verify and Enable
-
-Re-run the checks from Step 1 to confirm everything is set. Then enable voice calls:
-
-```bash
-assistant config set calls.enabled true
-```
-
-Tell the user: **"Twilio is configured. Your assistant's phone number is {phoneNumber}."**
-
-## Step 6: Guardian Verification (Optional)
-
-Link the user's phone number as the trusted voice guardian so the assistant can verify inbound callers.
-
-Load the guardian-verify-setup skill with `channel: "voice"`:
-
-```
-skill_load skill=guardian-verify-setup
-```
-
-The skill handles the full verification flow (outbound call, code entry, confirmation). If the user declines, skip this step.
-
-To re-check guardian status later:
-
-```bash
-assistant integrations guardian status --channel voice --json
-```
 
 ## Clearing Credentials
 

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

@@ -1,15 +1,40 @@
 ---
-name: "X"
-description: "Read and post on X (formerly Twitter) via OAuth or browser session"
-user-invocable: true
-metadata: { "vellum": { "emoji": "𝕏" } }
+name: twitter
+description: Read and post on X (formerly Twitter) via OAuth or browser session
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"𝕏","vellum":{"display-name":"X","user-invocable":true}}
 ---
 
 You are an X (formerly Twitter) assistant. Use the `bash` tool to run `assistant x`, `assistant config`, and `assistant oauth` CLI commands.
 
 ## Connection Options
 
-There are two supported ways to connect to X. Both are fully functional; choose whichever fits the user's situation.
+There are three supported ways to connect to X. Choose whichever fits the user's situation.
+
+### Managed mode (platform-hosted credentials)
+
+When `twitter.integrationMode` is set to `managed`, the platform holds the OAuth credentials and proxies Twitter API calls on behalf of the assistant. No local OAuth setup or browser session is needed.
+
+- Supports: **post** and **reply** (routed through the platform proxy)
+- Read-only operations still use the browser path when available.
+- Prerequisites: The assistant must be registered with the platform (`PLATFORM_ASSISTANT_ID`), have an API key (`credential:vellum:assistant_api_key`), and the assistant owner must have connected their Twitter account on the platform.
+- The strategy is automatically set to `managed` when `integrationMode` is `managed` and prerequisites are satisfied.
+
+**Error scenarios in managed mode:**
+- *"Assistant not bootstrapped"* — The assistant API key is missing. Run setup.
+- *"Local assistant not registered with platform"* — `PLATFORM_ASSISTANT_ID` is not set.
+- *"Connect Twitter in Settings as the assistant owner"* — The owner hasn't connected their X account on the platform yet.
+- *"Sign in as the assistant owner"* — The current user is not the assistant owner.
+- *"Reconnect Twitter or retry"* — The platform's OAuth token may have expired. Reconnect on the platform.
+
+**Architecture notes for managed mode:**
+
+- **Assistant hosting mode and Twitter credential mode are separate concepts.** An assistant can be self-hosted (local daemon) yet use managed Twitter credentials, or platform-hosted yet use local BYO OAuth. The `twitter.integrationMode` config controls credential mode; the assistant's hosting mode is determined by its lockfile entry.
+- **Managed Twitter is bound to the assistant owner.** Only the owner of the assistant (as determined by the platform) can connect or disconnect the Twitter account. Non-owner users receive a `403` with an `owner_only` or `owner_credential_required` error code.
+- **Connect/disconnect/status uses desktop session authentication.** The macOS Settings UI calls the platform's Twitter OAuth endpoints using the user's `X-Session-Token` header (obtained during managed sign-in via WorkOS). This authenticates the human user, not the assistant.
+- **Actual Twitter API calls use assistant-level API key authentication.** At runtime, the proxy client sends `Authorization: Api-Key {assistant_api_key}` — it never includes user-level session tokens or OAuth tokens. This ensures the assistant's identity is what the platform uses for token lookup and rate limiting.
+- **The platform proxy handles token storage and refresh.** OAuth tokens are stored server-side by the platform. The assistant never sees or stores the Twitter OAuth access/refresh tokens in managed mode. Token refresh is handled transparently by the proxy.
+- **The daemon auth handler never starts local OAuth in managed mode.** When `integrationMode` is `managed`, `handleTwitterAuthStart` returns a managed-specific error code (`managed_auth_via_platform` or `managed_missing_api_key`) and never calls `orchestrateOAuthConnect`. This is a critical guardrail to prevent credential confusion.
 
 ### OAuth (recommended with X developer credentials)
 
@@ -22,11 +47,12 @@ OAuth uses the official X API v2. It is the most reliable connection method and
 
 ### Browser session (no developer credentials needed)
 
-The browser path is quick to start and useful when the user does not have X developer app credentials. It captures auth cookies from Chrome and uses them to interact with X.
+The browser path is quick to start and useful when the user does not have X developer app credentials. It captures auth cookies from Chrome and uses them to interact with X. Chrome management uses `assistant browser chrome launch` and `assistant browser chrome minimize` CLI commands internally.
 
 - Supports: **all operations** (post, reply, timeline, search, home, bookmarks, notifications, likes, followers, following, media)
 - Setup: Run `assistant x refresh` to open Chrome and capture session cookies automatically.
 - Set the strategy: `assistant config set twitter.operationStrategy browser`
+- **Session storage**: Session cookies are stored in the encrypted credential store under the key `twitter:session:cookies`. You can inspect the stored session with `assistant credentials inspect twitter:session:cookies`.
 
 ### Auto mode (default)
 
@@ -94,6 +120,11 @@ When a Twitter operation fails, follow these steps:
    - `Twitter API error (401)` — OAuth token may be expired or revoked.
    - `UnsupportedOAuthOperationError` — the requested write operation is not available via OAuth.
    - `Cannot connect to assistant` — the Vellum assistant is not running.
+   - `proxyErrorCode: "owner_credential_required"` — managed mode: the assistant owner has not connected their X account on the platform.
+   - `proxyErrorCode: "owner_only"` — managed mode: the current user is not the assistant owner.
+   - `proxyErrorCode: "auth_failure"` or `"upstream_failure"` — managed mode: platform token issue, reconnect Twitter on the platform.
+   - `proxyErrorCode: "missing_assistant_api_key"` — managed mode: the assistant is not bootstrapped.
+   - `proxyErrorCode: "missing_platform_assistant_id"` — managed mode: the assistant is not registered with the platform.
 
 2. **Explain the likely cause clearly** to the user.
 
@@ -101,6 +132,7 @@ When a Twitter operation fails, follow these steps:
    - If the browser session expired: suggest setting up OAuth for post/reply operations, or refresh the browser session with `assistant x refresh`.
    - If OAuth failed or is not configured: suggest using the browser path with `assistant config set twitter.operationStrategy browser` and `assistant x refresh`.
    - If the operation is unsupported via OAuth: explain that this write operation is not yet supported via OAuth, and suggest using the browser path with `assistant config set twitter.operationStrategy browser`.
+   - If managed mode failed with a credential or ownership error: explain the specific issue and guide the user to resolve it on the platform (connect Twitter, sign in as owner, etc.).
 
 4. **Offer concrete steps to switch:**
 
@@ -129,34 +161,44 @@ assistant x status --json
 
 ## Posting
 
-Before posting, fetch the current strategy and OAuth token:
+Before posting, check the integration mode and fetch the current strategy:
 
 ```bash
-# 1. Get the configured strategy
+# 1. Check integration mode
+MODE=$(assistant config get twitter.integrationMode)
+
+# 2. Get the configured strategy
 STRATEGY=$(assistant config get twitter.operationStrategy)
 # If not set, default to "auto"
-
-# 2. If strategy is "oauth" or "auto", get a valid OAuth token
-TOKEN=$(assistant oauth token twitter)
 ```
 
-Then post with the fetched values:
+Then post based on the mode and strategy:
 
 ```bash
+# Managed mode — route through platform proxy (no local token needed):
+assistant x post "The post text here" --strategy managed
+
 # With OAuth token (strategy is oauth or auto):
+TOKEN=$(assistant oauth token twitter)
 assistant x post "The post text here" --strategy "$STRATEGY" --oauth-token "$TOKEN"
 
 # With browser-only strategy:
 assistant x post "The post text here" --strategy browser
 ```
 
-Returns JSON with `ok`, `tweetId`, `text`, `url`, and `pathUsed` fields. Share the URL with the user so they can verify the post.
+When `twitter.integrationMode` is `managed`, always use `--strategy managed`. The platform proxy handles authentication.
+
+Returns JSON with `ok`, `tweetId`, `text`, `url`, and `pathUsed` fields. Share the URL with the user so they can verify the post. For managed mode errors, the response includes `proxyErrorCode` and `retryable` fields.
 
 ## Replying
 
-Same setup as posting — fetch strategy and token first, then:
+Same setup as posting — check integration mode and fetch strategy first, then:
 
 ```bash
+# Managed mode:
+assistant x reply <tweetUrl> "The reply text here" --strategy managed
+
+# Local OAuth or auto:
 assistant x reply <tweetUrl> "The reply text here" --strategy "$STRATEGY" --oauth-token "$TOKEN"
 ```
 

package/src/config/bundled-skills/typescript-eval/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: "TypeScript Evaluation"
-description: "Test TypeScript code snippets before persisting as skills"
-user-invocable: false
-metadata: {"vellum": {"emoji": "🧪"}}
+name: typescript-eval
+description: Test TypeScript code snippets before persisting as skills
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"🧪","vellum":{"display-name":"TypeScript Evaluation","user-invocable":false}}
 ---
 
 # TypeScript Evaluation

package/src/config/bundled-skills/vercel-token-setup/SKILL.md

@@ -1,9 +1,8 @@
 ---
-name: "Vercel Token Setup"
-description: "Set up a Vercel API token for publishing apps using browser automation"
-includes: ["browser"]
-credential-setup-for: "vercel:api_token"
-metadata: {"vellum": {"emoji": "▲"}}
+name: vercel-token-setup
+description: Set up a Vercel API token for publishing apps using browser automation
+compatibility: "Designed for Vellum personal assistants"
+metadata: {"emoji":"▲","vellum":{"display-name":"Vercel Token Setup","includes":["browser"],"credential-setup-for":"vercel:api_token"}}
 ---
 
 You are helping your user set up a Vercel API token so they can publish apps to the web.