@vellumai/assistant 0.8.2 → 0.8.4

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -54,8 +54,114 @@ Each record is a JSON file at `<slug>/records/<uuid>.json` with shape:
 
 All new apps use `formatVersion: 2`: source files live under `src/` and compiled output lives under `dist/`. The build system compiles TSX to JS automatically when `app_refresh` is called.
 
+## Responsive Baseline & Mobile-First Mode
+
+Every app must be responsive across the full width range — phone (~360px) to desktop (~1400px+). The conversation context's `<turn_context>` block carries an `interface:` field. Visual interfaces are `macos`, `ios`, and `web`; the field doesn't toggle responsiveness on or off — it shifts the **design priority**. Non-visual values like `phone` represent voice channels that can't render apps at all and don't need to be considered here.
+
+- **`interface: ios`** (or any future mobile-web / android identifier) — mobile-first build. Design the narrow viewport first and progressively enhance upward at wider widths.
+- **`interface: macos` / `web`** — desktop-first build. Design the larger composition first; the narrow-width fallback must still meet the universal baseline below but doesn't need to feel like a native mobile app.
+- **Field absent or ambiguous** — default to desktop-first unless the user's request itself implies phone use ("for my iPhone home screen", "a tap-tracker I'll use on the go").
+
+### Universal baseline (every build, regardless of interface)
+
+These rules aren't mobile-specific — they're touch / responsive a11y baselines that any user-resizable WebView needs.
+
+**Viewport & safe areas**
+
+- Viewport meta: `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`. Never set `user-scalable=no` — it blocks accessibility zoom.
+- Pad the root container with `env(safe-area-inset-*)` so content clears the notch / home indicator when the app is opened on a notched device: `padding-top: max(var(--v-spacing-lg), env(safe-area-inset-top))`, mirrored for `-bottom`/`-left`/`-right`. On desktop the env vars resolve to `0` and the `max()` falls through to the design-system value — no-op.
+- Use `100dvh` (dynamic viewport height), not `100vh`, for full-height containers. `100vh` creates a scroll-jump on every mobile browser regardless of build mode.
+
+**Form controls**
+
+- `<input>`, `<textarea>`, `<select>` must be `font-size: 16px` or larger, or iOS Safari will zoom on focus and break the layout. This applies to every build — anyone may open a desktop-built app on their phone.
+- Add `inputmode` to text fields with structured input: `numeric` for integers, `decimal` for amounts, `email`, `tel`, `url`. Add matching `autocomplete` and `autocapitalize` hints where appropriate.
+
+**Touch & hover**
+
+- Interactive elements (buttons, list rows, nav items, toggles, icon buttons) must be ≥44×44pt. `.v-button` already meets this; for custom controls, set `min-height: 44px` explicitly.
+- Gate hover affordances behind `@media (hover: hover)` so they don't stick on touch devices visiting a desktop-built app.
+- Disable text selection on app chrome (headers, nav, buttons) with `user-select: none; -webkit-user-select: none` so long-press doesn't pop the iOS selection menu over interactive elements.
+
+**Layout fluidity**
+
+- Fluid widths only — no fixed-pixel layouts. Use `%`, `fr`, `minmax`, `clamp()` instead of `px` on container widths.
+- Horizontal-scroll tables don't work on narrow screens. At narrow widths, collapse rows into stacked cards with labels and values arranged vertically. (Mobile-first builds can use cards everywhere; desktop-first builds can keep the table at wide widths and switch to cards below a breakpoint.)
+- `vellum.widgets.*` chart containers should be sized in `vw`/`%`, not fixed `px`. Prefer simpler chart types (sparkline, bar) at narrow widths — dense multi-series charts lose detail.
+
+### Mobile-first priorities (`interface: ios` or future mobile identifier)
+
+These are the **design priority differences** that mobile-first builds adopt on top of the universal baseline. They reflect "narrow viewport is the primary experience, wider widths progressively enhance."
+
+**Typography**
+
+- Default body text to `--v-font-size-lg` (17px), not `--v-font-size-base` (14px) — the desktop base is too small to read comfortably on a phone. At wider widths the same 17px reads fine.
+
+**Spacing**
+
+- Bump default vertical rhythm one step (e.g. `--v-spacing-md` → `--v-spacing-lg` between cards and sections) so users can comfortably scroll-stop on each item.
+
+**Layout**
+
+- One column as the **default**, not as a narrow-width fallback. `flex-direction: column` first; opt into a multi-column grid only above a width breakpoint (`@media (min-width: 720px)`). No side rails, no two-pane master/detail, no fixed-width sidebars in the default view.
+- Bottom-anchor the primary action (e.g. "Add", "Save") so the thumb can reach it: `position: sticky; bottom: env(safe-area-inset-bottom)` over the scrolling list. On wider widths you may re-flow it back inline.
+- Replace side modals and popovers with bottom sheets that animate up from the bottom edge.
+
+**Interaction**
+
+- Skip the Tab/Enter/Esc keyboard pattern from "Interaction Standards" as the primary affordance — on mobile, focus comes from taps, submit from the soft keyboard's `return`, dismissal from a swipe down on bottom sheets. Keyboard support is still allowed (external-keyboard users exist on iPad) but isn't the design driver.
+
+### Desktop-first priorities (`interface: macos` / `web`)
+
+The default behaviour the rest of this skill describes — multi-column composition, hover-rich affordances, denser information, side modals, inline primary actions. The universal baseline above is the floor: the narrow-width view must still work and follow the touch / responsive a11y rules, but it doesn't need to feel native to mobile.
+
+Everything else in this skill applies unchanged.
+
 ## Workflow
 
