@vellumai/assistant 0.4.26 → 0.4.30

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

@@ -8,465 +8,9 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 **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, warm tinted background, emoji-rich stat cards, an accent-word hero heading, and thoughtful interactions. Don't ask what colors they want. Don't show wireframes. Just build something stunning and let them refine from there.
-
-## Design Philosophy
-
-Every app you create must clear this bar: **Would someone screenshot this and share it?** If the answer is no, you haven't tried hard enough.
-
-### The Quality Bar
-
-Your apps compete with products built by professional design teams. That means:
-
-- Every screen has visual depth — layers, shadows, gradients, texture
-- Typography creates clear hierarchy — not everything is 14px regular weight
-- Color is intentional and atmospheric — not just "blue buttons on white"
-- Interactions feel physical — elements respond to hover, press, and focus
-- Empty states are designed moments, not error messages
-- The page loads with grace — elements stagger in, content shimmers while loading
-
-### Anti-AI-Slop Rules
-
-These are hard prohibitions. Violating any of these produces that unmistakable "AI-generated" look:
-
-- **NEVER** use flat cards with no depth — every card needs a subtle 1px border and gentle shadow, not heavy multi-layer shadows
-- **NEVER** ship an app with zero animations — at minimum: page load stagger, hover states, state transitions
-- **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
-- **ALWAYS** include at least one pill-shaped trust/status badge somewhere visible — "🌟 Trusted by 12,000+ users", "+8.2% this week", "✨ Pro plan"
-- **ALWAYS** use tight letter-spacing on headings (`-0.02em` to `-0.04em`)
-- **ALWAYS** use `clamp()` for display/heading text so it scales fluidly
-- **ALWAYS** add at least one accent gradient somewhere — a hero, a button, a decorative element
-- **ALWAYS** give the app a distinct visual personality — if you removed the content, could you still tell which app this is?
-
-### Color Strategy
-
-- **Theme-match your palette to the domain.** Don't default to violet. Pick the color that feels right: emerald/sage for plants & nature, purple for fitness & wellness, amber/gold for finance & productivity, rose for social & lifestyle, indigo for tech & developer tools.
-- **Define custom CSS variables at the top of `<style>`** for every app:
-  ```css
-  :root {
-    --accent: #18B07A;          /* domain-matched accent */
-    --accent-light: #ECFDF5;    /* tinted surface */
-    --bg-tint: #F0F5F0;         /* warm/cool background tint */
-  }
-  @media (prefers-color-scheme: dark) {
-    :root {
-      --accent: #38CF93;
-      --accent-light: #073D2E;
-      --bg-tint: #0A1A14;
-    }
-  }
-  ```
-- **Background tint examples:** `#FEFCF9` cream (lifestyle), `#F0F5F0` sage (nature), `#F5F7FA` cool gray (finance), `#FDF6F3` warm blush (wellness), `#F5F3FF` lavender (creative). Apply to `body { background: var(--bg-tint); }`.
-- **60-30-10 rule:** 60% tinted background/surface, 30% secondary/text, 10% accent. Never use accent for large areas.
-- **Status colors are semantic:** emerald = success/positive, rose = danger/destructive, amber = warning/attention. Don't use these for decoration.
-- **`--v-*` tokens remain available** for spacing, radius, shadows, and animations. Use them for layout consistency. But stop defaulting to `--v-violet-*` for accent — use your domain-matched `--accent` variable instead.
-- For branded/themed apps, write custom CSS with `@media (prefers-color-scheme: dark)` overrides instead of mixing `--v-*` auto-switching variables with hardcoded colors.
-
-### Typography Rules
-
-- **Display/hero text:** `font-weight: 800`, `letter-spacing: -0.03em`, `clamp(1.75rem, 4vw, 2.5rem)` for fluid sizing
-- **Accent-word technique:** In hero headings, wrap ONE key word in a `<span>` with the accent color or a gradient. This is the single most impactful typography move: `<h1>Track your <span class="accent-word">Growth</span> daily</h1>`. Use `.accent-word { color: var(--accent); }` or apply a gradient fill.
-- **Section headings:** `font-weight: 700`, `letter-spacing: -0.02em`, `--v-font-size-xl` or `--v-font-size-2xl`
-- **Body text:** `--v-font-size-base` (14px), `line-height: 1.55`
-- **Labels/captions:** `text-transform: uppercase`, `letter-spacing: 0.04em`, `--v-font-size-xs`, `font-weight: 600`, `color: var(--v-text-muted)`
-- **Monospace data:** Use `--v-font-mono` for numbers in metrics, code, timestamps
-
-### Spacing & Layout
-
-- Use the `--v-spacing-*` scale consistently — don't mix arbitrary pixel values with token values
-- **Card padding:** `--v-spacing-lg` (16px) minimum, `--v-spacing-xl` (24px) for hero/featured cards
-- **Section gaps:** `--v-spacing-xxl` (32px) to `--v-spacing-xxxl` (48px) between major sections — Lovable-quality apps use generous whitespace
-- **Hero to first content:** minimum `--v-spacing-xxxl` (48px)
-- **Element gaps:** `--v-spacing-sm` to `--v-spacing-md` between related elements
-- **When in doubt, add more whitespace.** The #1 difference between AI-generated and designer-quality is spacing. Double what feels right, then evaluate.
-- Use CSS Grid for dashboards and complex layouts. Use Flexbox for single-axis arrangements.
-- Every layout should look good from 400px to 600px wide
-
-## Visual Techniques Cookbook
-
-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);
-  background-size: 400% 400%;
-  animation: gradientShift 15s ease infinite;
-}
-@keyframes gradientShift {
-  0%, 100% { background-position: 0% 50%; }
-  50% { background-position: 100% 50%; }
-}
-```
-
-### Mesh Gradient (Layered Radials)
-```css
-body {
-  background:
-    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);
-}
-```
-
-### Glassmorphism Card
-```css
-.glass-card {
-  background: color-mix(in srgb, var(--v-surface) 70%, transparent);
-  backdrop-filter: blur(12px);
-  -webkit-backdrop-filter: blur(12px);
-  border: 1px solid color-mix(in srgb, var(--v-surface-border) 50%, transparent);
-  border-radius: var(--v-radius-lg);
-  box-shadow: var(--v-shadow-lg);
-}
-```
-
-### Layered Shadows (Realistic Depth)
-```css
-.elevated-card {
-  box-shadow:
-    0 1px 2px rgba(0,0,0,0.04),
-    0 4px 8px rgba(0,0,0,0.06),
-    0 12px 24px rgba(0,0,0,0.08);
-  transition: box-shadow var(--v-duration-standard), transform var(--v-duration-standard);
-}
-.elevated-card:hover {
-  transform: translateY(-2px);
-  box-shadow:
-    0 2px 4px rgba(0,0,0,0.04),
-    0 8px 16px rgba(0,0,0,0.08),
-    0 24px 48px rgba(0,0,0,0.12);
-}
-```
-
-### Noise/Grain Texture Overlay
-```css
-body::before {
-  content: '';
-  position: fixed;
-  inset: 0;
-  opacity: 0.03;
-  pointer-events: none;
-  z-index: 9999;
-  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
-}
-```
-
-### Gradient Text
-```css
-.gradient-text {
-  background: linear-gradient(135deg, var(--v-rose-500), var(--v-amber-400));
-  -webkit-background-clip: text;
-  -webkit-text-fill-color: transparent;
-  background-clip: text;
-}
-```
-
-### Glow Effect
-```css
-.glow-accent {
-  box-shadow:
-    0 0 20px color-mix(in srgb, var(--v-accent) 30%, transparent),
-    0 0 40px color-mix(in srgb, var(--v-accent) 15%, transparent);
-}
-```
-
-### Dot Grid Pattern Background
-```css
-.dot-pattern {
-  background-image: radial-gradient(circle, var(--v-surface-border) 1px, transparent 1px);
-  background-size: 20px 20px;
-}
-```
-
-### Staggered Reveal Animation
-```css
-.reveal { opacity: 0; transform: translateY(20px); transition: opacity 0.6s ease, transform 0.6s ease; }
-.reveal.visible { opacity: 1; transform: translateY(0); }
-```
-```javascript
-const observer = new IntersectionObserver((entries) => {
-  entries.forEach((entry, i) => {
-    if (entry.isIntersecting) {
-      setTimeout(() => entry.target.classList.add('visible'), i * 100);
-      observer.unobserve(entry.target);
-    }
-  });
-}, { threshold: 0.1 });
-document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
-```
-
-### Card Hover (Lift + Border Glow)
-```css
-.interactive-card {
-  transition: transform var(--v-duration-standard), box-shadow var(--v-duration-standard),
-              border-color var(--v-duration-standard);
-  border: 1px solid var(--v-surface-border);
-  cursor: pointer;
-}
-.interactive-card:hover {
-  transform: translateY(-4px);
-  box-shadow: var(--v-shadow-lg), 0 0 0 1px color-mix(in srgb, var(--v-accent) 20%, transparent);
-  border-color: color-mix(in srgb, var(--v-accent) 40%, var(--v-surface-border));
-}
-```
-
-### Loading Skeleton Shimmer
-```css
-.skeleton {
-  background: linear-gradient(90deg,
-    var(--v-surface) 25%,
-    color-mix(in srgb, var(--v-surface-border) 50%, var(--v-surface)) 50%,
-    var(--v-surface) 75%);
-  background-size: 200% 100%;
-  animation: shimmer 1.5s infinite;
-  border-radius: var(--v-radius-sm);
-}
-.skeleton-text { height: 14px; margin-bottom: 8px; width: 80%; }
-.skeleton-heading { height: 24px; margin-bottom: 12px; width: 60%; }
-.skeleton-avatar { width: 40px; height: 40px; border-radius: 50%; }
-@keyframes shimmer { to { background-position: -200% 0; } }
-```
-
-### Animated Checkmark (Success Feedback)
-```css
-.checkmark-circle {
-  width: 48px; height: 48px; border-radius: 50%;
-  background: var(--v-success); display: flex;
-  align-items: center; justify-content: center;
-  animation: scaleIn 0.3s ease;
-}
-.checkmark-circle::after {
-  content: ''; width: 12px; height: 20px;
-  border: solid white; border-width: 0 3px 3px 0;
-  transform: rotate(45deg); margin-top: -4px;
-  animation: checkDraw 0.2s 0.2s ease both;
-}
-@keyframes scaleIn { from { transform: scale(0); } to { transform: scale(1); } }
-@keyframes checkDraw { from { opacity: 0; } to { opacity: 1; } }
-```
-
-### Navigation Bar (Sticky Header)
-```html
-<nav class="app-navbar">
-  <div class="navbar-brand">🌿 PlantCare</div>
-  <div class="navbar-links">
-    <a href="#" class="nav-link active">Dashboard</a>
-    <a href="#" class="nav-link">My Plants</a>
-    <a href="#" class="nav-link">Schedule</a>
-  </div>
-  <button class="v-button navbar-cta">Add Plant</button>
-</nav>
-```
-```css
-.app-navbar {
-  position: sticky; top: 0; z-index: 100;
-  display: flex; align-items: center; gap: var(--v-spacing-lg);
-  padding: var(--v-spacing-md) var(--v-spacing-xl);
-  background: color-mix(in srgb, var(--bg-tint, var(--v-bg)) 85%, transparent);
-  backdrop-filter: blur(12px); -webkit-backdrop-filter: blur(12px);
-  border-bottom: 1px solid var(--v-surface-border);
-}
-.navbar-brand { font-weight: 700; font-size: var(--v-font-size-lg); }
-.navbar-links { display: flex; gap: var(--v-spacing-sm); margin-left: auto; }
-.navbar-links .nav-link {
-  padding: var(--v-spacing-xs) var(--v-spacing-md); border-radius: var(--v-radius-md);
-  color: var(--v-text-secondary); font-weight: 500; font-size: var(--v-font-size-sm);
-  text-decoration: none; transition: all var(--v-duration-fast);
-}
-.navbar-links .nav-link:hover { color: var(--v-text); background: var(--v-surface); }
-.navbar-links .nav-link.active { color: var(--accent, var(--v-accent)); font-weight: 600; }
-.navbar-cta { margin-left: var(--v-spacing-sm); padding: var(--v-spacing-xs) var(--v-spacing-lg); font-size: var(--v-font-size-sm); }
-```
-
-### Pill Badge / Trust Badge
-```html
-<span class="trust-pill">🌟 Trusted by 12,000+ homes</span>
-<span class="trust-pill accent">+8.2% this week</span>
-```
-```css
-.trust-pill {
-  display: inline-flex; align-items: center; gap: var(--v-spacing-xs);
-  padding: var(--v-spacing-xs) var(--v-spacing-md);
-  background: var(--v-surface); border: 1px solid var(--v-surface-border);
-  border-radius: var(--v-radius-md); font-size: var(--v-font-size-xs);
-  font-weight: 600; color: var(--v-text-secondary);
-}
-.trust-pill.accent {
-  background: color-mix(in srgb, var(--accent, var(--v-accent)) 10%, transparent);
-  border-color: color-mix(in srgb, var(--accent, var(--v-accent)) 25%, transparent);
-  color: var(--accent, var(--v-accent));
-}
-```
-
-### Emoji Stat Card
-```html
-<div class="emoji-stat-row">
-  <div class="emoji-stat-card">
-    <span class="emoji-stat-icon">🔥</span>
-    <span class="emoji-stat-value">1,284</span>
-    <span class="emoji-stat-label">Calories</span>
-  </div>
-  <div class="emoji-stat-card">
-    <span class="emoji-stat-icon">🏃</span>
-    <span class="emoji-stat-value">8,421</span>
-    <span class="emoji-stat-label">Steps</span>
-  </div>
-  <div class="emoji-stat-card">
-    <span class="emoji-stat-icon">💧</span>
-    <span class="emoji-stat-value">2.4L</span>
-    <span class="emoji-stat-label">Hydration</span>
-  </div>
-</div>
-```
-```css
-.emoji-stat-row { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: var(--v-spacing-md); }
-.emoji-stat-card {
-  background: var(--v-surface); border: 1px solid var(--v-surface-border);
-  border-radius: var(--v-radius-lg); padding: var(--v-spacing-lg);
-  display: flex; flex-direction: column; align-items: center; gap: var(--v-spacing-xs);
-  text-align: center;
-}
-.emoji-stat-icon { font-size: 28px; line-height: 1; }
-.emoji-stat-value { font-size: var(--v-font-size-xl); font-weight: 700; color: var(--v-text); }
-.emoji-stat-label { font-size: var(--v-font-size-xs); color: var(--v-text-muted); text-transform: uppercase; letter-spacing: 0.04em; }
-```
+**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.
 
-### Accent Word Heading
-```html
-<h1>Track your <span class="accent-word">Growth</span> daily</h1>
-<!-- Or with gradient variant: -->
-<h1>Imagine it. <span class="v-gradient-text">See it.</span></h1>
-```
-```css
-.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-rose-500)), var(--v-amber-400));
-  -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;
-}
-```
-
-### Interactive Pill Toggles
-```html
-<div class="pill-toggles">
-  <button class="pill-toggle active">1W</button>
-  <button class="pill-toggle">1M</button>
-  <button class="pill-toggle">3M</button>
-  <button class="pill-toggle">1Y</button>
-</div>
-```
-```css
-.pill-toggles {
-  display: inline-flex; gap: var(--v-spacing-xxs);
-  background: var(--v-surface); border: 1px solid var(--v-surface-border);
-  border-radius: var(--v-radius-md); padding: var(--v-spacing-xxs);
-}
-.pill-toggle {
-  padding: var(--v-spacing-xs) var(--v-spacing-md);
-  border-radius: var(--v-radius-md); border: none; background: none;
-  font-size: var(--v-font-size-sm); font-weight: 500; color: var(--v-text-secondary);
-  cursor: pointer; transition: all var(--v-duration-fast);
-}
-.pill-toggle:hover { color: var(--v-text); }
-.pill-toggle.active {
-  background: var(--accent, var(--v-accent)); color: white; font-weight: 600;
-  box-shadow: var(--v-shadow-sm);
-}
-```
-```javascript
-document.querySelectorAll('.pill-toggles').forEach(group => {
-  group.addEventListener('click', (e) => {
-    if (!e.target.classList.contains('pill-toggle')) return;
-    group.querySelectorAll('.pill-toggle').forEach(b => b.classList.remove('active'));
-    e.target.classList.add('active');
-  });
-});
-```
-
-### Suggestion Chips
-```html
-<div class="chip-group">
-  <button class="chip">🏠 All Rooms</button>
-  <button class="chip">🛋️ Living Room</button>
-  <button class="chip">🍳 Kitchen</button>
-  <button class="chip">🛏️ Bedroom</button>
-  <button class="chip active">🚿 Bathroom</button>
-</div>
-```
-```css
-.chip-group { display: flex; flex-wrap: wrap; gap: var(--v-spacing-xs); }
-.chip {
-  padding: var(--v-spacing-xs) var(--v-spacing-md);
-  border-radius: var(--v-radius-md); border: 1px solid var(--v-surface-border);
-  background: var(--v-surface); font-size: var(--v-font-size-sm);
-  color: var(--v-text-secondary); cursor: pointer; transition: all var(--v-duration-fast);
-}
-.chip:hover { border-color: var(--accent, var(--v-accent)); color: var(--v-text); }
-.chip.active {
-  background: color-mix(in srgb, var(--accent, var(--v-accent)) 12%, transparent);
-  border-color: var(--accent, var(--v-accent)); color: var(--accent, var(--v-accent)); font-weight: 600;
-}
-```
-
-### Category Card Row
-```html
-<div class="category-cards">
-  <div class="category-card">
-    <span class="category-icon">🧹</span>
-    <span class="category-name">Standard Clean</span>
-    <span class="category-meta">2-3 hrs · From $60</span>
-  </div>
-  <div class="category-card">
-    <span class="category-icon">✨</span>
-    <span class="category-name">Deep Clean</span>
-    <span class="category-meta">4-5 hrs · From $120</span>
-  </div>
-  <div class="category-card">
-    <span class="category-icon">📦</span>
-    <span class="category-name">Move-Out</span>
-    <span class="category-meta">5-7 hrs · From $180</span>
-  </div>
-</div>
-```
-```css
-.category-cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: var(--v-spacing-md); }
-.category-card {
-  background: var(--v-surface); border: 1px solid var(--v-surface-border);
-  border-radius: var(--v-radius-lg); padding: var(--v-spacing-lg);
-  display: flex; flex-direction: column; align-items: center; gap: var(--v-spacing-sm);
-  text-align: center; cursor: pointer;
-  transition: transform var(--v-duration-fast), border-color var(--v-duration-fast);
-}
-.category-card:hover { transform: translateY(-2px); border-color: var(--accent, var(--v-accent)); }
-.category-icon { font-size: 32px; line-height: 1; }
-.category-name { font-weight: 600; font-size: var(--v-font-size-base); color: var(--v-text); }
-.category-meta { font-size: var(--v-font-size-xs); color: var(--v-text-muted); }
-```
+**Design quality is delegated to the `frontend-design` skill.** That skill defines your aesthetic principles: typography, color strategy, motion, spatial composition, and visual detail. Follow it completely for every build. This skill (app-builder) handles the technical infrastructure: sandbox constraints, data bridge, widget API, app lifecycle, and interaction patterns.
 
 ## Workflow
 
@@ -475,7 +19,7 @@ document.querySelectorAll('.pill-toggles').forEach(group => {
 **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?
-2. Pick a distinctive visual direction — a color palette, atmospheric background, visual personality
+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
 
@@ -485,11 +29,14 @@ document.querySelectorAll('.pill-toggles').forEach(group => {
 
 **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.
 
 Schema guidelines:
+
 - Use `type: "object"` at the top level
 - Define `properties` for each field
 - Supported types: `string`, `number`, `boolean`
@@ -497,13 +44,20 @@ Schema guidelines:
 - Keep schemas reasonably flat — encode complex nested data as JSON strings when needed
 
 Example schema for a project tracker:
+
 ```json
 {
   "type": "object",
   "properties": {
     "title": { "type": "string" },
-    "status": { "type": "string", "enum": ["backlog", "in-progress", "review", "done"] },
-    "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+    "status": {
+      "type": "string",
+      "enum": ["backlog", "in-progress", "review", "done"]
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "critical"]
+    },
     "description": { "type": "string" },
     "tags": { "type": "string" }
   },
