@imfusion/web-ui 0.5.1-dev.33.gadde98d1 → 0.5.1-dev.38.g1e36ac04

package/README.md

@@ -51,18 +51,26 @@ 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.
 
+The optional `--hooks` flag also installs the agent lifecycle hooks and registers them for both hosts, in
+`.claude/settings.json` (Claude Code) and `.codex/hooks.json` (Codex). Three hooks inject one fixed line each: `SessionStart`
+and `SubagentStart` point the agent at the `imf-web-ui` skills router, and `UserPromptSubmit` names the companion skills to
+consult per task. A fourth, the `Stop` gate, blocks a turn that edited source files once, until the agent has addressed the
+project's verification. Re-running the installer refreshes the scripts and prunes retired ones along with their
+registrations. Without `--hooks`, the skills are still available but no lifecycle hook runs. The full flow is documented in
+the shipped [`agent-tooling` topic](./src/llms/skills/imf-web-ui-conventions/topics/agent-tooling.md) of the conventions
+skill.
+
 **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`       | Assess an ImFusion frontend and write a reviewable setup report.               |
-| `/imf-web-ui-agent-setup`          | Install or update the vendored skills, agent hooks, and TanStack Intent.       |
-| `/imf-web-ui-update`               | Update the library, skills, and optional hooks, then verify before committing. |
+| Skill                     | What it does                                                                   |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `/imf-web-ui`             | The router: decides whether guidance is needed, then which companion to open.  |
+| `/imf-web-ui-setup`       | Plan and, after approval, bootstrap a consumer project by topic.               |
+| `/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-conventions` | The frontend conventions baseline, including the sanctioned styling seams.     |
+| `/imf-web-ui-audit`       | Read-only health check for a consumer project, with a reviewable audit report. |
+| `/imf-web-ui-update`      | Update the library, skills, and optional hooks, then verify before committing. |
 
 Start at `/imf-web-ui` — it routes to the rest. Storybook's **User Guide → AI Agents** page covers the whole family.
 

package/bin/install.js

@@ -2,7 +2,7 @@
 
 // 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
+// hooks in the installer-owned template home. 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
@@ -13,9 +13,10 @@
 // .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,
+// Flags: bare = skills only; --hooks adds the agent lifecycle hooks after the
+// consumer checks the repo's existing hooks and still installs the skills.
+// --target claude|agents
+// (repeatable) selects scripted install targets,
 // --reconfigure to re-open the target prompt on an existing install.
 
 import {
@@ -126,28 +127,31 @@ function detectInstalledTargets(skills) {
   );
 }
 
-// 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");
+// Hook templates are installer-owned; the installer copies the scripts into the
+// consumer's .agents/hooks/ and merges the registrations into the host
+// registration files: .claude/settings.json from settings.json, .codex/hooks.json
+// from codex-hooks.json. One pristine template per host, merged verbatim.
+const installTemplatesRoot = resolve(here, "..", "src", "llms", "install-templates");
+const hooksSourceDir = resolve(installTemplatesRoot, "hooks");
+const hooksSettingsTemplate = resolve(installTemplatesRoot, "settings.json");
+const codexHooksTemplate = resolve(installTemplatesRoot, "codex-hooks.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");
+const codexHooksPath = resolve(projectRoot, ".codex", "hooks.json");
 
 // Serializing the file reflows entries this installer doesn't own; the
 // consumer's own Prettier puts them back. Best-effort: absent, or the path is
 // .prettierignore'd, nothing happens.
-function formatSettings() {
+function formatSettings(path) {
   let toolRoot = projectRoot;
   while (toolRoot !== dirname(toolRoot) && !existsSync(resolve(toolRoot, "node_modules", ".bin"))) {
     toolRoot = dirname(toolRoot);
   }
   const prettier = resolve(toolRoot, "node_modules", ".bin", "prettier");
   if (!existsSync(prettier)) return;
-  spawnSync(prettier, ["--write", settingsPath], { cwd: projectRoot, stdio: "ignore" });
+  spawnSync(prettier, ["--write", path], { cwd: projectRoot, stdio: "ignore" });
 }
 
 function installHookScripts() {
@@ -158,7 +162,13 @@ function installHookScripts() {
     cpSync(resolve(hooksSourceDir, name), dest, { force: true });
     chmodSync(dest, 0o755);
   }
-  return scripts.length;
+  // The directory is installer-owned: a script dropped from the template is
+  // removed on refresh, so a stale hook can't keep running after an upgrade.
+  const removed = readdirSync(hooksDestDir).filter(name => name.endsWith(".sh") && !scripts.includes(name));
+  for (const name of removed) {
+    rmSync(resolve(hooksDestDir, name), { force: true });
+  }
+  return { installed: scripts, removed };
 }
 
 // A registration is identified by the script it runs, not the command string:
@@ -169,7 +179,12 @@ function hookScriptId(command) {
   if (typeof command !== "string") return null;
   const at = command.lastIndexOf(HOOKS_DIR_SEGMENT);
   if (at === -1) return null;
-  return command.slice(at + HOOKS_DIR_SEGMENT.length).replace(/["'\s]+$/, "");
+  // Only a bare script name (plus an optional closing quote) identifies a
+  // registration as installer-owned. Trailing arguments or redirection mean
+  // the consumer customized the command; that counts as foreign, so the
+  // stale-prune below can never delete it.
+  const match = command.slice(at + HOOKS_DIR_SEGMENT.length).match(/^([\w.-]+)["']?$/);
+  return match ? match[1] : null;
 }
 
 function entryScriptIds(entry) {
@@ -178,20 +193,50 @@ function entryScriptIds(entry) {
 
 // Merge, never clobber: a registration is added only when no existing entry
 // for that event already runs the same script, so re-runs are idempotent and
-// hand-written settings survive. A run that adds nothing writes nothing.
-function mergeHookRegistrations() {
-  const template = JSON.parse(readFileSync(hooksSettingsTemplate, "utf-8"));
+// hand-written settings survive. The one exception is entries that only run
+// scripts from the installer-owned directory that are no longer shipped —
+// those are pruned, or they would point at a script the refresh just removed.
+// A run that changes nothing writes nothing.
+function mergeHookRegistrations(targetPath, templateHooks, shippedScripts) {
   let settings = {};
-  if (existsSync(settingsPath)) {
+  if (existsSync(targetPath)) {
     try {
-      settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      settings = JSON.parse(readFileSync(targetPath, "utf-8"));
     } catch {
       return null;
     }
   }
   settings.hooks ??= {};
   let added = 0;
-  for (const [event, entries] of Object.entries(template.hooks)) {
+  let removed = 0;
+  // Pruning is per hook, not per entry: only an individual hook that
+  // unambiguously runs a no-longer-shipped installer-owned script goes;
+  // consumer hooks sharing the same entry stay.
+  const emptiedEvents = [];
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    let pruned = 0;
+    const kept = entries
+      .map(entry => {
+        if (!Array.isArray(entry.hooks)) return entry;
+        const hooks = entry.hooks.filter(hook => {
+          const script = hookScriptId(hook.command);
+          return script === null || shippedScripts.includes(script);
+        });
+        pruned += entry.hooks.length - hooks.length;
+        return hooks.length === entry.hooks.length ? entry : { ...entry, hooks };
+      })
+      .filter(entry => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
+    if (pruned === 0) continue;
+    removed += pruned;
+    if (kept.length === 0 && !(event in templateHooks)) emptiedEvents.push(event);
+    else settings.hooks[event] = kept;
+  }
+  // An event whose entries were all pruned disappears instead of lingering as [].
+  if (emptiedEvents.length > 0) {
+    settings.hooks = Object.fromEntries(Object.entries(settings.hooks).filter(([event]) => !emptiedEvents.includes(event)));
+  }
+  for (const [event, entries] of Object.entries(templateHooks)) {
     settings.hooks[event] ??= [];
     for (const entry of entries) {
       const scripts = entryScriptIds(entry);
@@ -204,11 +249,11 @@ function mergeHookRegistrations() {
       }
     }
   }
-  if (added === 0) return 0;
-  mkdirSync(dirname(settingsPath), { recursive: true });
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-  formatSettings();
-  return added;
+  if (added === 0 && removed === 0) return { added, removed };
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, JSON.stringify(settings, null, 2) + "\n");
+  formatSettings(targetPath);
+  return { added, removed };
 }
 
 // The AGENTS.md baseline note lives inside a fenced block owned by this
@@ -218,7 +263,7 @@ function mergeHookRegistrations() {
 // 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 agentsTemplatePath = resolve(installTemplatesRoot, "AGENTS.md");
 const agentsPath = resolve(projectRoot, "AGENTS.md");
 
 function extractAgentsBlock(content) {
@@ -262,11 +307,11 @@ async function main() {
   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.
+  // Every install includes the skill bundle. Hooks are opt-in via --hooks —
+  // the consumer's setup workflow drives that after checking what the repo
+  // already registers, but hooks without their companion skills are invalid.
   const wantHooks = argv.includes("--hooks");
-  const wantSkills = argv.includes("--skills") || !wantHooks;
+  const wantSkills = true;
 
   const components = [wantSkills && `${skills.length} skills`, wantHooks && "agent hooks"].filter(Boolean);
   p.intro(`@imfusion/web-ui install — ${components.join(" + ")}`);
@@ -279,19 +324,28 @@ async function main() {
   }
 
   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)}`);