+### 0. Preflight — Pin to a high-quality model
+
+App building is design-heavy judgment work — color palettes, layout decisions, component architecture, micro-interactions. A stronger model produces meaningfully better apps: more creative visual directions, cleaner component boundaries, fewer generic patterns. Before building, check whether the conversation is already pinned to the quality profile:
+
+```
+assistant inference session list
+```
+
+If no session is active, check the current active profile:
+
+```
+assistant config get llm.activeProfile
+```
+
+If the profile is already `quality-optimized`, skip the rest of this step and proceed to Step 1.
+
+**If the active profile is `balanced`, `cost-optimized`, or any non-quality profile, you MUST ask the user for permission before switching. Do NOT open an inference session without explicit user confirmation.** Use `assistant ui confirm`:
+
+```
+assistant ui confirm --message "App building works best with a high-quality model — it makes better design decisions, writes cleaner components, and produces more visually polished results. Switch to the quality profile for this build? (You can switch back after.)"
+```
+
+If `assistant ui confirm` isn't available on this binary, ask the user directly in conversation instead. **Either way, wait for the user's answer before proceeding.**
+
+**Only if the user confirms**, open an inference session:
+
+```
+assistant inference session open quality-optimized --ttl 1h
+```
+
+If `quality-optimized` isn't a profile name on this workspace, list the available profiles and open against the highest-quality one:
+
+```
+assistant config get llm.profiles
+assistant inference session open <profile-name> --ttl 1h
+```
+
+The `--ttl 1h` gives comfortable headroom for a typical app build without leaving a forever-pinned session if the close in Step 6 is skipped.
+
+**If the user declines, do not switch profiles.** Proceed with the current profile — the build still works, the model just won't be pinned. Skip the close in Step 6 too.
+
+If `assistant inference session` isn't available on this binary, proceed without it.
+
 ### 1. Gather Requirements
 
 **Default: just build.** When a user says "build me a habit tracker," don't ask what colors they want or how many fields to include. Immediately:
@@ -351,6 +457,16 @@ After making all file changes, call `app_refresh(app_id)` once to compile and re
 
 Apps should have multiple source files under `src/` (`styles.css`, components, helpers, etc.). Import CSS and modules from TSX so esbuild includes them in the compiled output.
 
