@imfusion/web-ui 0.5.1-dev.2.gf11bbed1 → 0.5.1-dev.21.g2accd17d

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

@@ -0,0 +1,76 @@
+# Tooling config
+
+The config baselines for the tools in [stack.md](stack.md). Prefer typed config (`.ts` over `.json`) where the tool supports
+it.
+
+## Prettier
+
+Config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
+
+```ts
+import type { Config } from "prettier";
+
+const config: Config = {
+  printWidth: 125,
+  tabWidth: 2,
+  useTabs: false,
+  trailingComma: "none",
+  arrowParens: "avoid",
+  semi: true,
+  singleQuote: false,
+  proseWrap: "always"
+};
+```
+
+No config file means Prettier runs on defaults — the values silently differ.
+
+## ESLint
+
+Flat config (`eslint.config.ts`):
+
+- `strictTypeChecked` + `stylisticTypeChecked`, `projectService: true`
+- `as` and `!` banned outside tests (`consistent-type-assertions`)
+- `.gitignore` as the ignore source (`includeIgnoreFile` from `@eslint/compat`) — ignores aren't maintained twice
+- The `#/` alias enforced via `no-restricted-imports` banning the `../*` pattern — parent-relative paths error, siblings
+  (`./`) stay relative ([project-structure.md](project-structure.md))
+
+## tsconfig
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true, // import type stays import type
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "skipLibCheck": true,
+    "paths": { "#/*": ["./src/*"] }
+  }
+}
+```
+
+The `#/` → `src/` alias and its rationale: [project-structure.md](project-structure.md).
+
+## Staged files
+
+Runner config (lint-staged or nano-staged) applying eslint `--fix` and prettier `--write` to staged files only.
+
+## CSS class names
+
+Generated CSS Module class names are readable in the DOM, `{prefix}-{file}-{local}`, never the default hash. A legible DOM is
+what makes devtools and browser automation usable. The library ships the plugin that produces them; pass your own short,
+app-scoped prefix:
+
+```ts
+import { readableCssModuleNames } from "@imfusion/web-ui/build/vite-css-module-names";
+
+export default defineConfig({
+  plugins: [react(), readableCssModuleNames({ prefix: "acme" })]
+});
+```
+
+One pattern for dev, Storybook, and production. Register the plugin in **every** tool that compiles the CSS — a compiler left
+out generates different names for the same source file, and its styles silently don't apply.

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

