@vellumai/assistant 0.7.2 → 0.8.0

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

@@ -3,7 +3,7 @@ import { createServer, type Server } from "node:http";
 import type { Command } from "commander";
 
 import { getIsContainerized } from "../../../config/env-registry.js";
-import { orchestrateOAuthConnect } from "../../../oauth/connect-orchestrator.js";
+import { cliIpcCall } from "../../../ipc/cli-client.js";
 import {
   getAppByProviderAndClientId,
   getMostRecentAppByProvider,
@@ -69,6 +69,39 @@ function startManagedRedirectServer(provider: string): Promise<{
   });
 }
 
+// ---------------------------------------------------------------------------
+// IPC polling helpers
+// ---------------------------------------------------------------------------
+
+type OAuthConnectStatusResponse =
+  | { status: "pending"; service: string }
+  | { status: "complete"; service: string; account_info?: string; granted_scopes?: string[] }
+  | { status: "error"; service: string; error?: string };
+
+async function pollOAuthConnectStatus(
+  state: string,
+  opts: { intervalMs: number; timeoutMs: number },
+): Promise<OAuthConnectStatusResponse> {
+  const deadline = Date.now() + opts.timeoutMs;
+  while (Date.now() < deadline) {
+    const r = await cliIpcCall<OAuthConnectStatusResponse>(
+      "internal_oauth_connect_status",
+      { pathParams: { state } },
+    );
+    if (r.ok && r.result) {
+      const { status } = r.result;
+      if (status === "complete" || status === "error") {
+        return r.result;
+      }
+    }
+    if (!r.ok && r.statusCode !== undefined) {
+      return { status: "error", service: "?", error: r.error ?? "assistant error during OAuth status poll" };
+    }
+    await new Promise<void>((res) => setTimeout(res, opts.intervalMs));
+  }
+  return { status: "error", service: "?", error: "Timed out waiting for OAuth callback" };
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -392,53 +425,104 @@ Examples:
               }
             }
 
