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

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

@@ -1,73 +1,49 @@
-# TypeScript & code style
+# TypeScript and code style
 
-Functional by default: pure functions over stateful classes, immutable data over in-place mutation, expressions over
-statements, side effects at the edges (network, DOM, store).
+Prefer pure functions, immutable values, and side effects at the edges.
 
 ## Types
 
-- No `any`. `unknown` at a boundary you can't type, narrowed before use.
-- Infer locals; annotate contracts. Exported functions get an explicit return type.
-- No temporal coupling — model the states instead of initialising `null` and filling in later.
-- Avoid `as`. Fix the type. The honest exception: an untyped third-party boundary, kept at the boundary.
-- Derive, don't duplicate:
+- Do not use `any`. Accept `unknown` at an untrusted boundary and narrow it.
+- Infer local values; give exported functions explicit return types.
+- Model states directly instead of filling a nullable value later.
+- Derive types from their source. Use `z.infer` for schemas and `React.ComponentProps` for Web UI components.
+- Avoid `as`. Keep an assertion only at an untyped third-party boundary where it is the honest boundary.
+- Use one or two positional arguments. At three or more, pass a named object.
 
 ```ts
 const sizes = ["sm", "md", "lg"] as const;
 type Size = (typeof sizes)[number];
 
-const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler breaks if `sizes` changes
+const labels: Record<Size, string> = {
+  sm: "S",
+  md: "M",
+  lg: "L"
+};
 ```
 
-- Same rule across boundaries: library props via `React.ComponentProps<typeof Button>`
-  ([library-boundary.md](library-boundary.md)), untrusted data via a runtime schema and `z.infer`
-  ([validation.md](validation.md)).
-- Function signatures: 1–2 positional arguments; at 3+, one destructured object.
+## Immutability and expressions
 
-## Immutability & expressions
+Use `map`, `filter`, `find`, `some`, and `flatMap` for ordinary collection work. Create new values instead of mutating the
+input. Use `toSorted` and `toReversed` instead of their mutating counterparts.
 
-- Array methods before loops — `map`, `filter`, `find`, `some`, `flatMap` name what they do:
-
-```ts
-const activeNames = users.filter(u => u.isActive).map(u => u.name);
-```
-
-- Produce new values: spreads and `structuredClone` over in-place edits, `toSorted`/`toReversed` over `sort`/`reverse` (which
-  mutate their receiver).
-- Allowed exceptions: a genuine early exit (`for` + `break`), a measured hot loop.
-- Keep chains flat: 3–4 steps read well; longer wants named intermediates, and a `reduce` doing four things wants to be a
-  loop.
+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.
 
 ## Naming
 
-- Say what it is, not what it's made of: `useUserQuery`, not `useUserHook`; `retryDelay`, not `num`.
-- Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`.
-- Handlers: `onX` as props, `handleX` as implementations.
-- Match the vocabulary the product and the API already use — no synonyms for terms the backend named.
-- Keep the object a hook or query returns as a namespace instead of destructuring it, and drop the `Query`/`Mutation` suffix
-  from the local binding — the binding reads as the domain name, and every field access shows where it came from:
+Name what a value is, not how it is built. Booleans read as assertions (`isOpen`, `hasAccess`, `canSubmit`). Props use `onX`;
+component implementations use `handleX`.
+
+Keep a hook or query result as a namespace and name the local after its domain:
 
 ```tsx
-const search = Route.useSearch(); // not const { page, filter } = ...
-const user = useSuspenseQuery(context.api.user.getDetails()); // not const { data } = ...
-const updateUser = useMutation(context.api.user.update());
+const search = Route.useSearch();
+const user = useSuspenseQuery(context.api.user.getDetails());
 
 search.page;
 user.data.name;
