@imfusion/web-ui 0.6.1-dev.12.ge86ac0a1 → 0.6.1-dev.14.g8fac1dfb

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

@@ -1,82 +1,60 @@
 # Agent tooling
 
-How a consumer repo carries the `@imfusion/web-ui` agent tooling; `npx web-ui-install` does the mechanics, this topic carries
-the judgment.
+`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.
 
 ## The skill bundle
 
-- `npx web-ui-install` installs or refreshes the vendored `imf-web-ui-*` skills, refreshes the
-  `<!-- imf-web-ui:begin/end -->` fence in an existing `AGENTS.md`, and removes skills dropped from the bundle.
-- Target: remembered first-run choice — `.claude/skills/`, vendor-neutral `.agents/skills/`, or both (`.agents/` real copy,
-  `.claude/` symlink); `--reconfigure` re-opens it, `--target claude|agents` selects non-interactively.
-- Staleness: per-skill `.imf-web-ui-skill-version.json`; a marker older than the installed package means re-run the binary —
-  never hand-diff or hand-edit vendored skill contents.
+Run:
+
+```sh
+npx web-ui-install
+```
+
+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.
+
+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
 
-- `npx web-ui-install --hooks` adds three injection hooks and a turn-end gate.
-- Scripts in `.agents/hooks/imf-web-ui/` are installer-owned: refreshed wholesale each run, retired scripts pruned with their
-  registrations.
-- Registrations merge idempotently into `.claude/settings.json` (Claude Code) and `.codex/hooks.json` (Codex), never touching
-  entries the installer didn't write.
-
-- **SessionStart** — once per session: points the agent at the `imf-web-ui` skills router.
-- **SubagentStart** — the same line, byte for byte, for each spawned subagent; subagents don't reliably inherit the parent
-  session's context.
-- **UserPromptSubmit** — one line per prompt naming the companion skills to consult.
-- **Stop** — the verify gate: when the turn edited source files, it blocks the agent from finishing once, with the
-  instruction to run the project's verification and fix what it reports. Re-entry is detected from the payload, so the gate
-  can never loop; a turn that edited nothing passes untouched.
-
-```mermaid
-flowchart LR
-    SS(["SessionStart<br/>once per session"]) --> ss["session-start.sh"]
-    SA(["SubagentStart<br/>per spawned subagent"]) --> sa["subagent-start.sh"]
-    UP(["UserPromptSubmit<br/>every prompt"]) --> up["user-prompt-submit.sh"]
-    ST(["Stop<br/>turn ends after edits"]) --> st["stop.sh"]
-    ss --> router["injects the router pointer:<br/>start at imf-web-ui"]
-    sa --> router
-    up --> hints["injects the per-task hints:<br/>components · conventions · ux"]
-    st --> gate["blocks once:<br/>run verification first"]
-    router --> agent["agent routes to the right<br/>companion skill"]
-    hints --> agent
-    gate --> agent2["agent verifies,<br/>then finishes"]
+Install the optional lifecycle hooks with:
+
+```sh
+npx web-ui-install --hooks
 ```
 
-- Each injection hook echoes one fixed line and exits 0; the router does the task-sorting a shell script can't — why a hint
-  on every prompt isn't noise.
-- `baseline-staleness.sh` ships alongside but is not an agent hook; the repo's pre-commit calls it ([git.md](./git.md),
-  staleness at commit time).
-- Never edit an installed script — the next install overwrites it; adapt in the repo's own hooks.
-- Registration entries are yours: the installer matches by script name and keeps edited commands across re-runs. Monorepo:
-  the Codex commands anchor at `$(git rev-parse --show-toplevel)` — adjust their paths once after installing when the
-  frontend isn't the git toplevel.
-- **Read the registration files before installing**; per event: nothing registered → install as shipped; already covered by
-  the repo (its own session reminder, say) → don't stack a second hook — fold the missing line into the repo's script, or
-  adapt the shipped one and register that; surface it and let the human pick.
+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 shipped events are:
+
+- `SessionStart`: point the agent at the Web UI router once per session.
+- `SubagentStart`: provide the same pointer to spawned agents.
+- `UserPromptSubmit`: name the companion skills relevant to the prompt.
+- `Stop`: ask for project verification after a turn edits source files.
+
+Read existing registrations first. If the project already covers an event, do not stack a second hook; adapt the existing
+registration and keep the missing behavior.
+
+`baseline-staleness.sh` is a pre-commit check, not an agent hook. It compares installed skill markers with the installed
+package version.
 
 ## Codex trust
 