+    const { installed, removed } = installHookScripts();
+    p.log.success(`Agent hooks -> ${displayPath(hooksDestDir)} (${installed.length} scripts)`);
+    if (removed.length > 0) {
+      p.log.info(`Removed stale hook script(s): ${removed.join(", ")} (no longer shipped)`);
     }
-    if (!wantSkills) {
-      p.outro("Done — hooks installed.");
-      return;
+    const registrations = [
+      [settingsPath, JSON.parse(readFileSync(hooksSettingsTemplate, "utf-8")).hooks],
+      [codexHooksPath, JSON.parse(readFileSync(codexHooksTemplate, "utf-8")).hooks]
+    ];
+    for (const [path, hooks] of registrations) {
+      const result = mergeHookRegistrations(path, hooks, installed);
+      if (result === null) {
+        p.log.warn(`${displayPath(path)} is not valid JSON — registrations not merged, fix it and re-run.`);
+      } else if (result.added > 0 || result.removed > 0) {
+        const changes = [
+          result.added > 0 && `registered ${result.added}`,
+          result.removed > 0 && `removed ${result.removed} stale`
+        ].filter(Boolean);
+        p.log.success(`${changes.join(", ")} hook registration(s) in ${displayPath(path)}`);
+      } else {
+        p.log.info(`Hook registrations already present in ${displayPath(path)}`);
+      }
     }
   }
 

