@imfusion/web-ui 0.6.4-dev.7.g1840f300 → 0.6.4-dev.84.gbfc0d437

package/dist/types/meta.d.ts

@@ -1,12 +1,9 @@
 export type ComponentCategoryId = "buttons" | "inputs" | "layout" | "display";
 export type ComponentStatus = "stable" | "experimental" | "deprecated";
 /**
- * Provenance of a component. `"adapted"` wraps an upstream behavioral package —
- * Base UI by default, or another best-in-class library (e.g. TanStack Table);
- * `"native"` is built by us with no upstream runtime dependency, regardless of
- * whether the design took inspiration from elsewhere. Surfaces as the origin
- * badge in the docs UI and on consumer-side surfaces that disambiguate the
- * implementation source.
+ * Provenance of a component. `"adapted"` wraps an upstream behavioral package
+ * (Base UI by default, or another library); `"native"` has no upstream runtime
+ * dependency, regardless of whether the design took inspiration elsewhere.
  */
 export type ComponentOrigin = "adapted" | "native";
 /**
@@ -24,23 +21,16 @@ export interface ComponentUpstream {
     /** LLM-friendly documentation URL — typically the `.md` companion of `docLink`. */
     llmDocLink?: string;
     /**
-     * Package specifiers a consumer must install to use this primitive, when
-     * adapting from an upstream OTHER than the house dependency (Base UI) — e.g.
-     * `["@tanstack/react-table"]` for Table. Omitted for Base-UI-adapted
-     * primitives, which are already present transitively; an absent field and an
-     * empty array both mean "no extra install". An array (not a single string)
-     * because one adapt may require several independently-installable peers (a
-     * lib plus a required companion package). Docs read this to render an install
-     * hint; `name` remains the human-readable display name.
+     * Install-time package specifiers, e.g. `["@tanstack/react-table"]`. Omitted
+     * for Base-UI-adapted primitives (already present transitively); an absent
+     * field and an empty array both mean "no extra install".
      */
     runtimeDependencies?: string[];
 }
 /**
- * A taxonomic category as it appears on a component's meta. Carries both the
- * stable `id` (slug used for grouping/sorting) and a human-readable `label`.
- * Default labels are English; i18n is out of scope for v0 — a later evolution
- * can swap `ComponentCategories` for locale-aware sources without changing the
- * `ComponentCategory` shape consumers read.
+ * A taxonomic category as it appears on a component's meta: a stable `id`
+ * (slug used for grouping/sorting) and a human-readable `label`. Labels are English only;
+ * locale-aware sources can replace `ComponentCategories` without changing this shape.
  */
 export interface ComponentCategory {
     id: ComponentCategoryId;
@@ -48,8 +38,7 @@ export interface ComponentCategory {
 }
 /**
  * Canonical category objects. Every `*.meta.ts` should reference one of these
- * (e.g. `category: ComponentCategories.inputs`) rather than inlining a literal
- * — a literal allows ID/label drift and duplicates the label string per meta.
+ * rather than inlining a literal, which would allow ID/label drift.
  */
 export declare const ComponentCategories: {
     readonly buttons: {
@@ -70,13 +59,9 @@ export declare const ComponentCategories: {
     };
 };
 /**
- * Self-descriptive metadata for an exported component. Describes *what the
- * component is* — name, taxonomy, lifecycle, a one-sentence identity line, and
- * provenance (adapted from an upstream vs. native). NOT documentation prose,
- * usage examples, props, or part enumerations. Props are derived from the
- * component's TypeScript Props interface at build time; longer-form
- * documentation lives in MDX; named sub-exports are the source of truth for
- * compound-component parts.
+ * Self-descriptive metadata for an exported component: name, taxonomy,
+ * lifecycle, identity line, provenance. NOT documentation prose, usage
+ * examples, props, or part enumerations — those live in MDX and the Props interface.
  */
 export interface ComponentMeta {
     /** PascalCase component name as exported from `@imfusion/web-ui`. Matches the `data-imf-ui-component` attribute. */
@@ -99,10 +84,8 @@ export interface ComponentMeta {
     upstream?: ComponentUpstream;
     /**
      * PascalCase names of other `@imfusion/web-ui` components this component
-     * composes internally (e.g. CopyButton renders through Button).
-     * The in-library counterpart to `upstream.runtimeDependencies`: no install
-     * implication — purely discovery/documentation, surfaced by doc tooling
-     * (DocHeader "Uses" row). Omit when the component composes nothing.
+     * composes internally (e.g. CopyButton renders through Button). No install
+     * implication — surfaced by doc tooling (DocHeader "Uses" row).
      */
     internalDependencies?: string[];
 }

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export { resolveClassName, resolveStyle } from './resolve-state-props';

package/dist/utils/resolve-state-props.d.ts

@@ -0,0 +1,4 @@
+/** Resolves a Base UI `className` against the part's state. */
+export declare function resolveClassName<State>(className: string | ((state: State) => string | undefined) | undefined, state: State): string | undefined;
+/** Resolves a Base UI `style` against the part's state. */
+export declare function resolveStyle<State>(style: React.CSSProperties | ((state: State) => React.CSSProperties | undefined) | undefined, state: State): React.CSSProperties | undefined;

package/dist/vite/brand-assets.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from 'vite';
+/** Serves and emits the complete ImFusion favicon set at stable root URLs. */
+export declare function imfusionBrandAssets(): Plugin;

package/dist/vite/index.d.ts

@@ -0,0 +1,2 @@
+export { imfusionBrandAssets } from './brand-assets.ts';
+export { readableCssModuleNames, type ReadableCssModuleNamesOptions } from './readable-css-module-names.ts';

package/dist/vite/readable-css-module-names.d.ts

@@ -0,0 +1,11 @@
+import { Plugin } from 'vite';
+export interface ReadableCssModuleNamesOptions {
+    /** Namespace for every generated class name. Short, stable, app-scoped (`imf-ui`, `acme`). */
+    prefix: string;
+}
+/**
+ * `button.module.css` yields `{prefix}-button-module-root`. Register in every CSS-compiling
+ * tool (app build AND Storybook) or class names diverge and styles silently break. Defaults to
+ * Lightning CSS, which drops `css.modules` options like `localsConvention`.
+ */
+export declare function readableCssModuleNames({ prefix }: ReadableCssModuleNamesOptions): Plugin;

package/dist/vite.js

@@ -0,0 +1,55 @@
+import { readFileSync as e, readdirSync as t } from "node:fs";
+import { dirname as n, join as r } from "node:path";
+import { fileURLToPath as i } from "node:url";
+//#region src/vite/brand-assets.ts
+var a = n(i(import.meta.resolve("@imfusion/web-ui/assets/favicon/favicon.svg"))), o = t(a).map((t) => ({
+	name: t,
+	source: e(r(a, t))
+})), s = {
+	".ico": "image/x-icon",
+	".png": "image/png",
+	".svg": "image/svg+xml"
+};
+function c(e) {
+	return s[e.slice(e.lastIndexOf("."))] ?? "application/octet-stream";
+}
+function l() {
+	return {
+		name: "imf-ui:brand-assets",
+		configureServer(e) {
+			e.middlewares.use((e, t, n) => {
+				let r = o.find(({ name: t }) => e.url?.split("?")[0] === `/${t}`);
+				if (!r) {
+					n();
+					return;
+				}
+				t.setHeader("Content-Type", c(r.name)), t.end(r.source);
+			});
+		},
+		generateBundle() {
+			for (let e of o) this.emitFile({
+				fileName: e.name,
+				source: e.source,
+				type: "asset"
+			});
+		}
+	};
+}
+//#endregion
+//#region src/vite/readable-css-module-names.ts
+function u(e, t) {
+	let { lightningcss: n, modules: r, transformer: i } = e.css ?? {}, a = n?.cssModules;
+	if (!(typeof a == "boolean" || r === !1) && !a?.pattern && !(typeof r == "object" && r.generateScopedName)) return i === "postcss" ? { css: { modules: { generateScopedName: t } } } : { css: {
+		transformer: "lightningcss",
+		lightningcss: { cssModules: { pattern: t } }
+	} };
+}
+function d({ prefix: e }) {
+	let t = `${e}-[name]-[local]`;
+	return {
+		name: "imf-ui:readable-css-module-names",
+		config: (e) => u(e, t)
+	};
+}
+//#endregion
+export { l as imfusionBrandAssets, d as readableCssModuleNames };

package/dist/web-ui-cli.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+import { chmodSync as e, cpSync as t, existsSync as n, lstatSync as r, mkdirSync as i, readFileSync as a, readdirSync as o, readlinkSync as s, realpathSync as c, rmSync as l, symlinkSync as u, writeFileSync as d } from "node:fs";
+import { dirname as f, relative as p, resolve as m } from "node:path";
+import { fileURLToPath as ee } from "node:url";
+import { Command as te, Option as ne } from "commander";
+import * as h from "@clack/prompts";
+import { spawnSync as g } from "node:child_process";
+var _ = {
+	harnesses: {
+		claude: {
+			label: "Claude Code",
+			hookSettings: ".claude/settings.json",
+			hookTemplate: "settings.json"
+		},
+		codex: {
+			label: "Codex",
+			hookSettings: ".codex/hooks.json",
+			hookTemplate: "codex-hooks.json"
+		}
+	},
+	namespace: "imf-web-ui",
+	hooksDir: ".agents/hooks/imf-web-ui",
+	templatesDir: "src/llms/install-templates",
+	skillsSource: "src/llms/skills",
+	skillsDir: ".agents/skills",
+	linkDir: ".claude/skills",
+	versionMarker: ".imf-web-ui-skill-version.json"
+};
+//#endregion
+//#region src/cli/paths.ts
+function re(e) {
+	let t = e;
+	for (; !n(m(t, "package.json"));) {
+		let n = f(t);
+		if (n === t) throw Error(`Could not find package.json above ${e}`);
+		t = n;
+	}
+	return t;
+}
+var v = re(f(ee(import.meta.url))), y = process.cwd(), ie = `<!-- ${_.namespace}:begin`, b = `<!-- ${_.namespace}:end -->`, ae = m(v, _.templatesDir, "AGENTS.md"), x = m(y, "AGENTS.md");
+function S(e) {
+	let t = e.indexOf(ie), n = e.indexOf(b);
+	return t === -1 || n === -1 ? null : e.slice(t, n + b.length);
+}
+function oe() {
+	if (!n(x)) return "absent";
+	let e = S(a(ae, "utf-8"));
+	if (!e) return "absent";
+	let t = a(x, "utf-8"), r = S(t), i = r ? t.replace(r, e) : `${t.trimEnd()}\n\n${e}\n`;
+	return i === t ? "unchanged" : (d(x, i), r ? "updated" : "added");
+}
+//#endregion
+//#region src/cli/skills.ts
+var C = Object.keys(_.harnesses).filter((e) => e in _.harnesses), se = [...C, "all"];
+function w(e) {
+	return e === "all" ? C : [e];
+}
+function T(e) {
+	return `./${p(y, e)}`;
+}
+var E = _.namespace, D = _.versionMarker, O = m(v, _.skillsSource), k = m(y, _.skillsDir), A = m(y, _.linkDir), j = class extends Error {}, M = JSON.parse(a(m(v, "package.json"), "utf-8"));
+if (typeof M != "object" || !M || !("version" in M) || typeof M.version != "string") throw Error(`${m(v, "package.json")} has no string "version" field`);
+var N = M.version;
+function P(e) {
+	return e === E || e.startsWith(`${E}-`);
+}
+function F() {
+	return n(O) ? o(O, { withFileTypes: !0 }).filter((e) => e.isDirectory() && P(e.name)).map((e) => e.name).sort() : [];
+}
+function I(e) {
+	let t = m(k, e, D);
+	if (!n(t)) return null;
+	try {
+		let e = JSON.parse(a(t, "utf-8"));
+		if (typeof e != "object" || !e) return null;
+		let n = "harnesses" in e && Array.isArray(e.harnesses) ? e.harnesses : null;
+		return n ? C.filter((e) => n.includes(e)) : null;
+	} catch {
+		return null;
+	}
+}
+function L(e) {
+	for (let t of e) {
+		let e = I(t);
+		if (e && e.length > 0) return e;
+	}
+	return null;
+}
+function R(e, t, r) {
+	if (n(e)) for (let n of o(e).filter(P)) t.has(n) || (l(m(e, n), {
+		recursive: !0,
+		force: !0
+	}), h.log.info(`Removed skill: ${n} (${r})`));
+}
+function ce() {
+	return n(A) && n(k) && c(A) === c(k);
+}
+function le(e) {
+	let t = m(A, e), n = p(A, m(k, e)), a = r(t, { throwIfNoEntry: !1 });
+	a?.isSymbolicLink() && s(t) === n || (a && l(t, {
+		recursive: !0,
+		force: !0
+	}), i(A, { recursive: !0 }), u(n, t));
+}
+function z(e, n) {
+	try {
+		i(k, { recursive: !0 });
+		for (let r of e) {
+			let e = m(k, r);
+			l(e, {
+				recursive: !0,
+				force: !0
+			}), t(m(O, r), e, { recursive: !0 }), d(m(e, D), JSON.stringify({
+				version: N,
+				harnesses: n
+			}, null, 2) + "\n");
+		}
+		if (R(k, new Set(e), "no longer in this bundle"), h.log.success(`Skills -> ${T(k)}/${E}*`), ce()) return;
+		if (n.includes("claude")) {
+			for (let t of e) le(t);
+			R(A, new Set(e), "no longer in this bundle"), h.log.success(`Claude Code -> ${T(A)}/${E}* (symlinks -> ${T(k)})`);
+		} else R(A, /* @__PURE__ */ new Set(), "claude not selected");
+	} catch (e) {
+		throw e instanceof Error ? new j(e.message) : e;
+	}
+}
+//#endregion
+//#region src/cli/hooks.ts
+var B = m(v, _.templatesDir), V = m(B, "hooks"), H = m(y, _.hooksDir), U = class extends Error {};
+function ue(e, t) {
+	if (typeof e != "object" || !e || Array.isArray(e)) throw new U(`${t} is not a JSON object.`);
+	let n = { ...e };
+	if ("hooks" in n) {
+		if (typeof n.hooks != "object" || n.hooks === null || Array.isArray(n.hooks)) throw new U(`${t}: "hooks" is not a JSON object.`);
+		for (let [e, r] of Object.entries(n.hooks)) if (!Array.isArray(r)) throw new U(`${t}: "hooks.${e}" is not a JSON array.`);
+	}
+	return n;
+}
+function W(e) {
+	let t;
+	try {
+		t = JSON.parse(a(e, "utf-8"));
+	} catch {
+		throw new U(`${e} is not valid JSON.`);
+	}
+	return ue(t, e);
+}
+function de(e) {
+	let t = y;
+	for (; t !== f(t) && !n(m(t, "node_modules", ".bin"));) t = f(t);
+	let r = m(t, "node_modules", ".bin", "prettier");
+	n(r) && g(r, ["--write", e], {
+		cwd: y,
+		stdio: "ignore"
+	});
+}
+function fe() {
+	let n = o(V).filter((e) => e.endsWith(".sh"));
+	i(H, { recursive: !0 });
+	for (let r of n) {
+		let n = m(H, r);
+		t(m(V, r), n, { force: !0 }), e(n, 493);
+	}
+	let r = o(H).filter((e) => e.endsWith(".sh") && !n.includes(e));
+	for (let e of r) l(m(H, e), { force: !0 });
+	return {
+		installed: n,
+		removed: r
+	};
+}
+var G = `${_.hooksDir}/`;
+function K(e) {
+	if (typeof e != "string") return null;
+	let t = e.lastIndexOf(G);
+	if (t === -1) return null;
+	let n = /^([\w.-]+)["']?$/.exec(e.slice(t + G.length));
+	return n ? n[1] : null;
+}
+function q(e) {
+	return typeof e == "object" && !!e && "hooks" in e && Array.isArray(e.hooks);
+}
+function J(e) {
+	return q(e) ? e.hooks : null;
+}
+function Y(e) {
+	return typeof e == "object" && e && "command" in e ? e.command : void 0;
+}
+function X(e) {
+	let t = J(e);
+	return t ? t.map((e) => K(Y(e))).filter((e) => e !== null) : [];
+}
+function pe(e, t, n) {
+	e.hooks ??= {};
+	let r = 0, i = 0, a = [];
+	for (let [r, o] of Object.entries(e.hooks)) {
+		let s = 0, c = o.map((e) => {
+			if (!q(e)) return e;
+			let t = e.hooks, r = t.filter((e) => {
+				let t = K(Y(e));
+				return t === null || n.includes(t);
+			});
+			return s += t.length - r.length, r.length === t.length ? e : {
+				...e,
+				hooks: r
+			};
+		}).filter((e) => {
+			let t = J(e);
+			return t === null || t.length > 0;
+		});
+		s !== 0 && (i += s, c.length === 0 && !(r in t) ? a.push(r) : e.hooks[r] = c);
+	}
+	a.length > 0 && (e.hooks = Object.fromEntries(Object.entries(e.hooks).filter(([e]) => !a.includes(e))));
+	for (let [n, i] of Object.entries(t)) {
+		e.hooks[n] ??= [];
+		for (let t of i) {
+			let i = X(t);
+			e.hooks[n].some((e) => X(e).some((e) => i.includes(e))) || (e.hooks[n].push(t), r++);
+		}
+	}
+	return {
+		added: r,
+		removed: i
+	};
+}
+function me(e) {
+	let t = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+	for (let i of C) {
+		let a = m(y, _.harnesses[i].hookSettings);
+		if (n(a) && t.set(i, W(a)), e.includes(i)) {
+			let e = m(B, _.harnesses[i].hookTemplate);
+			r.set(i, W(e).hooks ?? {});
+		}
+	}
+	let { installed: a, removed: o } = fe();
+	h.log.success(`Agent hooks -> ${T(H)} (${String(a.length)} scripts)`), o.length > 0 && h.log.info(`Removed stale hook script(s): ${o.join(", ")} (no longer shipped)`);
+	for (let n of C) {
+		let o = e.includes(n);
+		if (!o && !t.has(n)) continue;
+		let s = m(y, _.harnesses[n].hookSettings), c = r.get(n) ?? {}, l = t.get(n) ?? {}, u = pe(l, c, o ? a : []);
+		if (u.added === 0 && u.removed === 0) {
+			o && h.log.info(`Hook registrations already present in ${T(s)}`);
+			continue;
+		}
+		i(f(s), { recursive: !0 }), d(s, JSON.stringify(l, null, 2) + "\n"), de(s);
+		let p = [u.added > 0 && `registered ${String(u.added)}`, u.removed > 0 && `removed ${String(u.removed)} stale`].filter(Boolean);
+		h.log.success(`${p.join(", ")} hook registration(s) in ${T(s)}`);
+	}
+}
+//#endregion
+//#region src/cli/index.ts
+function Z() {
+	return new ne("--harness <harness>", "claude, codex, or all").choices(se);
+}
+async function he(e, t, n) {
+	if (t) return h.log.info(`Harness from --harness flag: ${t.join(", ")}`), t;
+	let r = L(e);
+	if (r && !n) return h.log.info(`Refreshing the existing install: ${r.join(", ")} — pass --reconfigure to choose differently.`), r;
+	if (!process.stdin.isTTY) return console.error("Pass --harness=claude|codex|all — no terminal to prompt in."), process.exitCode = 1, null;
+	let i = await h.multiselect({
+		message: "Install into which harness (or harnesses)?",
+		options: C.map((e) => ({
+			value: e,
+			label: _.harnesses[e].label
+		})),
+		required: !0
+	});
+	return h.isCancel(i) ? (h.cancel("Cancelled — nothing installed."), null) : i;
+}
+async function ge(e) {
+	let t = e.harness ? w(e.harness) : null, n = F();
+	if (h.intro(`@imfusion/web-ui install skills — ${String(n.length)} skills`), n.length === 0) {
+		h.log.error("No skills found. Reinstall @imfusion/web-ui and try again."), h.outro("Nothing installed."), process.exitCode = 1;
+		return;
+	}
+	let r = await he(n, t, e.reconfigure === !0);
+	if (!r) return;
+	h.log.message(`Skills in this bundle:\n${n.map((e) => `  - ${e}`).join("\n")}`);
+	try {
+		z(n, r);
+	} catch (e) {
+		if (e instanceof j) {
+			h.log.error(e.message), h.outro("Install failed."), process.exitCode = 1;
+			return;
+		}
+		throw e;
+	}
+	let i = oe();
+	(i === "updated" || i === "added") && h.log.success(`Refreshed the ${_.namespace} block in ./AGENTS.md`), h.outro(`Done — ${String(n.length)} skills installed.`);
+}
+function _e(e) {
+	let t = e.harness ? w(e.harness) : null, n = L(F());
+	if (!t && !n) {
+		console.error("No harness recorded. Pass --harness=claude|codex|all."), process.exitCode = 1;
+		return;
+	}
+	let r = t ?? n ?? [], i = r.filter((e) => !(n ?? []).includes(e));
+	if (i.length > 0) {
+		for (let e of i) console.error(`No skills installed for ${e}. Run \`npx web-ui install skills --harness=${e}\` first.`);
+		process.exitCode = 1;
+		return;
+	}
+	h.intro("@imfusion/web-ui install hooks");
+	try {
+		me(r);
+	} catch (e) {
+		if (e instanceof U) {
+			console.error(e.message), process.exitCode = 1;
+			return;
+		}
+		throw e;
+	}
+	h.outro("Done — agent hooks installed.");
+}
+var Q = new te();
+Q.name("web-ui").description("Command-line tools for @imfusion/web-ui").version(N);
+var $ = Q.command("install").description("Install @imfusion/web-ui agent skills or hooks into a project");
+$.command("skills").description("Install skills for the chosen harness").addOption(Z()).option("--reconfigure", "Re-open the harness selection prompt on an existing install").action(ge), $.command("hooks").description("Install agent lifecycle hooks (requires skills already installed for the harness)").addOption(Z()).action(_e), $.action(() => {
+	$.help();
+}), Q.action(() => {
+	Q.help();
+}), await Q.parseAsync();
+//#endregion

package/docs/user-guide/AgentTooling.mdx

@@ -0,0 +1,127 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="User Guide/Agent Tooling" />
+
+# Agent tooling
+
+The package ships skills and lifecycle hooks for coding agents working in a project that uses `@imfusion/web-ui`. Both are
+optional, but highly recommended: the library is built to be set up and used through an agent.
+
+## Supported agents
+
+The skills follow the [Agent Skills](https://agentskills.io/) standard and install into `.agents/skills/`. Project
+instructions go into [`AGENTS.md`](https://agents.md/): when the project has one, the installer keeps a fenced Web UI block
+in it up to date.
+
+| Agent | Skills | `AGENTS.md` | Hooks |
+| --- | --- | --- | --- |
+| [Codex](https://developers.openai.com/codex/skills) | Reads `.agents/skills/` | [Reads it](https://developers.openai.com/codex/guides/agents-md) | [Supported](https://developers.openai.com/codex/hooks) |
+| [Claude Code](https://code.claude.com/docs/en/skills) | Reads only `.claude/skills/`, so the installer links each skill there | [Reads it](https://code.claude.com/docs/en/changelog#2-1-277) when the project has no `CLAUDE.md`; otherwise add `@AGENTS.md` to `CLAUDE.md` | [Supported](https://code.claude.com/docs/en/hooks) |
+| Other Agent Skills clients | Check the agent's docs for `.agents/skills/` | Check the agent's docs | Not installed |
+
+The installer targets Codex and Claude Code. Other agents that implement the standard are listed on
+[agentskills.io](https://agentskills.io/); one that reads `.agents/skills/` picks up the same skills, without the hooks.
+
+## Install
+
+Install the package first, then run this in the project root:
+
+```sh
+npx web-ui install skills --harness=all
+npx web-ui install hooks --harness=all
+```
+
+`--harness` picks the agent the tooling is installed for:
+
+| Value | Installs for |
+| --- | --- |
+| `claude` | Claude Code |
+| `codex` | Codex, and any agent that reads `.agents/skills/` |
+| `all` | Both |
+
+Without `--harness`, `install skills` prompts once and records the choice, and later runs reuse it. `install hooks` needs the
+skills installed for the same harness first. Leave out the second command to install only the skills.
+
+`npx web-ui --help` lists the commands, and `--help` on any subcommand lists its options.
+
+## Skills
+
+`/imf-web-ui` is the router: the entry point for UI work and library questions. It routes usage questions to the packaged user
+guides and development tasks to the matching companion skill, and it keeps small tasks small instead of loading every
+reference just because the package is installed.
+
+With the hooks installed, the agent is pointed at the router at the start of every session. Without them, the agent usually
+picks it up from the skill's description; invoke it by name when it does not.
+
+| Skill | Use it for |
+| --- | --- |
+| `/imf-web-ui` | The router: any UI task or library question. |
+| `/imf-web-ui-components` | Component props, parts, defaults, and icons. |
+| `/imf-web-ui-ux` | Choosing components and shaping screens or flows. |
+| `/imf-web-ui-conventions` | Code, styling, data, validation, and project conventions. |
+| `/imf-web-ui-setup` | First-time wiring and approved project setup. |
+| `/imf-web-ui-audit` | A read-only check of an existing project. |
+| `/imf-web-ui-update` | Updating the package and its installed tooling. |
+
+## Hooks
+
+The hooks put the agent on the right skill at the right moment and ask it to verify the project after it edits source files:
+
+| Event | What the hook does |
+| --- | --- |
+| `SessionStart` | Points the agent at the router once per session. |
+| `SubagentStart` | Gives the same pointer to spawned agents. |
+| `UserPromptSubmit` | Names the companion skills relevant to the prompt. |
+| `Stop` | Asks for project verification after a turn edits source files. |
+
+## Keeping it current
+
+Ask the agent to update the library, for example "Update @imfusion/web-ui". That runs `/imf-web-ui-update`, which installs
+the newer package and refreshes the skills, hook scripts, and registrations to match it.
+
+To do the same by hand, update the package, then run:
+
+```sh
+npx web-ui install skills
+npx web-ui install hooks
+```
+
+Both reuse the recorded harness. Leave out the second command if the project skips hooks. Together they bring the installed
+tooling in line with the package version and remove anything the package no longer ships.
+
+## Reference
+
+### Where the files go
+
+- Skills: `.agents/skills/` for every harness. `claude` also links each skill from `.claude/skills/`.
+- Hook scripts: `.agents/hooks/imf-web-ui/`.
+- Hook registrations: `.claude/settings.json` for Claude Code, `.codex/hooks.json` for Codex.
+
+### Changing the harness
+
+Pass a different `--harness`, or `--reconfigure` to get the prompt again. Dropping `claude` removes its `.claude/skills`
+links. The next `install hooks` run removes the registrations from a harness that is no longer selected and adds them for the
+newly selected one.
+
+### What the installer owns
+
+The installer owns every skill directory named `imf-web-ui` or `imf-web-ui-*`. It overwrites and prunes those directories and
+leaves every other skill alone, so a project must not put its own skills under that prefix.
+
+Hook registrations merge into the chosen harness's file without touching unrelated entries. For each event, the installer
+adds a shipped hook unless that same script is already registered there; other hooks on that event stay alongside it.
+
+An agent reads the `agent-tooling` topic in the installed `imf-web-ui-conventions` skill before adapting a hook registration.
+
+### Codex trust
+
+Codex only runs project hooks after the project is trusted and each script is approved through `/hooks`. Revisit that review
+after a hook script changes. Claude Code has no equivalent trust gate.
+
+### Where the files come from
+
+The skills ship inside the package under `src/llms/skills/`, and `web-ui install` copies them into the project. The package
+also exposes generated component, token, and icon indexes for the lookup skill. User guides ship as readable MDX under
+`docs/user-guide/`; agents read them from the installed package without a running Storybook.
+
+<PageNav>Importing and composing components, then changing their look with tokens, CSS, and state attributes.</PageNav>