GravityDarkLab · GravityDarkLab · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026
diff --git a/.env.example b/.env.example
@@ -28,7 +28,7 @@ FORM_SECRET=replace_with_64_hex_chars_generated_by_openssl_rand_hex_32
 JWT_SECRET=replace_with_long_random_secret
 # Format used for time span should be a number followed by a unit, such as "5 minutes" or "1 day".
 # Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y".
-JWT_EXPIRY=8h
+ADMIN_JWT_EXPIRY=8h
 
 # ─── Server ───────────────────────────────────────────────────────────────────
 PORT=3001

diff --git a/.gitignore b/.gitignore
@@ -20,3 +20,9 @@ Thumbs.db
 
 # Claude
 .claude/
+
+.superpowers/
+
+# Local-only planning artifacts (design specs, implementation plans) —
+# useful while working, not meant to live in the repo permanently
+docs/superpowers/
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 A privacy-first couple matching platform. Applicants fill out a form, an admin reviews and runs the matching engine, and compatible pairs are surfaced — no Instagram handles or personal details ever leave the encrypted identity store.
 
 **Stack:** Bun · Hono · MongoDB · React · Vite · Tailwind  
-**Docs:** [`api/README.md`](./api/README.md) · [`frontend/README.md`](./frontend/README.md) · [`api/src/matching/README.md`](./api/src/matching/README.md)
+**Docs:** [`api/README.md`](./api/README.md) · [`frontend/README.md`](./frontend/README.md) · [`api/src/matching/README.md`](./api/src/matching/README.md) · [LLM listwise-rerank matching score — design & literature](./docs/llm-listwise-rerank-matching-score.md)
 
 ---
 
@@ -115,7 +115,7 @@ ons/
 │   │   ├── controllers/            ← Request handlers
 │   │   ├── routes/                 ← Hono route definitions
 │   │   ├── middleware/             ← Auth, rate limiting, audit logging
-│   │   └── __tests__/             ← Full test suite (199 tests)
+│   │   └── __tests__/             ← Full test suite (515 tests)
 │   ├── docs/openapi.yaml           ← Full OpenAPI 3.1 spec
 │   ├── Dockerfile
 │   └── README.md                   ← API setup & reference
@@ -138,11 +138,12 @@ ons/
 ## How it works
 
 1. **Applicant fills the form** — the frontend fetches the active questionnaire, gates access with an invite key, and POSTs answers to the API.
-2. **PII is isolated at submission** — the Instagram handle is AES-256-GCM encrypted and stored in a separate `identities` collection, never in the applicant profile.
-3. **Admin runs matching** — `POST /api/v1/matching/run` scores all active applicants pairwise and returns ranked candidates per person.
-4. **Admin resolves identities** — every access to an encrypted identity is audit-logged.
+2. **PII is isolated at submission** — the first/last name and Instagram handle are each AES-256-GCM encrypted (own fresh IV per field) and stored in a separate `identities` collection, never in the applicant profile.
+3. **Admin runs matching** — `POST /api/v1/matching/run` shortlists all active applicants pairwise with text embeddings, then an LLM rerank call (one per applicant, covering its whole shortlist) judges the shortlist and produces the score that's actually returned — the embedding step alone is structurally incapable of scoring a great pair above ~80%, see [`api/src/matching/README.md`](./api/src/matching/README.md#llm-rerank-servicesmatch-rerankservicets).
+4. **Admin resolves identities** — every access to someone else's encrypted identity is audit-logged. (Applicants can always see their own name on their own profile — that's not a "reveal", just their own data.)
 5. **Applicant uses their portal** — a magic link from the admin grants access to `/profile`, where the applicant reviews their matches and can edit their questionnaire answers.
