docs: add §0 - auth + payment authorization was missing entirely

Direct question caught a real gap: "everything is there? payment auth?"
The census only grepped src/app/ - auth moved into the external
@marketplaces/auth package this session, and its HTTP calls were never
captured. Seven real endpoints were silently absent from a doc that called
itself "complete":

- 3 Telegram QR/session endpoints (POST/GET/DELETE .../users/sessions) -
  live today, customer and admin login share them, which is exactly why
  every admin endpoint must independently verify authorization server-side
- 4 ed25519 admin challenge/response endpoints - specified in
  BACKEND-HANDOFF.md §3 and the package's own auth-api.model.ts, but not
  built server-side. Client shows backend-unavailable until they exist.

Added §0.3 stating plainly what actually connects auth to payment: there is
no separate payment login. Checkout, order pricing (§20), and partner
credentials (§16) each ride on whichever of the two sessions above is
active, or on the partner API's own separate signed-request auth (§6 of
that contract - unrelated to Telegram/ed25519, already built, not a gap).
The real payment gap is §1 (QR/card creation and polling, undocumented
anywhere), not auth.

Counts corrected: 51->54 specified, 90->97 total. Added item 0 to the
action list, ahead of everything else: the ed25519 endpoints are the single
most serious open issue named anywhere in docs/backend/, and every other
item on the list assumes a working admin session to authorize against.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/backend/FRONTEND-API-SURFACE-COMPLETE.md

@@ -1,6 +1,6 @@
 # Complete Frontend API Surface — Master Endpoint List
 
-Generated 2026-08-18, updated same day after the frontend backlog (F1–F65) closed. Directly from source (every `this.http.get/post/patch/put/delete` call across `src/app/core/`, `src/app/features/admin/`, `src/app/services/api.service.ts`). This is not a design document — it is a **census**: every endpoint this codebase currently calls or will call once its gateway swap goes live, in one place, cross-referenced against the contracts that already exist.
+Generated 2026-08-18, updated same day after the frontend backlog (F1–F65) closed, updated again same day to add §0 after a direct question ("everything is there? payment auth?") caught that the first pass only grepped `src/app/` — auth moved into the external `@marketplaces/auth` package this session, and its own HTTP calls (§0) were missing from what this doc called "complete." Fixed by grepping `node_modules/@marketplaces/auth/dist/` directly. Directly from source (every `this.http.get/post/patch/put/delete` call across `src/app/core/`, `src/app/features/admin/`, `src/app/services/api.service.ts`, and now the auth package). This is not a design document — it is a **census**: every endpoint this codebase currently calls or will call once its gateway swap goes live, in one place, cross-referenced against the contracts that already exist.
 
 **This is the final handoff doc for this pass.** Frontend work is done except one item that genuinely cannot be finished without a live backend (§19). Everything else — every gateway, every model, every invariant — is written, tested, and pushed. What follows is everything backend needs to make it real.
 
@@ -16,6 +16,41 @@ Generated 2026-08-18, updated same day after the frontend backlog (F1–F65) clo
 
 ---
 
+## 0. Auth — lives in `@marketplaces/auth`, not this repo, and payment authorization runs through it
+
+Two separate, real mechanisms. Both are called from the external package (`node_modules/@marketplaces/auth/dist/`), which is why §0 didn't exist in the first pass of this doc — that pass only grepped `src/app/`.
+
+### 0.1 Telegram QR/session — ✅ Specified, **live**
+
+Per `BACKEND-HANDOFF.md` §3 and `PACKAGES-USAGE.md`. **Customer and admin login call the same endpoints** — only client-side storage differs, which is exactly why every admin endpoint must independently verify authorization server-side (stated plainly in `BACKEND-HANDOFF.md` §3 as "the single most serious open issue in the system").
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `{authApiUrl}/users/sessions` | create a session from a Telegram login |
+| GET | `{authApiUrl}/users/sessions/{id}` | poll / check session status |
+| DELETE | `{authApiUrl}/users/sessions/{id}` | log out |
+
+Expected response: `{ webSessionID, user: { userId, username, firstName, lastName }, status, expiresAt }` — parsed permissively client-side (many key-name variants accepted), but a clean backend implementation should return exactly this shape.
+
+### 0.2 Ed25519 admin challenge/response — specified, **not built**
+
+Per `BACKEND-HANDOFF.md` §3 and the package's own `ed25519/models/auth-api.model.ts`. This is what backend-authorizes an admin session distinctly from a customer one, and it does not exist server-side yet — every request today shows a `backend-unavailable` screen once the client reaches for it, nothing is mocked.
+
+| Method | Path |
+|---|---|
+| GET | `/api/admin/auth/challenge` |
+| POST | `/api/admin/auth/verify` |
+| POST | `/api/admin/auth/refresh` |
+| POST | `/api/admin/auth/logout` |
+
+### 0.3 What this has to do with payment
+
+There is no separate "payment login." Authorization for anything payment-adjacent — creating a checkout session, viewing `GET /api/admin/v2/orders/{id}`'s pricing breakdown (§20), touching a partner credential (§16) — rides on whichever of the two sessions above is active. The partner-provisioning API (§16) has its **own**, separate signed-request auth (§6 of that contract, public-key based, no session token at all) — that one is unrelated to Telegram/ed25519 and is not a gap, it's a different, already-built mechanism for a different caller (partners, not our own admins or customers).
+
+**The actual payment gap is §1 below, not auth**: QR/card payment creation and status polling are real, live, and completely undocumented anywhere in `docs/backend/`.
+
+---
+
 ## 1. Legacy surface (still called today, no `/api/v2` contract)
 
 These come from `BACKEND-API-REFERENCE.md`, not `docs/backend/`. Base URL is `environment.localhostApiUrl` / tenant-resolved; `qrBaseUrl` is a separate provider base for QR-specific calls.
@@ -336,15 +371,18 @@ The frontend added a client-side guard against double-submitting checkout (a rea
 
 | Status | Count |
 |---|---|
-| ✅ Specified | 51 |
+| ✅ Specified | 54 |
 | ⚠️ Inferred (needs confirmation) | 24 |
 | ❌ Undocumented (legacy) | 15 |
-| **Total distinct endpoints called** | **90** |
+| **Total distinct endpoints called** | **97** |
+
+(§0's 3 Telegram endpoints count as Specified+live; its 4 ed25519 endpoints count as Specified+not-built — both are real, named endpoints with a known shape, distinct from §1's "no contract exists anywhere" undocumented status.)
 
 Plus 3 response-shape additions (§19–21) on existing endpoints — not new endpoints, new optional fields on responses those endpoints already return.
 
 ## What backend needs to do with this
 
+0. **§0.2 first, ahead of everything else on this list.** The 4 ed25519 admin auth endpoints are the single most serious open issue named anywhere in `docs/backend/` (`BACKEND-HANDOFF.md` §3's own words). Every other item below assumes an admin session exists to authorize the request — that session mechanism does not exist server-side yet.
 1. **Build the ✅ rows as written** — they match an existing contract doc exactly. This includes §18's 4 revision endpoints, pending confirmation on the `validated`/`preview` ambiguity called out there.
 2. **Confirm or correct every ⚠️ row** — each one has a comment at its call site in source explaining the inference. Search the codebase for `Inferred` to find all 24 in place, with the reasoning right next to the code.
 3. **Populate the 3 optional field sets (§19–21)** on the endpoints that already exist — `routing` and pricing-breakdown fields on `GET /api/admin/v2/orders/{id}`, the 8 metric fields on `GET /api/admin/v2/dashboard/metrics`. Nothing on the frontend breaks while these are absent; nothing shows the real data either.