@vellumai/assistant 0.5.0 → 0.5.2

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

@@ -49,6 +49,7 @@ export interface VoiceBridgeDeps {
     filename: string;
     mimeType: string;
     data: string;
+    filePath?: string;
   }>;
   deriveDefaultStrictSideEffects: (conversationId: string) => boolean;
 }

package/src/cli/commands/auth.ts

@@ -0,0 +1,92 @@
+import type { Command } from "commander";
+
+import {
+  getPlatformAssistantId,
+  getPlatformBaseUrl,
+  getPlatformOrganizationId,
+  getPlatformUserId,
+} from "../../config/env.js";
+import { resolveManagedProxyContext } from "../../providers/managed-proxy/context.js";
+import { log } from "../logger.js";
+import { shouldOutputJson, writeOutput } from "../output.js";
+
+export function registerAuthCommand(program: Command): void {
+  const auth = program
+    .command("auth")
+    .description("Manage platform authentication and identity")
+    .option("--json", "Machine-readable compact JSON output");
+
+  auth.addHelpText(
+    "after",
+    `
+The auth namespace manages the assistant's authentication state with the
+Vellum platform. It provides commands to inspect identity and connection
+status, helping diagnose configuration issues.
+
+Examples:
+  $ assistant auth info
+  $ assistant auth info --json`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // info
+  // ---------------------------------------------------------------------------
+
+  auth
+    .command("info")
+    .description("Show platform identity and authentication status")
+    .addHelpText(
+      "after",
+      `
+Fields:
+  platformUrl         The Vellum platform base URL this assistant connects to
+  assistantId         This assistant's platform UUID (from PLATFORM_ASSISTANT_ID)
+  organizationId      The organization this assistant belongs to (from PLATFORM_ORGANIZATION_ID)
+  userId              The user who owns this assistant (from PLATFORM_USER_ID)
+  authenticated       Whether all prerequisites for platform authentication are met
+                      (platform URL and assistant API key both present)
+
+When not authenticated, a message field provides guidance on next steps.
+
+Examples:
+  $ assistant auth info
+  $ assistant auth info --json`,
+    )
+    .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+      const ctx = await resolveManagedProxyContext();
+
+      const platformUrl = getPlatformBaseUrl();
+      const assistantId = getPlatformAssistantId();
+      const organizationId = getPlatformOrganizationId();
+      const userId = getPlatformUserId();
+      const authenticated = ctx.enabled;
+
+      const result: Record<string, unknown> = {
+        platformUrl: platformUrl || null,
+        assistantId: assistantId || null,
+        organizationId: organizationId || null,
+        userId: userId || null,
+        authenticated,
+      };
+
+      if (!authenticated) {
+        result.message = !platformUrl
+          ? "Platform URL not configured. Run assistant config set platform.baseUrl <url>"
+          : "Assistant API key not found. Store one with: assistant keys set credential/vellum/assistant_api_key <key>";
+      }
+
+      writeOutput(cmd, result);
+
+      if (!shouldOutputJson(cmd)) {
+        log.info(`Platform URL:        ${platformUrl || "(not set)"}`);
+        log.info(`Assistant ID:        ${assistantId || "(not set)"}`);
+        log.info(`Organization ID:     ${organizationId || "(not set)"}`);
+        log.info(`User ID:             ${userId || "(not set)"}`);
+        log.info(`Authenticated:       ${authenticated ? "yes" : "no"}`);
+        if (!authenticated && result.message) {
+          log.info("");
+          log.info(result.message as string);
+        }
+      }
+    });
+}

package/src/cli/commands/avatar.ts

@@ -38,7 +38,7 @@ The avatar system supports two modes:
 Files are stored in ~/.vellum/workspace/data/avatar/:
   character-traits.json   Current trait selection (bodyShape, eyeStyle, color)
   avatar-image.png        Rendered PNG of the character
-  character-ascii.txt     ASCII art representation of the character
+  character-ascii.txt     ASCII art representation (best-effort; may not be written)
 
 Examples:
   $ assistant avatar character update --body-shape blob --eye-style curious --color green
