@adia-ai/adia-ui-factory 0.2.3 → 0.8.0

package/skills/adia-ui-kit/evals/evals.json

@@ -1,55 +0,0 @@
-{
-  "skill_name": "adia-ui-kit",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "Build a user profile card with an avatar showing initials, the user's name and email, a role badge, and edit/delete action buttons in the footer.",
-      "expected_output": "A card-ui with header (avatar + heading + description), section with role badge, footer with edit (outline) and delete (ghost/danger) buttons.",
-      "required_components": ["Card", "Header", "Text", "Avatar", "Badge", "Button", "Footer", "Section"],
-      "forbidden_patterns": [],
-      "card_model": true,
-      "thresholds": { "aggregate": 60, "structural": 70, "intent": 50 },
-      "mode": "instant"
-    },
-    {
-      "id": 2,
-      "prompt": "Create a login form with email validation, password requiring minimum 8 characters, a remember me checkbox, forgot password link, and a full-width sign in button.",
-      "expected_output": "A card-ui wrapping form fields with input-ui (type=email, required), input-ui (type=password), check-ui, button-ui (variant=primary, block).",
-      "required_components": ["Card", "Input", "CheckBox", "Button", "Header", "Section", "Footer"],
-      "forbidden_patterns": [],
-      "card_model": true,
-      "thresholds": { "aggregate": 65, "structural": 70, "intent": 60 },
-      "mode": "instant"
-    },
-    {
-      "id": 3,
-      "prompt": "Build a metrics dashboard with 4 KPI stat cards in a row, a revenue chart below, and a recent orders table with sortable columns and pagination at the bottom.",
-      "expected_output": "Grid for KPI cards (each card > header + section > stat value + badge trend). Chart-n below. Table-n with sortable, pagination-ui in footer.",
-      "required_components": ["Grid", "Card", "Header", "Text", "Section"],
-      "forbidden_patterns": [],
-      "card_model": true,
-      "thresholds": { "aggregate": 55, "structural": 60, "intent": 40 },
-      "mode": "instant"
-    },
-    {
-      "id": 4,
-      "prompt": "Create a settings page with profile photo upload, name and email fields, notification toggles, and a save button.",
-      "expected_output": "Card with form fields, avatar, toggle switches, and primary save button in footer.",
-      "required_components": ["Card", "Header", "Section", "Input", "Button"],
-      "forbidden_patterns": [],
-      "card_model": true,
-      "thresholds": { "aggregate": 55, "structural": 60, "intent": 50 },
-      "mode": "instant"
-    },
-    {
-      "id": 5,
-      "prompt": "Build an FAQ page with a heading, description, and 5 expandable questions with answers.",
-      "expected_output": "Column layout with header and accordion items for each question.",
-      "required_components": ["Column", "Header", "Text", "Accordion"],
-      "forbidden_patterns": [],
-      "card_model": false,
-      "thresholds": { "aggregate": 55, "structural": 60, "intent": 50 },
-      "mode": "instant"
-    }
-  ]
-}

package/skills/adia-ui-kit/evals/routing-corpus.json

