docs(iios): bring API guide, DEPLOYMENT, and CEO overview up to as-built

API & SDK guide:
- §5.3 Threads & Messaging fully filled in: GET/POST /v1/threads, participants,
  my-annotations; the Message shape (senderId, attachment, annotations); the full
  socket event set (open_thread/send_message/add_participant/annotate/read/typing +
  server message/receipt/typing/annotation); reactions/pins/saves as the generic
  interaction-annotation primitive; mentions → MENTION inbox item.
- §5.4 inbox MENTION kind; SDK reactions/pins/saves + listThreads/createThread;
  vocab adds MENTION, message-part kinds, attachment kind, annotation types.

DEPLOYMENT:
- Real-IdP auth env (SUPABASE_URL/AUTH_ISSUERS via JWKS, no secret) + MEDIA_SECRET.
- Media StoragePort in topology: dev local disk → prod object storage; ⚠ local disk is
  single-instance/non-durable; bytes flow client↔storage direct (scales independently).

CEO overview: refreshed counts (192 tests, 53 tables / 19 migrations) and noted P9 has
begun — real Supabase auth (first stubbed port turned real) + generic reactions/pins/
saves/mentions/media on the kernel.

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

docs/DEPLOYMENT.md

@@ -46,7 +46,14 @@ Every knob is an environment variable — see [`packages/iios-service/.env.examp
 for the full, commented list. Highlights:
 
 - **Secrets** (inject from a vault, never bake into the image): `DATABASE_URL`,
-  `APP_SECRETS` (per-app JWT signing keys), `ADAPTER_SECRETS` (webhook HMAC keys).
+  `APP_SECRETS` (per-app HS256 JWT keys), `ADAPTER_SECRETS` (webhook HMAC keys),
+  `MEDIA_SECRET` (signs presigned media upload/download URLs).
+- **Auth (real IdP):** set `SUPABASE_URL` or `AUTH_ISSUERS` to trust real OIDC access
+  tokens, verified against the issuer's public **JWKS** (ES256) — **no secret to store**.
+  `AUTH_ISSUERS` is a JSON registry `[{url, appId, orgId?}]` routing many issuers → isolated
+  app scopes. The dev HS256 path (`APP_SECRETS`) stays for local/tests.
+- **Media storage:** `MEDIA_DIR` + `PUBLIC_URL` configure the **dev** local-disk store; for
+  prod, bind the `StoragePort` to object storage (see topology) — the API/SDK don't change.
 - **⚠️ `IIOS_DEV_TOKENS` MUST be `0`/unset in production.** It exposes `/v1/dev/*`
   (unauthenticated token minting, webhook injection, chaos, retention sweep). This is the
   single most important prod-hardening flag.
@@ -76,7 +83,12 @@ for the full, commented list. Highlights:
   > by message `id`** (the payload always carries one).
 - **Platform ports** (OPA policy, CMP consent, MDM, CRRE, SAS) — today in-process permissive
   stubs (`LocalDevPorts`). For production, point these at real external services; the service
-  already calls them **fail-closed**.
+  already calls them **fail-closed**. The **session** port already verifies real OIDC tokens
+  (Supabase/JWKS) when configured.
+- **Media storage** (`StoragePort`) — dev = **local disk** (`MEDIA_DIR`). ⚠️ Local disk is
+  **single-instance and non-durable**; with N>1 replicas or for persistence, bind it to shared
+  **object storage** (S3/R2/Supabase Storage). Bytes always flow **client ↔ storage directly**
+  via presigned URLs — they never transit the service — so this scales independently.
 
 ## Scaling & release strategy