refinement phase 1

dev/post-phase/refinement/RUNBOOK.md

@@ -79,6 +79,11 @@ On boot the API applies all EF migrations and seeds roles + an admin user + a sa
 against the (empty) local DB, then listens on **`https://localhost:5002`** — Swagger at
 `https://localhost:5002/swagger`.
 
+In **Development** it additionally runs the **demo-world seeder** (Refinement Phase 1): verified/unverified
+demo nurses with priced variants + Tehran coverage (and therefore real `nurse_search_index` rows), plus demo
+customers with patients and addresses. The console logs `Demo world seeded: 3 nurse(s), 2 customer(s)…` (or
+`already seeded — no-op` on a subsequent run). It is **idempotent** and **never runs outside Development**.
+
 ### Terminal 2 — frontend (from `client/`)
 
 ```bash
@@ -93,10 +98,29 @@ Serves **`http://localhost:3000`**. It reads the API base URL from `client/.env.
 
 ---
 
+## Demo accounts (Development seed)
+
+The demo seeder creates these loginable accounts (phone-OTP; any 6-digit code you read from the console/dev
+endpoint works). Use them to see the real path populated:
+
+| Phone | Role | Who | State |
+| --- | --- | --- | --- |
+| `09120000001` | nurse | زهرا عزیزی (female) | **verified**, 3 variants, whole-city + 2 districts |
+| `09120000002` | nurse | علی کریمی (male) | **verified**, 2 variants, 3 districts |
+| `09120000003` | nurse | مریم احمدی (female) | **unverified** — not discoverable in search |
+| `09120000010` | customer | سارا محمدی (female) | 2 patients, 1 Tehran address |
+| `09120000011` | customer | رضا حسینی (male) | 1 patient, 1 Tehran address |
+| `admin` / `qw123321` | admin | seeded admin (username+password) | backoffice |
+
+Prove search works without the frontend: open Swagger →
+`GET /api/v1/search/nurses?service_category_id=1&city_id=101` returns the two verified nurses' variants;
+`service_category_id=3` (only the unverified nurse) returns an empty page.
+
 ## Log in (the real round-trip)
 
 1. Open **`http://localhost:3000/fa/login`**.
-2. Enter an Iranian mobile number (e.g. `09120000001`) and request the code.
+2. Enter an Iranian mobile number (e.g. the verified nurse `09120000001`, or any demo phone above) and request
+   the code.
 3. Get the 6-digit OTP one of two ways:
    - **Read the server console** (Terminal 1) — SMS is mocked, so the code is logged:
      `MOCK SMS — OTP code 123456 for phone ending in 0001`.
@@ -118,8 +142,18 @@ Serves **`http://localhost:3000`**. It reads the API base URL from `client/.env.
   automatically, so `fetch` just works; for `curl` add `--http2`.
 - **Only `auth` is real by default.** 21 of 22 client service domains default to an in-browser mock
   (`USE_*_MOCK = true`); the home, search, bookings, etc. are fake in-memory data until Refinement Phase 4.
-- **The DB self-migrates + self-seeds**, so pointing at an empty local instance is enough. Rich demo data
-  (nurses, variants, search rows) arrives in [Refinement Phase 1](refinement-phase-1-database-and-seed.md).
+- **The DB self-migrates + self-seeds**, so pointing at an empty local instance is enough — including the
+  Development demo world (nurses, variants, search rows, customers) from
+  [Refinement Phase 1](refinement-phase-1-database-and-seed.md).
+- **Explicit migration path (deploy / migrations-off-boot).** Boot-time `MigrateAsync` is the dev convenience;
+  to apply migrations without booting the app (the direction [Refinement Phase 7](refinement-phase-7-unattended-ops.md)
+  will formalise), run from `server/`:
+  ```bash
+  dotnet ef database update --project src/Infrastructure/Baya.Infrastructure.Persistence --startup-project src/API/Baya.Web.Api
+  ```
+  (`dotnet tool install --global dotnet-ef` if the `ef` command is missing. It reads the same connection
+  string, so set the user-secret / env var first.) This applies **schema only** — the reference + demo seeds
+  run on the next app boot.
 - **Allowed browser origins** are configuration-driven (`Cors:AllowedOrigins`), defaulting to
   `http://localhost:3000` in Development. A deployed environment lists its real web origin(s).
 
@@ -127,9 +161,13 @@ Serves **`http://localhost:3000`**. It reads the API base URL from `client/.env.
 
 ```bash
 docker compose down          # stop the DB, keep its data
-docker compose down -v       # stop the DB and wipe the volume (fresh migrate + seed next run)
+docker compose down -v       # stop the DB and wipe the volume (fresh migrate + reference + demo seed next run)
 ```
 
+Re-running `dotnet run` against an **existing** seeded DB does not duplicate anything — both the reference and
+the demo seeders are idempotent (the demo seeder guards each persona on its phone number). To get a clean demo
+world, wipe the volume (`docker compose down -v`) and boot again.
+
 ## Troubleshooting
 
 | Symptom | Fix |