vellum 0.2.9 → 0.2.11

package/src/config/system-prompt.ts

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getWorkspaceDir, getWorkspacePromptPath } from '../util/platform.js';
+import { getWorkspaceDir, getWorkspacePromptPath, isMacOS } from '../util/platform.js';
 import { getLogger } from '../util/logger.js';
 import { loadSkillCatalog, type SkillSummary } from './skills.js';
 import { getConfig } from './loader.js';
@@ -108,13 +108,11 @@ export function buildSystemPrompt(): string {
     );
   }
   parts.push(buildConfigSection());
-  parts.push(buildToolRoutingSection());
   parts.push(buildTaskScheduleReminderRoutingSection());
   parts.push(buildAttachmentSection());
-  parts.push(buildDynamicUiSection());
-  parts.push(buildActionableUiSection());
-  parts.push(buildDocumentCreationSection());
-  parts.push(buildStarterTaskPlaybookSection());
+  if (!isOnboardingComplete()) {
+    parts.push(buildStarterTaskPlaybookSection());
+  }
   parts.push(buildToolPermissionSection());
   parts.push(buildSystemPermissionSection());
   parts.push(buildChannelAwarenessSection());
@@ -128,72 +126,6 @@ export function buildSystemPrompt(): string {
   return appendSkillsCatalog(parts.join('\n\n'));
 }
 