@@ -531,29 +85,29 @@ A design system CSS is auto-injected inside a `@layer`, so your styles always ta
 
 Available design tokens:
 
-| Category | Tokens |
-|---|---|
-| **Backgrounds** | `--v-bg`, `--v-surface`, `--v-surface-border` |
-| **Text** | `--v-text`, `--v-text-secondary`, `--v-text-muted` |
-| **Accent** | `--v-accent`, `--v-accent-hover` |
-| **Status** | `--v-success`, `--v-danger`, `--v-warning` |
-| **Spacing** | `--v-spacing-xxs` (2px) / `-xs` (4px) / `-sm` (8px) / `-md` (12px) / `-lg` (16px) / `-xl` (24px) / `-xxl` (32px) / `-xxxl` (48px) |
-| **Radius** | `--v-radius-xs` (2px) / `-sm` (4px) / `-md` (8px) / `-lg` (12px) / `-xl` (16px) / `-pill` (999px) |
-| **Shadows** | `--v-shadow-sm`, `--v-shadow-md`, `--v-shadow-lg` |
-| **Typography** | `--v-font-family`, `--v-font-mono`, `--v-font-size-xs` (10px) / `-sm` (11px) / `-base` (14px) / `-lg` (17px) / `-xl` (22px) / `-2xl` (26px), `--v-line-height` |
-| **Animation** | `--v-duration-fast` (0.15s) / `-standard` (0.25s) / `-slow` (0.4s) |
-| **Palettes** | `--v-slate-{950..50}`, `--v-emerald-*`, `--v-violet-*`, `--v-indigo-*`, `--v-rose-*`, `--v-amber-*` |
+| Category        | Tokens                                                                                                                                                         |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Backgrounds** | `--v-bg`, `--v-surface`, `--v-surface-border`                                                                                                                  |
+| **Text**        | `--v-text`, `--v-text-secondary`, `--v-text-muted`                                                                                                             |
+| **Accent**      | `--v-accent`, `--v-accent-hover`                                                                                                                               |
+| **Status**      | `--v-success`, `--v-danger`, `--v-warning`                                                                                                                     |
+| **Spacing**     | `--v-spacing-xxs` (2px) / `-xs` (4px) / `-sm` (8px) / `-md` (12px) / `-lg` (16px) / `-xl` (24px) / `-xxl` (32px) / `-xxxl` (48px)                              |
+| **Radius**      | `--v-radius-xs` (2px) / `-sm` (4px) / `-md` (8px) / `-lg` (12px) / `-xl` (16px) / `-pill` (999px)                                                              |
+| **Shadows**     | `--v-shadow-sm`, `--v-shadow-md`, `--v-shadow-lg`                                                                                                              |
+| **Typography**  | `--v-font-family`, `--v-font-mono`, `--v-font-size-xs` (10px) / `-sm` (11px) / `-base` (14px) / `-lg` (17px) / `-xl` (22px) / `-2xl` (26px), `--v-line-height` |
+| **Animation**   | `--v-duration-fast` (0.15s) / `-standard` (0.25s) / `-slow` (0.4s)                                                                                             |
+| **Palettes**    | `--v-slate-{950..50}`, `--v-emerald-*`, `--v-violet-*`, `--v-indigo-*`, `--v-rose-*`, `--v-amber-*`                                                            |
 
 Utility classes: `.v-button` (`.secondary`/`.danger`/`.ghost`), `.v-card`, `.v-list`/`.v-list-item`, `.v-badge` (`.success`/`.warning`/`.danger`), `.v-input-row`, `.v-empty-state`, `.v-toggle`.
 
 **Custom themes:** When the user wants a specific branded look, write complete CSS with hardcoded colors and `@media (prefers-color-scheme: dark)` for dark variants. Don't mix `--v-*` auto-switching variables with hardcoded colors in the same element.
 
 **Theme detection in JavaScript:**
