feat: sync blocks - wip

update aws packages
sync
2026-05-08 07:13:06 +08:00 · 2026-05-04 18:08:34 +01:00 · 2026-05-01 20:00:20 +01:00 · 2026-05-01 14:57:32 +01:00 · 2026-05-01 14:56:39 +01:00 · 2026-05-01 14:53:30 +01:00
125 changed files with 7013 additions and 1361 deletions
@@ -1,7 +1,7 @@
 {
  "name": "client",
  "private": true,
-  "version": "0.71.1",
+  "version": "0.80.1",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
@@ -31,8 +31,8 @@
    "emoji-mart": "^5.6.0",
    "file-saver": "^2.0.5",
    "highlightjs-sap-abap": "^0.3.0",
-    "i18next": "^25.10.1",
-    "i18next-http-backend": "^3.0.2",
+    "i18next": "25.10.1",
+    "i18next-http-backend": "3.0.6",
    "jotai": "^2.18.1",
    "jotai-optics": "^0.4.0",
    "js-cookie": "^3.0.5",
@@ -42,7 +42,7 @@
    "mantine-form-zod-resolver": "^1.3.0",
    "mermaid": "^11.13.0",
    "mitt": "^3.0.1",
-    "posthog-js": "1.363.1",
+    "posthog-js": "1.372.2",
    "react": "^18.3.1",
    "react-arborist": "3.4.0",
    "react-clear-modal": "^2.0.18",
@@ -50,11 +50,10 @@
    "react-drawio": "^1.0.7",
    "react-error-boundary": "^6.1.1",
    "react-helmet-async": "^3.0.0",
-    "react-i18next": "^16.5.8",
+    "react-i18next": "16.5.8",
    "react-router-dom": "^7.13.1",
    "semver": "^7.7.4",
    "socket.io-client": "^4.8.3",
-    "tiptap-extension-global-drag-handle": "^0.1.18",
    "zod": "^4.3.6"
  },
  "devDependencies": {
@@ -74,7 +73,7 @@
    "eslint-plugin-react-refresh": "^0.5.2",
    "globals": "^15.13.0",
    "optics-ts": "^2.4.1",
-    "postcss": "^8.5.8",
+    "postcss": "^8.5.12",
    "postcss-preset-mantine": "^1.18.0",
    "postcss-simple-vars": "^7.0.1",
    "prettier": "^3.8.1",
@@ -222,6 +222,8 @@
  "Edit comment": "Kommentar bearbeiten",
  "Delete comment": "Kommentar löschen",
  "Are you sure you want to delete this comment?": "Sind Sie sicher, dass Sie diesen Kommentar löschen möchten?",
+  "Delete chat": "Chat löschen",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Sind Sie sicher, dass Sie '{{title}}' löschen möchten? Diese Aktion kann nicht rückgängig gemacht werden.",
  "Comment created successfully": "Kommentar erfolgreich erstellt",
  "Error creating comment": "Fehler beim Erstellen des Kommentars",
  "Comment updated successfully": "Kommentar erfolgreich aktualisiert",
@@ -389,7 +391,7 @@
  "Write anything. Enter \"/\" for commands": "Schreiben Sie etwas. Geben Sie \"/\" für Befehle ein",
  "Write...": "\"Schreiben...\"",
  "Column count": "Spaltenanzahl",
-  "{{count}} Columns": "{count, plural, one {# Spalte} other {# Spalten}}",
+  "{{count}} Columns": "{{count}} Spalten",
  "Equal columns": "Gleich breite Spalten",
  "Left sidebar": "Linke Seitenleiste",
  "Right sidebar": "Rechte Seitenleiste",
@@ -222,6 +222,8 @@
  "Edit comment": "Edit comment",
  "Delete comment": "Delete comment",
  "Are you sure you want to delete this comment?": "Are you sure you want to delete this comment?",
+  "Delete chat": "Delete chat",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Are you sure you want to delete '{{title}}'? This action cannot be undone.",
  "Comment created successfully": "Comment created successfully",
  "Error creating comment": "Error creating comment",
  "Comment updated successfully": "Comment updated successfully",
@@ -606,25 +608,21 @@
  "Image exceeds 10MB limit.": "Image exceeds 10MB limit.",
  "Image removed successfully": "Image removed successfully",
  "API key": "API key",
-  "API key created successfully": "API key created successfully",
  "API keys": "API keys",
  "API management": "API management",
-  "Are you sure you want to revoke this API key": "Are you sure you want to revoke this API key",
-  "Create API Key": "Create API Key",
  "Custom expiration date": "Custom expiration date",
  "Enter a descriptive token name": "Enter a descriptive token name",
  "Expiration": "Expiration",
  "Expired": "Expired",
  "Expires": "Expires",
-  "I've saved my API key": "I've saved my API key",
  "Last use": "Last Used",
  "No API keys found": "No API keys found",
  "No expiration": "No expiration",
-  "Revoke API key": "Revoke API key",
  "Revoked successfully": "Revoked successfully",
  "Select expiration date": "Select expiration date",
  "This action cannot be undone. Any applications using this API key will stop working.": "This action cannot be undone. Any applications using this API key will stop working.",
-  "Update API key": "Update API key",
+  "Update": "Update",
+  "Update {{credential}}": "Update {{credential}}",
  "Manage API keys for all users in the workspace": "Manage API keys for all users in the workspace",
  "Restrict API key creation to admins": "Restrict API key creation to admins",
  "Only admins and owners can create new API keys. Existing member keys will continue to work.": "Only admins and owners can create new API keys. Existing member keys will continue to work.",
@@ -878,5 +876,41 @@
  "Try a different search term.": "Try a different search term.",
  "Try again": "Try again",
  "Untitled chat": "Untitled chat",
-  "What can I help you with?": "What can I help you with?"
+  "What can I help you with?": "What can I help you with?",
+  "Are you sure you want to revoke this {{credential}}": "Are you sure you want to revoke this {{credential}}",
+  "Automatically provision users and groups from your identity provider via SCIM.": "Automatically provision users and groups from your identity provider via SCIM.",
+  "Configure your identity provider with this URL to provision users and groups.": "Configure your identity provider with this URL to provision users and groups.",
+  "Create {{credential}}": "Create {{credential}}",
+  "{{credential}} created": "{{credential}} created",
+  "{{credential}} created successfully": "{{credential}} created successfully",
+  "Created by": "Created by",
+  "Custom": "Custom",
+  "Enable SCIM": "Enable SCIM",
+  "Enter a descriptive name": "Enter a descriptive name",
+  "I've saved my {{credential}}": "I've saved my {{credential}}",
+  "Important": "Important",
+  "Make sure to copy your {{credential}} now. You won't be able to see it again!": "Make sure to copy your {{credential}} now. You won't be able to see it again!",
+  "Never": "Never",
+  "Revoke {{credential}}": "Revoke {{credential}}",
+  "SCIM endpoint URL": "SCIM endpoint URL",
+  "SCIM provisioning": "SCIM provisioning",
+  "SCIM takes precedence over SSO group sync while enabled.": "SCIM takes precedence over SSO group sync while enabled.",
+  "You have reached the maximum of {{max}} SCIM tokens. Delete an existing token to create a new one.": "You have reached the maximum of {{max}} SCIM tokens. Delete an existing token to create a new one.",
+  "SCIM token": "SCIM token",
+  "SCIM tokens": "SCIM tokens",
+  "This action cannot be undone. Your identity provider will stop syncing immediately.": "This action cannot be undone. Your identity provider will stop syncing immediately.",
+  "Toggle SCIM provisioning": "Toggle SCIM provisioning",
+  "Token": "Token",
+  "Sync block": "Sync block",
+  "Create a block that stays in sync across pages.": "Create a block that stays in sync across pages.",
+  "Sync block name": "Sync block name",
+  "Editing original": "Editing original",
+  "Copy synced block": "Copy synced block",
+  "Unsync": "Unsync",
+  "Delete sync block": "Delete sync block",
+  "Synced to {{count}} other page_one": "Synced to {{count}} other page",
+  "Synced to {{count}} other page_other": "Synced to {{count}} other pages",
+  "ORIGINAL": "ORIGINAL",
+  "THIS PAGE": "THIS PAGE",
+  "No pages": "No pages"
 }
@@ -222,6 +222,8 @@
  "Edit comment": "Editar comentario",
  "Delete comment": "Eliminar comentario",
  "Are you sure you want to delete this comment?": "¿Está seguro de que desea eliminar este comentario?",
+  "Delete chat": "Eliminar chat",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "¿Está seguro de que desea eliminar '{{title}}'? Esta acción no se puede deshacer.",
  "Comment created successfully": "Comentario creado con éxito",
  "Error creating comment": "Error al crear comentario",
  "Comment updated successfully": "Comentario actualizado con éxito",
@@ -222,6 +222,8 @@
  "Edit comment": "Modifier le commentaire",
  "Delete comment": "Supprimer le commentaire",
  "Are you sure you want to delete this comment?": "Êtes-vous sûr de vouloir supprimer ce commentaire ?",
+  "Delete chat": "Supprimer la conversation",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Êtes-vous sûr de vouloir supprimer '{{title}}' ? Cette action est irréversible.",
  "Comment created successfully": "Commentaire créé avec succès",
  "Error creating comment": "Erreur lors de la création du commentaire",
  "Comment updated successfully": "Commentaire mis à jour avec succès",
@@ -222,6 +222,8 @@
  "Edit comment": "Modifica commento",
  "Delete comment": "Elimina commento",
  "Are you sure you want to delete this comment?": "Sei sicuro di voler eliminare questo commento?",
+  "Delete chat": "Elimina chat",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Sei sicuro di voler eliminare '{{title}}'? Questa azione non può essere annullata.",
  "Comment created successfully": "Commento creato con successo",
  "Error creating comment": "Si è verificato un errore durante la creazione del commento",
  "Comment updated successfully": "Commento aggiornato con successo",
@@ -222,6 +222,8 @@
  "Edit comment": "コメントを編集する",
  "Delete comment": "コメントを削除する",
  "Are you sure you want to delete this comment?": "このコメントを削除してもよろしいですか?",
+  "Delete chat": "チャットを削除",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "「{{title}}」を削除してもよろしいですか？この操作は元に戻せません。",
  "Comment created successfully": "コメントを作成しました",
  "Error creating comment": "コメントの作成に失敗しました",
  "Comment updated successfully": "コメントを更新しました",
@@ -222,6 +222,8 @@
  "Edit comment": "댓글 수정",
  "Delete comment": "댓글 삭제",
  "Are you sure you want to delete this comment?": "이 댓글을 삭제하시겠습니까?",
+  "Delete chat": "채팅 삭제",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "'{{title}}'을(를) 삭제하시겠습니까? 이 작업은 되돌릴 수 없습니다.",
  "Comment created successfully": "댓글 생성 완료",
  "Error creating comment": "댓글 생성 오류",
  "Comment updated successfully": "댓글 업데이트 완료",
@@ -222,6 +222,8 @@
  "Edit comment": "Bewerk reactie",
  "Delete comment": "Verwijder reactie",
  "Are you sure you want to delete this comment?": "Weet je zeker dat je deze reactie wilt verwijderen?",
+  "Delete chat": "Chat verwijderen",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Weet je zeker dat je '{{title}}' wilt verwijderen? Deze actie kan niet ongedaan worden gemaakt.",
  "Comment created successfully": "Reactie succesvol aangemaakt",
  "Error creating comment": "Fout bij het aanmaken van reactie",
  "Comment updated successfully": "Opmerking succesvol bijgewerkt",
@@ -222,6 +222,8 @@
  "Edit comment": "Editar comentário",
  "Delete comment": "Excluir comentário",
  "Are you sure you want to delete this comment?": "Você tem certeza de que deseja excluir este comentário?",
+  "Delete chat": "Excluir chat",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Tem certeza de que deseja excluir '{{title}}'? Esta ação não pode ser desfeita.",
  "Comment created successfully": "Comentário criado com sucesso",
  "Error creating comment": "Erro ao criar comentário",
  "Comment updated successfully": "Comentário atualizado com sucesso",
@@ -222,6 +222,8 @@
  "Edit comment": "Редактировать комментарий",
  "Delete comment": "Удалить комментарий",
  "Are you sure you want to delete this comment?": "Вы уверены, что хотите удалить этот комментарий?",
+  "Delete chat": "Удалить чат",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Вы уверены, что хотите удалить '{{title}}'? Это действие нельзя отменить.",
  "Comment created successfully": "Комментарий успешно создан",
  "Error creating comment": "Ошибка при создании комментария",
  "Comment updated successfully": "Комментарий успешно обновлён",
@@ -222,6 +222,8 @@
  "Edit comment": "Редагувати коментар",
  "Delete comment": "Видалити коментар",
  "Are you sure you want to delete this comment?": "Ви впевнені, що хочете видалити цей коментар?",
+  "Delete chat": "Видалити чат",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "Ви впевнені, що хочете видалити '{{title}}'? Цю дію неможливо скасувати.",
  "Comment created successfully": "Коментар успішно створено",
  "Error creating comment": "Помилка при створенні коментаря",
  "Comment updated successfully": "Коментар успішно оновлено",
@@ -222,6 +222,8 @@
  "Edit comment": "编辑评论",
  "Delete comment": "删除评论",
  "Are you sure you want to delete this comment?": "你确定要删除这条评论吗？",
+  "Delete chat": "删除聊天",
+  "Are you sure you want to delete '{{title}}'? This action cannot be undone.": "您确定要删除「{{title}}」吗？此操作无法撤销。",
  "Comment created successfully": "成功创建评论",
  "Error creating comment": "创建评论时出错",
  "Comment updated successfully": "评论更新成功",
