@appfire-ux/audit-agent 0.20260702.1 → 0.20260702.3

package/README.md

@@ -1,6 +1,11 @@
 # @appfire-ux/audit-agent
 
-One-command install of two Claude Code audit agents for Appfire repos. Both bootstrap/refresh `@appfire-ux/guidelines` by themselves (Phase 0):
+One-command install of two Claude Code audit agents for Appfire repos. **Every audit run refreshes both npm packages to `@latest`** (Phase 0):
+
+- **`@appfire-ux/audit-agent`** — agent/command definitions in `.claude/`
+- **`@appfire-ux/guidelines`** — rules, skills, and `guidelines/` kit
+
+Agents:
 
 - **ux-auditor** (`/ux-audit`) — guideline-compliance UX audit: design tokens, spacing/typography, accessibility, UX writing, messaging patterns, persona fit.
 - **ui-auditor** (`/ui-audit`) — UI & usability audit from a UI Designer's perspective: cross-screen consistency, layout & visual hierarchy, information architecture, navigation, interaction design, forms, data-dense views, responsiveness. Screenshot-driven (browser MCP or bundled Playwright fallback).
@@ -27,24 +32,29 @@ Once, for all repos on your machine:
 npx @appfire-ux/audit-agent --global   # installs into ~/.claude/
 ```
 
-## Update
+## Update (manual, optional)
+
+Phase 0 on every `/ux-audit`, `/ui-audit`, or `/full-audit` run already calls `npm update` + `@latest` for both packages. Use this only when you want to refresh **without** running an audit:
 
 ```bash
-npm update @appfire-ux/audit-agent
+npm update @appfire-ux/audit-agent @appfire-ux/guidelines
 npx @appfire-ux/audit-agent
