@imfusion/web-ui 0.5.1-dev.40.gfb5bc73e → 0.5.1-dev.44.g02fbbc52

package/README.md

@@ -69,7 +69,7 @@ skill.
 | `/imf-web-ui-components`  | Component reference — what exists and how it's meant to be used.               |
 | `/imf-web-ui-ux`          | UX guidance for building interfaces with the library.                          |
 | `/imf-web-ui-conventions` | The frontend conventions baseline, including the sanctioned styling seams.     |
-| `/imf-web-ui-audit`       | Read-only health check for a consumer project, with a reviewable audit report. |
+| `/imf-web-ui-audit`       | Read-only health check for a consumer project, ending in a plan you approve.   |
 | `/imf-web-ui-update`      | Update the library, skills, and optional hooks, then verify before committing. |
 
 Start at `/imf-web-ui` — it routes to the rest. Storybook's **User Guide → AI Agents** page covers the whole family.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.5.1-dev.40.gfb5bc73e",
+  "version": "0.5.1-dev.44.g02fbbc52",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "license": "UNLICENSED",

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

@@ -4,49 +4,76 @@ description:
   "Read-only health check for an ImFusion frontend against the conventions baseline. Audit the full project or any topic,
   including library-setup, tooling, git, npm-project, authentication, project-structure, docs-structure, data, testing,
   React, TypeScript, class names, validation, components, styling, assets, library-boundary, and tokens. Reports broken
-  pieces, missing pieces, working deviations, present evidence, and unverified state in AUDIT_REPORT.md."
+  pieces, missing pieces, working deviations, present evidence, and unverified state, then turns them into an actionable
+  plan."
 argument-hint: "[full|<topic>]"
 allowed-tools: Read Glob Grep
 ---
 
 # imf-web-ui-audit
 
-You are the frontend health-check auditor. Investigate the repository statically, record every supported conclusion in
-`AUDIT_REPORT.md`, and return the report path and a short verdict. Follow the applicable `imf-web-ui-conventions` topics,
-cite repository evidence, distinguish defects from working deviations, and never present the baseline as universal best
-practice.
+You are the frontend health-check auditor, and you run as an orchestrator: one investigator per topic gathers the evidence,
+you merge their findings and turn them into an actionable plan. Follow the applicable `imf-web-ui-conventions` topics, cite
+repository evidence, distinguish defects from working deviations, and never present the baseline as universal best practice.
+
+An audit belongs in plan mode: it ends in work to approve, not in files to write.
 
 ## Workflow
 
 1. Resolve the argument. Bare means `full`; a topic selects one row below. If no topic matches, list every available topic
    instead of guessing or widening the scope.
-2. Read every applicable convention topic and inspect the repository with `Read`, `Glob`, and `Grep` only.
-3. Work through the shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md), checking
-   every row for a full audit and the requested row plus dependencies for a scoped audit.
-4. Check the complete installed skill bundle, version markers, AGENTS fence, lifecycle hooks, registrations, and staleness
-   wiring when `agent-tooling` is in scope. Compare the declared version in `package.json`, the installed
-   `node_modules/@imfusion/web-ui/package.json`, and every `.imf-web-ui-skill-version.json` marker. Report drift and point at
-   `imf-web-ui-update`. The registry is unreachable from this audit, so a line saying that a newer version may exist is
-   unverified.
-5. Write or refresh `AUDIT_REPORT.md` from the shared report contract at
-   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md), changing the mode label
-   to `audit`. The template is the report contract. Preserve everything under `## Reviewer notes` verbatim.
+2. Enter the host's plan mode, unless one of the exceptions after step 5 applies. If plan mode is not already active, use the
+   host plan-mode control before dispatching anything.
+3. Dispatch one investigator per in-scope topic, using the host's subagent mechanism, as concurrently as the host allows.
+   Investigators are cheap and narrow: each one gets a single topic and reports back. A host with no subagent mechanism is
+   not a blocker — work the topics inline in this session, in the same order, to the same contract.
+4. Merge what comes back. Findings you did not gather yourself are the report; do not re-inspect files an investigator
+   covered. Reconcile conflicts by reading the cited evidence, and drop any finding whose citation does not hold.
+5. Deliver the merged report and the plan in the host plan, from the shared report contract at
+   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md), with the mode label
+   `audit`. The plan's ordered steps are the `Next action` lines of the findings, grouped by topic and cheapest-first;
+   `Present` findings produce no steps.
+
+Some runs take the report somewhere other than a plan. When the human asks for the durable file, or the host has no plan
+mode, write the same content to `AUDIT_REPORT.md` and preserve everything under `## Reviewer notes` verbatim. When another
+skill invokes the audit as its verification step, report the findings to that caller and stay out of plan mode — the caller
+owns the flow, and the human has usually just left plan mode to let its work happen.
+
+## Dispatching an investigator
+
+Each investigator prompt carries, in full:
+
+- the topic name and the path of its convention topic file;
+- the topic's block from the shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md), and
+  the instruction to check every box in it;
+- the safety constraint below, verbatim — an investigator that reaches for a shell breaks the audit's only guarantee;
+- the report contract's entry format, so findings arrive mergeable: severity, reference, short title, `path:line` evidence,
+  impact, next action;
+- the instruction to report findings back as its result and write no files.
+
+An investigator reports on its topic alone. Anything it notices outside that topic goes back as a note for the orchestrator
+to route, not as a finding it rules on.
 
 ## Checklist
 
