@vellumai/assistant 0.4.55 → 0.4.57

package/src/config/acp-schema.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+export const AcpAgentConfigSchema = z
+  .object({
+    command: z.string().describe("Command to spawn the ACP agent process"),
+    args: z
+      .array(z.string())
+      .default([])
+      .describe("Arguments passed to the agent command"),
+    description: z
+      .string()
+      .optional()
+      .describe("Human-readable description of what this agent does"),
+    env: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe("Environment variables set for the agent process"),
+  })
+  .describe("Configuration for an individual ACP agent");
+
+export const AcpConfigSchema = z
+  .object({
+    enabled: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Whether the Agent Communication Protocol (ACP) system is enabled",
+      ),
+    maxConcurrentSessions: z
+      .number()
+      .int()
+      .positive()
+      .default(4)
+      .describe(
+        "Maximum number of ACP agent sessions that can run simultaneously",
+      ),
+    agents: z
+      .record(z.string(), AcpAgentConfigSchema)
+      .default({})
+      .describe("Map of agent names to their configurations"),
+  })
+  .describe(
+    "Agent Communication Protocol (ACP) — enables inter-agent communication and delegation",
+  );
+
+export type AcpConfig = z.infer<typeof AcpConfigSchema>;
+export type AcpAgentConfig = z.infer<typeof AcpAgentConfigSchema>;

package/src/config/bundled-skills/_shared/CLI_RETRIEVAL_PATTERN.md

@@ -5,23 +5,25 @@ When running the `assistant` CLI, run it using the `bash` (not `host_bash`) tool
 For account and auth workflows, prefer documented `assistant` CLI commands over
 any generic account registry:
 
-- `assistant credentials ...` for stored secrets and credential metadata
-- `assistant oauth connections token <provider-key>` for OAuth-backed integrations
+- `assistant credentials list` for discovering stored credential handles
+- `assistant oauth connections list` for discovering OAuth connection handles
+- `assistant credentials set ...` for storing new credentials
 - `assistant mcp auth <name>` when an MCP server needs browser login
 - `assistant platform status` for platform-linked deployment/auth context
 
 If a bundled skill documents a service-specific `assistant <service>` auth or
 session flow, follow that CLI exactly.
 
-# Outbound Network Requests
+# Authenticated Outbound Requests
 
-When a skill needs outbound API calls with a stored credential (outside of `assistant` CLI reads), use proxied `bash`:
+When a skill needs outbound API calls with a stored credential, use CES tools instead of
+extracting raw tokens into shell commands. CES injects credentials securely without exposing
+secrets to the assistant:
 
-```yaml
-bash:
-  network_mode: proxied
-  credential_ids:
-    - "<credential-id>"
-  command: |
-    curl -s https://api.example.com/resource
-```
+1. Discover the credential handle: `assistant credentials list --search <service>`
+2. Use the appropriate CES tool:
+   - `make_authenticated_request` for HTTP API calls (CES injects auth and returns the response)
+   - `run_authenticated_command` for CLI commands needing credential env vars (runs in CES sandbox)
+
+Note: `host_bash` is approval-gated and runs outside the CES secrecy boundary. Do not use
+`host_bash` to pass raw credentials to shell commands. Route authenticated work through CES tools.

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