-6. **Matched applicants connect** — either side can request to exchange Instagram handles; once both accept, identities are decrypted (audit-logged) and shared with both parties.
+6. **Matched applicants connect** — either side can initiate contact; the target receives ice-breaker prompts and date ideas to decide. Only when the target **accepts** are both parties' Instagram handles and names decrypted simultaneously, audit-logged, and revealed to each other. A declined or withdrawn request leaves identities sealed.
+7. **Dating, the warm way** — once mutual, outcome reporting is time-gated rather than available immediately: a friendly rotating check-in message shows for the first 3 days, a quiet "things aren't working out?" option unlocks at day 3, and full "it worked / it didn't" reporting unlocks at day 7. A failed outcome can optionally tag why (e.g. "too far apart") and choose to keep looking or take a break — tagging distance later surfaces a one-time, dismissible suggestion to open up to long-distance matches.
 
 ---
 
@@ -157,16 +158,17 @@ browser ──► frontend (React + Vite)
            │form│ admin │ profile │ match │
            └──┬─┴───────┴────┬────┴───┬───┘
               │               │        │
-          MongoDB         Matching engine
-        ┌────┴──────┐    (baseline / cosine /
-        │ applicants│     embedding-cosine)
-        │ identities│
-        │ embeddings│
-        │ audit_logs│
-        └───────────┘
+          MongoDB              Matching engine
+        ┌───────┴───────┐     (embedding-cosine shortlist
+        │ applicants    │      + age filter, then an
+        │ identities    │      LLM listwise rerank for
+        │ embeddings    │      the displayed score)
+        │ match_reranks │
+        │ audit_logs    │
+        └───────────────┘
 ```
 
-See [`api/src/matching/README.md`](./api/src/matching/README.md) for the full algorithm breakdown — weights, math, embedding batching, and how to add a new algorithm.
+See [`api/src/matching/README.md`](./api/src/matching/README.md) for the full pipeline breakdown — weights, age filter math, embedding batching, and how to extend the system.
 
 ---
 
@@ -175,11 +177,11 @@ See [`api/src/matching/README.md`](./api/src/matching/README.md) for the full al
 | Data | Collection | Who can access |
 |---|---|---|
 | Questionnaire answers | `applicants` | Admin, and the applicant themselves via `/profile` |
-| Instagram handle | `identities` (AES-256-GCM encrypted) | Admin (audit-logged), or a matched applicant after mutual reveal (audit-logged) |
+| Instagram handle + first/last name | `identities` (AES-256-GCM encrypted, each field its own IV) | The applicant themselves (their own name, not audit-logged); admin (audit-logged); or both matched applicants simultaneously after mutual acceptance of a contact request (each audit-logged independently) |
 | Text embeddings | `embeddings` | Matching engine |
 | Admin actions | `audit_logs` | Admin |
 
-The Instagram handle never touches the `applicants` collection. It is encrypted with a fresh random IV on every write and stored separately. Decryption requires the `ENCRYPTION_KEY` secret and is always written to `audit_logs` before the plaintext is returned — whether the reader is an admin or a matched applicant who completed a mutual identity reveal.
+The Instagram handle and name never touch the `applicants` collection. Each is encrypted with its own fresh random IV on every write and stored separately — even within the same `identities` document, no two fields ever share an IV. Decryption requires the `ENCRYPTION_KEY` secret. Decrypting *someone else's* identity (an admin lookup, or a matched applicant's mutual reveal) is always written to `audit_logs` before the plaintext is returned; an applicant viewing their own name on their own profile is not, since that's not a privacy-sensitive reveal.
 
 ---
 
@@ -330,7 +332,8 @@ Inject secrets via ECS task-definition environment variables or AWS Secrets Mana
 | `bun run dev:api:prod` | API only — `.env.prod` (hot reload) |
 | `bun run dev:frontend` | Frontend only (hot reload) |
 | `bun run seed` | Interactive seed runner — choose questionnaire, applicants, or both; prompts for environment |
+| `bun run eval:rerank` | Runs a full matching pass and prints embedding-vs-LLM score distributions side by side (real calls, not mocked) |
 | `bun run build` | Build all workspaces |
 | `bun run typecheck` | Type-check all workspaces |
-| `bun run test` | Run API + frontend test suites in parallel (API: 383 tests, no DB required) |
+| `bun run test` | Run API + frontend test suites in parallel (API: 515 tests, no DB required) |
 | `bun run test:smoke` | Run smoke tests against a live server + DB (requires env vars — see `tests/smoke/`) |
diff --git a/api/.env.example b/api/.env.example
@@ -31,7 +31,10 @@ FORM_SECRET=replace_with_64_hex_chars_generated_by_openssl_rand_hex_32
 JWT_SECRET=replace_with_long_random_secret
 # Format used for time span should be a number followed by a unit, such as "5 minutes" or "1 day".
 # Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y".
-JWT_EXPIRY=8h
+ADMIN_JWT_EXPIRY=8h
+# Applicant portal session length — separate from ADMIN_JWT_EXPIRY above since
+# admins and applicants have very different re-login tolerance. Same format.
+APPLICANT_JWT_EXPIRY=30d
 
 # ─── Account deletion ──────────────────────────────────────────────────────────
 # Days an inactive applicant's personal data is retained before permanent purge.
@@ -41,6 +44,11 @@ DELETION_GRACE_DAYS=180
 # ─── Server ───────────────────────────────────────────────────────────────────
 PORT=3001
 NODE_ENV=development
+# Set to true ONLY when a trusted reverse proxy (nginx/caddy/load balancer that
+# overwrites X-Forwarded-For) sits in front of the API. When false (default),
+# proxy headers are ignored for the client IP used in rate limiting and audit
+# logs — otherwise any direct client could spoof its IP per request.
+TRUST_PROXY=false
 # Full base URL logged on startup. Leave empty in dev (defaults to http://localhost:<PORT>).
 # Set in test/prod: PUBLIC_URL=https://api.domain.com
 PUBLIC_URL=
@@ -65,10 +73,26 @@ EMBEDDING_MODEL=
 OPENAI_API_KEY=
 EMBEDDING_BASE_URL=
 
-# ─── AI chat (ice-breaker generation) ─────────────────────────────────────────
-# Uses the same provider/endpoint as embeddings. Only the model name differs.
-#   openai provider:  OPENAI_CHAT_MODEL=gpt-4o-mini
+# ─── AI chat (ice-breaker generation, match summaries, match rerank) ──────────
+# Defaults to EMBEDDING_PROVIDER/EMBEDDING_BASE_URL above if left unset — set
+# these only if you want chat completions to use a *different* backend than
+# embeddings (e.g. local embeddings you've already cached + a hosted OpenAI
+# chat model, or vice versa).
+#
+# CHAT_PROVIDER=openai   → OPENAI_API_KEY (same key as above) is required
+# CHAT_PROVIDER=local    → CHAT_BASE_URL (or EMBEDDING_BASE_URL as a fallback)
+#   CHAT_BASE_URL=http://localhost:1234/v1   # LM Studio
+#   CHAT_BASE_URL=http://localhost:11434/v1  # Ollama
+#
+#   openai provider:  OPENAI_CHAT_MODEL=gpt-5.4-mini
 #   local provider:   OPENAI_CHAT_MODEL=llama-3.2-3b-instruct  (whatever is loaded)
+# Privacy note: with CHAT_PROVIDER=openai (or EMBEDDING_PROVIDER=openai when
+# CHAT_PROVIDER is unset), free-text profile answers (lifestyle, deal
+# breakers, etc. — never the Instagram handle) are sent to OpenAI to generate
+# ice-breakers, match summaries, and rerank scores. Use a local provider to
+# keep all profile text on infrastructure you control.
+CHAT_PROVIDER=
+CHAT_BASE_URL=
 OPENAI_CHAT_MODEL=gpt-4o-mini
 
 # ─── Scheduled matching job ────────────────────────────────────────────────────

diff --git a/api/README.md b/api/README.md
@@ -43,9 +43,14 @@ cp api/.env.example api/.env
 | `PORT` | `3001` | Server port |
 | `NODE_ENV` | `development` | Environment |
 | `ALLOWED_ORIGINS` | `http://localhost:3000,http://localhost:5173` | CORS origins |
