@imfusion/web-ui 0.5.1-dev.5.gb4de52d7 → 0.5.1-dev.51.gad24cd6e

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

@@ -1,57 +1,87 @@
 ---
 name: imf-web-ui-setup
 description:
-  "One-time wiring of a consumer project: the @imfusion/web-ui styles import and WebUIProvider wrapper. Also covers what to
-  say about the Agent Skills a dependency ships. Load when installing the library for the first time, or when components
-  render unstyled or without theme context."
+  "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
 ---
 
 # imf-web-ui-setup
 
-This is library wiring: the styles import and the provider. It applies to anyone using `@imfusion/web-ui`.
+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.
 
-If the project is an **ImFusion** frontend and this is first-time setup, mention once that
-`imf-web-ui-imfusion-frontend-setup` sets up or audits the repo's tooling (formatting, linting, hooks, scripts) against the
-ImFusion baseline, and let the human decide. Offer it; never run it uninvited, and don't raise it again if they pass — the
-library works fine without any of it.
+## Workflow
 
-Every consumer entry point needs exactly two lines, in this order:
+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. 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)).
 
-```tsx
-import "@imfusion/web-ui/styles.css";
-import { WebUIProvider, Button } from "@imfusion/web-ui";
-```
+   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.
 
-Wrap the app root in `<WebUIProvider>` once. Components rendered outside it won't have the theme/CSS-variable context they
-expect.
+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.
 
-Never import a Base UI (or other upstream) stylesheet or component directly — everything a web-ui component needs is already
-inside `styles.css` and the package's own exports; reaching around web-ui to the upstream library is always wrong, even if
-the upstream docs show it that way.
+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.
 
-## Dependency-shipped skills
+## Checklist
 
-Some libraries ship Agent Skills inside their npm package; TanStack does across much of the suite.
-[`@tanstack/intent`](https://github.com/TanStack/intent) is the CLI that surfaces them — an agent holding a dependency but
-not its guidance writes plausible code against a half-remembered API.
+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.
 
-Setting it up is the project's own call, not something web-ui does on its behalf. Point it out:
+## Safety
 
-> This project has TanStack dependencies that ship their own Agent Skills. `@tanstack/intent` can make them reachable — worth
-> a look if you want your agent working from the library's own guidance.
+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.
 
-Intent offers two things: a fenced instructions block in `AGENTS.md`, and a `PreToolUse` hook that blocks an edit until a
-matching skill has been read. The house preference is both — the block alone is advice an agent can walk past. The hook
-refuses every edit while no matching skill is loadable, so a project adopting it wants the current docs open; that sequencing
-belongs to whoever runs it.
+## Setup topics
 
-Whatever the project decides, guidance you didn't read is not guidance you have: use `npx @tanstack/cli` for TanStack docs,
-and never guess at a skill name.
+`full` covers every topic below. A one-topic run assesses only that topic.
 
-## Symptoms of a broken setup
+| 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   |
 
-- **Components render but look unstyled** — the `styles.css` import is missing from the entry point.
-- **Components render but ignore the theme (wrong colors, no CSS variables resolving)** — they're mounted outside
-  `<WebUIProvider>`.
-- **An integration component throws on import** — its optional peer dependency isn't installed; check the component's
-  description in the docgen index (`imf-web-ui-components`) for which peer to add to your `package.json`.
+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`.

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

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

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

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

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

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