@imfusion/web-ui 0.5.1-dev.33.gadde98d1 → 0.5.1-dev.39.gfc64049e

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

@@ -1,82 +0,0 @@
----
-name: imf-web-ui-agent-setup
-description:
-  "Install or update the LLM/agent tooling @imfusion/web-ui ships in a consumer repo: the vendored imf-web-ui-* skills, the
-  AGENTS.md fence, the agent lifecycle hooks, and the staleness wiring. Also covers reaching the Agent Skills a dependency
-  ships — TanStack Intent (@tanstack/intent) and its allowlist. Wraps npx web-ui-install and adds the judgment the binary
-  can't have — reading what the repo already registers before adding anything. Load when setting up agent tooling in a
-  consumer app, when skills are stale, when hooks should be installed or adapted, or when asked to set up TanStack Intent or
-  dependency-shipped Agent Skills. Not for project tooling (imf-web-ui-frontend-setup) or library wiring
-  (imf-web-ui-library-setup)."
-allowed-tools: Read Bash
----
-
-# imf-web-ui-agent-setup
-
-Sets up or updates the agent side of a consumer repo. The binary does the mechanics; this skill does the judgment.
-
-## Skills
-
-`npx web-ui-install` installs or refreshes the vendored `imf-web-ui-*` skills (interactive target choice on first run,
-remembered after; `--reconfigure` re-opens it). It also refreshes the `<!-- imf-web-ui:begin/end -->` fence in an existing
-`AGENTS.md`. Stale check: `.imf-web-ui-skill-version.json` in each installed skill vs. the installed package version — older
-marker means re-run the binary, never hand-diff skill contents.
-
-## Hooks
-
-Three agent lifecycle hooks ship as templates in [`templates/hooks/`](templates/hooks/), registration in
-[`templates/settings.json`](templates/settings.json):
-
-- **SessionStart** — once per session: the conventions baseline is vendored, load it before writing.
-- **UserPromptSubmit** — a one-line conventions reminder per prompt. Per-prompt, not per-tool-call: a PreToolUse reminder
-  would re-inject the same text on every edit.
-- **PostToolUse** (advisory) — file-scope checks on the touched file after every Edit/Write, failures fed straight back. It
-  resolves the nearest package from the edited file, so a frontend nested below a monorepo root uses its own config and
-  dependencies. Never exits non-zero.
-- **`baseline-staleness.sh`** — not registered as an agent hook; the repo's pre-commit calls it
-  ([`git.md`](../imf-web-ui-frontend-conventions/references/git.md), Staleness at commit time).
-
-**Read `.claude/settings.json` before installing.** Then pick per event:
-
-- **Nothing registered** → install as shipped: `npx web-ui-install --hooks` copies the scripts to `.agents/hooks/imf-web-ui/`
-  (installer-owned, refreshed wholesale) and merges the registrations without touching existing entries.
-- **The repo already covers an event** (its own session reminder, its own post-edit verify) → don't stack a second hook on
-  it. Use the template as a starting point instead: fold the missing behaviour into the repo's existing script, or adapt the
-  template and register that. Surface the situation and let the human pick.
-
-## Assessment reference
-
-A static frontend setup assessment checks that the complete consumer skill bundle and version markers match the declared
-`@imfusion/web-ui` version; the AGENTS fence exists; SessionStart, UserPromptSubmit, and PostToolUse behavior is installed
-and registered or consciously adapted; PostToolUse resolves the edited file's package and its tools in monorepos; and the
-tracked pre-commit path calls `baseline-staleness.sh`. Read files and settings as text—do not run installers, hooks, or local
-config queries during assessment.
-
-## Dependency-shipped skills
-
-Some libraries ship Agent Skills inside their npm package; TanStack does across much of the suite.
-[TanStack Intent](https://github.com/TanStack/intent) (`@tanstack/intent`) is the CLI that surfaces them — an agent holding a
-dependency but not its guidance writes plausible code against a half-remembered API.
-
-Setting it up is the project's own call, not something web-ui does on its behalf. Point it out:
-
-> This project has TanStack dependencies that ship their own Agent Skills. `@tanstack/intent` can make them reachable — worth
-> a look if you want your agent working from the library's own guidance.
-
-Intent offers two things: a fenced instructions block in `AGENTS.md`, and a `PreToolUse` hook that blocks an edit until a
-matching skill has been read. The house preference is both — the block alone is advice an agent can walk past. The hook
-refuses every edit while no matching skill is loadable, so a project adopting it wants the current docs open; that sequencing
-belongs to whoever runs it.
-
-**Allowlist the whole scope.** `intent.skills` takes `@tanstack/*`. Per-package entries like `@tanstack/react-query` look
-more precise and silently reach almost nothing, because the skills ship from packages the app never names directly. Exclude
-`@tanstack/devtools-event-client` — it publishes skills that are noise in an app repo.
-
-Read Intent's own docs before wiring it; it is young and moves. Whatever the project decides, guidance you didn't read is not
-guidance you have: use `npx @tanstack/cli` for TanStack docs, and never guess at a skill name.
-
-## Not this skill
-
-- Project tooling, docs structure, the audit checklist → `imf-web-ui-frontend-setup` (which reads this skill as its
-  agent-tooling assessment contract)
-- Library wiring (styles import, provider) → `imf-web-ui-library-setup`

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/post-tool-use.sh

@@ -1,33 +0,0 @@
-#!/usr/bin/env sh
-# PostToolUse (Edit|Write): advisory file-scope checks on the touched file. Never exits
-# non-zero, so a mid-flight refactor can't trap the agent. Resolve the package from the
-# edited file, not cwd or the Git root, which may belong to a parent monorepo.
-FILE=$(sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
-[ -f "$FILE" ] || exit 0
-
-FILE_DIR=$(cd "$(dirname "$FILE")" && pwd) || exit 0
-FILE="$FILE_DIR/$(basename "$FILE")"
-PACKAGE_ROOT=$FILE_DIR
-while [ "$PACKAGE_ROOT" != "/" ] && [ ! -f "$PACKAGE_ROOT/package.json" ]; do
-  PACKAGE_ROOT=$(dirname "$PACKAGE_ROOT")
-done
-[ -f "$PACKAGE_ROOT/package.json" ] || exit 0
-
-TOOL_ROOT=$PACKAGE_ROOT
-while [ "$TOOL_ROOT" != "/" ] && [ ! -d "$TOOL_ROOT/node_modules/.bin" ]; do
-  TOOL_ROOT=$(dirname "$TOOL_ROOT")
-done
-[ -d "$TOOL_ROOT/node_modules/.bin" ] || exit 0
-cd "$PACKAGE_ROOT" || exit 0
-
-case "$FILE" in
-  *.ts | *.tsx | *.js | *.jsx)
-    [ -x "$TOOL_ROOT/node_modules/.bin/eslint" ] && "$TOOL_ROOT/node_modules/.bin/eslint" --cache "$FILE" 2>&1
-    ;;
-esac
-case "$FILE" in
-  *.ts | *.tsx | *.js | *.jsx | *.css | *.json | *.md)
-    [ -x "$TOOL_ROOT/node_modules/.bin/prettier" ] && "$TOOL_ROOT/node_modules/.bin/prettier" --check "$FILE" 2>&1
-    ;;
-esac
-exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/session-start.sh

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-# SessionStart: point the agent at the vendored conventions baseline once per session.
-echo "The ImFusion frontend conventions baseline is vendored in .agents/skills/ (imf-web-ui-frontend-conventions and siblings). Load the relevant skill before writing code, styles, or docs; repo docs in docs/ carry only what is unique to this repo."
-exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/user-prompt-submit.sh

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-# UserPromptSubmit: one-line conventions reminder per prompt.
-echo "Conventions check: if this task touches code, styles, data fetching, or docs, consult the matching imf-web-ui-* skill in .agents/skills/ before acting."
-exit 0

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

