@taprootio/site-authoring 0.15.0 → 0.16.0

package/src/reference-help.js

@@ -64,7 +64,12 @@ import {
   REDIRECTS_FILE_NAME,
 } from "./redirects-contract.js";
 import { SETTINGS_GROUPS } from "./settings-catalog.js";
-import { formatTypedPageReference, getTypedPageReference, TYPED_PAGE_TYPES } from "./typed-page-reference.js";
+import {
+  formatTypedPageReference,
+  getTypedPageReference,
+  MARKDOWN_PAGE_TYPES,
+  TYPED_PAGE_TYPES,
+} from "./typed-page-reference.js";
 import { PAGE_TEMPLATES } from "./typed-pages.js";
 import {
   INTERNAL_PAGE_BASELINE_DIRECTORY,
@@ -72,6 +77,7 @@ import {
   NAVIGATION_FILE_NAME,
   PAGE_SOURCE_EXTENSIONS,
   PAGE_WORKSPACE_MODE_EDITABLE,
+  PAGE_WORKSPACE_MODE_METADATA_ONLY,
   PAGES_DIRECTORY,
   pageSourceFormat,
   SETTINGS_DIRECTORY,
@@ -80,7 +86,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 34;
+export const REFERENCE_VERSION = 35;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -672,10 +678,16 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Run 'redirects check' after staging, or read deploy --staging's automatic check. The Node CLI consumes "
       + "a separate staging handoff and checks the current map at the real edge, using an in-memory cookie and "
       + "manual redirects. It reports each path, HTTP status and Location without following targets.",
+      "The result carries routeCheck (resolved or unresolved) and redirects: { revision, revisionUnchanged, "
+      + "verified, total, checked, matched, failed, items: [{ path, status, location, expectedStatus, matches, "
+      + "error? }], itemsTruncated? }, at the top level of both redirects check and deploy --staging. An entry "
+      + "whose request failed carries error: \"request_failed\". A check that cannot finish at all reports "
+      + "verified: false, an empty items list and redirects.error { code, message }.",
       "verified is true only if every entry matched and the map revision stayed unchanged during the check. "
       + "The check proves the current map at staging, not a historical deployment. A mismatch means the staged "
       + "release does not carry the entry (yet); re-run redirects check after the deployment completes, before promoting. Requests are bounded to 90 seconds, eight at a time; "
-      + "large JSON lists are truncated explicitly with failed entries first. Human output reports every entry.",
+      + "large JSON lists are truncated explicitly with failed entries first (redirects.itemsTruncated). Progress "
+      + "output reports every entry on stderr; --quiet hides it.",
       "stagingPreview.url is a fresh, single-use two-minute handoff, minted after checks. It is emitted only "
       + "in final JSON, excluded from progress and GITHUB_OUTPUT; keep it private. The staging cookie lasts "
       + "five minutes and remains subject to current site/host/credential permission.",
@@ -937,7 +949,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + `sourceFormat, and workspaceMode ${PAGE_WORKSPACE_MODE_EDITABLE}. Album images and the cover image must be `
       + "listed in fixture.imageIds. "
       + "status, hasDraft, isGenerated, and description are recorded by pull and not read: the page key set "
-      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string.",
+      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string. "
+      + `An entry with workspaceMode ${PAGE_WORKSPACE_MODE_METADATA_ONLY} names a page the fixture has no source for, `
+      + "such as a generated section page navigation links to: pageId, resourceId and path, and no file.",
       `file lives under '${PAGES_DIRECTORY}/' and ends in ${PAGE_SOURCE_EXTENSIONS.join(" or ")}; sourceFormat must be `
       + `the format that extension implies (${
         PAGE_SOURCE_EXTENSIONS.map((extension) => `${extension} is '${pageSourceFormat(`page${extension}`)}'`).join(
@@ -971,8 +985,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "validate reads the fixture and writes nothing to it. Copy the directory somewhere writable before editing it.",
       "validate --init <new-directory> exports the current pulled workspace as a validated version-7 fixture with "
       + "appearance and footer metadata. Run from the workspace or its configured project; --config may select the source.",
-      "Initialization keeps editable pages of every template as workspace documents and reports excluded metadata-only pages. "
-      + "References to excluded pages must be resolved before the fixture can validate. It never copies credentials, "
+      "Initialization keeps editable pages of every template as workspace documents. A metadata-only page that "
+      + "navigation, the footer or a page links to is kept as a metadata-only entry (initialized.linkedPages); other "
+      + "metadata-only pages are left out (initialized.skippedPages). It never copies credentials, "
       + "internal reconciliation state, or deployment receipts. UUIDs and HTTP(S) origins are replaced with deterministic "
       + "fixture identities and example.test origins; URL credentials, queries and fragments are removed. Authored prose is retained.",
       "The destination must be outside the source workspace and must not exist; its parent must already exist without symlinks. Exports are bounded to 64 MiB. "
@@ -1518,6 +1533,31 @@ const FREE_FORM_REFERENCE = Object.freeze({
         + "refuses before changing anything under pages/ and preserves the site's version as internal state. A "
         + "locally edited .pm.json is kept rather than overwritten, and only collides when the site changed too.",
       conflictError: "pages.pull_conflict",
+      metadata:
+        "A .pm.json page's title, path and description live in the manifest, not the file. Change the title or "
+        + "description with pages meta set <path> --title/--description; a Markdown page keeps them in its front "
+        + "matter. pull keeps such an edit until pages push sends it, and a site edit to the same page is a "
+        + "pages.pull_conflict. A description over 160 characters is warned about (search results cut it off); "
+        + "over 1000 is refused.",
+      authorship:
+        "Pages are authorless by default: a page created without an author publishes with no byline, and pages push "
+        + "lists the pages it created that way in pages.authorless. Name an author with author: in the front matter "
+        + "(every template) or, for a .pm.json page, pages meta set <path> --author. An author is a site author "
+        + "without a Taproot account, named by handle (jane-doe), or a site member who can create pages, named by "
+        + "email address. authors list shows who can be named and rewrites authors.json; authors add <handle> "
+        + "--name <name> [--email <address>] creates a site author, whose address stays private. A site author's "
+        + "name appears on the byline and in structured data, with no profile link or follow button. authors add "
+        + "again with the same handle and name succeeds (existing: true); another name for a taken handle is "
+        + "authors.handle_taken. Only the CLI assigns authors, and only to a page that has none. authors.json is as old "
+        + "as the last pull or authors list, so offline commands (validate, pages meta set) only warn "
+        + "(pages.author_unverified) about a name it lacks; pages push and plan read the site's current list once on a "
+        + "miss and refuse only a name the site lacks. The CLI only fills a page that has no author: a different one "
+        + "already on the page is pages.author_conflict, which names the way out (pages meta set <path> --author "
+        + "<the site's author> for a .pm.json page, the author: line for Markdown, or pages meta set <path> --author "
+        + "\"\" to drop an author that was never sent), naming the author a page already has changes nothing, and a "
+        + "name that is unknown or belongs to a member who cannot create pages is pages.author_unknown either way. "
+        + "Text that is neither a handle nor an address is pages.author_invalid.",
+      authorshipErrors: Object.freeze(["pages.author_invalid", "pages.author_unknown", "pages.author_conflict"]),
       conflictDetail:
         "A reported conflict names the JSON paths at which the site's document differs from the copy this workspace "
         + "last reconciled with, in error.differences, which carries three states. Absent: the two documents were "
@@ -1569,13 +1609,23 @@ const FREE_FORM_REFERENCE = Object.freeze({
             inheritedForTracked: true,
             defaultForNew: "",
           }),
+          Object.freeze({
+            name: "author",
+            type: "string",
+            requiredForNew: false,
+            inheritedForTracked: true,
+            defaultForNew: "",
+            description:
+              "A site author's handle (jane-doe) or a member's email address. Omit it for an authorless page; it "
+              + "only fills a page that has none, and never replaces one.",
+          }),
           Object.freeze({
             name: "template",
             type: "string",
             requiredForNew: false,
             inheritedForTracked: false,
             defaultForNew: "free-form",
-            description: `Other templates: ${TYPED_PAGE_TYPES.join(", ")}; see '${CLI_BINARY_NAME} help pages'.`,
+            description: `Other templates: ${MARKDOWN_PAGE_TYPES.join(", ")}; see '${CLI_BINARY_NAME} help pages'.`,
           }),
         ]),
       }),
@@ -1866,7 +1916,7 @@ export function formatReferenceResult(result) {
         page.workspace.formats.map((format) => `  ${format.extension.padEnd(9)} ${format.purpose}`).join("\n")
       }\n\nOne source per page:\n  rule                  ${sourceRule.rule}\n  manifest fields       ${
         sourceRule.manifestFields.join(", ")
-      }\n  pull                  ${sourceRule.pull}\n  internal state        ${sourceRule.internalState}\n  format change         ${sourceRule.formatChange} (${sourceRule.formatChangeError})\n  renamed source        ${sourceRule.renamedSource} (${sourceRule.renamedSourceError})\n  conflicts             ${sourceRule.conflict} (${sourceRule.conflictError})\n  conflict detail       ${sourceRule.conflictDetail}\n  push conflicts        ${sourceRule.pushConflict} (${sourceRule.pushConflictError})\n  revision              ${sourceRule.revisionSource}\n  recovery              ${sourceRule.conflictRecovery}\n  push selection        ${sourceRule.pushSelection}\n\nSystem pages: ${page.workspace.systemPages}\n\nMarkdown front matter:\n${
+      }\n  pull                  ${sourceRule.pull}\n  internal state        ${sourceRule.internalState}\n  format change         ${sourceRule.formatChange} (${sourceRule.formatChangeError})\n  renamed source        ${sourceRule.renamedSource} (${sourceRule.renamedSourceError})\n  conflicts             ${sourceRule.conflict} (${sourceRule.conflictError})\n  conflict detail       ${sourceRule.conflictDetail}\n  push conflicts        ${sourceRule.pushConflict} (${sourceRule.pushConflictError})\n  revision              ${sourceRule.revisionSource}\n  recovery              ${sourceRule.conflictRecovery}\n  push selection        ${sourceRule.pushSelection}\n  authors               ${sourceRule.authorship} (${sourceRule.authorshipErrors.join(", ")})\n\nSystem pages: ${page.workspace.systemPages}\n\nMarkdown front matter:\n${
         markdownFormat.metadata.map(formatMetadata).join("\n")
       }\n\nDocument root: { "type": "doc", "content": [...] }\nSupported nodes: ${
         page.document.nodes.join(", ")

package/src/staging-check.js

@@ -152,3 +152,65 @@ export async function checkStagingRedirects(client, siteId, onProgress, now) {
     },
   };
 }
+
+/**
+ * The staging redirect check and a fresh preview handoff, as redirects check and
+ * deploy --staging report them. A check that cannot finish keeps the same shape,
+ * with the reason.
+ */
+export async function inspectStagingPreview(client, siteId, onProgress, now) {
+  let routeCheck;
+  let redirects;
+  let stagingUrl;
+  try {
+    ({ routeCheck, redirects, stagingUrl } = await checkStagingRedirects(client, siteId, onProgress, now));
+    if (!redirects.verified) {
+      onProgress(
+        "Warning: staging redirects are not all verified. Check the reported mismatches against the staged release; run 'taproot-site redirects check' again once the deployment has completed.",
+      );
+    }
+  } catch (error) {
+    onProgress(
+      "Warning: the authenticated staging redirect check could not finish. Run 'taproot-site redirects check' again.",
+    );
+    routeCheck = "unresolved";
+    redirects = {
+      total: 0,
+      checked: 0,
+      matched: 0,
+      failed: 0,
+      verified: false,
+      items: [],
+      error: redirectCheckError(error),
+    };
+  }
+  try {
+    // Mint after checks so the final single-use URL has never been consumed.
+    const stagingPreview = await mintStagingPreviewHandoff(client, siteId, { now });
+    return { routeCheck, redirects, stagingPreview };
+  } catch {
+    onProgress("Warning: a staging handoff could not be minted.");
+    return {
+      routeCheck,
+      redirects,
+      stagingPreview: {
+        url: "",
+        ...(stagingUrl ? { stagingUrl } : {}),
+        warning: "Staging handoff unavailable; run redirects check to retry.",
+      },
+    };
+  }
+}
+
+/**
+ * Why the automatic redirect check could not finish. Only this CLI's own
+ * errors carry their code and message; anything else (a timeout, a network
+ * failure) is named, never echoed, since its text is not ours to publish.
+ */
+function redirectCheckError(error) {
+  if (error instanceof SiteAuthoringError) {
+    return { code: error.code, message: sanitizeDiagnostic(error.message, "The redirect check could not finish.") };
+  }
+  const name = typeof error?.name === "string" && /^[A-Za-z]{1,40}$/u.test(error.name) ? error.name : "Error";
+  return { code: "redirects.check_failed", message: `The redirect check could not finish (${name}).` };
+}

package/src/typed-page-reference.js

@@ -4,6 +4,7 @@ import {
   PLACE_REVIEW_RATINGS,
   TEMPLATE_ALBUM,
   TEMPLATE_ARTICLE,
+  TEMPLATE_GENERATED,
   TEMPLATE_PLACE_REVIEW,
   TEMPLATE_RECIPE,
 } from "./typed-pages.js";
@@ -35,6 +36,14 @@ const FIELD_HELP = Object.freeze({
     required: true,
     description: "Selects the template. A page's template never changes after it is created.",
   },
+  author: {
+    type: "string",
+    required: false,
+    description:
+      "Credits the page to a site author by handle (jane-doe) or to a site member who can create pages by email "
+      + "address. Pages are authorless unless you name one, and an author already on the page is never replaced. "
+      + "'authors list' shows who can be named; 'authors add' creates a site author without an account.",
+  },
   displayDate: {
     type: "YYYY-MM-DD",
     required: false,
@@ -270,48 +279,106 @@ const TYPE_DETAILS = Object.freeze({
       "body: ProseMirror document (required, not empty)",
     ],
   },
+  [TEMPLATE_GENERATED]: {
+    displayName: "Generated page",
+    summary:
+      "A listing Taproot generates from the site's content: a tag, the tags index, a published year or month, a place "
+      + "archive, or a folder. You cannot create one; you customize its title, breadcrumb, description and introduction.",
+    documentExample: documentExample(
+      TEMPLATE_GENERATED,
+      {},
+      {
+        kind: "GENERATED_PAGE_KIND_TAG",
+        tagId: "0198a3f2-7c4e-4a10-9b2d-3f6e5d4c3b2a",
+        year: 0,
+        month: 0,
+        countryCode: "",
+        regionCode: "",
+        citySlug: "",
+        categorySlug: "",
+        customTitle: "Trail notes",
+        breadcrumbTitle: "",
+        customDescription: "Field notes from the trails I walk most often.",
+        introductionBody: PARAGRAPH("Everything I have written about walking."),
+      },
+    ),
+    dataFields: [
+      "kind and the identity fields (tagId, year, month, countryCode, regionCode, citySlug, categorySlug): what the "
+      + "page is, written by pull. Leave them as pulled; a push that changes them is refused (pages.generated_identity)",
+      "customTitle: string; empty uses the generated title (the page's reader-facing title)",
+      "breadcrumbTitle: string; empty uses the generated label (used on pages beneath this one)",
+      "customDescription: string, at most 1000 characters, about 160 shown in search results; empty uses the "
+      + "introduction's first paragraph, else the generated description",
+      "introductionBody: ProseMirror document (optional), shown above the generated listing",
+    ],
+    note:
+      "The manifest's title and description for a generated page are what the site reports, recorded for reference; "
+      + "edit customTitle and customDescription here (or with 'pages meta set'), not the manifest. "
+      + "pages push updates the page and refuses to create one (pages.generated_create), move it (pages.generated_move) "
+      + "or change its identity (pages.generated_identity). The site derives the page's title and description from "
+      + "customTitle, customDescription and introductionBody, so what a push sends for them is ignored. A source the site "
+      + "no longer has a page for is reported and skipped by a whole-workspace push.",
+  },
 });
 
 export const TYPED_PAGE_TYPES = Object.freeze(Object.keys(TYPE_DETAILS));
+/** The templates a Markdown source can declare: every typed page but the update-only generated one. */
+export const MARKDOWN_PAGE_TYPES = Object.freeze(TYPED_PAGE_TYPES.filter((type) => type !== TEMPLATE_GENERATED));
 
 function typedReference(type) {
   const details = TYPE_DETAILS[type];
+  const generated = type === TEMPLATE_GENERATED;
   return Object.freeze({
     type,
     displayName: details.displayName,
     summary: details.summary,
     workspace: Object.freeze({
       directory: `${PAGES_DIRECTORY}/`,
-      sourceRule:
-        `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
-        + "The template is declared in the source (front matter 'template', or the .pm.json 'template' field) and is "
-        + "immutable after creation: pages push refuses a source whose template differs from the live page's "
-        + "(pages.template_immutable).",
-      pull:
-        "pull writes each page of this template as a .pm.json document, byte-stable across pulls. A page you authored as "
-        + "Markdown keeps its Markdown source, and a change made on the site since the last pull is reported as a conflict.",
+      sourceRule: generated
+        ? `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
+          + "A generated page exists only because the site's content produces it, so its source exists only after "
+          + "'pull' and is never created by hand."
+        : `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
+          + "The template is declared in the source (front matter 'template', or the .pm.json 'template' field) and is "
+          + "immutable after creation: pages push refuses a source whose template differs from the live page's "
+          + "(pages.template_immutable).",
+      pull: generated
+        ? "pull writes each generated page as a .pm.json document, byte-stable across pulls, and keeps your edits to it "
+          + "when the site's copy has not changed. A change made on the site since the last pull is reported as a conflict."
+        : "pull writes each page of this template as a .pm.json document, byte-stable across pulls. A page you authored as "
+          + "Markdown keeps its Markdown source, and a change made on the site since the last pull is reported as a conflict.",
       formats: Object.freeze([
-        Object.freeze({
+        ...(generated ? [] : [Object.freeze({
           extension: ".md",
           purpose: "Author the page as Markdown with front matter.",
           metadata: Object.freeze(
             frontMatterKeysFor(type).map((name) => Object.freeze({ name, ...FIELD_HELP[name] })),
           ),
-        }),
+        })]),
         Object.freeze({
           extension: ".pm.json",
-          purpose:
-            "The pulled form: { template, displayDate?, coverImageId?, data }. Title, path and description come from the manifest.",
+          purpose: generated
+            ? "The pulled form, and the only one: { template, data }. Path comes from the manifest; title and description "
+              + "are the custom ones in data."
+            : "The pulled form: { template, displayDate?, coverImageId?, data }. Title, path and description come from the manifest.",
           dataFields: Object.freeze(details.dataFields),
         }),
       ]),
     }),
