@vellumai/assistant 0.8.1 → 0.8.3

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

@@ -0,0 +1,82 @@
+/**
+ * Remove a plugin previously materialized under `<workspaceDir>/plugins/`.
+ *
+ * Symmetric to {@link ./install-from-github.installPlugin}. The CLI
+ * command `assistant plugins uninstall <name>` is a thin wrapper that
+ * supplies the live workspace directory and formats the result.
+ *
+ * The operation is destructive — a successful return means the plugin
+ * directory and everything beneath it have been removed from disk.
+ * Callers needing a confirmation prompt should run it before invoking
+ * this function (the CLI command does this via `--force`).
+ */
+
+import { existsSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  InvalidPluginNameError,
+  sanitizePluginName,
+} from "./install-from-github.js";
+
+/** Plugin is not present in the workspace plugins directory. */
+export class PluginNotInstalledError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly target: string,
+  ) {
+    super(`Plugin "${pluginName}" is not installed at ${target}.`);
+    this.name = "PluginNotInstalledError";
+  }
+}
+
+/** Options accepted by {@link uninstallPlugin}. */
+export interface UninstallPluginOptions {
+  readonly name: string;
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/** Result of a successful uninstall. */
+export interface UninstallPluginResult {
+  readonly name: string;
+  /** Absolute path that was removed. */
+  readonly target: string;
+}
+
+/**
+ * Validate the name, confirm the plugin exists, then recursively remove
+ * the install target. Throws {@link InvalidPluginNameError} if the name
+ * fails sanitization or {@link PluginNotInstalledError} if no directory
+ * (or symlink to a directory) is present at the resolved target.
+ *
+ * The name check is performed up front so an attacker-supplied
+ * `../../etc/passwd` style argument never reaches `rmSync` — even
+ * though commander typically prevents it at the argv level, defense in
+ * depth.
+ */
+export function uninstallPlugin(
+  opts: UninstallPluginOptions,
+): UninstallPluginResult {
+  const name = sanitizePluginName(opts.name);
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const target = join(pluginsDir, name);
+
+  if (!existsSync(target)) {
+    throw new PluginNotInstalledError(name, target);
+  }
+
+  // `existsSync` follows symlinks; guard against a stray file with the
+  // plugin's name (which would be surprising rather than dangerous —
+  // we'd refuse to delete it).
+  const stats = statSync(target);
+  if (!stats.isDirectory()) {
+    throw new PluginNotInstalledError(name, target);
+  }
+
+  rmSync(target, { recursive: true, force: true });
+  return { name, target };
+}
+
+export { InvalidPluginNameError };

package/src/cli/lib/unknown-command.ts

@@ -0,0 +1,111 @@
+import type { Command } from "commander";
+
+/**
+ * Result of detecting an unknown top-level subcommand. `suggestion` is set
+ * when a near-match is found (Levenshtein distance ≤ 40% of the longer name).
+ */
+export interface UnknownCommandHit {
+  readonly token: string;
+  readonly suggestion?: string;
+}
+
+/**
+ * Collect every top-level subcommand name and alias registered on `program`.
+ */
+export function knownCommandNames(program: Command): Set<string> {
+  const names = new Set<string>();
+  for (const cmd of program.commands) {
+    names.add(cmd.name());
+    for (const alias of cmd.aliases()) {
+      names.add(alias);
+    }
+  }
+  return names;
+}
+
+/**
+ * Pre-parse scan: returns the first positional argv token that doesn't match
+ * any known subcommand/alias, or null when the args look valid.
+ *
+ * Commander processes `--help` / `--version` before any action or hook runs,
+ * so `assistant invalid --help` would otherwise dump the root help instead of
+ * surfacing the unknown command. Callers should run this before `parse()` so
+ * the error wins over the help short-circuit.
+ *
+ * The first non-flag token is treated as the subcommand candidate. Flags are
+ * skipped wholesale; the root program has no value-taking options today.
+ */
+export function detectUnknownCommand(
+  program: Command,
+  argv: readonly string[],
+): UnknownCommandHit | null {
+  const firstPositional = argv.find((token) => !token.startsWith("-"));
+  if (!firstPositional) return null;
+
+  const known = knownCommandNames(program);
+  if (known.has(firstPositional)) return null;
+
+  const suggestion = findClosestCommand(firstPositional, [...known]);
+  return suggestion ? { token: firstPositional, suggestion } : { token: firstPositional };
+}
+
+/**
+ * Format the unknown-command error as a multi-line message. Kept as a pure
+ * function so it can be reused by `default-action`'s in-parse path (when the
+ * user runs `assistant invalid` with no `--help`) and by the pre-parse path.
+ */
+export function formatUnknownCommandMessage(hit: UnknownCommandHit): string {
+  const lines = [`unknown command '${hit.token}'`];
+  if (hit.suggestion) {
+    lines.push(`(Did you mean '${hit.suggestion}'?)`);
+  }
+  lines.push(`Run 'assistant --help' to see a list of available commands.`);
+  return lines.join("\n");
+}
+
+/**
+ * Find the closest matching command name using Levenshtein distance.
+ * Returns the best match if the distance is ≤ 40% of the longer string's
+ * length, otherwise returns undefined.
+ */
+export function findClosestCommand(
+  input: string,
+  candidates: readonly string[],
+): string | undefined {
+  let best: string | undefined;
+  let bestDist = Infinity;
+  const lowered = input.toLowerCase();
+
+  for (const name of candidates) {
+    const dist = levenshtein(lowered, name.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = name;
+    }
+  }
+
+  const maxLen = Math.max(input.length, best?.length ?? 0);
+  if (best && bestDist <= Math.ceil(maxLen * 0.4)) {
+    return best;
+  }
+  return undefined;
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    Array(n + 1).fill(0),
+  );
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}

