@taprootio/site-authoring 0.20.0 → 0.22.0

package/src/staging-served.js

@@ -0,0 +1,320 @@
+import {
+  DEPLOYMENT_ENVIRONMENT_STAGING,
+  DEPLOYMENT_PENDING_STATUSES,
+  DEPLOYMENT_STATUS_COMPLETED,
+  DEPLOYMENT_STATUS_FAILED,
+  listDeployments,
+  mintStagingPreviewHandoff,
+  poll,
+} from "./api.js";
+import { LIMITS } from "./constants.js";
+import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
+import { authorizeStagingHandoff, fetchStagingPage } from "./staging-check.js";
+import { ApiError } from "./transport.js";
+
+/**
+ * Which release the staging host serves right now (TR01236).
+ *
+ * A staging deployment reports completed once the platform has asked Cloudflare
+ * to write the host's route. The edge then needs up to about two minutes to
+ * serve it: the route propagates through Workers KV, and the Worker keeps its
+ * own KV read cache and per-isolate cache on top. A cache-busting query cannot
+ * help, because the release comes from the route entry and not the URL. The
+ * Worker stamps the release it served into every staged page, so the CLI reads
+ * that stamp and waits until it changes, instead of letting a reviewer open the
+ * previous version.
+ *
+ * The CLI cannot learn the new deployment's release id (the public deployment
+ * record does not carry a Standard site's), so it compares against what staging
+ * served before the deployment was sent. That comparison is only sound when the
+ * edge had settled on the previous release, which the caller checks.
+ */
+
+const IDENTITY_ATTRIBUTE = /\sdata-review-identity="([^"]{1,200})"/u;
+// The read before the deploy is bounded so a slow host cannot hold up sending it.
+const BEFORE_READ_MILLISECONDS = 15_000;
+// The deployments listing that tells whether the previous deployment has settled has its own budget.
+const PREVIOUS_DEPLOYMENT_MILLISECONDS = 10_000;
+
+/** The release a staged HTML document says it came from, or null when it names none. */
+export function parseServedStagingRelease(html) {
+  const attribute = IDENTITY_ATTRIBUTE.exec(html)?.[1];
+  if (attribute === undefined) return null;
+  try {
+    const identity = JSON.parse(attribute.replaceAll(""", "\""));
+    if (Array.isArray(identity) && identity.length === 2 && identity[0] === "staging" && isCanonicalUuid(identity[1])) {
+      return identity[1];
+    }
+  } catch {
+    // An unreadable stamp is the same as no stamp.
+  }
+  return null;
+}
+
+/**
+ * The release a staged response names, reading at most `maximumBytes` of its body and
+ * stopping at the first stamp. A body past the bound is cut, which loses the stamp rather
+ * than memory.
+ */
+export async function readServedStagingRelease(response, maximumBytes = LIMITS.stagingServedPageBytes) {
+  return parseServedStagingRelease(await readBoundedText(response, maximumBytes));
+}
+
+async function readBoundedText(response, maximumBytes) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  let bytes = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      text += decoder.decode(value, { stream: true });
+      if (bytes >= maximumBytes || IDENTITY_ATTRIBUTE.test(text)) break;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  return text;
+}
+
+// Every network step of a read ends by the read's deadline, not only the API call.
+function deadlineSignal(client, now, deadline) {
+  return deadline === undefined ? undefined : client.timeoutSignal(Math.max(1, deadline - now()));
+}
+
+async function openSession(client, siteId, now, deadline) {
+  const handoff = await mintStagingPreviewHandoff(client, siteId, { now, deadline });
+  const cookie = await authorizeStagingHandoff(client, handoff, deadlineSignal(client, now, deadline));
+  return { cookie, origin: new URL(handoff.stagingUrl).origin };
+}
+
+/**
+ * One read of the staging host's served release, inside `deadline`.
+ *
+ * Returns `{ kind: "release", releaseId }` when the host served a staged page,
+ * `{ kind: "none" }` when it has no staged release to show yet (the site's
+ * first staging deployment has no host until it completes, or the host answered
+ * with a page that carries no stamp), and `{ kind: "unknown" }` when the read
+ * itself failed. A failed read never says which release is served.
+ */
+export async function observeStagingRelease(client, siteId, now, session, deadline) {
+  try {
+    const open = session.current ?? await openSession(client, siteId, now, deadline);
+    session.current = open;
+    const response = await fetchStagingPage(
+      client,
+      `${open.origin}/`,
+      open.cookie,
+      deadlineSignal(client, now, deadline),
+    );
+    if (response.status !== 200 && response.status !== 404) {
+      await response.body?.cancel().catch(() => {});
+      // A redirect or refusal means the gate did not let the read through, not that nothing is served.
+      return { kind: "unknown" };
+    }
+    const releaseId = await readServedStagingRelease(response);
+    return releaseId === null ? { kind: "none" } : { kind: "release", releaseId };
+  } catch (error) {
+    if (client.signal?.aborted) throw error;
+    // The first staging deployment has no acknowledged host to mint a handoff for.
+    if (error instanceof ApiError && error.hasField("Host")) return { kind: "none" };
+    return { kind: "unknown" };
+  }
+}
+
+/**
+ * Whether the edge has settled on the newest completed staging deployment, and which
+ * deployment that is: state "none" (the site has never completed one, so any release
+ * staging serves is new), "recent" (it completed inside the propagation ceiling, so
+ * the edge may still be moving to it), "settled", or "unknown" (the listing could not
+ * be read, or its answer cannot be trusted). Only "none" and "settled" allow a
+ * comparison. `id` is that newest completed deployment, or null.
+ */
+async function previousStagingDeployment(client, siteId, now) {
+  const result = (state, id = null) => ({ state, id });
+  try {
+    const { deployments, truncated } = await listDeployments(
+      client,
+      siteId,
+      { environment: DEPLOYMENT_ENVIRONMENT_STAGING, pageSize: 5 },
+      { deadline: now() + PREVIOUS_DEPLOYMENT_MILLISECONDS, now },
+    );
+    // A deployment still under way (another terminal's, with a different candidate) will move the edge
+    // before this one does, so a change from the baseline could be its release.
+    if (deployments.some((deployment) => DEPLOYMENT_PENDING_STATUSES.includes(deployment.status))) return result("unknown");
+    const completed = deployments.find((deployment) => deployment.status === DEPLOYMENT_STATUS_COMPLETED);
+    if (completed === undefined) return truncated ? result("unknown") : result("none");
+    const completedAt = Date.parse(completed.completedAt ?? "");
+    if (!Number.isFinite(completedAt)) return result("unknown");
+    // A completion ahead of this machine's clock is treated as recent: the clocks disagree, so
+    // the age cannot be trusted and the wait should not claim to know.
+    return result(
+      now() - completedAt < LIMITS.stagingPropagationCeilingSeconds * 1000 ? "recent" : "settled",
+      completed.id,
+    );
+  } catch (error) {
+    if (client.signal?.aborted) throw error;
+    return result("unknown");
+  }
+}
+
+/**
+ * True when another staging deployment, not this one, may have moved the edge since the
+ * baseline was taken: any non-failed deployment newer than the baseline's newest completed
+ * one (another terminal's, submitted after the baseline listing and before this request).
+ * A listing that cannot show where the baseline sits, or cannot be read, is ambiguous too.
+ */
+async function interveningStagingDeployment(client, siteId, now, { baselineDeploymentId, deploymentId }) {
+  try {
+    // A wider page than the baseline's, so this request's own row cannot push the baseline off it.
+    const { deployments, truncated } = await listDeployments(
+      client,
+      siteId,
+      { environment: DEPLOYMENT_ENVIRONMENT_STAGING, pageSize: 20 },
+      { deadline: now() + PREVIOUS_DEPLOYMENT_MILLISECONDS, now },
+    );
+    const baselineAt = baselineDeploymentId === null
+      ? deployments.length
+      : deployments.findIndex((deployment) => deployment.id === baselineDeploymentId);
+    if (baselineAt < 0 || (baselineDeploymentId === null && truncated)) return true;
+    return deployments.slice(0, baselineAt).some((deployment) =>
+      deployment.id !== deploymentId && deployment.status !== DEPLOYMENT_STATUS_FAILED
+    );
+  } catch (error) {
+    if (client.signal?.aborted) throw error;
+    return true;
+  }
+}
+
+/**
+ * The release staging serves before a deployment is sent, to tell when it
+ * changes. `unsettled` marks a read taken when the previous staging deployment may
+ * still be propagating (or could not be checked): what it saw can be that
+ * deployment's predecessor, so a later change cannot be attributed to this one.
+ */
+export async function readStagingReleaseBefore(client, siteId, now) {
+  // Listed first, so the previous deployment's age is judged no later than the read it qualifies.
+  const { state: previous, id: baselineDeploymentId } = await previousStagingDeployment(client, siteId, now);
+  const observed = await observeStagingRelease(client, siteId, now, {}, now() + BEFORE_READ_MILLISECONDS);
+  // A site that never completed a staging deployment serves nothing yet, whether its host
+  // has no route (a derived address) or refuses a handoff for want of one.
+  if (previous === "none" && observed.kind !== "release") return { kind: "none", unsettled: false, baselineDeploymentId };
+  const unsettled = previous === "recent" || previous === "unknown";
+  // A site that has served a release and gave no readable baseline has nothing to compare against.
+  if (observed.kind === "none") return { kind: "unknown", unsettled, baselineDeploymentId };
+  return { ...observed, unsettled, baselineDeploymentId };
+}
+
+/**
+ * What a deployment reports when the served release cannot be confirmed: only
+ * the ceiling is known. `reason` says why, so a skipped check does not read as a
+ * failed one.
+ */
+export function unverifiedStagingServed(startedAt, reason = "The CLI could not confirm that staging serves the new release.") {
+  const ceiling = LIMITS.stagingPropagationCeilingSeconds;
+  const expectedBy = new Date(startedAt + ceiling * 1000).toISOString();
+  return {
+    state: "unverified",
+    ceilingSeconds: ceiling,
+    expectedBy,
+    message: `${reason} The edge can serve the previous release for up to ${ceiling} seconds after a deployment completes; wait until ${expectedBy} before reviewing.`,
+  };
+}
+
+/**
+ * Waits, within a bound, until staging serves a release other than `before`, and
+ * says what it found. It never fails the deployment: the deployment completed,
+ * and what is uncertain is only when the edge catches up.
+ *
+ * States: `served` (a different release answered twice in a row), `propagating`
+ * (the last read at the bound still showed the previous release), and
+ * `unverified` (the answer cannot be attributed to this deployment, or the last
+ * read did not name the previous release, so only the ceiling is known).
+ */
+export async function confirmStagingServed(client, siteId, { before, deploymentId, coalesced = false, onProgress, now }) {
+  const startedAt = now();
+  const ceiling = LIMITS.stagingPropagationCeilingSeconds;
+  if (before.kind === "unknown") return unverifiedStagingServed(startedAt);
+  if (before.unsettled) {
+    return unverifiedStagingServed(
+      startedAt,
+      "The previous staging deployment completed moments ago, so a change in what staging serves cannot be attributed to this one.",
+    );
+  }
+  if (coalesced) {
+    return unverifiedStagingServed(
+      startedAt,
+      "This request joined a deployment that was already under way, which may already be served.",
+    );
+  }
+  onProgress(
+    `Deployment completed. The edge can serve the previous release for up to ${ceiling} seconds; waiting for staging to serve the new one.`,
+  );
+  const session = {};
+  let streak = 0;
+  // Whether the latest read still named the baseline release: the only evidence of "still the previous release".
+  let stillBaseline = false;
+  let lastReported = startedAt;
+  try {
+    await poll({
+      client,
+      now,
+      onProgress,
+      timeoutMilliseconds: LIMITS.stagingServedMilliseconds,
+      intervalMilliseconds: LIMITS.stagingServedPollMilliseconds,
+      read: async ({ deadline }) => await observeStagingRelease(client, siteId, now, session, deadline),
+      evaluate: (observed) => {
+        stillBaseline = observed.kind === "release" && before.kind === "release"
+          && observed.releaseId === before.releaseId;
+        const isNew = observed.kind === "release"
+          && (before.kind !== "release" || observed.releaseId !== before.releaseId);
+        streak = isNew ? streak + 1 : 0;
+        if (streak >= LIMITS.stagingServedConfirmations) return { done: true, value: true };
+        // One line every fifteen seconds: enough to show it is alive, not a scrolling log.
+        if (stillBaseline && now() - lastReported >= 15_000) {
+          lastReported = now();
+          return { done: false, progress: "Staging is still serving the previous release; checking again." };
+        }
+        return { done: false };
+      },
+      timeoutCode: "staging.served_timeout",
+    });
+  } catch (error) {
+    if (!(error instanceof SiteAuthoringError) || error.code !== "staging.served_timeout") throw error;
+    const waited = Math.round((now() - startedAt) / 1000);
+    if (!stillBaseline) {
+      // The wait outlasted the ceiling, so there is no later time to wait for.
+      return {
+        state: "unverified",
+        waitedSeconds: waited,
+        ceilingSeconds: ceiling,
+        message: `The CLI could not confirm which release staging serves after ${waited} seconds, which is past the ${ceiling}-second ceiling. Open the handoff and confirm the release before reviewing.`,
+      };
+    }
+    return {
+      state: "propagating",
+      waitedSeconds: waited,
+      ceilingSeconds: ceiling,
+      message: `Staging was still serving the previous release ${waited} seconds after the deployment completed. Wait a minute and run 'taproot-site staging review' for a fresh handoff before reviewing.`,
+    };
+  }
+  // The baseline was read before this request was sent; a deployment another terminal completed
+  // in between could be the release that answered, so check the history again before claiming it.
+  if (
+    await interveningStagingDeployment(client, siteId, now, {
+      baselineDeploymentId: before.baselineDeploymentId ?? null,
+      deploymentId,
+    })
+  ) {
+    return unverifiedStagingServed(
+      now(),
+      "Another staging deployment ran around this one, so a change in what staging serves cannot be attributed to it.",
+    );
+  }
+  const seconds = Math.round((now() - startedAt) / 1000);
+  onProgress(`Staging serves the new release (${seconds} seconds after the deployment completed).`);
+  return { state: "served", servedAfterSeconds: seconds, ceilingSeconds: ceiling };
+}

package/src/theme-projection.js

@@ -1,17 +1,7 @@
-import {
-  buildTaprootDarkTheme,
-  buildTaprootLightTheme,
-  DEFAULT_DARK_THEME,
-  DEFAULT_LIGHT_THEME,
-  encodeTheme,
-  layerThemes,
-  mergePartials,
-  mergeTheme,
-  parseTheme,
-} from "@taprootio/espalier/shared/theme";
+import { encodeTheme, layerThemes, mergePartials, mergeTheme, parseTheme } from "@taprootio/espalier/shared/theme";
 
 import { SiteAuthoringError } from "./errors.js";
-import { authoredMappingTokens, missingThemeFields } from "./theme-validation.js";
+import { authoredMappingTokens, missingThemeFields, SCHEME_DEFAULTS } from "./theme-validation.js";
 
 /**
  * Project one stored scheme theme to the complete theme a consumer actually
@@ -19,13 +9,14 @@ import { authoredMappingTokens, missingThemeFields } from "./theme-validation.js
  *
  * Taproot stores what was written. A site whose theme was seeded or written
  * before a key existed keeps a sparse document, and every consumer — the
- * app's preview, the generator, the published runtime — resolves it by
- * layering the same defaults underneath: Espalier's scheme defaults plus,
- * for a theme Taproot still manages, the Taproot house theme with an empty
- * page background. A theme the CLI manages (`*ThemeManagedExternally`) is
- * rendered as stored over Espalier's defaults alone. `pull` writes exactly
- * that effective theme, so a fresh workspace validates and a designer edits
- * every group with its authoritative value instead of reconstructing it.
+ * app's preview, the generator, the published runtime — resolves it the same
+ * way for every theme: as stored, over Espalier's scheme defaults alone. No
+ * renderer layers the Taproot house theme under a stored theme any more
+ * (TR00879), whoever manages it. (The site editor keeps a house reference
+ * layer for its own inheritance display; it is inert for a complete theme and
+ * is not what the site publishes.) `pull` writes exactly that effective theme,
+ * so a fresh workspace validates and a designer edits every group with its
+ * authoritative value instead of reconstructing it.
  *
  * Semantic mappings are the one group that is *not* filled from defaults.
  * Espalier compiles them from `roles` at merge time, and since 4.18.0 the
@@ -52,40 +43,27 @@ import { authoredMappingTokens, missingThemeFields } from "./theme-validation.js
  * rendered before the pull.
  */
 
-const SCHEME_DEFAULTS = Object.freeze({
-  light: { defaults: DEFAULT_LIGHT_THEME, house: buildTaprootLightTheme },
-  dark: { defaults: DEFAULT_DARK_THEME, house: buildTaprootDarkTheme },
-});
+// Espalier's defaults carry no page background at all, but a stored theme must have both keys. No image is
+// the rendered truth, and the opacity of an absent image is neutral; these are the values pull has always
+// written there, so a pulled theme does not change.
+const NO_IMAGE_BACKGROUND_OPACITY = Object.freeze({ light: 0.5, dark: 0.55 });
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-/**
- * The complete theme a consumer layers a stored theme onto: Espalier's
- * scheme defaults, and — unless the theme is managed externally — the
- * Taproot house theme with the empty page background both the BFF and the
- * generator clear before rendering.
- */
-export function effectiveThemeBase(scheme, { managedExternally = false } = {}) {
-  const { defaults, house } = SCHEME_DEFAULTS[scheme];
-  const houseTheme = parseTheme(house("")) ?? {};
-  if (managedExternally) {
-    // Espalier's defaults carry no page background at all; the stored
-    // contract requires both keys. No image is the rendered truth, and the
-    // opacity of an absent image is neutral, so the house value fills it.
-    return {
-      ...defaults,
-      pageBackgroundImage: "",
-      pageBackgroundImageOpacity: houseTheme.pageBackgroundImageOpacity,
-    };
-  }
-  return { ...mergePartials(defaults, houseTheme), pageBackgroundImage: "" };
+/** The complete theme a consumer layers a stored theme onto: Espalier's scheme defaults, with no page background. */
+export function effectiveThemeBase(scheme) {
+  return {
+    ...SCHEME_DEFAULTS[scheme],
+    pageBackgroundImage: "",
+    pageBackgroundImageOpacity: NO_IMAGE_BACKGROUND_OPACITY[scheme],
+  };
 }
 
-export function projectPulledTheme(stored, scheme, { managedExternally = false } = {}) {
+export function projectPulledTheme(stored, scheme) {
   const source = isPlainObject(stored) ? stored : {};
-  const base = effectiveThemeBase(scheme, { managedExternally });
+  const base = effectiveThemeBase(scheme);
   const { semanticMappings: _baseMappings, ...layerable } = base;
   // The marker is set on the base so mergePartials treats every stored
   // mapping as authored; the pin filter below then decides which survive.
@@ -102,7 +80,6 @@ export function projectPulledTheme(stored, scheme, { managedExternally = false }
     { ...merged, semanticMappings: pins, explicitMappingTokens: Object.keys(pins) },
     source,
     scheme,
-    managedExternally,
     authored,
   );
 
@@ -111,12 +88,8 @@ export function projectPulledTheme(stored, scheme, { managedExternally = false }
 }
 
 /** What a consumer renders for a stored theme: the partial it layers, resolved over Espalier's defaults. */
-function renderedTheme(stored, scheme, managedExternally) {
-  const { defaults, house } = SCHEME_DEFAULTS[scheme];
-  const layered = managedExternally
-    ? layerThemes(encodeTheme(stored))
-    : layerThemes(house(""), encodeTheme({ pageBackgroundImage: "" }), encodeTheme(stored));
-  return mergeTheme(defaults, parseTheme(layered) ?? {});
+function renderedTheme(stored, scheme) {
+  return mergeTheme(SCHEME_DEFAULTS[scheme], parseTheme(layerThemes(encodeTheme(stored))) ?? {});
 }
 
 function canonicalJson(value) {
@@ -137,11 +110,11 @@ function canonicalJson(value) {
  * out of the projection and keep recompiling. Every other difference between
  * the projection and the stored theme's rendering is written back.
  */
-function reconcileWithRendering(projected, stored, scheme, managedExternally, authored) {
-  const { defaults } = SCHEME_DEFAULTS[scheme];
+function reconcileWithRendering(projected, stored, scheme, authored) {
+  const defaults = SCHEME_DEFAULTS[scheme];
   let rendered;
   try {
-    rendered = renderedTheme(stored, scheme, managedExternally);
+    rendered = renderedTheme(stored, scheme);
   } catch {
     // An invalid stored theme cannot be rendered for comparison; validation
     // reports it, and the layered projection is the best available document.

package/src/theme-validation.js

@@ -300,7 +300,8 @@ function refuseAgentStylesheets(theme, scheme) {
   }
 }
 
-const SCHEME_DEFAULTS = Object.freeze({ light: DEFAULT_LIGHT_THEME, dark: DEFAULT_DARK_THEME });
+/** Espalier's complete default theme for each scheme: the base every stored theme is rendered over. */
+export const SCHEME_DEFAULTS = Object.freeze({ light: DEFAULT_LIGHT_THEME, dark: DEFAULT_DARK_THEME });
 
 function sameMapping(left, right) {
   return isPlainObject(left) && isPlainObject(right)

package/src/transport.js

@@ -27,6 +27,7 @@ import {
 } from "./constants.js";
 import { Readable } from "node:stream";
 
+import { normalizeLatestCliVersion } from "./cli-release.js";
 import { validateApiBaseUrl } from "./config.js";
 import { hasControlCharacter, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 
@@ -574,6 +575,18 @@ export class ApiError extends SiteAuthoringError {
     return undefined;
   }
 
+  /**
+   * The latest published release a `cli_outdated` refusal names, or undefined.
+   * Taproot states it only inside the refusal's sentence, so it is read from
+   * there and kept only if it parses as a version (TR01225).
+   */
+  latestCliVersion() {
+    if (this.refusalKind() !== REFUSAL_CLI_OUTDATED) return undefined;
+    const text = this.descriptionFor(CLI_UPGRADE_REFUSAL_FIELD) ?? this.message;
+    const match = /accepts only the latest published release, (\S+?)\. Upgrade with:/u.exec(text);
+    return match === null ? undefined : normalizeLatestCliVersion(match[1]);
+  }
+
   /**
    * Classifies a refusal into the one thing the caller should do next. The
    * six kinds are genuinely different behaviors, and collapsing them into

package/src/typed-page-reference.js

@@ -323,9 +323,120 @@ const TYPE_DETAILS = Object.freeze({
   },
 });
 
-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));
+/**
+ * The legal page type (TR01221). It is described here and nowhere else in the
+ * CLI: it has no template name in `typed-pages.js` because a site-authoring
+ * key cannot author it, so `pull` records it as a metadata-only page and
+ * `pages push` never sees a source for it.
+ */
+export const LEGAL_PAGE_TYPE = "legal";
+
+export const TYPED_PAGE_TYPES = Object.freeze([...Object.keys(TYPE_DETAILS), LEGAL_PAGE_TYPE]);
+/** The templates a Markdown source can declare: the authorable typed pages, not generated or legal. */
+export const MARKDOWN_PAGE_TYPES = Object.freeze(
+  TYPED_PAGE_TYPES.filter((type) => type !== TEMPLATE_GENERATED && type !== LEGAL_PAGE_TYPE),
+);
+
+/**
+ * The default for any privacy policy or other legal text that names the
+ * platform (TR01224). `help page free-form` prints it too, because a policy
+ * written through the CLI is a free-form page.
+ */
+export const LEGAL_PLATFORM_LINK_GUIDANCE = Object.freeze({
+  rule:
+    "Where a privacy policy or other legal page names Taproot, link the first mention to https://www.taproot.io by "
+    + "default, so readers can learn how the platform affects them. Leave it plain only if the owner asks.",
+  example: "This site is published on [Taproot](https://www.taproot.io).",
+});
+
+function legalReference() {
+  return Object.freeze({
+    type: LEGAL_PAGE_TYPE,
+    displayName: "Legal page",
+    summary:
+      "A versioned legal document such as a privacy policy or terms: an automatic h1, a version and effective date, and "
+      + "permanent links to each version. The CLI sees it as metadata only; it is created and published in the app.",
+    readOnly: true,
+    workspace: Object.freeze({
+      directory: `${PAGES_DIRECTORY}/`,
+      templateType: "TEMPLATE_TYPE_LEGAL",
+      sourceRule:
+        "A legal page has no source file. 'pull' lists it in .taproot-site-manifest.json with templateType "
+        + "TEMPLATE_TYPE_LEGAL and workspaceMode \"metadata-only\" and writes nothing under pages/ for it, so 'pages push' has "
+        + "nothing to send.",
+    }),
+    fields: Object.freeze([
+      Object.freeze({ name: "title", description: "The page title. It prints as the page's h1, so the body should not open with its own title." }),
+      Object.freeze({
+        name: "body",
+        description: "The rich-text document. A table of contents is built from its level-2 headings.",
+      }),
+      Object.freeze({
+        name: "documentKey",
+        description:
+          "The document's stable identity, set in the app. The permanent version address exists only once the page has "
+          + "a document key and a version.",
+      }),
+      Object.freeze({
+        name: "documentRole",
+        description:
+          "The typed purpose of the document, such as membership_terms or privacy_notice. Selected in the app; fixed for membership terms.",
+      }),
+      Object.freeze({ name: "summaryOfChanges", description: "A short note on what this version changed, written by the owner." }),
+      Object.freeze({
+        name: "material",
+        description: "Set by a person: this version's changes need readers to accept again when the site's policy asks for that.",
+      }),
+      Object.freeze({
+        name: "version, effectiveDate, supersedesVersion",
+        description:
+          "Assigned by Taproot when the document is promoted to production: the version number, the promotion date, and "
+          + "the version it replaces. They cannot be written, so a document that has not been promoted shows none of them.",
+      }),
+    ]),
+    rendering: Object.freeze([
+      "An automatic <h1> from the title, then an Effective, Version and Supersedes list, a download link for a PDF of "
+      + "the version, the summary of changes, and a table of contents, once those exist.",
+      "Two addresses once published: the current document at /<path>, and an immutable copy of each version at "
+      + "/<path>/<version> (and /<path>/<version>.pdf). Later versions never change an earlier address.",
+    ]),
+    authoring: Object.freeze({
+      cli:
+        "Read-only. 'pull' records the page's identity, path, title and status. No verb creates, edits, converts, "
+        + "approves or publishes one. A bare 'approve' stages every tracked page with a draft, a pending legal draft "
+        + "included, and the request holding it is refused (up to 100 pages go in one request): name the pages ('approve <path>').",
+      key:
+        "A site-authoring key cannot create or publish a legal page, and a production deploy whose selected pages include "
+        + "one is refused for a key, because the permission that governs legal documents (site.legal_documents.manage) is "
+        + "outside the key's delegation.content, delegation.design and delegation.deployments capabilities. Until a "
+        + "person promotes an app-approved legal page, every production promotion of a release staged after that approval is refused. This is how keys work today; whether a key should ever author a legal page is an open owner decision.",
+      app:
+        "A signed-in person who may manage the site's legal documents creates the page, writes its body, and publishes it "
+        + "with a production deployment in the app. Taproot assigns the version and effective date at that point.",
+    }),
+    choosing: Object.freeze({
+      legal:
+        "Choose a legal page when readers must be able to see which version applied and when it took effect, such as a "
+        + "privacy policy, terms of service or membership terms.",
+      freeForm:
+        "A free-form page is an ordinary page. It has no version history, no effective date, no permanent version "
+        + "addresses and no automatic heading: open its Markdown with a '# ' line holding the title (see "
+        + `'${CLI_BINARY_NAME} help page free-form'). The CLI cannot author a legal page, so a policy written here is an ordinary `
+        + "page, free-form unless another template fits: put the date it was last updated in its text, and tell the owner it is not versioned.",
+    }),
+    platformLink: LEGAL_PLATFORM_LINK_GUIDANCE,
+    workflow: Object.freeze([
+      Object.freeze({
+        command: `${CLI_BINARY_NAME} pull`,
+        result: "Records the page as metadata-only in the manifest; nothing to edit.",
+      }),
+      Object.freeze({
+        command: "the app",
+        result: "A person with the legal permission edits the draft and promotes it with a production deployment.",
+      }),
+    ]),
+  });
+}
 
 function typedReference(type) {
   const details = TYPE_DETAILS[type];
@@ -389,7 +500,11 @@ function typedReference(type) {
   });
 }
 
-const REFERENCES = Object.freeze(Object.fromEntries(TYPED_PAGE_TYPES.map((type) => [type, typedReference(type)])));
+const REFERENCES = Object.freeze(
+  Object.fromEntries(
+    TYPED_PAGE_TYPES.map((type) => [type, type === LEGAL_PAGE_TYPE ? legalReference() : typedReference(type)]),
+  ),
+);
 
 /** The reference for one non-free-form template, or `undefined`. */
 export function getTypedPageReference(type) {
@@ -400,8 +515,17 @@ function formatField(field) {
   return `  ${field.name.padEnd(18)} ${field.type}; ${field.required ? "required" : "optional"}; ${field.description}`;
 }
 
+function formatLegalReference(page) {
+  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n\nFields (set in the app):\n${
+    page.fields.map((field) => `  ${field.name}: ${field.description}`).join("\n")
+  }\n\nHow it renders:\n${page.rendering.map((line) => `  - ${line}`).join("\n")}\n\nWho can author it:\n  CLI                   ${page.authoring.cli}\n  site-authoring key    ${page.authoring.key}\n  app                   ${page.authoring.app}\n\nLegal page or free-form page:\n  legal                 ${page.choosing.legal}\n  free-form             ${page.choosing.freeForm}\n\nLinking Taproot: ${page.platformLink.rule}\n  example               ${page.platformLink.example}\n\nWorkflow:\n${
+    page.workflow.map((step) => `  ${step.command}: ${step.result}`).join("\n")
+  }\n\nUse --json for the exact structure.\n`;
+}
+
 /** The plain-text `help page <type>` rendering. */
 export function formatTypedPageReference(page) {
+  if (page.type === LEGAL_PAGE_TYPE) return formatLegalReference(page);
   const markdown = page.workspace.formats.find((format) => format.extension === ".md");
   const json = page.workspace.formats.find((format) => format.extension === ".pm.json");
   const markdownSection = markdown === undefined