@imfusion/web-ui 0.8.0 → 0.8.1-dev.17.gcbf0282e

package/dist/utils/break-hints.d.ts

@@ -0,0 +1,3 @@
+import { ReactNode } from 'react';
+/** Inserts `<wbr>` before each `@` and after each `.` of string children, so an email wraps at its seams. */
+export declare function withBreakHints(children: ReactNode): ReactNode;

package/dist/utils/status-glyphs.d.ts

@@ -0,0 +1,4 @@
+import { IconComponent } from '../icons';
+export type Status = "info" | "positive" | "warning" | "negative";
+/** The glyph each status shows wherever a component marks it with an icon. */
+export declare const statusGlyphs: Record<Status, IconComponent>;

package/docs/user-guide/AgentTooling.mdx

@@ -55,8 +55,12 @@ With the hooks installed, the agent is pointed at the router at the start of eve
 picks it up from the skill's description; invoke it by name when it does not.
 
 The router answers library questions from the packaged user guides and hands other tasks to a skill. Setup, audit, and UX
-work from `imf-web-ui-conventions`, a knowledge skill that holds the ImFusion frontend conventions. Solid outlines are the
-skills you run; dashed boxes are knowledge the agent reads:
+work from `imf-web-ui-conventions`, a knowledge skill that holds the ImFusion frontend conventions. Every skill
+you run first reads `imf-web-ui-user-profile`. On the first run it asks a few questions about your name, your
+background, your experience, how much explanation you want, and how you like to work, then saves the answers to
+`~/.config/imfusion/web-ui/consumer-profile.md` if you agree. Say "change my profile" to answer again.
+
+Solid outlines are the skills you run; dashed boxes are knowledge the agent reads:
 
 <ConsumerLlmFrameworkDiagram />
 
@@ -83,7 +87,8 @@ The hooks put the agent on the right skill at the right moment and ask it to ver
 ## Keeping it current
 
 Ask the agent to update the library, for example "Update @imfusion/web-ui". That runs `/imf-web-ui-update`, which installs
-the newer package and refreshes the skills, hook scripts, and registrations to match it.
+the newer package and refreshes the skills, hook scripts, and registrations to match it. It then reports what the new
+releases change for your code and offers `/imf-web-ui-audit full` as a wider check of the project.
 
 To do the same by hand, update the package, then run:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.8.0",
+  "version": "0.8.1-dev.17.gcbf0282e",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "homepage": "https://imfusion.com",

package/src/docgen/doc.gen.json

@@ -1,4 +1,91 @@
 {
+  "account-card": {
+    "root": {
+      "name": "AccountCard.Root",
+      "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",
+          "required": false,
+          "type": "\"default\" | \"oncolor\" | null",
+          "defaultValue": "default",
+          "description": ""
+        }
+      ]
+    },
+    "subComponents": [
+      {
+        "name": "AccountCard.Action",
+        "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": []
+      },
+      {
+        "name": "AccountCard.Avatar",
+        "description": "AccountCard.Avatar — a decorative `Avatar` in the card's context. Its children are the initials; without them it shows\na person glyph.",
+        "props": [
+          {
+            "name": "size",
+            "required": false,
+            "type": "\"sm\" | \"md\" | \"lg\" | null",
+            "defaultValue": "md",
+            "description": "The avatar size."
+          },
+          {
+            "name": "src",
+            "required": false,
+            "type": "string",
+            "defaultValue": null,
+            "description": "The person's photo. Until it loads, and when it fails, the initials or the person glyph show instead."
+          }
+        ]
+      },
+      {
+        "name": "AccountCard.Description",
+        "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 the email's local part until a name exists. Set large; text wraps before\nan `@` and after a dot.",
+        "props": []
+      }
+    ]
+  },
   "app-shell": {
     "root": {
       "name": "AppShell.Root",
@@ -62,6 +149,140 @@
       }
     ]
   },
