Desperado · Sep 12, 2026 · Sep 12, 2026
diff --git a/.github/workflows/public-docs.yml b/.github/workflows/public-docs.yml
@@ -0,0 +1,30 @@
+name: Public documentation
+
+on:
+  pull_request:
+    paths: ["**.md", ".github/workflows/public-docs.yml"]
+  push:
+    branches: [main]
+    paths: ["**.md", ".github/workflows/public-docs.yml"]
+  workflow_dispatch:
+  schedule:
+    - cron: "19 8 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  links:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+      - name: Require the canonical documentation entry point
+        run: python3 -c "from pathlib import Path; assert 'https://docs.qualitymax.io/' in Path('README.md').read_text(), 'The entry README must link to canonical documentation'"
+      - name: Check Markdown links and local anchors
+        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2
+        with:
+          lycheeVersion: v0.24.2
+          args: --no-progress --include-fragments --timeout 30 --max-retries 2 '*.md' 'docs/**/*.md'
+          fail: true
+          jobSummary: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,22 +1,9 @@
 # Contributing to QualityMax
 
-Thank you for your interest in contributing!
+Use the issue tracker in the repository that owns the tool or documentation you want to improve. Before opening an issue, search for an existing report and check the [documentation](https://docs.qualitymax.io/).
 
-## Ways to Contribute
+For a bug report, include the version, environment, expected behavior, actual behavior, and a minimal reproduction. Remove credentials and customer data from logs and screenshots. Report sensitive vulnerabilities through [SECURITY.md](SECURITY.md).
 
-- Report bugs via GitHub Issues
-- Suggest features
-- Improve documentation
-- Share feedback
+For a change, create a branch and open a focused pull request. Follow the repository's own contribution instructions, preserve its license, and run checks appropriate to the change. Product setup and feature documentation should link to the canonical docs instead of duplicating volatile instructions.
 
-## Bug Reports
-
-Please include:
-
-- Steps to reproduce
-- Expected vs actual behavior
-- Screenshots if applicable
-
-## Contact
-
-For questions: contact@qamax.co
+For product questions that cannot be discussed publicly, contact **contact@qualitymax.io**. This guidance does not promise a support response time.
diff --git a/LICENSE b/LICENSE
@@ -5,4 +5,4 @@ All rights reserved.
 This software and its documentation are proprietary and confidential.
 Unauthorized copying, distribution, or use is strictly prohibited.
 
-For licensing inquiries, contact: contact@qamax.co
+For licensing inquiries, contact: contact@qualitymax.io
diff --git a/README.md b/README.md
@@ -1,133 +1,106 @@
-<p align="center">
-  <img src="assets/logo.png" alt="QualityMax" width="300">
-</p>
+# QualityMax
 
-<h1 align="center">QualityMax</h1>
+**Independent verification for AI-written code.**
 
-<p align="center">
-  <strong>AI-Native Test Automation Platform</strong>
-</p>
+Discover user journeys, generate and run tests, review changes, and inspect the evidence behind your next release.
 
-<p align="center">
-  Generate, execute, and self-heal tests for Go, Rust, Python, and Playwright — across your entire CI/CD pipeline.
-</p>
+[Website](https://qualitymax.io) · [Open QualityMax](https://app.qualitymax.io) · [Documentation](https://docs.qualitymax.io/) · [Standalone tools](https://docs.qualitymax.io/free-and-open-source/)
 
-<p align="center">
-  <a href="https://qualitymax.io"><img src="https://img.shields.io/badge/Website-qualitymax.io-7c3aed" alt="Website"></a>
-  <a href="https://app.qualitymax.io"><img src="https://img.shields.io/badge/App-app.qualitymax.io-10b981" alt="App"></a>
-  <a href="https://www.linkedin.com/company/qualitymax/"><img src="https://img.shields.io/badge/LinkedIn-QualityMax-0077B5" alt="LinkedIn"></a>
-  <a href="https://buymeacoffee.com/qualitymax"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?logo=buymeacoffee" alt="Buy Me a Coffee"></a>
-</p>
+This repository is the public product guide and documentation entry point. The hosted platform source is maintained separately. Individual tools below have their own source repositories, licenses, and requirements.
 
----
+## Choose your starting point
 
-## What is QualityMax?
+| I want to… | Start here |
+|---|---|
+| Generate coverage and inspect a first completed run | [Web app quickstart](https://docs.qualitymax.io/quickstart-web-app/) |
+| Connect my coding agent to hosted QualityMax | [MCP quickstart](https://docs.qualitymax.io/quickstart-mcp/) |
+| Use the platform CLI and local execution agent | [CLI quickstart](https://docs.qualitymax.io/quickstart-cli/) |
+| Try local tools without a QualityMax account | [Standalone tools guide](https://docs.qualitymax.io/free-and-open-source/) |
+| Evaluate QualityMax for my team | [Team evaluator guide](https://docs.qualitymax.io/persona-team-evaluator/) |
 
-QualityMax is the AI QA engineer for your team. Install the GitHub App, and on every pull request:
+Hosted workflows require a QualityMax account and use the allowances of your plan. Standalone tools have separate prerequisites; model providers, coding-agent subscriptions, and your own compute can have costs.
 
-- **AI reviews your code** — Claude Haiku analyzes the diff, flags security issues, posts inline annotations
-- **Runs your tests** — clones your repo, executes `go test` / `cargo test` / `pytest` on our cloud, reports pass/fail
-- **Runs AI-generated tests** — tests that QualityMax created from analyzing your codebase run alongside yours
-- **Reports results as a GitHub check** — directly on the PR
+## From a user journey to reviewable evidence
 
-Zero config. No YAML. No GitHub Actions minutes consumed.
-
-## How It Works
-
-```
-Install GitHub App -> Link repo -> Every PR gets:
-
-  Gate Alpha -- AI code review + SAST security scan
-  Gate Gamma -- Run your repo's own test suite
-  Gate Delta -- Run AI-generated tests
-  Results posted as GitHub check + PR comment
+```mermaid
+flowchart LR
+    A[Discover journeys] --> B[Review generated tests]
+    B --> C[Execute tests]
+    C --> D[Inspect results and artifacts]
+    D --> E[Review findings or repairs]
+    E --> F[Rerun and retain evidence]
 ```
 
-## Key Features
+QualityMax organizes work as **Projects → Test Cases → Automation Scripts**. A test case records expected behavior; scripts implement that intent for a framework. Inspect the completed execution and its available artifacts before treating a queued job or a generated script as proof. [Core concepts](https://docs.qualitymax.io/core-concepts/)
 
-| Feature | Description |
-|---------|-------------|
-| **Multi-Language Testing** | Go (`go test`), Rust (`cargo test`), Python (`pytest`), Playwright (browser E2E) |
-| **AI Test Generation** | Analyze your repo, identify test gaps, generate test cases and scripts |
-| **CI/CD Pipeline** | AI review + repo tests + AI tests on every PR |
-| **Cloud Execution** | Run tests on QualityMax infrastructure |
-| **Self-Healing Tests** | Broken Playwright tests auto-fix when selectors change |
-| **10 App Types** | CLI tools, TUI agents, libraries, mobile apps, browser extensions |
-| **MCP Integration** | Works with Claude Code and qmax-code as an AI agent tool |
-| **GitHub and GitLab** | Full support for both platforms |
+## Explore the platform
 
-## Quick Start
+| Capability | What to expect | Documentation |
+|---|---|---|
+| Discovery and generation | Discover application journeys and produce reviewable cases and scripts | [Discovery & Generation](https://docs.qualitymax.io/discovery-generation/) |
+| PR verification | Review changes, run supported suites, and check deployed previews | [Code Review & Gates](https://docs.qualitymax.io/code-review-gates/) |
+| Nexus | Specialist reviews with attributed findings and shareable reports | [Nexus review](https://docs.qualitymax.io/nexus-review/) |
+| AI application validation | Conversation evaluation, adversarial evaluations, and hallucination checks | [AI validation](https://docs.qualitymax.io/ai-validation/) |
+| Agentic Eyes | Simulated browser journeys with observations about usability and friction | [Agentic Eyes](https://docs.qualitymax.io/agentic-eyes/) |
+| Self-healing | Investigate failed tests and review proposed repairs | [Self-healing](https://docs.qualitymax.io/self-healing/) |
+| Slack | Project-aware questions and supported actions through proposals and approval | [Slack](https://docs.qualitymax.io/slack/) |
+| Grounded project context | Reuse verified facts and inspect their sources | [Memory & Grounding](https://docs.qualitymax.io/memory-grounding/) |
+| Test management and portability | Organize cases/scripts, import assets, and exchange QTML | [Test management](https://docs.qualitymax.io/test-management/) · [QTML](https://docs.qualitymax.io/export-qtml/) |
+| Performance | k6 workflows and migration guides for existing performance assets | [Performance](https://docs.qualitymax.io/performance/) |
+| Mobile | Responsive readiness audits and managed mobile-flow guidance | [Mobile](https://docs.qualitymax.io/mobile/) |
+| Evidence | Interpret execution artifacts, signed verdicts, and exposure receipts | [Evidence & Trust](https://docs.qualitymax.io/evidence-trust/) |
 
-### Option 1: GitHub App (recommended)
+### Understand the PR gates
 
-1. Install the [QualityMax GitHub App](https://github.com/apps/qualitymaxapp) on your repo
-2. Import the repo at [app.qualitymax.io](https://app.qualitymax.io)
-3. Deep scan runs automatically, test areas identified, review and approve
-4. Tests generated and run on every future PR
+| Gate | Purpose | Behavior |
+|---|---|---|
+| Alpha | Review the diff and run static security checks | Blocking verdicts can fail the check |
+| Gamma | Run a detected, supported native test suite | Failures can fail the check; skips when there is no applicable suite |
+| Delta | Run QualityMax-generated project scripts | Advisory warnings |
+| Beta | Run browser tests against a deployed preview | Triggered by the successful deployment event; failures can fail the check |
 
-### Option 2: CLI Agent
+Configure your repository's required checks for merge enforcement. Enabled gates, supported frameworks, preview deployment events, and project settings determine what runs. The GitHub App and the explicit GitHub Action have different setup and execution paths. See [gate verdicts](https://docs.qualitymax.io/code-review-gates-verdicts/) for the decision rules.
 
-```bash
-# Install qmax-code (Go TUI agent)
-brew install qualitymax/tap/qmax-code
-```
+Nexus on-demand specialist review is a separate workflow from automatic PR review. A Slack reply from one active specialist does not imply that a full multi-persona review ran.
 
-Or add QualityMax QA tools to Claude Code by placing a `.mcp.json` in your project root:
-
-```json
-{
-  "mcpServers": {
-    "qmax": {
-      "command": "npx",
-      "args": ["-y", "@qualitymax/qmax-mcp"]
-    }
-  }
-}
-```
+## Local tools and integrations
 
-## Pipeline Architecture
+| Project | Use it for | License / status |
+|---|---|---|
+| [qmax-mcp](https://github.com/Quality-Max/qmax-mcp) | Four standalone MCP tools: scan, inspect, generate a Playwright reproduction, run a test | MIT |
+| [qmax-code](https://github.com/Quality-Max/qmax-code) | A QA terminal agent with standalone and hosted-connected modes | Source available, FSL-1.1-ALv2 |
+| [Free QA Skills](https://github.com/Quality-Max/free-qa-skills) | QA workflows inside supported coding agents | Apache-2.0 |
+| [9lives](https://github.com/Quality-Max/9lives) | Local test repair, reruns, and reviewable diffs | MIT; prototype |
+| [Test Grader](https://github.com/Quality-Max/qualitymax-grader) | Static Playwright test-quality grading | Apache-2.0 |
+| [Supply Chain Scanner](https://github.com/Quality-Max/supply-chain-scanner) | Python dependency supply-chain checks | Apache-2.0 |
+| [qmax local agent](https://github.com/Quality-Max/qmax-local-agent) | Platform CLI and local test execution | Apache-2.0 |
+| [GitHub Action](https://github.com/Quality-Max/qualitymax-github-action) | Explicit CI workflows with results and report links | MIT |
+| [n8n integration](https://github.com/Quality-Max/n8n-nodes-qualitymax) | Connect project, test, and performance workflows | MIT |
+| [qmax-receipt](https://github.com/Quality-Max/qmax-receipt) | Shared signed exposure-receipt schema | MIT |
 
-```
-PR Opened
-  Gate Alpha: AI Code Review + SAST (~17s)
-  Gate Gamma: Clone and Run Repo Tests (~30-60s)
-  Gate Delta: Run AI-Generated Tests (~30s)
-  Gate Beta: E2E Tests Against Preview Deploy (web apps only)
-```
+**Local MCP versus hosted MCP:** starting the standalone qmax-mcp package exposes its local tools without a QualityMax account. To use hosted projects and execution, follow the [hosted MCP quickstart](https://docs.qualitymax.io/quickstart-mcp/) or the package's documented proxy mode. They are distinct connection paths.
 
-## Supported Languages
+For qmax-code installation, use the [maintained source README](https://github.com/Quality-Max/qmax-code#install) and [latest release](https://github.com/Quality-Max/qmax-code/releases/latest). Advanced terminal commands can be experimental; check the source README for current availability.
 
-| Language | Test Command | Cloud Execution | CI/CD Pipeline |
-|----------|-------------|-----------------|----------------|
-| **Go** | `go test -json ./...` | Yes | Yes |
-| **Rust** | `cargo test` | Yes | Yes |
-| **Python** | `pytest` | Yes | Yes |
-| **Playwright** | `npx playwright test` | Yes | Yes |
+## See concrete examples
 
-## Security
+- [Local MCP walkthrough](https://github.com/Quality-Max/qmax-mcp/tree/main/demo): inspection, reproduction, and execution artifacts.
+- [9lives repair demo](https://github.com/Quality-Max/9lives/blob/main/demo/heal.gif): a local repair workflow.
+- [Test Grader examples](https://github.com/Quality-Max/qualitymax-grader#live-example): sample grades and actionable findings.
+- [n8n regression-to-Slack workflow](https://github.com/Quality-Max/n8n-nodes-qualitymax#hero-workflow): an integration template with setup requirements.
+- [CI example repository](https://github.com/Quality-Max/qualitymax-demo-playground): inspect the example and its current run history.
+- [Self-healing sandbox cookbook](https://github.com/Quality-Max/e2b-cookbook-self-healing-tests): a separate example with its own provider and compute requirements.
 
-- Tests run in isolated environments with secrets-free env whitelist
-- Resource limits (4GB memory, 1024 processes) prevent abuse
-- GitHub App tokens scrubbed from all logs and error messages
-- Input validation on all webhook payloads
+These examples demonstrate their named workflows; they are not live production certifications or universal performance benchmarks. The [example guide](docs/examples.md) explains what to inspect.
 
-## Contact
+## Deployment and embedding
 
-<p>
-  <a href="mailto:contact@qualitymax.io">contact@qualitymax.io</a> ·
-  <a href="https://www.linkedin.com/company/qualitymax/">LinkedIn</a> ·
-  <a href="https://discord.gg/kbEC28D4">Discord</a> ·
-  <a href="https://qualitymax.io">Website</a> ·
-  <a href="https://github.com/Quality-Max/qualitymax/issues">Issues</a>
-</p>
+The hosted application is the standard evaluation path. Sovereign is a **private preview** with design partners; supported topology and operational responsibilities are agreed during evaluation. [Deployment guide](https://docs.qualitymax.io/deployment/)
 
-## License
+For embedding workflows and evaluating branding requirements, see [Partner / White-label](https://docs.qualitymax.io/partner-white-label/).
 
-Proprietary — Copyright 2025-2026 QualityMax. All rights reserved.  
-See [LICENSE](LICENSE) for details.
+## Help and contributions
 
----
+Use [documentation](https://docs.qualitymax.io/) for setup and product behavior, [issues](https://github.com/Quality-Max/qualitymax/issues) for public bugs and documentation feedback, and [CONTRIBUTING.md](CONTRIBUTING.md) for contributions. Report sensitive issues through [SECURITY.md](SECURITY.md).
 
-<p align="center">
-  Built in Berlin | Copyright 2025-2026 QualityMax. All rights reserved.
-</p>
+This repository's [license](LICENSE) is separate from the licenses of the individual tools linked above.
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,27 +1,7 @@
-# Security Policy
+# Security policy
 
-## Reporting a Vulnerability
+Report a suspected vulnerability privately to **contact@qualitymax.io**. Include the affected repository or product, version, impact, and a concise reproduction using a controlled example. Do not include live credentials or customer data, and do not open a public issue containing sensitive details.
 
-If you discover a security vulnerability, please email us at contact@qamax.co with:
+We will coordinate investigation and disclosure with you. Avoid accessing or changing other users' data. A repository-specific security policy takes precedence over the organization default.
 
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact
-
-We will respond within 48 hours and work with you to resolve the issue.
-
-## Security Measures
-
-- All data encrypted at rest (AES-256) and in transit (TLS 1.3)
-- Secrets stored with Fernet encryption
-- Regular dependency audits
-- No customer data stored in public repositories
-- Role-based access control
-
-## Responsible Disclosure
-
-We ask that you:
-
-- Give us reasonable time to fix issues before public disclosure
-- Avoid accessing or modifying other users' data
-- Act in good faith
+For ordinary bugs and documentation feedback, use the repository issue tracker. Product guidance is available at [docs.qualitymax.io](https://docs.qualitymax.io/).
diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,18 @@
+# Examples and evidence
+
+Use these public examples to understand one workflow at a time. Follow each repository's setup instructions and inspect its current status before running it.
+
+| Example | What to inspect |
+|---|---|
+| [qmax-mcp demo](https://github.com/Quality-Max/qmax-mcp/tree/main/demo) | Page observations, chosen locators, generated reproduction, and the execution result |
+| [9lives repair recording](https://github.com/Quality-Max/9lives/blob/main/demo/heal.gif) | The original failure, repair proposal, rerun, and final diff; 9lives is a prototype |
+| [Grader examples](https://github.com/Quality-Max/qualitymax-grader#live-example) | Why different tests receive different grades; a static grade does not establish application correctness |
+| [GitHub Action example](https://github.com/Quality-Max/qualitymax-demo-playground) | Workflow configuration and current run history, including the tested revision |
+| [n8n integration](https://github.com/Quality-Max/n8n-nodes-qualitymax#hero-workflow) | Required connections, execution polling, and the final report link |
+| [Sandbox cookbook](https://github.com/Quality-Max/e2b-cookbook-self-healing-tests) | Isolated execution setup, model requirements, and the rerun result |
+
+For a platform evaluation, follow the [web quickstart](https://docs.qualitymax.io/quickstart-web-app/) and retain the project/run identifiers, tested revision or target, expected behavior, result, and available artifacts. A queued job, generated test, or screenshot without an assertion is not a passing execution.
+
+When presenting a repair, show the same assertion failing before the change and passing afterward. Inspect any changed assertion separately. For a PR gate, include the required-check configuration and the exact commit the check evaluated.
+
+Remove account data, credentials, and customer content before publishing screenshots or reports. Label synthetic examples and recordings as examples rather than current production evidence. See [Evidence & Trust](https://docs.qualitymax.io/evidence-trust/) for interpretation limits.