@imfusion/web-ui 0.6.4-dev.8.g41d03f2f → 0.7.0

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

@@ -20,11 +20,11 @@ or suggesting a command.
 
 <The installer owns only the fenced block below. It refreshes that block on every install; the rest belongs to the project.>
 
-<!-- imf-web-ui:begin — managed by `npx web-ui-install`; edits inside the fence are overwritten -->
+<!-- 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`. Do not edit the
-vendored copy or put project-specific conventions there. Load the matching skill before changing UI, styles, data, tests, or
-docs.
+`.agents/skills/imf-web-ui-*` is vendored from `@imfusion/web-ui` and resynced with `npx web-ui install skills`. Do not edit
+the vendored copy or put project-specific conventions there. Load the matching skill before changing UI, styles, data, tests,
+or docs.
 
 <!-- imf-web-ui:end -->
 

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

@@ -6,11 +6,18 @@ 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
+# .claude/skills may be a symlink to .agents/skills; skip markers already read.
+seen=""
+for marker in .agents/skills/imf-web-ui*/.imf-web-ui-skill-version.json .claude/skills/imf-web-ui*/.imf-web-ui-skill-version.json; do
   [ -f "$marker" ] || continue
+  real=$(cd "$(dirname "$marker")" && pwd -P)/$(basename "$marker")
+  case " $seen " in
+    *" $real "*) continue ;;
+  esac
+  seen="$seen $real"
   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"
+    echo "imf-web-ui skills are stale ($INSTALLED installed, package is $CURRENT) — run /imf-web-ui-update, or: npx web-ui install skills && npx web-ui install hooks"
     break
   fi
 done

package/src/llms/llms.gen.txt

@@ -113,6 +113,12 @@ Navigation menu with horizontal or vertical triggers and anchored flyout panels.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .navigation-menu (jq: jq '.navigation-menu' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/navigation-menu.md
 
+## NumberField
+- category: Inputs, status: experimental
+Numeric entry with increment and decrement controls. Also called a number field, spinner, or stepper; use it instead of Input with type="number" whenever a value is numeric. NumberField.Stepper composes the whole control in one element and takes a scrub prop that turns its label into a drag handle.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .number-field (jq: jq '.number-field' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/number-field.md
+
 ## Popover
 - category: Display, status: stable
 Floating panel anchored to a trigger for contextual content, quick forms, or actions. Also called a popup or flyout; use Tooltip for hints without interaction.
@@ -195,5 +201,5 @@ Hover- or focus-triggered label for brief help about a control or term. Also cal
 
 ## Typo
 - category: Display, status: stable
-Semantic text primitives for headings, paragraphs, lists, quotes, links, and inline code. The namespace uses native HTML elements and token-based text roles.
+Semantic text primitives for display and standard headings, paragraphs, lists, quotes, links, and inline code. The namespace uses native HTML elements and token-based text roles.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .typo (jq: jq '.typo' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)

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

@@ -1,45 +1,68 @@
 ---
 name: imf-web-ui
 description:
-  "Route UI work in a project that uses @imfusion/web-ui. Use this skill whenever a user adds, edits, styles, or reviews UI
-  in a consumer project, even if they do not mention the library. Decide whether guidance is needed, then open only the
-  companion skills that match the task."
+  "Route UI work and library questions in a project that uses @imfusion/web-ui. Use this skill whenever a user adds, edits,
+  styles, or reviews UI, or asks about library setup, brand assets, favicons, theming, or usage in a consumer project, even
+  if they do not mention the library. Open only the matching packaged guide or companion skill."
 ---
 
 # Route Web UI work
 
-Start here for UI work in a project that uses `@imfusion/web-ui`. This skill is a map, not a second copy of every convention.
+Start here for UI work and library questions in a project that uses `@imfusion/web-ui`. This skill is a map, not a second
+copy of every convention.
 
 ## 1. Decide whether guidance is needed
 
-Skip a companion when the task is explicit and small, an existing local pattern already solves it, and the library usage is
-already correct. Do the work. Look up an API silently only when you are unsure.
+Skip a companion when the task is explicit and small, an existing local pattern already solves it in the file being changed,
+and the library usage is already correct. Do the work. Look up an API silently only when you are unsure.
 
-Use a companion when the task involves a choice, a missing setup piece, a new file, or a library convention the project may
-not already have.
+Use a companion when the task involves a choice, a missing setup piece, a new UI file, or a library convention the project
+may not already have. Open a companion by invoking its skill; reading one of its files directly does not load its workflow.
 
 ## 2. Route the task
 
-| Task                                                              | Open                                                   |
-| ----------------------------------------------------------------- | ------------------------------------------------------ |
-| Look up a component, part, prop, default, or icon                 | `imf-web-ui-components`                                |
-| Choose components or shape a screen or flow                       | `imf-web-ui-ux`                                        |
-| Write or update documentation                                     | `/documentation-writer`, then `imf-web-ui-conventions` |
-| Write a wrapper, custom UI, CSS, data layer, validation, or tests | `imf-web-ui-conventions`                               |
-| Install the library or bootstrap project tooling                  | `imf-web-ui-setup`                                     |
-| Inspect an existing project without changing it                   | `imf-web-ui-audit`                                     |
-| Update the package, skills, or hooks                              | `imf-web-ui-update`                                    |
+| Task                                                                 | Open                       |
+| -------------------------------------------------------------------- | -------------------------- |
+| Understand library setup, brand assets, theming, or usage            | Packaged user guides below |
+| Look up a component, part, prop, default, or icon                    | `imf-web-ui-components`    |
+| Choose components or shape a screen, form, or flow                   | `imf-web-ui-ux`            |
+| Write or update documentation                                        | `imf-web-ui-conventions`   |
+| Write a wrapper, custom UI, CSS, data layer, validation, or tests    | `imf-web-ui-conventions`   |
+| Choose a routing, data, form, or validation library for the project  | `imf-web-ui-conventions`   |
+| Install the library or bootstrap project tooling                     | `imf-web-ui-setup`         |
+| Diagnose a broken install: unstyled output, missing tokens, no theme | `imf-web-ui-setup`         |
+| Inspect an existing project without changing it                      | `imf-web-ui-audit`         |
+| Update the package, skills, or hooks                                 | `imf-web-ui-update`        |
 
-A screen often needs both `imf-web-ui-ux` and `imf-web-ui-components`, in that order. Setup and audit are for project-wide
-questions, not every one-file edit.
+A new form opens `imf-web-ui-ux`, even when its fields and action are already specified. A screen often needs both
+`imf-web-ui-ux` and `imf-web-ui-components`, in that order. Setup and audit are for project-wide questions, not every
+one-file edit.
+
+### Read a packaged user guide
+
+Read only the matching page under `node_modules/@imfusion/web-ui/docs/user-guide/` in the consumer project:
+
+| Question                                                                 | Page                 |
+| ------------------------------------------------------------------------ | -------------------- |
+| What the library provides, installation, stylesheet, and provider wiring | `GettingStarted.mdx` |
+| Favicons, social sharing images, and static brand files                  | `BrandAssets.mdx`    |
+| Composition, CSS overrides, state attributes, and color schemes          | `UsagePatterns.mdx`  |
+| Token families and customization                                         | `Tokens.mdx`         |
+| Agent skills, hooks, and their installation                              | `AgentTooling.mdx`   |
+| Library boundaries and implementation choices                            | `HowItsBuilt.mdx`    |
+
+Read MDX as text. Its imports, JSX previews, and Storybook navigation are presentation, not instructions to install or run
+Storybook in the consumer. Cite the packaged page when answering a library question. Use `imf-web-ui-components` for exact
+props and the conventions `tokens` topic for exact token names and defaults.
 
 ## 3. Keep project choices
 
 The host project's existing conventions win. The companion skills fill gaps; they do not justify refactoring a working
 styling system, state library, or folder structure.
 
-When a task needs TanStack Router, Query, Form, Table, or Store and the project has no incumbent, propose the matching
-library and read its current documentation with `npx @tanstack/cli` before using it.
+When a task needs TanStack Router, Query, Form, Table, or Store and the project has no incumbent, open
+`imf-web-ui-conventions` for the house position on that layer, then read the library's current documentation with
+`npx @tanstack/cli` before using it. The recommendation lives in the conventions topics, not here.
 
 ## 4. Ask only when the choice depends on missing context
 

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

@@ -10,22 +10,35 @@ allowed-tools: Read Glob Grep
 
 # Audit a consumer project
 
-This is a read-only audit. Compare the project with the selected `imf-web-ui-conventions` topics, report evidence, and end
-with work the human can approve. The baseline is an ImFusion default, not a universal law; a deliberate project choice is a
-deviation, not a defect.
+This is a read-only audit. Its job is to align a project with its conventions: compare the project against the selected
+`imf-web-ui-conventions` topics, report evidence, and end with work the human can approve.
+
+A gap against a convention is high severity: the project agreed to the conventions. Only a deliberate, stated reason to
+differ lowers it.
+
+Anything else belongs under `Suggestions`: findings from running the code, investigating, or reading through. Report it, keep
+it low, and do not let it crowd the sections a consumer has to act on.
 
 ## Workflow
 
 1. Resolve the argument. Bare means `full`; an unknown topic is an error, not a reason to widen the scope.
 2. Enter plan mode unless this audit is being called as verification by another skill or the host has no plan mode.
-3. Assign one investigator to each in-scope topic. An investigator checks every section in that topic and writes nothing. If
-   the host cannot dispatch agents, inspect the topics inline in the same order.
+3. Read the report template and existing reviewer notes, then dispatch one investigator per in-scope topic. Tell each
+   investigator to use only `Read`, `Glob`, and `Grep`, with no shell commands or writes. An investigator checks every
+   section in that topic and writes nothing. Once dispatch starts, the host performs no repository inspection: the returned
+   reports are the evidence, and the host merges them without reading or searching the files again. Gathering the evidence
+   twice spends context on the second pass and reports what the host still remembers. Inspect a topic inline only after its
+   dispatch has been tried and refused, and say which attempt failed.
 4. Merge the evidence into the shared report format in
-   [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md).
-5. Put each finding's `Next action` into an ordered plan, grouped by topic and cheapest first. Present the report and wait
-   for approval; an audit does not edit the project.
+   [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md). Before presenting or writing it, check that every
+   Broken, Missing, Deviation, and Unverified entry has a severity, evidence, impact, and next action; do not compact
+   Unverified entries.
+5. Put each finding's `Next action` into an ordered plan, grouped by topic and cheapest first. The plan is separate from the
+   report contract: present it in the host plan or response, never as another heading in `AUDIT_REPORT.md`. Present the
+   report and wait for approval; an audit does not edit the project.
 
-If the caller needs a durable report, write `AUDIT_REPORT.md` and preserve everything under `## Reviewer notes` verbatim.
+If the caller needs a durable report, write `AUDIT_REPORT.md` with exactly the template's H2 headings and preserve everything
+under `## Reviewer notes` verbatim.
 
 ## Finding format
 
