@imfusion/web-ui 0.5.1-dev.24.g5b275132 → 0.5.1-dev.28.g1156ad00

package/README.md

@@ -60,7 +60,7 @@ the directories it already installed into, without asking again — `--reconfigu
 | `/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-frontend-conventions` | The frontend conventions baseline, including the sanctioned styling seams.     |
-| `/imf-web-ui-frontend-setup`       | Set up or audit an ImFusion frontend's tooling against the house baseline.     |
+| `/imf-web-ui-frontend-setup`       | Assess an ImFusion frontend and write a reviewable setup report.               |
 | `/imf-web-ui-agent-setup`          | Install or update the vendored skills, agent hooks, and TanStack Intent.       |
 | `/imf-web-ui-update`               | Update the library, skills, and optional hooks, then verify before committing. |
 

package/bin/install.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it } from "vitest";
 import { spawnSync } from "node:child_process";
 import {
+  chmodSync,
   existsSync,
   lstatSync,
   mkdirSync,
@@ -150,6 +151,36 @@ describe("web-ui-install", () => {
     expect(staleness.stdout).toBe("");
   });
 
+  it("runs post-edit checks from the package containing the edited file", () => {
+    runInstall(consumer, "--hooks");
+
+    const frontend = join(consumer, "frontend");
+    const source = join(frontend, "src", "example.ts");
+    const binDir = join(frontend, "node_modules", ".bin");
+    const log = join(consumer, "hook.log");
+    mkdirSync(join(frontend, "src"), { recursive: true });
+    mkdirSync(binDir, { recursive: true });
+    writeFileSync(join(frontend, "package.json"), JSON.stringify({ private: true }));
+    writeFileSync(source, "export const example = true;\n");
+
+    for (const tool of ["eslint", "prettier"]) {
+      const path = join(binDir, tool);
+      writeFileSync(path, '#!/usr/bin/env sh\nprintf "%s|%s\\n" "$PWD" "$*" >> "$HOOK_LOG"\n');
+      chmodSync(path, 0o755);
+    }
+
+    const result = spawnSync("sh", [join(consumer, ".agents", "hooks", "imf-web-ui", "post-tool-use.sh")], {
+      cwd: consumer,
+      env: { ...process.env, HOOK_LOG: log },
+      input: JSON.stringify({ tool_input: { file_path: source } }),
+      encoding: "utf-8"
+    });
+
+    expect(result.status).toBe(0);
+    const calls = readFileSync(log, "utf-8").trim().split("\n");
+    expect(calls).toEqual([`${frontend}|--cache ${source}`, `${frontend}|--check ${source}`]);
+  });
+
   it("warns from the staleness script when skill markers lag the package", () => {
     runInstall(consumer, "--skills", "--hooks", "--target", "agents");
     const pkgDir = join(consumer, "node_modules", "@imfusion", "web-ui");

package/package.json

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

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

@@ -8,6 +8,7 @@ description:
   consumer app, when skills are stale, when hooks should be installed or adapted, or when asked to set up TanStack Intent or
   dependency-shipped Agent Skills. Not for project tooling (imf-web-ui-frontend-setup) or library wiring
   (imf-web-ui-library-setup)."
+allowed-tools: Read Bash
 ---
 
 # imf-web-ui-agent-setup
@@ -29,8 +30,9 @@ Three agent lifecycle hooks ship as templates in [`templates/hooks/`](templates/
 - **SessionStart** — once per session: the conventions baseline is vendored, load it before writing.
 - **UserPromptSubmit** — a one-line conventions reminder per prompt. Per-prompt, not per-tool-call: a PreToolUse reminder
   would re-inject the same text on every edit.
-- **PostToolUse** (advisory) — file-scope checks on the touched file after every Edit/Write, failures fed straight back.
-  Never exits non-zero.
+- **PostToolUse** (advisory) — file-scope checks on the touched file after every Edit/Write, failures fed straight back. It
+  resolves the nearest package from the edited file, so a frontend nested below a monorepo root uses its own config and
+  dependencies. Never exits non-zero.
 - **`baseline-staleness.sh`** — not registered as an agent hook; the repo's pre-commit calls it
   ([`git.md`](../imf-web-ui-frontend-conventions/references/git.md), Staleness at commit time).
 
@@ -42,6 +44,14 @@ Three agent lifecycle hooks ship as templates in [`templates/hooks/`](templates/
   it. Use the template as a starting point instead: fold the missing behaviour into the repo's existing script, or adapt the
   template and register that. Surface the situation and let the human pick.
 
+## Assessment reference
+
+A static frontend setup assessment checks that the complete consumer skill bundle and version markers match the declared
+`@imfusion/web-ui` version; the AGENTS fence exists; SessionStart, UserPromptSubmit, and PostToolUse behavior is installed
+and registered or consciously adapted; PostToolUse resolves the edited file's package and its tools in monorepos; and the
+tracked pre-commit path calls `baseline-staleness.sh`. Read files and settings as text—do not run installers, hooks, or local
+config queries during assessment.
+
 ## Dependency-shipped skills
 
 Some libraries ship Agent Skills inside their npm package; TanStack does across much of the suite.
@@ -67,5 +77,6 @@ guidance you have: use `npx @tanstack/cli` for TanStack docs, and never guess at
 
 ## Not this skill
 
-- Project tooling, docs structure, the audit checklist → `imf-web-ui-frontend-setup` (which delegates agent tooling here)
+- Project tooling, docs structure, the audit checklist → `imf-web-ui-frontend-setup` (which reads this skill as its
+  agent-tooling assessment contract)
 - Library wiring (styles import, provider) → `imf-web-ui-library-setup`

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/post-tool-use.sh

@@ -1,21 +1,33 @@
 #!/usr/bin/env sh
 # PostToolUse (Edit|Write): advisory file-scope checks on the touched file. Never exits
-# non-zero, so a mid-flight refactor can't trap the agent. Resolve the repo from the edited
-# file, not cwd, which is not guaranteed for hooks.
-FILE=$(jq -r '.tool_input.file_path // empty' 2>/dev/null)
+# non-zero, so a mid-flight refactor can't trap the agent. Resolve the package from the
+# edited file, not cwd or the Git root, which may belong to a parent monorepo.
+FILE=$(sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
 [ -f "$FILE" ] || exit 0
 
-ROOT=$(cd "$(dirname "$FILE")" && git rev-parse --show-toplevel 2>/dev/null) || exit 0
-cd "$ROOT" || exit 0
+FILE_DIR=$(cd "$(dirname "$FILE")" && pwd) || exit 0
+FILE="$FILE_DIR/$(basename "$FILE")"
+PACKAGE_ROOT=$FILE_DIR
+while [ "$PACKAGE_ROOT" != "/" ] && [ ! -f "$PACKAGE_ROOT/package.json" ]; do
+  PACKAGE_ROOT=$(dirname "$PACKAGE_ROOT")
+done
+[ -f "$PACKAGE_ROOT/package.json" ] || exit 0
+
+TOOL_ROOT=$PACKAGE_ROOT
+while [ "$TOOL_ROOT" != "/" ] && [ ! -d "$TOOL_ROOT/node_modules/.bin" ]; do
+  TOOL_ROOT=$(dirname "$TOOL_ROOT")
+done
+[ -d "$TOOL_ROOT/node_modules/.bin" ] || exit 0
+cd "$PACKAGE_ROOT" || exit 0
 
 case "$FILE" in
   *.ts | *.tsx | *.js | *.jsx)
-    [ -x ./node_modules/.bin/eslint ] && ./node_modules/.bin/eslint --cache "$FILE" 2>&1
+    [ -x "$TOOL_ROOT/node_modules/.bin/eslint" ] && "$TOOL_ROOT/node_modules/.bin/eslint" --cache "$FILE" 2>&1
     ;;
 esac
 case "$FILE" in
   *.ts | *.tsx | *.js | *.jsx | *.css | *.json | *.md)
-    [ -x ./node_modules/.bin/prettier ] && ./node_modules/.bin/prettier --check "$FILE" 2>&1
+    [ -x "$TOOL_ROOT/node_modules/.bin/prettier" ] && "$TOOL_ROOT/node_modules/.bin/prettier" --check "$FILE" 2>&1
     ;;
 esac
 exit 0

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

@@ -4,6 +4,7 @@ description:
   "Look up @imfusion/web-ui component APIs without reading their source: the two-hop lookup (identity index -> prop data),
   compound components, and integrations. Load when you need the props, sub-components, or defaults of a specific component —
   not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-library-setup)."
+allowed-tools: Bash
 ---
 
 # imf-web-ui-components

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

@@ -2,10 +2,10 @@
 name: imf-web-ui-frontend-conventions
 description:
   "The ImFusion frontend conventions baseline — in-house conventions, valid in every ImFusion frontend and usable by anyone
-  who likes them. A router over topic references: library boundary, React, components, TypeScript, styling, data layer,
-  project structure, testing, stack, npm project, tooling config, git, assets, docs structure. Load when writing wrapper
-  components, custom UI, styling beyond the defaults, adding new files to a consumer app, writing repo docs, touching tool
-  config, or choosing any dependency."
+  who likes them. A router over topic references: library boundary, React, components, TypeScript, styling, validation, data
+  layer, project structure, testing, stack, npm project, tooling config, git, assets, docs structure. Load when writing
+  wrapper components, custom UI, styling beyond the defaults, validating external data, adding new files to a consumer app,
+  writing repo docs, touching tool config, or choosing any dependency."
 ---
 
 # imf-web-ui-frontend-conventions
@@ -32,7 +32,8 @@ Each topic lives in one reference. Read the one whose moment you're in; starting
 | [typescript.md](references/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
 | [styling.md](references/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
 | [class-names.md](references/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
-| [data.md](references/data.md)                           | `api/`+`http/` shape, Zod boundary, query/mutation patterns         | adding an API topic, a fetch, or a mutation             |
+| [validation.md](references/validation.md)               | runtime schemas, boundary parsing, schema-derived types             | accepting data the frontend does not own                |
+| [data.md](references/data.md)                           | `api/`+`http/` shape, query/mutation patterns and invalidation      | adding an API topic, a fetch, or a mutation             |
 | [project-structure.md](references/project-structure.md) | the `src/` tree, file naming, imports                               | adding files rather than editing existing ones          |
 | [testing.md](references/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
 | [stack.md](references/stack.md)                         | the topic→tool map, when a library owns a layer                     | choosing or adding any dependency                       |

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

@@ -20,12 +20,9 @@ transport-level (base client, error normalisation) lives in `http/` and nowhere
 
 ## The network boundary validates
 
-The network is the only place untyped data enters the app, so it is the only place that validates. Everything a backend sends
-is parsed against a Zod schema at that edge; the TypeScript types are derived from the schemas with `z.infer`, never
-hand-written. A hand-written response type is a claim about the backend that nothing checks.
-
-The transport in `http/` is deliberately untyped: it returns `unknown` and leaves the parse to the caller, so no call site
-can accidentally skip validation.
+The transport in `http/` returns `unknown`; the topic schema parses the response in its query or mutation function before the
+value enters the app. The schema is also the source of its TypeScript type. The full boundary, type-derivation, and failure
+handling rules are [validation.md](validation.md).
 
 ## Errors are values
 
@@ -65,7 +62,8 @@ export const userQueryOptions = () =>
 ```
 
 Components consume query options directly with `useSuspenseQuery` (prefetched routes) or `useQuery` (secondary data). No
