@vellumai/assistant 0.6.1 → 0.6.3

package/src/config/assistant-feature-flags.ts

@@ -20,7 +20,6 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
-import { getIsContainerized } from "./env-registry.js";
 import type { AssistantConfig } from "./schema.js";
 
 // ---------------------------------------------------------------------------
@@ -173,61 +172,49 @@ function loadOverridesFromFile(): Record<string, boolean> {
 }
 
 /**
- * Load override values from the gateway via synchronous HTTP call.
+ * Fetch override values from the gateway via async HTTP.
  *
- * Follows the trust-client pattern: uses `Bun.spawnSync` + `curl` to make
- * a blocking GET request to the gateway's feature-flags endpoint. The
- * gateway returns `{ flags: Array<{ key, enabled, ... }> }` and we extract
- * just the key → enabled map.
+ * Returns the gateway's merged feature flag map (persisted > remote >
+ * registry), or an empty record on any failure (network, auth, parse).
  */
-function loadOverridesFromGateway(): Record<string, boolean> {
+async function fetchOverridesFromGateway(): Promise<Record<string, boolean>> {
   try {
     // Lazy-import to avoid circular dependency and keep this module
     // importable from bootstrap code when not in containerized mode.
     const { getGatewayInternalBaseUrl } =
       // eslint-disable-next-line @typescript-eslint/no-require-imports
       require("./env.js") as typeof import("./env.js");
-    const { mintEdgeRelayToken } =
+    const {
+      mintEdgeRelayToken,
+      isSigningKeyInitialized,
+      initAuthSigningKey,
+      resolveSigningKey,
+    } =
       // eslint-disable-next-line @typescript-eslint/no-require-imports
       require("../runtime/auth/token-service.js") as typeof import("../runtime/auth/token-service.js");
 
+    // CLI subprocesses don't run daemon startup, so the signing key
+    // may not be initialized yet. Initialize it now so mintEdgeRelayToken
+    // can produce a valid JWT for the gateway request.
+    if (!isSigningKeyInitialized()) {
+      initAuthSigningKey(resolveSigningKey());
+    }
+
     const url = `${getGatewayInternalBaseUrl()}/v1/feature-flags`;
     const token = mintEdgeRelayToken();
 
-    const proc = Bun.spawnSync(
-      [
-        "curl",
-        "-s",
-        "-S",
-        "-X",
-        "GET",
-        "--max-time",
-        "10",
-        "-H",
-        `Authorization: Bearer ${token}`,
-        "-H",
-        "Accept: application/json",
-        "-w",
-        "\n%{http_code}",
-        url,
-      ],
-      { stdout: "pipe", stderr: "pipe" },
-    );
-
-    if (proc.exitCode !== 0) return {};
-
-    const output = proc.stdout.toString().trim();
-    const lastNewline = output.lastIndexOf("\n");
-    const responseBody = lastNewline >= 0 ? output.slice(0, lastNewline) : "";
-    const statusCode = parseInt(
-      lastNewline >= 0 ? output.slice(lastNewline + 1) : output,
-      10,
-    );
-
-    if (statusCode < 200 || statusCode >= 300) return {};
-    if (!responseBody) return {};
-
-    const parsed = JSON.parse(responseBody) as {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!response.ok) return {};
+
+    const parsed = (await response.json()) as {
       flags?: Array<{ key: string; enabled: boolean }>;
     };
     if (!Array.isArray(parsed.flags)) return {};
@@ -245,25 +232,42 @@ function loadOverridesFromGateway(): Record<string, boolean> {
 }
 
 /**
- * Load overrides, preferring the gateway HTTP API.
+ * Pre-populate the override cache from the gateway (async).
  *
- * In containerized mode, always uses the gateway. In local mode, tries
- * the gateway first and falls back to `loadOverridesFromFile()` when
- * the gateway is not yet available (startup race).
+ * Call this once during startup (daemon or CLI entry) before any sync
+ * `isAssistantFeatureFlagEnabled` calls. In containerized mode, always
+ * uses the gateway. In local mode, falls back to the local file when
+ * the gateway is unreachable.
  *
- * Results are cached at module level.
+ * On failure, the cache is left unset so subsequent sync calls fall
+ * through to the file-based fallback rather than caching an empty map
+ * that masks all overrides for the process lifetime.
  */
-function loadOverrides(): Record<string, boolean> {
-  if (cachedOverrides != null) return cachedOverrides;
-
-  const gatewayOverrides = loadOverridesFromGateway();
-  if (Object.keys(gatewayOverrides).length > 0 || getIsContainerized()) {
+export async function initFeatureFlagOverrides(): Promise<void> {
+  const gatewayOverrides = await fetchOverridesFromGateway();
+  if (Object.keys(gatewayOverrides).length > 0) {
     cachedOverrides = gatewayOverrides;
-    return cachedOverrides;
+    return;
   }
 
-  // Graceful fallback: in local mode, if the gateway hasn't started yet
-  // (empty response), read overrides from file as a temporary measure.
+  // Gateway returned empty or failed. Leave the cache unset so
+  // loadOverrides() falls through to file on the next sync read,
+  // regardless of containerized vs local mode.
+}
+
+/**
+ * Read cached overrides synchronously.
+ *
+ * If `initFeatureFlagOverrides()` was called at startup, this returns the
+ * pre-populated cache. Otherwise falls back to the local file — this
+ * ensures the resolver never blocks on a network call.
+ */
+function loadOverrides(): Record<string, boolean> {
+  if (cachedOverrides != null) return cachedOverrides;
+
+  // Cache not yet populated (initFeatureFlagOverrides wasn't called or
+  // hasn't finished). Fall back to the local file so the resolver still
+  // works, just without gateway data.
   cachedOverrides = loadOverridesFromFile();
   return cachedOverrides;
 }

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

@@ -8,6 +8,10 @@ metadata:
     display-name: "App Builder"
     includes:
       - "frontend-design"
+    activation-hints:
+      - "User asks to build an app, landing page, website, dashboard, tool, calculator, game, tracker, or interactive page"
+      - "User asks to visualize data or says 'let's visualize this' — use the app sandbox to build interactive visualizations"
+      - "ALWAYS prefer the app sandbox over building standalone web apps, local servers, or outputting raw HTML/CSS/JS in chat — even when the user says 'make this an app' or 'turn this into an app'"
 ---
 
 You are an expert app builder and visual designer. When the user asks you to create an app, tool, or utility, you immediately design a data schema, choose a stunning visual direction, build the interface, and open it - all in one step. You don't discuss or ask for permission to be creative. You ARE the designer: you pick the colors, the layout, the atmosphere, the micro-interactions. Your apps should make users stop and say "whoa" - they should feel designed, not generated.
@@ -173,13 +177,16 @@ export const Header: FunctionComponent<Props> = ({ title, count }) => {
 
 **CSS:** Import CSS files directly in TSX (`import './styles.css'`). You can also use inline styles via the `style` attribute on JSX elements.
 
-**Data bridge:** The same `window.vellum.data` API works in TSX components - call it from `useEffect` hooks or event handlers:
+**Custom routes in TSX:** Use `window.vellum.fetch()` to call custom route handlers from components — see the [Custom route handlers](#custom-route-handlers-user-defined-routes) section for full details:
 
 ```tsx
-const [records, setRecords] = useState<Record[]>([]);
+const [items, setItems] = useState<Item[]>([]);
 
 useEffect(() => {
-  window.vellum.data.query().then(setRecords).catch(console.error);
+  window.vellum.fetch("/v1/x/items")
+    .then((res) => (res.ok ? res.json() : Promise.reject(res.status)))
+    .then(setItems)
+    .catch(console.error);
 }, []);
 ```
 
@@ -211,7 +218,10 @@ export const App: FunctionComponent = () => {
   const [records, setRecords] = useState([]);
 
   useEffect(() => {
-    window.vellum.data.query().then(setRecords);
+    window.vellum.fetch("/v1/x/projects")
+      .then((res) => res.ok ? res.json() : Promise.reject(res.status))
+      .then(setRecords)
+      .catch(console.error);
   }, []);
 
   return (
@@ -309,131 +319,15 @@ window.addEventListener("vellum-theme-change", (e) => {
 
 #### 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.
-
-**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                      |
-
-#### Widget JavaScript utilities
-
-Interactive utilities at `window.vellum.widgets.*`:
-
-**Charts** (always use these instead of hand-coding SVG/CSS charts):
+A CSS/JS widget library is auto-injected alongside the design system. Use `.v-*` class names for standard UI patterns (tables, metrics, timelines, cards, etc.) and `window.vellum.widgets.*` JS utilities for charts, data formatting, and interactive behaviors. **ALWAYS use `vellum.widgets.*` chart functions** instead of hand-coding SVG/CSS charts.
 
-```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%",
-});
-```
-
-**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"
-```
+For the full widget reference (class names, JS APIs, chart functions, formatting utilities), see **[Widget Component Library](references/WIDGETS.md)**.
 
-**Interactive Behaviors:**
+#### Data bridge API (deprecated)
 
-```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.
+> **Prefer custom route handlers** for new apps. The data bridge (`window.vellum.data`) only works for assistants that run on the same machine as the desktop app, which will also be deprecated soon.
 
-#### Data bridge API
-
-The HTML interface can read and write records via `window.vellum.data`. All methods return Promises.
+The native WebView can read and write app records via `window.vellum.data`. All methods return Promises.
 
 - `window.vellum.data.query()` - Returns all records: `{ id, appId, data, createdAt, updatedAt }[]`
 - `window.vellum.data.create(data)` - Creates a record. Returns the created record.
@@ -448,9 +342,15 @@ Important:
 - All operations are async - use `async/await`
 - Wrap all calls in `try/catch`
 
+#### Custom route handlers (user-defined routes)
+
+When the app needs server-side persistence, custom API logic, or workspace file access, use **user-defined routes**. Route handlers are TypeScript/JavaScript files in the workspace `routes/` directory, served under `/v1/x/`. Call them from the frontend via `window.vellum.fetch("/v1/x/...")`. **Never use raw `fetch()` for `/v1/x/` routes** — it will fail in the sandboxed origin.
+
+For handler conventions, examples, key rules, and frontend usage patterns, see **[Custom Route Handlers](references/CUSTOM_ROUTES.md)**.
+
 #### Client-side state management
 
-`localStorage` and `sessionStorage` are available for ephemeral UI state (filters, view modes, collapsed state, preferences, form drafts). Use `window.vellum.data` for persistent app records, `localStorage` for UI preferences.
+`localStorage` and `sessionStorage` are available for ephemeral UI state (filters, view modes, collapsed state, preferences, form drafts). Use custom routes for persistent app records, `localStorage` for UI preferences.
 
 <!-- feature:app-builder-multifile:alt -->
 
@@ -467,7 +367,9 @@ let allRecords = [];
 
 async function loadRecords() {
   try {
-    allRecords = await window.vellum.data.query();
+    const res = await window.vellum.fetch("/v1/x/records");
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    allRecords = await res.json();
     render();
   } catch (err) {
     console.error("Failed to load:", err);
@@ -556,7 +458,7 @@ Every app must meet these baselines:
 
 ## Presentation Slide Design
 
-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 — build navigation and layouts with custom HTML/CSS.
+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:**
 
@@ -569,58 +471,16 @@ Slides are a different domain from apps. Skip app-specific patterns (contextual
 
 ## Error Handling
 
-- All `window.vellum.data` calls must be wrapped in `try/catch` with user-friendly feedback.
+- All `window.vellum.fetch()` calls to custom routes must be wrapped in `try/catch` with user-friendly feedback. Always check `res.ok` before parsing the response body.
 - 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.
 
 ## App Interaction Hooks
 
-When building apps, proactively wire `sendAction` hooks so the assistant stays aware of meaningful user interactions. Two patterns are available:
-
-### Reactive hooks
-
-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.
-
-```javascript
-// User selects a city on a map — assistant can provide insights
-window.vellum.sendAction('city_selected', { city: 'Tokyo' });
-
-// User submits a form — assistant can confirm and suggest next steps
-window.vellum.sendAction('form_submitted', { formId: 'signup', email: 'user@example.com' });
-
-// User completes a level — assistant can congratulate and hint at what's next
-window.vellum.sendAction('level_complete', { level: 5, score: 2400 });
-```
-
-### Silent hooks
-
-Silent hooks accumulate state without interrupting the user. The state is automatically included as context when the next reactive hook fires.
-
-```javascript
-// User navigates to a new tab — no response needed, but assistant should know
-window.vellum.sendAction('state_update', { currentView: 'forecast', city: 'Tokyo' });
-
-// Score changes during gameplay — track silently
-window.vellum.sendAction('state_update', { score: 1250, lives: 2 });
-
-// User applies a filter — context for future questions
-window.vellum.sendAction('state_update', { filter: 'last-30-days', sortBy: 'revenue' });
-```
-
-### When to use reactive vs silent
-
-Choose based on whether the assistant's response would genuinely help the user at that moment:
-
-| 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 |
+Proactively wire `window.vellum.sendAction()` hooks so the assistant stays aware of meaningful user interactions. Two patterns: **reactive** hooks (trigger assistant response) and **silent** hooks (`state_update` — accumulate context without interrupting). Wire hooks during the initial build, don't wait for the user to ask.
 
-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.
+For examples, reactive vs silent guidance, and per-app-type recommendations, see **[App Interaction Hooks](references/INTERACTION_HOOKS.md)**.
 
 ## Actionable UI
 

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

@@ -0,0 +1,105 @@
+# Custom Route Handlers (User-Defined Routes)
+
+When the app needs server-side persistence, custom API logic, or workspace file access, use **user-defined routes**. Route handlers are TypeScript or JavaScript files that live in the workspace `routes/` directory and are served under the `/v1/x/` URL path.
+
+**Common use cases:** CRUD storage, file-based persistence, search/aggregation, external API proxying, webhook receivers.
+
+## Handler file convention
+
+Each handler file exports named functions for the HTTP methods it supports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Handlers use the standard Web API `Request`/`Response` signature.
+
+```
+{workspaceDir}/routes/
+  items.ts               # Handles /v1/x/items
+  items/
+    [id].ts              # Not supported — use query params instead
+    index.ts             # Also handles /v1/x/items (index convention)
+```
+
+## Example handler — JSON file persistence
+
+```typescript
+// routes/items.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const description = "Item CRUD — stores records as a JSON file";
+
+const DATA_DIR = join(process.env.VELLUM_WORKSPACE_DIR!, "data");
+const DATA_FILE = join(DATA_DIR, "items.json");
+
+function loadItems(): Array<Record<string, unknown>> {
+  mkdirSync(DATA_DIR, { recursive: true });
+  if (!existsSync(DATA_FILE)) return [];
+  return JSON.parse(readFileSync(DATA_FILE, "utf-8"));
+}
+
+function saveItems(items: Array<Record<string, unknown>>): void {
+  mkdirSync(DATA_DIR, { recursive: true });
+  writeFileSync(DATA_FILE, JSON.stringify(items, null, 2));
+}
+
+export function GET(): Response {
+  return Response.json(loadItems());
+}
+
+export async function POST(request: Request): Promise<Response> {
+  const body = await request.json();
+  const items = loadItems();
+  const item = {
+    id: crypto.randomUUID(),
+    ...body,
+    createdAt: new Date().toISOString(),
+  };
+  items.push(item);
+  saveItems(items);
+  return Response.json(item, { status: 201 });
+}
+```
+
+## Calling routes from the app frontend
+
+Apps call custom routes via `window.vellum.fetch()` using the `/v1/x/` prefix. This authenticated wrapper automatically injects the gateway URL and auth headers so requests reach the assistant runtime. **Never use raw `fetch()` for `/v1/x/` routes** — it will fail because the app runs in a sandboxed origin.
+
+```typescript
+// In a TSX component or HTML script
+const res = await window.vellum.fetch("/v1/x/items");
+if (!res.ok) throw new Error(`HTTP ${res.status}`);
+const items = await res.json();
+
+// Create a new item
+const createRes = await window.vellum.fetch("/v1/x/items", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "New item", status: "active" }),
+});
+if (!createRes.ok) throw new Error(`HTTP ${createRes.status}`);
+```
+
+## Key rules
+
+- Always create the route handler files via `file_write` before calling `app_refresh`
+- Export an optional `description` string for CLI discoverability (`assistant routes list`)
+- Handlers have full Node.js API access — `fs`, `path`, `crypto`, etc.
+- Handlers get a 30-second timeout per request
+- Files are hot-reloaded on change (mtime-based cache)
+- Use `.ts` (preferred) or `.js` extensions
+- Route resolution: `routes/foo.ts` → `/v1/x/foo`, `routes/bar/index.ts` → `/v1/x/bar`
+
+## Using custom routes in TSX components
+
+```tsx
+const [items, setItems] = useState<Item[]>([]);
+
+useEffect(() => {
+  window.vellum
+    .fetch("/v1/x/items")
+    .then((res) => (res.ok ? res.json() : Promise.reject(res.status)))
+    .then(setItems)
+    .catch(console.error);
+}, []);
+```
+
+## Error handling
+
+All `window.vellum.fetch()` calls to custom routes must be wrapped in `try/catch` with user-friendly feedback. Always check `res.ok` before parsing the response body. Never let a failed operation silently pass — always show a toast or inline error.

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

@@ -0,0 +1,56 @@
+# App Interaction Hooks
+
+When building apps, proactively wire `sendAction` hooks so the assistant stays aware of meaningful user interactions. Two patterns are available:
+
+## Reactive hooks
+
+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.
+
+```javascript
+// User selects a city on a map — assistant can provide insights
+window.vellum.sendAction("city_selected", { city: "Tokyo" });
+
+// User submits a form — assistant can confirm and suggest next steps
+window.vellum.sendAction("form_submitted", {
+  formId: "signup",
+  email: "user@example.com",
+});
+
+// User completes a level — assistant can congratulate and hint at what's next
+window.vellum.sendAction("level_complete", { level: 5, score: 2400 });
+```
+
+## Silent hooks
+
+Silent hooks accumulate state without interrupting the user. The state is automatically included as context when the next reactive hook fires.
+
+```javascript
+// User navigates to a new tab — no response needed, but assistant should know
+window.vellum.sendAction("state_update", {
+  currentView: "forecast",
+  city: "Tokyo",
+});
+
+// Score changes during gameplay — track silently
+window.vellum.sendAction("state_update", { score: 1250, lives: 2 });
+
+// User applies a filter — context for future questions
+window.vellum.sendAction("state_update", {
+  filter: "last-30-days",
+  sortBy: "revenue",
+});
+```
+
+## When to use reactive vs silent
+
+Choose based on whether the assistant's response would genuinely help the user at that moment:
+
+| 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              |
+
+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.