@diegovelasquezweb/a11y-engine 0.1.2 → 0.1.4

package/docs/cli-handbook.md

@@ -0,0 +1,237 @@
+# CLI Handbook
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+
+---
+
+## Table of Contents
+
+- [Basic usage](#basic-usage)
+- [Prerequisites](#prerequisites)
+- [Flag groups](#flag-groups)
+  - [Targeting & scope](#targeting--scope)
+  - [Audit intelligence](#audit-intelligence)
+  - [Execution & emulation](#execution--emulation)
+  - [Output generation](#output-generation)
+- [Examples](#examples)
+- [Exit codes](#exit-codes)
+
+---
+
+## Basic usage
+
+```bash
+npx a11y-audit --base-url <url> [options]
+```
+
+Or if installed locally:
+
+```bash
+node node_modules/@diegovelasquezweb/a11y-engine/scripts/audit.mjs --base-url <url> [options]
+```
+
+The only required flag is `--base-url`. All other flags are optional.
+
+---
+
+## Prerequisites
+
+The engine uses two separate browser installations:
+
+```bash
+# Required — used by axe-core and CDP checks
+npx playwright install chromium
+
+# Required for pa11y — uses Puppeteer's Chrome (separate from Playwright)
+npx puppeteer browsers install chrome
+```
+
+If Puppeteer Chrome is missing, pa11y checks fail silently (non-fatal) and the scan continues with axe-core + CDP only.
+
+---
+
+## Flag groups
+
+### Targeting & scope
+
+Controls what gets scanned.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base-url` | `<url>` | (Required) | Starting URL. Must include protocol (`https://` or `http://`). |
+| `--max-routes` | `<num>` | `10` | Maximum unique same-origin paths to discover and scan. |
+| `--crawl-depth` | `<num>` | `2` | How deep to follow links during BFS discovery (1-3). Has no effect when `--routes` is set. |
+| `--routes` | `<csv>` | — | Explicit paths to scan (e.g. `/,/about,/contact`). Overrides auto-discovery entirely. |
+| `--project-dir` | `<path>` | — | Path to the audited project source. Enables the source code pattern scanner and framework auto-detection from `package.json`. |
+
+**Route discovery logic**:
+1. If the target has a `sitemap.xml`, all listed URLs are used (up to `--max-routes`).
+2. Otherwise, BFS crawl from `--base-url`, following same-origin `<a href>` links.
+3. `--routes` always takes precedence over both.
+
+---
+
+### Audit intelligence
+
+Controls how findings are interpreted and filtered.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--target` | `<text>` | `WCAG 2.2 AA` | Compliance target label rendered in reports. Does not change which rules run. |
+| `--only-rule` | `<id>` | — | Run a single axe rule ID only. Useful for focused re-audits after fixing a specific issue. |
+| `--ignore-findings` | `<csv>` | — | Comma-separated list of axe rule IDs to suppress from output entirely. |
+| `--exclude-selectors` | `<csv>` | — | CSS selectors to skip. Elements matching these selectors are excluded from axe scanning. |
+| `--axe-tags` | `<csv>` | `wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22a,wcag22aa` | axe-core WCAG tag filter. Also determines the pa11y standard (`WCAG2A`, `WCAG2AA`, or `WCAG2AAA`). |
+| `--framework` | `<name>` | — | Override auto-detected framework. Affects which fix notes and source boundaries are applied. |
+
+**Supported `--framework` values**: `nextjs`, `gatsby`, `react`, `nuxt`, `vue`, `angular`, `astro`, `svelte`, `shopify`, `wordpress`, `drupal`.
+
+---
+
+### Execution & emulation
+
+Controls browser behavior during scanning.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--color-scheme` | `light\|dark` | `light` | Emulates `prefers-color-scheme` media query. |
+| `--wait-until` | `domcontentloaded\|load\|networkidle` | `domcontentloaded` | Playwright page load strategy. Use `networkidle` for SPAs with async rendering. |
+| `--viewport` | `<WxH>` | `1280x800` | Browser viewport in pixels (e.g. `375x812` for mobile, `1440x900` for desktop). |
+| `--wait-ms` | `<num>` | `2000` | Fixed delay (ms) after page load before the engines run. Useful when JS renders content after `DOMContentLoaded`. |
+| `--timeout-ms` | `<num>` | `30000` | Network timeout per page load (ms). |
+| `--headed` | — | `false` | Launch browser in visible mode. Useful for debugging page rendering issues. |
+| `--affected-only` | — | `false` | Re-scan only routes that had violations in the previous scan. Reads `.audit/a11y-scan-results.json` to determine affected routes. Falls back to full scan if no prior results exist. |
+
+---
+
+### Output generation
+
+Controls what artifacts are written.
+
+| Flag | Argument | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--with-reports` | — | `false` | Generate full artifact set: `report.html`, `report.pdf`, `checklist.html`, and `remediation.md`. Requires `--output`. |
+| `--skip-reports` | — | `true` | Default behavior. Only `remediation.md` is generated. |
+| `--output` | `<path>` | — | Absolute or relative path for `report.html`. PDF and checklist are derived from the same directory. |
+| `--skip-patterns` | — | `false` | Disable source code pattern scanner even when `--project-dir` is set. Use this for DOM-only results without static analysis. |
+
+---
+
+## Examples
+
+### Minimal scan
+
+```bash
+# Produces only remediation.md in .audit/
+a11y-audit --base-url https://example.com
+```
+
+### Full audit with all reports
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --with-reports \
+  --output ./audit/report.html
+```
+
+### Include source code intelligence
+
+```bash
+a11y-audit \
+  --base-url http://localhost:3000 \
+  --project-dir . \
+  --with-reports \
+  --output ./audit/report.html
+```
+
+### Focused re-audit — single rule, single route
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --only-rule color-contrast \
+  --routes /checkout \
+  --max-routes 1
+```
+
+### Fast re-audit after applying fixes
+
+```bash
+# Only re-scans routes that had violations in the last run
+a11y-audit --base-url https://example.com --affected-only
+```
+
+### SPA with deferred rendering
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --wait-until networkidle \
+  --wait-ms 3000
+```
+
+### Dark mode audit
+
+```bash
+a11y-audit --base-url https://example.com --color-scheme dark
+```
+
+### Mobile viewport
+
+```bash
+a11y-audit --base-url https://example.com --viewport 375x812
+```
+
+### Suppress known false positives
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --ignore-findings color-contrast,frame-title
+```
+
+### Explicit route list
+
+```bash
+a11y-audit \
+  --base-url https://example.com \
+  --routes /,/pricing,/blog,/contact
+```
+
+### Override framework detection
+
+```bash
+a11y-audit \
+  --base-url http://localhost:3000 \
+  --framework nextjs \
+  --project-dir .
+```
+
+### Custom axe-core WCAG tags
+
+```bash
+# Only WCAG 2.0 A checks
+a11y-audit --base-url https://example.com --axe-tags wcag2a
+
+# Include AAA checks
+a11y-audit --base-url https://example.com --axe-tags wcag2a,wcag2aa,wcag2aaa
+```
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+| :--- | :--- |
+| `0` | Audit completed successfully (regardless of findings count) |
+| `1` | Runtime error — invalid URL, missing required flag, stage failure, or timeout |
+
+The engine never exits `1` just because findings were found. Exit `1` only indicates a pipeline or configuration error.
+
+**Stdout markers** (parseable by scripts and CI):
+
+```
+REMEDIATION_PATH=<abs-path>   # always printed on success
+REPORT_PATH=<abs-path>        # only printed when --with-reports is set
+```

package/docs/outputs.md

@@ -0,0 +1,303 @@
+# Output Artifacts
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+
+---
+
+## Table of Contents
+
+- [Default output directory](#default-output-directory)
+- [progress.json](#progressjson)
+- [a11y-scan-results.json](#a11y-scan-resultsjson)
+- [a11y-findings.json](#a11y-findingsjson)
+- [remediation.md](#remediationmd)
+- [report.html](#reporthtml)
+- [report.pdf](#reportpdf)
+- [checklist.html](#checklisthtml)
+- [Consuming outputs programmatically](#consuming-outputs-programmatically)
+
+---
+
+## Default output directory
+
+All artifacts are written to `.audit/` relative to the package root (`SKILL_ROOT`). When consumed as an npm package, this resolves to the real package path inside `node_modules/`.
+
+```
+.audit/
+├── progress.json            # real-time scan progress (per-engine steps + counts)
+├── a11y-scan-results.json   # merged raw results from axe + CDP + pa11y
+├── a11y-findings.json       # enriched findings (primary data artifact)
+├── remediation.md           # AI agent remediation guide
+├── report.html              # interactive dashboard (--with-reports)
+├── report.pdf               # compliance report (--with-reports)
+├── checklist.html           # manual testing checklist (--with-reports)
+└── screenshots/             # element screenshots per violation
+```
+
+> When integrating the engine as a dependency (e.g. in `a11y-scanner`), use `fs.realpathSync` on the symlink path to resolve the real `.audit/` location — pnpm uses a deep `.pnpm/` directory structure, not the `node_modules/@scope/pkg` symlink.
+
+---
+
+## progress.json
+
+Real-time scan progress written by `scripts/engine/dom-scanner.mjs` as each engine runs. Used by integrations for live progress UI.
+
+```json
+{
+  "steps": {
+    "page":  { "status": "done", "updatedAt": "2026-03-14T14:02:50.609Z" },
+    "axe":   { "status": "done", "updatedAt": "2026-03-14T14:02:51.389Z", "found": 8 },
+    "cdp":   { "status": "done", "updatedAt": "2026-03-14T14:02:51.401Z", "found": 3 },
+    "pa11y": { "status": "done", "updatedAt": "2026-03-14T14:02:55.667Z", "found": 2 },
+    "merge": { "status": "done", "updatedAt": "2026-03-14T14:02:55.668Z", "axe": 8, "cdp": 3, "pa11y": 2, "merged": 11 }
+  },
+  "currentStep": "merge"
+}
+```
+
+### Step keys
+
+| Key | Engine | Description |
+| :--- | :--- | :--- |
+| `page` | — | Page navigation and load |
+| `axe` | axe-core | axe-core WCAG rule scan. `found` = violation count. |
+| `cdp` | CDP | Chrome DevTools Protocol accessibility tree check. `found` = issue count. |
+| `pa11y` | pa11y | HTML CodeSniffer scan. `found` = issue count. |
+| `merge` | — | Cross-engine merge and deduplication. `merged` = final unique count. |
+
+### Step statuses
+
+`pending` → `running` → `done` (or `error`)
+
+---
+
+## a11y-scan-results.json
+
+Merged results from all three engines (axe-core + CDP + pa11y) per route. Written by `scripts/engine/dom-scanner.mjs`.
+
+```json
+{
+  "generated_at": "2026-03-14T14:02:55.668Z",
+  "base_url": "https://example.com",
+  "projectContext": { "framework": "nextjs", "uiLibraries": ["radix-ui"] },
+  "routes": [
+    {
+      "path": "/",
+      "url": "https://example.com/",
+      "violations": [...],
+      "incomplete": [...],
+      "passes": [...]
+    }
+  ]
+}
+```
+
+Each violation in the `violations` array includes a `source` field indicating which engine produced it (`undefined` for axe-core, `"cdp"` for CDP checks, `"pa11y"` for pa11y).
+
+This file is consumed by `analyzer.mjs` and also used by `--affected-only` to determine which routes to re-scan on subsequent runs.
+
+---
+
+## a11y-findings.json
+
+The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. This is the file consumed by all report builders.
+
+### Top-level structure
+
+```json
+{
+  "metadata": { ... },
+  "findings": [ ... ],
+  "incomplete_findings": [ ... ]
+}
+```
+
+### `metadata` fields
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `scanDate` | `string` (ISO 8601) | Timestamp of when the scan ran |
+| `checklist` | `object` | Manual check results if checklist was run |
+| `projectContext` | `object` | Auto-detected framework, CMS, and UI libraries |
+| `overallAssessment` | `string` | `"Pass"`, `"Conditional Pass"`, or `"Fail"` |
+| `passedCriteria` | `string[]` | WCAG criterion IDs with no active violations |
+| `outOfScope` | `object[]` | Findings excluded due to guardrails |
+| `recommendations` | `object[]` | Grouped fix recommendations by component |
+| `testingMethodology` | `object` | Scan scope and methodology summary |
+| `fpFiltered` | `number` | Count of findings filtered as likely false positives |
+| `deduplicatedCount` | `number` | Count of duplicate findings removed |
+
+### `findings` — per-finding fields
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | Deterministic finding ID (e.g. `A11Y-001`) |
+| `rule_id` | `string` | Rule ID from the source engine (e.g. `color-contrast`, `cdp-missing-accessible-name`, `pa11y-wcag2aa-...`) |
+| `source_rule_id` | `string\|null` | Original rule ID when mapped from CDP/pa11y to axe equivalent |
+| `title` | `string` | Human-readable finding title |
+| `severity` | `string` | `Critical`, `Serious`, `Moderate`, or `Minor` |
+| `wcag` | `string` | WCAG success criterion (e.g. `1.4.3`) |
+| `wcag_criterion_id` | `string` | Full WCAG criterion ID (e.g. `1.4.3`) |
+| `wcag_classification` | `string` | `A`, `AA`, `AAA`, or `Best Practice` |
+| `area` | `string` | Affected page area (e.g. `Navigation`, `Forms`) |
+| `url` | `string` | URL where the violation was found |
+| `selector` | `string` | CSS selector for the affected element |
+| `primary_selector` | `string` | Most stable selector chosen by the analyzer |
+| `impacted_users` | `string` | Disability groups affected |
+| `actual` | `string` | Observed violation description |
+| `expected` | `string` | What the correct behavior should be |
+| `category` | `string` | Violation category (e.g. `Color & Contrast`) |
+| `primary_failure_mode` | `string\|null` | Root cause classification |
+| `relationship_hint` | `string\|null` | Label/input relationship context |
+| `failure_checks` | `object[]` | Engine check-level failure details |
+| `related_context` | `object[]` | Surrounding DOM context |
+| `fix_description` | `string\|null` | Plain-language fix explanation |
+| `fix_code` | `string\|null` | Ready-to-apply code snippet |
+| `fix_code_lang` | `string` | Language for code block (e.g. `html`, `jsx`) |
+| `recommended_fix` | `string` | Link to canonical fix reference (APG, MDN) |
+| `mdn` | `string\|null` | MDN documentation URL |
+| `effort` | `string\|null` | Fix effort estimate (`low`, `medium`, `high`) |
+| `related_rules` | `string[]` | Related rule IDs |
+| `guardrails` | `object\|null` | Agent scope guardrails for this finding |
+| `false_positive_risk` | `string\|null` | Known false positive patterns |
+| `fix_difficulty_notes` | `string\|null` | Edge cases and pitfalls for this fix |
+| `framework_notes` | `string\|null` | Framework-specific fix guidance |
+| `cms_notes` | `string\|null` | CMS-specific fix guidance |
+| `check_data` | `object\|null` | Raw engine check data |
+| `total_instances` | `number` | Count of affected elements across all pages |
+| `evidence` | `object[]` | DOM HTML snippets for each affected element |
+| `screenshot_path` | `string\|null` | Path to element screenshot |
+| `file_search_pattern` | `string\|null` | Regex/glob pattern to find the source file |
+| `managed_by_library` | `string\|null` | UI library managing this element (if any) |
+| `ownership_status` | `string` | `confirmed`, `potential`, or `unknown` |
+| `ownership_reason` | `string\|null` | Why this ownership status was assigned |
+| `primary_source_scope` | `string[]` | Source file paths likely containing the issue |
+| `search_strategy` | `string` | Agent search strategy recommendation |
+| `component_hint` | `string\|null` | Component name hint for source search |
+| `verification_command` | `string\|null` | CLI command to verify fix was applied |
+| `verification_command_fallback` | `string\|null` | Fallback verify command |
+| `pages_affected` | `number\|null` | Number of pages with this violation |
+| `affected_urls` | `string[]\|null` | All URLs where this violation appears |
+
+### `incomplete_findings`
+
+Violations that axe-core flagged as "needs review" (not confirmed pass or fail). Included for manual verification but not counted in the compliance score.
+
+---
+
+## remediation.md
+
+AI agent-optimized remediation guide. Always generated (even without `--with-reports`). Written to `.audit/remediation.md`.
+
+Content:
+
+- Audit summary header with score, URL, and date
+- Per-finding sections with: violation description, DOM evidence, fix description, code snippet, verify command, and WCAG criterion
+- "Passed WCAG 2.2 Criteria" section listing clean criteria
+- "Source Code Patterns" section (if source scanner ran)
+- Component grouping table for batching fixes
+
+The path is printed to stdout on completion as `REMEDIATION_PATH=<path>`.
+
+---
+
+## report.html
+
+Interactive HTML dashboard. Generated only with `--with-reports --output <path>`.
+
+Features:
+
+- Severity-grouped findings with expandable detail cards
+- DOM evidence with syntax-highlighted code
+- Screenshot thumbnails per finding
+- Search and filter by severity, category, and page
+- Compliance score gauge with grade label
+- Persona impact breakdown (visual, motor, cognitive, etc.)
+- Quick wins section (Critical/Serious findings with ready code)
+
+Written to the path specified by `--output`. The path is printed to stdout as `REPORT_PATH=<path>`.
+
+---
+
+## report.pdf
+
+Formal PDF compliance report for stakeholders. Generated alongside `report.html` when `--with-reports` is set.
+
+Sections:
+
+1. Cover page with score, date, and target URL
+2. Table of Contents
+3. Executive Summary — score, overall assessment, finding counts by severity
+4. Legal Risk Summary — applicable regulations based on score tier
+5. Methodology — scan scope, tools, and WCAG version
+6. Findings Breakdown — severity table and issue summary
+7. Recommended Next Steps — dynamically generated from findings
+
+Written to the same directory as `--output` with `.pdf` extension.
+
+---
+
+## checklist.html
+
+Interactive manual testing checklist. Generated alongside `report.html` when `--with-reports` is set.
+
+Contains the 41 WCAG 2.2 AA manual checks that automated tools cannot detect, including:
+
+- Keyboard navigation and focus order
+- Screen reader announcements
+- Motion and animation
+- Zoom and reflow (400%)
+- Cognitive load and reading level
+
+Each item is checkable and includes testing instructions. State is not persisted between sessions.
+
+Written to the same directory as `--output` as `checklist.html`.
+
+---
+
+## Consuming outputs programmatically
+
+### Reading `a11y-findings.json` from an integration
+
+```js
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+// Resolve real path (handles pnpm symlinks)
+const req = createRequire(import.meta.url);
+const auditScript = req.resolve("@diegovelasquezweb/a11y-engine/scripts/audit.mjs");
+const engineRoot = path.dirname(path.dirname(auditScript));
+const findingsPath = path.join(engineRoot, ".audit", "a11y-findings.json");
+
+const { findings, metadata } = JSON.parse(fs.readFileSync(findingsPath, "utf-8"));
+```
+
+> Note: `import.meta.url` may be mangled by bundlers (e.g. Next.js). In that case, use `fs.realpathSync` on the known symlink instead:
+
+```js
+const symlinkBase = path.join(process.cwd(), "node_modules", "@diegovelasquezweb", "a11y-engine");
+const engineRoot = fs.realpathSync(symlinkBase);
+const findingsPath = path.join(engineRoot, ".audit", "a11y-findings.json");
+```
+
+### Reading `progress.json` for live UI updates
+
+```js
+const progressPath = path.join(engineRoot, ".audit", "progress.json");
+
+// Poll this file during scan execution
+if (fs.existsSync(progressPath)) {
+  const progress = JSON.parse(fs.readFileSync(progressPath, "utf-8"));
+  console.log(`Current step: ${progress.currentStep}`);
+  console.log(`axe found: ${progress.steps?.axe?.found ?? "pending"}`);
+}
+```
+
+### Parsing stdout markers
+
+```bash
+OUTPUT=$(node scripts/audit.mjs --base-url https://example.com --with-reports --output ./audit/report.html)
+REMEDIATION_PATH=$(echo "$OUTPUT" | grep REMEDIATION_PATH | cut -d= -f2)
+REPORT_PATH=$(echo "$OUTPUT" | grep REPORT_PATH | cut -d= -f2)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",
@@ -12,13 +12,19 @@
   "engines": {
     "node": ">=18"
   },
+  "exports": {
+    ".": "./scripts/index.mjs"
+  },
+  "main": "scripts/index.mjs",
   "bin": {
     "a11y-audit": "scripts/audit.mjs"
   },
   "files": [
     "scripts/**",
     "assets/**",
+    "docs/**",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -33,5 +39,6 @@
   },
   "devDependencies": {
     "vitest": "^4.0.18"
-  }
+  },
+  "packageManager": "pnpm@10.22.0+sha512.bf049efe995b28f527fd2b41ae0474ce29186f7edcb3bf545087bd61fbbebb2bf75362d1307fda09c2d288e1e499787ac12d4fcb617a974718a6051f2eee741c"
 }

package/scripts/audit.mjs

@@ -31,6 +31,7 @@ Targeting & Scope:
 
 Audit Intelligence:
   --target <text>         Compliance target label (default: "WCAG 2.2 AA").
+  --axe-tags <csv>        Comma-separated axe tags (e.g., wcag2a,wcag2aa).
   --only-rule <id>        Only check for this specific rule ID.
   --ignore-findings <csv> Ignore specific rule IDs.
   --exclude-selectors <csv> Exclude CSS selectors from scan.
@@ -136,6 +137,7 @@ async function main() {
   const routes = getArgValue("routes");
   const waitMs = getArgValue("wait-ms") || DEFAULTS.waitMs;
   const timeoutMs = getArgValue("timeout-ms") || DEFAULTS.timeoutMs;
+  const axeTags = getArgValue("axe-tags");
 
   const sessionFile = getInternalPath("a11y-session.json");
   let projectDir = getArgValue("project-dir");
@@ -254,6 +256,7 @@ async function main() {
     if (viewport) {
       scanArgs.push("--viewport", `${viewport.width}x${viewport.height}`);
     }
+    if (axeTags) scanArgs.push("--axe-tags", axeTags);
 
     await runScript("engine/dom-scanner.mjs", scanArgs, childEnv);
 

package/scripts/core/asset-loader.mjs

@@ -34,6 +34,10 @@ export const ASSET_PATHS = {
     ),
     codePatterns: path.join(ASSET_ROOT, "remediation", "code-patterns.json"),
   },
+  engine: {
+    cdpChecks: path.join(ASSET_ROOT, "engine", "cdp-checks.json"),
+    pa11yConfig: path.join(ASSET_ROOT, "engine", "pa11y-config.json"),
+  },
   reporting: {
     wcagReference: path.join(ASSET_ROOT, "reporting", "wcag-reference.json"),
     complianceConfig: path.join(

package/scripts/engine/analyzer.mjs

@@ -745,7 +745,12 @@ function computeTestingMethodology(payload) {
   const scanned = routes.filter((r) => !r.error).length;
   const errored = routes.filter((r) => r.error).length;
   return {
-    automated_tools: ["axe-core (via @axe-core/playwright)", "Playwright + Chromium"],
+    automated_tools: [
+      "axe-core (via @axe-core/playwright)",
+      "CDP accessibility tree checks (Playwright)",
+      "pa11y (HTML CodeSniffer via Puppeteer)",
+      "Playwright + Chromium",
+    ],
     compliance_target: "WCAG 2.2 AA",
     pages_scanned: scanned,
     pages_errored: errored,
@@ -826,6 +831,8 @@ function buildFindings(inputPayload, cliArgs) {
         findings.push({
           id: "",
           rule_id: v.id,
+          source_rule_id: v.source_rule_id || null,
+          source: v.source || "axe",
           title: v.help,
           severity: IMPACT_MAP[v.impact] || "Medium",
           wcag: mapWcag(v.tags),