automatica11y 0.0.0-stage → 0.3.0

package/AGENTS.md

@@ -0,0 +1,32 @@
+# automatica11y.
+
+Instructions for AI agents working in this repository or asked to use this tool. This file ships in the npm package. The guide commands below print the copy that comes with the latest release, and the steps they print check that the tool's version matches the version those steps were written for.
+
+## If you're asked to check or compare accessibility.
+
+Keep the user's request as they gave it, including the target and any settings they named, and carry it into the steps. Don't ask again for what they've already said. If the request doesn't name a target, ask for the target once, then continue with the steps. Use the defaults in the steps for any setting the user didn't name. Read the full steps and follow them exactly. They cover the version check, `doctor`, turning a request into an `audit` or `compare` command, writing fixtures for npm packages, and writing the report from `results.json`:
+
+```bash
+npx --yes automatica11y@latest guide skill
+```
+
+When the steps tell you to write a fixture, read the fixture guide:
+
+```bash
+npx --yes automatica11y@latest guide fixtures
+```
+
+If either guide command fails, stop. Report the exact error to the user, and don't produce an audit or compare result from memory. If the steps report a problem themselves, such as `doctor` finding no browser, follow what they say. If the version check in the steps reports a mismatch, stop. Report the installed version and the version the steps expect, and don't produce an audit or compare result until the user confirms how to proceed.
+
+Both print files that live in `skills/automatica11y-runner/` in the repository and in the package. If you can read those files directly, you can read them instead of running the guide commands. That's only another way to get the text. If a guide command has already failed, stop as described above. Reading the files doesn't change that. Don't work from memory or from this file alone. The steps are the single source for what to run and for how to word results.
+
+## If you're changing the code (in a checkout of the repository).
+
+- Run `npm test` (about two minutes, needs Chrome or Chromium) and `npm run lint` before you finish.
+- If `npm test` can't run because Chrome or Chromium is missing, or if either command fails, stop. Report the exact error and the command that failed, and don't report the change as complete. The browser tests skip themselves when no browser is found, so a run that prints skipped tests isn't a pass either. Report the skipped count, and don't call the change complete.
+- The code is plain ESM JavaScript with JSDoc types and no build step. It needs Node 20 or newer.
+- `src/` holds the tool. `test/` holds the tests. `test/fixtures/` holds test pages and fake packages, which are not the fixtures a user writes for an npm package.
+- Heavy dependencies (Playwright, esbuild, the rule engines) load only when a command needs them. A test checks that `--version`, `doctor`, `guide`, and `--plan` never import them.
+- Keep findings from axe-core and IBM Equal Access separate. Never add their counts together or convert one engine's scale into the other's.
+- A gap, an error, a failed target, or a result that isn't testable is a finding. It never counts as a pass. A report says "no automated violations found" only where an engine found none, and never says "accessible."
+- There are two skills. `skills/automatica11y/` is a tiny bootstrap that people copy. It sends an agent to `guide`. `skills/automatica11y-runner/` holds the full steps and ships with the tool. The runner names the version series it works with. The series is the major and minor version while the major version is 0 (`0.2`), and the major version alone from 1.0 on. Update the series named in `skills/automatica11y-runner/SKILL.md` (written like `0.2.x`) whenever the series of the version in `package.json` changes, for example from `0.2.x` to `0.3.0`. A change from `0.2.5` to `0.2.6` needs no update. A test fails if they disagree.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# automatica11y.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Test and compare the accessibility of web pages, Storybook builds, and npm component libraries.
+
+automatica11y answers two questions:
+
+- How accessible is this? (`audit`)
+- How do these compare? (`compare`, two or more targets)
+
+It's **not** an attestation or certification tool. Automated checks cover only part of WCAG, so a report says "no automated violations found" only where an engine found none, and never says "accessible." See [Limits](#limits).
+
+## Quick start.
+
+You need Node 20 or newer and Chrome or Chromium.
+
+```bash
+npx automatica11y doctor
+npx automatica11y audit https://example.com
+npx automatica11y compare radix=npm:@radix-ui/react-dialog aria=npm:react-aria-components
+```
+
+`doctor` checks your setup. If it can't find a browser, it prints the command that installs one:
+
+```bash
+npx playwright-core install --only-shell chromium
+```
+
+Each run writes a folder (`./a11y-report` by default) with `report.md`, `results.json`, and `plan.json`.
+
+## Targets.
+
+A target is `[label=]<spec>`. The label is optional, and names the target in the report.
+
+| Target | Spec |
+|---|---|
+| A live page | `https://example.com/page` |
+| A local page or site | `./page.html` or `./dist`. A path with no prefix is relative to the working folder, so `dist` means `./dist`. Prefixes `../`, `/`, `~`, and `file:` work too. |
+| A Storybook | Its URL, or a local folder with `index.json` or `stories.json`. |
+| An npm package | `npm:name`, `npm:@scope/name`, or `npm:name@version`. React and web component libraries work. |
+
+A bare word such as `button` is a path: the folder or file `./button`. Write `npm:button` to pick the package. The prefix is what chooses a package, so a folder with the same name never gets in the way. A bare word that isn't a path fails with a hint, such as "If you meant the npm package, write npm:react."
+
+A local `.html` file is served over `http://localhost`, never `file://`. A static site audits its `index.html` only.
+
+## What it checks.
+
+Three tiers run by default. Use `--tiers` to pick fewer.
+
+- **Rules.** axe-core and IBM Equal Access run side by side. They overlap, and each catches things the other misses. Their findings are reported separately and never added together. axe-core reports an impact (`minor` to `critical`). IBM reports its Toolkit level, a staged adoption scale where level 1 is essential, high-impact requirements. The two scales aren't comparable.
+- **Interactions.** Keyboard and focus checks for nine archetypes: button, link, dialog, menu, tabs, combobox, form-field, accordion, and tooltip. Each check runs on a fresh page.
+- **Virtual screen reader.** The announcements a simulated screen reader makes, recorded as data. The output is simulated. It isn't a real screen reader, and real ones announce things differently.
+
+Every result says what it ran, or why it didn't. A gap, a failure, or a result that can't be tested is a finding. It never counts as a pass.
+
+## Options.
+
+| Option | Default | What it does |
+|---|---|---|
+| `--wcag 2.0\|2.1\|2.2` | `2.2` | The WCAG version. |
+| `--level A\|AA\|AAA` | `AA` | The conformance level. IBM Equal Access has no AAA rules, so it runs its AA rules and says so. |
+| `--engine axe,ibm` | both | Which rule engines run. |
+| `--tiers rules,interactions,vsr` | all | Which tiers run. |
+| `--archetypes a,b` | all | Limit npm and Storybook targets to these archetypes. |
+| `--lib-a11y on,off` | both | For libraries with opt-in accessibility features. See [the fixture guide](skills/automatica11y-runner/references/fixtures.md). |
+| `--mapping <file>` | none | A mapping file for npm targets. |
+| `--max-stories <n>` | `200` | The Storybook story cap. The cap spreads over components. |
+| `--out <dir>` | `./a11y-report` | Where results go. |
+| `--plan` | off | Classify the targets and write `plan.json`, then stop. Nothing installs and no browser launches. |
+| `--fail-on-axe <impact>` | off | Exit 1 if axe-core reports a violation at or above `minor`, `moderate`, `serious`, or `critical`. |
+| `--fail-on-ibm <1\|2\|3>` | off | Exit 1 if IBM reports a violation at or below that Toolkit level. |
+| `--fail-mode any\|all` | `any` | `any` trips when either engine's check trips. `all` trips only when both do, on the same target. |
+
+Run `automatica11y run --plan <plan.json>` to repeat a saved plan. It warns if tool versions have changed.
+
+## Output.
+
+- `report.md` is a complete report, written without any model. It opens with a coverage matrix, then lists findings, then ends with a method note.
+- `results.json` holds everything, including element selectors and announcement logs.
+- `plan.json` records what ran and the resolved tool and package versions.
+- `mapping.json` appears for npm targets. See below.
+
+## Exit codes.
+
+| Code | Meaning |
+|---|---|
+| 0 | The run completed. Findings don't change this unless a fail flag is set. |
+| 1 | The run completed and a fail check tripped. |
+| 2 | The command line was wrong. |
+| 3 | An environment problem, such as a missing browser or an old Node. The message says how to fix it. |
+| 4 | No target produced results. |
+
+One failing target doesn't stop a comparison. It's recorded with its reason, and the others run.
+
+## npm packages and fixtures.
+
+The tool installs each package into its own temporary folder (with install scripts turned off), loads it in the browser, and finds its exports or custom elements. It writes its guesses to `mapping.json`.
+
+It builds `button` and `link` tests on its own. Every other archetype is built from parts that differ by library (`Dialog.Root`, `Dialog.Trigger`, and so on), so it needs a **fixture**: a small file you or your agent write, following [the fixture guide](skills/automatica11y-runner/references/fixtures.md). Put fixtures at `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) and run again. An archetype without a fixture is a gap in the report.
+
+Fixtures are code that the tool bundles and runs in a browser on your machine. Write them from the library's documentation, and read ones you didn't write.
+
+## Use it with an AI agent.
+
+The tool prints its own guidance, so any agent that can run `npx` can learn to use it:
+
+```bash
+npx automatica11y@latest guide           # where to start (the AGENTS.md file)
+npx automatica11y@latest guide skill     # the full steps: build the command, run it, write the report
+npx automatica11y@latest guide fixtures  # how to write the fixtures an npm package needs
+```
+
+The guidance ships with the tool, so it always matches the version you run. Tell your agent to run `npx automatica11y@latest guide` and follow it, then ask for things like "How accessible is Radix Dialog?" or "Compare the accessibility of React Aria and Headless UI." The agent needs to run shell commands and read and write files. Nothing here is tied to one agent.
+
+**Skills.** If your agent loads skills from a folder, copy [`skills/automatica11y`](skills/automatica11y) into it. That's one small file, `SKILL.md`. It advertises the tool to the agent, and sends it to `guide`. It names no version, so it doesn't go stale. The full steps are the [`automatica11y-runner`](skills/automatica11y-runner) skill, which ships in the package and is what `guide skill` prints. Copy it too if you want the steps available without the network.
+
+**AGENTS.md.** [`AGENTS.md`](AGENTS.md) is for agents that read it but don't load skills. It points to the same steps, and tells contributors how to run and change the code.
+
+## Limits.
+
+- Automated rules find only part of what WCAG covers. They can't judge whether alt text is meaningful, whether link and heading text make sense in context, cognitive load, real focus and reading order in use, or how real screen readers behave. A person has to check those.
+- Components are tested in the states a fixture shows. Dialogs, menus, tooltips, and comboboxes run closed and open. Other states aren't visited.
+- Content on a canvas with no alternative, or inside a closed shadow root, can't be tested, and the report says so. The virtual screen reader can't read inside shadow roots at all.
+- Vue, Svelte, Angular, and other frameworks report "unsupported framework."
+- Native screen readers aren't part of this version.
+- Results are a snapshot. The tools run at their latest versions, and the report records them.
+
+## Using it in CI.
+
+```bash
+npx automatica11y audit ./dist --fail-on-axe serious --fail-on-ibm 1 --fail-mode any
+```
+
+The run exits 1 when the check trips. Needs-review items never trip it.
+
+## License.
+
+MIT. See [LICENSE](LICENSE).

package/bin/automatica11y.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "automatica11y",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Test and compare the accessibility of web pages, Storybook builds, and npm component libraries.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "automatica11y": "bin/automatica11y.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "AGENTS.md",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "tsc -p jsconfig.json",
+    "prepublishOnly": "npm run lint"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@guidepup/virtual-screen-reader": "^0.33.0",
+    "accessibility-checker-engine": "^4.0.34",
+    "axe-core": "^4.14.0",
+    "esbuild": "^0.28.2",
+    "playwright-core": "^1.64.0",
+    "valibot": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "axe-core",
+    "testing",
+    "storybook",
+    "web-components",
+    "react"
+  ]
+}

package/skills/automatica11y/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: automatica11y
+compatibility: Needs Node 20 or newer, a shell that can run npx, and network access to the npm registry.
+description: Test and compare web accessibility. Use when someone asks how accessible a web page, Storybook, or npm component library is, asks for an accessibility or WCAG check or audit, or asks to compare the accessibility of two or more sites or component libraries (for example "how accessible is Radix Dialog?" or "compare React Aria and Headless UI").
+---
+
+# automatica11y
+
+automatica11y tests and compares web accessibility. This skill only gets you started. The full steps ship with the tool, so they always match its version.
+
+1. Check `node --version`. It must be 20 or newer. If it isn't, tell the user and stop. If the command fails or prints no version number, tell the user that Node.js 20 or newer couldn't be verified, include the error text, and stop.
+2. Keep the user's request as they gave it: the target or targets, and any settings they named, such as a WCAG version or level. You'll apply them after you read the guide.
+3. Run this, read all of what it prints, and follow it:
+
+   ```bash
+   npx --yes automatica11y@latest guide
+   ```
+
+   If the command exits with an error or prints no usable output, tell the user it failed, include the error text, and stop. Don't continue with partial instructions.
+
+   After reading the guide and the steps it sends you to, pass only settings they list as supported. If the user named a setting they don't list as supported, tell the user which setting is unsupported, list the supported values from the guide, and ask which to use. Don't ask again for anything they've already said.
+
+4. If you can't run shell commands, or `npx` can't reach the npm registry, tell the user and stop. Don't guess at results.

package/skills/automatica11y-runner/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: automatica11y-runner
+compatibility: Needs Node 20 or newer, Chrome or Chromium, a shell that can run npx, and network access to the npm registry.
+description: The full steps for running automatica11y audits and comparisons, from building the command to writing the report. Use it when the automatica11y skill or AGENTS.md sends you here, or when you've already been told to run automatica11y and need the steps.
+---
+
+# automatica11y runner
+
+This skill turns a request into an `automatica11y` command, runs it, and writes a report from the results. The tool does the testing. This skill never guesses at results.
+
+It's plain Markdown, and it isn't tied to one agent. It needs an agent that can run shell commands (including `npx`) and read and write files. Paths such as `references/fixtures.md` are relative to this file.
+
+The tool is **not** an attestation or certification tool. Automated checks cover only part of WCAG. Never say a target is "accessible" or "compliant." Where an engine reports zero violations for a target, say "no automated violations found" for that engine. Where it reports violations, list them as the tool reports them, and don't use that phrase for that engine.
+
+## 1. Check the version
+
+This skill works with automatica11y **0.2.x**. Run:
+
+```bash
+npx --yes automatica11y@latest --version
+```
+
+If the command exits with an error or prints nothing, tell the user it failed, include the error text, and stop. If the output doesn't start with `0.2.`, stop. Tell the user the version you got and the series this copy expects (`0.2.x`). If this copy came from a file, offer to read the matching steps with `npx --yes automatica11y@latest guide skill`. Don't run an audit until the user confirms how to proceed.
+
+## 2. Check the setup
+
+```bash
+npx --yes automatica11y@latest doctor
+```
+
+Relay any fix it prints, then stop until the user has applied it. Exit code 3 means a problem with the environment: Node older than 20, or no Chrome or Chromium. Don't install or configure anything yourself. That logic lives in the tool.
+
+## 3. Turn the request into a command
+
+Only two commands run audits:
+
+```bash
+npx --yes automatica11y@latest audit <target> [options]
+npx --yes automatica11y@latest compare <target> <target> [<target>...] [options]
+```
+
+Use `audit` for one target and `compare` for two or more. A target is `[label=]<spec>`. The label is optional and names the target in the report.
+
+| The user means | The spec is |
+|---|---|
+| A live page | `https://example.com/page` |
+| A local page or site | `./page.html` or `./dist`. A path with no prefix is relative to the working folder. |
+| A Storybook | its URL, or a local folder with `index.json` |
+| An npm package | `npm:name`, `npm:@scope/name`, or `npm:name@version` |
+
+A bare word such as `button` is a path: the folder or file `./button`. Always write an npm package with the `npm:` prefix. If a word could mean a package or a folder, ask the user which one before you run anything.
+
+Options you can set, and nothing else:
+
+| Option | Default | Use it when |
+|---|---|---|
+| `--wcag 2.0\|2.1\|2.2` | `2.2` | The user names a WCAG version. |
+| `--level A\|AA\|AAA` | `AA` | The user names a level. IBM Equal Access has no AAA rules, so it runs its AA rules and says so. |
+| `--engine axe,ibm` | both | The user wants one rule engine. |
+| `--tiers rules,interactions,vsr` | all three | The user wants fewer checks. |
+| `--archetypes a,b` | all | The user cares about some components. Choose from button, link, dialog, menu, tabs, combobox, form-field, accordion, tooltip, chart. |
+| `--lib-a11y on,off` | both | Only for libraries with opt-in accessibility features. |
+| `--mapping <file>` | none | You wrote or edited a mapping file. |
+| `--max-stories <n>` | 200 | A large Storybook. |
+| `--out <dir>` | `./a11y-report` | The user names a folder. |
+| `--plan` | off | You want to see how targets classify without running anything. |
+| `--fail-on-axe <impact>` | off | CI-style gating on axe impact (`minor`, `moderate`, `serious`, `critical`). |
+| `--fail-on-ibm <1\|2\|3>` | off | Gating on IBM Toolkit level. |
+| `--fail-mode any\|all` | `any` | How to combine the two fail flags. |
+
+Use the target and the settings the user already gave, and ask only for what's missing. If the user doesn't name a target to test (a URL, a Storybook, a local page or site, or an npm package), ask for one before you run anything. Don't pick a target for them.
+
+Pass only the options in the table above, with the values it lists. If the user names a setting the tool doesn't have, or a value outside those lists (for example, WCAG 3.0), tell them which setting is unsupported, list the supported values, and ask which to use. Don't substitute a default or invent a value.
+
+Show the user the exact command before you run it. If a target is ambiguous, ask one question, then go on.
+
+Don't set the fail flags unless the user asks for gating. They change the exit code. They don't change the results.
+
+## 4. npm packages need fixtures
+
+A package's components can't be guessed from its name. The first run installs the package, loads it in the browser, finds its exports (or custom elements), and writes a candidate mapping to `<out>/mapping.json`. It tests `button` and `link` from a template. Every other archetype needs a **fixture**, a small file that assembles the component the way the library intends.
+
+1. Run the audit once. Read `<out>/mapping.json` and the report's **Archetypes** table.
+2. Treat the mapping as a guess. Check each `export` or `tag` against what the user asked about.
+3. For each archetype marked `needs-fixture` that matters to the request, write `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) in the working directory. Follow the contract and the examples below. `references/fixtures.md` has more: the mapping file, states, and library accessibility options. It should sit next to this file. If you can't open it, run `npx --yes automatica11y@latest guide fixtures` to print it. The contract here is enough for the first fixture.
+4. Run the same command again. The tool finds fixtures in that folder without `--mapping`.
+5. Don't invent fixtures for archetypes the user didn't ask about. A gap is an honest result.
+
+**The fixture contract, in brief.**
+
+- The default export renders the archetype in its starting state. For web components, the default export is the function `mount(container)`.
+- Mark **exactly one** element `data-a11y-trigger`. It's what a person would focus and activate. If nothing can be activated, as with a chart, put both attributes on the same outermost element.
+- Mark the main surface `data-a11y-root`, on the element that carries the role (`dialog`, `menu`, `tooltip`), not on an overlay or portal wrapper. It may appear only after the trigger fires, and it may render in a portal.
+- Mount without console errors. Don't import CSS.
+- The attributes have to reach the DOM. If a component drops unknown props, use the library's documented way to render your own element in its place (such as `asChild` in Radix, or the `as` prop in Headless UI), and mark that element. If the library has none, leave the archetype as a gap. Don't wrap the library's component in an element you add and mark that.
+
+A React fixture. JSX works without importing React. Import the library from its package name, and the tool installs it:
+
+```jsx
+import * as Dialog from "@radix-ui/react-dialog";
+
+export default function Fixture() {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger data-a11y-trigger>Open dialog</Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content data-a11y-root>
+          <Dialog.Title>Edit profile</Dialog.Title>
+          <Dialog.Description>Update your details.</Dialog.Description>
+          <Dialog.Close>Close</Dialog.Close>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+```
+
+A web component fixture. The tool imports the package first, so its elements are defined before `mount` runs. The `data-a11y-trigger` and `data-a11y-root` attributes can sit on a host, a slotted child, or an element inside an open shadow root. A closed shadow root hides its content from every tool:
+
+```js
+export default function mount(container) {
+  container.innerHTML = `
+    <my-dialog>
+      <button slot="trigger" data-a11y-trigger type="button">Open</button>
+      <div slot="content" data-a11y-root role="dialog" aria-label="Details">...</div>
+    </my-dialog>`;
+}
+```
+
+Fixtures are code that the tool bundles and runs in a browser on the user's machine. Write them from the library's public documentation. If the documentation doesn't cover the API you need, don't guess, and don't stand in a plain element for the library's component, which would test the element and not the library. Leave the archetype as a gap and tell the user what you couldn't find. Tell the user the files exist and where. Package installs run with scripts turned off.
+
+If the user asked for a comparison, give every target the same archetypes.
+
+## 5. Run, then read the results
+
+Run the command. Note the exit code:
+
+| Code | Meaning |
+|---|---|
+| 0 | The run completed. Findings don't change this unless a fail flag was set. |
+| 1 | The run completed and a fail flag tripped. |
+| 2 | The command was wrong. Read the message, fix it, and run again. |
+| 3 | An environment problem. Relay the fix. |
+| 4 | No target produced results. Say why, from `results.json`. |
+
+Then read `<out>/results.json`. It's the source for everything you write. Read `<out>/report.md` too. It's a complete report the tool wrote on its own.
+
+## 6. Write the report
+
+Write the narrative from `results.json`. Never write from memory, and never repeat a number you didn't read.
+
+1. Put the run date and tool versions first. Say that results are a snapshot.
+2. For a comparison, say that every target used the same archetypes, WCAG version, level, and rules.
+3. Open with the coverage matrix (target by archetype by tier). Then give the findings.
+4. Keep violations, needs-review items, and passes in separate lists. Never merge them.
+5. Break findings out by archetype and by impact.
+6. Use "no automated violations found" only for an engine that reported none for that target. For an engine that reported violations, list them as the tool reports them. Never say "accessible," "compliant," or "passes WCAG."
+7. Don't print a single score. If someone insists, pair any number with the coverage matrix and the automated-coverage caveat.
+8. Label virtual screen reader output **simulated**. Label library accessibility options **on** or **off** on every result that has one.
+9. Treat a gap, a not-testable result, an error, or a failed target as a finding. It never counts as a pass.
+10. If the comparison mixes component targets and page targets, open with a warning that the evidence isn't equivalent.
+11. Label every rule finding with its engine. Report axe-core and IBM Equal Access separately. Never add their counts together. Impact is axe-core's own label. IBM Toolkit level is IBM's staged adoption scale (1 is essential, high-impact requirements). Don't convert one into the other.
+12. End with a plain method note. Say what automated tools can't catch: whether alt text is meaningful, whether link and heading text make sense in context, cognitive load, real focus and reading order in use, and how real screen readers behave. Those need a person.
+
+Use the structure of `report.md`. Quote selectors and rule IDs exactly as `results.json` has them.
+
+## 7. When a target can't be tested
+
+Say these things plainly. Don't soften them, and don't fill in a result.
+
+- **Unsupported framework.** The package needs a framework other than React or web components. Name it. v1 covers React and web components.
+- **Not applicable.** The package has no rendering surface, such as a utility library. There's nothing to test.
+- **Not testable.** The content is a canvas with no alternative, or sits in a closed shadow root. The rule engines can't see it, so the result is untested, not clean. The virtual screen reader also can't read open shadow roots.
+- **Gap.** The archetype has no usable fixture or no matching export. Say what the archetype needs.
+- **Error.** An interaction check couldn't finish. It's untested, not failed.
+- **Failed target.** The target can't be reached, isn't a web page, or couldn't be built. The tool records it as failed with a reason. Tell the user which target failed, using the reason from `results.json`. Don't retry with guesses. If every target failed (exit code 4), stop. If others ran, report them, and list the failed target as a gap in coverage.
+
+## 8. Stay out of setup
+
+Anything about installing, configuring, or repairing tools belongs to the tool. If `doctor` doesn't cover it, tell the user what failed and stop.

package/skills/automatica11y-runner/references/fixtures.md

@@ -0,0 +1,59 @@
+# Writing fixtures
+
+A fixture renders one archetype (a dialog, a set of tabs, a menu) in its starting state, so the tool can test it. You write one when the tool can't build the component from a template. The tool only fills in `button` and `link`.
+
+Write fixtures from the library's public documentation. Don't copy from memory when you aren't sure of the API. If the documentation doesn't cover the API you need, or you can't read it, don't guess. Leave the archetype without a fixture, so the report lists it as a gap, and tell the user what you couldn't find. Don't stand in a plain element for the library's component. That would test the plain element, and the result would say nothing about the library.
+
+## Where fixtures go
+
+`fixtures/<target id>/<archetype>.jsx` for React, in the working folder: the folder where you run `automatica11y audit` or `automatica11y compare`. Use `.js` for web components. The target id is the label (`radix=npm:@radix-ui/react-dialog` has the id `radix`), or the package name with `/` turned into `-`, such as `radix-ui-react-dialog`. The report's **Targets** list shows each id.
+
+To keep a fixture somewhere else, name it in a mapping file and pass `--mapping`:
+
+```json
+{
+  "radix": {
+    "dialog": { "fixture": "my-fixtures/radix-dialog.jsx" },
+    "button": { "export": "Button" }
+  }
+}
+```
+
+The keys are target ids, then archetypes. `export` (React) or `tag` (web components) changes which export or element a template uses.
+
+## The contract
+
+1. The file's default export renders the archetype in its **initial state**.
+2. Mark **exactly one** element with `data-a11y-trigger`. This is what a person would focus and activate: the button that opens a dialog, the first tab, the combobox input, the form control. If nothing in the archetype can be activated, as with a chart, put `data-a11y-trigger` and `data-a11y-root` on the same element: the outermost one the library renders.
+3. Mark the **primary surface** with `data-a11y-root`. Put it on the element that carries the role (`role="dialog"`, `role="menu"`, `role="tooltip"`), not on an overlay or a portal wrapper. It's fine if the root doesn't exist until the trigger fires, and fine if it renders in a portal. The tool looks in the whole document.
+4. Mount without console errors. The tool treats errors as a broken fixture.
+5. Don't import CSS. The tool doesn't link it.
+6. Include every part the library's documentation marks as required (for example, a dialog's title and description), so the component doesn't log warnings.
+
+The attributes have to reach the DOM. Pass `data-a11y-trigger` to the component that renders the real element. If a component drops unknown props, use the library's documented way to render your own element in its place (for example, `asChild` in Radix, or the `as` prop in Headless UI), and put the attribute on that native element. If the library has no such way, leave the archetype as a gap. Don't wrap the library's component in an element you add and mark that element, because the fixture would then test your element and not the library.
+
+## Examples
+
+A React example and a web component example are in `SKILL.md`, in the section on npm packages. They follow the contract above.
+
+For React, JSX works without importing React. Import the library from its package name. The tool installs it for you.
+
+For web components, make `mount(container)` the file's default export. It adds the archetype to the container. The tool imports the package first, so its elements are defined before `mount` runs. The `data-a11y-trigger` and `data-a11y-root` attributes can sit on a host element, a slotted child, or an element inside an **open** shadow root. A **closed** shadow root hides its content from every tool, so the report lists it as not testable.
+
+## Library accessibility options
+
+Some libraries ship accessibility features you have to switch on (a chart library's accessibility module, for example). Declare it at the archetype level in the mapping file, next to `fixture` or `export`, for example `{ "charts": { "chart": { "libA11y": true } } }`. The first key is the target id, and the second is the archetype. The fixture then receives a `libA11y` value, `true` or `false`. In React it's a prop. In web components it's a second argument, `mount(container, { libA11y })`. The tool runs the fixture both ways with `--lib-a11y on,off` and labels each result.
+
+```jsx
+export default function Fixture({ libA11y }) {
+  return <Chart data-a11y-trigger data-a11y-root accessibility={libA11y} />;
+}
+```
+
+## States
+
+For a dialog, menu, tooltip, or combobox, the tool tests the closed state, then activates the trigger and tests the open state. For an accordion it tests collapsed, then expanded. The tool activates the trigger by clicking it. For a tooltip it focuses the trigger instead, so a tooltip has to open on focus. If it opens only on pointer hover, the open state never appears. Make sure activating the trigger really opens the surface, and that the element with `data-a11y-root` is then attached to the document, isn't `display: none` or `hidden`, and isn't `visibility: hidden`. The tool also counts the surface as open if the trigger has `aria-expanded="true"`. If neither holds, the open state is reported as failed, with the reason. The interaction checks also press keys and hover, but they don't change how the open state is reached.
+
+## Check your fixture
+
+Run the audit and look at the report's **Archetypes** table. `ran` means it worked. A `gap` row says what went wrong, such as "didn't render an element with data-a11y-trigger" or "didn't bundle." Fix the file and run again.

package/src/cli.js

@@ -0,0 +1,49 @@
+import { auditCommand } from "./commands/audit.js";
+import { compareCommand } from "./commands/compare.js";
+import { EXIT, UsageError, runSavedPlan, usage } from "./commands/common.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { guideCommand } from "./commands/guide.js";
+import { ownVersion } from "./env/versions.js";
+
+const COMMANDS = {
+  audit: auditCommand,
+  compare: compareCommand,
+  run: runSavedPlan,
+  doctor: doctorCommand,
+  guide: guideCommand,
+};
+
+/**
+ * Run the CLI and return its exit code. Takes its streams and environment as arguments so tests can drive it.
+ * @param {string[]} argv Arguments after the program name.
+ * @param {Partial<import("./commands/common.js").Io>} [overrides]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, overrides = {}) {
+  /** @type {import("./commands/common.js").Io} */
+  const io = { stdout: process.stdout, stderr: process.stderr, cwd: process.cwd(), env: process.env, ...overrides };
+  const [first, ...rest] = argv;
+
+  if (first === "--version" || first === "-v") {
+    io.stdout.write(`${ownVersion()}\n`);
+    return EXIT.OK;
+  }
+  if (first === "--help" || first === "-h") {
+    io.stdout.write(usage());
+    return EXIT.OK;
+  }
+  const handler = first ? COMMANDS[/** @type {keyof typeof COMMANDS} */ (first)] : undefined;
+  if (!handler) {
+    io.stderr.write(first ? `Unknown command "${first}".\n\n${usage()}` : usage());
+    return EXIT.USAGE;
+  }
+  try {
+    return await handler(rest, io);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.stderr.write(`${error.message}\n\nRun "automatica11y ${first} --help" for options.\n`);
+      return EXIT.USAGE;
+    }
+    throw error;
+  }
+}

package/src/commands/audit.js

@@ -0,0 +1,4 @@
+import { runCommand } from "./common.js";
+
+/** @param {string[]} argv @param {import("./common.js").Io} io */
+export const auditCommand = (argv, io) => runCommand("audit", argv, io);