@agent-native/core 0.115.4 → 0.117.0

package/corpus/core/src/server/realtime-token.ts

@@ -0,0 +1,106 @@
+/**
+ * Realtime subscribe-token mint endpoint.
+ *
+ * `GET /_agent-native/realtime-token` — the one Netlify request per page load
+ * that the hosted Realtime Gateway path needs. The SSR HTML/`.data` shell is a
+ * single impersonal, CDN-cached document (`guard:ssr-cache-shell`), so a
+ * per-visitor token cannot be baked into the page; the client mints it here
+ * after load. Same-origin + session-gated; sessionless requests get 401.
+ *
+ * The signed token binds this app's Builder project id (the gateway channel)
+ * and carries the app's own end-user identity (`owner` = session email, `orgId`
+ * = framework org) — the exact tuple `recordChange` stamps onto `sync_events`
+ * and the gateway feeds to `canSeeChangeForUser`. It is signed with the app's
+ * per-project HMAC secret, injected as a reserved env var at provision time.
+ */
+
+import {
+  defineEventHandler,
+  getMethod,
+  type H3Event,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import { getOrgContext } from "../org/context.js";
+import { getSession } from "./auth.js";
+import { resolveBuilderBranchProjectId } from "./builder-browser.js";
+import { runWithRequestContext } from "./request-context.js";
+import { isSameOriginRequest } from "./request-origin.js";
+import { signRealtimeSubscribeToken } from "./short-lived-token.js";
+
+/**
+ * Reserved env var holding the app's per-project HMAC secret. Injected by the
+ * Builder provisioning path (`SYSTEM_RESERVED_KEYS` + prod allowlist); see the
+ * Agent-Native Realtime Sync tech spec.
+ */
+export const REALTIME_HMAC_SECRET_ENV = "AGENT_NATIVE_REALTIME_HMAC_SECRET";
+
+/** Short TTL — validated at connect; the gateway rotates over the stream. */
+const REALTIME_TOKEN_TTL_SECONDS = 600;
+
+export function getRealtimeSigningSecret(): string | undefined {
+  return process.env[REALTIME_HMAC_SECRET_ENV]?.trim() || undefined;
+}
+
+export function createRealtimeTokenHandler() {
+  return defineEventHandler(async (event: H3Event) => {
+    // Identity-bearing token, valid ~10 min — never cacheable by the browser or
+    // any intermediary. Set once up front so every return path carries it.
+    setResponseHeader(event, "Cache-Control", "private, no-store");
+
+    if (getMethod(event) !== "GET") {
+      setResponseStatus(event, 405);
+      return { error: "Method not allowed" };
+    }
+    if (!isSameOriginRequest(event)) {
+      setResponseStatus(event, 403);
+      return { error: "Cross-origin request rejected" };
+    }
+
+    const session = await getSession(event).catch(() => null);
+    if (!session?.email) {
+      setResponseStatus(event, 401);
+      return { error: "Authentication required" };
+    }
+
+    const orgCtx = await getOrgContext(event).catch(() => null);
+    const requestContext = {
+      userEmail: session.email,
+      orgId: orgCtx?.orgId ?? session.orgId,
+    };
+
+    // The scoped-secret fallback inside resolveBuilderBranchProjectId reads the
+    // request-context ALS (resolveSecret -> getRequestUserEmail); without it the
+    // user/org/workspace scopes silently no-op and only env vars resolve. Wrap
+    // the resolution like google-realtime-session.ts does.
+    return runWithRequestContext(requestContext, async () => {
+      // Async resolver so hosted apps whose project id lives in a
+      // request-scoped app/org/workspace secret (not an env var) also work —
+      // the sync env-only lookup would 404 them and silently drop the gateway.
+      const projectId = await resolveBuilderBranchProjectId();
+      const secret = getRealtimeSigningSecret();
+      if (!projectId || !secret) {
+        // Hosted realtime isn't provisioned for this app. 404 lets the client
+        // fall back to the app's own /_agent-native/poll without treating it
+        // as an auth failure.
+        setResponseStatus(event, 404);
+        return { error: "Realtime gateway not configured" };
+      }
+
+      const token = signRealtimeSubscribeToken(
+        {
+          projectId,
+          owner: session.email,
+          orgId: requestContext.orgId,
+          ttlSeconds: REALTIME_TOKEN_TTL_SECONDS,
+        },
+        secret,
+      );
+      const expiresAt = new Date(
+        Date.now() + REALTIME_TOKEN_TTL_SECONDS * 1000,
+      ).toISOString();
+      return { token, expiresAt, ttlSeconds: REALTIME_TOKEN_TTL_SECONDS };
+    });
+  });
+}

package/corpus/core/src/server/sentry-config.ts

@@ -71,3 +71,43 @@ export function getSentryClientConfigScript(): string | null {
     "</script>",
   ].join("");
 }
