@taprootio/site-authoring 0.14.1 → 0.16.0

package/src/verbs/pages-push.js

@@ -5,20 +5,39 @@ import {
   listVideos,
   IMAGE_PROCESSING_STATE_COMPLETE,
   PAGE_STATUS_DELETED,
+  listSiteAuthors,
   posterFromImage,
+  translateAuthorRefusal,
   updatePage,
   withRefusalGuidance,
 } from "../api.js";
+import {
+  AUTHORS_FILE_NAME,
+  authorConflictMessage,
+  authorKnown,
+  parseAuthorReference,
+  projectAuthorsForWorkspace,
+  readAuthorsDocument,
+} from "../authors-contract.js";
 import { VERB_PAGES_PUSH } from "../constants.js";
+import { autolinkWarnings } from "../content/link-warnings.js";
+import { ApiError } from "../transport.js";
 import { waitForProcessing } from "./media-upload.js";
 import { SiteAuthoringError } from "../errors.js";
+import { DESCRIPTION_MAXIMUM_LENGTH, DESCRIPTION_WARN_LENGTH, descriptionWarnings } from "../page-metadata.js";
+import { stableJson } from "../footer-draft-hash.js";
+import { CHECK_AREA, collectProblems, planStale, problemsOf, refuseProblems } from "../problems.js";
 import { RUNTIME_MIRROR_PATH_REASON, isRuntimeMirrorPath } from "../reserved-paths.js";
