@vellumai/assistant 0.4.2 → 0.4.4

package/src/calls/twilio-config.ts

@@ -15,18 +15,11 @@ export interface TwilioConfig {
   wssBaseUrl: string;
 }
 
-function resolveTwilioPhoneNumber(assistantId: string | undefined, config: ReturnType<typeof loadConfig>): string {
+function resolveTwilioPhoneNumber(config: ReturnType<typeof loadConfig>, assistantId?: string): string {
   if (assistantId) {
-    const assistantPhone = config.sms?.assistantPhoneNumbers?.[assistantId];
-    if (assistantPhone) {
-      return assistantPhone;
-    }
+    const scoped = (config.sms?.assistantPhoneNumbers as Record<string, string> | undefined)?.[assistantId];
+    if (scoped) return scoped;
   }
-
-  // Global fallback order:
-  // 1. TWILIO_PHONE_NUMBER env var (explicit override)
-  // 2. config file sms.phoneNumber (primary storage)
-  // 3. credential:twilio:phone_number secure key (backward-compat fallback)
   return getTwilioPhoneNumberEnv() || config.sms?.phoneNumber || getSecureKey('credential:twilio:phone_number') || '';
 }
 
@@ -34,7 +27,7 @@ export function getTwilioConfig(assistantId?: string): TwilioConfig {
   const accountSid = getSecureKey('credential:twilio:account_sid');
   const authToken = getSecureKey('credential:twilio:auth_token');
   const config = loadConfig();
-  const phoneNumber = resolveTwilioPhoneNumber(assistantId, config);
+  const phoneNumber = resolveTwilioPhoneNumber(config, assistantId);
   const webhookBaseUrl = getPublicBaseUrl(config);
 
   // Always use the centralized relay URL derived from the public ingress base URL.

package/src/calls/twilio-routes.ts

@@ -147,10 +147,9 @@ function mapTwilioStatus(twilioStatus: string): CallStatus | null {
  * Supports two modes:
  * - **Outbound** (callSessionId present in query): uses the existing session
  * - **Inbound** (callSessionId absent): creates or reuses a session keyed
- *   by the Twilio CallSid. The optional `forwardedAssistantId` is resolved
- *   by the gateway from the "To" phone number.
+ *   by the Twilio CallSid. Uses daemon internal scope for assistant identity.
  */
-export async function handleVoiceWebhook(req: Request, forwardedAssistantId?: string): Promise<Response> {
+export async function handleVoiceWebhook(req: Request): Promise<Response> {
   const url = new URL(req.url);
   const callSessionId = url.searchParams.get('callSessionId');
 
@@ -167,13 +166,12 @@ export async function handleVoiceWebhook(req: Request, forwardedAssistantId?: st
       return new Response('Missing CallSid', { status: 400 });
     }
 
-    log.info({ callSid, from: callerFrom, to: callerTo, assistantId: forwardedAssistantId }, 'Inbound voice webhook — creating/reusing session');
+    log.info({ callSid, from: callerFrom, to: callerTo }, 'Inbound voice webhook — creating/reusing session');
 
     const { session } = createInboundVoiceSession({
       callSid,
       fromNumber: callerFrom,
       toNumber: callerTo,
-      assistantId: forwardedAssistantId,
     });
 
     return buildVoiceWebhookTwiml(session.id, session.assistantId ?? undefined, session.task, session.guardianVerificationSessionId);
@@ -254,7 +252,7 @@ function buildVoiceWebhookTwiml(
     });
   }
 
-  const twilioConfig = getTwilioConfig(assistantId);
+  const twilioConfig = getTwilioConfig();
   let relayUrl: string;
   try {
     relayUrl = getTwilioRelayUrl(loadConfig());

package/src/calls/types.ts

@@ -1,5 +1,7 @@
 export type CallStatus = 'initiated' | 'ringing' | 'in_progress' | 'waiting_on_user' | 'completed' | 'failed' | 'cancelled';
-export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'user_instruction_relayed' | 'call_ended' | 'call_failed' | 'callee_verification_started' | 'callee_verification_succeeded' | 'callee_verification_failed' | 'guardian_voice_verification_started' | 'guardian_voice_verification_succeeded' | 'guardian_voice_verification_failed' | 'outbound_guardian_voice_verification_started' | 'outbound_guardian_voice_verification_succeeded' | 'outbound_guardian_voice_verification_failed' | 'guardian_consultation_timed_out' | 'guardian_unavailable_skipped' | 'guardian_consult_deferred' | 'guardian_consult_coalesced' | 'inbound_acl_denied' | 'invite_redemption_started' | 'invite_redemption_succeeded' | 'invite_redemption_failed';
+export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'user_instruction_relayed' | 'call_ended' | 'call_failed' | 'callee_verification_started' | 'callee_verification_succeeded' | 'callee_verification_failed' | 'guardian_voice_verification_started' | 'guardian_voice_verification_succeeded' | 'guardian_voice_verification_failed' | 'outbound_guardian_voice_verification_started' | 'outbound_guardian_voice_verification_succeeded' | 'outbound_guardian_voice_verification_failed' | 'guardian_consultation_timed_out' | 'guardian_unavailable_skipped' | 'guardian_consult_deferred' | 'guardian_consult_coalesced' | 'inbound_acl_denied' | 'inbound_acl_name_capture_started' | 'inbound_acl_name_captured' | 'inbound_acl_name_capture_timeout' | 'inbound_acl_access_approved' | 'inbound_acl_access_denied' | 'inbound_acl_access_timeout' | 'invite_redemption_started' | 'invite_redemption_succeeded' | 'invite_redemption_failed' | 'voice_guardian_wait_heartbeat_sent' | 'voice_guardian_wait_prompt_classified' | 'voice_guardian_wait_callback_offer_sent' | 'voice_guardian_wait_callback_opt_in_set' | 'voice_guardian_wait_callback_opt_in_declined'
+  | 'callback_handoff_notified'
+  | 'callback_handoff_failed';
 export type PendingQuestionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
 
 /**

package/src/calls/voice-session-bridge.ts

@@ -19,6 +19,7 @@ import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.
 import { resolveChannelCapabilities } from '../daemon/session-runtime-assembly.js';
 import { buildAssistantEvent } from '../runtime/assistant-event.js';
 import { assistantEventHub } from '../runtime/assistant-event-hub.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../runtime/assistant-scope.js';
 import { checkIngressForSecrets } from '../security/secret-ingress.js';
 import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { IngressBlockedError } from '../util/errors.js';
@@ -306,7 +307,7 @@ export async function startVoiceTurn(opts: VoiceTurnOptions): Promise<VoiceTurnH
     ...session.memoryPolicy,
     strictSideEffects,
   };
-  session.setAssistantId(opts.assistantId ?? 'self');
+  session.setAssistantId(opts.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID);
   session.callSessionId = opts.callSessionId;
   session.setGuardianContext(opts.guardianContext ?? null);
   session.setCommandIntent(null);
@@ -330,7 +331,7 @@ export async function startVoiceTurn(opts: VoiceTurnOptions): Promise<VoiceTurnH
         ? (msg as { sessionId: string }).sessionId
         : undefined;
     const resolvedSessionId = msgSessionId ?? opts.conversationId;
-    const event = buildAssistantEvent('self', msg, resolvedSessionId);
+    const event = buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, msg, resolvedSessionId);
     hubChain = (async () => {
       await hubChain;
       try {
@@ -364,7 +365,7 @@ export async function startVoiceTurn(opts: VoiceTurnOptions): Promise<VoiceTurnH
             toolName: msg.toolName,
             inputDigest,
             consumingRequestId: msg.requestId,
-            assistantId: opts.assistantId ?? 'self',
+            assistantId: opts.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
             executionChannel: 'voice',
             conversationId: opts.conversationId,
             callSessionId: opts.callSessionId,

package/src/cli/core-commands.ts

@@ -107,8 +107,9 @@ export function registerDaemonCommand(program: Command): void {
 export function registerDevCommand(program: Command): void {
   program
     .command('dev')
-    .description('Run the daemon in dev mode with auto-restart on file changes')
-    .action(async () => {
+    .description('Run the daemon in dev mode')
+    .option('--watch', 'Auto-restart on source file changes (disruptive during Claude Code sessions)')
+    .action(async (opts: { watch?: boolean }) => {
       let status = await getDaemonStatus();
       if (status.running) {
         log.info('Stopping existing daemon...');
@@ -161,10 +162,12 @@ export function registerDevCommand(program: Command): void {
 
       const mainPath = `${import.meta.dirname}/../daemon/main.ts`;
 
-      log.info('Starting daemon in dev mode (Ctrl+C to stop)');
+      const useWatch = opts.watch === true;
+      log.info(`Starting daemon in dev mode${useWatch ? ' with file watching' : ''} (Ctrl+C to stop)`);
 
       const repoRoot = join(import.meta.dirname, '..', '..', '..');
-      const child = spawn('bun', ['--watch', 'run', mainPath], {
+      const args = useWatch ? ['--watch', 'run', mainPath] : ['run', mainPath];
+      const child = spawn('bun', args, {
         stdio: 'inherit',
         env: {
           ...process.env,

package/src/cli.ts

@@ -233,7 +233,7 @@ export async function startCli(): Promise<void> {
     process.stdout.write(`\u2502\n`);
     process.stdout.write(`\u2502 [a] Allow once\n`);
     process.stdout.write(`\u2502 [d] Deny once\n`);
-    if (req.allowlistOptions.length > 0) {
+    if (req.allowlistOptions.length > 0 && req.scopeOptions.length > 0) {
       process.stdout.write(`\u2502 [A] Allowlist...\n`);
       process.stdout.write(`\u2502 [H] Allowlist (high-risk)...\n`);
       process.stdout.write(`\u2502 [D] Denylist...\n`);
@@ -246,21 +246,22 @@ export async function startCli(): Promise<void> {
       const choice = trimmed.toLowerCase();
 
       // Uppercase 'A' → allowlist pattern selection (check before lowercase 'a')
-      if (trimmed === 'A' || choice === 'allowlist') {
+      // Only process when scope options exist, matching the display guard above
+      if ((trimmed === 'A' || choice === 'allowlist') && req.allowlistOptions.length > 0 && req.scopeOptions.length > 0) {
         // pendingConfirmation stays true through sub-prompts
         renderPatternSelection(req, 'always_allow');
         return;
       }
 
       // Uppercase 'H' → high-risk allowlist pattern selection
-      if (trimmed === 'H') {
+      if (trimmed === 'H' && req.allowlistOptions.length > 0 && req.scopeOptions.length > 0) {
         // pendingConfirmation stays true through sub-prompts
         renderPatternSelection(req, 'always_allow_high_risk');
         return;
       }
 
       // Uppercase 'D' → denylist pattern selection (check before lowercase 'd')
-      if (trimmed === 'D' || choice === 'denylist') {
+      if ((trimmed === 'D' || choice === 'denylist') && req.allowlistOptions.length > 0 && req.scopeOptions.length > 0) {
         // pendingConfirmation stays true through sub-prompts
         renderPatternSelection(req, 'always_deny');
         return;

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

@@ -14,6 +14,10 @@ Example: `host_bash("vellum email status --json")`
 
 Never use browser/computer-use unless user explicitly approves fallback.
 
+## When to Use This Skill
+
+This skill manages the **assistant's own** AgentMail address (`@agentmail.to`) — not the user's personal email. Only use this skill when the user explicitly asks the assistant to send email **from the assistant's own address**, manage the assistant's inbox, or perform operations on the assistant's AgentMail account. Generic email requests ("send an email", "check my email", "draft a reply") are about the **user's Gmail** and should be handled by the Messaging skill instead.
+
 ## Rules
 
 - Always run `vellum email` commands via `host_bash` and parse JSON output.

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

@@ -34,6 +34,7 @@ These are hard prohibitions. Violating any of these produces that unmistakable "
 - **NEVER** make all text the same size and weight — establish clear hierarchy with at least 3 distinct levels
 - **NEVER** use a pure white (`#fff`) or pure dark (`#000`/`#0a0a0a`) background — ALWAYS tint it to match the domain (cream `#FEFCF9` for lifestyle, sage `#F0F5F0` for nature, cool gray `#F5F7FA` for finance, warm blush `#FDF6F3` for wellness)
 - **NEVER** leave clickable elements without hover AND active states
+- **NEVER** hand-code SVG/CSS charts (lines, bars, sparklines, gauges) — ALWAYS use `vellum.widgets.lineChart()`, `.barChart()`, `.sparkline()`, or `.progressRing()`. They handle bounds, clipping, scaling, and dark mode correctly. Hand-coded charts invariably overflow and bleed into adjacent elements.
 - **ALWAYS** use emoji as visual identifiers in stat cards, list items, and navigation — they replace icon libraries and add instant personality (🍎 for food, 🔥 for streaks, 💰 for money, 🌿 for plants)
 - **ALWAYS** apply the accent-word pattern in hero headings — color ONE key word or phrase in the accent color: "Your <span style='color: var(--accent)'>Week</span> in Motion"
 - **ALWAYS** include a contextual/personalized header — a greeting ("Good morning"), date ("Saturday, Feb 15"), or welcome ("Welcome back, Alex") — not just the app title
@@ -92,6 +93,23 @@ These are hard prohibitions. Violating any of these produces that unmistakable "
 Copy-paste-ready CSS techniques. All work in the sandboxed WebView with no external dependencies.
 
 ### Animated Gradient Background
+
+Choose **one** of the following color variants (do not combine both):
+
+**Variant A — Warm pastels (light, airy feel):**
+```css
+body {
+  background: linear-gradient(-45deg, #fef3c7, #fce7f3, #e0e7ff, #d1fae5);
+  background-size: 400% 400%;
+  animation: gradientShift 15s ease infinite;
+}
+@keyframes gradientShift {
+  0%, 100% { background-position: 0% 50%; }
+  50% { background-position: 100% 50%; }
+}
+```
+
+**Variant B — Dark jewel tones (deep, rich feel):**
 ```css
 body {
   background: linear-gradient(-45deg, #0f172a, #1e1b4b, #172554, #0c4a6e);
@@ -108,9 +126,9 @@ body {
 ```css
 body {
   background:
-    radial-gradient(ellipse at 20% 50%, color-mix(in srgb, var(--v-violet-500) 15%, transparent) 0%, transparent 50%),
-    radial-gradient(ellipse at 80% 20%, color-mix(in srgb, var(--v-indigo-500) 12%, transparent) 0%, transparent 50%),
-    radial-gradient(ellipse at 50% 80%, color-mix(in srgb, var(--v-emerald-500) 8%, transparent) 0%, transparent 50%),
+    radial-gradient(ellipse at 20% 50%, color-mix(in srgb, var(--v-rose-400) 15%, transparent) 0%, transparent 50%),
+    radial-gradient(ellipse at 80% 20%, color-mix(in srgb, var(--v-amber-400) 12%, transparent) 0%, transparent 50%),
+    radial-gradient(ellipse at 50% 80%, color-mix(in srgb, var(--v-teal-400) 10%, transparent) 0%, transparent 50%),
     var(--v-bg);
 }
 ```
@@ -161,7 +179,7 @@ body::before {
 ### Gradient Text
 ```css
 .gradient-text {
-  background: linear-gradient(135deg, var(--v-violet-500), var(--v-indigo-400));
+  background: linear-gradient(135deg, var(--v-rose-500), var(--v-amber-400));
   -webkit-background-clip: text;
   -webkit-text-fill-color: transparent;
   background-clip: text;
@@ -348,7 +366,7 @@ document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
 .accent-word { color: var(--accent, var(--v-accent)); }
 /* Gradient variant — use .v-gradient-text from the design system, or customize: */
 .accent-gradient {
-  background: linear-gradient(135deg, var(--accent, var(--v-violet-500)), var(--v-indigo-400));
+  background: linear-gradient(135deg, var(--accent, var(--v-rose-500)), var(--v-amber-400));
   -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;
 }
 ```
@@ -673,6 +691,28 @@ Wrap in `.v-metric-grid` for responsive 2-4 column layout. Always use a semantic
 
 `.v-pullquote` — Blockquote with gradient accent border. `.v-comparison` — Before/after cards (3-column grid with `.before`/`.after` modifiers). `.v-page` — Centered container (max-width 600px). Use `.v-animate-in` on children for staggered fade-in. Use `.v-gradient-text` for accent-colored gradient text.
 
+`.v-slideshow` — Presentation slide deck with transitions and navigation. Init with `vellum.widgets.slideshow()`:
+```html
+<div class="v-slideshow" id="deck">
+  <div class="v-slide">
+    <div class="v-slide-header">
+      <span class="v-slide-label">Overview</span>
+    </div>
+    <h1 class="v-slide-title">The city that never <span class="accent-word">sleeps</span></h1>
+    <p class="v-slide-body">Body text here...</p>
+    <div class="v-slide-stats">
+      <div class="v-slide-stat">
+        <span class="v-slide-stat-value">8.3M</span>
+        <span class="v-slide-stat-label">Residents</span>
+      </div>
+    </div>
+  </div>
+  <div class="v-slide"><!-- Slide 2 --></div>
+  <div class="v-slide"><!-- Slide 3 --></div>
+</div>
+```
+Slide content helpers: `.v-slide-label` (section label with colored dot), `.v-slide-title` (responsive heading), `.v-slide-body` (body text, max-width 540px), `.v-slide-stats` (auto-fit grid), `.v-slide-stat` / `.v-slide-stat-value` / `.v-slide-stat-label` (big-number cards), `.v-slide-quote` / `.v-slide-quote-attribution` (blockquote), `.v-slide-list` (styled list), `.v-slide-columns` / `.v-slide-column` (2-column comparison grid).
+
 #### Widget JavaScript utilities
 
 Interactive utilities at `window.vellum.widgets.*`:
@@ -724,6 +764,13 @@ vellum.widgets.toast('Connection lost', 'error', 0);      // Manual dismiss
 vellum.widgets.countdown('timer-el', '2025-12-31T00:00:00Z', {
   onComplete: () => console.log('Done!')
 });
+
+// Slideshow — presentation deck with transitions and navigation
+vellum.widgets.slideshow('deck', {
+  transition: 'fade', showDots: true, showArrows: true,
+  showCounter: true, keyboard: true, loop: true
+});
+// Returns: { goTo(index), next(), prev() }
 ```
 
 #### Composition recipes
@@ -992,12 +1039,147 @@ async function handleBulk(action) {
 }
 ```
 
+**Presentation slideshow** — multi-slide deck with 8 layout variants (title, stats, bullets, quote, comparison, visual, timeline, closing). Use the slideshow widget for presentations, pitch decks, and multi-slide educational content. The model provides slide content; the widget handles navigation, transitions, and keyboard support. Never tell the user how to navigate slides — the UI is self-explanatory.
+
+> **For comprehensive slide design guidelines, see the "Presentation Slide Design" section below.** The following HTML shows the structural template for all 8 layout types.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<style>
+  :root { --v-accent: #8B5CF6; }
+  body { margin: 0; padding: 0; background: linear-gradient(-45deg, #0f172a, #1e1b4b, #172554); min-height: 100vh; }
+  .v-slideshow { border-radius: 0; min-height: 100vh; }
+  .accent-word { color: var(--v-accent); }
+  .trust-pill { display: inline-flex; align-items: center; gap: 6px; padding: 6px 14px; border-radius: 999px; font-size: 13px; font-weight: 500; background: color-mix(in srgb, var(--v-surface) 60%, transparent); border: 1px solid var(--v-surface-border); color: var(--v-text-secondary); margin-top: var(--v-spacing-lg); }
+  .trust-pill.accent { border-color: color-mix(in srgb, var(--v-accent) 30%, transparent); color: var(--v-accent); }
+  .v-slide-list li { font-size: 15px; line-height: 1.7; }
+  .v-slide-columns h3 { margin: 0 0 var(--v-spacing-sm); color: var(--v-text); font-size: var(--v-font-size-lg); }
+  .slide-visual { position: relative; overflow: hidden; }
+  .slide-visual-bg { position: absolute; inset: 0; background: radial-gradient(ellipse at 30% 40%, color-mix(in srgb, var(--v-accent) 15%, transparent), transparent 70%), radial-gradient(ellipse at 70% 60%, color-mix(in srgb, var(--v-forest-500, #22c55e) 10%, transparent), transparent 60%); }
+  .slide-visual-overlay { position: relative; z-index: 1; background: color-mix(in srgb, var(--v-bg) 40%, transparent); backdrop-filter: blur(20px); -webkit-backdrop-filter: blur(20px); border-radius: var(--v-radius-lg); padding: var(--v-spacing-xl); max-width: 500px; }
+</style>
+</head>
+<body>
+<div class="v-slideshow" id="deck">
+
+  <!-- 1. Title slide -->
+  <div class="v-slide">
+    <span class="v-slide-label">Introduction</span>
+    <h1 class="v-slide-title">The city that never <span class="accent-word">sleeps</span></h1>
+    <p class="v-slide-body">A brief subtitle or tagline here.</p>
+    <span class="trust-pill accent">&#x1f5fd; 8.3 million residents</span>
+  </div>
+
+  <!-- 2. Content + Stats slide -->
+  <div class="v-slide">
+    <span class="v-slide-label">By the Numbers</span>
+    <h2 class="v-slide-title">Economy at a glance</h2>
+    <p class="v-slide-body">New York generates more GDP than most countries...</p>
+    <div class="v-slide-stats">
+      <div class="v-slide-stat"><span class="v-slide-stat-value">$2.1T</span><span class="v-slide-stat-label">Metro GDP</span></div>
+      <div class="v-slide-stat"><span class="v-slide-stat-value">4.7M</span><span class="v-slide-stat-label">Jobs</span></div>
+      <div class="v-slide-stat"><span class="v-slide-stat-value">#1</span><span class="v-slide-stat-label">Financial Hub</span></div>
+    </div>
+  </div>
+
+  <!-- 3. Bullet points slide -->
+  <div class="v-slide">
+    <span class="v-slide-label">Culture</span>
+    <h2 class="v-slide-title">What makes it <span class="accent-word">unique</span></h2>
+    <ul class="v-slide-list">
+      <li>&#x1f3ad; Broadway — 41 professional theaters in the Theater District</li>
+      <li>&#x1f3db;&#xfe0f; 80+ world-class museums including the Met and MoMA</li>
+      <li>&#x1f355; Over 27,000 restaurants spanning every cuisine on earth</li>
+      <li>&#x1f333; 843 acres of Central Park in the heart of Manhattan</li>
+    </ul>
+  </div>
+
+  <!-- 4. Quote slide -->
+  <div class="v-slide" style="justify-content: center; align-items: center; text-align: center;">
+    <div class="v-slide-quote" style="border-left: none; padding-left: 0;">
+      "There is no place like New York. It is the most exciting city in the world."
+    </div>
+    <div class="v-slide-quote-attribution">— John Updike</div>
+  </div>
+
+  <!-- 5. Comparison / Two-column slide -->
+  <div class="v-slide">
+    <span class="v-slide-label">Comparison</span>
+    <h2 class="v-slide-title">Manhattan vs Brooklyn</h2>
+    <div class="v-slide-columns">
+      <div class="v-slide-column">
+        <h3>&#x1f3d9;&#xfe0f; Manhattan</h3>
+        <p class="v-slide-body" style="margin-bottom: var(--v-spacing-sm);">Financial center, dense skyscrapers, high-energy nightlife, world-famous landmarks.</p>
+        <span class="v-slide-stat-value">1.6M</span>
+        <span class="v-slide-stat-label">Population</span>
+      </div>
+      <div class="v-slide-column">
+        <h3>&#x1f309; Brooklyn</h3>
+        <p class="v-slide-body" style="margin-bottom: var(--v-spacing-sm);">Creative hub, brownstone neighborhoods, artisan food scene, waterfront parks.</p>
+        <span class="v-slide-stat-value">2.7M</span>
+        <span class="v-slide-stat-label">Population</span>
+      </div>
+    </div>
+  </div>
+
+  <!-- 6. Image/visual slide -->
+  <div class="v-slide slide-visual">
+    <div class="slide-visual-bg"></div>
+    <div class="slide-visual-overlay">
+      <span class="v-slide-label">Skyline</span>
+      <h2 class="v-slide-title">An iconic <span class="accent-word">horizon</span></h2>
+      <p class="v-slide-body">The Manhattan skyline is recognized worldwide...</p>
+    </div>
+  </div>
+
+  <!-- 7. Timeline slide -->
+  <div class="v-slide">
+    <span class="v-slide-label">History</span>
+    <h2 class="v-slide-title">Key <span class="accent-word">milestones</span></h2>
+    <div class="v-timeline" style="margin-top: var(--v-spacing-lg);">
+      <div class="v-timeline-entry"><span class="v-timeline-time">1626</span><span class="v-timeline-title">Manhattan purchased</span></div>
+      <div class="v-timeline-entry"><span class="v-timeline-time">1886</span><span class="v-timeline-title">Statue of Liberty dedicated</span></div>
+      <div class="v-timeline-entry active"><span class="v-timeline-time">1931</span><span class="v-timeline-title">Empire State Building opens</span></div>
+    </div>
+  </div>
+
+  <!-- 8. Closing / CTA slide -->
+  <div class="v-slide" style="text-align: center; align-items: center;">
+    <h1 class="v-slide-title">The world's <span class="accent-word">capital</span></h1>
+    <p class="v-slide-body" style="max-width: 400px;">New York isn't just a city — it's an idea that never stops evolving.</p>
+    <div class="v-slide-stats" style="margin-top: var(--v-spacing-xxl);">
+      <div class="v-slide-stat"><span class="v-slide-stat-value">800+</span><span class="v-slide-stat-label">Languages spoken</span></div>
+      <div class="v-slide-stat"><span class="v-slide-stat-value">62M</span><span class="v-slide-stat-label">Annual visitors</span></div>
+    </div>
+  </div>
+
+</div>
+<script>
+document.addEventListener('DOMContentLoaded', function() {
+  vellum.widgets.slideshow('deck', {
+    transition: 'fade',
+    showDots: true,
+    showArrows: true,
+    showCounter: true,
+    keyboard: true,
+    loop: true
+  });
+});
+</script>
+</body>
+</html>
+```
+
 #### When to use widgets vs custom HTML
 
-- **Use widgets** for standard patterns — tables, metrics, timelines, notifications
+- **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 prioritize the ideal user experience over using the widget library
+- Always prioritize the ideal user experience over using the widget library — EXCEPT for charts: always use `vellum.widgets.*` chart functions (lineChart, barChart, sparkline, progressRing) instead of hand-coding SVG/CSS charts. They handle overflow clipping, bounds, scaling, and dark mode. Hand-coded charts break layouts.
 
 #### Advanced techniques
 
@@ -1170,7 +1352,25 @@ Both `ui_show` and `app_create` support a `preview` object for an inline chat pr
 }
 ```
 
-**With `app_create`:**
+**With `app_create` (image URL icon):**
+```json
+{
+  "name": "Microsoft Overview",
+  "schema_json": "{}",
+  "html": "...",
+  "preview": {
+    "title": "Microsoft",
+    "subtitle": "3 Slides",
+    "icon": "https://www.microsoft.com/favicon.ico",
+    "metrics": [
+      { "label": "Founded", "value": "1975" },
+      { "label": "Market Cap", "value": "$2.98T" }
+    ]
+  }
+}
+```
+
+**With `app_create` (emoji icon):**
 ```json
 {
   "name": "Expense Tracker",
@@ -1187,7 +1387,7 @@ Both `ui_show` and `app_create` support a `preview` object for an inline chat pr
 }
 ```
 
-Preview fields: `title` (required), `subtitle`, `description`, `icon` (emoji), `metrics` (up to 3 key-value pills). When `app_create` is called with `auto_open: true` (the default), the preview is forwarded through `app_open` automatically.
+Preview fields: `title` (required), `subtitle`, `description`, `icon`, `metrics` (up to 3 key-value pills). The `icon` field accepts an emoji or an image URL. **Prefer an image URL whenever you have a relevant one** — logos, favicons, product images, headshots, flags, album art, or any image you encountered during research. The preview card renders image URLs as a thumbnail automatically. Fall back to emoji only when there is no natural image. When `app_create` is called with `auto_open: true` (the default), the preview is forwarded through `app_open` automatically.
 
 ### 6. Handle Iteration
 
@@ -1326,8 +1526,107 @@ Before delivering any app, mentally verify these 10 items — they cover the gap
 | `.v-pill-toggles` | Time range / filter toggle group | `.v-pill-toggle` (`.active`) — container with pill buttons |
 | `.v-chip-group` | Suggestion / filter chip row | `.v-chip` (`.active`) — wrapping row of clickable pills |
 | `.v-metric-card .v-metric-icon` | Emoji icon in metric cards | Place emoji `<span>` with `.v-metric-icon` inside `.v-metric-card` |
+| `.v-slideshow` | Presentation slide deck with transitions | `.v-slide` (`.active`), `.v-slide-label`, `.v-slide-title`, `.v-slide-body`, `.v-slide-stats`, `.v-slide-stat`, `.v-slide-quote` — init with `vellum.widgets.slideshow()` |
+
+Every app should include: search/filter, toast notifications for all CRUD operations, `window.vellum.confirm()` for destructive actions, staggered page-load animation, card hover effects, and skeleton loading states. (These requirements do not apply to presentation slide decks — see "Presentation Slide Design" below.)
+
+## Presentation Slide Design
+
+### Slide Design Philosophy
+
+- **One idea per slide** — each slide communicates a single concept, not a cluster of related points
+- **Glanceable, not readable** — a slide should be understood in 3 seconds; dense text belongs in documents, not presentations
+- **Visual storytelling arc** — open strong, build context, create emotional resonance, close with impact
+- **Cinematic quality bar** — every deck should feel at home in a startup pitch, TED talk, or Apple keynote
+- **The slide is the visual** — don't describe what the audience should imagine; show it through layout, color, and typography
 
-Every app should include: search/filter, toast notifications for all CRUD operations, `window.vellum.confirm()` for destructive actions, staggered page-load animation, card hover effects, and skeleton loading states.
+### What App Rules to Skip for Slides
+
+The general app design checklist does NOT apply to slide decks. Specifically skip:
+
+- Contextual header/greeting ("Good morning, Alex") — slides are not dashboards
+- Search/filter, pill toggles, suggestion chips — slides are not interactive apps
+- Toast notifications, confirm dialogs, form validation — no CRUD in slides
+- Data bridge API / `window.vellum.data` — slides are static content
+- Skeleton loading states — slides render instantly
+- Mandatory trust/status pill badge — use only when slide content calls for it (e.g., a "verified" badge on a stats slide)
+- Mandatory emoji stat cards — use when they strengthen the message, skip when they clutter
+- The app Pre-Ship Design Checklist — use the Slide Pre-Ship Checklist instead
+
+### Slide Typography
+
+- **Title slides:** `clamp(2rem, 5vw, 3rem)`, weight 800 — much larger than app text
+- **Body text:** `clamp(1rem, 2.5vw, 1.25rem)` — larger than app body (14px); keep to 2–3 sentences max
+- **Stat values:** `clamp(1.75rem, 4vw, 2.5rem)` — big numbers are the most impactful element on any slide
+- **Accent-word technique is ESSENTIAL** — even more than apps, every heading should color one key word with the accent color
+- **Contrast is everything** — near-white on dark, near-black on light; no washed-out middle ground
+- **Never go below 15px** for any visible text — if it doesn't fit, cut words, don't shrink font
+
+### Slide Color & Visual Treatment
+
+- **Bold, full-bleed backgrounds** — warm cream, blush pink, soft lavender, deep navy, rich purple, dark emerald; vary light and dark across the deck
+- **Animated gradient backgrounds** are ideal for title and closing slides — use `background-size: 400% 400%` with CSS animation
+- **Domain-matched palettes still apply**, just executed more dramatically — a finance deck is navy/gold, a health deck is teal/white
+- **One accent color used sparingly** — titles, stat borders, label dots, CTA buttons; never more than one accent
+- **Glassmorphism works well** for slide overlays on visual/immersive slides — `backdrop-filter: blur()` with semi-transparent bg
+- **Full-screen immersion:** `.v-slideshow` should use `border-radius: 0; min-height: 100vh` for edge-to-edge feel
+- **Vary background darkness across slides** — alternate between dark, medium, and light backgrounds to create visual rhythm
+
+### Slide Layout Rhythm
+
+When to use each of the 8 layout variants:
+
+| Type | When to Use |
+|---|---|
+| **Title** | Bold title with accent word, subtitle, optional badge — always first |
+| **Stats** | Early for credibility; 2–4 stat cards with big numbers |
+| **Bullets / Content** | Core message; 3–5 bullets max, or 2–3 sentence body |
+| **Quote** | Emotional punctuation; center-aligned, breaks visual pattern |
+| **Comparison** | Two-column before/after, entity comparison, or pros/cons |
+| **Timeline** | Chronological progression; milestones, history, roadmap, or process steps using `.v-timeline-entry` entries |
+| **Visual / Immersive** | Gradient background with glass overlay, minimal text |
+| **Closing / CTA** | Bold title, short takeaway, optional stat reinforcement |
+
+**Layout rhythm rules:**
+
+- **NEVER** two slides of the same type back-to-back
+- **5–8 slides:** title → stats → bullets → quote → comparison or timeline or visual → closing
+- **3–4 slides:** title → stats or bullets → closing
+- **10+ slides:** repeat content/stats but always separate with a quote, timeline, or visual slide
+- **Every deck needs at least 3 different layout types** — variety creates visual interest
+
+### Slide Anti-Slop Rules
+
+- **NEVER** more than 6 bullet points per slide — if you have more, split into two slides
+- **NEVER** body text smaller than 15px — cut words instead of shrinking
+- **NEVER** the same background color on consecutive slides — vary dark/light/gradient
+- **NEVER** skip accent-word on title/heading slides — it's the #1 visual technique
+- **NEVER** use `.v-slide-label` on every single slide — aim for 40–60% of slides
+- **NEVER** center-align bullet slides — only center quotes and closing slides
+- **NEVER** use the same stat value format everywhere — mix `$2.4M`, `147%`, `3x`, `12k+` for variety
+- **NEVER** hand-code charts on slides — use `vellum.widgets.lineChart()` / `.barChart()` / `.sparkline()` / `.progressRing()` rendered into a `<div>` with a fixed height. Hand-coded chart SVGs bleed into adjacent slide elements.
+
+### Slide Pre-Ship Checklist
+
+Before delivering any slide deck, verify:
+
+1. **Domain-matched palette** — colors match the topic (not default violet for everything)
+2. **Bold background** — dark, gradient, or strongly tinted; not plain white
+3. **Accent word in every title** — one key word colored with the accent
+4. **One idea per slide** — each slide understood in 3 seconds
+5. **Layout variety** — 3+ different layout types, no consecutive same-type
+6. **Typography scale** — clear hierarchy; titles much larger than body text
+7. **Sparse content** — max 6 bullets, max 3 sentences body text per slide
+8. **Visual punctuation** — at least one quote, visual, or center-aligned slide
+9. **Strong open and close** — impactful title slide, clear takeaway closing
+10. **Immersive feel** — full-viewport slides, `min-height: 100vh; border-radius: 0`
+
+### What Great Slide Decks Look Like
+
+- **Startup pitch deck** — dark navy animated gradient, accent-word title, trust pill on stats, big stat numbers (`$12M ARR`, `3x growth`), customer quote mid-deck, CTA closing with one bold ask
+- **Company overview** — corporate blue on charcoal, stats-heavy early slides, comparison slide (us vs. competitors), timeline slide, professional/minimal emoji usage
+- **Educational deck** — bright accent on light background, emoji in bullet points for visual anchoring, expert quote, glass overlay visual slide, "key takeaways" closing
+- **Creative agency deck** — bold saturated palette, animated gradient backgrounds, minimal text per slide, maximum visual drama, notable client quote, portfolio-style comparison
 
 ## Error Handling
 

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

@@ -50,7 +50,7 @@
               "title": { "type": "string", "description": "Preview card title" },
               "subtitle": { "type": "string", "description": "Optional subtitle" },
               "description": { "type": "string", "description": "Optional short description" },
-              "icon": { "type": "string", "description": "Optional emoji icon" },
+              "icon": { "type": "string", "description": "Optional icon — image URL preferred when available (logo, favicon, photo, etc.), emoji as fallback" },
               "metrics": {
                 "type": "array",
                 "description": "Optional key-value metrics",

package/src/config/bundled-skills/email-setup/SKILL.md

@@ -9,7 +9,7 @@ You are setting up your own personal email address. This is a one-time operation
 
 ## Prerequisites
 
-Only proceed if the user explicitly asks you to create or set up your email address. Do NOT proactively run this skill.
+Only proceed if the user explicitly asks you to create or set up **your own** (the assistant's) email address — e.g., "set up your email", "create your email address", "I want you to have your own email". Generic email requests like "send an email", "check my email", or "set up email" are about the **user's Gmail** and should be handled by the Messaging skill, not this one. Do NOT proactively run this skill.
 
 ## Step 1: Check if Email Already Exists