+
+/**
+ * Hosted Realtime Gateway config for the client, or null for the in-process
+ * (local) transport. Values are env-derived and identical for every visitor,
+ * so this is safe inside the CDN-cached SSR shell (see `guard:ssr-cache-shell`).
+ * The per-user subscribe token is NOT here — it is minted client-side after
+ * load from `/_agent-native/realtime-token`.
+ */
+export function resolveRealtimeClientConfig(): {
+  transport: "hosted";
+  gatewayBaseUrl: string;
+} | null {
+  // Fail closed: emit hosted config only when BOTH the transport is hosted AND
+  // an explicit gateway URL is set. No production default — this ships into the
+  // CDN-cached shell served to every visitor, so a mis-set staging/preview/
+  // self-hosted env must stay on the local transport rather than silently
+  // point every browser at api.builder.io. This gating is mirrored byte-for-
+  // byte in the worker emitter in `deploy/build.ts` (kept in sync deliberately).
+  if (firstNonEmpty(process.env.AGENT_NATIVE_REALTIME_TRANSPORT) !== "hosted") {
+    return null;
+  }
+  const gatewayBaseUrl = firstNonEmpty(
+    process.env.AGENT_NATIVE_REALTIME_GATEWAY_URL,
+  );
+  if (!gatewayBaseUrl) return null;
+  return { transport: "hosted", gatewayBaseUrl };
+}
+
+export function getRealtimeClientConfigScript(): string | null {
+  const realtime = resolveRealtimeClientConfig();
+  if (!realtime) return null;
+
+  return [
+    "<script data-agent-native-realtime-config>",
+    "window.__AGENT_NATIVE_CONFIG__=Object.assign({},window.__AGENT_NATIVE_CONFIG__,",
+    JSON.stringify({ realtime }),
+    ");",
+    "</script>",
+  ].join("");
+}

package/corpus/core/src/server/short-lived-token.ts

@@ -168,3 +168,159 @@ export function verifyShortLivedToken(
 
   return { ok: true, viewerEmail: claims.viewerEmail };
 }
