From 70803b9f601d8ff05c3efad97c4f165fa2715bd6 Mon Sep 17 00:00:00 2001
From: jules <cloudtech@juleslive.net>
Date: Sat, 16 May 2026 15:46:19 +1000
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=94=20social=20bindings?=
 =?UTF-8?q?=20+=20realtime=20social=20events?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 79987f4..39da08f 100644
--- a/README.md
+++ b/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.