-updateUser.mutate(values);
-updateUser.isPending;
 ```
 
-- Exception: a `useEffect` dependency array needs a stable primitive, since deps compare by identity — destructure the
-  primitive out first rather than listing the object or a deep path into it:
-
-```tsx
-const user = useSuspenseQuery(context.api.auth.getUser());
-const { name } = user.data; // destructure for the dep array
-
-useEffect(
-  function syncDocumentTitle() {
-    document.title = name;
-  },
-  [name]
-);
-```
+Destructure a primitive only when a stable value is needed, such as an effect dependency. Match existing product and API
+vocabulary instead of inventing synonyms.

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

@@ -1,20 +1,22 @@
 # Validation
 
-Validate where data crosses from untrusted representation into frontend-owned values; the schema is the single source of
-truth for runtime check and TypeScript type.
+Validate data when it crosses into frontend-owned code. Use the schema as both the runtime check and the TypeScript source.
 
 ## Boundaries
 
-- Validate once, at the edge: network responses on entry; URL path and search params before business logic; persisted browser
-  data on read; user input becoming a submitted domain or request value.
-- Inside the boundary: parsed values only, no repeated defensive shape checks.
-- Outgoing requests built from already parsed domain values are serialized, not re-validated.
-- A typed client's handwritten generic is not validation — it only asserts a type onto an untrusted response.
+Validate once at the edge:
+
+- network responses on entry;
+- URL path and search values;
+- persisted browser data when read;
+- user input when it becomes a submitted domain or request value.
+
+After the boundary, use parsed values. A generic on a typed client only tells TypeScript what you hope the response looks
+like; it does not validate it.
 
 ## Schema first, type derived
 
-- Zod schema, type via `z.infer`; never a handwritten type beside its schema.
-- Same rule for request and response shapes the frontend owns or consumes at runtime.
+Use a Zod schema and derive the type:
 
 ```ts
 import { z } from "zod";
