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

package/src/llms/install-templates/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+<Keep this file lean — target ~50 lines. Decision test for every line: would the agent make a costly mistake without it? If
+it would just need to read a file first, cut it. Dev commands, path aliases, and tool config are discoverable from the files
+themselves.>
+
+<One paragraph: what the app is and the stack in one line.>
+
+Scripts, deps, and setup: [`README.md`](./README.md) and [`package.json`](./package.json) are the source of truth. Check the
+`package.json` scripts before running or suggesting a command — don't infer one exists by pattern-matching a sibling.
+
+## Read before you write
+
+<One bullet per doc in docs/, each with when to read it, e.g.:>
+
+- [`docs/<topic>.md`](./docs/<topic>.md) — <what it covers>. Read before <the change it governs>.
+
+[`docs/index.md`](./docs/index.md) registers all of them.
+
+## Working here
+
+<The fenced block below is the only part of this file `npx web-ui-install` touches: its content comes from this template and
+is refreshed on every skills install. Everything else in the file is scaffolded once by the setup skill and then owned by the
+repo.>
+
+<!-- imf-web-ui:begin — managed by `npx web-ui-install`; edits inside the fence are overwritten -->
+
+`.agents/skills/imf-web-ui-*` is vendored from `@imfusion/web-ui` and resynced with `npx web-ui-install`. Don't edit it and
+don't put repo conventions there. Load the matching `imf-web-ui-*` skill before writing code, styles, data fetching, or docs;
+repo docs hold only what is unique to this repo.
+
+<!-- imf-web-ui:end -->
+
+<Repo-specific agent guidance: generated files that are committed, tools to verify APIs against, things never to touch.>

package/src/llms/install-templates/codex-hooks.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/session-start.sh\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/stop.sh\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/subagent-start.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/user-prompt-submit.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/llms/install-templates/hooks/baseline-staleness.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+# Advisory baseline-staleness check, meant to be called from the repo's pre-commit hook.
+# Compares the installed imf-web-ui skill markers against the installed package version
+# and warns on drift. Always exits 0 — staleness never blocks a commit.
+PKG=node_modules/@imfusion/web-ui/package.json
+[ -f "$PKG" ] || exit 0
+CURRENT=$(node -p "require('./$PKG').version" 2>/dev/null) || exit 0
+
+for marker in .agents/skills/imf-web-ui-*/.imf-web-ui-skill-version.json; do
+  [ -f "$marker" ] || continue
+  INSTALLED=$(node -p "require('./$marker').version" 2>/dev/null) || continue
+  if [ "$INSTALLED" != "$CURRENT" ]; then
+    echo "imf-web-ui skills are stale ($INSTALLED installed, package is $CURRENT) — run: npx web-ui-install"
+    break
+  fi
+done
+exit 0

package/src/llms/install-templates/hooks/session-start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# SessionStart: inject the web-ui router pointer once per session. Fixed string — the
+# hook-injection eval asserts on it verbatim.
+echo "This project depends on @imfusion/web-ui. Start at the imf-web-ui skill: it decides whether guidance is needed and routes to the right companion. Repo docs carry only what is unique to this repo."
+exit 0

