@vellumai/assistant 0.5.10 → 0.5.12

package/src/config/bundled-skills/gmail/tools/gmail-filters.ts

@@ -26,7 +26,7 @@ export async function run(
   }
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     switch (action) {

package/src/config/bundled-skills/gmail/tools/gmail-follow-up.ts

@@ -38,7 +38,7 @@ export async function run(
   }
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     switch (action) {

package/src/config/bundled-skills/gmail/tools/gmail-forward.ts

@@ -76,7 +76,7 @@ export async function run(
   if (!forwardTo) return err("to is required.");
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     const message = await getMessage(connection, messageId, "full");

package/src/config/bundled-skills/gmail/tools/gmail-label.ts

@@ -21,7 +21,7 @@ export async function run(
 
   if (messageIds && messageIds.length > 0) {
     try {
-      const connection = await resolveOAuthConnection("integration:google", {
+      const connection = await resolveOAuthConnection("google", {
         account,
       });
       await batchModifyMessages(connection, messageIds, {
@@ -36,7 +36,7 @@ export async function run(
 
   if (messageId) {
     try {
-      const connection = await resolveOAuthConnection("integration:google", {
+      const connection = await resolveOAuthConnection("google", {
         account,
       });
       await modifyMessage(connection, messageId, {

package/src/config/bundled-skills/gmail/tools/gmail-outreach-scan.ts

@@ -56,7 +56,7 @@ export async function run(
   const query = `in:inbox -has:unsubscribe newer_than:${timeRange}`;
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     // Pipeline: fire metadata fetches for each page of IDs as they arrive

package/src/config/bundled-skills/gmail/tools/gmail-send-draft.ts

@@ -15,7 +15,7 @@ export async function run(
   if (!draftId) return err("draft_id is required.");
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     const msg = await sendDraft(connection, draftId);

package/src/config/bundled-skills/gmail/tools/gmail-sender-digest.ts

@@ -58,7 +58,7 @@ export async function run(
   const inputPageToken = input.page_token as string | undefined;
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     // Pipeline: fire metadata fetches for each page of IDs as they arrive,

package/src/config/bundled-skills/gmail/tools/gmail-trash.ts

@@ -18,7 +18,7 @@ export async function run(
   }
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     await trashMessage(connection, messageId);

package/src/config/bundled-skills/gmail/tools/gmail-unsubscribe.ts

@@ -32,7 +32,7 @@ export async function run(
   }
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     const message = await getMessage(connection, messageId, "metadata", [

package/src/config/bundled-skills/gmail/tools/gmail-vacation.ts

@@ -22,7 +22,7 @@ export async function run(
   }
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     switch (action) {

package/src/config/bundled-skills/google-calendar/SKILL.md

@@ -14,10 +14,16 @@ You are a Google Calendar assistant with full access to the user's calendar. Use
 
 Before using any Calendar tool, verify that Google Calendar is connected by attempting a lightweight call (e.g., `calendar_list_events` with a narrow date range). If the call fails with a token/authorization error:
 
-1. **Do NOT call `credential_store oauth2_connect` yourself.** You do not have valid OAuth client credentials, and fabricating a client_id will cause a "401: invalid_client" error from Google.
-2. Instead, load the **google-oauth-applescript** skill, which walks the user through creating real credentials in Google Cloud Console:
-   - Call `skill_load` with `skill: "google-oauth-applescript"` to load the dependency skill.
-3. Tell the user: _"Google Calendar isn't connected yet. I've loaded a setup guide that will walk you through connecting your Google account - it only takes a couple of minutes."_
+1. **Try connecting directly first.** Run `assistant oauth status google`. This will show whether or not the user had previously connected their google account. If so, they are ready to go.
+2. **If no connections are found:** The user needs to either use Vellum's managed google integration or set up their own google oauth app. 
+   - Call `skill_load` with `skill: "vellum-oauth-integrations"` with `provider-key: google` throughout.
+   - To use `your-own` mode, you will need to call `skill_load` with `skill: google-oauth-app-setup`. In this case:
+      - Tell the user Google account 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 Google Calendar?"
+      - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials - creating a project, enabling APIs, and connecting your account. Takes about 5 minutes.\n\n**Your emails stay under your control** — I only ever create drafts. Nothing gets sent without your explicit say-so."
+      - **confirmLabel:** "Get Started"
+      - **cancelLabel:** "Not Now"
+      - If the user confirms, briefly acknowledge (e.g., "Setting up Google Calendar now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
 
 ## Capabilities
 

package/src/config/bundled-skills/google-calendar/tools/shared.ts

@@ -13,5 +13,5 @@ export function ok(content: string): ToolExecutionResult {
 export async function getCalendarConnection(
   account?: string,
 ): Promise<OAuthConnection> {
-  return resolveOAuthConnection("integration:google", { account });
+  return resolveOAuthConnection("google", { account });
 }

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

@@ -1,6 +1,6 @@
 ---
 name: messaging
-description: Read, search, send, and manage messages across Slack, Gmail, Telegram, and other platforms
+description: Read, search, send, and manage messages across Gmail, Telegram, and other platforms
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "\U0001F4AC"
@@ -11,7 +11,9 @@ metadata:
       - "Handles credential flows -- do not improvise setup instructions"
 ---
 
-You are a unified messaging assistant with access to multiple platforms (Slack, Gmail, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
+You are a unified messaging assistant with access to multiple platforms (Gmail, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
+
+**Slack is not handled by this skill.** Slack messaging (send, read, search) is handled by the **slack** skill, which uses the Slack Web API directly via CLI. Do not use messaging tools with `platform: "slack"`.
 
 ## External Identity
 
@@ -28,19 +30,21 @@ Do not offer AgentMail as an option or mention it unless the user specifically a
 ## Communication Style
 
 - **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox - that's obviously what they want.
-- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" - not "the OAuth2 access token for integration:google has expired."
+- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" - not "the OAuth2 access token for google has expired."
 - **Show progress.** When running a tool that scans many emails, tell the user what you're doing: "Scanning your inbox for clutter..." Don't go silent.
 - **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do - just do it and narrate lightly.
 
 When a platform is connected (auth test succeeds), always use the messaging API tools for that platform. Never fall back to browser automation, shell commands (bash, curl), or any other approach for operations that messaging tools can handle. The messaging tools handle authentication internally - never try to access tokens or call APIs directly. Browser automation is only appropriate for initial credential setup (OAuth consent screens), not for day-to-day messaging operations.
 
+**Exception: Slack.** Slack messaging should use the Slack Web API directly via CLI, not messaging tools. See the **slack** skill for details.
+
 ## Connection Setup
 
 Before using any messaging tool, verify that the platform is connected by calling `messaging_auth_test` with the appropriate `platform` parameter. If the call fails with a token/authorization error, follow the steps below.
 
 ### Public Ingress (required for Telegram)
 
-Telegram setup requires a publicly reachable URL for webhook delivery. The **public-ingress** skill handles ngrok tunnel setup and persists the URL as `ingress.publicBaseUrl`. Slack uses Socket Mode and does not require public ingress. Gmail on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the google-oauth-applescript skill) handles public ingress internally when needed.
+Telegram setup requires webhook routing, but it does **not** always require ngrok. Before suggesting public ingress for Telegram, check managed callback availability with `assistant platform status --json`. If that reports `containerized: true` with a non-empty `assistantId` and `available: true`, use the platform callback route flow and do not prompt for ngrok. Only use the **public-ingress** skill for local assistants that genuinely need a public gateway URL. Slack uses Socket Mode and does not require public ingress. Gmail on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the google-oauth-app-setup skill) handles public ingress internally when needed.
 
 ### Email Connection Flow
 
@@ -52,30 +56,26 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 
 ### Gmail
 
-1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. The tool auto-fills Google's OAuth endpoints and looks up any previously stored client credentials - so this single call may be all that's needed.
-2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Load the **google-oauth-applescript** skill:
-   - Call `skill_load` with `skill: "google-oauth-applescript"` to load the dependency skill.
+1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "google"`. The tool auto-fills Google's OAuth endpoints and looks up any previously stored client credentials - so this single call may be all that's needed.
+2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Load the **google-oauth-app-setup** skill:
+   - Call `skill_load` with `skill: "google-oauth-app-setup"` to load the dependency skill.
    - 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 few pages in your browser and walk you through setting up Google Cloud credentials - creating a project, enabling APIs, and connecting your account. Takes about 5 minutes."
      - **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.
+3. **If the user provides a client_id directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "google"`, and `client_id: "<their value>"`. Include `client_secret` too if they provide one. Everything else is auto-filled.
 
 ### Slack
 
-Slack connects via Socket Mode using a bot token and app-level token (not OAuth). Load the **slack-app-setup** skill, which guides the user through creating a Slack app from a pre-configured manifest, collecting tokens securely, and connecting the bot to their workspace:
-
-- Call `skill_load` with `skill: "slack-app-setup"` to load the dependency skill.
-- Tell the user Slack isn't connected yet and briefly explain what the setup involves, then follow the skill's guided flow.
-
-The slack-app-setup skill handles: manifest-driven app creation, app token and bot token collection via secure prompt (never accept tokens pasted in plaintext chat), and Slack connection setup through the same settings handler used by the Settings UI. That handler validates the bot token, stores workspace metadata, and activates Socket Mode. The skill also covers optional identity verification.
+Slack is **not** handled by this skill. For Slack setup, load the **slack-app-setup** skill directly. For Slack messaging, use the **slack** skill which accesses the Slack Web API via CLI.
 
 ### Telegram
 
-Telegram uses a bot token (not OAuth). Load the **telegram-setup** skill (which depends on **public-ingress** for the webhook URL) which automates the full setup:
+Telegram uses a bot token (not OAuth). Load the **telegram-setup** skill, which uses a managed platform callback route in containerized deployments and falls back to **public-ingress** locally when needed:
 
+- First run `assistant platform status --json`. If it shows managed callback routing is available, tell the user you will use the platform callback route and skip ngrok/public-ingress.
 - Call `skill_load` with `skill: "telegram-setup"` to load the dependency skill.
 - Tell the user: _"I've loaded a setup guide for Telegram. It will walk you through connecting a Telegram bot to your assistant."_
 
@@ -96,7 +96,7 @@ The guardian-verify-setup skill handles the full outbound verification flow for
 When a messaging tool fails with a token or authorization error:
 
 1. **Try to reconnect silently.** Call `credential_store` with `action: "oauth2_connect"` and the appropriate `service`. This often resolves expired tokens automatically.
-2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately follow the connection setup flow for that platform (e.g., install and load **google-oauth-applescript** for Gmail). The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately follow the connection setup flow for that platform (e.g., install and load **google-oauth-app-setup** for Gmail). The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
 3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the messaging tools can't do it, the reconnection flow is the answer.
 4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
 
@@ -109,10 +109,10 @@ When a messaging tool fails with a token or authorization error:
 
 ## Capabilities
 
-### Universal (Slack, Gmail)
+### Universal (Gmail)
 
 - **Auth Test**: Verify connection and show account info
-- **List Conversations**: Show channels, inboxes, DMs with unread counts
+- **List Conversations**: Show inboxes, DMs with unread counts
 - **Read Messages**: Read message history from a conversation
 - **Search**: Search messages with platform-appropriate query syntax
 - **Send / Reply**: Send a message or reply in a thread (via `thread_id`). High risk - requires user approval.
@@ -120,7 +120,7 @@ When a messaging tool fails with a token or authorization error:
 
 ### Telegram
 
-Telegram is supported as a messaging provider with limited capabilities compared to Slack and Gmail due to Bot API constraints:
+Telegram is supported as a messaging provider with limited capabilities compared to Gmail due to Bot API constraints:
 
 - **Send**: Send a message to a known chat ID (high risk - requires user approval)
 - **Auth Test**: Verify bot token and show bot info
@@ -136,29 +136,6 @@ 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.
 
-### Slack-specific
-
-- **Add Reaction**: Add an emoji reaction to a message
-- **Leave Channel**: Leave a Slack channel
-- **Edit Message**: `slack_edit_message` - edit a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`) from the original send response. High risk - requires confidence score.
-- **Delete Message**: `slack_delete_message` - delete a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`). High risk - requires confidence score. This is irreversible.
-
-When sending a Slack message, retain the `ts` (message timestamp) from the send response - it is needed to edit or delete that message later. Only messages sent by the assistant's bot can be edited or deleted.
-
-## Slack Search Syntax
-
-When searching Slack, the query is passed directly to Slack's search API:
-
-| Operator       | Example             | What it finds                  |
-| -------------- | ------------------- | ------------------------------ |
-| `from:`        | `from:@alice`       | Messages from a specific user  |
-| `in:`          | `in:#general`       | Messages in a specific channel |
-| `has:`         | `has:link`          | Messages containing links      |
-| `before:`      | `before:2024-01-01` | Messages before a date         |
-| `after:`       | `after:2024-01-01`  | Messages after a date          |
-| `has:reaction` | `has:reaction`      | Messages with reactions        |
-| `has:star`     | `has:star`          | Starred messages               |
-
 ## Notifications vs Messages
 
 - `send_notification` is provided by the **notifications** skill (always active) -- use it when the user asks for an alert/notification (for example "send this as a desktop notification").

package/src/config/bundled-skills/messaging/TOOLS.json

@@ -11,7 +11,7 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform to test (e.g. \"slack\", \"gmail\"). Auto-detected if only one is connected."
+            "description": "Platform to test (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
@@ -36,7 +36,7 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"slack\", \"gmail\"). Auto-detected if only one is connected."
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
@@ -73,7 +73,7 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"slack\", \"gmail\"). Auto-detected if only one is connected."
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
@@ -111,7 +111,7 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"slack\", \"gmail\"). Auto-detected if only one is connected."
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
@@ -145,7 +145,7 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"slack\", \"gmail\"). Auto-detected if only one is connected."
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
@@ -202,7 +202,7 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"slack\", \"gmail\"). Auto-detected if only one is connected."
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
@@ -236,7 +236,7 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"slack\", \"gmail\"). Auto-detected if only one is connected."
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
@@ -248,7 +248,7 @@
           },
           "query_filter": {
             "type": "string",
-            "description": "Optional search filter (e.g. 'to:alice@example.com' for Gmail, 'from:@me' for Slack)"
+            "description": "Optional search filter (e.g. 'to:alice@example.com' for Gmail)"
           },
           "activity": {
             "type": "string",
@@ -274,7 +274,7 @@
           },
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"slack\", \"gmail\"). Required for create/list."
+            "description": "Platform (e.g. \"gmail\"). Required for create/list. Slack is not supported — use the Slack Web API directly."
           },
           "conversation_id": {
             "type": "string",

package/src/config/bundled-skills/messaging/tools/messaging-analyze-style.ts

@@ -50,7 +50,7 @@ function upsertMemoryItem(opts: {
           Math.max(existing.importance ?? 0, opts.importance),
         ),
         lastSeenAt: now,
-        sourceType: "extraction",
+        sourceType: existing.sourceType === "tool" ? "tool" : "extraction",
       })
       .where(eq(memoryItems.id, existing.id))
       .run();

package/src/config/bundled-skills/messaging/tools/messaging-send.ts

@@ -9,7 +9,6 @@ import {
   listMessages,
 } from "../../../../messaging/providers/gmail/client.js";
 import { buildMultipartMime } from "../../../../messaging/providers/gmail/mime-builder.js";
-import type { OAuthConnection } from "../../../../oauth/connection.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -57,7 +56,11 @@ export async function run(
 
     // Gmail: create a draft instead of sending directly
     if (provider.id === "gmail") {
-      const gmailConn = conn as OAuthConnection;
+      if (!conn)
+        return err(
+          "Gmail requires an OAuth connection — is the account connected?",
+        );
+      const gmailConn = conn;
       // Reply mode: thread_id provided - create a threaded draft with reply-all recipients
       if (threadId) {
         // Fetch thread messages to extract recipients and threading headers

package/src/config/bundled-skills/messaging/tools/shared.ts

@@ -126,17 +126,16 @@ export async function resolveProvider(
 }
 
 /**
- * Resolve an OAuthConnection (or empty string for non-OAuth providers)
- * for the given messaging provider.
+ * Resolve an OAuthConnection for the given messaging provider.
  *
- * Non-OAuth providers (e.g. Telegram) use isConnected() and don't need
- * tokens - they receive an empty string which the string overload handles.
+ * Returns undefined for providers that manage credentials internally
+ * (e.g. Telegram bot tokens, Slack Socket Mode bot tokens).
  */
 export async function getProviderConnection(
   provider: MessagingProvider,
   account?: string,
-): Promise<OAuthConnection | string> {
+): Promise<OAuthConnection | undefined> {
   if (provider.resolveConnection) return provider.resolveConnection(account);
-  if (await provider.isConnected?.()) return "";
+  if (await provider.isConnected?.()) return undefined;
   return resolveOAuthConnection(provider.credentialService, { account });
 }

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

@@ -37,4 +37,4 @@ Conversation grouping is handled by the LLM-powered decision engine, not by any
 ## Important
 
 - Do **NOT** use AppleScript `display notification` or other OS-level notification commands for assistant-managed alerts. Always use `send_notification`.
-- For sending rich content (digests, summaries, reports) to a specific chat or email destination, use the messaging skill's `messaging_send` instead. The decision engine rewrites `send_notification` content into short alerts, which strips rich formatting.
+- For sending rich content (digests, summaries, reports) to a specific chat or email destination, use the appropriate platform's API directly. For Gmail, use `messaging_send`. For Slack, use the Slack Web API directly (see the **slack** skill). The decision engine rewrites `send_notification` content into short alerts, which strips rich formatting.

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

@@ -163,9 +163,9 @@ Scheduled messages run without user interaction. If the task produces output tha
 
 Choose the right delivery tool based on the content:
 
-- **Rich content** (digests, summaries, reports): Use `messaging_send` with the target platform and conversation ID. This preserves the full content and posts directly.
+- **Rich content** (digests, summaries, reports): For Gmail, use `messaging_send` with the target platform and conversation ID. For Slack, use the Slack Web API directly via CLI (`chat.postMessage`). This preserves the full content and posts directly.
 - **Short alerts** (status updates, completion notices): Use `send_notification` to let the notification router pick the best channel. Note: the router's decision engine rewrites content into short alerts, so it is not suitable for rich content.
 
 Example schedule message for a Slack digest:
 
-> "Scan my Slack channels for the last 24 hours using slack_scan_digest, then use messaging_send with platform 'slack' and conversation_id 'C0A7STRJ4G5' to post the summary to #alex-agent-messages."
+> "Scan my Slack channels for the last 24 hours using the Slack Web API via bash (network_mode: proxied, credential_ids: ['slack_channel/bot_token']), then post the summary to #alex-agent-messages (C0A7STRJ4G5)."

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

@@ -1,6 +1,6 @@
 ---
 name: settings
-description: Manage assistant voice, avatar, and system settings
+description: Manage assistant voice, avatar (set, remove, view, show), and system settings
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "\u2699\uFE0F"
@@ -8,7 +8,7 @@ metadata:
     display-name: "Settings"
 ---
 
-Tools for managing assistant settings: voice configuration (TTS voice, PTT activation key, conversation timeout), avatar management, system settings navigation, and in-app settings tab navigation.
+Tools for managing assistant settings: voice configuration (TTS voice, PTT activation key, conversation timeout), avatar management (set, remove, view/show current avatar), system settings navigation, and in-app settings tab navigation.
 
 ## Avatar
 
@@ -21,4 +21,6 @@ The tool copies the image to the canonical location (`data/avatar/avatar-image.p
 
 When the user asks to remove, clear, or reset their avatar, use the `remove_avatar` tool. It deletes only the custom image and preserves the native character traits so the character avatar is restored automatically.
 
-**Do NOT use `bash`, `cp`, or `rm` for avatar operations** — always use `set_avatar` / `remove_avatar` so the app is properly notified and character traits are preserved.
+When the user asks to see, view, or show their current avatar, use the `get_avatar` tool. It returns the avatar image inline. If no custom image exists but character traits are set, it regenerates the static PNG from traits and returns that.
+
+**Do NOT use `bash`, `cp`, `rm`, or `file_read` for avatar operations** — always use `set_avatar` / `remove_avatar` / `get_avatar` so the app is properly notified and character traits are preserved.

package/src/config/bundled-skills/settings/TOOLS.json

@@ -124,6 +124,23 @@
       },
       "executor": "tools/avatar-remove.ts",
       "execution_target": "sandbox"
+    },
+    {
+      "name": "get_avatar",
+      "description": "Read and return the current avatar image so the user can see it. Use this when the user asks to see, view, or show their avatar. Returns the image inline — do NOT copy the file or use bash commands.",
+      "category": "system",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of what you are doing, shown to the user as a status update."
+          }
+        }
+      },
+      "executor": "tools/avatar-get.ts",
+      "execution_target": "sandbox"
     }
   ]
 }

package/src/config/bundled-skills/settings/tools/avatar-get.ts

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { writeTraitsAndRenderAvatar } from "../../../../avatar/traits-png-sync.js";
+import { readImageFile } from "../../../../tools/shared/filesystem/image-read.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import { getWorkspaceDir } from "../../../../util/platform.js";
+
+export async function run(
+  _input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const avatarPath = join(
+    getWorkspaceDir(),
+    "data",
+    "avatar",
+    "avatar-image.png",
+  );
+
+  if (!existsSync(avatarPath)) {
+    // Check for native character traits and regenerate the static PNG
+    const traitsPath = join(
+      getWorkspaceDir(),
+      "data",
+      "avatar",
+      "character-traits.json",
+    );
+    if (existsSync(traitsPath)) {
+      try {
+        const traits = JSON.parse(readFileSync(traitsPath, "utf-8"));
+        const result = writeTraitsAndRenderAvatar(traits);
+        if (result.ok && existsSync(avatarPath)) {
+          return readImageFile(avatarPath);
+        }
+      } catch {
+        // Fall through to default message
+      }
+    }
+    return {
+      content:
+        "No avatar is currently set — no custom image and no character traits found.",
+      isError: false,
+    };
+  }
+
+  return readImageFile(avatarPath);
+}

package/src/config/bundled-skills/settings/tools/avatar-remove.ts

@@ -10,6 +10,7 @@ import type {
 } from "../../../../tools/types.js";
 import { getLogger } from "../../../../util/logger.js";
 import { getWorkspaceDir } from "../../../../util/platform.js";
+import { updateIdentityAvatarSection } from "./identity-avatar.js";
 
 const log = getLogger("avatar-remove");
 
@@ -50,6 +51,12 @@ export async function run(
       log.warn({ err }, "Failed to publish avatar_updated event");
     });
 
+  // Update IDENTITY.md to reflect the avatar was removed.
+  updateIdentityAvatarSection(
+    "Default character avatar (no custom image set)",
+    log,
+  );
+
   log.info("Custom avatar removed, reverting to character avatar");
 
   return {

package/src/config/bundled-skills/settings/tools/avatar-update.ts

@@ -10,6 +10,7 @@ import type {
 } from "../../../../tools/types.js";
 import { getLogger } from "../../../../util/logger.js";
 import { getWorkspaceDir } from "../../../../util/platform.js";
+import { updateIdentityAvatarSection } from "./identity-avatar.js";
 
 const log = getLogger("avatar-update");
 
@@ -71,10 +72,14 @@ export async function run(
       log.warn({ err }, "Failed to publish avatar_updated event");
     });
 
+  // Clear any stale avatar description from IDENTITY.md so the assistant
+  // is prompted to describe the new image on next read.
+  updateIdentityAvatarSection(null, log);
+
   log.info({ avatarPath, source: resolvedSource }, "Avatar updated");
 
   return {
-    content: `Avatar updated from ${sourcePath}. The app will refresh automatically.`,
+    content: `Avatar updated from ${sourcePath}. The app will refresh automatically. The avatar description in IDENTITY.md has been cleared — describe what the new avatar looks like by updating the ## Avatar section in IDENTITY.md with a plain-text description (not an image link).`,
     isError: false,
   };
 }