-| `JWT_EXPIRY` | `8h` | JWT token lifetime |
+| `TRUST_PROXY` | `false` | Set `true` only behind a trusted reverse proxy that overwrites `X-Forwarded-For` — enables proxy headers as the client IP for rate limiting and audit logs; otherwise headers are ignored (spoofable) |
+| `ADMIN_JWT_EXPIRY` | `8h` | Admin session JWT lifetime |
+| `APPLICANT_JWT_EXPIRY` | `30d` | Applicant portal session JWT lifetime |
 | `PUBLIC_URL` | _(empty)_ | Base URL for startup logs |
-| `OPENAI_API_KEY` | _(empty)_ | Required when `EMBEDDING_PROVIDER=openai` |
+| `OPENAI_API_KEY` | _(empty)_ | Required when `EMBEDDING_PROVIDER=openai` or `CHAT_PROVIDER=openai` |
+| `CHAT_PROVIDER` | `EMBEDDING_PROVIDER` | `openai` or `local` for ice-breakers/match-summaries/match-rerank — independent of the embedding provider |
+| `CHAT_BASE_URL` | `EMBEDDING_BASE_URL` | Base URL for a local chat provider, if different from the local embedding server |
+| `OPENAI_CHAT_MODEL` | `gpt-4o-mini` | Chat model name (e.g. `gpt-5.4-mini` for OpenAI) |
 
 ---
 
