@taprootio/site-authoring 0.14.1 → 0.16.0

package/src/content/tiptap-prosemirror.ts

@@ -367,14 +367,7 @@ function wrapMark(html: string, mark: ProseMirrorMark): string {
     case "link": {
       const href = stringAttr(mark.attrs?.href);
       if (!href || !isSafeUrl(href)) return html;
-      return renderElement(
-        "a",
-        {
-          href,
-          rel: "noopener noreferrer nofollow",
-        },
-        html,
-      );
+      return renderElement("a", { href, ...linkRelAttributes(mark.attrs) }, html);
     }
     default:
       return html;
@@ -1377,6 +1370,71 @@ function serializeAttributes(attrs: Record<string, string | number | boolean | n
   return serialized.length ? ` ${serialized.join(" ")}` : "";
 }
 
+/**
+ * The rel tokens a link may carry (TR01190): every HTML link type valid on
+ * `<a>` except `opener`, which hands a new tab a handle on the page.
+ */
+export const LINK_REL_TOKENS = [
+  "nofollow",
+  "sponsored",
+  "ugc",
+  "me",
+  "noopener",
+  "noreferrer",
+  "external",
+  "author",
+  "license",
+  "tag",
+  "bookmark",
+  "help",
+  "prev",
+  "next",
+  "privacy-policy",
+  "terms-of-service",
+] as const;
+/** The targets a link may carry; only `_blank` changes what renders. */
+export const LINK_TARGETS = ["_blank", "_self"] as const;
+/**
+ * The editor stored this rel, with `target="_blank"`, on every link before
+ * authors could choose, so a mark carrying it records no choice of either.
+ */
+export const LEGACY_EDITOR_LINK_REL = "noopener noreferrer nofollow";
+
+/**
+ * An author's chosen tokens as a stored rel. Those three tokens in the old
+ * default's order would read as no choice, so they are stored in vocabulary
+ * order instead.
+ */
+export function spellLinkRel(tokens: readonly string[]): string {
+  const rel = tokens.join(" ");
+  return rel === LEGACY_EDITOR_LINK_REL
+    ? LINK_REL_TOKENS.filter((token) => tokens.includes(token)).join(" ")
+    : rel;
+}
+
+/** A stored rel as tokens, or undefined when it is the editor's old default (no choice). */
+export function chosenLinkRelTokens(rel: unknown): string[] | undefined {
+  const tokens = stringAttr(rel)?.trim().toLowerCase().split(/\s+/u).filter(Boolean) ?? [];
+  return tokens.join(" ") === LEGACY_EDITOR_LINK_REL ? undefined : tokens;
+}
+
+/**
+ * The `rel` and `target` a link publishes with: the author's allowed tokens in
+ * their order, and noopener and noreferrer whenever it opens a new tab.
+ * Anything else stored is ignored.
+ */
+export function linkRelAttributes(attrs: Record<string, unknown> | undefined): { rel?: string; target?: string } {
+  const stored = chosenLinkRelTokens(attrs?.rel);
+  if (!stored) return {};
+  const newTab = stringAttr(attrs?.target)?.trim().toLowerCase() === "_blank";
+  const allowed: readonly string[] = LINK_REL_TOKENS;
+  const rel = new Set([
+    ...stored.filter((token) => allowed.includes(token)),
+    ...(newTab ? ["noopener", "noreferrer"] : []),
+  ]);
+  return { ...(rel.size ? { rel: [...rel].join(" ") } : {}), ...(newTab ? { target: "_blank" } : {}) };
+}
+
 function isSafeUrl(url: string): boolean {
   if (/[\x00-\x1f\x7f\\]/u.test(url)) return false;
   const cleaned = url.trim();

package/src/content/validate-document.js

@@ -18,6 +18,8 @@ import {
   isPlainObject,
   isSafeUrl,
   isUuid,
+  LINK_REL_TOKENS,
+  LINK_TARGETS,
   MARK_TYPE_SET,
   NODE_TYPE_SET,
   normalizeCssLengthOverride,
@@ -485,12 +487,34 @@ const MARK_RULES = Object.freeze({
       { required: true, code: CODES.linkHref, missingCode: CODES.linkHref },
     ),
     // `@tiptap/extension-link` declares these four alongside `href`, and
-    // `Mark.toJSON` emits every declared attribute — so every link the editor
-    // has ever written carries all five, and refusing any of them would refuse
-    // an ordinary pull/push round trip. The renderer ignores them and writes
-    // its own `rel`.
-    target: optionalString(),
-    rel: optionalString(),
+    // `Mark.toJSON` emits every declared attribute, so every link the editor
+    // has ever written carries all five. The renderer publishes `rel` and
+    // `target="_blank"` from closed lists (TR01190), so those two are held to
+    // them; it ignores `class` and `title`. The editor's old default rel,
+    // "noopener noreferrer nofollow", is within the list and renders as no
+    // choice.
+    target: spec(
+      (value) => {
+        if (isAbsent(value) || (typeof value === "string" && value.trim() === "")) return null;
+        return typeof value === "string" && LINK_TARGETS.includes(value.trim().toLowerCase())
+          ? null
+          : `"_blank" (open in a new tab), "_self", or absent`;
+      },
+      { code: CODES.linkTarget },
+    ),
+    rel: spec(
+      (value) => {
+        if (isAbsent(value)) return null;
+        if (typeof value !== "string") return "a string of space-separated link types";
+        const unknown = value.trim().toLowerCase().split(/\s+/u)
+          .filter((token) => token && !LINK_REL_TOKENS.includes(token));
+        if (unknown.length === 0) return null;
+        return `space-separated link types from ${LINK_REL_TOKENS.join(", ")}; ${
+          unknown.map((token) => `"${token}"`).join(", ")
+        } ${unknown.length === 1 ? "is" : "are"} not one`;
+      },
+      { code: CODES.linkRel },
+    ),
     class: optionalString(),
     title: optionalString(),
   }),

package/src/content/vocabulary.js

@@ -75,6 +75,30 @@ export const MARK_TYPES = Object.freeze([
   "link",
 ]);
 
+// The renderer's `LINK_REL_TOKENS` and `LINK_TARGETS` (TR01190): every HTML
+// link type valid on `<a>` except `opener`. The renderer publishes only these
+// and ignores the rest, so the CLI refuses the rest. The parity test reads
+// both lists from the copied renderer.
+export const LINK_REL_TOKENS = Object.freeze([
+  "nofollow",
+  "sponsored",
+  "ugc",
+  "me",
+  "noopener",
+  "noreferrer",
+  "external",
+  "author",
+  "license",
+  "tag",
+  "bookmark",
+  "help",
+  "prev",
+  "next",
+  "privacy-policy",
+  "terms-of-service",
+]);
+export const LINK_TARGETS = Object.freeze(["_blank", "_self"]);
+
 export const NODE_TYPE_SET = Object.freeze(new Set(NODE_TYPES));
 export const MARK_TYPE_SET = Object.freeze(new Set(MARK_TYPES));
 
@@ -108,6 +132,8 @@ export const CONTENT_ERROR_CODES = Object.freeze({
   markMisplaced: "content.mark_misplaced",
   unknownMark: "content.unknown_mark",
   linkHref: "content.link_href",
+  linkRel: "content.link_rel",
+  linkTarget: "content.link_target",
   // Attributes
   attrsInvalid: "content.attrs_invalid",
   attrUnknown: "content.attr_unknown",

package/src/errors.js

@@ -91,6 +91,8 @@ export function sanitizeDiagnostic(value, fallback = "The operation failed.") {
   return [...clean].slice(0, LIMITS.diagnosticScalars).join("") || fallback;
 }
 
+const MAXIMUM_PROBLEMS = 5_000;
+
 /**
  * The fixed wording every `theme.setting_missing` detail carries. A required
  * key that is absent is exactly that: absence alone says nothing about when
@@ -175,6 +177,26 @@ export class SiteAuthoringError extends Error {
     return this;
   }
 
+  /**
+   * Attach every problem a whole-workspace check found (TR01002). The JSON
+   * result carries a bounded prefix and the count; stderr lists them all.
+   */
+  withProblems(problems) {
+    const list = Array.isArray(problems) ? problems : [];
+    this.problems = list
+      .slice(0, MAXIMUM_PROBLEMS)
+      .filter((problem) => typeof problem?.code === "string")
+      .map((problem) => ({
+        ...(typeof problem.area === "string" ? { area: sanitizeDiagnostic(problem.area, "") } : {}),
+        ...(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, "") } : {}),
+        message: sanitizeDiagnostic(problem.message),
+      }));
+    this.problemCount = list.length;
+    return this;
+  }
+
   /** Attach the non-secret identity needed to inspect or revoke a created preview. */
   withPreviewRecovery(preview) {
     const recovery = normalizePreviewRecovery(preview);

package/src/espalier-shared.js

@@ -0,0 +1,11 @@
+/**
+ * An Espalier module that sits beside the exported theme module but is not
+ * exported itself (the fit report, the color engine). Its package root
+ * re-exports every component module, which registers custom elements as it
+ * loads, so these are loaded from beside the theme module instead, sharing its
+ * instance. The exact Espalier pin and this package's tests catch a release
+ * that moves them.
+ */
+export function loadEspalierShared(file) {
+  return import(new URL(`./${file}`, import.meta.resolve("@taprootio/espalier/shared/theme")).href);
+}

package/src/fixture-init.js

@@ -15,6 +15,8 @@ import {
   MANIFEST_FILE_NAME,
   MANIFEST_VERSION,
   PAGE_WORKSPACE_MODE_EDITABLE,
+  normalizePagePath,
+  PAGE_WORKSPACE_MODE_METADATA_ONLY,
   readManifest,
   readMediaManifest,
   readWorkspaceJson,
@@ -143,10 +145,14 @@ export async function initializeFixture(invocation, validate) {
       status: entry.status,
       templateType: entry.templateType,
       hasDraft: entry.hasDraft,
-      isGenerated: false,
+      isGenerated: entry.isGenerated === true,
       file,
       sourceFormat: "prosemirror",
       workspaceMode: "editable",
+      // What a generated page is, which its identity check needs offline.
+      ...(entry.generated !== null && typeof entry.generated === "object" && !Array.isArray(entry.generated)
+        ? { generated: entry.generated }
+        : {}),
     }));
     add(file, sanitize(page.document));
   }
@@ -194,6 +200,44 @@ export async function initializeFixture(invocation, validate) {
       ),
     );
   }
