@taprootio/site-authoring 0.20.0 → 0.21.0

package/README.md

@@ -119,6 +119,22 @@ dark logo on the rendered dark header at desktop and compact/mobile widths;
 transparent canvas pixels do not count as contrast. Supply separate
 scheme-specific assets when one visible mark cannot satisfy both surfaces.
 
+`taproot-site help settings` maps every pulled setting to the app control that
+shows it, says what it does and where it renders, and names the verb that
+writes it (`help appearance` prints the same text beside each writable field,
+and the shipped help is the authority if this table drifts). The ones that are
+easy to confuse:
+
+| App control | Workspace field | Where it renders |
+| --- | --- | --- |
+| Brand & style > Page style > Background image | `lightTheme` / `darkTheme` `pageBackgroundImage` (with `pageBackgroundImageOpacity`) | One layer across the page box behind the content; the opaque header and footer cover it, so it shows behind the main content. |
+| Brand & style > Page canvas > Canvas image | `lightCanvasImageId` / `darkCanvasImageId` in `taproot-styles.json` (with the two `...CanvasImageOpacity` fields) | Only the empty side margins of a page. Not on a standard site today, whose margins are 0 px wide. |
+| Brand & style > Brand > Logo | `lightLogoId` / `darkLogoId` | The header brand, and the footer's brand once the footer is enabled. |
+| Brand & style > Brand > Favicon | `brand.json` `faviconId` | The icon set in every page's head and `/favicon.ico`. |
+
+Both background layers tile at the image's natural pixel size from the top-left;
+neither sets a size, repeat or position.
+
 `taproot-site validate` checks the pulled workspace `taproot-site.json` names,
 with no credential, no network, and no write: every page source (metadata,
 Markdown conversion, media references, content vocabulary, section contexts),
