@diegovelasquezweb/a11y-engine 0.8.5 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] — 2026-03-16
+
+### Changed
+
+- **Knowledge API consolidated** — `getScannerHelp`, `getPersonaReference`, `getUiHelp`, `getConformanceLevels`, `getWcagPrinciples`, and `getSeverityLevels` are no longer part of the public API. They remain as internal helpers consumed by `getKnowledge`. `getUiHelp` renamed to `getConceptsAndGlossary` internally. `getKnowledge` is the single exported entry point for all knowledge data.
+- TypeScript declarations (`src/index.d.mts`) updated to remove the six individual knowledge functions.
+- `tests/knowledge-api.test.mjs` updated to reflect the consolidated API shape.
+
+---
+
+## [0.8.5] — 2026-03-16
+
+### Fixed
+
+- **pa11y merge no longer drops findings with shared selectors** — the merge step was discarding pa11y findings whenever any prior finding (from axe or CDP) targeted the same selector, regardless of rule. Now pa11y findings are only de-duplicated when the exact same `rule_id + selector` combination already exists.
+
+---
+
+## [0.8.4] — 2026-03-15
+
+### Added
+
+- **`DEFAULT_AI_SYSTEM_PROMPT` exported** — the default Claude system prompt is now part of the public API, allowing consumers to read, log, or extend it.
+- **`VIEWPORT_PRESETS` exported** — four ready-made viewport presets (`Desktop`, `Laptop`, `Tablet`, `Mobile`) exported from the package root for use in scanner UI option pickers.
+- **`dependabot.yml`** — automated dependency update configuration added.
+- **Effort fallback** — `getFindings` now infers `effort` after intelligence enrichment so findings that gain a `fixCode` from the intelligence database are correctly rated `"low"`.
+
+---
+
+## [0.8.3] — 2026-03-15
+
+### Fixed
+
+- **`actual` field no longer contains axe preamble** — the `"Fix any of the following:"` prefix from axe `failureSummary` strings is now stripped in `analyzer.mjs`, producing a cleaner violation description.
+
+### Added
+
+- `SECURITY.md` — security policy and vulnerability reporting process.
+
+---
+
 ## [0.8.2] — 2026-03-16
 
 ### Changed

package/README.md

@@ -15,7 +15,7 @@ Accessibility automation engine for web applications. It orchestrates multi engi
 | **AI enrichment** | Optional Claude-powered analysis that adds contextual fix suggestions based on detected stack, repo structure, and finding patterns |
 | **Report generation** | Produces HTML dashboard, PDF compliance report, manual testing checklist, and Markdown remediation guide |
 | **Source code scanning** | Static regex analysis of project source for accessibility patterns that runtime engines cannot detect. Works with local paths or remote GitHub repos |
-| **Knowledge API** | Exposes WCAG conformance levels, severity definitions, persona profiles, glossary, scanner help, and documentation so frontends and agents can render guidance from engine-owned data |
+| **Knowledge API** | Exposes WCAG conformance levels, severity definitions, persona profiles, glossary, scanner help, and documentation |
 
 ## Installation
 
@@ -41,12 +41,6 @@ import {
   getChecklist,
   getRemediationGuide,
   getSourcePatterns,
-  getScannerHelp,
-  getPersonaReference,
-  getUiHelp,
-  getConformanceLevels,
-  getWcagPrinciples,
-  getSeverityLevels,
   getKnowledge,
 } from "@diegovelasquezweb/a11y-engine";
 ```
@@ -100,12 +94,18 @@ Computes severity totals, compliance score, WCAG pass/fail status, persona impac
 ```ts
 const summary = getOverview(findings, payload);
 // summary.score         -> 72
-// summary.label         -> "Good"
-// summary.wcagStatus    -> "Fail"
+// summary.label         -> "Good"      // "Excellent" | "Good" | "Fair" | "Poor" | "Critical"
+// summary.wcagStatus    -> "Fail"      // "Pass" | "Conditional Pass" | "Fail"
 // summary.totals        -> { Critical: 1, Serious: 3, Moderate: 5, Minor: 2 }
-// summary.personaGroups -> { screenReader: {...}, keyboard: {...}, ... }
-// summary.quickWins     -> [top 3 fixable Critical/Serious findings]
+// summary.personaGroups -> {
+//   screenReader: { label: "Screen Readers", count: 4, icon: "screenReader" },
+//   keyboard:     { label: "Keyboard Only",  count: 2, icon: "keyboard" },
+//   ...
+// }
+// summary.quickWins     -> [top 3 Critical/Serious findings with fixCode]
+// summary.targetUrl     -> "https://example.com"
 // summary.detectedStack -> { framework: "nextjs", cms: null, uiLibraries: [] }