@@ -1,46 +0,0 @@
----
-name: imf-web-ui-frontend-conventions
-description:
-  "The ImFusion frontend conventions baseline — in-house conventions, valid in every ImFusion frontend and usable by anyone
-  who likes them. A router over topic references: library boundary, React, components, TypeScript, styling, validation, data
-  layer, project structure, testing, stack, npm project, tooling config, git, assets, docs structure. Load when writing
-  wrapper components, custom UI, styling beyond the defaults, validating external data, adding new files to a consumer app,
-  writing repo docs, touching tool config, or choosing any dependency."
----
-
-# imf-web-ui-frontend-conventions
-
-The ImFusion frontend baseline. In-house conventions, not industry claims — they encode how ImFusion frontends are built, and
-anyone else is welcome to them.
-
-**The project wins.** These defaults fill vacuums: if the host project already has a convention — a styling system, a state
-library, a folder shape — that stands. They are not a license to refactor a consumer codebase toward this document.
-
-**Alignment mode.** The exception is intent: when the user asks to _align_ the repo with the baseline ("align", "alignment"
-is the flag), the project-wins guard lifts. Deviations then become migration findings — proposed as a plan, still nothing
-changed until the human approves.
-
-## The references
-
-Each topic lives in one reference. Read the one whose moment you're in; starting a new feature usually wants several.
-
-| Reference                                               | Covers                                                              | Read when                                               |
-| ------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
-| [library-boundary.md](references/library-boundary.md)   | staying behind `@imfusion/web-ui`, wrappers, type derivation, peers | touching anything that renders library components       |
-| [react.md](references/react.md)                         | component roles, state kinds and owners, effects discipline         | writing new screens, components, or wrappers            |
-| [components.md](references/components.md)               | component anatomy on disk: grouping, folders, colocation            | adding a component file                                 |
-| [typescript.md](references/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
-| [styling.md](references/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
-| [class-names.md](references/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
-| [validation.md](references/validation.md)               | runtime schemas, boundary parsing, schema-derived types             | accepting data the frontend does not own                |
-| [data.md](references/data.md)                           | `api/`+`http/` shape, query/mutation patterns and invalidation      | adding an API topic, a fetch, or a mutation             |
-| [project-structure.md](references/project-structure.md) | the `src/` tree, file naming, imports                               | adding files rather than editing existing ones          |
-| [testing.md](references/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
-| [stack.md](references/stack.md)                         | the topic→tool map, when a library owns a layer                     | choosing or adding any dependency                       |
-| [npm-project.md](references/npm-project.md)             | `package.json`, the `verify:*` script set, dependency pinning       | running or adding a script, adding a dependency         |
-| [tooling.md](references/tooling.md)                     | Prettier, ESLint, tsconfig, staged files, CSS class names           | touching tool config                                    |
-| [git.md](references/git.md)                             | `git:config`, verify scopes, staleness at commit time               | wiring hooks or the commit path                         |
-| [assets.md](references/assets.md)                       | image formats, the WebP recipe                                      | adding images or other static assets                    |
-| [docs-structure.md](references/docs-structure.md)       | what a repo documents, where, how it's written                      | writing or restructuring repo docs                      |
-
-`imf-web-ui-frontend-setup` bootstraps and audits a repo against this baseline.

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

@@ -1,23 +0,0 @@
-# Assets
-
-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 is visually lossless on photos and routinely cuts file size by an order of magnitude.
-- `method=6` is the densest encoding. It's a one-off cost at conversion time, so take the smaller file.
-- Cap the long edge at 2000px — nothing on the market resolves more in a content image.
-- No `<picture>` fallback needed; 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.
-
-These rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep —
-convert opportunistically, when you're working on them anyway.

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

@@ -1,42 +0,0 @@
-# Class names in components
-
-How a component turns props into a `className` string. What the build does with the result is [tooling.md](tooling.md); what
-goes in the stylesheet is [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 and `@imfusion/web-ui` re-exports it, so it comes
-from the library alongside the components.
-
-```tsx
-import { cva } from "class-variance-authority";
-import classes from "./chip.module.css";
-
-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 })} />;
-}
-```
-
-- **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.
-- **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.
-- **Every component that accepts `className` merges it.** A component whose surface is deliberately closed omits the prop
-  entirely rather than accepting and ignoring it.
-- **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.
-- **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)}
-  ```
-
-- **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-frontend-conventions/references/components.md

@@ -1,63 +0,0 @@
-# Components
-
-How a component lives on disk and how dumb it stays. Roles, state, and effects in full are [react.md](react.md); styling is
-[styling.md](styling.md).
-
-## As dumb as possible
-
-Data comes from outside — props-fed, never self-fetching. Presentational logic (formatting a label, deriving a display state)
-is fine; owning data is not:
-
-```tsx
-// components/user-card/user-card.tsx
-interface Props {
-  name: string;
-  role: string;
-  onEdit: () => void;
-}
-
-export function UserCard({ name, role, onEdit }: Props) {
-  return (
-    <Card.Root>
-      <Card.Content>
-        <Typo>{name}</Typo>
-        <Chip>{role}</Chip>
-      </Card.Content>
-      <Card.Footer>
-        <Button onClick={onEdit}>Edit</Button>
-      </Card.Footer>
-    </Card.Root>
-  );
-}
-```
-
-No query hook, no store access, no route awareness — the component renders what it's given and reports events upward. Local
-UI state (`isOpen`, a draft value) is allowed; anything whose truth lives elsewhere is not ([react.md](react.md)).
-
-## Grouping
-
-`components/` groups by kind — a layout component under `layouts/`, not beside a domain widget. Flat is fine while there are
-few; let the grouping follow what the project actually has rather than imposing it up front. The kinds worth separating are
-the component roles in [react.md](react.md).
-
-## One file or a folder
-
-A component gets a folder once it has more than one file — sub-components, styles, tests — with an `index.ts` that only
-re-exports:
-
-```
-components/data-table/
-  data-table.tsx
-  data-table-row.tsx
-  data-table.module.css
-  index.ts
-```
-
-Imports then read `#/components/data-table` and the inside can be restructured without touching call sites. Single-file
-components stay single files, directly in their group.
-
-## Colocation
-
-The stylesheet is colocated as `<component>.module.css` next to the component, and 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 too. A file you have to hunt for in a parallel tree gets edited less carefully.

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

@@ -1,201 +0,0 @@
-# Data
-
-How data enters, moves through, and leaves an ImFusion frontend. This is the in-house pattern **for TanStack Query + Router**
-— the default stack ([stack.md](stack.md)). A project on a different data layer keeps the boundary principles (validate at
-the edge, errors as values) but not necessarily this file layout.
-
-## The shape
-
-```
-src/
-  api/<topic>/       # one folder per API topic
-    <topic>.ts       #   queryOptions / mutationOptions
-    query-key.ts     #   key factory, topic as the first segment
-    types.ts         #   Zod schemas + z.infer types
-  http/              # transport: client, error normalisation — the only transport-aware place
-```
-
-A query lives next to its key factory and its schemas, so a query key is never spelled out at a call site. Anything
-transport-level (base client, error normalisation) lives in `http/` and nowhere else.
-
-## The network boundary validates
-
-The transport in `http/` returns `unknown`; the topic schema parses the response in its query or mutation function before the
-value enters the app. The schema is also the source of its TypeScript type. The full boundary, type-derivation, and failure
-handling rules are [validation.md](validation.md).
-
-## Errors are values
-
-A failed request becomes an `ApiError` carrying a machine-readable code — it crosses the boundary the same way values do, not
-as an exception caught ad hoc. The frontend owns the mapping from codes to what the user reads.
-
-## The pattern, end to end
-
-The key factory — topic as the first segment, one function per key shape:
-
-```ts
-// api/user/query-key.ts
-const TOPIC = "user" as const;
-
-export const userKeys = {
-  all: [TOPIC] as const,
-  me: () => [TOPIC, "me"] as const,
-  detail: (id: string) => [TOPIC, "detail", id] as const
-};
-```
-
-Query options — key from the factory, parse at the boundary:
-
-```ts
-// api/user/user.ts
-import { queryOptions } from "@tanstack/react-query";
-
-import { bffClient } from "#/http/bff-client";
-import { userKeys } from "./query-key";
-import { userSchema } from "./types";
-
-export const userQueryOptions = () =>
-  queryOptions({
-    queryKey: userKeys.me(),
-    queryFn: async () => userSchema.parse(await bffClient("/me"))
-  });
-```
-
-Components consume query options directly with `useSuspenseQuery` (prefetched routes) or `useQuery` (secondary data). No
-wrapper hooks — the options function is the reusable unit. Call sites may spread the returned options only to add
-component-specific callbacks or overrides.
-
-Mutations follow the same shape with `mutationOptions`, the dirtied topic first in the `mutationKey`:
-
-```ts
-// api/user/user.ts
-export const updateUserMutationOptions = () =>
-  mutationOptions({
-    mutationKey: [...userKeys.all, "update"],
-    mutationFn: async (patch: UserPatch) => userSchema.parse(await bffClient("/me", { method: "PATCH", body: patch }))
-  });
-```
-
-The root route types the router context so every loader can reach the query client via DI:
-
-```ts
-// routes/__root.tsx
-import { Outlet, createRootRouteWithContext } from "@tanstack/react-router";
-import type { QueryClient } from "@tanstack/react-query";
-
-interface RouterContext {
-  queryClient: QueryClient;
-}
-
-export const Route = createRootRouteWithContext<RouterContext>()({
-  component: () => <Outlet />
-});
-```
-
-The router is created with that context filled in:
-
-```ts
-// router.ts
-import { createRouter } from "@tanstack/react-router";
-import { routeTree } from "./routeTree.gen";
-import { createQueryClient } from "./query-client";
-
-const queryClient = createQueryClient();
-
-export const router = createRouter({
-  routeTree,
-  context: { queryClient }
-});
-```
-
-A route prefetches in the `loader`, reads with `useSuspenseQuery`, and provides a `pendingComponent`; errors bubble to the
-nearest `errorComponent`:
-
-```tsx
-// routes/me.tsx
-import { createFileRoute } from "@tanstack/react-router";
-import { useSuspenseQuery } from "@tanstack/react-query";
-
-import { userQueryOptions } from "#/api/user/user";
-
-export const Route = createFileRoute("/me")({
-  loader: ({ context }) => context.queryClient.ensureQueryData(userQueryOptions()),
-  pendingComponent: () => <p>Loading…</p>,
-  component: MePage
-});
-
-function MePage() {
-  const { data: user } = useSuspenseQuery(userQueryOptions());
-  return <h1>{user.name}</h1>;
-}
-```
-
-Mutations use `useMutation` with the options factory instead of reconstructing `mutationKey` and `mutationFn` at the call
-site. Manual invalidation is unnecessary when automatic invalidation is on (see below):
-
-```tsx
-// components/user-settings.tsx
-import { useMutation } from "@tanstack/react-query";
-import { useSuspenseQuery } from "@tanstack/react-query";
-
-import { userQueryOptions, updateUserMutationOptions } from "#/api/user/user";
-
-function UserSettings() {
-  const { data: user } = useSuspenseQuery(userQueryOptions());
-  const updateUser = useMutation(updateUserMutationOptions());
-
-  return (
-    <form
-      onSubmit={e => {
-        e.preventDefault();
-        updateUser.mutate({ name: "New Name" });
-      }}
-    >
-      <input defaultValue={user.name} />
-    </form>
-  );
-}
-```
-
-## Automatic invalidation
-
-Mutations don't invalidate by hand at every call site — the query client does it centrally, keyed off the mutation's topic. A
-`MutationCache` `onSuccess` invalidates `mutationKey[0]`, on by default via `meta.autoInvalidate`; that's why every
-mutation's key leads with the topic it dirties:
-
-```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;
-}
-```
-
-Opt out per mutation with `meta: { autoInvalidate: false }` when a coarse topic-wide refetch is wrong (a huge list, a
-targeted optimistic update), and invalidate precisely through the key factory instead. Background reading:
-[query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) and
-[automatic invalidation after mutations](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations).
-
-## Audit
-
-Inspect the complete path, not the presence of TanStack Query alone: transport returns `unknown`; topic schemas parse
-responses; API types derive from those schemas; keys come from topic factories; API topics expose reusable `queryOptions` and
-`mutationOptions`; hooks consume those options with only local overrides; mutation keys match the configured invalidation
-strategy.
-
-## Testing the data layer
-
-Stub the network at the `fetch` boundary and let the real query client run: the test then exercises the same parse and error
-path production does. Schemas, clients, and query options are where behaviour worth asserting lives — schema cases are in
-[validation.md](validation.md), and the general philosophy is [testing.md](testing.md).

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

@@ -1,44 +0,0 @@
-# Documentation structure
-
-What a repo documents, where, and how it's written. `imf-web-ui-frontend-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: stack, 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
-
-The litmus, applied sentence by sentence: **would this be true in every ImFusion frontend? Then it's baseline — it lives in
-the installed skill references, don't restate it.** The baseline is already in the repo, vendored under
-`.agents/skills/imf-web-ui-frontend-conventions/`, human-readable and versioned.
-
-Where the repo deviates from the baseline, the doc says so as a **named deviation** — what the baseline prescribes, what this
-repo does instead, and why. A deviation written as freestanding convention gets copied into the next repo as if it were house
-style.
-
-## How docs are written
-
-- **Docs explain concepts; code is the source of truth for facts.** A doc captures the why — invariants, rationale,
-  decisions. It never restates a fact that lives in code (a script definition, a type shape, a config value): point at the
-  file instead. A copied fact rots the moment the code changes.
-- **State what is — no decision residue.** Positive, 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") — that 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. The two failure modes are equal: 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 that doc **in the same commit**, not in a follow-up. Pre-commit carries the advisory
-staleness checks (vendored baseline, docs) — the mechanics are in [git.md](git.md).

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

@@ -1,33 +0,0 @@
-# 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. Two silent failure modes to check
-for: `git:config` never run (hooks exist only on the machine that configured by hand), and `core.hooksPath` pointing at a
-directory that doesn't exist. Config **and** directory.
-
-## Verify scopes
-
-Two blocking, one advisory:
-
-- **staged** — `verify:staged`, called by the pre-commit hook: lint, format, restage. Fast; a passing commit is not CI green.
-- **full** — `verify:full`: the build plus every `verify:*` check. What CI runs.
-- **files** — post-edit agent hook. Advisory, never exits non-zero, so a mid-flight refactor can't trap the agent.
-
-One script owns each scope's step list; npm scripts and hooks only launch them. Name by depth, not by occasion — a
-`preflight` needs explaining and invites a near-identical sibling, and two of those drift 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 the 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 that doc in the same commit
-  ([docs-structure.md](docs-structure.md)). Where the repo has an agent commit workflow, a staged docs audit belongs in it.

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

@@ -1,37 +0,0 @@
-# Library boundary
-
-The contract between an app and `@imfusion/web-ui`.
-
-## Stay behind the library
-
-Never import Base UI (or any other upstream the library wraps) directly — no upstream stylesheets, no upstream components,
-even when upstream docs show it that way. Everything a component needs ships in `@imfusion/web-ui`. If the library is missing
-something upstream has, report the gap (see `imf-web-ui-components`); don't reach around it.
-
-## Wrap primitives when the app has a reason to
-
-When the app keeps repeating something around a primitive — default props, a styling override, a composition, an
-accessibility refinement, a restriction of the API — wrap it once in an app-level dumb component and use that. The wrapper
-derives its props from the primitive (`React.ComponentProps<typeof Button>`, narrowed or extended), lives in `components/`
-like any other dumb component ([components.md](components.md)), and styles itself through the sanctioned seams — it never
-reaches into the library's internals.
-
-Two rules keep wrappers honest:
-
-- Wrap for a reason — any repeated adaptation counts. A wrapper that only renames a primitive is indirection with no payoff.
-- Components marked `experimental` in the identity index get wrapped **always**, even with nothing added yet — a breaking
-  upstream change then lands in one file instead of every call site.
-
-## Derive types, don't import them
-
-Prop types come from the components themselves: `React.ComponentProps<typeof Button>`. The library deliberately exports no
-`Props` types — don't look for them, and don't re-declare prop shapes by hand.
-
-## Integrations own their peers
-
-Components under `@imfusion/web-ui/integrations/*` depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`).
-Add the peer explicitly to the consumer's `package.json` — never rely on hoisting.
-
-## Styling crosses the boundary through seams
-
-Tokens in, sanctioned selectors at the edge, never the library's internals — the full contract is [styling.md](styling.md).

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

@@ -1,21 +0,0 @@
-# Project structure
-
-Kebab-case throughout, folders and files alike. Exported symbols stay PascalCase — only the filename is kebab.
-
-```
-src/
-  routes/          # TanStack Router file-based routes; routing only — they compose, they don't fetch inline
-  api/             # one folder per API topic — layout and behaviour in data.md
-  components/      # grouped by kind — anatomy in components.md
-  http/            # transport: client, error normalisation — the only transport-aware place (data.md)
-  lib/             # framework-free helpers
-```
-
-Each subtree's own rules live with its topic: [data.md](data.md) for `api/` and `http/`, [components.md](components.md) for
-`components/`.
-
-## Imports
-
-The `#/` alias for anything outside the current folder, plain `./` for siblings. The alias is always `#/` → `src/` — `#` is
-Node's own subpath-import prefix, so it can't collide with an npm scope. Wire it once, through `package.json`'s `imports`
-field where the toolchain resolves it natively, with a matching tsconfig `paths` entry.