@imfusion/web-ui 0.5.1-dev.33.gadde98d1 → 0.5.1-dev.39.gfc64049e

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

@@ -0,0 +1,44 @@
+# Project structure
+
+Kebab-case throughout, folders and files alike; exported symbols stay PascalCase — only the filename is kebab.
+
+## Layout
+
+```
+src/
+  main.tsx         # providers and router bootstrap; one WebUIProvider at the app root
+  routes/          # TanStack Router file-based routes; routing only — they compose, they don't fetch inline
+    __root.tsx     # document-wide error/not-found boundary and Outlet
+    _public/       # anonymous route group; resolves the current user when public pages need it
+      route.tsx
+    _app/          # pathless authenticated route group; guards the subtree before children render
+      route.tsx
+  api/             # one folder per API topic — layout and behaviour in data.md
+    auth/           # one current-user query plus server-owned login/logout URL helpers
+  components/      # grouped by kind — anatomy in components.md
+    app-shell/     # optional persistent authenticated chrome: brand, navigation, and session action
+  http/            # transport: client, error normalisation — the only transport-aware place (data.md)
+  lib/             # framework-free helpers, each with a colocated .test.ts when it has decisions to test
+    auth/
+      login-url.ts
+      login-url.test.ts
+```
+
+- Each subtree's rules live with its topic: [data.md](data.md) for `api/` and `http/`, [components.md](components.md) for
+  `components/`.
+
+## Application boundary
+
+- Start every frontend with the root providers, a current-user query, and pathless `_public/` and `_app/` route groups —
+  contract in [authentication.md](authentication.md); add feature routes only after that boundary exists.
+- Greenfield: `_app/` starts with a minimal `AppShell` — ImFusion logo, route navigation, and a stable session-action area
+  around the route `Outlet`.
+- Omit the shell only when the human explicitly says the product has no persistent authenticated navigation; the `_app/`
+  guard stays.
+- An established project preserves its working choice; public pages can use a small branded header instead.
+
+## Imports
+
+- `#/` alias for anything outside the current folder, plain `./` for siblings.
+- The alias is always `#/` → `src/`: `#` is Node's own subpath-import prefix, so it can't collide with an npm scope.
+- Wire it once, through `package.json`'s `imports` field (toolchain-native), with a matching tsconfig `paths` entry.

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

@@ -0,0 +1,107 @@
+# 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 { data } = useUserQuery(userId);
+  const openEditor = useEditorNavigation(userId);
+  return <UserCard name={data.name} role={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]
+);
+```
+
+## 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

@@ -0,0 +1,88 @@
+# 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

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,116 @@
+# 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-frontend-conventions/references → imf-web-ui-conventions/topics}/typescript.md

@@ -18,10 +18,9 @@ type Size = (typeof sizes)[number];
 const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler breaks if `sizes` changes
 ```
 
-Across boundaries the same rule: 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)).
-
+- 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

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

@@ -0,0 +1,62 @@
+# 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-setup/SKILL.md

@@ -0,0 +1,71 @@
+---
+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."
+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
+
+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.
+
+## Workflow
+
+1. Resolve the argument. Bare means `full`; a topic selects one supported setup topic. For an unsupported topic, 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.
+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. For a greenfield project, propose the minimal branded `AppShell` in the authenticated route group by default. If the human
+   explicitly says the product has no persistent authenticated navigation, ask whether to omit the shell before finalizing
+   the proposal; keep the `_app/` boundary either way. Existing projects keep their working shell choice. This ticket
+   documents the starter shape but does not copy a full starter template.
+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` and review its
+   `AUDIT_REPORT.md` before declaring the setup complete.
+
+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.
+
+## Checklist
+
+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.
+
+## Safety
+
+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.
+
+## Setup topics
+
+`full` covers every topic below. A one-topic run assesses only that topic.
+
+| 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   |
+
+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`.

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

@@ -53,7 +53,7 @@ pass. Stop on install failure.
 Then refresh the existing web-ui skill target and lifecycle hooks:
 
 ```sh
-npx web-ui-install --skills
+npx web-ui-install
 npx web-ui-install --hooks
 ```
 
@@ -62,8 +62,10 @@ Run these from the consumer package root, the directory holding the `node_module
 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, prompt submit, and post-edit verification. The hook installer
-refreshes those scripts wholesale and merges registrations idempotently. Stop on malformed settings or installer conflicts.
+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
 
@@ -132,6 +134,10 @@ verification again, and show a second report with the migration paths, held-back
 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 report 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

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

@@ -11,7 +11,7 @@ description:
 Most teams consuming `@imfusion/web-ui` don't have a designer on call. This skill stands in: it encodes the library authors'
 UX experience — the whole experience of a screen, its visual design, and the usability where both meet. Follow it by default;
 deviate when the product has a real reason to. Code-level patterns (tokens, layers, wrappers) live in
-`imf-web-ui-frontend-conventions`; project wiring lives in `imf-web-ui-library-setup`.
+`imf-web-ui-conventions`; project wiring lives in the `library-setup` topic of `imf-web-ui-conventions`.
 
 Component names below are real — verify any API against the docgen index (`imf-web-ui-components`) before use. Never invent a
 component this library doesn't ship.
@@ -82,13 +82,13 @@ Every screen ships four states, not one:
 
 Custom UI the library doesn't cover should be indistinguishable from library UI: build it from `--imf-ui-*` tokens and
 compose it with library primitives. The goal lives here; the mechanics (tokens, layers, wrappers) live in
-`imf-web-ui-frontend-conventions`.
+`imf-web-ui-conventions`.
 
 ## Experimental components
 
 The identity index marks each component `stable` or `experimental`. Experimental ones are fine to use, but expect API
-movement across releases — prefer wrapping them once (see `imf-web-ui-frontend-conventions`) so a breaking change lands in
-one file, not forty call sites.
+movement across releases — prefer wrapping them once (see `imf-web-ui-conventions`) so a breaking change lands in one file,
+not forty call sites.
 
 ## Deep dives
 

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

@@ -8,8 +8,8 @@ non-compliant ones. Read before building any form beyond two fields.
 
 The library ships the controls (`Input`, `Select`, `Checkbox`, `Switch`, `Slider`) but no form or field wrapper, so labels,
 grouping, and where errors appear are composed by you. That's exactly where these rules apply. Composing the markup is not
-the same as owning the state: form state and validation belong to a form library (see `imf-web-ui-frontend-conventions`), and
-these rules govern how its errors get presented.
+the same as owning the state: form state and validation belong to a form library (see `imf-web-ui-conventions`), and these
+rules govern how its errors get presented.
 
 ## Structure