@@ -0,0 +1,45 @@
+# TypeScript & code style
+
+Functional by default: pure functions over stateful classes, immutable data over in-place mutation, expressions over
+statements, side effects at the edges (network, DOM, store).
+
+## Types
+
+- No `any`. `unknown` at a boundary you can't type, narrowed before use.
+- Infer locals; annotate contracts. Exported functions get an explicit return type.
+- No temporal coupling — model the states instead of initialising `null` and filling in later.
+- Avoid `as`. Fix the type. The honest exception: an untyped third-party boundary, kept at the boundary.
+- Derive, don't duplicate:
+
+```ts
+const sizes = ["sm", "md", "lg"] as const;
+type Size = (typeof sizes)[number];
+
+const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler breaks if `sizes` changes
+```
+
+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)).
+
+- Function signatures: 1–2 positional arguments; at 3+, one destructured object.
+
+## Immutability & expressions
+
+- Array methods before loops — `map`, `filter`, `find`, `some`, `flatMap` name what they do:
+
+```ts
+const activeNames = users.filter(u => u.isActive).map(u => u.name);
+```
+
+- Produce new values: spreads and `structuredClone` over in-place edits, `toSorted`/`toReversed` over `sort`/`reverse` (which
+  mutate their receiver).
+- Allowed exceptions: a genuine early exit (`for` + `break`), a measured hot loop.
+- Keep chains flat: 3–4 steps read well; longer wants named intermediates, and a `reduce` doing four things wants to be a
+  loop.
+
+## Naming
+
+- Say what it is, not what it's made of: `useUserQuery`, not `useUserHook`; `retryDelay`, not `num`.
+- Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`.
+- Handlers: `onX` as props, `handleX` as implementations.
+- Match the vocabulary the product and the API already use — no synonyms for terms the backend named.

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

@@ -0,0 +1,89 @@
+---
+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)."
+argument-hint: "[new|audit|align|<topic>]"
+---
+
+# 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

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

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+<Keep this file lean — target ~50 lines. 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.>
+
+<One paragraph: what the app is and the stack in one line.>
+
+Scripts, deps, and setup: [`README.md`](./README.md) and [`package.json`](./package.json) are the source of truth. Check the
+`package.json` scripts before running or suggesting a command — don't infer one exists by pattern-matching a sibling.
+
+## Read before you write
+
+<One bullet per doc in docs/, each with when to read it, e.g.:>
+
+- [`docs/<topic>.md`](./docs/<topic>.md) — <what it covers>. Read before <the change it governs>.
+
+[`docs/index.md`](./docs/index.md) registers all of them.
+
+## Working here
+
+<The fenced block below is the only part of this file `npx web-ui-install` touches: its content comes from this template and
+is refreshed on every skills install. Everything else in the file is scaffolded once by the setup skill and then owned by the
+repo.>
+
+<!-- imf-web-ui:begin — managed by `npx web-ui-install`; edits inside the fence are overwritten -->
+
+`.agents/skills/imf-web-ui-*` is vendored from `@imfusion/web-ui` and resynced with `npx web-ui-install`. Don't edit it and
+don't put repo conventions there. Load the matching `imf-web-ui-*` skill before writing code, styles, data fetching, or docs;
+repo docs hold only what is unique to this repo.
+
+<!-- imf-web-ui:end -->
+
+<Repo-specific agent guidance: generated files that are committed, tools to verify APIs against, things never to touch.>

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

@@ -0,0 +1,27 @@
+# <App name>
+
+<One paragraph: what the app is, the stack in one line — e.g. "Vite + React 19 + TanStack Router (file-based, CSR) + TanStack
+Query + @imfusion/web-ui".>
+
+## Install
+
+```bash
+npm install
+npm run git:config   # once per clone: hooks path, pull.rebase, merge.ff
+```
+
+<Registry tokens, required services, or other one-time setup. Delete if none.>
+
+## Usage
+
+```bash
+npm run dev
+```
+
+<Environment specifics: proxies, .env files, ports. Delete if none.>
+
+`npm run` lists every script; `package.json` is the source of truth. `verify:full` is the CI gate.
+
+## Docs
+
+[`docs/index.md`](./docs/index.md) registers them.

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

@@ -0,0 +1,36 @@
+---
+name: imf-web-ui-library-setup
+description:
+  "One-time wiring of a consumer project: the @imfusion/web-ui styles import and WebUIProvider wrapper. Load when installing
+  the library for the first time, or when components render unstyled or without theme context."
+---
+
+# imf-web-ui-library-setup
+
+This is library wiring: the styles import and the provider. It applies to anyone using `@imfusion/web-ui`.
+
+If the project is an **ImFusion** frontend and this is first-time setup, mention once that `imf-web-ui-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.
+
+Every consumer entry point needs exactly two lines, in this order:
+
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { WebUIProvider, Button } from "@imfusion/web-ui";
+```
+
+Wrap the app root in `<WebUIProvider>` once. Components rendered outside it won't have the theme/CSS-variable context they
+expect.
+
+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.
+
+## Symptoms of a broken setup
+
+- **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`.

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