-Use the shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md) as the working checklist.
-The report is not complete until the applicable rows have been inspected and their evidence is reflected in the report. The
+The shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md) is the working checklist: a
+full audit covers every block, a scoped audit covers the requested block plus its dependencies. The audit is not complete
+until every in-scope box has been checked by the investigator that owns it and its evidence appears in the report. The
 checklist itself is not edited during an audit.
 
 ## Safety
 
 Use only static inspection: Read, Glob, Grep, and equivalent non-executing search tools. Do not use a shell or invoke Node,
 npm, npx, package scripts, hooks, config imports, linters, tests, builds, Git commands, or project binaries. Read config as
-text and report runtime or machine-local state that cannot be established statically as unverified.
+text and report runtime or machine-local state that cannot be established statically as unverified. This binds every
+investigator too — a dispatched agent inherits the audit's constraint, not the host's default freedom, so the prompt that
+dispatches it repeats this paragraph verbatim.
 
-Only `AUDIT_REPORT.md` may be written. Write is intentionally not pre-approved in `allowed-tools`; the report follows the
-host's ordinary write approval. Host-managed hooks may run after that write; the skill neither invokes nor suppresses them,
-but it does report broken or unexpected hook behavior found during static inspection.
+An audit writes at most one file: `AUDIT_REPORT.md`, in the two cases named in the workflow. Investigators write nothing.
+Neither Write nor the host's dispatch tool is pre-approved in `allowed-tools` — `allowed-tools` names what an audit needs on
+every run, and both of these follow the host's ordinary approval when a run needs them. Host-managed hooks may run after that
+write; the skill neither invokes nor suppresses them, but it does report broken or unexpected hook behavior found during
+static inspection.
 
 ## Topics
 
@@ -83,5 +110,10 @@ three injection hooks, the stop gate, plus `baseline-staleness.sh` — are drift
 `baseline-staleness.sh`. Read files and settings as text—do not run installers, hooks, or local config queries during
 assessment.
 
+Version drift is part of this topic: compare the declared version in `package.json`, the installed
+`node_modules/@imfusion/web-ui/package.json`, and every `.imf-web-ui-skill-version.json` marker, then report the drift and
+point at `imf-web-ui-update`. The registry is unreachable from a static audit, so a line saying that a newer version may
+exist is unverified.
+
 Use the shared report template as the report contract. It defines the headings, ordering, empty-section marker, evidence
 format, and reviewer-note preservation rules; do not duplicate that contract here.

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

@@ -11,7 +11,7 @@ project-owned — no provider is prescribed or named.
 
 ```text
 src/
-  api/auth/            # getCurrentUser query options, query-key.ts, types.ts, index.ts barrel
+  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
@@ -25,10 +25,10 @@ src/
 
 - 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: `getCurrentUser` in `api/auth/auth.ts`, key leading with the
+- 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.getCurrentUser()`; returns query options, never a hook or a user value — callers pick
+- 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.

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

@@ -7,9 +7,11 @@ the boundary principles — validate at the edge, errors as values — not this
 
 - One folder per API topic: options factories, key factory, Zod schemas together, so a query key is never spelled out at a
   call site.
-- Default topic shape `<topic>.ts` + `query-key.ts` + `types.ts`; the reference project's GraphQL transport expands to
-  `keys.ts`, `queries.ts`/`queryFns.ts`, `mutations.ts`/`mutationFns.ts`, `index.ts` — GraphQL-specific, not a transport
-  requirement.
+- Name a file for what it holds, never for the topic it sits in — the folder already says that: `keys.ts`, not `<topic>.ts`
+  or `query-key.ts` (it holds mutation keys too).
+- A file appears only when the topic needs it: a topic with only queries has no `mutations.ts`, and vice versa.
+- A GraphQL (or similarly document-based) transport may split `queries.ts`/`mutations.ts` further into
+  `queryFns.ts`/`mutationFns.ts`; that's an elaboration of the same options-vs-mutations split, not its origin.
 - Transport code (base client, error normalisation): `http/` and nowhere else.
 - Topic helpers: `lib/`, framework-free, tested beside themselves (`build-query-string.ts` + its test) — never inside the
   topic folder.
