@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

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

@@ -33,9 +33,9 @@ Write and edit long-form documents using the built-in rich text editor. Document
 
 This is the default path when the user asks you to write something.
 
-1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble. Anything you pass as `initial_content` is saved right then, so the first `document_update` must start with the next chunk rather than repeating it.
 2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, _italic_, code blocks, tables, lists, blockquotes as appropriate.
-3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. When you are streaming into the document you just created, `surface_id` is optional — omit it and pass only `content`, and the update targets that document. The user experiences real-time content appearing as you write.
+3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. Each append carries ONLY that chunk: content already in the document is committed, and resending it would print it twice. When you are streaming into the document you just created, `surface_id` is optional: omit it and pass only `content`, and the update targets that document. The user experiences real-time content appearing as you write.
 
 ### Recovering from a failed update
 

package/src/config/bundled-skills/document-editor/TOOLS.json

@@ -33,7 +33,7 @@
           },
           "initial_content": {
             "type": "string",
-            "description": "Initial Markdown content to populate the editor (optional)"
+            "description": "Initial Markdown content to populate the editor (optional). It is saved as soon as the document is created, so the first document_update append must start with the NEXT chunk, never with this text again."
           }
         }
       },
@@ -54,7 +54,7 @@
           },
           "content": {
             "type": "string",
-            "description": "Markdown content to set or append"
+            "description": "Markdown content to set or append. In append mode, send only the new chunk: whatever is already in the document, including document_create's initial_content, is committed and must not be resent."
           },
           "mode": {
             "type": "string",

package/src/config/bundled-skills/image-studio/SKILL.md

@@ -69,10 +69,11 @@ Edits on large photos are slow (1 to 2 minutes). If the tool reports a timeout (
 
 ## Output handling
 
-Images return as inline content blocks in the tool result; they are not written to disk automatically.
+Each generated image is saved into the workspace under `media/generated/` and the tool result lists the saved paths. The images also come back as inline content blocks so you can judge the result before presenting it.
 
-- If the user just wants to see the image, the inline result is enough.
-- If the user wants a file or you need to iterate on the result, save it to disk and deliver it through the conversation's attachment mechanism.
+- Present an image to the user by embedding its saved path in your reply: `![short description](vellum://workspace/media/generated/<file>.png)`. The app renders it inline where your text refers to it, and chat channels (Slack, Telegram, WhatsApp) deliver it as a native image upload.
+- If you do not embed it, the image is still auto-attached to your reply as a file, so it is never lost. Prefer embedding: an attachment chip at the end of the message is a worse presentation than the image inline.
+- To iterate on a result, pass its saved path via `source_paths` with `mode: "edit"`.
 
 ## Error handling
 
@@ -88,4 +89,4 @@ Do NOT rephrase the prompt and retry on the same model, even if the error sugges
 
 ## Complete when
 
-The tool has returned at least one image and the user can see it: either the inline result in chat or an attached saved file. An error report counts as complete only after the retry path in Error handling has been exhausted.
+The tool has returned at least one image and your reply presents it to the user, preferably as an inline `![description](vellum://workspace/...)` embed of the saved path. An error report counts as complete only after the retry path in Error handling has been exhausted.

package/src/config/bundled-skills/image-studio/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "media_generate_image",
-      "description": "Generate or edit images using AI. Supports text-to-image generation and image editing with source images.",
+      "description": "Generate or edit images using AI. Supports text-to-image generation and image editing with source images. Saves results into the workspace and returns their file paths; present a result to the user by embedding its path in your reply as ![description](vellum://workspace/<path>).",
       "category": "media",
       "risk": "low",
       "input_schema": {

package/src/config/bundled-skills/image-studio/tools/media-generate-image.ts

@@ -1,3 +1,6 @@
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
 import {
   resolveImageGenCredentials,
   resolveImageGenRouting,
@@ -19,6 +22,87 @@ import type {
 } from "../../../../tools/types.js";
 import { getConfig } from "../../../loader.js";
 
+/** Workspace-relative directory where generated images are saved. */
+const GENERATED_MEDIA_DIR = "media/generated";
+
+/**
+ * Derive a filesystem-safe base name for a generated image from its title
+ * (when the provider returns one) or the generation prompt.
+ */
+function imageFileSlug(title: string | undefined, prompt: string): string {
+  const base = (title?.trim() || prompt)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, 48)
+    .replace(/-+$/, "");
+  return base || "image";
+}
+
+/** Upper bound on filename-collision retries per image. */
+const MAX_FILENAME_ATTEMPTS = 1000;
+
+/**
+ * Save generated images under `media/generated/` in the workspace so the
+ * model can reference them by path (inline embeds, edit-mode iteration).
+ * Each target path is validated through `sandboxPolicy` so a symlinked
+ * directory cannot redirect the write outside the workspace, and files are
+ * created exclusively (`wx`) so concurrent generations cannot claim the
+ * same filename. Returns workspace-relative paths for the images written
+ * before any failure; a failure stops the loop and is reported, not
+ * thrown, so the inline content blocks still reach the model.
+ */
+function saveGeneratedImages(
+  images: Array<{ mimeType: string; dataBase64: string; title?: string }>,
+  prompt: string,
+  workingDir: string,
+): { savedPaths: string[]; saveError?: string } {
+  const savedPaths: string[] = [];
+  try {
+    for (const img of images) {
+      const ext = img.mimeType.split("/")[1] ?? "png";
+      const slug = imageFileSlug(img.title, prompt);
+      let written = false;
+      for (let attempt = 1; attempt <= MAX_FILENAME_ATTEMPTS; attempt++) {
+        const relPath =
+          attempt === 1
+            ? `${GENERATED_MEDIA_DIR}/${slug}.${ext}`
+            : `${GENERATED_MEDIA_DIR}/${slug}-${attempt}.${ext}`;
+        const pathCheck = sandboxPolicy(join(workingDir, relPath), workingDir, {
+          mustExist: false,
+        });
+        if (!pathCheck.ok) {
+          throw new Error(pathCheck.error);
+        }
+        mkdirSync(dirname(pathCheck.resolved), { recursive: true });
+        try {
+          writeFileSync(
+            pathCheck.resolved,
+            Buffer.from(img.dataBase64, "base64"),
+            { flag: "wx" },
+          );
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+            continue;
+          }
+          throw error;
+        }
+        savedPaths.push(relPath);
+        written = true;
+        break;
+      }
+      if (!written) {
+        throw new Error(
+          `Could not find a free filename for "${slug}.${ext}" after ${MAX_FILENAME_ATTEMPTS} attempts.`,
+        );
+      }
+    }
+  } catch (error) {
+    return { savedPaths, saveError: (error as Error).message };
+  }
+  return { savedPaths };
+}
+
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -127,7 +211,24 @@ export async function run(
     });
 
     const imageCount = result.images.length;
+    const { savedPaths, saveError } = saveGeneratedImages(
+      result.images,
+      prompt,
+      context.workingDir,
+    );
+
     let content = `Generated ${imageCount} image${imageCount !== 1 ? "s" : ""} using ${result.resolvedModel}.`;
+    if (savedPaths.length === 1) {
+      content += ` Saved to ${savedPaths[0]}.`;
+    } else if (savedPaths.length > 1) {
+      content += ` Saved to:\n${savedPaths.map((p) => `- ${p}`).join("\n")}`;
+    }
+    if (savedPaths.length > 0) {
+      content += `\n\nShow the user an image by embedding it in your reply: ![description](vellum://workspace/${savedPaths[0]}). To iterate on a result, pass its saved path via source_paths with mode "edit".`;
+    }
+    if (saveError) {
+      content += `\n\nCould not save to the workspace (${saveError}); the image${imageCount !== 1 ? "s" : ""} will be attached to your reply automatically instead.`;
+    }
     if (result.text) {
       content += `\n\n${result.text}`;
     }

package/src/config/bundled-skills/media-processing/services/preprocess.ts

@@ -19,6 +19,7 @@ import {
   updateProcessingStage,
 } from "../../../../persistence/media-store.js";
 import { resolveBatchTranscriber } from "../../../../providers/speech-to-text/resolve.js";
+import type { BatchTranscriber } from "../../../../stt/types.js";
 import { silentlyWithLog } from "../../../../util/silently.js";
 import {
   FFMPEG_PALETTE_TIMEOUT_MS,
@@ -459,10 +460,19 @@ export async function preprocessForAsset(
     const allFramePaths: string[] = [];
 
     // Resolve the STT transcriber once for all segments to avoid repeated
-    // credential lookups in the per-segment loop.
-    const transcriber = options.includeAudio
-      ? await resolveBatchTranscriber()
-      : null;
+    // credential lookups in the per-segment loop. A resolver failure degrades
+    // to transcript-less segments like an absent provider does, reporting the
+    // reason on the progress stream rather than killing the whole run.
+    let transcriber: BatchTranscriber | null = null;
+    if (options.includeAudio) {
+      try {
+        transcriber = await resolveBatchTranscriber();
+      } catch (err) {
+        onProgress?.(
+          `Audio transcription unavailable: ${(err as Error).message}\n`,
+        );
+      }
+    }
 
     const scaleFilter = `scale='if(gt(iw,ih),-1,${config.shortEdge})':'if(gt(iw,ih),${config.shortEdge},-1)'`;
 

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "voice_config_update",
-      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, google-gemini, openai-whisper, xai. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (daemon route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 50 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT. Changes persist to services.stt / services.tts config and take effect immediately.",
+      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai. deepgram-flux is streaming-only: it serves live speech (voice mode, dictation) but cannot transcribe audio files or voice messages, so do not recommend it when the user wants file transcription. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (assistant route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 50 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively and deepgram-flux runs an English-only model, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT, and deepgram-flux shares it too. Changes persist to services.stt / services.tts config and take effect immediately.",
       "category": "system",
       "risk": "low",
       "input_schema": {
@@ -20,10 +20,10 @@
               "tts_provider",
               "tts_voice_id"
             ],
-            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it). Deepgram shares one API key across TTS and STT."
+            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it; deepgram-flux is English-only and ignores it). Deepgram shares one API key across TTS and STT, and deepgram-flux uses that same key."
           },
           "value": {
-            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, google-gemini, openai-whisper, xai. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 50 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
+            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai; deepgram-flux serves live speech only and cannot transcribe files. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 50 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
           }
         }
       },

