@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/references/loading-protocol.md

@@ -0,0 +1,406 @@
+---
+name: loading-protocol
+load-when: Before any procedural work — to know which references to load on demand, what the cold-start contract is, what the pre-author bundle gate triggers on, and what the harness manifest declares
+load-size-tokens: ~6,800
+required-for:
+  - cold-start
+  - any task crossing 2+ references
+  - any §Teach landing
+---
+
+# §LoadingProtocol — Inversion / progressive disclosure (read this before browsing further)
+
+This skill is structured as a **seed plus reference bundles**, not as a
+monolith. SKILL.md (you are here) is the seed: it carries identity,
+priors, posture decisions, hard rules, the harness manifest, and the
+reference manifest. **The bulk of procedural detail lives in
+`references/<topic>.md` files that you load on demand.**
+
+This is *inversion*: tiny initial footprint, agent has enough harness
++ tooling references to discover what it needs and load it as it goes.
+
+### Why inversion
+
+A skill is procedural memory loaded into agent context. At ~78K
+tokens the monolithic version of this skill consumed ~40% of a 200K
+context window *before any work happened*. Most sessions only need
+10-20% of the skill — a forward-authoring session doesn't need the
+ticket pipeline, a diagnostic session doesn't need the cold-start
+setup, etc. Loading everything to use a slice is wasteful and crowds
+out the actual task content.
+
+The inversion contract: **the seed teaches the agent what exists +
+when to load it. Loading is the agent's responsibility, not the
+skill's.**
+
+### The loading protocol
+
+When you (the agent) need something from this skill that isn't in the
+seed:
+
+1. **Check the reference manifest below** to find the right bundle.
+   Bundle names map to task categories (`patterns-shells.md`,
+   `feedback-authoring.md`, etc.).
+2. **Load the bundle via `skill_view(name='adia-ui-kit',
+   file_path='references/<bundle>.md')`**. This is a single tool
+   call. The bundle enters context only for the section it's
+   needed.
+3. **Do not preload bundles speculatively.** Each load has a token
+   cost. Load when the current step requires it.
+4. **When in doubt, search the seed first.** A `grep`-style scan of
+   SKILL.md is cheaper than loading a bundle "just in case."
+5. **If a bundle you expect doesn't exist, check the migration
+   status in the manifest** — some sections still live inline in
+   SKILL.md (mid-migration; see the §SkillHygiene token-economy
+   axis for context).
+
+### The pre-author bundle gate (mandatory loads before generation)
+
+The discretionary "load on demand" rule above (points 1–5) has one
+hard exception: **shell, dashboard, and product-surface authoring tasks
+have mandatory pre-loads.** Without them, agents systematically miss
+the canonical 10-tag admin-shell shape, the responsive layout
+primitives, the `[data-sidebar-toggle]` declarative attribute, and the
+canonical KPI card composition — all of which live in bundles, not in
+the seed.
+
+**Trigger keywords (any of these in the user's request fires the gate):**
+
+Direct shell/dashboard mentions:
+`shell`, `admin shell`, `editor shell`, `chat shell`, `simple shell`,
+`page shell`, `admin product`, `product surface`, `dashboard`,
+`admin dashboard`, `admin UI`, `admin ui`, `the admin`, `our admin`,
+`page anatomy`, `app shell`.
+
+Composition verbs paired with shell/page concepts:
+`build the whole thing`, `build it all`, `proceed to build all of it`,
+`wire up the shell`, `compose this page`, `compose the page`,
+`compose the shell`, `compose the admin`, `compose the dashboard`,
+`build a KPI`, `build the dashboard`, `build the admin`,
+`build the sidebar`, `build the topbar`, `build the layout`,
+`lay out a page`, `lay out the dashboard`, `assemble the UI`,
+`assemble the dashboard`, `assemble the admin`,
+`make the admin`, `make a dashboard`, `make the UI`, `set up the shell`,
+`set up the dashboard`, `scaffold the admin`, `scaffold a dashboard`,
+`scaffold the page`.
+
+Component-level mentions that imply shell composition:
+`sidebar`, `topbar`, `statusbar`, `breadcrumb`, `nav-ui composition`,
+`page header`, `page body`, `KPI cards`, `KPI grid`, `stat cards`,
+`metric cards`, `dashboard cards`, `command palette`, `app rail`,
+`nav rail`, `side navigation`, `collapse sidebar`, `resizable sidebar`,
+`responsive layout`, `app layout`, `screen layout`.
+
+Plural/possessive variants:
+`our dashboard`, `their admin`, `the dashboards`, `our admins`,
+`the operator dashboard`, `the analytics dashboard`,
+`extend the admin`, `extend our admin`, `update the dashboard`,
+`update the admin`, `improve the admin`, `improve the dashboard`,
+`refactor the admin`, `refactor the dashboard`,
+`fix the admin`, `fix the dashboard`, `redo the admin`,
+`redo the dashboard`, `clean up the admin`, `clean up the dashboard`.
+
+Consumer feedback patterns (user reports broken shell rendering):
+`my dashboard looks broken`, `my admin looks broken`,
+`the shell looks broken`, `the shell doesn't look right`,
+`the admin doesn't look right`, `the sidebar is missing`,
+`the topbar is missing`, `no surface contrast`, `no inset`,
+`bleeding into content`, `looks unstyled`, `looks raw`,
+`looks like a placeholder`, `looks unfinished`,
+`compare against ui-kit.exe.xyz`, `vs the reference`, `vs reference`.
+
+**Trigger discipline**: this list is INTENTIONALLY broad because the
+FEEDBACK-41 / FEEDBACK-NN regression-class consistently traps agents
+under context pressure who infer that "user said extend the admin so
+this is a small edit, not a shell composition". Bias the gate toward
+firing too often; the cost of a redundant bundle load is small, the
+cost of a non-canonical admin-shell ship is the entire FEEDBACK-41
+cluster.
+
+When any trigger fires, **before writing markup**, load:
+
+1. `patterns-recipes.md` — locate "Advanced — full markup
+   (start here for any new product surface)" (lines 188–340). Use it as
+   the baseline; subtract sections (Simple → Minimal) only when the
+   user explicitly opts out, not by default.
+2. `patterns-shells.md` — for sidebar/topbar/breadcrumb
+   composition + the §Anti-patterns list (hand-rolled toggle, header
+   nesting, shell composition violations).
+3. `patterns-layout.md` — for the `@bp` responsive notation
+   on `grid-ui` / `row-ui` / `col-ui` (xs=0/sm=480/md=768/lg=1024/xl=1280)
+   and the "never inline `grid-template-columns`" rule.
+
+This is NOT a violation of point 3 above ("don't preload speculatively").
+The "Advanced" recipe is explicitly self-described as *"start here for
+any new product surface"* and resolves every shell-tier authoring
+decision in one read. Loading it is the *next* step the protocol's
+point 1 ("check the reference manifest") points at — the gate just
+removes the discretion.
+
+**Failure-mode receipt.** Skipping the gate produces the FEEDBACK-41
+cluster: `slot="leading"` missing on `<admin-sidebar>`,
+`<admin-statusbar>` missing, `<breadcrumb-ui>` missing, hand-rolled
+`sidebar.toggle()` JS instead of declarative `[data-sidebar-toggle]`,
+bare `<stat-ui>` instead of `<card-ui><section><stat-ui /></section>
+</card-ui>`. Five canonical-shape defects shipped in one cold-start
+build before the user caught it.
+
+**Failure-mode receipt #2 (2026-05-23 claims-ui regression).** Even with
+the FEEDBACK-41 documentation in place, claude-code-Sonnet-4.6 in a
+consumer repo (claims-ui) shipped a NEW admin dashboard missing
+`<admin-statusbar>` at content footer, missing `[data-spacer]` +
+`[data-actions]` in the content topbar (no theme picker, no command
+palette, no global action affordances), and an incomplete sidebar
+topbar (no context-switcher menu — just plain text branding). Recipe
+was complete; gate was not loaded; user surfaced regression via visual
+diff against `ui-kit.exe.xyz/site/examples/admin-dashboard`. Hardening
+that landed: this trigger keyword list was broadened to catch natural
+phrasings like "extend the admin" / "the admin doesn't look right" /
+"my dashboard looks broken" that the prior list missed, plus the
+verification step below was added to stop agents who skim past the gate.
+
+**Verification before generation (use this gate as a stop-condition):**
+After loading the bundles, **explicitly enumerate** which of the 13
+canonical admin-shell parts your generation will include. The
+authoritative reference is `chat-ui:site/index.html` lines 42-120 —
+that's the actual source that renders the live docs site at
+`ui-kit.exe.xyz/site/examples/admin-dashboard`:
+
+1. `<admin-shell mode="rounded borderless">` outer (or another canonical mode)
+2. `<admin-sidebar slot="leading" resizable collapsible>` (left rail)
+3. Sidebar's inner `<admin-topbar slot="header">` with `<select-ui avatar="…" value="…" variant="ghost">` (workspace/context switcher — NOT `<menu-ui>`; that's the legacy v0.5.x pattern from `admin-shell.examples.html`. The live docs site uses select-ui because it auto-stamps the avatar + label + caret-up-down row and has narrower API surface)
+4. Sidebar's `<section-ui>` (the AdiaUI primitive, NOT native `<section>`) wrapping `<nav-ui>` with `<nav-item-ui>` / `<nav-group-ui>` children. The section-ui wrap is what admin-sidebar's light-DOM CSS targets for inner scroll + padding.
+5. Sidebar's `<admin-statusbar slot="footer">` with `<select-ui avatar="…" value="…" variant="ghost">` for user menu (same primitive as #3, NOT `<menu-ui>` + `<avatar-ui>` + button-trigger)
+6. Sidebar's `<div data-resize></div>` resize handle (REQUIRED when `resizable` attribute is on)
+7. `<admin-content>` with inner `<admin-topbar>` containing `<button-ui data-sidebar-toggle="leading" icon="sidebar">` + `<breadcrumb-ui>` + `<span data-spacer>` + `<div data-actions>`. The toggle button uses `icon="sidebar"` attribute — NOT a child `<icon-ui>`. **Note on slot attribute:** This list uses no-slot form for `<admin-topbar>` inside `<admin-content>`. `slot="header"` is also accepted and renders identically — `<admin-content>` is light-DOM per ADR-0033, so `slot=` is inert and CSS positions `admin-topbar` by tag + DOM order regardless. `patterns-recipes.md` and `site/index.html` use `slot="header"` form for parity with substrate demos. Both forms are correct; do not "fix" one to the other.
+8. `[data-actions]` (or new-code canonical `slot="action"`) contains `<popover-ui>` wrapping `<button-ui icon="palette" slot="trigger">` + `<theme-panel slot="content" persist parametric presets scheme-toggle>`. NOT a custom `<theme-picker-ui>` element — that doesn't exist; `theme-panel` is the actual primitive. Plus any other right-aligned action buttons (e.g. `[data-sidebar-toggle-trailing]` for the changelog rail).
+
+   **`slot="action"` vs `[data-actions]`** — `slot="action"` is the new-code canonical per `admin-topbar.yaml` (v0.6.13+); `[data-actions]` coexists for one release as a back-compat alias. New code should prefer `slot="action"`. Both render identically.
+
+   **🚨 CRITICAL CONTENT RULE — page CTAs DO NOT belong here.** The topbar trailing cluster (`slot="action"` or `[data-actions]`) carries **GLOBAL** controls only — theme picker, trailing-sidebar toggle, notifications bell, global "+ Quick add" if it spawns a global menu. **Page-scoped CTAs** like `+ New Claim`, `+ New Customer`, `Export CSV`, `Save Draft` belong in `<admin-page-header>` as `<button-ui slot="action">` children, NOT in the topbar trailing cluster. This is the FEEDBACK-58 §3 failure mode — agents follow this list, see `[data-actions]` described as "the trailing action container," and place page CTAs there. Result: every page in the app shows that one page's CTA in the global topbar (it sticks across navigation; it doesn't update). See `patterns-recipes.md` Advanced route fragment for the canonical page-CTA placement pattern.
+9. `<admin-scroll>` wrapping optional `<aside data-subnav hidden>` + `<router-ui>` (for routed pages; place `<admin-page>` directly here for non-routed surfaces)
+10. `<admin-page>` (inside router-ui or admin-scroll) with `<admin-page-header>` + `<admin-page-body>`
+11. `<admin-statusbar>` at content footer for version-strip band (`<span>Name</span> <span data-spacer></span> <span>vX.Y.Z</span>` — NOT just sidebar's statusbar; the content has its own statusbar slot)
+12. Second `<admin-sidebar slot="trailing" resizable collapsible hidden>` (right rail, hidden by default; toggled via `[data-sidebar-toggle-trailing]` buttons). Has its own `<admin-topbar slot="header">` with `<span slot="heading">` + `<button-ui slot="action">` close button.
+13. `<admin-command>` with `<command-ui placeholder="Search pages...">` (cmd-K palette — top-level child of `<admin-shell>`, NOT nested inside `<admin-content>`; admin-command self-stamps a `<dialog>` when activated)
+
+If your generation plan is missing any of parts 1-13, you haven't read
+the recipe. Load `patterns-recipes.md` Advanced section
+again — note that as of v2.27.0 (2026-05-23), the recipe was corrected
+to align with `site/index.html` (it had previously been ambiguous,
+naming both `<menu-ui>` and `<select-ui>` as valid context-switcher
+patterns; site/index.html is now declared the single canonical reference).
+
+If the user explicitly opted out of one (e.g. "minimal sidebar, no
+statusbar"), cite the opt-out in the generation plan; without the
+explicit opt-out, parts 1-11 are mandatory and parts 12-13 are strongly
+recommended (the live docs site has both).
+
+**Pair the 13-part composition with the CSS bootstrap.** A complete
+shell generation is structural composition PLUS the matching CSS/JS
+load. Pick one bootstrap path before generating markup:
+
+| Consumer mode | CSS bootstrap (in `<head>` or entry file) | JS bootstrap |
+|---------------|-------------------------------------------|--------------|
+| **CDN-first** (CodePen, marketing, static HTML, fresh repo with no `package.json`) | Two `<link>` tags: `web-components.min.css` + `<shell>.min.css` from `cdn.jsdelivr.net/npm/@adia-ai/*` | One `<script type="module">` tag pointing at `web-modules/.../dist/everything.min.js` |
+| **Bundler explicit-import** (production Vite/webpack) | Three `import` statements in entry: `'@adia-ai/web-components/css'` + (optional brand override) + `'@adia-ai/web-modules/shell/admin-shell.css'` | `import` statements registering primitives + shells (per §Setup) |
+| **Bundler `/with-css` opt-in** | One `import '@adia-ai/web-modules/shell/admin-shell/with-css'` (side-effect CSS bundled in) | Same as explicit-import for JS |
+
+The 2 CDN `<link>` tags map 1:1 to the bundler's 3-import pattern
+(tokens+catalog → shell CSS). When generating shell markup, the bootstrap
+choice MUST be cited alongside the composition — otherwise the consumer
+ships canonical structure with unstyled-stacked-divs rendering. **Both
+sides of the contract land in the same generation step.**
+
+**Stop-condition before generation:** you have the three bundles loaded
+AND have identified the recipe section that matches the user's task
+(Advanced for full product, Simple if user opted out of statusbar /
+trailing sidebar, Minimal for a skeleton app) AND have enumerated
+which of the 8 canonical parts you're including. If you can't name
+which section you're working from OR can't enumerate the 8 parts, you
+haven't loaded enough.
+
+### The harness manifest (scripts you can use)
+
+The skill ships with its own scripts (live inside the skill folder,
+travel with it to consumer repos) AND lives alongside substrate-side
+scripts (live in chat-ui's `scripts/skills/`, operate on the skill
+system itself). Both are part of the harness; knowing which is which
+tells you where to find them and whether they're available outside
+chat-ui.
+
+**Skill-bundled scripts** — live in this skill's own `scripts/`
+directory (resolve relative to the skill root; as a plugin,
+`${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-kit/scripts/`). Travel with the
+skill to any repo that vendors it. Operate on AdiaUI repos / consumers.
+
+| Tool | When to use | Invocation |
+|---|---|---|
+| `check-adia-versions.py` | Version-drift check during §Recon / §VersionCheck | `python3 scripts/check-adia-versions.py --root <path>` |
+
+**Substrate-resident scripts** — live at `scripts/skills/` in the
+chat-ui repo. Operate on the **skill system itself** (any skill, not
+just adia-ui-kit), so they're substrate-internal tooling and not
+available in consumer repos. Run via `npm run <task>` from chat-ui.
+
+| Tool | When to use | npm task |
+|---|---|---|
+| `audit-skill-hygiene.mjs` | Run the 8-axis hygiene audit on a skill | `npm run audit:skill-hygiene [skill-name]` |
+| `check-skill-patterns-sot.mjs` | Validate §Patterns SoT citations + tag vocabulary | `npm run check:skill-patterns-sot` |
+| `check-skill-frontmatter.mjs` | Validate skill frontmatter + intra-skill refs | `npm run check:skills` |
+| `audit-skills.mjs` | Aggregate skill metrics across the corpus | `npm run audit:skills` (if wired) |
+| `draft-skill.mjs` | Scaffold a new skill | `npm run draft-skill <name>` (if wired) |
+| `iterate-skill.mjs` | Apply iterative improvements to a skill | `npm run iterate-skill <name>` (if wired) |
+
+The split is **load-bearing**: when a consumer agent in `claims-ui-v4`
+needs to verify versions, they invoke the skill-bundled `check-adia-
+versions.py` directly (it ships with the vendored skill). When the
+same agent wants to audit the skill itself, that's substrate-internal
+work and they need to be in the chat-ui repo.
+
+### The peer-skill manifest (sibling skills you can defer to)
+
+This skill is the **anchor** for AdiaUI agent work, but it's not the
+only AdiaUI-related skill. The sibling skills below all live at
+`.agents/skills/<name>/` in the substrate repo. **Defer to them
+explicitly** when your task matches their specialty — don't
+re-implement what they already teach.
+
+| Peer skill | What it owns | When to defer |
+|---|---|---|
+| `adia-ui-authoring` | In-tree authoring engineer (absorbs `primitive-audit` + `bespoke-shell-children` + `promote-inline-to-module` + `adia-ui-code-bestpractices` + `llm-bridge-extension` + `adia-ui-author` rename) | Authoring / modifying primitives + shells + modules; extracting inline UI patterns into module-tier elements; extending the LLM bridge |
+| `adia-ui-migration` | Mechanical sweep automation for cross-version migrations | Codebase-wide rename (`@agent-ui-kit` → `@adia-ai`, `AgentElement` → `UIElement`, `--agent-*` → `--a-*` tokens); has grep + perl-rewrite recipes |
+| `adia-ui-a2ui` | A2UI generation pipeline substrate (absorbs `a2ui-pipeline` + `adia-ui-training` + `zettel-internals`); covers compose strategies, chunk corpus, fragment graphs, MCP server, retrieval, validator, runtime | Debugging A2UI JSON flows, generator/MCP/zettel synthesis, training data curation, eval-gap diagnosis, composition-strategy tuning |
+| `adia-ui-release` | Autonomous release engineer (cut + publish + EXE deploy + audit-history ledger; absorbs `release-publish` + `release-notes` + `verification-sweep`) | Cutting v0.6.X / batch push / version-skip recovery / GH release authoring / full `npm run check` umbrella + interpreting results / substantive CHANGELOG authoring |
+| `adia-ui-ops` | Operator skill for the AdiaUI substrate (absorbs `exe-dev-ops` + `ops-repo`); covers infrastructure (exe.dev VM deployment + service ops) + repo hygiene (memory layer audit, ADR rotation, postmortem sweep, stale content) | exe.dev deploy / diagnose `<host>.exe.xyz` / rotate keys / repo brain audit / `.brain/` curation / cross-cutting substrate maintenance |
+| `dogfood-sweep` | Exploratory dogfood QA testing of UI surfaces | Hunting for visual / behavioral regressions across canonical demos |
+
+**The deferral rule.** If a task is squarely in a peer skill's
+specialty, **invoke that skill rather than duplicating the procedure
+here**. Cross-skill linking is cheaper than cross-skill teaching —
+the peer skill stays maintained at its source.
+
+To load a peer skill: in agent harnesses that support it (`skill_view`,
+`skill-use`, etc.):
+
+```
+skill_view(name='adia-ui-migration')
+```
+
+Or read directly: `.agents/skills/<name>/SKILL.md`.
+
+### The reference manifest (bundles you can load on demand)
+
+| Bundle | Topic | When to load | Status |
+|---|---|---|---|
+| `local-link.md` | `file:` symlink consumer ↔ substrate (no npm round-trip) | When iterating on substrate + consumer simultaneously | **full extract** (v2.20.0) |
+| `mcp.md` | AdiaUI MCP server install + tool reference | When setting up generative-UI in an agent IDE | **full extract** (v2.20.0) |
+| `rendering-model.md` | SPA / SSR / static rendering, framework integration | When target framework is Next/Nuxt/SvelteKit/Astro | **full extract** (v2.20.1) |
+| `setup.md` | Cold-start: 8-step Vite + vanilla JS scaffold | When starting a new AdiaUI project from scratch | **full extract** (v2.20.2) |
+| `figma-make.md` | CDN load for Figma Make / Bolt / Lovable / v0 / StackBlitz — all CSS + JS bundle URLs, kitchen-sink default, JSX caveats | When the target is Figma Make or any prompt-to-app / web-container codegen tool | **full extract** (v3.8.0) |
+| `flows-auth.md` | Auth, registration, onboarding wizard flows | When implementing sign-in / sign-up / forgot-pw / multi-step registration / first-run onboarding | **full extract** (v2.20.3) |
+| `flows-shells.md` | App-shell composition (admin / chat / editor) | When composing the shell-tier of a multi-route app | **full extract** (v2.20.3) |
+| `flows-data.md` | Settings, tables, dashboard + KPI, charts | When wiring data-display surfaces | **full extract** (v2.20.3) |
+| `flows-interaction.md` | Command palette, destructive modal, profile card, marketing hero | When wiring transient/interactive surfaces | **full extract** (v2.20.3) |
+| `flows-content.md` | Error pages, kanban boards, agent surfaces | When wiring content-tier surfaces | **full extract** (v2.20.3) |
+| `patterns-shells.md` | Admin / chat / editor shell patterns | When building any shell-tier composition | **full extract** (v2.20.4) |
+| `patterns-data.md` | Tables, charts, stats, KPIs | When wiring data display | **full extract** (v2.20.4) |
+| `patterns-forms.md` | Inputs, fields, validation | When building forms | **full extract** (v2.20.4) |
+| `patterns-layout.md` | Grid, row, col, gap, page anatomy | When laying out content | **full extract** (v2.20.4) |
+| `patterns-wiring.md` | data-stream, event bindings, state | When wiring components to data | **full extract** (v2.20.4) |
+| `patterns-agent.md` | Agent-surface (chat, reasoning, activity) | When building agent UI | **full extract** (v2.20.4) |
+| `patterns-traits.md` | Trait system + composition | When working with traits | **full extract** (v2.20.4) |
+| `patterns-recipes.md` | Prompt-shaped recipes: admin shell anatomy, REST→component data binding, chart wiring, entity list/drawer, status badge, design-board → tokens, v0.6.18 loading, toasts | When matching a "give me the recipe for X" prompt | **full extract** (v2.20.4) |
+| `teach-protocol.md` | §Teach posture: decision tree + 5-step landing + 7 worked examples + 7 anti-patterns for absorbing new knowledge into THIS skill | When another agent says "make adia-ui-kit aware of X" / "train the skill on Y" / "absorb this lesson" | **full extract** (v2.21.0) |
+| `feedback-authoring.md` | Drafting upstream feedback tickets | When filing FEEDBACK-NN against substrate | full extract |
+| `response-authoring.md` | Authoring RESPONSE-NN to inbound tickets | When responding to consumer feedback | full extract |
+
+**Status legend:**
+
+- *full extract* — content lives in references/, SKILL.md has a one-paragraph stub pointing here.
+  - *inline+ref* — content currently duplicated in SKILL.md and references/; migration target.
+  - *full extract (v.X.Y)* — content lives ONLY in references/; the seed has a stub. As of v2.20.4 all 12 bundles are full-extract.
+- *inline only* — content not yet extracted; lives in SKILL.md.
+
+The migration goal is **all reference-shaped content → references/**.
+The seed retains: identity, priors, posture decisions, hard rules,
+manifests, the §0-§3 phase spine, and the cross-section discipline
+contracts (§FeedbackDiscipline, §SkillHygiene, this section).
+
+### What stays in the seed (and why)
+
+Seed-resident content has one of three properties:
+
+1. **It's required at decision-time, before the agent knows what
+   task they're on.** §Mission's posture-decision rule, §Reasoning­
+   Methodologies' priors, §CorrectionLoop's zeroth-question — all
+   need to be in the agent's head before any task-specific bundle
+   loads.
+2. **It's a manifest pointing at things.** This section is itself a
+   manifest; the §Docs URL manifest is another; the capability menu
+   is a third. Manifests have to be in the seed by definition.
+3. **It's the procedural spine** — §0 Reasoning Gate, §1 Catalog
+   Lookup, §2 Composition, §3 Validation. These are the universal
+   per-feature checkpoints; every forward-authoring task touches
+   them, so they pay their seed-cost honestly.
+
+Everything else (recipe libraries, flow examples, command reference
+pages, ticket-pipeline mechanics) is reference-shaped and belongs
+in `references/`.
+
+### What this means in practice
+
+For a task like "build a settings page in claims-ui-v4":
+
+```
+LOAD ORDER (with this protocol):
+  1. SKILL.md (seed, ~? K tokens after full migration — target ~25K)
+  2. references/patterns-shells.md   (settings page = shell-tier)
+  3. references/patterns-forms.md    (settings = forms)
+  4. references/patterns-layout.md   (grid for the form fields)
+
+LOAD ORDER (without this protocol, pre-inversion):
+  1. SKILL.md (entire 78K tokens) — including ticket-tool, MCP install,
+     migration guide, feedback-authoring, etc., none of which apply.
+```
+
+The agent loads 3 small bundles totaling ~30K tokens on top of a ~25K
+seed, instead of 78K of mostly-irrelevant monolith. Same coverage,
+~40% smaller working set.
+
+### Migration status
+
+This section (§LoadingProtocol) is the **contract**. The migration is
+ongoing — see the bundle manifest "Status" column. v2.19.0 added the
+hygiene audit that measures the work; v2.20.0+ executes it
+section-by-section.
+
+The first proof-of-concept migration (§LocalLink + §MCP, two
+self-contained workflow sections) ships alongside this section in
+v2.20.0. Token savings measured: ~18KB / ~4.5K tokens reclaimed from
+the seed with zero functional loss (the content is identical, just
+loaded on demand).
+
+### Anti-patterns
+
+- **Loading every bundle at task start "just in case."** Defeats the
+  whole point. Load on need, not on possibility.
+- **Inlining a bundle's content into a reply when the user could
+  load it themselves.** If the user is in an agentic context, give
+  them the file_path; don't paste the whole bundle.
+- **Pre-loading bundles for ticket pipeline at the start of a
+  forward-authoring session.** The pipeline matters if the session
+  encounters substrate-fixable issues; if it doesn't, you wasted
+  the load. Wait for the trigger.
+- **Failing to update the manifest when a new bundle is added.**
+  The manifest IS the discovery surface. An invisible bundle is no
+  better than a missing one.
+
+### Cross-references
+
+- §SkillHygiene — measures the cost this protocol reduces.
+- §DiagnosticOutput — same inversion-shape, applied to consumer repos.
+- `scripts/skills/audit-skill-hygiene.mjs` — track token-economy
+  metrics before/after each migration cut.
+
+---

package/skills/adia-ui-kit/references/local-link.md

@@ -0,0 +1,198 @@
+# §LocalLink — Develop against chat-ui sources without npm round-trip
+
+> **Loading note.** This is a reference bundle extracted from `SKILL.md`
+> per the §LoadingProtocol inversion contract (v2.20.0+). Load via
+> `skill_view(name='adia-ui-kit', file_path='references/local-link.md')`
+> when you need to wire `file:` symlinks between a consumer repo and
+> the chat-ui substrate. Skip otherwise — the seed has a one-paragraph
+> stub.
+
+**Why this section exists.** When you're iterating on `@adia-ai/*`
+source AND a consumer project simultaneously, publishing to npm
+between every change is too slow. `file:` linking points the
+consumer's `node_modules/@adia-ai/*` directly at chat-ui's package
+sources via symlinks — edits land without reinstall.
+
+**This is a development workflow, not a deployment workflow.** Ship
+to production by publishing to npm and reverting consumer `package.json`
+to semver ranges. Linked installs are for dev only.
+
+### Rule 1: link ALL 9, never a subset
+
+If you link `@adia-ai/web-components` but leave `@adia-ai/llm` on a
+semver range, npm resolves `@adia-ai/llm` to its registry version —
+but the linked `web-components` source's `package.json` might depend
+on a different `llm` version. You get split-lockstep where the
+linked source and npm-resolved transitive deps disagree.
+
+`scripts/check-adia-versions.py` will flag this with the warning:
+"⚠ Mixed link + npm declarations risk split-lockstep …".
+
+### Rule 2: use absolute paths
+
+Relative paths (`file:../../gen-ui-kit/packages/web-components`) work
+but break the moment the consumer moves on disk. Use absolute paths
+for stability. On a Mac with your usual layout:
+
+```json
+"dependencies": {
+  "@adia-ai/web-components": "file:/Users/<you>/Projects/gen-ui-kit/packages/web-components",
+  "@adia-ai/web-modules":    "file:/Users/<you>/Projects/gen-ui-kit/packages/web-modules",
+  "@adia-ai/llm":            "file:/Users/<you>/Projects/gen-ui-kit/packages/llm",
+  "@adia-ai/a2ui-runtime":   "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/runtime",
+  "@adia-ai/a2ui-compose":   "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/compose",
+  "@adia-ai/a2ui-corpus":    "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/corpus",
+  "@adia-ai/a2ui-mcp":       "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/mcp",
+  "@adia-ai/a2ui-retrieval": "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/retrieval",
+  "@adia-ai/a2ui-validator": "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/validator"
+}
+```
+
+Note the path shape: 6 of 9 live at `gen-ui-kit/packages/a2ui/<name>`
+(not `gen-ui-kit/packages/<name>`). Easy mistake.
+
+### Rule 3: verify symlinks after `npm install`
+
+```bash
+ls -la node_modules/@adia-ai/
+```
+
+Every entry should have a `->` arrow indicating a symlink. If you
+see real directories, npm copied instead of linked — edits to source
+won't propagate. Fix:
+
+```bash
+rm -rf node_modules/@adia-ai
+npm install --install-links=false
+```
+
+Modern npm (v8+) defaults to symlinks for absolute `file:` paths, so
+this is rare. But if it happens, the script's
+`⚠ copied-not-linked` marker will flag it.
+
+### Rule 4: lockfile churn is normal
+
+`package-lock.json` records the resolved path of every linked dep.
+The first `npm install` after switching to `file:` links generates
+a different lockfile than the npm-resolved version. **Don't commit
+the linked lockfile to a shared branch** — it pins the absolute path
+to your local filesystem and breaks for everyone else. Either:
+
+- Commit the npm-resolved lockfile (semver ranges declared) and treat
+  the linked install as a local-dev override; OR
+- Use `npm overrides` instead of changing `dependencies` (see
+  "Alternative: overrides" below), so the linked paths live in a
+  separate overrides block that's easier to revert.
+
+### Verification with check-adia-versions.py
+
+After linking, the script reports each package as `🔗 linked`:
+
+```
+@adia-ai/web-components    0.6.8   file:/Users/kimba/Proje...   0.6.8   🔗 linked
+@adia-ai/web-modules       0.6.8   file:/Users/kimba/Proje...   0.6.8   🔗 linked
+...
+🔗 Linked: 9 package(s) declared as local dev link (all declared).
+```
+
+Exit code stays 0 because linked = informational, not a failure.
+Version-drift comparisons are skipped (a `file:` path has no
+semver — the script reads the version from the linked source's
+own `package.json` for display, but doesn't compare it to npm latest).
+
+### Alternative: npm overrides (cleaner revert)
+
+If you want to keep `"@adia-ai/x": "^0.6.8"` declared as your
+intent and only override resolution for local dev:
+
+```json
+"dependencies": {
+  "@adia-ai/web-components": "^0.6.8",
+  "@adia-ai/web-modules":    "^0.6.8"
+},
+"overrides": {
+  "@adia-ai/web-components": "file:/Users/<you>/Projects/gen-ui-kit/packages/web-components",
+  "@adia-ai/web-modules":    "file:/Users/<you>/Projects/gen-ui-kit/packages/web-modules",
+  "@adia-ai/llm":            "file:/Users/<you>/Projects/gen-ui-kit/packages/llm",
+  "@adia-ai/a2ui-runtime":   "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/runtime",
+  "@adia-ai/a2ui-compose":   "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/compose",
+  "@adia-ai/a2ui-corpus":    "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/corpus",
+  "@adia-ai/a2ui-mcp":       "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/mcp",
+  "@adia-ai/a2ui-retrieval": "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/retrieval",
+  "@adia-ai/a2ui-validator": "file:/Users/<you>/Projects/gen-ui-kit/packages/a2ui/validator"
+}
+```
+
+Reverting to npm is a one-line delete (remove the `overrides` block,
+`npm install`). The `dependencies` block stays canonical.
+
+**Detection note:** `check-adia-versions.py` reads `dependencies`,
+`devDependencies`, and `peerDependencies` only — it does NOT inspect
+`overrides`. With this pattern, the script will show:
+
+```
+@adia-ai/web-components    0.6.8   ^0.6.8   0.6.8   ✓ ok
+```
+
+`installed` will still reflect the linked source (so `0.6.8` from
+the linked package.json), `declared` shows the semver range, status
+is `✓ ok`. This is correct — overrides don't change what your
+project declares, only how it resolves. To verify the symlinks
+are in place, fall back to `ls -la node_modules/@adia-ai/`.
+
+### Why not `npm link`?
+
+`npm link` (the classic global-prefix mechanism) works but has known
+problems in multi-package scenarios:
+
+- Peer-dependency hoisting differs between `npm link` and `npm install`
+  resolution; you can get duplicate `@adia-ai/web-components` instances
+  loaded into the same browser bundle.
+- The global link state is invisible from `package.json` — future you
+  (and your CI) won't know the consumer is linked.
+- Removing the link requires `npm unlink` in BOTH the source and the
+  consumer; easy to leave dangling.
+
+`file:` and `overrides` are declarative and visible in `package.json`
+— prefer them.
+
+### Going back to npm
+
+When you're done dev-iterating and want to ship from npm again:
+
+1. Edit consumer `package.json` — replace each `file:...` with the
+   target semver range (e.g. `^0.6.8`). Or, if using `overrides`,
+   delete the `overrides` block.
+2. `rm -rf node_modules package-lock.json`
+3. `npm install`
+4. Run `scripts/check-adia-versions.py` — should report `✓ all clean`.
+
+### Switching to the `/with-css` opt-in form (since v0.6.10)
+
+If you previously used the explicit-import 2-line form for a shell:
+
+```js
+import '@adia-ai/web-modules/shell/admin-shell';
+import '@adia-ai/web-modules/shell/admin-shell.css';
+```
+
+You can collapse to the opt-in form:
+
+```js
+import '@adia-ai/web-modules/shell/admin-shell/with-css';
+```
+
+The functional output is identical (the opt-in form re-exports the JS
+and side-effect-imports the CSS internally). The migration is purely
+cosmetic — both forms tree-shake the unused shells equally, both bundle
+the same CSS. Choose based on your team's preferred style. The same
+opt-in shape exists for `chat-shell`, `editor-shell`, `simple-shell`.
+
+See §CSSPolicy "Opt-in `/with-css` variants" for the full discussion.
+
+### Cross-reference
+
+- `multi-agent-git-staging-discipline` skill — if a peer is publishing
+  to npm while you're linked, your `package-lock.json` will diverge.
+  Hard Rule 12 (`git reset HEAD` + verify) applies double here: stage
+  EXACTLY your intent, never `git add -A`.