@taprootio/site-authoring 0.20.0 → 0.21.0

package/src/cli.js

@@ -1,3 +1,5 @@
+import { normalizeStagingReviewPath } from "./api.js";
+import { parseCliVersion } from "./cli-release.js";
 import { CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS, CAPABILITY_DESIGN } from "./capabilities.js";
 import { capabilitiesForSurface } from "./surface.js";
 import {
@@ -22,6 +24,7 @@ import {
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
   VERB_STAGING_REVIEW,
+  VERB_CHANGELOG,
   VERB_ENV,
   VERB_FOOTER_PUSH,
   VERB_FORMS_PULL,
@@ -69,6 +72,7 @@ import {
   getDesignBlueprint,
   getFooterReference,
   getPageTypeReference,
+  getSettingsReference,
   getThemeReference,
   getWorkflowReference,
   listComponentTypeReferences,
@@ -118,7 +122,12 @@ const VERBS = Object.freeze([
       + "rather than one per run. A pulled workspace is checked offline against the pages (generated ones included, "
       + "so navigation to a section or tag page resolves), images, and baselines its manifests recorded at the pull. "
       + "A link whose address is only http(s):// plus its own text (left by older editor autolinking) is reported in "
-      + "linkWarnings without refusing; pages push reports the same for the pages it sends. This proves local structure and semantics only. It does not prove "
+      + "linkWarnings without refusing; pages push reports the same for the pages it sends. "
+      + "The site checks that can run offline are reported in findings (a rule id, severity, file, and the value "
+      + "found, such as link.page_missing for a link to a page the workspace does not have) and never refuse a "
+      + "warning; siteChecks.checkedBySite names the rules that need the site's own records (images, forms), which "
+      + "'status' reports under siteHealth. A redirect source the site would refuse names its rule in "
+      + "error.problems[].rule. This proves local structure and semantics only. It does not prove "
       + "authorization, live site ownership, concurrency, persisted round trips, or rendering: 'plan' checks a "
       + "workspace against the live site, and 'pages push --dry-run' does that for pages alone. "
       + `See '${CLI_BINARY_NAME} help fixture' for the fixture manifest contract and for the path of the complete `
@@ -200,6 +209,21 @@ const VERBS = Object.freeze([
       + "its value. The sign-in secret is never printed; the credential is named by id and display prefix, which are "
       + "what an owner needs to revoke it.",
   },
+  {
+    name: VERB_CHANGELOG,
+    tokens: ["changelog"],
+    summary: "List what changed in each CLI release, offline.",
+    credentialFree: true,
+    configFree: true,
+    offline: true,
+    sinceOption: true,
+    note: "Only the latest CLI is accepted, so an upgrade can be forced at any time. After one, run "
+      + "'changelog --since <the version you upgraded from>' to see every release's note and the behavior it changed, "
+      + "and which help topics (help <topic>) to read again. With no --since it prints the installed release's entry. "
+      + "It reads the package's own record, needs no sign-in or site, and still runs when this CLI is outdated. "
+      + "The result lists entries newest first, each { version, note, behavior, help }; complete is false when "
+      + "--since starts before the oldest release the record covers. 'status' reports the installed release's note.",
+  },
   {
     name: VERB_ENV,
     tokens: ["env"],
@@ -440,9 +464,12 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["redirects", "check"],
     summary: "Check the current redirect map through the authenticated staging edge.",
+    handoffOptions: true,
     note: "Reports each entry's path, HTTP status and Location in redirects.items, and redirects.verified, without "
       + "following redirects. A redirect is live only with the release that carries it, so this reads the staged release. "
-      + "The result includes a fresh single-use staging handoff in stagingPreview.url; keep it private.",
+      + "The check authenticates with its own handoff and never reports it. The result carries no review URL unless "
+      + "you pass --handoff, which adds a fresh single-use one in stagingPreview.url (keep it private); "
+      + "'staging review' mints one at any time.",
   },
   {
     name: VERB_REDIRECTS_PULL,
@@ -589,11 +616,19 @@ const VERBS = Object.freeze([
     tokens: ["deploy"],
     summary: "Deploy to staging, or promote staging to production.",
     target: true,
-    note: "deploy --staging returns a single-use review handoff in stagingPreview.url, on a managed Docs site too, "
-      + "where it stages settings only: open the URL once, then switch the site's theme toggle to review both "
-      + "schemes before deploy --production. If no handoff could be minted, stagingPreview.reason names why and "
+    handoffOptions: true,
+    note: "deploy --staging does not report a review URL, because the URL is a live single-use credential and this "
+      + "JSON is often saved to logs. Run 'staging review' to mint one, or pass --handoff to get a fresh "
+      + "single-use one in stagingPreview.url (on a managed Docs site too, where it stages settings only): open it "
+      + "once, then switch the site's theme toggle to review both schemes before deploy --production. Without "
+      + "--handoff, stagingPreview.reason is staging.handoff_not_requested and stagingPreview.recovery names the "
+      + "command. If a requested handoff could not be minted, stagingPreview.reason names why and "
       + "stagingPreview.recovery the next step; 'staging review' mints another. On a Standard site the result also "
-      + "carries the automatic redirect check: routeCheck and redirects (see 'help redirects').",
+      + "carries the automatic redirect check: routeCheck and redirects (see 'help redirects'). The edge can keep "
+      + `serving the previous release for up to ${LIMITS.stagingPropagationCeilingSeconds} seconds after a deployment completes, so a Standard site's `
+      + "deploy --staging waits until staging serves the new release and reports stagingServed: state served, "
+      + "propagating (still the previous release at the bound) or unverified (the change cannot be attributed to this deployment, or the last read did not name the previous release), "
+      + "with the time to wait or the seconds waited.",
   },
   {
     name: VERB_PREVIEW_PAGE,
@@ -653,20 +688,23 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_DEPLOYMENTS],
     tokens: ["staging", "review"],
     summary: "Mint a fresh single-use review handoff for the site's staging host.",
+    reviewPath: true,
     note: "The handoff URL is reported only in the final JSON as stagingPreview.url, is single-use, and expires two "
-      + "minutes after it is minted; keep it private. Open it once, then use the site's theme toggle to review both "
-      + "schemes. This is the recovery when deploy --staging could not mint a handoff, on a managed Docs site too.",
+      + "minutes after it is minted; keep it private. --path <page> opens the review on that page instead of the "
+      + "home page: a page path as 'pull' records it ('about', '/posts/one'), optionally with a query. Open it once, then use the site's theme toggle to review both "
+      + "schemes. deploy --staging and redirects check report no review URL unless you pass --handoff, so this is "
+      + "the usual way to get one, on a managed Docs site too.",
   },
   {
     name: VERB_STATUS,
     surface: SURFACE_DOCS_PRESENTATION,
     // Readiness and the deployment log are Deployments; the image list is
-    // Content, as is the broken-reference report.
+    // Content, as is the site-health read.
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["status"],
     summary:
-      "Report the platform authoring switch, CLI release, deployments, readiness, image processing, and broken references.",
-    note: "Broken references list pages with missing image IDs or page paths in their latest editable body."
+      "Report the platform authoring switch, CLI release, deployments, readiness, image processing, and site health.",
+    note: "Site health lists the site checks' findings (a rule id, severity, page, and the value found) for the latest editable body of each page."
       + " Content permission is required; a refused or failed read fails status rather than reporting a clean site.",
   },
 ]);
@@ -733,7 +771,8 @@ credentials, and it expires 24 hours after it is issued.
 
 Verbs write one JSON result to stdout and human progress to stderr. validate,
 help, whoami, and env are offline and read-only. login, logout, sites, use,
-whoami, and env need no configuration and no site. The offline help family is
+whoami, and env need no configuration and no site. So does changelog, which
+also still runs when this CLI is outdated. The offline help family is
 human-readable by default; add --json for stable reference data. Exit codes: 0
 success, 1 failure, 2 usage fault.
 
@@ -817,6 +856,18 @@ function verbHelp(verb) {
   --production     Promote the completed staging deployment to production.
   --allow-failed-preview  Explicitly override the matching candidate's failed preview.`
     : "";
+  const handoffOption = verb.handoffOptions
+    ? `\n  --handoff        Also mint a fresh single-use review URL and report it in stagingPreview.url.
+  --no-handoff     Report no review URL (the default); accepted so scripts can say so explicitly.`
+    : "";
+  const sinceOption = verb.sinceOption
+    ? "\n  --since <version>  List the releases after this one, up to the installed release."
+    : "";
+  const reviewPathOption = verb.reviewPath
+    ? "\n  --path <page>    Open the review on this page instead of the home page, such as 'about' or '/posts/one'."
+    : verb.handoffOptions
+    ? "\n  --review-path <page>  With --handoff, open the review URL on this page instead of the home page."
+    : "";
   const metaOptions = verb.metaOptions
     ? `\n  --title <text>       The page's title.
   --description <text> The page's description for search results and link previews; '' clears it.
@@ -907,7 +958,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
+${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
 `;
 }
 
@@ -968,6 +1019,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "preview"
       || topic === "theme"
       || topic === "appearance"
+      || topic === "settings"
       || topic === "footer"
       || topic === "fixture"
       || topic === "redirects"
@@ -1070,6 +1122,8 @@ function referenceResult(parsed) {
       return { ...result, topic: "presentation", referenceKind: "theme", reference: getThemeReference() };
     case "appearance":
       return { ...result, topic: "presentation", referenceKind: "appearance", reference: getAppearanceReference() };
+    case "settings":
+      return { ...result, topic: "presentation", referenceKind: "settings", reference: getSettingsReference() };
     case "footer":
       return { ...result, topic: "presentation", referenceKind: "footer", reference: getFooterReference() };
     default:
@@ -1249,6 +1303,9 @@ function parseArguments(arguments_) {
   let propagationWaitSeconds;
   let browser;
   let allowFailedPreview = false;
+  let handoff;
+  let reviewPath;
+  let since;
   let dryRun = false;
   let json = false;
   let keyName;
@@ -1314,6 +1371,42 @@ function parseArguments(arguments_) {
       allowFailedPreview = true;
       continue;
     }
+    if (verb.handoffOptions && (argument === "--handoff" || argument === "--no-handoff")) {
+      if (handoff !== undefined) {
+        throw usageError(
+          handoff === (argument === "--handoff") ? "cli.duplicate_option" : "cli.handoff_conflict",
+          handoff === (argument === "--handoff")
+            ? `${argument} may be supplied only once.`
+            : "--handoff and --no-handoff cannot be used together.",
+        );
+      }
+      handoff = argument === "--handoff";
+      continue;
+    }
+    if ((verb.reviewPath && argument === "--path") || (verb.handoffOptions && argument === "--review-path")) {
+      if (reviewPath !== undefined) {
+        throw usageError("cli.duplicate_option", `${argument} may be supplied only once.`);
+      }
+      // An option-like value would otherwise become the page '/--json' and mint a handoff to a 404.
+      const candidate = rest[index + 1];
+      reviewPath = normalizeStagingReviewPath(typeof candidate === "string" && candidate.startsWith("--") ? "" : candidate);
+      index += 1;
+      continue;
+    }
+    if (verb.sinceOption && argument === "--since") {
+      if (since !== undefined) throw usageError("cli.duplicate_option", "--since may be supplied only once.");
+      const candidate = rest[index + 1];
+      if (parseCliVersion(candidate) === undefined) {
+        throw usageError(
+          "changelog.since_invalid",
+          "--since requires a version such as 0.20.0 (the version you upgraded from).",
+          { field: "since" },
+        );
+      }
+      since = candidate;
+      index += 1;
+      continue;
+    }
     if (verb.dryRun && argument === "--dry-run") {
       if (dryRun) throw usageError("cli.duplicate_option", "--dry-run may be supplied only once.");
       dryRun = true;
@@ -1394,6 +1487,16 @@ function parseArguments(arguments_) {
       `${verb.tokens.join(" ")} requires exactly one of --staging or --production.`,
     );
   }
+  if (verb.handoffOptions && reviewPath !== undefined && handoff !== true) {
+    throw usageError(
+      "cli.review_path_requires_handoff",
+      "--review-path chooses the page a --handoff review URL opens on; pass --handoff with it, or use 'staging review --path'.",
+      { field: "reviewPath" },
+    );
+  }
+  if (handoff === true && verb.target && deployTarget === DEPLOY_TARGET_PRODUCTION) {
+    throw usageError("cli.handoff_target", "--handoff applies only to deploy --staging.", { field: "handoff" });
+  }
   if (verb.positionals === "fixturePath" && (positionals.length > 1 || (init && positionals.length !== 1))) {
     throw usageError(
       "validate.fixture_path_invalid",
@@ -1507,6 +1610,9 @@ function parseArguments(arguments_) {
     quiet,
     deployTarget,
     allowFailedPreview,
+    ...(handoff === undefined ? {} : { handoff }),
+    ...(reviewPath === undefined ? {} : { reviewPath }),
+    ...(since === undefined ? {} : { since }),
     ...(deliveryUrl === undefined ? {} : { deliveryUrl }),
     ...(propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds }),
     ...(browser === undefined ? {} : { browser }),
@@ -1599,6 +1705,9 @@ export async function runCli({
       configPath: parsed.configPath,
       deployTarget: parsed.deployTarget,
       allowFailedPreview: parsed.allowFailedPreview,
+      ...(parsed.handoff === undefined ? {} : { handoff: parsed.handoff }),
+      ...(parsed.reviewPath === undefined ? {} : { reviewPath: parsed.reviewPath }),
+      ...(parsed.since === undefined ? {} : { since: parsed.since }),
       init: parsed.init,
       quiet: parsed.quiet,
       dryRun: parsed.dryRun,

package/src/constants.js

@@ -106,6 +106,12 @@ export const VERB_STAGING_REVIEW = "staging review";
 export const VERB_SITES = "sites";
 export const VERB_USE = "use";
 export const VERB_WHOAMI = "whoami";
+export const VERB_CHANGELOG = "changelog";
+
+/** The command that lists what changed since a version, for the CLI to name after an upgrade (TR01225). */
+export function changelogCommandSince(version) {
+  return `${CLI_BINARY_NAME} ${VERB_CHANGELOG} --since ${version}`;
+}
 export const VERB_PLAN = "plan";
 export const VERB_APPLY = "apply";
 export const VERB_PLACES_SEARCH = "places search";
@@ -256,6 +262,19 @@ export const LIMITS = Object.freeze({
   deploymentMilliseconds: 30 * 60_000,
   previewMilliseconds: 5 * 60_000,
   pollIntervalMilliseconds: 2_000,
+  // How long after a staging deployment completes the edge can still serve the
+  // previous release (TR01236): up to a minute for Workers KV to propagate the
+  // route, plus the Worker's 30-second KV read cache and 30-second isolate cache
+  // (docs/operations/published-site-worker-runbook.md, "Route resolution
+  // freshness budget"). The wait is longer than the ceiling so one slow read does
+  // not turn a propagating release into a false warning.
+  stagingPropagationCeilingSeconds: 120,
+  stagingServedMilliseconds: 180_000,
+  stagingServedPollMilliseconds: 3_000,
+  // Two reads in a row, because each read lands on one cached copy of the route.
+  stagingServedConfirmations: 2,
+  // The review notice sits at the end of the page, so the whole document is read.
+  stagingServedPageBytes: 4 * 1024 * 1024,
   requestAttempts: 4,
   uploadAttempts: 4,
   diagnosticScalars: 2_000,

package/src/errors.js

@@ -130,6 +130,8 @@ export class SiteAuthoringError extends Error {
     this.previewDiagnostic = normalizePreviewDiagnostic(options.previewDiagnostic);
     this.field = typeof options.field === "string" ? sanitizeDiagnostic(options.field, "") : undefined;
     this.status = typeof options.status === "string" ? sanitizeDiagnostic(options.status, "") : undefined;
+    // The site check rule (shared/site-check-rules.json) this refusal comes from, when it comes from one.
+    this.rule = typeof options.rule === "string" && /^[a-z0-9_.]+$/u.test(options.rule) ? options.rule : undefined;
     this.alternatives = Array.isArray(options.alternatives)
       ? options.alternatives
         .filter((value) => typeof value === "string")
@@ -191,6 +193,7 @@ export class SiteAuthoringError extends Error {
         ...(typeof problem.file === "string" ? { file: sanitizeDiagnostic(problem.file, "") } : {}),
         code: /^[a-z0-9_.-]+$/u.test(problem.code) ? problem.code : "site.failed",
         ...(typeof problem.field === "string" ? { field: sanitizeDiagnostic(problem.field, "") } : {}),
+        ...(typeof problem.rule === "string" && /^[a-z0-9_.]+$/u.test(problem.rule) ? { rule: problem.rule } : {}),
         message: sanitizeDiagnostic(problem.message),
       }));
     this.problemCount = list.length;

package/src/footer-contract.js

@@ -278,11 +278,13 @@ function richText(value, path, maximumLength, maximumParagraphs, knownPageResour
       if (text.length === 0) continue;
       totalLength += text.length;
       totalRuns += 1;
+      // A style flag that is off is left out, so a run carries only what it sets and a hand-written
+      // file matches what pull writes (TR01232).
       normalizedRuns.push({
         text,
-        bold: boolean(run.bold, false, `${runPath}.bold`),
-        italic: boolean(run.italic, false, `${runPath}.italic`),
-        underline: boolean(run.underline, false, `${runPath}.underline`),
+        ...(boolean(run.bold, false, `${runPath}.bold`) ? { bold: true } : {}),
+        ...(boolean(run.italic, false, `${runPath}.italic`) ? { italic: true } : {}),
+        ...(boolean(run.underline, false, `${runPath}.underline`) ? { underline: true } : {}),
         ...(run.link === undefined || run.link === null
           ? {}
           : { link: inlineLink(run.link, `${runPath}.link`, knownPageResourceIds, tolerateStoredValues) }),

package/src/index.js

@@ -14,3 +14,4 @@ export {
   getFooterReference,
   getThemeReference,
 } from "./presentation-reference.js";
+export { getSettingsReference } from "./setting-reference.js";

package/src/output.js

@@ -3,12 +3,14 @@ import { constants as fsConstants } from "node:fs";
 import { lstat, open } from "node:fs/promises";
 
 import {
+  changelogCommandSince,
   CLI_BINARY_NAME,
   CLI_NAME,
   CLI_VERSION,
   GITHUB_OUTPUT_KEY_PREFIX,
   GITHUB_OUTPUT_RESULT_KEY,
   LIMITS,
+  REFUSAL_CLI_OUTDATED,
   REFUSAL_UNCLASSIFIED,
   RESULT_SCHEMA_VERSION,
 } from "./constants.js";
@@ -37,6 +39,7 @@ export function failureResult(error) {
     error: { code: error.code },
   };
   if (error.field) result.error.field = error.field;
+  if (error.rule) result.error.rule = error.rule;
   if (error.details?.length) result.error.details = error.details;
   if (error.status) result.error.status = error.status;
   if (Array.isArray(error.alternatives) && error.alternatives.length > 0) {
@@ -67,6 +70,12 @@ export function failureResult(error) {
   if (previewRecovery) result.error.preview = previewRecovery;
   const refusal = typeof error.refusalKind === "function" ? error.refusalKind() : undefined;
   if (typeof refusal === "string" && refusal !== REFUSAL_UNCLASSIFIED) result.error.refusal = refusal;
+  if (refusal === REFUSAL_CLI_OUTDATED) {
+    const latestVersion = typeof error.latestCliVersion === "function" ? error.latestCliVersion() : error.latestVersion;
+    if (typeof latestVersion === "string") result.error.latestVersion = latestVersion;
+    // What to run once the upgrade is done, so the agent need not diff the help topics.
+    result.error.changelogCommand = changelogCommandSince(CLI_VERSION);
+  }
   return result;
 }
 

package/src/presentation-reference.js

@@ -44,6 +44,12 @@ import {
   REQUIRED_THEME_PROPERTIES,
   validateAndLintThemePair,
 } from "./theme-validation.js";
+import {
+  describeSettingField,
+  formatSettingsReference,
+  PAGE_BACKGROUND_IMAGE_RENDERING,
+  PAGE_BACKGROUND_VERSUS_CANVAS,
+} from "./setting-reference.js";
 import {
   SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
   SETTINGS_TYPE_TAPROOT_STYLES,
@@ -273,14 +279,23 @@ const THEME_GROUPS = Object.freeze([
   }),
   Object.freeze({
     name: "surface-assets",
-    summary: "Preserve pulled asset fields; use appearance image ids for site-owned canvas art.",
+    summary:
+      "Preserve pulled asset fields; use appearance image ids for the logos, favicon and canvas image. The page "
+      + "background image is a theme field behind the page content, unlike the canvas image, which paints only the "
+      + "side margins (help settings has both).",
     fields: Object.freeze([
       themeField("stylesheets", "Agent-authored site themes must keep this exact array empty.", { exact: [] }),
       themeField(
         "pageBackgroundImage",
-        "CSS background-image; the complete Taproot workspace includes an empty value.",
+        "CSS background-image (the app's Page style > Background image). " + PAGE_BACKGROUND_IMAGE_RENDERING
+          + " Today it is a CSS url(...) of a delivered image, the src that .taproot-site-media.json records; it tiles "
+          + "at the image's natural pixel size from the top-left. The complete Taproot workspace includes an empty value.",
+      ),
+      themeField(
+        "pageBackgroundImageOpacity",
+        "How strongly the page background image shows, from 0 (invisible) to 1 (fully opaque).",
+        { minimum: 0, maximum: 1 },
       ),
-      themeField("pageBackgroundImageOpacity", "Page background opacity.", { minimum: 0, maximum: 1 }),
       themeField("boxBackgroundImage", "Optional inherited box-surface background image."),
       themeField("boxBackgroundImageOpacity", "Optional box background opacity.", { minimum: 0, maximum: 1 }),
       themeField("vellumOpacity", "Optional modal-vellum opacity.", { minimum: 0, maximum: 1 }),
@@ -418,6 +433,9 @@ export function getThemeReference() {
   };
 }
 
+// "linkHoverColor" reads "link hover color", so a new footer color token needs no second table.
+const footerColorLabel = (name) => name.replace(/([A-Z])/gu, " $1").toLowerCase();
+
 function appearanceColorReference(definition) {
   return definition.type === "appearance-color"
     ? {
@@ -432,6 +450,7 @@ export function getAppearanceReference() {
   const scalarFields = APPEARANCE_SCALAR_FIELDS.map((field) => ({
     file: APPEARANCE_FILES[field.settingsType],
     path: "settings." + field.name,
+    ...describeSettingField(field.settingsType, field.name),
     type: field.type,
     ...(field.values ? { values: field.values } : {}),
     ...(field.minimum !== undefined ? { minimum: field.minimum, maximum: field.maximum } : {}),
@@ -447,27 +466,36 @@ export function getAppearanceReference() {
       {
         file: APPEARANCE_FILES[SETTINGS_TYPE_TAPROOT_STYLES],
         path: "settings.lightTheme",
+        ...describeSettingField(SETTINGS_TYPE_TAPROOT_STYLES, "lightTheme"),
         type: "complete-espalier-theme",
       },
       {
         file: APPEARANCE_FILES[SETTINGS_TYPE_TAPROOT_STYLES],
         path: "settings.darkTheme",
+        ...describeSettingField(SETTINGS_TYPE_TAPROOT_STYLES, "darkTheme"),
         type: "complete-espalier-theme",
       },
       ...scalarFields,
       ...APPEARANCE_FOOTER_COLOR_FIELDS.map((field) => ({
         file: field.file,
         path: field.path,
+        appLabel: "Footer",
+        description: `The footer's ${footerColorLabel(field.name)} in the ${field.scheme} scheme. footer push owns the rest of the footer.`,
+        renders: "The footer, once footerSettings.enabled is true (default false).",
         type: field.type,
         ...appearanceColorReference(field),
         default: field.default,
       })),
     ],
     readOnlyProjections: APPEARANCE_READ_ONLY_FIELDS,
+    pageBackgroundVersusCanvas: PAGE_BACKGROUND_VERSUS_CANVAS,
+    fieldMap: CLI_BINARY_NAME + " help settings maps every pulled field, including the read-only ones, to its app control.",
     imageReferences:
       "Use site-owned image ids retained from pull or returned by media upload. URLs are server projections, never authored inputs.",
     logoContract:
       "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting. "
+      + "Each takes one image id: upload the highest-resolution file you have and assign it. An @2x or @3x suffix is only "
+      + "part of a filename, nothing pairs it with another file, and the platform generates the sizes. "
       + "Prefer transparent PNG or WebP artwork with genuine alpha so the header background shows through, including "
       + "inside letter counters. Avoid baked-in background rectangles unless the brand intentionally uses a badge. "
       + "Keep padding tight and verify the delivered image preserves transparency. Logo style and coloration are "
@@ -776,11 +804,17 @@ export function formatPresentationReference(reference) {
   }
   if (reference.referenceKind === "appearance") {
     return reference.title + "\nUsage: " + reference.usage + "\n\nWritable fields:\n"
-      + reference.fields.map((field) => "  " + field.file + " :: " + field.path + " — " + fieldConstraint(field)).join(
-        "\n",
-      )
+      + reference.fields.map((field) =>
+        "  " + field.file + " :: " + field.path + " — " + fieldConstraint(field)
+        + "\n      app: " + field.appLabel + ". " + field.description
+        + (field.renders === undefined ? "" : "\n      renders: " + field.renders)
+      ).join("\n")
       + "\n\nRead-only server projections:\n"
       + reference.readOnlyProjections.map((field) => "  " + field.file + " :: " + field.path).join("\n")
+      + "\n\nPage background image versus canvas image:\n  - " + reference.pageBackgroundVersusCanvas.pageBackground
+      + "\n  - " + reference.pageBackgroundVersusCanvas.canvas
+      + "\n  - " + reference.pageBackgroundVersusCanvas.shared
+      + "\n\nField map: " + reference.fieldMap
       + "\n\nImages: " + reference.imageReferences + "\nLogos: " + reference.logoContract
       + "\nLogo contrast: " + reference.logoContrastContract
       + "\nFavicon: " + reference.faviconContract
@@ -794,6 +828,7 @@ export function formatPresentationReference(reference) {
       + "\nRetry: " + reference.retry
       + "\nRecovery: " + reference.recovery + "\n";
   }
+  if (reference.referenceKind === "settings") return formatSettingsReference(reference);
   if (reference.referenceKind === "footer") {
     const messages = reference.messages.map((message) =>
       message.name + " (unlisted fields rejected)\n"

package/src/problems.js

@@ -39,7 +39,12 @@ function withContext(problem, context, error) {
 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 }];
+    : [{
+      code: error.code,
+      ...(error.field === undefined ? {} : { field: error.field }),
+      ...(error.rule === undefined ? {} : { rule: error.rule }),
+      message: error.message,
+    }];
   return own.map((problem) => withContext(problem, context, error));
 }