@imfusion/web-ui 0.6.1-dev.27.gfc6e5abb → 0.6.1-dev.3.g8b2855c3

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

@@ -1,62 +1,113 @@
 ---
 name: imf-web-ui-components
 description:
-  "Look up @imfusion/web-ui component APIs, compound parts, defaults, and icon glyphs without reading source. Use this
-  whenever a consumer task names a Web UI component or icon and you need to choose a prop, part, default, or glyph. Do not
-  use it to choose between components or bootstrap a project."
+  "Look up @imfusion/web-ui component APIs and icon glyphs without reading source. Load when you need a component's props,
+  sub-components, defaults, or a supplied icon — not for choosing between components (imf-web-ui-ux) or first-time setup
+  (imf-web-ui-setup library-setup)."
 allowed-tools: Bash
 ---
 
-# Look up components
+# imf-web-ui-components
 
-Use the generated package indexes. They are smaller and more reliable than reading the library source.
+`@imfusion/web-ui` ships two generated files inside `node_modules` so an agent can discover and use its components without
+reading source or checking out the library's repo:
 
-## Component lookup
+- **`node_modules/@imfusion/web-ui/src/llms/llms.gen.txt`** — an identity index: every component's name, category, status,
+  and a one-sentence description of what it's for and what else it's called.
+- **`node_modules/@imfusion/web-ui/src/docgen/doc.gen.json`** — full prop tables (name, type, default, description) for every
+  component, keyed by kebab-case folder name.
+- **`node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json`** — searchable icon names, styles, categories, and tags.
+  Read it only when the task needs an icon.
 
-1. Read the identity index:
+Neither file is reachable through the package's pretty import paths (`@imfusion/web-ui/llms.txt`,
+`@imfusion/web-ui/docgen.json`) — those are Node module-resolution aliases, meaningless to `cat`/`jq`/`grep` reading files
+off disk. Use the `node_modules/...` paths above directly.
 
-   ```sh
-   cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
-   ```
+## The lookup, in two hops
 
-   It lists each component's name, category, status, purpose, and docgen entry.
+**Hop 1 — find the component.** Read the whole index; it's small (~13KB for the full library) and safe to load in full:
 
-2. Read only the matching entry from docgen:
+```sh
+cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
+```
 
-   ```sh
-   jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json
-   ```
+Each entry looks like this:
 
-   Replace `.button` with the kebab-case key from the identity index. The result contains `root` and `subComponents`, with
-   each prop's type, default, and description.
+```
+## Button
+- category: Buttons, status: stable
+Triggers an action — submit, confirm, cancel, navigate, or destructive operations. Six semantic variants ...
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .button (jq: jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/button.md
+```
 
-   If `jq` is unavailable, use Node without loading the whole file into the conversation:
+**Hop 2 — pull that component's props.** Don't read the whole docgen file (~500KB across all components) — slice out just the
+one entry with the exact command the index gave you:
 
-   ```sh
-   node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync('node_modules/@imfusion/web-ui/src/docgen/doc.gen.json','utf8')).button, null, 2))"
-   ```
+```sh
+jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json
+```
+
+That returns `{ root: { name, description, props: [...] }, subComponents: [...] }`. `root` is the primary export (`Button`);
+`subComponents` holds compound parts (e.g. `Drawer.Root`, `Drawer.Trigger`, `Drawer.Content` all live under the `drawer`
+key). Match the sub-component you need by its dotted `name`.
+
+**`jq` may not be installed.** Check with `which jq` before relying on it. If it's missing, do **not** fall back to reading
+the whole `doc.gen.json` file — that defeats the entire point of the two-hop design (~500KB across all components vs. one
+~9KB entry) and will burn your context budget for no reason. Use whatever's actually available instead:
+
+```sh
+node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync('node_modules/@imfusion/web-ui/src/docgen/doc.gen.json','utf8')).button, null, 2))"
+```
 
-Use `doc.gen.json` for Web UI props. A linked upstream page is useful for behavior, composition, and accessibility, but its
-prop table is not authoritative for this package.
+(Node ships everywhere this package can be installed, so this always works as a fallback.) Or ask the user to install `jq` if
+you expect to look up several components in one session.
 