-wrapper hooks — the options function is the reusable unit.
+wrapper hooks — the options function is the reusable unit. Call sites may spread the returned options only to add
+component-specific callbacks or overrides.
 
 Mutations follow the same shape with `mutationOptions`, the dirtied topic first in the `mutationKey`:
 
@@ -132,8 +130,8 @@ function MePage() {
 }
 ```
 
-Mutations use `useMutation` with the options factory. Manual invalidation is unnecessary when automatic invalidation is on
-(see below):
+Mutations use `useMutation` with the options factory instead of reconstructing `mutationKey` and `mutationFn` at the call
+site. Manual invalidation is unnecessary when automatic invalidation is on (see below):
 
 ```tsx
 // components/user-settings.tsx
@@ -189,8 +187,15 @@ targeted optimistic update), and invalidate precisely through the key factory in
 [query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) and
 [automatic invalidation after mutations](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations).
 
+## Audit
+
+Inspect the complete path, not the presence of TanStack Query alone: transport returns `unknown`; topic schemas parse
+responses; API types derive from those schemas; keys come from topic factories; API topics expose reusable `queryOptions` and
+`mutationOptions`; hooks consume those options with only local overrides; mutation keys match the configured invalidation
+strategy.
+
 ## Testing the data layer
 
 Stub the network at the `fetch` boundary and let the real query client run: the test then exercises the same parse and error
