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

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

@@ -0,0 +1,133 @@
+# Code conventions
+
+The ImFusion defaults for everyday code around `@imfusion/web-ui` — the parts that aren't React-specific. TypeScript, file
+organisation, naming, and testing. React component structure lives in [react-patterns.md](react-patterns.md); the two are
+read together when starting new code.
+
+These fill vacuums. Where the host project has already decided, the project wins.
+
+## TypeScript
+
+- **`any` is forbidden.** `unknown` at a boundary you genuinely can't type, narrowed before use. An `any` that silences an
+  error moves the failure from compile time to runtime, which is the opposite of the trade you wanted.
+- **Lean on inference for locals; annotate the contract.** Restating a type the compiler already knows inside a function body
+  is a second thing to keep in sync. An **explicit return type on an exported function is worth writing**: it's the promise
+  the module makes, it stops an internal refactor silently widening the public shape, and it makes the error surface at the
+  function rather than at every call site.
+- **No temporal coupling.** Don't initialise to `null` and fill the value in later — model the states instead, so "not loaded
+  yet" and "loaded, empty" aren't the same value.
+- **Avoid `as`.** A type assertion tells the compiler to stop checking exactly where checking is worth most. Fix the type.
+  Assertions at an untyped third-party boundary are the honest exception; keep them at the boundary, not spread through call
+  sites.
+
+**Derive types, don't duplicate them.** One source of truth, everything else follows from it:
+
+```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
+```
+
+The same rule crosses the library boundary: prop types come from the components themselves
+(`React.ComponentProps<typeof Button>`), never re-declared by hand.
+
+**Function signatures.** One or two positional arguments read fine. At three or more, take a single object and destructure —
+call sites stop depending on argument order, and adding a parameter stops being a breaking change.
+
+## Expressions over statements
+
+Reach for the array methods before the loop. `map`, `filter`, `find`, `some`, `every`, `flatMap`, `reduce` — each names what
+it's doing, where a `for` loop makes you read the body to find out.
+
+```ts
+// The name is the documentation
+const activeNames = users.filter(u => u.isActive).map(u => u.name);
+
+// vs. a loop you have to read to understand
+const activeNames = [];
+for (const u of users) {
+  if (u.isActive) activeNames.push(u.name);
+}
+```
+
+The deeper reason is mutation: the method chain produces a new value, so nothing else can observe a half-built array. Prefer
+spreads and `structuredClone` over in-place edits, and `toSorted`/`toReversed` over `sort`/`reverse`, which mutate their
+receiver and have surprised everyone at least once.
+
+Two honest exceptions: a genuine early exit (`for` with `break` beats `find` returning a sentinel) and a hot loop over
+thousands of items where the intermediate arrays actually measure. Neither is the common case, so reach for the method first
+and justify the loop.
+
+Keep the chain flat. Three or four steps read well; ten want intermediate named constants, and a `reduce` doing four things
+at once wants to be a loop after all.
+
+## Naming
+
+- Say what it is, not what it is made of. `useUserQuery`, not `useUserHook`. `retryDelay`, not `num`.
+- Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`. A boolean called `status` will end up holding a string.
+- Handlers are `onX` as props, `handleX` as implementations — the prop names the event, the function names the response.
+- Match the vocabulary the product and the API already use. Inventing a synonym for a term the backend already named costs a
+  translation step on every read.
+
+## File and folder organisation
+
+Kebab-case throughout, folders and files.
+
+```
+src/
+  routes/          # TanStack Router file-based routes; routing only
+  api/<topic>/     # <topic>.ts (queries/mutations), query-key.ts, types.ts
+  components/      # grouped by kind of component — layouts/, primitives/, or a domain name
+  http/            # client, error normalisation
+  lib/             # framework-free helpers
+```
+
+`api/` groups by topic: a query lives next to its key factory and its types, so a query key is never spelled out at a call
+site. Routes compose and don't fetch inline. Transport concerns live in `http/` and nowhere else.
+
+`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 has rather than imposing it up front. The kinds worth separating are the
+component roles in [react-patterns.md](react-patterns.md): dumb components, layout components, smart containers.
+
+A component gets a folder once it has more than one file, with an `index.ts` that only re-exports:
+
+```
+components/data-table/
+  data-table.tsx
+  data-table-row.tsx
+  data-table.module.css
+  index.ts
+```
+
+Colocate tests, styles, and types with their subject. A file you have to hunt for in a parallel tree gets edited less
+carefully.
+
+## Styling
+
+**CSS Modules by default**, colocated as `<component>.module.css`. No CSS-in-JS, no utility-class framework. Compose from
+`--imf-ui-*` tokens so custom UI stays consistent with library components and follows the theme; the override contract (CSS
+layers, `data-imf-ui-component`, never the library's generated class names) is in the parent skill.
+
+`imf-web-ui-imfusion-frontend-setup` sets up or audits this structure on an ImFusion project.
+
+## 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 measure isn't coverage percentage. It's whether a test failing tells you something you didn't already know.
+
+## Formatting and linting
+
+Don't argue about it in review — the tooling decides, and it runs before the commit lands. A formatter, a linter, and a
+pre-commit hook wired so none of them is optional. On an ImFusion project, `imf-web-ui-imfusion-frontend-setup` carries the
+baseline and the setup steps.

package/src/llms/skills/imf-web-ui-frontend-patterns/references/react-patterns.md

@@ -0,0 +1,94 @@
+# React patterns
+
+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
+asked.
+
+## Component roles
+
+Dumb/smart separation is standard React practice (it traces back to Dan Abramov's
+["Presentational and Container Components"](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) and
+survives in [Thinking in React](https://react.dev/learn/thinking-in-react)). The house version has three roles:
+
+- **Dumb components** own how things _look_. They style and compose library primitives, receive plain data and callbacks as
+  props, and know nothing about fetching, routing, or business logic. All non-layout styling lives here — and only here.
+- **Layout components** own _arrangement_ — and nothing else. `Stack`- and `Row`-based wrappers with token gaps, a page grid,
+  a section frame. They exist because smart containers are styleless: when a container needs two panels side by side, that
+  arrangement is a layout component, not an inline style.
+- **Smart containers** own how things _work_. Routes (or explicit container components) fetch data, hold orchestration logic,
+  and wire the other two together. Zero styling — the moment a container wants CSS, extract a layout component.
+
+```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>
+  );
+}
+
+// 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} />;
+}
+```
+
+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.
+
+## Compose, don't configure
+
+Build screen-level pieces by composing primitives (`Stack`, `Row`, `Card`, your dumb components) rather than growing one
+component with a dozen boolean props. If a component's prop list reads like a settings page, it wanted to be two or three
+components. When state must be shared between siblings, lift it to the nearest common parent —
+[Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — rather than syncing copies.
+
+## Put state where its truth lives
+
+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`.
+
+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
+reference — especially its rules on avoiding redundant and duplicated state.
+
+## Effects: last resort, and named
+
+Before writing `useEffect`, check: derived values belong in render (or `useMemo`), responses to user actions belong in the
+event handler, and server synchronization belongs in the data-fetching layer. Effects are for synchronizing with systems
+_outside_ React. The definitive catalog of effect misuses — read it before every effect you're tempted to write — is
+[You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect).
+
+When an effect is genuinely needed, extract it into a custom hook named for its purpose — `useSyncedScroll`,
+`useDocumentTitle`, `useHotkey` — never an anonymous `useEffect` block inline in a component. The name documents intent, the
+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).
+
+## 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-imfusion-frontend-setup/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: imf-web-ui-imfusion-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, folder structure. House conventions,
+  not industry standards. Load when starting a new ImFusion frontend, or when asked what an existing one's setup is missing.
+  Not for adding one config file on request — that's just the edit. Not for wiring the library itself (imf-web-ui-setup)."
+---
+
+# imf-web-ui-imfusion-frontend-setup
+
+ImFusion house conventions, **not** industry standards. Report as "missing against the ImFusion baseline", never "against
+best practice". Only apply to an ImFusion frontend.
+
+Two modes, same list:
+
+- **New project** — work down the list and set each piece up.
+- **Existing project** — 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.
+
+## The stack
+
+| Concern      | Tool                                                      | Notes                                                                               |
+| ------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Format       | [Prettier](https://prettier.io)                           | Values below are shared across repos                                                |
+| Lint         | [ESLint](https://eslint.org) flat config                  | `--cache --max-warnings=0`                                                          |
+| Types        | `tsc --noEmit`                                            | Own script, own CI step                                                             |
+| Staged files | [lint-staged](https://github.com/lint-staged/lint-staged) | [nano-staged](https://github.com/usmanyunusov/nano-staged) is a drop-in alternative |
+| Routing      | [TanStack Router](https://tanstack.com/router)            | File-based, `src/routes/`                                                           |
+| Server state | [TanStack Query](https://tanstack.com/query)              | Query keys colocated per API topic                                                  |
+| Client state | [TanStack Store](https://tanstack.com/store)              | Only for state that isn't URL- or server-owned                                      |
+| Styling      | CSS Modules                                               | Colocated `<component>.module.css`                                                  |
+| Dead code    | [knip](https://knipjs.dev)                                | Needs per-repo config                                                               |
+| Build        | [Vite](https://vite.dev)                                  |                                                                                     |
+| Test         | [Vitest](https://vitest.dev)                              |                                                                                     |
+
+Either staged-file runner is fine; lint-staged is the larger project and the safer default when one misbehaves.
+
+### Devtools come with the library
+
+Every TanStack library that ships a devtools package gets it as a dev dependency alongside the library itself, mounted in
+development only. Router is a given in any ImFusion frontend, so `@tanstack/react-router-devtools` is a given too; Query's
+goes in when Query does, and so on. Look for a `-devtools` sibling whenever you add a TanStack dependency rather than working
+from a fixed list — the set grows, and not every library has one yet (Store doesn't). Once a project has several,
+`@tanstack/devtools` hosts them in one panel.
+
+## package.json
+
+`"type": "module"`, `"private": true`. Scripts — these names, in every repo:
+
+| Script             | Runs                                                     |
+| ------------------ | -------------------------------------------------------- |
+| `dev`              | dev server                                               |
+| `build`            | production build                                         |
+| `verify:lint`      | `eslint . --cache --max-warnings=0`                      |
+| `verify:format`    | `prettier --check .`                                     |
+| `verify:typecheck` | `tsc --noEmit`                                           |
+| `verify:tests`     | `vitest run`                                             |
+| `verify:staged`    | staged-file subset, called by the pre-commit hook        |
+| `verify:full`      | every check above plus the build; what CI runs           |
+| `format`           | `prettier --write .`                                     |
+| `lint:fix`         | `eslint . --cache --fix`                                 |
+| `git:config`       | `git config core.hooksPath …` + `pull.rebase`/`merge.ff` |
+
+**Every check is `verify:*`.** One namespace, so "what can I run to check this?" is answered by tab-completion. Write-mode
+scripts keep tool names — `format` and `lint:fix` change files, which isn't verifying. Same name, same meaning, every repo.
+
+**Git config is an explicit command.** `git:config` holds the real command, greppable and run by hand after cloning, and the
+README's setup steps name it. `ignore-scripts=true` disables the root package's own lifecycle scripts alongside its
+dependencies', so setup that matters is a command someone runs, not a hook that fires on install.
+
+**Dependencies pinned exactly.** No `^`, `~`, or `latest`, in `dependencies` and `devDependencies` alike. A check script in
+the verify chain enforces it, but that only catches drift after it lands — `save-exact=true` in `.npmrc` stops `npm install`
+reintroducing ranges in the first place.
+
+## Config
+
+**Prettier** — config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
+
+```
+printWidth: 125   tabWidth: 2   useTabs: false   trailingComma: "none"
+arrowParens: "avoid"   semi: true   singleQuote: false   proseWrap: "always"
+```
+
+No config file at all means Prettier runs on defaults — flag it, the values silently differ.
+
+**ESLint** — flat config (`eslint.config.ts`), `strictTypeChecked` + `stylisticTypeChecked` with `projectService: true`, `as`
+and `!` banned outside tests, and `.gitignore` as the ignore source (`includeIgnoreFile` from `@eslint/compat`) so ignores
+aren't maintained twice.
+
+**tsconfig** — defaults:
+
+```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 alias is always `#/` → `src/`. `#` is Node's own subpath-import prefix, so it resolves without a bundler-specific
+convention, and it can't collide with an npm scope the way `@/` does.
+
+**Staged files** — runner config applying eslint `--fix` and prettier `--write` to staged files only.
+
+**Pre-commit** — the hook installs itself via `prepare` → `git:config`, which sets `core.hooksPath` to a tracked directory
+plus `pull.rebase true` and `merge.ff only`, so history strategy doesn't depend on personal git config. Two silent failure
+modes: no `prepare` at all (hooks exist only on the machine that ran `git config` by hand), and `core.hooksPath` pointing at
+a directory that doesn't exist. Check 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** — optional 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 name like
+`preflight` needs explaining and invites a second, near-identical script beside it. Two of those drift, and the drift reads
+as "passes locally, fails in CI".
+
+**Node pinning** — `.nvmrc` or `engines.node`. Not a personal version manager's config; that pins it for you alone.
+
+## Folder structure
+
+```
+src/
+  routes/                    # TanStack Router file-based routes; nothing but routing
+  api/<topic>/               # one folder per API topic
+    <topic>.ts               #   queries/mutations
+    query-key.ts             #   key factory
+    types.ts                 #   request/response types
+  components/                # see below
+  http/                      # client, error normalisation — the only transport-aware place
+  lib/                       # framework-free helpers
+```
+
+Everything is kebab-case, folders and files alike.
+
+**Inside `components/`, group by what kind of component it is** — `layouts/`, `primitives/`, `forms/`, or a domain name. Not
+a hard rule: a handful of components reads fine flat, and the grouping should follow what the project actually has rather
+than a structure imposed up front. But most codebases grow past flat, and a clear layout component belongs under `layouts/`
+rather than beside a domain widget.
+
+```
+components/
+  page-header/               # flat is fine
+  layouts/
+    page-shell/
+  data-table/                # a component with sub-component files
+    data-table.tsx
+    data-table-row.tsx
+    data-table.module.css
+    index.ts
+```
+
+A component gets a folder when it has more than one file — sub-components, styles, tests. Single-file components can stay
+single files. The folder's `index.ts` only re-exports, so imports read `#/components/data-table` and the inside can be
+restructured without touching call sites.
+
+Routes stay thin: they compose, they don't fetch inline. `api/<topic>/` holds the query and its key factory together so a key
+is never spelled out at a call site. Anything transport-level (base client, error normalisation) lives in `http/` and nowhere
+else.
+
+## Styling
+
+CSS Modules by default, colocated as `<component>.module.css` next to the component. No CSS-in-JS, no utility-class
+framework.
+
+On a project using `@imfusion/web-ui`, style through the sanctioned seams — `--imf-ui-*` tokens and `data-imf-ui-component`
+attributes, never the library's generated class names. `imf-web-ui-frontend-patterns` covers that contract.
+
+If more than one tool compiles the CSS (app build plus Storybook), the generated class-name pattern must be defined **once**
+and imported by both, or the same source file gets different class names in each and styles silently don't apply.
+`build/css-modules-config.ts` in web-ui is the reference shape; pick your own prefix.
+
+## Optional
+
+Recommend when the shape calls for it; absence is not a finding.
+
+- **knip** — once several people delete things independently.
+- **`ignore-scripts=true` in `.npmrc`** — blocks most supply-chain worm payloads; costs an explicit `npm rebuild` for native
+  deps.
+- **`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-setup`
+- Code conventions (TypeScript, naming, testing) → `imf-web-ui-frontend-patterns`, `references/code-conventions.md`

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

@@ -1,87 +1,57 @@
 ---
 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
+  "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-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.
+This is library wiring: the styles import and the provider. It applies to anyone using `@imfusion/web-ui`.
 
-## Workflow
+If the project is an **ImFusion** frontend and this is first-time setup, mention once that
+`imf-web-ui-imfusion-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.
 
-1. Resolve the argument, not the prose. Bare means `full`; a topic argument selects one supported setup topic. A prompt that
-   merely _mentions_ one area ("wire up the tooling", "get the project set up") is still a `full` run — the words describe a
-   starting point, not a scope that excludes the rest. For a greenfield `full` run the application boundary (router, route
-   groups, current-user query, AppShell) is part of the deliverable even when the prompt never names it; propose it and let
-   the human remove it, never silently defer it as "out of scope." For an unsupported topic argument, list the available
-   setup topics and point the human to `imf-web-ui-audit` for a read-only report.
-2. Enter the host's plan mode. If it is not already active, use the host plan-mode control before inspecting and planning.
-3. Read the selected convention topics and inspect the repository with `Read`, `Glob`, and `Grep` only.
-4. Build the complete proposal in the host plan from the shared report contract at
-   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md). Include the concrete
-   content of every file the approved setup would create or change, with repository evidence for each decision.
-5. A greenfield `full` setup proposes the whole starter skeleton, not just tooling — tooling without the application boundary
-   is an unfinished setup. Include, as concrete files in the plan:
-   - the TanStack Router **package added to `package.json`** (with its router devtools as a dev dependency), not just
-     imported — code that imports an uninstalled package is an incomplete setup
-     ([project-structure.md](../imf-web-ui-conventions/topics/project-structure.md));
-   - pathless `_public/` and `_app/` route groups behind one server-backed current-user boundary
-     ([authentication.md](../imf-web-ui-conventions/topics/authentication.md));
-   - the minimal branded `AppShell` in `_app/` by default — omit the shell only when the human explicitly says the product
-     has no persistent authenticated navigation (ask first), but keep the `_app/` boundary either way;
-   - a per-topic `api/` folder for any data the first screen shows, never an inline fixture in the component
-     ([data.md](../imf-web-ui-conventions/topics/data.md)).
+Every consumer entry point needs exactly two lines, in this order:
 
-   The plan documents this starter shape as concrete file content; it does not copy a full external starter template.
-   Existing projects keep their working choices — propose only the gaps.
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { WebUIProvider, Button } from "@imfusion/web-ui";
+```
 
-6. Keep the plan as the approval gate. After the host approves and exits plan mode, write only the listed files. Complete any
-   immediately requested bootstrap work covered by that approved plan, then invoke `imf-web-ui-audit full` as a verification
-   step and review the findings it reports back before declaring the setup complete. The audit stays out of plan mode here —
-   the human has just left it to let this work happen.
+Wrap the app root in `<WebUIProvider>` once. Components rendered outside it won't have the theme/CSS-variable context they
+expect.
 
-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.
+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.
 
-## Checklist
+## Dependency-shipped skills
 
-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.
+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.
 
-## Safety
+Setting it up is the project's own call, not something web-ui does on its behalf. Point it out:
 
-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.
+> 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.
 
-## Setup topics
+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.
 
-`full` covers every topic below. A one-topic run assesses only that topic.
+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.
 
-| 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   |
+## Symptoms of a broken setup
 
-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`.
+- **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`.

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-conventions`; project wiring lives in the `library-setup` topic of `imf-web-ui-conventions`.
+`imf-web-ui-frontend-patterns`; project wiring lives in `imf-web-ui-setup`.
 
 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-conventions`.
+`imf-web-ui-frontend-patterns`.
 
 ## 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-conventions`) so a breaking change lands in one file,
-not forty call sites.
+movement across releases — prefer wrapping them once (see `imf-web-ui-frontend-patterns`) 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-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-frontend-patterns`), and
+these rules govern how its errors get presented.
 
 ## Structure