@adia-ai/a2ui-corpus 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog — @adia-ai/a2ui-corpus
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Scope: training corpus for the A2UI pipeline. Patterns, fragments,
+compositions, exemplars, held-out eval fixtures, feedback registry,
+gap registry. Consumed by `@adia-ai/a2ui-retrieval` and
+`@adia-ai/a2ui-mcp`.
+
+## [Unreleased]
+
+_Nothing yet._
+
+---
+
+## [0.0.1] - 2026-04-24
+
+First public release. Pure-data package: pattern corpus,
+fragment + composition library, exemplars, and held-out eval
+fixtures for the A2UI generation pipeline.
+
+### Included
+
+- **Assembled catalog** (`catalog-a2ui_0_9.json`) — generated by
+  `scripts/build-components.mjs` from the per-component YAML
+  sources in `@adia-ai/web-components`. Contains component schemas,
+  registry, domain classifications, fragments, compositions.
+- **Rules manifest** (`catalog-a2ui_0_9_rules.txt`) — human-readable
+  rules file paired with the catalog.
+- **Patterns** (`patterns/`) — ~217 patterns across 11 domains
+  (layout, forms, data, agent, navigation, display, container,
+  settings, etc.). Indexed via `patterns/_index.json`.
+- **Fragments** (`fragments/`) — reusable A2UI atoms used by
+  zettel-engine composition.
+- **Compositions** (`compositions/`) — templates that reference
+  fragments via `$fragment` refs.
+- **Exemplars** (`exemplars/`) — few-shot training examples per
+  domain. Consumed by the monolithic engine's prompt assembly.
+- **Held-out eval fixtures** (`evals/held-out.jsonl`) — 100 intents
+  reserved from training for regression evaluation.
+
+### Corpus state at cut
+
+See the "Corpus state" section below for pattern counts by domain,
+fragment library size, and composition coverage.
+
+---
+
+## Corpus state (current)
+
+| Surface | Count |
+|---|---:|
+| Patterns (total) | 215 |
+| Pages (exemplars) | 9 |
+| Chunks | 61 |
+| Components registered | 89 |
+| Fragments | varies; see `fragments/` |
+
+Domain breakdown:
+- layout: 114
+- forms: 38
+- data: 23
+- agent: 20
+- navigation: 11
+- display, container: 3 each
+- settings, data-display, input: 1 each
+
+## [Unreleased]
+
+### Added
+- Pipeline re-run produced 70 newly ingested patterns (net library total: 215).
+
+### Changed
+- `patterns/layout/cookie-consent.{json,yaml}` renamed to `patterns/layout/consent-banner.{json,yaml}` (and the pattern's `name` field flipped `cookie-consent` → `consent-banner`). The old filename triggered common adblock / content-blocker filter lists (EasyList, uBlock), which blocked the Vite raw-import request with `ERR_BLOCKED_BY_CONTENT_BLOCKER` when the pattern library loaded in the browser. Filename was the URL segment the blocker matched — renaming the URL path is the fix. Keywords still include `cookie` / `gdpr` / `privacy` so retrieval continues to land on this pattern for those queries. Cascaded through `patterns/_index.json` (11 refs in the `related`/etc. graph + the main entry) and `pattern-embeddings.json` (single `"name"` key). Length-preserving rename (both strings are 14 chars) so byte offsets in the embeddings file are unchanged.
+- `patterns/_components.json` — `Footer.tag`, `Header.tag`, `Section.tag` updated from `*-n` → `*-ui` post-rename. `Nav.tag` deliberately kept as `nav-n` (sanctioned exception).
+- `patterns/_schema.json` — role enum `nav-item-n` → `nav-item`.
+- `fragments/content/icon-text-row.json` — purpose tag `nav-item-n` → `nav-item`.
+- `scripts/extract.js` — removed redundant `nav-group-n` / `nav-item-n` map entries (no parent `NavGroup`/`NavItem` in canonical A2UI registry). `nav-n` kept.
+- All `.a2ui.json` sidecars regenerated via `scripts/build-components.mjs` to reflect yaml cleanup across the component library — `catalog-a2ui_0_9.json` + `catalog-a2ui_0_9_rules.txt` rebuilt.
+
+### Verification
+- `node scripts/build-components.mjs --verify` — clean, 91 files up-to-date.
+
+---
+
+## [0.1.0] — internal baseline (unreleased)
+
+Initial version at the time the monorepo was established. Contains:
+
+- **Patterns** (`patterns/`) — monolithic pattern library with schema.
+- **Fragments** (`fragments/`) — atomic fragments for the zettel engine (content, layout, wiring, etc.).
+- **Compositions** (`compositions/`) — hand-authored compositions that reference fragments.
+- **Exemplars** (`exemplars/`) — hand-authored HTML pages harvested into chunks during extraction.
+- **Held-out eval set** (`evals/held-out.jsonl`) — ~100 intents with golden matches for regression testing.
+- **Feedback / gaps registry** (`feedback/`, `gaps/`) — runtime-written operational learning.
+- **Taxonomy / synonym registry** — concept mapping for keyword-based retrieval.
+
+Package name still uses the legacy `@adia-ai/a2ui-corpus` scope pending rename (see root CHANGELOG for context).

package/README.md

@@ -0,0 +1,168 @@
+# @adia-ai/a2ui-corpus
+
+Corpus and operational-learning artifacts for the gen-UI pipeline —
+patterns, fragments, compositions, exemplars, feedback, gaps, eval
+fixtures. Pure data plus the scripts that maintain it. No runtime.
+
+> The pipeline reads this package; this package never reads the pipeline.
+> See [`@adia-ai/a2ui-compose`](../compose) for engine code,
+> [`@adia-ai/web-components`](../web-components) for UI atoms,
+> [`@adia-ai/a2ui-utils`](../a2ui/utils) for the A2UI runtime (renderer,
+> registry, streams, wiring),
+> [`@adia-ai/a2ui-mcp`](../mcp) for the MCP server.
+
+## Dependency direction
+
+```
+a2ui-compose   ──reads──▶  a2ui-corpus
+a2ui-mcp       ──reads──▶  a2ui-compose, a2ui-corpus
+web-components ◀─reads──   a2ui-corpus (exemplars use AdiaUI tags)
+```
+
+No back-writes. No circular reads. Web-components ships UI atoms only;
+corpus lives here; runtime lives in a2ui-compose.
+
+## Layout
+
+```
+a2ui/corpus/
+├── patterns/                ~97 full-canvas A2UI templates (retrieval corpus)
+│   ├── <domain>/<name>.json   agent · data · forms · layout · navigation · settings
+│   ├── _components.json       canonical name + aliases map (Carousel → Swiper)
+│   └── _taxonomy.json         concept synonyms (auth → [login, signup, otp])
+│
+├── fragments/               atomic shapes — building blocks for Zettel
+│   ├── action/                  button rows, toolbars, inline CTAs
+│   ├── content/                 stat cards, list items, media blocks
+│   ├── form/                    field, field-row, field-group recipes
+│   └── layout/                  section, grid, card scaffolding
+│
+├── compositions/            named multi-fragment recipes
+│   ├── agent/ data/ form/ layout/ navigation/ settings/
+│                              each = pre-assembled fragment set with keywords + tags
+│
+├── exemplars/               hand-authored HTML sources
+│   ├── ui/                      component-level exemplars
+│   └── prose/                   prose + mixed-content exemplars
+│                              extract.js compiles these → chunks/ + catalog
+│
+├── evals/                   held-out.jsonl + eval fixtures
+├── chunks/                  extracted A2UI fragments  (build output)
+├── pages/                   extracted full-page A2UI   (build output)
+├── feedback/                daily JSONL — user feedback events
+├── gaps/                    gap registry — prompts with missing coverage
+├── scripts/                 maintenance tooling (extract, ingest, feedback, ticket)
+│
+├── catalog-a2ui_0_9.json       aggregated artifact — what a2ui-compose + a2ui-mcp read
+├── catalog-a2ui_0_9_rules.txt  natural-language composition rules (per component)
+├── common_types.json           shared A2UI type shapes
+├── pattern-embeddings.json     pre-computed embeddings for semantic search
+├── functions.json              declarative wiring-engine function catalog
+├── manifest.json               extraction metadata (what / when / counts)
+├── pattern-specs.md            written specs for each pattern category
+└── data-flow.md                how the 4 signal sources feed the pipeline
+```
+
+## What's committed vs generated
+
+| Kind                       | Committed | Source of truth                        |
+|----------------------------|-----------|----------------------------------------|
+| Patterns (`patterns/`)     | ✓         | Hand-authored JSON                     |
+| Fragments/compositions     | ✓         | Hand-authored JSON                     |
+| Exemplars (`exemplars/`)   | ✓         | Hand-authored HTML                     |
+| Extracted chunks/pages     | ✓         | `scripts/extract.js` (from exemplars)  |
+| `catalog-a2ui_0_9.json`    | ✓         | `scripts/build-catalog.js` (aggregated)|
+| Feedback JSONL             | ✓         | Written by `@adia-ai/a2ui-retrieval` at runtime |
+| Gap registry               | ✓         | Written by `@adia-ai/a2ui-retrieval` at runtime |
+
+Extracted artifacts are committed for convenience (avoids a build step to
+read the pipeline), but the scripts are authoritative — regenerate via
+`npm run pipeline` if anything drifts.
+
+## Scripts
+
+All run from repo root via npm:
+
+```bash
+npm run pipeline             # extract + ingest (full refresh of chunks/ + catalog)
+npm run pipeline:stats       # report counts without writing
+npm run build:catalog        # aggregate patterns/fragments/compositions → catalog
+npm run build:catalog -- --verify   # fail if catalog is stale vs source
+
+npm run feedback:report      # human-readable feedback digest
+npm run feedback:promote     # promote high-confidence feedback → new patterns
+
+npm run ticket               # open ticket tracker
+npm run ticket:list          # list open tickets
+npm run ticket:create        # create a ticket against corpus/pipeline
+```
+
+Script inventory (`scripts/`):
+
+| Script                    | Purpose                                              |
+|---------------------------|------------------------------------------------------|
+| `extract.js`              | Exemplar HTML → A2UI chunks & pages                  |
+| `ingest.js`               | Index extracted chunks into the retrieval corpus     |
+| `run-pipeline.mjs`        | Orchestrates extract + ingest                        |
+| `build-pattern-index.mjs` | Computes pattern-embeddings.json for semantic search |
+| `feedback-report.js`      | Aggregates feedback JSONL into a readable digest     |
+| `feedback-promote.js`     | Moves high-confidence feedback into the pattern lib  |
+| `ticket.mjs`              | Corpus/pipeline issue tracker                        |
+
+## Exports
+
+```javascript
+// Catalog — the aggregated read-target for engines
+import catalog from '@adia-ai/a2ui-corpus';
+
+// Alias map + taxonomy
+import aliases from '@adia-ai/a2ui-corpus/patterns';
+
+// Held-out eval fixture
+import fixture from '@adia-ai/a2ui-corpus/evals/held-out.jsonl?raw';
+
+// Exemplar source (for scripts + docs)
+import html from '@adia-ai/a2ui-corpus/exemplars/ui/pricing-tiers.html?raw';
+```
+
+## Authoring order — demo page → exemplar → training
+
+When adding coverage for a new intent:
+
+1. **Site demo page** — author the HTML in `site/pages/examples/**`
+   using pure primitive composition (no `<style>` block, no inline
+   styles, only real components). See repo-root `AGENTS.md`.
+2. **Exemplar** — copy the working markup into
+   `a2ui/corpus/exemplars/ui/<name>.html`. Strip non-essential chrome;
+   keep attributes that encode intent.
+3. **Extract + ingest** — `npm run pipeline`. The scripts write
+   `chunks/`, `pages/`, and refresh the catalog.
+4. **Verify** — `npm run eval:diff -- --engine zettel` should still hold
+   coverage 100%, avgScore ≥ 88. Regression thresholds in `AGENTS.md`.
+
+See `data-flow.md` for the full 4-signal pipeline (exemplars →
+fragments → compositions → feedback).
+
+## Regression floors
+
+The pipeline must hold these thresholds — tracked in the held-out
+benchmark:
+
+- **Fragment reuse ratio ≥ 29.9%** — 167 refs / 559 composition nodes
+- **Zettel**: coverage 100%, avgScore ≥ 88, MRR ≥ 0.94
+- **Monolithic**: coverage 100%, avgScore ≥ 95
+- **Dogfood**: 20/20 intents at avg ≥ 95
+
+## What this package does NOT contain
+
+- Pipeline runtime — `gen-ui/`
+- UI custom elements — `web-components/`
+- MCP transport — `gen-ui-mcp/`
+- Site / playground UI — `/site/`
+
+If a file here is `.js` / `.mjs`, it's a maintenance script, not runtime.
+Runtime readers go through `gen-ui/retrieval/*`.
+
+## License
+
+MIT