package/src/llms/install-templates/hooks/stop.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+# Stop: the turn-end verify gate. When this turn edited source files, block the
+# agent from finishing once, instructing it to run the project's verification.
+# Both hosts send stop_hook_active=true when the turn continues because of a
+# prior block, so the gate can never loop. Fails open everywhere else: no git,
+# a clean tree, or no edit evidence in the transcript all pass silently.
+PAYLOAD=$(cat)
+printf '%s' "$PAYLOAD" | grep -q '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+[ -n "$(git status --porcelain -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.css' 2>/dev/null)" ] || exit 0
+# Gate only turns that actually edited files — a tree left dirty by an earlier
+# session must not block a question-answering turn. Edit evidence: Write/Edit
+# tool calls (Claude transcript) or apply_patch calls (Codex rollout).
+TRANSCRIPT=$(printf '%s' "$PAYLOAD" | sed -n 's/.*"transcript_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)
+[ -f "$TRANSCRIPT" ] || exit 0
+grep -q '"name":"Write"\|"name":"Edit"\|"name":"MultiEdit"\|"name":"NotebookEdit"\|apply_patch' "$TRANSCRIPT" || exit 0
+printf '{"decision":"block","reason":"web-ui stop gate: this turn changed source files. Run the project verification (verify:typecheck, verify:lint, and verify:format at minimum), fix what it reports, then finish. If it already ran after the last change, say so and finish."}\n'
+exit 0

package/src/llms/install-templates/hooks/subagent-start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# SubagentStart: subagents don't reliably inherit the parent session's SessionStart
+# context, so they get the same router pointer. Text byte-identical to session-start.sh.
+echo "This project depends on @imfusion/web-ui. Start at the imf-web-ui skill: it decides whether guidance is needed and routes to the right companion. Repo docs carry only what is unique to this repo."
+exit 0

package/src/llms/install-templates/hooks/user-prompt-submit.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# UserPromptSubmit: one-line per-prompt pointer to the companion skills. Fixed string —
+# the hook-injection eval asserts on it verbatim.
+echo "web-ui: check imf-web-ui-components before using a component API, imf-web-ui-conventions before writing code, styles or docs, and imf-web-ui-ux when shaping a screen or flow."
+exit 0

package/src/llms/install-templates/settings.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/session-start.sh\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/stop.sh\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/subagent-start.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/user-prompt-submit.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/llms/llms.gen.txt

@@ -73,6 +73,23 @@ Off-canvas panel that slides in from a screen edge. Use for mobile navigation, s
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .drawer (jq: jq '.drawer' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/drawer.md
 
+## Field
+- category: Inputs, status: stable
+Accessible field composition for a label, form control, supporting description, and inline validation message. Use it to associate a control such as Input, Checkbox, or Select with field state including valid, invalid, dirty, touched, filled, and focused.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .field (jq: jq '.field' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/field.md
+
+## Fieldset
+- category: Inputs, status: stable
+Semantic grouping for related form controls with a shared legend. Also called a form group; use it to communicate a common topic and propagate disabled state without introducing a decorative container.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .fieldset (jq: jq '.fieldset' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/fieldset.md
+
+## Icon
+- category: Display, status: stable
+Semantic color wrapper for an icon imported from the Web UI icons entry. Use it when an icon needs a named foreground role instead of the inherited currentColor.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .icon (jq: jq '.icon' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## ImageDisplayOptions
 - category: Inputs, status: experimental
 A panel or toolbar of controls bound to an image dataset's display options.

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

@@ -2,8 +2,8 @@
 name: imf-web-ui
 description:
   "Entry point for UI work in a project that depends on @imfusion/web-ui. Decides whether guidance is needed at all, then
-  routes to the right companion skill — component reference, UX guidance, or frontend patterns. Load when adding or editing
-  UI in a consumer repo."
+  routes to the right companion skill — component reference, UX guidance, or frontend conventions. Load when adding or
+  editing UI in a consumer repo."
 ---
 
 # imf-web-ui
@@ -24,16 +24,17 @@ Guidance skills exist to fill gaps, not to add ceremony to clear tasks.
 
 ## Routing
 
-| The task at hand                                                                                      | Open                                 |
-| ----------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| Using a specific component; checking props, sub-components, or defaults                               | `imf-web-ui-components`              |
-| First-time setup, adding a library dependency, or components rendering unstyled/broken                | `imf-web-ui-setup`                   |
-| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states  | `imf-web-ui-ux`                      |
-| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing     | `imf-web-ui-frontend-patterns`       |
-| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-imfusion-frontend-setup` |
-
-The last row is narrow on purpose. It's for "what is this project missing?" — a question about the repo as a whole. Being
-asked to add one config file is just that edit; make it, and don't open a skill to do so.
+| The task at hand                                                                                      | Open                                    |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Using a specific component; checking props, sub-components, or defaults                               | `imf-web-ui-components`                 |
+| First-time setup, adding a library dependency, or components rendering unstyled/broken                | `imf-web-ui-setup` (`library-setup`)    |
+| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states  | `imf-web-ui-ux`                         |
+| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing     | `imf-web-ui-conventions`                |
+| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-setup` / `imf-web-ui-audit` |
+| Installing or checking agent tooling: vendored skills, lifecycle hooks, registrations, and staleness  | `imf-web-ui-setup` / `imf-web-ui-audit` |
+
+The two setup rows are narrow on purpose. They're for "what is this project missing?" — a question about the repo as a whole.
+Being asked to add one config file is just that edit; make it, and don't open a skill to do so.
 
 Tasks routinely span two: building a screen usually means `imf-web-ui-ux` for the shape and `imf-web-ui-components` for the
 APIs. That's normal — open both, in that order.

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

@@ -0,0 +1,119 @@
+---
+name: imf-web-ui-audit
+description:
+  "Read-only health check for an ImFusion frontend against the conventions baseline. Audit the full project or any topic,
+  including library-setup, tooling, git, npm-project, authentication, project-structure, docs-structure, data, testing,
+  React, TypeScript, class names, validation, components, styling, assets, library-boundary, and tokens. Reports broken
+  pieces, missing pieces, working deviations, present evidence, and unverified state, then turns them into an actionable
+  plan."
+argument-hint: "[full|<topic>]"
+allowed-tools: Read Glob Grep
+---
+
+# imf-web-ui-audit
+
+You are the frontend health-check auditor, and you run as an orchestrator: one investigator per topic gathers the evidence,
+you merge their findings and turn them into an actionable plan. Follow the applicable `imf-web-ui-conventions` topics, cite
+repository evidence, distinguish defects from working deviations, and never present the baseline as universal best practice.
+
+An audit belongs in plan mode: it ends in work to approve, not in files to write.
+
+## Workflow
+
+1. Resolve the argument. Bare means `full`; a topic selects one row below. If no topic matches, list every available topic
+   instead of guessing or widening the scope.
+2. Enter the host's plan mode, unless one of the exceptions after step 5 applies. If plan mode is not already active, use the
+   host plan-mode control before dispatching anything.
+3. Dispatch one investigator per in-scope topic, using the host's subagent mechanism, as concurrently as the host allows.
+   Investigators are cheap and narrow: each one gets a single topic and reports back. A host with no subagent mechanism is
+   not a blocker — work the topics inline in this session, in the same order, to the same contract.
+4. Merge what comes back. Findings you did not gather yourself are the report; do not re-inspect files an investigator
+   covered. Reconcile conflicts by reading the cited evidence, and drop any finding whose citation does not hold.
+5. Deliver the merged report and the plan in the host plan, from the shared report contract at
+   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md), with the mode label
+   `audit`. The plan's ordered steps are the `Next action` lines of the findings, grouped by topic and cheapest-first;
+   `Present` findings produce no steps.
+
+Some runs take the report somewhere other than a plan. When the human asks for the durable file, or the host has no plan
+mode, write the same content to `AUDIT_REPORT.md` and preserve everything under `## Reviewer notes` verbatim. When another
+skill invokes the audit as its verification step, report the findings to that caller and stay out of plan mode — the caller
+owns the flow, and the human has usually just left plan mode to let its work happen.
+
+## Dispatching an investigator
+
+Each investigator prompt carries, in full:
+
+- the topic name and the path of its convention topic file;
+- the topic's block from the shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md), and
+  the instruction to check every box in it;
+- the safety constraint below, verbatim — an investigator that reaches for a shell breaks the audit's only guarantee;
+- the report contract's entry format, so findings arrive mergeable: severity, reference, short title, `path:line` evidence,
+  impact, next action;
+- the instruction to report findings back as its result and write no files.
+
+An investigator reports on its topic alone. Anything it notices outside that topic goes back as a note for the orchestrator
+to route, not as a finding it rules on.
+
+## Checklist
+
+The shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md) is the working checklist: a
+full audit covers every block, a scoped audit covers the requested block plus its dependencies. The audit is not complete
+until every in-scope box has been checked by the investigator that owns it and its evidence appears in the report. The
+checklist itself is not edited during an audit.
+
+## Safety
+
+Use only static inspection: Read, Glob, Grep, and equivalent non-executing search tools. Do not use a shell or invoke Node,
+npm, npx, package scripts, hooks, config imports, linters, tests, builds, Git commands, or project binaries. Read config as
+text and report runtime or machine-local state that cannot be established statically as unverified. This binds every
+investigator too — a dispatched agent inherits the audit's constraint, not the host's default freedom, so the prompt that
+dispatches it repeats this paragraph verbatim.
+
+An audit writes at most one file: `AUDIT_REPORT.md`, in the two cases named in the workflow. Investigators write nothing.
+Neither Write nor the host's dispatch tool is pre-approved in `allowed-tools` — `allowed-tools` names what an audit needs on
+every run, and both of these follow the host's ordinary approval when a run needs them. Host-managed hooks may run after that
+write; the skill neither invokes nor suppresses them, but it does report broken or unexpected hook behavior found during
+static inspection.
+
+## Topics
+
+| Topic               | Assess                                                                         |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `library-setup`     | styles import, `WebUIProvider`, and library package wiring                     |
+| `library-boundary`  | imports, wrappers, type derivation, and peer boundaries                        |
+| `react`             | component roles, state ownership, and effects discipline                       |
+| `components`        | component folders, anatomy, and colocation                                     |
+| `typescript`        | functional style, types, and naming                                            |
+| `styling`           | CSS Modules, tokens, and prohibited styling systems                            |
+| `tokens`            | names, authored default values, and families from the shipped token index      |
+| `class-names`       | CVA variants, `cx`, and incoming `className` handling                          |
+| `validation`        | runtime schemas, boundary parsing, and derived types                           |
+| `data`              | transport, schemas, query/mutation options, keys, and invalidation             |
+| `authentication`    | current-user query, public/app guards, login, and logout                       |
+| `project-structure` | source tree, route groups, optional app shell, naming, and imports             |
+| `testing`           | test boundaries and verification coverage                                      |
+| `npm-project`       | package metadata, scripts, pins, npm, and Node configuration                   |
+| `tooling`           | dependency selection, devtools, Prettier, ESLint, TypeScript, and verification |
+| `git`               | tracked hooks, verification scopes, and staleness wiring                       |
+| `assets`            | image formats and static asset handling                                        |
+| `docs-structure`    | README, AGENTS, docs index, and content boundaries                             |
+| `agent-tooling`     | installed skills, AGENTS fence, lifecycle hooks, registrations, staleness      |
+
+Report everything within the selected topic: defects and working deviations alike, with no severity-based filtering.
+
+## Agent-tooling assessment reference
+
+The baseline is the conventions [agent-tooling topic](../imf-web-ui-conventions/topics/agent-tooling.md): the complete bundle
+with matching version markers, the AGENTS fence, and the lifecycle hooks installed and registered for both hosts
+(`.claude/settings.json` and `.codex/hooks.json`) or consciously adapted. Hooks or registrations beyond the shipped set — the
+three injection hooks, the stop gate, plus `baseline-staleness.sh` — are drift, 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.
+
+Version drift is part of this topic: compare the declared version in `package.json`, the installed
+`node_modules/@imfusion/web-ui/package.json`, and every `.imf-web-ui-skill-version.json` marker, then report the drift and
+point at `imf-web-ui-update`. The registry is unreachable from a static audit, so a line saying that a newer version may
+exist is unverified.
+
+Use the shared report template as the report contract. It defines the headings, ordering, empty-section marker, evidence
+format, and reviewer-note preservation rules; do not duplicate that contract here.

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

@@ -1,9 +1,10 @@
 ---
 name: imf-web-ui-components
 description:
-  "Look up @imfusion/web-ui component APIs without reading their source: the two-hop lookup (identity index -> prop data),
-  compound components, and integrations. Load when you need the props, sub-components, or defaults of a specific component —
-  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-setup)."
+  "Look up @imfusion/web-ui component APIs and icon glyphs without reading source. Load when you need a component's props,
+  sub-components, defaults, or a supplied icon — not for choosing between components (imf-web-ui-ux) or first-time setup
+  (imf-web-ui-setup library-setup)."
+allowed-tools: Bash
 ---
 
 # imf-web-ui-components
@@ -15,6 +16,8 @@ reading source or checking out the library's repo:
   and a one-sentence description of what it's for and what else it's called.
 - **`node_modules/@imfusion/web-ui/src/docgen/doc.gen.json`** — full prop tables (name, type, default, description) for every
   component, keyed by kebab-case folder name.
+- **`node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json`** — searchable icon names, styles, categories, and tags.
+  Read it only when the task needs an icon.
 
 Neither file is reachable through the package's pretty import paths (`@imfusion/web-ui/llms.txt`,
 `@imfusion/web-ui/docgen.json`) — those are Node module-resolution aliases, meaningless to `cat`/`jq`/`grep` reading files
@@ -72,6 +75,56 @@ don't guess at an API — that's a real gap to report, not something to work aro
 maintainer, or file it in the [WEBSDK Jira project](https://imfusion.atlassian.net/browse/WEBSDK) if you have access. If the
 gap is about _which_ component to use rather than a missing one, that's a design question: open `imf-web-ui-ux`.
 
+## Icons
+
+When the task mentions an icon, glyph, symbol, or `@imfusion/web-ui/icons`, query the icon catalog before choosing a name. Do
+not load it for ordinary component work.
+
+Search one relevant term at a time, then read only the matching records:
+
+```sh
+node -e '
+  const q = process.argv[1].toLowerCase();
+  const icons = JSON.parse(
+    require("fs").readFileSync(
+      "node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json",
+      "utf8"
+    )
+  );
+  console.log(
+    JSON.stringify(
+      icons
+        .filter(icon => [icon.name, icon.category, ...icon.tags]
+          .join(" ")
+          .toLowerCase()
+          .includes(q))
+        .slice(0, 20),
+      null,
+      2
+    )
+  );
+' "add"
+```
+
+Import the chosen glyph and `Icon` from `@imfusion/web-ui/icons`. Render it through `Icon`, including when it inherits the
+surrounding color:
+
+```tsx
+import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
+
+<Icon glyph={ArrowRight} aria-hidden />;
+```
+
+Use `Icon` for every rendered icon. Pass the component reference, not a rendered element:
+
+```tsx
+import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
+
+<Icon glyph={ArrowRight} size={16} variant="primary" aria-label="Continue" role="img" />;
+```
+
+Never import `iconoir-react` or another icon package directly.
+
 ## Compound components
 
 A component whose docgen entry has a non-empty `subComponents` array is used as a namespace, not a single import — e.g.

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

@@ -0,0 +1,57 @@
+---
+name: imf-web-ui-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 setup, library boundary, React, components, TypeScript, styling,
+  tokens, validation, data layer, authentication, project structure, testing, tooling, npm project, git, agent tooling,
+  assets, and 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, choosing any dependency, or
+  installing the vendored skills and lifecycle hooks."
+---
+
+# imf-web-ui-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.
+
+When a project has an established convention, it wins. The audit skill records a working difference as a deviation; the setup
+skill proposes only the changes the project asks it to make.
+
+## The topics
+
+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-setup.md](topics/library-setup.md)         | styles import, `WebUIProvider`, and broken library wiring           | installing or repairing library wiring                  |
+| [library-boundary.md](topics/library-boundary.md)   | staying behind `@imfusion/web-ui`, wrappers, type derivation, peers | touching anything that renders library components       |
+| [authentication.md](topics/authentication.md)       | current-user source, public/app guards, login and logout            | setting up or reviewing route protection                |
+| [react.md](topics/react.md)                         | component roles, state kinds and owners, effects discipline         | writing new screens, components, or wrappers            |
+| [components.md](topics/components.md)               | component anatomy on disk: grouping, folders, colocation            | adding a component file                                 |
+| [typescript.md](topics/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
+| [styling.md](topics/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
+| [tokens.md](topics/tokens.md)                       | shipped CSS-variable names grouped by family                        | choosing a design token                                 |
+| [class-names.md](topics/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
+| [validation.md](topics/validation.md)               | runtime schemas, boundary parsing, schema-derived types             | accepting data the frontend does not own                |
+| [data.md](topics/data.md)                           | `api/`+`http/` shape, query/mutation patterns and invalidation      | adding an API topic, a fetch, or a mutation             |
+| [project-structure.md](topics/project-structure.md) | the `src/` tree, route groups, file naming, imports                 | adding files rather than editing existing ones          |
+| [testing.md](topics/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
+| [tooling.md](topics/tooling.md)                     | the topic→tool map, tool configuration, and verification            | choosing a dependency or touching tool config           |
+| [npm-project.md](topics/npm-project.md)             | `package.json`, the `verify:*` script set, dependency pinning       | running or adding a script, adding a dependency         |
+| [git.md](topics/git.md)                             | `git:config`, verify scopes, staleness at commit time               | wiring hooks or the commit path                         |
+| [agent-tooling.md](topics/agent-tooling.md)         | vendored skills, lifecycle hooks, registrations, Codex trust        | installing or reviewing the shipped agent tooling       |
+| [assets.md](topics/assets.md)                       | image formats, the WebP recipe                                      | adding images or other static assets                    |
+| [docs-structure.md](topics/docs-structure.md)       | what a repo documents, where, how it's written                      | writing or restructuring repo docs                      |
+
+## Topic format
+
+Topics are manifests, not essays: `##` sections group rule bullets, and each section is one auditable unit. A rule is one
+imperative bullet; only a pushback-prone rule carries a one-line why. Snippets illustrate rules, prose never replaces them.
+Each topic's `##` sections map 1:1 to its block in [templates/AUDIT_CHECKLIST.md](templates/AUDIT_CHECKLIST.md) — add,
+remove, or rename a section and the checklist follows in the same change.
+
+`imf-web-ui-setup` proposes approved bootstrap changes, while `imf-web-ui-audit` reports the current state against this
+baseline.

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

@@ -0,0 +1,141 @@
+# Convention audit checklist
+
+One block per topic, one box per topic section. Check a box only after checking that section's rules against the repo. A full
+audit checks every box; a scoped audit names its topics first and checks only their blocks. Blocks mirror each topic's `##`
+sections one to one — change a topic's sections and this file follows in the same commit.
+
+## Library setup — `library-setup`
+
+- [ ] Entry-point wiring
+- [ ] Symptoms of broken setup
+
+## Library boundary — `library-boundary`
+
+- [ ] Stay behind the library
+- [ ] Wrap primitives when the app has a reason to
+- [ ] Derive types, don't import them
+- [ ] Integrations own their peers
+- [ ] Styling crosses the boundary through seams
+
+## Authentication — `authentication`
+
+- [ ] Starter shape
+- [ ] One current-user query
+- [ ] The two route groups
+- [ ] Login and logout
+- [ ] App shell
+
+## Project structure — `project-structure`
+
+- [ ] Layout
+- [ ] Application boundary
+- [ ] Imports
+
+## React — `react`
+
+- [ ] Composition: pages (smart containers), partials, dumb components
+- [ ] Compose, don't configure
+- [ ] Put state where its truth lives
+- [ ] Effects: last resort, and named
+- [ ] Reading list
+
+## Components — `components`
+
+- [ ] As dumb as possible
+- [ ] Grouping
+- [ ] One file or a folder
+- [ ] Colocation
+
+## TypeScript & code style — `typescript`
+
+- [ ] Types
+- [ ] Immutability & expressions
+- [ ] Naming
+
+## Styling — `styling`
+
+- [ ] CSS authoring
+- [ ] Build custom UI from tokens
+- [ ] Override through the sanctioned seams
+- [ ] The color system
+- [ ] Responsive styling
+
+## Tokens — `tokens`
+
+- [ ] Token index
+
+## Class names in components — `class-names`
+
+- [ ] CVA is the only tool
+- [ ] Merging `className`
+- [ ] Shared CVA modules
+
+## Validation — `validation`
+
+- [ ] Boundaries
+- [ ] Schema first, type derived
+- [ ] TanStack Router search params
+- [ ] Failure handling
+
+## Data — `data`
+
+- [ ] The shape
+- [ ] The network boundary validates
+- [ ] Errors are values
+- [ ] Topic registry and key factory
+- [ ] Options factories and naming
+- [ ] Router context access
+- [ ] Automatic invalidation
+- [ ] Testing the data layer
+
+## Testing — `testing`
+
+- [ ] Naming
+- [ ] What gets a test
+- [ ] Layer-specific recipes
+
+## Tooling — `tooling`
+
+- [ ] Topic-to-tool map
+- [ ] When a library owns a layer
+- [ ] Devtools
+- [ ] Docs over memory
+- [ ] Prettier
+- [ ] ESLint
+- [ ] tsconfig
+- [ ] Staged files
+- [ ] CSS class names
+
+## npm project — `npm-project`
+
+- [ ] package.json
+- [ ] Scripts
+- [ ] Dependencies
+
+## Git — `git`
+
+- [ ] git:config
+- [ ] Verify scopes
+- [ ] Staleness at commit time
+
+## Assets — `assets`
+
+- [ ] Importing
+- [ ] Photographs — WebP
+- [ ] Other formats
+- [ ] Scope
+
+## Documentation structure — `docs-structure`
+
+- [ ] The shape
+- [ ] Repo docs hold only what is unique to the repo
+- [ ] How docs are written
+- [ ] Staleness at commit time
+
+## Agent tooling — `agent-tooling`
+
+- [ ] The skill bundle
+- [ ] The hooks
+- [ ] Codex trust
+- [ ] Dependency-shipped skills
+- [ ] Hook docs