@imfusion/web-ui 0.5.0 → 0.5.1-dev.11.g2e949f6d

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.

package/src/llms/skills/{imf-web-ui-frontend-patterns/references/react-patterns.md → imf-web-ui-frontend-conventions/references/react.md}

@@ -1,4 +1,4 @@
-# React patterns
+# React
 
 The house defaults for the React code around `@imfusion/web-ui`, in full. The links throughout are for **you, the agent**:
 consult them while building — they are the authoritative source when a case here is ambiguous. Hand them to the human only if
@@ -43,9 +43,8 @@ function UserCardContainer({ userId }: { userId: string }) {
 ```
 
 Why it matters here: dumb components are the layer where `@imfusion/web-ui` lives. Keeping them free of logic keeps every
-screen restylable, testable with plain props, and resilient to library updates. The one web-ui-specific addition: wrap
-`experimental` components (marked in the identity index) in a dumb component once per app even if you add nothing yet — a
-breaking upstream change then lands in one file instead of every call site.
+screen restylable, testable with plain props, and resilient to library updates. When and how to wrap the library's primitives
+in app-level dumb components is [library-boundary.md](library-boundary.md).
 
 ## Compose, don't configure
 
@@ -56,15 +55,18 @@ components. When state must be shared between siblings, lift it to the nearest c
 
 ## Put state where its truth lives
 
-Work down this list and stop at the first match:
+State comes in kinds, and each kind has an owner. Work down this list and stop at the first match:
 
-1. **Shareable via URL?** (filters, sort, pagination, active tab) → router search params. Back button and copied links are UX
-   features you get for free.
-2. **Comes from an API?** → the data-fetching layer's cache (e.g. TanStack Query). Never copy server data into `useState` —
-   that's how stale-UI bugs are born.
-3. **Scoped to a subtree, resets on leave?** (wizard progress) → React context.
-4. **App-wide and persistent?** → a client store, and only now.
-5. **Local to one component?** (input value, open/closed) → `useState`.
+1. **URL state** — shareable via the address bar (filters, sort, pagination, active tab) → TanStack Router search params.
+   Back button and copied links are UX features you get for free.
+2. **Server state** — comes from an API → TanStack Query's cache ([data.md](data.md)). Never copy server data into `useState`
+   — that's how stale-UI bugs are born.
+3. **Subtree state** — scoped to a subtree, resets on leave (wizard progress) → React context.
+4. **Client state** — app-wide and persistent → TanStack Store, and only now.
+5. **Local state** — one component's own (input value, open/closed) → `useState`.
+
+`useState` is the right tool for local UI state, and most state is local: whether a panel is open, which tab is active, a
+draft value being typed, a hover flag. Keep those in the component and don't reach for a library.
 
 Most frontends need far less of tier 4 than they think; tiers 1–2 usually dissolve the "we need a store" instinct. For
 structuring the state itself, [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) is the
@@ -82,6 +84,18 @@ When an effect is genuinely needed, extract it into a custom hook named for its
 hook isolates the dependency array, and the component body stays declarative. Pattern reference:
 [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
 
+The naming rule holds even for the rare effect that stays inline: give the callback a name, so the 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:

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

@@ -0,0 +1,39 @@
+# Stack
+
+The topic→tool map for an ImFusion frontend. Check this before adding a dependency; check the TanStack suite before adding a
+non-TanStack one.
+
+| 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) — values in [tooling.md](tooling.md)                                  |
+| Lint                  | [ESLint](https://eslint.org) flat config ([tooling.md](tooling.md))                                   |
+| 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) — needs per-repo config                                                    |
+
+## Devtools come with the library
+
+Every TanStack library that ships a devtools package gets it as a dev dependency, mounted in development only. Router is a
+given, so `@tanstack/react-router-devtools` is a given too; Query's goes in when Query does. Look for a `-devtools` sibling
+whenever you add a TanStack dependency — the set grows, and not every library has one yet. Once a project has several,
+`@tanstack/devtools` hosts them in one panel.
+
+## When a library owns a layer
+
+A library owns the layer once you find yourself rebuilding what it does: validation timing and cross-field rules (Form),
+caching and refetching (Query), URL as the source of truth (Router), sorting and pagination over rows (Table). Adding the
+library mid-project is normal and cheap; unpicking a hand-rolled version later is not.
+
+## Docs over memory
+
+`npx @tanstack/cli` for TanStack docs — never work from memory. Where a project has wired up `@tanstack/intent`, use it to
+reach the Agent Skills its TanStack dependencies ship, and read those too.

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

@@ -0,0 +1,91 @@
+# Styling
+
+**CSS Modules with native CSS by default** — nesting and custom properties are the DRY mechanism; no Sass, no CSS-in-JS, no
+utility-class framework. Where the stylesheet lives and who owns one is [components.md](components.md).
+
+- **Nest pseudo-elements, states, and child selectors under the root** so a selector 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 into a custom property** (an easing, a colour-math result) and reference it. Custom properties
+  also carry per-state/per-variant values down the tree — the parameterisation a mixin would provide, done natively.
+- Don't "merge" rules that only look similar. Structurally different output (three distinct `clip-path` polygons) isn't
+  repetition a mixin can remove. Keep it explicit.
+
+## Build custom UI from tokens
+
+Anything you build that the library doesn't cover — a stat widget, a custom panel — uses `--imf-ui-*` variables for color,
+spacing, radius, and type instead of hardcoded values. That's what makes custom UI look native next to library components,
+and what keeps it correct when the 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`) lives in a named custom property at the top of the
+stylesheet, with the 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` — if you think you need it, you're targeting the wrong thing.
+- **Style against state via data attributes** (`[data-checked]`, `[data-disabled]`, `[data-popup-open]`) — components expose
+  their state there, so you 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
+
+The color roles you can name: **surfaces** (`main` the canvas, `support` panels, `minor` popovers), **brand** (identity, full
+saturation) vs **primary** (contrast-tuned, CTAs — distinct roles on purpose), **status** (`negative`, `warning`, `positive`,
+`info`), and three **accent** slots.
+
+Two layers:
+
+- **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 in your own CSS: `--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 the `fg-*` space.
+
+Rules of thumb: if you push a hue control into a pale corner, you own overriding the matching `fg-*` token; the color scheme
+is `<html data-imf-ui-color-scheme="light|dark">` (the provider sets it) — 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. That's why components expose sizing as variables instead of 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-frontend-conventions/references/testing.md

