@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

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

@@ -74,6 +74,17 @@
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: add coin flip app', 'fix: correct button alignment'). Used as the version history entry."
+          },
+          "icon": {
+            "type": "string",
+            "description": "Lenient alias. Prefer preview.icon. An emoji or image URL passed here is folded into preview.icon automatically."
+          },
+          "html": {
+            "type": "string",
+            "description": "Lenient alias. Prefer source_files. Raw HTML passed here is folded into source_files['src/index.html'] automatically."
+          },
+          "pages": {
+            "description": "Retired. Multi-page apps route inside the Preact app under src/components/. Passing this returns a guidance error."
           }
         },
         "required": ["name"]
@@ -150,6 +161,24 @@
       },
       "executor": "tools/app-generate-icon.ts",
       "execution_target": "host"
+    },
+    {
+      "name": "app_list",
+      "description": "List the persistent apps the user has built, returning each app's app_id, name, description, and timestamps (most recently updated first). Pass `query` to resolve an app the user mentions by name to its app_id before calling app_open. Use this whenever the user refers to an existing app and you don't already have its app_id in context.",
+      "category": "apps",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Optional name (or partial name) the user mentioned. When provided, only matching apps are returned: an exact case-insensitive name match if one exists, otherwise substring matches in either direction (e.g. 'habit tracker' resolves 'Habit Tracker'). Omit to list all apps."
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/app-list.ts",
+      "execution_target": "host"
     }
   ]
 }

package/src/config/bundled-skills/app-builder/references/DESIGN_SYSTEM.md