@@ -1,121 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "adia-ui-kit bundled routing corpus",
-  "version": "1.0.0",
-  "purpose": "Portable routing-accuracy corpus for adia-ui-kit. Each phrase declares whether the kit SHOULD be the routing target. Scored by `scripts/run-skill-evals.mjs` against the kit's description + trigger frontmatter — approximates how the harness routes intent. Per REFACTOR-SPEC P3.",
-  "scoring_notes": "The bundled scorer uses TF-IDF-style token overlap between the phrase and the kit's frontmatter. This is a HEURISTIC eval — the real harness routing may differ (especially for ambiguous phrases). Treat misroutes as a signal to tighten the kit's description / triggers, not as ground truth. Substrate runs the cross-skill version at `scripts/skills/run-skill-evals.mjs`; the bundled runner restricts evaluation to the kit alone (consumer repos don't have the sibling seniors available to compare against).",
-  "license": "internal",
-  "scope": "kit-only routing — does this phrase activate adia-ui-kit?",
-
-  "minimums_per_spec": {
-    "trigger_phrases": 10,
-    "adversarial_phrases": 5,
-    "adversarial_fraction": "33%"
-  },
-
-  "phrases": [
-    {
-      "id": "kit-01",
-      "phrase": "build a user profile card with avatar and edit actions",
-      "should_route_to_kit": true,
-      "rationale": "Canonical composition task — user profile card is a kit recipe."
-    },
-    {
-      "id": "kit-02",
-      "phrase": "generate UI for a pricing page with 3 tiers",
-      "should_route_to_kit": true,
-      "rationale": "Generative UI composition with specific layout intent."
-    },
-    {
-      "id": "kit-03",
-      "phrase": "compose a settings page with form fields and a save button",
-      "should_route_to_kit": true,
-      "rationale": "Multi-primitive composition — settings page is a kit recipe."
-    },
-    {
-      "id": "kit-04",
-      "phrase": "create an FAQ page with expandable questions",
-      "should_route_to_kit": true,
-      "rationale": "Page composition with accordion-ui pattern."
-    },
-    {
-      "id": "kit-05",
-      "phrase": "build a metrics dashboard with KPI stat cards",
-      "should_route_to_kit": true,
-      "rationale": "Dashboard composition — admin-shell + stat-ui pattern."
-    },
-    {
-      "id": "kit-06",
-      "phrase": "use AdiaUI primitives to compose a login screen",
-      "should_route_to_kit": true,
-      "rationale": "Explicit AdiaUI mention + auth-flow composition."
-    },
-    {
-      "id": "kit-07",
-      "phrase": "what's the recipe for a hero section with a CTA?",
-      "should_route_to_kit": true,
-      "rationale": "Recipe lookup — kit owns composition recipes."
-    },
-    {
-      "id": "kit-08",
-      "phrase": "compose this Figma mock into AdiaUI components",
-      "should_route_to_kit": true,
-      "rationale": "Mock-to-component translation — kit's primary mode."
-    },
-    {
-      "id": "kit-09",
-      "phrase": "build a navigation pattern with sidebar and main content",
-      "should_route_to_kit": true,
-      "rationale": "Layout pattern — admin-shell composition."
-    },
-    {
-      "id": "kit-10",
-      "phrase": "generate a chat interface from this user intent",
-      "should_route_to_kit": true,
-      "rationale": "Chat-shell composition — kit's chat cluster recipes."
-    },
-
-    {
-      "id": "kit-adv-01",
-      "phrase": "add a new component to packages/web-components/",
-      "should_route_to_kit": false,
-      "expected_alternative": "adia-ui-authoring",
-      "rationale": "Authoring NEW primitives — explicitly NEG-clause in kit description."
-    },
-    {
-      "id": "kit-adv-02",
-      "phrase": "cut a release of v0.6.34",
-      "should_route_to_kit": false,
-      "expected_alternative": "adia-ui-release",
-      "rationale": "Release cycle — not kit's domain."
-    },
-    {
-      "id": "kit-adv-03",
-      "phrase": "diagnose why zettel composition coverage dropped on the eval",
-      "should_route_to_kit": false,
-      "expected_alternative": "adia-ui-a2ui",
-      "rationale": "A2UI pipeline internals — not kit composition."
-    },
-    {
-      "id": "kit-adv-04",
-      "phrase": "explain how React useEffect hooks work",
-      "should_route_to_kit": false,
-      "expected_alternative": null,
-      "rationale": "Generic framework knowledge — kit's NEG clause covers 'unrelated frameworks'. Risk: kit's trigger block contains 'React, useEffect' as routing hints for AdiaUI-in-React projects, which has historically over-activated kit on bare React questions (documented as inherent-scorer-limit negative-02)."
-    },
-    {
-      "id": "kit-adv-05",
-      "phrase": "compose this",
-      "should_route_to_kit": false,
-      "expected_alternative": null,
-      "rationale": "Bare 'compose this' with no AdiaUI context — explicitly NEG-clause in kit description. Should not activate on the trigger word alone."
-    }
-  ],
-
-  "evaluator_notes": {
-    "current_state": "This corpus is scored by `scripts/run-skill-evals.mjs` (bundled in v2.30.0) against the kit's own description + trigger fields. The runner emits a routing F1 number; PASS for trigger-phrases means kit scores ≥ MIN_SCORE_THRESHOLD; PASS for adversarial-phrases means kit scores < MIN_SCORE_THRESHOLD (i.e. doesn't activate).",
-    "cross-skill_comparison": "When run inside the chat-ui substrate (where all 5 senior skills are present), the bundled runner falls through to the substrate's `scripts/skills/run-skill-evals.mjs` cross-skill comparison for higher fidelity. When run in a consumer repo (where only adia-ui-kit ships), it scores kit-only.",
-    "promotion_criteria": "Promote to a CI gate (warn → hard-fail) when the kit alone scores F1 ≥ 0.85 on this corpus across 3+ consecutive cycles. Until then, the corpus is for VISIBILITY (per REFACTOR-SPEC §10 OQ2).",
-    "review_cadence": "Every senior-skill quarterly checkpoint (per AGENTS.md BORIS §B3). Add 1+ new trigger / adversarial phrase per checkpoint reflecting newly-observed routing failure modes. Current cases cover: canonical composition (10), authoring-NEG (1), release-NEG (1), a2ui-NEG (1), bare-framework (1), bare-verb (1)."
-  }
-}