@@ -0,0 +1,119 @@
+---
+name: imf-web-ui-update
+description:
+  "Update @imfusion/web-ui in a consumer repository: refresh the package and vendored skills, audit and optionally install
+  lifecycle hooks, handle conflicts, verify the result, and obtain explicit approval before committing."
+argument-hint: "[--dry-run] [optional version or reason]"
+---
+
+# imf-web-ui-update
+
+Update a repository that consumes `@imfusion/web-ui`. Preserve existing project choices and user work. 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.
+- Detect the package manager from lockfiles. Use npm for `package-lock.json`, pnpm for `pnpm-lock.yaml`, Yarn for
+  `yarn.lock`, and Bun for `bun.lock*`. If multiple lockfiles exist, stop and ask which is authoritative.
+- 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.
+
+## Preflight
+
+1. Select the frontend package in the active worktree and read its instructions, `package.json`, and lockfile.
+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 package-manager process. Stop on any conflict or ambiguous target.
+
+## Update
+
+In a non-dry run, update the dependency with the detected manager:
+
+```sh
+npm install @imfusion/web-ui
+```
+
+Use the equivalent command for another detected manager. 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:
+
+```sh
+npx web-ui-install --skills
+```
+
+Use the detected manager's runner for non-npm projects. Preserve the existing target (`.agents`, `.claude`, or both); do not
+silently choose a new one. Stop on malformed settings or installer conflicts.
+
+## Hook audit
+
+Audit these responsibilities separately: session start, prompt submit, and post-edit verification.
+
+- If current web-ui hooks cover a responsibility, do not reinstall it.
+- If no equivalent hook exists and the installer-owned destination is clean, ask whether to run:
+
+  ```sh
+  npx web-ui-install --hooks
+  ```
+
+  Run it only after the user accepts. Use the detected runner otherwise.
+
+- If another hook covers a responsibility, do not stack a duplicate. Report the overlap and ask whether to leave hooks alone
+  or adapt the existing hook in a separate approved change.
+- Invalid settings or dirty installer-owned hook files are conflicts. Stop and ask for resolution.
+
+A declined hook offer is valid. Report `hooks: skipped by user` and continue.
+
+## Conflict and 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 only scripts documented by the frontend's `package.json`. 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.
+
+## Report and approval
+
+Before any 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.
+
+## Commit
+
+After approval:
+
+1. Recheck status and exclude held-back paths.
+2. Stage 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. 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-frontend-conventions`; project wiring lives in `imf-web-ui-library-setup`.
 
 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-frontend-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-frontend-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,7 +8,7 @@ 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
+the same as owning the state: form state and validation belong to a form library (see `imf-web-ui-frontend-conventions`), and
 these rules govern how its errors get presented.
 
 ## Structure

package/bin/install-skill.js

@@ -1,180 +0,0 @@
-#!/usr/bin/env node
-
-// Installs the consumer skill family (../src/llms/skills/imf-web-ui*/)
-// into the consumer project's agent skill directories. Runs in the
-// CONSUMER's environment, so it may only use this package's real runtime
-// dependencies (@clack/prompts). Never wire this into a postinstall hook:
-// ambient script execution on `npm install` is a live supply-chain attack
-// vector — install stays an explicit, user-run command.
-//
-// The skills cross-reference each other, so they install as one bundle.
-// When both targets are selected, .agents/skills/ holds the real copy and
-// .claude/skills/ symlinks it (this repo's own convention) so the two
-// can't drift apart.
-
-import {
-  cpSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync
-} from "node:fs";
-import { dirname, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import * as p from "@clack/prompts";
-
-const SKILL_PREFIX = "imf-web-ui";
-const VERSION_MARKER = ".imf-web-ui-skill-version.json";
-
-const here = dirname(fileURLToPath(import.meta.url));
-// Source is relative to THIS SCRIPT's location (inside node_modules), not
-// the consumer's cwd — the script is invoked from the consumer's project
-// root, but the skills it copies ship alongside this file in the package.
-const skillsRoot = resolve(here, "..", "src", "llms", "skills");
-const packageJson = JSON.parse(readFileSync(resolve(here, "..", "package.json"), "utf-8"));
-const currentVersion = packageJson.version;
-
-// Destination is relative to the consumer's project root (cwd), since
-// that's where their `.claude/` or `.agents/` directory lives.
-const projectRoot = process.cwd();
-
-const TARGETS = {
-  claude: { label: "Claude Code", root: resolve(projectRoot, ".claude", "skills") },
-  agents: { label: "Vendor-neutral (.agents/)", root: resolve(projectRoot, ".agents", "skills") }
-};
-
-function discoverSkills() {
-  if (!existsSync(skillsRoot)) return [];
-  return readdirSync(skillsRoot, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() && entry.name.startsWith(SKILL_PREFIX))
-    .map(entry => entry.name)
-    .sort();
-}
-
-function displayPath(absPath) {
-  return `./${relative(projectRoot, absPath)}`;
-}
-
-function readInstalledVersion(dir) {
-  const markerPath = resolve(dir, VERSION_MARKER);
-  if (!existsSync(markerPath)) return null;
-  try {
-    return JSON.parse(readFileSync(markerPath, "utf-8")).version ?? null;
-  } catch {
-    return null;
-  }
-}
-
-function writeRealCopy(sourceDir, destDir) {
-  mkdirSync(dirname(destDir), { recursive: true });
-  // force: true makes re-running after a version bump overwrite cleanly.
-  cpSync(sourceDir, destDir, { recursive: true, force: true });
-  writeFileSync(resolve(destDir, VERSION_MARKER), JSON.stringify({ version: currentVersion }, null, 2) + "\n");
-}
-
-function writeSymlink(linkPath, targetPath) {
-  mkdirSync(dirname(linkPath), { recursive: true });
-  // lstat (not existsSync, which follows symlinks) catches a broken/stale
-  // symlink left over from a prior run, not just a real file or directory.
-  if (lstatSync(linkPath, { throwIfNoEntry: false })) {
-    rmSync(linkPath, { recursive: true, force: true });
-  }
-  symlinkSync(relative(dirname(linkPath), targetPath), linkPath);
-}
-
-// --target claude|agents (repeatable) selects targets without the
-// interactive prompt — for CI and scripted installs.
-function parseTargetFlags(argv) {
-  const targets = [];
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] !== "--target") continue;
-    const value = argv[i + 1];
-    if (!value || !(value in TARGETS)) {
-      console.error(`--target expects one of: ${Object.keys(TARGETS).join(", ")}`);
-      process.exit(1);
-    }
-    targets.push(value);
-    i++;
-  }
-  return targets;
-}
-
-async function main() {
-  const skills = discoverSkills();
-  const flagTargets = parseTargetFlags(process.argv.slice(2));
-
-  p.intro(`@imfusion/web-ui — install the ${SKILL_PREFIX} skills (${skills.length})`);
-
-  if (skills.length === 0) {
-    p.log.error(`No skills found at ${skillsRoot}. Reinstall @imfusion/web-ui and try again.`);
-    p.outro("Nothing installed.");
-    process.exitCode = 1;
-    return;
-  }
-
-  const existingVersions = Object.values(TARGETS)
-    .flatMap(({ root }) => skills.map(name => readInstalledVersion(resolve(root, name))))
-    .filter(Boolean);
-  if (existingVersions.length > 0 && existingVersions.every(v => v === currentVersion)) {
-    p.log.info(`Already up to date (v${currentVersion}). Re-running will overwrite with the same content.`);
-  } else if (existingVersions.some(v => v !== currentVersion)) {
-    const from = existingVersions.find(v => v !== currentVersion);
-    p.log.info(`Updating installed skills from v${from} to v${currentVersion}.`);
-  }
-
-  p.log.message(`Skills in this bundle:\n${skills.map(name => `  - ${name}`).join("\n")}`);
-
-  let selected;
-  if (flagTargets.length > 0) {
-    selected = flagTargets;
-    p.log.info(`Targets from --target flags: ${selected.join(", ")}`);
-  } else {
-    selected = await p.multiselect({
-      message: "Install into which skill directory (or directories)?",
-      options: Object.entries(TARGETS).map(([key, { label, root }]) => ({
-        value: key,
-        label,
-        hint: displayPath(root)
-      })),
-      required: true
-    });
-
-    if (p.isCancel(selected)) {
-      p.cancel("Cancelled — nothing installed.");
-      return;
-    }
-  }
-
-  const both = selected.includes("claude") && selected.includes("agents");
-
-  for (const name of skills) {
-    const sourceDir = resolve(skillsRoot, name);
-    if (both) {
-      // .agents/ is the canonical real copy; .claude/ aliases it via symlink.
-      const realDir = resolve(TARGETS.agents.root, name);
-      writeRealCopy(sourceDir, realDir);
-      writeSymlink(resolve(TARGETS.claude.root, name), realDir);
-    } else {
-      for (const key of selected) {
-        writeRealCopy(sourceDir, resolve(TARGETS[key].root, name));
-      }
-    }
-  }
-
-  if (both) {
-    p.log.success(`Vendor-neutral (.agents/) -> ${displayPath(TARGETS.agents.root)}/${SKILL_PREFIX}*`);
-    p.log.success(`Claude Code -> ${displayPath(TARGETS.claude.root)}/${SKILL_PREFIX}* (symlinks -> .agents/)`);
-  } else {
-    for (const key of selected) {
-      p.log.success(`${TARGETS[key].label} -> ${displayPath(TARGETS[key].root)}/${SKILL_PREFIX}*`);
-    }
-  }
-
-  p.outro(`Done — ${skills.length} skills installed.`);
-}
-
-await main();