chore: update collab docs

Author: harbournick

apps/docs/core/superdoc/configuration.mdx

@@ -162,21 +162,20 @@ new SuperDoc({
 <ParamField path="modules.collaboration" type="Object">
   Real-time collaboration settings
   <Expandable title="properties" defaultOpen>
-    <ParamField path="url" type="string" required>
-      WebSocket server URL
+    <ParamField path="modules.collaboration.ydoc" type="Y.Doc" required>
+      Shared Yjs document instance for this collaborative session.
     </ParamField>
-    <ParamField path="providerType" type="string" default="'hocuspocus'">
-      Provider implementation
-    </ParamField>
-    <ParamField path="token" type="string">
-      Authentication token
-    </ParamField>
-    <ParamField path="params" type="Object">
-      Additional connection parameters
+    <ParamField path="modules.collaboration.provider" type="Object" required>
+      Yjs-compatible provider instance (for example LiveblocksYjsProvider or WebsocketProvider from y-websocket).
     </ParamField>
   </Expandable>
 </ParamField>
 
+<Note>
+  SuperDoc uses a provider-agnostic collaboration contract: `modules.collaboration = { ydoc, provider }`.
+  Provider setup remains in your app code. See [Collaboration configuration](/modules/collaboration/configuration) and [Collaboration guides](/modules/collaboration/overview).
+</Note>
+
 ### Comments module
 
 <ParamField path="modules.comments" type="Object">

apps/docs/docs.json

@@ -110,6 +110,7 @@
                 ]
               },
               "document-engine/sdks",
+              "document-engine/sdk-collaboration-sessions",
               "document-engine/cli",
               "document-engine/mcp"
             ]

apps/docs/document-engine/sdk-collaboration-sessions.mdx

@@ -0,0 +1,81 @@
+---
+title: SDK + Collaboration Sessions
+sidebarTitle: SDK + Collaboration
+description: How SDK sessions relate to Yjs collaboration sessions in SuperDoc
+keywords: "sdk collaboration, yjs session, superdoc session, liveblocks sdk, hocuspocus sdk"
+---
+
+Use this guide when you are combining:
+
+- The SuperDoc SDK (`@superdoc-dev/sdk` or `superdoc-sdk`) for headless/document automation
+- SuperDoc real-time collaboration (Yjs providers like Liveblocks, Hocuspocus, or SuperDoc Yjs)
+
+## Two session types
+
+These are different concepts:
+
+- **Collaboration session**: a shared Yjs room/document (`ydoc` + provider) used by browser editors.
+- **SDK session**: a SuperDoc Document Engine editing session created by `doc.open`.
+
+The SDK does not directly attach to a provider object. It operates through Document Engine sessions.
+
+## SuperDoc JS collaboration contract
+
+In the browser, SuperDoc uses a provider-agnostic contract:
+
+```javascript
+import * as Y from "yjs";
+import { LiveblocksYjsProvider } from "@liveblocks/yjs";
+import { SuperDoc } from "superdoc";
+
+const ydoc = new Y.Doc();
+const provider = new LiveblocksYjsProvider(room, ydoc);
+
+new SuperDoc({
+  selector: "#editor",
+  modules: {
+    collaboration: { ydoc, provider },
+  },
+});
+```
+
+See [Collaboration Configuration](/modules/collaboration/configuration) for details.
+
+## Using SDK sessions with collaboration-enabled documents
+
+The SDK can work against a document that is also edited collaboratively, but interaction is through SDK/CLI session APIs.
+
+```ts
+import { createSuperDocClient } from "@superdoc-dev/sdk";
+
+const client = createSuperDocClient();
+await client.connect();
+
+await client.doc.open({ doc: "./contract.docx" });
+
+const sessions = await client.doc.session.list();
+console.log(sessions);
+```
+
+You can target a specific active SDK session:
+
+```ts
+await client.doc.session.setDefault({ id: "session-id" });
+await client.doc.info();
+```
+
+## Provider choice is unchanged
+
+Provider setup still happens in your app using SuperDoc JS:
+
+- [Liveblocks](/guides/collaboration/liveblocks)
+- [Hocuspocus](/guides/collaboration/hocuspocus)
+- [SuperDoc Yjs](/guides/collaboration/superdoc-yjs)
+
+The SDK integration pattern does not change by provider.
+
+## Practical guidance
+
+- Use collaboration providers for multi-user real-time editing UX.
+- Use SDK sessions for backend automation, workflows, and deterministic operations.
+- Keep the distinction explicit in your architecture: provider state vs SDK/CLI session state.

apps/docs/document-engine/sdks.mdx

@@ -323,3 +323,4 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 
 - [Document API](/document-api/overview) — the in-browser API that defines the operation set
 - [CLI](/document-engine/cli) — use the same operations from the terminal
+- [SDK + Collaboration Sessions](/document-engine/sdk-collaboration-sessions) — how SDK sessions relate to Yjs collaboration sessions

apps/docs/guides/collaboration/hocuspocus.mdx

@@ -85,6 +85,8 @@ provider.on("synced", () => {
 });
 ```
 
+SuperDoc JS always uses the same collaboration contract, regardless of provider: `modules.collaboration = { ydoc, provider }`.
+
 ## React example
 
 ```tsx

apps/docs/guides/collaboration/liveblocks.mdx

@@ -59,6 +59,8 @@ provider.on("sync", (synced) => {
 });
 ```
 
+SuperDoc JS always uses the same collaboration contract, regardless of provider: `modules.collaboration = { ydoc, provider }`.
+
 ## Room management
 
 Each **room** represents a collaborative session. Use unique room IDs for different documents:

apps/docs/guides/collaboration/superdoc-yjs.mdx

@@ -50,28 +50,37 @@ fastify.listen({ port: 3050 });
 
 ### Client
 
+```bash
+npm install yjs y-websocket
+```
+
 ```javascript
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
 import { SuperDoc } from 'superdoc';
 
+const documentId = 'document-123';
+const ydoc = new Y.Doc();
+const provider = new WebsocketProvider(
+  `ws://localhost:3050/doc/${documentId}`,
+  documentId,
+  ydoc
+);
+
 new SuperDoc({
   selector: '#editor',
-  document: {
-    id: 'document-123',
-    type: 'docx'
-  },
   user: {
     name: 'John Smith',
     email: 'john@example.com'
   },
   modules: {
-    collaboration: {
-      url: 'ws://localhost:3050/doc',
-      token: 'auth-token'
-    }
+    collaboration: { ydoc, provider }
   }
 });
 ```
 
+The SuperDoc JS collaboration contract is provider-agnostic: always pass `{ ydoc, provider }` in `modules.collaboration`.
+
 ## Builder API
 
 The `CollaborationBuilder` provides a fluent interface:

apps/docs/modules/collaboration/configuration.mdx

@@ -6,6 +6,8 @@ keywords: "collaboration configuration, superdoc events, awareness, user presenc
 
 All configuration options and events for real-time collaboration.
 
+If you need to combine collaboration with headless SDK automation, see [SDK + Collaboration Sessions](/document-engine/sdk-collaboration-sessions).
+
 ## Configuration
 
 **You manage the Yjs provider** — works with SuperDoc Yjs, Liveblocks, Hocuspocus, etc.

apps/docs/modules/collaboration/overview.mdx

@@ -69,3 +69,5 @@ provider.on("sync", (synced) => {
 ```
 
 See the [full quickstart guide](/modules/collaboration/quickstart) for framework-specific examples (React, Vue, Vanilla JS).
+
+If you are also using the SDK for backend automation, see [SDK + Collaboration Sessions](/document-engine/sdk-collaboration-sessions).