zefiro 0.3.4 → 0.3.6

package/README.md

@@ -6,56 +6,63 @@ AI-powered codebase scanner and QA map generator. Scans your project's AST, iden
 
 ```bash
 npm install -g zefiro
+# or
+bun add -g zefiro
 ```
 
-### 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 — copies agents, writes QAI_* env vars to .env
 zefiro init
 
-# Scan → Analyze → Push
+# 2. Scan → Analyze → Push
 zefiro scan
 zefiro analyze
 zefiro push
 ```
 
-## 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
-```
+`zefiro init` writes the `QAI_*` variables to your `.env`. You can also set them manually.
 
-### Commands
+| Variable | Description |
+|----------|-------------|
+| `QAI_INPUT_SOURCE` | Issue tracker: `none` \| `jira` \| `linear` |
+| `QAI_OUTPUT_TARGET` | QA format: `markdown` \| `zephyr` \| `both` |
+| `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 |
+| `OPENAI_API_KEY` | OpenAI API key (for `analyze` with OpenAI) |
+| `ANTHROPIC_API_KEY` | Anthropic API key (for `analyze` with Anthropic) |
 
-#### `zefiro init`
+---
 
-Initialize zefiro in your project. Creates `.qai/zefiro/` with config and agent templates.
+## Commands
+
+### `zefiro init`
+
+Initialize zefiro in your project. Copies agent templates to `.qai/zefiro/agents/` and writes `QAI_*` variables to `.env`.
 
 ```bash
 zefiro init
-zefiro init --non-interactive
+zefiro init --non-interactive   # skip prompts, use defaults
 ```
 
-Interactive setup prompts for issue tracker, output format, LLM provider, and base URL.
+On re-run (`.qai/zefiro/agents/` already exists), preserves your existing setup and only updates agents and workflow guide.
+
+**After init:**
+1. Generate `.qai/zefiro/context.md` using the `init-agent` prompt in your AI tool, or via MCP (`zefiro_scan_codebase`)
+2. Review the generated context
+3. Run `zefiro scan`
+
+---
 
-#### `zefiro scan`
+### `zefiro scan`
 
-Scan your codebase AST to extract routes, components, hooks, imports, and dependencies.
+Scan your codebase AST — extracts routes, components, hooks, imports, and dependencies.
 
 ```bash
 zefiro scan
@@ -70,17 +77,19 @@ zefiro scan --no-cache
 | `--scan-dir <dir>` | Directory to scan (overrides config) |
 | `--no-cache` | Disable file-level MD5 caching |
 
-#### `zefiro analyze [input]`
+---
 
-Run two-stage AI analysis to generate a QA map from the AST scan.
+### `zefiro analyze [input]`
 
-**Stage 1:** Feature analysis — identifies features, workflows, and components.
-**Stage 2:** Scenario planning — generates test scenarios for each workflow.
+Two-stage AI analysis that generates a QA map from the AST scan.
+
+**Stage 1:** Feature analysis — identifies features, workflows, and components (runs in parallel).
+**Stage 2:** Scenario planning — generates test scenarios for each workflow (runs in parallel).
 
 ```bash
 zefiro analyze
 zefiro analyze custom-scan.json
-zefiro analyze --skip-scenarios
+zefiro analyze --skip-scenarios          # features and workflows only
 zefiro analyze --output custom-qa-map.json
 ```
 
@@ -88,11 +97,15 @@ zefiro analyze --output custom-qa-map.json
 |--------|-------------|
 | `[input]` | AST scan file (default: `.qai/zefiro/ast-scan.json`) |
 | `--output <file>` | QA map output (default: `.qai/zefiro/qa-map.json`) |
-| `--skip-scenarios` | Only run feature analysis, skip scenario generation |
+| `--skip-scenarios` | Skip scenario generation |
+
+**Incremental:** if the AST is unchanged since the last run, analysis is skipped. If the AST changed, only affected features are re-analyzed.
 
-#### `zefiro push [input]`
+---
 
-Push the generated QA map to a remote API.
+### `zefiro push [input]`
+
+Push the generated QA map to QA Intelligence (or a custom endpoint).
 
 ```bash
 zefiro push
@@ -103,34 +116,108 @@ zefiro push --commit-sha abc1234
 | Option | Description |
 |--------|-------------|
 | `[input]` | QA map file (default: `.qai/zefiro/qa-map.json`) |
-| `--commit-sha <sha>` | Git commit SHA to associate with the push |
+| `--commit-sha <sha>` | Git commit SHA to associate with this version |
+
+Authenticates via `zefiro auth login` session first, falls back to `QAI_API_URL` + `QAI_API_KEY`.
+
+---
+
+### `zefiro auth`
+
+Manage authentication with QA Intelligence.
+
+```bash
+zefiro auth login    # open browser for OAuth sign-in
+zefiro auth logout   # revoke CLI token
+zefiro auth status   # show current auth status
+zefiro auth switch   # re-authenticate with a different org/project/app
+```
+
+---
+
+### `zefiro mcp`
+
+Print MCP server setup instructions.
+
+```bash
+zefiro mcp
+```
+
+**Claude Code:**
+```bash
+claude mcp add zefiro -- zefiro-mcp              # project-scoped
+claude mcp add zefiro -s user -- zefiro-mcp      # global
+```
+
+**Claude Desktop / other clients:**
+```json
+{
+  "mcpServers": {
+    "zefiro": { "command": "zefiro-mcp" }
+  }
+}
+```
+
+**Available MCP tools:**
+
+| Tool | Description |
+|------|-------------|
+| `zefiro_scan_codebase` | Scan project test infrastructure |
+| `zefiro_scan_ast` | Deep AST scan: routes, components, hooks |
+| `zefiro_scan_ast_detail` | Drill into a specific AST category |
+| `zefiro_build_qa_map` | Validate and write a QAMapV2Payload |
+| `zefiro_read_qa_map` | Read the existing QA map file |
 
-Requires `push.apiUrl` and `push.apiKey` in config or via environment variables.
+---
+
+## Global Options
+
+```
+-k, --key <KEY>        Issue key context (e.g. PROJ-101, LIN-42)
+--provider <provider>  LLM provider: openai | anthropic
+--model <model>        LLM model override
+--verbose              Verbose output
+-v, --version          Show version
+-h, --help             Show help
+```
+
+---
 
 ## Configuration
 
-Configuration lives in `.qai/zefiro/config.ts`:
+For most projects, the `.env` variables written by `zefiro init` are sufficient. For advanced setups (custom paths, per-agent model overrides, integrations), create `.qai/zefiro/config.ts`:
 
 ```typescript