-path production does. Schemas, clients, and query options are where behaviour worth asserting lives — the general philosophy
-is [testing.md](testing.md).
+path production does. Schemas, clients, and query options are where behaviour worth asserting lives — schema cases are in
+[validation.md](validation.md), and the general philosophy is [testing.md](testing.md).

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

@@ -58,7 +58,8 @@ components. When state must be shared between siblings, lift it to the nearest c
 State comes in kinds, and each kind has an owner. Work down this list and stop at the first match:
 
 1. **URL state** — shareable via the address bar (filters, sort, pagination, active tab) → TanStack Router search params.
-   Back button and copied links are UX features you get for free.
+   Back button and copied links are UX features you get for free. URL values cross an external boundary; parse them according
+   to [validation.md](validation.md).
 2. **Server state** — comes from an API → TanStack Query's cache ([data.md](data.md)). Never copy server data into `useState`
    — that's how stale-UI bugs are born.
 3. **Subtree state** — scoped to a subtree, resets on leave (wizard progress) → React context.
@@ -66,7 +67,8 @@ State comes in kinds, and each kind has an owner. Work down this list and stop a
 5. **Local state** — one component's own (input value, open/closed) → `useState`.
 
 `useState` is the right tool for local UI state, and most state 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.
+draft value being typed, a hover flag. Keep those in the component and don't reach for a library. When a form turns drafts
+into a submitted domain value, validate that boundary as described in [validation.md](validation.md).
 
 Most frontends need far less of tier 4 than they think; tiers 1–2 usually dissolve the "we need a store" instinct. For
 structuring the state itself, [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) is the

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