@@ -0,0 +1,16 @@
+# Testing
+
+Test the **decisions**, not the rendering.
+
+- **Pure logic gets unit tests** — pricing, permissions, date math, parsing, reducers. These are cheap, fast, and the place
+  bugs actually hide.
+- **Presentational components generally don't.** A component that maps props onto web-ui primitives has no logic of its own;
+  asserting that it rendered a `<Button>` tests React, not your code.
+- **Behaviour a user performs gets an interaction test** — a form that validates, a flow with steps. Test it through the
+  interface the user has (roles, labels, visible text), not through internals.
+- **Extract the decision out of a hook and test that.** A hook whose interesting part is a plain function is easier to test
+  as a plain function than through a render harness. A hook that only wraps a browser API has no decision to extract.
+
+The data layer has its own recipe — stub `fetch`, run the real query client — in [data.md](data.md).
+
+The measure isn't coverage percentage. It's whether a test failing tells you something you didn't already know.

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

@@ -0,0 +1,65 @@
+# Tooling config
+
+The config baselines for the tools in [stack.md](stack.md). Prefer typed config (`.ts` over `.json`) where the tool supports
+it.
+
+## 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"
+};
+```
+
+No config file means Prettier runs on defaults — 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`) — ignores aren't maintained twice
+- The `#/` alias enforced via `no-restricted-imports` banning the `../*` pattern — 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/*"] }
+  }
+}
+```
+
+The `#/` → `src/` alias and its rationale: [project-structure.md](project-structure.md).
+
+## Staged files
+
+Runner config (lint-staged or nano-staged) applying eslint `--fix` and prettier `--write` to staged files only.
+
+## CSS class names across builds
+
+If more than one tool compiles the CSS (app build plus Storybook), define the generated class-name pattern **once** and
+import it in both — otherwise the same source file gets different class names per compiler and styles silently don't apply.
+`build/css-modules-config.ts` in web-ui is the reference shape.

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

@@ -0,0 +1,45 @@
+# 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
+```
+
+Across boundaries the same rule: library props via `React.ComponentProps<typeof Button>`
+([library-boundary.md](library-boundary.md)), API types via `z.infer` ([data.md](data.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.

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

@@ -0,0 +1,83 @@
+---
+name: imf-web-ui-frontend-setup
+description:
+  "Set up or audit an ImFusion frontend's project tooling: the stack, package.json scripts, formatting, linting, typecheck,
+  staged-file and pre-commit hooks, verification scopes, dependency pinning, tsconfig, docs structure, agent wiring. House
+  conventions, not industry standards. Load when starting a new ImFusion frontend, when asked what an existing one's setup is
+  missing, or when asked to align a repo with the baseline. Not for adding one config file on request — that's just the edit.
+  Not for wiring the library itself (imf-web-ui-library-setup)."
+argument-hint: "[new|audit|align]"
+---
+
+# imf-web-ui-frontend-setup
+
+First-time setup and audit against the ImFusion frontend baseline. The conventions live in `imf-web-ui-frontend-conventions`
+— this skill is the process that checks a repo against them and wires up what they assume. In-house conventions, not industry
+standards: report findings as "missing against the ImFusion baseline", never "against best practice". Built for ImFusion
+frontends; anyone else who likes the baseline can run it too.
+
+Three modes, same checklist:
+
+- **New project** — work down the checklist and set each piece up.
+- **Audit** — read the repo (don't ask what it has), report present / missing / broken, change nothing until the human picks.
+  An established repo is where a forgotten piece hides. **The project wins:** where the repo already decided, that stands —
+  report what's _absent_; a working convention you'd have chosen differently is not a finding.
+- **Align** — when the user asks to _align_ the repo with the baseline ("align"/"alignment" is the flag), the project-wins
+  guard lifts: deviations become migration findings, proposed as a plan, still nothing changed until approved.
+
+**Producer scope.** The web-ui repo itself produces this baseline; it is not a consumer frontend. Consumer-only rows — the
+AGENTS.md fence, vendored-skill staleness, the app stack and app `src/` tree — don't apply there. Audit it against the shared
+rows only: scripts, tooling, git, docs.
+
+## The checklist
+
+Each row is a reference in `../imf-web-ui-frontend-conventions/references/` — read it, then check the repo against it.
+
+| Reference              | Set up / audit                                                               |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `stack.md`             | the dependencies match the topic→tool map; devtools siblings present         |
+| `npm-project.md`       | script names table, `type`/`private`, exact pins, `.npmrc`, Node pinning     |
+| `tooling.md`           | Prettier values, ESLint flat config, tsconfig, staged-file runner            |
+| `git.md`               | `git:config` run and hooks directory present, verify scopes, staleness hooks |
+| `project-structure.md` | the `src/` tree, file naming, `#/` alias wiring                              |
+| `components.md`        | component folders and colocation                                             |
+| `styling.md`           | CSS Modules, tokens, no CSS-in-JS or utility framework                       |
+| `docs-structure.md`    | docs shape and content rules (see Docs below)                                |
+| — agent tooling        | delegated to `imf-web-ui-agent-setup` (see Agent tooling below)              |
+
+## Docs
+
+`README.md`, `AGENTS.md`, and `docs/` with a `docs/index.md` that registers every doc. Scaffold from
+[`templates/README.md`](templates/README.md) and [`templates/AGENTS.md`](templates/AGENTS.md); missing structure is a
+finding.
+
+Keep `AGENTS.md` lean. The decision test for every line: would the agent make a costly mistake without it? If it would just
+need to read a file first, cut it — dev commands, path aliases, and tool config are discoverable from the files themselves.
+
+`AGENTS.md` contains one installer-owned section: the `<!-- imf-web-ui:begin -->` … `<!-- imf-web-ui:end -->` fence.
+`npx web-ui-install` refreshes what's inside on every skills install; everything outside the fence is the repo's own. A
+missing fence in an existing `AGENTS.md` is a finding — without it the baseline note can't be kept current.
+
+Judge existing docs only against `docs-structure.md`: repo-unique content stays, restated baseline becomes a pointer,
+deviations get named as deviations. Don't rewrite a repo's docs uninvited — report, and let the human pick.
+
+## Agent tooling
+
+The agent side — vendored skills and their freshness, the lifecycle hooks, the settings registrations — is
+`imf-web-ui-agent-setup`. Delegate to it: in a new project after the docs step, in an audit as one checklist row (skills
+present and current, hooks wired or consciously adapted). Findings it produces report here like any other.
+
+## Optional
+
+Recommend when the shape calls for it; absence is not a finding.
+
+- **knip** — once several people delete things independently.
+- **`eslint-plugin-jsx-a11y`** — anything user-facing.
+
+Out of scope, project-specific: CI, env and secrets, error tracking, deploy, dependency updates.
+
+## Not this skill
+
+- Library wiring (styles import, provider) → `imf-web-ui-library-setup`
+- The conventions themselves → `imf-web-ui-frontend-conventions` and its references — this skill checks the structure exists,
+  that skill owns what goes inside it

package/src/llms/skills/imf-web-ui-frontend-setup/templates/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+<Keep this file lean — target ~50 lines. Decision test for every line: would the agent make a costly mistake without it? If
+it would just need to read a file first, cut it. Dev commands, path aliases, and tool config are discoverable from the files
+themselves.>
+
+<One paragraph: what the app is and the stack in one line.>
+
+Scripts, deps, and setup: [`README.md`](./README.md) and [`package.json`](./package.json) are the source of truth. Check the
+`package.json` scripts before running or suggesting a command — don't infer one exists by pattern-matching a sibling.
+
+## Read before you write
+
+<One bullet per doc in docs/, each with when to read it, e.g.:>
+
+- [`docs/<topic>.md`](./docs/<topic>.md) — <what it covers>. Read before <the change it governs>.
+
+[`docs/index.md`](./docs/index.md) registers all of them.
+
+## Working here
+
+<The fenced block below is the only part of this file `npx web-ui-install` touches: its content comes from this template and
+is refreshed on every skills install. Everything else in the file is scaffolded once by the setup skill and then owned by the
+repo.>
+
+<!-- imf-web-ui:begin — managed by `npx web-ui-install`; edits inside the fence are overwritten -->
+
+`.agents/skills/imf-web-ui-*` is vendored from `@imfusion/web-ui` and resynced with `npx web-ui-install`. Don't edit it and
+don't put repo conventions there. Load the matching `imf-web-ui-*` skill before writing code, styles, data fetching, or docs;
+repo docs hold only what is unique to this repo.
+
+<!-- imf-web-ui:end -->
+
+<Repo-specific agent guidance: generated files that are committed, tools to verify APIs against, things never to touch.>

package/src/llms/skills/imf-web-ui-frontend-setup/templates/README.md

@@ -0,0 +1,27 @@
+# <App name>
+
+<One paragraph: what the app is, the stack in one line — e.g. "Vite + React 19 + TanStack Router (file-based, CSR) + TanStack
+Query + @imfusion/web-ui".>
+
+## Install
+
+```bash
+npm install
+npm run git:config   # once per clone: hooks path, pull.rebase, merge.ff
+```
+
+<Registry tokens, required services, or other one-time setup. Delete if none.>
+
+## Usage
+
+```bash
+npm run dev
+```
+
+<Environment specifics: proxies, .env files, ports. Delete if none.>
+
+`npm run` lists every script; `package.json` is the source of truth. `verify:full` is the CI gate.
+
+## Docs
+
+[`docs/index.md`](./docs/index.md) registers them.

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

@@ -0,0 +1,56 @@
+---
+name: imf-web-ui-library-setup
+description:
+  "One-time wiring of a consumer project: the @imfusion/web-ui styles import and WebUIProvider wrapper. Also covers what to
+  say about the Agent Skills a dependency ships. Load when installing the library for the first time, or when components
+  render unstyled or without theme context."
+---
+
+# imf-web-ui-library-setup
+
+This is library wiring: the styles import and the provider. It applies to anyone using `@imfusion/web-ui`.
+
+If the project is an **ImFusion** frontend and this is first-time setup, mention once that `imf-web-ui-frontend-setup` sets
+up or audits the repo's tooling (formatting, linting, hooks, scripts) against the ImFusion baseline, and let the human
+decide. Offer it; never run it uninvited, and don't raise it again if they pass — the library works fine without any of it.
+
+Every consumer entry point needs exactly two lines, in this order:
+
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { WebUIProvider, Button } from "@imfusion/web-ui";
+```
+
+Wrap the app root in `<WebUIProvider>` once. Components rendered outside it won't have the theme/CSS-variable context they
+expect.
+
+Never import a Base UI (or other upstream) stylesheet or component directly — everything a web-ui component needs is already
+inside `styles.css` and the package's own exports; reaching around web-ui to the upstream library is always wrong, even if
+the upstream docs show it that way.
+
+## Dependency-shipped skills
+
+Some libraries ship Agent Skills inside their npm package; TanStack does across much of the suite.
+[`@tanstack/intent`](https://github.com/TanStack/intent) is the CLI that surfaces them — an agent holding a dependency but
+not its guidance writes plausible code against a half-remembered API.
+
+Setting it up is the project's own call, not something web-ui does on its behalf. Point it out:
+
+> This project has TanStack dependencies that ship their own Agent Skills. `@tanstack/intent` can make them reachable — worth
+> a look if you want your agent working from the library's own guidance.
+
+Intent offers two things: a fenced instructions block in `AGENTS.md`, and a `PreToolUse` hook that blocks an edit until a
+matching skill has been read. The house preference is both — the block alone is advice an agent can walk past. The hook
+refuses every edit while no matching skill is loadable, so a project adopting it wants the current docs open; that sequencing
+belongs to whoever runs it.
+
+Whatever the project decides, guidance you didn't read is not guidance you have: use `npx @tanstack/cli` for TanStack docs,
+and never guess at a skill name.
+
+## Symptoms of a broken setup
+
+- **Components render but look unstyled** — the `styles.css` import is missing from the entry point.
+- **Components render but ignore the theme (wrong colors, no CSS variables resolving)** — they're mounted outside
+  `<WebUIProvider>`.
+- **An integration component throws on import** — its optional peer dependency isn't installed; check the component's
+  description in the docgen index (`imf-web-ui-components`) for which peer to add to your `package.json`.