@exodus/xqa 1.2.3 → 1.3.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;
@@ -48106,7 +48106,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 +55763,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 +55776,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 +55884,277 @@ 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
+- 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\`; if the accessibility tree cannot confirm, emit a \`spec-deviation\` finding based on what is observable
+- Flag unexpected navigation failures, broken interactions, or crash dialogs encountered during step execution, even if not listed as assertions
+
+## 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 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 +56170,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 +56235,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 +56405,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 +56681,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 +56732,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 +56757,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 +56774,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 +56821,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 +56855,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;
@@ -56720,6 +56866,15 @@ function buildPrompt(safeConfig, specs) {
     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,
@@ -56757,7 +56912,7 @@ function runPipeline({
   runPaths,
   start
 }) {
-  return resolveSpecs(safeConfig).mapErr((cause) => ({ type: "SPEC_RESOLVE_FAILED", cause })).map((specs) => buildPrompt(safeConfig, specs)).map((prompt) => {
+  return resolveSpecs(safeConfig).mapErr((cause) => ({ type: "SPEC_RESOLVE_FAILED", cause })).andThen((specs) => parseSpecs(specs)).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 +56996,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 +59635,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 +59712,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 +59739,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 +59812,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 +59824,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 +59863,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 +59931,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 +59978,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 +60061,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 +60078,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 +60311,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 +60386,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 +60410,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 +60422,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 +60436,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 +60451,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 +60478,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 +60501,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 +60531,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 +60541,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 +60568,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 +60581,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 +60594,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 +60676,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 +60702,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 +60725,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 +60737,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 +60750,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 +60793,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 +60841,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 +60897,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 +60987,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 +61048,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");
@@ -60914,7 +61069,7 @@ function writeLastPath(xqaDirectory, findingsPath) {
 // src/shell/instructions.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";
@@ -60924,9 +61079,9 @@ function toInstructionsError(cause) {
 }
 function absentInstructions() {
   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
 );
@@ -60940,7 +61095,7 @@ function readInstructions(xqaDirectory) {
     if (isEnoentError(error48.cause)) {
       return absentInstructions();
     }
-    return (0, import_neverthrow35.err)(error48);
+    return (0, import_neverthrow36.err)(error48);
   });
 }
 
@@ -61029,8 +61184,10 @@ ${cause}
 }
 
 // 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
 `;
@@ -61050,17 +61207,27 @@ 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.
 -->
 `;
+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"), "--all", "-y"], {
+    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);
+  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.
@@ -61070,7 +61237,7 @@ function runInitCommand() {
 // 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 +63642,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 +63795,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 +63820,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 +63899,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 +63912,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,45 +63967,42 @@ 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);
+    return (0, import_neverthrow39.ok)(maxStepsRaw);
   }
   const parsed = Number(maxStepsRaw);
   if (!Number.isInteger(parsed) || parsed <= 0) {
-    return (0, import_neverthrow38.err)({ type: "PARSE_ERROR", cause: `invalid max_steps: ${maxStepsRaw}` });
+    return (0, import_neverthrow39.err)({ type: "PARSE_ERROR", cause: `invalid max_steps: ${maxStepsRaw}` });
   }
-  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 }));
   });
 }
@@ -63877,14 +64041,22 @@ 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.`,
+    userPrompt: context.entry ? `Navigate to \`${context.entry}\` before beginning spec verification.` : void 0,
     buildEnv: context.config.QA_BUILD_ENV
   };
 }
@@ -63937,33 +64109,66 @@ ${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);
+}
 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, 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);
+  await executeSpec(input, { config: config3, xqaDirectory, absolutePath, entry: frontmatter.entry, slug });
 }
 
 // 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 +68221,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 +68229,15 @@ 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/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 +68246,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 +68312,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;
   }
@@ -68162,7 +68367,7 @@ 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("--verbose", "Log tool call results").action((specFile, options) => {
   const xqaDirectory = resolveXqaDirectory();
   void runSpecCommand(
     { specFile, verbose: options.verbose ?? false, signal: controller.signal },