package/skills/adia-ui-kit/evals/teach-routing-cases.json

@@ -1,92 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "adia-ui-kit teach-routing behavioral corpus",
-  "version": "1.0.0",
-  "purpose": "Behavioral eval for the §Teach decision tree mechanization. Each case names a knowledge-payload + the expected branch (A–G) the script should classify it into. Per REFACTOR-SPEC P4.",
-  "scoring_notes": "Scored by `scripts/teach-route.mjs --eval=...`. Pass = branch matches expected_branch. Confidence (high/medium/low) is reported but doesn't affect pass/fail — track confidence trends across releases to spot vocabulary drift.",
-  "license": "internal",
-
-  "minimums_per_spec": {
-    "trigger_cases_per_branch": 1,
-    "total_cases": 7,
-    "branches_covered": "A-G all 7"
-  },
-
-  "cases": [
-    {
-      "id": "branch-A-01",
-      "payload": "new slot on calendar-picker-ui for trailing actions",
-      "expected_branch": "A",
-      "expected_landing_pattern": "packages/web-components/components/calendar-picker/",
-      "rationale": "Per-component slot addition — substrate yaml."
-    },
-    {
-      "id": "branch-A-02",
-      "payload": "add a new a2ui.rule to the table-toolbar-ui yaml clarifying when [sticky] is allowed",
-      "expected_branch": "A",
-      "expected_landing_pattern": "packages/web-components/components/table-toolbar/",
-      "rationale": "a2ui.rule = per-component contract; lives in yaml SoT."
-    },
-
-    {
-      "id": "branch-B-01",
-      "payload": "add a recipe showing how to compose an editor-shell inside admin-page-body for the nested-shell case",
-      "expected_branch": "B",
-      "expected_landing_pattern": "references/patterns-shells.md",
-      "rationale": "Cross-component composition recipe with shell focus — patterns-shells."
-    },
-    {
-      "id": "branch-B-02",
-      "payload": "recipe for wiring a chart-ui with optimistic-update controllers and signal subscriptions",
-      "expected_branch": "B",
-      "expected_landing_pattern": "references/patterns-",
-      "rationale": "Cross-component recipe — could land in patterns-data or patterns-wiring depending on gravity."
-    },
-
-    {
-      "id": "branch-C-01",
-      "payload": "end-to-end auth flow with sign-in, OTP verification, forgot-password reset, and the registration wizard",
-      "expected_branch": "C",
-      "expected_landing_pattern": "references/flows-auth.md",
-      "rationale": "Multi-page user journey covering auth — flows-auth."
-    },
-
-    {
-      "id": "branch-D-01",
-      "payload": "we need a new reasoning methodology: before any composition, decompose the user intent into named decisions with required signals (the DecisionModel posture from REFACTOR-SPEC P5)",
-      "expected_branch": "D",
-      "expected_landing_pattern": "SKILL.md inline",
-      "rationale": "Methodology / posture shift that shapes every other section — SKILL.md inline."
-    },
-
-    {
-      "id": "branch-E-01",
-      "payload": "new audit script that detects orphan components in agent output (DecisionModel trace audit per REFACTOR-SPEC P5(b))",
-      "expected_branch": "E",
-      "expected_landing_pattern": "scripts/",
-      "rationale": "Tooling addition — runnable script — scripts/."
-    },
-
-    {
-      "id": "branch-F-01",
-      "payload": "FB-42 resolved upstream; the skill used to say <admin-statusbar> defaults to slot=footer, but that was wrong. Update the skill's misdiagnosis taxonomy in CorrectionLoop.",
-      "expected_branch": "F",
-      "expected_landing_pattern": "§CorrectionLoop",
-      "rationale": "Feedback resolution — correction belongs in §CorrectionLoop."
-    },
-
-    {
-      "id": "branch-G-01",
-      "payload": "lesson learned from the v0.6.33 release cycle — the icon-loader race condition that caused FB-53 was a one-off that's already fixed upstream. Archive the post-mortem.",
-      "expected_branch": "G",
-      "expected_landing_pattern": "docs/journal/",
-      "rationale": "Arc story / historical context — journal entry, not skill."
-    }
-  ],
-
-  "evaluator_notes": {
-    "current_state": "Corpus has 9 cases across all 7 branches (A: 2 cases, B: 2 cases, C/D/E/F/G: 1 case each). Pass-rate target: 100% on the bundled corpus (the script must classify its own canonical examples correctly).",
-    "promotion_criteria": "Add 2-3 cases per quarterly senior-skill checkpoint as new payload shapes are observed. Aim for ≥3 cases per branch by v3.2.0 (per AGENTS.md BORIS §B3 cadence).",
-    "review_cadence": "When teach-route.mjs misroutes in real-world use, add the failing payload to the corpus as a new case with the correct expected_branch. The corpus grows in lockstep with the script's vocabulary."
-  }
-}

