@imfusion/web-ui 0.5.1-dev.3.g8e0a047a → 0.5.1-dev.30.gf9b152db

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

@@ -0,0 +1,166 @@
+---
+name: imf-web-ui-update
+description:
+  "Update @imfusion/web-ui in a consumer repository: refresh the package and vendored skills, audit and optionally install
+  lifecycle hooks, verify the base update, then audit and optionally migrate affected or custom consumer components in a
+  separate approved commit."
+argument-hint: "[--dry-run] [optional version or reason]"
+allowed-tools: Bash Read Grep
+---
+
+# imf-web-ui-update
+
+Update a repository that consumes `@imfusion/web-ui`. Preserve existing project choices and user work. The workflow has two
+commits: the dependency/tooling update first, then an optional consumer migration. Never commit without a fresh explicit
+approval.
+
+## Rules
+
+- Work from the frontend package root. In a monorepo, inspect package manifests and `git worktree list` first, then choose
+  the frontend package in the active worktree that uses web-ui. Read repository and component instructions before changing
+  files.
+- Detect the package manager from lockfiles. Use npm for `package-lock.json`, pnpm for `pnpm-lock.yaml`, Yarn for
+  `yarn.lock`, and Bun for `bun.lock*`. If multiple lockfiles exist, stop and ask which is authoritative.
+- A dry run is read-only. Do not install, run the installer, format, stage, commit, reset, or clean. Report what would run.
+- Record the initial `git status --short`. Existing changes are held back, never staged or overwritten.
+- A dirty file that the workflow needs to modify is a conflict. Stop and report it. This includes package files, installed
+  skill directories, the `AGENTS.md` installer fence, hook files, and hook settings.
+- Do not hand-edit installer-owned skills, the `AGENTS.md` fenced block, or installer-owned hook files.
+- Keep the base update and consumer migration in separate commits. Do not begin the migration audit until the base update
+  commit is complete.
+- Treat the installed package version before the update as the comparison baseline. There is no assumed changelog.
+- A migration candidate is a custom consumer implementation whose behavior overlaps with a current web-ui component, or an
+  existing web-ui usage affected by changed types or documented API. Do not infer a replacement from a name alone; inspect
+  the implementation and the current component documentation/types.
+
+## Preflight
+
+1. Select the frontend package in the active worktree and read its instructions, `package.json`, and lockfile.
+2. Check whether `@imfusion/web-ui` is already declared and record its installed/version-marker version.
+3. Record the worktree status and identify files the update would touch.
+4. Inspect `.agents/skills/`, `.claude/skills/`, the `AGENTS.md` fence, `.claude/settings.json`, and `.agents/hooks/`.
+5. Check for another package-manager process. Stop on any conflict or ambiguous target.
+
+## Base update
+
+In a non-dry run, update the dependency with the detected manager:
+
+```sh
+npm install @imfusion/web-ui
+```
+
+Use the equivalent command for another detected manager. Pass an explicit version only when the user supplied one. Do not use
+`--force` or `--legacy-peer-deps` to make installation pass. Stop on install failure.
+
+Then refresh the existing web-ui skill target:
+
+```sh
+npx web-ui-install --skills
+```
+
+Use the detected manager's runner for non-npm projects. Preserve the existing target (`.agents`, `.claude`, or both); do not
+silently choose a new one. Stop on malformed settings or installer conflicts.
+
+## Hook audit
+
+Audit these responsibilities separately: session start, prompt submit, and post-edit verification.
+
+- If current web-ui hooks cover a responsibility, do not reinstall it.
+- If no equivalent hook exists and the installer-owned destination is clean, ask whether to run:
+
+  ```sh
+  npx web-ui-install --hooks
+  ```
+
+  Run it only after the user accepts. Use the detected runner otherwise.
+
+- If another hook covers a responsibility, do not stack a duplicate. Report the overlap and ask whether to leave hooks alone
+  or adapt the existing hook in a separate approved change.
+- Invalid settings or dirty installer-owned hook files are conflicts. Stop and ask for resolution.
+
+A declined hook offer is valid. Report `hooks: skipped by user` and continue.
+
+## Verification
+
+After each mutating command, compare `git status --short` with the preflight snapshot.
+
+Classify paths as:
+
+- **Update-owned:** package files and installer-owned files changed by this workflow.
+- **Held back:** pre-existing user changes, excluded from the commit.
+- **Conflict:** an overlapping pre-existing change, ambiguous target, or unexpected changed path.
+
+On conflict, stop. Never use `git restore`, `git reset`, `git clean`, or broad staging to hide it.
+
+Run the frontend package's documented full verification after the base update. Read its `package.json` scripts and choose
+commands that cover typechecking, linting, tests, and building. Prefer one documented aggregate `verify`/`check` script when
+it covers those responsibilities; otherwise run the documented non-watch scripts for the responsibilities that exist. Do not
+invent script names or run watch/dev scripts. A type or build failure is a base-update conflict to resolve before the base
+commit, not a migration finding to defer.
+
+Verify the dependency/lockfile, current skill markers, the `AGENTS.md` fence, hook coverage, and the final path list. In
+dry-run mode, say that mutation-dependent checks were skipped.
+
+## Base update report and approval
+
+Before the base commit, show this concise report:
+
+```text
+@imfusion/web-ui update report
+Package      : <old> -> <new> / would update
+Skills       : <status>
+Hooks        : <status>
+Verification : <status>
+Update files : <paths>
+Held back    : <paths or none>
+Conflicts    : <paths or none>
+Commit       : <imperative message or not proposed>
+```
+
+Normal mode: ask exactly, **“Approve these update-owned changes and commit them?”** Do not commit without an affirmative
+answer. If denied, leave the changes uncommitted.
+
+Dry-run mode: state **“Dry run complete; no changes or commit were made.”** Do not mutate or ask for commit approval.
+
+## Consumer migration audit
+
+Begin this phase only after the approved base update has been committed. Record the old and new package versions from the
+pre-update and current manifests/lockfile. Use the current package's exported types, generated documentation, and component
+examples as the source of truth. Use the old version's package metadata or repository history when available to identify what
+changed; do not pretend a changelog exists.
+
+Run the same documented full verification again after the base commit. Separate findings into:
+
+- **Compatibility fixes:** existing web-ui imports, props, or usage patterns that no longer typecheck, build, lint, or pass
+  tests.
+- **Changed component usages:** existing components whose current API, behavior, or documented contract changed between the
+  two versions and may need a consumer update, even when the typecheck passes.
+- **Replacement candidates:** custom consumer components, wrappers, or field implementations that overlap with a component
+  now exported by `@imfusion/web-ui`. Inspect their code, styles, and call sites before suggesting a replacement. Include the
+  current custom implementation, the proposed web-ui component, the relevant API/type evidence, and any behavior or styling
+  that still needs to be preserved.
+
+Report these findings separately from the base update. Ask whether to apply the proposed migration. If the user declines,
+leave the consumer code unchanged. If accepted, make only the approved migration changes, run the documented full
+verification again, and show a second report with the migration paths, held-back paths, conflicts, and verification result.
+
+If no findings exist, report that the installed update has no detected compatibility fixes, changed usages, or replacement
+candidates. Do not create an empty migration commit.
+
+## Migration approval
+
+Ask exactly, **“Approve these consumer migration changes and commit them separately?”** Do not commit without an affirmative
+answer. The migration approval is not implied by approval of the base update.
+
+## Commit
+
+For the base update, after approval:
+
+1. Recheck status and exclude held-back paths.
+2. Stage base update-owned paths selectively. Never use `git add .` or `git add -A`.
+3. Run the repository's commit workflow if it has one, including its required verification and documentation audit. Otherwise
+   run documented verification and follow the repository's commit convention.
+4. Commit with a concise imperative message and confirm the commit and final status.
+
+For an approved migration, repeat the same selective staging and documented commit workflow with a separate imperative
+message. Never bypass hooks or amend an unrelated commit after a hook failure.

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

