@imfusion/web-ui 0.6.1-dev.9.g317bd6f2 → 0.6.1

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

@@ -1,27 +1,22 @@
 # 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).
+Use CVA to turn design props into CSS Module classes, then merge the caller's `className`.
 
 ## 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.
+- 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.
 
 ```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 }
   }
 });
@@ -33,18 +28,18 @@ export function Chip({ appearance = "outline", inline = false, className, ...pro
 
 ## 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:
+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:
 
 ```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
 
-- Two components sharing one visual share one CVA module, a `{name}.cva.ts` next to them, so their variant axes can't drift
-  apart.
+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.

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

@@ -1,26 +1,25 @@
 # Components
 
-How a component lives on disk and how dumb it stays. Roles, state, effects: [react.md](react.md); styling:
+Keep consumer components small and easy to replace. React roles are described in [react.md](react.md); CSS ownership is in
 [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)).
+- 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.
 
 ```tsx
-// components/user-card/user-card.tsx
-interface Props {
+interface UserCardProps {
   name: string;
   onEdit: () => void;
 }
 
-export function UserCard({ name, onEdit }: Props) {
+export function UserCard({ name, onEdit }: UserCardProps) {
   return (
     <Card.Root>
-      <Typo>{name}</Typo>
+      <Typo.P>{name}</Typo.P>
       <Button onClick={onEdit}>Edit</Button>
     </Card.Root>
   );
@@ -29,73 +28,25 @@ export function UserCard({ name, onEdit }: Props) {
 
 ## 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.
+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.
 
 ## 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.
+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:
 
-The full anatomy of a folder component:
-
-```
+```text
 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
+  data-table.tsx
+  data-table.module.css
+  data-table.test.tsx
+  index.ts
 ```
 
-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";
-```
+The barrel only re-exports the public pieces.
 
 ## 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.
+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.

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

@@ -1,207 +1,111 @@
 # 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.
+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 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.
+Use one folder per API topic:
 
 ```text
 src/
   api/
-    topics.ts        # one topic registry, reused by keys and namespaces
-    index.ts         # topic barrels composed as api.<topic>
+    topics.ts
+    index.ts
     <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
+      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
 ```
 
+`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
 
-- `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).
+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).
 
 ## 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.
+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.
 
 ## 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.
+Keep one registry of topic names. Use it for API namespaces and as the first segment of every query and mutation key:
 
 ```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>;
+type QueryKey<Topic extends ApiTopic> = readonly [Topic, ...ReadonlyArray<unknown>] | readonly [Topic];
 
 export function createApiKeys<
   Topic extends ApiTopic,
-  QueryKeys extends Record<string, QueryKey<Topic> | QueryKeyFactory<Topic>>,
+  QueryKeys extends Record<string, QueryKey<Topic> | ((...args: never[]) => QueryKey<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";
+Use the factory in each topic so every key starts with that topic:
 
+```ts
 export const keys = createApiKeys(API_TOPICS.USER, {
-  queries: { details: ["user", "details"], byId: (id: string) => ["user", "detail", id] },
-  mutations: { update: ["user", "update"] }
+  queries: {
+    details: [API_TOPICS.USER, "details"],
+    byId: (id: string) => [API_TOPICS.USER, "detail", id]
+  },
+  mutations: { update: [API_TOPICS.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;
-```
+Cross-topic invalidation can then use `keys.topic` instead of rebuilding a prefix by hand.
 
 ## 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).
+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.
 
-```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";
+A query factory owns its key and parsing:
 
-export function getDetails(args: { options?: Omit<QueryOptions<User>, "queryKey" | "queryFn"> } = {}) {
+```ts
+export function getDetails(options?: QueryOptions<User>) {
   return queryOptions({
-    ...args.options,
+    ...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
-  };
-}
-```
+Callers choose `ensureQueryData`, `useSuspenseQuery`, or another Query API.
 
 ## 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";
+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.
 
-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
-});
+## Automatic invalidation
 
-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 })} />;
-}
-```
+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.
 
-## Automatic invalidation
+For a related topic, add an explicit success handler that invalidates that topic's `keys.topic`.
 
-- 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).
+Configure the shared cache once, so the default applies to every mutation:
 
 ```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;
@@ -216,6 +120,6 @@ export function createQueryClient() {
 
 ## 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).
+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).

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

@@ -1,40 +1,34 @@
 # Documentation structure
 
-What a repo documents, where, and how. `imf-web-ui-setup` scaffolds this shape from its `templates/` and audits it.
+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.
 
 ## The shape
 
-```
+```text
 <app>/
-  README.md            # humans: what the app is, setup, scripts
-  AGENTS.md            # agents: tooling and architecture pointers into docs/ — restates nothing
+  README.md       # what the app is, setup, and scripts
+  AGENTS.md       # short pointers for agents
   docs/
-    index.md           # registers every doc with a one-line "covers" summary
-    <topic>.md         # repo-unique content only
+    index.md      # index of repo-specific docs
+    <topic>.md
 ```
 
 ## 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.
+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.
 
 ## 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.
+- 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.
 
 ## 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).
+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.

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

@@ -1,34 +1,29 @@
 # Git
 
+Use the repository's tracked configuration and keep verification scopes clear.
+
 ## git:config
 
-- One script holds the repo's git configuration, run by hand once per clone (the README names it):
+Run once in a clone:
 
-```
-git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only
+```sh
+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.
+The hooks are tracked in `.githooks/`. Check both the Git setting and the directory; a missing hook path fails silently.
 
 ## Verify scopes
 
-Two scopes, both blocking:
+There are two scopes:
 
-- **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".
+- **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.
 
-## Staleness at commit time
+The scripts under `scripts/verify/` own the step lists. Hooks and npm scripts only launch them.
 
-Pre-commit also runs the advisory staleness checks — warn, never block:
+## Staleness at commit time
 
-- **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.
+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.

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

@@ -1,35 +1,44 @@
 # Library boundary
 
-The contract between an app and `@imfusion/web-ui`.
+Keep the application behind `@imfusion/web-ui`. The library owns the public component API, implementation packages, and
+integration seams.
 
 ## Stay behind the library
 
-- Never import Base UI (or any other upstream the library wraps) directly — no upstream stylesheets, no upstream components,
-  even when upstream docs show it that way: everything a component needs ships in `@imfusion/web-ui`.
-- 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.
+- 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`.
 
 ## Wrap primitives when the app has a reason to
 
-- 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.
+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.
 
-## Derive types, don't import them
+Derive its props from the primitive:
 
-- 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.
+```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.
 
 ## Integrations own their peers
 
-- `@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.
+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.
 
 ## Styling crosses the boundary through seams
 
-- Tokens in, sanctioned selectors at the edge, never the library's internals — the full contract is [styling.md](styling.md).
+Use token overrides, your own classes, and `data-imf-ui-component` or state attributes. The complete CSS contract is in
+[styling.md](styling.md).