+  // Navigation and footer links may point at pages the fixture has no source
+  // for, such as generated section pages; they travel as metadata-only entries
+  // so the fixture validates as the site does (TR01198).
+  const editablePageCount = pages.length;
+  const linkedResourceIds = new Set();
+  (function collect(value) {
+    if (Array.isArray(value)) value.forEach(collect);
+    else if (value && typeof value === "object") {
+      for (const [key, child] of Object.entries(value)) {
+        if ((key === "resourceId" || key === "pageResourceId") && typeof child === "string") {
+          linkedResourceIds.add(child);
+        } else collect(child);
+      }
+    }
+  })([...documents.values()]);
+  for (const entry of source.pages) {
+    if (entry.workspaceMode !== PAGE_WORKSPACE_MODE_METADATA_ONLY) continue;
+    if (!isCanonicalUuid(entry.pageId) || !isCanonicalUuid(entry.resourceId)) continue;
+    if (!linkedResourceIds.has(identity(entry.resourceId))) continue;
+    const linkedPath = normalizePagePath(entry.path);
+    if (linkedPath === undefined || linkedPath === "") {
+      refuse(
+        `A page that is linked to has no usable path of its own (${JSON.stringify(entry.path ?? null)}); pull again.`,
+        "pages",
+      );
+    }
+    pages.push(sanitize({
+      pageId: entry.pageId,
+      resourceId: entry.resourceId,
+      path: linkedPath,
+      title: typeof entry.title === "string" ? entry.title : "",
+      status: entry.status,
+      templateType: entry.templateType,
+      hasDraft: entry.hasDraft === true,
+      isGenerated: entry.isGenerated === true,
+      workspaceMode: PAGE_WORKSPACE_MODE_METADATA_ONLY,
+    }));
+  }
   const redirects = documents.get("redirects.json");
   // A fixture hash is a local placeholder, not authority to mutate the original site.
   const revision = createHash("sha256").update(JSON.stringify(redirects.entries)).digest("hex");