@@ -11,7 +11,7 @@ description:
 Most teams consuming `@imfusion/web-ui` don't have a designer on call. This skill stands in: it encodes the library authors'
 UX experience — the whole experience of a screen, its visual design, and the usability where both meet. Follow it by default;
 deviate when the product has a real reason to. Code-level patterns (tokens, layers, wrappers) live in
-`imf-web-ui-frontend-patterns`; project wiring lives in `imf-web-ui-setup`.
+`imf-web-ui-frontend-conventions`; project wiring lives in `imf-web-ui-library-setup`.
 
 Component names below are real — verify any API against the docgen index (`imf-web-ui-components`) before use. Never invent a
 component this library doesn't ship.
@@ -82,13 +82,13 @@ Every screen ships four states, not one:
 
 Custom UI the library doesn't cover should be indistinguishable from library UI: build it from `--imf-ui-*` tokens and
 compose it with library primitives. The goal lives here; the mechanics (tokens, layers, wrappers) live in
-`imf-web-ui-frontend-patterns`.
+`imf-web-ui-frontend-conventions`.
 
 ## Experimental components
 
 The identity index marks each component `stable` or `experimental`. Experimental ones are fine to use, but expect API
-movement across releases — prefer wrapping them once (see `imf-web-ui-frontend-patterns`) so a breaking change lands in one
-file, not forty call sites.
+movement across releases — prefer wrapping them once (see `imf-web-ui-frontend-conventions`) so a breaking change lands in
+one file, not forty call sites.
 
 ## Deep dives
 

