@taprootio/site-authoring 0.11.1 → 0.12.1

package/src/reference-help.js

@@ -1,6 +1,5 @@
 import { readFileSync } from "node:fs";
 
-import { TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { CLI_BINARY_NAME } from "./constants.js";
 import {
   canonicalizeComponentData,
@@ -35,6 +34,8 @@ 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 { PAGE_TEMPLATES } from "./typed-pages.js";
 import {
   INTERNAL_PAGE_BASELINE_DIRECTORY,
   MANIFEST_VERSION,
@@ -49,8 +50,8 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 27;
-export const PAGE_TYPES = Object.freeze(["free-form"]);
+export const REFERENCE_VERSION = 28;
+export const PAGE_TYPES = Object.freeze(["free-form", ...TYPED_PAGE_TYPES]);
 
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
@@ -334,7 +335,7 @@ export function getDesignBlueprint(type) {
   return DESIGN_BLUEPRINTS.find((blueprint) => blueprint.type === type);
 }
 export const REFERENCE_TOPICS = Object.freeze([
-  Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types." }),
+  Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types: free-form, article, recipe, album, place-review." }),
   Object.freeze({
     name: "page",
     usage: `${CLI_BINARY_NAME} help page <page-type>`,
@@ -397,6 +398,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help footer`,
     summary: "Author and concurrency-safely push the complete footer document.",
   }),
+  Object.freeze({
+    name: "import",
+    usage: `${CLI_BINARY_NAME} help import`,
+    summary: "Import an existing WordPress site from its export: mapping rules, order of work, and what to report.",
+  }),
   Object.freeze({
     name: "fixture",
     usage: `${CLI_BINARY_NAME} help fixture`,
@@ -405,6 +411,60 @@ export const REFERENCE_TOPICS = Object.freeze([
 ]);
 
 const WORKFLOW_REFERENCES = Object.freeze({
+  import: Object.freeze({
+    title: "Importing a WordPress site",
+    summary: "Turn a WordPress export (WXR) into a published Taproot site with the templates, dates, media and redirects preserved, and a written account of everything that could not be mapped.",
+    usage: `${CLI_BINARY_NAME} pull | media upload <files...> | pages push | redirects push | nav push | deploy --staging`,
+    details: Object.freeze([
+      "Source: a WordPress export file (Tools > Export > All content, WXR 1.2). Read the live site only when the owner "
+      + "has said you may; the export names every media URL but carries no image bytes, so downloading originals from "
+      + "the old site also needs that permission. Work in a fresh workspace: 'use' the site, then 'pull'.",
+      "Order of work: 1 parse the export; 2 classify every item; 3 stage media; 4 write page sources; 5 check every "
+      + "source; 6 pages push; 7 nav.json and nav push; 8 redirects.json and redirects push; 9 approve, deploy "
+      + "--staging, review it; 10 redirects check and delivery check --staging; 11 deploy --production; 12 delivery "
+      + "check --production --url <the origin 'sites' reports as primaryDomain>. Do not promote until the account of unmapped content has been read by the owner.",
+      "Classify. Published post: article (the default); recipe when it has an Ingredients list and a Steps list "
+      + "(help page recipe); album when it is a gallery with little text (help page album). Published page: a free-form "
+      + "page at its path, children under their parent's path. Never guess a place review: it needs a Taproot "
+      + "placeId this CLI cannot look up, so import the post as an article and list it. Not imported, and always "
+      + "listed: drafts, pending, private, scheduled and password-protected items; custom post types; comments; the WordPress front "
+      + "page (Taproot seeds its own home page: ask the owner what belongs there).",
+      "Paths and dates. A post's path is '<first category slug, ignoring the default Uncategorized>/<post name>' ('journal/' with no category; a post or page whose slug has no ASCII letters gets a name like post-<id>, listed), a "
+      + "page's is its post name under its parents. Keep the original publication date in displayDate (the date "
+      + "part of wp:post_date). Categories beyond the first, and all tags, have no Taproot equivalent (tags are "
+      + "generated per page type): list them. The featured image becomes coverImage on typed pages, and the same image must also appear in the page's own content (put it at the top of the body), or the site refuses the cover; a free-form page "
+      + "has none, so list it.",
+      "Content. Convert the HTML to the Markdown subset. Keep headings from h2 to h4 (the title is the h1; deeper levels are refused, so make h5 and h6 an h4). Decode HTML entities (&amp;, &#8217;) in titles, excerpts, menu labels and term names; WordPress stores them encoded. An image "
+      + "must stand alone in its own block, so split paragraphs around images and lift images out of links; a link "
+      + "to the full-size file is dropped, so list it. Tables need a header row and 2 to 12 columns, else write "
+      + "a list and report it. Remove Gutenberg block comments and the more-tag marker. In a recipe, times and servings "
+      + "go to front matter, text after the steps moves into the introduction with its headings dropped to level 3, and the only "
+      + "level-2 headings are Ingredients and Instructions; an album's only level-2 heading is Images.",
+      "Report, never silently drop. Shortcodes with no equivalent ([contact-form-7], [adsense], maps, recipe cards "
+      + "whose data sits in separate records), iframes and other embeds (a YouTube, Vimeo, X/Twitter, Instagram or TikTok address becomes a plain "
+      + "link), scripts, video and audio elements, inline styles, galleries (flattened to sequential images, or an "
+      + "album when they are the post), links to content you did not import (keep the absolute old link), and images "
+      + "on other hosts. Every item goes in the account with its page and what happened to it.",
+      "Media. Save each original in the workspace's media/ directory (PNG, JPEG, GIF or WebP up to 32 MiB each; list SVG, AVIF, HEIC and oversized files, which cannot be uploaded; use the original, not "
+      + "the -300x200 thumbnail WordPress also stores), then upload in batches of at most 10 files (conservative: the limit depends on how long the delivery URLs are, and was measured only with short stand-in URLs): 'media upload' "
+      + "prints every file's delivery URLs into a result capped at 64 KiB, and a longer batch uploads everything, "
+      + "writes .taproot-site-media.json, then exits 1 with output.too_large. If that happens the files are already "
+      + "uploaded; run the same paths again (they deduplicate) in smaller batches.",
+      "Check before sending. 'pages push' validates every source before it sends anything but stops at the first "
+      + "problem. On a large import, validate the sources yourself first so you see every problem at once: run the "
+      + "package's validators over each file, or push one page at a time ('pages push <path>').",
+      "Navigation. A site can have several menus (header, footer): ask which is primary and list the rest. Rebuild it as nav.json after 'pages push', at most three levels deep with canonical UUID ids, 1000 items and 200-character titles (help nav); a label-only dropdown heading (a WordPress '#' link) is a GROUP_HEADER, and a child of an item you cannot map is listed, not promoted (page items carry the resourceId from the "
+      + "manifest; a custom link is an EXTERNAL_URL item; a category or tag item has no target, so list it).",
+      "Redirects. At most 2000 entries; never redirect to a page you did not push. Every imported page's old path (from its <link>) becomes a 301 to its new path, unless the two "
+      + "are the same. A category archive redirects to its folder when it became one. Query-string URLs (?p=12), "
+      + "feeds, tag archives, author archives and attachment pages cannot be redirect sources or have no "
+      + "destination: list them and ask the owner whether each is 410 or goes to an index. A source that a live page "
+      + "occupies is refused by the site.",
+      "Finish with the account: counts of pages by template, media staged, redirects written, then every unmapped "
+      + "item grouped by kind with examples, the questions only the owner can answer, and the verification results "
+      + "(redirects check, delivery check).",
+    ]),
+  }),
   delivery: Object.freeze({
     title: "Delivery verification",
     summary: "delivery check reads a completed deployment's target the way a visitor does and reports HTTP delivery, runtime compatibility and (optionally) browser behaviour as separate dimensions.",
@@ -542,8 +602,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "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.",
       "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 can be propagation "
-      + "delay; re-run redirects check before promoting. Requests are bounded to 90 seconds, eight at a time; "
+      + "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.",
       "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 "
@@ -594,10 +654,15 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Converting an engagement's CSV into this file is the agent's job. The CLI's contract is JSON, on "
       + "purpose: a real migration list needs judgement about which old URLs still deserve a destination and "
       + "which are simply gone.",
-      "Entries take effect on the next deploy, staging first. They are written to the edge's key-value store "
-      + "when the deploy syncs routing, and that store is eventually consistent, so a spot-check run "
-      + "immediately afterwards can briefly still see the previous map. Re-check before concluding an entry "
-      + "did not land.",
+      "Entries take effect on the next deploy, staging first. Each is a file inside that release, so it goes live "
+      + "exactly when the release does: staging with the staged release, production when it is promoted. There is "
+      + "no separate propagation delay; an entry a check does not see belongs to a release that is not being "
+      + "served yet.",
+      "A source cannot name a file the site generates: '/index.html' or any page's own 'index.html', '/404.html', "
+      + "'/sitemap.xml', '/robots.txt', '/favicon.ico', or a path under the sitemap or robots names. The platform "
+      + "already redirects every '…/index.html' address to its directory, so no entry is needed for one. A source "
+      + "that could not be stored as a file (a dot-prefixed segment, a reserved device name, an escaped percent "
+      + "sign) is refused too. 'validate' names the entry and the reason.",
     ]),
     example: Object.freeze({
       siteId: "<site-uuid>",
@@ -683,8 +748,10 @@ const WORKFLOW_REFERENCES = Object.freeze({
       `manifestVersion must be ${MANIFEST_VERSION}; fixture.contractVersion must be ${FIXTURE_CONTRACT_VERSION}.`,
       "siteId, every pageId and resourceId, every settings entityId, and every fixture.imageIds entry is a canonical "
       + "lowercase UUID. They are deterministic fixture identities, not identities from a live site.",
-      `Each pages[] entry binds one editable free-form source: pageId, resourceId, path, title, templateType `
-      + `${TEMPLATE_TYPE_FREE_FORM}, file, sourceFormat, and workspaceMode ${PAGE_WORKSPACE_MODE_EDITABLE}. `
+      `Each pages[] entry binds one editable page source: pageId, resourceId, path, title, templateType `
+      + `(${Object.values(PAGE_TEMPLATES).map((template) => template.wireType).join(", ")}; the source must be that template), file, `
+      + `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.",
       `file lives under '${PAGES_DIRECTORY}/' and ends in ${PAGE_SOURCE_EXTENSIONS.join(" or ")}; sourceFormat must be `
@@ -716,7 +783,7 @@ 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 free-form pages as ProseMirror sources and reports excluded metadata-only pages. "
+      "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, "
       + "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.",
@@ -1302,6 +1369,14 @@ const FREE_FORM_REFERENCE = Object.freeze({
             inheritedForTracked: true,
             defaultForNew: "",
           }),
+          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'.`,
+          }),
         ]),
       }),
       Object.freeze({
@@ -1387,17 +1462,20 @@ const FREE_FORM_REFERENCE = Object.freeze({
 });
 
 export function listPageTypeReferences() {
-  return PAGE_TYPES.map((type) => ({
-    type,
-    displayName: FREE_FORM_REFERENCE.displayName,
-    summary: FREE_FORM_REFERENCE.summary,
-    helpCommand: `${CLI_BINARY_NAME} help page ${type}`,
-  }));
+  return PAGE_TYPES.map((type) => {
+    const reference = type === "free-form" ? FREE_FORM_REFERENCE : getTypedPageReference(type);
+    return {
+      type,
+      displayName: reference.displayName,
+      summary: reference.summary,
+      helpCommand: `${CLI_BINARY_NAME} help page ${type}`,
+    };
+  });
 }
 
 export function getPageTypeReference(type) {
-  if (type !== "free-form") return undefined;
-  return { ...FREE_FORM_REFERENCE, components: listComponentTypeReferences() };
+  if (type === "free-form") return { ...FREE_FORM_REFERENCE, components: listComponentTypeReferences() };
+  return getTypedPageReference(type);
 }
 
 function schemaLabel(schema) {
@@ -1557,6 +1635,7 @@ export function formatReferenceResult(result) {
     }
     case "page": {
       const page = result.page;
+      if (page.type !== "free-form") return formatTypedPageReference(page);
       const markdownFormat = page.workspace.formats.find((format) => format.extension === ".md");
       const sourceRule = page.workspace.sourceRule;
       return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace:\n${

package/src/typed-page-reference.js

@@ -0,0 +1,339 @@
+import { CLI_BINARY_NAME } from "./constants.js";
+import {
+  frontMatterKeysFor,
+  PLACE_REVIEW_RATINGS,
+  TEMPLATE_ALBUM,
+  TEMPLATE_ARTICLE,
+  TEMPLATE_PLACE_REVIEW,
+  TEMPLATE_RECIPE,
+} from "./typed-pages.js";
+import { PAGES_DIRECTORY } from "./workspace.js";
+
+/**
+ * `help page <type>` for the four templates beyond free-form (TR00893).
+ *
+ * The front-matter fields are read from `typed-pages.js`, the module that
+ * enforces them, so the reference cannot list a field the parser refuses. The
+ * worked examples are checked against that same parser by the test suite.
+ */
+
+const FIELD_HELP = Object.freeze({
+  title: { type: "string", required: true, description: "The page title." },
+  path: {
+    type: "string",
+    required: true,
+    description:
+      "URL path, e.g. journal/first-post. Each segment starts with a letter or digit and uses only letters, digits, '.', '_' and '-'.",
+  },
+  description: {
+    type: "string",
+    required: false,
+    description: "Short description used in listings and search results.",
+  },
+  template: {
+    type: "string",
+    required: true,
+    description: "Selects the template. A page's template never changes after it is created.",
+  },
+  displayDate: {
+    type: "YYYY-MM-DD",
+    required: false,
+    description:
+      "The date the page is about or was originally published. Set it to preserve an imported date; omit it to use the "
+      + "first publication date. An empty value clears it.",
+  },
+  coverImage: {
+    type: "media reference",
+    required: false,
+    description:
+      "A file recorded by 'media upload', e.g. media/cover.jpg. The site requires the cover to be one of the page's own "
+      + "images, so the same file must also appear in the body, introduction, steps or album images "
+      + "(pages.cover_image_unused). Omit it for automatic selection; an empty value clears it.",
+  },
+  prepTimeMinutes: { type: "whole number", required: false, description: "Preparation time in minutes." },
+  cookTimeMinutes: { type: "whole number", required: false, description: "Cooking time in minutes." },
+  servings: { type: "whole number", required: false, description: "Number of servings." },
+  recipeCategory: { type: "string", required: false, description: "For example Dessert." },
+  recipeCuisine: { type: "string", required: false, description: "For example American." },
+  cookingMethod: { type: "string", required: false, description: "For example Baking." },
+  seamless: { type: "true | false", required: false, description: "Overrides the site's seamless-album setting." },
+  borderWidth: {
+    type: "whole number 0-20",
+    required: false,
+    description: "Overrides the site's album border width in pixels.",
+  },
+  placeId: {
+    type: "UUID",
+    required: true,
+    description:
+      "The Taproot place being reviewed. The site fills in its name, address and coordinates from this record; this "
+      + "CLI does not search for places.",
+  },
+  rating: {
+    type: Object.keys(PLACE_REVIEW_RATINGS).join(" | "),
+    required: true,
+    description: "The reviewer's verdict.",
+  },
+});
+
+const ARTICLE_EXAMPLE = `---
+title: How we found the trailhead
+path: journal/how-we-found-the-trailhead
+description: A short note about the first hike.
+template: article
+displayDate: 2023-06-18
+coverImage: media/trailhead.jpg
+---
+
+We parked at the end of the gravel road and walked the last mile.
+
+![The trailhead at dawn](media/trailhead.jpg)
+`;
+
+const RECIPE_EXAMPLE = `---
+title: Lemon bars
+path: recipes/lemon-bars
+template: recipe
+displayDate: 2022-11-04
+prepTimeMinutes: 15
+cookTimeMinutes: 35
+servings: 16
+recipeCategory: Dessert
+recipeCuisine: American
+cookingMethod: Baking
+---
+
+Tart, sweet, and easy to double.
+
+## Ingredients
+
+### Crust
+
+- 2 cups flour
+- 1/2 cup powdered sugar
+
+### Filling
+
+- 4 eggs
+- 1 1/2 cups sugar
+
+## Instructions
+
+1. Press the crust into a pan and bake for 20 minutes.
+2. Whisk the filling and pour it over the warm crust.
+
+   Bake until set.
+`;
+
+const ALBUM_EXAMPLE = `---
+title: Weekend at the lake
+path: albums/lake-weekend
+template: album
+displayDate: 2023-07-01
+seamless: true
+---
+
+Three days, one cabin.
+
+## Images
+
+![Sunrise over the dock](media/dock.jpg)
+![Canoes on the shore](media/canoes.jpg)
+`;
+
+const PLACE_REVIEW_EXAMPLE = `---
+title: Corner Cafe
+path: reviews/corner-cafe
+template: place-review
+placeId: 0198a3f2-7c4e-4a10-9b2d-3f6e5d4c3b2a
+rating: will-return
+---
+
+The espresso is excellent and the pastries sell out by ten.
+`;
+
+// The id `media upload` records for a file, shown here as a stand-in.
+const EXAMPLE_IMAGE_ID = "c1c1c1c1-c1c1-4c1c-8c1c-c1c1c1c1c1c1";
+
+const PARAGRAPH = (text) => ({ type: "doc", content: [{ type: "paragraph", content: [{ type: "text", text }] }] });
+
+function documentExample(template, extra, data) {
+  return { template, ...extra, data };
+}
+
+const TYPE_DETAILS = Object.freeze({
+  [TEMPLATE_ARTICLE]: {
+    displayName: "Article",
+    summary: "A dated post: a title, an optional cover image, and a rich-text body. The template for blog posts.",
+    body: "Everything after the front matter is the article body, in the same Markdown subset as a free-form page.",
+    markdownExample: ARTICLE_EXAMPLE,
+    documentExample: documentExample(
+      TEMPLATE_ARTICLE,
+      { displayDate: "2023-06-18", coverImageId: EXAMPLE_IMAGE_ID },
+      { body: PARAGRAPH("We parked at the end of the gravel road and walked the last mile.") },
+    ),
+    dataFields: ["body: ProseMirror document (required, not empty)"],
+  },
+  [TEMPLATE_RECIPE]: {
+    displayName: "Recipe",
+    summary: "Structured ingredients and steps with times, servings and category, published with recipe markup.",
+    body:
+      "Text before '## Ingredients' is the introduction (optional). '## Ingredients' holds '- ' bullets, optionally split "
+      + "by '### Group name' headings. '## Instructions' holds numbered or bulleted steps, optionally split by "
+      + "'### Section name' headings; indent a step's later paragraphs by two spaces. Those two headings are the only "
+      + "level-2 headings allowed, and both are required: text that does not fit is refused, never dropped. The "
+      + "introduction and each step take paragraphs, headings, lists, quotes, code, images, tables and components, but "
+      + "not sections or inline facts, which the site rejects there (pages.node_unsupported_for_template).",
+    markdownExample: RECIPE_EXAMPLE,
+    documentExample: documentExample(
+      TEMPLATE_RECIPE,
+      { displayDate: "2022-11-04" },
+      {
+        introductionBody: PARAGRAPH("Tart, sweet, and easy to double."),
+        ingredientGroups: [{
+          name: "Crust",
+          ingredients: [{ rawText: "2 cups flour", quantity: "", unit: "", name: "", parsed: false }],
+        }],
+        instructionSections: [{ name: "", stepBodies: [PARAGRAPH("Press the crust into a pan and bake.")] }],
+        prepTimeMinutes: 15,
+        cookTimeMinutes: 35,
+        servings: 16,
+        recipeCategory: "Dessert",
+        recipeCuisine: "American",
+        cookingMethod: "Baking",
+      },
+    ),
+    dataFields: [
+      "introductionBody: ProseMirror document (optional)",
+      "ingredientGroups: [{ name, ingredients: [{ rawText, quantity, unit, name, parsed }] }]; at least one ingredient",
+      "instructionSections: [{ name, stepBodies: [ProseMirror document] }]; at least one step",
+      "prepTimeMinutes, cookTimeMinutes, servings: whole numbers; recipeCategory, recipeCuisine, cookingMethod: strings",
+    ],
+    note:
+      "A Markdown source supplies each ingredient as text only, so it publishes as written. A .pm.json source may also "
+      + "carry quantity, unit and name with parsed: true.",
+  },
+  [TEMPLATE_ALBUM]: {
+    displayName: "Album",
+    summary: "A gallery of images with an optional introduction and per-album layout overrides.",
+    body:
+      "Text before '## Images' is the introduction (optional). '## Images' holds one '![caption](media/file.jpg)' line "
+      + "per image, in display order, each recorded by 'media upload'. It is the only level-2 heading allowed. The "
+      + "introduction takes paragraphs, headings, lists, quotes, code, images, tables and components, but not sections "
+      + "or inline facts (pages.node_unsupported_for_template).",
+    markdownExample: ALBUM_EXAMPLE,
+    documentExample: documentExample(
+      TEMPLATE_ALBUM,
+      { displayDate: "2023-07-01" },
+      {
+        introductionBody: PARAGRAPH("Three days, one cabin."),
+        images: [{
+          imageId: EXAMPLE_IMAGE_ID,
+          caption: "Sunrise over the dock",
+          width: 1600,
+          height: 900,
+        }],
+        seamless: true,
+      },
+    ),
+    dataFields: [
+      "introductionBody: ProseMirror document (optional)",
+      "images: [{ imageId, caption, width, height }]; at least one",
+      "seamless: true | false and borderWidth: 0-20 (optional; omitted inherits the site default)",
+    ],
+  },
+  [TEMPLATE_PLACE_REVIEW]: {
+    displayName: "Place review",
+    summary: "A review of a place with a three-step rating, listed on the site's places archive.",
+    body: "Everything after the front matter is the review body.",
+    markdownExample: PLACE_REVIEW_EXAMPLE,
+    documentExample: documentExample(
+      TEMPLATE_PLACE_REVIEW,
+      {},
+      {
+        placeId: "0198a3f2-7c4e-4a10-9b2d-3f6e5d4c3b2a",
+        rating: "will-return",
+        body: PARAGRAPH("The espresso is excellent and the pastries sell out by ten."),
+      },
+    ),
+    dataFields: [
+      "placeId: UUID of an existing Taproot place",
+      `rating: ${Object.keys(PLACE_REVIEW_RATINGS).join(" | ")}`,
+      "body: ProseMirror document (required, not empty)",
+    ],
+  },
+});
+
+export const TYPED_PAGE_TYPES = Object.freeze(Object.keys(TYPE_DETAILS));
+
+function typedReference(type) {
+  const details = TYPE_DETAILS[type];
+  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.",
+      formats: Object.freeze([
+        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.",
+          dataFields: Object.freeze(details.dataFields),
+        }),
+      ]),
+    }),
+    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." }),
+      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} approve, deploy --staging, deploy --production`,
+        result: "Stage, review and promote, as for any page.",
+      }),
+    ]),
+  });
+}
+
+const REFERENCES = Object.freeze(Object.fromEntries(TYPED_PAGE_TYPES.map((type) => [type, typedReference(type)])));
+
+/** The reference for one non-free-form template, or `undefined`. */
+export function getTypedPageReference(type) {
+  return Object.hasOwn(REFERENCES, type) ? REFERENCES[type] : undefined;
+}
+
+function formatField(field) {
+  return `  ${field.name.padEnd(18)} ${field.type}; ${field.required ? "required" : "optional"}; ${field.description}`;
+}
+
+/** The plain-text `help page <type>` rendering. */
+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${
+    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)
+  }\n\nWorkflow:\n${
+    page.workflow.map((step) => `  ${step.command}: ${step.result}`).join("\n")
+  }\n\nUse --json for the exact structure.\n`;
+}