-import { defineConfig } from 'zefiro/config';
+import { defineConfig } from 'zefiro';
 
 export default defineConfig({
-  inputSource: 'jira',           // 'none' | 'jira' | 'linear'
-  outputTarget: 'markdown',      // 'markdown' | 'zephyr' | 'both'
+  inputSource: 'jira',            // 'none' | 'jira' | 'linear'
+  outputTarget: 'markdown',       // 'markdown' | 'zephyr' | 'both'
+  baseUrl: 'https://qaligent.space',
+
+  scanner: {
+    scanDir: 'src',
+    include: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+    exclude: ['**/node_modules/**', '**/dist/**', '**/*.test.*'],
+    cacheDir: '.qai/zefiro/scan-cache',
+  },
 
   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
       'feature-analyzer-agent': 'claude-sonnet-4-20250514',
     },
   },
 
-  scanner: {
-    scanDir: 'src',
-    include: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
-    exclude: ['**/node_modules/**', '**/dist/**'],
-    cacheDir: '.qai/zefiro/scan-cache',
+  paths: {
+    tests: 'e2e/tests',
+    scenarios: 'e2e/scenarios',
+    qaOutput: 'qa',
+  },
+
+  integrations: {
+    zephyr: { titlePrefix: 'UI Automation' },
   },
 
   push: {
@@ -140,41 +227,64 @@ export default defineConfig({
 });
 ```
 
+> `QAI_*` env vars take precedence over `config.ts` values when both are set.
+
+---
+
 ## AI Agents
 
-Zefiro ships with 3 agents (customizable in `.qai/zefiro/agents/`):
+Zefiro ships with agents copied to `.qai/zefiro/agents/` on `init`. Edit them to tune AI behavior for your project.
 
 | Agent | Purpose |
 |-------|---------|
-| `feature-analyzer-agent` | Identifies features, workflows, and components from AST |
-| `scenario-planner-agent` | Generates test scenarios for each workflow |
-| `scanner-agent` | Interactive agent for manual QA map building (MCP) |
+| `1.feature-analyzer-agent` | Identifies features, workflows, and components from AST |
+| `2.scenario-planner-agent` | Generates test scenarios for each workflow |
+| `3.scanner-agent` | Interactive QA map building (used via MCP) |
+| `input-agent` | Enriches form component input definitions |
+| `workflow-agent` | Maps user workflows within features |
+
+Add `.qai/zefiro/context.md` to inject project-specific context into every agent call.
+
+---
 
 ## QA Map Output
 
-The generated QA map contains:
+The generated `.qai/zefiro/qa-map.json` contains:
 
 - **Features** — User-facing capabilities grouped by routes
-- **Workflows** — User journeys (navigation, CRUD, multi-step, configuration, search/filter)
-- **Components** — UI elements (forms, modals, navigation, display)
-- **Scenarios** — Test cases with categories (happy-path, validation, error, edge-case, permission)
+- **Workflows** — User journeys (navigation, CRUD, multi-step, search/filter, configuration)
+- **Components** — UI elements (forms, modals, navigation, data display)
+- **Scenarios** — Test cases per workflow (happy-path, validation, error, edge-case, permission)
 
-## Project Structure
+---
 
-After initialization, zefiro creates:
+## Project Structure
 
 ```
 your-project/
+  .env                         # QAI_* variables (written by zefiro init)
   .qai/zefiro/
-    config.ts          # Configuration
-    context.md         # Project context for AI agents
-    agents/            # Agent prompts (customizable)
-    workflow.md        # Workflow guide
-    ast-scan.json      # AST scan output
-    qa-map.json        # Generated QA map
-    scan-cache/        # File-level MD5 cache
+    config.ts                  # Advanced config (optional)
+    context.md                 # Project context for AI agents
+    agents/                    # Agent prompts (customizable)
+    workflow.md                # Workflow guide
+    ast-scan.json              # Latest AST scan output
+    qa-map.json                # Generated QA map
+    scan-cache/                # File-level MD5 cache
 ```
 
+---
+
+## Interactive TUI
+
+Running `zefiro` with no arguments launches an interactive terminal UI (requires TTY, ≥ 60×20).
+
+```bash
+zefiro
+```
+
+---
+
 ## License
 
 MIT