@@ -37,8 +50,9 @@ Classify every result as one of these:
 - **Present**: the rule is met, with evidence.
 - **Unverified**: static inspection cannot establish it.
 
-Use the report contract's severity, `path:line` evidence, concrete impact, and smallest next action. Do not promote an
-optional tool or a working alternative to a missing finding.
+Use the report contract's severity, `path:line` evidence, concrete impact, and smallest next action. Unverified entries use
+that same structure: unavailable runtime evidence, the impact of the unknown, and the check that resolves it. Do not promote
+an optional tool or a working alternative to a missing finding.
 
 ## Topics
 

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

@@ -13,13 +13,14 @@ Use the generated package indexes. They are smaller and more reliable than readi
 
 ## Component lookup
 
-1. Read the identity index:
+1. Read the identity index first, even when you already know the component's name: it gives the docgen key and the status.
 
    ```sh
    cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
    ```
 
-   It lists each component's name, category, status, purpose, and docgen entry.
+   It lists each component's name, category, status, purpose, and docgen entry. The docgen entry is the prop source; the
+   `.d.ts` files in `dist/` carry no defaults and hide upstream props behind their base types.
 
 2. Read only the matching entry from docgen:
 
@@ -39,6 +40,9 @@ Use the generated package indexes. They are smaller and more reliable than readi
 Use `doc.gen.json` for Web UI props. A linked upstream page is useful for behavior, composition, and accessibility, but its
 prop table is not authoritative for this package.
 