package/src/llms/skills/imf-web-ui-ux/references/forms.md

@@ -8,7 +8,7 @@ non-compliant ones. Read before building any form beyond two fields.
 
 The library ships the controls (`Input`, `Select`, `Checkbox`, `Switch`, `Slider`) but no form or field wrapper, so labels,
 grouping, and where errors appear are composed by you. That's exactly where these rules apply. Composing the markup is not
-the same as owning the state: form state and validation belong to a form library (see `imf-web-ui-frontend-patterns`), and
+the same as owning the state: form state and validation belong to a form library (see `imf-web-ui-frontend-conventions`), and
 these rules govern how its errors get presented.
 
 ## Structure

package/bin/install-skill.js

@@ -1,180 +0,0 @@
-#!/usr/bin/env node
-
-// Installs the consumer skill family (../src/llms/skills/imf-web-ui*/)
-// into the consumer project's agent skill directories. Runs in the
-// CONSUMER's environment, so it may only use this package's real runtime
-// dependencies (@clack/prompts). Never wire this into a postinstall hook:
-// ambient script execution on `npm install` is a live supply-chain attack
-// vector — install stays an explicit, user-run command.
-//
-// The skills cross-reference each other, so they install as one bundle.
-// When both targets are selected, .agents/skills/ holds the real copy and
-// .claude/skills/ symlinks it (this repo's own convention) so the two
-// can't drift apart.
-
-import {
-  cpSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync
-} from "node:fs";
-import { dirname, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import * as p from "@clack/prompts";
-
-const SKILL_PREFIX = "imf-web-ui";
-const VERSION_MARKER = ".imf-web-ui-skill-version.json";
-
-const here = dirname(fileURLToPath(import.meta.url));
-// Source is relative to THIS SCRIPT's location (inside node_modules), not
-// the consumer's cwd — the script is invoked from the consumer's project
-// root, but the skills it copies ship alongside this file in the package.
-const skillsRoot = resolve(here, "..", "src", "llms", "skills");
-const packageJson = JSON.parse(readFileSync(resolve(here, "..", "package.json"), "utf-8"));
-const currentVersion = packageJson.version;
-
-// Destination is relative to the consumer's project root (cwd), since
-// that's where their `.claude/` or `.agents/` directory lives.
-const projectRoot = process.cwd();
-
-const TARGETS = {
-  claude: { label: "Claude Code", root: resolve(projectRoot, ".claude", "skills") },
-  agents: { label: "Vendor-neutral (.agents/)", root: resolve(projectRoot, ".agents", "skills") }
-};
-
-function discoverSkills() {
-  if (!existsSync(skillsRoot)) return [];
-  return readdirSync(skillsRoot, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() && entry.name.startsWith(SKILL_PREFIX))
-    .map(entry => entry.name)
-    .sort();
-}
-
-function displayPath(absPath) {
-  return `./${relative(projectRoot, absPath)}`;
-}
-
-function readInstalledVersion(dir) {
-  const markerPath = resolve(dir, VERSION_MARKER);
-  if (!existsSync(markerPath)) return null;
-  try {
-    return JSON.parse(readFileSync(markerPath, "utf-8")).version ?? null;
-  } catch {
-    return null;
-  }
-}
-
-function writeRealCopy(sourceDir, destDir) {
-  mkdirSync(dirname(destDir), { recursive: true });
-  // force: true makes re-running after a version bump overwrite cleanly.
-  cpSync(sourceDir, destDir, { recursive: true, force: true });
-  writeFileSync(resolve(destDir, VERSION_MARKER), JSON.stringify({ version: currentVersion }, null, 2) + "\n");
-}
-
-function writeSymlink(linkPath, targetPath) {
-  mkdirSync(dirname(linkPath), { recursive: true });
-  // lstat (not existsSync, which follows symlinks) catches a broken/stale
-  // symlink left over from a prior run, not just a real file or directory.
-  if (lstatSync(linkPath, { throwIfNoEntry: false })) {
-    rmSync(linkPath, { recursive: true, force: true });
-  }
-  symlinkSync(relative(dirname(linkPath), targetPath), linkPath);
-}
-
-// --target claude|agents (repeatable) selects targets without the
-// interactive prompt — for CI and scripted installs.
-function parseTargetFlags(argv) {
-  const targets = [];
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] !== "--target") continue;
-    const value = argv[i + 1];
-    if (!value || !(value in TARGETS)) {
-      console.error(`--target expects one of: ${Object.keys(TARGETS).join(", ")}`);
-      process.exit(1);
-    }
-    targets.push(value);
-    i++;
-  }
-  return targets;
-}
-
-async function main() {
-  const skills = discoverSkills();
-  const flagTargets = parseTargetFlags(process.argv.slice(2));
-
-  p.intro(`@imfusion/web-ui — install the ${SKILL_PREFIX} skills (${skills.length})`);
-
-  if (skills.length === 0) {
-    p.log.error(`No skills found at ${skillsRoot}. Reinstall @imfusion/web-ui and try again.`);
-    p.outro("Nothing installed.");
-    process.exitCode = 1;
-    return;
-  }
-
-  const existingVersions = Object.values(TARGETS)
-    .flatMap(({ root }) => skills.map(name => readInstalledVersion(resolve(root, name))))
-    .filter(Boolean);
-  if (existingVersions.length > 0 && existingVersions.every(v => v === currentVersion)) {
-    p.log.info(`Already up to date (v${currentVersion}). Re-running will overwrite with the same content.`);
-  } else if (existingVersions.some(v => v !== currentVersion)) {
-    const from = existingVersions.find(v => v !== currentVersion);
-    p.log.info(`Updating installed skills from v${from} to v${currentVersion}.`);
-  }
-
-  p.log.message(`Skills in this bundle:\n${skills.map(name => `  - ${name}`).join("\n")}`);
-
-  let selected;
-  if (flagTargets.length > 0) {
-    selected = flagTargets;
-    p.log.info(`Targets from --target flags: ${selected.join(", ")}`);
-  } else {
-    selected = await p.multiselect({
-      message: "Install into which skill directory (or directories)?",
-      options: Object.entries(TARGETS).map(([key, { label, root }]) => ({
-        value: key,
-        label,
-        hint: displayPath(root)
-      })),
-      required: true
-    });
-
-    if (p.isCancel(selected)) {
-      p.cancel("Cancelled — nothing installed.");
-      return;
-    }
-  }
-
-  const both = selected.includes("claude") && selected.includes("agents");
-
-  for (const name of skills) {
-    const sourceDir = resolve(skillsRoot, name);
-    if (both) {
-      // .agents/ is the canonical real copy; .claude/ aliases it via symlink.
-      const realDir = resolve(TARGETS.agents.root, name);
-      writeRealCopy(sourceDir, realDir);
-      writeSymlink(resolve(TARGETS.claude.root, name), realDir);
-    } else {
-      for (const key of selected) {
-        writeRealCopy(sourceDir, resolve(TARGETS[key].root, name));
-      }
-    }
-  }
-
-  if (both) {
-    p.log.success(`Vendor-neutral (.agents/) -> ${displayPath(TARGETS.agents.root)}/${SKILL_PREFIX}*`);
-    p.log.success(`Claude Code -> ${displayPath(TARGETS.claude.root)}/${SKILL_PREFIX}* (symlinks -> .agents/)`);
-  } else {
-    for (const key of selected) {
-      p.log.success(`${TARGETS[key].label} -> ${displayPath(TARGETS[key].root)}/${SKILL_PREFIX}*`);
-    }
-  }
-
-  p.outro(`Done — ${skills.length} skills installed.`);
-}
-
-await main();

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

