@agent-native/core 0.46.0 → 0.48.1

package/docs/content/components.md

@@ -0,0 +1,308 @@
+---
+title: "Component API"
+description: "Public React building blocks for custom agent UI, chat fields, conversation rendering, realtime presence, sharing, progress, and rich editors."
+---
+
+# Component API
+
+Agent-Native ships a full sidebar, but the sidebar is not the contract. The
+contract is the runtime: chat streaming, thread state, actions, context,
+attachments, model selection, runs, and SQL-backed sync. Use the stock
+components when you can, and drop down a layer when you need custom product UI.
+
+Import browser UI from focused client subpaths:
+
+```tsx
+import { AgentSidebar } from "@agent-native/core/client";
+import { PromptComposer } from "@agent-native/core/client/composer";
+import { AgentConversation } from "@agent-native/core/client/conversation";
+import { usePresence } from "@agent-native/core/client/collab";
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+import { ResourcesPanel } from "@agent-native/core/client/resources";
+```
+
+Avoid importing UI components from the bare `@agent-native/core` package. Use
+`@agent-native/core/client` or a focused `@agent-native/core/client/*` subpath
+so bundlers choose the browser-safe entry.
+
+## Agent And Chat UI {#agent-chat-ui}
+
+| API                        | Import path                                   | Use when                                                                                         |
+| -------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `<AgentSidebar>`           | `@agent-native/core/client` or `/client/chat` | You want the complete sidebar around your app.                                                   |
+| `<AgentToggleButton>`      | `@agent-native/core/client` or `/client/chat` | You render your own header button for the sidebar.                                               |
+| `<AgentPanel>`             | `@agent-native/core/client` or `/client/chat` | You want the full panel in your own layout, route, dialog, or side column.                       |
+| `<AgentChatSurface>`       | `@agent-native/core/client` or `/client/chat` | You want chat in panel or page mode without the sidebar wrapper.                                 |
+| `<AssistantChat>`          | `@agent-native/core/client` or `/client/chat` | You want to own surrounding chrome while keeping the standard conversation and composer runtime. |
+| `<MultiTabAssistantChat>`  | `@agent-native/core/client` or `/client/chat` | You want the framework's thread tabs without `AgentPanel` chrome.                                |
+| `createAgentChatAdapter()` | `@agent-native/core/client` or `/client/chat` | You are building a custom assistant-ui runtime and need the Agent-Native chat transport.         |
+| `useChatThreads()`         | `@agent-native/core/client` or `/client/chat` | You need a custom thread list, history picker, or scoped chat UI.                                |
+| `sendToAgentChat()`        | `@agent-native/core/client` or `/client/chat` | A product action should hand work to the agent chat.                                             |
+
+The shortest custom route is still a pre-wired surface:
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+For custom chrome around the standard runtime:
+
+```tsx
+import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";
+
+function CustomChat({ projectSlug }: { projectSlug: string }) {
+  const threads = useChatThreads(undefined, projectSlug);
+  const threadId = threads.activeThreadId ?? undefined;
+
+  return (
+    <section className="grid h-full grid-cols-[260px_1fr]">
+      <ThreadList
+        threads={threads.threads}
+        activeThreadId={threadId}
+        onSelect={threads.switchThread}
+      />
+      <AssistantChat threadId={threadId} />
+    </section>
+  );
+}
+```
+
+## Chat Field And Composer {#composer}
+
+Use `@agent-native/core/client/composer` when you need to place the same chat
+field used by the sidebar inside custom UI.
+
+| API                               | Use when                                                                                                                                                            |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<PromptComposer>`                | You need a ready-to-submit chat field with attachments, slash commands, references, pasted-text handling, draft persistence, voice input, and submission semantics. |
+| `<AgentComposerFrame>`            | You want the standard visual shell around a custom composer body.                                                                                                   |
+| `<TiptapComposer>`                | You need the lowest-level rich chat field. It must be rendered inside an assistant-ui `ThreadPrimitive.Root` / composer runtime.                                    |
+| `buildPromptComposerSubmission()` | You need the same attachment and pasted-text normalization before calling your own submit handler.                                                                  |
+| `formatPromptWithAttachments()`   | You need to render hidden attachment metadata into a prompt string.                                                                                                 |
+
+Most custom UIs should start with `PromptComposer`:
+
+```tsx
+import { PromptComposer } from "@agent-native/core/client/composer";
+
+<PromptComposer
+  placeholder="Ask the agent..."
+  onSubmit={async (text, files, references, options) => {
+    await sendMessageToYourRuntime({ text, files, references, options });
+  }}
+/>;
+```
+
+Use `TiptapComposer` only if you are already wiring assistant-ui primitives
+yourself. It is the field, not the whole chat runtime.
+
+## Conversation Rendering {#conversation}
+
+Use `@agent-native/core/client/conversation` for transcript-style rendering
+outside the full agent runtime.
+
+| API                                             | Use when                                                         |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| `<AgentConversation>`                           | Render a list of normalized agent messages.                      |
+| `<AgentConversationMessageView>`                | Render one normalized message.                                   |
+| `normalizeCodeAgentTranscriptForConversation()` | Convert code-agent transcript events into conversation messages. |
+| `useNearBottomAutoscroll()`                     | Keep a custom transcript pinned to the bottom while streaming.   |
+
+This layer is intentionally data-first: you own where messages come from, and
+the renderer owns consistent markdown, attachments, notices, artifacts, and
+tool-call display.
+
+## Realtime Collab And Presence {#collab-presence}
+
+Use `@agent-native/core/client/collab` for Liveblocks-style presence and
+collaborative document hooks.
+
+| API                                                 | Use when                                                                                    |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `useCollaborativeDoc()`                             | Bind a rich text editor or custom Yjs surface to `/_agent-native/collab`.                   |
+| `usePresence()`                                     | Publish and render arbitrary awareness fields: cursors, selections, viewport, mode.         |
+| `<PresenceBar>`                                     | Show active human and agent collaborators.                                                  |
+| `<LiveCursorOverlay>`                               | Render remote cursor labels over a positioned container.                                    |
+| `<RemoteSelectionRings>`                            | Render remote selection outlines over DOM elements.                                         |
+| `useFollowUser()`                                   | Follow another participant's viewport or selection.                                         |
+| `useCollaborativeMap()` / `useCollaborativeArray()` | Experiment with structured Y.Map/Y.Array state when rich-text body collab is the wrong fit. |
+| `dedupeCollabUsersByEmail()`                        | Build a custom avatar stack without duplicate tabs for the same user.                       |
+
+Server-side agent actions that want to appear as a live participant use the
+lower-level `@agent-native/core/collab` agent presence helpers:
+
+```ts
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+```
+
+## Rich Editor {#rich-editor}
+
+Use `@agent-native/core/client/editor` when you need the shared markdown editor
+surface used by plans, content, resources, and collaborative document
+experiences.
+
+| API                              | Use when                                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `<SharedRichEditor>`             | You need the current, configurable editor with markdown serialization, optional Yjs, and app extras. |
+| `<RichMarkdownEditor>`           | You need the backwards-compatible alias for the shared rich editor.                                  |
+| `createSharedEditorExtensions()` | You are building your own Tiptap editor but want the framework schema and markdown dialects.         |
+| `<SlashCommandMenu>`             | You need the shared slash-command UI for a custom Tiptap surface.                                    |
+| `<BubbleToolbar>`                | You need the shared selection toolbar for marks, links, and custom inline actions.                   |
+| `createRegistryBlockNode()`      | You need registry-backed block nodes inside a rich editor.                                           |
+| `uploadEditorImage()`            | You want the framework upload-image action behind the editor's shared image block.                   |
+| `useCollabReconcile()`           | You are binding a custom editor surface to a Yjs doc while preserving markdown as saved state.       |
+
+The basic controlled editor is just markdown in and markdown out:
+
+```tsx
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+
+<SharedRichEditor
+  value={markdown}
+  onChange={setMarkdown}
+  placeholder="Write notes..."
+  features={{ tables: true, tasks: true, link: true }}
+/>;
+```
+
+For realtime editing, pair it with the collab subpath:
+
+```tsx
+import {
+  emailToColor,
+  useCollaborativeDoc,
+} from "@agent-native/core/client/collab";
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+
+const editorUser = {
+  name: user.name,
+  email: user.email,
+  color: emailToColor(user.email),
+};
+const collab = useCollaborativeDoc({
+  docId,
+  user: editorUser,
+});
+
+<SharedRichEditor
+  value={markdown}
+  onChange={setMarkdown}
+  ydoc={collab.ydoc}
+  awareness={collab.awareness}
+  user={editorUser}
+/>;
+```
+
+## Workspace Resources {#resources}
+
+Use `@agent-native/core/client/resources` when you want to expose the same
+workspace resource model that powers the agent panel's Workspace tab.
+
+| API                                                                   | Use when                                                                |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `<ResourcesPanel>`                                                    | You want the complete Workspace tab as a page, drawer, or custom panel. |
+| `<ResourceTree>`                                                      | You want to render your own resource browser around framework data.     |
+| `<ResourceEditor>`                                                    | You want the framework editor for a selected resource.                  |
+| `useResourceTree()`                                                   | You need a scoped tree for personal, shared, or workspace resources.    |
+| `useResource()`                                                       | You need the content and metadata for one selected resource.            |
+| `useCreateResource()` / `useUpdateResource()` / `useDeleteResource()` | You need custom controls around the resource lifecycle.                 |
+| `useUploadResource()`                                                 | You need file upload into the framework resource store.                 |
+
+The complete panel needs no props:
+
+```tsx
+import { ResourcesPanel } from "@agent-native/core/client/resources";
+
+<ResourcesPanel />;
+```
+
+For custom resource chrome, keep the hooks and primitives together:
+
+```tsx
+import { useState } from "react";
+import {
+  ResourceEditor,
+  ResourceTree,
+  useResource,
+  useResourceTree,
+  useUpdateResource,
+} from "@agent-native/core/client/resources";
+
+function WorkspaceResources() {
+  const tree = useResourceTree("workspace");
+  const updateResource = useUpdateResource();
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const resource = useResource(selectedId);
+
+  return (
+    <div className="grid h-full grid-cols-[260px_1fr]">
+      <ResourceTree
+        tree={tree.data ?? []}
+        selectedId={selectedId}
+        onSelect={(item) => setSelectedId(item.id)}
+        onCreateFile={() => {}}
+        onCreateFolder={() => {}}
+        onDelete={() => {}}
+        onRename={() => {}}
+        onDrop={() => {}}
+      />
+      {resource.data ? (
+        <ResourceEditor
+          resource={resource.data}
+          onSave={(content) =>
+            updateResource.mutate({ id: resource.data.id, content })
+          }
+        />
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Other Public UI {#other-ui}
+
+| Area          | APIs                                                   | Import path                               |
+| ------------- | ------------------------------------------------------ | ----------------------------------------- |
+| Sharing       | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>`  | `@agent-native/core/client/sharing`       |
+| Notifications | `<NotificationsBell>`                                  | `@agent-native/core/client/notifications` |
+| Progress      | `<RunsTray>`, progress hooks and types                 | `@agent-native/core/client/progress`      |
+| Onboarding    | `useOnboarding()`, onboarding panel hooks              | `@agent-native/core/client/onboarding`    |
+| Observability | `<ObservabilityDashboard>`, `<ThumbsFeedback>`         | `@agent-native/core/client/observability` |
+| Resources     | `<ResourcesPanel>`, `<ResourceTree>`, resource hooks   | `@agent-native/core/client/resources`     |
+| Rich editor   | `<SharedRichEditor>`, slash commands, block node hooks | `@agent-native/core/client/editor`        |
+
+## One-Off Text Completion {#one-off-text-completion}
+
+If you truly need raw text-in/text-out, keep it server-side and use
+`completeText()` from `@agent-native/core/server`. Wrap user-facing usage in an
+action so the UI and agent share the same capability.
+
+```ts
+import { defineAction } from "@agent-native/core";
+import { completeText } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Classify a short message",
+  run: async ({ body }: { body: string }) => {
+    const result = await completeText({
+      systemPrompt: "Return exactly one label.",
+      input: body,
+      maxOutputTokens: 12,
+      temperature: 0,
+    });
+    return { label: result.text.trim() };
+  },
+});
+```
+
+Use `sendToAgentChat({ background: true, openSidebar: false })` instead when
+the work needs tools, state, auditability, user steering, or multi-step
+reasoning.

package/docs/content/context-awareness.md

@@ -5,12 +5,16 @@ description: "How the agent knows what the user is looking at: navigation state,
 
 # Context Awareness
 
+> **Developer page.** This page is for developers wiring the app's context layer. For the end-user experience — how the agent uses that context in conversation — see [Using Your Agent](/docs/using-your-agent).
+
 How the agent knows what the user is looking at -- and how the agent can control what the user sees.
 
 ## Overview {#overview}
 
 Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. With context awareness, the user can click a row, highlight a paragraph, select a slide element, or press Cmd+I, then say "summarize this" and the agent already knows what "this" means.
 
+Six patterns solve this. To understand what to put in which surface (AGENTS.md vs. skills vs. application_state), see [Writing Agent Instructions — The four surfaces the agent sees](/docs/writing-agent-instructions#four-surfaces).
+
 Six patterns solve this:
 
 1. **Navigation state** -- the UI writes a `navigation` key to application-state on every route change

package/docs/content/creating-templates.md

@@ -97,7 +97,7 @@ export const projects = table("projects", {
   updatedAt: text("updated_at").notNull().default(now()),
 });
 
-export const projectShares = createSharesTable("project_shares", "project");
+export const projectShares = createSharesTable("project_shares");
 ```
 
 Schema changes must be additive. Add tables and columns through `runMigrations()` in `server/plugins/db.ts`; never use destructive SQL, `drizzle-kit push`, table renames, or column drops.
@@ -391,7 +391,9 @@ Community templates can be created from a GitHub repo:
 pnpm dlx @agent-native/core create my-app --template github:user/repo
 ```
 
-## Test Unpublished Framework Changes {#test-unpublished-framework-changes}
+## Contributing to the framework monorepo {#contributing}
+
+### Test unpublished framework changes {#test-unpublished-framework-changes}
 
 When you are working inside the framework monorepo and need a generated
 workspace to use unpublished package or template changes, run create with the

package/docs/content/cross-app-sso.md

@@ -9,6 +9,8 @@ Each hosted app at `*.agent-native.com` runs its own deployment with its **own s
 
 This is the same trust primitive [A2A](/docs/a2a-protocol) and [External Agents](/docs/external-agents) already use — an `A2A_SECRET`-signed JWT verified at the request boundary — applied to the human sign-in path instead of agent-to-agent calls.
 
+> **Unified deploy vs. per-domain deploy.** If you host all apps at one origin (`your-agents.com/mail`, `your-agents.com/calendar`), you already get shared login via a single cookie domain — no federation needed. Cross-App SSO is only necessary when apps run on separate domains. See [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
 ## What & why {#what-why}
 
 Per-app user stores mean there is no single place a browser cookie could live that every app trusts. The federation model instead names one app — **Dispatch** — as the identity authority. Any other app can delegate "who is this person?" to Dispatch, get back a short-lived signed assertion of the user's verified email, and then **link that to its own local account by email**.
@@ -18,7 +20,7 @@ The linking rule is deliberately narrow and additive:
 - **Existing same-email user → linked.** The local account is matched by verified email and reused as-is. It is **never modified, renamed, or deleted** — the federation layer only ever reads it and mints a session for it.
 - **New email → created.** A fresh local account is created for that verified email, then a normal local session is minted.
 
-This makes the rollout safe even though it logs people out. **Logout is expected.** When an app turns this on, existing sessions end and users re-authenticate through Dispatch. But they always log back into the **same email-matched account, with all their data intact**, because identity rows are only ever _added to_ — never destroyed, renamed, or repointed. There is no migration, no table rename, no destructive write anywhere in this path. (See the auth invariants in [Authentication](/docs/authentication) and [Security & Data Scoping](/docs/security).)
+This makes the rollout safe even though it logs people out. **Logout is expected.** When an app turns this on, existing sessions end and users re-authenticate through Dispatch. But they always log back into the **same email-matched account, with all their data intact**, because identity rows are only ever _added to_ — never destroyed, renamed, or repointed.
 
 ## How it works {#how-it-works}
 
@@ -35,7 +37,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
 
 2. **Dispatch authenticates the human.** If the user already has a Dispatch session, this is transparent. If not, Dispatch shows its own normal login (email/password, Google, etc. — see [Authentication](/docs/authentication)). Dispatch is just a regular agent-native app here; it is not running a special auth mode.
 
-3. **Dispatch → App (signed identity token).** Dispatch validates `redirect_uri` against a **strict allowlist** (`*.agent-native.com` plus localhost — nothing else) and 302-redirects back to the app's `redirect_uri` carrying a short-lived **`A2A_SECRET`-signed identity JWT**. The token's claims are intentionally minimal:
+3. **Dispatch → App (signed identity token).** Dispatch validates `redirect_uri` against a strict allowlist and 302-redirects back to the app's `redirect_uri` carrying a short-lived **`A2A_SECRET`-signed identity JWT**. The token's claims are intentionally minimal:
 
    | Claim        | Meaning                                                  |
    | ------------ | -------------------------------------------------------- |
@@ -44,7 +46,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
    | `name`       | Display name (non-authoritative, for UI only)            |
    | `org_domain` | Workspace/org domain, when present                       |
    | `scope`      | Always `"identity"` — this token authorizes sign-in only |
-   | `exp`        | **≤ 5 minutes** from issue                               |
+   | `exp`        | **≤ 2 minutes** from issue                               |
 
 4. **App verifies and JIT-links by email.** The app verifies the token signature with its own `A2A_SECRET`, checks `scope: "identity"` and `exp`, then performs **just-in-time linking strictly by verified email**:
    - If a local user with that email exists → reuse it unchanged.
@@ -67,47 +69,70 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 
 The whole model rests on a few deliberately small guarantees:
 
-- **Short-lived signed token.** The identity assertion is an `A2A_SECRET`-signed JWT with a **≤ 5-minute** expiry and `scope: "identity"`. It authorizes a single sign-in and cannot be replayed for long or repurposed for API/A2A access. Verification runs at the request boundary before any session is minted — same boundary discipline as [A2A auth](/docs/a2a-protocol#auth-policy).
-- **Strict `redirect_uri` allowlist.** Dispatch only ever redirects to `*.agent-native.com` or localhost. Arbitrary, scheme-relative (`//host`), and cross-origin redirect targets are rejected, so the authority can't be turned into an open-redirect or token-exfiltration oracle.
+- **Short-lived signed token.** The identity assertion is an `A2A_SECRET`-signed JWT with a **≤ 2-minute** expiry and `scope: "identity"`. It authorizes a single sign-in and cannot be replayed for long or repurposed for API/A2A access.
+- **Strict `redirect_uri` allowlist.** Dispatch only ever redirects to `*.agent-native.com` or localhost by default. Arbitrary, scheme-relative (`//host`), and cross-origin redirect targets are rejected, so the authority can't be turned into an open-redirect or token-exfiltration oracle.
 - **Email-only join from a verified token.** The _only_ thing that crosses the trust boundary is the verified email in a signed token. The app does not accept a user id, role, org membership, or any privileged state from the wire — it derives everything locally from the matched account.
-- **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path — consistent with the framework's "no breaking database changes" rule.
-- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert. Enabling or disabling it is one env var on one deploy, with no data side effects.
+- **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path.
+- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert.
+
+## Self-hosting {#self-hosting}
+
+Any Dispatch deployment can serve as the identity hub — you are not limited to `dispatch.agent-native.com`. Set `AGENT_NATIVE_IDENTITY_HUB_URL` on each client app to point at your Dispatch instance:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**Redirect allowlist.** The hub (Dispatch) validates `redirect_uri` on the authorize endpoint before issuing a token. The allowlist is configured in `templates/dispatch/server/lib/identity-sso.ts`:
+
+- **Default:** `*.agent-native.com` and localhost only (the `DEFAULT_ALLOWED_HOST_SUFFIXES` constant).
+- **Extending it:** set the `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` environment variable on the Dispatch deployment with a comma-separated list of additional host suffixes:
+
+  ```bash
+  # Allow yourcompany.com subdomains in addition to the defaults
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
+  ```
+
+  Each entry is normalized to a dot-prefixed suffix (`.yourcompany.com`), so a suffix check is both sufficient and the least footgun-prone — no per-app list to keep in sync. Entries that would match everything (empty or just `.`) are filtered out.
+
+- **Localhost** is always allowed for local development of client-side apps regardless of `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
+
+Without `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, a self-hosted Dispatch can only issue tokens to apps on `*.agent-native.com`. Set the env var on your Dispatch deployment to unlock other domains.
 
 ## Canary rollout runbook {#canary-rollout}
 
 Cutover and rollback are **a single environment variable per app deployment**. Roll out one app at a time, verify, then expand. Do not set the variable on every app at once.
 
 **1. Deploy the code — no behavior change.**
-Ship the release to every app with `AGENT_NATIVE_IDENTITY_HUB_URL` **unset everywhere**. Because the feature is off by default, this deploy is a no-op for users: every app keeps authenticating exactly as before. Confirm normal logins still work on a couple of apps.
+Ship the release to every app with `AGENT_NATIVE_IDENTITY_HUB_URL` **unset everywhere**. Confirm normal logins still work on a couple of apps.
 
-**2. Enable the canary on ONE app (mail) only.**
-Set, on the **mail** deployment only:
+**2. Enable the canary on ONE app at a time.**
+Set, on one deployment only:
 
 ```bash
 AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 ```
 
-Leave every other app's environment unset. Redeploy/restart mail so it picks up the variable.
+Leave every other app's environment unset. Redeploy/restart so it picks up the variable.
 
 **3. Verify the canary (checklist).**
-On mail, walk the full loop:
 
-- Log **out** of mail.
+- Log **out** of the app.
 - The login screen now shows **"Sign in with Agent-Native"**. Click it.
 - You are taken to **Dispatch** and complete its login (or pass straight through if already signed in there).
-- You are redirected **back to mail, logged in** — and it is the **same pre-existing account** (same email) you had before, not a new one.
-- **Mail data is intact** — your existing mailboxes, drafts, settings, and org scoping are all exactly as they were.
-- **Existing direct logins still work** — email/password and Google sign-in on mail continue to function for users who don't use the SSO button.
+- You are redirected **back to the app, logged in** — and it is the **same pre-existing account** (same email) you had before, not a new one.
+- **App data is intact** — your existing records, settings, and org scoping are exactly as they were.
+- **Existing direct logins still work** — email/password and Google sign-in continue to function alongside SSO.
 
-If any check fails, go straight to step 5 (rollback) — it is instant and data-safe.
+If any check fails, go straight to step 4 (rollback) — it is instant and data-safe.
 
 **4. Expand app-by-app.**
-Once mail is verified, repeat steps 2–3 for the next app, then the next — setting `AGENT_NATIVE_IDENTITY_HUB_URL` on one deployment at a time and running the same checklist after each. Never batch-enable.
+Once one app is verified, repeat steps 2–3 for the next app — setting `AGENT_NATIVE_IDENTITY_HUB_URL` on one deployment at a time. Never batch-enable.
 
 **5. Rollback = unset the env var on that app's deploy.**
 To revert any app, **remove `AGENT_NATIVE_IDENTITY_HUB_URL` from that app's environment and redeploy/restart it.** The app immediately returns to its prior auth behavior. There is **no data change to undo** — identity rows were only ever added, and unsetting the variable simply makes the federation path dormant again. Each app's cutover and rollback are independent and reversible.
 
-> The rollout logs users out as each app is enabled (they re-auth via Dispatch), but they always log back into the **same email-matched account with data intact**, because identity rows are never destroyed or renamed — only added.
+> Rollout logs users out as each app is enabled (they re-auth via Dispatch), but they always log back into the **same email-matched account with data intact**, because identity rows are never destroyed or renamed — only added.
 
 ## Related {#related}
 
@@ -116,3 +141,4 @@ To revert any app, **remove `AGENT_NATIVE_IDENTITY_HUB_URL` from that app's envi
 - [External Agents](/docs/external-agents) — the same `A2A_SECRET`-signed identity pattern applied to agent connections and deep links.
 - [Dispatch](/docs/dispatch) — the workspace identity authority and routing hub.
 - [Security & Data Scoping](/docs/security) — additive-only data writes and per-account scoping.
+- [Multi-App Workspaces](/docs/multi-app-workspace) — the unified single-origin deploy that avoids cross-domain SSO entirely.

package/docs/content/database.md

@@ -36,7 +36,21 @@ The framework auto-detects the dialect from the URL and configures Drizzle accor
 
 ## Builder.io Managed Database {#builder-managed}
 
-When connected to Builder.io, your app can use a managed database that is provisioned and scaled automatically. This is the simplest path to production — no connection strings or database admin required. Coming soon.
+When connected to Builder.io, your app can use a managed database provisioned automatically — no connection strings required. Coming soon.
+
+## Where the DB Client Lives {#db-client}
+
+Each template creates a lazy, singleton Drizzle client by calling `createGetDb(schema)` from `@agent-native/core/db`. The canonical location is `server/db/index.ts`:
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+Import `getDb` from this template-local path — `../../server/db/index.js` in routes, `../server/db/index.js` in actions — rather than from `@agent-native/core` directly. The core export returns a generic untyped instance; the template's `getDb()` carries your schema types. See [Server](/docs/server#request-context) for how actions and custom routes each import it.
 
 ## Dialect-Agnostic Schema And Queries {#schema}
 
@@ -68,6 +82,8 @@ export const tasks = table("tasks", {
 
 Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly. Always use `@agent-native/core/db/schema`.
 
+Tables that store user-facing data must include an `owner_email` column so the framework's SQL-level scoping can filter rows to the authenticated user — see [Security](/docs/security#data-scoping). Tables that also support sharing with other users or orgs should spread `...ownableColumns()` instead, which adds `owner_email`, `org_id`, and `visibility` in one call — see [Sharing](/docs/sharing#building).
+
 For reads and writes, use Drizzle's query builder and portable operators from `drizzle-orm`:
 
 ```ts
@@ -125,6 +141,15 @@ export default runMigrations(
       version: 1,
       sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,
     },
+    {
+      // Dialect-gated: runs only on the matching backend. Omit the other key
+      // to make it a no-op on that dialect.
+      version: 2,
+      sql: {
+        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,
+        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only
+      },
+    },
   ],
   { table: "my_app_migrations" },
 );

package/docs/content/deployment.md

@@ -121,7 +121,9 @@ RUN pnpm build
 FROM node:24-slim
 WORKDIR /app
 COPY --from=build /app/.output .output
-COPY --from=build /app/data data
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
 ENV PORT=3000
 EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]