@taprootio/site-authoring 0.14.1 → 0.16.0

package/src/problems.js

@@ -0,0 +1,116 @@
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * Collecting problems instead of stopping at the first (TR01002, TR00823).
+ *
+ * A check that runs over a whole workspace reports every refusal it finds, so
+ * an importer fixing hundreds of converted pages learns them all in one run.
+ * Only `SiteAuthoringError`s are collected: anything else is a defect, and
+ * hiding it inside a list would turn a crash into a refusal.
+ */
+
+/** The parts of a workspace a check reports a problem against. */
+export const CHECK_AREA = Object.freeze({
+  media: "media",
+  pages: "pages",
+  presentation: "presentation",
+  footer: "footer",
+  navigation: "navigation",
+  redirects: "redirects",
+  forms: "forms",
+});
+
+// Kept off the JSON so a problem serializes as plain data, but remembered so a
+// single refusal can be rethrown exactly as it was raised.
+const SOURCE = Symbol("source error");
+
+function withContext(problem, context, error) {
+  const located = {
+    ...(context.area === undefined ? {} : { area: context.area }),
+    ...(context.file === undefined || problem.file !== undefined ? {} : { file: context.file }),
+    ...problem,
+  };
+  if (located.field === located.file) delete located.field;
+  Object.defineProperty(located, SOURCE, { value: error });
+  return located;
+}
+
+/** The problems one refusal stands for: its own list when it carries one, otherwise itself. */
+export function problemsOf(error, context = {}) {
+  const own = Array.isArray(error.problems) && error.problems.length > 0
+    ? error.problems
+    : [{ code: error.code, ...(error.field === undefined ? {} : { field: error.field }), message: error.message }];
+  return own.map((problem) => withContext(problem, context, error));
+}
+
+/**
+ * Runs `action`, adding its refusal to `problems` instead of throwing. Returns
+ * the action's value, or undefined when it refused.
+ */
+export async function collectProblems(problems, context, action) {
+  try {
+    return await action();
+  } catch (error) {
+    if (!(error instanceof SiteAuthoringError)) throw error;
+    problems.push(...problemsOf(error, context));
+    return undefined;
+  }
+}
+
+/**
+ * One refusal for a list of problems. When they all came from one refusal it
+ * is rethrown as raised, alternatives and differences included, so a check
+ * that finds one problem fails exactly as it did before problems were
+ * collected. Otherwise the code, message and field are the first refusal's and
+ * `error.problems` lists every problem.
+ */
+export function problemsError(problems, summary) {
+  const [first] = problems;
+  if (problems.every((problem) => problem[SOURCE] !== undefined && problem[SOURCE] === first[SOURCE])) {
+    return first[SOURCE];
+  }
+  return new SiteAuthoringError(
+    first[SOURCE]?.code ?? first.code,
+    `${summary}: ${problems.length} problems. First: ${first[SOURCE]?.message ?? first.message}`,
+    { field: first[SOURCE]?.field ?? first.field ?? first.file },
+  ).withProblems(problems);
+}
+
+// A whole-workspace check can find thousands of problems. A JSON result keeps
+// as many as fit well inside its 64 KiB bound; stderr lists them all.
+const PROBLEM_BUDGET_BYTES = 40 * 1024;
+
+/** The leading items whose JSON fits `budget` bytes. */
+export function withinByteBudget(items, budget) {
+  const kept = [];
+  let bytes = 0;
+  for (const item of items) {
+    bytes += Buffer.byteLength(JSON.stringify(item), "utf8") + 1;
+    if (bytes > budget) break;
+    kept.push(item);
+  }
+  return kept;
+}
+
+/** The leading problems that fit the result's byte budget, or a smaller one. */
+export function problemsWithinBudget(problems, budget = PROBLEM_BUDGET_BYTES) {
+  return withinByteBudget(problems, Math.min(budget, PROBLEM_BUDGET_BYTES));
+}
+
+/**
+ * Under `apply`, a step refuses to send what its plan did not list: an input
+ * edited, or a site state changed, while an earlier step ran was never reviewed.
+ */
+export function planStale(subject, field) {
+  return new SiteAuthoringError(
+    "apply.plan_stale",
+    `${subject} changed after the plan was made, so this step stopped before sending it. Run 'taproot-site plan' again and `
+      + "apply the new planHash.",
+    { field },
+  );
+}
+
+/** Throws when `problems` is not empty. */
+export function refuseProblems(problems, summary) {
+  if (problems.length > 0) throw problemsError(problems, summary);
+}

package/src/reference-help.js

