@imfusion/web-ui 0.5.0 → 0.5.1-dev.11.g2e949f6d

package/README.md

@@ -1,60 +1,195 @@
 # Web UI
 
-`@imfusion/web-ui` — the official shared Web UI library for ImFusion web apps, built on Base UI (selected through the
-company's Component Library ADR). It will be published to ImFusion's private npm registry for internal use (publishing isn't
-wired up yet — the package is still `private`).
+`@imfusion/web-ui` — the official shared Web UI library for ImFusion web apps, built on Base UI.
 
-This repo is **AI-first**: it's designed to be worked on by driving an agent through a set of skills, and that's the
-smoothest path — but hand-writing code is perfectly welcome too. (How the agent config is wired is described under
-[Working with an AI agent](#working-with-an-ai-agent).)
+- [Usage](#usage) — install, wire up, and keep the version current
+- [Documentation](#documentation) — Storybook and the developer docs
+- [Development](#development) — working on the library itself, including the Agent Skills
+- [Releasing](#releasing) — how versions are derived and how to cut one
 
-Either way, the fastest way in is the **`/web-ui-dev-getting-started`** skill: a short interactive intro that figures out
-what you want to do and points you at the right skill and docs, walking you through setup and the commands you'll need.
+## Usage
 
-For the full workflow, see [`CONTRIBUTING.md`](CONTRIBUTING.md); for the runnable scripts, [`package.json`](package.json) is
-the source of truth.
+The packages are private on npmjs.com.
+
+To install them, get the Web SDK npm token from the
+[Test Licenses](https://imfusion.atlassian.net/wiki/spaces/DEV/pages/255590402/Test+Licenses) page on Confluence and add it
+to your user-level `.npmrc`:
+
+```bash
+npm config set //registry.npmjs.org/:_authToken=<token> --location=user
+```
+
+Then:
+
+```bash
+npm install @imfusion/web-ui
+```
+
+Or if you want to install the latest CI build from master:
+
+```bash
+npm install @imfusion/web-ui@dev
+```
+
+Import the stylesheet and wrap your app root once:
+
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { WebUIProvider } from "@imfusion/web-ui";
+```
+
+### LLM integration
+
+The `web-ui` package does offer first-class support for LLMs, but it's not wired up by default.
+
+To install the skills, run this command after the package is installed:
+
+```bash
+npx web-ui-install
+```
+
+The binary asks which LLM client you use and installs everything it needs. Run it again after a version bump and it refreshes
+the directories it already installed into, without asking again — `--reconfigure` re-opens that choice.
+
+**Available consumer skills - `/imf-web-ui-*`**
+
+| Skill                              | What it does                                                                  |
+| ---------------------------------- | ----------------------------------------------------------------------------- |
+| `/imf-web-ui`                      | The router: decides whether guidance is needed, then which companion to open. |
+| `/imf-web-ui-library-setup`        | One-time wiring in a consumer project — the styles import and the provider.   |
+| `/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-agent-setup`          | Install or update the vendored skills and agent hooks in a consumer repo.     |
+
+Start at `/imf-web-ui` — it routes to the rest. Storybook's **User Guide → AI Agents** page covers the whole family.
+
+### Versions and updates
+
+Every merge to master publishes a new build under the `dev` dist-tag. Which spec you install decides how you pick those up:
+
+| Spec in `package.json`             | Gets                       | Update with                    |
+| ---------------------------------- | -------------------------- | ------------------------------ |
+| `"@imfusion/web-ui": "^0.5.0"`     | matching releases          | `npm update @imfusion/web-ui`  |
+| `"@imfusion/web-ui": "latest"`     | the newest release         | `npm update @imfusion/web-ui`  |
+| `"@imfusion/web-ui": "dev"`        | the newest build of master | `npm update @imfusion/web-ui`  |
+| `"@imfusion/web-ui": "file:….tgz"` | a packed tarball, frozen   | re-pack and re-install by hand |
+
+- **Two dist-tags.** `latest` moves when a release is tagged, `dev` on every build of master (and onto the release when one
+  is cut).
+- **A range like `^0.5.0` is the usual choice.** It tracks releases and states which major you expect; bare `latest` follows
+  releases across majors, breaking changes included.
+- **Dist-tag specs stay literal.** npm keeps `dev` or `latest` as-is in `package.json` and re-resolves on every `npm update`.
+  The concrete version lands in `package-lock.json`, so builds stay reproducible until you update.
+- **Track `dev` while building against the library**, to get new components as they land. Use a release spec for anything you
+  cut a production release from, since `dev` moves whenever someone merges.
+- **A `file:` tarball never updates.** npm copies the archive into `node_modules` and re-copies the same one on every
+  install. Switch to `dev` or a version range to get updates.
+
+## Documentation
+
+**[Storybook](https://storybook.js.org/)** is the documentation platform — the component catalog, every prop, and the setup
+guides. It isn't hosted yet, so run it locally:
+
+```bash
+npm run dev   # builds the library, then Storybook + a rebuild watcher
+```
+
+See the [Developer Docs](./docs/README.md).
+
+## Development
+
+Install the deps and configure git:
 
 ```bash
-npm install   # installs deps, then configures git (see notes below)
+npm install
+npm run git:config   # hooks path + rebase-only pull/merge
 ```
 
-> **Note — `npm install` also configures git** via the `prepare` script: sets `.githooks` as the hooks path, and enforces a
-> rebase-only pull/merge strategy (`pull.rebase true`, `merge.ff only`). No manual git setup needed.
+**Try out **`/web-ui-dev-getting-started`** for an ai assisted start.**
 
-> **Note — install scripts are disabled** (`.npmrc` sets `ignore-scripts=true` for supply-chain security). Today's native
-> deps (esbuild, fsevents) ship their platform binary as an optional dependency, so a fresh install works out of the box. If
-> you add a package that relies on a native install hook (e.g. `sharp`, `node-gyp` builds), it won't run —
-> `npm rebuild <pkg>` once after install, and note it here.
+### LLM integration
 
-# Using the library
+These skills are shipped with a `/web-ui-dev-*` prefix, so to make their names identifiable and not pollute the skill
+namespace.
 
-If you're consuming `@imfusion/web-ui` in a downstream app rather than working on it, **Storybook is your entry point** — it
-carries the setup guides and a live, browsable catalog of every component and its props. It isn't hosted yet; run it locally
-with `npm run dev` (or `npm run storybook`) and open the printed URL.
+| Skill                                     | What it does                                                                          |
+| ----------------------------------------- | ------------------------------------------------------------------------------------- |
+| `/web-ui-dev-getting-started`             | Interactive intro — gauges your experience, works out your goal, routes you.          |
+| `/web-ui-dev-start`                       | Starting ritual for any task: Jira context, `master` vs. a worktree, context summary. |
+| `/web-ui-dev-new-component`               | Scaffolds an architecture-compliant primitive (adapted or absorbed).                  |
+| `/web-ui-dev-update-component`            | Pointers to every file a prop, variant, or sub-component change touches.              |
+| `/web-ui-dev-design-component`            | Brand design pass for a component that works but isn't styled yet.                    |
+| `/web-ui-dev-story`                       | Author or update a Storybook story.                                                   |
+| `/web-ui-dev-commit`                      | Commit workflow: staged docs audit, CI-parity checks, house commit format.            |
+| `/web-ui-dev-audit-docs`                  | Audit docs against staged or recent changes for staleness, gaps, and drift.           |
+| `/web-ui-dev-audit-pass-through-defaults` | Check `@default` annotations on pass-through props against Base UI upstream.          |
+| `/web-ui-dev-manage-worktrees`            | Create, close, or discard a worktree in `.workspaces/`.                               |
+| `/web-ui-dev-refresh-design-reference`    | Refresh the committed brand snapshots in `design/` from the Figma styleguide.         |
+| `/web-ui-dev-mcp`                         | Set up or recover Storybook, DevTools, Atlassian, or Figma MCP access.                |
 
-If an AI agent is working in that downstream app, run `npx web-ui-install-skills` (once `@imfusion/web-ui` is installed) to
-give it the `imf-web-ui` skill family — setup, component lookup, UX guidance, and frontend patterns, with a small router
-skill deciding which applies — no need for it to read this library's source. The skills ship inside the package at
-`src/llms/skills/` (next to the generated llms index; deliberately _not_ in `.agents/skills/`, which holds this repo's own
-development skills). See the **AI Agents** page in Storybook's User Guide for the full skill family and how it routes.
+## Releasing
 
-# Working with an AI agent
+The published version is derived from git tags, not from `package.json`.
 
-The agent config is tool-neutral by design, so the repo isn't tied to a single LLM client:
+The `version` field stays at `0.0.0` in the repository and he CI computes the real number with
+[`scripts/version.ts`](./scripts/version.ts) and writes it into `package.json` on the build agent just before publishing.
 
-- **`AGENTS.md`** holds the instructions, following the cross-tool `AGENTS.md` convention that Cursor, Aider, Windsurf,
-  Copilot and others read directly.
-- **`.agents/skills/`** holds the skills — the reusable, step-by-step workflows an agent runs.
+That working copy is thrown away, so nothing is committed back.
 
-Claude Code is the one client that looks for its own paths rather than these, so it's bridged with two symlinks:
-`CLAUDE.md → AGENTS.md` and `.claude/skills → .agents/skills`. Edit through either path — it's the same file — but `.agents/`
-and `AGENTS.md` are the canonical, git-tracked source.
+`scripts/version.ts` reads `git describe` and applies two rules:
 
-# Architecture
+Given the tag `web-ui/v0.5.0`:
 
-The library's wrappers, types, and public API follow strict rules captured in
-**[docs/architecture.md](docs/architecture.md)**. Read it before contributing — every wrapped component, hook, and public API
-decision must satisfy these rules.
+| Where HEAD sits            | Published version       | dist-tag |
+| -------------------------- | ----------------------- | -------- |
+| Exactly on `web-ui/v0.5.0` | `0.5.0`                 | `latest` |
+| 5 commits after that tag   | `0.5.1-dev.5.gb4de52d7` | `dev`    |
 
-That's one of several developer docs — architecture, conventions, the color system, responsiveness, and story authoring.
-Start from **[docs/README.md](docs/README.md)**, which lays out the full reading order.
+The off-tag string breaks down as:
+
+```
+0.5.1-dev.5.gb4de52d7
+└─┬─┘ └┬┘ │ └───┬────┘
+  │    │  │     └── commit hash, abbreviated; the leading g means "git"
+  │    │  └──────── commits since the tag
+  │    └─────────── pre-release marker, which is what puts it on the dev tag
+  └──────────────── the tag's version, patch bumped
+```
+
+Bumping the patch is what makes a dev build sort above the release it follows and below the next one.
+
+Every build of `master` publishes a `dev` version automatically. To check what the current checkout would publish:
+
+```bash
+npx tsx scripts/version.ts        # prints, changes nothing
+```
+
+### Cutting a release
+
+Tag the commit you want to ship and push the tag:
+
+```bash
+git tag -a web-ui/v0.5.1 -m "web-ui 0.5.1"
+git push origin web-ui/v0.5.1
+```
+
+The tag triggers a build that publishes `0.5.1` as `latest` and repoints the `dev` dist-tag at the same version.
+
+**The tag must be annotated (`-a`).** `git describe` ignores lightweight tags, so a tag pushed without `-a` is invisible to
+the version script — the build reads through it to the previous release tag and publishes another `dev` version instead of
+the release.
+
+The tag name must match `web-ui/vX.Y.Z` exactly. Both the version script's `--match` and the TeamCity branch filter in
+[`.teamcity/settings.kts`](./.teamcity/settings.kts) key off that shape; a tag in any other form publishes nothing.
+
+### Building locally with a real version
+
+A local `npm run build` stamps `dist` with `0.0.0`. When you need the true version in a local artifact:
+
+```bash
+npx tsx scripts/version.ts --write   # writes it into package.json
+npm run build
+git checkout package.json            # discard the write
+```

package/bin/install.js

@@ -0,0 +1,319 @@
+#!/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();