@taprootio/site-authoring 0.23.1 → 0.26.0

package/src/reference-help.js

@@ -50,6 +50,13 @@ import {
   FORM_SINKS,
   FORMS_DIRECTORY,
 } from "./forms-contract.js";
+import {
+  LINK_SOURCES,
+  MARKETING_KEY_RULE,
+  MARKETING_KINDS,
+  MARKETING_STATES,
+  maximumActive,
+} from "./marketing-contract.js";
 import {
   formatPresentationReference,
   getAppearanceReference,
@@ -88,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 41;
+export const REFERENCE_VERSION = 43;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -389,7 +396,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 page types: free-form, article, recipe, album, place-review, generated, and the read-only legal page." }),
+  Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List page types: free-form, article, recipe, album, place-review, generated, and legal draft pages." }),
   Object.freeze({
     name: "page",
     usage: `${CLI_BINARY_NAME} help page <page-type>`,
@@ -422,6 +429,16 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help forms`,
     summary: "Author a form as forms/<key>.json: file shape, field types, validate, pull, push, and placing it on a page.",
   }),
+  Object.freeze({
+    name: "marketing",
+    usage: `${CLI_BINARY_NAME} help marketing`,
+    summary: "Keep a site's campaigns and placements as marketing/*.json: file shape, pull, push, archive, and what an agent may do.",
+  }),
+  Object.freeze({
+    name: "link",
+    usage: `${CLI_BINARY_NAME} help link`,
+    summary: "Build a tracked address: path, source, optional campaign and placement; what counts and when it goes live.",
+  }),
   Object.freeze({
     name: "media",
     usage: `${CLI_BINARY_NAME} help media`,
@@ -903,6 +920,95 @@ const WORKFLOW_REFERENCES = Object.freeze({
       }),
     }),
   }),
+  marketing: Object.freeze({
+    title: "Campaigns and placements workspace contract",
+    summary: "A site's campaigns and placements are two JSON files under marketing/. 'marketing pull' reads the site's, "
+      + "'marketing push' creates, updates, restores and (with --archive) archives to match them, and 'link build' prints "
+      + "an address that uses them.",
+    usage: `${CLI_BINARY_NAME} marketing pull | ${CLI_BINARY_NAME} marketing push [--archive]`,
+    details: Object.freeze([
+      "Run 'pull' once first: both verbs need the pulled workspace's manifest, which records what each record looked "
+      + "like when this workspace last read it. The site's licence must include analytics, and the site must be a Standard site.",
+      `A campaign groups links from one push; a placement names the spot a link appears, such as a newsletter footer. `
+      + `Both are public keys the site's release admits, so page views carry them: a campaign as utm_campaign, a placement as `
+      + `utm_content. ${MARKETING_KINDS.campaigns.file} is { campaigns: [ { key, name, note?, starts_on?, ends_on? } ] }; `
+      + `${MARKETING_KINDS.placements.file} is { placements: [ { key, name } ] }. Records are listed by key.`,
+      `A key is ${MARKETING_KEY_RULE}. It is public URL text and never changes or returns to use, even after the record is `
+      + "archived, because page views already counted under it keep the key. A name (at most "
+      + `${MARKETING_KINDS.campaigns.rules.nameMaxLength} characters), a campaign's note (at most ${MARKETING_KINDS.campaigns.rules.noteMaxLength}) `
+      + "and its starts_on and ends_on days (YYYY-MM-DD, labels only) are private and can change.",
+      `A pull also writes two read-only fields: state (${MARKETING_STATES.join(", ")}) and counted_from, the day the key first `
+      + "went live and page views began to count under it. A push ignores both. A record is live once the silent release "
+      + "that carries its key has run; until then page views count under the source only.",
+      "'marketing push' validates both files and compares every record with the site before the first write. "
+      + "A key the file names that the site lacks is created. A record whose labels differ is updated. A key the file "
+      + "names that the site has archived is restored (and updated if its labels differ). Nothing else is touched: a "
+      + "record the file leaves out stays unless you pass --archive, and --archive archives only records this workspace "
+      + "pulled. A changed key is therefore a new record plus, if you want the old one gone, an explicit --archive.",
+      "A record that changed on the site since the last pull is refused as marketing.concurrent_modification, a key "
+      + "the site has that this workspace never pulled as marketing.pull_required; reconcile with 'marketing pull' and "
+      + "retry. Taproot refuses a key outside the grammar, a key already used by an archived record, and a record over "
+      + `the quota (${maximumActive("campaigns")} unarchived campaigns, ${maximumActive("placements")} unarchived placements, and a larger cap on archived ones `
+      + "together); the refusal is shown as Taproot returns it. Archive one to make room, or restore an archived one.",
+      "'marketing pull' reports, per kind, file, total, items ([{ key, state }], at most 200), archived keys (at most 200, "
+      + "with archivedTotal and archivedTruncated), canManage and maxActive. 'marketing push' reports, per kind, the keys it "
+      + "created, updated, restored, archived, left unchanged, left on the site because the file omits them (unlisted) and found "
+      + "on the site but never pulled (unpulled), each list capped at 50 with the true totals in counts and the capped lists "
+      + "named in truncated; written is { items, count } across both kinds.",
+      "Creating or restoring a key queues a silent production release that starts admitting it; no 'deploy' is needed and "
+      + "none is waited for. 'marketing pull' later shows the state. Archiving queues no release: the key stops being admitted from the next one.",
+      "The delegation.content capability carries the permissions this needs: site.analytics.view to read and also "
+      + "site.pages.publish_any to change, because a new key publishes a release. Platform-wide, an administrator can pause external "
+      + "authoring; a push is then refused with the rollout field. A refusal names a missing permission.",
+    ]),
+    example: Object.freeze({
+      campaigns: Object.freeze({
+        campaigns: Object.freeze([
+          Object.freeze({
+            key: "spring-launch",
+            name: "Spring launch",
+            note: "Newsletter and social push",
+            starts_on: "2026-03-01",
+            ends_on: "2026-03-31",
+          }),
+        ]),
+      }),
+      placements: Object.freeze({
+        placements: Object.freeze([Object.freeze({ key: "nl-footer", name: "Newsletter footer" })]),
+      }),
+      commands: Object.freeze([
+        `${CLI_BINARY_NAME} marketing pull`,
+        `${CLI_BINARY_NAME} marketing push`,
+        `${CLI_BINARY_NAME} link build --path /recipes/spring-salad --source newsletter --campaign spring-launch --placement nl-footer`,
+      ]),
+    }),
+  }),
+  link: Object.freeze({
+    title: "Tracked link builder",
+    summary: "'link build' prints one address that counts under a source, and optionally a campaign and a placement. It saves nothing.",
+    usage: `${CLI_BINARY_NAME} link build --path <page> --source <key> [--campaign <key>] [--placement <key>] [--domain <host>]`,
+    details: Object.freeze([
+      "--path is the page on this site, such as /recipes/spring-salad; / or an empty value is the home page. A query or #fragment "
+      + "is kept; a full address is accepted only if it is on this site's own host. --source is where the link will be posted: "
+      + `${LINK_SOURCES.map((source) => source.key).join(", ")}. The medium (social or email) is set by the source and cannot be chosen. 'reader' is not offered: `
+      + "a published page's own share action sets it.",
+      "The address is https://<public host><path>?utm_source=<source>&utm_medium=<medium>[&utm_campaign=<campaign>][&utm_content=<placement>]. "
+      + "A utm_source, utm_medium, utm_campaign or utm_content already on the path is replaced, never duplicated. Page views carry these values into the site's "
+      + "analytics only for campaigns and placements the site admits; anything else is dropped.",
+      "The host is the site's public address, read from the signed-in site; a site credential alone cannot read it, so "
+      + "pass --domain <host> then. A site with no public address yet has nothing to build a link to.",
+      "A campaign or placement is checked first. When the workspace has marketing/campaigns.json or marketing/placements.json "
+      + "(from 'marketing pull'), the file is the record of what exists; otherwise the live site is asked. A key it does not "
+      + "hold, or one the site has archived, is refused, because it would not be counted. A key that exists but is not live yet is "
+      + "allowed, and the result carries a note: 'publishing' while its release runs, 'goes live with your first publish' for a site "
+      + "that has not published, or 'not in the current release' after a rollback. Until it is live, page views count under the source only. A note read from a file says it is as of the last marketing pull or push, so run 'marketing pull' for the current state.",
+      "The result is { link: { address, host, path, source, medium, campaign?, placement? }, notes? }.",
+    ]),
+    example: Object.freeze({
+      command: `${CLI_BINARY_NAME} link build --path /recipes/spring-salad --source newsletter --campaign spring-launch --placement nl-footer`,
+      address: "https://example.com/recipes/spring-salad?utm_source=newsletter&utm_medium=email&utm_campaign=spring-launch&utm_content=nl-footer",
+    }),
+  }),
   media: Object.freeze({
     title: "Media upload contract",
     summary: "Upload workspace-root-relative raster files and videos; images are recorded in .taproot-site-media.json and videos report their ids.",
@@ -1728,7 +1834,7 @@ const FREE_FORM_REFERENCE = Object.freeze({
     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'.`,
+        `A policy that needs a version and an effective date is a legal page; see '${CLI_BINARY_NAME} help page legal' for draft editing and app approval.`,
     }),
     componentNode: Object.freeze({
       type: "componentBlock",

package/src/session.js

@@ -11,6 +11,7 @@ import {
   ROLLOUT_REFUSAL_FIELD,
   VERB_LOGIN,
   VERB_USE,
+  SURFACE_STANDARD,
 } from "./constants.js";
 import { loadSiteConfig } from "./config.js";
 import { cliOutdatedError, compareCliVersions, isBehindLatest } from "./cli-release.js";
@@ -85,7 +86,7 @@ function keyMissingError() {
  * The exchange's own answer is checked again afterwards, because the
  * recording can be stale.
  */
-function requireRecordedSurface(invocation, config) {
+export function requireRecordedSurface(invocation, config) {
   if (invocation.surface === undefined || config.authoringSurface === undefined) return;
   if (!surfaceAllows(config.authoringSurface, invocation.surface)) {
     throw surfaceRefusal(invocation.verb ?? "This verb", config.authoringSurface, { source: "config" });
@@ -219,6 +220,7 @@ export async function resolveApiBaseUrl(environment) {
 }
 
 export async function openSession(invocation = {}) {
+  if (invocation.resolvedSession !== undefined) return invocation.resolvedSession;
   const environment = invocation.environment ?? process.env;
   const onProgress = progressSink(invocation);
   const now = invocation.now ?? Date.now;
@@ -231,6 +233,9 @@ export async function openSession(invocation = {}) {
   // at all.
   const environmentToken = environment?.[PUBLISH_KEY_ENVIRONMENT_VARIABLE];
   if (environmentToken !== undefined) {
+    if (invocation.legalDrafts) {
+      throw new SiteAuthoringError("auth.legal_environment_override", `Unset ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} and run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts' to use the selected site's legal draft grant.`);
+    }
     const apiBaseUrl = await resolveApiBaseUrl(environment);
     const config = await loadConfig(invocation);
     if (!config.siteId) throw siteMissingError();
@@ -244,6 +249,7 @@ export async function openSession(invocation = {}) {
     return {
       config,
       client,
+      legalDrafts: false,
       siteId: config.siteId,
       surface: config.authoringSurface,
       platform: UNKNOWN_PLATFORM,
@@ -253,6 +259,32 @@ export async function openSession(invocation = {}) {
     };
   }
 
+  if (invocation.legalDrafts) {
+    const apiBaseUrl = await resolveApiBaseUrl(environment);
+    const config = await loadConfig(invocation);
+    if (!config.siteId) throw siteMissingError();
+    if (config.authoringSurface !== undefined && config.authoringSurface !== SURFACE_STANDARD) {
+      throw new SiteAuthoringError("auth.legal_site_required", "Legal draft access requires a standard site.");
+    }
+    requireRecordedSurface(invocation, config);
+    const store = await readCredentialStore(environment);
+    const credential = selectCredential(store.credentials, credentialApiOrigin(apiBaseUrl), { siteId: config.siteId });
+    if (credential === undefined) {
+      throw new SiteAuthoringError("auth.legal_grant_missing", `Legal draft access is missing. Run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts' again.`);
+    }
+    if (Date.parse(credential.keyExpiresAt) <= now()) {
+      onProgress(
+        `The stored legal draft grant expired at ${credential.keyExpiresAt}. `
+          + `If Taproot refuses it, run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts' again.`,
+      );
+    }
+    return {
+      config, client: invocation.client ?? new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, credential.key)),
+      legalDrafts: true, siteId: config.siteId, surface: config.authoringSurface,
+      platform: UNKNOWN_PLATFORM, release: UNKNOWN_CLI_RELEASE, now, onProgress,
+    };
+  }
+
   let config;
   let apiBaseUrl;
   const signIn = await requireSignIn(environment, async () => {
@@ -280,6 +312,7 @@ export async function openSession(invocation = {}) {
     return {
       config,
       client: invocation.client,
+      legalDrafts: false,
       siteId: config.siteId,
       surface: config.authoringSurface,
       platform: UNKNOWN_PLATFORM,
@@ -403,6 +436,7 @@ export async function openSession(invocation = {}) {
     config,
     client,
     siteId: config.siteId,
+    legalDrafts: false,
     surface: exchanged.authoringSurface,
     exchanged: {
       keyId: exchanged.keyId,

package/src/site-check-findings.js

@@ -36,7 +36,6 @@ export const SITE_CHECK_WORDING = Object.freeze({
   "redirect.source_invalid": () => "has a source that is not an absolute site path",
   "redirect.source_index_html": () => "has a source ending in index.html",
   "redirect.source_integration_data": () => "has a source under the integration data root",
-  "redirect.source_share_link": () => "has a source under the share-link root",
   "redirect.source_runtime_mirror": () => "has a source under the published-site runtime",
   "redirect.source_generated_file": () => "has a source naming a file the site generates",
   "redirect.source_not_storable": () => "has a source the publisher cannot store",

package/src/site-check-rules.json

@@ -16,7 +16,6 @@
     { "id": "redirect.source_invalid", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "none" },
     { "id": "redirect.source_index_html", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_integration_data", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
-    { "id": "redirect.source_share_link", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_runtime_mirror", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_generated_file", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_not_storable", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },

package/src/site-checks.js

@@ -19,7 +19,6 @@ export const RULE_FORM_KEY_UNKNOWN = "form.key_unknown";
 export const RULE_REDIRECT_SOURCE_INVALID = "redirect.source_invalid";
 export const RULE_REDIRECT_SOURCE_INDEX_HTML = "redirect.source_index_html";
 export const RULE_REDIRECT_SOURCE_INTEGRATION_DATA = "redirect.source_integration_data";
-export const RULE_REDIRECT_SOURCE_SHARE_LINK = "redirect.source_share_link";
 export const RULE_REDIRECT_SOURCE_RUNTIME_MIRROR = "redirect.source_runtime_mirror";
 export const RULE_REDIRECT_SOURCE_GENERATED_FILE = "redirect.source_generated_file";
 export const RULE_REDIRECT_SOURCE_NOT_STORABLE = "redirect.source_not_storable";
@@ -282,7 +281,6 @@ export function normalizeRedirectPath(value) {
 }
 const GENERATED_ROOT_FILES = ["404.html", "sitemap.xml", "robots.txt", "favicon.ico"];
 const INTEGRATION_DATA_ROOT = "integrations";
-const SHARE_LINK_ROOT = "s";
 const MAX_MARKER_SEGMENT_BYTES = 200;
 const MAX_OUTPUT_PATH_LENGTH = 1_024;
 const WINDOWS_DEVICE_STEMS = new Set(["con", "prn", "aux", "nul"]);
@@ -317,10 +315,6 @@ export function redirectSourceRule(edgePath) {
     }
     if (first.toLowerCase() === INTEGRATION_DATA_ROOT)
         return refuse(RULE_REDIRECT_SOURCE_INTEGRATION_DATA);
-    const shareSegments = decoded.replace(/^\/+|\/+$/gu, "").split("/");
-    if (shareSegments.length > 1 && shareSegments[1].length > 0 && shareSegments[0].toLowerCase() === SHARE_LINK_ROOT) {
-        return refuse(RULE_REDIRECT_SOURCE_SHARE_LINK);
-    }
     if (isRuntimeMirrorPath(decoded))
         return refuse(RULE_REDIRECT_SOURCE_RUNTIME_MIRROR);
     if (GENERATED_ROOT_FILES.includes(first.toLowerCase()))

package/src/typed-page-reference.js

@@ -323,12 +323,6 @@ const TYPE_DETAILS = Object.freeze({
   },
 });
 
-/**
- * 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]);
@@ -355,15 +349,14 @@ function legalReference() {
     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,
+      + "permanent links to each version. The CLI can edit drafts with an explicit site grant; approval and publication happen in the app.",
+    readOnly: false,
     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.",
+        "Pull writes a .pm.json source containing template legal and data with documentKey, documentRole, summaryOfChanges, material and body. "
+        + "Edit that source to change the draft; Markdown is not supported. To create one, add a .pm.json source and a manifest pages entry with file, title and path, without a pageId. Version, effectiveDate and supersedesVersion are assigned by Taproot and must not be authored.",
     }),
     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." }),
@@ -374,13 +367,13 @@ function legalReference() {
       Object.freeze({
         name: "documentKey",
         description:
-          "The document's stable identity, set in the app. The permanent version address exists only once the page has "
+          "The document's stable identity, fixed after creation. 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.",
+          "The typed purpose of the document, such as membership_terms or privacy_notice. Fixed after creation.",
       }),
       Object.freeze({ name: "summaryOfChanges", description: "A short note on what this version changed, written by the owner." }),
       Object.freeze({
@@ -402,14 +395,11 @@ function legalReference() {
     ]),
     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>').",
+        "Pull reads legal pages with ordinary Content access. Run 'taproot-site login --legal-drafts', then "
+        + "'taproot-site --legal-drafts pages push' to create or edit legal drafts. Approval and deletion are refused by the CLI; use the app. A bare 'approve' skips legal drafts; naming a legal page refuses the whole selection.",
       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.",
+        "Only an explicit site-specific legal-drafts grant can save legal drafts. It does not grant site.legal_documents.manage, "
+        + "and cannot approve, delete or deploy legal documents.",
       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.",
@@ -421,18 +411,21 @@ function legalReference() {
       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.",
+        + `'${CLI_BINARY_NAME} help page free-form'). A policy written as free-form is an ordinary page; put its last-updated date 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.",
+        result: "Writes the legal draft as a .pm.json source and records its identity in the manifest.",
+      }),
+      Object.freeze({
+        command: `${CLI_BINARY_NAME} login --legal-drafts`,
+        result: "Request a site-specific grant; a person approves it in the app.",
       }),
       Object.freeze({
-        command: "the app",
-        result: "A person with the legal permission edits the draft and promotes it with a production deployment.",
+        command: `${CLI_BINARY_NAME} --legal-drafts pages push`,
+        result: "Saves changed legal drafts. A person approves and publishes them in the app.",
       }),
     ]),
   });
@@ -516,7 +509,7 @@ function formatField(field) {
 }
 
 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${
+  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n\nFields:\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")

package/src/typed-pages.js

@@ -30,6 +30,7 @@ export const TEMPLATE_ARTICLE = "article";
 export const TEMPLATE_RECIPE = "recipe";
 export const TEMPLATE_ALBUM = "album";
 export const TEMPLATE_PLACE_REVIEW = "place-review";
+export const TEMPLATE_LEGAL = "legal";
 /**
  * A page Taproot generates (a tag, a month, a folder). It is update-only: the
  * owner's title, breadcrumb, description and introduction are authored, and
@@ -44,6 +45,7 @@ export const PAGE_TEMPLATES = Object.freeze({
   [TEMPLATE_RECIPE]: Object.freeze({ wireType: "TEMPLATE_TYPE_RECIPE", dataKey: "recipeData" }),
   [TEMPLATE_ALBUM]: Object.freeze({ wireType: "TEMPLATE_TYPE_ALBUM", dataKey: "albumData" }),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze({ wireType: "TEMPLATE_TYPE_PLACE_REVIEW", dataKey: "placeReviewData" }),
+  [TEMPLATE_LEGAL]: Object.freeze({ wireType: "TEMPLATE_TYPE_LEGAL", dataKey: "legalDocumentData" }),
   [TEMPLATE_GENERATED]: Object.freeze({ wireType: "TEMPLATE_TYPE_GENERATED", dataKey: "generatedPageData" }),
 });
 
@@ -77,6 +79,7 @@ const TEMPLATE_FRONT_MATTER_KEYS = Object.freeze({
   [TEMPLATE_PLACE_REVIEW]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "placeId", "rating"]),
   // Generated pages have no Markdown form.
   [TEMPLATE_GENERATED]: Object.freeze([]),
+  [TEMPLATE_LEGAL]: Object.freeze([]),
 });
 
 export const FRONT_MATTER_KEYS = Object.freeze(
@@ -172,7 +175,17 @@ export function isAuthorableTemplateType(wireType) {
   return templateNameForWireType(wireType) !== undefined;
 }
 
-/** Whether a wire `templateType` is a generated page. */
+/** Whether this wire template type is a legal document. */
+export function isLegalTemplateType(wireType) {
+  return wireType === PAGE_TEMPLATES[TEMPLATE_LEGAL].wireType;
+}
+
+/** The legal identity fields that remain fixed after creation. */
+export function legalIdentity(data) {
+  return { documentKey: data.documentKey, documentRole: data.documentRole };
+}
+
+/** Whether this wire template type is a generated page. */
 export function isGeneratedTemplateType(wireType) {
   return wireType === PAGE_TEMPLATES[TEMPLATE_GENERATED].wireType;
 }
@@ -342,6 +355,13 @@ function canonicalIngredient(value) {
  * server's JSON omits defaults and may gain fields).
  */
 const DATA_BUILDERS = Object.freeze({
+  [TEMPLATE_LEGAL]: (raw) => ({
+    documentKey: raw.documentKey ?? "",
+    documentRole: raw.documentRole ?? "",
+    summaryOfChanges: raw.summaryOfChanges ?? "",
+    material: raw.material === true,
+    body: raw.body,
+  }),
   [TEMPLATE_ARTICLE]: (raw) => definedEntries([["body", raw.body], ["place", raw.place]]),
   [TEMPLATE_PLACE_REVIEW]: (raw) => ({ placeId: raw.placeId, rating: raw.rating, body: raw.body }),
   // Defaults are written out, so a page with no custom title reads the same on every pull.
@@ -415,6 +435,16 @@ function optionalPlace(value, file, path) {
 /** Strict checks on a source document's `data`, returning it in canonical form. */
 function canonicalSourceData(template, data, file) {
   const path = "data";
+  if (template === TEMPLATE_LEGAL) {
+    requireKeys(data, ["documentKey", "documentRole", "summaryOfChanges", "material", "body"], file, path);
+    for (const key of ["documentKey", "documentRole", "summaryOfChanges"]) {
+      if (data[key] !== undefined) requireString(data[key], file, `${path}.${key}`);
+    }
+    if (data.material !== undefined && typeof data.material !== "boolean") {
+      throw fail("pages.document_shape", `'${file}' ${path}.material must be true or false.`, file);
+    }
+    return DATA_BUILDERS[template]({ ...data, body: requireDocument(data.body, file, `${path}.body`, { nonEmpty: true }) });
+  }
   if (template === TEMPLATE_ARTICLE) {
     requireKeys(data, ["body", "place"], file, path);
     return DATA_BUILDERS[template]({
@@ -564,10 +594,10 @@ export function typedDocumentFromJson(parsed, file) {
       file,
     );
   }
-  if (template === TEMPLATE_GENERATED && (parsed.displayDate !== undefined || parsed.coverImageId !== undefined)) {
+  if ((template === TEMPLATE_GENERATED || template === TEMPLATE_LEGAL) && (parsed.displayDate !== undefined || parsed.coverImageId !== undefined)) {
     throw fail(
       "pages.document_shape",
-      `'${file}' is a generated page, which has no displayDate or coverImageId of its own: its document is `
+      `'${file}' is a ${template} page, which has no displayDate or coverImageId of its own: its document is `
         + "{ template, data }.",
       file,
     );
@@ -602,6 +632,16 @@ const pagePlaceId = (value) =>
 
 /** Lenient projections of what the site returned for each template's data. */
 const PAGE_PROJECTIONS = Object.freeze({
+  [TEMPLATE_LEGAL]: (raw) => {
+    const body = presentDocument(raw.body);
+    return body === undefined ? undefined : DATA_BUILDERS[TEMPLATE_LEGAL]({
+      documentKey: typeof raw.documentKey === "string" ? raw.documentKey : "",
+      documentRole: typeof raw.documentRole === "string" ? raw.documentRole : "",
+      summaryOfChanges: typeof raw.summaryOfChanges === "string" ? raw.summaryOfChanges : "",
+      material: raw.material === true,
+      body,
+    });
+  },
   [TEMPLATE_ARTICLE]: (raw) => {
     const body = presentDocument(raw.body);
     return body === undefined ? undefined : DATA_BUILDERS[TEMPLATE_ARTICLE]({ body, place: pagePlaceId(raw.place) });
@@ -666,7 +706,7 @@ export function workspaceDocumentFromPage(page, listedTemplateType) {
   const data = PAGE_PROJECTIONS[name](raw);
   if (data === undefined) return undefined;
   // A generated page's date and cover are not part of its source: a push leaves them as the site holds them.
-  const generated = name === TEMPLATE_GENERATED;
+  const generated = name === TEMPLATE_GENERATED || name === TEMPLATE_LEGAL;
   return typedDocument(name, {
     displayDate: !generated && typeof page.displayDate === "string" && page.displayDate !== ""
       ? page.displayDate
@@ -705,7 +745,7 @@ export function contentDocuments(document_) {
 /** Whether a push sends `displayDate` for pages of this wire template type (every template but free-form). */
 export function sentDisplayDate(wireType) {
   const name = templateNameForWireType(wireType);
-  return name !== undefined && name !== TEMPLATE_FREE_FORM && name !== TEMPLATE_GENERATED;
+  return name !== undefined && name !== TEMPLATE_FREE_FORM && name !== TEMPLATE_GENERATED && name !== TEMPLATE_LEGAL;
 }
 
 // The nodes the API accepts in an album or recipe introduction and in a recipe
@@ -903,7 +943,7 @@ export function wireTemplate(document_) {
  * an update, and an empty string means "clear", which is what the API does.
  */
 export function wirePageFields(document_) {
-  if (documentTemplate(document_) === TEMPLATE_FREE_FORM) return {};
+  if ([TEMPLATE_FREE_FORM, TEMPLATE_LEGAL].includes(documentTemplate(document_))) return {};
   return definedEntries([
     ["displayDate", document_.displayDate],
     ["coverImageId", document_.coverImageId],
@@ -1111,6 +1151,10 @@ function parseFlag(fields, key, file) {
 }
 
 /** Generated pages are edited in their .pm.json source only. */
+export function legalMarkdownFault(file) {
+  return fail("pages.legal_markdown", `'${file}' declares the legal template, which has no Markdown form. Use a .pm.json document.`, file);
+}
+
 export function generatedMarkdownFault(file) {
   return fail(
     "pages.generated_markdown",
@@ -1149,6 +1193,7 @@ export function templateFrontMatterFault(template, fieldNames, file) {
  */
 export async function typedDocumentFromMarkdown({ template, fields, markdown, file, convert, resolveImage }) {
   if (template === TEMPLATE_GENERATED) throw generatedMarkdownFault(file);
+  if (template === TEMPLATE_LEGAL) throw legalMarkdownFault(file);
   const displayDate = fields.has("displayDate") ? requireDisplayDate(fields.get("displayDate"), file) : undefined;
   let coverImageId;
   if (fields.has("coverImage")) {