package/src/config/bundled-skills/settings/tools/navigate-settings-tab.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import type { ToolContext } from "../../../../tools/types.js";
+import { run } from "./navigate-settings-tab.js";
+
+let sentMessages: Array<{ type: string; [key: string]: unknown }> = [];
+
+function makeContext(overrides?: Partial<ToolContext>): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "conv-xyz",
+    trustClass: "guardian",
+    sendToClient: (msg) => {
+      sentMessages.push(msg);
+    },
+    ...overrides,
+  };
+}
+
+describe("navigate_settings_tab tool", () => {
+  beforeEach(() => {
+    sentMessages = [];
+  });
+
+  test("navigates to the Voice tab and hints the inline picker", async () => {
+    const result = await run({ tab: "Voice" }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages).toEqual([{ type: "navigate_settings", tab: "Voice" }]);
+    expect(result.content).toStartWith("Opened settings to the Voice tab.");
+    expect(result.content).toContain(
+      'ui_show { surface_type: "voice_picker", data: {} }',
+    );
+  });
+
+  test("leaves a non-Voice tab's result unchanged", async () => {
+    const result = await run({ tab: "Billing" }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages).toEqual([
+      { type: "navigate_settings", tab: "Billing" },
+    ]);
+    expect(result.content).toBe("Opened settings to the Billing tab.");
+    expect(result.content).not.toContain("voice_picker");
+  });
+
+  test("resolves legacy tab aliases without hinting", async () => {
+    const result = await run({ tab: "Archived Conversations" }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages).toEqual([
+      { type: "navigate_settings", tab: "Archive" },
+    ]);
+    expect(result.content).toBe("Opened settings to the Archive tab.");
+    expect(result.content).not.toContain("voice_picker");
+  });
+
+  test("rejects an unknown tab without navigating", async () => {
+    const result = await run({ tab: "Telepathy" }, makeContext());
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('unknown tab "Telepathy"');
+    expect(sentMessages).toEqual([]);
+  });
+});

