@imfusion/web-ui 0.8.1-dev.2.g74f81c31 → 0.8.1-dev.20.g50b02289

package/src/docgen/doc.gen.json

@@ -2,7 +2,7 @@
   "account-card": {
     "root": {
       "name": "AccountCard.Root",
-      "description": "AccountCard.Root — the link to the signed-in person's account, holding `AccountCard.Avatar`, `AccountCard.Title`, and\n`AccountCard.Description`. Pass a router link through `render`. `aria-current=\"page\"` marks it current with a tint and\nan inset rule. Its accessible name is the title and description; the avatar stays decorative.\n\nPlace `AccountCard.Action` beside the root, not inside it: a link cannot contain a button.",
+      "description": "AccountCard.Root — the signed-in person's card: `AccountCard.Link` and, in its top row, `AccountCard.Action`. The\naction sits beside the link, not inside it, since a link cannot contain a button.",
       "props": [
         {
           "name": "context",
@@ -10,27 +10,13 @@
           "type": "\"default\" | \"oncolor\" | null",
           "defaultValue": "default",
           "description": ""
-        },
-        {
-          "name": "ref",
-          "required": false,
-          "type": "Ref<HTMLAnchorElement>",
-          "defaultValue": null,
-          "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
-        },
-        {
-          "name": "render",
-          "required": false,
-          "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, {}>",
-          "defaultValue": null,
-          "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
         }
       ]
     },
     "subComponents": [
       {
         "name": "AccountCard.Action",
-        "description": "AccountCard.Action — a trailing slot beside `AccountCard.Root`, such as a ghost icon `Button` that logs out. The\nbutton carries its own `aria-label` and its own `context`.",
+        "description": "AccountCard.Action — a slot in the card's top row, beside the link, such as a ghost icon `Button` that logs out. The\nbutton carries its own `aria-label` and its own `context`.",
         "props": []
       },
       {
@@ -55,12 +41,47 @@
       },
       {
         "name": "AccountCard.Description",
-        "description": "AccountCard.Description — a second line such as organization and role. Truncates to one line.",
+        "description": "AccountCard.Description — the organization, under a rule at the foot of the card.",
+        "props": []
+      },
+      {
+        "name": "AccountCard.Group",
+        "description": "AccountCard.Group — a list of cards, such as accounts to switch between. Inside it a link with `aria-current=\"page\"`\nshows as current; a standalone card is always the signed-in account and shows no current state.",
+        "props": []
+      },
+      {
+        "name": "AccountCard.Link",
+        "description": "AccountCard.Link — the link to the account, holding `AccountCard.Avatar`, `AccountCard.Title`,\n`AccountCard.Subtitle`, `AccountCard.Description`, and `AccountCard.Role`. Pass a router link through `render`. Its\naccessible name is its text; the avatar stays decorative.",
+        "props": [
+          {
+            "name": "ref",
+            "required": false,
+            "type": "Ref<HTMLAnchorElement>",
+            "defaultValue": null,
+            "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
+          },
+          {
+            "name": "render",
+            "required": false,
+            "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, {}>",
+            "defaultValue": null,
+            "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+          }
+        ]
+      },
+      {
+        "name": "AccountCard.Role",
+        "description": "AccountCard.Role — a mono uppercase label beside the description, such as the person's role.",
+        "props": []
+      },
+      {
+        "name": "AccountCard.Subtitle",
+        "description": "AccountCard.Subtitle — the quiet line under the title: the email's domain, or the whole email once the title is a\nname. Text wraps before an `@` and after a dot.",
         "props": []
       },
       {
         "name": "AccountCard.Title",
-        "description": "AccountCard.Title — the account's name, or its email until a name exists. Truncates to one line.",
+        "description": "AccountCard.Title — the account's name, or the email's local part until a name exists. Set large; text wraps before\nan `@` and after a dot.",
         "props": []
       }
     ]
@@ -478,6 +499,19 @@
             "description": "Width divided by height, or \"auto\" to use the image's intrinsic ratio."
           }
         ]
+      },
+      {
+        "name": "Card.Status",
+        "description": "Card.Status — a tinted slot that marks the card's status with the variant's glyph. Pass\nchildren to replace the glyph. Like `Card.Image`, place it first among the slots: a column\nbeside the body in a horizontal card, a band above it in a vertical one. Decorative\n(`aria-hidden`); the card's text carries the status.",
+        "props": [
+          {
+            "name": "variant",
+            "required": false,
+            "type": "| \"info\"\n| \"positive\"\n| \"warning\"\n| \"negative\"\n| null",
+            "defaultValue": "info",
+            "description": ""
+          }
+        ]
       }
     ]
   },