+A `variant` value belongs to the component that defines it; one component's list is not a global one. `brand` means identity
+color and `primary` means the action color, even where they look alike.
+
 ## If the component is missing
 
 Treat a missing identity-index entry as a real gap. Do not invent an API or silently import the upstream component. Report
@@ -87,7 +91,7 @@ A component whose identity entry says it comes from `@imfusion/web-ui/integratio
 listed optional peer explicitly, then import from that path:
 
 ```tsx
-import { Code } from "@imfusion/web-ui/integrations/code-highlight";
+import { ImageDisplayOptions } from "@imfusion/web-ui/integrations/image-display-options";
 ```
 
 ## Data grids

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

@@ -4,6 +4,7 @@ description:
   "Apply the ImFusion frontend conventions to consumer code. Use this whenever a task writes a wrapper or custom UI, CSS,
   TypeScript, data fetching, validation, tests, project files, configuration, documentation, dependencies, or agent tooling
   in a project that uses @imfusion/web-ui. Read only the topic references that match the task."
+user-invocable: false
 ---
 
 # Frontend conventions
@@ -45,5 +46,5 @@ state without changing files.
 
 ## Documentation
 
-Invoke `/documentation-writer` for new or updated documentation. Use the `docs-structure` topic for repository-specific
-boundaries and conventions; it supplies context for the writer and does not replace the writer's workflow.
+Use the `docs-structure` topic for new or updated documentation. If `/documentation-writer` is available, invoke it for the
+page type and outline; the topic supplies the repository-specific boundaries.

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

@@ -37,7 +37,6 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Compose, don't configure
 - [ ] Put state where its truth lives
 - [ ] Effects: last resort, and named
-- [ ] Reading list
 
 ## Components — `components`
 

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

@@ -12,8 +12,23 @@ Broken, Missing, Deviations, and Unverified entries use:
   - Impact: concrete consequence
   - Next action: smallest selectable follow-up
 
-Present entries name the topic and evidence path. Deviations are selectable follow-up work, not defects. Optional tools are not
-missing findings.
+Present entries name the topic and evidence path. Optional tools are not missing findings.
+
+Where a finding belongs follows from where it came from, not from how strongly you hold it.
+
+A convention names it:
+- Broken: the convention is followed but does not work. Something is unmounted, unwired, or fails at runtime.
+- Missing: a convention expects it and the project has nothing there.
+- Deviations: it works, and differs from what a convention says.
+
+These three are high severity by default. The project agreed to the conventions; a gap against them is not a preference.
+Drop the severity only when the project shows a deliberate reason to differ, and say what the reason is.
+
+Nothing names it:
+- Suggestions: real improvements that no convention asks for. What running the code revealed, what an investigation turned
+  up, what a reader would tidy on their way past. Never high severity, and never a reason to hold up the work.
+
+- Unverified: it could not be checked from the files available.
 -->
 
 ## Verdict
@@ -32,6 +47,10 @@ None.
 
 None.
 
+## Suggestions
+
+None.
+
 ## Present
 
 None.

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

@@ -1,33 +1,38 @@
 # Agent tooling
 
-`npx web-ui-install` manages the Web UI skills and optional lifecycle hooks in a consumer project. This topic explains the
-choices around that installer.
+`npx web-ui install` manages the Web UI skills and optional lifecycle hooks in a consumer project.
 
 ## The skill bundle
 
-Run:
+Run, on a first install:
 
 ```sh
