@imfusion/web-ui 0.5.1-dev.48.g27701f90 → 0.5.1-dev.5.gb4de52d7

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

@@ -1,109 +0,0 @@
-# React
-
-House defaults for React around `@imfusion/web-ui`. Links are for you, the agent — authoritative when a case here is
-ambiguous; hand them to the human only if asked.
-
-## Composition: pages (smart containers), partials, dumb components
-
-The architecture principle, top-down — rooted in Dan Abramov's
-[Presentational and Container Components](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) and
-[Thinking in React](https://react.dev/learn/thinking-in-react). Styling lives exclusively in dumb and layout components,
-nowhere else:
-
-- **Pages are the smart containers.** The route component in `routes/` is the container — don't go looking for `*Container`
-  files. It owns how things _work_: loaders prefetch, the component fetches data, orchestrates, composes partials and passes
-  data down. Zero styling — a page wanting CSS (two panels side by side) means a layout component, not an inline style. A
-  standalone container earns its place only off-route (a modal fetching its own data).
-- **Partials** are pure composition: reusable units of dumb and layout components with light logic and zero styling of their
-  own, extracted because they read as a unit. A partial with a CSS file is a red flag — the styled element wants to be its
-  own dumb component, or the wrapper wants to be a layout component.
-- **Layout components** own _arrangement_ and nothing else: `Stack`-/`Row`-based wrappers with token gaps, a page grid, a
-  section frame.
-- **Dumb components** own how things _look_: style and compose library primitives, take plain data and callbacks as props; no
-  fetching, routing, or business logic. All non-layout styling lives here and only here — logic-free dumb components (the
-  `@imfusion/web-ui` layer) keep screens restylable, testable with plain props, resilient to library updates.
-- Wrapping library primitives in app-level dumb components: [library-boundary.md](library-boundary.md).
-
-```tsx
-// Dumb — renders what it's given
-function UserCard({ name, role, onEdit }: { name: string; role: string; onEdit: () => void }) {
-  return (
-    <Card.Root>
-      <Card.Content>
-        <Typo>{name}</Typo>
-        <Chip>{role}</Chip>
-      </Card.Content>
-      <Card.Footer>
-        <Button onClick={onEdit}>Edit</Button>
-      </Card.Footer>
-    </Card.Root>
-  );
-}
-```
-
-```tsx
-// Smart — knows where data comes from, renders the dumb component
-function UserCardContainer({ userId }: { userId: string }) {
-  const user = useUserQuery(userId);
-  const openEditor = useEditorNavigation(userId);
-  return <UserCard name={user.data.name} role={user.data.role} onEdit={openEditor} />;
-}
-```
-
-## Compose, don't configure
-
-- Build screen-level pieces by composing primitives (`Stack`, `Row`, `Card`, dumb components), not one component with a dozen
-  boolean props — a prop list that reads like a settings page wanted to be two or three components.
-- Lift state shared between siblings to the nearest common parent
-  ([Sharing State Between Components](https://react.dev/learn/sharing-state-between-components)); never sync copies.
-
-## Put state where its truth lives
-
-Work down this list; stop at the first match:
-
-1. **URL state** — shareable via the address bar (filters, sort, pagination, active tab) → TanStack Router search params;
-   back button and copied links come free. These cross an external boundary — parse per [validation.md](validation.md).
-2. **Server state** — from an API → TanStack Query's cache ([data.md](data.md)); never copy it into `useState` — that's how
-   stale-UI bugs are born.
-3. **Subtree state** — resets on leave (wizard progress) → React context.
-4. **Client state** — app-wide and persistent → TanStack Store, and only now: tiers 1–2 usually dissolve the "we need a
-   store" instinct.
-5. **Local state** — one component's own (input value, open/closed, a draft, a hover flag) → `useState`. Most state is local;
-   keep it in the component, no library.
-
-- A form turning drafts into a submitted domain value validates that boundary per [validation.md](validation.md).
-- Shape the state itself per [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) —
-  especially its rules on redundant and duplicated state.
-
-## Effects: last resort, and named
-
-- No `useEffect` for: derived values (render or `useMemo`), responses to user actions (the event handler), server sync (the
-  data-fetching layer). Effects only synchronize with systems _outside_ React.
-- Read [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) — the definitive misuse catalog —
-  before every effect you're tempted to write.
-- Extract a genuine effect into a custom hook named for its purpose (`useSyncedScroll`, `useDocumentTitle`, `useHotkey`),
-  never an anonymous inline `useEffect`: the name documents intent, the hook isolates the dependency array. Pattern:
-  [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
-- The rare effect that stays inline still names its callback, so intent survives without a comment:
-
-```tsx
-useEffect(
-  function syncDocumentTitle() {
-    document.title = title;
-  },
-  [title]
-);
-```
-
-- A dependency sourced from a hook or query return: destructure the primitive first — [typescript.md](typescript.md#naming).
-
-## Reading list
-
-Consult while building; each is the authority for its topic:
-
-- [Thinking in React](https://react.dev/learn/thinking-in-react) — decomposition and one-way data flow
-- [Keeping Components Pure](https://react.dev/learn/keeping-components-pure) — why dumb components stay dumb
-- [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) — shaping state without duplication
-- [Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — lifting state
-- [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) — the effect misuse catalog
-- [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) — named effects live here

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

@@ -1,88 +0,0 @@
-# Styling
-
-How app CSS is written and how it meets `@imfusion/web-ui`.
-
-## CSS authoring
-
-- **CSS Modules with native CSS only** — no Sass, no CSS-in-JS, no utility-class framework: nesting and custom properties
-  already cover DRY. Stylesheet location and ownership: [components.md](components.md).
-- Nest pseudo-elements, states, and child selectors under the root so the prefix is written once:
-
-  ```css
-  .root {
-    transition: clip-path var(--ease);
-
-    &:focus-visible {
-      outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-support);
-    }
-
-    &[data-disabled] {
-      opacity: 0.5;
-    }
-  }
-  ```
-
-- Lift a repeated literal (an easing, a colour-math result) into a custom property; custom properties also carry
-  per-state/per-variant values down the tree — native parameterisation, no mixin needed.
-- Don't merge rules that only look similar — structurally different output (three distinct `clip-path` polygons) isn't
-  repetition; keep it explicit.
-
-## Build custom UI from tokens
-
-- Custom UI the library doesn't cover (a stat widget, a custom panel) uses names from the shipped token index
-  ([tokens.md](tokens.md)) for color, size, radius, and type — that's what makes it look native and survive theme changes.
-- A hex code or a magic `px` next to a concept the tokens already name is a defect.
-- Geometry that can't be a token (a clip-path percentage, a hairline `1px`) → named custom property at the top of the
-  stylesheet, invariant written next to it. Don't silently approximate to the nearest token.
-
-## Override through the sanctioned seams
-
-- All library styles live in the `imf-ui.components` CSS layer, so any plain selector you write wins — that's the whole
-  override contract.
-- Target the stable hooks: `data-imf-ui-component` attributes and your own classes/wrappers.
-- Never target the library's internal class names — they are generated and change without notice.
-- Never `!important` — needing it means you're targeting the wrong thing.
-- Style against state via data attributes (`[data-checked]`, `[data-disabled]`, `[data-popup-open]`) — components expose
-  state there, so never maintain your own state classes. `className` is purely a styling surface:
-
-  ```css
-  [data-imf-ui-component="Switch"][data-checked] {
-    outline: 2px solid var(--imf-ui-color-bg-positive);
-  }
-  ```
-
-## The color system
-
-- Roles: **surfaces** (`main` canvas, `support` panels, `minor` popovers); **brand** (identity, full saturation) vs
-  **primary** (contrast-tuned, CTAs) — distinct roles on purpose; **status** (`negative`, `warning`, `positive`, `info`);
-  three **accent** slots.
-- **Controls** are the 80/20 customization surface — override one and every derived token shifts:
-
-  ```css
-  :root {
-    --imf-ui-color-primary-hue: 30; /* every primary semantic token follows */
-  }
-  ```
-
-- **Semantic tokens** are what you consume: `--imf-ui-color-bg-{name}` per role, a flat
-  `--imf-ui-color-fg-{main|support|minor|oncolor|…}` ladder for text. Borders and rings draw from `fg-*`.
-- Push a hue control into a pale corner → you own overriding the matching `fg-*` token.
-- Color scheme is `<html data-imf-ui-color-scheme="light|dark">`, set by the provider; scheme-specific styling selects via
-  that attribute.
-
-## Responsive styling
-
-- Tune components per breakpoint by overriding their `--imf-ui-*` variables inside your own media queries — custom properties
-  cross the `@media` boundary, props don't (why sizing is variables, not a `width` prop):
-
-  ```css
-  @media (min-width: 768px) {
-    .my-shell {
-      --imf-ui-appshell-navbar-width: 22rem;
-    }
-  }
-  ```
-
-- Write literal breakpoint values — the library's `@custom-media` aliases are build-internal and don't ship.
-- JS only for behaviour (render a burger menu on mobile): `useMediaQuery(minWidth("md"))`. Never for styling CSS can do.
-- No responsive props — `size={{ sm: … }}` objects are deliberately not offered; write the media query.

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

@@ -1,25 +0,0 @@
-# Testing
-
-Test the **decisions**, not the rendering.
-
-## Naming
-
-- Colocated tests use `.test.ts` / `.test.tsx` (e.g. `login-url.test.ts`) — not `.spec.*` or plural `.tests.*`.
-
-## What gets a test
-
-- **Pure logic gets unit tests** — pricing, permissions, date math, parsing, reducers: cheap, fast, and where bugs actually
-  hide.
-- **Presentational components generally don't**: a component mapping props onto web-ui primitives has no logic of its own —
-  asserting a `<Button>` rendered tests React, not your code.
-- **Behaviour a user performs gets an interaction test** — a validating form, a stepped flow — through the interface the user
-  has (roles, labels, visible text), not through internals.
-- **Extract the decision out of a hook and test it as a plain function** — easier than a render harness; a hook that only
-  wraps a browser API has no decision to extract.
-- The measure isn't coverage percentage — it's whether a failing test tells you something you didn't already know.
-
-## Layer-specific recipes
-
-- Data layer: stub `fetch`, run the real query client — the recipe is in [data.md](data.md).
-- A schema whose constraints or transforms encode product behavior gets focused accepted, rejected, and transformed cases:
-  [validation.md](validation.md).

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

@@ -1,7 +0,0 @@
-# Tokens
-
-## Token index
-
-- `@imfusion/web-ui` ships the generated token index at `node_modules/@imfusion/web-ui/src/llms/tokens.gen.json` — the only
-  source for consumer token names and authored default values.
-- Look up the exact entry there; never invent, recall, or duplicate a plausible `--imf-ui-*` name.

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

@@ -1,116 +0,0 @@
-# Tooling
-
-Dependency and configuration baseline for an ImFusion frontend; check before adding a dependency and before writing its
-config.
-
-## Topic-to-tool map
-
-- Use the mapped tool for each topic; prefer typed config (`.ts` over `.json`) where the tool supports it.
-
-| Topic                 | Tool                                                                                                  |
-| --------------------- | ----------------------------------------------------------------------------------------------------- |
-| Build                 | [Vite](https://vite.dev)                                                                              |
-| Routing, URL state    | [TanStack Router](https://tanstack.com/router) — file-based, type-safe search params                  |
-| Server state          | [TanStack Query](https://tanstack.com/query) — the pattern around it is [data.md](data.md)            |
-| Forms                 | [TanStack Form](https://tanstack.com/form)                                                            |
-| Data grids            | [TanStack Table](https://tanstack.com/table) + web-ui's styled `Table` parts                          |
-| App-wide client state | [TanStack Store](https://tanstack.com/store) — last resort in the state ladder ([react.md](react.md)) |
-| Schema validation     | [Zod](https://zod.dev) — at the network boundary ([data.md](data.md))                                 |
-| Styling               | CSS Modules ([styling.md](styling.md))                                                                |
-| Test                  | [Vitest](https://vitest.dev)                                                                          |
-| Format                | [Prettier](https://prettier.io)                                                                       |
-| Lint                  | [ESLint](https://eslint.org) flat config                                                              |
-| Types                 | `tsc --noEmit` — own script, own CI step                                                              |
-| Staged files          | [lint-staged](https://github.com/lint-staged/lint-staged) (or nano-staged, drop-in)                   |
-| Dead code             | [Knip](https://knipjs.dev) via `verify:knip` — needs per-repo config                                  |
-
-## When a library owns a layer
-
-- Adopt the library once you're rebuilding what it does — validation timing and cross-field rules (Form), caching and
-  refetching (Query), URL as source of truth (Router), sorting/pagination over rows (Table): adding it mid-project is cheap,
-  unpicking a hand-rolled version later is not.
-
-## Devtools
-
-- Every TanStack library with a devtools package gets it as a dev dependency, mounted in development only — Router's
-  `@tanstack/react-router-devtools` is a given; Query's goes in when Query does.
-- Check for a `-devtools` sibling on every new TanStack dependency — not every library has one yet.
-- Once several are in, host them in one panel via `@tanstack/devtools`.
-
-## Docs over memory
-
-- `npx @tanstack/cli` for TanStack docs — never work from memory.
-- Where `@tanstack/intent` is wired up, use it to reach and read the Agent Skills the TanStack dependencies ship.
-
-## Prettier
-
-- Config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
-
-```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"
-};
-```
-
-- Never omit the config file — no file means defaults, and the values silently differ.
-
-## ESLint
-
-Flat config (`eslint.config.ts`):
-
-- `strictTypeChecked` + `stylisticTypeChecked`, `projectService: true`
-- `as` and `!` banned outside tests (`consistent-type-assertions`)
-- `.gitignore` as the ignore source (`includeIgnoreFile` from `@eslint/compat`)
-- `#/` alias enforced via `no-restricted-imports` banning `../*` — parent-relative paths error, siblings (`./`) stay relative
-  ([project-structure.md](project-structure.md))
-
-## tsconfig
-
-```jsonc
-{
-  "compilerOptions": {
-    "strict": true,
-    "moduleResolution": "bundler",
-    "verbatimModuleSyntax": true, // import type stays import type
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true,
-    "skipLibCheck": true,
-    "paths": { "#/*": ["./src/*"] }
-  }
-}
-```
-
-- `#/` → `src/` alias rationale: [project-structure.md](project-structure.md).
-
-## Staged files
-
-- Runner config (lint-staged or nano-staged) applies eslint `--fix` and prettier `--write` to staged files only.
-- The pre-commit runner also invokes `verify:knip` when staged source or project config can change the reachability graph.
-
-## CSS class names
-
-- Generated CSS Module class names are readable in the DOM, `{prefix}-{file}-{local}`, never the default hash: a legible DOM
-  is what makes devtools and browser automation usable.
-- The library ships the plugin; pass a short, app-scoped prefix:
-
-```ts
-import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
-
-export default defineConfig({
-  plugins: [react(), readableCssModuleNames({ prefix: "acme" })]
-});
-```
-
-- One pattern for dev, Storybook, and production: register the plugin in **every** tool that compiles the CSS — a compiler
-  left out generates different names for the same source, and its styles silently don't apply.

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

@@ -1,73 +0,0 @@
-# TypeScript & 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).
-
-## 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:
-
-```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
-```
-
-- 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 & expressions
-
-- 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.
-
-## 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:
-
-```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());
-
-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]
-);
-```

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

@@ -1,62 +0,0 @@
-# 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.
-
-## 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.
-
-## 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.
-
-```ts
-import { z } from "zod";
-
-export const userSchema = z.object({
-  id: z.string(),
-  email: z.email()
-});
-
-export type User = z.infer<typeof userSchema>;
-```
-
-## 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.
-
-```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("")
-});
-
-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} />;
-}
-```
-
-## 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.

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

@@ -1,157 +0,0 @@
----
-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."
-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.
-
-## 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.
-
-## Base update
-
-In a non-dry run, update the dependency:
-
-```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.
-
-Classify paths as:
-
-- **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.
-
-On conflict, stop. Never use `git restore`, `git reset`, `git clean`, or broad staging to hide it.
-
-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.
-
-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.
-
-## Base update report and approval
-
-Before the base commit, show this concise report:
-
-```text
-@imfusion/web-ui update report
-Package      : <old> -> <new> / would update
-Skills       : <status>
-Hooks        : <status>
-Verification : <status>
-Update files : <paths>
-Held back    : <paths or none>
-Conflicts    : <paths or none>
-Commit       : <imperative 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.
-
-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.
-
-## Migration approval
-
-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.
-
-## Commit
-
-For the base update, after approval:
-
-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.
-
-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.