@imfusion/web-ui 0.6.1-dev.12.ge86ac0a1 → 0.6.1-dev.14.g8fac1dfb

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

@@ -1,56 +1,46 @@
 ---
 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 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.

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

@@ -1,113 +1,62 @@
 ---
 name: imf-web-ui-components
 description:
-  "Look up @imfusion/web-ui component APIs and icon glyphs without reading source. Load when you need a component's props,
-  sub-components, defaults, or a supplied icon — not for choosing between components (imf-web-ui-ux) or first-time setup
-  (imf-web-ui-setup library-setup)."
+  "Look up @imfusion/web-ui component APIs, compound parts, defaults, and icon glyphs without reading source. Use this
+  whenever a consumer task names a Web UI component or icon and you need to choose a prop, part, default, or glyph. Do not
+  use it to choose between components or bootstrap a project."
 allowed-tools: Bash
 ---
 
-# imf-web-ui-components
+# Look up components
 
-`@imfusion/web-ui` ships two generated files inside `node_modules` so an agent can discover and use its components without
-reading source or checking out the library's repo:
+Use the generated package indexes. They are smaller and more reliable than reading the library source.
 
-- **`node_modules/@imfusion/web-ui/src/llms/llms.gen.txt`** — an identity index: every component's name, category, status,
-  and a one-sentence description of what it's for and what else it's called.
-- **`node_modules/@imfusion/web-ui/src/docgen/doc.gen.json`** — full prop tables (name, type, default, description) for every
-  component, keyed by kebab-case folder name.
-- **`node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json`** — searchable icon names, styles, categories, and tags.
-  Read it only when the task needs an icon.
+## Component lookup
 
-Neither file is reachable through the package's pretty import paths (`@imfusion/web-ui/llms.txt`,
-`@imfusion/web-ui/docgen.json`) — those are Node module-resolution aliases, meaningless to `cat`/`jq`/`grep` reading files
-off disk. Use the `node_modules/...` paths above directly.
+1. Read the identity index:
 
-## The lookup, in two hops
+   ```sh
+   cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
+   ```
 
-**Hop 1 — find the component.** Read the whole index; it's small (~13KB for the full library) and safe to load in full:
+   It lists each component's name, category, status, purpose, and docgen entry.
 
-```sh
-cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
-```
+2. Read only the matching entry from docgen:
 
-Each entry looks like this:
+   ```sh
+   jq '.button' 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 ...
-- 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
-```
+   Replace `.button` with the kebab-case key from the identity index. The result contains `root` and `subComponents`, with
+   each prop's type, default, and description.
 
-**Hop 2 — pull that component's props.** Don't read the whole docgen file (~500KB across all components) — slice out just the
-one entry with the exact command the index gave you:
+   If `jq` is unavailable, use Node without loading the whole file into the conversation:
 
-```sh
-jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json
-```
-
-That returns `{ root: { name, description, props: [...] }, subComponents: [...] }`. `root` is the primary export (`Button`);
-`subComponents` holds compound parts (e.g. `Drawer.Root`, `Drawer.Trigger`, `Drawer.Content` all live under the `drawer`
-key). Match the sub-component you need by its dotted `name`.
-
-**`jq` may not be installed.** Check with `which jq` before relying on it. If it's missing, do **not** fall back to reading
-the whole `doc.gen.json` file — that defeats the entire point of the two-hop design (~500KB across all components vs. one
-~9KB entry) and will burn your context budget for no reason. Use whatever's actually available instead:
-
-```sh
-node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync('node_modules/@imfusion/web-ui/src/docgen/doc.gen.json','utf8')).button, null, 2))"
-```
+   ```sh
+   node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync('node_modules/@imfusion/web-ui/src/docgen/doc.gen.json','utf8')).button, null, 2))"
+   ```
 
-(Node ships everywhere this package can be installed, so this always works as a fallback.) Or ask the user to install `jq` if
-you expect to look up several components in one session.
+Use `doc.gen.json` for Web UI props. A linked upstream page is useful for behavior, composition, and accessibility, but its
+prop table is not authoritative for this package.
 