-npx web-ui-install
+npx web-ui install skills --harness=claude
 ```
 
 It installs or refreshes the `imf-web-ui-*` skills, updates the managed `AGENTS.md` fence, and removes skills that the
-package no longer ships. The installer remembers `.claude/skills/`, `.agents/skills/`, or both. Use `--target claude|agents`
-to choose explicitly and `--reconfigure` to choose again.
+package no longer ships. The skills always live in `.agents/skills/`. `--harness` selects `claude`, which also links each
+skill into `.claude/skills/`, `codex`, or `all`; without it, the command prompts and remembers the choice. Pass
+`--reconfigure` to choose again. On a project that already has an install, re-running `install skills` without `--harness`
+reuses the remembered harness instead of narrowing it.
 
 Skill version markers (`.imf-web-ui-skill-version.json`) show which package version installed each skill. Refresh them with
 the installer; do not hand-edit the vendored files.
 
 ## The hooks
 
-Install the optional lifecycle hooks with:
+`install hooks` requires the skills to already be installed for the target harness; without them, it errors and tells you to
+run `install skills` first:
 
 ```sh
-npx web-ui-install --hooks
+npx web-ui install skills --harness=claude
+npx web-ui install hooks --harness=claude
 ```
 
-The installer owns the scripts under `.agents/hooks/imf-web-ui/` and merges its registrations into Claude Code and Codex
-settings. It refreshes scripts and removes retired registrations without replacing unrelated entries.
+The installer owns the scripts under `.agents/hooks/imf-web-ui/` and merges its registrations into the registration file for
+the chosen harness only: Claude Code's `.claude/settings.json`, Codex's `.codex/hooks.json`, or both with `--harness=all`. It
+refreshes scripts and removes retired registrations without replacing unrelated entries, and removes its registrations from a
+harness that is not selected.
 
 The shipped events are:
 

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

@@ -2,8 +2,11 @@
 
 ## Importing
 
-Import files from `src/assets/` so the bundler fingerprints and includes them. Do not reference an asset through a
-public-path string.
+Import application images from `src/assets/` so the bundler fingerprints and includes them. Use public URLs for files
+consumed by document metadata or manifests, with a build step that serves the files at those URLs.
+
+For the library's favicon set and social sharing image, read `BrandAssets.mdx` through the packaged user-guide route in
+`imf-web-ui`.
 
 ## Photographs: WebP
 
@@ -17,8 +20,8 @@ Keep the long edge at 2000px or less. WebP is supported by the browser floor.
 
 ## Other formats
 
-Use PNG when the image needs alpha or exact pixels. Use an inline SVG component for icons, logos, and line art so it inherits
-`currentColor` and follows the theme.
+Use PNG when the image needs alpha or exact pixels. Use an inline SVG component for in-app icons, logos, and line art so it
+inherits `currentColor` and follows the theme.
 
 ## Scope
 

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

@@ -85,7 +85,9 @@ export function getDetails(options?: QueryOptions<User>) {
 }
 ```
 