+
 ```javascript
 console.log(window.vellum.theme.mode); // 'light' or 'dark'
-window.addEventListener('vellum-theme-change', (e) => {
-  // Update canvas colors, chart themes, etc.
-  console.log('Theme:', e.detail.mode);
+window.addEventListener("vellum-theme-change", (e) => {
+  console.log("Theme:", e.detail.mode);
 });
 ```
 
@@ -561,617 +115,127 @@ window.addEventListener('vellum-theme-change', (e) => {
 
 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 & Data Primitives:**
-
-`.v-metric-card` — Big number with emoji icon, label, and trend:
-```html
-<div class="v-metric-card">
-  <span class="v-metric-icon">💰</span>
-  <span class="v-metric-label">Revenue</span>
-  <span class="v-metric-value">$12,450</span>
-  <span class="v-metric-trend up">↑ 12.3%</span>
-</div>
-```
-Wrap in `.v-metric-grid` for responsive 2-4 column layout. Always use a semantically meaningful emoji: 🔥 for streaks, 🏃 for activity, 💧 for hydration, 📈 for growth, etc.
-
-`.v-data-table` — Sortable table with sticky header and hover states:
-```html
-<table class="v-data-table" id="my-table">
-  <thead><tr>
-    <th><input type="checkbox"></th>
-    <th data-sortable>Name</th>
-    <th data-sortable>Amount</th>
-  </tr></thead>
-  <tbody><tr data-id="1">
-    <td><input type="checkbox"></td>
-    <td>Item</td>
-    <td data-sort-value="100">$100.00</td>
-  </tr></tbody>
-</table>
-```
-
-`.v-tabs` — Tab navigation with keyboard support:
-```html
-<div class="v-tabs" id="my-tabs">
-  <div class="v-tab-bar" role="tablist">
-    <button class="v-tab" aria-controls="panel-1">Tab 1</button>
-    <button class="v-tab" aria-controls="panel-2">Tab 2</button>
-  </div>
-  <div class="v-tab-panel" id="panel-1">Content 1</div>
-  <div class="v-tab-panel" id="panel-2" hidden>Content 2</div>
-</div>
-```
-
-`.v-accordion` — Collapsible sections:
-```html
-<div class="v-accordion" id="my-accordion">
-  <div class="v-accordion-item">
-    <button class="v-accordion-header" aria-expanded="true">Section 1</button>
-    <div class="v-accordion-body">Content here</div>
-  </div>
-</div>
-```
-
-`.v-search-bar` — Search input with clear button:
-```html
-<div class="v-search-bar">
-  <input type="text" placeholder="Search..." id="search">
-  <button class="v-search-clear">✕</button>
-</div>
-```
-
-`.v-empty-state` — No-data placeholder with CTA:
-```html
-<div class="v-empty-state">
-  <div class="v-empty-icon">📋</div>
-  <div class="v-empty-title">No items yet</div>
-  <div class="v-empty-desc">Create your first item to get started.</div>
-  <button class="v-button">Create Item</button>
-</div>
-```
-
-**Additional layout widgets** (use with semantic HTML, all support `--v-*` tokens):
-
-| Widget | Usage | Key Classes/Modifiers |
-|---|---|---|
-| `.v-timeline` | Vertical timeline | `.v-timeline-entry` (`.active`/`.success`/`.error`), `.v-timeline-time`, `.v-timeline-title`, `.v-timeline-desc` |
-| `.v-action-list` | Rows with per-item actions | `.v-action-list-item`, `.v-action-content`, `.v-action-title`, `.v-action-subtitle`, `.v-action-buttons` |
-| `.v-card-grid` | Responsive card grid | Wrap `.v-card` elements |
-| `.v-progress-bar` | Horizontal progress | `.v-progress-header`, `.v-progress-track`, `.v-progress-fill` (`.success`/`.warning`/`.danger`) |
-| `.v-status-badge` | Colored pill with dot | `.success`, `.error`, `.warning`, `.info` |
-| `.v-stat-row` | Horizontal label-value pairs | `.v-stat`, `.v-stat-label`, `.v-stat-value` |
-| `.v-toast` | Notification banner | `.success`, `.error`, `.warning`, `.info` — prefer `vellum.widgets.toast()` |
-| `.v-divider` | Section separator | Optional text label inside |
-| `.v-avatar-row` | Contact/team display | `.v-avatar`, `.v-avatar-info`, `.v-avatar-name`, `.v-avatar-subtitle` |
-| `.v-tag-group` | Wrapping tag row | Wrap `.v-badge` elements |
-
-**Domain-specific widgets** (infer HTML structure from class names):
-
-| Widget | Purpose | Key Classes |
-|---|---|---|
-| `.v-weather-card` | Temperature + forecast | `.v-weather-main`, `.v-weather-temp`, `.v-weather-condition`, `.v-weather-icon`, `.v-weather-details`, `.v-weather-forecast`, `.v-weather-forecast-item` |
-| `.v-stock-ticker` | Price display + chart | `.v-stock-header`, `.v-stock-symbol`, `.v-stock-price`, `.v-stock-change` (`.up`/`.down`), `.v-stock-chart`, `.v-stock-meta` |
-| `.v-flight-card` | Flight info | `.v-flight-header`, `.v-flight-airline`, `.v-flight-price`, `.v-flight-route`, `.v-flight-endpoint`, `.v-flight-time`, `.v-flight-code`, `.v-flight-duration`, `.v-flight-line` |
-| `.v-billing-chart` | Usage/billing display | `.v-billing-header`, `.v-billing-total`, `.v-billing-period`, `.v-billing-canvas`, `.v-billing-legend`, `.v-billing-legend-item`, `.v-billing-legend-dot` |
-| `.v-boarding-pass` | Pass-styled layout | `.v-bp-header`, `.v-bp-route`, `.v-bp-city`, `.v-bp-details`, `.v-bp-field`, `.v-bp-field-label`, `.v-bp-field-value` |
-| `.v-itinerary` | Day-by-day travel plan | `.v-itinerary-day`, `.v-itinerary-date`, `.v-itinerary-item`, `.v-itinerary-time`, `.v-itinerary-content`, `.v-itinerary-title`, `.v-itinerary-location` |
-| `.v-receipt` | Receipt layout | `.v-receipt-header`, `.v-receipt-store`, `.v-receipt-items`, `.v-receipt-line`, `.v-receipt-divider`, `.v-receipt-total` |
-| `.v-invoice` | Formal invoice | `.v-invoice-header`, `.v-invoice-title`, `.v-invoice-number`, `.v-invoice-parties`, `.v-invoice-party-label`, `.v-invoice-party-name`, `.v-invoice-table`, `.v-invoice-totals`, `.v-invoice-line` (`.total`) |
-
-**Content & landing page components:**
-
-`.v-hero` — Hero banner with gradient background, trust badge, and accent word:
-```html
-<div class="v-hero">
-  <span class="v-hero-badge">✨ Now with 4x faster generation</span>
-  <h1>Imagine it. <span class="v-gradient-text">See it.</span></h1>
-  <p class="v-hero-subtitle">A compelling tagline that makes users feel something.</p>
-</div>
-```
-
-`.v-section-header` — Section intro with label:
-```html
-<div class="v-section-header">
-  <span class="v-section-label">🎯 Section</span>
-  <h2>Section Title</h2>
-  <p class="v-section-desc">Description text.</p>
-</div>
-```
-
-`.v-feature-grid` + `.v-feature-card` — Feature showcase with hover lift:
-```html
-<div class="v-feature-grid">
-  <div class="v-feature-card">
-    <div class="v-feature-icon">🚀</div>
-    <div class="v-feature-title">Feature Name</div>
-    <div class="v-feature-desc">Short description.</div>
-  </div>
-</div>
-```
-
-`.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).
+**Layout widgets** (class names, infer HTML structure):
+
+| Widget                                                       | Purpose                                                        |
+| ------------------------------------------------------------ | -------------------------------------------------------------- |
+| `.v-metric-card` (`.v-metric-grid`)                          | Big number with emoji icon, label, trend                       |
+| `.v-data-table`                                              | Sortable table with sticky header, `th[data-sortable]`         |
+| `.v-tabs` / `.v-tab-bar` / `.v-tab-panel`                    | Tab navigation with keyboard support                           |
+| `.v-accordion` / `.v-accordion-item`                         | Collapsible sections                                           |
+| `.v-search-bar`                                              | Search input with clear button                                 |
+| `.v-empty-state`                                             | No-data placeholder with CTA                                   |
+| `.v-timeline` / `.v-timeline-entry`                          | Vertical timeline (`.active`/`.success`/`.error`)              |
+| `.v-action-list` / `.v-action-list-item`                     | Rows with per-item actions                                     |
+| `.v-card-grid`                                               | Responsive card grid                                           |
+| `.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-avatar-row`                                              | Contact/team display                                           |
+| `.v-tag-group`                                               | Wrapping tag row                                               |
+
+**Domain-specific widgets** (class names, infer HTML structure):
+
+| Widget             | Purpose                |
+| ------------------ | ---------------------- |
+| `.v-weather-card`  | Temperature + forecast |
+| `.v-stock-ticker`  | Price display + chart  |
+| `.v-flight-card`   | Flight info with route |
+| `.v-billing-chart` | Usage/billing display  |
+| `.v-boarding-pass` | Pass-styled layout     |
+| `.v-itinerary`     | Day-by-day travel plan |
+| `.v-receipt`       | Receipt layout         |
+| `.v-invoice`       | Formal invoice         |
+
+**Content & landing page components** (class names, infer HTML structure):
+
+| Widget                                           | Purpose                                             |
+| ------------------------------------------------ | --------------------------------------------------- |
+| `.v-hero` / `.v-hero-badge` / `.v-hero-subtitle` | Hero banner with gradient, trust badge, accent word |
+| `.v-section-header` / `.v-section-label`         | Section intro with label                            |
+| `.v-feature-grid` / `.v-feature-card`            | Feature showcase with hover lift                    |
+| `.v-pullquote`                                   | Blockquote with gradient accent border              |
+| `.v-comparison`                                  | Before/after cards (`.before`/`.after`)             |
+| `.v-page`                                        | Centered container (max-width 600px)                |
+| `.v-gradient-text`                               | Accent-colored gradient text                        |
+| `.v-animate-in`                                  | Staggered fade-in for children                      |
+
+**Slideshow** (`.v-slideshow`): Presentation slide deck with transitions. Init with `vellum.widgets.slideshow()`. Slide helpers: `.v-slide`, `.v-slide-label`, `.v-slide-title`, `.v-slide-body`, `.v-slide-stats`, `.v-slide-stat`, `.v-slide-quote`, `.v-slide-list`, `.v-slide-columns`.
 
 #### Widget JavaScript utilities
 
 Interactive utilities at `window.vellum.widgets.*`:
 
-**SVG Charts:**
+**Charts** (always use these instead of hand-coding SVG/CSS charts):
+
 ```javascript
-// Sparkline — inline mini chart
-vellum.widgets.sparkline('container-id', [10, 25, 15, 30], {
-  width: 200, height: 40, color: 'var(--v-success)', strokeWidth: 2, fill: true
+vellum.widgets.sparkline("container-id", [10, 25, 15, 30], {
+  width: 200,
+  height: 40,
+  color: "var(--v-success)",
+  strokeWidth: 2,
+  fill: true,
 });
-
-// Bar chart — labels, tooltips, optional horizontal
-vellum.widgets.barChart('container-id', [
-  { label: 'Jan', value: 120 },
-  { label: 'Feb', value: 180, color: 'var(--v-success)' }
-], { width: 400, height: 200, showLabels: true, showValues: true, horizontal: false });
-
-// Line chart — gradient fill, grid, hover crosshair
-vellum.widgets.lineChart('container-id', [
-  { label: 'Mon', value: 42 },
-  { label: 'Tue', value: 58 }
-], { width: 400, height: 200, showDots: true, showGrid: true, gridLines: 4 });
-
-// Progress ring — circular gauge
-vellum.widgets.progressRing('container-id', 75, {
-  size: 100, strokeWidth: 8, color: 'var(--v-success)', label: '75%'
+vellum.widgets.barChart(
+  "container-id",
+  [
+    { label: "Jan", value: 120 },
+    { label: "Feb", value: 180, color: "var(--v-success)" },
+  ],
+  {
+    width: 400,
+    height: 200,
+    showLabels: true,
+    showValues: true,
+    horizontal: false,
+  },
+);
+vellum.widgets.lineChart(
+  "container-id",
+  [
+    { label: "Mon", value: 42 },
+    { label: "Tue", value: 58 },
+  ],
+  { width: 400, height: 200, showDots: true, showGrid: true, gridLines: 4 },
+);
+vellum.widgets.progressRing("container-id", 75, {
+  size: 100,
+  strokeWidth: 8,
+  color: "var(--v-success)",
+  label: "75%",
 });
 ```
 
 **Data Formatting:**
+
 ```javascript
-vellum.widgets.formatCurrency(1234.56, 'USD');          // "$1,234.56"
-vellum.widgets.formatDate('2025-01-15', 'relative');     // "3d ago"
-vellum.widgets.formatDate('2025-01-15', 'short');        // "1/15/25"
+vellum.widgets.formatCurrency(1234.56, "USD"); // "$1,234.56"
+vellum.widgets.formatDate("2025-01-15", "relative"); // "3d ago"
+vellum.widgets.formatDate("2025-01-15", "short"); // "1/15/25"
 vellum.widgets.formatNumber(1234567, { compact: true }); // "1.2M"
-vellum.widgets.formatNumber(0.156, { decimals: 1 });     // "0.2"
 ```
 
 **Interactive Behaviors:**
-```javascript
-vellum.widgets.sortTable('table-id');            // Wire th[data-sortable] click-to-sort
-vellum.widgets.sortTable('table-id', 0);         // Sort by column 0 immediately
-vellum.widgets.filterTable('table-id', 'search-input-id'); // Live text search
-vellum.widgets.tabs('tabs-id');                  // Tab switching + keyboard nav
-vellum.widgets.accordion('accordion-id', { allowMultiple: true });
-vellum.widgets.multiSelect('table-id');          // Checkboxes + select-all
-vellum.widgets.toast('Saved!', 'success', 4000);          // Auto-dismiss notification
-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
-
-Combine widgets with wiring code to build complex UIs:
-
-**Search-driven list with suggestion chips** — filter items with quick-tap categories:
-```html
-<div class="v-search-bar"><input id="search" placeholder="Search..."></div>
-<div class="chip-group" style="margin-top: var(--v-spacing-sm);">
-  <button class="chip active" data-filter="all">🏠 All</button>
-  <button class="chip" data-filter="kitchen">🍳 Kitchen</button>
-  <button class="chip" data-filter="bedroom">🛏️ Bedroom</button>
-  <button class="chip" data-filter="bathroom">🚿 Bathroom</button>
-</div>
-<ul class="v-action-list" id="list"></ul>
-<div class="v-empty-state" id="empty" hidden>
-  <div class="v-empty-icon">🔍</div>
-  <div class="v-empty-title">No results</div>
-</div>
-```
-```javascript
-let activeFilter = 'all';
-document.getElementById('search').addEventListener('input', filterList);
-document.querySelectorAll('.chip[data-filter]').forEach(chip => {
-  chip.addEventListener('click', () => {
-    document.querySelectorAll('.chip[data-filter]').forEach(c => c.classList.remove('active'));
-    chip.classList.add('active');
-    activeFilter = chip.dataset.filter;
-    filterList();
-  });
-});
-
-function filterList() {
-  const q = document.getElementById('search').value.toLowerCase();
-  let visible = 0;
-  document.querySelectorAll('#list .v-action-list-item').forEach(item => {
-    const textMatch = item.textContent.toLowerCase().includes(q);
-    const catMatch = activeFilter === 'all' || item.dataset.category === activeFilter;
-    item.hidden = !(textMatch && catMatch);
-    if (!item.hidden) visible++;
-  });
-  document.getElementById('empty').hidden = visible > 0;
-}
-```
 
-**Form with inline validation:**
-```html
-<form id="create-form" novalidate>
-  <div class="v-input-row">
-    <label>Title *</label>
-    <input id="title" required placeholder="Enter title">
-    <span class="field-error" id="title-error"></span>
-  </div>
-  <div class="v-input-row">
-    <label>Priority</label>
-    <select id="priority">
-      <option value="low">Low</option>
-      <option value="medium" selected>Medium</option>
-      <option value="high">High</option>
-    </select>
-  </div>
-  <button type="submit" class="v-button" id="submit-btn">Create</button>
-</form>
-```
-```css
-.field-error { color: var(--v-danger); font-size: var(--v-font-size-xs); min-height: 1em; }
-input:invalid:not(:placeholder-shown) { border-color: var(--v-danger); }
-```
 ```javascript
-document.getElementById('create-form').addEventListener('submit', async (e) => {
-  e.preventDefault();
-  const title = document.getElementById('title').value.trim();
-  if (!title) {
-    document.getElementById('title-error').textContent = 'Title is required';
-    return;
-  }
-  document.getElementById('submit-btn').disabled = true;
-  try {
-    await window.vellum.data.create({
-      title,
-      priority: document.getElementById('priority').value
-    });
-    vellum.widgets.toast('Created!', 'success');
-    e.target.reset();
-    document.getElementById('title-error').textContent = '';
-    await loadRecords();
-  } catch (err) {
-    vellum.widgets.toast('Failed to create', 'error');
-  } finally {
-    document.getElementById('submit-btn').disabled = false;
-  }
+vellum.widgets.sortTable("table-id"); // Wire th[data-sortable] click-to-sort
+vellum.widgets.filterTable("table-id", "input-id"); // Live text search
+vellum.widgets.tabs("tabs-id"); // Tab switching + keyboard nav
+vellum.widgets.accordion("accordion-id", { allowMultiple: true });
+vellum.widgets.multiSelect("table-id"); // Checkboxes + select-all
+vellum.widgets.toast("Saved!", "success", 4000); // Auto-dismiss notification
+vellum.widgets.countdown("timer-el", "2025-12-31T00:00:00Z", {
+  onComplete: () => {},
 });
-```
-
-**Dashboard** — contextual header + emoji stats + pill toggles + chart:
-```html
-<!-- Contextual header -->
-<div style="margin-bottom: var(--v-spacing-xxxl);">
-  <p style="color: var(--v-text-muted); font-size: var(--v-font-size-sm); margin: 0;">Saturday, Feb 15</p>
-  <h1 style="margin: var(--v-spacing-xs) 0;">Good morning, <span class="accent-word">Alex</span></h1>
-  <span class="trust-pill accent">🔥 7-day streak</span>
-</div>
-
-<!-- Pill toggles for time range -->
-<div class="pill-toggles" style="margin-bottom: var(--v-spacing-xl);">
-  <button class="pill-toggle active">1W</button>
-  <button class="pill-toggle">1M</button>
-  <button class="pill-toggle">3M</button>
-  <button class="pill-toggle">1Y</button>
-</div>
-
-<!-- Emoji stat cards -->
-<div class="emoji-stat-row" style="margin-bottom: var(--v-spacing-xxl);">
-  <div class="emoji-stat-card">
-    <span class="emoji-stat-icon">🔥</span>
-    <span class="emoji-stat-value" id="cal-value">1,284</span>
-    <span class="emoji-stat-label">Calories</span>
-  </div>
-  <div class="emoji-stat-card">
-    <span class="emoji-stat-icon">🏃</span>
-    <span class="emoji-stat-value" id="steps-value">8,421</span>
-    <span class="emoji-stat-label">Steps</span>
-  </div>
-  <div class="emoji-stat-card">
-    <span class="emoji-stat-icon">💧</span>
-    <span class="emoji-stat-value" id="hydration-value">2.4L</span>
-    <span class="emoji-stat-label">Hydration</span>
-  </div>
-</div>
-
-<!-- Chart + trend badge -->
-<div class="v-card" style="margin-bottom: var(--v-spacing-xxl);">
-  <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom: var(--v-spacing-md);">
-    <h3 style="margin:0;">Weekly Activity</h3>
-    <span class="trust-pill accent">📈 +12% vs last week</span>
-  </div>
-  <div id="chart" style="height:200px;"></div>
-</div>
-
-<!-- Atmospheric tagline -->
-<p style="text-align:center; color: var(--v-text-muted); font-size: var(--v-font-size-sm); font-style:italic;">Powered by your consistency.</p>
-```
-```javascript
-function esc(s) { const d = document.createElement('div'); d.textContent = String(s); return d.innerHTML; }
-
-async function loadDashboard() {
-  const records = await window.vellum.data.query();
-  // Update stat values from real data
-  // Render chart
-  vellum.widgets.barChart('chart', records.map(r => ({
-    label: esc(r.data.name), value: r.data.amount
-  })));
-}
-// Wire pill toggles
-document.querySelectorAll('.pill-toggles').forEach(group => {
-  group.addEventListener('click', (e) => {
-    if (!e.target.classList.contains('pill-toggle')) return;
-    group.querySelectorAll('.pill-toggle').forEach(b => b.classList.remove('active'));
-    e.target.classList.add('active');
-    // Re-fetch data for selected range
-  });
-});
-```
-
-**Landing page** — nav bar + trust badge hero + accent word + category cards:
-```html
-<div class="v-page">
-  <!-- Navigation bar -->
-  <nav class="app-navbar reveal">
-    <div class="navbar-brand">✨ SparkClean</div>
-    <div class="navbar-links">
-      <a href="#" class="nav-link active">Home</a>
-      <a href="#" class="nav-link">Services</a>
-      <a href="#" class="nav-link">Pricing</a>
-    </div>
-    <button class="v-button navbar-cta">Book Now</button>
-  </nav>
-
-  <!-- Hero with trust badge + accent word -->
-  <div class="v-hero reveal">
-    <span class="v-hero-badge">🌟 Trusted by 12,000+ homes</span>
-    <h1>Your home, <span class="v-gradient-text">spotless.</span></h1>
-    <p class="v-hero-subtitle">Professional cleaning matched to your schedule. Book in 60 seconds.</p>
-  </div>
-
-  <!-- Category cards -->
-  <div class="reveal">
-    <h2 style="text-align:center; margin-bottom: var(--v-spacing-xl);">Our <span class="accent-word">Services</span></h2>
-    <div class="category-cards">
-      <div class="category-card">
-        <span class="category-icon">🧹</span>
-        <span class="category-name">Standard Clean</span>
-        <span class="category-meta">2-3 hrs · From $60</span>
-      </div>
-      <div class="category-card">
-        <span class="category-icon">✨</span>
-        <span class="category-name">Deep Clean</span>
-        <span class="category-meta">4-5 hrs · From $120</span>
-      </div>
-      <div class="category-card">
-        <span class="category-icon">📦</span>
-        <span class="category-name">Move-Out</span>
-        <span class="category-meta">5-7 hrs · From $180</span>
-      </div>
-    </div>
-  </div>
-
-  <!-- Feature grid -->
-  <div class="v-feature-grid">
-    <div class="v-feature-card reveal"><div class="v-feature-icon">⚡</div><div class="v-feature-title">Fast Booking</div><div class="v-feature-desc">Book in under 60 seconds.</div></div>
-    <div class="v-feature-card reveal"><div class="v-feature-icon">🛡️</div><div class="v-feature-title">Insured</div><div class="v-feature-desc">Fully bonded & insured teams.</div></div>
-    <div class="v-feature-card reveal"><div class="v-feature-icon">💚</div><div class="v-feature-title">Eco Products</div><div class="v-feature-desc">Safe for kids & pets.</div></div>
-  </div>
-
-  <!-- Atmospheric tagline -->
-  <p class="reveal" style="text-align:center; color: var(--v-text-muted); font-style:italic;">A cleaner home starts here.</p>
-</div>
-```
-```javascript
-const observer = new IntersectionObserver((entries) => {
-  entries.forEach((entry, i) => {
-    if (entry.isIntersecting) {
-      setTimeout(() => entry.target.classList.add('visible'), i * 120);
-      observer.unobserve(entry.target);
-    }
-  });
-}, { threshold: 0.1 });
-document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
-```
-
-**Multi-select table** — checkboxes + bulk toolbar:
-```html
-<table class="v-data-table" id="my-table">
-  <thead><tr>
-    <th><input type="checkbox"></th>
-    <th data-sortable>Name</th>
-    <th data-sortable>Status</th>
-  </tr></thead>
-  <tbody>
-    <tr data-id="1"><td><input type="checkbox"></td><td>Item 1</td><td>Active</td></tr>
-  </tbody>
-</table>
-<div id="bulk-toolbar" hidden style="position:sticky;bottom:0;padding:12px;background:var(--v-surface);border-top:1px solid var(--v-surface-border);display:flex;gap:8px;">
-  <button class="v-button danger" onclick="handleBulk('delete')">Delete Selected</button>
-  <button class="v-button secondary" onclick="handleBulk('archive')">Archive</button>
-</div>
-```
-```javascript
-vellum.widgets.multiSelect('my-table');
-document.getElementById('my-table').addEventListener('change', () => {
-  const any = document.querySelectorAll('#my-table tbody input:checked').length > 0;
-  document.getElementById('bulk-toolbar').hidden = !any;
-});
-
-async function handleBulk(action) {
-  const ids = Array.from(document.querySelectorAll('#my-table tbody input:checked'))
-    .map(cb => cb.closest('tr').dataset.id);
-  if (action === 'delete') {
-    const ok = await window.vellum.confirm('Delete items?', `Delete ${ids.length} selected items?`);
-    if (!ok) return;
-    for (const id of ids) await window.vellum.data.delete(id);
-    vellum.widgets.toast(`Deleted ${ids.length} items`, 'success');
-  }
-  await loadRecords();
-}
-```
-
-**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: 8px; 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
-  });
+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
@@ -1179,25 +243,7 @@ document.addEventListener('DOMContentLoaded', function() {
 - **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 — 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
-
-Use modern web APIs to build genuinely impressive apps:
-
-- **Canvas 2D / WebGL** — charts, visualization, drawing, games, generative art
-- **SVG** — icons, diagrams, interactive graphics
-- **CSS animations & keyframes** — loading states, micro-interactions, page transitions
-- **CSS transforms** — drag-and-drop, card flips, 3D effects
-- **CSS gradients & filters** — blur effects, color overlays, rich backgrounds
-- **CSS Grid subgrid** — complex dashboard layouts
-- **Web Audio API** — sound effects, metronomes, music tools
-- **requestAnimationFrame** — smooth animations, interactive canvases
-- **Drag and drop** (HTML5) — reorderable lists, kanban boards
-- **IntersectionObserver** — scroll-triggered animations, lazy rendering
-- **ResizeObserver** — responsive canvas/chart sizing
-
-Don't reach for these when a simple list will do, but don't avoid them when they'd make the app genuinely better.
+- **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
 
@@ -1209,6 +255,7 @@ The HTML interface can read and write records via `window.vellum.data`. All meth
 - `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
@@ -1222,8 +269,9 @@ Important:
 #### JavaScript patterns
 
 Initialize apps with clean state management:
+
 ```javascript
-document.addEventListener('DOMContentLoaded', async () => {
+document.addEventListener("DOMContentLoaded", async () => {
   await loadRecords();
 });
 
@@ -1234,473 +282,118 @@ async function loadRecords() {
     allRecords = await window.vellum.data.query();
     render();
   } catch (err) {
-    console.error('Failed to load:', err);
+    console.error("Failed to load:", err);
   }
 }
 
 function render() {
   // Re-render UI from allRecords
-  // Apply client-side filtering/sorting
 }
 ```
 
-For complex apps, use a single state object:
-```javascript
-const state = {
-  records: [],
-  filter: localStorage.getItem('filter') || 'all',
-  sortBy: localStorage.getItem('sortBy') || 'createdAt',
-  searchQuery: '',
-  editingId: null,
-};
-
-function setState(updates) {
-  Object.assign(state, updates);
-  render();
-}
-```
+**HTML escaping:** Always escape user-controlled data before inserting into the DOM via `innerHTML`:
 
-**Loading state pattern:**
 ```javascript
-async function loadWithSkeleton() {
-  document.getElementById('content').innerHTML = `
-    <div class="skeleton skeleton-heading"></div>
-    <div class="skeleton skeleton-text"></div>
-    <div class="skeleton skeleton-text" style="width:60%"></div>`;
-  const records = await window.vellum.data.query();
-  setState({ records });
+function esc(s) {
+  const d = document.createElement("div");
+  d.textContent = String(s);
+  return d.innerHTML;
 }
 ```
 
-**HTML escaping:** Always escape user-controlled data before inserting it into the DOM via `innerHTML`. Use this utility:
-```javascript
-function esc(s) { const d = document.createElement('div'); d.textContent = String(s); return d.innerHTML; }
-```
-Then wrap every user data interpolation: `` `<td>${esc(record.data.name)}</td>` ``. Alternatively, use `textContent` or DOM APIs to set text without innerHTML. Failing to escape leads to XSS vulnerabilities.
-
 ### 4. Single-Page App Views
 
-Apps run inside a sandboxed WebView that blocks all navigation — standard `<a>` links will not work for in-app navigation. All apps are effectively single-page. When an app needs multiple views (e.g., list + detail, dashboard + settings), use JavaScript to swap content within the page.
-
-#### View switching pattern
-
-Use a simple `showView()` function to toggle between sections:
-```html
-<nav class="app-nav">
-  <button class="nav-link active" onclick="showView('home')">Home</button>
-  <button class="nav-link" onclick="showView('settings')">Settings</button>
-</nav>
-
-<div id="view-home" class="view">
-  <!-- Home content -->
-</div>
-<div id="view-settings" class="view" hidden>
-  <!-- Settings content -->
-</div>
-
-<style>
-.app-nav { display: flex; gap: 4px; padding: 8px 12px; background: var(--v-surface); border-bottom: 1px solid var(--v-surface-border); }
-.nav-link { padding: 6px 14px; border-radius: 6px; border: none; background: none; color: var(--v-text-secondary); font-size: 13px; font-weight: 500; cursor: pointer; transition: all 150ms; }
-.nav-link:hover { background: var(--v-surface-border); color: var(--v-text); }
-.nav-link.active { background: var(--v-accent); color: white; }
-</style>
-```
+Apps run inside a sandboxed WebView that blocks all navigation. All apps are effectively single-page. When an app needs multiple views, use JavaScript to swap content:
+
 ```javascript
 function showView(name) {
-  document.querySelectorAll('.view').forEach(v => v.hidden = true);
-  document.getElementById('view-' + name).hidden = false;
-  document.querySelectorAll('.nav-link').forEach(btn => btn.classList.remove('active'));
-  document.querySelector(`[onclick="showView('${name}')"]`)?.classList.add('active');
+  document.querySelectorAll(".view").forEach((v) => (v.hidden = true));
+  document.getElementById("view-" + name).hidden = false;
+  document
+    .querySelectorAll(".nav-link")
+    .forEach((btn) => btn.classList.remove("active"));
+  document
+    .querySelector(`[onclick="showView('${name}')"]`)
+    ?.classList.add("active");
 }
 ```
 
-For detail pages, call `showView('detail')` and populate the detail section's content dynamically before showing it. Use a "Back" button that calls `showView('home')` to return to the list.
-
 ### 5. Create and Open the App
 
 Call `app_create` with:
+
 - `name`: Short descriptive name
 - `description`: One-sentence summary
 - `schema_json`: JSON schema as string
-- `html`: Complete HTML document as string
-- `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat after creation
-- `preview`: Always include this — see below
-
-Since `auto_open` defaults to `true`, an inline preview card is shown in chat after creation. The app is NOT opened in a workspace panel automatically — users open it explicitly if desired by clicking 'Open App' on the inline card. The app appears in Things (sidebar) immediately after creation via the `app_files_changed` broadcast.
-
-#### Preview metadata
-
-Always include preview metadata in `app_create` calls. The app shows as an inline card in chat first — no workspace opens automatically. Users can click 'Open App' on the inline card to open the workspace.
-
-Both `ui_show` and `app_create` support a `preview` object for an inline chat preview card. Always include it so the user sees a compact summary of what was built.
-
-**With `ui_show`:**
-```json
-{
-  "surface_type": "dynamic_page",
-  "data": {
-    "html": "...",
-    "preview": {
-      "title": "Expense Tracker",
-      "subtitle": "Personal Finance",
-      "description": "Track daily expenses with category breakdowns.",
-      "icon": "💰",
-      "metrics": [
-        { "label": "Records", "value": "24" },
-        { "label": "Categories", "value": "8" }
-      ]
-    }
-  }
-}
-```
-
-**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" }
-    ]
-  }
-}
-```
+- `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)
 
-**With `app_create` (emoji icon):**
-```json
-{
-  "name": "Expense Tracker",
-  "schema_json": "{}",
-  "html": "...",
-  "preview": {
-    "title": "Expense Tracker",
-    "icon": "💰",
-    "metrics": [
-      { "label": "Records", "value": "24" },
-      { "label": "Categories", "value": "8" }
-    ]
-  }
-}
-```
-
-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 inline preview card is shown in chat — the app is NOT automatically opened in a workspace panel.
+The app is NOT opened in a workspace panel automatically — users open it via the 'Open App' button on the inline card.
 
 ### 6. Handle Iteration
 
-When the user requests changes to an existing app, prefer **`app_file_edit`** over rewriting the entire file. It performs surgical find-and-replace edits (like sed), which is faster and less error-prone than re-emitting a full page.
-
-#### Editing code
-
-- **`app_file_edit`** — preferred for modifying existing code. Provide `app_id`, `path` (e.g. `index.html`, `styles.css`), `old_string` (exact text to find), and `new_string` (replacement). Use this for targeted changes like updating styles, fixing bugs, or adding features.
-- **`app_file_write`** — use when creating a new file or when changes are so extensive that a full rewrite is cleaner. Provide `app_id`, `path`, and `content`.
-- Always include a **`status`** parameter when calling `app_file_edit` or `app_file_write` — a brief human-readable message describing what you are doing (e.g. "adding dark mode styles", "updating navigation layout", "fixing chart rendering bug"). This gives the user visible progress feedback.
-
-#### Metadata vs code changes
-
-- **`app_update`** — use for metadata changes only: `name`, `description`, and `schema_json`. Do not use it for code changes.
-- **`app_file_edit`** / **`app_file_write`** — use for all code changes (HTML, CSS, JS). The surface refreshes automatically after file edits.
-- If schema changes affect existing records, mention this.
-
-#### Multi-file apps
-
-Apps can have multiple files beyond `index.html`. Use separate files for CSS and JavaScript to keep code organized:
-
-- Create additional files with `app_file_write` (e.g. `styles.css`, `app.js`, `components/chart.js`).
-- Link them from `index.html` using `<link rel="stylesheet" href="styles.css">` and `<script src="app.js"></script>`.
-- Use `app_file_list` to see all files in an app.
-- Use `app_file_read` to read any file with line numbers (helpful before making edits).
-
-Use `app_delete` to start over. Use `app_list` to check existing apps. Use `app_query` to inspect app data.
-
-## Interactive Quality Standard
-
-Every app must meet these interaction baselines — they're the difference between "works" and "feels professional."
-
-### Feedback for Every Action
-
-Every user action must produce visible feedback:
-```javascript
-// After creating a record
-vellum.widgets.toast('Task created', 'success');
-
-// After deleting
-vellum.widgets.toast('Deleted', 'success');
-
-// After updating
-vellum.widgets.toast('Changes saved', 'success');
-
-// On error
-vellum.widgets.toast('Something went wrong', 'error');
-```
-
-### Confirmation for Destructive Actions
+When the user requests changes, prefer **`app_file_edit`** over rewriting the entire file.
 
-Use `window.vellum.confirm()` before deleting, resetting, or any irreversible action:
-```javascript
-async function deleteRecord(id) {
-  const confirmed = await window.vellum.confirm(
-    'Delete this item?',
-    'This action cannot be undone.'
-  );
-  if (!confirmed) return;
-  await window.vellum.data.delete(id);
-  vellum.widgets.toast('Deleted', 'success');
-  await loadRecords();
-}
-```
-`window.vellum.confirm(title, message)` returns a `Promise<boolean>` — `true` if the user clicks OK, `false` for Cancel. It shows a native macOS dialog.
-
-### Form Validation
-
-Validate before submit, show errors inline:
-```css
-.field-error {
-  color: var(--v-danger);
-  font-size: var(--v-font-size-xs);
-  margin-top: 2px;
-  min-height: 1em;
-}
-input.invalid, select.invalid {
-  border-color: var(--v-danger);
-  box-shadow: 0 0 0 2px color-mix(in srgb, var(--v-danger) 15%, transparent);
-}
-```
-- Disable submit button while a required field is empty
-- Clear error messages on input focus
-- Show loading state on submit button during async operations
-
-### Loading States
-
-Never show a blank screen while data loads:
-```javascript
-function showLoading() {
-  container.innerHTML = `
-    <div class="skeleton skeleton-heading"></div>
-    <div class="skeleton skeleton-text"></div>
-    <div class="skeleton skeleton-text" style="width:70%"></div>`;
-}
-```
-- Disable buttons during async operations to prevent double-submit
-- Use the skeleton shimmer CSS from the Visual Techniques section
-
-### Keyboard Navigation
+- **`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.
 
-- `Tab` moves between interactive elements in logical order
-- `Enter` submits forms, activates buttons
-- `Escape` closes modals, cancels edits, clears search
-- Use `tabindex` only when natural DOM order is insufficient
+Apps can have multiple files (`styles.css`, `app.js`, etc.). Link from `index.html` with standard tags.
 
-## What Great Apps Look Like
+## Interaction Standards
 
-These are the apps you should aspire to — each one demonstrates the Lovable-quality patterns in action:
+Every app must meet these baselines:
 
-- **Fitness dashboard** — Purple accent (`--accent: #8A5BE0`), lavender tinted background. Contextual header: "Good morning, Alex" with date. Pill toggles (Day/Week/Month) switching chart ranges. Emoji stat cards row (🔥 Calories, 🏃 Steps, 💧 Hydration, 😴 Sleep). Progress rings with distinct colors per metric. Trust pill: "🔥 7-day streak". Atmospheric tagline: "Powered by your consistency."
-- **Plant tracker** — Sage green accent (`--accent: #18B07A`), soft sage background (`#F0F5F0`). Contextual header: "🌿 Your Garden" with plant count badge. Category cards for plant types with emoji (🌵 Succulents, 🌿 Tropicals, 🌸 Flowering). Emoji stat row (💧 Watered today, ☀️ Light exposure, 🌱 New growth). Suggestion chips for filtering: "Needs water", "Low light", "Outdoors".
-- **Finance vault** — Navy/blue-gray accent (`--accent: #3B82F6`), cool gray background (`#F5F7FA`). Contextual header: "Welcome back, Alex" with net worth badge. Transaction list with emoji identifiers (🏠 Rent, 🛒 Groceries, ☕ Coffee). Trend badge: "+8.2% this month". Pill toggles for time ranges (1W/1M/3M/1Y).
-- **Cleaning service landing page** — Warm amber accent (`--accent: #E8A020`), cream background (`#FEFCF9`). Nav bar with logo ("✨ SparkClean") + CTA. Trust pill in hero: "🌟 Trusted by 12,000+ homes". Accent word hero: "Your home, **spotless.**" Category cards (🧹 Standard, ✨ Deep Clean, 📦 Move-Out with pricing). Feature grid with eco/speed/insurance.
-- **AI tool landing page** — Purple gradient text, dark hero section. Suggestion chips below a demo input: "Summarize this", "Generate code", "Explain like I'm 5". Feature grid with emoji icons. Trust badge: "⚡ 4x faster than v1". Atmospheric tagline: "Intelligence, simplified."
+- **Feedback for every action:** Use `vellum.widgets.toast()` after creates, deletes, updates, and errors.
+- **Confirmation for destructive actions:** Use `window.vellum.confirm(title, message)` before deleting or resetting. Returns `Promise<boolean>`.
+- **Form validation:** Validate before submit, show errors inline, disable submit during async operations.
+- **Loading states:** Never show a blank screen while data loads. Use skeleton shimmer or spinners.
+- **Keyboard navigation:** `Tab` between elements, `Enter` to submit, `Escape` to close/cancel.
 
-### Pre-Ship Design Checklist
-
-Before delivering any app, mentally verify these 10 items — they cover the gap between "functional" and "designer-quality":
-
-1. **Domain-matched palette** — Is the accent color appropriate for this domain? (Not default violet)
-2. **Tinted background** — Does the body have a warm/cool tint instead of pure white/dark?
-3. **Emoji stat cards** — Are there emoji icons in metric cards, list items, or navigation?
-4. **Accent word in heading** — Is ONE key word in the hero heading colored or gradient-filled?
-5. **Contextual header** — Is there a greeting, date, or personalized welcome (not just an app title)?
-6. **Trust/status pill badge** — Is there at least one pill badge with a stat, streak, or social proof?
-7. **Generous spacing** — Are section gaps 32-48px? Does the layout feel spacious, not cramped?
-8. **Clean card borders** — Do cards use subtle 1px borders instead of heavy multi-layer shadows?
-9. **Interactive elements** — Are there pill toggles, suggestion chips, or filter controls?
-10. **Atmospheric tagline** — Is there a warm, human-sounding line at the bottom or between sections?
+## Presentation Slide Design
 
-### Additional widget classes
+Slides are a different domain from apps. Skip app-specific patterns (contextual headers, search/filter, toast notifications, form validation, data bridge). Slides are static content.
 
-| Widget | Purpose | Key Classes |
-|---|---|---|
-| `.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()` |
+**Key principles:**
 
-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.)
+- 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
+- Max 6 bullets per slide, max 3 sentences body text
+- Never go below 15px for any visible text
 
-## 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
-
-### 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
+Init with `vellum.widgets.slideshow()`. Use `.v-slide` with helpers: `.v-slide-label`, `.v-slide-title`, `.v-slide-body`, `.v-slide-stats`, `.v-slide-stat`, `.v-slide-quote`, `.v-slide-list`, `.v-slide-columns`.
 
 ## Error Handling
 
-- If `app_create` fails, verify `schema_json` is valid JSON and `html` is a complete HTML document. Retry with fixes.
-- If `app_open` fails, verify `app_id` with `app_list`.
-- If the user reports visual issues, use `app_file_edit` to fix the code. The surface refreshes automatically.
-- All `window.vellum.data` calls must be wrapped in `try/catch` with user-friendly error feedback:
-  ```javascript
-  try {
-    await window.vellum.data.create(data);
-    vellum.widgets.toast('Created!', 'success');
-  } catch (err) {
-    console.error('Create failed:', err);
-    vellum.widgets.toast('Failed to save. Please try again.', 'error');
-  }
-  ```
-- Never let a failed data operation silently pass — always show a toast or inline error message.
-- If the page loads with no data, show a designed empty state (`.v-empty-state`) — never a blank screen.
-- For forms, show validation errors inline next to the relevant field, not as an alert.
+- 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.
+- 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.
 
 ## Actionable UI
 
-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
-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
-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: grouped cards with checkboxes, data tables with selectable rows, kanban columns, stacked list items with inline actions, or any creative layout. 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` and `.v-action-bar-buttons`
-- `.v-action-progress` — inline progress bar for bulk operations
-- `.v-group-header` / `.v-group-body` — collapsible grouped sections
-- `.v-row-removing` — fade-out + slide animation for processed items
-
-### Action data conventions
-- Use semantic action IDs: `archive`, `unsubscribe`, `delete`, `move`, `mark_read`
-- Always include selected item IDs: `sendAction("archive", { ids: ["msg_1", "msg_2"] })`
-
-### Processing flow
-1. Parse the `surfaceAction` to get the action ID and data
-2. Use `vellum.confirm(title, message)` for destructive actions before executing
-3. Call the relevant tools with the item IDs
-4. Use `ui_update` to remove processed items and update counts
-5. Show `widgets.toast()` for feedback
-
-### Error handling
-- Handle partial failures: remove successful items, toast count, keep failed items selectable for retry
+When the user wants to triage or bulk-act on items, generate an interactive UI with selectable items and action buttons.
 
-### Surface lifecycle
-- Use `ui_show` with `display: "panel"` to keep the surface open alongside chat
-- Use `widgets.groupedSelect()` for grouped multi-select with action bar
-- Use `widgets.removeItems()` to animate processed items out
+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
+4. Execute tools, update UI with `ui_update`, show feedback via `widgets.toast()`
+5. Use `window.vellum.confirm()` for destructive actions
 
 ## Home Base
 
-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`.
+Home Base starts from a prebuilt scaffold. When updating, preserve required task-lane anchors and apply changes through `app_file_edit` or `app_file_write`.
 
-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.
+Home Base buttons send prefilled natural-language prompts through `vellum.sendAction`. Treat these as normal user messages.
 
 ## 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"})`.
+Use `vellum.openLink(url, metadata)` to make items clickable. Construct deep-link URLs when possible. Include `metadata.provider` and `metadata.type` for context.
 
 ## 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.
+A "Built on Vellum" badge is auto-injected into every page. Do NOT add your own.