@adia-ai/adia-ui-forge 0.8.5 → 0.8.6

package/skills/adia-a2ui/SKILL.md

@@ -1,11 +1,16 @@
 ---
 name: adia-a2ui
 description: >-
-  Maintains the A2UI pipeline (packages/a2ui/): chunk corpus, compose
-  strategies, calibration, evals, the a2ui MCP. Use when asked to author/fix
-  chunks, tune STRONG_MATCH, lift eval fails, change MCP tools, run pipeline
-  ops, or when a component's A2UI contract can't express a content shape.
-  NOT for app screens (adia-compose).
+  Maintains the A2UI pipeline (packages/a2ui/): the harvested chunk corpus,
+  compose strategies (zettel, chunk-zettel, free-form, monolithic), retrieval,
+  validator, calibration, evals, the a2ui MCP server. Use when asked to
+  author/harvest/fix chunks, tune STRONG_MATCH or zettel thresholds, validate
+  an A2UI document, diagnose an eval gap/regression or lift a semantic fail,
+  add or change MCP tools (generate_ui, compose_from_chunks,
+  check_anti_patterns, refine_composition), scan anti-patterns, run pipeline
+  ops, or when a component's A2UI contract can't express a content shape. NOT
+  for app screens (adia-compose), runtime gen-UI app features (adia-genui),
+  primitive authoring (adia-author), or gallery scoring (adia-gen-review).
 disable-model-invocation: false
 user-invocable: true
 ---
