@imfusion/web-ui 0.6.1-dev.6.g4adc5c3e → 0.6.1

package/src/llms/install-templates/AGENTS.md

@@ -1,34 +1,31 @@
-# AGENTS.md
+# Agent instructions
 
-<Keep this file lean — target ~50 lines. Decision test for every line: would the agent make a costly mistake without it? If
-it would just need to read a file first, cut it. Dev commands, path aliases, and tool config are discoverable from the files
-themselves.>
+<Keep this file short. Include only rules that prevent a costly mistake. Point to the repository's own docs for everything
+else.>
 
-<One paragraph: what the app is and the stack in one line.>
+<One paragraph describing the app, its package, and its stack.>
 
-Scripts, deps, and setup: [`README.md`](./README.md) and [`package.json`](./package.json) are the source of truth. Check the
-`package.json` scripts before running or suggesting a command — don't infer one exists by pattern-matching a sibling.
+Setup and commands: [`README.md`](./README.md) and [`package.json`](./package.json). Read the package scripts before running
+or suggesting a command.
 
-## Read before you write
+## Read before writing
 
-<One bullet per doc in docs/, each with when to read it, e.g.:>
+<Add one pointer for each repository-specific document.>
 
-- [`docs/<topic>.md`](./docs/<topic>.md) — <what it covers>. Read before <the change it governs>.
+- [`docs/<topic>.md`](./docs/<topic>.md) — <what it covers and when to read it>.
 
-[`docs/index.md`](./docs/index.md) registers all of them.
+[`docs/index.md`](./docs/index.md) lists the documents.
 
 ## Working here
 
-<The fenced block below is the only part of this file `npx web-ui-install` touches: its content comes from this template and
-is refreshed on every skills install. Everything else in the file is scaffolded once by the setup skill and then owned by the
-repo.>
+<The installer owns only the fenced block below. It refreshes that block on every install; the rest belongs to the project.>
 
 <!-- imf-web-ui:begin — managed by `npx web-ui-install`; edits inside the fence are overwritten -->
 
-`.agents/skills/imf-web-ui-*` is vendored from `@imfusion/web-ui` and resynced with `npx web-ui-install`. Don't edit it and
-don't put repo conventions there. Load the matching `imf-web-ui-*` skill before writing code, styles, data fetching, or docs;
-repo docs hold only what is unique to this repo.
+`.agents/skills/imf-web-ui-*` is vendored from `@imfusion/web-ui` and resynced with `npx web-ui-install`. Do not edit the
+vendored copy or put project-specific conventions there. Load the matching skill before changing UI, styles, data, tests, or
+docs.
 
 <!-- imf-web-ui:end -->
 
-<Repo-specific agent guidance: generated files that are committed, tools to verify APIs against, things never to touch.>
+<Add project-specific rules here: generated files, API lookup tools, and paths the agent must not touch.>

package/src/llms/llms.gen.txt

@@ -11,183 +11,189 @@ props, which always live in the docgen file above.
 
 ## AppShell
 - category: Layout, status: stable