@@ -19,8 +21,13 @@ src/
   api/
     topics.ts        # one topic registry, reused by keys and namespaces
     index.ts         # topic barrels composed as api.<topic>
-    user/            # expanded topic (used in the examples): index.ts barrel, keys.ts, queries.ts, mutations.ts
-    <topic>/         # default shape: <topic>.ts, query-key.ts, types.ts
+    <topic>/
+      index.ts       # barrel: named re-exports of what other modules call
+      keys.ts        # createApiKeys — query and mutation keys
+      queries.ts     # query options factories — present when the topic has queries
+      mutations.ts   # mutation options factories — present when the topic has mutations
+      types.ts       # Zod schemas + z.infer types
+      types.test.ts  # schema cases, when the schema encodes product behaviour
   http/              # transport: client, error normalisation — the only transport-aware place
   lib/               # framework-free helpers shared by API topics and other callers
 ```
@@ -94,6 +101,8 @@ export type API = typeof api;
 - No topic prefix, no `Options` suffix: `context.api.<topic>.<fn>()` carries both.
 - Queries `get*` (`getAll`, `getById`, `getBySlug`, `getDetails`, `getActive`, `getFiltered`); mutations bare verbs
   (`update`, `login`, `addItem`, `deleteAddress`, `setShippingMethod`).
+- Same suffix-free naming applies to the local binding a query or mutation resolves to —
+  [typescript.md](typescript.md#naming).
 
 ```ts
 // api/user/queries.ts — returns options; keys come from the factory
@@ -166,13 +175,13 @@ export const Route = createFileRoute("/user")({
 
 function UserPage() {
   const context = Route.useRouteContext();
-  const { data: user } = useSuspenseQuery(context.api.user.getDetails());
+  const user = useSuspenseQuery(context.api.user.getDetails());
   const updateUser = useMutation(
     context.api.user.update({
       onSuccess: () => context.queryClient.invalidateQueries({ queryKey: context.api.orders.keys.topic })
     })
   );
-  return <input defaultValue={user.name} onBlur={e => updateUser.mutate({ name: e.target.value })} />;
+  return <input defaultValue={user.data.name} onBlur={e => updateUser.mutate({ name: e.target.value })} />;
 }
 ```
 

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

@@ -44,9 +44,9 @@ function UserCard({ name, role, onEdit }: { name: string; role: string; onEdit:
 ```tsx
 // Smart — knows where data comes from, renders the dumb component
 function UserCardContainer({ userId }: { userId: string }) {
-  const { data } = useUserQuery(userId);
+  const user = useUserQuery(userId);
   const openEditor = useEditorNavigation(userId);
-  return <UserCard name={data.name} role={data.role} onEdit={openEditor} />;
+  return <UserCard name={user.data.name} role={user.data.role} onEdit={openEditor} />;
 }
 ```
 
@@ -95,6 +95,8 @@ useEffect(
 );
 ```
 
+- A dependency sourced from a hook or query return: destructure the primitive first — [typescript.md](typescript.md#naming).
+
 ## Reading list
 
 Consult while building; each is the authority for its topic:

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

@@ -43,3 +43,31 @@ const activeNames = users.filter(u => u.isActive).map(u => u.name);
 - 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(); // 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;
+```
+
+- 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-setup/SKILL.md

@@ -18,20 +18,36 @@ report file as a substitute for the host plan.
 
 ## Workflow
 
-1. Resolve the argument. Bare means `full`; a topic selects one supported setup topic. For an unsupported topic, list the
-   available setup topics and point the human to `imf-web-ui-audit` for a read-only report.
+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. 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. For a greenfield project, propose the minimal branded `AppShell` in the authenticated route group by default. If the human
-   explicitly says the product has no persistent authenticated navigation, ask whether to omit the shell before finalizing
-   the proposal; keep the `_app/` boundary either way. Existing projects keep their working shell choice. This ticket
-   documents the starter shape but does not copy a full starter template.
+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)).
+
+   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.
+
 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` and review its
-   `AUDIT_REPORT.md` before declaring the setup complete.
+   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.
 
 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

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

@@ -135,8 +135,8 @@ If no findings exist, report that the installed update has no detected compatibi
 candidates. Do not create an empty migration commit.
 
 Whatever the migration outcome, close the phase by asking whether to run `imf-web-ui-audit full`: an update can shift the
-baseline (new components, hooks, conventions), and the audit report shows where the project now stands against it. Run it
-only on an explicit yes.
+baseline (new components, hooks, conventions), and the audit shows where the project now stands against it. Run it only on an
+explicit yes.
 
 ## Migration approval