@@ -1,93 +0,0 @@
----
-name: imf-web-ui-frontend-patterns
-description:
-  "Raise the quality of frontend code written around @imfusion/web-ui — including quickly vibe-coded frontends. Library
-  boundary contract (tokens, CSS layers, type derivation), component roles, state placement, effects discipline, code
-  conventions (TypeScript, naming, file organisation, testing), and stack defaults. Load when writing wrapper components,
-  custom UI, styling beyond the defaults, adding new files to a consumer app, or choosing a routing, data-fetching, form, or
-  table library."
----
-
-# imf-web-ui-frontend-patterns
-
-One guard, once: **if the host project already has a convention — a styling system, a state library, a folder shape — the
-project wins.** These defaults fill vacuums. They are not a license to refactor a consumer codebase toward this document.
-
-Everything else below is how to build.
-
-## Stay behind the library
-
-Never import Base UI (or any other upstream this 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.
-
-## Style through the sanctioned seams
-
-All library styles live in the `imf-ui.components` CSS layer, so **any plain selector you write wins** — that's the whole
-override contract:
-
-- Target the stable hooks: `data-imf-ui-component` attributes and your own classes/wrappers.
-- Never target the library's internal class names — they are generated and change without notice.
-- Never `!important` — if you think you need it, you're targeting the wrong thing.
-
-## Build custom UI from tokens
-
-Anything you build that the library doesn't cover — a stat widget, a custom panel — uses `--imf-ui-*` variables for color,
-spacing, radius, and type instead of hardcoded values. That's what makes custom UI look native next to library components,
-and what keeps it correct when the theme changes. A hex code or a magic `px` next to a concept the tokens already name is a
-defect.
-
-## 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.
-
-## React patterns
-
-The full treatment — component roles with an example, state placement, effects discipline, and the react.dev sources to
-consult while building — lives in [references/react-patterns.md](references/react-patterns.md). Read it before writing new
-screens or wrappers. The core in one breath:
-
-- **Three roles.** Dumb components own how things look, layout components own arrangement, smart containers own data and
-  logic. Styling never lives in containers.
-- **State lives where its truth lives.** URL → query cache → context → store → local state; walk the list, stop at the first
-  match.
-- **Effects are a last resort**, and always extracted into purpose-named hooks.
-- **Compose, don't configure.** If a component's prop list reads like a settings page, it wanted to be two or three
-  components.
-
-## Everything else about the code
-
-TypeScript, naming, where files go, and what's worth testing live in
-[references/code-conventions.md](references/code-conventions.md). Read it when you're adding files rather than editing
-existing ones — that's when these choices get made and then inherited by everything after.
-
-The split between the two references: `react-patterns.md` covers **writing React** — component roles, where state lives,
-effects discipline, composition. `code-conventions.md` covers **the code around it** — TypeScript, JS style, naming, file
-layout, testing. Starting a new feature usually wants both.
-
-## Stack defaults
-
-TanStack is the default for the tooling around web-ui, whether the app is greenfield or you're adding one screen to something
-that already exists. The ones you'll reach for most: **Router** (URL state, type-safe search params), **Query** (server
-state), **Form** (form state), and **Table** for data grids, which you pair with web-ui's styled `Table` parts
-(`Table.SortableHeaderCell` carries the sort glue). The suite goes wider than those four — check what exists before adding a
-non-TanStack dependency. This is the stack the state ladder assumes.
-
-`useState` is the right tool for local UI state, and most of it is local: whether a panel is open, which tab is active, a
-draft value being typed, a hover flag. Keep those in the component and don't reach for a library.
-
-The line is what the state is _for_, not how much of it there is. A library owns the layer once you find yourself rebuilding
-what it does: validation timing and cross-field rules (**Form**), caching and refetching (**Query**), URL as the source of
-truth (**Router**), sorting and pagination over rows (**Table**). web-ui ships none of that logic, and that absence is not an
-argument for writing it yourself. Adding the library mid-project is normal and cheap; unpicking a hand-rolled version of it
-later is not.
-
-For best practices and patterns within any of these libraries, go to the library's own guidance rather than working from
-memory: `npx @tanstack/cli` for docs. Where a project has wired up `@tanstack/intent`, use it to reach the Agent Skills its
-TanStack dependencies ship, and read those too.

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

