@imfusion/web-ui 0.6.1-dev.27.gfc6e5abb → 0.6.1-dev.3.g5b432448

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

@@ -1,44 +1,50 @@
 # Tooling
 
-Read this topic before adding a dependency or configuring a tool. Use the tool's current documentation rather than memory.
+Dependency and configuration baseline for an ImFusion frontend; check before adding a dependency and before writing its
+config.
 
 ## Topic-to-tool map
 
-| Need                  | Default                                      |
-| --------------------- | -------------------------------------------- |
-| Build                 | Vite                                         |
-| Routing and URL state | TanStack Router                              |
-| Server state          | TanStack Query                               |
-| Forms                 | TanStack Form                                |
-| Data grids            | TanStack Table plus Web UI `Table` parts     |
-| App-wide client state | TanStack Store, after URL/server/local state |
-| Schema validation     | Zod at the boundary                          |
-| Tests                 | Vitest                                       |
-| Format                | Prettier                                     |
-| Lint                  | ESLint flat config                           |
-| Types                 | `tsc --noEmit`                               |
-| Staged files          | lint-staged or nano-staged                   |
-| Dead code             | Knip via `verify:knip`                       |
+- Use the mapped tool for each topic; prefer typed config (`.ts` over `.json`) where the tool supports it.
+
+| Topic                 | Tool                                                                                                  |
+| --------------------- | ----------------------------------------------------------------------------------------------------- |
+| Build                 | [Vite](https://vite.dev)                                                                              |
+| Routing, URL state    | [TanStack Router](https://tanstack.com/router) — file-based, type-safe search params                  |
+| Server state          | [TanStack Query](https://tanstack.com/query) — the pattern around it is [data.md](data.md)            |
+| Forms                 | [TanStack Form](https://tanstack.com/form)                                                            |
+| Data grids            | [TanStack Table](https://tanstack.com/table) + web-ui's styled `Table` parts                          |
+| App-wide client state | [TanStack Store](https://tanstack.com/store) — last resort in the state ladder ([react.md](react.md)) |
+| Schema validation     | [Zod](https://zod.dev) — at the network boundary ([data.md](data.md))                                 |
+| Styling               | CSS Modules ([styling.md](styling.md))                                                                |
+| Test                  | [Vitest](https://vitest.dev)                                                                          |
+| Format                | [Prettier](https://prettier.io)                                                                       |
+| Lint                  | [ESLint](https://eslint.org) flat config                                                              |
+| Types                 | `tsc --noEmit` — own script, own CI step                                                              |
+| Staged files          | [lint-staged](https://github.com/lint-staged/lint-staged) (or nano-staged, drop-in)                   |
+| Dead code             | [Knip](https://knipjs.dev) via `verify:knip` — needs per-repo config                                  |
 
 ## When a library owns a layer
 
-Use the library that already owns the problem. Adopt Form for form rules, Query for caching and refetching, Router for URL
-state, and Table for sorting and pagination instead of rebuilding those layers. Keep an existing project choice when it
-works.
+- Adopt the library once you're rebuilding what it does — validation timing and cross-field rules (Form), caching and
+  refetching (Query), URL as source of truth (Router), sorting/pagination over rows (Table): adding it mid-project is cheap,
+  unpicking a hand-rolled version later is not.
 
 ## Devtools
 
-Add the devtools package for a TanStack library when one exists, mount it only in development, and check for a matching
-devtools package whenever a new TanStack dependency is added.
+- Every TanStack library with a devtools package gets it as a dev dependency, mounted in development only — Router's
+  `@tanstack/react-router-devtools` is a given; Query's goes in when Query does.
+- Check for a `-devtools` sibling on every new TanStack dependency — not every library has one yet.
+- Once several are in, host them in one panel via `@tanstack/devtools`.
 
 ## Docs over memory
 
-Use `npx @tanstack/cli` for TanStack documentation. If TanStack Intent is configured, use it for the Agent Skills the
-TanStack package provides.
+- `npx @tanstack/cli` for TanStack docs — never work from memory.
+- Where `@tanstack/intent` is wired up, use it to reach and read the Agent Skills the TanStack dependencies ship.
 
 ## Prettier
 
-Use a config file. The repo's values are:
+- Config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
 
 ```ts
 import type { Config } from "prettier";
@@ -53,36 +59,58 @@ const config: Config = {
   singleQuote: false,
   proseWrap: "always"
 };
-
-export default config;
 ```
 
-## ESLint and TypeScript
-
-Use flat ESLint config with type-aware rules and the repo's ignore file. The baseline bans `as` and non-null `!` outside
-tests, requires the `#/` alias instead of parent-relative imports, and uses project-service type information.
+- Never omit the config file — no file means defaults, and the values silently differ.
+
+## ESLint
+
+Flat config (`eslint.config.ts`):
+
+- `strictTypeChecked` + `stylisticTypeChecked`, `projectService: true`
+- `as` and `!` banned outside tests (`consistent-type-assertions`)
+- `.gitignore` as the ignore source (`includeIgnoreFile` from `@eslint/compat`)
+- `#/` alias enforced via `no-restricted-imports` banning `../*` — parent-relative paths error, siblings (`./`) stay relative
+  ([project-structure.md](project-structure.md))
+
+## tsconfig
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true, // import type stays import type
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "skipLibCheck": true,
+    "paths": { "#/*": ["./src/*"] }
+  }
+}
+```
 
-Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `#/` paths. Keep
-`import type` for type-only imports.
+- `#/` → `src/` alias rationale: [project-structure.md](project-structure.md).
 
 ## Staged files
 
-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.
+- Runner config (lint-staged or nano-staged) applies eslint `--fix` and prettier `--write` to staged files only.
+- The pre-commit runner also invokes `verify:knip` when staged source or project config can change the reachability graph.
 
 ## CSS class names
 
-Register Web UI's `readableCssModuleNames` plugin in every compiler that processes the app's CSS, including development,
-Storybook, and production:
+- Generated CSS Module class names are readable in the DOM, `{prefix}-{file}-{local}`, never the default hash: a legible DOM
+  is what makes devtools and browser automation usable.
+- The library ships the plugin; pass a short, app-scoped prefix:
 
 ```ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
 import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
 
 export default defineConfig({
-  plugins: [react(), readableCssModuleNames({ prefix: "app" })]
+  plugins: [react(), readableCssModuleNames({ prefix: "acme" })]
 });
 ```
 
-A compiler left out of the plugin produces different class names and styles that appear to work only in some environments.
+- One pattern for dev, Storybook, and production: register the plugin in **every** tool that compiles the CSS — a compiler
+  left out generates different names for the same source, and its styles silently don't apply.

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

@@ -1,49 +1,73 @@
-# TypeScript and code style
+# TypeScript & code style
 
-Prefer pure functions, immutable values, and side effects at the edges.
+Functional by default: pure functions over stateful classes, immutable data over in-place mutation, expressions over
+statements, side effects at the edges (network, DOM, store).
 
 ## Types
 
-- Do not use `any`. Accept `unknown` at an untrusted boundary and narrow it.
-- Infer local values; give exported functions explicit return types.
-- Model states directly instead of filling a nullable value later.
-- Derive types from their source. Use `z.infer` for schemas and `React.ComponentProps` for Web UI components.
-- Avoid `as`. Keep an assertion only at an untyped third-party boundary where it is the honest boundary.
-- Use one or two positional arguments. At three or more, pass a named object.
+- No `any`. `unknown` at a boundary you can't type, narrowed before use.
+- Infer locals; annotate contracts. Exported functions get an explicit return type.
+- No temporal coupling — model the states instead of initialising `null` and filling in later.
+- Avoid `as`. Fix the type. The honest exception: an untyped third-party boundary, kept at the boundary.
+- Derive, don't duplicate:
 
 ```ts
 const sizes = ["sm", "md", "lg"] as const;
 type Size = (typeof sizes)[number];
 
-const labels: Record<Size, string> = {
-  sm: "S",
-  md: "M",
-  lg: "L"
-};
+const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler breaks if `sizes` changes
 ```
 
-## Immutability and expressions
+- Same rule across boundaries: library props via `React.ComponentProps<typeof Button>`
+  ([library-boundary.md](library-boundary.md)), untrusted data via a runtime schema and `z.infer`
+  ([validation.md](validation.md)).
+- Function signatures: 1–2 positional arguments; at 3+, one destructured object.
 
-Use `map`, `filter`, `find`, `some`, and `flatMap` for ordinary collection work. Create new values instead of mutating the
-input. Use `toSorted` and `toReversed` instead of their mutating counterparts.
+## Immutability & expressions
 
-A loop is fine when it has a real early exit or measured hot-path benefit. A long chain or a `reduce` with several jobs wants
-named intermediate values.
+- Array methods before loops — `map`, `filter`, `find`, `some`, `flatMap` name what they do:
 
-## Naming
+```ts
+const activeNames = users.filter(u => u.isActive).map(u => u.name);
+```
 
-Name what a value is, not how it is built. Booleans read as assertions (`isOpen`, `hasAccess`, `canSubmit`). Props use `onX`;
-component implementations use `handleX`.
+- Produce new values: spreads and `structuredClone` over in-place edits, `toSorted`/`toReversed` over `sort`/`reverse` (which
+  mutate their receiver).
+- Allowed exceptions: a genuine early exit (`for` + `break`), a measured hot loop.
+- Keep chains flat: 3–4 steps read well; longer wants named intermediates, and a `reduce` doing four things wants to be a
+  loop.
+
+## Naming
 
-Keep a hook or query result as a namespace and name the local after its domain:
+- Say what it is, not what it's made of: `useUserQuery`, not `useUserHook`; `retryDelay`, not `num`.
+- Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`.
+- Handlers: `onX` as props, `handleX` as implementations.
+- Match the vocabulary the product and the API already use — no synonyms for terms the backend named.
+- Keep the object a hook or query returns as a namespace instead of destructuring it, and drop the `Query`/`Mutation` suffix
+  from the local binding — the binding reads as the domain name, and every field access shows where it came from:
 
 ```tsx
-const search = Route.useSearch();
-const user = useSuspenseQuery(context.api.user.getDetails());
+const search = Route.useSearch(); // not const { page, filter } = ...
+const user = useSuspenseQuery(context.api.user.getDetails()); // not const { data } = ...
+const updateUser = useMutation(context.api.user.update());
 
 search.page;
 user.data.name;
+updateUser.mutate(values);
+updateUser.isPending;
 ```
 
-Destructure a primitive only when a stable value is needed, such as an effect dependency. Match existing product and API
-vocabulary instead of inventing synonyms.
+- Exception: a `useEffect` dependency array needs a stable primitive, since deps compare by identity — destructure the
+  primitive out first rather than listing the object or a deep path into it:
+
+```tsx
+const user = useSuspenseQuery(context.api.auth.getUser());
+const { name } = user.data; // destructure for the dep array
+
+useEffect(
+  function syncDocumentTitle() {
+    document.title = name;
+  },
+  [name]
+);
+```

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

@@ -1,22 +1,20 @@
 # Validation
 
-Validate data when it crosses into frontend-owned code. Use the schema as both the runtime check and the TypeScript source.
+Validate where data crosses from untrusted representation into frontend-owned values; the schema is the single source of
+truth for runtime check and TypeScript type.
 
 ## Boundaries
 
-Validate once at the edge:
-
-- network responses on entry;
-- URL path and search values;
-- persisted browser data when read;
-- user input when it becomes a submitted domain or request value.
-
-After the boundary, use parsed values. A generic on a typed client only tells TypeScript what you hope the response looks
-like; it does not validate it.
+- Validate once, at the edge: network responses on entry; URL path and search params before business logic; persisted browser
+  data on read; user input becoming a submitted domain or request value.
+- Inside the boundary: parsed values only, no repeated defensive shape checks.
+- Outgoing requests built from already parsed domain values are serialized, not re-validated.
+- A typed client's handwritten generic is not validation — it only asserts a type onto an untrusted response.
 
 ## Schema first, type derived
 
-Use a Zod schema and derive the type:
+- Zod schema, type via `z.infer`; never a handwritten type beside its schema.
+- Same rule for request and response shapes the frontend owns or consumes at runtime.
 
 ```ts
 import { z } from "zod";
@@ -29,13 +27,17 @@ export const userSchema = z.object({
 export type User = z.infer<typeof userSchema>;
 ```
 
-Apply the same rule to request and response shapes the frontend owns at runtime.
-
 ## TanStack Router search params
 
-Pass a Zod v4 schema to `validateSearch`. Route search types then come from that schema:
+- `validateSearch` takes a Zod v4 schema directly (TanStack Router v1) — no adapter or parsing wrapper.
+- `Route.useSearch()` infers its type from `validateSearch`.
+- `.catch()`: malformed URL input falls back without interrupting navigation.
+- `.default()`: only for missing values; malformed values still follow the route's validation error path.
 
 ```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { z } from "zod";
+
 const searchSchema = z.object({
   page: z.number().int().positive().catch(1),
   filter: z.string().catch("")
@@ -45,12 +47,16 @@ export const Route = createFileRoute("/users")({
   validateSearch: searchSchema,
   component: Users
 });
-```
 
-Use `.catch()` for malformed values that can safely fall back. Use `.default()` only for missing values.
+function Users() {
+  const search = Route.useSearch(); // inferred: z.infer<typeof searchSchema>
+  return <UserList page={search.page} filter={search.filter} />;
+}
+```
 
 ## Failure handling
 
-- Use `parse` when invalid data is a contract failure that should reach the normal error boundary.
-- Use `safeParse` when failure is expected and the caller can show a validation message.
-- Keep trimming, coercion, transforms, and defaults in the boundary schema.
+- `schema.parse`: invalid data is a contract failure on the normal error path (malformed backend response → route error
+  boundary).
+- `schema.safeParse`: failure is expected and the caller handles the issues (submitted user input).
+- Transforms and coercion live in the boundary schema — never scatter trimming, number conversion, or defaulting downstream.

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

@@ -1,68 +1,87 @@
 ---
 name: imf-web-ui-setup
 description:
-  "Plan and, after explicit approval, bootstrap a consumer project that uses @imfusion/web-ui. Use this whenever a project
-  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."
+  "Plan and, after explicit approval, bootstrap an ImFusion frontend against the conventions baseline: library setup,
+  tooling, git, npm project, authentication, project structure, docs structure, data, testing, or agent tooling. Inspect
+  statically first and write only the approved files. Use imf-web-ui-audit for read-only health checks or topics with no
+  setup action."
 argument-hint: "[full|library-setup|tooling|git|npm-project|authentication|project-structure|docs-structure|data|testing|agent-tooling]"
 allowed-tools: Read Glob Grep Write
 ---
 
-# Set up a consumer project
+# imf-web-ui-setup
 
-Plan the missing pieces of an ImFusion frontend. The existing project wins; this skill fills gaps instead of reshaping
-working choices.
+You are the frontend bootstrap planner. Inspect the repository statically, read the applicable `imf-web-ui-conventions`
+topics, and prepare a complete proposal for every file you would create or change. The project wins where it already has a
+working convention. This skill is plan-first: enter the host's plan mode before presenting the proposal, and do not create a
+report file as a substitute for the host plan.
 
 ## 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`.
-2. Enter the host's plan mode before inspecting or proposing changes.
+1. Resolve the argument, not the prose. Bare means `full`; a topic argument selects one supported setup topic. A prompt that
+   merely _mentions_ one area ("wire up the tooling", "get the project set up") is still a `full` run — the words describe a
+   starting point, not a scope that excludes the rest. For a greenfield `full` run the application boundary (router, route
+   groups, current-user query, AppShell) is part of the deliverable even when the prompt never names it; propose it and let
+   the human remove it, never silently defer it as "out of scope." For an unsupported topic argument, list the available
+   setup topics and point the human to `imf-web-ui-audit` for a read-only report.
+2. Enter the host's plan mode. If it is not already active, use the host plan-mode control before inspecting and planning.
 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.
+4. Build the complete proposal in the host plan from the shared report contract at
+   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md). Include the concrete
+   content of every file the approved setup would create or change, with repository evidence for each decision.
+5. A greenfield `full` setup proposes the whole starter skeleton, not just tooling — tooling without the application boundary
+   is an unfinished setup. Include, as concrete files in the plan:
+   - the TanStack Router **package added to `package.json`** (with its router devtools as a dev dependency), not just
+     imported — code that imports an uninstalled package is an incomplete setup
+     ([project-structure.md](../imf-web-ui-conventions/topics/project-structure.md));
+   - pathless `_public/` and `_app/` route groups behind one server-backed current-user boundary
+     ([authentication.md](../imf-web-ui-conventions/topics/authentication.md));
+   - the minimal branded `AppShell` in `_app/` by default — omit the shell only when the human explicitly says the product
+     has no persistent authenticated navigation (ask first), but keep the `_app/` boundary either way;
+   - a per-topic `api/` folder for any data the first screen shows, never an inline fixture in the component
+     ([data.md](../imf-web-ui-conventions/topics/data.md)).
 
-## Greenfield `full` setup
+   The plan documents this starter shape as concrete file content; it does not copy a full external starter template.
+   Existing projects keep their working choices — propose only the gaps.
 
-Include these pieces unless the existing project already has them or the user removes them from the plan:
+6. Keep the plan as the approval gate. After the host approves and exits plan mode, write only the listed files. Complete any
+   immediately requested bootstrap work covered by that approved plan, then invoke `imf-web-ui-audit full` as a verification
+   step and review the findings it reports back before declaring the setup complete. The audit stays out of plan mode here —
+   the human has just left it to let this work happen.
 
-- `@tanstack/react-router` and its router devtools in `package.json`;
-- pathless `_public/` and `_app/` route groups;
-- one server-backed current-user query at the route boundary;
-- a minimal `AppShell` in `_app/`, unless the user says the product has no persistent authenticated navigation;
-- an API topic folder for data shown by the first screen;
-- the root provider and library wiring.
+Installer and hook runs stay with the human: an `agent-tooling` proposal lists the `npx web-ui-install` commands as human
+steps, applies the judgment from the topic (read existing registrations first, never stack a hook on a covered event), and
+includes the topic's Codex trust follow-up whenever hooks are part of the plan.
 
-The plan describes the exact starter files. It does not copy a generic starter project.
+## Checklist
 
-## Installer steps
-
-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.
+The post-implementation audit uses the shared
+[convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md) to verify the complete baseline, not
+only the setup topic selected at the start.
 
 ## Safety
 
-During inspection use only `Read`, `Glob`, and `Grep`. Do not run shells, Git, Node, npm, npx, installers, builds, tests, or
-local config. Report anything that needs runtime state as unverified. After approval, `Write` is limited to the approved file
-list; put commands in the plan for the human to run.
+Use only static inspection: `Read`, `Glob`, and `Grep`. Do not use a shell or invoke Node, npm, npx, package scripts, hooks,
+config imports, linters, tests, builds, Git commands, project binaries, installers, or package managers. Read config as text
+and report runtime or machine-local state that cannot be established statically as unverified. After approval, `Write` is
+limited to the files listed in the approved report; anything needing execution goes in the plan for the human.
+
+## Setup topics
 
-## Topics
+`full` covers every topic below. A one-topic run assesses only that topic.
 
-| Topic               | Covers                                                                   |
-| ------------------- | ------------------------------------------------------------------------ |
-| `library-setup`     | Stylesheet, `WebUIProvider`, and package wiring.                         |
-| `tooling`           | Dependencies, devtools, formatter, linter, TypeScript, and verification. |
-| `git`               | Hooks, verification scopes, and staleness checks.                        |
-| `npm-project`       | Manifest, scripts, pins, npm, and Node.                                  |
-| `authentication`    | Current-user query, route groups, login, and logout.                     |
-| `project-structure` | Source tree, route placement, naming, and imports.                       |
-| `docs-structure`    | README, AGENTS, docs index, and content boundaries.                      |
-| `data`              | Transport, schemas, query/mutation options, keys, and invalidation.      |
-| `testing`           | Test boundaries and coverage.                                            |
-| `agent-tooling`     | Vendored skills, hooks, registrations, and Codex trust.                  |
+| Topic               | Assess and plan                                                                |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `library-setup`     | styles import, `WebUIProvider`, and library package wiring                     |
+| `tooling`           | dependency selection, devtools, Prettier, ESLint, TypeScript, and verification |
+| `git`               | tracked hooks, verification scopes, and staleness wiring                       |
+| `npm-project`       | package metadata, scripts, pins, npm, and Node configuration                   |
+| `authentication`    | current-user query, public/app guards, login, and logout                       |
+| `project-structure` | source tree, route groups, optional app shell, naming, and placement           |
+| `docs-structure`    | README, AGENTS, docs index, and content boundaries                             |
+| `data`              | transport, schemas, query/mutation options, keys, and invalidation             |
+| `testing`           | test boundaries and verification coverage                                      |
+| `agent-tooling`     | vendored skills, AGENTS fence, lifecycle hooks, registrations, and staleness   |
 
-The other convention topics are read by `imf-web-ui-audit` when a project needs assessment rather than setup.
+Setup has no file-creation action for `react`, `typescript`, `class-names`, `validation`, `components`, `styling`, `assets`,
+`library-boundary`, or `tokens`; select those in `imf-web-ui-audit`.