-    markdown: Object.freeze({ body: details.body, example: details.markdownExample }),
+    ...(generated ? {} : { markdown: Object.freeze({ body: details.body, example: details.markdownExample }) }),
     document: Object.freeze({ example: details.documentExample, ...(details.note ? { note: details.note } : {}) }),
     workflow: Object.freeze([
-      Object.freeze({ command: `${CLI_BINARY_NAME} media upload`, result: "Upload cover and album images first." }),
+      ...(generated
+        ? [Object.freeze({
+          command: `${CLI_BINARY_NAME} pull, then pages meta set <path> --title/--description`,
+          result: "Pull the page, then set its custom title or description (or edit the .pm.json).",
+        })]
+        : [Object.freeze({ command: `${CLI_BINARY_NAME} media upload`, result: "Upload cover and album images first." })]),
       Object.freeze({ command: `${CLI_BINARY_NAME} validate`, result: "Check the workspace before sending anything." }),
-      Object.freeze({ command: `${CLI_BINARY_NAME} pages push`, result: "Create or update an unapproved draft." }),
+      Object.freeze({
+        command: `${CLI_BINARY_NAME} pages push`,
+        result: generated ? "Update the generated page's unapproved draft." : "Create or update an unapproved draft.",
+      }),
       Object.freeze({
         command: `${CLI_BINARY_NAME} approve, deploy --staging, deploy --production`,
         result: "Stage, review and promote, as for any page.",
@@ -335,9 +402,10 @@ function formatField(field) {
 export function formatTypedPageReference(page) {
   const markdown = page.workspace.formats.find((format) => format.extension === ".md");
   const json = page.workspace.formats.find((format) => format.extension === ".pm.json");
-  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n  pull                  ${page.workspace.pull}\n\nMarkdown front matter:\n${
-    markdown.metadata.map(formatField).join("\n")
-  }\n\nMarkdown body: ${page.markdown.body}\n\nMarkdown example:\n${page.markdown.example}\n.pm.json (${json.purpose})\n  data:\n${
+  const markdownSection = markdown === undefined
+    ? ""
+    : `Markdown front matter:\n${markdown.metadata.map(formatField).join("\n")}\n\nMarkdown body: ${page.markdown.body}\n\nMarkdown example:\n${page.markdown.example}\n`;
+  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n  pull                  ${page.workspace.pull}\n\n${markdownSection}.pm.json (${json.purpose})\n  data:\n${
     json.dataFields.map((field) => `    ${field}`).join("\n")
   }\n${page.document.note === undefined ? "" : `  ${page.document.note}\n`}\n.pm.json example:\n${
     JSON.stringify(page.document.example, null, 2)

package/src/typed-pages.js

@@ -1,6 +1,7 @@
 import { FREE_FORM_TEMPLATE_VERSION, TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { isVideoEmbedId } from "./content/video-embed-url.js";
 import { SiteAuthoringError } from "./errors.js";
+import { requireDescriptionLength } from "./page-metadata.js";
 
 /**
  * The authored page templates (TR00893).
@@ -29,6 +30,12 @@ export const TEMPLATE_ARTICLE = "article";
 export const TEMPLATE_RECIPE = "recipe";
 export const TEMPLATE_ALBUM = "album";
 export const TEMPLATE_PLACE_REVIEW = "place-review";
+/**
+ * A page Taproot generates (a tag, a month, a folder). It is update-only: the
+ * owner's title, breadcrumb, description and introduction are authored, and
+ * pages push refuses to create one or to change what it is (TR01195).
+ */
+export const TEMPLATE_GENERATED = "generated";
 
 /** Wire identity and the `PageTemplate` member that carries each template's data. */
 export const PAGE_TEMPLATES = Object.freeze({
@@ -37,12 +44,13 @@ export const PAGE_TEMPLATES = Object.freeze({
   [TEMPLATE_RECIPE]: Object.freeze({ wireType: "TEMPLATE_TYPE_RECIPE", dataKey: "recipeData" }),
   [TEMPLATE_ALBUM]: Object.freeze({ wireType: "TEMPLATE_TYPE_ALBUM", dataKey: "albumData" }),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze({ wireType: "TEMPLATE_TYPE_PLACE_REVIEW", dataKey: "placeReviewData" }),
+  [TEMPLATE_GENERATED]: Object.freeze({ wireType: "TEMPLATE_TYPE_GENERATED", dataKey: "generatedPageData" }),
 });
 
 export const PAGE_TEMPLATE_NAMES = Object.freeze(Object.keys(PAGE_TEMPLATES));
 
 /** Front-matter fields every template accepts. */
-export const SHARED_FRONT_MATTER_KEYS = Object.freeze(["title", "path", "description", "template"]);
+export const SHARED_FRONT_MATTER_KEYS = Object.freeze(["title", "path", "description", "template", "author"]);
 
 /**
  * The page-level fields the other templates add. A free-form page's source is
@@ -67,6 +75,8 @@ const TEMPLATE_FRONT_MATTER_KEYS = Object.freeze({
   ]),
   [TEMPLATE_ALBUM]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "seamless", "borderWidth", "place"]),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "placeId", "rating"]),
+  // Generated pages have no Markdown form.
+  [TEMPLATE_GENERATED]: Object.freeze([]),
 });
 
 export const FRONT_MATTER_KEYS = Object.freeze(
@@ -96,6 +106,52 @@ const DISPLAY_DATE = /^\d{4}-\d{2}-\d{2}$/u;
 const ALBUM_IMAGES_HEADING = "images";
 const RECIPE_HEADINGS = Object.freeze(["ingredients", "instructions"]);
 
+/** The generated page kinds the site reports, as the API names them (never the unknown kind). */
+export const GENERATED_PAGE_KINDS = Object.freeze([
+  "GENERATED_PAGE_KIND_TAG",
+  "GENERATED_PAGE_KIND_TAGS_INDEX",
+  "GENERATED_PAGE_KIND_PUBLISHED_INDEX",
+  "GENERATED_PAGE_KIND_PUBLISHED_YEAR",
+  "GENERATED_PAGE_KIND_PUBLISHED_MONTH",
+  "GENERATED_PAGE_KIND_PLACES_INDEX",
+  "GENERATED_PAGE_KIND_PLACES_COUNTRY",
+  "GENERATED_PAGE_KIND_PLACES_STATE",
+  "GENERATED_PAGE_KIND_PLACES_CITY",
+  "GENERATED_PAGE_KIND_PLACES_CATEGORY",
+  "GENERATED_PAGE_KIND_FOLDER_INDEX",
+]);
+/** What a generated page is: system-managed, so a push must send it back unchanged. */
+export const GENERATED_IDENTITY_KEYS = Object.freeze([
+  "kind",
+  "tagId",
+  "year",
+  "month",
+  "countryCode",
+  "regionCode",
+  "citySlug",
+  "categorySlug",
+]);
+const GENERATED_KEYS = [
+  ...GENERATED_IDENTITY_KEYS,
+  "customTitle",
+  "breadcrumbTitle",
+  "customDescription",
+  "introductionBody",
+];
+const GENERATED_TEXT_KEYS = [
+  "tagId",
+  "countryCode",
+  "regionCode",
+  "citySlug",
+  "categorySlug",
+  "customTitle",
+  "breadcrumbTitle",
+  "customDescription",
+];
+const GENERATED_MAXIMUM_YEAR = 9999;
+const GENERATED_MAXIMUM_MONTH = 12;
+const EMPTY_DOCUMENT = Object.freeze({ type: "doc", content: Object.freeze([]) });
+
 function fail(code, message, field) {
   return new SiteAuthoringError(code, message, { field });
 }
@@ -116,6 +172,32 @@ export function isAuthorableTemplateType(wireType) {
   return templateNameForWireType(wireType) !== undefined;
 }
 
+/** Whether a wire `templateType` is a generated page. */
+export function isGeneratedTemplateType(wireType) {
+  return wireType === PAGE_TEMPLATES[TEMPLATE_GENERATED].wireType;
+}
+
+/** The system-managed fields of a generated page's `data`, which the manifest records and a push must not change. */
+export function generatedIdentity(data) {
+  return Object.fromEntries(GENERATED_IDENTITY_KEYS.map((key) => [key, data[key]]));
+}
+
+/** The names of the identity fields that differ, for a message. */
+export function changedGeneratedIdentity(recorded, data) {
+  return GENERATED_IDENTITY_KEYS.filter((key) => recorded[key] !== data[key]);
+}
+
+/** The title a generated page is sent with: the owner's, else the one the site last reported. */
+export function generatedPageTitle(data, reportedTitle) {
+  // Trimmed as Taproot trims it, or a padded title would never match the key a pull recorded.
+  return data.customTitle.trim() || reportedTitle;
+}
+
+/** The description a generated page is sent with: the owner's, else the one the site last reported. */
+export function generatedPageDescription(data, reportedDescription) {
+  return data.customDescription.trim() === "" ? reportedDescription : data.customDescription.trim();
+}
+
 /** The template a canonical workspace document represents. */
 export function documentTemplate(document_) {
   return isPlainObject(document_) && typeof document_.template === "string" && document_.type === undefined
@@ -262,6 +344,22 @@ function canonicalIngredient(value) {
 const DATA_BUILDERS = Object.freeze({
   [TEMPLATE_ARTICLE]: (raw) => definedEntries([["body", raw.body], ["place", raw.place]]),
   [TEMPLATE_PLACE_REVIEW]: (raw) => ({ placeId: raw.placeId, rating: raw.rating, body: raw.body }),
+  // Defaults are written out, so a page with no custom title reads the same on every pull.
+  [TEMPLATE_GENERATED]: (raw) =>
+    definedEntries([
+      ["kind", raw.kind],
+      ["tagId", raw.tagId ?? ""],
+      ["year", raw.year ?? 0],
+      ["month", raw.month ?? 0],
+      ["countryCode", raw.countryCode ?? ""],
+      ["regionCode", raw.regionCode ?? ""],
+      ["citySlug", raw.citySlug ?? ""],
+      ["categorySlug", raw.categorySlug ?? ""],
+      ["customTitle", raw.customTitle ?? ""],
+      ["breadcrumbTitle", raw.breadcrumbTitle ?? ""],
+      ["customDescription", raw.customDescription ?? ""],
+      ["introductionBody", raw.introductionBody],
+    ]),
   [TEMPLATE_ALBUM]: (raw) =>
     definedEntries([
       ["introductionBody", raw.introductionBody],
@@ -339,6 +437,30 @@ function canonicalSourceData(template, data, file) {
       body: requireDocument(data.body, file, `${path}.body`, { nonEmpty: true }),
     });
   }
+  if (template === TEMPLATE_GENERATED) {
+    requireKeys(data, GENERATED_KEYS, file, path);
+    if (!GENERATED_PAGE_KINDS.includes(data.kind)) {
+      throw fail(
+        "pages.document_shape",
+        `'${file}' ${path}.kind must be one of ${GENERATED_PAGE_KINDS.join(", ")}.`,
+        file,
+      );
+    }
+    for (const key of GENERATED_TEXT_KEYS) {
+      if (data[key] !== undefined) requireString(data[key], file, `${path}.${key}`);
+    }
+    if (data.tagId !== undefined && data.tagId !== "") requireIdentifier(data.tagId, file, `${path}.tagId`);
+    if (data.year !== undefined) requireCount(data.year, file, `${path}.year`, GENERATED_MAXIMUM_YEAR);
+    if (data.month !== undefined) requireCount(data.month, file, `${path}.month`, GENERATED_MAXIMUM_MONTH);
+    // The API trims a description, so the length that counts is the trimmed one.
+    const customDescription = data.customDescription?.trim();
+    requireDescriptionLength(customDescription, `${file}:${path}.customDescription`);
+    return DATA_BUILDERS[template]({
+      ...data,
+      customDescription,
+      introductionBody: OPTIONAL_INTRODUCTION(data.introductionBody, file, `${path}.introductionBody`),
+    });
+  }
   if (template === TEMPLATE_ALBUM) {
     requireKeys(data, ALBUM_KEYS, file, path);
     const images = requireArray(data.images, file, `${path}.images`);
@@ -442,6 +564,14 @@ export function typedDocumentFromJson(parsed, file) {
       file,
     );
   }
+  if (template === TEMPLATE_GENERATED && (parsed.displayDate !== undefined || parsed.coverImageId !== undefined)) {
+    throw fail(
+      "pages.document_shape",
+      `'${file}' is a generated page, which has no displayDate or coverImageId of its own: its document is `
+        + "{ template, data }.",
+      file,
+    );
+  }
   const displayDate = parsed.displayDate === undefined ? undefined : requireDisplayDate(parsed.displayDate, file);
   let coverImageId;
   if (parsed.coverImageId !== undefined) {
@@ -482,6 +612,17 @@ const PAGE_PROJECTIONS = Object.freeze({
     if (body === undefined || rating === undefined || typeof raw.placeId !== "string") return undefined;
     return DATA_BUILDERS[TEMPLATE_PLACE_REVIEW]({ placeId: raw.placeId, rating, body });
   },
+  // A kind this package does not know cannot be pushed back safely, so it is not readable here.
+  [TEMPLATE_GENERATED]: (raw) =>
+    GENERATED_PAGE_KINDS.includes(raw.kind)
+      ? DATA_BUILDERS[TEMPLATE_GENERATED]({
+        kind: raw.kind,
+        ...Object.fromEntries(GENERATED_TEXT_KEYS.map((key) => [key, typeof raw[key] === "string" ? raw[key] : ""])),
+        year: Number.isSafeInteger(raw.year) ? raw.year : 0,
+        month: Number.isSafeInteger(raw.month) ? raw.month : 0,
+        introductionBody: presentIntroduction(raw.introductionBody),
+      })
+      : undefined,
   [TEMPLATE_ALBUM]: (raw) =>
     DATA_BUILDERS[TEMPLATE_ALBUM]({
       introductionBody: presentIntroduction(raw.introductionBody),
@@ -524,9 +665,15 @@ export function workspaceDocumentFromPage(page, listedTemplateType) {
   if (name === TEMPLATE_FREE_FORM) return isPlainObject(raw.body) ? raw.body : undefined;
   const data = PAGE_PROJECTIONS[name](raw);
   if (data === undefined) return undefined;
+  // A generated page's date and cover are not part of its source: a push leaves them as the site holds them.
+  const generated = name === TEMPLATE_GENERATED;
   return typedDocument(name, {
-    displayDate: typeof page.displayDate === "string" && page.displayDate !== "" ? page.displayDate : undefined,
-    coverImageId: typeof page.coverImageId === "string" && page.coverImageId !== "" ? page.coverImageId : undefined,
+    displayDate: !generated && typeof page.displayDate === "string" && page.displayDate !== ""
+      ? page.displayDate
+      : undefined,
+    coverImageId: !generated && typeof page.coverImageId === "string" && page.coverImageId !== ""
+      ? page.coverImageId
+      : undefined,
     data,
   });
 }
@@ -558,7 +705,7 @@ export function contentDocuments(document_) {
 /** Whether a push sends `displayDate` for pages of this wire template type (every template but free-form). */
 export function sentDisplayDate(wireType) {
   const name = templateNameForWireType(wireType);
-  return name !== undefined && name !== TEMPLATE_FREE_FORM;
+  return name !== undefined && name !== TEMPLATE_FREE_FORM && name !== TEMPLATE_GENERATED;
 }
 
 // The nodes the API accepts in an album or recipe introduction and in a recipe
@@ -742,6 +889,9 @@ export function wireTemplate(document_) {
     ? { body: document_ }
     : template === TEMPLATE_PLACE_REVIEW
     ? { ...document_.data, rating: PLACE_REVIEW_RATINGS[document_.data.rating] }
+    // The API reads a missing introduction as no document at all, so the empty one is sent.
+    : template === TEMPLATE_GENERATED
+    ? { ...document_.data, introductionBody: document_.data.introductionBody ?? EMPTY_DOCUMENT }
     : document_.data.place === undefined
     ? document_.data
     : { ...document_.data, place: { placeId: document_.data.place } };
@@ -960,6 +1110,16 @@ function parseFlag(fields, key, file) {
   return value === "true";
 }
 
+/** Generated pages are edited in their .pm.json source only. */
+export function generatedMarkdownFault(file) {
+  return fail(
+    "pages.generated_markdown",
+    `'${file}' declares the generated template, which has no Markdown form: a generated page is pulled as a `
+      + ".pm.json document and edited there.",
+    file,
+  );
+}
+
 /**
  * Front-matter fields the declared template does not accept.
  *
@@ -988,6 +1148,7 @@ export function templateFrontMatterFault(template, fieldNames, file) {
  * module stays pure.
  */
 export async function typedDocumentFromMarkdown({ template, fields, markdown, file, convert, resolveImage }) {
+  if (template === TEMPLATE_GENERATED) throw generatedMarkdownFault(file);
   const displayDate = fields.has("displayDate") ? requireDisplayDate(fields.get("displayDate"), file) : undefined;
   let coverImageId;
   if (fields.has("coverImage")) {