@@ -73,7 +78,7 @@ Unmatched work defaults to pipeline-overview and re-classifies from there.
 Full structural gate after any pipeline change:
 
 ```bash
-node scripts/build/components.mjs --verify   # "clean — N files up-to-date" (127 component dirs)
+node scripts/build/components.mjs --verify   # "clean — N files up-to-date" (the N is the gate; dir count drifts, don't pin it)
 npm run verify:traits                        # 100% coverage
 npm run smoke:engines
 npm run smoke:register-engine                # 11/11
@@ -109,3 +114,19 @@ intent → retrieval (chunk / composition search)
 Every change touches exactly one stage; identify which before patching. History
 for any constant or decision lives in git and PR descriptions
 (`git log -S STRONG_MATCH_THRESHOLD -- packages/a2ui`).
+
+## Pipeline Change Record — the output contract
+
+Every change reports:
+
+| Field | Value |
+| --- | --- |
+| Stage touched | retrieval \| strategy engine (zettel/chunk-zettel/free-form/monolithic) \| composer \| validator \| MCP surface |
+| Narrowest gate run | the specific check for the touched stage, + result |
+| Full sequence | `npm run smoke:engines` + `npm run test:a2ui` result |
+| Floors before → after | cov/avg/MRR (zettel) or cov/avg/F1 (free-form) or cov/avg (monolithic) |
+| Re-baseline | no / yes — if yes, the PR that ratified the new floor |
+
+Done when every row is filled and the cited gates are green. NOT done: a
+floor number changed with no before/after comparison, or a threshold tweak
+with no root-cause note for why the floor moved.

package/skills/adia-a2ui/evals/routing-corpus.json

@@ -1,31 +1,38 @@
 {
-  "skill": "adia-a2ui",
-  "description": "Routing corpus — does a phrase route to adia-a2ui (the A2UI/gen-ui pipeline maintainer skill) or to a sibling/off-topic?",
-  "minimums_per_spec": {
-    "trigger_phrases": 10,
-    "adversarial_phrases": 5
-  },
-  "phrases": [
-    { "id": "t1", "phrase": "validate this A2UI document", "should_route_to_a2ui": true },
-    { "id": "t2", "phrase": "harvest a chunk from this HTML demo", "should_route_to_a2ui": true },
-    { "id": "t3", "phrase": "zettel coverage dropped after the last change", "should_route_to_a2ui": true },
-    { "id": "t4", "phrase": "should this repeated subtree become its own chunk", "should_route_to_a2ui": true },
-    { "id": "t5", "phrase": "tune the STRONG_MATCH threshold", "should_route_to_a2ui": true },
-    { "id": "t6", "phrase": "run check_anti_patterns on this rendered HTML", "should_route_to_a2ui": true },
-    { "id": "t7", "phrase": "refine composition with an OAuth row", "should_route_to_a2ui": true },
-    { "id": "t8", "phrase": "MRR dropped in the chunk retrieval eval", "should_route_to_a2ui": true },
-    { "id": "t9", "phrase": "add an MCP tool to the a2ui server", "should_route_to_a2ui": true },
-    { "id": "t10", "phrase": "audit the training data corpus for drift", "should_route_to_a2ui": true },
-    { "id": "t11", "phrase": "diagnose this eval gap and regression", "should_route_to_a2ui": true },
-    { "id": "t12", "phrase": "run the MCP pipeline: generate_ui then validate_schema", "should_route_to_a2ui": true },
-    { "id": "t13", "phrase": "lift a semantic fail under sixty", "should_route_to_a2ui": true },
-    { "id": "t14", "phrase": "why did the composer emit composition-match instead of composition-synthesized", "should_route_to_a2ui": true },
-    { "id": "a1", "phrase": "build a settings page from existing primitives", "should_route_to_a2ui": false, "expected_alternative": "adia-author" },
-    { "id": "a2", "phrase": "add a slot to button-ui and update its yaml contract", "should_route_to_a2ui": false, "expected_alternative": "adia-author" },
-    { "id": "a3", "phrase": "cut a release and bump the version tag", "should_route_to_a2ui": false, "expected_alternative": "adia-release" },
-    { "id": "a4", "phrase": "score the generated UI quality in apps/genui", "should_route_to_a2ui": false, "expected_alternative": "adia-gen-review" },
-    { "id": "a5", "phrase": "run a broad visual QA sweep across site and playgrounds", "should_route_to_a2ui": false, "expected_alternative": "adia-dogfood" },
-    { "id": "a6", "phrase": "fix the @adia-ai/llm SSE adapter", "should_route_to_a2ui": false, "expected_alternative": "adia-llm" },
-    { "id": "a7", "phrase": "explain how React state management works", "should_route_to_a2ui": false, "expected_alternative": "off-topic" }
-  ]
+  "positives": [
+    "validate this A2UI document",
+    "harvest a chunk from this HTML demo",
+    "zettel coverage dropped after the last change",
+    "should this repeated subtree become its own chunk",
+    "tune the STRONG_MATCH threshold",
+    "run check_anti_patterns on this rendered HTML",
+    "refine composition with an OAuth row",
+    "MRR dropped in the chunk retrieval eval",
+    "add an MCP tool to the a2ui server",
+    "audit the training data corpus for drift",
+    "diagnose this eval gap and regression",
+    "run the MCP pipeline: generate_ui then validate_schema",
+    "lift a semantic fail under sixty",
+    "why did the composer emit composition-match instead of composition-synthesized"
+  ],
+  "negatives": [
+    "build a settings page from existing primitives",
+    "add a slot to button-ui and update its yaml contract",
+    "cut a release and bump the version tag",
+    "score the generated UI quality in apps/genui",
+    "run a broad visual QA sweep across site and playgrounds",
+    "fix the @adia-ai/llm SSE adapter",
+    "explain how React state management works",
+    "compose a settings screen from catalog primitives",
+    "mount gen-root and wire data resolvers for end users at runtime",
+    "edit the getting-started docs page on the site"
+  ],
+  "_measured": {
+    "as_of": "2026-07-18",
+    "scorer": "routing_eval.py (nonoun-plugins/forge)",
+    "f1": 0.783,
+    "precision": 1.0,
+    "recall": 0.643,
+    "exit_code": 0
+  }
 }

package/skills/adia-a2ui/references/zettel-calibration.md

@@ -8,7 +8,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `STRONG_MATCH_THRESHOLD = 40`
 
-- **File**: `packages/a2ui/compose/strategies/zettel/generator-adapter.js:89`
+- **File**: `packages/a2ui/compose/strategies/zettel/generator-adapter.js` (`grep -n STRONG_MATCH_THRESHOLD`)
 - **Raised**: 22 → 40 post-incident.
 - **Reason**: at 22, login-form / signup-form played verbatim too often →
   repetitive output. At 40, only near-perfect retrievals (chart-dashboard=48,
@@ -29,7 +29,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `STRONG_RETRIEVAL_SCORE = 8`
 
-- **File**: `chunk-synthesizer.js:31`
+- **File**: `chunk-synthesizer.js` (`grep -n STRONG_RETRIEVAL_SCORE`)
 - **Scale**: corpus-size-**independent** absolute keyword score from
   `chunk-library.js#keywordScore()`: first name-word matches a token **+10**,
   full-query substring **+5**, whole-word token in name **+3**, substring /