@@ -116,7 +116,9 @@ export default function GlobalAppShell({
      </AppShell.Navbar>
      <AppShell.Main>
        {isSettingsRoute ? (
-          <Container size={900}>{children}</Container>
+          <Container size={900} pb={80}>
+            {children}
+          </Container>
        ) : (
          children
        )}
@@ -13,6 +13,7 @@ import { getShares } from "@/features/share/services/share-service.ts";
 import { getApiKeys } from "@/ee/api-key";
 import { getAuditLogs } from "@/ee/audit/services/audit-service";
 import { getVerificationList } from "@/ee/page-verification/services/page-verification-service";
+import { getScimTokens } from "@/ee/scim/services/scim-token-service";

 export const prefetchWorkspaceMembers = () => {
  const params: QueryParams = { limit: 100, query: "" };
@@ -98,3 +99,10 @@ export const prefetchVerifiedPages = () => {
    queryFn: () => getVerificationList(params),
  });
 };
+
+export const prefetchScimTokens = () => {
+  queryClient.prefetchQuery({
+    queryKey: ["scim-token-list", { cursor: undefined }],
+    queryFn: () => getScimTokens({}),
+  });
+};
@@ -31,6 +31,7 @@ import {
  prefetchBilling,
  prefetchGroups,
  prefetchLicense,
+  prefetchScimTokens,
  prefetchShares,
  prefetchSpaces,
  prefetchSsoProviders,
@@ -204,7 +205,10 @@ export default function SettingsSidebar() {
              }
              break;
            case "Security & SSO":
-              prefetchHandler = prefetchSsoProviders;
+              prefetchHandler = () => {
+                prefetchSsoProviders();
+                prefetchScimTokens();
+              };
              break;
            case "Public sharing":
              prefetchHandler = prefetchShares;
@@ -9,7 +9,7 @@ import classes from "../styles/chat-sidebar.module.css";
 type Props = {
  chat: AiChat;
  isActive: boolean;
-  onDelete: (chatId: string) => void;
+  onDelete: (chatId: string, title: string | null) => void;
  onRename: (chatId: string, title: string) => void;
 };

@@ -153,7 +153,7 @@ export default function AiChatSidebarItem({
              onClick={(e) => {
                e.preventDefault();
                e.stopPropagation();
-                onDelete(chat.id);
+                onDelete(chat.id, chat.title);
              }}
            >
              {t("Delete")}
@@ -1,6 +1,14 @@
 import { useState, useCallback, useEffect, useMemo, useRef } from "react";
 import { Link, useNavigate, useParams } from "react-router-dom";
-import { ActionIcon, Center, TextInput, Loader, Tooltip } from "@mantine/core";
+import {
+  ActionIcon,
+  Center,
+  Text,
+  TextInput,
+  Loader,
+  Tooltip,
+} from "@mantine/core";
+import { modals } from "@mantine/modals";
 import { useDebouncedValue } from "@mantine/hooks";
 import { IconPlus, IconSearch, IconMessageCircle2 } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
@@ -73,16 +81,31 @@ export default function AiChatSidebar() {
  );

  const handleDelete = useCallback(
-    (id: string) => {
-      deleteMutation.mutate(id, {
-        onSuccess: () => {
-          if (chatId === id) {
-            navigate("/ai");
-          }
+    (id: string, title: string | null) => {
+      modals.openConfirmModal({
+        title: t("Delete chat"),
+        centered: true,
+        children: (
+          <Text size="sm">
+            {t("Are you sure you want to delete '{{title}}'? This action cannot be undone.", {
+              title: title || t("Untitled"),
+            })}
+          </Text>
+        ),
+        labels: { confirm: t("Delete"), cancel: t("Cancel") },
+        confirmProps: { color: "red" },
+        onConfirm: () => {
+          deleteMutation.mutate(id, {
+            onSuccess: () => {
+              if (chatId === id) {
+                navigate("/ai");
+              }
+            },
+          });
        },
      });
    },
-    [deleteMutation, chatId, navigate],
+    [deleteMutation, chatId, navigate, t],
  );

  const handleRename = useCallback(
@@ -31,7 +31,7 @@ export function ApiKeyCreatedModal({
    <Modal
      opened={opened}
      onClose={onClose}
-      title={t("API key created")}
+      title={t("{{credential}} created", { credential: t("API key") })}
      size="lg"
    >
      <Stack gap="md">
@@ -41,7 +41,8 @@ export function ApiKeyCreatedModal({
          color="red"
        >
          {t(
-            "Make sure to copy your API key now. You won't be able to see it again!",
+            "Make sure to copy your {{credential}} now. You won't be able to see it again!",
+            { credential: t("API key") },
          )}
        </Alert>

@@ -64,7 +65,7 @@ export function ApiKeyCreatedModal({
        </div>

        <Button fullWidth onClick={onClose} mt="md">
-          {t("I've saved my API key")}
+          {t("I've saved my {{credential}}", { credential: t("API key") })}
        </Button>
      </Stack>
    </Modal>
@@ -105,7 +105,7 @@ export function CreateApiKeyModal({
    <Modal
      opened={opened}
      onClose={handleClose}
-      title={t("Create API Key")}
+      title={t("Create {{credential}}", { credential: t("API key") })}
      size="md"
    >
      <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>
@@ -30,12 +30,14 @@ export function RevokeApiKeyModal({
    <Modal
      opened={opened}
      onClose={onClose}
-      title={t("Revoke API key")}
+      title={t("Revoke {{credential}}", { credential: t("API key") })}
      size="md"
    >
      <Stack gap="md">
        <Text>
-          {t("Are you sure you want to revoke this API key")}{" "}
+          {t("Are you sure you want to revoke this {{credential}}", {
+            credential: t("API key"),
+          })}{" "}
          <strong>{apiKey?.name}</strong>?
        </Text>
        <Text size="sm" c="dimmed">
@@ -53,7 +53,7 @@ export function UpdateApiKeyModal({
    <Modal
      opened={opened}
      onClose={onClose}
-      title={t("Update API key")}
+      title={t("Update {{credential}}", { credential: t("API key") })}
      size="md"
    >
      <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>
@@ -63,7 +63,11 @@ export function useCreateApiKeyMutation() {
  return useMutation<IApiKey, Error, ICreateApiKeyRequest>({
    mutationFn: (data) => createApiKey(data),
    onSuccess: () => {
-      notifications.show({ message: t("API key created successfully") });
+      notifications.show({
+        message: t("{{credential}} created successfully", {
+          credential: t("API key"),
+        }),
+      });
      queryClient.invalidateQueries({
        predicate: (item) =>
          ["api-key-list"].includes(item.queryKey[0] as string),
@@ -33,6 +33,10 @@ export const auditEventLabels: Record<string, string> = {
  "api_key.updated": "Updated API key",
  "api_key.deleted": "Deleted API key",

+  "scim_token.created": "Created SCIM token",
+  "scim_token.updated": "Updated SCIM token",
+  "scim_token.deleted": "Deleted SCIM token",
+
  "space.created": "Created space",
  "space.updated": "Updated space",
  "space.deleted": "Deleted space",
@@ -174,6 +178,14 @@ export const eventFilterOptions: EventGroup[] = [
      { value: "api_key.deleted", label: "Deleted API key" },
    ],
  },
+  {
+    group: "SCIM token",
+    items: [
+      { value: "scim_token.created", label: "Created SCIM token" },
+      { value: "scim_token.updated", label: "Updated SCIM token" },
+      { value: "scim_token.deleted", label: "Deleted SCIM token" },
+    ],
+  },
  {
    group: "License",
    items: [
@@ -8,6 +8,7 @@ export const Feature = {
  AI: 'ai',
  CONFLUENCE_IMPORT: 'import:confluence',
  DOCX_IMPORT: 'import:docx',
+  PDF_IMPORT: 'import:pdf',
  ATTACHMENT_INDEXING: 'attachment:indexing',
  SECURITY_SETTINGS: 'security:settings',
  MCP: 'mcp',
@@ -140,7 +140,7 @@ export function PagePermissionList({
        )}
      </Group>

-      <ScrollArea mah={250} viewportRef={viewportRef}>
+      <ScrollArea.Autosize mah={400} viewportRef={viewportRef}>
        {sortedMembers.map((member) => (
          <PagePermissionItem
            key={`${member.type}-${member.id}`}
@@ -158,7 +158,7 @@ export function PagePermissionList({
            <Loader size="xs" />
          </Center>
        )}
-      </ScrollArea>
+      </ScrollArea.Autosize>
    </>
  );
 }
@@ -0,0 +1,78 @@
+import { Modal, TextInput, Button, Group, Stack } from "@mantine/core";
+import { useForm } from "@mantine/form";
+import { zod4Resolver } from "mantine-form-zod-resolver";
+import { z } from "zod/v4";
+import { useTranslation } from "react-i18next";
+import { useCreateScimTokenMutation } from "@/ee/scim/queries/scim-token-query";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface CreateScimTokenModalProps {
+  opened: boolean;
+  onClose: () => void;
+  onSuccess: (response: IScimToken) => void;
+}
+
+const formSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+});
+type FormValues = z.infer<typeof formSchema>;
+
+export function CreateScimTokenModal({
+  opened,
+  onClose,
+  onSuccess,
+}: CreateScimTokenModalProps) {
+  const { t } = useTranslation();
+  const createMutation = useCreateScimTokenMutation();
+
+  const form = useForm<FormValues>({
+    validate: zod4Resolver(formSchema),
+    initialValues: { name: "" },
+  });
+
+  const handleSubmit = async (data: FormValues) => {
+    try {
+      const created = await createMutation.mutateAsync({ name: data.name });
+      onSuccess(created);
+      form.reset();
+      onClose();
+    } catch (err) {
+      //
+    }
+  };
+
+  const handleClose = () => {
+    form.reset();
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={handleClose}
+      title={t("Create {{credential}}", { credential: t("SCIM token") })}
+      size="md"
+    >
+      <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>
+        <Stack gap="md">
+          <TextInput
+            label={t("Name")}
+            placeholder={t("Enter a descriptive name")}
+            data-autofocus
+            required
+            {...form.getInputProps("name")}
+          />
+
+          <Group justify="flex-end" mt="md">
+            <Button variant="default" onClick={handleClose}>
+              {t("Cancel")}
+            </Button>
+            <Button type="submit" loading={createMutation.isPending}>
+              {t("Create")}
+            </Button>
+          </Group>
+        </Stack>
+      </form>
+    </Modal>
+  );
+}
@@ -0,0 +1,55 @@
+import { Group, Text, Switch, Tooltip } from "@mantine/core";
+import { useAtom } from "jotai";
+import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
+import React, { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { updateWorkspace } from "@/features/workspace/services/workspace-service.ts";
+import { notifications } from "@mantine/notifications";
+import { useHasFeature } from "@/ee/hooks/use-feature.ts";
+import { Feature } from "@/ee/features.ts";
+import { useUpgradeLabel } from "@/ee/hooks/use-upgrade-label.ts";
+
+export default function EnableScim() {
+  const { t } = useTranslation();
+  const [workspace, setWorkspace] = useAtom(workspaceAtom);
+  const [checked, setChecked] = useState(workspace?.isScimEnabled ?? false);
+  const hasAccess = useHasFeature(Feature.SCIM);
+  const upgradeLabel = useUpgradeLabel();
+
+  const handleChange = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    const value = event.currentTarget.checked;
+    try {
+      const updatedWorkspace = await updateWorkspace({ isScimEnabled: value });
+      setChecked(value);
+      setWorkspace(updatedWorkspace);
+    } catch (err) {
+      notifications.show({
+        message: err?.response?.data?.message,
+        color: "red",
+      });
+    }
+  };
+
+  return (
+    <Group justify="space-between" wrap="nowrap" gap="xl">
+      <div>
+        <Text size="md">{t("Enable SCIM")}</Text>
+        <Text size="sm" c="dimmed">
+          {t(
+            "Automatically provision users and groups from your identity provider via SCIM.",
+          )}
+        </Text>
+      </div>
+
+      <Tooltip label={upgradeLabel} disabled={hasAccess} refProp="rootRef">
+        <Switch
+          labelPosition="left"
+          defaultChecked={checked}
+          onChange={handleChange}
+          disabled={!hasAccess}
+          aria-label={t("Toggle SCIM provisioning")}
+        />
+      </Tooltip>
+    </Group>
+  );
+}
@@ -0,0 +1,61 @@
+import { Modal, Text, Button, Group, Stack } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import { useRevokeScimTokenMutation } from "@/ee/scim/queries/scim-token-query";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface RevokeScimTokenModalProps {
+  opened: boolean;
+  onClose: () => void;
+  scimToken: IScimToken | null;
+}
+
+export function RevokeScimTokenModal({
+  opened,
+  onClose,
+  scimToken,
+}: RevokeScimTokenModalProps) {
+  const { t } = useTranslation();
+  const revokeMutation = useRevokeScimTokenMutation();
+
+  const handleRevoke = async () => {
+    if (!scimToken) return;
+    await revokeMutation.mutateAsync({ tokenId: scimToken.id });
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={t("Revoke {{credential}}", { credential: t("SCIM token") })}
+      size="md"
+    >
+      <Stack gap="md">
+        <Text>
+          {t("Are you sure you want to revoke this {{credential}}", {
+            credential: t("SCIM token"),
+          })}{" "}
+          <strong>{scimToken?.name}</strong>?
+        </Text>
+        <Text size="sm" c="dimmed">
+          {t(
+            "This action cannot be undone. Your identity provider will stop syncing immediately.",
+          )}
+        </Text>
+
+        <Group justify="flex-end" mt="md">
+          <Button variant="default" onClick={onClose}>
+            {t("Cancel")}
+          </Button>
+          <Button
+            color="red"
+            onClick={handleRevoke}
+            loading={revokeMutation.isPending}
+          >
+            {t("Revoke")}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
@@ -0,0 +1,69 @@
+import {
+  Modal,
+  Text,
+  Stack,
+  Alert,
+  Group,
+  Button,
+  TextInput,
+} from "@mantine/core";
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import CopyTextButton from "@/components/common/copy.tsx";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface ScimTokenCreatedModalProps {
+  opened: boolean;
+  onClose: () => void;
+  scimToken: IScimToken | null;
+}
+
+export function ScimTokenCreatedModal({
+  opened,
+  onClose,
+  scimToken,
+}: ScimTokenCreatedModalProps) {
+  const { t } = useTranslation();
+  if (!scimToken) return null;
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={t("{{credential}} created", { credential: t("SCIM token") })}
+      size="lg"
+    >
+      <Stack gap="md">
+        <Alert
+          icon={<IconAlertTriangle size={16} />}
+          title={t("Important")}
+          color="red"
+        >
+          {t(
+            "Make sure to copy your {{credential}} now. You won't be able to see it again!",
+            { credential: t("SCIM token") },
+          )}
+        </Alert>
+
+        <div>
+          <Text size="sm" fw={500} mb="xs">
+            {t("SCIM token")}
+          </Text>
+          <Group gap="xs" wrap="nowrap">
+            <TextInput
+              variant="filled"
+              style={{ flex: 1 }}
+              value={scimToken.token}
+              readOnly
+            />
+            <CopyTextButton text={scimToken.token} />
+          </Group>
+        </div>
+
+        <Button fullWidth onClick={onClose} mt="md">
+          {t("I've saved my {{credential}}", { credential: t("SCIM token") })}
+        </Button>
+      </Stack>
+    </Modal>
+  );
+}
@@ -0,0 +1,130 @@
+import { ActionIcon, Group, Menu, Table, Text } from "@mantine/core";
+import { IconDots, IconEdit, IconTrash } from "@tabler/icons-react";
+import { format } from "date-fns";
+import { useTranslation } from "react-i18next";
+import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
+import React from "react";
+import NoTableResults from "@/components/common/no-table-results";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface ScimTokenTableProps {
+  tokens: IScimToken[];
+  isLoading?: boolean;
+  onUpdate?: (token: IScimToken) => void;
+  onRevoke?: (token: IScimToken) => void;
+}
+
+export function ScimTokenTable({
+  tokens,
+  isLoading,
+  onUpdate,
+  onRevoke,
+}: ScimTokenTableProps) {
+  const { t } = useTranslation();
+
+  const formatDate = (date: Date | string | null) => {
+    if (!date) return t("Never");
+    return format(new Date(date), "MMM dd, yyyy");
+  };
+
+  return (
+    <Table.ScrollContainer minWidth={500}>
+      <Table highlightOnHover verticalSpacing="sm">
+        <Table.Thead>
+          <Table.Tr>
+            <Table.Th>{t("Name")}</Table.Th>
+            <Table.Th>{t("Token")}</Table.Th>
+            <Table.Th>{t("Created by")}</Table.Th>
+            <Table.Th>{t("Last used")}</Table.Th>
+            <Table.Th>{t("Created")}</Table.Th>
+            <Table.Th></Table.Th>
+          </Table.Tr>
+        </Table.Thead>
+
+        <Table.Tbody>
+          {tokens && tokens.length > 0 ? (
+            tokens.map((token) => (
+              <Table.Tr key={token.id}>
+                <Table.Td>
+                  <Text fz="sm" fw={500}>
+                    {token.name}
+                  </Text>
+                </Table.Td>
+
+                <Table.Td>
+                  <Text fz="sm" ff="monospace" c="dimmed">
+                    ••••{token.tokenLastFour}
+                  </Text>
+                </Table.Td>
+
+                {token.creator ? (
+                  <Table.Td>
+                    <Group gap="4" wrap="nowrap">
+                      <CustomAvatar
+                        avatarUrl={token.creator?.avatarUrl}
+                        name={token.creator.name}
+                        size="sm"
+                      />
+                      <Text fz="sm" lineClamp={1}>
+                        {token.creator.name}
+                      </Text>
+                    </Group>
+                  </Table.Td>
+                ) : (
+                  <Table.Td>
+                    <Text fz="sm" c="dimmed">
+                      —
+                    </Text>
+                  </Table.Td>
+                )}
+
+                <Table.Td>
+                  <Text fz="sm" style={{ whiteSpace: "nowrap" }}>
+                    {formatDate(token.lastUsedAt)}
+                  </Text>
+                </Table.Td>
+
+                <Table.Td>
+                  <Text fz="sm" style={{ whiteSpace: "nowrap" }}>
+                    {formatDate(token.createdAt)}
+                  </Text>
+                </Table.Td>
+
+                <Table.Td>
+                  <Menu position="bottom-end" withinPortal>
+                    <Menu.Target>
+                      <ActionIcon variant="subtle" color="gray">
+                        <IconDots size={16} />
+                      </ActionIcon>
+                    </Menu.Target>
+                    <Menu.Dropdown>
+                      {onUpdate && (
+                        <Menu.Item
+                          leftSection={<IconEdit size={16} />}
+                          onClick={() => onUpdate(token)}
+                        >
+                          {t("Rename")}
+                        </Menu.Item>
+                      )}
+                      {onRevoke && (
+                        <Menu.Item
+                          leftSection={<IconTrash size={16} />}
+                          color="red"
+                          onClick={() => onRevoke(token)}
+                        >
+                          {t("Revoke")}
+                        </Menu.Item>
+                      )}
+                    </Menu.Dropdown>
+                  </Menu>
+                </Table.Td>
+              </Table.Tr>
+            ))
+          ) : (
+            <NoTableResults colSpan={6} />
+          )}
+        </Table.Tbody>
+      </Table>
+    </Table.ScrollContainer>
+  );
+}
@@ -0,0 +1,30 @@
+import { Group, Stack, Text, TextInput } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import CopyTextButton from "@/components/common/copy.tsx";
+
+export function ScimUrlPanel() {
+  const { t } = useTranslation();
+  const scimUrl = `${window.location.origin}/api/scim/v2`;
+
+  return (
+    <Stack gap="xs">
+      <Text size="sm" fw={500}>
+        {t("SCIM endpoint URL")}
+      </Text>
+      <Text size="xs" c="dimmed">
+        {t(
+          "Configure your identity provider with this URL to provision users and groups.",
+        )}
+      </Text>
+      <Group gap="xs" wrap="nowrap">
+        <TextInput
+          variant="filled"
+          style={{ flex: 1 }}
+          value={scimUrl}
+          readOnly
+        />
+        <CopyTextButton text={scimUrl} />
+      </Group>
+    </Stack>
+  );
+}
@@ -0,0 +1,77 @@
+import { Modal, TextInput, Button, Group, Stack } from "@mantine/core";
+import { useForm } from "@mantine/form";
+import { zod4Resolver } from "mantine-form-zod-resolver";
+import { z } from "zod/v4";
+import { useTranslation } from "react-i18next";
+import { useEffect } from "react";
+import { useUpdateScimTokenMutation } from "@/ee/scim/queries/scim-token-query";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+const formSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+});
+type FormValues = z.infer<typeof formSchema>;
+
+interface UpdateScimTokenModalProps {
+  opened: boolean;
+  onClose: () => void;
+  scimToken: IScimToken | null;
+}
+
+export function UpdateScimTokenModal({
+  opened,
+  onClose,
+  scimToken,
+}: UpdateScimTokenModalProps) {
+  const { t } = useTranslation();
+  const updateMutation = useUpdateScimTokenMutation();
+
+  const form = useForm<FormValues>({
+    validate: zod4Resolver(formSchema),
+    initialValues: { name: "" },
+  });
+
+  useEffect(() => {
+    if (opened && scimToken) {
+      form.setValues({ name: scimToken.name });
+    }
+  }, [opened, scimToken]);
+
+  const handleSubmit = async (data: FormValues) => {
+    if (!scimToken) return;
+    await updateMutation.mutateAsync({
+      tokenId: scimToken.id,
+      name: data.name,
+    });
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={t("Update {{credential}}", { credential: t("SCIM token") })}
+      size="md"
+    >
+      <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>
+        <Stack gap="md">
+          <TextInput
+            label={t("Name")}
+            placeholder={t("Enter a descriptive name")}
+            required
+            {...form.getInputProps("name")}
+          />
+
+          <Group justify="flex-end" mt="md">
+            <Button variant="default" onClick={onClose}>
+              {t("Cancel")}
+            </Button>
+            <Button type="submit" loading={updateMutation.isPending}>
+              {t("Update")}
+            </Button>
+          </Group>
+        </Stack>
+      </form>
+    </Modal>
+  );
+}
@@ -0,0 +1,2 @@
+export * from "./types/scim-token.types";
+export * from "./services/scim-token-service";
@@ -0,0 +1,96 @@
+import { IPagination, QueryParams } from "@/lib/types.ts";
+import {
+  keepPreviousData,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  UseQueryResult,
+} from "@tanstack/react-query";
+import {
+  createScimToken,
+  getScimTokens,
+  revokeScimToken,
+  updateScimToken,
+} from "@/ee/scim/services/scim-token-service";
+import {
+  IScimToken,
+  ICreateScimTokenRequest,
+  IRevokeScimTokenRequest,
+  IUpdateScimTokenRequest,
+} from "@/ee/scim/types/scim-token.types";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
+
+export function useGetScimTokensQuery(
+  params?: QueryParams,
+): UseQueryResult<IPagination<IScimToken>, Error> {
+  return useQuery({
+    queryKey: ["scim-token-list", params],
+    queryFn: () => getScimTokens(params),
+    placeholderData: keepPreviousData,
+  });
+}
+
+export function useCreateScimTokenMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<IScimToken, Error, ICreateScimTokenRequest>({
+    mutationFn: (data) => createScimToken(data),
+    onSuccess: () => {
+      notifications.show({
+        message: t("{{credential}} created successfully", {
+          credential: t("SCIM token"),
+        }),
+      });
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["scim-token-list"].includes(item.queryKey[0] as string),
+      });
+    },
+    onError: (error) => {
+      const errorMessage = error["response"]?.data?.message;
+      notifications.show({ message: errorMessage, color: "red" });
+    },
+  });
+}
+
+export function useUpdateScimTokenMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<void, Error, IUpdateScimTokenRequest>({
+    mutationFn: (data) => updateScimToken(data),
+    onSuccess: () => {
+      notifications.show({ message: t("Updated successfully") });
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["scim-token-list"].includes(item.queryKey[0] as string),
+      });
+    },
+    onError: (error) => {
+      const errorMessage = error["response"]?.data?.message;
+      notifications.show({ message: errorMessage, color: "red" });
+    },
+  });
+}
+
+export function useRevokeScimTokenMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<void, Error, IRevokeScimTokenRequest>({
+    mutationFn: (data) => revokeScimToken(data),
+    onSuccess: () => {
+      notifications.show({ message: t("Revoked successfully") });
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["scim-token-list"].includes(item.queryKey[0] as string),
+      });
+    },
+    onError: (error) => {
+      const errorMessage = error["response"]?.data?.message;
+      notifications.show({ message: errorMessage, color: "red" });
+    },
+  });
+}
@@ -0,0 +1,34 @@
+import api from "@/lib/api-client";
+import {
+  IScimToken,
+  ICreateScimTokenRequest,
+  IRevokeScimTokenRequest,
+  IUpdateScimTokenRequest,
+} from "@/ee/scim/types/scim-token.types";
+import { IPagination, QueryParams } from "@/lib/types.ts";
+
+export async function getScimTokens(
+  params?: QueryParams,
+): Promise<IPagination<IScimToken>> {
+  const req = await api.post("/scim-tokens", { ...params });
+  return req.data;
+}
+
+export async function createScimToken(
+  data: ICreateScimTokenRequest,
+): Promise<IScimToken> {
+  const req = await api.post<IScimToken>("/scim-tokens/create", data);
+  return req.data;
+}
+
+export async function updateScimToken(
+  data: IUpdateScimTokenRequest,
+): Promise<void> {
+  await api.post("/scim-tokens/update", data);
+}
+
+export async function revokeScimToken(
+  data: IRevokeScimTokenRequest,
+): Promise<void> {
+  await api.post("/scim-tokens/revoke", data);
+}
@@ -0,0 +1,27 @@
+import { IUser } from "@/features/user/types/user.types.ts";
+
+export interface IScimToken {
+  id: string;
+  name: string;
+  token?: string;
+  tokenLastFour: string;
+  isEnabled: boolean;
+  creatorId: string;
+  workspaceId: string;
+  lastUsedAt: string | null;
+  createdAt: string;
+  creator?: Partial<IUser>;
+}
+
+export interface ICreateScimTokenRequest {
+  name: string;
+}
+
+export interface IUpdateScimTokenRequest {
+  tokenId: string;
+  name: string;
+}
+
+export interface IRevokeScimTokenRequest {
+  tokenId: string;
+}
@@ -69,8 +69,8 @@ export default function SsoProviderList() {
  return (
    <>
      <Card shadow="sm" radius="sm">
-        <Table.ScrollContainer minWidth={600}>
-          <Table verticalSpacing="sm">
+        <Table.ScrollContainer minWidth={600} maxHeight={400}>
+          <Table verticalSpacing="sm" stickyHeader>
            <Table.Thead>
              <Table.Tr>
                <Table.Th>{t("Name")}</Table.Th>
@@ -1,8 +1,18 @@
 import { Helmet } from "react-helmet-async";
 import { getAppName, isCloud } from "@/lib/config.ts";
 import SettingsTitle from "@/components/settings/settings-title.tsx";
-import { Divider, Title } from "@mantine/core";
-import React from "react";
+import {
+  Alert,
+  Button,
+  Card,
+  Divider,
+  Group,
+  Space,
+  Title,
+  Tooltip,
+} from "@mantine/core";
+import { IconInfoCircle } from "@tabler/icons-react";
+import React, { useState } from "react";
 import useUserRole from "@/hooks/use-user-role.tsx";
 import SsoProviderList from "@/ee/security/components/sso-provider-list.tsx";
 import CreateSsoProvider from "@/ee/security/components/create-sso-provider.tsx";
@@ -12,16 +22,41 @@ import { useTranslation } from "react-i18next";
 import EnforceMfa from "@/ee/security/components/enforce-mfa.tsx";
 import DisablePublicSharing from "@/ee/security/components/disable-public-sharing.tsx";
 import TrashRetention from "@/ee/security/components/trash-retention.tsx";
-
+import { useAtom } from "jotai";
+import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useHasFeature } from "@/ee/hooks/use-feature";
 import { Feature } from "@/ee/features";
+import { useGetScimTokensQuery } from "@/ee/scim/queries/scim-token-query";
+import { ScimUrlPanel } from "@/ee/scim/components/scim-url-panel";
+import { ScimTokenTable } from "@/ee/scim/components/scim-token-table";
+import { CreateScimTokenModal } from "@/ee/scim/components/create-scim-token-modal";
+import { ScimTokenCreatedModal } from "@/ee/scim/components/scim-token-created-modal";
+import { RevokeScimTokenModal } from "@/ee/scim/components/revoke-scim-token-modal";
+import { UpdateScimTokenModal } from "@/ee/scim/components/update-scim-token-modal";
+import EnableScim from "@/ee/scim/components/enable-scim";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
+import Paginate from "@/components/common/paginate";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+const SCIM_TOKEN_LIMIT = 5;

 export default function Security() {
  const { t } = useTranslation();
  const { isAdmin } = useUserRole();
  const hasCustomSso = useHasFeature(Feature.SSO_CUSTOM);
-  const hasRetention = useHasFeature(Feature.RETENTION);
-  const hasSharingControls = useHasFeature(Feature.SHARING_CONTROLS);
+  const hasScim = useHasFeature(Feature.SCIM);
+  const [workspace] = useAtom(workspaceAtom);
+  const isScimEnabled = workspace?.isScimEnabled ?? false;
+
+  const { cursor, goNext, goPrev } = useCursorPaginate();
+  const { data: scimData, isLoading: scimLoading } = useGetScimTokensQuery(
+    hasScim && isScimEnabled ? { cursor } : undefined,
+  );
+
+  const [createOpen, setCreateOpen] = useState(false);
+  const [createdToken, setCreatedToken] = useState<IScimToken | null>(null);
+  const [updateTarget, setUpdateTarget] = useState<IScimToken | null>(null);
+  const [revokeTarget, setRevokeTarget] = useState<IScimToken | null>(null);

  if (!isAdmin) {
    return null;
@@ -45,7 +80,7 @@ export default function Security() {
      <Divider my="lg" />

      <Title order={4} my="lg">
-        Single sign-on (SSO)
+        {t("Single sign-on (SSO)")}
      </Title>

      <EnforceSso />
@@ -66,6 +101,102 @@ export default function Security() {
      )}

      <SsoProviderList />
+
+      {hasScim && (
+        <>
+          <Divider my="xl" />
+
+          <Title order={4} my="lg">
+            {t("SCIM provisioning")}
+          </Title>
+
+          <Alert
+            icon={<IconInfoCircle size={16} />}
+            color="blue"
+            variant="light"
+            mb="md"
+          >
+            {t("SCIM takes precedence over SSO group sync while enabled.")}
+          </Alert>
+
+          <EnableScim />
+
+          <Divider my="lg" />
+
+          <ScimUrlPanel />
+
+          {isScimEnabled && (
+            <>
+              <Divider my="lg" />
+
+              <Group justify="space-between" mb="md">
+                <Title order={5}>{t("SCIM tokens")}</Title>
+                <Tooltip
+                  label={t(
+                    "You have reached the maximum of {{max}} SCIM tokens. Delete an existing token to create a new one.",
+                    { max: SCIM_TOKEN_LIMIT },
+                  )}
+                  disabled={(scimData?.items.length ?? 0) < SCIM_TOKEN_LIMIT}
+                  refProp="rootRef"
+                >
+                  <Button
+                    onClick={() => setCreateOpen(true)}
+                    disabled={(scimData?.items.length ?? 0) >= SCIM_TOKEN_LIMIT}
+                  >
+                    {t("Create {{credential}}", {
+                      credential: t("SCIM token"),
+                    })}
+                  </Button>
+                </Tooltip>
+              </Group>
+
+              <Card shadow="sm" radius="sm">
+                <ScimTokenTable
+                  tokens={scimData?.items}
+                  isLoading={scimLoading}
+                  onUpdate={setUpdateTarget}
+                  onRevoke={setRevokeTarget}
+                />
+              </Card>
+
+              <Space h="md" />
+
+              {scimData?.items.length > 0 && (
+                <Paginate
+                  hasPrevPage={scimData?.meta?.hasPrevPage}
+                  hasNextPage={scimData?.meta?.hasNextPage}
+                  onNext={() => goNext(scimData?.meta?.nextCursor)}
+                  onPrev={goPrev}
+                />
+              )}
+
+              <CreateScimTokenModal
+                opened={createOpen}
+                onClose={() => setCreateOpen(false)}
+                onSuccess={setCreatedToken}
+              />
+
+              <ScimTokenCreatedModal
+                opened={!!createdToken}
+                onClose={() => setCreatedToken(null)}
+                scimToken={createdToken}
+              />
+
+              <UpdateScimTokenModal
+                opened={!!updateTarget}
+                onClose={() => setUpdateTarget(null)}
+                scimToken={updateTarget}
+              />
+
+              <RevokeScimTokenModal
+                opened={!!revokeTarget}
+                onClose={() => setRevokeTarget(null)}
+                scimToken={revokeTarget}
+              />
+            </>
+          )}
+        </>
+      )}
    </>
  );
 }
@@ -10,6 +10,7 @@ import { useTranslation } from "react-i18next";
 import EmojiCommand from "@/features/editor/extensions/emoji-command";
 import mentionRenderItems from "@/features/editor/components/mention/mention-suggestion";
 import MentionView from "@/features/editor/components/mention/mention-view";
+import { platformModifierKey } from "@/lib";

 interface CommentEditorProps {
  defaultContent?: any;
@@ -83,7 +84,7 @@ const CommentEditor = forwardRef(
              }
            }

-            if ((event.ctrlKey || event.metaKey) && event.key === "Enter") {
+            if (platformModifierKey(event) && event.code === "Enter") {
              event.preventDefault();
              if (onSave) onSave();

@@ -19,7 +19,9 @@ export const uploadAttachmentAction = handleAttachmentUpload({
  },
  validateFn: (file, allowMedia: boolean) => {
    if (
-      (file.type.includes("image/") || file.type.includes("video/")) &&
+      (file.type.includes("image/") ||
+        file.type.includes("video/") ||
+        file.type === "application/pdf") &&
      !allowMedia
    ) {
      return false;
@@ -12,6 +12,7 @@ import {
  IconInfoCircle,
  IconList,
  IconListNumbers,
+  IconQuote,
  IconTypography,
 } from "@tabler/icons-react";
 import { Popover, Button, ScrollArea, Tooltip } from "@mantine/core";
@@ -59,6 +60,7 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
        isCodeBlock: ctx.editor.isActive("codeBlock"),
        isCallout: ctx.editor.isActive("callout"),
        isDetails: ctx.editor.isActive("details"),
+        isTransclusion: ctx.editor.isActive("transclusion"),
      };
    },
  });
@@ -140,6 +142,12 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
      command: () => editor.chain().focus().setDetails().run(),
      isActive: () => editorState?.isDetails,
    },
+    {
+      name: "Sync block",
+      icon: IconQuote,
+      command: () => editor.chain().focus().toggleTransclusion().run(),
+      isActive: () => editorState?.isTransclusion,
+    },
  ];

  const activeItem = items.filter((item) => item.isActive()).pop() ?? {
@@ -25,6 +25,7 @@ import {
  IconColumns3,
  IconColumns2,
  IconTag,
+  IconRotate2,
 } from "@tabler/icons-react";
 import {
  CommandProps,
@@ -477,6 +478,23 @@ const CommandGroups: SlashMenuGroupedItemsType = {
        editor.chain().focus().deleteRange(range).insertSubpages().run();
      },
    },
+    {
+      title: "Sync block",
+      description: "Create a block that stays in sync across pages.",
+      searchTerms: [
+        "sync",
+        "synced",
+        "sync block",
+        "excerpt",
+        "transclusion",
+        "reusable",
+        "snippet",
+      ],
+      icon: IconRotate2,
+      command: ({ editor, range }: CommandProps) => {
+        editor.chain().focus().deleteRange(range).insertTransclusion().run();
+      },
+    },
    {
      title: "2 Columns",
      description: "Split content into two columns.",
@@ -0,0 +1,22 @@
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function ErrorPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconAlertTriangle
+        size={20}
+        stroke={1.5}
+        className={classes.placeholderIcon}
+      />
+      <div className={classes.placeholderTitle}>
+        {t("Failed to load transclusion")}
+      </div>
+      <div className={classes.placeholderSubtext}>
+        {t("An error occurred while rendering this reference")}
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,16 @@
+import { IconEyeOff } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NoAccessPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconEyeOff size={20} stroke={1.5} className={classes.placeholderIcon} />
+      <div className={classes.placeholderTitle}>{t("No access")}</div>
+      <div className={classes.placeholderSubtext}>
+        {t("You don't have access to this content")}
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,24 @@
+import { IconQuestionMark } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NotFoundPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconQuestionMark
+        size={20}
+        stroke={1.5}
+        className={classes.placeholderIcon}
+      />
+      <div className={classes.placeholderTitle}>
+        {t("Synced block unavailable")}
+      </div>
+      <div className={classes.placeholderSubtext}>
+        {t(
+          "The source may have been removed, or embedding it here would create a loop.",
+        )}
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,52 @@
+import { EditorProvider } from "@tiptap/react";
+import { useMemo } from "react";
+import { mainExtensions } from "@/features/editor/extensions/extensions";
+import { UniqueID } from "@docmost/editor-ext";
+import { TransclusionLookupProvider } from "./transclusion-lookup-context";
+
+type Props = {
+  hostPageId: string;
+  content: unknown;
+};
+
+export default function TransclusionContent({ hostPageId, content }: Props) {
+  const extensions = useMemo(() => {
+    const filtered = mainExtensions.filter(
+      (e: any) => e.name !== "uniqueID" && e.name !== "globalDragHandle",
+    );
+    return [
+      ...filtered,
+      UniqueID.configure({
+        types: ["heading", "paragraph", "transclusion"],
+        updateDocument: false,
+      }),
+    ];
+  }, []);
+
+  // Isolate the nested read-only editor's events from the host editor:
+  // - mousedown/click would otherwise make the host node-select the atom
+  //   wrapper, blocking native text selection inside.
+  // - dragstart/dragover/drop would otherwise let the host treat events
+  //   inside the nested view as drops on the host, duplicating dropped
+  //   files at the transclusion's position.
+  const stop = (e: React.SyntheticEvent) => e.stopPropagation();
+
+  return (
+    <TransclusionLookupProvider hostPageId={hostPageId}>
+      <div
+        onMouseDown={stop}
+        onClick={stop}
+        onDragStart={stop}
+        onDragOver={stop}
+        onDrop={stop}
+      >
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={extensions}
+          content={content as any}
+        />
+      </div>
+    </TransclusionLookupProvider>
+  );
+}
@@ -0,0 +1,198 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { lookupTransclusion } from "@/features/transclusion/services/transclusion-api";
+import type { TransclusionLookup } from "@/features/transclusion/types/transclusion.types";
+
+type LookupKey = string; // `${sourcePageId}::${transclusionId}`
+
+type Subscriber = {
+  key: LookupKey;
+  sourcePageId: string;
+  transclusionId: string;
+  setResult: (r: TransclusionLookup) => void;
+};
+
+type ContextValue = {
+  /** Register a subscriber. Returns an unsubscribe function. */
+  subscribe: (s: Subscriber) => () => void;
+  /**
+   * Force a re-fetch of `key` and resolve when the response arrives (or the
+   * request fails). Bypasses the cache and any in-flight de-dup so the user
+   * always sees a fresh server read.
+   */
+  refresh: (key: LookupKey) => Promise<void>;
+};
+
+const TransclusionLookupContext = createContext<ContextValue | null>(null);
+
+export function TransclusionLookupProvider({
+  children,
+}: {
+  /**
+   * Retained for API compatibility with previous callers that passed the
+   * host page id; no longer used internally now that cycle prevention lives
+   * on the server side and lookups are stateless.
+   */
+  hostPageId?: string;
+  children: React.ReactNode;
+}) {
+  const subscribersRef = useRef(new Map<LookupKey, Subscriber[]>());
+  const queueRef = useRef(new Set<LookupKey>());
+  const tickRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Last looked-up value for each key. Re-subscribers (e.g. when the editor
+  // remounts after switching from static to live) get this immediately
+  // instead of triggering a duplicate fetch.
+  const resultCacheRef = useRef(new Map<LookupKey, TransclusionLookup>());
+  // Keys that are currently in flight in a batch request. A second subscribe
+  // for the same key while the first request is pending is a no-op; the
+  // subscriber is added to subscribersRef and will be notified when the
+  // pending request completes.
+  const inFlightRef = useRef(new Set<LookupKey>());
+  // Resolvers waiting on the next response for a key. Populated by refresh()
+  // so callers can await the fetch round-trip; resolved on success and on
+  // network error so the UI never hangs in a loading state.
+  const pendingRef = useRef(new Map<LookupKey, Array<() => void>>());
+
+  const flush = useCallback(async () => {
+    tickRef.current = null;
+    const keys = Array.from(queueRef.current);
+    queueRef.current.clear();
+    if (keys.length === 0) return;
+
+    for (const k of keys) inFlightRef.current.add(k);
+
+    const references = keys.map((k) => {
+      const [sourcePageId, transclusionId] = k.split("::");
+      return { sourcePageId, transclusionId };
+    });
+
+    const resolveWaiters = (key: LookupKey) => {
+      const waiters = pendingRef.current.get(key);
+      if (!waiters) return;
+      pendingRef.current.delete(key);
+      for (const w of waiters) w();
+    };
+
+    try {
+      const { items } = await lookupTransclusion({ references });
+      for (const r of items) {
+        const key = `${r.sourcePageId}::${r.transclusionId}`;
+        resultCacheRef.current.set(key, r);
+        inFlightRef.current.delete(key);
+        const subs = subscribersRef.current.get(key);
+        if (subs) {
+          for (const s of subs) s.setResult(r);
+        }
+        resolveWaiters(key);
+      }
+    } catch {
+      // Network error — leave subscribers in pending state and clear the
+      // in-flight flag so a future subscribe can retry.
+      for (const k of keys) {
+        inFlightRef.current.delete(k);
+        resolveWaiters(k);
+      }
+    }
+  }, []);
+
+  const enqueue = useCallback(
+    (key: LookupKey) => {
+      queueRef.current.add(key);
+      if (tickRef.current === null) {
+        tickRef.current = setTimeout(flush, 10);
+      }
+    },
+    [flush],
+  );
+
+  const subscribe = useCallback<ContextValue["subscribe"]>(
+    (s) => {
+      const list = subscribersRef.current.get(s.key) ?? [];
+      list.push(s);
+      subscribersRef.current.set(s.key, list);
+
+      const cached = resultCacheRef.current.get(s.key);
+      if (cached) {
+        s.setResult(cached);
+      } else if (!inFlightRef.current.has(s.key)) {
+        enqueue(s.key);
+      }
+
+      return () => {
+        const cur = subscribersRef.current.get(s.key) ?? [];
+        const next = cur.filter((x) => x !== s);
+        if (next.length === 0) subscribersRef.current.delete(s.key);
+        else subscribersRef.current.set(s.key, next);
+      };
+    },
+    [enqueue],
+  );
+
+  const refresh = useCallback<ContextValue["refresh"]>(
+    (key) =>
+      new Promise<void>((resolve) => {
+        resultCacheRef.current.delete(key);
+        inFlightRef.current.delete(key);
+        const waiters = pendingRef.current.get(key) ?? [];
+        waiters.push(resolve);
+        pendingRef.current.set(key, waiters);
+        enqueue(key);
+      }),
+    [enqueue],
+  );
+
+  useEffect(
+    () => () => {
+      if (tickRef.current) clearTimeout(tickRef.current);
+    },
+    [],
+  );
+
+  const value = useMemo<ContextValue>(
+    () => ({ subscribe, refresh }),
+    [subscribe, refresh],
+  );
+
+  return (
+    <TransclusionLookupContext.Provider value={value}>
+      {children}
+    </TransclusionLookupContext.Provider>
+  );
+}
+
+export function useTransclusionLookup(
+  sourcePageId: string | null | undefined,
+  transclusionId: string | null | undefined,
+): {
+  result: TransclusionLookup | null;
+  refresh: () => Promise<void>;
+} {
+  const ctx = useContext(TransclusionLookupContext);
+  const [result, setResult] = useState<TransclusionLookup | null>(null);
+
+  useEffect(() => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    const key = `${sourcePageId}::${transclusionId}`;
+    const unsubscribe = ctx.subscribe({
+      key,
+      sourcePageId,
+      transclusionId,
+      setResult,
+    });
+    return unsubscribe;
+  }, [ctx, sourcePageId, transclusionId]);
+
+  const refresh = useCallback(async () => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    await ctx.refresh(`${sourcePageId}::${transclusionId}`);
+  }, [ctx, sourcePageId, transclusionId]);
+
+  return { result, refresh };
+}
@@ -0,0 +1,204 @@
+import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconDots,
+  IconExternalLink,
+  IconLinkOff,
+  IconRefresh,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { ErrorBoundary } from "react-error-boundary";
+import { useTransclusionLookup } from "./transclusion-lookup-context";
+import TransclusionContent from "./transclusion-content";
+import NoAccessPlaceholder from "./no-access-placeholder";
+import NotFoundPlaceholder from "./not-found-placeholder";
+import ErrorPlaceholder from "./error-placeholder";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+import {
+  useReferencesQuery,
+  useUnsyncReferenceMutation,
+} from "@/features/transclusion/queries/transclusion-query";
+import { buildPageUrl } from "@/features/page/page.utils";
+
+export default function TransclusionReferenceView(props: NodeViewProps) {
+  const isEditable = props.editor.isEditable;
+  const sourcePageId: string | null = props.node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = props.node.attrs.transclusionId ?? null;
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  return (
+    <NodeViewWrapper
+      className={classes.includeWrap}
+      data-focused={isEditable && props.selected ? "true" : "false"}
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+      contentEditable={false}
+    >
+      <ErrorBoundary
+        resetKeys={[sourcePageId, transclusionId]}
+        fallback={<ErrorPlaceholder />}
+      >
+        <TransclusionReferenceBody {...props} trackOpen={trackOpen} />
+      </ErrorBoundary>
+    </NodeViewWrapper>
+  );
+}
+
+function TransclusionReferenceBody({
+  editor,
+  node,
+  deleteNode,
+  getPos,
+  trackOpen,
+}: NodeViewProps & { trackOpen: (open: boolean) => void }) {
+  const { t } = useTranslation();
+  const sourcePageId: string | null = node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = node.attrs.transclusionId ?? null;
+  const isEditable = editor.isEditable;
+
+  const { result, refresh } = useTransclusionLookup(
+    sourcePageId,
+    transclusionId,
+  );
+  const [refreshing, setRefreshing] = useState(false);
+  const handleRefresh = async () => {
+    setRefreshing(true);
+    try {
+      await refresh();
+    } finally {
+      setRefreshing(false);
+    }
+  };
+  // @ts-ignore - editor.storage.pageId is set by the host editor
+  const hostPageId: string | undefined = editor.storage?.pageId;
+  const unsyncMutation = useUnsyncReferenceMutation();
+  // Cached against the dropdown's identical query so the source link target
+  // is ready as soon as the controls fade in on hover, without a second
+  // fetch.
+  const referencesQuery = useReferencesQuery(
+    sourcePageId,
+    transclusionId,
+    isEditable,
+  );
+  const sourcePageHref = (() => {
+    const source = referencesQuery.data?.source;
+    if (source?.spaceSlug) {
+      return buildPageUrl(source.spaceSlug, source.slugId, source.title);
+    }
+    return sourcePageId ? `/p/${sourcePageId}` : null;
+  })();
+
+  const handleUnsync = async () => {
+    if (!hostPageId || !sourcePageId || !transclusionId) return;
+    try {
+      const { content } = await unsyncMutation.mutateAsync({
+        referencePageId: hostPageId,
+        sourcePageId,
+        transclusionId,
+      });
+      const pos = getPos();
+      if (typeof pos !== "number") return;
+      const from = pos;
+      const to = pos + node.nodeSize;
+      editor
+        .chain()
+        .focus()
+        .insertContentAt({ from, to }, content as any)
+        .run();
+    } catch {
+      // mutation surfaces errors via React Query; node stays as-is
+    }
+  };
+
+  return (
+    <>
+      {isEditable && (
+        <div className={classes.includeControls} contentEditable={false}>
+          {sourcePageId && transclusionId && hostPageId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={hostPageId}
+              mode="reference"
+              onOpenChange={trackOpen}
+            />
+          )}
+          <span className={classes.controlsDivider} />
+          <Tooltip label={t("Refresh")}>
+            <ActionIcon
+              variant="subtle"
+              color="gray"
+              size="sm"
+              onClick={handleRefresh}
+              loading={refreshing}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              <IconRefresh size={14} />
+            </ActionIcon>
+          </Tooltip>
+          {sourcePageHref && (
+            <Tooltip label={t("Go to source page")}>
+              <ActionIcon
+                component={Link}
+                to={sourcePageHref}
+                variant="subtle"
+                color="gray"
+                size="sm"
+              >
+                <IconExternalLink size={14} />
+              </ActionIcon>
+            </Tooltip>
+          )}
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+                disabled={
+                  unsyncMutation.isPending ||
+                  !hostPageId ||
+                  !sourcePageId ||
+                  !transclusionId
+                }
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Remove from page")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      {!sourcePageId || !transclusionId ? (
+        <NotFoundPlaceholder />
+      ) : !result ? (
+        <div style={{ minHeight: 24 }} />
+      ) : !("status" in result) ? (
+        <TransclusionContent
+          hostPageId={hostPageId ?? sourcePageId}
+          content={result.content}
+        />
+      ) : result.status === "no_access" ? (
+        <NoAccessPlaceholder />
+      ) : (
+        <NotFoundPlaceholder />
+      )}
+    </>
+  );
+}
@@ -0,0 +1,122 @@
+import {
+  NodeViewContent,
+  NodeViewProps,
+  NodeViewWrapper,
+} from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import {
+  IconCheck,
+  IconCopy,
+  IconDots,
+  IconLinkOff,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+
+export default function TransclusionView(props: NodeViewProps) {
+  const { editor, node, deleteNode } = props;
+  const { t } = useTranslation();
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  const isEditable = editor.isEditable;
+  // @ts-ignore - editor.storage.pageId is set by the host editor (page-editor.tsx onCreate)
+  const sourcePageId: string | undefined = editor.storage?.pageId;
+  const transclusionId: string | null = node.attrs.id ?? null;
+
+  const [copied, setCopied] = useState(false);
+  const handleCopy = async () => {
+    if (!sourcePageId || !transclusionId) return;
+    const html = `<div data-type="transclusionReference" data-source-page-id="${sourcePageId}" data-transclusion-id="${transclusionId}"></div>`;
+    try {
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/html": new Blob([html], { type: "text/html" }),
+          "text/plain": new Blob([html], { type: "text/plain" }),
+        }),
+      ]);
+    } catch {
+      // Fallback for browsers without ClipboardItem write support
+      try {
+        await navigator.clipboard.writeText(html);
+      } catch {
+        return;
+      }
+    }
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), 2000);
+    notifications.show({
+      message: t("Copied. Paste on any page to embed this synced block."),
+    });
+  };
+
+  const handleUnsync = () => {
+    editor.chain().focus().unsyncTransclusion().run();
+  };
+
+  return (
+    <NodeViewWrapper
+      className={classes.transclusionWrap}
+      data-drag-handle
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+    >
+      {isEditable && (
+        <div className={classes.transclusionControls} contentEditable={false}>
+          {sourcePageId && transclusionId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={sourcePageId}
+              mode="source"
+              onOpenChange={trackOpen}
+            />
+          )}
+
+          <span className={classes.controlsDivider} />
+
+          <Tooltip label={copied ? t("Copied") : t("Copy synced block")}>
+            <ActionIcon
+              variant="subtle"
+              color={copied ? "teal" : "gray"}
+              size="sm"
+              onClick={handleCopy}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              {copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
+            </ActionIcon>
+          </Tooltip>
+
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Delete sync block")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      <NodeViewContent />
+    </NodeViewWrapper>
+  );
+}
@@ -0,0 +1,199 @@
+.placeholder {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: var(--mantine-spacing-md);
+  border-radius: var(--mantine-radius-md);
+  background: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+  border: 1px dashed
+    light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-4));
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+}
+
+.placeholderIcon {
+  color: light-dark(var(--mantine-color-gray-5), var(--mantine-color-dark-3));
+}
+
+.placeholderTitle {
+  font-weight: 600;
+  font-size: var(--mantine-font-size-sm);
+}
+
+.placeholderSubtext {
+  font-size: var(--mantine-font-size-xs);
+  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+  text-align: center;
+}
+
+.transclusionBadge {
+  display: inline-block;
+  padding: 2px 8px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 600;
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  border-radius: var(--mantine-radius-sm);
+  margin-bottom: 4px;
+}
+
+.transclusionWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 3rem;
+  border-radius: 4px;
+  border: 1px solid transparent;
+  transition: border 0.3s;
+}
+
+.transclusionWrap:hover,
+.transclusionWrap:focus-within {
+  border: 1px solid
+    light-dark(var(--mantine-color-gray-3), var(--mantine-color-gray-7));
+}
+
+.transclusionControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.transclusionControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.transclusionWrap:hover .transclusionControls,
+.transclusionWrap:focus-within .transclusionControls,
+.transclusionWrap[data-menu-open="true"] .transclusionControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.controlsDivider {
+  display: inline-block;
+  width: 1px;
+  height: 16px;
+  background: var(--mantine-color-default-border);
+}
+
+.includeWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 0;
+  border-radius: 4px;
+  border: 1px solid transparent;
+  transition: border 0.3s;
+}
+
+.includeWrap:hover,
+.includeWrap[data-focused="true"],
+.includeWrap[data-menu-open="true"] {
+  border: 1px solid
+    light-dark(var(--mantine-color-gray-3), var(--mantine-color-gray-7));
+}
+
+.includeControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.includeControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.includeWrap:hover .includeControls,
+.includeWrap:focus-within .includeControls,
+.includeWrap[data-focused="true"] .includeControls,
+.includeWrap[data-menu-open="true"] .includeControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+:global(.react-renderer.node-transclusion.ProseMirror-selectednode),
+:global(.react-renderer.node-transclusionReference.ProseMirror-selectednode) {
+  outline: none;
+}
+
+@media (max-width: 48em) {
+  .transclusionWrap,
+  .includeWrap {
+    margin-left: -1rem;
+    margin-right: -1rem;
+    width: calc(100% + 2rem);
+  }
+
+  .transclusionWrap {
+    padding-left: 1rem;
+    padding-right: 1rem;
+  }
+}
+
+@media print {
+  .transclusionControls,
+  .includeControls {
+    display: none !important;
+  }
+}
+
+.editingOriginalTag {
+  display: inline-block;
+  padding: 0 6px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
+  color: var(--mantine-color-blue-7);
+  background: light-dark(
+    var(--mantine-color-blue-0),
+    var(--mantine-color-blue-9)
+  );
+  border-radius: var(--mantine-radius-sm);
+}
@@ -0,0 +1,419 @@
+import { Extension } from "@tiptap/core";
+import {
+  NodeSelection,
+  Plugin,
+  PluginKey,
+  TextSelection,
+} from "@tiptap/pm/state";
+import { Fragment, Slice, Node } from "@tiptap/pm/model";
+import { EditorView } from "@tiptap/pm/view";
+
+export interface GlobalDragHandleOptions {
+  /**
+   * The width of the drag handle
+   */
+  dragHandleWidth: number;
+
+  /**
+   * The treshold for scrolling
+   */
+  scrollThreshold: number;
+
+  /*
+   * The css selector to query for the drag handle. (eg: '.custom-handle').
+   * If handle element is found, that element will be used as drag handle. If not, a default handle will be created
+   */
+  dragHandleSelector?: string;
+
+  /**
+   * Tags to be excluded for drag handle
+   */
+  excludedTags: string[];
+
+  /**
+   * Custom nodes to be included for drag handle
+   */
+  customNodes: string[];
+}
+function absoluteRect(node: Element) {
+  const data = node.getBoundingClientRect();
+  const modal = node.closest('[role="dialog"]');
+
+  if (modal && window.getComputedStyle(modal).transform !== "none") {
+    const modalRect = modal.getBoundingClientRect();
+
+    return {
+      top: data.top - modalRect.top,
+      left: data.left - modalRect.left,
+      width: data.width,
+    };
+  }
+  return {
+    top: data.top,
+    left: data.left,
+    width: data.width,
+  };
+}
+
+function nodeDOMAtCoords(
+  coords: { x: number; y: number },
+  options: GlobalDragHandleOptions,
+  view: EditorView,
+) {
+  const selectors = [
+    "li",
+    "p:not(:first-child)",
+    "pre",
+    "blockquote",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    ...options.customNodes.map((node) => `[data-type=${node}]`),
+  ].join(", ");
+  return document
+    .elementsFromPoint(coords.x, coords.y)
+    .find((elem: Element) => {
+      // Skip elements that belong to a nested editor (e.g. transclusion
+      // references render their own ProseMirror instance). Only consider
+      // elements whose closest editor is this host view.
+      if (elem.closest(".ProseMirror") !== view.dom) return false;
+      return (
+        elem.parentElement?.matches?.(".ProseMirror") ||
+        elem.matches(selectors)
+      );
+    });
+}
+function nodePosAtDOM(
+  node: Element,
+  view: EditorView,
+  options: GlobalDragHandleOptions,
+) {
+  const boundingRect = node.getBoundingClientRect();
+
+  return view.posAtCoords({
+    left: boundingRect.left + 50 + options.dragHandleWidth,
+    top: boundingRect.top + 1,
+  })?.inside;
+}
+
+function calcNodePos(pos: number, view: EditorView) {
+  const $pos = view.state.doc.resolve(pos);
+  if ($pos.depth > 1) return $pos.before($pos.depth);
+  return pos;
+}
+
+export function DragHandlePlugin(
+  options: GlobalDragHandleOptions & { pluginKey: string },
+) {
+  let listType = "";
+  function handleDragStart(event: DragEvent, view: EditorView) {
+    view.focus();
+
+    if (!event.dataTransfer) return;
+
+    const node = nodeDOMAtCoords(
+      {
+        x: event.clientX + 50 + options.dragHandleWidth,
+        y: event.clientY,
+      },
+      options,
+      view,
+    );
+
+    if (!(node instanceof Element)) return;
+
+    let draggedNodePos = nodePosAtDOM(node, view, options);
+    if (draggedNodePos == null || draggedNodePos < 0) return;
+    draggedNodePos = calcNodePos(draggedNodePos, view);
+
+    const { from, to } = view.state.selection;
+    const diff = from - to;
+
+    const fromSelectionPos = calcNodePos(from, view);
+    let differentNodeSelected = false;
+
+    const nodePos = view.state.doc.resolve(fromSelectionPos);
+
+    // Check if nodePos points to the top level node
+    if (nodePos.node().type.name === "doc") differentNodeSelected = true;
+    else {
+      const nodeSelection = NodeSelection.create(
+        view.state.doc,
+        nodePos.before(),
+      );
+
+      // Check if the node where the drag event started is part of the current selection
+      differentNodeSelected = !(
+        draggedNodePos + 1 >= nodeSelection.$from.pos &&
+        draggedNodePos <= nodeSelection.$to.pos
+      );
+    }
+    let selection = view.state.selection;
+    if (
+      !differentNodeSelected &&
+      diff !== 0 &&
+      !(view.state.selection instanceof NodeSelection)
+    ) {
+      const endSelection = NodeSelection.create(view.state.doc, to - 1);
+      selection = TextSelection.create(
+        view.state.doc,
+        draggedNodePos,
+        endSelection.$to.pos,
+      );
+    } else {
+      selection = NodeSelection.create(view.state.doc, draggedNodePos);
+
+      // if inline node is selected, e.g mention -> go to the parent node to select the whole node
+      // if table row is selected, go to the parent node to select the whole node
+      if (
+        (selection as NodeSelection).node.type.isInline ||
+        (selection as NodeSelection).node.type.name === "tableRow"
+      ) {
+        let $pos = view.state.doc.resolve(selection.from);
+        selection = NodeSelection.create(view.state.doc, $pos.before());
+      }
+    }
+    view.dispatch(view.state.tr.setSelection(selection));
+
+    // If the selected node is a list item, we need to save the type of the wrapping list e.g. OL or UL
+    if (
+      view.state.selection instanceof NodeSelection &&
+      view.state.selection.node.type.name === "listItem"
+    ) {
+      listType = node.parentElement!.tagName;
+    }
+
+    const slice = view.state.selection.content();
+    const { dom, text } = view.serializeForClipboard(slice);
+
+    event.dataTransfer.clearData();
+    event.dataTransfer.setData("text/html", dom.innerHTML);
+    event.dataTransfer.setData("text/plain", text);
+    event.dataTransfer.effectAllowed = "move";
+
+    event.dataTransfer.setDragImage(node, 0, 0);
+
+    view.dragging = { slice, move: event.ctrlKey };
+  }
+
+  let dragHandleElement: HTMLElement | null = null;
+
+  function hideDragHandle() {
+    if (dragHandleElement) {
+      dragHandleElement.classList.add("hide");
+    }
+  }
+
+  function showDragHandle() {
+    if (dragHandleElement) {
+      dragHandleElement.classList.remove("hide");
+    }
+  }
+
+  function hideHandleOnEditorOut(event: MouseEvent) {
+    if (event.target instanceof Element) {
+      // Check if the relatedTarget class is still inside the editor
+      const relatedTarget = event.relatedTarget as HTMLElement;
+      const isInsideEditor =
+        relatedTarget?.classList.contains("tiptap") ||
+        relatedTarget?.classList.contains("drag-handle");
+
+      if (isInsideEditor) return;
+    }
+    hideDragHandle();
+  }
+
+  return new Plugin({
+    key: new PluginKey(options.pluginKey),
+    view: (view) => {
+      const handleBySelector = options.dragHandleSelector
+        ? document.querySelector<HTMLElement>(options.dragHandleSelector)
+        : null;
+      dragHandleElement = handleBySelector ?? document.createElement("div");
+      dragHandleElement.draggable = true;
+      dragHandleElement.dataset.dragHandle = "";
+      dragHandleElement.classList.add("drag-handle");
+
+      function onDragHandleDragStart(e: DragEvent) {
+        handleDragStart(e, view);
+      }
+
+      dragHandleElement.addEventListener("dragstart", onDragHandleDragStart);
+
+      function onDragHandleDrag(e: DragEvent) {
+        hideDragHandle();
+        let scrollY = window.scrollY;
+        if (e.clientY < options.scrollThreshold) {
+          window.scrollTo({ top: scrollY - 30, behavior: "smooth" });
+        } else if (window.innerHeight - e.clientY < options.scrollThreshold) {
+          window.scrollTo({ top: scrollY + 30, behavior: "smooth" });
+        }
+      }
+
+      dragHandleElement.addEventListener("drag", onDragHandleDrag);
+
+      hideDragHandle();
+
+      if (!handleBySelector) {
+        view?.dom?.parentElement?.appendChild(dragHandleElement);
+      }
+      view?.dom?.parentElement?.addEventListener(
+        "mouseout",
+        hideHandleOnEditorOut,
+      );
+
+      return {
+        destroy: () => {
+          if (!handleBySelector) {
+            dragHandleElement?.remove?.();
+          }
+          dragHandleElement?.removeEventListener("drag", onDragHandleDrag);
+          dragHandleElement?.removeEventListener(
+            "dragstart",
+            onDragHandleDragStart,
+          );
+          dragHandleElement = null;
+          view?.dom?.parentElement?.removeEventListener(
+            "mouseout",
+            hideHandleOnEditorOut,
+          );
+        },
+      };
+    },
+    props: {
+      handleDOMEvents: {
+        mousemove: (view, event) => {
+          if (!view.editable) {
+            return;
+          }
+
+          const node = nodeDOMAtCoords(
+            {
+              x: event.clientX + 50 + options.dragHandleWidth,
+              y: event.clientY,
+            },
+            options,
+            view,
+          );
+
+          const notDragging = node?.closest(".not-draggable");
+          const excludedTagList = options.excludedTags
+            .concat(["ol", "ul"])
+            .join(", ");
+
+          if (
+            !(node instanceof Element) ||
+            node.matches(excludedTagList) ||
+            notDragging
+          ) {
+            hideDragHandle();
+            return;
+          }
+
+          const compStyle = window.getComputedStyle(node);
+          const parsedLineHeight = parseInt(compStyle.lineHeight, 10);
+          const lineHeight = isNaN(parsedLineHeight)
+            ? parseInt(compStyle.fontSize) * 1.2
+            : parsedLineHeight;
+          const paddingTop = parseInt(compStyle.paddingTop, 10);
+
+          const rect = absoluteRect(node);
+
+          rect.top += (lineHeight - 24) / 2;
+          rect.top += paddingTop;
+          // Li markers
+          if (node.matches("ul:not([data-type=taskList]) li, ol li")) {
+            rect.left -= options.dragHandleWidth;
+          }
+          rect.width = options.dragHandleWidth;
+
+          if (!dragHandleElement) return;
+
+          dragHandleElement.style.left = `${rect.left - rect.width}px`;
+          dragHandleElement.style.top = `${rect.top}px`;
+          showDragHandle();
+        },
+        keydown: () => {
+          hideDragHandle();
+        },
+        mousewheel: () => {
+          hideDragHandle();
+        },
+        // dragging class is used for CSS
+        dragstart: (view) => {
+          view.dom.classList.add("dragging");
+        },
+        drop: (view, event) => {
+          view.dom.classList.remove("dragging");
+          hideDragHandle();
+          let droppedNode: Node | null = null;
+          const dropPos = view.posAtCoords({
+            left: event.clientX,
+            top: event.clientY,
+          });
+
+          if (!dropPos) return;
+
+          if (view.state.selection instanceof NodeSelection) {
+            droppedNode = view.state.selection.node;
+          }
+          if (!droppedNode) return;
+
+          const resolvedPos = view.state.doc.resolve(dropPos.pos);
+
+          const isDroppedInsideList =
+            resolvedPos.parent.type.name === "listItem";
+
+          // If the selected node is a list item and is not dropped inside a list, we need to wrap it inside <ol> tag otherwise ol list items will be transformed into ul list item when dropped
+          if (
+            view.state.selection instanceof NodeSelection &&
+            view.state.selection.node.type.name === "listItem" &&
+            !isDroppedInsideList &&
+            listType == "OL"
+          ) {
+            const newList = view.state.schema.nodes.orderedList?.createAndFill(
+              null,
+              droppedNode,
+            );
+            const slice = new Slice(Fragment.from(newList), 0, 0);
+            view.dragging = { slice, move: event.ctrlKey };
+          }
+        },
+        dragend: (view) => {
+          view.dom.classList.remove("dragging");
+        },
+      },
+    },
+  });
+}
+
+const GlobalDragHandle = Extension.create({
+  name: "globalDragHandle",
+
+  addOptions() {
+    return {
+      dragHandleWidth: 20,
+      scrollTreshold: 100,
+      excludedTags: [],
+      customNodes: [],
+    };
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      DragHandlePlugin({
+        pluginKey: "globalDragHandle",
+        dragHandleWidth: this.options.dragHandleWidth,
+        scrollThreshold: this.options.scrollThreshold,
+        dragHandleSelector: this.options.dragHandleSelector,
+        excludedTags: this.options.excludedTags,
+        customNodes: this.options.customNodes,
+      }),
+    ];
+  },
+});
+
+export default GlobalDragHandle;
@@ -9,7 +9,6 @@ import SubScript from "@tiptap/extension-subscript";
 import { Typography } from "@tiptap/extension-typography";
 import { TextStyle } from "@tiptap/extension-text-style";
 import { Color } from "@tiptap/extension-color";
-import GlobalDragHandle from "tiptap-extension-global-drag-handle";
 import { Youtube } from "@tiptap/extension-youtube";
 import SlashCommand, { SlashCommandExtension as Command } from "@/features/editor/extensions/slash-command";
 import renderItems from "@/features/editor/components/slash-menu/render-items";
@@ -52,6 +51,8 @@ import {
  Columns,
  Column,
  Status,
+  Transclusion,
+  TransclusionReference,
 } from "@docmost/editor-ext";
 import {
  randomElement,
@@ -80,6 +81,8 @@ import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-v
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import PdfView from "@/features/editor/components/pdf/pdf-view.tsx";
 import SubpagesView from "@/features/editor/components/subpages/subpages-view.tsx";
+import TransclusionView from "@/features/editor/components/transclusion/transclusion-view.tsx";
+import TransclusionReferenceView from "@/features/editor/components/transclusion/transclusion-reference-view.tsx";
 import { common, createLowlight } from "lowlight";
 import plaintext from "highlight.js/lib/languages/plaintext";
 import powershell from "highlight.js/lib/languages/powershell";
@@ -100,6 +103,7 @@ import { MarkdownClipboard } from "@/features/editor/extensions/markdown-clipboa
 import EmojiCommand from "./emoji-command";
 import { countWords } from "alfaaz";
 import AutoJoiner from "@/features/editor/extensions/autojoiner.ts";
+import GlobalDragHandle from "@/features/editor/extensions/drag-handle.ts";

 const lowlight = createLowlight(common);
 lowlight.register("mermaid", plaintext);
@@ -167,7 +171,7 @@ export const mainExtensions = [
  SharedStorage,
  Heading,
  UniqueID.configure({
-    types: ["heading", "paragraph"],
+    types: ["heading", "paragraph", "transclusion"],
    filterTransaction: (transaction) => !isChangeOrigin(transaction),
  }),
  Placeholder.configure({
@@ -215,7 +219,9 @@ export const mainExtensions = [
  }),
  Typography,
  TrailingNode,
-  GlobalDragHandle,
+  GlobalDragHandle.configure({
+    customNodes: ["transclusion", "transclusionReference"],
+  }),
  TextStyle,
  Color,
  SlashCommand,
@@ -351,6 +357,12 @@ export const mainExtensions = [
  Status.configure({
    view: StatusView,
  }),
+  Transclusion.configure({
+    view: TransclusionView,
+  }),
+  TransclusionReference.configure({
+    view: TransclusionReferenceView,
+  }),
  MarkdownClipboard.configure({
    transformPastedText: true,
  }),
@@ -80,10 +80,12 @@ export const MarkdownClipboard = Extension.create({
            const { from, to } = view.state.selection;

            const parsed = markdownToHtml(text.replace(/\n+$/, ""));
+            const body = elementFromString(parsed);
+            normalizeTableColumnWidths(body);

            const contentNodes = DOMParser.fromSchema(
              this.editor.schema,
-            ).parseSlice(elementFromString(parsed), {
+            ).parseSlice(body, {
              preserveWhitespace: true,
            });

@@ -137,3 +139,92 @@ function elementFromString(value) {

  return new window.DOMParser().parseFromString(wrappedValue, "text/html").body;
 }
+
+const DEFAULT_PASTE_COL_WIDTH_PX = 150;
+
+function parsePixelWidth(el: Element): number | null {
+  const attr = el.getAttribute("width");
+  if (attr) {
+    const n = parseInt(attr, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  const style = el.getAttribute("style") || "";
+  const m = style.match(/(?:^|;)\s*width\s*:\s*([\d.]+)\s*px/i);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return null;
+}
+
+function getFirstRow(table: Element): Element | null {
+  const tbodyRow = table.querySelector(":scope > tbody > tr");
+  if (tbodyRow) return tbodyRow;
+  const theadRow = table.querySelector(":scope > thead > tr");
+  if (theadRow) return theadRow;
+  return table.querySelector(":scope > tr");
+}
+
+function deriveColumnWidths(table: Element): (number | null)[] | null {
+  const cols = table.querySelectorAll(":scope > colgroup > col");
+  if (cols.length > 0) {
+    const widths: (number | null)[] = [];
+    cols.forEach((col) => widths.push(parsePixelWidth(col)));
+    if (widths.some((w) => w !== null)) return widths;
+  }
+
+  const firstRow = getFirstRow(table);
+  if (!firstRow) return null;
+
+  const widths: (number | null)[] = [];
+  Array.from(firstRow.children)
+    .filter((c) => c.tagName === "TD" || c.tagName === "TH")
+    .forEach((cell) => {
+      const colspan = parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+      const w = parsePixelWidth(cell);
+      for (let i = 0; i < colspan; i++) {
+        widths.push(w !== null ? Math.round(w / colspan) : null);
+      }
+    });
+  if (widths.length === 0 || widths.every((w) => w === null)) return null;
+  return widths;
+}
+
+// Mirror of server normalizeTableColumnWidths (see import/utils/table-utils.ts):
+// markdown source has no widths, so without this every pasted table renders
+// at table-layout:fixed/100% and squashes columns to fit the editor instead of
+// letting .tableWrapper's overflow-x: auto scroll.
+export function normalizeTableColumnWidths(root: Element): void {
+  root.querySelectorAll("table").forEach((table) => {
+    const firstRow = getFirstRow(table);
+    if (!firstRow) return;
+
+    let colWidths = deriveColumnWidths(table);
+    if (!colWidths) {
+      let count = 0;
+      Array.from(firstRow.children)
+        .filter((c) => c.tagName === "TD" || c.tagName === "TH")
+        .forEach((cell) => {
+          count += parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+        });
+      if (count === 0) return;
+      colWidths = new Array(count).fill(DEFAULT_PASTE_COL_WIDTH_PX);
+    }
+
+    let col = 0;
+    Array.from(firstRow.children)
+      .filter((c) => c.tagName === "TD" || c.tagName === "TH")
+      .forEach((cell) => {
+        if (cell.getAttribute("colwidth")) {
+          col += parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+          return;
+        }
+        const colspan = parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+        const slice = colWidths!.slice(col, col + colspan);
+        col += colspan;
+        if (slice.length === 0 || slice.every((w) => w === null)) return;
+        const values = slice.map((w) => (w == null ? 100 : w));
+        cell.setAttribute("colwidth", values.join(","));
+      });
+  });
+}
@@ -62,7 +62,7 @@ import { useIdle } from "@/hooks/use-idle.ts";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { useParams } from "react-router-dom";
-import { extractPageSlugId } from "@/lib";
+import { extractPageSlugId, platformModifierKey } from "@/lib";
 import { FIVE_MINUTES } from "@/lib/constants.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { jwtDecode } from "jwt-decode";
@@ -71,6 +71,7 @@ import { useEditorScroll } from "./hooks/use-editor-scroll";
 import { EditorAiMenu } from "@/ee/ai/components/editor/ai-menu/ai-menu";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
 import ColumnsMenu from "@/features/editor/components/columns/columns-menu.tsx";
+import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";

 interface PageEditorProps {
  pageId: string;
@@ -232,11 +233,19 @@ export default function PageEditor({
        scrollMargin: 80,
        handleDOMEvents: {
          keydown: (_view, event) => {
-            if ((event.ctrlKey || event.metaKey) && event.code === "KeyS") {
+            if (platformModifierKey(event) && event.code === "KeyS") {
              event.preventDefault();
              return true;
            }
-            if ((event.ctrlKey || event.metaKey) && event.code === "KeyK") {
+            if (event.key === "Tab") {
+                const editor = editorRef.current;
+                if (!editor) return false;
+                event.preventDefault();
+                return editor.view.someProp("handleKeyDown", (f) =>
+                  f(editor.view, event)
+                );
+            }
+            if (platformModifierKey(event) && event.code === "KeyK") {
              searchSpotlight.open();
              return true;
            }
@@ -391,55 +400,60 @@ export default function PageEditor({
    }
  }, [yjsConnectionStatus, isSynced]);

-  if (showStatic) {
-    return (
-      <EditorProvider
-        editable={false}
-        immediatelyRender={true}
-        extensions={mainExtensions}
-        content={content}
-      />
-    );
-  }
-
  return (
-    <div className="editor-container" style={{ position: "relative" }}>
-      <div ref={menuContainerRef}>
-        <EditorContent editor={editor} />
+    <TransclusionLookupProvider hostPageId={pageId}>
+      {showStatic ? (
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={mainExtensions}
+          content={content}
+        />
+      ) : (
+        <div className="editor-container" style={{ position: "relative" }}>
+          <div ref={menuContainerRef}>
+            <EditorContent editor={editor} />

-        {editor && (
-          <SearchAndReplaceDialog editor={editor} editable={editable} />
-        )}
+            {editor && (
+              <SearchAndReplaceDialog editor={editor} editable={editable} />
+            )}

-        {editor && editorIsEditable && (
-          <div>
-            <EditorAiMenu editor={editor} />
-            <EditorLinkMenu editor={editor} />
-            <EditorBubbleMenu editor={editor} />
-            <TableMenu editor={editor} />
-            <TableCellMenu editor={editor} appendTo={menuContainerRef} />
-            <ImageMenu editor={editor} />
-            <VideoMenu editor={editor} />
-            <PdfMenu editor={editor} />
-            <CalloutMenu editor={editor} />
-            <SubpagesMenu editor={editor} />
-            <ExcalidrawMenu editor={editor} />
-            <DrawioMenu editor={editor} />
-            <ColumnsMenu editor={editor} />
+            {editor && editorIsEditable && (
+              <div>
+                <EditorAiMenu editor={editor} />
+                <EditorLinkMenu editor={editor} />
+                <EditorBubbleMenu editor={editor} />
+                <TableMenu editor={editor} />
+                <TableCellMenu editor={editor} appendTo={menuContainerRef} />
+                <ImageMenu editor={editor} />
+                <VideoMenu editor={editor} />
+                <PdfMenu editor={editor} />
+                <CalloutMenu editor={editor} />
+                <SubpagesMenu editor={editor} />
+                <ExcalidrawMenu editor={editor} />
+                <DrawioMenu editor={editor} />
+                <ColumnsMenu editor={editor} />
+              </div>
+            )}
+            {editor &&
+              !editorIsEditable &&
+              (editable || canComment) &&
+              providersRef.current && (
+                <ReadonlyBubbleMenu editor={editor} />
+              )}
+            {showCommentPopup && (
+              <CommentDialog editor={editor} pageId={pageId} />
+            )}
+            {showReadOnlyCommentPopup && (
+              <CommentDialog editor={editor} pageId={pageId} readOnly />
+            )}
          </div>
-        )}
-        {editor && !editorIsEditable && (editable || canComment) && providersRef.current && (
-          <ReadonlyBubbleMenu editor={editor} />
-        )}
-        {showCommentPopup && <CommentDialog editor={editor} pageId={pageId} />}
-        {showReadOnlyCommentPopup && (
-          <CommentDialog editor={editor} pageId={pageId} readOnly />
-        )}
-      </div>
-      <div
-        onClick={() => editor.commands.focus("end")}
-        style={{ paddingBottom: "20vh" }}
-      ></div>
-    </div>
+          <div
+            onClick={() => editor.commands.focus("end")}
+            style={{ paddingBottom: "20vh" }}
+          ></div>
+        </div>
+      )}
+    </TransclusionLookupProvider>
  );
 }
@@ -9,6 +9,7 @@ import { Placeholder } from "@tiptap/extension-placeholder";
 import { useAtom } from "jotai";
 import { readOnlyEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
+import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";

 interface PageEditorProps {
  title: string;
@@ -65,7 +66,7 @@ export default function ReadonlyPageEditor({
  ];

  return (
-    <>
+    <TransclusionLookupProvider hostPageId={pageId ?? "anonymous"}>
      <div className="page-title">
        <EditorProvider
          editable={false}
@@ -95,6 +96,6 @@ export default function ReadonlyPageEditor({
        }}
      ></EditorProvider>
      <div style={{ paddingBottom: "20vh" }}></div>
-    </>
+    </TransclusionLookupProvider>
  );
 }
@@ -27,6 +27,7 @@ import localEmitter from "@/lib/local-emitter.ts";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { searchSpotlight } from "@/features/search/constants.ts";
+import { platformModifierKey } from "@/lib";

 export interface TitleEditorProps {
  pageId: string;
@@ -90,11 +91,11 @@ export function TitleEditor({
    editorProps: {
      handleDOMEvents: {
        keydown: (_view, event) => {
-          if ((event.ctrlKey || event.metaKey) && event.code === "KeyS") {
+          if (platformModifierKey(event) && event.code === "KeyS") {
            event.preventDefault();
            return true;
          }
-          if ((event.ctrlKey || event.metaKey) && event.code === "KeyK") {
+          if (platformModifierKey(event) && event.code === "KeyK") {
            searchSpotlight.open();
            return true;
          }
@@ -12,6 +12,7 @@ import {
  IconCheck,
  IconFileCode,
  IconFileTypeDocx,
+  IconFileTypePdf,
  IconFileTypeZip,
  IconMarkdown,
  IconX,
@@ -90,12 +91,14 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
  const markdownFileRef = useRef<() => void>(null);
  const htmlFileRef = useRef<() => void>(null);
  const docxFileRef = useRef<() => void>(null);
+  const pdfFileRef = useRef<() => void>(null);
  const notionFileRef = useRef<() => void>(null);
  const confluenceFileRef = useRef<() => void>(null);
  const zipFileRef = useRef<() => void>(null);

  const canUseConfluence = useHasFeature(Feature.CONFLUENCE_IMPORT);
  const canUseDocx = useHasFeature(Feature.DOCX_IMPORT);
+  const canUsePdf = useHasFeature(Feature.PDF_IMPORT);
  const upgradeLabel = useUpgradeLabel();

  const handleZipUpload = async (selectedFile: File, source: string) => {
@@ -244,7 +247,7 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
    }, 3000);
  }, [fileTaskId]);

-  const maxSingleFileSize = bytes("20mb");
+  const maxSingleFileSize = bytes("30mb");

  const handleFileUpload = async (selectedFiles: File[]) => {
    if (!selectedFiles) {
@@ -298,6 +301,7 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
      if (markdownFileRef.current) markdownFileRef.current();
      if (htmlFileRef.current) htmlFileRef.current();
      if (docxFileRef.current) docxFileRef.current();
+      if (pdfFileRef.current) pdfFileRef.current();

      const pageCountText =
        pageCount === 1 ? `1 ${t("page")}` : `${pageCount} ${t("pages")}`;
@@ -378,6 +382,30 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
          )}
        </FileButton>

+        <FileButton
+          onChange={handleFileUpload}
+          accept=".pdf"
+          multiple
+          resetRef={pdfFileRef}
+        >
+          {(props) => (
+            <Tooltip
+              label={upgradeLabel}
+              disabled={canUsePdf}
+            >
+              <Button
+                disabled={!canUsePdf}
+                justify="start"
+                variant="default"
+                leftSection={<IconFileTypePdf size={18} />}
+                {...props}
+              >
+                PDF
+              </Button>
+            </Tooltip>
+          )}
+        </FileButton>
+
        <FileButton
          onChange={(file) => handleZipUpload(file, "notion")}
          accept="application/zip"
@@ -13,6 +13,7 @@ import {
 import classes from "./search-control.module.css";
 import React from "react";
 import { useTranslation } from "react-i18next";
+import { platformModifierLabel } from "@/lib";

 interface SearchControlProps extends BoxProps, ElementProps<"button"> {}

@@ -27,7 +28,7 @@ export function SearchControl({ className, ...others }: SearchControlProps) {
          {t("Search")}
        </Text>
        <Text fw={700} className={classes.shortcut}>
-          Ctrl + K
+          {platformModifierLabel} + K
        </Text>
      </Group>
    </UnstyledButton>
@@ -0,0 +1,205 @@
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 6px 3px 6px;
+  border-radius: 999px;
+  background: transparent;
+  border: 0;
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--mantine-font-size-xs);
+  color: light-dark(
+    var(--mantine-color-gray-7),
+    var(--mantine-color-dark-1)
+  );
+  transition: background 120ms ease;
+  user-select: none;
+}
+
+.trigger:hover {
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+}
+
+.triggerIcon {
+  color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+  display: inline-flex;
+}
+
+.triggerChev {
+  color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+  display: inline-flex;
+  margin-left: 2px;
+}
+
+.dropdown {
+  padding: 0;
+}
+
+.banner {
+  display: flex;
+  gap: 10px;
+  padding: 10px 14px;
+  background: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+  border-bottom: 1px solid
+    light-dark(var(--mantine-color-gray-2), var(--mantine-color-dark-4));
+  color: light-dark(
+    var(--mantine-color-gray-7),
+    var(--mantine-color-dark-1)
+  );
+  font-size: var(--mantine-font-size-xs);
+  line-height: 1.5;
+}
+
+.bannerIcon {
+  color: light-dark(
+    var(--mantine-color-gray-6),
+    var(--mantine-color-dark-2)
+  );
+  flex: none;
+  display: inline-flex;
+  margin-top: 1px;
+}
+
+.bannerLink {
+  color: light-dark(
+    var(--mantine-color-gray-9),
+    var(--mantine-color-dark-0)
+  );
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  text-decoration-thickness: 1px;
+  font-weight: 500;
+}
+
+.bannerLink:hover {
+  text-decoration-thickness: 2px;
+}
+
+.section {
+  padding: 12px;
+}
+
+.sectionLabel {
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
+  color: light-dark(
+    var(--mantine-color-gray-6),
+    var(--mantine-color-dark-2)
+  );
+  margin: 0 0 6px;
+  padding: 0 4px;
+}
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 6px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  color: light-dark(
+    var(--mantine-color-gray-9),
+    var(--mantine-color-dark-0)
+  );
+  font-size: var(--mantine-font-size-sm);
+  text-decoration: none;
+  transition: background 100ms ease;
+}
+
+.row:hover {
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+}
+
+.rowIcon {
+  color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+  flex: none;
+  display: inline-flex;
+}
+
+.rowEmoji {
+  font-size: 14px;
+  line-height: 1;
+  flex: none;
+  display: inline-flex;
+  width: 18px;
+  justify-content: center;
+}
+
+.rowTitle {
+  font-weight: 500;
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.badge {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  padding: 2px 7px;
+  border-radius: 999px;
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  color: light-dark(
+    var(--mantine-color-gray-7),
+    var(--mantine-color-dark-1)
+  );
+  text-transform: uppercase;
+  flex: none;
+}
+
+.badgeAccent {
+  background: light-dark(
+    var(--mantine-color-blue-0),
+    var(--mantine-color-blue-9)
+  );
+  color: light-dark(
+    var(--mantine-color-blue-7),
+    var(--mantine-color-blue-2)
+  );
+}
+
+.empty {
+  padding: 18px 14px;
+  text-align: center;
+  color: light-dark(
+    var(--mantine-color-gray-6),
+    var(--mantine-color-dark-2)
+  );
+  font-size: var(--mantine-font-size-xs);
+}
+
+.loading {
+  display: flex;
+  justify-content: center;
+  padding: 18px;
+}
@@ -0,0 +1,184 @@
+import { useState } from "react";
+import { Loader, Popover } from "@mantine/core";
+import {
+  IconChevronDown,
+  IconCornerDownLeft,
+  IconFile,
+  IconInfoCircle,
+} from "@tabler/icons-react";
+import { Link } from "react-router-dom";
+import { Trans, useTranslation } from "react-i18next";
+import { useReferencesQuery } from "@/features/transclusion/queries/transclusion-query";
+import type { ReferencingPage } from "@/features/transclusion/types/transclusion.types";
+import { buildPageUrl } from "@/features/page/page.utils";
+import classes from "./sync-block-references-dropdown.module.css";
+
+type Props = {
+  sourcePageId: string | null;
+  transclusionId: string | null;
+  /** The page currently being viewed - used to mark the "THIS PAGE" badge. */
+  currentPageId: string;
+  /**
+   * Source: trigger reads "Editing original".
+   * Reference: trigger reads "Synced to N other pages".
+   */
+  mode: "source" | "reference";
+  /** Notified whenever the dropdown opens/closes (for keep-chrome-visible). */
+  onOpenChange?: (open: boolean) => void;
+};
+
+export default function SyncBlockReferencesDropdown({
+  sourcePageId,
+  transclusionId,
+  currentPageId,
+  mode,
+  onOpenChange,
+}: Props) {
+  const { t } = useTranslation();
+  const [opened, setOpened] = useState(false);
+
+  const handleOpenChange = (next: boolean) => {
+    setOpened(next);
+    onOpenChange?.(next);
+  };
+
+  // Fetch eagerly so the "Synced to N other pages" count is correct even
+  // before the dropdown is opened. The cache is keyed on (sourcePageId,
+  // transclusionId), so two views (source + reference) share one fetch.
+  const enabled = !!sourcePageId && !!transclusionId;
+  const { data, isLoading } = useReferencesQuery(
+    sourcePageId,
+    transclusionId,
+    enabled,
+  );
+
+  const allPages: Array<{ page: ReferencingPage; isOriginal: boolean }> = [];
+  if (data?.source) {
+    allPages.push({ page: data.source, isOriginal: true });
+  }
+  for (const ref of data?.references ?? []) {
+    allPages.push({ page: ref, isOriginal: false });
+  }
+
+  const otherCount = allPages.filter((p) => p.page.id !== currentPageId).length;
+  const label =
+    mode === "source"
+      ? t("Editing original")
+      : t("Synced to {{count}} other page", {
+          count: otherCount,
+          defaultValue_one: "Synced to {{count}} other page",
+          defaultValue_other: "Synced to {{count}} other pages",
+        });
+
+  return (
+    <Popover
+      position="bottom-start"
+      shadow="lg"
+      opened={opened}
+      onChange={handleOpenChange}
+      width={340}
+      withinPortal
+    >
+      <Popover.Target>
+        <button
+          type="button"
+          className={classes.trigger}
+          onClick={() => handleOpenChange(!opened)}
+          aria-expanded={opened}
+          aria-haspopup="dialog"
+        >
+          <span className={classes.triggerIcon}>
+            <IconCornerDownLeft size={14} stroke={1.8} />
+          </span>
+          <span>{label}</span>
+          <span className={classes.triggerChev}>
+            <IconChevronDown size={12} stroke={2} />
+          </span>
+        </button>
+      </Popover.Target>
+
+      <Popover.Dropdown className={classes.dropdown}>
+        {mode === "reference" && data?.source && (
+          <div className={classes.banner}>
+            <span className={classes.bannerIcon}>
+              <IconInfoCircle size={16} stroke={1.6} />
+            </span>
+            <div>
+              <Trans
+                i18nKey="sourceReadOnlyHint"
+                defaults="This section is read-only here. Edit it on the <link>original source page</link>."
+                components={{
+                  link: (
+                    <Link
+                      to={
+                        data.source.spaceSlug
+                          ? buildPageUrl(
+                              data.source.spaceSlug,
+                              data.source.slugId,
+                              data.source.title,
+                            )
+                          : `/p/${data.source.id}`
+                      }
+                      className={classes.bannerLink}
+                      onClick={() => handleOpenChange(false)}
+                    />
+                  ),
+                }}
+              />
+            </div>
+          </div>
+        )}
+
+        {isLoading ? (
+          <div className={classes.loading}>
+            <Loader size="xs" />
+          </div>
+        ) : allPages.length === 0 ? (
+          <div className={classes.empty}>{t("No pages")}</div>
+        ) : (
+          <div className={classes.section}>
+            <div className={classes.sectionLabel}>{t("Synced to")}</div>
+            <ul className={classes.list}>
+              {allPages.map(({ page, isOriginal }) => {
+                const isCurrent = page.id === currentPageId;
+                const href = page.spaceSlug
+                  ? buildPageUrl(page.spaceSlug, page.slugId, page.title)
+                  : `/p/${page.id}`;
+                const title = page.title?.length ? page.title : t("Untitled");
+                return (
+                  <li key={page.id}>
+                    <Link
+                      to={href}
+                      className={classes.row}
+                      onClick={() => handleOpenChange(false)}
+                    >
+                      {page.icon ? (
+                        <span className={classes.rowEmoji}>{page.icon}</span>
+                      ) : (
+                        <span className={classes.rowIcon}>
+                          <IconFile size={16} stroke={1.6} />
+                        </span>
+                      )}
+                      <span className={classes.rowTitle} title={title}>
+                        {title}
+                      </span>
+                      {isCurrent ? (
+                        <span
+                          className={`${classes.badge} ${classes.badgeAccent}`}
+                        >
+                          {t("THIS PAGE")}
+                        </span>
+                      ) : isOriginal ? (
+                        <span className={classes.badge}>{t("ORIGINAL")}</span>
+                      ) : null}
+                    </Link>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        )}
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
@@ -0,0 +1,32 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  listReferences,
+  unsyncReference,
+} from "../services/transclusion-api";
+
+export function useReferencesQuery(
+  sourcePageId: string | null,
+  transclusionId: string | null,
+  enabled: boolean,
+) {
+  return useQuery({
+    queryKey: ["transclusion-references", sourcePageId, transclusionId],
+    queryFn: () =>
+      listReferences({
+        sourcePageId: sourcePageId!,
+        transclusionId: transclusionId!,
+      }),
+    enabled: enabled && !!sourcePageId && !!transclusionId,
+    staleTime: 10 * 1000,
+  });
+}
+
+export function useUnsyncReferenceMutation() {
+  return useMutation({
+    mutationFn: (params: {
+      referencePageId: string;
+      sourcePageId: string;
+      transclusionId: string;
+    }) => unsyncReference(params),
+  });
+}
@@ -0,0 +1,29 @@
+import api from "@/lib/api-client";
+import type {
+  ReferencingPagesResponse,
+  TransclusionLookup,
+} from "../types/transclusion.types";
+
+export async function lookupTransclusion(params: {
+  references: Array<{ sourcePageId: string; transclusionId: string }>;
+}): Promise<{ items: TransclusionLookup[] }> {
+  const r = await api.post("/pages/transclusion/lookup", params);
+  return r.data;
+}
+
+export async function listReferences(params: {
+  sourcePageId: string;
+  transclusionId: string;
+}): Promise<ReferencingPagesResponse> {
+  const r = await api.post("/pages/transclusion/references", params);
+  return r.data;
+}
+
+export async function unsyncReference(params: {
+  referencePageId: string;
+  sourcePageId: string;
+  transclusionId: string;
+}): Promise<{ content: unknown }> {
+  const r = await api.post("/pages/transclusion/unsync-reference", params);
+  return r.data;
+}
@@ -0,0 +1,23 @@
+export type TransclusionLookup =
+  | {
+      sourcePageId: string;
+      transclusionId: string;
+      content: unknown;
+      sourceUpdatedAt: string;
+    }
+  | { sourcePageId: string; transclusionId: string; status: "not_found" }
+  | { sourcePageId: string; transclusionId: string; status: "no_access" };
+
+export type ReferencingPage = {
+  id: string;
+  slugId: string;
+  title: string | null;
+  icon: string | null;
+  spaceId: string;
+  spaceSlug: string | null;
+};
+
+export type ReferencingPagesResponse = {
+  source: ReferencingPage | null;
+  references: ReferencingPage[];
+};
@@ -28,6 +28,7 @@ export interface IWorkspace {
  trashRetentionDays?: number;
  restrictApiToAdmins?: boolean;
  allowMemberTemplates?: boolean;
+  isScimEnabled?: boolean;
 }

 export interface IWorkspaceSettings {
@@ -100,6 +100,15 @@ export const normalizeUrl = (url: string): string => {
  return `https://${url}`;
 };

+const _isApple = /mac|iphone|ipad|ipod/i.test(navigator.platform ?? "");
+
+/// Cmd key on Apple devices, Ctrl key everywhere else
+export function platformModifierKey(event: KeyboardEvent): boolean {
+  return _isApple ? event.metaKey : event.ctrlKey;
+}
+
+export const platformModifierLabel = _isApple ? "⌘" : "Ctrl";
+
 export function castToBoolean(value: unknown): boolean {
  if (value == null) {
    return false;
@@ -1,6 +1,6 @@
 {
  "name": "server",
-  "version": "0.71.1",
+  "version": "0.80.1",
  "description": "",
  "author": "",
  "private": true,
@@ -33,13 +33,14 @@
    "@ai-sdk/google": "^3.0.52",
    "@ai-sdk/openai": "^3.0.47",
    "@ai-sdk/openai-compatible": "^2.0.37",
-    "@aws-sdk/client-s3": "3.1014.0",
-    "@aws-sdk/lib-storage": "3.1014.0",
-    "@aws-sdk/s3-request-presigner": "3.1014.0",
+    "@aws-sdk/client-s3": "3.1040.0",
+    "@aws-sdk/lib-storage": "3.1040.0",
+    "@aws-sdk/s3-request-presigner": "3.1040.0",
    "@clickhouse/client": "^1.18.2",
+    "@docmost/pdf-inspector": "1.9.4",
    "@fastify/cookie": "^11.0.2",
-    "@fastify/multipart": "^9.4.0",
-    "@fastify/static": "^9.0.0",
+    "@fastify/multipart": "^10.0.0",
+    "@fastify/static": "^9.1.3",
    "@keyv/redis": "^5.1.6",
    "@langchain/core": "1.1.39",
    "@langchain/textsplitters": "1.0.1",
@@ -48,19 +49,19 @@
    "@nestjs-labs/nestjs-ioredis": "^11.0.4",
    "@nestjs/bullmq": "^11.0.4",
    "@nestjs/cache-manager": "^3.1.0",
-    "@nestjs/common": "^11.1.18",
-    "@nestjs/config": "^4.0.3",
-    "@nestjs/core": "^11.1.18",
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.1.19",
    "@nestjs/event-emitter": "^3.0.1",
    "@nestjs/jwt": "11.0.2",
    "@nestjs/mapped-types": "^2.1.1",
    "@nestjs/passport": "^11.0.5",
-    "@nestjs/platform-fastify": "^11.1.18",
-    "@nestjs/platform-socket.io": "^11.1.18",
-    "@nestjs/schedule": "^6.1.1",
+    "@nestjs/platform-fastify": "^11.1.19",
+    "@nestjs/platform-socket.io": "^11.1.19",
+    "@nestjs/schedule": "^6.1.3",
    "@nestjs/terminus": "^11.1.1",
    "@nestjs/throttler": "^6.5.0",
-    "@nestjs/websockets": "^11.1.18",
+    "@nestjs/websockets": "^11.1.19",
    "@node-saml/passport-saml": "^5.1.0",
    "@react-email/components": "1.0.10",
    "@react-email/render": "2.0.4",
@@ -69,7 +70,7 @@
    "ai-sdk-ollama": "^3.8.1",
    "bcrypt": "^6.0.0",
    "bowser": "^2.14.1",
-    "bullmq": "^5.71.0",
+    "bullmq": "^5.76.0",
    "cache-manager": "^7.2.8",
    "cheerio": "^1.2.0",
    "class-transformer": "^0.5.1",
@@ -100,7 +101,6 @@
    "p-limit": "^7.3.0",
    "passport-google-oauth20": "^2.0.0",
    "passport-jwt": "^4.0.1",
-    "pdfjs-dist": "^5.5.207",
    "pg-tsquery": "^8.4.2",
    "pgvector": "^0.2.1",
    "pino-http": "^11.0.0",
@@ -110,22 +110,24 @@
    "react": "^18.3.1",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.2",
-    "sanitize-filename-ts": "1.0.2",
+    "sanitize-filename": "1.6.3",
+    "scimmy": "1.3.5",
    "socket.io": "^4.8.3",
    "stripe": "^17.7.0",
    "tlds": "^1.261.0",
    "tmp-promise": "^3.0.3",
    "tseep": "^1.3.1",
    "typesense": "^3.0.5",
+    "undici": "7.24.0",
    "ws": "^8.20.0",
    "yauzl": "^3.2.1",
    "zod": "^4.3.6"
  },
  "devDependencies": {
    "@eslint/js": "^9.28.0",
-    "@nestjs/cli": "^11.0.18",
+    "@nestjs/cli": "^11.0.21",
    "@nestjs/schematics": "^11.0.10",
-    "@nestjs/testing": "^11.1.18",
+    "@nestjs/testing": "^11.1.19",
    "@types/bcrypt": "^6.0.0",
    "@types/debounce": "^1.2.4",
    "@types/fs-extra": "^11.0.4",
@@ -165,6 +167,9 @@
    "transform": {
      "^.+\\.(t|j)s$": "ts-jest"
    },
+    "transformIgnorePatterns": [
+      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked)(@|/))"
+    ],
    "collectCoverageFrom": [
      "**/*.(t|j)s"
    ],
@@ -18,6 +18,7 @@ import { LoggerExtension } from './extensions/logger.extension';
 import { CollaborationHandler } from './collaboration.handler';
 import { CollabHistoryService } from './services/collab-history.service';
 import { WatcherModule } from '../core/watcher/watcher.module';
+import { TransclusionService } from '../core/page/transclusion/transclusion.service';

@Module({
  providers: [
@@ -28,6 +29,7 @@ import { WatcherModule } from '../core/watcher/watcher.module';
    HistoryProcessor,
    CollabHistoryService,
    CollaborationHandler,
+    TransclusionService,
  ],
  exports: [CollaborationGateway],
  imports: [TokenModule, WatcherModule],
@@ -40,6 +40,8 @@ import {
  Status,
  addUniqueIdsToDoc,
  htmlToMarkdown,
+  Transclusion,
+  TransclusionReference,
 } from '@docmost/editor-ext';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
@@ -101,6 +103,8 @@ export const tiptapExtensions = [
  Columns,
  Column,
  Status,
+  Transclusion,
+  TransclusionReference,
 ] as any;

 export function jsonToHtml(tiptapJson: any) {
@@ -32,6 +32,7 @@ import {
  HISTORY_FAST_THRESHOLD,
  HISTORY_INTERVAL,
 } from '../constants';
+import { TransclusionService } from '../../core/page/transclusion/transclusion.service';

@Injectable()
 export class PersistenceExtension implements Extension {
@@ -45,6 +46,7 @@ export class PersistenceExtension implements Extension {
    @InjectQueue(QueueName.HISTORY_QUEUE) private historyQueue: Queue,
    @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
    private readonly collabHistory: CollabHistoryService,
+    private readonly transclusionService: TransclusionService,
  ) {}

  async onLoadDocument(data: onLoadDocumentPayload) {
@@ -134,7 +136,11 @@ export class PersistenceExtension implements Extension {
        try {
          const existingContributors = page.contributorIds || [];
          contributorIds = Array.from(
-            new Set([...existingContributors, ...editingUserIds, page.creatorId]),
+            new Set([
+              ...existingContributors,
+              ...editingUserIds,
+              page.creatorId,
+            ]),
          );
        } catch (err) {
          //this.logger.debug('Contributors error:' + err?.['message']);
@@ -158,6 +164,10 @@ export class PersistenceExtension implements Extension {
      this.logger.error(`Failed to update page ${pageId}`, err);
    }

+    if (page) {
+      await this.syncTransclusion(pageId, tiptapJson);
+    }
+
    if (page) {
      await this.collabHistory.addContributors(pageId, editingUserIds);

@@ -165,7 +175,9 @@ export class PersistenceExtension implements Extension {

      const userMentions = extractUserMentions(mentions);
      const oldMentions = page.content ? extractMentions(page.content) : [];
-      const oldMentionedUserIds = extractUserMentions(oldMentions).map((m) => m.entityId);
+      const oldMentionedUserIds = extractUserMentions(oldMentions).map(
+        (m) => m.entityId,
+      );

      if (userMentions.length > 0) {
        await this.notificationQueue.add(QueueJob.PAGE_MENTION_NOTIFICATION, {
@@ -229,4 +241,29 @@ export class PersistenceExtension implements Extension {
      { jobId: page.id, delay },
    );
  }
+
+  /**
+   * Refresh `page_transclusions` and `page_transclusion_references` to match
+   * the page's current content. Runs outside the page-write transaction and
+   * isolates each call so a failure here cannot affect the page save itself.
+   * The diff is idempotent — the next save converges if a round drops anything.
+   */
+  private async syncTransclusion(
+    pageId: string,
+    tiptapJson: unknown,
+  ): Promise<void> {
+    try {
+      await this.transclusionService.syncPageTransclusions(pageId, tiptapJson);
+    } catch (err) {
+      this.logger.error(`Failed to sync transclusions for page ${pageId}`, err);
+    }
+    try {
+      await this.transclusionService.syncPageReferences(pageId, tiptapJson);
+    } catch (err) {
+      this.logger.error(
+        `Failed to sync transclusion references for page ${pageId}`,
+        err,
+      );
+    }
+  }
 }
@@ -23,6 +23,11 @@ export const AuditEvent = {
  API_KEY_UPDATED: 'api_key.updated',
  API_KEY_DELETED: 'api_key.deleted',

+  // SCIM Tokens
+  SCIM_TOKEN_CREATED: 'scim_token.created',
+  SCIM_TOKEN_UPDATED: 'scim_token.updated',
+  SCIM_TOKEN_DELETED: 'scim_token.deleted',
+
  // Space
  SPACE_CREATED: 'space.created',
  SPACE_UPDATED: 'space.updated',
@@ -119,6 +124,7 @@ export const AuditResource = {
  COMMENT: 'comment',
  SHARE: 'share',
  API_KEY: 'api_key',
+  SCIM_TOKEN: 'scim_token',
  SSO_PROVIDER: 'sso_provider',
  WORKSPACE_INVITATION: 'workspace_invitation',
  ATTACHMENT: 'attachment',
@@ -8,6 +8,7 @@ export const Feature = {
  AI: 'ai',
  CONFLUENCE_IMPORT: 'import:confluence',
  DOCX_IMPORT: 'import:docx',
+  PDF_IMPORT: 'import:pdf',
  ATTACHMENT_INDEXING: 'attachment:indexing',
  SECURITY_SETTINGS: 'security:settings',
  MCP: 'mcp',
@@ -1,6 +1,6 @@
 import * as path from 'path';
 import * as bcrypt from 'bcrypt';
-import { sanitize } from 'sanitize-filename-ts';
+import sanitize = require('sanitize-filename');
 import { FastifyRequest } from 'fastify';
 import { Readable, Transform } from 'stream';

@@ -72,11 +72,33 @@ export function extractDateFromUuid7(uuid7: string) {
  return new Date(timestamp);
 }

-export function sanitizeFileName(fileName: string): string {
-  const sanitizedFilename = sanitize(fileName)
-    .replace(/ /g, '_')
-    .replace(/#/g, '_');
-  return sanitizedFilename.slice(0, 255);
+export type SanitizeFileNameOptions = {
+  /** Keep spaces and `#` instead of replacing them with `_`. Useful for
+   * download filenames where readability matters. Defaults to false. */
+  preserveSpaces?: boolean;
+};
+
+export function sanitizeFileName(
+  fileName: string,
+  options: SanitizeFileNameOptions = {},
+): string {
+  // Decode percent-encoded sequences so that bypasses like "..%2F" reach
+  // sanitize() as literal "../" and get stripped. sanitize-filename only
+  // strips literal characters and won't catch encoded path separators
+  // on its own.
+  const decoded = fileName.replace(/%[0-9a-fA-F]{2}/g, (m) => {
+    try {
+      return decodeURIComponent(m);
+    } catch {
+      return m;
+    }
+  });
+
+  const sanitized = sanitize(decoded);
+  if (options.preserveSpaces) {
+    return sanitized;
+  }
+  return sanitized.replace(/ /g, '_').replace(/#/g, '_');
 }

 export function removeAccent(str: string): string {
@@ -88,7 +110,7 @@ export function extractBearerTokenFromHeader(
  request: FastifyRequest,
 ): string | undefined {
  const [type, token] = request.headers.authorization?.split(' ') ?? [];
-  return type === 'Bearer' ? token : undefined;
+  return type?.toLowerCase() === 'bearer' ? token : undefined;
 }

 /**
@@ -356,9 +356,19 @@ export class AttachmentController {
      throw new BadRequestException('Invalid image attachment type');
    }

-    const filenameWithoutExt = path.basename(fileName, path.extname(fileName));
-    if (!isValidUUID(filenameWithoutExt)) {
-      throw new BadRequestException('Invalid file id');
+    if (!fileName) {
+      throw new BadRequestException('Invalid file name');
+    }
+
+    const ext = path.extname(fileName);
+    const filenameWithoutExt = path.basename(fileName, ext);
+
+    if (
+      !ext ||
+      !isValidUUID(filenameWithoutExt) ||
+      `${filenameWithoutExt}${ext}` !== fileName
+    ) {
+      throw new BadRequestException('Invalid file name');
    }

    const filePath = `${getAttachmentFolderPath(attachmentType, workspace.id)}/${fileName}`;
@@ -7,7 +7,7 @@ import {
 } from '@nestjs/common';
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { GroupService } from './group.service';
-import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
 import { InjectKysely } from 'nestjs-kysely';
 import { GroupUserRepo } from '@docmost/db/repos/group/group-user.repo';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
@@ -20,6 +20,7 @@ import {
  AUDIT_SERVICE,
  IAuditService,
 } from '../../../integrations/audit/audit.service';
+import { dbOrTx } from '@docmost/db/utils';

@Injectable()
 export class GroupUserService {
@@ -54,17 +55,23 @@ export class GroupUserService {
    userIds: string[],
    groupId: string,
    workspaceId: string,
+    trx?: KyselyTransaction,
  ): Promise<void> {
-    await this.groupService.findAndValidateGroup(groupId, workspaceId);
+    const db = dbOrTx(this.db, trx);
+    await this.groupService.findAndValidateGroup(groupId, workspaceId, trx);
+
+    if (userIds.length === 0) return;

    // make sure we have valid workspace users
-    const validUsers = await this.db
+    const validUsers = await db
      .selectFrom('users')
      .select(['id', 'name'])
      .where('users.id', 'in', userIds)
      .where('users.workspaceId', '=', workspaceId)
      .execute();

+    if (validUsers.length === 0) return;
+
    // prepare users to add to group
    const groupUsersToInsert = [];
    for (const user of validUsers) {
@@ -75,7 +82,7 @@ export class GroupUserService {
    }

    // batch insert new group users
-    await this.db
+    await db
      .insertInto('groupUsers')
      .values(groupUsersToInsert)
      .onConflict((oc) => oc.columns(['userId', 'groupId']).doNothing())
@@ -216,8 +216,11 @@ export class GroupService {
  async findAndValidateGroup(
    groupId: string,
    workspaceId: string,
+    trx?: KyselyTransaction,
  ): Promise<Group> {
-    const group = await this.groupRepo.findById(groupId, workspaceId);
+    const group = await this.groupRepo.findById(groupId, workspaceId, {
+      trx,
+    });
    if (!group) {
      throw new NotFoundException('Group not found');
    }
@@ -6,11 +6,12 @@ import { TrashCleanupService } from './services/trash-cleanup.service';
 import { StorageModule } from '../../integrations/storage/storage.module';
 import { CollaborationModule } from '../../collaboration/collaboration.module';
 import { WatcherModule } from '../watcher/watcher.module';
+import { TransclusionModule } from './transclusion/transclusion.module';

@Module({
  controllers: [PageController],
  providers: [PageService, PageHistoryService, TrashCleanupService],
  exports: [PageService, PageHistoryService],
-  imports: [StorageModule, CollaborationModule, WatcherModule],
+  imports: [StorageModule, CollaborationModule, WatcherModule, TransclusionModule],
 })
 export class PageModule {}
@@ -54,6 +54,7 @@ import {
 import { markdownToHtml } from '@docmost/editor-ext';
 import { WatcherService } from '../../watcher/watcher.service';
 import { sql } from 'kysely';
+import { TransclusionService } from '../transclusion/transclusion.service';

@Injectable()
 export class PageService {
@@ -71,6 +72,7 @@ export class PageService {
    private eventEmitter: EventEmitter2,
    private collaborationGateway: CollaborationGateway,
    private readonly watcherService: WatcherService,
+    private readonly transclusionService: TransclusionService,
  ) {}

  async findById(
@@ -600,6 +602,17 @@ export class PageService {
            }
          }

+          // Remap transclusion-reference source pages to their copies when
+          // the source page is also being duplicated in the same operation.
+          if (node.type.name === 'transclusionReference') {
+            const sourcePageId = node.attrs.sourcePageId;
+            if (sourcePageId && pageMap.has(sourcePageId)) {
+              const mappedPage = pageMap.get(sourcePageId);
+              //@ts-ignore
+              node.attrs.sourcePageId = mappedPage.newPageId;
+            }
+          }
+
          // Update internal page links in link marks
          for (const mark of node.marks) {
            if (
@@ -659,6 +672,31 @@ export class PageService {

    await this.db.insertInto('pages').values(insertablePages).execute();

+    // Extract transclusions from every duplicated page and persist them in
+    // one statement. Duplication bypasses Yjs onStoreDocument; brand-new
+    // pages never have prior rows so we can skip the diff and just bulk-insert.
+    try {
+      await this.transclusionService.insertTransclusionsForPages(
+        insertablePages.map((p) => ({ id: p.id, content: p.content })),
+      );
+    } catch (err) {
+      this.logger.error(
+        'Failed to insert transclusions for duplicated pages',
+        err,
+      );
+    }
+
+    try {
+      await this.transclusionService.insertReferencesForPages(
+        insertablePages.map((p) => ({ id: p.id, content: p.content })),
+      );
+    } catch (err) {
+      this.logger.error(
+        'Failed to insert transclusion references for duplicated pages',
+        err,
+      );
+    }
+
    const insertedPageIds = insertablePages.map((page) => page.id);
    this.eventEmitter.emit(EventName.PAGE_CREATED, {
      pageIds: insertedPageIds,
@@ -0,0 +1,24 @@
+import { Type } from 'class-transformer';
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsString,
+  IsUUID,
+  ValidateNested,
+} from 'class-validator';
+
+export class LookupReferenceDto {
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  transclusionId!: string;
+}
+
+export class LookupDto {
+  @IsArray()
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => LookupReferenceDto)
+  references!: LookupReferenceDto[];
+}
@@ -0,0 +1,9 @@
+import { IsString, IsUUID } from 'class-validator';
+
+export class ReferencesDto {
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  transclusionId!: string;
+}
@@ -0,0 +1,12 @@
+import { IsString, IsUUID } from 'class-validator';
+
+export class UnsyncReferenceDto {
+  @IsUUID()
+  referencePageId!: string;
+
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  transclusionId!: string;
+}
@@ -0,0 +1,232 @@
+import {
+  collectReferencesFromPmJson,
+  collectTransclusionsFromPmJson,
+} from '../utils/transclusion-prosemirror.util';
+
+describe('collectTransclusionsFromPmJson', () => {
+  it('returns [] for null/undefined doc', () => {
+    expect(collectTransclusionsFromPmJson(null)).toEqual([]);
+    expect(collectTransclusionsFromPmJson(undefined)).toEqual([]);
+  });
+
+  it('returns [] for a doc with no transclusion nodes', () => {
+    const doc = {
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hi' }] }],
+    };
+    expect(collectTransclusionsFromPmJson(doc)).toEqual([]);
+  });
+
+  it('extracts a top-level transclusion with id, name and content', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'abc123', name: 'Pricing' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Body' }] }],
+        },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got).toHaveLength(1);
+    expect(got[0].transclusionId).toBe('abc123');
+    expect(got[0].name).toBe('Pricing');
+    expect(got[0].content).toEqual({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Body' }] }],
+    });
+  });
+
+  it('skips transclusion nodes with no id (transient before UniqueID assigns one)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusion', attrs: {}, content: [{ type: 'paragraph' }] },
+      ],
+    };
+    expect(collectTransclusionsFromPmJson(doc)).toEqual([]);
+  });
+
+  it('returns multiple top-level transclusions', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusion', attrs: { id: 'a' }, content: [{ type: 'paragraph' }] },
+        { type: 'transclusion', attrs: { id: 'b', name: 'Two' }, content: [{ type: 'paragraph' }] },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got.map((e) => e.transclusionId)).toEqual(['a', 'b']);
+  });
+
+  it('does not recurse into a nested transclusion (transclusion cannot contain transclusion per schema, but be defensive)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'outer' },
+          content: [
+            {
+              type: 'transclusion',
+              attrs: { id: 'inner' },
+              content: [{ type: 'paragraph' }],
+            },
+          ],
+        },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got.map((e) => e.transclusionId)).toEqual(['outer']);
+  });
+
+  it('finds transclusions nested inside other block containers (e.g. column)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'column',
+          content: [
+            { type: 'transclusion', attrs: { id: 'inCol' }, content: [{ type: 'paragraph' }] },
+          ],
+        },
+      ],
+    };
+    expect(collectTransclusionsFromPmJson(doc).map((e) => e.transclusionId)).toEqual([
+      'inCol',
+    ]);
+  });
+
+  it('uses the last id when duplicate ids appear (later wins, deterministic)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusion', attrs: { id: 'dup', name: 'first' }, content: [{ type: 'paragraph' }] },
+        { type: 'transclusion', attrs: { id: 'dup', name: 'second' }, content: [{ type: 'paragraph' }] },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got).toHaveLength(1);
+    expect(got[0].name).toBe('second');
+  });
+});
+
+describe('collectReferencesFromPmJson', () => {
+  it('returns [] for null/undefined doc', () => {
+    expect(collectReferencesFromPmJson(null)).toEqual([]);
+    expect(collectReferencesFromPmJson(undefined)).toEqual([]);
+  });
+
+  it('returns [] for a doc with no transclusionReference nodes', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'hi' }] },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([]);
+  });
+
+  it('extracts a top-level reference', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { containingTransclusionId: null, sourcePageId: 'p1', transclusionId: 'e1' },
+    ]);
+  });
+
+  it('skips references missing sourcePageId or transclusionId', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusionReference', attrs: { transclusionId: 'e1' } },
+        { type: 'transclusionReference', attrs: { sourcePageId: 'p1' } },
+        { type: 'transclusionReference', attrs: {} },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([]);
+  });
+
+  it('finds references nested in other block containers (column, callout, etc.)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'column',
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+            },
+          ],
+        },
+        {
+          type: 'callout',
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+            },
+          ],
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { containingTransclusionId: null, sourcePageId: 'p1', transclusionId: 'e1' },
+      { containingTransclusionId: null, sourcePageId: 'p2', transclusionId: 'e2' },
+    ]);
+  });
+
+  it('also finds references nested inside a transclusion (source) node', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'src1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+            },
+          ],
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { containingTransclusionId: 'src1', sourcePageId: 'p1', transclusionId: 'e1' },
+    ]);
+  });
+
+  it('dedupes identical (containingTransclusionId, sourcePageId, transclusionId) triples', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { containingTransclusionId: null, sourcePageId: 'p1', transclusionId: 'e1' },
+      { containingTransclusionId: null, sourcePageId: 'p2', transclusionId: 'e2' },
+    ]);
+  });
+});
@@ -0,0 +1,161 @@
+import {
+  rewriteAttachmentsForUnsync,
+  type AttachmentRewritePlan,
+} from '../utils/transclusion-unsync.util';
+
+describe('rewriteAttachmentsForUnsync', () => {
+  const fixedIds = (() => {
+    let i = 0;
+    return () => `new-${++i}`;
+  });
+
+  it('returns content unchanged when no attachment nodes are present', () => {
+    const content = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'hello' }] },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.content).toEqual(content);
+    expect(r.copies).toEqual([]);
+  });
+
+  it('rewrites attachmentId and src on a single image node', () => {
+    const oldId = '11111111-1111-1111-1111-111111111111';
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'image',
+          attrs: {
+            attachmentId: oldId,
+            src: `/api/files/${oldId}/cat.png`,
+          },
+        },
+      ],
+    };
+    const gen = fixedIds();
+    const r = rewriteAttachmentsForUnsync(content, gen);
+
+    expect(r.copies).toHaveLength(1);
+    const plan: AttachmentRewritePlan = r.copies[0];
+    expect(plan.oldAttachmentId).toBe(oldId);
+    expect(plan.newAttachmentId).toBe('new-1');
+
+    const img = (r.content as any).content[0];
+    expect(img.attrs.attachmentId).toBe('new-1');
+    expect(img.attrs.src).toBe('/api/files/new-1/cat.png');
+  });
+
+  it('rewrites every attachment node type (image, video, audio, attachment, drawio, excalidraw, pdf)', () => {
+    const types = [
+      'image',
+      'video',
+      'audio',
+      'attachment',
+      'drawio',
+      'excalidraw',
+      'pdf',
+    ] as const;
+    const content = {
+      type: 'doc',
+      content: types.map((t, i) => ({
+        type: t,
+        attrs: {
+          attachmentId: `old-${i}`,
+          src: `/api/files/old-${i}/file`,
+        },
+      })),
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toHaveLength(types.length);
+    expect((r.content as any).content.map((n: any) => n.attrs.attachmentId)).toEqual(
+      Array.from({ length: types.length }, (_, i) => `new-${i + 1}`),
+    );
+  });
+
+  it('reuses one new id per old attachmentId across nodes (dedupe)', () => {
+    const shared = 'shared-old';
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'image',
+          attrs: {
+            attachmentId: shared,
+            src: `/api/files/${shared}/a.png`,
+          },
+        },
+        {
+          type: 'image',
+          attrs: {
+            attachmentId: shared,
+            src: `/api/files/${shared}/a.png`,
+          },
+        },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toHaveLength(1);
+    expect(r.copies[0].oldAttachmentId).toBe(shared);
+    const newId = r.copies[0].newAttachmentId;
+    expect((r.content as any).content[0].attrs.attachmentId).toBe(newId);
+    expect((r.content as any).content[1].attrs.attachmentId).toBe(newId);
+  });
+
+  it('does not mutate the input content object', () => {
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'image',
+          attrs: { attachmentId: 'old-x', src: '/api/files/old-x/x.png' },
+        },
+      ],
+    };
+    const snapshot = JSON.parse(JSON.stringify(content));
+    rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(content).toEqual(snapshot);
+  });
+
+  it('skips nodes whose attachmentId is missing or not a uuid-shaped string', () => {
+    const content = {
+      type: 'doc',
+      content: [
+        { type: 'image', attrs: {} },
+        { type: 'image', attrs: { attachmentId: '' } },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toEqual([]);
+    expect(r.content).toEqual(content);
+  });
+
+  it('recurses into nested containers (column, callout)', () => {
+    const oldId = 'old-nested';
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          content: [
+            {
+              type: 'image',
+              attrs: {
+                attachmentId: oldId,
+                src: `/api/files/${oldId}/x.png`,
+              },
+            },
+          ],
+        },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toHaveLength(1);
+    const newId = r.copies[0].newAttachmentId;
+    const inner = (r.content as any).content[0].content[0];
+    expect(inner.attrs.attachmentId).toBe(newId);
+    expect(inner.attrs.src).toBe(`/api/files/${newId}/x.png`);
+  });
+});
@@ -0,0 +1,78 @@
+import { Test } from '@nestjs/testing';
+import { TransclusionController } from '../transclusion.controller';
+import { TransclusionService } from '../transclusion.service';
+import { JwtAuthGuard } from '../../../../common/guards/jwt-auth.guard';
+
+describe('TransclusionController.lookup', () => {
+  let controller: TransclusionController;
+  let service: jest.Mocked<TransclusionService>;
+
+  beforeEach(async () => {
+    service = {
+      lookup: jest.fn(),
+      listReferences: jest.fn(),
+      unsyncReference: jest.fn(),
+    } as any;
+
+    const module = await Test.createTestingModule({
+      controllers: [TransclusionController],
+      providers: [{ provide: TransclusionService, useValue: service }],
+    })
+      .overrideGuard(JwtAuthGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    controller = module.get(TransclusionController);
+  });
+
+  const user = { id: 'u1' } as any;
+  const ref = { sourcePageId: 'p1', transclusionId: 'e1' };
+
+  it('returns content when lookup succeeds', async () => {
+    service.lookup.mockResolvedValue({
+      items: [
+        {
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+          content: { type: 'doc' },
+          sourceUpdatedAt: new Date(),
+        },
+      ],
+    } as any);
+
+    const out = await controller.lookup({ references: [ref] } as any, user);
+    expect(out.items[0]).not.toHaveProperty('status');
+    expect((out.items[0] as any).content).toEqual({ type: 'doc' });
+    expect(service.lookup).toHaveBeenCalledWith([ref], 'u1');
+  });
+
+  it('returns no_access when service says no_access', async () => {
+    service.lookup.mockResolvedValue({
+      items: [
+        {
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+          status: 'no_access',
+        },
+      ],
+    } as any);
+
+    const out = await controller.lookup({ references: [ref] } as any, user);
+    expect((out.items[0] as { status?: string }).status).toBe('no_access');
+  });
+
+  it('returns not_found when service says not_found', async () => {
+    service.lookup.mockResolvedValue({
+      items: [
+        {
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+          status: 'not_found',
+        },
+      ],
+    } as any);
+
+    const out = await controller.lookup({ references: [ref] } as any, user);
+    expect((out.items[0] as { status?: string }).status).toBe('not_found');
+  });
+});
@@ -0,0 +1,412 @@
+import { Test } from '@nestjs/testing';
+import { TransclusionService } from '../transclusion.service';
+import { PageTransclusionsRepo } from '@docmost/db/repos/page-transclusions/page-transclusions.repo';
+import { PageTransclusionReferencesRepo } from '@docmost/db/repos/page-transclusion-references/page-transclusion-references.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
+import { StorageService } from '../../../../integrations/storage/storage.service';
+
+describe('TransclusionService.syncPageTransclusions', () => {
+  let service: TransclusionService;
+  let repo: jest.Mocked<PageTransclusionsRepo>;
+
+  beforeEach(async () => {
+    const mockRepo: jest.Mocked<Partial<PageTransclusionsRepo>> = {
+      findByPageId: jest.fn(),
+      insert: jest.fn(),
+      update: jest.fn(),
+      deleteByPageAndTransclusionIds: jest.fn(),
+    };
+    const module = await Test.createTestingModule({
+      providers: [
+        TransclusionService,
+        { provide: PageTransclusionsRepo, useValue: mockRepo },
+        { provide: PageTransclusionReferencesRepo, useValue: {} },
+        { provide: PageRepo, useValue: {} },
+        { provide: PagePermissionRepo, useValue: {} },
+        { provide: AttachmentRepo, useValue: {} },
+        { provide: StorageService, useValue: {} },
+      ],
+    }).compile();
+    service = module.get(TransclusionService);
+    repo = module.get(PageTransclusionsRepo);
+  });
+
+  const pageId = '00000000-0000-0000-0000-000000000001';
+
+  it('inserts new transclusions that did not exist before', async () => {
+    repo.findByPageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'a', name: 'Hello' },
+          content: [{ type: 'paragraph' }],
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, pm);
+
+    expect(result).toEqual({ inserted: 1, updated: 0, deleted: 0 });
+    expect(repo.insert).toHaveBeenCalledTimes(1);
+    expect(repo.insert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        pageId,
+        transclusionId: 'a',
+        name: 'Hello',
+      }),
+      undefined,
+    );
+    expect(repo.update).not.toHaveBeenCalled();
+    expect(repo.deleteByPageAndTransclusionIds).not.toHaveBeenCalled();
+  });
+
+  it('updates transclusions whose name or content changed', async () => {
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'row1',
+        pageId,
+        transclusionId: 'a',
+        name: 'Old',
+        content: { type: 'doc', content: [{ type: 'paragraph' }] },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'a', name: 'New' },
+          content: [
+            { type: 'paragraph', content: [{ type: 'text', text: 'X' }] },
+          ],
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, pm);
+
+    expect(result).toEqual({ inserted: 0, updated: 1, deleted: 0 });
+    expect(repo.update).toHaveBeenCalledWith(
+      pageId,
+      'a',
+      expect.objectContaining({ name: 'New' }),
+      undefined,
+    );
+  });
+
+  it('skips update when name and content are unchanged', async () => {
+    const sameContent = {
+      type: 'doc',
+      content: [{ type: 'paragraph' }],
+    };
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'row1',
+        pageId,
+        transclusionId: 'a',
+        name: 'Same',
+        content: sameContent,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'a', name: 'Same' },
+          content: sameContent.content,
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, pm);
+
+    expect(result).toEqual({ inserted: 0, updated: 0, deleted: 0 });
+    expect(repo.update).not.toHaveBeenCalled();
+  });
+
+  it('deletes transclusions that no longer appear in the doc', async () => {
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'r',
+        pageId,
+        transclusionId: 'gone',
+        name: null,
+        content: { type: 'doc', content: [] },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const pm = { type: 'doc', content: [{ type: 'paragraph' }] };
+
+    const result = await service.syncPageTransclusions(pageId, pm);
+
+    expect(result).toEqual({ inserted: 0, updated: 0, deleted: 1 });
+    expect(repo.deleteByPageAndTransclusionIds).toHaveBeenCalledWith(
+      pageId,
+      ['gone'],
+      undefined,
+    );
+  });
+
+  it('handles empty doc → noop', async () => {
+    repo.findByPageId.mockResolvedValue([]);
+    const result = await service.syncPageTransclusions(pageId, null);
+    expect(result).toEqual({ inserted: 0, updated: 0, deleted: 0 });
+    expect(repo.insert).not.toHaveBeenCalled();
+    expect(repo.update).not.toHaveBeenCalled();
+    expect(repo.deleteByPageAndTransclusionIds).not.toHaveBeenCalled();
+  });
+
+  it('passes through the trx parameter to repo calls', async () => {
+    repo.findByPageId.mockResolvedValue([]);
+    const trx = { mock: 'trx' } as any;
+    const pm = {
+      type: 'doc',
+      content: [
+        { type: 'transclusion', attrs: { id: 'a' }, content: [{ type: 'paragraph' }] },
+      ],
+    };
+
+    await service.syncPageTransclusions(pageId, pm, trx);
+
+    expect(repo.findByPageId).toHaveBeenCalledWith(pageId, trx);
+    expect(repo.insert).toHaveBeenCalledWith(expect.anything(), trx);
+  });
+});
+
+describe('TransclusionService.syncPageReferences', () => {
+  let service: TransclusionService;
+  let refRepo: jest.Mocked<PageTransclusionReferencesRepo>;
+
+  beforeEach(async () => {
+    const mockTransclusionsRepo: Partial<PageTransclusionsRepo> = {};
+    const mockRefRepo: jest.Mocked<Partial<PageTransclusionReferencesRepo>> = {
+      findByReferencePageId: jest.fn(),
+      insertMany: jest.fn(),
+      deleteByReferenceAndKeys: jest.fn(),
+      findCyclicEdgesForSource: jest.fn().mockResolvedValue([]),
+      deleteByIds: jest.fn(),
+    };
+    const module = await Test.createTestingModule({
+      providers: [
+        TransclusionService,
+        { provide: PageTransclusionsRepo, useValue: mockTransclusionsRepo },
+        { provide: PageTransclusionReferencesRepo, useValue: mockRefRepo },
+        { provide: PageRepo, useValue: {} },
+        { provide: PagePermissionRepo, useValue: {} },
+        { provide: AttachmentRepo, useValue: {} },
+        { provide: StorageService, useValue: {} },
+      ],
+    }).compile();
+    service = module.get(TransclusionService);
+    refRepo = module.get(PageTransclusionReferencesRepo);
+  });
+
+  const referencePageId = '00000000-0000-0000-0000-000000000001';
+
+  it('inserts new loose references, no deletes when none existed', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 2, deleted: 0 });
+    expect(refRepo.insertMany).toHaveBeenCalledWith(
+      [
+        {
+          referencePageId,
+          containingTransclusionId: null,
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+        },
+        {
+          referencePageId,
+          containingTransclusionId: null,
+          sourcePageId: 'p2',
+          transclusionId: 'e2',
+        },
+      ],
+      undefined,
+    );
+    expect(refRepo.deleteByReferenceAndKeys).not.toHaveBeenCalled();
+    // Loose references never seed cycle detection.
+    expect(refRepo.findCyclicEdgesForSource).not.toHaveBeenCalled();
+  });
+
+  it('records the containing transclusion when references nest in a source', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 's1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 1, deleted: 0 });
+    expect(refRepo.insertMany).toHaveBeenCalledWith(
+      [
+        {
+          referencePageId,
+          containingTransclusionId: 's1',
+          sourcePageId: 'p2',
+          transclusionId: 'e2',
+        },
+      ],
+      undefined,
+    );
+    expect(refRepo.findCyclicEdgesForSource).toHaveBeenCalledWith(
+      'p2',
+      'e2',
+      undefined,
+    );
+  });
+
+  it('deletes edges that close a cycle and excludes them from the inserted count', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    refRepo.findCyclicEdgesForSource.mockResolvedValue([
+      {
+        id: 'closing-edge-id',
+        referencePageId,
+        containingTransclusionId: 's1',
+        sourcePageId: 'p2',
+        transclusionId: 'e2',
+        createdAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 's1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 0 });
+    expect(refRepo.deleteByIds).toHaveBeenCalledWith(
+      ['closing-edge-id'],
+      undefined,
+    );
+  });
+
+  it('deletes references that no longer appear', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([
+      {
+        id: 'r1',
+        referencePageId,
+        containingTransclusionId: null,
+        sourcePageId: 'p1',
+        transclusionId: 'e1',
+        createdAt: new Date(),
+      } as any,
+    ]);
+    const pm = { type: 'doc', content: [{ type: 'paragraph' }] };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 1 });
+    expect(refRepo.deleteByReferenceAndKeys).toHaveBeenCalledWith(
+      referencePageId,
+      [
+        {
+          containingTransclusionId: null,
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+        },
+      ],
+      undefined,
+    );
+    expect(refRepo.insertMany).not.toHaveBeenCalled();
+  });
+
+  it('is a no-op when desired matches existing exactly', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([
+      {
+        id: 'r',
+        referencePageId,
+        containingTransclusionId: null,
+        sourcePageId: 'p1',
+        transclusionId: 'e1',
+        createdAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 0 });
+    expect(refRepo.insertMany).not.toHaveBeenCalled();
+    expect(refRepo.deleteByReferenceAndKeys).not.toHaveBeenCalled();
+  });
+
+  it('passes through trx parameter to repo calls', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    const trx = { mock: 'trx' } as any;
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+      ],
+    };
+
+    await service.syncPageReferences(referencePageId, pm, trx);
+
+    expect(refRepo.findByReferencePageId).toHaveBeenCalledWith(
+      referencePageId,
+      trx,
+    );
+    expect(refRepo.insertMany).toHaveBeenCalledWith(expect.anything(), trx);
+  });
+});
@@ -0,0 +1,57 @@
+import {
+  Body,
+  Controller,
+  HttpCode,
+  HttpStatus,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { JwtAuthGuard } from '../../../common/guards/jwt-auth.guard';
+import { AuthUser } from '../../../common/decorators/auth-user.decorator';
+import { User } from '@docmost/db/types/entity.types';
+import { TransclusionService } from './transclusion.service';
+import { LookupDto } from './dto/lookup.dto';
+import { ReferencesDto } from './dto/references.dto';
+import { UnsyncReferenceDto } from './dto/unsync-reference.dto';
+
+@UseGuards(JwtAuthGuard)
+@Controller('pages/transclusion')
+export class TransclusionController {
+  constructor(private readonly transclusionService: TransclusionService) {}
+
+  @HttpCode(HttpStatus.OK)
+  @Post('lookup')
+  async lookup(@Body() dto: LookupDto, @AuthUser() user: User) {
+    return this.transclusionService.lookup(
+      dto.references,
+      user?.id ?? null,
+    );
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('references')
+  async references(
+    @Body() dto: ReferencesDto,
+    @AuthUser() user: User,
+  ) {
+    return this.transclusionService.listReferences({
+      sourcePageId: dto.sourcePageId,
+      transclusionId: dto.transclusionId,
+      viewerUserId: user.id,
+    });
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('unsync-reference')
+  async unsyncReference(
+    @Body() dto: UnsyncReferenceDto,
+    @AuthUser() user: User,
+  ) {
+    return this.transclusionService.unsyncReference(
+      dto.referencePageId,
+      dto.sourcePageId,
+      dto.transclusionId,
+      user.id,
+    );
+  }
+}
@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { TransclusionController } from './transclusion.controller';
+import { TransclusionService } from './transclusion.service';
+import { StorageModule } from '../../../integrations/storage/storage.module';
+
+@Module({
+  imports: [StorageModule],
+  controllers: [TransclusionController],
+  providers: [TransclusionService],
+  exports: [TransclusionService],
+})
+export class TransclusionModule {}
@@ -0,0 +1,526 @@
+import {
+  Injectable,
+  Logger,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import { isDeepStrictEqual } from 'node:util';
+import { v7 as uuid7 } from 'uuid';
+import { KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { PageTransclusionsRepo } from '@docmost/db/repos/page-transclusions/page-transclusions.repo';
+import { PageTransclusionReferencesRepo } from '@docmost/db/repos/page-transclusion-references/page-transclusion-references.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
+import { StorageService } from '../../../integrations/storage/storage.service';
+import {
+  collectReferencesFromPmJson,
+  collectTransclusionsFromPmJson,
+} from './utils/transclusion-prosemirror.util';
+import { rewriteAttachmentsForUnsync } from './utils/transclusion-unsync.util';
+import { TransclusionLookup } from './transclusion.types';
+import { Page } from '@docmost/db/types/entity.types';
+
+type ReferencingPageInfo = {
+  id: string;
+  slugId: string;
+  title: string | null;
+  icon: string | null;
+  spaceId: string;
+  spaceSlug: string | null;
+};
+
+@Injectable()
+export class TransclusionService {
+  private readonly logger = new Logger(TransclusionService.name);
+
+  constructor(
+    private readonly pageTransclusionsRepo: PageTransclusionsRepo,
+    private readonly pageTransclusionReferencesRepo: PageTransclusionReferencesRepo,
+    private readonly pageRepo: PageRepo,
+    private readonly pagePermissionRepo: PagePermissionRepo,
+    private readonly attachmentRepo: AttachmentRepo,
+    private readonly storageService: StorageService,
+  ) {}
+
+  async syncPageTransclusions(
+    pageId: string,
+    pmJson: unknown,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number; updated: number; deleted: number }> {
+    const desired = collectTransclusionsFromPmJson(pmJson);
+    const desiredById = new Map(desired.map((d) => [d.transclusionId, d]));
+
+    const existing = await this.pageTransclusionsRepo.findByPageId(pageId, trx);
+    const existingById = new Map(existing.map((e) => [e.transclusionId, e]));
+
+    let inserted = 0;
+    let updated = 0;
+    let deleted = 0;
+
+    for (const d of desired) {
+      const prev = existingById.get(d.transclusionId);
+      if (!prev) {
+        await this.pageTransclusionsRepo.insert(
+          {
+            pageId,
+            transclusionId: d.transclusionId,
+            name: d.name,
+            content: d.content as any,
+          },
+          trx,
+        );
+        inserted += 1;
+        continue;
+      }
+
+      const nameChanged = prev.name !== d.name;
+      const contentChanged = !isDeepStrictEqual(prev.content, d.content);
+      if (nameChanged || contentChanged) {
+        await this.pageTransclusionsRepo.update(
+          pageId,
+          d.transclusionId,
+          { name: d.name, content: d.content as any },
+          trx,
+        );
+        updated += 1;
+      }
+    }
+
+    const removedIds = existing
+      .filter((e) => !desiredById.has(e.transclusionId))
+      .map((e) => e.transclusionId);
+    if (removedIds.length > 0) {
+      await this.pageTransclusionsRepo.deleteByPageAndTransclusionIds(
+        pageId,
+        removedIds,
+        trx,
+      );
+      deleted = removedIds.length;
+    }
+
+    return { inserted, updated, deleted };
+  }
+
+  async syncPageReferences(
+    referencePageId: string,
+    pmJson: unknown,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number; deleted: number }> {
+    const desired = collectReferencesFromPmJson(pmJson);
+    const keyOf = (s: {
+      containingTransclusionId: string | null;
+      sourcePageId: string;
+      transclusionId: string;
+    }) =>
+      `${s.containingTransclusionId ?? ''}::${s.sourcePageId}::${s.transclusionId}`;
+    const desiredKeys = new Set(desired.map(keyOf));
+
+    const existing = await this.pageTransclusionReferencesRepo.findByReferencePageId(
+      referencePageId,
+      trx,
+    );
+    const existingKeys = new Set(existing.map(keyOf));
+
+    const toInsert = desired
+      .filter((d) => !existingKeys.has(keyOf(d)))
+      .map((d) => ({
+        referencePageId,
+        containingTransclusionId: d.containingTransclusionId,
+        sourcePageId: d.sourcePageId,
+        transclusionId: d.transclusionId,
+      }));
+
+    const toDelete = existing
+      .filter((e) => !desiredKeys.has(keyOf(e)))
+      .map((e) => ({
+        containingTransclusionId: e.containingTransclusionId,
+        sourcePageId: e.sourcePageId,
+        transclusionId: e.transclusionId,
+      }));
+
+    if (toInsert.length > 0) {
+      await this.pageTransclusionReferencesRepo.insertMany(toInsert, trx);
+    }
+    if (toDelete.length > 0) {
+      await this.pageTransclusionReferencesRepo.deleteByReferenceAndKeys(
+        referencePageId,
+        toDelete,
+        trx,
+      );
+    }
+
+    const removedCount = await this.removeCyclicEdgesIntroducedBy(
+      toInsert,
+      trx,
+    );
+
+    return {
+      inserted: toInsert.length - removedCount,
+      deleted: toDelete.length,
+    };
+  }
+
+  /**
+   * Run cycle detection rooted at each newly-introduced edge's target and
+   * delete any closing edge that belongs to a cycle. Lookups for those rows
+   * then return `not_found`, which the editor renders as the cycle-aware
+   * placeholder. Returns the count of rows removed.
+   */
+  private async removeCyclicEdgesIntroducedBy(
+    candidates: ReadonlyArray<{
+      referencePageId: string;
+      containingTransclusionId: string | null;
+      sourcePageId: string;
+      transclusionId: string;
+    }>,
+    trx?: KyselyTransaction,
+  ): Promise<number> {
+    const seedKeys = new Set<string>();
+    const seeds: Array<{ sourcePageId: string; transclusionId: string }> = [];
+    for (const c of candidates) {
+      if (c.containingTransclusionId === null) continue;
+      const key = `${c.sourcePageId}::${c.transclusionId}`;
+      if (seedKeys.has(key)) continue;
+      seedKeys.add(key);
+      seeds.push({
+        sourcePageId: c.sourcePageId,
+        transclusionId: c.transclusionId,
+      });
+    }
+    if (seeds.length === 0) return 0;
+
+    const offendingIds = new Set<string>();
+    for (const seed of seeds) {
+      const cyclicEdges =
+        await this.pageTransclusionReferencesRepo.findCyclicEdgesForSource(
+          seed.sourcePageId,
+          seed.transclusionId,
+          trx,
+        );
+      for (const edge of cyclicEdges) offendingIds.add(edge.id);
+    }
+
+    if (offendingIds.size === 0) return 0;
+
+    await this.pageTransclusionReferencesRepo.deleteByIds(
+      Array.from(offendingIds),
+      trx,
+    );
+    return offendingIds.size;
+  }
+
+  /**
+   * Extract transclusions from each page's PM JSON and bulk-insert into
+   * `page_transclusions` in a single statement. Intended for brand-new pages
+   * (e.g. duplication, import) where there is nothing to diff against.
+   */
+  async insertTransclusionsForPages(
+    pages: Array<{ id: string; content: unknown }>,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number }> {
+    const rows: Parameters<PageTransclusionsRepo['insertMany']>[0] = [];
+    for (const page of pages) {
+      const snapshots = collectTransclusionsFromPmJson(page.content);
+      for (const s of snapshots) {
+        rows.push({
+          pageId: page.id,
+          transclusionId: s.transclusionId,
+          name: s.name,
+          content: s.content as any,
+        });
+      }
+    }
+    if (rows.length === 0) return { inserted: 0 };
+    await this.pageTransclusionsRepo.insertMany(rows, trx);
+    return { inserted: rows.length };
+  }
+
+  /**
+   * Walk each page's PM JSON for `transclusionReference` nodes and bulk-insert
+   * one row per `(containing, source, target)` triple. For brand-new pages
+   * (duplication, import) where there is nothing to diff against.
+   *
+   * Cycle detection runs once per distinct seed source after the bulk insert;
+   * any closing edges are removed so lookups return `not_found` and the
+   * editor renders the cycle-aware placeholder.
+   */
+  async insertReferencesForPages(
+    pages: Array<{ id: string; content: unknown }>,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number }> {
+    const rows: Array<{
+      referencePageId: string;
+      containingTransclusionId: string | null;
+      sourcePageId: string;
+      transclusionId: string;
+    }> = [];
+    for (const page of pages) {
+      const refs = collectReferencesFromPmJson(page.content);
+      for (const r of refs) {
+        rows.push({
+          referencePageId: page.id,
+          containingTransclusionId: r.containingTransclusionId,
+          sourcePageId: r.sourcePageId,
+          transclusionId: r.transclusionId,
+        });
+      }
+    }
+    if (rows.length === 0) return { inserted: 0 };
+    await this.pageTransclusionReferencesRepo.insertMany(rows, trx);
+
+    const removedCount = await this.removeCyclicEdgesIntroducedBy(rows, trx);
+    return { inserted: rows.length - removedCount };
+  }
+
+  async lookup(
+    references: Array<{ sourcePageId: string; transclusionId: string }>,
+    viewerUserId: string | null,
+  ): Promise<{ items: TransclusionLookup[] }> {
+    if (references.length === 0) return { items: [] };
+
+    const items: TransclusionLookup[] = new Array(references.length).fill(null);
+    const pendingIdx = references.map((_, i) => i);
+
+    // 1) permission filter on the candidate pageIds (auth users only;
+    // unauthenticated share viewers get no_access for any private page).
+    const candidatePageIds = Array.from(
+      new Set(pendingIdx.map((i) => references[i].sourcePageId)),
+    );
+    const accessibleSet = viewerUserId
+      ? new Set(
+          await this.pagePermissionRepo.filterAccessiblePageIds({
+            pageIds: candidatePageIds,
+            userId: viewerUserId,
+          }),
+        )
+      : new Set<string>();
+
+    // 2) one DB hit for all (page_id, transclusion_id) keys still pending and accessible
+    const accessiblePending = pendingIdx.filter((i) =>
+      accessibleSet.has(references[i].sourcePageId),
+    );
+    const rows = await this.pageTransclusionsRepo.findManyByPageAndTransclusion(
+      accessiblePending.map((i) => ({
+        pageId: references[i].sourcePageId,
+        transclusionId: references[i].transclusionId,
+      })),
+    );
+    const rowKey = (r: { pageId: string; transclusionId: string }) =>
+      `${r.pageId}::${r.transclusionId}`;
+    const rowMap = new Map(rows.map((r) => [rowKey(r), r]));
+
+    // 3) pull updatedAt from each accessible page so we can return
+    //    sourceUpdatedAt on each successful result.
+    const accessiblePageIds = Array.from(
+      new Set(accessiblePending.map((i) => references[i].sourcePageId)),
+    );
+    const pageMeta = new Map<string, Date>();
+    for (const pid of accessiblePageIds) {
+      const p = await this.pageRepo.findById(pid);
+      if (p && !p.deletedAt) pageMeta.set(p.id, p.updatedAt);
+    }
+
+    // 4) stitch the results
+    for (const i of pendingIdx) {
+      const ref = references[i];
+      if (!accessibleSet.has(ref.sourcePageId)) {
+        items[i] = {
+          sourcePageId: ref.sourcePageId,
+          transclusionId: ref.transclusionId,
+          status: 'no_access',
+        };
+        continue;
+      }
+      const updatedAt = pageMeta.get(ref.sourcePageId);
+      if (!updatedAt) {
+        items[i] = {
+          sourcePageId: ref.sourcePageId,
+          transclusionId: ref.transclusionId,
+          status: 'not_found',
+        };
+        continue;
+      }
+
+      const row = rowMap.get(`${ref.sourcePageId}::${ref.transclusionId}`);
+      if (!row) {
+        items[i] = {
+          sourcePageId: ref.sourcePageId,
+          transclusionId: ref.transclusionId,
+          status: 'not_found',
+        };
+        continue;
+      }
+      items[i] = {
+        sourcePageId: ref.sourcePageId,
+        transclusionId: ref.transclusionId,
+        content: row.content,
+        sourceUpdatedAt: updatedAt,
+      };
+    }
+
+    return { items };
+  }
+
+  async listReferences(opts: {
+    sourcePageId: string;
+    transclusionId: string;
+    viewerUserId: string;
+  }): Promise<{
+    source: ReferencingPageInfo | null;
+    references: ReferencingPageInfo[];
+  }> {
+    const { sourcePageId, transclusionId, viewerUserId } = opts;
+
+    const referencePageIds =
+      await this.pageTransclusionReferencesRepo.findReferencePageIdsByTransclusion(
+        sourcePageId,
+        transclusionId,
+      );
+
+    const candidatePageIds = Array.from(
+      new Set([sourcePageId, ...referencePageIds]),
+    );
+    const accessibleSet = new Set(
+      await this.pagePermissionRepo.filterAccessiblePageIds({
+        pageIds: candidatePageIds,
+        userId: viewerUserId,
+      }),
+    );
+
+    const accessibleIds = candidatePageIds.filter((id) =>
+      accessibleSet.has(id),
+    );
+    if (accessibleIds.length === 0) {
+      return { source: null, references: [] };
+    }
+
+    const rows = await Promise.all(
+      accessibleIds.map((id) =>
+        this.pageRepo.findById(id, { includeSpace: true }),
+      ),
+    );
+    const byId = new Map<string, ReferencingPageInfo>();
+    for (const p of rows) {
+      if (!p || p.deletedAt) continue;
+      const space = (p as Page & { space?: { slug?: string } }).space;
+      byId.set(p.id, {
+        id: p.id,
+        slugId: p.slugId,
+        title: p.title ?? null,
+        icon: p.icon ?? null,
+        spaceId: p.spaceId,
+        spaceSlug: space?.slug ?? null,
+      });
+    }
+
+    const source = byId.get(sourcePageId) ?? null;
+    const references = referencePageIds
+      .map((id) => byId.get(id))
+      .filter((p): p is ReferencingPageInfo => Boolean(p));
+
+    return { source, references };
+  }
+
+  /**
+   * Convert a `transclusionReference` into a self-contained copy on the
+   * reference page: load source content, generate fresh attachment ids, copy storage
+   * files, insert new attachment rows, return rewritten content. The caller
+   * (controller) returns the content blob to the client which then performs
+   * `editor.commands.insertContentAt(range, content)` to replace the
+   * reference node. The next Yjs save naturally cleans up the
+   * page_transclusion_references row, but we also delete it eagerly here so a
+   * crash between server response and client save doesn't leave a stale row.
+   */
+  async unsyncReference(
+    referencePageId: string,
+    sourcePageId: string,
+    transclusionId: string,
+    viewerUserId: string,
+  ): Promise<{ content: unknown }> {
+    const referencePage = await this.pageRepo.findById(referencePageId);
+    if (!referencePage || referencePage.deletedAt) {
+      throw new NotFoundException('Reference page not found');
+    }
+
+    const sourcePage = await this.pageRepo.findById(sourcePageId);
+    if (!sourcePage || sourcePage.deletedAt) {
+      throw new NotFoundException('Source page not found');
+    }
+
+    const accessible = new Set(
+      await this.pagePermissionRepo.filterAccessiblePageIds({
+        pageIds: [referencePageId, sourcePageId],
+        userId: viewerUserId,
+      }),
+    );
+    if (!accessible.has(referencePageId) || !accessible.has(sourcePageId)) {
+      throw new ForbiddenException();
+    }
+
+    const transclusion =
+      await this.pageTransclusionsRepo.findByPageAndTransclusion(
+        sourcePageId,
+        transclusionId,
+      );
+    if (!transclusion) {
+      throw new NotFoundException('Sync block not found');
+    }
+
+    const { content, copies } = rewriteAttachmentsForUnsync(
+      transclusion.content,
+      () => uuid7(),
+    );
+
+    if (copies.length > 0) {
+      const oldIds = copies.map((c) => c.oldAttachmentId);
+      const oldRows = await this.attachmentRepo.findBySpaceId(sourcePage.spaceId);
+      const byOldId = new Map(
+        oldRows
+          .filter(
+            (a) => oldIds.includes(a.id) && a.pageId === sourcePageId,
+          )
+          .map((a) => [a.id, a]),
+      );
+
+      for (const plan of copies) {
+        const old = byOldId.get(plan.oldAttachmentId);
+        if (!old) continue;
+
+        const newFilePath = old.filePath
+          .split(plan.oldAttachmentId)
+          .join(plan.newAttachmentId);
+        try {
+          await this.storageService.copy(old.filePath, newFilePath);
+        } catch (err) {
+          this.logger.error(
+            `unsync: failed to copy attachment ${old.id}`,
+            err as Error,
+          );
+          continue;
+        }
+        await this.attachmentRepo.insertAttachment({
+          id: plan.newAttachmentId,
+          type: old.type,
+          filePath: newFilePath,
+          fileName: old.fileName,
+          fileSize: old.fileSize,
+          mimeType: old.mimeType,
+          fileExt: old.fileExt,
+          creatorId: viewerUserId,
+          workspaceId: referencePage.workspaceId,
+          pageId: referencePageId,
+          spaceId: referencePage.spaceId,
+        });
+      }
+    }
+
+    await this.pageTransclusionReferencesRepo.deleteOne(
+      referencePageId,
+      sourcePageId,
+      transclusionId,
+    );
+
+    return { content };
+  }
+}
@@ -0,0 +1,15 @@
+export type TransclusionLookup =
+  | {
+      sourcePageId: string;
+      transclusionId: string;
+      content: unknown;
+      sourceUpdatedAt: Date;
+    }
+  | { sourcePageId: string; transclusionId: string; status: 'not_found' }
+  | { sourcePageId: string; transclusionId: string; status: 'no_access' };
+
+export type TransclusionNodeSnapshot = {
+  transclusionId: string;
+  name: string | null;
+  content: unknown;
+};
@@ -0,0 +1,111 @@
+import { TransclusionNodeSnapshot } from '../transclusion.types';
+
+const TRANSCLUSION_TYPE = 'transclusion';
+const REFERENCE_TYPE = 'transclusionReference';
+
+export type TransclusionReferenceSnapshot = {
+  /**
+   * Id of the `transclusion` (source) node whose content holds this reference,
+   * or `null` if the reference is loose on the page (not nested inside a source).
+   * Used by the cycle-detection CTE to walk source-to-source edges.
+   */
+  containingTransclusionId: string | null;
+  sourcePageId: string;
+  transclusionId: string;
+};
+
+/**
+ * Walks a ProseMirror JSON document and returns one snapshot per top-level
+ * `transclusion` node. Does not recurse into transclusions (schema disallows
+ * nesting). Skips transclusion nodes without an id (transient state). When
+ * duplicate ids are encountered, the later occurrence wins so the result is
+ * deterministic.
+ */
+export function collectTransclusionsFromPmJson(
+  doc: unknown,
+): TransclusionNodeSnapshot[] {
+  if (!doc || typeof doc !== 'object') return [];
+
+  const byId = new Map<string, TransclusionNodeSnapshot>();
+
+  const visit = (node: any): void => {
+    if (!node || typeof node !== 'object') return;
+
+    if (node.type === TRANSCLUSION_TYPE) {
+      const id = node.attrs?.id;
+      if (typeof id === 'string' && id.length > 0) {
+        const name =
+          typeof node.attrs?.name === 'string' && node.attrs.name.length > 0
+            ? node.attrs.name
+            : null;
+        byId.set(id, {
+          transclusionId: id,
+          name,
+          content: { type: 'doc', content: node.content ?? [] },
+        });
+      }
+      return; // do not recurse into transclusion children
+    }
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child);
+    }
+  };
+
+  visit(doc);
+  return Array.from(byId.values());
+}
+
+/**
+ * Walks a ProseMirror JSON document and returns one snapshot per unique
+ * `(containingTransclusionId, sourcePageId, transclusionId)` triple found on
+ * `transclusionReference` nodes. Recurses into every container, including
+ * `transclusion` (a source node may contain a reference to another source).
+ * Order preserved by first-seen.
+ */
+export function collectReferencesFromPmJson(
+  doc: unknown,
+): TransclusionReferenceSnapshot[] {
+  if (!doc || typeof doc !== 'object') return [];
+
+  const seen = new Set<string>();
+  const out: TransclusionReferenceSnapshot[] = [];
+
+  const visit = (node: any, containingTransclusionId: string | null): void => {
+    if (!node || typeof node !== 'object') return;
+
+    if (node.type === REFERENCE_TYPE) {
+      const sourcePageId = node.attrs?.sourcePageId;
+      const transclusionId = node.attrs?.transclusionId;
+      if (
+        typeof sourcePageId === 'string' &&
+        sourcePageId.length > 0 &&
+        typeof transclusionId === 'string' &&
+        transclusionId.length > 0
+      ) {
+        const key = `${containingTransclusionId ?? ''}::${sourcePageId}::${transclusionId}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          out.push({
+            containingTransclusionId,
+            sourcePageId,
+            transclusionId,
+          });
+        }
+      }
+      return; // atom node - no children
+    }
+
+    const nextContainer =
+      node.type === TRANSCLUSION_TYPE && typeof node.attrs?.id === 'string'
+        ? node.attrs.id
+        : containingTransclusionId;
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child, nextContainer);
+    }
+  };
+
+  visit(doc, null);
+  return out;
+}
@@ -0,0 +1,65 @@
+import { isAttachmentNode } from '../../../../common/helpers/prosemirror/utils';
+
+export type AttachmentRewritePlan = {
+  oldAttachmentId: string;
+  newAttachmentId: string;
+};
+
+export type RewriteResult = {
+  content: unknown;
+  copies: AttachmentRewritePlan[];
+};
+
+/**
+ * Walk a ProseMirror JSON tree, rewrite every attachment-like node so its
+ * `attachmentId` (and any `src` substring matching that id) point at a fresh
+ * id. Each unique old id maps to exactly one new id; the caller is responsible
+ * for actually copying the underlying storage file.
+ *
+ * Pure: does not mutate the input. Returns a deep clone.
+ */
+export function rewriteAttachmentsForUnsync(
+  content: unknown,
+  generateId: () => string,
+): RewriteResult {
+  const cloned = content ? JSON.parse(JSON.stringify(content)) : content;
+  const idMap = new Map<string, string>();
+
+  const visit = (node: any): void => {
+    if (!node || typeof node !== 'object') return;
+
+    if (
+      typeof node.type === 'string' &&
+      isAttachmentNode(node.type) &&
+      node.attrs
+    ) {
+      const oldId = node.attrs.attachmentId;
+      if (typeof oldId === 'string' && oldId.length > 0) {
+        let newId = idMap.get(oldId);
+        if (!newId) {
+          newId = generateId();
+          idMap.set(oldId, newId);
+        }
+        node.attrs.attachmentId = newId;
+        if (typeof node.attrs.src === 'string' && node.attrs.src.includes(oldId)) {
+          node.attrs.src = node.attrs.src.split(oldId).join(newId);
+        }
+      }
+    }
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child);
+    }
+  };
+
+  visit(cloned);
+
+  const copies: AttachmentRewritePlan[] = Array.from(idMap.entries()).map(
+    ([oldAttachmentId, newAttachmentId]) => ({
+      oldAttachmentId,
+      newAttachmentId,
+    }),
+  );
+
+  return { content: cloned, copies };
+}
@@ -13,10 +13,6 @@ import { CreateUserDto } from '../../auth/dto/create-user.dto';
 export class UpdateUserDto extends PartialType(
  OmitType(CreateUserDto, ['password'] as const),
 ) {
-  @IsOptional()
-  @IsString()
-  avatarUrl: string;
-
  @IsOptional()
  @IsBoolean()
  fullPageWidth: boolean;
@@ -110,10 +110,6 @@ export class UserService {
      user.email = updateUserDto.email;
    }

-    if (updateUserDto.avatarUrl) {
-      user.avatarUrl = updateUserDto.avatarUrl;
-    }
-
    if (updateUserDto.locale) {
      user.locale = updateUserDto.locale;
    }
@@ -5,15 +5,10 @@ import {
  IsBoolean,
  IsInt,
  IsOptional,
-  IsString,
  Min,
 } from 'class-validator';

 export class UpdateWorkspaceDto extends PartialType(CreateWorkspaceDto) {
-  @IsOptional()
-  @IsString()
-  logo: string;
-
  @IsOptional()
  @IsArray()
  emailDomains: string[];
@@ -46,6 +41,10 @@ export class UpdateWorkspaceDto extends PartialType(CreateWorkspaceDto) {
  @IsBoolean()
  mcpEnabled: boolean;

+  @IsOptional()
+  @IsBoolean()
+  isScimEnabled: boolean;
+
  @IsOptional()
  @IsBoolean()
  aiChat: boolean;
@@ -331,7 +331,8 @@ export class WorkspaceService {
      typeof updateWorkspaceDto.trashRetentionDays !== 'undefined' ||
      typeof updateWorkspaceDto.mcpEnabled !== 'undefined' ||
      typeof updateWorkspaceDto.restrictApiToAdmins !== 'undefined' ||
-      typeof updateWorkspaceDto.allowMemberTemplates !== 'undefined'
+      typeof updateWorkspaceDto.allowMemberTemplates !== 'undefined' ||
+      typeof updateWorkspaceDto.isScimEnabled !== 'undefined'
    ) {
      const ws = await this.db
        .selectFrom('workspaces')
@@ -351,6 +352,14 @@ export class WorkspaceService {
        }
      }

+      if (typeof updateWorkspaceDto.isScimEnabled !== 'undefined') {
+        if (!this.licenseCheckService.hasFeature(ws.licenseKey, Feature.SCIM, ws.plan)) {
+          throw new ForbiddenException(
+            'This feature requires a valid license',
+          );
+        }
+      }
+
      if (
        typeof updateWorkspaceDto.disablePublicSharing !== 'undefined' ||
        typeof updateWorkspaceDto.trashRetentionDays !== 'undefined' ||
@@ -535,6 +544,7 @@ export class WorkspaceService {
        'enforceSso',
        'enforceMfa',
        'emailDomains',
+        'isScimEnabled',
      ],
      updateWorkspaceDto,
      workspaceBefore,
@@ -11,6 +11,8 @@ import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
 import { PageRepo } from './repos/page/page.repo';
 import { PagePermissionRepo } from './repos/page/page-permission.repo';
 import { CommentRepo } from './repos/comment/comment.repo';
+import { PageTransclusionsRepo } from './repos/page-transclusions/page-transclusions.repo';
+import { PageTransclusionReferencesRepo } from './repos/page-transclusion-references/page-transclusion-references.repo';
 import { PageHistoryRepo } from './repos/page/page-history.repo';
 import { AttachmentRepo } from './repos/attachment/attachment.repo';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
@@ -75,6 +77,8 @@ import { normalizePostgresUrl } from '../common/helpers';
    SpaceMemberRepo,
    PageRepo,
    PagePermissionRepo,
+    PageTransclusionsRepo,
+    PageTransclusionReferencesRepo,
    PageHistoryRepo,
    CommentRepo,
    FavoriteRepo,
@@ -97,6 +101,8 @@ import { normalizePostgresUrl } from '../common/helpers';
    SpaceMemberRepo,
    PageRepo,
    PagePermissionRepo,
+    PageTransclusionsRepo,
+    PageTransclusionReferencesRepo,
    PageHistoryRepo,
    CommentRepo,
    FavoriteRepo,
@@ -0,0 +1,110 @@
+import { Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('scim_tokens')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('name', 'varchar', (col) => col.notNull())
+    .addColumn('token_hash', 'varchar', (col) => col.notNull())
+    .addColumn('token_last_four', 'varchar(4)', (col) => col.notNull())
+    .addColumn('last_used_at', 'timestamptz')
+    .addColumn('is_enabled', 'boolean', (col) => col.notNull().defaultTo(true))
+    .addColumn('creator_id', 'uuid', (col) =>
+      col.references('users.id').onDelete('set null'),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.references('workspaces.id').onDelete('cascade').notNull(),
+    )
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('updated_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('deleted_at', 'timestamptz')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_scim_tokens_token_hash')
+    .ifNotExists()
+    .on('scim_tokens')
+    .column('token_hash')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_scim_tokens_workspace_id')
+    .ifNotExists()
+    .on('scim_tokens')
+    .column('workspace_id')
+    .execute();
+
+  await db.schema
+    .alterTable('users')
+    .addColumn('scim_external_id', 'text')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_users_workspace_scim_external_id')
+    .ifNotExists()
+    .on('users')
+    .columns(['workspace_id', 'scim_external_id'])
+    .where('scim_external_id', 'is not', null)
+    .unique()
+    .execute();
+
+  await db.schema
+    .alterTable('groups')
+    .addColumn('scim_external_id', 'text')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_groups_workspace_scim_external_id')
+    .ifNotExists()
+    .on('groups')
+    .columns(['workspace_id', 'scim_external_id'])
+    .where('scim_external_id', 'is not', null)
+    .unique()
+    .execute();
+
+  await db.schema
+    .alterTable('groups')
+    .addColumn('is_external', 'boolean', (col) =>
+      col.notNull().defaultTo(false),
+    )
+    .execute();
+
+  // Backfill: mark all non-default groups as external in workspaces with SSO group sync enabled
+  await sql`
+    UPDATE groups SET is_external = true
+    WHERE is_default = false
+    AND workspace_id IN (
+      SELECT workspace_id FROM auth_providers WHERE group_sync = true
+    )
+  `.execute(db);
+
+  await db.schema
+    .alterTable('workspaces')
+    .addColumn('is_scim_enabled', 'boolean', (col) =>
+      col.notNull().defaultTo(false),
+    )
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('scim_tokens').execute();
+
+  await db.schema.dropIndex('idx_users_workspace_scim_external_id').execute();
+  await db.schema.alterTable('users').dropColumn('scim_external_id').execute();
+
+  await db.schema.dropIndex('idx_groups_workspace_scim_external_id').execute();
+  await db.schema.alterTable('groups').dropColumn('scim_external_id').execute();
+
+  await db.schema.alterTable('groups').dropColumn('is_external').execute();
+
+  await db.schema
+    .alterTable('workspaces')
+    .dropColumn('is_scim_enabled')
+    .execute();
+}
@@ -0,0 +1,79 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('page_transclusions')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('transclusion_id', 'varchar', (col) => col.notNull())
+    .addColumn('name', 'text')
+    .addColumn('content', 'jsonb', (col) => col.notNull())
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('updated_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addUniqueConstraint('page_transclusions_page_transclusion_unique', [
+      'page_id',
+      'transclusion_id',
+    ])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusions_page_id')
+    .on('page_transclusions')
+    .column('page_id')
+    .execute();
+
+  await db.schema
+    .createTable('page_transclusion_references')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('reference_page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('containing_transclusion_id', 'varchar')
+    .addColumn('source_page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('transclusion_id', 'varchar', (col) => col.notNull())
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addUniqueConstraint('page_transclusion_references_unique', [
+      'reference_page_id',
+      'containing_transclusion_id',
+      'source_page_id',
+      'transclusion_id',
+    ])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusion_references_reference_page_id')
+    .on('page_transclusion_references')
+    .column('reference_page_id')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusion_references_source')
+    .on('page_transclusion_references')
+    .columns(['source_page_id', 'transclusion_id'])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusion_references_container')
+    .on('page_transclusion_references')
+    .columns(['reference_page_id', 'containing_transclusion_id'])
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('page_transclusion_references').execute();
+  await db.schema.dropTable('page_transclusions').execute();
+}
@@ -9,7 +9,7 @@ import {
 } from '@docmost/db/types/entity.types';
 import { ExpressionBuilder, sql } from 'kysely';
 import { PaginationOptions } from '../../pagination/pagination-options';
-import { DB } from '@docmost/db/types/db';
+import { DB, Groups } from '@docmost/db/types/db';
 import { DefaultGroup } from '../../../core/group/dto/create-group.dto';
 import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagination';

@@ -17,16 +17,34 @@ import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagin
 export class GroupRepo {
  constructor(@InjectKysely() private readonly db: KyselyDB) {}

+  private baseFields: Array<keyof Groups> = [
+    'id',
+    'name',
+    'description',
+    'isDefault',
+    'isExternal',
+    'creatorId',
+    'workspaceId',
+    'createdAt',
+    'updatedAt',
+    'deletedAt',
+  ];
+
  async findById(
    groupId: string,
    workspaceId: string,
-    opts?: { includeMemberCount?: boolean; trx?: KyselyTransaction },
+    opts?: {
+      includeMemberCount?: boolean;
+      includeScimExternalId?: boolean;
+      trx?: KyselyTransaction;
+    },
  ): Promise<Group> {
    const db = dbOrTx(this.db, opts?.trx);
    return db
      .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
      .$if(opts?.includeMemberCount, (qb) => qb.select(this.withMemberCount))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
      .where('id', '=', groupId)
      .where('workspaceId', '=', workspaceId)
      .executeTakeFirst();
@@ -35,13 +53,18 @@ export class GroupRepo {
  async findByName(
    groupName: string,
    workspaceId: string,
-    opts?: { includeMemberCount?: boolean; trx?: KyselyTransaction },
+    opts?: {
+      includeMemberCount?: boolean;
+      includeScimExternalId?: boolean;
+      trx?: KyselyTransaction;
+    },
  ): Promise<Group> {
    const db = dbOrTx(this.db, opts?.trx);
    return db
      .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
      .$if(opts?.includeMemberCount, (qb) => qb.select(this.withMemberCount))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
      .where(sql`LOWER(name)`, '=', sql`LOWER(${groupName})`)
      .where('workspaceId', '=', workspaceId)
      .executeTakeFirst();
@@ -51,8 +74,11 @@ export class GroupRepo {
    updatableGroup: UpdatableGroup,
    groupId: string,
    workspaceId: string,
+    trx?: KyselyTransaction,
  ): Promise<void> {
-    await this.db
+    const db = dbOrTx(this.db, trx);
+
+    await db
      .updateTable('groups')
      .set({ ...updatableGroup, updatedAt: new Date() })
      .where('id', '=', groupId)
@@ -68,7 +94,7 @@ export class GroupRepo {
    return db
      .insertInto('groups')
      .values(insertableGroup)
-      .returningAll()
+      .returning(this.baseFields)
      .executeTakeFirst();
  }

@@ -80,7 +106,7 @@ export class GroupRepo {
    return (
      db
        .selectFrom('groups')
-        .selectAll()
+        .select(this.baseFields)
        // .select((eb) => this.withMemberCount(eb))
        .where('isDefault', '=', true)
        .where('workspaceId', '=', workspaceId)
@@ -106,7 +132,7 @@ export class GroupRepo {
  async getGroupsPaginated(workspaceId: string, pagination: PaginationOptions) {
    let baseQuery = this.db
      .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
      .select((eb) => this.withMemberCount(eb))
      .where('workspaceId', '=', workspaceId);

--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Philipinho	cc343b095a	feat: sync blocks - wip	2026-05-04 18:08:34 +01:00
Philipinho	17f3158a3b	update aws packages	2026-05-01 20:00:20 +01:00
Philipinho	b74ca00bfd	sync	2026-05-01 14:57:32 +01:00
Philip Okugbe	c247d4c1e3	feat(ee): PDF import (#2142 ) * feat: replace pdfjs-dist with firecrawl-pdf-inspector * use modified firecrawl-pdf-inspector * feat: pdf import * increase single file upload size limit * use npm package * sync * update package	2026-05-01 14:56:39 +01:00
Philip Okugbe	641ce142df	feat(ee): SCIM (#1347 ) * SCIM - init (EE) * accept db transaction * sync * Content parser support for scim+json * patch scimmy * sync * return early if userIds is empty * sync * SCIM db table * fixes * scim tokens * backfill * feat(audit): add scim token events * rename scim migration * fix * fix translation * cleanup	2026-05-01 14:53:30 +01:00
Sarthak Chaturvedi	1d2486455f	fix: prevent browser tab fallback in editor (#2123 )	2026-05-01 13:58:51 +01:00
Philipinho	a0aea43e25	feat(saml): allow disabling RequestedAuthnContext via env var Adds SAML_DISABLE_REQUESTED_AUTHN_CONTEXT env var, passed through to the SAML strategy's disableRequestedAuthnContext option. Defaults to existing behavior (element sent). Set to true to omit the element when the IdP authenticates the user with a method that does not match (e.g. MFA, FIDO, passwordless), which would otherwise cause AADSTS75011 with Microsoft Entra ID.	2026-05-01 11:47:03 +01:00
Philip Okugbe	09c69d7a0f	feat: properly preserve table width (#2143 )	2026-05-01 00:49:31 +01:00
Sarthak Chaturvedi	9943e104a5	fix(i18n): Correct German column count label rendering (#2131 )	2026-05-01 00:37:59 +01:00
Peter Tripp	b16f1e5a55	fix: ctrl-k behavior on macOS (#2052 ) * Improve cmd-k / ctrl-k behavior Use cmd-k on macOS/iOS for search and keep ctrl-k everywhere else. Fixes a bug where ctrl-k on macOS, which cuts to the end of the line, was also triggering the search prompt. * comment submit: cmd-enter (mac) / ctrl-enter (win/linux)	2026-05-01 00:36:40 +01:00
Philip Okugbe	24be90b95f	fix: duplicate PDF uploads (#2139 )	2026-04-29 10:01:47 +01:00
Olivier Lambert	3ecf27c6b0	fix(page-permission): make people-with-access list scroll past 4 entries (#2137 ) The "People with access" list in the page share modal used <ScrollArea mah={250}>, which caps the container height but does not make the inner viewport scroll (no fixed height is given to the viewport). Items beyond ~4 entries were rendered correctly but clipped out of view. Switches to <ScrollArea.Autosize mah={400}>, which is Mantine's dedicated primitive for "grow with content up to a max, then scroll". Closes #2135	2026-04-29 09:36:38 +01:00
Philipinho	980521f957	v0.80.1	2026-04-27 16:06:32 +01:00
Philipinho	fe44dc92a9	sync	2026-04-27 15:51:23 +01:00
Philip Okugbe	fad410ef23	chore: add undici for oidc proxy support (#2132 )	2026-04-27 15:50:42 +01:00
Philipinho	15b8908b1a	update postcss	2026-04-27 15:23:47 +01:00
Philipinho	8e15b22d8c	package updates	2026-04-27 15:22:02 +01:00
Philipinho	ec83fc82d5	fix: refactor sanitize	2026-04-27 15:16:26 +01:00
Philipinho	a573acedd0	fix: local storage, and package overrides	2026-04-22 14:13:25 +01:00
Philipinho	dba8e315ab	override	2026-04-14 17:59:59 +01:00
Philipinho	81ae7a17a6	confirm dialog	2026-04-14 17:56:36 +01:00
Philipinho	271f855761	v0.80.0	2026-04-14 17:08:44 +01:00