@@ -141,8 +141,8 @@ Examples:
     .addHelpText(
       "after",
       `
-Sets the three character traits and regenerates all avatar files (PNG image,
-ASCII art, and traits JSON). Each trait value must be a valid ID from the
+Sets the three character traits and regenerates avatar files (PNG image,
+traits JSON, and optionally ASCII art). Each trait value must be a valid ID from the
 component set — use "assistant avatar character components" to list valid IDs.
 
 The --body-shape flag sets the character silhouette. Valid values:
@@ -154,8 +154,9 @@ The --eye-style flag sets the eye expression. Valid values:
 The --color flag sets the body fill color. Valid values:
   green, orange, pink, purple, teal, yellow
 
-On success, writes three files to ~/.vellum/workspace/data/avatar/:
-  character-traits.json, avatar-image.png, character-ascii.txt
+On success, writes character-traits.json and avatar-image.png to
+~/.vellum/workspace/data/avatar/. character-ascii.txt is written on a
+best-effort basis and may be skipped if ASCII rendering fails.
 
 Examples:
   $ assistant avatar character update --body-shape blob --eye-style curious --color green
@@ -323,7 +324,7 @@ Examples:
       }
 
       const width = parseInt(opts.width, 10);
-      if (width < 1) {
+      if (!Number.isFinite(width) || width < 1) {
         log.error(
           `Invalid width: "${opts.width}". Must be a positive integer.`,
         );

package/src/cli/commands/config.ts

@@ -152,6 +152,7 @@ Examples:
       if (!path) {
         const jsonSchema = z.toJSONSchema(AssistantConfigSchema, {
           unrepresentable: "any",
+          io: "input",
         });
         log.info(JSON.stringify(jsonSchema, null, 2));
         return;
@@ -165,6 +166,7 @@ Examples:
 
       const jsonSchema = z.toJSONSchema(subSchema, {
         unrepresentable: "any",
+        io: "input",
       });
       log.info(JSON.stringify(jsonSchema, null, 2));
     });

package/src/cli/commands/oauth/providers.ts

@@ -51,6 +51,11 @@ function parseProviderRow(row: ReturnType<typeof getProvider>) {
   if (!row) return row;
   return {
     ...row,
+    displayName: row.displayName ?? null,
+    description: row.description ?? null,
+    dashboardUrl: row.dashboardUrl ?? null,
+    clientIdPlaceholder: row.clientIdPlaceholder ?? null,
+    requiresClientSecret: row.requiresClientSecret ?? 1,
     defaultScopes: row.defaultScopes ? JSON.parse(row.defaultScopes) : [],
     scopePolicy: row.scopePolicy ? JSON.parse(row.scopePolicy) : {},
     extraParams: row.extraParams ? JSON.parse(row.extraParams) : null,
@@ -203,6 +208,14 @@ Examples:
       "--ping-url <url>",
       "Health-check endpoint URL for token validation",
     )
+    .option("--display-name <name>", "Display name for the provider")
+    .option("--description <text>", "Short description")
+    .option("--dashboard-url <url>", "Developer console URL")
+    .option("--client-id-placeholder <text>", "Placeholder for client ID field")
+    .option(
+      "--no-client-secret",
+      "Set requires_client_secret to false (default is true)",
+    )
     .addHelpText(
       "after",
       `
@@ -220,6 +233,12 @@ Arguments (via options):
   --ping-url            Optional URL for a lightweight health-check endpoint.
                         Used by "connections ping" to validate that a stored token
                         is still functional (e.g. "https://api.example.com/user").
+  --display-name        Optional human-readable display name for the provider.
+  --description         Optional short description of the provider.
+  --dashboard-url       Optional URL to the provider's developer console / dashboard.
+  --client-id-placeholder  Optional placeholder text for the client ID input field.
+  --no-client-secret    If set, marks the provider as not requiring a client secret
+                        (sets requires_client_secret to 0). Default is true (1).
 
 Registers a new OAuth provider configuration in the local store. This is
 used for custom integrations not covered by the built-in provider seeds.
@@ -253,6 +272,11 @@ Examples:
           tokenAuthMethod?: string;
           callbackTransport?: string;
           pingUrl?: string;
+          displayName?: string;
+          description?: string;
+          dashboardUrl?: string;
+          clientIdPlaceholder?: string;
+          clientSecret: boolean;
         },
         cmd: Command,
       ) => {
@@ -268,6 +292,11 @@ Examples:
             tokenEndpointAuthMethod: opts.tokenAuthMethod,
             callbackTransport: opts.callbackTransport,
             pingUrl: opts.pingUrl,
+            displayName: opts.displayName,
+            description: opts.description,
+            dashboardUrl: opts.dashboardUrl,
+            clientIdPlaceholder: opts.clientIdPlaceholder,
+            requiresClientSecret: opts.clientSecret ? 1 : 0,
           });
 
           writeOutput(cmd, parseProviderRow(row));

