@taprootio/site-authoring 0.21.0 → 0.22.0

package/README.md

@@ -150,8 +150,17 @@ autolinking), and `pages push` reports the same for the pages it sends.
 `validate` also runs the site checks that need nothing but the workspace, from
 the same rule catalogue the editor and the site-health page read. `findings`
 lists each one as a rule id (`link.page_missing`, a link to a page the workspace
-does not have), a severity, the file, and the value found; a warning never
-refuses. `siteChecks.checkedBySite` names the rules that need the site's own
+does not have), a severity, the file, and the value found (and a `detail` for
+some); a warning never refuses. For a free-form page the rules also read its headings,
+images and links the way the publisher does: `seo.h1_missing` when no `#` heading,
+banner title or hero title is the page's `<h1>`; `seo.h1_demoted` when a `#` heading
+publishes as an `<h2>` because the banner's overlay text, a hero title or an earlier
+`#` heading already is the `<h1>` (`detail` says which); `seo.h1_multiple` for a hero
+title after the `<h1>`; `seo.heading_renumbered` and `seo.heading_before_title` for
+headings published at another level; and `a11y.image_alt_missing` and
+`a11y.link_text_empty`. Any page gets `seo.title_long` and `seo.description_missing`.
+`siteChecks.checkedInEditor` names the rules only the page editor evaluates (a cover, a description field, or a
+description's length, which `descriptionWarnings` reports here). `siteChecks.checkedBySite` names the rules that need the site's own
 records, such as placed images and forms: `status` reports those under
 `siteHealth`; `siteChecks.checkedAtDeploy` names the ones only a deploy applies. A redirect source the site would refuse also names its rule in
 `error.problems[].rule`.
@@ -718,7 +727,11 @@ on the site, sends the form's id, and refuses a key the site does not have
 (`pages.form_unknown`) or has archived (`pages.form_archived`) before it writes
 anything; `plan` reports the same. `pages pull` writes the key back. An id the
 site no longer has stays an id in the pulled file, and a push of it is refused
-until you choose a form. Form names are now unique on a site, ignoring case.
+until you choose a form. Form names are now unique on a site, ignoring case. `validate`
+checks the same keys offline against the workspace's own form files: when the
+workspace has a `forms/` directory, a `formKey` no `forms/<key>.json` in it names is refused
+(`pages.form_unknown`, rule `form.key_unknown`) naming the file it expected. A workspace
+with no `forms/` directory is not checked, because its forms may live only on the site.
 The deploy that introduces this rewrites the stored page bodies, which changes the
 body revision of every page that places a form, so the first `pages pull` after it
 can report `pages.pull_conflict` for such a Markdown page even though its content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",

package/src/changelog.json

@@ -1,5 +1,17 @@
 {
   "entries": [
+    {
+      "version": "0.22.0",
+      "note": "validate warns when a free-form page has no h1 or a banner or hero already claims it, and about alt text, link text, long titles and missing descriptions.",
+      "behavior": [
+        "validate reports page-structure warnings in findings, never refusing: seo.h1_missing for a free-form page with no # heading, banner title or hero title; seo.h1_demoted when a # heading publishes as an h2 because the banner's overlay text, a hero title or an earlier # heading is already the h1 (detail names which); seo.h1_multiple for a hero title after the h1; seo.heading_renumbered and seo.heading_before_title for headings published at another level; a11y.image_alt_missing; a11y.link_text_empty. Any page gets seo.title_long and seo.description_missing.",
+        "validate's siteChecks gains checkedInEditor, the rules only the page editor evaluates (a cover, a description field, or a description's length, which descriptionWarnings reports here).",
+        "The API refuses a page save that newly places a form that does not exist or is archived, and a first form block on a Profile or Docs site, with a validation error on Forms; status lists form.not_supported_on_site_type among the site findings. preview-page now renders the form a page places, from its current version.",
+        "validate refuses a component:form formKey that none of the workspace's forms/<key>.json files has (pages.form_unknown, rule form.key_unknown), naming the file it expected; a workspace with no forms/ directory is not checked. pages push and plan say whether the missing key's file is in the workspace.",
+        "pull writes a stored light or dark theme as the generator renders it: as stored over Espalier's defaults alone. It no longer layers the Taproot house theme under a theme the CLI does not manage, so a sparse theme from such a site pulls with Espalier's values for the keys it never set, so the pulled theme matches what the published site renders."
+      ],
+      "help": []
+    },
     {
       "version": "0.21.0",
       "note": "Review URLs stay out of deploy output unless you ask; deploy --staging waits until staging serves the new release; validate reports site checks; help corrections for free-form h1, legal pages, settings and logos; this changelog.",

package/src/cli.js

@@ -125,7 +125,13 @@ const VERBS = Object.freeze([
       + "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 "
+      + "warning. For a free-form page they include the page-structure rules: seo.h1_missing when no heading, banner "
+      + "title or hero title is the page's h1, seo.h1_demoted when a # heading is published as an h2 because the "
+      + "banner's overlay text, a hero title or an earlier # heading already is the h1 (detail names which), "
+      + "seo.heading_renumbered and seo.heading_before_title for headings published at another level, "
+      + "a11y.image_alt_missing and a11y.link_text_empty; for any page seo.title_long and seo.description_missing. "
+      + "siteChecks.checkedInEditor names the rules only the page editor evaluates (a cover, a description field, or a description's length, which descriptionWarnings reports here); "
+      + "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 "
@@ -332,7 +338,7 @@ const VERBS = Object.freeze([
     note:
       "Positional page paths narrow the push to those pages; with none, every workspace page is validated and sent. "
       + "A page names a form by key (formKey); the push looks each key up on the site, sends the form's id, and "
-      + "refuses a key the site does not have or has archived (pages.form_unknown, pages.form_archived) before writing. "
+      + "refuses a key the site does not have or has archived (pages.form_unknown, pages.form_archived) before writing, and says whether the key's forms/<key>.json is in the workspace. validate refuses the same key offline (rule form.key_unknown) when the workspace has a forms/ directory and no file in it is for that key. "
       + "A link in a page being sent whose address is only http(s):// plus its own text is reported in linkWarnings "
       + "(content.link_autolinked) without refusing. "
       + "A page is created without an author unless its source names one ('author:' in the front matter, or 'pages "

package/src/forms-workspace.js

@@ -53,6 +53,28 @@ export async function readWorkspaceForms(workspaceDir, keys, validationOptions =
   return forms;
 }
 
+/**
+ * The keys of the form files the workspace holds, read from file names alone (TR01081), or undefined
+ * when the folder cannot be read (a name outside the safe grammar, a link, too many files): the
+ * answer is only a hint for a refusal, so a workspace that cannot say changes nothing, and
+ * `forms validate` reports the folder's problem. A file whose name is not a form key is left out.
+ */
+export async function workspaceFormKeys(workspaceDir) {
+  let files;
+  try {
+    files = await walkWorkspaceFiles(workspaceDir, FORMS_DIRECTORY, [FORM_FILE_EXTENSION]);
+  } catch (error) {
+    if (error instanceof SiteAuthoringError) return undefined;
+    throw error;
+  }
+  const keys = new Set();
+  for (const file of files) {
+    const key = file.slice(FORMS_DIRECTORY.length + 1, -FORM_FILE_EXTENSION.length);
+    if (!key.includes("/") && isFormKey(key)) keys.add(key);
+  }
+  return keys;
+}
+
 /** A form name as the site compares it: trimmed, ignoring case (TR01216). */
 export function comparableFormName(name) {
   return String(name).trim().toLowerCase();

package/src/heading-outline.js

@@ -0,0 +1,76 @@
+// Generated from shared/heading-outline.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * How a published page numbers its headings (TR00929, TR00946, TR00947).
+ *
+ * The generator renders a page with this state machine, and the page-structure
+ * checks in `page-structure-checks.ts` replay the same machine over a document
+ * to tell an author which element claims the page's `<h1>` and which headings
+ * the publisher renumbers. One owner keeps what the warning says in step with
+ * what ships. The generator's `component-renderer.ts` and the site-authoring
+ * package import copies of this file; `node scripts/sync-field-validation.mjs`
+ * writes them, so edit only this file.
+ *
+ * It is dependency-free so every consumer can carry a copy.
+ */
+export function createHeadingOutlineState(options = {}) {
+    const titleOpen = options.titleOpen === true;
+    const parentLevel = options.parentLevel ?? 1;
+    return { level: parentLevel, titleOpen, titleClaimed: !titleOpen, parentLevel, open: [] };
+}
+// Not `Array.prototype.at`: the editor's TypeScript library predates it.
+function lastOpen(state) {
+    return state.open[state.open.length - 1];
+}
+/**
+ * The level to render an author heading at (TR00946). It closes the open
+ * headings at its authored level or deeper, then sits one level below the
+ * heading still open, so an h3 straight after the page's h1 becomes an h2,
+ * and so do the h3s after it until the author's own h2. A free-form page's
+ * first author h1 is its title; any other h1 is demoted.
+ */
+export function nextHeadingLevel(state, authored) {
+    if (!state)
+        return authored;
+    if (authored === 1 && !state.titleClaimed) {
+        recordFixedHeading(state, 1);
+        return 1;
+    }
+    while ((lastOpen(state)?.authored ?? 0) >= authored)
+        state.open.pop();
+    const level = Math.min(6, (lastOpen(state)?.level ?? state.parentLevel) + 1);
+    state.open.push({ authored, level });
+    state.level = level;
+    return level;
+}
+/** A heading whose level the page fixes, such as a hero title or CTA heading. */
+export function recordFixedHeading(state, level) {
+    if (level === 1)
+        state.titleClaimed = true;
+    while ((lastOpen(state)?.level ?? 0) >= level)
+        state.open.pop();
+    state.open.push({ authored: level, level });
+    state.level = level;
+}
+/**
+ * Whether an Image Banner is the page's title: it opens a free-form page,
+ * shows an image, and carries overlay text. Without an image the overlay is
+ * not drawn, so the banner carries no heading.
+ */
+export function bannerOpensPage(state, data) {
+    return state?.titleOpen === true
+        && Boolean(data.image?.src)
+        && typeof data.overlayText === "string"
+        && data.overlayText.trim() !== "";
+}
+/**
+ * The level of the heading a hero or CTA component fixes on the page, or
+ * undefined when the component carries none. A hero title is always an h1;
+ * a CTA heading is an h2.
+ */
+export function componentFixedHeadingLevel(type, data) {
+    if (type === "hero-section" && data.title)
+        return 1;
+    if (type === "cta" && data.heading)
+        return 2;
+    return undefined;
+}

package/src/page-metadata.js

@@ -1,4 +1,5 @@
 import { SiteAuthoringError } from "./errors.js";
+import { DESCRIPTION_WARN_LENGTH } from "./page-structure-checks.js";
 import { boundedByBytes } from "./session.js";
 import { displayPagePath } from "./workspace.js";
 
@@ -7,7 +8,7 @@ import { displayPagePath } from "./workspace.js";
  * 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 { DESCRIPTION_WARN_LENGTH };
 export const DESCRIPTION_MAXIMUM_LENGTH = 1000;
 export const PAGE_DESCRIPTION_LONG = "pages.description_long";
 

package/src/page-structure-checks.js

@@ -0,0 +1,356 @@
+// Generated from shared/page-structure-checks.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * The page-structure site checks (TR00947): the SEO and accessibility oddities
+ * a creator can fix in the editor or the CLI before publishing.
+ *
+ * `shared/site-check-rules.json` is the catalogue; these are the `document`
+ * scope rules in it. They read one document and the page's own metadata, never
+ * the site's records, so the editor evaluates the open document in the browser
+ * and the CLI evaluates a workspace file offline, from copies of this one
+ * source. The API carries no second implementation: the rules are advice, and
+ * nothing on the server needs them to decide a save or a deploy.
+ *
+ * The heading rules replay the generator's own outline machine
+ * (`heading-outline.ts`) over the document, so what they say matches what is
+ * published. `generator/src/page-structure-parity.test.ts` renders every
+ * heading case in `site-check-corpus.json` and compares it with what these
+ * rules predicted.
+ *
+ * It is dependency-free so the editor and the published site-authoring package
+ * can carry copies. `node scripts/sync-field-validation.mjs` writes them; edit
+ * only this file and re-run it.
+ */
+import { bannerOpensPage, componentFixedHeadingLevel, createHeadingOutlineState, nextHeadingLevel, recordFixedHeading, } from "./heading-outline.js";
+export const RULE_H1_MISSING = "seo.h1_missing";
+export const RULE_H1_DEMOTED = "seo.h1_demoted";
+export const RULE_H1_MULTIPLE = "seo.h1_multiple";
+export const RULE_HEADING_RENUMBERED = "seo.heading_renumbered";
+export const RULE_HEADING_BEFORE_TITLE = "seo.heading_before_title";
+export const RULE_IMAGE_ALT_MISSING = "a11y.image_alt_missing";
+export const RULE_LINK_TEXT_EMPTY = "a11y.link_text_empty";
+export const RULE_TITLE_LONG = "seo.title_long";
+export const RULE_DESCRIPTION_MISSING = "seo.description_missing";
+export const RULE_DESCRIPTION_LONG = "seo.description_long";
+export const RULE_SOCIAL_IMAGE_FALLBACK = "seo.social_image_fallback";
+const RULE_ORDER = [
+    RULE_H1_MISSING,
+    RULE_H1_DEMOTED,
+    RULE_H1_MULTIPLE,
+    RULE_HEADING_RENUMBERED,
+    RULE_HEADING_BEFORE_TITLE,
+    RULE_IMAGE_ALT_MISSING,
+    RULE_LINK_TEXT_EMPTY,
+    RULE_TITLE_LONG,
+    RULE_DESCRIPTION_MISSING,
+    RULE_DESCRIPTION_LONG,
+    RULE_SOCIAL_IMAGE_FALLBACK,
+];
+/** Search results cut a title off after about this many characters. */
+export const TITLE_WARN_LENGTH = 60;
+/** Search results cut a description off after about this many characters. */
+export const DESCRIPTION_WARN_LENGTH = 160;
+const MAXIMUM_DEPTH = 256;
+const MAXIMUM_SUBJECT_LENGTH = 80;
+const characters = (value) => [...value].length;
+function isNode(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function children(node) {
+    return Array.isArray(node.content) ? node.content.filter(isNode) : [];
+}
+function clip(value) {
+    const text = value.replace(/\s+/gu, " ").trim();
+    const letters = [...text];
+    return letters.length > MAXIMUM_SUBJECT_LENGTH ? `${letters.slice(0, MAXIMUM_SUBJECT_LENGTH - 1).join("")}…` : text;
+}
+function textOf(node) {
+    if (node.type === "text")
+        return typeof node.text === "string" ? node.text : "";
+    return children(node).map(textOf).join(node.type === "hardBreak" ? " " : "");
+}
+function componentData(node) {
+    const raw = node.attrs?.componentData;
+    if (typeof raw === "string") {
+        try {
+            const parsed = JSON.parse(raw);
+            return isNode(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    // The publisher reads only a JSON string here; anything else renders as an empty component.
+    return {};
+}
+function nonBlank(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function imageSource(value) {
+    return isNode(value) && nonBlank(value.src);
+}
+function clampLevel(value) {
+    const level = typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : 1;
+    return Math.min(4, Math.max(1, level));
+}
+/**
+ * The headings, images and links of a free-form body, as the publisher meets them.
+ * Every component block counts as content before a banner, though the publisher drops
+ * one that renders only a comment (a Latest posts block with no posts, an unknown type), and
+ * an integration placement renders nothing or a status paragraph depending on the site;
+ * whether it does can depend on the site, so a banner after such a block is the one case
+ * where this walk and the publisher can differ.
+ */
+function walkBody(body) {
+    const findings = [];
+    // Findings about headings wait for the whole walk: whether the page has an h1 is known only at the end.
+    const headings = [];
+    const extraTitles = [];
+    const outline = createHeadingOutlineState({ titleOpen: true });
+    let claimant;
+    let imageCount = 0;
+    let hasContent = false;
+    // Adopted integration markup is opaque here; it may hold the page's own h1.
+    let opaqueH1 = false;
+    const seeContent = () => {
+        hasContent = true;
+        outline.titleOpen = false;
+    };
+    const visitLinks = (node, path) => {
+        // A link split by formatting is several adjacent text nodes; the link is empty only when all of them are.
+        let run;
+        const close = () => {
+            if (run && run.text.trim() === "") {
+                findings.push({ ruleId: RULE_LINK_TEXT_EMPTY, severity: "warning", subject: clip(run.href), detail: "", path });
+            }
+            run = undefined;
+        };
+        for (const child of children(node)) {
+            const href = child.type === "text" && Array.isArray(child.marks)
+                ? child.marks.find((mark) => isNode(mark) && mark.type === "link")?.attrs?.href
+                : undefined;
+            if (typeof href !== "string") {
+                close();
+                continue;
+            }
+            if (run && run.href !== href)
+                close();
+            run = { href, text: `${run?.text ?? ""}${typeof child.text === "string" ? child.text : ""}` };
+        }
+        close();
+    };
+    const visit = (node, path, depth) => {
+        if (depth > MAXIMUM_DEPTH)
+            return;
+        switch (node.type) {
+            case "heading": {
+                const authored = clampLevel(node.attrs?.level);
+                const titleWasOpen = !outline.titleClaimed;
+                const level = nextHeadingLevel(outline, authored);
+                const text = clip(textOf(node));
+                const claimsTitle = authored === 1 && titleWasOpen;
+                if (claimsTitle)
+                    claimant = { kind: "heading", text };
+                headings.push({
+                    path,
+                    text,
+                    authored,
+                    level,
+                    role: claimsTitle ? "title" : titleWasOpen ? "before_title" : authored === 1 ? "demoted" : "numbered",
+                });
+                break;
+            }
+            case "taprootImage": {
+                imageCount++;
+                seeContent();
+                if (!nonBlank(node.attrs?.alt)) {
+                    const id = node.attrs?.imageId;
+                    findings.push({
+                        ruleId: RULE_IMAGE_ALT_MISSING,
+                        severity: "warning",
+                        subject: typeof id === "string" ? id : "",
+                        detail: "",
+                        path,
+                    });
+                }
+                return;
+            }
+            case "componentBlock": {
+                const type = typeof node.attrs?.componentType === "string" ? node.attrs.componentType : "";
+                const data = componentData(node);
+                // The banner decides whether it is the title before the page counts it as content.
+                const opensPage = type === "image-banner" && bannerOpensPage(outline, data);
+                const fixedLevel = componentFixedHeadingLevel(type, data);
+                if (type === "image-banner" && imageSource(data.image)) {
+                    imageCount++;
+                    if (!nonBlank(data.altText)) {
+                        findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
+                    }
+                }
+                // The social preview also draws on a hero's picture.
+                if (type === "hero-section" && imageSource(data.media)) {
+                    imageCount++;
+                    if (!nonBlank(data.media.alt)) {
+                        findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
+                    }
+                }
+                if (type === "cta" && imageSource(data.mediaImage) && !nonBlank(data.mediaImage.alt)) {
+                    findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
+                }
+                if (opensPage) {
+                    recordFixedHeading(outline, 1);
+                    claimant = { kind: "banner", text: clip(String(data.overlayText)) };
+                }
+                else if (fixedLevel === 1) {
+                    const text = clip(String(data.title));
+                    if (outline.titleClaimed)
+                        extraTitles.push({ path, text });
+                    else
+                        claimant = { kind: "hero", text };
+                    recordFixedHeading(outline, 1);
+                }
+                else if (fixedLevel !== undefined) {
+                    recordFixedHeading(outline, fixedLevel);
+                }
+                seeContent();
+                return;
+            }
+            case "section": {
+                // A section's photo background is an image too; its children are still walked below.
+                const background = node.attrs?.background;
+                if (isNode(background) && imageSource(background.image))
+                    imageCount++;
+                break;
+            }
+            case "text":
+                if (nonBlank(node.text))
+                    seeContent();
+                return;
+            case "integrationFragment": {
+                // The publisher treats an adopted fragment with markup as content before a banner, and its bytes may
+                // carry the page's own `<h1>`, which this walk cannot see.
+                const html = node.attrs?.html;
+                if (nonBlank(html)) {
+                    seeContent();
+                    if (/<h1[\s>]/iu.test(html))
+                        opaqueH1 = true;
+                }
+                return;
+            }
+            case "inlineFacts":
+                // A fact list is visible content; one with no items renders nothing.
+                if (Array.isArray(node.attrs?.items) && node.attrs.items.length > 0)
+                    seeContent();
+                return;
+            default:
+                break;
+        }
+        visitLinks(node, path);
+        children(node).forEach((child, index) => visit(child, [...path, index], depth + 1));
+    };
+    if (isNode(body))
+        children(body).forEach((child, index) => visit(child, [index], 1));
+    if (claimant === undefined) {
+        // A page with nothing on it has nothing to title yet.
+        if (hasContent && !opaqueH1) {
+            findings.unshift({ ruleId: RULE_H1_MISSING, severity: "warning", subject: "", detail: "" });
+        }
+    }
+    else {
+        const kind = claimant.kind;
+        // A Heading 1 with no text still claims the title, so the page publishes an empty `<h1>`.
+        if (claimant.kind === "heading" && claimant.text === "" && hasContent) {
+            findings.unshift({ ruleId: RULE_H1_MISSING, severity: "warning", subject: "", detail: "" });
+        }
+        for (const heading of headings) {
+            if (heading.role === "demoted") {
+                findings.push({
+                    ruleId: RULE_H1_DEMOTED,
+                    severity: "warning",
+                    subject: heading.text,
+                    detail: kind,
+                    path: heading.path,
+                });
+            }
+            else if (heading.role === "before_title") {
+                findings.push({
+                    ruleId: RULE_HEADING_BEFORE_TITLE,
+                    severity: "warning",
+                    subject: heading.text,
+                    detail: String(heading.level),
+                    path: heading.path,
+                });
+            }
+            else if (heading.role === "numbered" && heading.level !== heading.authored) {
+                findings.push({
+                    ruleId: RULE_HEADING_RENUMBERED,
+                    severity: "warning",
+                    subject: heading.text,
+                    detail: `${heading.authored}>${heading.level}`,
+                    path: heading.path,
+                });
+            }
+        }
+        for (const title of extraTitles) {
+            findings.push({
+                ruleId: RULE_H1_MULTIPLE,
+                severity: "warning",
+                subject: title.text,
+                detail: kind,
+                path: title.path,
+            });
+        }
+    }
+    return { findings, imageCount, hasContent };
+}
+/**
+ * The warnings for one page. Headings, images and links are checked on a
+ * free-form body only; the title, description and social preview checks run
+ * for any page whose surface supplies those fields. `rules` limits the result
+ * to the rule ids a surface runs: the catalogue's `runsAt` says which.
+ */
+export function pageStructureFindings(page, rules) {
+    // Catalogue order, so a surface that shows only the first few keeps the heading rules.
+    return collectFindings(page)
+        .filter((finding) => rules === undefined || rules.has(finding.ruleId))
+        .sort((left, right) => RULE_ORDER.indexOf(left.ruleId) - RULE_ORDER.indexOf(right.ruleId));
+}
+function collectFindings(page) {
+    const findings = [];
+    let imageCount = 0;
+    if (page.freeForm) {
+        const walked = walkBody(page.body);
+        findings.push(...walked.findings);
+        imageCount = walked.imageCount;
+    }
+    if (typeof page.title === "string" && characters(page.title.trim()) > TITLE_WARN_LENGTH) {
+        findings.push({
+            ruleId: RULE_TITLE_LONG,
+            severity: "warning",
+            subject: "",
+            detail: String(characters(page.title.trim())),
+        });
+    }
+    if (typeof page.description === "string") {
+        const description = page.description.trim();
+        if (description === "") {
+            findings.push({ ruleId: RULE_DESCRIPTION_MISSING, severity: "warning", subject: "", detail: "" });
+        }
+        else if (characters(description) > DESCRIPTION_WARN_LENGTH) {
+            findings.push({
+                ruleId: RULE_DESCRIPTION_LONG,
+                severity: "warning",
+                subject: "",
+                detail: String(characters(description)),
+            });
+        }
+    }
+    if (page.freeForm && page.hasCover === false) {
+        findings.push({
+            ruleId: RULE_SOCIAL_IMAGE_FALLBACK,
+            severity: "warning",
+            subject: "",
+            detail: imageCount > 0 ? "first_image" : "none",
+        });
+    }
+    return findings;
+}

package/src/settings-catalog.js

@@ -200,12 +200,11 @@ export function projectSettingsGroup(group, response) {
     if (field.wireType === "theme") {
       // A stored theme is what was written, possibly before a required key
       // existed; the workspace gets the complete theme consumers actually
-      // render, resolved the way they resolve it (TR00775). The read-only
-      // provenance flag says whether Taproot's house look still layers under it.
+      // render, resolved the way they resolve it (TR00775): as stored, over
+      // Espalier's defaults alone (TR01060).
       projected[field.name] = projectPulledTheme(
         projected[field.name],
         field.name === "lightTheme" ? "light" : "dark",
-        { managedExternally: source[`${field.name}ManagedExternally`] === true },
       );
     }
   }

package/src/site-check-findings.js

@@ -1,7 +1,10 @@
 import { sanitizeDiagnostic } from "./errors.js";
 import { boundedByBytes } from "./session.js";
 import rules from "./site-check-rules.json" with { type: "json" };
+import { isFormKey } from "./forms-contract.js";
+import { DESCRIPTION_WARN_LENGTH, pageStructureFindings, TITLE_WARN_LENGTH } from "./page-structure-checks.js";
 import { missingPageLinkFindings, normalizedPathSet } from "./site-checks.js";
+import { documentTemplate, TEMPLATE_FREE_FORM, TEMPLATE_GENERATED } from "./typed-pages.js";
 import { displayPagePath } from "./workspace.js";
 
 /**
@@ -21,6 +24,11 @@ export const SITE_CHECK_WORDING = Object.freeze({
   "form.unreadable": () => "places a form by an old key or an id the site cannot read",
   "form.missing": () => "places a form that does not exist",
   "form.archived": (finding) => `places the form '${finding.detail}', which is archived`,
+  "form.key_unknown": (finding) =>
+    isFormKey(finding.subject)
+      ? `places the form '${finding.subject}', but the workspace has no forms/${finding.subject}.json (add that form file, run 'forms pull' if the site has it, or fix the key)`
+      : `places the form '${finding.subject}', which is not a form key (lowercase letters, digits and single hyphens)`,
+  "form.not_supported_on_site_type": () => "places a form, but forms are available on standard sites only",
   "form.after_submit_page_unpublished": (finding) =>
     `the form '${finding.detail}' sends visitors to ${finding.subject || "a page that no longer exists"}, which the release does not publish`,
   "form.after_submit_page_not_allowed": (finding) =>
@@ -32,6 +40,36 @@ export const SITE_CHECK_WORDING = Object.freeze({
   "redirect.source_runtime_mirror": () => "has a source under the published-site runtime",
   "redirect.source_generated_file": () => "has a source naming a file the site generates",
   "redirect.source_not_storable": () => "has a source the publisher cannot store",
+  "seo.h1_missing": () =>
+    "has no h1: no level 1 heading, banner title or hero title opens the page, so search engines find no page title",
+  "seo.h1_demoted": (finding) =>
+    `has the level 1 heading '${finding.subject}', which publishes as an h2 because ${H1_CLAIMANT[finding.detail] ?? "another element"} is already the page's h1`,
+  "seo.h1_multiple": (finding) =>
+    `has the hero title '${finding.subject}', which is a second h1 because ${H1_CLAIMANT[finding.detail] ?? "another element"} is already the page's h1`,
+  "seo.heading_renumbered": (finding) => {
+    const [authored, published] = finding.detail.split(">");
+    return `has the heading '${finding.subject}' written as an h${authored}, which publishes as an h${published} so no level is skipped`;
+  },
+  "seo.heading_before_title": (finding) =>
+    `has the heading '${finding.subject}' before the page's h1; it publishes as an h${finding.detail}`,
+  "a11y.image_alt_missing": () => "places an image with no alt text",
+  "a11y.link_text_empty": (finding) => `has a link to ${finding.subject} with no text`,
+  "seo.title_long": (finding) =>
+    `has a title of ${finding.detail} characters; search results show about ${TITLE_WARN_LENGTH}`,
+  "seo.description_missing": () => "has no description; search results use the start of the page instead",
+  "seo.description_long": (finding) =>
+    `has a description of ${finding.detail} characters; search results show about ${DESCRIPTION_WARN_LENGTH}`,
+  "seo.social_image_fallback": (finding) =>
+    finding.detail === "first_image"
+      ? "has no cover image; link previews use the page's first image only when it is public and at least 1200 pixels wide"
+      : "has no cover image and no images, so link previews show no picture",
+});
+
+/** What a finding's `detail` names as the element that already claims the page's h1. */
+const H1_CLAIMANT = Object.freeze({
+  heading: "the first level 1 heading",
+  banner: "the banner at the top",
+  hero: "the hero title",
 });
 
 /** The sentence for a finding, falling back to the rule id for a rule this release has no words for. */
@@ -45,32 +83,74 @@ const MAXIMUM_PROGRESS_LINES = 20;
 
 const rulesRunningAt = (point) => SITE_CHECK_RULES.filter((rule) => rule.runsAt.includes(point)).map((rule) => rule.id);
 
+// The document rules `validate` runs offline, as the set the shared evaluator filters by.
+const OFFLINE_DOCUMENT_RULES = new Set(
+  SITE_CHECK_RULES.filter((rule) => rule.scope === "document" && rule.runsAt.includes("validate")).map((rule) => rule.id),
+);
+
+/** The page-structure findings for one planned page, or none for a document the rules cannot read. */
+function structureFindingsFor(page) {
+  if (page.document === null || typeof page.document !== "object") return [];
+  const template = documentTemplate(page.document);
+  // A generated page's title and description come from the site, not from an author.
+  if (template === TEMPLATE_GENERATED) return [];
+  const freeForm = template === TEMPLATE_FREE_FORM;
+  return pageStructureFindings(
+    {
+      freeForm,
+      body: freeForm ? page.document : undefined,
+      title: page.title,
+      description: page.declaredDescription ?? page.description,
+    },
+    OFFLINE_DOCUMENT_RULES,
+  );
+}
+
 /**
  * Evaluates the offline page rules over the planned pages. `pagePaths` is every
  * page path the workspace knows, and `pagesComplete` says whether that list is
  * the whole site: a truncated manifest cannot say a link is broken.
  */
-export function evaluateOfflineSiteChecks({ planned, pagePaths, pagesComplete = true, onProgress = () => {} }) {
+export function evaluateOfflineSiteChecks({
+  planned,
+  pagePaths,
+  pagesComplete = true,
+  formKeysChecked = true,
+  onProgress = () => {},
+}) {
   const known = normalizedPathSet([...pagePaths, ...(planned ?? []).map((page) => page.pagePath)]);
 
+  const found = [];
+  for (const page of planned ?? []) {
+    if (page.document === null || typeof page.document !== "object") continue;
+    // The link rule needs every page path; the structure rules read only the page itself.
+    const linkFindings = pagesComplete ? missingPageLinkFindings(page.document, page.pagePath ?? "", known) : [];
+    for (const finding of [...linkFindings, ...structureFindingsFor(page)]) found.push({ page, finding });
+  }
+  // Errors first, then in catalogue order, so the bounded list and the progress lines keep the rules that
+  // matter most when a large site raises a frequent one (a missing description) on every page.
+  const catalogueOrder = (ruleId) => SITE_CHECK_RULES.findIndex((rule) => rule.id === ruleId);
+  const severityOrder = (finding) => (finding.severity === "error" ? 0 : 1);
+  found.sort((left, right) =>
+    severityOrder(left.finding) - severityOrder(right.finding)
+    || catalogueOrder(left.finding.ruleId) - catalogueOrder(right.finding.ruleId)
+  );
+
   const items = [];
-  if (pagesComplete) {
-    for (const page of planned ?? []) {
-      if (page.document === null || typeof page.document !== "object") continue;
-      for (const finding of missingPageLinkFindings(page.document, page.pagePath ?? "", known)) {
-        const item = {
-          rule: finding.ruleId,
-          severity: finding.severity,
-          file: page.file,
-          path: displayPagePath(page.pagePath),
-          subject: [...sanitizeDiagnostic(finding.subject, "")].slice(0, 300).join(""),
-        };
-        if (items.length < MAXIMUM_PROGRESS_LINES) {
-          onProgress(`Warning: ${item.file} ${describeSiteFinding({ ...finding, subject: item.subject })}.`);
-        }
-        items.push(item);
-      }
+  for (const { page, finding } of found) {
+    const subject = [...sanitizeDiagnostic(finding.subject, "")].slice(0, 300).join("");
+    const item = {
+      rule: finding.ruleId,
+      severity: finding.severity,
+      file: page.file,
+      path: displayPagePath(page.pagePath),
+      subject,
+      ...(finding.detail === "" ? {} : { detail: finding.detail }),
+    };
+    if (items.length < MAXIMUM_PROGRESS_LINES) {
+      onProgress(`Warning: ${item.file} ${describeSiteFinding({ ...finding, subject })}.`);
     }
+    items.push(item);
   }
   if (items.length > MAXIMUM_PROGRESS_LINES) {
     onProgress(`Warning: ${items.length - MAXIMUM_PROGRESS_LINES} more site check finding(s); see findings.`);
@@ -91,9 +171,18 @@ export function evaluateOfflineSiteChecks({ planned, pagePaths, pagesComplete =
       checkedBySite: SITE_CHECK_RULES.filter((rule) => !rule.runsAt.includes("validate") && rule.runsAt.includes("health"))
         .map((rule) => rule.id),
       // Rules the deploy itself applies; the deploy refusal names them, and no read reports them beforehand.
-      checkedAtDeploy: SITE_CHECK_RULES.filter((rule) => !rule.runsAt.includes("validate") && !rule.runsAt.includes("health"))
-        .map((rule) => rule.id),
-      ...(pagesComplete ? {} : { skipped: ["link.page_missing"] }),
+      checkedAtDeploy: SITE_CHECK_RULES.filter((rule) =>
+        !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && rule.runsAt.includes("deploy")
+      ).map((rule) => rule.id),
+      // Rules only the page editor evaluates: a cover, a description field, or a description's length (which the CLI reports as descriptionWarnings).
+      checkedInEditor: SITE_CHECK_RULES.filter((rule) =>
+        !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && !rule.runsAt.includes("deploy")
+        && rule.runsAt.includes("edit")
+      ).map((rule) => rule.id),
+      // A rule that had nothing to read: a truncated page manifest, or a workspace with no form files.
+      ...(pagesComplete && formKeysChecked
+        ? {}
+        : { skipped: [...(pagesComplete ? [] : ["link.page_missing"]), ...(formKeysChecked ? [] : ["form.key_unknown"])] }),
     },
   };
 }

package/src/site-check-rules.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "about": "The catalogue of site checks (TR01085). Severity: 'error' blocks a deploy, 'warning' informs. Scope: 'page' rules read one page body, 'site' rules read the site's own records. runsAt names the run points that evaluate the rule: save, validate (the CLI, offline), deploy, health. subject and detail say what a finding's two values hold. The typed registry in Taproot.Domain/SiteChecks/SiteCheckRules.cs must list the same rules; SiteCheckTests fails on a difference.",
-  "runPoints": ["save", "validate", "deploy", "health"],
+  "about": "The catalogue of site checks (TR01085, TR00947). Severity: 'error' blocks a deploy, 'warning' informs. Scope: 'page' rules read one page body plus cheap site lookups, 'site' rules read the site's own records, 'document' rules read only one document and its metadata, so the editor and the CLI evaluate them from shared/page-structure-checks.ts and the server does not. runsAt names the run points that evaluate the rule: save, validate (the CLI, offline), deploy, health, edit (the editor, over the open document in the browser). appliesTo, when present, limits a rule to those page types. subject and detail say what a finding's two values hold. The typed registry in Taproot.Domain/SiteChecks/SiteCheckRules.cs must list the same rules; SiteCheckTests fails on a difference.",
+  "runPoints": ["save", "validate", "deploy", "health", "edit"],
   "rules": [
     { "id": "link.page_missing", "severity": "warning", "scope": "page", "runsAt": ["save", "validate", "health"], "subject": "page_path", "detail": "none" },
     { "id": "image.missing", "severity": "warning", "scope": "page", "runsAt": ["save", "health"], "subject": "image_id", "detail": "none" },
@@ -9,14 +9,27 @@
     { "id": "form.unreadable", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "form_reference_text", "detail": "none" },
     { "id": "form.missing", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "form_id", "detail": "none" },
     { "id": "form.archived", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "form_id", "detail": "form_name" },
+    { "id": "form.not_supported_on_site_type", "severity": "error", "scope": "page", "runsAt": ["save", "health"], "subject": "none", "detail": "none" },
     { "id": "form.after_submit_page_unpublished", "severity": "error", "scope": "site", "runsAt": ["deploy"], "subject": "page_path", "detail": "form_name" },
     { "id": "form.after_submit_page_not_allowed", "severity": "error", "scope": "site", "runsAt": ["deploy"], "subject": "page_path", "detail": "form_name" },
+    { "id": "form.key_unknown", "severity": "error", "scope": "site", "runsAt": ["validate"], "subject": "form_key", "detail": "none" },
     { "id": "redirect.source_invalid", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "none" },
     { "id": "redirect.source_index_html", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_integration_data", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_share_link", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_runtime_mirror", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_generated_file", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
-    { "id": "redirect.source_not_storable", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" }
+    { "id": "redirect.source_not_storable", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
+    { "id": "seo.h1_missing", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "none", "detail": "none" },
+    { "id": "seo.h1_demoted", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "h1_claimant" },
+    { "id": "seo.h1_multiple", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "h1_claimant" },
+    { "id": "seo.heading_renumbered", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "authored_and_published_level" },
+    { "id": "seo.heading_before_title", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "published_level" },
+    { "id": "a11y.image_alt_missing", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "image_id", "detail": "none" },
+    { "id": "a11y.link_text_empty", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "link_target", "detail": "none" },
+    { "id": "seo.title_long", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.description_missing", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit"], "subject": "none", "detail": "none" },
+    { "id": "seo.description_long", "severity": "warning", "scope": "document", "runsAt": ["edit"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.social_image_fallback", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["edit"], "subject": "none", "detail": "social_image_source" }
   ]
 }

package/src/site-checks.js

@@ -15,6 +15,7 @@
  * and re-run it.
  */
 export const RULE_LINK_PAGE_MISSING = "link.page_missing";
+export const RULE_FORM_KEY_UNKNOWN = "form.key_unknown";
 export const RULE_REDIRECT_SOURCE_INVALID = "redirect.source_invalid";
 export const RULE_REDIRECT_SOURCE_INDEX_HTML = "redirect.source_index_html";
 export const RULE_REDIRECT_SOURCE_INTEGRATION_DATA = "redirect.source_integration_data";
@@ -222,6 +223,21 @@ export function missingPageLinkFindings(templateData, currentPagePath, knownPath
         .filter((link) => !knownPaths.has(normalizeStoredPath(link).toLowerCase()))
         .map((link) => ({ ruleId: RULE_LINK_PAGE_MISSING, severity: "warning", subject: link, detail: "" }));
 }
+/**
+ * The `form.key_unknown` findings (TR01081): every placed form key that no form file of the
+ * workspace has. A workspace names a form by key (`forms/<key>.json`); the server stores the id.
+ * `knownKeys` is the workspace's own form keys, and a caller with no form files passes nothing
+ * to check, since a workspace for a site whose forms were created elsewhere must still push.
+ */
+export function unknownFormKeyFindings(placedKeys, knownKeys) {
+    const findings = [];
+    for (const key of new Set(placedKeys)) {
+        if (!knownKeys.has(key)) {
+            findings.push({ ruleId: RULE_FORM_KEY_UNKNOWN, severity: "error", subject: key, detail: "" });
+        }
+    }
+    return findings;
+}
 // ---------------------------------------------------------------- redirects
 const RUNTIME_MIRROR_PATH = /^taproot\/[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\/|$)/iu;
 /** Whether a site-relative path (no leading slash) is `taproot/<semver>` or under it. */

package/src/theme-projection.js

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

package/src/theme-validation.js

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

package/src/verbs/pages-push.js

@@ -22,6 +22,7 @@ import {
 import { VERB_PAGES_PUSH } from "../constants.js";
 import { autolinkWarnings } from "../content/link-warnings.js";
 import { placedFormKeys, readFormIndex, withFormIds } from "../form-references.js";
+import { workspaceFormKeys } from "../forms-workspace.js";
 import { ApiError } from "../transport.js";
 import { waitForProcessing } from "./media-upload.js";
 import { SiteAuthoringError } from "../errors.js";
@@ -883,9 +884,11 @@ export async function placedVideoProblems(client, siteId, planned) {
  * The pages that place a form the site does not have, or has archived, and the
  * site's forms by key for the wire (TR01216). A page is stored with the form's id,
  * so a key that names no active form cannot be sent at all. Pages that will not be
- * sent are not asked about, and a push that places no form reads nothing.
+ * sent are not asked about, and a push that places no form reads nothing. `readLocalFormKeys`, when given,
+ * reads the workspace's own form files (TR01081), only once a key turns out to be one the site lacks, so the
+ * refusal can say whether the key's file is there to push.
  */
-export async function placedFormProblems(client, siteId, planned) {
+export async function placedFormProblems(client, siteId, planned, readLocalFormKeys) {
   const placements = new Map();
   for (const page of planned) {
     if (page.unchanged) continue;
@@ -897,8 +900,14 @@ export async function placedFormProblems(client, siteId, planned) {
 
   const index = await readFormIndex(client, siteId);
   const problems = [];
+  let localFormKeys;
+  let localRead = false;
   for (const [key, file] of placements) {
     if (index.idByKey.has(key)) continue;
+    if (!localRead && !index.archivedKeys.has(key) && readLocalFormKeys !== undefined) {
+      localFormKeys = await readLocalFormKeys();
+      localRead = true;
+    }
     problems.push(...problemsOf(
       index.archivedKeys.has(key)
         ? documentError(
@@ -909,8 +918,11 @@ export async function placedFormProblems(client, siteId, planned) {
         )
         : documentError(
           "pages.form_unknown",
-          `'${file}' places the form '${key}', which this site does not have. Run 'taproot-site forms push' to create `
-            + "it, or fix the key.",
+          localFormKeys?.has(key) === false
+            ? `'${file}' places the form '${key}', which this site does not have, and the workspace has no forms/${key}.json. `
+              + "Add the form file and run 'taproot-site forms push', or fix the key."
+            : `'${file}' places the form '${key}', which this site does not have. Run 'taproot-site forms push' to create `
+              + "it, or fix the key.",
           file,
         ),
       { area: CHECK_AREA.pages, file },
@@ -1607,7 +1619,7 @@ export async function pagesPush(invocation) {
     // publishing would then refuse.
     plan.problems.push(...await placedVideoProblems(client, siteId, planned));
     // Likewise a form: pages store its id, which only the site's own forms can supply.
-    const placedForms = await placedFormProblems(client, siteId, planned);
+    const placedForms = await placedFormProblems(client, siteId, planned, () => workspaceFormKeys(config.workspaceDir));
     plan.problems.push(...placedForms.problems);
 
     // Under apply, the workspace read ledger has already held every source and

package/src/verbs/plan.js

@@ -27,6 +27,7 @@ import { sharedThemeContextNames } from "../content/free-form-sections.js";
 import { SiteAuthoringError } from "../errors.js";
 import { computeFooterContentHash, computeFooterDraftHash, stableJson } from "../footer-draft-hash.js";
 import { FOOTER_SETTINGS_FILE } from "../footer-workspace.js";
+import { workspaceFormKeys } from "../forms-workspace.js";
 import { CHECK_AREA, collectProblems, problemsError, problemsOf, problemsWithinBudget, withinByteBudget } from "../problems.js";
 import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { IMAGE_IDENTIFIER, usedImageIds } from "../typed-pages.js";
@@ -284,7 +285,7 @@ async function preflight(session, invocation) {
     });
     problems.push(...pages.problems);
     problems.push(...await placedVideoProblems(client, siteId, pages.planned));
-    problems.push(...(await placedFormProblems(client, siteId, pages.planned)).problems);
+    problems.push(...(await placedFormProblems(client, siteId, pages.planned, () => workspaceFormKeys(workspaceDir))).problems);
     const sending = pages.planned.filter((page) => !page.unchanged);
 
     // An image a page names must be one the site holds; an image this plan

package/src/verbs/validate.js

@@ -659,6 +659,7 @@ function offlineSiteChecks(checked, manifest, onProgress) {
     planned: checked.pages?.planned,
     pagePaths: manifest.pages.map((entry) => normalizePagePath(entry?.path)).filter((value) => value !== undefined),
     pagesComplete: manifest.pagesTruncated !== true,
+    formKeysChecked: checked.formKeysChecked === true,
     onProgress,
   });
 }
@@ -782,7 +783,8 @@ export async function validateFixture(invocation = {}) {
       "remote concurrency or current revisions",
       "server normalization and pull round trips",
       "the site checks listed in siteChecks.checkedBySite (images, forms), which 'taproot-site status' reports under "
-        + "siteHealth, or siteChecks.checkedAtDeploy, which only a deploy applies",
+        + "siteHealth, siteChecks.checkedAtDeploy, which only a deploy applies, or siteChecks.checkedInEditor, "
+        + "which only the page editor evaluates (a cover, a description field, or a description's length)",
       "preview or published rendering",
     ],
     nextStep: "Run a real pull and authorized preview before approval or deployment.",
@@ -846,7 +848,8 @@ async function validatePulledWorkspace(workspaceDir, siteId, invocation, onProgr
       "pages, revisions, or videos that changed on the site since the pull",
       "server normalization and pull round trips",
       "the site checks listed in siteChecks.checkedBySite (images, forms), which 'taproot-site status' reports under "
-        + "siteHealth, or siteChecks.checkedAtDeploy, which only a deploy applies",
+        + "siteHealth, siteChecks.checkedAtDeploy, which only a deploy applies, or siteChecks.checkedInEditor, "
+        + "which only the page editor evaluates (a cover, a description field, or a description's length)",
       "preview or published rendering",
     ],
     nextStep: "Run 'taproot-site plan' to check the workspace against the live site and see the ordered apply.",

package/src/workspace-check.js

@@ -1,6 +1,10 @@
 import { sharedThemeContextNames } from "./content/free-form-sections.js";
 import { readAppearanceWorkspaceContext, FOOTER_SETTINGS_FILE } from "./footer-workspace.js";
+import { placedFormKeys } from "./form-references.js";
+import { FORMS_DIRECTORY } from "./forms-contract.js";
 import { readWorkspaceForms } from "./forms-workspace.js";
+import { describeSiteFinding } from "./site-check-findings.js";
+import { unknownFormKeyFindings } from "./site-checks.js";
 import { CHECK_AREA, collectProblems, problemsOf } from "./problems.js";
 import { normalizeRedirectPath, REDIRECTS_FILE_NAME, validateRedirectsDocument } from "./redirects-contract.js";
 import { SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES } from "./settings-catalog.js";
@@ -16,6 +20,7 @@ import {
   readWorkspaceJson,
   walkWorkspaceFiles,
   WORKSPACE_LIMITS,
+  workspaceDirectoryExists,
   workspaceFileExists,
 } from "./workspace.js";
 import { SiteAuthoringError } from "./errors.js";
@@ -135,7 +140,27 @@ export async function checkWorkspace({
     onProgress(`Validated ${forms.length} form file${forms.length === 1 ? "" : "s"} against the shared field schema.`);
   }
 
-  return { problems, settingsOnly, presentation, footer, navigation, pages, redirects, forms };
+  // A page places a form by key, and the workspace's form files are what a key can name (TR01081). Only
+  // when the workspace carries a forms/ directory: one for a site whose forms were created elsewhere still
+  // pushes. A directory with no files left in it counts, since that is what deleting the last form leaves.
+  const formKeysChecked = forms !== undefined && await workspaceDirectoryExists(workspaceDir, FORMS_DIRECTORY);
+  if (pages !== undefined && formKeysChecked) {
+    const known = new Set(forms.map((form) => form.key));
+    for (const page of pages.planned) {
+      for (const finding of unknownFormKeyFindings(placedFormKeys(page.document), known)) {
+        problems.push(...problemsOf(
+          new SiteAuthoringError(
+            "pages.form_unknown",
+            `'${page.file}' ${describeSiteFinding(finding)}.`,
+            { field: page.file, rule: finding.ruleId },
+          ),
+          { area: CHECK_AREA.pages, file: page.file },
+        ));
+      }
+    }
+  }
+
+  return { problems, settingsOnly, presentation, footer, navigation, pages, redirects, forms, formKeysChecked };
 }
 
 /**

package/src/workspace.js

@@ -1088,6 +1088,11 @@ export async function deleteWorkspaceFile(workspaceDir, relativePath) {
   return true;
 }
 
+/** Whether the workspace has this directory (a link or a file in its place is refused, as everywhere). */
+export async function workspaceDirectoryExists(workspaceDir, relativePath) {
+  return await requireRealDirectoryChain(workspaceDir, relativePath, { includeLeaf: true });
+}
+
 /**
  * Collects the workspace files a push verb should consider, in a stable sorted
  * order so two runs of the same workspace produce the same request sequence.