@exodus/xqa 1.2.3 → 1.4.0

package/dist/xqa.cjs

@@ -3587,7 +3587,7 @@ var require_index_cjs = __commonJS({
         }, reject);
       }
     }
-    var ResultAsync8 = class _ResultAsync {
+    var ResultAsync9 = class _ResultAsync {
       constructor(res) {
         this._promise = res;
       }
@@ -3726,14 +3726,14 @@ var require_index_cjs = __commonJS({
       }
     };
     function okAsync8(value) {
-      return new ResultAsync8(Promise.resolve(new Ok(value)));
+      return new ResultAsync9(Promise.resolve(new Ok(value)));
     }
     function errAsync7(err17) {
-      return new ResultAsync8(Promise.resolve(new Err(err17)));
+      return new ResultAsync9(Promise.resolve(new Err(err17)));
     }
-    var fromPromise = ResultAsync8.fromPromise;
-    var fromSafePromise2 = ResultAsync8.fromSafePromise;
-    var fromAsyncThrowable9 = ResultAsync8.fromThrowable;
+    var fromPromise = ResultAsync9.fromPromise;
+    var fromSafePromise2 = ResultAsync9.fromSafePromise;
+    var fromAsyncThrowable9 = ResultAsync9.fromThrowable;
     var combineResultList = (resultList) => {
       let acc = ok17([]);
       for (const result of resultList) {
@@ -3746,7 +3746,7 @@ var require_index_cjs = __commonJS({
       }
       return acc;
     };
-    var combineResultAsyncList = (asyncResultList) => ResultAsync8.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultList);
+    var combineResultAsyncList = (asyncResultList) => ResultAsync9.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultList);
     var combineResultListWithAllErrors = (resultList) => {
       let acc = ok17([]);
       for (const result of resultList) {
@@ -3760,9 +3760,9 @@ var require_index_cjs = __commonJS({
       }
       return acc;
     };
-    var combineResultAsyncListWithAllErrors = (asyncResultList) => ResultAsync8.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultListWithAllErrors);
+    var combineResultAsyncListWithAllErrors = (asyncResultList) => ResultAsync9.fromSafePromise(Promise.all(asyncResultList)).andThen(combineResultListWithAllErrors);
     exports2.Result = void 0;
-    (function(Result) {
+    (function(Result3) {
       function fromThrowable11(fn, errorFn) {
         return (...args) => {
           try {
@@ -3773,15 +3773,15 @@ var require_index_cjs = __commonJS({
           }
         };
       }
-      Result.fromThrowable = fromThrowable11;
+      Result3.fromThrowable = fromThrowable11;
       function combine(resultList) {
         return combineResultList(resultList);
       }
-      Result.combine = combine;
+      Result3.combine = combine;
       function combineWithAllErrors(resultList) {
         return combineResultListWithAllErrors(resultList);
       }
-      Result.combineWithAllErrors = combineWithAllErrors;
+      Result3.combineWithAllErrors = combineWithAllErrors;
     })(exports2.Result || (exports2.Result = {}));
     function ok17(value) {
       return new Ok(value);
@@ -3792,7 +3792,7 @@ var require_index_cjs = __commonJS({
     function safeTry(body) {
       const n3 = body().next();
       if (n3 instanceof Promise) {
-        return new ResultAsync8(n3.then((r3) => r3.value));
+        return new ResultAsync9(n3.then((r3) => r3.value));
       }
       return n3.value;
     }
@@ -3843,7 +3843,7 @@ var require_index_cjs = __commonJS({
         return f6(this.value).map(() => this.value);
       }
       asyncMap(f6) {
-        return ResultAsync8.fromSafePromise(f6(this.value));
+        return ResultAsync9.fromSafePromise(f6(this.value));
       }
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       unwrapOr(_v) {
@@ -3947,7 +3947,7 @@ var require_index_cjs = __commonJS({
     var fromThrowable10 = exports2.Result.fromThrowable;
     exports2.Err = Err;
     exports2.Ok = Ok;
-    exports2.ResultAsync = ResultAsync8;
+    exports2.ResultAsync = ResultAsync9;
     exports2.err = err16;
     exports2.errAsync = errAsync7;
     exports2.fromAsyncThrowable = fromAsyncThrowable9;
@@ -15864,6 +15864,18 @@ function formatMemoryElements(elements) {
     (element) => `${element.label} [${String(Math.round(element.confidence * PCT_MULTIPLIER))}%${element.phase === "after-scroll" ? "\u2193" : ""}]`
   ).join(", ");
 }
+var ALL_VERBOSE_CATEGORIES = /* @__PURE__ */ new Set([
+  "prompt",
+  "tools",
+  "screen",
+  "memory"
+]);
+function isVerboseEnabled(config3, category) {
+  if (config3 === void 0) {
+    return false;
+  }
+  return config3.has(category);
+}
 var SCREEN_PREVIEW_LENGTH = 80;
 function write(line) {
   process.stderr.write(line + "\n");
@@ -15871,7 +15883,7 @@ function write(line) {
 function writePlainScreenState(event, verbose) {
   const preview = (event.snapshot.split("\n")[0] ?? "").slice(0, SCREEN_PREVIEW_LENGTH);
   write(`[${event.agent}] screen (${String(event.snapshot.length)} chars): ${preview}`);
-  if (verbose) {
+  if (isVerboseEnabled(verbose, "screen")) {
     write(event.snapshot);
   }
 }
@@ -15879,7 +15891,7 @@ function writePlainScreenMemory(event, verbose) {
   write(
     `[${event.agent}] memory (${String(event.sessionsObserved)} sessions): ${formatMemoryElements(event.elements)}`
   );
-  if (verbose) {
+  if (isVerboseEnabled(verbose, "memory")) {
     write(event.enrichedSnapshot);
   }
 }
@@ -15914,8 +15926,14 @@ function writePlainToolError(event) {
     write(`${prefix} error handling ${event.toolName}: ${line}`);
   }
 }
+function writePlainError(event) {
+  write(`[${event.agent}] error: ${event.message}`);
+  if (event.stack !== void 0) {
+    write(event.stack);
+  }
+}
 function writePlainToolResult(event, verbose) {
-  if (!verbose) {
+  if (!isVerboseEnabled(verbose, "tools")) {
     return;
   }
   const prefix = `[${event.agent}]`;
@@ -15941,13 +15959,13 @@ function handlePlainToolEvent(event, verbose) {
   }
 }
 function writePlainSystemPrompt(event, verbose) {
-  if (!verbose) {
+  if (!isVerboseEnabled(verbose, "prompt")) {
     return;
   }
   write(`[${event.agent}] system prompt:
 ${event.prompt}`);
 }
-function dispatchPlainEventFirst(event, verbose) {
+function dispatchPlainNonVerboseFirst(event) {
   switch (event.type) {
     case "STAGE_START": {
       writePlainStageStart(event);
@@ -15961,16 +15979,19 @@ function dispatchPlainEventFirst(event, verbose) {
       writePlainThought(event);
       return;
     }
-    case "SCREEN_STATE": {
-      writePlainScreenState(event, verbose);
-      return;
-    }
     case "SCREENSHOT": {
       writePlainScreenshot(event);
       return;
     }
   }
 }
+function dispatchPlainEventFirst(event, verbose) {
+  if (event.type === "SCREEN_STATE") {
+    writePlainScreenState(event, verbose);
+    return;
+  }
+  dispatchPlainNonVerboseFirst(event);
+}
 function dispatchPlainEventSecond(event, verbose) {
   switch (event.type) {
     case "SCREEN_MEMORY": {
@@ -15986,10 +16007,7 @@ function dispatchPlainEventSecond(event, verbose) {
       return;
     }
     case "ERROR": {
-      write(`[${event.agent}] error: ${event.message}`);
-      if (event.stack !== void 0) {
-        write(event.stack);
-      }
+      writePlainError(event);
       return;
     }
   }
@@ -16054,14 +16072,14 @@ function createGitHubCIFormatter(write2) {
       for (const warning of flushWarnings(event.agent, warnings)) {
         write2(warning);
       }
-      handlePlain(event, false);
+      handlePlain(event);
       return;
     }
     if (event.type === "INSPECTOR_STEP") {
       collectWarning(event, warnings);
       return;
     }
-    handlePlain(event, false);
+    handlePlain(event);
   };
 }
 var CHALK_TRUECOLOR_LEVEL = 3;
@@ -16116,7 +16134,7 @@ function writePrettyMemory(event, context) {
     barLine(applyMemoryStyle(`\u25B8 memory (${String(event.sessionsObserved)} sessions): ${top}`)),
     context.state
   );
-  if (context.verbose) {
+  if (isVerboseEnabled(context.verbose, "memory")) {
     for (const line of event.enrichedSnapshot.split("\n")) {
       writeLine(`${chalk2.dim(S_BAR)}     ${applyMemoryStyle(line)}`, context.state);
     }
@@ -16136,7 +16154,7 @@ function writePrettyScreenState(snapshot, context) {
     barLine(applyMemoryStyle(`\u25B8 screen (${String(snapshot.length)} chars): ${preview}`)),
     context.state
   );
-  if (context.verbose) {
+  if (isVerboseEnabled(context.verbose, "screen")) {
     for (const line of snapshot.split("\n")) {
       writeLine(`${chalk2.dim(S_BAR)}     ${applyMemoryStyle(line)}`, context.state);
     }
@@ -16151,7 +16169,7 @@ function writePrettyError(event, state) {
   }
 }
 function writePrettySystemPrompt(event, context) {
-  if (!context.verbose) {
+  if (!isVerboseEnabled(context.verbose, "prompt")) {
     return;
   }
   writeLine(barLine(applyThoughtStyle("\u25C6 system prompt")), context.state);
@@ -16566,7 +16584,7 @@ function buildToolArguments(input) {
   return Object.entries(input).filter(([key]) => !HIDDEN_TOOL_ARGS.has(key)).map(([key, value]) => `${key}: ${String(value)}`).join(", ");
 }
 function writeToolResult(event, context) {
-  if (context.verbose) {
+  if (isVerboseEnabled(context.verbose, "tools")) {
     for (const line of event.result.split("\n")) {
       writeLine(`${chalk4.dim(S_BAR4)}     ${applyToolStyle(line)}`, context.state);
     }
@@ -16697,7 +16715,7 @@ function resolveOutputMode() {
 }
 function createConsoleObserver(options) {
   const mode = options?.mode ?? resolveOutputMode();
-  const verbose = options?.verbose ?? false;
+  const verbose = options?.verbose;
   if (mode === "tty") {
     return createHybridTtyRenderer({ verbose });
   }
@@ -48106,7 +48124,7 @@ function dismissalsPath(baseDirectory, override) {
 }
 
 // ../../packages/pipeline/dist/index.js
-var import_neverthrow27 = __toESM(require_index_cjs(), 1);
+var import_neverthrow28 = __toESM(require_index_cjs(), 1);
 var import_promises14 = require("node:timers/promises");
 
 // ../../agents/analyser/dist/index.js
@@ -55763,10 +55781,10 @@ function runConsolidator(input, config3) {
 }
 
 // ../../packages/pipeline/dist/index.js
-var import_neverthrow28 = __toESM(require_index_cjs(), 1);
 var import_neverthrow29 = __toESM(require_index_cjs(), 1);
-var import_node_fs3 = require("node:fs");
 var import_neverthrow30 = __toESM(require_index_cjs(), 1);
+var import_node_fs3 = require("node:fs");
+var import_neverthrow31 = __toESM(require_index_cjs(), 1);
 var import_promises15 = require("node:timers/promises");
 
 // ../../agents/explorer/dist/index.js
@@ -55776,16 +55794,17 @@ var import_node_path4 = __toESM(require("node:path"), 1);
 var import_neverthrow14 = __toESM(require_index_cjs(), 1);
 var import_promises8 = require("node:fs/promises");
 var import_neverthrow15 = __toESM(require_index_cjs(), 1);
-var import_promises9 = require("node:timers/promises");
 var import_neverthrow16 = __toESM(require_index_cjs(), 1);
+var import_promises9 = require("node:timers/promises");
 var import_neverthrow17 = __toESM(require_index_cjs(), 1);
+var import_neverthrow18 = __toESM(require_index_cjs(), 1);
 var import_promises10 = require("node:fs/promises");
 var import_node_path5 = __toESM(require("node:path"), 1);
-var import_neverthrow18 = __toESM(require_index_cjs(), 1);
+var import_neverthrow19 = __toESM(require_index_cjs(), 1);
 var import_node_child_process4 = require("node:child_process");
 var import_promises11 = require("node:fs/promises");
 var import_node_path6 = __toESM(require("node:path"), 1);
-var import_neverthrow19 = __toESM(require_index_cjs(), 1);
+var import_neverthrow20 = __toESM(require_index_cjs(), 1);
 async function runFfmpeg(arguments_) {
   const { promise: promise2, resolve, reject } = Promise.withResolvers();
   (0, import_node_child_process3.execFile)("ffmpeg", arguments_, (error48) => {
@@ -55883,6 +55902,299 @@ function speedUpVideo({
     () => outputPath
   );
 }
+var DEV_ENVIRONMENT_SECTION = `## Environment
+
+This is a development build. Debug overlays and internal messages are expected artifacts \u2014 do not report them as findings.`;
+var WORKING_STATE_SECTION = `## Working State
+
+At every reasoning step, maintain a mental ledger:
+- VISITED: screen names confirmed via \`view_ui\` this session
+- QUEUE: screen names seen as reachable but not yet explored \u2014 also seed from App Knowledge if present
+- PATH: your current navigation stack from root (e.g. Home > Settings > Privacy)
+
+Consult the ledger before every action. Always prefer navigating to a QUEUE screen over a VISITED one.`;
+var BACK_NAV_RULE = `After navigating forward to any new screen: tap back, call \`view_ui\`, confirm you returned to the expected parent in PATH \u2014 if not, emit a \`back-nav-failure\` finding, then navigate forward again to continue`;
+var STUCK_LOOP_RULE = `Stuck loop: emit a \`stuck-loop\` finding when any of these occur: (1) \`view_ui\` returns the same screen state 3 or more consecutive steps, (2) the same element has been tapped more than twice with no screen change, (3) PATH shows the same screen at two non-adjacent positions \u2014 before emitting, try one alternative action (scroll, long-press, swipe) to rule out a gesture mismatch`;
+var CLIPPED_ELEMENT_RULE = `Never tap an element tagged \`[clipped-top]\`, \`[clipped-bottom]\`, \`[clipped-left]\`, or \`[clipped-right]\` \u2014 scroll to fully reveal it first, then re-call \`view_ui\` before tapping`;
+var WHAT_TO_TEST_SECTION = `## What to Test
+
+Test navigation elements first, interactions second.
+
+**Tier 1 \u2014 test every one, every time:**
+- Tab bar items, drawer menu items, hamburger menus
+- Back buttons, close buttons (X), modal dismiss controls
+- Bottom sheet handles and drag gestures
+- Navigation links and "Go to X" CTAs
+
+**Tier 2 \u2014 test one representative per type per screen:**
+- Primary action buttons
+- Form inputs and toggles
+- Segmented controls and dropdowns
+
+**Tier 3 \u2014 skip unless visibly broken:**
+- Static labels, decorative images, dividers
+
+If an interaction produces no observable change, retry once before flagging.`;
+var DEAD_END_SECTION = `## Dead End and Modal Detection
+
+**Dead end** \u2014 when \`view_ui\` shows no interactive exit affordance, first consult App Knowledge for gesture-based navigation on this screen, then attempt ALL of before emitting a finding: (1) any visible back/close button, (2) swipe from the left edge (back gesture), (3) swipe down (dismiss gesture). If all fail, emit a \`dead-end\` finding describing what was visible and what was attempted.
+
+**Stuck modal** \u2014 when a modal or bottom sheet blocks the screen, attempt dismissal in order: (1) close/X button if present, (2) tap outside the modal, (3) swipe down, (4) swipe from the left edge. If all fail, emit a \`stuck-modal\` finding listing the modal, the screen it appeared on, and the methods attempted.`;
+var SPEC_WHAT_TO_TEST_SECTION = `## What to Test
+
+Test only the elements and interactions described in the spec. Do not interact with elements outside the spec path.
+
+If you observe obvious breakage while navigating to a spec step \u2014 a broken control, unexpected error, missing screen, or crash \u2014 flag it as a passive observation without stopping to investigate it.`;
+var SPEC_DEAD_END_SECTION = `## Dead End and Modal Detection
+
+**Dead end** \u2014 if a spec step leaves the agent on a screen with no path to the next spec step, attempt: (1) any visible back/close button, (2) swipe from the left edge, (3) swipe down. If all fail, emit a \`dead-end\` finding and halt \u2014 do not attempt further exploration to recover.
+
+**Stuck modal** \u2014 when a modal or bottom sheet blocks spec step execution, attempt dismissal in order: (1) close/X button if present, (2) tap outside the modal, (3) swipe down, (4) swipe from the left edge. If all fail, emit a \`stuck-modal\` finding listing the modal, the screen it appeared on, and the methods attempted.`;
+function buildContextSections(appContext, initialState) {
+  return [
+    appContext ? `## App Knowledge
+
+${appContext}` : void 0,
+    initialState ? `## Initial State
+
+${initialState}` : void 0,
+    WORKING_STATE_SECTION
+  ].filter((section) => section !== void 0).join("\n\n");
+}
+var SPEC_RULES_SECTION = `## Rules
+
+- ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
+- ${BACK_NAV_RULE}
+- Before selecting any action, prefer navigating to a QUEUE screen over re-exploring a VISITED one
+- ${STUCK_LOOP_RULE}
+- ${CLIPPED_ELEMENT_RULE}
+- Each item in \`**Assertions**\` is a mandatory pass/fail check \u2014 verify using \`view_ui\`; if the accessibility tree cannot confirm, emit a \`spec-deviation\` finding based on what is observable
+- Flag crash dialogs, unexpected system errors, or navigation failures that occur as a direct result of executing a spec step; if you observe a visibly broken element in passing while navigating, note it without interacting with it`;
+function buildSpecModeBody({
+  specContent,
+  contextBlock,
+  environmentSection
+}) {
+  return `You are a spec execution agent. Your role is to follow the provided spec exactly \u2014 execute each step in sequence, verify each assertion, and report deviations. Observe and flag obvious breakage encountered in transit, but do not explore or interact with anything outside the spec.
+
+Verify app against specs below.
+
+${contextBlock}
+
+${SPEC_RULES_SECTION}
+
+## Execution Strategy
+
+Execute spec steps in strict sequence. Navigate by the shortest path to each step's target screen. Do not interact with any screen, element, or flow not required by the spec.
+
+${SPEC_WHAT_TO_TEST_SECTION}
+
+${SPEC_DEAD_END_SECTION}
+
+## Specs
+
+${specContent}${environmentSection}
+
+## Output
+
+CRITICAL: Call \`set_output\` each time your findings change \u2014 when you discover something new, confirm a false positive, or revise a finding. Each call replaces the previous output entirely, so always pass the full current list. Do not reply in plain text.`;
+}
+var SPEC_MODE_TEMPLATE = (specContent, options) => {
+  const contextBlock = buildContextSections(options.appContext, options.initialState);
+  const environmentSection = options.buildEnv === "dev" ? `
+
+${DEV_ENVIRONMENT_SECTION}` : "";
+  return buildSpecModeBody({ specContent, contextBlock, environmentSection });
+};
+var FREESTYLE_TEMPLATE = (options) => {
+  const { appContext, initialState, buildEnv } = options ?? {};
+  const contextBlock = buildContextSections(appContext, initialState);
+  const environmentSection = buildEnv === "dev" ? `
+
+${DEV_ENVIRONMENT_SECTION}` : "";
+  return `You are a navigation and interaction testing agent. Your role is to find broken navigation flows and non-functional interactive elements. Do not report content bugs, copy errors, or visual style issues unless they directly prevent a navigation action from completing.
+
+${contextBlock}
+
+## Rules
+
+- ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
+- ${BACK_NAV_RULE}
+- Before selecting any action, prefer navigating to a QUEUE screen over re-exploring a VISITED one
+- ${STUCK_LOOP_RULE}
+- ${CLIPPED_ELEMENT_RULE}
+
+## Exploration Strategy
+
+Explore breadth-first: map all screens reachable from the current screen before descending into any one path. Visit all siblings at the current depth before going deeper.
+
+${WHAT_TO_TEST_SECTION}
+
+${DEAD_END_SECTION}${environmentSection}
+
+## Output
+
+CRITICAL: Call \`set_output\` each time your findings change \u2014 when you discover something new, confirm a false positive, or revise a finding. Each call replaces the previous output entirely, so always pass the full current list. Do not reply in plain text.`;
+};
+function generateExplorerPrompt({
+  mode,
+  specs,
+  appContext,
+  initialState,
+  buildEnv
+}) {
+  return mode === "spec" ? buildSpecModePrompt(specs, { appContext, initialState, buildEnv }) : FREESTYLE_TEMPLATE({ appContext, initialState, buildEnv });
+}
+function renderStep(step, index) {
+  const stepNumber = String(index + 1);
+  const base = `${stepNumber}. ${step.action}`;
+  return step.assertion === void 0 ? base : `${base} \u2192 ${step.assertion}`;
+}
+function collectAssertions(spec) {
+  return spec.assertions;
+}
+function renderSpec(spec) {
+  const stepsBlock = spec.steps.map((step, index) => renderStep(step, index)).join("\n");
+  const allAssertions = collectAssertions(spec);
+  const assertionsBlock = allAssertions.length > 0 ? `
+
+**Assertions**
+${allAssertions.map((assertion) => `- ${assertion}`).join("\n")}` : "";
+  return `### ${spec.name}
+
+**Setup**
+${spec.setup}
+
+**Steps**
+${stepsBlock}${assertionsBlock}`;
+}
+function buildSpecModePrompt(specs, options) {
+  const specContent = specs.map((spec) => renderSpec(spec)).join("\n\n---\n\n");
+  return SPEC_MODE_TEMPLATE(specContent, options);
+}
+var FRONTMATTER_FENCE = "---";
+var INLINE_ASSERTION_DELIMITER = " \u2192 ";
+var NUMBERED_STEP_PREFIX = /^\d+\.\s+/;
+function parseTagsValue(value) {
+  if (!value.startsWith("[") || !value.endsWith("]")) {
+    return (0, import_neverthrow16.err)({ type: "MALFORMED_FRONTMATTER", cause: `Invalid tags format: ${value}` });
+  }
+  return (0, import_neverthrow16.ok)(
+    value.slice(1, -1).split(",").map((tag) => tag.trim()).filter((tag) => tag.length > 0)
+  );
+}
+function parseTimeoutValue(value) {
+  const parsed = Number(value);
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    return (0, import_neverthrow16.err)({ type: "MALFORMED_FRONTMATTER", cause: `Invalid timeout: ${value}` });
+  }
+  return (0, import_neverthrow16.ok)(parsed);
+}
+function parseFrontmatterLine(line) {
+  const colonIndex = line.indexOf(":");
+  if (colonIndex === -1) {
+    return (0, import_neverthrow16.err)({ type: "MALFORMED_FRONTMATTER", cause: `Invalid line: ${line}` });
+  }
+  const key = line.slice(0, colonIndex).trim();
+  const value = line.slice(colonIndex + 1).trim();
+  switch (key) {
+    case "description": {
+      return (0, import_neverthrow16.ok)({ description: value });
+    }
+    case "tags": {
+      return parseTagsValue(value).map((tags) => ({ tags }));
+    }
+    case "timeout": {
+      return parseTimeoutValue(value).map((timeout) => ({ timeout }));
+    }
+    default: {
+      return (0, import_neverthrow16.ok)({});
+    }
+  }
+}
+function normalizeFrontmatter(raw) {
+  return {
+    description: raw.description,
+    tags: raw.tags ?? [],
+    timeout: raw.timeout
+  };
+}
+function emptyFrontmatter() {
+  return { description: void 0, tags: [], timeout: void 0 };
+}
+function mergePartials(partials) {
+  return Object.fromEntries(partials.flatMap((partial2) => Object.entries(partial2)));
+}
+function combineFrontmatterLines(lines) {
+  const lineResults = lines.filter((line) => line.trim().length > 0).map((line) => parseFrontmatterLine(line));
+  return import_neverthrow16.Result.combine(lineResults).map((partials) => mergePartials(partials)).map((merged) => normalizeFrontmatter(merged));
+}
+function extractFrontmatter(content) {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith(FRONTMATTER_FENCE)) {
+    return (0, import_neverthrow16.ok)({ frontmatter: emptyFrontmatter(), body: content });
+  }
+  const afterOpenFence = trimmed.slice(FRONTMATTER_FENCE.length);
+  const closeIndex = afterOpenFence.indexOf(`
+${FRONTMATTER_FENCE}`);
+  if (closeIndex === -1) {
+    return (0, import_neverthrow16.err)({ type: "MALFORMED_FRONTMATTER", cause: "Unclosed frontmatter fence" });
+  }
+  const rawFrontmatter = afterOpenFence.slice(0, closeIndex);
+  const body = afterOpenFence.slice(closeIndex + FRONTMATTER_FENCE.length + 1);
+  return combineFrontmatterLines(rawFrontmatter.split("\n")).map((frontmatter) => ({
+    frontmatter,
+    body
+  }));
+}
+function splitIntoSections(body) {
+  const parts = ("\n" + body).split(/\n## /).slice(1);
+  return Object.fromEntries(
+    parts.map((part) => {
+      const newlineIndex = part.indexOf("\n");
+      const heading = newlineIndex === -1 ? part.trim() : part.slice(0, newlineIndex).trim();
+      const sectionContent = newlineIndex === -1 ? "" : part.slice(newlineIndex + 1).trim();
+      return [heading, sectionContent];
+    })
+  );
+}
+function parseStep(line) {
+  const withoutNumber = line.replace(NUMBERED_STEP_PREFIX, "");
+  const delimiterIndex = withoutNumber.indexOf(INLINE_ASSERTION_DELIMITER);
+  if (delimiterIndex === -1) {
+    return { action: withoutNumber.trim(), assertion: void 0 };
+  }
+  return {
+    action: withoutNumber.slice(0, delimiterIndex).trim(),
+    assertion: withoutNumber.slice(delimiterIndex + INLINE_ASSERTION_DELIMITER.length).trim()
+  };
+}
+function parseSteps(stepsSection) {
+  return stepsSection.split("\n").filter((line) => NUMBERED_STEP_PREFIX.test(line)).map((line) => parseStep(line));
+}
+function parseAssertions(assertionsSection) {
+  return assertionsSection.split("\n").filter((line) => line.startsWith("- ")).map((line) => line.slice(2).trim());
+}
+function parseTestSpec(name, content) {
+  return extractFrontmatter(content).andThen(({ frontmatter, body }) => {
+    const sections = splitIntoSections(body);
+    const setup = sections.Setup;
+    if (setup === void 0) {
+      return (0, import_neverthrow16.err)({ type: "MISSING_SETUP_SECTION" });
+    }
+    const stepsSection = sections.Steps;
+    if (stepsSection === void 0) {
+      return (0, import_neverthrow16.err)({ type: "MISSING_STEPS_SECTION" });
+    }
+    return (0, import_neverthrow16.ok)({
+      name,
+      frontmatter,
+      setup,
+      steps: parseSteps(stepsSection),
+      assertions: sections.Assertions === void 0 ? [] : parseAssertions(sections.Assertions)
+    });
+  });
+}
 var VIEW_UI_TOOL_NAME = "mcp__perception__view_ui";
 var VIEW_UI_DESCRIPTION = `Capture the current screen state: accessibility snapshot (element list with positions) and screenshot. Call this after every action to observe the result.
 
@@ -55898,7 +56210,7 @@ function deriveScreenLabel(tree, stepIndex) {
 }
 async function persistScreenshot(params) {
   const screenshotPath = import_node_path5.default.join(params.screenshotsDirectory, `${params.screenLabel}.png`);
-  const safeWriteFile = (0, import_neverthrow18.fromAsyncThrowable)(
+  const safeWriteFile = (0, import_neverthrow19.fromAsyncThrowable)(
     import_promises10.writeFile,
     (cause) => ({ type: "WRITE_FAILED", cause })
   );
@@ -55963,7 +56275,7 @@ function buildSnapshotRecord(rawElements, { stepIndex, context }) {
 }
 async function handleScreenshotData(data, params) {
   if (params.context.screenshotsDir !== void 0) {
-    const safeWrite2 = (0, import_neverthrow18.fromAsyncThrowable)(
+    const safeWrite2 = (0, import_neverthrow19.fromAsyncThrowable)(
       import_promises10.writeFile,
       (cause) => ({ type: "WRITE_FAILED", cause })
     );
@@ -56133,23 +56445,23 @@ function processMessage(message, state) {
   }
   if (message.type === "result") {
     if (message.subtype !== "success" && !state.timedOut.value && !state.aborted.value) {
-      return (0, import_neverthrow17.err)(message.errors.join("; "));
+      return (0, import_neverthrow18.err)(message.errors.join("; "));
     }
-    return (0, import_neverthrow17.ok)(true);
+    return (0, import_neverthrow18.ok)(true);
   }
-  return (0, import_neverthrow17.ok)(false);
+  return (0, import_neverthrow18.ok)(false);
 }
 async function processMessages(queryRunner, state) {
   for await (const message of queryRunner) {
     const result = processMessage(message, state);
     if (result.isErr()) {
-      return (0, import_neverthrow17.err)(result.error);
+      return (0, import_neverthrow18.err)(result.error);
     }
     if (result.value) {
       break;
     }
   }
-  return (0, import_neverthrow17.ok)(null);
+  return (0, import_neverthrow18.ok)(null);
 }
 var MessageQueue = class {
   pending = [];
@@ -56409,7 +56721,7 @@ var INTERRUPT_DRAIN_TIMEOUT_MS = 1e4;
 async function interruptOrTimeout(queryRunner) {
   await Promise.race([queryRunner.interrupt(), (0, import_promises9.setTimeout)(INTERRUPT_DRAIN_TIMEOUT_MS)]);
 }
-var safeInterruptOrTimeout = import_neverthrow16.ResultAsync.fromThrowable(
+var safeInterruptOrTimeout = import_neverthrow17.ResultAsync.fromThrowable(
   interruptOrTimeout,
   (error48) => error48
 );
@@ -56460,18 +56772,18 @@ function startQueryTimers(config3, context) {
 }
 function awaitMessagesAndResolve({ queryRunner, state }, { cleanup: cleanup2, getOutput }) {
   const messagesPromise = processMessages(queryRunner, state);
-  return import_neverthrow16.ResultAsync.fromPromise(messagesPromise, String).andThen((innerResult) => {
+  return import_neverthrow17.ResultAsync.fromPromise(messagesPromise, String).andThen((innerResult) => {
     cleanup2();
     if (innerResult.isErr()) {
-      return (0, import_neverthrow16.err)(innerResult.error);
+      return (0, import_neverthrow17.err)(innerResult.error);
     }
-    return (0, import_neverthrow16.ok)(getOutput());
+    return (0, import_neverthrow17.ok)(getOutput());
   }).orElse((sdkError) => {
     cleanup2();
     if (!state.timedOut.value && !state.aborted.value) {
-      return (0, import_neverthrow16.err)(sdkError);
+      return (0, import_neverthrow17.err)(sdkError);
     }
-    return (0, import_neverthrow16.ok)(getOutput());
+    return (0, import_neverthrow17.ok)(getOutput());
   });
 }
 function executeQuery({
@@ -56485,9 +56797,9 @@ function executeQuery({
     message: { role: "user", content: prompt },
     parent_tool_use_id: null
   });
-  const queryRunnerResult = (0, import_neverthrow16.fromThrowable)(Qs, String)({ prompt: inputQueue, options });
+  const queryRunnerResult = (0, import_neverthrow17.fromThrowable)(Qs, String)({ prompt: inputQueue, options });
   if (queryRunnerResult.isErr()) {
-    return (0, import_neverthrow16.errAsync)(queryRunnerResult.error);
+    return (0, import_neverthrow17.errAsync)(queryRunnerResult.error);
   }
   const queryRunner = queryRunnerResult.value;
   const cleanup2 = startQueryTimers(config3, { state, queryRunner, inputQueue, linkedController });
@@ -56502,7 +56814,7 @@ function executeQuery({
 function runQuery(prompt, config3) {
   const outputTools = createOutputTool({ findings: external_exports.array(EXPLORER_FINDING_SCHEMA) });
   const setupPromise = setupQuery(config3, outputTools);
-  return import_neverthrow16.ResultAsync.fromPromise(setupPromise, String).andThen(
+  return import_neverthrow17.ResultAsync.fromPromise(setupPromise, String).andThen(
     (setup) => executeQuery({ prompt, config: config3, outputTools, setup })
   );
 }
@@ -56549,25 +56861,25 @@ function direntToSpecEntry(directory, entry) {
   return [];
 }
 function scanDirectory(directory) {
-  const safeReaddir = (0, import_neverthrow19.fromAsyncThrowable)(
+  const safeReaddir2 = (0, import_neverthrow20.fromAsyncThrowable)(
     async () => (0, import_promises11.readdir)(directory, { withFileTypes: true }),
     (cause) => ({ type: "DIR_READ_FAILED", dir: directory, cause })
   );
-  return safeReaddir().orElse((error48) => isNotFound(error48.cause) ? (0, import_neverthrow19.okAsync)([]) : (0, import_neverthrow19.errAsync)(error48)).map(
+  return safeReaddir2().orElse((error48) => isNotFound(error48.cause) ? (0, import_neverthrow20.okAsync)([]) : (0, import_neverthrow20.errAsync)(error48)).map(
     (entries) => entries.flatMap((entry) => direntToSpecEntry(directory, entry))
   );
 }
 function readEntries(entries) {
-  return import_neverthrow19.ResultAsync.combine(entries.map((entry) => readEntry(entry))).map(
+  return import_neverthrow20.ResultAsync.combine(entries.map((entry) => readEntry(entry))).map(
     (results) => results.flat()
   );
 }
 function readEntry(entry) {
-  const safeReadFile5 = (0, import_neverthrow19.fromAsyncThrowable)(
+  const safeReadFile5 = (0, import_neverthrow20.fromAsyncThrowable)(
     async () => (0, import_promises11.readFile)(entry.path, "utf8"),
     (cause) => ({ type: "FILE_READ_FAILED", path: entry.path, cause })
   );
-  return safeReadFile5().map((content) => [{ name: entry.name, content }]).orElse((error48) => entry.required ? (0, import_neverthrow19.errAsync)(error48) : (0, import_neverthrow19.okAsync)([]));
+  return safeReadFile5().map((content) => [{ name: entry.name, content }]).orElse((error48) => entry.required ? (0, import_neverthrow20.errAsync)(error48) : (0, import_neverthrow20.okAsync)([]));
 }
 function specNameFromPath(filePath) {
   const parts = filePath.split("/");
@@ -56583,132 +56895,6 @@ function filterByNames(specs, specNames) {
   }
   return specs.filter((spec) => specNames.includes(spec.name));
 }
-var DEV_ENVIRONMENT_SECTION = `## Environment
-
-This is a development build. Debug overlays and internal messages are expected artifacts \u2014 do not report them as findings.`;
-var WORKING_STATE_SECTION = `## Working State
-
-At every reasoning step, maintain a mental ledger:
-- VISITED: screen names confirmed via \`view_ui\` this session
-- QUEUE: screen names seen as reachable but not yet explored
-- PATH: your current navigation stack from root (e.g. Home > Settings > Privacy)
-
-Consult the ledger before every action. Always prefer navigating to a QUEUE screen over a VISITED one.`;
-var BACK_NAV_RULE = `- After navigating forward to any new screen: tap back, call \`view_ui\`, confirm you returned to the expected parent in PATH \u2014 if not, emit a \`back-nav-failure\` finding, then navigate forward again to continue`;
-var STUCK_LOOP_RULE = `- Stuck loop: emit a \`stuck-loop\` finding when any of these occur: (1) \`view_ui\` returns the same screen state 3 or more consecutive steps, (2) the same element has been tapped more than twice with no screen change, (3) PATH shows the same screen at two non-adjacent positions \u2014 before emitting, try one alternative action (scroll, long-press, swipe) to rule out a gesture mismatch`;
-var CLIPPED_ELEMENT_RULE = `- Never tap an element tagged \`[clipped-top]\`, \`[clipped-bottom]\`, \`[clipped-left]\`, or \`[clipped-right]\` \u2014 scroll to fully reveal it first, then re-call \`view_ui\` before tapping`;
-var WHAT_TO_TEST_SECTION = `## What to Test
-
-Test navigation elements first, interactions second.
-
-**Tier 1 \u2014 test every one, every time:**
-- Tab bar items, drawer menu items, hamburger menus
-- Back buttons, close buttons (X), modal dismiss controls
-- Bottom sheet handles and drag gestures
-- Navigation links and "Go to X" CTAs
-
-**Tier 2 \u2014 test one representative per type per screen:**
-- Primary action buttons
-- Form inputs and toggles
-- Segmented controls and dropdowns
-
-**Tier 3 \u2014 skip unless visibly broken:**
-- Static labels, decorative images, dividers
-
-If an interaction produces no observable change, retry once before flagging.`;
-var DEAD_END_SECTION = `## Dead End and Modal Detection
-
-**Dead end** \u2014 when \`view_ui\` shows no interactive exit affordance, attempt ALL of before emitting a finding: (1) any visible back/close button, (2) swipe from the left edge (back gesture), (3) swipe down (dismiss gesture). If all fail, emit a \`dead-end\` finding describing what was visible and what was attempted.
-
-**Stuck modal** \u2014 when a modal or bottom sheet blocks the screen, attempt dismissal in order: (1) close/X button if present, (2) tap outside the modal, (3) swipe down, (4) swipe from the left edge. If all fail, emit a \`stuck-modal\` finding listing the modal, the screen it appeared on, and the methods attempted.`;
-var SPEC_MODE_TEMPLATE = (specContent, options) => {
-  const appSection = options.userPrompt ? `## Application
-
-${options.userPrompt}
-
-` : "";
-  const environmentSection = options.buildEnv === "dev" ? `
-
-${DEV_ENVIRONMENT_SECTION}` : "";
-  return `You are a navigation and interaction testing agent. Your role is to find broken navigation flows and non-functional interactive elements. Do not report content bugs, copy errors, or visual style issues unless they directly prevent a navigation action from completing.
-
-Verify app against specs below.
-
-${appSection}${WORKING_STATE_SECTION}
-
-## Rules
-
-- ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
-- ${BACK_NAV_RULE.slice(2)}
-- Before selecting any action, prefer navigating to a QUEUE screen over re-exploring a VISITED one
-- ${STUCK_LOOP_RULE.slice(2)}
-- ${CLIPPED_ELEMENT_RULE.slice(2)}
-- Each item in \`## Assertions\` is a mandatory pass/fail check \u2014 verify using \`view_ui\` first; fall back to \`screenshot\` only when no accessibility node is present
-
-## Exploration Strategy
-
-Navigate to verify each spec's scenarios. When choosing how to reach a screen, prefer breadth-first paths \u2014 map sibling screens before going deeper into any one branch.
-
-${WHAT_TO_TEST_SECTION}
-
-${DEAD_END_SECTION}
-
-## Specs
-
-${specContent}${environmentSection}
-
-## Output
-
-CRITICAL: Call \`set_output\` each time your findings change \u2014 when you discover something new, confirm a false positive, or revise a finding. Each call replaces the previous output entirely, so always pass the full current list. Do not reply in plain text.`;
-};
-var FREESTYLE_TEMPLATE = (options) => {
-  const { userPrompt, buildEnv } = options ?? {};
-  const appSection = userPrompt ? `## Application
-
-${userPrompt}
-
-` : "";
-  const environmentSection = buildEnv === "dev" ? `
-
-${DEV_ENVIRONMENT_SECTION}` : "";
-  return `You are a navigation and interaction testing agent. Your role is to find broken navigation flows and non-functional interactive elements. Do not report content bugs, copy errors, or visual style issues unless they directly prevent a navigation action from completing.
-
-${appSection}${WORKING_STATE_SECTION}
-
-## Rules
-
-- ALWAYS call \`view_ui\` after every action before deciding what to do next \u2014 it is your only way to observe the screen
-- ${BACK_NAV_RULE.slice(2)}
-- Before selecting any action, prefer navigating to a QUEUE screen over re-exploring a VISITED one
-- ${STUCK_LOOP_RULE.slice(2)}
-- ${CLIPPED_ELEMENT_RULE.slice(2)}
-
-## Exploration Strategy
-
-Explore breadth-first: map all screens reachable from the current screen before descending into any one path. Visit all siblings at the current depth before going deeper.
-
-${WHAT_TO_TEST_SECTION}
-
-${DEAD_END_SECTION}${environmentSection}
-
-## Output
-
-CRITICAL: Call \`set_output\` each time your findings change \u2014 when you discover something new, confirm a false positive, or revise a finding. Each call replaces the previous output entirely, so always pass the full current list. Do not reply in plain text.`;
-};
-function generateExplorerPrompt({
-  mode,
-  specs,
-  userPrompt,
-  buildEnv
-}) {
-  return mode === "spec" ? buildSpecModePrompt(specs, { userPrompt, buildEnv }) : FREESTYLE_TEMPLATE({ userPrompt, buildEnv });
-}
-function buildSpecModePrompt(specs, options) {
-  const specContent = specs.map((spec) => `### ${spec.name}
-
-${spec.content}`).join("\n\n---\n\n");
-  return SPEC_MODE_TEMPLATE(specContent, options);
-}
 var SPEED_2X = 2;
 var SPEED_4X = 4;
 var ISO_DATE_LENGTH = 10;
@@ -56716,10 +56902,20 @@ function buildPrompt(safeConfig, specs) {
   return generateExplorerPrompt({
     mode: safeConfig.mode,
     specs,
-    userPrompt: safeConfig.userPrompt,
+    appContext: safeConfig.appContext,
+    initialState: safeConfig.initialState,
     buildEnv: safeConfig.buildEnv
   });
 }
+function parseSpecs(resolvedSpecs) {
+  return import_neverthrow15.Result.combine(
+    resolvedSpecs.map(
+      (spec) => parseTestSpec(spec.name, spec.content).mapErr(
+        (cause) => ({ type: "SPEC_PARSE_FAILED", specName: spec.name, cause })
+      )
+    )
+  );
+}
 function toArtifacts(result, runPaths) {
   return {
     findings: result.findings,
@@ -56752,12 +56948,18 @@ function collectAndFinalize({
     return error48;
   });
 }
+function resolveAndParseSpecs(safeConfig) {
+  if (safeConfig.mode === "freestyle") {
+    return (0, import_neverthrow15.okAsync)([]);
+  }
+  return resolveSpecs(safeConfig).mapErr((cause) => ({ type: "SPEC_RESOLVE_FAILED", cause })).andThen((specs) => parseSpecs(specs));
+}
 function runPipeline({
   safeConfig,
   runPaths,
   start
 }) {
-  return resolveSpecs(safeConfig).mapErr((cause) => ({ type: "SPEC_RESOLVE_FAILED", cause })).map((specs) => buildPrompt(safeConfig, specs)).map((prompt) => {
+  return resolveAndParseSpecs(safeConfig).map((parsedSpecs) => buildPrompt(safeConfig, parsedSpecs)).map((prompt) => {
     safeConfig.onEvent?.({ type: "SYSTEM_PROMPT", agent: "explorer", prompt });
     return prompt;
   }).andThen((prompt) => collectAndFinalize({ safeConfig, prompt, runPaths, start }));
@@ -56841,17 +57043,17 @@ function runWithRecording(handle, collectOutput) {
 }
 
 // ../../packages/pipeline/dist/index.js
-var import_neverthrow31 = __toESM(require_index_cjs(), 1);
+var import_neverthrow32 = __toESM(require_index_cjs(), 1);
 
 // ../../agents/inspector/dist/index.js
-var import_neverthrow20 = __toESM(require_index_cjs(), 1);
-var import_promises12 = require("node:fs/promises");
 var import_neverthrow21 = __toESM(require_index_cjs(), 1);
+var import_promises12 = require("node:fs/promises");
 var import_neverthrow22 = __toESM(require_index_cjs(), 1);
 var import_neverthrow23 = __toESM(require_index_cjs(), 1);
 var import_neverthrow24 = __toESM(require_index_cjs(), 1);
-var import_sharp2 = __toESM(require("sharp"), 1);
 var import_neverthrow25 = __toESM(require_index_cjs(), 1);
+var import_sharp2 = __toESM(require("sharp"), 1);
+var import_neverthrow26 = __toESM(require_index_cjs(), 1);
 var import_promises13 = require("node:fs/promises");
 var import_node_path7 = __toESM(require("node:path"), 1);
 
@@ -59480,7 +59682,7 @@ var jsYaml = {
 };
 
 // ../../agents/inspector/dist/index.js
-var import_neverthrow26 = __toESM(require_index_cjs(), 1);
+var import_neverthrow27 = __toESM(require_index_cjs(), 1);
 var MS_PER_DAY = 864e5;
 function checkStaleness({ lastUpdated, thresholdDays, now }) {
   if (!lastUpdated) {
@@ -59557,7 +59759,7 @@ function mapRawFinding(item) {
 function parseJson(raw) {
   return JSON.parse(raw);
 }
-var safeJsonParse2 = (0, import_neverthrow23.fromThrowable)(parseJson);
+var safeJsonParse2 = (0, import_neverthrow24.fromThrowable)(parseJson);
 function parseClaudeResponse(raw) {
   const parseResult = safeJsonParse2(raw);
   if (parseResult.isErr()) {
@@ -59584,7 +59786,7 @@ async function downscaleBuffer(buffer) {
   return (0, import_sharp2.default)(buffer).resize({ width: targetWidth }).toBuffer();
 }
 function downscale(buffer) {
-  return (0, import_neverthrow24.fromAsyncThrowable)(
+  return (0, import_neverthrow25.fromAsyncThrowable)(
     downscaleBuffer,
     (cause) => ({ type: "CLAUDE_API_FAILED", cause })
   )(buffer);
@@ -59657,7 +59859,7 @@ async function fetchClaudeText({
   return block?.type === "text" ? block.text : "";
 }
 function callClaude(options) {
-  return (0, import_neverthrow22.fromAsyncThrowable)(
+  return (0, import_neverthrow23.fromAsyncThrowable)(
     fetchClaudeText,
     (cause) => ({ type: "CLAUDE_API_FAILED", cause })
   )(options);
@@ -59669,9 +59871,9 @@ function toFindings(text) {
   const cleaned = stripCodeFences(text);
   const findings = parseClaudeResponse(cleaned);
   if (!findings) {
-    return (0, import_neverthrow22.errAsync)({ type: "CLAUDE_RESPONSE_INVALID", raw: cleaned });
+    return (0, import_neverthrow23.errAsync)({ type: "CLAUDE_RESPONSE_INVALID", raw: cleaned });
   }
-  return (0, import_neverthrow22.okAsync)(findings);
+  return (0, import_neverthrow23.okAsync)(findings);
 }
 function buildResolveMessages(screenshotBase64, artboardNames) {
   return [
@@ -59708,12 +59910,12 @@ async function fetchResolveName({
 }
 function resolveArtboard(screenshot, artboardNames) {
   if (artboardNames.length === 0) {
-    return (0, import_neverthrow22.okAsync)(void 0);
+    return (0, import_neverthrow23.okAsync)(void 0);
   }
   const anthropic = new Anthropic();
   return downscale(screenshot).andThen((scaled) => {
     const screenshotBase64 = scaled.toString("base64");
-    return (0, import_neverthrow22.fromAsyncThrowable)(
+    return (0, import_neverthrow23.fromAsyncThrowable)(
       fetchResolveName,
       (cause) => ({ type: "CLAUDE_API_FAILED", cause })
     )({ anthropic, screenshotBase64, artboardNames }).map((name) => {
@@ -59776,7 +59978,7 @@ var SEVERITY_CONFIDENCE = {
   medium: CONFIDENCE_MEDIUM2,
   low: CONFIDENCE_LOW2
 };
-var safeJsonParse22 = (0, import_neverthrow25.fromThrowable)(JSON.parse);
+var safeJsonParse22 = (0, import_neverthrow26.fromThrowable)(JSON.parse);
 function buildFindCandidatesMessages(screenshotBase64, artboardNames) {
   return [
     {
@@ -59823,12 +60025,12 @@ async function fetchCandidateNames({
 }
 function findCandidates(screenshot, artboardNames) {
   if (artboardNames.length === 0) {
-    return (0, import_neverthrow25.okAsync)([]);
+    return (0, import_neverthrow26.okAsync)([]);
   }
   const anthropic = new Anthropic();
   return downscale(screenshot).andThen((scaled) => {
     const screenshotBase64 = scaled.toString("base64");
-    return (0, import_neverthrow25.fromAsyncThrowable)(
+    return (0, import_neverthrow26.fromAsyncThrowable)(
       fetchCandidateNames,
       (cause) => ({ type: "CLAUDE_API_FAILED", cause })
     )({ anthropic, screenshotBase64, artboardNames });
@@ -59906,14 +60108,14 @@ async function fetchDesignContextText({
 function toDesignContextFindings(text) {
   const findings = parseConservativeResponse(text);
   if (!findings) {
-    return (0, import_neverthrow25.errAsync)({ type: "CLAUDE_RESPONSE_INVALID", raw: text });
+    return (0, import_neverthrow26.errAsync)({ type: "CLAUDE_RESPONSE_INVALID", raw: text });
   }
-  return (0, import_neverthrow25.okAsync)(findings);
+  return (0, import_neverthrow26.okAsync)(findings);
 }
 async function downscaleAll(buffers) {
   return Promise.all(buffers.map(async (buf) => downscaleBuffer(buf)));
 }
-var downscaleAllBuffers = (0, import_neverthrow25.fromAsyncThrowable)(
+var downscaleAllBuffers = (0, import_neverthrow26.fromAsyncThrowable)(
   downscaleAll,
   (cause) => ({ type: "CLAUDE_API_FAILED", cause })
 );
@@ -59923,7 +60125,7 @@ function compareWithDesignContext(screenshot, artboards) {
     const screenshotBase64 = scaledScreenshot.toString("base64");
     return downscaleAllBuffers(artboards).andThen((scaledArtboards) => {
       const artboardBase64s = scaledArtboards.map((buf) => buf.toString("base64"));
-      return (0, import_neverthrow25.fromAsyncThrowable)(
+      return (0, import_neverthrow26.fromAsyncThrowable)(
         fetchDesignContextText,
         (cause) => ({ type: "CLAUDE_API_FAILED", cause })
       )({ anthropic, screenshotBase64, artboardBase64s }).andThen(toDesignContextFindings);
@@ -60156,7 +60358,7 @@ async function initArtboardNames({ designStore, config: config3, state }) {
   return state.artboardNamesPromise;
 }
 function readScreenshot(screenshotPath, stepIndex) {
-  return import_neverthrow21.ResultAsync.fromThrowable(
+  return import_neverthrow22.ResultAsync.fromThrowable(
     import_promises12.readFile,
     (cause) => ({ type: "SCREENSHOT_READ_FAILED", stepIndex, cause })
   )(screenshotPath);
@@ -60231,7 +60433,7 @@ function buildInspector(state, context) {
       const { promise: promise2, resolve } = Promise.withResolvers();
       state.resolve = resolve;
       applyTryResolve(state);
-      return (0, import_neverthrow20.fromSafePromise)(promise2);
+      return (0, import_neverthrow21.fromSafePromise)(promise2);
     }
   };
 }
@@ -60255,10 +60457,10 @@ async function readAndParseSidecar(sidecarPath) {
   return parseMeta(raw);
 }
 function readSidecarFile(sidecarPath) {
-  return (0, import_neverthrow26.fromAsyncThrowable)(
+  return (0, import_neverthrow27.fromAsyncThrowable)(
     readAndParseSidecar,
     () => ({})
-  )(sidecarPath).orElse(() => (0, import_neverthrow26.okAsync)({}));
+  )(sidecarPath).orElse(() => (0, import_neverthrow27.okAsync)({}));
 }
 function isEnoent(error48) {
   return error48?.code === "ENOENT";
@@ -60267,13 +60469,13 @@ function wrapFsError(cause) {
   return { type: "FS_ERROR", cause };
 }
 function toFsError(fsError) {
-  return (0, import_neverthrow26.errAsync)(fsError);
+  return (0, import_neverthrow27.errAsync)(fsError);
 }
 function missingBuffer() {
-  return (0, import_neverthrow26.okAsync)(void 0);
+  return (0, import_neverthrow27.okAsync)(void 0);
 }
 function missingArtboard() {
-  return (0, import_neverthrow26.okAsync)(void 0);
+  return (0, import_neverthrow27.okAsync)(void 0);
 }
 var FsDesignStore = class {
   designsDirectory;
@@ -60281,12 +60483,12 @@ var FsDesignStore = class {
     this.designsDirectory = designsDirectory;
   }
   listArtboards() {
-    return (0, import_neverthrow26.fromAsyncThrowable)(
+    return (0, import_neverthrow27.fromAsyncThrowable)(
       import_promises13.readdir,
       wrapFsError
     )(this.designsDirectory).orElse((fsError) => {
       if (fsError.type === "FS_ERROR" && isEnoent(fsError.cause)) {
-        return (0, import_neverthrow26.okAsync)([]);
+        return (0, import_neverthrow27.okAsync)([]);
       }
       return toFsError(fsError);
     }).map(
@@ -60296,7 +60498,7 @@ var FsDesignStore = class {
   getArtboard(filename) {
     const pngPath = import_node_path7.default.join(this.designsDirectory, `${filename}.png`);
     const sidecarPath = import_node_path7.default.join(this.designsDirectory, `${filename}.meta.yaml`);
-    return (0, import_neverthrow26.fromAsyncThrowable)(
+    return (0, import_neverthrow27.fromAsyncThrowable)(
       import_promises13.readFile,
       wrapFsError
     )(pngPath).orElse((fsError) => {
@@ -60323,10 +60525,10 @@ function attemptRetry(options) {
   const { factory, config: config3, delayFunction, onRetry, attempt } = options;
   return factory().orElse((error48) => {
     if (attempt >= config3.maxAttempts) {
-      return (0, import_neverthrow29.errAsync)(error48);
+      return (0, import_neverthrow30.errAsync)(error48);
     }
     const delay = config3.baseDelayMs * Math.pow(2, attempt - 1);
-    return import_neverthrow29.ResultAsync.fromPromise(
+    return import_neverthrow30.ResultAsync.fromPromise(
       (onRetry?.({ attempt, maxAttempts: config3.maxAttempts, delayMs: delay, error: error48 }), delayFunction(delay)),
       () => error48
     ).andThen(
@@ -60346,7 +60548,7 @@ function withRetry(factory, options) {
 var CONSOLIDATOR_AGENT = "consolidator";
 function analyserFallback(artifacts, onEvent) {
   onEvent?.({ type: "AGENT_FAILED_NON_CRITICAL", agent: "analyser", attempts: RETRY_MAX_ATTEMPTS });
-  return (0, import_neverthrow28.okAsync)(artifacts.findings);
+  return (0, import_neverthrow29.okAsync)(artifacts.findings);
 }
 function runAnalyserWithRetry(params) {
   const { artifacts, config: config3, onEvent } = params;
@@ -60376,7 +60578,7 @@ function resolveVisualFindings({
   onEvent
 }) {
   if (config3.analyser === void 0 || config3.signal?.aborted) {
-    return (0, import_neverthrow28.okAsync)(artifacts.findings);
+    return (0, import_neverthrow29.okAsync)(artifacts.findings);
   }
   return runAnalyserWithRetry({ artifacts, config: config3, onEvent });
 }
@@ -60386,7 +60588,7 @@ function unmergedFallback(allFindings, onEvent) {
     agent: CONSOLIDATOR_AGENT,
     message: "Consolidation failed, returning unmerged findings"
   });
-  return (0, import_neverthrow28.okAsync)({ findings: allFindings, dismissed: [] });
+  return (0, import_neverthrow29.okAsync)({ findings: allFindings, dismissed: [] });
 }
 function mergeWithFallback(options) {
   const {
@@ -60413,7 +60615,7 @@ function consolidate(options) {
   const { artifacts, inspectorFindings, runId, dismissals, config: config3, consolidatorConfig, onEvent } = options;
   return resolveVisualFindings({ artifacts, config: config3, onEvent }).andThen((visualFindings) => {
     if (config3.signal?.aborted) {
-      return (0, import_neverthrow28.okAsync)({ findings: artifacts.findings, dismissed: [] });
+      return (0, import_neverthrow29.okAsync)({ findings: artifacts.findings, dismissed: [] });
     }
     return mergeWithFallback({
       artifacts,
@@ -60426,8 +60628,8 @@ function consolidate(options) {
     });
   });
 }
-var safeReadFile = (0, import_neverthrow30.fromThrowable)((filePath) => (0, import_node_fs3.readFileSync)(filePath, "utf8"));
-var safeParseJson = (0, import_neverthrow30.fromThrowable)(JSON.parse);
+var safeReadFile = (0, import_neverthrow31.fromThrowable)((filePath) => (0, import_node_fs3.readFileSync)(filePath, "utf8"));
+var safeParseJson = (0, import_neverthrow31.fromThrowable)(JSON.parse);
 function isEnoent2(error48) {
   if (!(error48 instanceof Error)) {
     return false;
@@ -60439,19 +60641,19 @@ function loadDismissals(filePath) {
   const readResult = safeReadFile(filePath);
   if (readResult.isErr()) {
     if (isEnoent2(readResult.error)) {
-      return (0, import_neverthrow30.ok)([]);
+      return (0, import_neverthrow31.ok)([]);
     }
-    return (0, import_neverthrow30.err)({ type: "DISMISSALS_LOAD_FAILED", cause: readResult.error });
+    return (0, import_neverthrow31.err)({ type: "DISMISSALS_LOAD_FAILED", cause: readResult.error });
   }
   return safeParseJson(readResult.value).mapErr((cause) => ({ type: "DISMISSALS_LOAD_FAILED", cause })).andThen((data) => {
     const store = data;
     if (!Array.isArray(store.dismissed)) {
-      return (0, import_neverthrow30.err)({
+      return (0, import_neverthrow31.err)({
         type: "DISMISSALS_LOAD_FAILED",
         cause: "invalid shape: dismissed is not an array"
       });
     }
-    return (0, import_neverthrow30.ok)(store.dismissed);
+    return (0, import_neverthrow31.ok)(store.dismissed);
   });
 }
 function toInspectorStepEvent(event) {
@@ -60521,7 +60723,7 @@ function runExplorerWithTeardown(explorerConfig, udid) {
   return runExplorer(explorerConfig).mapErr((cause) => ({ type: "EXPLORER_FAILED", cause })).andThen(
     (artifacts) => disableTouchIndicators(udid).mapErr(toSimulatorError).map(() => artifacts)
   ).orElse(
-    (error48) => disableTouchIndicators(udid).mapErr(toSimulatorError).andThen(() => (0, import_neverthrow31.errAsync)(error48)).orElse(() => (0, import_neverthrow31.errAsync)(error48))
+    (error48) => disableTouchIndicators(udid).mapErr(toSimulatorError).andThen(() => (0, import_neverthrow32.errAsync)(error48)).orElse(() => (0, import_neverthrow32.errAsync)(error48))
   );
 }
 function runExplorerWithRetry(options) {
@@ -60547,12 +60749,12 @@ async function drainAfterExplorer(options) {
   inspector?.close();
   const inspectorFindings = inspector ? await collectInspectorFindings({ inspector, onEvent, totalSteps: enqueuedCount.value }) : [];
   if (explorerResult.isErr()) {
-    return (0, import_neverthrow31.err)(explorerResult.error);
+    return (0, import_neverthrow32.err)(explorerResult.error);
   }
-  return (0, import_neverthrow31.ok)({ artifacts: explorerResult.value, inspectorFindings });
+  return (0, import_neverthrow32.ok)({ artifacts: explorerResult.value, inspectorFindings });
 }
 function runExplorerAndDrain(options) {
-  return new import_neverthrow31.ResultAsync(drainAfterExplorer(options));
+  return new import_neverthrow32.ResultAsync(drainAfterExplorer(options));
 }
 var require2 = (0, import_node_module.createRequire)(__importMetaUrl);
 function createMobileMcpServer() {
@@ -60570,7 +60772,7 @@ function runAnalysis(artifacts, config3) {
 }
 var ISO_DATE_LENGTH2 = 10;
 var RUN_ID_PAD_LENGTH = 4;
-var safeReaddirSync = (0, import_neverthrow27.fromThrowable)((directory) => (0, import_node_fs2.readdirSync)(directory));
+var safeReaddirSync = (0, import_neverthrow28.fromThrowable)((directory) => (0, import_node_fs2.readdirSync)(directory));
 function nextRunId(outputDirectory, date5) {
   const entries = safeReaddirSync(`${outputDirectory}/${date5}`).unwrapOr([]);
   let max = 0;
@@ -60582,7 +60784,7 @@ function nextRunId(outputDirectory, date5) {
   }
   return String(max + 1).padStart(RUN_ID_PAD_LENGTH, "0");
 }
-var writeOutputFile = (0, import_neverthrow27.fromThrowable)(
+var writeOutputFile = (0, import_neverthrow28.fromThrowable)(
   (params) => {
     const { findingsPath, outputDirectory, json: json3 } = params;
     (0, import_node_fs2.mkdirSync)(outputDirectory, { recursive: true });
@@ -60595,15 +60797,15 @@ function validatePipelineConfig(config3) {
   const runId = config3.runId ?? nextRunId(config3.outputDir, date5);
   const runPathsResult = resolveRunPaths({ outputDirectory: config3.outputDir, runId, date: date5 });
   if (runPathsResult.isErr()) {
-    return (0, import_neverthrow27.err)({ type: "RUN_PATHS_FAILED", cause: runPathsResult.error });
+    return (0, import_neverthrow28.err)({ type: "RUN_PATHS_FAILED", cause: runPathsResult.error });
   }
   const dismissalsResult = loadDismissals(
     dismissalsPath(config3.outputDir, process.env.QA_DISMISSALS_PATH)
   );
   if (dismissalsResult.isErr()) {
-    return (0, import_neverthrow27.err)(dismissalsResult.error);
+    return (0, import_neverthrow28.err)(dismissalsResult.error);
   }
-  return (0, import_neverthrow27.ok)({ runId, date: date5, runPaths: runPathsResult.value, dismissals: dismissalsResult.value });
+  return (0, import_neverthrow28.ok)({ runId, date: date5, runPaths: runPathsResult.value, dismissals: dismissalsResult.value });
 }
 function buildExplorerConfig({
   config: config3,
@@ -60638,11 +60840,11 @@ function buildOutput(consolidationResult, options) {
 function buildPipelineSetup(config3) {
   const validatedResult = validatePipelineConfig(config3);
   if (validatedResult.isErr()) {
-    return (0, import_neverthrow27.err)(validatedResult.error);
+    return (0, import_neverthrow28.err)(validatedResult.error);
   }
   const { runId, date: date5, runPaths, dismissals } = validatedResult.value;
   const { inspector, explorerOnEvent, enqueuedCount } = buildInspectorSetup(config3);
-  return (0, import_neverthrow27.ok)({
+  return (0, import_neverthrow28.ok)({
     runId,
     udid: config3.simulatorUdid ?? "booted",
     runPaths,
@@ -60686,19 +60888,19 @@ function executePipeline(setup, config3) {
 function runPipeline2(config3) {
   const setupResult = buildPipelineSetup(config3);
   if (setupResult.isErr()) {
-    return (0, import_neverthrow27.errAsync)(setupResult.error);
+    return (0, import_neverthrow28.errAsync)(setupResult.error);
   }
   return executePipeline(setupResult.value, config3);
 }
 
 // src/commands/analyse-command.ts
-var import_neverthrow32 = __toESM(require_index_cjs(), 1);
+var import_neverthrow33 = __toESM(require_index_cjs(), 1);
 var JSON_INDENT = 2;
 function buildArtifacts(videoPath) {
   return { videoPath, videoPath2x: "", videoPath4x: videoPath, findings: [], snapshots: [] };
 }
 async function checkVideoPathExists(videoPath) {
-  const safeAccess = (0, import_neverthrow32.fromAsyncThrowable)(import_promises16.access, () => ({ type: "FILE_NOT_FOUND" }));
+  const safeAccess = (0, import_neverthrow33.fromAsyncThrowable)(import_promises16.access, () => ({ type: "FILE_NOT_FOUND" }));
   const result = await safeAccess(videoPath);
   return result.isOk();
 }
@@ -60742,7 +60944,7 @@ async function runAnalyseCommand(videoPath, config3) {
 }
 
 // src/core/completion-generator.ts
-var import_neverthrow33 = __toESM(require_index_cjs(), 1);
+var import_neverthrow34 = __toESM(require_index_cjs(), 1);
 function extractLongFlags(flags) {
   return flags.split(/[\s,]+/).filter((token) => token.startsWith("--"));
 }
@@ -60832,9 +61034,9 @@ complete -F _xqa_completion xqa`;
 }
 function generateCompletion(commands, shell) {
   if (shell !== "bash" && shell !== "zsh") {
-    return (0, import_neverthrow33.err)({ type: "UNSUPPORTED_SHELL", shell });
+    return (0, import_neverthrow34.err)({ type: "UNSUPPORTED_SHELL", shell });
   }
-  return (0, import_neverthrow33.ok)(shell === "zsh" ? generateZshCompletion(commands) : generateBashCompletion(commands));
+  return (0, import_neverthrow34.ok)(shell === "zsh" ? generateZshCompletion(commands) : generateBashCompletion(commands));
 }
 
 // src/commands/completion-command.ts
@@ -60893,16 +61095,16 @@ var DEFAULT_ABORT_EXIT_CODE = 130;
 // src/core/last-path.ts
 var import_node_fs4 = require("node:fs");
 var import_node_path8 = __toESM(require("node:path"), 1);
-var import_neverthrow34 = __toESM(require_index_cjs(), 1);
+var import_neverthrow35 = __toESM(require_index_cjs(), 1);
 function resolveLastPath(argument, stateContent) {
   if (argument !== void 0) {
-    return (0, import_neverthrow34.ok)(argument);
+    return (0, import_neverthrow35.ok)(argument);
   }
   const trimmed = stateContent?.trim();
   if (trimmed) {
-    return (0, import_neverthrow34.ok)(trimmed);
+    return (0, import_neverthrow35.ok)(trimmed);
   }
-  return (0, import_neverthrow34.err)({ type: "NO_ARG_AND_NO_STATE" });
+  return (0, import_neverthrow35.err)({ type: "NO_ARG_AND_NO_STATE" });
 }
 function lastPathFilePath(xqaDirectoryectory) {
   return import_node_path8.default.join(xqaDirectoryectory, "last-findings-path");
@@ -60911,53 +61113,61 @@ function writeLastPath(xqaDirectory, findingsPath) {
   (0, import_node_fs4.writeFileSync)(lastPathFilePath(xqaDirectory), findingsPath);
 }
 
-// src/shell/instructions.ts
+// src/shell/app-context.ts
 var import_promises17 = require("node:fs/promises");
 var import_node_path9 = __toESM(require("node:path"), 1);
-var import_neverthrow35 = __toESM(require_index_cjs(), 1);
+var import_neverthrow36 = __toESM(require_index_cjs(), 1);
 var HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
 function isEnoentError(value) {
   return value !== null && typeof value === "object" && "code" in value && value.code === "ENOENT";
 }
-function toInstructionsError(cause) {
+function toAppContextError(cause) {
   return { type: "READ_FAILED", cause };
 }
-function absentInstructions() {
+function absentContext() {
   const absent = void 0;
-  return (0, import_neverthrow35.ok)(absent);
+  return (0, import_neverthrow36.ok)(absent);
 }
-var safeReadFile2 = import_neverthrow35.ResultAsync.fromThrowable(
+var safeReadFile2 = import_neverthrow36.ResultAsync.fromThrowable(
   async (filePath) => (0, import_promises17.readFile)(filePath, "utf8"),
-  toInstructionsError
+  toAppContextError
 );
 function stripAndNormalize(content) {
   const stripped = content.replaceAll(HTML_COMMENT_PATTERN, "").trim();
   return stripped.length === 0 ? void 0 : stripped;
 }
-function readInstructions(xqaDirectory) {
-  const filePath = import_node_path9.default.join(xqaDirectory, "instructions.md");
+function readContextFile(xqaDirectory, filename) {
+  const filePath = import_node_path9.default.join(xqaDirectory, filename);
   return safeReadFile2(filePath).map((content) => stripAndNormalize(content)).orElse((error48) => {
     if (isEnoentError(error48.cause)) {
-      return absentInstructions();
+      return absentContext();
     }
-    return (0, import_neverthrow35.err)(error48);
+    return (0, import_neverthrow36.err)(error48);
   });
 }
+function readAppContext(xqaDirectory) {
+  return readContextFile(xqaDirectory, "app.md");
+}
+function readExploreContext(xqaDirectory) {
+  return readContextFile(xqaDirectory, "explore.md");
+}
 
 // src/commands/explore-command.ts
 function buildExplorerConfig2({
   input,
   config: config3,
-  instructions
+  appContext,
+  initialState
 }) {
-  const parts = [instructions, input.prompt].filter(Boolean);
-  const userPrompt = parts.length > 0 ? parts.join("\n\n") : void 0;
+  const parts = [initialState, input.prompt].filter(Boolean);
+  const resolvedStartingState = parts.length > 0 ? parts.join("\n\n") : void 0;
   return {
     mode: "freestyle",
     mcpServers: createDefaultMcpServers(),
     allowedTools: ALLOWED_TOOLS,
     timeoutMs: config3.QA_EXPLORE_TIMEOUT_SECONDS === void 0 ? void 0 : config3.QA_EXPLORE_TIMEOUT_SECONDS * MS_PER_SECOND3,
-    userPrompt,
+    appContext,
+    initialState: resolvedStartingState,
     buildEnv: config3.QA_BUILD_ENV
   };
 }
@@ -60970,7 +61180,7 @@ function buildPipelineConfig({
   const base = {
     outputDir: import_node_path10.default.join(xqaDirectory, "output"),
     runId: config3.QA_RUN_ID,
-    onEvent: createConsoleObserver(input.verbose ? { verbose: true } : void 0),
+    onEvent: createConsoleObserver(input.verbose ? { verbose: input.verbose } : void 0),
     signal: input.signal,
     inspector: { designsDirectory: import_node_path10.default.join(xqaDirectory, "designs") },
     explorer
@@ -61008,69 +61218,114 @@ ${cause}
     }
   };
 }
+function handleContextError(error48) {
+  const cause = error48.cause instanceof Error ? error48.cause.message : JSON.stringify(error48.cause);
+  process.stderr.write(`Failed to read context: ${error48.type}
+${cause}
+`);
+  process.exit(1);
+}
 function runExploreCommand(input, options) {
   const { config: config3, xqaDirectory } = options;
   const { onSuccess, onError } = handlePipelineResult(input, xqaDirectory);
-  void readInstructions(xqaDirectory).match(
-    (instructions) => {
-      const explorerConfig = buildExplorerConfig2({ input, config: config3, instructions });
-      void runPipeline2(
-        buildPipelineConfig({ input, config: config3, xqaDirectory, explorer: explorerConfig })
-      ).match(onSuccess, onError);
-    },
-    (error48) => {
-      const cause = error48.cause instanceof Error ? error48.cause.message : JSON.stringify(error48.cause);
-      process.stderr.write(`Failed to read instructions: ${error48.type}
-${cause}
-`);
-      process.exit(1);
-    }
-  );
+  void readAppContext(xqaDirectory).andThen(
+    (appContext) => readExploreContext(xqaDirectory).map((exploreContext) => ({ appContext, exploreContext }))
+  ).match(({ appContext, exploreContext }) => {
+    const explorerConfig = buildExplorerConfig2({
+      input,
+      config: config3,
+      appContext,
+      initialState: exploreContext
+    });
+    void runPipeline2(
+      buildPipelineConfig({ input, config: config3, xqaDirectory, explorer: explorerConfig })
+    ).match(onSuccess, onError);
+  }, handleContextError);
 }
 
 // src/commands/init-command.ts
+var import_node_child_process5 = require("node:child_process");
 var import_node_fs5 = require("node:fs");
 var import_node_path11 = __toESM(require("node:path"), 1);
+var import_node_url = require("node:url");
 var GITIGNORE_CONTENT = `/output
 /last-findings-path
 `;
-var INSTRUCTIONS_TEMPLATE = `<!-- App Overview
-Describe what your app does and its main purpose.
-Example: This is a crypto wallet app that lets users send, receive, and swap tokens.
+var APP_TEMPLATE = `<!-- Overview
+What this app does in 1-2 sentences. Focus on domain, not tech stack.
+Example: Crypto wallet for sending, receiving, and swapping tokens across multiple blockchains.
 -->
 
-<!-- Navigation
-Describe the main navigation structure and how to move between screens.
-Example: The main screen is the asset list. Swipe down to open Profile. Dismiss modals by swiping down.
+<!-- Screens
+List the main screens and how to reach them. Use > for navigation paths.
+Include any non-obvious names the accessibility tree uses for screen titles.
+Example:
+- Portfolio: default home screen, shows asset list
+- Asset Detail: tap any asset in Portfolio
+- Settings: tap the gear icon top-right on Portfolio
+- Send: Portfolio > tap asset > Send button
+If the accessibility tree uses a different name than what's visible, include both.
 -->
 
-<!-- Startup
-Describe the initial state of the app when the agent starts.
-Example: The app starts on the home screen with a wallet already loaded.
-If this file contains a mnemonic phrase, add .xqa/instructions.md to your .gitignore.
+<!-- Gestures
+Optional. List navigation gestures that have no visible button. The agent cannot discover these from the UI tree.
+Skip this section if your app does not use gesture-based navigation.
+Example:
+- Swipe down on Portfolio \u2192 opens Profile
+- Swipe down on any modal \u2192 dismisses it
+- Swipe left on Asset Detail \u2192 goes back (no back button visible)
 -->
 `;
+var EXPLORE_TEMPLATE = `<!-- Starting State
+Describe the exact screen and state the app is in when the agent connects.
+Include credentials or wallet state if relevant. Add explore.md to .gitignore if it contains secrets.
+Example: App is on the Portfolio screen with a funded wallet loaded. No modals are open.
+Example with credentials: App is on the Login screen. Use PIN 123456 to unlock.
+Example with mid-flow state: App is on the Send flow, amount entry modal is open. Dismiss before exploring.
+-->
+
+<!-- Scope
+Optional. Tell the agent where to focus or what to skip.
+Without this, the agent explores everything reachable from the starting screen.
+Example: Focus on the Settings section only. Skip the Send and Receive flows.
+Example: Explore everything except the Swap screen \u2014 it requires live network.
+Scope applies from the starting screen. If the focus area requires navigation, describe that in Starting State instead.
+-->
+`;
+function resolveSkillPath(skillName) {
+  const packageDistributionDirectory = import_node_path11.default.dirname((0, import_node_url.fileURLToPath)(__importMetaUrl));
+  return import_node_path11.default.join(packageDistributionDirectory, "skills", skillName);
+}
 function runInitCommand() {
   const xqaDirectory = import_node_path11.default.join(process.cwd(), ".xqa");
+  (0, import_node_child_process5.spawnSync)("npx", ["skills", "add", resolveSkillPath("xqa-spec")], {
+    stdio: "inherit"
+  });
   if ((0, import_node_fs5.existsSync)(xqaDirectory)) {
-    process.stderr.write(`xqa already initialized: ${xqaDirectory}
+    process.stdout.write(`Skills updated. .xqa already exists, skipping project init.
 `);
-    process.exit(1);
     return;
   }
   (0, import_node_fs5.mkdirSync)(xqaDirectory);
   (0, import_node_fs5.writeFileSync)(import_node_path11.default.join(xqaDirectory, ".gitignore"), GITIGNORE_CONTENT);
-  (0, import_node_fs5.writeFileSync)(import_node_path11.default.join(xqaDirectory, "instructions.md"), INSTRUCTIONS_TEMPLATE);
+  (0, import_node_fs5.writeFileSync)(import_node_path11.default.join(xqaDirectory, "app.md"), APP_TEMPLATE);
+  (0, import_node_fs5.writeFileSync)(import_node_path11.default.join(xqaDirectory, "explore.md"), EXPLORE_TEMPLATE);
+  for (const subdir of ["designs", "specs", "suites"]) {
+    (0, import_node_fs5.mkdirSync)(import_node_path11.default.join(xqaDirectory, subdir));
+    (0, import_node_fs5.writeFileSync)(import_node_path11.default.join(xqaDirectory, subdir, ".gitkeep"), "");
+  }
   process.stdout.write(`Initialized xqa project: ${xqaDirectory}
 `);
-  process.stdout.write(`Edit .xqa/instructions.md to describe your app.
-`);
+  process.stdout.write(
+    `Edit .xqa/app.md to describe your app and .xqa/explore.md to configure exploration.
+`
+  );
 }
 
 // src/commands/review-command.ts
 var import_node_fs6 = require("node:fs");
 var import_node_path13 = __toESM(require("node:path"), 1);
-var import_neverthrow37 = __toESM(require_index_cjs(), 1);
+var import_neverthrow38 = __toESM(require_index_cjs(), 1);
 
 // ../../node_modules/.pnpm/@inquirer+core@10.3.2_@types+node@22.19.15/node_modules/@inquirer/core/dist/esm/lib/key.js
 var isUpKey = (key, keybindings = []) => (
@@ -63475,7 +63730,7 @@ var esm_default11 = createPrompt((config3, done) => {
 });
 
 // src/review-session.ts
-var import_neverthrow36 = __toESM(require_index_cjs(), 1);
+var import_neverthrow37 = __toESM(require_index_cjs(), 1);
 var CONFIDENCE_PERCENT = 100;
 var FLOW_COL_WIDTH = 35;
 var TRIGGER_COL_WIDTH = 16;
@@ -63628,15 +63883,15 @@ async function runInteractiveLoop(findings, existing) {
   }
   return { staged: state.staged, undoneKeys: state.undoneKeys };
 }
-var safeRunInteractiveLoop = (0, import_neverthrow36.fromAsyncThrowable)(
+var safeRunInteractiveLoop = (0, import_neverthrow37.fromAsyncThrowable)(
   runInteractiveLoop,
   (error48) => error48 instanceof Error && error48.name === "ExitPromptError" ? "exit-prompt" : "unexpected"
 );
 
 // src/commands/review-command.ts
-var safeReadFile3 = (0, import_neverthrow37.fromThrowable)((filePath) => (0, import_node_fs6.readFileSync)(filePath, "utf8"));
-var safeParseJson2 = (0, import_neverthrow37.fromThrowable)(JSON.parse);
-var safeWrite = (0, import_neverthrow37.fromThrowable)((filePath, content) => {
+var safeReadFile3 = (0, import_neverthrow38.fromThrowable)((filePath) => (0, import_node_fs6.readFileSync)(filePath, "utf8"));
+var safeParseJson2 = (0, import_neverthrow38.fromThrowable)(JSON.parse);
+var safeWrite = (0, import_neverthrow38.fromThrowable)((filePath, content) => {
   (0, import_node_fs6.writeFileSync)(filePath, content);
 });
 function readLastPath(xqaDirectory) {
@@ -63653,13 +63908,13 @@ function isPipelineOutput(data) {
 function readFindings(filePath) {
   const readResult = safeReadFile3(filePath);
   if (readResult.isErr()) {
-    return (0, import_neverthrow37.err)("not-found");
+    return (0, import_neverthrow38.err)("not-found");
   }
   return safeParseJson2(readResult.value).mapErr(() => "invalid").andThen((data) => {
     if (!isPipelineOutput(data)) {
-      return (0, import_neverthrow37.err)("invalid");
+      return (0, import_neverthrow38.err)("invalid");
     }
-    return (0, import_neverthrow37.ok)(data);
+    return (0, import_neverthrow38.ok)(data);
   });
 }
 function loadExistingDismissals(filePath) {
@@ -63732,7 +63987,7 @@ function resolveAndReadFindings(findingsPath, xqaDirectory) {
       "No findings path provided and no last path found. Run: xqa review <findings-path>\n"
     );
     process.exit(1);
-    return (0, import_neverthrow37.err)();
+    return (0, import_neverthrow38.err)();
   }
   const resolvedPath = resolvedPathResult.value;
   const findingsResult = readFindings(resolvedPath);
@@ -63745,9 +64000,9 @@ function resolveAndReadFindings(findingsPath, xqaDirectory) {
 `);
     }
     process.exit(1);
-    return (0, import_neverthrow37.err)();
+    return (0, import_neverthrow38.err)();
   }
-  return (0, import_neverthrow37.ok)({ resolvedPath, output: findingsResult.value });
+  return (0, import_neverthrow38.ok)({ resolvedPath, output: findingsResult.value });
 }
 async function runReviewLoop({
   findings,
@@ -63800,46 +64055,43 @@ async function runReviewCommand(findingsPath, xqaDirectory) {
 // src/commands/spec-command.ts
 var import_node_fs7 = require("node:fs");
 var import_node_path15 = __toESM(require("node:path"), 1);
-var import_neverthrow39 = __toESM(require_index_cjs(), 1);
+var import_neverthrow40 = __toESM(require_index_cjs(), 1);
 
 // src/spec-frontmatter.ts
-var import_neverthrow38 = __toESM(require_index_cjs(), 1);
+var import_neverthrow39 = __toESM(require_index_cjs(), 1);
 var FRONTMATTER_OPEN_LEN = 4;
 var FRONTMATTER_MARKER_LEN = 3;
 function extractFrontmatterBlock(content) {
   const normalized = content.replaceAll("\r\n", "\n");
   if (!normalized.startsWith("---")) {
-    return (0, import_neverthrow38.err)({ type: "MISSING_FRONTMATTER" });
+    return (0, import_neverthrow39.err)({ type: "MISSING_FRONTMATTER" });
   }
   const end = normalized.indexOf("\n---", FRONTMATTER_MARKER_LEN);
   if (end === -1) {
-    return (0, import_neverthrow38.err)({ type: "MISSING_FRONTMATTER" });
+    return (0, import_neverthrow39.err)({ type: "MISSING_FRONTMATTER" });
   }
-  return (0, import_neverthrow38.ok)(normalized.slice(FRONTMATTER_OPEN_LEN, end));
+  return (0, import_neverthrow39.ok)(normalized.slice(FRONTMATTER_OPEN_LEN, end));
 }
-function parseMaxSteps(fields) {
-  const maxStepsRaw = fields.get("max_steps");
-  if (maxStepsRaw === void 0) {
-    return (0, import_neverthrow38.ok)(maxStepsRaw);
+function parseTimeout(fields) {
+  const raw = fields.get("timeout");
+  if (raw === void 0) {
+    return (0, import_neverthrow39.ok)(raw);
   }
-  const parsed = Number(maxStepsRaw);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    return (0, import_neverthrow38.err)({ type: "PARSE_ERROR", cause: `invalid max_steps: ${maxStepsRaw}` });
+  const parsed = Number(raw);
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    return (0, import_neverthrow39.err)({ type: "PARSE_ERROR", cause: `invalid timeout: ${raw}` });
   }
-  return (0, import_neverthrow38.ok)(parsed);
+  return (0, import_neverthrow39.ok)(parsed);
 }
 function parseSpecFrontmatter(content) {
   return extractFrontmatterBlock(content).andThen((block) => {
     const fields = parseYamlFields(block);
     const feature = fields.get("feature");
     if (feature === void 0) {
-      return (0, import_neverthrow38.err)({ type: "MISSING_FIELD", field: "feature" });
+      return (0, import_neverthrow39.err)({ type: "MISSING_FIELD", field: "feature" });
     }
     const entry = fields.get("entry");
-    if (entry === void 0) {
-      return (0, import_neverthrow38.err)({ type: "MISSING_FIELD", field: "entry" });
-    }
-    return parseMaxSteps(fields).map((maxSteps) => ({ feature, entry, maxSteps }));
+    return parseTimeout(fields).map((timeout) => ({ feature, entry, timeout }));
   });
 }
 function parseYamlFields(block) {
@@ -63877,14 +64129,24 @@ function stripExtensions(filename) {
 }
 
 // src/commands/spec-command.ts
-var safeReadFile4 = (0, import_neverthrow39.fromThrowable)((filePath) => (0, import_node_fs7.readFileSync)(filePath, "utf8"));
+var safeReadFile4 = (0, import_neverthrow40.fromThrowable)((filePath) => (0, import_node_fs7.readFileSync)(filePath, "utf8"));
+var safeReaddir = (0, import_neverthrow40.fromThrowable)(
+  (directory) => (0, import_node_fs7.readdirSync)(directory, { recursive: true, encoding: "utf8" })
+);
+var CANCEL = "xqa:cancel";
+var safeSelect = import_neverthrow40.ResultAsync.fromThrowable(
+  esm_default11,
+  (error48) => error48 instanceof Error && error48.name === "ExitPromptError" ? "cancelled" : "failed"
+);
 function buildSpecExplorer(input, context) {
   return {
     mode: "spec",
     specFiles: [context.absolutePath],
     mcpServers: createDefaultMcpServers(),
     allowedTools: ALLOWED_TOOLS,
-    userPrompt: `Navigate to \`${context.entry}\` before beginning spec verification.`,
+    timeoutMs: context.timeout === void 0 ? void 0 : context.timeout * MS_PER_SECOND3,
+    appContext: context.appContext,
+    initialState: context.entry ? `Navigate to \`${context.entry}\` before beginning spec verification.` : void 0,
     buildEnv: context.config.QA_BUILD_ENV
   };
 }
@@ -63892,7 +64154,7 @@ function buildPipelineConfig2(input, context) {
   return {
     outputDir: import_node_path15.default.join(context.xqaDirectory, "output", context.slug),
     signal: input.signal,
-    onEvent: createConsoleObserver(input.verbose ? { verbose: true } : void 0),
+    onEvent: createConsoleObserver(input.verbose ? { verbose: input.verbose } : void 0),
     inspector: { designsDirectory: import_node_path15.default.join(context.xqaDirectory, "designs") },
     explorer: buildSpecExplorer(input, context)
   };
@@ -63937,33 +64199,95 @@ ${cause}
 `);
   process.exit(1);
 }
+function findSpecFiles(xqaDirectory) {
+  const specsDirectory = import_node_path15.default.join(xqaDirectory, "specs");
+  return safeReaddir(specsDirectory).unwrapOr([]).filter((file2) => file2.endsWith(".test.md")).map((file2) => import_node_path15.default.join(specsDirectory, file2));
+}
+async function promptForSpec(specFiles, xqaDirectory) {
+  const result = await safeSelect({
+    message: "Select a spec",
+    choices: [
+      ...specFiles.map((specFile) => ({
+        name: import_node_path15.default.relative(xqaDirectory, specFile),
+        value: specFile
+      })),
+      new Separator(),
+      { name: "Cancel", value: CANCEL }
+    ]
+  });
+  if (result.isErr() || result.value === CANCEL) {
+    process.exit(0);
+    return void 0;
+  }
+  return result.value;
+}
+async function resolveSpecFile(specFile, xqaDirectory) {
+  if (specFile !== void 0) {
+    return specFile;
+  }
+  const specFiles = findSpecFiles(xqaDirectory);
+  if (specFiles.length === 0) {
+    process.stderr.write("No spec files found in .xqa/specs/. Create one with /xqa-spec.\n");
+    process.exit(1);
+    return void 0;
+  }
+  return promptForSpec(specFiles, xqaDirectory);
+}
+async function executeSpec(input, context) {
+  const result = await runPipeline2(buildPipelineConfig2(input, context));
+  result.match((output) => {
+    handleSpecSuccess(context.xqaDirectory, output);
+  }, handleSpecError);
+}
+function handleAppContextError(error48) {
+  const cause = error48.cause instanceof Error ? error48.cause.message : JSON.stringify(error48.cause);
+  process.stderr.write(`Failed to read app context: ${error48.type}
+${cause}
+`);
+  process.exit(1);
+}
+async function buildContext(options, specData) {
+  const appContextResult = await readAppContext(options.xqaDirectory);
+  if (appContextResult.isErr()) {
+    handleAppContextError(appContextResult.error);
+    return void 0;
+  }
+  return {
+    config: options.config,
+    xqaDirectory: options.xqaDirectory,
+    absolutePath: specData.absolutePath,
+    entry: specData.entry,
+    timeout: specData.timeout,
+    slug: deriveSpecSlug(specData.absolutePath),
+    appContext: appContextResult.value
+  };
+}
 async function runSpecCommand(input, options) {
-  const { config: config3, xqaDirectory } = options;
-  const absolutePath = import_node_path15.default.resolve(input.specFile);
+  const resolvedSpecFile = await resolveSpecFile(input.specFile, options.xqaDirectory);
+  if (resolvedSpecFile === void 0) {
+    return;
+  }
+  const absolutePath = import_node_path15.default.resolve(resolvedSpecFile);
   const frontmatter = readAndParseSpec(absolutePath);
   if (frontmatter === void 0) {
     return;
   }
-  const slug = deriveSpecSlug(absolutePath);
-  const result = await runPipeline2(
-    buildPipelineConfig2(input, {
-      config: config3,
-      xqaDirectory,
-      absolutePath,
-      entry: frontmatter.entry,
-      slug
-    })
-  );
-  result.match((output) => {
-    handleSpecSuccess(xqaDirectory, output);
-  }, handleSpecError);
+  const context = await buildContext(options, {
+    absolutePath,
+    entry: frontmatter.entry,
+    timeout: frontmatter.timeout
+  });
+  if (context === void 0) {
+    return;
+  }
+  await executeSpec(input, context);
 }
 
 // src/config.ts
 var import_node_path16 = __toESM(require("node:path"), 1);
-var import_node_url = require("node:url");
+var import_node_url2 = require("node:url");
 var import_dotenv = __toESM(require_main(), 1);
-var import_neverthrow40 = __toESM(require_index_cjs(), 1);
+var import_neverthrow41 = __toESM(require_index_cjs(), 1);
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var external_exports2 = {};
@@ -68016,7 +68340,7 @@ var configSchema = external_exports2.object({
 });
 
 // src/config.ts
-var packageDirectory = import_node_path16.default.dirname((0, import_node_url.fileURLToPath)(__importMetaUrl));
+var packageDirectory = import_node_path16.default.dirname((0, import_node_url2.fileURLToPath)(__importMetaUrl));
 function loadConfig() {
   (0, import_dotenv.config)({ path: import_node_path16.default.resolve(packageDirectory, "..", ".env.local") });
   const result = configSchema.safeParse(process.env);
@@ -68024,15 +68348,34 @@ function loadConfig() {
     const messages = result.error.issues.map(
       (issue2) => `  - ${issue2.path.join(".")}: ${issue2.message}`
     );
-    return (0, import_neverthrow40.err)({ type: "INVALID_CONFIG", message: `Configuration error:
+    return (0, import_neverthrow41.err)({ type: "INVALID_CONFIG", message: `Configuration error:
 ${messages.join("\n")}` });
   }
-  return (0, import_neverthrow40.ok)(result.data);
+  return (0, import_neverthrow41.ok)(result.data);
+}
+
+// src/core/parse-verbose.ts
+function parseVerboseOption(value) {
+  if (value === void 0 || value === "all") {
+    return new Set(ALL_VERBOSE_CATEGORIES);
+  }
+  if (value === "") {
+    throw new InvalidArgumentError("--verbose requires categories or no value for all");
+  }
+  const requested = value.split(",").map((category) => category.trim().toLowerCase());
+  const invalid = requested.filter((category) => !ALL_VERBOSE_CATEGORIES.has(category));
+  const validList = [...ALL_VERBOSE_CATEGORIES].join(", ");
+  if (invalid.length > 0) {
+    const names = invalid.map((name) => `"${name}"`).join(", ");
+    const label = invalid.length === 1 ? "category" : "categories";
+    throw new InvalidArgumentError(`Unknown verbose ${label}: ${names}. Valid: ${validList}`);
+  }
+  return new Set(requested);
 }
 
 // src/pid-lock.ts
 var import_node_fs8 = require("node:fs");
-var import_neverthrow41 = __toESM(require_index_cjs(), 1);
+var import_neverthrow42 = __toESM(require_index_cjs(), 1);
 var PID_FILE = "/tmp/xqa.pid";
 var SIGINT_EXIT_CODE = 130;
 var SIGTERM_EXIT_CODE = 143;
@@ -68041,7 +68384,7 @@ var HARD_TIMEOUT_MS = 1e4;
 var cleanup = () => {
   (0, import_node_fs8.rmSync)(PID_FILE, { force: true });
 };
-var checkProcessRunning = (0, import_neverthrow41.fromThrowable)(
+var checkProcessRunning = (0, import_neverthrow42.fromThrowable)(
   (pid) => {
     process.kill(pid, 0);
     return true;
@@ -68107,17 +68450,17 @@ function acquireLock() {
 // src/shell/xqa-directory.ts
 var import_node_fs9 = require("node:fs");
 var import_node_path17 = __toESM(require("node:path"), 1);
-var import_neverthrow42 = __toESM(require_index_cjs(), 1);
+var import_neverthrow43 = __toESM(require_index_cjs(), 1);
 function findXqaDirectory(startDirectory) {
   let current = startDirectory;
   for (; ; ) {
     const candidate = import_node_path17.default.join(current, ".xqa");
     if ((0, import_node_fs9.existsSync)(candidate)) {
-      return (0, import_neverthrow42.ok)(candidate);
+      return (0, import_neverthrow43.ok)(candidate);
     }
     const parent = import_node_path17.default.dirname(current);
     if (parent === current) {
-      return (0, import_neverthrow42.err)({ type: "XQA_NOT_INITIALIZED" });
+      return (0, import_neverthrow43.err)({ type: "XQA_NOT_INITIALIZED" });
     }
     current = parent;
   }
@@ -68145,7 +68488,11 @@ program2.name("xqa").description("AI-powered QA agent CLI");
 program2.command("init").description("Initialize a new xqa project in the current directory").action(() => {
   runInitCommand();
 });
-program2.command("explore").description("Run the explorer agent; omit prompt for a full breadth-first sweep").argument("[prompt]", "Optional focus hint for the explorer; omit for a full breadth-first sweep").option("--verbose", "Log tool call results").action((prompt, options) => {
+program2.command("explore").description("Run the explorer agent; omit prompt for a full breadth-first sweep").argument("[prompt]", "Optional focus hint for the explorer; omit for a full breadth-first sweep").option(
+  "-v, --verbose [categories]",
+  "Verbose output [prompt,tools,screen,memory] (default: all)",
+  parseVerboseOption
+).action((prompt, options) => {
   const xqaDirectory = resolveXqaDirectory();
   runExploreCommand(
     { prompt, verbose: options.verbose, signal: controller.signal },
@@ -68162,10 +68509,14 @@ program2.command("review").description("Review findings and mark false positives
   const xqaDirectory = resolveXqaDirectory();
   void runReviewCommand(findingsPath, xqaDirectory);
 });
-program2.command("spec").description("Run the explorer agent against a spec file").argument("<spec-file>", "Path to the spec markdown file").option("--verbose", "Log tool call results").action((specFile, options) => {
+program2.command("spec").description("Run the explorer agent against a spec file").argument("[spec-file]", "Path to the spec markdown file; omit to pick interactively").option(
+  "-v, --verbose [categories]",
+  "Verbose output [prompt,tools,screen,memory] (default: all)",
+  parseVerboseOption
+).action((specFile, options) => {
   const xqaDirectory = resolveXqaDirectory();
   void runSpecCommand(
-    { specFile, verbose: options.verbose ?? false, signal: controller.signal },
+    { specFile, verbose: options.verbose, signal: controller.signal },
     { config: config2, xqaDirectory }
   );
 });