@imfusion/web-ui 0.5.1-dev.48.g27701f90 → 0.5.1-dev.5.gb4de52d7

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

@@ -1,50 +0,0 @@
-# Class names in components
-
-How a component turns props into a `className` string. What the build does with the result: [tooling.md](tooling.md); what
-goes in the stylesheet: [styling.md](styling.md).
-
-## CVA is the only tool
-
-- `class-variance-authority` maps variant props to CSS Module classes. No `clsx`, no `tailwind-merge`, no local `cn()`
-  helper.
-- `cx` is CVA's own concatenator, re-exported by `@imfusion/web-ui` — import it from the library alongside the components.
-- Base class is CVA's first argument; variant values are CSS Module references, never string literals. A boolean axis uses
-  `null` for its off-state.
-- Defaults live in the props destructuring, not CVA's `defaultVariants`: react-docgen-typescript reads the destructuring, so
-  defaults declared in CVA don't reach the generated docs.
-
-```tsx
-interface Props extends HTMLAttributes<HTMLSpanElement> {
-  appearance?: "outline" | "solid";
-  inline?: boolean;
-}
-
-const chip = cva(classes.root, {
-  variants: {
-    appearance: { outline: classes.appearanceOutline, solid: classes.appearanceSolid },
-    inline: { false: null, true: classes.inline }
-  }
-});
-
-export function Chip({ appearance = "outline", inline = false, className, ...props }: Props) {
-  return <span {...props} className={chip({ appearance, inline, className })} />;
-}
-```
-
-## Merging `className`
-
-- Every component that accepts `className` merges it; a deliberately closed surface omits the prop entirely rather than
-  accepting and ignoring it.
-- The incoming `className` goes into CVA's `className` slot, which appends it last so a caller's class always wins. With no
-  variants to map, `cx(classes.inline, className)` does the same job.
-- Resolve a function-form `className` before merging — components built on a library that passes render state
-  (`className={state => …}`) receive either shape:
-
-```tsx
-className={state => cx(classes.root, typeof className === "function" ? className(state) : className)}
-```
-
-## Shared CVA modules
-
-- Two components sharing one visual share one CVA module, a `{name}.cva.ts` next to them, so their variant axes can't drift
-  apart.

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

@@ -1,101 +0,0 @@
-# Components
-
-How a component lives on disk and how dumb it stays. Roles, state, effects: [react.md](react.md); styling:
-[styling.md](styling.md).
-
-## As dumb as possible
-
-- Props-fed, never self-fetching: no query hook, no store access, no route awareness — render what's given, report events
-  upward.
-- Presentational logic (formatting a label, deriving a display state) is fine; owning data is not.
-- Local UI state (`isOpen`, a draft value) is allowed; anything whose truth lives elsewhere is not ([react.md](react.md)).
-
-```tsx
-// components/user-card/user-card.tsx
-interface Props {
-  name: string;
-  onEdit: () => void;
-}
-
-export function UserCard({ name, onEdit }: Props) {
-  return (
-    <Card.Root>
-      <Typo>{name}</Typo>
-      <Button onClick={onEdit}>Edit</Button>
-    </Card.Root>
-  );
-}
-```
-
-## Grouping
-
-- `components/` groups by kind (the component roles in [react.md](react.md)) — a layout component under `layouts/`, not
-  beside a domain widget.
-- Flat is fine while there are few; let grouping follow what the project has, don't impose it up front.
-
-## One file or a folder
-
-- More than one file (sub-components, styles, tests) → a folder with an `index.ts` that only re-exports; single-file
-  components stay single files, directly in their group.
-- Imports read `#/components/data-table`, so the inside can be restructured without touching call sites.
-
-The full anatomy of a folder component:
-
-```
-components/data-table/
-  data-table.tsx           # the component: props type + export, CVA variants when it has axes
-  data-table-row.tsx       # sub-component, private unless index.ts re-exports it
-  data-table.module.css    # co-located stylesheet (styling.md)
-  data-table.test.tsx      # only when the component carries decisions worth testing (testing.md)
-  index.ts                 # re-exports only
-```
-
-Most components need only a subset — start with the `.tsx`, add files as they earn their place.
-
-```tsx
-// data-table.tsx — CVA even with one variant axis, so future axes slot in (class-names.md)
-import { cva, type VariantProps } from "class-variance-authority";
-import classes from "./data-table.module.css";
-
-const dataTable = cva(classes.root, {
-  variants: { density: { comfortable: classes.densityComfortable, compact: classes.densityCompact } }
-});
-
-// Intersection, not `interface extends` — VariantProps is an object type. Defaults live in the destructuring.
-type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof dataTable> & { rows: TableRow[] };
-
-export function DataTable({ className, density = "comfortable", rows, ...props }: Props) {
-  return (
-    <div {...props} className={dataTable({ density, className })}>
-      {/* … */}
-    </div>
-  );
-}
-```
-
-```css
-/* data-table.module.css — native nesting + library tokens, no preprocessor, no @layer (styling.md) */
-.root {
-  border-radius: var(--imf-ui-border-radius-2);
-  font-size: var(--imf-ui-font-size-1);
-
-  &:focus-visible {
-    /* states nest under the root */
-  }
-}
-
-.densityCompact {
-  /* one class per CVA variant value */
-}
-```
-
-```ts
-// index.ts — re-exports only; callers import #/components/data-table
-export { DataTable } from "./data-table";
-```
-
-## Colocation
-
-- Stylesheet: `<component>.module.css` next to the component; only dumb components have one — a container that wants CSS is
-  asking for a layout component instead ([react.md](react.md)).
-- Tests and local types sit next to their subject: a file hunted for in a parallel tree gets edited less carefully.

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

