frontend phase 0: app shells, design system & data/contract patterns

Turn the starter into the Balinyaar foundation for the three actor
experiences and lock in the patterns later phases copy.

- Cleanup: remove toastDemo namespace, placeholder home page, and the two
  dead icons; fix BottomBar to use usePathname (locale-aware active tab).
- Three actor shells under (private-routes), no layout above [locale]:
  customer (customer) group with the 5-tab bottom nav; nurse (/nurse) and
  admin (/admin) on the shared sidebar engine. Role model via constants/roles
  + useActorRole (defaults to customer until roles land in f1-b2).
- services/{domain} reference (patients) with a mock behind a config seam,
  hierarchical query keys, deliberate staleTime, and mutation invalidation;
  shared ApiEnvelope/Paginated wire types + unwrap() in lib/api/types.
- Money (integer-safe IRR/Toman) + Shamsi-date utils; toEnglishDigits helper.
- Shared composites, each tested: OtpInput, PhoneNumberField, StepperHeader,
  StatusChip, PlaceholderScreen.
- i18n: seed nav/common/shell/patients in both locales; document namespace
  conventions. Update client/CLAUDE.md Project Structure + fix ColorSchemeScript
  doc drift. Add phase report, STATUS, and REQ-001 (envelope/casing/pagination).

Gate: npm run check + test:ci green (72 tests); build green with NEXT_PUBLIC_API_URL.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

dev/shared-working-context/frontend/STATUS.md

@@ -12,4 +12,17 @@ for awareness.
 - **Requests filed:** frontend/requests/for-backend.md (yes/no)
 -->
 
-_(no phases completed yet)_
+## frontend-phase-0 — Foundations: app shells, design system & data/contract patterns — 2026-07-02
+- **Shipped:** 3 actor shells (customer bottom-nav / nurse / admin sidebar) + role-aware routing under
+  `(private-routes)`; `useActorRole`; the `services/{domain}` reference (`patients`, mocked behind a
+  seam) with deliberate Query caching + invalidation; `lib/api/types.ts` (envelope/pagination); money +
+  Shamsi-date utils; shared composites `OtpInput`/`PhoneNumberField`/`StepperHeader`/`StatusChip`/
+  `PlaceholderScreen` (each tested); i18n `nav`/`common`/`shell`/`patients` in both locales. Removed the
+  demo scaffolding; fixed the `BottomBar` pathname bug.
+- **Consumes:** dev/contracts/conventions/* + openapi/swagger.v1.json (b0 = ping only). No feature
+  contract consumed yet.
+- **Mocked client-side:** `services/patients` via `patientsMockApi` (USE_PATIENTS_MOCK=true) — template
+  for f1+. Swap is one line once real endpoints land.
+- **Gate:** npm run check green · npm run test:ci green (72 tests) · npm run build green with
+  NEXT_PUBLIC_API_URL set.
+- **Requests filed:** frontend/requests/for-backend.md — yes (REQ-001).

dev/shared-working-context/frontend/requests/for-backend.md

@@ -12,4 +12,21 @@ delivers fixes in its own change. **Frontend never edits backend code to "fix" a
 - **Status:** open | delivered in backend-phase-K
 -->
 
-_(no requests yet)_
+## REQ-001 — Confirm response envelope, wire casing & pagination shape — filed by frontend-phase-0 — 2026-07-02
+- **Need:** Authoritative confirmation of three things the frontend types depend on:
+  1. **Envelope unwrapping.** The b0 swagger shows every response wrapped in `ApiResult`
+     (`{ isSuccess, statusCode, message, requestId, data }`). The frontend's `clientFetch` currently
+     returns the **raw body**, so domain `clientApi`s read the payload via `unwrap()` (`data`). Confirm this
+     is the intended shape for all endpoints (i.e. payload always under `data`), so the pattern is correct
+     before f1+ copy it.
+  2. **Wire casing.** Observed swagger properties are **camelCase** (`isSuccess`, `serverTimeUtc`) — not the
+     snake_case `api-conventions.md` implies for URL segments. Please confirm JSON body casing is camelCase
+     (and, if so, we can note it in the convention doc), or state where it differs.
+  3. **Pagination payload.** `api-conventions.md` says lists return `items` + `total` (+ `page`/`page_size`).
+     Confirm the exact field names/casing on the wire (we've typed `Paginated<T>` as
+     `{ items, total, page, pageSize }` in `client/src/lib/api/types.ts`).
+- **Why:** These fix the shared `ApiEnvelope<T>`/`Paginated<T>` types and the `services/{domain}` reference
+  pattern every later frontend phase inherits.
+- **Proposed shape:** `{ isSuccess: boolean, statusCode: number, message?: string, requestId?: string, data?: T }`
+  and `data: { items: T[], total: number, page: number, pageSize: number }` for lists.
+- **Status:** open