+  "avatar": {
+    "root": {
+      "name": "Avatar.Root",
+      "description": "Avatar.Root — a round badge that stands for a person. Also called a profile picture or user badge.\n\nWithout `aria-label` or `aria-labelledby` it is decorative and hidden from assistive tech, for use next to a visible\nname. With a label it is announced as an image with that name.",
+      "props": [
+        {
+          "name": "className",
+          "required": false,
+          "type": "string | ((state: AvatarRootState) => string)",
+          "defaultValue": null,
+          "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
+        },
+        {
+          "name": "context",
+          "required": false,
+          "type": "\"default\" | \"oncolor\" | null",
+          "defaultValue": "default",
+          "description": ""
+        },
+        {
+          "name": "ref",
+          "required": false,
+          "type": "Ref<HTMLSpanElement>",
+          "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, AvatarRootState>",
+          "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": "size",
+          "required": false,
+          "type": "\"sm\" | \"md\" | \"lg\" | null",
+          "defaultValue": "md",
+          "description": ""
+        },
+        {
+          "name": "style",
+          "required": false,
+          "type": "| CSSProperties\n| ((state: AvatarRootState) => CSSProperties)",
+          "defaultValue": null,
+          "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
+        }
+      ]
+    },
+    "subComponents": [
+      {
+        "name": "Avatar.Fallback",
+        "description": "Avatar.Fallback — the initials the consumer passes, one or two letters. Without children it shows a person glyph.\nIt derives nothing from a name or email.",
+        "props": [
+          {
+            "name": "className",
+            "required": false,
+            "type": "string | ((state: AvatarFallbackState) => string)",
+            "defaultValue": null,
+            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
+          },
+          {
+            "name": "delay",
+            "required": false,
+            "type": "number",
+            "defaultValue": null,
+            "description": "How long to wait before showing the fallback. Specified in milliseconds."
+          },
+          {
+            "name": "ref",
+            "required": false,
+            "type": "Ref<HTMLSpanElement>",
+            "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, AvatarFallbackState>",
+            "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": "style",
+            "required": false,
+            "type": "| CSSProperties\n| ((state: AvatarFallbackState) => CSSProperties)",
+            "defaultValue": null,
+            "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
+          }
+        ]
+      },
+      {
+        "name": "Avatar.Image",
+        "description": "Avatar.Image — the person's photo, cropped to the circle. It shows once `src` has loaded; until then, and when it\nfails, `Avatar.Fallback` shows instead.",
+        "props": [
+          {
+            "name": "className",
+            "required": false,
+            "type": "string | ((state: AvatarImageState) => string)",
+            "defaultValue": null,
+            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
+          },
+          {
+            "name": "onLoadingStatusChange",
+            "required": false,
+            "type": "(status: ImageLoadingStatus) => void",
+            "defaultValue": null,
+            "description": "Callback fired when the loading status changes."
+          },
+          {
+            "name": "ref",
+            "required": false,
+            "type": "Ref<HTMLSpanElement>",
+            "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, AvatarImageState>",
+            "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": "style",
+            "required": false,
+            "type": "| CSSProperties\n| ((state: AvatarImageState) => CSSProperties)",
+            "defaultValue": null,
+            "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
+          }
+        ]
+      }
+    ]
+  },
   "button": {
     "root": {
       "name": "Button",
@@ -278,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": ""
+          }
+        ]
       }
     ]
   },
@@ -1742,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",
@@ -7596,6 +7830,33 @@
           }
         ]
       },
+      {
+        "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": ""
+          }
+        ]
+      },
       {
         "name": "Typo.H1",
         "description": "Typo.H1 — top-level page heading.",

package/src/llms/llms.gen.txt

@@ -9,11 +9,22 @@ reading the whole file. `further reading` links (when present) point at
 the upstream library's own docs for usage/anatomy/composition — not for
 props, which always live in the docgen file above.
 
+## AccountCard
+- category: Display, status: experimental
+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
 - category: Layout, status: stable
 Application layout shell for a header, sidebars, footer, and scrolling main area. Also called an app layout or dashboard shell; sizing is CSS-driven and sidebars can become sliding panels on small screens.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .app-shell (jq: jq '.app-shell' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
+## Avatar
+- category: Display, status: experimental
+Round badge that stands for a person, showing their photo, their initials, or a person glyph. Also called a profile picture or user badge; for a signed-in account row with a name, use AccountCard.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .avatar (jq: jq '.avatar' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/avatar.md
+
 ## Button
 - category: Buttons, status: stable
 Triggers an action such as submit, confirm, cancel, navigate, or delete. Also called a CTA or action button; variants and sizes communicate its importance.
@@ -27,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

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.