@@ -0,0 +1,48 @@
+# Design System
+
+A design system CSS is auto-injected inside a `@layer`, so your styles always take priority. It provides element defaults and automatic light/dark mode switching via `prefers-color-scheme`.
+
+**Use `--v-*` variables and `.v-*` classes** — they handle light/dark mode automatically. No manual dark mode CSS needed.
+
+---
+
+## 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-*`                                                            |
+| **Constant**    | `--v-aux-white` (always `#FFFFFF` in both modes — use for text on filled/accent backgrounds)                                                                    |
+
+---
+
+## 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`.
+
+⚠️ **Never hardcode `color: white` or `color: #fff`.** Use `var(--v-aux-white)` for text on filled/accent backgrounds, or `var(--v-text)` / `var(--v-text-secondary)` for text on surface backgrounds. Hardcoded white causes invisible text on light surfaces.
+
+---
+
+## 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) => {
+  console.log("Theme:", e.detail.mode);
+});
+```

package/src/config/bundled-skills/app-builder/references/RESPONSIVE.md

@@ -0,0 +1,57 @@
+# Responsive Baseline & Mobile-First Mode
+
+Every app must work across phone (~360px) to desktop (~1400px+).
+
+## Mode selection
+
+The conversation context's `<turn_context>` block carries an `interface:` field.
+
+**If `interface: ios`** (or any future mobile-web / android identifier):
+  → Mobile-first build. Design the narrow viewport first, enhance upward.
+
+**If `interface: macos` or `web`**:
+  → Desktop-first build. Design larger composition first; narrow fallback still meets the universal baseline below.
+
+**If field is absent or ambiguous**:
+  → Default to desktop-first unless the request implies phone use ("for my iPhone", "a tap-tracker I'll use on the go").
+
+---
+
+## Universal baseline (every build, regardless of interface)
+
+### Viewport & safe areas
+
+- Set viewport meta: `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`. Never set `user-scalable=no` — it blocks accessibility zoom.
+- Pad the root container with `env(safe-area-inset-*)` so content clears the notch: `padding-top: max(var(--v-spacing-lg), env(safe-area-inset-top))`, mirrored for `-bottom` / `-left` / `-right`.
+- Use `100dvh` (dynamic viewport height), not `100vh`, for full-height containers.
+
+### Form controls
+
+- `<input>`, `<textarea>`, `<select>` must be `font-size: 16px` or larger, or iOS Safari will zoom on focus and break the layout. This applies to every build.
+- Add `inputmode` to text fields with structured input: `numeric` for integers, `decimal` for amounts, `email`, `tel`, `url`.
+
+### Touch & hover
+
+- Interactive elements must be ≥44×44pt. `.v-button` already meets this; for custom controls, set `min-height: 44px` explicitly.
+- Gate hover affordances behind `@media (hover: hover)` so they don't stick on touch devices.
+- Disable text selection on app chrome with `user-select: none; -webkit-user-select: none`.
+
+### Layout fluidity
+
+- Use fluid widths only. No fixed-pixel layouts. Prefer `%`, `fr`, `minmax`, `clamp()` over `px` on container widths.
+- At narrow widths, collapse tables into stacked cards with labels and values arranged vertically.
+- Size `vellum.widgets.*` chart containers in `vw` / `%`, not fixed `px`.
+
+---
+
+## Mobile-first priorities (`interface: ios`)
+
+- Default body text to `--v-font-size-lg` (17px), not `--v-font-size-base` (14px).
+- Bump default vertical rhythm one step (e.g. `--v-spacing-md` → `--v-spacing-lg`).
+- One column as the default, not a fallback. Opt into multi-column only above `@media (min-width: 720px)`.
+- Bottom-anchor the primary action: `position: sticky; bottom: env(safe-area-inset-bottom)`.
+- Replace side modals and popovers with bottom sheets.
+
+## Desktop-first priorities (`interface: macos` / `web`)
+
+Multi-column composition, hover-rich affordances, denser information, side modals, inline primary actions. The universal baseline above is still the floor — narrow view must still work.

package/src/config/bundled-skills/app-builder/references/SLIDES.md

@@ -0,0 +1,38 @@
+# Presentation Slide Design
+
+Slides are a different domain from apps. Skip app-specific patterns (contextual headers, search/filter, toast notifications, form validation, custom routes). Slides are static content — build navigation and layouts with custom HTML/CSS.
+
+## Key principles
+
+- 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
+
+## Navigation
+
+Build slide navigation as your own component. Common patterns:
+- Keyboard: `ArrowLeft` / `ArrowRight` / `Space` / `Escape`
+- Click affordances at left/right edges
+- Slide counter pill in a corner (e.g. `3 / 12`)
+- Optional progress bar at the top
+
+## Layout templates
+
+- **Title** — Centered headline, optional subtitle, no body. Full-bleed background or gradient.
+- **Stats** — One huge number, label below, supporting paragraph optional.
+- **Bullets** — Heading + 3–6 short bullets. Avoid wall-of-text.
+- **Quote** — Pull quote in large italic type, attribution below, contrasting background.
+- **Comparison** — Two columns (before/after, us/them, problem/solution). Visual symmetry matters.
+- **Timeline** — Horizontal or vertical sequence with dates and milestones.
+- **Visual/Immersive** — Full-bleed image, gradient, or generated graphic with minimal text overlay.
+- **Closing/CTA** — Headline + single call to action. Mirror the title slide aesthetic.
+
+## What to avoid
+
+- Generic Keynote / PowerPoint aesthetic (default white background, sans-serif body, bullet lists everywhere)
+- Tiny text below 15px — slides are read across rooms
+- Same layout type used 3+ times in a row — vary the rhythm
+- Body paragraphs longer than 3 sentences — split into multiple slides

package/src/config/bundled-skills/app-builder/references/examples/README.md

@@ -0,0 +1,17 @@
+# Example Apps
+
+Complete, copyable reference apps that demonstrate the recommended patterns from this skill:
+multi-file TSX (`formatVersion: 2`), web-compatible persistence via **custom route handlers**
+(`window.vellum.fetch("/v1/x/…")`), and disciplined error handling. Use them as starting
+points — match the structure, not the styling (give every new app its own visual identity per
+the `frontend-design` skill).
+
+| Example                                 | Persistence pattern                              | Route methods                    |
+| --------------------------------------- | ------------------------------------------------ | -------------------------------- |
+| [Focus Timer](./focus-timer.md)         | Append-only log + aggregate stats read on mount  | `GET`, `POST`                    |
+| [Habit Tracker](./habit-tracker.md)     | Full CRUD addressed by `id` query param          | `GET`, `POST`, `PATCH`, `DELETE` |
+| [Expense Tracker](./expense-tracker.md) | Create / read / delete + client-side aggregation | `GET`, `POST`, `DELETE`          |
+
+All three persist through a `routes/*.ts` handler — never through `window.vellum.data`, which
+is a desktop-only bridge that silently no-ops on web. See
+[CUSTOM_ROUTES.md](../CUSTOM_ROUTES.md) for the full route handler reference.