@taprootio/site-authoring 0.20.0 → 0.22.0

package/src/verbs/changelog.js

@@ -0,0 +1,62 @@
+import {
+  changelogEntriesSince,
+  changelogEntryFor,
+  earliestRecordedVersion,
+} from "../changelog.js";
+import { compareCliVersions } from "../cli-release.js";
+import { CLI_UPGRADE_COMMAND, CLI_VERSION, VERB_CHANGELOG } from "../constants.js";
+import { successResult } from "../session.js";
+
+/**
+ * `changelog [--since <version>]` — what changed in each release, offline.
+ *
+ * Only the latest CLI is accepted, so an upgrade is forced often and the agent
+ * that meets it needs to know what moved without diffing every help topic
+ * (TR01225). With no version it prints the installed release's entry; with
+ * `--since` it prints every release after that one, up to the installed one. It
+ * reads the package's own record, needs no sign-in or site, and is outside the
+ * outdated-CLI gate on purpose: it is how the upgraded CLI explains itself.
+ */
+export async function changelog(invocation) {
+  const onProgress = invocation.onProgress ?? (() => {});
+  const since = invocation.since;
+  const installed = changelogEntryFor(CLI_VERSION);
+  const entries = since === undefined
+    ? installed === undefined ? [] : [installed]
+    : changelogEntriesSince(since);
+  const earliest = earliestRecordedVersion();
+  const startsBeforeRecord = since !== undefined && earliest !== undefined && compareCliVersions(since, earliest) < 0;
+
+  const notes = [];
+  if (since !== undefined && compareCliVersions(since, CLI_VERSION) >= 0) {
+    notes.push(
+      `This CLI is ${CLI_VERSION}, which is not newer than ${since}. Upgrade with: ${CLI_UPGRADE_COMMAND}, then run this again.`,
+    );
+  } else if (entries.length === 0) {
+    notes.push(`No changelog entry is recorded for ${CLI_VERSION}.`);
+  }
+  if (startsBeforeRecord) {
+    notes.push(`The record starts at ${earliest}; changes before it are not listed.`);
+  }
+
+  for (const entry of entries) {
+    onProgress(`${entry.version}${entry.date === undefined ? "" : ` (${entry.date})`}: ${entry.note}`);
+    for (const line of entry.behavior) onProgress(`  - ${line}`);
+    if (entry.help.length > 0) onProgress(`  Help changed: ${entry.help.map((topic) => `help ${topic}`).join(", ")}`);
+  }
+  for (const note of notes) onProgress(note);
+
+  return successResult(VERB_CHANGELOG, undefined, {
+    installedVersion: CLI_VERSION,
+    ...(since === undefined ? {} : { since }),
+    entries: entries.map((entry) => ({
+      version: entry.version,
+      ...(entry.date === undefined ? {} : { date: entry.date }),
+      note: entry.note,
+      behavior: [...entry.behavior],
+      help: [...entry.help],
+    })),
+    complete: !startsBeforeRecord,
+    ...(notes.length === 0 ? {} : { notes }),
+  });
+}

package/src/verbs/deploy.js

