@adia-ai/adia-ui-forge 0.8.62 → 0.8.63

package/skills/demo-audit/evals/routing-corpus.json

@@ -4,7 +4,7 @@
   "version": "2.1.0",
   "purpose": "Routing-eval corpus for demo-audit. Each phrase declares the skill (expected), a forbidden skill (expected_not, for phrases the source data only ever asserted as \"not this skill\"), or neither. Scored by scripts/skills/run-skill-evals.mjs (TF-IDF token overlap over per-skill description+triggers).",
   "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
-  "scope": "demo-audit routing \u2014 does this phrase activate demo-audit?",
+  "scope": "demo-audit routing, does this phrase activate demo-audit?",
   "phrases": [
     {
       "id": "demo-audit-pos-01",

package/skills/demo-audit/references/admin-shell-anatomy.md

@@ -1,31 +1,28 @@
-# Mode 5 — Admin-shell composition: the 13 canonical parts
+# Mode 5, Admin-shell composition: the 13 canonical parts
 
 Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
 `audit:shell-composition{,:strict,:all}`. Static AST walk over
-`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html` —
-no browser needed; pre-commit fast. The script's own `PARTS` array is the
-mechanical census — it has grown past this list (count it in
+`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html`, no browser needed; pre-commit fast. The script's own `PARTS` array is the
+mechanical census, it has grown past this list (count it in
 `scripts/dev/audit-shell-composition.mjs`, never from a hand-typed number
 here); this numbered list is the human review standard, and the findings
 table below samples common symptoms rather than the script's full roster.
-Canonical source: the monorepo's `site/index.html` — the markup that renders
+Canonical source: the monorepo's `site/index.html`, the markup that renders
 the live admin-dashboard example.
 
 1. `<admin-shell mode="rounded borderless">` outer (canonical mode attr)
 2. `<admin-sidebar slot="leading" resizable collapsible>` (left rail)
 3. Sidebar `<admin-topbar slot="header">` with
-   `<select-ui avatar="…" value="…" variant="ghost">` context switcher —
-   NOT `<menu-ui>` (legacy pattern) — ★ commonly mis-implemented
-4. Sidebar nav wrap around `<nav-ui>` — `<section>` (per the examples),
+   `<select-ui avatar="…" value="…" variant="ghost">` context switcher, NOT `<menu-ui>` (legacy pattern), ★ commonly mis-implemented
+4. Sidebar nav wrap around `<nav-ui>`, `<section>` (per the examples),
    `<section-ui>` (card-style chrome), or `<page-scroll>` all accepted;
    a bare `<nav-ui>` direct child overflows long lists
 5. Sidebar `<admin-statusbar slot="footer">` with `<select-ui avatar="…">`
-   (user menu) — ★ commonly missing
-6. Sidebar `<div data-sidebar-resize></div>` — REQUIRED when `resizable` is on
+   (user menu), ★ commonly missing
+6. Sidebar `<div data-sidebar-resize></div>`, REQUIRED when `resizable` is on
 7. `<admin-content>` inner `<admin-topbar>` containing
    `<button-ui data-sidebar-toggle="leading" icon="sidebar">` +
-   `<breadcrumb-ui>` + `<span data-spacer>` + `<div data-actions>` —
-   ★ spacer + actions commonly missing
+   `<breadcrumb-ui>` + `<span data-spacer>` + `<div data-actions>`, ★ spacer + actions commonly missing
 8. `[data-actions]` contains `<popover-ui>` + `<theme-panel slot="content">`
    (there is no `<theme-picker-ui>`)
 9. `<page-scroll>` wrapping optional `<aside data-subnav hidden>` +
@@ -45,31 +42,30 @@ the live admin-dashboard example.
     wrapping `page-ui[band]`). This item is kept only so this anatomy
     still recognizes the retired shape when auditing legacy surfaces
     that predate the migration; never author it in new surfaces.
-11. `<admin-statusbar>` at content footer (version strip) — ★ commonly missing
+11. `<admin-statusbar>` at content footer (version strip), ★ commonly missing
 12. Second `<admin-sidebar slot="trailing">` (inspector rail, hidden by
-    default) — strongly recommended
-13. `<admin-command>` with `<command-ui>` (cmd-K palette, top-level child) —
-    strongly recommended
+    default), strongly recommended
+13. `<admin-command>` with `<command-ui>` (cmd-K palette, top-level child), strongly recommended
 
 ## Severity mapping
 
-- **critical** — `<admin-shell>` present but structurally broken (no
+- **critical**, `<admin-shell>` present but structurally broken (no
   `<admin-content>` / no sidebar). Halt; re-author the outer composition from
   the canonical source before continuing.
-- **warning** — a commonly-missing part (3, 5, 6, 7 spacer/actions, 8, 11)
+- **warning**, a commonly-missing part (3, 5, 6, 7 spacer/actions, 8, 11)
   absent, or the wrong primitive used (`menu-ui` context switcher, native
   `<section>` where chrome was wanted).
-- **info** — parts 12–13 absent; `data-shell-opt-out=` declared.
+- **info**, parts 12–13 absent; `data-shell-opt-out=` declared.
 
 ## What the script flags (mechanical subset)
 
 | Symptom | Diagnosis |
 |---|---|
-| `<admin-shell>` with no `<admin-content>` | critical — broken outer composition |
-| sidebar missing `<admin-statusbar slot="footer">` | warning — part 5 |
-| content topbar missing `[data-spacer]` / `[data-actions]` | warning — part 7 |
-| content missing trailing `<admin-statusbar>` | warning — part 11 |
-| sidebar topbar contains only plain text | warning — part 3 context switcher |
+| `<admin-shell>` with no `<admin-content>` | critical, broken outer composition |
+| sidebar missing `<admin-statusbar slot="footer">` | warning, part 5 |
+| content topbar missing `[data-spacer]` / `[data-actions]` | warning, part 7 |
+| content missing trailing `<admin-statusbar>` | warning, part 11 |
+| sidebar topbar contains only plain text | warning, part 3 context switcher |
 | `<page-scroll>` missing around `<page-ui band>` | critical, part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+chrome wrapper the content renders flush with the topbar, no margins). **[deleted, ADR-0098 / gh#3745]** `admin-scroll` and the `admin-page` family are both deleted outright, no compat alias; the successor is `page-scroll` wrapping `page-ui[band]` |
 
 ## Opt-out contract
@@ -87,7 +83,7 @@ for reviewers to sanity-check.
 - Playground isolating ONE narrow feature → fix optional; annotating the
   opt-out is acceptable.
 - Never point this audit at `/site/components/*` demos (single-primitive
-  spotlights — every one would "miss" an admin shell) or at consumer repos
+  spotlights, every one would "miss" an admin shell) or at consumer repos
   (substrate-side tooling; consumers get the factory's forward-time pattern
   gate instead).
 - `:strict` is the CI/publish posture; keep the warn-only default while

package/skills/demo-audit/references/app-shell-pitfalls.md

@@ -1,17 +1,17 @@
-# Mode 2 — App-shell QA: pitfalls + fix recipes
+# Mode 2, App-shell QA: pitfalls + fix recipes
 
 Script: `node scripts/dev/audit-app-shells.mjs` (repo-local). Walks every
 `apps/<name>/…/<page>.html` shell headlessly and checks console errors,
 custom-element registration, collapsed heights, icon-ui presence, demo-root
 flex, and network 4xx/5xx. Flags: `--only=NAME` · `--fail-fast` ·
 `--compare-prod` (diff registered tags against the prod deploy) ·
-`--playgrounds` (gh#3197 — also sweeps `playgrounds/<name>/app/<name>.html`,
+`--playgrounds` (gh#3197, also sweeps `playgrounds/<name>/app/<name>.html`,
 same shell shape; opt-in because that root carries other pre-existing,
-unaudited findings — combine with `--only=NAME` to scope to one playground).
+unaudited findings, combine with `--only=NAME` to scope to one playground).
 
 Prerequisites: `npm run dev` running (vite `:5173`); `npm run proxy` only when
 probing chat / gen-ui pages. If vite is mid dep-reoptimization the first sweep
-may stall — wait 30s, re-run.
+may stall, wait 30s, re-run.
 
 ## Pitfall → finding map (fix recipes apply unattended)
 
@@ -23,14 +23,13 @@ may stall — wait 30s, re-run.
 | 4 | Top-level `await` without async setup wrap | `[setup-failed]` console error | `export default async function setup(host) { … }` |
 | 5 | Vite import-analysis 500 on dynamic import | `[network-4xx] 500` for `./<name>.contents.js` | add `/* @vite-ignore */` to the dynamic import |
 | 6 | icon-ui not imported despite `<icon-ui>` / `[icon=…]` / icon-rendering composites | `[icon-ui-missing]` | `import "/packages/web-components/components/icon/icon.js"` |
-| 7 | `<admin-page-body>` emitted without its `<admin-page>` ancestor (gh#981) | *(no audit-app-shells.mjs tag — apps/-only script, doesn't sweep this surface)* | wrap in `<admin-page>` — `admin-page > admin-page-body { flex:1; … }` (`admin-shell.bespoke.css:144`) is a direct-child selector; without that literal parent, `admin-page-body` falls back to UA `display:inline` — **[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-body` are retired deprecate-then-delete; author new surfaces with `page-ui[band]` instead |
+| 7 | `<admin-page-body>` emitted without its `<admin-page>` ancestor (gh#981) | *(no audit-app-shells.mjs tag, apps/-only script, doesn't sweep this surface)* | wrap in `<admin-page>`, `admin-page > admin-page-body { flex:1; … }` (`admin-shell.bespoke.css:144`) is a direct-child selector; without that literal parent, `admin-page-body` falls back to UA `display:inline`, **[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-body` are retired deprecate-then-delete; author new surfaces with `page-ui[band]` instead |
 
-Secondary signals: `[collapsed-element]` (registered but 0px tall —
-`audit-app-shells.mjs`'s own threshold is <4px, so a shallower-but-still-broken
+Secondary signals: `[collapsed-element]` (registered but 0px tall, `audit-app-shells.mjs`'s own threshold is <4px, so a shallower-but-still-broken
 collapse won't trip it), `[network-4xx]` (typoed stylesheet href, missing
 contents.html, stale `import.meta.url`). Row 7's specific case (gh#981, in
 `site/site.js`'s router, not swept by this script at all): the 150px isn't
-`admin-page-body`'s own height — it's a *replaced child* (an `<iframe>`)
+`admin-page-body`'s own height, it's a *replaced child* (an `<iframe>`)
 whose `height:100%` can't resolve, so it falls back to the browser's
 intrinsic default (300×150). The observable is a body rendering ~150px tall
 with no console error, regardless of real content height.
@@ -51,11 +50,11 @@ with no console error, regardless of real content height.
 ## Registration diagnosis rules
 
 - Bespoke shell children (`admin-sidebar`, `chat-thread`, `editor-sidebar`, …)
-  register only when their sibling JS loads — importing `admin-shell.js` alone
+  register only when their sibling JS loads, importing `admin-shell.js` alone
   registers ONLY the host. Use the cluster barrel
   `/packages/web-modules/<cluster>/index.js`.
 - Some tags register in their **parent component's** `.js`, not a directory of
-  their own name — when deciding whether a tag is real, grep
+  their own name, when deciding whether a tag is real, grep
   `customElements.define`, never `ls components/`.
 - `customElements.whenDefined(name)` never rejects; an un-imported name leaves
   the promise pending forever. A `Promise.all([...]).then(bootstrap)` gate then
@@ -64,15 +63,14 @@ with no console error, regardless of real content height.
 
 ## False positives (already filtered by the script)
 
-- CSS-only components (`aside-ui`, `header-ui`, `section-ui`, `footer-ui`) —
-  some components ship `.yaml` + `.a2ui.json` with no `.js` by design; they are
+- CSS-only components (`aside-ui`, `header-ui`, `section-ui`, `footer-ui`), some components ship `.yaml` + `.a2ui.json` with no `.js` by design; they are
   real, not stubs.
 - Inherently thin elements (`divider-ui`, `separator-ui`); empty containers
   with no children.
 
 ## Verification + escalation
 
-1. Apply diffs; re-run the audit — target 0 findings on real issues.
+1. Apply diffs; re-run the audit, target 0 findings on real issues.
 2. Spot-check the worst-affected page in a real browser.
 3. Escalate when: a finding matches no pitfall above, >10 shells are affected,
    or the fix would alter shared `catalog/` or `packages/` files.

package/skills/demo-audit/references/auto-fix-allowlist.md

@@ -1,8 +1,8 @@
-# Auto-fix allowlist — BUILDER-ONLY, the ONLY unattended fixes
+# Auto-fix allowlist, BUILDER-ONLY, the ONLY unattended fixes
 
 **Routing:** every row below is a mutation (`perl -i`, in-place CSS/JS edits).
 A read-only seat holds Bash, and Bash alone can run `perl -i` / `sed -i` /
-`node -e` with a file write even without a Write or Edit tool — the tool
+`node -e` with a file write even without a Write or Edit tool: the tool
 allowlist is not the enforcement boundary, the routing rule is: these fixes
 are executed by `primitive-authoring-agent` (or a human), never dispatched to or run
 by `demo-audit-agent` or any other read-only dogfood seat. A read-only run
@@ -23,4 +23,4 @@ unrecognized component, native-primitive replacement (attribute-shape
 decisions), card-header wrapper hoists (slot intent), any warning without an
 allowlist row.
 **NEVER exceed 5 mechanical fixes per PR or apply a fix outside this
-allowlist** — blast radius stays human-reviewable.
+allowlist**, blast radius stays human-reviewable.

package/skills/demo-audit/references/card-anatomy-sweep.md

@@ -1,14 +1,14 @@
-# Mode 6 — Card structure + anatomy docs coverage
+# Mode 6, Card structure + anatomy docs coverage
 
 Three probes; all static, pre-commit fast.
 
-## Probe A — card-ui header `<div>` wrapper (grep, warning)
+## Probe A, card-ui header `<div>` wrapper (grep, warning)
 
 Header content wrapped in a bare `<div>` (no `slot=`) inside a `<card-ui>`
 `<header>` bypasses card-ui's `:has(> [slot])` grid activator: title + badge
 collapse into one full-width row instead of the 1fr-heading + auto-action
-grid. **No console error — pure silent visual regression.** (The header grid
-comes from the card's `@scope` — `header-ui` has no CSS of its own — so only
+grid. **No console error, pure silent visual regression.** (The header grid
+comes from the card's `@scope`, `header-ui` has no CSS of its own, so only
 correctly-slotted direct children activate it.)
 
 ```bash
@@ -27,12 +27,12 @@ while read -r file; do
 done
 ```
 
-Fix (manual only — never auto-fix; which child gets `slot="action"` is
+Fix (manual only, never auto-fix; which child gets `slot="action"` is
 intent): hoist the children out of the wrapper `<div>`, apply `slot="action"`
-to trailing badges/buttons. Scope stays `<card-ui>`-ancestored — the
+to trailing badges/buttons. Scope stays `<card-ui>`-ancestored: the
 `<div>`-wrapper pattern is acceptable in admin-topbar / drawer-ui headers.
 
-## Probe B — card-ui body contract (npm gate, warning)
+## Probe B, card-ui body contract (npm gate, warning)
 
 `npm run audit:card-structure` (`:strict` for CI). Direct flow children of
 `<card-ui>` other than `<img>` / `<header>` / `<section>` / `<footer>` skip
@@ -40,7 +40,7 @@ the canonical body slot: `<section>`'s `margin: var(--card-inset)` is lost AND
 the gen-UI corpus harvests the broken pattern as a training exemplar. Fix:
 wrap in `<section>` (`<section bleed>` to zero the inset).
 
-## Probe C — anatomy section coverage (grep + sweep, info)
+## Probe C, anatomy section coverage (grep + sweep, info)
 
 A component's `*.examples.html` missing all of the schema-derivable anatomy
 sections (`props` / `events` / `slots` / `data-attrs` / `keyboard` /
@@ -55,12 +55,11 @@ done
 
 Fix: `node scripts/docs/anatomy-sweep.mjs` (preview with `--dry`) populates
 sections from the `.a2ui.json` sidecar + yaml. Still skipped after the sweep →
-the yaml is missing `props:`/`events:`/`slots:` declarations — investigate the
+the yaml is missing `props:`/`events:`/`slots:` declarations, investigate the
 yaml, don't hand-author the section. Info-level only: CSS-only primitives
 legitimately ship with just a `usage` section.
 
 ## When to run
 
 After any wide screen-authoring sweep that generated `<card-ui>` blocks; after
-a new-component yaml + examples author pass; before a docs-site refresh —
-target 0 findings or explicit opt-outs.
+a new-component yaml + examples author pass; before a docs-site refresh, target 0 findings or explicit opt-outs.

package/skills/demo-audit/references/chat-shell-anatomy.md

@@ -1,11 +1,10 @@
-# Mode 5b — Chat-shell composition: the canonical parts
+# Mode 5b, Chat-shell composition: the canonical parts
 
 Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
 `audit:shell-composition{,:strict,:all}`. Static AST walk over
-`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html` —
-no browser needed; pre-commit fast. Shares one script and one output
+`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html`, no browser needed; pre-commit fast. Shares one script and one output
 contract with the `<admin-shell>` census
-([admin-shell-anatomy](admin-shell-anatomy.md)) — the script's own `CHAT_PARTS`
+([admin-shell-anatomy](admin-shell-anatomy.md)): the script's own `CHAT_PARTS`
 array is the mechanical census; this file is the human review standard.
 Canonical source: `packages/web-modules/chat/chat-shell/chat-shell.yaml`
 (the behavioral contract) and `playgrounds/chat/app/chat.contents.html`
@@ -14,59 +13,59 @@ chrome-decision table as chat-shell's canonical demo).
 
 `gh#2909`/`apps/genui/PATTERNS.md:329-337` established that `apps/genui`
 (gen-ui, factory-chat) is a real `<chat-shell>` consumer that a
-`<admin-shell>`-only mode 5 sweep never scanned — this anatomy closes that
+`<admin-shell>`-only mode 5 sweep never scanned, this anatomy closes that
 blind spot.
 
 ## The canonical parts
 
 1. `<chat-shell provider="…" model="…" proxy-url="…">` outer.
-2. `<chat-thread>` direct child — the message scroll surface. Required:
+2. `<chat-thread>` direct child, the message scroll surface. Required:
    without it there is nowhere for the host's rendering pipeline to append
    messages.
-3. `<chat-thread> > <chat-empty>` as (typically first) child — the
+3. `<chat-thread> > <chat-empty>` as (typically first) child, the
    empty-state placeholder shown via the `[empty]` reflected attribute
    before any message exists.
-4. `<chat-composer>` direct child — the input region.
-5. `<chat-composer> > <chat-input-ui>` (or `<input-ui>`) inner child — the
+4. `<chat-composer>` direct child, the input region.
+5. `<chat-composer> > <chat-input-ui>` (or `<input-ui>`) inner child, the
    actual input; a composer with no primitive input inside has nothing to
    submit.
-6. `<chat-header>` direct child — optional top chrome bar (name, status,
+6. `<chat-header>` direct child, optional top chrome bar (name, status,
    actions). When present, expected to carry `[slot="name"]` and
-   `[slot="status"]` (typically a `<chat-status>`) — a header with neither
+   `[slot="status"]` (typically a `<chat-status>`), a header with neither
    is bare chrome with no identifying content.
-7. `<chat-sidebar slot="leading"|"trailing">` — optional conversation-history
+7. `<chat-sidebar slot="leading"|"trailing">`, optional conversation-history
    or inspector rail.
 8. No generic layout primitive (`<col-ui>`, `<row-ui>`, `<stack-ui>`) as a
-   **direct child** of `<chat-shell>` — the shell's CSS lays out children by
+   **direct child** of `<chat-shell>`, the shell's CSS lays out children by
    tag selector (`chat-thread`, `chat-composer`, etc.); a generic wrapper
    defeats that and the shell's `:has(chat-thread[streaming])` cross-cut
    styling.
 
 ## Severity mapping
 
-- **critical** — `<chat-shell>` present but missing `<chat-thread>` or
+- **critical**, `<chat-shell>` present but missing `<chat-thread>` or
   `<chat-composer>` (parts 2, 4). The shell can't render a usable
   conversation surface without both.
-- **warning** — `<chat-composer>` has no inner `<chat-input-ui>`/`<input-ui>`
+- **warning**, `<chat-composer>` has no inner `<chat-input-ui>`/`<input-ui>`
   (part 5); a `<chat-header>` present but missing both `[slot="name"]` and
   `[slot="status"]` content (part 6); a generic layout primitive
   (`col-ui`/`row-ui`/`stack-ui`) authored as a direct child (part 8).
-- **info** — `<chat-thread>` missing its `<chat-empty>` first child (part 3;
+- **info**, `<chat-thread>` missing its `<chat-empty>` first child (part 3;
   a thread pre-seeded with real messages legitimately skips this);
   `<chat-header>` absent entirely (part 6 is optional chrome);
-  `<chat-sidebar>` absent (part 7, forward-looking per the yaml — chat is
+  `<chat-sidebar>` absent (part 7, forward-looking per the yaml, chat is
   typically single-pane).
 
 ## What the script flags (mechanical subset)
 
 | Symptom | Diagnosis |
 |---|---|
-| `<chat-shell>` with no `<chat-thread>` | critical — part 2 |
-| `<chat-shell>` with no `<chat-composer>` | critical — part 4 |
-| `<chat-composer>` with no `<chat-input-ui>`/`<input-ui>` child | warning — part 5 |
-| `<chat-header>` present, no `[slot="name"]` and no `[slot="status"]`/`<chat-status>` | warning — part 6 |
-| `<chat-shell>` direct child is `col-ui`/`row-ui`/`stack-ui` | warning — part 8 (legacy-generic-layout leak) |
-| `<chat-thread>` with no `<chat-empty>` child | info — part 3 |
+| `<chat-shell>` with no `<chat-thread>` | critical, part 2 |
+| `<chat-shell>` with no `<chat-composer>` | critical, part 4 |
+| `<chat-composer>` with no `<chat-input-ui>`/`<input-ui>` child | warning, part 5 |
+| `<chat-header>` present, no `[slot="name"]` and no `[slot="status"]`/`<chat-status>` | warning, part 6 |
+| `<chat-shell>` direct child is `col-ui`/`row-ui`/`stack-ui` | warning, part 8 (legacy-generic-layout leak) |
+| `<chat-thread>` with no `<chat-empty>` child | info, part 3 |
 
 ## Opt-out contract
 
@@ -82,17 +81,17 @@ info and prints the reason for reviewers.
   optional; annotate the opt-out.
 - Never point this audit at `packages/web-modules/chat/**/*.examples.html`
   or `packages/web-components/components/*/*.html` (single-primitive
-  spotlights) — the script's `isShowcaseDemo`/showcase-path exclusion
+  spotlights), the script's `isShowcaseDemo`/showcase-path exclusion
   already keeps those out of scope, same as admin-shell.
 - `:strict` is the CI/publish posture; keep warn-only while iterating
   locally.
 
-## Legacy shapes — never re-authored
+## Legacy shapes, never re-authored
 
 `chat-shell.yaml`'s own description lists the ADR-0024-retired legacy
 data-attribute shapes (`<section data-chat-messages>`, `<chat-input-ui
 data-chat-input>`, `<empty-state-ui data-chat-empty>`, `<header
 data-chat-name>`) as silently unrecognized, not merely deprecated. This
 audit does not re-detect them (a separate concern from anatomy
-completeness) — `verify:no-legacy-shell-shapes` in `npm run check` already
+completeness), `verify:no-legacy-shell-shapes` in `npm run check` already
 covers that ground.

package/skills/demo-audit/references/editor-shell-anatomy.md

@@ -1,11 +1,10 @@
-# Mode 5c — Editor-shell composition: the canonical parts
+# Mode 5c, Editor-shell composition: the canonical parts
 
 Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
 `audit:shell-composition{,:strict,:all}`. Static AST walk over
-`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html` —
-no browser needed; pre-commit fast. Shares one script and one output
+`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html`, no browser needed; pre-commit fast. Shares one script and one output
 contract with the `<admin-shell>` census
-([admin-shell-anatomy](admin-shell-anatomy.md)) — the script's own
+([admin-shell-anatomy](admin-shell-anatomy.md)): the script's own
 `EDITOR_PARTS` array is the mechanical census; this file is the human
 review standard. Canonical source:
 `packages/web-modules/editor/editor-shell/editor-shell.yaml` (the
@@ -16,63 +15,62 @@ chrome-decision table as editor-shell's canonical demo, alongside
 
 `gh#2909`/`apps/genui/PATTERNS.md:329-337` established that `apps/genui`
 (a2ui-editor) is a real `<editor-shell>` consumer that a
-`<admin-shell>`-only mode 5 sweep never scanned — this anatomy closes that
+`<admin-shell>`-only mode 5 sweep never scanned, this anatomy closes that
 blind spot.
 
 ## The canonical parts
 
 1. `<editor-shell>` outer.
-2. `<editor-canvas>` direct child — the central work surface. Required:
+2. `<editor-canvas>` direct child, the central work surface. Required:
    without it there is nowhere for artboards/document body/canvas content
    to land, the editor equivalent of admin-shell's `<admin-content>`.
-3. `<editor-toolbar>` direct child — the app-scope top chrome bar (document
+3. `<editor-toolbar>` direct child, the app-scope top chrome bar (document
    title, run/save/undo/redo, focus-mode toggle). Recommended; an editor
    with no toolbar has no document-wide action surface.
-4. `<editor-canvas> > <editor-canvas-empty>` as (typically first) child —
-   the empty-state placeholder shown via the parent's `[empty]` reflected
+4. `<editor-canvas> > <editor-canvas-empty>` as (typically first) child, the empty-state placeholder shown via the parent's `[empty]` reflected
    attribute before any content exists.
-5. `<editor-canvas> > <editor-canvas-toolbar>` — optional canvas-scope
+5. `<editor-canvas> > <editor-canvas-toolbar>`, optional canvas-scope
    chrome (view-mode tabs, breadcrumbs) sticky to the canvas top edge;
    distinct from part 3's app-scope toolbar.
-6. `<editor-statusbar>` direct child — bottom chrome bar (save/sync state,
+6. `<editor-statusbar>` direct child, bottom chrome bar (save/sync state,
    zoom, cursor position). Recommended; loses the canonical status-strip
    without it.
-7. `<editor-sidebar slot="leading"|"trailing">` — optional navigator or
+7. `<editor-sidebar slot="leading"|"trailing">`, optional navigator or
    inspector rail.
 8. When an `<editor-sidebar>` is present, it must wrap `<pane-ui
-   resizable>` (or at minimum `<pane-ui>`) — editor-sidebar is the one
+   resizable>` (or at minimum `<pane-ui>`), editor-sidebar is the one
    bespoke shell child that **delegates** rather than duplicates a
    primitive's resize behavior (per `shell-patterns.md`'s "FIRST bespoke
    shell child that delegates" note); an editor-sidebar with no inner
    `<pane-ui>` reimplements drag by hand instead of reusing the primitive.
 9. No bare `<header>` / `<footer>` native elements as direct children of
-   `<editor-shell>` — these are the ADR-0024-retired legacy chrome shapes
+   `<editor-shell>`: these are the ADR-0024-retired legacy chrome shapes
    that `<editor-toolbar>` / `<editor-statusbar>` replaced.
 
 ## Severity mapping
 
-- **critical** — `<editor-shell>` present but missing `<editor-canvas>`
+- **critical**, `<editor-shell>` present but missing `<editor-canvas>`
   (part 2). The shell can't render usable content without it.
-- **warning** — no `<editor-toolbar>` (part 3); no `<editor-statusbar>`
+- **warning**, no `<editor-toolbar>` (part 3); no `<editor-statusbar>`
   (part 6); an `<editor-sidebar>` present with no inner `<pane-ui>` (part
   8); a bare native `<header>`/`<footer>` direct child (part 9, the
   retired-legacy-shape leak).
-- **info** — `<editor-canvas>` missing its `<editor-canvas-empty>` first
+- **info**, `<editor-canvas>` missing its `<editor-canvas-empty>` first
   child (part 4; a canvas pre-seeded with real content legitimately skips
   this); no `<editor-canvas-toolbar>` (part 5, optional canvas chrome); no
-  `<editor-sidebar>` at all (part 7 — `construct-canvas`'s own comment
+  `<editor-sidebar>` at all (part 7, `construct-canvas`'s own comment
   notes "no leading pane today", a legitimately sidebar-less composition).
 
 ## What the script flags (mechanical subset)
 
 | Symptom | Diagnosis |
 |---|---|
-| `<editor-shell>` with no `<editor-canvas>` | critical — part 2 |
-| `<editor-shell>` with no `<editor-toolbar>` | warning — part 3 |
-| `<editor-shell>` with no `<editor-statusbar>` | warning — part 6 |
-| `<editor-sidebar>` present, no inner `<pane-ui>` | warning — part 8 (delegation contract violated) |
-| `<editor-shell>` direct child is native `<header>`/`<footer>` | warning — part 9 (retired-legacy-shape leak) |
-| `<editor-canvas>` with no `<editor-canvas-empty>` child | info — part 4 |
+| `<editor-shell>` with no `<editor-canvas>` | critical, part 2 |
+| `<editor-shell>` with no `<editor-toolbar>` | warning, part 3 |
+| `<editor-shell>` with no `<editor-statusbar>` | warning, part 6 |
+| `<editor-sidebar>` present, no inner `<pane-ui>` | warning, part 8 (delegation contract violated) |
+| `<editor-shell>` direct child is native `<header>`/`<footer>` | warning, part 9 (retired-legacy-shape leak) |
+| `<editor-canvas>` with no `<editor-canvas-empty>` child | info, part 4 |
 
 ## Opt-out contract
 
@@ -88,17 +86,16 @@ info and prints the reason for reviewers.
   optional; annotate the opt-out.
 - Never point this audit at `packages/web-modules/editor/**/*.examples.html`
   or `packages/web-components/components/*/*.html` (single-primitive
-  spotlights) — the script's `isShowcaseDemo`/showcase-path exclusion
+  spotlights), the script's `isShowcaseDemo`/showcase-path exclusion
   already keeps those out of scope, same as admin-shell.
-- **Don't nest `<editor-shell>` inside `<admin-shell>`** as page chrome —
-  `editor-shell.examples.html` documents them as sibling surfaces, not
+- **Don't nest `<editor-shell>` inside `<admin-shell>`** as page chrome, `editor-shell.examples.html` documents them as sibling surfaces, not
   nested; this audit doesn't mechanically flag the nesting mistake (a
   cross-shell structural rule, not a within-shell anatomy gap), but a
   reviewer seeing both tags in one file should treat it as a design smell.
 - `:strict` is the CI/publish posture; keep warn-only while iterating
   locally.
 
-## Legacy shapes — never re-authored
+## Legacy shapes, never re-authored
 
 `editor-shell.yaml`'s own description lists the ADR-0024-retired legacy
 data-attribute shapes (`<header>`, `<div data-editor-body>`, `<pane-ui

package/skills/demo-audit/references/html-attr-sweep.md

@@ -1,7 +1,7 @@
-# Mode 3 — HTML attr-quote typo sweep
+# Mode 3, HTML attr-quote typo sweep
 
 Bug class: an attribute value opens with `"`, embeds unescaped `"` characters,
-and closes with another `"` — the parser closes the value at the second quote
+and closes with another `"`, the parser closes the value at the second quote
 and sprays the rest as junk attributes:
 
 ```html
@@ -10,14 +10,14 @@ and sprays the rest as junk attributes:
 ```
 
 Sibling traps in the same family: `\"` inside attribute values (JSON pasted
-into HTML — backslash escapes don't exist in HTML) and `data-x=""…` (an
-entity-opened quote never closed) — both swallow the parser past the next
+into HTML, backslash escapes don't exist in HTML) and `data-x=""…` (an
+entity-opened quote never closed), both swallow the parser past the next
 quote. Sweep them with the same one-attribute-at-a-time discipline.
 
 Scope: rendered HTML files only. Not for `<script>` blocks, JS template
 literals, Markdown, JSX, or single isolated typos (targeted edit instead).
 
-## Audit (narrow regex — never a broad one)
+## Audit (narrow regex, never a broad one)
 
 ```js
 // An attribute closes with " and the next char is not whitespace or >
@@ -31,29 +31,28 @@ Attribute order (run each independently, never one glob regex over all):
 `data-artifact-label` → `data-note` → `aria-label` → `title` → `alt` →
 `placeholder`.
 
-## Fix (greedy capture — stops at `>`, never crosses a tag boundary)
+## Fix (greedy capture, stops at `>`, never crosses a tag boundary)
 
 ```js
 const FIX = new RegExp(
   `${ATTR}="([^>]*[a-z0-9][a-z0-9_-]*="[^"]*")"(?=[\\s>])`, 'g');
 const fixed = html.replace(FIX, (_m, value) =>
   value.includes("'")
-    ? `${ATTR}="${value.replace(/"/g, '&quot;')}"`   // value has ' — entity-escape
+    ? `${ATTR}="${value.replace(/"/g, '&quot;')}"`   // value has ', entity-escape
     : `${ATTR}='${value}'`);                          // else single-quote outside
 ```
 
 Remaining hits after the automated pass are edge cases (trailing prose, no
-`ident=` prefix) — fix each with a targeted edit; do not extend the regex.
+`ident=` prefix), fix each with a targeted edit; do not extend the regex.
 
 ## Anti-patterns
 
-- Never sweep with a broad regex like `="[^"]*"[^"]*"` across all attributes —
-  thousands of false positives on legitimate multi-attribute tags.
-- Never use the non-greedy capture variant — it stops at the first `"` and
+- Never sweep with a broad regex like `="[^"]*"[^"]*"` across all attributes, thousands of false positives on legitimate multi-attribute tags.
+- Never use the non-greedy capture variant, it stops at the first `"` and
   captures only `name=` instead of `name="attachment"`.
-- Never run the regexes inside `<script>` blocks — JS quoting rules differ.
+- Never run the regexes inside `<script>` blocks, JS quoting rules differ.
 - Never skip the re-audit after the automated pass.
-- Never commit the one-shot script — run from the scratchpad or `node -e`.
+- Never commit the one-shot script, run from the scratchpad or `node -e`.
 
 ## Verification (all three)
 

package/skills/demo-audit/references/mode7-status-battery.md

@@ -1,8 +1,8 @@
-# Mode 7 — the `dogfood:status` battery
+# Mode 7, the `dogfood:status` battery
 
 `npm run dogfood:status` runs seven static-analysis audits and aggregates them
 into `qa/findings/dogfood-tracker.md` (the "what's open right now" ledger, on
-its own P0–P3 severity scale — see the script's header comment, distinct from
+its own P0–P3 severity scale, see the script's header comment, distinct from
 the critical/warning/info contract modes 1–6 use):
 
 - `audit:warning-strong-vs-bg`
@@ -14,9 +14,9 @@ the critical/warning/info contract modes 1–6 use):
 - `audit:icon-color-inherit`
 
 Each is also runnable standalone with `--json`/`:strict`. Fix templates are
-inline in `scripts/qa/dogfood-status.mjs`'s `AUDITS` array — no separate
+inline in `scripts/qa/dogfood-status.mjs`'s `AUDITS` array, no separate
 reference doc for this mode.
 
-`npm run dogfood:status` does **not** roll up modes 1–6 — it runs only this
+`npm run dogfood:status` does **not** roll up modes 1–6, it runs only this
 mode-7 battery. Regenerate the ledger after any mode-7 sweep; modes 1–6 file
 their own reports per SKILL.md's "Findings home + PR shape" section.