-function buildToolRoutingSection(): string {
-  return [
-    '## Tool Routing by Content Type',
-    '',
-    'Choose the right tool based on what the user is asking for:',
-    '',
-    '### Writing Text Content → `document_create` + multiple `document_update` calls',
-    '',
-    'Use when the user wants to **write or compose** long-form text:',
-    '- Blog posts, articles, essays',
-    '- Reports, documentation, guides',
-    '- Any long-form writing (500+ words)',
-    '',
-    '**CRITICAL ACTION REQUIRED:**',
-    '1. User says "write a blog post" → You MUST call `document_create` tool IMMEDIATELY',
-    '2. Do NOT just say "I\'ll create a document" - actually call the tool!',
-    '3. After creating the document, call `document_update` MULTIPLE times to stream content in chunks',
-    '- Content that benefits from editing and markdown formatting',
-    '',
-    '**Key indicators:** User says "write", "draft", "compose", "create a blog/article/essay"',
-    '**Workflow:** Call `document_create` with title, then stream content using `document_update`',
-    '**Output:** Opens the Documents tab with built-in rich text editor',
-    '',
-    '### Building Interactive Apps → `app_create`',
-    '',
-    'Use when the user wants to **build or create** an interactive application:',
-    '- Dashboards, calculators, tools, utilities',
-    '- Games, trackers, timers, counters',
-    '- Data visualizations with user interaction',
-    '- Forms, CRUD apps, admin panels',
-    '- Presentational sites (portfolios, landing pages, resumes)',
-    '',
-    '**Key indicators:** User says "build", "create", "make an app/dashboard/calculator"',
-    '**Workflow:** Call `app_create` with HTML/CSS/JS and schema',
-    '**Output:** Opens a dynamic_page surface with full interactivity',
-    '',
-    '### Showing Structured Data → `ui_show`',
-    '',
-    'Use when the user wants to **display or visualize** existing data:',
-    '- Weather forecasts, flight results, stock prices',
-    '- Quick tables, cards, lists from API/tool data',
-    '- Temporary displays (no persistence needed)',
-    '',
-    '**Key indicators:** User says "show", "display", "what\'s the weather/stock price"',
-    '**Workflow:** Gather data via tools, then call `ui_show` with formatted HTML',
-    '**Output:** Shows a temporary dynamic page in chat context',
-    '',
-    '### Decision Framework',
-    '',
-    '**Ask yourself:**',
-    '1. Is this primarily **text composition**? → `document_create`',
-    '2. Is this an **interactive app** with state/logic? → `app_create`',
-    '3. Is this **displaying data** from tools/APIs? → `ui_show`',
-    '',
-    '**Examples:**',
-    '- "Write a blog post about AI" → `document_create` (text composition)',
-    '- "Build a todo list app" → `app_create` (interactive, stateful)',
-    '- "Show me the weather in NYC" → `ui_show` (data display)',
-    '- "Create a markdown editor" → `app_create` (interactive tool)',
-    '- "Draft an essay on philosophy" → `document_create` (text composition)',
-    '- "Make a countdown timer" → `app_create` (interactive, dynamic)',
-    '',
-    '**All three tools are equally important — use the right one for the task.**',
-  ].join('\n');
-}
-
 function buildTaskScheduleReminderRoutingSection(): string {
   return [
     '## Tool Routing: Tasks vs Schedules vs Reminders',
@@ -308,294 +240,6 @@ function buildAttachmentSection(): string {
   ].join('\n');
 }
 
-function buildDynamicUiSection(): string {
-  return [
-    '## Dynamic UI',
-    '',
-    '### When to use',
-    'Use dynamic UI when the response involves structured data, visual metrics, comparisons, multi-item results, charts, weather, flights, financial data, dashboards, or anything better presented visually than as plain text. Do NOT use for simple text answers, short factual replies, or casual conversation.',
-    '',
-    '**Important:** Dynamic UI availability is channel-dependent. Use the active channel onboarding playbook + transport guidance to decide whether to render UI directly or provide channel-safe text output with a clean dashboard handoff.',
-    '',
-    '### Routing rules',
-    '- **Blog posts, articles, essays, reports** → `document_create` (NOT app_create)',
-    '- **Tool auto-emissions** (e.g. `get_weather`): handled automatically — do nothing extra',
-    '- **Predefined domain data** (flights, stocks): `ui_show` with `surface_type: "dynamic_page"` and domain component classes',
-    '- **Simple structured data** (key-value, table, list): `ui_show` with `card`/`table`/`list`/`form` surface_type',
-    '- **Multi-step tasks** (ordering food, booking, purchasing, multi-phase workflows): `ui_show` with `card` surface_type + `data.template: "task_progress"` (see below)',
-    '- **Interactive apps only**: `app_create` (calculators, dashboards, tools - NOT text content)',
-    '',
-    '### Loading app tools',
-    'Most `app_*` tools (`app_create`, `app_update`, `app_file_edit`, `app_file_write`, `app_file_read`, `app_file_list`, `app_delete`, `app_list`, `app_query`) are provided by the `app-builder` skill. If they are not yet available, call `skill_load` with `id: "app-builder"` to load them. You only need to load the skill once per session. Note: `app_open` is always available as a core tool and does not require skill_load.',
-    '',
-    '### App type selection',
-    'When using `app_create`, set the `type` parameter:',
-    '- `"app"` (default) — interactive apps with data/state (calculators, dashboards, games)',
-    '- `"site"` — presentational sites (portfolios, landing pages, resumes)',
-    '',
-    '**app_create will ERROR if you try to create blog posts or articles. Use document_create instead.**',
-    '',
-    '### Using app_create (default for custom UIs)',
-    'When your user asks you to build, create, or visualize something that requires custom HTML, use `app_create`:',
-    '- Provide `name`, `html`, and `preview`. For apps, include `schema_json`; for sites (`type: "site"`), it defaults to `"{}"`',
-    '- `auto_open` defaults to true — the app opens immediately after creation',
-    '- Always include `preview`: `{ title, icon (emoji), metrics: [{ label, value }] }` for an inline chat card',
-    '- For iteration on an existing app: use `app_file_edit` for targeted code changes or `app_file_write` to rewrite a file. The surface refreshes automatically — no need to call `app_open`',
-    '- Home Base starts from a prebuilt scaffold. When updating Home Base, preserve required task-lane anchors and apply changes through `app_file_edit` or `app_file_write`',
-    '',
-    '### Quality standards',
-    '- Build immediately — make creative decisions, deliver polished output',
-    '- Anti-AI-slop rules: no flat cards with zero depth, no zero animations, 3+ text hierarchy levels, no plain backgrounds, hover+active states required on interactive elements',
-    '- Always: tight letter-spacing on headings, `clamp()` for display text, at least one accent gradient, distinct visual personality',
-    '- Toast notifications for all CRUD operations, `window.vellum.confirm()` for destructive actions',
-    '',
-    '### Using ui_show with domain components',
-    'For predefined domain data (flights, weather, stocks), write a self-contained HTML string using the domain component classes. The CSS design system (`vellum-design-system.css`) and JS widget library (`vellum-widgets.js`) are auto-injected. Call `ui_show` with `surface_type: "dynamic_page"` and `data: { html: "<your html>", preview: { title, subtitle?, description?, icon?, metrics? } }`.',
-    '',
-    '### Design system tokens',
-    'Semantic colors: `--v-bg`, `--v-surface`, `--v-surface-border`, `--v-text`, `--v-text-secondary`, `--v-text-muted`, `--v-accent`, `--v-success`, `--v-danger`, `--v-warning`.',
-    'Palettes: `--v-slate-{950..50}`, `--v-violet-*`, `--v-emerald-*`, `--v-rose-*`, `--v-amber-*`, `--v-indigo-*`.',
-    'Spacing: `--v-spacing-xs` through `--v-spacing-xxxl`. Radius: `--v-radius-sm`/`md`/`lg`/`pill`.',
-    '',
-    '### Component classes',
-    'Layout: `.v-card`, `.v-card-grid`, `.v-metric-card`, `.v-metric-grid`, `.v-data-table`, `.v-stat-row`, `.v-tabs`, `.v-accordion`, `.v-timeline`, `.v-divider`, `.v-page`, `.v-hero`, `.v-section-header`, `.v-pullquote`, `.v-comparison`, `.v-feature-grid`, `.v-feature-card`, `.v-gradient-text`, `.v-animate-in`.',
-    'Domain: `.v-flight-card`, `.v-weather-card`, `.v-stock-ticker`, `.v-billing-chart`, `.v-itinerary`, `.v-boarding-pass`, `.v-receipt`, `.v-invoice`.',
-    'UI: `.v-button` (`.secondary`/`.danger`/`.ghost`), `.v-badge`, `.v-status-badge` (`.success`/`.error`/`.warning`), `.v-progress-bar`, `.v-search-bar`, `.v-empty-state`, `.v-action-list`.',
-    'Action UI: `.v-action-bar` (`.v-action-bar-count`, `.v-action-bar-buttons`), `.v-action-progress`, `.v-group-header`, `.v-group-body`, `.v-row-removing`.',
-    '',
-    '### Widget JS APIs',
-    '```',
-    'vellum.widgets.sparkline(container, number[], {width, height, color})',
-    'vellum.widgets.barChart(container, [{label, value, color?}], {width, height, horizontal?})',
-    'vellum.widgets.lineChart(container, [{label, value}], {width, height, showDots?, showGrid?})',
-    'vellum.widgets.progressRing(container, value0to100, {size, color, label?})',
-    'vellum.widgets.sortTable(tableId)  — make .v-data-table sortable',
-    'vellum.widgets.tabs(tabsId)        — wire .v-tabs click behavior',
-    'vellum.openExternal(url)           — open URL in default browser',
-    'vellum.openLink(url, metadata?)    — open URL in user\'s browser (works everywhere incl. shared apps)',
-    'vellum.sendAction(actionId, data)  — send interaction back to assistant',
-    'vellum.widgets.groupedSelect(containerId, {actionBarId?, countId?})  — wire grouped multi-select with action bar',
-    'vellum.widgets.removeItems(ids, containerId, onComplete?)  — animate-remove processed items, auto-clean empty groups',
-    '```',
-    '',
-    '### Home Base interaction prompts',
-    'Home Base buttons send prefilled natural-language prompts through `vellum.sendAction`.',
-    'Treat these as normal user messages, not as direct execution commands.',
-    '- For appearance changes: keep customization color-first, ask for explicit confirmation before applying a full-dashboard update.',
-    '- For optional capability setup tasks (voice/computer control/ambient): keep them user-initiated and request permissions only when required for the chosen path.',
-    '- If a prompt is underspecified, ask one brief follow-up and continue.',
-    '',
-    '### External Links',
-    'When building apps with linkable items (search results, product cards, bookings), use `vellum.openLink(url, metadata)` to make them clickable.',
-    'Construct deep-link URLs when possible (airline booking pages, product pages, hotel reservations).',
-    'Include `metadata.provider` and `metadata.type` for context: `vellum.openLink("https://delta.com/book?flight=DL123", {provider: "delta", type: "booking"})`.',
-    '',
-    '### Example — Flight results page (ui_show with domain components)',
-    '```html',
-    '<div style="max-width:500px;margin:0 auto;display:flex;flex-direction:column;gap:12px">',
-    '  <h2 style="color:var(--v-text);margin:0">Flights: IAH → LGA</h2>',
-    '  <div class="v-flight-card">',
-    '    <div class="v-flight-header">',
-    '      <span class="v-flight-airline">Spirit</span>',
-    '      <span class="v-flight-price">$120</span>',
-    '    </div>',
-    '    <div class="v-flight-route">',
-    '      <div class="v-flight-endpoint"><div class="v-flight-time">6:38 PM</div><div class="v-flight-code">IAH</div></div>',
-    '      <div class="v-flight-duration"><span>3h 28m</span><div class="v-flight-line"></div><span>Nonstop</span></div>',
-    '      <div class="v-flight-endpoint"><div class="v-flight-time">11:06 PM</div><div class="v-flight-code">LGA</div></div>',
-    '    </div>',
-    '  </div>',
-    '</div>',
-    '```',
-    '',
-    '### Branding',
-    'A "Built on Vellum" badge is auto-injected into every dynamic page and app at the bottom-right corner. Do NOT add your own "Built on Vellum" or "Powered by Vellum" text — the badge is handled automatically by the rendering layer.',
-    '',
-    '### Tool chaining',
-    'After gathering data via tools (web search, browser, `get_weather`, APIs), synthesize results into a visual output rather than displaying raw tool outputs.',
-    '- **Weather**: `get_weather` automatically renders a dynamic page with a compact preview card. Do NOT call `ui_show` or `app_create` after `get_weather` — the weather surface is emitted directly. Just respond with a brief natural-language summary.',
-    '- **Research → Render**: When using browser/web search to research something visual (flights, hotels, products, comparisons), gather the data first, then compose it into a polished output — use `app_create` for custom UIs, or `ui_show` with domain component classes for predefined data types.',
-    '',
-    '### Presenting choices to your user',
-    'When you need your user to make a choice or provide structured input, prefer interactive UI surfaces over plain text:',
-    '- **Simple option selection** (2-8 choices): Use a `list` surface with `selectionMode: "single"`',
-    '- **Structured input** (names, settings, config): Use a `form` surface with typed fields',
-    '- **Complex configuration** (many fields, logical grouping): Use a multi-page `form` with `pages` array',
-    '- **Destructive or important actions**: Use a `confirmation` surface',
-    '- **Data review/selection**: Use a `table` surface with selectable rows',
-    '',
-    'Interactive surfaces provide a better user experience than asking your user to type their choice. Only fall back to plain text when the interaction is conversational or doesn\'t fit a structured format.',
-    '',
-    '### Task progress for multi-step workflows',
-    'When executing a multi-step task (booking a flight, purchasing, research with multiple phases), show live progress using the `task_progress` card template. Note: DoorDash ordering auto-emits a task_progress card on the first `vellum doordash` command (surface ID `doordash-progress`), so you only need `ui_update` for DoorDash flows.',
-    '',
-    '1. **Before starting**, call `ui_show` with `surface_type: "card"` and put `template: "task_progress"` inside `data`:',
-    '   ```json',
-    '   {',
-    '     "surface_type": "card",',
-    '     "data": {',
-    '       "title": "Booking Flight",',
-    '       "body": "",',
-    '       "template": "task_progress",',
-    '       "templateData": {',
-    '         "title": "Booking Flight",',
-    '         "status": "in_progress",',
-    '         "steps": [',
-    '           { "label": "Search flights", "status": "in_progress" },',
-    '           { "label": "Compare options", "status": "pending" },',
-    '           { "label": "Select flight", "status": "pending" },',
-    '           { "label": "Complete booking", "status": "pending" }',
-    '         ]',
-    '       }',
-    '     }',
-    '   }',
-    '   ```',
-    '2. **As each step completes**, call `ui_update` with the same surface ID and patch `data.templateData` (not top-level `status`/`steps`):',
-    '   ```json',
-    '   {',
-    '     "surface_id": "<surface-id>",',
-    '     "data": {',
-    '       "templateData": {',
-    '         "status": "in_progress",',
-    '         "steps": [',
-    '           { "label": "Search flights", "status": "completed", "detail": "Found 12 options" },',
-    '           { "label": "Compare options", "status": "in_progress" },',
-    '           { "label": "Select flight", "status": "pending" },',
-    '           { "label": "Complete booking", "status": "pending" }',
-    '         ]',
-    '       }',
-    '     }',
-    '   }',
-    '   ```',
-    '3. **On completion**, set `data.templateData.status` to `"completed"`. On failure, set it to `"failed"` and mark the failing step accordingly.',
-    '',
-    'Use this for ANY multi-step workflow where the user benefits from seeing structured progress instead of just "Running a command...".',
-  ].join('\n');
-}
-
-function buildActionableUiSection(): string {
-  return [
-    '## Actionable UI',
-    '',
-    '### When to use',
-    'When the user wants to triage, manage, or bulk-act on a collection of items (emails, files, notifications, tasks, subscriptions, contacts), generate an interactive UI that lets them review, select, and act on items directly.',
-    '',
-    '### Pattern',
-    '1. **Fetch data** — use the relevant tools to gather the items (e.g. `gmail_search`, file listing, etc.)',
-    '2. **Generate interactive UI** — render a `dynamic_page` with selectable items and action buttons',
-    '3. **User selects + clicks action** — the UI sends a `surfaceAction` with an action ID and selected item IDs',
-    '4. **Execute tools** — parse the action, call the appropriate tools (e.g. `gmail_batch_archive`, `gmail_unsubscribe`)',
-    '5. **Update UI** — use `ui_update` to remove processed items and show feedback via `widgets.toast()`',
-    '',
-    '### HTML structure',
-    'Choose the best layout for the data. Pick whatever fits the context:',
-    '- Grouped cards with checkboxes (e.g. email senders with message counts)',
-    '- Data tables with selectable rows (e.g. file listings)',
-    '- Kanban-style columns (e.g. triage into categories)',
-    '- Stacked list items with inline action buttons (e.g. notification feed)',
-    '- Any creative layout that makes sense for the data',
-    '',
-    'The key constraint: items must be selectable and action buttons must call `sendAction` with the selected item IDs.',
-    '',
-    '### CSS building blocks',
-    '- `.v-action-bar` — sticky bar at top, auto-hidden when nothing selected. Contains `.v-action-bar-count` ("N selected" label) and `.v-action-bar-buttons` (action button container)',
-    '- `.v-action-progress` — inline progress bar that replaces the action bar during bulk operations',
-    '- `.v-group-header` — collapsible section header with checkbox, title, count badge, and chevron',
-    '- `.v-group-body` — indented container for group items',
-    '- `.v-row-removing` — fade-out + slide animation class for processed items',
-    '',
-    '### Action data conventions',
-    '- Use semantic action IDs: `archive`, `unsubscribe`, `delete`, `move`, `mark_read`, etc.',
-    '- Always include selected item IDs: `sendAction("archive", { ids: ["msg_1", "msg_2"] })`',
-    '- For actions needing extra context, include it: `sendAction("move", { ids: [...], destination: "folder" })`',
-    '',
-    '### Processing flow',
-    '1. Parse the `surfaceAction` to get the action ID and data',
-    '2. Use `vellum.confirm(title, message)` for destructive actions (delete, unsubscribe) before executing',
-    '3. Call the relevant tools with the item IDs',
-    '4. Use `ui_update` to update the surface HTML (remove processed items, update counts)',
-    '5. Show `widgets.toast()` for feedback: success count, partial failure info',
-    '',
-    '### Error handling',
-    '- Handle partial failures: if 8 of 10 items succeed, remove the 8 successful ones and toast "Archived 8 items. 2 failed — try again."',
-    '- Keep failed items visible and selectable so the user can retry',
-    '',
-    '### Surface lifecycle',
-    '- Use `ui_show` with `display: "panel"` to keep the surface open alongside chat',
-    '- The surface stays alive for multiple action rounds (select → act → select more → act again)',
-    '- Use `widgets.groupedSelect()` to wire up grouped multi-select with action bar auto-show/hide',
-    '- Use `widgets.removeItems()` to animate processed items out and auto-clean empty groups',
-  ].join('\n');
-}
-
-function buildDocumentCreationSection(): string {
-  return [
-    '## Document Creation Workflow',
-    '',
-    'When creating documents with `document_create` (see Tool Routing for when to use this):',
-    '',
-    '**IMPORTANT: Call tools immediately, not after conversational preamble.**',
-    'Example: User says "write a blog post about X" → You immediately call `document_create`, then explain what you\'re doing.',
-    '',
-    '### Workflow Steps',
-    '1. **Create the document**: Call `document_create` with a title (inferred from the request)',
-    '   - The editor opens in full-screen workspace mode with chat docked to the side',
-    '   - The user sees a rich text editor powered by Toast UI Editor',
-    '',
-    '2. **Write content**: Generate the content in Markdown format',
-    '   - Write naturally and continuously',
-    '   - Use proper Markdown structure: `#` for titles, `##` for sections, `###` for subsections',
-    '   - Use **bold** and *italic* for emphasis',
-    '   - Include code blocks with ` ```language ` syntax',
-    '   - Add tables, lists, blockquotes as appropriate',
-    '',
-    '3. **CRITICAL - Stream content in chunks**: You MUST call `document_update` multiple times, NOT just once',
-    '   - Break your content into logical chunks (paragraphs, sections, or every 200-300 words)',
-    '   - Call `document_update` with `mode: "append"` for EACH chunk separately',
-    '   - DO NOT generate all content and send it in one call - this defeats the purpose of streaming',
-    '   - Think: "First paragraph" → call document_update → "Second paragraph" → call document_update → etc.',
-    '   - The user experiences real-time content appearing as you write, not a dump at the end',
-    '',
-    '4. **Respond to edits**: When the user requests changes via the docked chat',
-    '   - Listen for edit requests like "make the intro shorter", "add a section about X"',
-    '   - Generate the updated content',
-    '   - Use `document_update` with appropriate mode (replace for full rewrites, append for additions)',
-    '',
-    '### Content quality standards',
-    '- Write in clear, engaging prose appropriate for the content type',
-    '- Use active voice and vary sentence structure',
-    '- Break content into logical sections with descriptive headings',
-    '- Include transitions between sections',
-    '- For technical content: use code blocks with syntax highlighting',
-    '- For data-heavy content: use Markdown tables',
-    '',
-    '### Example flow',
-    '```',
-    'User: "Write a blog post about the future of AI"',
-    '',
-    'Assistant: "I\'ll create a document for your blog post about the future of AI."',
-    '  → Calls document_create with title: "The Future of AI"',
-    '',
-    'Assistant: (generates content in SEPARATE chunks - one document_update call per chunk)',
-    '  → document_update with mode: "append", content: "# The Future of AI\\n\\nArtificial intelligence..."',
-    '  → document_update with mode: "append", content: "## Current State\\n\\nToday\'s AI landscape..."',
-    '  → document_update with mode: "append", content: "The past decade has witnessed..."',
-    '  → document_update with mode: "append", content: "## Emerging Trends\\n\\nLooking ahead..."',
-    '',
-    'User (via docked chat): "Add a section about ethical considerations"',
-    '',
-    'Assistant: "I\'ll add a section on AI ethics."',
-    '  → document_update with mode: "append", content: "## Ethical Considerations\\n\\n..."',
-    '```',
-    '',
-    '### Important notes',
-    '- Documents are automatically saved and accessible via the Generated panel',
-    '- Users can manually edit documents at any time - your role is to help generate and refine content',
-    '- The editor supports drag-and-drop images, which are converted to base64 inline',
-    '- Word count is tracked automatically and displayed to the user',
-    '- Acknowledge the document creation in chat before opening the editor',
-  ].join('\n');
-}
 
 export function buildStarterTaskPlaybookSection(): string {
   return [
@@ -764,6 +408,66 @@ function buildAccessPreferenceSection(): string {
     '- Can I get the data via web_fetch?',
     '',
     'If yes to any of these, use that path instead of the browser.',
+    ...(isMacOS() ? [
+      '',
+      '### macOS App Automation',
+      '',
+      'When interacting with native macOS apps or performing system-level actions, prefer **osascript**',
+      'via host_bash over browser automation or computer-use.',
+      '',
+      'The following apps support AppleScript and should be automated via osascript:',
+      '',
+      '**Communication:** Messages, Mail, Microsoft Outlook, FaceTime',
+      '**Contacts & Calendar:** Contacts, Calendar, Reminders',
+      '**Notes & Writing:** Notes, TextEdit, Pages, BBEdit, CotEditor',
+      '**Files & Finder:** Finder, Path Finder',
+      '**Browsers:** Safari, Google Chrome',
+      '**Music & Media:** Music (iTunes), Spotify, VLC, Podcasts, TV',
+      '**Productivity:** OmniFocus, Things 3, OmniOutliner, OmniPlan, OmniGraffle',
+      '**Office:** Microsoft Word, Microsoft Excel, Numbers, Keynote',
+      '**Developer tools:** Xcode, Terminal, iTerm2, Script Editor',
+      '**System:** Finder, System Events (UI scripting for any app), System Settings',
+      '**Automation:** Keyboard Maestro, Alfred, Automator',
+      '**Creative:** Adobe Photoshop, Final Cut Pro',
+      '',
+      'For any other app, try osascript first — check scriptability with:',
+      '```bash',
+      'osascript -e \'tell application "AppName" to get name\'',
+      '```',
+      '',
+      'Common examples:',
+      '```bash',
+      '# Send an iMessage',
+      'osascript -e \'tell application "Messages" to send "Hello!" to buddy "user@example.com"\'',
+      '',
+      '# Look up a contact',
+      'osascript -e \'tell application "Contacts" to get {name, phones} of every person whose name contains "Marina"\'',
+      '',
+      '# Read upcoming calendar events',
+      'osascript -e \'tell application "Calendar" to get summary of every event of calendar "Home" whose start date > (current date)\'',
+      '',
+      '# Create a reminder',
+      'osascript -e \'tell application "Reminders" to make new reminder with properties {name:"Buy milk", due date:((current date) + 1 * hours)}\'',
+      '',
+      '# Send an email',
+      'osascript -e \'tell application "Mail" to send (make new outgoing message with properties {subject:"Hi", content:"Hello", visible:true})\'',
+      '',
+      '# Create a note',
+      'osascript -e \'tell application "Notes" to make new note at folder "Notes" with properties {body:"My note"}\'',
+      '',
+      '# Open a URL in Safari',
+      'osascript -e \'tell application "Safari" to open location "https://example.com"\'',
+      '',
+      '# Play/pause Music',
+      'osascript -e \'tell application "Music" to playpause\'',
+      '',
+      '# Display a system notification',
+      'osascript -e \'display notification "Done!" with title "Vellum"\'',
+      '```',
+      '',
+      'osascript (AppleScript/JXA) has direct, reliable access to macOS app APIs and system events.',
+      'Use it whenever the task involves a native macOS app or system-level interaction.',
+    ] : []),
   ].join('\n');
 }
 

package/src/config/vellum-skills/google-oauth-setup/SKILL.md

@@ -2,7 +2,7 @@
 name: "Google OAuth Setup"
 description: "Create Google Cloud OAuth credentials for Gmail integration using browser automation"
 user-invocable: true
-includes: ["browser"]
+includes: ["browser", "public-ingress"]
 metadata: {"vellum": {"emoji": "\ud83d\udd11"}}
 ---
 
@@ -10,6 +10,10 @@ You are helping your user create Google Cloud OAuth credentials so the Gmail and
 
 **Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
 
+## Prerequisites
+
+Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+
 ## Before You Start
 
 Tell the user:

package/src/config/vellum-skills/slack-oauth-setup/SKILL.md

@@ -2,7 +2,7 @@
 name: "Slack OAuth Setup"
 description: "Create Slack App and OAuth credentials for Slack integration using browser automation"
 user-invocable: true
-includes: ["browser"]
+includes: ["browser", "public-ingress"]
 metadata: {"vellum": {"emoji": "🔑"}}
 ---
 
@@ -10,6 +10,10 @@ You are helping your user create a Slack App and OAuth credentials so the Messag
 
 **Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
 
+## Prerequisites
+
+Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+
 ## Before You Start
 
 Tell the user:

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

@@ -2,6 +2,7 @@
 name: "Telegram Setup"
 description: "Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage"
 user-invocable: true
+includes: ["public-ingress"]
 metadata: {"vellum": {"emoji": "\ud83e\udd16"}}
 ---
 
@@ -10,7 +11,7 @@ You are helping your user connect a Telegram bot to the Vellum Assistant gateway
 ## What You Need
 
 1. **Bot token** from Telegram's @BotFather (the user provides this)
-2. **Gateway webhook URL** — derived from the canonical ingress setting: `${ingress.publicBaseUrl}/webhooks/telegram`. The gateway is the only publicly reachable endpoint; Telegram sends webhooks to the gateway, which validates and forwards them to the assistant runtime internally. If `ingress.publicBaseUrl` is configured (Settings UI > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var), use it to auto-derive the webhook URL. If it is not configured, ask the user to set it before proceeding.
+2. **Gateway webhook URL** — derived from the canonical ingress setting: `${ingress.publicBaseUrl}/webhooks/telegram`. The gateway is the only publicly reachable endpoint; Telegram sends webhooks to the gateway, which validates and forwards them to the assistant runtime internally. If `ingress.publicBaseUrl` is not configured, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the URL before continuing.
 
 If the user has already provided the bot token in the conversation, use it directly. Otherwise, ask for it.
 

package/src/daemon/handlers/config.ts

@@ -26,6 +26,10 @@ import type {
 import { log, CONFIG_RELOAD_DEBOUNCE_MS, defineHandlers, type HandlerContext } from './shared.js';
 import { MODEL_TO_PROVIDER } from '../session-slash.js';
 
+// Snapshot the env-provided value at module load time so we can restore it
+// when the user clears a Settings-set override.
+const ORIGINAL_INGRESS_ENV = process.env.INGRESS_PUBLIC_BASE_URL;
+
 export function handleModelGet(socket: net.Socket, ctx: HandlerContext): void {
   const config = getConfig();
   const configured = Object.keys(config.apiKeys).filter((k) => !!config.apiKeys[k]);
@@ -416,7 +420,8 @@ export function handleIngressConfig(
       const raw = loadRawConfig();
       const ingress = (raw?.ingress ?? {}) as Record<string, unknown>;
       const publicBaseUrl = (ingress.publicBaseUrl as string) ?? '';
-      ctx.send(socket, { type: 'ingress_config_response', publicBaseUrl, localGatewayTarget, success: true });
+      const enabled = (ingress.enabled as boolean) ?? false;
+      ctx.send(socket, { type: 'ingress_config_response', enabled, publicBaseUrl, localGatewayTarget, success: true });
     } else if (msg.action === 'set') {
       const value = (msg.publicBaseUrl ?? '').trim().replace(/\/+$/, '');
       const raw = loadRawConfig();
@@ -424,10 +429,13 @@ export function handleIngressConfig(
       // Update ingress.publicBaseUrl — this is the single source of truth for
       // the canonical public ingress URL. The gateway receives this value via
       // the INGRESS_PUBLIC_BASE_URL env var at spawn time (see hatch.ts).
-      // A gateway restart is required for the new value to take effect in
-      // inbound Twilio signature validation.
+      // The gateway also validates Twilio signatures against forwarded public
+      // URL headers, so local tunnel updates generally apply without restarts.
       const ingress = (raw?.ingress ?? {}) as Record<string, unknown>;
       ingress.publicBaseUrl = value || undefined;
+      if (msg.enabled !== undefined) {
+        ingress.enabled = msg.enabled;
+      }
 
       const wasSuppressed = ctx.suppressConfigReload;
       ctx.setSuppressConfigReload(true);
@@ -443,24 +451,27 @@ export function handleIngressConfig(
       ctx.debounceTimers.set('__suppress_reset__', resetTimer);
 
       // Propagate to the gateway's process environment so it picks up the
-      // new URL on its next config load. For the local-deployment path the
+      // new URL when it is restarted. For the local-deployment path the
       // gateway runs as a child process that inherited the assistant's env,
       // so updating process.env here ensures the value is visible when the
       // gateway is restarted (e.g. by the self-upgrade skill or a manual
       // `pkill -f gateway`).
       if (value) {
         process.env.INGRESS_PUBLIC_BASE_URL = value;
+      } else if (ORIGINAL_INGRESS_ENV !== undefined) {
+        process.env.INGRESS_PUBLIC_BASE_URL = ORIGINAL_INGRESS_ENV;
+      } else {
+        delete process.env.INGRESS_PUBLIC_BASE_URL;
       }
-      // When cleared, do NOT delete the env var — the original env-provided
-      // value (if any) serves as a fallback per the documented precedence model.
 
-      ctx.send(socket, { type: 'ingress_config_response', publicBaseUrl: value, localGatewayTarget, success: true });
+      const enabled = (ingress.enabled as boolean) ?? false;
+      ctx.send(socket, { type: 'ingress_config_response', enabled, publicBaseUrl: value, localGatewayTarget, success: true });
     } else {
-      ctx.send(socket, { type: 'ingress_config_response', publicBaseUrl: '', localGatewayTarget, success: false, error: `Unknown action: ${String((msg as unknown as Record<string, unknown>).action)}` });
+      ctx.send(socket, { type: 'ingress_config_response', enabled: false, publicBaseUrl: '', localGatewayTarget, success: false, error: `Unknown action: ${String((msg as unknown as Record<string, unknown>).action)}` });
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    ctx.send(socket, { type: 'ingress_config_response', publicBaseUrl: '', localGatewayTarget, success: false, error: message });
+    ctx.send(socket, { type: 'ingress_config_response', enabled: false, publicBaseUrl: '', localGatewayTarget, success: false, error: message });
   }
 }
 

package/src/daemon/handlers/home-base.ts

@@ -66,9 +66,10 @@ export function handleHomeBaseGet(
       },
     });
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, 'Failed to resolve home base metadata');
-    ctx.send(socket, { type: 'error', message: `Failed to resolve home base metadata: ${message}` });
+    // Return null rather than surfacing an error banner to the user —
+    // the chat still works fine without home base metadata.
+    ctx.send(socket, { type: 'home_base_get_response', homeBase: null });
   }
 }