@@ -1,221 +0,0 @@
-# Data
-
-The in-house pattern **for TanStack Query + Router**, the default stack ([tooling.md](tooling.md)); other data layers keep
-the boundary principles — validate at the edge, errors as values — not this file layout.
-
-## The shape
-
-- One folder per API topic: options factories, key factory, Zod schemas together, so a query key is never spelled out at a
-  call site.
-- Name a file for what it holds, never for the topic it sits in — the folder already says that: `keys.ts`, not `<topic>.ts`
-  or `query-key.ts` (it holds mutation keys too).
-- A file appears only when the topic needs it: a topic with only queries has no `mutations.ts`, and vice versa.
-- A GraphQL (or similarly document-based) transport may split `queries.ts`/`mutations.ts` further into
-  `queryFns.ts`/`mutationFns.ts`; that's an elaboration of the same options-vs-mutations split, not its origin.
-- Transport code (base client, error normalisation): `http/` and nowhere else.
-- Topic helpers: `lib/`, framework-free, tested beside themselves (`build-query-string.ts` + its test) — never inside the
-  topic folder.
-
-```text
-src/
-  api/
-    topics.ts        # one topic registry, reused by keys and namespaces
-    index.ts         # topic barrels composed as api.<topic>
-    <topic>/
-      index.ts       # barrel: named re-exports of what other modules call
-      keys.ts        # createApiKeys — query and mutation keys
-      queries.ts     # query options factories — present when the topic has queries
-      mutations.ts   # mutation options factories — present when the topic has mutations
-      types.ts       # Zod schemas + z.infer types
-      types.test.ts  # schema cases, when the schema encodes product behaviour
-  http/              # transport: client, error normalisation — the only transport-aware place
-  lib/               # framework-free helpers shared by API topics and other callers
-```
-
-## The network boundary validates
-
-- `http/` returns `unknown`; the topic schema parses the response in its query or mutation function and sources the
-  TypeScript type. Full rules: [validation.md](validation.md).
-
-## Errors are values
-
-- A failed request becomes an `ApiError` with a machine-readable code — a value crossing the boundary, not an ad-hoc caught
-  exception; the frontend maps codes to what the user reads.
-
-## Topic registry and key factory
-
-- One registry of topic names, reused for the barrel's namespaces and the first segment of every query and mutation key.
-- `createApiKeys(topic, { queries, mutations })` types every key `readonly [Topic, ...unknown[]]` and returns `keys.topic`:
-  cross-topic invalidation names the topic, never reconstructs a key prefix.
-
-```ts
-// api/topics.ts — one list of topic names, ApiTopic derived from it
-export const API_TOPICS = { AUTH: "auth", USER: "user", ORDERS: "orders" } as const;
-export type ApiTopic = (typeof API_TOPICS)[keyof typeof API_TOPICS];
-export type QueryKey<Topic extends ApiTopic> = readonly [Topic, ...ReadonlyArray<unknown>] | readonly [Topic];
-export type QueryKeyFactory<Topic extends ApiTopic> = (...args: never[]) => QueryKey<Topic>;
-
-export function createApiKeys<
-  Topic extends ApiTopic,
-  QueryKeys extends Record<string, QueryKey<Topic> | QueryKeyFactory<Topic>>,
-  MutationKeys extends Record<string, QueryKey<Topic>>
->(topic: Topic, keys: { queries: QueryKeys; mutations: MutationKeys }) {
-  return { topic: [topic] as const, queries: keys.queries, mutations: keys.mutations };
-}
-```
-
-```ts
-// api/user/keys.ts — createApiKeys enforces topic-first
-import { API_TOPICS, createApiKeys } from "../topics";
-
-export const keys = createApiKeys(API_TOPICS.USER, {
-  queries: { details: ["user", "details"], byId: (id: string) => ["user", "detail", id] },
-  mutations: { update: ["user", "update"] }
-});
-
-// api/user/index.ts — the topic barrel
-export * from "./keys";
-export * from "./queries";
-export * from "./mutations";
-```
-
-```ts
-// api/index.ts — namespace imports keyed by the topic registry
-import { API_TOPICS } from "./topics";
-import * as auth from "./auth";
-import * as orders from "./orders";
-import * as user from "./user";
-
-export const api = {
-  [API_TOPICS.AUTH]: auth,
-  [API_TOPICS.USER]: user,
-  [API_TOPICS.ORDERS]: orders
-} as const;
-
-export type API = typeof api;
-```
-
-## Options factories and naming
-
-- Topic functions return **options** — never a hook, never data; the caller picks `ensureQueryData` or `useSuspenseQuery`.
-- No topic prefix, no `Options` suffix: `context.api.<topic>.<fn>()` carries both.
-- Queries `get*` (`getAll`, `getById`, `getBySlug`, `getDetails`, `getActive`, `getFiltered`); mutations bare verbs
-  (`update`, `login`, `addItem`, `deleteAddress`, `setShippingMethod`).
-- Same suffix-free naming applies to the local binding a query or mutation resolves to —
-  [typescript.md](typescript.md#naming).
-
-```ts
-// api/user/queries.ts — returns options; keys come from the factory
-import { queryOptions, type QueryOptions } from "@tanstack/react-query";
-import { bffClient } from "../http/bff-client";
-import { userSchema, type User } from "./types";
-import { keys } from "./keys";
-
-export function getDetails(args: { options?: Omit<QueryOptions<User>, "queryKey" | "queryFn"> } = {}) {
-  return queryOptions({
-    ...args.options,
-    queryKey: keys.queries.details,
-    queryFn: async () => userSchema.parse(await bffClient("/me"))
-  });
-}
-```
-
-```ts
-// api/user/mutations.ts — overrides merge over the base, mutationKey leads with the topic
-import type { MutationOptions } from "@tanstack/react-query";
-import { bffClient } from "../http/bff-client";
-import { userSchema, type User, type UserPatch } from "./types";
-import { keys } from "./keys";
-import type { ApiError } from "../http/api-error";
-
-export function update(options?: Omit<MutationOptions<User, ApiError, UserPatch>, "mutationFn">) {
-  return {
-    mutationKey: keys.mutations.update,
-    mutationFn: async (patch: UserPatch) => userSchema.parse(await bffClient("/me", { method: "PATCH", body: patch })),
-    ...options
-  };
-}
-```
-
-## Router context access
-
-- Loaders call `context.api.<topic>.<fn>()`; components use `Route.useRouteContext()`.
-- `createRouter` seeds a placeholder `queryClient`; `router.update()` fills it once the client exists — required because the
-  `MutationCache` closes over both `queryClient` and `router`.
-- Direct imports stay for plain utilities and tests outside the router tree.
-
-```tsx
-// routes/__root.tsx
-import type { QueryClient } from "@tanstack/react-query";
-import type { API } from "../api";
-
-interface RouterContext {
-  api: API;
-  queryClient: QueryClient;
-}
-```
-
-```tsx
-// router.tsx
-import { createRouter } from "@tanstack/react-router";
-import { api } from "./api";
-import { createQueryClient } from "./query-client";
-
-const queryClient = createQueryClient();
-const router = createRouter({ routeTree, context: { api, queryClient } });
-router.update({ context: { api, queryClient } });
-```
-
-```tsx
-// routes/user.tsx
-export const Route = createFileRoute("/user")({
-  loader: ({ context }) => context.queryClient.ensureQueryData(context.api.user.getDetails()),
-  component: UserPage
-});
-
-function UserPage() {
-  const context = Route.useRouteContext();
-  const user = useSuspenseQuery(context.api.user.getDetails());
-  const updateUser = useMutation(
-    context.api.user.update({
-      onSuccess: () => context.queryClient.invalidateQueries({ queryKey: context.api.orders.keys.topic })
-    })
-  );
-  return <input defaultValue={user.data.name} onBlur={e => updateUser.mutate({ name: e.target.value })} />;
-}
-```
-
-## Automatic invalidation
-
-- No hand invalidation at call sites: a `MutationCache` `onSuccess` invalidates `mutationKey[0]` centrally, on by default via
-  `meta.autoInvalidate` — hence every mutation key leads with the topic it dirties.
-- Cross-topic invalidation: per-call-site `onSuccess` override naming `keys.topic` (see `routes/user.tsx`).
-- Opt out with `meta: { autoInvalidate: false }` when a topic-wide refetch is wrong (huge list, targeted optimistic update);
-  invalidate precisely via the key factory.
-- Background: [query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation),
-  [automatic invalidation after mutations](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations).
-
-```ts
-// query-client.ts
-export function createQueryClient() {
-  const queryClient = new QueryClient({
-    defaultOptions: {
-      mutations: { meta: { autoInvalidate: true } }
-    },
-    mutationCache: new MutationCache({
-      onSuccess: async (_data, _variables, _context, mutation) => {
-        if (!mutation.meta?.autoInvalidate) return;
-        const topic = mutation.options.mutationKey?.[0];
-        if (topic !== undefined) await queryClient.invalidateQueries({ queryKey: [topic] });
-      }
-    })
-  });
-  return queryClient;
-}
-```
-
-## Testing the data layer
-
-- Stub the network at the `fetch` boundary and run the real query client: same parse and error path as production.
-- Assert behaviour in schemas, clients, and query options — schema cases: [validation.md](validation.md), philosophy:
-  [testing.md](testing.md).

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

@@ -1,40 +0,0 @@
-# Documentation structure
-
-What a repo documents, where, and how. `imf-web-ui-setup` scaffolds this shape from its `templates/` and audits it.
-
-## The shape
-
-```
-<app>/
-  README.md            # humans: what the app is, setup, scripts
-  AGENTS.md            # agents: tooling and architecture pointers into docs/ — restates nothing
-  docs/
-    index.md           # registers every doc with a one-line "covers" summary
-    <topic>.md         # repo-unique content only
-```
-
-## Repo docs hold only what is unique to the repo
-
-- Litmus, per sentence: would this be true in every ImFusion frontend? Then it's baseline — don't restate it; it's already
-  vendored in-repo under `.agents/skills/imf-web-ui-conventions/`, human-readable and versioned.
-- Write deviations as **named deviations** — what the baseline prescribes, what this repo does instead, and why: a deviation
-  written as freestanding convention gets copied into the next repo as house style.
-
-## How docs are written
-
-- **Docs explain concepts; code is the source of truth for facts.** Capture the why — invariants, rationale, decisions. Never
-  restate a fact that lives in code (a script definition, a type shape, a config value); point at the file — a copied fact
-  rots the moment the code changes.
-- **State what is — no decision residue.** Present-tense statements about the current state; never narrate the delta from a
-  past decision or refute alternatives nobody raised ("there is no X mode", "Y was dropped") — history belongs in commits and
-  tickets. A negation earns its place only as a guardrail or to preempt a wrong assumption a present reader would actually
-  arrive at.
-- **Boy Scout rule.** Discovered rot (a stale pointer, a doc contradicting the code) is always your responsibility: fix it in
-  place if trivial, otherwise report it. Equal failure modes: stepping over rot, and cramming unrelated cleanup into an
-  unrelated change.
-
-## Staleness at commit time
-
-- Docs are checked when they can go stale: at the commit. A staged change that invalidates a doc (a renamed script, a moved
-  folder, a changed flow) updates it **in the same commit**, never a follow-up.
-- Pre-commit carries the advisory staleness checks (vendored baseline, docs) — mechanics in [git.md](git.md).

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

@@ -1,34 +0,0 @@
-# Git
-
-## git:config
-
-- One script holds the repo's git configuration, run by hand once per clone (the README names it):
-
-```
-git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only
-```
-
-- Hooks live in a tracked directory; history strategy doesn't depend on personal git config.
-- Check both silent failure modes — config **and** directory: `git:config` never run (hooks exist only on the machine that
-  configured by hand), and `core.hooksPath` pointing at a missing directory.
-
-## Verify scopes
-
-Two scopes, both blocking:
-
-- **staged** — `verify:staged`, called by the pre-commit hook: lint, format, restage, plus the relevant project-wide checks,
-  including `verify:knip` when staged source or project config can change the reachability graph. Fast; a passing commit is
-  not CI green.
-- **full** — `verify:full`: the build plus every `verify:*` check; what CI runs.
-- One script owns each scope's step list; npm scripts and hooks only launch them.
-- Name by depth, not by occasion: a `preflight` needs explaining and invites a near-identical sibling that drifts into
-  "passes locally, fails in CI".
-
-## Staleness at commit time
-
-Pre-commit also runs the advisory staleness checks — warn, never block:
-
-- **Vendored baseline** — `.agents/hooks/imf-web-ui/baseline-staleness.sh` compares installed `imf-web-ui-*` skill markers
-  against the installed package version; the fix it names is `npx web-ui-install`.
-- **Docs** — a staged change that invalidates a doc updates it in the same commit ([docs-structure.md](docs-structure.md)).
-  An agent commit workflow, where the repo has one, carries a staged docs audit.

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

@@ -1,33 +0,0 @@
-# Library boundary
-
-The contract between an app and `@imfusion/web-ui`.
-
-## Stay behind the library
-
-- Never import Base UI (or any other upstream the library wraps) directly — no upstream stylesheets, no upstream components,
-  even when upstream docs show it that way: everything a component needs ships in `@imfusion/web-ui`.
-- Library missing something upstream has → report the gap (see `imf-web-ui-components`); don't reach around it.
-
-## Wrap primitives when the app has a reason to
-
-- Repeated adaptation around a primitive (default props, a styling override, a composition, an accessibility refinement, a
-  restriction of the API) → wrap it once in an app-level dumb component in `components/` ([components.md](components.md)).
-- The wrapper derives its props from the primitive (`React.ComponentProps<typeof Button>`, narrowed or extended) and styles
-  itself through the sanctioned seams — never the library's internals.
-- Wrap for a reason — any repeated adaptation counts; a wrapper that only renames a primitive is indirection with no payoff.
-- Components marked `experimental` in the identity index get wrapped **always**, even with nothing added yet — a breaking
-  upstream change then lands in one file instead of every call site.
-
-## Derive types, don't import them
-
-- Prop types come from the components themselves: `React.ComponentProps<typeof Button>`.
-- The library deliberately exports no `Props` types — don't look for them, don't re-declare prop shapes by hand.
-
-## Integrations own their peers
-
-- `@imfusion/web-ui/integrations/*` components depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`). Add
-  the peer explicitly to the consumer's `package.json` — never rely on hoisting.
-
-## Styling crosses the boundary through seams
-
-- Tokens in, sanctioned selectors at the edge, never the library's internals — the full contract is [styling.md](styling.md).

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

@@ -1,26 +0,0 @@
-# Library setup
-
-Library wiring (styles import + `WebUIProvider`) for anyone using `@imfusion/web-ui` — `imf-web-ui-setup library-setup`
-proposes a bootstrap change, `imf-web-ui-audit library-setup` is the read-only health check.
-
-## Entry-point wiring
-
-- Every consumer entry point has exactly two lines, in this order:
-
-  ```tsx
-  import "@imfusion/web-ui/styles.css";
-  import { WebUIProvider, Button } from "@imfusion/web-ui";
-  ```
-
-- Wrap the app root in `<WebUIProvider>` once — components rendered outside it lack the theme and CSS-variable context they
-  expect.
-- Never import a Base UI (or other upstream) stylesheet or component directly — everything a web-ui component needs is inside
-  `styles.css` and the package's own exports. What may be reached for when the library lacks a component:
-  [library boundary](library-boundary.md).
-
-## Symptoms of broken setup
-
-- Components render but look unstyled → the `styles.css` import is missing from the entry point.
-- Components render but ignore the theme (wrong colors, CSS variables not resolving) → mounted outside `<WebUIProvider>`.
-- An integration component throws on import → its optional peer dependency is not installed; check the component's
-  description in the docgen index (`imf-web-ui-components`) for which peer to add to `package.json`.

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

@@ -1,53 +0,0 @@
-# npm project
-
-The npm side of an ImFusion frontend: `package.json`, scripts, dependencies. `imf-web-ui-setup` audits against this file.
-
-## package.json
-
-```jsonc
-{
-  "name": "@imfusion/scan-review",
-  "type": "module",
-  "private": true, // only when the package is not meant to be published
-  "engines": { "node": ">=22" },
-  "imports": { "#/*": "./src/*" }
-}
-```
-
-- `"type": "module"` always.
-- `"private": true` only for apps that never publish.
-- Pin Node via `engines.node` or `.nvmrc` — never a personal version manager's config.
-- Wire the `#/` alias through `imports` ([project-structure.md](project-structure.md)).
-
-## Scripts
-
-Same name, same meaning, every repo — "what can I run to check this?" is tab-completing `verify:`.
-
-| Script             | Runs                                                                  |
-| ------------------ | --------------------------------------------------------------------- |
-| `dev`              | dev server                                                            |
-| `build`            | production build                                                      |
-| `verify:deps`      | exact-pin check over `dependencies` and `devDependencies`             |
-| `verify:format`    | `prettier --check .`                                                  |
-| `verify:lint`      | `eslint . --cache --max-warnings=0`                                   |
-| `verify:typecheck` | `tsc --noEmit` (or `tsc -b --noEmit` in a project-references setup)   |
-| `verify:tests`     | `vitest run`                                                          |
-| `verify:knip`      | `knip` — dead-code and unused-export check                            |
-| `verify:staged`    | staged-file subset, called by the pre-commit hook                     |
-| `verify:full`      | every `verify:*` check plus the build; what CI runs                   |
-| `format`           | `prettier --write .`                                                  |
-| `lint`             | `eslint . --cache --fix`                                              |
-| `git:config`       | see [git.md](git.md); run by hand once per clone, named in the README |
-
-- **Every check is `verify:*`** — one namespace for everything that reads and reports.
-- **Write-mode scripts keep the tool name** (`format`, `lint`): changing files isn't verifying — no prefix, no `:fix` suffix.
-- `verify:staged` is fast and partial: staged-file format/lint plus the relevant project-wide checks for staged source or
-  config changes, including `verify:knip` — a passing commit is not CI green.
-- `verify:full` is the CI gate.
-
-## Dependencies
-
-- **Pin exactly** — no `^`, `~`, or `latest`, in `dependencies` and `devDependencies` alike: `verify:deps` catches drift,
-  `save-exact=true` in `.npmrc` prevents it.
-- **`ignore-scripts=true` in `.npmrc`** — blocks lifecycle scripts on install (the supply-chain vector); setup that matters
-  is a command someone runs, not a hook that fires on install.

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

@@ -1,44 +0,0 @@
-# Project structure
-
-Kebab-case throughout, folders and files alike; exported symbols stay PascalCase — only the filename is kebab.
-
-## Layout
-
-```
-src/
-  main.tsx         # providers and router bootstrap; one WebUIProvider at the app root
-  routes/          # TanStack Router file-based routes; routing only — they compose, they don't fetch inline
-    __root.tsx     # document-wide error/not-found boundary and Outlet
-    _public/       # anonymous route group; resolves the current user when public pages need it
-      route.tsx
-    _app/          # pathless authenticated route group; guards the subtree before children render
-      route.tsx
-  api/             # one folder per API topic — layout and behaviour in data.md
-    auth/           # one current-user query plus server-owned login/logout URL helpers
-  components/      # grouped by kind — anatomy in components.md
-    app-shell/     # optional persistent authenticated chrome: brand, navigation, and session action
-  http/            # transport: client, error normalisation — the only transport-aware place (data.md)
-  lib/             # framework-free helpers, each with a colocated .test.ts when it has decisions to test
-    auth/
-      login-url.ts
-      login-url.test.ts
-```
-
-- Each subtree's rules live with its topic: [data.md](data.md) for `api/` and `http/`, [components.md](components.md) for
-  `components/`.
-
-## Application boundary
-
-- Start every frontend with the root providers, a current-user query, and pathless `_public/` and `_app/` route groups —
-  contract in [authentication.md](authentication.md); add feature routes only after that boundary exists.
-- Greenfield: `_app/` starts with a minimal `AppShell` — ImFusion logo, route navigation, and a stable session-action area
-  around the route `Outlet`.
-- Omit the shell only when the human explicitly says the product has no persistent authenticated navigation; the `_app/`
-  guard stays.
-- An established project preserves its working choice; public pages can use a small branded header instead.
-
-## Imports
-
-- `#/` alias for anything outside the current folder, plain `./` for siblings.
-- The alias is always `#/` → `src/`: `#` is Node's own subpath-import prefix, so it can't collide with an npm scope.
-- Wire it once, through `package.json`'s `imports` field (toolchain-native), with a matching tsconfig `paths` entry.