@imfusion/web-ui 0.5.1-dev.33.gadde98d1 → 0.5.1-dev.39.gfc64049e

package/src/llms/install-templates/codex-hooks.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/session-start.sh\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/stop.sh\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/subagent-start.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/.agents/hooks/imf-web-ui/user-prompt-submit.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/llms/install-templates/hooks/session-start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# SessionStart: inject the web-ui router pointer once per session. Fixed string — the
+# hook-injection eval asserts on it verbatim.
+echo "This project depends on @imfusion/web-ui. Start at the imf-web-ui skill: it decides whether guidance is needed and routes to the right companion. Repo docs carry only what is unique to this repo."
+exit 0

package/src/llms/install-templates/hooks/stop.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+# Stop: the turn-end verify gate. When this turn edited source files, block the
+# agent from finishing once, instructing it to run the project's verification.
+# Both hosts send stop_hook_active=true when the turn continues because of a
+# prior block, so the gate can never loop. Fails open everywhere else: no git,
+# a clean tree, or no edit evidence in the transcript all pass silently.
+PAYLOAD=$(cat)
+printf '%s' "$PAYLOAD" | grep -q '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+[ -n "$(git status --porcelain -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.css' 2>/dev/null)" ] || exit 0
+# Gate only turns that actually edited files — a tree left dirty by an earlier
+# session must not block a question-answering turn. Edit evidence: Write/Edit
+# tool calls (Claude transcript) or apply_patch calls (Codex rollout).
+TRANSCRIPT=$(printf '%s' "$PAYLOAD" | sed -n 's/.*"transcript_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)
+[ -f "$TRANSCRIPT" ] || exit 0
+grep -q '"name":"Write"\|"name":"Edit"\|"name":"MultiEdit"\|"name":"NotebookEdit"\|apply_patch' "$TRANSCRIPT" || exit 0
+printf '{"decision":"block","reason":"web-ui stop gate: this turn changed source files. Run the project verification (verify:typecheck, verify:lint, and verify:format at minimum), fix what it reports, then finish. If it already ran after the last change, say so and finish."}\n'
+exit 0

package/src/llms/install-templates/hooks/subagent-start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# SubagentStart: subagents don't reliably inherit the parent session's SessionStart
+# context, so they get the same router pointer. Text byte-identical to session-start.sh.
+echo "This project depends on @imfusion/web-ui. Start at the imf-web-ui skill: it decides whether guidance is needed and routes to the right companion. Repo docs carry only what is unique to this repo."
+exit 0

package/src/llms/install-templates/hooks/user-prompt-submit.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# UserPromptSubmit: one-line per-prompt pointer to the companion skills. Fixed string —
+# the hook-injection eval asserts on it verbatim.
+echo "web-ui: check imf-web-ui-components before using a component API, imf-web-ui-conventions before writing code, styles or docs, and imf-web-ui-ux when shaping a screen or flow."
+exit 0

package/src/llms/{skills/imf-web-ui-agent-setup/templates → install-templates}/settings.json

@@ -11,24 +11,32 @@
         ]
       }
     ],
-    "UserPromptSubmit": [
+    "Stop": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/user-prompt-submit.sh\""
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/stop.sh\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/subagent-start.sh\""
           }
         ]
       }
     ],
-    "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\""
           }
         ]
       }

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

@@ -24,14 +24,14 @@ Guidance skills exist to fill gaps, not to add ceremony to clear tasks.
 
 ## Routing
 