@@ -11,6 +11,8 @@ Test the **decisions**, not the rendering.
 - **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 data layer has its own recipe — stub `fetch`, run the real query client — in [data.md](data.md).
+The data layer has its own recipe — stub `fetch`, run the real query client — in [data.md](data.md). A schema whose
+constraints or transforms encode product behavior gets focused accepted, rejected, and transformed cases; see
+[validation.md](validation.md).
 
 The measure isn't coverage percentage. It's whether a test failing tells you something you didn't already know.

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

@@ -19,7 +19,8 @@ const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler
 ```
 
 Across boundaries the same rule: library props via `React.ComponentProps<typeof Button>`
-([library-boundary.md](library-boundary.md)), API types via `z.infer` ([data.md](data.md)).
+([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.
 

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

@@ -0,0 +1,88 @@
+# Validation
+
+Runtime validation belongs where data crosses from an untrusted representation into frontend-owned values. The schema is the
+single source of truth for both the runtime check and the TypeScript type.
+
+## Boundaries
+
+Validate once, at the edge:
+
+- network responses when they enter the frontend;
+- URL path and search parameters before business logic uses them;
+- persisted browser data when it is read;
+- user input when it becomes a submitted domain value or request value.
+
+Code inside that boundary receives parsed values and does not repeat defensive shape checks. An outgoing request built from
+an already parsed domain value is serialized, not validated a second time. A typed client returning a handwritten generic is
+not validation: it only asserts that an untrusted response has the requested type.
+
+## Schema first, type derived
+
+Use Zod for the runtime schema and derive the type with `z.infer`:
+
+```ts
+import { z } from "zod";
+
+export const userSchema = z.object({
+  id: z.string(),
+  email: z.email()
+});
+
+export type User = z.infer<typeof userSchema>;
+```
+
+Do not maintain a handwritten `User` beside `userSchema`. Request and response shapes follow the same rule when the frontend
+owns or consumes their runtime representation.
+
+## TanStack Router search params
+
+TanStack Router v1 accepts a Zod v4 schema directly in `validateSearch`; no adapter or parsing wrapper is needed:
+
+```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("")
+});
+
+type UserSearch = z.infer<typeof searchSchema>;
+
+export const Route = createFileRoute("/users")({
+  validateSearch: searchSchema,
+  component: Users
+});
+
+function Users() {
+  const search = Route.useSearch();
+  return <UserList page={search.page} filter={search.filter} />;
+}
+```
+
+`Route.useSearch()` returns `UserSearch` by inference from `validateSearch`. Use `.catch()` when malformed URL input should
+fall back without interrupting navigation. Use `.default()` only when a missing value gets a default while malformed values
+should still follow the route's validation error path.
+
+## Failure handling
+
+Use `schema.parse(value)` when invalid data is a contract failure that should follow the normal error path, such as a
+malformed backend response reaching a route error boundary. Use `schema.safeParse(value)` when failure is expected and the
+caller must render or otherwise handle validation issues, such as submitted user input.
+
+Transforms and coercion belong in the boundary schema when they are part of entering the domain. Do not scatter trimming,
+number conversion, or defaulting through downstream components.
+
+## Audit
+
+A boundary is aligned when:
+
+- the untrusted source is represented as `unknown` until parsed;
+- a Zod schema parses it at the point of entry;
+- exported TypeScript types use `z.infer<typeof schema>`;
+- downstream code consumes the parsed value without duplicate checks or assertions;
+- parse failures reach the intended error or user-feedback path;
+- behavior-changing schemas have focused tests for accepted, rejected, and transformed values.
+
+TanStack Query placement is in [data.md](data.md), general type derivation in [typescript.md](typescript.md), URL and form
+ownership in [react.md](react.md), and test selection in [testing.md](testing.md).

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

@@ -1,89 +1,66 @@
 ---
 name: imf-web-ui-frontend-setup
 description:
-  "Set up or audit an ImFusion frontend's project tooling: the stack, package.json scripts, formatting, linting, typecheck,
-  staged-file and pre-commit hooks, verification scopes, dependency pinning, tsconfig, docs structure, agent wiring. House
-  conventions, not industry standards. Load when starting a new ImFusion frontend, when asked what an existing one's setup is
-  missing, when asked to align a repo with the baseline, or when asked to check or set up one named topic from it (e.g. CSS
-  class names, Prettier). Not for a bare 'add this config file' request — that's just the edit. Not for wiring the library
-  itself (imf-web-ui-library-setup)."
+  "Assess an ImFusion frontend against the project baseline and write a reviewable FRONTEND_SETUP_REPORT.md: new-project
+  setup needs, existing-project gaps, alignment migrations, or one named topic (for example data, lifecycle hooks, CSS class
+  names, or Prettier). Covers stack, package scripts, tooling, verification, project shape, data, docs, and agent wiring.
+  House conventions, not industry standards. This skill inspects and plans; approved implementation is a separate task. Not
+  for wiring the library itself (imf-web-ui-library-setup)."
 argument-hint: "[new|audit|align|<topic>]"
+allowed-tools: Read Glob Grep
 ---
 
 # imf-web-ui-frontend-setup
 
-First-time setup and audit against the ImFusion frontend baseline. The conventions live in `imf-web-ui-frontend-conventions`
-— this skill is the process that checks a repo against them and wires up what they assume. In-house conventions, not industry
-standards: report findings as "missing against the ImFusion baseline", never "against best practice". Built for ImFusion
-frontends; anyone else who likes the baseline can run it too.
-
-Four modes, same checklist:
-
-- **New project** — work down the checklist and set each piece up.
-- **Audit** — read the repo (don't ask what it has), report present / missing / broken, change nothing until the human picks.
-  An established repo is where a forgotten piece hides. **The project wins:** where the repo already decided, that stands —
-  report what's _absent_; a working convention you'd have chosen differently is not a finding.
-- **Align** — when the user asks to _align_ the repo with the baseline ("align"/"alignment" is the flag), the project-wins
-  guard lifts: deviations become migration findings, proposed as a plan, still nothing changed until approved.
-- **One topic** — any other argument names a topic instead of a mode (`class names`, `prettier`, `tooling`). Resolve it to
-  the checklist rows it touches and run the audit process against those only, reading their references as usual. Say which
-  rows you resolved it to before reporting, and if nothing matches, say so and list the rows rather than guessing or sweeping
-  everything. Same output as an audit: findings, nothing changed until the human picks.
-
-**Producer scope.** The web-ui repo itself produces this baseline; it is not a consumer frontend. Consumer-only rows — the
-AGENTS.md fence, vendored-skill staleness, the app stack and app `src/` tree — don't apply there. Audit it against the shared
-rows only: scripts, tooling, git, docs.
-
-## The checklist
-
-Each row is a reference in `../imf-web-ui-frontend-conventions/references/` — read it, then check the repo against it. A
-topic argument narrows this table to the rows it names; every other mode works down all of it.
-
-| Reference              | Set up / audit                                                                              |
-| ---------------------- | ------------------------------------------------------------------------------------------- |
-| `stack.md`             | the dependencies match the topic→tool map; devtools siblings present                        |
-| `npm-project.md`       | script names table, `type`/`private`, exact pins, `.npmrc`, Node pinning                    |
-| `tooling.md`           | Prettier values, ESLint flat config, tsconfig, staged-file runner, readable CSS class names |
-| `git.md`               | `git:config` run and hooks directory present, verify scopes, staleness hooks                |
-| `project-structure.md` | the `src/` tree, file naming, `#/` alias wiring                                             |
-| `components.md`        | component folders and colocation                                                            |
-| `styling.md`           | CSS Modules, tokens, no CSS-in-JS or utility framework                                      |
-| `docs-structure.md`    | docs shape and content rules (see Docs below)                                               |
-| — agent tooling        | delegated to `imf-web-ui-agent-setup` (see Agent tooling below)                             |
-
-## Docs
-
-`README.md`, `AGENTS.md`, and `docs/` with a `docs/index.md` that registers every doc. Scaffold from
-[`templates/README.md`](templates/README.md) and [`templates/AGENTS.md`](templates/AGENTS.md); missing structure is a
-finding.
-
-Keep `AGENTS.md` lean. The decision test for every line: would the agent make a costly mistake without it? If it would just
-need to read a file first, cut it — dev commands, path aliases, and tool config are discoverable from the files themselves.
-
-`AGENTS.md` contains one installer-owned section: the `<!-- imf-web-ui:begin -->` … `<!-- imf-web-ui:end -->` fence.
-`npx web-ui-install` refreshes what's inside on every skills install; everything outside the fence is the repo's own. A
-missing fence in an existing `AGENTS.md` is a finding — without it the baseline note can't be kept current.
-
-Judge existing docs only against `docs-structure.md`: repo-unique content stays, restated baseline becomes a pointer,
-deviations get named as deviations. Don't rewrite a repo's docs uninvited — report, and let the human pick.
-
-## Agent tooling
-
-The agent side — vendored skills and their freshness, the lifecycle hooks, the settings registrations — is
-`imf-web-ui-agent-setup`. Delegate to it: in a new project after the docs step, in an audit as one checklist row (skills
-present and current, hooks wired or consciously adapted). Findings it produces report here like any other.
-
-## Optional
-
-Recommend when the shape calls for it; absence is not a finding.
-
-- **knip** — once several people delete things independently.
-- **`eslint-plugin-jsx-a11y`** — anything user-facing.
-
-Out of scope, project-specific: CI, env and secrets, error tracking, deploy, dependency updates.
-
-## Not this skill
-
-- Library wiring (styles import, provider) → `imf-web-ui-library-setup`
-- The conventions themselves → `imf-web-ui-frontend-conventions` and its references — this skill checks the structure exists,
-  that skill owns what goes inside it
+You are the frontend setup auditor. Investigate the repository statically, record every supported conclusion in
+`FRONTEND_SETUP_REPORT.md`, then stop for human review. You must follow the applicable `imf-web-ui-frontend-conventions`
+references, cite repository evidence, distinguish defects from working deviations, and never present the baseline as
+universal best practice.
+
+## Workflow
+
+1. Resolve the requested mode and scope.
+2. Read every applicable convention reference below. For agent tooling, also read the vendored
+   `imf-web-ui-agent-setup/SKILL.md` and its templates.
+3. Inspect the repository and write or refresh `FRONTEND_SETUP_REPORT.md` from
+   [`templates/FRONTEND_SETUP_REPORT.md`](templates/FRONTEND_SETUP_REPORT.md). The template is the report contract. Preserve
+   everything under `## Reviewer notes` verbatim.
+4. Return the report path and a short verdict. Change nothing else; implementation is a separate, approved task.
+
+## 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.
+
+Only `FRONTEND_SETUP_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.
+
+## Modes
+
+- **New** — record what exists and what setup work is needed.
+- **Audit** — report broken and missing pieces. A working project convention wins; differences are deviations, not defects.
+- **Align** — use the same evidence, but make deviations explicit migration proposals.
+- **One topic** — resolve any other argument to matching rows below and assess only those. If none match, list the available
+  rows instead of guessing or widening scope.
+
+## References
+
+| Reference                         | Assess                                                                    |
+| --------------------------------- | ------------------------------------------------------------------------- |
+| `stack.md`                        | dependencies, dead-code detection, and matching devtools                  |
+| `npm-project.md`                  | package metadata, scripts, pins, npm and Node config                      |
+| `tooling.md`                      | Prettier, ESLint, TypeScript, staged files, CSS class names               |
+| `git.md`                          | tracked hooks, verification scopes, staleness wiring                      |
+| `project-structure.md`            | source tree, naming, imports                                              |
+| `components.md`                   | component folders and colocation                                          |
+| `styling.md`                      | CSS Modules, tokens, prohibited styling systems                           |
+| `validation.md`                   | runtime schemas, boundary parsing, derived types                          |
+| `data.md`                         | transport, query/mutation options, keys, invalidation                     |
+| `docs-structure.md`               | README, AGENTS, docs index and content boundaries                         |
+| `imf-web-ui-agent-setup/SKILL.md` | installed skills, AGENTS fence, lifecycle hooks, registrations, staleness |
+
+Knip is required for dead-code detection. `eslint-plugin-jsx-a11y` remains a recommendation when the project is user-facing;
+its absence is not a finding. CI, env and secrets, error tracking, deploy, dependency updates, and library wiring are out of
+scope.

package/src/llms/skills/imf-web-ui-frontend-setup/templates/FRONTEND_SETUP_REPORT.md

@@ -0,0 +1,45 @@
+# Frontend Setup Report
+
+Mode: `<new|audit|align|topic>` Scope: `<all applicable references or resolved topic references>`
+
+<!--
+This template is the report contract. Keep every H2 below once and in this order.
+Use `None.` for an empty section.
+
+Broken, Missing, Deviations, and Unverified entries use:
+- **[high|medium|low] reference-or-agent-tooling — Short title**
+  - Evidence: `path:line`
+  - Impact: concrete consequence
+  - Next action: smallest selectable follow-up
+
+Present entries name the reference and evidence path. Deviations are selectable follow-up work, not defects; in align mode,
+their next actions are migration proposals. Optional tools are not missing findings.
+-->
+
+## Verdict
+
+<One short assessment of the current frontend setup.>
+
+## Broken
+
+None.
+
+## Missing
+
+None.
+
+## Deviations
+
+None.
+
+## Present
+
+None.
+
+## Unverified
+
+None.
+
+## Reviewer notes
+
+<!-- Human-owned. Preserve everything under this heading verbatim when refreshing the report. -->

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

@@ -5,6 +5,7 @@ description:
   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