e2e-ai 1.3.0 → 1.4.0

package/README.md

@@ -10,9 +10,12 @@ Includes a **codebase scanner** that builds a QA map of your application's featu
 # Install
 npm install e2e-ai
 
-# Initialize config + project context
+# Initialize config + copy agents
 npx e2e-ai init
 
+# Generate project context (use init-agent in your AI tool)
+# → produces .e2e-ai/context.md
+
 # Show all commands
 npx e2e-ai --help
 
@@ -57,7 +60,7 @@ Scans your codebase structure (routes, components, hooks), uses AI to identify f
 
 ### `init` - Project Setup
 
-Interactive wizard that scans your codebase and generates configuration + project context.
+Interactive wizard that creates `.e2e-ai/config.ts` and copies agent prompts to `.e2e-ai/agents/`.
 
 ```bash
 npx e2e-ai init
@@ -66,6 +69,8 @@ npx e2e-ai init
 npx e2e-ai init --non-interactive
 ```
 
+After init, use the **init-agent** in your AI tool (Claude Code, Cursor, etc.) to generate `.e2e-ai/context.md`. This context file teaches all downstream agents about your project's test conventions. If you have the MCP server configured, the AI tool can call `e2e_ai_scan_codebase` to analyze your project automatically.
+
 ---
 
 ### `record` - Browser Recording
@@ -409,7 +414,7 @@ npx e2e-ai analyze
 
 ## Configuration
 
-Run `npx e2e-ai init` to generate `e2e-ai.config.ts`:
+Run `npx e2e-ai init` to generate `.e2e-ai/config.ts`:
 
 ```typescript
 import { defineConfig } from 'e2e-ai/config';
@@ -463,12 +468,10 @@ export default defineConfig({
     retries: 0,
     traceMode: 'on',
   },
-
-  contextFile: '.e2e-ai/context.md',
 });
 ```
 
-See `templates/e2e-ai.context.example.md` for the project context file format.
+All configuration lives inside the `.e2e-ai/` directory — no files at project root.
 
 ## Global Options
 
@@ -524,7 +527,7 @@ You can customize agent behavior by editing the `.md` files directly. The frontm
 
 ## Output Directory Structure
 
-Default paths (configurable via `e2e-ai.config.ts`):
+Default paths (configurable via `.e2e-ai/config.ts`):
 
 ```
 e2e/
@@ -534,12 +537,85 @@ e2e/
 qa/                    # QA documentation .md files
 
 .e2e-ai/
+  config.ts            # project configuration
+  context.md           # project context (generated by init-agent)
+  agents/              # agent prompt definitions (.md files)
   <KEY>/               # per-issue working dir: codegen, recordings/, intermediate files
   ast-scan.json        # scan command output
   qa-map.json          # analyze command output
   scan-cache/          # file-level parse cache (gitignored)
 ```
 