@@ -6,9 +6,18 @@ import {
   COMPONENT_TYPES,
   getComponentDefinition,
   getComponentPropertyReference,
+  mapComponentImages,
 } from "./content/components.js";
 import { FREE_FORM_SECTION_REGISTRY } from "./content/free-form-sections.js";
-import { CONTENT_ERROR_CODES, CONTENT_LIMITS, MARK_TYPES, NODE_TYPES } from "./content/vocabulary.js";
+import { formatFontCatalog } from "./font-catalog.js";
+import {
+  CONTENT_ERROR_CODES,
+  CONTENT_LIMITS,
+  LINK_REL_TOKENS,
+  LINK_TARGETS,
+  MARK_TYPES,
+  NODE_TYPES,
+} from "./content/vocabulary.js";
 import {
   FIXTURE_CONTRACT_VERSION,
   FIXTURE_DELIVERY_ORIGIN_DOMAIN,
@@ -55,7 +64,12 @@ import {
   REDIRECTS_FILE_NAME,
 } from "./redirects-contract.js";
 import { SETTINGS_GROUPS } from "./settings-catalog.js";
-import { formatTypedPageReference, getTypedPageReference, TYPED_PAGE_TYPES } from "./typed-page-reference.js";
+import {
+  formatTypedPageReference,
+  getTypedPageReference,
+  MARKDOWN_PAGE_TYPES,
+  TYPED_PAGE_TYPES,
+} from "./typed-page-reference.js";
 import { PAGE_TEMPLATES } from "./typed-pages.js";
 import {
   INTERNAL_PAGE_BASELINE_DIRECTORY,
@@ -63,6 +77,7 @@ import {
   NAVIGATION_FILE_NAME,
   PAGE_SOURCE_EXTENSIONS,
   PAGE_WORKSPACE_MODE_EDITABLE,
+  PAGE_WORKSPACE_MODE_METADATA_ONLY,
   PAGES_DIRECTORY,
   pageSourceFormat,
   SETTINGS_DIRECTORY,
@@ -71,7 +86,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 33;
+export const REFERENCE_VERSION = 35;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -408,7 +423,7 @@ export const REFERENCE_TOPICS = Object.freeze([
   Object.freeze({
     name: "media",
     usage: `${CLI_BINARY_NAME} help media`,
-    summary: "Describe media selection, naming, and component-ready output.",
+    summary: "Describe media selection, naming, and where the uploaded media is recorded.",
   }),
   Object.freeze({
     name: "preview",
@@ -445,6 +460,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help import`,
     summary: "Import an existing WordPress site from its export: mapping rules, order of work, and what to report.",
   }),
+  Object.freeze({
+    name: "fonts",
+    usage: `${CLI_BINARY_NAME} help fonts [category]`,
+    summary: "List the font families a published site can load, for the theme's font fields.",
+  }),
   Object.freeze({
     name: "fixture",
     usage: `${CLI_BINARY_NAME} help fixture`,
@@ -462,15 +482,20 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "has said you may; the export names every media URL but carries no image bytes, so downloading originals from "
       + "the old site also needs that permission. Work in a fresh workspace: 'use' the site, then 'pull'.",
       "Order of work: 1 parse the export; 2 classify every item; 3 stage media; 4 write page sources; 5 check every "
-      + "source; 6 pages push; 7 nav.json and nav push; 8 redirects.json and redirects push; 9 approve, deploy "
+      + "source with validate and pages push --dry-run; 6 pages push; 7 nav.json and nav push; 8 redirects.json and redirects push; 9 approve, deploy "
       + "--staging, review it; 10 redirects check and delivery check --staging; 11 deploy --production; 12 delivery "
       + "check --production --url <the origin 'sites' reports as primaryDomain>. Do not promote until the account of unmapped content has been read by the owner.",
       "Classify. Published post: article (the default); recipe when it has an Ingredients list and a Steps list "
       + "(help page recipe); album when it is a gallery with little text (help page album). Published page: a free-form "
-      + "page at its path, children under their parent's path. Never guess a place review: it needs a Taproot "
-      + "placeId this CLI cannot look up, so import the post as an article and list it. Not imported, and always "
+      + "page at its path, children under their parent's path. Never guess a place review: see Place reviews "
+      + "below. Not imported, and always "
       + "listed: drafts, pending, private, scheduled and password-protected items; custom post types; comments; the WordPress front "
       + "page (Taproot seeds its own home page: ask the owner what belongs there).",
+      "Place reviews. A post with a rating and a place becomes a place review when the place can be found: run "
+      + "'places search <name and city>', and if one prediction is plainly the same place, 'places select "
+      + "<googlePlaceId> <sessionToken>' gives the placeId for its front matter (rating: will-return, might-return or "
+      + "wont-return, mapped from the post's own scale). When nothing matches, import it as an article and list it. A travel "
+      + "or food article, or an album, about one place can carry place: <placeId> in its front matter.",
       "Paths and dates. A post's path is '<first category slug, ignoring the default Uncategorized>/<post name>' ('journal/' with no category; a post or page whose slug has no ASCII letters gets a name like post-<id>, listed), a "
       + "page's is its post name under its parents. Keep the original publication date in displayDate (the date "
       + "part of wp:post_date). Categories beyond the first, and all tags, have no Taproot equivalent (tags are "
@@ -488,13 +513,14 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "album when they are the post), links to content you did not import (keep the absolute old link), and images "
       + "on other hosts. Every item goes in the account with its page and what happened to it.",
       "Media. Save each original in the workspace's media/ directory (PNG, JPEG, GIF or WebP up to 32 MiB each; list SVG, AVIF, HEIC and oversized files, which cannot be uploaded; use the original, not "
-      + "the -300x200 thumbnail WordPress also stores), then upload in batches of at most 10 files (conservative: the limit depends on how long the delivery URLs are, and was measured only with short stand-in URLs): 'media upload' "
-      + "prints every file's delivery URLs into a result capped at 64 KiB, and a longer batch uploads everything, "
-      + "writes .taproot-site-media.json, then exits 1 with output.too_large. If that happens the files are already "
-      + "uploaded; run the same paths again (they deduplicate) in smaller batches.",
-      "Check before sending. 'pages push' validates every source before it sends anything but stops at the first "
-      + "problem. On a large import, validate the sources yourself first so you see every problem at once: run the "
-      + "package's validators over each file, or push one page at a time ('pages push <path>').",
+      + "the -300x200 thumbnail WordPress also stores), then run 'media upload' once for the whole media/ directory (at most 500 "
+      + "files a run). It records every file in .taproot-site-media.json and reports counts and a bounded item list; "
+      + "a run that stopped partway is safe to repeat, because identical files deduplicate.",
+      "Check before sending. 'validate' (no credential, no request) checks every page source, media reference and "
+      + "setting in the workspace at once and lists every problem in error.problems with its file, code and field. "
+      + "'pages push --dry-run' then checks the pages against the live site — paths taken, templates, revisions, "
+      + "videos — and sends nothing. 'plan' checks the whole workspace against the site and orders what is left "
+      + "(media, pages, footer, theme, navigation); 'apply --plan <planHash>' runs exactly that plan.",
       "Navigation. A site can have several menus (header, footer): ask which is primary and list the rest. Rebuild it as nav.json after 'pages push', at most three levels deep with canonical UUID ids, 1000 items and 200-character titles (help nav); a label-only dropdown heading (a WordPress '#' link) is a GROUP_HEADER, and a child of an item you cannot map is listed, not promoted (page items carry the resourceId from the "
       + "manifest; a custom link is an EXTERNAL_URL item; a category or tag item has no target, so list it).",
       "Redirects. At most 2000 entries; never redirect to a page you did not push. Every imported page's old path (from its <link>) becomes a 301 to its new path, unless the two "
@@ -568,7 +594,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       `Pull the baseline: ${CLI_BINARY_NAME} pull writes settings/taproot-styles.json with both schemes' complete effective `
       + "themes (the stored theme resolved over the same defaults every consumer renders) beside brand.json, "
       + "site-header.json and site-publishing-preferences.json. Keep that pull as the baseline you edit; never build "
-      + "a theme from memory or from an example. semanticMappings holds only authored pins, listed in explicitMappingTokens. "
+      + "a theme from memory or from an example. semanticMappings holds only authored pins, listed in explicitMappingTokens "
+      + "at the root; a context's pins need no marker. "
       + "site-publishing-preferences.json also carries timeZone, the site's IANA zone (UTC until the owner sets it), "
       + "which decides what \"today\" means for relative form date bounds; it is read-only here, so ask the owner to set "
       + "it in the editor under Site settings.",
@@ -579,10 +606,16 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "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 "
       + "recolor, crop or SVG upload command. Upload each with media upload, then assign lightLogoId and darkLogoId "
-      + "(and brand.faviconId) from the returned image ids so each scheme carries the artwork that reads on its header.",
-      `Validate offline: ${CLI_BINARY_NAME} validate checks the complete pair, the appearance files and the footer against `
-      + "the contracts the site enforces, and warns when a semanticMappings pin repeats the default on a token your "
-      + "roles would have moved (the pin would keep the role from rendering).",
+      + "(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 `
+      + "appearance files, the footer, every page, navigation and redirects — against the contracts the site enforces, "
+      + "lists every problem in error.problems, and warns when a semanticMappings pin repeats the default on a token "
+      + "your roles would have moved (the pin would keep the role from rendering).",
+      `Plan a combined change: when pages, the footer, the theme and navigation all changed, ${CLI_BINARY_NAME} plan `
+      + "checks them against the live site and lists the steps in the order they must run, each ready, blocked or "
+      + `nothing to do; ${CLI_BINARY_NAME} apply --plan <planHash> runs them through the ordinary push verbs and refuses `
+      + "a plan the workspace or the site has moved past. After a failed step, plan again: finished steps read as "
+      + "nothing to do.",
       `Push: ${CLI_BINARY_NAME} theme push --dry-run first: it reads the site and lists the JSON paths at which each `
       + "settings file differs from it, and says whether the baseline pull recorded is still current. Then "
       + `${CLI_BINARY_NAME} theme push saves both themes, the appearance scalars and the ten footer scheme colours in `
@@ -645,10 +678,16 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Run 'redirects check' after staging, or read deploy --staging's automatic check. The Node CLI consumes "
       + "a separate staging handoff and checks the current map at the real edge, using an in-memory cookie and "
       + "manual redirects. It reports each path, HTTP status and Location without following targets.",
+      "The result carries routeCheck (resolved or unresolved) and redirects: { revision, revisionUnchanged, "
+      + "verified, total, checked, matched, failed, items: [{ path, status, location, expectedStatus, matches, "
+      + "error? }], itemsTruncated? }, at the top level of both redirects check and deploy --staging. An entry "
+      + "whose request failed carries error: \"request_failed\". A check that cannot finish at all reports "
+      + "verified: false, an empty items list and redirects.error { code, message }.",
       "verified is true only if every entry matched and the map revision stayed unchanged during the check. "
       + "The check proves the current map at staging, not a historical deployment. A mismatch means the staged "
       + "release does not carry the entry (yet); re-run redirects check after the deployment completes, before promoting. Requests are bounded to 90 seconds, eight at a time; "
-      + "large JSON lists are truncated explicitly with failed entries first. Human output reports every entry.",
+      + "large JSON lists are truncated explicitly with failed entries first (redirects.itemsTruncated). Progress "
+      + "output reports every entry on stderr; --quiet hides it.",
       "stagingPreview.url is a fresh, single-use two-minute handoff, minted after checks. It is emitted only "
       + "in final JSON, excluded from progress and GITHUB_OUTPUT; keep it private. The staging cookie lasts "
       + "five minutes and remains subject to current site/host/credential permission.",
@@ -829,22 +868,23 @@ const WORKFLOW_REFERENCES = Object.freeze({
   }),
   media: Object.freeze({
     title: "Media upload contract",
-    summary: "Upload workspace-root-relative raster files and videos and receive component-ready media objects and video ids.",
+    summary: "Upload workspace-root-relative raster files and videos; images are recorded in .taproot-site-media.json and videos report their ids.",
     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.",
       "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.",
-      "Assign both schemes after uploading: lightLogoId and darkLogoId in settings/taproot-styles.json and brand.faviconId in settings/brand.json take the returned image ids; theme push writes them. See help walkthrough for the full design pass.",
-      "Each result item includes media: { imageId, src, urls, width, height, alt }.",
+      "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.",
       "Place an uploaded video on a page with a video component: a component:video fence in Markdown or a componentBlock of type video, with the returned videoId and optional maxHeight and borderWidth; the poster, caption and shape are the video's own. See help component video. pages push refuses a video that is not in the site's library; validate checks it against fixture.videoIds.",
-      "The same src/urls delivery fields are saved in .taproot-site-media.json for page and component authoring.",
+      "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`,
-      componentMedia: Object.freeze({
+      markdownImage: "media/logo@2x.png",
+      pmJsonImageRecord: Object.freeze({
         imageId: "<image-uuid>",
         src: "<preferred-delivery-url>",
         urls: Object.freeze([Object.freeze({ minWidth: 640, url: "<responsive-delivery-url>" })]),
@@ -872,6 +912,10 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "(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.",
+      "A preview is served on the site's staging address: its own address under Taproot's user-content domain "
+      + "(ontaproot.io in production), or its customer staging domain once that is active. The address has to be "
+      + "live, so a site that has never deployed to staging, or whose staging host is changing, answers "
+      + "preview.staging_unavailable; run 'deploy --staging' once, or wait for the change to finish.",
       "A page path resolves through .taproot-site-manifest.json; a canonical page UUID works directly.",
       "The homepage's manifest path is empty; address it as '/', which resolves to that empty root path.",
       "Preview before approving: approve consumes the draft, so an approved page has no draft left to render and answers preview.no_draft. Review it on staging after a deploy instead.",
@@ -889,7 +933,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
     summary:
       `${FIXTURE_MANIFEST_FILE_NAME} binds a directory laid out like a pulled workspace to deterministic identities, `
       + "so validate can prove it with no credential, no network, and no write.",
-    usage: `${CLI_BINARY_NAME} validate <fixture-directory>`,
+    usage: `${CLI_BINARY_NAME} validate [<fixture-directory>]`,
     details: Object.freeze([
       `Required root fields: ${FIXTURE_REQUIRED_ROOT_FIELDS.join(", ")}.`,
       `Optional root fields: ${FIXTURE_OPTIONAL_ROOT_FIELDS.join(", ")}. Appearance and footer metadata, when present, `
@@ -905,7 +949,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + `sourceFormat, and workspaceMode ${PAGE_WORKSPACE_MODE_EDITABLE}. Album images and the cover image must be `
       + "listed in fixture.imageIds. "
       + "status, hasDraft, isGenerated, and description are recorded by pull and not read: the page key set "
-      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string.",
+      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string. "
+      + `An entry with workspaceMode ${PAGE_WORKSPACE_MODE_METADATA_ONLY} names a page the fixture has no source for, `
+      + "such as a generated section page navigation links to: pageId, resourceId and path, and no file.",
       `file lives under '${PAGES_DIRECTORY}/' and ends in ${PAGE_SOURCE_EXTENSIONS.join(" or ")}; sourceFormat must be `
       + `the format that extension implies (${
         PAGE_SOURCE_EXTENSIONS.map((extension) => `${extension} is '${pageSourceFormat(`page${extension}`)}'`).join(
@@ -928,6 +974,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       }.`,
       `The fixture block carries ${FIXTURE_METADATA_FIELDS.join(", ")}. Every image a page references by imageId must `
       + "be listed in fixture.imageIds, and every absolute delivery URL a page uses must sit on a declared origin. "
+      + "A Markdown media path resolves through the fixture's own .taproot-site-media.json, as in a workspace; "
+      + "without one, no media path resolves. "
       + "videoIds is optional: list the ready videos a page may place with a video component, and validate refuses a "
       + "video component whose videoId is not listed. A live push makes the same check against the site's video library.",
       `Each deliveryOrigins entry is an origin-only HTTPS URL (no path, query, fragment, or credentials) on `
@@ -937,8 +985,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "validate reads the fixture and writes nothing to it. Copy the directory somewhere writable before editing it.",
       "validate --init <new-directory> exports the current pulled workspace as a validated version-7 fixture with "
       + "appearance and footer metadata. Run from the workspace or its configured project; --config may select the source.",
-      "Initialization keeps editable pages of every template as workspace documents and reports excluded metadata-only pages. "
-      + "References to excluded pages must be resolved before the fixture can validate. It never copies credentials, "
+      "Initialization keeps editable pages of every template as workspace documents. A metadata-only page that "
+      + "navigation, the footer or a page links to is kept as a metadata-only entry (initialized.linkedPages); other "
+      + "metadata-only pages are left out (initialized.skippedPages). It never copies credentials, "
       + "internal reconciliation state, or deployment receipts. UUIDs and HTTP(S) origins are replaced with deterministic "
       + "fixture identities and example.test origins; URL credentials, queries and fragments are removed. Authored prose is retained.",
       "The destination must be outside the source workspace and must not exist; its parent must already exist without symlinks. Exports are bounded to 64 MiB. "
@@ -1011,11 +1060,15 @@ export function listComponentTypeReferences() {
   return COMPONENT_TYPES.map(componentSummary);
 }
 
+const EXAMPLE_MEDIA_PATH = "media/photo.webp";
+
 export function getComponentReference(type) {
   const definition = getComponentDefinition(type);
   if (!definition) return undefined;
   const example = definition.example;
-  const markdownExample = `\`\`\`component:${type}\n${JSON.stringify(example, null, 2)}\n\`\`\``;
+  // Markdown names each image by its media path; pages push resolves it (TR01187).
+  const markdownData = mapComponentImages(type, example, (value) => (value === null ? null : EXAMPLE_MEDIA_PATH));
+  const markdownExample = `\`\`\`component:${type}\n${JSON.stringify(markdownData, null, 2)}\n\`\`\``;
   return {
     type,
     displayName: definition.displayName,
@@ -1150,12 +1203,14 @@ function backgroundReference() {
     }),
     scrimOpacityByValue: Object.freeze({ ...BACKGROUND_DEFINITION.fields.scrimStrength.opacityByValue }),
     deliveryUrlPolicy:
-      "Use complete site-owned processed-image results for image and portraitImage. src and every urls[].url must be HTTPS or non-protocol-relative root-relative delivery URLs; credentials, whitespace, controls, and backslashes are rejected.",
+      "In Markdown, give image and portraitImage as media paths recorded by media upload (such as \"media/photo.webp\"); pages push stores the image records. In a .pm.json document they are complete site-owned processed-image records: src and every urls[].url must be HTTPS or non-protocol-relative root-relative delivery URLs; credentials, whitespace, controls, and backslashes are rejected.",
     compactBehavior:
       "At the shared compact breakpoint, portraitImage and portraitFocus replace the landscape image and focus when supplied.",
     example: BACKGROUND_EXAMPLE,
     markdownExample: `:::section ${
-      JSON.stringify({ background: BACKGROUND_EXAMPLE })
+      JSON.stringify({
+        background: { ...BACKGROUND_EXAMPLE, image: "media/class.webp", portraitImage: "media/class-portrait.webp" },
+      })
     }\n## Practice with us\n\nFind your next class.\n:::`,
   });
 }
@@ -1185,11 +1240,11 @@ function decorationReference() {
     additionalProperties: false,
     fields: sectionAttributeReference().find((attr) => attr.name === "decoration").fields,
     deliveryUrlPolicy:
-      "Use the complete site-owned processed-image result from media upload. src and every urls[].url must be HTTPS or non-protocol-relative root-relative delivery URLs; credentials, whitespace, controls, and backslashes are rejected.",
+      "In Markdown, give image as a media path recorded by media upload (such as \"media/starburst.webp\"); pages push stores the image record. In a .pm.json document it is the complete site-owned processed-image record: src and every urls[].url must be HTTPS or non-protocol-relative root-relative delivery URLs; credentials, whitespace, controls, and backslashes are rejected.",
     tintTokens: Object.freeze({ ...DECORATION_DEFINITION.fields.tint.tokenByValue }),
     example: DECORATION_EXAMPLE,
     markdownExample: `:::section ${
-      JSON.stringify({ decoration: DECORATION_EXAMPLE })
+      JSON.stringify({ decoration: { ...DECORATION_EXAMPLE, image: "media/starburst.webp" } })
     }\n## Rooted in warmth\n\nMove with confidence.\n:::`,
     maskGuidance:
       "Use a transparent PNG or WebP whose alpha channel contains only the mark. The active section context supplies the tint in both schemes.",
@@ -1478,6 +1533,31 @@ const FREE_FORM_REFERENCE = Object.freeze({
         + "refuses before changing anything under pages/ and preserves the site's version as internal state. A "
         + "locally edited .pm.json is kept rather than overwritten, and only collides when the site changed too.",
       conflictError: "pages.pull_conflict",
+      metadata:
+        "A .pm.json page's title, path and description live in the manifest, not the file. Change the title or "
+        + "description with pages meta set <path> --title/--description; a Markdown page keeps them in its front "
+        + "matter. pull keeps such an edit until pages push sends it, and a site edit to the same page is a "
+        + "pages.pull_conflict. A description over 160 characters is warned about (search results cut it off); "
+        + "over 1000 is refused.",
+      authorship:
+        "Pages are authorless by default: a page created without an author publishes with no byline, and pages push "
+        + "lists the pages it created that way in pages.authorless. Name an author with author: in the front matter "
+        + "(every template) or, for a .pm.json page, pages meta set <path> --author. An author is a site author "
+        + "without a Taproot account, named by handle (jane-doe), or a site member who can create pages, named by "
+        + "email address. authors list shows who can be named and rewrites authors.json; authors add <handle> "
+        + "--name <name> [--email <address>] creates a site author, whose address stays private. A site author's "
+        + "name appears on the byline and in structured data, with no profile link or follow button. authors add "
+        + "again with the same handle and name succeeds (existing: true); another name for a taken handle is "
+        + "authors.handle_taken. Only the CLI assigns authors, and only to a page that has none. authors.json is as old "
+        + "as the last pull or authors list, so offline commands (validate, pages meta set) only warn "
+        + "(pages.author_unverified) about a name it lacks; pages push and plan read the site's current list once on a "
+        + "miss and refuse only a name the site lacks. The CLI only fills a page that has no author: a different one "
+        + "already on the page is pages.author_conflict, which names the way out (pages meta set <path> --author "
+        + "<the site's author> for a .pm.json page, the author: line for Markdown, or pages meta set <path> --author "
+        + "\"\" to drop an author that was never sent), naming the author a page already has changes nothing, and a "
+        + "name that is unknown or belongs to a member who cannot create pages is pages.author_unknown either way. "
+        + "Text that is neither a handle nor an address is pages.author_invalid.",
+      authorshipErrors: Object.freeze(["pages.author_invalid", "pages.author_unknown", "pages.author_conflict"]),
       conflictDetail:
         "A reported conflict names the JSON paths at which the site's document differs from the copy this workspace "
         + "last reconciled with, in error.differences, which carries three states. Absent: the two documents were "
@@ -1529,13 +1609,23 @@ const FREE_FORM_REFERENCE = Object.freeze({
             inheritedForTracked: true,
             defaultForNew: "",
           }),
+          Object.freeze({
+            name: "author",
+            type: "string",
+            requiredForNew: false,
+            inheritedForTracked: true,
+            defaultForNew: "",
+            description:
+              "A site author's handle (jane-doe) or a member's email address. Omit it for an authorless page; it "
+              + "only fills a page that has none, and never replaces one.",
+          }),
           Object.freeze({
             name: "template",
             type: "string",
             requiredForNew: false,
             inheritedForTracked: false,
             defaultForNew: "free-form",
-            description: `Other templates: ${TYPED_PAGE_TYPES.join(", ")}; see '${CLI_BINARY_NAME} help pages'.`,
+            description: `Other templates: ${MARKDOWN_PAGE_TYPES.join(", ")}; see '${CLI_BINARY_NAME} help pages'.`,
           }),
         ]),
       }),
@@ -1556,6 +1646,25 @@ const FREE_FORM_REFERENCE = Object.freeze({
     root: Object.freeze({ type: "doc", content: "array of supported block nodes" }),
     nodes: NODE_TYPES,
     marks: MARK_TYPES,
+    // TR01190: what a link mark's rel and target publish as.
+    links: Object.freeze({
+      markdown: '[Shop](https://shop.example){rel="sponsored nofollow" target="_blank"}',
+      rel: LINK_REL_TOKENS,
+      target: LINK_TARGETS,
+      default:
+        "A link with no rel is followed, whether it goes to this site or another. Choose nofollow, sponsored "
+        + "(paid or affiliate), or ugc (written by someone else) for a link that should not pass endorsement; the "
+        + "choice is per link, internal links included.",
+      markdownRule:
+        'Write {rel="…" target="…"} directly after the link\'s closing parenthesis: either attribute alone or both, '
+        + 'each double-quoted once. rel is space-separated; target="_blank" opens a new tab.',
+      pmJson:
+        'In .pm.json, a link mark carries attrs.rel (a space-separated string, or null) and attrs.target ("_blank" '
+        + 'opens a new tab and publishes with noopener noreferrer added, "_self" or null keeps the same tab).',
+      refusals:
+        `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.`,
+    }),
     componentNode: Object.freeze({
       type: "componentBlock",
       attrs: Object.freeze({
@@ -1665,7 +1774,8 @@ function schemaConstraints(schema) {
 
 function formatSchemaLine(name, schema, required, indent) {
   const constraints = schemaConstraints(schema);
-  return `${indent}${name.padEnd(Math.max(1, 28 - indent.length))} ${schemaLabel(schema)}; ${
+  const label = schema.markdownType ? "media path | null in Markdown; object | null in .pm.json" : schemaLabel(schema);
+  return `${indent}${name.padEnd(Math.max(1, 28 - indent.length))} ${label}; ${
     required ? "required" : "optional"
   }${constraints.length > 0 ? `; ${constraints.join("; ")}` : ""}`;
 }
@@ -1675,7 +1785,7 @@ function nestedSchemaLines(schema, path, indent = "    ") {
   const valuePath = schema.type === "array" ? `${path}[]` : path;
   if (!valueSchema?.properties) return [];
 
-  const lines = [];
+  const lines = valueSchema.markdownType ? [`${indent}${valuePath} in a .pm.json document:`] : [];
   for (const property of valueSchema.properties) {
     const propertyPath = `${valuePath}.${property.name}`;
     lines.push(formatSchemaLine(propertyPath, property.schema, property.required, indent));
@@ -1719,9 +1829,11 @@ function formatSectionAttr(attr) {
 
 function formatRegistryField(field, indent = "  ") {
   if (field.type === "processed-image") {
-    return `${indent}${field.name.padEnd(Math.max(1, 20 - indent.length))} processed-image${
+    return `${indent}${field.name.padEnd(Math.max(1, 20 - indent.length))} media path${
+      field.nullable ? " | null" : ""
+    } in Markdown; processed-image${
       field.nullable ? " | null" : ""
-    }; ${field.required ? "required" : `default ${JSON.stringify(field.default)}`}; required keys ${
+    } in .pm.json; ${field.required ? "required" : `default ${JSON.stringify(field.default)}`}; .pm.json required keys ${
       field.requiredKeys.join(", ")
     }; optional keys ${
       field.optionalKeys.join(", ")
@@ -1761,6 +1873,8 @@ function formatDesignRecipe(recipe) {
 
 export function formatReferenceResult(result) {
   switch (result.topic) {
+    case "fonts":
+      return formatFontCatalog(result.fonts);
     case "topics":
       return `Usage: ${CLI_BINARY_NAME} help <topic> [name] [--json]\n\nReference topics:\n${
         result.topics.map((topic) => `  ${topic.usage.padEnd(48)} ${topic.summary}`).join("\n")
@@ -1802,13 +1916,15 @@ export function formatReferenceResult(result) {
         page.workspace.formats.map((format) => `  ${format.extension.padEnd(9)} ${format.purpose}`).join("\n")
       }\n\nOne source per page:\n  rule                  ${sourceRule.rule}\n  manifest fields       ${
         sourceRule.manifestFields.join(", ")
-      }\n  pull                  ${sourceRule.pull}\n  internal state        ${sourceRule.internalState}\n  format change         ${sourceRule.formatChange} (${sourceRule.formatChangeError})\n  renamed source        ${sourceRule.renamedSource} (${sourceRule.renamedSourceError})\n  conflicts             ${sourceRule.conflict} (${sourceRule.conflictError})\n  conflict detail       ${sourceRule.conflictDetail}\n  push conflicts        ${sourceRule.pushConflict} (${sourceRule.pushConflictError})\n  revision              ${sourceRule.revisionSource}\n  recovery              ${sourceRule.conflictRecovery}\n  push selection        ${sourceRule.pushSelection}\n\nSystem pages: ${page.workspace.systemPages}\n\nMarkdown front matter:\n${
+      }\n  pull                  ${sourceRule.pull}\n  internal state        ${sourceRule.internalState}\n  format change         ${sourceRule.formatChange} (${sourceRule.formatChangeError})\n  renamed source        ${sourceRule.renamedSource} (${sourceRule.renamedSourceError})\n  conflicts             ${sourceRule.conflict} (${sourceRule.conflictError})\n  conflict detail       ${sourceRule.conflictDetail}\n  push conflicts        ${sourceRule.pushConflict} (${sourceRule.pushConflictError})\n  revision              ${sourceRule.revisionSource}\n  recovery              ${sourceRule.conflictRecovery}\n  push selection        ${sourceRule.pushSelection}\n  authors               ${sourceRule.authorship} (${sourceRule.authorshipErrors.join(", ")})\n\nSystem pages: ${page.workspace.systemPages}\n\nMarkdown front matter:\n${
         markdownFormat.metadata.map(formatMetadata).join("\n")
       }\n\nDocument root: { "type": "doc", "content": [...] }\nSupported nodes: ${
         page.document.nodes.join(", ")
       }\nSupported marks: ${
         page.document.marks.join(", ")
-      }\n\nTop-level section container:\n${page.sections.example}\n\nSection attributes:\n${
+      }\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${
         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/session.js

@@ -21,6 +21,7 @@ import {
   updateCredentialMetadata,
 } from "./credentials.js";
 import { SiteAuthoringError } from "./errors.js";
+import { withinByteBudget } from "./problems.js";
 import { exchangeSiteAuthoringToken, withRefusalGuidance } from "./api.js";
 import { ApiError, SiteApiClient } from "./transport.js";
 import { readStoredApiBaseUrl } from "./settings.js";
@@ -125,6 +126,9 @@ function siteMissingError() {
 }
 
 async function loadConfig(invocation) {
+  // apply hands its steps the configuration it planned with, so a
+  // taproot-site.json edited mid-apply is not read by a later step.
+  if (invocation.resolvedConfig !== undefined) return invocation.resolvedConfig;
   return await loadSiteConfig({
     cwd: invocation.cwd ?? process.cwd(),
     configPath: invocation.configPath,
@@ -552,6 +556,15 @@ export function boundedList(values, maximum) {
     : { items, count: values.length, truncated: true };
 }
 
+/**
+ * The leading values whose JSON fits `budget` bytes, for a list whose entries
+ * vary in length: a count bound alone can still pass the 64 KiB result bound.
+ */
+export function boundedByBytes(values, budget) {
+  const items = withinByteBudget(values, budget);
+  return items.length === values.length ? { items } : { items, truncated: true };
+}
+
 export function successResult(verb, siteId, payload = {}) {
   return {
     schemaVersion: RESULT_SCHEMA_VERSION,