package/src/cli/program.ts

@@ -5,6 +5,7 @@ import { Command } from "commander";
 import { initFeatureFlagOverrides } from "../config/assistant-feature-flags.js";
 import { getConfigReadOnly } from "../config/loader.js";
 import { isEmailEnabled } from "../email/feature-gate.js";
+import { isExternalPluginsEnabled } from "../plugins/feature-gate.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { APP_VERSION } from "../version.js";
 import { registerAttachmentCommand } from "./commands/attachment.js";
@@ -37,18 +38,22 @@ import { registerNotificationsCommand } from "./commands/notifications.js";
 import { registerOAuthCommand } from "./commands/oauth/index.js";
 import { registerPendingCommand } from "./commands/pending.js";
 import { registerPlatformCommand } from "./commands/platform/index.js";
+import { registerPluginsCommand } from "./commands/plugins.js";
 import { registerRoutesCommand } from "./commands/routes.js";
+import { registerSchedulesCommand } from "./commands/schedules.js";
 import { registerSequenceCommand } from "./commands/sequence.js";
 import { registerSkillsCommand } from "./commands/skills.js";
 import { registerStatusCommand } from "./commands/status.js";
 import { registerSttCommand } from "./commands/stt.js";
 import { registerTaskCommand } from "./commands/task.js";
+import { registerTelemetryCommand } from "./commands/telemetry.js";
 import { registerTrustCommand } from "./commands/trust.js";
 import { registerTtsCommand } from "./commands/tts.js";
 import { registerUiCommand } from "./commands/ui.js";
 import { registerUsageCommand } from "./commands/usage.js";
 import { registerWatchersCommand } from "./commands/watchers.js";
 import { registerWebhooksCommand } from "./commands/webhooks.js";
