@mediacubeco/expo-template-fsd 2.3.1 → 2.4.1

package/.claude/commands/git-commit.md

@@ -0,0 +1,164 @@
+---
+allowed-tools: "Bash(git branch --show-current)"
+---
+
+# Git Commit
+
+Creates git commits with proper messages and decomposes staged/unstaged changes into logical atomic commits.
+
+## Step 1: Understand the branch
+
+Current branch name:
+
+!`git branch --show-current`
+
+Derive the **prefix** from the branch name above in two steps:
+
+1. **Strip the workflow prefix** — drop any leading `feature/`, `fix/`, `chore/`, etc. by taking everything after the last `/`. E.g. `feature/CU-869dgtyz4` → `CU-869dgtyz4`.
+2. **Strip the author postfix** — the task identifier is `CU-` plus the single token right after it (e.g. `CU-869dgtyz4`). Drop any further `-<segment>` that follows it — that's a developer/author suffix, not part of the ID. E.g. `CU-869dgtyz4-sulumov` → `CU-869dgtyz4`, and `feature/CU-869dgtyz4-sulumov` → `CU-869dgtyz4`.
+
+Use that identifier as `{prefix}` everywhere below. If the branch has no task identifier (e.g., `main`, `develop`), commit without a prefix.
+
+## Step 2: Analyze all changes
+
+Run these together to get the full picture:
+
+```bash
+git status
+git diff HEAD
+git diff --cached
+```
+
+Read the actual diff carefully — don't just look at filenames. You need to understand _what_ each change does, not just _where_ it is, to group things correctly.
+
+## Step 3: Decompose into logical commits
+
+This is the most important step. Think like a reviewer who will read this history in six months: they want the **fewest commits that still tell the story clearly** — each one a coherent, self-contained change they could review or revert on its own.
+
+**Each commit should be one coherent unit of work — a whole change that stands on its own.** Default to **grouping, not splitting**: a feature and everything that exists only to serve it (its types, styles, hook, shared helper — across whatever FSD layers it touches) is normally **one** commit, not one per file or per layer.
+
+Good decomposition principles:
+
+- **Group by unit of work, not by file or by layer** — a feature that touches `shared` + `entities` + `features` + `pages` is usually **one** commit when those changes only exist to make that one feature work. Crossing an FSD layer boundary is _not_ by itself a reason to split.
+- **Split only when the pieces are genuinely independent** — two changes deserve separate commits when each stands on its own: it could be reviewed, reverted, or shipped without the other. If pulling them apart leaves either half meaningless or broken, keep them together.
+- **Truly reusable infrastructure can stand alone** — a shared component/util that multiple _unrelated_ consumers will use is worth its own commit. But a "shared" piece written specifically for one feature in this same batch goes _with_ that feature, not on its own.
+- **Config/tooling separate from features** — `eslint`, `tsconfig`, `package.json`, `.env` changes are their own commit, unless they were added specifically to enable a single feature that's in the same batch.
+- **Refactoring separate from new behavior** — a real refactor (extracting, renaming, restructuring) is its own commit. Don't over-apply this to trivial incidental tidy-ups that ride along with the feature.
+- **Unrelated changes never share a commit** — separate concerns that merely happened in the same session go in separate commits.
+
+As a rough gauge: most batches decompose into **1–4 commits**. If you're planning many more, you're almost certainly splitting by file or by layer instead of by unit of work — regroup. A big feature can legitimately be a big commit; size alone is never the reason to split.
+
+Common anti-patterns to avoid:
+
+- **One giant "various fixes" commit** — decompose it into its distinct units of work.
+- **Death by a thousand commits** — splitting one coherent change into a commit per file, per FSD layer, or per type definition. If a reviewer must read three commits to understand one feature, you split too far.
+- **Splitting one logical unit across commits** — e.g. a component in one commit and its required types/styles/hook in another.
+- **Committing unrelated files together** just because they were modified in the same session.
+
+After analyzing, produce a decomposition plan like this (show it mentally, then execute without asking for confirmation unless the decomposition is genuinely ambiguous):
+
+```
+Commit 1: {prefix} - add user API layer (entity, resource, repository)
+  → src/shared/lib/api/entities/user.ts
+  → src/shared/lib/api/resources/user.ts
+  → src/shared/lib/api/models/user-repository.ts
+  → src/shared/lib/api/api.ts (registration)
+
+Commit 2: {prefix} - add profile screen with user data fetching
+  → src/pages/profile/
+  → src/features/profile/
+```
+
+Two commits, not five: the whole API layer is one unit of work (don't split entity from resource from repository), and the screen that consumes it is another. Had the API layer been built solely for this one screen and used nowhere else, folding both into a single commit would be fine too.
+
+The plan above lists subjects only. When you execute each commit (Step 4), also write its Russian body — see [Commit message format](#commit-message-format).
+
+## Step 4: Stage and commit each group
+
+For each commit in the plan, stage exactly the relevant files and commit:
+
+```bash
+# Stage specific files (never use git add . or git add -A)
+git add <specific files>
+
+# Commit: English subject as the first -m, Russian body as the second -m
+git commit -m "{prefix} - add UserEntity and UserResource types" -m "- Добавлены сущность UserEntity и ресурс UserResource
+- Поля приведены к camelCase с безопасными дефолтами"
+```
+
+Repeat for each commit in the plan.
+
+If a single file contains changes that belong to different logical commits (mixed concerns in one file), use `git add -p` to stage only the relevant hunks:
+
+```bash
+git add -p src/shared/lib/api/api.ts
+```
+
+## Commit message format
+
+Every commit has two parts: a one-line **subject** in English, and a multi-line **body** in Russian.
+
+### Subject — English
+
+```
+{prefix} - short imperative description
+```
+
+Rules:
+
+- Start with `{prefix}` — the identifier from Step 1
+- Follow with `-` then the message
+- Use imperative mood: "add", "fix", "remove", "update", "extract" — not "added", "adding", "fixes"
+- Be specific: "add UserEntity with profile fields" beats "add user types"
+- Keep it under 72 characters total
+- No period at the end
+
+| Situation            | Subject                                               |
+| -------------------- | ----------------------------------------------------- |
+| New API types        | `{prefix} - add OrderResource and OrderEntity`        |
+| New screen           | `{prefix} - add checkout screen with order summary`   |
+| Bug fix              | `{prefix} - fix token refresh on 401 response`        |
+| Config change        | `{prefix} - add react-query persistence config`       |
+| Refactor             | `{prefix} - extract AuthHeader into shared component` |
+| Multiple small fixes | `{prefix} - fix navigation types and screen params`   |
+
+### Body — Russian
+
+The body explains, **in Russian**, what this commit actually changed — enough that reading the commit alone makes the change clear, without opening the diff. The subject stays English; only the body is Russian.
+
+Write it as a short bullet list, one bullet per meaningful change in **this** commit:
+
+- Each bullet is a concrete thing that was done or reworked, in past tense ("Добавлен…", "Вынесен…", "Исправлен…", "Переименован…").
+- Group by what changed, not file-by-file.
+- По делу: skip filler, don't restate the subject, don't narrate the obvious ("обновлён код", "внесены правки").
+- 1–5 bullets for a typical commit. A trivial commit may be a single bullet — don't pad it; a large one shouldn't turn into an essay.
+
+**Full example:**
+
+```
+CU-869dgtyz4 - add user API layer
+
+- Добавлены сущность UserEntity и ресурс UserResource с полями профиля
+- Поля приведены к camelCase с безопасными дефолтами
+- UserRepository зарегистрирован в Api singleton
+```
+
+## Step 5: Verify
+
+After all commits are done:
+
+```bash
+git log --oneline -10
+```
+
+Each commit should read cleanly as a standalone unit of work. If two adjacent commits feel like they should be one, or one commit feels like it should be two — that's worth noting but not worth amending if already done.
+
+## Edge cases
+
+**Nothing staged, nothing to commit** — say so and stop. Don't create empty commits.
+
+**Only whitespace / formatting changes** — still a valid commit: subject `{prefix} - format auth module`, body e.g. `- Прогнан prettier по модулю auth`.
+
+**Single logical change across many files** — fine, that's one commit. Stage all the files together.
+
+**Uncertain decomposition** — if you genuinely cannot tell whether two changes are the same logical unit, keep them together. Atomic is better than artificially split.

package/.claude/rules/architecture.md

@@ -0,0 +1,38 @@
+# Architecture guardrails: `src/app` and `src/shared`
+
+`src/app` and `src/shared` are the two most sensitive layers of the codebase —
+every screen and every slice depends on them. They are kept in full cleanliness,
+and changes there are never routine.
+
+## Be extremely careful — and ask first
+
+Before **adding or changing anything** in `src/app` or `src/shared` (a new
+shared component, a new dependency, a new provider, a new util, a change to an
+existing shared API), **always ask the user first**. Describe what you want to
+add, where, and why it belongs on that layer. This holds even when the change
+seems obviously useful — the cost of a wrong abstraction on these layers is
+paid by the whole app.
+
+- `src/app` stays maximally empty: route wiring only (see the code-style
+  skill, section "Routes"). No business logic, no state, no extra
+  dependencies.
+- `src/shared` holds only genuinely reusable, business-agnostic code. A
+  component or helper needed by one feature belongs to that feature's slice,
+  not to `src/shared`.
+
+## Watch for degradation — and speak up
+
+Whenever you notice these layers drifting in a bad direction — while editing,
+reviewing, or just reading nearby code — **point it out proactively and
+propose a fix**, even if it is outside the current task:
+
+- logic or new dependencies accumulating in `src/app` (providers gaining
+  business code, route files growing beyond thin wrappers, boot logic
+  spreading);
+- unclear or single-consumer components appearing in `src/shared/ui`,
+  duplicated helpers in `src/shared`, business knowledge leaking into the
+  shared layer.
+
+Flag the problem, explain why it violates the layer's contract, and suggest
+where the code should live instead. Keeping these two layers clean matters
+more than the convenience of any single change.

package/.claude/rules/{prettier-eslint-typescript.mdc → prettier-eslint-typescript.md}

@@ -1,24 +1,19 @@
----
-description: All code must satisfy Prettier, ESLint, and TypeScript for this project
-alwaysApply: true
----
-
 # Prettier, ESLint, and TypeScript
 
 Every change you produce must align with the project toolchain: **Prettier** (`prettier.config.js`), **ESLint** (`eslint.config.js`), and **TypeScript** (`tsconfig.json` and extended configs).
 
 ## Expectations
 
-- **Prettier**: formatting, line breaks, and import/style choices must match what Prettier would produce for this repo (run `npm format` or format-on-save with the same config).
+- **Prettier**: formatting, line breaks, and import/style choices must match what Prettier would produce for this repo (run `npm run format` or format-on-save with the same config).
 - **ESLint**: no new violations of project rules; fix issues instead of widening ignores. Avoid blanket `eslint-disable` unless there is a documented, narrow reason.
-- **TypeScript**: valid types, no errors under `npm type` (`tsc`). Do not paper over problems with `any`, unchecked casts, or `@ts-expect-error` / `@ts-ignore` unless unavoidable and explained in place.
+- **TypeScript**: valid types, no errors under `npm run type` (`tsc`). Do not paper over problems with `any`, unchecked casts, or `@ts-expect-error` / `@ts-ignore` unless unavoidable and explained in place.
 
 ## Verification
 
 After substantive edits, prefer that the tree would pass:
 
-- `npm format`
-- `npm lint`
-- `npm type`
+- `npm run format`
+- `npm run lint`
+- `npm run type`
 
 If a constraint from the configs conflicts with another instruction, follow the stricter requirement or resolve the conflict explicitly in code without disabling tools by default.

package/.claude/settings.json

@@ -1,8 +1,8 @@
 {
   "enabledPlugins": {
-    "gitlab@claude-plugins-official": true,
+    "gitlab@claude-plugins-official": false,
 
-    "superpowers@claude-plugins-official": true,
+    "superpowers@claude-plugins-official": false,
 
     "expo@claude-plugins-official": true,
     "code-review@claude-plugins-official": true,

package/.claude/skills/api/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: api
+description: >-
+  Generates and edits the project's shared API layer end to end — Resource types
+  and Entity classes from backend JSON, repository classes over ApiInstance,
+  TanStack Query option factories (queries/), useQuery/useMutation hooks, and
+  mock fixtures. Use this skill whenever the user works on the API/data layer:
+  "add an API for ...", "model this backend JSON", "create an entity/resource",
+  "add a repository", "generate query hooks", "connect this endpoint to React",
+  "add a mutation", "make mocks for ...", or adds/edits anything under
+  resources/, entities/, repositories/, queries/, hooks/. Also use when wiring a
+  new domain into the shared api lib or when reviewing API-layer code for
+  correctness. Prefer this skill over hand-rolling fetch calls, query keys, or
+  TanStack Query wiring.
+---
+
+# API layer
+
+This skill generates the project's shared API layer so every domain looks like
+one hand wrote it. General conventions (naming, exports at end of file,
+async/await, file casing, barrels) come from the **code-style** skill — follow it
+for everything; this skill only adds the API-specific architecture on top.
+
+## The architecture in one picture
+
+Data flows through fixed layers. Get the **direction of transformation** right —
+it is the thing most often done wrong:
+
+```
+backend JSON  →  Resource (wire shape, optional fields, snake_case)
+                   ↓  consumed by
+                 Entity (class, camelCase, safe defaults)   ← lives in the HOOK's select
+repository      →  returns the RAW server response, unchanged ( e.g. { data?: Resource[] } — plain, snake_case )
+queries/        →  queryOptions + query-key factory           ( key + queryFn + staleTime + meta )
+hooks/          →  useQuery({ ...queries.x(), select })        ← select SHAPES { list }/{ item } + maps → entities
+```
+
+**Why the cache holds raw plain responses and entities live in `select`:** the
+cache stores exactly what the repository returns. TanStack Query's structural
+sharing preserves references only for plain objects/arrays — class instances break
+it, so caching entities causes a new reference on every refetch and re-renders
+everything. Plain responses also serialize cleanly for persistence. `select` is
+memoized by TanStack Query and only re-runs when the raw data actually changes, so
+the consumer-facing shape (`{ list }`/`{ item }`) and the entity instances are
+derived exactly when needed. **Never** return entities or a reshaped `{ list }`/
+`{ item }` from a repository, and never build entities in `queryFn` — the
+repository is a thin pass-through of the wire payload; all shaping happens in
+`select`.
+
+Read `references/client/overview.md` once — it explains the shared machine
+(transport options, centralized `onError`, typed `meta`, persistence, retry) that
+every domain plugs into.
+
+## Generation order
+
+A full domain is built bottom-up. Each step has authoritative reference files —
+read them before writing, they are the source of truth for shape and style:
+
+| Step | Produces | References |
+| ---- | -------- | ---------- |
+| 1. Model | `resources/<domain>/`, `entities/<domain>/` | `references/model/` |
+| 2. Repository | `repositories/<domain>/` (`.ts`, `.types.ts`, `index.ts`) | `references/repository/post/` |
+| 3. Queries | `queries/<domain>.ts` | `references/queries/post.ts` |
+| 4. Hooks | `hooks/use-api-<domain>(s).ts`, mutation hooks | `references/hooks/` |
+| 5. Mock (on request) | fixtures next to the domain or in the project's mocks dir | `references/mock/post.mock.ts` |
+
+Then wire the domain into shared files (see "Wiring a new domain" below).
+
+Do only the steps the user asked for. "Add hooks for X" assumes the model and
+repository exist — if they don't, say so and offer to generate them first, in
+order. Never invent a domain name; if the root object's name is unclear, ask.
+
+### Decide first: full model or map-case?
+
+Not every endpoint deserves a Resource + Entity. Decide before Step 1:
+
+- **Full model (Resource + Entity)** — for a real domain object: something reusable,
+  with an identity/lifecycle, or a structural object nested inside another (a country,
+  a payment method, a translation, a shared stored file…). It gets `resources/<domain>/`
+  + `entities/<domain>/` (Step 1) and its `select` wraps in the Entity.
+- **Map-case (no Resource/Entity)** — for a short, flat, single-endpoint payload with no
+  domain identity (a status/feature-flags/health-style response). Skip Step 1 entirely:
+  the only type is `<Op>Response` (snake_case) in the repository's `.types.ts`, and the
+  hook's `select` renames it into a camelCase plain object inline. See the `health`
+  reference (`references/repository/health/`, `references/hooks/use-api-health.ts`).
+
+When in doubt, prefer a full model — but don't manufacture an Entity for a one-off flag
+bag just to follow the pattern.
+
+## Step 1 — Model (Resource + Entity)
+
+Follow `references/model/`. Core rules:
+
+- **Resource** mirrors the wire format exactly — copy backend keys verbatim
+  (snake_case stays snake_case), every field optional (`?`), extends
+  `BaseResource`. Never add `id`/`created_at`/`updated_at`/`is_skeleton` (inherited).
+  Express optionality with `?` alone — don't also union `| null`; a `?` field is
+  already absent-or-value, and the Entity default handles `null` and `undefined` the
+  same way.
+- **Entity** is a class extending `BaseEntity<Resource>`, every property
+  camelCase with a safe default. Apply the semantic renames:
+  - dates end in `at` (`publish_date → publishedAt`),
+  - arrays end in `List` (`comments → commentList`),
+  - booleans start with `is/has/did/can/should/was/will`.
+- Defaults: `string → ''`, `number → 0`, `boolean → false`, `Date → new Date()`,
+  nested entity → `new ChildEntity(resource?.field, this)`, array → `[]`.
+- **Every object goes through the model: one object = one Resource + one Entity, each
+  in its own file — reused, never inlined, never duplicated.** A nested object is never
+  written inline in its parent; it gets its own files in the parent's folder named
+  `<parent>-<child>.ts` (e.g. `label-translation.ts` under both `resources/label/` and
+  `entities/label/`) and is re-exported from that folder's barrel. The parent **Resource**
+  references the child Resource type; the parent **Entity** wraps it through the child
+  Entity (`new ChildEntity(resource?.field, this)`, arrays via `.map(...)`) and exposes the
+  Entity — never a raw nested resource. An object used in more than one place — its own
+  endpoint **and** embedded elsewhere (e.g. a stored file returned standalone *and* nested
+  under a label) — is **shared**: lift it to its own top-level `resources/<name>/` +
+  `entities/<name>/` folder and import it everywhere (response types included). If you
+  catch the same fields written twice, stop and extract — and since `BaseResource` already
+  supplies `id`/`created_at`/`updated_at`, a re-declared inline shape is a correctness bug
+  too. See `references/model/` (`post`/`user`) for the file-per-object layout.
+- Dependency direction is **entities → resources only**; string enums are union
+  types, never `enum`.
+
+For the full case-conversion table and nested/multi-file examples, read
+`references/model/` (resources + entities for `post`/`user`).
+
+## Step 2 — Repository
+
+Follow `references/repository/post/`. Core rules:
+
+- The class extends `ApiInstance`; methods call `this.get/post/put/patch/delete`.
+- **Return the raw server response unchanged** — `return await this.get<...ApiResponse>(...)`.
+  Do not unwrap envelopes or reshape into `{ list }`/`{ item }`, and never construct
+  entities here: that is the hook's `select` job, so the cache holds the plain wire
+  payload (typically `{ data?: Resource[] }` for a list, the flat object for a
+  singleton). The repository's *only* transformation is request-side (see next bullet).
+- **The repository is the only camelCase ↔ snake_case boundary.** Destructure the
+  explicit camelCase fields plus `options` from the config, then build `params`/`body`
+  by hand, mapping each key to its snake_case wire name — so `options` never leaks into
+  the URL/body and the wire shape is written in exactly one place:
+  `async getXList({ isActive, options }: GetXListApiConfig)` then
+  `this.get('/', { params: { is_active: isActive }, options })`. Writes mirror it:
+  `async createX({ title, options }: CreateXApiConfig)` then
+  `this.post('/', { body: { title }, options })`. No automatic key transform lives in
+  the transport — keep it explicit per method.
+- No `try/catch` — errors propagate to the centralized `onError`.
+- Mark each method `// auth` or `// no auth`.
+
+### Types file (`<domain>.types.ts`)
+
+- Bare types first, then `// config` and `// response` sections (the `Api*` wrappers).
+- **Four types per operation**, following `references/repository/post/post.types.ts`:
+  - `<Op>Config` — the bare request fields in **camelCase** (`{}` when the endpoint
+    takes none). This is the public type the query factory consumes.
+  - `<Op>Response` — the bare response in **snake_case**, mirroring the server's wire
+    shape (a list is typically enveloped as `{ data?: Resource[] }`; a singleton/map is
+    the flat object). This is the type the hook's `select` consumes.
+  - `<Op>ApiConfig = ApiConfig<<Op>Config>` — adds `options?`; the method's parameter type.
+  - `<Op>ApiResponse = ApiResponse<<Op>Response>` — the method's return type.
+- Base wrappers live in `api.types.ts`: `ApiConfig<C> = C & { options? }`,
+  `ApiResponse<R> = R`. ID fields use `Entity['id']`, not plain `string`.
+- **The barrel (`index.ts`) re-exports the repository class plus both bare types —
+  `<Op>Config` and `<Op>Response`.** The query factory imports `<Op>Config`; the hook
+  imports `<Op>Response` to type its `select`/`placeholderData`. The `Api*` wrappers stay
+  internal to the repository (imported over the relative `<domain>.types` path).
+
+### Method naming
+
+Every method returns the raw `<Op>ApiResponse` (or nothing). The consumer-facing
+`{ list }`/`{ item }` shape is produced later by the hook's `select`, not here.
+
+| Verb | Method | Returns (raw wire payload) |
+| ---- | ------ | -------------------------- |
+| GET list | `get<Domain>List` | `{ data?: Resource[] }` |
+| GET one | `get<Domain>` | `{ data?: Resource }` |
+| POST | `create<Domain>` | `{ data?: Resource }` or nothing |
+| PUT/PATCH | `update<Domain>` | `{ data?: Resource }` or nothing |
+| DELETE | `delete<Domain>` | nothing |
+
+## Step 3 — Queries
+
+Follow `references/queries/post.ts`. Each domain exports one `<domain>Queries`
+object — the query-key factory plus `queryOptions` builders:
+
+- `key` — the base key array, built from `QUERY_KEYS.<DOMAIN>`. Used for
+  invalidation (`invalidateQueries({ queryKey: postQueries.key })`).
+- One builder per read endpoint, named for the read it does — `list` for a
+  collection, `detail` for a single object (pass an id for a by-id endpoint, or call
+  it with no args for a sole-instance/singleton endpoint). Each returns
+  `queryOptions({ queryKey, queryFn, … })`.
+- A read builder takes the bare `<Op>Config` (`config: GetXListConfig = {}`) and
+  **puts it in the key** — `[...key, config]` for a filtered list, `[...key, id]` for a
+  detail (a singleton's key is just `key`). Different params must not share a cache entry.
+- `queryFn: (options) => Api.<domain>Repository.method({ ...config, options })` — the
+  whole TanStack Query context is forwarded as `options`; it carries the `signal`, so
+  unmounts/invalidations cancel in-flight `fetch`es.
+- Add `staleTime: STALE_TIME` and `meta: { persist: true }` **only** for
+  slow-changing reference data. Omit both for always-fresh or user-specific data.
+
+`queryOptions` is what lets the same definition feed `useQuery`, `prefetchQuery`,
+and `queryClient.setQueryData` with full type inference — never inline the
+queryKey/queryFn in the hook.
+
+## Step 4 — Hooks
+
+Follow `references/hooks/`. Hooks are thin and own only the presentation concern
+(`select` → shape + camelCase/entities, placeholder skeleton):
+
+- **One hook per endpoint/operation — never a facade hook that bundles several
+  operations.** A hook wraps exactly one `useQuery` or one `useMutation` and (for
+  mutations) returns it directly. Don't return `{ create, update, remove }` or several
+  mutations from one hook: it forces every consumer to instantiate operations it doesn't
+  use and defeats per-call `select`/options.
+- **Hooks are always prefixed `useApi` and named `useApi<Domain><Operation>`** — reads
+  `useApi<Domain>` / `useApi<Domain>List`; writes `useApi<Domain><Op>` (e.g.
+  `useApiPostCreate`, `useApiPostUpdate`). A domain's operation hooks are **grouped in its
+  `use-api-<domain>(s).ts` file**, each exported separately — never split one operation per
+  file. A domain with three write endpoints exports three hooks from `use-api-<domain>.ts`
+  (e.g. `use-api-oauth.ts` exporting `useApiOauthAuth`, `useApiOauthLink`,
+  `useApiOauthCheck`), not one hook returning three mutations and not three separate files.
+- **Every read hook MUST run its result through `select` — no exceptions, including
+  single-value / "simple" endpoints.** The cache holds the raw snake_case wire payload;
+  the consumer must only ever see a **camelCase `{ item }` / `{ list }`**. A `useQuery`
+  without `select` leaks snake_case to the UI — that is a bug. `select` does **both jobs
+  the repository deliberately skipped**: it shapes the payload into `{ list }`/`{ item }`
+  **and** converts to camelCase. There are two flavors:
+  - **Entity-domain** — wrap each resource in its Entity, unwrapping the envelope:
+    `{ list: data.data?.map((post) => new PostEntity(post)) ?? [] }` for a list,
+    `{ item: new PostEntity(data.data) }` for a single object.
+  - **Map-case (no Entity)** — for a short flat endpoint with no domain identity (a
+    status/flags/health-style payload), there is no Resource/Entity; `select` just renames
+    fields into a camelCase plain object: `{ item: { startAt: data.start_at } }`. See
+    `references/hooks/use-api-health.ts`.
+- Read query: `useQuery({ ...postQueries.list(), placeholderData: PLACEHOLDER_DATA, select: selectPostList })`.
+  **`placeholderData` is mandatory on every read hook — lists, single objects, and
+  map-cases alike, not just lists.** Its job is not only the skeleton: it guarantees the
+  query always holds data in the wire shape, so `select` always runs it through the Entity
+  (or the map-case rename) and the consumer always receives a fully-defaulted
+  `{ item }` / `{ list }` instead of `undefined` during load. That means callers read
+  `data.item` / `data.list` directly — never `data?.item`, never a manual default. Both
+  `placeholderData` and `select` are required; neither is ever omitted.
+- **`select` is a module-level function** (stable reference). Never inline it — an inline
+  `select` re-runs every render and, because entities break structural sharing, causes
+  constant re-renders.
+- The `select` input type is the bare **`<Op>Response`** imported from the repositories
+  barrel (`import { type GetPostListResponse } from '../repositories'`) — this is what
+  the cache holds. (That is why the barrel exports `<Op>Response`.)
+- `PLACEHOLDER_DATA` is a module-level constant typed as that same `<Op>Response`, holding
+  **plain default data in the wire shape** — never entities. Its exact shape follows the
+  endpoint:
+  - **list** — a few skeleton items: `{ data: [{ is_skeleton: true }, …] }`;
+  - **single object** — one skeleton resource: `{ data: { is_skeleton: true } }`;
+  - **map-case** — the flat wire object with default field values (`{}` when every field
+    is optional).
+
+  `select` runs it through the Entity (or the map-case rename), so before the server
+  answers the consumer already has a default entity with `isPending: true` and safe
+  defaults. Use `placeholderData`, not `initialData`.
+
+### Which hook for which endpoint
+
+| Endpoint | Hook |
+| -------- | ---- |
+| List / single fetched on mount | `useQuery` (+ `select`) |
+| Create / update / delete | `useMutation` |
+
+One row = one hook. A domain with three write endpoints gets three hooks —
+`useApi<Domain><Op>` each, all grouped in `use-api-<domain>.ts` — never one hook returning
+three mutations.
+
+Default mutations invalidate on settle (see `useApiPostCreate` in
+`references/hooks/use-api-post.ts`):
+`onSettled: () => queryClient.invalidateQueries({ queryKey: postQueries.key })`,
+with `queryClient` imported from `../api.client`.
+
+#### Mutations that return data the caller uses — map in `mutationFn`
+
+`useMutation` has **no `select`** (that's a `useQuery` option). So when a mutation's
+response carries data the caller reads from `mutation.data` (not just fire-and-invalidate),
+do the **same mapping a query `select` does, inside `mutationFn`** — the repository still
+returns the raw `<Op>Response`; the hook awaits it and runs it through a module-level
+mapping function before returning:
+
+```ts
+// module-level — the mutation analog of a query `select`: shape to { item } / { list }
+// and snake_case → camelCase (Entity-wrap a modelled domain, plain camelCase for a map-case)
+const selectPostCreate = (data: CreatePostResponse) => {
+  return { item: new PostEntity(data.data) }
+}
+
+const useApiPostCreate = () => {
+  return useMutation({
+    mutationFn: async (config: CreatePostConfig) =>
+      selectPostCreate(await Api.postRepository.createPost(config)),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: postQueries.key }),
+  })
+}
+```
+
+One shared mapping function can serve all of a domain's mutation hooks. The rule "build
+entities/shape only in `select`, never in the repository" holds — for mutations the
+`mutationFn` is where that mapping runs; the repository stays a raw pass-through.
+
+### Optimistic mutations (when instant feedback matters)
+
+Add `onMutate`/`onError` around the default:
+
+1. `await queryClient.cancelQueries({ queryKey: postQueries.key })` — stop
+   in-flight refetches from overwriting the optimistic state.
+2. Snapshot: `const previous = queryClient.getQueryData(postQueries.list().queryKey)`.
+3. Write optimistically with `setQueryData` — **into the raw wire shape the cache
+   holds** (`{ data?: PostResource[] }`), not the `{ list }`/entity shape; `select`
+   re-derives the shaped entities on read. Return `{ previous }`.
+4. `onError` rolls back: `setQueryData(postQueries.list().queryKey, context?.previous)`.
+5. `onSettled` invalidates to reconcile with the server.
+
+Use `meta: { silent: true }` on a mutation whose error you handle locally, so the
+global `onError` stays quiet.
+
+## Step 5 — Mock (on request)
+
+Follow `references/mock/post.mock.ts`. Fixtures use **wire-format (Resource) field
+names**, returned as deep clones; an entity helper round-trips them through the
+Entity class the way production does. Reuse an existing `mock`/`fixtures` dir; ask
+before inventing a new root.
+
+## Wiring a new domain into shared files
+
+After generating the domain, update (see `references/client/overview.md` for the
+full picture):
+
+1. `api.ts` — `static <domain>Repository = new <Domain>Repository('/<domain>s')`.
+2. `constants/index.ts` — add `<DOMAIN>S: '<domain>s'` to `QUERY_KEYS`.
+3. Barrels — one alphabetical re-export line in each of `resources/index.ts`,
+   `entities/index.ts`, `repositories/index.ts`, `queries/index.ts`, `hooks/index.ts`.
+4. Prefetch (optional) — reference data shown on first screens gets a
+   `queryClient.prefetchQuery(<domain>Queries.list())` in the startup prefetch.
+
+## Verify
+
+After generating, the tree must pass `npm run type`, `npm run lint`, and
+`npm run format` cleanly (per the prettier-eslint-typescript rule). A common miss:
+forgetting a barrel export, or leaving `options` un-destructured in a repository
+method.
+
+## Checklist before finishing
+
+- [ ] Resource fields match the backend wire format exactly; all optional
+- [ ] Entity is camelCase with defaults; dates end `at`, arrays end `List`, booleans prefixed
+- [ ] Every distinct/nested/shared object has its own Resource+Entity **in its own file**, reused and wrapped through its Entity in the parent — no inline/raw nested shapes, no duplicates
+- [ ] Repository returns the **raw wire response** unchanged — no `{ list }`/`{ item }` reshaping, no entities, no try/catch
+- [ ] Repository maps camelCase → snake_case by hand into `params`/`body`, keeping `options` separate
+- [ ] Per-op types `<Op>Config` (bare camelCase) / `<Op>Response` (bare snake_case wire shape) / `<Op>ApiConfig` / `<Op>ApiResponse`; IDs use `Entity['id']`; barrel exports the bare `<Op>Config` **and** `<Op>Response`
+- [ ] `queries/<domain>.ts` exports `<domain>Queries` with `key` + `list`/`detail` builders; key includes `config`; `queryFn` forwards the context as `options` (`{ ...config, options }`)
+- [ ] `staleTime: STALE_TIME` / `meta.persist` set only for reference data
+- [ ] One hook per endpoint/operation, prefixed `useApi<Domain><Operation>`, all grouped in `use-api-<domain>.ts`; no facade hook returning multiple mutations, no one-operation-per-file split
+- [ ] **Every** read hook runs through a module-level `select` that both shapes `{ list }`/`{ item }` and converts to camelCase — Entity-wrap for domains, plain camelCase object for map-cases (no `useQuery` without `select`)
+- [ ] **Every** read hook passes `placeholderData` (list, single, and map-case alike) so `select` always runs and the consumer always gets a defaulted `{ item }`/`{ list }`, never `undefined`
+- [ ] `select` input typed as the bare `<Op>Response` from the repositories barrel; entities built only in `select`, never in repository or `queryFn`
+- [ ] Mutation whose `mutation.data` is consumed maps the raw response inside `mutationFn` (the `useMutation` analog of `select`, since there is no `select` option); repository stays raw
+- [ ] Shared files wired: `api.ts`, `QUERY_KEYS`, all barrels
+- [ ] `npm run type` / `lint` / `format` clean