+### 6. Close the inference session
+
+If you opened an inference session in Step 0, close it now:
+
+```
+assistant inference session close
+```
+
+If you skipped the open in Step 0 (because the user declined, the CLI didn't have the command, or the profile was already quality), skip this step too.
+
 ## Interaction Standards
 
 Every app must meet these baselines:
@@ -359,7 +475,7 @@ Every app must meet these baselines:
 - **Confirmation for destructive actions:** Use `window.vellum.confirm(title, message)` before deleting or resetting. Returns `Promise<boolean>`.
 - **Form validation:** Validate before submit, show errors inline, disable submit during async operations.
 - **Loading states:** Never show a blank screen while data loads. Use skeleton shimmer or spinners.
-- **Keyboard navigation:** `Tab` between elements, `Enter` to submit, `Escape` to close/cancel.
+- **Keyboard navigation:** `Tab` between elements, `Enter` to submit, `Escape` to close/cancel. *(De-prioritised on mobile-first builds — see [Responsive Baseline & Mobile-First Mode](#responsive-baseline--mobile-first-mode).)*
 
 ## Presentation Slide Design
 

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

@@ -0,0 +1,115 @@
+---
+name: document-editor
+description: Rich text document editor with collaborative editing tools — create, read, update, and annotate documents
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "📄"
+  vellum:
+    display-name: "Document Editor"
+    activation-hints:
+      - "User asks to write, draft, or collaborate on long-form content — use the document editor for a better editing experience"
+      - "When content will be iterated on, reviewed, or exported, prefer the document editor over inline markdown"
+      - "When a file attachment contains a draft or document the user wants to iterate on, open it in the editor"
+---
+
+Create and edit long-form documents using the built-in rich text editor. Documents open in workspace mode with chat docked to the side.
+
+## Tools
+
+- **document_create** - Opens a new document editor with an optional title and initial Markdown content. Returns a `surface_id` for subsequent updates.
+- **document_update** - Updates content in an open document editor by `surface_id`. Supports `replace` (overwrite) and `append` (add to end) modes.
+- **document_read** - Reads the current content of a document by `surface_id` when it belongs to the current conversation, or when the current actor is the guardian/local user. Use to verify content before editing.
+- **document_list** - Lists documents. Without `query`, lists the current conversation's documents. With `query`, searches by title; guardian/local users can search across conversations, while other actors are scoped to the current conversation.
+- **document_find** - Searches a document for text or regex patterns. Returns matching lines with line numbers, match positions, and matched text.
+- **document_replace_text** - Targeted find-and-replace within a document. Supports literal and regex patterns (with backreferences). Optionally limit the number of replacements.
+- **document_delete** - Deletes a document by `surface_id`. Use to clean up unwanted documents.
+
+## Retrieving existing documents
+
+When the user asks to see, open, or pull up a document:
+
+1. Check the `<active_documents>` block in your context — it lists all documents in this conversation with their `surface_id` and title. If the document is there, call `document_read` with its `surface_id`. Done in one call.
+2. If the document is NOT in `<active_documents>`, call `document_list` with a `query` matching the document title. For guardian/local users, this searches across previous conversations and sessions.
+3. Once you have the `surface_id`, call `document_read` to retrieve the content.
+
+**Never** search the filesystem, conversation history, or archives to find a document. Always use `document_list` with a `query`.
+
+## Creating a new document
+
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
+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. The user experiences real-time content appearing as you write.
+
+## Editing an existing document
+
+When the user requests changes to a document:
+
+1. Find the `surface_id` from the `<active_documents>` context block.
+2. Use `document_update` with the existing `surface_id` — do NOT call `document_create` again.
+3. **Choose the right editing tool:**
+   - `document_update` with `mode: "append"` — adding new content to the end.
+   - `document_update` with `mode: "replace"` — ONLY for full rewrites where the majority of the document is changing.
+   - `document_find` + `document_replace_text` — **for everything else**. Fixing typos, renaming terms, swapping sections, reordering content, adjusting formatting, or any edit that touches only part of the document. This is the default choice for edits. It avoids rewriting the entire document and eliminates the risk of accidentally dropping content.
+4. **Do NOT use `document_update` with `mode: "replace"` for targeted edits.** Rewriting the entire document to change a few words or rearrange sections is wasteful and error-prone.
+
+## Find & Replace
+
+Use `document_find` and `document_replace_text` for surgical edits that target specific text patterns without rewriting the entire document.
+
+### document_find
+
+Search a document for literal text or regex patterns. Parameters:
+
+- `surface_id` (required) — the document to search
+- `query` (required) — the search string or regex pattern
+- `regex` (optional, default `false`) — treat `query` as a regular expression
+- `case_sensitive` (optional, default `false`) — match case exactly
+
+Returns a list of matches with line numbers, line content, match positions, and matched text. Use this to preview what will be affected before making replacements.
+
+### document_replace_text
+
+Targeted find-and-replace within a document. Parameters:
+
+- `surface_id` (required) — the document to modify
+- `find` (required) — the search string or regex pattern
+- `replace` (required) — the replacement string (supports `$1`, `$2` backreferences when `regex` is `true`)
+- `regex` (optional, default `false`) — treat `find` as a regular expression
+- `case_sensitive` (optional, default `false`) — match case exactly
+- `max_replacements` (optional) — limit the number of replacements made
+
+Returns the number of replacements made and whether the content changed.
+
+### Workflow
+
+1. Call `document_find` to preview matches and confirm the pattern is correct.
+2. Call `document_replace_text` to apply the changes.
+
+**Examples:**
+
+- **Fix a recurring typo**: Find `"recieve"`, replace with `"receive"`.
+- **Rename a term throughout**: Find `"widget"` (case-insensitive), replace with `"component"`.
+- **Reformat dates with regex**: Find `(\d{2})/(\d{2})/(\d{4})` with `regex: true`, replace with `$3-$1-$2` to convert `MM/DD/YYYY` to `YYYY-MM-DD`.
+- **Swap or reorder sections**: Use `document_read` to get the content, identify the sections to swap, then call `document_replace_text` to replace the first section with the second and vice versa. For complex rearrangements, use multiple `document_replace_text` calls with `max_replacements: 1`.
+
+## Comments
+
+Users can leave inline comments on documents. Open comments are surfaced in a `<document_comments>` context block so you can see pending feedback.
+
+- **comment_list** — Lists open comments on a document by `surface_id`. Use this to check for feedback before or after editing, especially when the user asks you to address comments.
+- **comment_resolve** — Marks a comment as resolved by `comment_id`. Use this after you have addressed the feedback in the document content. Always edit the document first, then resolve the comment.
+- **comment_reply** — Posts a reply to an existing comment by `comment_id`. Use this to ask clarifying questions or explain why you made (or declined) a change before resolving.
+
+### Addressing comments workflow
+
+1. Read the `<document_comments>` block or call `comment_list` to see open comments.
+2. For each comment, edit the document to address the feedback.
+3. Call `comment_resolve` on comments you have addressed.
+4. If a comment is ambiguous, call `comment_reply` to ask for clarification instead of guessing.
+
+## Usage Notes
+
+- The `mode` parameter on `document_update` defaults to `append`.
+- Documents are automatically saved and accessible via the Generated panel.
+- Users can manually edit documents at any time.
+- Write in clear, engaging prose. Use active voice, vary sentence structure, and break content into logical sections with descriptive headings.

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

@@ -0,0 +1,240 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "document_create",
+      "description": "Create a new long-form document with a rich text editor. Use this when the user asks to write a blog post, article, or any long-form content. The editor opens in workspace mode with chat docked to the side.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Initial title for the document (optional, can be updated later)"
+          },
+          "initial_content": {
+            "type": "string",
+            "description": "Initial Markdown content to populate the editor (optional)"
+          }
+        }
+      },
+      "executor": "tools/document-create.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_update",
+      "description": "Update content in an open document editor. Use this to stream generated content or apply edits.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The ID of the document surface to update"
+          },
+          "content": {
+            "type": "string",
+            "description": "Markdown content to set or append"
+          },
+          "mode": {
+            "type": "string",
+            "enum": ["replace", "append"],
+            "description": "Whether to replace all content or append to the end. Defaults to append."
+          }
+        },
+        "required": ["surface_id", "content"]
+      },
+      "executor": "tools/document-update.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_read",
+      "description": "Read the current content of a document by its surface_id when it belongs to the current conversation, or when the current actor is the guardian/local user. Use this to verify document state before making edits.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The ID of the document to read"
+          }
+        },
+        "required": ["surface_id"]
+      },
+      "executor": "tools/document-read.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_list",
+      "description": "List documents. Without a query, lists documents in the current conversation. With a query, searches documents by title; guardian/local users can search across conversations, while other actors are scoped to the current conversation.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search documents by title. Omit to list only the current conversation's documents."
+          }
+        }
+      },
+      "executor": "tools/document-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_delete",
+      "description": "Delete a document by its surface_id.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The ID of the document to delete"
+          }
+        },
+        "required": ["surface_id"]
+      },
+      "executor": "tools/document-delete.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_find",
+      "description": "Search for text or a regex pattern within a document. Returns matching lines with line numbers and context — like grep. Use this to locate specific content before making targeted edits with document_replace_text.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The document surface ID"
+          },
+          "query": {
+            "type": "string",
+            "description": "Text or regex pattern to search for"
+          },
+          "regex": {
+            "type": "boolean",
+            "description": "Treat query as a regex pattern. Defaults to false (literal match)."
+          },
+          "case_sensitive": {
+            "type": "boolean",
+            "description": "Match case-sensitively. Defaults to false."
+          }
+        },
+        "required": ["surface_id", "query"]
+      },
+      "executor": "tools/document-find.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_replace_text",
+      "description": "Find and replace text within a document — like sed. Performs targeted replacements without rewriting the entire document. Supports literal text and regex patterns. Use document_find first to preview what will be matched.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The document surface ID"
+          },
+          "find": {
+            "type": "string",
+            "description": "Text or regex pattern to find"
+          },
+          "replace": {
+            "type": "string",
+            "description": "Replacement text. When using regex, supports backreferences ($1, $2, etc.)."
+          },
+          "regex": {
+            "type": "boolean",
+            "description": "Treat find as a regex pattern. Defaults to false (literal match)."
+          },
+          "case_sensitive": {
+            "type": "boolean",
+            "description": "Match case-sensitively. Defaults to false."
+          },
+          "max_replacements": {
+            "type": "number",
+            "description": "Maximum number of replacements to make. Omit to replace all occurrences."
+          }
+        },
+        "required": ["surface_id", "find", "replace"]
+      },
+      "executor": "tools/document-replace-text.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "comment_list",
+      "description": "List open comments on a document. Returns all unresolved comments with their content, anchor text, and thread context so you can address user feedback.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The document surface ID"
+          }
+        },
+        "required": ["surface_id"]
+      },
+      "executor": "tools/comment-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "comment_resolve",
+      "description": "Mark a comment as resolved after you have addressed the feedback. Use this after editing the document to satisfy the comment.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The document surface ID"
+          },
+          "comment_id": {
+            "type": "string",
+            "description": "The comment ID to resolve"
+          }
+        },
+        "required": ["surface_id", "comment_id"]
+      },
+      "executor": "tools/comment-resolve.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "comment_reply",
+      "description": "Reply to a comment thread. Use this to ask clarifying questions or explain your approach before or after making changes.",
+      "category": "document-editor",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The document surface ID"
+          },
+          "comment_id": {
+            "type": "string",
+            "description": "The parent comment ID to reply to"
+          },
+          "content": {
+            "type": "string",
+            "description": "Reply text"
+          }
+        },
+        "required": ["surface_id", "comment_id", "content"]
+      },
+      "executor": "tools/comment-reply.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/document-editor/tools/comment-list.ts