-Application layout shell — a fixed header, collapsible navbar/aside sidebars, an optional footer, and a scrolling main area. The classic dashboard frame; also called an app layout, application frame, dashboard shell, or sidebar layout. Sizing is CSS-driven and sidebars collapse to sliding overlays on small screens.
+Application layout shell for a header, sidebars, footer, and scrolling main area. Also called an app layout or dashboard shell; sizing is CSS-driven and sidebars can become sliding panels on small screens.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .app-shell (jq: jq '.app-shell' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Button
 - category: Buttons, status: stable
-Triggers an action — submit, confirm, cancel, navigate, or destructive operations. Six semantic variants (primary, secondary, positive, negative, outline, ghost) communicate intent across four sizes (sm, md, lg, hero). The brand's chamfered shape; hover inverts fill and label. An optional endIcon slot aligns the label left and pins the icon right. Also called a CTA or action.
+Triggers an action such as submit, confirm, cancel, navigate, or delete. Also called a CTA or action button; variants and sizes communicate its importance.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .button (jq: jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/button.md
 
 ## Callout
 - category: Display, status: stable
-Inline status banner — a persistent, non-interactive message that sits in the content flow to convey info, success, warning, or error state. Composed from slots: Callout.Root wraps a Callout.Icon (status glyph), an optional Callout.Title, and a Callout.Description. Tonal `variant` (info/positive/warning/negative) tints the surface and colours the icon and text. Also called an alert, callout, or inline notice. Not a Toast (transient) or Alert Dialog (modal).
+Persistent, in-place status message for information, success, warnings, and errors. Also called an inline alert or notice; it is not a transient toast or modal dialog.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .callout (jq: jq '.callout' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Card
 - category: Layout, status: stable
-Surface container — groups related content on a tonal background. Composed from slots: Card.Root wraps an optional edge-to-edge Card.Image plus padded Card.Header, Card.Content, and Card.Footer. Tonal or coloured `variant`, opt-in shadow and radius, and a `density` scale. Also called a panel, tile, or paper.
+Surface container for related content on a tonal background. Also called a panel or tile; compose it from optional image, header, content, and footer parts.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .card (jq: jq '.card' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Checkbox
 - category: Inputs, status: stable
-Binary form control for opt-in choices — accept terms, select table rows, pick list items. Supports an indeterminate state for parent/child selection. Also called a check box or tick box; for immediate on/off preferences, prefer Switch.
+Binary form control for submitted choices such as terms, table rows, or list items. Also called a check box; it supports an indeterminate parent state.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .checkbox (jq: jq '.checkbox' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/checkbox.md
 
 ## Chip
 - category: Display, status: stable
-Compact inline label for tags, status, categories, counts, or metadata. Also known as a badge, tag, or pill. Two dimensions — a color variant for semantic role and a shape variant for visual appearance, including an inline form that sits naturally in flowing body text.
+Compact label for tags, status, categories, counts, and metadata. Also called a badge or tag; its color and appearance are independent choices.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .chip (jq: jq '.chip' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## ChipLink
 - category: Buttons, status: stable
-Inline link styled as a chip — a small labeled anchor that auto-appends a directional icon. Use for external doc references and source attribution (opens in a new tab) or in-app navigation badges (stays in the current tab). Also called a link chip or link badge.
+Link styled as a compact chip, with a directional icon for external references or in-app navigation. Also called a link chip or link badge.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .chip-link (jq: jq '.chip-link' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Code
 - category: Display, status: stable
-Displays source code — Code.Inline for a fragment in running text, Code.Block for a fenced block with an optional language label and copy button. Also called a code snippet or code block.
+Displays source code inline or in a block, with optional language labels and copying. Also called a code snippet or code block.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .code (jq: jq '.code' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## CodeHighlight
 - category: Display, status: experimental
-Syntax-highlighted drop-in for the Code parts — the same Code.Block and Code.Inline, with TanStack Highlight token coloring that follows the color scheme. Imported from @imfusion/web-ui/integrations/code-highlight; requires the @tanstack/highlight peer.
+Syntax-highlighted Code parts powered by TanStack Highlight. Import from the integration entry and install the optional @tanstack/highlight peer.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .code-highlight (jq: jq '.code-highlight' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Collapsible
 - category: Display, status: stable
-Toggleable show/hide region for progressive disclosure — FAQ entries, expandable settings, detail toggles. A trigger button drives an animated open/close panel; multiple stacked form an accordion. Also called a disclosure or expand/collapse.
+Show-and-hide region for secondary content such as FAQs, settings, or details. Also called a disclosure or expand/collapse.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .collapsible (jq: jq '.collapsible' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/collapsible.md
 
 ## CopyButton
 - category: Buttons, status: stable
-Button that copies a value to the clipboard and shows a transient confirmation. Also called a copy-to-clipboard button. Composes Button; commonly paired with Code.Block.
+Copies a value to the clipboard and briefly shows confirmation. Also called a copy-to-clipboard button; commonly used with Code.Block.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .copy-button (jq: jq '.copy-button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Drawer
 - category: Layout, status: stable
-Off-canvas panel that slides in from a screen edge. Use for mobile navigation, secondary nav, settings trays, filter sidebars, or any side sheet. Also called a sidebar, side panel, off-canvas, or sheet.
+Off-canvas panel that slides in from a screen edge for navigation, settings, filters, or focused tasks. Also called a sidebar, side panel, or sheet.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .drawer (jq: jq '.drawer' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/drawer.md
 
 ## Field
 - category: Inputs, status: stable
-Accessible field composition for a label, form control, supporting description, and inline validation message. Use it to associate a control such as Input, Checkbox, or Select with field state including valid, invalid, dirty, touched, filled, and focused.
+Accessible field composition for a label, control, supporting text, and validation message. Use it with Input, Checkbox, Select, and other form controls.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .field (jq: jq '.field' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/field.md
 
 ## Fieldset
 - category: Inputs, status: stable
-Semantic grouping for related form controls with a shared legend. Also called a form group; use it to communicate a common topic and propagate disabled state without introducing a decorative container.
+Semantic group for related form controls with a shared legend. Also called a form group; it can propagate a disabled state to the group.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .fieldset (jq: jq '.fieldset' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/fieldset.md
 
 ## Icon
 - category: Display, status: stable
-Semantic color wrapper for an icon imported from the Web UI icons entry. Use it when an icon needs a named foreground role instead of the inherited currentColor.
+Renders a Web UI icon with an optional semantic foreground color. The default inherits the surrounding currentColor.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .icon (jq: jq '.icon' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## ImageDisplayOptions
 - category: Inputs, status: experimental
-A panel or toolbar of controls bound to an image dataset's display options.
+Panel and toolbar controls for an image dataset's display options, including window, level, gamma, and invert settings.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .image-display-options (jq: jq '.image-display-options' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://docs.imfusion.com/
 
 ## Input
 - category: Inputs, status: stable
-Single-line text input for form data entry. Also called a text field or input field. Supports controlled and uncontrolled modes, and integrates with Base UI's Field context for validation state (valid, invalid, dirty, touched, filled, focused).
+Single-line text input for form data entry. Also called a text field; it supports controlled values and Field validation state.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .input (jq: jq '.input' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/input.md
 
 ## Logo
 - category: Display, status: stable
-Brand mark display primitive — renders a logo from a URL or inline React element with consistent sizing. Also called a wordmark, brand icon, or logotype.
+Renders a logo from a URL or inline React element with consistent sizing. Also called a wordmark or brand mark.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .logo (jq: jq '.logo' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## NavigationMenu
 - category: Display, status: experimental
-Navigation menu — a horizontal (or vertical) strip of triggers that open flat, anchored flyout panels for site or app wayfinding, with multi-column mega-menu content and a viewport-responsive inline master/detail submenu. Composed from slots: NavigationMenu.Root, List, Item, Trigger, Icon, Content, Link, FlyoutLink, LinkList, LinkCard, InlineSubmenu, Portal, Positioner, Popup, Viewport, Arrow, Backdrop. Also called a nav bar, menu bar, or mega menu.
+Navigation menu with horizontal or vertical triggers and anchored flyout panels. Also called a menu bar or mega menu; it supports links, rich cards, and nested navigation.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .navigation-menu (jq: jq '.navigation-menu' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/navigation-menu.md
 
 ## Popover
 - category: Display, status: stable
-Floating panel anchored to a trigger element. Use for contextual menus, tooltips-with-actions, rich hover cards, quick-edit forms, or any non-modal detail overlay. Also called a popup, flyout, or floating menu.
+Floating panel anchored to a trigger for contextual content, quick forms, or actions. Also called a popup or flyout; use Tooltip for hints without interaction.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .popover (jq: jq '.popover' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/popover.md
 
 ## Row
 - category: Layout, status: stable
-Horizontal layout primitive — children are arranged left-to-right with configurable spacing, alignment, and optional wrapping. Also called hstack, horizontal stack, flex row.
+Horizontal layout primitive for spacing, aligning, and wrapping children. Also called a horizontal stack or flex row.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .row (jq: jq '.row' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Select
 - category: Inputs, status: stable
-Single-choice dropdown — pick one value from a known list. Keyboard-accessible listbox with a labelled trigger and a portalled popup. Best for short, fixed option sets (status, role, country). Also called a dropdown or picker.
+Dropdown for choosing a value from a known list. Also called a picker; use it for a labeled, keyboard-accessible option list.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .select (jq: jq '.select' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/select.md
 
 ## Separator
 - category: Layout, status: stable
-Thin line that visually divides content into groups — section break, list item rule, sidebar division. Also called a divider, hr, or horizontal / vertical rule.
+Line that divides content horizontally or vertically. Also called a divider or rule.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .separator (jq: jq '.separator' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/separator.md
 
 ## Slider
 - category: Inputs, status: stable
-Drag a thumb along a track to pick a numeric value or range. Use for continuous or stepped numeric input where magnitude matters — volume, brightness, opacity, price ranges. Also called a range input.
+Numeric input for choosing one value or a range by dragging a thumb. Also called a range input; use it when relative magnitude matters.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .slider (jq: jq '.slider' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/slider.md
 
 ## Spinner
 - category: Display, status: stable
-Loading indicator built from the animated ImFusion glyph. Also called a loader, progress spinner, or activity indicator; signals indeterminate loading.
+Indeterminate loading indicator. Also called a loader or progress spinner.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .spinner (jq: jq '.spinner' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Stack
 - category: Layout, status: stable
-Vertical layout primitive — children stack top-to-bottom with configurable spacing and alignment. Use it instead of writing flex column layouts by hand. Also called a vstack or column.
+Vertical layout primitive for spacing and aligning children. Also called a vertical stack or column.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .stack (jq: jq '.stack' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Switch
 - category: Inputs, status: stable
-Two-state toggle for immediate on/off preferences — enable a feature, mute audio, toggle dark mode. Takes effect right away (no submit step); for form-submission booleans, a checkbox is more conventional. Also called a toggle.
+Two-state control for an on/off setting that takes effect immediately. Also called a toggle; use Checkbox for a submitted choice.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .switch (jq: jq '.switch' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/switch.md
 
 ## Table
 - category: Display, status: stable
-Styled, static building blocks for tabular data — Root, Header, Body, Row, HeaderCell, Cell, HeaderButton, SortableHeaderCell. Also called a data grid anatomy. Purely presentational with no data logic; for a full data grid, drive these parts with a headless table library (TanStack Table recommended) that you install yourself.
+Presentational table parts for static tabular data. Pair them with a headless table library for sorting, pagination, or selection.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .table (jq: jq '.table' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## Tabs
 - category: Display, status: stable
-Tabbed navigation — switches between panels of content within one view via a horizontal (or vertical) strip of labels with a sliding active-state underline. Composed from slots: Tabs.Root, Tabs.List, Tabs.Tab, Tabs.Indicator, Tabs.Panel. Also called a tab strip or tab bar.
+Switches between related panels within one view. Also called a tab strip or tab bar; it supports horizontal and vertical layouts.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .tabs (jq: jq '.tabs' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/tabs.md
 
+## Toast
+- category: Display, status: experimental
+Transient message stack that reports the outcome of a background action without interrupting the page. Use for save confirmations, undo offers, and async progress; attach one to an element for contextual feedback like a copy confirmation. Also called a snackbar, notification, or flash message; for a message that stays inline in the page use Callout instead.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .toast (jq: jq '.toast' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/toast.md
+
 ## Toggle
 - category: Inputs, status: experimental
-A two-state button that can be on or off. Compose several inside a ToggleGroup for a segmented control.
+Two-state button for a pressed or unpressed option. Compose several in ToggleGroup for a segmented control.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .toggle (jq: jq '.toggle' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/toggle.md
 
 ## ToggleGroup
 - category: Inputs, status: experimental
-A set of connected Toggle buttons sharing one value: single-select by default (a segmented control), or multi-select with `multiple`. Compose one Toggle per segment, each with a value. Also called a segmented control or segmented button.
+Group of connected Toggle buttons that share a selection. Also called a segmented control; set `multiple` for more than one active option.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .toggle-group (jq: jq '.toggle-group' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/toggle-group.md
 
 ## Tooltip
 - category: Display, status: stable
-Hover- or focus-triggered floating label giving terse contextual help for a control or term. Use for icon-button descriptions, truncated-text reveals, and field hints. Also called a hint, hovercard, or info bubble; for click-triggered panels with actions use Popover instead.
+Hover- or focus-triggered label for brief help about a control or term. Also called a hint; use Popover for a panel with actions.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .tooltip (jq: jq '.tooltip' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/tooltip.md
 
 ## Typo
 - category: Display, status: stable
-Typographic primitives — a family of heading (H1–H4), paragraph (P, Lead), and inline accent (InlineCode, Highlight, Link) components. Most support a color role — main, support, or minor — plus the standard HTML attributes for its element; InlineCode is a fixed neutral chip (it renders Code.Inline).
+Semantic text primitives for headings, paragraphs, lists, quotes, links, and inline code. The namespace uses native HTML elements and token-based text roles.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .typo (jq: jq '.typo' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)

package/src/llms/skills/imf-web-ui/SKILL.md

@@ -1,56 +1,47 @@
 ---
 name: imf-web-ui
 description:
-  "Entry point for UI work in a project that depends on @imfusion/web-ui. Decides whether guidance is needed at all, then
-  routes to the right companion skill — component reference, UX guidance, or frontend conventions. Load when adding or
-  editing UI in a consumer repo."
+  "Route UI work in a project that uses @imfusion/web-ui. Use this skill whenever a user adds, edits, styles, or reviews UI
+  in a consumer project, even if they do not mention the library. Decide whether guidance is needed, then open only the
+  companion skills that match the task."
 ---
 
-# imf-web-ui
+# Route Web UI work
 
-`@imfusion/web-ui` ships a small family of skills. This one is the map — it costs almost nothing to load and tells you which
-companion to open, or that you need none at all. Don't load a companion speculatively: route first, zoom second.
+Start here for UI work in a project that uses `@imfusion/web-ui`. This skill is a map, not a second copy of every convention.
 
-## Row zero — is help needed at all?
+## 1. Decide whether guidance is needed
 
-Before routing, check whether this task needs guidance in the first place. It does **not** when:
+Skip a companion when the task is explicit and small, an existing local pattern already solves it, and the library usage is
+already correct. Do the work. Look up an API silently only when you are unsure.
 
-- The request is explicit and small ("make the button say Save", "add a column for email"), or
-- You're repeating a pattern that already exists nearby in the codebase — copy it, and
-- The components involved are already imported and used correctly.
+Use a companion when the task involves a choice, a missing setup piece, a new file, or a library convention the project may
+not already have.
 
-In that case: just do the work. At most, do a silent props lookup via `imf-web-ui-components` if you're unsure of an API.
-Guidance skills exist to fill gaps, not to add ceremony to clear tasks.
+## 2. Route the task
 
-## Routing
+| Task                                                              | Open                                                   |
+| ----------------------------------------------------------------- | ------------------------------------------------------ |
+| Look up a component, part, prop, default, or icon                 | `imf-web-ui-components`                                |
+| Choose components or shape a screen or flow                       | `imf-web-ui-ux`                                        |
+| Write or update documentation                                     | `/documentation-writer`, then `imf-web-ui-conventions` |
+| Write a wrapper, custom UI, CSS, data layer, validation, or tests | `imf-web-ui-conventions`                               |
+| Install the library or bootstrap project tooling                  | `imf-web-ui-setup`                                     |
+| Inspect an existing project without changing it                   | `imf-web-ui-audit`                                     |
+| Update the package, skills, or hooks                              | `imf-web-ui-update`                                    |
 
-| The task at hand                                                                                      | Open                                    |
-| ----------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| Using a specific component; checking props, sub-components, or defaults                               | `imf-web-ui-components`                 |
-| First-time setup, adding a library dependency, or components rendering unstyled/broken                | `imf-web-ui-setup` (`library-setup`)    |
-| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states  | `imf-web-ui-ux`                         |
-| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing     | `imf-web-ui-conventions`                |
-| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-setup` / `imf-web-ui-audit` |
-| Installing or checking agent tooling: vendored skills, lifecycle hooks, registrations, and staleness  | `imf-web-ui-setup` / `imf-web-ui-audit` |
+A screen often needs both `imf-web-ui-ux` and `imf-web-ui-components`, in that order. Setup and audit are for project-wide
+questions, not every one-file edit.
 
-The two setup rows are narrow on purpose. They're for "what is this project missing?" — a question about the repo as a whole.
-Being asked to add one config file is just that edit; make it, and don't open a skill to do so.
+## 3. Keep project choices
 
-Tasks routinely span two: building a screen usually means `imf-web-ui-ux` for the shape and `imf-web-ui-components` for the
-APIs. That's normal — open both, in that order.
+The host project's existing conventions win. The companion skills fill gaps; they do not justify refactoring a working
+styling system, state library, or folder structure.
 
-## The stack
+When a task needs TanStack Router, Query, Form, Table, or Store and the project has no incumbent, propose the matching
+library and read its current documentation with `npx @tanstack/cli` before using it.
 
-TanStack is the recommended tooling library — routing, server state, forms, tables. When a task needs one of those and the
-project has no incumbent, propose it, and read the library's own docs (`npx @tanstack/cli`) rather than working from memory.
+## 4. Ask only when the choice depends on missing context
 
-## When to interview the human
-
-`imf-web-ui-ux` contains a short per-feature interview. Run it **only** when both hold:
-
-1. The request is foggy — you couldn't say what the primary action of the screen is, who uses it, or what data it shows.
-2. A human is available to answer.
-
-Never interview when a spec, mockup, or clear instruction exists — asking questions the conversation already answered is
-worse than not asking at all. When in doubt and no human is around, make the conservative choice, and say which assumptions
-you made.
+For a vague screen or flow, use the short interview in `imf-web-ui-ux`. Do not ask questions the prompt, a spec, or the
+repository already answers.

package/src/llms/skills/imf-web-ui-audit/SKILL.md

@@ -1,119 +1,67 @@
 ---
 name: imf-web-ui-audit
 description:
-  "Read-only health check for an ImFusion frontend against the conventions baseline. Audit the full project or any topic,
-  including library-setup, tooling, git, npm-project, authentication, project-structure, docs-structure, data, testing,
-  React, TypeScript, class names, validation, components, styling, assets, library-boundary, and tokens. Reports broken
-  pieces, missing pieces, working deviations, present evidence, and unverified state, then turns them into an actionable
-  plan."
+  "Audit an existing ImFusion frontend against the @imfusion/web-ui conventions without changing files. Use this for a
+  project health check, a pre-setup review, or one named topic. Report broken and missing pieces, working deviations,
+  evidence, and an ordered plan."
 argument-hint: "[full|<topic>]"
 allowed-tools: Read Glob Grep
 ---
 
-# imf-web-ui-audit
+# Audit a consumer project
 
-You are the frontend health-check auditor, and you run as an orchestrator: one investigator per topic gathers the evidence,
-you merge their findings and turn them into an actionable plan. Follow the applicable `imf-web-ui-conventions` topics, cite
-repository evidence, distinguish defects from working deviations, and never present the baseline as universal best practice.
-
-An audit belongs in plan mode: it ends in work to approve, not in files to write.
+This is a read-only audit. Compare the project with the selected `imf-web-ui-conventions` topics, report evidence, and end
+with work the human can approve. The baseline is an ImFusion default, not a universal law; a deliberate project choice is a
+deviation, not a defect.
 
 ## Workflow
 
-1. Resolve the argument. Bare means `full`; a topic selects one row below. If no topic matches, list every available topic
-   instead of guessing or widening the scope.
-2. Enter the host's plan mode, unless one of the exceptions after step 5 applies. If plan mode is not already active, use the
-   host plan-mode control before dispatching anything.
-3. Dispatch one investigator per in-scope topic, using the host's subagent mechanism, as concurrently as the host allows.
-   Investigators are cheap and narrow: each one gets a single topic and reports back. A host with no subagent mechanism is
-   not a blocker — work the topics inline in this session, in the same order, to the same contract.
-4. Merge what comes back. Findings you did not gather yourself are the report; do not re-inspect files an investigator
-   covered. Reconcile conflicts by reading the cited evidence, and drop any finding whose citation does not hold.
-5. Deliver the merged report and the plan in the host plan, from the shared report contract at
-   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md), with the mode label
-   `audit`. The plan's ordered steps are the `Next action` lines of the findings, grouped by topic and cheapest-first;
-   `Present` findings produce no steps.
-
-Some runs take the report somewhere other than a plan. When the human asks for the durable file, or the host has no plan
-mode, write the same content to `AUDIT_REPORT.md` and preserve everything under `## Reviewer notes` verbatim. When another
-skill invokes the audit as its verification step, report the findings to that caller and stay out of plan mode — the caller
-owns the flow, and the human has usually just left plan mode to let its work happen.
-
-## Dispatching an investigator
-
-Each investigator prompt carries, in full:
-
-- the topic name and the path of its convention topic file;
-- the topic's block from the shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md), and
-  the instruction to check every box in it;
-- the safety constraint below, verbatim — an investigator that reaches for a shell breaks the audit's only guarantee;
-- the report contract's entry format, so findings arrive mergeable: severity, reference, short title, `path:line` evidence,
-  impact, next action;
-- the instruction to report findings back as its result and write no files.
-
-An investigator reports on its topic alone. Anything it notices outside that topic goes back as a note for the orchestrator
-to route, not as a finding it rules on.
-
-## Checklist
-
-The shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md) is the working checklist: a
-full audit covers every block, a scoped audit covers the requested block plus its dependencies. The audit is not complete
-until every in-scope box has been checked by the investigator that owns it and its evidence appears in the report. The
-checklist itself is not edited during an audit.
+1. Resolve the argument. Bare means `full`; an unknown topic is an error, not a reason to widen the scope.
+2. Enter plan mode unless this audit is being called as verification by another skill or the host has no plan mode.
+3. Assign one investigator to each in-scope topic. An investigator checks every section in that topic and writes nothing. If
+   the host cannot dispatch agents, inspect the topics inline in the same order.
+4. Merge the evidence into the shared report format in
+   [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md).
+5. Put each finding's `Next action` into an ordered plan, grouped by topic and cheapest first. Present the report and wait
+   for approval; an audit does not edit the project.
 
-## Safety
+If the caller needs a durable report, write `AUDIT_REPORT.md` and preserve everything under `## Reviewer notes` verbatim.
+
+## Finding format
 
-Use only static inspection: Read, Glob, Grep, and equivalent non-executing search tools. Do not use a shell or invoke Node,
-npm, npx, package scripts, hooks, config imports, linters, tests, builds, Git commands, or project binaries. Read config as
-text and report runtime or machine-local state that cannot be established statically as unverified. This binds every
-investigator too — a dispatched agent inherits the audit's constraint, not the host's default freedom, so the prompt that
-dispatches it repeats this paragraph verbatim.
+Classify every result as one of these:
 
-An audit writes at most one file: `AUDIT_REPORT.md`, in the two cases named in the workflow. Investigators write nothing.
-Neither Write nor the host's dispatch tool is pre-approved in `allowed-tools` — `allowed-tools` names what an audit needs on
-every run, and both of these follow the host's ordinary approval when a run needs them. Host-managed hooks may run after that
-write; the skill neither invokes nor suppresses them, but it does report broken or unexpected hook behavior found during
-static inspection.
+- **Broken**: the project violates a rule in a way that blocks or risks the work.
+- **Missing**: a required piece is absent.
+- **Deviation**: the project works differently from the baseline.
+- **Present**: the rule is met, with evidence.
+- **Unverified**: static inspection cannot establish it.
+
+Use the report contract's severity, `path:line` evidence, concrete impact, and smallest next action. Do not promote an
+optional tool or a working alternative to a missing finding.
 
 ## Topics
 
-| Topic               | Assess                                                                         |
-| ------------------- | ------------------------------------------------------------------------------ |
-| `library-setup`     | styles import, `WebUIProvider`, and library package wiring                     |
-| `library-boundary`  | imports, wrappers, type derivation, and peer boundaries                        |
-| `react`             | component roles, state ownership, and effects discipline                       |
-| `components`        | component folders, anatomy, and colocation                                     |
-| `typescript`        | functional style, types, and naming                                            |
-| `styling`           | CSS Modules, tokens, and prohibited styling systems                            |
-| `tokens`            | names, authored default values, and families from the shipped token index      |
-| `class-names`       | CVA variants, `cx`, and incoming `className` handling                          |
-| `validation`        | runtime schemas, boundary parsing, and derived types                           |
-| `data`              | transport, schemas, query/mutation options, keys, and invalidation             |
-| `authentication`    | current-user query, public/app guards, login, and logout                       |
-| `project-structure` | source tree, route groups, optional app shell, naming, and imports             |
-| `testing`           | test boundaries and verification coverage                                      |
-| `npm-project`       | package metadata, scripts, pins, npm, and Node configuration                   |
-| `tooling`           | dependency selection, devtools, Prettier, ESLint, TypeScript, and verification |
-| `git`               | tracked hooks, verification scopes, and staleness wiring                       |
-| `assets`            | image formats and static asset handling                                        |
-| `docs-structure`    | README, AGENTS, docs index, and content boundaries                             |
-| `agent-tooling`     | installed skills, AGENTS fence, lifecycle hooks, registrations, staleness      |
-
-Report everything within the selected topic: defects and working deviations alike, with no severity-based filtering.
-
-## Agent-tooling assessment reference
-
-The baseline is the conventions [agent-tooling topic](../imf-web-ui-conventions/topics/agent-tooling.md): the complete bundle
-with matching version markers, the AGENTS fence, and the lifecycle hooks installed and registered for both hosts
-(`.claude/settings.json` and `.codex/hooks.json`) or consciously adapted. Hooks or registrations beyond the shipped set — the
-three injection hooks, the stop gate, plus `baseline-staleness.sh` — are drift, and the tracked pre-commit path calls
-`baseline-staleness.sh`. Read files and settings as text—do not run installers, hooks, or local config queries during
-assessment.
-
-Version drift is part of this topic: compare the declared version in `package.json`, the installed
-`node_modules/@imfusion/web-ui/package.json`, and every `.imf-web-ui-skill-version.json` marker, then report the drift and
-point at `imf-web-ui-update`. The registry is unreachable from a static audit, so a line saying that a newer version may
-exist is unverified.
-
-Use the shared report template as the report contract. It defines the headings, ordering, empty-section marker, evidence
-format, and reviewer-note preservation rules; do not duplicate that contract here.
+`full` covers all of these; a named argument covers one:
+
+`library-setup`, `library-boundary`, `react`, `components`, `typescript`, `styling`, `tokens`, `class-names`, `validation`,
+`data`, `authentication`, `project-structure`, `testing`, `npm-project`, `tooling`, `git`, `assets`, `docs-structure`, and
+`agent-tooling`.
+
+Read the corresponding topic and the matching block in
+[`templates/AUDIT_CHECKLIST.md`](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md). The audit is incomplete until every
+in-scope box has evidence.
+
+## Agent tooling checks
+
+For `agent-tooling`, compare the declared version in `package.json`, the installed
+`node_modules/@imfusion/web-ui/package.json`, every `.imf-web-ui-skill-version.json` marker, the `AGENTS.md` fence, hook
+scripts, and both host registrations with the shipped topic. Version drift, extra hooks, stale markers, and missing
+registrations are findings; point version drift to `imf-web-ui-update`. Registry availability is unverified. Read files as
+text; do not run installers or hooks.
+
+## Safety
+
+Use only `Read`, `Glob`, `Grep`, and equivalent static inspection. Do not run Git, shells, Node, npm, npx, package scripts,
+linters, tests, builds, hooks, or imported config. Report runtime state as unverified. Investigators inherit this
+restriction.