@@ -131,6 +147,15 @@ Warnings never refuse: `linkWarnings` names a link whose address is only
 `http(s)://` plus its own text (`content.link_autolinked`, left by older editor
 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
+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`.
+
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
 the same way: a directory laid out like a
 pulled workspace — `pages/`, `nav.json`, `redirects.json`, and the four
@@ -242,7 +267,7 @@ upward from the current directory through a bounded number of parents.
 Exactly one must be found: none is `config.not_found`, more than one is
 `config.ambiguous`, and `--config <path>` placed before the verb selects one
 explicitly and bypasses discovery. `login`, `logout`, `sites`, `use`,
-`whoami`, and `env` need no configuration and no site.
+`whoami`, `env`, and `changelog` need no configuration and no site.
 
 ```json
 {
@@ -301,11 +326,12 @@ each step names the reference it relies on.
    and favicon; `help fonts` lists the font families, by category, that the
    font fields can name.
 4. **Prepare media locally.** Raster files only (PNG, JPEG, GIF, WebP),
-   relative to the workspace root; make the transparent logo, its `@2x` copy,
-   a dark-scheme logo when needed and a square favicon with your own tools,
-   upload them with `media upload`, then assign `lightLogoId`, `darkLogoId`
-   and `brand.faviconId` from the returned ids. There is no recolor, crop or
-   SVG upload command.
+   relative to the workspace root; make the transparent logo at the highest
+   resolution you have (one file, not a 1x and `@2x` pair: the platform
+   generates the sizes), a dark-scheme logo when needed and a square favicon
+   with your own tools, upload them with `media upload`, then assign
+   `lightLogoId`, `darkLogoId` and `brand.faviconId` from the returned ids. There
+   is no recolor, crop or SVG upload command.
 5. **Validate, preview, then push.** `validate` checks the whole workspace offline;
    `theme push --dry-run` reads the site and lists the JSON paths at which
    each settings file differs from it, and whether the baseline `pull`
@@ -320,10 +346,12 @@ each step names the reference it relies on.
    change set. `pull` reads the four settings documents and the revision
    from one snapshot, and `footer push` advances the recorded revision only
    when its save replaced that same revision.
-6. **Review on staging in both schemes.** `deploy --staging` returns a
-   single-use handoff in `stagingPreview.url`, on a managed Docs site too;
-   open it once and use the site's theme toggle. No page draft is needed;
-   `preview page` renders one draft and is a different tool.
+6. **Review on staging in both schemes.** `staging review` (or
+   `deploy --staging --handoff`) returns a single-use handoff in
+   `stagingPreview.url`, on a managed Docs site too; open it once and use the
+   site's theme toggle. On a Standard site `deploy --staging` first waits until
+   staging serves the new release (see `stagingServed`). No page draft is
+   needed; `preview page` renders one draft and is a different tool.
 7. **Promote only after review.** `deploy --production`.
 
 ## The authoring loop
@@ -362,7 +390,22 @@ its original publication date) and `coverImage`, which the site requires to be a
 image the page itself uses (place it in the body too; `pages.cover_image_unused`). A page's template is fixed when
 it is created: a source for another template is refused with
 `pages.template_immutable`. `taproot-site help page <type>` gives each
-template's fields and one worked example.
+template's fields and one worked example. The structured legal page (a versioned
+privacy policy or terms with an effective date) is created and published in the
+app; the CLI records it as a metadata-only page, and `taproot-site help page
+legal` says what a site-authoring key can and cannot do with one.
+A privacy policy or other legal page that names Taproot should link the first
+mention to <https://www.taproot.io>; `help page free-form` and `help page legal`
+give a sample sentence.
+
+A structured page prints its title as the page's `<h1>`, so its body starts at
+`##`. A free-form page renders no automatic heading, so open its Markdown with
+a `# Page title` line: the first level-1 heading becomes the `<h1>`. A
+`hero-section` with a title, or a leading `image-banner` with overlay text,
+claims the `<h1>` first, so do not also write a `#` line on a page with a
+titled hero. A later `#` heading is rendered as an `<h2>`, never a second
+`<h1>`, and the other headings are renumbered so none skips a level. The
+Markdown subset accepts levels 1 to 4.
 
 A `.pm.json` page's title, path, description and author live in the workspace
 manifest rather than the file. `pages meta set <path> --title <text>
@@ -495,7 +538,10 @@ choose one on the Videos page, where an upload made there gets one automatically
 title and caption there too: the poster, caption and shape are the video's own and show wherever
 it is placed. The command reports its `videoId`, title, caption and file name for a `video`
 component (`help component video`), and
-`pages push` refuses a page that places a video the site does not have. `nav push`, `theme push`, and `footer push` replace the whole
+`pages push` refuses a page that places a video the site does not have. `nav.json` and the footer
+document leave defaults out (no empty `externalUrl` or `children` on a navigation item, no `bold: false`
+on a footer text run); `pull`, `nav push` and `footer push` all write that form and accept either, so a
+pull after a push shows only changes you made. `nav push`, `theme push`, and `footer push` replace the whole
 navigation tree, the complete light/dark theme pair with its appearance
 settings, and the closed footer document. `pull` writes each scheme's
 complete effective theme — the stored theme resolved over the same defaults
@@ -546,14 +592,13 @@ cleaned-up snapshot answers `preview.not_found`.
 It stages; nothing reaches an audience until `deploy --staging` publishes the
 candidate and `deploy --production` promotes that completed staging
 deployment. `status` reports the platform authoring switch, the CLI release,
-deployments, readiness, image processing, and broken references under Content
-permission. `brokenReferences` names affected pages and their missing image IDs
-or internal page paths in the latest editable bodies. It reports `covered: true`,
-`totalPages`, and `pages`; an empty report means no missing targets were found.
-Output is bounded to 50 pages and 50 targets of each kind per page, with explicit
-`pagesTruncated`, `missingImageIdsTruncated`, or `missingPagePathsTruncated` flags.
-A denied, malformed, or failed read fails `status` instead of implying a clean
-site.
+deployments, readiness, image processing, and site health under Content
+permission. `siteHealth` lists the site checks' findings over the latest editable
+body of each page: a rule id, a severity (`error` or `warning`), the page, and
+the value found. It reports `covered: true`, `errors`, `warnings`, `pages`, and
+`findings`; an empty list means no check found anything. Output is bounded to 100
+findings, with an explicit `findingsTruncated` flag. A denied, malformed, or
+failed read fails `status` instead of implying a clean site.
 
 ## Output contract
 
@@ -645,6 +690,24 @@ Other C0/C1 controls, U+2028/U+2029, U+FEFF, and literal `<br>` tags are rejecte
 with the exact fact field path. A label is optional and stays outside the value's link. See
 `taproot-site help page free-form` and `taproot-site help component cta`.
 
+### Staging serves the new release in 0.21.0
+
+A deployment reports `completed` once Taproot has asked Cloudflare to switch the
+host to the new release. The edge then needs up to about two minutes to follow:
+the route propagates, and the Worker keeps it cached for up to a minute more. A
+cache-busting query cannot help, because the release comes from the route and not
+the URL. `deploy --staging` on a Standard site now reads the release staging
+serves before it deploys, and after the deployment completes waits (up to three
+minutes, one read every three seconds) until a different release answers twice in
+a row. The result carries `stagingServed`: `served` with `servedAfterSeconds`,
+`propagating` when staging still showed the previous release at the bound, or
+`unverified` when the change cannot be attributed to this deployment (no readable
+baseline, another deployment under way or just completed, or a request that joined
+one already running; it carries `expectedBy`, or `waitedSeconds` when the last read at the bound
+did not name the previous release), and a managed Docs site always reports `unverified`. The check reads from the machine running the CLI, so a reviewer in another
+region can still see the previous release until the two-minute ceiling. The
+deployment itself is never failed by this wait. The redirect note no longer says there is no propagation delay.
+
 ### Forms by id in 0.20.0
 
 A page stores the form it places by the form's id, so renaming a form never
@@ -738,15 +801,37 @@ targets are refused (`content.link_rel`, `content.link_target`). The editor's
 old default, `noopener noreferrer nofollow`, reads as no choice. See
 `taproot-site help page free-form`.
 
+### What changed between releases
+
+Taproot accepts only the latest CLI, so an upgrade can be forced at any time.
+After one, run `taproot-site changelog --since <the version you upgraded from>`:
+it prints each release's note, the behavior it changed, and the help topics
+(`taproot-site help <topic>`) to read again, newest first, offline and without a
+sign-in. With no `--since` it prints the installed release's entry; `complete:
+false` means `--since` starts before the oldest release the record covers.
+`status` reports the installed release's note in `cliRelease.whatsNew`. An
+outdated-CLI refusal carries `latestVersion` and `changelogCommand` as their own
+fields beside the message, so the command to run after upgrading is in the
+refusal itself. Every release's notes live in one file, `src/changelog.json`,
+and a package test fails when the installed version has no entry there.
+
 ### Staging verification and deployment evidence
 
 `deploy --staging` selects the same changed pages, settings groups and navigation
-as the Deployments page, and returns a single-use staging review handoff in
-`stagingPreview.url` — on a managed Docs site too, where it stages settings
-only: open the URL once, then use the site's theme toggle to review both
-schemes before promoting. When no handoff can be minted, `stagingPreview.reason`
-and `stagingPreview.recovery` say why and what to do next; `staging review`
-mints another on any surface. `status` checks that exact current candidate, so a
+as the Deployments page. It reports no review URL by default, because the URL is
+a live single-use credential and this JSON is often saved to logs:
+`stagingPreview.reason` is `staging.handoff_not_requested` and
+`stagingPreview.recovery` names `taproot-site staging review`. Run that command
+for a single-use review handoff (on a managed Docs site too, where deploy stages
+settings only), or pass `--handoff` to `deploy --staging` to get it in
+`stagingPreview.url` straight away; `--no-handoff` states the default
+explicitly. Open the URL once, then use the site's theme toggle to review both
+schemes before promoting. `staging review --path about` (or
+`deploy --staging --handoff --review-path about`) opens the review on that page
+instead of the home page; a page path as `pull` records it works, with or
+without the leading slash, and a query is allowed. When a requested handoff cannot be minted,
+`stagingPreview.reason` and `stagingPreview.recovery` say why and what to do
+next; `staging review` mints another on any surface. `status` checks that exact current candidate, so a
 completed CLI stage counts as successful until that candidate changes.
 
 A retained failed preview of selected page content refuses deployment as
@@ -770,8 +855,9 @@ Requests have a 90-second deadline with eight concurrent requests; large JSON
 lists have explicit truncation, prioritizing failures. Progress output reports
 each entry. A gate/transport failure never counts as verified.
 
-`stagingPreview.url` is a fresh single-use two-minute handoff minted **after**
-checks. Opening it consumes it and establishes a five-minute staging cookie.
+With `--handoff`, `stagingPreview.url` is a fresh single-use two-minute handoff
+minted **after** checks; without it the check still authenticates with its own
+handoff and reports none. Opening it consumes it and establishes a five-minute staging cookie.
 Minting again replaces the same authority's previous handoff and cookie. Current
 site, host and credential permission are rechecked; key revocation stops access.
 Treat the URL as secret: it is returned only in final JSON, omitted from progress

package/examples/riverbend-wellness/nav.json

@@ -5,22 +5,19 @@
       "id": "a0000000-0000-4000-8000-000000000030",
       "kind": "NAV_ITEM_KIND_PAGE",
       "title": "Home",
-      "resourceId": "a0000000-0000-4000-8000-000000000011",
-      "children": []
+      "resourceId": "a0000000-0000-4000-8000-000000000011"
     },
     {
       "id": "a0000000-0000-4000-8000-000000000031",
       "kind": "NAV_ITEM_KIND_PAGE",
       "title": "Visit",
-      "resourceId": "a0000000-0000-4000-8000-000000000013",
-      "children": []
+      "resourceId": "a0000000-0000-4000-8000-000000000013"
     },
     {
       "id": "a0000000-0000-4000-8000-000000000032",
       "kind": "NAV_ITEM_KIND_EXTERNAL_URL",
       "title": "Book a class",
-      "externalUrl": "https://schedule.example.test/riverbend",
-      "children": []
+      "externalUrl": "https://schedule.example.test/riverbend"
     }
   ]
 }

package/examples/riverbend-wellness/pages/visit.md

@@ -5,7 +5,7 @@ description: An example second page for the offline authoring fixture.
 ---
 
 :::section {"contentPadding":"standard","surface":"none"}
-## Visit the studio
+# Visit the studio
 
 Riverbend Wellness is a fictional studio in the fictional town of Elm Harbor.
 Nothing on this page describes a real place, and no address, telephone number,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.20.0",
+  "version": "0.21.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",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "6.2.0",
+    "@taprootio/espalier": "6.3.0",
     "mediabunny": "1.61.1"
   },
   "scripts": {

package/src/api.js

@@ -3,6 +3,7 @@ import {
   BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CANONICAL_TIMESTAMP,
   CAPABILITY_REFUSAL_FIELD,
+  changelogCommandSince,
   CLI_UPGRADE_COMMAND,
   CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
@@ -398,6 +399,7 @@ export function announceRefusal(error, onProgress, action = "request") {
         + "and no retry of this version can succeed.",
     );
     onProgress(`  Upgrade with: ${CLI_UPGRADE_COMMAND}`);
+    onProgress(`  Then see what changed: ${changelogCommandSince(CLI_VERSION)}`);
     // The server names both versions and says when waiting is the right move
     // (a deploy that landed ahead of its npm publish). Surface it verbatim
     // rather than restating a policy this side does not own; the bounded
@@ -1123,39 +1125,51 @@ export async function listSiteImages(client, siteId, requestOptions = {}, { imag
   return { images, summary, truncated: true };
 }
 
-/** Broken targets in the latest editable page bodies, authorized by Content. */
-export async function getSiteBrokenReferences(client, siteId) {
-  const code = "api.broken_references_contract";
-  const response = requireObject(
-    await client.request(sitePath(siteId, "broken-references")),
-    code,
-    "broken-reference report",
-  );
-  // Proto3 omits empty repeated fields. A present non-array is a bad report,
-  // not evidence that the site has no broken links.
-  const repeated = (value, field) => {
-    if (value === undefined) return [];
-    if (!Array.isArray(value)) {
+/** The site checks' findings over the latest editable page bodies, authorized by Content. */
+export async function getSiteHealth(client, siteId) {
+  const code = "api.site_health_contract";
+  const response = requireObject(await client.request(sitePath(siteId, "health")), code, "site-health report");
+  // Proto3 omits empty repeated fields and zero counts. A present non-array is a
+  // bad report, not evidence that the site is healthy.
+  if (response.findings !== undefined && !Array.isArray(response.findings)) {
+    throw new SiteAuthoringError(code, "Taproot returned an invalid findings list.", { field: "findings" });
+  }
+  const count = (value, field) => {
+    if (value === undefined) return 0;
+    if (!Number.isSafeInteger(value) || value < 0) {
       throw new SiteAuthoringError(code, `Taproot returned an invalid ${field}.`, { field });
     }
     return value;
   };
-  return repeated(response.pages, "pages").map((entry) => {
-    const page = requireObject(entry, code, "broken-reference page");
-    const missingPagePaths = repeated(page.missingPagePaths, "missingPagePaths");
-    if (missingPagePaths.some((path) => typeof path !== "string")) {
-      throw new SiteAuthoringError(code, "Taproot returned an invalid missing page path.", {
-        field: "missingPagePaths",
-      });
+  const severities = {
+    SITE_FINDING_SEVERITY_ERROR: "error",
+    SITE_FINDING_SEVERITY_WARNING: "warning",
+  };
+  const findings = (response.findings ?? []).map((entry) => {
+    const finding = requireObject(entry, code, "finding");
+    const severity = severities[finding.severity];
+    if (typeof finding.ruleId !== "string" || severity === undefined) {
+      throw new SiteAuthoringError(code, "Taproot returned a finding with no rule or severity.", { field: "findings" });
     }
     return {
-      pageId: requireCanonicalUuid(page.pageId, code, "pageId"),
-      pageTitle: text(page.pageTitle),
-      missingImageIds: repeated(page.missingImageIds, "missingImageIds")
-        .map((id) => requireCanonicalUuid(id, code, "missingImageIds")),
-      missingPagePaths,
+      ruleId: finding.ruleId,
+      severity,
+      ...(finding.pageId === undefined || finding.pageId === "" ? {} : {
+        pageId: requireCanonicalUuid(finding.pageId, code, "pageId"),
+        pageTitle: text(finding.pageTitle),
+        pagePath: text(finding.pagePath),
+      }),
+      subject: text(finding.subject),
+      detail: text(finding.detail),
     };
   });
+  return {
+    findings,
+    errorCount: count(response.errorCount, "errorCount"),
+    warningCount: count(response.warningCount, "warningCount"),
+    pageCount: count(response.pageCount, "pageCount"),
+    truncated: response.truncated === true,
+  };
 }
 
 /** Use the same changed release set the Deployments page selects. */
@@ -1311,13 +1325,82 @@ export async function getStagingPreviewStatus(client, siteId) {
   return { ready: true, stagingUrl: `https://${url.hostname}/` };
 }
 