+npx @appfire-ux/guidelines
 ```
 
 ## What gets installed
 
 | File | Purpose |
 |---|---|
-| `.claude/agents/ux-auditor.md` | 8-phase compliance audit: guidelines bootstrap → static + runtime audit → evidence-based report → self-verification |
-| `.claude/commands/ux-audit.md` | `/ux-audit [scope] [--static-only] [--lang pl] [--out <path>]` |
-| `.claude/agents/ui-auditor.md` | 8-phase UI & usability audit: guidelines bootstrap → screen/pattern inventory → screenshot capture → consistency/IA/interaction passes → report → self-verification |
-| `.claude/commands/ui-audit.md` | `/ui-audit [scope] [--static-only] [--lang pl] [--out <path>]` |
-| `.claude/commands/full-audit.md` | `/full-audit [scope] [--static-only] [--lang pl] [--out-dir <path>]` — runs **ux-auditor** and **ui-auditor** in parallel with shared guidelines bootstrap and one dev server |
-
-The audits complement each other: `ux-audit` checks *compliance with the guidelines*, `ui-audit` checks *the interface as designed*. Use `/full-audit` when you want both at once; findings each agent notices outside its lane are handed off to the other's report section, and the combined summary deduplicates cross-cutting issues.
+| `.claude/agents/ux-auditor.md` | Guideline-compliance audit → MD + HTML + `assets/*.png` (Confluence-ready) |
+| `.claude/commands/ux-audit.md` | `/ux-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
+| `.claude/agents/ui-auditor.md` | UI & usability audit → same deliverable format |
+| `.claude/commands/ui-audit.md` | `/ui-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
+| `.claude/commands/full-audit.md` | `/full-audit` — parallel run, shared capture, combined summary MD+HTML |
+| `scripts/ux-audit-capture.mjs` | Playwright screenshot fallback (`--widths 1440,768`) |
+| `scripts/build-html-reports.mjs` | MD → Confluence-ready HTML with local `assets/` gallery |
+
+The audits complement each other. Every run produces **Markdown + HTML + PNG assets** under `docs/audits/` (STOP & ASK on auth walls; no base64). Use `/full-audit` for both agents in parallel.
 
 ## Publishing (maintainers)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260702.1",
-  "description": "Claude Code audit agents for Appfire apps — installs ux-auditor (/ux-audit: guideline compliance) and ui-auditor (/ui-audit: UI consistency, IA, interaction design), auditing against @appfire-ux/guidelines",
+  "version": "0.20260702.3",
+  "description": "Claude Code audit agents for Appfire apps — ux-auditor (/ux-audit), ui-auditor (/ui-audit), /full-audit parallel orchestration. Confluence-ready MD+HTML+PNG output, runtime capture scripts.",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/scripts/build-html-reports.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Convert audit Markdown reports to Confluence-ready HTML.
+ * Images stay as relative assets/*.png — never base64.
+ *
+ * Usage:
+ *   node build-html-reports.mjs --file docs/audits/ux-audit/UX-AUDIT-2026-07-02.md
+ *   node build-html-reports.mjs --dir docs/audits/ux-audit
+ *   node build-html-reports.mjs --dir docs/audits
+ *
+ * Bundled path: node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs
+ */
+
+'use strict';
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const opts = { files: [], dirs: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--file') opts.files.push(argv[++i]);
+    else if (arg === '--dir') opts.dirs.push(argv[++i]);
+  }
+  return opts;
+}
+
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function inlineFormat(text) {
+  let out = escapeHtml(text);
+  out = out.replace(/`([^`]+)`/g, '<code>$1</code>');
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  out = out.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+  return out;
+}
+
+function mdToHtml(md) {
+  const lines = md.replace(/\r\n/g, '\n').split('\n');
+  const html = [];
+  let inCode = false;
+  let codeBuf = [];
+  let inTable = false;
+  let tableRows = [];
+
+  function flushTable() {
+    if (!tableRows.length) return;
+    html.push('<table>');
+    tableRows.forEach((row, idx) => {
+      const tag = idx === 0 ? 'th' : 'td';
+      const cells = row.split('|').map((c) => c.trim()).filter(Boolean);
+      if (cells.length === 0) return;
+      if (idx === 1 && cells.every((c) => /^[-:]+$/.test(c))) return;
+      html.push('<tr>' + cells.map((c) => `<${tag}>${inlineFormat(c)}</${tag}>`).join('') + '</tr>');
+    });
+    html.push('</table>');
+    tableRows = [];
+    inTable = false;
+  }
+
+  for (const line of lines) {
+    if (line.startsWith('```')) {
+      if (inCode) {
+        html.push('<pre><code>' + escapeHtml(codeBuf.join('\n')) + '</code></pre>');
+        codeBuf = [];
+        inCode = false;
+      } else {
+        flushTable();
+        inCode = true;
+      }
+      continue;
+    }
+    if (inCode) {
+      codeBuf.push(line);
+      continue;
+    }
+
+    if (line.trim().startsWith('|')) {
+      inTable = true;
+      tableRows.push(line.trim());
+      continue;
+    }
+    if (inTable) flushTable();
+
+    const img = line.match(/^!\[([^\]]*)\]\(([^)]+)\)\s*$/);
+    if (img) {
+      html.push(`<figure><img src="${img[2]}" alt="${escapeHtml(img[1])}" /><figcaption>${escapeHtml(img[1])}</figcaption></figure>`);
+      continue;
+    }
+
+    if (/^#{1,6}\s/.test(line)) {
+      const level = line.match(/^#+/)[0].length;
+      const text = line.replace(/^#+\s*/, '');
+      html.push(`<h${level}>${inlineFormat(text)}</h${level}>`);
+      continue;
+    }
+
+    if (/^[-*]\s/.test(line)) {
+      html.push(`<li>${inlineFormat(line.replace(/^[-*]\s/, ''))}</li>`);
+      continue;
+    }
+
+    if (/^\d+\.\s/.test(line)) {
+      html.push(`<li>${inlineFormat(line.replace(/^\d+\.\s/, ''))}</li>`);
+      continue;
+    }
+
+    if (line.trim() === '---') {
+      html.push('<hr />');
+      continue;
+    }
+
+    if (line.trim() === '') {
+      html.push('');
+      continue;
+    }
+
+    html.push(`<p>${inlineFormat(line)}</p>`);
+  }
+
+  if (inTable) flushTable();
+  if (inCode && codeBuf.length) {
+    html.push('<pre><code>' + escapeHtml(codeBuf.join('\n')) + '</code></pre>');
+  }
+
+  return html.join('\n');
+}
+
+function listPngs(assetsDir) {
+  if (!fs.existsSync(assetsDir)) return [];
+  return fs
+    .readdirSync(assetsDir)
+    .filter((f) => f.endsWith('.png'))
+    .sort()
+    .map((f) => `assets/${f}`);
+}
+
+function buildGallery(assetsDir) {
+  const images = listPngs(assetsDir);
+  if (!images.length) return '';
+  const items = images
+    .map((src) => `<figure><img src="${src}" alt="${path.basename(src)}" /><figcaption>${escapeHtml(path.basename(src))}</figcaption></figure>`)
+    .join('\n');
+  return `<section class="gallery"><h2>Visual evidence gallery</h2>\n${items}\n</section>`;
+}
+
+function wrapHtml(title, body, gallery) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; line-height: 1.5; max-width: 960px; margin: 0 auto; padding: 24px; color: #172b4d; }
+    .confluence-hint { background: #deebff; border-left: 4px solid #0052cc; padding: 12px 16px; margin-bottom: 24px; font-size: 14px; }
+    h1, h2, h3 { line-height: 1.25; }
+    table { border-collapse: collapse; width: 100%; margin: 16px 0; }
+    th, td { border: 1px solid #dfe1e6; padding: 8px 12px; text-align: left; vertical-align: top; }
+    th { background: #f4f5f7; }
+    img { max-width: 100%; height: auto; border: 1px solid #dfe1e6; border-radius: 3px; }
+    figure { margin: 16px 0; }
+    figcaption { font-size: 12px; color: #5e6c84; margin-top: 4px; }
+    pre { background: #f4f5f7; padding: 12px; overflow-x: auto; border-radius: 3px; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9em; }
+    .gallery { margin-top: 48px; padding-top: 24px; border-top: 2px solid #dfe1e6; }
+    .gallery figure { display: inline-block; width: 48%; margin: 1%; vertical-align: top; }
+  </style>
+</head>
+<body>
+  <div class="confluence-hint">
+    <strong>Confluence:</strong> Open this file in a browser → <kbd>⌘A</kbd> / <kbd>Ctrl+A</kbd> → Copy → Paste into Confluence.
+    Images load from the local <code>assets/</code> folder — keep PNG files alongside this HTML when sharing.
+  </div>
+  <main>
+${body}
+  </main>
+${gallery}
+</body>
+</html>`;
+}
+
+function convertFile(mdPath) {
+  const abs = path.resolve(mdPath);
+  if (!fs.existsSync(abs)) {
+    console.error(`[build-html-reports] not found: ${abs}`);
+    return false;
+  }
+  const md = fs.readFileSync(abs, 'utf8');
+  const dir = path.dirname(abs);
+  const base = path.basename(abs, '.md');
+  const assetsDir = path.join(dir, 'assets');
+  const title = base;
+  const body = mdToHtml(md);
+  const gallery = buildGallery(assetsDir);
+  const html = wrapHtml(title, body, gallery);
+  const outPath = path.join(dir, `${base}.html`);
+  fs.writeFileSync(outPath, html);
+  console.log(`[build-html-reports] ${outPath}`);
+  return true;
+}
+
+function collectMdFiles(dir) {
+  const abs = path.resolve(dir);
+  if (!fs.existsSync(abs)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+    const full = path.join(abs, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'assets' || entry.name === 'node_modules') continue;
+      results.push(...collectMdFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md') && /AUDIT/i.test(entry.name)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function main() {
+  const { files, dirs } = parseArgs(process.argv.slice(2));
+  const targets = [...files];
+  for (const d of dirs) targets.push(...collectMdFiles(d));
+
+  if (!targets.length) {
+    console.error('[build-html-reports] Usage: --file <path.md> | --dir <folder>');
+    process.exit(1);
+  }
+
+  let ok = 0;
+  for (const f of [...new Set(targets)]) {
+    if (convertFile(f)) ok++;
+  }
+  if (ok === 0) process.exit(1);
+}
+
+main();

package/scripts/ux-audit-capture.mjs

@@ -7,7 +7,7 @@
  * Usage:
  *   npx playwright install chromium   # once, if not already installed
  *   node scripts/ux-audit-capture.mjs --url http://localhost:5173 \
- *     --out docs/ux-audit/assets --routes /,/dashboard/teams
+ *     --out docs/ux-audit/assets --routes /,/dashboard/teams --widths 1440,768
  *
  * Requires the optional "playwright" dependency (see package.json).
  */
@@ -18,15 +18,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 function parseArgs(argv) {
-  const opts = { url: null, out: null, routes: ['/'], width: 1440, height: 900 };
+  const opts = { url: null, out: null, routes: ['/'], widths: [1440], height: 900 };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--url') opts.url = argv[++i];
     else if (arg === '--out') opts.out = argv[++i];
     else if (arg === '--routes') opts.routes = argv[++i].split(',').map((r) => r.trim()).filter(Boolean);
-    else if (arg === '--width') opts.width = parseInt(argv[++i], 10) || 1440;
+    else if (arg === '--width') opts.widths = [parseInt(argv[++i], 10) || 1440];
+    else if (arg === '--widths') opts.widths = argv[++i].split(',').map((w) => parseInt(w.trim(), 10)).filter(Boolean);
     else if (arg === '--height') opts.height = parseInt(argv[++i], 10) || 900;
   }
+  if (!opts.widths.length) opts.widths = [1440];
   return opts;
 }
 
@@ -36,10 +38,10 @@ function routeToFilename(route, width) {
 }
 
 async function main() {
-  const { url, out, routes, width, height } = parseArgs(process.argv.slice(2));
+  const { url, out, routes, widths, height } = parseArgs(process.argv.slice(2));
 
   if (!url || !out) {
-    console.error('[ux-audit-capture] Usage: --url <base-url> --out <dir> [--routes /,/foo,/bar] [--width 1440] [--height 900]');
+    console.error('[ux-audit-capture] Usage: --url <base-url> --out <dir> [--routes /,/foo] [--width 1440 | --widths 1440,768] [--height 900]');
     process.exit(1);
   }
 
@@ -54,21 +56,24 @@ async function main() {
   fs.mkdirSync(out, { recursive: true });
 
   const browser = await chromium.launch();
-  const page = await browser.newPage({ viewport: { width, height } });
-
   const results = [];
-  for (const route of routes) {
-    const target = new URL(route, url).toString();
-    const file = path.join(out, routeToFilename(route, width));
-    try {
-      await page.goto(target, { waitUntil: 'networkidle', timeout: 15000 });
-      await page.screenshot({ path: file, fullPage: true });
-      results.push({ route, file, ok: true });
-      console.log(`[ux-audit-capture] captured ${route} -> ${file}`);
-    } catch (err) {
-      results.push({ route, file: null, ok: false, error: err.message });
-      console.error(`[ux-audit-capture] failed ${route}: ${err.message}`);
+
+  for (const width of widths) {
+    const page = await browser.newPage({ viewport: { width, height } });
+    for (const route of routes) {
+      const target = new URL(route, url).toString();
+      const file = path.join(out, routeToFilename(route, width));
+      try {
+        await page.goto(target, { waitUntil: 'networkidle', timeout: 15000 });
+        await page.screenshot({ path: file, fullPage: true });
+        results.push({ route, width, file, ok: true });
+        console.log(`[ux-audit-capture] captured ${route} @${width}w -> ${file}`);
+      } catch (err) {
+        results.push({ route, width, file: null, ok: false, error: err.message });
+        console.error(`[ux-audit-capture] failed ${route} @${width}w: ${err.message}`);
+      }
     }
+    await page.close();
   }
 
   await browser.close();

package/templates/agents/ui-auditor.md

@@ -20,9 +20,34 @@ You are a senior UI Designer at Appfire doing a design critique of a shipped pro
 
 Work through the phases below IN ORDER. Do not skip Phase 0 or Phase 7.
 
-## Phase 0 — Bootstrap @appfire-ux/guidelines
+## Shared deliverables & runtime protocol
 
-Same kit as ux-auditor (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines; postinstall copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, `guidelines/` into the project root). Assume it is NOT installed yet.
+Every audit must produce **Confluence-ready** output. Applies to ux-auditor, ui-auditor, and `/full-audit`. **Full spec:** same section in `ux-auditor` agent (identical rules).
+
+**ui-auditor paths:** `docs/audits/ui-audit/UI-AUDIT-<date>[-prod].{md,html}` + `docs/audits/ui-audit/assets/*.png`.
+
+**Role:** you own IA, consistency, layout, interaction, responsiveness — **not** token/a11y/copy compliance (hand off to ux-auditor). Same STOP & ASK protocol, same HTML+PNG rules, same Definition of done checklist.
+
+**HTML after MD:**
+```bash
+node node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs --dir docs/audits/ui-audit
+```
+
+**STOP & ASK** when: login redirect, auth wall, wrong UI, capture script total fail, no MCP session for dashboard. Use the Polish/English template from ux-auditor. Resume capture only after user reply; else static-only with Limitations on page 1.
+
+**Definition of done:** MD+HTML, PNGs in `assets/` (relative paths, no base64), gallery in HTML, verified-runtime ↔ PNG or downgrade, Limitations complete, preview links if served.
+
+## Phase 0 — Bootstrap audit toolchain
+
+Run **0a** then **0b** before any audit work. Record installed versions and any stale/failed steps in the report appendix.
+
+### 0a — Refresh @appfire-ux/audit-agent
+
+Same steps as ux-auditor Phase 0a: update/install `@appfire-ux/audit-agent@latest`, run `npx @appfire-ux/audit-agent`, verify `.claude/agents/` and `.claude/commands/` exist. Flag **"audit-agent possibly stale"** on npm failure when older files remain; STOP if no agent files and npm fails.
+
+### 0b — Bootstrap @appfire-ux/guidelines
+
+Same kit as ux-auditor (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines; postinstall copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, `guidelines/` into the project root).
 
 1. Locate the repo-root `package.json` (monorepo → workspace root; none anywhere → `npm init -y` and note it in the appendix).
 2. Kit present (`guidelines/` with `foundations/` + `personas/` AND at least one `.cursor/rules/ux-*.mdc`) → refresh:
@@ -53,22 +78,25 @@ You read the kit for *design context*, not as a rulebook:
 
 ## Phase 3 — Runtime capture (do this EARLY — the audit is visual)
 
-Unlike a compliance audit, this audit is materially weaker without screenshots, so capture comes before analysis. Never let it break the audit; on failure fall back gracefully and record the limitation.
+Follow **Shared deliverables & runtime protocol** (STOP & ASK, capture order, minimum screenshots). Never let capture break the audit.
 
-1. Find the dev command (`package.json` scripts: `dev`/`start`/`storybook`), install deps if needed, start it in the background, wait for the port to answer.
-2. Capture in this order — stop at the first that works:
-   1. **Browser MCP/tool in session** (Playwright MCP, Chrome DevTools, Claude in Chrome) → walk the screen inventory: screenshot every screen (save under `docs/ui-audit/assets/`), plus key states (open modal, expanded filters, populated vs empty table) and at least two viewport widths (~1440 and ~768; mobile if the app claims support). Perform interaction probes: click-count for the top 3 persona jobs, hover/focus affordance on primary controls, scroll behavior of sticky headers/toolbars.
-   2. **No browser tool** → use the bundled Playwright capture script:
+1. **Resolve base URL** — do not assume localhost; verify the app responds with real UI. Record URL in Limitations.
+2. **STOP & ASK** on blind-alley signals before wasting analysis time.
+3. Capture in order:
+   1. **Browser MCP in session** → screenshot every inventory screen + key states (modal, empty table, error) at **1440px and 768px**; save to `docs/audits/ui-audit/assets/`; interaction probes where possible.
+   2. **Bundled Playwright script**:
       ```bash
-      npx playwright install chromium   # one-time, skip if already installed
+      npx playwright install chromium
       node node_modules/@appfire-ux/audit-agent/scripts/ux-audit-capture.mjs \
-        --url http://localhost:5173 \
-        --out docs/ui-audit/assets \
-        --routes /,/dashboard,/settings
+        --url <verified-base-url> \
+        --out docs/audits/ui-audit/assets \
+        --routes /,<key-routes> \
+        --widths 1440,768
       ```
-      Run it twice — once with `--width 1440` and once with `--width 768` — to cover both viewports (filenames get a `-<width>w` suffix). Screenshots only — interaction probes stay `suspected`. If the script errors entirely, fall through to 2.3.
-   3. **Both unavailable** → static-only audit from JSX/templates; state prominently in the report that visual findings are code-inferred.
-3. **Look at every screenshot you captured** (Read the image files). Your visual analysis must come from actually viewing them, not from imagining the rendered result. If Storybook exists, prefer it for isolated component-state screenshots.
+      Interaction probes stay `suspected` without MCP.
+   3. **Both fail** → static-only; Limitations prominent; code-inferred visual claims only as `verified-static` / `suspected`.
+4. **Read every captured PNG** (Read tool on image files) before writing visual findings.
+5. If `/full-audit` orchestrator placed shared PNGs in `docs/audits/prod-assets/`, **copy or symlink** into your `ui-audit/assets/` and reference as `assets/<file>.png` — do not use `../prod-assets/` in MD/HTML.
 
 ## Phase 4 — The audit passes
 
@@ -128,31 +156,40 @@ Per-category (A–H) score ✅/⚠️/❌ + counts. Top 5 quick wins. Suggested
 
 ## Phase 6 — Write the report
 
-Write to `docs/ui-audit/UI-AUDIT-<YYYY-MM-DD>.md` (create dirs; honor a user-given path). English unless asked otherwise. Structure:
+Write to `docs/audits/ui-audit/UI-AUDIT-<YYYY-MM-DD>[-prod].md` (honor user `--out`). English unless asked otherwise.
+
+**Limitations** — prominent block after executive summary when capture was partial or static-only.
 
-1. **Executive summary** — app purpose, audited personas, the interface's 3 biggest strengths and 3 biggest problems, headline numbers, top 5 quick wins.
-2. **Scorecard** — category (A–H) → status → Critical/High/Medium/Low counts → one-line verdict.
-3. **Scope & method** — commit SHA, date, guidelines kit version, screens captured (with viewport widths) vs code-only, interaction probes performed, de-scoped areas.
-4. **IA map & screen inventory** — the Phase 2 artifacts, annotated with problems found.
-5. **Pattern inventory** — table: pattern → # of divergent implementations → screens → target pattern recommendation.
-6. **Findings** — grouped by category, ordered by severity:
+Structure:
+
+1. **Executive summary** — app purpose, personas, 3 biggest strengths / 3 biggest problems, headline numbers, top 5 quick wins.
+2. **Scorecard** — category (A–H) → status → counts → verdict.
+3. **Scope & method** — commit SHA, date, kit versions, capture URL & viewports, screens captured vs code-only, interaction probes, de-scoped areas.
+4. **IA map & screen inventory** — Phase 2 artifacts, annotated.
+5. **Pattern inventory** — pattern → # implementations → screens → target pattern.
+6. **Findings** — by category, by severity:
    ```
    ### [UI-<CAT>-<NN>] <title>
    Severity: … | Confidence: … | Effort: S/M/L
-   Screens: <screens/routes affected> | Location: <file>:<line> (+ occurrence count)
-   Evidence: <screenshot reference and/or ≤10-line code excerpt>
+   Screens: <routes> | Location: <file>:<line>
+   Screenshot: assets/<file>.png (required for verified-runtime)
+   Evidence: ![desc](assets/file.png) and/or code excerpt
    Personas affected: …
-   Why it matters: <the design reasoning — 1–3 sentences>
-   Recommendation: <concrete fix; sketch the target pattern when useful>
+   Why it matters: …
+   Recommendation: …
    ```
-7. **Positive observations** — what to keep.
-8. **Remediation roadmap** — quick wins → pattern consolidation → structural IA changes.
-9. **Handoff to /ux-audit** — token/a11y/copy issues noticed in passing, one line each.
-10. **Appendix** — bootstrap log, capture method and its limitations, `suspected` items needing human review.
+7. **Positive observations**
+8. **Remediation roadmap**
+9. **Handoff to /ux-audit** — token/a11y/copy one-liners
+10. **Appendix** — bootstrap log, STOP & ASK, capture limitations, `suspected` items
+
+**Then generate HTML** via `build-html-reports.mjs` (see Shared deliverables).
 
 ## Phase 7 — Self-verification (mandatory)
 
-Re-open every finding: the cited screenshot/file:line exists and shows what is claimed; occurrence counts are accurate; every screenshot referenced in the report exists under `docs/ui-audit/assets/`; delete or downgrade to `suspected` anything not re-verifiable; check the report renders (tables, image links). Then summarize to the caller: report path, finding counts by severity, top 3 issues, capture coverage, limitations.
+Run **Definition of done** checklist. Verify every PNG referenced exists under `assets/`; downgrade `verified-runtime` without PNG; MD+HTML+gallery; no base64.
+
+Summarize: MD + HTML paths, preview URL, severity counts, top 3 issues, capture coverage, Limitations, STOP & ASK status.
 
 ## Operating rules
 

package/templates/agents/ux-auditor.md

@@ -15,9 +15,127 @@ You are a principal UX auditor at Appfire. You produce the most comprehensive, e
 
 Work through the phases below IN ORDER. Do not skip Phase 0 or Phase 7.
 
-## Phase 0 — Bootstrap @appfire-ux/guidelines
+## Shared deliverables & runtime protocol
 
-The audit is driven by the Appfire UX Guidelines kit (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines). Its postinstall script copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, and `guidelines/` into the project root. Assume it is NOT installed yet.
+Every audit must produce **Confluence-ready** output. Applies to ux-auditor, ui-auditor, and `/full-audit`.
+
+### Output goal
+
+Each audit ends with reports ready to paste into Confluence:
+
+- **Markdown** — source of truth in the repo
+- **HTML** — open in browser → ⌘A / Ctrl+A → copy → paste into Confluence
+- **PNG** in `assets/` — separate files only; **never** base64 in MD/HTML
+
+### Required file layout
+
+Default under `docs/audits/` (honor user `--out` / `--out-dir`; add `-prod` suffix when auditing production/staging URL):
+
+```
+docs/audits/
+├── AUDIT-SUMMARY-<YYYY-MM-DD>[-prod].md          # /full-audit only
+├── AUDIT-SUMMARY-<YYYY-MM-DD>[-prod].html
+├── prod-assets/                                   # optional — shared PNGs when /full-audit reuses captures
+├── ux-audit/
+│   ├── UX-AUDIT-<date>[-prod].md
+│   ├── UX-AUDIT-<date>[-prod].html
+│   └── assets/*.png
+└── ui-audit/
+    ├── UI-AUDIT-<date>[-prod].md
+    ├── UI-AUDIT-<date>[-prod].html
+    └── assets/*.png
+```
+
+**ux-auditor** writes to `docs/audits/ux-audit/` (or user path). Use relative image paths in MD/HTML: `assets/dashboard-teams-1440w.png` — not `../prod-assets/`, not `data:image/...`.
+
+### HTML generation (mandatory after MD)
+
+1. If `docs/audits/build-html-reports.mjs` exists in the repo → run it.
+2. Else use the bundled script:
+   ```bash
+   node node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs --dir docs/audits/ux-audit
+   ```
+3. If neither works → generate HTML yourself: simple CSS, Confluence hint at top, `<img src="assets/...">` for every screenshot, **Visual evidence gallery** at the bottom listing each unique PNG once.
+
+HTML rules: load images from local `assets/`; no base64; `img { max-width: 100% }`; inline screenshots in findings as `![desc](assets/file.png)`.
+
+### Runtime capture rules
+
+1. **Establish a working base URL first** — do not assume `localhost` without verifying the port responds with real app UI.
+2. Capture order (stop at first that works):
+   1. Browser MCP / Playwright with the **user's existing session** (preferred)
+   2. Bundled script: `node node_modules/@appfire-ux/audit-agent/scripts/ux-audit-capture.mjs --url <base> --out <assets-dir> --routes ... --widths 1440,768`
+   3. Static code audit only — **explicit disclaimer** in Limitations; no `verified-runtime` for dashboard claims
+3. **Minimum screenshots:** key routes from inventory (overview + top flows per persona); **1440px and 768px** for shell/nav + at least one data-heavy screen; empty list / error / open modal when cheap to reproduce.
+4. **Naming:** `<route-slug>-<width>w.png` (e.g. `dashboard-teams-768w.png`).
+5. **PII:** redact emails, tokens, names in report text; do not quote secrets; if PII appears on a PNG, describe generically or request re-capture after masking.
+
+### 🛑 STOP & ASK protocol (blind alley)
+
+**Stop the audit and ask the user** when any signal below is true — do not continue with fake `verified-runtime` or pretend you saw the dashboard:
+
+| Signal | Example |
+|--------|---------|
+| Login redirect | Google OAuth, empty `/`, infinite "Loading configuration…" |
+| Auth wall | `/dashboard/*` without JWT → login / 401 |
+| Wrong UI | OAuth landing instead of dashboard; "Admin only." without admin access |
+| Capture script fail | Playwright won't start; every route errors |
+| No browser MCP + no session | Only landing page; zero dashboard |
+
+**Message template:**
+
+> Nie mogę zweryfikować UI w runtime — [krótki powód].
+>
+> Żeby dokończyć audyt z pełnym visual evidence, podaj proszę:
+> 1. URL (np. `https://…/dashboard`) gdzie jesteś zalogowany i widzisz pełny shell, **albo**
+> 2. Dev command + port localhost, **albo**
+> 3. Potwierdzenie, że mogę użyć otwartej karty w przeglądarce (Browser MCP) z Twoją sesją.
+>
+> Opcjonalnie: konto admin vs team user — które mam użyć do capture?
+
+Resume Phase 3+/4+ only after the user answers. If they cannot provide a working path → finish **static-only** with **Limitations** on page 1 and no `verified-runtime` claims for protected surfaces.
+
+### Definition of done
+
+- [ ] MD + HTML for this audit (summary HTML too when `/full-audit`)
+- [ ] All PNGs in `assets/`; relative paths; zero base64
+- [ ] HTML includes visual evidence gallery
+- [ ] `verified-runtime` findings cite a PNG file OR are downgraded to `suspected` / `verified-static`
+- [ ] Limitations document: capture URL, viewports, role (admin/non-admin), what could not be opened
+- [ ] User receives local preview links if a static server was started (e.g. `http://localhost:<port>/.../*.html`)
+
+## Phase 0 — Bootstrap audit toolchain
+
+Run **0a** then **0b** before any audit work. Record installed versions and any stale/failed steps in the report appendix.
+
+### 0a — Refresh @appfire-ux/audit-agent
+
+This package ships the agent/command definitions in `.claude/`. Refresh them on every audit so methodology updates are picked up automatically.
+
+1. At the repo-root `package.json` (monorepo → workspace root):
+   - **Listed in `devDependencies` or `dependencies`** → refresh:
+     ```bash
+     npm update @appfire-ux/audit-agent
+     npx @appfire-ux/audit-agent
+     ```
+     Compare `npm ls @appfire-ux/audit-agent --depth=0` with `npm view @appfire-ux/audit-agent version`. If still behind, force: `npm install @appfire-ux/audit-agent@latest`, then `npx @appfire-ux/audit-agent`.
+   - **Not listed** but `.claude/agents/ux-auditor.md` exists (e.g. global install) → refresh in place:
+     ```bash
+     npx @appfire-ux/audit-agent@latest
+     ```
+   - **Neither** → install as a dev tool, then copy agents:
+     ```bash
+     npm install -D @appfire-ux/audit-agent@latest
+     ```
+     (postinstall runs `npx` automatically; if not, run `npx @appfire-ux/audit-agent` explicitly). Note the fresh install in the appendix.
+2. Verify post-conditions — these MUST exist before continuing:
+   - `.claude/agents/ux-auditor.md`, `.claude/agents/ui-auditor.md`
+   - `.claude/commands/ux-audit.md`, `.claude/commands/ui-audit.md`, `.claude/commands/full-audit.md`
+3. Failure handling: npm fails but older `.claude/` files exist → proceed and flag **"audit-agent possibly stale"**. npm fails and no agent files → STOP and report the npm error.
+
+### 0b — Bootstrap @appfire-ux/guidelines
+
+The audit is driven by the Appfire UX Guidelines kit (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines). Its postinstall script copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, and `guidelines/` into the project root.
 
 1. Locate the correct install directory: the repo-root `package.json`. In a monorepo, use the workspace root. If there is no `package.json` anywhere, run `npm init -y` first and note this in the report appendix.
 2. Detect an existing kit: BOTH `guidelines/` (containing `foundations/` and `personas/`) AND at least one `.cursor/rules/ux-*.mdc` must exist.
@@ -96,23 +214,25 @@ Run each pass over the scoped source. For each pass: start with the greps below
 
 ## Phase 4 — Runtime verification (best effort)
 
-Attempt only if the environment allows; NEVER let this phase break the audit — on any failure, fall back to static-only and record the limitation.
+Follow **Shared deliverables & runtime protocol** (STOP & ASK, capture order, minimum screenshots). Attempt only if the environment allows; NEVER let this phase break the audit.
 
-1. Find the dev command (`package.json` scripts: `dev`/`start`/`storybook`). Install deps if needed, start it in the background, wait for the port to answer.
-2. Capture screenshots in this explicit order — stop at the first that works:
-   1. **Browser MCP/tool available in this session** (Playwright MCP, Chrome DevTools, Claude in Chrome) → use it directly: visit the main surfaces, capture screenshots of key screens and states (save under `docs/ux-audit/assets/`), tab through primary flows to verify focus order and visible focus, trigger error/empty states where cheap to do, spot-check computed colors/contrast of flagged elements, toggle reduced-motion emulation if possible.
-   2. **No browser tool/MCP available** → you always have Bash, so shell out to the bundled Playwright capture script instead of skipping screenshots:
+1. **Resolve base URL** — check env files, README, package.json, user context, or an already-running dev server. Probe with `curl -sI` or browser before assuming a port. Record the URL in Limitations.
+2. **STOP & ASK** if blind-alley signals appear — do not proceed to analysis pretending runtime worked.
+3. Capture in order:
+   1. **Browser MCP/tool in session** → visit inventory routes; save PNGs to `docs/audits/ux-audit/assets/` (or user `--out` dir + `/assets/`); tab through primary flows for focus/contrast where possible; trigger error/empty states when cheap.
+   2. **Bundled Playwright script** (when no browser MCP):
       ```bash
-      npx playwright install chromium   # one-time, skip if already installed
+      npx playwright install chromium   # one-time
       node node_modules/@appfire-ux/audit-agent/scripts/ux-audit-capture.mjs \
-        --url http://localhost:5173 \
-        --out docs/ux-audit/assets \
-        --routes /,/dashboard/teams
+        --url <verified-base-url> \
+        --out docs/audits/ux-audit/assets \
+        --routes /,<key-routes-from-inventory> \
+        --widths 1440,768
       ```
-      This only covers screenshots (no focus/contrast/reduced-motion checks — note that limitation in the report). If the script errors (e.g. `playwright` not installed and install fails, or every route fails), fall through to 2.3.
-   3. **Both unavailable** → static-only. Record the limitation explicitly in the report appendix (Phase 6) instead of silently skipping runtime checks.
-3. If Storybook exists, prefer it for isolated component states (still via the MCP tool if available, otherwise the same Playwright script pointed at the Storybook URL).
-4. Attach evidence: reference screenshots in findings; runtime-confirmed findings get higher confidence. Screenshots captured via the Playwright script fallback are `verified-runtime` for visual findings only — accessibility findings that need interaction (focus order, keyboard reachability) stay `suspected` unless a browser MCP tool confirmed them.
+      Visual-only evidence — note in Limitations that a11y interaction checks (focus order, keyboard) stay `suspected` unless MCP confirmed them.
+   3. **Both fail** → static-only; Limitations on page 1; downgrade runtime claims.
+4. If Storybook exists, use it for isolated component states (same capture rules).
+5. Embed evidence inline in findings: `![description](assets/<route-slug>-<width>w.png)`. Reference the PNG path in the finding's Evidence line.
 
 ## Phase 5 — Synthesis & scoring
 
@@ -128,29 +248,43 @@ Per-category score: ✅ compliant / ⚠️ partial / ❌ significant gaps, plus
 
 ## Phase 6 — Write the report
 
-Write to `docs/ux-audit/UX-AUDIT-<YYYY-MM-DD>.md` (create dirs; if the user gave another location, use that). Report language: English unless asked otherwise. Structure:
+Write to `docs/audits/ux-audit/UX-AUDIT-<YYYY-MM-DD>[-prod].md` (create dirs; honor user `--out`). Report language: English unless asked otherwise.
+
+**Limitations** — if static-only or partial capture, put a prominent Limitations block immediately after the executive summary (capture URL, viewports, role, what was not reachable).
+
+Structure:
 
 1. **Executive summary** — app purpose, audited personas, overall assessment in 5–8 sentences, headline numbers (findings by severity), top 5 quick wins.
 2. **Scorecard** — table: category (A–H) → status → Critical/High/Medium/Low counts → one-line verdict.
-3. **Audit scope & method** — commit SHA, date, guidelines package version (`npm ls @appfire-ux/guidelines`), surfaces audited, static vs runtime coverage, de-scoped areas.
+3. **Audit scope & method** — commit SHA, date, `audit-agent` + `guidelines` versions, surfaces audited, capture URL & viewports, static vs runtime coverage, de-scoped areas.
 4. **Findings** — grouped by category, ordered by severity. Each finding:
    ```
    ### [UX-<CAT>-<NN>] <title>
    Severity: … | Confidence: … | Effort: S/M/L
-   Location: <file>:<line> (+ occurrence count; + screenshot if any)
+   Location: <file>:<line> (+ occurrence count)
+   Screenshot: assets/<file>.png (required for verified-runtime visual claims)
    Guideline: <kit file path> — "<the rule, quoted or tightly paraphrased>"
    Personas affected: …
-   Evidence: <≤10-line code excerpt or screenshot reference>
+   Evidence: <≤10-line code excerpt and/or ![desc](assets/file.png)>
    Recommendation: <concrete fix, with a short code sketch when useful>
    ```
 5. **State coverage matrix** — surface × {loading, empty, error, success}.
 6. **Positive observations** — what to keep doing.
 7. **Remediation roadmap** — ordered plan: quick wins → systemic fixes → strategic items.
-8. **Appendix** — bootstrap log (files added by the kit install, npm version info), limitations, `suspected` items needing human review.
+8. **Appendix** — bootstrap log, STOP & ASK events, `suspected` items needing human review.
+
+**Then generate HTML** (see Shared deliverables): run `build-html-reports.mjs` on the report directory. Confirm `.html` exists beside `.md`.
 
 ## Phase 7 — Self-verification (mandatory)
 
-Before finishing: re-open every finding and confirm the cited file:line exists and shows what the finding claims; confirm every cited guideline file exists and actually contains the referenced rule; recount occurrence numbers; delete or downgrade to `suspected` anything you cannot re-verify; check the report renders (no broken tables/links). Then summarize to the caller: report path, finding counts by severity, top 3 issues, and any limitations.
+Run the **Definition of done** checklist from Shared deliverables. Additionally:
+
+- Re-open every finding: cited `file:line` exists; guideline file contains the rule; occurrence counts accurate.
+- Every `verified-runtime` finding references an existing PNG under `assets/` or is downgraded.
+- MD and HTML render (tables, `<img src="assets/...">` links, gallery at bottom of HTML).
+- No base64 images anywhere.
+
+Summarize to the caller: MD + HTML paths, local preview URL if served, finding counts by severity, top 3 issues, capture coverage, Limitations, whether STOP & ASK was triggered.
 
 ## Operating rules
 

package/templates/commands/full-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Run ux-auditor and ui-auditor in parallel — full guideline compliance + UI/usability audit
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out-dir <path>]
+argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out-dir <path>] [--prod]
 ---
 
 Run **both** audit agents on this repository **in parallel**: **ux-auditor** (guideline compliance) and **ui-auditor** (UI & usability).
@@ -12,59 +12,92 @@ Arguments passed by the user: `$ARGUMENTS`
 - **Scope path** — optional directory (default: whole repo).
 - `--static-only` — skip runtime/screenshots for both agents; warn the user that the UI audit will be much weaker.
 - `--lang pl|en` — report language for both agents (default: English).
-- `--out-dir <path>` — parent folder for outputs (default: `docs/audits`). Individual reports go in subfolders; do not use `--out` here.
+- `--out-dir <path>` — parent folder for outputs (default: `docs/audits`).
+- `--prod` — append `-prod` to report filenames (auditing production/staging URL).
 
-Derive report paths (use today's date `YYYY-MM-DD`):
+Date slug: `YYYY-MM-DD` + optional `-prod` suffix.
 
-| Agent | Report |
-|-------|--------|
-| ux-auditor | `<out-dir>/ux-audit/UX-AUDIT-<date>.md` |
-| ui-auditor | `<out-dir>/ui-audit/UI-AUDIT-<date>.md` |
-| summary | `<out-dir>/AUDIT-SUMMARY-<date>.md` |
+## Required output layout
 
-Screenshot assets: `docs/ui-audit/assets/` and `docs/ux-audit/assets/` (per each agent's defaults) unless you consolidate under `<out-dir>/` — if so, tell both agents the same asset dir to avoid duplicate captures.
+```
+<out-dir>/
+├── AUDIT-SUMMARY-<date>[-prod].md
+├── AUDIT-SUMMARY-<date>[-prod].html
+├── prod-assets/              # only when both agents share the same PNG captures
+├── ux-audit/
+│   ├── UX-AUDIT-<date>[-prod].md
+│   ├── UX-AUDIT-<date>[-prod].html
+│   └── assets/*.png
+└── ui-audit/
+    ├── UI-AUDIT-<date>[-prod].md
+    ├── UI-AUDIT-<date>[-prod].html
+    └── assets/*.png
+```
 
-## Step 1 — Shared setup (once, before agents)
+Relative image paths in MD/HTML: `assets/<file>.png` — never base64, never `../prod-assets/`.
 
-Do this yourself in the main session — **do not** delegate to either agent yet:
+## Role division (/full-audit)
 
-1. Bootstrap `@appfire-ux/guidelines` (Phase 0 from ux-auditor): install/update, run `npx @appfire-ux/guidelines`, verify `.cursor/rules/ux-*.mdc` and `guidelines/` exist. Record bootstrap notes for the summary appendix.
-2. Unless `--static-only`: detect dev command (`npm run dev`, etc.), start **one** dev server, note the base URL. Both agents will reuse it — do not start a second server.
+| Agent | Owns | Same protocol |
+|-------|------|----------------|
+| **ux-auditor** | Guideline compliance: tokens, a11y, copy, messaging, personas | STOP & ASK, MD+HTML+PNG, Definition of done |
+| **ui-auditor** | IA, consistency, layout, interaction, responsiveness | STOP & ASK, MD+HTML+PNG, Definition of done |
 
-## Step 2 — Launch agents in parallel
+- Each agent writes to its own `ux-audit/` or `ui-audit/` subfolder with its own `assets/`.
+- Use `prod-assets/` **only** when orchestrator captures once and both agents reuse identical PNGs — then each agent copies into local `assets/` for Confluence-relative paths.
+- Do **not** duplicate capture work unless one agent needs extra viewports/states the other missed.
 
-Spawn **ux-auditor** and **ui-auditor** **concurrently** (two parallel agent tasks — not sequential).
+## Step 1 — Shared setup (once, before agents)
 
-Pass each agent this context:
+Do this in the main session — **do not** delegate yet:
 
-```
-Phase 0 (guidelines bootstrap) is ALREADY COMPLETE in the main session.
-- Kit verified at: [list key paths]
-- Dev server: [running at URL | not started — static-only]
-- Scope: [path or whole repo]
-- Language: [en|pl]
-- Report path: [agent-specific path above]
-- Asset dir: [shared or per-agent path]
-
-Skip Phase 0 npm install. Begin at your Phase 1.
-For runtime/screenshot phases: reuse the dev server URL above; do not start another server.
-When done: complete through Phase 7 and return report path, severity counts, top 3 issues, limitations.
-```
+1. **Refresh audit toolchain (Phase 0):**
+   - **0a** — `@appfire-ux/audit-agent@latest` + `npx @appfire-ux/audit-agent`
+   - **0b** — `@appfire-ux/guidelines@latest` + `npx @appfire-ux/guidelines`
+   - Record versions for the summary appendix.
+2. **Resolve base URL** — do not assume localhost. If blind-alley signals (OAuth redirect, auth wall, wrong UI) → **STOP & ASK** user with the template from ux-auditor before launching agents.
+3. Unless `--static-only`: start **one** dev server OR use user-provided logged-in URL. Note base URL for both agents.
+4. Optional shared capture: if Browser MCP or Playwright script runs here, save to `<out-dir>/prod-assets/` and tell agents to copy into their `assets/` folders.
 
-Let each agent follow its full methodology from Phase 1 onward.
+## Step 2 — Launch agents in parallel
 
-## Step 3 — Combined summary (after both finish)
+Spawn **ux-auditor** and **ui-auditor** **concurrently**.
 
-Write `<out-dir>/AUDIT-SUMMARY-<date>.md`:
+```
+Phase 0 COMPLETE. Orchestrator context:
+- audit-agent version: …
+- guidelines version: …
+- Base URL: [url | static-only]
+- Scope: …
+- Language: …
+- ux report: <out-dir>/ux-audit/UX-AUDIT-<date>[-prod].md
+- ui report: <out-dir>/ui-audit/UI-AUDIT-<date>[-prod].md
+- Shared prod-assets: [path or none — copy to local assets/ if used]
+- STOP & ASK already resolved: [yes/no — what user provided]
+
+Skip Phase 0 npm. Begin Phase 1.
+Reuse base URL; do not start another server.
+Follow Shared deliverables: MD+HTML+PNG, Definition of done.
+If STOP & ASK triggers mid-run, pause and ask user — do not fake verified-runtime.
+```
 
-1. **Executive overview** — 5–8 sentences, both lenses combined.
-2. **Reports** — links to both markdown files.
-3. **Combined scorecard** — ux-auditor categories + ui-auditor categories, total findings by severity.
-4. **Top 5 cross-cutting issues** — deduplicated; note if ux and ui flagged the same surface differently.
-5. **Handoffs merged** — items each agent deferred to the other.
-6. **Shared limitations** — static-only, capture gaps, bootstrap notes.
-7. **Suggested order of work** — quick wins that satisfy both audits first.
+## Step 3 — Combined summary + HTML (after both finish)
+
+1. Write `<out-dir>/AUDIT-SUMMARY-<date>[-prod].md`:
+   - Executive overview (both lenses)
+   - Links to both MD reports
+   - Combined scorecard + severity totals
+   - Top 5 cross-cutting issues (deduplicated)
+   - Merged handoffs
+   - Shared Limitations (URL, viewports, roles, capture gaps)
+   - Suggested remediation order
+2. Generate HTML for **all three** reports:
+   ```bash
+   node node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs --dir <out-dir>
+   ```
+   (or repo-local `docs/audits/build-html-reports.mjs` if present)
+3. Optionally serve preview: `npx --yes serve <out-dir> -p 4173` and give user links to `*.html`.
 
 ## Relay to the user
 
-Report paths, combined severity counts, top 3 issues across both audits, whether parallel run succeeded, and any limitations.
+MD + HTML paths (all three), combined severity counts, top 3 issues, capture coverage, Limitations, local preview URLs, whether parallel run and STOP & ASK occurred.

package/templates/commands/ui-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Run a UI & usability audit of this repo (consistency, IA, interaction design)
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>]
+argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>] [--prod]
 ---
 
 Use the **ui-auditor** agent to run a full UI & usability audit of this repository.
@@ -9,8 +9,11 @@ Arguments passed by the user: `$ARGUMENTS`
 
 Interpretation:
 - A path argument limits the audit scope to that directory (default: whole repo, primary-persona surfaces prioritized).
-- `--static-only` — skip Phase 3 (runtime capture); do not start the dev server. Note: this significantly weakens a UI audit — warn the user before proceeding.
+- `--static-only` — skip Phase 3 (runtime capture); warn the user this significantly weakens the audit.
 - `--lang pl` — write the report in Polish (default: English).
-- `--out <path>` — report location (default: `docs/ui-audit/UI-AUDIT-<date>.md`).
+- `--out <path>` — report MD path (default: `docs/audits/ui-audit/UI-AUDIT-<date>[-prod].md`).
+- `--prod` — append `-prod` to the report filename.
 
-Launch the agent with these parameters and let it follow its full methodology, including bootstrapping/refreshing `@appfire-ux/guidelines` (Phase 0), early screenshot capture (Phase 3), and mandatory self-verification (Phase 7). When it finishes, relay: the report path, finding counts by severity, top 3 issues, capture coverage, and any limitations it reported.
+Deliverables: **MD + HTML + PNG in `assets/`** (Confluence-ready). STOP & ASK on auth/login walls before faking visual evidence. Generate HTML via `build-html-reports.mjs` after the MD report.
+
+Launch the agent with these parameters and let it follow its full methodology, including Phase 0 toolchain refresh and Phase 7 Definition of done. Relay: MD + HTML paths, preview URL if served, finding counts, top 3 issues, capture coverage, Limitations.

package/templates/commands/ux-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Run a comprehensive UX audit of this repo against @appfire-ux/guidelines
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>]
+argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>] [--prod]
 ---
 
 Use the **ux-auditor** agent to run a full UX audit of this repository.
@@ -11,6 +11,9 @@ Interpretation:
 - A path argument limits the audit scope to that directory (default: whole repo, UI code prioritized).
 - `--static-only` — skip Phase 4 (runtime verification); do not start the dev server.
 - `--lang pl` — write the report in Polish (default: English).
-- `--out <path>` — report location (default: `docs/ux-audit/UX-AUDIT-<date>.md`).
+- `--out <path>` — report MD path (default: `docs/audits/ux-audit/UX-AUDIT-<date>[-prod].md`).
+- `--prod` — append `-prod` to the report filename (production/staging URL audit).
 
-Launch the agent with these parameters and let it follow its full methodology, including bootstrapping/refreshing `@appfire-ux/guidelines` (Phase 0) and mandatory self-verification (Phase 7). When it finishes, relay: the report path, finding counts by severity, top 3 issues, and any limitations it reported.
+Deliverables: **MD + HTML + PNG in `assets/`** (Confluence-ready). Follow STOP & ASK if runtime capture hits auth walls. Generate HTML via `build-html-reports.mjs` after the MD report.
+
+Launch the agent with these parameters and let it follow its full methodology, including Phase 0 toolchain refresh and Phase 7 Definition of done. Relay: MD + HTML paths, preview URL if served, finding counts, top 3 issues, Limitations.