+## MCP Server
+
+e2e-ai ships an MCP (Model Context Protocol) server that lets AI assistants interact with your project's test infrastructure directly. The server binary is `e2e-ai-mcp`.
+
+### Setup
+
+Add to your MCP client configuration:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "e2e-ai": {
+      "command": "npx",
+      "args": ["e2e-ai-mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add e2e-ai -- npx e2e-ai-mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "e2e-ai": {
+      "command": "npx",
+      "args": ["e2e-ai-mcp"]
+    }
+  }
+}
+```
+
+If e2e-ai is installed globally or as a project dependency, you can use the binary path directly instead of `npx`:
+
+```json
+{
+  "command": "node",
+  "args": ["node_modules/.bin/e2e-ai-mcp"]
+}
+```
+
+### Available Tools
+
+| Tool | Description | Input |
+|------|-------------|-------|
+| `e2e_ai_scan_codebase` | Scan project for test files, configs, fixtures, path aliases, and sample test content | `projectRoot?` (defaults to cwd) |
+| `e2e_ai_validate_context` | Validate that a context markdown file has all required sections | `content` (markdown string) |
+| `e2e_ai_read_agent` | Load an agent prompt by name — returns system prompt + config | `agentName` (e.g. `scenario-agent`) |
+| `e2e_ai_get_example` | Get the example context markdown template | (none) |
+
+### Usage with AI Assistants
+
+Once configured, an AI assistant can:
+
+1. **Scan your project** to understand its test structure, fixtures, and conventions
+2. **Read agent prompts** to understand how each pipeline step works
+3. **Validate context files** to ensure they have the right format before running commands
+4. **Get the example template** as a starting point for writing `e2e-ai.context.md`
+
+This enables AI assistants to help you set up e2e-ai, debug pipeline issues, and generate better project context files.
+
 ## Library API
 
 e2e-ai also exports types and config helpers for programmatic use:

package/agents/feature-analyzer-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: feature-analyzer-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.1
 ---
 
 # System Prompt

package/agents/init-agent.md

@@ -1,20 +1,24 @@
 ---
 agent: init-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.3
 ---
 
 # System Prompt
 
-You are a codebase analysis assistant for the e2e-ai test automation tool. Your job is to analyze a project's test infrastructure and produce a well-structured context document (`e2e-ai.context.md`) that will guide AI agents when generating, refining, and healing Playwright tests for this specific project.
+You are a codebase analysis assistant for the e2e-ai test automation tool. Your job is to analyze a project's test infrastructure and produce a well-structured context document (`.e2e-ai/context.md`) that will guide AI agents when generating, refining, and healing Playwright tests for this specific project.
 
-You will receive scan results from the target codebase and engage in a conversation to clarify patterns you're uncertain about.
+## How to Use This Agent
+
+This agent is designed to be used directly in your AI tool (Claude Code, Cursor, Gemini CLI, etc.). Start a conversation and ask it to generate your project context.
+
+**If the e2e-ai MCP server is configured**, call `e2e_ai_scan_codebase` to get scan results, then follow this agent's instructions to produce the context file.
+
+**If no MCP server**, manually explore the codebase: look at test files, fixtures, playwright config, tsconfig paths, and helper modules.
 
 ## Your Task
 
-Analyze the provided codebase scan and produce a context document covering:
+Analyze the project codebase and produce a file at `.e2e-ai/context.md` that documents the project's test infrastructure, conventions, and patterns. This context file is consumed by downstream AI agents (scenario, generator, refiner, healer, QA) to produce Playwright tests that match the project's existing style.
+
+Cover these areas:
 
 1. **Application Overview**: What the app does, tech stack, key pages/routes
 2. **Test Infrastructure**: Fixtures, custom test helpers, step counters, auth patterns
@@ -26,13 +30,13 @@ Analyze the provided codebase scan and produce a context document covering:
 
 ## Output Format
 
-When you have enough information, produce the final context as a markdown document with these sections:
+Produce the context document with these sections and save it to `.e2e-ai/context.md`:
 
 ```markdown
 # Project Context for e2e-ai
 
 ## Application
-<name, description, tech stack>
+<name, description, tech stack, base URL>
 
 ## Test Infrastructure
 <fixtures, helpers, auth pattern>
@@ -53,6 +57,22 @@ When you have enough information, produce the final context as a markdown docume
 <timeouts, waits, assertion patterns>
 ```
 
+All sections are required. The file should be 100-300 lines, self-contained, and use actual code from the project (not generic Playwright examples).
+
+## How Context is Used
+
+Each pipeline agent reads `.e2e-ai/context.md` to understand project conventions:
+
+| Agent | Uses context for |
+|-------|-----------------|
+| **scenario-agent** | Structuring test steps to match project patterns |
+| **playwright-generator-agent** | Generating code with correct imports, fixtures, selectors |
+| **refactor-agent** | Applying project-specific refactoring patterns |
+| **self-healing-agent** | Understanding expected test structure when fixing failures |
+| **qa-testcase-agent** | Formatting QA documentation to match conventions |
+| **feature-analyzer-agent** | Understanding app structure for QA map generation |
+| **scenario-planner-agent** | Generating realistic test scenarios from codebase analysis |
+
 ## Rules
 
 1. Ask clarifying questions if the scan data is ambiguous — do NOT guess
@@ -61,15 +81,3 @@ When you have enough information, produce the final context as a markdown docume
 4. The context file should be self-contained — an AI agent reading only this file should understand all project conventions
 5. Keep the document concise but complete — aim for 100-300 lines
 6. If you need to see specific files to complete the analysis, list them explicitly
-
-## Conversation Flow
-
-1. **First turn**: Receive scan results, analyze them, ask clarifying questions if needed
-2. **Middle turns**: Receive answers, refine understanding
-3. **Final turn**: When you have enough info, produce the complete context document wrapped in a `<context>` tag:
-   ```
-   <context>
-   # Project Context for e2e-ai
-   ...
-   </context>
-   ```

package/agents/playwright-generator-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: playwright-generator-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/qa-testcase-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: qa-testcase-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/refactor-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: refactor-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/scenario-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: scenario-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 4096
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/scenario-planner-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: scenario-planner-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/self-healing-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: self-healing-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 8192
-temperature: 0.2
 ---
 
 # System Prompt

package/agents/transcript-agent.md

@@ -1,9 +1,5 @@
 ---
 agent: transcript-agent
-version: "1.0"
-model: gpt-4o
-max_tokens: 4096
-temperature: 0.2
 ---
 
 # System Prompt

package/dist/cli-98db6h2q.js

@@ -0,0 +1,101 @@
+import {
+  getPackageRoot,
+  getProjectRoot
+} from "./cli-kx32qnf3.js";
+
+// src/agents/loadAgent.ts
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+function loadAgent(agentName, config) {
+  const localPath = join(getProjectRoot(), ".e2e-ai", "agents", `${agentName}.md`);
+  const packagePath = join(getPackageRoot(), "agents", `${agentName}.md`);
+  const filePath = existsSync(localPath) ? localPath : packagePath;
+  let content;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    throw new Error(`Agent file not found: ${filePath}`);
+  }
+  const { frontmatter, body } = parseFrontmatter(content);
+  const agentConfig = extractConfig(frontmatter);
+  let systemPrompt = body;
+  if (config) {
+    const contextPath = join(getProjectRoot(), ".e2e-ai", "context.md");
+    if (existsSync(contextPath)) {
+      const projectContext = readFileSync(contextPath, "utf-8").trim();
+      if (projectContext) {
+        systemPrompt = `${body}
+
+## Project Context
+
+${projectContext}`;
+      }
+    }
+    if (config.llm.agentModels[agentName]) {
+      agentConfig.model = config.llm.agentModels[agentName];
+    }
+  }
+  const sections = parseSections(body);
+  return {
+    name: frontmatter.agent ?? agentName,
+    systemPrompt,
+    inputSchema: sections["Input Schema"],
+    outputSchema: sections["Output Schema"],
+    rules: sections["Rules"],
+    example: sections["Example"],
+    config: agentConfig
+  };
+}
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match)
+    return { frontmatter: {}, body: content };
+  const frontmatter = {};
+  for (const line of match[1].split(`
+`)) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1)
+      continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"'))
+      value = value.slice(1, -1);
+    if (value === "true")
+      value = true;
+    if (value === "false")
+      value = false;
+    if (!isNaN(Number(value)) && value !== "")
+      value = Number(value);
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body: match[2] };
+}
+function extractConfig(frontmatter) {
+  return {
+    model: frontmatter.model,
+    maxTokens: frontmatter.max_tokens ?? 4096,
+    temperature: frontmatter.temperature ?? 0.2
+  };
+}
+function parseSections(body) {
+  const sections = {};
+  const headingRegex = /^##\s+(.+)$/gm;
+  const headings = [];
+  let match;
+  while ((match = headingRegex.exec(body)) !== null) {
+    headings.push({ title: match[1].trim(), index: match.index });
+  }
+  const systemMatch = body.match(/^#\s+System Prompt\n([\s\S]*?)(?=\n##\s|$)/m);
+  if (systemMatch) {
+    sections["System Prompt"] = systemMatch[1].trim();
+  }
+  for (let i = 0;i < headings.length; i++) {
+    const start = headings[i].index + body.slice(headings[i].index).indexOf(`
+`) + 1;
+    const end = i + 1 < headings.length ? headings[i + 1].index : body.length;
+    sections[headings[i].title] = body.slice(start, end).trim();
+  }
+  return sections;
+}
+
+export { loadAgent };

package/dist/cli-kx32qnf3.js

@@ -0,0 +1,67 @@
+import {
+  E2eAiConfigSchema
+} from "./cli-fgp618yt.js";
+
+// src/config/loader.ts
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+var CONFIG_DIR = ".e2e-ai";
+var CONFIG_FILENAMES = ["config.ts", "config.js", "config.mjs"];
+var cachedConfig = null;
+var cachedProjectRoot = null;
+function findConfigDir(startDir) {
+  let dir = resolve(startDir);
+  const root = dirname(dir) === dir ? dir : undefined;
+  while (true) {
+    const e2eDir = join(dir, CONFIG_DIR);
+    for (const name of CONFIG_FILENAMES) {
+      if (existsSync(join(e2eDir, name))) {
+        return dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir || dir === root)
+      return null;
+    dir = parent;
+  }
+}
+function getProjectRoot() {
+  if (cachedProjectRoot)
+    return cachedProjectRoot;
+  const found = findConfigDir(process.cwd());
+  cachedProjectRoot = found ?? process.cwd();
+  return cachedProjectRoot;
+}
+function getPackageRoot() {
+  let dir = import.meta.dirname;
+  while (!existsSync(join(dir, "package.json"))) {
+    const parent = dirname(dir);
+    if (parent === dir)
+      return dir;
+    dir = parent;
+  }
+  return dir;
+}
+async function loadConfig() {
+  if (cachedConfig)
+    return cachedConfig;
+  const projectRoot = getProjectRoot();
+  const e2eDir = join(projectRoot, CONFIG_DIR);
+  let userConfig = {};
+  for (const name of CONFIG_FILENAMES) {
+    const configPath = join(e2eDir, name);
+    if (existsSync(configPath)) {
+      try {
+        const fileUrl = pathToFileURL(configPath).href;
+        const mod = await import(fileUrl);
+        userConfig = mod.default ?? mod;
+        break;
+      } catch {}
+    }
+  }
+  cachedConfig = E2eAiConfigSchema.parse(userConfig);
+  return cachedConfig;
+}
+
+export { getProjectRoot, getPackageRoot, loadConfig };

package/dist/cli.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import {
-  loadAgent,
-  scanCodebase
-} from "./cli-6c0wsk32.js";
+  loadAgent
+} from "./cli-98db6h2q.js";
 import {
   getPackageRoot,
   getProjectRoot,
   loadConfig
-} from "./cli-cqabyzv3.js";
+} from "./cli-kx32qnf3.js";
 import"./cli-fgp618yt.js";
 import {
   __commonJS,
@@ -9057,10 +9056,11 @@ var import_picocolors2 = __toESM(require_picocolors(), 1);
 function registerInit(program2) {
   program2.command("init").description("Initialize e2e-ai configuration for your project").option("--non-interactive", "Skip interactive prompts, use defaults").action(async (cmdOpts) => {
     const projectRoot = getProjectRoot();
+    const e2eDir = join13(projectRoot, ".e2e-ai");
     header("e2e-ai init");
     const answers = cmdOpts?.nonInteractive ? getDefaultAnswers() : await askConfigQuestions();
     const config = buildConfigFromAnswers(answers);
-    const configPath = join13(projectRoot, "e2e-ai.config.ts");
+    const configPath = join13(e2eDir, "config.ts");
     if (fileExists(configPath)) {
       warn(`Config already exists: ${configPath}`);
       const overwrite = cmdOpts?.nonInteractive ? false : await dist_default4({ message: "Overwrite existing config?", default: false });
@@ -9074,28 +9074,15 @@ function registerInit(program2) {
       writeFile(configPath, generateConfigFile(config));
       success(`Config written: ${configPath}`);
     }
-    const spinner = createSpinner();
-    spinner.start("Scanning codebase for test patterns...");
-    const scan = await scanCodebase(projectRoot);
-    spinner.stop();
-    if (scan.testFiles.length === 0 && scan.configFiles.length === 0) {
-      warn("No test files found. Scan results will be minimal.");
-    } else {
-      info(`Found ${scan.testFiles.length} test files, ${scan.configFiles.length} config files`);
-    }
-    const instructionsContent = generateInstructionsFile(scan);
-    const instructionsPath = join13(projectRoot, "e2e-ai.instructions.md");
-    writeFile(instructionsPath, instructionsContent);
-    success(`Instructions written: ${instructionsPath}`);
-    const copiedCount = await copyAgentsToLocal(projectRoot, !!cmdOpts?.nonInteractive);
+    await copyAgentsToLocal(projectRoot, !!cmdOpts?.nonInteractive);
     console.log("");
     success(`Initialization complete!
 `);
     console.log(import_picocolors2.default.bold("Next steps:"));
-    console.log(`  1. Open ${import_picocolors2.default.cyan("e2e-ai.instructions.md")} with your AI tool`);
+    console.log(`  1. Use the ${import_picocolors2.default.cyan("init-agent")} in your AI tool to generate ${import_picocolors2.default.cyan(".e2e-ai/context.md")}`);
+    console.log(`     (or use the MCP server: ${import_picocolors2.default.cyan("e2e_ai_scan_codebase")} + ${import_picocolors2.default.cyan("e2e_ai_read_agent")})`);
     console.log(`  2. Review the generated ${import_picocolors2.default.cyan(".e2e-ai/context.md")}`);
-    console.log(`  3. Customize agents in ${import_picocolors2.default.cyan(".e2e-ai/agents/")} if needed`);
-    console.log(`  4. Run: ${import_picocolors2.default.cyan("e2e-ai run --key PROJ-101")}`);
+    console.log(`  3. Run: ${import_picocolors2.default.cyan("e2e-ai run --key PROJ-101")}`);
   });
 }
 function getDefaultAnswers() {
@@ -9157,8 +9144,7 @@ function buildConfigFromAnswers(answers) {
     inputSource: answers.inputSource,
     outputTarget: answers.outputTarget,
     voice: { enabled: answers.voiceEnabled },
-    llm: { provider: answers.provider },
-    contextFile: ".e2e-ai/context.md"
+    llm: { provider: answers.provider }
   };
   if (answers.baseUrl) {
     config.baseUrl = answers.baseUrl;
@@ -9190,127 +9176,6 @@ function generateConfigFile(config) {
   return lines.join(`
 `);
 }
-function generateInstructionsFile(scan) {
-  const packageRoot = getPackageRoot();
-  const sections = [];
-  sections.push(`# e2e-ai: Context Generation Instructions
-
-This file was generated by \`e2e-ai init\`. It contains everything an AI tool needs to generate \`.e2e-ai/context.md\` for your project.
-
-## How to Use
-
-1. Open this file in your AI tool (Claude Code, Cursor, Gemini CLI, etc.)
-2. Ask it to follow these instructions to generate \`.e2e-ai/context.md\`
-3. Review the generated file and adjust as needed
-
-Alternatively, if the e2e-ai MCP server is configured, your AI tool can call \`e2e_ai_scan_codebase\` and \`e2e_ai_validate_context\` directly.
-
----`);
-  sections.push(`## Task
-
-Scan this codebase and generate a file at \`.e2e-ai/context.md\` that documents the project's test infrastructure, conventions, and patterns. This context file is consumed by downstream AI agents (scenario, generator, refiner, healer, QA) to produce Playwright tests that match the project's existing style.`);
-  sections.push(`## Codebase Scan Results
-
-The following was pre-computed during \`e2e-ai init\`:
-
-### Test Files (${scan.testFiles.length} found)
-${scan.testFiles.length > 0 ? scan.testFiles.slice(0, 20).map((f) => `- \`${f}\``).join(`
-`) : "_No test files found_"}
-${scan.testFiles.length > 20 ? `
-_(${scan.testFiles.length - 20} more not shown)_` : ""}
-
-### Config Files
-${scan.configFiles.length > 0 ? scan.configFiles.map((f) => `- \`${f}\``).join(`
-`) : "_None found_"}
-
-### Fixture Files
-${scan.fixtureFiles.length > 0 ? scan.fixtureFiles.slice(0, 10).map((f) => `- \`${f}\``).join(`
-`) : "_None found_"}
-
-### Feature Files
-${scan.featureFiles.length > 0 ? scan.featureFiles.slice(0, 20).map((f) => `- \`${f}\``).join(`
-`) : "_None found_"}
-
-### Path Aliases (from tsconfig.json)
-${Object.keys(scan.tsconfigPaths).length > 0 ? Object.entries(scan.tsconfigPaths).map(([alias, targets]) => `- \`${alias}\` -> \`${targets.join(", ")}\``).join(`
-`) : "_None configured_"}
-
-### Playwright Config
-${scan.playwrightConfig ? `Found: \`${scan.playwrightConfig}\`` : "_Not found_"}
-
-### Sample Test Content
-${scan.sampleTestContent ? "```typescript\n" + scan.sampleTestContent + "\n```" : "_No sample available_"}`);
-  let agentChecklist = "";
-  try {
-    const agentContent = readFileSync2(join13(packageRoot, "agents", "init-agent.md"), "utf-8");
-    const bodyMatch = agentContent.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-    if (bodyMatch) {
-      agentChecklist = bodyMatch[1].trim();
-    }
-  } catch {}
-  if (agentChecklist) {
-    sections.push(`## What to Look For
-
-The following guidance comes from the e2e-ai init agent:
-
-${agentChecklist}`);
-  }
-  sections.push(`## Output Format
-
-The generated \`.e2e-ai/context.md\` MUST contain these sections:
-
-\`\`\`markdown
-# Project Context for e2e-ai
-
-## Application
-<name, description, tech stack, base URL>
-
-## Test Infrastructure
-<fixtures, helpers, auth pattern>
-
-## Feature Methods
-<method signatures grouped by module>
-
-## Import Conventions
-<path aliases, standard imports>
-
-## Selector Conventions
-<preferred selector strategies, patterns>
-
-## Test Structure Template
-<code template showing standard test layout>
-
-## Utility Patterns
-<timeouts, waits, assertion patterns>
-\`\`\`
-
-All sections are required. The file should be 100-300 lines, self-contained, and use actual code from the project (not generic Playwright examples).`);
-  sections.push(`## How Context is Used
-
-Each pipeline agent reads \`.e2e-ai/context.md\` to understand project conventions:
-
-| Agent | Uses context for |
-|-------|-----------------|
-| **scenario-agent** | Structuring test steps to match project patterns |
-| **playwright-generator-agent** | Generating code with correct imports, fixtures, selectors |
-| **refactor-agent** | Applying project-specific refactoring patterns |
-| **self-healing-agent** | Understanding expected test structure when fixing failures |
-| **qa-testcase-agent** | Formatting QA documentation to match conventions |`);
-  let exampleContent = "";
-  try {
-    exampleContent = readFileSync2(join13(packageRoot, "templates", "e2e-ai.context.example.md"), "utf-8");
-  } catch {}
-  if (exampleContent) {
-    sections.push(`## Complete Example
-
-Below is a full example of a well-structured context file:
-
-${exampleContent}`);
-  }
-  return sections.join(`
-
-`);
-}
 async function copyAgentsToLocal(projectRoot, nonInteractive) {
   const packageRoot = getPackageRoot();
   const sourceDir = join13(packageRoot, "agents");

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   getPackageRoot,
   getProjectRoot,
   loadConfig
-} from "./cli-cqabyzv3.js";
+} from "./cli-kx32qnf3.js";
 import {
   defineConfig
 } from "./cli-fgp618yt.js";

package/dist/mcp.js

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 import {
-  loadAgent,
-  scanCodebase
-} from "./cli-6c0wsk32.js";
+  loadAgent
+} from "./cli-98db6h2q.js";
 import {
   getPackageRoot
-} from "./cli-cqabyzv3.js";
+} from "./cli-kx32qnf3.js";
 import {
   $ZodObject,
   $ZodType,
@@ -14857,8 +14856,72 @@ class StdioServerTransport {
 }
 
 // src/mcp.ts
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync as readFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/utils/scan.ts
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+async function scanCodebase(root) {
+  const scan = {
+    testFiles: [],
+    configFiles: [],
+    fixtureFiles: [],
+    featureFiles: [],
+    tsconfigPaths: {},
+    playwrightConfig: null,
+    sampleTestContent: null
+  };
+  function walk(dir, depth = 0) {
+    if (depth > 5)
+      return [];
+    const files = [];
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist")
+          continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          files.push(...walk(full, depth + 1));
+        } else {
+          files.push(full);
+        }
+      }
+    } catch {}
+    return files;
+  }
+  const allFiles = walk(root);
+  for (const file of allFiles) {
+    const rel = relative(root, file);
+    if (rel.endsWith(".test.ts") || rel.endsWith(".spec.ts")) {
+      scan.testFiles.push(rel);
+      if (!scan.sampleTestContent && scan.testFiles.length <= 3) {
+        try {
+          scan.sampleTestContent = readFileSync(file, "utf-8").slice(0, 3000);
+        } catch {}
+      }
+    }
+    if (rel.endsWith(".feature.ts"))
+      scan.featureFiles.push(rel);
+    if (rel.includes("fixture") && rel.endsWith(".ts"))
+      scan.fixtureFiles.push(rel);
+    if (rel === "playwright.config.ts" || rel === "playwright.config.js")
+      scan.playwrightConfig = rel;
+    if (rel === "tsconfig.json" || rel.endsWith("/tsconfig.json")) {
+      try {
+        const tsconfig = JSON.parse(readFileSync(file, "utf-8"));
+        if (tsconfig.compilerOptions?.paths) {
+          scan.tsconfigPaths = { ...scan.tsconfigPaths, ...tsconfig.compilerOptions.paths };
+        }
+      } catch {}
+    }
+  }
+  for (const name of ["playwright.config.ts", "vitest.config.ts", "jest.config.ts", "tsconfig.json", "package.json"]) {
+    if (existsSync(join(root, name)))
+      scan.configFiles.push(name);
+  }
+  return scan;
+}
 
 // src/utils/validateContext.ts
 var REQUIRED_SECTIONS = [
@@ -14955,8 +15018,8 @@ server.registerTool("e2e_ai_get_example", {
   inputSchema: exports_external.object({})
 }, async () => {
   try {
-    const examplePath = join(getPackageRoot(), "templates", "e2e-ai.context.example.md");
-    const content = readFileSync(examplePath, "utf-8");
+    const examplePath = join2(getPackageRoot(), "templates", "e2e-ai.context.example.md");
+    const content = readFileSync2(examplePath, "utf-8");
     return {
       content: [{ type: "text", text: content }]
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "e2e-ai",
   "description": "AI-powered test automation pipeline — record, transcribe, generate, heal and ship Playwright tests from a single CLI",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "type": "module",
   "bin": {

package/scripts/codegen-env.mjs

@@ -129,8 +129,54 @@ console.error(`Voice recording: ${voiceEnabled ? 'ENABLED' : 'disabled (--no-voi
 console.error(`Trace replay:    ${traceEnabled ? 'ENABLED' : 'disabled (--no-trace)'}`);
 console.error('(When you close the Playwright Inspector, the file is written there.)\n');
 
+// --- Session timing (always track, used for action timestamps) ---
+const sessionStartTime = Date.now();
+
+// --- Action timestamp tracking via file polling ---
+const actionPattern = /^\s*(await\s+page\.|await\s+expect\()/;
+let prevActionCount = 0;
+const actionElapsedSec = []; // elapsed seconds for each action, in order
+let pollInterval = null;
+
+function startActionPolling() {
+  pollInterval = setInterval(() => {
+    if (!existsSync(outputPath)) return;
+    try {
+      const content = readFileSync(outputPath, 'utf-8');
+      const actionLines = content.split('\n').filter((l) => actionPattern.test(l));
+      const newCount = actionLines.length;
+      if (newCount > prevActionCount) {
+        const elapsed = (Date.now() - sessionStartTime) / 1000;
+        for (let i = prevActionCount; i < newCount; i++) {
+          actionElapsedSec.push(elapsed);
+        }
+        prevActionCount = newCount;
+      }
+    } catch {
+      // File might be mid-write — ignore
+    }
+  }, 500);
+}
+
+/** Inject // @t:<seconds>s comments above each action line in the codegen file. */
+function injectActionTimestamps(filePath) {
+  if (actionElapsedSec.length === 0) return;
+  const content = readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const result = [];
+  let idx = 0;
+  for (const line of lines) {
+    if (actionPattern.test(line) && idx < actionElapsedSec.length) {
+      const indent = line.match(/^(\s*)/)[1];
+      result.push(`${indent}// @t:${actionElapsedSec[idx].toFixed(1)}s`);
+      idx++;
+    }
+    result.push(line);
+  }
+  writeFileSync(filePath, result.join('\n'));
+}
+
 // --- Voice setup ---
-let sessionStartTime = null;
 let recording = false;
 let currentRecProcess = null;
 let segmentIndex = 0;
@@ -147,8 +193,6 @@ if (voiceEnabled) {
     mkdirSync(recordingsDir, { recursive: true });
   }
 
-  sessionStartTime = Date.now();
-
   const segPath = resolve(recordingsDir, `seg-${String(segmentIndex).padStart(3, '0')}.wav`);
   segmentPaths.push(segPath);
   const rec = startRecording(segPath);
@@ -195,6 +239,9 @@ const child = spawn('npx', codegenArgs, {
   shell: true,
 });
 
+// Start polling the output file for new actions to capture timestamps
+startActionPolling();
+
 // --- Keyboard listener for pause/resume ---
 if (voiceEnabled && process.stdin.isTTY) {
   process.stdin.setRawMode(true);
@@ -238,16 +285,20 @@ function cleanupTerminal() {
 
 child.on('exit', async (code) => {
   cleanupTerminal();
+  if (pollInterval) clearInterval(pollInterval);
 
   if (code === 0) {
     console.error(`\nSaved: ${outputRelative}`);
   }
 
-  // --- Voice post-processing ---
-  if (voiceEnabled && segmentPaths.length > 0) {
-    const sessionEndTime = Date.now();
-    const durationSec = (sessionEndTime - sessionStartTime) / 1000;
+  // --- Inject action timestamps into codegen output ---
+  if (existsSync(outputPath) && actionElapsedSec.length > 0) {
+    injectActionTimestamps(outputPath);
+    console.error(`Injected ${actionElapsedSec.length} action timestamp(s) into: ${outputRelative}`);
+  }
 
+  // --- Voice post-processing: merge WAV segments only (transcription deferred to transcribe command) ---
+  if (voiceEnabled && segmentPaths.length > 0) {
     try {
       if (recording && currentRecProcess) {
         const { stopRecording } = await import(resolve(__dirname, 'voice', 'recorder.mjs'));
@@ -260,45 +311,26 @@ child.on('exit', async (code) => {
 
       if (existingSegments.length === 0) {
         console.error('No audio segments recorded.');
-        process.exit(code ?? 0);
-        return;
-      }
-
-      const mergedWavPath = resolve(recordingsDir, `voice-${timestamp}.wav`);
-
-      if (existingSegments.length === 1) {
-        renameSync(existingSegments[0], mergedWavPath);
       } else {
-        console.error(`Merging ${existingSegments.length} audio segments...`);
-        const args = ['--combine', 'concatenate', ...existingSegments, mergedWavPath];
-        execSync(`sox ${args.map((a) => `"${a}"`).join(' ')}`, { stdio: 'ignore' });
-
-        for (const seg of existingSegments) {
-          try { unlinkSync(seg); } catch {}
+        const mergedWavPath = resolve(recordingsDir, `voice-${timestamp}.wav`);
+
+        if (existingSegments.length === 1) {
+          renameSync(existingSegments[0], mergedWavPath);
+        } else {
+          console.error(`Merging ${existingSegments.length} audio segments...`);
+          const args = ['--combine', 'concatenate', ...existingSegments, mergedWavPath];
+          execSync(`sox ${args.map((a) => `"${a}"`).join(' ')}`, { stdio: 'ignore' });
+
+          for (const seg of existingSegments) {
+            try { unlinkSync(seg); } catch {}
+          }
         }
-      }
-
-      console.error(`Audio saved: ${relative(root, mergedWavPath)}`);
 
-      const { transcribe } = await import(resolve(__dirname, 'voice', 'transcriber.mjs'));
-      const segments = await transcribe(mergedWavPath);
-
-      const transcriptPath = resolve(recordingsDir, `voice-${timestamp}.json`);
-      writeFileSync(transcriptPath, JSON.stringify(segments, null, 2));
-      console.error(`Transcript saved: ${relative(root, transcriptPath)}`);
-
-      if (segments.length > 0 && existsSync(outputPath)) {
-        const { merge } = await import(resolve(__dirname, 'voice', 'merger.mjs'));
-        const codegenContent = readFileSync(outputPath, 'utf-8');
-        const annotated = merge(codegenContent, segments, durationSec);
-        writeFileSync(outputPath, annotated);
-        console.error(`Merged ${segments.length} voice segment(s) into: ${outputRelative}`);
+        console.error(`\nVoice recording summary:`);
+        console.error(`  Audio:   ${relative(root, mergedWavPath)}`);
+        console.error(`  Codegen: ${outputRelative}`);
+        console.error(`  (Run 'transcribe' to process voice → merge into codegen)`);
       }
-
-      console.error('\nVoice recording summary:');
-      console.error(`  Audio:      ${relative(root, mergedWavPath)}`);
-      console.error(`  Transcript: ${relative(root, transcriptPath)}`);
-      console.error(`  Codegen:    ${outputRelative}`);
     } catch (err) {
       console.error(`\nVoice processing error: ${err.message}`);
     }

package/scripts/voice/merger.mjs

@@ -9,16 +9,42 @@ function formatTime(sec) {
   return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
 }
 
+/**
+ * Extract real action timestamps from // @t:<seconds>s comments injected during codegen.
+ * Returns an array of { lineIndex, elapsed } or null if no timestamps found.
+ *
+ * @param {string[]} lines
+ * @param {number[]} actionIndices - line indices of action lines
+ * @returns {number[] | null} elapsed seconds per action, or null
+ */
+function extractEmbeddedTimestamps(lines, actionIndices) {
+  const tsPattern = /^\s*\/\/\s*@t:([\d.]+)s\s*$/;
+  const timestamps = [];
+
+  for (const actionIdx of actionIndices) {
+    // Look at the line immediately before the action for a @t: comment
+    if (actionIdx > 0 && tsPattern.test(lines[actionIdx - 1])) {
+      const match = lines[actionIdx - 1].match(tsPattern);
+      timestamps.push(parseFloat(match[1]));
+    } else {
+      // Missing timestamp for this action — can't use embedded timestamps
+      return null;
+    }
+  }
+
+  return timestamps;
+}
+
 /**
  * Merge codegen output with voice transcript segments.
  *
- * Action lines (await page.* / await expect(*) are identified and distributed
- * linearly across the session duration. Each speech segment is inserted as a
- * comment before the nearest action line.
+ * If the codegen contains // @t:<seconds>s comments (injected during recording),
+ * those real timestamps are used for alignment. Otherwise, action timestamps are
+ * distributed linearly across the session duration (fallback).
  *
  * @param {string} codegenContent - The original codegen .ts file content
  * @param {Array<{ start: number, end: number, text: string }>} segments - Whisper transcript segments
- * @param {number} durationSec - Total session duration in seconds
+ * @param {number} durationSec - Total session duration in seconds (used only for linear fallback)
  * @returns {string} Annotated codegen content
  */
 export function merge(codegenContent, segments, durationSec) {
@@ -26,8 +52,9 @@ export function merge(codegenContent, segments, durationSec) {
 
   const lines = codegenContent.split('\n');
   const actionPattern = /^\s*(await\s+page\.|await\s+expect\()/;
+  const tsCommentPattern = /^\s*\/\/\s*@t:[\d.]+s\s*$/;
 
-  // Find indices of action lines
+  // Find indices of action lines (skip @t: comment lines)
   const actionIndices = [];
   for (let i = 0; i < lines.length; i++) {
     if (actionPattern.test(lines[i])) {
@@ -37,14 +64,16 @@ export function merge(codegenContent, segments, durationSec) {
 
   if (actionIndices.length === 0) return codegenContent;
 
-  // Estimate timestamp for each action: distribute linearly across the session
-  const actionTimestamps = actionIndices.map((_, idx) => {
-    if (actionIndices.length === 1) return durationSec / 2;
-    return (idx / (actionIndices.length - 1)) * durationSec;
-  });
+  // Try to use embedded timestamps, fall back to linear distribution
+  const embeddedTs = extractEmbeddedTimestamps(lines, actionIndices);
+  const actionTimestamps = embeddedTs
+    ? embeddedTs
+    : actionIndices.map((_, idx) => {
+        if (actionIndices.length === 1) return durationSec / 2;
+        return (idx / (actionIndices.length - 1)) * durationSec;
+      });
 
   // For each segment, find the nearest action by timestamp
-  // Map: actionIndex → list of segments to insert before it
   /** @type {Map<number, Array<{ start: number, end: number, text: string }>>} */
   const insertions = new Map();
 
@@ -68,12 +97,14 @@ export function merge(codegenContent, segments, durationSec) {
     insertions.get(actionLineIdx).push(seg);
   }
 
-  // Build result: insert comment lines before action lines
+  // Build result: strip old @t: comments and insert voice comments before action lines
   const result = [];
   for (let i = 0; i < lines.length; i++) {
+    // Skip @t: timestamp comments — they're consumed, not preserved
+    if (tsCommentPattern.test(lines[i])) continue;
+
     const segs = insertions.get(i);
     if (segs) {
-      // Detect indentation of the action line
       const indent = lines[i].match(/^(\s*)/)[1];
       for (const seg of segs) {
         result.push(