@imfusion/web-ui 0.5.1-dev.18.g81350f83 → 0.5.1-dev.2.g0a349a2a

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

@@ -0,0 +1,201 @@
+---
+name: imf-web-ui-imfusion-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, folder structure. House conventions,
+  not industry standards. Load when starting a new ImFusion frontend, or when asked what an existing one's setup is missing.
+  Not for adding one config file on request — that's just the edit. Not for wiring the library itself (imf-web-ui-setup)."
+---
+
+# imf-web-ui-imfusion-frontend-setup
+
+ImFusion house conventions, **not** industry standards. Report as "missing against the ImFusion baseline", never "against
+best practice". Only apply to an ImFusion frontend.
+
+Two modes, same list:
+
+- **New project** — work down the list and set each piece up.
+- **Existing project** — 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.
+
+## The stack
+
+| Concern      | Tool                                                      | Notes                                                                               |
+| ------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Format       | [Prettier](https://prettier.io)                           | Values below are shared across repos                                                |
+| Lint         | [ESLint](https://eslint.org) flat config                  | `--cache --max-warnings=0`                                                          |
+| Types        | `tsc --noEmit`                                            | Own script, own CI step                                                             |
+| Staged files | [lint-staged](https://github.com/lint-staged/lint-staged) | [nano-staged](https://github.com/usmanyunusov/nano-staged) is a drop-in alternative |
+| Routing      | [TanStack Router](https://tanstack.com/router)            | File-based, `src/routes/`                                                           |
+| Server state | [TanStack Query](https://tanstack.com/query)              | Query keys colocated per API topic                                                  |
+| Client state | [TanStack Store](https://tanstack.com/store)              | Only for state that isn't URL- or server-owned                                      |
+| Styling      | CSS Modules                                               | Colocated `<component>.module.css`                                                  |
+| Dead code    | [knip](https://knipjs.dev)                                | Needs per-repo config                                                               |
+| Build        | [Vite](https://vite.dev)                                  |                                                                                     |
+| Test         | [Vitest](https://vitest.dev)                              |                                                                                     |
+
+Either staged-file runner is fine; lint-staged is the larger project and the safer default when one misbehaves.
+
+### Devtools come with the library
+
+Every TanStack library that ships a devtools package gets it as a dev dependency alongside the library itself, mounted in
+development only. Router is a given in any ImFusion frontend, so `@tanstack/react-router-devtools` is a given too; Query's
+goes in when Query does, and so on. Look for a `-devtools` sibling whenever you add a TanStack dependency rather than working
+from a fixed list — the set grows, and not every library has one yet (Store doesn't). Once a project has several,
+`@tanstack/devtools` hosts them in one panel.
+
+## package.json
+
+`"type": "module"`, `"private": true`. Scripts — these names, in every repo:
+
+| Script             | Runs                                                     |
+| ------------------ | -------------------------------------------------------- |
+| `dev`              | dev server                                               |
+| `build`            | production build                                         |
+| `verify:lint`      | `eslint . --cache --max-warnings=0`                      |
+| `verify:format`    | `prettier --check .`                                     |
+| `verify:typecheck` | `tsc --noEmit`                                           |
+| `verify:tests`     | `vitest run`                                             |
+| `verify:staged`    | staged-file subset, called by the pre-commit hook        |
+| `verify:full`      | every check above plus the build; what CI runs           |
+| `format`           | `prettier --write .`                                     |
+| `lint:fix`         | `eslint . --cache --fix`                                 |
+| `git:config`       | `git config core.hooksPath …` + `pull.rebase`/`merge.ff` |
+
+**Every check is `verify:*`.** One namespace, so "what can I run to check this?" is answered by tab-completion. Write-mode
+scripts keep tool names — `format` and `lint:fix` change files, which isn't verifying. Same name, same meaning, every repo.
+
+**Git config is an explicit command.** `git:config` holds the real command, greppable and run by hand after cloning, and the
+README's setup steps name it. `ignore-scripts=true` disables the root package's own lifecycle scripts alongside its
+dependencies', so setup that matters is a command someone runs, not a hook that fires on install.
+
+**Dependencies pinned exactly.** No `^`, `~`, or `latest`, in `dependencies` and `devDependencies` alike. A check script in
+the verify chain enforces it, but that only catches drift after it lands — `save-exact=true` in `.npmrc` stops `npm install`
+reintroducing ranges in the first place.
+
+## Config
+
+**Prettier** — config file shape is free (`.prettierrc`, `prettier.config.ts`); the values are not:
+
+```
+printWidth: 125   tabWidth: 2   useTabs: false   trailingComma: "none"
+arrowParens: "avoid"   semi: true   singleQuote: false   proseWrap: "always"
+```
+
+No config file at all means Prettier runs on defaults — flag it, the values silently differ.
+
+**ESLint** — flat config (`eslint.config.ts`), `strictTypeChecked` + `stylisticTypeChecked` with `projectService: true`, `as`
+and `!` banned outside tests, and `.gitignore` as the ignore source (`includeIgnoreFile` from `@eslint/compat`) so ignores
+aren't maintained twice.
+
+**tsconfig** — defaults:
+
+```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 alias is always `#/` → `src/`. `#` is Node's own subpath-import prefix, so it resolves without a bundler-specific
+convention, and it can't collide with an npm scope the way `@/` does.
+
+**Staged files** — runner config applying eslint `--fix` and prettier `--write` to staged files only.
+
+**Pre-commit** — the hook installs itself via `prepare` → `git:config`, which sets `core.hooksPath` to a tracked directory
+plus `pull.rebase true` and `merge.ff only`, so history strategy doesn't depend on personal git config. Two silent failure
+modes: no `prepare` at all (hooks exist only on the machine that ran `git config` by hand), and `core.hooksPath` pointing at
+a directory that doesn't exist. Check config **and** directory.
+
+**Verify scopes** — two blocking, one advisory:
+
+- **staged** — `verify:staged`, called by the pre-commit hook: lint, format, restage. Fast. A passing commit is not CI green.
+- **full** — `verify:full`: the build plus every `verify:*` check. What CI runs.
+- **files** — optional post-edit agent hook. Advisory, never exits non-zero, so a mid-flight refactor can't trap the agent.
+
+One script owns each scope's step list; npm scripts and hooks only launch them. Name by depth, not by occasion — a name like
+`preflight` needs explaining and invites a second, near-identical script beside it. Two of those drift, and the drift reads
+as "passes locally, fails in CI".
+
+**Node pinning** — `.nvmrc` or `engines.node`. Not a personal version manager's config; that pins it for you alone.
+
+## Folder structure
+
+```
+src/
+  routes/                    # TanStack Router file-based routes; nothing but routing
+  api/<topic>/               # one folder per API topic
+    <topic>.ts               #   queries/mutations
+    query-key.ts             #   key factory
+    types.ts                 #   request/response types
+  components/                # see below
+  http/                      # client, error normalisation — the only transport-aware place
+  lib/                       # framework-free helpers
+```
+
+Everything is kebab-case, folders and files alike.
+
+**Inside `components/`, group by what kind of component it is** — `layouts/`, `primitives/`, `forms/`, or a domain name. Not
+a hard rule: a handful of components reads fine flat, and the grouping should follow what the project actually has rather
+than a structure imposed up front. But most codebases grow past flat, and a clear layout component belongs under `layouts/`
+rather than beside a domain widget.
+
+```
+components/
+  page-header/               # flat is fine
+  layouts/
+    page-shell/
+  data-table/                # a component with sub-component files
+    data-table.tsx
+    data-table-row.tsx
+    data-table.module.css
+    index.ts
+```
+
+A component gets a folder when it has more than one file — sub-components, styles, tests. Single-file components can stay
+single files. The folder's `index.ts` only re-exports, so imports read `#/components/data-table` and the inside can be
+restructured without touching call sites.
+
+Routes stay thin: they compose, they don't fetch inline. `api/<topic>/` holds the query and its key factory together so a key
+is never spelled out at a call site. Anything transport-level (base client, error normalisation) lives in `http/` and nowhere
+else.
+
+## Styling
+
+CSS Modules by default, colocated as `<component>.module.css` next to the component. No CSS-in-JS, no utility-class
+framework.
+
+On a project using `@imfusion/web-ui`, style through the sanctioned seams — `--imf-ui-*` tokens and `data-imf-ui-component`
+attributes, never the library's generated class names. `imf-web-ui-frontend-patterns` covers that contract.
+
+If more than one tool compiles the CSS (app build plus Storybook), the generated class-name pattern must be defined **once**
+and imported by both, or the same source file gets different class names in each and styles silently don't apply.
+`build/css-modules-config.ts` in web-ui is the reference shape; pick your own prefix.
+
+## Optional
+
+Recommend when the shape calls for it; absence is not a finding.
+
+- **knip** — once several people delete things independently.
+- **`ignore-scripts=true` in `.npmrc`** — blocks most supply-chain worm payloads; costs an explicit `npm rebuild` for native
+  deps.
+- **`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-setup`
+- Code conventions (TypeScript, naming, testing) → `imf-web-ui-frontend-patterns`, `references/code-conventions.md`

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

@@ -0,0 +1,57 @@
+---
+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."
+---
+
+# imf-web-ui-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-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.
+
+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.
+
+## Dependency-shipped skills
+
+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.
+
+Setting it up is the project's own call, not something web-ui does on its behalf. Point it out:
+
+> 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.
+
+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.
+
+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.
+
+## 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-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-conventions`; project wiring lives in `imf-web-ui-library-setup`.
+`imf-web-ui-frontend-patterns`; project wiring lives in `imf-web-ui-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-conventions`.
+`imf-web-ui-frontend-patterns`.
 
 ## 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-conventions`) so a breaking change lands in
-one file, not forty call sites.
+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.
 
 ## 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-conventions`), and
+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.
 
 ## Structure

package/bin/install.js

@@ -1,319 +0,0 @@
-#!/usr/bin/env node
-
-// Installs this package's agent tooling into the consumer project: the
-// skill family (../src/llms/skills/imf-web-ui*/) and the agent lifecycle
-// hooks the frontend-setup skill ships as templates. 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.
-//
-// Flags: bare = skills only; --hooks adds the agent lifecycle hooks (driven
-// by the imf-web-ui-agent-setup skill, which checks the repo's existing hooks
-// first). --target claude|agents (repeatable) for scripted installs,
-// --reconfigure to re-open the target prompt on an existing install.
-
-import {
-  chmodSync,
-  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);
-}
-
-// A prior install is recoverable from the filesystem, so a re-run doesn't
-// re-ask: a target counts as chosen when any bundled skill is present under
-// it. Symlinks count — they're how the both-targets layout represents
-// .claude/, and lstat avoids following them into the real copy.
-function detectInstalledTargets(skills) {
-  return Object.keys(TARGETS).filter(key =>
-    skills.some(name => lstatSync(resolve(TARGETS[key].root, name), { throwIfNoEntry: false }))
-  );
-}
-
-// Hook templates ship inside the agent-setup skill so they're readable as
-// part of its documentation; the installer copies the scripts into the
-// consumer's .agents/hooks/ and merges the registrations into
-// .claude/settings.json.
-const hooksSourceDir = resolve(skillsRoot, "imf-web-ui-agent-setup", "templates", "hooks");
-const hooksSettingsTemplate = resolve(skillsRoot, "imf-web-ui-agent-setup", "templates", "settings.json");
-// Installer-owned subdirectory: refreshed wholesale on every run, so a repo's
-// own hooks in .agents/hooks/ are never touched.
-const hooksDestDir = resolve(projectRoot, ".agents", "hooks", "imf-web-ui");
-const settingsPath = resolve(projectRoot, ".claude", "settings.json");
-
-function installHookScripts() {
-  const scripts = readdirSync(hooksSourceDir).filter(name => name.endsWith(".sh"));
-  mkdirSync(hooksDestDir, { recursive: true });
-  for (const name of scripts) {
-    const dest = resolve(hooksDestDir, name);
-    cpSync(resolve(hooksSourceDir, name), dest, { force: true });
-    chmodSync(dest, 0o755);
-  }
-  return scripts.length;
-}
-
-// Merge, never clobber: a registration is added only when no existing entry
-// for that event already runs the same command, so re-runs are idempotent
-// and hand-written settings survive.
-function mergeHookRegistrations() {
-  const template = JSON.parse(readFileSync(hooksSettingsTemplate, "utf-8"));
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-    } catch {
-      return null;
-    }
-  }
-  settings.hooks ??= {};
-  let added = 0;
-  for (const [event, entries] of Object.entries(template.hooks)) {
-    settings.hooks[event] ??= [];
-    for (const entry of entries) {
-      const commands = entry.hooks.map(hook => hook.command);
-      const present = settings.hooks[event].some(existing =>
-        (existing.hooks ?? []).some(hook => commands.includes(hook.command))
-      );
-      if (!present) {
-        settings.hooks[event].push(entry);
-        added++;
-      }
-    }
-  }
-  mkdirSync(dirname(settingsPath), { recursive: true });
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-  return added;
-}
-
-// The AGENTS.md baseline note lives inside a fenced block owned by this
-// installer. The template between the markers is the source of truth; an
-// existing AGENTS.md gets the block replaced in place (or appended when
-// absent), everything outside the fence is untouched. No AGENTS.md at all
-// is left alone — scaffolding one is the setup skill's job.
-const AGENTS_BLOCK_BEGIN = "<!-- imf-web-ui:begin";
-const AGENTS_BLOCK_END = "<!-- imf-web-ui:end -->";
-const agentsTemplatePath = resolve(skillsRoot, "imf-web-ui-frontend-setup", "templates", "AGENTS.md");
-const agentsPath = resolve(projectRoot, "AGENTS.md");
-
-function extractAgentsBlock(content) {
-  const begin = content.indexOf(AGENTS_BLOCK_BEGIN);
-  const end = content.indexOf(AGENTS_BLOCK_END);
-  if (begin === -1 || end === -1) return null;
-  return content.slice(begin, end + AGENTS_BLOCK_END.length);
-}
-
-function upsertAgentsBlock() {
-  if (!existsSync(agentsPath)) return "absent";
-  const block = extractAgentsBlock(readFileSync(agentsTemplatePath, "utf-8"));
-  if (!block) return "absent";
-  const current = readFileSync(agentsPath, "utf-8");
-  const existing = extractAgentsBlock(current);
-  const next = existing ? current.replace(existing, block) : `${current.trimEnd()}\n\n${block}\n`;
-  if (next === current) return "unchanged";
-  writeFileSync(agentsPath, next);
-  return existing ? "updated" : "added";
-}
-
-// --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 argv = process.argv.slice(2);
-  const flagTargets = parseTargetFlags(argv);
-  const reconfigure = argv.includes("--reconfigure");
-  // Bare invocation installs skills only. Hooks are opt-in via --hooks — the
-  // imf-web-ui-agent-setup skill drives that after checking what the repo
-  // already registers; the binary stays the dumb mechanical tail.
-  const wantHooks = argv.includes("--hooks");
-  const wantSkills = argv.includes("--skills") || !wantHooks;
-
-  const components = [wantSkills && `${skills.length} skills`, wantHooks && "agent hooks"].filter(Boolean);
-  p.intro(`@imfusion/web-ui install — ${components.join(" + ")}`);
-
-  if (wantSkills && 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;
-  }
-
-  if (wantHooks) {
-    const scriptCount = installHookScripts();
-    const added = mergeHookRegistrations();
-    p.log.success(`Agent hooks -> ${displayPath(hooksDestDir)} (${scriptCount} scripts)`);
-    if (added === null) {
-      p.log.warn(`${displayPath(settingsPath)} is not valid JSON — registrations not merged, fix it and re-run.`);
-    } else if (added > 0) {
-      p.log.success(`Registered ${added} hook(s) in ${displayPath(settingsPath)}`);
-    } else {
-      p.log.info(`Hook registrations already present in ${displayPath(settingsPath)}`);
-    }
-    if (!wantSkills) {
-      p.outro("Done — hooks installed.");
-      return;
-    }
-  }
-
-  const installedTargets = detectInstalledTargets(skills);
-
-  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 if (installedTargets.length > 0 && !reconfigure) {
-    selected = installedTargets;
-    p.log.info(
-      `Refreshing the existing install: ${selected.map(key => displayPath(TARGETS[key].root)).join(", ")}` +
-        ` — pass --reconfigure to choose different targets.`
-    );
-  } 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}*`);
-    }
-  }
-
-  const agentsResult = upsertAgentsBlock();
-  if (agentsResult === "updated" || agentsResult === "added") {
-    p.log.success(`Refreshed the imf-web-ui block in ${displayPath(agentsPath)}`);
-  }
-
-  p.outro(`Done — ${skills.length} skills installed${wantHooks ? " + agent hooks" : ""}.`);
-}
-
-await main();