package/src/cli/program.ts

@@ -5,6 +5,7 @@ import { isEmailEnabled } from "../email/feature-gate.js";
 import { registerHooksCommand } from "../hooks/cli.js";
 import { APP_VERSION } from "../version.js";
 import { registerAuditCommand } from "./commands/audit.js";
+import { registerAuthCommand } from "./commands/auth.js";
 import { registerAutonomyCommand } from "./commands/autonomy.js";
 import { registerAvatarCommand } from "./commands/avatar.js";
 import { registerBashCommand } from "./commands/bash.js";
@@ -39,6 +40,16 @@ export function buildCliProgram(): Command {
     .description("Local AI assistant")
     .version(APP_VERSION);
 
+  program.addHelpText(
+    "after",
+    `
+Examples:
+  $ assistant auth info          Show platform identity and auth status
+  $ assistant config list        List all configuration values
+  $ assistant keys list          List stored API keys
+  $ assistant doctor             Run diagnostic checks`,
+  );
+
   registerDefaultAction(program);
   registerBashCommand(program);
   registerConversationsCommand(program);
@@ -49,6 +60,7 @@ export function buildCliProgram(): Command {
   registerTrustCommand(program);
   registerMemoryCommand(program);
   registerAuditCommand(program);
+  registerAuthCommand(program);
   registerAvatarCommand(program);
   registerDoctorCommand(program);
   registerHooksCommand(program);

package/src/cli.ts

@@ -17,10 +17,6 @@ import {
   updateDaemonText,
   updateStatusText,
 } from "./cli/main-screen.jsx";
-import { loadRawConfig, saveRawConfig } from "./config/loader.js";
-import { setServiceField } from "./config/raw-config-utils.js";
-import { MODEL_TO_PROVIDER } from "./daemon/conversation-slash.js";
-import { getModelInfo } from "./daemon/handlers/config-model.js";
 import { renderHistoryContent } from "./daemon/handlers/shared.js";
 import type {
   ConfirmationRequest,
@@ -1030,7 +1026,7 @@ export async function startCli(): Promise<void> {
       return;
     }
 
-    if (content === "/sessions" || content === "/conversations") {
+    if (content === "/conversations") {
       pendingSessionPick = true;
       try {
         const rows = listConversations(20);
@@ -1064,7 +1060,7 @@ export async function startCli(): Promise<void> {
       return;
     }
 
-    if (content === "/copy-session" || content === "/copy-conversation") {
+    if (content === "/copy-conversation") {
       try {
         const mapping = getConversationByKey(conversationKey);
         if (!mapping) {
@@ -1133,37 +1129,9 @@ export async function startCli(): Promise<void> {
     }
 
     if (content === "/model" || content.startsWith("/model ")) {
-      const modelArg = content.slice("/model".length).trim();
-      if (modelArg) {
-        try {
-          const raw = loadRawConfig();
-          const provider = MODEL_TO_PROVIDER[modelArg];
-          setServiceField(raw, "inference", "model", modelArg);
-          if (provider) setServiceField(raw, "inference", "provider", provider);
-          saveRawConfig(raw);
-          const existingProvider = (
-            raw.services as Record<string, Record<string, unknown>>
-          )?.inference?.provider as string | undefined;
-          process.stdout.write(
-            `\n  Model: ${modelArg} (${provider ?? existingProvider})\n\n`,
-          );
-        } catch {
-          process.stdout.write("[Failed to set model]\n");
-        }
-      } else {
-        getModelInfo()
-          .then((info) => {
-            process.stdout.write(
-              `\n  Model: ${info.model} (${info.provider})\n\n`,
-            );
-            prompt();
-          })
-          .catch(() => {
-            process.stdout.write("[Failed to get model info]\n");
-            prompt();
-          });
-        return;
-      }
+      process.stdout.write(
+        "\n  The /model command has been removed. Use Settings to change your model and provider.\n\n",
+      );
       prompt();
       return;
     }
@@ -1295,27 +1263,26 @@ export async function startCli(): Promise<void> {
 
     if (content === "/help") {
       process.stdout.write("\n  Available commands:\n");
-      process.stdout.write("  /new              Start a new conversation\n");
+      process.stdout.write("  /new                Start a new conversation\n");
       process.stdout.write(
-        "  /conversations    Switch between conversations\n",
+        "  /conversations      Switch between conversations\n",
       );
-      process.stdout.write("  /clear            Clear the screen\n");
-      process.stdout.write("  /model [name]     Show or change the model\n");
-      process.stdout.write("  /history          Show conversation history\n");
+      process.stdout.write("  /clear              Clear the screen\n");
+      process.stdout.write("  /history            Show conversation history\n");
       process.stdout.write(
-        "  /undo             Remove last message exchange\n",
+        "  /undo               Remove last message exchange\n",
       );
-      process.stdout.write("  /usage            Show token usage and cost\n");
+      process.stdout.write("  /usage              Show token usage and cost\n");
       process.stdout.write(
-        "  /copy             Copy last response to clipboard\n",
+        "  /copy               Copy last response to clipboard\n",
       );
       process.stdout.write(
-        "  /copy-code        Copy last code block to clipboard\n",
+        "  /copy-code          Copy last code block to clipboard\n",
       );
       process.stdout.write(
-        "  /copy-conversation Copy entire conversation to clipboard\n",
+        "  /copy-conversation  Copy entire conversation to clipboard\n",
       );
-      process.stdout.write("  /help             Show this help\n");
+      process.stdout.write("  /help               Show this help\n");
       process.stdout.write("\n");
       prompt();
       return;

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

@@ -18,6 +18,40 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 **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.
 
+## Filesystem Layout
+
+Apps live under `~/.vellum/workspace/data/apps/`. Each app has a slug-based layout:
+
+```
+~/.vellum/workspace/data/apps/
+  <slug>.json          # App metadata
+  <slug>/              # App directory (contains all app files)
+    index.html         # Main page (entry point rendered in WebView)
+    pages/             # Additional pages
+    records/           # Data records (one JSON file per record)
+    src/               # Source files (multifile TSX apps, formatVersion: 2)
+    dist/              # Compiled output (multifile TSX apps)
+  <slug>.preview       # Preview image (auto-generated)
+```
+
+### Metadata JSON (`<slug>.json`)
+
+Fields: `id`, `name`, `description`, `icon`, `schemaJson`, `createdAt`, `updatedAt`, `formatVersion`, `dirName`.
+
+**Important:** `htmlDefinition` and `pages` are NOT stored in the metadata JSON — they live as separate files inside the app directory (`index.html` and `pages/`).
+
+### Records
+
+Each record is a JSON file at `<slug>/records/<uuid>.json` with shape:
+
+```json
+{ "id": "<uuid>", "appId": "<app-id>", "data": { ... }, "createdAt": "...", "updatedAt": "..." }
+```
+
+### Multifile TSX Apps
+
+For `formatVersion: 2` apps, source files live under `src/` and compiled output under `dist/`. The build system compiles TSX → JS automatically when `app_refresh` is called.
+
 ## Workflow
 
 ### 1. Gather Requirements
@@ -44,7 +78,7 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 **Only ask questions when the request is genuinely ambiguous** - e.g., "build me an app" with no indication of what kind. Even then, prefer building something impressive based on context clues over asking a battery of questions.
 
-**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.
+**When in doubt, build something impressive** and let the user refine. 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.
 
@@ -149,27 +183,27 @@ useEffect(() => {
 }, []);
 ```
 
-**File workflow:** Use `app_file_write` for each source file. Each write automatically triggers a recompile of the project.
+**File workflow:** Use `file_write` for each source file. After writing all files, call `app_refresh` once to compile and refresh the UI.
 
 **Allowed third-party packages:** `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`, `lucide`. Import them directly - esbuild resolves them at build time. No CDN imports. Note: `lucide` is the vanilla JS icon library (not `lucide-react`). Use its `createElement` or `createIcons` API, or manually inline SVG - do not import JSX icon components.
 
-**Example - creating a multi-file project:**
+**Example - creating a multi-file project** (assuming app slug is `project-tracker`):
 
 ```
-app_file_write(app_id, "src/index.html", `<!DOCTYPE html>
+file_write("~/.vellum/workspace/data/apps/project-tracker/src/index.html", `<!DOCTYPE html>
 <html lang="en">
 <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Project Tracker</title></head>
 <body><div id="app"></div></body>
 </html>`)
 
-app_file_write(app_id, "src/main.tsx", `import { render } from 'preact';
+file_write("~/.vellum/workspace/data/apps/project-tracker/src/main.tsx", `import { render } from 'preact';
 import { App } from './components/App';
 import './styles.css';
 
 render(<App />, document.getElementById('app')!);`)
 
-app_file_write(app_id, "src/components/App.tsx", `import { FunctionComponent } from 'preact';
+file_write("~/.vellum/workspace/data/apps/project-tracker/src/components/App.tsx", `import { FunctionComponent } from 'preact';
 import { useState, useEffect } from 'preact/hooks';
 import { Header } from './Header';
 
@@ -188,7 +222,7 @@ export const App: FunctionComponent = () => {
   );
 };`)
 
-app_file_write(app_id, "src/components/Header.tsx", `import { FunctionComponent } from 'preact';
+file_write("~/.vellum/workspace/data/apps/project-tracker/src/components/Header.tsx", `import { FunctionComponent } from 'preact';
 
 interface HeaderProps {
   title: string;
@@ -202,9 +236,12 @@ export const Header: FunctionComponent<HeaderProps> = ({ title, count }) => (
   </header>
 );`)
 
-app_file_write(app_id, "src/styles.css", `.app { padding: var(--v-spacing-lg); }
+file_write("~/.vellum/workspace/data/apps/project-tracker/src/styles.css", `.app { padding: var(--v-spacing-lg); }
 .header { display: flex; justify-content: space-between; align-items: center; }
 .badge { background: var(--v-accent); color: white; padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`)
+
+# After all files are written, compile and refresh:
+app_refresh(app_id)
 ```
 
 **Technical constraints (multi-file):**
@@ -317,8 +354,6 @@ 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                      |
 
-**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.*`:
@@ -384,19 +419,11 @@ vellum.widgets.toast("Saved!", "success", 4000); // Auto-dismiss notification
 vellum.widgets.countdown("timer-el", "2025-12-31T00:00:00Z", {
   onComplete: () => {},
 });
-vellum.widgets.slideshow("deck", {
-  transition: "fade",
-  showDots: true,
-  showArrows: true,
-  showCounter: true,
-  keyboard: true,
-  loop: true,
-});
 ```
 
 #### When to use widgets vs custom HTML
 
-- **Use widgets** for standard patterns - tables, metrics, timelines, notifications, presentations
+- **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.
@@ -490,7 +517,7 @@ Call `app_create` with:
 - `name`: Short descriptive name
 - `description`: One-sentence summary
 - `schema_json`: JSON schema as string
-- `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`.
+- `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 `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)
 
@@ -503,12 +530,14 @@ The app is NOT opened in a workspace panel automatically - users open it via the
 ### 6. Handle Iteration
 <!-- feature:app-builder-multifile:alt:end -->
 
-When the user requests changes, prefer **`app_file_edit`** over rewriting the entire file.
+When the user requests changes, prefer **`file_edit`** over rewriting the entire file.
 
-- **`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.
+- **`file_edit`** - preferred for targeted changes (styles, bugs, features). Provide the full file path (e.g. `~/.vellum/workspace/data/apps/<slug>/src/components/App.tsx`).
+- **`file_write`** - for creating new files or full rewrites.
+- **`app_refresh`** - call ONCE after all file changes are complete to trigger compilation and surface refresh.
+- For metadata changes (`name`, `description`, `schemaJson`, etc.), edit the `<slug>.json` file directly with `file_edit`, then call `app_refresh`.
+
+After making all file changes, call `app_refresh(app_id)` once to compile and refresh the UI. Do NOT call it after every individual file edit — batch your changes first.
 
 Apps can have multiple files (`styles.css`, `app.js`, etc.). Link from `index.html` with standard tags.
 
@@ -524,7 +553,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.
+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.
 
 **Key principles:**
 
@@ -535,8 +564,6 @@ Slides are a different domain from apps. Skip app-specific patterns (contextual
 - Max 6 bullets per slide, max 3 sentences body text
 - Never go below 15px for any visible text
 
-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
 
 - All `window.vellum.data` calls must be wrapped in `try/catch` with user-friendly feedback.
@@ -544,6 +571,54 @@ Init with `vellum.widgets.slideshow()`. Use `.v-slide` with helpers: `.v-slide-l
 - 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 |
+
+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.
+
 ## Actionable UI
 
 When the user wants to triage or bulk-act on items, generate an interactive UI with selectable items and action buttons.