-Callers choose `ensureQueryData`, `useSuspenseQuery`, or another Query API.
+Callers choose `ensureQueryData`, `useSuspenseQuery`, or another Query API. Mutation factories likewise return
+`mutationOptions`, own their mutation key and parsing, and are passed to `useMutation`; do not inline those options at the
+call site.
 
 ## Router context access
 

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

@@ -1,7 +1,7 @@
 # Documentation structure
 
-Keep repository docs useful to a human who has just joined the project. Invoke `/documentation-writer` for new or updated
-documentation. The setup skill can propose the shape; the audit skill can check it.
+Keep repository docs useful to a human who has just joined the project. The setup skill can propose the shape; the audit
+skill can check it.
 
 ## The shape
 

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

@@ -18,7 +18,8 @@ The hooks are tracked in `.githooks/`. Check both the Git setting and the direct
 
 There are two scopes:
 
-- **staged**: `verify:staged`, run by pre-commit. It is fast and checks the staged files plus relevant project-wide checks.
+- **commit**: `verify:staged`, run by pre-commit. It checks whole-repository lint and formatting, then runs project checks
+  for staged inputs.
 - **full**: `verify:full`, the build and complete verification used by CI.
 
 The scripts under `scripts/verify/` own the step lists. Hooks and npm scripts only launch them.
