@imfusion/web-ui 0.6.1-dev.9.g317bd6f2 → 0.6.2-dev.1.gf73fc5d3

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

@@ -1,113 +1,62 @@
 ---
 name: imf-web-ui-components
 description:
-  "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)."
+  "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."
 allowed-tools: Bash
 ---
 
-# imf-web-ui-components
+# Look up components
 
-`@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:
+Use the generated package indexes. They are smaller and more reliable than reading the library source.
 
-- **`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.
+## Component lookup
 
-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.
+1. Read the identity index:
 
-## The lookup, in two hops
+   ```sh
+   cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
+   ```
 
-**Hop 1 — find the component.** Read the whole index; it's small (~13KB for the full library) and safe to load in full:
+   It lists each component's name, category, status, purpose, and docgen entry.
 
-```sh
-cat node_modules/@imfusion/web-ui/src/llms/llms.gen.txt
-```
+2. Read only the matching entry from docgen:
 
-Each entry looks like this:
+   ```sh
+   jq '.button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json
+   ```
 
-```
-## 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
-```
+   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.
 
-**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:
+   If `jq` is unavailable, use Node without loading the whole file into the conversation:
 
-```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))"
-```
+   ```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))"
+   ```
 
-(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.
+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.
 
-**"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.
+## If the component is missing
 
-## 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`.
+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.
 
 ## Icons
 
-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:
+When the task needs an icon, search the generated catalog before choosing a name:
 
 ```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 chosen glyph and `Icon` from `@imfusion/web-ui/icons`. Render it through `Icon`, including when it inherits the
-surrounding color:
+Import the glyph and `Icon` from the Web UI icons entry. Always render the glyph through `Icon`:
 
 ```tsx
 import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
@@ -115,39 +64,33 @@ import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
 <Icon glyph={ArrowRight} aria-hidden />;
 ```
 
-Use `Icon` for every rendered icon. Pass the component reference, not a rendered element:
+Do not import `iconoir-react` or another icon package directly.
 
-```tsx
-import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
+## Compound components
 
-<Icon glyph={ArrowRight} size={16} variant="primary" aria-label="Continue" role="img" />;
-```
+A non-empty `subComponents` array means the component is a namespace:
 
-Never import `iconoir-react` or another icon package directly.
+```tsx
+import { Drawer } from "@imfusion/web-ui";
 
-## Compound components
+<Drawer.Root>
+  <Drawer.Trigger>Open</Drawer.Trigger>
+  <Drawer.Content>…</Drawer.Content>
+</Drawer.Root>;
+```
 
-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.
+Use the identity index for the family description and the docgen entry for each part's props.
 
-## Integrations (own-entry components)
+## Integrations
 
-A description mentioning "Imported from `@imfusion/web-ui/integrations/<name>`" is a signal this component isn't in the
-default import — e.g.:
+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:
 
 ```tsx
 import { Code } from "@imfusion/web-ui/integrations/code-highlight";
 ```
 
-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)
+## Data grids
 
-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.
+`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.

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

@@ -1,57 +1,49 @@
 ---
 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."
+  "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."
 ---
 
-# 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.
+# 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.

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

@@ -58,6 +58,7 @@ 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,82 +1,60 @@
 # 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.
+`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.
 
 ## 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.
+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.
 
 ## 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"]
+Install the optional lifecycle hooks with:
+
+```sh
+npx web-ui-install --hooks
 ```
 
-- 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.
+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.
 
 ## 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.
+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.
 
 ## Dependency-shipped skills
 
-- npm packages can ship Agent Skills of their own; TanStack does — [tooling.md](./tooling.md) covers TanStack Intent and its
-  allowlist.
+Dependencies can ship their own skills. TanStack is one example; its docs and allowlist determine how it is used.
 
 ## 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.
+Read the current host documentation before adding or adapting a hook:
 
-- [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]`
+- [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)

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

@@ -2,26 +2,25 @@
 
 ## Importing
 
-- Import everything from `src/assets/` so the bundler fingerprints and bundles it. Never reference an image by public-path
-  string.
+Import files from `src/assets/` so the bundler fingerprints and includes them. Do not reference an asset through a
+public-path string.
 
-## Photographs — WebP
+## Photographs: WebP
 
-```bash
+Convert photographs to WebP before adding them:
+
+```sh
 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.
+Keep the long edge at 2000px or less. WebP is supported by the browser floor.
 
 ## 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.
+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.
 
 ## Scope
 
-- Rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep — convert
-  opportunistically.
+Apply these rules to assets you add or touch. Existing files do not need a format migration just because they use another
+format.

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

@@ -1,65 +1,50 @@
 # Authentication
 
-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.
+Use one route boundary for authentication. The provider, session mechanism, endpoint paths, and login/logout transport stay
+owned by the application.
 
 ## Starter shape
 
-- 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
-```
+- 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).
 
 ## One current-user query
 
-- 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.
+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.
 
 ## The two route groups
 
-Both resolve the current-user query in `beforeLoad` when they need the answer; only the meaning of a 401 differs:
+Both groups may resolve the current-user query in `beforeLoad`. They handle a 401 differently:
 
-| Group      | 401 means         | Result                                      |
-| ---------- | ----------------- | ------------------------------------------- |
-| `_app/`    | not logged in     | navigate to the server-owned login endpoint |
-| `_public/` | anonymous visitor | continue with `user: null`                  |
+| Group      | 401 result                                   |
+| ---------- | -------------------------------------------- |
+| `_app/`    | Navigate to the server-owned login endpoint. |
+| `_public/` | Continue as an anonymous user.               |
 
-- 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.
+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/`.
 
 ## Login and logout
 
-- 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.
+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.
 
 ## App shell
 
-- `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.
+`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.