-**"Further reading" links, if present, are not a props source.** They point at the upstream library's (usually Base UI's) own
-documentation for composition, anatomy, keyboard/focus behavior, and accessibility notes docgen can't express. Props always
-come from `doc.gen.json` — never treat the linked page's prop table as authoritative for a web-ui component; web-ui may add,
-remove, or default differently.
+## If the component is missing
 
-## A component not found in the index?
-
-The index is regenerated on every `@imfusion/web-ui` release; it should be exhaustive. If a component you expect is missing,
-don't guess at an API — that's a real gap to report, not something to work around by inventing props. Tell the web-ui
-maintainer, or file it in the [WEBSDK Jira project](https://imfusion.atlassian.net/browse/WEBSDK) if you have access. If the
-gap is about _which_ component to use rather than a missing one, that's a design question: open `imf-web-ui-ux`.
+Treat a missing identity-index entry as a real gap. Do not invent an API or silently import the upstream component. Report
+the gap to the Web UI maintainer. If the question is which existing component fits, use `imf-web-ui-ux` instead.
 
 ## Icons
 
-When the task mentions an icon, glyph, symbol, or `@imfusion/web-ui/icons`, query the icon catalog before choosing a name. Do
-not load it for ordinary component work.
-
-Search one relevant term at a time, then read only the matching records:
+When the task needs an icon, search the generated catalog before choosing a name:
 
 ```sh
 node -e '
   const q = process.argv[1].toLowerCase();
-  const icons = JSON.parse(
-    require("fs").readFileSync(
-      "node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json",
-      "utf8"
-    )
-  );
-  console.log(
-    JSON.stringify(
-      icons
-        .filter(icon => [icon.name, icon.category, ...icon.tags]
-          .join(" ")
-          .toLowerCase()
-          .includes(q))
-        .slice(0, 20),
-      null,
-      2
-    )
-  );
+  const icons = JSON.parse(require("fs").readFileSync("node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json", "utf8"));
+  console.log(JSON.stringify(icons.filter(icon => [icon.name, icon.category, ...icon.tags].join(" ").toLowerCase().includes(q)).slice(0, 20), null, 2));
 ' "add"
 ```
 
-Import the chosen glyph and `Icon` from `@imfusion/web-ui/icons`. Render it through `Icon`, including when it inherits the
-surrounding color:
+Import the glyph and `Icon` from the Web UI icons entry. Always render the glyph through `Icon`:
 
 ```tsx
 import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
@@ -115,39 +64,33 @@ import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
 <Icon glyph={ArrowRight} aria-hidden />;
 ```
 
-Use `Icon` for every rendered icon. Pass the component reference, not a rendered element:
+Do not import `iconoir-react` or another icon package directly.
 
-```tsx
-import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
+## Compound components
 
-<Icon glyph={ArrowRight} size={16} variant="primary" aria-label="Continue" role="img" />;
-```
+A non-empty `subComponents` array means the component is a namespace:
 
-Never import `iconoir-react` or another icon package directly.
+```tsx
+import { Drawer } from "@imfusion/web-ui";
 
-## Compound components
+<Drawer.Root>
+  <Drawer.Trigger>Open</Drawer.Trigger>
+  <Drawer.Content>…</Drawer.Content>
+</Drawer.Root>;
+```
 
-A component whose docgen entry has a non-empty `subComponents` array is used as a namespace, not a single import — e.g.
-`import { Drawer } from "@imfusion/web-ui"` then `<Drawer.Root>`, `<Drawer.Trigger>`, `<Drawer.Content>`. The index's
-category/description covers the whole family; look at `subComponents` in the docgen entry to see which parts exist and what
-each one's own props are.
+Use the identity index for the family description and the docgen entry for each part's props.
 
-## Integrations (own-entry components)
+## Integrations
 
-A description mentioning "Imported from `@imfusion/web-ui/integrations/<name>`" is a signal this component isn't in the
-default import — e.g.:
+A component whose identity entry says it comes from `@imfusion/web-ui/integrations/*` is not in the main import. Install the
+listed optional peer explicitly, then import from that path:
 
 ```tsx
 import { Code } from "@imfusion/web-ui/integrations/code-highlight";
 ```
 
-These exist because their behavior depends on an optional peer dependency (e.g. `@tanstack/highlight` for `CodeHighlight`)
-that most consumers shouldn't be forced to install. Check the component's description for which peer to add, and add it
-explicitly to your own `package.json` — web-ui does not install it for you.
-
-## Data grids (Table + a headless library)
+## Data grids
 
-For a data grid, drive the styled `Table` parts with a headless table library you install yourself. **TanStack Table**
-(`@tanstack/react-table`) is recommended. Map your `useReactTable` instance onto `Table.Root` / `Table.Header` / `Table.Row`
-/ `Table.Cell`, and use `Table.SortableHeaderCell` for sortable columns — it carries the `aria-sort` state and the sort
-indicator. See the Table primitive's Storybook docs for the pairing.
+`Table` supplies styled table parts, not sorting or pagination. Pair them with a headless table library installed by the
+consumer. TanStack Table is the recommended choice. Use `Table.SortableHeaderCell` for sortable columns.

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

@@ -1,57 +1,44 @@
 ---
 name: imf-web-ui-conventions
 description:
-  "The ImFusion frontend conventions baseline — in-house conventions, valid in every ImFusion frontend and usable by anyone
-  who likes them. A router over topic references: library setup, library boundary, React, components, TypeScript, styling,
-  tokens, validation, data layer, authentication, project structure, testing, tooling, npm project, git, agent tooling,
-  assets, and docs structure. Load when writing wrapper components, custom UI, styling beyond the defaults, validating
-  external data, adding new files to a consumer app, writing repo docs, touching tool config, choosing any dependency, or
-  installing the vendored skills and lifecycle hooks."
+  "Apply the ImFusion frontend conventions to consumer code. Use this whenever a task writes a wrapper or custom UI, CSS,
+  TypeScript, data fetching, validation, tests, project files, configuration, documentation, dependencies, or agent tooling
+  in a project that uses @imfusion/web-ui. Read only the topic references that match the task."
 ---
 
-# imf-web-ui-conventions
-
-The ImFusion frontend baseline. In-house conventions, not industry claims — they encode how ImFusion frontends are built, and
-anyone else is welcome to them.
-
-**The project wins.** These defaults fill vacuums: if the host project already has a convention — a styling system, a state
-library, a folder shape — that stands. They are not a license to refactor a consumer codebase toward this document.
-
-When a project has an established convention, it wins. The audit skill records a working difference as a deviation; the setup
-skill proposes only the changes the project asks it to make.
-
-## The topics
-
-Each topic lives in one reference. Read the one whose moment you're in; starting a new feature usually wants several.
-
-| Reference                                           | Covers                                                              | Read when                                               |
-| --------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
-| [library-setup.md](topics/library-setup.md)         | styles import, `WebUIProvider`, and broken library wiring           | installing or repairing library wiring                  |
-| [library-boundary.md](topics/library-boundary.md)   | staying behind `@imfusion/web-ui`, wrappers, type derivation, peers | touching anything that renders library components       |
-| [authentication.md](topics/authentication.md)       | current-user source, public/app guards, login and logout            | setting up or reviewing route protection                |
-| [react.md](topics/react.md)                         | component roles, state kinds and owners, effects discipline         | writing new screens, components, or wrappers            |
-| [components.md](topics/components.md)               | component anatomy on disk: grouping, folders, colocation            | adding a component file                                 |
-| [typescript.md](topics/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
-| [styling.md](topics/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
-| [tokens.md](topics/tokens.md)                       | shipped CSS-variable names grouped by family                        | choosing a design token                                 |
-| [class-names.md](topics/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
-| [validation.md](topics/validation.md)               | runtime schemas, boundary parsing, schema-derived types             | accepting data the frontend does not own                |
-| [data.md](topics/data.md)                           | `api/`+`http/` shape, query/mutation patterns and invalidation      | adding an API topic, a fetch, or a mutation             |
-| [project-structure.md](topics/project-structure.md) | the `src/` tree, route groups, file naming, imports                 | adding files rather than editing existing ones          |
-| [testing.md](topics/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
-| [tooling.md](topics/tooling.md)                     | the topic→tool map, tool configuration, and verification            | choosing a dependency or touching tool config           |
-| [npm-project.md](topics/npm-project.md)             | `package.json`, the `verify:*` script set, dependency pinning       | running or adding a script, adding a dependency         |
-| [git.md](topics/git.md)                             | `git:config`, verify scopes, staleness at commit time               | wiring hooks or the commit path                         |
-| [agent-tooling.md](topics/agent-tooling.md)         | vendored skills, lifecycle hooks, registrations, Codex trust        | installing or reviewing the shipped agent tooling       |
-| [assets.md](topics/assets.md)                       | image formats, the WebP recipe                                      | adding images or other static assets                    |
-| [docs-structure.md](topics/docs-structure.md)       | what a repo documents, where, how it's written                      | writing or restructuring repo docs                      |
-
-## Topic format
-
-Topics are manifests, not essays: `##` sections group rule bullets, and each section is one auditable unit. A rule is one
-imperative bullet; only a pushback-prone rule carries a one-line why. Snippets illustrate rules, prose never replaces them.
-Each topic's `##` sections map 1:1 to its block in [templates/AUDIT_CHECKLIST.md](templates/AUDIT_CHECKLIST.md) — add,
-remove, or rename a section and the checklist follows in the same change.
-
-`imf-web-ui-setup` proposes approved bootstrap changes, while `imf-web-ui-audit` reports the current state against this
-baseline.
+# Frontend conventions
+
+These are ImFusion defaults, not claims about every frontend. A host project's working choice wins. Use these topics to fill
+a gap or to make a deliberate deviation visible; do not refactor a project just to match the baseline.
+
+## Choose a topic
+
+| Topic                                            | Read when                                                       |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| [library-setup](topics/library-setup.md)         | Installing or repairing stylesheet and provider wiring.         |
+| [library-boundary](topics/library-boundary.md)   | Rendering Web UI components, wrapping them, or choosing a peer. |
+| [authentication](topics/authentication.md)       | Protecting routes or defining login and logout.                 |
+| [react](topics/react.md)                         | Designing component roles, state ownership, or effects.         |
+| [components](topics/components.md)               | Adding files or deciding component anatomy.                     |
+| [typescript](topics/typescript.md)               | Writing TypeScript or naming values.                            |
+| [styling](topics/styling.md)                     | Writing CSS or customizing Web UI.                              |
+| [tokens](topics/tokens.md)                       | Choosing an exact token name.                                   |
+| [class-names](topics/class-names.md)             | Mapping variants and `className` to CSS.                        |
+| [validation](topics/validation.md)               | Accepting data from outside the frontend.                       |
+| [data](topics/data.md)                           | Adding API queries, mutations, or invalidation.                 |
+| [project-structure](topics/project-structure.md) | Adding files or routes.                                         |
+| [testing](topics/testing.md)                     | Deciding what to test.                                          |
+| [tooling](topics/tooling.md)                     | Adding a dependency or configuring a tool.                      |
+| [npm-project](topics/npm-project.md)             | Changing `package.json`, scripts, pins, or Node.                |
+| [git](topics/git.md)                             | Configuring hooks or choosing verification scope.               |
+| [agent-tooling](topics/agent-tooling.md)         | Installing skills or lifecycle hooks.                           |
+| [assets](topics/assets.md)                       | Adding images, icons, or other static files.                    |
+| [docs-structure](topics/docs-structure.md)       | Writing or reorganizing repository docs.                        |
+
+## How to use the topics
+
+Read the relevant file instead of loading the whole set. Each topic is a short checklist: follow its rules, use its examples
+as patterns, and keep any exception explicit in the host project.
+
+`imf-web-ui-setup` uses these topics to plan approved project changes. `imf-web-ui-audit` uses them to report the current
+state without changing files.

package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md

@@ -58,6 +58,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Build custom UI from tokens
 - [ ] Override through the sanctioned seams
 - [ ] The color system
+- [ ] Browser floor
 - [ ] Responsive styling
 
 ## Tokens — `tokens`