-            // e. Call the orchestrator
-            const result = await orchestrateOAuthConnect({
-              service: provider,
-              clientId,
-              clientSecret,
-              callbackTransport: opts.callbackTransport,
-              isInteractive: opts.browser !== false,
-              openUrl: opts.browser !== false ? openInHostBrowser : undefined,
-              ...(opts.scopes ? { requestedScopes: opts.scopes } : {}),
-            });
-
-            // f. Handle results
-            if (!result.success) {
-              writeError(result.error ?? "OAuth connect failed");
-              return;
-            }
+            // e. Try daemon-orchestrated path first (fixes heap-split for gateway transport).
+            const startResult = await cliIpcCall<{ auth_url: string; state: string }>(
+              "internal_oauth_connect_start",
+              {
+                body: {
+                  service: provider,
+                  clientId,
+                  ...(clientSecret !== undefined ? { clientSecret } : {}),
+                  callbackTransport: opts.callbackTransport,
+                  ...(opts.scopes ? { requestedScopes: opts.scopes } : {}),
+                },
+              },
+            );
+
+            if (startResult.ok && startResult.result?.auth_url) {
+              const { auth_url, state } = startResult.result;
+
+              if (opts.browser !== false) {
+                await openInHostBrowser(auth_url);
 
-            if (result.deferred) {
-              if (jsonMode) {
-                writeOutput(cmd, {
-                  ok: true,
-                  deferred: true,
-                  // Wire key stays `authUrl` for backward compatibility with
-                  // existing CLI script consumers; the internal field on
-                  // `result` is `authorizeUrl`.
-                  authUrl: result.authorizeUrl,
-                  service: result.service,
+                if (!jsonMode) {
+                  log.info("Waiting for authorization in browser... (press Ctrl+C to cancel)");
+                }
+                const final = await pollOAuthConnectStatus(state, {
+                  intervalMs: 2000,
+                  timeoutMs: 5 * 60 * 1000, // match LOOPBACK_TIMEOUT_MS in oauth2.ts (5 min)
                 });
+
+                if (final.status === "complete") {
+                  if (jsonMode) {
+                    writeOutput(cmd, {
+                      ok: true,
+                      grantedScopes: final.granted_scopes ?? [],
+                      accountInfo: final.account_info,
+                    });
+                  } else {
+                    process.stdout.write(
+                      `Connected to ${provider}${final.account_info ? ` as ${final.account_info}` : ""}\n`,
+                    );
+                  }
+                  return;
+                }
+
+                if (final.status === "error") {
+                  // Includes the timeout sentinel emitted by pollOAuthConnectStatus.
+                  writeError(final.error ?? "OAuth connect failed");
+                  return;
+                }
+
+                // Defensive: pollOAuthConnectStatus should never return pending,
+                // but TS narrowing requires us to handle it.
+                writeError("OAuth connect ended in an unexpected pending state");
+                return;
               } else {
-                process.stdout.write(
-                  `\nAuthorize with ${provider}:\n\n${result.authorizeUrl}\n\nThe connection will complete automatically once you authorize.\n`,
-                );
+                // --no-browser: return the URL immediately, matching existing deferred behavior.
+                if (jsonMode) {
+                  writeOutput(cmd, {
+                    ok: true,
+                    deferred: true,
+                    authUrl: auth_url,
+                    state,
+                    service: provider,
+                  });
+                } else {
+                  process.stdout.write(
+                    `\nAuthorize with ${provider}:\n\n${auth_url}\n\nThe connection will complete automatically once you authorize.\n`,
+                  );
+                }
+                return;
               }
+            }
+
+            // ok:true but no auth_url means a malformed daemon response — surface an error rather
+            // than falling back to in-process (which would re-introduce the heap-split bug for
+            // gateway transport).
+            if (startResult.ok && !startResult.result?.auth_url) {
+              writeError("assistant returned unexpected response for OAuth connect start");
               return;
             }
 
-            // Interactive mode completed
-            if (jsonMode) {
-              writeOutput(cmd, {
-                ok: true,
-                grantedScopes: result.grantedScopes,
-                accountInfo: result.accountInfo,
-              });
-            } else {
-              const msg = `Connected to ${provider}${result.accountInfo ? ` as ${result.accountInfo}` : ""}`;
-              process.stdout.write(msg + "\n");
+            // If the daemon was reachable but returned an error, surface it rather than
+            // falling back to in-process (which would re-introduce the heap-split bug for
+            // gateway transport).
+            if (!startResult.ok && startResult.statusCode !== undefined) {
+              writeError(startResult.error ?? "OAuth connect failed (assistant error)");
+              return;
             }
+
+            // IPC unavailable: the assistant must be running for OAuth connect. The
+            // gateway-routed callback lands in the assistant's process, and any tokens
+            // acquired need the assistant to store and use them — so an unreachable
+            // assistant is a fatal precondition. Surface a clear error and exit 1.
+            writeError(
+              startResult.error
+                ? `Could not reach the assistant: ${startResult.error}. Is the assistant running?`
+                : "Could not reach the assistant. Is the assistant running?",
+            );
+            return;
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);

package/src/cli/commands/platform/__tests__/callback-routes-list.test.ts

@@ -10,7 +10,6 @@ let mockResolvePlatformCallbackRegistrationContext: () => Promise<
   isPlatform: false,
   platformBaseUrl: "",
   assistantId: "",
-  hasInternalApiKey: false,
   hasAssistantApiKey: false,
   authHeader: null,
   enabled: false,
@@ -93,7 +92,6 @@ function connectedContext(
     isPlatform: false,
     platformBaseUrl: "https://dev-platform.vellum.ai",
     assistantId: "019d6d4f-6dbd-779f-91d3-cb273b9429a5",
-    hasInternalApiKey: false,
     hasAssistantApiKey: true,
     authHeader: "Api-Key vak_test123",
     enabled: false,
@@ -181,7 +179,6 @@ describe("assistant platform callback-routes list", () => {
       isPlatform: false,
       platformBaseUrl: "",
       assistantId: "",
-      hasInternalApiKey: false,
       hasAssistantApiKey: false,
       authHeader: null,
       enabled: false,

package/src/cli/commands/platform/__tests__/connect.test.ts

@@ -32,6 +32,13 @@ mock.module("../../../../security/secure-keys.js", () => ({
   onCesClientChanged: () => ({ unsubscribe: () => {} }),
   setCesReconnect: () => {},
   getActiveBackendName: () => "file",
+  getActiveBackendInfoAsync: async () => ({
+    backend: "encrypted-store",
+    storePath: "/tmp/keys.enc",
+    storeKeyPath: "/tmp/store.key",
+    storeExists: false,
+    storeKeyExists: false,
+  }),
   _resetBackend: () => {},
 }));
 
@@ -45,7 +52,6 @@ mock.module("../../../../inbound/platform-callback-registration.js", () => ({
     isPlatform: false,
     platformBaseUrl: "",
     assistantId: "",
-    hasInternalApiKey: false,
     hasAssistantApiKey: false,
     authHeader: null,
     enabled: false,

package/src/cli/commands/platform/__tests__/disconnect.test.ts

@@ -39,7 +39,6 @@ mock.module("../../../../inbound/platform-callback-registration.js", () => ({
     isPlatform: false,
     platformBaseUrl: "",
     assistantId: "",
-    hasInternalApiKey: false,
     hasAssistantApiKey: false,
     authHeader: null,
     enabled: false,
@@ -64,6 +63,13 @@ mock.module("../../../../security/secure-keys.js", () => ({
   onCesClientChanged: () => ({ unsubscribe: () => {} }),
   setCesReconnect: () => {},
   getActiveBackendName: () => "file",
+  getActiveBackendInfoAsync: async () => ({
+    backend: "encrypted-store",
+    storePath: "/tmp/keys.enc",
+    storeKeyPath: "/tmp/store.key",
+    storeExists: false,
+    storeKeyExists: false,
+  }),
   _resetBackend: () => {},
 }));
 

package/src/cli/commands/platform/__tests__/status.test.ts

@@ -14,12 +14,16 @@ let mockResolvePlatformCallbackRegistrationContext: () => Promise<
   isPlatform: false,
   platformBaseUrl: "",
   assistantId: "",
-  hasInternalApiKey: false,
   hasAssistantApiKey: false,
   authHeader: null,
   enabled: false,
 });
 
+let mockIpcGetVelayStatus: () => Promise<{
+  connected: boolean;
+  publicUrl: string | null;
+} | null> = async () => null;
+
 // ---------------------------------------------------------------------------
 // Mocks
 // ---------------------------------------------------------------------------
@@ -47,6 +51,13 @@ mock.module("../../../../security/secure-keys.js", () => ({
   onCesClientChanged: () => ({ unsubscribe: () => {} }),
   setCesReconnect: () => {},
   getActiveBackendName: () => "file",
+  getActiveBackendInfoAsync: async () => ({
+    backend: "encrypted-store",
+    storePath: "/tmp/keys.enc",
+    storeKeyPath: "/tmp/store.key",
+    storeExists: false,
+    storeKeyExists: false,
+  }),
   _resetBackend: () => {},
 }));
 
@@ -100,6 +111,15 @@ mock.module("../../../../config/loader.js", () => ({
   mergeDefaultWorkspaceConfig: () => {},
 }));
 
+mock.module("../../../../ipc/gateway-client.js", () => ({
+  ipcGetVelayStatus: () => mockIpcGetVelayStatus(),
+  ipcCall: async () => undefined,
+  ipcCallPersistent: async () => undefined,
+  resetPersistentClient: () => {},
+  ipcGetFeatureFlags: async () => ({}),
+  ipcClassifyRisk: async () => undefined,
+}));
+
 // ---------------------------------------------------------------------------
 // Import module under test (after mocks are registered)
 // ---------------------------------------------------------------------------
@@ -158,11 +178,11 @@ describe("assistant platform status", () => {
       isPlatform: false,
       platformBaseUrl: "",
       assistantId: "",
-      hasInternalApiKey: false,
       hasAssistantApiKey: false,
       authHeader: null,
       enabled: false,
     });
+    mockIpcGetVelayStatus = async () => null;
     process.exitCode = 0;
   });
 
@@ -179,9 +199,8 @@ describe("assistant platform status", () => {
       isPlatform: true,
       platformBaseUrl: "https://platform.vellum.ai",
       assistantId: "asst-abc-123",
-      hasInternalApiKey: true,
       hasAssistantApiKey: true,
-      authHeader: "Bearer internal-key",
+      authHeader: "Api-Key assistant-key",
       enabled: true,
     });
 
@@ -209,12 +228,91 @@ describe("assistant platform status", () => {
     expect(parsed.isPlatform).toBe(true);
     expect(parsed.baseUrl).toBe("https://platform.vellum.ai");
     expect(parsed.assistantId).toBe("asst-abc-123");
-    expect(parsed.hasInternalApiKey).toBe(true);
     expect(parsed.hasAssistantApiKey).toBe(true);
     expect(parsed.hasWebhookSecret).toBe(true);
     expect(parsed.available).toBe(true);
     expect(parsed.organizationId).toBe("org-456");
     expect(parsed.userId).toBe("user-789");
+    // velayTunnel is null when gateway is unreachable
+    expect(parsed.velayTunnel).toBeNull();
+  });
+
+  test("velayTunnel connected with publicUrl is returned when gateway is live", async () => {
+    /**
+     * When the gateway is running and the Velay tunnel is connected, the
+     * status command includes velayTunnel.connected=true and the public URL.
+     */
+
+    // GIVEN a connected Velay tunnel reported by the gateway IPC
+    mockIpcGetVelayStatus = async () => ({
+      connected: true,
+      publicUrl: "https://abc123.vellum.ai",
+    });
+
+    // WHEN the status command is run with --json
+    const { exitCode, stdout } = await runCommand([
+      "platform",
+      "status",
+      "--json",
+    ]);
+
+    // THEN the command succeeds
+    expect(exitCode).toBe(0);
+
+    // AND velayTunnel reflects the live connection
+    const parsed = JSON.parse(stdout);
+    expect(parsed.velayTunnel).toEqual({
+      connected: true,
+      publicUrl: "https://abc123.vellum.ai",
+    });
+  });
+
+  test("velayTunnel disconnected when gateway reports no active connection", async () => {
+    /**
+     * When the gateway is running but Velay is not connected (e.g.
+     * reconnecting after disconnect), velayTunnel.connected is false.
+     */
+
+    // GIVEN a disconnected Velay tunnel
+    mockIpcGetVelayStatus = async () => ({
+      connected: false,
+      publicUrl: null,
+    });
+
+    // WHEN the status command is run with --json
+    const { exitCode, stdout } = await runCommand([
+      "platform",
+      "status",
+      "--json",
+    ]);
+
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.velayTunnel).toEqual({ connected: false, publicUrl: null });
+  });
+
+  test("velayTunnel is null when gateway IPC is unreachable", async () => {
+    /**
+     * When the gateway IPC socket is not available (assistant not running),
+     * velayTunnel is null rather than causing the status command to fail.
+     */
+
+    // GIVEN the gateway IPC throws
+    mockIpcGetVelayStatus = async () => {
+      throw new Error("ENOENT");
+    };
+
+    // WHEN the status command is run with --json
+    const { exitCode, stdout } = await runCommand([
+      "platform",
+      "status",
+      "--json",
+    ]);
+
+    // THEN the command still succeeds (graceful fallback)
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.velayTunnel).toBeNull();
   });
 
   test("plain text mode does not emit JSON to stdout", async () => {
@@ -229,7 +327,6 @@ describe("assistant platform status", () => {
       isPlatform: false,
       platformBaseUrl: "",
       assistantId: "",
-      hasInternalApiKey: false,
       hasAssistantApiKey: false,
       authHeader: null,
       enabled: false,

package/src/cli/commands/platform/index.ts

@@ -4,6 +4,7 @@ import {
   registerCallbackRoute,
   resolvePlatformCallbackRegistrationContext,
 } from "../../../inbound/platform-callback-registration.js";
+import { ipcGetVelayStatus } from "../../../ipc/gateway-client.js";
 import { credentialKey } from "../../../security/credential-key.js";
 import { getSecureKeyAsync } from "../../../security/secure-keys.js";
 import { log } from "../../logger.js";
@@ -62,14 +63,14 @@ Fields:
   isPlatform          Whether IS_PLATFORM is set (boolean)
   baseUrl             VELLUM_PLATFORM_URL — the platform gateway base URL
   assistantId         This assistant's platform UUID
-  hasInternalApiKey   Whether PLATFORM_INTERNAL_API_KEY is set (boolean,
-                      value not disclosed)
   hasAssistantApiKey  Whether a stored assistant API key is available
   hasWebhookSecret    Whether a stored webhook secret is available (needed
                       for email and other inbound webhook channels)
   available           Whether callback registration prerequisites are satisfied
   organizationId      The platform organization ID (from stored credentials)
   userId              The platform user ID (from stored credentials)
+  velayTunnel         Live Velay tunnel status from the gateway IPC socket
+                      (null when the gateway is not running)
 
 Examples:
   $ assistant platform status
@@ -77,7 +78,10 @@ Examples:
     )
     .action(async (_opts: Record<string, unknown>, cmd: Command) => {
       try {
-        const context = await resolvePlatformCallbackRegistrationContext();
+        const [context, velayTunnel] = await Promise.all([
+          resolvePlatformCallbackRegistrationContext(),
+          ipcGetVelayStatus().catch(() => null),
+        ]);
 
         const organizationId =
           (
@@ -106,12 +110,12 @@ Examples:
           isPlatform: context.isPlatform,
           baseUrl: context.platformBaseUrl,
           assistantId: context.assistantId,
-          hasInternalApiKey: context.hasInternalApiKey,
           hasAssistantApiKey: context.hasAssistantApiKey,
           hasWebhookSecret,
           available: context.enabled,
           organizationId: organizationId || null,
           userId: userId || null,
+          velayTunnel,
         };
 
         if (shouldOutputJson(cmd)) {
@@ -120,9 +124,6 @@ Examples:
           log.info(`Platform: ${result.isPlatform}`);
           log.info(`Base URL: ${result.baseUrl || "(not set)"}`);
           log.info(`Assistant ID: ${result.assistantId || "(not set)"}`);
-          log.info(
-            `Internal API key: ${result.hasInternalApiKey ? "set" : "not set"}`,
-          );
           log.info(
             `Assistant API key: ${result.hasAssistantApiKey ? "set" : "not set"}`,
           );
@@ -134,6 +135,14 @@ Examples:
           );
           log.info(`Organization ID: ${organizationId || "(not set)"}`);
           log.info(`User ID: ${userId || "(not set)"}`);
+          if (result.velayTunnel !== null) {
+            const tunnelState = result.velayTunnel.connected
+              ? `connected${result.velayTunnel.publicUrl ? ` (${result.velayTunnel.publicUrl})` : ""}`
+              : "disconnected";
+            log.info(`Velay tunnel: ${tunnelState}`);
+          } else {
+            log.info(`Velay tunnel: (gateway not running)`);
+          }
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/src/cli/commands/status.ts

@@ -0,0 +1,57 @@
+import type { Command } from "commander";
+
+import { cliIpcCall } from "../../ipc/cli-client.js";
+import { getWorkspaceDirDisplay } from "../../util/platform.js";
+import { log } from "../logger.js";
+
+interface HealthResponse {
+  version: string;
+  memory: { currentMb: number; maxMb: number };
+  disk: { freeMb: number; totalMb: number } | null;
+}
+
+function fmtMb(mb: number): string {
+  if (mb >= 1024) return `${(mb / 1024).toFixed(1)} GB`;
+  return `${Math.round(mb)} MB`;
+}
+
+export function registerStatusCommand(program: Command): void {
+  program
+    .command("status")
+    .description("Show assistant version, workspace, and runtime health")
+    .action(async () => {
+      const result = await cliIpcCall<HealthResponse>("health");
+
+      if (!result.ok || !result.result) {
+        log.error(
+          result.error ??
+            "Assistant not running — could not connect to IPC socket.",
+        );
+        process.exit(1);
+      }
+
+      const h = result.result;
+      const workspace = getWorkspaceDirDisplay();
+
+      const rows: [string, string][] = [
+        ["Version", h.version],
+        ["Workspace", workspace],
+        ["", ""],
+        ["Memory", `${fmtMb(h.memory.currentMb)} / ${fmtMb(h.memory.maxMb)}`],
+        ...(h.disk
+          ? ([["Disk", `${fmtMb(h.disk.freeMb)} free`]] as [string, string][])
+          : []),
+      ];
+
+      const labelWidth = Math.max(
+        ...rows.filter(([l]) => l).map(([l]) => l.length),
+      );
+      for (const [label, value] of rows) {
+        if (!label) {
+          log.info("");
+          continue;
+        }
+        log.info(`${label.padEnd(labelWidth)}  ${value}`);
+      }
+    });
+}

package/src/cli/program.ts

@@ -41,6 +41,7 @@ import { registerPlatformCommand } from "./commands/platform/index.js";
 import { registerRoutesCommand } from "./commands/routes.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 { registerTrustCommand } from "./commands/trust.js";
@@ -56,7 +57,7 @@ import { log } from "./logger.js";
  * the gateway so flag-gated commands are registered correctly.
  */
 export async function buildCliProgram(): Promise<Command> {
-  await initFeatureFlagOverrides();
+  await initFeatureFlagOverrides({ retryBackoffsMs: [], callTimeoutMs: 200 });
   const program = new Command();
 
   program
@@ -110,6 +111,7 @@ Examples:
   registerPlatformCommand(program);
   registerRoutesCommand(program);
   registerSequenceCommand(program);
+  registerStatusCommand(program);
   registerSkillsCommand(program);
   registerSttCommand(program);
   registerTaskCommand(program);
@@ -126,7 +128,7 @@ 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"]);
+  const workspaceExemptCommands = new Set(["completions", "status"]);
   program.hook("preAction", (_thisCommand, actionCommand) => {
     if (workspaceExemptCommands.has(actionCommand.name())) {
       return;

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

@@ -135,9 +135,11 @@ let cachedOverridesFromGateway = false;
  * timeout, parse error). No auth needed — the IPC socket is
  * access-controlled by file-system permissions on the shared volume.
  */
-async function fetchOverridesFromGateway(): Promise<Record<string, boolean>> {
+async function fetchOverridesFromGateway(
+  timeoutMs?: number,
+): Promise<Record<string, boolean>> {
   try {
-    return await ipcGetFeatureFlags();
+    return await ipcGetFeatureFlags(timeoutMs);
   } catch {
     return {};
   }
@@ -182,10 +184,18 @@ const DEFAULT_INIT_RETRY_BACKOFFS_MS: readonly number[] = [
  */
 export async function initFeatureFlagOverrides(options?: {
   retryBackoffsMs?: readonly number[];
+  /**
+   * Timeout (ms) for each IPC call to the gateway. When omitted the
+   * transport defaults apply (3 s connect + 5 s call). CLI callers should
+   * pass a small value (e.g. 200) so a slow/absent gateway fails fast
+   * instead of blocking startup.
+   */
+  callTimeoutMs?: number;
 }): Promise<void> {
   if (cachedOverridesFromGateway) return;
 
   const backoffs = options?.retryBackoffsMs ?? DEFAULT_INIT_RETRY_BACKOFFS_MS;
+  const callTimeoutMs = options?.callTimeoutMs;
 
   // First attempt has no preceding delay; subsequent attempts wait per the
   // backoff schedule. An empty result is treated as a transient miss
@@ -201,7 +211,7 @@ export async function initFeatureFlagOverrides(options?: {
       if (cachedOverridesFromGateway) return;
     }
 
-    const gatewayOverrides = await fetchOverridesFromGateway();
+    const gatewayOverrides = await fetchOverridesFromGateway(callTimeoutMs);
     if (Object.keys(gatewayOverrides).length > 0) {
       cachedOverrides = gatewayOverrides;
       cachedOverridesFromGateway = true;

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

@@ -6,8 +6,6 @@ metadata:
   emoji: "🏗️"
   vellum:
     display-name: "App Builder"
-    includes:
-      - "frontend-design"
     activation-hints:
       - "User asks to build an app, landing page, website, dashboard, tool, calculator, game, tracker, or interactive page"
       - "User asks to visualize data or says 'let's visualize this' — use the app sandbox to build interactive visualizations"
@@ -20,7 +18,7 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 **Your default behavior:** Build immediately. The user types "build me a habit tracker" and you deliver a complete, polished app with a domain-matched color palette, atmospheric background, and thoughtful interactions. Don't ask what colors they want. Don't show wireframes. Just build something stunning and let them refine from there.
 
-**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.
+**Design quality is delegated to the `frontend-design` skill, so you must also load/install that before proceeding.** 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