+
+// ── Realtime subscribe tokens ────────────────────────────────────────────────
+//
+// An identity-bearing extension of the same HMAC discipline, used by the hosted
+// Realtime Gateway. Differs from the media token above in three ways the gateway
+// depends on:
+//   1. It is signed with a caller-supplied PER-PROJECT key (the app's HMAC
+//      secret), not the single deployment-wide `getSigningKey()`. The app server
+//      mints with it; the gateway (a second issuer for stream rotation) verifies
+//      and re-mints with the same per-project key. A token minted for project A
+//      fails signature verification against project B's key.
+//   2. It carries authorization-bearing identity (`owner`/`orgId`) that the
+//      gateway feeds to `canSeeChangeForUser` — the media token's `viewerEmail`
+//      is audit-only by contract, so a new field is required, not repurposed.
+//   3. It binds `projectId` as the channel and stamps a `typ` discriminator, so
+//      it is verified against the connect channel and cannot be replayed as a
+//      media token (or vice-versa) even if keys ever overlapped.
+
+/** Payload `typ` discriminator for realtime subscribe tokens. */
+export const REALTIME_SUBSCRIBE_TOKEN_TYPE = "rt-subscribe";
+const DEFAULT_REALTIME_TTL_SECONDS = 600;
+
+/** Inputs for {@link signRealtimeSubscribeToken}. */
+export interface RealtimeSubscribeClaims {
+  /** Channel — one Neon project per app. Verified at connect, not just carried. */
+  projectId: string;
+  /**
+   * App end-user session email (NOT a Builder.io account — see the tech spec).
+   * Fed to `canSeeChangeForUser`. Present in v0.
+   */
+  owner?: string;
+  /** Framework org id for the app's end-user. */
+  orgId?: string;
+  /** Override default TTL (seconds). */
+  ttlSeconds?: number;
+}
+
+interface DecodedRealtimeClaims {
+  typ: string;
+  projectId: string;
+  owner?: string;
+  orgId?: string;
+  exp: number;
+}
+
+/**
+ * Result of {@link verifyRealtimeSubscribeToken}. On success it returns the
+ * identity claims the gateway uses to scope delivery.
+ */
+export type RealtimeVerifyResult =
+  | {
+      ok: true;
+      projectId: string;
+      owner?: string;
+      orgId?: string;
+      exp: number;
+    }
+  | { ok: false; reason: string };
+
+function hmacB64(payloadStr: string, key: string): string {
+  return base64UrlEncode(
+    crypto.createHmac("sha256", key).update(payloadStr).digest(),
+  );
+}
+
+function timingSafeEqualB64(sig: string, expected: string): boolean {
+  const sigBuf = Buffer.from(sig, "utf8");
+  const expBuf = Buffer.from(expected, "utf8");
+  if (sigBuf.length !== expBuf.length) {
+    crypto.timingSafeEqual(expBuf, expBuf); // burn ~equal cycles
+    return false;
+  }
+  return crypto.timingSafeEqual(sigBuf, expBuf);
+}
+
+/**
+ * Mint a realtime subscribe token for `claims.projectId`, signed with the
+ * app's per-project `key`. Safe to place on the connect query string (short
+ * TTL, single-purpose, channel-bound). Verified by
+ * {@link verifyRealtimeSubscribeToken} at connect.
+ */
+export function signRealtimeSubscribeToken(
+  claims: RealtimeSubscribeClaims,
+  key: string,
+): string {
+  if (!key) throw new Error("signRealtimeSubscribeToken requires a key");
+  // Fail closed: a token with neither owner nor orgId carries no authorization
+  // identity, so canSeeChangeForUser would only ever match global/unowned
+  // events. Every issuer (mint endpoint + the gateway's rotation re-mint) must
+  // supply at least one identity claim.
+  if (!claims.owner && !claims.orgId) {
+    throw new Error(
+      "signRealtimeSubscribeToken requires an owner or orgId claim",
+    );
+  }
+  const ttl = claims.ttlSeconds ?? DEFAULT_REALTIME_TTL_SECONDS;
+  const payload: DecodedRealtimeClaims = {
+    typ: REALTIME_SUBSCRIBE_TOKEN_TYPE,
+    projectId: claims.projectId,
+    exp: Math.floor(Date.now() / 1000) + ttl,
+  };
+  if (claims.owner) payload.owner = claims.owner;
+  if (claims.orgId) payload.orgId = claims.orgId;
+
+  const payloadStr = base64UrlEncode(JSON.stringify(payload));
+  return `${payloadStr}.${hmacB64(payloadStr, key)}`;
+}
+
+/**
+ * Verify a realtime subscribe token against the app's per-project `key` and the
+ * connect channel `projectId`. Returns the identity claims only when the shape,
+ * signature (constant-time), `typ`, `exp`, and `projectId` binding all hold.
+ */
+export function verifyRealtimeSubscribeToken(
+  token: string,
+  expected: { projectId: string; key: string },
+): RealtimeVerifyResult {
+  if (!expected.key) return { ok: false, reason: "no_key" };
+  if (typeof token !== "string" || !token.includes(".")) {
+    return { ok: false, reason: "malformed" };
+  }
+  const [payloadStr, sig] = token.split(".", 2);
+  if (!payloadStr || !sig) return { ok: false, reason: "malformed" };
+
+  if (!timingSafeEqualB64(sig, hmacB64(payloadStr, expected.key))) {
+    return { ok: false, reason: "bad_signature" };
+  }
+
+  let claims: DecodedRealtimeClaims;
+  try {
+    claims = JSON.parse(base64UrlDecode(payloadStr).toString("utf8"));
+  } catch {
+    return { ok: false, reason: "bad_payload" };
+  }
+
+  if (claims.typ !== REALTIME_SUBSCRIBE_TOKEN_TYPE) {
+    return { ok: false, reason: "wrong_type" };
+  }
+  if (typeof claims.exp !== "number") {
+    return { ok: false, reason: "bad_payload" };
+  }
+  if (claims.exp * 1000 < Date.now()) {
+    return { ok: false, reason: "expired" };
+  }
+  if (claims.projectId !== expected.projectId) {
+    return { ok: false, reason: "wrong_project" };
+  }
+
+  return {
+    ok: true,
+    projectId: claims.projectId,
+    owner: claims.owner,
+    orgId: claims.orgId,
+    exp: claims.exp,
+  };
+}

package/corpus/core/src/server/sse.ts

@@ -1,5 +1,20 @@
 import { defineEventHandler, createEventStream } from "h3";
 
