@vellumai/assistant 0.10.0 → 0.10.1-staging.1

package/src/cli/lib/plugin-pin-history.ts

@@ -0,0 +1,257 @@
+/**
+ * Reconstruct the history of marketplace pins for a single plugin.
+ *
+ * The curated `plugins/marketplace.json` manifest (see {@link ./plugin-marketplace})
+ * records only the *current* pin for each plugin — there is no stored version
+ * list. But the manifest is a file in a Git repo, and every time a curator bumps
+ * a plugin's pin, that is a commit to the manifest. So the history of reviewed
+ * pins already exists as the commit history of that one file: this module walks
+ * it (newest → oldest) via the GitHub API and reports the distinct pins a plugin
+ * has been promoted to over time, each tagged with the marketplace commit an
+ * install can reproduce it from.
+ *
+ * Why this is the safe source for "install an older version": every commit on
+ * the default branch was reviewed and merged, so a pin drawn from this history
+ * is a reviewed, known-good revision — unlike an arbitrary caller-supplied ref,
+ * which the install route deliberately refuses. Resolving an older pin to the
+ * marketplace commit that introduced it (rather than the plugin SHA directly)
+ * also means the install reads that era's manifest, so the curated adapter stub
+ * matches the pin and the historical version reproduces coherently.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring the
+ * sibling plugin libraries.
+ */
+
+import { type FetchLike, sanitizePluginName } from "./install-from-github.js";
+import {
+  fetchMarketplaceEntries,
+  MARKETPLACE_MANIFEST_LOCATION,
+} from "./plugin-marketplace.js";
+
+/** Default number of distinct historical pins surfaced by `plugins versions`. */
+export const DEFAULT_PIN_HISTORY_LIMIT = 5;
+
+/**
+ * Cap on how many manifest-touching commits are inspected in one walk. Bounds
+ * the GitHub API cost: a plugin whose pin changes rarely could otherwise force
+ * a fetch of the manifest at every commit that touched it for *any* plugin.
+ * Well above {@link DEFAULT_PIN_HISTORY_LIMIT} so the default listing is
+ * complete in all but pathological histories.
+ */
+const MAX_MARKETPLACE_COMMITS_SCANNED = 100;
+
+/** A single point in a plugin's marketplace-pin history. */
+export interface PluginPinHistoryEntry {
+  /** Plugin commit SHA pinned at this point in history. */
+  readonly pin: string;
+  /**
+   * Marketplace-manifest commit to install this pin from — the newest commit
+   * that carries it. Installing with this as the marketplace ref reproduces the
+   * pin together with the curated adapter stub of the same era.
+   */
+  readonly marketplaceCommit: string;
+  /**
+   * ISO-8601 committer date (UTC) of {@link PluginPinHistoryEntry.marketplaceCommit},
+   * i.e. when this pin was promoted; `null` when the date could not be read.
+   */
+  readonly promotedAt: string | null;
+  /** True for the pin currently active on the default branch. */
+  readonly current: boolean;
+}
+
+/** Options controlling the pin-history walk. */
+export interface ListPinHistoryOptions {
+  /** Max distinct pins to return (newest first). Defaults to {@link DEFAULT_PIN_HISTORY_LIMIT}. */
+  readonly limit?: number;
+  /** Marketplace branch to read history from. Defaults to `main`. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface ListPinHistoryDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+}
+
+/** Shape of a commit entry from the GitHub commits API. */
+interface GitHubCommitListEntry {
+  readonly sha: string;
+  readonly commit: {
+    readonly committer?: { readonly date?: string } | null;
+  } | null;
+}
+
+/** A manifest-touching commit and its committer date. */
+interface ManifestCommit {
+  readonly sha: string;
+  readonly date: string | null;
+}
+
+/** The pin-history walk could not read the marketplace commit list. */
+export class PluginPinHistoryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PluginPinHistoryError";
+  }
+}
+
+/**
+ * List the commits that touched the marketplace manifest on `ref`, newest
+ * first, capped at {@link MAX_MARKETPLACE_COMMITS_SCANNED}. A 404 (the file
+ * never existed at this ref) yields an empty list.
+ */
+async function listManifestCommits(
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<ManifestCommit[]> {
+  const { owner, repo, path } = MARKETPLACE_MANIFEST_LOCATION;
+  const url =
+    `https://api.github.com/repos/${owner}/${repo}/commits` +
+    `?path=${encodeURIComponent(path)}` +
+    `&sha=${encodeURIComponent(ref)}` +
+    `&per_page=${MAX_MARKETPLACE_COMMITS_SCANNED}`;
+
+  const res = await fetchFn(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+  if (res.status === 404) return [];
+  if (!res.ok) {
+    throw new PluginPinHistoryError(
+      `Marketplace commit history fetch failed for ${path} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(await res.text());
+  } catch (err) {
+    throw new PluginPinHistoryError(
+      `Marketplace commit history is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (!Array.isArray(body)) {
+    throw new PluginPinHistoryError(
+      "Marketplace commit history response was not an array",
+    );
+  }
+
+  const commits: ManifestCommit[] = [];
+  for (const item of body as GitHubCommitListEntry[]) {
+    if (typeof item?.sha !== "string") continue;
+    const rawDate = item.commit?.committer?.date;
+    commits.push({
+      sha: item.sha,
+      date: typeof rawDate === "string" ? rawDate : null,
+    });
+  }
+  return commits;
+}
+
+/**
+ * Resolve the plugin's pinned SHA in the manifest at a specific marketplace
+ * commit, or `null` when no entry claims the name at that revision.
+ */
+async function pinAtCommit(
+  name: string,
+  marketplaceCommit: string,
+  fetchFn: FetchLike,
+): Promise<string | null> {
+  const entries = await fetchMarketplaceEntries(
+    { fetch: fetchFn },
+    { ref: marketplaceCommit },
+  );
+  return entries.find((e) => e.name === name)?.source.ref ?? null;
+}
+
+/**
+ * Walk a plugin's distinct marketplace pins, newest first. Each pin is yielded
+ * once, tagged with the newest marketplace commit carrying it. Revisions where
+ * the plugin is absent from the manifest are skipped (a gap, not a pin). The
+ * `current` flag is set against the pin live on `ref` today.
+ *
+ * Bounded by {@link MAX_MARKETPLACE_COMMITS_SCANNED} commits scanned.
+ */
+async function* iteratePinHistory(
+  name: string,
+  ref: string,
+  fetchFn: FetchLike,
+): AsyncGenerator<PluginPinHistoryEntry> {
+  const commits = await listManifestCommits(ref, fetchFn);
+  if (commits.length === 0) return;
+
+  // The pin live on the branch today, used to flag the current entry. Reading
+  // it explicitly (rather than assuming the newest commit carries it) stays
+  // correct even if the plugin was just removed from the manifest at the tip.
+  const currentPin = await pinAtCommit(name, ref, fetchFn);
+
+  let lastPin: string | null = null;
+  for (const commit of commits) {
+    const pin = await pinAtCommit(name, commit.sha, fetchFn);
+    if (pin === null) continue;
+    if (pin === lastPin) continue;
+    lastPin = pin;
+    yield {
+      pin,
+      marketplaceCommit: commit.sha,
+      promotedAt: commit.date,
+      current: currentPin !== null && pin === currentPin,
+    };
+  }
+}
+
+/**
+ * List a plugin's distinct marketplace pins, newest first, capped at
+ * `limit` (default {@link DEFAULT_PIN_HISTORY_LIMIT}). The first entry is the
+ * current pin. An empty list means the plugin has no resolvable history at this
+ * ref (never in the manifest, or the manifest does not exist).
+ *
+ * Throws {@link PluginPinHistoryError} when the commit list cannot be read, and
+ * propagates a `MarketplaceFetchError` if a manifest revision fails to parse.
+ */
+export async function listPinHistory(
+  name: string,
+  deps: ListPinHistoryDeps,
+  opts: ListPinHistoryOptions = {},
+): Promise<PluginPinHistoryEntry[]> {
+  const sanitized = sanitizePluginName(name);
+  const ref = opts.ref ?? "main";
+  const limit = opts.limit ?? DEFAULT_PIN_HISTORY_LIMIT;
+
+  const out: PluginPinHistoryEntry[] = [];
+  for await (const entry of iteratePinHistory(sanitized, ref, deps.fetch)) {
+    out.push(entry);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Resolve a plugin pin (a full commit SHA) to the marketplace commit it should
+ * be installed from, by searching the plugin's pin history. Returns `null` when
+ * the pin is not found in the scanned history — i.e. it is not a reviewed pin
+ * this plugin was ever promoted to (or it predates the scan window).
+ *
+ * Case-insensitive on the SHA, matching the rest of the install pipeline. The
+ * search walks the full scan window, not just the `limit` shown by
+ * {@link listPinHistory}, so a pin older than the default listing still
+ * resolves.
+ */
+export async function resolvePinToMarketplaceCommit(
+  name: string,
+  pin: string,
+  deps: ListPinHistoryDeps,
+  opts: { readonly ref?: string } = {},
+): Promise<PluginPinHistoryEntry | null> {
+  const sanitized = sanitizePluginName(name);
+  const ref = opts.ref ?? "main";
+  const target = pin.trim().toLowerCase();
+  if (target.length === 0) return null;
+
+  for await (const entry of iteratePinHistory(sanitized, ref, deps.fetch)) {
+    if (entry.pin.toLowerCase() === target) return entry;
+  }
+  return null;
+}

package/src/cli/lib/toggle-plugin.ts

@@ -0,0 +1,146 @@
+/**
+ * Enable / disable plugins by creating or removing a `.disabled` sentinel
+ * file inside the plugin's workspace directory.
+ *
+ * The sentinel is read by the daemon at boot:
+ * - User plugins: {@link ../../plugins/mtime-cache.ts} skips any plugin
+ *   whose directory contains `.disabled`.
+ * - Default plugins: {@link ../../daemon/external-plugins-bootstrap.ts}
+ *   checks `<workspace>/plugins/<manifest-name>/.disabled` before init.
+ *
+ * For user plugins the directory already exists (it is the install target).
+ * For default plugins (which live in the source tree) the directory may not
+ * exist yet, so `disable` creates a stub directory and drops the sentinel
+ * inside it. `enable` removes the sentinel and cleans up the stub directory
+ * if it becomes empty (so the workspace stays tidy when the only thing in
+ * it was the sentinel).
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+
+const DISABLED_FILE = ".disabled";
+
+/**
+ * Plugin name pattern: single path segment, kebab-case alphanumerics.
+ * Rejects path traversal (`../`, slashes, null bytes) and any name that
+ * is not a flat directory entry. Same pattern as {@link sanitizePluginName}
+ * but does NOT reject the `default-` prefix, since enable/disable must
+ * accept default plugin names.
+ */
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
+/** The plugin is already in the requested state. */
+export class PluginAlreadyInStateException extends Error {
+  constructor(
+    public readonly name: string,
+    public readonly action: "enable" | "disable",
+  ) {
+    super(
+      `Plugin "${name}" is already ${action === "disable" ? "disabled" : "enabled"}.`,
+    );
+    this.name = "PluginAlreadyInStateException";
+  }
+}
+
+/** The plugin name contains invalid characters or path segments. */
+export class InvalidPluginNameError extends Error {
+  constructor(public readonly name: string) {
+    super(
+      `Invalid plugin name "${name}". Names must be kebab-case alphanumerics (a-z, 0-9, -, _).`,
+    );
+    this.name = "InvalidPluginNameError";
+  }
+}
+
+/** No plugin directory found for the given name. */
+export class PluginDirectoryNotFoundError extends Error {
+  constructor(public readonly name: string) {
+    super(
+      `No plugin directory found for "${name}". Run \`assistant plugins list\` to see installed plugins. To disable a default plugin, prefix the name with "default-" (e.g. "default-advisor").`,
+    );
+    this.name = "PluginDirectoryNotFoundError";
+  }
+}
+
+export interface TogglePluginResult {
+  readonly name: string;
+  readonly action: "enable" | "disable";
+  readonly sentinelPath: string;
+}
+
+/**
+ * Validate a plugin name for enable/disable. Same kebab-case rule as
+ * {@link sanitizePluginName} but allows the `default-` prefix (needed for
+ * toggling default plugins).
+ */
+function validatePluginName(name: string): string {
+  const trimmed = name.trim();
+  if (!PLUGIN_NAME_RE.test(trimmed)) {
+    throw new InvalidPluginNameError(name);
+  }
+  return trimmed;
+}
+
+/**
+ * Disable a plugin by creating a `.disabled` sentinel file in its workspace
+ * directory. For default plugins (names starting with `default-`), creates a
+ * stub directory under `<workspace>/plugins/<name>/` if one does not exist.
+ * For user plugins, the directory must already exist.
+ */
+export function disablePlugin(name: string): TogglePluginResult {
+  const validated = validatePluginName(name);
+  const pluginsDir = getWorkspacePluginsDir();
+  const pluginDir = join(pluginsDir, validated);
+  const sentinelPath = join(pluginDir, DISABLED_FILE);
+
+  if (existsSync(sentinelPath)) {
+    throw new PluginAlreadyInStateException(validated, "disable");
+  }
+
+  if (!existsSync(pluginDir)) {
+    // Only create stub directories for default plugins. User plugins must
+    // already be installed — creating a directory for a name that has no
+    // plugin would be misleading.
+    if (!validated.startsWith("default-")) {
+      throw new PluginDirectoryNotFoundError(validated);
+    }
+    mkdirSync(pluginDir, { recursive: true });
+  }
+
+  // Write empty sentinel file — content is irrelevant, existence is the signal.
+  Bun.write(sentinelPath, "");
+  return { name: validated, action: "disable", sentinelPath };
+}
+
+/**
+ * Enable a plugin by removing the `.disabled` sentinel file from its
+ * workspace directory. If the directory was a stub created by `disable`
+ * (i.e. it contains nothing but the sentinel), it is removed entirely.
+ */
+export function enablePlugin(name: string): TogglePluginResult {
+  const validated = validatePluginName(name);
+  const pluginsDir = getWorkspacePluginsDir();
+  const pluginDir = join(pluginsDir, validated);
+  const sentinelPath = join(pluginDir, DISABLED_FILE);
+
+  if (!existsSync(sentinelPath)) {
+    throw new PluginAlreadyInStateException(validated, "enable");
+  }
+
+  unlinkSync(sentinelPath);
+
+  // Clean up the stub directory if it is now empty (default plugin case).
+  // A user plugin directory has package.json and source files, so it will
+  // never be empty after removing the sentinel.
+  if (existsSync(pluginDir)) {
+    const remaining = readdirSync(pluginDir);
+    if (remaining.length === 0) {
+      rmSync(pluginDir, { recursive: true });
+    }
+  }
+
+  return { name: validated, action: "enable", sentinelPath };
+}

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.