@appilots/cli 0.4.0 → 0.10.0

package/dist/cli/index.js

@@ -28,12 +28,79 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/index.ts
-var import_commander7 = require("commander");
+var import_commander8 = require("commander");
+
+// src/version.ts
+var CLI_VERSION = "0.10.0";
 
 // src/config/index.ts
 var import_fs = require("fs");
 var import_path = require("path");
 var import_fs2 = require("fs");
+var DEFAULT_SERVER_URL = "http://localhost:4000";
+var KNOWN_CONFIG_KEYS = [
+  "apiKey",
+  "projectId",
+  "serverUrl",
+  "outputDir",
+  "include",
+  "exclude",
+  "autoActivate",
+  "strictScreens",
+  "screenPatterns",
+  "navigationInclude",
+  "navigationExclude",
+  "platform",
+  "manifestPath",
+  "eval"
+];
+var KEY_ALIASES = {
+  apiUrl: "serverUrl",
+  // `@appilots/sdk`'s own name for this. One `.appilotsrc` feeds both
+  // packages, so an integrator who wrote the SDK's key should not be told
+  // it is unrecognized.
+  apiBaseUrl: "serverUrl",
+  apiURL: "serverUrl",
+  baseUrl: "serverUrl",
+  url: "serverUrl",
+  host: "serverUrl",
+  endpoint: "serverUrl",
+  server: "serverUrl",
+  key: "apiKey",
+  token: "apiKey",
+  project: "projectId",
+  sourceDir: "include",
+  srcDir: "include",
+  source: "include",
+  outDir: "outputDir"
+};
+function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const deletion = (previous[j] ?? 0) + 1;
+      const insertion = (current[j - 1] ?? 0) + 1;
+      const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+      current.push(Math.min(deletion, insertion, substitution));
+    }
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function suggestConfigKey(key) {
+  const alias = KEY_ALIASES[key];
+  if (alias) return alias;
+  const lower = key.toLowerCase();
+  let best;
+  for (const known of KNOWN_CONFIG_KEYS) {
+    const distance = editDistance(lower, known.toLowerCase());
+    if (distance <= 2 && (!best || distance < best.distance)) {
+      best = { key: known, distance };
+    }
+  }
+  return best?.key;
+}
 function getEnvOverrides(env = process.env) {
   const clean = (value) => {
     const trimmed = value?.trim();
@@ -45,7 +112,7 @@ function getEnvOverrides(env = process.env) {
     serverUrl: clean(env.APPILOTS_SERVER_URL)
   };
 }
-function loadConfig() {
+function loadConfig(onWarn) {
   const configPath = getConfigPath();
   const env = getEnvOverrides();
   let fileConfig = {};
@@ -53,13 +120,15 @@ function loadConfig() {
     try {
       fileConfig = JSON.parse((0, import_fs.readFileSync)(configPath, "utf-8"));
     } catch (error2) {
-      throw new Error(`Failed to parse .appilotsrc at ${configPath}: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+      throw new Error(
+        `Failed to parse .appilotsrc at ${configPath}: ${error2 instanceof Error ? error2.message : "Unknown error"}`
+      );
     }
   } else if (!env.apiKey) {
     return null;
   }
   const merged = {
-    serverUrl: "http://localhost:4000",
+    serverUrl: DEFAULT_SERVER_URL,
     outputDir: ".appilots",
     autoActivate: true,
     strictScreens: true,
@@ -69,6 +138,12 @@ function loadConfig() {
     ...env.serverUrl ? { serverUrl: env.serverUrl } : {}
   };
   const validation = validateConfig(merged);
+  if (onWarn) {
+    const source = configPath ?? "environment variables";
+    for (const warning of validation.warnings) {
+      onWarn(`${source}: ${warning}`);
+    }
+  }
   if (!validation.valid) {
     const source = configPath ?? "environment variables";
     throw new Error(
@@ -84,7 +159,7 @@ function saveConfig(dir, config) {
   const mergedConfig = {
     apiKey: config.apiKey || existingConfig?.apiKey || "",
     projectId: config.projectId || existingConfig?.projectId || "",
-    serverUrl: config.serverUrl || existingConfig?.serverUrl || "http://localhost:4000",
+    serverUrl: config.serverUrl || existingConfig?.serverUrl || DEFAULT_SERVER_URL,
     outputDir: config.outputDir || existingConfig?.outputDir || ".appilots",
     autoActivate: config.autoActivate !== void 0 ? config.autoActivate : existingConfig?.autoActivate ?? true,
     include: config.include || existingConfig?.include,
@@ -100,7 +175,9 @@ function saveConfig(dir, config) {
   try {
     (0, import_fs.writeFileSync)(configPath, JSON.stringify(mergedConfig, null, 2), "utf-8");
   } catch (error2) {
-    throw new Error(`Failed to write .appilotsrc to ${configPath}: ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+    throw new Error(
+      `Failed to write .appilotsrc to ${configPath}: ${error2 instanceof Error ? error2.message : "Unknown error"}`
+    );
   }
 }
 function getConfigPath() {
@@ -127,14 +204,25 @@ function getConfigPath() {
 }
 function validateConfig(config) {
   const errors = [];
+  const warnings = [];
   if (!config || typeof config !== "object") {
     return {
       valid: false,
-      errors: ["Configuration must be an object"]
+      errors: ["Configuration must be an object"],
+      warnings
     };
   }
+  for (const key of Object.keys(config)) {
+    if (KNOWN_CONFIG_KEYS.includes(key)) continue;
+    const suggestion = suggestConfigKey(key);
+    warnings.push(
+      `unknown key "${key}" \u2014 ignored` + (suggestion ? ` (did you mean "${suggestion}"?)` : "")
+    );
+  }
   if (!config.apiKey || typeof config.apiKey !== "string") {
-    errors.push("apiKey is required and must be a string (set it in .appilotsrc or via APPILOTS_API_KEY)");
+    errors.push(
+      "apiKey is required and must be a string (set it in .appilotsrc or via APPILOTS_API_KEY)"
+    );
   } else if (!config.apiKey.startsWith("ak_")) {
     errors.push('apiKey must start with "ak_"');
   }
@@ -196,7 +284,8 @@ function validateConfig(config) {
   }
   return {
     valid: errors.length === 0,
-    errors
+    errors,
+    warnings
   };
 }
 
@@ -241,14 +330,23 @@ function dim(msg) {
   if (mode !== "pretty") return;
   console.log(import_chalk.default.dim(msg));
 }
+var BANNER_WIDTH = 39;
+function bannerRow(plain, colored) {
+  return `  ${import_chalk.default.cyan("\u2551")}     ${colored}${" ".repeat(Math.max(0, BANNER_WIDTH - 5 - plain.length))}${import_chalk.default.cyan("\u2551")}`;
+}
 function banner() {
   if (mode !== "pretty") return;
-  const logo = `
-  ${import_chalk.default.cyan("\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557")}
-  ${import_chalk.default.cyan("\u2551")}     ${import_chalk.default.bold.cyan("Appilots MCP Generator")}          ${import_chalk.default.cyan("\u2551")}
-  ${import_chalk.default.cyan("\u2551")}     ${import_chalk.default.dim("v0.1.0")}                    ${import_chalk.default.cyan("\u2551")}
-  ${import_chalk.default.cyan("\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D")}
-  `;
+  const title = "Appilots MCP Generator";
+  const version = `v${CLI_VERSION}`;
+  const border = "\u2550".repeat(BANNER_WIDTH);
+  const logo = [
+    "",
+    `  ${import_chalk.default.cyan(`\u2554${border}\u2557`)}`,
+    bannerRow(title, import_chalk.default.bold.cyan(title)),
+    bannerRow(version, import_chalk.default.dim(version)),
+    `  ${import_chalk.default.cyan(`\u255A${border}\u255D`)}`,
+    "  "
+  ].join("\n");
   console.log(logo);
 }
 function heading(msg) {
@@ -269,19 +367,105 @@ function table(rows) {
 // src/cli/commands/init.ts
 var import_commander = require("commander");
 
+// ../shared/dist/chunk-UEMUBXFH.mjs
+var DEFAULT_API_BASE_URL = "https://api.appilots.com";
+var APPILOTS_API_PATH_PREFIX = "/api/v1";
+function normalizeApiBaseUrl(configured) {
+  const raw = (configured ?? DEFAULT_API_BASE_URL).trim().replace(/\/+$/, "");
+  if (!raw) return `${DEFAULT_API_BASE_URL}${APPILOTS_API_PATH_PREFIX}`;
+  if (new RegExp(`${APPILOTS_API_PATH_PREFIX}(/|$)`).test(raw)) return raw;
+  return `${raw}${APPILOTS_API_PATH_PREFIX}`;
+}
+var LIMITS = {
+  MAX_MCP_DOCUMENT_SIZE_MB: 10,
+  MAX_PROJECTS_PER_USER: 20,
+  MAX_MESSAGE_LENGTH: 4096,
+  MAX_ACTIONS_PER_MESSAGE: 10,
+  SESSION_TIMEOUT_MS: 30 * 60 * 1e3
+  // 30 minutes
+};
+
+// src/utils/stringify.ts
+function stringifyUnknown(value) {
+  if (value instanceof Error) {
+    const message = value.message || value.name;
+    const cause = value.cause;
+    if (cause instanceof Error && cause.message && cause.message !== message) {
+      return `${message} (${cause.message})`;
+    }
+    return message;
+  }
+  if (typeof value === "string") return value;
+  if (value === null || value === void 0) return String(value);
+  if (typeof value !== "object") return String(value);
+  try {
+    const json = JSON.stringify(value);
+    if (json && json !== "{}") return json;
+  } catch {
+  }
+  return String(value);
+}
+
 // src/services/api-client.ts
-var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_TIMEOUT_MS2 = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var RETRY_BASE_DELAY_MS = 500;
+function describeNetworkError(url, err) {
+  let origin = url;
+  try {
+    origin = new URL(url).origin;
+  } catch {
+  }
+  const cause = err?.cause;
+  const code = typeof cause?.code === "string" ? cause.code : void 0;
+  const detail = code ?? stringifyUnknown(err);
+  return new Error(`Cannot reach Appilots server at ${origin} (${detail})`);
+}
+function errorCodeOf(payload) {
+  const error2 = payload?.error;
+  if (error2 && typeof error2 === "object") {
+    const { code } = error2;
+    if (typeof code === "string" && code.trim()) return code;
+  }
+  return void 0;
+}
+function describeApiError(payload, fallback) {
+  const error2 = payload?.error;
+  if (typeof error2 === "string" && error2.trim()) return error2;
+  if (error2 && typeof error2 === "object") {
+    const { code, message: message2 } = error2;
+    const text = typeof message2 === "string" && message2.trim() ? message2 : void 0;
+    const tag = typeof code === "string" && code.trim() ? code : void 0;
+    if (text && tag) return `${text} (${tag})`;
+    if (text) return text;
+    if (tag) return tag;
+  }
+  const message = payload?.message;
+  if (typeof message === "string" && message.trim()) return message;
+  return fallback;
+}
 var AppilotsAPIClient = class {
-  serverUrl;
+  /**
+   * `serverUrl` with the API's mount prefix resolved — every path below
+   * is relative to THIS, not to the configured origin.
+   *
+   * It used to be the raw `serverUrl` with `/api/v1` hardcoded into each
+   * path, which made the field mean something different here than in the
+   * SDK. Both read the same `.appilotsrc`: the SDK completes the prefix
+   * when it is missing, so `https://api.appilots.com/api/v1` is correct
+   * there — and here that same value produced
+   * `/api/v1/api/v1/cli/sync`, a 404 whose body reads `Route not found`.
+   * Sharing `normalizeApiBaseUrl` is what makes one file mean one thing:
+   * with or without the prefix now works in both.
+   */
+  baseUrl;
   apiKey;
   timeoutMs;
   maxRetries;
   constructor(config) {
-    this.serverUrl = config.serverUrl.replace(/\/$/, "");
+    this.baseUrl = normalizeApiBaseUrl(config.serverUrl);
     this.apiKey = config.apiKey;
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
   }
   /**
@@ -305,7 +489,7 @@ var AppilotsAPIClient = class {
         }
         return response;
       } catch (err) {
-        lastError = controller.signal.aborted ? new Error(`Request timed out after ${this.timeoutMs}ms: ${url}`) : err;
+        lastError = controller.signal.aborted ? new Error(`Request timed out after ${this.timeoutMs}ms: ${url}`) : describeNetworkError(url, err);
       } finally {
         clearTimeout(timer);
       }
@@ -324,7 +508,7 @@ var AppilotsAPIClient = class {
    */
   async sync(content, version, appVersion) {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/cli/sync`, {
+      const response = await this.request(`${this.baseUrl}/cli/sync`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -338,7 +522,9 @@ var AppilotsAPIClient = class {
         return {
           success: false,
           unchanged: false,
-          error: errorData?.error || `HTTP ${response.status}: ${response.statusText}`
+          error: describeApiError(errorData, `HTTP ${response.status}: ${response.statusText}`),
+          errorCode: errorCodeOf(errorData),
+          errorStatus: response.status
         };
       }
       const json = await response.json();
@@ -351,7 +537,8 @@ var AppilotsAPIClient = class {
       return {
         success: false,
         unchanged: false,
-        error: error2 instanceof Error ? error2.message : "Failed to sync with Appilots API"
+        error: error2 instanceof Error ? error2.message : "Failed to sync with Appilots API",
+        errorStatus: 0
       };
     }
   }
@@ -362,7 +549,7 @@ var AppilotsAPIClient = class {
    */
   async status() {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/cli/status`, {
+      const response = await this.request(`${this.baseUrl}/cli/status`, {
         method: "GET",
         headers: {
           Authorization: `Bearer ${this.apiKey}`
@@ -371,7 +558,7 @@ var AppilotsAPIClient = class {
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
         return {
-          error: errorData?.error || `HTTP ${response.status}: ${response.statusText}`
+          error: describeApiError(errorData, `HTTP ${response.status}: ${response.statusText}`)
         };
       }
       const json = await response.json();
@@ -393,7 +580,7 @@ var AppilotsAPIClient = class {
    */
   async evalRun(scenarios) {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/cli/eval/run`, {
+      const response = await this.request(`${this.baseUrl}/cli/eval/run`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -424,7 +611,7 @@ var AppilotsAPIClient = class {
    */
   async health() {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/health`, {
+      const response = await this.request(`${this.baseUrl}/health`, {
         method: "GET"
       });
       return response.ok;
@@ -437,6 +624,19 @@ var AppilotsAPIClient = class {
 // src/cli/commands/init.ts
 var import_fs3 = require("fs");
 var import_path2 = require("path");
+
+// src/cli/utils/server-hint.ts
+function hintUnreachableServer(serverUrl, message) {
+  if (serverUrl !== DEFAULT_SERVER_URL) return;
+  if (typeof message === "string" && !message.includes("Cannot reach Appilots server")) return;
+  if (message !== void 0 && typeof message !== "string") return;
+  info(`serverUrl is not set, so the CLI is using the built-in default (${DEFAULT_SERVER_URL})`);
+  info("For the hosted backend, set it in .appilotsrc:");
+  info('  "serverUrl": "https://api.appilots.com"');
+  info("Or pass --server <url>, or set APPILOTS_SERVER_URL");
+}
+
+// src/cli/commands/init.ts
 function ensureConfigIgnored(dir) {
   const gitignorePath = (0, import_path2.join)(dir, ".gitignore");
   if (!(0, import_fs3.existsSync)(gitignorePath)) {
@@ -450,7 +650,10 @@ function ensureConfigIgnored(dir) {
   if (ignored) {
     return "already-ignored";
   }
-  (0, import_fs3.appendFileSync)(gitignorePath, "\n# Appilots CLI config (contains your API key \u2014 do not commit)\n.appilotsrc\n");
+  (0, import_fs3.appendFileSync)(
+    gitignorePath,
+    "\n# Appilots CLI config (contains your API key \u2014 do not commit)\n.appilotsrc\n"
+  );
   return "added";
 }
 function initCommand() {
@@ -473,7 +676,7 @@ function initCommand() {
       if (!options.apiKey && env.apiKey) {
         info("Using API key from APPILOTS_API_KEY environment variable");
       }
-      const serverUrl = options.server || env.serverUrl || "http://localhost:4000";
+      const serverUrl = options.server || env.serverUrl || DEFAULT_SERVER_URL;
       if (!apiKey.startsWith("ak_")) {
         error("Invalid API key format. Must start with ak_");
         process.exit(1);
@@ -487,6 +690,7 @@ function initCommand() {
       if (!isHealthy) {
         error(`Cannot reach Appilots server at ${serverUrl}`);
         info("Make sure the server is running and the URL is correct");
+        hintUnreachableServer(serverUrl);
         process.exit(1);
       }
       const status = await apiClient.status();
@@ -524,7 +728,7 @@ function initCommand() {
       dim("  $ appilots sync  - Analyze and upload your project");
       dim("  $ appilots watch - Watch for changes and auto-sync");
     } catch (err) {
-      error(`Initialization failed: ${err instanceof Error ? err.message : String(err)}`);
+      error(`Initialization failed: ${stringifyUnknown(err)}`);
       process.exit(1);
     }
   });
@@ -533,7 +737,7 @@ function initCommand() {
 // src/cli/commands/sync.ts
 var import_commander2 = require("commander");
 var import_promises5 = require("fs/promises");
-var import_node_path4 = require("path");
+var import_node_path5 = require("path");
 
 // src/generators/MCPGenerator.ts
 var import_promises4 = require("fs/promises");
@@ -813,6 +1017,45 @@ function hasJsxAttribute(element, name) {
 }
 
 // src/ast/jsx/classify.ts
+var NON_INTERACTION_HANDLERS = /* @__PURE__ */ new Set([
+  "onLayout",
+  "onScroll",
+  "onScrollBeginDrag",
+  "onScrollEndDrag",
+  "onMomentumScrollBegin",
+  "onMomentumScrollEnd",
+  "onContentSizeChange",
+  "onEndReached",
+  "onViewableItemsChanged",
+  "onLoad",
+  "onLoadStart",
+  "onLoadEnd",
+  "onError",
+  "onProgress",
+  "onFocus",
+  "onBlur"
+]);
+var VALUE_HANDLERS = /* @__PURE__ */ new Set([
+  "onChange",
+  "onChangeText",
+  "onValueChange",
+  "onSelect",
+  "onSelectionChange",
+  "onSubmitEditing"
+]);
+function pressHandlerProp(element) {
+  let fallback;
+  for (const attr of element.attributes) {
+    if (attr.type !== "JSXAttribute" || attr.name.type !== "JSXIdentifier") continue;
+    const name = attr.name.name;
+    if (!/^on[A-Z]/.test(name)) continue;
+    if (attr.value?.type !== "JSXExpressionContainer") continue;
+    if (name === "onPress") return name;
+    if (NON_INTERACTION_HANDLERS.has(name) || VALUE_HANDLERS.has(name)) continue;
+    fallback ??= name;
+  }
+  return fallback;
+}
 var VIEW_COMPONENTS = /* @__PURE__ */ new Set(["View", "ScrollView", "SafeAreaView", "KeyboardAvoidingView"]);
 var INPUT_COMPONENTS = /* @__PURE__ */ new Set(["TextInput", "Input", "HocInput"]);
 var BUTTON_COMPONENTS = /* @__PURE__ */ new Set(["TouchableOpacity", "Pressable", "Button"]);
@@ -827,17 +1070,16 @@ function classifyJsxComponent(name, element) {
   if (INPUT_COMPONENTS.has(name)) return "input";
   if (BUTTON_COMPONENTS.has(name)) return "button";
   if (element) {
-    const hasOptions = hasJsxAttribute(element, "options");
+    const hasOptions = hasJsxAttribute(element, "options") || hasJsxAttribute(element, "segments") || hasJsxAttribute(element, "choices") || hasJsxAttribute(element, "tabs");
     const hasValue = hasJsxAttribute(element, "value");
     const hasChecked = hasJsxAttribute(element, "checked") || hasJsxAttribute(element, "selected");
     const hasOnChange = hasJsxAttribute(element, "onChange") || hasJsxAttribute(element, "onValueChange") || hasJsxAttribute(element, "onChangeText");
-    const hasOnPress = hasJsxAttribute(element, "onPress");
     if (hasOptions && (hasValue || hasOnChange)) return "select";
     if (hasChecked && hasOnChange) return "toggle";
     if (hasOnChange && (hasJsxAttribute(element, "label") || hasJsxAttribute(element, "placeholder"))) {
       return "input";
     }
-    if (hasOnPress) return "button";
+    if (pressHandlerProp(element)) return "button";
     if (getStringAttr(element, "visible") || getExpressionIdentifierAttr(element, "visible")) {
       return "modal";
     }
@@ -1165,8 +1407,8 @@ var ScreenAnalyzer = class {
     }
     const screens = [];
     this.screensFilteredOut = 0;
-    for (const file of files) {
-      const filePath = import_path3.default.resolve(this.config.rootDir, file);
+    for (const file2 of files) {
+      const filePath = import_path3.default.resolve(this.config.rootDir, file2);
       try {
         const descriptor = await this.analyzeFile(filePath);
         if (!descriptor) continue;
@@ -1176,23 +1418,28 @@ var ScreenAnalyzer = class {
           if (!hasRegisterScreen && !matchesPattern) {
             this.screensFilteredOut++;
             if (this.verbose) {
-              console.log(`[ScreenAnalyzer] \u2717 Filtered (strict): ${file}`);
+              console.log(`[ScreenAnalyzer] \u2717 Filtered (strict): ${file2}`);
             }
             continue;
           }
         }
         screens.push(descriptor);
         if (this.verbose) {
-          console.log(`[ScreenAnalyzer] \u2713 Analyzed: ${descriptor.name} (${file})`);
+          console.log(`[ScreenAnalyzer] \u2713 Analyzed: ${descriptor.name} (${file2})`);
         }
       } catch (error2) {
         if (this.verbose) {
-          console.warn(`[ScreenAnalyzer] Failed to parse ${file}:`, error2 instanceof Error ? error2.message : error2);
+          console.warn(
+            `[ScreenAnalyzer] Failed to parse ${file2}:`,
+            error2 instanceof Error ? error2.message : error2
+          );
         }
       }
     }
     if (this.verbose && this.strictScreens) {
-      console.log(`[ScreenAnalyzer] Strict mode: ${screens.length} included, ${this.screensFilteredOut} filtered out`);
+      console.log(
+        `[ScreenAnalyzer] Strict mode: ${screens.length} included, ${this.screensFilteredOut} filtered out`
+      );
     }
     return screens;
   }
@@ -1480,7 +1727,11 @@ var ScreenAnalyzer = class {
     for (const form of secondary) {
       const existing = out.find((candidate) => candidate.id === form.id) ?? this.findFormWithSharedFields(out, form);
       if (!existing) {
-        out.push({ ...form, fields: [...form.fields], submitAction: this.namedSubmitAction(form.submitAction) });
+        out.push({
+          ...form,
+          fields: [...form.fields],
+          submitAction: this.namedSubmitAction(form.submitAction)
+        });
         continue;
       }
       for (const field of form.fields) {
@@ -1499,9 +1750,12 @@ var ScreenAnalyzer = class {
   findEquivalentField(fields, incoming) {
     return fields.find((field) => {
       if (field.name && incoming.name && field.name === incoming.name) return true;
-      if (field.valueBinding && incoming.valueBinding && field.valueBinding === incoming.valueBinding) return true;
-      if (field.locator?.id && incoming.locator?.id && field.locator.id === incoming.locator.id) return true;
-      if (field.placeholder && incoming.placeholder && field.placeholder === incoming.placeholder) return true;
+      if (field.valueBinding && incoming.valueBinding && field.valueBinding === incoming.valueBinding)
+        return true;
+      if (field.locator?.id && incoming.locator?.id && field.locator.id === incoming.locator.id)
+        return true;
+      if (field.placeholder && incoming.placeholder && field.placeholder === incoming.placeholder)
+        return true;
       if (field.locator?.accessibilityLabel && incoming.locator?.accessibilityLabel && field.locator.accessibilityLabel === incoming.locator.accessibilityLabel) {
         return true;
       }
@@ -1661,9 +1915,11 @@ var ScreenAnalyzer = class {
               source: field.locator?.source ?? "accessibilityLabel"
             });
           } else if (attrName === "keyboardType") {
-            if (attr.value.value === "email-address" || attr.value.value === "email") field.type = "email";
+            if (attr.value.value === "email-address" || attr.value.value === "email")
+              field.type = "email";
             if (attr.value.value === "phone-pad") field.type = "phone";
-            if (attr.value.value === "numeric" || attr.value.value === "number-pad") field.type = "number";
+            if (attr.value.value === "numeric" || attr.value.value === "number-pad")
+              field.type = "number";
           }
         } else if (BabelTypes.isJSXExpressionContainer(attr.value)) {
           if (attrName === "value" && BabelTypes.isIdentifier(attr.value.expression)) {
@@ -1829,8 +2085,10 @@ var ScreenAnalyzer = class {
       };
       if (handler.nativeConfirmationExpected) action.nativeConfirmationExpected = true;
       if (handler.targetScreen && !action.targetScreen) action.targetScreen = handler.targetScreen;
-      if (handler.successSignal && !action.successSignal) action.successSignal = handler.successSignal;
-      if (handler.failureSignal && !action.failureSignal) action.failureSignal = handler.failureSignal;
+      if (handler.successSignal && !action.successSignal)
+        action.successSignal = handler.successSignal;
+      if (handler.failureSignal && !action.failureSignal)
+        action.failureSignal = handler.failureSignal;
       if (handler.opensModal && !action.opensModal) action.opensModal = handler.opensModal;
       if (handler.destructive || action.destructive === true || action.requiresConfirmation === true || action.effect === "destructive" || action.riskLevel === "high") {
         action.destructive = true;
@@ -1848,6 +2106,7 @@ var ScreenAnalyzer = class {
         if (!BabelTypes.isJSXIdentifier(element.name)) return;
         const componentName = element.name.name;
         if (classifyJsxComponent(componentName, element) !== "button") return;
+        const pressProp = pressHandlerProp(element);
         let label;
         let handler;
         for (const attr of element.attributes) {
@@ -1857,7 +2116,7 @@ var ScreenAnalyzer = class {
           if ((attrName === "title" || attrName === "accessibilityLabel" || attrName === "label") && BabelTypes.isStringLiteral(attr.value)) {
             label = attr.value.value;
           }
-          if (attrName === "onPress" && BabelTypes.isJSXExpressionContainer(attr.value) && BabelTypes.isIdentifier(attr.value.expression)) {
+          if (attrName === pressProp && BabelTypes.isJSXExpressionContainer(attr.value) && BabelTypes.isIdentifier(attr.value.expression)) {
             handler = attr.value.expression.name;
           }
         }
@@ -1923,10 +2182,13 @@ var ScreenAnalyzer = class {
       }
     };
     if (fn.body) {
-      (0, import_traverse4.default)(fn.body, {
-        noScope: true,
-        enter: (nodePath) => inspectNode(nodePath.node)
-      });
+      (0, import_traverse4.default)(
+        fn.body,
+        {
+          noScope: true,
+          enter: (nodePath) => inspectNode(nodePath.node)
+        }
+      );
     }
     const expectedOutcome = targetScreen ? "navigation" : hasStateSetter ? "inline-feedback" : hasAwait || hasThen ? "mixed" : "none";
     return {
@@ -1984,6 +2246,7 @@ var ScreenAnalyzer = class {
     };
     const componentName = BabelTypes.isJSXIdentifier(element.name) ? element.name.name : void 0;
     action.sourceComponent = componentName;
+    const pressProp = pressHandlerProp(element) ?? "onPress";
     let handlerName;
     for (const attr of element.attributes) {
       if (!BabelTypes.isJSXAttribute(attr)) continue;
@@ -2018,7 +2281,7 @@ var ScreenAnalyzer = class {
             }
           }
         } else if (BabelTypes.isJSXExpressionContainer(attr.value)) {
-          if (attrName === "onPress" && BabelTypes.isIdentifier(attr.value.expression)) {
+          if (attrName === pressProp && BabelTypes.isIdentifier(attr.value.expression)) {
             handlerName = attr.value.expression.name.toLowerCase();
             action.handler = attr.value.expression.name;
             if (handlerName.includes("submit")) {
@@ -2026,7 +2289,7 @@ var ScreenAnalyzer = class {
             } else if (handlerName.includes("navigate")) {
               action.type = "navigation";
             }
-          } else if (attrName === "onPress") {
+          } else if (attrName === pressProp) {
             const inline = this.extractInlineOnPressMetadata(attr.value.expression);
             if (inline.handler) {
               handlerName = inline.handler.toLowerCase();
@@ -2050,7 +2313,11 @@ var ScreenAnalyzer = class {
       }
     }
     if (!action.locator && action.id) {
-      action.locator = { id: action.id, label: action.label, source: action.label ? "label" : "inferred" };
+      action.locator = {
+        id: action.id,
+        label: action.label,
+        source: action.label ? "label" : "inferred"
+      };
     }
     if (this.isElementDestructive(element, handlerName, action.id)) {
       action.destructive = true;
@@ -2192,24 +2459,27 @@ var ScreenAnalyzer = class {
   }
   extractRowAction(fn) {
     let action;
-    (0, import_traverse4.default)(fn.body, {
-      noScope: true,
-      CallExpression: (nodePath) => {
-        const node = nodePath.node;
-        if (!BabelTypes.isMemberExpression(node.callee) || !BabelTypes.isIdentifier(node.callee.object) || node.callee.object.name !== "navigation" || !BabelTypes.isIdentifier(node.callee.property) || !["navigate", "push", "replace"].includes(node.callee.property.name)) {
-          return;
+    (0, import_traverse4.default)(
+      fn.body,
+      {
+        noScope: true,
+        CallExpression: (nodePath) => {
+          const node = nodePath.node;
+          if (!BabelTypes.isMemberExpression(node.callee) || !BabelTypes.isIdentifier(node.callee.object) || node.callee.object.name !== "navigation" || !BabelTypes.isIdentifier(node.callee.property) || !["navigate", "push", "replace"].includes(node.callee.property.name)) {
+            return;
+          }
+          const firstArg = node.arguments[0];
+          if (!BabelTypes.isStringLiteral(firstArg)) return;
+          const params = this.extractNavigationParams(node.arguments[1]);
+          action = {
+            type: "navigation",
+            targetScreen: firstArg.value,
+            ...Object.keys(params).length > 0 ? { params } : {},
+            description: `Pressing a row opens ${firstArg.value}`
+          };
         }
-        const firstArg = node.arguments[0];
-        if (!BabelTypes.isStringLiteral(firstArg)) return;
-        const params = this.extractNavigationParams(node.arguments[1]);
-        action = {
-          type: "navigation",
-          targetScreen: firstArg.value,
-          ...Object.keys(params).length > 0 ? { params } : {},
-          description: `Pressing a row opens ${firstArg.value}`
-        };
       }
-    });
+    );
     return action;
   }
   extractNavigationParams(arg) {
@@ -2242,15 +2512,18 @@ var ScreenAnalyzer = class {
     } else if (BabelTypes.isIdentifier(firstParam)) {
       itemNames.add(firstParam.name);
     }
-    (0, import_traverse4.default)(fn.body, {
-      noScope: true,
-      MemberExpression: (nodePath) => {
-        const node = nodePath.node;
-        if (BabelTypes.isIdentifier(node.object) && itemNames.has(node.object.name) && BabelTypes.isIdentifier(node.property)) {
-          fields.add(node.property.name);
+    (0, import_traverse4.default)(
+      fn.body,
+      {
+        noScope: true,
+        MemberExpression: (nodePath) => {
+          const node = nodePath.node;
+          if (BabelTypes.isIdentifier(node.object) && itemNames.has(node.object.name) && BabelTypes.isIdentifier(node.property)) {
+            fields.add(node.property.name);
+          }
         }
       }
-    });
+    );
     return Array.from(fields).sort();
   }
   inferItemType(dataSource, renderItem, displayFields) {
@@ -2262,11 +2535,19 @@ var ScreenAnalyzer = class {
     if (displayFields.length > 0) return "Item";
     return void 0;
   }
+  /**
+   * Identity comes from how a field is NAMED, not from what the app
+   * sells: `id`/`uuid`/`key`/`slug` are conventions any codebase uses,
+   * `name`/`title`/`email` are how any row introduces itself. `plate`
+   * used to sit in this list and read like one of them — but it is the
+   * example app's schema, and no other tenant ever got its equivalent
+   * (`mrn`, `trackingNumber`, `sku`) added here.
+   */
   inferIdentityFields(keyField, displayFields) {
     const out = /* @__PURE__ */ new Set();
     if (keyField) out.add(keyField);
     for (const field of displayFields) {
-      if (/^(id|uuid|key|name|title|plate|email|slug)$/i.test(field)) out.add(field);
+      if (/^(id|uuid|key|name|title|email|slug)$/i.test(field)) out.add(field);
     }
     return Array.from(out);
   }
@@ -2277,17 +2558,23 @@ var ScreenAnalyzer = class {
       CallExpression: (nodePath) => {
         const node = nodePath.node;
         if (!BabelTypes.isMemberExpression(node.callee)) return;
-        if (!BabelTypes.isIdentifier(node.callee.property) || node.callee.property.name !== "filter") return;
-        if (!BabelTypes.isIdentifier(node.callee.object) || node.callee.object.name !== dataSource) return;
+        if (!BabelTypes.isIdentifier(node.callee.property) || node.callee.property.name !== "filter")
+          return;
+        if (!BabelTypes.isIdentifier(node.callee.object) || node.callee.object.name !== dataSource)
+          return;
         const fn = node.arguments[0];
-        if (!BabelTypes.isArrowFunctionExpression(fn) && !BabelTypes.isFunctionExpression(fn)) return;
-        (0, import_traverse4.default)(fn.body, {
-          noScope: true,
-          Identifier: (innerPath) => {
-            const name = innerPath.node.name;
-            if (/query|search|filter/i.test(name)) queryBinding = queryBinding ?? name;
+        if (!BabelTypes.isArrowFunctionExpression(fn) && !BabelTypes.isFunctionExpression(fn))
+          return;
+        (0, import_traverse4.default)(
+          fn.body,
+          {
+            noScope: true,
+            Identifier: (innerPath) => {
+              const name = innerPath.node.name;
+              if (/query|search|filter/i.test(name)) queryBinding = queryBinding ?? name;
+            }
           }
-        });
+        );
       }
     });
     return queryBinding;
@@ -2378,7 +2665,7 @@ var NavigationAnalyzer = class {
       cwd: this.config.rootDir,
       ignore: excludePatterns
     });
-    return files.map((file) => import_path4.default.join(this.config.rootDir, file));
+    return files.map((file2) => import_path4.default.join(this.config.rootDir, file2));
   }
   /** Parse navigator definitions from a file */
   parseNavigators(content, filePath) {
@@ -2439,11 +2726,7 @@ var NavigationAnalyzer = class {
                 if (t5.isJSXAttribute(initialRouteAttr) && t5.isStringLiteral(initialRouteAttr.value)) {
                   navigator.initialRouteName = initialRouteAttr.value.value;
                 }
-                const screens = this.extractScreensFromNavigator(
-                  node,
-                  objectName,
-                  navigator.type
-                );
+                const screens = this.extractScreensFromNavigator(node, objectName, navigator.type);
                 screensByNavigator.set(objectName, screens);
               }
             }
@@ -2460,27 +2743,112 @@ var NavigationAnalyzer = class {
     }
     return navigators;
   }
+  /**
+   * Is this JSX element `<navigatorVarName.MEMBER …>`?
+   */
+  // Deliberately NOT a type predicate (`node is t.JSXElement`): a false
+  // result would then narrow `node` to "not a JSXElement", and the very
+  // next check — the same node against a different member — would see
+  // `never`. It is a question about the member name, not about the node
+  // kind.
+  isNavigatorMember(node, navigatorVarName, member) {
+    if (!t5.isJSXElement(node)) return false;
+    const name = node.openingElement.name;
+    return t5.isJSXMemberExpression(name) && t5.isJSXIdentifier(name.object) && name.object.name === navigatorVarName && t5.isJSXIdentifier(name.property) && name.property.name === member;
+  }
+  /**
+   * Flatten a navigator's JSX children into the `<X.Screen>` elements they
+   * contain, unwrapping every container a real app puts in between.
+   *
+   * The old version compared `t.isJSXElement(child)` against the direct
+   * children only. A ternary is a `JSXExpressionContainer`, so an
+   * auth-gated root — the modal shape of a commercial app, and the shape
+   * of this repo's own `apps/example-app` — contributed ZERO screens to
+   * the graph while `appilots sync` reported success (#396).
+   *
+   * Both branches of a conditional are collected on purpose. The graph is
+   * a design-time map of what routes EXIST, not a prediction of which one
+   * a given session will render; the agent needs the destination name to
+   * be there whether or not the user happens to be logged in right now.
+   */
+  collectScreenElements(children, navigatorVarName, depth = 0) {
+    if (depth > 12) return [];
+    const found = [];
+    const visit = (node) => {
+      if (!node) return;
+      if (this.isNavigatorMember(node, navigatorVarName, "Screen")) {
+        found.push(node);
+        return;
+      }
+      if (this.isNavigatorMember(node, navigatorVarName, "Group")) {
+        const group = node;
+        found.push(...this.collectScreenElements(group.children, navigatorVarName, depth + 1));
+        return;
+      }
+      if (t5.isJSXElement(node)) {
+        const name = node.openingElement.name;
+        const isForeignNavigator = t5.isJSXMemberExpression(name) && t5.isJSXIdentifier(name.property) && name.property.name === "Navigator";
+        if (isForeignNavigator) return;
+        found.push(...this.collectScreenElements(node.children, navigatorVarName, depth + 1));
+        return;
+      }
+      if (t5.isJSXFragment(node)) {
+        found.push(...this.collectScreenElements(node.children, navigatorVarName, depth + 1));
+        return;
+      }
+      if (t5.isJSXExpressionContainer(node)) {
+        visit(node.expression);
+        return;
+      }
+      if (t5.isConditionalExpression(node)) {
+        visit(node.consequent);
+        visit(node.alternate);
+        return;
+      }
+      if (t5.isLogicalExpression(node)) {
+        visit(node.left);
+        visit(node.right);
+        return;
+      }
+      if (t5.isCallExpression(node)) {
+        for (const arg of node.arguments) {
+          if (t5.isArrowFunctionExpression(arg) || t5.isFunctionExpression(arg)) {
+            if (t5.isBlockStatement(arg.body)) {
+              for (const stmt of arg.body.body) {
+                if (t5.isReturnStatement(stmt)) visit(stmt.argument);
+              }
+            } else {
+              visit(arg.body);
+            }
+          }
+        }
+        return;
+      }
+      if (t5.isArrayExpression(node)) {
+        for (const el of node.elements) visit(el);
+        return;
+      }
+      if (t5.isTSAsExpression(node) || t5.isTSNonNullExpression(node)) {
+        visit(node.expression);
+      }
+    };
+    for (const child of children) visit(child);
+    return found;
+  }
   /** Extract screens from a navigator JSX element */
   extractScreensFromNavigator(navigatorElement, navigatorVarName, navigatorType) {
     const screens = [];
     if (!navigatorElement.children) return screens;
-    for (const child of navigatorElement.children) {
-      if (t5.isJSXElement(child) && t5.isJSXMemberExpression(child.openingElement.name)) {
-        const memberExpr = child.openingElement.name;
-        if (t5.isJSXIdentifier(memberExpr.object) && memberExpr.object.name === navigatorVarName && t5.isJSXIdentifier(memberExpr.property) && memberExpr.property.name === "Screen") {
-          const screenName = this.extractAttributeValue(
-            child.openingElement.attributes,
-            "name"
-          );
-          if (screenName) {
-            screens.push({
-              name: screenName,
-              navigatorName: navigatorVarName,
-              navigatorType
-            });
-          }
-        }
-      }
+    const seen = /* @__PURE__ */ new Set();
+    for (const element of this.collectScreenElements(navigatorElement.children, navigatorVarName)) {
+      const screenName = this.extractAttributeValue(element.openingElement.attributes, "name");
+      if (!screenName || seen.has(screenName)) continue;
+      seen.add(screenName);
+      screens.push({
+        name: screenName,
+        navigatorName: navigatorVarName,
+        navigatorType
+      });
     }
     return screens;
   }
@@ -2539,9 +2907,7 @@ var NavigationAnalyzer = class {
       if (member.type === "TSPropertySignature" && member.key) {
         const keyName = member.key.type === "Identifier" ? member.key.name : null;
         if (keyName && member.typeAnnotation) {
-          const params = this.extractParamsFromType(
-            member.typeAnnotation.typeAnnotation
-          );
+          const params = this.extractParamsFromType(member.typeAnnotation.typeAnnotation);
           entries.set(keyName, params);
         }
       }
@@ -2581,7 +2947,7 @@ var NavigationAnalyzer = class {
     if (type.type === "TSUndefinedKeyword") return "undefined";
     if (type.type === "TSNullKeyword") return "null";
     if (type.type === "TSUnionType") {
-      return type.types.map((t12) => this.typeToString(t12)).join(" | ");
+      return type.types.map((t15) => this.typeToString(t15)).join(" | ");
     }
     if (type.type === "TSTypeLiteral") {
       return "object";
@@ -2602,7 +2968,7 @@ var NavigationAnalyzer = class {
   /** Attach parsed type params to navigator screens */
   attachParamsToNavigators(navigators, types) {
     for (const navigator of navigators) {
-      const matchingType = types.find((t12) => t12.type === navigator.type);
+      const matchingType = types.find((t15) => t15.type === navigator.type);
       if (matchingType) {
         for (const screen of navigator.screens) {
           const screenParams = matchingType.paramEntries.get(screen.name);
@@ -2620,6 +2986,11 @@ var NavigationAnalyzer = class {
     let initialScreen = "";
     for (const navigator of parsedNavigators) {
       const screenNames = navigator.screens.map((s) => s.name);
+      if (screenNames.length === 0) {
+        console.warn(
+          `[MCPGenerator] navigator "${navigator.name}" (${navigator.type}) declared no reachable screens. Its routes will be missing from the app map, so the agent will have no destination name for them. If the screens are there in the source, this is a parser gap \u2014 please report it with the file.`
+        );
+      }
       navigators.push({
         name: navigator.name,
         type: navigator.type,
@@ -2693,8 +3064,8 @@ var ComponentAnalyzer = class {
       });
       const components = [];
       (0, import_traverse6.default)(ast, {
-        JSXElement: (path9) => {
-          const component = this.extractComponentFromJSXElement(path9.node);
+        JSXElement: (path11) => {
+          const component = this.extractComponentFromJSXElement(path11.node);
           if (component) {
             components.push(component);
           }
@@ -2828,13 +3199,13 @@ var FormAnalyzer = class {
       this.inputElements = [];
       this.submitButtons = [];
       (0, import_traverse7.default)(ast, {
-        CallExpression: (path9) => {
-          this.extractStateVariables(path9.node);
+        CallExpression: (path11) => {
+          this.extractStateVariables(path11.node);
         }
       });
       (0, import_traverse7.default)(ast, {
-        JSXElement: (path9) => {
-          this.extractFormElements(path9.node);
+        JSXElement: (path11) => {
+          this.extractFormElements(path11.node);
         }
       });
       const validationRules = this.extractValidationRules(ast);
@@ -2934,8 +3305,8 @@ var FormAnalyzer = class {
   extractValidationRules(ast) {
     const rules = {};
     (0, import_traverse7.default)(ast, {
-      IfStatement: (path9) => {
-        const test = path9.node.test;
+      IfStatement: (path11) => {
+        const test = path11.node.test;
         const rule = this.extractRuleFromCondition(test);
         if (rule) {
           const { field, description } = rule;
@@ -3068,8 +3439,8 @@ var ReactNativePlatformAnalyzer = class {
     console.log(
       `[ReactNativePlatformAnalyzer] Analyzing components and forms from ${screenFiles.length} files...`
     );
-    const enrichmentPromises = screenFiles.map(async (file) => {
-      const filePath = import_node_path.default.resolve(config.rootDir, file);
+    const enrichmentPromises = screenFiles.map(async (file2) => {
+      const filePath = import_node_path.default.resolve(config.rootDir, file2);
       try {
         const [components, forms] = await Promise.all([
           componentAnalyzer.analyzeFile(filePath),
@@ -3077,7 +3448,7 @@ var ReactNativePlatformAnalyzer = class {
         ]);
         return { filePath, components, forms };
       } catch (error2) {
-        console.warn(`[ReactNativePlatformAnalyzer] Failed to analyze ${file}:`, error2);
+        console.warn(`[ReactNativePlatformAnalyzer] Failed to analyze ${file2}:`, error2);
         return { filePath, components: [], forms: [] };
       }
     });
@@ -3345,13 +3716,13 @@ function staticRoutePath(node) {
   if (!node) return void 0;
   if (t9.isStringLiteral(node)) return node.value;
   if (t9.isTemplateLiteral(node)) {
-    let path9 = "";
+    let path11 = "";
     node.quasis.forEach((quasi, index) => {
-      path9 += quasi.value.cooked ?? quasi.value.raw;
+      path11 += quasi.value.cooked ?? quasi.value.raw;
       const expr = node.expressions[index];
-      if (expr) path9 += `:${paramNameOf(expr)}`;
+      if (expr) path11 += `:${paramNameOf(expr)}`;
     });
-    return path9;
+    return path11;
   }
   return void 0;
 }
@@ -3436,27 +3807,29 @@ var WebScreenAnalyzer = class {
       include = ["**/*.tsx", "**/*.ts", "**/*.jsx", "**/*.js"],
       exclude = ["**/node_modules/**", "**/dist/**", "**/build/**"]
     } = this.config;
-    const files = await (0, import_fast_glob4.default)(include, { cwd: this.config.rootDir, ignore: exclude });
+    const files = (await (0, import_fast_glob4.default)(include, { cwd: this.config.rootDir, ignore: exclude })).filter(
+      (file2) => !file2.endsWith(".d.ts")
+    );
     const patternMatches = await (0, import_fast_glob4.default)(this.screenPatterns, {
       cwd: this.config.rootDir,
       ignore: exclude
     });
     const patternSet = new Set(patternMatches.map((f) => import_path5.default.resolve(this.config.rootDir, f)));
     const candidates = [];
-    for (const file of files) {
-      const filePath = import_path5.default.resolve(this.config.rootDir, file);
+    for (const file2 of files) {
+      const filePath = import_path5.default.resolve(this.config.rootDir, file2);
       try {
         const candidate = await this.analyzeFile(filePath);
         if (!candidate) continue;
         candidate.matchesScreenPattern = patternSet.has(filePath);
         candidates.push(candidate);
         if (this.verbose) {
-          console.log(`[WebScreenAnalyzer] \u2713 Analyzed: ${candidate.descriptor.name} (${file})`);
+          console.log(`[WebScreenAnalyzer] \u2713 Analyzed: ${candidate.descriptor.name} (${file2})`);
         }
       } catch (error2) {
         if (this.verbose) {
           console.warn(
-            `[WebScreenAnalyzer] Failed to parse ${file}:`,
+            `[WebScreenAnalyzer] Failed to parse ${file2}:`,
             error2 instanceof Error ? error2.message : error2
           );
         }
@@ -3807,7 +4180,8 @@ var WebScreenAnalyzer = class {
     if (type === "email") return "email";
     if (type === "tel") return "phone";
     if (type === "number") return "number";
-    if (type === "date" || type === "datetime-local" || type === "month" || type === "week") return "date";
+    if (type === "date" || type === "datetime-local" || type === "month" || type === "week")
+      return "date";
     const inputMode = getStringAttr(opening, "inputMode") ?? getStringAttr(opening, "inputmode");
     if (inputMode === "email") return "email";
     if (inputMode === "tel") return "phone";
@@ -4121,7 +4495,9 @@ var WebScreenAnalyzer = class {
         }
         const callback = expr.arguments[0];
         if (!t10.isArrowFunctionExpression(callback) && !t10.isFunctionExpression(callback)) return;
-        const enclosing = nodePath.findParent((p) => p.isJSXElement());
+        const enclosing = nodePath.findParent(
+          (p) => p.isJSXElement()
+        );
         const enclosingName = enclosing ? getJsxElementName(enclosing.node.openingElement) : null;
         const enclosingRole = enclosing && enclosingName ? classifyWebJsxComponent(enclosingName, enclosing.node.openingElement) : null;
         const returnsListItem = callbackReturnsTag(callback, /* @__PURE__ */ new Set(["li", "tr"]));
@@ -4223,16 +4599,19 @@ function firstCalledFunctionName(node) {
 }
 function containsWindowConfirm(body) {
   let found = false;
-  (0, import_traverse9.default)(body, {
-    noScope: true,
-    CallExpression: (nodePath) => {
-      const callee = nodePath.node.callee;
-      if (t10.isIdentifier(callee) && callee.name === "confirm") found = true;
-      if (t10.isMemberExpression(callee) && t10.isIdentifier(callee.object) && callee.object.name === "window" && t10.isIdentifier(callee.property) && callee.property.name === "confirm") {
-        found = true;
+  (0, import_traverse9.default)(
+    body,
+    {
+      noScope: true,
+      CallExpression: (nodePath) => {
+        const callee = nodePath.node.callee;
+        if (t10.isIdentifier(callee) && callee.name === "confirm") found = true;
+        if (t10.isMemberExpression(callee) && t10.isIdentifier(callee.object) && callee.object.name === "window" && t10.isIdentifier(callee.property) && callee.property.name === "confirm") {
+          found = true;
+        }
       }
     }
-  });
+  );
   return found;
 }
 function mergeLocator(current, next) {
@@ -4272,32 +4651,38 @@ function collectionItemNames(callback) {
 function collectionDisplayFields(callback, itemNames) {
   const fields = /* @__PURE__ */ new Set();
   if (!callback.body) return [];
-  (0, import_traverse9.default)(callback.body, {
-    noScope: true,
-    MemberExpression: (nodePath) => {
-      const node = nodePath.node;
-      if (t10.isIdentifier(node.object) && itemNames.has(node.object.name) && t10.isIdentifier(node.property)) {
-        fields.add(node.property.name);
+  (0, import_traverse9.default)(
+    callback.body,
+    {
+      noScope: true,
+      MemberExpression: (nodePath) => {
+        const node = nodePath.node;
+        if (t10.isIdentifier(node.object) && itemNames.has(node.object.name) && t10.isIdentifier(node.property)) {
+          fields.add(node.property.name);
+        }
       }
     }
-  });
+  );
   return Array.from(fields).sort();
 }
 function collectionKeyField(callback, itemNames) {
   let keyField;
   if (!callback.body) return void 0;
-  (0, import_traverse9.default)(callback.body, {
-    noScope: true,
-    JSXAttribute: (nodePath) => {
-      const attr = nodePath.node;
-      if (!t10.isJSXIdentifier(attr.name) || attr.name.name !== "key") return;
-      if (!attr.value || !t10.isJSXExpressionContainer(attr.value)) return;
-      const expr = attr.value.expression;
-      if (t10.isMemberExpression(expr) && t10.isIdentifier(expr.object) && itemNames.has(expr.object.name) && t10.isIdentifier(expr.property)) {
-        keyField = keyField ?? expr.property.name;
+  (0, import_traverse9.default)(
+    callback.body,
+    {
+      noScope: true,
+      JSXAttribute: (nodePath) => {
+        const attr = nodePath.node;
+        if (!t10.isJSXIdentifier(attr.name) || attr.name.name !== "key") return;
+        if (!attr.value || !t10.isJSXExpressionContainer(attr.value)) return;
+        const expr = attr.value.expression;
+        if (t10.isMemberExpression(expr) && t10.isIdentifier(expr.object) && itemNames.has(expr.object.name) && t10.isIdentifier(expr.property)) {
+          keyField = keyField ?? expr.property.name;
+        }
       }
     }
-  });
+  );
   return keyField;
 }
 function collectionRowAction(callback) {
@@ -4345,7 +4730,7 @@ function inferIdentityFields(keyField, displayFields) {
   const out = /* @__PURE__ */ new Set();
   if (keyField) out.add(keyField);
   for (const field of displayFields) {
-    if (/^(id|uuid|key|name|title|plate|email|slug)$/i.test(field)) out.add(field);
+    if (/^(id|uuid|key|name|title|email|slug)$/i.test(field)) out.add(field);
   }
   return Array.from(out);
 }
@@ -4403,7 +4788,7 @@ var WebNavigationAnalyzer = class {
       ...this.navigationExclude
     ];
     const files = await (0, import_fast_glob5.default)(patterns, { cwd: this.config.rootDir, ignore });
-    return files.map((file) => import_path6.default.join(this.config.rootDir, file));
+    return files.map((file2) => import_path6.default.join(this.config.rootDir, file2));
   }
   // ── JSX <Route> style ────────────────────────────────────────────
   extractJsxRoutes(ast) {
@@ -4905,8 +5290,8 @@ var ZodParsedType = util.arrayToEnum([
   "set"
 ]);
 var getParsedType = (data) => {
-  const t12 = typeof data;
-  switch (t12) {
+  const t15 = typeof data;
+  switch (t15) {
     case "undefined":
       return ZodParsedType.undefined;
     case "string":
@@ -5178,8 +5563,8 @@ function getErrorMap() {
 
 // ../../node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path9, errorMaps, issueData } = params;
-  const fullPath = [...path9, ...issueData.path || []];
+  const { data, path: path11, errorMaps, issueData } = params;
+  const fullPath = [...path11, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -5295,11 +5680,11 @@ var errorUtil;
 
 // ../../node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path9, key) {
+  constructor(parent, value, path11, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path9;
+    this._path = path11;
     this._key = key;
   }
   get path() {
@@ -8741,7 +9126,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// ../shared/dist/chunk-MSOZJNXB.mjs
+// ../shared/dist/chunk-PKS3VDNB.mjs
 var locatorSourceSchema = external_exports.enum([
   "appilotsId",
   "testID",
@@ -8767,7 +9152,16 @@ var locatorDescriptorSchema = external_exports.object({
   source: locatorSourceSchema.optional()
 }).passthrough();
 var signalDescriptorSchema = external_exports.object({
-  type: external_exports.enum(["navigation", "goBack", "toast", "modal", "inline-error", "data-arrival", "loading", "none"]).or(external_exports.string().min(1).max(60)),
+  type: external_exports.enum([
+    "navigation",
+    "goBack",
+    "toast",
+    "modal",
+    "inline-error",
+    "data-arrival",
+    "loading",
+    "none"
+  ]).or(external_exports.string().min(1).max(60)),
   target: external_exports.string().optional(),
   description: external_exports.string().optional()
 }).passthrough();
@@ -8781,7 +9175,20 @@ var waitPolicyDescriptorSchema = external_exports.object({
   signals: external_exports.array(signalDescriptorSchema).optional(),
   maxMs: external_exports.number().finite().optional()
 }).passthrough();
-var targetDescriptorRoleSchema = external_exports.enum(["button", "submit", "input", "toggle", "select", "date", "list", "row", "menuItem", "modal", "custom"]).or(external_exports.string().min(1).max(60));
+var targetDescriptorRoleSchema = external_exports.enum([
+  "button",
+  "submit",
+  "input",
+  "toggle",
+  "select",
+  "date",
+  "list",
+  "row",
+  "menuItem",
+  "modal",
+  "custom"
+]).or(external_exports.string().min(1).max(60));
+var targetOriginSchema = external_exports.enum(["analyzer", "manifest"]).or(external_exports.string().min(1).max(40));
 var targetDescriptorSchema = external_exports.object({
   id: external_exports.string(),
   role: targetDescriptorRoleSchema,
@@ -8795,10 +9202,20 @@ var targetDescriptorSchema = external_exports.object({
   requiresConfirmation: external_exports.boolean().optional(),
   opensModal: external_exports.string().optional(),
   opensBottomSheet: external_exports.string().optional(),
-  sourceComponent: external_exports.string().optional()
+  sourceComponent: external_exports.string().optional(),
+  origin: targetOriginSchema.optional()
 }).passthrough();
 var flowStepDescriptorSchema = external_exports.object({
-  type: external_exports.enum(["navigate", "fill", "press", "select", "toggle", "wait", "confirm", "choose-list-item"]).or(external_exports.string().min(1).max(60)),
+  type: external_exports.enum([
+    "navigate",
+    "fill",
+    "press",
+    "select",
+    "toggle",
+    "wait",
+    "confirm",
+    "choose-list-item"
+  ]).or(external_exports.string().min(1).max(60)),
   target: external_exports.string().optional(),
   label: external_exports.string().optional(),
   description: external_exports.string().optional(),
@@ -9020,6 +9437,15 @@ var mfaRegenerateRecoveryCodesSchema = external_exports.object({
   password: external_exports.string().min(1, "Password is required"),
   code: totpCodeSchema
 });
+var deleteAccountSchema = external_exports.object({
+  password: external_exports.string().min(1, "Password is required"),
+  code: totpCodeSchema.optional(),
+  recoveryCode: recoveryCodeSchema.optional(),
+  confirm: external_exports.literal("DELETE MY ACCOUNT")
+}).refine((v) => !(v.code && v.recoveryCode), {
+  message: "Provide either a TOTP code or a recovery code, not both",
+  path: ["code"]
+});
 var createProjectSchema = external_exports.object({
   name: external_exports.string().min(1).max(100),
   description: external_exports.string().max(500).optional(),
@@ -9055,6 +9481,7 @@ var uploadMCPDocumentSchema = external_exports.object({
   content: external_exports.record(external_exports.unknown())
 });
 var apiKeyScopeSchema = external_exports.enum(["sdk", "operator"]);
+var apiKeyEnvironmentSchema = external_exports.enum(["test", "live"]);
 var createApiKeySchema = external_exports.object({
   name: external_exports.string().min(1).max(100),
   // Required for `sdk` (default), forbidden/ignored for `operator` —
@@ -9062,6 +9489,7 @@ var createApiKeySchema = external_exports.object({
   // missing scope still validates as the pre-existing SDK shape.
   projectId: external_exports.string().min(1).optional(),
   scope: apiKeyScopeSchema.default("sdk"),
+  environment: apiKeyEnvironmentSchema.optional(),
   expiresAt: external_exports.string().datetime().optional()
 }).refine((v) => v.scope !== "sdk" || !!v.projectId, {
   message: 'projectId is required for scope "sdk"',
@@ -9069,13 +9497,23 @@ var createApiKeySchema = external_exports.object({
 });
 var boundedString = (max) => external_exports.string().max(max);
 var clientPlatformSchema = external_exports.enum(["react-native", "web", "android", "ios"]).or(external_exports.string().min(1).max(40));
+var identityProvenanceSchema = external_exports.enum(["declared", "derived", "positional"]).or(external_exports.string().min(1).max(40));
 var snapshotInputSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   value: boundedString(4096).optional(),
   placeholder: boundedString(300).optional(),
   editable: external_exports.boolean().optional(),
   secure: external_exports.boolean().optional(),
+  submitsOnReturn: external_exports.boolean().optional(),
   type: boundedString(40).optional(),
   required: external_exports.boolean().optional(),
   invalid: external_exports.boolean().optional(),
@@ -9083,6 +9521,14 @@ var snapshotInputSchema = external_exports.object({
 }).passthrough();
 var snapshotButtonSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   disabled: external_exports.boolean().optional(),
   inModal: external_exports.boolean().optional(),
@@ -9092,12 +9538,28 @@ var snapshotButtonSchema = external_exports.object({
 }).passthrough();
 var snapshotToggleSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   value: external_exports.boolean().optional(),
   inModal: external_exports.boolean().optional()
 }).passthrough();
 var snapshotSliderSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   value: external_exports.number().finite().optional(),
   min: external_exports.number().finite().optional(),
@@ -9138,6 +9600,26 @@ var snapshotListSchema = external_exports.object({
   // should chase, and the relay only reads a known subset.
   items: external_exports.array(external_exports.record(external_exports.unknown())).max(500).optional()
 }).passthrough();
+var snapshotNativeDialogSchema = external_exports.object({
+  id: boundedString(160),
+  title: boundedString(300).optional(),
+  message: boundedString(2e3).optional(),
+  buttons: external_exports.array(
+    external_exports.object({
+      label: boundedString(160),
+      style: external_exports.enum(["default", "cancel", "destructive"]).optional()
+    }).passthrough()
+  ).max(10)
+}).passthrough();
+var snapshotScrollableSchema = external_exports.object({
+  id: boundedString(160),
+  containerType: boundedString(60).optional(),
+  label: boundedString(300).optional(),
+  scrollOffsetY: external_exports.number().finite().optional(),
+  canScrollUp: external_exports.boolean().optional(),
+  canScrollDown: external_exports.boolean().optional(),
+  horizontal: external_exports.boolean().optional()
+}).passthrough();
 var snapshotChoiceGroupSchema = external_exports.object({
   index: external_exports.number().int().optional(),
   id: boundedString(160).optional(),
@@ -9154,6 +9636,14 @@ var snapshotElementSchema = external_exports.object({
   disabled: external_exports.boolean().optional(),
   selected: external_exports.boolean().optional(),
   source: boundedString(40).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   targetId: boundedString(160).optional(),
   listContext: external_exports.record(external_exports.unknown()).optional(),
   inModal: external_exports.boolean().optional()
@@ -9170,7 +9660,34 @@ var agentSnapshotSchema = external_exports.object({
   modalOpen: external_exports.boolean().optional(),
   lists: external_exports.array(snapshotListSchema).max(100).optional(),
   choiceGroups: external_exports.array(snapshotChoiceGroupSchema).max(100).optional(),
-  elements: external_exports.array(snapshotElementSchema).max(1e3).optional()
+  scrollables: external_exports.array(snapshotScrollableSchema).max(20).optional(),
+  nativeDialog: snapshotNativeDialogSchema.optional(),
+  elements: external_exports.array(snapshotElementSchema).max(1e3).optional(),
+  /**
+   * The client clamped this observation to the caps above and lost
+   * data doing it (`clampSnapshotToWireLimits` in
+   * `@appilots/client-core`). Read by the prompt serializer so the
+   * model is told the view is partial — a screen truncated at 500
+   * texts must not be read as a screen that only has 500 things on
+   * it. Optional: older SDKs never clamp and never send it.
+   */
+  truncated: external_exports.boolean().optional(),
+  /**
+   * How many of this screen's controls the client could name, split by
+   * `identityProvenance`. Diagnostic only — the relay never grounds an
+   * action on it — but it is the number that says whether an app needs
+   * annotating, and comparing it between a debug and a release build is
+   * the first direct measurement of what minification costs the agent.
+   */
+  stats: external_exports.object({
+    visitedFibers: external_exports.number().int().nonnegative().optional(),
+    skippedHidden: external_exports.number().int().nonnegative().optional(),
+    identity: external_exports.object({
+      declared: external_exports.number().int().nonnegative().optional(),
+      derived: external_exports.number().int().nonnegative().optional(),
+      positional: external_exports.number().int().nonnegative().optional()
+    }).passthrough().optional()
+  }).passthrough().optional()
 }).passthrough();
 var agentContextSchema = external_exports.object({
   /**
@@ -9220,6 +9737,19 @@ var agentContextSchema = external_exports.object({
   ).max(200).optional(),
   loadingPending: external_exports.boolean().optional()
 }).passthrough();
+var introspectionFailureReasonSchema = external_exports.enum([
+  "sentinel-missing-internals",
+  "never-mounted",
+  "render-crashed",
+  "names-mangled",
+  "walk-recognized-nothing"
+]);
+var introspectionDiagnosticsSchema = external_exports.object({
+  captured: external_exports.boolean(),
+  failureReason: introspectionFailureReasonSchema.nullish(),
+  reactVersion: boundedString(32).nullish(),
+  failureCount: external_exports.number().int().min(0).max(1e6).optional()
+});
 var sendMessageSchema = external_exports.object({
   content: external_exports.string().min(1).max(4096),
   sessionId: external_exports.string().optional(),
@@ -9229,7 +9759,20 @@ var sendMessageSchema = external_exports.object({
    * the active MCP doc and emits `mcp_version_mismatch` telemetry when
    * they differ. Optional — older SDKs simply skip the check.
    */
-  mcpVersion: external_exports.string().max(64).optional()
+  mcpVersion: external_exports.string().max(64).optional(),
+  /**
+   * SDK-side introspection health. Only sent when it FAILED — a client
+   * that reached the React tree omits the field entirely, so the happy
+   * path costs nothing on the wire.
+   *
+   * Without this, an app whose introspection is dead sends a snapshot
+   * that is empty but perfectly well-formed, indistinguishable from a
+   * genuinely empty screen. The server emits
+   * `introspection_unavailable` so the failure is visible to us instead
+   * of waiting for a bug report. Optional — older SDKs simply never
+   * send it.
+   */
+  introspection: introspectionDiagnosticsSchema.optional()
 });
 var agentActionTypeSchema = external_exports.enum([
   "navigate",
@@ -9240,11 +9783,22 @@ var agentActionTypeSchema = external_exports.enum([
   "custom"
 ]);
 var navigationPayloadSchema = external_exports.object({
-  screenName: external_exports.string().min(1),
+  // Optional ONLY so `goBack` can exist (#398): it returns to whatever
+  // is beneath on the stack and has no destination to name. Every other
+  // action is still required to carry one — enforced by the refine
+  // below rather than by the field, so the error names the real problem
+  // ("navigate needs a screenName") instead of a missing key.
+  screenName: external_exports.string().min(1).optional(),
   params: external_exports.record(external_exports.unknown()).optional(),
   navigationAction: external_exports.enum(["push", "navigate", "replace", "goBack", "reset"]).default("navigate").optional(),
   path: external_exports.array(external_exports.string().min(1)).optional()
-}).passthrough();
+}).passthrough().refine(
+  (payload) => payload.navigationAction === "goBack" || typeof payload.screenName === "string" && payload.screenName.length > 0,
+  {
+    message: 'screenName is required for every navigationAction except "goBack"',
+    path: ["screenName"]
+  }
+);
 var formFillFieldSchema = external_exports.object({
   fieldId: external_exports.string().min(1),
   fieldType: external_exports.enum(["text", "select", "toggle", "date", "number", "custom"]).default("text").optional(),
@@ -9578,6 +10132,8 @@ var sandboxObservationSchema = external_exports.object({
   inputs: external_exports.array(
     external_exports.object({
       id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
       label: external_exports.string().max(200).optional(),
       value: external_exports.string().max(2e3).optional(),
       disabled: external_exports.boolean().optional(),
@@ -9591,6 +10147,8 @@ var sandboxObservationSchema = external_exports.object({
   buttons: external_exports.array(
     external_exports.object({
       id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
       label: external_exports.string().max(200).optional(),
       disabled: external_exports.boolean().optional(),
       /** Risk metadata (e.g. "high") the SDK forwards for danger UI. */
@@ -9612,6 +10170,8 @@ var sandboxObservationSchema = external_exports.object({
   sliders: external_exports.array(
     external_exports.object({
       id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
       label: external_exports.string().max(200).optional(),
       value: external_exports.number().finite().optional(),
       min: external_exports.number().finite().optional(),
@@ -9641,6 +10201,44 @@ var sandboxObservationSchema = external_exports.object({
       ).max(200).optional()
     }).passthrough()
   ).max(20).optional(),
+  /**
+   * Toggles exactly as the SDK snapshot reports them (#390).
+   *
+   * Their absence is why `generality-component-control-smarthome`
+   * came back `errored` with a 422 instead of measuring anything:
+   * this schema is `.strict()`, so a scenario that declares a switch
+   * is rejected before the agent is ever asked. Which means the
+   * corpus could not express the single control behind failure 02 of
+   * the functional audit — "disable an agent; the switch never
+   * moves". The one defect the eval most needed to catch was the one
+   * shape it could not describe.
+   */
+  toggles: external_exports.array(
+    external_exports.object({
+      id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
+      label: external_exports.string().max(200).optional(),
+      value: external_exports.boolean().optional(),
+      disabled: external_exports.boolean().optional()
+    })
+  ).max(100).optional(),
+  /**
+   * The interaction graph — the `el:*` ids the prompt tells the model
+   * to prefer over ordinal handles. Passthrough per entry for the
+   * same reason `lists` is: the SDK adds fields faster than this
+   * schema should chase them.
+   */
+  elements: external_exports.array(
+    external_exports.object({
+      id: external_exports.string().max(160),
+      role: external_exports.string().max(40).optional(),
+      label: external_exports.string().max(300).optional()
+    }).passthrough()
+  ).max(500).optional(),
+  /** Screen-level state the relay renders and branches on. */
+  loading: external_exports.boolean().optional(),
+  modalOpen: external_exports.boolean().optional(),
   extra: external_exports.record(external_exports.unknown()).optional()
 }).strict();
 var sandboxRunRequestSchema = external_exports.object({
@@ -9681,13 +10279,29 @@ var sandboxRunRequestSchema = external_exports.object({
    * heuristics, forces tool choice when the last user message carries a
    * failure marker). Only meaningful alongside `history`.
    */
-  isRecoveryHop: external_exports.boolean().optional()
+  isRecoveryHop: external_exports.boolean().optional(),
+  /**
+   * Run this call against the application structure supplied here
+   * instead of the project's active MCP document.
+   *
+   * Sandbox-only, and the relay honours it only on a `dryRun` call —
+   * see `resolveMcpOverride` in apps/api. It exists because the eval
+   * corpus could otherwise only ever describe ONE app: every scenario
+   * resolves to the same seeded project, so every navigate destination,
+   * every screen title and every bit of domain priming in the prompt
+   * came from the same vehicle-management demo. A suite that can only
+   * pose questions about one app cannot measure whether the agent works
+   * on another one.
+   *
+   * Deliberately loose (`z.record`): the MCP document's shape is owned
+   * by the generator, and pinning it here would turn every additive
+   * generator change into a 422 in the sandbox.
+   */
+  applicationStructure: external_exports.record(external_exports.unknown()).optional()
 }).strict();
 var relayDiagnosticsSchema = external_exports.object({
   unverifiedTargets: external_exports.array(external_exports.string()),
-  guardsFired: external_exports.array(
-    external_exports.object({ guard: external_exports.string(), detail: external_exports.string().optional() })
-  ),
+  guardsFired: external_exports.array(external_exports.object({ guard: external_exports.string(), detail: external_exports.string().optional() })),
   repairMode: external_exports.enum(["repair", "strict", "disabled"]),
   promptVersion: external_exports.string(),
   // Defaulted for producers that predate the field: before it existed
@@ -9946,6 +10560,30 @@ var identifyUserSchema = external_exports.object({
   name: external_exports.string().min(1).max(200).optional(),
   identifiers: endUserIdentifiersSchema.optional()
 });
+var MAX_EXTERNAL_USER_ID_LENGTH = 128;
+function normalizeExternalUserId(value) {
+  let raw;
+  if (typeof value === "string") raw = value;
+  else if (typeof value === "number" && Number.isFinite(value)) raw = String(value);
+  else return void 0;
+  const trimmed = raw.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.length > MAX_EXTERNAL_USER_ID_LENGTH) return void 0;
+  return trimmed;
+}
+var MAX_DEVICE_INFO_BYTES = 4096;
+var sessionDeviceInfoSchema = external_exports.object({
+  platform: external_exports.string().max(64).optional(),
+  osVersion: external_exports.string().max(64).optional(),
+  appVersion: external_exports.string().max(64).optional(),
+  sdkVersion: external_exports.string().max(64).optional()
+}).passthrough().refine((info2) => JSON.stringify(info2).length <= MAX_DEVICE_INFO_BYTES, {
+  message: `device_info exceeds ${MAX_DEVICE_INFO_BYTES} bytes`
+});
+var createAgentSessionSchema = external_exports.object({
+  userId: external_exports.preprocess(normalizeExternalUserId, external_exports.string().optional()),
+  deviceInfo: sessionDeviceInfoSchema.optional().catch(void 0)
+});
 var upsertEndUserSchema = external_exports.object({
   projectId: external_exports.string().min(1).max(64),
   externalId: external_exports.string().min(1).max(128),
@@ -9969,14 +10607,16 @@ async function loadManifest(rootDir, manifestPath) {
     if (error2?.code === "ENOENT") {
       return { manifest: null, resolvedPath };
     }
-    throw new Error(`Failed to read Appilots manifest at ${resolvedPath}: ${error2?.message ?? String(error2)}`);
+    throw new Error(
+      `Failed to read Appilots manifest at ${resolvedPath}: ${stringifyUnknown(error2)}`
+    );
   }
   let parsedJson;
   try {
     parsedJson = JSON.parse(raw);
   } catch (error2) {
     throw new Error(
-      `Appilots manifest at ${resolvedPath} is not valid JSON: ${error2 instanceof Error ? error2.message : String(error2)}`
+      `Appilots manifest at ${resolvedPath} is not valid JSON: ${stringifyUnknown(error2)}`
     );
   }
   const result = manifestSchema.safeParse(parsedJson);
@@ -9990,11 +10630,47 @@ Each entry in "screens" must match the ScreenDescriptor shape (see docs/platform
   }
   return { manifest: result.data, resolvedPath };
 }
+function mergeScreen(base, declared) {
+  const fields = { ...base };
+  for (const [key, value] of Object.entries(declared)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    fields[key] = value;
+  }
+  const merged = fields;
+  merged.targets = mergeById(base.targets, markManifestOrigin(declared.targets));
+  merged.actions = mergeById(base.actions, declared.actions) ?? [];
+  if (base.agentHints || declared.agentHints) {
+    merged.agentHints = { ...base.agentHints, ...declared.agentHints };
+  }
+  return merged;
+}
+function mergeById(base, overlay) {
+  if (!overlay || overlay.length === 0) return base;
+  if (!base || base.length === 0) return overlay;
+  const byId = /* @__PURE__ */ new Map();
+  for (const entry of base) byId.set(entry.id, entry);
+  for (const entry of overlay) {
+    const existing = byId.get(entry.id);
+    byId.set(entry.id, existing ? { ...existing, ...entry } : entry);
+  }
+  return Array.from(byId.values());
+}
+function markManifestOrigin(targets) {
+  if (!targets || targets.length === 0) return targets;
+  return targets.map((target) => ({ origin: "manifest", ...target }));
+}
 function mergeManifestScreens(analyzerScreens, manifestScreens) {
   if (!manifestScreens || manifestScreens.length === 0) return analyzerScreens;
   const byName = /* @__PURE__ */ new Map();
   for (const screen of analyzerScreens) byName.set(screen.name, screen);
-  for (const screen of manifestScreens) byName.set(screen.name, screen);
+  for (const declared of manifestScreens) {
+    const base = byName.get(declared.name);
+    byName.set(
+      declared.name,
+      base ? mergeScreen(base, declared) : { ...declared, targets: markManifestOrigin(declared.targets) }
+    );
+  }
   return Array.from(byName.values());
 }
 function mergeManifestNavigation(analyzerNavigation, manifestNavigation) {
@@ -10069,7 +10745,12 @@ var MCPGenerator = class _MCPGenerator {
     }
     const mergedScreens = mergeManifestScreens(analyzed.screens, manifest?.screens);
     const navigation = mergeManifestNavigation(analyzed.navigation, manifest?.navigation);
-    const agentReadyScreens = mergedScreens.map(enrichScreenForAgent);
+    const agentReadyScreens = mergedScreens.map(
+      (screen) => enrichScreenForAgent({
+        ...screen,
+        filePath: screen.filePath ? import_node_path3.default.relative(this.generatorConfig.rootDir, screen.filePath) : screen.filePath
+      })
+    );
     const projectInfo = await this.getProjectInfo();
     const projectName = projectInfo.name;
     console.log(`[MCPGenerator] Project name: ${projectName}`);
@@ -10092,10 +10773,7 @@ var MCPGenerator = class _MCPGenerator {
     };
     const serialized = JSON.stringify(document, null, 2);
     const checksum = this.calculateChecksum(serialized);
-    const filePath = import_node_path3.default.resolve(
-      outputDir,
-      `mcp-document.${this.options.format}`
-    );
+    const filePath = import_node_path3.default.resolve(outputDir, `mcp-document.${this.options.format}`);
     await (0, import_promises4.writeFile)(filePath, serialized, "utf-8");
     console.log(`[MCPGenerator] Document written to: ${filePath}`);
     const checksumFilePath = import_node_path3.default.resolve(outputDir, ".appilots-checksum");
@@ -10211,14 +10889,136 @@ function reportMetadataLint(document, strict) {
   }
 }
 
-// src/cli/commands/sync.ts
-function syncCommand() {
-  return new import_commander2.Command("sync").description("Analyze project and sync MCP documents with Appilots").option("--verbose", "Enable verbose logging", false).option("--force", "Force upload even if nothing changed", false).option("--api-key <key>", "Appilots API key (overrides .appilotsrc and APPILOTS_API_KEY)").option("--project-id <id>", "Project ID (overrides .appilotsrc and APPILOTS_PROJECT_ID)").option("--server <url>", "Appilots server URL (overrides .appilotsrc and APPILOTS_SERVER_URL)").option("--json", "Output a machine-readable JSON result (implies --quiet)", false).option("--quiet", "Suppress banner and informational output", false).option("--strict-metadata", "Fail when mutating actions are missing effect/riskLevel metadata", false).action(async (options) => {
-    if (options.json) setLogMode("json");
-    else if (options.quiet) setLogMode("quiet");
-    try {
+// src/cli/utils/remote-drift.ts
+var import_node_fs = require("fs");
+var import_node_path4 = require("path");
+var STUB_RATIO = 0.5;
+function compareWithRemote(local, remote) {
+  if (remote.screensCount === local.screens) return null;
+  return {
+    localScreens: local.screens,
+    remoteScreens: remote.screensCount,
+    remoteId: remote.id,
+    severe: local.screens > 0 && remote.screensCount <= local.screens * STUB_RATIO
+  };
+}
+function readLocalDocumentSummary(outputDir) {
+  try {
+    const raw = (0, import_node_fs.readFileSync)((0, import_node_path4.join)(outputDir, "mcp-document.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.metadata?.totalScreens !== "number") return null;
+    return { screens: parsed.metadata.totalScreens };
+  } catch {
+    return null;
+  }
+}
+function reportRemoteDrift(drift, options = {}) {
+  if (!drift.severe) {
+    info(
+      `Server's active document differs from what was just generated (active: ${drift.remoteId}, ${drift.remoteScreens} screens).`
+    );
+    return;
+  }
+  warn(
+    `The agent is ${options.uploadFailed ? "still " : ""}running on a ${drift.remoteScreens}-screen document while this app has ${drift.localScreens} screens.`
+  );
+  info(`  Active on server: ${drift.remoteId} (${drift.remoteScreens} screens)`);
+  info(`  Just generated:   ${drift.localScreens} screens`);
+  info("");
+  info("While a document that small is active the agent cannot see the other");
+  info("screens, and missions that need them fail in ways that read as model");
+  info("errors. The usual causes: an older version activated from the");
+  info("dashboard, a sync that went to a different server, or a database");
+  info("seeded before the seed learned to refuse partial documents.");
+  info("");
+  if (options.uploadFailed) {
+    info("Nothing was uploaded just now, so this is unchanged. Fix the error");
+    info("above and run sync again \u2014 e2e runs before that will fail on");
+    info("navigation, not on anything the model did.");
+  } else {
+    info("Uploading now replaces it.");
+  }
+}
+
+// src/cli/utils/upload-failure.ts
+function explainUploadFailure(failure, serverUrl) {
+  const status = failure.errorStatus ?? 0;
+  if (status === 401) {
+    info("");
+    info("`sync` authenticates with the project API key (`ak_\u2026`) \u2014 the same key");
+    info("the SDK uses. Check that it is the key for THIS project, is still");
+    info("active, and reaches the server you meant:");
+    info(`  Server: ${serverUrl ?? "(default)"}`);
+    info("Set it in .appilotsrc (`apiKey`), via APPILOTS_API_KEY, or --api-key.");
+    info("");
+    info("A dashboard login token will not work here and is not needed: the CLI");
+    info("talks to /cli/sync, not the dashboard's /mcp-documents.");
+    return;
+  }
+  if (failure.errorCode === "WORKSPACE_INACTIVE") {
+    info("");
+    info("The workspace is deactivated. Re-activate it in the dashboard");
+    info("(Settings \u2192 Workspace) and run sync again.");
+    return;
+  }
+  if (status === 404) {
+    info("");
+    info(`No /cli/sync at ${serverUrl ?? "(default)"} \u2014 check serverUrl points at`);
+    info("an Appilots API (and one recent enough to serve the CLI routes).");
+    return;
+  }
+  if (status === 422) {
+    info("");
+    info("The server rejected the document itself. Inspect what was generated:");
+    info("  .appilots/mcp-document.json");
+    return;
+  }
+  if (status >= 500) {
+    info("");
+    info("The server failed to process the upload. It was retried already \u2014");
+    info("if it persists, the API logs hold the matching request id.");
+  }
+}
+
+// src/cli/utils/empty-document.ts
+function assertDocumentHasScreens(document, options = {}) {
+  if ((document.metadata?.totalScreens ?? 0) > 0) return;
+  if (options.allowEmpty) {
+    info("No screens found, continuing because --allow-empty was passed.");
+    return;
+  }
+  error("No screens found \u2014 this application map would give the agent nothing to navigate.");
+  info("");
+  info("The analyzer looks for React Navigation: a <NavigationContainer> and");
+  info("<Stack.Screen> / <Tab.Screen> declarations. It found none.");
+  info("");
+  info("The two usual causes:");
+  info("  \u2022 The app uses Expo Router (or another file-based router). It is the");
+  info("    default for `npx create-expo-app` and the analyzer cannot read it.");
+  info("  \u2022 The screens live outside the analyzed paths \u2014 check `include`,");
+  info("    `exclude` and `screenPatterns` in your Appilots config.");
+  info("");
+  info("The escape hatch, which works for any router: declare your screens in");
+  info("an `appilots.manifest.json` at the project root. Its screens are merged");
+  info("on top of whatever the analyzer found, so a fully declared app needs no");
+  info("React Navigation at all. See the CLI docs for the shape.");
+  info("");
+  info("If an empty map really is what you want, pass --allow-empty.");
+  process.exit(1);
+}
+
+// src/cli/commands/sync.ts
+function syncCommand() {
+  return new import_commander2.Command("sync").description("Analyze project and sync MCP documents with Appilots").option("--verbose", "Enable verbose logging", false).option("--force", "Force upload even if nothing changed", false).option("--api-key <key>", "Appilots API key (overrides .appilotsrc and APPILOTS_API_KEY)").option("--project-id <id>", "Project ID (overrides .appilotsrc and APPILOTS_PROJECT_ID)").option("--server <url>", "Appilots server URL (overrides .appilotsrc and APPILOTS_SERVER_URL)").option("--json", "Output a machine-readable JSON result (implies --quiet)", false).option("--quiet", "Suppress banner and informational output", false).option(
+    "--strict-metadata",
+    "Fail when mutating actions are missing effect/riskLevel metadata",
+    false
+  ).option("--allow-empty", "Do not fail when the application map has zero screens", false).action(async (options) => {
+    if (options.json) setLogMode("json");
+    else if (options.quiet) setLogMode("quiet");
+    try {
       banner();
-      const loaded = loadConfig();
+      const loaded = loadConfig(warn);
       const apiKey = options.apiKey || loaded?.apiKey;
       if (!apiKey) {
         error("No .appilotsrc configuration found");
@@ -10229,7 +11029,7 @@ function syncCommand() {
         return;
       }
       const config = {
-        serverUrl: "http://localhost:4000",
+        serverUrl: DEFAULT_SERVER_URL,
         outputDir: ".appilots",
         ...loaded,
         apiKey,
@@ -10243,7 +11043,7 @@ function syncCommand() {
       const outputDir = config.outputDir || ".appilots";
       let previousChecksum = "";
       try {
-        const checksumPath = (0, import_node_path4.join)(outputDir, ".appilots-checksum");
+        const checksumPath = (0, import_node_path5.join)(outputDir, ".appilots-checksum");
         previousChecksum = (await (0, import_promises5.readFile)(checksumPath, "utf-8")).trim();
       } catch {
       }
@@ -10264,22 +11064,32 @@ function syncCommand() {
       });
       const output = await generator.generate();
       spinner.stop();
+      assertDocumentHasScreens(output.document, {
+        rootDir: process.cwd(),
+        allowEmpty: Boolean(options.allowEmpty)
+      });
       success(
         `Found ${output.document.metadata.totalScreens} screens, ${output.document.metadata.totalForms} forms, ${output.document.metadata.totalActions} actions`
       );
       reportMetadataLint(output.document, Boolean(options.strictMetadata));
+      spinner = createSpinner("Checking remote status...");
+      spinner.start();
+      const remote = await apiClient.status();
+      spinner.stop();
+      const remoteActive = remote.error ? null : remote.activeMcp ?? null;
+      const drift = remoteActive ? compareWithRemote({ screens: output.document.metadata.totalScreens }, remoteActive) : null;
       if (!options.force && previousChecksum && previousChecksum === output.checksum) {
-        spinner = createSpinner("Checking remote status...");
-        spinner.start();
-        const status = await apiClient.status();
-        spinner.stop();
-        if (status.error) {
-          warn(`Could not verify remote: ${status.error}`);
+        if (remote.error) {
+          warn(`Could not verify remote: ${remote.error}`);
+          info("Uploading anyway...");
+        } else if (remoteActive) {
+          if (!drift) {
+            success("Already up to date (no local or remote changes)");
+            jsonOutput({ success: true, unchanged: true, checksum: output.checksum });
+            return;
+          }
+          reportRemoteDrift(drift);
           info("Uploading anyway...");
-        } else if (status.activeMcp) {
-          success("Already up to date (no local or remote changes)");
-          jsonOutput({ success: true, unchanged: true, checksum: output.checksum });
-          return;
         }
       }
       spinner = createSpinner("Uploading to Appilots...");
@@ -10292,13 +11102,33 @@ function syncCommand() {
       spinner.stop();
       if (!syncResult.success) {
         error(`Sync failed: ${syncResult.error}`);
-        jsonOutput({ success: false, error: syncResult.error });
+        hintUnreachableServer(config.serverUrl, syncResult.error);
+        explainUploadFailure(syncResult, config.serverUrl);
+        if (drift?.severe) {
+          reportRemoteDrift(drift, { uploadFailed: true });
+        }
+        jsonOutput({
+          success: false,
+          error: syncResult.error,
+          errorCode: syncResult.errorCode,
+          errorStatus: syncResult.errorStatus,
+          activeDocument: remoteActive,
+          drift
+        });
         process.exit(1);
       }
       if (syncResult.unchanged && !options.force) {
         success("Already up to date on server");
+        if (syncResult.activated) {
+          info(`Re-activated document ${syncResult.id} (it was stored but not active).`);
+        }
       } else {
         success("Successfully synced MCP document");
+        if (drift?.severe) {
+          info(
+            `Replaced the ${drift.remoteScreens}-screen document that was active (${drift.remoteId}) \u2014 the agent could not see the other ${drift.localScreens - drift.remoteScreens} screens until now.`
+          );
+        }
         info(`Document ID: ${syncResult.id}`);
         info(`Checksum: ${syncResult.checksum}`);
         if (config.projectId) {
@@ -10328,8 +11158,8 @@ function syncCommand() {
         actionsCount: syncResult.actionsCount ?? output.document.metadata.totalActions
       });
     } catch (err) {
-      error(`Sync failed: ${err instanceof Error ? err.message : String(err)}`);
-      jsonOutput({ success: false, error: err instanceof Error ? err.message : String(err) });
+      error(`Sync failed: ${stringifyUnknown(err)}`);
+      jsonOutput({ success: false, error: stringifyUnknown(err) });
       if (options.verbose) {
         console.error(err);
       }
@@ -10340,12 +11170,12 @@ function syncCommand() {
 
 // src/cli/commands/watch.ts
 var import_commander3 = require("commander");
-var import_node_fs = require("fs");
+var import_node_fs2 = require("fs");
 function watchCommand() {
   return new import_commander3.Command("watch").description("Watch project for changes and auto-sync MCP documents").option("--verbose", "Enable verbose logging", false).action(async (options) => {
     try {
       banner();
-      const config = loadConfig();
+      const config = loadConfig(warn);
       if (!config) {
         error("No .appilotsrc configuration found");
         info("Run: appilots init --api-key <your-key>");
@@ -10374,7 +11204,10 @@ function watchCommand() {
       };
       const generator = new MCPGenerator(generatorConfig);
       const initialOutput = await generator.generate();
-      const initialSync = await apiClient.sync(initialOutput.document, initialOutput.document.version);
+      const initialSync = await apiClient.sync(
+        initialOutput.document,
+        initialOutput.document.version
+      );
       if (!initialSync.success) {
         error(`Initial sync failed: ${initialSync.error}`);
         process.exit(1);
@@ -10384,45 +11217,41 @@ function watchCommand() {
       dim("Press Ctrl+C to stop\n");
       let debounceTimer = null;
       const DEBOUNCE_MS = 500;
-      const watcher = (0, import_node_fs.watch)(
-        process.cwd(),
-        { recursive: true },
-        async (eventType, filename) => {
-          if (!filename) return;
-          if (filename.startsWith(".") || filename.includes("node_modules") || filename.includes(config.outputDir || ".appilots")) {
-            return;
-          }
-          if (debounceTimer) {
-            clearTimeout(debounceTimer);
-          }
-          debounceTimer = setTimeout(async () => {
-            try {
-              if (options.verbose) {
-                info(`Change detected: ${filename}`);
-              }
-              const spinner = createSpinner("Re-analyzing project...");
-              spinner.start();
-              const newGenerator = new MCPGenerator(generatorConfig);
-              const output = await newGenerator.generate();
-              spinner.text = "Uploading changes...";
-              const syncResult = await apiClient.sync(output.document, output.document.version);
-              spinner.stop();
-              if (!syncResult.success) {
-                error(`Sync failed: ${syncResult.error}`);
-              } else if (syncResult.unchanged) {
-                info("Changes synced (no content changes detected)");
-              } else {
-                success("Changes synced successfully");
-                info(
-                  `${output.document.metadata.totalScreens} screens, ${output.document.metadata.totalForms} forms, ${output.document.metadata.totalActions} actions`
-                );
-              }
-            } catch (err) {
-              error(`Watch sync failed: ${err instanceof Error ? err.message : String(err)}`);
-            }
-          }, DEBOUNCE_MS);
+      const watcher = (0, import_node_fs2.watch)(process.cwd(), { recursive: true }, async (eventType, filename) => {
+        if (!filename) return;
+        if (filename.startsWith(".") || filename.includes("node_modules") || filename.includes(config.outputDir || ".appilots")) {
+          return;
         }
-      );
+        if (debounceTimer) {
+          clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(async () => {
+          try {
+            if (options.verbose) {
+              info(`Change detected: ${filename}`);
+            }
+            const spinner = createSpinner("Re-analyzing project...");
+            spinner.start();
+            const newGenerator = new MCPGenerator(generatorConfig);
+            const output = await newGenerator.generate();
+            spinner.text = "Uploading changes...";
+            const syncResult = await apiClient.sync(output.document, output.document.version);
+            spinner.stop();
+            if (!syncResult.success) {
+              error(`Sync failed: ${syncResult.error}`);
+            } else if (syncResult.unchanged) {
+              info("Changes synced (no content changes detected)");
+            } else {
+              success("Changes synced successfully");
+              info(
+                `${output.document.metadata.totalScreens} screens, ${output.document.metadata.totalForms} forms, ${output.document.metadata.totalActions} actions`
+              );
+            }
+          } catch (err) {
+            error(`Watch sync failed: ${stringifyUnknown(err)}`);
+          }
+        }, DEBOUNCE_MS);
+      });
       process.on("SIGINT", () => {
         info("Stopping watcher...");
         watcher.close();
@@ -10432,7 +11261,7 @@ function watchCommand() {
         process.exit(0);
       });
     } catch (err) {
-      error(`Watch failed: ${err instanceof Error ? err.message : String(err)}`);
+      error(`Watch failed: ${stringifyUnknown(err)}`);
       process.exit(1);
     }
   });
@@ -10441,7 +11270,11 @@ function watchCommand() {
 // src/cli/commands/generate.ts
 var import_commander4 = require("commander");
 function generateCommand() {
-  return new import_commander4.Command("generate").description("Generate MCP documents from project source (local only)").option("-o, --output <path>", "Output directory for MCP documents", ".appilots").option("-f, --format <format>", "Output format (only json supported)", "json").option("--strict-metadata", "Fail when mutating actions are missing effect/riskLevel metadata", false).action(async (options) => {
+  return new import_commander4.Command("generate").description("Generate MCP documents from project source (local only)").option("-o, --output <path>", "Output directory for MCP documents", ".appilots").option("-f, --format <format>", "Output format (only json supported)", "json").option(
+    "--strict-metadata",
+    "Fail when mutating actions are missing effect/riskLevel metadata",
+    false
+  ).option("--allow-empty", "Do not fail when the application map has zero screens", false).action(async (options) => {
     try {
       banner();
       if (options.format && options.format !== "json") {
@@ -10452,7 +11285,7 @@ function generateCommand() {
       spinner.start();
       let loaded = null;
       try {
-        loaded = loadConfig();
+        loaded = loadConfig(warn);
       } catch {
         loaded = null;
       }
@@ -10465,6 +11298,10 @@ function generateCommand() {
       });
       const output = await generator.generate();
       spinner.stop();
+      assertDocumentHasScreens(output.document, {
+        rootDir: process.cwd(),
+        allowEmpty: Boolean(options.allowEmpty)
+      });
       success(
         `Generated MCP document with ${output.document.metadata.totalScreens} screens, ${output.document.metadata.totalForms} forms, ${output.document.metadata.totalActions} actions`
       );
@@ -10472,21 +11309,761 @@ function generateCommand() {
       info(`Checksum: ${output.checksum}`);
       reportMetadataLint(output.document, Boolean(options.strictMetadata));
     } catch (err) {
-      error(`Generation failed: ${err instanceof Error ? err.message : String(err)}`);
+      error(`Generation failed: ${stringifyUnknown(err)}`);
       process.exit(1);
     }
   });
 }
 
-// src/cli/commands/status.ts
+// src/cli/commands/annotate.ts
+var import_promises6 = require("fs/promises");
+var import_node_path7 = __toESM(require("path"));
 var import_commander5 = require("commander");
+var import_fast_glob6 = __toESM(require("fast-glob"));
+
+// src/annotate/sites.ts
+var import_traverse12 = __toESM(require("@babel/traverse"));
+var t13 = __toESM(require("@babel/types"));
+
+// src/annotate/forwarding.ts
+var import_node_path6 = __toESM(require("path"));
+var import_node_fs3 = require("fs");
+var import_traverse11 = __toESM(require("@babel/traverse"));
+var t12 = __toESM(require("@babel/types"));
+var traverse11 = import_traverse11.default.default ?? import_traverse11.default;
+var RN_TESTID_CARRIERS = /* @__PURE__ */ new Set([
+  "View",
+  "Text",
+  "TextInput",
+  "Image",
+  "ImageBackground",
+  "ScrollView",
+  "FlatList",
+  "SectionList",
+  "VirtualizedList",
+  "TouchableOpacity",
+  "TouchableHighlight",
+  "TouchableWithoutFeedback",
+  "TouchableNativeFeedback",
+  "Pressable",
+  "Button",
+  "Switch",
+  "Modal",
+  "RefreshControl",
+  "ActivityIndicator",
+  "SafeAreaView",
+  "KeyboardAvoidingView",
+  "Slider"
+]);
+function collectImports(ast) {
+  const out = /* @__PURE__ */ new Map();
+  traverse11(ast, {
+    ImportDeclaration(nodePath) {
+      const source = nodePath.node.source.value;
+      for (const spec of nodePath.node.specifiers) {
+        if (t12.isImportSpecifier(spec)) {
+          const imported = t12.isIdentifier(spec.imported) ? spec.imported.name : spec.imported.value;
+          out.set(spec.local.name, { source, local: spec.local.name, imported });
+        } else if (t12.isImportDefaultSpecifier(spec)) {
+          out.set(spec.local.name, { source, local: spec.local.name, imported: "default" });
+        }
+      }
+    }
+  });
+  return out;
+}
+var EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
+function resolveRelativeImport(fromFile, source) {
+  if (!source.startsWith(".")) return void 0;
+  const base = import_node_path6.default.resolve(import_node_path6.default.dirname(fromFile), source);
+  for (const ext of EXTENSIONS) {
+    const candidate = `${base}${ext}`;
+    if ((0, import_node_fs3.existsSync)(candidate)) return candidate;
+  }
+  for (const ext of EXTENSIONS) {
+    const candidate = import_node_path6.default.join(base, `index${ext}`);
+    if ((0, import_node_fs3.existsSync)(candidate)) return candidate;
+  }
+  return void 0;
+}
+var IDENTITY_HOOKS = /* @__PURE__ */ new Set([
+  "useAppilotsTarget",
+  "useAppilotsField",
+  "useAppilotsToggle",
+  "useAppilotsSlider"
+]);
+function inspectModule(file2, exportName, depth = 0) {
+  const none = { forwards: false, derives: false };
+  if (depth > 2) return none;
+  let source;
+  try {
+    source = (0, import_node_fs3.readFileSync)(file2, "utf-8");
+  } catch {
+    return none;
+  }
+  const mentionsIdentity = source.includes("testID") || source.includes("accessibilityLabel") || source.includes("useAppilots") || /\{\s*\.\.\./.test(source);
+  if (!mentionsIdentity && !/export\s*\{[^}]*\}\s*from/.test(source)) return none;
+  let ast;
+  try {
+    ast = parseSource(source);
+  } catch {
+    return none;
+  }
+  let forwards = false;
+  let derives = false;
+  let barrelTarget;
+  traverse11(ast, {
+    // `export { Card } from './Card'` — follow one hop.
+    ExportNamedDeclaration(nodePath) {
+      const from = nodePath.node.source?.value;
+      if (!from) return;
+      const named = nodePath.node.specifiers.some(
+        (spec) => t12.isExportSpecifier(spec) && (t12.isIdentifier(spec.exported) ? spec.exported.name : spec.exported.value) === exportName
+      );
+      if (named) barrelTarget = from;
+    },
+    ExportAllDeclaration(nodePath) {
+      barrelTarget ??= nodePath.node.source.value;
+    },
+    // `interface CardProps { testID?: string }` / `type Props = { testID… }`
+    TSPropertySignature(nodePath) {
+      if (t12.isIdentifier(nodePath.node.key) && nodePath.node.key.name === "testID") forwards = true;
+    },
+    // `function Card({ testID }) {}` — the destructured parameter.
+    ObjectProperty(nodePath) {
+      if (t12.isIdentifier(nodePath.node.key) && nodePath.node.key.name === "testID") forwards = true;
+    },
+    // `<View {...props} />` — anything spread onto JSX carries it along.
+    JSXSpreadAttribute() {
+      forwards = true;
+    },
+    // `testID={`toggle-${id}`}` / `accessibilityLabel={label}` — the
+    // component naming itself from a prop. A STRING literal does not count:
+    // that is one hardcoded name shared by every instance, which is the
+    // duplicate-id problem rather than a solution to it.
+    JSXAttribute(nodePath) {
+      const name = t12.isJSXIdentifier(nodePath.node.name) ? nodePath.node.name.name : "";
+      if (name !== "testID" && name !== "accessibilityLabel") return;
+      const value = nodePath.node.value;
+      if (!t12.isJSXExpressionContainer(value)) return;
+      if (t12.isStringLiteral(value.expression)) return;
+      derives = true;
+    },
+    // `useAppilotsTarget(`${groupId}-${option.value}`, …)`
+    CallExpression(nodePath) {
+      const callee = nodePath.node.callee;
+      if (t12.isIdentifier(callee) && IDENTITY_HOOKS.has(callee.name)) derives = true;
+    }
+  });
+  if (forwards || derives) return { forwards, derives };
+  if (barrelTarget) {
+    const next = resolveRelativeImport(file2, barrelTarget);
+    if (next) return inspectModule(next, exportName, depth + 1);
+  }
+  return none;
+}
+var verdictCache = /* @__PURE__ */ new Map();
+function canCarryTestId(componentName, fromFile, imports) {
+  const origin = imports.get(componentName);
+  if (origin?.source === "react-native") {
+    return RN_TESTID_CARRIERS.has(origin.imported) ? "rn-primitive" : "unverifiable";
+  }
+  const target = origin ? resolveRelativeImport(fromFile, origin.source) : fromFile;
+  if (!target) return "unverifiable";
+  const exportName = origin?.imported ?? componentName;
+  const key = `${target}#${exportName}`;
+  let identity = verdictCache.get(key);
+  if (identity === void 0) {
+    identity = inspectModule(target, exportName);
+    verdictCache.set(key, identity);
+  }
+  if (identity.forwards) return "forwards";
+  if (identity.derives) return "derives";
+  return "swallows";
+}
+function resetForwardingCache() {
+  verdictCache.clear();
+}
+
+// src/annotate/sites.ts
+var traverse12 = import_traverse12.default.default ?? import_traverse12.default;
+var LABEL_PROPS = ["title", "label", "placeholder"];
+var IDENTITY_PROPS = ["testID", "appilotsId", "accessibilityLabel"];
+function kebab(text) {
+  return text.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function verbOf(name) {
+  return kebab(name.replace(/^(handle|on)(?=[A-Z])/, ""));
+}
+function scopeSlugForFile(file2) {
+  const base = file2.replace(/\\/g, "/").split("/").pop() ?? file2;
+  const name = base.replace(/\.[jt]sx?$/, "");
+  if (name.toLowerCase() === "index") {
+    const dir = file2.replace(/\\/g, "/").split("/").slice(-2, -1)[0] ?? "";
+    return kebab(dir);
+  }
+  return kebab(name.replace(/Screen$/, ""));
+}
+function collapseRepeats(slug) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const token of slug.split("-")) {
+    if (!token || seen.has(token)) continue;
+    seen.add(token);
+    out.push(token);
+  }
+  return out.join("-");
+}
+function deriveTestId(site) {
+  const base = [site.scope, kebab(site.component)].filter(Boolean).join("-");
+  if (site.pressProp && site.pressProp !== "onPress") {
+    return collapseRepeats(`${base}-${verbOf(site.pressProp)}`);
+  }
+  if (site.handler) {
+    const verb = verbOf(site.handler);
+    return collapseRepeats(verb ? `${base}-${verb}` : base);
+  }
+  return collapseRepeats(`${base}-${site.ordinal}`);
+}
+function hasAnyProp(element, names) {
+  return names.some((name) => findJsxAttribute(element, name) !== void 0);
+}
+function hasLabelText(element) {
+  return LABEL_PROPS.some((name) => {
+    const value = getStringAttr(element, name);
+    return typeof value === "string" && value.trim().length > 0;
+  });
+}
+function namedHandler(element, prop) {
+  if (!prop) return void 0;
+  const attr = findJsxAttribute(element, prop);
+  if (!attr || !t13.isJSXExpressionContainer(attr.value)) return void 0;
+  return t13.isIdentifier(attr.value.expression) ? attr.value.expression.name : void 0;
+}
+var ANNOTATABLE_ROLES = /* @__PURE__ */ new Set(["button", "input", "select", "toggle", "date", "list"]);
+function isPerItemRender(nodePath) {
+  let current = nodePath.parentPath;
+  while (current) {
+    const node = current.node;
+    if (t13.isCallExpression(node) && t13.isMemberExpression(node.callee) && t13.isIdentifier(node.callee.property) && (node.callee.property.name === "map" || node.callee.property.name === "flatMap")) {
+      return true;
+    }
+    if (t13.isJSXAttribute(node) && t13.isJSXIdentifier(node.name) && /^render[A-Z]|^ListHeaderComponent$|^ListFooterComponent$/.test(node.name.name) && node.name.name !== "renderScrollComponent") {
+      return /^renderItem$|^renderSectionHeader$|^renderSectionFooter$/.test(node.name.name);
+    }
+    current = current.parentPath;
+  }
+  return false;
+}
+function findAnnotationSites(source, file2) {
+  let ast;
+  try {
+    ast = parseSource(source);
+  } catch {
+    return [];
+  }
+  const imports = collectImports(ast);
+  const scope = scopeSlugForFile(file2);
+  const sites = [];
+  const perComponent = /* @__PURE__ */ new Map();
+  const usedIds = /* @__PURE__ */ new Set();
+  traverse12(ast, {
+    JSXOpeningElement(nodePath) {
+      for (const prop of IDENTITY_PROPS) {
+        const existing = getStringAttr(nodePath.node, prop);
+        if (existing) usedIds.add(existing);
+      }
+    }
+  });
+  traverse12(ast, {
+    JSXOpeningElement(nodePath) {
+      const element = nodePath.node;
+      if (!t13.isJSXIdentifier(element.name)) return;
+      const component = element.name.name;
+      const role = classifyJsxComponent(component, element);
+      if (!ANNOTATABLE_ROLES.has(role)) return;
+      if (hasAnyProp(element, IDENTITY_PROPS)) return;
+      if (role === "button" && hasLabelText(element)) return;
+      const carrier = canCarryTestId(component, file2, imports);
+      if (carrier === "derives") return;
+      if (isPerItemRender(nodePath)) return;
+      const pressProp = pressHandlerProp(element) ?? void 0;
+      const handler = namedHandler(element, pressProp);
+      const ordinal = (perComponent.get(component) ?? 0) + 1;
+      perComponent.set(component, ordinal);
+      let testId = deriveTestId({ scope, component, pressProp, handler, ordinal });
+      if (usedIds.has(testId)) {
+        let suffix = 2;
+        while (usedIds.has(`${testId}-${suffix}`)) suffix += 1;
+        testId = `${testId}-${suffix}`;
+      }
+      usedIds.add(testId);
+      const line = element.loc?.start.line ?? 0;
+      const nameEndLine = element.name.loc?.end.line ?? line;
+      const firstAttr = element.attributes[0];
+      const firstAttrLoc = firstAttr?.loc?.start;
+      const isMultiline = !!firstAttrLoc && firstAttrLoc.line !== nameEndLine;
+      const insertText = isMultiline ? `
+${" ".repeat(firstAttrLoc.column)}testID="${testId}"` : ` testID="${testId}"`;
+      sites.push({
+        file: file2,
+        line,
+        column: element.loc?.start.column ?? 0,
+        component,
+        role,
+        pressProp,
+        handler,
+        testId,
+        carrier,
+        // Just past the element name — before any existing attribute, so a
+        // multi-line element keeps its formatting and the new prop reads
+        // first in the diff.
+        insertAt: element.name.end ?? element.start ?? 0,
+        insertText
+      });
+    }
+  });
+  return sites;
+}
+
+// src/annotate/apply.ts
+var import_magic_string = __toESM(require("magic-string"));
+function planSite(site) {
+  if (site.carrier === "rn-primitive" || site.carrier === "forwards") {
+    return { ...site, outcome: "annotated" };
+  }
+  if (site.carrier === "swallows") {
+    return {
+      ...site,
+      outcome: "blocked-swallows",
+      blockedReason: `<${site.component}> does not accept testID, so React would drop the prop and the agent would be told about an element that never reaches the screen. Add testID?: string to its props and pass it to the element it renders, then re-run.`
+    };
+  }
+  return {
+    ...site,
+    outcome: "blocked-unverifiable",
+    blockedReason: `<${site.component}> comes from a package whose source is not readable from here, so whether it forwards testID cannot be checked. Annotate it by hand if it does.`
+  };
+}
+function applyToFile(source, sites) {
+  const planned = sites.map(planSite);
+  const written = planned.filter((site) => site.outcome === "annotated");
+  const blocked = planned.filter((site) => site.outcome !== "annotated");
+  if (written.length === 0) {
+    return { file: sites[0]?.file ?? "", content: source, written, blocked };
+  }
+  const magic = new import_magic_string.default(source);
+  for (const site of written) {
+    magic.appendLeft(site.insertAt, site.insertText);
+  }
+  return { file: written[0].file, content: magic.toString(), written, blocked };
+}
+
+// src/annotate/forward.ts
+var import_node_fs4 = require("fs");
+var import_magic_string2 = __toESM(require("magic-string"));
+var import_traverse13 = __toESM(require("@babel/traverse"));
+var t14 = __toESM(require("@babel/types"));
+var traverse13 = import_traverse13.default.default ?? import_traverse13.default;
+function findComponent(ast, name) {
+  let found;
+  traverse13(ast, {
+    FunctionDeclaration(nodePath) {
+      if (nodePath.node.id?.name === name) {
+        found ??= { params: nodePath.node.params, body: nodePath.node.body };
+      }
+    },
+    VariableDeclarator(nodePath) {
+      if (!t14.isIdentifier(nodePath.node.id) || nodePath.node.id.name !== name) return;
+      const init = nodePath.node.init;
+      if (t14.isArrowFunctionExpression(init) || t14.isFunctionExpression(init)) {
+        found ??= { params: init.params, body: init.body };
+      }
+    }
+  });
+  return found;
+}
+function findReturnedRoots(body) {
+  const roots = [];
+  let unsupported = false;
+  const record = (node) => {
+    if (!node) return;
+    if (t14.isParenthesizedExpression(node)) return record(node.expression);
+    if (t14.isJSXElement(node)) {
+      roots.push(node.openingElement);
+      return;
+    }
+    if (t14.isConditionalExpression(node)) {
+      record(node.consequent);
+      record(node.alternate);
+      return;
+    }
+    if (t14.isJSXFragment(node)) {
+      unsupported = true;
+      return;
+    }
+    if (t14.isNullLiteral(node)) return;
+    unsupported = true;
+  };
+  if (t14.isBlockStatement(body)) {
+    traverse13(
+      t14.file(t14.program([t14.expressionStatement(t14.functionExpression(null, [], body))])),
+      {
+        ReturnStatement(nodePath) {
+          record(nodePath.node.argument);
+        }
+      }
+    );
+  } else {
+    record(body);
+  }
+  if (unsupported || roots.length === 0) return void 0;
+  return roots;
+}
+function isCarrierRoot(element, imports) {
+  if (!t14.isJSXIdentifier(element.name)) return false;
+  const name = element.name.name;
+  const origin = imports.get(name);
+  if (origin?.source !== "react-native") return false;
+  return RN_TESTID_CARRIERS.has(origin.imported);
+}
+function hasProp(element, name) {
+  return element.attributes.some(
+    (attr) => t14.isJSXAttribute(attr) && t14.isJSXIdentifier(attr.name) && attr.name.name === name
+  );
+}
+function indentOf(source, offset) {
+  const lineStart = source.lastIndexOf("\n", offset - 1) + 1;
+  const match = /^[ \t]*/.exec(source.slice(lineStart, offset));
+  return match?.[0] ?? "";
+}
+function insertAfterLastMember(source, members, text, closingBrace, separator) {
+  const last = members[members.length - 1];
+  if (!last || typeof last.end !== "number" || typeof last.start !== "number") {
+    return { at: closingBrace, text };
+  }
+  const trailing = /^\s*[,;]/.exec(source.slice(last.end, closingBrace));
+  const at = last.end + (trailing?.[0].length ?? 0);
+  const endsWithSeparator = source.slice(0, last.end).trimEnd().endsWith(separator);
+  const lead = trailing || endsWithSeparator ? "" : separator;
+  const openLine = source.lastIndexOf("\n", last.start);
+  const multiline = openLine !== -1 && openLine > source.lastIndexOf("{", last.start);
+  if (!multiline) return { at, text: `${lead} ${text}` };
+  const indent = indentOf(source, last.start);
+  return { at, text: `${lead}
+${indent}${text}` };
+}
+function followBarrel(file2, ast, component) {
+  let target;
+  traverse13(ast, {
+    ExportNamedDeclaration(nodePath) {
+      const from = nodePath.node.source?.value;
+      if (!from) return;
+      const named = nodePath.node.specifiers.some(
+        (spec) => t14.isExportSpecifier(spec) && (t14.isIdentifier(spec.exported) ? spec.exported.name : spec.exported.value) === component
+      );
+      if (named) target ??= from;
+    }
+  });
+  return target ? resolveRelativeImport(file2, target) : void 0;
+}
+function planForward(file2, component, depth = 0) {
+  const base = { file: file2, component, edits: [], roots: 0 };
+  let source;
+  try {
+    source = (0, import_node_fs4.readFileSync)(file2, "utf-8");
+  } catch {
+    return { ...base, refusal: `cannot read ${file2}` };
+  }
+  let ast;
+  try {
+    ast = parseSource(source);
+  } catch {
+    return { ...base, refusal: `cannot parse ${file2}` };
+  }
+  const found = findComponent(ast, component);
+  if (!found) {
+    const barrel = depth < 2 ? followBarrel(file2, ast, component) : void 0;
+    if (barrel) return planForward(barrel, component, depth + 1);
+    return { ...base, refusal: `no function named ${component} in this file` };
+  }
+  const param = found.params[0];
+  if (!t14.isObjectPattern(param)) {
+    return {
+      ...base,
+      refusal: `${component} does not destructure its props, so there is no safe place to add one without knowing what the parameter is called downstream`
+    };
+  }
+  const roots = findReturnedRoots(found.body);
+  if (!roots) {
+    return {
+      ...base,
+      refusal: `${component} returns something other than a JSX element (a fragment, or a value this cannot follow)`
+    };
+  }
+  const imports = collectImports(ast);
+  const nonCarrier = roots.find((root) => !isCarrierRoot(root, imports));
+  if (nonCarrier) {
+    const name = t14.isJSXIdentifier(nonCarrier.name) ? nonCarrier.name.name : "its root";
+    return {
+      ...base,
+      refusal: `${component} renders <${name}> at its root, which is not a React Native element known to accept testID. Forwarding into it would move the problem down a level, not fix it`
+    };
+  }
+  const edits = [];
+  const alreadyDestructured = param.properties.some(
+    (prop) => t14.isObjectProperty(prop) && t14.isIdentifier(prop.key) && prop.key.name === "testID"
+  );
+  if (!alreadyDestructured) {
+    const insert = insertAfterLastMember(source, param.properties, "testID", param.end ?? 0, ",");
+    edits.push({ ...insert, what: "parameter" });
+  }
+  const annotation = param.typeAnnotation;
+  if (t14.isTSTypeAnnotation(annotation)) {
+    const declared = annotation.typeAnnotation;
+    let body;
+    let closing = 0;
+    if (t14.isTSTypeLiteral(declared)) {
+      body = declared.members;
+      closing = declared.end ?? 0;
+    } else if (t14.isTSTypeReference(declared) && t14.isIdentifier(declared.typeName)) {
+      const typeName = declared.typeName.name;
+      traverse13(ast, {
+        TSInterfaceDeclaration(nodePath) {
+          if (nodePath.node.id.name !== typeName) return;
+          body = nodePath.node.body.body;
+          closing = nodePath.node.body.end ?? 0;
+        },
+        TSTypeAliasDeclaration(nodePath) {
+          if (nodePath.node.id.name !== typeName || !t14.isTSTypeLiteral(nodePath.node.typeAnnotation))
+            return;
+          body = nodePath.node.typeAnnotation.members;
+          closing = nodePath.node.typeAnnotation.end ?? 0;
+        }
+      });
+      if (!body) {
+        return {
+          ...base,
+          refusal: `${component}'s props type \`${typeName}\` is not declared in this file, so adding a field to it would edit a contract shared with code this cannot see`
+        };
+      }
+    }
+    if (body) {
+      const declaresTestId = body.some(
+        (member) => t14.isTSPropertySignature(member) && t14.isIdentifier(member.key) && member.key.name === "testID"
+      );
+      if (!declaresTestId) {
+        const insert = insertAfterLastMember(source, body, "testID?: string;", closing, ";");
+        edits.push({ ...insert, what: "props-type" });
+      }
+    }
+  }
+  let delivered = 0;
+  for (const root of roots) {
+    if (hasProp(root, "testID")) continue;
+    edits.push({
+      at: root.name.end ?? root.start ?? 0,
+      text: " testID={testID}",
+      what: "root"
+    });
+    delivered += 1;
+  }
+  if (edits.length === 0) {
+    return { ...base, refusal: `${component} already forwards testID` };
+  }
+  return { file: file2, component, edits, roots: delivered };
+}
+function applyForward(source, plan) {
+  if (plan.refusal || plan.edits.length === 0) return source;
+  const magic = new import_magic_string2.default(source);
+  for (const edit of plan.edits) magic.appendLeft(edit.at, edit.text);
+  return magic.toString();
+}
+
+// src/cli/commands/annotate.ts
+var DEFAULT_INCLUDE = ["src/**/*Screen.{tsx,jsx}", "src/**/screens/**/*.{tsx,jsx}"];
+var DEFAULT_EXCLUDE = ["**/node_modules/**", "**/dist/**", "**/*.test.*", "**/__tests__/**"];
+function annotateCommand() {
+  return new import_commander5.Command("annotate").description(
+    "Add missing testIDs to interactive elements so the agent can address them (dry run by default)"
+  ).option("--write", "Actually modify the files (default: report only)", false).option(
+    "--forward",
+    "Also teach a shared component to accept and pass through testID, when its call sites are blocked only by that",
+    false
+  ).option("-i, --include <globs...>", "Glob patterns to scan", void 0).option("--json", "Emit a machine-readable report", false).option("--quiet", "Only warnings and errors", false).action(async (options) => {
+    try {
+      if (options.json) setLogMode("json");
+      else if (options.quiet) setLogMode("quiet");
+      banner();
+      let loaded = null;
+      try {
+        loaded = loadConfig(warn);
+      } catch {
+        loaded = null;
+      }
+      const rootDir = process.cwd();
+      const include = options.include ?? DEFAULT_INCLUDE;
+      const exclude = loaded?.exclude ?? DEFAULT_EXCLUDE;
+      const spinner = createSpinner("Scanning for unaddressable controls...");
+      spinner.start();
+      resetForwardingCache();
+      const files = await (0, import_fast_glob6.default)(include, { cwd: rootDir, ignore: exclude, absolute: true });
+      const scan = async () => {
+        const out = [];
+        for (const file2 of files) {
+          const source = await (0, import_promises6.readFile)(file2, "utf-8");
+          const sites = findAnnotationSites(source, file2);
+          if (sites.length === 0) continue;
+          out.push(applyToFile(source, sites));
+        }
+        return out;
+      };
+      let edits = await scan();
+      let forwards = [];
+      if (options.forward) {
+        forwards = await planForwards(edits, rootDir);
+        const applied = forwards.filter((plan) => !plan.refusal);
+        if (options.write && applied.length > 0) {
+          for (const plan of applied) {
+            const before = await (0, import_promises6.readFile)(plan.file, "utf-8");
+            await (0, import_promises6.writeFile)(plan.file, applyForward(before, plan), "utf-8");
+          }
+          resetForwardingCache();
+          edits = await scan();
+        }
+      }
+      spinner.stop();
+      const written = edits.flatMap((edit) => edit.written);
+      const blocked = edits.flatMap((edit) => edit.blocked);
+      const touched = edits.filter((edit) => edit.written.length > 0);
+      if (written.length === 0 && blocked.length === 0) {
+        success("Every interactive control already has something to address it by.");
+        if (options.json) {
+          jsonOutput({ ok: true, scanned: files.length, annotated: 0, blocked: 0, sites: [] });
+        }
+        return;
+      }
+      if (options.write) {
+        for (const edit of touched) {
+          await (0, import_promises6.writeFile)(edit.file, edit.content, "utf-8");
+        }
+      }
+      reportSites(rootDir, touched, blocked, options.write === true, forwards);
+      if (options.json) {
+        jsonOutput({
+          ok: true,
+          scanned: files.length,
+          written: options.write === true,
+          annotated: written.length,
+          blocked: blocked.length,
+          files: touched.map((edit) => import_node_path7.default.relative(rootDir, edit.file)),
+          sites: [...written, ...blocked].map((site) => ({
+            file: import_node_path7.default.relative(rootDir, site.file),
+            line: site.line,
+            component: site.component,
+            role: site.role,
+            testId: site.testId,
+            outcome: site.outcome,
+            reason: site.blockedReason
+          }))
+        });
+      }
+    } catch (err) {
+      error(`Annotate failed: ${stringifyUnknown(err)}`);
+      process.exit(1);
+    }
+  });
+}
+async function planForwards(edits, rootDir) {
+  const seen = /* @__PURE__ */ new Set();
+  const plans = [];
+  for (const edit of edits) {
+    for (const site of edit.blocked) {
+      if (site.outcome !== "blocked-swallows") continue;
+      if (seen.has(site.component)) continue;
+      seen.add(site.component);
+      const source = await (0, import_promises6.readFile)(site.file, "utf-8");
+      const origin = findImportSource(source, site.component);
+      const target = origin ? resolveRelativeImport(site.file, origin) : site.file;
+      if (!target) {
+        plans.push({
+          file: site.file,
+          component: site.component,
+          edits: [],
+          roots: 0,
+          refusal: `cannot locate the source of <${site.component}>`
+        });
+        continue;
+      }
+      plans.push(planForward(target, site.component));
+    }
+  }
+  void rootDir;
+  return plans;
+}
+function findImportSource(source, name) {
+  const pattern = new RegExp(
+    String.raw`import\s*\{[^}]*\b${name}\b[^}]*\}\s*from\s*['"]([^'"]+)['"]`
+  );
+  return pattern.exec(source)?.[1];
+}
+function reportSites(rootDir, touched, blocked, didWrite, forwards) {
+  const written = touched.flatMap((edit) => edit.written);
+  if (written.length > 0) {
+    heading(didWrite ? "Added" : "Would add");
+    for (const edit of touched) {
+      info(import_node_path7.default.relative(rootDir, edit.file));
+      for (const site of edit.written) {
+        dim(`  ${String(site.line).padStart(4)}  <${site.component}>  testID="${site.testId}"`);
+      }
+    }
+  }
+  const teachable = new Map(
+    forwards.filter((plan) => !plan.refusal).map((plan) => [plan.component, plan])
+  );
+  if (teachable.size > 0) {
+    heading(didWrite ? "Taught to carry testID" : "Would teach to carry testID");
+    for (const plan of teachable.values()) {
+      info(`<${plan.component}>  ${import_node_path7.default.relative(rootDir, plan.file)}`);
+      for (const edit of plan.edits) {
+        dim(`      ${edit.what}: ${edit.text.trim()}`);
+      }
+    }
+  }
+  if (blocked.length > 0) {
+    heading("Skipped \u2014 the prop would not survive to the runtime");
+    const byComponent = /* @__PURE__ */ new Map();
+    for (const site of blocked) {
+      const group = byComponent.get(site.component) ?? [];
+      group.push(site);
+      byComponent.set(site.component, group);
+    }
+    for (const [component, group] of byComponent) {
+      if (teachable.has(component)) continue;
+      warn(`<${component}> \u2014 ${group.length} site${group.length === 1 ? "" : "s"}`);
+      const refusal = forwards.find((plan) => plan.component === component)?.refusal;
+      dim(`  ${group[0].blockedReason}`);
+      if (refusal) dim(`  --forward cannot do it either: ${refusal}`);
+    }
+  }
+  if (!didWrite && written.length > 0) {
+    info("");
+    info(`Nothing was written. Re-run with --write to apply ${written.length} change(s).`);
+  } else if (didWrite) {
+    success(`Wrote ${written.length} testID(s) across ${touched.length} file(s).`);
+    info("Re-run `appilots generate` so the document picks them up.");
+  }
+}
+
+// src/cli/commands/status.ts
+var import_commander6 = require("commander");
 function statusCommand() {
-  return new import_commander5.Command("status").description("Show current project and MCP document status").option("--json", "Output a machine-readable JSON result (implies --quiet)", false).option("--quiet", "Suppress banner and informational output", false).action(async (options) => {
+  return new import_commander6.Command("status").description("Show current project and MCP document status").option("--json", "Output a machine-readable JSON result (implies --quiet)", false).option("--quiet", "Suppress banner and informational output", false).action(async (options) => {
     if (options.json) setLogMode("json");
     else if (options.quiet) setLogMode("quiet");
     try {
       banner();
-      const config = loadConfig();
+      const config = loadConfig(warn);
       if (!config) {
         error("No .appilotsrc configuration found");
         info("Run: appilots init --api-key <your-key>");
@@ -10513,8 +12090,13 @@ function statusCommand() {
       ]);
       if (status.project) {
         heading("\n\u{1F4CC} Project Info:");
-        table([["Name", status.project.name], ["ID", status.project.id]]);
+        table([
+          ["Name", status.project.name],
+          ["ID", status.project.id]
+        ]);
       }
+      const outputDir = config.outputDir || ".appilots";
+      let drift = null;
       if (status.activeMcp) {
         heading("\n\u2705 Active MCP Document:");
         table([
@@ -10524,6 +12106,14 @@ function statusCommand() {
           ["Forms", String(status.activeMcp.formsCount)],
           ["Actions", String(status.activeMcp.actionsCount)]
         ]);
+        const local = readLocalDocumentSummary(outputDir);
+        if (local) {
+          drift = compareWithRemote(local, status.activeMcp);
+          if (drift) {
+            heading("");
+            reportRemoteDrift(drift);
+          }
+        }
       } else {
         heading("\n\u26A0\uFE0F  No active MCP document");
         info("Run: appilots sync");
@@ -10534,21 +12124,22 @@ function statusCommand() {
         local: {
           serverUrl: config.serverUrl,
           projectId: config.projectId || null,
-          outputDir: config.outputDir || ".appilots"
+          outputDir
         },
         project: status.project ?? null,
-        activeMcp: status.activeMcp ?? null
+        activeMcp: status.activeMcp ?? null,
+        drift
       });
     } catch (err) {
-      error(`Status check failed: ${err instanceof Error ? err.message : String(err)}`);
-      jsonOutput({ success: false, error: err instanceof Error ? err.message : String(err) });
+      error(`Status check failed: ${stringifyUnknown(err)}`);
+      jsonOutput({ success: false, error: stringifyUnknown(err) });
       process.exit(1);
     }
   });
 }
 
 // src/cli/commands/eval.ts
-var import_commander6 = require("commander");
+var import_commander7 = require("commander");
 var import_fs10 = require("fs");
 var import_path9 = require("path");
 
@@ -10578,21 +12169,21 @@ function loadScenarios(dir) {
   } catch {
     return { scenarios, errors };
   }
-  for (const file of files) {
-    const full = (0, import_path7.join)(dir, file);
+  for (const file2 of files) {
+    const full = (0, import_path7.join)(dir, file2);
     let raw;
     try {
       raw = JSON.parse((0, import_fs8.readFileSync)(full, "utf-8"));
     } catch (err) {
-      errors.push({ file, error: `invalid JSON: ${err instanceof Error ? err.message : String(err)}` });
+      errors.push({ file: file2, error: `invalid JSON: ${stringifyUnknown(err)}` });
       continue;
     }
     const shapeError = validateScenarioShape(raw);
     if (shapeError) {
-      errors.push({ file, error: shapeError });
+      errors.push({ file: file2, error: shapeError });
       continue;
     }
-    scenarios.push({ file, scenario: raw });
+    scenarios.push({ file: file2, scenario: raw });
   }
   return { scenarios, errors };
 }
@@ -10741,10 +12332,10 @@ function matchActions(expected, actual, reply = "") {
 var import_fs9 = require("fs");
 var import_path8 = require("path");
 var EMPTY_BASELINE = { generatedAt: null, gitSha: null, perScenario: {} };
-function loadBaseline(path9) {
-  if (!(0, import_fs9.existsSync)(path9)) return { ...EMPTY_BASELINE, perScenario: {} };
+function loadBaseline(path11) {
+  if (!(0, import_fs9.existsSync)(path11)) return { ...EMPTY_BASELINE, perScenario: {} };
   try {
-    const raw = JSON.parse((0, import_fs9.readFileSync)(path9, "utf-8"));
+    const raw = JSON.parse((0, import_fs9.readFileSync)(path11, "utf-8"));
     return {
       generatedAt: raw.generatedAt ?? null,
       gitSha: raw.gitSha ?? null,
@@ -10754,9 +12345,9 @@ function loadBaseline(path9) {
     return { ...EMPTY_BASELINE, perScenario: {} };
   }
 }
-function saveBaseline(path9, baseline) {
-  (0, import_fs9.mkdirSync)((0, import_path8.dirname)(path9), { recursive: true });
-  (0, import_fs9.writeFileSync)(path9, `${JSON.stringify(baseline, null, 2)}
+function saveBaseline(path11, baseline) {
+  (0, import_fs9.mkdirSync)((0, import_path8.dirname)(path11), { recursive: true });
+  (0, import_fs9.writeFileSync)(path11, `${JSON.stringify(baseline, null, 2)}
 `, "utf-8");
 }
 function buildBaseline(outcomes, meta) {
@@ -10838,13 +12429,16 @@ function parseRate(raw, fallback, flagName) {
   return n;
 }
 function evalCommand() {
-  return new import_commander6.Command("eval").description(
+  return new import_commander7.Command("eval").description(
     "Run agent eval scenarios against the current MCP document in dry-run mode and check for regressions vs a committed baseline"
   ).option("--init", "Scaffold an example scenario in the scenarios directory", false).option("--force", "With --init, overwrite an existing example scenario", false).option("--dir <path>", "Scenarios directory (default: <outputDir>/scenarios)").option("--baseline <path>", "Baseline file path (default: <outputDir>/eval-baseline.json)").option(
     "--update-baseline",
     "Record this run as the new baseline (refuses if pass rate is below the threshold)",
     false
-  ).option("--min-pass-rate <n>", "Minimum fraction of scenarios that must pass, 0-1 (default: 0.95)").option(
+  ).option(
+    "--min-pass-rate <n>",
+    "Minimum fraction of scenarios that must pass, 0-1 (default: 0.95)"
+  ).option(
     "--max-token-regression <n>",
     "Max fractional token increase before a passing scenario is flagged, e.g. 0.25 for +25% (default: 0.25)"
   ).option("--model <id>", "Model override for scenarios that do not set their own modelOverride").option("--api-key <key>", "Appilots API key (overrides .appilotsrc and APPILOTS_API_KEY)").option("--project-id <id>", "Project ID (overrides .appilotsrc and APPILOTS_PROJECT_ID)").option("--server <url>", "Appilots server URL (overrides .appilotsrc and APPILOTS_SERVER_URL)").option("--json", "Output a machine-readable JSON result (implies --quiet)", false).option("--quiet", "Suppress banner and informational output", false).action(async (options) => {
@@ -10852,7 +12446,7 @@ function evalCommand() {
     else if (options.quiet) setLogMode("quiet");
     try {
       banner();
-      const loaded = loadConfig();
+      const loaded = loadConfig(warn);
       const outputDir = loaded?.outputDir || ".appilots";
       const scenariosDir = options.dir || loaded?.eval?.scenariosDir || (0, import_path9.join)(outputDir, "scenarios");
       if (options.init) {
@@ -10881,7 +12475,7 @@ function evalCommand() {
         return;
       }
       const config = {
-        serverUrl: "http://localhost:4000",
+        serverUrl: DEFAULT_SERVER_URL,
         ...loaded,
         apiKey,
         ...options.projectId ? { projectId: options.projectId } : {},
@@ -10927,11 +12521,17 @@ function evalCommand() {
         error(
           `Duplicate scenario name(s) \u2014 "name" must be unique across all scenario files: ${duplicates.join(", ")}`
         );
-        jsonOutput({ success: false, error: `Duplicate scenario names: ${duplicates.join(", ")}` });
+        jsonOutput({
+          success: false,
+          error: `Duplicate scenario names: ${duplicates.join(", ")}`
+        });
         process.exit(1);
         return;
       }
-      const apiClient = new AppilotsAPIClient({ serverUrl: config.serverUrl, apiKey: config.apiKey });
+      const apiClient = new AppilotsAPIClient({
+        serverUrl: config.serverUrl,
+        apiKey: config.apiKey
+      });
       const requests = loadedScenarios.scenarios.map(({ scenario }) => ({
         id: scenario.name,
         screen: scenario.given?.screen,
@@ -11033,8 +12633,8 @@ Pass rate: ${passed}/${total} (${passRatePct}%) \u2014 threshold ${minPassRatePc
         success("Eval passed");
       }
     } catch (err) {
-      error(`Eval failed: ${err instanceof Error ? err.message : String(err)}`);
-      jsonOutput({ success: false, error: err instanceof Error ? err.message : String(err) });
+      error(`Eval failed: ${stringifyUnknown(err)}`);
+      jsonOutput({ success: false, error: stringifyUnknown(err) });
       process.exit(1);
     }
   });
@@ -11042,16 +12642,17 @@ Pass rate: ${passed}/${total} (${passRatePct}%) \u2014 threshold ${minPassRatePc
 
 // src/cli/index.ts
 async function main() {
-  const program = new import_commander7.Command();
-  program.name("appilots").description(
+  const program2 = new import_commander8.Command();
+  program2.name("appilots").description(
     "Analyze your React Native app and generate MCP documents for AI-powered navigation.\n\nQuick start:\n  $ appilots init --api-key ak_xxx\n  $ appilots sync\n  $ appilots watch"
-  ).version("0.1.0").option("--verbose", "Enable verbose logging");
-  program.addCommand(initCommand());
-  program.addCommand(syncCommand());
-  program.addCommand(watchCommand());
-  program.addCommand(generateCommand());
-  program.addCommand(statusCommand());
-  program.addCommand(evalCommand());
+  ).version(CLI_VERSION).option("--verbose", "Enable verbose logging");
+  program2.addCommand(initCommand());
+  program2.addCommand(syncCommand());
+  program2.addCommand(watchCommand());
+  program2.addCommand(generateCommand());
+  program2.addCommand(annotateCommand());
+  program2.addCommand(statusCommand());
+  program2.addCommand(evalCommand());
   const args = process.argv.slice(2);
   const firstArg = args[0];
   const hasCommand = firstArg !== void 0 && args.length > 0 && !firstArg.startsWith("-");
@@ -11064,14 +12665,14 @@ async function main() {
       info("Welcome to Appilots! Get started with:");
       info("  appilots init --api-key <your-ak_key>");
       console.log("");
-      program.outputHelp();
+      program2.outputHelp();
       return;
     }
   }
-  await program.parseAsync(process.argv);
+  await program2.parseAsync(process.argv);
 }
 main().catch((err) => {
-  error(err instanceof Error ? err.message : String(err));
+  error(stringifyUnknown(err));
   process.exit(1);
 });
 //# sourceMappingURL=index.js.map