@imfusion/web-ui 0.5.1-dev.3.g8e0a047a → 0.5.1-dev.32.gddf4b438

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/session-start.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+# SessionStart: point the agent at the vendored conventions baseline once per session.
+echo "The ImFusion frontend conventions baseline is vendored in .agents/skills/ (imf-web-ui-frontend-conventions and siblings). Load the relevant skill before writing code, styles, or docs; repo docs in docs/ carry only what is unique to this repo."
+exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/user-prompt-submit.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+# UserPromptSubmit: one-line conventions reminder per prompt.
+echo "Conventions check: if this task touches code, styles, data fetching, or docs, consult the matching imf-web-ui-* skill in .agents/skills/ before acting."
+exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/settings.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/session-start.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/user-prompt-submit.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/post-tool-use.sh\"",
+            "statusMessage": "Verifying file"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -3,7 +3,8 @@ name: imf-web-ui-components
 description:
   "Look up @imfusion/web-ui component APIs without reading their source: the two-hop lookup (identity index -> prop data),
   compound components, and integrations. Load when you need the props, sub-components, or defaults of a specific component —
-  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-setup)."
+  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-library-setup)."
+allowed-tools: Bash
 ---
 
 # imf-web-ui-components

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

@@ -0,0 +1,46 @@
+---
+name: imf-web-ui-frontend-conventions
+description:
+  "The ImFusion frontend conventions baseline — in-house conventions, valid in every ImFusion frontend and usable by anyone
+  who likes them. A router over topic references: library boundary, React, components, TypeScript, styling, validation, data
+  layer, project structure, testing, stack, npm project, tooling config, git, assets, docs structure. Load when writing
+  wrapper components, custom UI, styling beyond the defaults, validating external data, adding new files to a consumer app,
+  writing repo docs, touching tool config, or choosing any dependency."
+---
+
+# imf-web-ui-frontend-conventions
+
+The ImFusion frontend baseline. In-house conventions, not industry claims — they encode how ImFusion frontends are built, and
+anyone else is welcome to them.
+
+**The project wins.** These defaults fill vacuums: if the host project already has a convention — a styling system, a state
+library, a folder shape — that stands. They are not a license to refactor a consumer codebase toward this document.
+
+**Alignment mode.** The exception is intent: when the user asks to _align_ the repo with the baseline ("align", "alignment"
+is the flag), the project-wins guard lifts. Deviations then become migration findings — proposed as a plan, still nothing
+changed until the human approves.
+
+## The references
+
+Each topic lives in one reference. Read the one whose moment you're in; starting a new feature usually wants several.
+
+| Reference                                               | Covers                                                              | Read when                                               |
+| ------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
+| [library-boundary.md](references/library-boundary.md)   | staying behind `@imfusion/web-ui`, wrappers, type derivation, peers | touching anything that renders library components       |
+| [react.md](references/react.md)                         | component roles, state kinds and owners, effects discipline         | writing new screens, components, or wrappers            |
+| [components.md](references/components.md)               | component anatomy on disk: grouping, folders, colocation            | adding a component file                                 |
+| [typescript.md](references/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
+| [styling.md](references/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
+| [class-names.md](references/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
+| [validation.md](references/validation.md)               | runtime schemas, boundary parsing, schema-derived types             | accepting data the frontend does not own                |
+| [data.md](references/data.md)                           | `api/`+`http/` shape, query/mutation patterns and invalidation      | adding an API topic, a fetch, or a mutation             |
+| [project-structure.md](references/project-structure.md) | the `src/` tree, file naming, imports                               | adding files rather than editing existing ones          |
+| [testing.md](references/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
+| [stack.md](references/stack.md)                         | the topic→tool map, when a library owns a layer                     | choosing or adding any dependency                       |
+| [npm-project.md](references/npm-project.md)             | `package.json`, the `verify:*` script set, dependency pinning       | running or adding a script, adding a dependency         |
+| [tooling.md](references/tooling.md)                     | Prettier, ESLint, tsconfig, staged files, CSS class names           | touching tool config                                    |
+| [git.md](references/git.md)                             | `git:config`, verify scopes, staleness at commit time               | wiring hooks or the commit path                         |
+| [assets.md](references/assets.md)                       | image formats, the WebP recipe                                      | adding images or other static assets                    |
+| [docs-structure.md](references/docs-structure.md)       | what a repo documents, where, how it's written                      | writing or restructuring repo docs                      |
+
+`imf-web-ui-frontend-setup` bootstraps and audits a repo against this baseline.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/assets.md

@@ -0,0 +1,23 @@
+# Assets
+
+Import everything from `src/assets/` so the bundler fingerprints and bundles it. Never reference an image by public-path
+string.
+
+## Photographs — WebP
+
+```bash
+magick source.png -resize 2000x -quality 80 -define webp:method=6 src/assets/name.webp
+```
+
+- Quality 80 is visually lossless on photos and routinely cuts file size by an order of magnitude.
+- `method=6` is the densest encoding. It's a one-off cost at conversion time, so take the smaller file.
+- Cap the long edge at 2000px — nothing on the market resolves more in a content image.
+- No `<picture>` fallback needed; WebP is supported everywhere since 2020.
+
+## Other formats
+
+- **Alpha, or pixels that must stay exact** → PNG, optimized with `oxipng` or `pngquant`.
+- **Icons, logos, line art** → inline SVG component, so it inherits `currentColor` and follows the theme.
+
+These rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep —
+convert opportunistically, when you're working on them anyway.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/class-names.md

@@ -0,0 +1,42 @@
+# Class names in components
+
+How a component turns props into a `className` string. What the build does with the result is [tooling.md](tooling.md); what
+goes in the stylesheet is [styling.md](styling.md).
+
+**CVA is the only tool.** `class-variance-authority` maps variant props to CSS Module classes. No `clsx`, no
+`tailwind-merge`, no local `cn()` helper. `cx` is CVA's own concatenator and `@imfusion/web-ui` re-exports it, so it comes
+from the library alongside the components.
+
+```tsx
+import { cva } from "class-variance-authority";
+import classes from "./chip.module.css";
+
+const chip = cva(classes.root, {
+  variants: {
+    appearance: { outline: classes.appearanceOutline, solid: classes.appearanceSolid },
+    inline: { false: null, true: classes.inline }
+  }
+});
+
+export function Chip({ appearance = "outline", inline = false, className, ...props }: Props) {
+  return <span {...props} className={chip({ appearance, inline, className })} />;
+}
+```
+
+- **Base class is CVA's first argument**, variant values are CSS Module references, never string literals. A boolean axis
+  uses `null` for its off-state.
+- **The incoming `className` goes into CVA's `className` slot**, which appends it last so a caller's class always wins. With
+  no variants to map, `cx(classes.inline, className)` does the same job.
+- **Every component that accepts `className` merges it.** A component whose surface is deliberately closed omits the prop
+  entirely rather than accepting and ignoring it.
+- **Defaults live in the props destructuring, not CVA's `defaultVariants`.** react-docgen-typescript reads the destructuring,
+  so defaults declared in CVA don't reach the generated docs.
+- **Resolve a function-form `className` before merging.** Components built on a library that passes render state
+  (`className={state => …}`) receive either shape:
+
+  ```tsx
+  className={state => cx(classes.root, typeof className === "function" ? className(state) : className)}
+  ```
+
+- **Two components sharing one visual share one CVA module**, a `{name}.cva.ts` next to them, so their variant axes can't
+  drift apart.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/components.md

@@ -0,0 +1,63 @@
+# Components
+
+How a component lives on disk and how dumb it stays. Roles, state, and effects in full are [react.md](react.md); styling is
+[styling.md](styling.md).
+
+## As dumb as possible
+
+Data comes from outside — props-fed, never self-fetching. Presentational logic (formatting a label, deriving a display state)
+is fine; owning data is not:
+
+```tsx
+// components/user-card/user-card.tsx
+interface Props {
+  name: string;
+  role: string;
+  onEdit: () => void;
+}
+
+export function UserCard({ name, role, onEdit }: Props) {
+  return (
+    <Card.Root>
+      <Card.Content>
+        <Typo>{name}</Typo>
+        <Chip>{role}</Chip>
+      </Card.Content>
+      <Card.Footer>
+        <Button onClick={onEdit}>Edit</Button>
+      </Card.Footer>
+    </Card.Root>
+  );
+}
+```
+
+No query hook, no store access, no route awareness — the component renders what it's given and reports events upward. Local
+UI state (`isOpen`, a draft value) is allowed; anything whose truth lives elsewhere is not ([react.md](react.md)).
+
+## Grouping
+
+`components/` groups by kind — a layout component under `layouts/`, not beside a domain widget. Flat is fine while there are
+few; let the grouping follow what the project actually has rather than imposing it up front. The kinds worth separating are
+the component roles in [react.md](react.md).
+
+## One file or a folder
+
+A component gets a folder once it has more than one file — sub-components, styles, tests — with an `index.ts` that only
+re-exports:
+
+```
+components/data-table/
+  data-table.tsx
+  data-table-row.tsx
+  data-table.module.css
+  index.ts
+```
+
+Imports then read `#/components/data-table` and the inside can be restructured without touching call sites. Single-file
+components stay single files, directly in their group.
+
+## Colocation
+
+The stylesheet is colocated as `<component>.module.css` next to the component, and only dumb components have one — a
+container that wants CSS is asking for a layout component instead ([react.md](react.md)). Tests and local types sit next to
+their subject too. A file you have to hunt for in a parallel tree gets edited less carefully.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/data.md

@@ -0,0 +1,201 @@
+# Data
+
+How data enters, moves through, and leaves an ImFusion frontend. This is the in-house pattern **for TanStack Query + Router**
+— the default stack ([stack.md](stack.md)). A project on a different data layer keeps the boundary principles (validate at
+the edge, errors as values) but not necessarily this file layout.
+
+## The shape
+
+```
+src/
+  api/<topic>/       # one folder per API topic
+    <topic>.ts       #   queryOptions / mutationOptions
+    query-key.ts     #   key factory, topic as the first segment
+    types.ts         #   Zod schemas + z.infer types
+  http/              # transport: client, error normalisation — the only transport-aware place
+```
+
+A query lives next to its key factory and its schemas, so a query key is never spelled out at a call site. Anything
+transport-level (base client, error normalisation) lives in `http/` and nowhere else.
+
+## The network boundary validates
+
+The transport in `http/` returns `unknown`; the topic schema parses the response in its query or mutation function before the
+value enters the app. The schema is also the source of its TypeScript type. The full boundary, type-derivation, and failure
+handling rules are [validation.md](validation.md).
+
+## Errors are values
+
+A failed request becomes an `ApiError` carrying a machine-readable code — it crosses the boundary the same way values do, not
+as an exception caught ad hoc. The frontend owns the mapping from codes to what the user reads.
+
+## The pattern, end to end
+
+The key factory — topic as the first segment, one function per key shape:
+
+```ts
+// api/user/query-key.ts
+const TOPIC = "user" as const;
+
+export const userKeys = {
+  all: [TOPIC] as const,
+  me: () => [TOPIC, "me"] as const,
+  detail: (id: string) => [TOPIC, "detail", id] as const
+};
+```
+
+Query options — key from the factory, parse at the boundary:
+
+```ts
+// api/user/user.ts
+import { queryOptions } from "@tanstack/react-query";
+
+import { bffClient } from "#/http/bff-client";
+import { userKeys } from "./query-key";
+import { userSchema } from "./types";
+
+export const userQueryOptions = () =>
+  queryOptions({
+    queryKey: userKeys.me(),
+    queryFn: async () => userSchema.parse(await bffClient("/me"))
+  });
+```
+
+Components consume query options directly with `useSuspenseQuery` (prefetched routes) or `useQuery` (secondary data). No
+wrapper hooks — the options function is the reusable unit. Call sites may spread the returned options only to add
+component-specific callbacks or overrides.
+
+Mutations follow the same shape with `mutationOptions`, the dirtied topic first in the `mutationKey`:
+
+```ts
+// api/user/user.ts
+export const updateUserMutationOptions = () =>
+  mutationOptions({
+    mutationKey: [...userKeys.all, "update"],
+    mutationFn: async (patch: UserPatch) => userSchema.parse(await bffClient("/me", { method: "PATCH", body: patch }))
+  });
+```
+
+The root route types the router context so every loader can reach the query client via DI:
+
+```ts
+// routes/__root.tsx
+import { Outlet, createRootRouteWithContext } from "@tanstack/react-router";
+import type { QueryClient } from "@tanstack/react-query";
+
+interface RouterContext {
+  queryClient: QueryClient;
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: () => <Outlet />
+});
+```
+
+The router is created with that context filled in:
+
+```ts
+// router.ts
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+import { createQueryClient } from "./query-client";
+
+const queryClient = createQueryClient();
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient }
+});
+```
+
+A route prefetches in the `loader`, reads with `useSuspenseQuery`, and provides a `pendingComponent`; errors bubble to the
+nearest `errorComponent`:
+
+```tsx
+// routes/me.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import { userQueryOptions } from "#/api/user/user";
+
+export const Route = createFileRoute("/me")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(userQueryOptions()),
+  pendingComponent: () => <p>Loading…</p>,
+  component: MePage
+});
+
+function MePage() {
+  const { data: user } = useSuspenseQuery(userQueryOptions());
+  return <h1>{user.name}</h1>;
+}
+```
+
+Mutations use `useMutation` with the options factory instead of reconstructing `mutationKey` and `mutationFn` at the call
+site. Manual invalidation is unnecessary when automatic invalidation is on (see below):
+
+```tsx
+// components/user-settings.tsx
+import { useMutation } from "@tanstack/react-query";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import { userQueryOptions, updateUserMutationOptions } from "#/api/user/user";
+
+function UserSettings() {
+  const { data: user } = useSuspenseQuery(userQueryOptions());
+  const updateUser = useMutation(updateUserMutationOptions());
+
+  return (
+    <form
+      onSubmit={e => {
+        e.preventDefault();
+        updateUser.mutate({ name: "New Name" });
+      }}
+    >
+      <input defaultValue={user.name} />
+    </form>
+  );
+}
+```
+
+## Automatic invalidation
+
+Mutations don't invalidate by hand at every call site — the query client does it centrally, keyed off the mutation's topic. A
+`MutationCache` `onSuccess` invalidates `mutationKey[0]`, on by default via `meta.autoInvalidate`; that's why every
+mutation's key leads with the topic it dirties:
+
+```ts
+// query-client.ts
+export function createQueryClient() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      mutations: { meta: { autoInvalidate: true } }
+    },
+    mutationCache: new MutationCache({
+      onSuccess: async (_data, _variables, _context, mutation) => {
+        if (!mutation.meta?.autoInvalidate) return;
+        const topic = mutation.options.mutationKey?.[0];
+        if (topic !== undefined) await queryClient.invalidateQueries({ queryKey: [topic] });
+      }
+    })
+  });
+  return queryClient;
+}
+```
+
+Opt out per mutation with `meta: { autoInvalidate: false }` when a coarse topic-wide refetch is wrong (a huge list, a
+targeted optimistic update), and invalidate precisely through the key factory instead. Background reading:
+[query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) and
+[automatic invalidation after mutations](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations).
+
+## Audit
+
+Inspect the complete path, not the presence of TanStack Query alone: transport returns `unknown`; topic schemas parse
+responses; API types derive from those schemas; keys come from topic factories; API topics expose reusable `queryOptions` and
+`mutationOptions`; hooks consume those options with only local overrides; mutation keys match the configured invalidation
+strategy.
+
+## Testing the data layer
+
+Stub the network at the `fetch` boundary and let the real query client run: the test then exercises the same parse and error
+path production does. Schemas, clients, and query options are where behaviour worth asserting lives — schema cases are in
+[validation.md](validation.md), and the general philosophy is [testing.md](testing.md).

package/src/llms/skills/imf-web-ui-frontend-conventions/references/docs-structure.md

@@ -0,0 +1,44 @@
+# Documentation structure
+
+What a repo documents, where, and how it's written. `imf-web-ui-frontend-setup` scaffolds this shape from its `templates/`
+and audits it.
+
+## The shape
+
+```
+<app>/
+  README.md            # humans: what the app is, setup, scripts
+  AGENTS.md            # agents: stack, pointers into docs/ — restates nothing
+  docs/
+    index.md           # registers every doc with a one-line "covers" summary
+    <topic>.md         # repo-unique content only
+```
+
+## Repo docs hold only what is unique to the repo
+
+The litmus, applied sentence by sentence: **would this be true in every ImFusion frontend? Then it's baseline — it lives in
+the installed skill references, don't restate it.** The baseline is already in the repo, vendored under
+`.agents/skills/imf-web-ui-frontend-conventions/`, human-readable and versioned.
+
+Where the repo deviates from the baseline, the doc says so as a **named deviation** — what the baseline prescribes, what this
+repo does instead, and why. A deviation written as freestanding convention gets copied into the next repo as if it were house
+style.
+
+## How docs are written
+
+- **Docs explain concepts; code is the source of truth for facts.** A doc captures the why — invariants, rationale,
+  decisions. It never restates a fact that lives in code (a script definition, a type shape, a config value): point at the
+  file instead. A copied fact rots the moment the code changes.
+- **State what is — no decision residue.** Positive, present-tense statements about the current state. Never narrate the
+  delta from a past decision or refute alternatives nobody raised ("there is no X mode", "Y was dropped") — that history
+  belongs in commits and tickets. A negation earns its place only as a guardrail or to preempt a wrong assumption a present
+  reader would actually arrive at.
+- **Boy Scout rule.** Discovered rot — a stale pointer, a doc contradicting the code — is always your responsibility: fix it
+  in place if trivial, otherwise report it. The two failure modes are equal: stepping over rot, and cramming unrelated
+  cleanup into an unrelated change.
+
+## Staleness at commit time
+
+Docs are checked when they can go stale: at the commit. A staged change that invalidates a doc — a renamed script, a moved
+folder, a changed flow — updates that doc **in the same commit**, not in a follow-up. Pre-commit carries the advisory
+staleness checks (vendored baseline, docs) — the mechanics are in [git.md](git.md).

package/src/llms/skills/imf-web-ui-frontend-conventions/references/git.md

@@ -0,0 +1,33 @@
+# Git
+
+## git:config
+
+One script holds the repo's git configuration, run by hand once per clone (the README names it):
+
+```
+git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only
+```
+
+Hooks live in a tracked directory; history strategy doesn't depend on personal git config. Two silent failure modes to check
+for: `git:config` never run (hooks exist only on the machine that configured by hand), and `core.hooksPath` pointing at a
+directory that doesn't exist. Config **and** directory.
+
+## Verify scopes
+
+Two blocking, one advisory:
+
+- **staged** — `verify:staged`, called by the pre-commit hook: lint, format, restage. Fast; a passing commit is not CI green.
+- **full** — `verify:full`: the build plus every `verify:*` check. What CI runs.
+- **files** — post-edit agent hook. Advisory, never exits non-zero, so a mid-flight refactor can't trap the agent.
+
+One script owns each scope's step list; npm scripts and hooks only launch them. Name by depth, not by occasion — a
+`preflight` needs explaining and invites a near-identical sibling, and two of those drift into "passes locally, fails in CI".
+
+## Staleness at commit time
+
+Pre-commit also runs the advisory staleness checks — warn, never block:
+
+- **Vendored baseline** — `.agents/hooks/imf-web-ui/baseline-staleness.sh` compares the installed `imf-web-ui-*` skill
+  markers against the installed package version; the fix it names is `npx web-ui-install`.
+- **Docs** — a staged change that invalidates a doc updates that doc in the same commit
+  ([docs-structure.md](docs-structure.md)). Where the repo has an agent commit workflow, a staged docs audit belongs in it.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/library-boundary.md

@@ -0,0 +1,37 @@
+# Library boundary
+
+The contract between an app and `@imfusion/web-ui`.
+
+## Stay behind the library
+
+Never import Base UI (or any other upstream the library wraps) directly — no upstream stylesheets, no upstream components,
+even when upstream docs show it that way. Everything a component needs ships in `@imfusion/web-ui`. If the library is missing
+something upstream has, report the gap (see `imf-web-ui-components`); don't reach around it.
+
+## Wrap primitives when the app has a reason to
+
+When the app keeps repeating something around a primitive — default props, a styling override, a composition, an
+accessibility refinement, a restriction of the API — wrap it once in an app-level dumb component and use that. The wrapper
+derives its props from the primitive (`React.ComponentProps<typeof Button>`, narrowed or extended), lives in `components/`
+like any other dumb component ([components.md](components.md)), and styles itself through the sanctioned seams — it never
+reaches into the library's internals.
+
+Two rules keep wrappers honest:
+
+- Wrap for a reason — any repeated adaptation counts. A wrapper that only renames a primitive is indirection with no payoff.
+- Components marked `experimental` in the identity index get wrapped **always**, even with nothing added yet — a breaking
+  upstream change then lands in one file instead of every call site.
+
+## Derive types, don't import them
+
+Prop types come from the components themselves: `React.ComponentProps<typeof Button>`. The library deliberately exports no
+`Props` types — don't look for them, and don't re-declare prop shapes by hand.
+
+## Integrations own their peers
+
+Components under `@imfusion/web-ui/integrations/*` depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`).
+Add the peer explicitly to the consumer's `package.json` — never rely on hoisting.
+
+## Styling crosses the boundary through seams
+
+Tokens in, sanctioned selectors at the edge, never the library's internals — the full contract is [styling.md](styling.md).

package/src/llms/skills/imf-web-ui-frontend-conventions/references/npm-project.md

@@ -0,0 +1,57 @@
+# npm project
+
+How the npm side of an ImFusion frontend is structured: `package.json`, scripts, dependencies. `imf-web-ui-frontend-setup`
+audits against this file.
+
+## package.json
+
+The exemplary shape:
+
+```jsonc
+{
+  "name": "@imfusion/scan-review",
+  "type": "module",
+  "private": true, // only when the package is not meant to be published
+  "engines": { "node": ">=22" },
+  "imports": { "#/*": "./src/*" }
+}
+```
+
+- `"type": "module"` always.
+- `"private": true` for apps that never publish; a publishable package drops it.
+- Node pinned via `engines.node` or `.nvmrc` — not a personal version manager's config.
+- The `#/` alias wired through `imports` ([project-structure.md](project-structure.md)).
+
+## Scripts
+
+Same name, same meaning, every repo — "what can I run to check this?" is answered by tab-completing `verify:`.
+
+| Script             | Runs                                                                  |
+| ------------------ | --------------------------------------------------------------------- |
+| `dev`              | dev server                                                            |
+| `build`            | production build                                                      |
+| `verify:deps`      | exact-pin check over `dependencies` and `devDependencies`             |
+| `verify:format`    | `prettier --check .`                                                  |
+| `verify:lint`      | `eslint . --cache --max-warnings=0`                                   |
+| `verify:typecheck` | `tsc --noEmit` (or `tsc -b --noEmit` in a project-references setup)   |
+| `verify:tests`     | `vitest run`                                                          |
+| `verify:staged`    | staged-file subset, called by the pre-commit hook                     |
+| `verify:full`      | every `verify:*` check plus the build; what CI runs                   |
+| `format`           | `prettier --write .`                                                  |
+| `lint`             | `eslint . --cache --fix`                                              |
+| `git:config`       | see [git.md](git.md); run by hand once per clone, named in the README |
+
+Two rules generate the names:
+
+- **Every check is `verify:*`.** One namespace for everything that reads and reports.
+- **Write-mode scripts keep the tool name.** `format` and `lint` change files, which isn't verifying — no prefix, no `:fix`
+  suffix.
+
+`verify:staged` is fast and partial; a passing commit is not CI green. `verify:full` is the CI gate.
+
+## Dependencies
+
+- **Pinned exactly.** No `^`, `~`, or `latest`, in `dependencies` and `devDependencies` alike. `verify:deps` catches drift;
+  `save-exact=true` in `.npmrc` prevents it.
+- **`ignore-scripts=true` in `.npmrc`.** Blocks lifecycle scripts on install (the supply-chain vector). Setup that matters is
+  a command someone runs, not a hook that fires on install.

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

@@ -0,0 +1,21 @@
+# Project structure
+
+Kebab-case throughout, folders and files alike. Exported symbols stay PascalCase — only the filename is kebab.
+
+```
+src/
+  routes/          # TanStack Router file-based routes; routing only — they compose, they don't fetch inline
+  api/             # one folder per API topic — layout and behaviour in data.md
+  components/      # grouped by kind — anatomy in components.md
+  http/            # transport: client, error normalisation — the only transport-aware place (data.md)
+  lib/             # framework-free helpers
+```
+
+Each subtree's own rules live with its topic: [data.md](data.md) for `api/` and `http/`, [components.md](components.md) for
+`components/`.
+
+## Imports
+
+The `#/` 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 where the toolchain resolves it natively, with a matching tsconfig `paths` entry.