@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/config/__tests__/loader-callsite-strip-fallback.test.ts

@@ -0,0 +1,143 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+const WORKSPACE_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+const CONFIG_PATH = join(WORKSPACE_DIR, "config.json");
+
+function ensureTestDir(): void {
+  const dirs = [
+    WORKSPACE_DIR,
+    join(WORKSPACE_DIR, "data"),
+    join(WORKSPACE_DIR, "data", "memory"),
+    join(WORKSPACE_DIR, "data", "logs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of [
+    "info",
+    "warn",
+    "error",
+    "debug",
+    "trace",
+    "fatal",
+    "silent",
+    "child",
+  ]) {
+    stub[m] = m === "child" ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+afterAll(() => {
+  mock.restore();
+});
+
+import { resolveCallSiteConfig } from "../llm-resolver.js";
+import { invalidateConfigCache, loadConfig } from "../loader.js";
+
+function writeConfig(obj: unknown): void {
+  writeFileSync(CONFIG_PATH, JSON.stringify(obj, null, 2) + "\n");
+}
+
+/**
+ * Base config where the active profile resolves to a DIFFERENT model than the
+ * `balanced` profile that the shipped `memoryV3SelectL2` call-site default
+ * points at. This lets each test distinguish the two failure modes:
+ *   - call-site default applied (fixed)  -> model "balanced-model"
+ *   - silently downgraded to active      -> model "active-model"
+ */
+function baseLlm(callSites: Record<string, unknown>): unknown {
+  return {
+    llm: {
+      default: { provider: "anthropic", model: "default-model" },
+      profiles: {
+        balanced: { provider: "anthropic", model: "balanced-model" },
+        speedy: { provider: "anthropic", model: "active-model" },
+      },
+      activeProfile: "speedy",
+      callSites,
+    },
+  };
+}
+
+describe("config recovery prunes call-site overrides emptied by a strip", () => {
+  beforeEach(() => {
+    ensureTestDir();
+    if (existsSync(CONFIG_PATH)) rmSync(CONFIG_PATH, { force: true });
+    delete process.env.IS_PLATFORM;
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    delete process.env.IS_PLATFORM;
+    if (existsSync(CONFIG_PATH)) rmSync(CONFIG_PATH, { force: true });
+    invalidateConfigCache();
+  });
+
+  test("an undefined call-site profile ref falls back to the shipped default, not the active profile", () => {
+    // The `.profile` ref is invalid (no such profile), so schema recovery
+    // strips it. Before the fix this left `callSites.memoryV3SelectL2 = {}`,
+    // which the resolver treats as a present override and so skips the shipped
+    // `{profile:"balanced"}` default — silently resolving to the active profile.
+    writeConfig(baseLlm({ memoryV3SelectL2: { profile: "ghost-profile" } }));
+
+    const config = loadConfig();
+
+    // The emptied call-site entry must be pruned entirely, not left as `{}`.
+    expect(config.llm.callSites?.memoryV3SelectL2).toBeUndefined();
+
+    // Resolution now lands on the shipped call-site default (balanced), not the
+    // active profile ("active-model"), which is what the bug produced.
+    const resolved = resolveCallSiteConfig("memoryV3SelectL2", config.llm);
+    expect(resolved.model).toBe("balanced-model");
+  });
+
+  test("a valid sibling call-site override survives while the invalid one is pruned", () => {
+    // memoryRouter -> balanced is valid and must be preserved; only the invalid
+    // memoryV3SelectL2 entry is pruned. Guards against over-pruning the parent.
+    writeConfig(
+      baseLlm({
+        memoryV3SelectL2: { profile: "missing" },
+        memoryRouter: { profile: "balanced" },
+      }),
+    );
+
+    const config = loadConfig();
+
+    expect(config.llm.callSites?.memoryV3SelectL2).toBeUndefined();
+    expect(config.llm.callSites?.memoryRouter).toEqual({ profile: "balanced" });
+  });
+
+  test("a partial override keeping other fields is not pruned", () => {
+    // Stripping the invalid `.profile` leaves a non-empty `{temperature:0.5}`,
+    // a legitimate user override the resolver should keep (and which therefore
+    // still shadows the shipped default per existing either/or semantics).
+    writeConfig(
+      baseLlm({ memoryV3SelectL2: { profile: "missing", temperature: 0.5 } }),
+    );
+
+    const config = loadConfig();
+
+    expect(config.llm.callSites?.memoryV3SelectL2).toEqual({
+      temperature: 0.5,
+    });
+  });
+});

package/src/config/__tests__/sync-gated-profiles.test.ts

@@ -181,7 +181,7 @@ describe("reconcileFlagGatedProfiles", () => {
     expect(after.llm.profiles["os-beta"]).toBeUndefined();
     expect(after.llm.profileOrder.includes("os-beta")).toBe(false);
     expect(after.llm.activeProfile).toBe("balanced");
-    expect(after.llm.advisorProfile).toBe("quality-optimized");
+    expect(after.llm.advisorProfile).toBe("frontier");
   });
 
   test("flag off with no os-beta present is a no-op", () => {
@@ -262,7 +262,7 @@ describe("reconcileFlagGatedProfiles", () => {
     expect(after.llm.profileOrder.includes("os-beta")).toBe(false);
     expect(after.llm.profileOrder.includes("experiment")).toBe(false);
     expect(after.llm.activeProfile).toBe("balanced");
-    expect(after.llm.advisorProfile).toBe("quality-optimized");
+    expect(after.llm.advisorProfile).toBe("frontier");
     expect(
       (
         after.llm as unknown as Record<

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

@@ -86,7 +86,7 @@ Every app works phone (~360px) to desktop (~1400px+). The `<turn_context>` block
 
 Full detail when reachable: `{baseDir}/references/RESPONSIVE.md`.
 
-A design-system CSS and widget library are **auto-injected** (inside a `@layer`, so your own styles always win). Use the `--v-*` variables and `.v-*` classes below — they switch light/dark automatically, no manual dark-mode CSS needed. **Always use `window.vellum.widgets.*` chart functions** instead of hand-coded SVG/CSS charts.
+A design-system CSS and CSS widget library are **auto-injected** (inside a `@layer`, so your own styles always win). Use the `--v-*` variables and `.v-*` classes below — they switch light/dark automatically, no manual dark-mode CSS needed. For charts, bundle `chart.js` (an allowed package), or hand-write inline SVG / CSS bars for tiny sparklines — sized to the container so they can't overflow.
 
 **Design tokens** (use these, don't invent hex values):
 
@@ -106,7 +106,7 @@ A design-system CSS and widget library are **auto-injected** (inside a `@layer`,
 
 **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`.
 
-**Theme in JS:** `window.vellum.theme.mode` (`'light'`/`'dark'`); listen on `window.addEventListener("vellum-theme-change", e => e.detail.mode)`.
+**Theme:** the `--v-*` tokens switch light/dark on their own. For custom (non-token) colors that must follow the theme, use `@media (prefers-color-scheme: dark)` in CSS.
 
 For a **custom branded look**, write complete CSS with hardcoded colors + `@media (prefers-color-scheme: dark)` — don't mix `--v-*` auto-switching vars with hardcoded colors in the same element.
 
@@ -118,27 +118,9 @@ Full detail when reachable: `{baseDir}/references/DESIGN_SYSTEM.md`. Note: in lo
 
 CSS classes for standard patterns: `.v-metric-card`/`.v-metric-grid` (big-number stats), `.v-data-table` (sortable, sticky header, `th[data-sortable]`), `.v-tabs`, `.v-accordion`, `.v-search-bar`, `.v-timeline`, `.v-action-list` (rows with per-item actions), `.v-card-grid`, `.v-progress-bar`, `.v-status-badge` (`.success`/`.error`/`.warning`/`.info`), `.v-stat-row`/`.v-stat`, `.v-tag-group`, `.v-avatar-row`. Landing-page components: `.v-hero`/`.v-hero-badge`/`.v-hero-subtitle`, `.v-section-header`/`.v-section-label`, `.v-feature-grid`/`.v-feature-card`, `.v-pullquote`, `.v-comparison` (`.before`/`.after`), `.v-page`, `.v-gradient-text`, `.v-animate-in`. Domain widgets: `.v-weather-card`, `.v-stock-ticker`, `.v-receipt`, `.v-invoice`, `.v-itinerary`, `.v-boarding-pass`.
 
-JS utilities at `window.vellum.widgets.*`:
-
-```javascript
-// Charts — ALWAYS use these, never hand-code SVG/CSS charts (they handle bounds, scaling, dark mode)
-vellum.widgets.sparkline("el-id", [10,25,15,30], { width:200, height:40, color:"var(--v-success)", fill:true });
-vellum.widgets.barChart("el-id", [{label:"Jan",value:120},{label:"Feb",value:180,color:"var(--v-success)"}], { width:400, height:200, showValues:true, horizontal:false });
-vellum.widgets.lineChart("el-id", [{label:"Mon",value:42},{label:"Tue",value:58}], { width:400, height:200, showDots:true, showGrid:true });
-vellum.widgets.progressRing("el-id", 75, { size:100, strokeWidth:8, color:"var(--v-success)", label:"75%" });
-// Formatting
-vellum.widgets.formatCurrency(1234.56, "USD");        // "$1,234.56"
-vellum.widgets.formatDate("2025-01-15", "relative");  // "3d ago"  ("short" → "1/15/25")
-vellum.widgets.formatNumber(1234567, { compact:true }); // "1.2M"
-// Behaviors
-vellum.widgets.sortTable("table-id");                 // wire th[data-sortable]
-vellum.widgets.filterTable("table-id", "input-id");   // live text search
-vellum.widgets.tabs("tabs-id"); vellum.widgets.accordion("acc-id", { allowMultiple:true });
-vellum.widgets.toast("Saved!", "success", 4000);      // success | error | warning | info
-vellum.widgets.countdown("el", "2025-12-31T00:00:00Z", { onComplete:()=>{} });
-```
+Interactive behavior is your own JS: charts → the bundleable `chart.js` (or inline SVG for tiny sparklines); formatting → `Intl.NumberFormat` / `Intl.DateTimeFormat`; table sort/filter, tabs, accordions, toasts, countdowns → plain JS wired to the `.v-*` markup.
 
-Use custom HTML for novel/creative UIs (games, art tools); widgets for standard patterns; mix freely. Full list: `{baseDir}/references/WIDGETS.md`.
+Use custom HTML for novel/creative UIs (games, art tools); the `.v-*` classes for standard patterns; mix freely. Full list: `{baseDir}/references/WIDGETS.md`.
 
 ---
 
@@ -270,7 +252,7 @@ The point of these apps is to put **the user's own data and the assistant's capa
 ```tsx
 async function loadRecords() {
   const res = await window.vellum.fetch("/v1/x/my-route");
-  if (!res.ok) { window.vellum.widgets.toast("Couldn't load", "error"); return []; }
+  if (!res.ok) { notifyError("Couldn't load"); return []; } // your own toast/inline error
   return res.json();
 }
 ```
@@ -282,7 +264,7 @@ useEffect(() => {
   window.vellum.fetch("/v1/x/items")
     .then(res => res.ok ? res.json() : Promise.reject(res.status))
     .then(setItems)
-    .catch(() => window.vellum.widgets.toast("Couldn't load", "error"));
+    .catch(() => notifyError("Couldn't load")); // your own toast/inline error
 }, []);
 ```
 
@@ -307,25 +289,25 @@ export async function POST(req: Request): Promise<Response> {
 
 The optional `context` arg exposes daemon singletons — e.g. `context.assistantEventHub.publish({...})` to push real-time events to connected clients (UI updates, navigation, notifications). It's immutable. Full guide + copyable examples (Focus Timer, Habit Tracker, Expense Tracker): `{baseDir}/references/CUSTOM_ROUTES.md`, `{baseDir}/references/examples/`.
 
-**Persistence options:** `localStorage` for ephemeral UI state (filters, view modes, drafts); custom routes for persistent records and server-side logic. (`window.vellum.data.*` is deprecated — only for editing pre-existing legacy apps.)
+**Persistence options:** `localStorage` for ephemeral UI state (filters, view modes, drafts); custom routes for persistent records and server-side logic.
 
 ---
 
 ## Interaction standards
 
-- **Feedback for every action** — `vellum.widgets.toast()` after creates, deletes, updates, errors.
-- **Confirm destructive actions** — `window.vellum.confirm(title, message)` (returns `Promise<boolean>`) before deleting or resetting.
+- **Feedback for every action** — a toast or inline confirmation after creates, deletes, updates, errors. Build your own (e.g. toggle the `.v-toast` class with JS).
+- **Confirm destructive actions** — render your own confirmation (an inline "Are you sure?" or a modal) before deleting or resetting.
 - **Validate forms** before submit, show errors inline, disable submit during async.
 - **Loading states** — skeleton or spinner, never a blank screen.
 - **Designed empty states** — `.v-empty-state` when there's no data.
 
 ### Keep the assistant aware
 
-Wire `window.vellum.sendAction()` during the build so the assistant sees meaningful interactions. **Reactive** hooks trigger a response (form submissions, selections worth explaining); **silent** hooks (`state_update`) accumulate context without interrupting (tab changes, filter changes). Examples in `{baseDir}/references/INTERACTION_HOOKS.md`.
+Wire `window.vellum.sendAction()` during the build so the app can pull the assistant in. The host handles two actions: **`relay_prompt`** (`{ prompt, conversation }`) sends a message to the assistant as if the user typed it — the way to get an explanation, summary, or follow-up from inside the app (`conversation: "new"` starts a fresh chat instead of the open one); **`set_view`** (`{ view }`) arranges the app and chat (`"split"` / `"full"` / `"chat"`). These two are the whole app→host surface — relay anything you want the assistant to act on as a self-contained prompt. Patterns in `{baseDir}/references/INTERACTION_HOOKS.md`.
 
-### Actionable UI & links
+### Actionable UI
 
-For triage/bulk-action UIs: render a `dynamic_page` with selectable items + action buttons → user selects and clicks → UI sends `surfaceAction` with action ID + selected IDs → execute tools, `ui_update`, toast. Use `window.vellum.confirm()` for destructive actions. Make items clickable with `vellum.openLink(url, metadata)` (include `metadata.provider` and `metadata.type`).
+For triage/bulk-action UIs: render selectable items + action buttons → the user selects and clicks → relay the choice as a prompt with `window.vellum.sendAction("relay_prompt", { prompt: ... })`, listing the selected items in the text, so the assistant can run the tools and report back. Render your own confirmation for destructive actions.
 
 ---
 
@@ -348,9 +330,9 @@ Slide decks are a different domain — skip app patterns (contextual headers, se
 Read with `file_read` using the `{baseDir}/references/...` paths (`{baseDir}` resolves to this skill's directory):
 
 - `RESPONSIVE.md` — mobile vs desktop, universal baseline, safe areas
-- `DESIGN_SYSTEM.md` — token table, utility classes, theme detection
-- `WIDGETS.md` — widget classes, chart utilities, formatting helpers
+- `DESIGN_SYSTEM.md` — token table, utility classes, theme/dark mode
+- `WIDGETS.md` — CSS widget classes (no JS chart/format runtime)
 - `CUSTOM_ROUTES.md` — server-side persistence and custom API routes
 - `examples/` — complete copyable example apps
-- `INTERACTION_HOOKS.md` — sendAction patterns, reactive vs silent
+- `INTERACTION_HOOKS.md` — relay_prompt / set_view app→host actions
 - `SLIDES.md` — presentation slide design

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

@@ -38,11 +38,6 @@ When the user wants a specific branded look, write complete CSS with hardcoded c
 
 ---
 
-## 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);
-});
-```
+## Theme and dark mode
+
+The `--v-*` tokens switch between light and dark automatically, so token-based UI needs no dark-mode code. For custom (non-token) colors that must follow the theme, use `@media (prefers-color-scheme: dark)` in CSS.

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

@@ -1,56 +1,83 @@
 # App Interaction Hooks
 
-When building apps, proactively wire `sendAction` hooks so the assistant stays aware of meaningful user interactions. Two patterns are available:
+A sandboxed app drives the assistant and its own on-screen layout through
+`window.vellum.sendAction(actionId, data)`. When the app is open inside a
+conversation — the chat panel, split view, or mobile app overlay, the surface
+this skill builds for — the host acts on exactly two actions: `relay_prompt`
+and `set_view`. Wire them during the build so the app can pull the assistant in
+and arrange itself.
 
-## Reactive hooks
+Both actions are about the app↔conversation relationship, so an app opened
+standalone — from the Library, with no chat beside it — has nothing listening,
+and `sendAction` there no-ops. Treat them as enhancements: every feature must
+still work when the call is ignored.
 
-Reactive hooks trigger an assistant response. Use them for moments where the assistant's input adds value - selections that need explanation, completions worth celebrating, or submissions that benefit from feedback.
+## `relay_prompt` — send a message to the assistant
 
-```javascript
-// User selects a city on a map — assistant can provide insights
-window.vellum.sendAction("city_selected", { city: "Tokyo" });
+Sends `prompt` into the conversation as if the user typed it; the assistant
+then responds in chat. This is the channel for involving the assistant from an
+app, so phrase the intent as natural language.
 
-// User submits a form — assistant can confirm and suggest next steps
-window.vellum.sendAction("form_submitted", {
-  formId: "signup",
-  email: "user@example.com",
+```javascript
+// A button in a dashboard: "Explain this anomaly"
+window.vellum.sendAction("relay_prompt", {
+  prompt: "Revenue dropped 40% on the 14th — what happened?",
 });
 
-// User completes a level — assistant can congratulate and hint at what's next
-window.vellum.sendAction("level_complete", { level: 5, score: 2400 });
+// Start a fresh conversation instead of using the open one
+window.vellum.sendAction("relay_prompt", {
+  prompt: "Draft a follow-up email to this customer.",
+  conversation: "new", // "active" (default) | "new"
+});
 ```
 
-## Silent hooks
+- **`prompt`** (required) — the message text. Empty or missing → ignored.
+- **`conversation`** — `"active"` (default: the open conversation) or
+  `"new"` (a fresh draft). With `"active"` and nothing open, it's a no-op.
+- **The layout is left exactly as-is.** Relaying never opens, closes, or
+  resizes the app — if the user has chat and app side by side, it stays that
+  way. Each relay is delivered even when the same text is sent repeatedly.
 
-Silent hooks accumulate state without interrupting the user. The state is automatically included as context when the next reactive hook fires.
+The assistant can't see the app's internal state, so make every prompt
+**self-contained**: include the numbers, selection, or row the user is acting
+on. "Summarize these" won't work; "Summarize these 3 expenses: $42 lunch,
+$118 hotel, $30 taxi" will.
 
-```javascript
-// User navigates to a new tab — no response needed, but assistant should know
-window.vellum.sendAction("state_update", {
-  currentView: "forecast",
-  city: "Tokyo",
-});
+Good triggers: "explain this chart," "what should I focus on," "turn these
+into tasks," "compare the two selected plans." Wire them on the buttons and
+selections where the assistant's help is the actual point.
 
-// Score changes during gameplay — track silently
-window.vellum.sendAction("state_update", { score: 1250, lives: 2 });
+### Triage / bulk-action UIs
 
-// User applies a filter — context for future questions
-window.vellum.sendAction("state_update", {
-  filter: "last-30-days",
-  sortBy: "revenue",
-});
+Render selectable items + an action button, then relay the user's choice as a
+prompt the assistant can act on:
+
+```javascript
+function runBulkAction(selected) {
+  const list = selected.map((s) => `- ${s.title} (${s.id})`).join("\n");
+  window.vellum.sendAction("relay_prompt", {
+    prompt: `Archive these ${selected.length} items:\n${list}`,
+  });
+}
 ```
 
-## When to use reactive vs silent
+## `set_view` — arrange the app and chat
+
+Moves the app panel. Independent of `relay_prompt`; use it only when the app
+itself should change the layout.
 
-Choose based on whether the assistant's response would genuinely help the user at that moment:
+```javascript
+window.vellum.sendAction("set_view", { view: "split" }); // app + chat side by side
+window.vellum.sendAction("set_view", { view: "full" }); // app full-width
+window.vellum.sendAction("set_view", { view: "chat" }); // close app, back to chat
+```
 
-| App type            | Silent (state accumulation)                          | Reactive (triggers response)                               |
-| ------------------- | ---------------------------------------------------- | ---------------------------------------------------------- |
-| **Dashboards**      | Tab navigation, filter changes, date range selection | Anomaly detected, threshold breached, data export complete |
-| **Games**           | Score updates, move tracking, timer ticks            | Level complete, achievement unlocked, game over            |
-| **Forms & wizards** | Field focus, partial input, step navigation          | Form submitted, validation failed on submit                |
-| **Trackers**        | Incremental progress, status toggles, reordering     | Milestone reached, streak achieved, all items complete     |
-| **Data explorers**  | Sorting, paging, column toggling                     | Row selected for detail, comparison initiated              |
+- **`"split"`** — side by side with the conversation. Desktop only; ignored on
+  mobile, which has no side-by-side layout.
+- **`"full"`** — the app takes the full width.
+- **`"chat"`** — closes the app and returns to the conversation.
 
-Wire hooks during the initial build - don't wait for the user to ask. Apps that communicate state back to the assistant feel alive; apps that don't feel like static pages.
+Most apps never need this — the user controls the layout from the app's nav
+bar. Reach for it only when an in-app action implies a layout change (e.g. a
+"Discuss with assistant" button that opens `split` so the reply lands beside
+the app).

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

@@ -40,7 +40,7 @@ The conversation context's `<turn_context>` block carries an `interface:` field.
 
 - 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`.
+- Size chart containers (`chart.js` canvas or inline SVG) in `vw` / `%`, not fixed `px`.
 
 ---
 

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

@@ -1,6 +1,6 @@
 # Widget Component Library
 
-A CSS/JS widget library is auto-injected alongside the design system. Use these for standard UI patterns - skip them when custom HTML serves the user better.
+A CSS widget library is auto-injected alongside the design system — the `.v-*` classes below. Use these for standard UI patterns; skip them when custom HTML serves the user better. The classes are styling only; wire any interactive behavior with your own JS (see below).
 
 ## Layout widgets
 
@@ -18,7 +18,7 @@ A CSS/JS widget library is auto-injected alongside the design system. Use these
 | `.v-progress-bar` / `.v-progress-track` / `.v-progress-fill` | Horizontal progress                                            |
 | `.v-status-badge`                                            | Colored pill with dot (`.success`/`.error`/`.warning`/`.info`) |
 | `.v-stat-row` / `.v-stat`                                    | Horizontal label-value pairs                                   |
-| `.v-toast`                                                   | Notification banner - prefer `vellum.widgets.toast()`          |
+| `.v-toast`                                                   | Notification banner (show/hide with your own JS)              |
 | `.v-avatar-row`                                              | Contact/team display                                           |
 | `.v-tag-group`                                               | Wrapping tag row                                               |
 
@@ -48,78 +48,20 @@ A CSS/JS widget library is auto-injected alongside the design system. Use these
 | `.v-gradient-text`                               | Accent-colored gradient text                           |
 | `.v-animate-in`                                  | Staggered fade-in for children                         |
 
-## Widget JavaScript utilities
+## Interactive behavior — your own JS
 
-Interactive utilities at `window.vellum.widgets.*`:
+The `.v-*` classes are styling only. Wire behavior with standard web tools:
 
-### Charts
+- **Charts** → the bundleable `chart.js`, or hand-written inline SVG / CSS bars for tiny sparklines, sized to the container to avoid overflow.
+- **Notifications** → toggle the `.v-toast` class with your own JS.
+- **Table sort/filter, tabs, accordions, countdowns** → plain JS event handlers.
+- **Formatting** → `Intl.NumberFormat` / `Intl.DateTimeFormat`.
+- **Theme** → `@media (prefers-color-scheme: dark)` in CSS.
 
-Always use these instead of hand-coding SVG/CSS charts:
+The complete in-app JS API is `window.vellum.sendAction`, `window.vellum.fetch`, and `window.vellum.route` (see [`INTERACTION_HOOKS.md`](./INTERACTION_HOOKS.md)).
 
-```javascript
-vellum.widgets.sparkline("container-id", [10, 25, 15, 30], {
-  width: 200,
-  height: 40,
-  color: "var(--v-success)",
-  strokeWidth: 2,
-  fill: true,
-});
-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%",
-});
-```
+## When to use the CSS widgets vs custom HTML
 
-### 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.formatNumber(1234567, { compact: true }); // "1.2M"
-```
-
-### Interactive Behaviors
-
-```javascript
-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: () => {},
-});
-```
-
-## When to use widgets vs custom HTML
-
-- **Use widgets** for standard patterns - tables, metrics, timelines, notifications
-- **Use custom HTML** for novel or creative UIs - games, art tools, unique dashboards
-- **Mix freely** - widgets compose well together and with custom elements
-- **ALWAYS use `vellum.widgets.*` chart functions** instead of hand-coding SVG/CSS charts. They handle overflow clipping, bounds, scaling, and dark mode. Hand-coded charts break layouts.
+- **Use the CSS widget classes** for standard patterns — tables, metrics, timelines, notifications.
+- **Use custom HTML** for novel or creative UIs — games, art tools, unique dashboards.
+- **Mix freely** — the classes compose well together and with custom elements.

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

@@ -12,6 +12,5 @@ the `frontend-design` skill).
 | [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
+All three persist through a `routes/*.ts` handler. See
 [CUSTOM_ROUTES.md](../CUSTOM_ROUTES.md) for the full route handler reference.

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

@@ -218,16 +218,14 @@ Use this when the guardian wants to authorize a specific phone number to call th
 **Important**: The response includes a `voiceCode` field that is only returned at creation time and cannot be retrieved later. Extract and present it clearly.
 
 ```bash
-assistant contacts invites create --source-channel phone --contact-id "<contact_id>" --expected-external-user-id "<phone_E164>" --friend-name "<invitee_name>" --guardian-name "<guardian_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
+assistant contacts invites create --source-channel phone --contact-id "<contact_id>" --expected-external-user-id "<phone_E164>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
 Required flags:
 
 - `--source-channel` -- must be `phone`
-- `--contact-id` -- the ID of the contact this invite is for. Look up the contact first with `assistant contacts list`. New contacts must be added via the Contacts tab in the assistant web UI; you cannot create them here.
+- `--contact-id` -- the ID of the contact this invite is for. Look up the contact first with `assistant contacts list`. New contacts must be added via the Contacts tab in the assistant web UI; you cannot create them here. The contact's `displayName` is used to personalize the voice greeting; the guardian label is resolved at runtime.
 - `--expected-external-user-id` -- the invitee's phone number in E.164 format (e.g., `+15551234567`)
-- `--friend-name` -- the invitee's display name (e.g., "Mom", "Dr. Smith"). Used during the voice verification call to personalize the experience.
-- `--guardian-name` -- the guardian's display name (e.g., "Alex"). Used during the voice verification call so the invitee knows who invited them.
 
 Optional flags:
 
@@ -235,10 +233,9 @@ Optional flags:
 - `--expires-in-ms` -- expiration time in milliseconds from now (e.g., `86400000` for 24 hours). Defaults to 7 days if omitted.
 - `--note` -- a human-readable label for the invite (e.g., "For Mom", "Dr. Smith")
 
-The create response contains `{ ok: true, invite: { id, voiceCode, expectedExternalUserId, friendName, guardianName, ... } }`.
+The create response contains `{ ok: true, invite: { id, voiceCode, expectedExternalUserId, ... } }`.
 
 - `voiceCode` is the numeric code the invitee must enter and is only returned at creation time.
-- `friendName` and `guardianName` are echoed back in the response.
 - Voice invite responses do **not** include `token` or `share.url`. Do not try to build or send a deep link for voice invites.
 
 **Presenting to the guardian**: Give the guardian clear instructions to relay to the invitee:
@@ -264,7 +261,7 @@ If the user provides a phone number without the `+` country code prefix, ask the
 Use this when the guardian wants to invite someone to message the assistant via email. Email invites use a 6-digit code - the invitee sends the code to the assistant's email address to redeem access.
 
 ```bash
-assistant contacts invites create --source-channel email --contact-id "<contact_id>" --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
+assistant contacts invites create --source-channel email --contact-id "<contact_id>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
 Required flags:
@@ -295,7 +292,7 @@ If the assistant's email address is not available, tell the guardian they need t
 Use this when the guardian wants to invite someone to message the assistant on WhatsApp. WhatsApp invites use a 6-digit code - the invitee sends the code to the assistant's WhatsApp number to redeem access.
 
 ```bash
-assistant contacts invites create --source-channel whatsapp --contact-id "<contact_id>" --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
+assistant contacts invites create --source-channel whatsapp --contact-id "<contact_id>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
 Required flags:
@@ -328,7 +325,7 @@ If the assistant's WhatsApp integration is not configured at all (Meta WhatsApp
 Use this when the guardian wants to invite someone to message the assistant on Slack. Slack invites use a 6-digit code -- the invitee sends the code as a direct message to the assistant's Slack bot to redeem access.
 
 ```bash
-assistant contacts invites create --source-channel slack --contact-id "<contact_id>" --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
+assistant contacts invites create --source-channel slack --contact-id "<contact_id>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
 ```
 
 Required flags:
@@ -451,8 +448,6 @@ Each channel has:
   - `contactId is required for create` -- when creating an invite, always pass `--contact-id`. Look up or create the contact first.
   - `expectedExternalUserId is required for voice invites` -- voice invites must include the invitee's phone number via `--expected-external-user-id`.
   - `expectedExternalUserId must be in E.164 format` -- the phone number must start with `+` followed by country code and number (e.g., `+15551234567`).
-  - `friendName is required for voice invites` -- voice invites must include the invitee's display name via `--friend-name`.
-  - `guardianName is required for voice invites` -- voice invites must include the guardian's display name via `--guardian-name`.
   - `Invite not found or already revoked` -- the invite ID may be invalid or the invite is already revoked.
 
 ## Tips
@@ -485,7 +480,7 @@ Each channel has:
 
 **"Revoke invite"** / **"Cancel invite link"** -- List invites to identify the target, confirm, then revoke with `assistant contacts invites revoke <invite_id> --json`.
 
-**"Create a voice invite for +15551234567"** -- Look up or create the contact first, then create a voice invite with `assistant contacts invites create --source-channel phone --contact-id <contact_id> --expected-external-user-id "+15551234567" --friend-name "<name>" --guardian-name "<name>"`. Present the invite code and instructions: the person must call from that number and enter the code.
+**"Create a voice invite for +15551234567"** -- Look up or create the contact first, then create a voice invite with `assistant contacts invites create --source-channel phone --contact-id <contact_id> --expected-external-user-id "+15551234567"`. Present the invite code and instructions: the person must call from that number and enter the code. The caller's name and the guardian's name resolve from the bound contact and the runtime guardian — no name flags needed.
 
 **"Let my mom call in"** / **"Invite someone by phone"** -- Ask for the phone number in E.164 format, look up or create the contact first, then create a voice invite with `assistant contacts invites create --source-channel phone --contact-id <contact_id>`, and present the code + calling instructions.
 

package/src/config/bundled-skills/messaging/tools/shared.ts

@@ -137,5 +137,8 @@ export async function getProviderConnection(
 ): Promise<OAuthConnection | undefined> {
   if (provider.resolveConnection) return provider.resolveConnection(account);
   if (await provider.isConnected?.()) return undefined;
-  return resolveOAuthConnection(provider.credentialService, { account });
+  return resolveOAuthConnection(provider.credentialService, {
+    account,
+    requiredScopes: provider.requiredScopes,
+  });
 }