td-ai-tools 1.1.8 → 1.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/README.md

@@ -1,8 +1,10 @@
 # skills
 
 ## Available Skills
+- `a11y-audit`: Run script-driven accessibility audits for user-provided URLs with Axe Core and Playwright, targeting…
 - `barrage`: Convert a group of Basecamp todos or cards into a td-barrage queue.json task file.
 - `basecamp`: Interact with Basecamp via the Basecamp CLI.
+- `browser-validation`: Before completing a task validate frontend or template changes in a real browser with the Playwright-CLI…
 - `cache-reset`: Clear and warm Laravel and Statamic caches (including Statamic Glide image caches) after content or template…
 - `car-ticket-generator`: Generate a ticket for the codex-auto-runner queue
 - `everhour-basecamp-estimates`: Bulk update Everhour task estimates from a Basecamp todo or todolist URL, then append bracketed hours to the…

package/skills/a11y-audit/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: a11y-audit
+description: Run script-driven accessibility audits for user-provided URLs with Axe Core and Playwright, targeting baseline or WCAG thresholds such as WCAG 2.1 AA or WCAG 2.2 AA. Use when Codex is asked to audit a page/site for accessibility, produce a prioritized list of required accessibility changes, identify WCAG/Axe violations, or perform manual accessibility review with playwright-cli.
+---
+
+# A11y Audit
+
+## Workflow
+
+1. Run the Axe audit script first. Keep dependencies local to this skill directory.
+
+```bash
+cd .agents/skills/a11y-audit
+npm run setup
+node scripts/audit.js "https://example.com" --threshold wcag22aa
+```
+
+If the user does not name a threshold, use `baseline`. Accepted thresholds: `baseline`, `wcag2a`, `wcag2aa`, `wcag21aa`, `wcag22aa`. The script also accepts multiple URLs and `--tags` for custom Axe tag filters.
+
+2. Read the generated Markdown report path printed by the script. Use it as the primary source of automated findings and required changes.
+
+3. If the report includes `Manual review required`, review those items with `$playwright-cli`. Use browser snapshots, keyboard navigation, screenshots, and targeted page evaluation as needed. Do not guess outcomes for manual-only criteria.
+
+4. Return the final audit as a concise remediation list:
+- Automated failures from Axe that must be fixed.
+- Manual-review failures confirmed with `playwright-cli`.
+- Manual checks that could not be completed, with the blocker and exact next action.
+- Threshold tested, URL(s), viewport(s), and report artifact paths.
+
+## Script
+
+Use `scripts/audit.js` for deterministic collection. It:
+- launches Chromium through Playwright;
+- injects Axe Core from the skill-local dependency;
+- audits desktop and mobile viewports by default;
+- writes `report.md`, `results.json`, and `manual-review.json`;
+- groups issues by impact, rule, WCAG tags, affected nodes, and suggested remediation;
+- lists Axe `incomplete` results and threshold-specific human checks for manual review.
+
+Exit code `2` means the audit completed and found violations or manual-review items. Treat it as a findings signal, not a runner failure.
+
+Useful options:
+
+```bash
+node scripts/audit.js URL [URL ...]
+node scripts/audit.js URL --threshold wcag22aa --out ./a11y-report
+node scripts/audit.js URL --viewport desktop --viewport 390x844
+node scripts/audit.js URL --tags wcag2a,wcag2aa,wcag21aa,wcag22aa
+node scripts/audit.js URL --wait-until networkidle --timeout 45000
+```
+
+## Manual Review With playwright-cli
+
+Use `playwright-cli` only after the script flags manual review or the user asks for deeper investigation. Typical checks:
+- Keyboard path: `Tab`, `Shift+Tab`, `Enter`, `Space`, `Escape`; confirm logical order, visible focus, no traps, and operable controls.
+- Screen-reader semantics proxy: inspect snapshots for names, roles, headings, landmarks, labels, and state changes.
+- Visual checks: screenshots for focus indication, responsive reflow, text spacing, content on hover/focus, contrast edge cases, and motion/animation behavior.
+- Forms and dynamic UI: submit invalid states, open menus/dialogs, expand accordions, trigger errors, and verify announcements or visible status messages.
+
+Close browser sessions when finished.