package/src/config/bundled-skills/settings/tools/navigate-settings-tab.ts

@@ -2,6 +2,7 @@ import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
+import { voicePickerHint } from "./shared.js";
 
 const SETTINGS_TABS = [
   "General",
@@ -23,6 +24,10 @@ const LEGACY_TAB_ALIASES: Record<string, SettingsTab> = {
   "Archived Conversations": "Archive",
 };
 
+const VOICE_TAB_PICKER_HINT = voicePickerHint(
+  "which puts the picker in the conversation without navigating away. Navigating here is right only when the user explicitly asked to open Settings.",
+);
+
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -45,8 +50,9 @@ export async function run(
     });
   }
 
+  const opened = `Opened settings to the ${tab} tab.`;
   return {
-    content: `Opened settings to the ${tab} tab.`,
+    content: tab === "Voice" ? `${opened} ${VOICE_TAB_PICKER_HINT}` : opened,
     isError: false,
   };
 }

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

@@ -0,0 +1,16 @@
+/**
+ * Shared helpers for the settings skill's tool executors.
+ */
+
+/**
+ * Steer the model back to the inline voice picker.
+ *
+ * Both settings tools a "change my voice" request can land on (the Voice tab
+ * navigation and a managed `tts_voice_id` write) end by naming the picker, so
+ * the invocation itself lives here: one edit keeps both tools teaching the same
+ * call. Each caller supplies its own tail, because the reason the picker is
+ * better differs by the tool the model just reached for.
+ */
+export function voicePickerHint(tail: string): string {
+  return `Next time the user wants to change or hear a voice, prefer \`ui_show { surface_type: "voice_picker", data: {} }\`, ${tail}`;
+}

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

