@exodus/xqa 1.3.0 → 1.4.0

package/README.md

@@ -1,166 +1,220 @@
 # @exodus/xqa
 
-CLI for running AI-powered QA agents against Exodus mobile apps on iOS.
+AI-powered QA agent CLI for Exodus applications.
 
-## Prerequisites
+## Overview
 
-- Node >= 22
-- pnpm
-- An Anthropic API key
+`xqa` automates mobile app QA by connecting to physical devices or emulators and running intelligent exploration and spec-based testing. The CLI orchestrates the pipeline that spawns agents to interact with your app, capture screenshots, and generate findings based on user-defined specs or breadth-first exploration.
 
-## Installation
+The tool manages configuration, project initialization, session state tracking, and interactive review workflows for triaging findings.
 
-From the monorepo root:
+## Commands
 
-```bash
-pnpm install
-```
+### init
 
-Then build and link the CLI globally:
+Initialize a new xqa project in the current directory.
+
+Creates a `.xqa/` directory with templates and subdirectories for specs, designs, and suites. Installs the `xqa-spec` skill for creating test specs.
 
 ```bash
-pnpm build:link   # build + link `xqa` into PATH
+xqa init
 ```
 
-For active development:
+### explore [prompt]
+
+Run the explorer agent; omit prompt for a full breadth-first sweep.
+
+Optional focus hint for the explorer agent. Omit to explore the entire app from the starting state. Generates a findings JSON file in `.xqa/output/` and prints the path upon completion.
 
 ```bash
-pnpm dev:link     # build, link, and watch for changes
+xqa explore                          # breadth-first exploration
+xqa explore "test the login flow"    # focused exploration
+xqa explore -v prompt,screen         # verbose output for categories
+xqa explore -v                       # verbose output for all categories
 ```
 
-## Setup
+Flag: `-v, --verbose [categories]` — Log categories (prompt, tools, screen, memory). Default: all if flag is present without value.
 
-Copy the example env file and fill in your values:
+### spec [spec-file]
+
+Run the explorer agent against a spec file.
+
+Loads a spec markdown file from `.xqa/specs/` (or an absolute path) and executes the agent against it. Spec files define entry points, steps, and optional timeouts. Omit the argument to pick from available specs interactively.
 
 ```bash
-cp .env.example .env.local
+xqa spec                                      # interactive spec picker
+xqa spec .xqa/specs/authentication.test.md   # explicit spec file
+xqa spec -v tools,memory                      # verbose output
 ```
 
-`.env.local` is loaded automatically at startup.
+Flag: `-v, --verbose [categories]` — Same as explore.
 
-## Environment Variables
+Spec file format (YAML frontmatter + markdown):
 
-| Variable                       | Required | Default          | Description                                                                                 |
-| ------------------------------ | -------- | ---------------- | ------------------------------------------------------------------------------------------- |
-| `ANTHROPIC_API_KEY`            | Yes      | —                | Anthropic API key                                                                           |
-| `GOOGLE_GENERATIVE_AI_API_KEY` | No       | —                | Gemini key — enables video analysis; required for `xqa analyse`                             |
-| `QA_RUN_ID`                    | No       | auto-generated   | Fixed run ID; auto-incremented when omitted                                                 |
-| `QA_EXPLORE_TIMEOUT_SECONDS`   | No       | —                | Max wall-clock time for an explore or spec run                                              |
-| `QA_WALLET_MNEMONIC`           | No       | —                | Wallet mnemonic; agent restores wallet before exploring when set                            |
-| `QA_BUILD_ENV`                 | No       | `prod`           | `dev` or `prod`; `dev` mode ignores debug overlays                                          |
-| `QA_STARTUP_STATE`             | No       | —                | `portfolio`, `new-wallet`, or `restore-wallet`; unset means app starts in its current state |
-| `QA_DESIGNS_DIR`               | No       | `./.xqa/designs` | Design artboards directory; enables visual regression checks when set                       |
+```markdown
+---
+feature: 'Feature Name'
+entry: 'Screen name or navigation path'
+timeout: 300
+---
 
-## Commands
+# Spec content
+```
+
+### review [findings-path]
 