-| The task at hand                                                                                          | Open                              |
-| --------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| Using a specific component; checking props, sub-components, or defaults                                   | `imf-web-ui-components`           |
-| First-time setup, adding a library dependency, or components rendering unstyled/broken                    | `imf-web-ui-library-setup`        |
-| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states      | `imf-web-ui-ux`                   |
-| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing         | `imf-web-ui-frontend-conventions` |
-| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure     | `imf-web-ui-frontend-setup`       |
-| Setting up or refreshing agent tooling: vendored skills, lifecycle hooks, dependency-shipped Agent Skills | `imf-web-ui-agent-setup`          |
+| The task at hand                                                                                      | Open                                    |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Using a specific component; checking props, sub-components, or defaults                               | `imf-web-ui-components`                 |
+| First-time setup, adding a library dependency, or components rendering unstyled/broken                | `imf-web-ui-setup` (`library-setup`)    |
+| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states  | `imf-web-ui-ux`                         |
+| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing     | `imf-web-ui-conventions`                |
+| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-setup` / `imf-web-ui-audit` |
+| Installing or checking agent tooling: vendored skills, lifecycle hooks, registrations, and staleness  | `imf-web-ui-setup` / `imf-web-ui-audit` |
 
 The two setup rows are narrow on purpose. They're for "what is this project missing?" — a question about the repo as a whole.
 Being asked to add one config file is just that edit; make it, and don't open a skill to do so.
@@ -44,9 +44,6 @@ APIs. That's normal — open both, in that order.
 TanStack is the recommended tooling library — routing, server state, forms, tables. When a task needs one of those and the
 project has no incumbent, propose it, and read the library's own docs (`npx @tanstack/cli`) rather than working from memory.
 
-Much of the suite also ships Agent Skills inside the package, reachable via TanStack Intent. Wiring that up is
-`imf-web-ui-agent-setup`.
-
 ## When to interview the human
 
 `imf-web-ui-ux` contains a short per-feature interview. Run it **only** when both hold:

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

@@ -0,0 +1,87 @@
+---
+name: imf-web-ui-audit
+description:
+  "Read-only health check for an ImFusion frontend against the conventions baseline. Audit the full project or any topic,
+  including library-setup, tooling, git, npm-project, authentication, project-structure, docs-structure, data, testing,
+  React, TypeScript, class names, validation, components, styling, assets, library-boundary, and tokens. Reports broken
+  pieces, missing pieces, working deviations, present evidence, and unverified state in AUDIT_REPORT.md."
+argument-hint: "[full|<topic>]"
+allowed-tools: Read Glob Grep
+---
+
+# imf-web-ui-audit
+
+You are the frontend health-check auditor. Investigate the repository statically, record every supported conclusion in
+`AUDIT_REPORT.md`, and return the report path and a short verdict. Follow the applicable `imf-web-ui-conventions` topics,
+cite repository evidence, distinguish defects from working deviations, and never present the baseline as universal best
+practice.
+
+## Workflow
+
+1. Resolve the argument. Bare means `full`; a topic selects one row below. If no topic matches, list every available topic
+   instead of guessing or widening the scope.
+2. Read every applicable convention topic and inspect the repository with `Read`, `Glob`, and `Grep` only.
+3. Work through the shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md), checking
+   every row for a full audit and the requested row plus dependencies for a scoped audit.
+4. Check the complete installed skill bundle, version markers, AGENTS fence, lifecycle hooks, registrations, and staleness
+   wiring when `agent-tooling` is in scope. Compare the declared version in `package.json`, the installed
+   `node_modules/@imfusion/web-ui/package.json`, and every `.imf-web-ui-skill-version.json` marker. Report drift and point at
+   `imf-web-ui-update`. The registry is unreachable from this audit, so a line saying that a newer version may exist is
+   unverified.
+5. Write or refresh `AUDIT_REPORT.md` from the shared report contract at
+   [`../imf-web-ui-conventions/templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md), changing the mode label
+   to `audit`. The template is the report contract. Preserve everything under `## Reviewer notes` verbatim.
+
+## Checklist
+
+Use the shared [convention audit checklist](../imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md) as the working checklist.
+The report is not complete until the applicable rows have been inspected and their evidence is reflected in the report. The
+checklist itself is not edited during an audit.
+
+## Safety
+
+Use only static inspection: Read, Glob, Grep, and equivalent non-executing search tools. Do not use a shell or invoke Node,
+npm, npx, package scripts, hooks, config imports, linters, tests, builds, Git commands, or project binaries. Read config as
+text and report runtime or machine-local state that cannot be established statically as unverified.
+
+Only `AUDIT_REPORT.md` may be written. Write is intentionally not pre-approved in `allowed-tools`; the report follows the
+host's ordinary write approval. Host-managed hooks may run after that write; the skill neither invokes nor suppresses them,
+but it does report broken or unexpected hook behavior found during static inspection.
+
+## Topics
+
+| Topic               | Assess                                                                         |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `library-setup`     | styles import, `WebUIProvider`, and library package wiring                     |
+| `library-boundary`  | imports, wrappers, type derivation, and peer boundaries                        |
+| `react`             | component roles, state ownership, and effects discipline                       |
+| `components`        | component folders, anatomy, and colocation                                     |
+| `typescript`        | functional style, types, and naming                                            |
+| `styling`           | CSS Modules, tokens, and prohibited styling systems                            |
+| `tokens`            | names, authored default values, and families from the shipped token index      |
+| `class-names`       | CVA variants, `cx`, and incoming `className` handling                          |
+| `validation`        | runtime schemas, boundary parsing, and derived types                           |
+| `data`              | transport, schemas, query/mutation options, keys, and invalidation             |
+| `authentication`    | current-user query, public/app guards, login, and logout                       |
+| `project-structure` | source tree, route groups, optional app shell, naming, and imports             |
+| `testing`           | test boundaries and verification coverage                                      |
+| `npm-project`       | package metadata, scripts, pins, npm, and Node configuration                   |
+| `tooling`           | dependency selection, devtools, Prettier, ESLint, TypeScript, and verification |
+| `git`               | tracked hooks, verification scopes, and staleness wiring                       |
+| `assets`            | image formats and static asset handling                                        |
+| `docs-structure`    | README, AGENTS, docs index, and content boundaries                             |
+| `agent-tooling`     | installed skills, AGENTS fence, lifecycle hooks, registrations, staleness      |
+
+Report everything within the selected topic: defects and working deviations alike, with no severity-based filtering.
+
+## Agent-tooling assessment reference
+
+The baseline is the conventions [agent-tooling topic](../imf-web-ui-conventions/topics/agent-tooling.md): the complete bundle
+with matching version markers, the AGENTS fence, and the lifecycle hooks installed and registered for both hosts
+(`.claude/settings.json` and `.codex/hooks.json`) or consciously adapted. Hooks or registrations beyond the shipped set — the
+three injection hooks, the stop gate, plus `baseline-staleness.sh` — are drift, and the tracked pre-commit path calls
+`baseline-staleness.sh`. Read files and settings as text—do not run installers, hooks, or local config queries during
+assessment.
+
+Use the shared report template as the report contract. It defines the headings, ordering, empty-section marker, evidence
+format, and reviewer-note preservation rules; do not duplicate that contract here.

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