-## If the component is missing
+**"Further reading" links, if present, are not a props source.** They point at the upstream library's (usually Base UI's) own
+documentation for composition, anatomy, keyboard/focus behavior, and accessibility notes docgen can't express. Props always
+come from `doc.gen.json` — never treat the linked page's prop table as authoritative for a web-ui component; web-ui may add,
+remove, or default differently.
 
-Treat a missing identity-index entry as a real gap. Do not invent an API or silently import the upstream component. Report
-the gap to the Web UI maintainer. If the question is which existing component fits, use `imf-web-ui-ux` instead.
+## A component not found in the index?
+
+The index is regenerated on every `@imfusion/web-ui` release; it should be exhaustive. If a component you expect is missing,
+don't guess at an API — that's a real gap to report, not something to work around by inventing props. Tell the web-ui
+maintainer, or file it in the [WEBSDK Jira project](https://imfusion.atlassian.net/browse/WEBSDK) if you have access. If the
+gap is about _which_ component to use rather than a missing one, that's a design question: open `imf-web-ui-ux`.
 
 ## Icons
 
-When the task needs an icon, search the generated catalog before choosing a name:
+When the task mentions an icon, glyph, symbol, or `@imfusion/web-ui/icons`, query the icon catalog before choosing a name. Do
+not load it for ordinary component work.
+
+Search one relevant term at a time, then read only the matching records:
 
 ```sh
 node -e '
   const q = process.argv[1].toLowerCase();
-  const icons = JSON.parse(require("fs").readFileSync("node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json", "utf8"));
-  console.log(JSON.stringify(icons.filter(icon => [icon.name, icon.category, ...icon.tags].join(" ").toLowerCase().includes(q)).slice(0, 20), null, 2));
+  const icons = JSON.parse(
+    require("fs").readFileSync(
+      "node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json",
+      "utf8"
+    )
+  );
+  console.log(
+    JSON.stringify(
+      icons
+        .filter(icon => [icon.name, icon.category, ...icon.tags]
+          .join(" ")
+          .toLowerCase()
+          .includes(q))
+        .slice(0, 20),
+      null,
+      2
+    )
+  );
 ' "add"
 ```
 
-Import the glyph and `Icon` from the Web UI icons entry. Always render the glyph through `Icon`:
+Import the chosen glyph and `Icon` from `@imfusion/web-ui/icons`. Render it through `Icon`, including when it inherits the
+surrounding color:
 
 ```tsx
 import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
@@ -64,33 +115,39 @@ import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
 <Icon glyph={ArrowRight} aria-hidden />;
 ```
 
-Do not import `iconoir-react` or another icon package directly.
-
-## Compound components
-
-A non-empty `subComponents` array means the component is a namespace:
+Use `Icon` for every rendered icon. Pass the component reference, not a rendered element:
 
 ```tsx
-import { Drawer } from "@imfusion/web-ui";
+import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
 
-<Drawer.Root>
-  <Drawer.Trigger>Open</Drawer.Trigger>
-  <Drawer.Content>…</Drawer.Content>
-</Drawer.Root>;
+<Icon glyph={ArrowRight} size={16} variant="primary" aria-label="Continue" role="img" />;
 ```
 
-Use the identity index for the family description and the docgen entry for each part's props.
+Never import `iconoir-react` or another icon package directly.
+
+## Compound components
 
-## Integrations
+A component whose docgen entry has a non-empty `subComponents` array is used as a namespace, not a single import — e.g.
+`import { Drawer } from "@imfusion/web-ui"` then `<Drawer.Root>`, `<Drawer.Trigger>`, `<Drawer.Content>`. The index's
+category/description covers the whole family; look at `subComponents` in the docgen entry to see which parts exist and what
+each one's own props are.
 
-A component whose identity entry says it comes from `@imfusion/web-ui/integrations/*` is not in the main import. Install the
-listed optional peer explicitly, then import from that path:
+## Integrations (own-entry components)
+
+A description mentioning "Imported from `@imfusion/web-ui/integrations/<name>`" is a signal this component isn't in the
+default import — e.g.:
 
 ```tsx
 import { Code } from "@imfusion/web-ui/integrations/code-highlight";
 ```
 
-## Data grids
+These exist because their behavior depends on an optional peer dependency (e.g. `@tanstack/highlight` for `CodeHighlight`)
+that most consumers shouldn't be forced to install. Check the component's description for which peer to add, and add it
+explicitly to your own `package.json` — web-ui does not install it for you.
+
+## Data grids (Table + a headless library)
 
-`Table` supplies styled table parts, not sorting or pagination. Pair them with a headless table library installed by the
-consumer. TanStack Table is the recommended choice. Use `Table.SortableHeaderCell` for sortable columns.
+For a data grid, drive the styled `Table` parts with a headless table library you install yourself. **TanStack Table**
+(`@tanstack/react-table`) is recommended. Map your `useReactTable` instance onto `Table.Root` / `Table.Header` / `Table.Row`
+/ `Table.Cell`, and use `Table.SortableHeaderCell` for sortable columns — it carries the `aria-sort` state and the sort
+indicator. See the Table primitive's Storybook docs for the pairing.

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

@@ -1,49 +1,57 @@
 ---
 name: imf-web-ui-conventions
 description:
-  "Apply the ImFusion frontend conventions to consumer code. Use this whenever a task writes a wrapper or custom UI, CSS,
-  TypeScript, data fetching, validation, tests, project files, configuration, documentation, dependencies, or agent tooling
-  in a project that uses @imfusion/web-ui. Read only the topic references that match the task."
+  "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."
 ---
 
-# Frontend conventions
-
-These are ImFusion defaults, not claims about every frontend. A host project's working choice wins. Use these topics to fill
-a gap or to make a deliberate deviation visible; do not refactor a project just to match the baseline.
-
-## Choose a topic
-
-| Topic                                            | Read when                                                       |
-| ------------------------------------------------ | --------------------------------------------------------------- |
-| [library-setup](topics/library-setup.md)         | Installing or repairing stylesheet and provider wiring.         |
-| [library-boundary](topics/library-boundary.md)   | Rendering Web UI components, wrapping them, or choosing a peer. |
-| [authentication](topics/authentication.md)       | Protecting routes or defining login and logout.                 |
-| [react](topics/react.md)                         | Designing component roles, state ownership, or effects.         |
-| [components](topics/components.md)               | Adding files or deciding component anatomy.                     |
-| [typescript](topics/typescript.md)               | Writing TypeScript or naming values.                            |
-| [styling](topics/styling.md)                     | Writing CSS or customizing Web UI.                              |
-| [tokens](topics/tokens.md)                       | Choosing an exact token name.                                   |
-| [class-names](topics/class-names.md)             | Mapping variants and `className` to CSS.                        |
-| [validation](topics/validation.md)               | Accepting data from outside the frontend.                       |
-| [data](topics/data.md)                           | Adding API queries, mutations, or invalidation.                 |
-| [project-structure](topics/project-structure.md) | Adding files or routes.                                         |
-| [testing](topics/testing.md)                     | Deciding what to test.                                          |
-| [tooling](topics/tooling.md)                     | Adding a dependency or configuring a tool.                      |
-| [npm-project](topics/npm-project.md)             | Changing `package.json`, scripts, pins, or Node.                |
-| [git](topics/git.md)                             | Configuring hooks or choosing verification scope.               |
-| [agent-tooling](topics/agent-tooling.md)         | Installing skills or lifecycle hooks.                           |
-| [assets](topics/assets.md)                       | Adding images, icons, or other static files.                    |
-| [docs-structure](topics/docs-structure.md)       | Writing or reorganizing repository docs.                        |
-
-## How to use the topics
-
-Read the relevant file instead of loading the whole set. Each topic is a short checklist: follow its rules, use its examples
-as patterns, and keep any exception explicit in the host project.
-
-`imf-web-ui-setup` uses these topics to plan approved project changes. `imf-web-ui-audit` uses them to report the current
-state without changing files.
-
-## Documentation
-
-Invoke `/documentation-writer` for new or updated documentation. Use the `docs-structure` topic for repository-specific
-boundaries and conventions; it supplies context for the writer and does not replace the writer's workflow.
+# 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

@@ -58,7 +58,6 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Build custom UI from tokens
 - [ ] Override through the sanctioned seams
 - [ ] The color system
-- [ ] Browser floor
 - [ ] Responsive styling
 
 ## Tokens — `tokens`

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

@@ -1,60 +1,82 @@
 # Agent tooling
 
-`npx web-ui-install` manages the Web UI skills and optional lifecycle hooks in a consumer project. This topic explains the
-choices around that installer.
+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
 
-Run:
-
-```sh
-npx web-ui-install
-```
-
-It installs or refreshes the `imf-web-ui-*` skills, updates the managed `AGENTS.md` fence, and removes skills that the
-package no longer ships. The installer remembers `.claude/skills/`, `.agents/skills/`, or both. Use `--target claude|agents`
-to choose explicitly and `--reconfigure` to choose again.
-
-Skill version markers (`.imf-web-ui-skill-version.json`) show which package version installed each skill. Refresh them with
-the installer; do not hand-edit the vendored files.
+- `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
 
-Install the optional lifecycle hooks with:
-
-```sh
-npx web-ui-install --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"]
 ```
 
-The installer owns the scripts under `.agents/hooks/imf-web-ui/` and merges its registrations into Claude Code and Codex
-settings. It refreshes scripts and removes retired registrations without replacing unrelated entries.
-
-The shipped events are:
-
-- `SessionStart`: point the agent at the Web UI router once per session.
-- `SubagentStart`: provide the same pointer to spawned agents.
-- `UserPromptSubmit`: name the companion skills relevant to the prompt.
-- `Stop`: ask for project verification after a turn edits source files.
-
-Read existing registrations first. If the project already covers an event, do not stack a second hook; adapt the existing
-registration and keep the missing behavior.
-
-`baseline-staleness.sh` is a pre-commit check, not an agent hook. It compares installed skill markers with the installed
-package version.
+- 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 project hooks only 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 project-hook trust gate.
+- 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
 
-Dependencies can ship their own skills. TanStack is one example; its docs and allowlist determine how it is used.
+- npm packages can ship Agent Skills of their own; TanStack does — [tooling.md](./tooling.md) covers TanStack Intent and its
+  allowlist.
 
 ## Hook docs
 
-Read the current host documentation before adding or adapting a hook:
+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](https://code.claude.com/docs/en/hooks)
-- [Codex hooks](https://learn.chatgpt.com/docs/hooks)
-- [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-reference)
+- [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

@@ -2,25 +2,26 @@
 
 ## Importing
 
-Import files from `src/assets/` so the bundler fingerprints and includes them. Do not reference an asset through a
-public-path string.
+- Import everything from `src/assets/` so the bundler fingerprints and bundles it. Never reference an image by public-path
+  string.
 
-## Photographs: WebP
+## Photographs — WebP
 
-Convert photographs to WebP before adding them:
-
-```sh
+```bash
 magick source.png -resize 2000x -quality 80 -define webp:method=6 src/assets/name.webp
 ```
 
-Keep the long edge at 2000px or less. WebP is supported by the browser floor.
+- 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
 
-Use PNG when the image needs alpha or exact pixels. Use an inline SVG component for icons, logos, and line art so it inherits
-`currentColor` and follows the theme.
+- 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
 
-Apply these rules to assets you add or touch. Existing files do not need a format migration just because they use another
-format.
+- Rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep — convert
+  opportunistically.

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

@@ -1,50 +1,65 @@
 # Authentication
 
-Use one route boundary for authentication. The provider, session mechanism, endpoint paths, and login/logout transport stay
-owned by the application.
+One route-protection shape for every frontend; provider, session mechanism, endpoint paths, and login/logout transport stay
+project-owned — no provider is prescribed or named.
 
 ## Starter shape
 
-- Keep public routes under a pathless `_public/` group.
-- Keep authenticated routes under a pathless `_app/` group.
-- Guard `_app/` before its children render.
-- Keep the root route neutral: it owns the outlet and global error/not-found boundaries.
-- A greenfield app starts `_app/` with a minimal `AppShell` unless it has no persistent authenticated navigation.
-
-The file layout is in [project-structure.md](project-structure.md).
+- Authentication sits at the route-group boundary, before child routes render.
+- `_public/` and `_app/`: pathless TanStack Router groups — guards and layouts without `public`/`app` in the URL.
+- The authenticated group keeps this shape even without an `AppShell`.
+
+```text
+src/
+  api/auth/            # getUser query options, keys.ts, types.ts, index.ts barrel
+  lib/auth/
+    login-url.ts       # pure login navigation helper; not an API topic file
+    login-url.test.ts  # focused helper tests
+  routes/
+    __root.tsx         # global Outlet and error/not-found boundaries; no auth guard
+    _public/route.tsx  # anonymous route group
+    _app/route.tsx     # authenticated route group
+```
 
 ## One current-user query
 
-Use one server-backed current-user query as the identity source:
-
-- Put it in `api/auth/queries.ts` and define its key and schema with the [data.md](data.md) pattern.
-- Expose query options as `context.api.auth.getUser()`.
-- Call `ensureQueryData` in a loader or a query hook in a component.
-- Keep credentials and access tokens out of React state.
-- Do not infer authentication from local storage, decoded tokens, route flags, or permission-gated UI.
-
-The server response, parsed at the network boundary, is the source of truth.
+- One identity source of truth: a server-backed current-user query; never copy session credentials or access tokens into
+  React state.
+- The auth topic follows the default [data.md](data.md) shape: `getUser` in `api/auth/queries.ts`, key leading with the
+  `auth` topic, schema in `types.ts`.
+- `lib/auth/login-url.ts`: project-owned navigation helper, not an options factory; tests colocated.
+- Reached as `context.api.auth.getUser()`; returns query options, never a hook or a user value — callers pick
+  `ensureQueryData` or a query hook.
+- Never infer authentication from local storage, a decoded token, a route flag, or permission-gated chrome — stale or
+  forgeable; the server response and its schema define the current user.
 
 ## The two route groups
 
-Both groups may resolve the current-user query in `beforeLoad`. They handle a 401 differently:
+Both resolve the current-user query in `beforeLoad` when they need the answer; only the meaning of a 401 differs:
 
-| Group      | 401 result                                   |
-| ---------- | -------------------------------------------- |
-| `_app/`    | Navigate to the server-owned login endpoint. |
-| `_public/` | Continue as an anonymous user.               |
+| Group      | 401 means         | Result                                      |
+| ---------- | ----------------- | ------------------------------------------- |
+| `_app/`    | not logged in     | navigate to the server-owned login endpoint |
+| `_public/` | anonymous visitor | continue with `user: null`                  |
 
-The `_app/` guard should navigate only for the authentication 401. Rethrow redirects, server failures, connection failures,
-and schema errors so the normal error boundary can handle them. A public route may redirect an already-authenticated user
-into `_app/`.
+- The `_app/route.tsx` guard awaits the query before children render, converts only an authentication 401 into login
+  navigation, rethrows router redirects, and lets 5xx, connection failures, and schema mismatches reach the error boundary.
+- A public landing route may redirect an authenticated user into `_app/`.
+- The root route stays neutral: global `Outlet` and error/not-found boundaries, no public/authenticated decision.
 
 ## Login and logout
 
-Follow the application's documented server flow. Login is a browser navigation when the server owns the session; it is not a
-Query fetch. Logout uses the server's documented state-changing action. Preserve a validated same-origin return path when the
-server supports one. Do not invent an endpoint shape in this shared baseline.
+- Follow the project's documented transport. Server-owned flow: login is a browser navigation, not a Query fetch; logout is
+  the server's documented state-changing action, not an ad-hoc client request.
+- Preserve a validated same-origin return path when the server supports returning to the interrupted route.
+- Never hard-code an endpoint shape or provider into shared frontend conventions.
+- No intermediate login route when the server owns the flow.
+- A failed API request is an auth failure only when its typed error is specifically a 401.
 
 ## App shell
 
-`AppShell` is authenticated chrome, not the authentication mechanism. It can hold the logo, navigation, and session action
-around the `_app/` outlet. An established project keeps its working shell or header choice.
+- `AppShell` is authenticated chrome, not the authentication mechanism.
+- Greenfield default: propose a minimal shell — ImFusion logo, route navigation, stable session action area around the
+  `_app/` outlet.
+- An explicit no-persistent-navigation decision may omit the shell; the `_app/` guard stays.
+- An established project keeps its working choice; public pages may use a small branded header.