@taprootio/site-authoring 0.20.0 → 0.22.0

package/src/redirects-contract.js

@@ -1,5 +1,20 @@
 import { SiteAuthoringError } from "./errors.js";
-import { RUNTIME_MIRROR_PATH_REASON, isRuntimeMirrorPath } from "./reserved-paths.js";
+import { RUNTIME_MIRROR_PATH_REASON } from "./reserved-paths.js";
+import {
+  isRequestSpelling,
+  normalizeRedirectPath,
+  redirectSourceRule,
+  resolvesAway,
+  RULE_REDIRECT_SOURCE_GENERATED_FILE,
+  RULE_REDIRECT_SOURCE_INDEX_HTML,
+  RULE_REDIRECT_SOURCE_INTEGRATION_DATA,
+  RULE_REDIRECT_SOURCE_INVALID,
+  RULE_REDIRECT_SOURCE_NOT_STORABLE,
+  RULE_REDIRECT_SOURCE_RUNTIME_MIRROR,
+  RULE_REDIRECT_SOURCE_SHARE_LINK,
+} from "./site-checks.js";
+
+export { normalizeRedirectPath };
 
 /**
  * The redirect map's workspace contract (TR00702).
@@ -64,64 +79,14 @@ const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F-\u009F]/u;
 const ENTRY_KEYS = new Set(["path", "kind", "target", "status", "origin"]);
 const SHA256 = /^[0-9a-f]{64}$/u;
 
-// An empty interior segment, or a dot or slash hidden behind percent-encoding.
-// '//' is also where a protocol-relative URL hides, which is why the leading
-// case is covered by this rule rather than by a separate prefix check.
-const RESOLVABLE_SPELLING = /\/\/|%2e|%2f/iu;
-
-// A spelling no browser would send as a pathname: anything outside printable
-// ASCII, one of the characters a URL parser escapes on sight, or a '%' that is
-// not an escape.
-// No `i` flag: under Unicode case folding it would let U+212A (KELVIN SIGN)
-// and U+017F (LONG S) through `[^!-~]`, which the site refuses.
-const UNSENDABLE_SPELLING = /[^!-~]|["<>`{}]|%(?![0-9a-fA-F]{2})/u;
-
-/**
- * Whether a path is already written the way a browser sends a pathname.
- *
- * The published-site edge keys on `url.pathname`, which the URL parser has
- * already percent-encoded, and its `normalizePathname` decodes nothing — while
- * every rule here compares the string as written. So '/old%20page -> /old page'
- * is two different strings to loop detection and one path to the edge, which
- * matches '/old%20page', resolves the target with `new URL` back to
- * '/old%20page', and serves a permanent self-loop. A source written with a
- * literal space or a non-ASCII character is the same mismatch the other way,
- * stored under a key no request pathname ever matches.
- *
- * Refused rather than encoded here. URL escaping is not reproducibly canonical
- * between the API's .NET and the edge's WHATWG parser, so a spelling this pass
- * encoded would still not be the one the Worker computes and the layers would
- * go on comparing different strings. Write what a browser sends and every layer
- * compares it unchanged — and the byte bounds then measure that same spelling.
- */
-function isRequestSpelling(value) {
-  return !UNSENDABLE_SPELLING.test(value);
-}
-
-/**
- * Whether a path names one thing to this pass and another wherever it is
- * resolved.
- *
- * Every rule here compares the string as written, and nothing downstream does:
- * the generator resolves a source with path.resolve, so '/x/../visit' writes
- * over the page rendered at '/visit', and the published-site edge resolves a
- * target with `new URL`, so '/a -> /x/../a' is the self-loop that loop
- * detection just passed. Percent-encoded dots and slashes are the same trick
- * spelled so a segment scan cannot see it, so they are refused wherever they
- * appear rather than decoded and re-examined.
- */
-function resolvesAway(value) {
-  if (RESOLVABLE_SPELLING.test(value)) return true;
-  return value.split("/").some((segment) => segment === "." || segment === "..");
-}
 
 /** Whether the value is a redirect-map revision as the server mints one. */
 export function isRedirectMapRevision(value) {
   return typeof value === "string" && SHA256.test(value);
 }
 