@@ -27,17 +29,13 @@ export const userSchema = z.object({
 export type User = z.infer<typeof userSchema>;
 ```
 
+Apply the same rule to request and response shapes the frontend owns at runtime.
+
 ## TanStack Router search params
 
-- `validateSearch` takes a Zod v4 schema directly (TanStack Router v1) — no adapter or parsing wrapper.
-- `Route.useSearch()` infers its type from `validateSearch`.
-- `.catch()`: malformed URL input falls back without interrupting navigation.
-- `.default()`: only for missing values; malformed values still follow the route's validation error path.
+Pass a Zod v4 schema to `validateSearch`. Route search types then come from that schema:
 
 ```tsx
-import { createFileRoute } from "@tanstack/react-router";
-import { z } from "zod";
-
 const searchSchema = z.object({
   page: z.number().int().positive().catch(1),
   filter: z.string().catch("")
@@ -47,16 +45,12 @@ export const Route = createFileRoute("/users")({
   validateSearch: searchSchema,
   component: Users
 });
-
-function Users() {
-  const search = Route.useSearch(); // inferred: z.infer<typeof searchSchema>
-  return <UserList page={search.page} filter={search.filter} />;
-}
 ```
 
+Use `.catch()` for malformed values that can safely fall back. Use `.default()` only for missing values.
+
 ## Failure handling
 
-- `schema.parse`: invalid data is a contract failure on the normal error path (malformed backend response → route error
-  boundary).
-- `schema.safeParse`: failure is expected and the caller handles the issues (submitted user input).
-- Transforms and coercion live in the boundary schema — never scatter trimming, number conversion, or defaulting downstream.
+- Use `parse` when invalid data is a contract failure that should reach the normal error boundary.
+- Use `safeParse` when failure is expected and the caller can show a validation message.
+- Keep trimming, coercion, transforms, and defaults in the boundary schema.

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

@@ -1,87 +1,66 @@
 ---
 name: imf-web-ui-setup
 description:
-  "Plan and, after explicit approval, bootstrap an ImFusion frontend against the conventions baseline: library setup,
-  tooling, git, npm project, authentication, project structure, docs structure, data, testing, or agent tooling. Inspect
-  statically first and write only the approved files. Use imf-web-ui-audit for read-only health checks or topics with no
-  setup action."
+  "Plan and, after explicit approval, bootstrap a consumer project that uses @imfusion/web-ui. Use this whenever a project
+  needs library wiring, tooling, git, npm, authentication, structure, data, testing, docs, or agent tooling. Inspect first,
+  propose concrete files, and write only what the user approves. Use imf-web-ui-audit for read-only checks."
 argument-hint: "[full|library-setup|tooling|git|npm-project|authentication|project-structure|docs-structure|data|testing|agent-tooling]"
 allowed-tools: Read Glob Grep Write
 ---
 
-# imf-web-ui-setup
+# Set up a consumer project
 
-You are the frontend bootstrap planner. Inspect the repository statically, read the applicable `imf-web-ui-conventions`
-topics, and prepare a complete proposal for every file you would create or change. The project wins where it already has a
-working convention. This skill is plan-first: enter the host's plan mode before presenting the proposal, and do not create a
-report file as a substitute for the host plan.
+Plan the missing pieces of an ImFusion frontend. The existing project wins; this skill fills gaps instead of reshaping
+working choices.
 
 ## Workflow
 
-1. Resolve the argument, not the prose. Bare means `full`; a topic argument selects one supported setup topic. A prompt that
-   merely _mentions_ one area ("wire up the tooling", "get the project set up") is still a `full` run — the words describe a
-   starting point, not a scope that excludes the rest. For a greenfield `full` run the application boundary (router, route
-   groups, current-user query, AppShell) is part of the deliverable even when the prompt never names it; propose it and let
-   the human remove it, never silently defer it as "out of scope." For an unsupported topic argument, list the available
-   setup topics and point the human to `imf-web-ui-audit` for a read-only report.
-2. Enter the host's plan mode. If it is not already active, use the host plan-mode control before inspecting and planning.
+1. Resolve the argument. Bare means `full`. A named topic limits the assessment to that topic. If the argument is unknown,
+   list the supported topics and point to `imf-web-ui-audit`.
+2. Enter the host's plan mode before inspecting or proposing changes.
 3. Read the selected convention topics and inspect the repository with `Read`, `Glob`, and `Grep` only.
-4. Build the complete proposal in the host plan from the shared report contract at
-   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md). Include the concrete
-   content of every file the approved setup would create or change, with repository evidence for each decision.
-5. A greenfield `full` setup proposes the whole starter skeleton, not just tooling — tooling without the application boundary
-   is an unfinished setup. Include, as concrete files in the plan:
-   - the TanStack Router **package added to `package.json`** (with its router devtools as a dev dependency), not just
-     imported — code that imports an uninstalled package is an incomplete setup
-     ([project-structure.md](../imf-web-ui-conventions/topics/project-structure.md));
-   - pathless `_public/` and `_app/` route groups behind one server-backed current-user boundary
-     ([authentication.md](../imf-web-ui-conventions/topics/authentication.md));
-   - the minimal branded `AppShell` in `_app/` by default — omit the shell only when the human explicitly says the product
-     has no persistent authenticated navigation (ask first), but keep the `_app/` boundary either way;
-   - a per-topic `api/` folder for any data the first screen shows, never an inline fixture in the component
-     ([data.md](../imf-web-ui-conventions/topics/data.md)).
+4. Put a complete proposal in the host plan, using [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md).
+   Name every file to create or change, include its intended content, and cite the repository evidence behind the choice.
+5. Wait for explicit approval. After approval, write only the listed files.
+6. Run `imf-web-ui-audit full` as a follow-up and review its findings before calling setup complete.
 
-   The plan documents this starter shape as concrete file content; it does not copy a full external starter template.
-   Existing projects keep their working choices — propose only the gaps.
+## Greenfield `full` setup
 
-6. Keep the plan as the approval gate. After the host approves and exits plan mode, write only the listed files. Complete any
-   immediately requested bootstrap work covered by that approved plan, then invoke `imf-web-ui-audit full` as a verification
-   step and review the findings it reports back before declaring the setup complete. The audit stays out of plan mode here —
-   the human has just left it to let this work happen.
+Include these pieces unless the existing project already has them or the user removes them from the plan:
 
-Installer and hook runs stay with the human: an `agent-tooling` proposal lists the `npx web-ui-install` commands as human
-steps, applies the judgment from the topic (read existing registrations first, never stack a hook on a covered event), and
-includes the topic's Codex trust follow-up whenever hooks are part of the plan.
+- `@tanstack/react-router` and its router devtools in `package.json`;
+- pathless `_public/` and `_app/` route groups;
+- one server-backed current-user query at the route boundary;
+- a minimal `AppShell` in `_app/`, unless the user says the product has no persistent authenticated navigation;
+- an API topic folder for data shown by the first screen;
+- the root provider and library wiring.
 
-## Checklist
+The plan describes the exact starter files. It does not copy a generic starter project.
 
-The post-implementation audit uses the shared
-[convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md) to verify the complete baseline, not
-only the setup topic selected at the start.
+## Installer steps
 
-## Safety
+For `agent-tooling`, list the `npx web-ui-install` commands as steps for the human. Read existing registrations first and do
+not stack a hook on an event the project already covers. Include the Codex trust review when hooks are part of the plan.
 
-Use only static inspection: `Read`, `Glob`, and `Grep`. Do not use a shell or invoke Node, npm, npx, package scripts, hooks,
-config imports, linters, tests, builds, Git commands, project binaries, installers, or package managers. Read config as text
-and report runtime or machine-local state that cannot be established statically as unverified. After approval, `Write` is
-limited to the files listed in the approved report; anything needing execution goes in the plan for the human.
+## Safety
 
-## Setup topics
+During inspection use only `Read`, `Glob`, and `Grep`. Do not run shells, Git, Node, npm, npx, installers, builds, tests, or
+local config. Report anything that needs runtime state as unverified. After approval, `Write` is limited to the approved file
+list; put commands in the plan for the human to run.
 
-`full` covers every topic below. A one-topic run assesses only that topic.
+## Topics
 
-| Topic               | Assess and plan                                                                |
-| ------------------- | ------------------------------------------------------------------------------ |
-| `library-setup`     | styles import, `WebUIProvider`, and library package wiring                     |
-| `tooling`           | dependency selection, devtools, Prettier, ESLint, TypeScript, and verification |
-| `git`               | tracked hooks, verification scopes, and staleness wiring                       |
-| `npm-project`       | package metadata, scripts, pins, npm, and Node configuration                   |
-| `authentication`    | current-user query, public/app guards, login, and logout                       |
-| `project-structure` | source tree, route groups, optional app shell, naming, and placement           |
-| `docs-structure`    | README, AGENTS, docs index, and content boundaries                             |
-| `data`              | transport, schemas, query/mutation options, keys, and invalidation             |
-| `testing`           | test boundaries and verification coverage                                      |
-| `agent-tooling`     | vendored skills, AGENTS fence, lifecycle hooks, registrations, and staleness   |
+| Topic               | Covers                                                                   |
+| ------------------- | ------------------------------------------------------------------------ |
+| `library-setup`     | Stylesheet, `WebUIProvider`, and package wiring.                         |
+| `tooling`           | Dependencies, devtools, formatter, linter, TypeScript, and verification. |
+| `git`               | Hooks, verification scopes, and staleness checks.                        |
+| `npm-project`       | Manifest, scripts, pins, npm, and Node.                                  |
+| `authentication`    | Current-user query, route groups, login, and logout.                     |
+| `project-structure` | Source tree, route placement, naming, and imports.                       |
+| `docs-structure`    | README, AGENTS, docs index, and content boundaries.                      |
+| `data`              | Transport, schemas, query/mutation options, keys, and invalidation.      |
+| `testing`           | Test boundaries and coverage.                                            |
+| `agent-tooling`     | Vendored skills, hooks, registrations, and Codex trust.                  |
 
-Setup has no file-creation action for `react`, `typescript`, `class-names`, `validation`, `components`, `styling`, `assets`,
-`library-boundary`, or `tokens`; select those in `imf-web-ui-audit`.
+The other convention topics are read by `imf-web-ui-audit` when a project needs assessment rather than setup.

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

@@ -1,157 +1,91 @@
 ---
 name: imf-web-ui-update
 description:
-  "Update @imfusion/web-ui in a consumer repository: refresh the package, vendored skills, and lifecycle hooks, verify the
-  base update, then audit and optionally migrate affected or custom consumer components in a separate approved commit."
+  "Update @imfusion/web-ui in a consumer repository. Use this whenever a consumer needs a newer package, installed skills, or
+  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
 ---
 
-# imf-web-ui-update
-
-Update a repository that consumes `@imfusion/web-ui`. Preserve existing project choices and user work. The workflow has two
-commits: the dependency/tooling update first, then an optional consumer migration. Never commit without a fresh explicit
-approval.
-
-## Rules
-
-- Work from the frontend package root. In a monorepo, inspect package manifests and `git worktree list` first, then choose
-  the frontend package in the active worktree that uses web-ui. Read repository and component instructions before changing
-  files.
-- This workflow uses npm. `package-lock.json` is the expected lockfile. Another lockfile is a conflict: stop and ask.
-- A dry run is read-only. Do not install, run the installer, format, stage, commit, reset, or clean. Report what would run.
-- Record the initial `git status --short`. Existing changes are held back, never staged or overwritten.
-- A dirty file that the workflow needs to modify is a conflict. Stop and report it. This includes package files, installed
-  skill directories, the `AGENTS.md` installer fence, hook files, and hook settings.
-- Do not hand-edit installer-owned skills, the `AGENTS.md` fenced block, or installer-owned hook files.
-- Keep the base update and consumer migration in separate commits. Do not begin the migration audit until the base update
-  commit is complete.
-- Treat the installed package version before the update as the comparison baseline. There is no assumed changelog.
-- A migration candidate is a custom consumer implementation whose behavior overlaps with a current web-ui component, or an
-  existing web-ui usage affected by changed types or documented API. Do not infer a replacement from a name alone; inspect
-  the implementation and the current component documentation/types.
+# Update Web UI
+
+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.
 
 ## Preflight
 
-1. Select the frontend package in the active worktree and read its instructions, `package.json`, and `package-lock.json`.
-2. Check whether `@imfusion/web-ui` is already declared and record its installed/version-marker version.
-3. Record the worktree status and identify files the update would touch.
-4. Inspect `.agents/skills/`, `.claude/skills/`, the `AGENTS.md` fence, `.claude/settings.json`, and `.agents/hooks/`.
-5. Check for another npm process. Stop on any conflict or ambiguous target.
+1. Work from the frontend package root. In a monorepo, find the package that owns the Web UI dependency.
+2. Read its `package.json`, lockfile, and repository instructions. npm with `package-lock.json` is the expected setup; stop
+   if another lockfile is the active one.
+3. Record `git status --short`, the installed Web UI version, the installed skill targets, hooks, registrations, and
+   `AGENTS.md` fence.
+4. Check for another npm process and stop on a conflict. A dirty file this workflow needs is also a conflict. Do not 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.
 
-## Base update
+## Update the base
 
-In a non-dry run, update the dependency:
+Run from the consumer package root:
 
 ```sh
 npm install @imfusion/web-ui
-```
-
-Pass an explicit version only when the user supplied one. Do not use `--force` or `--legacy-peer-deps` to make installation
-pass. Stop on install failure.
-
-Then refresh the existing web-ui skill target and lifecycle hooks:
-
-```sh
 npx web-ui-install
 npx web-ui-install --hooks
 ```
 
-Run these from the consumer package root, the directory holding the `node_modules` that the dependency install just wrote.
-`npx` resolves `web-ui-install` from the installed `@imfusion/web-ui` there; from any other directory it cannot find the
-binary. Preserve the existing target (`.agents`, `.claude`, or both); do not silently choose a new one.
-
-Always run both installer commands after the package update. Skills and installer-owned hook scripts may have changed even
-when their existing registrations already cover session start, subagent start, prompt submit, and the stop gate. The hook
-installer refreshes those scripts wholesale, prunes retired scripts and their registrations, and merges registrations
-idempotently into both host files (`.claude/settings.json` and `.codex/hooks.json`). Stop on malformed settings or installer
-conflicts.
-
-## Verification
-
-After each mutating command, compare `git status --short` with the preflight snapshot.
+Use `npm install @imfusion/web-ui@<version>` when the user supplied an explicit version. Stop on install failure. Preserve
+the installer's existing target. Do not use `--force` or `--legacy-peer-deps`.
 
-Classify paths as:
+The installer owns the vendored skills, its `AGENTS.md` fence, and hook scripts. Run both installer commands after the
+package update even when the existing registrations look complete: they refresh scripts, prune retired registrations, and
+merge installer-owned entries idempotently into `.claude/settings.json` and `.codex/hooks.json`. Stop on malformed settings
+or installer conflicts. Read existing host registrations first and do not stack an event the project already covers.
 
-- **Update-owned:** package files and installer-owned files changed by this workflow.
-- **Held back:** pre-existing user changes, excluded from the commit.
-- **Conflict:** an overlapping pre-existing change, ambiguous target, or unexpected changed path.
+## Verify the base update
 
-On conflict, stop. Never use `git restore`, `git reset`, `git clean`, or broad staging to hide it.
+After every mutating command, compare the status with the preflight snapshot. Stop on an unexpected path or overlapping
+change.
 
-Run the frontend package's documented full verification after the base update. Read its `package.json` scripts and choose
-commands that cover typechecking, linting, tests, and building. Prefer one documented aggregate `verify`/`check` script when
-it covers those responsibilities; otherwise run the documented non-watch scripts for the responsibilities that exist. Do not
-invent script names or run watch/dev scripts. A type or build failure is a base-update conflict to resolve before the base
-commit, not a migration finding to defer.
+Run the consumer's documented full verification. Read its scripts first; prefer an aggregate check, otherwise run the
+non-watch format, lint, typecheck, test, and build commands that exist.
 
-Verify the dependency/lockfile, current skill markers, the `AGENTS.md` fence, hook coverage, and the final path list. In
-dry-run mode, say that mutation-dependent checks were skipped.
+Check the dependency and lockfile, skill markers, `AGENTS.md` fence, hook registrations, and final update-owned path list.
 
-## Base update report and approval
-
-Before the base commit, show this concise report:
+Report before the first commit:
 
 ```text
 @imfusion/web-ui update report
-Package      : <old> -> <new> / would update
+Package      : <old> -> <new>
 Skills       : <status>
 Hooks        : <status>
 Verification : <status>
 Update files : <paths>
 Held back    : <paths or none>
 Conflicts    : <paths or none>
-Commit       : <imperative message or not proposed>
+Commit       : <message or not proposed>
 ```
 
-Normal mode: ask exactly, **“Approve these update-owned changes and commit them?”** Do not commit without an affirmative
-answer. If denied, leave the changes uncommitted.
-
-Dry-run mode: state **“Dry run complete; no changes or commit were made.”** Do not mutate or ask for commit approval.
-
-## Consumer migration audit
-
-Begin this phase only after the approved base update has been committed. Record the old and new package versions from the
-pre-update and current manifests/lockfile. Use the current package's exported types, generated documentation, and component
-examples as the source of truth. Use the old version's package metadata or repository history when available to identify what
-changed; do not pretend a changelog exists.
-
-Run the same documented full verification again after the base commit. Separate findings into:
-
-- **Compatibility fixes:** existing web-ui imports, props, or usage patterns that no longer typecheck, build, lint, or pass
-  tests.
-- **Changed component usages:** existing components whose current API, behavior, or documented contract changed between the
-  two versions and may need a consumer update, even when the typecheck passes.
-- **Replacement candidates:** custom consumer components, wrappers, or field implementations that overlap with a component
-  now exported by `@imfusion/web-ui`. Inspect their code, styles, and call sites before suggesting a replacement. Include the
-  current custom implementation, the proposed web-ui component, the relevant API/type evidence, and any behavior or styling
-  that still needs to be preserved.
-
-Report these findings separately from the base update. Ask whether to apply the proposed migration. If the user declines,
-leave the consumer code unchanged. If accepted, make only the approved migration changes, run the documented full
-verification again, and show a second report with the migration paths, held-back paths, conflicts, and verification result.
-
-If no findings exist, report that the installed update has no detected compatibility fixes, changed usages, or replacement
-candidates. Do not create an empty migration commit.
+Ask: **Approve these update-owned changes and commit them?** Stage only approved update paths and follow the repository's
+commit workflow.
 
-Whatever the migration outcome, close the phase by asking whether to run `imf-web-ui-audit full`: an update can shift the
-baseline (new components, hooks, conventions), and the audit shows where the project now stands against it. Run it only on an
-explicit yes.
+## Audit the consumer migration
 
-## Migration approval
+Start this phase only after the base update commit exists. Use the pre-update package metadata as the comparison baseline;
+don't assume a changelog exists. Compare the old and new package metadata, current generated docs, types, and examples. Run
+the full verification again.
 
-Ask exactly, **“Approve these consumer migration changes and commit them separately?”** Do not commit without an affirmative
-answer. The migration approval is not implied by approval of the base update.
+Report separately:
 
-## Commit
+- compatibility fixes required by changed imports or types;
+- existing uses affected by a changed API or documented behavior;
+- custom components that overlap with a current Web UI primitive, with evidence and any behavior to preserve.
 
-For the base update, after approval:
+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.
 
-1. Recheck status and exclude held-back paths.
-2. Stage base update-owned paths selectively. Never use `git add .` or `git add -A`.
-3. Run the repository's commit workflow if it has one, including its required verification and documentation audit. Otherwise
-   run documented verification and follow the repository's commit convention.
-4. Commit with a concise imperative message and confirm the commit and final status.
+Ask whether to run `imf-web-ui-audit full`. Run it only after an explicit yes.
 
-For an approved migration, repeat the same selective staging and documented commit workflow with a separate imperative
-message. Never bypass hooks or amend an unrelated commit after a hook failure.
+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.