@@ -46,7 +46,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `PRE_SEARCH_LIMIT = 30`
 
-- **Files**: `chunk-synthesizer.js:32`, `chunk-refiner.js:32`
+- **Files**: `chunk-synthesizer.js` + `chunk-refiner.js` (`grep -n PRE_SEARCH_LIMIT`)
 - **Reason**: token-budget mitigation — pre-filter the catalog before the LLM
   sees it; the full catalog per prompt would burn tens of thousands of tokens.
 - **Synthesizer**: kind-aware allocation —
@@ -61,7 +61,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `SCOPE_DRIFT_RATIO = 1.5` + `SCOPE_DRIFT_MIN_ACTUAL = 20`
 
-- **File**: `chunk-synthesizer.js:38-39` (exported)
+- **File**: `chunk-synthesizer.js` (exported; `grep -n SCOPE_DRIFT`)
 - Composed envelope's component count > 1.5× the sum of bound chunks' counts
   auto-fires a `scope-drift` issue — catches LLM creative expansion that
   hallucinates components beyond the bound chunks.
@@ -70,7 +70,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `DEFAULT_MAX_ATTEMPTS = 2`
 
-- **Files**: `chunk-refiner.js:31`, `chunk-synthesizer.js:33`
+- **Files**: `chunk-refiner.js` + `chunk-synthesizer.js` (`grep -n DEFAULT_MAX_ATTEMPTS`)
 - Validator-driven retry budget. After 2 failed validations the engine emits
   `synthesis-failed`.
 

package/skills/adia-author/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: adia-author
 description: >-
-  Author or modify code inside the adia-ui monorepo — primitives, shells,
-  demos, component yaml SoTs, the @adia-ai/llm bridge. Use when asked to add
-  or edit a primitive, prop, slot, shell, or component CSS, promote inline
-  UI to a module, or author a demo. NOT for composing app screens from
-  primitives (adia-compose) or pipeline internals (adia-a2ui).
+  Author or modify AdiaUI framework source inside the monorepo — primitives
+  (packages/web-components), shells/composites (packages/web-modules), yaml
+  SoTs, demos. Use when asked to add a new primitive component, add or fix a prop/slot/
+  attribute/CSS variant, update a component's yaml, build or fix a shell
+  (chat-shell, admin-shell, editor-shell — sidebar/pane/bespoke-tier
+  composition), promote or extract repeated inline content into a shared
+  module, audit a component's four-axis contract/token usage/lifecycle
+  (connected/disconnected symmetry) for drift, or author/write a demo or
+  examples.html for a component or composite. NOT for composing app screens
+  from primitives (adia-compose), A2UI pipeline internals (adia-a2ui),
+  @adia-ai/llm adapter/streaming/bridge internals (adia-llm-internals), or
+  site/pages docs pages (adia-site-docs).
 disable-model-invocation: false
 user-invocable: true
 ---
@@ -14,7 +21,9 @@ user-invocable: true
 
 Guard rails for code that lands INSIDE the adia-ui monorepo: primitives
 (`packages/web-components/`), shells and composites (`packages/web-modules/`),
-their `<name>.yaml` SoTs, the `@adia-ai/llm` bridge, and composite demos.
+their `<name>.yaml` SoTs, and composite demos. `@adia-ai/llm` internals
+(adapters, streaming, the bridge) are `adia-llm-internals`'s charter, not
+this skill's — route there.
 Light-DOM is load-bearing: `slot=` attributes are decorative metadata,
 positioning is CSS by tag + ancestor + DOM order — never `::slotted()`,
 `::part()`, or shadow DOM. `.claude/docs/specs/component-token-contract.md`