@@ -1,133 +0,0 @@
-# Code conventions
-
-The ImFusion defaults for everyday code around `@imfusion/web-ui` — the parts that aren't React-specific. TypeScript, file
-organisation, naming, and testing. React component structure lives in [react-patterns.md](react-patterns.md); the two are
-read together when starting new code.
-
-These fill vacuums. Where the host project has already decided, the project wins.
-
-## TypeScript
-
-- **`any` is forbidden.** `unknown` at a boundary you genuinely can't type, narrowed before use. An `any` that silences an
-  error moves the failure from compile time to runtime, which is the opposite of the trade you wanted.
-- **Lean on inference for locals; annotate the contract.** Restating a type the compiler already knows inside a function body
-  is a second thing to keep in sync. An **explicit return type on an exported function is worth writing**: it's the promise
-  the module makes, it stops an internal refactor silently widening the public shape, and it makes the error surface at the
-  function rather than at every call site.
-- **No temporal coupling.** Don't initialise to `null` and fill the value in later — model the states instead, so "not loaded
-  yet" and "loaded, empty" aren't the same value.
-- **Avoid `as`.** A type assertion tells the compiler to stop checking exactly where checking is worth most. Fix the type.
-  Assertions at an untyped third-party boundary are the honest exception; keep them at the boundary, not spread through call
-  sites.
-
-**Derive types, don't duplicate them.** One source of truth, everything else follows from it:
-
-```ts
-const sizes = ["sm", "md", "lg"] as const;
-type Size = (typeof sizes)[number];
-
-const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler breaks if `sizes` changes
-```
-
-The same rule crosses the library boundary: prop types come from the components themselves
-(`React.ComponentProps<typeof Button>`), never re-declared by hand.
-
-**Function signatures.** One or two positional arguments read fine. At three or more, take a single object and destructure —
-call sites stop depending on argument order, and adding a parameter stops being a breaking change.
-
-## Expressions over statements
-
-Reach for the array methods before the loop. `map`, `filter`, `find`, `some`, `every`, `flatMap`, `reduce` — each names what
-it's doing, where a `for` loop makes you read the body to find out.
-
-```ts
-// The name is the documentation
-const activeNames = users.filter(u => u.isActive).map(u => u.name);
-
-// vs. a loop you have to read to understand
-const activeNames = [];
-for (const u of users) {
-  if (u.isActive) activeNames.push(u.name);
-}
-```
-
-The deeper reason is mutation: the method chain produces a new value, so nothing else can observe a half-built array. Prefer
-spreads and `structuredClone` over in-place edits, and `toSorted`/`toReversed` over `sort`/`reverse`, which mutate their
-receiver and have surprised everyone at least once.
-
-Two honest exceptions: a genuine early exit (`for` with `break` beats `find` returning a sentinel) and a hot loop over
-thousands of items where the intermediate arrays actually measure. Neither is the common case, so reach for the method first
-and justify the loop.
-
-Keep the chain flat. Three or four steps read well; ten want intermediate named constants, and a `reduce` doing four things
-at once wants to be a loop after all.
-
-## Naming
-
-- Say what it is, not what it is made of. `useUserQuery`, not `useUserHook`. `retryDelay`, not `num`.
-- Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`. A boolean called `status` will end up holding a string.
-- Handlers are `onX` as props, `handleX` as implementations — the prop names the event, the function names the response.
-- Match the vocabulary the product and the API already use. Inventing a synonym for a term the backend already named costs a
-  translation step on every read.
-
-## File and folder organisation
-
-Kebab-case throughout, folders and files.
-
-```
-src/
-  routes/          # TanStack Router file-based routes; routing only
-  api/<topic>/     # <topic>.ts (queries/mutations), query-key.ts, types.ts
-  components/      # grouped by kind of component — layouts/, primitives/, or a domain name
-  http/            # client, error normalisation
-  lib/             # framework-free helpers
-```
-
-`api/` groups by topic: a query lives next to its key factory and its types, so a query key is never spelled out at a call
-site. Routes compose and don't fetch inline. Transport concerns live in `http/` and nowhere else.
-
-`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 has rather than imposing it up front. The kinds worth separating are the
-component roles in [react-patterns.md](react-patterns.md): dumb components, layout components, smart containers.
-
-A component gets a folder once it has more than one file, with an `index.ts` that only re-exports:
-
-```
-components/data-table/
-  data-table.tsx
-  data-table-row.tsx
-  data-table.module.css
-  index.ts
-```
-
-Colocate tests, styles, and types with their subject. A file you have to hunt for in a parallel tree gets edited less
-carefully.
-
-## Styling
-
-**CSS Modules by default**, colocated as `<component>.module.css`. No CSS-in-JS, no utility-class framework. Compose from
-`--imf-ui-*` tokens so custom UI stays consistent with library components and follows the theme; the override contract (CSS
-layers, `data-imf-ui-component`, never the library's generated class names) is in the parent skill.
-
-`imf-web-ui-imfusion-frontend-setup` sets up or audits this structure on an ImFusion project.
-
-## Testing
-
-Test the **decisions**, not the rendering.
-
-- **Pure logic gets unit tests** — pricing, permissions, date math, parsing, reducers. These are cheap, fast, and the place
-  bugs actually hide.
-- **Presentational components generally don't.** A component that maps props onto web-ui primitives has no logic of its own;
-  asserting that it rendered a `<Button>` tests React, not your code.
-- **Behaviour a user performs gets an interaction test** — a form that validates, a flow with steps. Test it through the
-  interface the user has (roles, labels, visible text), not through internals.
-- **Extract the decision out of a hook and test that.** A hook whose interesting part is a plain function is easier to test
-  as a plain function than through a render harness. A hook that only wraps a browser API has no decision to extract.
-
-The measure isn't coverage percentage. It's whether a test failing tells you something you didn't already know.
-
-## Formatting and linting
-
-Don't argue about it in review — the tooling decides, and it runs before the commit lands. A formatter, a linter, and a
-pre-commit hook wired so none of them is optional. On an ImFusion project, `imf-web-ui-imfusion-frontend-setup` carries the
-baseline and the setup steps.