-### `xqa explore [prompt]`
+Review findings and mark false positives.
 
-Runs the explorer agent against the live simulator. Without a prompt the agent sweeps the entire app. With a prompt it focuses on the described flow.
+Interactive session for triaging findings generated by explore or spec runs. Displays findings with confidence scores, steps, and screenshots. Mark findings as false positives (with optional reason) or undo previous dismissals. Saves dismissals to `.xqa/dismissals.json`. Defaults to the last findings path if omitted.
 
 ```bash
-xqa explore
-xqa explore "Try to send Bitcoin to an external address"
-xqa explore --verbose
+xqa review                                      # use last findings file
+xqa review .xqa/output/findings-abc123.json    # explicit path
 ```
 
-Startup state (`QA_STARTUP_STATE`) controls what the agent sees on launch:
+### analyse [video-path]
+
+Analyse a session recording with Gemini.
 
-- `portfolio` — main assets screen (default)
-- `new-wallet` — onboarding screen; agent taps through setup
-- `restore-wallet` — onboarding screen; agent restores wallet using `QA_WALLET_MNEMONIC`
+Requires `GOOGLE_GENERATIVE_AI_API_KEY` in environment. Analyzes a video file recorded during exploration and outputs findings as JSON.
+
+```bash
+xqa analyse /path/to/video.mp4
+```
 
-When `GOOGLE_GENERATIVE_AI_API_KEY` is set, a Gemini video analyser runs automatically after the explorer finishes.
+### completion <shell>
 
-### `xqa spec <spec-file>`
+Output shell completion script.
 
-Runs the explorer against a markdown spec file. The agent navigates to the entry point defined in the frontmatter and verifies each described step.
+Generate completion script for bash or zsh. Pipe output to shell config file to enable tab completion.
 
 ```bash
-xqa spec path/to/send-flow.md
-xqa spec path/to/send-flow.md --verbose
+xqa completion bash  # generate bash completions
+xqa completion zsh   # generate zsh completions
 ```
 
-Spec file format:
+## Configuration
 
-```markdown
----
-feature: Send Flow
-entry: Assets list
-max_steps: 40
----
+Configuration is loaded from environment variables and `.env.local`:
 
-Steps describing the flow to verify...
-```
+- `ANTHROPIC_API_KEY` (required) — Anthropic Claude API key for agent reasoning
+- `GOOGLE_GENERATIVE_AI_API_KEY` (optional) — Google Generative AI key for video analysis
+- `QA_RUN_ID` (optional) — Custom run identifier; defaults to auto-generated
+- `QA_EXPLORE_TIMEOUT_SECONDS` (optional) — Exploration timeout in seconds
+- `QA_BUILD_ENV` (optional) — Build environment: `dev` or `prod` (default: prod)
+
+## Architecture
 
-| Field       | Required | Description                                        |
-| ----------- | -------- | -------------------------------------------------- |
-| `feature`   | Yes      | Human-readable feature name                        |
-| `entry`     | Yes      | Screen name the agent navigates to before starting |
-| `max_steps` | No       | Maximum number of agent steps                      |
+Key files and directories:
 
-### `xqa analyse <video-path>`
+- `src/index.ts` — CLI entry point; wires commander commands and manages graceful shutdown via process locks
+- `src/commands/` — Command implementations (init, explore, spec, review, analyse, completion)
+- `src/core/` — Pure functions: spec parsing, completion generation, verbose option parsing, last-path tracking
+- `src/shell/` — I/O wrappers: file reading, device discovery, app context loading
+- `src/config.ts`, `src/config-schema.ts` — Configuration loading and validation with Zod
+- `src/review-session.ts` — Interactive finding review loop with dismissal tracking
+- `src/spec-frontmatter.ts` — Spec markdown frontmatter parsing (YAML)
+- `src/spec-slug.ts` — Spec filename to slug derivation for output organization
+- `src/pid-lock.ts` — Process-level mutual exclusion to prevent concurrent runs
 