@@ -30,7 +39,6 @@ wins any tie with this skill. Monorepo source read while authoring (yaml, CSS,
 | Shell / bespoke cluster child (`<admin-*>` `<chat-*>` `<editor-*>` `<simple-*>`) | [shell-patterns.md](references/shell-patterns.md) |
 | Promote repeated inline UI → shared module | [module-promotion.md](references/module-promotion.md) |
 | Contract / token / lifecycle drift audit on an existing component | [token-contract.md](references/token-contract.md) + [anti-patterns.md](references/anti-patterns.md) |
-| Extend `@adia-ai/llm` (provider, streaming, proxy) | [llm-bridge.md](references/llm-bridge.md) |
 | Demo for a composite/module — any `packages/web-modules/**/*.{examples,contents}.html` | [composite-demo-protocol.md](references/composite-demo-protocol.md) — NOT the primitive or promotion paths; they lack the canonical-survey discipline |
 | Convention question ("is this idiomatic?") | [code-style.md](references/code-style.md) — cite the rule, don't expand it inline |
 
@@ -82,7 +90,6 @@ citation mechanically on every web-modules demo write; the
 | Shell | render `packages/web-modules/<cluster>/<name>/<name>.html`; `node scripts/dev/audit-native-primitive-leak.mjs --include=<surface>`; `node scripts/dev/audit-shell-composition.mjs --include=<surface>` for `<admin-shell>` composites |
 | Inline → module promotion | source page renders identically post-refactor (visual sweep + DOM diff) + native-primitive-leak audit on the touched surface |
 | Drift audit | the findings report itself; gates run once a fix is applied |
-| LLM-bridge extension | a real client round-trip parses + returns (`npm run check:lockstep` + `npm run smoke:engines`) |
 | Composite demo | `npm run audit:demo-pattern-source:strict` + `npm run qa:design-coherence:strict` + (8b) `npm run qa:rendered-dom:emit -- --slug=<slug>` |
 
 Full structural-gate sequence after any primitive / shell / promotion work:

package/skills/adia-author/evals/routing-corpus.json

@@ -1,222 +1,43 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "adia-author routing accuracy corpus",
-  "version": "2.0.0",
-  "purpose": "Routing-eval corpus for adia-author (adia-forge plugin). Each phrase declares whether adia-author SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
-  "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.",
-  "license": "internal",
-  "scope": "adia-author routing — does this phrase activate adia-author?",
-
-  "minimums_per_spec": {
-    "trigger_phrases": 21,
-    "adversarial_phrases": 6,
-    "task_shapes_covered": "new-primitive, modify-primitive, shell, module-promotion, drift-audit, llm-bridge, composite-demo",
-    "adversarial_fraction": "20%"
-  },
-
-  "phrases": [
-    {
-      "id": "author-new-primitive-01",
-      "phrase": "add a new button-ui primitive component",
-      "should_route_to_author": true,
-      "expected_shape": "new-primitive",
-      "rationale": "Canonical new-primitive task shape."
-    },
-    {
-      "id": "author-new-primitive-02",
-      "phrase": "build a new <toggle-ui> component from scratch",
-      "should_route_to_author": true,
-      "expected_shape": "new-primitive",
-      "rationale": "'build a <foo-ui>' phrasing."
-    },
-    {
-      "id": "author-new-primitive-03",
-      "phrase": "create a new primitive web component in packages/web-components",
-      "should_route_to_author": true,
-      "expected_shape": "new-primitive",
-      "rationale": "Explicit packages/web-components path mention."
-    },
-
-    {
-      "id": "author-modify-01",
-      "phrase": "add a new prop to table-ui",
-      "should_route_to_author": true,
-      "expected_shape": "modify-primitive",
-      "rationale": "Modify existing primitive — add a prop."
-    },
-    {
-      "id": "author-modify-02",
-      "phrase": "fix the CSS in card-ui to handle the new bleed variant",
-      "should_route_to_author": true,
-      "expected_shape": "modify-primitive",
-      "rationale": "Modify existing primitive CSS."
-    },
-    {
-      "id": "author-modify-03",
-      "phrase": "update the input-ui yaml to add a placeholder attribute",
-      "should_route_to_author": true,
-      "expected_shape": "modify-primitive",
-      "rationale": "Update the yaml SoT for an existing primitive."
-    },
-
-    {
-      "id": "author-shell-01",
-      "phrase": "build the chat-shell composition with the new sidebar slot",
-      "should_route_to_author": true,
-      "expected_shape": "shell",
-      "rationale": "Shell authoring."
-    },
-    {
-      "id": "author-shell-02",
-      "phrase": "author a new web-module shell at packages/web-modules/editor/editor-shell",
-      "should_route_to_author": true,
-      "expected_shape": "shell",
-      "rationale": "Explicit web-modules + shell."
-    },
-    {
-      "id": "author-shell-03",
-      "phrase": "add a pane behaviour to admin-shell per the bespoke shell-tier convention",
-      "should_route_to_author": true,
-      "expected_shape": "shell",
-      "rationale": "Bespoke shell-tier (ADR-0023 shape) work."
-    },
-
-    {
-      "id": "author-promote-01",
-      "phrase": "promote this inline content to a shared web-modules module",
-      "should_route_to_author": true,
-      "expected_shape": "module-promotion",
-      "rationale": "Promote inline → module."
-    },
-    {
-      "id": "author-promote-02",
-      "phrase": "this content keeps repeating across apps, extract to a shared module",
-      "should_route_to_author": true,
-      "expected_shape": "module-promotion",
-      "rationale": "Repetition trigger."
-    },
-    {
-      "id": "author-promote-03",
-      "phrase": "lift this billing-summary block from apps/saas to web-modules",
-      "should_route_to_author": true,
-      "expected_shape": "module-promotion",
-      "rationale": "Lift inline page content to a reusable module."
-    },
-
-    {
-      "id": "author-audit-01",
-      "phrase": "audit the four-axis contract for table-ui",
-      "should_route_to_author": true,
-      "expected_shape": "drift-audit",
-      "rationale": "Contract drift audit."
-    },
-    {
-      "id": "author-audit-02",
-      "phrase": "check the token usage in card-ui for drift",
-      "should_route_to_author": true,
-      "expected_shape": "drift-audit",
-      "rationale": "Token audit procedure."
-    },
-    {
-      "id": "author-audit-03",
-      "phrase": "lifecycle audit on dropdown-ui — symmetric connected/disconnected?",
-      "should_route_to_author": true,
-      "expected_shape": "drift-audit",
-      "rationale": "Lifecycle audit."
-    },
-
-    {
-      "id": "author-llm-01",
-      "phrase": "extend the LLM bridge to add a new provider",
-      "should_route_to_author": true,
-      "expected_shape": "llm-bridge",
-      "rationale": "Extend @adia-ai/llm."
-    },
-    {
-      "id": "author-llm-02",
-      "phrase": "modify createAdapter in @adia-ai/llm to add chunk-shape support",
-      "should_route_to_author": true,
-      "expected_shape": "llm-bridge",
-      "rationale": "Explicit createAdapter + @adia-ai/llm mention."
-    },
-    {
-      "id": "author-llm-03",
-      "phrase": "set up the LLM-bridge surface for a new tool-call provider",
-      "should_route_to_author": true,
-      "expected_shape": "llm-bridge",
-      "rationale": "LLM-bridge trigger phrase."
-    },
-
-    {
-      "id": "author-demo-01",
-      "phrase": "author a demo for the billing-overview composite",
-      "should_route_to_author": true,
-      "expected_shape": "composite-demo",
-      "rationale": "Composite-demo authoring."
-    },
-    {
-      "id": "author-demo-02",
-      "phrase": "compose the examples.html for dashboard-layout",
-      "should_route_to_author": true,
-      "expected_shape": "composite-demo",
-      "rationale": "'compose examples.html for Y' trigger."
-    },
-    {
-      "id": "author-demo-03",
-      "phrase": "write the demo for <integrations-page-ui> in packages/web-modules/settings",
-      "should_route_to_author": true,
-      "expected_shape": "composite-demo",
-      "rationale": "'write the demo for <module-ui>' + web-modules path."
-    },
-
-    {
-      "id": "author-adv-01",
-      "phrase": "compose this Figma mock into AdiaUI components for our consumer app",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-compose (adia-factory plugin)",
-      "rationale": "Adversarial — consumer-side composition (screens FROM existing primitives). The description NEG-fences it."
-    },
-    {
-      "id": "author-adv-02",
-      "phrase": "cut a release of the next version and publish the npm packages",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-release",
-      "rationale": "Adversarial — release territory."
-    },
-    {
-      "id": "author-adv-03",
-      "phrase": "tune the zettel composition coverage; eval is at 38%",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-a2ui",
-      "rationale": "Adversarial — a2ui pipeline internals (compose strategies, eval coverage)."
-    },
-    {
-      "id": "author-adv-04",
-      "phrase": "build a user profile card with avatar and edit actions",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-compose (adia-factory plugin)",
-      "rationale": "Adversarial — canonical consumer-composition task (build UI from intent)."
-    },
-    {
-      "id": "author-adv-05",
-      "phrase": "deploy the api service to the hosting platform",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-deploy",
-      "rationale": "Adversarial — deployment/ops territory."
-    },
-    {
-      "id": "author-adv-06",
-      "phrase": "explain how React hooks work",
-      "should_route_to_author": false,
-      "expected_alternative": null,
-      "rationale": "Adversarial — generic framework knowledge; no AdiaUI skill should activate."
-    }
+  "positives": [
+    "add a new button-ui primitive component",
+    "build a new <toggle-ui> component from scratch",
+    "create a new primitive web component in packages/web-components",
+    "add a new prop to table-ui",
+    "fix the CSS in card-ui to handle the new bleed variant",
+    "update the input-ui yaml to add a placeholder attribute",
+    "build the chat-shell composition with the new sidebar slot",
+    "author a new web-module shell at packages/web-modules/editor/editor-shell",
+    "add a pane behaviour to admin-shell per the bespoke shell-tier convention",
+    "promote this inline content to a shared web-modules module",
+    "this content keeps repeating across apps, extract to a shared module",
+    "lift this billing-summary block from apps/saas to web-modules",
+    "audit the four-axis contract for table-ui",
+    "check the token usage in card-ui for drift",
+    "lifecycle audit on dropdown-ui \u2014 symmetric connected/disconnected?",
+    "author a demo for the billing-overview composite",
+    "compose the examples.html for dashboard-layout",
+    "write the demo for <integrations-page-ui> in packages/web-modules/settings"
   ],
-
-  "evaluator_notes": {
-    "current_state": "27 cases (21 trigger + 6 adversarial). Each of the 7 task shapes has 3 trigger cases. The old corpus's 3 Teach-mode cases were dropped (skill-teaching is estate-level maintenance now, not a product-skill mode).",
-    "promotion_criteria": "Promote to a CI gate (warn → hard-fail) when F1 ≥ 0.85 on this corpus across 3+ consecutive runs without description edits.",
-    "review_cadence": "Re-run on every adia-author description edit. Add 1-2 new cases per checkpoint reflecting newly-observed routing failure modes.",
-    "known_limitations": "module-promotion and composite-demo phrases overlap semantically ('lift to web-modules' vs 'author demo for module') — the heuristic scorer may not disambiguate; the harness with file-path context will (the demo path pattern also fires the demo-postwrite-pattern-gate hook regardless of routing)."
+  "negatives": [
+    "compose this Figma mock into AdiaUI components for our consumer app",
+    "cut a release of the next version and publish the npm packages",
+    "tune the zettel composition coverage; eval is at 38%",
+    "build a user profile card with avatar and edit actions",
+    "deploy the api service to the hosting platform",
+    "explain how React hooks work",
+    "the gemini adapter is dropping usage tokens on streamed responses",
+    "fix the openai stopReason mapping in the llm client",
+    "extend the LLM bridge to add a new provider",
+    "modify createAdapter in @adia-ai/llm to add chunk-shape support",
+    "set up the LLM-bridge surface for a new tool-call provider"
+  ],
+  "_measured": {
+    "as_of": "2026-07-18",
+    "scorer": "routing_eval.py (nonoun-plugins/forge)",
+    "f1": 0.971,
+    "precision": 1.0,
+    "recall": 0.944,
+    "exit_code": 0
   }
 }

package/skills/adia-author/references/authoring-cycle.md

@@ -184,6 +184,24 @@ Before declaring the work done, run through this checklist. If anything fails, f
 - [ ] Cached DOM refs (`this.#fooEl`) are nulled in `disconnected()`.
 - [ ] Class declares `disconnected()` exactly once.
 
+## Step 4b — Author the yaml SoT (+ regenerate the sidecar)
+
+A component isn't just its `.js`/`.css` — the `<name>.yaml` is the SOURCE OF
+TRUTH the whole pipeline reads (docs site, A2UI registries, consumer
+harnesses, `.d.ts` codegen). Every new primitive ships one; every prop/slot/
+event change updates it. Field-by-field contract:
+[yaml-contract.md](yaml-contract.md). Then regenerate — never hand-edit the
+sidecar (`sidecar-prewrite-guard` blocks it anyway):
+
+```bash
+npm run build:components            # yaml → <name>.a2ui.json + catalog + .d.ts
+node scripts/build/components.mjs --verify   # "clean — N files up-to-date"
+```
+
+A primitive also needs BOTH barrel registrations — the CSS `@import` in
+`styles/components.css` AND the JS `export` in `components/index.js`
+(`scripts/audit/check-components-js-barrel.mjs` gates the second).
+
 ## Step 5 — Run the project's verification gates
 
 Before committing, run the project's verify scripts. These catch the drift-shaped bugs the checklist can miss:
@@ -206,4 +224,5 @@ If a gate fails, fix before declaring done.
 - [lifecycle-patterns.md](lifecycle-patterns.md) — timers, observers, popovers, listener patterns
 - [anti-patterns.md](anti-patterns.md) — full failure-mode catalogue, file:line refs
 - [worked-example.md](worked-example.md) — badge-ui + counter-ui walkthroughs
+- [yaml-contract.md](yaml-contract.md) — the `<name>.yaml` SoT schema (Step 4b)
 - [token-contract.md](token-contract.md) — token audit (post-implementation check)

package/skills/adia-author/references/code-style.md

@@ -319,7 +319,6 @@ For component source under `packages/web-components/components/**`, the gate is
 - [css-patterns.md](css-patterns.md) — full @scope + variant/mode CSS architecture
 - [lifecycle-patterns.md](lifecycle-patterns.md) — timers, observers, popovers, listeners
 - [token-contract.md](token-contract.md) — token audit procedure
-- [llm-bridge.md](llm-bridge.md) — extend @adia-ai/llm
 - [module-promotion.md](module-promotion.md) — promote inline → module
 - [anti-patterns.md](anti-patterns.md) — failure-mode catalogue with file:line refs
 - **adia-a2ui** (sibling skill) — generator / corpus / MCP pipeline

package/skills/adia-author/references/llm-bridge.md

@@ -1,5 +1,12 @@
 # LLM Bridge extension — @adia-ai/llm
 
+**Superseded 2026-07-18 — `@adia-ai/llm` internals are `adia-llm-internals`'s charter, not
+`adia-author`'s.** That skill's references (`adapter-contract.md`, `streaming-sse.md`,
+`model-registry.md`, `bridge-facade.md`, `browser-proxy-boundary.md`, `add-a-provider.md`)
+are the current, maintained source — this file is kept only as a historical pointer and is
+no longer linked from `adia-author`'s task-shape table or `code-style.md`. Route provider/
+streaming/bridge work to `adia-llm-internals`.
+
 Use when adding a 4th provider, modifying `createAdapter()`, changing the streaming chunk shape, or extending `packages/llm/server.js`.
 
 This reference is about **modifying** the package. For day-to-day consumption (import + call), the README at `packages/llm/README.md` is sufficient.

package/skills/adia-author/references/worked-example.md

@@ -8,12 +8,28 @@ A small inline container for status labels. Supports cosmetic variants (accent/s
 
 ### File layout
 
+The REAL anatomy every shipped primitive carries (this example's code blocks
+below show only the two hand-authored core files, but "copy the structure"
+means all of these — the yaml SoT and its regenerated artifacts are not
+optional):
+
 ```text
 packages/web-components/components/badge/
-  badge.js
-  badge.css
+  badge.yaml           # SoT — props/slots/events contract (yaml-contract.md); edit FIRST
+  badge.class.js       # the class, non-registering export (test isolation / subclassing)
+  badge.js             # side-effect registration wrapper: import class + defineIfFree()
+  badge.css            # @scope'd styles
+  badge.html           # standalone demo page
+  badge.examples.html  # docs-site examples
+  badge.examples.md    # examples prose
+  badge.a2ui.json      # GENERATED from the yaml (npm run build:components) — never hand-edit
+  badge.d.ts           # GENERATED types
 ```
 
+The code below collapses the class + registration into one `badge.js` for
+reading compactness only — a real component splits them
+(`badge.class.js` exports, `badge.js` registers).
+
 ### `badge.js`
 
 ```javascript