-import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { boundedByBytes, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { SETTINGS_TYPE_TAPROOT_STYLES } from "../settings-catalog.js";
 import {
+  changedGeneratedIdentity,
   contentDocuments,
   COVER_IMAGE_UNUSED_MESSAGE,
   documentTemplate,
+  generatedMarkdownFault,
+  generatedPageDescription,
+  generatedPageTitle,
   placedVideoIds,
   posterlessVideoEmbeds,
   FRONT_MATTER_KEYS,
@@ -26,6 +45,7 @@ import {
   requireTemplateName,
   sentDisplayDate,
   TEMPLATE_FREE_FORM,
+  TEMPLATE_GENERATED,
   templateFrontMatterFault,
   typedDocumentFromJson,
   typedDocumentFromMarkdown,
@@ -41,6 +61,7 @@ import {
 } from "../content/free-form-sections.js";
 import { CONTENT_ERROR_CODES } from "../content/vocabulary.js";
 import {
+  displayPagePath,
   deleteWorkspaceFile,
   internalPageObservedRevisionFile,
   MEDIA_MANIFEST_FILE_NAME,
@@ -68,6 +89,7 @@ import {
   workspaceContentHash,
   workspaceFileExists,
   writeManifest,
+  writeWorkspaceJson,
 } from "../workspace.js";
 
 /**
@@ -109,7 +131,40 @@ import {
  *   ambiguous outcome surfaces as ambiguous.
  */
 
-const MAXIMUM_REPORTED = 200;
+// Shares of the result's 64 KiB for its lists, whose entries carry page paths
+// of any length.
+const ITEMS_BYTES = 32 * 1024;
+const LIST_BYTES = 8 * 1024;
+// A send that ended this way may still have written the page.
+const OUTCOME_UNKNOWN_CODES = new Set([
+  "transport.mutation_ambiguous",
+  "transport.response_read",
+  "transport.response_too_large",
+  "transport.invalid_json",
+  "api.page_contract",
+]);
+
+function outcomeUnknown(error) {
+  // A cancelled retry of a write, and a server error on a write the transport
+  // does not replay, leave the same question open.
+  return OUTCOME_UNKNOWN_CODES.has(error.code) || error.ambiguousMutation === true || error.httpStatus >= 500;
+}
+
+/** The creates this workspace sent without hearing back, by page path. */
+function pendingCreates(manifest) {
+  const recorded = manifest.pendingCreates;
+  return recorded !== null && typeof recorded === "object" && !Array.isArray(recorded) ? recorded : {};
+}
+
+function pendingCreateFor(manifest, pagePath) {
+  return Object.hasOwn(pendingCreates(manifest), pagePath);
+}
+
+/** A result list bounded by bytes, as `<name>` plus `<name>Truncated` when cut. */
+function reportedList(name, values, budget) {
+  const shown = boundedByBytes(values, budget);
+  return { [name]: shown.items, ...(shown.truncated ? { [`${name}Truncated`]: true } : {}) };
+}
 const FRONT_MATTER_FENCE = "---";
 const FRONT_MATTER_ENTRY = /^([A-Za-z][A-Za-z0-9_]*)[ \t]*:[ \t]*(.*)$/u;
 
@@ -231,6 +286,7 @@ function parseFrontMatter(source, file) {
   if (fields.has("template")) {
     try {
       template = requireTemplateName(fields.get("template"), file);
+      if (template === TEMPLATE_GENERATED) record(generatedMarkdownFault(file));
     } catch (error) {
       record(error);
     }
@@ -379,14 +435,22 @@ function assertValid(content, document_, file, { mayBeEmpty = false } = {}) {
   const errors = mayBeEmpty ? reported.filter((error) => error?.code !== CONTENT_ERROR_CODES.emptyDocument) : reported;
   if (errors.length === 0) return;
   const first = errors[0] ?? {};
-  const location = typeof first.path === "string" && first.path !== "" ? first.path : "doc";
+  const locate = (error) => typeof error?.path === "string" && error.path !== "" ? error.path : "doc";
+  const describe = (error) =>
+    typeof error?.message === "string" ? error.message : "the node or mark is outside the accepted vocabulary.";
+  // Every finding travels with the refusal, so a whole-workspace check reports
+  // all of a page's problems and not only the first (TR01002).
   throw documentError(
     first.code === CONTENT_ERROR_CODES.rawHtmlForbidden ? CONTENT_ERROR_CODES.rawHtmlForbidden : "pages.document_invalid",
-    `'${file}' is not a valid Taproot document: ${errors.length} problem(s), first at ${location} (${
+    `'${file}' is not a valid Taproot document: ${errors.length} problem(s), first at ${locate(first)} (${
       typeof first.code === "string" ? first.code : "invalid"
-    }): ${typeof first.message === "string" ? first.message : "the node or mark is outside the accepted vocabulary."}`,
-    `${file}:${location}`,
-  );
+    }): ${describe(first)}`,
+    `${file}:${locate(first)}`,
+  ).withProblems(errors.map((error) => ({
+    code: typeof error?.code === "string" ? error.code : "pages.document_invalid",
+    field: `${file}:${locate(error)}`,
+    message: describe(error),
+  })));
 }
 
 function systemPageKind(pagePath) {
@@ -435,6 +499,7 @@ export async function readWorkspacePageSource({ workspaceDir, file, manifestEntr
   let pathCandidates = [];
   let title;
   let declaredDescription;
+  let declaredAuthor;
   let declaredPath;
   let template = TEMPLATE_FREE_FORM;
   let fields;
@@ -444,6 +509,9 @@ export async function readWorkspacePageSource({ workspaceDir, file, manifestEntr
     fields = frontMatter.fields;
     title = frontMatter.fields.get("title") ?? manifestEntry?.title;
     declaredDescription = frontMatter.fields.get("description") ?? manifestEntry?.description;
+    // An empty `author:` names nobody, so it falls back like an absent one
+    // rather than overriding the manifest's with nothing (TR01196).
+    declaredAuthor = frontMatter.fields.get("author") || manifestEntry?.author;
     declaredPath = frontMatter.fields.has("path") ? frontMatter.fields.get("path") : manifestEntry?.path;
     markdown = frontMatter.markdown;
     fault = frontMatter.fault;
@@ -459,10 +527,10 @@ export async function readWorkspacePageSource({ workspaceDir, file, manifestEntr
     }
     title = manifestEntry.title;
     declaredDescription = manifestEntry.description;
+    declaredAuthor = manifestEntry.author;
     declaredPath = manifestEntry.path;
     template = peekJsonTemplate(source);
   }
-
   const pagePath = normalizePagePath(declaredPath);
   if (pagePath === undefined) {
     // Not one resolved page, but not nothing either: a file declaring two
@@ -511,6 +579,7 @@ export async function readWorkspacePageSource({ workspaceDir, file, manifestEntr
     pagePath,
     title,
     declaredDescription,
+    declaredAuthor,
     fault,
     pathClaims: [],
     template,
@@ -588,6 +657,51 @@ function requireReconciledDisplayDate({ file, pagePath, target, entry, document_
   );
 }
 
+/**
+ * The refusals that keep a generated page what Taproot made it (TR01195). Only
+ * its title, breadcrumb, description and introduction are the owner's, so a
+ * push may update an existing generated page and nothing else: it never creates
+ * one, moves it, or changes the kind or identity it was pulled with. Checked
+ * here, before anything is sent, because the API refuses the same changes only
+ * after earlier pages in the push were written.
+ *
+ * A source with no live page is the caller's to classify (a stale file in a
+ * whole-workspace push, a refusal when the path was asked for), so `target` is
+ * always a live page here.
+ */
+function requireGeneratedUpdate({ file, pagePath, target, entry, document_ }) {
+  const livePath = normalizePagePath(target.path) ?? target.path;
+  if (livePath !== pagePath) {
+    throw documentError(
+      "pages.generated_move",
+      `'${file}' would move the generated page at '${livePath || "/"}' to '${pagePath || "/"}'. A generated page's `
+        + "path is set by Taproot from the content it lists: change the content that produces it, not its path.",
+      file,
+    );
+  }
+  const recorded = entry?.generated;
+  if (recorded === null || typeof recorded !== "object" || Array.isArray(recorded)) {
+    // Without the record there is nothing to prove this file is still the page
+    // it was pulled as, and an edit to its identity would pass for an owner's.
+    throw documentError(
+      "pages.generated_identity",
+      `'${file}' is a generated-page source, but this workspace has no record of which generated page it was pulled `
+        + "as, so its identity cannot be checked. Run 'taproot-site pull' to record it, then push again.",
+      file,
+    );
+  }
+  const changed = changedGeneratedIdentity(recorded, document_.data);
+  if (changed.length > 0) {
+    throw documentError(
+      "pages.generated_identity",
+      `'${file}' changes ${changed.join(", ")}, which say what this generated page is and which the site manages. `
+        + "Only customTitle, breadcrumbTitle, customDescription and introductionBody are yours to edit: restore "
+        + "the pulled values, or delete the file and pull again.",
+      `${file}:data.${changed[0]}`,
+    );
+  }
+}
+
 /**
  * The metadata checks that are *not* part of deciding which page a source is.
  *
@@ -708,6 +822,9 @@ export async function validateWorkspacePageDocument({
       const contexts = typeof getSharedThemeContexts === "function"
         ? await getSharedThemeContexts()
         : await readSharedThemeContexts(workspaceDir, siteId);
+      // No contexts means the theme itself failed validation and was reported
+      // as its own problem; a context cannot be checked against it.
+      if (contexts === undefined) continue;
       const contextErrors = validateFreeFormSectionContexts(doc, contexts).errors;
       if (contextErrors.length > 0) {
         const first = contextErrors[0];
@@ -722,10 +839,10 @@ export async function validateWorkspacePageDocument({
 }
 
 /**
- * Refuses a push that places a video the site's library does not hold; every
+ * The pages that place a video the site's library does not hold; every
  * library video is ready to play. Pages that will not be sent are not asked about.
  */
-async function requirePlacedVideosExist(client, siteId, planned) {
+export async function placedVideoProblems(client, siteId, planned) {
   const placements = new Map();
   for (const page of planned) {
     if (page.unchanged) continue;
@@ -733,30 +850,32 @@ async function requirePlacedVideosExist(client, siteId, planned) {
       if (!placements.has(videoId)) placements.set(videoId, page.file);
     }
   }
-  if (placements.size === 0) return;
+  if (placements.size === 0) return [];
 
   const library = await listVideos(client, siteId);
   const knownIds = new Set(library.videos.map((video) => video.videoId));
+  const problems = [];
   for (const [videoId, file] of placements) {
-    const known = knownIds.has(videoId);
-    if (!known && library.truncated) {
-      throw documentError(
-        "pages.video_library_unverifiable",
-        `'${file}' places video ${videoId}, which is not among the first ${library.videos.length} videos of this `
-          + "site's library, and the library is larger than one push can check. Reduce the library or place the video "
-          + "from the editor.",
-        file,
-      );
-    }
-    if (!known) {
-      throw documentError(
-        "pages.video_unknown",
-        `'${file}' places video ${videoId}, which is not in this site's video library. Upload it with `
-          + "'taproot-site media upload' and use the videoId it reports.",
-        file,
-      );
-    }
+    if (knownIds.has(videoId)) continue;
+    problems.push(...problemsOf(
+      library.truncated
+        ? documentError(
+          "pages.video_library_unverifiable",
+          `'${file}' places video ${videoId}, which is not among the first ${library.videos.length} videos of this `
+            + "site's library, and the library is larger than one push can check. Reduce the library or place the video "
+            + "from the editor.",
+          file,
+        )
+        : documentError(
+          "pages.video_unknown",
+          `'${file}' places video ${videoId}, which is not in this site's video library. Upload it with `
+            + "'taproot-site media upload' and use the videoId it reports.",
+          file,
+        ),
+      { area: CHECK_AREA.pages, file },
+    ));
   }
+  return problems;
 }
 
 /**
@@ -796,49 +915,151 @@ async function copyVideoEmbedPosters(client, siteId, planned, { onProgress, now
   }
 }
 
-export async function pagesPush(invocation) {
-  const session = await openSession(invocation);
-  const { client, config, siteId, now, onProgress } = session;
-  // One advisory line before this verb does any work, and only when the
-  // exchange said the platform is paused. It changes nothing else: the write
-  // still runs and its refusal still classifies as platform_paused (TR00692).
-  warnIfExternalWritesPaused(session, VERB_PAGES_PUSH);
-  // Both manifests are bound to the site before anything is planned or sent:
-  // every id in them is site-scoped, and a workspace pulled from another site
-  // reads as entirely valid until phase two is already writing.
-  const manifest = await readManifest(config.workspaceDir, siteId);
-  const mediaManifest = await readMediaManifest(config.workspaceDir, siteId);
-  const content = requireContentFunctions(await loadContentModule(invocation.content));
-  const requestedPaths = Array.isArray(invocation.pagePaths)
-    ? new Set(invocation.pagePaths.map((value) => {
-      const normalized = normalizePagePath(value);
-      if (normalized === undefined) {
-        throw new SiteAuthoringError(
-          "pages.page_path_invalid",
-          `'${typeof value === "string" ? value : String(value)}' is not a usable page path.`,
-          { field: typeof value === "string" ? value : undefined, exitCode: 2 },
+/** `authors.json`, or undefined when it is absent, unreadable, or another site's. */
+async function readRecordedAuthors(workspaceDir, siteId) {
+  try {
+    if (!await workspaceFileExists(workspaceDir, AUTHORS_FILE_NAME)) return undefined;
+    return readAuthorsDocument(
+      await readWorkspaceJson(workspaceDir, AUTHORS_FILE_NAME, WORKSPACE_LIMITS.authorsBytes),
+      siteId,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Reads the site's live author listing for an online run (TR01196), in the
+ * shape `readAuthorsDocument` gives, so a name added since `authors.json` was
+ * written is found. `write` keeps the workspace copy current; `plan` leaves the
+ * workspace alone and passes false. A site that cannot be asked (an older
+ * Taproot, a credential without the content capability) answers `undefined`,
+ * which proves nothing either way.
+ */
+export function liveAuthorsRefresher({ client, workspaceDir, siteId, write, onProgress }) {
+  return async () => {
+    onProgress(`An author is not in ${AUTHORS_FILE_NAME}; asking the site who can be named.`);
+    let listing;
+    try {
+      listing = await listSiteAuthors(client, siteId);
+    } catch (error) {
+      if (!(error instanceof ApiError)) throw error;
+      onProgress("The site's authors could not be read, so the author is left for the site to check.");
+      return undefined;
+    }
+    const document_ = projectAuthorsForWorkspace(siteId, listing);
+    if (write) await writeWorkspaceJson(workspaceDir, AUTHORS_FILE_NAME, document_);
+    return readAuthorsDocument(document_, siteId);
+  };
+}
+
+/**
+ * Decides what a page says about its author before anything is sent
+ * (TR01196). `declared` is what the source (or, for a `.pm.json` page, its
+ * manifest entry) names; `recorded` is the author the site held when the
+ * workspace last reconciled with the page.
+ *
+ * Pages are authorless by default and an author is never replaced, so:
+ * nothing declared sends nothing; the author the site already has sends
+ * nothing and passes; a different one is refused here, where the site would
+ * refuse it only after earlier pages were written; and a new one is sent once
+ * the site is known to have it.
+ *
+ * "Known to have it" is asked of `authors.json` first, but a miss there is only
+ * as good as the day the file was written. An online run (`refreshAuthors`)
+ * asks the site once and refuses only what the site's own list lacks; an
+ * offline one cannot ask, so it sends nothing and flags the name as unverified
+ * rather than refusing a person who may have been added since.
+ */
+async function resolvePageAuthor({ file, pagePath, declared, recorded, markdown, knownAuthors, refreshAuthors }) {
+  if (declared === undefined || declared === "") return { author: "", sendAuthor: false };
+  const reference = parseAuthorReference(declared);
+  if (reference === undefined) {
+    throw documentError(
+      "pages.author_invalid",
+      `'${file}' names author '${String(declared).slice(0, 80)}', which is neither a site author's handle (such as `
+        + "jane-doe) nor a member's email address.",
+      file,
+    );
+  }
+  const current = parseAuthorReference(recorded)?.value ?? "";
+  if (reference.value === current) return { author: reference.value, sendAuthor: false };
+  if (current !== "") {
+    throw documentError(
+      "pages.author_conflict",
+      authorConflictMessage({
+        shown: displayPagePath(pagePath),
+        file,
+        held: current,
+        wanted: reference.value,
+        markdown,
+      }),
+      file,
+    );
+  }
+  let known = authorKnown(await knownAuthors(), reference.value);
+  let unverified = false;
+  if (known !== true) {
+    if (refreshAuthors === undefined) {
+      unverified = known === false;
+    } else {
+      const fresh = await refreshAuthors();
+      known = authorKnown(fresh, reference.value);
+      if (known === false) {
+        throw documentError(
+          "pages.author_unknown",
+          `'${file}' names author '${reference.value}', who is not among the site's authors or the members who can `
+            + "create pages. Run 'taproot-site authors list' to see who can be named, or 'taproot-site authors add' "
+            + "to create a site author.",
+          file,
         );
       }
-      return normalized;
-    }))
-    : undefined;
-  // Manifest integrity is never scoped: a registry that contradicts itself
-  // describes some other workspace, and a selection cannot make that safe.
-  requireManifestSourceRegistry(pageSourceRegistry(manifest));
-  const targeted = requestedPaths !== undefined;
+    }
+  }
+  return { author: reference.value, sendAuthor: true, unverified };
+}
 
-  // The shared list, so the set `pull` refuses to write over is exactly the set
-  // this walks: a file one counted and the other ignored would be a page pushed
-  // from a workspace nothing proved the ownership of.
-  const files = await walkWorkspaceFiles(config.workspaceDir, PAGES_DIRECTORY, PAGE_SOURCE_EXTENSIONS);
-  if (files.length === 0) {
-    throw new SiteAuthoringError(
-      "pages.none_found",
-      `No Markdown or ProseMirror page files were found under '${PAGES_DIRECTORY}/' in the workspace.`,
-      { field: PAGES_DIRECTORY },
-    );
+/**
+ * Phase one over the workspace's page sources (TR01002): resolve which file is
+ * each page's one source, convert and validate it, and decide create, update,
+ * or unchanged — collecting every problem rather than stopping at the first.
+ *
+ * `livePages` is what the sources are checked against. A push passes the
+ * site's own list with `online`; the offline workspace check passes the pull
+ * manifest's pages, which is what the site held when the workspace was pulled,
+ * and skips the two guards only a live read can arm (a moved revision or
+ * display date). `getSharedThemeContexts` names the theme's contexts when
+ * the caller has already validated the theme.
+ */
+export async function planPages({
+  workspaceDir,
+  siteId,
+  manifest,
+  mediaManifest,
+  content,
+  files,
+  livePages,
+  online,
+  requestedPaths,
+  getSharedThemeContexts,
+  refreshAuthors,
+  onProgress = () => {},
+}) {
+  const problems = [];
+  const area = { area: CHECK_AREA.pages };
+  const targeted = requestedPaths !== undefined;
+  // Generated-page sources whose page no longer exists on the site, found in a
+  // whole-workspace run: reported, and nothing is sent for them.
+  const staleGenerated = [];
+  // Manifest integrity is never scoped: a registry that contradicts itself
+  // describes some other workspace, so nothing in it can be planned.
+  await collectProblems(problems, area, () => requireManifestSourceRegistry(pageSourceRegistry(manifest)));
+  if (problems.length > 0) {
+    return { targeted, sources: [], selected: [], planned: [], unresolved: [], staleGenerated, problems };
   }
-  let sharedThemeContexts;
+  const live = livePages.filter((summary) => summary.status !== PAGE_STATUS_DELETED);
+  const liveById = new Map(live.map((summary) => [summary.pageId, summary]));
+  const liveByPath = new Map(live.map((summary) => [normalizePagePath(summary.path) ?? summary.path, summary]));
   const manifestByFile = new Map(
     manifest.pages.filter((entry) => typeof entry?.file === "string").map((entry) => [entry.file, entry]),
   );
@@ -850,118 +1071,156 @@ export async function pagesPush(invocation) {
   const manifestByPageId = new Map(
     manifest.pages.filter((entry) => typeof entry?.pageId === "string").map((entry) => [entry.pageId, entry]),
   );
-
-  return await withRefusalGuidance(onProgress, "push", async () => {
-    onProgress("Listing the site's pages to resolve creates from updates.");
-    const { pages: livePages, truncated } = await listSitePages(client, siteId, { onProgress });
-    if (truncated) {
-      // Every create-or-update decision below is made against this list. A
-      // partial one turns a tracked page into a create, which the server then
-      // refuses for a duplicate path — mid-phase-two, after earlier pages have
-      // already been written.
-      throw new SiteAuthoringError(
-        "pages.live_list_truncated",
-        "The site has more pages than this CLI can enumerate, so an update cannot be told from a create. "
-          + "No page was pushed.",
-        { field: PAGES_DIRECTORY },
-      );
+  let sharedThemeContexts;
+  // What the workspace last recorded about who can be named (TR01196). Absent
+  // is the common case and means a reference cannot be checked offline, which
+  // is never a reason to refuse it.
+  let recordedAuthors;
+  let recordedAuthorsRead = false;
+  const getRecordedAuthors = async () => {
+    if (!recordedAuthorsRead) {
+      recordedAuthorsRead = true;
+      recordedAuthors = await readRecordedAuthors(workspaceDir, siteId);
     }
-    const live = livePages.filter((summary) => summary.status !== PAGE_STATUS_DELETED);
-    const liveById = new Map(live.map((summary) => [summary.pageId, summary]));
-    const liveByPath = new Map(live.map((summary) => [normalizePagePath(summary.path) ?? summary.path, summary]));
+    return recordedAuthors;
+  };
+  // At most one live read per run, however many pages name a new author.
+  let liveAuthorsRead;
+  const getLiveAuthors = refreshAuthors === undefined
+    ? undefined
+    : () => {
+      liveAuthorsRead ??= refreshAuthors();
+      return liveAuthorsRead;
+    };
 
-    // Resolution: which file is each page path's one authoritative source.
-    // This reads metadata only — a manifest entry, or a front-matter block —
-    // so no document is converted, no media reference is resolved, and no
-    // component contract is checked until the selection is known.
-    const sources = [];
-    const claimants = [];
-    const unresolved = [];
-    for (const file of files) {
-      const manifestEntry = manifestByFile.get(file);
-      try {
-        const source = await readWorkspacePageSource({ workspaceDir: config.workspaceDir, file, manifestEntry });
-        if (source.pagePath === undefined) {
-          // A file whose page identity is ambiguous. A whole-workspace push
-          // reports every authored page, so it is a refusal there; a targeted
-          // one refuses only if the selection touches a path it might be.
-          if (!targeted) throw source.fault;
-          claimants.push(source);
-          continue;
-        }
-        sources.push(source);
-      } catch (error) {
-        // A source whose metadata cannot be read declares no page path, so it
-        // cannot be the page a selection asked for. A whole-workspace push is
-        // the command that reports it; a targeted one names it and carries on.
-        // Anything that is not a metadata fault — a containment refusal, an
-        // oversized file, an unreadable one — still fails closed.
-        if (!targeted || !(error instanceof SiteAuthoringError) || !RESOLUTION_METADATA_CODES.has(error.code)) {
-          throw error;
-        }
+  // Resolution: which file is each page path's one authoritative source.
+  // This reads metadata only — a manifest entry, or a front-matter block —
+  // so no document is converted, no media reference is resolved, and no
+  // component contract is checked until the selection is known.
+  const sources = [];
+  const claimants = [];
+  const unresolved = [];
+  // Sources of generated pages the site has since retired, which pull keeps
+  // apart from the live pages (TR01195). Never sent; reported, not refused,
+  // unless a push names that path.
+  const retiredByFile = new Map(
+    (Array.isArray(manifest.retiredGeneratedSources) ? manifest.retiredGeneratedSources : [])
+      .filter((entry) => typeof entry?.file === "string" && typeof entry?.path === "string")
+      .map((entry) => [entry.file, entry]),
+  );
+  for (const file of files) {
+    const manifestEntry = manifestByFile.get(file);
+    const retired = manifestEntry === undefined ? retiredByFile.get(file) : undefined;
+    if (retired !== undefined) {
+      const retiredPath = normalizePagePath(retired.path) ?? retired.path;
+      // A page created since at the same path has its own source, which is the
+      // one a push by that path sends.
+      if (targeted && requestedPaths.has(retiredPath) && !liveByPath.has(retiredPath)) {
+        throw documentError(
+          "pages.generated_create",
+          `'${file}' was the source of a generated page that the site no longer has, and a push cannot create `
+            + "one. Delete the file.",
+          file,
+        );
+      }
+      if (!targeted) {
+        staleGenerated.push({ file, path: displayPagePath(retiredPath) });
+        onProgress(`'${file}' is the source of a generated page the site no longer has; nothing is sent for it.`);
+      }
+      continue;
+    }
+    try {
+      const source = await readWorkspacePageSource({ workspaceDir, file, manifestEntry });
+      if (source.pagePath === undefined) {
+        // A file whose page identity is ambiguous. A whole-workspace check
+        // reports it; a targeted one refuses only if the selection touches a
+        // path it might be.
+        if (targeted) claimants.push(source);
+        else problems.push(...problemsOf(source.fault ?? missingPathError(file), { ...area, file }));
+        continue;
+      }
+      sources.push(source);
+    } catch (error) {
+      if (!(error instanceof SiteAuthoringError)) throw error;
+      // A source whose metadata cannot be read declares no page path, so it
+      // cannot be the page a selection asked for: a targeted push names it and
+      // carries on. Anything that is not a metadata fault — a containment
+      // refusal, an oversized file, an unreadable one — still fails closed.
+      if (targeted && RESOLUTION_METADATA_CODES.has(error.code)) {
         unresolved.push({ file, code: error.code });
         onProgress(`'${file}' declares no readable page path (${error.code}); it is outside this selection.`);
+        continue;
       }
+      if (targeted) throw error;
+      problems.push(...problemsOf(error, { ...area, file }));
     }
+  }
 
-    // Two editable sources for one page path. Whichever push would touch that
-    // path refuses: choosing between them is exactly the ambiguity one source
-    // per page exists to remove, and it is also how the documented format
-    // change — remove the old source, author the other beside it — is proved
-    // to have actually removed the old one.
-    const sourcesByPath = new Map();
-    for (const source of sources) {
-      const existing = sourcesByPath.get(source.pagePath);
-      if (existing === undefined) {
-        sourcesByPath.set(source.pagePath, source);
-        continue;
-      }
-      if (!targeted || requestedPaths.has(source.pagePath)) {
-        throw documentError(
+  // Two editable sources for one page path. Whichever check touches that path
+  // refuses: choosing between them is exactly the ambiguity one source per
+  // page exists to remove, and it is also how the documented format change —
+  // remove the old source, author the other beside it — is proved to have
+  // actually removed the old one.
+  const sourcesByPath = new Map();
+  const conflicted = new Set();
+  for (const source of sources) {
+    const existing = sourcesByPath.get(source.pagePath);
+    if (existing === undefined) {
+      sourcesByPath.set(source.pagePath, source);
+      continue;
+    }
+    if (!targeted || requestedPaths.has(source.pagePath)) {
+      conflicted.add(source.pagePath);
+      problems.push(...problemsOf(
+        documentError(
           "pages.path_conflict",
           `'${source.file}' and '${existing.file}' both claim page path '${source.pagePath}'.`,
           source.pagePath,
-        );
-      }
-      onProgress(
-        `'${source.file}' and '${existing.file}' both claim page path '${source.pagePath}'; `
-          + "neither is in this selection.",
-      );
+        ),
+        { ...area, file: source.file },
+      ));
+      continue;
     }
+    onProgress(
+      `'${source.file}' and '${existing.file}' both claim page path '${source.pagePath}'; `
+        + "neither is in this selection.",
+    );
+  }
 
-    const selected = targeted ? sources.filter((source) => requestedPaths.has(source.pagePath)) : sources;
-    if (targeted) {
-      // Before deciding what the selection resolved to: a file that might be
-      // one of the selected pages makes the selection unprovable, so its own
-      // fault is what this push reports.
-      const claimant = claimants.find((source) => source.pathClaims.some((claim) => requestedPaths.has(claim)));
-      if (claimant !== undefined) throw claimant.fault;
-    }
-    if (targeted) {
-      const matched = new Set(selected.map((source) => source.pagePath));
-      const missing = [...requestedPaths].filter((pagePath) => !matched.has(pagePath)).sort();
-      if (missing.length > 0) {
-        // The homepage normalizes to the empty path, which the result emitters
-        // drop as falsy; name it by its documented '/' spelling so the stable
-        // error contract keeps a field for every unknown path.
-        throw new SiteAuthoringError(
-          "pages.page_not_found",
-          `No workspace page was found for page path '${missing[0] || "/"}'.`,
-          { field: missing[0] || "/" },
-        );
-      }
-      onProgress(
-        `Selected ${selected.length} of ${sources.length} page source(s) by path; `
-          + "only the selection is validated and sent.",
+  const selected = (targeted ? sources.filter((source) => requestedPaths.has(source.pagePath)) : sources)
+    .filter((source) => !conflicted.has(source.pagePath));
+  if (targeted) {
+    // Before deciding what the selection resolved to: a file that might be
+    // one of the selected pages makes the selection unprovable, so its own
+    // fault is what this push reports.
+    const claimant = claimants.find((source) => source.pathClaims.some((claim) => requestedPaths.has(claim)));
+    if (claimant !== undefined) throw claimant.fault;
+    const matched = new Set([...selected.map((source) => source.pagePath), ...conflicted]);
+    const missing = [...requestedPaths].filter((pagePath) => !matched.has(pagePath)).sort();
+    if (missing.length > 0) {
+      // The homepage normalizes to the empty path, which the result emitters
+      // drop as falsy; name it by its documented '/' spelling so the stable
+      // error contract keeps a field for every unknown path.
+      throw new SiteAuthoringError(
+        "pages.page_not_found",
+        `No workspace page was found for page path '${missing[0] || "/"}'.`,
+        { field: missing[0] || "/" },
       );
-    } else {
-      onProgress(`Validating every one of the ${sources.length} page source(s) in this workspace.`);
     }
+    onProgress(
+      `Selected ${selected.length} of ${sources.length} page source(s) by path; `
+        + "only the selection is validated and sent.",
+    );
+  } else {
+    onProgress(`Validating every one of the ${sources.length} page source(s) in this workspace.`);
+  }
 
-    // Phase one: convert and validate the selection. No mutation is sent until
-    // every document that will be sent has passed.
-    const planned = [];
-    for (const source of selected) {
+  // Phase one proper: convert and validate the selection. Each source's first
+  // refusal is collected and the next source is checked; nothing is sent
+  // until the whole list is empty.
+  const planned = [];
+  for (const source of selected) {
+    await collectProblems(problems, { ...area, file: source.file }, async () => {
       const { file, pagePath, title, declaredDescription } = source;
       onProgress(`Validating '${file}'.`);
       const manifestEntry = manifestByFile.get(file);
@@ -972,6 +1231,88 @@ export async function pagesPush(invocation) {
       const target = manifestEntry?.pageId !== undefined
         ? liveById.get(manifestEntry.pageId)
         : liveByPath.get(pagePath);
+      if (manifestEntry?.pageId === undefined && target !== undefined && pendingCreateFor(manifest, pagePath)) {
+        throw documentError(
+          "pages.create_unconfirmed",
+          `An earlier push tried to create page '${pagePath || "/"}' from '${file}' without hearing back, and the site now has a `
+            + "page at that path. It may be that create or someone else's page, so nothing will write over it: run "
+            + "'taproot-site pull' to record the site's page, then reconcile it with this source and push again.",
+          file,
+        );
+      }
+      const generated = documentTemplate(document_) === TEMPLATE_GENERATED;
+      if (generated && target === undefined) {
+        if (targeted) {
+          throw documentError(
+            "pages.generated_create",
+            `'${file}' is a generated-page source, but the site has no generated page for it. Taproot creates `
+              + "generated pages from the site's content; a push cannot create one. If the page no longer exists, "
+              + "delete this file and run 'taproot-site pull'.",
+            file,
+          );
+        }
+        // The site retired this page (its tag, month, place or folder is gone),
+        // which is Taproot's doing, not a mistake in the workspace: it cannot
+        // block the pages that do exist.
+        staleGenerated.push({ file, path: displayPagePath(pagePath) });
+        onProgress(
+          `'${file}' is a generated-page source, but the site has no generated page at '${pagePath || "/"}' any more; `
+            + "nothing is sent for it. Delete the file, or run 'taproot-site pull' to refresh the workspace.",
+        );
+        return;
+      }
+      // The file-keyed entry is gone whenever the file was renamed or replaced —
+      // which is exactly what the pull, delete the `.pm.json`, author a `.md`
+      // flow does. Falling back through the page's own identity keeps the
+      // fields the workspace never restated; without it the whole-object
+      // UpdatePage sends "" and false and silently clears both.
+      const targetEntry = target === undefined ? undefined : manifestByPageId.get(target.pageId);
+      const description = generated
+        // The manifest's title and description are what the site reported; the owner's are in the document.
+        ? generatedPageDescription(document_.data, declaredDescription ?? targetEntry?.description ?? "")
+        : declaredDescription ?? targetEntry?.description ?? "";
+      const sentTitle = generated ? generatedPageTitle(document_.data, title) : title;
+      const sentDescription = typeof description === "string" ? description : "";
+      // A Markdown source carries its author in the front matter its hash
+      // already covers; only a .pm.json page keeps one in the manifest, where
+      // the key has to see it. Absent, the key is the one it always was.
+      const markdownSource = source.sourceFormat === PAGE_SOURCE_FORMAT_MARKDOWN;
+      const contentKeyFor = (author) => pageContentKey(
+        source.sourceHash,
+        {
+          title: sentTitle,
+          path: pagePath,
+          description: sentDescription,
+          author: markdownSource ? "" : author,
+        },
+        markdownSource ? canonicalDocumentHash(document_) : "",
+      );
+      // A generated page has no author, so its key is final here. Every other
+      // page's key waits for the author resolved below.
+      let contentKey = contentKeyFor("");
+      // The source and everything sent with it match what the site last agreed
+      // to, so sending again would only turn an approved page back into a draft.
+      // Not when the operator was shown a conflict for this page (the record
+      // exists to let this push reassert the source), and not when the source
+      // moved or changed format, which the send re-registers in the manifest.
+      const isUnchanged = (record) => target !== undefined
+        && targetEntry?.baseline?.contentKey === contentKey
+        && record === undefined
+        && targetEntry.file === file
+        && targetEntry.sourceFormat === source.sourceFormat;
+      // An untouched generated page is not this push's to judge. Taproot
+      // moves its revision and its path on its own (a tag rename, a month that
+      // gained a post), and refusing the whole push for a page nothing here
+      // sends would make one renamed page block every other edit.
+      let untouchedGenerated = false;
+      if (generated) {
+        const observedFile = internalPageObservedRevisionFile(target.pageId);
+        if (observedFile !== undefined) await workspaceFileExists(workspaceDir, observedFile);
+        untouchedGenerated = isUnchanged(await readObservedPageRecord(workspaceDir, target.pageId));
+        if (!untouchedGenerated) {
+          requireGeneratedUpdate({ file, pagePath, target, entry: manifestEntry ?? targetEntry, document_ });
+        }
+      }
       const workspaceSystemKind = systemPageKind(pagePath);
       if (target === undefined) {
         if (workspaceSystemKind !== undefined) {
@@ -1008,18 +1349,20 @@ export async function pagesPush(invocation) {
         // a directory or a symlink at its path is refused here, before any
         // page is written, rather than discovered after the site has changed.
         const observedRecordFile = internalPageObservedRevisionFile(target.pageId);
-        if (observedRecordFile !== undefined) await workspaceFileExists(config.workspaceDir, observedRecordFile);
-        const observed = await readObservedPageRecord(config.workspaceDir, target.pageId);
+        if (observedRecordFile !== undefined) await workspaceFileExists(workspaceDir, observedRecordFile);
+        const observed = await readObservedPageRecord(workspaceDir, target.pageId);
         observedRecord = observed;
-        const guard = {
-          file,
-          pagePath,
-          target,
-          entry: manifestByPageId.get(target.pageId),
-          observedRevision: observed?.revision,
-        };
-        requireReconciledRevision(guard);
-        requireReconciledDisplayDate({ ...guard, document_, observed });
+        if (online && !untouchedGenerated) {
+          const guard = {
+            file,
+            pagePath,
+            target,
+            entry: manifestByPageId.get(target.pageId),
+            observedRevision: observed?.revision,
+          };
+          requireReconciledRevision(guard);
+          requireReconciledDisplayDate({ ...guard, document_, observed });
+        }
       }
 
       // The duplicate-source check above only catches two workspace files
@@ -1029,7 +1372,7 @@ export async function pagesPush(invocation) {
       // earlier pages have been written. A page matching itself is the ordinary
       // update and is left alone.
       const holder = liveByPath.get(pagePath);
-      if (holder !== undefined && holder.pageId !== target?.pageId) {
+      if (!untouchedGenerated && holder !== undefined && holder.pageId !== target?.pageId) {
         throw documentError(
           "pages.path_taken",
           `'${file}' claims page path '${pagePath}', which page ${holder.pageId} already holds on this site. `
@@ -1038,68 +1381,248 @@ export async function pagesPush(invocation) {
         );
       }
 
-      // The file-keyed entry is gone whenever the file was renamed or replaced —
-      // which is exactly what the pull, delete the `.pm.json`, author a `.md`
-      // flow does. Falling back through the page's own identity keeps the
-      // fields the workspace never restated; without it the whole-object
-      // UpdatePage sends "" and false and silently clears both.
-      const targetEntry = target === undefined ? undefined : manifestByPageId.get(target.pageId);
-      const description = declaredDescription ?? targetEntry?.description ?? "";
-
       await validateWorkspacePageDocument({
-        workspaceDir: config.workspaceDir,
+        workspaceDir,
         siteId,
         file,
         document: document_,
         content,
-        getSharedThemeContexts: async () => {
-          sharedThemeContexts ??= await readSharedThemeContexts(config.workspaceDir, siteId);
+        getSharedThemeContexts: getSharedThemeContexts ?? (async () => {
+          sharedThemeContexts ??= await readSharedThemeContexts(workspaceDir, siteId);
           return sharedThemeContexts;
-        },
+        }),
       });
 
-      const sentDescription = typeof description === "string" ? description : "";
-      const contentKey = pageContentKey(
-        source.sourceHash,
-        { title, path: pagePath, description: sentDescription },
-        source.sourceFormat === PAGE_SOURCE_FORMAT_MARKDOWN ? canonicalDocumentHash(document_) : "",
-      );
+      // Online, the listing says whom the site credits now; the baseline is
+      // only whom it credited at the last reconcile. Discarding a draft in the
+      // app can drop an author the CLI assigned, and the push must then ask
+      // again rather than trust the record. A page that credits someone this
+      // credential may not name keeps the recorded author (TR01196).
+      const recordedAuthor = targetEntry?.baseline?.author;
+      const heldAuthor = online && target !== undefined
+        ? target.authorRef || (target.hasAuthor ? recordedAuthor : "")
+        : recordedAuthor;
+      const authorship = generated
+        ? { author: "", sendAuthor: false }
+        : await resolvePageAuthor({
+          file,
+          pagePath,
+          declared: source.declaredAuthor ?? targetEntry?.author,
+          recorded: heldAuthor,
+          markdown: markdownSource,
+          knownAuthors: getRecordedAuthors,
+          refreshAuthors: getLiveAuthors,
+        });
+      contentKey = contentKeyFor(authorship.author);
+      // An author the site no longer holds is a change to send, however the
+      // source compares with the record.
+      const unchanged = isUnchanged(observedRecord) && !(online && target !== undefined && authorship.sendAuthor);
+      // Only for a page this push sends: a description stored before the limit
+      // existed must not block a push that leaves it alone (TR01194). A
+      // generated page's derived description is not the owner's to shorten;
+      // its customDescription is checked with the document.
+      if (!generated && !unchanged && [...sentDescription].length > DESCRIPTION_MAXIMUM_LENGTH) {
+        throw documentError(
+          "pages.description_too_long",
+          `'${file}' has a ${[...sentDescription].length}-character description; it may be at most `
+            + `${DESCRIPTION_MAXIMUM_LENGTH}, and search results show about ${DESCRIPTION_WARN_LENGTH}.`,
+          file,
+        );
+      }
       planned.push({
         file,
         pagePath,
-        title,
+        title: sentTitle,
+        // Only the owner's own description is warned about for length: the derived one is not theirs to shorten.
+        ...(generated ? { declaredDescription: document_.data.customDescription } : {}),
         contentKey,
-        // The source and everything sent with it match what the site last agreed
-        // to, so sending again would only turn an approved page back into a draft.
-        // Not when the operator was shown a conflict for this page (the record
-        // exists to let this push reassert the source), and not when the source
-        // moved or changed format, which the send re-registers in the manifest.
-        unchanged: target !== undefined
-          && targetEntry?.baseline?.contentKey === contentKey
-          && observedRecord === undefined
-          && targetEntry.file === file
-          && targetEntry.sourceFormat === source.sourceFormat,
+        unchanged,
         description: sentDescription,
+        author: authorship.author,
+        sendAuthor: authorship.sendAuthor,
+        ...(authorship.unverified === true ? { authorUnverified: true } : {}),
         document: document_,
         sourceFormat: source.sourceFormat,
         sourceHash: source.sourceHash,
         pageId: target?.pageId,
+        // The live revision this page would be sent against; `plan` binds it
+        // into its hash so a concurrent edit invalidates the plan.
+        revision: target?.bodyRevision,
         templateType: PAGE_TEMPLATES[documentTemplate(document_)].wireType,
         action: target === undefined ? "created" : "updated",
       });
-    }
+    });
+  }
+
+  return { targeted, sources, selected, planned, unresolved, staleGenerated, problems };
+}
+
+function missingPathError(file) {
+  return documentError(
+    "pages.path_missing",
+    `'${file}' does not declare a usable page path. Add 'path:' to its front-matter (use an empty value for the home page).`,
+    file,
+  );
+}
+
+/**
+ * The generated-page sources whose page the site no longer has, as a result
+ * field (TR01195). Reported rather than refused: the site retired the page, and
+ * nothing is sent for the file.
+ */
+export function staleGeneratedSourcesField(staleGenerated) {
+  return staleGenerated.length === 0
+    ? {}
+    : { staleGeneratedSources: { total: staleGenerated.length, ...reportedList("items", staleGenerated, LIST_BYTES) } };
+}
+
+/** What a dry run or a plan reports for one planned page. */
+export function plannedPageItem(page) {
+  return { file: page.file, path: displayPagePath(page.pagePath), action: page.unchanged ? "unchanged" : page.action };
+}
+
+export async function pagesPush(invocation) {
+  const session = await openSession(invocation);
+  const { client, config, siteId, now, onProgress } = session;
+  const dryRun = invocation.dryRun === true;
+  // One advisory line before this verb does any work, and only when the
+  // exchange said the platform is paused. It changes nothing else: the write
+  // still runs and its refusal still classifies as platform_paused (TR00692).
+  if (!dryRun) warnIfExternalWritesPaused(session, VERB_PAGES_PUSH);
+  // Both manifests are bound to the site before anything is planned or sent:
+  // every id in them is site-scoped, and a workspace pulled from another site
+  // reads as entirely valid until phase two is already writing.
+  const manifest = await readManifest(config.workspaceDir, siteId);
+  const mediaManifest = await readMediaManifest(config.workspaceDir, siteId);
+  const content = requireContentFunctions(await loadContentModule(invocation.content));
+  const requestedPaths = Array.isArray(invocation.pagePaths)
+    ? new Set(invocation.pagePaths.map((value) => {
+      const normalized = normalizePagePath(value);
+      if (normalized === undefined) {
+        throw new SiteAuthoringError(
+          "pages.page_path_invalid",
+          `'${typeof value === "string" ? value : String(value)}' is not a usable page path.`,
+          { field: typeof value === "string" ? value : undefined, exitCode: 2 },
+        );
+      }
+      return normalized;
+    }))
+    : undefined;
+  // Refused before any request: a registry that contradicts itself describes
+  // some other workspace, and a selection cannot make that safe.
+  requireManifestSourceRegistry(pageSourceRegistry(manifest));
+
+  // The shared list, so the set `pull` refuses to write over is exactly the set
+  // this walks: a file one counted and the other ignored would be a page pushed
+  // from a workspace nothing proved the ownership of.
+  const files = await walkWorkspaceFiles(config.workspaceDir, PAGES_DIRECTORY, PAGE_SOURCE_EXTENSIONS);
+  if (files.length === 0) {
+    throw new SiteAuthoringError(
+      "pages.none_found",
+      `No Markdown or ProseMirror page files were found under '${PAGES_DIRECTORY}/' in the workspace.`,
+      { field: PAGES_DIRECTORY },
+    );
+  }
 
+  return await withRefusalGuidance(onProgress, "push", async () => {
+    onProgress("Listing the site's pages to resolve creates from updates.");
+    const { pages: livePages, truncated } = await listSitePages(client, siteId, { onProgress });
+    if (truncated) {
+      // Every create-or-update decision below is made against this list. A
+      // partial one turns a tracked page into a create, which the server then
+      // refuses for a duplicate path — mid-phase-two, after earlier pages have
+      // already been written.
+      throw new SiteAuthoringError(
+        "pages.live_list_truncated",
+        "The site has more pages than this CLI can enumerate, so an update cannot be told from a create. "
+          + "No page was pushed.",
+        { field: PAGES_DIRECTORY },
+      );
+    }
+    const plan = await planPages({
+      workspaceDir: config.workspaceDir,
+      siteId,
+      manifest,
+      mediaManifest,
+      content,
+      files,
+      livePages,
+      online: true,
+      requestedPaths,
+      refreshAuthors: liveAuthorsRefresher({
+        client,
+        workspaceDir: config.workspaceDir,
+        siteId,
+        // A dry run writes nothing, authors.json included.
+        write: !dryRun,
+        onProgress,
+      }),
+      onProgress,
+    });
+    const { planned, targeted, unresolved, staleGenerated } = plan;
     // A page that places a video names it by id, and only the library knows
     // whether that id is one of this site's videos. Asked once for the whole
     // push, before anything is written, so a page cannot be sent that
     // publishing would then refuse.
-    await requirePlacedVideosExist(client, siteId, planned);
+    plan.problems.push(...await placedVideoProblems(client, siteId, planned));
+
+    // Under apply, the workspace read ledger has already held every source and
+    // manifest to the plan. What it cannot see is the site: every page the plan
+    // would send must still be the page, revision and action it listed, and
+    // nothing it did not list may be sent. A planned page can still turn out
+    // unchanged, when an upload deduplicates to the image it already shows, and
+    // is then skipped.
+    if (invocation.plannedPages !== undefined) {
+      const byFile = new Map(planned.map((page) => [page.file, page]));
+      for (const [file, expected] of invocation.plannedPages) {
+        const page = byFile.get(file);
+        if (page === undefined || stableJson([page.pageId ?? "", page.revision ?? "", page.action]) !== expected) {
+          throw planStale(`'${file}'`, file);
+        }
+      }
+      const unplanned = planned.find((page) => !page.unchanged && !invocation.plannedPages.has(page.file));
+      if (unplanned !== undefined) throw planStale(`'${unplanned.file}'`, unplanned.file);
+    }
+    // What this run actually looked at, so automation can tell a targeted
+    // push from a whole-workspace one without inferring it from counts.
+    const selection = {
+      selection: targeted ? "targeted" : "workspace",
+      ...(targeted
+        ? reportedList("selectedPaths", [...requestedPaths].sort().map((pagePath) => pagePath || "/"), LIST_BYTES)
+        : {}),
+      discovered: files.length,
+    };
+    // Warned about only for pages this push sends, so an unchanged page is not
+    // re-reported every time.
+    const sending = planned.filter((page) => !page.unchanged);
+    const warnings = { ...autolinkWarnings(sending, onProgress), ...descriptionWarnings(sending, onProgress) };
+    if (dryRun) {
+      refuseProblems(plan.problems, "pages push --dry-run found problems and sent nothing");
+      onProgress("Dry run: nothing was sent.");
+      return successResult(VERB_PAGES_PUSH, siteId, {
+        dryRun: true,
+        pages: {
+          total: planned.length,
+          unchanged: planned.filter((page) => page.unchanged).length,
+          wouldCreate: planned.filter((page) => !page.unchanged && page.action === "created").length,
+          wouldUpdate: planned.filter((page) => !page.unchanged && page.action === "updated").length,
+          ...selection,
+          validated: planned.length,
+          ...staleGeneratedSourcesField(staleGenerated),
+          ...reportedList("items", planned.map(plannedPageItem), ITEMS_BYTES),
+        },
+        ...warnings,
+      });
+    }
+    refuseProblems(plan.problems, "pages push sent nothing");
     await copyVideoEmbedPosters(client, siteId, planned, { onProgress, now });
 
     // Phase two: send. The manifest is written back even if a later page fails,
     // so a retry updates the pages this run created rather than duplicating them.
     const applied = [];
     let manifestDirty = false;
+    // The page whose request is in flight, so a failure names it and not the next one.
+    let attempting;
     try {
       for (const page of planned) {
         if (page.unchanged) {
@@ -1113,17 +1636,40 @@ export async function pagesPush(invocation) {
           shortDescription: page.description,
           template: wireTemplate(page.document),
           ...wirePageFields(page.document),
+          // Only a name the site has not been told: repeating the author a page
+          // already has would let a later change of that person's permissions
+          // refuse a push that changes nothing about authorship.
+          ...(page.sendAuthor ? { author: page.author } : {}),
         };
-        const summary = page.action === "created"
-          ? await createPage(client, { siteId, ...fields })
-          : await updatePage(client, page.pageId, { pageId: page.pageId, ...fields });
+        // A create whose answer is lost may still have made the page. Recorded
+        // first, so a later push or plan that finds a page at this path refuses
+        // to treat it as this workspace's own until a pull adopts it.
+        if (page.action === "created") {
+          manifest.pendingCreates = { ...pendingCreates(manifest), [page.pagePath]: page.file };
+          await writeManifest(config.workspaceDir, manifest);
+        }
+        attempting = page;
+        let summary;
+        try {
+          summary = page.action === "created"
+            ? await createPage(client, { siteId, ...fields })
+            : await updatePage(client, page.pageId, { pageId: page.pageId, ...fields });
+        } catch (error) {
+          throw translateAuthorRefusal(error, page.file);
+        }
+        attempting = undefined;
         manifestDirty = true;
+        if (page.action === "created") {
+          delete manifest.pendingCreates[page.pagePath];
+          if (Object.keys(manifest.pendingCreates).length === 0) delete manifest.pendingCreates;
+        }
         applied.push({
           file: page.file,
-          path: summary.path,
+          path: displayPagePath(summary.path),
           pageId: summary.pageId,
           action: page.action,
           status: summary.status,
+          ...(page.author === "" ? {} : { author: page.author }),
         });
         // `entry?.` because a hand-edited manifest can hold a null in the list,
         // and a raw TypeError here would collapse to an opaque `site.failed`
@@ -1131,6 +1677,10 @@ export async function pagesPush(invocation) {
         // where a crash costs more than a refusal.
         const existing = manifest.pages.find((entry) => entry?.pageId === summary.pageId);
         const record = existing ?? {};
+        // The author the site holds now: what it reports, else what was just
+        // accepted, else what this workspace already knew it held.
+        const heldAuthor = summary.authorRef
+          || (page.sendAuthor ? page.author : parseAuthorReference(record.baseline?.author)?.value ?? "");
         Object.assign(record, {
           pageId: summary.pageId,
           resourceId: summary.resourceId || record.resourceId || "",
@@ -1169,9 +1719,14 @@ export async function pagesPush(invocation) {
             // Recorded for the pages whose push sends a date, so the next push
             // can tell a date the site changed from one it already holds.
             ...(sentDisplayDate(page.templateType) ? { displayDate: summary.displayDate } : {}),
+            ...(heldAuthor === "" ? {} : { author: heldAuthor }),
           },
           pendingApproval: true,
         });
+        // What the source names, kept beside the site's own for a .pm.json
+        // page, whose manifest entry is the only place it is written down.
+        if (page.author === "") delete record.author;
+        else record.author = page.author;
         if (existing === undefined) manifest.pages.push(record);
         // The override this page's record permitted has now been taken, and
         // the baseline above records what the site holds because of it.
@@ -1185,34 +1740,69 @@ export async function pagesPush(invocation) {
           await deleteWorkspaceFile(config.workspaceDir, observedRevisionFile);
         }
       }
+    } catch (error) {
+      // Each page is its own request, so a failure partway leaves earlier
+      // pages written. Name every page's outcome; the manifest below records
+      // the written ones, so a retry updates rather than duplicates them.
+      // The labels are bounded, so the failure and the count of what was not
+      // sent come first and the written pages after.
+      if (error instanceof SiteAuthoringError) {
+        // A create the site refused outright made nothing, so it leaves no marker.
+        if (attempting?.action === "created" && !outcomeUnknown(error)) {
+          delete manifest.pendingCreates[attempting.pagePath];
+          if (Object.keys(manifest.pendingCreates).length === 0) delete manifest.pendingCreates;
+          manifestDirty = true;
+        }
+        const sent = new Set(applied.map((entry) => entry.file));
+        const unsent = planned.filter((page) => !page.unchanged && !sent.has(page.file) && page !== attempting);
+        error.withCompletedWrites([
+          ...(attempting === undefined
+            ? []
+            // An ambiguous or unreadable answer may have committed; the next pull or plan tells.
+            : [`page ${attempting.pagePath || "/"}: ${outcomeUnknown(error) ? "unknown" : "failed"}`]),
+          ...(unsent.length === 0 ? [] : [`${unsent.length} more page(s): not sent`]),
+          ...(error.completedWrites ?? []),
+          ...applied.map((entry) => `page ${entry.path || "/"}: ${entry.action}`),
+        ]);
+      }
+      throw error;
     } finally {
       if (manifestDirty) await writeManifest(config.workspaceDir, manifest);
     }
 
-    const reported = boundedList(applied, MAXIMUM_REPORTED);
-    const reportedUnresolved = boundedList(unresolved, MAXIMUM_REPORTED);
+    // Pages are authorless unless a source names an author, and an owner
+    // otherwise finds the missing byline only after publishing (TR01196).
+    const authorless = applied.filter((entry) => entry.action === "created" && entry.author === undefined);
+    if (authorless.length > 0) {
+      onProgress(
+        `${authorless.length} page(s) were created without an author, so they publish with no byline. To credit one, `
+          + "add 'author: <handle or email>' to its front matter or run 'taproot-site pages meta set <path> --author "
+          + "<handle or email>', then push again; 'taproot-site authors list' shows who can be named.",
+      );
+    }
     return successResult(VERB_PAGES_PUSH, siteId, {
       pages: {
         total: planned.length,
         unchanged: planned.filter((page) => page.unchanged).length,
         created: applied.filter((entry) => entry.action === "created").length,
         updated: applied.filter((entry) => entry.action === "updated").length,
-        // What this run actually looked at, so automation can tell a targeted
-        // push from a whole-workspace one without inferring it from counts.
-        selection: targeted ? "targeted" : "workspace",
-        ...(targeted ? { selectedPaths: [...requestedPaths].sort().map((pagePath) => pagePath || "/") } : {}),
-        discovered: files.length,
+        ...selection,
         validated: planned.length,
         ...(unresolved.length > 0
+          ? { unresolved: unresolved.length, ...reportedList("unresolvedItems", unresolved, LIST_BYTES) }
+          : {}),
+        ...staleGeneratedSourcesField(staleGenerated),
+        ...reportedList("items", applied, ITEMS_BYTES),
+        ...(authorless.length > 0
           ? {
-            unresolved: unresolved.length,
-            unresolvedItems: reportedUnresolved.items,
-            ...(reportedUnresolved.truncated ? { unresolvedItemsTruncated: true } : {}),
+            authorless: {
+              total: authorless.length,
+              ...reportedList("items", authorless.map(({ file, path }) => ({ file, path })), LIST_BYTES),
+            },
           }
           : {}),
-        items: reported.items,
-        ...(reported.truncated ? { itemsTruncated: true } : {}),
       },
+      ...warnings,
       // `pages push` writes drafts. Nothing reaches an audience until `approve`
       // stages them and `deploy` publishes the site.
       // Nothing to approve when every page was unchanged and nothing was sent.