@@ -0,0 +1,12 @@
+import { executeCommentList } from "../../../../tools/document/document-comment-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeCommentList(input, context);
+}

package/src/config/bundled-skills/document-editor/tools/comment-reply.ts

@@ -0,0 +1,12 @@
+import { executeCommentReply } from "../../../../tools/document/document-comment-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeCommentReply(input, context);
+}

package/src/config/bundled-skills/document-editor/tools/comment-resolve.ts

@@ -0,0 +1,12 @@
+import { executeCommentResolve } from "../../../../tools/document/document-comment-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeCommentResolve(input, context);
+}

package/src/config/bundled-skills/document-editor/tools/document-find.ts

@@ -0,0 +1,12 @@
+import { executeDocumentFind } from "../../../../tools/document/document-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeDocumentFind(input, context);
+}

package/src/config/bundled-skills/document-editor/tools/document-replace-text.ts

@@ -0,0 +1,12 @@
+import { executeDocumentReplaceText } from "../../../../tools/document/document-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeDocumentReplaceText(input, context);
+}

package/src/config/bundled-skills/media-processing/SKILL.md

@@ -6,6 +6,14 @@ metadata:
   emoji: "🎬"
   vellum:
     display-name: "Media Processing"
+    activation-hints:
+      - "User wants to ingest, process, or analyze a local video, audio, or image file"
+      - "User wants to ask natural-language questions about a video's content (e.g. 'what happens at 3:14', 'find all the goals', 'who appears in this footage')"
+      - "User wants to extract a clip or short segment from a video"
+      - "User wants to run keyframe extraction, segmentation, or frame-by-frame analysis on a video"
+    avoid-when:
+      - "User only wants a plain audio transcript — use the transcribe skill instead"
+      - "User just wants to play or open a media file in their default system player — that does not need this pipeline"
 ---
 
 Ingest and track processing of media files (video, audio, images) through a configurable 3-phase pipeline.

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -33,7 +33,7 @@ Follow the steps below to ensure everything is prepared to make and receive phon
 
 ## Step 1: Twilio Setup
 
