feat(api): add unified v2 gateway and mobile read slice

docs/BACKEND/API_GUIDES/V2/README.md

@@ -2,31 +2,43 @@
 
 This is the frontend-facing source of truth for the v2 backend.
 
-If you are building against the new backend, start here.
+## 1) Frontend entrypoint
 
-## 1) Which service to use
+Frontend should target one public base URL:
 
-| Use case | Service |
+```env
+API_V2_BASE_URL=<krow-api-v2-url>
+```
+
+The unified v2 gateway exposes:
+
+- `/auth/*`
+- `/core/*`
+- `/commands/*`
+- `/query/*`
+- `/query/client/*`
+- `/query/staff/*`
+
+Internal services still stay separate behind that gateway.
+
+## 2) Internal service split
+
+| Use case | Internal service |
 | --- | --- |
-| File upload, signed URLs, model calls, rapid order helpers, verification flows | `core-api-v2` |
+| File upload, signed URLs, model calls, verification helpers | `core-api-v2` |
 | Business writes and workflow actions | `command-api-v2` |
-| Screen reads for the implemented v2 views | `query-api-v2` |
-
-## 2) Live dev base URLs
-
-- Core API: `https://krow-core-api-v2-e3g6witsvq-uc.a.run.app`
-- Command API: `https://krow-command-api-v2-e3g6witsvq-uc.a.run.app`
-- Query API: `https://krow-query-api-v2-e3g6witsvq-uc.a.run.app`
+| Screen reads and mobile read models | `query-api-v2` |
+| Frontend-facing single host and auth wrappers | `krow-api-v2` |
 
 ## 3) Auth and headers
 
-All protected routes require:
+Protected routes require:
 
 ```http
 Authorization: Bearer <firebase-id-token>
 ```
 
-All command routes also require:
+Command routes also require:
 
 ```http
 Idempotency-Key: <unique-per-user-action>
@@ -43,78 +55,88 @@ All services return the same error envelope:
 }
 ```
 
-## 4) What frontend can use now
+## 4) What frontend can use now on this branch
 
-### Ready now
+### Unified gateway
 
-- `core-api-v2`
-  - upload file
-  - create signed URL
-  - invoke model
-  - rapid order transcribe
-  - rapid order parse
-  - create verification
-  - get verification
-  - review verification
-  - retry verification
-- `command-api-v2`
-  - create order
-  - update order
-  - cancel order
-  - assign staff to shift
-  - accept shift
-  - change shift status
-  - clock in
-  - clock out
-  - favorite and unfavorite staff
-  - create staff review
-- `query-api-v2`
-  - order list
-  - order detail
-  - favorite staff list
-  - staff review summary
-  - assignment attendance detail
+- `POST /auth/client/sign-in`
+- `POST /auth/client/sign-up`
+- `POST /auth/sign-out`
+- `POST /auth/client/sign-out`
+- `POST /auth/staff/sign-out`
+- `GET /auth/session`
+- Proxy access to `/core/*`, `/commands/*`, `/query/*`
 
-### Do not move yet
+### Client read routes
 
-- reports
-- payments and finance screens
-- undocumented dashboard reads
-- undocumented scheduling reads and writes
-- any flow that assumes verification history is durable in SQL
+- `GET /query/client/session`
+- `GET /query/client/dashboard`
+- `GET /query/client/reorders`
+- `GET /query/client/billing/accounts`
+- `GET /query/client/billing/invoices/pending`
+- `GET /query/client/billing/invoices/history`
+- `GET /query/client/billing/current-bill`
+- `GET /query/client/billing/savings`
+- `GET /query/client/billing/spend-breakdown`
+- `GET /query/client/coverage`
+- `GET /query/client/coverage/stats`
+- `GET /query/client/hubs`
+- `GET /query/client/cost-centers`
+- `GET /query/client/vendors`
+- `GET /query/client/vendors/:vendorId/roles`
+- `GET /query/client/hubs/:hubId/managers`
+- `GET /query/client/orders/view`
 
-## 5) Important caveat
+### Staff read routes
 
-`core-api-v2` is usable now, but verification job state is not yet persisted to `krow-sql-v2`.
+- `GET /query/staff/session`
+- `GET /query/staff/dashboard`
+- `GET /query/staff/profile-completion`
+- `GET /query/staff/availability`
+- `GET /query/staff/clock-in/shifts/today`
+- `GET /query/staff/clock-in/status`
+- `GET /query/staff/payments/summary`
+- `GET /query/staff/payments/history`
+- `GET /query/staff/payments/chart`
+- `GET /query/staff/shifts/assigned`
+- `GET /query/staff/shifts/open`
+- `GET /query/staff/shifts/pending`
+- `GET /query/staff/shifts/cancelled`
+- `GET /query/staff/shifts/completed`
+- `GET /query/staff/shifts/:shiftId`
+- `GET /query/staff/profile/sections`
+- `GET /query/staff/profile/personal-info`
+- `GET /query/staff/profile/industries`
+- `GET /query/staff/profile/skills`
+- `GET /query/staff/profile/documents`
+- `GET /query/staff/profile/certificates`
+- `GET /query/staff/profile/bank-accounts`
+- `GET /query/staff/profile/benefits`
 
-What is durable today:
-- uploaded files in Google Cloud Storage
-- generated signed URLs
-- model invocation itself
+### Existing v2 routes still valid
 
-What is not yet durable:
-- verification job history
-- verification review history
-- verification event history
+- `/core/*` routes documented in `core-api.md`
+- `/commands/*` routes documented in `command-api.md`
+- `/query/tenants/*` routes documented in `query-api.md`
 
-That means frontend can integrate with verification routes now, but should not treat them as mission-critical durable state yet.
+## 5) Remaining gaps after this slice
 
-## 6) Recommended frontend environment variables
+Still not implemented yet:
 
-```env
-CORE_API_V2_BASE_URL=https://krow-core-api-v2-e3g6witsvq-uc.a.run.app
-COMMAND_API_V2_BASE_URL=https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
-QUERY_API_V2_BASE_URL=https://krow-query-api-v2-e3g6witsvq-uc.a.run.app
-```
+- staff phone OTP wrapper endpoints
+- hub write flows
+- hub NFC assignment write route
+- invoice approve and dispute commands
+- staff apply / decline / request swap commands
+- staff profile update commands
+- availability write commands
+- reports suite
+- durable verification persistence in `core-api-v2`
 
-## 7) Service docs
+## 6) Docs
 
+- [Unified API](./unified-api.md)
 - [Core API](./core-api.md)
 - [Command API](./command-api.md)
 - [Query API](./query-api.md)
-
-## 8) Frontend integration rule
-
-Do not point screens directly at database access just because a route does not exist yet.
-
-If a screen is missing from the docs, the next step is to define the route contract and add it to `query-api-v2` or `command-api-v2`.
+- [Mobile gap analysis](./mobile-api-gap-analysis.md)