@imfusion/web-ui 0.8.1-dev.7.g5ec2789c → 0.8.1-dev.72.g2aaa1dd3

package/src/llms/llms.gen.txt

@@ -38,7 +38,7 @@ Persistent, in-place status message for information, success, warnings, and erro
 
 ## 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 for related content on a tonal background. Also called a panel or tile; compose it from optional image, status, 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
@@ -96,11 +96,22 @@ Semantic group for related form controls with a shared legend. Also called a for
 - 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
 
+## FrameSelection
+- category: Inputs, status: experimental
+Frame or slice picker bound to the focused frame of ImFusion image sets, with a focus and count readout. For a position picker not tied to the SDK, use Slider with variant="position".
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .frame-selection (jq: jq '.frame-selection' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://docs.imfusion.com/
+
 ## Icon
 - category: Display, status: stable
 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)
 
+## IconButton
+- category: Buttons, status: experimental
+Square button that shows a single icon and no visible text, with its accessible name from `label`. Also called an icon-only or toolbar button. Use Button with `startIcon` or `endIcon` when a text label is visible.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .icon-button (jq: jq '.icon-button' 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.
@@ -113,11 +124,22 @@ Single-line text input for form data entry. Also called a text field; it support
 - 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
 
+## Kbd
+- category: Display, status: experimental
+Shows a keyboard key or shortcut, such as the letter that activates a button. Also called a key hint; Button and Toggle render it through their `shortcut` prop.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .kbd (jq: jq '.kbd' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## 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.
 - 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)
 
+## Meter
+- category: Display, status: experimental
+Read-only bar for a measured amount within a known range, such as seats in use or storage used. Also called a gauge or usage bar. Use Slider when the user sets the value.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .meter (jq: jq '.meter' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/meter.md
+
 ## 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.
@@ -158,9 +180,14 @@ Line that divides content horizontally or vertically. Also called a divider or r
 - 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
 
+## Skeleton
+- category: Display, status: experimental
+Loading placeholder that stands in for data at the size it will take, so nothing shifts when it lands. Also called a skeleton loader or ghost. Use Spinner when the layout is unknown.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .skeleton (jq: jq '.skeleton' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## 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.
+Numeric input for choosing one value or a range by dragging a thumb. Also called a range input; use it when relative magnitude matters. The position variant is a scrubber for picking one slice or frame.
 - 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
 

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

@@ -11,6 +11,8 @@ description:
 Start here for UI work and library questions in a project that uses `@imfusion/web-ui`. This skill is a map, not a second
 copy of every convention.
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 ## 1. Decide whether guidance is needed
 
 Skip a companion when the task is explicit and small, an existing local pattern already solves it in the file being changed,
@@ -60,7 +62,7 @@ props and the conventions `tokens` topic for exact token names and defaults.
 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.
 
-When a task needs TanStack Router, Query, Form, Table, or Store and the project has no incumbent, open
+When a task needs TanStack Router, Query, Form, Table, Store, or Hotkeys and the project has no incumbent, open
 `imf-web-ui-conventions` for the house position on that layer, then read the library's current documentation with
 `npx @tanstack/cli` before using it. The recommendation lives in the conventions topics, not here.
 

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

@@ -1,11 +1,11 @@
 ---
 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,
+  "Audit an existing ImFusion frontend against the @imfusion/web-ui conventions without changing project 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
+allowed-tools: Read Glob Grep Skill
 ---
 
 # Audit a consumer project
@@ -21,6 +21,8 @@ it low, and do not let it crowd the sections a consumer has to act on.
 
 ## Workflow
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 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. Read the report template and existing reviewer notes, then dispatch one investigator per in-scope topic. Tell each
@@ -28,7 +30,8 @@ it low, and do not let it crowd the sections a consumer has to act on.
    section in that topic and writes nothing. Once dispatch starts, the host performs no repository inspection: the returned
    reports are the evidence, and the host merges them without reading or searching the files again. Gathering the evidence
    twice spends context on the second pass and reports what the host still remembers. Inspect a topic inline only after its
-   dispatch has been tried and refused, and say which attempt failed.
+   dispatch has been tried and refused, and say which attempt failed. A `full` audit also dispatches one marker investigator;
+   a named-topic audit gives that search to the topic's investigator. See [Deferred-work markers](#deferred-work-markers).
 4. Merge the evidence into the shared report format in
    [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md). Before presenting or writing it, check that every
    Broken, Missing, Deviation, and Unverified entry has a severity, evidence, impact, and next action; do not compact
@@ -66,6 +69,17 @@ 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.
 
+## Deferred-work markers
+
+Comments that mark unfinished work are evidence the code itself admits. Search the frontend sources, styles, stories, tests,
+and frontend config for `TODO`, `FIXME`, `HACK`, `XXX`, and phrases like "temporary", "workaround", "for now", or "remove
+once". Skip `node_modules`, build output, generated files, and vendored code. A named-topic audit keeps only the markers that
+bear on that topic.
+
+Read each marker with its surrounding code. One that admits a convention gap, such as a hand-rolled control waiting for a Web
+UI component or a hard-coded color waiting for a token, is evidence for that topic's finding. Every other marker goes under
+`Suggestions` with its `path:line` and what it defers; group repeats of one cause into a single entry.
+
 ## Agent tooling checks
 
 For `agent-tooling`, compare the declared version in `package.json`, the installed

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

@@ -4,13 +4,15 @@ description:
   "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
+allowed-tools: Bash Skill
 ---
 
 # Look up components
 
 Use the generated package indexes. They are smaller and more reliable than reading the library source.
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 ## Component lookup
 
 1. Read the identity index first, even when you already know the component's name: it gives the docgen key and the status.

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

@@ -103,8 +103,9 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] When a library owns a layer
 - [ ] Devtools
 - [ ] Docs over memory
-- [ ] Prettier
-- [ ] ESLint and TypeScript
+- [ ] Vite+
+- [ ] Oxfmt
+- [ ] Oxlint and TypeScript
 - [ ] Pre-commit checks
 - [ ] Vite plugins
 

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

@@ -19,7 +19,8 @@ Use one server-backed current-user query as the identity source:
 
 - Put it in `api/auth/queries.ts` and define its key and schema with the [data.md](data.md) pattern.
 - Expose query options as `context.api.auth.getUser()`.
-- Call `ensureQueryData` in a loader or a query hook in a component.
+- Call `queryClient.query({ ...options, staleTime: "static" })` in a loader (see [data.md](data.md)) or a query hook in a
+  component.
 - Keep credentials and access tokens out of React state.
 - Do not infer authentication from local storage, decoded tokens, route flags, or permission-gated UI.
 

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

@@ -85,9 +85,11 @@ export function getDetails(options?: QueryOptions<User>) {
 }
 ```
 
-Callers choose `ensureQueryData`, `useSuspenseQuery`, or another Query API. Mutation factories likewise return
-`mutationOptions`, own their mutation key and parsing, and are passed to `useMutation`; do not inline those options at the
-call site.
+Callers choose `queryClient.query`, `useSuspenseQuery`, or another Query API. A router loader reads the cache with
+`queryClient.query({ ...options, staleTime: "static" })`, not the deprecated `ensureQueryData` or `fetchQuery`. Keep
+`"static"`: without it the factory's `staleTime` applies (default 0), so every loader run waits on the network and the page's
+`useQuery` refetches on mount. Mutation factories likewise return `mutationOptions`, own their mutation key and parsing, and
+are passed to `useMutation`; do not inline those options at the call site.
 
 ## Router context access
 

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

@@ -18,11 +18,10 @@ The hooks are tracked in `.githooks/`. Check both the Git setting and the direct
 
 There are two scopes:
 
-- **commit**: `verify:staged`, run by pre-commit. It checks whole-repository lint and formatting, then runs project checks
-  for staged inputs.
+- **commit**: the pre-commit hook, which runs `vp staged` as `tooling.md` describes under Pre-commit checks.
 - **full**: `verify:full`, the build and complete verification used by CI.
 
-The scripts under `scripts/verify/` own the step lists. Hooks and npm scripts only launch them.
+The `staged` block and the scripts under `scripts/verify/` own the step lists. Hooks and npm scripts only launch them.
 
 ## Staleness at commit time
 

package/src/llms/skills/imf-web-ui-conventions/topics/npm-project.md

@@ -17,12 +17,11 @@ Use the same names for the same checks where the project supports them:
 | ------------------ | --------------------------------------- |
 | `dev`              | Start local development.                |
 | `build`            | Create a production build.              |
-| `verify:format`    | Check Prettier.                         |
-| `verify:lint`      | Check ESLint.                           |
+| `verify:format`    | Run `vp fmt --check`.                   |
+| `verify:lint`      | Run `vp lint`.                          |
 | `verify:typecheck` | Run TypeScript without emitting.        |
-| `verify:tests`     | Run tests once.                         |
+| `verify:tests`     | Run `vp test run`.                      |
 | `verify:knip`      | Check dead code and unused exports.     |
-| `verify:staged`    | Run the pre-commit scope.               |
 | `verify:full`      | Run the CI scope.                       |
 | `format`           | Rewrite formatting.                     |
 | `lint`             | Rewrite fixable lint issues.            |

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

@@ -7,6 +7,8 @@ Use native CSS and Web UI's public seams. The library's CSS Modules and token na
 - Use CSS Modules with native nesting. Do not add Sass, CSS-in-JS, or a utility-class framework for ordinary component
   styles.
 - Nest states, pseudo-elements, and child selectors under the root.
+- Write declarations before nested rules; browsers before Chrome 130, Firefox 132, and Safari 18 move later ones above them.
+- Do not nest under a selector list whose selectors differ in specificity. The nested rule takes the highest one.
 - Lift repeated values into custom properties, especially when a state or variant changes several descendants.
 - Keep structurally different rules explicit; not every repeated value needs an abstraction.
 
@@ -85,8 +87,8 @@ Foreground roles are for text, icons, borders, and focus rings. Background roles
 
 ## Browser floor
 
-The library targets Safari 16.2 or newer. `color-mix(in oklch, …)` is available at that floor. Relative color syntax needs a
-guarded fallback for older Safari:
+The library targets Safari 17.5, Chrome 123, and Firefox 120 or newer, the first versions with native `light-dark()`.
+`color-mix(in oklch, …)` is available at that floor. Relative color syntax needs a guarded fallback for older Safari:
 
 ```css
 .subtle {

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

@@ -4,27 +4,28 @@ Use the tool's current documentation rather than memory.
 
 ## Topic-to-tool map
 
-| Need                  | Default                                      |
-| --------------------- | -------------------------------------------- |
-| Build                 | Vite                                         |
-| Routing and URL state | TanStack Router                              |
-| Server state          | TanStack Query                               |
-| Forms                 | TanStack Form                                |
-| Data grids            | TanStack Table plus Web UI `Table` parts     |
-| App-wide client state | TanStack Store, after URL/server/local state |
-| Schema validation     | Zod at the boundary                          |
-| Tests                 | Vitest                                       |
-| Format                | Prettier                                     |
-| Lint                  | ESLint flat config                           |
-| Types                 | `tsc --noEmit`                               |
-| Pre-commit checks     | Whole-repository lint and format checks      |
-| Dead code             | Knip via `verify:knip`                       |
+| Need                  | Default                                                        | Docs                                      |
+| --------------------- | -------------------------------------------------------------- | ----------------------------------------- |
+| Toolchain             | Vite+ (`vite-plus`), driven through `vp`                       | https://viteplus.dev/guide                |
+| Routing and URL state | TanStack Router                                                | `npx @tanstack/cli`, library `router`     |
+| Server state          | TanStack Query                                                 | `npx @tanstack/cli`, library `query`      |
+| Forms                 | TanStack Form                                                  | `npx @tanstack/cli`, library `form`       |
+| Data grids            | TanStack Table plus Web UI `Table` parts                       | `npx @tanstack/cli`, library `table`      |
+| App-wide client state | TanStack Store, after URL/server/local state                   | `npx @tanstack/cli`, library `store`      |
+| Keyboard shortcuts    | TanStack Hotkeys; show the key with Web UI `shortcut` or `Kbd` | `npx @tanstack/cli`, library `hotkeys`    |
+| Schema validation     | Zod at the boundary                                            | https://zod.dev                           |
+| Tests                 | Vitest through `vp test`                                       | https://vitest.dev                        |
+| Format                | Oxfmt through `vp fmt`                                         | https://oxc.rs/docs/guide/usage/formatter |
+| Lint                  | Oxlint through `vp lint`, type-aware                           | https://oxc.rs/docs/guide/usage/linter    |
+| Types                 | `tsc --noEmit`                                                 | https://www.typescriptlang.org/docs       |
+| Pre-commit checks     | `vp staged` against the staged state                           | https://viteplus.dev/guide                |
+| Dead code             | Knip via `verify:knip`                                         | https://knip.dev                          |
 
 ## When a library owns a layer
 
 Use the library that already owns the problem. Adopt Form for form rules, Query for caching and refetching, Router for URL
-state, and Table for sorting and pagination instead of rebuilding those layers. Keep an existing project choice when it
-works.
+state, Table for sorting and pagination, and Hotkeys for keyboard shortcuts instead of rebuilding those layers. Web UI only
+shows a key; the app binds it. Keep an existing project choice when it works.
 
 ## Devtools
 
@@ -33,50 +34,90 @@ devtools package whenever a new TanStack dependency is added.
 
 ## Docs over memory
 
-Use `npx @tanstack/cli` for TanStack documentation. If TanStack Intent is configured, use it for the Agent Skills the
-TanStack package provides.
+Use `npx @tanstack/cli` for TanStack documentation, with the library id from the map: `search-docs "<query>" --library <id>`
+finds a page, and `doc <id> <path>` prints it, for example
+`npx @tanstack/cli doc hotkeys framework/react/reference/functions/useHotkey`. If TanStack Intent is configured, use it for
+the Agent Skills the TanStack package provides.
 
-## Prettier
+## Vite+
 
-Use a config file. The repo's values are:
+Vite+ runs development, build, tests, format, lint, and staged checks through one `vp` binary configured in `vite.config.ts`.
+Pin `vite-plus` exactly, alias `vite` to `npm:@voidzero-dev/vite-plus-core@<vite-plus version>`, pin `vitest` to the version
+`vp toolchain vitest` reports, and repeat both pins under `overrides`. Import `defineConfig` from `vite-plus` and Vitest APIs
+from `vite-plus/test`. It needs Node `^22.22.1 || ^24.11 || >=26` and Git 2.32 or later.
+
+`vp <command>` is a built-in; `vp run <script>` runs a package script.
+
+Move an existing Vite, Vitest, ESLint, or Prettier project with `vp migrate --no-hooks` (`vp help migrate` lists its
+options), then check the result against this topic. The hook lives in `.githooks/`, as `git.md` describes.
+
+## Oxfmt
+
+Configure formatting in the `fmt` block of `vite.config.ts`. The repo's values:
 
 ```ts
-import type { Config } from "prettier";
-
-const config: Config = {
-  printWidth: 125,
-  tabWidth: 2,
-  useTabs: false,
-  trailingComma: "none",
-  arrowParens: "avoid",
-  semi: true,
-  singleQuote: false,
-  proseWrap: "always"
-};
-
-export default config;
+export default defineConfig({
+  fmt: {
+    printWidth: 125,
+    tabWidth: 2,
+    useTabs: false,
+    trailingComma: "none",
+    arrowParens: "avoid",
+    semi: true,
+    singleQuote: false,
+    proseWrap: "always",
+    sortPackageJson: false
+  }
+});
 ```
 
-## ESLint and TypeScript
+## Oxlint and TypeScript
 
-Use flat ESLint config with type-aware rules and the repo's ignore file. The baseline bans `as` and non-null `!` outside
-tests, requires the `#/` alias instead of parent-relative imports, and uses project-service type information.
+Configure linting in the `lint` block with type-aware rules on. The baseline bans `as` and non-null `!` outside tests and
+requires the `#/` alias instead of parent-relative imports:
+
+```ts
+export default defineConfig({
+  lint: {
+    options: { typeAware: true },
+    overrides: [
+      {
+        files: ["src/**/*.{ts,tsx}"],
+        rules: {
+          "typescript/consistent-type-assertions": ["error", { assertionStyle: "never" }],
+          "typescript/no-non-null-assertion": "error",
+          "no-restricted-imports": [
+            "error",
+            { patterns: [{ group: ["../*"], message: "Use the #/ alias for anything outside the current folder." }] }
+          ]
+        }
+      },
+      {
+        files: ["**/*.test.{ts,tsx}"],
+        rules: { "typescript/consistent-type-assertions": "off", "typescript/no-non-null-assertion": "off" }
+      }
+    ]
+  }
+});
+```
 
 Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `#/` paths. Keep
 `import type` for type-only imports.
 
 ## Pre-commit checks
 
-The pre-commit hook checks the whole repository with ESLint and Prettier, then runs project checks for staged inputs that can
-affect generated files, types, dependencies, or TeamCity configuration. It does not rewrite files during a commit; use
-`npm run format` to apply Prettier changes explicitly.
+`.githooks/pre-commit` runs `vp staged --hide-unstaged --fail-on-changes --revert --diff-filter=ACMRD` with `set -e`. Those
+flags make the checks see only the staged state, include deletion-only commits, fail the commit when a check would change a
+file, and restore the tree afterwards, so the hook never rewrites or stages files. The `staged` block in `vite.config.ts` is
+a function returning path-free commands such as `npm run --silent verify:lint`, so each project-wide check runs once. Use
+`npm run format` to apply formatting explicitly.
 
 ## Vite plugins
 
 Register Web UI's Vite plugins in the application configuration:
 
 ```ts
-import { defineConfig } from "vite";
+import { defineConfig } from "vite-plus";
 import react from "@vitejs/plugin-react";
 import { imfusionBrandAssets, readableCssModuleNames } from "@imfusion/web-ui/vite";
 

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

@@ -15,6 +15,8 @@ working choices.
 
 ## Workflow
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 1. Resolve the scope. A named topic limits the assessment to that topic. A bare invocation means `full`, unless the request
    is about one topic, in which case that topic is the scope: answer what was asked and offer the wider sweep rather than
    running it. If the argument is unknown, list the supported topics and point to `imf-web-ui-audit`.

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

@@ -5,7 +5,7 @@ description:
   lifecycle hooks. Refresh the base first, verify it, then audit any consumer migration separately. Preserve user work and
   get approval before each commit."
 argument-hint: "[--dry-run] [optional version or reason]"
-allowed-tools: Bash Read Grep
+allowed-tools: Bash Read Grep Skill
 ---
 
 # Update Web UI
@@ -13,6 +13,22 @@ allowed-tools: Bash Read Grep
 This workflow has two possible commits: the package/tooling update, then an optional consumer migration. Keep them separate.
 Never overwrite user changes or commit without fresh approval.
 
+## Before you start
+
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
+Open with a short orientation, before any command runs, so the person knows the route and when they will be asked:
+
+1. **Preflight**: check the project and stop on uncommitted work.
+2. **Base update**: install the new package, refresh the skills and hooks, verify, then ask to commit.
+3. **Migration check**: read what the new releases changed and report what this project needs; changes and their separate
+   commit wait for approval.
+4. **Full audit**: offer `imf-web-ui-audit full`, a read-only check of the whole project against the conventions, wider than
+   what this release changed.
+
+Name the decision points up front: `latest` or `dev` when the installed version is a prerelease, the base commit, the
+migration commit, and the audit offer. With `--dry-run`, say the run stops after preflight and changes nothing.
+
 ## Preflight
 
 1. Work from the frontend package root. In a monorepo, find the package that owns the Web UI dependency.
@@ -20,9 +36,22 @@ Never overwrite user changes or commit without fresh approval.
    if another lockfile is the active one.
 3. Record `git status --short`, the installed Web UI version, the installed skill harness(es), hooks, registrations, and
    `AGENTS.md` fence.
-4. Check for another npm process and stop on a conflict. Uncommitted work is also a conflict: report it and stop before the
-   first mutating command, even if it looks unrelated to this workflow: what the update touches is only known once it runs,
-   and the person can commit, stash, or wave it through in one reply. Never reset, clean, restore, or hide it.
+4. Check for another npm process in this package and stop on a conflict:
+
+   ```sh
+   pgrep npm                     # process IDs only
+   lsof -a -d cwd -p <pid> -Fn   # the folder a process runs in
+   ps -o args= -p <pid>          # its command, only when that folder is this package
+   ```
+
+   A running install, update, or `ci` in this package is a conflict; a long-running `npm exec` server is not. Full process
+   listings such as `pgrep -fl` or `ps aux` print every program's arguments, secrets included, so keep them out of the
+   transcript.
+
+   Uncommitted work is also a conflict: report it and stop before the first mutating command, even if it looks unrelated to
+   this workflow: what the update touches is only known once it runs, and the person can commit, stash, or wave it through in
+   one reply. Never reset, clean, restore, or hide it.
+
 5. With `--dry-run`, stop after reporting what would happen. Do not install, format, stage, commit, or ask for commit
    approval.
 
@@ -87,12 +116,13 @@ Update files : <paths>
 Held back    : <paths or none>
 Conflicts    : <paths or none>
 Commit       : <message or not proposed>
+Next         : migration check, then the optional full audit
 ```
 
 Ask: **Approve these update-owned changes and commit them?** Stage only approved update paths and follow the repository's
 commit workflow.
 
-## Audit the consumer migration
+## Check the consumer migration
 
 Start this phase only after the base update commit exists. Read `node_modules/@imfusion/web-ui/CHANGELOG.md`: every release
 section after the pre-update version, up to and including the new one. Each section's highlights, migration guide, and
@@ -114,12 +144,17 @@ releases read, then report separately:
 - existing uses affected by a changed API or documented behavior;
 - suggestions: new features from the highlights and `Added` entries that fit what the project already builds, each with the
   project code it would serve; a suggestion stays a proposal until the person asks for it;
-- custom components that overlap with a current Web UI primitive, with evidence and any behavior to preserve.
+- custom components that overlap with a current Web UI primitive, with evidence and any behavior to preserve;
+- icons: project-local icons (inline SVGs, icon components, a third-party icon set) that a catalog icon now covers, above all
+  the ImFusion icons (`"origin": "imfusion"`). Search `node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json` by
+  meaning, compare the drawing, and report each with the replacement export; a replacement stays a proposal until the person
+  asks for it.
 
 Do not infer a replacement from a name. Inspect the implementation, styles, and call sites. If there are no findings, say so
 and do not make an empty migration commit.
 
-Ask whether to run `imf-web-ui-audit full`. Run it only after an explicit yes.
+Offer `imf-web-ui-audit full` as the next step: the migration check covered what the releases changed, the audit checks the
+whole project against the conventions and changes nothing. Run it only after an explicit yes.
 
 For approved migration work, ask: **Approve these consumer migration changes and commit them separately?** Then stage only
 the approved paths, verify again, and use a separate imperative commit message.

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

@@ -0,0 +1,95 @@
+---
+name: imf-web-ui-user-profile
+description:
+  "Read or create the person's profile: technical background, experience, how they want things explained, and how they like
+  to work. Invoke it first in every Web UI skill, and when the person asks to change their profile or how the agent explains
+  or paces work."
+user-invocable: false
+allowed-tools: Bash Read Write
+---
+
+# Fit the work to the person
+
+The profile records who the person is and how they learn, so every Web UI workflow explains what they need and paces the work
+the way they like. Read it once per session; later skills in the same session reuse what is already loaded.
+
+## Read the profile
+
+Resolve the profile path with the shell, then read that exact path:
+
+```sh
+printf '%s\n' "${XDG_CONFIG_HOME:-$HOME/.config}/imfusion/web-ui/consumer-profile.md"
+```
+
+The profile sits outside the project: it belongs to the person, never to the repository, so read-only promises such as the
+audit's still hold when this skill writes it.
+
+When the file exists, apply it and return to the calling workflow without comment. When it is missing, run the interview
+before the workflow starts. When the router skips companions for a small task, do the task first and offer the interview
+afterwards.
+
+## Interview
+
+Open with one question: may you ask six short questions and save the answers to the profile path, so every later workflow
+fits them and they are never asked again? Mention that they can decline any single question. On no, use the defaults below
+for this session and do not offer the interview again in it.
+
+On yes, ask one question per message, in plain prose, and wait for each answer:
+
+1. What is your name?
+2. What is your technical background: the languages and tools you work with?
+3. How much have you built for the web, for example with React, HTML, and CSS?
+4. Beyond Git, how comfortable are you with npm and the terminal?
+5. How much explanation do you want: just the results, a short gloss for new terms, or the reasoning behind each step?
+6. How do you like to work: pause after every step, pause after each finished piece, or work freely and stop only before a
+   commit?
+
+Derive the levels from the answers; ask a short follow-up only when an answer fits no level. The person can decline any
+question: its field stays out of the file, and its default applies: `some`, `comfortable`, `terms`, `slice`.
+
+## The file
+
+Show the profile below before writing it. The person can correct or remove any line, or reject the whole profile; on a
+rejection, save nothing and use the defaults for this session. After they confirm, write it and name its path so they can
+edit or delete it later:
+
+```markdown
+---
+name: <their name>
+frontend: none | some | seasoned
+tooling: new | comfortable
+explanation: results | terms | reasoning
+pace: step | slice | commit
+---
+
+## Background
+
+<their answer to question 2, in their words>
+
+## Notes
+
+- <lasting preferences learned later>
+```
+
+When the write fails, keep the answers for this session. When the person later states a lasting preference about how to work
+with them, such as a language, a term they want avoided, or a tool they already know, add it under `Notes` and tell them.
+When they ask to change their profile, run the interview again with the current answers as defaults.
+
+## Apply the profile
+
+The fields apply independently.
+
+- **Name**: address the person by name.
+- **Background**: explain by analogy to what they already know, such as a component compared to a class for a Java developer.
+- **Frontend `none` or `some`**: give a one-line gloss the first time a frontend term appears, such as component, prop,
+  design token, CSS layer, or Storybook. For `none`, also say what a finding means for the running app.
+- **Tooling `new`**: gloss tooling terms on first use, such as lockfile, dist-tag, prerelease, hook, harness, or the
+  `AGENTS.md` fence; say in one plain sentence what each command does before it runs, read-only checks included; and before
+  an approval question, say what yes changes and how to undo it.
+- **Explanation**: `results` adds nothing beyond what the experience levels call for; `terms` glosses every new term;
+  `reasoning` also says why each step happens, and after a report block, what happened and what comes next.
+- **Pace**: `step` ends the reply after each step or phase of the calling workflow and waits for a go-ahead; `slice` pauses
+  after each working piece; `commit` runs freely between the workflow's own approval points.
+
+Pace adds pauses on top of the calling workflow's approval gates and keeps every one of them. Put explanations around report
+blocks and approval questions, never inside them.

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

@@ -10,6 +10,8 @@ description:
 Use this skill for screen-level decisions. Verify component APIs with `imf-web-ui-components`; put code and styling rules in
 `imf-web-ui-conventions`.
 
+Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
+
 The identity index marks components as stable or experimental. Experimental components are usable, but prefer wrapping one
 when it is used across many call sites so API movement stays local.