@@ -3,7 +3,7 @@ name: imf-web-ui-components
 description:
   "Look up @imfusion/web-ui component APIs without reading their source: the two-hop lookup (identity index -> prop data),
   compound components, and integrations. Load when you need the props, sub-components, or defaults of a specific component —
-  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-library-setup)."
+  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-setup library-setup)."
 allowed-tools: Bash
 ---
 

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

@@ -0,0 +1,57 @@
+---
+name: imf-web-ui-conventions
+description:
+  "The ImFusion frontend conventions baseline — in-house conventions, valid in every ImFusion frontend and usable by anyone
+  who likes them. A router over topic references: library setup, library boundary, React, components, TypeScript, styling,
+  tokens, validation, data layer, authentication, project structure, testing, tooling, npm project, git, agent tooling,
+  assets, and docs structure. Load when writing wrapper components, custom UI, styling beyond the defaults, validating
+  external data, adding new files to a consumer app, writing repo docs, touching tool config, choosing any dependency, or
+  installing the vendored skills and lifecycle hooks."
+---
+
+# imf-web-ui-conventions
+
+The ImFusion frontend baseline. In-house conventions, not industry claims — they encode how ImFusion frontends are built, and
+anyone else is welcome to them.
+
+**The project wins.** These defaults fill vacuums: if the host project already has a convention — a styling system, a state
+library, a folder shape — that stands. They are not a license to refactor a consumer codebase toward this document.
+
+When a project has an established convention, it wins. The audit skill records a working difference as a deviation; the setup
+skill proposes only the changes the project asks it to make.
+
+## The topics
+
+Each topic lives in one reference. Read the one whose moment you're in; starting a new feature usually wants several.
+
+| Reference                                           | Covers                                                              | Read when                                               |
+| --------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
+| [library-setup.md](topics/library-setup.md)         | styles import, `WebUIProvider`, and broken library wiring           | installing or repairing library wiring                  |
+| [library-boundary.md](topics/library-boundary.md)   | staying behind `@imfusion/web-ui`, wrappers, type derivation, peers | touching anything that renders library components       |
+| [authentication.md](topics/authentication.md)       | current-user source, public/app guards, login and logout            | setting up or reviewing route protection                |
+| [react.md](topics/react.md)                         | component roles, state kinds and owners, effects discipline         | writing new screens, components, or wrappers            |
+| [components.md](topics/components.md)               | component anatomy on disk: grouping, folders, colocation            | adding a component file                                 |
+| [typescript.md](topics/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
+| [styling.md](topics/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
+| [tokens.md](topics/tokens.md)                       | shipped CSS-variable names grouped by family                        | choosing a design token                                 |
+| [class-names.md](topics/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
+| [validation.md](topics/validation.md)               | runtime schemas, boundary parsing, schema-derived types             | accepting data the frontend does not own                |
+| [data.md](topics/data.md)                           | `api/`+`http/` shape, query/mutation patterns and invalidation      | adding an API topic, a fetch, or a mutation             |
+| [project-structure.md](topics/project-structure.md) | the `src/` tree, route groups, file naming, imports                 | adding files rather than editing existing ones          |
+| [testing.md](topics/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
+| [tooling.md](topics/tooling.md)                     | the topic→tool map, tool configuration, and verification            | choosing a dependency or touching tool config           |
+| [npm-project.md](topics/npm-project.md)             | `package.json`, the `verify:*` script set, dependency pinning       | running or adding a script, adding a dependency         |
+| [git.md](topics/git.md)                             | `git:config`, verify scopes, staleness at commit time               | wiring hooks or the commit path                         |
+| [agent-tooling.md](topics/agent-tooling.md)         | vendored skills, lifecycle hooks, registrations, Codex trust        | installing or reviewing the shipped agent tooling       |
+| [assets.md](topics/assets.md)                       | image formats, the WebP recipe                                      | adding images or other static assets                    |
+| [docs-structure.md](topics/docs-structure.md)       | what a repo documents, where, how it's written                      | writing or restructuring repo docs                      |
+
+## Topic format
+
+Topics are manifests, not essays: `##` sections group rule bullets, and each section is one auditable unit. A rule is one
+imperative bullet; only a pushback-prone rule carries a one-line why. Snippets illustrate rules, prose never replaces them.
+Each topic's `##` sections map 1:1 to its block in [templates/AUDIT_CHECKLIST.md](templates/AUDIT_CHECKLIST.md) — add,
+remove, or rename a section and the checklist follows in the same change.
+
+`imf-web-ui-setup` proposes approved bootstrap changes, while `imf-web-ui-audit` reports the current state against this
+baseline.

package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md

@@ -0,0 +1,141 @@
+# Convention audit checklist
+
+One block per topic, one box per topic section. Check a box only after checking that section's rules against the repo. A full
+audit checks every box; a scoped audit names its topics first and checks only their blocks. Blocks mirror each topic's `##`
+sections one to one — change a topic's sections and this file follows in the same commit.
+
+## Library setup — `library-setup`
+
+- [ ] Entry-point wiring
+- [ ] Symptoms of broken setup
+
+## Library boundary — `library-boundary`
+
+- [ ] Stay behind the library
+- [ ] Wrap primitives when the app has a reason to
+- [ ] Derive types, don't import them
+- [ ] Integrations own their peers
+- [ ] Styling crosses the boundary through seams
+
+## Authentication — `authentication`
+
+- [ ] Starter shape
+- [ ] One current-user query
+- [ ] The two route groups
+- [ ] Login and logout
+- [ ] App shell
+
+## Project structure — `project-structure`
+
+- [ ] Layout
+- [ ] Application boundary
+- [ ] Imports
+
+## React — `react`
+
+- [ ] Composition: pages (smart containers), partials, dumb components
+- [ ] Compose, don't configure
+- [ ] Put state where its truth lives
+- [ ] Effects: last resort, and named
+- [ ] Reading list
+
+## Components — `components`
+
+- [ ] As dumb as possible
+- [ ] Grouping
+- [ ] One file or a folder
+- [ ] Colocation
+
+## TypeScript & code style — `typescript`
+
+- [ ] Types
+- [ ] Immutability & expressions
+- [ ] Naming
+
+## Styling — `styling`
+
+- [ ] CSS authoring
+- [ ] Build custom UI from tokens
+- [ ] Override through the sanctioned seams
+- [ ] The color system
+- [ ] Responsive styling
+
+## Tokens — `tokens`
+
+- [ ] Token index
+
+## Class names in components — `class-names`
+
+- [ ] CVA is the only tool
+- [ ] Merging `className`
+- [ ] Shared CVA modules
+
+## Validation — `validation`
+
+- [ ] Boundaries
+- [ ] Schema first, type derived
+- [ ] TanStack Router search params
+- [ ] Failure handling
+
+## Data — `data`
+
+- [ ] The shape
+- [ ] The network boundary validates
+- [ ] Errors are values
+- [ ] Topic registry and key factory
+- [ ] Options factories and naming
+- [ ] Router context access
+- [ ] Automatic invalidation
+- [ ] Testing the data layer
+
+## Testing — `testing`
+
+- [ ] Naming
+- [ ] What gets a test
+- [ ] Layer-specific recipes
+
+## Tooling — `tooling`
+
+- [ ] Topic-to-tool map
+- [ ] When a library owns a layer
+- [ ] Devtools
+- [ ] Docs over memory
+- [ ] Prettier
+- [ ] ESLint
+- [ ] tsconfig
+- [ ] Staged files
+- [ ] CSS class names
+
+## npm project — `npm-project`
+
+- [ ] package.json
+- [ ] Scripts
+- [ ] Dependencies
+
+## Git — `git`
+
+- [ ] git:config
+- [ ] Verify scopes
+- [ ] Staleness at commit time
+
+## Assets — `assets`
+
+- [ ] Importing
+- [ ] Photographs — WebP
+- [ ] Other formats
+- [ ] Scope
+
+## Documentation structure — `docs-structure`
+
+- [ ] The shape
+- [ ] Repo docs hold only what is unique to the repo
+- [ ] How docs are written
+- [ ] Staleness at commit time
+
+## Agent tooling — `agent-tooling`
+
+- [ ] The skill bundle
+- [ ] The hooks
+- [ ] Codex trust
+- [ ] Dependency-shipped skills
+- [ ] Hook docs

package/src/llms/skills/{imf-web-ui-frontend-setup/templates/FRONTEND_SETUP_REPORT.md → imf-web-ui-conventions/templates/REPORT.md}

@@ -1,6 +1,6 @@
-# Frontend Setup Report
+# Frontend Report
 
-Mode: `<new|audit|align|topic>` Scope: `<all applicable references or resolved topic references>`
+Mode: `<setup|audit>` Scope: `<all applicable topics or the resolved topic>`
 
 <!--
 This template is the report contract. Keep every H2 below once and in this order.
@@ -12,8 +12,8 @@ Broken, Missing, Deviations, and Unverified entries use:
   - Impact: concrete consequence
   - Next action: smallest selectable follow-up
 
-Present entries name the reference and evidence path. Deviations are selectable follow-up work, not defects; in align mode,
-their next actions are migration proposals. Optional tools are not missing findings.
+Present entries name the topic and evidence path. Deviations are selectable follow-up work, not defects. Optional tools are not
+missing findings.
 -->
 
 ## Verdict

package/src/llms/skills/imf-web-ui-conventions/topics/agent-tooling.md

@@ -0,0 +1,82 @@
+# Agent tooling
+
+How a consumer repo carries the `@imfusion/web-ui` agent tooling; `npx web-ui-install` does the mechanics, this topic carries
+the judgment.
+
+## The skill bundle
+
+- `npx web-ui-install` installs or refreshes the vendored `imf-web-ui-*` skills, refreshes the
+  `<!-- imf-web-ui:begin/end -->` fence in an existing `AGENTS.md`, and removes skills dropped from the bundle.
+- Target: remembered first-run choice — `.claude/skills/`, vendor-neutral `.agents/skills/`, or both (`.agents/` real copy,
+  `.claude/` symlink); `--reconfigure` re-opens it, `--target claude|agents` selects non-interactively.
+- Staleness: per-skill `.imf-web-ui-skill-version.json`; a marker older than the installed package means re-run the binary —
+  never hand-diff or hand-edit vendored skill contents.
+
+## The hooks
+
+- `npx web-ui-install --hooks` adds three injection hooks and a turn-end gate.
+- Scripts in `.agents/hooks/imf-web-ui/` are installer-owned: refreshed wholesale each run, retired scripts pruned with their
+  registrations.
+- Registrations merge idempotently into `.claude/settings.json` (Claude Code) and `.codex/hooks.json` (Codex), never touching
+  entries the installer didn't write.
+
+- **SessionStart** — once per session: points the agent at the `imf-web-ui` skills router.
+- **SubagentStart** — the same line, byte for byte, for each spawned subagent; subagents don't reliably inherit the parent
+  session's context.
+- **UserPromptSubmit** — one line per prompt naming the companion skills to consult.
+- **Stop** — the verify gate: when the turn edited source files, it blocks the agent from finishing once, with the
+  instruction to run the project's verification and fix what it reports. Re-entry is detected from the payload, so the gate
+  can never loop; a turn that edited nothing passes untouched.
+
+```mermaid
+flowchart LR
+    SS(["SessionStart<br/>once per session"]) --> ss["session-start.sh"]
+    SA(["SubagentStart<br/>per spawned subagent"]) --> sa["subagent-start.sh"]
+    UP(["UserPromptSubmit<br/>every prompt"]) --> up["user-prompt-submit.sh"]
+    ST(["Stop<br/>turn ends after edits"]) --> st["stop.sh"]
+    ss --> router["injects the router pointer:<br/>start at imf-web-ui"]
+    sa --> router
+    up --> hints["injects the per-task hints:<br/>components · conventions · ux"]
+    st --> gate["blocks once:<br/>run verification first"]
+    router --> agent["agent routes to the right<br/>companion skill"]
+    hints --> agent
+    gate --> agent2["agent verifies,<br/>then finishes"]
+```
+
+- Each injection hook echoes one fixed line and exits 0; the router does the task-sorting a shell script can't — why a hint
+  on every prompt isn't noise.
+- `baseline-staleness.sh` ships alongside but is not an agent hook; the repo's pre-commit calls it ([git.md](./git.md),
+  staleness at commit time).
+- Never edit an installed script — the next install overwrites it; adapt in the repo's own hooks.
+- Registration entries are yours: the installer matches by script name and keeps edited commands across re-runs. Monorepo:
+  the Codex commands anchor at `$(git rev-parse --show-toplevel)` — adjust their paths once after installing when the
+  frontend isn't the git toplevel.
+- **Read the registration files before installing**; per event: nothing registered → install as shipped; already covered by
+  the repo (its own session reminder, say) → don't stack a second hook — fold the missing line into the repo's script, or
+  adapt the shipped one and register that; surface it and let the human pick.
+
+## Codex trust
+
+- Codex runs a project's hooks only when two trust gates hold: the project itself is trusted, and each hook script has been
+  trusted via the `/hooks` review, which keys trust to the script's hash.
+- Until then hooks are skipped, and skipped silently — from outside, a skipped hook and a hook that ran and said nothing look
+  identical.
+- After installing or updating hooks, tell the user to trust the project and review `/hooks` in Codex, and again after any
+  hook script changes.
+- When a hint doesn't show up, check trust before debugging the script.
+- Claude Code has no trust gate for project hooks.
+
+## Dependency-shipped skills
+
+- npm packages can ship Agent Skills of their own; TanStack does — [tooling.md](./tooling.md) covers TanStack Intent and its
+  allowlist.
+
+## Hook docs
+
+Both hosts move fast; read the current references before adapting or adding a hook — payloads and stdout rules differ per
+host and per event.
+
+- [Claude Code: hooks reference](https://code.claude.com/docs/en/hooks) — event list, JSON input and output, exit codes,
+  `disableAllHooks`
+- [Codex: hooks](https://learn.chatgpt.com/docs/hooks) — events, the `hooks.json` schema, trust, `/hooks`
+- [Codex: config reference](https://learn.chatgpt.com/docs/config-file/config-reference) — `[features]` and `[hooks.state]`

package/src/llms/skills/imf-web-ui-conventions/topics/assets.md

@@ -0,0 +1,27 @@
+# Assets
+
+## Importing
+
+- Import everything from `src/assets/` so the bundler fingerprints and bundles it. Never reference an image by public-path
+  string.
+
+## Photographs — WebP
+
+```bash
+magick source.png -resize 2000x -quality 80 -define webp:method=6 src/assets/name.webp
+```
+
+- Quality 80 — visually lossless on photos, routinely an order of magnitude smaller.
+- `method=6` — densest encoding; a one-off cost at conversion time, so take the smaller file.
+- Long edge ≤ 2000px — nothing on the market resolves more in a content image.
+- No `<picture>` fallback — WebP is supported everywhere since 2020.
+
+## Other formats
+
+- Alpha, or pixels that must stay exact → PNG, optimized with `oxipng` or `pngquant`.
+- Icons, logos, line art → inline SVG component, so it inherits `currentColor` and follows the theme.
+
+## Scope
+
+- Rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep — convert
+  opportunistically.