+// summary.totalFindings -> 11
 ```
 
 ### Output API
@@ -122,42 +122,32 @@ These functions render final artifacts from scan payload data.
 
 ### Knowledge API
 
-These functions expose scanner help content, persona explanations, conformance levels, and UI copy so frontends or agents can render guidance from engine-owned data.
+Returns all accessibility knowledge in a single call: scanner help, persona profiles, concepts, glossary, documentation, conformance levels, WCAG principles, and severity definitions.
 
-| Function | Returns | Description |
-| :--- | :--- | :--- |
-| `getScannerHelp(options?)` | `{ locale, version, title, engines, options }` | Scanner option and engine help metadata |
-| `getPersonaReference(options?)` | `{ locale, version, personas }` | Persona labels, descriptions, and mapping hints |
-| `getUiHelp(options?)` | `{ locale, version, concepts, glossary }` | Shared concept definitions and glossary entries |
-| `getConformanceLevels(options?)` | `{ locale, version, conformanceLevels }` | WCAG conformance level definitions with axe tag mappings |
-| `getWcagPrinciples(options?)` | `{ locale, version, wcagPrinciples }` | The four WCAG principles with criterion prefix patterns |
-| `getSeverityLevels(options?)` | `{ locale, version, severityLevels }` | Severity level definitions with labels and ordering |
-| `getKnowledge(options?)` | Full knowledge pack | Combines all knowledge APIs into a single response for UI or agent flows |
+```ts
+const knowledge = getKnowledge({ locale: "en" });
+// knowledge.scanner          → engine and option descriptions
+// knowledge.personas         → persona labels and descriptions
+// knowledge.concepts         → concept definitions
+// knowledge.glossary         → accessibility glossary
+// knowledge.docs             → documentation articles
+// knowledge.conformanceLevels → A/AA/AAA with axe tag mappings
+// knowledge.wcagPrinciples   → the four WCAG principles
+// knowledge.severityLevels   → Critical/Serious/Moderate/Minor definitions
+```
 
-See [API Reference](docs/api-reference.md) for exact options and return types.
+See [API Reference](docs/api-reference.md) for the full `EngineKnowledge` shape.
 
 ## CLI
 
 The package exposes an `a11y-audit` binary for terminal execution. See the [CLI Handbook](docs/cli-handbook.md) for all flags, env vars, and examples.
 
-## AI enrichment
-
-When `ANTHROPIC_API_KEY` is set, the engine runs a post-scan enrichment step that sends Critical and Serious findings to Claude. Claude generates:
-
-- A specific fix description referencing the actual selector, colors, and violation data
-- A production-quality code snippet in the correct framework syntax
-- Context-aware suggestions when repo source files are available
-
-AI output is stored in separate fields (`ai_fix_description`, `ai_fix_code`). The original engine fixes are always preserved. Findings improved by AI are flagged with `aiEnhanced: true`.
-
-The system prompt is fully customizable via `options.ai.systemPrompt` (programmatic API) or the `AI_SYSTEM_PROMPT` env var (CLI).
-
 ## Documentation
 
 | Resource | Description |
 | :--- | :--- |
 | [Architecture](docs/architecture.md) | Multi-engine pipeline, merge logic, and execution model |
-| [API Reference](docs/api-reference.md) | Function signatures, options, and return contracts |
+| [API Reference](docs/api-reference.md) | Function signatures, options, return contracts, and exported constants |
 | [CLI Handbook](docs/cli-handbook.md) | Full flag reference and usage examples |
 | [Output Artifacts](docs/outputs.md) | Schema and structure of every generated file |
 | [Engine Manifest](docs/engine-manifest.md) | Current inventory of source modules, assets, and tests |

package/docs/api-reference.md

@@ -21,12 +21,9 @@
   - [getSourcePatterns](#getsourcepatternsprojdir-options)
 - [Knowledge API](#knowledge-api)
   - [getKnowledge](#getknowledgeoptions)
-  - [getScannerHelp](#getscannerhelpoptions)
-  - [getPersonaReference](#getpersonareferenceoptions)
-  - [getUiHelp](#getuihelpoptions)
-  - [getConformanceLevels](#getconformancelevelsoptions)
-  - [getWcagPrinciples](#getwcagprinciplesoptions)
-  - [getSeverityLevels](#getseveritylevelsoptions)
+- [Constants](#constants)
+  - [VIEWPORT_PRESETS](#viewport_presets)
+  - [DEFAULT_AI_SYSTEM_PROMPT](#default_ai_system_prompt)
 
 ---
 
@@ -53,12 +50,8 @@ import {
   getRemediationGuide,
   getSourcePatterns,
   getKnowledge,
-  getScannerHelp,
-  getPersonaReference,
-  getUiHelp,
-  getConformanceLevels,
-  getWcagPrinciples,
-  getSeverityLevels,
+  VIEWPORT_PRESETS,
+  DEFAULT_AI_SYSTEM_PROMPT,
 } from "@diegovelasquezweb/a11y-engine";
 ```
 