-/** Mint a site-bound handoff; its URL is emitted only in final operational JSON. */
-export async function mintStagingPreviewHandoff(client, siteId, { now = Date.now } = {}) {
+// The server accepts 2048, but the edge appends a check parameter before its own 2048 test.
+const STAGING_RETURN_PATH_MAXIMUM = 2_000;
+const STAGING_HANDOFF_PARAMETER = "__taproot_preview_handoff";
+// Transport-owned query keys the server refuses in a return path (StagingPreviewProtocol).
+const STAGING_RESERVED_QUERY_KEYS = new Set([
+  STAGING_HANDOFF_PARAMETER,
+  "__taproot_preview_check",
+  "__taproot_preview_denied",
+]);
+
+/**
+ * A page path for `staging review --path`, as the same-origin return path the
+ * server accepts (TR01230). `about`, `/about` and `posts/one?draft=true` all
+ * work; the rules mirror `StagingPreviewProtocol.TryValidateReturnPath`, so a
+ * path the server would refuse is refused here before any request.
+ */
+export function normalizeStagingReviewPath(value) {
+  const invalid = (reason) =>
+    new SiteAuthoringError(
+      "staging.review_path_invalid",
+      `A review path must be a page path on this site, such as 'about' or '/posts/one'; ${reason}.`,
+      { field: "reviewPath", exitCode: 2 },
+    );
+  if (typeof value !== "string" || value.length === 0) throw invalid("it is empty");
+  // URL parsing drops edge whitespace, so the server's URL would no longer match the path asked for.
+  if (value !== value.trim()) throw invalid("it must not start or end with whitespace");
+  const path = value.startsWith("/") ? value : `/${value}`;
+  if (path.length > STAGING_RETURN_PATH_MAXIMUM) throw invalid("it is too long");
+  // Checked before URL parsing, which would throw on some of these (such as '/\\') instead of naming the problem.
+  if (path.includes("#") || path.includes("\\") || /[\u0000-\u001f\u007f-\u009f]/u.test(path)) {
+    throw invalid("it must not contain a fragment, a backslash or control characters");
+  }
+  if (path.startsWith("//")) throw invalid("it must not start with two slashes");
+  const queryStart = path.indexOf("?");
+  if (queryStart >= 0) {
+    for (const pair of path.slice(queryStart + 1).split("&")) {
+      const separator = pair.indexOf("=");
+      const rawName = separator < 0 ? pair : pair.slice(0, separator);
+      let name = rawName;
+      try {
+        name = decodeURIComponent(rawName.replaceAll("+", " "));
+      } catch {
+        // A malformed escape cannot spell a reserved key once decoded; compare the raw text.
+      }
+      if (STAGING_RESERVED_QUERY_KEYS.has(name.toLowerCase())) throw invalid("it names a reserved preview parameter");
+    }
+  }
+  let resolved;
+  try {
+    resolved = new URL(path, "https://staging.invalid");
+  } catch {
+    throw invalid("it is not a valid path");
+  }
+  // Dot segments can resolve to '//x'; the edge refuses that after spending the single-use handoff.
+  if (resolved.pathname.startsWith("//")) {
+    throw invalid("it must not resolve to a path starting with two slashes");
+  }
+  // The edge re-encodes the path and query and adds its own check parameter before its length test.
+  resolved.searchParams.set("__taproot_preview_check", "1");
+  if (resolved.pathname.length + resolved.search.length > 2_048) throw invalid("it is too long once encoded");
+  return path;
+}
+
+/**
+ * Mint a site-bound handoff; its URL is emitted only in final operational JSON.
+ * `returnPath` is the page the browser lands on after the handoff is consumed;
+ * `deadline` lets a bounded wait (the served-release poller) cap the mint too.
+ */
+export async function mintStagingPreviewHandoff(client, siteId, { now = Date.now, returnPath = "/", deadline } = {}) {
   const code = "api.staging_handoff_contract";
   const result = requireObject(
     await client.request(sitePath(siteId, "staging-preview:mint-handoff"), {
       method: "POST",
-      body: { siteId },
+      body: { siteId, ...(returnPath === "/" ? {} : { returnPath }) },
+      // A poller's budget reaches the mint, so a slow API cannot stretch a bounded wait.
+      ...(deadline === undefined ? {} : { deadline, now }),
     }),
     code,
     "staging handoff",
@@ -1332,12 +1415,16 @@ export async function mintStagingPreviewHandoff(client, siteId, { now = Date.now
   }
   const expires = requireCanonicalTimestamp(result.handoffExpiresAt, code, "handoffExpiresAt");
   const current = now();
+  // The URL is the requested path plus the handoff token as the last query parameter.
+  const expectedUrl = new URL(returnPath, "https://staging.invalid");
+  const expectedQuery = expectedUrl.search.replace(/^\?/u, "").replace(/&$/u, "");
+  const tokenQuery = new RegExp(`^\\?(?:(.*)&)?${STAGING_HANDOFF_PARAMETER}=([A-Za-z0-9_-]{43})$`, "u")
+    .exec(url.search);
   if (
     result.siteId !== siteId || origin.protocol !== "https:" || !CANONICAL_HOST.test(origin.hostname)
     || origin.port || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash
-    || url.origin !== origin.origin || url.username || url.password || url.pathname !== "/" || url.hash
-    || [...url.searchParams].length !== 1
-    || !/^[A-Za-z0-9_-]{43}$/u.test(url.searchParams.get("__taproot_preview_handoff") ?? "")
+    || url.origin !== origin.origin || url.username || url.password || url.pathname !== expectedUrl.pathname
+    || url.hash || tokenQuery === null || (tokenQuery[1] ?? "") !== expectedQuery
     || expires.milliseconds <= current - AUTHORING_PREVIEW_CLOCK_SKEW_MILLISECONDS
     || expires.milliseconds > current + AUTHORING_PREVIEW_HANDOFF_LIFETIME_MILLISECONDS
         + AUTHORING_PREVIEW_CLOCK_SKEW_MILLISECONDS

package/src/changelog.js

@@ -0,0 +1,48 @@
+import changelogRecord from "./changelog.json" with { type: "json" };
+import { compareCliVersions, parseCliVersion } from "./cli-release.js";
+import { CLI_VERSION } from "./constants.js";
+
+/**
+ * What changed in each release (TR01225), from the one record the package ships.
+ *
+ * `changelog.json` is the only place a release note is written: the `changelog`
+ * command and `status` both read it here, so neither carries prose of its own.
+ * The outdated-CLI refusal comes from a CLI that predates the release it
+ * refuses for, so it can only name the command to run after upgrading. An entry is `{ version, date?, note, behavior,
+ * help }`: `note` is the one-sentence summary, `behavior` the changes a script or
+ * agent can observe, and `help` the reference topics (`help <topic>`) whose text
+ * changed. The newest entry comes first. The version being prepared is
+ * "unreleased" until the release is stamped.
+ */
+
+export const UNRELEASED = "unreleased";
+
+export const CHANGELOG = Object.freeze(changelogRecord.entries.map((entry) => Object.freeze(entry)));
+
+/** The entry for one released version, or undefined. */
+export function changelogEntryFor(version) {
+  return CHANGELOG.find((entry) => entry.version === version);
+}
+
+/**
+ * The released entries newer than `since` and no newer than `through`, newest
+ * first. The unreleased entry is never part of an installed release.
+ */
+export function changelogEntriesSince(since, through = CLI_VERSION) {
+  return CHANGELOG.filter((entry) => {
+    if (entry.version === UNRELEASED || parseCliVersion(entry.version) === undefined) return false;
+    return compareCliVersions(entry.version, since) > 0 && compareCliVersions(entry.version, through) <= 0;
+  });
+}
+
+/** The oldest released version the record covers, so a caller can say when a range starts before it. */
+export function earliestRecordedVersion() {
+  const released = CHANGELOG.filter((entry) => parseCliVersion(entry.version) !== undefined);
+  return released.length === 0 ? undefined : released[released.length - 1].version;
+}
+
+/** The short note `status` shows for the installed version, or undefined when none is recorded. */
+export function installedWhatsNew(version = CLI_VERSION) {
+  const entry = changelogEntryFor(version);
+  return entry === undefined ? undefined : { version: entry.version, note: entry.note, help: [...entry.help] };
+}

package/src/changelog.json

@@ -0,0 +1,71 @@
+{
+  "entries": [
+    {
+      "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.",
+      "behavior": [
+        "deploy --staging and redirects check no longer report a live single-use review URL: stagingPreview.url is empty and stagingPreview.reason is staging.handoff_not_requested. Pass --handoff for a fresh URL in the result, or run staging review. --no-handoff states the default.",
+        "staging review takes --path <page> to open the review on that page instead of the home page; deploy --staging --handoff and redirects check --handoff take --review-path <page>. The path is checked offline (staging.review_path_invalid).",
+        "pull and nav push write nav.json without default-only fields (no empty externalUrl, resourceId or children), and nav push rewrites nav.json from the saved tree after a successful save; either form is accepted.",
+        "Footer text runs omit bold, italic and underline when they are false, in pull and footer push; either form is accepted.",
+        "New command: changelog [--since <version>] prints these notes offline, and status reports the installed version's note. The cli_outdated refusal now carries latestVersion and the changelog command to run after upgrading.",
+        "deploy --staging on a Standard site waits, bounded at 180 seconds, until staging serves the new release before it finishes, and reports stagingServed as served, propagating or unverified; the result never fails on the wait. Propagation can take up to about 120 seconds after the deployment completes.",
+        "validate runs the shared site check rules it can run offline and reports findings (ruleId, severity, pageId, subject) and siteChecks (ranOffline, checkedBySite, checkedAtDeploy); redirect refusals keep their codes and carry the rule id. status reads the site health summary; the broken-references report is gone, so an older CLI needs this upgrade.",
+        "Published forms mark required fields with an asterisk and a legend; help forms describes the mark.",
+        "Help corrections: a free-form page renders no automatic heading and its first level-1 heading is the h1; help pages lists the read-only legal page type and help page legal describes it; the new help settings topic maps every pulled setting to the app control that writes it and says where it renders; logo.png and logo@2x.png are not paired, so assign the highest-resolution file.",
+        "Espalier 6.3.0: a field fills one layer above the surface that contains it; the default site theme was rebuilt for it."
+      ],
+      "help": [
+        "walkthrough",
+        "nav",
+        "redirects",
+        "preview",
+        "forms",
+        "pages",
+        "page",
+        "settings",
+        "appearance",
+        "theme",
+        "media",
+        "delivery"
+      ]
+    },
+    {
+      "version": "0.20.0",
+      "note": "Pages place a form by its id, so renaming a form never breaks a page; form names are unique on a site.",
+      "behavior": [
+        "pages push turns a component:form formKey into the form's id, and refuses a key the site does not have (pages.form_unknown) or has archived (pages.form_archived) before writing anything; plan reports the same. pages pull writes the key back, and keeps an id the site no longer has.",
+        "forms validate and forms push refuse two forms with the same name, ignoring case (forms.name_duplicate, forms.name_taken).",
+        "The first pages pull after the server release can report pages.pull_conflict for a Markdown page that places a form, though its content is the same; run pages push for that page, or delete the file and pull again."
+      ],
+      "help": [
+        "forms",
+        "component"
+      ]
+    },
+    {
+      "version": "0.19.0",
+      "note": "Forms can email the site owner an hourly count of new submissions, and a newsletter sink needs a consent checkbox.",
+      "behavior": [
+        "A form file takes an optional top-level notify_owner boolean. New forms default to false, omitting it on an existing form keeps the site's choice, and it takes effect without a new version or publishing.",
+        "A newsletter sink requires a required email contact field and at least one consent checkbox, and every consent checkbox must be checked.",
+        "forms.concurrent_modification is also raised when the site's operational settings moved since the last read."
+      ],
+      "help": [
+        "forms"
+      ]
+    },
+    {
+      "version": "0.18.0",
+      "note": "Place categories can be set per site, and deploy shows the pages it will generate before it sends anything.",
+      "behavior": [
+        "New commands: places category list, places category set <placeId> <category> and places category clear <placeId> change the category this site files a place review under.",
+        "deploy --staging plans the candidate first and reports the pages it will generate and the allowance left (readiness.pageEstimate); a candidate that does not fit stops with deploy.page_allowance_exceeded before anything is sent.",
+        "A deploy refused for the pages-generated allowance or the bandwidth pause reports plan_limit with the time it can lift."
+      ],
+      "help": [
+        "page"
+      ]
+    }
+  ]
+}

package/src/cli-release.js

@@ -1,4 +1,5 @@
 import {
+  changelogCommandSince,
   CLI_UPGRADE_COMMAND,
   CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
@@ -131,6 +132,11 @@ export function isBehindLatest(latestVersion, currentVersion = CLI_VERSION) {
  * `api.request_rejected`.
  */
 class CliOutdatedError extends SiteAuthoringError {
+  constructor(code, message, options, latestVersion) {
+    super(code, message, options);
+    this.latestVersion = latestVersion;
+  }
+
   refusalKind() {
     return REFUSAL_CLI_OUTDATED;
   }
@@ -146,7 +152,9 @@ export function cliOutdatedError(latestVersion) {
     `This CLI is version ${CLI_VERSION}, and the last Taproot sign-in exchange reported ${latestVersion} as the `
       + "latest published release. Taproot accepts only the latest, so every online verb is refused until this "
       + `package is upgraded. Upgrade with: ${CLI_UPGRADE_COMMAND}. If ${latestVersion} was published in the last `
-      + "few minutes, npm may not serve it yet — wait a moment and retry the upgrade.",
+      + "few minutes, npm may not serve it yet — wait a moment and retry the upgrade. Once upgraded, run "
+      + `'${changelogCommandSince(CLI_VERSION)}' to see what changed.`,
     { field: CLI_UPGRADE_REFUSAL_FIELD },
+    latestVersion,
   );
 }