-Analyses a session recording with Gemini. Requires `GOOGLE_GENERATIVE_AI_API_KEY`. Prints findings as JSON to stdout.
+## Error Types
+
+Core error discriminated unions:
+
+- `ConfigError` — Configuration validation failed (INVALID_CONFIG)
+- `AppContextError` — Failed to read app.md or explore.md (READ_FAILED)
+- `XqaDirectoryError` — No .xqa directory found (XQA_NOT_INITIALIZED)
+- `SpecFrontmatterError` — Malformed spec markdown (MISSING_FRONTMATTER, MISSING_FIELD, PARSE_ERROR)
+- `LastPathError` — No findings path provided and no prior session (NO_ARG_AND_NO_STATE)
+
+## Development
+
+Install dependencies:
 
 ```bash
-xqa analyse .xqa/output/2026-04-10/0001/recording.mp4
+pnpm install
 ```
 
-### `xqa review [findings-path]`
+Build the CLI:
 
-Interactive terminal session for reviewing findings and marking false positives. Requires a TTY. Dismissals are persisted to a dismissals store and excluded from future runs.
+```bash
+pnpm run build
+```
+
+Run tests:
 
 ```bash
-xqa review .xqa/output/2026-04-10/0001/findings.json
+pnpm run test
+```
+
+Type check:
 
-# re-open the last reviewed findings file
-xqa review
+```bash
+pnpm run typecheck
 ```
 
-### `xqa completion <shell>`
+Lint and format:
 
-Outputs a shell completion script.
+```bash
+pnpm run lint
+pnpm run lint:fix
+```
+
+Full quality check (lint, typecheck, test):
 
 ```bash
-xqa completion zsh >> ~/.zshrc
-xqa completion bash >> ~/.bashrc
+pnpm run check
+pnpm run check:fix
 ```
 
-## Process Behaviour
+Watch mode (build + re-run on file changes):
 
-Only one `xqa` instance runs at a time (PID lock). A second invocation while a run is active will exit immediately with an error.
+```bash
+pnpm run dev
+```
 
-- `Ctrl+C` once: graceful shutdown — the current agent step completes, findings are written, then the process exits
-- `Ctrl+C` twice: force exit
+Link binary globally (symlinks dist/xqa.cjs to ~/.local/bin/xqa):
 
-## Development
+```bash
+pnpm run build:link
+```
+
+Unlink binary:
 
 ```bash
-pnpm dev          # watch build
-pnpm build        # production build
-pnpm build:link   # build + link `xqa` globally
-pnpm dev:link     # watch build + link
-pnpm test         # run Vitest test suite
-pnpm typecheck    # TypeScript type check
-pnpm lint         # ESLint + Prettier check
-pnpm lint:fix     # ESLint + Prettier auto-fix
-pnpm check        # lint + typecheck + test (affected only)
-pnpm check:fix    # lint:fix + typecheck + test (affected only)
+pnpm run build:unlink
 ```
 
-## Architecture
+## Project Structure
 
 ```
 src/
-  index.ts                # CLI entry — registers all commands
-  config-schema.ts        # Zod schema for all environment variables
+  index.ts                    # CLI entry point
+  config.ts                   # Config loading and types
+  config-schema.ts            # Zod schema for env vars
+  constants.ts                # Tool lists and timeouts
+  pid-lock.ts                 # Process exclusion lock
+  spec-slug.ts                # Spec file to slug conversion
+  spec-frontmatter.ts         # Spec YAML parsing
+  review-session.ts           # Interactive finding review loop
+
   commands/
-    explore-command.ts    # xqa explore
-    spec-command.ts       # xqa spec
-    analyse-command.ts    # xqa analyse
-    review-command.ts     # xqa review
-    completion-command.ts # xqa completion
-  prompt-builder.ts       # builds the explorer system prompt from config
+    init-command.ts           # Project initialization
+    explore-command.ts        # Breadth-first exploration
+    spec-command.ts           # Spec-based exploration
+    review-command.ts         # Finding triage workflow
+    analyse-command.ts        # Video analysis
+    completion-command.ts     # Shell completion generation
+
+  core/
+    parse-verbose.ts          # Verbose flag parsing
+    completion-generator.ts   # Bash/zsh completion script generation
+    last-path.ts              # Last findings path tracking
+
+  shell/
+    app-context.ts            # Read app.md and explore.md
+    xqa-directory.ts          # Locate .xqa directory
+
+  __tests__/
+    *.test.ts                 # Test files co-located with src/
 ```
