@vellumai/assistant 0.7.1 → 0.7.3

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";
@@ -40,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";
@@ -55,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
@@ -96,6 +98,7 @@ Examples:
     registerDomainCommand(program);
     registerEmailCommand(program);
   }
+  registerGatewayCommand(program);
   registerImageGenerationCommand(program);
   registerInferenceCommand(program);
   registerKeysCommand(program);
@@ -108,6 +111,7 @@ Examples:
   registerPlatformCommand(program);
   registerRoutesCommand(program);
   registerSequenceCommand(program);
+  registerStatusCommand(program);
   registerSkillsCommand(program);
   registerSttCommand(program);
   registerTaskCommand(program);
@@ -124,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

@@ -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
 // ---------------------------------------------------------------------------
@@ -132,14 +135,30 @@ 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 {};
   }
 }
 
+/**
+ * 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 +167,74 @@ 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[];
+  /**
+   * 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 gatewayOverrides = await fetchOverridesFromGateway();
-  if (Object.keys(gatewayOverrides).length > 0) {
-    cachedOverrides = gatewayOverrides;
-    cachedOverridesFromGateway = true;
-    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
+  // (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(callTimeoutMs);
+    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
 

package/src/config/bundled-skills/app-builder/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "app_create",
-      "description": "Create a persistent app with a name, optional description, JSON schema, and HTML definition.",
+      "description": "Create a persistent multi-file TSX app scaffold with a name, optional description, and JSON schema. Write source files under src/ with file tools, then call app_refresh.",
       "category": "apps",
       "risk": "low",
       "input_schema": {
@@ -21,17 +21,6 @@
             "type": "string",
             "description": "JSON schema defining the app data structure"
           },
-          "html": {
-            "type": "string",
-            "description": "Optional HTML definition for the main index.html page. If omitted, a minimal scaffold is created and you can write index.html later via file_write."
-          },
-          "pages": {
-            "type": "object",
-            "description": "Optional additional pages as a mapping of filename to HTML content (e.g. {\"settings.html\": \"<html>...</html>\"}). Navigate between pages with <a href=\"settings.html\">. Do not include index.html here \u2014 use the html parameter instead.",
-            "additionalProperties": {
-              "type": "string"
-            }
-          },
           "auto_open": {
             "type": "boolean",
             "description": "When true (default), an inline preview card is shown in chat after creation. The app is NOT automatically opened in a workspace panel \u2014 users can open it explicitly via the 'Open App' button on the inline card."
@@ -78,10 +67,6 @@
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: add coin flip app', 'fix: correct button alignment'). Used as the version history entry."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["name"]
@@ -104,10 +89,6 @@
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'chore: delete unused app'). Used as the version history entry."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["app_id"]
@@ -130,10 +111,6 @@
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: add dark mode toggle', 'fix: form validation'). Used as the version history entry."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["app_id"]
@@ -160,10 +137,6 @@
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: generate app icon'). Used as the version history entry."
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["app_id"]

package/src/config/bundled-skills/app-builder/tools/app-create.ts

@@ -1,5 +1,3 @@
-import { isAssistantFeatureFlagEnabled } from "../../../../config/assistant-feature-flags.js";
-import { getConfig } from "../../../../config/loader.js";
 import { setAppCommitMessage } from "../../../../memory/app-git-service.js";
 import * as appStore from "../../../../memory/app-store.js";
 import type { AppCreateInput } from "../../../../tools/apps/executors.js";
@@ -16,13 +14,6 @@ export async function run(
   if (typeof input.change_summary === "string" && input.change_summary.trim()) {
     setAppCommitMessage(context.conversationId, input.change_summary.trim());
   }
-  const multifileEnabled = isAssistantFeatureFlagEnabled(
-    "app-builder-multifile",
-    getConfig(),
-  );
-  const createInput: AppCreateInput = {
-    ...(input as unknown as AppCreateInput),
-    featureFlags: { multifileEnabled },
-  };
+  const createInput: AppCreateInput = input as unknown as AppCreateInput;
   return executeAppCreate(createInput, appStore, context.proxyToolResolver);
 }

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

@@ -0,0 +1,75 @@
+---
+name: app-control
+description: Drive a specific named macOS app via raw input bypassing the Accessibility tree
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "🎯"
+  vellum:
+    display-name: "App Control"
+    feature-flag: "app-control"
+    activation-hints:
+      - "User explicitly directs the assistant to drive a specific named app via raw input (emulator, game, OpenGL canvas, custom-rendered Electron app)"
+      - "User says the macOS Accessibility tree is unhelpful or empty for the target app"
+    avoid-when:
+      - "Task can be done via the computer-use skill (general macOS UI navigation)"
+      - "Task can be done via a CLI / API alternative"
+---
+
+This skill exposes the `app_control_*` proxy tools for driving a single
+named macOS application via raw input — keyboard, mouse, screenshot — that
+bypasses the system Accessibility tree. Use it only when explicitly directed
+to a specific app where the AX tree is unhelpful (emulators, games, OpenGL
+canvases, custom-rendered Electron apps). For general macOS UI navigation
+prefer the `computer-use` skill.
+
+Tools in this skill are proxy tools — execution is forwarded to the connected
+macOS client, never handled locally by the assistant.
+
+## Cadence
+
+Take 2-3 actions per turn, then yield with a short narration so the user can
+interject. Do not chain long sequences without surfacing what you are doing.
+
+## Always observe before acting
+
+Call `app_control_observe` before your first input action whenever the screen
+state matters (e.g. you need to know what is on screen, where a UI element is,
+or whether the app is even running). Re-observe after actions that may have
+moved the window or changed visibility.
+
+`observe` waits a short settle delay (default ~200ms) before capturing so the
+target app and the WindowServer can flush pending input and composite a fresh
+frame. If the captured screenshot looks one input behind the latest state
+(common with emulators or other slow-feedback apps), pass a larger
+`settle_ms`. For static UIs where you just want a quick snapshot, pass
+`settle_ms: 0` to skip the wait.
+
+## Input choice
+
+- Prefer `app_control_sequence` over multiple back-to-back `app_control_press`
+  calls when sending an ordered batch of presses (e.g. menu navigation,
+  repeated movement). Sequence runs in a single round-trip — the target app is
+  activated once at the start and the keys are sent serially without any
+  window for keyboard focus to drift to another app between presses. Each step
+  may carry its own `duration_ms` (hold) and `gap_ms` (pause after).
+- Prefer `app_control_combo` over rapid sequential `app_control_press` for
+  simultaneous inputs (e.g. cmd+shift+4). `combo` holds every key at once;
+  sequential presses interleave key-down and key-up events.
+- Use `app_control_type` for literal text into a focused field.
+
+## Coordinate caveat
+
+`app_control_click` and `app_control_drag` use **window-relative** coordinates.
+The window may move or resize between observation and click — if you are
+uncertain whether the window has shifted, re-observe first.
+
+## App targeting
+
+Use bundle IDs (e.g. `com.example.app`) when possible — they are the most
+reliable identifier. Fall back to localized process names if a bundle ID is
+unavailable.
+
+## Ending the session
+
+Call `app_control_stop` when you are done. Do **not** auto-quit the controlled
+app — `stop` only ends the app-control session, leaving the app running.