@imfusion/web-ui 0.6.1-dev.27.gfc6e5abb → 0.6.1-dev.3.g5b432448

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

@@ -1,22 +1,27 @@
 # Class names in components
 
-Use CVA to turn design props into CSS Module classes, then merge the caller's `className`.
+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
 
-- Use `class-variance-authority` for variant axes. Do not add `clsx`, `tailwind-merge`, or a local `cn` helper.
-- Import `cx` from `@imfusion/web-ui` when a component only needs concatenation.
-- Pass CSS Module references to CVA, not string class names.
-- Represent a boolean axis with `false: null` and `true: classes.axisOn`.
-- Put defaults in function destructuring. CVA `defaultVariants` does not reach the generated docs.
+- `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
-    },
+    appearance: { outline: classes.appearanceOutline, solid: classes.appearanceSolid },
     inline: { false: null, true: classes.inline }
   }
 });
@@ -28,18 +33,18 @@ export function Chip({ appearance = "outline", inline = false, className, ...pro
 
 ## Merging `className`
 
-A component that accepts `className` must merge it. Put the incoming value in CVA's `className` slot so it is appended after
-the component classes. If there is no CVA configuration, use `cx`.
-
-A library render prop may make `className` a function. Resolve it with the render state before merging:
+- 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)}
 ```
 
-A closed component should omit `className`, not accept and ignore it.
-
 ## Shared CVA modules
 
-When two components share the same visual variant axes, put their CVA call in a `{name}.cva.ts` module next to them. This
-keeps the visual contract in one place.
+- 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

@@ -1,25 +1,26 @@
 # Components
 
-Keep consumer components small and easy to replace. React roles are described in [react.md](react.md); CSS ownership is in
+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
 