@@ -242,10 +286,18 @@ export async function initializeFixture(invocation, validate) {
   try {
     for (const [file, value] of documents) await writeWorkspaceJson(destination, file, value);
     const result = await validate({ ...invocation, init: false, cwd, fixturePath: destination });
-    invocation.onProgress?.(`Initialized a sanitized fixture with ${pages.length} editable page(s).`);
+    invocation.onProgress?.(
+      `Initialized a sanitized fixture with ${editablePageCount} editable page(s)`
+        + `${pages.length > editablePageCount ? ` and ${pages.length - editablePageCount} linked page(s)` : ""}.`,
+    );
     return {
       ...result,
-      initialized: { directory: destination, pages: pages.length, skippedPages: source.pages.length - pages.length },
+      initialized: {
+        directory: destination,
+        pages: editablePageCount,
+        linkedPages: pages.length - editablePageCount,
+        skippedPages: source.pages.length - pages.length,
+      },
     };
   } catch (error) {
     await rm(destination, { recursive: true, force: true });

package/src/font-catalog.js

@@ -0,0 +1,87 @@
+import definitions from "@taprootio/espalier/css/fonts/font-definitions.json" with { type: "json" };
+
+import { CLI_BINARY_NAME } from "./constants.js";
+
+/**
+ * `help fonts` (TR01188): the font families a published site can load, read
+ * from the catalog Espalier ships with the CLI. A theme's font fields name a
+ * family from it; the generator fetches that family's faces at publish time.
+ *
+ * The whole catalog is larger than one result may be, so the topic lists the
+ * categories and `help fonts <category>` lists one category's families.
+ */
+
+/** A catalog variant is `regular`, `italic`, or a weight with an optional `italic`. */
+function variantWeight(variant) {
+  return variant === "regular" || variant === "italic" ? 400 : Number.parseInt(variant, 10);
+}
+
+// Only upright weights: a publish loads one upright face per font field, and
+// the browser slants it for italics.
+const FAMILIES = Object.freeze(definitions.map((definition) => Object.freeze({
+  family: definition.family,
+  category: definition.category,
+  weights: Object.freeze(definition.variants.filter((variant) => !variant.endsWith("italic")).map(variantWeight)),
+})));
+
+export const FONT_CATEGORIES = Object.freeze([...new Set(FAMILIES.map((entry) => entry.category))]);
+
+const DETAILS = Object.freeze([
+  "Set fontBody, fontHeadings, fontBrand, fontMonospace or fontMenu in settings/taproot-styles.json to a CSS "
+  + "font-family list that starts with a family from this catalog, spelled exactly as listed (the match is "
+  + "case-sensitive), such as \"Inter, sans-serif\". Finish with a CSS generic family: sans-serif, serif or "
+  + "monospace, or cursive for a handwriting family. A first family that is not listed is not loaded: the page "
+  + "falls back to the rest of the list, so a misspelled name publishes quietly in a fallback font.",
+  "Each font field's weight (fontWeightBody and the others) must be one of that family's weights; normal means 400 "
+  + "and bold 700. Any other weight, or lighter or bolder, would fail the publish for a catalog family, so validate "
+  + "and theme push refuse it and name the nearest weight the family has. An unset weight "
+  + "takes the default: 400 for body and monospace, 700 for headings, brand and menu (brand also inherits the "
+  + "headings family). So when a family lacks the default weight for its field, set that field's weight.",
+  "A publish loads one upright face per font field and serves it from the site itself; visitors never contact a "
+  + "font service. Italic text is the browser slanting that face. A family with no weights offers only italics and "
+  + "cannot be used.",
+]);
+
+/** The catalog's categories, or one category's families. */
+export function getFontCatalogReference(category) {
+  const base = {
+    title: "Font catalog",
+    summary: "The font families a published site can load, by category, with the weights each offers.",
+    usage: `${CLI_BINARY_NAME} help fonts [category] [--json]`,
+    details: DETAILS,
+  };
+  if (category === undefined) {
+    return Object.freeze({
+      ...base,
+      familyCount: FAMILIES.length,
+      categories: Object.freeze(FONT_CATEGORIES.map((name) => Object.freeze({
+        category: name,
+        familyCount: FAMILIES.filter((entry) => entry.category === name).length,
+        helpCommand: `${CLI_BINARY_NAME} help fonts ${name}`,
+      }))),
+    });
+  }
+  if (!FONT_CATEGORIES.includes(category)) return undefined;
+  const families = FAMILIES.filter((entry) => entry.category === category)
+    .map(({ family, weights }) => Object.freeze({ family, weights }));
+  return Object.freeze({ ...base, category, familyCount: families.length, families: Object.freeze(families) });
+}
+
+export function formatFontCatalog(reference) {
+  const header = `${reference.title}\n${reference.summary}\n\nUsage: ${reference.usage}\n\n${
+    reference.details.map((detail) => `- ${detail}`).join("\n")
+  }\n\n`;
+  if (reference.families === undefined) {
+    return `${header}${reference.familyCount} families:\n${
+      reference.categories.map((entry) =>
+        `  ${entry.category.padEnd(14)}${String(entry.familyCount).padStart(4)}  ${entry.helpCommand}`
+      ).join("\n")
+    }\n\nAdd --json for stable machine-readable output.\n`;
+  }
+  const width = Math.max(...reference.families.map(({ family }) => family.length)) + 2;
+  return `${header}${reference.familyCount} ${reference.category} families and their weights:\n${
+    reference.families.map(({ family, weights }) =>
+      `  ${family.padEnd(width)}${weights.length > 0 ? weights.join(" ") : "none (italic only; cannot be used)"}`
+    ).join("\n")
+  }\n\nAdd --json for the same list as stable machine-readable output.\n`;
+}

package/src/footer-contract.js

@@ -235,7 +235,7 @@ function target(value, path, knownPageResourceIds, tolerateStoredValues) {
     if (knownPageResourceIds && !knownPageResourceIds.has(value.pageResourceId)) {
       fail(
         "footer.page_reference_unknown",
-        `${path}.pageResourceId must identify a page tracked by the pull manifest.`,
+        `${path}.pageResourceId must identify a page tracked by the pull manifest that the site still holds.`,
         `${path}.pageResourceId`,
       );
     }

package/src/output.js

@@ -19,6 +19,7 @@ import {
   sanitizeDiagnostic,
   SiteAuthoringError,
 } from "./errors.js";
+import { problemsWithinBudget } from "./problems.js";
 
 const SAFE_SCALAR = /^[a-z][a-z0-9]*(?: [a-z][a-z0-9]*)?$/u;
 const MAXIMUM_OUTPUT_PATH_LENGTH = 4_096;
@@ -53,6 +54,13 @@ export function failureResult(error) {
   if (Array.isArray(error.differences)) {
     result.error.differences = error.differences;
   }
+  if (Array.isArray(error.problems) && error.problems.length > 0) {
+    const problems = problemsWithinBudget(error.problems);
+    const count = Math.max(error.problemCount ?? 0, error.problems.length);
+    result.error.problems = problems;
+    result.error.problemCount = count;
+    if (problems.length < count) result.error.problemsTruncated = true;
+  }
   const previewDiagnostic = normalizePreviewDiagnostic(error.previewDiagnostic);
   if (previewDiagnostic) result.error.diagnostic = previewDiagnostic;
   const previewRecovery = normalizePreviewRecovery(error.previewRecovery);
@@ -159,6 +167,12 @@ export async function writeGithubActionsOutput(outputPath, result) {
   await appendInspectedGithubOutput(outputPath, stats, `${lines.join("\n")}\n`);
 }
 
+function problemLocation(problem) {
+  if (problem.file === undefined) return problem.field ?? problem.area ?? "-";
+  if (problem.field === undefined || problem.field.startsWith(problem.file)) return problem.field ?? problem.file;
+  return `${problem.file} ${problem.field}`;
+}
+
 export function humanFailure(error) {
   const field = error.field ? ` field=${sanitizeDiagnostic(error.field, "unknown")}` : "";
   const status = error.status ? ` status=${sanitizeDiagnostic(error.status, "unknown")}` : "";
@@ -167,8 +181,12 @@ export function humanFailure(error) {
     ? ` refusal=${sanitizeDiagnostic(kind, "unknown")}`
     : "";
   const details = error.details?.map((item) => `${item.field}: ${item.message}`).join("\n");
+  const problems = error.problems?.length > 1
+    ? error.problems.map((problem) => `  ${problemLocation(problem)} [${problem.code}]: ${problem.message}`).join("\n")
+    : undefined;
   return `${CLI_BINARY_NAME} failed [${error.code}]${field}${status}${refusal}: ${sanitizeDiagnostic(error.message)}`
-    + (details ? `\n${details}` : "");
+    + (details ? `\n${details}` : "")
+    + (problems ? `\n${problems}` : "");
 }
 
 export function serializeResult(result) {

package/src/page-metadata.js

@@ -0,0 +1,92 @@
+import { SiteAuthoringError } from "./errors.js";
+import { boundedByBytes } from "./session.js";
+import { displayPagePath } from "./workspace.js";
+
+/**
+ * A page description is what search results and link previews show. Past about
+ * 160 characters search engines cut it off, so it is warned about; past 1000 it
+ * is refused, here and by the API (TR01194).
+ */
+export const DESCRIPTION_WARN_LENGTH = 160;
+export const DESCRIPTION_MAXIMUM_LENGTH = 1000;
+export const PAGE_DESCRIPTION_LONG = "pages.description_long";
+
+const length = (value) => [...value].length;
+
+/** Refuses a description the API would refuse. */
+export function requireDescriptionLength(description, field = "description") {
+  if (typeof description === "string" && length(description) > DESCRIPTION_MAXIMUM_LENGTH) {
+    throw new SiteAuthoringError(
+      "pages.description_too_long",
+      `The description is ${length(description)} characters; it may be at most ${DESCRIPTION_MAXIMUM_LENGTH} `
+        + `(search results show about ${DESCRIPTION_WARN_LENGTH}).`,
+      { field },
+    );
+  }
+}
+
+/** Warnings for descriptions search results will cut off, named per page. */
+export function descriptionWarnings(pages, onProgress) {
+  const items = [];
+  for (const page of pages ?? []) {
+    const description = page.declaredDescription ?? page.description;
+    if (typeof description !== "string" || length(description) <= DESCRIPTION_WARN_LENGTH) continue;
+    const item = {
+      code: PAGE_DESCRIPTION_LONG,
+      file: page.file,
+      path: displayPagePath(page.pagePath ?? page.path),
+      length: length(description),
+    };
+    onProgress(
+      `Warning: ${item.file}'s description is ${item.length} characters; search results show about `
+        + `${DESCRIPTION_WARN_LENGTH}.`,
+    );
+    items.push(item);
+  }
+  const reported = boundedByBytes(items, 8 * 1024);
+  return items.length === 0
+    ? {}
+    : {
+      descriptionWarnings: {
+        total: items.length,
+        items: reported.items,
+        ...(reported.truncated ? { truncated: true } : {}),
+      },
+    };
+}
+
+export const PAGE_AUTHOR_UNVERIFIED = "pages.author_unverified";
+
+/**
+ * Warnings for authors an offline run could not confirm (TR01196). The only
+ * evidence offline is `authors.json`, which is as old as the last `pull` or
+ * `authors list`, so a name missing from it may simply be newer; it is flagged
+ * rather than refused, and an online run settles it against the site.
+ */
+export function authorWarnings(pages, onProgress) {
+  const items = [];
+  for (const page of pages ?? []) {
+    if (page.authorUnverified !== true) continue;
+    const item = {
+      code: PAGE_AUTHOR_UNVERIFIED,
+      file: page.file,
+      path: displayPagePath(page.pagePath ?? page.path),
+      author: page.author,
+    };
+    onProgress(
+      `Warning: ${item.file} names author '${item.author}', who is not in authors.json; it may have been added `
+        + "since. 'taproot-site authors list' refreshes it, and 'pages push' checks the name against the site.",
+    );
+    items.push(item);
+  }
+  const reported = boundedByBytes(items, 8 * 1024);
+  return items.length === 0
+    ? {}
+    : {
+      authorWarnings: {
+        total: items.length,
+        items: reported.items,
+        ...(reported.truncated ? { truncated: true } : {}),
+      },
+    };
+}

package/src/presentation-reference.js

@@ -227,14 +227,25 @@ const THEME_GROUPS = Object.freeze([
     summary: "Choose families and weights, then tune type, spacing, radius, and fluid viewport scales together.",
     fields: Object.freeze([
       ...["fontBody", "fontHeadings", "fontBrand", "fontMonospace"].map((name) =>
-        themeField(name, "CSS font-family; empty inherits the consuming surface's fallback.")
+        themeField(
+          name,
+          "CSS font-family starting with a family from 'help fonts'; an unlisted family is not loaded. Empty "
+            + "inherits the consuming surface's fallback.",
+        )
       ),
       themeField(
         "fontMenu",
-        "CSS font-family for navigation menu items and group labels; empty falls back to fontBody, never to headings.",
+        "CSS font-family for navigation menu items and group labels, starting with a family from 'help fonts'; "
+          + "empty falls back to fontBody, never to headings.",
       ),
       ...["fontWeightBody", "fontWeightHeadings", "fontWeightBrand", "fontWeightMonospace", "fontWeightMenu"].map(
-        (name) => themeField(name, "CSS font-weight: 1–1000, normal/bold/lighter/bolder, or a CSS-wide keyword."),
+        (name) =>
+          themeField(
+            name,
+            "CSS font-weight. For a catalog family it must be one of the family's weights in 'help fonts' "
+              + "(normal is 400, bold 700); validate and theme push refuse any other value, which would fail the "
+              + "publish. Unset, it defaults to 400 for body and monospace and 700 for headings, brand and menu.",
+          ),
       ),
       themeField("rootFontSize", "Root font size in px.", { minimum: 1, warningMaximum: 100 }),
       themeField("typeRatio", "Modular type-scale ratio.", { exclusiveMinimum: 1, warningMaximum: 1.3 }),
@@ -323,11 +334,14 @@ export const ROLE_RESOLUTION = Object.freeze({
     + "makes a mapping a pin: the resolver recompiles every token the marker leaves out, so a mapping it does not "
     + "name is a cached value that is never applied. To pin a token, set the mapping and add the token to the "
     + "marker; to let a role reach it, drop the token from the marker or delete the mapping. A document that "
-    + "carries no explicitMappingTokens at all predates the marker, and every mapping in it is still a pin.",
+    + "carries no explicitMappingTokens at all predates the marker, and every mapping in it is still a pin. The "
+    + "marker is the root's alone: a mapping in a context's semanticMappings is a pin by itself, needs no marker, "
+    + "and a context cannot carry one.",
     "Otherwise the token is compiled from the roles, and an APCA contrast check may nudge an action or ink stop so "
     + "the pair stays readable.",
     "Otherwise the Espalier default mapping applies.",
-    "A context rebinds roles, lightness, tones and pins for one zone with the same precedence inside that zone.",
+    "A context rebinds roles, lightness, tones and pins for one zone with the same precedence inside that zone; its "
+    + "pins need no explicitMappingTokens.",
   ]),
 });
 
@@ -392,12 +406,12 @@ export function getThemeReference() {
       "Check the filled action before anything else looks finished. Its ramp stop is chosen by the engine near a mid-band target rather than named by the theme, so seating the ramp — the remedy for every other anchored token — cannot move it, and declaring an action role does not either. The only lever is pinning semanticMappings.actionBackground.",
       "A brand colour between roughly L 0.55 and L 0.83 cannot be a button surface at its own lightness: across that band no ink, not even pure black, reaches the Lc 75 APCA asks of a button label. Espalier then walks the label to the far end of the ramp and the button renders inverted — a dark surface carrying a pale label where the swatch wanted the opposite. Pin the stop just past the band instead. A gold at L 0.81 pinned to a tone at L 0.85 carries a dark label at Lc 76; the same gold left to the engine compiles to a brown one.",
       "Name a tone as a lowercase slug — gold-band, not goldBand. theme push refuses any other name, and refuses a mapping that names a tone its theme or context never declares.",
-      "theme push runs Espalier's fit report over the root and every context in both schemes and lists each finding as a warning reading 'fit lint <id>'; theme push --dry-run does the same and writes nothing, and validate does it for an offline fixture. Read the lints before calling a theme done: action-anchor-inversion names a filled action that rendered the opposite way round from the swatches it declares, apca-target-unmet names a pair enforcement could not rescue, and action-canvas-separation and link-hover-ordering cover an action lost in its canvas and a hover weaker than its link. A lint is a warning, not a refusal, so a push still goes through with one — the lints are what tell an agent the design did not survive the compile.",
+      "theme push runs Espalier's fit report over the root and every context in both schemes and lists each finding as a warning reading 'fit lint <id>'; theme push --dry-run does the same and writes nothing, and validate does it for an offline fixture. Read the lints before calling a theme done: action-anchor-inversion names a filled action that rendered the opposite way round from the swatches it declares, apca-target-unmet names a pair enforcement could not rescue, and action-canvas-separation and link-hover-ordering cover an action lost in its canvas and a hover weaker than its link. A lint is a warning, not a refusal, so a push still goes through with one — the lints are what tell an agent the design did not survive the compile. Contrast and status-color warnings end with 'Nearest passing value: …' when the CLI finds one: it applied that value to a copy of the theme and checked that the warning clears without raising another, so start there and check again. validate and theme push refuse a font weight a catalog family has no face for (theme.font_weight_unavailable), because the publish would fail, and name the nearest weight it has.",
       "Add named contexts for whole zones, including inverted zones, and rebind lightness when the zone changes brightness. A context that declares its own action needs its own actionBackground pin: without one it compiles at the engine's mid-band stop, and where the root is pinned it carries the root's pin instead, whatever action colour the context declares.",
       "Tune typography, type/space ratios, radii, and viewport interpolation as one layout system.",
       "Typography is per scheme on purpose: light and dark set their own moods, so a heading, body, or brand face that differs between them is a design choice, and theme push never warns about it.",
       "Retune danger/success/warning/info through intents without changing their meanings; design data palettes separately.",
-      "Use semanticMappings only for meanings roles and contexts cannot express; scattered pins shadow the coherent model. pull keeps only authored pins there and lists them in explicitMappingTokens; a mapping the marker does not name is never applied, so a hand-added pin needs its token added to the marker or theme push reports it as inert.",
+      "Use semanticMappings only for meanings roles and contexts cannot express; scattered pins shadow the coherent model. pull keeps only authored pins there and lists them in explicitMappingTokens; a mapping the marker does not name is never applied, so a hand-added pin at the root needs its token added to the marker or theme push reports it as inert. A pin inside a context needs no marker.",
       "Run theme push --dry-run and clear its warnings, fit lints included; then run theme push and verify text, actions, focus states, and both schemes in authoring previews.",
     ],
     example: THEME_EXAMPLE,