@taprootio/site-authoring 0.19.0 → 0.21.0

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/forms-push.js

@@ -5,11 +5,12 @@ import {
   createSiteForm,
   getPageIndex,
   getSiteFormByKey,
+  listSiteForms,
   saveSiteFormVersion,
   updateSiteFormSettings,
 } from "../forms-api.js";
 import { afterSubmitPage, formFileName, projectFormForWorkspace, storedDefinition, validateNewsletterDefinition } from "../forms-contract.js";
-import { readWorkspaceForms, recordedForm, siteSettingsBaseline, withRecordedForm } from "../forms-workspace.js";
+import { comparableFormName, readWorkspaceForms, recordedForm, siteSettingsBaseline, withRecordedForm } from "../forms-workspace.js";
 import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { ApiError } from "../transport.js";
 import { readManifest, writeManifest, writeWorkspaceJson } from "../workspace.js";
@@ -155,6 +156,26 @@ export async function formsPush(invocation) {
     );
   }
 
+  // A form name is unique on the site, ignoring case, so a name another form holds is refused here with
+  // the rest of the checks, not by the first write that reaches it.
+  const naming = plans.filter((plan) => plan.action === "create" || plan.settingsChanged);
+  if (naming.length > 0) {
+    const siteForms = await withRefusalGuidance(onProgress, "forms push", async () => await listSiteForms(client, siteId));
+    for (const plan of naming) {
+      const name = comparableFormName(plan.desired.name);
+      const holder = siteForms.find((siteForm) => siteForm.key !== plan.form.key && comparableFormName(siteForm.name) === name);
+      if (holder !== undefined) {
+        throw new SiteAuthoringError(
+          "forms.name_taken",
+          `${formFileName(plan.form.key)}: the site's form '${holder.key}'${holder.archived ? " (archived)" : ""} already `
+            + `has the name '${plan.desired.name}'. A form name is unique on a site, ignoring case; rename one of them. `
+            + "Nothing was written.",
+          { field: `${formFileName(plan.form.key)}:name` },
+        );
+      }
+    }
+  }
+
   const results = [];
   for (const plan of plans) {
     let { desired } = plan;

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

@@ -21,6 +21,7 @@ import {
 } from "../authors-contract.js";
 import { VERB_PAGES_PUSH } from "../constants.js";
 import { autolinkWarnings } from "../content/link-warnings.js";
+import { placedFormKeys, readFormIndex, withFormIds } from "../form-references.js";
 import { ApiError } from "../transport.js";
 import { waitForProcessing } from "./media-upload.js";
 import { SiteAuthoringError } from "../errors.js";
@@ -878,6 +879,46 @@ export async function placedVideoProblems(client, siteId, planned) {
   return problems;
 }
 
+/**
+ * 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.
+ */
+export async function placedFormProblems(client, siteId, planned) {
+  const placements = new Map();
+  for (const page of planned) {
+    if (page.unchanged) continue;
+    for (const key of placedFormKeys(page.document)) {
+      if (!placements.has(key)) placements.set(key, page.file);
+    }
+  }
+  if (placements.size === 0) return { problems: [], idByKey: new Map() };
+
+  const index = await readFormIndex(client, siteId);
+  const problems = [];
+  for (const [key, file] of placements) {
+    if (index.idByKey.has(key)) continue;
+    problems.push(...problemsOf(
+      index.archivedKeys.has(key)
+        ? documentError(
+          "pages.form_archived",
+          `'${file}' places the form '${key}', which is archived. Restore the form under Site → Forms or remove it `
+            + "from the page.",
+          file,
+        )
+        : 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.",
+          file,
+        ),
+      { area: CHECK_AREA.pages, file },
+    ));
+  }
+  return { problems, idByKey: index.idByKey };
+}
+
 /**
  * Gives each `video-embed` block that has no poster the provider's thumbnail,
  * copied into the site's images by the server (TR01109). One request per provider
@@ -1565,6 +1606,9 @@ export async function pagesPush(invocation) {
     // push, before anything is written, so a page cannot be sent that
     // 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);
+    plan.problems.push(...placedForms.problems);
 
     // Under apply, the workspace read ledger has already held every source and
     // manifest to the plan. What it cannot see is the site: every page the plan
@@ -1634,7 +1678,7 @@ export async function pagesPush(invocation) {
           path: page.pagePath,
           title: page.title,
           shortDescription: page.description,
-          template: wireTemplate(page.document),
+          template: wireTemplate(withFormIds(page.document, placedForms.idByKey)),
           ...wirePageFields(page.document),
           // Only a name the site has not been told: repeating the author a page
           // already has would let a later change of that person's permissions

package/src/verbs/plan.js

@@ -45,6 +45,7 @@ import { navPush, validateNavigationWorkspaceDocument } from "./nav-push.js";
 import {
   liveAuthorsRefresher,
   pagesPush,
+  placedFormProblems,
   placedVideoProblems,
   planPages,
   plannedPageItem,
@@ -283,6 +284,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);
     const sending = pages.planned.filter((page) => !page.unchanged);
 
     // An image a page names must be one the site holds; an image this plan
@@ -433,7 +435,7 @@ function planReport(planned) {
     ready: problems.length === 0,
     steps,
     checked: [
-      "every page source, against the live site's pages, revisions, and video library",
+      "every page source, against the live site's pages, revisions, video library, and the forms it places",
       "media under media/ that pages reference and media upload has not sent",
       "the theme, appearance, and footer colors, against the site's presentation revision",
       "the footer document, against the site's footer draft and the pages it still holds",
@@ -441,7 +443,7 @@ function planReport(planned) {
       "navigation shape and page targets, against the live page list and navigation",
     ],
     notChecked: [
-      "redirects and forms: run 'redirects push' and 'forms push' on their own",
+      "redirects, and the forms files themselves: run 'redirects push' and 'forms push' on their own",
       "rendering: preview pages before approving them",
       "approval, staging, and production, which stay separate commands",
     ],

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,
@@ -33,6 +34,7 @@ import {
   SETTINGS_TYPE_TAPROOT_STYLES,
 } from "../settings-catalog.js";
 import { ApiError } from "../transport.js";
+import { placesFormIds, readFormIndex, withFormKeys } from "../form-references.js";
 import {
   generatedIdentity,
   isAuthorableTemplateType,
@@ -643,6 +645,15 @@ async function requireWorkspaceBelongsToSite(workspaceDir, siteId) {
 
 export async function pull(invocation) {
   const { client, config, siteId, surface, now, onProgress } = await openSession(invocation);
+  // A page names its forms by id on the site and by key in the workspace (TR01216). The
+  // site's forms are read once, and only when a page body places one.
+  let formKeys;
+  const workspaceBodyFromPage = async (page, listedTemplateType) => {
+    const body = workspaceDocumentFromPage(page, listedTemplateType);
+    if (body === undefined || !placesFormIds(body)) return body;
+    formKeys ??= readFormIndex(client, siteId).then((index) => index.keyById);
+    return withFormKeys(body, await formKeys);
+  };
   await ensureWorkspaceRoot(config);
 
   await requireWorkspaceBelongsToSite(config.workspaceDir, siteId);
@@ -891,7 +902,7 @@ export async function pull(invocation) {
       if (source === undefined) continue;
       onProgress(`Reading page '${summary.path}'.`);
       const page = await getPage(client, summary.pageId, bodyStatusFor(summary));
-      const body = workspaceDocumentFromPage(page, summary.templateType);
+      const body = await workspaceBodyFromPage(page, summary.templateType);
       const description = typeof page.shortDescription === "string" ? page.shortDescription : "";
       if (body === undefined) {
         // The site's body is unreadable, but the workspace file is still this
@@ -1261,7 +1272,7 @@ export async function pull(invocation) {
         }
         onProgress(`Reading page '${summary.path}'.`);
         const page = await getPage(client, summary.pageId, bodyStatusFor(summary));
-        const body = workspaceDocumentFromPage(page, summary.templateType);
+        const body = await workspaceBodyFromPage(page, summary.templateType);
         entry.description = typeof page.shortDescription === "string" ? page.shortDescription : "";
         entry.title = titleFromRead(page, summary);
         entry.path = pathFromRead(page, summary);
@@ -1304,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,20 @@ 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,
+    onProgress,
+  });
+}
+
 export async function validateFixture(invocation = {}) {
   if (invocation.init) return await initializeFixture(invocation, validateFixture);
   const onProgress = typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
@@ -736,6 +751,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 +781,8 @@ 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, or siteChecks.checkedAtDeploy, which only a deploy applies",
       "preview or published rendering",
     ],
     nextStep: "Run a real pull and authorized preview before approval or deployment.",
@@ -801,6 +819,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 +845,8 @@ 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, or siteChecks.checkedAtDeploy, which only a deploy applies",
       "preview or published rendering",
     ],
     nextStep: "Run 'taproot-site plan' to check the workspace against the live site and see the ordered apply.",