-
-The CLI is a thin shell over `@qa-agents/pipeline`. It parses env vars, builds a `PipelineConfig`, and calls `runPipeline()`.

package/dist/skills/xqa-spec/AGENTS.md

@@ -23,7 +23,7 @@ Silently scan `.xqa/specs/*.test.md`. Learn:
 - Tag vocabulary
 - Level of detail and step granularity
 
-Also read `.xqa/instructions.md` if it exists for app context.
+Also read `.xqa/app.md` if it exists for app context.
 
 ### 2. Detect mode
 
@@ -40,17 +40,20 @@ Ask one question at a time. Wait for the answer before asking the next. Prefer m
 
 **Question sequence:**
 
-1. **What flow?** — Confirm what's being tested if not already clear. Suggest a filename.
-2. **Starting state** — "Where does the app start for this test? What's already set up?" → becomes `## Setup`
-3. **Steps** — "Walk me through the steps, one at a time. I'll ask for the next when you're done." → collect each step, then ask "What should happen?" for the assertion (optional)
-4. **Global assertions** — "Anything non-obvious that should hold at the end?" → becomes `## Assertions`; skip if none. Never suggest trivial examples (no errors shown, page loaded) — only capture meaningful, app-specific checks.
-5. **Metadata** — "Any tags or a custom timeout?" (offer to skip)
+1. **What flow?** — Confirm what's being tested if not already clear. Suggest a filename and `feature` name.
+2. **Entry point** — "What's the navigation path to reach this flow?" (e.g., `App launch`, `Home > Wallet`) → becomes `entry:` frontmatter
+3. **Starting state** — "What's already set up? What state is the device/app in?" → becomes `## Setup`
+4. **Steps** — "Walk me through the steps, one at a time. I'll ask for the next when you're done." → collect each step, then ask "What should happen?" for the assertion (optional)
+5. **Global assertions** — "Any overall things that should be true at the end of the flow?" → becomes `## Assertions` (skip if none)
+6. **Timeout** — "Set a timeout in seconds? (optional, for long-running specs)" → becomes `timeout:` frontmatter (offer to skip)
 
 IMPORTANT: Ask each question in its own message. Never batch questions.
 
 ### 4. Draft
 
-Assemble the spec from interview answers — don't invent steps or assertions the user didn't describe. Present the full draft for review.
+Assemble using ONLY these frontmatter fields: `feature`, `entry`, `timeout`. Do not add any other frontmatter field. `feature` MUST be present. `timeout` MUST be a positive number (seconds) if included.
+
+Steps and assertions come from the user — never invent them. Present the full draft for review.
 
 ### 5. Review
 
@@ -66,28 +69,30 @@ Save to `.xqa/specs/<name>.test.md` only after explicit approval.
 
 ```md
 ---
-description: optional one-liner
-tags: [optional, tags]
-timeout: 120
+feature: <string>
+entry: <string>
+timeout: <seconds>
 ---
 
 ## Setup
 
-Starting screen and preconditions. Required.
+<preconditions and starting state>
 
 ## Steps
 
-1. Action → expected outcome (optional inline assertion)
-2. Next action
+1. <action> → <expected outcome>
+2. <action>
 
 ## Assertions
 
-- Global flow-level check (optional section)
+- <global flow-level check>
 ```
 
+Omit `entry` and `timeout` lines if not provided. Omit `## Assertions` section if none.
+
 ## Rules
 
-- `## Setup` and `## Steps` are required; frontmatter and `## Assertions` are optional
+- `## Setup` and `## Steps` are required; `## Assertions` is optional
 - Inline assertion syntax: `action → outcome` using the → character
 - Steps come from the user — never invent them
 - Write file only after explicit approval