@@ -78,6 +83,20 @@ bun run --cwd .. seed:applicants -- --count 50 --clear
 
 ---
 
+## Evaluating the matching score
+
+`bun run eval:rerank` (from the monorepo root) runs one full matching pass and prints embedding-vs-LLM score distributions side by side — no need to disable the rerank stage to compare, since every candidate already carries both numbers. Requires a seeded applicant pool and a configured `EMBEDDING_PROVIDER`/`OPENAI_CHAT_MODEL` (real embedding + LLM calls, not mocked):
+
+```bash
+bun run eval:rerank                  # api/.env.dev
+bun run eval:rerank --env=test
+bun run eval:rerank --csv=out.csv    # also write every candidate row to CSV
+```
+
+See ["7. Evaluation"](../docs/llm-listwise-rerank-matching-score.md#7-evaluation) in the design writeup for what this is meant to validate.
+
+---
+
 ## API reference
 
 ### Public
@@ -107,7 +126,7 @@ curl -X POST http://localhost:3001/api/v1/admin/login \
 | `GET` | `/api/v1/admin/me` | Current admin session info |
 | `GET` | `/api/v1/admin/applicants` | List applicants (paginated, filterable) |
 | `GET` | `/api/v1/admin/applicants/:id` | Get applicant profile |
-| `GET` | `/api/v1/admin/applicants/:id/identity` | Decrypt & return Instagram handle ⚠ audit logged, `super_admin` only |
+| `GET` | `/api/v1/admin/applicants/:id/identity` | Decrypt & return Instagram handle + full name ⚠ audit logged, `super_admin` only |
 | `DELETE` | `/api/v1/admin/applicants/:id` | Deactivate applicant |
 | `POST` | `/api/v1/admin/applicants/:id/regenerate-magic-link` | Issue a new portal magic link, `super_admin` only |
 | `GET` | `/api/v1/admin/audit-logs` | View audit trail |
@@ -124,8 +143,8 @@ curl -X POST http://localhost:3001/api/v1/admin/login \
 | `GET` | `/api/v1/matching/last-run` | Summary of the most recent matching pass |
 | `POST` | `/api/v1/matching/run` | Full pairwise pass over all active applicants |
 
-Both `candidates` and `run` accept an `algorithm` parameter: `baseline`, `cosine`, or `embedding-cosine`.  
-See [`src/matching/README.md`](./src/matching/README.md) for algorithm details.
+Candidates are shortlisted with the `embedding-cosine` algorithm (semantic text embeddings + age filter), then the shortlist is rescored by an LLM listwise rerank call — that's the score actually returned and displayed. No `algorithm` parameter is accepted.  
+See [`src/matching/README.md`](./src/matching/README.md) for pipeline details.
 
 ### Applicant portal (session cookie)
 
@@ -141,10 +160,11 @@ Applicants log in with a magic link (issued by an admin) and, on first login, se
 | `GET` | `/api/v1/profile/answers` | Get my questionnaire answers |
 | `PUT` | `/api/v1/profile/answers` | Edit my questionnaire answers |
 | `GET` | `/api/v1/profile/matches` | List my matches with score breakdown |
-| `POST` | `/api/v1/profile/matches/:id/contact` | Request to exchange Instagram handles with a match ⚠ audit logged on acceptance |
-| `POST` | `/api/v1/profile/matches/:id/respond` | Accept or decline a contact request |
+| `POST` | `/api/v1/profile/matches/:id/contact` | Initiate contact with a match — returns ice-breakers and date ideas; no identity revealed yet |
+| `POST` | `/api/v1/profile/matches/:id/respond` | Accept or decline a contact request — accepting reveals the initiator's handle + name immediately in the response |
 | `POST` | `/api/v1/profile/matches/:id/withdraw` | Withdraw a contact request |
-| `POST` | `/api/v1/profile/matches/:id/outcome` | Report a match outcome (`success` / `failed`) |
+| `POST` | `/api/v1/profile/matches/:id/outcome` | Report a match outcome (`success` / `failed`). Time-gated: `failed` unlocks 3 days after `dating`, `success` after 7. Optional `outcomeFeedback` (tags + note) and a `continuation` (`continue`/`break`) choice on `failed` |
+| `POST` | `/api/v1/profile/matches/:id/nudge-ack` | Dismiss the distance-preference nudge surfaced after a `failed` outcome tagged `too_far`; optionally opens the applicant to long-distance matches |
 | `POST` | `/api/v1/profile/change-password` | Change my password |
 | `POST` | `/api/v1/profile/deactivate` | Deactivate my account |
 | `POST` | `/api/v1/profile/cancel-deletion` | Cancel a pending account deletion |
@@ -179,10 +199,11 @@ api/
 
 ## Privacy & security
 
-- **No PII in applicant profiles** — Instagram handles are AES-256-GCM encrypted in a separate `identities` collection.
+- **No PII in applicant profiles** — Instagram handles and first/last names are AES-256-GCM encrypted in a separate `identities` collection, each field with its own fresh IV (never reusing another field's IV, even within the same document).
 - **Submission keys** — HMAC-SHA256(version, `FORM_SECRET`) prevents questionnaire version enumeration.
-- **Audit logs** — every identity decryption (admin lookup *or* mutual match reveal) is written to `audit_logs` with actor, IP, user-agent, and timestamp before plaintext is returned.
-- **Mutual identity reveal** — an applicant calling `/profile/matches/:id/contact` immediately decrypts and is shown the partner's Instagram handle; the partner sees the initiator's handle as soon as they view that match (`GET /profile/matches`), before accepting or declining.
+- **Audit logs** — every identity decryption of *someone else's* data (admin lookup or mutual match reveal) is written to `audit_logs` with actor, IP, user-agent, and timestamp before plaintext is returned. Viewing your own name on your own profile is not audit-logged — it isn't a privacy-sensitive reveal.
+- **Mutual identity reveal** — Instagram handles and full names are only decrypted when the target explicitly accepts a contact request (`POST /profile/matches/:id/respond` with `accept: true`). At that point both parties' handles/names are decrypted simultaneously, each reveal is audit-logged independently, and both parties see them on their next `GET /profile/matches` call (the response to `/respond` itself already includes the initiator's handle/name for the responding applicant). A declined or withdrawn request leaves identities sealed.
+- **Outcome gating** — once a match is `dating`, `POST /profile/matches/:id/outcome` enforces a minimum wait: 3 days before `failed` can be reported, 7 before `success` — encourages giving a match a real chance before either applicant can end it.
 - **Rate limiting** — in-memory sliding-window limiter on all public, admin, and applicant-portal routes.
 - **Orientation filter** — incompatible pairs are excluded *before* scoring, never just ranked low.
 - **Account deletion** — applicants can deactivate immediately or schedule a deletion with a cancellable grace period.