From 5ddee1f37356cee8becde1d4b72da4c19bc059b9 Mon Sep 17 00:00:00 2001
From: naaiyy <naaiyyyy@gmail.com>
Date: Fri, 28 Aug 2026 20:21:54 +0200
Subject: [PATCH 1/6] Refactor publication around immutable releases

---
 README.md                                     |   8 +-
 .../dashboard/use-site-navigation.test.ts     |  16 +
 .../features/dashboard/use-site-navigation.ts |  10 +-
 apps/web/features/editor/editor.tsx           |  31 +-
 .../features/editor/publish-dialog.test.ts    |  24 +
 apps/web/features/editor/publish-dialog.tsx   | 101 +--
 .../content/docs/publishing/index.fr.mdx      |  22 +-
 .../content/docs/publishing/index.mdx         |  21 +-
 .../features/published-sites/read-model.ts    |  39 +-
 docs/publishing-migration.md                  |  60 ++
 packages/backend/convex/_generated/api.d.ts   |   4 +
 packages/backend/convex/draftRestore.test.ts  | 149 +++-
 packages/backend/convex/draftRestores.ts      | 107 ++-
 packages/backend/convex/editorWorkspace.ts    |  12 +-
 packages/backend/convex/files.ts              |  17 +-
 packages/backend/convex/libraries.ts          |   3 +-
 .../convex/model/contentObjects.test.ts       |  42 +
 .../backend/convex/model/contentObjects.ts    |  26 +
 packages/backend/convex/model/draftSummary.ts |   8 +-
 .../backend/convex/model/publishedRelease.ts  |   3 +-
 .../convex/model/releaseChangeDetails.ts      |  17 +-
 .../backend/convex/model/releaseOperations.ts |  25 +-
 .../backend/convex/model/releaseState.test.ts |  35 +-
 packages/backend/convex/model/releaseState.ts |  17 +
 packages/backend/convex/publication.test.ts   | 757 ++++++++++++++++++
 packages/backend/convex/publication.ts        | 504 ++++++++++++
 .../convex/publicationMigrations.test.ts      | 296 +++++++
 .../backend/convex/publicationMigrations.ts   | 408 ++++++++++
 packages/backend/convex/published.ts          |  16 +-
 .../backend/convex/releasePublication.test.ts | 276 ++++---
 packages/backend/convex/releasePublication.ts | 685 ++++------------
 packages/backend/convex/releases.ts           | 208 +++--
 packages/backend/convex/schema.ts             |  73 +-
 packages/backend/convex/search.test.ts        |  21 +
 packages/backend/convex/search.ts             |  69 +-
 packages/backend/convex/siteDomains.ts        |   3 +
 36 files changed, 3148 insertions(+), 965 deletions(-)
 create mode 100644 apps/web/features/dashboard/use-site-navigation.test.ts
 create mode 100644 apps/web/features/editor/publish-dialog.test.ts
 create mode 100644 docs/publishing-migration.md
 create mode 100644 packages/backend/convex/model/contentObjects.test.ts
 create mode 100644 packages/backend/convex/publication.test.ts
 create mode 100644 packages/backend/convex/publication.ts
 create mode 100644 packages/backend/convex/publicationMigrations.test.ts
 create mode 100644 packages/backend/convex/publicationMigrations.ts

diff --git a/README.md b/README.md
index ef1bb85b..f8926239 100644
--- a/README.md
+++ b/README.md
@@ -23,9 +23,10 @@ Teams create structured sites with a block editor, organize pages and document l
 
 ## Publishing model
 
-A site can be published or unpublished. Publishing makes the current saved content available at its generated URL and any verified custom domain. Unpublishing removes public access without deleting the site.
-
-Published sites currently read the latest saved page content. Historical deployment snapshots and rollback are not implemented yet.
+A site can be published or unpublished. Each publish creates an immutable version
+from the saved draft and switches the live site to that version atomically.
+Unpublishing removes public access without deleting the site. Version history can
+make an earlier version live or restore it to the draft before republishing.
 
 ## Tech stack
 