@@ -26,4 +27,5 @@ The scripts under `scripts/verify/` own the step lists. Hooks and npm scripts on
 ## Staleness at commit time
 
 Pre-commit also runs advisory checks for vendored skill markers and documentation drift. If a staged change makes a doc
-stale, update the doc in the same commit. For an outdated installed skill, run `npx web-ui-install` in the consumer project.
+stale, update the doc in the same commit. For an outdated installed skill, run `npx web-ui install skills` (also
+`npx web-ui install hooks` if the project uses hooks) with the project's existing `--harness` in the consumer project.

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

@@ -22,9 +22,18 @@ export function App() {
 Components outside the provider do not receive the library's provider context. Keep upstream imports behind the library; see
 [library-boundary.md](library-boundary.md).
 
+The provider follows the OS color scheme by default. An app that paints its own surfaces from a fixed palette pins the scheme
+instead, so component colors cannot resolve against the opposite scheme:
+
+```tsx
+<WebUIProvider colorScheme="dark">
+```
+
 ## Symptoms of broken setup
 
 - Unstyled components usually mean the `styles.css` import is missing.
-- Wrong colors or unresolved variables usually mean the component is outside `WebUIProvider`.
+- Unresolved variables usually mean the component is outside `WebUIProvider`.
+- Light component colors inside a dark app (or the reverse) mean the scheme is following the OS against a fixed palette. Pin
+  `colorScheme` on the provider.
 - An integration import error usually means its optional peer is missing. Check the component entry in
   `imf-web-ui-components` for the package to install.

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

@@ -45,7 +45,7 @@ Do not target generated CSS Module class names and do not use `!important` to fi
 hook, not a state flag.
 
 ```css
-[data-imf-ui-component="Switch"][data-checked] {
+[data-imf-ui-component="Switch.Root"][data-checked] {
   outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-positive);
 }
 ```
@@ -56,7 +56,7 @@ Use surface roles (`main`, `support`, `minor`), the separate `brand` and `primar
 slots. Override a high-level control when a whole family should change; consume a semantic token in a component.
 
 Foreground roles are for text, icons, borders, and focus rings. Background roles are for fills. The provider sets
-`data-imf-ui-color-scheme="light" | "dark"` on `<html>`.
+`data-imf-ui-color-scheme="light" | "dark"` on `<html>`, from the OS preference unless its `colorScheme` prop pins one.
 
 ## Browser floor
 

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

@@ -8,5 +8,7 @@ Read:
 node_modules/@imfusion/web-ui/src/llms/tokens.gen.json
 ```
 
-It contains the shipped token names and authored defaults. Look up the exact entry instead of guessing a plausible
-`--imf-ui-*` name or copying a token list into the project.
+It contains the shipped token names and authored defaults. Before writing CSS, check every concrete `--imf-ui-*` name the
+file will use against that index or the relevant component stylesheet. A family with one entry does not imply numbered
+variants. When no matching token exists, use an existing documented seam or say that the token is absent instead of guessing
+a plausible name.

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

@@ -1,6 +1,6 @@
 # Tooling
 
-Read this topic before adding a dependency or configuring a tool. Use the tool's current documentation rather than memory.
+Use the tool's current documentation rather than memory.
 
 ## Topic-to-tool map
 
@@ -17,7 +17,7 @@ Read this topic before adding a dependency or configuring a tool. Use the tool's
 | Format                | Prettier                                     |
 | Lint                  | ESLint flat config                           |
 | Types                 | `tsc --noEmit`                               |
-| Staged files          | lint-staged or nano-staged                   |
+| Pre-commit checks     | Whole-repository lint and format checks      |
 | Dead code             | Knip via `verify:knip`                       |
 
 ## When a library owns a layer
@@ -65,24 +65,26 @@ tests, requires the `#/` alias instead of parent-relative imports, and uses proj
 Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `#/` paths. Keep
 `import type` for type-only imports.
 
-## Staged files
+## Pre-commit checks
 
-The staged-file runner applies ESLint fixes and Prettier writes only to staged files. It also runs the relevant project
-checks when source or config can affect the dependency graph.
+The pre-commit hook checks the whole repository with ESLint and Prettier, then runs project checks for staged inputs that can
+affect generated files, types, dependencies, or TeamCity configuration. It does not rewrite files during a commit; use
+`npm run format` to apply Prettier changes explicitly.
 
-## CSS class names
+## Vite plugins
 
-Register Web UI's `readableCssModuleNames` plugin in every compiler that processes the app's CSS, including development,
-Storybook, and production:
+Register Web UI's Vite plugins in the application configuration:
 
 ```ts
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
-import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
+import { imfusionBrandAssets, readableCssModuleNames } from "@imfusion/web-ui/vite";
 
 export default defineConfig({
-  plugins: [react(), readableCssModuleNames({ prefix: "app" })]
+  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" })]
 });
 ```
 
-A compiler left out of the plugin produces different class names and styles that appear to work only in some environments.
+`imfusionBrandAssets` serves the complete favicon set during development and emits it at stable root URLs during builds.
+Register `readableCssModuleNames` in every compiler that processes the app's CSS, including development, Storybook, and
+production. A compiler left out produces different class names and styles that appear to work only in some environments.

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

@@ -5,7 +5,7 @@ description:
   needs library wiring, tooling, git, npm, authentication, structure, data, testing, docs, or agent tooling. Inspect first,
   propose concrete files, and write only what the user approves. Use imf-web-ui-audit for read-only checks."
 argument-hint: "[full|library-setup|tooling|git|npm-project|authentication|project-structure|docs-structure|data|testing|agent-tooling]"
-allowed-tools: Read Glob Grep Write
+allowed-tools: Read Glob Grep Write Skill
 ---
 
 # Set up a consumer project
@@ -15,16 +15,24 @@ working choices.
 
 ## Workflow
 
-1. Resolve the argument. Bare means `full`. A named topic limits the assessment to that topic. If the argument is unknown,
-   list the supported topics and point to `imf-web-ui-audit`.
+1. Resolve the scope. A named topic limits the assessment to that topic. A bare invocation means `full`, unless the request
+   is about one topic, in which case that topic is the scope: answer what was asked and offer the wider sweep rather than
+   running it. If the argument is unknown, list the supported topics and point to `imf-web-ui-audit`.
 2. Enter the host's plan mode before inspecting or proposing changes.
 3. Read the selected convention topics and inspect the repository with `Read`, `Glob`, and `Grep` only.
 4. Put a complete proposal in the host plan, using [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md).
-   For new or updated documentation, invoke `/documentation-writer` before writing and use the `docs-structure` topic for
-   repository-specific boundaries. Name every file to create or change, include its intended content, and cite the repository
-   evidence behind the choice.
-5. Wait for explicit approval. After approval, write only the listed files.
-6. Run `imf-web-ui-audit full` as a follow-up and review its findings before calling setup complete.
+   For new or updated documentation, use the `docs-structure` topic for repository-specific boundaries. Name every file to
+   create or change, include its intended content, and cite the repository evidence behind the choice.
+5. Wait for explicit approval. After approval, write only the listed files. Before calling setup complete, ensure every
+   package imported by those files and every tool named by their scripts is declared in `package.json`.
+6. Offer `imf-web-ui-audit full` as an optional next step for checking the wider project, and run it only if the user says
+   yes. Setup is complete once the approved files are written; the audit reviews ground setup did not touch.
+
+## Audit handoff
+
+When the approved request includes an audit, the next tool call after the final setup write invokes `imf-web-ui-audit`
+through the host's skill tool. Do not read audit files, inspect the project again, or dispatch audit investigators first;
+reproducing the audit workflow does not load the skill.
 
 ## Greenfield `full` setup
 
@@ -41,7 +49,7 @@ The plan describes the exact starter files. It does not copy a generic starter p
 
 ## Installer steps
 
-For `agent-tooling`, list the `npx web-ui-install` commands as steps for the human. Read existing registrations first and do
+For `agent-tooling`, list the `npx web-ui install` commands as steps for the human. Read existing registrations first and do
 not stack a hook on an event the project already covers. Include the Codex trust review when hooks are part of the plan.
 
 ## Safety