@imfusion/web-ui 0.6.1-dev.12.ge86ac0a1 → 0.6.1-dev.14.g8fac1dfb

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

@@ -1,207 +1,111 @@
 # 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.
+This topic defines the ImFusion pattern for TanStack Query and TanStack Router. Other data libraries keep the same boundary
+rules: validate external data at the edge and represent errors as values.
 
 ## 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.
+Use one folder per API topic:
 
 ```text
 src/
   api/
-    topics.ts        # one topic registry, reused by keys and namespaces
-    index.ts         # topic barrels composed as api.<topic>
+    topics.ts
+    index.ts
     <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
+      index.ts
+      keys.ts
+      queries.ts       # when the topic has queries
+      mutations.ts     # when it has mutations
+      types.ts         # schemas and inferred types
+      types.test.ts    # when schema rules encode behavior
+  http/                # transport and error normalization
+  lib/                 # framework-free shared helpers
 ```
 
+`keys.ts` owns query and mutation keys. Topic functions return options, not hooks or data. Keep transport code in `http/` and
+keep topic helpers out of the API folder when they are shared and framework-free.
+
 ## 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).
+The transport returns `unknown`. The topic schema parses it in the query or mutation function, and `z.infer` supplies the
+TypeScript type. A handwritten generic on `fetch` is not validation. See [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.
+Normalize failed requests into an `ApiError` with a machine-readable code. The UI maps the code to user-facing text instead
+of handling arbitrary thrown shapes at every call site.
 
 ## 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.
+Keep one registry of topic names. Use it for API namespaces and as the first segment of every query and mutation key:
 
 ```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>;
+type QueryKey<Topic extends ApiTopic> = readonly [Topic, ...ReadonlyArray<unknown>] | readonly [Topic];
 
 export function createApiKeys<
   Topic extends ApiTopic,
-  QueryKeys extends Record<string, QueryKey<Topic> | QueryKeyFactory<Topic>>,
+  QueryKeys extends Record<string, QueryKey<Topic> | ((...args: never[]) => QueryKey<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";
+Use the factory in each topic so every key starts with that topic:
 
+```ts
 export const keys = createApiKeys(API_TOPICS.USER, {
-  queries: { details: ["user", "details"], byId: (id: string) => ["user", "detail", id] },
-  mutations: { update: ["user", "update"] }
+  queries: {
+    details: [API_TOPICS.USER, "details"],
+    byId: (id: string) => [API_TOPICS.USER, "detail", id]
+  },
+  mutations: { update: [API_TOPICS.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;
-```
+Cross-topic invalidation can then use `keys.topic` instead of rebuilding a prefix by hand.
 
 ## 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).
+Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use bare verbs such as `update` or
+`delete`. Do not add a topic prefix or `Options` suffix; `context.api.user.getDetails()` already supplies the context.
 
-```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";
+A query factory owns its key and parsing:
 
-export function getDetails(args: { options?: Omit<QueryOptions<User>, "queryKey" | "queryFn"> } = {}) {
+```ts
+export function getDetails(options?: QueryOptions<User>) {
   return queryOptions({
-    ...args.options,
+    ...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
-  };
-}
-```
+Callers choose `ensureQueryData`, `useSuspenseQuery`, or another Query API.
 
 ## 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";
+Put the API object and `QueryClient` in router context. Loaders use `context.api.<topic>.<fn>()`; route components read the
+same context with `Route.useRouteContext()`. Direct imports are for plain utilities and tests outside the route tree.
 
-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
-});
+## Automatic invalidation
 
-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 })} />;
-}
-```
+Mutation keys start with the topic they change. The shared `MutationCache` invalidates that topic after success by default.
+Use `meta: { autoInvalidate: false }` for a mutation where a topic-wide refetch is wrong, then invalidate exact keys
+yourself.
 
-## Automatic invalidation
+For a related topic, add an explicit success handler that invalidates that topic's `keys.topic`.
 
-- 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).
+Configure the shared cache once, so the default applies to every mutation:
 
 ```ts