@@ -81,9 +74,9 @@ const payload = await runAudit({
 const findings = getFindings(payload);
 
 // 3. Get compliance summary
-const { score, scoreLabel, wcagStatus, totals, quickWins } = getOverview(findings, payload);
+const { score, label, wcagStatus, totals, quickWins } = getOverview(findings, payload);
 
-console.log(`Score: ${score}/100 (${scoreLabel})`);
+console.log(`Score: ${score}/100 (${label})`);
 console.log(`WCAG Status: ${wcagStatus}`);
 console.log(`Critical: ${totals.Critical}, Serious: ${totals.Serious}`);
 ```
@@ -169,6 +162,42 @@ const payload = await runAudit({
 
 Returns: `Promise<ScanPayload>`
 
+**`ScanPayload` shape:**
+
+```ts
+{
+  findings: RawFinding[],                // Raw findings from axe/CDP/pa11y merge
+  metadata: {
+    target_url: string,                  // The baseUrl that was scanned
+    scanned_at: string,                  // ISO 8601 timestamp
+    engines: {                           // Which engines actually ran
+      axe: boolean,
+      cdp: boolean,
+      pa11y: boolean,
+    },
+    projectContext: {                     // Auto-detected or overridden stack
+      framework: string | null,          // "nextjs" | "react" | "vue" | etc.
+      cms: string | null,               // "wordpress" | "shopify" | etc.
+      uiLibraries: string[],            // ["radix-ui", "tailwindcss", ...]
+    },
+    routes_scanned: number,              // How many pages were actually scanned
+    discovery_method: string,            // "crawl" | "explicit"
+  },
+  incomplete_findings?: RawFinding[],    // axe "incomplete" results (needs-review)
+  patternFindings?: {                    // Only present if projectDir/repoUrl + !skipPatterns
+    generated_at: string,
+    project_dir: string,                 // Local path or repo URL
+    findings: SourcePatternFinding[],
+    summary: {
+      total: number,
+      confirmed: number,
+      potential: number,
+    },
+  },
+  ai_enriched_findings?: EnrichedFinding[], // Only present if ai.enabled + ai.apiKey
+}
+```
+
 > **`ai_enriched_findings` fast path**: When AI enrichment runs, `getFindings()` uses `payload.ai_enriched_findings` directly instead of re-normalizing the raw findings array.
 
 ---
@@ -207,6 +236,85 @@ const findings = getFindings(payload, {
 
 Returns: `EnrichedFinding[]`
 
+**`EnrichedFinding` shape:**
+
+```ts
+{
+  // Identity
+  id: string,                            // "A11Y-001", "A11Y-002", ...
+  ruleId: string,                        // Canonical rule ID (e.g. "color-contrast")
+  source: string,                        // "axe" | "cdp" | "pa11y"
+  sourceRuleId: string | null,           // Original engine rule ID before canonicalization
+
+  // Classification
+  title: string,                         // Human-readable issue title
+  severity: string,                      // "Critical" | "Serious" | "Moderate" | "Minor"
+  category: string | null,               // "color", "forms", "structure", "aria", ...
+  wcag: string,                          // WCAG criterion (e.g. "1.4.3")
+  wcagCriterionId: string | null,        // Full criterion ID (e.g. "1.4.3")
+  wcagClassification: string | null,     // "A" | "AA" | "AAA" | "Best Practice"
+
+  // Location
+  area: string,                          // Page path (e.g. "/about")
+  url: string,                           // Full page URL
+  selector: string,                      // CSS selector of the violating element
+  primarySelector: string,               // Preferred selector for targeting
+
+  // Problem description
+  actual: string,                        // What the engine found
+  expected: string,                      // What WCAG requires
+  impactedUsers: string,                 // "Screen reader users", "Keyboard users", etc.
+  primaryFailureMode: string | null,     // "missing-label" | "low-contrast" | ...
+  relationshipHint: string | null,       // How this relates to other findings
+
+  // Evidence
+  evidence: object[],                    // Raw evidence from the engine
+  failureChecks: object[],              // axe check details
+  relatedContext: object[],             // Related DOM elements
+  totalInstances: number | null,         // How many elements are affected
+  pagesAffected: number | null,          // How many pages have this issue
+  affectedUrls: string[] | null,         // Specific URLs affected
+
+  // Fix guidance
+  fixDescription: string | null,         // Human-readable fix explanation
+  fixCode: string | null,               // Code snippet to fix the issue
+  fixCodeLang: string,                   // "html" | "css" | "jsx" | ...
+  recommendedFix: string,               // Short fix summary
+  mdn: string | null,                   // MDN reference URL
+  effort: string,                        // "low" (has fixCode) | "high" (no fixCode)
+  fixDifficultyNotes: object | null,     // Detailed difficulty breakdown
+
+  // Framework / CMS context
+  frameworkNotes: string | null,         // Framework-specific fix guidance
+  cmsNotes: string | null,              // CMS-specific fix guidance
+  managedByLibrary: string | null,       // If the element is from a 3rd-party lib
+  componentHint: string | null,          // Likely component name
+  fileSearchPattern: string | null,      // Glob pattern to find source file
+
+  // Ownership & search
+  ownershipStatus: string,               // "own" | "third-party" | "unknown"
+  ownershipReason: string | null,        // Why it was classified that way
+  primarySourceScope: string[],          // Directories to search for source
+  searchStrategy: string,                // "verify_ownership_before_search" | ...
+
+  // Verification
+  verificationCommand: string | null,    // CLI command to verify the fix
+  verificationCommandFallback: string | null,
+  screenshotPath: string | null,         // Path or URL to element screenshot
+
+  // Metadata
+  relatedRules: string[],               // Related axe rule IDs
+  falsePositiveRisk: string | null,      // "low" | "medium" | "high"
+  guardrails: object | null,             // Guardrail metadata from the engine
+  checkData: object | null,              // Raw check data from the engine
+
+  // AI enrichment (only when ai.enabled ran)
+  aiEnhanced?: boolean,                  // true when AI enriched this finding
+  aiFixDescription?: string,             // Claude-generated fix explanation
+  aiFixCode?: string,                    // Claude-generated code snippet
+}
+```
+
 ---
 
 ### `getOverview(findings, payload?)`
@@ -218,27 +326,39 @@ import { getFindings, getOverview } from "@diegovelasquezweb/a11y-engine";
 
 const findings = getFindings(payload);
 const overview = getOverview(findings, payload);
-
-// overview example:
-// {
-//   score: 72,              // 0–100. Formula: 100 - (Critical×15) - (Serious×5) - (Moderate×2) - (Minor×0.5)
-//   label: "Fair",          // "Excellent" (90–100) | "Good" (75–89) | "Fair" (55–74) | "Poor" (35–54) | "Critical" (0–34)
-//   wcagStatus: "Fail",     // "Pass" | "Conditional Pass" | "Fail"
-//   totals: { Critical: 1, Serious: 3, Moderate: 5, Minor: 2 },
-//   personaGroups: {
-//     screenReader: { count: 4, findings: [...] },
-//     keyboard:     { count: 2, findings: [...] },
-//     vision:       { count: 3, findings: [...] },
-//     cognitive:    { count: 1, findings: [...] },
-//   },
-//   quickWins: [...],       // top Critical/Serious findings with fix code ready
-//   targetUrl: "https://example.com",
-//   detectedStack: { framework: "nextjs", cms: null, uiLibraries: ["radix-ui"] },
-// }
 ```
 
 Returns: `AuditSummary`
 
+**`AuditSummary` shape:**
+
+```ts
+{
+  score: number,                         // 0–100. Formula: 100 - (Critical×15) - (Serious×5) - (Moderate×2) - (Minor×0.5)
+  label: string,                         // "Excellent" (90–100) | "Good" (75–89) | "Fair" (55–74) | "Poor" (35–54) | "Critical" (0–34)
+  wcagStatus: string,                    // "Pass" | "Conditional Pass" | "Fail"
+  totals: {
+    Critical: number,
+    Serious: number,
+    Moderate: number,
+    Minor: number,
+  },
+  personaGroups: Record<string, {        // Keyed by persona ID
+    label: string,                       // "Screen Readers", "Keyboard Only", ...
+    count: number,                       // Findings affecting this persona
+    icon: string,                        // Same as persona ID
+  }>,
+  quickWins: EnrichedFinding[],          // Top 3 Critical/Serious findings with fixCode
+  targetUrl: string,                     // The scanned URL
+  detectedStack: {
+    framework: string | null,            // "nextjs" | "react" | etc.
+    cms: string | null,                  // "wordpress" | "shopify" | etc.
+    uiLibraries: string[],              // ["radix-ui", "tailwindcss", ...]
+  },
+  totalFindings: number,                 // Total enriched findings count
+}
+```
+
 ---
 
 ## Output API
@@ -254,12 +374,18 @@ const { buffer, contentType } = await getPDFReport(payload, {
   baseUrl: "https://example.com",
   target: "WCAG 2.2 AA",
 });
-
-// In a Next.js API route:
-return new Response(buffer, { headers: { "Content-Type": contentType } });
 ```
 
-Returns: `Promise<{ buffer: Buffer, contentType: string }>`
+Returns: `Promise<PDFReportResult>`
+
+**`PDFReportResult` shape:**
+
+```ts
+{
+  buffer: Buffer,                        // Raw PDF binary data
+  contentType: "application/pdf",        // MIME type for response headers
+}
+```
 
 ---
 
@@ -276,7 +402,16 @@ const { html, contentType } = await getHTMLReport(payload, {
 });
 ```
 
-Returns: `Promise<{ html: string, contentType: string }>`
+Returns: `Promise<HTMLReportResult>`
+
+**`HTMLReportResult` shape:**
+
+```ts
+{
+  html: string,                          // Self-contained HTML document string
+  contentType: "text/html",              // MIME type for response headers
+}
+```
 
 ---
 
@@ -292,7 +427,16 @@ const { html, contentType } = await getChecklist({
 });
 ```
 
-Returns: `Promise<{ html: string, contentType: string }>`
+Returns: `Promise<ChecklistResult>`
+
+**`ChecklistResult` shape:**
+
+```ts
+{
+  html: string,                          // Self-contained HTML with interactive checklist
+  contentType: "text/html",              // MIME type for response headers
+}
+```
 
 ---
 
@@ -307,11 +451,18 @@ const { markdown, contentType } = await getRemediationGuide(payload, {
   baseUrl: "https://example.com",
   patternFindings: payload.patternFindings ?? null,
 });
-
-// Write to disk or return as download
 ```
 
-Returns: `Promise<{ markdown: string, contentType: string }>`
+Returns: `Promise<RemediationGuideResult>`
+
+**`RemediationGuideResult` shape:**
+
+```ts
+{
+  markdown: string,                      // Full Markdown document with remediation roadmap
+  contentType: "text/markdown",          // MIME type for response headers
+}
+```
 
 ---
 
@@ -326,122 +477,181 @@ const result = await getSourcePatterns("./", {
   framework: "nextjs",   // optional — scopes scan to framework source dirs
   onlyPattern: "placeholder-only-label", // optional — run a single pattern
 });
-
-// result example:
-// {
-//   findings: [
-//     {
-//       id: "PAT-a1b2c3",
-//       pattern_id: "placeholder-only-label",
-//       title: "Input uses placeholder as its only label",
-//       severity: "Critical",
-//       status: "confirmed",
-//       file: "src/components/SearchBar.tsx",
-//       line: 12,
-//       match: '  <input placeholder="Search..." />',
-//       context: "...",
-//       fix_description: "Add an aria-label or visible <label> element",
-//     }
-//   ],
-//   summary: { total: 3, confirmed: 2, potential: 1 }
-// }
 ```
 
 Returns: `Promise<SourcePatternResult>`
 
+**`SourcePatternResult` shape:**
+
+```ts
+{
+  findings: {
+    id: string,                          // "PAT-a1b2c3" — unique pattern finding ID
+    pattern_id: string,                  // Pattern definition ID (e.g. "placeholder-only-label")
+    title: string,                       // Human-readable issue title
+    severity: string,                    // "Critical" | "Serious" | "Moderate" | "Minor"
+    status: string,                      // "confirmed" | "potential"
+    file: string,                        // Relative file path (e.g. "src/components/SearchBar.tsx")
+    line: number,                        // Line number where the pattern was found
+    match: string,                       // The matching source code line
+    context: string,                     // Surrounding code for context
+    fix_description: string,             // How to fix the pattern
+  }[],
+  summary: {
+    total: number,                       // Total findings found
+    confirmed: number,                   // Definite accessibility issues
+    potential: number,                   // Likely issues that need manual review
+  },
+}
+```
+
 ---
 
 ## Knowledge API
 
-These functions expose engine-owned content for UIs and agents to render. All accept an optional `{ locale?: string }` option (default: `"en"`).
-
 ### `getKnowledge(options?)`
 
-Returns the full knowledge pack — combines all knowledge functions into one call. Useful for pre-loading UI help content.
+Returns all accessibility knowledge in a single call. Accepts an optional `{ locale?: string }` option (default: `"en"`).
+
+This is the **only exported Knowledge API function**. The data it returns covers scanner help, persona profiles, concepts, glossary, docs, conformance levels, WCAG principles, and severity definitions — all in one call.
 
 ```ts
 import { getKnowledge } from "@diegovelasquezweb/a11y-engine";
 
 const knowledge = getKnowledge({ locale: "en" });
-
-// knowledge.scanner         → scan options help and engine descriptions
-// knowledge.personas        → persona labels, icons, descriptions
-// knowledge.concepts        → UI concept definitions
-// knowledge.glossary        → accessibility glossary
-// knowledge.conformanceLevels → WCAG A/AA/AAA definitions with axe tags
-// knowledge.wcagPrinciples  → the 4 WCAG principles
-// knowledge.severityLevels  → Critical/Serious/Moderate/Minor definitions
 ```
 
-Returns: `EngineKnowledge`
-
----
+**Returns:** `EngineKnowledge`
 
-### `getScannerHelp(options?)`
-
-Returns scan option descriptions, allowed values, and engine metadata — used to render Advanced Settings UI.
+**`EngineKnowledge` shape:**
 
 ```ts
-const help = getScannerHelp();
-// help.engines → [{ id: "axe", label: "axe-core", description: "..." }, ...]
-// help.options → [{ id: "maxRoutes", label: "Max Routes", type: "number", ... }, ...]
+{
+  locale: string,                        // "en"
+  version: string,                       // "1.0.0"
+
+  scanner: {
+    title: string,                       // "Scanner Help"
+    engines: {                           // Engine descriptions
+      id: string,                        // "axe" | "cdp" | "pa11y"
+      label: string,
+      description: string,
+    }[],
+    options: {                           // CLI/API option descriptions
+      name: string,                      // "maxRoutes"
+      type: string,                      // "number" | "string" | "boolean"
+      default: string | number | boolean,
+      description: string,
+      values?: string[],                 // Allowed values if enum-like
+    }[],
+  },
+
+  personas: {                            // Disability persona profiles
+    id: string,                          // "screenReader" | "keyboard" | "vision" | "cognitive"
+    icon: string,                        // Same as id, used for icon lookup
+    label: string,                       // "Screen Readers"
+    description: string,                 // Explanation of the persona
+    keywords: string[],                  // Keywords for matching findings
+    mappedRules: string[],               // axe rule IDs mapped to this persona
+  }[],
+
+  concepts: Record<string, {             // Concept definitions keyed by ID
+    title: string,
+    body: string,
+    context?: string,                    // When/where this concept applies
+  }>,
+
+  glossary: {                            // Accessibility term definitions
+    term: string,
+    definition: string,
+  }[],
+
+  docs: {                                // Documentation articles
+    sections: {
+      id: string,
+      title: string,
+      groups: {
+        id: string,
+        title: string,
+        articles: {
+          id: string,
+          title: string,
+          body: string,
+        }[],
+      }[],
+    }[],
+  },
+
+  conformanceLevels: {                   // WCAG A/AA/AAA definitions
+    level: string,                       // "A" | "AA" | "AAA"
+    label: string,
+    description: string,
+    axeTags: string[],                   // ["wcag2a", "wcag21a", "wcag22a"]
+  }[],
+
+  wcagPrinciples: {                      // The four WCAG principles
+    id: string,                          // "perceivable" | "operable" | "understandable" | "robust"
+    label: string,
+    description: string,
+    criterionPrefix: string,             // "1." | "2." | "3." | "4."
+  }[],
+
+  severityLevels: {                      // Severity definitions
+    level: string,                       // "Critical" | "Serious" | "Moderate" | "Minor"
+    label: string,
+    description: string,
+    order: number,                       // 1 (Critical) – 4 (Minor)
+  }[],
+}
 ```
 
 ---
 
-### `getPersonaReference(options?)`
+## Constants
 
-Returns persona labels, descriptions, and disability group definitions.
+### `VIEWPORT_PRESETS`
 
-```ts
-const ref = getPersonaReference();
-// ref.personas → [{ id: "screenReader", label: "Screen Readers", icon: "...", description: "..." }, ...]
-```
-
----
-
-### `getUiHelp(options?)`
-
-Returns shared concept definitions and a glossary of accessibility terms.
+Ready-made viewport dimensions for common device classes. Useful when building scanner UI option pickers.
 
 ```ts
-const ui = getUiHelp();
-// ui.concepts  → { wcag: "...", aria: "...", ... }
-// ui.glossary  → [{ term: "ARIA", definition: "..." }, ...]
+import { VIEWPORT_PRESETS } from "@diegovelasquezweb/a11y-engine";
+
+// VIEWPORT_PRESETS:
+// [
+//   { label: "Desktop", width: 1280, height: 800 },
+//   { label: "Laptop",  width: 1440, height: 900 },
+//   { label: "Tablet",  width: 768,  height: 1024 },
+//   { label: "Mobile",  width: 375,  height: 812 },
+// ]
 ```
 
----
-
-### `getConformanceLevels(options?)`
-
-Returns WCAG conformance level definitions with their corresponding axe-core tag sets.
-
-```ts
-const { conformanceLevels } = getConformanceLevels();
-// conformanceLevels[0] → { id: "AA", label: "WCAG 2.2 AA", axeTags: ["wcag2a", "wcag2aa", ...] }
-```
+Type: `ViewportPreset[]` — `{ label: string; width: number; height: number }[]`
 
 ---
 
-### `getWcagPrinciples(options?)`
+### `DEFAULT_AI_SYSTEM_PROMPT`
 
-Returns the four WCAG principles (Perceivable, Operable, Understandable, Robust) with criterion prefix patterns.
+The default system prompt passed to Claude for AI enrichment. Exported so consumers can read, log, or extend it when building custom AI workflows.
 
 ```ts
-const { wcagPrinciples } = getWcagPrinciples();
-// wcagPrinciples[0] → { id: "perceivable", label: "Perceivable", prefix: "1.", description: "..." }
-```
+import { DEFAULT_AI_SYSTEM_PROMPT } from "@diegovelasquezweb/a11y-engine";
 
----
+// Override for a specific scan:
+await runAudit({
+  baseUrl: "https://example.com",
+  ai: {
+    enabled: true,
+    apiKey: process.env.ANTHROPIC_API_KEY,
+    systemPrompt: DEFAULT_AI_SYSTEM_PROMPT + "\n\nFocus on Vue 3 Composition API patterns.",
+  },
+});
+```
 
-### `getSeverityLevels(options?)`
+Type: `string`
 
-Returns severity level definitions with labels, descriptions, and ordering.
+---
 
-```ts
-const { severityLevels } = getSeverityLevels();
-// severityLevels[0] → { id: "Critical", label: "Critical", order: 0, description: "..." }
-```
+> **Note on `ai_enriched_findings` fast path**: When `getFindings()` receives a payload that contains `ai_enriched_findings` and no `screenshotUrlBuilder` option is provided, it returns `ai_enriched_findings` directly without re-normalizing the raw `findings` array. If a `screenshotUrlBuilder` is provided, normalization always runs so paths can be rewritten.
 
 ---
 

package/docs/architecture.md

@@ -119,7 +119,7 @@ Output shape:
 
 Core artifacts generated by the pipeline:
 
-- `progress.json`: step status (`page`, `axe`, `cdp`, `pa11y`, `merge`, `intelligence`)
+- `progress.json`: step status — `page`, `axe`, `cdp`, `pa11y`, `merge`, `intelligence`, `repo` (remote package.json fetch), `patterns` (source pattern scan), `ai` (Claude enrichment)
 - `a11y-scan-results.json`: merged runtime scan output per route
 - `a11y-findings.json`: enriched findings payload used by reports and API consumers
 

package/docs/engine-manifest.md

@@ -49,6 +49,7 @@ This document is the current technical inventory of the engine package.
 | `assets/remediation/code-patterns.mjs` | Source code pattern definitions |
 | `assets/remediation/source-boundaries.mjs` | Framework source boundaries |
 | `assets/remediation/axe-check-maps.mjs` | axe check-to-rule mappings |
+| `assets/knowledge/knowledge.mjs` | Knowledge API data — scanner help, personas, concepts, glossary, docs, conformance levels, WCAG principles, severity definitions |
 | `assets/reporting/compliance-config.mjs` | Compliance scoring configuration |
 | `assets/reporting/wcag-reference.mjs` | WCAG + persona mapping reference |
 | `assets/reporting/manual-checks.mjs` | Manual checklist data |
@@ -62,6 +63,7 @@ Current files:
 - `tests/asset-loader.test.mjs`
 - `tests/audit-summary.test.mjs`
 - `tests/enriched-findings.test.mjs`
+- `tests/knowledge-api.test.mjs`
 - `tests/reports-api.test.mjs`
 - `tests/reports-paths.test.mjs`
 - `tests/run-audit.integration.test.mjs`

package/docs/intelligence.md

@@ -1,6 +1,6 @@
 # Intelligence & Enrichment
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Intelligence](intelligence.md) • [Testing](testing.md)
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [Intelligence](intelligence.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
 
 ---
 

package/docs/outputs.md

@@ -63,6 +63,10 @@ Real-time scan progress written by `src/pipeline/dom-scanner.mjs` as each engine
 | `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. |
+| `repo` | — | Remote `package.json` fetch via GitHub API for stack detection. Only emitted when `repoUrl` is set. |
+| `intelligence` | — | Analyzer enrichment step (fix intelligence, ownership, scoring). |
+| `patterns` | — | Source code pattern scan (local or remote). Only emitted when `projectDir` or `repoUrl` is set. `total` / `confirmed` / `potential` counts in `extra`. |
+| `ai` | Claude | AI enrichment via Anthropic API. Only emitted when `ai.enabled` is `true` and `ai.apiKey` is set. |
 
 ### Step statuses
 

package/docs/testing.md

@@ -14,7 +14,7 @@
 
 - **Framework**: Vitest
 - **Command**: `pnpm test`
-- **Current suite**: 8 files, 26 tests
+- **Current suite**: 9 files, 38 tests
 
 The suite focuses on regression protection for architecture changes, public API contracts, and critical report-generation paths.
 
@@ -32,19 +32,24 @@ The suite focuses on regression protection for architecture changes, public API
 - `tests/audit-summary.test.mjs`
 - Verifies canonicalization, normalization, sorting, effort inference, quick wins, and detected stack output.
 
-### 3) Report API and import safety
+### 3) Knowledge API
+
+- `tests/knowledge-api.test.mjs`
+- Verifies `getKnowledge()` returns the full expected shape: scanner, personas, concepts, glossary, docs, conformance levels, WCAG principles, and severity levels.
+
+### 4) Report API and import safety
 
 - `tests/reports-api.test.mjs`
 - `tests/reports-paths.test.mjs`
 - Verifies report APIs return expected output types and protects against broken relative imports after refactors.
 
-### 4) Source-pattern behavior
+### 5) Source-pattern behavior
 
 - `tests/source-patterns.test.mjs`
 - `tests/source-scanner-utils.test.mjs`
 - Verifies edge behavior for pattern filtering and source scanner utility functions.
 
-### 5) Integration tests (no network)
+### 6) Integration tests (no network)
 
 - `tests/run-audit.integration.test.mjs`
 - Mocks scanner/analyzer modules to verify:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.8.5",
+  "version": "0.10.0",
   "description": "WCAG 2.2 accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",

package/src/cli/audit.mjs

@@ -34,6 +34,7 @@ Audit Intelligence:
   --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.
+  --include-incomplete    Include axe "incomplete" items as findings.
   --exclude-selectors <csv> Exclude CSS selectors from scan.
 
 Execution & Emulation:
@@ -187,6 +188,7 @@ async function main() {
   const skipPatterns = argv.includes("--skip-patterns");
   const affectedOnly = argv.includes("--affected-only");
   const ignoreFindings = getArgValue("ignore-findings");
+  const includeIncomplete = argv.includes("--include-incomplete");
   const excludeSelectors = getArgValue("exclude-selectors");
 
   const waitUntil = getArgValue("wait-until");
@@ -290,6 +292,7 @@ async function main() {
 
     const analyzerArgs = [];
     if (ignoreFindings) analyzerArgs.push("--ignore-findings", ignoreFindings);
+    if (includeIncomplete) analyzerArgs.push("--include-incomplete");
     const resolvedFramework = framework || detectedFramework;
     if (resolvedFramework) analyzerArgs.push("--framework", resolvedFramework);
     await runScript("../enrichment/analyzer.mjs", analyzerArgs);

package/src/enrichment/analyzer.mjs

@@ -257,6 +257,7 @@ function printUsage() {
 Options:
   --output <path>          Output findings JSON path (default: .audit/a11y-findings.json)
   --ignore-findings <csv> Ignore specific rule IDs (overrides config)
+  --include-incomplete     Include axe "incomplete" items as findings
   -h, --help               Show this help
 `);
 }