-function entryError(code, message, field) {
-  return new SiteAuthoringError(code, `${field}: ${message}`, { field });
+function entryError(code, message, field, rule) {
+  return new SiteAuthoringError(code, `${field}: ${message}`, { field, rule });
 }
 
 function isPlainObject(value) {
@@ -133,93 +98,32 @@ function utf8Length(value) {
 }
 
 /**
- * Normalizes a source path exactly as the published-site Worker's
- * `normalizePathname` does: require the leading slash, strip trailing slashes,
- * change nothing else. A `.html` suffix survives, which is the whole point —
- * `/faqs.html` is a real legacy URL and has to be representable. A spelling
- * some other layer would resolve away is refused rather than repaired (see
- * `resolvesAway`), and so is one no browser would send as a pathname (see
- * `isRequestSpelling`, which subsumes the control-character refusal).
+ * Why a source rule refuses a path, in the words the CLI shows. The rule ids are
+ * the site checks' (shared/site-check-rules.json); the decisions themselves are
+ * made by `redirectSourceRule` in the shared source, which the API's C#
+ * implementation also passes the same corpus for.
  */
-export function normalizeRedirectPath(value) {
-  if (typeof value !== "string") return undefined;
-  const candidate = value.trim();
-  if (
-    candidate === ""
-    || /[?#\\]/u.test(candidate)
-    || !isRequestSpelling(candidate)
-    || resolvesAway(candidate)
-  ) {
-    return undefined;
-  }
-  const withSlash = candidate.startsWith("/") ? candidate : `/${candidate}`;
-  const trimmed = withSlash.replace(/\/+$/u, "");
-  return trimmed === "" ? "/" : trimmed;
-}
-
-// The root segment the published output reserves for integration data; the release
-// inventory leaves everything under it out.
-const RESERVED_INTEGRATION_DATA_SEGMENT = "integrations";
-
-// Root-level files the site generates. A redirect is a marker file inside the
-// published site (TR00968), so a source that names one has nowhere to live.
-const GENERATED_ROOT_FILES = Object.freeze(["404.html", "sitemap.xml", "robots.txt", "favicon.ico"]);
-// The longest decoded path segment a marker file name may have; the API rule and the
-// generator use the same 200 bytes.
-const MAX_MARKER_SEGMENT_BYTES = 200;
-const WINDOWS_DEVICE_STEMS = new Set(["con", "prn", "aux", "nul"]);
-
-function isWindowsDeviceSegment(segment) {
-  const stem = segment.split(".", 1)[0].toLowerCase();
-  return WINDOWS_DEVICE_STEMS.has(stem) || /^(?:com|lpt)[1-9]$/u.test(stem);
-}
+const SOURCE_RULE_REASONS = Object.freeze({
+  [RULE_REDIRECT_SOURCE_INDEX_HTML]: () =>
+    "the platform already redirects every '…/index.html' address to its directory, so it cannot also be "
+    + "a redirect source, and the page or home file there is generated.",
+  [RULE_REDIRECT_SOURCE_INTEGRATION_DATA]: (first) =>
+    `'/${first}' is reserved for integration data, so nothing under it can be a redirect source.`,
+  [RULE_REDIRECT_SOURCE_SHARE_LINK]: () =>
+    "'/s/' is reserved for share links, so nothing under it can be a redirect source.",
+  [RULE_REDIRECT_SOURCE_RUNTIME_MIRROR]: () => RUNTIME_MIRROR_PATH_REASON,
+  [RULE_REDIRECT_SOURCE_GENERATED_FILE]: (first) =>
+    `'/${first}' is a file the site generates, so neither it nor anything under it can be a redirect source.`,
+  [RULE_REDIRECT_SOURCE_NOT_STORABLE]: () =>
+    "a redirect is stored as a file in the published site, and this path cannot be one (no dot-prefixed "
+    + "segments, reserved device names, '..', escaped percent signs, or segments over 200 bytes).",
+});
 
-/**
- * Why a normalized source path cannot be a redirect, or undefined when it can.
- * A mirror of `SiteRedirectMapContract.SourceRefusalReason` on the server (the
- * API is the authority; both run the same test vectors): `…/index.html` is
- * answered by the platform for every page, the generator writes the files
- * named above, and the marker is stored under the decoded spelling, so a path
- * that cannot be stored once decoded (an escaped percent sign, a dot-prefixed
- * segment, a reserved device name) is refused. The site root is left to the
- * occupancy rule.
- */
-export function redirectSourceRefusalReason(path) {
-  if (path === "/") return undefined;
-  // Every rule reads the decoded spelling: it is the name the marker is stored
-  // under, and the name the generator's own files use (`/%69ndex.html` is
-  // `/index.html`).
-  let decoded;
-  try {
-    decoded = path.replace(/^\/+|\/+$/gu, "").split("/").map(decodeURIComponent).join("/");
-  } catch {
-    return "it holds a percent escape that does not decode.";
-  }
-  const segments = decoded.split("/");
-  const first = segments[0].toLowerCase();
-  if (segments.some((segment) => segment.toLowerCase() === "index.html")) {
-    return "the platform already redirects every '…/index.html' address to its directory, so it cannot also be "
-      + "a redirect source, and the page or home file there is generated.";
-  }
-  if (first === RESERVED_INTEGRATION_DATA_SEGMENT) {
-    return `'/${segments[0]}' is reserved for integration data, so nothing under it can be a redirect source.`;
-  }
-  if (isRuntimeMirrorPath(decoded)) return RUNTIME_MIRROR_PATH_REASON;
-  if (GENERATED_ROOT_FILES.includes(first)) {
-    return `'/${segments[0]}' is a file the site generates, so neither it nor anything under it can be a redirect source.`;
-  }
-  if (
-    decoded.includes("..")
-    || decoded !== decoded.normalize("NFC")
-    || segments.some((segment) =>
-      segment === "" || segment.startsWith(".") || /[%\\?#\u0000-\u001F\u007F-\u009F]/u.test(segment)
-      || isWindowsDeviceSegment(segment) || new TextEncoder().encode(segment).length > MAX_MARKER_SEGMENT_BYTES
-    )
-  ) {
-    return "a redirect is stored as a file in the published site, and this path cannot be one (no dot-prefixed "
-      + "segments, reserved device names, '..', escaped percent signs, or segments over 200 bytes).";
-  }
-  return undefined;
+/** The refusal for a normalized source: its site-check rule id and the reason, or undefined when it can be a redirect. */
+export function redirectSourceRefusal(path) {
+  const refusal = redirectSourceRule(path);
+  if (refusal === undefined) return undefined;
+  return { ruleId: refusal.ruleId, reason: SOURCE_RULE_REASONS[refusal.ruleId](refusal.detail) };
 }
 
 function looksAbsolute(value) {
@@ -281,6 +185,7 @@ function validateEntry(value, index, seen) {
         + "or '..' segment, no empty segment, and no percent-encoded dot or slash. Write the percent-encoded "
         + "spelling a browser sends (/caf%C3%A9, /old%20page), never the raw one.",
       `${field}.path`,
+      RULE_REDIRECT_SOURCE_INVALID,
     );
   }
   // The site root is not refused here. A home page rename records an entry at
@@ -303,9 +208,14 @@ function validateEntry(value, index, seen) {
       `${field}.path`,
     );
   }
-  const sourceRefusal = redirectSourceRefusalReason(path);
+  const sourceRefusal = redirectSourceRefusal(path);
   if (sourceRefusal !== undefined) {
-    throw entryError("redirects.path_unpublishable", `'${path}': ${sourceRefusal}`, `${field}.path`);
+    throw entryError(
+      "redirects.path_unpublishable",
+      `'${path}': ${sourceRefusal.reason}`,
+      `${field}.path`,
+      sourceRefusal.ruleId,
+    );
   }
   // The marker is stored under the decoded spelling, so `/a%41` and `/aA` are one
   // file, and the second would silently replace the first.

package/src/reference-help.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 
-import { CLI_BINARY_NAME } from "./constants.js";
+import { CLI_BINARY_NAME, LIMITS } from "./constants.js";
 import {
   canonicalizeComponentData,
   COMPONENT_TYPES,
@@ -64,9 +64,11 @@ import {
   REDIRECTS_FILE_NAME,
 } from "./redirects-contract.js";
 import { SETTINGS_GROUPS } from "./settings-catalog.js";
+import { getSettingsReference } from "./setting-reference.js";
 import {
   formatTypedPageReference,
   getTypedPageReference,
+  LEGAL_PLATFORM_LINK_GUIDANCE,
   MARKDOWN_PAGE_TYPES,
   TYPED_PAGE_TYPES,
 } from "./typed-page-reference.js";
@@ -84,9 +86,9 @@ import {
   SYSTEM_PAGE_NOT_FOUND_PATH,
 } from "./workspace.js";
 
-export { getAppearanceReference, getFooterReference, getThemeReference };
+export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 37;
+export const REFERENCE_VERSION = 38;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -387,7 +389,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: free-form, article, recipe, album, place-review." }),
+  Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List page types: free-form, article, recipe, album, place-review, generated, and the read-only legal page." }),
   Object.freeze({
     name: "page",
     usage: `${CLI_BINARY_NAME} help page <page-type>`,
@@ -450,6 +452,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help appearance`,
     summary: "Map site presentation decisions to theme-push workspace fields.",
   }),
+  Object.freeze({
+    name: "settings",
+    usage: `${CLI_BINARY_NAME} help settings`,
+    summary: "Map every pulled site setting to its app control, say what it does and where it renders, and which verb writes it.",
+  }),
   Object.freeze({
     name: "footer",
     usage: `${CLI_BINARY_NAME} help footer`,
@@ -501,7 +508,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "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 "
+      "Content. Convert the HTML to the Markdown subset. Keep body headings from h2 to h4 (deeper levels are refused, so make h5 and h6 an h4). The h1 depends on the template: an article or place review prints its title as the h1, so its body starts at h2 (a recipe and an album print their titles too; their fixed level-2 headings are set out below); a free-form page prints no title, so open its Markdown with a '# ' line holding the page title (the first level-1 heading becomes the h1; see help page free-form). 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 "
@@ -604,7 +611,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "contexts and intents paired across schemes. Set appearance scalars (default scheme, header, logos, favicon) "
       + "in the appearance files: help appearance.",
       "Prepare media locally: PNG, JPEG, GIF and WebP raster files only, addressed relative to the workspace root. Make "
-      + "the variants yourself with any image tool (a transparent logo, a @2x copy, a square favicon); there is no "
+      + "the variants yourself with any image tool (a transparent logo at the highest resolution you have, a square favicon); there is no "
       + "recolor, crop or SVG upload command. Upload each with media upload, then assign lightLogoId and darkLogoId "
       + "(and brand.faviconId) from the image ids .taproot-site-media.json records for those files, so each scheme carries the artwork that reads on its header.",
       `Validate offline: ${CLI_BINARY_NAME} validate checks the whole workspace at once — the complete pair, the `
@@ -623,10 +630,12 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "(theme.concurrent_modification) and nothing is written; keep copies of the edited files, pull, re-apply, "
       + "and push again. A lost response is safe to retry — the site answers applied=false when it already holds "
       + "the change set. footer push owns footer prose, links and imagery.",
-      `Review on staging: ${CLI_BINARY_NAME} deploy --staging stages the presentation and returns a single-use review handoff `
-      + "in stagingPreview.url (on a managed Docs site too). Open it once, then use the site's theme toggle to check "
-      + "both schemes: text, headings, links and hover, actions and focus, the header logos, the favicon. When no "
-      + "handoff could be minted, stagingPreview.reason says why and staging review mints another. A page draft is "
+      `Review on staging: ${CLI_BINARY_NAME} deploy --staging stages the presentation; it reports no review URL by default `
+      + `because the URL is a live credential, so run ${CLI_BINARY_NAME} staging review (or add --handoff to deploy) for `
+      + "a single-use handoff in stagingPreview.url (on a managed Docs site too). Open it once, then use the site's "
+      + "theme toggle to check both schemes: text, headings, links and hover, actions and focus, the header logos, the "
+      + "favicon. When a requested handoff could not be minted, stagingPreview.reason says why and staging review mints "
+      + "another (add --path <page> to open it on the page under review). A page draft is "
       + "not needed to review a presentation change; preview page renders one persisted draft and is a different tool.",
       `Promote only after review: ${CLI_BINARY_NAME} deploy --production promotes the completed staging deployment. `
       + "Never use production to discover what staging should have shown.",
@@ -650,7 +659,10 @@ const WORKFLOW_REFERENCES = Object.freeze({
     summary: "nav push replaces the complete tree in nav.json; item IDs are author-minted canonical lowercase UUIDs.",
     usage: `${CLI_BINARY_NAME} nav push`,
     details: Object.freeze([
-      "nav.json is { siteId, navItems }, not a bare array.",
+      "nav.json is { siteId, navItems }, not a bare array. Defaults are left out: an item has no resourceId or "
+      + "externalUrl unless its kind uses one, and no children when it has none. pull and nav push both write that "
+      + "form (nav push rewrites the file after it saves), and either form is accepted on the way in, so a pull after "
+      + "a push shows no change you did not make.",
       "kind is NAV_ITEM_KIND_PAGE, NAV_ITEM_KIND_EXTERNAL_URL, or NAV_ITEM_KIND_GROUP_HEADER.",
       "PAGE uses resourceId from .taproot-site-manifest.json, never pageId or path.",
       "EXTERNAL_URL uses externalUrl; GROUP_HEADER has no target; every kind may carry children.",
@@ -664,7 +676,6 @@ const WORKFLOW_REFERENCES = Object.freeze({
         kind: "NAV_ITEM_KIND_PAGE",
         title: "Classes",
         resourceId: "<resourceId-from-manifest>",
-        children: Object.freeze([]),
       })]),
     }),
   }),
@@ -688,9 +699,12 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "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 (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.",
+      "redirects check and deploy --staging report no review URL unless you pass --handoff; the check "
+      + "authenticates with its own handoff either way. With --handoff, 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. Without it, stagingPreview.reason is staging.handoff_not_requested and "
+      + "'staging review' mints one. The staging cookie lasts five minutes and remains subject to current "
+      + "site/host/credential permission.",
       `${REDIRECTS_FILE_NAME} is { siteId, revision, entries }, not a bare array. 'redirects pull' writes it and `
       + "records the revision in .taproot-site-manifest.json; 'pull' writes it too.",
       "An entry is { path, kind, target, status }. kind is 'redirect' (the default) or 'gone'; a gone entry "
@@ -738,9 +752,10 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "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. 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.",
+      + "exactly when the release does: staging with the staged release, production when it is promoted. The edge "
+      + `can keep serving the previous release for up to ${LIMITS.stagingPropagationCeilingSeconds} seconds after a deployment completes, so an entry a `
+      + "check does not see may belong to a release the edge has not switched to yet; deploy --staging waits for "
+      + "staging to serve the new release and reports stagingServed.",
       "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. Nothing under "
       + "'/taproot/<version>/' (for example '/taproot/5.0.62/manifest.json') can be a source either: the platform "
@@ -790,8 +805,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "Delivery also requires Taproot's rollout and email provider readiness; opt-in enables neither, and earlier submissions are not backfilled.",
       `definition is { fields, contact_field?, submit_label?, after_submit? } (contact_field only with several email fields). Each field is { id, type, label, hint?, ...constraints }; the closed `
       + `field types are ${FIELD_TYPES.join(", ")}. hint is optional helper text of up to ${MAX_HINT_LENGTH} `
-      + "characters, drawn under the field on the published form; it is the only author-defined text printed there, so a required "
-      + "field is not marked 'Required' and a visitor learns it from the error on submit. "
+      + "characters, drawn under the field on the published form. The published form marks a required field itself: its label "
+      + "ends with ' *' and a '* Required' legend sits above the fields, so do not write 'required' into a label or hint; the "
+      + "stored label stays exactly as written. "
       + `At most ${MAX_FIELDS} fields and ${MAX_SUBMISSION_BYTES} bytes `
       + "per submission. There are no author-supplied regular expressions: use 'format' from its closed list. "
       + "The exact constraints per type are in shared/field-schema.json, which 'forms validate' enforces by "
@@ -824,7 +840,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "a deploy whose release does not publish that page is refused, naming the form and the page. The path in "
       + "each release is the one the page has in that release, so the published form never asks the site where "
       + "to go. The page must be one you created, the home page included: a generated page (folder, tag or "
-      + "archive index), the 404 page, a legal page, a profile home and an integration-managed page are refused as forms.page_not_allowed. The button text and the confirmation belong to the form, not to the page that places it: "
+      + "archive index), the 404 page, a legal page (help page legal), a profile home and an integration-managed page are refused as forms.page_not_allowed. The button text and the confirmation belong to the form, not to the page that places it: "
       + "the 'form' component takes only formKey.",
       "A form's contact address is the value of one email field, stored with each submission. That is what lets the "
       + "owner find and delete every row for a visitor who asks. With exactly one email field, that field is the "
@@ -881,9 +897,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
     usage: `${CLI_BINARY_NAME} media upload [path...]`,
     details: Object.freeze([
       "Paths are relative to the configured workspace root, not the shell's current directory.",
-      "PNG, JPEG, GIF, and WebP are accepted; retina names such as logo@2x.png and logo@3x.png are supported.",
+      "PNG, JPEG, GIF, and WebP are accepted. Each file uploads as its own image: a name such as logo@2x.png is only a filename, nothing pairs it with logo.png, and the platform generates the display sizes from the one file you assign (see help appearance for logos).",
       "For header logos prefer genuine transparent PNG/WebP, check contrast in both themes, and include a simplified square favicon. See help appearance for branding guidance.",
-      "Prepare variants locally with any image tool before uploading: a transparent logo, its @2x copy, a scheme-specific dark logo when one asset does not read on both headers, and a square favicon. The CLI uploads what you give it; it has no recolor, crop, or SVG upload command.",
+      "Prepare variants locally with any image tool before uploading: a transparent logo at the highest resolution you have (never a 1x and a 2x pair: assign one file and the platform generates the sizes; keep it under the 32 MiB upload limit), a scheme-specific dark logo when one asset does not read on both headers, and a square favicon. The CLI uploads what you give it; it has no recolor, crop, or SVG upload command.",
       "Assign both schemes after uploading: lightLogoId and darkLogoId in settings/taproot-styles.json and brand.faviconId in settings/brand.json take the image ids .taproot-site-media.json records for those files; theme push writes them. See help walkthrough for the full design pass.",
       "Each result item reports file, imageId, deduplicated, width, height and processingState; the delivery URLs (src, urls) are in .taproot-site-media.json, not the result, so an upload of any size reports within its bound. media.total and videos.total count every file, and media.itemsTruncated or videos.itemsTruncated says that list stopped short.",
       "MP4, MOV, and WebM files are uploaded as videos (up to 250 MB each; the site's licence sets the cap, and the container is read from the file's bytes, not its name). The CLI reads each file with mediabunny. A file that is H.264 and AAC but not already an MP4 with its index first is rewritten as one without re-encoding; anything else is sent as it is and judged by the server. When the server refuses a file, its one-line message is printed as media.video_refused. A video is ready to play as soon as the upload is confirmed. The CLI sets no poster, because Node has no video decoder: the Videos page picks one automatically for a video uploaded there, and lets the owner choose another frame, so set a CLI-uploaded video's poster there, with its title and caption. The command reports videos.items: { file, videoId, title, caption, fileName, contentType, byteLength, deduplicated, durationMilliseconds, component }, where component.markdown is the component:video fence and component.block the componentBlock node that place it. Needs the site's licence to include video.",
@@ -891,8 +907,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "In Markdown, name an uploaded image by its path (such as media/photo.webp) wherever an image goes: body images, coverImage, album images, component image fields and section images. pages push resolves each path through .taproot-site-media.json, which also keeps the src/urls delivery fields a .pm.json image record carries.",
     ]),
     example: Object.freeze({
-      command: `${CLI_BINARY_NAME} media upload media/logo@2x.png`,
-      markdownImage: "media/logo@2x.png",
+      command: `${CLI_BINARY_NAME} media upload media/logo.png`,
+      markdownImage: "media/logo.png",
       pmJsonImageRecord: Object.freeze({
         imageId: "<image-uuid>",
         src: "<preferred-delivery-url>",
@@ -913,11 +929,15 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "selected page's content until a newer matching preview is ready, the content changes, or the operator "
       + "explicitly supplies --allow-failed-preview. Pending retries do not clear a known failure; previews "
       + "remain optional and old snapshots without content identity do not block deployment.",
-      "deploy --staging and redirects check return a separate fresh single-use staging handoff in "
-      + "stagingPreview.url, after authenticating headless redirect checks. Handoffs never go to GITHUB_OUTPUT.",
-      "On a managed Docs site deploy --staging stages settings only and still returns stagingPreview.url: open it "
-      + "once, then use the site's theme toggle to review both schemes; no page draft is needed to preview a "
-      + "presentation change. When no handoff can be minted the result carries stagingPreview.reason "
+      "deploy --staging and redirects check report no review URL by default, because it is a live single-use "
+      + "credential and their JSON is often saved to logs (stagingPreview.reason staging.handoff_not_requested). Run "
+      + "staging review for one, or pass --handoff to get a fresh single-use handoff in stagingPreview.url, minted "
+      + "after the headless redirect checks. staging review --path <page> (and --review-path <page> beside --handoff) "
+      + "opens the review on that page instead of the home page. Handoffs never go to GITHUB_OUTPUT.",
+      "On a managed Docs site deploy --staging stages settings only: run staging review (or deploy --staging "
+      + "--handoff) and open the URL once, then use the site's theme toggle to review both schemes; no page draft is "
+      + "needed to preview a presentation change. When a requested handoff can't be minted the result carries "
+      + "stagingPreview.reason "
       + "(staging.host_unavailable, staging.authority_denied, staging.surface_refused, or staging.handoff_unavailable) "
       + "and a recovery step; run staging review to mint another (it works on every surface). Never verify a theme "
       + "on production instead.",
@@ -1514,7 +1534,8 @@ const BACKGROUND_REFERENCE = backgroundReference();
 const FREE_FORM_REFERENCE = Object.freeze({
   type: "free-form",
   displayName: "Free-form page",
-  summary: "A page whose body is authored as validated ProseMirror, directly or through the supported Markdown subset.",
+  summary:
+    "A page whose body is authored as validated ProseMirror, directly or through the supported Markdown subset. It renders no automatic heading: open the body with a '# ' title line.",
   workspace: Object.freeze({
     directory: "pages/",
     sourceRule: Object.freeze({
@@ -1674,6 +1695,27 @@ const FREE_FORM_REFERENCE = Object.freeze({
         `Any other rel token, opener included, is refused (${CONTENT_ERROR_CODES.linkRel}); so is another target `
         + `(${CONTENT_ERROR_CODES.linkTarget}). The editor's old default, "noopener noreferrer nofollow", reads as no choice.`,
     }),
+    // TR01220: a free-form page prints no title, so its first level-1 heading is the h1.
+    headings: Object.freeze({
+      rule:
+        "A free-form page renders no automatic heading: its title is not printed on the page. "
+        + "The first level-1 heading in the body becomes the page's h1, so open the Markdown with '# Page title'. A "
+        + "structured page (article, recipe, album, place review) prints its title as the h1, so its body starts at '## '.",
+      claimedFirst:
+        "A hero-section with a title claims the h1, and so does an image-banner with overlay text that opens the page; "
+        + "a '# ' heading after either is then not a second h1. A titled hero-section renders its own h1 wherever it sits, so a '# ' line before one gives the page two h1s: use one or the other. Without a hero or banner, write the '# ' heading yourself.",
+      laterHeadings:
+        "Any later '# ' heading renders as an h2, like the other top-level sections, never as a second h1, "
+        + "and the other headings are renumbered so none skips a level.",
+      depth: `The Markdown subset accepts levels 1 to 4; a deeper heading is refused (${CONTENT_ERROR_CODES.headingDepth}).`,
+      example: "# Visit the studio\n\nWe are open every day.\n\n## Hours\n\nMonday to Friday, 6 AM to 7:30 PM.",
+    }),
+    // TR01224: the default for a policy written as a free-form page.
+    legalAndPrivacyPages: Object.freeze({
+      ...LEGAL_PLATFORM_LINK_GUIDANCE,
+      choosing:
+        `A policy that needs a version and an effective date is a legal page, which the CLI cannot author: see '${CLI_BINARY_NAME} help page legal'.`,
+    }),
     componentNode: Object.freeze({
       type: "componentBlock",
       attrs: Object.freeze({
@@ -1889,7 +1931,7 @@ export function formatReferenceResult(result) {
         result.topics.map((topic) => `  ${topic.usage.padEnd(48)} ${topic.summary}`).join("\n")
       }\n\nAdd --json for stable machine-readable output.\n`;
     case "page-types":
-      return `Authorable page types:\n${
+      return `Page types:\n${
         result.pageTypes.map((page) =>
           `  ${page.type.padEnd(16)} ${page.summary}\n${" ".repeat(19)}Help: ${page.helpCommand}`
         ).join("\n")
@@ -1933,7 +1975,9 @@ export function formatReferenceResult(result) {
         page.document.marks.join(", ")
       }\n\nLinks:\n  markdown              ${page.document.links.markdown}\n  rel                   ${
         page.document.links.rel.join(", ")
-      }\n  default               ${page.document.links.default}\n  in Markdown           ${page.document.links.markdownRule}\n  in .pm.json           ${page.document.links.pmJson}\n  refusals              ${page.document.links.refusals}\n\nTop-level section container:\n${page.sections.example}\n\nSection attributes:\n${
+      }\n  default               ${page.document.links.default}\n  in Markdown           ${page.document.links.markdownRule}\n  in .pm.json           ${page.document.links.pmJson}\n  refusals              ${page.document.links.refusals}\n\nHeadings and the h1:\n  rule                  ${page.document.headings.rule}\n  banner and hero       ${page.document.headings.claimedFirst}\n  later headings        ${page.document.headings.laterHeadings}\n  depth                 ${page.document.headings.depth}\n  example\n${
+        page.document.headings.example.split("\n").map((line) => `    ${line}`).join("\n")
+      }\n\nLegal and privacy pages:\n  linking Taproot       ${page.document.legalAndPrivacyPages.rule}\n  example               ${page.document.legalAndPrivacyPages.example}\n  versioned policies    ${page.document.legalAndPrivacyPages.choosing}\n\nTop-level section container:\n${page.sections.example}\n\nSection attributes:\n${
         page.document.sectionNode.attrs.map(formatSectionAttr).join("\n")
       }\n\nSection photo background (closed object):\n${
         page.sections.background.fields.map((field) => formatRegistryField(field)).join("\n")

package/src/reserved-paths.js

@@ -5,17 +5,11 @@
  * `/taproot/<semver>/...` (TR01144), and Cloudflare answers a matching request
  * before the Worker runs, so a page or redirect authored there could never be
  * reached. This is the one place the package owns that prefix; page push and
- * the redirect map both ask here. The API is the authority and mirrors the rule
- * in `PublishedOutputPaths.IsRuntimeMirrorPath`; both are pinned by the same
- * test vectors.
+ * the redirect map both ask here. The API is the authority
+ * (`PublishedOutputPaths.IsRuntimeMirrorPath`); both pass the site-check corpus.
  */
-const RUNTIME_MIRROR_PATH =
-  /^taproot\/[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\/|$)/iu;
-
-/** Whether a site-relative path (no leading slash) is `taproot/<semver>` or under it. */
-export function isRuntimeMirrorPath(path) {
-  return RUNTIME_MIRROR_PATH.test(path);
-}
+// The rule itself lives in the shared site-check source, which the redirect source rules also read.
+export { isRuntimeMirrorPath } from "./site-checks.js";
 
 export const RUNTIME_MIRROR_PATH_REASON =
   "'/taproot/<version>/' is reserved for the published-site runtime, which the platform answers before any page "