package/dist/skills/xqa-spec/SKILL.md

@@ -29,7 +29,7 @@ Silently scan `.xqa/specs/*.test.md`. Learn:
 - Tag vocabulary
 - Level of detail and step granularity
 
-Also read `.xqa/instructions.md` if it exists for app context.
+Also read `.xqa/app.md` if it exists for app context.
 
 ### 2. Detect mode
 
@@ -46,17 +46,20 @@ Ask one question at a time. Wait for the answer before asking the next. Prefer m
 
 **Question sequence:**
 
-1. **What flow?** — Confirm what's being tested if not already clear. Suggest a filename.
-2. **Starting state** — "Where does the app start for this test? What's already set up?" → becomes `## Setup`
-3. **Steps** — "Walk me through the steps, one at a time. I'll ask for the next when you're done." → collect each step, then ask "What should happen?" for the assertion (optional)
-4. **Global assertions** — "Anything non-obvious that should hold at the end?" → becomes `## Assertions`; skip if none. Never suggest trivial examples (no errors shown, page loaded) — only capture meaningful, app-specific checks.
-5. **Metadata** — "Any tags or a custom timeout?" (offer to skip)
+1. **What flow?** — Confirm what's being tested if not already clear. Suggest a filename and `feature` name.
+2. **Entry point** — "What's the navigation path to reach this flow?" (e.g., `App launch`, `Home > Wallet`) → becomes `entry:` frontmatter
+3. **Starting state** — "What's already set up? What state is the device/app in?" → becomes `## Setup`
+4. **Steps** — "Walk me through the steps, one at a time. I'll ask for the next when you're done." → collect each step, then ask "What should happen?" for the assertion (optional)
+5. **Global assertions** — "Any overall things that should be true at the end of the flow?" → becomes `## Assertions` (skip if none)
+6. **Max steps** — "Set a timeout in seconds? (optional, for long-running specs)" → becomes `timeout:` frontmatter (offer to skip)
 
 IMPORTANT: Ask each question in its own message. Never batch questions.
 
 ### 4. Draft
 
-Assemble the spec from interview answers — don't invent steps or assertions the user didn't describe. Present the full draft for review.
+Assemble using ONLY these frontmatter fields: `feature`, `entry`, `timeout`. Do not add any other frontmatter field. `feature` MUST be present. `timeout` MUST be a positive number (seconds) if included.
+
+Steps and assertions come from the user — never invent them. Present the full draft for review.
 
 ### 5. Review
 
@@ -66,34 +69,56 @@ Iterate until approved. One round of changes per message.
 
 ### 6. Write
 
-Save to `.xqa/specs/<name>.test.md` only after explicit approval.
+Before writing, verify the draft passes all checks:
+
+- [ ] `feature` is present and non-empty
+- [ ] frontmatter contains only permitted fields: `feature`, `entry`, `timeout`
+- [ ] `timeout` if present is a positive number in seconds (not a string, not zero)
+- [ ] `## Setup` section is present
+- [ ] `## Steps` section is present
+- [ ] No forbidden fields: `tags`, `max_steps`, `priority`, `type`, `description`, `id`, `author`
+
+Fix any failure before writing. Save to `.xqa/specs/<name>.test.md` only after explicit approval.
 
 ## File format
 
+FRONTMATTER SCHEMA — exact fields, exact types, no others:
+
+```
+feature    string           REQUIRED
+entry      string           OPTIONAL — omit if not provided
+timeout  positive number (seconds) OPTIONAL — omit if not provided
+```
+
+FORBIDDEN frontmatter fields — never generate these: `tags`, `max_steps`, `priority`, `type`, `description`, `id`, `author`, `version`
+
+CANONICAL OUTPUT FORMAT:
+
 ```md
 ---
-description: optional one-liner
-tags: [optional, tags]
-timeout: 120
+feature: <string>
+entry: <string>
+timeout: <seconds>
 ---
 
 ## Setup
 
-Starting screen and preconditions. Required.
+<preconditions and starting state>
 
 ## Steps
 
-1. Action → expected outcome (optional inline assertion)
-2. Next action
+1. <action> → <expected outcome>
+2. <action>
 
 ## Assertions
 
-- Global flow-level check (optional section)
+- <global flow-level check>
 ```
 