@@ -1942,7 +1976,7 @@
       },
       {
         "name": "Field.Error",
-        "description": "Field.Error — an inline validation message shown when its match condition fails.",
+        "description": "Field.Error — an inline validation message shown when its match condition fails.\nIt announces itself with `role=\"alert\"`; pass another `role` to quiet it.",
         "props": [
           {
             "name": "className",
@@ -5535,7 +5569,7 @@
   "slider": {
     "root": {
       "name": "Slider.Root",
-      "description": "Slider.Root — value selector along a continuous or stepped track.",
+      "description": "Slider.Root — value selector along a continuous or stepped track.\n\n`variant=\"position\"` draws a scrollbar-like trough and bar thumb for picking one position\nbetween `min` and `max`, such as a slice or frame; `onValueChange` reports the position.",
       "props": [
         {
           "name": "className",
@@ -5683,6 +5717,13 @@
           "type": "number | readonly number[]",
           "defaultValue": null,
           "description": "The value of the slider.\nFor ranged sliders, provide an array with two values."
+        },
+        {
+          "name": "variant",
+          "required": false,
+          "type": "\"default\" | \"position\" | null",
+          "defaultValue": "default",
+          "description": ""
         }
       ]
     },
@@ -7766,6 +7807,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "support",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       },
@@ -7793,6 +7841,40 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "main",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
+          }
+        ]
+      },
+      {
+        "name": "Typo.Eyebrow",
+        "description": "Typo.Eyebrow — short uppercase label above a heading. Also called a kicker or overline.",
+        "props": [
+          {
+            "name": "ref",
+            "required": false,
+            "type": "Ref<HTMLHeadingElement>",
+            "defaultValue": null,
+            "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
+          },
+          {
+            "name": "render",
+            "required": false,
+            "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, {}>",
+            "defaultValue": null,
+            "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+          },
+          {
+            "name": "variant",
+            "required": false,
+            "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
+            "defaultValue": "support",
+            "description": ""
           }
         ]
       },
@@ -7976,6 +8058,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "oncolor",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       },
@@ -8037,6 +8126,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "main",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       },
@@ -8071,6 +8167,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "primary",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       },
@@ -8098,6 +8201,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "main",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       },
@@ -8125,6 +8235,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "main",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       },
@@ -8152,6 +8269,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "minor",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       },
@@ -8179,6 +8303,13 @@
             "type": "| \"main\"\n| \"support\"\n| \"minor\"\n| \"brand\"\n| \"primary\"\n| \"negative\"\n| \"positive\"\n| \"warning\"\n| \"info\"\n| \"oncolor\"\n| \"accent-1\"\n| \"accent-2\"\n| \"accent-3\"\n| null",
             "defaultValue": "main",
             "description": ""
+          },
+          {
+            "name": "weight",
+            "required": false,
+            "type": "\"strong\" | \"regular\" | \"medium\"",
+            "defaultValue": null,
+            "description": "Font weight. Omit to keep the member's default; `medium` firms up short body text on cards."
           }
         ]
       }
@@ -8288,6 +8419,43 @@
       }
     ]
   },
+  "frame-selection": {
+    "root": {
+      "name": "FrameSelection",
+      "description": "FrameSelection - a position slider bound to the focused frame of the multi-frame image sets in `data`.\nEvery matching image set follows the slider, and a `{focus} | {count}` readout sits beside it.\nRenders nothing when `data` holds no multi-frame image set.\n\nMust render inside an `ImFusionProvider`.",
+      "props": [
+        {
+          "name": "data",
+          "required": true,
+          "type": "HandleArray<Data>",
+          "defaultValue": null,
+          "description": "Datasets to scan, for example from `useVisibleData()`. Non-image data, single-frame image sets, and image sets whose\nframe count differs from the first multi-frame set are ignored."
+        },
+        {
+          "name": "disabled",
+          "required": false,
+          "type": "boolean",
+          "defaultValue": "false",
+          "description": "Whether the slider ignores user interaction."
+        },
+        {
+          "name": "label",
+          "required": false,
+          "type": "string",
+          "defaultValue": "Frame",
+          "description": "Accessible name of the slider thumb."
+        },
+        {
+          "name": "orientation",
+          "required": false,
+          "type": "\"horizontal\" | \"vertical\"",
+          "defaultValue": "horizontal",
+          "description": "Direction of the slider; the vertical layout stacks the readout under it."
+        }
+      ]
+    },
+    "subComponents": []
+  },
   "image-display-options": {
     "root": {
       "name": "ImageDisplayOptions",

package/src/llms/llms.gen.txt

@@ -11,7 +11,7 @@ props, which always live in the docgen file above.
 
 ## AccountCard
 - category: Display, status: experimental
-Link to the signed-in person's account, with avatar, name or email, and a second line such as organization and role. Also called an ID card or user row; for a bare person badge, use Avatar.
+Card linking to the signed-in person's account: avatar, a large name or email, a quiet line under it, and organization and role at its foot, with a trailing action such as Log out. Also called an ID card or user row; for a bare person badge, use Avatar.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .account-card (jq: jq '.account-card' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## AppShell
@@ -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,6 +96,12 @@ 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.
@@ -160,7 +166,7 @@ Line that divides content horizontally or vertically. Also called a divider or r
 
 ## 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,

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

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

@@ -50,6 +50,7 @@ sections one to one — change a topic's sections and this file follows in the s
 
 - [ ] Types
 - [ ] Immutability & expressions
+- [ ] Functions
 - [ ] Naming
 
 ## Styling — `styling`

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/typescript.md

@@ -30,6 +30,20 @@ input. Use `toSorted` and `toReversed` instead of their mutating counterparts.
 A loop is fine when it has a real early exit or measured hot-path benefit. A long chain or a `reduce` with several jobs wants
 named intermediate values.
 
+## Functions
+
+Declare a named function with `function`, including a local helper inside a component. A callback passed inline as a prop or
+argument stays an arrow.
+
+```tsx
+function resetCaptcha() {
+  captcha.current?.reset();
+}
+
+<Button onClick={() => setOpen(true)}>Open</Button>;
+items.map(item => item.id);
+```
+
 ## Naming
 
 Name what a value is, not how it is built. Booleans read as assertions (`isOpen`, `hasAccess`, `canSubmit`). Props use `onX`;

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
@@ -119,7 +149,8 @@ releases read, then report separately:
 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.