@imfusion/web-ui 0.6.1-dev.27.gfc6e5abb → 0.6.1-dev.3.g5b432448

package/src/llms/llms.gen.txt

@@ -11,189 +11,183 @@ props, which always live in the docgen file above.
 
 ## AppShell
 - category: Layout, status: stable
-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.
+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.
 - 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 such as submit, confirm, cancel, navigate, or delete. Also called a CTA or action button; variants and sizes communicate its importance.
+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.
 - 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
-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.
+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).
 - 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 for related content on a tonal background. Also called a panel or tile; compose it from optional image, header, content, and footer parts.
+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.
 - 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 submitted choices such as terms, table rows, or list items. Also called a check box; it supports an indeterminate parent state.
+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.
 - 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 label for tags, status, categories, counts, and metadata. Also called a badge or tag; its color and appearance are independent choices.
+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.
 - 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
-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.
+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.
 - 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 inline or in a block, with optional language labels and copying. Also called a code snippet or code block.
+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.
 - 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 Code parts powered by TanStack Highlight. Import from the integration entry and install the optional @tanstack/highlight peer.
+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.
 - 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
-Show-and-hide region for secondary content such as FAQs, settings, or details. Also called a disclosure or expand/collapse.
+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.
 - 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
-Copies a value to the clipboard and briefly shows confirmation. Also called a copy-to-clipboard button; commonly used with Code.Block.
+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.
 - 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 for navigation, settings, filters, or focused tasks. Also called a sidebar, side panel, or sheet.
+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.
 - 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, control, supporting text, and validation message. Use it with Input, Checkbox, Select, and other form controls.
+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.
 - 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 group for related form controls with a shared legend. Also called a form group; it can propagate a disabled state to the group.
+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.
 - 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
-Renders a Web UI icon with an optional semantic foreground color. The default inherits the surrounding currentColor.
+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.
 - 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
-Panel and toolbar controls for an image dataset's display options, including window, level, gamma, and invert settings.
+A panel or toolbar of controls bound to an image dataset's display options.
 - 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; it supports controlled values and Field validation state.
+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).
 - 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
-Renders a logo from a URL or inline React element with consistent sizing. Also called a wordmark or brand mark.
+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.
 - 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 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.
+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.
 - 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 for contextual content, quick forms, or actions. Also called a popup or flyout; use Tooltip for hints without interaction.
+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.
 - 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 for spacing, aligning, and wrapping children. Also called a horizontal stack or flex row.
+Horizontal layout primitive — children are arranged left-to-right with configurable spacing, alignment, and optional wrapping. Also called hstack, horizontal stack, 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
-Dropdown for choosing a value from a known list. Also called a picker; use it for a labeled, keyboard-accessible option list.
+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.
 - 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
-Line that divides content horizontally or vertically. Also called a divider or rule.
+Thin line that visually divides content into groups — section break, list item rule, sidebar division. Also called a divider, hr, or horizontal / vertical 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
-Numeric input for choosing one value or a range by dragging a thumb. Also called a range input; use it when relative magnitude matters.
+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.
 - 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
-Indeterminate loading indicator. Also called a loader or progress spinner.
+Loading indicator built from the animated ImFusion glyph. Also called a loader, progress spinner, or activity indicator; signals indeterminate loading.
 - 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 for spacing and aligning children. Also called a vertical stack or column.
+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.
 - 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 control for an on/off setting that takes effect immediately. Also called a toggle; use Checkbox for a submitted choice.
+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.
 - 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
-Presentational table parts for static tabular data. Pair them with a headless table library for sorting, pagination, or selection.
+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.
 - 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
-Switches between related panels within one view. Also called a tab strip or tab bar; it supports horizontal and vertical layouts.
+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.
 - 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
-Two-state button for a pressed or unpressed option. Compose several in ToggleGroup for a segmented control.
+A two-state button that can be on or off. Compose several inside a 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
-Group of connected Toggle buttons that share a selection. Also called a segmented control; set `multiple` for more than one active option.
+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.
 - 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 label for brief help about a control or term. Also called a hint; use Popover for a panel with actions.
+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.
 - 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
-Semantic text primitives for headings, paragraphs, lists, quotes, links, and inline code. The namespace uses native HTML elements and token-based text roles.
+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).
 - 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,47 +1,56 @@
 ---
 name: imf-web-ui
 description:
-  "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."
+  "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 Web UI work
+# imf-web-ui
 
-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.
+`@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.
 
-## 1. Decide whether guidance is needed
+## Row zero — is help needed at all?
 
-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.
+Before routing, check whether this task needs guidance in the first place. It does **not** when:
 
-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.
+- 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.
 
-## 2. Route the task
+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.
 
-| 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`                                    |
+## Routing
 
-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 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` |
 
-## 3. Keep project choices
+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.
 
-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.
+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.
 
-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.
+## The stack
 
-## 4. Ask only when the choice depends on missing context
+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.
 
-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.
+## 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.

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

@@ -1,67 +1,119 @@
 ---
 name: imf-web-ui-audit
 description:
-  "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."
+  "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."
 argument-hint: "[full|<topic>]"
 allowed-tools: Read Glob Grep
 ---
 
-# Audit a consumer project
+# imf-web-ui-audit
 
-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.
+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.
 
-## Workflow
-
-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.
+An audit belongs in plan mode: it ends in work to approve, not in files to write.
 
-If the caller needs a durable report, write `AUDIT_REPORT.md` and preserve everything under `## Reviewer notes` verbatim.
+## Workflow
 
-## Finding format
+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.
 
-Classify every result as one of these:
+## Safety
 
-- **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 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.
 
-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.
+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.
 
 ## Topics
 
-`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.
+| 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.