agentic-qe 3.14.7 → 3.15.0

package/README.md

@@ -1,56 +1,111 @@
-# Agentic Quality Engineering Fleet
+<img src="assets/readme/project-header.svg" width="100%" alt="Agentic QE. Better tests, clearer risk, evidence you can inspect. Generate, execute, challenge and learn." />
 
-<div align="center">
+# Agentic QE
 
-[![npm version](https://img.shields.io/npm/v/agentic-qe.svg)](https://www.npmjs.com/package/agentic-qe)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Monthly Downloads](https://img.shields.io/npm/dm/agentic-qe)](https://www.npmjs.com/package/agentic-qe)
-[![Total Downloads](https://img.shields.io/npm/dt/agentic-qe?label=total%20downloads)](https://www.npmjs.com/package/agentic-qe)
+**Quality engineering tools for your coding agent.** Generate tests, investigate coverage gaps, analyze flaky behavior and coordinate quality checks across the software lifecycle. Keep the findings close to the code and use them to make a better quality decision.
 
-[Release Notes](docs/releases/README.md) | [Changelog](CHANGELOG.md) | [Issues](https://github.com/proffesor-for-testing/agentic-qe/issues) | [Discussions](https://github.com/proffesor-for-testing/agentic-qe/discussions)
+[![npm version](https://img.shields.io/npm/v/agentic-qe?color=168c91)](https://www.npmjs.com/package/agentic-qe)
+[![License: MIT](https://img.shields.io/badge/license-MIT-168c91)](LICENSE)
 
-**AI-powered quality engineering agents that generate tests, find coverage gaps, detect flaky tests, and learn your codebase patterns — across 11 coding agent platforms.**
+[Start with one task](#start-with-one-task) · [Choose your client](#choose-your-client) · [Inspect the evidence](#inspect-the-evidence) · [Contribute](#contribute) · [Release notes](docs/releases/README.md)
 
-</div>
+## Put AQE to work
 
----
+| Your QE problem | What AQE helps you do | What to inspect |
+| --- | --- | --- |
+| A changed service needs meaningful tests | Generate unit, integration, property-based or BDD tests | Assertions, edge cases and executed test results |
+| Coverage is high but important behavior is missing | Analyze gaps and prioritize by risk | Uncovered branches and the rationale for priorities |
+| A flaky suite is eroding trust | Investigate failure patterns and suggest stabilization | Reproduction and results before and after a change |
+| A release needs a quality assessment | Coordinate coverage, security, contracts and resilience checks | Findings, tool output and unresolved risks |
+| Your team repeats the same investigation | Store and retrieve QE patterns | Pattern relevance and recorded outcomes |
 
-## What AQE Does For You
+Supports framework-specific output for tools including Jest, Vitest, Playwright, Cypress, pytest and JUnit. Review generated tests and run them in your environment; an agent's recommendation is an input to your team's decision.
 
-- **Generates comprehensive tests automatically** — unit, integration, property-based, and BDD scenarios for your codebase with framework-specific output (Jest, Vitest, Playwright, Cypress, pytest, JUnit, Go, Rust, Swift, Flutter, and more)
-- **Finds coverage gaps and prioritizes what to test** — risk-weighted analysis identifies the most impactful untested code paths
-- **Detects and fixes flaky tests** — ML-powered detection with root cause analysis and stabilization recommendations
-- **Learns your codebase patterns over time** — remembered patterns are reused across sessions and projects, improving with every interaction
-- **Coordinates 60 specialized QE agents** — from test generation to security scanning to chaos engineering, orchestrated by a central coordinator
-- **Reduces AI costs with intelligent routing** — automatically routes tasks to the right model tier (fast/cheap for simple tasks, powerful for complex ones)
-- **Works with your existing tools** — integrates with 11 coding agent platforms and your existing CI/CD pipeline
+## Start with one task
 
----
-
-## Quick Start
+Requires **Node.js ≥22.13.0** and **npm ≥10.0.0**. Use the coding agent/client you already have configured.
 
 ```bash
-# Install
 npm install -g agentic-qe
+cd your-project
+aqe init --auto
+aqe health
+```
+
+`aqe init --auto` analyzes your project and configures the default Claude Code surface, including MCP. Review the generated project files. For another client, select its setup flag below and use its MCP connection flow.
+
+In your coding agent, start with a narrow request:
+
+```text
+Generate tests for src/services/UserService.ts.
+Explain the risks and edge cases each test covers.
+Run the tests if execution is available, and report failures and anything you could not verify.
+```
+
+Then ask for a second view:
+
+```text
+Find coverage gaps in src/services/ and prioritize them by risk.
+Challenge weak assertions in the generated tests and explain what still needs human review.
+```
+
+The paths are examples; use a real file in your project. Success means tests you can inspect and execute, plus a clear account of what remains untested. A coverage target is a request, not a promised result.
+
+## Choose your client
+
+| Client | Project setup |
+| --- | --- |
+| Claude Code | `aqe init --auto` |
+| OpenAI Codex CLI | `aqe init --auto --with-codex` |
+| GitHub Copilot | `aqe init --auto --with-copilot` |
+| Cursor | `aqe init --auto --with-cursor` |
+| Cline | `aqe init --auto --with-cline` |
+| OpenCode | `aqe init --auto --with-opencode` |
+| AWS Kiro | `aqe init --auto --with-kiro` |
+| Kilo Code | `aqe init --auto --with-kilocode` |
+| Roo Code | `aqe init --auto --with-roocode` |
+| Windsurf | `aqe init --auto --with-windsurf` |
+| Continue.dev | `aqe init --auto --with-continuedev` |
+
+These are implemented setup paths, not a claim of identical behavior across clients. The default Claude Code files are also created unless you add `--no-claude` when targeting another client.
+
+```bash
+# Configure every supported client
+aqe init --auto --with-all-platforms
 
-# Initialize your project (auto-detects tech stack, configures MCP)
-cd your-project && aqe init --auto
+# Inspect or add client configuration later
+aqe platform list
+aqe platform setup cursor
+aqe platform verify cursor
 
-# That's it — MCP tools are available immediately in Claude Code
-# For other clients: aqe-mcp
+# Standalone MCP server entry point
+aqe-mcp
 ```
 
-After init, your coding agent can use AQE tools directly. For example in Claude Code:
+See the [Platform Setup Guide](docs/platform-setup-guide.md) for client-specific configuration.
+
+### Claude Code plugin: a scoped alternative
+
+Use the `agentic-qe-fleet` plugin when you want a smaller Claude Code surface with slash commands. The full `aqe init` path adds broader project configuration and persistent learning setup.
 
+In Claude Code:
+
+```text
+/plugin install agentic-qe-fleet --marketplace proffesor-for-testing/agentic-qe
 ```
-"Generate tests for src/services/UserService.ts with 90% coverage target"
-"Find coverage gaps in src/ and prioritize by risk"
-"Run security scan on the authentication module"
-"Analyze why tests in auth/ are flaky and suggest fixes"
+
+Or load it from a checkout:
+
+```bash
+git clone https://github.com/proffesor-for-testing/agentic-qe.git
+claude --plugin-dir ./agentic-qe/plugins/agentic-qe-fleet
 ```
 
-### Windows install
+Start with `/aqe-fleet-status`, `/aqe-generate src/services/Auth.ts` or `/aqe-analyze src/`. The plugin registers its own MCP server, pinned to the matching package version (`npx -y agentic-qe@<plugin version> mcp`). See the [plugin README](plugins/agentic-qe-fleet/README.md) for the bundled agents, commands and skills.
+
+<details>
+<summary>Windows and native dependency setup</summary>
+
 
 `agentic-qe` runs on Windows, but several of its performance-oriented native
 dependencies (`hnswlib-node` for HNSW search, `@ruvector/gnn` for graph
@@ -86,285 +141,54 @@ aqe health
 # (ProgressiveHnswBackend — see caveat above).
 ```
 
-Linux and macOS users: no extra setup required. The native binary compiles
-out of the box.
-
----
-
-## Claude Code Plugin (Alternative Install)
-
-If you only need a slim, scoped fleet inside Claude Code — without the full `aqe init` setup — install the **`agentic-qe-fleet`** plugin. It bundles 11 specialized QE agents, 9 slash commands, 9 skills, and auto-registers the MCP server.
-
-### Install from a local checkout
-
-```bash
-git clone https://github.com/proffesor-for-testing/agentic-qe.git
-claude --plugin-dir ./agentic-qe/plugins/agentic-qe-fleet
-```
-
-### Install from the marketplace
-
-In any Claude Code session:
-
-```
-/plugin marketplace add proffesor-for-testing/agentic-qe
-/plugin install agentic-qe-fleet
-```
-
-### What you get
-
-| Asset | Count | Notes |
-|---|---|---|
-| **Agents** (Task tool) | 11 | Model-routed: 6 on Opus (heavy reasoning), 5 on Sonnet (focused execution) |
-| **Slash commands** | 9 | `/aqe-analyze`, `/aqe-execute`, `/aqe-generate`, `/aqe-optimize`, `/aqe-chaos`, `/aqe-fleet-status`, `/aqe-report`, `/aqe-benchmark`, `/aqe-costs` |
-| **Skills** | 9 | All trust-tier 2 or 3 (validated/verified). Tier-1 untested skills excluded per policy. |
-| **MCP server** | 1 | Auto-registers via `npx -y agentic-qe@latest mcp` — no separate `claude mcp add` |
-
-**Bundled agents:** `qe-test-architect`, `qe-coverage-specialist`, `qe-flaky-hunter`, `qe-chaos-engineer`, `qe-fleet-commander`, `qe-quality-gate`, `qe-security-scanner`, `qe-performance-tester`, `qe-regression-analyzer`, `qe-tdd-specialist`, `qe-requirements-validator`.
-
-**Bundled skills:** `qe-test-generation`, `qe-coverage-analysis`, `qe-test-execution`, `qe-chaos-resilience`, `qe-quality-assessment`, `chaos-engineering-resilience`, `mutation-testing`, `risk-based-testing`, `tdd-london-chicago`.
-
-### Use it
-
-After loading the plugin, the slash commands and agents are available immediately:
-
-```
-/aqe-fleet-status                 # health and metrics
-/aqe-generate src/services/Auth.ts
-/aqe-analyze src/                 # coverage gap analysis
-```
-
-Or invoke an agent through the Task tool:
-
-```
-"Use qe-test-architect to generate tests for src/services/PaymentService.ts"
-"Use qe-flaky-hunter to find and stabilize flaky tests in tests/integration/"
-"Use qe-chaos-engineer to inject network partitions into the order workflow"
-```
-
-### Plugin vs `aqe init` — which to use?
-
-| | **Plugin** | **`aqe init`** |
-|---|---|---|
-| Setup | One slash command | Full project setup |
-| Scope | 11 agents, 9 skills | 60 agents, 86 skills |
-| Persistent learning DB | No (uses MCP server's) | Yes (`.agentic-qe/memory.db`) |
-| Cross-platform support | Claude Code only | 11 platforms (Cursor, Copilot, Cline, etc.) |
-| Use when | Quick start, single Claude Code project | Production team setup, multi-platform, full fleet |
-
-You can run both — the plugin's MCP server uses the same `agentic-qe` package, so installing both gives you the full fleet via `aqe init` and the slash-command shortcuts via the plugin.
-
----
-
-## Platform Support
-
-AQE works with **11 coding agent platforms** through a single MCP server:
-
-| Platform | Setup |
-|----------|-------|
-| **Claude Code** | `aqe init --auto` (built-in) |
-| **GitHub Copilot** | `aqe init --auto --with-copilot` |
-| **Cursor** | `aqe init --auto --with-cursor` |
-| **Cline** | `aqe init --auto --with-cline` |
-| **OpenCode** | `aqe init --auto --with-opencode` |
-| **AWS Kiro** | `aqe init --auto --with-kiro` |
-| **Kilo Code** | `aqe init --auto --with-kilocode` |
-| **Roo Code** | `aqe init --auto --with-roocode` |
-| **OpenAI Codex CLI** | `aqe init --auto --with-codex` |
-| **Windsurf** | `aqe init --auto --with-windsurf` |
-| **Continue.dev** | `aqe init --auto --with-continuedev` |
-
-```bash
-# Set up all platforms at once
-aqe init --auto --with-all-platforms
-
-# Or add a platform later
-aqe platform setup cursor
-aqe platform list       # show install status
-aqe platform verify cursor  # validate config
-```
-
-For detailed per-platform instructions, see [Platform Setup Guide](docs/platform-setup-guide.md).
-
----
-
-## Usage Examples
-
-### Generate Tests
-
-```bash
-claude "Use qe-test-architect to create tests for PaymentService with 95% coverage target"
-```
-
-Output:
-```
-Generated 48 tests across 4 files
-- unit/PaymentService.test.ts (32 unit tests)
-- property/PaymentValidation.property.test.ts (8 property tests)
-- integration/PaymentFlow.integration.test.ts (8 integration tests)
-Coverage: 96.2%
-Pattern reuse: 78% from learned patterns
-```
-
-### Full Quality Pipeline
-
-```bash
-claude "Use qe-queen-coordinator to run full quality assessment:
-1. Generate tests for src/services/*.ts
-2. Analyze coverage gaps with risk scoring
-3. Run security scan
-4. Validate quality gate at 90% threshold
-5. Provide deployment recommendation"
-```
-
-The Queen Coordinator spawns domain-specific agents, runs them in parallel, and synthesizes a final recommendation.
-
-### TDD Workflow
-
-```bash
-claude "Use qe-tdd-specialist to implement UserAuthentication with full RED-GREEN-REFACTOR cycle"
-```
-
-Coordinates 5 subagents: write failing tests → implement minimal code → refactor → code review → security review.
-
-### Security Audit
-
-```bash
-claude "Coordinate security audit:
-- SAST/DAST scanning with qe-security-scanner
-- Dependency vulnerability scanning with qe-dependency-mapper
-- API security with qe-contract-validator
-- Chaos resilience testing with qe-chaos-engineer"
-```
-
----
-
-## 60 QE Agents
-
-The fleet is organized into **13 domains**, coordinated by the **qe-queen-coordinator**:
-
-| Domain | Agents | What They Do |
-|--------|--------|-------------|
-| **Test Generation** | test-architect, tdd-specialist, mutation-tester, property-tester | Generate tests, TDD workflows, validate test effectiveness |
-| **Test Execution** | parallel-executor, retry-handler, integration-tester | Run tests in parallel, handle retries, integration testing |
-| **Coverage Analysis** | coverage-specialist, gap-detector | Find untested code, prioritize by risk |
-| **Quality Assessment** | quality-gate, risk-assessor, deployment-advisor, devils-advocate | Go/no-go decisions, risk scoring, adversarial review |
-| **Defect Intelligence** | defect-predictor, root-cause-analyzer, flaky-hunter, regression-analyzer | Predict bugs, find root causes, fix flaky tests |
-| **Requirements** | requirements-validator, bdd-generator | Validate testability, generate BDD scenarios |
-| **Code Intelligence** | code-intelligence, kg-builder, dependency-mapper, impact-analyzer | Knowledge graphs, semantic search, change impact |
-| **Security** | security-scanner, security-auditor, pentest-validator | SAST/DAST, compliance audits, exploit validation |
-| **Contracts** | contract-validator, graphql-tester | API contracts, GraphQL schema testing |
-| **Visual & A11y** | visual-tester, accessibility-auditor, responsive-tester | Visual regression, WCAG compliance, viewport testing |
-| **Chaos & Performance** | chaos-engineer, load-tester, performance-tester | Fault injection, load testing, performance validation |
-| **Learning** | learning-coordinator, pattern-learner, transfer-specialist, metrics-optimizer | Cross-project learning, pattern discovery |
-| **Enterprise** | soap-tester, sap-rfc-tester, sap-idoc-tester, sod-analyzer, odata-contract-tester, middleware-validator, message-broker-tester | SAP, SOAP, ESB, OData, JMS/AMQP/Kafka |
-
-Plus **7 TDD subagents** (red, green, refactor, code/integration/performance/security reviewers) and the **fleet-commander** for large-scale orchestration.
-
----
-
-## 75 QE Skills
-
-Agents automatically apply relevant skills from the skill library. Skills are rated by **trust tier**:
-
-| Tier | Count | Meaning |
-|------|-------|---------|
-| **Tier 3 — Verified** | 49 | Full evaluation test suite, production-ready |
-| **Tier 2 — Validated** | 7 | Has executable validator |
-| **Tier 1 — Structured** | 5 | Has JSON output schema |
-| **Tier 0 — Advisory** | 5 | Guidance only |
-
-<details>
-<summary><b>View all 76 skills</b></summary>
-
-**Core Testing (12):** agentic-quality-engineering, holistic-testing-pact, context-driven-testing, tdd-london-chicago, xp-practices, risk-based-testing, test-automation-strategy, refactoring-patterns, shift-left-testing, shift-right-testing, regression-testing, verification-quality
-
-**Specialized Testing (13):** accessibility-testing, mobile-testing, database-testing, contract-testing, chaos-engineering-resilience, visual-testing-advanced, security-visual-testing, compliance-testing, compatibility-testing, localization-testing, mutation-testing, performance-testing, security-testing
-
-**Browser Automation (1):** qe-browser (Vibium engine — assert, batch, visual-diff, prompt-injection scanning, semantic intents; see [ADR-091](docs/implementation/adrs/ADR-091-qe-browser-skill-vibium-engine.md))
-
-**Domain Skills (11):** qe-test-generation, qe-test-execution, qe-coverage-analysis, qe-quality-assessment, qe-defect-intelligence, qe-requirements-validation, qe-code-intelligence, qe-visual-accessibility, qe-chaos-resilience, qe-learning-optimization, qe-iterative-loop
-
-**Strategic (9):** six-thinking-hats, brutal-honesty-review, sherlock-review, qe-court (adversarial review court — SHIP/REMAND/BLOCK verdict that must survive escalating cross-vendor reviewers; see [ADR-124](docs/implementation/adrs/ADR-124-qe-court-adversarial-verdict-service.md)), cicd-pipeline-qe-orchestrator, bug-reporting-excellence, consultancy-practices, quality-metrics, pair-programming
-
-**Testing Techniques (9):** exploratory-testing-advanced, test-design-techniques, test-data-management, test-environment-management, test-reporting-analytics, testability-scoring, technical-writing, code-review-quality, api-testing-patterns
-
-**On-Demand Hooks (5):** strict-tdd, no-skip, coverage-guard, freeze-tests, security-watch
-
-**Runbooks & Analysis (5):** test-failure-investigator, coverage-drop-investigator, e2e-flow-verifier, test-metrics-dashboard, skill-stats
-
-**n8n Workflow Testing (5):** n8n-workflow-testing-fundamentals, n8n-expression-testing, n8n-security-testing, n8n-trigger-testing-strategies, n8n-integration-testing-patterns
-
-**QCSD Swarms (5):** qcsd-ideation-swarm, qcsd-refinement-swarm, qcsd-development-swarm, qcsd-cicd-swarm, qcsd-production-swarm
-
-**Accessibility (2):** a11y-ally, accessibility-testing
-
-**Enterprise Integration (5):** enterprise-integration-testing, middleware-testing-patterns, observability-testing-patterns, wms-testing-patterns, pentest-validation
-
-**Validation (1):** validation-pipeline
+On Linux and macOS, verify the active backend with `aqe health` as well; native module availability depends on your environment.
 
 </details>
 
----
-
-## How It Works
-
-### Agent Coordination
+## How a quality task flows
 
-The **Queen Coordinator** orchestrates agents across all 13 domains. When you ask for a quality assessment, the Queen decomposes the task, spawns the right agents, coordinates their work in parallel, and synthesizes results. Agents communicate through shared memory namespaces and use consensus protocols for critical quality decisions.
+<img src="assets/readme/quality-loop.svg" width="100%" alt="Conceptual quality workflow: frame risk, generate and execute tests, challenge findings through coverage, mutation, security and review, then make a human quality decision and record the outcome." />
 
-### Pattern Learning
+The `qe-queen-coordinator` decomposes a quality assessment into domain tasks and combines findings. Domains cover test generation and execution, coverage, quality assessment, defect intelligence, requirements, code intelligence, security, contracts, visual accessibility, resilience, learning and enterprise integration.
 
-AQE learns from every interaction. Successful test patterns, coverage strategies, and defect indicators are stored and indexed for fast retrieval. When generating tests for a new service, AQE searches for similar patterns from past sessions — even across different projects. Patterns improve over time through experience replay and dream cycles (background consolidation).
+Patterns can be stored and retrieved across sessions. AQE provides outcome feedback and consolidation mechanisms; retrieval alone does not prove that future tests are better. Model routing offers cost-aware task selection, while actual costs and quality depend on your provider and workload.
 
-```bash
-aqe learning stats      # view learning statistics
-aqe learning dream      # trigger pattern consolidation
-aqe brain export        # export learned patterns for sharing
-```
+Anti-sycophancy checks examine weak or tautological tests. Adversarial review adds a way to challenge a verdict. See [quality gate features](docs/loki-mode-features.md) and [QE Court design](docs/implementation/adrs/ADR-124-qe-court-adversarial-verdict-service.md).
 
-### Intelligent Model Routing
+## Inspect the evidence
 
-**TinyDancer** routes tasks to the right model tier to minimize cost without sacrificing quality:
+| Evidence | What it supports | Scope and limits |
+| --- | --- | --- |
+| [Shipped agent definitions](assets/agents/v3/) | Inspect each agent's intended role and instructions | Source definitions establish inventory, not demonstrated effectiveness |
+| [Packaged skills](assets/skills/) and [validation guide](docs/guides/skill-validation.md) | Inspect workflows, validators and evaluations | Trust tiers describe validation artifacts; they do not guarantee production outcomes |
+| [Interaction benchmark run records](benchmarks/interaction/results/README.md) | Compare QE-guided and bare interactions against ground truth | June 11, 2026: two scenarios; no demonstrated arm benefit, statistically underpowered |
+| [MCP tests](tests/unit/mcp/) and [integration tests](tests/integration/mcp/) | Inspect protocol and handler checks | Repository tests are not a record of a fresh passing run |
+| [Changelog](CHANGELOG.md) and [release notes](docs/releases/README.md) | Trace changes and fixes | Read the entry matching your installed version |
 
-| Task Complexity | Model | Examples |
-|----------------|-------|---------|
-| Simple (0-20) | Haiku | Type additions, simple refactors |
-| Moderate (20-70) | Sonnet | Bug fixes, test generation |
-| Critical (70+) | Opus | Architecture, security, complex reasoning |
+**Inventory verified October 9, 2026 at [`829d030`](https://github.com/proffesor-for-testing/agentic-qe/tree/829d03060d56ee82e6fa294b2be8f6c5fc9f2766):** 53 top-level `qe-*.md` agent definitions + 7 QE subagents; 86 packaged `SKILL.md` entry points; 13 domain directories. The scoped plugin separately contains 11 agents, 9 skills and 9 command files. Client setup flags above cover 11 clients. These counts exclude platform infrastructure agents and supporting Markdown files.
 
-### Quality Gates
-
-Anti-sycophancy scoring catches hollow tests. Tautological assertions (`expect(true).toBe(true)`) are rejected. Edge cases from historical patterns are injected into test generation. See [Loki-mode features](docs/loki-mode-features.md).
-
----
-
-## CLI Reference
+## Commands for everyday work
 
 ```bash
-aqe init [--auto]              # Initialize project
-aqe agent list                 # List available agents
-aqe fleet status               # Fleet health and coordination
-aqe learning stats             # Learning statistics
-aqe learning dream             # Trigger dream cycle
-aqe brain export/import        # Portable intelligence
-aqe platform list/setup/verify # Manage coding agent platforms
-aqe health                     # System health check
-
-# Code intelligence
-aqe code index src/                  # Index codebase into knowledge graph
-aqe code index src/ --incremental    # Incremental index (changed files only)
-aqe code index . --git-since HEAD~5  # Index files changed in last 5 commits
-aqe code search "authentication"     # Semantic code search
-aqe code impact src/                 # Change impact analysis
-aqe code deps src/                   # Dependency mapping
-aqe code complexity src/             # Complexity metrics and hotspots
-aqe code c4 .                        # C4 architecture diagrams (Mermaid) + confidence
+aqe agent list                  # Agent inventory
+aqe fleet status                # Fleet status
+aqe health                      # Runtime health
+aqe learning stats              # Learning statistics
+aqe learning dream              # Pattern consolidation
+aqe brain export                # Export learned patterns
+
+aqe code index src/             # Build code intelligence index
+aqe code index src/ --incremental
+aqe code index . --git-since HEAD~5
+aqe code search "authentication"
+aqe code impact src/
+aqe code deps src/
+aqe code complexity src/
+aqe code c4 .                   # C4 diagrams with confidence
 ```
 
----
+## LLM providers and local models
 
-## LLM Providers
 
 AQE Fleet's LLM-enhanced analysis (ADR-043, ADR-051) routes through a
 HybridRouter that picks providers based on routing rules and your env
@@ -375,8 +199,8 @@ config. Set one or more API keys and Fleet auto-detects what's available:
 | **Claude** | `ANTHROPIC_API_KEY` | Cloud | Default in routing rules |
 | **OpenAI** | `OPENAI_API_KEY` | Cloud | Wide model coverage |
 | **Gemini** | `GOOGLE_AI_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Cloud | Cheap; free tier |
-| **OpenRouter** | `OPENROUTER_API_KEY` | Cloud | 300+ models behind one key |
-| **Ollama** | (local) | Local | Privacy, offline |
+| **OpenRouter** | `OPENROUTER_API_KEY` | Cloud | Multiple models behind one key |
+| **Ollama** | (local) | Local | Local inference |
 | **Azure OpenAI** | `AZURE_OPENAI_API_KEY` | Cloud | Enterprise |
 | **Bedrock** | `AWS_ACCESS_KEY_ID` | Cloud | AWS-native |
 
@@ -421,28 +245,27 @@ export AQE_FREE_TIER=1            # opt in (default model: qwen3-coder:30b)
 `qwen3-coder:30b` needs ~18 GB of RAM. `qwen3:8b` fits smaller machines but
 measured below the QE test-generation quality floor (ADR-111).
 
-Most routine test generation is then handled locally at **$0**. See the
+Local inference avoids per-call cloud charges; hardware costs and fallback cloud calls still apply. See the
 [Free-Tier Local Models guide](docs/guides/free-tier-local-models.md) for
 provider options and configuration.
 
----
 
 ## Documentation
 
-| Guide | Description |
-|-------|-------------|
-| [Platform Setup](docs/platform-setup-guide.md) | Per-platform configuration instructions |
-| [Free-Tier Local Models](docs/guides/free-tier-local-models.md) | Cheap-first test generation on local/free models (opt-in) |
-| [Skill Validation](docs/guides/skill-validation.md) | Trust tiers and evaluation system |
-| [Learning System](docs/guides/reasoningbank-learning-system.md) | ReasoningBank pattern learning |
-| [Code Intelligence](docs/guides/fleet-code-intelligence-integration.md) | Knowledge graph and semantic search |
-| [Loki-mode Features](docs/loki-mode-features.md) | Anti-sycophancy and quality gates |
-| [Release Notes](docs/releases/README.md) | Version history and changelogs |
-| [Architecture Glossary](docs/v3-technical-architecture-glossary.md) | Technical terms and concepts |
+| Guide | Use it for |
+| --- | --- |
+| [Platform setup](docs/platform-setup-guide.md) | Client configuration |
+| [Free-tier local models](docs/guides/free-tier-local-models.md) | Opt-in local/free generation and fallback |
+| [Skill validation](docs/guides/skill-validation.md) | Trust tiers and evaluations |
+| [Learning system](docs/guides/reasoningbank-learning-system.md) | Pattern storage and feedback |
+| [Code intelligence](docs/guides/fleet-code-intelligence-integration.md) | Indexing, graphs and search |
+| [Architecture glossary](docs/v3-technical-architecture-glossary.md) | Technical terminology |
+
+## Contribute
 
----
+Bring a small problem we can reproduce. Useful starting points include a failing test, a client setup issue, a better example, or a validator that challenges an unsupported claim.
 
-## Development
+Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) before changing code. For bug reports, include your AQE version, Node version, operating system, client, expected behavior and a minimal reproduction. Use [Issues](https://github.com/proffesor-for-testing/agentic-qe/issues) for reproducible bugs, [Issues](https://github.com/proffesor-for-testing/agentic-qe/issues) for questions and use cases, and the [security policy](SECURITY.md) for security reports.
 
 ```bash
 git clone https://github.com/proffesor-for-testing/agentic-qe.git
@@ -452,34 +275,13 @@ npm run build
 npm test -- --run
 ```
 
-| Script | Description |
-|--------|-------------|
-| `npm run build` | Compile TypeScript + CLI + MCP bundles |
-| `npm test -- --run` | Run all tests |
-| `npm run cli` | Run CLI in dev mode |
-| `npm run mcp` | Start MCP server |
+For a focused change, start with the relevant checks documented in [AGENTS.md](AGENTS.md), such as `npm run typecheck`, `npm run lint` and the relevant test suite. Keep production learning databases intact and test data changes against copies.
 
----
+## License and support
 
-## Contributing
+**MIT** — see [LICENSE](LICENSE). Free to use, fork, build and contribute under its terms.
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
-
----
-
-## Support
-
-- **Documentation**: [docs/](docs/)
-- **Issues**: [GitHub Issues](https://github.com/proffesor-for-testing/agentic-qe/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/proffesor-for-testing/agentic-qe/discussions)
-
----
-
-## License
-
-MIT — see [LICENSE](LICENSE).
-
----
+[Support the project](FUNDING.md) · [Project documentation](docs/) · [View all contributors](CONTRIBUTORS.md)
 
 ## Contributors
 
@@ -490,37 +292,12 @@ MIT — see [LICENSE](LICENSE).
 | <img src="https://github.com/JLMA-Agentic-Ai.png" width="60" style="border-radius:50%"/><br/>**[@JLMA-Agentic-Ai](https://github.com/JLMA-Agentic-Ai)**<br/>Package Exports | <img src="https://github.com/amonkarsidhant.png" width="60" style="border-radius:50%"/><br/>**[@amonkarsidhant](https://github.com/amonkarsidhant)**<br/>MCP-first Setup | <img src="https://github.com/gurdasnijor.png" width="60" style="border-radius:50%"/><br/>**[@gurdasnijor](https://github.com/gurdasnijor)**<br/>Smithery Integration |  |
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-[View all contributors](CONTRIBUTORS.md) | [Become a contributor](CONTRIBUTING.md)
-
----
-
-## Support the Project
-
-If you find AQE valuable, consider supporting its development:
-
-| | Monthly | Annual (Save $10) |
-|---|:---:|:---:|
-| **Price** | $5/month | $50/year |
-| **Subscribe** | [**Monthly**](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-88G03706DU8150205NEYZZAY) | [**Annual**](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-39189175UE6623540NEYZ2CI) |
-
-[View sponsorship details](FUNDING.md)
-
----
-
 ## Acknowledgments
 
-- **[Claude Flow](https://github.com/ruvnet/claude-flow)** by [@ruvnet](https://github.com/ruvnet) — Multi-agent orchestration and MCP integration
-- **[Agentic Flow](https://github.com/ruvnet/agentic-flow)** by [@ruvnet](https://github.com/ruvnet) — Agent patterns and learning systems
-- Built with TypeScript, Node.js, and better-sqlite3
-- Compatible with Jest, Cypress, Playwright, Vitest, Mocha, pytest, JUnit, and more
-
----
-
-<div align="center">
-
-**Made with care by the Agentic QE Team**
+Agentic QE was developed with help from **[Ruflo](https://github.com/ruvnet/ruflo), formerly Claude Flow**, by **[rUv](https://github.com/ruvnet)**, for coordination during development. **[RuVector](https://github.com/ruvnet/ruvector) provides the vector and RVF database foundation** through the `@ruvector/*` packages; AQE also uses `better-sqlite3` for SQLite persistence. Ruflo is development tooling, not a required AQE runtime dependency.
 
-[Star us on GitHub](https://github.com/proffesor-for-testing/agentic-qe) | [Sponsor](FUNDING.md) | [Contributors](CONTRIBUTORS.md)
+<a href="https://github.com/ruvnet/ruflo"><img src="assets/readme/credit-ruflo.svg" width="600" alt="Ruflo, formerly Claude Flow. Coordination support during Agentic QE development. Open the upstream repository." /></a>
 
-</div>
+<a href="https://github.com/ruvnet/ruvector"><img src="assets/readme/credit-ruvector.svg" width="600" alt="RuVector. Vector search and RVF pattern storage, alongside SQLite persistence. Open the upstream repository." /></a>
 
+Thanks also to [Agentic Flow](https://github.com/ruvnet/agentic-flow) for agent patterns and learning systems, and to the maintainers and contributors across the testing tools this project builds on. The cards are original AQE artwork and link to the upstream projects.

package/assets/readme/credit-ruflo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="230" viewBox="0 0 600 230" role="img" aria-labelledby="title desc"><title id="title">Ruflo — Formerly Claude Flow. Coordination during development.</title><desc id="desc">Original Agentic QE visual in dark teal and cyan. Ruflo — Formerly Claude Flow. Coordination during development.</desc><defs><linearGradient id="bg" x2="1" y2="1"><stop stop-color="#071a20"/><stop offset="1" stop-color="#10343b"/></linearGradient><pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse"><path d="M40 0H0V40" fill="none" stroke="#61cbc9" stroke-opacity=".07"/></pattern></defs><rect width="600" height="230" rx="22" fill="url(#bg)"/><rect width="600" height="230" rx="22" fill="url(#grid)"/><g font-family="Arial, Helvetica, sans-serif" fill="#e6f4f4"><text x="28" y="38" font-size="13" fill="#78ddd3" letter-spacing="2">DEVELOPMENT SUPPORT</text><text x="28" y="88" font-size="36" fill="#e6f4f4" font-weight="700">Ruflo</text><text x="28" y="131" font-size="19" fill="#e6f4f4" >Formerly Claude Flow</text><text x="28" y="167" font-size="17" fill="#bed8dc" >Coordination during development</text><text x="28" y="205" font-size="15" fill="#78ddd3" >Explore the upstream project →</text><g transform="translate(449,83) scale(0.53)"><path d="M0 0 65 -37 130 0V100L65 138 0 100Z" fill="#0d343b" stroke="#55dfcf" stroke-width="3"/><path d="M33 48 57 72 101 22" fill="none" stroke="#6ee7d5" stroke-width="9" stroke-linecap="round" stroke-linejoin="round"/><path d="M-68 25H-18M-52 58H-18M-38 91H-18M150 58H218" stroke="#73d6e8" stroke-width="3"/><circle cx="224" cy="58" r="7" fill="#73d6e8"/></g></g></svg>

package/assets/readme/credit-ruvector.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="230" viewBox="0 0 600 230" role="img" aria-labelledby="title desc"><title id="title">RuVector — Vector search and RVF patterns. Alongside SQLite persistence.</title><desc id="desc">Original Agentic QE visual in dark teal and cyan. RuVector — Vector search and RVF patterns. Alongside SQLite persistence.</desc><defs><linearGradient id="bg" x2="1" y2="1"><stop stop-color="#071a20"/><stop offset="1" stop-color="#10343b"/></linearGradient><pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse"><path d="M40 0H0V40" fill="none" stroke="#61cbc9" stroke-opacity=".07"/></pattern></defs><rect width="600" height="230" rx="22" fill="url(#bg)"/><rect width="600" height="230" rx="22" fill="url(#grid)"/><g font-family="Arial, Helvetica, sans-serif" fill="#e6f4f4"><text x="28" y="38" font-size="13" fill="#78ddd3" letter-spacing="2">MEMORY + DATA FOUNDATION</text><text x="28" y="88" font-size="36" fill="#e6f4f4" font-weight="700">RuVector</text><text x="28" y="131" font-size="19" fill="#e6f4f4" >Vector search and RVF patterns</text><text x="28" y="167" font-size="17" fill="#bed8dc" >Alongside SQLite persistence</text><text x="28" y="205" font-size="15" fill="#78ddd3" >Explore the upstream project →</text><g transform="translate(449,83) scale(0.53)"><path d="M0 0 65 -37 130 0V100L65 138 0 100Z" fill="#0d343b" stroke="#55dfcf" stroke-width="3"/><path d="M33 48 57 72 101 22" fill="none" stroke="#6ee7d5" stroke-width="9" stroke-linecap="round" stroke-linejoin="round"/><path d="M-68 25H-18M-52 58H-18M-38 91H-18M150 58H218" stroke="#73d6e8" stroke-width="3"/><circle cx="224" cy="58" r="7" fill="#73d6e8"/></g></g></svg>

package/assets/readme/project-header.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="380" viewBox="0 0 1200 380" role="img" aria-labelledby="title desc"><title id="title">Agentic QE — Better tests. Clearer risk. Evidence you can inspect.</title><desc id="desc">Original Agentic QE visual in dark teal and cyan. Agentic QE — Better tests. Clearer risk. Evidence you can inspect.</desc><defs><linearGradient id="bg" x2="1" y2="1"><stop stop-color="#071a20"/><stop offset="1" stop-color="#10343b"/></linearGradient><pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse"><path d="M40 0H0V40" fill="none" stroke="#61cbc9" stroke-opacity=".07"/></pattern></defs><rect width="1200" height="380" rx="22" fill="url(#bg)"/><rect width="1200" height="380" rx="22" fill="url(#grid)"/><g font-family="Arial, Helvetica, sans-serif" fill="#e6f4f4"><text x="50" y="52" font-size="18" fill="#78ddd3" letter-spacing="3">AGENTIC QE / OPEN SOURCE QUALITY ENGINEERING</text><text x="50" y="125" font-size="54" fill="#e6f4f4" font-weight="700">Better tests. Clearer risk.</text><text x="50" y="190" font-size="54" fill="#e6f4f4" font-weight="700">Evidence you can inspect.</text><text x="50" y="254" font-size="24" fill="#bed8dc" >Generate · Execute · Challenge · Learn</text><text x="50" y="331" font-size="16" fill="#78ddd3" letter-spacing="2">YOUR CODEBASE  →  YOUR TOOLS  →  YOUR QUALITY DECISION</text><g transform="translate(930,132) scale(1)"><path d="M0 0 65 -37 130 0V100L65 138 0 100Z" fill="#0d343b" stroke="#55dfcf" stroke-width="3"/><path d="M33 48 57 72 101 22" fill="none" stroke="#6ee7d5" stroke-width="9" stroke-linecap="round" stroke-linejoin="round"/><path d="M-68 25H-18M-52 58H-18M-38 91H-18M150 58H218" stroke="#73d6e8" stroke-width="3"/><circle cx="224" cy="58" r="7" fill="#73d6e8"/></g></g></svg>

package/assets/readme/quality-loop.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="510" viewBox="0 0 1200 510" role="img" aria-labelledby="title desc"><title id="title">Frame risk, do the work, challenge results, decide and learn. Conceptual workflow with human review.</title><desc id="desc">Original Agentic QE visual in dark teal and cyan. Frame risk, do the work, challenge results, decide and learn. Conceptual workflow with human review.</desc><defs><linearGradient id="bg" x2="1" y2="1"><stop stop-color="#071a20"/><stop offset="1" stop-color="#10343b"/></linearGradient><pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse"><path d="M40 0H0V40" fill="none" stroke="#61cbc9" stroke-opacity=".07"/></pattern></defs><rect width="1200" height="510" rx="22" fill="url(#bg)"/><rect width="1200" height="510" rx="22" fill="url(#grid)"/><g font-family="Arial, Helvetica, sans-serif" fill="#e6f4f4"><text x="40" y="44" font-size="18" fill="#78ddd3" letter-spacing="2">A QUALITY FEEDBACK LOOP</text><text x="40" y="82" font-size="28" fill="#e6f4f4" >A recommendation earns trust through checks and review.</text><rect x="40" y="122" width="250" height="182" rx="14" fill="#0a252d" stroke="#31717a"/><text x="59" y="155" font-size="15" fill="#78ddd3" >01</text><text x="59" y="192" font-size="23" fill="#e6f4f4" font-weight="700">Frame the risk</text><text x="59" y="234" font-size="18" fill="#e6f4f4" >Change + context</text><text x="59" y="269" font-size="18" fill="#bed8dc" >What could fail?</text><rect x="330" y="122" width="250" height="182" rx="14" fill="#0a252d" stroke="#31717a"/><text x="349" y="155" font-size="15" fill="#78ddd3" >02</text><text x="349" y="192" font-size="23" fill="#e6f4f4" font-weight="700">Do the work</text><text x="349" y="234" font-size="18" fill="#e6f4f4" >Generate + execute</text><text x="349" y="269" font-size="18" fill="#bed8dc" >Keep run evidence</text><rect x="620" y="122" width="250" height="182" rx="14" fill="#0a252d" stroke="#31717a"/><text x="639" y="155" font-size="15" fill="#78ddd3" >03</text><text x="639" y="192" font-size="23" fill="#e6f4f4" font-weight="700">Challenge it</text><text x="639" y="234" font-size="18" fill="#e6f4f4" >Coverage + mutation</text><text x="639" y="269" font-size="18" fill="#bed8dc" >Security + review</text><rect x="910" y="122" width="250" height="182" rx="14" fill="#0a252d" stroke="#31717a"/><text x="929" y="155" font-size="15" fill="#78ddd3" >04</text><text x="929" y="192" font-size="23" fill="#e6f4f4" font-weight="700">Decide + learn</text><text x="929" y="234" font-size="18" fill="#e6f4f4" >Human quality decision</text><text x="929" y="269" font-size="18" fill="#bed8dc" >Record the outcome</text><path d="M290 211H322M580 211H612M870 211H902M1035 321V358H165V321" fill="none" stroke="#78ddd3" stroke-width="3"/><text x="455" y="388" font-size="16" fill="#78ddd3" letter-spacing="2">OUTCOME FEEDBACK → REUSABLE PATTERNS</text><text x="40" y="441" font-size="21" fill="#e6f4f4" >Truth filter: inspect claims, surface uncertainty, keep people accountable.</text><text x="40" y="479" font-size="17" fill="#bed8dc" >Conceptual workflow. Available checks depend on your task, tools and configuration.</text></g></svg>