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

package/skills/site-docs-authoring/intent.md

@@ -1,4 +1,4 @@
-# intent — site-docs-authoring
+# intent, site-docs-authoring
 status: shipped
 species: procedural
 dials: { disable-model-invocation: false, user-invocable: true }
@@ -10,7 +10,7 @@ plan (`.claude/plans/enchanted-singing-globe.md`, "Site docs review +
 authoring method") and this session's own research (3 parallel Explore
 agents surveying `site/pages/`'s structure, a color-contrast root-cause
 investigation, and a review of existing tooling) rather than a live
-turn-by-turn interview — the operator confirmed the plan, including
+turn-by-turn interview, the operator confirmed the plan, including
 "doc + a dedicated skill" as the Phase 4 method depth, before this
 skill was forged. Slots below are answered from that record, not
 fabricated dialogue.
@@ -23,22 +23,22 @@ should:
   - "author a new page under site/pages/getting-started"
   - "is this site page consistent with our conventions"
 should_not:
-  - "review this component demo gallery" (packages/web-components/components/*/*.examples.html — primitive-authoring)
-  - "fix this gen-ui training exemplar page" (site/pages/examples/**, site/pages/gen-ui/** — composition-and-examples.md's no-style-block rule + a2ui-maintenance)
+  - "review this component demo gallery" (packages/web-components/components/*/*.examples.html, primitive-authoring)
+  - "fix this gen-ui training exemplar page" (site/pages/examples/**, site/pages/gen-ui/**, composition-and-examples.md's no-style-block rule + a2ui-maintenance)
 
 ## delta
 Without this skill, Claude (or a human author) reaches for whatever
 looks locally plausible on a `site/pages/*.html` page and repeats the
 defect classes this session found and fixed: a fabricated `data-*`
 attribute standing in for a real primitive (16 of 34 pages had
-`data-alert="warning|info"` with ZERO matching CSS anywhere — dead
+`data-alert="warning|info"` with ZERO matching CSS anywhere, dead
 markup that silently renders as plain paragraphs), a hand-rolled
 `<style>` block duplicating an existing shared utility (4 pages
 independently reinvented the same "tame this admin-shell demo" CSS),
 and a background token picked for its "feels dark and subtle" name
 rather than its actual measured contrast (inline `<code>` used
 `--a-canvas-well`, hand-measured at ~1.1:1 against
-the page background — WCAG 2.2 SC 1.4.11 wants ≥3:1). All three are
+the page background, WCAG 2.2 SC 1.4.11 wants ≥3:1). All three are
 now fixed at the shared-CSS/token level (cascades to all 34 pages),
 but a NEW page authored without this skill's guidance would
 re-introduce the same classes on page 35. Deleted after a month: the
@@ -49,24 +49,24 @@ before they start typing.
 
 ## fences
 - NOT for `packages/web-components/components/*/*.examples.html` component demo pages (primitive-authoring)
-- NOT for `site/pages/examples/**`, `site/pages/gen-ui/**`, `packages/gen-ui/a2ui/corpus/exemplars/**` — pure primitive-composition training-harvest surfaces with their own no-style-block rule (`composition-and-examples.md`, a2ui-maintenance)
+- NOT for `site/pages/examples/**`, `site/pages/gen-ui/**`, `packages/gen-ui/a2ui/corpus/exemplars/**`, pure primitive-composition training-harvest surfaces with their own no-style-block rule (`composition-and-examples.md`, a2ui-maintenance)
 - NOT for the A2UI generation pipeline itself, chunk corpus, or MCP tools (a2ui-maintenance)
 
 ## assertions
-1. A new callout block the skill produces uses `<alert-ui variant="...">` with a `[slot="content"]` wrapper for rich text — never a bare `data-*` attribute with no matching CSS.
-2. A new tamed-demo page the skill produces adds `class="demo-frame"` plus only a page-local `--demo-frame-height` override — it does not restate `position`/`border`/`overflow`/`.demo-body` padding.
+1. A new callout block the skill produces uses `<alert-ui variant="...">` with a `[slot="content"]` wrapper for rich text, never a bare `data-*` attribute with no matching CSS.
+2. A new tamed-demo page the skill produces adds `class="demo-frame"` plus only a page-local `--demo-frame-height` override, it does not restate `position`/`border`/`overflow`/`.demo-body` padding.
 3. When asked to review an existing page, the skill's output names the specific rule from `site-pages-authoring.md` a defect violates (not just "this looks off").
 4. The skill's own description correctly declines to fire on a component `.examples.html` demo or a `site/pages/examples/**` training page (see `should_not` above) and instead names the owning sibling skill.
 
 ## gates
-P0 route:      PASS — 2026-07-14 — knowledge/procedure needed on demand (author or review a site/pages doc), not mechanically checkable (hook), not always-true-every-turn (entry file), no tool-wall/parallelism need (agent). Skill.
-P1 intent:     PASS — 2026-07-14 — slots filled from the approved plan + this session's research; operator confirmed the plan's Phase 4 scope (doc + dedicated skill) via AskUserQuestion before forging began.
-P2 evals:      PASS — 2026-07-14 — see evals/routing-corpus.json (trigger cases, matching this repo's primitive-authoring sibling's own eval-file convention) and assertions above (behavioral). No literal fresh-session baseline captured (this is a same-session, plan-driven forge, not an interactive intent interview) — the delta section above records the concrete "without this skill" failure mode from direct evidence (the 3 defect classes this session found and fixed) in place of a baseline transcript.
-P3 draft:      PASS — 2026-07-14 — SKILL.md + evals/routing-corpus.json exist; both dials explicit; body 61 lines, well under the 500-line budget.
-P4 language:   PASS — 2026-07-14 — self-audited against the 5 instantiation checks: task-shape rows commit to concrete actions (not descriptions); ~3 hard-gate ceiling held (never restate demo-frame properties, never a bare data-* callout, don't reach for a raw ramp step without color-verify); numeric anchors present (>=3:1, 34-page, 4 rules); contracts (task-shape table) precede the verify-steps tail; the labeled good/bad alert-ui pair lives in the referenced convention doc rather than duplicated here (reference, never restate).
-P5 validate:   PASS — 2026-07-14 — skill_lint.py clean; skill-auditor FLOOR audit verdict PASS (report at evals/audit-report.md), 3 minor non-blocking findings, all fixed same-change (phantom fence trimmed to reference composition-and-examples.md by name rather than specific paths; 2 negative imperatives demoted to positive form; intent.md's routing-corpus.json citation corrected). No fence-reciprocity step run against primitive-authoring's own evals — primitive-authoring's corpus already covers "primitive authoring" as should_route_to_author:true, which is the correct answer for those phrases; no reciprocal edit needed there.
+P0 route:      PASS, 2026-07-14, knowledge/procedure needed on demand (author or review a site/pages doc), not mechanically checkable (hook), not always-true-every-turn (entry file), no tool-wall/parallelism need (agent). Skill.
+P1 intent:     PASS, 2026-07-14, slots filled from the approved plan + this session's research; operator confirmed the plan's Phase 4 scope (doc + dedicated skill) via AskUserQuestion before forging began.
+P2 evals:      PASS, 2026-07-14, see evals/routing-corpus.json (trigger cases, matching this repo's primitive-authoring sibling's own eval-file convention) and assertions above (behavioral). No literal fresh-session baseline captured (this is a same-session, plan-driven forge, not an interactive intent interview), the delta section above records the concrete "without this skill" failure mode from direct evidence (the 3 defect classes this session found and fixed) in place of a baseline transcript.
+P3 draft:      PASS, 2026-07-14, SKILL.md + evals/routing-corpus.json exist; both dials explicit; body 61 lines, well under the 500-line budget.
+P4 language:   PASS, 2026-07-14, self-audited against the 5 instantiation checks: task-shape rows commit to concrete actions (not descriptions); ~3 hard-gate ceiling held (never restate demo-frame properties, never a bare data-* callout, don't reach for a raw ramp step without color-verify); numeric anchors present (>=3:1, 34-page, 4 rules); contracts (task-shape table) precede the verify-steps tail; the labeled good/bad alert-ui pair lives in the referenced convention doc rather than duplicated here (reference, never restate).
+P5 validate:   PASS, 2026-07-14, skill_lint.py clean; skill-auditor FLOOR audit verdict PASS (report at evals/audit-report.md), 3 minor non-blocking findings, all fixed same-change (phantom fence trimmed to reference composition-and-examples.md by name rather than specific paths; 2 negative imperatives demoted to positive form; intent.md's routing-corpus.json citation corrected). No fence-reciprocity step run against primitive-authoring's own evals, primitive-authoring's corpus already covers "primitive authoring" as should_route_to_author:true, which is the correct answer for those phrases; no reciprocal edit needed there.
 
 ## rulings
-- Accepted with note: no literal fresh-session baseline transcript (P2) — this forge ran from an already-approved plan's research rather than a live interview; the delta section's direct evidence substitutes. Not re-litigated.
-- Accepted with note: convention doc lives at `.claude/docs/conventions/site-pages-authoring.md`, not inside this skill's own `references/` — deliberate, to avoid a drift pair with the doc that's also linked from `document-routing.md`.
-- Post-ship correction (same session, before task close): the skill's own Rule-2 example used `<span slot="content">` — a real bug, not just a style choice. `scripts/build/lib/docs-transpiler.mjs`'s `PROSE_CONTAINERS` only recognizes `p`/`div`/`ul`/`ol`; `<span>` fell to a different decomposition path that silently reordered mixed inline content (a leading `<strong>` rendered AFTER the surrounding text, bold dropped) once the compiled `site-a2ui/pages/*.json` regenerated — invisible to schema validation (`valid:true`) and to a raw-HTML read, only caught by a live-browser check. Fixed in SKILL.md, the convention doc, and all 16 already-migrated `site/pages/*.html` files (`<span>` → `<div>`). Added "visually verify" as a non-optional Verify step for this content shape.
+- Accepted with note: no literal fresh-session baseline transcript (P2), this forge ran from an already-approved plan's research rather than a live interview; the delta section's direct evidence substitutes. Not re-litigated.
+- Accepted with note: convention doc lives at `.claude/docs/conventions/site-pages-authoring.md`, not inside this skill's own `references/`, deliberate, to avoid a drift pair with the doc that's also linked from `document-routing.md`.
+- Post-ship correction (same session, before task close): the skill's own Rule-2 example used `<span slot="content">`, a real bug, not just a style choice. `scripts/build/lib/docs-transpiler.mjs`'s `PROSE_CONTAINERS` only recognizes `p`/`div`/`ul`/`ol`; `<span>` fell to a different decomposition path that silently reordered mixed inline content (a leading `<strong>` rendered AFTER the surrounding text, bold dropped) once the compiled `site-a2ui/pages/*.json` regenerated, invisible to schema validation (`valid:true`) and to a raw-HTML read, only caught by a live-browser check. Fixed in SKILL.md, the convention doc, and all 16 already-migrated `site/pages/*.html` files (`<span>` → `<div>`). Added "visually verify" as a non-optional Verify step for this content shape.

package/skills/ssr-compatibility/SKILL.md

@@ -2,7 +2,7 @@
 name: ssr-compatibility
 description: >-
   Answers why an AdiaUI component crashes, drops content, renders wrong, or
-  mutates a byte-identical subtree under SSR (linkedom/Astro) — the known
+  mutates a byte-identical subtree under SSR (linkedom/Astro), the known
   failure shapes, what's fixed vs open, how to prove a fix under the
   linkedom shim gate. Use for "does this work under SSR", why a component
   crashes on attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/
@@ -19,25 +19,25 @@ disable-model-invocation: false
 user-invocable: false
 ---
 
-# ssr-compatibility — does it work under SSR, and why not if it doesn't
+# ssr-compatibility, does it work under SSR, and why not if it doesn't
 
 Two real consumers (adiav2's `admin-portal-fe` and `factory-dashboard`) server-render
 AdiaUI's light-DOM components via Astro 5 + `custom-elements-ssr`, which runs on
-linkedom — a DOM shim with no layout engine and missing browser APIs the framework's
+linkedom, a DOM shim with no layout engine and missing browser APIs the framework's
 base class assumes exist. Every SSR bug that's surfaced maps onto one of six root-cause
 shapes; misclassifying a new report against the wrong shape sends the investigation
 to the wrong fix (or worse, invents a redundant one). This pack answers "which shape is
-this" and "what's the state of each shape's fix" — it never carries the fix itself.
+this" and "what's the state of each shape's fix", it never carries the fix itself.
 
 ## The shapes, in one line each
 
 1. **A browser-only API is called unconditionally → crash** (`attachInternals`, Observers, `adoptedStyleSheets`). **Fixed** (gh#285).
-2. **`connectedCallback` destructively re-stamps existing DOM → silent content loss.** ORIGINAL diagnosis, narrowed to a static audit 2026-07-17 (gh#284) — doesn't currently expose against any shipped component.
+2. **`connectedCallback` destructively re-stamps existing DOM → silent content loss.** ORIGINAL diagnosis, narrowed to a static audit 2026-07-17 (gh#284), doesn't currently expose against any shipped component.
 2b. **Custom-element upgrade doesn't replay `attributeChangedCallback` for pre-existing attributes → reflected properties stuck at class default.** The REAL mechanism behind gh#284's symptom. **Fixed 2026-07-18** (PR #309).
 3. **A connect-time layout measurement is treated as confirmed, not unknown.** **Fixed for one component** (gh#286); the general pattern is unswept.
-4. **Property-only components can't seed initial state from SSR HTML** (gh#288) — a feature gap, **CLOSED 2026-07-18** (table-ui's `data="[…]"` attribute).
-5. **A custom `render()`/`connected()` unconditionally rebuilds a subtree that already matches** — no value-diff, no adopt-existing-DOM path, so a byte-identical server-rendered subtree gets torn down at upgrade. **Implemented for table-ui in open PR #1756** (gh#1678), pending merge — not yet fixed/shipped; not swept framework-wide (no static audit for it).
-6. **The conditional-inject class** (`querySelector`-guard-before-`innerHTML`, `search-ui`/`pagination-ui`) — decision recorded: SSR-safe when the guard target is structurally specific; post-adopt attribute writes still need shape 5's idempotent-write guard, **not yet applied** to either component (gh#1678's follow-up).
+4. **Property-only components can't seed initial state from SSR HTML** (gh#288), a feature gap, **CLOSED 2026-07-18** (table-ui's `data="[…]"` attribute).
+5. **A custom `render()`/`connected()` unconditionally rebuilds a subtree that already matches**, no value-diff, no adopt-existing-DOM path, so a byte-identical server-rendered subtree gets torn down at upgrade. **Implemented for table-ui in open PR #1756** (gh#1678), pending merge, not yet fixed/shipped; not swept framework-wide (no static audit for it).
+6. **The conditional-inject class** (`querySelector`-guard-before-`innerHTML`, `search-ui`/`pagination-ui`), decision recorded: SSR-safe when the guard target is structurally specific; post-adopt attribute writes still need shape 5's idempotent-write guard, **not yet applied** to either component (gh#1678's follow-up).
 
 Full symptom → root-cause → status detail, cited to the actual shipped/open
 code: [failure-shapes.md](references/failure-shapes.md).
@@ -46,15 +46,15 @@ code: [failure-shapes.md](references/failure-shapes.md).
 
 | Ask | Answer from |
 | --- | --- |
-| "why does `<text-ui>`/`<avatar-ui>`/a container lose its content under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §2 — shape 2, NARROWED (doesn't currently reproduce against any shipped component; see the survey before assuming a new report fits this shape) |
-| "why does this crash / throw at import, construction or connect under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1 — shape 1, FIXED twice (gh#285, gh#1430/#1436) and now GATED by `scripts/dev/ssr-linkedom-smoke.mjs`; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1 — feature-detect the API, never `typeof window` |
-| "is this connect-time `getBoundingClientRect()`/measurement read safe" | [`failure-shapes.md`](references/failure-shapes.md) §3 + [`guard-patterns.md`](references/guard-patterns.md) §3 — the fixed component's exact shape, and the "unknown ≠ confirmed" principle to apply elsewhere |
-| "what's fixed vs still open for SSR support" | [`status-ledger.md`](references/status-ledger.md) — re-verify against `gh issue view` before trusting it, it drifts |
-| "how do I test / prove an SSR gap or fix" | [`test-without-linkedom.md`](references/test-without-linkedom.md) — run the linkedom shim gate first (`node scripts/dev/ssr-linkedom-smoke.mjs`, the consumer's exact global surface), then the unit-level delete/try/finally pattern and what it does NOT prove |
+| "why does `<text-ui>`/`<avatar-ui>`/a container lose its content under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §2, shape 2, NARROWED (doesn't currently reproduce against any shipped component; see the survey before assuming a new report fits this shape) |
+| "why does this crash / throw at import, construction or connect under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1, shape 1, FIXED twice (gh#285, gh#1430/#1436) and now GATED by `scripts/dev/ssr-linkedom-smoke.mjs`; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1, feature-detect the API, never `typeof window` |
+| "is this connect-time `getBoundingClientRect()`/measurement read safe" | [`failure-shapes.md`](references/failure-shapes.md) §3 + [`guard-patterns.md`](references/guard-patterns.md) §3, the fixed component's exact shape, and the "unknown ≠ confirmed" principle to apply elsewhere |
+| "what's fixed vs still open for SSR support" | [`status-ledger.md`](references/status-ledger.md), re-verify against `gh issue view` before trusting it, it drifts |
+| "how do I test / prove an SSR gap or fix" | [`test-without-linkedom.md`](references/test-without-linkedom.md), run the linkedom shim gate first (`node scripts/dev/ssr-linkedom-smoke.mjs`, the consumer's exact global surface), then the unit-level delete/try/finally pattern and what it does NOT prove |
 | "what's the consumer's current workaround, and can they drop it yet" | [`consumer-workarounds.md`](references/consumer-workarounds.md) |
-| "table/chart/select renders empty in the SSR response" | [`failure-shapes.md`](references/failure-shapes.md) §4 — shape 4, CLOSED (table-ui's `data="[…]"` attribute); check whether the reporting component is registered server-side first if it still reproduces |
-| "a byte-identical SSR subtree gets rebuilt/mutated at upgrade — role/tabindex/cells added that weren't in the SSR HTML" | [`failure-shapes.md`](references/failure-shapes.md) §5 — shape 5, implemented for table-ui in open PR #1756 (gh#1678), pending merge; the adopt-or-diff pattern to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §4 — `Node.isEqualNode()` for a positional child, a seeded keyed-reconcile map for a flat list, `setAttrIfChanged()` for a plain attribute write, and §4.1 for why a renderer-owned candidate (one that can attach a listener) must never be adopted on structural equality alone |
-| "is this querySelector-guard-before-innerHTML component (search-ui/pagination-ui shape) SSR-safe" | [`failure-shapes.md`](references/failure-shapes.md) §6 — decision recorded: yes, when the guard target is structurally specific; post-adopt attribute writes are a separate, NOT-yet-closed gap (same file, same section) |
+| "table/chart/select renders empty in the SSR response" | [`failure-shapes.md`](references/failure-shapes.md) §4, shape 4, CLOSED (table-ui's `data="[…]"` attribute); check whether the reporting component is registered server-side first if it still reproduces |
+| "a byte-identical SSR subtree gets rebuilt/mutated at upgrade, role/tabindex/cells added that weren't in the SSR HTML" | [`failure-shapes.md`](references/failure-shapes.md) §5, shape 5, implemented for table-ui in open PR #1756 (gh#1678), pending merge; the adopt-or-diff pattern to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §4, `Node.isEqualNode()` for a positional child, a seeded keyed-reconcile map for a flat list, `setAttrIfChanged()` for a plain attribute write, and §4.1 for why a renderer-owned candidate (one that can attach a listener) must never be adopted on structural equality alone |
+| "is this querySelector-guard-before-innerHTML component (search-ui/pagination-ui shape) SSR-safe" | [`failure-shapes.md`](references/failure-shapes.md) §6, decision recorded: yes, when the guard target is structurally specific; post-adopt attribute writes are a separate, NOT-yet-closed gap (same file, same section) |
 
 ## Deviation doctrine
 
@@ -62,29 +62,29 @@ Every fix pattern this pack cites ([guard-patterns.md](references/guard-patterns
 carries the reasoning for why it looks the way it does (e.g. the no-op
 `ElementInternals` shim exists because `undefined` would relocate the crash,
 not remove it). If a new case doesn't fit an existing pattern's reasoning,
-that's a signal to design a new pattern — route through `primitive-authoring`,
+that's a signal to design a new pattern, route through `primitive-authoring`,
 don't force-fit the nearest existing shape.
 
 ## Boundaries
 
-- **Implementing any fix — new or matching an existing pattern.** Route to
+- **Implementing any fix, new or matching an existing pattern.** Route to
   `primitive-authoring`. This pack orients and cites; it never edits
   `packages/web-components/core/` or any component source.
 - **Consumer-side SSR/hydration host wiring** (an app's own Astro/Next config, which
   rendering mode to pick, how to structure the hydration boundary). Route to
-  `host-wiring` (adia-ui-factory plugin) — this pack answers whether the FRAMEWORK's own
+  `host-wiring` (adia-ui-factory plugin), this pack answers whether the FRAMEWORK's own
   components are SSR-safe, not how a consumer app should be structured around them.
 - **A2UI runtime/generation-pipeline SSR concerns** (if any surface later). Route to
-  `a2ui-maintenance` — this pack is scoped to `UIElement`'s own lifecycle and the
+  `a2ui-maintenance`: this pack is scoped to `UIElement`'s own lifecycle and the
   component/trait/module layer, not the generative pipeline.
 - **Not a general web-components-SSR tutorial.** Every claim here is cited to this
-  specific framework's actual code, issues, and PRs — general SSR/custom-elements
+  specific framework's actual code, issues, and PRs, general SSR/custom-elements
   theory that isn't grounded in this repo's own history doesn't belong in this pack.
 
-## Worked example — the answer contract
+## Worked example, the answer contract
 
 A "content vanished" report can match shape 2's symptom while shape 2
-itself no longer applies (it was narrowed 2026-07-17) — the general lesson
+itself no longer applies (it was narrowed 2026-07-17), the general lesson
 (grep the component's `static template` before answering "known issue,
 shape 2") plus a full worked ask/answer are in
 [failure-shapes.md](references/failure-shapes.md) §2's own Worked example.
@@ -92,7 +92,6 @@ shape 2") plus a full worked ask/answer are in
 ## Corpus of record
 
 Routing-eval corpus: [`evals/routing-corpus.json`](evals/routing-corpus.json).
-This pack is hand-authored from verified session work (not a research-wave corpus) —
-re-sync it per [`status-ledger.md`](references/status-ledger.md)'s own instructions
+This pack is hand-authored from verified session work (not a research-wave corpus), re-sync it per [`status-ledger.md`](references/status-ledger.md)'s own instructions
 whenever an issue referenced here changes state, rather than letting the ledger and
 reality drift apart silently.

package/skills/ssr-compatibility/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Ssr Compatibility"
-  short_description: "Answers why an AdiaUI component crashes, drops content, renders wrong, or mutates a byte-identical subtree under SSR (linkedom/Astro) — the known failure shapes, what's fixed vs open, how to prove a fix under the linkedom shim gate."
+  short_description: "Answers why an AdiaUI component crashes, drops content, renders wrong, or mutates a byte-identical subtree under SSR (linkedom/Astro), the known failure shapes, what's fixed vs open, how to prove a fix under the linkedom shim gate."

package/skills/ssr-compatibility/evals/evals.json

@@ -8,7 +8,7 @@
     { "id": "t04", "prompt": "table-ui and chart-ui always render empty in our server-rendered HTML even though the data is set", "expect": "trigger" },
     { "id": "t05", "prompt": "Is it safe to call getBoundingClientRect() synchronously in connectedCallback?", "expect": "trigger" },
     { "id": "t06", "prompt": "document.adoptedStyleSheets is undefined and our component library crashes on import under SSR", "expect": "trigger" },
-    { "id": "t07", "prompt": "What's the actual root cause of the SSR content-loss bug — container CEs losing their nested children?", "expect": "trigger" },
+    { "id": "t07", "prompt": "What's the actual root cause of the SSR content-loss bug, container CEs losing their nested children?", "expect": "trigger" },
     { "id": "t08", "prompt": "Can our app finally delete the 110-line browser-API SSR shim now that 0.8.5 is out?", "expect": "trigger" },
     { "id": "n01", "prompt": "Add hydration-aware stamping so connectedCallback stops overwriting existing children", "expect": "no-trigger", "owner": "primitive-authoring" },
     { "id": "n02", "prompt": "Set up Astro's rendering mode and hydration boundaries for our admin app", "expect": "no-trigger", "owner": "host-wiring" },

package/skills/ssr-compatibility/evals/routing-corpus.json

@@ -4,7 +4,7 @@
   "version": "2.1.0",
   "purpose": "Routing-eval corpus for ssr-compatibility. 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": "ssr-compatibility routing \u2014 does this phrase activate ssr-compatibility?",
+  "scope": "ssr-compatibility routing, does this phrase activate ssr-compatibility?",
   "phrases": [
     {
       "id": "ssr-compatibility-pos-01",

package/skills/ssr-compatibility/references/consumer-workarounds.md

@@ -1,89 +1,88 @@
-# The consumer's current workarounds — what they look like, why they're fragile
+# The consumer's current workarounds, what they look like, why they're fragile
 
-Two real consumers — adiav2's `admin-portal-fe` and `factory-dashboard` — SSR AdiaUI
+Two real consumers, adiav2's `admin-portal-fe` and `factory-dashboard`, SSR AdiaUI
 via Astro 5 + `custom-elements-ssr` (linkedom). Each open issue names a workaround
 they currently maintain in their OWN app code (not in this framework). Knowing the
-shape of each matters for two reasons: (1) it tells you what "done" looks like — the
+shape of each matters for two reasons: (1) it tells you what "done" looks like, the
 workaround should become deletable once the underlying gh issue closes; (2) it's the
 concrete evidence for WHY each open issue matters, beyond the abstract description.
 
-## The ~110-line browser-API shim (gh#285 — now deletable, unconfirmed)
+## The ~110-line browser-API shim (gh#285, now deletable, unconfirmed)
 
 Before every component module import, the consumer's SSR entry point ran a
 prototype-patching shim: stubbed `attachInternals`, defined four no-op Observer
 classes (`ResizeObserver`/`IntersectionObserver`/`MutationObserver`/`PerformanceObserver`),
 and force-assigned `document.adoptedStyleSheets = []`. Two named fragilities:
-- **Fragile import order** — the shim MUST execute before any component module
+- **Fragile import order**, the shim MUST execute before any component module
   loads, or the "deep-render pass" crashes anyway. This already broke once in a
-  production bundle (per the issue) — a bundler/tree-shaking change that reordered
+  production bundle (per the issue), a bundler/tree-shaking change that reordered
   imports silently reintroduced the crash.
-- **A global patch, not scoped** — patching `HTMLElement.prototype` /
+- **A global patch, not scoped**, patching `HTMLElement.prototype` /
   `globalThis.ResizeObserver` affects EVERY component and every other library in the
   same process, not just AdiaUI's.
 
 **Status as of gh#285's fix (PR #292, merged 2026-07-17): the AdiaUI-facing sections
-of this shim are no longer necessary** — the framework guards its own call sites now.
+of this shim are no longer necessary**, the framework guards its own call sites now.
 **Consumer-confirmed 2026-08-17 (gh#1430 §Additional context, against 0.8.40):**
 `attachInternals`, the four Observer stubs and `adoptedStyleSheets` are all confirmed
 unnecessary. **But gh#285's closing comment over-reached** in saying the shim "as a
-whole" can go: two of its sections patch `CustomElementRender.prototype` — a
-`setAttribute` null-guard and a `renderShadow` null-guard — i.e. they patch
+whole" can go: two of its sections patch `CustomElementRender.prototype`, a
+`setAttribute` null-guard and a `renderShadow` null-guard, i.e. they patch
 `custom-elements-ssr` itself, which reads `shadowRoot.innerHTML` unconditionally and
 AdiaUI is light-DOM-only, so `shadowRoot` is always `null`. Remove those two and every
 SSR'd fixture dies with `Cannot read properties of null (reading 'innerHTML')`. No fix
 in this repo can retire them; they belong to the renderer. Tell the next consumer that
 explicitly rather than "the shim is unnecessary". (Also from that trial: `matchMedia`
-was a further AdiaUI-side gap the #292 sweep missed — fixed by gh#1430, so a
+was a further AdiaUI-side gap the #292 sweep missed, fixed by gh#1430, so a
 `matchMedia` stub is not needed either from the version carrying it.)
 
-## Attribute-only SSR registration restriction (gh#284 — likely no longer necessary, unconfirmed)
+## Attribute-only SSR registration restriction (gh#284, likely no longer necessary, unconfirmed)
 
 The consumer restricts server-side custom-element registration to components whose
-visible content derives ENTIRELY from attributes — `button-ui text="…"`, `icon-ui
+visible content derives ENTIRELY from attributes, `button-ui text="…"`, `icon-ui
 name="…"`. Every container (`admin-shell`, `admin-sidebar`, `nav-ui`) and every
 projected-text component (`text-ui`, `avatar-ui`, `badge-ui`, and by extension
 anything using `<component>slotted text</component>` markup) must register
 CLIENT-side only, upgrading after first paint.
 
 **Status as of gh#284's narrowing (2026-07-17): the STAMP() reason for this
-restriction is gone** — every component it names (and every other shipped
+restriction is gone**, every component it names (and every other shipped
 component with real content) currently derives its visible content from
 properties/attributes only, never from light-DOM children, so `stamp()`'s
 destructive replace never fires against real content for any of them (see
 [`failure-shapes.md`](failure-shapes.md) §2 for the empirical survey). This did
-NOT ship as a `stamp()` fix — it's a narrowing based on the CURRENT shape of the
+NOT ship as a `stamp()` fix, it's a narrowing based on the CURRENT shape of the
 component set, backed by a forward static audit
 (`scripts/dev/audit-template-child-conflict.mjs`) that would catch a future
 regression.
 
-**UPDATE 2026-07-18 — but there WAS a second, independent, real reason this
+**UPDATE 2026-07-18, but there WAS a second, independent, real reason this
 restriction was justified, now also fixed.** Every component this restriction
-names is attribute/property-driven — and until PR #309, attribute-driven
+names is attribute/property-driven, and until PR #309, attribute-driven
 content was ITSELF broken under a late/SSR upgrade (see `failure-shapes.md` §2's
 "UPDATE 2026-07-18" and `guard-patterns.md` §2b): `attributeChangedCallback`
 never replayed for pre-existing attributes on upgrade, so `<nav-item-ui
 text="Profile">` rendered with an empty label regardless of the stamp()
 question. That's now fixed at the framework level (`element.js`
 `connectedCallback`). So as of the version carrying PR #309, both reasons this
-restriction existed are addressed — not just the one gh#284 originally named.
+restriction existed are addressed, not just the one gh#284 originally named.
 
 As with gh#285's shim: don't assume the consumer has actually
-relaxed this restriction without checking the issue thread for their confirmation
-— a consumer removing their own workaround is their change, not something this
+relaxed this restriction without checking the issue thread for their confirmation, a consumer removing their own workaround is their change, not something this
 narrowing does automatically. If the consumer's linkedom/`custom-elements-ssr`
 setup surfaces something this repo's own repro didn't (a real second-connect
 timing difference, an app-level component not covered by this framework), that's
 new information worth feeding back into the issue, not something to assume away.
 
-## gh#288 (property-only components) — CLOSED 2026-07-18, workaround droppable
+## gh#288 (property-only components), CLOSED 2026-07-18, workaround droppable
 
 The consumer's PRE-fix behavior for `table-ui`/`chart-ui`/`select-ui` with
 programmatic content was: render empty in the SSR response, then a per-page
 wiring script does `customElements.whenDefined(...) → getElementById → assign
 properties` after hydration. As of the fix, that boilerplate is droppable for all
-three — `select-ui` via native `<option>` children (already worked, pre-existing),
+three, `select-ui` via native `<option>` children (already worked, pre-existing),
 `chart-ui` via a `data="[…]"` JSON attribute (already worked, pre-existing),
 `table-ui` via the same `data="[…]"` attribute (new) plus `<col-def>` children for
 columns (pre-existing). Don't assume the consumer has removed the wiring script
-without their confirmation — see [`failure-shapes.md`](failure-shapes.md) §4 for
+without their confirmation, see [`failure-shapes.md`](failure-shapes.md) §4 for
 the full narrative.