-- Feed components data and callbacks through props.
-- Keep fetching, routing, and business logic in the page or feature layer.
-- Local UI state such as an open state or draft value is fine.
-- Formatting and display-only decisions are fine; owning server state is not.
+- 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
-interface UserCardProps {
+// components/user-card/user-card.tsx
+interface Props {
   name: string;
   onEdit: () => void;
 }
 
-export function UserCard({ name, onEdit }: UserCardProps) {
+export function UserCard({ name, onEdit }: Props) {
   return (
     <Card.Root>
-      <Typo.P>{name}</Typo.P>
+      <Typo>{name}</Typo>
       <Button onClick={onEdit}>Edit</Button>
     </Card.Root>
   );
@@ -28,25 +29,73 @@ export function UserCard({ name, onEdit }: UserCardProps) {
 
 ## Grouping
 
-Group by component role, such as layout or domain UI, according to the project structure. Do not create a hierarchy before
-the project needs one.
+- `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
 
-A one-file component can stay in its group. A component with parts, styles, or tests gets a folder with an `index.ts` barrel.
-Call sites import the folder path:
+- 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.
 
-```text
+The full anatomy of a folder component:
+
+```
 components/data-table/
-  data-table.tsx
-  data-table.module.css
-  data-table.test.tsx
-  index.ts
+  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
 ```
 
-The barrel only re-exports the public pieces.
+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
 
-Keep a component's stylesheet, tests, and local types beside the component. A container that needs styling usually wants to
-be a layout or dumb component instead.
+- 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

@@ -1,111 +1,207 @@
 # Data
 
-This topic defines the ImFusion pattern for TanStack Query and TanStack Router. Other data libraries keep the same boundary
-rules: validate external data at the edge and represent errors as values.
+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
 
-Use one folder per API topic:
+- 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
-    index.ts
+    topics.ts        # one topic registry, reused by keys and namespaces
+    index.ts         # topic barrels composed as api.<topic>
     <topic>/
-      index.ts
-      keys.ts
-      queries.ts       # when the topic has queries
-      mutations.ts     # when it has mutations
-      types.ts         # schemas and inferred types
-      types.test.ts    # when schema rules encode behavior
-  http/                # transport and error normalization
-  lib/                 # framework-free shared helpers
+      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
 ```
 
-`keys.ts` owns query and mutation keys. Topic functions return options, not hooks or data. Keep transport code in `http/` and
-keep topic helpers out of the API folder when they are shared and framework-free.
-
 ## The network boundary validates
 
-The transport returns `unknown`. The topic schema parses it in the query or mutation function, and `z.infer` supplies the
-TypeScript type. A handwritten generic on `fetch` is not validation. See [validation.md](validation.md).
+- `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
 
-Normalize failed requests into an `ApiError` with a machine-readable code. The UI maps the code to user-facing text instead
-of handling arbitrary thrown shapes at every call site.
+- 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
 
-Keep one registry of topic names. Use it for API namespaces and as the first segment of every query and mutation key:
+- 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];
-type QueryKey<Topic extends ApiTopic> = readonly [Topic, ...ReadonlyArray<unknown>] | readonly [Topic];
+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> | ((...args: never[]) => QueryKey<Topic>)>,
+  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 };
 }
 ```
 
-Use the factory in each topic so every key starts with that topic:
-
 ```ts
+// api/user/keys.ts — createApiKeys enforces topic-first
+import { API_TOPICS, createApiKeys } from "../topics";
+
 export const keys = createApiKeys(API_TOPICS.USER, {
-  queries: {
-    details: [API_TOPICS.USER, "details"],
-    byId: (id: string) => [API_TOPICS.USER, "detail", id]
-  },
-  mutations: { update: [API_TOPICS.USER, "update"] }
+  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";
 ```
 
-Cross-topic invalidation can then use `keys.topic` instead of rebuilding a prefix by hand.
+```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
 
-Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use bare verbs such as `update` or
-`delete`. Do not add a topic prefix or `Options` suffix; `context.api.user.getDetails()` already supplies the context.
-
-A query factory owns its key and parsing:
+- 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
-export function getDetails(options?: QueryOptions<User>) {
+// 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({
-    ...options,
+    ...args.options,
     queryKey: keys.queries.details,
     queryFn: async () => userSchema.parse(await bffClient("/me"))
   });
 }
 ```
 
-Callers choose `ensureQueryData`, `useSuspenseQuery`, or another Query API.
+```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
 
-Put the API object and `QueryClient` in router context. Loaders use `context.api.<topic>.<fn>()`; route components read the
-same context with `Route.useRouteContext()`. Direct imports are for plain utilities and tests outside the route tree.
+- 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.
 
-## Automatic invalidation
+```tsx
+// routes/__root.tsx
+import type { QueryClient } from "@tanstack/react-query";
+import type { API } from "../api";
 
-Mutation keys start with the topic they change. The shared `MutationCache` invalidates that topic after success by default.
-Use `meta: { autoInvalidate: false }` for a mutation where a topic-wide refetch is wrong, then invalidate exact keys
-yourself.
+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 })} />;
+}
+```
 
-For a related topic, add an explicit success handler that invalidates that topic's `keys.topic`.
+## Automatic invalidation
 
-Configure the shared cache once, so the default applies to every mutation:
+- 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 } } },
+    defaultOptions: {
+      mutations: { meta: { autoInvalidate: true } }
+    },
     mutationCache: new MutationCache({
       onSuccess: async (_data, _variables, _context, mutation) => {
         if (!mutation.meta?.autoInvalidate) return;
@@ -120,6 +216,6 @@ export function createQueryClient() {
 
 ## Testing the data layer
 
-Stub `fetch` at the transport boundary and run the real query client. Test schemas, transport normalization, and query
-options where they encode decisions. Schema cases belong beside the schema; the general test boundary is in
-[testing.md](testing.md).
+- 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

@@ -1,34 +1,40 @@
 # Documentation structure
 
-Keep repository docs useful to a human who has just joined the project. Invoke `/documentation-writer` for new or updated
-documentation. The setup skill can propose the shape; the audit skill can check it.
+What a repo documents, where, and how. `imf-web-ui-setup` scaffolds this shape from its `templates/` and audits it.
 
 ## The shape
 
-```text
+```
 <app>/
-  README.md       # what the app is, setup, and scripts
-  AGENTS.md       # short pointers for agents
+  README.md            # humans: what the app is, setup, scripts
+  AGENTS.md            # agents: tooling and architecture pointers into docs/ — restates nothing
   docs/
-    index.md      # index of repo-specific docs
-    <topic>.md
+    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
 
-If a rule should be true in every ImFusion frontend, keep it in the shipped conventions skill. Repo docs should explain local
-decisions and deviations. A deviation names the baseline, the local choice, and why it exists.
+- 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
 
-- Give each page one reader goal.
-- Use plain language and active verbs.
-- Explain a reason when it helps someone make the right choice.
-- Let code own changing facts such as scripts, types, token names, and config. Link to the source instead of copying it.
-- State the current situation. History belongs in commits and tickets.
-- Use examples that a reader could adapt, not placeholder prose.
+- **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
 
-When a change makes a doc inaccurate, update the doc in the same commit. The repository's commit workflow runs the staged
-docs audit; the check is advisory, but the correction belongs with the change.
+- 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

@@ -1,29 +1,34 @@
 # Git
 
-Use the repository's tracked configuration and keep verification scopes clear.
-
 ## git:config
 
-Run once in a clone:
+- One script holds the repo's git configuration, run by hand once per clone (the README names it):
 
-```sh
-git config core.hooksPath .githooks
-git config pull.rebase true
-git config merge.ff only
+```
+git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only
 ```
 
-The hooks are tracked in `.githooks/`. Check both the Git setting and the directory; a missing hook path fails silently.
+- 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
 
-There are two scopes:
+Two scopes, both blocking:
 
-- **staged**: `verify:staged`, run by pre-commit. It is fast and checks the staged files plus relevant project-wide checks.
-- **full**: `verify:full`, the build and complete verification used by CI.
-
-The scripts under `scripts/verify/` own the step lists. Hooks and npm scripts only launch them.
+- **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 advisory checks for vendored skill markers and documentation drift. If a staged change makes a doc
-stale, update the doc in the same commit. For an outdated installed skill, run `npx web-ui-install` in the consumer project.
+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.

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

@@ -1,44 +1,35 @@
 # Library boundary
 
-Keep the application behind `@imfusion/web-ui`. The library owns the public component API, implementation packages, and
-integration seams.
+The contract between an app and `@imfusion/web-ui`.
 
 ## Stay behind the library
 
-- Do not import Base UI or another implementation package directly, including its stylesheet.
-- If Web UI is missing a component or part, report the gap instead of reaching around it.
-- Import glyphs from `@imfusion/web-ui/icons` and render them with `Icon`.
+- 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`.
+- Library missing something upstream has → report the gap (see `imf-web-ui-components`); don't reach around it.
+- Import icons from `@imfusion/web-ui/icons` and render them through its `Icon` component. Direct imports from
+  `iconoir-react` are outside the library boundary.
 
 ## Wrap primitives when the app has a reason to
 
-Create an app-level dumb wrapper when you repeat a default, composition, styling override, accessibility improvement, or API
-restriction. A wrapper that only renames a component adds indirection without helping.
+- Repeated adaptation 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 in `components/` ([components.md](components.md)).
+- The wrapper derives its props from the primitive (`React.ComponentProps<typeof Button>`, narrowed or extended) and styles
+  itself through the sanctioned seams — never the library's internals.
+- 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 its props from the primitive:
+## Derive types, don't import them
 
-```tsx
-type SaveButtonProps = React.ComponentProps<typeof Button> & {
-  busy?: boolean;
-};
-```
-
-Style the wrapper through tokens, your own classes, and the library's public data attributes. Do not target library CSS
-Module classes.
-
-An `experimental` primitive should be wrapped once before it is used throughout an app. That gives an API change one place to
-land.
-
-## Derive types, don't copy them
-
-The library intentionally does not export component `Props` interfaces. Use `React.ComponentProps<typeof Component>` and
-narrow or extend that type locally.
+- Prop types come from the components themselves: `React.ComponentProps<typeof Button>`.
+- The library deliberately exports no `Props` types — don't look for them, don't re-declare prop shapes by hand.
 
 ## Integrations own their peers
 
-An integration under `@imfusion/web-ui/integrations/*` has an optional peer. Add that peer explicitly to the consumer's
-`package.json`; npm hoisting is not a dependency contract.
+- `@imfusion/web-ui/integrations/*` components 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
 
-Use token overrides, your own classes, and `data-imf-ui-component` or state attributes. The complete CSS contract is in
-[styling.md](styling.md).
+- Tokens in, sanctioned selectors at the edge, never the library's internals — the full contract is [styling.md](styling.md).