+import { red } from "./lib/cli-colors.js";
 import { log } from "./logger.js";
 
 /**
@@ -57,6 +62,20 @@ import { log } from "./logger.js";
  */
 export async function buildCliProgram(): Promise<Command> {
   await initFeatureFlagOverrides({ retryBackoffsMs: [], callTimeoutMs: 200 });
+  return buildCliProgramTree();
+}
+
+/**
+ * Synchronously build the CLI program tree without pre-populating the
+ * feature-flag cache. Use this from inside the daemon, where flags are
+ * already initialized — calling `buildCliProgram` from there would round-trip
+ * to the gateway unnecessarily.
+ *
+ * Same shape as `buildCliProgram` minus the async feature-flag init: registers
+ * the full subcommand set (conditionally gated on email / external-plugins
+ * flags via `getConfigReadOnly()`) and installs the workspace-preAction hook.
+ */
+export function buildCliProgramTree(): Command {
   const program = new Command();
 
   program
@@ -65,6 +84,13 @@ export async function buildCliProgram(): Promise<Command> {
     .version(APP_VERSION)
     .allowExcessArguments(true);
 
+  // Color Commander-emitted error output red (unknown options, missing args,
+  // cmd.error() calls). Plain success output and --help text are untouched.
+  // The `red` helper is a no-op when stderr isn't a TTY or NO_COLOR is set.
+  program.configureOutput({
+    outputError: (str, write) => write(red(str)),
+  });
+
   program.addHelpText(
     "after",
     `
@@ -107,12 +133,17 @@ Examples:
   registerOAuthCommand(program);
   registerPendingCommand(program);
   registerPlatformCommand(program);
+  if (isExternalPluginsEnabled(getConfigReadOnly())) {
+    registerPluginsCommand(program);
+  }
   registerRoutesCommand(program);
+  registerSchedulesCommand(program);
   registerSequenceCommand(program);
   registerStatusCommand(program);
   registerSkillsCommand(program);
   registerSttCommand(program);
   registerTaskCommand(program);
+  registerTelemetryCommand(program);
   registerTrustCommand(program);
   registerTtsCommand(program);
   registerUiCommand(program);
@@ -126,9 +157,28 @@ Examples:
   // remain available even without a workspace.
   // Workspace-independent commands are exempt:
   //   completions — pure shell-script generation, no workspace files needed
-  const workspaceExemptCommands = new Set(["completions", "status"]);
+  //   status     — diagnostic; should run even when the workspace is broken
+  //   changelog  — pure read-only network surface backed by GitHub Releases;
+  //                its on-disk cache is best-effort and tolerates a missing
+  //                workspace dir (see changelog.ts:writeCache)
+  const workspaceExemptCommands = new Set([
+    "completions",
+    "status",
+    "changelog",
+  ]);
+  // An action command's `.name()` returns the leaf (e.g. "show" for
+  // `changelog show <ver>`), so we walk up the parent chain to see whether
+  // any ancestor — typically the top-level subcommand — is exempt.
+  const isExemptFromWorkspaceCheck = (command: Command): boolean => {
+    let current: Command | null | undefined = command;
+    while (current && current !== program) {
+      if (workspaceExemptCommands.has(current.name())) return true;
+      current = current.parent;
+    }
+    return false;
+  };
   program.hook("preAction", (_thisCommand, actionCommand) => {
-    if (workspaceExemptCommands.has(actionCommand.name())) {
+    if (isExemptFromWorkspaceCheck(actionCommand)) {
       return;
     }
     const workspaceDir = getWorkspaceDir();

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

@@ -110,20 +110,22 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
 }
 
 // ---------------------------------------------------------------------------
-// Override loading — reads from gateway IPC socket or local file
+// Override loading — reads from gateway IPC socket
 // ---------------------------------------------------------------------------
 
 /**
- * Module-level cache of feature flag override values. Populated lazily on
- * first access, invalidated by `clearFeatureFlagOverridesCache()`.
+ * Module-level cache of feature flag override values. Populated by
+ * `initFeatureFlagOverrides()` at startup, invalidated by
+ * `clearFeatureFlagOverridesCache()`.
  */
 let cachedOverrides: Record<string, boolean> | null = null;
 
 /**
- * True when `cachedOverrides` was populated by the gateway IPC fetch (or
- * preseeded by a test). False/unset when the cache was populated by the sync
- * file fallback in `loadOverrides()`, which must not prevent a subsequent
- * authoritative gateway fetch from running.
+ * True when `cachedOverrides` was populated by the gateway IPC fetch or
+ * preseeded by a test via `_setOverridesForTesting()`. Guards
+ * `initFeatureFlagOverrides()` from clobbering an existing populated cache
+ * when called a second time (e.g. by a CLI entry point after the daemon
+ * has already initialized).
  */
 let cachedOverridesFromGateway = false;
 
@@ -247,59 +249,30 @@ function loadOverrides(): Record<string, boolean> {
   return cachedOverrides ?? {};
 }
 
-// ---------------------------------------------------------------------------
-// Remote values — platform-pushed flags cached in a local JSON file
-// ---------------------------------------------------------------------------
-
 /**
- * Module-level cache of remote feature flag values. Populated lazily on
- * first access, invalidated by `clearFeatureFlagOverridesCache()`.
- */
-let cachedRemoteValues: Record<string, boolean> | null = null;
-
-/**
- * Load remote values with module-level caching.
+ * Invalidate the cached overrides so the next call to
+ * `isAssistantFeatureFlagEnabled` re-reads from the gateway.
  *
- * Remote values are now always included in the gateway IPC response (merged
- * server-side), so this only returns the injected test cache. In production,
- * remote values flow through the overrides cache.
- */
-function loadRemoteValues(): Record<string, boolean> {
-  return cachedRemoteValues ?? {};
-}
-
-/**
- * Invalidate the cached override and remote values so the next call to
- * `isAssistantFeatureFlagEnabled` re-reads from the source.
- *
- * Called by the config watcher when the feature-flags file changes.
+ * Used by tests between cases to reset module state.
  */
 export function clearFeatureFlagOverridesCache(): void {
   cachedOverrides = null;
   cachedOverridesFromGateway = false;
-  cachedRemoteValues = null;
 }
 
 /**
  * Directly inject override values into the module-level cache.
  *
- * **Test-only** — bypasses file/gateway loading so unit tests can control
- * flag state without writing to disk. Production code should never call this;
- * use `clearFeatureFlagOverridesCache()` instead and let the resolver
- * re-read from the appropriate source.
- *
- * Forces `cachedRemoteValues` to an empty record (not `null`) so the resolver
- * does not fall through to reading `feature-flags-remote.json` from disk. This
- * matters because a developer's local remote-cache file can leak platform-set
- * values into the test environment (e.g. `email-channel: true`), defeating
- * test isolation.
+ * **Test-only** — bypasses the gateway IPC fetch so unit tests can control
+ * flag state without standing up a real gateway. Production code should
+ * never call this; use `clearFeatureFlagOverridesCache()` instead and let
+ * the resolver re-read from the gateway.
  */
 export function _setOverridesForTesting(
   overrides: Record<string, boolean>,
 ): void {
   cachedOverrides = { ...overrides };
   cachedOverridesFromGateway = true;
-  cachedRemoteValues = {};
 }
 
 // ---------------------------------------------------------------------------
@@ -310,9 +283,11 @@ export function _setOverridesForTesting(
  * Resolve whether an assistant feature flag is enabled.
  *
  * Resolution order:
- *   1. Override from gateway IPC socket
- *   2. defaults registry `defaultEnabled`         (for declared assistant-scope keys)
- *   3. `true`                                     (for undeclared keys with no override)
+ *   1. Override from the gateway IPC fetch (includes platform-pushed remote
+ *      values, which the gateway merges server-side: persisted > remote >
+ *      registry)
+ *   2. Registry `defaultEnabled` (for declared assistant-scope keys)
+ *   3. `true` (for undeclared keys with no override)
  */
 export function isAssistantFeatureFlagEnabled(
   key: string,
@@ -322,18 +297,13 @@ export function isAssistantFeatureFlagEnabled(
   const declared = defaults[key];
   const overrides = loadOverrides();
 
-  // 1. Check overrides from gateway / local file
+  // 1. Check overrides from the gateway IPC cache.
   const explicit = overrides[key];
   if (typeof explicit === "boolean") return explicit;
 
-  // 2. Check remote values (platform-pushed, cached locally)
-  const remote = loadRemoteValues();
-  const remoteValue = remote[key];
-  if (typeof remoteValue === "boolean") return remoteValue;
-
-  // 3. For declared keys, use the registry default
+  // 2. For declared keys, use the registry default.
   if (declared) return declared.defaultEnabled;
 
-  // 4. Undeclared keys with no persisted override default to enabled
+  // 3. Undeclared keys with no override default to enabled.
   return true;
 }

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

@@ -54,8 +54,114 @@ Each record is a JSON file at `<slug>/records/<uuid>.json` with shape:
 
 All new apps use `formatVersion: 2`: source files live under `src/` and compiled output lives under `dist/`. The build system compiles TSX to JS automatically when `app_refresh` is called.
 
+## Responsive Baseline & Mobile-First Mode
+
+Every app must be responsive across the full width range — phone (~360px) to desktop (~1400px+). The conversation context's `<turn_context>` block carries an `interface:` field. Visual interfaces are `macos`, `ios`, and `web`; the field doesn't toggle responsiveness on or off — it shifts the **design priority**. Non-visual values like `phone` represent voice channels that can't render apps at all and don't need to be considered here.
+
+- **`interface: ios`** (or any future mobile-web / android identifier) — mobile-first build. Design the narrow viewport first and progressively enhance upward at wider widths.
+- **`interface: macos` / `web`** — desktop-first build. Design the larger composition first; the narrow-width fallback must still meet the universal baseline below but doesn't need to feel like a native mobile app.
+- **Field absent or ambiguous** — default to desktop-first unless the user's request itself implies phone use ("for my iPhone home screen", "a tap-tracker I'll use on the go").
+
+### Universal baseline (every build, regardless of interface)
+
+These rules aren't mobile-specific — they're touch / responsive a11y baselines that any user-resizable WebView needs.
+
+**Viewport & safe areas**
+
+- Viewport meta: `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`. Never set `user-scalable=no` — it blocks accessibility zoom.
+- Pad the root container with `env(safe-area-inset-*)` so content clears the notch / home indicator when the app is opened on a notched device: `padding-top: max(var(--v-spacing-lg), env(safe-area-inset-top))`, mirrored for `-bottom`/`-left`/`-right`. On desktop the env vars resolve to `0` and the `max()` falls through to the design-system value — no-op.
+- Use `100dvh` (dynamic viewport height), not `100vh`, for full-height containers. `100vh` creates a scroll-jump on every mobile browser regardless of build mode.
+
+**Form controls**
+
+- `<input>`, `<textarea>`, `<select>` must be `font-size: 16px` or larger, or iOS Safari will zoom on focus and break the layout. This applies to every build — anyone may open a desktop-built app on their phone.
+- Add `inputmode` to text fields with structured input: `numeric` for integers, `decimal` for amounts, `email`, `tel`, `url`. Add matching `autocomplete` and `autocapitalize` hints where appropriate.
+
+**Touch & hover**
+
+- Interactive elements (buttons, list rows, nav items, toggles, icon buttons) must be ≥44×44pt. `.v-button` already meets this; for custom controls, set `min-height: 44px` explicitly.
+- Gate hover affordances behind `@media (hover: hover)` so they don't stick on touch devices visiting a desktop-built app.
+- Disable text selection on app chrome (headers, nav, buttons) with `user-select: none; -webkit-user-select: none` so long-press doesn't pop the iOS selection menu over interactive elements.
+
+**Layout fluidity**
+
+- Fluid widths only — no fixed-pixel layouts. Use `%`, `fr`, `minmax`, `clamp()` instead of `px` on container widths.
+- Horizontal-scroll tables don't work on narrow screens. At narrow widths, collapse rows into stacked cards with labels and values arranged vertically. (Mobile-first builds can use cards everywhere; desktop-first builds can keep the table at wide widths and switch to cards below a breakpoint.)
+- `vellum.widgets.*` chart containers should be sized in `vw`/`%`, not fixed `px`. Prefer simpler chart types (sparkline, bar) at narrow widths — dense multi-series charts lose detail.
+
+### Mobile-first priorities (`interface: ios` or future mobile identifier)
+
+These are the **design priority differences** that mobile-first builds adopt on top of the universal baseline. They reflect "narrow viewport is the primary experience, wider widths progressively enhance."
+
+**Typography**
+
+- Default body text to `--v-font-size-lg` (17px), not `--v-font-size-base` (14px) — the desktop base is too small to read comfortably on a phone. At wider widths the same 17px reads fine.
+
+**Spacing**
+
+- Bump default vertical rhythm one step (e.g. `--v-spacing-md` → `--v-spacing-lg` between cards and sections) so users can comfortably scroll-stop on each item.
+
+**Layout**
+
+- One column as the **default**, not as a narrow-width fallback. `flex-direction: column` first; opt into a multi-column grid only above a width breakpoint (`@media (min-width: 720px)`). No side rails, no two-pane master/detail, no fixed-width sidebars in the default view.
+- Bottom-anchor the primary action (e.g. "Add", "Save") so the thumb can reach it: `position: sticky; bottom: env(safe-area-inset-bottom)` over the scrolling list. On wider widths you may re-flow it back inline.
+- Replace side modals and popovers with bottom sheets that animate up from the bottom edge.
+
+**Interaction**
+
+- Skip the Tab/Enter/Esc keyboard pattern from "Interaction Standards" as the primary affordance — on mobile, focus comes from taps, submit from the soft keyboard's `return`, dismissal from a swipe down on bottom sheets. Keyboard support is still allowed (external-keyboard users exist on iPad) but isn't the design driver.
+
+### Desktop-first priorities (`interface: macos` / `web`)
+
+The default behaviour the rest of this skill describes — multi-column composition, hover-rich affordances, denser information, side modals, inline primary actions. The universal baseline above is the floor: the narrow-width view must still work and follow the touch / responsive a11y rules, but it doesn't need to feel native to mobile.
+
+Everything else in this skill applies unchanged.
+
 ## Workflow
 
+### 0. Preflight — Pin to a high-quality model
+
+App building is design-heavy judgment work — color palettes, layout decisions, component architecture, micro-interactions. A stronger model produces meaningfully better apps: more creative visual directions, cleaner component boundaries, fewer generic patterns. Before building, check whether the conversation is already pinned to the quality profile:
+
+```
+assistant inference session list
+```
+
+If no session is active, check the current default profile:
+
+```
+assistant config get llm.default.profile
+```
+
+If the profile is already `quality-optimized`, skip the rest of this step and proceed to Step 1.
+
+**If the active profile is `balanced`, `cost-optimized`, or any non-quality profile, you MUST ask the user for permission before switching. Do NOT open an inference session without explicit user confirmation.** Use `assistant ui confirm`:
+
+```
+assistant ui confirm --message "App building works best with a high-quality model — it makes better design decisions, writes cleaner components, and produces more visually polished results. Switch to the quality profile for this build? (You can switch back after.)"
+```
+
+If `assistant ui confirm` isn't available on this binary, ask the user directly in conversation instead. **Either way, wait for the user's answer before proceeding.**
+
+**Only if the user confirms**, open an inference session:
+
+```
+assistant inference session open quality-optimized --ttl 1h
+```
+
+If `quality-optimized` isn't a profile name on this workspace, list the available profiles and open against the highest-quality one:
+
+```
+assistant config get llm.profiles
+assistant inference session open <profile-name> --ttl 1h
+```
+
+The `--ttl 1h` gives comfortable headroom for a typical app build without leaving a forever-pinned session if the close in Step 6 is skipped.
+
+**If the user declines, do not switch profiles.** Proceed with the current profile — the build still works, the model just won't be pinned. Skip the close in Step 6 too.
+
+If `assistant inference session` isn't available on this binary, proceed without it.
+
 ### 1. Gather Requirements
 
 **Default: just build.** When a user says "build me a habit tracker," don't ask what colors they want or how many fields to include. Immediately:
@@ -177,27 +283,31 @@ useEffect(() => {
 }, []);
 ```
 
-**File workflow:** Call `app_create` first to create the app record and scaffold, use `file_write` for each source file under `src/`, then call `app_refresh` once to compile and refresh the UI.
+**File workflow:** Pass all source files inline via the `source_files` parameter of `app_create`. This writes and compiles the real app in a single call — no scaffold placeholder, no separate `file_write` or `app_refresh` needed for initial creation. For subsequent edits, use `file_edit`/`file_write` then call `app_refresh` once.
 
 **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** (assuming app slug is `project-tracker`):
+**Example - creating a multi-file project:**
 
 ```
-file_write("{workspaceDir}/data/apps/project-tracker/src/index.html", `<!DOCTYPE html>
+app_create({
+  name: "Project Tracker",
+  description: "Track projects with status and priority",
+  schema_json: '{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string"}},"required":["title"]}',
+  preview: { title: "Project Tracker", icon: "📋" },
+  source_files: {
+    "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>`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/main.tsx", `import { render } from 'preact';
+</html>`,
+    "src/main.tsx": `import { render } from 'preact';
 import { App } from './components/App';
 import './styles.css';
 
-render(<App />, document.getElementById('app')!);`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/components/App.tsx", `import { FunctionComponent } from 'preact';
+render(<App />, document.getElementById('app')!);`,
+    "src/components/App.tsx": `import { FunctionComponent } from 'preact';
 import { useState, useEffect } from 'preact/hooks';
 import { Header } from './Header';
 
@@ -217,9 +327,8 @@ export const App: FunctionComponent = () => {
       {/* ... */}
     </div>
   );
-};`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/components/Header.tsx", `import { FunctionComponent } from 'preact';
+};`,
+    "src/components/Header.tsx": `import { FunctionComponent } from 'preact';
 
 interface HeaderProps {
   title: string;
@@ -231,14 +340,12 @@ export const Header: FunctionComponent<HeaderProps> = ({ title, count }) => (
     <h1>{title}</h1>
     <span className="badge">{count} items</span>
   </header>
-);`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/styles.css", `.app { padding: var(--v-spacing-lg); }
+);`,
+    "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: var(--v-aux-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)
+.badge { background: var(--v-accent); color: var(--v-aux-white); padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`
+  }
+})
 ```
 
 **Technical constraints (multi-file):**
@@ -329,10 +436,11 @@ Call `app_create` with:
 - `name`: Short descriptive name
 - `description`: One-sentence summary
 - `schema_json`: JSON schema as string
-- `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat
+- `source_files`: Map of relative file paths to contents (e.g. `{"src/main.tsx": "...", "src/styles.css": "..."}`). **Always include this** with the complete app source — it writes, compiles, and opens the real app in a single call.
+- `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat after the app is built. Only fires when real source files are provided (not for scaffold-only apps).
 - `preview`: Always include - `title` (required), `subtitle`, `description`, `icon` (image URL preferred, emoji fallback), `metrics` (up to 3 key-value pills)
 
-Do not pass `html` or `pages` to `app_create`; those single-file shortcuts are retired. After `app_create` returns the app ID, write the real app source under `src/` and call `app_refresh`.
+Do not pass `html` or `pages` to `app_create`; those single-file shortcuts are retired.
 
 The app is NOT opened in a workspace panel automatically - users open it via the 'Open App' button on the inline card.
 
@@ -349,6 +457,16 @@ After making all file changes, call `app_refresh(app_id)` once to compile and re
 
 Apps should have multiple source files under `src/` (`styles.css`, components, helpers, etc.). Import CSS and modules from TSX so esbuild includes them in the compiled output.
 
+### 6. Close the inference session
+
+If you opened an inference session in Step 0, close it now:
+
+```
+assistant inference session close
+```
+
+If you skipped the open in Step 0 (because the user declined, the CLI didn't have the command, or the profile was already quality), skip this step too.
+
 ## Interaction Standards
 
 Every app must meet these baselines:
@@ -357,7 +475,7 @@ Every app must meet these baselines:
 - **Confirmation for destructive actions:** Use `window.vellum.confirm(title, message)` before deleting or resetting. Returns `Promise<boolean>`.
 - **Form validation:** Validate before submit, show errors inline, disable submit during async operations.
 - **Loading states:** Never show a blank screen while data loads. Use skeleton shimmer or spinners.
-- **Keyboard navigation:** `Tab` between elements, `Enter` to submit, `Escape` to close/cancel.
+- **Keyboard navigation:** `Tab` between elements, `Enter` to submit, `Escape` to close/cancel. *(De-prioritised on mobile-first builds — see [Responsive Baseline & Mobile-First Mode](#responsive-baseline--mobile-first-mode).)*
 
 ## Presentation Slide Design