@imfusion/web-ui 0.5.1-dev.7.ga571658e → 0.6.0

package/src/llms/skills/imf-web-ui-conventions/templates/REPORT.md

@@ -0,0 +1,45 @@
+# Frontend Report
+
+Mode: `<setup|audit>` Scope: `<all applicable topics or the resolved topic>`
+
+<!--
+This template is the report contract. Keep every H2 below once and in this order.
+Use `None.` for an empty section.
+
+Broken, Missing, Deviations, and Unverified entries use:
+- **[high|medium|low] reference-or-agent-tooling — Short title**
+  - Evidence: `path:line`
+  - Impact: concrete consequence
+  - Next action: smallest selectable follow-up
+
+Present entries name the topic and evidence path. Deviations are selectable follow-up work, not defects. Optional tools are not
+missing findings.
+-->
+
+## Verdict
+
+<One short assessment of the current frontend setup.>
+
+## Broken
+
+None.
+
+## Missing
+
+None.
+
+## Deviations
+
+None.
+
+## Present
+
+None.
+
+## Unverified
+
+None.
+
+## Reviewer notes
+
+<!-- Human-owned. Preserve everything under this heading verbatim when refreshing the report. -->

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

@@ -0,0 +1,82 @@
+# Agent tooling
+
+How a consumer repo carries the `@imfusion/web-ui` agent tooling; `npx web-ui-install` does the mechanics, this topic carries
+the judgment.
+
+## The skill bundle
+
+- `npx web-ui-install` installs or refreshes the vendored `imf-web-ui-*` skills, refreshes the
+  `<!-- imf-web-ui:begin/end -->` fence in an existing `AGENTS.md`, and removes skills dropped from the bundle.
+- Target: remembered first-run choice — `.claude/skills/`, vendor-neutral `.agents/skills/`, or both (`.agents/` real copy,
+  `.claude/` symlink); `--reconfigure` re-opens it, `--target claude|agents` selects non-interactively.
+- Staleness: per-skill `.imf-web-ui-skill-version.json`; a marker older than the installed package means re-run the binary —
+  never hand-diff or hand-edit vendored skill contents.
+
+## The hooks
+
+- `npx web-ui-install --hooks` adds three injection hooks and a turn-end gate.
+- Scripts in `.agents/hooks/imf-web-ui/` are installer-owned: refreshed wholesale each run, retired scripts pruned with their
+  registrations.
+- Registrations merge idempotently into `.claude/settings.json` (Claude Code) and `.codex/hooks.json` (Codex), never touching
+  entries the installer didn't write.
+
+- **SessionStart** — once per session: points the agent at the `imf-web-ui` skills router.
+- **SubagentStart** — the same line, byte for byte, for each spawned subagent; subagents don't reliably inherit the parent
+  session's context.
+- **UserPromptSubmit** — one line per prompt naming the companion skills to consult.
+- **Stop** — the verify gate: when the turn edited source files, it blocks the agent from finishing once, with the
+  instruction to run the project's verification and fix what it reports. Re-entry is detected from the payload, so the gate
+  can never loop; a turn that edited nothing passes untouched.
+
+```mermaid
+flowchart LR
+    SS(["SessionStart<br/>once per session"]) --> ss["session-start.sh"]
+    SA(["SubagentStart<br/>per spawned subagent"]) --> sa["subagent-start.sh"]
+    UP(["UserPromptSubmit<br/>every prompt"]) --> up["user-prompt-submit.sh"]
+    ST(["Stop<br/>turn ends after edits"]) --> st["stop.sh"]
+    ss --> router["injects the router pointer:<br/>start at imf-web-ui"]
+    sa --> router
+    up --> hints["injects the per-task hints:<br/>components · conventions · ux"]
+    st --> gate["blocks once:<br/>run verification first"]
+    router --> agent["agent routes to the right<br/>companion skill"]
+    hints --> agent
+    gate --> agent2["agent verifies,<br/>then finishes"]
+```
+
+- Each injection hook echoes one fixed line and exits 0; the router does the task-sorting a shell script can't — why a hint
+  on every prompt isn't noise.
+- `baseline-staleness.sh` ships alongside but is not an agent hook; the repo's pre-commit calls it ([git.md](./git.md),
+  staleness at commit time).
+- Never edit an installed script — the next install overwrites it; adapt in the repo's own hooks.
+- Registration entries are yours: the installer matches by script name and keeps edited commands across re-runs. Monorepo:
+  the Codex commands anchor at `$(git rev-parse --show-toplevel)` — adjust their paths once after installing when the
+  frontend isn't the git toplevel.
+- **Read the registration files before installing**; per event: nothing registered → install as shipped; already covered by
+  the repo (its own session reminder, say) → don't stack a second hook — fold the missing line into the repo's script, or
+  adapt the shipped one and register that; surface it and let the human pick.
+
+## Codex trust
+
+- Codex runs a project's hooks only when two trust gates hold: the project itself is trusted, and each hook script has been
+  trusted via the `/hooks` review, which keys trust to the script's hash.
+- Until then hooks are skipped, and skipped silently — from outside, a skipped hook and a hook that ran and said nothing look
+  identical.
+- After installing or updating hooks, tell the user to trust the project and review `/hooks` in Codex, and again after any
+  hook script changes.
+- When a hint doesn't show up, check trust before debugging the script.
+- Claude Code has no trust gate for project hooks.
+
+## Dependency-shipped skills
+
+- npm packages can ship Agent Skills of their own; TanStack does — [tooling.md](./tooling.md) covers TanStack Intent and its
+  allowlist.
+
+## Hook docs
+
+Both hosts move fast; read the current references before adapting or adding a hook — payloads and stdout rules differ per
+host and per event.
+
+- [Claude Code: hooks reference](https://code.claude.com/docs/en/hooks) — event list, JSON input and output, exit codes,
+  `disableAllHooks`
+- [Codex: hooks](https://learn.chatgpt.com/docs/hooks) — events, the `hooks.json` schema, trust, `/hooks`
+- [Codex: config reference](https://learn.chatgpt.com/docs/config-file/config-reference) — `[features]` and `[hooks.state]`

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

@@ -0,0 +1,27 @@
+# Assets
+
+## Importing
+
+- 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 — visually lossless on photos, routinely an order of magnitude smaller.
+- `method=6` — densest encoding; a one-off cost at conversion time, so take the smaller file.
+- Long edge ≤ 2000px — nothing on the market resolves more in a content image.
+- No `<picture>` fallback — 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.
+
+## Scope
+
+- Rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep — convert
+  opportunistically.

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

@@ -0,0 +1,65 @@
+# Authentication
+
+One route-protection shape for every frontend; provider, session mechanism, endpoint paths, and login/logout transport stay
+project-owned — no provider is prescribed or named.
+
+## Starter shape
+
+- Authentication sits at the route-group boundary, before child routes render.
+- `_public/` and `_app/`: pathless TanStack Router groups — guards and layouts without `public`/`app` in the URL.
+- The authenticated group keeps this shape even without an `AppShell`.
+
+```text
+src/
+  api/auth/            # getUser query options, keys.ts, types.ts, index.ts barrel
+  lib/auth/
+    login-url.ts       # pure login navigation helper; not an API topic file
+    login-url.test.ts  # focused helper tests
+  routes/
+    __root.tsx         # global Outlet and error/not-found boundaries; no auth guard
+    _public/route.tsx  # anonymous route group
+    _app/route.tsx     # authenticated route group
+```
+
+## One current-user query
+
+- One identity source of truth: a server-backed current-user query; never copy session credentials or access tokens into
+  React state.
+- The auth topic follows the default [data.md](data.md) shape: `getUser` in `api/auth/queries.ts`, key leading with the
+  `auth` topic, schema in `types.ts`.
+- `lib/auth/login-url.ts`: project-owned navigation helper, not an options factory; tests colocated.
+- Reached as `context.api.auth.getUser()`; returns query options, never a hook or a user value — callers pick
+  `ensureQueryData` or a query hook.
+- Never infer authentication from local storage, a decoded token, a route flag, or permission-gated chrome — stale or
+  forgeable; the server response and its schema define the current user.
+
+## The two route groups
+
+Both resolve the current-user query in `beforeLoad` when they need the answer; only the meaning of a 401 differs:
+
+| Group      | 401 means         | Result                                      |
+| ---------- | ----------------- | ------------------------------------------- |
+| `_app/`    | not logged in     | navigate to the server-owned login endpoint |
+| `_public/` | anonymous visitor | continue with `user: null`                  |
+
+- The `_app/route.tsx` guard awaits the query before children render, converts only an authentication 401 into login
+  navigation, rethrows router redirects, and lets 5xx, connection failures, and schema mismatches reach the error boundary.
+- A public landing route may redirect an authenticated user into `_app/`.
+- The root route stays neutral: global `Outlet` and error/not-found boundaries, no public/authenticated decision.
+
+## Login and logout
+
+- Follow the project's documented transport. Server-owned flow: login is a browser navigation, not a Query fetch; logout is
+  the server's documented state-changing action, not an ad-hoc client request.
+- Preserve a validated same-origin return path when the server supports returning to the interrupted route.
+- Never hard-code an endpoint shape or provider into shared frontend conventions.
+- No intermediate login route when the server owns the flow.
+- A failed API request is an auth failure only when its typed error is specifically a 401.
+
+## App shell
+
+- `AppShell` is authenticated chrome, not the authentication mechanism.
+- Greenfield default: propose a minimal shell — ImFusion logo, route navigation, stable session action area around the
+  `_app/` outlet.
+- An explicit no-persistent-navigation decision may omit the shell; the `_app/` guard stays.
+- An established project keeps its working choice; public pages may use a small branded header.

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

@@ -0,0 +1,50 @@
+# Class names in components
+
+How a component turns props into a `className` string. What the build does with the result: [tooling.md](tooling.md); what
+goes in the stylesheet: [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, re-exported by `@imfusion/web-ui` — import it from the library alongside the components.
+- 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.
+- 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.
+
+```tsx
+interface Props extends HTMLAttributes<HTMLSpanElement> {
+  appearance?: "outline" | "solid";
+  inline?: boolean;
+}
+
+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 })} />;
+}
+```
+
+## Merging `className`
+
+- Every component that accepts `className` merges it; a deliberately closed surface omits the prop entirely rather than
+  accepting and ignoring it.
+- 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.
+- 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)}
+```
+
+## Shared CVA modules
+
+- 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-conventions/topics/components.md

@@ -0,0 +1,101 @@
+# Components
+
+How a component lives on disk and how dumb it stays. Roles, state, effects: [react.md](react.md); styling:
+[styling.md](styling.md).
+
+## As dumb as possible
+
+- Props-fed, never self-fetching: no query hook, no store access, no route awareness — render what's given, report events
+  upward.
+- Presentational logic (formatting a label, deriving a display state) is fine; owning data is not.
+- Local UI state (`isOpen`, a draft value) is allowed; anything whose truth lives elsewhere is not ([react.md](react.md)).
+
+```tsx
+// components/user-card/user-card.tsx
+interface Props {
+  name: string;
+  onEdit: () => void;
+}
+
+export function UserCard({ name, onEdit }: Props) {
+  return (
+    <Card.Root>
+      <Typo>{name}</Typo>
+      <Button onClick={onEdit}>Edit</Button>
+    </Card.Root>
+  );
+}
+```
+
+## Grouping
+
+- `components/` groups by kind (the component roles in [react.md](react.md)) — a layout component under `layouts/`, not
+  beside a domain widget.
+- Flat is fine while there are few; let grouping follow what the project has, don't impose it up front.
+
+## One file or a folder
+
+- More than one file (sub-components, styles, tests) → a folder with an `index.ts` that only re-exports; single-file
+  components stay single files, directly in their group.
+- Imports read `#/components/data-table`, so the inside can be restructured without touching call sites.
+
+The full anatomy of a folder component:
+
+```
+components/data-table/
+  data-table.tsx           # the component: props type + export, CVA variants when it has axes
+  data-table-row.tsx       # sub-component, private unless index.ts re-exports it
+  data-table.module.css    # co-located stylesheet (styling.md)
+  data-table.test.tsx      # only when the component carries decisions worth testing (testing.md)
+  index.ts                 # re-exports only
+```
+
+Most components need only a subset — start with the `.tsx`, add files as they earn their place.
+
+```tsx
+// data-table.tsx — CVA even with one variant axis, so future axes slot in (class-names.md)
+import { cva, type VariantProps } from "class-variance-authority";
+import classes from "./data-table.module.css";
+
+const dataTable = cva(classes.root, {
+  variants: { density: { comfortable: classes.densityComfortable, compact: classes.densityCompact } }
+});
+
+// Intersection, not `interface extends` — VariantProps is an object type. Defaults live in the destructuring.
+type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof dataTable> & { rows: TableRow[] };
+
+export function DataTable({ className, density = "comfortable", rows, ...props }: Props) {
+  return (
+    <div {...props} className={dataTable({ density, className })}>
+      {/* … */}
+    </div>
+  );
+}
+```
+
+```css
+/* data-table.module.css — native nesting + library tokens, no preprocessor, no @layer (styling.md) */
+.root {
+  border-radius: var(--imf-ui-border-radius-2);
+  font-size: var(--imf-ui-font-size-1);
+
+  &:focus-visible {
+    /* states nest under the root */
+  }
+}
+
+.densityCompact {
+  /* one class per CVA variant value */
+}
+```
+
+```ts
+// index.ts — re-exports only; callers import #/components/data-table
+export { DataTable } from "./data-table";
+```
+
+## Colocation
+
+- Stylesheet: `<component>.module.css` next to the component; 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: a file hunted for in a parallel tree gets edited less carefully.

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

@@ -0,0 +1,221 @@
+# Data
+
+The in-house pattern **for TanStack Query + Router**, the default stack ([tooling.md](tooling.md)); other data layers keep
+the boundary principles — validate at the edge, errors as values — not this file layout.
+
+## The shape
+
+- One folder per API topic: options factories, key factory, Zod schemas together, so a query key is never spelled out at a
+  call site.
+- Name a file for what it holds, never for the topic it sits in — the folder already says that: `keys.ts`, not `<topic>.ts`
+  or `query-key.ts` (it holds mutation keys too).
+- A file appears only when the topic needs it: a topic with only queries has no `mutations.ts`, and vice versa.
+- A GraphQL (or similarly document-based) transport may split `queries.ts`/`mutations.ts` further into
+  `queryFns.ts`/`mutationFns.ts`; that's an elaboration of the same options-vs-mutations split, not its origin.
+- Transport code (base client, error normalisation): `http/` and nowhere else.
+- Topic helpers: `lib/`, framework-free, tested beside themselves (`build-query-string.ts` + its test) — never inside the
+  topic folder.
+
+```text
+src/
+  api/
+    topics.ts        # one topic registry, reused by keys and namespaces
+    index.ts         # topic barrels composed as api.<topic>
+    <topic>/
+      index.ts       # barrel: named re-exports of what other modules call
+      keys.ts        # createApiKeys — query and mutation keys
+      queries.ts     # query options factories — present when the topic has queries
+      mutations.ts   # mutation options factories — present when the topic has mutations
+      types.ts       # Zod schemas + z.infer types
+      types.test.ts  # schema cases, when the schema encodes product behaviour
+  http/              # transport: client, error normalisation — the only transport-aware place
+  lib/               # framework-free helpers shared by API topics and other callers
+```
+
+## The network boundary validates
+
+- `http/` returns `unknown`; the topic schema parses the response in its query or mutation function and sources the
+  TypeScript type. Full rules: [validation.md](validation.md).
+
+## Errors are values
+
+- A failed request becomes an `ApiError` with a machine-readable code — a value crossing the boundary, not an ad-hoc caught
+  exception; the frontend maps codes to what the user reads.
+
+## Topic registry and key factory
+
+- One registry of topic names, reused for the barrel's namespaces and the first segment of every query and mutation key.
+- `createApiKeys(topic, { queries, mutations })` types every key `readonly [Topic, ...unknown[]]` and returns `keys.topic`:
+  cross-topic invalidation names the topic, never reconstructs a key prefix.
+
+```ts
+// api/topics.ts — one list of topic names, ApiTopic derived from it
+export const API_TOPICS = { AUTH: "auth", USER: "user", ORDERS: "orders" } as const;
+export type ApiTopic = (typeof API_TOPICS)[keyof typeof API_TOPICS];
+export type QueryKey<Topic extends ApiTopic> = readonly [Topic, ...ReadonlyArray<unknown>] | readonly [Topic];
+export type QueryKeyFactory<Topic extends ApiTopic> = (...args: never[]) => QueryKey<Topic>;
+
+export function createApiKeys<
+  Topic extends ApiTopic,
+  QueryKeys extends Record<string, QueryKey<Topic> | QueryKeyFactory<Topic>>,
+  MutationKeys extends Record<string, QueryKey<Topic>>
+>(topic: Topic, keys: { queries: QueryKeys; mutations: MutationKeys }) {
+  return { topic: [topic] as const, queries: keys.queries, mutations: keys.mutations };
+}
+```
+
+```ts
+// api/user/keys.ts — createApiKeys enforces topic-first
+import { API_TOPICS, createApiKeys } from "../topics";
+
+export const keys = createApiKeys(API_TOPICS.USER, {
+  queries: { details: ["user", "details"], byId: (id: string) => ["user", "detail", id] },
+  mutations: { update: ["user", "update"] }
+});
+
+// api/user/index.ts — the topic barrel
+export * from "./keys";
+export * from "./queries";
+export * from "./mutations";
+```
+
+```ts
+// api/index.ts — namespace imports keyed by the topic registry
+import { API_TOPICS } from "./topics";
+import * as auth from "./auth";
+import * as orders from "./orders";
+import * as user from "./user";
+
+export const api = {
+  [API_TOPICS.AUTH]: auth,
+  [API_TOPICS.USER]: user,
+  [API_TOPICS.ORDERS]: orders
+} as const;
+
+export type API = typeof api;
+```
+
+## Options factories and naming
+
+- Topic functions return **options** — never a hook, never data; the caller picks `ensureQueryData` or `useSuspenseQuery`.
+- No topic prefix, no `Options` suffix: `context.api.<topic>.<fn>()` carries both.
+- Queries `get*` (`getAll`, `getById`, `getBySlug`, `getDetails`, `getActive`, `getFiltered`); mutations bare verbs
+  (`update`, `login`, `addItem`, `deleteAddress`, `setShippingMethod`).
+- Same suffix-free naming applies to the local binding a query or mutation resolves to —
+  [typescript.md](typescript.md#naming).
+
+```ts
+// api/user/queries.ts — returns options; keys come from the factory
+import { queryOptions, type QueryOptions } from "@tanstack/react-query";
+import { bffClient } from "../http/bff-client";
+import { userSchema, type User } from "./types";
+import { keys } from "./keys";
+
+export function getDetails(args: { options?: Omit<QueryOptions<User>, "queryKey" | "queryFn"> } = {}) {
+  return queryOptions({
+    ...args.options,
+    queryKey: keys.queries.details,
+    queryFn: async () => userSchema.parse(await bffClient("/me"))
+  });
+}
+```
+
+```ts
+// api/user/mutations.ts — overrides merge over the base, mutationKey leads with the topic
+import type { MutationOptions } from "@tanstack/react-query";
+import { bffClient } from "../http/bff-client";
+import { userSchema, type User, type UserPatch } from "./types";
+import { keys } from "./keys";
+import type { ApiError } from "../http/api-error";
+
+export function update(options?: Omit<MutationOptions<User, ApiError, UserPatch>, "mutationFn">) {
+  return {
+    mutationKey: keys.mutations.update,
+    mutationFn: async (patch: UserPatch) => userSchema.parse(await bffClient("/me", { method: "PATCH", body: patch })),
+    ...options
+  };
+}
+```
+
+## Router context access
+
+- Loaders call `context.api.<topic>.<fn>()`; components use `Route.useRouteContext()`.
+- `createRouter` seeds a placeholder `queryClient`; `router.update()` fills it once the client exists — required because the
+  `MutationCache` closes over both `queryClient` and `router`.
+- Direct imports stay for plain utilities and tests outside the router tree.
+
+```tsx
+// routes/__root.tsx
+import type { QueryClient } from "@tanstack/react-query";
+import type { API } from "../api";
+
+interface RouterContext {
+  api: API;
+  queryClient: QueryClient;
+}
+```
+
+```tsx
+// router.tsx
+import { createRouter } from "@tanstack/react-router";
+import { api } from "./api";
+import { createQueryClient } from "./query-client";
+
+const queryClient = createQueryClient();
+const router = createRouter({ routeTree, context: { api, queryClient } });
+router.update({ context: { api, queryClient } });
+```
+
+```tsx
+// routes/user.tsx
+export const Route = createFileRoute("/user")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(context.api.user.getDetails()),
+  component: UserPage
+});
+
+function UserPage() {
+  const context = Route.useRouteContext();
+  const user = useSuspenseQuery(context.api.user.getDetails());
+  const updateUser = useMutation(
+    context.api.user.update({
+      onSuccess: () => context.queryClient.invalidateQueries({ queryKey: context.api.orders.keys.topic })
+    })
+  );
+  return <input defaultValue={user.data.name} onBlur={e => updateUser.mutate({ name: e.target.value })} />;
+}
+```
+
+## Automatic invalidation
+
+- No hand invalidation at call sites: a `MutationCache` `onSuccess` invalidates `mutationKey[0]` centrally, on by default via
+  `meta.autoInvalidate` — hence every mutation key leads with the topic it dirties.
+- Cross-topic invalidation: per-call-site `onSuccess` override naming `keys.topic` (see `routes/user.tsx`).
+- Opt out with `meta: { autoInvalidate: false }` when a topic-wide refetch is wrong (huge list, targeted optimistic update);
+  invalidate precisely via the key factory.
+- Background: [query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation),
+  [automatic invalidation after mutations](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations).
+
+```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;
+}
+```
+
+## Testing the data layer
+
+- Stub the network at the `fetch` boundary and run the real query client: same parse and error path as production.
+- Assert behaviour in schemas, clients, and query options — schema cases: [validation.md](validation.md), philosophy:
+  [testing.md](testing.md).

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

@@ -0,0 +1,40 @@
+# Documentation structure
+
+What a repo documents, where, and how. `imf-web-ui-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: tooling and architecture 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
+
+- Litmus, per sentence: would this be true in every ImFusion frontend? Then it's baseline — don't restate it; it's already
+  vendored in-repo under `.agents/skills/imf-web-ui-conventions/`, human-readable and versioned.
+- Write deviations as **named deviations** — what the baseline prescribes, what this repo does instead, and why: a deviation
+  written as freestanding convention gets copied into the next repo as house style.
+
+## How docs are written
+
+- **Docs explain concepts; code is the source of truth for facts.** Capture the why — invariants, rationale, decisions. Never
+  restate a fact that lives in code (a script definition, a type shape, a config value); point at the file — a copied fact
+  rots the moment the code changes.
+- **State what is — no decision residue.** 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") — 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. Equal failure modes: 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 it **in the same commit**, never a follow-up.
+- Pre-commit carries the advisory staleness checks (vendored baseline, docs) — mechanics in [git.md](git.md).

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

@@ -0,0 +1,34 @@
+# 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.
+- Check both silent failure modes — config **and** directory: `git:config` never run (hooks exist only on the machine that
+  configured by hand), and `core.hooksPath` pointing at a missing directory.
+
+## Verify scopes
+
+Two scopes, both blocking:
+
+- **staged** — `verify:staged`, called by the pre-commit hook: lint, format, restage, plus the relevant project-wide checks,
+  including `verify:knip` when staged source or project config can change the reachability graph. Fast; a passing commit is
+  not CI green.
+- **full** — `verify:full`: the build plus every `verify:*` check; what CI runs.
+- 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 that drifts 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 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 it in the same commit ([docs-structure.md](docs-structure.md)).
+  An agent commit workflow, where the repo has one, carries a staged docs audit.