-// query-client.ts
 export function createQueryClient() {
   const queryClient = new QueryClient({
-    defaultOptions: {
-      mutations: { meta: { autoInvalidate: true } }
-    },
+    defaultOptions: { mutations: { meta: { autoInvalidate: true } } },
     mutationCache: new MutationCache({
       onSuccess: async (_data, _variables, _context, mutation) => {
         if (!mutation.meta?.autoInvalidate) return;
@@ -216,6 +120,6 @@ export function createQueryClient() {
 
 ## 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).
+Stub `fetch` at the transport boundary and run the real query client. Test schemas, transport normalization, and query
+options where they encode decisions. Schema cases belong beside the schema; the general test boundary is in
+[testing.md](testing.md).

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

@@ -1,40 +1,34 @@
 # Documentation structure
 
-What a repo documents, where, and how. `imf-web-ui-setup` scaffolds this shape from its `templates/` and audits it.
+Keep repository docs useful to a human who has just joined the project. The setup skill can propose the shape; the audit
+skill can check it.
 
 ## The shape
 
-```
+```text
 <app>/
-  README.md            # humans: what the app is, setup, scripts
-  AGENTS.md            # agents: tooling and architecture pointers into docs/ — restates nothing
+  README.md       # what the app is, setup, and scripts
+  AGENTS.md       # short pointers for agents
   docs/
-    index.md           # registers every doc with a one-line "covers" summary
-    <topic>.md         # repo-unique content only
+    index.md      # index of repo-specific docs
+    <topic>.md
 ```
 
 ## 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.
+If a rule should be true in every ImFusion frontend, keep it in the shipped conventions skill. Repo docs should explain local
+decisions and deviations. A deviation names the baseline, the local choice, and why it exists.
 
 ## 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.
+- Give each page one reader goal.
+- Use plain language and active verbs.
+- Explain a reason when it helps someone make the right choice.
+- Let code own changing facts such as scripts, types, token names, and config. Link to the source instead of copying it.
+- State the current situation. History belongs in commits and tickets.
+- Use examples that a reader could adapt, not placeholder prose.
 
 ## 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).
+When a change makes a doc inaccurate, update the doc in the same commit. The repository's commit workflow runs the staged
+docs audit; the check is advisory, but the correction belongs with the change.

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

@@ -1,34 +1,29 @@
 # Git
 
+Use the repository's tracked configuration and keep verification scopes clear.
+
 ## git:config
 
-- One script holds the repo's git configuration, run by hand once per clone (the README names it):
+Run once in a clone:
 
-```
-git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only
+```sh
+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.
+The hooks are tracked in `.githooks/`. Check both the Git setting and the directory; a missing hook path fails silently.
 
 ## Verify scopes
 
-Two scopes, both blocking:
+There are two scopes:
 
-- **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".
+- **staged**: `verify:staged`, run by pre-commit. It is fast and checks the staged files plus relevant project-wide checks.
+- **full**: `verify:full`, the build and complete verification used by CI.
 
-## Staleness at commit time
+The scripts under `scripts/verify/` own the step lists. Hooks and npm scripts only launch them.
 
-Pre-commit also runs the advisory staleness checks — warn, never block:
+## Staleness at commit time
 
-- **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.
+Pre-commit also runs advisory checks for vendored skill markers and documentation drift. If a staged change makes a doc
+stale, update the doc in the same commit. For an outdated installed skill, run `npx web-ui-install` in the consumer project.

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

@@ -1,35 +1,44 @@
 # Library boundary
 
-The contract between an app and `@imfusion/web-ui`.
+Keep the application behind `@imfusion/web-ui`. The library owns the public component API, implementation packages, and
+integration seams.
 
 ## 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.
-- Import icons from `@imfusion/web-ui/icons` and render them through its `Icon` component. Direct imports from
-  `iconoir-react` are outside the library boundary.
+- Do not import Base UI or another implementation package directly, including its stylesheet.
+- If Web UI is missing a component or part, report the gap instead of reaching around it.
+- Import glyphs from `@imfusion/web-ui/icons` and render them with `Icon`.
 
 ## 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.
+Create an app-level dumb wrapper when you repeat a default, composition, styling override, accessibility improvement, or API
+restriction. A wrapper that only renames a component adds indirection without helping.
 
-## Derive types, don't import them
+Derive its props from the primitive:
 
-- 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.
+```tsx
+type SaveButtonProps = React.ComponentProps<typeof Button> & {
+  busy?: boolean;
+};
+```
+
+Style the wrapper through tokens, your own classes, and the library's public data attributes. Do not target library CSS
+Module classes.
+
+An `experimental` primitive should be wrapped once before it is used throughout an app. That gives an API change one place to
+land.
+
+## Derive types, don't copy them
+
+The library intentionally does not export component `Props` interfaces. Use `React.ComponentProps<typeof Component>` and
+narrow or extend that type locally.
 
 ## 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.
+An integration under `@imfusion/web-ui/integrations/*` has an optional peer. Add that peer explicitly to the consumer's
+`package.json`; npm hoisting is not a dependency contract.
 
 ## 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).
+Use token overrides, your own classes, and `data-imf-ui-component` or state attributes. The complete CSS contract is in
+[styling.md](styling.md).

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

@@ -1,26 +1,30 @@
 # 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.
+Wire `@imfusion/web-ui` at the app entry point. The setup skill can propose a fix; the audit skill can check it.
 
 ## Entry-point wiring
 
-- Every consumer entry point has exactly two lines, in this order:
+Import the stylesheet before the components and mount `WebUIProvider` once around the app:
 
-  ```tsx
-  import "@imfusion/web-ui/styles.css";
-  import { WebUIProvider, Button } from "@imfusion/web-ui";
-  ```
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { Button, WebUIProvider } 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).
+export function App() {
+  return (
+    <WebUIProvider>
+      <Button>Save</Button>
+    </WebUIProvider>
+  );
+}
+```
+
+Components outside the provider do not receive the library's provider context. Keep upstream imports behind the library; see
+[library-boundary.md](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`.
+- Unstyled components usually mean the `styles.css` import is missing.
+- Wrong colors or unresolved variables usually mean the component is outside `WebUIProvider`.
+- An integration import error usually means its optional peer is missing. Check the component entry in
+  `imf-web-ui-components` for the package to install.

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

@@ -1,53 +1,39 @@
 # npm project
 
-The npm side of an ImFusion frontend: `package.json`, scripts, dependencies. `imf-web-ui-setup` audits against this file.
+Keep project metadata, scripts, and dependency policy in `package.json` and the lockfile.
 
 ## 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)).
+- Use ESM with `"type": "module"`.
+- Set the Node floor with `engines.node` or `.nvmrc`.
+- Use the `#/` source alias when the project has one, and wire it through the package `imports` field.
+- Set `private: true` only for packages that are never published.
 
 ## 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.
+Use the same names for the same checks where the project supports them:
+
+| Script             | Purpose                                 |
+| ------------------ | --------------------------------------- |
+| `dev`              | Start local development.                |
+| `build`            | Create a production build.              |
+| `verify:format`    | Check Prettier.                         |
+| `verify:lint`      | Check ESLint.                           |
+| `verify:typecheck` | Run TypeScript without emitting.        |
+| `verify:tests`     | Run tests once.                         |
+| `verify:knip`      | Check dead code and unused exports.     |
+| `verify:staged`    | Run the pre-commit scope.               |
+| `verify:full`      | Run the CI scope.                       |
+| `format`           | Rewrite formatting.                     |
+| `lint`             | Rewrite fixable lint issues.            |
+| `git:config`       | Apply the repository Git configuration. |
+
+Read the repository's actual `package.json` before running a command. A project may not have every script in the table.
 
 ## 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.
+Pin dependencies exactly. Avoid `^`, `~`, and `latest` in runtime and development dependencies. Set `save-exact=true` in
+`.npmrc` so new installs follow the same rule.
+
+Use `ignore-scripts=true` in `.npmrc` when the project relies on explicit setup commands rather than install-time lifecycle
+scripts.