@@ -276,10 +277,15 @@ function parseArgs(argv) {
     input: getInternalPath("a11y-scan-results.json"),
     output: getInternalPath("a11y-findings.json"),
     ignoreFindings: [],
+    includeIncomplete: false,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
     const key = argv[i];
+    if (key === "--include-incomplete") {
+      args.includeIncomplete = true;
+      continue;
+    }
     const value = argv[i + 1];
     if (!key.startsWith("--") || value === undefined) continue;
 
@@ -897,6 +903,7 @@ function buildFindings(inputPayload, cliArgs) {
           primary_source_scope: ownership.primarySourceScope,
           search_strategy: ownership.searchStrategy,
           component_hint: extractComponentHint(bestSelector) ?? derivePageHint(route.path),
+          needs_verification: !!v._fromIncomplete,
           verification_command: `pnpm a11y --base-url ${route.url} --routes ${route.path} --only-rule ${v.id} --max-routes 1`,
           verification_command_fallback: `node scripts/audit.mjs --base-url ${route.url} --routes ${route.path} --only-rule ${v.id} --max-routes 1`,
         });
@@ -966,12 +973,33 @@ export function collectIncompleteFindings(routes) {
 /**
  * Runs the analyzer programmatically on a scan payload.
  * @param {Object} scanPayload - The raw scan output from dom-scanner ({ routes, base_url, projectContext, ... }).
- * @param {{ ignoreFindings?: string[], framework?: string, output?: string }} [options={}]
+ * @param {{ ignoreFindings?: string[], framework?: string, output?: string, includeIncomplete?: boolean }} [options={}]
  * @returns {Object} The enriched findings payload { findings, incomplete_findings, metadata, ... }.
  */
 export function runAnalyzer(scanPayload, options = {}) {
   if (!scanPayload) throw new Error("Missing scan payload");
 
+  const sourceRoutes = scanPayload.routes || [];
+  const routesForAnalysis = options.includeIncomplete
+    ? sourceRoutes.map((route) => {
+      const incomplete = Array.isArray(route.incomplete) ? route.incomplete : [];
+      const violations = Array.isArray(route.violations) ? route.violations : [];
+      if (incomplete.length === 0) return route;
+      return {
+        ...route,
+        violations: [
+          ...violations,
+          ...incomplete.map((item) => ({ ...item, _fromIncomplete: true })),
+        ],
+      };
+    })
+    : sourceRoutes;
+
+  const scanPayloadForAnalysis =
+    routesForAnalysis === sourceRoutes
+      ? scanPayload
+      : { ...scanPayload, routes: routesForAnalysis };
+
   const args = {
     input: null,
     output: options.output || getInternalPath("a11y-findings.json"),
@@ -980,7 +1008,7 @@ export function runAnalyzer(scanPayload, options = {}) {
   };
 
   const ignoredRules = new Set(args.ignoreFindings);
-  const result = buildFindings(scanPayload, args);
+  const result = buildFindings(scanPayloadForAnalysis, args);
 
   if (ignoredRules.size > 0) {
     const knownIds = new Set(
@@ -1056,6 +1084,7 @@ function main() {
   runAnalyzer(payload, {
     ignoreFindings: args.ignoreFindings,
     framework: args.framework,
+    includeIncomplete: args.includeIncomplete,
     output: args.output,
   });
 }

package/src/index.d.mts

@@ -51,6 +51,7 @@ export interface Finding {
   source_rule_id?: string | null;
   pages_affected?: number | null;
   affected_urls?: string[] | null;
+  needs_verification?: boolean;
 }
 
 export interface EnrichedFinding {
@@ -102,6 +103,7 @@ export interface EnrichedFinding {
   checkData: Record<string, unknown> | null;
   pagesAffected: number | null;
   affectedUrls: string[] | null;
+  needsVerification?: boolean;
 }
 
 export interface SeverityTotals {
@@ -142,6 +144,7 @@ export interface AuditSummary {
 export interface ScanPayload {
   findings: Finding[] | Record<string, unknown>[];
   metadata?: Record<string, unknown>;
+  incomplete_findings?: unknown[];
 }
 
 export interface ReportOptions {
@@ -397,6 +400,7 @@ export interface RunAuditOptions {
   repoUrl?: string;
   githubToken?: string;
   skipPatterns?: boolean;
+  includeIncomplete?: boolean;
   screenshotsDir?: string;
   engines?: EngineSelection;
   ai?: AiOptions;
@@ -449,18 +453,6 @@ export function getSourcePatterns(
   options?: SourcePatternOptions
 ): Promise<SourcePatternResult>;
 
-export function getScannerHelp(options?: KnowledgeOptions): ScannerHelp;
-
-export function getPersonaReference(options?: KnowledgeOptions): PersonaReference;
-
-export function getUiHelp(options?: KnowledgeOptions): UiHelp;
-
-export function getConformanceLevels(options?: KnowledgeOptions): ConformanceLevelsResult;
-
-export function getWcagPrinciples(options?: KnowledgeOptions): WcagPrinciplesResult;
-
-export function getSeverityLevels(options?: KnowledgeOptions): SeverityLevelsResult;
-
 export function getKnowledge(options?: KnowledgeOptions): EngineKnowledge;
 
 export const DEFAULT_AI_SYSTEM_PROMPT: string;

package/src/index.mjs

@@ -161,6 +161,7 @@ function normalizeSingleFinding(item, index, screenshotUrlBuilder) {
     check_data: item.check_data && typeof item.check_data === "object" ? item.check_data : null,
     pages_affected: typeof item.pages_affected === "number" ? item.pages_affected : null,
     affected_urls: Array.isArray(item.affected_urls) ? item.affected_urls : null,
+    needs_verification: Boolean(item.needs_verification),
   };
 }
 
@@ -247,6 +248,7 @@ export function getFindings(input, options = {}) {
       checkData: finding.check_data,
       pagesAffected: finding.pages_affected,
       affectedUrls: finding.affected_urls,
+      needsVerification: finding.needs_verification,
     };
 
     // Enrich from intelligence if no fix data exists yet
@@ -379,8 +381,9 @@ function getPersonaGroups(findings) {
  * @returns {object} Full audit summary.
  */
 export function getOverview(findings, payload = null) {
+  const scorableFindings = findings.filter((f) => !f.needsVerification);
   const totals = { Critical: 0, Serious: 0, Moderate: 0, Minor: 0 };
-  for (const f of findings) {
+  for (const f of scorableFindings) {
     const severity = f.severity || "";
     if (severity in totals) totals[severity] += 1;
   }
@@ -434,7 +437,7 @@ export function getOverview(findings, payload = null) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, title: string, engines: object[], options: object[] }}
  */
-export function getScannerHelp(options = {}) {
+function getScannerHelp(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const scanner = payload.locales[locale]?.scanner || { title: "Scanner Help", engines: [], options: [] };
@@ -455,7 +458,7 @@ export function getScannerHelp(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, personas: object[] }}
  */
-export function getPersonaReference(options = {}) {
+function getPersonaReference(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const wcagRef = getWcagReference();
@@ -492,7 +495,7 @@ export function getPersonaReference(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, tooltips: Record<string, object>, glossary: object[] }}
  */
-export function getUiHelp(options = {}) {
+function getConceptsAndGlossary(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const localePayload = payload.locales[locale] || {};
@@ -518,7 +521,7 @@ export function getUiHelp(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, conformanceLevels: object[] }}
  */
-export function getConformanceLevels(options = {}) {
+function getConformanceLevels(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const levels = payload.locales[locale]?.conformanceLevels || [];
@@ -535,7 +538,7 @@ export function getConformanceLevels(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, wcagPrinciples: object[] }}
  */
-export function getWcagPrinciples(options = {}) {
+function getWcagPrinciples(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const principles = payload.locales[locale]?.wcagPrinciples || [];
@@ -552,7 +555,7 @@ export function getWcagPrinciples(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, severityLevels: object[] }}
  */
-export function getSeverityLevels(options = {}) {
+function getSeverityLevels(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const levels = payload.locales[locale]?.severityLevels || [];
@@ -573,7 +576,7 @@ export const VIEWPORT_PRESETS = [
 export function getKnowledge(options = {}) {
   const scanner = getScannerHelp(options);
   const personas = getPersonaReference(options);
-  const ui = getUiHelp(options);
+  const ui = getConceptsAndGlossary(options);
   const conformance = getConformanceLevels(options);
   const principles = getWcagPrinciples(options);
   const severity = getSeverityLevels(options);
@@ -622,6 +625,7 @@ export function getKnowledge(options = {}) {
  *   framework?: string,
  *   projectDir?: string,
  *   skipPatterns?: boolean,
+ *   includeIncomplete?: boolean,
  *   engines?: { axe?: boolean, cdp?: boolean, pa11y?: boolean },
  *   onProgress?: (step: string, status: string, extra?: object) => void,
  * }} options
@@ -691,6 +695,7 @@ export async function runAudit(options) {
   const findingsPayload = runAnalyzer(scanPayload, {
     ignoreFindings: options.ignoreFindings,
     framework: options.framework,
+    includeIncomplete: options.includeIncomplete,
   });
 
   // Step 3: Source patterns (optional) — works with local projectDir or remote repoUrl