package/bin/install.test.ts

@@ -1,7 +1,6 @@
 import { beforeEach, describe, expect, it } from "vitest";
 import { spawnSync } from "node:child_process";
 import {
-  chmodSync,
   existsSync,
   lstatSync,
   mkdirSync,
@@ -32,6 +31,10 @@ function readSettings(cwd: string) {
 }
 
 let consumer: string;
+const retiredSkillNames = [
+  ["agent", "setup"],
+  ["library", "setup"]
+].map(parts => `imf-web-ui-${parts.join("-")}`);
 
 beforeEach(() => {
   consumer = mkdtempSync(join(tmpdir(), "web-ui-install-"));
@@ -43,8 +46,11 @@ describe("web-ui-install", () => {
 
     const installed = readdirSync(join(consumer, ".agents", "skills"));
     expect(installed).toContain("imf-web-ui");
-    expect(installed).toContain("imf-web-ui-frontend-conventions");
-    expect(installed).toContain("imf-web-ui-frontend-setup");
+    expect(installed).toContain("imf-web-ui-conventions");
+    expect(installed).toContain("imf-web-ui-setup");
+    expect(installed).toContain("imf-web-ui-audit");
+    expect(installed).toHaveLength(7);
+    for (const name of retiredSkillNames) expect(installed).not.toContain(name);
 
     for (const name of installed) {
       expect(existsSync(join(consumer, ".agents", "skills", name, ".imf-web-ui-skill-version.json"))).toBe(true);
@@ -69,20 +75,97 @@ describe("web-ui-install", () => {
     expect(result.stdout).toContain(`Removed orphaned skill: ${orphan} (no longer in this bundle)`);
   });
 
-  it("installs hooks into an installer-owned directory and registers them", () => {
-    runInstall(consumer, "--hooks");
+  it("installs hooks into an installer-owned directory and registers them for both hosts", () => {
+    runInstall(consumer, "--hooks", "--target", "agents");
 
     const hookDir = join(consumer, ".agents", "hooks", "imf-web-ui");
     const scripts = readdirSync(hookDir);
-    expect(scripts).toEqual(expect.arrayContaining(["session-start.sh", "user-prompt-submit.sh", "post-tool-use.sh"]));
+    expect(scripts).toEqual(expect.arrayContaining(["session-start.sh", "subagent-start.sh", "user-prompt-submit.sh"]));
     for (const script of scripts) {
       expect(statSync(join(hookDir, script)).mode & 0o100).toBeTruthy();
     }
 
     const settings = readSettings(consumer);
-    expect(Object.keys(settings.hooks)).toEqual(expect.arrayContaining(["SessionStart", "UserPromptSubmit", "PostToolUse"]));
-    // --hooks alone installs no skills
-    expect(existsSync(join(consumer, ".agents", "skills"))).toBe(false);
+    expect(Object.keys(settings.hooks)).toEqual(
+      expect.arrayContaining(["SessionStart", "SubagentStart", "UserPromptSubmit"])
+    );
+
+    const codexHooks = JSON.parse(readFileSync(join(consumer, ".codex", "hooks.json"), "utf-8")) as {
+      hooks: Record<string, { hooks: { command?: string }[] }[]>;
+    };
+    expect(Object.keys(codexHooks.hooks)).toEqual(Object.keys(settings.hooks));
+    const codexCommands = Object.values(codexHooks.hooks).flatMap(entries =>
+      entries.flatMap(entry => entry.hooks.map(hook => hook.command))
+    );
+    for (const command of codexCommands) {
+      expect(command).toContain("$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/");
+      expect(command).not.toContain("CLAUDE_PROJECT_DIR");
+    }
+
+    expect(readdirSync(join(consumer, ".agents", "skills"))).toHaveLength(7);
+  });
+
+  it("prunes a stale hook script and its registrations on refresh", () => {
+    runInstall(consumer, "--hooks", "--target", "agents");
+    const hookDir = join(consumer, ".agents", "hooks", "imf-web-ui");
+    writeFileSync(join(hookDir, "retired-hook.sh"), "#!/usr/bin/env sh\nexit 0\n");
+    const settingsFile = join(consumer, ".claude", "settings.json");
+    const settings = readSettings(consumer);
+    settings.hooks.PostToolUse = [
+      {
+        hooks: [{ type: "command", command: '"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/retired-hook.sh"' }]
+      } as never
+    ];
+    writeFileSync(settingsFile, JSON.stringify(settings));
+
+    runInstall(consumer, "--hooks", "--target", "agents");
+
+    expect(existsSync(join(hookDir, "retired-hook.sh"))).toBe(false);
+    const refreshed = readSettings(consumer);
+    expect(refreshed.hooks.PostToolUse).toBeUndefined();
+  });
+
+  it("prunes per hook, keeping consumer hooks and customized commands in the same entry", () => {
+    runInstall(consumer, "--hooks", "--target", "agents");
+    const hookDir = join(consumer, ".agents", "hooks", "imf-web-ui");
+    writeFileSync(join(hookDir, "retired-hook.sh"), "#!/usr/bin/env sh\nexit 0\n");
+    const settingsFile = join(consumer, ".claude", "settings.json");
+    const settings = readSettings(consumer);
+    const customized = '"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/session-start.sh" 2>/dev/null';
+    settings.hooks.PostToolUse = [
+      {
+        hooks: [
+          { type: "command", command: '"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/retired-hook.sh"' },
+          { type: "command", command: "npm run my-check" },
+          { type: "command", command: customized }
+        ]
+      } as never
+    ];
+    writeFileSync(settingsFile, JSON.stringify(settings));
+
+    runInstall(consumer, "--hooks", "--target", "agents");
+
+    const commands = readSettings(consumer).hooks.PostToolUse.flatMap(entry => entry.hooks.map(hook => hook.command));
+    expect(commands).toEqual(["npm run my-check", customized]);
+  });
+
+  it("keeps a consumer-adjusted codex command across re-runs, without duplicating it", () => {
+    runInstall(consumer, "--hooks", "--target", "agents");
+    const codexPath = join(consumer, ".codex", "hooks.json");
+    const adjusted = '"$(git rev-parse --show-toplevel)/frontend/.agents/hooks/imf-web-ui/session-start.sh"';
+    const codexHooks = JSON.parse(readFileSync(codexPath, "utf-8")) as {
+      hooks: Record<string, { hooks: { command?: string }[] }[]>;
+    };
+    codexHooks.hooks.SessionStart[0].hooks[0].command = adjusted;
+    writeFileSync(codexPath, JSON.stringify(codexHooks));
+
+    runInstall(consumer, "--hooks", "--target", "agents");
+
+    const refreshed = JSON.parse(readFileSync(codexPath, "utf-8")) as {
+      hooks: Record<string, { hooks: { command?: string }[] }[]>;
+    };
+    const commands = refreshed.hooks.SessionStart.flatMap(entry => entry.hooks.map(hook => hook.command));
+    expect(commands).toEqual([adjusted]);
   });
 
   it("merges registrations without clobbering existing settings, idempotently", () => {
@@ -95,15 +178,16 @@ describe("web-ui-install", () => {
       })
     );
 
-    runInstall(consumer, "--hooks");
-    runInstall(consumer, "--hooks");
+    runInstall(consumer, "--hooks", "--target", "agents");
+    runInstall(consumer, "--hooks", "--target", "agents");
 
     const settings = readSettings(consumer);
     expect(settings.permissions?.allow).toEqual(["Bash(git *)"]);
-    const commands = settings.hooks.PostToolUse.flatMap(entry => entry.hooks.map(hook => hook.command));
-    expect(commands).toContain("echo existing");
+    const foreign = settings.hooks.PostToolUse.flatMap(entry => entry.hooks.map(hook => hook.command));
+    expect(foreign).toContain("echo existing");
     // the shipped registration is added exactly once across both runs
-    expect(commands.filter(command => command?.includes("post-tool-use.sh"))).toHaveLength(1);
+    const commands = settings.hooks.UserPromptSubmit.flatMap(entry => entry.hooks.map(hook => hook.command));
+    expect(commands.filter(command => command?.includes("user-prompt-submit.sh"))).toHaveLength(1);
   });
 
   it("recognises registrations written with braced ${CLAUDE_PROJECT_DIR}", () => {
@@ -112,14 +196,12 @@ describe("web-ui-install", () => {
       join(consumer, ".claude", "settings.json"),
       JSON.stringify({
         hooks: {
-          PostToolUse: [
+          UserPromptSubmit: [
             {
-              matcher: "Edit|MultiEdit|Write",
               hooks: [
                 {
                   type: "command",
-                  command: '"${CLAUDE_PROJECT_DIR}/.agents/hooks/imf-web-ui/post-tool-use.sh"',
-                  statusMessage: "Verifying file"
+                  command: '"${CLAUDE_PROJECT_DIR}/.agents/hooks/imf-web-ui/user-prompt-submit.sh"'
                 }
               ]
             },
@@ -130,23 +212,23 @@ describe("web-ui-install", () => {
       })
     );
 
-    runInstall(consumer, "--hooks");
+    runInstall(consumer, "--hooks", "--target", "agents");
 
     const settings = readSettings(consumer);
-    const commands = settings.hooks.PostToolUse.flatMap(entry => entry.hooks.map(hook => hook.command));
-    expect(commands.filter(command => command?.includes("post-tool-use.sh"))).toHaveLength(1);
-    expect(commands).toContain('"${CLAUDE_PROJECT_DIR}/.agents/hooks/imf-web-ui/post-tool-use.sh"');
+    const commands = settings.hooks.UserPromptSubmit.flatMap(entry => entry.hooks.map(hook => hook.command));
+    expect(commands.filter(command => command?.includes("user-prompt-submit.sh"))).toHaveLength(1);
+    expect(commands).toContain('"${CLAUDE_PROJECT_DIR}/.agents/hooks/imf-web-ui/user-prompt-submit.sh"');
   });
 
   it("does not touch settings.json when every registration is already present", () => {
-    runInstall(consumer, "--hooks");
+    runInstall(consumer, "--hooks", "--target", "agents");
     const settingsFile = join(consumer, ".claude", "settings.json");
     const settings = readSettings(consumer);
     settings.hooks.PreToolUse = [{ hooks: [{ command: "./other/gate.mjs" }] }];
     const before = JSON.stringify(settings, null, 4) + "\n";
     writeFileSync(settingsFile, before);
 
-    const result = runInstall(consumer, "--hooks");
+    const result = runInstall(consumer, "--hooks", "--target", "agents");
 
     expect(readFileSync(settingsFile, "utf-8")).toBe(before);
     expect(result.stdout).toContain("Hook registrations already present");
@@ -174,22 +256,22 @@ describe("web-ui-install", () => {
     expect(appended).toContain("<!-- imf-web-ui:begin");
   });
 
-  it("ships hooks that stay advisory: exit 0 with and without a usable payload", () => {
-    runInstall(consumer, "--hooks");
+  it("ships injection hooks that exit 0 and echo their fixed one-liners", () => {
+    runInstall(consumer, "--hooks", "--target", "agents");
     const hookDir = join(consumer, ".agents", "hooks", "imf-web-ui");
 
-    const noFile = spawnSync("sh", [join(hookDir, "post-tool-use.sh")], { input: "{}", encoding: "utf-8" });
-    expect(noFile.status).toBe(0);
-
-    const missingFile = spawnSync("sh", [join(hookDir, "post-tool-use.sh")], {
-      input: JSON.stringify({ tool_input: { file_path: join(consumer, "nope.ts") } }),
-      encoding: "utf-8"
-    });
-    expect(missingFile.status).toBe(0);
-
     const sessionStart = spawnSync("sh", [join(hookDir, "session-start.sh")], { encoding: "utf-8" });
     expect(sessionStart.status).toBe(0);
-    expect(sessionStart.stdout).toContain("imf-web-ui-frontend-conventions");
+    expect(sessionStart.stdout).toContain("imf-web-ui skill");
+
+    // Subagents get the same router pointer, byte for byte.
+    const subagentStart = spawnSync("sh", [join(hookDir, "subagent-start.sh")], { encoding: "utf-8" });
+    expect(subagentStart.status).toBe(0);
+    expect(subagentStart.stdout).toBe(sessionStart.stdout);
+
+    const promptSubmit = spawnSync("sh", [join(hookDir, "user-prompt-submit.sh")], { encoding: "utf-8" });
+    expect(promptSubmit.status).toBe(0);
+    expect(promptSubmit.stdout).toContain("imf-web-ui-components");
 
     // no node_modules in the consumer → silent success
     const staleness = spawnSync("sh", [join(hookDir, "baseline-staleness.sh")], { cwd: consumer, encoding: "utf-8" });
@@ -197,34 +279,38 @@ describe("web-ui-install", () => {
     expect(staleness.stdout).toBe("");
   });
 
-  it("runs post-edit checks from the package containing the edited file", () => {
-    runInstall(consumer, "--hooks");
-
-    const frontend = join(consumer, "frontend");
-    const source = join(frontend, "src", "example.ts");
-    const binDir = join(frontend, "node_modules", ".bin");
-    const log = join(consumer, "hook.log");
-    mkdirSync(join(frontend, "src"), { recursive: true });
-    mkdirSync(binDir, { recursive: true });
-    writeFileSync(join(frontend, "package.json"), JSON.stringify({ private: true }));
-    writeFileSync(source, "export const example = true;\n");
-
-    for (const tool of ["eslint", "prettier"]) {
-      const path = join(binDir, tool);
-      writeFileSync(path, '#!/usr/bin/env sh\nprintf "%s|%s\\n" "$PWD" "$*" >> "$HOOK_LOG"\n');
-      chmodSync(path, 0o755);
-    }
-
-    const result = spawnSync("sh", [join(consumer, ".agents", "hooks", "imf-web-ui", "post-tool-use.sh")], {
-      cwd: consumer,
-      env: { ...process.env, HOOK_LOG: log },
-      input: JSON.stringify({ tool_input: { file_path: source } }),
-      encoding: "utf-8"
-    });
-
-    expect(result.status).toBe(0);
-    const calls = readFileSync(log, "utf-8").trim().split("\n");
-    expect(calls).toEqual([`${frontend}|--cache ${source}`, `${frontend}|--check ${source}`]);
+  it("gates the turn end only after in-session edits, and never loops", () => {
+    runInstall(consumer, "--hooks", "--target", "agents");
+    const stopHook = join(consumer, ".agents", "hooks", "imf-web-ui", "stop.sh");
+    const transcript = join(consumer, "transcript.jsonl");
+    const runStop = (input: string) => spawnSync("sh", [stopHook], { cwd: consumer, input, encoding: "utf-8" });
+
+    // outside a git repo → silent pass
+    const noGit = runStop("{}");
+    expect(noGit.status).toBe(0);
+    expect(noGit.stdout).toBe("");
+
+    spawnSync("git", ["init", "--quiet", consumer]);
+    mkdirSync(join(consumer, "src"), { recursive: true });
+    writeFileSync(join(consumer, "src", "app.ts"), "export const x = 1;\n");
+    writeFileSync(transcript, '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Write"}]}}\n');
+    const payload = JSON.stringify({ transcript_path: transcript, stop_hook_active: false });
+
+    const blocked = runStop(payload);
+    expect(blocked.status).toBe(0);
+    expect(blocked.stdout).toContain('"decision":"block"');
+    expect(blocked.stdout).toContain("web-ui stop gate:");
+
+    // re-entry after a block → silent pass
+    const reentry = runStop(JSON.stringify({ transcript_path: transcript, stop_hook_active: true }));
+    expect(reentry.status).toBe(0);
+    expect(reentry.stdout).toBe("");
+
+    // dirty tree, but this session's transcript shows no edits → silent pass
+    writeFileSync(transcript, '{"type":"user","message":{"content":"a question"}}\n');
+    const questionTurn = runStop(payload);
+    expect(questionTurn.status).toBe(0);
+    expect(questionTurn.stdout).toBe("");
   });
 
   it("warns from the staleness script when skill markers lag the package", () => {

package/dist/llms/gen-tokens.d.ts

@@ -0,0 +1,7 @@
+export type TokenEntry = {
+    name: string;
+    value: string;
+};
+export declare function collectTokenEntries(files: readonly string[]): TokenEntry[];
+export declare function renderTokenIndex(tokens: readonly TokenEntry[]): string;
+export declare function generateTokenIndex(): Promise<number>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.5.1-dev.33.gadde98d1",
+  "version": "0.5.1-dev.38.g1e36ac04",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "license": "UNLICENSED",
@@ -41,8 +41,10 @@
   },
   "files": [
     "dist",
+    "src/llms/install-templates",
     "src/docgen/doc.gen.json",
     "src/llms/llms.gen.txt",
+    "src/llms/tokens.gen.json",
     "src/llms/skills",
     "bin"
   ],
@@ -50,7 +52,7 @@
     "dev": "tsx scripts/dev.ts",
     "dev:host": "tsx scripts/dev.ts --host",
     "dev:lib": "concurrently -n codegen,lib -c yellow,blue \"npm run codegen:watch\" \"vite build --watch\"",
-    "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms",
+    "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms && npm run codegen:tokens",
     "build:storybook": "npm run codegen:storybook && storybook build",
     "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
     "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
@@ -59,10 +61,12 @@
     "codegen:storybook": "tsx src/codegen/run.ts --storybook",
     "codegen:docgen": "tsx src/docgen/gen-docgen.ts",
     "codegen:llms": "tsx src/llms/gen-llms.ts",
+    "codegen:tokens": "tsx src/llms/gen-tokens.ts",
     "verify:format": "prettier --check .",
     "verify:lint": "eslint . --cache --max-warnings=0",
     "verify:typecheck": "npm run codegen && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.lib.json --noEmit && tsc -p .storybook/tsconfig.json --noEmit",
     "verify:tests": "vitest run",
+    "verify:knip": "knip",
     "verify:deps": "tsx scripts/check-pinned-dependencies.ts",
     "verify:changelog": "tsx scripts/verify/changelog.ts",
     "verify:staged": "tsx scripts/verify/staged.ts",
@@ -77,7 +81,6 @@
     "skills:eval:dev": "WEB_UI_SKILL_EVAL_ROOT=/private/tmp/web-ui-dev-skill-evals WEB_UI_SKILL_EVAL_RESULTS_DIR=.agents/evals/results WEB_UI_SKILL_EVAL_REPORT_PATH=.agents/evals/REPORT.md WEB_UI_SKILL_EVAL_SKILL_FAMILY=web-ui-dev WEB_UI_SKILL_EVAL_WORKSPACE_LABEL='development repository' node src/llms/evals/run.mjs --scenarios-dir .agents/evals/scenarios --setup .agents/evals/setup-env.sh",
     "skills:eval:compare": "node src/llms/evals/compare.mjs",
     "skills:eval:report": "node src/llms/evals/report.mjs",
-    "knip": "knip",
     "git:config": "git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only"
   },
   "peerDependencies": {