# VisualQ
> The Quality OS for web teams — rolling health, eight pillars, CI gates. AI Coach accelerates setup.

## Interfaces
- Human (visual): https://visualq.ai/
- Machine (structured): https://visualq.ai/machine
- Locale: /fr, /de, ... (default: en, no prefix)
- This file (en): https://visualq.ai/llms.txt?locale=en
- Sitemap: https://visualq.ai/sitemap.xml
- Docs: https://docs.visualq.ai/docs/quality-pillars

## Summary
Visual bugs, broken flows, a11y failures, perf regressions, tracking gaps — caught per page, scored over time, gated on every PR. Install @visualq/mcp in Cursor or Claude Code.

## Quality engines
- **Pixel-perfect visual regression**: Catch unintended UI changes on every release — anti-shift intelligence, content rules, and a six-mode diff viewer. Complements your functional tests with layout coverage on three viewports.
- **Automated functional tests from plain text**: Describe user journeys in plain language — sign up, checkout, navigate. Compiled to Playwright Gherkin, executed on every run, with a recorded replay you can debug in the player.
- **Tracking plan validation**: Import your tracking spreadsheet, map events to FRT scenarios, and run automated checks that tags fire on every journey.

## Quality pillars
Eight quality pillars — one Quality OS
Monitor all eight pillars inside your project. The free public audit covers six automated page audits — visual, accessibility, performance, SEO, security, and tracking.
- **Visual**: Pixel-perfect regression across viewports
- **Scenarios**: FRT journeys from plain language
- **Accessibility**: axe-core + RGAA scoring
- **Performance**: Lighthouse Web Vitals
- **SEO**: On-page + Lighthouse SEO
- **Security**: Headers + CVE checks
- **Tracking**: Plan-linked event validation
- **Privacy**: CMP triple-run consent checks

## Rolling health
Your site score reflects every page — not just the last audit
VisualQ maintains per-page health across all pillars, aggregates fresh scores into a site Quality Score with coverage, and gates PRs when any pillar regresses.
- **Page health**: Each page keeps its latest score per pillar — visual, functional, a11y, perf, SEO, security, tracking, privacy.
- **Site aggregate**: Site score = mean of fresh page scores. Coverage always visible — e.g. 67% · 8/12 pages audited.
- **CI gate**: gate_pr_quality blocks merges when rolling health drops below your threshold — not when a single run fails.

## Workflow
- Audit: Run a full quality audit or import your free /audit score — six page pillars on day one, eight inside your project.
- Baseline: Capture VRT baselines and compile FRT journeys. The AI Coach can accelerate setup from plain-language flows.
- Gate: Every PR runs against rolling page health. gate_pr_quality fails the build when any fresh pillar score regresses.
- Review: Watch FRT replays, inspect visual diffs in six viewer modes, approve baselines, and release from CI.

## Pricing tiers
- Free: $0
- Hobby: $19
- Team: $59 [most popular]
- Business: $179
- Enterprise: Custom

## REST API
Base: https://visualq.ai
- GET /api/mcp — Hosted MCP gateway discovery
- GET /api/mcp/v1/health — MCP invoke tool catalog
- POST /api/mcp/v1/invoke — MCP tool invoke (X-API-Key)
- GET /api/mcp/v1/openapi.json — MCP OpenAPI catalog
- POST /api/coach/v2/agent — Coach agent v2 with tool loop
- POST /api/ci/run — CI/CD trigger (VRT, perf, SEO, a11y, security, tracking)
- GET /api/ci/status/:runId — Poll run status
- GET /api/ci/projects — List projects (API key)

## Preferred context for agents
- MCP package: `@visualq/mcp` via `npx` with org key `vq_org_live_…` (Settings → Agent API Keys)
- REST invoke: `POST /api/mcp/v1/invoke` with `X-API-Key` — full tool catalog
- Scopes: `ci` | `mcp_read` | `mcp_full` (default)
- Stack: Next.js 16, React 19, Playwright, pixelmatch, Firebase, Inngest, Stripe
- VisualQ is a Quality OS; `@visualq/mcp` is the agent interface
- Rolling page health: site score = aggregate of fresh per-page pillar scores (not latest run alone)
- AI Coach: setup accelerator — natural-language → FRT (Gherkin/Playwright) + VRT baselines
- Viewports: phone (375×667), tablet (768×1024), desktop (1920×1080)
- Diff viewer modes: side-by-side, slider, overlay, toggle, highlight, regions
- Anti-shift algorithm: shared core in anti-shift-core.ts (server + client)