-Load the `twilio-setup` skill to determine whether Twilio has been fully configured and set it up if not. This is a prerequisite to all subsequent steps.
+Immediately load the `twilio-setup` skill to begin setup. That skill marks Twilio setup as started before its read-only checks, which gives managed deployments a chance to open the Velay tunnel WebSocket while the user finishes entering credentials and choosing a number. Twilio setup is a prerequisite to all subsequent steps.
 
 ## Step 2: Enable Calls
 

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

@@ -6,6 +6,14 @@ metadata:
   emoji: "📅"
   vellum:
     display-name: "Schedule"
+    activation-hints:
+      - "User wants to set a reminder for a future time (e.g. 'remind me at 9am tomorrow', 'remind me to take meds at 8pm')"
+      - "User wants to schedule a recurring task or automation (e.g. 'every weekday at 9am', 'every Monday at noon')"
+      - "User wants to schedule a one-time future action the assistant should run autonomously (e.g. 'at 5pm check my email and summarize it')"
+      - "User wants to list, update, cancel, or inspect existing scheduled tasks or reminders"
+    avoid-when:
+      - "User wants to add something to their task list or queue — use task-list tools instead"
+      - "User wants to act immediately or run a quick command that completes within the conversation — schedule is only for deferred or recurring execution"
 ---
 
 Manage scheduled automations. Schedules can be **recurring** (cron or RRULE expression) or **one-shot** (a single `fire_at` timestamp). Schedules support three modes: **execute** (run a message through the assistant), **notify** (send a notification to the user), and **script** (run a shell command directly without LLM involvement).