+Omit `entry` and `timeout` lines if not provided. Omit `## Assertions` section if none.
+
 ## Rules
 
-- `## Setup` and `## Steps` are required; frontmatter and `## Assertions` are optional
 - Inline assertion syntax: `action → outcome` using the → character
 - Steps come from the user — never invent them
 - Write file only after explicit approval

package/dist/xqa.cjs

@@ -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 });
   }
@@ -55891,13 +55909,13 @@ 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
+- 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 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.
@@ -55919,41 +55937,59 @@ Test navigation elements first, interactions second.
 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.
+**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_MODE_TEMPLATE = (specContent, options) => {
-  const appSection = options.userPrompt ? `## Application
+var SPEC_WHAT_TO_TEST_SECTION = `## What to Test
 
-${options.userPrompt}
+Test only the elements and interactions described in the spec. Do not interact with elements outside the spec path.
 
-` : "";
-  const environmentSection = options.buildEnv === "dev" ? `
+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
 
-${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.
+**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.
 
-Verify app against specs below.
+**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
 
-${appSection}${WORKING_STATE_SECTION}
+${appContext}` : void 0,
+    initialState ? `## Initial State
 
-## Rules
+${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.slice(2)}
+- ${BACK_NAV_RULE}
 - 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)}
+- ${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 unexpected navigation failures, broken interactions, or crash dialogs encountered during step execution, even if not listed as assertions
+- 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.
 
-## Exploration Strategy
+Verify app against specs below.
 
-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.
+${contextBlock}
 
-${WHAT_TO_TEST_SECTION}
+${SPEC_RULES_SECTION}
 
-${DEAD_END_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
 
@@ -55962,28 +55998,31 @@ ${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 { userPrompt, buildEnv } = options ?? {};
-  const appSection = userPrompt ? `## Application
-
-${userPrompt}
-
-` : "";
+  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.
 
-${appSection}${WORKING_STATE_SECTION}
+${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.slice(2)}
+- ${BACK_NAV_RULE}
 - 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)}
+- ${STUCK_LOOP_RULE}
+- ${CLIPPED_ELEMENT_RULE}
 
 ## Exploration Strategy
 
@@ -56000,10 +56039,11 @@ CRITICAL: Call \`set_output\` each time your findings change \u2014 when you dis
 function generateExplorerPrompt({
   mode,
   specs,
-  userPrompt,
+  appContext,
+  initialState,
   buildEnv
 }) {
-  return mode === "spec" ? buildSpecModePrompt(specs, { userPrompt, buildEnv }) : FREESTYLE_TEMPLATE({ userPrompt, buildEnv });
+  return mode === "spec" ? buildSpecModePrompt(specs, { appContext, initialState, buildEnv }) : FREESTYLE_TEMPLATE({ appContext, initialState, buildEnv });
 }
 function renderStep(step, index) {
   const stepNumber = String(index + 1);
@@ -56862,7 +56902,8 @@ function buildPrompt(safeConfig, specs) {
   return generateExplorerPrompt({
     mode: safeConfig.mode,
     specs,
-    userPrompt: safeConfig.userPrompt,
+    appContext: safeConfig.appContext,
+    initialState: safeConfig.initialState,
     buildEnv: safeConfig.buildEnv
   });
 }
@@ -56907,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 })).andThen((specs) => parseSpecs(specs)).map((parsedSpecs) => buildPrompt(safeConfig, parsedSpecs)).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 }));
@@ -61066,7 +61113,7 @@ 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_neverthrow36 = __toESM(require_index_cjs(), 1);
@@ -61074,45 +61121,53 @@ 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_neverthrow36.ok)(absent);
 }
 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_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
   };
 }
@@ -61125,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
@@ -61163,24 +61218,29 @@ ${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
@@ -61191,20 +61251,45 @@ 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) {
@@ -61213,7 +61298,7 @@ function resolveSkillPath(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"], {
+  (0, import_node_child_process5.spawnSync)("npx", ["skills", "add", resolveSkillPath("xqa-spec")], {
     stdio: "inherit"
   });
   if ((0, import_node_fs5.existsSync)(xqaDirectory)) {
@@ -61223,15 +61308,18 @@ function runInitCommand() {
   }
   (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
@@ -63984,14 +64072,14 @@ function extractFrontmatterBlock(content) {
   }
   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_neverthrow39.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_neverthrow39.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_neverthrow39.ok)(parsed);
 }
@@ -64003,7 +64091,7 @@ function parseSpecFrontmatter(content) {
       return (0, import_neverthrow39.err)({ type: "MISSING_FIELD", field: "feature" });
     }
     const entry = fields.get("entry");
-    return parseMaxSteps(fields).map((maxSteps) => ({ feature, entry, maxSteps }));
+    return parseTimeout(fields).map((timeout) => ({ feature, entry, timeout }));
   });
 }
 function parseYamlFields(block) {
@@ -64056,7 +64144,9 @@ function buildSpecExplorer(input, context) {
     specFiles: [context.absolutePath],
     mcpServers: createDefaultMcpServers(),
     allowedTools: ALLOWED_TOOLS,
-    userPrompt: context.entry ? `Navigate to \`${context.entry}\` before beginning spec verification.` : void 0,
+    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
   };
 }
@@ -64064,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)
   };
@@ -64149,9 +64239,31 @@ async function executeSpec(input, context) {
     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 resolvedSpecFile = await resolveSpecFile(input.specFile, xqaDirectory);
+  const resolvedSpecFile = await resolveSpecFile(input.specFile, options.xqaDirectory);
   if (resolvedSpecFile === void 0) {
     return;
   }
@@ -64160,8 +64272,15 @@ async function runSpecCommand(input, options) {
   if (frontmatter === void 0) {
     return;
   }
-  const slug = deriveSpecSlug(absolutePath);
-  await executeSpec(input, { config: config3, xqaDirectory, absolutePath, entry: frontmatter.entry, slug });
+  const context = await buildContext(options, {
+    absolutePath,
+    entry: frontmatter.entry,
+    timeout: frontmatter.timeout
+  });
+  if (context === void 0) {
+    return;
+  }
+  await executeSpec(input, context);
 }
 
 // src/config.ts
@@ -68235,6 +68354,25 @@ ${messages.join("\n")}` });
   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_neverthrow42 = __toESM(require_index_cjs(), 1);
@@ -68350,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 },
@@ -68367,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; omit to pick interactively").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 }
   );
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/xqa",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -26,12 +26,12 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.1",
     "zod": "^3.0.0",
-    "@qa-agents/explorer": "0.0.0",
     "@qa-agents/eslint-config": "0.0.0",
-    "@qa-agents/shared": "0.0.0",
-    "@qa-agents/typescript-config": "0.0.0",
+    "@qa-agents/explorer": "0.0.0",
     "@qa-agents/observer": "0.0.0",
-    "@qa-agents/pipeline": "0.0.0"
+    "@qa-agents/pipeline": "0.0.0",
+    "@qa-agents/typescript-config": "0.0.0",
+    "@qa-agents/shared": "0.0.0"
   },
   "dependencies": {
     "@mobilenext/mobile-mcp": "^0.0.50",
@@ -46,8 +46,8 @@
   },
   "scripts": {
     "dev": "node scripts/build.mjs --watch",
-    "build:link": "pnpm link --global",
-    "build:unlink": "pnpm remove -g @exodus/xqa",
+    "build:link": "ln -sf \"$(pwd)/dist/xqa.cjs\" ~/.local/bin/xqa",
+    "build:unlink": "rm -f ~/.local/bin/xqa",
     "dev:link": "pnpm link --global && pnpm run dev",
     "build": "node scripts/build.mjs",
     "typecheck": "tsc --noEmit",