docs: README — social bindings + realtime social events

Document createSocialBindings + useSocial pattern + the three new
TenantEventMap entries (social:notification, social:post,
social:article) so consumers know the channel events exist.

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

README.md

@@ -118,10 +118,36 @@ function NotificationToasts() {
 }
 ```
 
-Known events on `TenantEventMap`: `notification`, `digital_object`, `announcement`, `status_update`, `event`. The map is open-ended — apps can subscribe to any string event arcadia emits; payload type defaults to `Record<string, unknown>`.
+Known events on `TenantEventMap`: `notification`, `digital_object`, `announcement`, `status_update`, `event`, plus social: `social:notification`, `social:post`, `social:article`. The map is open-ended — apps can subscribe to any string event arcadia emits; payload type defaults to `Record<string, unknown>`.
 
 For user-scoped events (those filtered to the current user), pass `{ scope: "user" }` and ensure `userId` was provided to the provider.
 
+## Social bindings
+
+For the social surfaces (profiles, articles, discussion board,
+favourites, DNA-change subscriptions, notifications, search,
+@-mention search), there's a typed wrapper over the generic client:
+
+```ts
+import { createArcadiaClient, createSocialBindings } from "@crema/arcadia-client";
+
+const client = createArcadiaClient({ baseUrl, getToken });
+const social = createSocialBindings(client);
+
+await social.createPost({ body_md: "hello" });
+await social.search("agent design");
+await social.addSubscription(agentId, { lastSeenDnaHash: currentHash });
+```
+
+In a React app, prefer the `useSocial()` hook pattern (see
+`arcadia-aifirst-starter/app/lib/api/social.ts`) so the bindings
+pick up the ArcadiaProvider's auth context automatically.
+
+Realtime: the social write paths broadcast via Phoenix.PubSub →
+`ArcadiaWeb.TenantChannel` forwards them as `social:notification` /
+`social:post` / `social:article` channel events. Subscribe via
+`useArcadiaSubscription`.
+
 ## What's not in here yet
 
 - **TanStack Query helpers** — opt-in. Vibespace doesn't use Query today; we can layer it via a sub-export later.