@@ -0,0 +1,58 @@
+---
+name: acp
+description: Spawn external coding agents via the Agent Client Protocol (ACP)
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "🔗"
+  vellum:
+    display-name: "ACP"
+---
+
+ACP agent orchestration - spawn external coding agents (Claude Code, Codex, Gemini CLI, etc.) to work on tasks via the Agent Client Protocol.
+
+## Usage
+
+Use `acp_spawn` to delegate a coding task to an external agent. The agent runs as a subprocess speaking the ACP protocol over stdio and streams results back.
+
+## First-time setup
+
+When the user first tries to use ACP and it's not configured, set it up automatically:
+
+1. **Check if `claude-agent-acp` is installed** by running `which claude-agent-acp`. If not found, install it:
+   ```bash
+   npm install -g @zed-industries/claude-agent-acp
+   ```
+
+2. **Enable ACP in the workspace config** by editing the config file to add the `acp` section. The correct config is:
+   ```json
+   {
+     "acp": {
+       "enabled": true,
+       "maxConcurrentSessions": 4,
+       "agents": {
+         "claude": {
+           "command": "claude-agent-acp",
+           "args": [],
+           "description": "Claude Code (via ACP adapter)"
+         }
+       }
+     }
+   }
+   ```
+
+3. **Wait a few seconds** for the config watcher to pick up the change (it hot-reloads automatically - no restart needed).
+
+4. Then retry the `acp_spawn` call. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
+
+## Critical: correct agent command
+
+- The command MUST be `claude-agent-acp` - this is the ACP adapter from `@zed-industries/claude-agent-acp`.
+- NEVER use `claude`, `claude -p`, `claude --acp`, or any other command. Only `claude-agent-acp` speaks the ACP JSON-RPC protocol.
+- NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp`, leave it alone.
+
+## Tips
+
+- The spawned agent runs autonomously with its own tools, file editing, and terminal access.
+- Results are streamed back and injected into the conversation when the agent completes.
+- Use `acp_status` to check on running agents and `acp_abort` to stop them.
+- The `cwd` parameter controls where the agent works - set it to the project root the user wants the agent to operate in.

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

@@ -0,0 +1,79 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "acp_spawn",
+      "description": "Spawn an external coding agent (e.g. Claude Code, Codex, Gemini CLI) via ACP to work on a task. The agent runs as a subprocess and streams results back. Use this when you want to delegate a coding task to an external agent that has its own tools, file editing, and terminal access. If ACP is not enabled, follow the setup instructions in SKILL.md to install claude-agent-acp and configure it. The command MUST be 'claude-agent-acp' - NEVER use 'claude', 'claude -p', or 'claude --acp'.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "agent": {
+            "type": "string",
+            "description": "Which agent to spawn (e.g. 'claude', 'codex', 'gemini'). Defaults to 'claude'."
+          },
+          "task": {
+            "type": "string",
+            "description": "The task to give the agent - what it should accomplish"
+          },
+          "cwd": {
+            "type": "string",
+            "description": "Working directory for the agent. This determines where the agent runs and where its session is stored. Set this to the project/repo root the user wants the agent to work in. Defaults to current conversation's working directory."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief explanation of why this tool is being called"
+          }
+        },
+        "required": ["task"]
+      },
+      "executor": "tools/acp-spawn.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "acp_status",
+      "description": "Get the status of a specific ACP session or list all ACP sessions. Only use this when the user explicitly asks about ACP session status - do NOT poll automatically, as you will be notified when sessions complete.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "acp_session_id": {
+            "type": "string",
+            "description": "Optional ACP session ID to query. If omitted, returns all ACP sessions."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief explanation of why this tool is being called"
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/acp-status.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "acp_abort",
+      "description": "Abort a running ACP session by ID. This kills the agent process and removes the session.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "acp_session_id": {
+            "type": "string",
+            "description": "The ID of the ACP session to abort."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief explanation of why this tool is being called"
+          }
+        },
+        "required": ["acp_session_id"]
+      },
+      "executor": "tools/acp-abort.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/{settings/tools/set-avatar.ts → acp/tools/acp-abort.ts}

@@ -1,4 +1,4 @@
-import { setAvatarTool } from "../../../../tools/system/avatar-generator.js";
+import { executeAcpAbort } from "../../../../tools/acp/abort.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -8,5 +8,5 @@ export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  return setAvatarTool.execute(input, context);
+  return executeAcpAbort(input, context);
 }

package/src/config/bundled-skills/acp/tools/acp-spawn.ts

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

package/src/config/bundled-skills/acp/tools/acp-status.ts

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

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

@@ -1,6 +1,6 @@
 ---
 name: app-builder
-description: Build interactive apps, dashboards, calculators, games, trackers, tools, landing pages, and data visualizations with HTML/CSS/JS. Use when the user says build, create, or make an app/dashboard/calculator/game.
+description: Build interactive apps, dashboards, calculators, games, trackers, tools, landing pages, and data visualizations with HTML/CSS/JS
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🏗️"
@@ -10,9 +10,9 @@ metadata:
       - "frontend-design"
 ---
 
-You are an expert app builder and visual designer. When the user asks you to create an app, tool, or utility, you immediately design a data schema, choose a stunning visual direction, build a self-contained HTML/CSS/JS interface, and open it — all in one step. You don't discuss or ask for permission to be creative. You ARE the designer: you pick the colors, the layout, the atmosphere, the micro-interactions. Your apps should make users stop and say "whoa" — they should feel designed, not generated.
+You are an expert app builder and visual designer. When the user asks you to create an app, tool, or utility, you immediately design a data schema, choose a stunning visual direction, build the interface, and open it - all in one step. You don't discuss or ask for permission to be creative. You ARE the designer: you pick the colors, the layout, the atmosphere, the micro-interactions. Your apps should make users stop and say "whoa" - they should feel designed, not generated.
 
-**Every app gets its own visual identity.** A plant tracker should feel earthy and green. A finance dashboard should feel precise and navy. A fitness app should feel energetic and purple. Apps should look like they were designed by a boutique studio for that specific domain — not like generic branded tools. Think standalone premium product, not template.
+**Every app gets its own visual identity.** A plant tracker should feel earthy and green. A finance dashboard should feel precise and navy. A fitness app should feel energetic and purple. Apps should look like they were designed by a boutique studio for that specific domain - not like generic branded tools. Think standalone premium product, not template.
 
 **Your default behavior:** Build immediately. The user types "build me a habit tracker" and you deliver a complete, polished app with a domain-matched color palette, atmospheric background, and thoughtful interactions. Don't ask what colors they want. Don't show wireframes. Just build something stunning and let them refine from there.
 
@@ -24,7 +24,7 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 **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:
 
-1. Envision the ideal version of this app — what would make someone excited to use it?
+1. Envision the ideal version of this app - what would make someone excited to use it?
 2. Pick a distinctive visual direction following the `frontend-design` skill
 3. Design a clean data schema
 4. Build the complete, polished app with animations, interactions, and empty states
@@ -42,15 +42,15 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 <!-- feature:app-builder-multifile:alt:end -->
 
-**Only ask questions when the request is genuinely ambiguous** — e.g., "build me an app" with no indication of what kind. Even then, prefer building something impressive based on context clues over asking a battery of questions.
+**Only ask questions when the request is genuinely ambiguous** - e.g., "build me an app" with no indication of what kind. Even then, prefer building something impressive based on context clues over asking a battery of questions.
 
-**When in doubt, build something impressive** and let the user refine with `app_update`. The first impression matters most — a beautiful app with the wrong shade of blue is easy to fix. A correct but ugly app is hard to come back from.
+**When in doubt, build something impressive** and let the user refine with `app_update`. The first impression matters most - a beautiful app with the wrong shade of blue is easy to fix. A correct but ugly app is hard to come back from.
 
 **There are no "quick" builds.** Every app, regardless of complexity, gets the full design treatment. A 3-field form and a 20-section dashboard get the same design care. The only difference is scope, not quality.
 
 ### 2. Design the Data Schema
 
-Create a JSON Schema that defines the structure of a single record. Every record automatically gets `id`, `appId`, `createdAt`, and `updatedAt` — you only define user-facing fields.
+Create a JSON Schema that defines the structure of a single record. Every record automatically gets `id`, `appId`, `createdAt`, and `updatedAt` - you only define user-facing fields.
 
 Schema guidelines:
 
@@ -58,7 +58,7 @@ Schema guidelines:
 - Define `properties` for each field
 - Supported types: `string`, `number`, `boolean`
 - Add a `required` array for mandatory fields
-- Keep schemas reasonably flat — encode complex nested data as JSON strings when needed
+- Keep schemas reasonably flat - encode complex nested data as JSON strings when needed
 
 Example schema for a project tracker:
 
@@ -88,18 +88,16 @@ Apps are rendered inside a sandboxed WebView on macOS.
 
 <!-- feature:app-builder-multifile:start -->
 
-You can build them in two formats: **multi-file TSX** (preferred) or **single-file HTML** (legacy).
+#### Multi-file TSX projects
 
-#### Multi-file TSX projects (preferred)
-
-Use this format for any non-trivial app. You get component reuse, TypeScript type-checking, and clean file organization. The build system uses esbuild to bundle everything automatically.
+Build apps as multi-file TSX projects. You get component reuse, TypeScript type-checking, and clean file organization. The build system uses esbuild to bundle everything automatically.
 
 **Project structure:**
 
 ```
 src/