+// Re-export the wire protocol so server consumers (the hosted Realtime Gateway
+// in ai-services) get the frame contract from the same `./server/sse` subpath.
+// The browser client imports it directly from `../realtime-protocol.js`.
+export {
+  buildHandshakeFrame,
+  parseHandshakeFrame,
+  parseTokenFrame,
+  REALTIME_CAP_NO_AWARENESS,
+  REALTIME_PROTOCOL_VERSION,
+  REALTIME_SSE_HANDSHAKE_EVENT,
+  REALTIME_SSE_TOKEN_EVENT,
+  type RealtimeHandshake,
+  type RealtimeTokenFrame,
+} from "../realtime-protocol.js";
+
 /** Any object with on/off methods (compatible with EventEmitter, TypedEventEmitter, etc.). */
 interface EventLike {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/corpus/core/src/server/ssr-handler.ts

@@ -37,7 +37,10 @@ import {
 } from "./app-base-path.js";
 import { captureError } from "./capture-error.js";
 import { runWithRequestContext } from "./request-context.js";
-import { getSentryClientConfigScript } from "./sentry-config.js";
+import {
+  getRealtimeClientConfigScript,
+  getSentryClientConfigScript,
+} from "./sentry-config.js";
 
 export {
   DEFAULT_SSR_CACHE_HEADERS,
@@ -342,7 +345,10 @@ async function rewriteMountedResponse(
   pathname: string,
   requestUrl: string,
 ): Promise<Response> {
-  const sentryClientConfigScript = getSentryClientConfigScript();
+  const clientConfigScript =
+    [getSentryClientConfigScript(), getRealtimeClientConfigScript()]
+      .filter(Boolean)
+      .join("") || null;
   const headers = new Headers(response.headers);
   applyDefaultSsrCacheHeader(headers, response.status, pathname);
   applyDefaultSpeculationRulesHeader(headers, response.status, basePath);
@@ -377,7 +383,7 @@ async function rewriteMountedResponse(
         prefixMountedHtml(html, basePath),
         defaultSocialImageUrl(requestUrl, basePath),
       ),
-      sentryClientConfigScript,
+      clientConfigScript,
     ),
     {
       status: response.status,

package/corpus/core/src/styles/agent-native.css

@@ -927,7 +927,35 @@
   display: inline-block;
 }
 
+.agent-tool-call {
+  position: relative;
+}
+
 @media (prefers-reduced-motion: no-preference) {
+  .agent-tool-call--entering {
+    animation: agent-tool-call-enter 220ms var(--ease-out-strong) both;
+  }
+
+  .agent-tool-call[data-active-tail="true"]::after {
+    position: absolute;
+    z-index: 1;
+    inset: 0 0 auto;
+    height: 2rem;
+    pointer-events: none;
+    content: "";
+    background: linear-gradient(
+      90deg,
+      transparent 0%,
+      transparent 38%,
+      hsl(var(--foreground) / 0.055) 50%,
+      transparent 62%,
+      transparent 100%
+    );
+    background-repeat: repeat;
+    background-size: 14rem 100%;
+    animation: agent-thinking-shine 2.6s linear infinite;
+  }
+
   @supports ((background-clip: text) or (-webkit-background-clip: text)) {
     .agent-thinking-indicator__text,
     .agent-running-shimmer {
@@ -960,6 +988,18 @@
     }
   }
 
+  @keyframes agent-tool-call-enter {
+    from {
+      opacity: 0;
+      transform: translateY(0.375rem);
+    }
+
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
   @supports (view-transition-name: agent-native-chat) {
     .agent-native-chat-view-transition {
       contain: layout;

package/corpus/core/src/templates/default/.agents/skills/agent-native-toolkit/SKILL.md

@@ -85,7 +85,10 @@ in the moment of agent use.
   approval, generative UI, progress, and screen-state exposure.
 - **Chat history kit**: presentational chat lists and recent-chat rails belong
   in Toolkit; Core keeps thread persistence, agent execution, transport, and
-  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+  page-to-sidebar handoff. Use Toolkit's `ChatHistoryRail` for the standard
+  five-item sidebar preview and a footer row with New chat followed by an
+  ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
+  actions.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

package/corpus/core/src/templates/default/.agents/skills/real-time-collab/SKILL.md

@@ -16,7 +16,7 @@ metadata:
 
 Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are
 equal participants — both edit the same Y.Doc and changes merge cleanly without
-conflicts. Always set `resourceType` on `createCollabPlugin`.
+conflicts. Always choose an explicit `access` mode on `createCollabPlugin`.
 
 ## How It Works
 
@@ -104,7 +104,16 @@ in **different** regions merge fine through the CRDT.
 
 ## Security
 
-### Always set `resourceType`
+### Always choose an explicit access mode
+
+Inspect the schema and sharing registration before configuring collaboration:
+
+- For owned or shareable records, use `mode: "resource"` and the resource type
+  registered through `registerShareableResource`.
+- For records deliberately visible to every authenticated user on the
+  deployment, use `mode: "all-authenticated"`.
+- Never invent a `resourceType` merely to silence a warning. Resource mode is
+  correct only when the matching ownership and sharing model exists.
 
 ```ts
 // server/plugins/collab.ts
@@ -114,14 +123,23 @@ export default createCollabPlugin({
   table: "documents",
   contentColumn: "content",
   idColumn: "id",
-  resourceType: "document", // required
+  access: { mode: "resource", resourceType: "document" },
 });
 ```
 
-Without `resourceType`, the server logs a one-time warning and collab push
-events are delivered to **all authenticated users** without document-level
-scoping. Set it to the resource type name registered via
-`registerShareableResource`.
+For intentionally deployment-wide authenticated collaboration:
+
+```ts
+createCollabPlugin({
+  table: "todos",
+  contentColumn: "content",
+  access: { mode: "all-authenticated" },
+});
+```
+
+Omitting `access` is supported only for legacy compatibility and is deprecated.
+It behaves like `all-authenticated`, logs a warning, and is flagged by Doctor.
+Choose the mode explicitly so access intent is reviewable.
 
 Non-owner sharees who have explicit access fall back to state-vector catch-up
 (safe, slightly higher latency). Awareness routes require the same viewer
@@ -133,7 +151,10 @@ Write routes reject payloads exceeding `maxPayloadBytes` (default 2 MB) with
 HTTP 413. Override:
 
 ```ts
-createCollabPlugin({ resourceType: "document", maxPayloadBytes: 512 * 1024 });
+createCollabPlugin({
+  access: { mode: "resource", resourceType: "document" },
+  maxPayloadBytes: 512 * 1024,
+});
 ```
 
 ## Enabling Collaboration
@@ -144,7 +165,7 @@ createCollabPlugin({ resourceType: "document", maxPayloadBytes: 512 * 1024 });
 pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core
 ```
 
-### 2. Add collab server plugin (with `resourceType`)
+### 2. Add collab server plugin (with explicit access)
 
 ```ts
 // server/plugins/collab.ts
@@ -154,7 +175,7 @@ export default createCollabPlugin({
   table: "documents",
   contentColumn: "content",
   idColumn: "id",
-  resourceType: "document",
+  access: { mode: "resource", resourceType: "document" },
 });
 ```
 
@@ -343,9 +364,10 @@ the whole history — external/agent edits must not wipe the user's undo stack.
 
 ## Common Pitfalls
 
-- **Missing `resourceType`** — The server logs a warning on startup and
-  delivers collab events to all authenticated users without access scoping.
-  Always set `resourceType`.
+- **Missing `access`** — Legacy omission behaves like `all-authenticated`, logs
+  a startup warning, and is flagged by Doctor. Choose `resource` for records
+  backed by ownership/sharing, or explicit `all-authenticated` for intentionally
+  deployment-wide records. Never invent a resource type to silence the warning.
 - **Don't pass `content` as a TipTap prop** when Collaboration is enabled —
   Yjs owns the content. Seed via `editor.commands.setContent()` only when the
   Y.XmlFragment is empty.

package/corpus/core/src/templates/default/.agents/skills/real-time-sync/SKILL.md

@@ -72,7 +72,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
   });
   ```
 
-  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events. Hidden tabs keep that shared transport alive by default: SSE stays connected and active fallback polling relaxes to a 10-second floor (idle polling remains once per minute). Pass `pauseWhenHidden: true` only for a consumer that explicitly must stop all hidden-tab sync.
 
 ## Which sources to depend on
 

package/corpus/core/src/templates/headless/.agents/skills/agent-native-toolkit/SKILL.md

@@ -85,7 +85,10 @@ in the moment of agent use.
   approval, generative UI, progress, and screen-state exposure.
 - **Chat history kit**: presentational chat lists and recent-chat rails belong
   in Toolkit; Core keeps thread persistence, agent execution, transport, and
-  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+  page-to-sidebar handoff. Use Toolkit's `ChatHistoryRail` for the standard
+  five-item sidebar preview and a footer row with New chat followed by an
+  ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
+  actions.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

package/corpus/core/src/templates/workspace-core/.agents/skills/agent-native-toolkit/SKILL.md

@@ -85,7 +85,10 @@ in the moment of agent use.
   approval, generative UI, progress, and screen-state exposure.
 - **Chat history kit**: presentational chat lists and recent-chat rails belong
   in Toolkit; Core keeps thread persistence, agent execution, transport, and
-  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+  page-to-sidebar handoff. Use Toolkit's `ChatHistoryRail` for the standard
+  five-item sidebar preview and a footer row with New chat followed by an
+  ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
+  actions.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

package/corpus/core/src/templates/workspace-core/.agents/skills/real-time-collab/SKILL.md

@@ -16,7 +16,7 @@ metadata:
 
 Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are
 equal participants — both edit the same Y.Doc and changes merge cleanly without
-conflicts. Always set `resourceType` on `createCollabPlugin`.
+conflicts. Always choose an explicit `access` mode on `createCollabPlugin`.
 
 ## How It Works
 
@@ -104,7 +104,16 @@ in **different** regions merge fine through the CRDT.
 
 ## Security
 
-### Always set `resourceType`
+### Always choose an explicit access mode
+
+Inspect the schema and sharing registration before configuring collaboration:
+
+- For owned or shareable records, use `mode: "resource"` and the resource type
+  registered through `registerShareableResource`.
+- For records deliberately visible to every authenticated user on the
+  deployment, use `mode: "all-authenticated"`.
+- Never invent a `resourceType` merely to silence a warning. Resource mode is
+  correct only when the matching ownership and sharing model exists.
 
 ```ts
 // server/plugins/collab.ts
@@ -114,14 +123,23 @@ export default createCollabPlugin({
   table: "documents",
   contentColumn: "content",
   idColumn: "id",
-  resourceType: "document", // required
+  access: { mode: "resource", resourceType: "document" },
 });
 ```
 
-Without `resourceType`, the server logs a one-time warning and collab push
-events are delivered to **all authenticated users** without document-level
-scoping. Set it to the resource type name registered via
-`registerShareableResource`.
+For intentionally deployment-wide authenticated collaboration:
+
+```ts
+createCollabPlugin({
+  table: "todos",
+  contentColumn: "content",
+  access: { mode: "all-authenticated" },
+});
+```
+
+Omitting `access` is supported only for legacy compatibility and is deprecated.
+It behaves like `all-authenticated`, logs a warning, and is flagged by Doctor.
+Choose the mode explicitly so access intent is reviewable.
 
 Non-owner sharees who have explicit access fall back to state-vector catch-up
 (safe, slightly higher latency). Awareness routes require the same viewer
@@ -133,7 +151,10 @@ Write routes reject payloads exceeding `maxPayloadBytes` (default 2 MB) with
 HTTP 413. Override:
 
 ```ts
-createCollabPlugin({ resourceType: "document", maxPayloadBytes: 512 * 1024 });
+createCollabPlugin({
+  access: { mode: "resource", resourceType: "document" },
+  maxPayloadBytes: 512 * 1024,
+});
 ```
 
 ## Enabling Collaboration
@@ -144,7 +165,7 @@ createCollabPlugin({ resourceType: "document", maxPayloadBytes: 512 * 1024 });
 pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core
 ```
 
-### 2. Add collab server plugin (with `resourceType`)
+### 2. Add collab server plugin (with explicit access)
 
 ```ts
 // server/plugins/collab.ts
@@ -154,7 +175,7 @@ export default createCollabPlugin({
   table: "documents",
   contentColumn: "content",
   idColumn: "id",
-  resourceType: "document",
+  access: { mode: "resource", resourceType: "document" },
 });
 ```
 
@@ -343,9 +364,10 @@ the whole history — external/agent edits must not wipe the user's undo stack.
 
 ## Common Pitfalls
 
-- **Missing `resourceType`** — The server logs a warning on startup and
-  delivers collab events to all authenticated users without access scoping.
-  Always set `resourceType`.
+- **Missing `access`** — Legacy omission behaves like `all-authenticated`, logs
+  a startup warning, and is flagged by Doctor. Choose `resource` for records
+  backed by ownership/sharing, or explicit `all-authenticated` for intentionally
+  deployment-wide records. Never invent a resource type to silence the warning.
 - **Don't pass `content` as a TipTap prop** when Collaboration is enabled —
   Yjs owns the content. Seed via `editor.commands.setContent()` only when the
   Y.XmlFragment is empty.