@@ -19,6 +19,7 @@ import {
 } from "../../../loader.js";
 import { VALID_CONVERSATION_TIMEOUTS } from "../../../schemas/elevenlabs.js";
 import { VALID_STT_PROVIDERS } from "../../../schemas/stt.js";
+import { voicePickerHint } from "./shared.js";
 
 /**
  * Valid voice config settings and their UserDefaults key mappings.
@@ -187,6 +188,19 @@ const STT_LANGUAGE_ALIASES: Record<
   "code-switching": "multi",
 };
 
+/**
+ * Same steer `navigate_settings_tab` puts on the Voice tab, applied to the
+ * strongest competing affordance: this tool's description coaches the model to
+ * read the managed catalog and set `tts_voice_id` itself, which is exactly the
+ * "assistant names voices in prose" outcome the inline picker exists to
+ * replace. Managed only, because that is the catalog the picker renders. The
+ * write still happens and the result stays non-error; this only redirects the
+ * next request.
+ */
+const MANAGED_VOICE_PICKER_HINT = voicePickerHint(
+  "which lets them hear and pick from the managed catalog in the conversation. Set the id here only when the user named a specific voice.",
+);
+
 function validateSetting(
   setting: string,
   value: unknown,
@@ -530,10 +544,14 @@ export async function run(
     AUTO_DETECT_STT_PROVIDERS.has(activeSttProviderId)
       ? ` Note: the configured STT provider (${activeSttProviderId}) auto-detects the spoken language natively and ignores this setting.`
       : "";
+  const pickerNote =
+    setting === "tts_voice_id" && activeTtsProviderId === "vellum"
+      ? ` ${MANAGED_VOICE_PICKER_HINT}`
+      : "";
   return {
     content: `${friendlyName} updated to ${JSON.stringify(
       validation.coerced,
-    )}.${broadcastNote}${autoDetectNote}`,
+    )}.${broadcastNote}${autoDetectNote}${pickerNote}`,
     isError: false,
   };
 }

package/src/config/bundled-skills/skill-management/TOOLS.json

@@ -40,12 +40,12 @@
           "includes": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Optional list of child skill IDs that this skill includes (metadata only, no auto-activation)."
+            "description": "Optional list of child skill IDs this skill composes. When this skill is loaded via skill_load, each child's body is inlined after the parent's and the child's tools are projected, so the parent can rely on the child's procedure without re-stating it. Does not affect which skills get selected for a turn."
           },
           "activation_hints": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Optional trigger phrases describing the situations where this skill should activate, phrased as the observed intent (e.g. \"user asks to deploy staging\"). Surfaced in memory as a \"Use when: …\" clause so the skill is retrievable by intent, not just by name."
+            "description": "Required. 1-4 short trigger phrases describing the situations where this skill should activate, phrased as the observed intent (e.g. \"user asks to deploy staging\"). Surfaced in memory as a \"Use when: …\" clause so the skill is retrievable by intent, not just by name. Scaffolding rewrites the whole SKILL.md, so an overwrite must pass the hints the skill should keep, revised if the procedure changed."
           },
           "avoid_when": {
             "type": "array",
@@ -79,7 +79,13 @@
             "description": "Deprecated no-op compatibility field. Skills are discovered from top-level SKILL.md files."
           }
         },
-        "required": ["skill_id", "name", "description", "body_markdown"]
+        "required": [
+          "skill_id",
+          "name",
+          "description",
+          "body_markdown",
+          "activation_hints"
+        ]
       },
       "executor": "tools/scaffold-managed.ts",
       "execution_target": "host"

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

@@ -12,7 +12,7 @@ metadata:
       - "Delegate a self-contained research or implementation task off the main thread"
       - "Multiple agents at once, or a context-inheriting fork"
     avoid-when:
-      - "Task is small enough to do inline (single tool call, quick lookup)"
+      - "Task is small enough to do inline (a handful of tool calls, quick lookups or reads)"
       - "User wants Claude Code or Codex — use the acp skill instead"
 ---
 
@@ -37,7 +37,7 @@ There are three subagent types. Pick one with two questions: **does it need to c
 |---|---|---|---|---|
 | `researcher` | No | No | `web_search`, `web_fetch`, `file_read`, `file_list`, `code_search`, `recall`, `skill_execute`, `notify_parent` | Web research, codebase exploration, reading documentation, root-cause investigation, reviewing an approach against the code |
 | `builder` | Yes | No | Your whole tool surface, unrestricted: shell, file writes and edits, and every connector, MCP, and browser tool you can reach | Code changes, file output, build/test runs, anything that must run a command or act on an outside system |
-| `advisor` | No | Yes | Read-only fact checking in the workspace: `file_read`, `file_list`, `code_search` | Read-only senior-advisor consult. Runs on a stronger model, inherits full parent context, and BLOCKS until it returns guidance |
+| `advisor` | No | Yes | Read-only fact checking in the workspace: `file_read`, `file_list`, `code_search` | Read-only senior-advisor consult. Reads the brief you write in `objective`, runs on a stronger model, and BLOCKS until it returns guidance |
 
 Both background types can call `notify_parent` for mid-run communication with the parent.
 
@@ -65,17 +65,23 @@ The other contracts: `output_contract: "artifact"` tells a `builder` that the de
 
 ## Consulting the Advisor
 
-The `advisor` is the one type you spawn on your own judgment, unprompted: you do NOT wait for the user to ask for a subagent. The background types (`researcher`, `builder`) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it. The advisor is different: proactively consult it whenever the conditions below are met.
+The `advisor` is the one type you may spawn on your own judgment, unprompted: you do not wait for the user to ask for a subagent. The background types (`researcher`, `builder`) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it.
 
-Orient yourself first (read the relevant files, understand the task), then consult the advisor:
+A consult is expensive (a stronger model reviews your brief and answers), so reserve it for moments where a second perspective can genuinely change the outcome. Most tasks need no consult at all: a routine task with an obvious approach does not require sign-off, before you start or after you finish. Orient yourself first (read the relevant files, understand the task), then consult the advisor:
 
-- **Before you commit to an approach and start building** — to shape a plan when you don't have one, or to pressure-test and sharpen a plan you've already drafted.
+- **Before you commit to an approach on a consequential or ambiguous task**: the design space is wide, a wrong approach would be costly to unwind, or requirements pull against each other.
 - **When you get stuck or are weighing a change in direction.**
-- **Once before you declare the task done.**
 
-The consult is synchronous and read-only: spawning an `advisor` subagent BLOCKS until it returns guidance. It runs on a stronger model and inherits your full context, so it sees the task, your tool calls, and their results without you re-explaining. It also receives a snapshot of your environment (the tools available to you this turn, the full skill catalog, and your workspace) so its guidance can point you at existing platform capabilities by name. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.
+The consult is synchronous and read-only: spawning an `advisor` subagent BLOCKS until it returns guidance. It runs on a stronger model, and it sees ONLY the brief you write in `objective` plus a snapshot of your environment (the tools available to you this turn, the full skill catalog, and your workspace). It cannot read this conversation, so the quality of its guidance tracks the quality of your brief. Write a substantive one:
 
-The advisor has read-only workspace tools (`file_read`, `file_list`, `code_search`) so it can open a file or search the code when a decisive fact would change its advice. It uses them sparingly, for verification rather than exploration, and it cannot change anything or persist output. It has no memory search and cannot see other conversations or external systems, and every lookup it has to make delays your answer, so surface the evidence you already have (a file's contents, a command's output, results gathered elsewhere) in the conversation or the spawn objective before consulting.
+- The task or goal, stated in full.
+- Your plan, or the options you are weighing against each other.
+- The key evidence you already have: file paths, command output, results, decisions already made.
+- The specific question you want answered.
+
+The environment snapshot is what lets its guidance point you at existing platform capabilities by name. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.
+
+The advisor has read-only workspace tools (`file_read`, `file_list`, `code_search`) so it can open a file or search the code when a decisive fact would change its advice. It uses them sparingly, for verification rather than exploration, and it cannot change anything or persist output. It has no memory search and cannot see other conversations or external systems, and every lookup it has to make delays your answer, so put the evidence you already have (a file's contents, a command's output, results gathered elsewhere) into the objective rather than making it go find them.
 
 Spawn the advisor **alone** — do NOT batch the consult in the same turn as other tool calls (especially file edits, shell commands, or anything destructive or expensive). Tool calls you issue in the same turn run concurrently with the consult, so they would execute before you see its guidance. Consult the advisor by itself, read its guidance, then act.
 
@@ -151,7 +157,6 @@ Rule of thumb: "Does this task need to know what we've been talking about?" If y
 - Use `notify_parent` for interim findings instead of waiting for completion. This lets the parent act on partial results early.
 - Use `subagent_message` to send follow-up instructions to a running subagent.
 - Use `subagent_abort` to cancel a subagent that is no longer needed.
-- Default to spawning subagents for any task that involves web research, multi-file exploration, or independent coding work. Serial execution should be the exception, not the rule.
-- Delegate root-cause investigations ("why is X happening?", debugging, log forensics) to a `researcher` instead of grepping inline. A long investigation done inline floods your own context with file slices and grep output, crowding out the conversation; the researcher does the digging in its own context and returns a compact root-cause report.
-- When a user request has both an information-gathering component and an action component, spawn a researcher immediately rather than doing the research inline yourself.
-- Prefer spawning 2-3 focused subagents over one broad one. Smaller scopes finish faster and fail more gracefully.
+- Spawn a subagent when the work is extensive: a sweep across a large codebase, deep research across many sources, or an investigation whose raw output (file slices, grep output, logs) would flood your context. Do quick work inline -- a few file reads or searches, an ordinary web lookup -- since a spawn pays for a whole fresh context and is slower than just doing the work.
+- Delegate long root-cause investigations (log forensics, multi-file "why is X happening?" digs) to a `researcher`: it does the digging in its own context and returns a compact root-cause report, instead of crowding your conversation with intermediate output.
+- Scale the fan-out to the task. Most tasks need zero or one subagent. Split work across multiple subagents only when the parts are genuinely independent and each is substantial on its own.

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "subagent_spawn",
-      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Pick its type with role: 'researcher' (read-only, fixed tool list) or 'builder' (write-capable, your whole tool surface).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. A fork that names a role runs scoped to it; a fork that names none keeps your full tool surface. Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), has read-only workspace tools for checking a decisive fact (file_read, file_list, code_search), and BLOCKS until it returns focused strategic guidance in a single response. It cannot change anything, persist output, or see other conversations.",
+      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Pick its type with role: 'researcher' (read-only, fixed tool list) or 'builder' (write-capable, your whole tool surface).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. A fork that names a role runs scoped to it; a fork that names none keeps your full tool surface. Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it sees ONLY the brief you write in 'objective' plus a snapshot of your environment (available tools, skill catalog, workspace), has read-only workspace tools for checking a decisive fact (file_read, file_list, code_search), and BLOCKS until it returns focused strategic guidance in a single response. It cannot read this conversation, change anything, persist output, or see other conversations, so the quality of its guidance tracks the quality of your brief.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -15,11 +15,11 @@
           },
           "objective": {
             "type": "string",
-            "description": "The task objective \u2014 what the subagent should accomplish"
+            "description": "The task objective: what the subagent should accomplish. For role 'advisor' this field IS the brief the advisor reads, and the only account of the work it gets, so write it out in full: the task or goal, the approach you have chosen or the options you are weighing, the key evidence you already gathered (file paths, command output, decisions made), and the specific question you want answered."
           },
           "context": {
             "type": "string",
-            "description": "Optional additional context to pass to the subagent. Ignored when fork is true; forks inherit the parent's full context."
+            "description": "Optional additional context to pass to the subagent. Ignored when fork is true (forks inherit the parent's full context), and ignored for role 'advisor', which reads only the objective brief."
           },
           "fork": {
             "type": "boolean",
@@ -31,7 +31,7 @@
           },
           "role": {
             "type": "string",
-            "description": "Which of the three subagent types to run, chosen by two questions: does it need to change anything, and do you need the answer before you can continue? 'researcher': changes nothing, runs in the background, scoped to a fixed read-only list (web_search, web_fetch, file_read, file_list, code_search, recall, skill_execute) for research, exploration, root-cause investigation, and review. 'builder': changes things, runs in the background on this conversation's whole tool surface (shell, file writes and edits, plus every connector, MCP, and browser tool you can reach) for code changes, file output, and anything that must run a command or act on an outside system. 'advisor': changes nothing and BLOCKS your turn until it answers; inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), can read files and search code (file_read, file_list, code_search) to check a decisive fact, and returns focused strategic guidance. Default when omitted: 'builder', so a spawn that names no type keeps the full tool surface. The older names are still accepted as aliases ('planner' and 'investigator' run as researcher, 'coder' and 'general' run as builder). Any other text is not a type: the subagent runs as a researcher with that text as its persona, so if the task must write files or run commands, name 'builder' explicitly. A read-only subagent asked to produce a file finishes without producing anything. Roles apply to forks too; a fork that names no role runs as a builder and keeps this conversation's full tool surface, and a fork's persona reaches it through its task framing."
+            "description": "Which of the three subagent types to run, chosen by two questions: does it need to change anything, and do you need the answer before you can continue? 'researcher': changes nothing, runs in the background, scoped to a fixed read-only list (web_search, web_fetch, file_read, file_list, code_search, recall, skill_execute) for research, exploration, root-cause investigation, and review. 'builder': changes things, runs in the background on this conversation's whole tool surface (shell, file writes and edits, plus every connector, MCP, and browser tool you can reach) for code changes, file output, and anything that must run a command or act on an outside system. 'advisor': changes nothing and BLOCKS your turn until it answers; reads the brief you write in 'objective' plus a snapshot of your environment (available tools, skill catalog, workspace), can read files and search code (file_read, file_list, code_search) to check a decisive fact, and returns focused strategic guidance. It cannot see this conversation, so a thin objective gets thin advice. Default when omitted: 'builder', so a spawn that names no type keeps the full tool surface. The older names are still accepted as aliases ('planner' and 'investigator' run as researcher, 'coder' and 'general' run as builder). Any other text is not a type: the subagent runs as a researcher with that text as its persona, so if the task must write files or run commands, name 'builder' explicitly. A read-only subagent asked to produce a file finishes without producing anything. Roles apply to forks too; a fork that names no role runs as a builder and keeps this conversation's full tool surface, and a fork's persona reaches it through its task framing."
           },
           "inference_profile": {
             "type": "string",

package/src/config/bundled-skills/transcribe/tools/transcribe-media.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { BatchTranscriber } from "../../../../stt/types.js";
+import { SttError } from "../../../../stt/types.js";
 import type { ToolContext } from "../../../../tools/types.js";
 
 // ---------------------------------------------------------------------------
@@ -8,9 +9,15 @@ import type { ToolContext } from "../../../../tools/types.js";
 // ---------------------------------------------------------------------------
 
 let mockTranscriber: BatchTranscriber | null = null;
+let mockResolveError: Error | null = null;
 
 mock.module("../../../../providers/speech-to-text/resolve.js", () => ({
-  resolveBatchTranscriber: async () => mockTranscriber,
+  resolveBatchTranscriber: async () => {
+    if (mockResolveError) {
+      throw mockResolveError;
+    }
+    return mockTranscriber;
+  },
 }));
 
 // Track calls to spawnWithTimeout so we can simulate ffmpeg/ffprobe results.
@@ -103,6 +110,7 @@ function makeMockTranscriber(
 describe("transcribe_media tool", () => {
   beforeEach(() => {
     mockTranscriber = null;
+    mockResolveError = null;
     spawnResults = {};
     accessiblePaths = new Set();
     mockFileContents = {};
@@ -119,6 +127,19 @@ describe("transcribe_media tool", () => {
         "No speech-to-text provider is configured",
       );
     });
+
+    test("surfaces a resolver error verbatim rather than the not-configured copy", async () => {
+      const reason =
+        'Deepgram Flux is streaming-only. Batch transcription requires the deepgram provider: set services.stt.provider to "deepgram".';
+      mockResolveError = new SttError("provider-error", reason, {
+        userFacing: true,
+      });
+
+      const result = await run({ file_path: "/tmp/test.mp3" }, makeContext());
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toBe(reason);
+    });
   });
 
   describe("input validation", () => {

package/src/config/bundled-skills/transcribe/tools/transcribe-media.ts

@@ -234,8 +234,15 @@ export async function run(
     };
   }
 
-  // Resolve the configured STT provider
-  const transcriber = await resolveBatchTranscriber();
+  // Resolve the configured STT provider. A typed resolver error already names
+  // the mismatch (e.g. a streaming-only provider) and its fix, so it reaches
+  // the model verbatim rather than as the "nothing configured" copy below.
+  let transcriber: BatchTranscriber | null;
+  try {
+    transcriber = await resolveBatchTranscriber();
+  } catch (err) {
+    return { content: (err as Error).message, isError: true };
+  }
   if (!transcriber) {
     return {
       content: