levante 0.3.4 → 0.3.6

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

@@ -56844,7 +56844,7 @@ var init_build3 = __esm(async () => {
 
 // src/tui/CommandInspect.tsx
 function CommandInspect({ theme, cliName, command, globalOptions, onRun, onBack }) {
-  const allOptions = [...command.options, ...globalOptions];
+  const allOptions = command.hideGlobalOptions ? [...command.options] : [...command.options, ...globalOptions];
   const [fields, setFields] = import_react25.useState(() => ({
     args: Object.fromEntries(command.args.map((a) => [a.name, ""])),
     booleans: Object.fromEntries(allOptions.filter((o) => o.type === "boolean").map((o) => [o.flags, false])),
@@ -56859,12 +56859,14 @@ function CommandInspect({ theme, cliName, command, globalOptions, onRun, onBack
   use_input_default((input, key) => {
     if (key.escape)
       return onBack();
+    if (command.InlineView)
+      return;
     if (key.tab) {
       setFocusIndex((i) => (i + 1) % Math.max(focusableFields.length, 1));
       return;
     }
     if (key.return) {
-      const argv = [command.name];
+      const argv = [...command.baseArgv ?? [command.name]];
       for (const arg of command.args) {
         const val = fields.args[arg.name]?.trim();
         if (val)
@@ -56900,6 +56902,60 @@ function CommandInspect({ theme, cliName, command, globalOptions, onRun, onBack
   }
   if (allOptions.length > 0)
     usageParts.push("[options]");
+  if (command.InlineView) {
+    return /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
+      flexDirection: "column",
+      paddingX: 1,
+      children: [
+        /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
+          justifyContent: "space-between",
+          marginBottom: 1,
+          children: [
+            /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Text, {
+              dimColor: true,
+              children: "← esc"
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Text, {
+              color: theme.accent,
+              bold: true,
+              children: [
+                cliName,
+                " ",
+                command.name
+              ]
+            }, undefined, true, undefined, this)
+          ]
+        }, undefined, true, undefined, this),
+        /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(command.InlineView, {
+          theme
+        }, undefined, false, undefined, this),
+        /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
+          marginTop: 1,
+          children: /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Text, {
+            dimColor: true,
+            children: "esc back"
+          }, undefined, false, undefined, this)
+        }, undefined, false, undefined, this)
+      ]
+    }, undefined, true, undefined, this);
+  }
+  const previewArgv = [cliName, ...command.baseArgv ?? [command.name]];
+  for (const arg of command.args) {
+    const val = fields.args[arg.name]?.trim();
+    if (val)
+      previewArgv.push(val);
+  }
+  for (const opt of allOptions) {
+    if (opt.type === "boolean" && fields.booleans[opt.flags]) {
+      previewArgv.push(opt.flags);
+    }
+    if (opt.type === "string") {
+      const val = fields.strings[opt.flags]?.trim();
+      if (val)
+        previewArgv.push(opt.flags, val);
+    }
+  }
+  const previewCommand = previewArgv.join(" ");
   const renderOption = (opt) => {
     const isFocused = currentFocus === `opt:${opt.flags}`;
     if (opt.type === "boolean") {
@@ -56998,6 +57054,7 @@ function CommandInspect({ theme, cliName, command, globalOptions, onRun, onBack
             children: "USAGE"
           }, undefined, false, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Text, {
+            dimColor: true,
             children: [
               "  ",
               usageParts.join(" ")
@@ -57005,6 +57062,24 @@ function CommandInspect({ theme, cliName, command, globalOptions, onRun, onBack
           }, undefined, true, undefined, this)
         ]
       }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
+        flexDirection: "column",
+        marginBottom: 1,
+        children: [
+          /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Text, {
+            dimColor: true,
+            bold: true,
+            children: "COMMAND"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Text, {
+            color: theme.accent,
+            children: [
+              "  $ ",
+              previewCommand
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
       command.args.length > 0 && /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
         flexDirection: "column",
         marginBottom: 1,
@@ -57051,7 +57126,7 @@ function CommandInspect({ theme, cliName, command, globalOptions, onRun, onBack
           command.options.map(renderOption)
         ]
       }, undefined, true, undefined, this),
-      globalOptions.length > 0 && /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
+      !command.hideGlobalOptions && globalOptions.length > 0 && /* @__PURE__ */ jsx_dev_runtime3.jsxDEV(Box_default, {
         flexDirection: "column",
         marginBottom: 1,
         children: [
@@ -57095,9 +57170,108 @@ var init_theme2 = __esm(() => {
   };
 });
 
+// src/tui/McpInline.tsx
+function McpInline({ theme: theme2 }) {
+  return /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Box_default, {
+    flexDirection: "column",
+    gap: 1,
+    children: [
+      /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Box_default, {
+        flexDirection: "column",
+        children: [
+          /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            bold: true,
+            children: "Claude Code — add to project"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            color: theme2.accent,
+            children: "  claude mcp add levante -- levante-mcp"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Box_default, {
+        flexDirection: "column",
+        children: [
+          /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            bold: true,
+            children: "Claude Code — add globally"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            color: theme2.accent,
+            children: "  claude mcp add levante -s user -- levante-mcp"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Box_default, {
+        flexDirection: "column",
+        children: [
+          /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            bold: true,
+            children: "Claude Desktop / other clients"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            dimColor: true,
+            children: "  ~/.config/claude/claude_desktop_config.json"
+          }, undefined, false, undefined, this),
+          CONFIG.split(`
+`).map((line, i) => /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            color: theme2.accent,
+            children: [
+              "  ",
+              line
+            ]
+          }, i, true, undefined, this))
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Box_default, {
+        flexDirection: "column",
+        children: [
+          /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            bold: true,
+            children: "Available tools"
+          }, undefined, false, undefined, this),
+          TOOLS2.map((t) => /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+            dimColor: true,
+            children: [
+              "  · ",
+              /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Text, {
+                color: theme2.accentSecondary,
+                children: t
+              }, undefined, false, undefined, this)
+            ]
+          }, t, true, undefined, this))
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+var jsx_dev_runtime4, CONFIG = `{
+  "mcpServers": {
+    "levante": {
+      "command": "levante-mcp"
+    }
+  }
+}`, TOOLS2;
+var init_McpInline = __esm(async () => {
+  await init_build2();
+  jsx_dev_runtime4 = __toESM(require_jsx_dev_runtime(), 1);
+  TOOLS2 = [
+    "levante_plan_workflow",
+    "levante_execute_step",
+    "levante_scan_codebase",
+    "levante_read_agent",
+    "levante_scan_ast",
+    "levante_scan_ast_detail",
+    "levante_build_qa_map",
+    "levante_read_qa_map",
+    "levante_get_workflow_guide"
+  ];
+});
+
 // src/tui/commands.ts
 var commandGroups;
-var init_commands = __esm(() => {
+var init_commands = __esm(async () => {
+  await init_McpInline();
   commandGroups = [
     {
       label: "⚡ PIPELINE",
@@ -57182,16 +57356,73 @@ var init_commands = __esm(() => {
       label: "\uD83D\uDD17 INTEGRATIONS",
       commands: [
         {
-          name: "auth",
+          name: "auth login",
+          baseArgv: ["auth", "login"],
           args: [],
-          description: "Manage QA Intelligence authentication",
-          options: []
+          description: "Authenticate with QA Intelligence — opens browser for sign-in",
+          options: [],
+          hideGlobalOptions: true
         },
         {
-          name: "jira",
+          name: "auth logout",
+          baseArgv: ["auth", "logout"],
           args: [],
-          description: "Browse and search Jira issues",
-          options: []
+          description: "Sign out and revoke CLI token",
+          options: [],
+          hideGlobalOptions: true
+        },
+        {
+          name: "auth status",
+          baseArgv: ["auth", "status"],
+          args: [],
+          description: "Show current authentication status",
+          options: [],
+          hideGlobalOptions: true
+        },
+        {
+          name: "auth switch",
+          baseArgv: ["auth", "switch"],
+          args: [],
+          description: "Switch scope — re-authenticate with a different org/project/app",
+          options: [],
+          hideGlobalOptions: true
+        },
+        {
+          name: "mcp",
+          args: [],
+          description: "Show MCP server setup instructions for Claude",
+          options: [],
+          hideGlobalOptions: true,
+          InlineView: McpInline
+        },
+        {
+          name: "jira browse",
+          baseArgv: ["jira", "browse"],
+          args: [],
+          description: "Interactive Jira issue browser — search, select, and start test workflow",
+          options: [],
+          hideGlobalOptions: true
+        },
+        {
+          name: "jira search",
+          baseArgv: ["jira", "search"],
+          args: [{ name: "query", required: true, description: "Text search query" }],
+          description: "Search Jira issues by text or raw JQL",
+          options: [
+            { flags: "--jql", description: "Use raw JQL instead of text search", type: "string", placeholder: "jql" },
+            { flags: "--max", description: "Maximum results to return", type: "string", placeholder: "n", default: "20" }
+          ],
+          hideGlobalOptions: true
+        },
+        {
+          name: "jira show",
+          baseArgv: ["jira", "show"],
+          args: [{ name: "issueKey", required: true, description: "Issue key (e.g. PROJ-101)" }],
+          description: "Show full Jira issue details",
+          options: [
+            { flags: "--save", description: "Save issue context for pipeline use", type: "boolean" }
+          ],
+          hideGlobalOptions: true
         }
       ]
     }
@@ -57225,22 +57456,22 @@ function App2({ version: version2, onRunCommand, onQuit }) {
     exit();
     onRunCommand(argv);
   }, [exit, onRunCommand]);
-  return /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Box_default, {
+  return /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(Box_default, {
     flexDirection: "column",
     children: [
-      screen === "banner" && /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(Banner, {
+      screen === "banner" && /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(Banner, {
         theme,
         version: version2,
         onComplete: handleBannerComplete
       }, undefined, false, undefined, this),
-      screen === "browser" && /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(CommandBrowser, {
+      screen === "browser" && /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(CommandBrowser, {
         theme,
         version: version2,
         groups: commandGroups,
         onSelect: handleSelect,
         onQuit: handleQuit
       }, undefined, false, undefined, this),
-      screen === "inspect" && inspectCommand && /* @__PURE__ */ jsx_dev_runtime4.jsxDEV(CommandInspect, {
+      screen === "inspect" && inspectCommand && /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(CommandInspect, {
         theme,
         cliName: "levante",
         command: inspectCommand,
@@ -57253,7 +57484,7 @@ function App2({ version: version2, onRunCommand, onQuit }) {
 }
 async function launchTui(program2) {
   const version2 = program2.version() || "0.0.0";
-  return new Promise((resolve2, reject2) => {
+  return new Promise((resolve2) => {
     let resolved = false;
     const done = () => {
       if (!resolved) {
@@ -57261,35 +57492,49 @@ async function launchTui(program2) {
         resolve2();
       }
     };
-    const instance = render_default(/* @__PURE__ */ jsx_dev_runtime4.jsxDEV(App2, {
+    let runningCommand = false;
+    const instance = render_default(/* @__PURE__ */ jsx_dev_runtime5.jsxDEV(App2, {
       version: version2,
       onRunCommand: (argv) => {
+        runningCommand = true;
         instance.waitUntilExit().then(() => {
-          program2.parseAsync(argv, { from: "user" }).then(done).catch((err) => {
-            if (err?.name === "ExitPromptError") {
-              process.exit(0);
+          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;
             }
-            reject2(err);
-          });
+            done();
+          }, 50);
         });
       },
       onQuit: done
     }, undefined, false, undefined, this));
-    instance.waitUntilExit().then(done);
+    instance.waitUntilExit().then(() => {
+      if (!runningCommand)
+        done();
+    });
   });
 }
-var import_react26, jsx_dev_runtime4, globalOptions;
+var import_react26, jsx_dev_runtime5, globalOptions;
 var init_App2 = __esm(async () => {
   init_theme2();
-  init_commands();
   await __promiseAll([
     init_build2(),
     init_Banner(),
     init_CommandBrowser(),
-    init_CommandInspect()
+    init_CommandInspect(),
+    init_commands()
   ]);
   import_react26 = __toESM(require_react(), 1);
-  jsx_dev_runtime4 = __toESM(require_jsx_dev_runtime(), 1);
+  jsx_dev_runtime5 = __toESM(require_jsx_dev_runtime(), 1);
   globalOptions = [
     { flags: "--key", description: "Issue key (e.g., PROJ-101, LIN-42)", type: "string", placeholder: "KEY" },
     { flags: "--provider", description: "LLM provider (openai|anthropic)", type: "string", placeholder: "provider" },
@@ -75265,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;
     }
   });
 }
@@ -75474,7 +75726,7 @@ async function copyWorkflowGuide(projectRoot, nonInteractive) {
 // src/commands/auth.ts
 init_dist10();
 function registerAuth(program2) {
-  registerAuthCommands(program2, { defaultWebappUrl: "https://app.qaligent.dev" });
+  registerAuthCommands(program2);
 }
 
 // src/commands/jira.ts
@@ -75735,6 +75987,57 @@ function registerJira(program2) {
   });
 }
 
+// src/commands/mcp.ts
+var import_picocolors7 = __toESM(require_picocolors(), 1);
+var TOOLS = [
+  "levante_plan_workflow",
+  "levante_execute_step",
+  "levante_scan_codebase",
+  "levante_validate_context",
+  "levante_read_agent",
+  "levante_get_example",
+  "levante_get_workflow_guide",
+  "levante_scan_ast",
+  "levante_scan_ast_detail",
+  "levante_build_qa_map",
+  "levante_read_qa_map"
+];
+var DESKTOP_CONFIG = JSON.stringify({
+  mcpServers: {
+    levante: {
+      command: "levante-mcp"
+    }
+  }
+}, null, 2);
+function registerMcp(program2) {
+  program2.command("mcp").description("Show MCP server setup instructions for Claude").action(() => {
+    console.log("");
+    console.log(import_picocolors7.default.bold(import_picocolors7.default.cyan("  Levante MCP Server")));
+    console.log(import_picocolors7.default.dim("  " + "─".repeat(42)));
+    console.log("");
+    console.log(import_picocolors7.default.bold("  Claude Code — add to project:"));
+    console.log(import_picocolors7.default.cyan("    claude mcp add levante -- levante-mcp"));
+    console.log("");
+    console.log(import_picocolors7.default.bold("  Claude Code — add globally:"));
+    console.log(import_picocolors7.default.cyan("    claude mcp add levante -s user -- levante-mcp"));
+    console.log("");
+    console.log(import_picocolors7.default.bold("  Claude Desktop / other clients"));
+    console.log(import_picocolors7.default.dim("  ~/.config/claude/claude_desktop_config.json"));
+    console.log("");
+    const configLines = DESKTOP_CONFIG.split(`
+`);
+    for (const line of configLines) {
+      console.log(import_picocolors7.default.cyan("    " + line));
+    }
+    console.log("");
+    console.log(import_picocolors7.default.bold("  Available tools:"));
+    for (const tool of TOOLS) {
+      console.log(import_picocolors7.default.dim("    · ") + tool);
+    }
+    console.log("");
+  });
+}
+
 // src/cli.ts
 var require2 = createRequire2(import.meta.url);
 var { version: version2 } = require2("../package.json");
@@ -75759,6 +76062,7 @@ registerQa(program2);
 registerRun(program2);
 registerAuth(program2);
 registerJira(program2);
+registerMcp(program2);
 var userArgs = process.argv.slice(2);
 var commandNames = program2.commands.map((c) => c.name());
 var hasCommand = userArgs.some((a) => commandNames.includes(a));

package/package.json

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