-  index.html          # Entry HTML — minimal shell, loads compiled bundle
-  main.tsx             # App entry — renders root component into #app
+  index.html          # Entry HTML - minimal shell, loads compiled bundle
+  main.tsx             # App entry - renders root component into #app
   components/          # Preact functional components
     Header.tsx
     RecordList.tsx
@@ -141,7 +139,7 @@ export const Header: FunctionComponent<Props> = ({ title, count }) => {
 
 **CSS:** Import CSS files directly in TSX (`import './styles.css'`). You can also use inline styles via the `style` attribute on JSX elements.
 
-**Data bridge:** The same `window.vellum.data` API works in TSX components — call it from `useEffect` hooks or event handlers:
+**Data bridge:** The same `window.vellum.data` API works in TSX components - call it from `useEffect` hooks or event handlers:
 
 ```tsx
 const [records, setRecords] = useState<Record[]>([]);
@@ -151,11 +149,11 @@ useEffect(() => {
 }, []);
 ```
 
-**File workflow:** Use `app_file_write` for each source file. The build happens automatically when you call `app_open`.
+**File workflow:** Use `app_file_write` for each source file. Each write automatically triggers a recompile of the project.
 
-**Allowed third-party packages:** `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`, `lucide`. Import them directly — esbuild resolves them at build time. No CDN imports. Note: `lucide` is the vanilla JS icon library (not `lucide-react`). Use its `createElement` or `createIcons` API, or manually inline SVG — do not import JSX icon components.
+**Allowed third-party packages:** `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`, `lucide`. Import them directly - esbuild resolves them at build time. No CDN imports. Note: `lucide` is the vanilla JS icon library (not `lucide-react`). Use its `createElement` or `createIcons` API, or manually inline SVG - do not import JSX icon components.
 
-**Example — creating a multi-file project:**
+**Example - creating a multi-file project:**
 
 ```
 app_file_write(app_id, "src/index.html", `<!DOCTYPE html>
@@ -211,31 +209,35 @@ app_file_write(app_id, "src/styles.css", `.app { padding: var(--v-spacing-lg); }
 
 **Technical constraints (multi-file):**
 
-- No CDN imports — use esbuild-resolved packages from the allowlist above
-- Preact for UI (not React) — `import { render } from 'preact'`
+- No CDN imports - use esbuild-resolved packages from the allowlist above
+- Preact for UI (not React) - `import { render } from 'preact'`
 - TypeScript encouraged for all `.tsx`/`.ts` files
-- No external fonts, images, or resources — use system fonts and CSS/SVG for visuals
+- No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
 - Design for 400-600px width with graceful resizing
-- The WebView blocks all navigation — links and form `action` attributes won't work
+- The WebView blocks all navigation - links and form `action` attributes won't work
 <!-- feature:app-builder-multifile:end -->
 
+<!-- feature:app-builder-multifile:alt -->
+
 #### Single HTML file
 
 Write a complete, self-contained HTML document.
 
 **Technical constraints (single-file):**
 
-- Single HTML string — no external files, CDNs, or imports
+- Single HTML string - no external files, CDNs, or imports
 - All CSS in `<style>` in `<head>`, all JavaScript in `<script>` before `</body>`
-- No external fonts, images, or resources — use system fonts and CSS/SVG for visuals
+- No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
 - Design for 400-600px width with graceful resizing
-- The WebView blocks all navigation — links and form `action` attributes won't work
+- The WebView blocks all navigation - links and form `action` attributes won't work
+
+<!-- feature:app-builder-multifile:alt:end -->
 
 #### Injected design system
 
 A design system CSS is auto-injected inside a `@layer`, so your styles always take priority. It provides element defaults and automatic light/dark mode switching via `prefers-color-scheme`.
 
-**Use `--v-*` variables and `.v-*` classes** — they handle light/dark mode automatically. No manual dark mode CSS needed.
+**Use `--v-*` variables and `.v-*` classes** - they handle light/dark mode automatically. No manual dark mode CSS needed.
 
 Available design tokens:
 
@@ -267,7 +269,7 @@ window.addEventListener("vellum-theme-change", (e) => {
 
 #### Widget component library
 
-A CSS/JS widget library is auto-injected alongside the design system. Use these for standard UI patterns — skip them when custom HTML serves the user better.
+A CSS/JS widget library is auto-injected alongside the design system. Use these for standard UI patterns - skip them when custom HTML serves the user better.
 
 **Layout widgets** (class names, infer HTML structure):
 
@@ -285,7 +287,7 @@ A CSS/JS widget library is auto-injected alongside the design system. Use these
 | `.v-progress-bar` / `.v-progress-track` / `.v-progress-fill` | Horizontal progress                                            |
 | `.v-status-badge`                                            | Colored pill with dot (`.success`/`.error`/`.warning`/`.info`) |
 | `.v-stat-row` / `.v-stat`                                    | Horizontal label-value pairs                                   |
-| `.v-toast`                                                   | Notification banner — prefer `vellum.widgets.toast()`          |
+| `.v-toast`                                                   | Notification banner - prefer `vellum.widgets.toast()`          |
 | `.v-avatar-row`                                              | Contact/team display                                           |
 | `.v-tag-group`                                               | Wrapping tag row                                               |
 
@@ -394,32 +396,34 @@ vellum.widgets.slideshow("deck", {
 
 #### When to use widgets vs custom HTML
 
-- **Use widgets** for standard patterns — tables, metrics, timelines, notifications, presentations
-- **Use custom HTML** for novel or creative UIs — games, art tools, unique dashboards
-- **Mix freely** — widgets compose well together and with custom elements
+- **Use widgets** for standard patterns - tables, metrics, timelines, notifications, presentations
+- **Use custom HTML** for novel or creative UIs - games, art tools, unique dashboards
+- **Mix freely** - widgets compose well together and with custom elements
 - **ALWAYS use `vellum.widgets.*` chart functions** instead of hand-coding SVG/CSS charts. They handle overflow clipping, bounds, scaling, and dark mode. Hand-coded charts break layouts.
 
 #### Data bridge API
 
 The HTML interface can read and write records via `window.vellum.data`. All methods return Promises.
 
-- `window.vellum.data.query()` — Returns all records: `{ id, appId, data, createdAt, updatedAt }[]`
-- `window.vellum.data.create(data)` — Creates a record. Returns the created record.
-- `window.vellum.data.update(recordId, data)` — Updates a record by ID. Returns updated record.
-- `window.vellum.data.delete(recordId)` — Deletes a record by ID. Returns void.
+- `window.vellum.data.query()` - Returns all records: `{ id, appId, data, createdAt, updatedAt }[]`
+- `window.vellum.data.create(data)` - Creates a record. Returns the created record.
+- `window.vellum.data.update(recordId, data)` - Updates a record by ID. Returns updated record.
+- `window.vellum.data.delete(recordId)` - Deletes a record by ID. Returns void.
 
 Important:
 
 - Call `query()` on page load to populate initial state
 - User fields live in `record.data` (e.g., `record.data.title`)
 - Record IDs are UUID strings
-- All operations are async — use `async/await`
+- All operations are async - use `async/await`
 - Wrap all calls in `try/catch`
 
 #### Client-side state management
 
 `localStorage` and `sessionStorage` are available for ephemeral UI state (filters, view modes, collapsed state, preferences, form drafts). Use `window.vellum.data` for persistent app records, `localStorage` for UI preferences.
 
+<!-- feature:app-builder-multifile:alt -->
+
 #### JavaScript patterns
 
 Initialize apps with clean state management:
@@ -472,26 +476,38 @@ function showView(name) {
 }
 ```
 
+<!-- feature:app-builder-multifile:alt:end -->
+
+<!-- feature:app-builder-multifile:start -->
+### 4. Create and Open the App
+<!-- feature:app-builder-multifile:end -->
+<!-- feature:app-builder-multifile:alt -->
 ### 5. Create and Open the App
+<!-- feature:app-builder-multifile:alt:end -->
 
 Call `app_create` with:
 
 - `name`: Short descriptive name
 - `description`: One-sentence summary
 - `schema_json`: JSON schema as string
-- `html`: (optional) Complete HTML document as string for `index.html`. If omitted, a minimal scaffold is created — you can then write `index.html` and other files via `app_file_write`.
+- `html`: (optional) Complete HTML document as string for `index.html`. If omitted, a minimal scaffold is created - you can then write `index.html` and other files via `app_file_write`.
 - `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat
-- `preview`: Always include — `title` (required), `subtitle`, `description`, `icon` (image URL preferred, emoji fallback), `metrics` (up to 3 key-value pills)
+- `preview`: Always include - `title` (required), `subtitle`, `description`, `icon` (image URL preferred, emoji fallback), `metrics` (up to 3 key-value pills)
 
-The app is NOT opened in a workspace panel automatically — users open it via the 'Open App' button on the inline card.
+The app is NOT opened in a workspace panel automatically - users open it via the 'Open App' button on the inline card.
 
+<!-- feature:app-builder-multifile:start -->
+### 5. Handle Iteration
+<!-- feature:app-builder-multifile:end -->
+<!-- feature:app-builder-multifile:alt -->
 ### 6. Handle Iteration
+<!-- feature:app-builder-multifile:alt:end -->
 
 When the user requests changes, prefer **`app_file_edit`** over rewriting the entire file.
 
-- **`app_file_edit`** — preferred for targeted changes (styles, bugs, features). Provide `app_id`, `path`, `old_string`, `new_string`.
-- **`app_file_write`** — use when creating new files or when changes are so extensive a full rewrite is cleaner.
-- **`app_update`** — metadata only: `name`, `description`, `schema_json`. Not for code changes.
+- **`app_file_edit`** - preferred for targeted changes (styles, bugs, features). Provide `app_id`, `path`, `old_string`, `new_string`.
+- **`app_file_write`** - use when creating new files or when changes are so extensive a full rewrite is cleaner.
+- **`app_update`** - metadata only: `name`, `description`, `schema_json`. Not for code changes.
 - Always include a **`status`** parameter describing what you're doing.
 
 Apps can have multiple files (`styles.css`, `app.js`, etc.). Link from `index.html` with standard tags.
@@ -512,10 +528,10 @@ Slides are a different domain from apps. Skip app-specific patterns (contextual
 
 **Key principles:**
 
-- One idea per slide — understood in 3 seconds
-- Layout variety — 3+ different types per deck, never consecutive same-type
+- One idea per slide - understood in 3 seconds
+- Layout variety - 3+ different types per deck, never consecutive same-type
 - 8 layout types: Title, Stats, Bullets, Quote, Comparison, Timeline, Visual/Immersive, Closing/CTA
-- Bold backgrounds — dark, gradient, or strongly tinted
+- Bold backgrounds - dark, gradient, or strongly tinted
 - Max 6 bullets per slide, max 3 sentences body text
 - Never go below 15px for any visible text
 
@@ -524,7 +540,7 @@ Init with `vellum.widgets.slideshow()`. Use `.v-slide` with helpers: `.v-slide-l
 ## Error Handling
 
 - All `window.vellum.data` calls must be wrapped in `try/catch` with user-friendly feedback.
-- Never let a failed operation silently pass — always show a toast or inline error.
+- Never let a failed operation silently pass - always show a toast or inline error.
 - If the page loads with no data, show a designed empty state (`.v-empty-state`).
 - For forms, show validation errors inline next to the relevant field.
 
@@ -534,7 +550,7 @@ When the user wants to triage or bulk-act on items, generate an interactive UI w
 
 1. Fetch data with relevant tools
 2. Render a `dynamic_page` with selectable items and action buttons
-3. User selects + clicks action — UI sends `surfaceAction` with action ID and selected IDs
+3. User selects + clicks action - UI sends `surfaceAction` with action ID and selected IDs
 4. Execute tools, update UI with `ui_update`, show feedback via `widgets.toast()`
 5. Use `window.vellum.confirm()` for destructive actions
 

package/src/config/bundled-skills/app-builder/TOOLS.json

@@ -75,7 +75,7 @@
             },
             "required": ["title"]
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -93,7 +93,7 @@
       "input_schema": {
         "type": "object",
         "properties": {
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -114,7 +114,7 @@
             "type": "string",
             "description": "The ID of the app to query records for"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -159,7 +159,7 @@
               "type": "string"
             }
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -181,7 +181,7 @@
             "type": "string",
             "description": "The ID of the app to delete"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -203,7 +203,7 @@
             "type": "string",
             "description": "The ID of the app"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -237,7 +237,7 @@
             "type": "number",
             "description": "Number of lines to return (default: all)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -279,7 +279,7 @@
             "type": "string",
             "description": "Optional short human-readable progress message shown to the user (e.g. 'adding dark mode styles')"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -313,7 +313,7 @@
             "type": "string",
             "description": "Optional short human-readable progress message shown to the user (e.g. 'adding dark mode styles')"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -339,7 +339,7 @@
             "type": "string",
             "description": "Optional description to guide icon generation (e.g. 'a blue calendar with a checkmark'). If omitted, the app name and description are used."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }