levante 0.3.5 → 0.3.7

package/README.md

@@ -1,11 +1,13 @@
 # Levante
 
-AI-powered end-to-end test pipeline for Playwright. Record, transcribe, generate, refine, heal, and document your tests — all driven by LLM agents.
+AI-powered end-to-end test pipeline for Playwright. Record interactions, transcribe narration, generate Playwright tests, self-heal failures, and produce QA documentation — all driven by LLM agents.
 
 ## Installation
 
 ```bash
 npm install -g levante
+# or
+bun add -g levante
 ```
 
 Levante requires Playwright as a peer dependency:
@@ -14,82 +16,109 @@ Levante requires Playwright as a peer dependency:
 npm install -D @playwright/test
 ```
 
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `OPENAI_API_KEY` | Yes (if using OpenAI) | OpenAI API key |
-| `ANTHROPIC_API_KEY` | Yes (if using Anthropic) | Anthropic API key |
-| `E2E_AI_API_URL` | No | Remote API URL for QA map push |
-| `E2E_AI_API_KEY` | No | API key for push authentication |
-
 ## Quick Start
 
 ```bash
-# Initialize config and agents
+# 1. Initialize config and agents
 levante init
 
-# Run full pipeline for a test case
+# 2. Run full pipeline for a test case
 levante run --key PROJ-101
 
-# Or run individual steps
+# Or step by step
 levante record --key PROJ-101
 levante transcribe --key PROJ-101
 levante scenario --key PROJ-101
 levante generate --key PROJ-101
+levante refine --key PROJ-101
 levante test --key PROJ-101
+levante heal --key PROJ-101        # only if test fails
+levante qa --key PROJ-101
 ```
 
-## CLI Usage
+---
 
-### Global Options
+## Environment Variables
 
-```
--k, --key <KEY>          Issue key (e.g., PROJ-101)
---provider <provider>    LLM provider: openai | anthropic
---model <model>          LLM model override
--v, --verbose            Verbose output
---no-voice               Disable voice recording
---no-trace               Disable trace replay
-```
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY` | OpenAI API key |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `QAI_BASE_URL` | QA Intelligence API base URL |
+| `QAI_API_URL` | Full push endpoint (overrides base URL) |
+| `QAI_API_KEY` | API key for authenticated push |
 
-### Commands
+---
 
-#### `levante init`
+## Commands
 
-Initialize levante in your project. Creates `.qai/levante/` with config, agents, and workflow guide.
+### `levante init`
+
+Initialize levante in your project. Generates `.qai/levante/config.ts`, copies agent templates, and optionally connects to QA Intelligence.
 
 ```bash
 levante init
-levante init --non-interactive
+levante init --non-interactive   # skip prompts, use defaults
 ```
 
-#### `levante record [session]`
+On re-run, preserves your existing config and context, and only updates agents.
+
+**After init:**
+1. Generate `.qai/levante/context.md` using the `init-agent` prompt in your AI tool, or via MCP (`levante_scan_codebase`)
+2. Review the generated context
+3. Start recording: `levante record --key PROJ-101`
+
+---
 
-Launch Playwright codegen with optional audio narration capture.
+### `levante record [session]`
+
+Launch Playwright codegen with optional voice narration recording.
 
 ```bash
 levante record --key PROJ-101
-levante record --key PROJ-101 --no-voice
+levante record --key PROJ-101 --no-companion   # voice only, no companion UI
+levante record --key PROJ-101 --no-voice       # codegen only, no audio
 ```
 
-#### `levante transcribe [session]`
+| Option | Description |
+|--------|-------------|
+| `--no-companion` | Disable companion UI (voice recording only) |
+| `--no-voice` | Disable voice recording entirely |
 
-Transcribe `.wav` voice recording via OpenAI Whisper.
+**Output:** codegen TypeScript file + `.wav` audio (if voice enabled)
+
+---
+
+### `levante transcribe [session]`
+
+Transcribe the `.wav` voice recording via OpenAI Whisper. If a live transcript from the recording session exists, Whisper is skipped.
 
 ```bash
 levante transcribe --key PROJ-101
+levante transcribe --key PROJ-101 --force   # re-transcribe even if transcript exists
 ```
 
-#### `levante scenario [session]`
+Merges voice annotations (with timestamps) back into the codegen file as inline comments.
+
+**Output:** `*-transcript.json`, `*-transcript.md`, annotated codegen file
+
+---
+
+### `levante scenario [session]`
 
-Generate a structured YAML scenario from codegen output and transcript.
+Generate a structured YAML scenario from codegen output and voice transcript.
 
 ```bash
 levante scenario --key PROJ-101
 ```
 
-#### `levante generate [scenario]`
+Uses `transcript-agent` (if transcript available) to extract narrative and action intents, then `scenario-agent` to produce a YAML scenario with title, precondition, steps, and postcondition. Jira/Linear issue context is included automatically if `--key` is set.
+
+**Output:** `.yaml` scenario file in `e2e/tests/[key]/`
+
+---
+
+### `levante generate [scenario]`
 
 Generate a Playwright `.test.ts` file from a YAML scenario.
 
@@ -97,118 +126,238 @@ Generate a Playwright `.test.ts` file from a YAML scenario.
 levante generate --key PROJ-101
 ```
 
-#### `levante refine [test]`
+Uses `playwright-generator-agent` with scenario + project context. If Zephyr is configured, also generates a Zephyr test case export.
+
+**Output:** `[key].test.ts` in `e2e/tests/[key]/`
+
+---
 
-Refactor a generated test with AI — replaces raw selectors, adds best practices.
+### `levante refine [test]`
+
+Refactor a generated test with AI — replaces raw selectors, improves structure, applies project patterns.
 
 ```bash
 levante refine --key PROJ-101
 ```
 
-#### `levante test [test]`
+Uses `refactor-agent`. Rewrites the test file in-place.
+
+---
+
+### `levante test [test]`
 
-Run the Playwright test with trace/video/screenshot capture.
+Run the Playwright test with trace, video, and screenshot capture.
 
 ```bash
 levante test --key PROJ-101
+levante test --key PROJ-101 --no-trace
 ```
 
-#### `levante heal [test]`
+**Output:** Test execution logs, trace files in `e2e/traces/`
 
-Self-heal a failing test (up to 3 retries). Diagnoses failures and patches automatically.
+---
+
+### `levante heal [test]`
+
+Self-heal a failing test. Diagnoses the failure, patches the test, and re-runs — up to 3 retries.
 
 ```bash
 levante heal --key PROJ-101
 ```
 
-#### `levante qa [test]`
+Each attempt uses `self-healing-agent` with test content + error output + trace data to produce:
+- `diagnosis` (failure type, root cause, confidence)
+- `patchedTest` (updated test file)
+- `changes` (summary of what was fixed)
+
+Exits with error if all 3 attempts fail.
 
-Generate QA documentation (markdown and/or Zephyr XML).
+---
+
+### `levante qa [test]`
+
+Generate QA documentation from the test and scenario.
 
 ```bash
 levante qa --key PROJ-101
 ```
 
-#### `levante run [session]`
+Uses `qa-testcase-agent` with test + scenario + Jira context. Produces markdown and/or Zephyr export depending on `outputTarget`.
+
+**Output:** `qa/[testId].md` and/or Zephyr JSON
+
+---
+
+### `levante run [session]`
 
-Run the full pipeline: record → transcribe → scenario → generate → refine → test → heal → qa.
+Run the full pipeline: `record → transcribe → scenario → generate → refine → test → heal → qa`.
 
 ```bash
 levante run --key PROJ-101
-levante run --key PROJ-101 --from generate
+levante run --key PROJ-101 --from generate     # resume from a specific step
 levante run --key PROJ-101 --skip transcribe,heal
+levante run --key PROJ-101 --no-voice          # skip recording + transcription
 ```
 
 | Option | Description |
 |--------|-------------|
-| `--from <step>` | Start from a specific step |
-| `--skip <steps>` | Skip comma-separated steps |
+| `--from <step>` | Start from a specific step (skips earlier steps) |
+| `--skip <steps>` | Comma-separated step names to skip |
+| `--no-voice` | Disable voice recording (skips transcription too) |
+| `--no-trace` | Disable trace capture |
 
-## MCP Server
+**Steps (in order):** `record` → `transcribe` → `scenario` → `generate` → `refine` → `test` → `heal` → `qa`
 
-Levante includes an MCP server for use with AI coding assistants.
+---
 
-### Claude Code
+### `levante auth`
+
+Manage authentication with QA Intelligence.
 
 ```bash
-claude mcp add levante -- npx levante-mcp
+levante auth login    # open browser for OAuth sign-in
+levante auth logout   # revoke CLI token
+levante auth status   # show current auth status
+levante auth switch   # re-authenticate with a different org/project/app
 ```
 
-### Manual Configuration
+---
+
+### `levante jira`
+
+Interactive Jira integration for issue discovery and workflow launch.
 
-Add to your MCP client config (e.g., `claude_desktop_config.json`):
+#### `levante jira browse`
 
+Interactive browser — search, view, and select Jira issues to start a test workflow.
+
+```bash
+levante jira browse
+```
+
+Select an issue to:
+- **run** — save context and launch `levante run --key <KEY>`
+- **save** — save issue context without running
+- **view** — display full issue details
+
+#### `levante jira search <query>`
+
+Search Jira issues by text or raw JQL.
+
+```bash
+levante jira search "login flow"
+levante jira search --jql "project = QA AND status = 'In Progress'"
+levante jira search "dashboard" --max 10
+```
+
+| Option | Description |
+|--------|-------------|
+| `<query>` | Text search query |
+| `--jql <jql>` | Use raw JQL instead of text search |
+| `--max <n>` | Maximum results to return (default: 20) |
+
+#### `levante jira show <issueKey>`
+
+Display full details for a Jira issue.
+
+```bash
+levante jira show PROJ-101
+levante jira show PROJ-101 --save    # also save context for pipeline use
+```
+
+| Option | Description |
+|--------|-------------|
+| `--save` | Save issue context to `.qai/levante/issues/[KEY].json` |
+
+---
+
+### `levante mcp`
+
+Print MCP server setup instructions.
+
+```bash
+levante mcp
+```
+
+**Claude Code:**
+```bash
+claude mcp add levante -- levante-mcp              # project-scoped
+claude mcp add levante -s user -- levante-mcp      # global
+```
+
+**Claude Desktop / other clients:**
 ```json
 {
   "mcpServers": {
-    "levante": {
-      "command": "npx",
-      "args": ["levante-mcp"]
-    }
+    "levante": { "command": "levante-mcp" }
   }
 }
 ```
 
-### Available MCP Tools
+**Available MCP tools:**
 
 | Tool | Description |
 |------|-------------|
 | `levante_plan_workflow` | Get ordered step list with prerequisite checks |
 | `levante_execute_step` | Execute a single pipeline step |
-| `levante_get_workflow_guide` | Get the full workflow guide |
+| `levante_get_workflow_guide` | Read the full workflow guide |
 | `levante_scan_codebase` | Scan project for test infrastructure |
 | `levante_validate_context` | Validate context.md completeness |
 | `levante_read_agent` | Load an agent prompt by name |
-| `levante_get_example` | Get example context.md template |
+| `levante_get_example` | Get an example context.md template |
 | `levante_scan_ast` | Run AST scanner |
 | `levante_scan_ast_detail` | Drill into routes/components/hooks |
 | `levante_build_qa_map` | Build and validate QA map |
 | `levante_read_qa_map` | Load existing QA map |
 
+---
+
+## Global Options
+
+```
+-k, --key <KEY>        Issue key (e.g. PROJ-101, LIN-42)
+--provider <provider>  LLM provider: openai | anthropic
+--model <model>        LLM model override
+--verbose              Verbose output
+--no-voice             Disable voice recording
+--no-trace             Disable trace capture
+-v, --version          Show version
+-h, --help             Show help
+```
+
+---
+
 ## Configuration
 
-Configuration lives in `.qai/levante/config.ts`:
+Configuration lives in `.qai/levante/config.ts` (generated by `levante init`):
 
 ```typescript
-import { defineConfig } from 'levante/config';
+import { defineConfig } from 'levante';
 
 export default defineConfig({
-  inputSource: 'jira',           // 'none' | 'jira' | 'linear'
-  outputTarget: 'both',          // 'markdown' | 'zephyr' | 'both'
+  inputSource: 'jira',            // 'none' | 'jira' | 'linear'
+  outputTarget: 'both',           // 'markdown' | 'zephyr' | 'both'
   baseUrl: 'http://localhost:3000',
 
   llm: {
-    provider: 'openai',          // 'openai' | 'anthropic'
-    model: 'gpt-4o',             // Override default model
-    agentModels: {                // Per-agent overrides
+    provider: 'openai',           // 'openai' | 'anthropic'
+    model: 'gpt-4o',
+    agentModels: {                 // per-agent model overrides
       'scenario-agent': 'claude-sonnet-4-20250514',
     },
   },
 
   playwright: {
-    browser: 'chromium',
+    browser: 'chromium',          // 'chromium' | 'firefox' | 'webkit'
     timeout: 120_000,
-    traceMode: 'on',
+    retries: 0,
+    traceMode: 'on',              // 'on' | 'off' | 'retain-on-failure'
+  },
+
+  voice: {
+    enabled: true,
+    engine: 'webspeech',          // 'webspeech' | 'whisper'
+    language: 'en-US',
   },
 
   paths: {
@@ -221,36 +370,67 @@ export default defineConfig({
   },
 
   integrations: {
-    jira: { /* ... */ },
+    jira: { /* Jira config */ },
     zephyr: { titlePrefix: 'UI Automation' },
   },
 
   push: {
-    apiUrl: 'https://your-api.com/qa-map',
+    apiUrl: 'https://qaligent.space/api',
     apiKey: 'your-key',
   },
 });
 ```
 
-## Project Structure
+---
+
+## AI Agents
+
+Levante ships with agents copied to `.qai/levante/agents/` on `init`. Edit them to tune AI behavior for your project.
 
-After initialization, levante creates:
+| Agent | Purpose |
+|-------|---------|
+| `0.init-agent` | Generate project `context.md` |
+| `1_1.transcript-agent` | Analyze voice transcript + codegen into narrative |
+| `1_2.scenario-agent` | Generate YAML scenario from narrative and actions |
+| `2.playwright-generator-agent` | Generate Playwright test from YAML scenario |
+| `3.refactor-agent` | Refactor test code for quality and conventions |
+| `4.self-healing-agent` | Diagnose and patch failing tests |
+| `5.qa-testcase-agent` | Generate QA documentation and Zephyr export |
+
+Add `.qai/levante/context.md` to inject project-specific context into every agent call.
+
+---
+
+## Project Structure
 
 ```
 your-project/
   .qai/levante/
-    config.ts          # Configuration
-    context.md         # Project context for AI agents
-    agents/            # Agent prompts (customizable)
-    workflow.md        # Pipeline workflow guide
+    config.ts                  # Configuration
+    context.md                 # Project context for AI agents
+    agents/                    # Agent prompts (customizable)
+    workflow.md                # Pipeline workflow guide
+    issues/                    # Saved Jira issue contexts
   e2e/
-    tests/{key}/       # Generated test files
-    recordings/        # Codegen + voice recordings
-    transcripts/       # Transcription output
-    traces/            # Playwright traces
-  qa/                  # QA documentation output
+    tests/{key}/               # Generated test files + scenario YAML
+    recordings/                # Codegen + voice recordings
+    transcripts/               # Transcription output
+    traces/                    # Playwright traces
+  qa/                          # QA documentation output
 ```
 
+---
+
+## Interactive TUI
+
+Running `levante` with no arguments launches an interactive terminal UI (requires TTY, ≥ 60×20).
+
+```bash
+levante
+```
+
+---
+
 ## License
 
 MIT

package/dist/cli.js

@@ -57497,19 +57497,22 @@ async function launchTui(program2) {
       version: version2,
       onRunCommand: (argv) => {
         runningCommand = true;
-        instance.waitUntilExit().then(async () => {
-          process.stdin.resume();
-          process.stdout.write(`
+        instance.waitUntilExit().then(() => {
+          setTimeout(async () => {
+            process.stdin.resume();
+            process.stdin.ref();
+            process.stdout.write(`
 $ levante ${argv.join(" ")}
 
 `);
-          try {
-            await program2.parseAsync(argv, { from: "user" });
-          } catch (err) {
-            if (err?.name !== "ExitPromptError")
-              throw err;
-          }
-          done();
+            try {
+              await program2.parseAsync(argv, { from: "user" });
+            } catch (err) {
+              if (err?.name !== "ExitPromptError")
+                throw err;
+            }
+            done();
+          }, 50);
         });
       },
       onQuit: done
@@ -75507,54 +75510,61 @@ async function migrateFromLegacy(projectRoot, nonInteractive) {
 // src/commands/init.ts
 function registerInit(program2) {
   program2.command("init").description("Initialize levante configuration for your project").option("--non-interactive", "Skip interactive prompts, use defaults").action(async (cmdOpts) => {
-    const projectRoot = getProjectRoot();
-    const nonInteractive = !!cmdOpts?.nonInteractive;
-    header("levante init");
-    await migrateFromLegacy(projectRoot, nonInteractive);
-    const qaiDir = join17(projectRoot, CONFIG_DIR);
-    const configPath = join17(qaiDir, "config.ts");
-    const isReInit = fileExists(configPath);
-    if (isReInit) {
-      info(`Existing ${CONFIG_DIR}/ detected — preserving config and context.
+    try {
+      const projectRoot = getProjectRoot();
+      const nonInteractive = !!cmdOpts?.nonInteractive;
+      header("levante init");
+      await migrateFromLegacy(projectRoot, nonInteractive);
+      const qaiDir = join17(projectRoot, CONFIG_DIR);
+      const configPath = join17(qaiDir, "config.ts");
+      const isReInit = fileExists(configPath);
+      if (isReInit) {
+        info(`Existing ${CONFIG_DIR}/ detected — preserving config and context.
 `);
-      await copyAgentsToLocal(projectRoot, nonInteractive);
-      await copyWorkflowGuide(projectRoot, nonInteractive);
-    } else {
-      const answers = nonInteractive ? getDefaultAnswers() : await askConfigQuestions();
-      const config2 = buildConfigFromAnswers(answers);
-      writeFile(configPath, generateConfigFile(config2));
-      success2(`Config written: ${configPath}`);
-      await copyAgentsToLocal(projectRoot, nonInteractive);
-      await copyWorkflowGuide(projectRoot, nonInteractive);
-    }
-    if (!nonInteractive) {
-      const { confirm: confirmPrompt } = await Promise.resolve().then(() => (init_dist9(), exports_dist));
-      const connectAuth = await confirmPrompt({
-        message: "Connect to QA Intelligence?",
-        default: false
-      });
-      if (connectAuth) {
-        try {
-          const { login: login2 } = await Promise.resolve().then(() => (init_dist10(), exports_dist2));
-          const session = await login2({ webappUrl: "https://qaligent.space" });
-          success2(`Authenticated as ${session.user.email}`);
-          success2(`Linked to: ${session.scope.orgSlug} / ${session.scope.projectSlug} / ${session.scope.appSlug}`);
-        } catch (err) {
-          warn(`Authentication skipped: ${err instanceof Error ? err.message : "unknown error"}`);
+        await copyAgentsToLocal(projectRoot, nonInteractive);
+        await copyWorkflowGuide(projectRoot, nonInteractive);
+      } else {
+        const answers = nonInteractive ? getDefaultAnswers() : await askConfigQuestions();
+        const config2 = buildConfigFromAnswers(answers);
+        writeFile(configPath, generateConfigFile(config2));
+        success2(`Config written: ${configPath}`);
+        await copyAgentsToLocal(projectRoot, nonInteractive);
+        await copyWorkflowGuide(projectRoot, nonInteractive);
+      }
+      if (!nonInteractive) {
+        const { confirm: confirmPrompt } = await Promise.resolve().then(() => (init_dist9(), exports_dist));
+        const connectAuth = await confirmPrompt({
+          message: "Connect to QA Intelligence?",
+          default: false
+        });
+        if (connectAuth) {
+          try {
+            const { login: login2 } = await Promise.resolve().then(() => (init_dist10(), exports_dist2));
+            const session = await login2({ webappUrl: "https://qaligent.space" });
+            success2(`Authenticated as ${session.user.email}`);
+            success2(`Linked to: ${session.scope.orgSlug} / ${session.scope.projectSlug} / ${session.scope.appSlug}`);
+          } catch (err) {
+            warn(`Authentication skipped: ${err instanceof Error ? err.message : "unknown error"}`);
+          }
         }
       }
-    }
-    console.log("");
-    success2(`Initialization complete!
+      console.log("");
+      success2(`Initialization complete!
 `);
-    if (!isReInit) {
-      console.log(import_picocolors5.default.bold("Next steps:"));
-      console.log(`  1. Use the ${import_picocolors5.default.cyan("init-agent")} in your AI tool to generate ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
-      console.log(`     (or use the MCP server: ${import_picocolors5.default.cyan("levante_scan_codebase")} + ${import_picocolors5.default.cyan("levante_read_agent")})`);
-      console.log(`  2. Review the generated ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
-      console.log(`  3. Run: ${import_picocolors5.default.cyan("levante run --key PROJ-101")}`);
-    } else {
-      console.log(import_picocolors5.default.dim("Config and context.md were preserved. Only agents and workflow were checked."));
+      if (!isReInit) {
+        console.log(import_picocolors5.default.bold("Next steps:"));
+        console.log(`  1. Use the ${import_picocolors5.default.cyan("init-agent")} in your AI tool to generate ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
+        console.log(`     (or use the MCP server: ${import_picocolors5.default.cyan("levante_scan_codebase")} + ${import_picocolors5.default.cyan("levante_read_agent")})`);
+        console.log(`  2. Review the generated ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
+        console.log(`  3. Run: ${import_picocolors5.default.cyan("levante run --key PROJ-101")}`);
+      } else {
+        console.log(import_picocolors5.default.dim("Config and context.md were preserved. Only agents and workflow were checked."));
+      }
+    } catch (err) {
+      if (err?.name === "ExitPromptError") {
+        process.exit(0);
+      }
+      throw err;
     }
   });
 }

package/dist/mcp.js

@@ -28540,7 +28540,7 @@ class StdioServerTransport {
 // src/mcp.ts
 import { execSync } from "node:child_process";
 import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 
 // src/agents/loadAgent.ts
 import { readFileSync, existsSync as existsSync2, readdirSync } from "node:fs";
@@ -28726,6 +28726,44 @@ function parseSections(body) {
   return sections;
 }
 
+// src/config/paths.ts
+import { join as join3 } from "node:path";
+function resolvePaths(config2, key) {
+  const root = getProjectRoot();
+  const workingDir = join3(root, config2.paths.workingDir);
+  const testsDir = join3(root, config2.paths.tests);
+  const recordingsDir = join3(root, config2.paths.recordings);
+  const transcriptsDir = join3(root, config2.paths.transcripts);
+  const tracesDir = join3(root, config2.paths.traces);
+  const qaDir = join3(root, config2.paths.qaOutput);
+  const keyDir = key ? join3(workingDir, key) : null;
+  const testDir = key ? join3(testsDir, key) : null;
+  const testFile = key ? join3(testsDir, key, `${key}.test.ts`) : null;
+  const scenarioDir = key ? join3(testsDir, key) : null;
+  const scenarioFile = key ? join3(testsDir, key, `${key}.yaml`) : null;
+  const qaFile = key ? join3(qaDir, `${key}.md`) : null;
+  const needsZephyr = config2.outputTarget === "zephyr" || config2.outputTarget === "both";
+  const zephyrJsonFile = needsZephyr && key ? join3(workingDir, key, `${key}-zephyr-test-case.json`) : null;
+  const zephyrXmlFile = needsZephyr && key ? join3(testsDir, key, `${key}-zephyr-import.xml`) : null;
+  return {
+    projectRoot: root,
+    workingDir,
+    keyDir,
+    testsDir,
+    testDir,
+    testFile,
+    scenarioDir,
+    scenarioFile,
+    recordingsDir,
+    transcriptsDir,
+    tracesDir,
+    qaDir,
+    qaFile,
+    zephyrJsonFile,
+    zephyrXmlFile
+  };
+}
+
 // src/scanner/scanner.ts
 import { readFileSync as readFileSync3, existsSync as existsSync3, mkdirSync, writeFileSync } from "node:fs";
 import { resolve as resolve2, relative as relative2 } from "node:path";
@@ -32218,10 +32256,10 @@ class TypeScriptParser {
 
 // src/scanner/extractors/routes.ts
 import { readdirSync as readdirSync2, statSync, readFileSync as readFileSync2 } from "node:fs";
-import { join as join3, relative, basename, dirname as dirname2 } from "node:path";
+import { join as join4, relative, basename, dirname as dirname2 } from "node:path";
 function extractRoutes(scanDir) {
   const routes = [];
-  const appDirs = ["app", "src/app"].map((d) => join3(scanDir, d));
+  const appDirs = ["app", "src/app"].map((d) => join4(scanDir, d));
   for (const appDir of appDirs) {
     try {
       if (statSync(appDir).isDirectory()) {
@@ -32229,7 +32267,7 @@ function extractRoutes(scanDir) {
       }
     } catch {}
   }
-  const pagesDirs = ["pages", "src/pages"].map((d) => join3(scanDir, d));
+  const pagesDirs = ["pages", "src/pages"].map((d) => join4(scanDir, d));
   for (const pagesDir of pagesDirs) {
     try {
       if (statSync(pagesDir).isDirectory()) {
@@ -32242,7 +32280,7 @@ function extractRoutes(scanDir) {
 function extractAppRouterRoutes(dir, baseDir, routes) {
   const entries = readdirSync2(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join3(dir, entry.name);
+    const fullPath = join4(dir, entry.name);
     if (entry.isDirectory()) {
       extractAppRouterRoutes(fullPath, baseDir, routes);
       continue;
@@ -32278,7 +32316,7 @@ function extractAppRouterRoutes(dir, baseDir, routes) {
 function extractPagesRouterRoutes(dir, baseDir, routes) {
   const entries = readdirSync2(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join3(dir, entry.name);
+    const fullPath = join4(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "api") {
         extractPagesApiRoutes(fullPath, baseDir, routes);
@@ -32304,7 +32342,7 @@ function extractPagesRouterRoutes(dir, baseDir, routes) {
 function extractPagesApiRoutes(dir, baseDir, routes) {
   const entries = readdirSync2(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join3(dir, entry.name);
+    const fullPath = join4(dir, entry.name);
     if (entry.isDirectory()) {
       extractPagesApiRoutes(fullPath, baseDir, routes);
       continue;
@@ -32332,7 +32370,7 @@ function findLayoutFile(dir, baseDir) {
   let current = dir;
   while (current.startsWith(baseDir)) {
     for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
-      const layoutPath = join3(current, `layout${ext}`);
+      const layoutPath = join4(current, `layout${ext}`);
       try {
         statSync(layoutPath);
         return layoutPath;
@@ -32793,7 +32831,7 @@ function requireEnum(obj, field, allowed, context, errors3) {
 
 // src/utils/scan.ts
 import { readdirSync as readdirSync3, existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
-import { join as join4, relative as relative3 } from "node:path";
+import { join as join5, relative as relative3 } from "node:path";
 async function scanCodebase(root) {
   const scan = {
     testFiles: [],
@@ -32812,7 +32850,7 @@ async function scanCodebase(root) {
       for (const entry of readdirSync3(dir, { withFileTypes: true })) {
         if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist")
           continue;
-        const full = join4(dir, entry.name);
+        const full = join5(dir, entry.name);
         if (entry.isDirectory()) {
           files.push(...walk(full, depth + 1));
         } else {
@@ -32849,7 +32887,7 @@ async function scanCodebase(root) {
     }
   }
   for (const name of ["playwright.config.ts", "vitest.config.ts", "jest.config.ts", "tsconfig.json", "package.json"]) {
-    if (existsSync4(join4(root, name)))
+    if (existsSync4(join5(root, name)))
       scan.configFiles.push(name);
   }
   return scan;
@@ -32898,38 +32936,60 @@ You have access to Levante, an AI-powered E2E test automation tool. Follow this
 
 NEVER run multiple pipeline steps at once. Each step is a separate job with its own context.
 
+## Two Modes of Execution
+
+Steps fall into two categories:
+
+### 1. Tool Steps — use \`levante_execute_step\`
+These steps do NOT require an LLM. Run them via \`levante_execute_step\`:
+- \`record\` — opens Playwright browser codegen (interactive)
+- \`test\` — runs Playwright tests
+- \`push\` — pushes QA map to remote API
+- \`scan\` — runs the filesystem/AST scan
+
+### 2. Agent Steps — YOU are the AI, do these yourself
+These steps require LLM reasoning. Do NOT call \`levante_execute_step\` for them. Instead, load the agent prompt and act on it directly:
+
+| Step | Agent to load | Input to read | Output to write |
+|------|--------------|---------------|-----------------|
+| \`transcribe\` | \`transcript-agent\` | codegen file via \`levante_read_pipeline_file(key, "codegen")\` | transcript JSON via \`levante_write_pipeline_file\` |
+| \`scenario\` | \`scenario-agent\` | codegen + optional transcript | scenario YAML via \`levante_write_pipeline_file(key, "scenario", ...)\` |
+| \`generate\` | \`playwright-generator-agent\` | scenario YAML | test file via \`levante_write_pipeline_file(key, "test", ...)\` |
+| \`refine\` | \`refactor-agent\` | test file | updated test file (overwrite via \`levante_write_pipeline_file\`) |
+| \`heal\` | \`self-healing-agent\` | test file + error output | patched test file |
+| \`qa\` | \`qa-testcase-agent\` | test file + scenario | QA markdown via \`levante_write_pipeline_file(key, "qa", ...)\` |
+| \`analyze\` | \`feature-analyzer-agent\` | AST via \`levante_scan_ast_detail\` | QA map via \`levante_build_qa_map\` |
+
+**Workflow for each agent step:**
+1. Call \`levante_read_agent("<agent-name>")\` to load the system prompt and config.
+2. Call \`levante_read_pipeline_file(key, "<type>")\` to load the input artifact.
+3. Read \`.qai/levante/context.md\` if it exists — this is project context the agent needs.
+4. Apply the agent system prompt to your own reasoning and produce the output.
+5. Call \`levante_write_pipeline_file(key, "<type>", content)\` to save the output.
+
 ## Protocol
 
-1. **Plan first.** Call \`levante_plan_workflow\` with the user's goal. This returns a structured todo list of steps.
-2. **Check prerequisites.** The plan includes a \`ready\` boolean and \`missingPrerequisites\` array. If \`ready\` is false, show the user what's missing (API keys, config, etc.) and **wait for them to fix it** before proceeding. Do NOT attempt to execute any step while prerequisites are missing.
-3. **Present the plan.** Show the user the ordered step list with descriptions. Ask for confirmation or adjustments before proceeding.
-4. **Execute one step at a time.** For each step in the approved plan:
-   a. Tell the user which step you're about to run and why.
-   b. Call \`levante_execute_step\` with the step name and parameters.
-   c. Report the result to the user (success, key output, any warnings).
-   d. If the step fails, stop and discuss with the user before continuing.
-   e. Move to the next step only after the current one succeeds.
-5. **Use subagents when available.** If your AI platform supports subagents (e.g., Claude Code Agent tool), dispatch each step as a dedicated subagent to preserve context. Each subagent should:
-   - Receive only the context it needs (step name, key, relevant file paths)
-   - Call \`levante_execute_step\` to do its work
-   - Return the result to the orchestrator
+1. **Plan first.** Call \`levante_plan_workflow\` with the user's goal to get a structured step list.
+2. **Present the plan.** Show the user the ordered steps. Ask for confirmation before proceeding.
+3. **Execute one step at a time.** For each step:
+   a. Announce which step you're running and why.
+   b. Use **Tool Steps** via \`levante_execute_step\`, or handle **Agent Steps** yourself (see above).
+   c. Report the result. If a step fails, stop and discuss before continuing.
+4. **Use subagents when available.** If your AI platform supports subagents (Claude Code Agent tool), dispatch each step as a dedicated subagent. Each subagent should receive only the context it needs.
 
 ## Step Dependencies
 
-Steps produce artifacts that feed into later steps. The pipeline handles this automatically — each step picks up where the previous one left off. Do not skip steps unless the plan says a step can be skipped.
+Steps produce artifacts consumed by later steps. Do not skip steps unless the plan says a step can be skipped.
 
 ## Interactive Steps
 
-The \`record\` step opens a browser and requires user interaction. When the plan includes \`record\`:
-- Tell the user they need to interact with the browser window
-- The step will block until they close the codegen window
-- After recording completes, proceed with the next step
+The \`record\` step opens a browser. Tell the user to interact with it — the step blocks until they close the codegen window.
 
 ## When Things Fail
 
-- If \`test\` fails and \`heal\` is in the plan, that's expected — heal will attempt to fix it
-- If \`heal\` exhausts all retries, stop and show the user the last error output
-- For any other failure, stop and ask the user how to proceed
+- If \`test\` fails and \`heal\` is in the plan, that's expected — do the \`heal\` agent step yourself.
+- If healing fails after multiple attempts, stop and show the user the last error.
+- For any other failure, stop and ask the user how to proceed.
 
 ## Available Workflows
 
@@ -32945,7 +33005,7 @@ Always use \`levante_plan_workflow\` to determine the right steps — don't gues
 
 ## Scanner Analysis (Interactive QA Map)
 
-For deep codebase analysis and QA map generation, use the interactive scanner workflow instead of the CLI pipeline:
+For deep codebase analysis and QA map generation, use the interactive scanner workflow:
 
 1. **Load the protocol.** Call \`levante_read_agent("scanner-agent")\` — this returns the full interactive protocol.
 2. **Scan.** Call \`levante_scan_ast()\` to run the AST scanner and get a compact summary.
@@ -32954,8 +33014,6 @@ For deep codebase analysis and QA map generation, use the interactive scanner wo
 5. **Build.** Construct the QA map payload and validate with \`levante_build_qa_map({ dryRun: true })\`.
 6. **Write.** Once validated and approved, call \`levante_build_qa_map({ dryRun: false })\` to save.
 7. **Read existing.** Use \`levante_read_qa_map()\` to load a previously generated QA map for incremental updates.
-
-This approach is preferred over \`scan → analyze\` CLI steps because it allows interactive refinement with the user.
 `.trim();
 var TEST_PIPELINE_STEPS = [
   {
@@ -33043,41 +33101,20 @@ var SCANNER_PIPELINE_STEPS = [
 var ALL_STEPS = [...TEST_PIPELINE_STEPS, ...SCANNER_PIPELINE_STEPS];
 var STEP_REQUIREMENTS = {
   record: { envVars: [] },
-  transcribe: { envVars: [{ name: "OPENAI_API_KEY", reason: "Whisper transcription requires OpenAI API key" }] },
-  scenario: { envVars: [
-    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
-    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
-  ] },
-  generate: { envVars: [
-    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
-    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
-  ] },
-  refine: { envVars: [
-    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
-    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
-  ] },
+  transcribe: { envVars: [] },
+  scenario: { envVars: [] },
+  generate: { envVars: [] },
+  refine: { envVars: [] },
   test: { envVars: [] },
-  heal: { envVars: [
-    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
-    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
-  ] },
-  qa: { envVars: [
-    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
-    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
-  ] },
+  heal: { envVars: [] },
+  qa: { envVars: [] },
   scan: { envVars: [] },
-  analyze: { envVars: [
-    { name: "OPENAI_API_KEY", reason: "LLM calls require OpenAI API key", onlyIf: () => getProvider() === "openai" },
-    { name: "ANTHROPIC_API_KEY", reason: "LLM calls require Anthropic API key", onlyIf: () => getProvider() === "anthropic" }
-  ] },
+  analyze: { envVars: [] },
   push: { envVars: [
     { name: "E2E_AI_API_URL", reason: "Push requires API URL (set E2E_AI_API_URL or push.apiUrl in config)" },
     { name: "E2E_AI_API_KEY", reason: "Push requires API key (set E2E_AI_API_KEY or push.apiKey in config)" }
   ] }
 };
-function getProvider() {
-  return process.env.AI_PROVIDER ?? "openai";
-}
 function checkPrerequisites(stepNames) {
   const issueMap = new Map;
   for (const stepName of stepNames) {
@@ -33085,8 +33122,6 @@ function checkPrerequisites(stepNames) {
     if (!reqs)
       continue;
     for (const envReq of reqs.envVars) {
-      if (envReq.onlyIf && !envReq.onlyIf())
-        continue;
       if (!process.env[envReq.name]) {
         const key = `env:${envReq.name}`;
         if (issueMap.has(key)) {
@@ -33230,7 +33265,7 @@ function executeStep(stepName, options) {
     args.push(...options.extraArgs);
   }
   const pkgRoot = getPackageRoot();
-  const cliBin = join5(pkgRoot, "dist", "cli.js");
+  const cliBin = join6(pkgRoot, "dist", "cli.js");
   const command = `node ${cliBin} ${args.join(" ")}`;
   try {
     const stdout = execSync(command, {
@@ -33257,7 +33292,7 @@ ${stderr}`,
     };
   }
 }
-var server = new McpServer({ name: "levante", version: "1.5.1" }, { instructions: SERVER_INSTRUCTIONS });
+var server = new McpServer({ name: "levante", version: "1.6.0" }, { instructions: SERVER_INSTRUCTIONS });
 server.registerTool("levante_scan_codebase", {
   title: "Scan Codebase",
   description: "Scan a project directory for test files, configs, fixtures, path aliases, and sample test content. Use this during project setup or to understand test infrastructure.",
@@ -33309,13 +33344,108 @@ server.registerTool("levante_read_agent", {
     };
   }
 });
+server.registerTool("levante_read_pipeline_file", {
+  title: "Read Pipeline File",
+  description: "Read a pipeline artifact for a given issue key. Use this before an agent step to load the input. " + 'Types: "codegen" (raw Playwright codegen), "transcript" (voice transcript JSON), ' + '"scenario" (YAML test scenario), "test" (Playwright .test.ts), "qa" (QA markdown), "context" (project context.md).',
+  inputSchema: exports_external.object({
+    key: exports_external.string().optional().describe('Issue key (e.g. PROJ-101). Not required for "context" type.'),
+    type: exports_external.enum(["codegen", "transcript", "scenario", "test", "qa", "context"]).describe("Which artifact to read")
+  })
+}, async ({ key, type }) => {
+  try {
+    let filePath = null;
+    if (type === "context") {
+      filePath = join6(process.cwd(), CONFIG_DIR, "context.md");
+    } else {
+      if (!key) {
+        return {
+          content: [{ type: "text", text: "Error: key is required for this file type" }],
+          isError: true
+        };
+      }
+      const config2 = await loadConfig();
+      const paths = resolvePaths(config2, key);
+      if (type === "codegen") {
+        filePath = paths.keyDir ? join6(paths.keyDir, `${key}.codegen.ts`) : null;
+      } else if (type === "transcript") {
+        filePath = paths.keyDir ? join6(paths.keyDir, `${key}.transcript.json`) : null;
+      } else if (type === "scenario") {
+        filePath = paths.scenarioFile;
+      } else if (type === "test") {
+        filePath = paths.testFile;
+      } else if (type === "qa") {
+        filePath = paths.qaFile;
+      }
+    }
+    if (!filePath) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ found: false, path: null, reason: "Could not resolve path" }) }]
+      };
+    }
+    if (!existsSync5(filePath)) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ found: false, path: filePath }) }]
+      };
+    }
+    const fileContent = readFileSync5(filePath, "utf-8");
+    return {
+      content: [{ type: "text", text: JSON.stringify({ found: true, path: filePath, content: fileContent }) }]
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+});
+server.registerTool("levante_write_pipeline_file", {
+  title: "Write Pipeline File",
+  description: "Write a pipeline artifact after completing an agent step. " + 'Types: "transcript" (voice transcript JSON), "scenario" (YAML test scenario), ' + '"test" (Playwright .test.ts), "qa" (QA markdown).',
+  inputSchema: exports_external.object({
+    key: exports_external.string().describe("Issue key (e.g. PROJ-101)"),
+    type: exports_external.enum(["transcript", "scenario", "test", "qa"]).describe("Which artifact to write"),
+    content: exports_external.string().describe("The file content to write")
+  })
+}, async ({ key, type, content: fileContent }) => {
+  try {
+    const config2 = await loadConfig();
+    const paths = resolvePaths(config2, key);
+    const fileMap = {
+      transcript: paths.keyDir ? join6(paths.keyDir, `${key}.transcript.json`) : null,
+      scenario: paths.scenarioFile,
+      test: paths.testFile,
+      qa: paths.qaFile
+    };
+    const filePath = fileMap[type];
+    if (!filePath) {
+      return {
+        content: [{ type: "text", text: `Error: Could not resolve path for type "${type}" with key "${key}"` }],
+        isError: true
+      };
+    }
+    const { mkdirSync: mkdirSync2, writeFileSync: writeFileSync2 } = await import("node:fs");
+    const { dirname: dirname4 } = await import("node:path");
+    mkdirSync2(dirname4(filePath), { recursive: true });
+    writeFileSync2(filePath, fileContent, "utf-8");
+    return {
+      content: [{ type: "text", text: JSON.stringify({ written: true, path: filePath }) }]
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+});
 server.registerTool("levante_get_example", {
   title: "Get Example Context",
   description: `Returns the full example context markdown file that shows the expected format for ${CONFIG_DIR}/context.md.`,
   inputSchema: exports_external.object({})
 }, async () => {
   try {
-    const examplePath = join5(getPackageRoot(), "templates", "e2e-ai.context.example.md");
+    const examplePath = join6(getPackageRoot(), "templates", "e2e-ai.context.example.md");
     const content = readFileSync5(examplePath, "utf-8");
     return {
       content: [{ type: "text", text: content }]
@@ -33411,7 +33541,7 @@ server.registerTool("levante_get_workflow_guide", {
   inputSchema: exports_external.object({})
 }, async () => {
   try {
-    const guidePath = join5(getPackageRoot(), "templates", "workflow.md");
+    const guidePath = join6(getPackageRoot(), "templates", "workflow.md");
     if (!existsSync5(guidePath)) {
       return {
         content: [{ type: "text", text: "Error: workflow.md not found in templates" }],
@@ -33442,15 +33572,15 @@ server.registerTool("levante_scan_ast", {
     const cwd = process.cwd();
     const dir = scanDir ?? "src";
     const scanConfig = {
-      scanDir: join5(cwd, dir),
+      scanDir: join6(cwd, dir),
       include: include ?? ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
       exclude: exclude ?? ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.next/**", "**/*.test.*", "**/*.spec.*", "**/__tests__/**"],
-      cacheDir: join5(cwd, CONFIG_DIR, "cache")
+      cacheDir: join6(cwd, CONFIG_DIR, "cache")
     };
     const ast = await runStage1(scanConfig);
-    const astPath = join5(cwd, CONFIG_DIR, "ast-scan.json");
+    const astPath = join6(cwd, CONFIG_DIR, "ast-scan.json");
     const { mkdirSync: mkdirSync2, writeFileSync: writeFileSync2 } = await import("node:fs");
-    mkdirSync2(join5(cwd, CONFIG_DIR), { recursive: true });
+    mkdirSync2(join6(cwd, CONFIG_DIR), { recursive: true });
     writeFileSync2(astPath, JSON.stringify(ast, null, 2));
     const summary2 = summarizeAST(ast, astPath);
     return {
@@ -33473,7 +33603,7 @@ server.registerTool("levante_scan_ast_detail", {
   })
 }, async ({ category, filter, limit }) => {
   try {
-    const astPath = join5(process.cwd(), CONFIG_DIR, "ast-scan.json");
+    const astPath = join6(process.cwd(), CONFIG_DIR, "ast-scan.json");
     if (!existsSync5(astPath)) {
       return {
         content: [{ type: "text", text: "Error: No AST scan found. Run levante_scan_ast first." }],
@@ -33509,7 +33639,7 @@ server.registerTool("levante_build_qa_map", {
         payload.commitSha = sha;
       } catch {}
     }
-    const outputPath = output ?? join5(process.cwd(), CONFIG_DIR, "qa-map.json");
+    const outputPath = output ?? join6(process.cwd(), CONFIG_DIR, "qa-map.json");
     let written = false;
     if (validation.valid && !dryRun) {
       const { mkdirSync: mkdirSync2, writeFileSync: writeFileSync2 } = await import("node:fs");
@@ -33553,7 +33683,7 @@ server.registerTool("levante_read_qa_map", {
   })
 }, async ({ path }) => {
   try {
-    const mapPath = path ?? join5(process.cwd(), CONFIG_DIR, "qa-map.json");
+    const mapPath = path ?? join6(process.cwd(), CONFIG_DIR, "qa-map.json");
     if (!existsSync5(mapPath)) {
       return {
         content: [{ type: "text", text: JSON.stringify(null) }]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "levante",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "bin": {
     "levante": "./dist/cli.js",