@@ -15,6 +15,7 @@ import {
 import {
   DEPLOY_TARGET_PRODUCTION,
   DEPLOY_TARGET_STAGING,
+  LIMITS,
   REFUSAL_CAPABILITY_MISSING,
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_UNCLASSIFIED,
@@ -23,23 +24,28 @@ import {
 } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
-import { inspectStagingPreview } from "../staging-check.js";
+import { HANDOFF_NOT_REQUESTED_PROGRESS, handoffNotRequested, inspectStagingPreview } from "../staging-check.js";
+import { confirmStagingServed, readStagingReleaseBefore, unverifiedStagingServed } from "../staging-served.js";
 import { ApiError } from "../transport.js";
 import { readManifest, writeManifest } from "../workspace.js";
 
 /**
- * When a redirect goes live (TR00702, TR00968).
+ * When a redirect goes live (TR00702, TR00968, TR01236).
  *
  * A redirect or gone entry is a file inside the release this deploy publishes.
  * It goes live with that release and no other way: staging shows it as soon as
  * the staged release is served, production shows it when the release is
- * promoted. There is no separate store to wait on, so a check that does not see
- * an entry is looking at a release that does not carry it yet.
+ * promoted. The release itself reaches the edge after the deployment reports
+ * completed: Cloudflare propagates the route and the Worker caches it, so the
+ * previous release can answer for about two minutes (the note below quotes the
+ * ceiling). A check that does not see an entry is looking at a release that is
+ * not served yet.
  */
 const REDIRECT_ACTIVATION_NOTE =
   "Redirect and gone entries live inside the release this deploy publishes: staging serves them with the staged "
-  + "release and production serves them once that release is promoted. There is no separate propagation delay; "
-  + "an entry a check does not see belongs to a release that is not being served yet.";
+  + "release and production serves them once that release is promoted. The edge can keep serving the previous "
+  + `release for up to ${LIMITS.stagingPropagationCeilingSeconds} seconds after a deployment completes, so an entry a `
+  + "check does not see may belong to a release the edge has not switched to yet.";
 
 /**
  * `deploy --staging` / `deploy --production` — readiness, deploy, poll to
@@ -208,9 +214,9 @@ function presentationHandoffUnavailable(error) {
  * It is minted after the deployment completed, bound by the server to the
  * site's exact acknowledged staging host, and single-use like every other.
  */
-async function mintPresentationStagingHandoff(client, siteId, onProgress, now) {
+async function mintPresentationStagingHandoff(client, siteId, onProgress, now, returnPath) {
   try {
-    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now, returnPath });
     onProgress(`Staging review handoff minted for ${handoff.stagingUrl}. ${PRESENTATION_REVIEW_GUIDANCE}`);
     return { ...handoff, review: PRESENTATION_REVIEW_GUIDANCE };
   } catch (error) {
@@ -387,6 +393,9 @@ export async function deploy(invocation) {
       }
     }
 
+    // The release staging serves now, so the wait after completion can tell when the new one replaces it
+    // (TR01236). A managed Docs site's pages carry no release stamp, so it is not read there.
+    const servedBefore = presentationOnly ? undefined : await readStagingReleaseBefore(client, siteId, now);
     const created = await deploySite(client, siteId, {
       siteId,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,
@@ -405,8 +414,22 @@ export async function deploy(invocation) {
       now,
     });
     await recordDeployment(config, manifest, "staging", completed);
+    const stagingServed = presentationOnly
+      ? unverifiedStagingServed(now(), "A managed Docs site's staging is not checked for the served release.")
+      : await confirmStagingServed(client, siteId, {
+        before: servedBefore,
+        deploymentId: created.id,
+        coalesced: created.outcome === DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
+        onProgress,
+        now,
+      });
+    if (stagingServed.state !== "served") onProgress(`Warning: ${stagingServed.message}`);
     if (presentationOnly) {
-      const stagingPreview = await mintPresentationStagingHandoff(client, siteId, onProgress, now);
+      // The review URL is a live credential, so it is minted only when asked for (TR01233).
+      if (invocation.handoff !== true) onProgress(HANDOFF_NOT_REQUESTED_PROGRESS);
+      const stagingPreview = invocation.handoff === true
+        ? await mintPresentationStagingHandoff(client, siteId, onProgress, now, invocation.reviewPath)
+        : handoffNotRequested();
       return successResult(VERB_DEPLOY, siteId, {
         target,
         environment: DEPLOYMENT_ENVIRONMENT_STAGING,
@@ -419,11 +442,15 @@ export async function deploy(invocation) {
         deployment: completed,
         outcome: created.outcome,
         readiness: reportReadiness(readiness),
+        stagingServed,
         stagingPreview,
         nextStep: stagingPreview.url === "" ? "staging review" : "deploy --production",
       });
     }
-    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now);
+    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now, {
+      handoff: invocation.handoff === true,
+      returnPath: invocation.reviewPath,
+    });
     onProgress(REDIRECT_ACTIVATION_NOTE);
     return successResult(VERB_DEPLOY, siteId, {
       target,
@@ -436,6 +463,7 @@ export async function deploy(invocation) {
       deployment: completed,
       outcome: created.outcome,
       readiness: reportReadiness(readiness),
+      stagingServed,
       routeCheck,
       redirects,
       stagingPreview,

package/src/verbs/index.js

@@ -5,6 +5,7 @@ import {
   VERB_AUTHORS_LIST,
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
+  VERB_CHANGELOG,
   VERB_ENV,
   VERB_FOOTER_PUSH,
   VERB_FORMS_PULL,
@@ -38,6 +39,7 @@ import {
 } from "../constants.js";
 import { approve } from "./approve.js";
 import { authorsAdd, authorsList } from "./authors.js";
+import { changelog } from "./changelog.js";
 import { deliveryCheck } from "./delivery-check.js";
 import { deploy } from "./deploy.js";
 import { env } from "./env.js";
@@ -174,6 +176,7 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_USE]: use,
   [VERB_WHOAMI]: whoami,
   [VERB_ENV]: env,
+  [VERB_CHANGELOG]: changelog,
   [VERB_STATUS]: status,
   [VERB_DELIVERY_CHECK]: deliveryCheck,
   [VERB_STAGING_REVIEW]: stagingReview,

package/src/verbs/nav-push.js

@@ -23,6 +23,7 @@ import {
   readWorkspaceJson,
   workspaceFileExists,
   WORKSPACE_LIMITS,
+  writeWorkspaceJson,
 } from "../workspace.js";
 
 /**
@@ -52,7 +53,9 @@ const MAXIMUM_REPORTED = 100;
 const MAXIMUM_ITEMS = 1_000;
 const MAXIMUM_TITLE_LENGTH = 200;
 const MAXIMUM_URL_LENGTH = CONTACT_OR_WEB_URL_MAX_LENGTH;
-const ITEM_KEYS = new Set(["id", "kind", "title", "resourceId", "externalUrl", "children"]);
+// The item keys in the order the workspace file spells them; validation and projection share this list.
+const NAVIGATION_ITEM_KEY_ORDER = Object.freeze(["id", "kind", "title", "resourceId", "externalUrl", "children"]);
+const ITEM_KEYS = new Set(NAVIGATION_ITEM_KEY_ORDER);
 
 // `SaveSiteNavigation` maps both `id` and `resourceId` through
 // `RequestValidation.RequireGuid`. A value that is not a GUID comes back as a
@@ -182,6 +185,36 @@ function validateItem(item, itemPath, depth, seenIds, counters) {
   };
 }
 
+/**
+ * The one workspace spelling of a navigation tree (TR01232): the item keys in a
+ * fixed order, with the fields that only carry a default left out. The API prints
+ * proto3 defaults (`externalUrl: ""`, `children: []`) and `nav push` validates into
+ * the same full shape, so without this a pull after a push rewrote nav.json with
+ * values nobody wrote. Both `pull` and `nav push` write this form, and either form
+ * is accepted on the way in.
+ */
+export function projectNavigationForWorkspace(items) {
+  if (!Array.isArray(items)) return items;
+  return items.map((item) => {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) return item;
+    const projected = {};
+    const keys = [
+      ...NAVIGATION_ITEM_KEY_ORDER.filter((key) => Object.hasOwn(item, key)),
+      ...Object.keys(item).filter((key) => !NAVIGATION_ITEM_KEY_ORDER.includes(key)),
+    ];
+    for (const key of keys) {
+      const value = item[key];
+      if ((key === "resourceId" || key === "externalUrl") && value === "") continue;
+      if (key === "children" && Array.isArray(value)) {
+        if (value.length > 0) projected.children = projectNavigationForWorkspace(value);
+        continue;
+      }
+      projected[key] = value;
+    }
+    return projected;
+  });
+}
+
 function collectIds(items, into = new Set()) {
   for (const item of items) {
     if (item === null || typeof item !== "object") continue;
@@ -325,6 +358,21 @@ export async function navPush(invocation) {
 
     const saved = await saveNavigation(client, siteId, navItems);
     onProgress(`Replaced the navigation tree with ${validated.items} items.`);
+    try {
+      // The file now holds what the site stored, in the form pull writes, so the next pull is byte-identical.
+      const stored = saved.length > 0 || navItems.length === 0 ? saved : navItems;
+      // siteId and navItems first, in pull's order; any other key the author kept follows.
+      const { siteId: _siteId, navItems: _navItems, ...extras } = parsed;
+      await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, {
+        siteId,
+        navItems: projectNavigationForWorkspace(stored),
+        ...extras,
+      });
+    } catch (error) {
+      // The site already holds the new tree; only the local file is stale, so say the tree was replaced.
+      if (error instanceof SiteAuthoringError) throw error.withCompletedWrites(["navigationTree"]);
+      throw error;
+    }
 
     const removedReport = boundedList(removed, MAXIMUM_REPORTED);
     const addedReport = boundedList(added, MAXIMUM_REPORTED);

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/pull.js

@@ -23,6 +23,7 @@ import { appearanceManifestEntry, footerManifestEntry, presentationManifestEntry
 import { describeJsonDifferences, reportableDifferencePaths } from "../json-path-diff.js";
 import { projectRedirectMapForWorkspace, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
 import { redirectsManifestEntry } from "../redirects-workspace.js";
+import { projectNavigationForWorkspace } from "./nav-push.js";
 import { boundedList, openSession, successResult } from "../session.js";
 import {
   projectSettingsGroup,
@@ -1314,7 +1315,10 @@ export async function pull(invocation) {
     if (!presentationOnly) {
       onProgress("Reading the navigation tree.");
       navItems = await getNavigation(client, siteId);
-      await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, { siteId, navItems });
+      await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, {
+        siteId,
+        navItems: projectNavigationForWorkspace(navItems),
+      });
     }
 
     if (redirectMap !== undefined) {

package/src/verbs/redirects-check.js

@@ -6,7 +6,10 @@ import { inspectStagingPreview } from "../staging-check.js";
 export async function redirectsCheck(invocation) {
   const { client, siteId, onProgress, now } = await openSession(invocation);
   return await withRefusalGuidance(onProgress, "staging redirects", async () => {
-    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now);
+    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now, {
+      handoff: invocation.handoff === true,
+      returnPath: invocation.reviewPath,
+    });
     return successResult(VERB_REDIRECTS_CHECK, siteId, { routeCheck, redirects, stagingPreview });
   });
 }

package/src/verbs/staging-review.js

@@ -20,7 +20,7 @@ export async function stagingReview(invocation) {
   const { client, siteId, now, onProgress } = await openSession(invocation);
   return await withRefusalGuidance(onProgress, "staging review", async () => {
     onProgress("Minting a fresh single-use staging review handoff.");
-    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now, returnPath: invocation.reviewPath });
     onProgress(`Staging review handoff minted for ${handoff.stagingUrl}. ${STAGING_REVIEW_GUIDANCE}`);
     return successResult(VERB_STAGING_REVIEW, siteId, {
       stagingPreview: { ...handoff, review: STAGING_REVIEW_GUIDANCE },

package/src/verbs/status.js

@@ -1,15 +1,17 @@
 import {
   getDeploySelection,
   getPublishingReadiness,
-  getSiteBrokenReferences,
+  getSiteHealth,
   IMAGE_PROCESSING_STATE_COMPLETE,
   IMAGE_PROCESSING_STATE_FAILED,
   listDeployments,
   listSiteImages,
   withRefusalGuidance,
 } from "../api.js";
+import { installedWhatsNew } from "../changelog.js";
 import { isBehindLatest } from "../cli-release.js";
 import {
+  changelogCommandSince,
   CLI_UPGRADE_COMMAND,
   CLI_VERSION,
   EXTERNAL_WRITES_SETTING_KEY,
@@ -24,13 +26,12 @@ import { boundedList, openSession, successResult } from "../session.js";
 
 /**
  * `status` — the platform authoring switch, CLI release, deployments,
- * publishing readiness, image processing, and broken-reference pages.
+ * publishing readiness, image processing, and the site checks' findings.
  */
 const MAXIMUM_DEPLOYMENTS = 20;
 const MAXIMUM_FAILED_IMAGES = 50;
 const MAXIMUM_BLOCKERS = 50;
-const MAXIMUM_BROKEN_REFERENCE_PAGES = 50;
-const MAXIMUM_MISSING_TARGETS = 50;
+const MAXIMUM_HEALTH_FINDINGS = 100;
 
 const PLATFORM_UNKNOWN_NOTE =
   "Taproot never reported the platform authoring switch on this run: either no sign-in token exchange happened "
@@ -61,9 +62,15 @@ const CLI_RELEASE_UNKNOWN_NOTE =
  */
 function reportCliRelease(release, onProgress) {
   const latestVersion = release?.latestVersion;
+  // The installed release's one-line note, from the same record `changelog` prints.
+  const whatsNew = installedWhatsNew();
+  const whatsNewField = whatsNew === undefined ? {} : { whatsNew };
+  if (whatsNew !== undefined) {
+    onProgress(`What's new in ${CLI_VERSION}: ${whatsNew.note} ('${changelogCommandSince("<version>")}' lists the details.)`);
+  }
   if (latestVersion === undefined) {
     onProgress(`CLI release: ${CLI_VERSION}. Latest not known on this run. ${CLI_RELEASE_UNKNOWN_NOTE}`);
-    return { version: CLI_VERSION, latestKnown: false, reason: CLI_RELEASE_UNKNOWN_NOTE };
+    return { version: CLI_VERSION, latestKnown: false, reason: CLI_RELEASE_UNKNOWN_NOTE, ...whatsNewField };
   }
   const behind = isBehindLatest(latestVersion);
   onProgress(
@@ -71,9 +78,16 @@ function reportCliRelease(release, onProgress) {
       ? `CLI release: ${CLI_VERSION} is BEHIND the latest published release ${latestVersion}, and Taproot accepts `
         + `only the latest, so every online verb is refused (refusal=${REFUSAL_CLI_OUTDATED}). Upgrade with: `
         + CLI_UPGRADE_COMMAND
+        + `. Once upgraded, run '${changelogCommandSince(CLI_VERSION)}' to see what changed.`
       : `CLI release: ${CLI_VERSION}; latest published release ${latestVersion}.`,
   );
-  return { version: CLI_VERSION, latestVersion, behind };
+  return {
+    version: CLI_VERSION,
+    latestVersion,
+    behind,
+    ...whatsNewField,
+    ...(behind ? { changelogCommand: changelogCommandSince(CLI_VERSION) } : {}),
+  };
 }
 
 /**
@@ -104,12 +118,12 @@ function reportPlatform(platform, onProgress) {
 /**
  * What a managed Docs site's status leaves out (TR00790), said the same way
  * the platform switch says "unknown": by shape. The image library and the
- * broken-reference report are page-authoring reads a Docs site refuses, so
+ * site-health read are page-authoring reads a Docs site refuses, so
  * they are reported as not covered rather than as empty — an automation
  * reading `failed: 0` off a report that was never made would be reading a lie.
  */
 const DOCS_SITE_NOT_COVERED_NOTE =
-  "This is a managed Docs site: its pages come from the Docs artifact, so the image library and broken-reference "
+  "This is a managed Docs site: its pages come from the Docs artifact, so the image library and site-health "
   + "reads do not apply and were not made.";
 
 export async function status(invocation) {
@@ -144,25 +158,14 @@ export async function status(invocation) {
     let images = [];
     let summary = { totalImages: 0, processingImages: 0 };
     let truncated = false;
-    let brokenReferencePages = [];
+    let health = { findings: [], errorCount: 0, warningCount: 0, pageCount: 0, truncated: false };
     if (!presentationOnly) {
       onProgress("Reading image processing state.");
       ({ images, summary, truncated } = await listSiteImages(client, siteId));
-      onProgress("Reading broken references.");
-      brokenReferencePages = await getSiteBrokenReferences(client, siteId);
+      onProgress("Reading site health.");
+      health = await getSiteHealth(client, siteId);
     }
-    const reportedBrokenPages = boundedList(brokenReferencePages, MAXIMUM_BROKEN_REFERENCE_PAGES);
-    const brokenPages = reportedBrokenPages.items.map((page) => {
-      const images = boundedList(page.missingImageIds, MAXIMUM_MISSING_TARGETS);
-      const paths = boundedList(page.missingPagePaths, MAXIMUM_MISSING_TARGETS);
-      return {
-        ...page,
-        missingImageIds: images.items,
-        missingPagePaths: paths.items,
-        ...(images.truncated ? { missingImageIdsTruncated: true } : {}),
-        ...(paths.truncated ? { missingPagePathsTruncated: true } : {}),
-      };
-    });
+    const reportedFindings = boundedList(health.findings, MAXIMUM_HEALTH_FINDINGS);
 
     const byState = {};
     for (const image of images) {
@@ -182,7 +185,9 @@ export async function status(invocation) {
     const blockers = boundedList(readiness.blockers, MAXIMUM_BLOCKERS);
 
     if (!presentationOnly) {
-      onProgress(`Broken references: ${brokenReferencePages.length} page(s) with missing targets.`);
+      onProgress(
+        `Site health: ${health.errorCount} problem(s) and ${health.warningCount} warning(s) on ${health.pageCount} page(s).`,
+      );
     }
 
     return successResult(VERB_STATUS, siteId, {
@@ -221,11 +226,13 @@ export async function status(invocation) {
         ...(failedImages.truncated ? { failedItemsTruncated: true } : {}),
         ...(truncated ? { listTruncated: true } : {}),
       },
-      brokenReferences: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
+      siteHealth: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
         covered: true,
-        totalPages: brokenReferencePages.length,
-        pages: brokenPages,
-        ...(reportedBrokenPages.truncated ? { pagesTruncated: true } : {}),
+        errors: health.errorCount,
+        warnings: health.warningCount,
+        pages: health.pageCount,
+        findings: reportedFindings.items,
+        ...(reportedFindings.truncated || health.truncated ? { findingsTruncated: true } : {}),
       },
     });
   });

package/src/verbs/validate.js

@@ -22,6 +22,7 @@ import { authorWarnings, descriptionWarnings } from "../page-metadata.js";
 import { CHECK_AREA, collectProblems, refuseProblems } from "../problems.js";
 import { isRedirectMapRevision, REDIRECT_KIND_GONE, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
 import { boundedList, successResult } from "../session.js";
+import { evaluateOfflineSiteChecks } from "../site-check-findings.js";
 import { SETTINGS_GROUPS } from "../settings-catalog.js";
 import { checkWorkspace } from "../workspace-check.js";
 import {
@@ -648,6 +649,21 @@ function pageHints(checked, onProgress) {
   return hints;
 }
 
+/**
+ * The offline site checks (TR01085) over the planned pages: the rules the shared
+ * catalogue lists for `validate`, with the rest named as checked by the site.
+ */
+function offlineSiteChecks(checked, manifest, onProgress) {
+  if (checked.settingsOnly) return {};
+  return evaluateOfflineSiteChecks({
+    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,
+  });
+}
+
 export async function validateFixture(invocation = {}) {
   if (invocation.init) return await initializeFixture(invocation, validateFixture);
   const onProgress = typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
@@ -736,6 +752,7 @@ export async function validateFixture(invocation = {}) {
     ...autolinkWarnings(checked.pages?.planned, onProgress),
     ...descriptionWarnings(checked.pages?.planned, onProgress),
     ...authorWarnings(checked.pages?.planned, onProgress),
+    ...offlineSiteChecks(checked, manifest, onProgress),
   };
   onProgress(
     `Validated ${validatedPages.length} page(s), ${checked.navigation.items} navigation item(s), two themes, appearance, and footer without credentials or mutation.`,
@@ -765,6 +782,9 @@ export async function validateFixture(invocation = {}) {
       "credential authorization or live site ownership",
       "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, 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.",
@@ -801,6 +821,7 @@ async function validatePulledWorkspace(workspaceDir, siteId, invocation, onProgr
       ...autolinkWarnings(checked.pages.planned, onProgress),
       ...descriptionWarnings(checked.pages.planned, onProgress),
       ...authorWarnings(checked.pages.planned, onProgress),
+      ...offlineSiteChecks(checked, manifest, onProgress),
     };
   onProgress(
     checked.settingsOnly
@@ -826,6 +847,9 @@ async function validatePulledWorkspace(workspaceDir, siteId, invocation, onProgr
       "credential authorization or live site ownership",
       "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, 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 };
 }
 
 /**