package/skills/a11y-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "A11y Audit"
+  short_description: "Run Axe Core audits with manual review guidance."
+  default_prompt: "Use $a11y-audit to audit the provided URL against WCAG 2.2 AA."

package/skills/a11y-audit/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "a11y-audit-skill",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Local dependencies for the a11y-audit Codex skill.",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "scripts": {
+    "audit": "node scripts/audit.js",
+    "setup": "bash scripts/setup.sh"
+  },
+  "dependencies": {
+    "axe-core": "^4.10.3",
+    "playwright": "^1.52.0"
+  },
+  "devDependencies": {}
+}

package/skills/a11y-audit/scripts/audit.js

@@ -0,0 +1,624 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SKILL_ROOT = path.resolve(__dirname, '..');
+if (!process.env.PLAYWRIGHT_BROWSERS_PATH) {
+  process.env.PLAYWRIGHT_BROWSERS_PATH = path.join(SKILL_ROOT, '.ms-playwright');
+}
+
+const HELP = `
+Usage:
+  node scripts/audit.js URL [URL ...] [options]
+
+Options:
+  --threshold <name>       baseline | wcag2a | wcag2aa | wcag21aa | wcag22aa
+                           Default: baseline
+  --tags <csv>             Custom axe tags, overriding --threshold.
+  --viewport <preset|WxH>  desktop, mobile, tablet, or e.g. 390x844.
+                           May be repeated. Default: desktop,mobile
+  --out <dir>              Output directory. Default: ./a11y-audit-<timestamp>
+  --wait-until <state>     load | domcontentloaded | networkidle. Default: networkidle
+  --timeout <ms>           Navigation timeout. Default: 30000
+  --include-passes         Include passed/inapplicable results in results.json.
+  --help                   Show this help.
+`;
+
+const THRESHOLDS = {
+  baseline: null,
+  wcag2a: ['wcag2a'],
+  wcag2aa: ['wcag2a', 'wcag2aa'],
+  wcag21aa: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'],
+  wcag22aa: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa']
+};
+
+const VIEWPORTS = {
+  desktop: { name: 'desktop', width: 1440, height: 1000 },
+  mobile: { name: 'mobile', width: 390, height: 844, isMobile: true },
+  tablet: { name: 'tablet', width: 768, height: 1024, isMobile: true }
+};
+
+const MANUAL_CHECKS = {
+  baseline: [
+    {
+      id: 'keyboard-operable',
+      title: 'Keyboard operation and focus path',
+      wcag: ['2.1.1', '2.1.2', '2.4.3', '2.4.7'],
+      review: 'Use Tab, Shift+Tab, Enter, Space, and Escape to confirm all interactive elements are reachable, usable, visibly focused, and do not trap focus.'
+    },
+    {
+      id: 'meaningful-structure',
+      title: 'Meaningful reading and heading order',
+      wcag: ['1.3.1', '1.3.2', '2.4.6'],
+      review: 'Inspect headings, landmarks, labels, and DOM order against the visual layout and page purpose.'
+    },
+    {
+      id: 'dynamic-state-announcements',
+      title: 'Dynamic content and status changes',
+      wcag: ['4.1.3'],
+      review: 'Trigger menus, filters, validation, async loading, dialogs, and notifications; confirm state changes are exposed visibly and semantically.'
+    }
+  ],
+  wcag2a: [
+    {
+      id: 'non-text-alternatives-quality',
+      title: 'Quality of text alternatives',
+      wcag: ['1.1.1'],
+      review: 'Confirm image, icon, chart, media, and control alternatives communicate equivalent purpose, not just that an alt attribute exists.'
+    },
+    {
+      id: 'media-alternatives',
+      title: 'Captions, transcripts, and audio descriptions',
+      wcag: ['1.2.1', '1.2.2', '1.2.3'],
+      review: 'Inspect prerecorded audio/video for required captions, transcripts, or audio description equivalents.'
+    },
+    {
+      id: 'sensory-and-color',
+      title: 'Instructions do not rely only on sensory traits or color',
+      wcag: ['1.3.3', '1.4.1'],
+      review: 'Check instructions, errors, charts, and required states for text or programmatic cues beyond color, shape, size, sound, or position.'
+    },
+    {
+      id: 'keyboard-operable',
+      title: 'Keyboard operation and focus path',
+      wcag: ['2.1.1', '2.1.2', '2.4.3', '2.4.7'],
+      review: 'Use Tab, Shift+Tab, Enter, Space, and Escape to confirm all interactive elements are reachable, usable, visibly focused, and do not trap focus.'
+    },
+    {
+      id: 'timing-pausing-flashing',
+      title: 'Timing, moving content, and flashing',
+      wcag: ['2.2.1', '2.2.2', '2.3.1'],
+      review: 'Check time limits, auto-updating regions, moving content, carousels, and flashes for required pause/stop/extend controls and flash safety.'
+    },
+    {
+      id: 'meaningful-navigation',
+      title: 'Bypass blocks, page title, link purpose, headings, and labels',
+      wcag: ['2.4.1', '2.4.2', '2.4.4', '2.4.6'],
+      review: 'Confirm repeated navigation can be bypassed and that titles, links, headings, and labels describe purpose in context.'
+    },
+    {
+      id: 'forms-errors-names',
+      title: 'Forms, errors, names, roles, and values',
+      wcag: ['3.3.1', '3.3.2', '4.1.2'],
+      review: 'Submit forms and inspect widgets for clear labels, visible error identification, instructions, names, roles, values, and state changes.'
+    }
+  ],
+  wcag2aa: [
+    {
+      id: 'live-media-and-audio-description',
+      title: 'Live captions and prerecorded audio description',
+      wcag: ['1.2.4', '1.2.5'],
+      review: 'Inspect live media and prerecorded video for captions and audio description where applicable.'
+    },
+    {
+      id: 'orientation-reflow-resize',
+      title: 'Orientation, resize, and reflow',
+      wcag: ['1.3.4', '1.4.4', '1.4.10'],
+      review: 'Resize to 320 CSS px width, zoom to 200%, and rotate viewport; confirm content and functionality remain available without two-dimensional scrolling except where allowed.'
+    },
+    {
+      id: 'visual-contrast-and-spacing',
+      title: 'Contrast, non-text contrast, and text spacing',
+      wcag: ['1.4.3', '1.4.11', '1.4.12'],
+      review: 'Check text, focus indicators, icons, component boundaries, charts, and custom text spacing. Verify edge cases Axe cannot compute from CSS or images.'
+    },
+    {
+      id: 'hover-focus-content',
+      title: 'Content on hover or focus',
+      wcag: ['1.4.13'],
+      review: 'Open tooltips, popovers, menus, and hover cards; confirm content is dismissible, hoverable, and persistent while needed.'
+    },
+    {
+      id: 'multiple-ways-consistent-navigation',
+      title: 'Multiple ways and consistency',
+      wcag: ['2.4.5', '3.2.3', '3.2.4'],
+      review: 'Confirm pages can be found through more than one method where applicable and repeated navigation/components behave consistently.'
+    },
+    {
+      id: 'error-suggestion-prevention',
+      title: 'Error suggestion and prevention',
+      wcag: ['3.3.3', '3.3.4'],
+      review: 'Test validation and critical submissions for actionable suggestions, review, confirmation, or reversal where required.'
+    }
+  ],
+  wcag22aa: [
+    {
+      id: 'focus-not-obscured',
+      title: 'Focus not obscured',
+      wcag: ['2.4.11', '2.4.12'],
+      review: 'Tab through sticky headers, cookie banners, dialogs, and overlays; confirm focused controls are not hidden behind other content.'
+    },
+    {
+      id: 'dragging-target-size',
+      title: 'Dragging alternatives and target size',
+      wcag: ['2.5.7', '2.5.8'],
+      review: 'Check drag/drop and small pointer targets for single-pointer alternatives and minimum target spacing/size exceptions.'
+    },
+    {
+      id: 'consistent-help-redundant-entry-accessible-auth',
+      title: 'Help, redundant entry, and accessible authentication',
+      wcag: ['3.2.6', '3.3.7', '3.3.8'],
+      review: 'Inspect forms, login, checkout, and support paths for consistent help placement, no unnecessary repeated entry, and authentication without cognitive-function tests unless alternatives exist.'
+    }
+  ]
+};
+
+function parseArgs(argv) {
+  const opts = {
+    threshold: 'baseline',
+    viewports: [],
+    waitUntil: 'networkidle',
+    timeout: 30000,
+    includePasses: false,
+    urls: []
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg === '--threshold') {
+      opts.threshold = (argv[++i] || '').toLowerCase();
+    } else if (arg === '--tags') {
+      opts.tags = (argv[++i] || '').split(',').map((tag) => tag.trim()).filter(Boolean);
+    } else if (arg === '--viewport') {
+      opts.viewports.push(parseViewport(argv[++i]));
+    } else if (arg === '--out') {
+      opts.out = argv[++i];
+    } else if (arg === '--wait-until') {
+      opts.waitUntil = argv[++i];
+    } else if (arg === '--timeout') {
+      opts.timeout = Number(argv[++i]);
+    } else if (arg === '--include-passes') {
+      opts.includePasses = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      opts.urls.push(arg);
+    }
+  }
+
+  if (!opts.viewports.length) {
+    opts.viewports = [VIEWPORTS.desktop, VIEWPORTS.mobile];
+  }
+  if (!opts.out) {
+    opts.out = path.resolve(process.cwd(), `a11y-audit-${timestamp()}`);
+  } else {
+    opts.out = path.resolve(process.cwd(), opts.out);
+  }
+  if (!Number.isFinite(opts.timeout) || opts.timeout <= 0) {
+    throw new Error('--timeout must be a positive number');
+  }
+  if (!THRESHOLDS.hasOwnProperty(opts.threshold)) {
+    throw new Error(`Unsupported threshold "${opts.threshold}". Use one of: ${Object.keys(THRESHOLDS).join(', ')}`);
+  }
+  if (!['load', 'domcontentloaded', 'networkidle'].includes(opts.waitUntil)) {
+    throw new Error('--wait-until must be load, domcontentloaded, or networkidle');
+  }
+  return opts;
+}
+
+function parseViewport(value) {
+  if (!value) throw new Error('--viewport requires a value');
+  if (VIEWPORTS[value]) return VIEWPORTS[value];
+  const match = /^(\d{2,5})x(\d{2,5})$/i.exec(value);
+  if (!match) throw new Error(`Unsupported viewport "${value}". Use desktop, mobile, tablet, or WIDTHxHEIGHT.`);
+  return { name: `${match[1]}x${match[2]}`, width: Number(match[1]), height: Number(match[2]) };
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (!opts.urls.length) {
+    throw new Error('Provide at least one URL.');
+  }
+
+  const { chromium } = loadDependency('playwright');
+  const axe = loadDependency('axe-core');
+  fs.mkdirSync(opts.out, { recursive: true });
+
+  const browser = await launchChromium(chromium);
+  const results = [];
+  try {
+    for (const url of opts.urls) {
+      for (const viewport of opts.viewports) {
+        results.push(await auditPage({ browser, axe, url, viewport, opts }));
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+
+  const report = buildReport(results, opts);
+  const json = {
+    metadata: metadata(opts),
+    summary: summarize(results),
+    results: opts.includePasses ? results : results.map(stripLargeResultFields),
+    manualReview: buildManualReview(results, opts)
+  };
+
+  fs.writeFileSync(path.join(opts.out, 'results.json'), `${JSON.stringify(json, null, 2)}\n`);
+  fs.writeFileSync(path.join(opts.out, 'manual-review.json'), `${JSON.stringify(json.manualReview, null, 2)}\n`);
+  fs.writeFileSync(path.join(opts.out, 'report.md'), report);
+
+  const summary = summarize(results);
+  console.log(`Accessibility audit complete: ${opts.out}`);
+  console.log(`Violations: ${summary.violations}; manual review items: ${json.manualReview.items.length}; URLs: ${opts.urls.length}; viewports: ${opts.viewports.length}`);
+  console.log(`Report: ${path.join(opts.out, 'report.md')}`);
+
+  if (summary.violations > 0 || json.manualReview.items.length > 0) {
+    process.exitCode = 2;
+  }
+}
+
+function loadDependency(name) {
+  try {
+    return require(name);
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND') {
+      throw new Error(`Missing dependency "${name}". Run "cd .agents/skills/a11y-audit && npm install" first.`);
+    }
+    throw error;
+  }
+}
+
+async function launchChromium(chromium) {
+  try {
+    return await chromium.launch({
+      channel: 'chromium',
+      chromiumSandbox: false,
+      args: ['--no-sandbox', '--disable-setuid-sandbox']
+    });
+  } catch (error) {
+    const message = String(error && error.message ? error.message : error);
+    if (message.includes("Executable doesn't exist") || message.includes('Please run the following command')) {
+      throw new Error(`Missing Playwright Chromium browser in ${process.env.PLAYWRIGHT_BROWSERS_PATH}. Run "cd .agents/skills/a11y-audit && npm run setup" first.`);
+    }
+    throw error;
+  }
+}
+
+async function auditPage({ browser, axe, url, viewport, opts }) {
+  const context = await browser.newContext({
+    viewport: { width: viewport.width, height: viewport.height },
+    isMobile: Boolean(viewport.isMobile)
+  });
+  const page = await context.newPage();
+  const startedAt = new Date().toISOString();
+
+  try {
+    await page.goto(url, { waitUntil: opts.waitUntil, timeout: opts.timeout });
+    await page.addScriptTag({ content: axe.source });
+
+    const axeOptions = {
+      resultTypes: opts.includePasses
+        ? ['violations', 'incomplete', 'passes', 'inapplicable']
+        : ['violations', 'incomplete']
+    };
+    const tags = opts.tags || THRESHOLDS[opts.threshold];
+    if (tags) {
+      axeOptions.runOnly = { type: 'tag', values: tags };
+    }
+
+    const axeResults = await page.evaluate(async (options) => {
+      return window.axe.run(document, options);
+    }, axeOptions);
+
+    return {
+      url,
+      finalUrl: page.url(),
+      title: await page.title(),
+      viewport: viewport.name,
+      viewportSize: { width: viewport.width, height: viewport.height },
+      startedAt,
+      completedAt: new Date().toISOString(),
+      threshold: opts.threshold,
+      tags: tags || ['axe-default'],
+      error: null,
+      axe: axeResults
+    };
+  } catch (error) {
+    return {
+      url,
+      finalUrl: page.url(),
+      title: await page.title().catch(() => ''),
+      viewport: viewport.name,
+      viewportSize: { width: viewport.width, height: viewport.height },
+      startedAt,
+      completedAt: new Date().toISOString(),
+      threshold: opts.threshold,
+      tags: opts.tags || THRESHOLDS[opts.threshold] || ['axe-default'],
+      error: String(error && error.stack ? error.stack : error),
+      axe: { violations: [], incomplete: [], passes: [], inapplicable: [] }
+    };
+  } finally {
+    await context.close();
+  }
+}
+
+function metadata(opts) {
+  return {
+    generatedAt: new Date().toISOString(),
+    threshold: opts.threshold,
+    tags: opts.tags || THRESHOLDS[opts.threshold] || ['axe-default'],
+    urls: opts.urls,
+    viewports: opts.viewports.map((viewport) => ({
+      name: viewport.name,
+      width: viewport.width,
+      height: viewport.height
+    }))
+  };
+}
+
+function summarize(results) {
+  const summary = {
+    violations: 0,
+    incomplete: 0,
+    pagesWithErrors: 0,
+    impacts: {}
+  };
+  for (const result of results) {
+    if (result.error) summary.pagesWithErrors += 1;
+    for (const violation of result.axe.violations || []) {
+      summary.violations += violation.nodes.length || 1;
+      const impact = violation.impact || 'unknown';
+      summary.impacts[impact] = (summary.impacts[impact] || 0) + (violation.nodes.length || 1);
+    }
+    for (const item of result.axe.incomplete || []) {
+      summary.incomplete += item.nodes.length || 1;
+    }
+  }
+  return summary;
+}
+
+function stripLargeResultFields(result) {
+  const clone = JSON.parse(JSON.stringify(result));
+  delete clone.axe.passes;
+  delete clone.axe.inapplicable;
+  return clone;
+}
+
+function buildManualReview(results, opts) {
+  const items = [];
+
+  for (const result of results) {
+    if (result.error) {
+      items.push({
+        type: 'page-error',
+        url: result.url,
+        viewport: result.viewport,
+        title: 'Audit could not complete',
+        detail: result.error
+      });
+    }
+
+    for (const incomplete of result.axe.incomplete || []) {
+      for (const node of incomplete.nodes || [{}]) {
+        items.push({
+          type: 'axe-incomplete',
+          url: result.finalUrl || result.url,
+          viewport: result.viewport,
+          ruleId: incomplete.id,
+          impact: incomplete.impact || 'unknown',
+          title: incomplete.help,
+          wcag: wcagTags(incomplete.tags),
+          target: node.target || [],
+          detail: node.failureSummary || incomplete.description,
+          helpUrl: incomplete.helpUrl
+        });
+      }
+    }
+  }
+
+  const manualChecks = checksForThreshold(opts.threshold);
+  for (const check of manualChecks) {
+    items.push({
+      type: 'threshold-manual-check',
+      threshold: opts.threshold,
+      id: check.id,
+      title: check.title,
+      wcag: check.wcag,
+      detail: check.review
+    });
+  }
+
+  return { items };
+}
+
+function checksForThreshold(threshold) {
+  const ordered = ['baseline'];
+  if (['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'].includes(threshold)) ordered.push('wcag2a');
+  if (['wcag2aa', 'wcag21aa', 'wcag22aa'].includes(threshold)) ordered.push('wcag2aa');
+  if (['wcag22aa'].includes(threshold)) ordered.push('wcag22aa');
+
+  const seen = new Set();
+  const checks = [];
+  for (const group of ordered) {
+    for (const check of MANUAL_CHECKS[group]) {
+      const key = `${check.id}:${check.wcag.join(',')}`;
+      if (!seen.has(key)) {
+        checks.push(check);
+        seen.add(key);
+      }
+    }
+  }
+  return checks;
+}
+
+function buildReport(results, opts) {
+  const lines = [];
+  const summary = summarize(results);
+  const manual = buildManualReview(results, opts);
+  const meta = metadata(opts);
+
+  lines.push('# A11y Audit Report', '');
+  lines.push(`Generated: ${meta.generatedAt}`);
+  lines.push(`Threshold: ${opts.threshold}`);
+  lines.push(`Axe tags: ${meta.tags.join(', ')}`);
+  lines.push(`URLs: ${opts.urls.join(', ')}`);
+  lines.push(`Viewports: ${meta.viewports.map((v) => `${v.name} (${v.width}x${v.height})`).join(', ')}`, '');
+
+  lines.push('## Summary', '');
+  lines.push(`- Violating node instances: ${summary.violations}`);
+  lines.push(`- Axe incomplete/manual node instances: ${summary.incomplete}`);
+  lines.push(`- Page audit errors: ${summary.pagesWithErrors}`);
+  lines.push(`- Manual review required: ${manual.items.length > 0 ? 'yes' : 'no'}`);
+  lines.push('');
+
+  if (Object.keys(summary.impacts).length) {
+    lines.push('Impact counts:');
+    for (const [impact, count] of Object.entries(sortImpacts(summary.impacts))) {
+      lines.push(`- ${impact}: ${count}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Required Changes From Axe', '');
+  const violations = collectViolations(results);
+  if (!violations.length) {
+    lines.push('No automated Axe violations were found for the selected threshold and viewport set.', '');
+  } else {
+    for (const group of violations) {
+      lines.push(`### ${group.impactLabel} ${group.id}: ${group.help}`);
+      lines.push('');
+      lines.push(`- WCAG/tags: ${group.tags.length ? group.tags.join(', ') : 'n/a'}`);
+      lines.push(`- Help: ${group.helpUrl || 'n/a'}`);
+      lines.push(`- Required change: ${group.description}`);
+      lines.push(`- Affected instances: ${group.nodes.length}`);
+      lines.push('');
+      for (const node of group.nodes) {
+        lines.push(`  - ${node.url} [${node.viewport}] target: \`${formatTarget(node.target)}\``);
+        if (node.failureSummary) lines.push(`    ${oneLine(node.failureSummary)}`);
+      }
+      lines.push('');
+    }
+  }
+
+  lines.push('## Manual Review Required', '');
+  if (!manual.items.length) {
+    lines.push('No manual-review items were generated.', '');
+  } else {
+    const byType = groupBy(manual.items, (item) => item.type);
+    for (const [type, items] of Object.entries(byType)) {
+      lines.push(`### ${titleCase(type)}`, '');
+      for (const item of items) {
+        lines.push(`- ${item.title || item.id}`);
+        if (item.wcag && item.wcag.length) lines.push(`  WCAG: ${item.wcag.join(', ')}`);
+        if (item.url) lines.push(`  URL: ${item.url} [${item.viewport || 'n/a'}]`);
+        if (item.target && item.target.length) lines.push(`  Target: \`${formatTarget(item.target)}\``);
+        if (item.helpUrl) lines.push(`  Help: ${item.helpUrl}`);
+        lines.push(`  Review: ${oneLine(item.detail || '')}`);
+      }
+      lines.push('');
+    }
+  }
+
+  lines.push('## Raw Artifacts', '');
+  lines.push('- `results.json`: Axe results and metadata.');
+  lines.push('- `manual-review.json`: Items that require `playwright-cli` review.');
+  lines.push('');
+
+  return `${lines.join('\n')}\n`;
+}
+
+function collectViolations(results) {
+  const groups = new Map();
+
+  for (const result of results) {
+    for (const violation of result.axe.violations || []) {
+      const key = [violation.id, violation.impact || 'unknown'].join('::');
+      if (!groups.has(key)) {
+        groups.set(key, {
+          id: violation.id,
+          impact: violation.impact || 'unknown',
+          impactLabel: `[${(violation.impact || 'unknown').toUpperCase()}]`,
+          help: violation.help,
+          helpUrl: violation.helpUrl,
+          description: violation.description,
+          tags: wcagTags(violation.tags),
+          nodes: []
+        });
+      }
+      const group = groups.get(key);
+      for (const node of violation.nodes || []) {
+        group.nodes.push({
+          url: result.finalUrl || result.url,
+          viewport: result.viewport,
+          target: node.target || [],
+          failureSummary: node.failureSummary || ''
+        });
+      }
+    }
+  }
+
+  return Array.from(groups.values()).sort((a, b) => {
+    return impactRank(a.impact) - impactRank(b.impact) || a.id.localeCompare(b.id);
+  });
+}
+
+function wcagTags(tags = []) {
+  return tags.filter((tag) => /^(wcag|section508|best-practice)/.test(tag));
+}
+
+function impactRank(impact) {
+  return { critical: 0, serious: 1, moderate: 2, minor: 3, unknown: 4 }[impact] ?? 4;
+}
+
+function sortImpacts(impacts) {
+  return Object.fromEntries(Object.entries(impacts).sort(([a], [b]) => impactRank(a) - impactRank(b)));
+}
+
+function groupBy(items, keyFn) {
+  return items.reduce((groups, item) => {
+    const key = keyFn(item);
+    groups[key] = groups[key] || [];
+    groups[key].push(item);
+    return groups;
+  }, {});
+}
+
+function formatTarget(target) {
+  return Array.isArray(target) ? target.join(', ') : String(target || 'n/a');
+}
+
+function oneLine(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function titleCase(value) {
+  return String(value).replace(/-/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+main().catch((error) => {
+  console.error(error.message || error);
+  process.exit(1);
+});

package/skills/a11y-audit/scripts/setup.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+npm install
+PLAYWRIGHT_BROWSERS_PATH="$PWD/.ms-playwright" npx playwright install chromium

package/skills/browser-validation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: browser-validation
+description: Before completing a task validate frontend or template changes in a real browser with the Playwright-CLI skill. Use when an agent has changed anything that will change appearance or functionality.
+version: 1.0.0
+---
+
+# Browser Validation
+
+## Required Dependency
+
+If no Playwright-CLI skill is available, stop and ask the user to install the required Playwright-CLI skill before browser validation can run.
+
+## Configuration
+
+Read `config.toml` in this skill folder and use `dev_server_url` as the target application URL.

package/skills/browser-validation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Browser Validation"
+  short_description: "Validate changes in the browser"
+  default_prompt: "Validate the current changes in the browser"

package/skills/browser-validation/config.toml

@@ -0,0 +1 @@
+dev_server_url = "http://localhost:8000"

package/skills/scry/SKILL.md

@@ -68,6 +68,75 @@ Useful options:
 - `--path=/about --path=/products/example` overrides sitemap paths for the current run and writes them to `paths.json`.
 - `--wait-until=networkidle` changes navigation waiting; default is `domcontentloaded`.
 
+## Temporary Playwright Setup
+
+Some theme repositories do not have a local `package.json`, `node_modules/`, or `@playwright/test` install. In that case, keep Playwright out of the repository and install it temporarily under `/tmp`.
+
+Create the temporary install directory:
+
+```bash
+mkdir -p /tmp/scry-playwright
+```
+
+Install Playwright Test there:
+
+```bash
+npm install --prefix /tmp/scry-playwright @playwright/test
+```
+
+Install the browser needed for the run:
+
+```bash
+/tmp/scry-playwright/node_modules/.bin/playwright install chromium
+```
+
+Generate the scry config and paths from the repository root:
+
+```bash
+python3 .agents/skills/scry/scripts/scry.py "$LIVE_URL" "$PREVIEW_URL" --refresh --regenerate-paths --no-ui --browser=chromium
+```
+
+If `paths.json` is large, inspect it and trim duplicate template paths before the full comparison.
+
+Run the generated suite with the temporary Playwright install:
+
+```bash
+env NODE_PATH=/tmp/scry-playwright/node_modules \
+  SCRY_CONFIG="$PWD/.agents/skills/scry/config.json" \
+  SCRY_PATHS="$PWD/.agents/skills/scry/paths.json" \
+  SCRY_BASELINE_DIR="$PWD/.agents/skills/scry/baselines" \
+  SCRY_REFRESH=1 \
+  /tmp/scry-playwright/node_modules/.bin/playwright test \
+  --config "$PWD/.agents/skills/scry/runtime/playwright.config.cjs"
+```
+
+## Cleanup
+
+After a temporary Playwright run, remove transient report output from the repository root:
+
+```bash
+rm -rf playwright-report test-results
+```
+
+Remove the temporary dependency install:
+
+```bash
+rm -rf /tmp/scry-playwright
+```
+
+Only remove downloaded Playwright browsers when intentionally resetting local tooling:
+
+```bash
+rm -rf ~/.cache/ms-playwright
+```
+
+Keep these scry artifacts unless intentionally resetting the comparison state:
+
+- `.agents/skills/scry/config.json`
+- `.agents/skills/scry/paths.json`
+- `.agents/skills/scry/runtime/`
+- `.agents/skills/scry/baselines/`
+
 ## Playwright CLI
 
 If the comparison fails or needs manual investigation, use `$playwright-cli` after the UI run to inspect pages directly.

package/skills/scry/scripts/scry.py

@@ -50,6 +50,7 @@ function joinUrl(baseUrl, pagePath) {
   if (base.pathname !== "/" && base.pathname !== "") {
     joined.pathname = path.posix.join(base.pathname, joined.pathname);
   }
+  joined.search = base.search;
   return joined.toString();
 }