-- Codex runs a project's hooks only when two trust gates hold: the project itself is trusted, and each hook script has been
-  trusted via the `/hooks` review, which keys trust to the script's hash.
-- Until then hooks are skipped, and skipped silently — from outside, a skipped hook and a hook that ran and said nothing look
-  identical.
-- After installing or updating hooks, tell the user to trust the project and review `/hooks` in Codex, and again after any
-  hook script changes.
-- When a hint doesn't show up, check trust before debugging the script.
-- Claude Code has no trust gate for project hooks.
+Codex runs project hooks only after the project is trusted and each script is approved through `/hooks`. Revisit that review
+after a hook script changes. Claude Code has no equivalent project-hook trust gate.
 
 ## Dependency-shipped skills
 
-- npm packages can ship Agent Skills of their own; TanStack does — [tooling.md](./tooling.md) covers TanStack Intent and its
-  allowlist.
+Dependencies can ship their own skills. TanStack is one example; its docs and allowlist determine how it is used.
 
 ## Hook docs
 
-Both hosts move fast; read the current references before adapting or adding a hook — payloads and stdout rules differ per
-host and per event.
+Read the current host documentation before adding or adapting a hook:
 
-- [Claude Code: hooks reference](https://code.claude.com/docs/en/hooks) — event list, JSON input and output, exit codes,
-  `disableAllHooks`
-- [Codex: hooks](https://learn.chatgpt.com/docs/hooks) — events, the `hooks.json` schema, trust, `/hooks`
-- [Codex: config reference](https://learn.chatgpt.com/docs/config-file/config-reference) — `[features]` and `[hooks.state]`
+- [Claude Code hooks](https://code.claude.com/docs/en/hooks)
+- [Codex hooks](https://learn.chatgpt.com/docs/hooks)
+- [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-reference)

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

@@ -2,26 +2,25 @@
 
 ## Importing
 
-- Import everything from `src/assets/` so the bundler fingerprints and bundles it. Never reference an image by public-path
-  string.
+Import files from `src/assets/` so the bundler fingerprints and includes them. Do not reference an asset through a
+public-path string.
 
-## Photographs — WebP
+## Photographs: WebP
 
-```bash
+Convert photographs to WebP before adding them:
+
+```sh
 magick source.png -resize 2000x -quality 80 -define webp:method=6 src/assets/name.webp
 ```
 
-- Quality 80 — visually lossless on photos, routinely an order of magnitude smaller.
-- `method=6` — densest encoding; a one-off cost at conversion time, so take the smaller file.
-- Long edge ≤ 2000px — nothing on the market resolves more in a content image.
-- No `<picture>` fallback — WebP is supported everywhere since 2020.
+Keep the long edge at 2000px or less. WebP is supported by the browser floor.
 
 ## Other formats
 
-- Alpha, or pixels that must stay exact → PNG, optimized with `oxipng` or `pngquant`.
-- Icons, logos, line art → inline SVG component, so it inherits `currentColor` and follows the theme.
+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.
 
 ## Scope
 
-- Rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep — convert
-  opportunistically.
+Apply these rules to assets you add or touch. Existing files do not need a format migration just because they use another
+format.

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

@@ -1,65 +1,50 @@
 # Authentication
 
-One route-protection shape for every frontend; provider, session mechanism, endpoint paths, and login/logout transport stay
-project-owned — no provider is prescribed or named.
+Use one route boundary for authentication. The provider, session mechanism, endpoint paths, and login/logout transport stay
+owned by the application.
 
 ## Starter shape
 
-- Authentication sits at the route-group boundary, before child routes render.
-- `_public/` and `_app/`: pathless TanStack Router groups — guards and layouts without `public`/`app` in the URL.
-- The authenticated group keeps this shape even without an `AppShell`.
-
-```text
-src/
-  api/auth/            # getUser query options, keys.ts, types.ts, index.ts barrel
-  lib/auth/
-    login-url.ts       # pure login navigation helper; not an API topic file
-    login-url.test.ts  # focused helper tests
-  routes/
-    __root.tsx         # global Outlet and error/not-found boundaries; no auth guard
-    _public/route.tsx  # anonymous route group
-    _app/route.tsx     # authenticated route group
-```
+- Keep public routes under a pathless `_public/` group.
+- Keep authenticated routes under a pathless `_app/` group.
+- Guard `_app/` before its children render.
+- Keep the root route neutral: it owns the outlet and global error/not-found boundaries.
+- A greenfield app starts `_app/` with a minimal `AppShell` unless it has no persistent authenticated navigation.
+
+The file layout is in [project-structure.md](project-structure.md).
 
 ## One current-user query
 
-- One identity source of truth: a server-backed current-user query; never copy session credentials or access tokens into
-  React state.
-- The auth topic follows the default [data.md](data.md) shape: `getUser` in `api/auth/queries.ts`, key leading with the
-  `auth` topic, schema in `types.ts`.
-- `lib/auth/login-url.ts`: project-owned navigation helper, not an options factory; tests colocated.
-- Reached as `context.api.auth.getUser()`; returns query options, never a hook or a user value — callers pick
-  `ensureQueryData` or a query hook.
-- Never infer authentication from local storage, a decoded token, a route flag, or permission-gated chrome — stale or
-  forgeable; the server response and its schema define the current user.
+Use one server-backed current-user query as the identity source:
+
+- Put it in `api/auth/queries.ts` and define its key and schema with the [data.md](data.md) pattern.
+- Expose query options as `context.api.auth.getUser()`.
+- Call `ensureQueryData` in a loader or a query hook in a component.
+- Keep credentials and access tokens out of React state.
+- Do not infer authentication from local storage, decoded tokens, route flags, or permission-gated UI.
+
+The server response, parsed at the network boundary, is the source of truth.
 
 ## The two route groups
 
-Both resolve the current-user query in `beforeLoad` when they need the answer; only the meaning of a 401 differs:
+Both groups may resolve the current-user query in `beforeLoad`. They handle a 401 differently:
 
-| Group      | 401 means         | Result                                      |
-| ---------- | ----------------- | ------------------------------------------- |
-| `_app/`    | not logged in     | navigate to the server-owned login endpoint |
-| `_public/` | anonymous visitor | continue with `user: null`                  |
+| Group      | 401 result                                   |
+| ---------- | -------------------------------------------- |
+| `_app/`    | Navigate to the server-owned login endpoint. |
+| `_public/` | Continue as an anonymous user.               |
 
-- The `_app/route.tsx` guard awaits the query before children render, converts only an authentication 401 into login
-  navigation, rethrows router redirects, and lets 5xx, connection failures, and schema mismatches reach the error boundary.
-- A public landing route may redirect an authenticated user into `_app/`.
-- The root route stays neutral: global `Outlet` and error/not-found boundaries, no public/authenticated decision.
+The `_app/` guard should navigate only for the authentication 401. Rethrow redirects, server failures, connection failures,
+and schema errors so the normal error boundary can handle them. A public route may redirect an already-authenticated user
+into `_app/`.
 
 ## Login and logout
 
-- Follow the project's documented transport. Server-owned flow: login is a browser navigation, not a Query fetch; logout is
-  the server's documented state-changing action, not an ad-hoc client request.
-- Preserve a validated same-origin return path when the server supports returning to the interrupted route.
-- Never hard-code an endpoint shape or provider into shared frontend conventions.
-- No intermediate login route when the server owns the flow.
-- A failed API request is an auth failure only when its typed error is specifically a 401.
+Follow the application's documented server flow. Login is a browser navigation when the server owns the session; it is not a
+Query fetch. Logout uses the server's documented state-changing action. Preserve a validated same-origin return path when the
+server supports one. Do not invent an endpoint shape in this shared baseline.
 
 ## App shell
 
-- `AppShell` is authenticated chrome, not the authentication mechanism.
-- Greenfield default: propose a minimal shell — ImFusion logo, route navigation, stable session action area around the
-  `_app/` outlet.
-- An explicit no-persistent-navigation decision may omit the shell; the `_app/` guard stays.
-- An established project keeps its working choice; public pages may use a small branded header.
+`AppShell` is authenticated chrome, not the authentication mechanism. It can hold the logo, navigation, and session action
+around the `_app/` outlet. An established project keeps its working shell or header choice.

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

@@ -1,27 +1,22 @@
 # Class names in components
 
-How a component turns props into a `className` string. What the build does with the result: [tooling.md](tooling.md); what
-goes in the stylesheet: [styling.md](styling.md).
+Use CVA to turn design props into CSS Module classes, then merge the caller's `className`.
 
 ## CVA is the only tool
 
-- `class-variance-authority` maps variant props to CSS Module classes. No `clsx`, no `tailwind-merge`, no local `cn()`
-  helper.
-- `cx` is CVA's own concatenator, re-exported by `@imfusion/web-ui` — import it from the library alongside the components.
-- Base class is CVA's first argument; variant values are CSS Module references, never string literals. A boolean axis uses
-  `null` for its off-state.
-- Defaults live in the props destructuring, not CVA's `defaultVariants`: react-docgen-typescript reads the destructuring, so
-  defaults declared in CVA don't reach the generated docs.
+- Use `class-variance-authority` for variant axes. Do not add `clsx`, `tailwind-merge`, or a local `cn` helper.
+- Import `cx` from `@imfusion/web-ui` when a component only needs concatenation.
+- Pass CSS Module references to CVA, not string class names.
+- Represent a boolean axis with `false: null` and `true: classes.axisOn`.
+- Put defaults in function destructuring. CVA `defaultVariants` does not reach the generated docs.
 
 ```tsx
-interface Props extends HTMLAttributes<HTMLSpanElement> {
-  appearance?: "outline" | "solid";
-  inline?: boolean;
-}
-
 const chip = cva(classes.root, {
   variants: {
-    appearance: { outline: classes.appearanceOutline, solid: classes.appearanceSolid },
+    appearance: {
+      outline: classes.appearanceOutline,
+      solid: classes.appearanceSolid
+    },
     inline: { false: null, true: classes.inline }
   }
 });
@@ -33,18 +28,18 @@ export function Chip({ appearance = "outline", inline = false, className, ...pro
 
 ## Merging `className`
 
-- Every component that accepts `className` merges it; a deliberately closed surface omits the prop entirely rather than
-  accepting and ignoring it.
-- The incoming `className` goes into CVA's `className` slot, which appends it last so a caller's class always wins. With no
-  variants to map, `cx(classes.inline, className)` does the same job.
-- Resolve a function-form `className` before merging — components built on a library that passes render state
-  (`className={state => …}`) receive either shape:
+A component that accepts `className` must merge it. Put the incoming value in CVA's `className` slot so it is appended after
+the component classes. If there is no CVA configuration, use `cx`.
+
+A library render prop may make `className` a function. Resolve it with the render state before merging:
 
 ```tsx
 className={state => cx(classes.root, typeof className === "function" ? className(state) : className)}
 ```
 
+A closed component should omit `className`, not accept and ignore it.
+
 ## Shared CVA modules
 
-- Two components sharing one visual share one CVA module, a `{name}.cva.ts` next to them, so their variant axes can't drift
-  apart.
+When two components share the same visual variant axes, put their CVA call in a `{name}.cva.ts` module next to them. This
+keeps the visual contract in one place.

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

@@ -1,26 +1,25 @@
 # Components
 
-How a component lives on disk and how dumb it stays. Roles, state, effects: [react.md](react.md); styling:
+Keep consumer components small and easy to replace. React roles are described in [react.md](react.md); CSS ownership is in
 [styling.md](styling.md).
 
 ## As dumb as possible
 
-- Props-fed, never self-fetching: no query hook, no store access, no route awareness — render what's given, report events
-  upward.
-- Presentational logic (formatting a label, deriving a display state) is fine; owning data is not.
-- Local UI state (`isOpen`, a draft value) is allowed; anything whose truth lives elsewhere is not ([react.md](react.md)).
+- Feed components data and callbacks through props.
+- Keep fetching, routing, and business logic in the page or feature layer.
+- Local UI state such as an open state or draft value is fine.
+- Formatting and display-only decisions are fine; owning server state is not.
 
 ```tsx
-// components/user-card/user-card.tsx
-interface Props {
+interface UserCardProps {
   name: string;
   onEdit: () => void;
 }
 
-export function UserCard({ name, onEdit }: Props) {
+export function UserCard({ name, onEdit }: UserCardProps) {
   return (
     <Card.Root>
-      <Typo>{name}</Typo>
+      <Typo.P>{name}</Typo.P>
       <Button onClick={onEdit}>Edit</Button>
     </Card.Root>
   );
@@ -29,73 +28,25 @@ export function UserCard({ name, onEdit }: Props) {
 
 ## Grouping
 
-- `components/` groups by kind (the component roles in [react.md](react.md)) — a layout component under `layouts/`, not
-  beside a domain widget.
-- Flat is fine while there are few; let grouping follow what the project has, don't impose it up front.
+Group by component role, such as layout or domain UI, according to the project structure. Do not create a hierarchy before
+the project needs one.
 
 ## One file or a folder
 
-- More than one file (sub-components, styles, tests) → a folder with an `index.ts` that only re-exports; single-file
-  components stay single files, directly in their group.
-- Imports read `#/components/data-table`, so the inside can be restructured without touching call sites.
+A one-file component can stay in its group. A component with parts, styles, or tests gets a folder with an `index.ts` barrel.
+Call sites import the folder path:
 
-The full anatomy of a folder component:
-
-```
+```text
 components/data-table/
-  data-table.tsx           # the component: props type + export, CVA variants when it has axes
-  data-table-row.tsx       # sub-component, private unless index.ts re-exports it
-  data-table.module.css    # co-located stylesheet (styling.md)
-  data-table.test.tsx      # only when the component carries decisions worth testing (testing.md)
-  index.ts                 # re-exports only
+  data-table.tsx
+  data-table.module.css
+  data-table.test.tsx
+  index.ts
 ```
 
-Most components need only a subset — start with the `.tsx`, add files as they earn their place.
-
-```tsx
-// data-table.tsx — CVA even with one variant axis, so future axes slot in (class-names.md)
-import { cva, type VariantProps } from "class-variance-authority";
-import classes from "./data-table.module.css";
-
-const dataTable = cva(classes.root, {
-  variants: { density: { comfortable: classes.densityComfortable, compact: classes.densityCompact } }
-});
-
-// Intersection, not `interface extends` — VariantProps is an object type. Defaults live in the destructuring.
-type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof dataTable> & { rows: TableRow[] };
-
-export function DataTable({ className, density = "comfortable", rows, ...props }: Props) {
-  return (
-    <div {...props} className={dataTable({ density, className })}>
-      {/* … */}
-    </div>
-  );
-}
-```
-
-```css
-/* data-table.module.css — native nesting + library tokens, no preprocessor, no @layer (styling.md) */
-.root {
-  border-radius: var(--imf-ui-border-radius-2);
-  font-size: var(--imf-ui-font-size-1);
-
-  &:focus-visible {
-    /* states nest under the root */
-  }
-}
-
-.densityCompact {
-  /* one class per CVA variant value */
-}
-```
-
-```ts
-// index.ts — re-exports only; callers import #/components/data-table
-export { DataTable } from "./data-table";
-```
+The barrel only re-exports the public pieces.
 
 ## Colocation
 
-- Stylesheet: `<component>.module.css` next to the component; only dumb components have one — a container that wants CSS is
-  asking for a layout component instead ([react.md](react.md)).
-- Tests and local types sit next to their subject: a file hunted for in a parallel tree gets edited less carefully.
+Keep a component's stylesheet, tests, and local types beside the component. A container that needs styling usually wants to
+be a layout or dumb component instead.