@vellumai/assistant 0.7.0 → 0.7.2

package/src/cli/lib/daemon-credential-client.ts

@@ -3,6 +3,7 @@ import type { DeleteResult } from "../../security/credential-backend.js";
 import { credentialKey } from "../../security/credential-key.js";
 import {
   deleteSecureKeyAsync,
+  getActiveBackendName,
   setSecureKeyAsync,
 } from "../../security/secure-keys.js";
 import { getLogger } from "../../util/logger.js";
@@ -16,6 +17,26 @@ function isDaemonUnreachable(error: string): boolean {
   return error === DAEMON_UNREACHABLE;
 }
 
+// ---------------------------------------------------------------------------
+// Result types — include error context so the CLI can surface it
+// ---------------------------------------------------------------------------
+
+export interface SetSecureKeyResult {
+  ok: boolean;
+  /** Human-readable error reason when ok=false. */
+  error?: string;
+}
+
+export interface DeleteSecureKeyResult {
+  result: DeleteResult;
+  /** Human-readable error reason when result="error". */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Set
+// ---------------------------------------------------------------------------
+
 /**
  * Store a secret via the daemon IPC socket (so daemon-side singletons
  * stay in sync). Falls back to direct `setSecureKeyAsync()` when the
@@ -25,34 +46,61 @@ export async function setSecureKeyViaDaemon(
   type: string,
   name: string,
   value: string,
-): Promise<boolean> {
-  const ipc = await cliIpcCall<{ success: boolean }>("secrets/write", {
-    type,
-    name,
-    value,
-  });
+): Promise<SetSecureKeyResult> {
+  const ipc = await cliIpcCall<{ success: boolean; error?: string }>(
+    "secrets/write",
+    { type, name, value },
+  );
 
-  if (ipc.ok && ipc.result) {
-    return ipc.result.success;
+  if (ipc.ok && ipc.result?.success) {
+    return { ok: true };
   }
 
+  // Daemon returned an IPC-level error (thrown InternalError, etc.)
   if (ipc.error && !isDaemonUnreachable(ipc.error)) {
     log.warn({ type, name, error: ipc.error }, "Daemon secret write failed");
-    return false;
+    return { ok: false, error: ipc.error };
+  }
+
+  // Daemon returned success=false (e.g. validation error, backend failure)
+  if (ipc.ok && ipc.result && !ipc.result.success) {
+    return {
+      ok: false,
+      error: ipc.result.error || "Credential write rejected by assistant",
+    };
   }
 
   // Daemon unreachable — fall back to direct write.
-  if (type === "credential" && !name.startsWith("credential/")) {
+  let account: string;
+  if (type === "api_key") {
+    account = credentialKey(name, "api_key");
+  } else if (type === "credential" && !name.startsWith("credential/")) {
     const colonIdx = name.lastIndexOf(":");
     if (colonIdx > 0 && colonIdx < name.length - 1) {
       const service = name.slice(0, colonIdx);
       const field = name.slice(colonIdx + 1);
-      return setSecureKeyAsync(credentialKey(service, field), value);
+      account = credentialKey(service, field);
+    } else {
+      account = name;
     }
+  } else {
+    account = name;
   }
-  return setSecureKeyAsync(name, value);
+
+  const ok = await setSecureKeyAsync(account, value);
+  if (!ok) {
+    return {
+      ok: false,
+      error: `Failed to store credential (backend: ${getActiveBackendName()})`,
+    };
+  }
+  return { ok: true };
 }
 
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+
 /**
  * Delete a secret via the daemon IPC socket. Falls back to direct
  * `deleteSecureKeyAsync()` when the daemon is not running.
@@ -60,31 +108,79 @@ export async function setSecureKeyViaDaemon(
 export async function deleteSecureKeyViaDaemon(
   type: string,
   name: string,
-): Promise<DeleteResult> {
+): Promise<DeleteSecureKeyResult> {
   const ipc = await cliIpcCall<{ success: boolean }>("secrets/delete", {
     type,
     name,
   });
 
-  if (ipc.ok && ipc.result) {
-    return ipc.result.success ? "deleted" : "error";
+  if (ipc.ok && ipc.result?.success) {
+    return { result: "deleted" };
   }
 
+  // Daemon returned an IPC-level error
   if (ipc.error && !isDaemonUnreachable(ipc.error)) {
     if (ipc.error.includes("not found") || ipc.error.includes("404")) {
-      return "not-found";
+      return { result: "not-found" };
     }
-    return "error";
+    return { result: "error", error: ipc.error };
+  }
+
+  // Daemon returned success=false
+  if (ipc.ok && ipc.result && !ipc.result.success) {
+    return {
+      result: "error",
+      error: "Credential delete rejected by assistant",
+    };
   }
 
   // Daemon unreachable — fall back to direct delete.
+  if (type === "api_key") {
+    // Delete from both locations; during migration overlap both may exist.
+    const credResult = await deleteSecureKeyAsync(
+      credentialKey(name, "api_key"),
+    );
+    if (credResult === "error") {
+      return {
+        result: "error",
+        error: `Failed to delete credential (backend: ${getActiveBackendName()})`,
+      };
+    }
+    const bareResult = await deleteSecureKeyAsync(name);
+    if (bareResult === "error") {
+      return {
+        result: "error",
+        error: `Failed to delete credential (backend: ${getActiveBackendName()})`,
+      };
+    }
+    return {
+      result:
+        credResult === "deleted" || bareResult === "deleted"
+          ? "deleted"
+          : "not-found",
+    };
+  }
+
+  let account: string;
   if (type === "credential" && !name.startsWith("credential/")) {
     const colonIdx = name.lastIndexOf(":");
     if (colonIdx > 0 && colonIdx < name.length - 1) {
       const service = name.slice(0, colonIdx);
       const field = name.slice(colonIdx + 1);
-      return deleteSecureKeyAsync(credentialKey(service, field));
+      account = credentialKey(service, field);
+    } else {
+      account = name;
     }
+  } else {
+    account = name;
+  }
+
+  const result = await deleteSecureKeyAsync(account);
+  if (result === "error") {
+    return {
+      result: "error",
+      error: `Failed to delete credential (backend: ${getActiveBackendName()})`,
+    };
   }
-  return deleteSecureKeyAsync(name);
+  return { result };
 }

package/src/cli/program.ts

@@ -27,6 +27,7 @@ import { registerCredentialsCommand } from "./commands/credentials.js";
 import { registerDefaultAction } from "./commands/default-action.js";
 import { registerDomainCommand } from "./commands/domain.js";
 import { registerEmailCommand } from "./commands/email.js";
+import { registerGatewayCommand } from "./commands/gateway.js";
 import { registerImageGenerationCommand } from "./commands/image-generation.js";
 import { registerInferenceCommand } from "./commands/inference.js";
 import { registerKeysCommand } from "./commands/keys.js";
@@ -35,6 +36,7 @@ import { registerMemoryCommand } from "./commands/memory.js";
 import { registerMemoryV2Command } from "./commands/memory-v2.js";
 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 { registerRoutesCommand } from "./commands/routes.js";
 import { registerSequenceCommand } from "./commands/sequence.js";
@@ -95,6 +97,7 @@ Examples:
     registerDomainCommand(program);
     registerEmailCommand(program);
   }
+  registerGatewayCommand(program);
   registerImageGenerationCommand(program);
   registerInferenceCommand(program);
   registerKeysCommand(program);
@@ -103,6 +106,7 @@ Examples:
   registerMemoryV2Command(program);
   registerNotificationsCommand(program);
   registerOAuthCommand(program);
+  registerPendingCommand(program);
   registerPlatformCommand(program);
   registerRoutesCommand(program);
   registerSequenceCommand(program);

package/src/cli.ts

@@ -498,27 +498,6 @@ export async function startCli(): Promise<void> {
         prompt();
         break;
 
-      case "secret_detected": {
-        const wasSpinning = spinner.isSpinning;
-        spinner.stop();
-        const types = msg.matches.map((m) => m.type).join(", ");
-        const actionLabel =
-          msg.action === "redact"
-            ? "redacted"
-            : msg.action === "block"
-              ? "blocked"
-              : "detected";
-        process.stdout.write(
-          `\n  ⚠ Secret ${actionLabel} in ${msg.toolName} output: ${types}\n`,
-        );
-        for (const match of msg.matches) {
-          process.stdout.write(`    • ${match.type}: ${match.redactedValue}\n`);
-        }
-        process.stdout.write("\n");
-        if (wasSpinning) spinner.start("Thinking...");
-        break;
-      }
-
       case "conversation_list_response":
         if (pendingSessionPick) {
           renderConversationPicker(msg.conversations);

package/src/config/__tests__/feature-flag-registry-guard.test.ts

@@ -31,7 +31,7 @@ function loadRegistry(): Record<string, unknown> {
   return JSON.parse(raw);
 }
 
-const VALID_SCOPES = new Set(["assistant", "macos"]);
+const VALID_SCOPES = new Set(["assistant", "client"]);
 
 // ---------------------------------------------------------------------------
 // Tests
@@ -169,7 +169,7 @@ describe("unified feature flag registry guard", () => {
       const scope = flag.scope as string;
       if (!VALID_SCOPES.has(scope)) {
         violations.push(
-          `flag '${flag.id}' has invalid scope '${scope}' (expected 'assistant' or 'macos')`,
+          `flag '${flag.id}' has invalid scope '${scope}' (expected 'assistant' or 'client')`,
         );
       }
     }

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

@@ -17,8 +17,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { ipcGetFeatureFlags } from "../ipc/gateway-client.js";
+import { getLogger } from "../util/logger.js";
 import type { AssistantConfig } from "./schema.js";
 
+const log = getLogger("assistant-feature-flags");
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -140,6 +143,20 @@ async function fetchOverridesFromGateway(): Promise<Record<string, boolean>> {
   }
 }
 
+/**
+ * Default backoff schedule (ms) between `initFeatureFlagOverrides` retries
+ * when the gateway IPC fetch returns empty. The daemon and gateway start
+ * as sibling child processes of the macOS app, so the daemon can race
+ * ahead of the gateway binding `gateway.sock`. Each delay is the
+ * *additional* wait before the next attempt, so total worst-case latency
+ * is the sum: 250 + 500 + 1000 + 2000 + 4000 = 7.75s. All retries run in
+ * the background (lifecycle.ts fires `initFeatureFlagOverrides`
+ * non-blocking), so this never delays startup.
+ */
+const DEFAULT_INIT_RETRY_BACKOFFS_MS: readonly number[] = [
+  250, 500, 1000, 2000, 4000,
+];
+
 /**
  * Pre-populate the override cache from the gateway (async).
  *
@@ -148,26 +165,66 @@ async function fetchOverridesFromGateway(): Promise<Record<string, boolean>> {
  * uses the gateway. In local mode, falls back to the local file when
  * the gateway is unreachable.
  *
- * On failure, the cache is left unset so subsequent sync calls return an
- * empty override map (registry defaults only).
+ * Retries the gateway IPC fetch on empty/failed results — the gateway
+ * may not have bound its IPC socket yet when the daemon races ahead at
+ * startup. After exhausting retries, the cache is left unset so
+ * subsequent sync calls return an empty override map (registry defaults
+ * only).
+ *
+ * Pass `retryBackoffsMs: []` to disable retries (used by unit tests that
+ * intentionally simulate an unreachable gateway and want immediate
+ * fallback without waiting through the production schedule).
  *
  * No-ops when the cache is already populated — callers that want to
  * refresh must call `clearFeatureFlagOverridesCache()` first. This lets
  * tests preseed flag state via `_setOverridesForTesting()` without the
  * gateway IPC call clobbering their setup.
  */
-export async function initFeatureFlagOverrides(): Promise<void> {
+export async function initFeatureFlagOverrides(options?: {
+  retryBackoffsMs?: readonly number[];
+}): Promise<void> {
   if (cachedOverridesFromGateway) return;
 
-  const gatewayOverrides = await fetchOverridesFromGateway();
-  if (Object.keys(gatewayOverrides).length > 0) {
-    cachedOverrides = gatewayOverrides;
-    cachedOverridesFromGateway = true;
-    return;
+  const backoffs = options?.retryBackoffsMs ?? DEFAULT_INIT_RETRY_BACKOFFS_MS;
+
+  // First attempt has no preceding delay; subsequent attempts wait per the
+  // backoff schedule. An empty result is treated as a transient miss
+  // (gateway not yet bound) and triggers a retry — a healthy gateway
+  // always returns at least the registry-merged flags.
+  for (let attempt = 0; attempt <= backoffs.length; attempt++) {
+    if (attempt > 0) {
+      const delay = backoffs[attempt - 1]!;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      // Re-check after the wait: a concurrent caller (e.g. a test using
+      // `_setOverridesForTesting`) may have populated the cache while we
+      // were sleeping. Bail out so we don't clobber their setup.
+      if (cachedOverridesFromGateway) return;
+    }
+
+    const gatewayOverrides = await fetchOverridesFromGateway();
+    if (Object.keys(gatewayOverrides).length > 0) {
+      cachedOverrides = gatewayOverrides;
+      cachedOverridesFromGateway = true;
+      if (attempt > 0) {
+        log.info(
+          { attempt: attempt + 1 },
+          "Feature flag overrides loaded from gateway after retry",
+        );
+      }
+      return;
+    }
   }
 
-  // Gateway returned empty or failed — leave cache unset so loadOverrides()
-  // returns an empty map on subsequent sync reads.
+  // Exhausted retries — leave cache unset so loadOverrides() returns an
+  // empty map on subsequent sync reads. Flag checks fall through to the
+  // registry default (`defaultEnabled`), which biases toward off for
+  // newer assistant-scope flags.
+  if (backoffs.length > 0) {
+    log.warn(
+      { attempts: backoffs.length + 1 },
+      "Feature flag overrides empty after all retries; falling back to registry defaults",
+    );
+  }
 }
 
 /**

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

@@ -6,6 +6,12 @@ metadata:
   emoji: "🔗"
   vellum:
     display-name: "ACP"
+    activation-hints:
+      - "User wants to delegate a coding task to Claude Code, Codex, or another ACP agent"
+      - "User wants to spawn an external coding agent that runs autonomously and streams results back"
+      - "User mentions ACP, claude-agent-acp, codex-acp, or running multiple coding agents in parallel"
+    avoid-when:
+      - "Task is small enough to do inline with the assistant's own tools — no need for an external agent"
 ---
 
 ACP agent orchestration - spawn external coding agents (Claude Code, Codex, etc.) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.

package/src/config/bundled-skills/acp/TOOLS.json

@@ -20,10 +20,6 @@
           "cwd": {
             "type": "string",
             "description": "Working directory for the agent. This determines where the agent runs and where its session is stored. Set this to the project/repo root the user wants the agent to work in. Defaults to current conversation's working directory."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief explanation of why this tool is being called"
           }
         },
         "required": ["task"]
@@ -42,10 +38,6 @@
           "acp_session_id": {
             "type": "string",
             "description": "Optional ACP session ID to query. If omitted, returns all ACP sessions."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief explanation of why this tool is being called"
           }
         },
         "required": []
@@ -64,10 +56,6 @@
           "acp_session_id": {
             "type": "string",
             "description": "The ID of the ACP session to abort."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief explanation of why this tool is being called"
           }
         },
         "required": ["acp_session_id"]
@@ -90,10 +78,6 @@
           "instruction": {
             "type": "string",
             "description": "The new instruction that replaces the in-flight prompt."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief explanation of why this tool is being called"
           }
         },
         "required": ["acp_session_id", "instruction"]
@@ -108,12 +92,7 @@
       "risk": "low",
       "input_schema": {
         "type": "object",
-        "properties": {
-          "activity": {
-            "type": "string",
-            "description": "Brief explanation of why this tool is being called"
-          }
-        },
+        "properties": {},
         "required": []
       },
       "executor": "tools/acp-list-agents.ts",

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

@@ -1,6 +1,6 @@
 ---
 name: app-builder
-description: Build interactive apps, dashboards, calculators, games, trackers, tools, landing pages, and data visualizations with HTML/CSS/JS
+description: Build interactive apps, dashboards, calculators, games, trackers, tools, landing pages, and data visualizations with Preact/TypeScript/CSS
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🏗️"
@@ -30,11 +30,11 @@ Apps live under `{workspaceDir}/data/apps/`. Each app has a slug-based layout:
 {workspaceDir}/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
+    index.html         # Legacy single-file entry point (do not create for new apps)
+    pages/             # Legacy additional pages (do not create for new apps)
     records/           # Data records (one JSON file per record)
-    src/               # Source files (multifile TSX apps, formatVersion: 2)
-    dist/              # Compiled output (multifile TSX apps)
+    src/               # Source files (multi-file TSX apps, formatVersion: 2)
+    dist/              # Compiled output (multi-file TSX apps)
   <slug>.preview       # Preview image (auto-generated)
 ```
 
@@ -42,7 +42,7 @@ Apps live under `{workspaceDir}/data/apps/`. Each app has a slug-based layout:
 
 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/`).
+**Important:** Legacy `htmlDefinition` and `pages` content is NOT stored in the metadata JSON — it lives as separate files inside the app directory (`index.html` and `pages/`). Do not create new single-file apps or new `pages/` directories.
 
 ### Records
 
@@ -52,9 +52,9 @@ Each record is a JSON file at `<slug>/records/<uuid>.json` with shape:
 { "id": "<uuid>", "appId": "<app-id>", "data": { ... }, "createdAt": "...", "updatedAt": "..." }
 ```
 
-### Multifile TSX Apps
+### Multi-file 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.
+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.
 
 ## Workflow
 
@@ -69,16 +69,7 @@ For `formatVersion: 2` apps, source files live under `src/` and compiled output
 
 **Make creative decisions on behalf of the user.** They want to be delighted, not consulted. Pick the accent color. Choose between a dark moody aesthetic or a light airy one. Decide if cards should have glassmorphism or layered shadows. Add a background pattern or gradient. These are YOUR decisions as the designer.
 
-<!-- feature:app-builder-multifile:start -->
-
-**Prefer multi-file TSX projects** for any non-trivial app. They give you component reuse, TypeScript safety, and cleaner organization. Fall back to single-file HTML only for the simplest one-off pages.
-
-<!-- feature:app-builder-multifile:end -->
-<!-- feature:app-builder-multifile:alt -->
-
-**Always build single-file HTML apps.** Write a complete, self-contained HTML document with all CSS in `<style>` and all JavaScript in `<script>`. Do not use multi-file projects or TSX.
-
-<!-- feature:app-builder-multifile:alt:end -->
+**Build all new apps as multi-file TSX projects.** They give you component reuse, TypeScript safety, and cleaner organization.
 
 **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.
 
@@ -124,11 +115,9 @@ Example schema for a project tracker:
 
 Apps are rendered inside a sandboxed WebView on macOS.
 
-<!-- feature:app-builder-multifile:start -->
-
 #### Multi-file TSX projects
 
-Build apps as multi-file TSX projects. You get component reuse, TypeScript type-checking, and clean file organization. The build system uses esbuild to bundle everything automatically.
+Build apps as multi-file TSX projects. You get component reuse, TypeScript type-checking, and clean file organization. The build system uses esbuild to bundle everything automatically. Do not create root-level `index.html` files or `pages/` directories for new apps.
 
 **Project structure:**
 
@@ -190,7 +179,7 @@ useEffect(() => {
 }, []);
 ```
 
-**File workflow:** Use `file_write` for each source file. After writing all files, call `app_refresh` once to compile and refresh the UI.
+**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.
 
 **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.
 
@@ -262,23 +251,6 @@ app_refresh(app_id)
 - No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
 - Design responsively. Apps render at fluid, user-resizable widths — avoid fixed-pixel layouts
 - The WebView blocks all navigation - links and form `action` attributes won't work
-<!-- feature:app-builder-multifile:end -->
-
-<!-- feature:app-builder-multifile:alt -->
-
-#### Single HTML file
-
-Write a complete, self-contained HTML document.
-
-**Technical constraints (single-file):**
-
-- Single HTML string - no external files, CDNs, or imports
-- All CSS in `<style>` in `<head>`, all JavaScript in `<script>` before `</body>`
-- No external fonts, images, or resources - use system fonts and CSS/SVG for visuals
-- Design responsively. Apps render at fluid, user-resizable widths — avoid fixed-pixel layouts
-- The WebView blocks all navigation - links and form `action` attributes won't work
-
-<!-- feature:app-builder-multifile:alt:end -->
 
 #### Injected design system
 
@@ -352,88 +324,21 @@ For handler conventions, examples, key rules, and frontend usage patterns, see *
 
 `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 -->
-
-#### JavaScript patterns
-
-Initialize apps with clean state management:
-
-```javascript
-document.addEventListener("DOMContentLoaded", async () => {
-  await loadRecords();
-});
-
-let allRecords = [];
-
-async function loadRecords() {
-  try {
-    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);
-  }
-}
-
-function render() {
-  // Re-render UI from allRecords
-}
-```
-
-**HTML escaping:** Always escape user-controlled data before inserting into the DOM via `innerHTML`:
-
-```javascript
-function esc(s) {
-  const d = document.createElement("div");
-  d.textContent = String(s);
-  return d.innerHTML;
-}
-```
-
-### 4. Single-Page App Views
-
-Apps run inside a sandboxed WebView that blocks all navigation. All apps are effectively single-page. When an app needs multiple views, use JavaScript to swap content:
-
-```javascript
-function showView(name) {
-  document.querySelectorAll(".view").forEach((v) => (v.hidden = true));
-  document.getElementById("view-" + name).hidden = false;
-  document
-    .querySelectorAll(".nav-link")
-    .forEach((btn) => btn.classList.remove("active"));
-  document
-    .querySelector(`[onclick="showView('${name}')"]`)
-    ?.classList.add("active");
-}
-```
-
-<!-- feature:app-builder-multifile:alt:end -->
-
-<!-- feature:app-builder-multifile:start -->
 ### 4. Create and Open the App
-<!-- feature:app-builder-multifile:end -->
-<!-- feature:app-builder-multifile:alt -->
-### 5. Create and Open the App
-<!-- feature:app-builder-multifile:alt:end -->
 
 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 `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)
 
+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`.
+
 The app is NOT opened in a workspace panel automatically - users open it via the 'Open App' button on the inline card.
 
-<!-- feature:app-builder-multifile:start -->
 ### 5. Handle Iteration
-<!-- feature:app-builder-multifile:end -->
-<!-- feature:app-builder-multifile:alt -->
-### 6. Handle Iteration
-<!-- feature:app-builder-multifile:alt:end -->
 
 When the user requests changes, prefer **`file_edit`** over rewriting the entire file.
 
@@ -444,7 +349,7 @@ When the user requests changes, prefer **`file_edit`** over rewriting the entire
 
 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.
+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.
 
 ## Interaction Standards