@aceshooting/lyra-ui 26.0.0 → 27.0.0

package/skills/compose-lyra-interfaces/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: compose-lyra-interfaces
+description: Design and implement coherent interfaces with @aceshooting/lyra-ui, its companion packages, and lr-* custom elements. Use when selecting Lyra components for a page, dashboard, form, data view, retrieval flow, conversation or agent experience; composing responsive layouts and application states; or reviewing a Lyra interface for accessibility, localization, RTL, theming, framework binding, and granular imports.
+---
+
+# Compose Lyra Interfaces
+
+Turn product intent into a small, coherent Lyra component hierarchy, then implement and verify it.
+Use the sibling `lyra-ui` skill (or the installed package's `llms.txt`) for exact properties, events,
+slots, parts, custom properties, peers and import paths before writing code; its companion-package
+routes cover the experimental DOCX editor, flag assets, locale catalogs and editor data.
+
+Appearance: Shadcn look, Glass surface, Emerald accent, System mode and comfortable density are the
+built-in defaults. The [Lyra signature starter](node_modules/@aceshooting/lyra-ui/llms/shared/styles-and-tokens.md#lyra-signature-starter)
+owns the optional spotlights, gemstone selector (one localized "Selected accent: {name}" label used
+for its trigger name, hover title, dialog and radiogroup), 44px mode/design/flag-language controls
+and persistence recipe; older releases have different defaults, so read the installed
+`llms/shared/styles-and-tokens.md`. Language menus keep flags and readable localized names. Preserve
+saved preferences and branding, and retheme an existing app only within an authorized migration or
+redesign (Lyra look, Solid surface, `accent: null` selected explicitly retains the earlier look).
+
+## Workflow
+
+1. **Frame the experience.** Identify the primary user outcome, critical actions, data ownership,
+   navigation boundary, and failure modes. Ask only for choices that materially change the result.
+2. **Inventory exact contracts.** Look up every candidate tag. Prefer an existing Lyra or native
+   primitive over inventing a wrapper. Record optional peers and stable/experimental status.
+3. **Sketch structure before chrome.** Start with semantic page regions and native headings/forms.
+   Add Lyra layout, control, data, feedback, and overlay primitives only where they provide a real
+   contract. Read [references/composition-patterns.md](references/composition-patterns.md) for
+   selection and state patterns.
+4. **Model states and transitions.** Cover initial, loading, populated, empty, error, disabled or
+   read-only, and destructive/confirmation states that apply. Define event detail, focus movement,
+   cancellation, and ownership of controlled values.
+5. **Design across constraints.** Check narrow allocation and long content first, then wide layout.
+   Include RTL, translated strings, keyboard-only use, reduced motion, forced colors, and both
+   supported theme modes. Use logical CSS and Lyra tokens/utilities.
+6. **Implement with stable boundaries.** Import registration modules through stable tag-shaped
+   paths such as `@aceshooting/lyra-ui/components/lr-input.js`. Bind objects, arrays, functions, and
+   sets as properties. Listen for kebab-case CustomEvents through the framework's DOM event path.
+   Do not add runtime framework wrappers.
+7. **Verify the experience.** Exercise keyboard and focus order, names/roles/states, form submit and
+   reset, loading/empty/error recovery, 320px allocation, long translated content, RTL arrows,
+   reduced motion, forced colors, SSR/hydration where applicable, and optional-peer failure. Run
+   automated accessibility checks on populated/open states. Report human visual or assistive-
+   technology review only when it actually occurred.
+
+## Output contract
+
+Deliver:
+
+- a concise hierarchy and state model;
+- exact component/import choices with optional peers called out;
+- framework-correct property and event bindings;
+- responsive, accessibility, localization, RTL, theme, motion, and SSR decisions;
+- executable implementation or a file-specific implementation plan, as requested; and
+- verification performed plus genuine pending limitations.
+
+Keep examples on granular imports. Never copy upstream source, styles, token values, prose, or
+branding. Do not claim undocumented parity or invent a public member from memory.

package/skills/compose-lyra-interfaces/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Compose Lyra Interfaces"
+  short_description: "Design accessible interfaces with Lyra UI"
+  default_prompt: "Use $compose-lyra-interfaces to design an accessible, responsive interface from Lyra UI components."

package/skills/compose-lyra-interfaces/references/composition-patterns.md

@@ -0,0 +1,77 @@
+# Lyra composition patterns
+
+Use this reference after the product outcome is known. Confirm each named component's exact public
+contract in the `lyra-ui` skill or the package reference before emitting markup.
+
+## Select the smallest layer that owns the contract
+
+| Need | Start with | Add only when needed |
+|---|---|---|
+| Document structure | Native `main`, `nav`, `section`, headings, lists, and forms | `lr-page` or application-shell components when their named regions and responsive behavior fit |
+| Text hierarchy | Native headings, paragraphs, links, lists, and tables inside a `.lr-typography` (or `.lr-prose`) scope; `.lr-not-typography` around embedded widgets | `.lr-heading-1`…`.lr-heading-4` classes when the look must differ from the outline level |
+| Flow and wrapping | `utilities.css` stack, cluster, grid, gap, alignment, and sizing classes | A stateful layout component for resizing, collapse, rails, or managed navigation |
+| Data entry | A form-associated Lyra control with visible label and hint | Grouping, validation summary, conditional fields, or confirmation around the real form owner |
+| Data display | Native text/list for small static content | Table, data grid, tree, virtual list, chart, or viewer when their interaction contract is required |
+| Feedback | Inline text near the action | Alert, progress, skeleton, spinner, empty state, toast, or live announcement based on urgency and persistence |
+| Transient UI | Inline disclosure when space permits | Popover, dropdown, drawer, or dialog when focus/dismissal/stacking behavior is genuinely needed |
+
+Do not nest a component merely to obtain padding or a border. Use layout utilities and semantic
+containers for visual grouping; reserve interactive components for interactions they own.
+
+## Build a state matrix
+
+For every data-backed region, decide which rows apply:
+
+| State | Content | Interaction and focus |
+|---|---|---|
+| Initial | Explain the task or show the stable shell | Put focus only where the user can act |
+| Loading | Preserve useful geometry; label indeterminate work | Keep unrelated actions available; do not announce on first mount without intent |
+| Populated | Expose primary content before secondary metadata | Define selection, activation, sorting, pagination, and keyboard ownership |
+| Empty | Distinguish no data from no filtered results | Offer the next useful action and preserve the user's filter when appropriate |
+| Error | Use localized, actionable language | Place retry near the failure; return focus only after a user-triggered transition |
+| Disabled/read-only | Explain unavailable actions where necessary | Disable every subordinate action, not only the primary control |
+
+Keep remote-content and optional-peer failures separate from a valid empty result. Never render raw
+caught error messages into user-facing status UI.
+
+## Compose common experiences
+
+### Form flow
+
+Use one native `form` as the submission boundary. Give each Lyra control its public `name`, visible
+label, hint, and error path. Keep the submit action in the same form, rely on form-associated
+behavior, and verify submit, reset-to-default, fieldset-disabled, invalid, and server-error paths.
+Do not duplicate a shadow control's label with an unresolved cross-shadow `aria-labelledby`.
+
+### Data workspace
+
+Separate query/filter controls, results status, and the results surface. Preserve filters while
+loading or retrying. Use a table for comparable columns, a tree for hierarchy, a virtual list for
+large linear data, and a chart only when the visual relationship conveys more than a text summary.
+Provide an accessible label and a non-visual equivalent for meaningful graphics.
+
+### Responsive application shell
+
+Lay out semantic regions first. Let reusable content respond to its own allocation; use a shell's
+viewport behavior only for true application navigation. At narrow widths, preserve reading and tab
+order when a rail becomes a drawer or panels stack. Test at 320px with long labels, then repeat in
+RTL so logical start/end and arrow semantics remain correct.
+
+### Conversation or agent flow
+
+Keep message history, current run state, tool approvals, artifacts, and composer responsibilities
+separate. Announce user-triggered status transitions without replaying initial state. Put destructive
+or consequential tool actions behind an explicit confirmation/approval contract, and keep focus
+return deterministic when transient UI closes.
+
+## Implementation handoff checklist
+
+- Register only rendered tags through stable tag-shaped imports.
+- Import the framework's type-only declaration entry once.
+- Bind complex values as properties; do not serialize objects into attributes.
+- Use the documented CustomEvent name and exact detail type; decide whether cancellation matters.
+- Use caller data verbatim but localize library-owned labels and announcements.
+- Use logical CSS, Lyra tokens, and allocation-aware layout.
+- Record SSR mode, optional peers, remote-content boundaries, and failure behavior.
+- Test populated/open accessibility, keyboard/focus, narrow/long content, RTL, reduced motion,
+  forced colors, form semantics, reconnect, and framework type/build integration as applicable.

package/skills/lyra-ui/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: lyra-ui
+description: >
+  Use when writing or reviewing code that imports @aceshooting/lyra-ui (or its lyra-docs,
+  lyra-flags, lyra-translations and lyra-ide companions), uses any lr-* custom element, or
+  migrates a project off Web Awesome (wa-*) or Shoelace (sl-*). Covers exact component APIs
+  (attributes, slots, events, parts, CSS custom properties), design-token theming, localization,
+  framework/TypeScript integration, and wa-*/sl-* to lr-* migration.
+---
+
+# lyra-ui
+
+`@aceshooting/lyra-ui` is a free, MIT-licensed, framework-agnostic Lit 3 web-component library, an
+independent alternative to Shoelace and Web Awesome with no runtime dependency on either. Elements
+use the `lr-` prefix and ship design tokens, localization, RTL support and native form association.
+The tag count and full tag list live in `node_modules/@aceshooting/lyra-ui/llms/index.md`; never repeat a remembered count.
+
+## Look up the exact API before writing any `lr-*` markup
+
+Never infer attributes, slots, events, parts or CSS custom properties from memory or from a
+similarly named component in another library.
+
+| Need | Read |
+|---|---|
+| Find a component by need | Search `node_modules/@aceshooting/lyra-ui/llms/index.md` |
+| A known tag's full API and import | `node_modules/@aceshooting/lyra-ui/llms/components/<tag>.md` (path derived from the tag, e.g. `lr-table`) |
+| Imports, registration, events, forms, styling, localization, frameworks, AI, utilities, testing | The matching `node_modules/@aceshooting/lyra-ui/llms/shared/<topic>.md` (`imports-and-registration.md`, `events-and-types.md`, `forms-and-accessibility.md`, `styles-and-tokens.md`, `native-styles-and-utilities.md`, `localization-and-rtl.md`, `frameworks-and-ssr.md`, `ai-and-peers.md`, `testing-and-utilities.md`) |
+| Design tokens | `node_modules/@aceshooting/lyra-ui/llms/tokens.md` |
+| What to install (optional peers) | `node_modules/@aceshooting/lyra-ui/llms/peers.md` |
+| One `wa-*`/`sl-*` tag | That tag's section in `node_modules/@aceshooting/lyra-ui/llms/migration.md` |
+| Lyra v23 to v24 upgrade | `node_modules/@aceshooting/lyra-ui/llms/shared/v23-to-v24-migration.md` |
+| Any other version upgrade | `CHANGELOG.md` of the package (current major; it links older history) |
+
+Each component file carries its import path, optional peers, properties with types and defaults,
+events with payloads, slots, CSS parts, themeable properties, a usage snippet and gotchas.
+
+Without local references, use the public surfaces instead of guessing:
+
+| Need | Public fallback |
+|---|---|
+| Search by intent, synonym or typo | `GET https://www.lyra-ui.com/api/v1/components/search?q=<query>` |
+| Exact component API | `GET https://www.lyra-ui.com/api/v1/components/<lr-tag>` |
+| Shared documentation search | `GET https://www.lyra-ui.com/api/v1/documentation/search?q=<query>` |
+| Resolve a `wa-*`/`sl-*` tag | `GET https://www.lyra-ui.com/api/v1/migrations/<tag>` |
+| Structured index | `https://www.lyra-ui.com/component-api-index.json` |
+
+MCP clients can connect to `https://www.lyra-ui.com/mcp` (streamable HTTP, no authentication):
+`search_components`, `get_component`, `search_documentation`, `resolve_migration`; resources
+`lyra://catalog`, `lyra://component/{tag}`, `lyra://guide/{topic}`.
+
+## Non-negotiable conventions
+
+- **Register through stable tag-shaped paths**, one per rendered tag:
+  `import '@aceshooting/lyra-ui/components/lr-combobox.js';`. `import '@aceshooting/lyra-ui'` is
+  registration-free. `all.js` is a compatibility set (prefer per-component entries in applications)
+  and omits the 15 optional-peer tags (charts, `lr-map`, `lr-graph`, `lr-knowledge-graph-explorer`,
+  `lr-geojson-viewer`), which always need their own import. Class-only `.class.js` entries keep
+  their family path; `node_modules/@aceshooting/lyra-ui/llms/index.md` lists every exact path.
+- **Use the style API and `--lr-theme-*` inputs**, never ad-hoc values: look, surface, density, mode
+  and accent compose through the style API or scope attributes
+  (`node_modules/@aceshooting/lyra-ui/llms/shared/styles-and-tokens.md`, exact tokens in `node_modules/@aceshooting/lyra-ui/llms/tokens.md`).
+  `@aceshooting/lyra-ui/theme.css` supplies the document-level default profile.
+- **Events are `lr-*`-prefixed, bubbling, composed `CustomEvent`s** with payload on `event.detail`,
+  non-cancelable unless the component says otherwise. Native wrappers also relay only the native
+  events their section lists; do not assume an unlisted native event works.
+- **Complex values need property bindings**, not attributes (an object attribute becomes
+  `[object Object]`): Lit `.rows=${rows}`, Vue `:rows.prop`, Angular `[rows]`, React 19+ natively,
+  older React via a ref.
+- **Form controls are form-associated** (native submit and validation, no wiring). Read
+  `effectiveDisabled`, not `disabled`, for the state merged with an ancestor `<fieldset disabled>`.
+- **Every built-in string is localizable** through a per-instance `.strings` override or an app-wide
+  catalog via `registerLyraLocale()`; never overwrite slotted content to translate. Locale does not
+  set writing direction: inherit an explicit `dir="rtl"`.
+
+## Appearance defaults
+
+The built-in profile is Shadcn look, Glass surface, Emerald accent, System mode, comfortable
+density. Preserve saved style/locale choices and explicit project branding; restyle an existing app
+only inside an authorized migration or redesign. To keep the pre-default look select
+`look: 'lyra'`, `surface: 'solid'`, `accent: null` explicitly (`accent: null` clears;
+`resetLyraStyle()` restores Emerald). For optional spotlights, gemstones and the 44px
+gemstone/mode/design/flag-language controls follow the
+[Lyra signature starter](node_modules/@aceshooting/lyra-ui/llms/shared/styles-and-tokens.md#lyra-signature-starter), which owns
+the exact recipe, labels and persistence; read it before changing startup or persistence.
+
+## Companion packages
+
+Install each at the same version as `@aceshooting/lyra-ui`.
+
+- **`@aceshooting/lyra-translations`** (optional peer): the 66 locale catalogs. Import
+  `@aceshooting/lyra-translations/<locale>.js` (or `<locale>/<family>.js` slices); it is also what
+  `loadLyraLocale()` from `@aceshooting/lyra-ui/locale-loader.js` imports. Only the pseudo-locales
+  stay under `@aceshooting/lyra-ui/translations/pseudo/`. The old
+  `@aceshooting/lyra-ui/translations/<locale>.js` path no longer exists.
+- **`@aceshooting/lyra-ide`** (dev dependency): `custom-elements.json`, `web-types.json`,
+  `vscode-html-data.json`, `vscode-css-data.json`. Point editor settings and manifest imports there;
+  `@aceshooting/lyra-ui` no longer exports `custom-elements.json`.
+- **`@aceshooting/lyra-flags`** (optional peer): assets for `<lr-flag>`. Read
+  `node_modules/@aceshooting/lyra-ui/llms/components/lr-flag.md`; for direct asset loading read the installed package README.
+- **`@aceshooting/lyra-docs`**: experimental `<lr-docx-editor>`; read its installed README for the
+  optional peer, registration, stylesheet imports, save receipts and limits. Core document viewers
+  stay in `node_modules/@aceshooting/lyra-ui/llms/components/`.
+
+Tests under Happy DOM: call `installHappyDomShims()` from `@aceshooting/lyra-ui/testing` in the
+setup file instead of local patches (details in `node_modules/@aceshooting/lyra-ui/llms/shared/testing-and-utilities.md`).
+
+## Upgrading to 27
+
+Check these first when a project moves to 27.0.0 (the `CHANGELOG.md` has the complete notes):
+
+- `ToolCallStatus` and `ToolResultStatus` became the single `ToolStatus` union.
+- `heading-level` defaults to `none` on `lr-task-list`, `lr-prompt-studio` and `lr-result-card`;
+  set `heading-level` explicitly to keep a semantic heading.
+- Locale catalogs and editor data moved to the two companion packages above.
+- `lr-copy-button` `feedbackDuration` defaults to 1500 ms.
+
+## Migrating from Web Awesome or Shoelace
+
+`node_modules/@aceshooting/lyra-ui/llms/migration.md` holds the `wa-*`/`sl-*` mappings, import rewrites and warnings. Resolve
+each occurrence against the source ecosystem and installed version that supplied it; apply verified
+automatic mappings, review warnings and semantic differences in context. A mapped tag is not a
+guaranteed lossless rename, and a tag absent from the tables has no documented counterpart. Some
+deprecated Lyra spellings stay supported (`removalNotBefore` is a floor, not a removal date), such
+as `clearable`/`with-clear` on the combobox and `lr-icon`'s `autoWidth` (a CSS-level alias of
+`canvas="auto"`; an explicit `canvas` wins); do not blanket-rewrite them.
+
+## Workflows
+
+Slash commands in the plugin; in an `init-agents` install read the matching file in this skill's
+`commands/` directory:
+
+- `/lyra-ui:migrate` (`commands/migrate.md`): verified `wa-*`/`sl-*` rewrites plus a manual list.
+- `/lyra-ui:review` (`commands/review.md`): whole-project audit, local fixes, upstream requests, ledger.
+- `/lyra-ui:frontend` (`commands/frontend.md`): read-only review of how a project uses lyra-ui.
+- `/lyra-ui:new-component` (`commands/new-component.md`): usage snippet from the real API.
+- `/lyra-ui:update` (`commands/update.md`): bump the dependency and report the changelog.
+
+For page and interface design use the sibling `compose-lyra-interfaces` skill.
+
+## Report gaps and bugs on a user's behalf
+
+For a missing component, capability, bug or improvement idea, read [reporting.md](reporting.md)
+(naming-mismatch check, payload, classification). **Always get the user's explicit agreement before
+filing**, never as a side effect of noticing something, and never include source, file paths or
+product/client names.

package/skills/lyra-ui/commands/frontend.md

@@ -0,0 +1,37 @@
+---
+description: Review a consumer project's lyra-ui usage for correctness, tokens and native-element adoption, a11y/i18n/RTL, and performance
+argument-hint: [path]
+allowed-tools: Read, Grep, Glob, Bash(grep:*)
+---
+
+Review the frontend at `$1` (default: the current working directory) for how it uses
+`@aceshooting/lyra-ui`. Read-only: report findings and let the user ask for fixes afterwards.
+
+Every claim is checked against `node_modules/@aceshooting/lyra-ui/llms/components/<lr-tag>.md`
+(path derived from the tag), never against memory. Check, in order:
+
+1. **API correctness.** For every `lr-*` tag, compare the attributes, slots and listened events with
+   its reference. Flag nonexistent attributes (typo or stale API), missing required attributes or
+   slots, and listeners for events the component never fires.
+2. **Accessibility.** Components own their internal ARIA: flag consumer `role`/`aria-*` that
+   duplicates or conflicts with the documented behavior, and `lr-*` form controls with no `label`
+   attribute or `<label>`.
+3. **i18n/RTL.** Flag hardcoded user-facing English passed into slots or attributes of components
+   that support `.strings`/`registerLyraLocale()`, and physical CSS (`left`/`right`,
+   `margin-left`, `text-align: left`) in rules touching `lr-*`.
+4. **Performance.** Flag side-effect imports never used in the importing file, one component
+   imported through several specifiers, and root-barrel or `all.js` imports where per-component
+   registration is documented.
+5. **General bugs.** Properties written that the reference documents as read-only, `disabled` read
+   where `effectiveDisabled` is documented, native `click`/`input` listened for where the reference
+   says to use the `lr-*` event, complex values passed as attributes instead of properties.
+6. **Tokens and native elements.** In files that import lyra-ui, grep style blocks and `style=` for
+   hex colors, `rgb(`/`rgba(`/`hsl(` and hardcoded `px` spacing. Suggest a replacement only when
+   `node_modules/@aceshooting/lyra-ui/llms/tokens.md` has a genuinely matching token
+   (documented default in the same color or size family); a brand color may be intentional, so flag
+   rather than assume. Also flag native `<button>`, `<input>`, `<select>`, `<dialog>`, `<textarea>`
+   in files that already import an `lr-*` component, as candidates for the matching Lyra component
+   (check both `lr-select` and `lr-combobox`).
+
+Report grouped by category, each finding with `file:line` and a one-line fix grounded in what the
+reference documents.

package/skills/lyra-ui/commands/migrate.md

@@ -0,0 +1,44 @@
+---
+description: Rename Web Awesome (wa-*) and/or Shoelace (sl-*) usage in a consumer project to lyra-ui (lr-*) equivalents using verified per-source mappings and required warnings
+argument-hint: [path]
+allowed-tools: Read, Edit, Grep, Glob, Bash(grep:*), Bash(git:*), Bash(npx:*)
+---
+
+Migrate the project at `$1` (default: the current working directory) off Web Awesome (`<wa-*>`,
+`@awesome.me/webawesome`) and/or Shoelace (`<sl-*>`, `@shoelace-style/shoelace`) onto
+`@aceshooting/lyra-ui`'s `lr-*` equivalents.
+
+Migration is best-effort for both ecosystems. Resolve each occurrence against the source prefix and
+the installed package version that supplied it (installing both libraries does not change an
+occurrence's source), then use its classification and warnings in
+`node_modules/@aceshooting/lyra-ui/llms/migration.md`. A classified mapping is not a promise
+of an automatic or lossless rename; manual and warning-required cases (included remote markup,
+Shoelace alert listener timing) stay manual.
+
+1. **Inventory.** Grep for `<wa-`/`<sl-` tags and the `@awesome.me/webawesome` /
+   `@shoelace-style/shoelace` imports (check `package.json` for the exact specifier). List every
+   distinct tag by source library with `file:line` and the installed source version. If neither
+   library is present, say so and stop.
+2. **Mechanical pass (optional).** `npx lyra-ui-migrate --diff <path>` (or `npx lyra-ui migrate-wa`)
+   applies only exact and fully rewritten inventory mappings and reports the rest with
+   source-located warnings; `--check` exits nonzero while rewrites or warnings remain. Review its
+   diff against steps 3 and 4 rather than trusting it blindly.
+3. **Look up each tag** in its own source's row of `migration.md` (a tag absent from the tables has
+   no documented counterpart), then read the target's
+   `node_modules/@aceshooting/lyra-ui/llms/components/<lr-tag>.md`. Check every used
+   attribute, slot, event, method, part and CSS custom property against both; never infer parity
+   from similar tag names or drop unmatched members. Lyra combobox accepts both `clearable` and
+   `with-clear`; neither alone needs a rename.
+4. **Classify and act.**
+   - *Automatic or rewritten:* rename the tag at every call site, switch the import to
+     `@aceshooting/lyra-ui/components/<lr-tag>.js` (the **Import** line of the component
+     reference), and carry over attribute, slot and event differences the reference documents.
+   - *Manual or warning-required:* keep the original occurrence and report its mapping and warnings;
+     never promote it to an automatic rewrite.
+   - *Unresolved:* leave the tag and list it; no partial migration without a verified mapping.
+5. **Re-grep** for `<wa-`, `<sl-` and both import specifiers: only reported manual and unresolved
+   usages may remain.
+6. **Report** by source library then component: tags migrated, files touched, and what changed
+   besides the tag name; then everything still `wa-*`/`sl-*` and why. For leftover `wa-*` suggest
+   `/lyra-ui:update` (a newer release may close the gap) or filing it upstream; recommend reviewing
+   used contracts and warnings for every migrated or remaining occurrence in either ecosystem.

package/skills/lyra-ui/commands/new-component.md

@@ -0,0 +1,19 @@
+---
+description: Emit a correct @aceshooting/lyra-ui usage snippet for one component, from the real installed API
+argument-hint: <component-name>
+allowed-tools: Read, Grep, Bash(grep:*)
+---
+
+Produce a working usage snippet for the lyra-ui component `$1` (bare name such as `button` or full
+tag such as `lr-button`; normalize to the bare name).
+
+1. If `$1` is empty, ask which component and stop; do not guess.
+2. Read `node_modules/@aceshooting/lyra-ui/llms/components/lr-$1.md` (derived from the tag,
+   no search needed). If it does not exist the component does not exist: say so and suggest the
+   closest names from `node_modules/@aceshooting/lyra-ui/llms/index.md`; never invent an API.
+3. Extract the import path, the required and most common attributes, the default and named slots,
+   and the primary events.
+4. Emit the **Import** line verbatim (`import '@aceshooting/lyra-ui/components/<lr-tag>.js';`), a
+   minimal realistic HTML example using only documented attributes and slots, and, when a consumer
+   would typically handle one, a one-line `addEventListener` for the primary event.
+5. If the reference notes a Web Awesome or Shoelace counterpart, mention it in one line.