@@ -182,7 +183,6 @@ Document text extraction can be connected through `EXTRACTION_API_URL` and `EXTR
 Active areas of work include:
 
 - Continued editor polish and accessibility
-- Historical publishing snapshots and rollback
 - Broader custom-block APIs
 - Templates and starter sites
 - Analytics and insights
diff --git a/apps/web/features/dashboard/use-site-navigation.test.ts b/apps/web/features/dashboard/use-site-navigation.test.ts
new file mode 100644
index 00000000..4878a175
--- /dev/null
+++ b/apps/web/features/dashboard/use-site-navigation.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { getSitesWithReadablePages } from "./use-site-navigation";
+
+describe("site navigation page queries", () => {
+  test("does not request pages while a historical restore owns the site", () => {
+    const readableSite = { _id: "site-readable" };
+    const restoringSite = {
+      _id: "site-restoring",
+      activeDraftRestoreId: "restore-1",
+    };
+
+    expect(getSitesWithReadablePages([readableSite, restoringSite])).toEqual([
+      readableSite,
+    ]);
+  });
+});
diff --git a/apps/web/features/dashboard/use-site-navigation.ts b/apps/web/features/dashboard/use-site-navigation.ts
index 45292b64..26554a47 100644
--- a/apps/web/features/dashboard/use-site-navigation.ts
+++ b/apps/web/features/dashboard/use-site-navigation.ts
@@ -17,6 +17,12 @@ export type SiteNavigationItem = {
   pages: Array<PageListItem & { updatedAt: number }>;
 };
 
+export function getSitesWithReadablePages<
+  T extends { activeDraftRestoreId?: unknown },
+>(sites: readonly T[]): T[] {
+  return sites.filter((site) => !site.activeDraftRestoreId);
+}
+
 /**
  * Builds the workspace navigation from the long-lived site and page queries.
  * Keeping the dynamic query set behind one hook gives callers a single loading
@@ -30,7 +36,7 @@ export function useSiteNavigation(
     if (!sites) return {};
 
     return Object.fromEntries(
-      sites.map((site) => [
+      getSitesWithReadablePages(sites).map((site) => [
         site._id,
         { query: api.pages.list, args: { siteId: site._id } },
       ]),
@@ -42,7 +48,7 @@ export function useSiteNavigation(
 
   const navigation: SiteNavigationItem[] = [];
   for (const site of sites) {
-    const pages = pageResults[site._id];
+    const pages = site.activeDraftRestoreId ? [] : pageResults[site._id];
     if (pages === undefined) return undefined;
     if (pages instanceof Error) throw pages;
 
diff --git a/apps/web/features/editor/editor.tsx b/apps/web/features/editor/editor.tsx
index cde0b176..6343d640 100644
--- a/apps/web/features/editor/editor.tsx
+++ b/apps/web/features/editor/editor.tsx
@@ -66,6 +66,7 @@ function SiteEditorScreen({
   );
   const searchParams = useSearchParams();
   const requestedAction = searchParams.get("action");
+  const selectedPageId = selectedPage?._id;
 
   const unpublishSite = useMutation(api.releases.unpublish);
 
@@ -122,6 +123,17 @@ function SiteEditorScreen({
     );
   }, [isPreviewing, siteId]);
 
+  useEffect(() => {
+    if (!restore?._id) return;
+    setActiveDialog(null);
+    setAiChatOpen(false);
+  }, [restore?._id]);
+
+  useEffect(() => {
+    if (!selectedPageId) return;
+    setSaveStatus("idle");
+  }, [selectedPageId]);
+
   if (status === "loading") {
     return <EditorRevealBoundary state="loading" />;
   }
@@ -231,18 +243,17 @@ function SiteEditorScreen({
               </aside>
             ) : null}
           </div>
+          <EditorDialogs
+            activeDialog={activeDialog}
+            draftSummary={draftSummary}
+            onActiveDialogChange={setActiveDialog}
+            pageId={selectedPage?._id}
+            siteId={site._id}
+            siteSlug={site.slug}
+            teamSlug={team.slug}
+          />
         </>
       )}
-
-      <EditorDialogs
-        activeDialog={activeDialog}
-        draftSummary={draftSummary}
-        onActiveDialogChange={setActiveDialog}
-        pageId={selectedPage?._id}
-        siteId={site._id}
-        siteSlug={site.slug}
-        teamSlug={team.slug}
-      />
     </EditorRevealBoundary>
   );
 }
diff --git a/apps/web/features/editor/publish-dialog.test.ts b/apps/web/features/editor/publish-dialog.test.ts
new file mode 100644
index 00000000..3d7e3134
--- /dev/null
+++ b/apps/web/features/editor/publish-dialog.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { ConvexError } from "convex/values";
+import { getPublishErrorMessage } from "./publish-dialog";
+
+describe("publish error messages", () => {
+  test("preserves the stale-draft error from Convex", () => {
+    const error = new ConvexError(
+      "The draft changed while publishing. Review the latest changes and try again.",
+    );
+
+    expect(getPublishErrorMessage(error)).toBe(
+      "The draft changed while publishing. Review the latest changes and try again.",
+    );
+  });
+
+  test("handles serialized client errors", () => {
+    expect(getPublishErrorMessage({ message: "Publication failed" })).toBe(
+      "Publication failed",
+    );
+    expect(getPublishErrorMessage("Publication failed")).toBe(
+      "Publication failed",
+    );
+  });
+});
diff --git a/apps/web/features/editor/publish-dialog.tsx b/apps/web/features/editor/publish-dialog.tsx
index 17b31116..a15e4656 100644
--- a/apps/web/features/editor/publish-dialog.tsx
+++ b/apps/web/features/editor/publish-dialog.tsx
@@ -16,7 +16,7 @@ import { Spinner } from "@baseblocks/ui/spinner";
 import { Globe02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useMutation, useQuery } from "convex/react";
-import { useEffect, useState } from "react";
+import { useRef, useState } from "react";
 import { toast } from "sonner";
 
 type DraftChange = {
@@ -27,6 +27,24 @@ type DraftChange = {
   details: string[];
 };
 
+export function getPublishErrorMessage(
+  error: unknown,
+  fallback = "The site could not publish",
+): string {
+  if (error instanceof Error && error.message.trim()) return error.message;
+  if (typeof error === "string" && error.trim()) return error;
+  if (
+    error &&
+    typeof error === "object" &&
+    "message" in error &&
+    typeof error.message === "string" &&
+    error.message.trim()
+  ) {
+    return error.message;
+  }
+  return fallback;
+}
+
 export type DraftSummary = {
   draftRevision: number;
   hasUnpublishedChanges: boolean;
@@ -53,64 +71,30 @@ export function PublishDialog({
     | DraftChange[]
     | null
     | undefined;
-  const [requesting, setRequesting] = useState(false);
-  const [pendingPublication, setPendingPublication] = useState<{
-    releaseId: Id<"siteReleases">;
-    number: number;
-  } | null>(null);
-  const publicationStatus = useQuery(
-    api.releases.getPublicationStatus,
-    pendingPublication ? { releaseId: pendingPublication.releaseId } : "skip",
-  );
-  const publicationFinished =
-    publicationStatus === null ||
-    publicationStatus?.status === "complete" ||
-    publicationStatus?.status === "failed";
-  const publishing =
-    requesting || (pendingPublication !== null && !publicationFinished);
-
-  useEffect(() => {
-    if (!pendingPublication || publicationStatus === undefined) return;
-    if (publicationStatus?.status === "complete") {
-      toast.success(`Version ${pendingPublication.number} is live`, {
-        id: `publication:${pendingPublication.releaseId}:complete`,
-      });
-    } else if (publicationStatus?.status === "failed") {
-      toast.error(
-        publicationStatus.failure ?? "The site could not be published.",
-        { id: `publication:${pendingPublication.releaseId}:failed` },
-      );
-    } else if (publicationStatus === null) {
-      toast.error(
-        "The draft changed before publication completed. Review it and try again.",
-        { id: `publication:${pendingPublication.releaseId}:missing` },
-      );
-    }
-  }, [pendingPublication, publicationStatus]);
+  const [publishing, setPublishing] = useState(false);
+  const publishInFlight = useRef(false);
 
   const handlePublish = () => {
-    setRequesting(true);
+    if (publishInFlight.current) return;
+    publishInFlight.current = true;
+    setPublishing(true);
+    // Freeze the revision for this request only. If the request detects a
+    // concurrent edit, a later retry must use the newly rendered revision.
+    const expectedDraftRevision = draftSummary.draftRevision;
     void publish({
       siteId,
-      expectedDraftRevision: draftSummary.draftRevision,
+      expectedDraftRevision,
     }).then(
       (result) => {
-        setRequesting(false);
-        if (result.reused) {
-          toast.success(`Version ${result.number} is live again`);
-          onOpenChange(false);
-          return;
-        }
-        setPendingPublication({
-          releaseId: result.releaseId,
-          number: result.number,
-        });
+        publishInFlight.current = false;
+        setPublishing(false);
+        toast.success(`Version ${result.number} is live`);
+        onOpenChange(false);
       },
       (error: unknown) => {
-        setRequesting(false);
-        toast.error(
-          error instanceof Error ? error.message : "The site could not publish",
-        );
+        publishInFlight.current = false;
+        setPublishing(false);
+        toast.error(getPublishErrorMessage(error));
       },
     );
   };
@@ -121,15 +105,9 @@ export function PublishDialog({
   };
 
   return (
-    <Dialog
-      open={publicationStatus?.status !== "complete"}
-      onOpenChange={handleOpenChange}
-    >
+    <Dialog open={true} onOpenChange={handleOpenChange}>
       <DialogContent
         className="overflow-hidden rounded-2xl border-0 bg-background/80 p-0 text-foreground shadow-2xl backdrop-blur-xl backdrop-saturate-150 sm:max-w-lg"
-        onCloseAutoFocus={() => {
-          if (publicationStatus?.status === "complete") onOpenChange(false);
-        }}
         returnFocusTo={returnFocusTo}
         showCloseButton={false}
       >
@@ -165,7 +143,7 @@ export function PublishDialog({
             </Button>
             <Button
               disabled={publishing || changes === undefined || changes === null}
-              onClick={() => void handlePublish()}
+              onClick={handlePublish}
               size="sm"
             >
               {publishing ? (
@@ -198,7 +176,7 @@ function ChangeList({ changes }: { changes: DraftChange[] }) {
     <div className="grid min-w-0 max-h-72 gap-2 overflow-y-auto">
       {changes.map((change) => (
         <div
-          className="flex items-start gap-3 rounded-xl bg-muted/50 px-3 py-2.5"
+          className="flex items-start gap-2 rounded-xl bg-muted/50 px-3 py-2"
           key={`${change.entityType}:${change.entityId}`}
         >
           <ChangeBadge changeType={change.changeType} />
@@ -208,9 +186,6 @@ function ChangeList({ changes }: { changes: DraftChange[] }) {
               {change.details.join(" · ")}
             </p>
           </div>
-          <span className="text-xs capitalize text-muted-foreground">
-            {change.entityType}
-          </span>
         </div>
       ))}
     </div>
diff --git a/apps/web/features/marketing/content-pages/content/docs/publishing/index.fr.mdx b/apps/web/features/marketing/content-pages/content/docs/publishing/index.fr.mdx
index 4e424011..2a7414dc 100644
--- a/apps/web/features/marketing/content-pages/content/docs/publishing/index.fr.mdx
+++ b/apps/web/features/marketing/content-pages/content/docs/publishing/index.fr.mdx
@@ -8,14 +8,11 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';
 
 ## État de publication
 
-Un site est soit **publié**, soit **non publié**. La publication active sa
-surface en ligne. La visibilité détermine ensuite si elle est publique ou
-réservée aux membres connectés de l'équipe. Le retrait coupe entièrement la
-surface en ligne.
-
-<Callout type="warn" title="Modèle de publication actuel">
-  Les sites publiés lisent actuellement le dernier contenu enregistré. Modifier un site publié peut donc changer ce que voient les visiteurs sans déploiement d'un instantané séparé. L'historique des instantanés et la restauration ne sont pas disponibles actuellement.
-</Callout>
+Un site est soit **publié**, soit **non publié**. La publication crée une version
+immuable à partir du brouillon enregistré et active cette version atomiquement.
+La visibilité détermine ensuite si la surface en ligne est publique ou réservée
+aux membres connectés de l'équipe. Le retrait coupe entièrement la surface en
+ligne.
 
 ## Publier
 
@@ -31,13 +28,20 @@ Créez des pages et modifiez le contenu. Les changements sont enregistrés autom
 
 ### Publier
 
-Cliquez sur **Déployer** dans l'en-tête de l'éditeur. Un site Public devient
+Cliquez sur **Publier** dans l'en-tête de l'éditeur. Un site Public devient
 accessible à tous. Un site Privé devient accessible uniquement aux membres
 authentifiés depuis son adresse BaseBlocks générée.
 
 </Step>
 </Steps>
 
+## Historique des versions
+
+Ouvrez **Historique des versions** pour consulter les changements d'une version
+publiée. Choisissez **Définir comme version en ligne** pour restaurer une version
+précédente sans modifier le brouillon. Choisissez **Restaurer comme brouillon**
+pour copier cette version dans l'éditeur, puis publiez le brouillon restauré.
+
 ## Retirer un site
 
 Ouvrez le menu de déploiement et choisissez **Retirer**. L'URL générée et le
diff --git a/apps/web/features/marketing/content-pages/content/docs/publishing/index.mdx b/apps/web/features/marketing/content-pages/content/docs/publishing/index.mdx
index 04a44bdd..9b02f793 100644
--- a/apps/web/features/marketing/content-pages/content/docs/publishing/index.mdx
+++ b/apps/web/features/marketing/content-pages/content/docs/publishing/index.mdx
@@ -8,13 +8,11 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';
 
 ## Publication status
 
-A site is either **published** or **unpublished**. Publishing enables its live
-surface. Visibility then determines whether that surface is public or restricted
-to signed-in team members. Unpublishing disables the live surface completely.
-
-<Callout type="warn" title="Current publishing model">
-  Published sites currently read the latest saved page content. Editing a published site can therefore change what visitors see without a separate snapshot deployment. Historical snapshots and rollback are not currently available.
-</Callout>
+A site is either **published** or **unpublished**. Publishing creates an
+immutable version from the saved draft and switches the live surface to that
+version atomically. Visibility then determines whether that surface is public or
+restricted to signed-in team members. Unpublishing disables the live surface
+completely.
 
 ## Publishing
 
@@ -30,13 +28,20 @@ Create pages and edit content. Changes save automatically.
 
 ### Publish
 
-Click **Deploy** in the editor header. A Public site becomes available to
+Click **Publish** in the editor header. A Public site becomes available to
 everyone. A Private site becomes available only to authenticated team members
 at its generated BaseBlocks address.
 
 </Step>
 </Steps>
 
+## Version history
+
+Open **Version history** to review the changes in a published version. Choose
+**Set as live** to roll back visitors to an earlier version without changing the
+draft. Choose **Restore as draft** to copy that version into the editor; publish
+the restored draft when it is ready.
+
 ## Unpublishing
 
 Open the deployment menu and choose **Unpublish**. The generated URL and custom
diff --git a/apps/web/features/published-sites/read-model.ts b/apps/web/features/published-sites/read-model.ts
index 5488848e..7c5c27fd 100644
--- a/apps/web/features/published-sites/read-model.ts
+++ b/apps/web/features/published-sites/read-model.ts
@@ -24,12 +24,12 @@ async function queryPublishedSite(
   });
 }
 
-const queryPublicPublishedSite = unstable_cache(
-  (organizationSlug: string, siteSlug: string) =>
-    queryPublishedSite(organizationSlug, siteSlug),
-  ["published-site-resolution-v1"],
-  { revalidate: 30 },
-);
+// The site record contains the mutable live-release pointer. Do not cache
+// this lookup: publication and unpublish happen in Convex and cannot
+// invalidate Next.js's data cache. The immutable release reads below are
+// still cached by release ID.
+const queryPublicPublishedSite = (organizationSlug: string, siteSlug: string) =>
+  queryPublishedSite(organizationSlug, siteSlug);
 
 async function queryReleasePage(
   releaseId: Id<"siteReleases">,
@@ -101,22 +101,19 @@ const queryPublicReleaseLibraries = unstable_cache(
   ["published-release-libraries-v2"],
 );
 
-const queryCustomDomain = unstable_cache(
-  (hostname: string) =>
-    getServerConvexClient().query(api.siteDomains.resolve, { hostname }),
-  ["published-custom-domain"],
-  { revalidate: 300 },
-);
+// Domain resolution also depends on the site's mutable live-release pointer.
+// Keep it request-current so unpublish takes effect immediately on custom
+// domains as well as subdomain routes.
+const queryCustomDomain = (hostname: string) =>
+  getServerConvexClient().query(api.siteDomains.resolve, { hostname });
 
-const queryPublishedSitemap = unstable_cache(
-  (organizationSlug: string, siteSlug?: string) =>
-    getServerConvexClient().query(api.published.sitemap, {
-      organizationSlug,
-      siteSlug,
-    }),
-  ["published-sitemap"],
-  { revalidate: 300 },
-);
+// Sitemap entries also depend on each site's mutable live-release pointer.
+// Keep this lookup request-current for the same reason as site resolution.
+const queryPublishedSitemap = (organizationSlug: string, siteSlug?: string) =>
+  getServerConvexClient().query(api.published.sitemap, {
+    organizationSlug,
+    siteSlug,
+  });
 
 type PublishedSiteResolution = NonNullable<
   Awaited<ReturnType<typeof queryPublishedSite>>
diff --git a/docs/publishing-migration.md b/docs/publishing-migration.md
new file mode 100644
index 00000000..70e17aff
--- /dev/null
+++ b/docs/publishing-migration.md
@@ -0,0 +1,60 @@
+# Publication manifest migration
+
+`publicationMigrations` backfills data required by the atomic publication
+path. It is resumable and supports `dryRun` and `apply` modes.
+
+The migration processes these phases in order:
+
+1. Add `searchText` to historical content revisions.
+2. Add bounded `description` values to release pages.
+3. Capture immutable `extractedText` on historical release files.
+4. Add `releaseId` to legacy release search entries.
+5. Rebuild the live search scope for every currently live site.
+
+The migration does not delete legacy fields or old per-release search entries.
+Those are removed only after every environment has been migrated and verified.
+
+## Run a preview migration
+
+Run these commands from `packages/backend` against the Convex deployment used by
+the preview deployment. Use a unique run ID for each mode.
+
+```sh
+bunx convex run --deployment <preview-deployment> publicationMigrations:runBatch \
+  '{"runId":"publication-preview-dry-YYYYMMDD","mode":"dryRun"}'
+
+bunx convex run --deployment <preview-deployment> publicationMigrations:getReport \
+  '{"runId":"publication-preview-dry-YYYYMMDD"}'
+```
+
+Wait for `status` to become `completed`. Apply only when the dry run reports
+`errorCount: 0`. `migratedCount` counts records that need backfilling;
+`scheduledCount` counts live-search rebuilds that will be scheduled.
+
+```sh
+bunx convex run --deployment <preview-deployment> publicationMigrations:runBatch \
+  '{"runId":"publication-preview-apply-YYYYMMDD","mode":"apply"}'
+
+bunx convex run --deployment <preview-deployment> publicationMigrations:getReport \
+  '{"runId":"publication-preview-apply-YYYYMMDD"}'
+```
+
+The batch function schedules its next batch automatically. A repeated command
+with the same completed run ID is an idempotent no-op.
+
+After the apply run completes, verify that revisions, release pages, release
+files, and release search entries have the new fields. Also wait for every
+scheduled live-search projection to finish before testing published search.
+
+## Production gate
+
+Before applying in production:
+
+1. Take and verify a Convex backup.
+2. Run the production dry run.
+3. Investigate every migration error.
+4. Record the dry-run report.
+5. Apply the migration only after the preview verification passes.
+
+Do not remove compatibility code until all environments have completed the
+backfill and the old record shapes have been separately audited.
diff --git a/packages/backend/convex/_generated/api.d.ts b/packages/backend/convex/_generated/api.d.ts
index 5b191b33..9354db65 100644
--- a/packages/backend/convex/_generated/api.d.ts
+++ b/packages/backend/convex/_generated/api.d.ts
@@ -65,6 +65,8 @@ import type * as pageContentFormat from "../pageContentFormat.js";
 import type * as pageGuests from "../pageGuests.js";
 import type * as pages from "../pages.js";
 import type * as permissions from "../permissions.js";
+import type * as publication from "../publication.js";
+import type * as publicationMigrations from "../publicationMigrations.js";
 import type * as published from "../published.js";
 import type * as releasePublication from "../releasePublication.js";
 import type * as releases from "../releases.js";
@@ -154,6 +156,8 @@ declare const fullApi: ApiFromModules<{
   pageGuests: typeof pageGuests;
   pages: typeof pages;
   permissions: typeof permissions;
+  publication: typeof publication;
+  publicationMigrations: typeof publicationMigrations;
   published: typeof published;
   releasePublication: typeof releasePublication;
   releases: typeof releases;
diff --git a/packages/backend/convex/draftRestore.test.ts b/packages/backend/convex/draftRestore.test.ts
index c399bbb2..cfbdb26e 100644
--- a/packages/backend/convex/draftRestore.test.ts
+++ b/packages/backend/convex/draftRestore.test.ts
@@ -5,6 +5,7 @@ import { publish } from "./releases";
 import { restore, resume } from "./draftRestores";
 import { list as listPages } from "./pages";
 import { draftRestoreView } from "./editorWorkspace";
+import { getEffectiveDraftRestoreStatus } from "./draftRestores";
 
 type RegisteredFunction = {
   _handler: (ctx: unknown, args: unknown) => Promise<unknown>;
@@ -36,7 +37,6 @@ describe("draft restore ownership", () => {
     const release = {
       _id: activeRestore.releaseId,
       siteId: activeRestore.siteId,
-      publicationStatus: "complete",
     };
     const site = {
       _id: activeRestore.siteId,
@@ -163,6 +163,31 @@ describe("draft restore read gating", () => {
       failure: expect.stringContaining("remains locked"),
     });
   });
+
+  test("projects a failed applying workflow as a resumable paused restore", async () => {
+    const restore = {
+      ...activeRestore,
+      status: "applying" as const,
+      workflowId: "workflow-1",
+    };
+    const result = await getEffectiveDraftRestoreStatus(
+      {
+        runQuery: async () => ({
+          workflow: {
+            runResult: { kind: "failed", error: "transient failure" },
+          },
+          inProgress: [],
+          logLevel: "INFO",
+        }),
+      } as never,
+      restore as never,
+    );
+    expect(result).toEqual({
+      status: "paused",
+      failure: "transient failure",
+      resultDraftRevision: undefined,
+    });
+  });
 });
 
 describe("draft restore workflow", () => {
@@ -216,6 +241,72 @@ describe("draft restore workflow", () => {
     ).rejects.toThrow("content payload is missing");
   });
 
+  test("preflight rejects malformed historical page content before applying it", async () => {
+    const restore = {
+      ...activeRestore,
+      status: "validating" as const,
+      phase: "validatePages" as const,
+    };
+    const site = {
+      _id: restore.siteId,
+      activeDraftRestoreId: restore._id,
+      draftRevision: restore.baseDraftRevision,
+    };
+    const snapshot = {
+      pageId: "page-1",
+      contentRevisionId: "revision-1",
+    };
+    const revision = {
+      _id: snapshot.contentRevisionId,
+      siteId: restore.siteId,
+      payloadId: "payload-1",
+    };
+    const ctx = {
+      db: {
+        get: async (id: string) => {
+          if (id === restore._id) return restore;
+          if (id === site._id) return site;
+          if (id === snapshot.pageId)
+            return { _id: id, siteId: restore.siteId };
+          if (id === revision._id) return revision;
+          if (id === revision.payloadId) {
+            return {
+              _id: id,
+              siteId: restore.siteId,
+              content: {
+                type: "doc",
+                version: 1,
+                content: [
+                  {
+                    type: "unknownHistoricalNode",
+                    attrs: { "openeditor-id": "bad-1" },
+                  },
+                ],
+              },
+            };
+          }
+          return null;
+        },
+        query: () => ({
+          withIndex: () => ({
+            paginate: async () => ({
+              page: [snapshot],
+              isDone: true,
+              continueCursor: "",
+            }),
+          }),
+        }),
+      },
+    };
+
+    await expect(
+      invoke(applyBatch, ctx, {
+        restoreId: restore._id,
+        phase: restore.phase,
+      }),
+    ).rejects.toThrow("Unknown node type");
+  });
+
   test("activation changes the draft pointer but never the live release", async () => {
     const restore = {
       ...activeRestore,
@@ -351,4 +442,60 @@ describe("draft restore workflow", () => {
       expect.objectContaining({ workflowId: restore.workflowId }),
     ]);
   });
+
+  test("resume accepts an applying restore whose workflow failure is projected as paused", async () => {
+    const restore = {
+      ...activeRestore,
+      status: "applying" as const,
+      workflowId: "workflow-1",
+    };
+    const site = {
+      _id: restore.siteId,
+      organizationId: "organization-1",
+      activeDraftRestoreId: restore._id,
+    };
+    const patches: Array<Record<string, unknown>> = [];
+    const mutations: Array<Record<string, unknown>> = [];
+    let queryCount = 0;
+    const ctx = {
+      auth: {
+        getUserIdentity: async () => ({ subject: restore.requestedBy }),
+      },
+      runQuery: async () => {
+        queryCount += 1;
+        if (queryCount === 1) {
+          return {
+            _id: "member-1",
+            organizationId: site.organizationId,
+            role: "owner",
+            userId: restore.requestedBy,
+          };
+        }
+        return {
+          workflow: {
+            runResult: { kind: "failed", error: "transient failure" },
+          },
+          inProgress: [],
+          logLevel: "INFO",
+        };
+      },
+      runMutation: async (_fn: unknown, args: Record<string, unknown>) => {
+        mutations.push(args);
+      },
+      db: {
+        get: async (id: string) => (id === restore._id ? restore : site),
+        patch: async (_id: string, value: Record<string, unknown>) => {
+          patches.push(value);
+        },
+      },
+    };
+
+    await invoke(resume, ctx, { restoreId: restore._id });
+    expect(patches).toContainEqual(
+      expect.objectContaining({ status: "applying", failure: undefined }),
+    );
+    expect(mutations).toEqual([
+      expect.objectContaining({ workflowId: restore.workflowId }),
+    ]);
+  });
 });
diff --git a/packages/backend/convex/draftRestores.ts b/packages/backend/convex/draftRestores.ts
index e0d151c8..c2877fd5 100644
--- a/packages/backend/convex/draftRestores.ts
+++ b/packages/backend/convex/draftRestores.ts
@@ -7,8 +7,10 @@ import {
 } from "@convex-dev/workflow";
 import { ConvexError, v } from "convex/values";
 import { components, internal } from "./_generated/api";
+import type { Doc } from "./_generated/dataModel";
 import { mutation, query } from "./_generated/server";
-import { findActivePublication } from "./model/releaseOperations";
+import type { QueryCtx } from "./_generated/server";
+import { isReleaseAvailable } from "./model/releaseState";
 import {
   isOrganizationMember,
   requireOrganizationPermission,
@@ -27,8 +29,8 @@ export const restore = mutation({
       site.organizationId,
       { resource: "content", action: "edit" },
     );
-    if (release.publicationStatus !== "complete") {
-      throw new ConvexError("Release publication is not complete");
+    if (!isReleaseAvailable(release)) {
+      throw new ConvexError("Release is not available for restore");
     }
     if (site.activeDraftRestoreId) {
       const active = await ctx.db.get(site.activeDraftRestoreId);
@@ -42,11 +44,6 @@ export const restore = mutation({
       }
       throw new ConvexError("Another draft restore is already in progress");
     }
-    if (await findActivePublication(ctx, site._id)) {
-      throw new ConvexError(
-        "A publication is still finishing. Try restoring when it completes.",
-      );
-    }
     const now = Date.now();
     const restoreId = await ctx.db.insert("draftRestores", {
       siteId: site._id,
@@ -57,18 +54,70 @@ export const restore = mutation({
       createdAt: now,
       updatedAt: now,
     });
-    const workflowId = await start(
-      ctx,
-      internal.draftRestore.run,
-      { restoreId },
-      { startAsync: true },
-    );
-    await ctx.db.patch(restoreId, { workflowId });
     await ctx.db.patch(site._id, { activeDraftRestoreId: restoreId });
+
+    try {
+      const workflowId = await start(
+        ctx,
+        internal.draftRestore.run,
+        { restoreId },
+        { startAsync: true },
+      );
+      await ctx.db.patch(restoreId, { workflowId });
+    } catch (error) {
+      // Do not leave a site locked when the workflow component cannot start.
+      // The restore row remains as an auditable failed attempt and a later
+      // request can create a fresh restore.
+      await ctx.db.patch(site._id, { activeDraftRestoreId: undefined });
+      await ctx.db.patch(restoreId, {
+        status: "failed",
+        failure: formatRestoreFailure(error),
+        completedAt: Date.now(),
+        updatedAt: Date.now(),
+      });
+      throw error;
+    }
     return { restoreId, reused: false };
   },
 });
 
+function formatRestoreFailure(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error))
+    .replaceAll(/[\r\n\t]+/gu, " ")
+    .slice(0, 300);
+}
+
+export async function getEffectiveDraftRestoreStatus(
+  ctx: QueryCtx,
+  restore: Doc<"draftRestores">,
+) {
+  if (
+    restore.workflowId &&
+    (restore.status === "validating" || restore.status === "applying")
+  ) {
+    const workflowStatus = await getStatus(
+      ctx,
+      components.workflow,
+      restore.workflowId as WorkflowId,
+    );
+    if (workflowStatus.type === "failed") {
+      return {
+        status:
+          restore.status === "validating"
+            ? ("failed" as const)
+            : ("paused" as const),
+        failure: workflowStatus.error,
+        resultDraftRevision: restore.resultDraftRevision,
+      };
+    }
+  }
+  return {
+    status: restore.status,
+    failure: restore.failure,
+    resultDraftRevision: restore.resultDraftRevision,
+  };
+}
+
 export const status = query({
   args: { restoreId: v.id("draftRestores") },
   returns: v.union(
@@ -93,31 +142,7 @@ export const status = query({
     if (!site || !(await isOrganizationMember(ctx, site.organizationId))) {
       return null;
     }
-    if (
-      restore.workflowId &&
-      (restore.status === "validating" || restore.status === "applying")
-    ) {
-      const workflowStatus = await getStatus(
-        ctx,
-        components.workflow,
-        restore.workflowId as WorkflowId,
-      );
-      if (workflowStatus.type === "failed") {
-        return {
-          status:
-            restore.status === "validating"
-              ? ("failed" as const)
-              : ("paused" as const),
-          failure: workflowStatus.error,
-          resultDraftRevision: restore.resultDraftRevision,
-        };
-      }
-    }
-    return {
-      status: restore.status,
-      failure: restore.failure,
-      resultDraftRevision: restore.resultDraftRevision,
-    };
+    return getEffectiveDraftRestoreStatus(ctx, restore);
   },
 });
 
@@ -138,7 +163,7 @@ export const resume = mutation({
       action: "edit",
     });
     if (
-      restore.status !== "paused" ||
+      (restore.status !== "paused" && restore.status !== "applying") ||
       !restore.workflowId ||
       site.activeDraftRestoreId !== restore._id
     ) {
diff --git a/packages/backend/convex/editorWorkspace.ts b/packages/backend/convex/editorWorkspace.ts
index e789952e..25921033 100644
--- a/packages/backend/convex/editorWorkspace.ts
+++ b/packages/backend/convex/editorWorkspace.ts
@@ -5,6 +5,7 @@ import type { Doc, Id } from "./_generated/dataModel";
 import { buildDraftSummary } from "./model/draftSummary";
 import { readPageContent } from "./model/pageDocuments";
 import { hashOpenEditorContent } from "./pageContentFormat";
+import { getEffectiveDraftRestoreStatus } from "./draftRestores";
 
 export function draftRestoreView(
   restoreId: Id<"draftRestores">,
@@ -44,6 +45,9 @@ export const get = query({
 
     if (site.activeDraftRestoreId) {
       const restore = await ctx.db.get(site.activeDraftRestoreId);
+      const restoreStatus = restore
+        ? await getEffectiveDraftRestoreStatus(ctx, restore)
+        : null;
       return {
         status: "restoring" as const,
         site,
@@ -51,7 +55,13 @@ export const get = query({
         selectedPage: null,
         selectedDocument: null,
         draftSummary,
-        restore: draftRestoreView(site.activeDraftRestoreId, restore),
+        restore: restore
+          ? {
+              _id: restore._id,
+              status: restoreStatus?.status ?? restore.status,
+              failure: restoreStatus?.failure ?? restore.failure,
+            }
+          : draftRestoreView(site.activeDraftRestoreId, null),
       };
     }
 
diff --git a/packages/backend/convex/files.ts b/packages/backend/convex/files.ts
index ff958157..b47d1a33 100644
--- a/packages/backend/convex/files.ts
+++ b/packages/backend/convex/files.ts
@@ -25,6 +25,7 @@ import {
 } from "./search";
 import { recordStorageUsageEvent } from "./model/storageTelemetry";
 import { pendingSiteAssetLifecycle } from "./model/siteAssets";
+import { isReleaseAvailable } from "./model/releaseState";
 
 async function isFileReferencedByAccessiblePage(
   ctx: Parameters<typeof getPageAccessOrNull>[0],
@@ -178,10 +179,12 @@ export const getPublic = query({
     if (!file) return null;
     const site = await ctx.db.get(file.siteId);
     if (!site?.liveReleaseId || !isPubliclyPublishedSite(site)) return null;
+    const release = await ctx.db.get(site.liveReleaseId);
+    if (!release || !isReleaseAvailable(release)) return null;
     const snapshot = await ctx.db
       .query("releaseFiles")
       .withIndex("by_release_file", (q) =>
-        q.eq("releaseId", site.liveReleaseId!).eq("fileId", file._id),
+        q.eq("releaseId", release._id).eq("fileId", file._id),
       )
       .unique();
     return snapshot
@@ -204,12 +207,16 @@ export const getAuthorized = query({
     if (!file) return null;
     const site = await ctx.db.get(file.siteId);
     if (!site) return null;
+    const liveRelease = site.liveReleaseId
+      ? await ctx.db.get(site.liveReleaseId)
+      : null;
     const released =
-      site.liveReleaseId &&
+      liveRelease &&
+      isReleaseAvailable(liveRelease) &&
       (await ctx.db
         .query("releaseFiles")
         .withIndex("by_release_file", (q) =>
-          q.eq("releaseId", site.liveReleaseId!).eq("fileId", file._id),
+          q.eq("releaseId", liveRelease._id).eq("fileId", file._id),
         )
         .unique());
     if (file.kind === "siteAsset") {
@@ -222,6 +229,9 @@ export const getAuthorized = query({
         ? false
         : await isFileReferencedByAccessiblePage(ctx, file);
       if (!canManage && !guestReference) return null;
+      if (site.visibility === "public" && !canManage && !released) {
+        return null;
+      }
       if (!released) assertDraftReadable(site);
       return released
         ? {
@@ -238,6 +248,7 @@ export const getAuthorized = query({
     if (!member && !(await isFileReferencedByAccessiblePage(ctx, file))) {
       return null;
     }
+    if (site.visibility === "public" && !member && !released) return null;
     if (!released) assertDraftReadable(site);
     return released
       ? {
diff --git a/packages/backend/convex/libraries.ts b/packages/backend/convex/libraries.ts
index 679af836..d097e740 100644
--- a/packages/backend/convex/libraries.ts
+++ b/packages/backend/convex/libraries.ts
@@ -14,6 +14,7 @@ import {
   requireLibraryManagement,
 } from "./model/libraryAccess";
 import { assertDraftReadable, touchSiteDraft } from "./model/draft";
+import { isReleaseAvailable } from "./model/releaseState";
 
 const librarySummary = v.object({
   _id: v.id("documentLibraries"),
@@ -250,7 +251,7 @@ export const getPublishedExplorer = query({
     const access = await resolvePublishedSiteAccess(ctx, site);
     if (!canRenderPublishedSite(access)) return null;
     const release = await ctx.db.get(site.liveReleaseId);
-    if (!release) return null;
+    if (!release || !isReleaseAvailable(release)) return null;
     const releasedLibrary = await ctx.db
       .query("releaseLibraries")
       .withIndex("by_release_library", (q) =>
diff --git a/packages/backend/convex/model/contentObjects.test.ts b/packages/backend/convex/model/contentObjects.test.ts
new file mode 100644
index 00000000..821dea4a
--- /dev/null
+++ b/packages/backend/convex/model/contentObjects.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { readContentRevisionSearchText } from "./contentObjects";
+
+describe("content revision search text", () => {
+  test("rebuilds missing search text for revisions written before the field existed", async () => {
+    const revision = {
+      _id: "revision-1",
+      payloadId: "payload-1",
+      searchText: undefined,
+    };
+    const payload = {
+      _id: "payload-1",
+      content: {
+        type: "doc",
+        version: 1,
+        content: [
+          {
+            type: "paragraph",
+            attrs: { "openeditor-id": "paragraph-1" },
+            content: [{ type: "text", text: "Legacy searchable content" }],
+          },
+        ],
+      },
+    };
+
+    const result = await readContentRevisionSearchText(
+      {
+        db: {
+          get: async (id: string) =>
+            id === revision._id
+              ? revision
+              : id === payload._id
+                ? payload
+                : null,
+        },
+      } as never,
+      revision._id as never,
+    );
+
+    expect(result).toContain("Legacy searchable content");
+  });
+});
diff --git a/packages/backend/convex/model/contentObjects.ts b/packages/backend/convex/model/contentObjects.ts
index 44c11180..97f1bff0 100644
--- a/packages/backend/convex/model/contentObjects.ts
+++ b/packages/backend/convex/model/contentObjects.ts
@@ -2,12 +2,37 @@ import type { GenericMutationCtx } from "convex/server";
 import type { DataModel, Id } from "../_generated/dataModel";
 import {
   extractOpenEditorReferences,
+  extractOpenEditorText,
+  parseOpenEditorDocument,
   type OpenEditorDocument,
 } from "../pageContentFormat";
 import { recordStorageUsageEvent } from "./storageTelemetry";
 
 type MutationCtx = Pick<GenericMutationCtx<DataModel>, "db">;
 
+/**
+ * Reads the denormalized text when present and rebuilds it for content
+ * revisions written before `searchText` was added to the schema.
+ */
+export async function readContentRevisionSearchText(
+  ctx: MutationCtx,
+  revisionId: Id<"contentRevisions"> | undefined,
+): Promise<string> {
+  if (!revisionId) return "";
+  const revision = await ctx.db.get(revisionId);
+  if (!revision) return "";
+  if (revision.searchText !== undefined) return revision.searchText;
+  const payload = await ctx.db.get(revision.payloadId);
+  if (!payload) return "";
+  try {
+    return extractOpenEditorText(parseOpenEditorDocument(payload.content));
+  } catch {
+    // Search is a derived projection. Omit malformed historical content here;
+    // publication validates legacy payloads before activation.
+    return "";
+  }
+}
+
 export async function getOrCreateContentObject(
   ctx: MutationCtx,
   value: {
@@ -70,6 +95,7 @@ export async function getOrCreateContentObject(
     contentHash: value.contentHash,
     contentSize: value.contentSize,
     payloadId,
+    searchText: extractOpenEditorText(value.document),
     libraryIds,
     fileIds,
     pageIds,
diff --git a/packages/backend/convex/model/draftSummary.ts b/packages/backend/convex/model/draftSummary.ts
index dfbb0534..af33526d 100644
--- a/packages/backend/convex/model/draftSummary.ts
+++ b/packages/backend/convex/model/draftSummary.ts
@@ -1,10 +1,16 @@
 import type { Doc } from "../_generated/dataModel";
 import type { QueryCtx } from "../_generated/server";
+import { isReleaseAvailable } from "./releaseState";
 
 export async function buildDraftSummary(ctx: QueryCtx, site: Doc<"sites">) {
-  const liveRelease = site.liveReleaseId
+  const liveReleaseCandidate = site.liveReleaseId
     ? await ctx.db.get(site.liveReleaseId)
     : null;
+  const liveRelease =
+    liveReleaseCandidate?.siteId === site._id &&
+    isReleaseAvailable(liveReleaseCandidate)
+      ? liveReleaseCandidate
+      : null;
   const hasDraftChanges =
     (await ctx.db
       .query("draftChanges")
diff --git a/packages/backend/convex/model/publishedRelease.ts b/packages/backend/convex/model/publishedRelease.ts
index ef0fe03c..57212109 100644
--- a/packages/backend/convex/model/publishedRelease.ts
+++ b/packages/backend/convex/model/publishedRelease.ts
@@ -1,5 +1,6 @@
 import type { Doc, Id } from "../_generated/dataModel";
 import type { QueryCtx } from "../_generated/server";
+import { isReleaseAvailable } from "./releaseState";
 import { canRenderPublishedSite, resolvePublishedSiteAccess } from "../sharing";
 
 export type ResolvedReleasePage = {
@@ -100,7 +101,7 @@ export async function getReadableLiveRelease(
   releaseId: Id<"siteReleases">,
 ) {
   const release = await ctx.db.get(releaseId);
-  if (!release) return null;
+  if (!release || !isReleaseAvailable(release)) return null;
   const site = await ctx.db.get(release.siteId);
   if (!site || site.liveReleaseId !== release._id) return null;
   const access = await resolvePublishedSiteAccess(ctx, site);
diff --git a/packages/backend/convex/model/releaseChangeDetails.ts b/packages/backend/convex/model/releaseChangeDetails.ts
index 9d9b32cc..7d5da2b9 100644
--- a/packages/backend/convex/model/releaseChangeDetails.ts
+++ b/packages/backend/convex/model/releaseChangeDetails.ts
@@ -64,11 +64,18 @@ export async function buildReleaseChangeDetail(
         ])
       : [null, null, null];
     const active = current?.deletedAt === undefined ? current : null;
-    const [before, after] = await Promise.all([
-      revisionContent(ctx, base?.contentRevisionId),
-      revisionContent(ctx, active ? currentDocument?.revisionId : undefined),
-    ]);
-    const contentChanged = currentDocument?.contentHash !== base?.contentHash;
+    const contentChanged =
+      currentDocument?.contentHash !== base?.contentHash ||
+      (active === null && base?.contentRevisionId !== undefined);
+    const [before, after] = contentChanged
+      ? await Promise.all([
+          revisionContent(ctx, base?.contentRevisionId),
+          revisionContent(
+            ctx,
+            active ? currentDocument?.revisionId : undefined,
+          ),
+        ])
+      : [undefined, undefined];
     return {
       fields: compact([
         changedField("Title", base?.title, active?.title),
diff --git a/packages/backend/convex/model/releaseOperations.ts b/packages/backend/convex/model/releaseOperations.ts
index b9bcbedb..0350ddeb 100644
--- a/packages/backend/convex/model/releaseOperations.ts
+++ b/packages/backend/convex/model/releaseOperations.ts
@@ -1,26 +1,7 @@
-import type { Doc, Id } from "../_generated/dataModel";
+import type { Doc } from "../_generated/dataModel";
 import type { MutationCtx } from "../_generated/server";
 import { publicationActionForTarget } from "./releaseState";
 
-const activePublicationStatuses = ["building", "clearing"] as const;
-
-export async function findActivePublication(
-  ctx: MutationCtx,
-  siteId: Id<"sites">,
-) {
-  const releases = await Promise.all(
-    activePublicationStatuses.map((status) =>
-      ctx.db
-        .query("siteReleases")
-        .withIndex("by_site_publication_status", (q) =>
-          q.eq("siteId", siteId).eq("publicationStatus", status),
-        )
-        .first(),
-    ),
-  );
-  return releases.find((release) => release !== null) ?? null;
-}
-
 export async function promoteRelease(
   ctx: MutationCtx,
   site: Doc<"sites">,
@@ -31,9 +12,12 @@ export async function promoteRelease(
     ? await ctx.db.get(site.liveReleaseId)
     : null;
   const now = Date.now();
+  const liveSearchProjectionGeneration =
+    (site.liveSearchProjectionGeneration ?? 0) + 1;
   await ctx.db.patch(site._id, {
     liveReleaseId: release._id,
     updatedAt: now,
+    liveSearchProjectionGeneration,
   });
   await ctx.db.insert("publicationEvents", {
     siteId: site._id,
@@ -43,4 +27,5 @@ export async function promoteRelease(
     actorId,
     createdAt: now,
   });
+  return liveSearchProjectionGeneration;
 }
diff --git a/packages/backend/convex/model/releaseState.test.ts b/packages/backend/convex/model/releaseState.test.ts
index cfdb8ada..8422e5e1 100644
--- a/packages/backend/convex/model/releaseState.test.ts
+++ b/packages/backend/convex/model/releaseState.test.ts
@@ -1,9 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import {
   extractionBlocksPublication,
-  extractionIsPublishable,
   extractionRetryInvalidatesDraft,
-  isPublicationInFlight,
+  isReleaseAvailable,
   publicationActionForTarget,
 } from "./releaseState";
 
@@ -21,14 +20,7 @@ describe("release promotion", () => {
   });
 });
 
-describe("release publication state machine", () => {
-  test("treats snapshot building and draft cleanup as nonterminal", () => {
-    expect(isPublicationInFlight("building")).toBe(true);
-    expect(isPublicationInFlight("clearing")).toBe(true);
-    expect(isPublicationInFlight("complete")).toBe(false);
-    expect(isPublicationInFlight("failed")).toBe(false);
-  });
-
+describe("release publication guards", () => {
   test("blocks only while document extraction is incomplete", () => {
     expect(extractionBlocksPublication("queued")).toBe(true);
     expect(extractionBlocksPublication("processing")).toBe(true);
@@ -43,22 +35,11 @@ describe("release publication state machine", () => {
     expect(extractionRetryInvalidatesDraft("processing")).toBe(false);
   });
 
-  test("publishes only terminal extraction state for the current source", () => {
-    expect(extractionIsPublishable(null, "v1")).toBe(false);
-    expect(
-      extractionIsPublishable({ sourceVersion: "v0", status: "ready" }, "v1"),
-    ).toBe(false);
-    expect(
-      extractionIsPublishable(
-        { sourceVersion: "v1", status: "processing" },
-        "v1",
-      ),
-    ).toBe(false);
-    expect(
-      extractionIsPublishable({ sourceVersion: "v1", status: "ready" }, "v1"),
-    ).toBe(true);
-    expect(
-      extractionIsPublishable({ sourceVersion: "v1", status: "failed" }, "v1"),
-    ).toBe(true);
+  test("keeps atomic and completed legacy releases readable", () => {
+    expect(isReleaseAvailable({})).toBe(true);
+    expect(isReleaseAvailable({ publicationStatus: "complete" })).toBe(true);
+    expect(isReleaseAvailable({ publicationStatus: "clearing" })).toBe(true);
+    expect(isReleaseAvailable({ publicationStatus: "building" })).toBe(false);
+    expect(isReleaseAvailable({ publicationStatus: "failed" })).toBe(false);
   });
 });
diff --git a/packages/backend/convex/model/releaseState.ts b/packages/backend/convex/model/releaseState.ts
index 869adece..50697c13 100644
--- a/packages/backend/convex/model/releaseState.ts
+++ b/packages/backend/convex/model/releaseState.ts
@@ -1,3 +1,5 @@
+import type { Doc } from "../_generated/dataModel";
+
 export function publicationActionForTarget(
   currentNumber: number | undefined,
   targetNumber: number,
@@ -9,6 +11,7 @@ export function publicationActionForTarget(
 
 export type PublicationStatus = "building" | "clearing" | "complete" | "failed";
 
+/** Compatibility state helpers for releases created by the retired workflow. */
 export function isPublicationInFlight(
   status: PublicationStatus | undefined,
 ): boolean {
@@ -42,3 +45,17 @@ export function extractionIsPublishable(
     (extraction.status === "ready" || extraction.status === "failed")
   );
 }
+
+/**
+ * Old releases may still carry a publication workflow status. New releases
+ * activate atomically and have no status, so an absent status is readable.
+ */
+export function isReleaseAvailable(
+  release: Pick<Doc<"siteReleases">, "publicationStatus">,
+): boolean {
+  return (
+    release.publicationStatus === undefined ||
+    release.publicationStatus === "complete" ||
+    release.publicationStatus === "clearing"
+  );
+}
diff --git a/packages/backend/convex/publication.test.ts b/packages/backend/convex/publication.test.ts
new file mode 100644
index 00000000..63d6a6f4
--- /dev/null
+++ b/packages/backend/convex/publication.test.ts
@@ -0,0 +1,757 @@
+import { describe, expect, test } from "bun:test";
+import {
+  getDraftReferencedFileIds,
+  projectLiveSearch,
+  projectLiveSearchBatch,
+  snapshotFiles,
+  truncateDescription,
+} from "./publication";
+import { buildReleaseChangeDetail } from "./model/releaseChangeDetails";
+import { publish } from "./releases";
+
+type RegisteredFunction = {
+  _handler: (ctx: unknown, args: unknown) => Promise<unknown>;
+};
+
+function invoke(fn: unknown, ctx: unknown, args: unknown): Promise<unknown> {
+  return (fn as RegisteredFunction)._handler(ctx, args);
+}
+
+type Row = Record<string, unknown> & { _id: string };
+
+/**
+ * Minimal in-memory Convex db covering the access patterns the publish
+ * transaction uses: point reads/writes and indexed queries consumed
+ * through unique/first/collect/async-iteration.
+ */
+function makeDb(tables: Record<string, Row[]>) {
+  const inserted: Array<{ table: string; value: Record<string, unknown> }> = [];
+  const patches: Array<[string, Record<string, unknown>]> = [];
+  const deletes: string[] = [];
+  let nextId = 1;
+  const idFor = (row: Row) => row._id;
+  const results = (table: string, filter: (row: Row) => boolean) => {
+    const rows = () => (tables[table] ?? []).filter(filter);
+    const builder = {
+      unique: async () => {
+        const all = rows();
+        if (all.length > 1) throw new Error("expected unique");
+        return all[0] ?? null;
+      },
+      first: async () => rows()[0] ?? null,
+      collect: async () => rows(),
+      order: () => builder,
+      paginate: async () => ({
+        page: rows(),
+        isDone: true,
+        continueCursor: "",
+      }),
+      [Symbol.asyncIterator]: async function* () {
+        for (const row of rows()) yield row;
+      },
+    };
+    return builder;
+  };
+  return {
+    inserted,
+    patches,
+    deletes,
+    db: {
+      get: async (id: string) => {
+        for (const rows of Object.values(tables)) {
+          const row = rows.find((candidate) => candidate._id === id);
+          if (row) return row;
+        }
+        return null;
+      },
+      insert: async (table: string, value: Record<string, unknown>) => {
+        const id = `${table}:${nextId++}`;
+        const rows = tables[table] ?? [];
+        rows.push({ ...value, _id: id } as Row);
+        tables[table] = rows;
+        inserted.push({ table, value });
+        return id;
+      },
+      patch: async (id: string, value: Record<string, unknown>) => {
+        for (const rows of Object.values(tables)) {
+          const row = rows.find((candidate) => candidate._id === id);
+          if (row) Object.assign(row, value);
+        }
+        patches.push([id, value]);
+      },
+      replace: async (id: string, value: Record<string, unknown>) => {
+        for (const rows of Object.values(tables)) {
+          const row = rows.find((candidate) => candidate._id === id);
+          if (row) {
+            for (const key of Object.keys(row)) delete row[key];
+            Object.assign(row, { ...value, _id: id });
+          }
+        }
+      },
+      delete: async (id: string) => {
+        for (const [table, rows] of Object.entries(tables)) {
+          const index = rows.findIndex((candidate) => candidate._id === id);
+          if (index >= 0) {
+            rows.splice(index, 1);
+            deletes.push(table);
+          }
+        }
+      },
+      query: (table: string) => ({
+        withIndex: (
+          _indexName: string,
+          resolve: (q: {
+            eq: (field: string, value: unknown) => unknown;
+          }) => unknown,
+        ) => {
+          const constraints: Array<[string, unknown]> = [];
+          const q = {
+            eq: (field: string, value: unknown) => {
+              constraints.push([field, value]);
+              return q;
+            },
+          };
+          resolve(q);
+          return results(table, (row) =>
+            constraints.every(([field, value]) => row[field] === value),
+          );
+        },
+      }),
+      normalizeId: (table: string, id: string) =>
+        (tables[table] ?? []).some((row) => row._id === id) ? id : null,
+    },
+    idFor,
+    results,
+    tables,
+  };
+}
+
+function memberCtx(db: unknown, userId: string) {
+  return {
+    auth: { getUserIdentity: async () => ({ subject: userId }) },
+    runQuery: async () => ({
+      _id: "member-1",
+      organizationId: "organization-1",
+      role: "owner",
+      userId,
+    }),
+    scheduler: {
+      runAfter: async () => null,
+    },
+    db,
+  };
+}
+
+async function runLiveSearchProjection(
+  state: ReturnType<typeof makeDb>,
+  args: Record<string, unknown>,
+) {
+  const scheduled: Array<Record<string, unknown>> = [];
+  const ctx = {
+    db: state.db,
+    scheduler: {
+      runAfter: async (
+        _delay: number,
+        _fn: unknown,
+        nextArgs: Record<string, unknown>,
+      ) => {
+        scheduled.push(nextArgs);
+      },
+    },
+  };
+  await invoke(projectLiveSearch, ctx, args);
+  while (scheduled.length > 0) {
+    const nextArgs = scheduled.shift();
+    if (nextArgs) await invoke(projectLiveSearchBatch, ctx, nextArgs);
+  }
+}
+
+describe("publish", () => {
+  test("re-promotes the base release when the draft has no pending changes", async () => {
+    const site: Row = {
+      _id: "site-1",
+      organizationId: "organization-1",
+      draftRevision: 3,
+      liveReleaseId: "release-old",
+      draftBaseReleaseId: "release-base",
+    };
+    const baseRelease: Row = {
+      _id: "release-base",
+      siteId: "site-1",
+      number: 2,
+    };
+    const state = makeDb({
+      sites: [site],
+      siteReleases: [baseRelease],
+      draftChanges: [],
+    });
+    let scheduled: unknown;
+    const ctx = {
+      ...memberCtx(state.db, "user-1"),
+      scheduler: {
+        runAfter: async (
+          _delay: number,
+          fn: unknown,
+          args: Record<string, unknown>,
+        ) => {
+          scheduled = { fn, args };
+        },
+      },
+    };
+    expect(
+      await invoke(publish, ctx, {
+        siteId: site._id,
+        expectedDraftRevision: 3,
+      }),
+    ).toEqual({ releaseId: "release-base", number: 2, reused: true });
+    expect(site.liveReleaseId).toBe("release-base");
+    expect(scheduled).toMatchObject({
+      args: { siteId: "site-1", expectedLiveReleaseId: "release-base" },
+    });
+  });
+
+  test("rejects publishing when the draft is already live", async () => {
+    const site: Row = {
+      _id: "site-1",
+      organizationId: "organization-1",
+      draftRevision: 3,
+      liveReleaseId: "release-base",
+      draftBaseReleaseId: "release-base",
+    };
+    const state = makeDb({
+      sites: [site],
+      siteReleases: [{ _id: "release-base", siteId: "site-1", number: 2 }],
+      draftChanges: [],
+    });
+    await expect(
+      invoke(publish, memberCtx(state.db, "user-1"), {
+        siteId: site._id,
+        expectedDraftRevision: 3,
+      }),
+    ).rejects.toThrow("already live");
+  });
+
+  test("builds the manifest, activates, and clears draft changes atomically", async () => {
+    const page: Row = {
+      _id: "page-1",
+      siteId: "site-1",
+      parentId: undefined,
+      title: "Home",
+      slug: "home",
+      icon: undefined,
+      order: 0,
+      updatedAt: 10,
+      deletedAt: undefined,
+    };
+    const document: Row = {
+      _id: "document-1",
+      siteId: "site-1",
+      pageId: "page-1",
+      revisionId: "revision-1",
+      contentHash: "hash-1",
+      updatedAt: 12,
+    };
+    const revision: Row = {
+      _id: "revision-1",
+      siteId: "site-1",
+      payloadId: "payload-1",
+      fileIds: [],
+      searchText: "Hello world",
+    };
+    const change: Row = {
+      _id: "change-1",
+      siteId: "site-1",
+      entityType: "page",
+      entityId: "page-1",
+      changeType: "updated",
+      label: "Home",
+      details: ["Content changed"],
+      draftRevision: 4,
+    };
+    const site: Row = {
+      _id: "site-1",
+      organizationId: "organization-1",
+      draftRevision: 4,
+      liveReleaseId: undefined,
+      draftBaseReleaseId: undefined,
+      activeDraftRestoreId: undefined,
+      defaultPageId: "page-1",
+      nextReleaseNumber: 5,
+      name: "Site",
+      settings: {},
+    };
+    const state = makeDb({
+      sites: [site],
+      pages: [page],
+      pageDocuments: [document],
+      contentRevisions: [revision],
+      contentPayloads: [
+        {
+          _id: "payload-1",
+          siteId: "site-1",
+          content: JSON.stringify({
+            type: "doc",
+            version: 1,
+            content: [
+              {
+                type: "paragraph",
+                attrs: { "openeditor-id": "paragraph-1" },
+              },
+            ],
+          }),
+        },
+      ],
+      draftChanges: [change],
+    });
+    const scheduled: Array<Record<string, unknown>> = [];
+    const ctx = {
+      ...memberCtx(state.db, "user-1"),
+      scheduler: {
+        runAfter: async (
+          _delay: number,
+          fn: unknown,
+          args: Record<string, unknown>,
+        ) => {
+          scheduled.push({ fn, args });
+        },
+      },
+    };
+    const result = (await invoke(publish, ctx, {
+      siteId: site._id,
+      expectedDraftRevision: 4,
+    })) as { releaseId: string; number: number; reused: boolean };
+    expect(result.reused).toBe(false);
+    expect(site.liveReleaseId).toBe(result.releaseId);
+    expect(site.draftBaseReleaseId).toBe(result.releaseId);
+    expect(site.nextReleaseNumber).toBe(6);
+
+    const releasePages = state.inserted.filter(
+      (row) => row.table === "releasePages",
+    );
+    expect(releasePages).toHaveLength(1);
+    expect(releasePages[0]?.value).toMatchObject({
+      pageId: "page-1",
+      title: "Home",
+      description: "Hello world",
+    });
+    const releaseChanges = state.inserted.filter(
+      (row) => row.table === "releaseChanges",
+    );
+    expect(releaseChanges).toHaveLength(1);
+    expect(state.deletes).toContain("draftChanges");
+    expect(scheduled).toHaveLength(1);
+    expect(scheduled[0]).toMatchObject({
+      args: {
+        siteId: "site-1",
+        expectedLiveReleaseId: result.releaseId,
+        expectedLiveSearchProjectionGeneration: 1,
+      },
+    });
+  });
+
+  test("rejects a stale draft revision before touching data", async () => {
+    const site: Row = {
+      _id: "site-1",
+      organizationId: "organization-1",
+      draftRevision: 7,
+      liveReleaseId: undefined,
+      draftBaseReleaseId: undefined,
+    };
+    const state = makeDb({ sites: [site], draftChanges: [] });
+    await expect(
+      invoke(publish, memberCtx(state.db, "user-1"), {
+        siteId: site._id,
+        expectedDraftRevision: 6,
+      }),
+    ).rejects.toThrow("draft changed while publishing");
+    expect(state.inserted).toHaveLength(0);
+  });
+
+  test("rejects malformed legacy page content before activation", async () => {
+    const site: Row = {
+      _id: "site-1",
+      organizationId: "organization-1",
+      draftRevision: 2,
+      liveReleaseId: undefined,
+      draftBaseReleaseId: undefined,
+      nextReleaseNumber: 1,
+      name: "Site",
+      settings: {},
+    };
+    const page: Row = {
+      _id: "page-1",
+      siteId: site._id,
+      title: "Home",
+      slug: "home",
+      order: 0,
+      updatedAt: 1,
+    };
+    const document: Row = {
+      _id: "document-1",
+      siteId: site._id,
+      pageId: page._id,
+      revisionId: "revision-1",
+      contentHash: "hash-1",
+      updatedAt: 1,
+    };
+    const revision: Row = {
+      _id: "revision-1",
+      siteId: site._id,
+      payloadId: "payload-1",
+    };
+    const state = makeDb({
+      sites: [site],
+      pages: [page],
+      pageDocuments: [document],
+      contentRevisions: [revision],
+      contentPayloads: [
+        {
+          _id: "payload-1",
+          siteId: site._id,
+          content: JSON.stringify({
+            type: "doc",
+            version: 1,
+            content: [{ type: "unknownHistoricalNode" }],
+          }),
+        },
+      ],
+      draftChanges: [],
+    });
+
+    await expect(
+      invoke(publish, memberCtx(state.db, "user-1"), {
+        siteId: site._id,
+        expectedDraftRevision: site.draftRevision,
+      }),
+    ).rejects.toThrow();
+    expect(site.liveReleaseId).toBeUndefined();
+  });
+
+  test("rejects publishing a site with no live pages", async () => {
+    const site: Row = {
+      _id: "site-1",
+      organizationId: "organization-1",
+      draftRevision: 1,
+      liveReleaseId: undefined,
+      draftBaseReleaseId: undefined,
+      nextReleaseNumber: 1,
+      name: "Site",
+      settings: {},
+    };
+    const state = makeDb({ sites: [site], draftChanges: [] });
+
+    await expect(
+      invoke(publish, memberCtx(state.db, "user-1"), {
+        siteId: site._id,
+        expectedDraftRevision: site.draftRevision,
+      }),
+    ).rejects.toThrow("at least one page");
+    expect(site.liveReleaseId).toBeUndefined();
+  });
+});
+
+describe("live search projection", () => {
+  test("uses the text captured by the released file instead of current extraction", async () => {
+    const site: Row = {
+      _id: "site-1",
+      liveReleaseId: "release-1",
+    };
+    const release: Row = {
+      _id: "release-1",
+      siteId: site._id,
+    };
+    const releasedFile: Row = {
+      _id: "release-file-1",
+      releaseId: release._id,
+      fileId: "file-1",
+      kind: "file",
+      filename: "guide.md",
+      extractedText: "released guide text",
+    };
+    const existingEntry: Row = {
+      _id: "search-1",
+      siteId: site._id,
+      scopeId: "live:site-1",
+      kind: "file",
+      sourceId: "file-1",
+      title: "guide.md",
+      text: "draft guide text",
+    };
+    const state = makeDb({
+      sites: [site],
+      siteReleases: [release],
+      releasePages: [],
+      releaseFiles: [releasedFile],
+      fileExtractions: [
+        {
+          _id: "extraction-1",
+          fileId: "file-1",
+          status: "ready",
+          extractedText: "newer draft extraction",
+        },
+      ],
+      searchEntries: [existingEntry],
+    });
+
+    await runLiveSearchProjection(state, {
+      siteId: site._id,
+      expectedLiveReleaseId: release._id,
+    });
+
+    expect(state.tables.searchEntries).toContainEqual(
+      expect.objectContaining({
+        sourceId: "file-1",
+        text: "released guide text",
+        releaseId: release._id,
+      }),
+    );
+  });
+
+  test("does not leak current extraction into a legacy release", async () => {
+    const site: Row = {
+      _id: "site-1",
+      liveReleaseId: "release-1",
+    };
+    const release: Row = {
+      _id: "release-1",
+      siteId: site._id,
+    };
+    const releasedFile: Row = {
+      _id: "release-file-1",
+      releaseId: release._id,
+      fileId: "file-1",
+      kind: "file",
+      objectKey: "files/old-guide.md",
+      filename: "guide.md",
+      size: 10,
+      checksum: "old-checksum",
+    };
+    const existingEntry: Row = {
+      _id: "search-1",
+      siteId: site._id,
+      scopeId: "live:site-1",
+      kind: "file",
+      sourceId: "file-1",
+      title: "guide.md",
+      text: "stale text",
+    };
+    const state = makeDb({
+      sites: [site],
+      siteReleases: [release],
+      releasePages: [],
+      releaseFiles: [releasedFile],
+      files: [
+        {
+          _id: "file-1",
+          kind: "file",
+          objectKey: "files/new-guide.md",
+          size: 12,
+          checksum: "new-checksum",
+        },
+      ],
+      fileExtractions: [
+        {
+          _id: "extraction-1",
+          fileId: "file-1",
+          status: "ready",
+          sourceVersion: "files/new-guide.md\u000012\u0000new-checksum",
+          extractedText: "current draft extraction",
+        },
+      ],
+      searchEntries: [existingEntry],
+    });
+
+    await runLiveSearchProjection(state, {
+      siteId: site._id,
+      expectedLiveReleaseId: release._id,
+    });
+
+    expect(state.tables.searchEntries).toContainEqual(
+      expect.objectContaining({
+        sourceId: "file-1",
+        text: "",
+      }),
+    );
+  });
+});
+
+describe("publication helpers", () => {
+  test("keeps content diff details when a page is deleted", async () => {
+    const site: Row = {
+      _id: "site-1",
+      draftBaseReleaseId: "release-base",
+    };
+    const state = makeDb({
+      sites: [site],
+      pages: [
+        {
+          _id: "page-1",
+          siteId: site._id,
+          title: "Removed page",
+          slug: "removed",
+          order: 0,
+          deletedAt: 1,
+        },
+      ],
+      pageDocuments: [
+        {
+          _id: "document-1",
+          siteId: site._id,
+          pageId: "page-1",
+          revisionId: "revision-1",
+          contentHash: "same-content",
+        },
+      ],
+      contentRevisions: [
+        {
+          _id: "revision-1",
+          siteId: site._id,
+          payloadId: "payload-1",
+          fileIds: [],
+          libraryIds: [],
+          pageIds: [],
+        },
+      ],
+      contentPayloads: [
+        {
+          _id: "payload-1",
+          siteId: site._id,
+          content: JSON.stringify({
+            type: "doc",
+            version: 1,
+            content: [
+              {
+                type: "paragraph",
+                attrs: { "openeditor-id": "paragraph-1" },
+                content: [
+                  {
+                    type: "text",
+                    text: "Before",
+                    attrs: { "openeditor-id": "text-1" },
+                  },
+                ],
+              },
+            ],
+          }),
+        },
+      ],
+      siteReleases: [
+        {
+          _id: "release-base",
+          siteId: site._id,
+          number: 1,
+        },
+      ],
+      releasePages: [
+        {
+          _id: "release-page-1",
+          releaseId: "release-base",
+          siteId: site._id,
+          pageId: "page-1",
+          contentRevisionId: "revision-1",
+          contentHash: "same-content",
+          title: "Removed page",
+          slug: "removed",
+          order: 0,
+        },
+      ],
+    });
+
+    const detail = await buildReleaseChangeDetail(
+      { db: state.db } as never,
+      site as never,
+      {
+        entityType: "page",
+        entityId: "page-1",
+        changeType: "deleted",
+        label: "Removed page",
+        details: [],
+      },
+    );
+
+    expect(detail.content).toEqual({
+      beforeLines: ["Before"],
+      afterLines: [],
+    });
+  });
+
+  test("rejects a file without a publishable extraction", async () => {
+    const file: Row = {
+      _id: "file-1",
+      siteId: "site-1",
+      kind: "file",
+      objectKey: "files/guide.md",
+      filename: "guide.md",
+      contentType: "text/markdown",
+      size: 10,
+      checksum: "checksum-1",
+      createdAt: 1,
+      uploadedBy: "user-1",
+    };
+    const state = makeDb({ files: [file], fileExtractions: [] });
+
+    await expect(
+      snapshotFiles(
+        { db: state.db } as never,
+        "release-1" as never,
+        "site-1" as never,
+        { _id: "site-1" as never },
+      ),
+    ).rejects.toThrow("Document extraction changed");
+    expect(
+      state.inserted.filter((row) => row.table === "releaseFiles"),
+    ).toHaveLength(0);
+  });
+
+  test("resolves draft file references with one page-document scan", async () => {
+    const page = {
+      _id: "page-1",
+      siteId: "site-1",
+      deletedAt: undefined,
+    };
+    const document = {
+      _id: "document-1",
+      siteId: "site-1",
+      pageId: page._id,
+      revisionId: "revision-1",
+    };
+    const revision = {
+      _id: "revision-1",
+      siteId: "site-1",
+      fileIds: ["file-1"],
+    };
+    let pageDocumentScanCount = 0;
+    const ctx = {
+      db: {
+        get: async (id: string) => (id === revision._id ? revision : null),
+        query: (table: string) => ({
+          withIndex: () => {
+            if (table === "pages") {
+              return {
+                [Symbol.asyncIterator]: async function* () {
+                  yield page;
+                },
+              };
+            }
+            pageDocumentScanCount += 1;
+            return { collect: async () => [document] };
+          },
+        }),
+      },
+    };
+
+    const referenced = await getDraftReferencedFileIds(ctx as never, {
+      _id: "site-1" as never,
+      logoFileId: "logo-1" as never,
+      faviconFileId: undefined,
+    });
+
+    expect(pageDocumentScanCount).toBe(1);
+    expect([...referenced].map(String)).toEqual(["logo-1", "file-1"]);
+  });
+
+  test("bounds and normalizes page descriptions", () => {
+    expect(truncateDescription("  one   two  ")).toBe("one two");
+    expect(truncateDescription("x".repeat(281))).toBe(`${"x".repeat(279)}…`);
+  });
+});
diff --git a/packages/backend/convex/publication.ts b/packages/backend/convex/publication.ts
new file mode 100644
index 00000000..fd5c6eb6
--- /dev/null
+++ b/packages/backend/convex/publication.ts
@@ -0,0 +1,504 @@
+import { v } from "convex/values";
+import { internal } from "./_generated/api";
+import type { Doc } from "./_generated/dataModel";
+import { internalMutation, type MutationCtx } from "./_generated/server";
+import { buildReleaseChangeDetail } from "./model/releaseChangeDetails";
+import { fileSourceVersion } from "./model/fileExtraction";
+import { readContentRevisionSearchText } from "./model/contentObjects";
+import {
+  extractionIsPublishable,
+  isReleaseAvailable,
+} from "./model/releaseState";
+import {
+  extractOpenEditorText,
+  parseOpenEditorDocument,
+} from "./pageContentFormat";
+import { upsertSearchEntry } from "./search";
+
+/**
+ * A release manifest freezes mutable metadata and the immutable search text
+ * needed by the live projection. Page content rows reference immutable
+ * content revisions; file text is captured on the release file row.
+ */
+const DESCRIPTION_MAX_CHARS = 280;
+const LIVE_SEARCH_BATCH_SIZE = 8;
+
+const liveSearchProjectionPhase = v.union(
+  v.literal("clear"),
+  v.literal("pages"),
+  v.literal("files"),
+);
+
+type LiveSearchProjectionPhase = "clear" | "pages" | "files";
+
+async function readPublishablePageText(
+  ctx: MutationCtx,
+  siteId: Doc<"sites">["_id"],
+  document: Doc<"pageDocuments"> | null,
+): Promise<string> {
+  if (!document) return "";
+  if (document.siteId !== siteId) {
+    throw new Error("Page content belongs to another site");
+  }
+  const revision = await ctx.db.get(document.revisionId);
+  if (!revision || revision.siteId !== siteId) {
+    throw new Error("Page content revision is missing");
+  }
+  // New revisions already carry their denormalized text. Avoid loading the
+  // potentially large payload in the publish transaction just to derive the
+  // bounded description below.
+  if (revision.searchText !== undefined) return revision.searchText;
+  const payload = await ctx.db.get(revision.payloadId);
+  if (!payload || payload.siteId !== siteId) {
+    throw new Error("Page content payload is missing");
+  }
+  // Parse legacy revisions once so malformed content cannot become the live
+  // release.
+  return extractOpenEditorText(parseOpenEditorDocument(payload.content));
+}
+
+export function truncateDescription(text: string): string {
+  const trimmed = text.trim().replace(/\s+/g, " ");
+  return trimmed.length <= DESCRIPTION_MAX_CHARS
+    ? trimmed
+    : `${trimmed.slice(0, DESCRIPTION_MAX_CHARS - 1)}…`;
+}
+
+export async function snapshotPages(
+  ctx: MutationCtx,
+  releaseId: Doc<"siteReleases">["_id"],
+  siteId: Doc<"sites">["_id"],
+): Promise<number> {
+  const documents = await ctx.db
+    .query("pageDocuments")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))
+    .collect();
+  const documentsByPageId = new Map<string, Doc<"pageDocuments">[]>();
+  for (const document of documents) {
+    const rows = documentsByPageId.get(document.pageId) ?? [];
+    rows.push(document);
+    documentsByPageId.set(document.pageId, rows);
+  }
+
+  let inserted = 0;
+  for await (const source of ctx.db
+    .query("pages")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))) {
+    if (source.deletedAt !== undefined) continue;
+    const documentRows = documentsByPageId.get(source._id) ?? [];
+    if (documentRows.length > 1) {
+      throw new Error("A page has multiple content documents");
+    }
+    const document = documentRows[0] ?? null;
+    await ctx.db.insert("releasePages", {
+      releaseId,
+      siteId,
+      pageId: source._id,
+      parentId: source.parentId,
+      title: source.title,
+      slug: source.slug,
+      icon: source.icon,
+      order: source.order,
+      contentRevisionId: document?.revisionId,
+      contentHash: document?.contentHash,
+      description: truncateDescription(
+        await readPublishablePageText(ctx, siteId, document),
+      ),
+      updatedAt: Math.max(source.updatedAt, document?.updatedAt ?? 0),
+    });
+    inserted += 1;
+  }
+  return inserted;
+}
+
+export async function snapshotLibraries(
+  ctx: MutationCtx,
+  releaseId: Doc<"siteReleases">["_id"],
+  siteId: Doc<"sites">["_id"],
+): Promise<void> {
+  for await (const source of ctx.db
+    .query("documentLibraries")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))) {
+    if (source.deletedAt !== undefined) continue;
+    await ctx.db.insert("releaseLibraries", {
+      releaseId,
+      siteId,
+      libraryId: source._id,
+      name: source.name,
+    });
+  }
+}
+
+export async function snapshotFolders(
+  ctx: MutationCtx,
+  releaseId: Doc<"siteReleases">["_id"],
+  siteId: Doc<"sites">["_id"],
+): Promise<void> {
+  for await (const source of ctx.db
+    .query("documentFolders")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))) {
+    if (source.deletedAt !== undefined) continue;
+    const library = await ctx.db.get(source.libraryId);
+    if (!library || library.deletedAt !== undefined) continue;
+    await ctx.db.insert("releaseFolders", {
+      releaseId,
+      siteId,
+      libraryId: source.libraryId,
+      folderId: source._id,
+      parentId: source.parentId,
+      name: source.name,
+      order: source.order,
+    });
+  }
+}
+
+/**
+ * Resolves all file references from the current draft once. Calling the
+ * per-asset helper inside the publication loop rescans every page document for
+ * every site asset and can exceed Convex's transaction range limit.
+ */
+export async function getDraftReferencedFileIds(
+  ctx: MutationCtx,
+  site: Pick<Doc<"sites">, "_id" | "logoFileId" | "faviconFileId">,
+): Promise<Set<Doc<"files">["_id"]>> {
+  const referenced = new Set<Doc<"files">["_id"]>();
+  if (site.logoFileId) referenced.add(site.logoFileId);
+  if (site.faviconFileId) referenced.add(site.faviconFileId);
+
+  const activePageIds = new Set<Doc<"pages">["_id"]>();
+  for await (const page of ctx.db
+    .query("pages")
+    .withIndex("by_site", (q) => q.eq("siteId", site._id))) {
+    if (page.deletedAt === undefined) activePageIds.add(page._id);
+  }
+
+  const documents = await ctx.db
+    .query("pageDocuments")
+    .withIndex("by_site", (q) => q.eq("siteId", site._id))
+    .collect();
+  for (const document of documents) {
+    if (!activePageIds.has(document.pageId)) continue;
+    const revision = await ctx.db.get(document.revisionId);
+    if (!revision || revision.siteId !== site._id) continue;
+    for (const fileId of revision.fileIds) referenced.add(fileId);
+  }
+  return referenced;
+}
+
+export async function snapshotFiles(
+  ctx: MutationCtx,
+  releaseId: Doc<"siteReleases">["_id"],
+  siteId: Doc<"sites">["_id"],
+  site?: Pick<Doc<"sites">, "_id" | "logoFileId" | "faviconFileId">,
+): Promise<void> {
+  const referencedFileIds = await getDraftReferencedFileIds(
+    ctx,
+    site ?? (await ctx.db.get(siteId)) ?? { _id: siteId },
+  );
+  const extractions = await ctx.db
+    .query("fileExtractions")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))
+    .collect();
+  const extractionsByFileId = new Map<string, Doc<"fileExtractions">[]>();
+  for (const extraction of extractions) {
+    const rows = extractionsByFileId.get(extraction.fileId) ?? [];
+    rows.push(extraction);
+    extractionsByFileId.set(extraction.fileId, rows);
+  }
+
+  for await (const source of ctx.db
+    .query("files")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))) {
+    if (source.deletedAt !== undefined) continue;
+    if (source.kind === "siteAsset" && !referencedFileIds.has(source._id)) {
+      continue;
+    }
+    let extraction: Doc<"fileExtractions"> | null = null;
+    if (source.kind === "file") {
+      const extractionRows = extractionsByFileId.get(source._id) ?? [];
+      if (extractionRows.length > 1) {
+        throw new Error("A file has multiple document extractions");
+      }
+      extraction = extractionRows[0] ?? null;
+      if (!extractionIsPublishable(extraction, fileSourceVersion(source))) {
+        throw new Error(
+          "Document extraction changed before publication completed.",
+        );
+      }
+    }
+    await ctx.db.insert("releaseFiles", {
+      releaseId,
+      siteId,
+      fileId: source._id,
+      kind: source.kind,
+      objectKey: source.objectKey,
+      filename: source.filename,
+      contentType: source.contentType,
+      size: source.size,
+      checksum: source.checksum,
+      libraryId: source.libraryId,
+      folderId: source.folderId,
+      order: source.order,
+      uploadedBy: source.uploadedBy,
+      createdAt: source.createdAt,
+      ...(source.kind === "file"
+        ? {
+            extractedText:
+              extraction?.status === "ready" &&
+              extraction.sourceVersion === fileSourceVersion(source)
+                ? (extraction.extractedText ?? "")
+                : "",
+          }
+        : {}),
+    });
+  }
+}
+
+/**
+ * Copies the current draft changes into the release. Must run before
+ * activation: detail diffs read the draft state and the previous base
+ * release.
+ */
+export async function snapshotChanges(
+  ctx: MutationCtx,
+  site: Doc<"sites">,
+  releaseId: Doc<"siteReleases">["_id"],
+): Promise<number> {
+  let inserted = 0;
+  for await (const source of ctx.db
+    .query("draftChanges")
+    .withIndex("by_site", (q) => q.eq("siteId", site._id))) {
+    const detail = await buildReleaseChangeDetail(ctx, site, source);
+    await ctx.db.insert("releaseChanges", {
+      releaseId,
+      entityType: source.entityType,
+      entityId: source.entityId,
+      changeType: source.changeType,
+      label: source.label,
+      details: source.details,
+      sourceDraftChangeId: source._id,
+      sourceDraftRevision: source.draftRevision,
+      fields: detail.fields,
+      content: detail.content,
+    });
+    inserted += 1;
+  }
+  return inserted;
+}
+
+export async function clearPublishedDraftChanges(
+  ctx: MutationCtx,
+  siteId: Doc<"sites">["_id"],
+): Promise<void> {
+  const changes = await ctx.db
+    .query("draftChanges")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))
+    .collect();
+  for (const change of changes) {
+    await ctx.db.delete(change._id);
+  }
+}
+
+async function readReleasedFileText(
+  ctx: MutationCtx,
+  row: Doc<"releaseFiles">,
+): Promise<string> {
+  if (row.extractedText !== undefined) return row.extractedText;
+
+  // Releases created before `releaseFiles.extractedText` was added need a
+  // guarded compatibility fallback. Never use an extraction for a different
+  // file source; doing so would make historical releases search current draft
+  // content.
+  const file = await ctx.db.get(row.fileId);
+  if (
+    file?.kind !== "file" ||
+    file.deletedAt !== undefined ||
+    file.objectKey !== row.objectKey ||
+    file.size !== row.size ||
+    file.checksum !== row.checksum
+  ) {
+    return "";
+  }
+
+  const extraction = await ctx.db
+    .query("fileExtractions")
+    .withIndex("by_file", (q) => q.eq("fileId", row.fileId))
+    .unique();
+  return extraction?.status === "ready" &&
+    extraction.sourceVersion === fileSourceVersion(file)
+    ? (extraction.extractedText ?? "")
+    : "";
+}
+
+async function scheduleLiveSearchBatch(
+  ctx: Pick<MutationCtx, "scheduler">,
+  args: {
+    siteId: Doc<"sites">["_id"];
+    expectedLiveReleaseId: Doc<"siteReleases">["_id"] | undefined;
+    expectedLiveSearchProjectionGeneration: number | undefined;
+    phase: LiveSearchProjectionPhase;
+    cursor?: string;
+  },
+) {
+  await ctx.scheduler.runAfter(
+    0,
+    internal.publication.projectLiveSearchBatch,
+    args,
+  );
+}
+
+/**
+ * Starts a bounded rebuild of the `live:${siteId}` search scope. Runs as a
+ * derived projection after activation; never blocks publishing. The expected
+ * release id fences the run: if the live pointer moved on, a newer projection
+ * supersedes this one.
+ */
+export const projectLiveSearch = internalMutation({
+  args: {
+    siteId: v.id("sites"),
+    expectedLiveReleaseId: v.optional(v.id("siteReleases")),
+    expectedLiveSearchProjectionGeneration: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (
+    ctx,
+    { siteId, expectedLiveReleaseId, expectedLiveSearchProjectionGeneration },
+  ) => {
+    await scheduleLiveSearchBatch(ctx, {
+      siteId,
+      expectedLiveReleaseId,
+      expectedLiveSearchProjectionGeneration,
+      phase: "clear",
+    });
+    return null;
+  },
+});
+
+/** Processes one bounded portion of a live search projection. */
+export const projectLiveSearchBatch = internalMutation({
+  args: {
+    siteId: v.id("sites"),
+    expectedLiveReleaseId: v.optional(v.id("siteReleases")),
+    expectedLiveSearchProjectionGeneration: v.optional(v.number()),
+    phase: liveSearchProjectionPhase,
+    cursor: v.optional(v.string()),
+  },
+  returns: v.null(),
+  handler: async (
+    ctx,
+    {
+      siteId,
+      expectedLiveReleaseId,
+      expectedLiveSearchProjectionGeneration,
+      phase,
+      cursor,
+    },
+  ) => {
+    const site = await ctx.db.get(siteId);
+    if (
+      !site ||
+      site.liveReleaseId !== expectedLiveReleaseId ||
+      (expectedLiveSearchProjectionGeneration !== undefined &&
+        site.liveSearchProjectionGeneration !==
+          expectedLiveSearchProjectionGeneration)
+    ) {
+      return null;
+    }
+
+    const scopeId = `live:${siteId}`;
+    if (phase === "clear") {
+      const page = await ctx.db
+        .query("searchEntries")
+        .withIndex("by_scope", (q) => q.eq("scopeId", scopeId))
+        .paginate({ cursor: cursor ?? null, numItems: LIVE_SEARCH_BATCH_SIZE });
+      for (const entry of page.page) {
+        if (entry.siteId === siteId) await ctx.db.delete(entry._id);
+      }
+      if (!page.isDone) {
+        await scheduleLiveSearchBatch(ctx, {
+          siteId,
+          expectedLiveReleaseId,
+          expectedLiveSearchProjectionGeneration,
+          phase,
+          cursor: page.continueCursor,
+        });
+        return null;
+      }
+      if (!expectedLiveReleaseId) return null;
+      const release = await ctx.db.get(expectedLiveReleaseId);
+      if (
+        !release ||
+        release.siteId !== siteId ||
+        !isReleaseAvailable(release)
+      ) {
+        return null;
+      }
+      await scheduleLiveSearchBatch(ctx, {
+        siteId,
+        expectedLiveReleaseId,
+        expectedLiveSearchProjectionGeneration,
+        phase: "pages",
+      });
+      return null;
+    }
+
+    if (!expectedLiveReleaseId) return null;
+    const release = await ctx.db.get(expectedLiveReleaseId);
+    if (!release || release.siteId !== siteId || !isReleaseAvailable(release)) {
+      return null;
+    }
+
+    if (phase === "pages") {
+      const page = await ctx.db
+        .query("releasePages")
+        .withIndex("by_release", (q) => q.eq("releaseId", release._id))
+        .paginate({ cursor: cursor ?? null, numItems: LIVE_SEARCH_BATCH_SIZE });
+      for (const row of page.page) {
+        await upsertSearchEntry(ctx, {
+          siteId,
+          scopeId,
+          releaseId: release._id,
+          kind: "page",
+          sourceId: row.pageId,
+          title: row.title,
+          text: await readContentRevisionSearchText(ctx, row.contentRevisionId),
+        });
+      }
+      await scheduleLiveSearchBatch(ctx, {
+        siteId,
+        expectedLiveReleaseId,
+        expectedLiveSearchProjectionGeneration,
+        phase: page.isDone ? "files" : phase,
+        cursor: page.isDone ? undefined : page.continueCursor,
+      });
+      return null;
+    }
+
+    const page = await ctx.db
+      .query("releaseFiles")
+      .withIndex("by_release", (q) => q.eq("releaseId", release._id))
+      .paginate({ cursor: cursor ?? null, numItems: LIVE_SEARCH_BATCH_SIZE });
+    for (const row of page.page) {
+      if (row.kind !== "file") continue;
+      await upsertSearchEntry(ctx, {
+        siteId,
+        scopeId,
+        releaseId: release._id,
+        kind: "file",
+        sourceId: row.fileId,
+        title: row.filename,
+        text: await readReleasedFileText(ctx, row),
+      });
+    }
+    if (!page.isDone) {
+      await scheduleLiveSearchBatch(ctx, {
+        siteId,
+        expectedLiveReleaseId,
+        expectedLiveSearchProjectionGeneration,
+        phase,
+        cursor: page.continueCursor,
+      });
+    }
+    return null;
+  },
+});
diff --git a/packages/backend/convex/publicationMigrations.test.ts b/packages/backend/convex/publicationMigrations.test.ts
new file mode 100644
index 00000000..83824e4f
--- /dev/null
+++ b/packages/backend/convex/publicationMigrations.test.ts
@@ -0,0 +1,296 @@
+import { describe, expect, test } from "bun:test";
+import { internal } from "./_generated/api";
+import { runBatch } from "./publicationMigrations";
+
+type RegisteredFunction = {
+  _handler: (ctx: unknown, args: unknown) => Promise<unknown>;
+};
+
+type Row = Record<string, unknown> & { _id: string };
+
+function invoke(fn: unknown, ctx: unknown, args: unknown): Promise<unknown> {
+  return (fn as RegisteredFunction)._handler(ctx, args);
+}
+
+function makeContext(tables: Record<string, Row[]>) {
+  const scheduled: Array<{
+    functionReference: unknown;
+    args: Record<string, unknown>;
+  }> = [];
+  let nextId = 1;
+
+  const findRows = (table: string, constraints: Array<[string, unknown]>) =>
+    (tables[table] ?? []).filter((row) =>
+      constraints.every(([field, value]) => row[field] === value),
+    );
+
+  const query = (table: string, constraints: Array<[string, unknown]> = []) => {
+    const rows = () => findRows(table, constraints);
+    const builder = {
+      unique: async () => {
+        const matches = rows();
+        if (matches.length > 1) throw new Error("expected unique");
+        return matches[0] ?? null;
+      },
+      paginate: async ({
+        cursor,
+        numItems,
+      }: {
+        cursor: string | null;
+        numItems: number;
+      }) => {
+        const offset = cursor ? Number(cursor) : 0;
+        const page = rows().slice(offset, offset + numItems);
+        return {
+          page,
+          isDone: offset + page.length >= rows().length,
+          continueCursor: String(offset + page.length),
+        };
+      },
+    };
+    return {
+      ...builder,
+      withIndex: (
+        _indexName: string,
+        resolve: (q: {
+          eq: (field: string, value: unknown) => unknown;
+        }) => unknown,
+      ) => {
+        const indexConstraints: Array<[string, unknown]> = [];
+        const q = {
+          eq: (field: string, value: unknown) => {
+            indexConstraints.push([field, value]);
+            return q;
+          },
+        };
+        resolve(q);
+        return query(table, indexConstraints);
+      },
+    };
+  };
+
+  const db = {
+    get: async (id: string) => {
+      for (const rows of Object.values(tables)) {
+        const row = rows.find((candidate) => candidate._id === id);
+        if (row) return row;
+      }
+      return null;
+    },
+    insert: async (table: string, value: Record<string, unknown>) => {
+      const id = `${table}-${nextId++}`;
+      const rows = tables[table] ?? [];
+      rows.push({ ...value, _id: id });
+      tables[table] = rows;
+      return id;
+    },
+    patch: async (id: string, value: Record<string, unknown>) => {
+      for (const rows of Object.values(tables)) {
+        const row = rows.find((candidate) => candidate._id === id);
+        if (row) Object.assign(row, value);
+      }
+    },
+    query,
+    normalizeId: (table: string, id: string) =>
+      (tables[table] ?? []).some((row) => row._id === id) ? id : null,
+  };
+
+  const ctx = {
+    db,
+    scheduler: {
+      runAfter: async (
+        _delay: number,
+        functionReference: unknown,
+        args: Record<string, unknown>,
+      ) => {
+        scheduled.push({ functionReference, args });
+      },
+    },
+  };
+  return { ctx, scheduled, tables };
+}
+
+function migrationFixture() {
+  return makeContext({
+    sites: [
+      {
+        _id: "site-1",
+        liveReleaseId: "release-1",
+        organizationId: "organization-1",
+      },
+    ],
+    siteReleases: [{ _id: "release-1", siteId: "site-1", number: 1 }],
+    contentRevisions: [
+      {
+        _id: "revision-1",
+        siteId: "site-1",
+        payloadId: "payload-1",
+        fileIds: [],
+        libraryIds: [],
+        pageIds: ["page-1"],
+      },
+    ],
+    contentPayloads: [
+      {
+        _id: "payload-1",
+        siteId: "site-1",
+        content: JSON.stringify({
+          type: "doc",
+          version: 1,
+          content: [
+            {
+              type: "paragraph",
+              attrs: { "openeditor-id": "paragraph-1" },
+              content: [{ type: "text", text: "Migrated body" }],
+            },
+          ],
+        }),
+      },
+    ],
+    releasePages: [
+      {
+        _id: "release-page-1",
+        releaseId: "release-1",
+        siteId: "site-1",
+        pageId: "page-1",
+        contentRevisionId: "revision-1",
+        descriptionText: "Legacy description",
+      },
+    ],
+    releaseFiles: [
+      {
+        _id: "release-file-1",
+        releaseId: "release-1",
+        siteId: "site-1",
+        fileId: "file-1",
+        kind: "file",
+        objectKey: "documents/file-1",
+        size: 10,
+        checksum: "checksum-1",
+      },
+    ],
+    searchEntries: [
+      {
+        _id: "search-page-1",
+        siteId: "site-1",
+        scopeId: "release:release-1",
+        kind: "page",
+        sourceId: "page-1",
+        title: "Home",
+        text: "Migrated body",
+      },
+      {
+        _id: "search-file-1",
+        siteId: "site-1",
+        scopeId: "release:release-1",
+        kind: "file",
+        sourceId: "file-1",
+        title: "guide.md",
+        text: "Historical file text",
+      },
+    ],
+  });
+}
+
+async function drainMigration(
+  state: ReturnType<typeof migrationFixture>,
+  args: { runId: string; mode: "dryRun" | "apply" },
+) {
+  await invoke(runBatch, state.ctx, args);
+  while (true) {
+    const index = state.scheduled.findIndex(
+      (item) => item.args.runId === args.runId,
+    );
+    if (index === -1) return;
+    const [next] = state.scheduled.splice(index, 1);
+    if (next) await invoke(runBatch, state.ctx, next.args);
+  }
+}
+
+describe("publication migration", () => {
+  test("backfills immutable text, release metadata, search identity, and live projection", async () => {
+    const state = migrationFixture();
+
+    await drainMigration(state, { runId: "apply-1", mode: "apply" });
+
+    expect(state.tables.contentRevisions?.[0]?.searchText).toContain(
+      "Migrated body",
+    );
+    expect(state.tables.releasePages?.[0]?.description).toContain(
+      "Migrated body",
+    );
+    expect(state.tables.releaseFiles?.[0]?.extractedText).toBe(
+      "Historical file text",
+    );
+    expect(state.tables.searchEntries).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          _id: "search-page-1",
+          releaseId: "release-1",
+        }),
+        expect.objectContaining({
+          _id: "search-file-1",
+          releaseId: "release-1",
+        }),
+      ]),
+    );
+    expect(state.tables.sites?.[0]?.liveSearchProjectionGeneration).toBe(1);
+    expect(state.tables.publicationMigrationRuns?.[0]).toMatchObject({
+      status: "completed",
+      migratedCount: 6,
+      scheduledCount: 1,
+      skippedCount: 0,
+      errorCount: 0,
+    });
+    expect(state.scheduled).toContainEqual({
+      functionReference: internal.publication.projectLiveSearch,
+      args: {
+        siteId: "site-1",
+        expectedLiveReleaseId: "release-1",
+        expectedLiveSearchProjectionGeneration: 1,
+      },
+    });
+  });
+
+  test("dry run reports work without changing publication data", async () => {
+    const state = migrationFixture();
+
+    await drainMigration(state, { runId: "dry-1", mode: "dryRun" });
+
+    expect(state.tables.contentRevisions?.[0]?.searchText).toBeUndefined();
+    expect(state.tables.releasePages?.[0]?.description).toBeUndefined();
+    expect(state.tables.releaseFiles?.[0]?.extractedText).toBeUndefined();
+    expect(state.tables.searchEntries?.[0]?.releaseId).toBeUndefined();
+    expect(
+      state.tables.sites?.[0]?.liveSearchProjectionGeneration,
+    ).toBeUndefined();
+    expect(state.tables.publicationMigrationRuns?.[0]).toMatchObject({
+      status: "completed",
+      migratedCount: 6,
+      scheduledCount: 1,
+      skippedCount: 0,
+      errorCount: 0,
+    });
+    expect(
+      state.scheduled.some(
+        (item) =>
+          item.functionReference === internal.publication.projectLiveSearch,
+      ),
+    ).toBe(false);
+  });
+
+  test("persists a failure for malformed historical content", async () => {
+    const state = migrationFixture();
+    const payload = state.tables.contentPayloads?.[0];
+    if (payload) payload.content = "not-json";
+
+    await drainMigration(state, { runId: "bad-1", mode: "apply" });
+
+    expect(state.tables.publicationMigrationRuns?.[0]).toMatchObject({
+      status: "failed",
+      errorCount: 1,
+      failureSummary: expect.stringContaining("Unexpected"),
+    });
+    expect(state.scheduled).toEqual([]);
+  });
+});
diff --git a/packages/backend/convex/publicationMigrations.ts b/packages/backend/convex/publicationMigrations.ts
new file mode 100644
index 00000000..1ac9e014
--- /dev/null
+++ b/packages/backend/convex/publicationMigrations.ts
@@ -0,0 +1,408 @@
+import { v } from "convex/values";
+import { internal } from "./_generated/api";
+import type { Doc } from "./_generated/dataModel";
+import {
+  internalMutation,
+  internalQuery,
+  type QueryCtx,
+  type MutationCtx,
+} from "./_generated/server";
+import {
+  extractOpenEditorText,
+  parseOpenEditorDocument,
+} from "./pageContentFormat";
+import { fileSourceVersion } from "./model/fileExtraction";
+import { readContentRevisionSearchText } from "./model/contentObjects";
+import { truncateDescription } from "./publication";
+
+const PUBLICATION_MIGRATION_KEY = "publication-manifest-v1";
+const BATCH_SIZE = 8;
+
+type MigrationPhase = "revisions" | "pages" | "files" | "search" | "sites";
+type MigrationMode = "dryRun" | "apply";
+type MigrationRun = Doc<"publicationMigrationRuns">;
+
+function nextPhase(phase: MigrationPhase): MigrationPhase | undefined {
+  switch (phase) {
+    case "revisions":
+      return "pages";
+    case "pages":
+      return "files";
+    case "files":
+      return "search";
+    case "search":
+      return "sites";
+    case "sites":
+      return undefined;
+  }
+}
+
+async function findRun(
+  ctx: Pick<QueryCtx, "db">,
+  runId: string,
+): Promise<MigrationRun | null> {
+  return await ctx.db
+    .query("publicationMigrationRuns")
+    .withIndex("by_migration_run", (q) =>
+      q.eq("migrationKey", PUBLICATION_MIGRATION_KEY).eq("runId", runId),
+    )
+    .unique();
+}
+
+type Counters = {
+  scannedCount: number;
+  migratedCount: number;
+  skippedCount: number;
+  scheduledCount: number;
+  errorCount: number;
+};
+
+type Page<T> = {
+  page: T[];
+  isDone: boolean;
+  continueCursor: string;
+};
+
+function advance(
+  run: MigrationRun,
+  page: { isDone: boolean; continueCursor: string },
+  counters: Counters,
+  now: number,
+) {
+  const phase = page.isDone ? nextPhase(run.phase) : run.phase;
+  const completed = page.isDone && phase === undefined;
+  return {
+    ...counters,
+    phase: phase ?? run.phase,
+    cursor: page.isDone ? undefined : page.continueCursor,
+    status: completed ? ("completed" as const) : ("running" as const),
+    ...(completed ? { completedAt: now } : {}),
+  };
+}
+
+function countScanned(counters: Counters, amount: number): Counters {
+  return { ...counters, scannedCount: counters.scannedCount + amount };
+}
+
+function countersFromRun(run: MigrationRun): Counters {
+  return {
+    scannedCount: run.scannedCount,
+    migratedCount: run.migratedCount,
+    skippedCount: run.skippedCount,
+    scheduledCount: run.scheduledCount ?? 0,
+    errorCount: run.errorCount,
+  };
+}
+
+async function migrateRevisions(
+  ctx: MutationCtx,
+  run: MigrationRun,
+): Promise<ReturnType<typeof advance>> {
+  const page = (await ctx.db
+    .query("contentRevisions")
+    .paginate({ cursor: run.cursor ?? null, numItems: BATCH_SIZE })) as Page<
+    Doc<"contentRevisions">
+  >;
+  let counters = countScanned(countersFromRun(run), page.page.length);
+  for (const revision of page.page) {
+    if (revision.searchText !== undefined) {
+      counters = { ...counters, skippedCount: counters.skippedCount + 1 };
+      continue;
+    }
+    const payload = await ctx.db.get(revision.payloadId);
+    if (!payload || payload.siteId !== revision.siteId) {
+      throw new Error(
+        `Content payload is missing for revision ${revision._id}`,
+      );
+    }
+    const searchText = extractOpenEditorText(
+      parseOpenEditorDocument(payload.content),
+    );
+    if (run.mode === "apply") {
+      await ctx.db.patch(revision._id, { searchText });
+    }
+    counters = { ...counters, migratedCount: counters.migratedCount + 1 };
+  }
+  return advance(run, page, counters, Date.now());
+}
+
+async function migrateReleasePages(
+  ctx: MutationCtx,
+  run: MigrationRun,
+): Promise<ReturnType<typeof advance>> {
+  const page = (await ctx.db
+    .query("releasePages")
+    .paginate({ cursor: run.cursor ?? null, numItems: BATCH_SIZE })) as Page<
+    Doc<"releasePages">
+  >;
+  let counters = countScanned(countersFromRun(run), page.page.length);
+  for (const releasePage of page.page) {
+    if (releasePage.description !== undefined) {
+      counters = { ...counters, skippedCount: counters.skippedCount + 1 };
+      continue;
+    }
+    const contentText = await readContentRevisionSearchText(
+      ctx,
+      releasePage.contentRevisionId,
+    );
+    const description = truncateDescription(
+      contentText || releasePage.descriptionText || "",
+    );
+    if (run.mode === "apply") {
+      await ctx.db.patch(releasePage._id, { description });
+    }
+    counters = { ...counters, migratedCount: counters.migratedCount + 1 };
+  }
+  return advance(run, page, counters, Date.now());
+}
+
+async function readHistoricalFileText(
+  ctx: MutationCtx,
+  releaseFile: Doc<"releaseFiles">,
+): Promise<string> {
+  const legacyEntry = await ctx.db
+    .query("searchEntries")
+    .withIndex("by_scope_source", (q) =>
+      q
+        .eq("scopeId", `release:${releaseFile.releaseId}`)
+        .eq("kind", "file")
+        .eq("sourceId", releaseFile.fileId),
+    )
+    .unique();
+  if (
+    legacyEntry &&
+    legacyEntry.siteId === releaseFile.siteId &&
+    (legacyEntry.releaseId === undefined ||
+      legacyEntry.releaseId === releaseFile.releaseId)
+  ) {
+    return legacyEntry.text;
+  }
+
+  const file = await ctx.db.get(releaseFile.fileId);
+  if (
+    file?.siteId !== releaseFile.siteId ||
+    file.kind !== "file" ||
+    file.deletedAt !== undefined ||
+    file.objectKey !== releaseFile.objectKey ||
+    file.size !== releaseFile.size ||
+    file.checksum !== releaseFile.checksum
+  ) {
+    return "";
+  }
+  const extraction = await ctx.db
+    .query("fileExtractions")
+    .withIndex("by_file", (q) => q.eq("fileId", releaseFile.fileId))
+    .unique();
+  return extraction?.status === "ready" &&
+    extraction.sourceVersion === fileSourceVersion(file)
+    ? (extraction.extractedText ?? "")
+    : "";
+}
+
+async function migrateReleaseFiles(
+  ctx: MutationCtx,
+  run: MigrationRun,
+): Promise<ReturnType<typeof advance>> {
+  const page = (await ctx.db
+    .query("releaseFiles")
+    .paginate({ cursor: run.cursor ?? null, numItems: BATCH_SIZE })) as Page<
+    Doc<"releaseFiles">
+  >;
+  let counters = countScanned(countersFromRun(run), page.page.length);
+  for (const releaseFile of page.page) {
+    if (
+      releaseFile.kind !== "file" ||
+      releaseFile.extractedText !== undefined
+    ) {
+      counters = { ...counters, skippedCount: counters.skippedCount + 1 };
+      continue;
+    }
+    const extractedText = await readHistoricalFileText(ctx, releaseFile);
+    if (run.mode === "apply") {
+      await ctx.db.patch(releaseFile._id, { extractedText });
+    }
+    counters = { ...counters, migratedCount: counters.migratedCount + 1 };
+  }
+  return advance(run, page, counters, Date.now());
+}
+
+async function migrateSearchEntries(
+  ctx: MutationCtx,
+  run: MigrationRun,
+): Promise<ReturnType<typeof advance>> {
+  const page = (await ctx.db
+    .query("searchEntries")
+    .paginate({ cursor: run.cursor ?? null, numItems: BATCH_SIZE })) as Page<
+    Doc<"searchEntries">
+  >;
+  let counters = countScanned(countersFromRun(run), page.page.length);
+  for (const entry of page.page) {
+    if (
+      !entry.scopeId.startsWith("release:") ||
+      entry.releaseId !== undefined
+    ) {
+      counters = { ...counters, skippedCount: counters.skippedCount + 1 };
+      continue;
+    }
+    const releaseId = ctx.db.normalizeId(
+      "siteReleases",
+      entry.scopeId.slice("release:".length),
+    );
+    if (!releaseId) {
+      throw new Error(
+        `Release search entry points to a missing release: ${entry._id}`,
+      );
+    }
+    const release = await ctx.db.get(releaseId);
+    if (!release || release.siteId !== entry.siteId) {
+      throw new Error(`Release search entry has the wrong site: ${entry._id}`);
+    }
+    if (run.mode === "apply") {
+      await ctx.db.patch(entry._id, { releaseId });
+    }
+    counters = { ...counters, migratedCount: counters.migratedCount + 1 };
+  }
+  return advance(run, page, counters, Date.now());
+}
+
+async function migrateLiveSites(
+  ctx: MutationCtx,
+  run: MigrationRun,
+): Promise<ReturnType<typeof advance>> {
+  const page = (await ctx.db
+    .query("sites")
+    .paginate({ cursor: run.cursor ?? null, numItems: BATCH_SIZE })) as Page<
+    Doc<"sites">
+  >;
+  let counters = countScanned(countersFromRun(run), page.page.length);
+  for (const site of page.page) {
+    if (!site.liveReleaseId) {
+      counters = { ...counters, skippedCount: counters.skippedCount + 1 };
+      continue;
+    }
+    const release = await ctx.db.get(site.liveReleaseId);
+    if (!release || release.siteId !== site._id) {
+      throw new Error(`Live release is missing for site ${site._id}`);
+    }
+    counters = {
+      ...counters,
+      scheduledCount: counters.scheduledCount + 1,
+    };
+    if (run.mode === "apply") {
+      const generation = (site.liveSearchProjectionGeneration ?? 0) + 1;
+      await ctx.db.patch(site._id, {
+        liveSearchProjectionGeneration: generation,
+      });
+      await ctx.scheduler.runAfter(0, internal.publication.projectLiveSearch, {
+        siteId: site._id,
+        expectedLiveReleaseId: site.liveReleaseId,
+        expectedLiveSearchProjectionGeneration: generation,
+      });
+      counters = {
+        ...counters,
+        migratedCount: counters.migratedCount + 1,
+      };
+    } else if (site.liveSearchProjectionGeneration === undefined) {
+      counters = {
+        ...counters,
+        migratedCount: counters.migratedCount + 1,
+      };
+    } else {
+      counters = { ...counters, skippedCount: counters.skippedCount + 1 };
+    }
+  }
+  return advance(run, page, counters, Date.now());
+}
+
+async function processPhase(ctx: MutationCtx, run: MigrationRun) {
+  switch (run.phase) {
+    case "revisions":
+      return await migrateRevisions(ctx, run);
+    case "pages":
+      return await migrateReleasePages(ctx, run);
+    case "files":
+      return await migrateReleaseFiles(ctx, run);
+    case "search":
+      return await migrateSearchEntries(ctx, run);
+    case "sites":
+      return await migrateLiveSites(ctx, run);
+  }
+}
+
+async function createRun(
+  ctx: MutationCtx,
+  runId: string,
+  mode: MigrationMode,
+): Promise<MigrationRun> {
+  const now = Date.now();
+  const id = await ctx.db.insert("publicationMigrationRuns", {
+    migrationKey: PUBLICATION_MIGRATION_KEY,
+    runId,
+    mode,
+    phase: "revisions",
+    status: "running",
+    scannedCount: 0,
+    migratedCount: 0,
+    skippedCount: 0,
+    scheduledCount: 0,
+    errorCount: 0,
+    startedAt: now,
+    updatedAt: now,
+  });
+  const run = await ctx.db.get(id);
+  if (!run) throw new Error("Publication migration run was not created");
+  return run;
+}
+
+export const runBatch = internalMutation({
+  args: {
+    runId: v.string(),
+    mode: v.union(v.literal("dryRun"), v.literal("apply")),
+  },
+  returns: v.any(),
+  handler: async (ctx, { runId, mode }) => {
+    const existing = await findRun(ctx, runId);
+    if (existing?.mode !== undefined && existing.mode !== mode) {
+      throw new Error("A migration run cannot change mode");
+    }
+    if (existing?.status === "completed") return existing;
+    const run = existing ?? (await createRun(ctx, runId, mode));
+
+    try {
+      const update = await processPhase(ctx, run);
+      await ctx.db.patch(run._id, {
+        ...update,
+        failureSummary: undefined,
+        updatedAt: Date.now(),
+      });
+      if (update.status === "running") {
+        await ctx.scheduler.runAfter(
+          0,
+          internal.publicationMigrations.runBatch,
+          {
+            runId,
+            mode,
+          },
+        );
+      }
+      return await ctx.db.get(run._id);
+    } catch (error) {
+      const failureSummary =
+        error instanceof Error ? error.message : String(error);
+      await ctx.db.patch(run._id, {
+        status: "failed",
+        phase: run.phase,
+        errorCount: run.errorCount + 1,
+        failureSummary,
+        updatedAt: Date.now(),
+      });
+      return await ctx.db.get(run._id);
+    }
+  },
+});
+
+export const getReport = internalQuery({
+  args: { runId: v.string() },
+  returns: v.any(),
+  handler: async (ctx, { runId }) => await findRun(ctx, runId),
+});
diff --git a/packages/backend/convex/published.ts b/packages/backend/convex/published.ts
index 95b72b71..ea9ba4db 100644
--- a/packages/backend/convex/published.ts
+++ b/packages/backend/convex/published.ts
@@ -8,6 +8,7 @@ import {
   getReadableLiveRelease,
   resolveReleasePage,
 } from "./model/publishedRelease";
+import { isReleaseAvailable } from "./model/releaseState";
 import { buildPageTree } from "./pages";
 import {
   emptyOpenEditorDocument,
@@ -89,7 +90,7 @@ async function getPublishedSiteBySlug(
     .unique();
   if (!site?.liveReleaseId) return null;
   const release = await ctx.db.get(site.liveReleaseId);
-  return release
+  return release && isReleaseAvailable(release)
     ? {
         organization: { ...organization, slug: organization.slug },
         site,
@@ -245,7 +246,10 @@ export const getPageMetadata = query({
     if (!resolved) return null;
     return {
       title: resolved.page.title,
-      descriptionText: resolved.page.descriptionText || resolved.page.title,
+      descriptionText:
+        resolved.page.description ||
+        resolved.page.descriptionText ||
+        resolved.page.title,
       canonicalPath: canonicalPagePath(context.release, resolved),
       updatedAt: resolved.page.updatedAt,
     };
@@ -360,7 +364,7 @@ export const sitemap = query({
         const release = site.liveReleaseId
           ? await ctx.db.get(site.liveReleaseId)
           : null;
-        if (!release) return null;
+        if (!release || !isReleaseAvailable(release)) return null;
         const pages = await ctx.db
           .query("releasePages")
           .withIndex("by_release", (q) => q.eq("releaseId", release._id))
@@ -412,10 +416,12 @@ export const getPageExport = query({
     if (!site?.liveReleaseId) return null;
     const access = await resolvePublishedSiteAccess(ctx, site);
     if (!canRenderPublishedSite(access)) return null;
+    const release = await ctx.db.get(site.liveReleaseId);
+    if (!release || !isReleaseAvailable(release)) return null;
     const page = await ctx.db
       .query("releasePages")
       .withIndex("by_release_page", (q) =>
-        q.eq("releaseId", site.liveReleaseId!).eq("pageId", pageId),
+        q.eq("releaseId", release._id).eq("pageId", pageId),
       )
       .unique();
     if (!page) return null;
@@ -433,7 +439,7 @@ export const getPageExport = query({
     }
     const assets = await readReleaseImageAssets(
       ctx,
-      site.liveReleaseId,
+      release._id,
       revision?.fileIds ?? [],
       imageReferenceIds,
     );
diff --git a/packages/backend/convex/releasePublication.test.ts b/packages/backend/convex/releasePublication.test.ts
index 943640c6..f8b7464f 100644
--- a/packages/backend/convex/releasePublication.test.ts
+++ b/packages/backend/convex/releasePublication.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { draftChangeMatchesPublication } from "./releasePublication";
-import { makeLive, publish } from "./releases";
+import { internal } from "./_generated/api";
+import { cleanupFailedRelease, recover } from "./releasePublication";
 
 type RegisteredFunction = {
   _handler: (ctx: unknown, args: unknown) => Promise<unknown>;
@@ -10,148 +10,176 @@ function invoke(fn: unknown, ctx: unknown, args: unknown): Promise<unknown> {
   return (fn as RegisteredFunction)._handler(ctx, args);
 }
 
-describe("release publication fencing", () => {
-  test("authorization runs before publication state is disclosed", async () => {
-    let permissionChecks = 0;
-    const release = {
-      _id: "release-1",
-      siteId: "site-1",
-      publicationStatus: "building",
-    };
-    const site = { _id: "site-1", organizationId: "organization-1" };
-    const ctx = {
-      auth: {
-        getUserIdentity: async () => ({ subject: "unauthorized-user" }),
+type Row = Record<string, unknown> & { _id: string };
+
+function makeContext(tables: Record<string, Row[]>) {
+  const patches: Array<[string, Record<string, unknown>]> = [];
+  const deleted: string[] = [];
+  const scheduled: Array<{
+    delay: number;
+    functionReference: unknown;
+    args: Record<string, unknown>;
+  }> = [];
+
+  return {
+    patches,
+    deleted,
+    scheduled,
+    db: {
+      get: async (id: string) => {
+        for (const rows of Object.values(tables)) {
+          const row = rows.find((candidate) => candidate._id === id);
+          if (row) return row;
+        }
+        return null;
       },
-      db: {
-        get: async (id: string) => (id === release._id ? release : site),
+      patch: async (id: string, values: Record<string, unknown>) => {
+        for (const rows of Object.values(tables)) {
+          const row = rows.find((candidate) => candidate._id === id);
+          if (row) Object.assign(row, values);
+        }
+        patches.push([id, values]);
       },
-      runQuery: async () => {
-        permissionChecks += 1;
-        return null;
+      delete: async (id: string) => {
+        for (const rows of Object.values(tables)) {
+          const index = rows.findIndex((candidate) => candidate._id === id);
+          if (index >= 0) rows.splice(index, 1);
+        }
+        deleted.push(id);
       },
-    };
-
-    await expect(
-      invoke(makeLive, ctx, { releaseId: release._id }),
-    ).rejects.not.toThrow("Release publication is not complete");
-    expect(permissionChecks).toBe(1);
-  });
+      query: (table: string) => ({
+        withIndex: () => ({
+          collect: async () => tables[table] ?? [],
+          paginate: async () => ({
+            page: tables[table] ?? [],
+            isDone: true,
+            continueCursor: "",
+          }),
+        }),
+      }),
+    },
+    scheduler: {
+      runAfter: async (
+        delay: number,
+        functionReference: unknown,
+        args: Record<string, unknown>,
+      ) => {
+        scheduled.push({ delay, functionReference, args });
+      },
+    },
+  };
+}
 
-  test("promotes an existing complete release without waiting for extraction", async () => {
-    const release = {
+describe("legacy publication workflow recovery", () => {
+  test("marks an interrupted building release unavailable", async () => {
+    const release: Row = {
       _id: "release-1",
       siteId: "site-1",
-      number: 3,
-      publicationStatus: "complete",
-    };
-    const site = {
-      _id: release.siteId,
-      organizationId: "organization-1",
-      draftRevision: 9,
-      draftBaseReleaseId: release._id,
-      liveReleaseId: undefined,
-    };
-    let queriedExtractions = false;
-    const ctx = {
-      auth: { getUserIdentity: async () => ({ subject: "user-1" }) },
-      runQuery: async () => ({
-        _id: "member-1",
-        organizationId: site.organizationId,
-        role: "owner",
-        userId: "user-1",
-      }),
-      db: {
-        get: async (id: string) => (id === site._id ? site : release),
-        query: (table: string) => {
-          if (table === "fileExtractions") queriedExtractions = true;
-          return {
-            withIndex: () => ({ first: async () => null }),
-          };
-        },
-        patch: async () => undefined,
-        insert: async () => "event-1",
-      },
+      publicationStatus: "building",
     };
+    const state = makeContext({ siteReleases: [release] });
 
-    expect(
-      await invoke(publish, ctx, {
-        siteId: site._id,
-        expectedDraftRevision: site.draftRevision,
-      }),
-    ).toEqual({ releaseId: release._id, number: release.number, reused: true });
-    expect(queriedExtractions).toBe(false);
+    await invoke(recover, state, { releaseId: release._id });
+
+    expect(release).toMatchObject({
+      publicationStatus: "failed",
+      publicationFailure:
+        "The legacy publication was interrupted during the publishing refactor.",
+    });
+    expect(state.scheduled).toEqual([
+      {
+        delay: 0,
+        functionReference: internal.releasePublication.cleanupFailedRelease,
+        args: { releaseId: release._id, phase: "pages" },
+      },
+    ]);
   });
 
-  test("rejects an in-flight publication with no workflow identity", async () => {
-    const release = {
+  test("cleans partial release snapshots in bounded phases", async () => {
+    const release: Row = {
       _id: "release-1",
       siteId: "site-1",
-      number: 3,
-      sourceDraftRevision: 9,
-      publicationStatus: "building",
-    };
-    const site = {
-      _id: release.siteId,
-      organizationId: "organization-1",
-      draftRevision: release.sourceDraftRevision,
-    };
-    let publicationQuery = 0;
-    const ctx = {
-      auth: { getUserIdentity: async () => ({ subject: "user-1" }) },
-      runQuery: async () => ({
-        _id: "member-1",
-        organizationId: site.organizationId,
-        role: "owner",
-        userId: "user-1",
-      }),
-      db: {
-        get: async () => site,
-        query: () => ({
-          withIndex: () => ({
-            first: async () => {
-              publicationQuery += 1;
-              return publicationQuery === 1 ? release : null;
-            },
-          }),
-        }),
-      },
+      publicationStatus: "failed",
     };
+    const tables = {
+      siteReleases: [release],
+      releasePages: [{ _id: "page-snapshot", releaseId: release._id }],
+      releaseLibraries: [{ _id: "library-snapshot", releaseId: release._id }],
+      releaseFolders: [{ _id: "folder-snapshot", releaseId: release._id }],
+      releaseFiles: [{ _id: "file-snapshot", releaseId: release._id }],
+      searchEntries: [
+        { _id: "search-snapshot", scopeId: `release:${release._id}` },
+      ],
+      releaseChanges: [{ _id: "change-snapshot", releaseId: release._id }],
+    } satisfies Record<string, Row[]>;
+    const state = makeContext(tables);
 
-    await expect(
-      invoke(publish, ctx, {
-        siteId: site._id,
-        expectedDraftRevision: site.draftRevision,
-      }),
-    ).rejects.toThrow("workflow state is missing");
+    for (const phase of [
+      "pages",
+      "libraries",
+      "folders",
+      "files",
+      "search",
+      "changes",
+    ] as const) {
+      await invoke(cleanupFailedRelease, state, {
+        releaseId: release._id,
+        phase,
+      });
+    }
+
+    expect(tables.releasePages).toHaveLength(0);
+    expect(tables.releaseLibraries).toHaveLength(0);
+    expect(tables.releaseFolders).toHaveLength(0);
+    expect(tables.releaseFiles).toHaveLength(0);
+    expect(tables.searchEntries).toHaveLength(0);
+    expect(tables.releaseChanges).toHaveLength(0);
   });
-});
 
-describe("published draft-change cleanup", () => {
-  test("deletes only the exact snapshotted draft generation", () => {
-    const snapshot = {
-      sourceDraftChangeId: "change-1" as never,
-      sourceDraftRevision: 7,
+  test("finishes cleanup only for the exact snapshotted draft generation", async () => {
+    const release: Row = {
+      _id: "release-1",
+      siteId: "site-1",
+      publicationStatus: "clearing",
+    };
+    const site: Row = {
+      _id: "site-1",
+      liveReleaseId: release._id,
     };
-    expect(
-      draftChangeMatchesPublication(
+    const state = makeContext({
+      siteReleases: [release],
+      sites: [site],
+      releaseChanges: [
         {
-          _id: "change-1" as never,
-          draftRevision: 7,
-          updatedAt: 100,
+          _id: "snapshot-1",
+          releaseId: release._id,
+          sourceDraftChangeId: "change-1",
+          sourceDraftRevision: 7,
         },
-        snapshot,
-      ),
-    ).toBe(true);
-    expect(
-      draftChangeMatchesPublication(
         {
-          _id: "change-1" as never,
-          draftRevision: 8,
-          updatedAt: 100,
+          _id: "snapshot-2",
+          releaseId: release._id,
+          sourceDraftChangeId: "change-2",
+          sourceDraftRevision: 6,
         },
-        snapshot,
-      ),
-    ).toBe(false);
+      ],
+      draftChanges: [
+        { _id: "change-1", siteId: site._id, draftRevision: 7 },
+        { _id: "change-2", siteId: site._id, draftRevision: 8 },
+        { _id: "change-3", siteId: site._id, draftRevision: 7 },
+      ],
+    });
+
+    await invoke(recover, state, { releaseId: release._id });
+
+    expect(release.publicationStatus).toBe("complete");
+    expect(state.deleted).toEqual(["change-1"]);
+    expect(state.scheduled).toEqual([
+      {
+        delay: 0,
+        functionReference: internal.publication.projectLiveSearch,
+        args: { siteId: site._id, expectedLiveReleaseId: release._id },
+      },
+    ]);
   });
 });
diff --git a/packages/backend/convex/releasePublication.ts b/packages/backend/convex/releasePublication.ts
index 43844211..5328a864 100644
--- a/packages/backend/convex/releasePublication.ts
+++ b/packages/backend/convex/releasePublication.ts
@@ -1,557 +1,216 @@
 import { v } from "convex/values";
 import { internal } from "./_generated/api";
-import type { Doc, Id } from "./_generated/dataModel";
-import { type MutationCtx, internalMutation } from "./_generated/server";
+import type { Id } from "./_generated/dataModel";
+import { internalMutation } from "./_generated/server";
+import type { MutationCtx } from "./_generated/server";
 import { workflows } from "./workflows";
-import { fileSourceVersion } from "./model/fileExtraction";
-import { buildReleaseChangeDetail } from "./model/releaseChangeDetails";
-import { extractionIsPublishable } from "./model/releaseState";
-import { isSiteAssetReferencedByDraft } from "./model/siteAssets";
-import {
-  extractOpenEditorText,
-  parseOpenEditorDocument,
-} from "./pageContentFormat";
-import { releaseSearchScope, upsertSearchEntry } from "./search";
 
-const PAGE_BATCH_SIZE = 6;
-const FILE_BATCH_SIZE = 8;
-const CHANGE_BATCH_SIZE = 8;
-const METADATA_BATCH_SIZE = 40;
-const CLEANUP_BATCH_SIZE = 50;
+const LEGACY_CLEANUP_BATCH_SIZE = 50;
 
-const buildPhaseValidator = v.union(
+const legacyCleanupPhase = v.union(
   v.literal("pages"),
   v.literal("libraries"),
   v.literal("folders"),
   v.literal("files"),
+  v.literal("search"),
   v.literal("changes"),
-  v.literal("activate"),
-  v.literal("clearDraftChanges"),
 );
 
-const cleanupPhaseValidator = v.union(
-  v.literal("cleanupPages"),
-  v.literal("cleanupLibraries"),
-  v.literal("cleanupFolders"),
-  v.literal("cleanupFiles"),
-  v.literal("cleanupSearch"),
-  v.literal("cleanupChanges"),
-);
-
-type BuildPhase =
+type LegacyCleanupPhase =
   | "pages"
   | "libraries"
   | "folders"
   | "files"
-  | "changes"
-  | "activate"
-  | "clearDraftChanges";
-
-type CleanupPhase =
-  | "cleanupPages"
-  | "cleanupLibraries"
-  | "cleanupFolders"
-  | "cleanupFiles"
-  | "cleanupSearch"
-  | "cleanupChanges";
-
-async function hasPendingFileExtraction(
-  ctx: MutationCtx,
-  siteId: Id<"sites">,
-): Promise<boolean> {
-  const [queued, processing] = await Promise.all([
-    ctx.db
-      .query("fileExtractions")
-      .withIndex("by_site_status", (q) =>
-        q.eq("siteId", siteId).eq("status", "queued"),
-      )
-      .first(),
-    ctx.db
-      .query("fileExtractions")
-      .withIndex("by_site_status", (q) =>
-        q.eq("siteId", siteId).eq("status", "processing"),
-      )
-      .first(),
-  ]);
-  return Boolean(queued || processing);
-}
-
-async function continuePagination(
-  _ctx: MutationCtx,
-  _release: Doc<"siteReleases">,
-  _token: string,
-  _phase: BuildPhase,
-  result: { isDone: boolean; continueCursor: string },
-  _nextPhase: BuildPhase,
-) {
-  return result;
-}
-
-async function snapshotPages(
-  ctx: MutationCtx,
-  release: Doc<"siteReleases">,
-  token: string,
-  cursor?: string,
-) {
-  const page = await ctx.db
-    .query("pages")
-    .withIndex("by_site", (q) => q.eq("siteId", release.siteId))
-    .paginate({ cursor: cursor ?? null, numItems: PAGE_BATCH_SIZE });
-  let inserted = 0;
-  for (const source of page.page) {
-    if (source.deletedAt !== undefined) continue;
-    const document = await ctx.db
-      .query("pageDocuments")
-      .withIndex("by_page", (q) => q.eq("pageId", source._id))
-      .unique();
-    const revision = document ? await ctx.db.get(document.revisionId) : null;
-    const payload = revision ? await ctx.db.get(revision.payloadId) : null;
-    const text = payload
-      ? extractOpenEditorText(parseOpenEditorDocument(payload.content)).trim()
-      : "";
-    await ctx.db.insert("releasePages", {
-      releaseId: release._id,
-      siteId: release.siteId,
-      pageId: source._id,
-      parentId: source.parentId,
-      title: source.title,
-      slug: source.slug,
-      icon: source.icon,
-      order: source.order,
-      contentRevisionId: document?.revisionId,
-      contentHash: document?.contentHash,
-      descriptionText: text,
-      updatedAt: Math.max(source.updatedAt, document?.updatedAt ?? 0),
-    });
-    await upsertSearchEntry(ctx, {
-      siteId: release.siteId,
-      scopeId: releaseSearchScope(release._id),
-      kind: "page",
-      sourceId: source._id,
-      title: source.title,
-      text,
-    });
-    inserted += 1;
-  }
-  if (inserted > 0) {
-    await ctx.db.patch(release._id, {
-      pageCount: release.pageCount + inserted,
-    });
-  }
-  return continuePagination(ctx, release, token, "pages", page, "libraries");
-}
-
-async function snapshotLibraries(
-  ctx: MutationCtx,
-  release: Doc<"siteReleases">,
-  token: string,
-  cursor?: string,
-) {
-  const page = await ctx.db
-    .query("documentLibraries")
-    .withIndex("by_site", (q) => q.eq("siteId", release.siteId))
-    .paginate({ cursor: cursor ?? null, numItems: METADATA_BATCH_SIZE });
-  for (const source of page.page) {
-    if (source.deletedAt !== undefined) continue;
-    await ctx.db.insert("releaseLibraries", {
-      releaseId: release._id,
-      siteId: release.siteId,
-      libraryId: source._id,
-      name: source.name,
-    });
-  }
-  return continuePagination(ctx, release, token, "libraries", page, "folders");
-}
-
-async function snapshotFolders(
-  ctx: MutationCtx,
-  release: Doc<"siteReleases">,
-  token: string,
-  cursor?: string,
+  | "search"
+  | "changes";
+
+const nextLegacyCleanupPhase: Record<
+  LegacyCleanupPhase,
+  LegacyCleanupPhase | undefined
+> = {
+  pages: "libraries",
+  libraries: "folders",
+  folders: "files",
+  files: "search",
+  search: "changes",
+  changes: undefined,
+};
+
+async function scheduleLegacyCleanup(
+  ctx: Pick<MutationCtx, "scheduler">,
+  args: {
+    releaseId: Id<"siteReleases">;
+    phase: LegacyCleanupPhase;
+    cursor?: string;
+  },
 ) {
-  const page = await ctx.db
-    .query("documentFolders")
-    .withIndex("by_site", (q) => q.eq("siteId", release.siteId))
-    .paginate({ cursor: cursor ?? null, numItems: METADATA_BATCH_SIZE });
-  for (const source of page.page) {
-    if (source.deletedAt !== undefined) continue;
-    const library = await ctx.db.get(source.libraryId);
-    if (!library || library.deletedAt !== undefined) continue;
-    await ctx.db.insert("releaseFolders", {
-      releaseId: release._id,
-      siteId: release.siteId,
-      libraryId: source.libraryId,
-      folderId: source._id,
-      parentId: source.parentId,
-      name: source.name,
-      order: source.order,
-    });
-  }
-  return continuePagination(ctx, release, token, "folders", page, "files");
+  await ctx.scheduler.runAfter(
+    0,
+    internal.releasePublication.cleanupFailedRelease,
+    args,
+  );
 }
 
-async function snapshotFiles(
-  ctx: MutationCtx,
-  release: Doc<"siteReleases">,
-  token: string,
-  cursor?: string,
-) {
-  const page = await ctx.db
-    .query("files")
-    .withIndex("by_site", (q) => q.eq("siteId", release.siteId))
-    .paginate({ cursor: cursor ?? null, numItems: FILE_BATCH_SIZE });
-  for (const source of page.page) {
-    if (source.deletedAt !== undefined) continue;
-    if (
-      source.kind === "siteAsset" &&
-      !(await isSiteAssetReferencedByDraft(ctx, source))
-    ) {
-      continue;
-    }
-    await ctx.db.insert("releaseFiles", {
-      releaseId: release._id,
-      siteId: release.siteId,
-      fileId: source._id,
-      kind: source.kind,
-      objectKey: source.objectKey,
-      filename: source.filename,
-      contentType: source.contentType,
-      size: source.size,
-      checksum: source.checksum,
-      libraryId: source.libraryId,
-      folderId: source.folderId,
-      order: source.order,
-      uploadedBy: source.uploadedBy,
-      createdAt: source.createdAt,
-    });
-    if (source.kind !== "file") continue;
-    const extraction = await ctx.db
-      .query("fileExtractions")
-      .withIndex("by_file", (q) => q.eq("fileId", source._id))
-      .unique();
-    if (!extractionIsPublishable(extraction, fileSourceVersion(source))) {
-      throw new Error(
-        "Document extraction changed before publication completed.",
+/**
+ * Compatibility entry point for workflows created before publication became
+ * atomic. New releases never use this workflow. Keeping the function path
+ * available lets an already queued workflow finish safely after deployment.
+ */
+export const recover = internalMutation({
+  args: { releaseId: v.id("siteReleases") },
+  returns: v.null(),
+  handler: async (ctx, { releaseId }) => {
+    const release = await ctx.db.get(releaseId);
+    if (!release || release.publicationStatus === undefined) return null;
+
+    const now = Date.now();
+    if (release.publicationStatus === "clearing") {
+      const snapshots = await ctx.db
+        .query("releaseChanges")
+        .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+        .collect();
+      const snapshottedChanges = new Map(
+        snapshots
+          .filter(
+            (snapshot) =>
+              snapshot.sourceDraftChangeId !== undefined &&
+              snapshot.sourceDraftRevision !== undefined,
+          )
+          .map((snapshot) => [
+            snapshot.sourceDraftChangeId!,
+            snapshot.sourceDraftRevision!,
+          ]),
       );
+      const currentChanges = await ctx.db
+        .query("draftChanges")
+        .withIndex("by_site", (q) => q.eq("siteId", release.siteId))
+        .collect();
+      for (const change of currentChanges) {
+        if (snapshottedChanges.get(change._id) === change.draftRevision) {
+          await ctx.db.delete(change._id);
+        }
+      }
+      await ctx.db.patch(releaseId, {
+        publicationStatus: "complete",
+        publicationFailure: undefined,
+        publicationUpdatedAt: now,
+      });
+      const site = await ctx.db.get(release.siteId);
+      if (site?.liveReleaseId === releaseId) {
+        await ctx.scheduler.runAfter(
+          0,
+          internal.publication.projectLiveSearch,
+          {
+            siteId: site._id,
+            expectedLiveReleaseId: releaseId,
+            expectedLiveSearchProjectionGeneration:
+              site.liveSearchProjectionGeneration,
+          },
+        );
+      }
+      return null;
     }
-    await upsertSearchEntry(ctx, {
-      siteId: release.siteId,
-      scopeId: releaseSearchScope(release._id),
-      kind: "file",
-      sourceId: source._id,
-      title: source.filename,
-      text:
-        extraction?.status === "ready" ? (extraction.extractedText ?? "") : "",
-    });
-  }
-  return continuePagination(ctx, release, token, "files", page, "changes");
-}
-
-async function snapshotChanges(
-  ctx: MutationCtx,
-  release: Doc<"siteReleases">,
-  token: string,
-  cursor?: string,
-) {
-  const site = await ctx.db.get(release.siteId);
-  if (!site) {
-    throw new Error("The draft changed before publication completed.");
-  }
-  const page = await ctx.db
-    .query("draftChanges")
-    .withIndex("by_site", (q) => q.eq("siteId", release.siteId))
-    .paginate({ cursor: cursor ?? null, numItems: CHANGE_BATCH_SIZE });
-  for (const source of page.page) {
-    const detail = await buildReleaseChangeDetail(ctx, site, source);
-    await ctx.db.insert("releaseChanges", {
-      releaseId: release._id,
-      entityType: source.entityType,
-      entityId: source.entityId,
-      changeType: source.changeType,
-      label: source.label,
-      details: source.details,
-      sourceDraftChangeId: source._id,
-      sourceDraftRevision: source.draftRevision,
-      fields: detail.fields,
-      content: detail.content,
-    });
-  }
-  if (page.page.length > 0) {
-    await ctx.db.patch(release._id, {
-      changeCount: release.changeCount + page.page.length,
-    });
-  }
-  return continuePagination(ctx, release, token, "changes", page, "activate");
-}
-
-async function activateRelease(ctx: MutationCtx, release: Doc<"siteReleases">) {
-  const site = await ctx.db.get(release.siteId);
-  if (
-    !site ||
-    site.draftRevision !== release.sourceDraftRevision ||
-    release.pageCount === 0 ||
-    (await hasPendingFileExtraction(ctx, release.siteId))
-  ) {
-    throw new Error(
-      "The draft or document extraction changed before publication completed.",
-    );
-  }
-  const now = Date.now();
-  await ctx.db.patch(release._id, {
-    publicationStatus: "clearing",
-    publicationUpdatedAt: now,
-  });
-  await ctx.db.patch(site._id, {
-    liveReleaseId: release._id,
-    draftBaseReleaseId: release._id,
-    updatedAt: now,
-  });
-  await ctx.db.insert("publicationEvents", {
-    siteId: site._id,
-    action: site.liveReleaseId ? "update" : "publish",
-    fromReleaseId: site.liveReleaseId,
-    toReleaseId: release._id,
-    actorId: release.createdBy,
-    createdAt: now,
-  });
-}
-
-export function draftChangeMatchesPublication(
-  current: Pick<Doc<"draftChanges">, "_id" | "draftRevision" | "updatedAt">,
-  snapshot: Pick<
-    Doc<"releaseChanges">,
-    "sourceDraftChangeId" | "sourceDraftRevision"
-  >,
-) {
-  if (
-    !snapshot.sourceDraftChangeId ||
-    current._id !== snapshot.sourceDraftChangeId
-  ) {
-    return false;
-  }
-  return (
-    snapshot.sourceDraftRevision !== undefined &&
-    current.draftRevision === snapshot.sourceDraftRevision
-  );
-}
 
-async function clearPublishedDraftChanges(
-  ctx: MutationCtx,
-  release: Doc<"siteReleases">,
-  cursor?: string,
-) {
-  const page = await ctx.db
-    .query("releaseChanges")
-    .withIndex("by_release", (q) => q.eq("releaseId", release._id))
-    .paginate({ cursor: cursor ?? null, numItems: METADATA_BATCH_SIZE });
-  for (const snapshot of page.page) {
-    if (!snapshot.sourceDraftChangeId) continue;
-    const current = await ctx.db.get(snapshot.sourceDraftChangeId);
-    if (
-      current?.siteId === release.siteId &&
-      draftChangeMatchesPublication(current, snapshot)
-    ) {
-      await ctx.db.delete(current._id);
+    if (release.publicationStatus === "building") {
+      await ctx.db.patch(releaseId, {
+        publicationStatus: "failed",
+        publicationFailure:
+          "The legacy publication was interrupted during the publishing refactor.",
+        publicationUpdatedAt: now,
+      });
+      await scheduleLegacyCleanup(ctx, {
+        releaseId,
+        phase: "pages",
+      });
     }
-  }
-  return page;
-}
-
-const cleanupTables = {
-  cleanupPages: "releasePages",
-  cleanupLibraries: "releaseLibraries",
-  cleanupFolders: "releaseFolders",
-  cleanupFiles: "releaseFiles",
-  cleanupChanges: "releaseChanges",
-} as const;
-
-const cleanupPhases: CleanupPhase[] = [
-  "cleanupPages",
-  "cleanupLibraries",
-  "cleanupFolders",
-  "cleanupFiles",
-  "cleanupSearch",
-  "cleanupChanges",
-];
+    return null;
+  },
+});
 
-async function cleanupRelease(
+/**
+ * Removes partial snapshots left by an interrupted legacy build without
+ * placing a large cleanup in one transaction. The failed release row remains
+ * as an audit record and is never made readable by the publication surface.
+ */
+async function readLegacyCleanupPage(
   ctx: MutationCtx,
-  release: Doc<"siteReleases">,
-  phase: CleanupPhase,
+  releaseId: Id<"siteReleases">,
+  phase: LegacyCleanupPhase,
+  cursor: string | undefined,
 ) {
-  if (phase === "cleanupSearch") {
-    const rows = await ctx.db
-      .query("searchEntries")
-      .withIndex("by_scope", (q) =>
-        q.eq("scopeId", releaseSearchScope(release._id)),
-      )
-      .take(CLEANUP_BATCH_SIZE);
-    for (const row of rows) await ctx.db.delete(row._id);
-    return rows.length < CLEANUP_BATCH_SIZE;
+  const paginationOpts = {
+    cursor: cursor ?? null,
+    numItems: LEGACY_CLEANUP_BATCH_SIZE,
+  };
+  switch (phase) {
+    case "pages":
+      return ctx.db
+        .query("releasePages")
+        .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+        .paginate(paginationOpts);
+    case "libraries":
+      return ctx.db
+        .query("releaseLibraries")
+        .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+        .paginate(paginationOpts);
+    case "folders":
+      return ctx.db
+        .query("releaseFolders")
+        .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+        .paginate(paginationOpts);
+    case "files":
+      return ctx.db
+        .query("releaseFiles")
+        .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+        .paginate(paginationOpts);
+    case "search":
+      return ctx.db
+        .query("searchEntries")
+        .withIndex("by_scope", (q) => q.eq("scopeId", `release:${releaseId}`))
+        .paginate(paginationOpts);
+    case "changes":
+      return ctx.db
+        .query("releaseChanges")
+        .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+        .paginate(paginationOpts);
   }
-  const rows = await ctx.db
-    .query(cleanupTables[phase])
-    .withIndex("by_release", (q) => q.eq("releaseId", release._id))
-    .take(CLEANUP_BATCH_SIZE);
-  for (const row of rows) await ctx.db.delete(row._id);
-  return rows.length < CLEANUP_BATCH_SIZE;
 }
 
-export const applyBatch = internalMutation({
+export const cleanupFailedRelease = internalMutation({
   args: {
     releaseId: v.id("siteReleases"),
-    phase: buildPhaseValidator,
+    phase: legacyCleanupPhase,
     cursor: v.optional(v.string()),
   },
-  handler: async (ctx, args) => {
-    const release = await ctx.db.get(args.releaseId);
-    if (release?.publicationStatus !== "building") return null;
-    const site = await ctx.db.get(release.siteId);
-    if (!site || site.draftRevision !== release.sourceDraftRevision) {
-      throw new Error("The draft changed before publication completed.");
-    }
-
-    switch (args.phase as BuildPhase) {
-      case "pages":
-        return snapshotPages(ctx, release, "", args.cursor);
-      case "libraries":
-        return snapshotLibraries(ctx, release, "", args.cursor);
-      case "folders":
-        return snapshotFolders(ctx, release, "", args.cursor);
-      case "files":
-        return snapshotFiles(ctx, release, "", args.cursor);
-      case "changes":
-        return snapshotChanges(ctx, release, "", args.cursor);
-      case "activate":
-        return null;
-      case "clearDraftChanges":
-        return null;
-    }
-  },
-});
-
-export const activate = internalMutation({
-  args: { releaseId: v.id("siteReleases") },
-  handler: async (ctx, { releaseId }) => {
-    const release = await ctx.db.get(releaseId);
-    if (release?.publicationStatus !== "building") return;
-    await activateRelease(ctx, release);
-  },
-});
-
-export const clearChangesBatch = internalMutation({
-  args: { releaseId: v.id("siteReleases"), cursor: v.optional(v.string()) },
-  handler: async (ctx, { releaseId, cursor }) => {
+  returns: v.null(),
+  handler: async (ctx, { releaseId, phase, cursor }) => {
     const release = await ctx.db.get(releaseId);
-    if (release?.publicationStatus !== "clearing") return null;
-    return clearPublishedDraftChanges(ctx, release, cursor);
-  },
-});
+    if (release?.publicationStatus !== "failed") return null;
 
-export const finish = internalMutation({
-  args: { releaseId: v.id("siteReleases") },
-  handler: async (ctx, { releaseId }) => {
-    await ctx.db.patch(releaseId, {
-      publicationStatus: "complete",
-      publicationFailure: undefined,
-      publicationUpdatedAt: Date.now(),
-    });
-  },
-});
+    const page = await readLegacyCleanupPage(ctx, releaseId, phase, cursor);
 
-export const cleanupBatch = internalMutation({
-  args: { releaseId: v.id("siteReleases"), phase: cleanupPhaseValidator },
-  handler: async (ctx, { releaseId, phase }) => {
-    const release = await ctx.db.get(releaseId);
-    return release ? cleanupRelease(ctx, release, phase) : true;
-  },
-});
-
-export const fail = internalMutation({
-  args: { releaseId: v.id("siteReleases"), failure: v.string() },
-  handler: async (ctx, { releaseId, failure }) => {
-    await ctx.db.patch(releaseId, {
-      publicationStatus: "failed",
-      publicationFailure: failure.replaceAll(/[\r\n\t]+/gu, " ").slice(0, 300),
-      publicationUpdatedAt: Date.now(),
-    });
-  },
-});
+    for (const row of page.page) await ctx.db.delete(row._id);
+    if (!page.isDone) {
+      await scheduleLegacyCleanup(ctx, {
+        releaseId,
+        phase,
+        cursor: page.continueCursor,
+      });
+      return null;
+    }
 
-export const recordFailure = internalMutation({
-  args: { releaseId: v.id("siteReleases"), failure: v.string() },
-  handler: async (ctx, { releaseId, failure }) => {
-    await ctx.db.patch(releaseId, {
-      publicationFailure: failure.replaceAll(/[\r\n\t]+/gu, " ").slice(0, 300),
-      publicationUpdatedAt: Date.now(),
-    });
+    const nextPhase = nextLegacyCleanupPhase[phase];
+    if (nextPhase) {
+      await scheduleLegacyCleanup(ctx, { releaseId, phase: nextPhase });
+    }
+    return null;
   },
 });
 
 export const run = workflows
   .define({ args: { releaseId: v.id("siteReleases") } })
   .handler(async (step, { releaseId }): Promise<void> => {
-    let activated = false;
-    try {
-      for (const phase of [
-        "pages",
-        "libraries",
-        "folders",
-        "files",
-        "changes",
-      ] as const) {
-        let cursor: string | undefined;
-        do {
-          const page: { isDone: boolean; continueCursor: string } | null =
-            await step.runMutation(internal.releasePublication.applyBatch, {
-              releaseId,
-              phase,
-              cursor,
-            });
-          if (!page) return;
-          cursor = page.isDone ? undefined : page.continueCursor;
-        } while (cursor);
-      }
-      await step.runMutation(internal.releasePublication.activate, {
-        releaseId,
-      });
-      activated = true;
-      let cursor: string | undefined;
-      do {
-        const page: { isDone: boolean; continueCursor: string } | null =
-          await step.runMutation(
-            internal.releasePublication.clearChangesBatch,
-            {
-              releaseId,
-              cursor,
-            },
-          );
-        if (!page) return;
-        cursor = page.isDone ? undefined : page.continueCursor;
-      } while (cursor);
-      await step.runMutation(internal.releasePublication.finish, { releaseId });
-    } catch (error) {
-      const failure = error instanceof Error ? error.message : String(error);
-      if (!activated) {
-        for (const phase of cleanupPhases) {
-          let done = false;
-          while (!done) {
-            done = await step.runMutation(
-              internal.releasePublication.cleanupBatch,
-              { releaseId, phase },
-            );
-          }
-        }
-        await step.runMutation(internal.releasePublication.fail, {
-          releaseId,
-          failure,
-        });
-        return;
-      }
-      await step.runMutation(internal.releasePublication.recordFailure, {
-        releaseId,
-        failure,
-      });
-      throw error;
-    }
+    await step.runMutation(internal.releasePublication.recover, {
+      releaseId,
+    });
   });
diff --git a/packages/backend/convex/releases.ts b/packages/backend/convex/releases.ts
index abdfb821..a9024f85 100644
--- a/packages/backend/convex/releases.ts
+++ b/packages/backend/convex/releases.ts
@@ -1,23 +1,25 @@
 import { ConvexError, v } from "convex/values";
-import {
-  getStatus,
-  restart,
-  start,
-  type WorkflowId,
-} from "@convex-dev/workflow";
+import type { GenericMutationCtx } from "convex/server";
+import { getStatus, type WorkflowId } from "@convex-dev/workflow";
 import { components, internal } from "./_generated/api";
-import type { Id } from "./_generated/dataModel";
+import type { DataModel, Id } from "./_generated/dataModel";
 import { mutation, query } from "./_generated/server";
 import {
   extractionBlocksPublication,
   isPublicationInFlight,
+  isReleaseAvailable,
 } from "./model/releaseState";
 import { buildDraftSummary } from "./model/draftSummary";
-import {
-  findActivePublication,
-  promoteRelease,
-} from "./model/releaseOperations";
+import { promoteRelease } from "./model/releaseOperations";
 import { buildHistoricalReleaseContent } from "./model/releaseChangeDetails";
+import {
+  snapshotChanges,
+  snapshotFiles,
+  snapshotFolders,
+  snapshotLibraries,
+  snapshotPages,
+  clearPublishedDraftChanges,
+} from "./publication";
 import {
   isOrganizationMember,
   requireOrganizationPermission,
@@ -108,6 +110,10 @@ export const getDraftChanges = query({
   },
 });
 
+/**
+ * Backward-compatible read for clients that still poll the retired workflow.
+ * Atomic releases have no workflow status and are complete at creation time.
+ */
 export const getPublicationStatus = query({
   args: { releaseId: v.id("siteReleases") },
   returns: v.union(
@@ -150,7 +156,7 @@ export const getPublicationStatus = query({
       }
     }
     return {
-      status: release.publicationStatus,
+      status: release.publicationStatus ?? ("complete" as const),
       failure: release.publicationFailure,
     };
   },
@@ -164,14 +170,12 @@ export const list = query({
     if (!site) return [];
     const releases = await ctx.db
       .query("siteReleases")
-      .withIndex("by_site_publication_status", (q) =>
-        q.eq("siteId", siteId).eq("publicationStatus", "complete"),
-      )
+      .withIndex("by_site_number", (q) => q.eq("siteId", siteId))
       .order("desc")
       .collect();
-    return releases.map((release) =>
-      releaseSummary(release, site.liveReleaseId),
-    );
+    return releases
+      .filter(isReleaseAvailable)
+      .map((release) => releaseSummary(release, site.liveReleaseId));
   },
 });
 
@@ -206,9 +210,7 @@ export const get = query({
   ),
   handler: async (ctx, { releaseId }) => {
     const release = await ctx.db.get(releaseId);
-    if (release?.publicationStatus !== "complete") {
-      return null;
-    }
+    if (!release || !isReleaseAvailable(release)) return null;
     const site = await requireSiteForMember(ctx, release.siteId);
     if (!site) return null;
     const changes = await ctx.db
@@ -232,6 +234,11 @@ export const get = query({
   },
 });
 
+/**
+ * Publishing is atomic: the release manifest is built and activated in a
+ * single transaction. The user-visible site switches when this mutation
+ * commits; search projection runs as a derived background job.
+ */
 export const publish = mutation({
   args: {
     siteId: v.id("sites"),
@@ -262,60 +269,36 @@ export const publish = mutation({
       );
     }
 
-    const activePublication = await findActivePublication(ctx, siteId);
-    if (
-      activePublication &&
-      isPublicationInFlight(activePublication.publicationStatus)
-    ) {
-      if (!activePublication.publicationWorkflowId) {
-        throw new ConvexError("Publication workflow state is missing");
-      }
-      const workflowStatus = await getStatus(
-        ctx,
-        components.workflow,
-        activePublication.publicationWorkflowId as WorkflowId,
-      );
-      if (workflowStatus.type === "failed") {
-        await restart(
-          ctx,
-          components.workflow,
-          activePublication.publicationWorkflowId as WorkflowId,
-          { startAsync: true },
-        );
-        if (activePublication.sourceDraftRevision !== draftRevision) {
-          throw new ConvexError(
-            "A previous publication recovery was restarted. Try publishing the latest draft again shortly.",
-          );
-        }
-      }
-      if (activePublication.sourceDraftRevision === draftRevision) {
-        return {
-          releaseId: activePublication._id,
-          number: activePublication.number,
-          reused: false,
-        };
-      }
-      throw new ConvexError(
-        "A previous publication is still finishing. Try again shortly.",
-      );
-    }
-
     const matchingRelease = site.draftBaseReleaseId
       ? await ctx.db.get(site.draftBaseReleaseId)
       : null;
+    if (
+      matchingRelease &&
+      (matchingRelease.siteId !== siteId ||
+        !isReleaseAvailable(matchingRelease))
+    ) {
+      throw new ConvexError("The draft base version is unavailable");
+    }
     const pendingChange = await ctx.db
       .query("draftChanges")
       .withIndex("by_site", (q) => q.eq("siteId", siteId))
       .first();
-    if (
-      matchingRelease &&
-      matchingRelease.publicationStatus === "complete" &&
-      !pendingChange
-    ) {
+    if (matchingRelease && !pendingChange) {
       if (site.liveReleaseId === matchingRelease._id) {
         throw new ConvexError("This draft is already live");
       }
-      await promoteRelease(ctx, site, matchingRelease, auth.userId);
+      const liveSearchProjectionGeneration = await promoteRelease(
+        ctx,
+        site,
+        matchingRelease,
+        auth.userId,
+      );
+      await scheduleLiveSearchProjection(
+        ctx,
+        siteId,
+        matchingRelease._id,
+        liveSearchProjectionGeneration,
+      );
       return {
         releaseId: matchingRelease._id,
         number: matchingRelease.number,
@@ -379,24 +362,81 @@ export const publish = mutation({
       createdAt: now,
       pageCount: 0,
       changeCount: 0,
-      publicationStatus: "building",
-      publicationUpdatedAt: now,
     });
+
+    // Change details diff the draft against the previous base release, so
+    // they must be captured before activation moves the base pointer.
+    const changeCount = await snapshotChanges(ctx, site, releaseId);
+    const pageCount = await snapshotPages(ctx, releaseId, siteId);
+    if (pageCount === 0) {
+      throw new ConvexError("The site must contain at least one page");
+    }
+    await snapshotLibraries(ctx, releaseId, siteId);
+    await snapshotFolders(ctx, releaseId, siteId);
+    await snapshotFiles(ctx, releaseId, siteId, site);
+
+    await ctx.db.patch(releaseId, { pageCount, changeCount });
+    const liveSearchProjectionGeneration = await activateRelease(
+      ctx,
+      site,
+      releaseId,
+      auth.userId,
+    );
+    await clearPublishedDraftChanges(ctx, siteId);
+
     await ctx.db.patch(siteId, {
       nextReleaseNumber: number + 1,
       updatedAt: now,
     });
-    const publicationWorkflowId = await start(
+    await scheduleLiveSearchProjection(
       ctx,
-      internal.releasePublication.run,
-      { releaseId },
-      { startAsync: true },
+      siteId,
+      releaseId,
+      liveSearchProjectionGeneration,
     );
-    await ctx.db.patch(releaseId, { publicationWorkflowId });
     return { releaseId, number, reused: false };
   },
 });
 
+async function activateRelease(
+  ctx: GenericMutationCtx<DataModel>,
+  site: NonNullable<Awaited<ReturnType<typeof requireSiteForMember>>>,
+  releaseId: Id<"siteReleases">,
+  actorId: string,
+) {
+  const now = Date.now();
+  const liveSearchProjectionGeneration =
+    (site.liveSearchProjectionGeneration ?? 0) + 1;
+  await ctx.db.patch(site._id, {
+    liveReleaseId: releaseId,
+    draftBaseReleaseId: releaseId,
+    updatedAt: now,
+    liveSearchProjectionGeneration,
+  });
+  await ctx.db.insert("publicationEvents", {
+    siteId: site._id,
+    action: site.liveReleaseId ? "update" : "publish",
+    fromReleaseId: site.liveReleaseId,
+    toReleaseId: releaseId,
+    actorId,
+    createdAt: now,
+  });
+  return liveSearchProjectionGeneration;
+}
+
+async function scheduleLiveSearchProjection(
+  ctx: Pick<GenericMutationCtx<DataModel>, "scheduler">,
+  siteId: Id<"sites">,
+  liveReleaseId: Id<"siteReleases"> | undefined,
+  liveSearchProjectionGeneration: number,
+) {
+  await ctx.scheduler.runAfter(0, internal.publication.projectLiveSearch, {
+    siteId,
+    expectedLiveReleaseId: liveReleaseId,
+    expectedLiveSearchProjectionGeneration: liveSearchProjectionGeneration,
+  });
+}
+
 export const makeLive = mutation({
   args: {
     releaseId: v.id("siteReleases"),
@@ -412,7 +452,7 @@ export const makeLive = mutation({
       site.organizationId,
       { resource: "publication", action: "publish" },
     );
-    if (release.publicationStatus !== "complete") {
+    if (!isReleaseAvailable(release)) {
       throw new ConvexError("Release publication is not complete");
     }
     if (site.activeDraftRestoreId) {
@@ -421,7 +461,18 @@ export const makeLive = mutation({
       );
     }
     if (site.liveReleaseId === releaseId) return null;
-    await promoteRelease(ctx, site, release, auth.userId);
+    const liveSearchProjectionGeneration = await promoteRelease(
+      ctx,
+      site,
+      release,
+      auth.userId,
+    );
+    await scheduleLiveSearchProjection(
+      ctx,
+      site._id,
+      releaseId,
+      liveSearchProjectionGeneration,
+    );
     return null;
   },
 });
@@ -444,9 +495,12 @@ export const unpublish = mutation({
     }
     if (!site.liveReleaseId) return null;
     const now = Date.now();
+    const liveSearchProjectionGeneration =
+      (site.liveSearchProjectionGeneration ?? 0) + 1;
     await ctx.db.patch(siteId, {
       liveReleaseId: undefined,
       updatedAt: now,
+      liveSearchProjectionGeneration,
     });
     await ctx.db.insert("publicationEvents", {
       siteId,
@@ -455,6 +509,12 @@ export const unpublish = mutation({
       actorId: auth.userId,
       createdAt: now,
     });
+    await scheduleLiveSearchProjection(
+      ctx,
+      siteId,
+      undefined,
+      liveSearchProjectionGeneration,
+    );
     return null;
   },
 });
diff --git a/packages/backend/convex/schema.ts b/packages/backend/convex/schema.ts
index 8a8fda56..f8f7d7d1 100644
--- a/packages/backend/convex/schema.ts
+++ b/packages/backend/convex/schema.ts
@@ -37,6 +37,8 @@ export default defineSchema({
     activeDraftRestoreId: v.optional(v.id("draftRestores")),
     nextReleaseNumber: v.number(),
     liveReleaseId: v.optional(v.id("siteReleases")),
+    /** Fences overlapping asynchronous live-search projections. */
+    liveSearchProjectionGeneration: v.optional(v.number()),
   })
     .index("by_organization", ["organizationId"])
     .index("by_organization_slug", ["organizationId", "slug"]),
@@ -86,6 +88,12 @@ export default defineSchema({
     contentHash: v.string(),
     contentSize: v.number(),
     payloadId: v.id("contentPayloads"),
+    /**
+     * Extracted plain text captured once when the revision is written.
+     * Publication, search projection, and metadata reads consume this
+     * instead of re-parsing the payload.
+     */
+    searchText: v.optional(v.string()),
     libraryIds: v.array(v.id("documentLibraries")),
     fileIds: v.array(v.id("files")),
     pageIds: v.array(v.id("pages")),
@@ -106,6 +114,39 @@ export default defineSchema({
     .index("by_page", ["pageId"])
     .index("by_revision", ["revisionId"]),
 
+  /**
+   * Progress for the publication manifest backfill. The migration is kept
+   * separate from the legacy publication workflow so it can be dry-run and
+   * resumed without changing publication behavior.
+   */
+  publicationMigrationRuns: defineTable({
+    migrationKey: v.string(),
+    runId: v.string(),
+    mode: v.union(v.literal("dryRun"), v.literal("apply")),
+    phase: v.union(
+      v.literal("revisions"),
+      v.literal("pages"),
+      v.literal("files"),
+      v.literal("search"),
+      v.literal("sites"),
+    ),
+    cursor: v.optional(v.string()),
+    status: v.union(
+      v.literal("running"),
+      v.literal("completed"),
+      v.literal("failed"),
+    ),
+    scannedCount: v.number(),
+    migratedCount: v.number(),
+    skippedCount: v.number(),
+    scheduledCount: v.optional(v.number()),
+    errorCount: v.number(),
+    startedAt: v.number(),
+    updatedAt: v.number(),
+    completedAt: v.optional(v.number()),
+    failureSummary: v.optional(v.string()),
+  }).index("by_migration_run", ["migrationKey", "runId"]),
+
   draftChanges: defineTable({
     siteId: v.id("sites"),
     entityType: v.union(
@@ -329,6 +370,8 @@ export default defineSchema({
   searchEntries: defineTable({
     siteId: v.id("sites"),
     scopeId: v.string(),
+    /** Set only for published entries; draft entries remain scope-local. */
+    releaseId: v.optional(v.id("siteReleases")),
     kind: v.union(v.literal("file"), v.literal("page")),
     sourceId: v.string(),
     title: v.string(),
@@ -361,19 +404,24 @@ export default defineSchema({
     createdAt: v.number(),
     pageCount: v.number(),
     changeCount: v.number(),
-    publicationStatus: v.union(
-      v.literal("building"),
-      v.literal("clearing"),
-      v.literal("complete"),
-      v.literal("failed"),
+    /**
+     * Legacy publication workflow fields remain optional so existing rows can
+     * still be read while new releases use atomic activation.
+     */
+    publicationStatus: v.optional(
+      v.union(
+        v.literal("building"),
+        v.literal("clearing"),
+        v.literal("complete"),
+        v.literal("failed"),
+      ),
     ),
     publicationFailure: v.optional(v.string()),
     publicationWorkflowId: v.optional(v.string()),
     publicationUpdatedAt: v.optional(v.number()),
   })
     .index("by_site", ["siteId"])
-    .index("by_site_number", ["siteId", "number"])
-    .index("by_site_publication_status", ["siteId", "publicationStatus"]),
+    .index("by_site_number", ["siteId", "number"]),
 
   draftRestores: defineTable({
     siteId: v.id("sites"),
@@ -407,7 +455,14 @@ export default defineSchema({
     order: v.number(),
     contentRevisionId: v.optional(v.id("contentRevisions")),
     contentHash: v.optional(v.string()),
-    descriptionText: v.string(),
+    /**
+     * Short description snippet (bounded) resolved from the released
+     * revision's captured search text. The live projection owns its searchable
+     * copy; the release row keeps only this metadata snippet.
+     */
+    description: v.optional(v.string()),
+    /** Compatibility with releases created before the description rename. */
+    descriptionText: v.optional(v.string()),
     updatedAt: v.number(),
   })
     .index("by_content_revision", ["contentRevisionId"])
@@ -453,6 +508,8 @@ export default defineSchema({
     order: v.number(),
     uploadedBy: v.string(),
     createdAt: v.number(),
+    /** Immutable text captured for this released file's search projection. */
+    extractedText: v.optional(v.string()),
   })
     .index("by_release", ["releaseId"])
     .index("by_release_file", ["releaseId", "fileId"])
diff --git a/packages/backend/convex/search.test.ts b/packages/backend/convex/search.test.ts
index 8dbfff00..02b7ef5a 100644
--- a/packages/backend/convex/search.test.ts
+++ b/packages/backend/convex/search.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   extractSearchExcerpt,
+  isPublishedSearchEntryForRelease,
   mergeSearchMatches,
   normalizeSearchLimit,
 } from "./search";
@@ -67,3 +68,23 @@ describe("search result limits", () => {
     expect(normalizeSearchLimit(500)).toBe(50);
   });
 });
+
+describe("published search release fencing", () => {
+  test("ignores entries that were not projected for the current release", () => {
+    expect(
+      isPublishedSearchEntryForRelease(
+        { releaseId: "release-2" as never },
+        "release-2" as never,
+      ),
+    ).toBe(true);
+    expect(
+      isPublishedSearchEntryForRelease(
+        { releaseId: "release-1" as never },
+        "release-2" as never,
+      ),
+    ).toBe(false);
+    expect(isPublishedSearchEntryForRelease({}, "release-2" as never)).toBe(
+      false,
+    );
+  });
+});
diff --git a/packages/backend/convex/search.ts b/packages/backend/convex/search.ts
index 52c30ec3..00d15158 100644
--- a/packages/backend/convex/search.ts
+++ b/packages/backend/convex/search.ts
@@ -3,13 +3,9 @@ import { v } from "convex/values";
 import { internal } from "./_generated/api";
 import type { DataModel, Doc, Id } from "./_generated/dataModel";
 import { internalMutation, query } from "./_generated/server";
+import { readContentRevisionSearchText } from "./model/contentObjects";
 import { assertDraftReadable } from "./model/draft";
-import { readPageContent } from "./model/pageDocuments";
-import {
-  extractOpenEditorText,
-  parseOpenEditorDocument,
-  type OpenEditorDocument,
-} from "./pageContentFormat";
+import { isReleaseAvailable } from "./model/releaseState";
 import { isOrganizationMember } from "./permissions";
 import { canRenderPublishedSite, resolvePublishedSiteAccess } from "./sharing";
 
@@ -30,15 +26,33 @@ export function draftSearchScope(siteId: Id<"sites">): string {
   return `draft:${siteId}`;
 }
 
+/**
+ * One search scope per site for the published surface, rebuilt from the
+ * live release manifest by the post-publication projection. Full text is
+ * stored once per site, not once per historical release.
+ */
+export function liveSearchScope(siteId: Id<"sites">): string {
+  return `live:${siteId}`;
+}
+
+/** Compatibility scope used by releases created before live projection. */
 export function releaseSearchScope(releaseId: Id<"siteReleases">): string {
   return `release:${releaseId}`;
 }
 
+export function isPublishedSearchEntryForRelease(
+  entry: Pick<Doc<"searchEntries">, "releaseId">,
+  releaseId: Id<"siteReleases">,
+): boolean {
+  return entry.releaseId === releaseId;
+}
+
 export async function upsertSearchEntry(
   ctx: MutationCtx,
   value: {
     siteId: Id<"sites">;
     scopeId: string;
+    releaseId?: Id<"siteReleases">;
     kind: SearchKind;
     sourceId: string;
     title: string;
@@ -104,19 +118,20 @@ export async function queuePageContentIndex(
 export async function indexPageContent(
   ctx: MutationCtx,
   pageId: Id<"pages">,
-  document?: OpenEditorDocument,
 ): Promise<void> {
   const page = await ctx.db.get(pageId);
   if (!page || page.deletedAt !== undefined) return;
-  const searchableDocument =
-    document ?? (await readPageContent(ctx, pageId)).document;
+  const record = await ctx.db
+    .query("pageDocuments")
+    .withIndex("by_page", (q) => q.eq("pageId", pageId))
+    .unique();
   await upsertSearchEntry(ctx, {
     siteId: page.siteId,
     scopeId: draftSearchScope(page.siteId),
     kind: "page",
     sourceId: pageId,
     title: page.title,
-    text: searchableDocument ? extractOpenEditorText(searchableDocument) : "",
+    text: await readContentRevisionSearchText(ctx, record?.revisionId),
   });
 }
 
@@ -132,17 +147,7 @@ export const flushPageIndex = internalMutation({
       .withIndex("by_page", (q) => q.eq("pageId", pageId))
       .unique();
     if (!current || current.revisionId !== revisionId) return null;
-    const revision = await ctx.db.get(revisionId);
-    if (!revision) return null;
-    const payload = await ctx.db.get(revision.payloadId);
-    if (!payload) return null;
-    const page = await ctx.db.get(pageId);
-    if (!page || page.deletedAt !== undefined) return null;
-    await indexPageContent(
-      ctx,
-      pageId,
-      parseOpenEditorDocument(payload.content),
-    );
+    await indexPageContent(ctx, pageId);
     return null;
   },
 });
@@ -342,8 +347,10 @@ export const run = query({
     } else {
       const access = await resolvePublishedSiteAccess(ctx, site);
       if (!canRenderPublishedSite(access) || !site.liveReleaseId) return [];
+      const release = await ctx.db.get(site.liveReleaseId);
+      if (!release || !isReleaseAvailable(release)) return [];
       releaseId = site.liveReleaseId;
-      scopeId = releaseSearchScope(releaseId);
+      scopeId = liveSearchScope(siteId);
     }
 
     const matches = await searchScope(
@@ -352,8 +359,24 @@ export const run = query({
       searchTerm,
       normalizeSearchLimit(limit),
     );
+    let currentMatches = releaseId
+      ? matches.filter(({ doc }) =>
+          isPublishedSearchEntryForRelease(doc, releaseId),
+        )
+      : matches;
+    if (releaseId && currentMatches.length === 0) {
+      const legacyMatches = await searchScope(
+        ctx,
+        releaseSearchScope(releaseId),
+        searchTerm,
+        normalizeSearchLimit(limit),
+      );
+      if (legacyMatches.length > 0) {
+        currentMatches = legacyMatches;
+      }
+    }
     const hydrated = await Promise.all(
-      matches.map(({ doc, match }) =>
+      currentMatches.map(({ doc, match }) =>
         releaseId
           ? hydrateReleaseResult(ctx, releaseId, doc, match, searchTerm)
           : hydrateDraftResult(ctx, doc, match, searchTerm),
diff --git a/packages/backend/convex/siteDomains.ts b/packages/backend/convex/siteDomains.ts
index 43c29e66..158f09e1 100644
--- a/packages/backend/convex/siteDomains.ts
+++ b/packages/backend/convex/siteDomains.ts
@@ -1,6 +1,7 @@
 import { v } from "convex/values";
 import { mutation, query } from "./_generated/server";
 import { getAuthOrganizationById } from "./authComponent/model";
+import { isReleaseAvailable } from "./model/releaseState";
 import { requireOrganizationPermission } from "./permissions";
 
 const domainStatus = v.union(
@@ -20,6 +21,8 @@ export const resolve = query({
 
     const site = await ctx.db.get(mapping.siteId);
     if (!site?.liveReleaseId) return null;
+    const release = await ctx.db.get(site.liveReleaseId);
+    if (!release || !isReleaseAvailable(release)) return null;
     const organization = await getAuthOrganizationById(
       ctx,
       site.organizationId,

From 417e454cf8f34f9b4b37f2bccec7dea11c0d9734 Mon Sep 17 00:00:00 2001
From: naaiyy <naaiyyyy@gmail.com>
Date: Fri, 28 Aug 2026 21:40:33 +0200
Subject: [PATCH 2/6] Fix Convex JWT cookie for OAuth proxy callbacks

---
 packages/backend/convex/auth.ts | 35 ++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/packages/backend/convex/auth.ts b/packages/backend/convex/auth.ts
index efe27b25..147d4f6b 100644
--- a/packages/backend/convex/auth.ts
+++ b/packages/backend/convex/auth.ts
@@ -1,5 +1,6 @@
 import { type GenericCtx, createClient } from "@convex-dev/better-auth";
 import { convex } from "@convex-dev/better-auth/plugins";
+import { createAuthMiddleware } from "better-auth/api";
 import { type BetterAuthOptions, betterAuth } from "better-auth/minimal";
 import { oAuthProxy, organization } from "better-auth/plugins";
 import { internal } from "./_generated/api";
@@ -193,6 +194,38 @@ export const authComponent = createClient<DataModel, never>(
 export const createAuthOptions = (ctx: GenericCtx<DataModel>) => {
   const { baseURL, trustedOrigins, crossSubdomainCookieDomain } =
     getAuthUrlConfig();
+  const convexPlugin = convex({ authConfig });
+  const convexTokenEndpoint = convexPlugin.endpoints?.getToken;
+
+  if (!convexTokenEndpoint) {
+    throw new Error("Convex Better Auth plugin is missing its token endpoint");
+  }
+
+  // @convex-dev/better-auth does not include the OAuth proxy callback in the
+  // matcher that writes the Convex JWT cookie. The proxy does create
+  // `newSession`, so generate the SSR token from that session here.
+  convexPlugin.hooks?.after?.push({
+    matcher: (hookContext) => hookContext.path === "/oauth-proxy-callback",
+    handler: createAuthMiddleware(async (hookContext) => {
+      const newSession = hookContext.context.newSession;
+      if (!newSession) return;
+
+      const originalSession = hookContext.context.session;
+      hookContext.context.session = newSession;
+      try {
+        await convexTokenEndpoint({
+          ...hookContext,
+          headers: new Headers(),
+          method: "GET",
+          asResponse: false,
+          returnHeaders: false,
+          returnStatus: false,
+        } as never);
+      } finally {
+        hookContext.context.session = originalSession;
+      }
+    }),
+  });
 
   return {
     baseURL,
@@ -299,7 +332,7 @@ export const createAuthOptions = (ctx: GenericCtx<DataModel>) => {
           },
         },
       }),
-      convex({ authConfig }),
+      convexPlugin,
     ],
   } satisfies BetterAuthOptions;
 };

From 448ef6c6ec2f2b093d936444d44b376943aa9729 Mon Sep 17 00:00:00 2001
From: naaiyy <naaiyyyy@gmail.com>
Date: Fri, 28 Aug 2026 22:07:30 +0200
Subject: [PATCH 3/6] Clean publish error toasts

---
 .../features/editor/publish-dialog.test.ts    | 12 ++++++++++
 apps/web/features/editor/publish-dialog.tsx   | 22 ++++++++++++++++---
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/apps/web/features/editor/publish-dialog.test.ts b/apps/web/features/editor/publish-dialog.test.ts
index 3d7e3134..29176c53 100644
--- a/apps/web/features/editor/publish-dialog.test.ts
+++ b/apps/web/features/editor/publish-dialog.test.ts
@@ -21,4 +21,16 @@ describe("publish error messages", () => {
       "Publication failed",
     );
   });
+
+  test("unwraps the Convex client error envelope", () => {
+    expect(
+      getPublishErrorMessage(
+        new Error(
+          "[CONVEX M(releases:publish)] [Request ID: abc] Server Error Uncaught ConvexError: The draft changed while publishing. Review the latest changes and try again. at handler (../convex/releases.ts:267:8) Called by client",
+        ),
+      ),
+    ).toBe(
+      "The draft changed while publishing. Review the latest changes and try again.",
+    );
+  });
 });
diff --git a/apps/web/features/editor/publish-dialog.tsx b/apps/web/features/editor/publish-dialog.tsx
index a15e4656..900f1d32 100644
--- a/apps/web/features/editor/publish-dialog.tsx
+++ b/apps/web/features/editor/publish-dialog.tsx
@@ -31,8 +31,12 @@ export function getPublishErrorMessage(
   error: unknown,
   fallback = "The site could not publish",
 ): string {
-  if (error instanceof Error && error.message.trim()) return error.message;
-  if (typeof error === "string" && error.trim()) return error;
+  if (error instanceof Error && error.message.trim()) {
+    return cleanPublishErrorMessage(error.message);
+  }
+  if (typeof error === "string" && error.trim()) {
+    return cleanPublishErrorMessage(error);
+  }
   if (
     error &&
     typeof error === "object" &&
@@ -40,11 +44,23 @@ export function getPublishErrorMessage(
     typeof error.message === "string" &&
     error.message.trim()
   ) {
-    return error.message;
+    return cleanPublishErrorMessage(error.message);
   }
   return fallback;
 }
 
+function cleanPublishErrorMessage(message: string): string {
+  const convexErrorMarker = "Uncaught ConvexError:";
+  const markerIndex = message.indexOf(convexErrorMarker);
+  if (markerIndex === -1) return message;
+
+  const errorMessage = message.slice(markerIndex + convexErrorMarker.length);
+  return errorMessage
+    .split(/\s+at\s+[^\s(]+\s*\(/, 1)[0]
+    .replace(/\s+Called by client\s*$/, "")
+    .trim();
+}
+
 export type DraftSummary = {
   draftRevision: number;
   hasUnpublishedChanges: boolean;

From 5b868e697a73753525333a58ce9ae8a9cc9b6d00 Mon Sep 17 00:00:00 2001
From: naaiyy <naaiyyyy@gmail.com>
Date: Fri, 28 Aug 2026 22:08:16 +0200
Subject: [PATCH 4/6] Fix publish error message typing

---
 apps/web/features/editor/publish-dialog.tsx | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/apps/web/features/editor/publish-dialog.tsx b/apps/web/features/editor/publish-dialog.tsx
index 900f1d32..0db37a95 100644
--- a/apps/web/features/editor/publish-dialog.tsx
+++ b/apps/web/features/editor/publish-dialog.tsx
@@ -55,10 +55,11 @@ function cleanPublishErrorMessage(message: string): string {
   if (markerIndex === -1) return message;
 
   const errorMessage = message.slice(markerIndex + convexErrorMarker.length);
-  return errorMessage
-    .split(/\s+at\s+[^\s(]+\s*\(/, 1)[0]
-    .replace(/\s+Called by client\s*$/, "")
-    .trim();
+  const [userMessage = errorMessage] = errorMessage.split(
+    /\s+at\s+[^\s(]+\s*\(/,
+    1,
+  );
+  return userMessage.replace(/\s+Called by client\s*$/, "").trim();
 }
 
 export type DraftSummary = {

From 4639def1bdb34f9aa2b82fce461d0a9e633337cf Mon Sep 17 00:00:00 2001
From: naaiyy <naaiyyyy@gmail.com>
Date: Fri, 28 Aug 2026 23:11:25 +0200
Subject: [PATCH 5/6] Fix publish error toast normalization

---
 .../features/editor/publish-dialog.test.ts    | 22 +++++++++
 apps/web/features/editor/publish-dialog.tsx   | 48 ++++++++++++++++---
 2 files changed, 64 insertions(+), 6 deletions(-)

diff --git a/apps/web/features/editor/publish-dialog.test.ts b/apps/web/features/editor/publish-dialog.test.ts
index 29176c53..d280756c 100644
--- a/apps/web/features/editor/publish-dialog.test.ts
+++ b/apps/web/features/editor/publish-dialog.test.ts
@@ -33,4 +33,26 @@ describe("publish error messages", () => {
       "The draft changed while publishing. Review the latest changes and try again.",
     );
   });
+
+  test("prefers Convex error data over the client error envelope", () => {
+    const error = new ConvexError(
+      "[CONVEX M(releases:publish)] [Request ID: abc] Server Error\n  Called by client",
+    );
+    error.data =
+      "The draft changed while publishing. Review the latest changes and try again.";
+
+    expect(getPublishErrorMessage(error)).toBe(
+      "The draft changed while publishing. Review the latest changes and try again.",
+    );
+  });
+
+  test("uses the fallback for an empty Convex error envelope", () => {
+    expect(
+      getPublishErrorMessage(
+        new Error(
+          "[CONVEX M(releases:publish)] [Request ID: abc] Server Error\n  Called by client",
+        ),
+      ),
+    ).toBe("The site could not publish");
+  });
 });
diff --git a/apps/web/features/editor/publish-dialog.tsx b/apps/web/features/editor/publish-dialog.tsx
index 0db37a95..d4f3ad63 100644
--- a/apps/web/features/editor/publish-dialog.tsx
+++ b/apps/web/features/editor/publish-dialog.tsx
@@ -31,11 +31,14 @@ export function getPublishErrorMessage(
   error: unknown,
   fallback = "The site could not publish",
 ): string {
+  const dataMessage = getPublishErrorDataMessage(error);
+  if (dataMessage) return dataMessage;
+
   if (error instanceof Error && error.message.trim()) {
-    return cleanPublishErrorMessage(error.message);
+    return cleanPublishErrorMessage(error.message) || fallback;
   }
   if (typeof error === "string" && error.trim()) {
-    return cleanPublishErrorMessage(error);
+    return cleanPublishErrorMessage(error) || fallback;
   }
   if (
     error &&
@@ -44,17 +47,50 @@ export function getPublishErrorMessage(
     typeof error.message === "string" &&
     error.message.trim()
   ) {
-    return cleanPublishErrorMessage(error.message);
+    return cleanPublishErrorMessage(error.message) || fallback;
   }
   return fallback;
 }
 
+function getPublishErrorDataMessage(error: unknown): string | null {
+  if (!error || typeof error !== "object" || !("data" in error)) {
+    return null;
+  }
+
+  const data = error.data;
+  if (typeof data === "string" && data.trim()) {
+    return cleanPublishErrorMessage(data) || null;
+  }
+  if (
+    data &&
+    typeof data === "object" &&
+    "message" in data &&
+    typeof data.message === "string" &&
+    data.message.trim()
+  ) {
+    return cleanPublishErrorMessage(data.message) || null;
+  }
+  return null;
+}
+
 function cleanPublishErrorMessage(message: string): string {
+  const trimmedMessage = message.trim();
   const convexErrorMarker = "Uncaught ConvexError:";
-  const markerIndex = message.indexOf(convexErrorMarker);
-  if (markerIndex === -1) return message;
+  const markerIndex = trimmedMessage.indexOf(convexErrorMarker);
+  if (markerIndex === -1) {
+    if (
+      /^\[CONVEX [^\]]+\([^)]*\)\](?: \[Request ID: [^\]]+\])? Server Error(?:\s+Called by client)?$/s.test(
+        trimmedMessage,
+      )
+    ) {
+      return "";
+    }
+    return trimmedMessage;
+  }
 
-  const errorMessage = message.slice(markerIndex + convexErrorMarker.length);
+  const errorMessage = trimmedMessage.slice(
+    markerIndex + convexErrorMarker.length,
+  );
   const [userMessage = errorMessage] = errorMessage.split(
     /\s+at\s+[^\s(]+\s*\(/,
     1,

From 4a5bcfc84915e3bca9c8f5e3a3ba12b80d7a6840 Mon Sep 17 00:00:00 2001
From: naaiyy <naaiyyyy@gmail.com>
Date: Fri, 28 Aug 2026 23:51:27 +0200
Subject: [PATCH 6/6] Add one-time publication data cleanup

---
 packages/backend/convex/_generated/api.d.ts   |   2 +
 packages/backend/convex/publicationCleanup.ts | 216 ++++++++++++++++++
 2 files changed, 218 insertions(+)
 create mode 100644 packages/backend/convex/publicationCleanup.ts

diff --git a/packages/backend/convex/_generated/api.d.ts b/packages/backend/convex/_generated/api.d.ts
index 9354db65..e25e8772 100644
--- a/packages/backend/convex/_generated/api.d.ts
+++ b/packages/backend/convex/_generated/api.d.ts
@@ -66,6 +66,7 @@ import type * as pageGuests from "../pageGuests.js";
 import type * as pages from "../pages.js";
 import type * as permissions from "../permissions.js";
 import type * as publication from "../publication.js";
+import type * as publicationCleanup from "../publicationCleanup.js";
 import type * as publicationMigrations from "../publicationMigrations.js";
 import type * as published from "../published.js";
 import type * as releasePublication from "../releasePublication.js";
@@ -157,6 +158,7 @@ declare const fullApi: ApiFromModules<{
   pages: typeof pages;
   permissions: typeof permissions;
   publication: typeof publication;
+  publicationCleanup: typeof publicationCleanup;
   publicationMigrations: typeof publicationMigrations;
   published: typeof published;
   releasePublication: typeof releasePublication;
diff --git a/packages/backend/convex/publicationCleanup.ts b/packages/backend/convex/publicationCleanup.ts
new file mode 100644
index 00000000..28da9688
--- /dev/null
+++ b/packages/backend/convex/publicationCleanup.ts
@@ -0,0 +1,216 @@
+import {
+  cleanup as cleanupWorkflow,
+  getStatus,
+  type WorkflowId,
+  type WorkflowStatus,
+} from "@convex-dev/workflow";
+import { v } from "convex/values";
+import { components, internal } from "./_generated/api";
+import type { Id } from "./_generated/dataModel";
+import type { MutationCtx } from "./_generated/server";
+import { internalMutation } from "./_generated/server";
+
+const CLEANUP_BATCH_SIZE = 25;
+
+const cleanupPhase = v.union(
+  v.literal("releases"),
+  v.literal("pages"),
+  v.literal("search"),
+  v.literal("migrationRuns"),
+);
+
+type CleanupPhase = "releases" | "pages" | "search" | "migrationRuns";
+
+const nextPhase: Record<CleanupPhase, CleanupPhase | undefined> = {
+  releases: "pages",
+  pages: "search",
+  search: "migrationRuns",
+  migrationRuns: undefined,
+};
+
+async function scheduleNext(
+  ctx: Pick<MutationCtx, "scheduler">,
+  args: { phase: CleanupPhase; cursor?: string },
+) {
+  await ctx.scheduler.runAfter(0, internal.publicationCleanup.run, args);
+}
+
+async function assertReleaseHasNoReferences(
+  ctx: MutationCtx,
+  releaseId: Id<"siteReleases">,
+  siteId: Id<"sites">,
+): Promise<void> {
+  const siteReference = await ctx.db
+    .query("sites")
+    .filter((q) =>
+      q.or(
+        q.eq(q.field("liveReleaseId"), releaseId),
+        q.eq(q.field("draftBaseReleaseId"), releaseId),
+      ),
+    )
+    .first();
+  const successor = await ctx.db
+    .query("siteReleases")
+    .filter((q) => q.eq(q.field("previousReleaseId"), releaseId))
+    .first();
+  const [page, library, folder, file, change] = await Promise.all([
+    ctx.db
+      .query("releasePages")
+      .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+      .first(),
+    ctx.db
+      .query("releaseLibraries")
+      .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+      .first(),
+    ctx.db
+      .query("releaseFolders")
+      .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+      .first(),
+    ctx.db
+      .query("releaseFiles")
+      .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+      .first(),
+    ctx.db
+      .query("releaseChanges")
+      .withIndex("by_release", (q) => q.eq("releaseId", releaseId))
+      .first(),
+  ]);
+  const event = (await ctx.db
+    .query("publicationEvents")
+    .withIndex("by_site", (q) => q.eq("siteId", siteId))
+    .filter((q) =>
+      q.or(
+        q.eq(q.field("fromReleaseId"), releaseId),
+        q.eq(q.field("toReleaseId"), releaseId),
+      ),
+    )
+    .first()) as unknown;
+
+  if (
+    siteReference ||
+    successor ||
+    page ||
+    library ||
+    folder ||
+    file ||
+    change ||
+    event
+  ) {
+    throw new Error(`Failed release ${releaseId} still has references`);
+  }
+}
+
+async function cleanupWorkflowStorage(
+  ctx: MutationCtx,
+  workflowId: string,
+): Promise<void> {
+  const typedWorkflowId = workflowId as WorkflowId;
+  let status: WorkflowStatus;
+  try {
+    status = await getStatus(ctx, components.workflow, typedWorkflowId);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("not found")) {
+      return;
+    }
+    throw error;
+  }
+  if (status.type === "inProgress") {
+    throw new Error(
+      `Legacy publication workflow ${workflowId} is still active`,
+    );
+  }
+  await cleanupWorkflow(ctx, components.workflow, typedWorkflowId);
+}
+
+export const run = internalMutation({
+  args: {
+    phase: cleanupPhase,
+    cursor: v.optional(v.string()),
+  },
+  returns: v.null(),
+  handler: async (ctx, { phase, cursor }) => {
+    if (phase === "releases") {
+      const page = await ctx.db
+        .query("siteReleases")
+        .paginate({ cursor: cursor ?? null, numItems: CLEANUP_BATCH_SIZE });
+      for (const release of page.page) {
+        if (release.publicationStatus === "failed") {
+          await assertReleaseHasNoReferences(ctx, release._id, release.siteId);
+          if (release.publicationWorkflowId) {
+            await cleanupWorkflowStorage(ctx, release.publicationWorkflowId);
+          }
+          await ctx.db.delete(release._id);
+          continue;
+        }
+        if (
+          release.publicationStatus !== undefined ||
+          release.publicationFailure !== undefined ||
+          release.publicationWorkflowId !== undefined ||
+          release.publicationUpdatedAt !== undefined
+        ) {
+          if (release.publicationWorkflowId) {
+            await cleanupWorkflowStorage(ctx, release.publicationWorkflowId);
+          }
+          await ctx.db.patch(release._id, {
+            publicationStatus: undefined,
+            publicationFailure: undefined,
+            publicationWorkflowId: undefined,
+            publicationUpdatedAt: undefined,
+          });
+        }
+      }
+      if (!page.isDone) {
+        await scheduleNext(ctx, { phase, cursor: page.continueCursor });
+      } else {
+        await scheduleNext(ctx, { phase: nextPhase[phase]! });
+      }
+      return null;
+    }
+
+    if (phase === "pages") {
+      const page = await ctx.db
+        .query("releasePages")
+        .paginate({ cursor: cursor ?? null, numItems: CLEANUP_BATCH_SIZE });
+      for (const releasePage of page.page) {
+        if (releasePage.descriptionText !== undefined) {
+          await ctx.db.patch(releasePage._id, { descriptionText: undefined });
+        }
+      }
+      if (!page.isDone) {
+        await scheduleNext(ctx, { phase, cursor: page.continueCursor });
+      } else {
+        await scheduleNext(ctx, { phase: nextPhase[phase]! });
+      }
+      return null;
+    }
+
+    if (phase === "search") {
+      const page = await ctx.db
+        .query("searchEntries")
+        .paginate({ cursor: cursor ?? null, numItems: CLEANUP_BATCH_SIZE });
+      for (const entry of page.page) {
+        if (
+          entry.scopeId.startsWith("release:") ||
+          entry.scopeId.startsWith("site:")
+        ) {
+          await ctx.db.delete(entry._id);
+        }
+      }
+      if (!page.isDone) {
+        await scheduleNext(ctx, { phase, cursor: page.continueCursor });
+      } else {
+        await scheduleNext(ctx, { phase: nextPhase[phase]! });
+      }
+      return null;
+    }
+
+    const page = await ctx.db
+      .query("publicationMigrationRuns")
+      .paginate({ cursor: cursor ?? null, numItems: CLEANUP_BATCH_SIZE });
+    for (const run of page.page) await ctx.db.delete(run._id);
+    if (!page.isDone) {
+      await scheduleNext(ctx, { phase, cursor: page.continueCursor });
+    }
+    return null;
+  },
+});