package/skills/adia-ui-kit/references/capabilities.md

@@ -1,245 +0,0 @@
----
-name: capabilities
-load-when: When choosing a mode / capability: full 14-item menu + per-mode triage table + 'pick your entry point' rows. Load if the seed's 4-item summary doesn't cover the user's intent.
-load-size-tokens: ~3,700
-required-for:
-  - mode picking
-  - first-task discovery
----
-
-# What this skill can do (capability surface)
-
-**LLM directive — on-load presentation contract.** When the user invokes
-this skill with no concrete request — e.g. `use adia-ui-kit`, `load
-adia-ui-kit`, `what can you do with AdiaUI?`, "the skill is loaded, now
-what?" — your on-load summary must follow **this exact shape**:
-
-1. One short greeting line acknowledging the skill is active and its
-   version (e.g. `✅ AdiaUI Kit skill v2.8.0 active. Here's the full
-   capability surface:`).
-2. A **numbered list (1., 2., 3., …)** with one item per category below.
-3. Each item formatted as two lines:
-   - **Line 1 (headline):** `<N>. <emoji> <Title>` — short, scannable.
-   - **Line 2 (summary):** one short sentence in plain English describing
-     what the user gets, **plus** the `→ §Section` pointer at the end.
-4. Do **not** dump the inline detail strings ("npm install …", attribute
-   names, decorator syntax) into the on-load summary. Those belong in the
-   section bodies. The on-load summary is a menu, not a manual.
-5. **Enumerate every category — do not collapse, drop, or merge.**
-   Install (📦) and Harness (🧬) are the most-missed; surface them as
-   their own numbered items, never folded into a generic "Setup" line.
-   Consultant posture (🩺, item 13) is the most-missed for brownfield
-   sessions — when the user lands in an existing repo without naming a
-   concrete request, item 13 is often the right entry point.
-6. **Render the "Pick your entry point" triage table** (verbatim from
-   below — copy the markdown table; do NOT paraphrase) immediately after
-   the 13-item menu, under the heading `### Where are you starting from?`.
-   The menu tells the user *what the skill offers*; the triage table
-   tells them *which item maps to their situation*. Both are required.
-7. End with one short prompt question (e.g. `Which would you like to
-   start with — pick a number 1-13, or describe your situation?`) —
-   never start composing markup before the user picks.
-
-The skill operates across the full project lifecycle, from `npm create
-vite@latest` through shipping a generative-UI surface. **Render the
-capability menu from the headlines + summaries below — not the detail
-fields.**
-
-### Capability menu (the on-load source-of-truth)
-
-1. 📦 **Install `@adia-ai` packages**
-   - **Summary:** The cold-start path — install the npm packages, wire
-     `main.js` with CSS + barrel + icon loader, and verify with
-     `scripts/check-adia-versions.py` that the 9-package lockstep is
-     aligned + installed ≥ latest published. **End state: a working
-     `<button-ui>` or `<card-ui>` rendering in the browser.** No
-     generative harness required at this stage — that's a separate
-     opt-in (item 4) for apps that render LLM-generated UI at runtime.
-     **If the project has no `AGENTS.md` / `CLAUDE.md` at the root,
-     scaffold them from `assets/templates/` so future agent sessions
-     auto-load with the right skill pointer.** → §Setup + §VersionCheck
-   - *Detail (for the body, not the on-load menu):* `npm install
-     @adia-ai/web-components @adia-ai/web-modules @phosphor-icons/core`,
-     wire CSS + barrel import + `installIconLoadersForRegistered`,
-     minimal Vite config, TypeScript types, per-component imports for
-     tree-shaking, conflict-safe `defineIfFree` registration.
-     **Verify** with `scripts/check-adia-versions.py` — reports
-     installed / declared / latest side-by-side and exits non-zero on
-     lockstep break, stale install, or undeclared user-facing package.
-     **Bootstrap** `AGENTS.md` + `CLAUDE.md` (1-line pointer) from
-     `assets/templates/` if absent — see §Setup Step 8. **`<canvas-ui>` /
-     `<a2ui-root>` / `registerResolver` are NOT part of basic install** —
-     they belong to the generative harness (item 4), which the vast
-     majority of product UIs (dashboards, forms, data tables, auth
-     flows) do not need.
-
-2. 🖼️ **Wire AdiaUI into an existing framework app**
-   - **Summary:** Drop AdiaUI into SPA, Next.js, Nuxt, SvelteKit, or
-     Astro with framework-correct imports and property binding.
-     → §Rendering Model
-   - *Detail:* `'use client'` boundaries, hydration guards, React
-     `useEffect`+`ref`, Vue `:value`, Svelte `bind:value`, SSR-safe
-     barrel placement.
-
-3. 🤖 **Install + use the AdiaUI MCP server**
-   - **Summary:** Drive AdiaUI from your agent IDE (Claude Desktop /
-     Claude Code / Cursor / Windsurf) via the `adiaui-mcp` server.
-     → §MCP
-   - *Detail:* one-time host registration, provider keys, native tools
-     `generate_ui` / `list_patterns` / `refine_ui` / `server_status`,
-     dual stdio (sampling) + HTTP transports.
-
-4. 🧬 **Choose a generative-UI rendering mode**
-   - **Summary:** Once the harness is mounted (item 1), decide *when*
-     generation happens — at build time (static HTML), at runtime from
-     a `doc=` array (no server), or live via SSE/MCP streaming. → §Harness
-   - *Detail:* Mode A (author-time → static HTML committed to repo),
-     Mode B (runtime `doc=` rendering, no server), Mode C (SSE/MCP
-     streaming), `canvas.process()` / `canvas.processAll()` /
-     `canvas.reset()` API, when each mode is the right fit.
-
-5. 🚚 **Migrate from `@agent-ui-kit` or an older `@adia-ai` version**
-   - **Summary:** Bring an inherited or pre-existing codebase forward —
-     namespace rename (`@agent-ui-kit/*` → `@adia-ai/*`), tag renames,
-     attribute changes, token renames, retired legacy shell shapes,
-     and every version-cut breaking change up to `^0.6.0`. → §Migration
-     (defers to `docs/MIGRATION GUIDE.md` + the `adia-ui-migration` skill
-     for the mechanical sweep)
-   - *Detail:* Predecessor namespace `@agent-ui-kit/web-components` →
-     `@adia-ai/*` 9-package monorepo; base class `AgentElement`/`AdiaElement`
-     → `UIElement`; design tokens `--agent-*` → `--a-*`; `<stat-ui>` →
-     `<stat>` filename; `<link-ui>` token rename `--link-color-*` →
-     `--link-fg-*`; legacy shell authoring shapes RETIRED in `0.4.0`
-     (ADR-0024) — use the bespoke `<admin-shell>` / `<chat-shell>` /
-     `<editor-shell>` vocabulary. Mechanical sweeps via the dedicated
-     `adia-ui-migration` skill — call it explicitly for codebase-wide
-     search-and-replace + verification gate.
-
-6. 🏗️ **Build screens and flows (phase-gated)**
-   - **Summary:** Compose a new surface via §0 plan → §1 catalog → §2
-     markup → §3 validation. Never skip §0. → §0 Reasoning Gate
-   - *Detail:* GenUI Plan + confirmation wait, yaml/a2ui.json lookup,
-     HTML + A2UI JSON composition, 5-gate validation checklist.
-
-7. 🔌 **Wire state and data**
-   - **Summary:** Add reactivity, domain state, and live endpoints
-     without script blocks of `fetch()`. → §State
-   - *Detail:* signals (local), `BaseController` (domain state with
-     optimistic + undo/redo), `data-stream-*` bindings (REST/SSE),
-     form submission patterns.
-
-8. 🎨 **Theme and brand**
-   - **Summary:** Apply named themes, toggle light/dark, or override
-     brand colors via tokens. → §Theme
-   - *Detail:* `toggle-scheme`, density modes, custom theme registration,
-     zero-specificity token overrides.
-
-9. 🧩 **Apply real-world patterns**
-   - **Summary:** Reach for proven assemblies — admin shell, tables,
-     dashboards, charts, drawers, error pages, agent surfaces.
-     → §Patterns
-   - *Detail:* admin/editor/nested/simple shells, command palette,
-     `table-ui` + `table-toolbar-ui` pairing, KPI grids, all 18 chart
-     types, heatmaps, destructive confirms, 404/500, chat streaming +
-     reasoning panels.
-
-10. 📋 **Copy-paste end-to-end flows**
-    - **Summary:** Full recipes for the common surfaces — auth, wizard,
-      onboarding, settings, marketing, kanban. → §Flows
-    - *Detail:* sign-in / OTP / forgot-password, registration wizard,
-      persona picker, settings page, marketing hero, kanban board, user
-      profile card.
-
-11. 📚 **Discover documentation**
-    - **Summary:** Look up components, tokens, guides, and live demos
-      without inventing URLs. → §Docs
-    - *Detail:* URL manifest for `ui-kit.exe.xyz/site/...`, in-package
-      files (`<name>.yaml` / `.a2ui.json` / `.d.ts` / `.test.js` /
-      `.examples.md` v0.6.7+), numbered guides in `docs/guides/`,
-      specs in `docs/specs/`, documentation triage table.
-
-12. 📝 **Author session logs + defensible upstream tickets**
-    - **Summary:** Capture provenance and file upstream FEEDBACK
-      maintainers can act on. Agents draft to
-      `.agents/team/tickets/drafts/` on a rolling basis; humans finalize
-      to `outbox/`; responses land in `inbox/`. The 4-stage pipeline is
-      gated by `ticket-tool.py` (11 finalize gates).
-      → §FeedbackDiscipline + §Team Tickets + §AutoCapture + §TicketTooling
-    - *Detail:* `generate ui-kit log` → `.adia-ui-kit/session-log.md`;
-      `ticket-tool.py new feedback <recipient> --slug <s>` scaffolds a
-      draft from the 5-block template (Executive summary + cost table +
-      per-finding What/Root/Repro/Request/Why + verified exclusions +
-      pre-finalize checklist); `ticket-tool.py finalize NN` runs 11 gates
-      and promotes drafts/ → outbox/; `retract` / `set-status` /
-      `register-response` / `registry-rebuild` handle lifecycle.
-      Discipline vendored from color-app's battle-tested
-      `.agents/team/skills/feedback-authoring.md` (60+ shipped tickets).
-
-13. 🩺 **Diagnose an inherited / unknown AdiaUI repo (Consultant posture)**
-    - **Summary:** Land in a brownfield repo you don't know, walk a
-      9-step inventory + 3-class gap-detection, and produce a Repo
-      Health Report scoring overall posture across primitive usage,
-      composition shape, token coverage, version coherence, and
-      consumer-side hygiene. Use **before** filing tickets, proposing
-      migrations, or authoring new surfaces — the report tells you
-      what's already there and where the actual gaps are.
-      → §Recon + §GapDetection + §DiagnosticOutput
-    - *Detail:* 9-step recon (sitemap / package.json / @adia-ai version
-      coherence / shell-tier inventory / token usage / primitive census
-      / unused-import scan / a11y signals / build state); 3 gap classes
-      (substrate-misuse, version-drift, missing-discipline); diagnostic
-      template (executive summary + per-gap What/Evidence/Layer/Fix +
-      posture assessment). Archive each report alongside the consuming
-      repo's other diagnostics (e.g. a `diagnostic-reports/` folder),
-      named `YYYY-MM-DD-<repo>-health-report.md`.
-      Pair with §CorrectionLoop when a specific bug is reported (the
-      report tells you the landscape; the correction loop tells you how
-      to reason about a specific defect).
-
-14. 📚 **Teach the skill new knowledge (Teach posture)**
-    - **Summary:** Land new knowledge (a new primitive, a new pattern,
-      a resolved FEEDBACK ticket, a methodology shift) into the right
-      target without bloating the skill or drifting from yaml SoT. The
-      Teach protocol's decision tree routes each input to its correct
-      home — yaml SoT (per-component facts), a patterns reference
-      (cross-component recipes), a flows reference (end-to-end
-      journeys), inline SKILL.md (methodology / posture), tooling
-      cross-link, FEEDBACK correction, or **NO landing in the skill**
-      (arc stories belong in the journal, not here). Triggers: "make
-      sure adia-ui-kit knows about X", "train the skill on Y", "absorb
-      this lesson into adia-ui-kit", "the skill should be aware of Z".
-      → §Teach (→ `references/teach-protocol.md` for the full procedure)
-    - *Detail:* 5-step landing procedure (audit before patching →
-      author the patch → wire the activation surface → version +
-      CHANGELOG → verify with `audit:skill-hygiene`). Seven worked
-      examples covering every decision-tree branch including the
-      negative case ("arc stories go in journal, not skill"). Seven
-      anti-patterns observed during this skill's own evolution
-      (append-only, yaml SoT duplication, orphan triggers, capability
-      menu lies, MINOR + PATCH bundling, hygiene-debt deferral,
-      one-way thinking). Use when another agent in the codebase hands
-      you new content to integrate; **don't use** when authoring fresh
-      from scratch (that's §Mission Author posture) or fixing a wrong
-      claim (§CorrectionLoop).
-
-**Pick your entry point** by where the project is today:
-
-| Project state                                              | Start at           |
-| ---------------------------------------------------------- | ------------------ |
-| **Inherited / unknown repo — diagnose first**              | **§Recon + §GapDetection + §DiagnosticOutput** |
-| Empty / fresh `npm create vite@latest`                     | §Setup + §Harness  |
-| Existing SPA / Next / Nuxt / SvelteKit / Astro             | §Rendering Model   |
-| Existing AdiaUI app, want runtime/generative UI            | §Harness           |
-| Existing app on `@agent-ui-kit` or older `@adia-ai` version | §Migration         |
-| Want to drive AdiaUI from an agent (Claude/Cursor/Windsurf)| §MCP               |
-| **Teaching the skill new knowledge — \"make adia-ui-kit aware of X\"** | **§Teach**         |
-| Existing AdiaUI app, building a new feature                | §0 Reasoning Gate  |
-| Need to recreate a known surface (admin / chat / form)     | §Flows or §Patterns |
-| Found a bug or want to file feedback                       | §Tickets           |
-| Wrong output reported — diagnose before fixing             | §CorrectionLoop    |
-
-If the user request is ambiguous about which entry point applies, **ask
-one clarifying question** (e.g. "is this a new project or an existing
-app?") before recommending steps. Don't assume cold-start.
-
----