@taprootio/site-authoring 0.22.4 → 0.23.1

package/README.md

@@ -342,6 +342,11 @@ each step names the reference it relies on.
    `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 resolve` prints, also offline, the colors Espalier compiles from the
+   theme for each scheme and context with the contrast of every ink-on-surface
+   pair and a flag for each one under WCAG AA (add `--json` for the stable
+   result, `--scheme` and `--context` to narrow it, `--site` for the site's
+   stored theme);
    `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`
    recorded is still current; `theme push` saves both themes, the appearance
@@ -358,7 +363,9 @@ each step names the reference it relies on.
 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
+   site's theme toggle; the review session lasts five minutes (see
+   [How long a staging review lasts](#staging-verification-and-deployment-evidence)).
+   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`.
@@ -512,6 +519,26 @@ closed with `pages.push_conflict` when a page's stored-state revision has
 moved since this workspace last reconciled with it, naming both revisions;
 `pull` first, or push after a refused pull has shown you the site's version.
 
+`pages delete <page-path> [--dry-run]` deletes one tracked page and removes its
+source file and manifest entry, so the next
+`pull` or whole-workspace push does not bring it back. It runs the same
+revision fence as `pages push` first (`pages.push_conflict`, nothing deleted),
+and refuses a page that navigation, the footer or a form's after-submit page
+still uses (`pages.delete_referenced`, naming each use): remove those first,
+then delete. A redirect that lands on the page is listed in `redirectsToPage`
+and does not stop the delete; links from other pages are checked afterwards by
+`validate` (`link.page_missing`). A page the live site serves is not taken off
+it by the delete: the site stages the removal (`effect: removalStaged`) and the
+page stays live until a deployment promotes it, so run `deploy --staging`,
+review the staging site, then `deploy`. A page never published is removed
+outright. The home page, 404, generated, legal and integration-managed pages
+are refused. `--dry-run` runs every check and sends nothing. A page the site
+already deleted or staged for removal (an interrupted run) is only cleaned from
+the workspace and reports `effect: alreadyDeleted` or `alreadyRemovalStaged`.
+`effect` is the answer: `deleted` is true only when the page is gone from the site
+now, so a staged removal reports `deleted: false` and `removalStaged: true`. A
+staged removal can be undone only in the app, with Keep page on the Pages list.
+
 `places search <name and city>` asks Google Places for the place a review
 names and reports predictions with a session token; `places select
 <googlePlaceId> <sessionToken>` records the match as a Taproot place and
@@ -524,7 +551,9 @@ they reference and the images the settings name, the footer and the pages it
 links, the theme, navigation — and orders what is left
 to send: media upload, pages push, footer push (theme push refuses unsaved
 footer content), theme push, nav push, each marked ready, blocked, or nothing
-to do. It writes nothing and reports a `planHash`. `apply --plan <planHash>`
+to do. Navigation is also checked against the revision `pull` recorded: a tree that moved is a blocked
+step (`nav.concurrent_modification`), and an unchanged tree under a stale revision is listed ready with
+`settlesLostPush` so `apply` settles a push whose answer was lost. It writes nothing and reports a `planHash`. `apply --plan <planHash>`
 plans again, refuses with `apply.plan_stale` if the workspace or the site
 moved, and otherwise runs the steps through the ordinary push verbs. While
 they run, a workspace file read differently from the plan (or not read by it)
@@ -550,7 +579,10 @@ component (`help component video`), and
 `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
+pull after a push shows only changes you made. `nav push` is fenced by the navigation revision `pull` recorded
+(`navigation.revision` in the manifest): a tree edited in the app since is refused with `nav.concurrent_modification`
+and nothing is written, and a manifest without a revision is refused with `nav.pull_required`; keep a copy of
+`nav.json`, run `pull`, re-apply the edits and push again. `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
@@ -873,9 +905,26 @@ 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
 and `GITHUB_OUTPUT`. The same Actions exclusion applies to `preview page` URLs.
 
+**How long a staging review lasts.** The handoff works once and expires two
+minutes after it is minted. Opening it starts a five-minute review session in
+that browser, and the session never renews. When it ends, the staging site
+redirects to the Taproot sign-in. A reviewer whose Taproot account can preview
+the site signs in and is sent straight back to the page with a fresh session; a
+reviewer without one needs a fresh link from `taproot-site staging review`,
+because a link minted with a key has no Taproot session behind it. Minting another handoff with the same
+key for the same site, which `staging review`, `deploy --staging` (on a Standard
+site, or with `--handoff`), `redirects check` and `delivery check --staging` do,
+ends the earlier link and any session opened from it. That browser then shows "Staging preview
+unavailable" rather than the sign-in redirect, so mint the link last, just
+before the reviewer opens it. The staging site does not show a separate "link expired"
+page for a missing cookie: the staging host cannot tell an expired link from a first visit, or see
+whether the visitor is signed in to Taproot, and the sign-in redirect is what
+renews a signed-in owner's review.
+
 Deployment results carry `phaseTimings`. New deployments retain up to 32 durable
 server-observed phase transitions, including repeated phases on retry. Durations
 are calculated only between recorded transitions. `truncated` marks missing

package/package.json

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

package/src/api.js

@@ -10,6 +10,7 @@ import {
   EXTERNAL_WRITES_SETTING_KEY,
   EXTERNAL_WRITES_SETTING_LOCATION,
   GRPC_NOT_FOUND,
+  HEX_DIGEST,
   HTTP_NOT_FOUND,
   LIMITS,
   REFUSAL_CAPABILITY_MISSING,
@@ -509,6 +510,11 @@ export async function withRefusalGuidance(onProgress, action, work) {
   }
 }
 
+/** A page the author no longer has: deleted, or deleted and waiting for a deployment to take it off the live site. */
+export function isGonePage(summary) {
+  return summary.status === PAGE_STATUS_DELETED || summary.removalStaged === true;
+}
+
 export function normalizePageSummary(value) {
   const summary = requireObject(value, "api.page_contract", "page summary");
   return {
@@ -521,7 +527,11 @@ export function normalizePageSummary(value) {
     templateType: typeof summary.templateType === "string" ? summary.templateType : "TEMPLATE_TYPE_UNKNOWN",
     status: enumValue(summary.status, PAGE_STATUSES, PAGE_STATUS_UNKNOWN, "api.page_status", "page status"),
     hasDraft: summary.hasDraft === true,
+    // The first publication, which outlives the status: a published page being edited reports a draft status.
+    datePublished: typeof summary.datePublished === "string" ? summary.datePublished : "",
     isGenerated: summary.isGenerated === true,
+    // A published page whose deletion waits for a deployment: it is still live, and the author has deleted it.
+    removalStaged: summary.removalStaged === true,
     // Absent against a Taproot that predates the revision contract, and absent
     // on the listings that never resolve stored body state. Both mean the same
     // thing to a caller — "this read cannot say what version you are looking
@@ -579,6 +589,15 @@ export async function createPage(client, body) {
   return normalizePageSummary(await client.request("v1/pages", { method: "POST", body }));
 }
 
+/**
+ * Deletes one page. A page the live site does not serve is removed at once (a path it published stays reserved);
+ * one it serves is staged for removal and stays live until a deployment takes it off (TR01278). The answer says
+ * which: `removalStaged`.
+ */
+export async function deletePage(client, pageId) {
+  return normalizePageSummary(await client.request(`v1/pages/${encodeURIComponent(pageId)}`, { method: "DELETE" }));
+}
+
 export async function updatePage(client, pageId, body) {
   return normalizePageSummary(
     await client.request(`v1/pages/${encodeURIComponent(pageId)}`, { method: "PATCH", body }),
@@ -664,21 +683,29 @@ export async function publishDrafts(client, pageIds) {
  */
 export async function getNavigation(client, siteId) {
   const search = query([["environment", SITE_ENVIRONMENT_DRAFT]]);
-  const response = requireObject(
-    await client.request(sitePath(siteId, `navigation${search}`)),
-    "api.navigation_contract",
-    "site navigation",
-  );
-  return Array.isArray(response.navItems) ? response.navItems : [];
+  return requireNavigation(await client.request(sitePath(siteId, `navigation${search}`)));
 }
 
-export async function saveNavigation(client, siteId, navItems) {
-  const response = requireObject(
-    await client.request(sitePath(siteId, "navigation"), { method: "PUT", body: { siteId, navItems } }),
-    "api.navigation_contract",
-    "site navigation",
+/**
+ * Replaces the draft tree. `expectedRevision` is the revision the tree was read
+ * at; the site refuses the write rather than erasing an item added since.
+ */
+export async function saveNavigation(client, siteId, navItems, expectedRevision) {
+  return requireNavigation(
+    await client.request(sitePath(siteId, "navigation"), {
+      method: "PUT",
+      body: { siteId, navItems, expectedRevision },
+    }),
   );
-  return Array.isArray(response.navItems) ? response.navItems : [];
+}
+
+/** A navigation answer: the tree and the revision a later save must present. */
+function requireNavigation(value) {
+  const response = requireObject(value, "api.navigation_contract", "site navigation");
+  return {
+    navItems: Array.isArray(response.navItems) ? response.navItems : [],
+    revision: typeof response.revision === "string" ? response.revision : "",
+  };
 }
 
 /**
@@ -815,7 +842,7 @@ export async function saveSiteFooterSettings(client, siteId, footerSettings, exp
  * is a containment check on a server string that reaches the manifest, not a
  * claim about how the value is computed.
  */
-export const PRESENTATION_REVISION = /^[0-9a-f]{64}$/u;
+export const PRESENTATION_REVISION = HEX_DIGEST;
 
 /**
  * Reads the site's draft presentation — the four theme-gated settings groups

package/src/changelog.json

@@ -1,5 +1,34 @@
 {
   "entries": [
+    {
+      "version": "0.23.1",
+      "note": "Image uploads support Taproot’s single-use upload gateway and send an operation key with each upload request.",
+      "behavior": [
+        "media upload sends an operation key when requesting an image upload. It accepts a single-use gateway capability only for the configured Taproot API origin and image-upload path, and never automatically retries that capability after a transport failure or retryable response. Direct signed object-store uploads retain their existing retry behavior."
+      ],
+      "help": []
+    },
+    {
+      "version": "0.23.0",
+      "note": "theme resolve prints the colors Espalier compiles from the theme, per scheme and context, with their contrast ratios, offline; the help and the staging review result say how long a review lasts and what ends it; pages delete with a dry run; nav push fenced by a navigation revision.",
+      "behavior": [
+        "New verb: taproot-site theme resolve [--scheme light|dark] [--context <name>] [--site] [--json]. It reads the pulled settings/taproot-styles.json with no credential and no network (--site reads the site's stored theme instead and needs a sign-in), compiles it through Espalier's own pipeline, and prints for the root page and every context in each scheme every semantic color as oklch and hex, whether it is compiled from the roles or pinned (origin compiled, pinned or inherited_pin), and the WCAG contrast of every ink-on-surface pair Espalier defines beside the APCA Lc and its target.",
+        "A pair under WCAG AA (4.5:1 text, 3:1 large text and UI) is listed in flags with the stable code theme.contrast_text_below_aa and the theme field to edit; flags never refuse, so the exit code is 0. An invalid or incomplete theme is refused with the code theme push and validate use (theme.settings_missing lists every absent path). Without --json the output is a table; with it, the stable result (schemes[].surfaces[].tokens and pairs, contrast, flags). A result too large for the output bound names what it left out in omittedSurfaces (items, count, truncated); --scheme and --context fetch it.",
+        "The help reference version is 41.",
+        "staging review, deploy and the delivery, preview, redirects and walkthrough help now state that a review handoff works once and expires after two minutes, that opening it starts a five-minute review session that never renews, that the staging site then redirects to the Taproot sign-in (a reviewer without a Taproot account that can preview the site needs a fresh link), and that minting another handoff with the same key (staging review, deploy --staging, redirects check, delivery check --staging) ends the earlier link and any session opened from it. The same text is in stagingPreview.review for staging review and for deploy --staging --handoff on a managed Docs site. No command or refusal changed.",
+        "Correction to 0.22.4: analyticsConsentPrompt is read-only in the CLI. A pull records it in the publishing preferences, but no push verb writes it (theme push writes only the appearance scalars, both themes and the footer colours); switch it on or off in the app under Settings, then deploy. help settings has said so since 0.22.4.",
+        "pages delete <path> [--dry-run] deletes one tracked page and removes its source and manifest entry, so a test page no longer needs the app. It runs the same revision fence as pages push first (pages.push_conflict, nothing deleted), refuses a page navigation, the footer or a form's after-submit page still uses (pages.delete_referenced, naming each use), reports redirects that land on the page in redirectsToPage, and stages the removal of a page the live site serves (effect removalStaged): the page stays live until a deployment promotes the removal, so deploy --staging then deploy finish the job, and pull, push, plan and approve treat it as deleted. The home page, 404, generated, legal and integration-managed pages are refused. A page the site already deleted or staged for removal is only cleaned from the workspace (effect alreadyDeleted or alreadyRemovalStaged).",
+        "pull records the navigation revision beside the tree (navigation.revision in the manifest and in pull's result), and nav push presents it. A tree edited in the app since the pull is refused with nav.concurrent_modification and nothing is written; keep a copy of nav.json, run pull, re-apply the edits and push again. A manifest with no navigation revision (a workspace pulled by an earlier release) is refused with nav.pull_required: run pull once. A successful push records the revision it saved, so the next push is fenced against it, and a push whose answer was lost after it committed is settled by running it again (navigation.alreadyApplied, nothing sent). The result no longer carries lastWriteWins; navigation.revision is the saved revision."
+      ],
+      "help": [
+        "theme",
+        "walkthrough",
+        "delivery",
+        "preview",
+        "redirects",
+        "nav"
+      ]
+    },
     {
       "version": "0.22.4",
       "note": "The publishing preferences gain analyticsConsentPrompt, the switch that asks readers before the visit cookie is set.",

package/src/cli.js

@@ -15,6 +15,7 @@ import {
   PLAN_HASH,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
   RESULT_SCHEMA_VERSION,
+  STAGING_REVIEW_SESSION_NOTE,
   SURFACE_DOCS_PRESENTATION,
   SURFACE_STANDARD,
   VERB_APPLY,
@@ -35,6 +36,7 @@ import {
   VERB_LOGOUT,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
+  VERB_PAGES_DELETE,
   VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
   VERB_PLACES_CATEGORY_CLEAR,
@@ -52,6 +54,7 @@ import {
   VERB_SITES,
   VERB_STATUS,
   VERB_THEME_PUSH,
+  VERB_THEME_RESOLVE,
   VERB_USE,
   VERB_VALIDATE,
   VERB_WHOAMI,
@@ -85,6 +88,8 @@ import {
 } from "./reference-help.js";
 import { FONT_CATEGORIES, getFontCatalogReference } from "./font-catalog.js";
 import { assertCliCurrent } from "./session.js";
+import { formatThemeResolve } from "./theme-resolve.js";
+import { MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS } from "./theme-validation.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
 
 /**
@@ -97,7 +102,13 @@ import { VERB_HANDLERS } from "./verbs/index.js";
  * are outdated. `--help` and `--version` are outside it for the same reason:
  * they are how someone finds out what they have.
  */
-const VERSION_GATED_OFFLINE_VERBS = Object.freeze([VERB_HELP, VERB_VALIDATE, VERB_FORMS_VALIDATE, VERB_WHOAMI]);
+const VERSION_GATED_OFFLINE_VERBS = Object.freeze([
+  VERB_HELP,
+  VERB_VALIDATE,
+  VERB_FORMS_VALIDATE,
+  VERB_THEME_RESOLVE,
+  VERB_WHOAMI,
+]);
 
 // One entry per verb, in help order. `tokens` is the exact leading positional
 // sequence; matching prefers the longest sequence, so a two-token family can
@@ -296,6 +307,32 @@ const VERBS = Object.freeze([
       + "A description longer than 160 characters is warned about (search results cut it off) and one longer than "
       + "1000 is refused. Nothing is sent: run 'pages push', then 'approve'.",
   },
+  {
+    name: VERB_PAGES_DELETE,
+    surface: SURFACE_STANDARD,
+    // Deleting is Content; the navigation read that checks for a dangling item is Design.
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
+    tokens: ["pages", "delete"],
+    dryRun: true,
+    positionals: "deletePagePath",
+    summary: "Delete one page (a live page is staged for removal until you deploy), and remove its source from the workspace.",
+    note: "Names one page this workspace tracks by its path and deletes it from the site, "
+      + "then removes its source file and manifest entry so the next pull or push does not bring it back. "
+      + "A draft or staged page that was never published is removed outright and its path is free again. A page "
+      + "the live site serves is not taken off it by the delete: the site stages the removal (effect "
+      + "removalStaged) and the page stays live until a deployment promotes it, so run 'deploy --staging', "
+      + "review the staging site, then 'deploy'. A deployment is also how a staging candidate that held a page "
+      + "is refreshed. A staged removal can be undone only in the app, with Keep page on the Pages list. The same fence as 'pages push' runs first: a page changed on "
+      + "the site since this workspace last reconciled with it is refused with pages.push_conflict and nothing is "
+      + "deleted; run 'pull' and decide again. A page that navigation, the footer or a form's after-submit page "
+      + "still uses is refused with pages.delete_referenced, naming each use; remove those first. A redirect that "
+      + "lands on the path is reported in redirectsToPage and does not stop the delete. Links from other pages "
+      + "are not checked here: run 'validate' afterwards (link.page_missing). The home page, 404, generated pages, "
+      + "legal documents and integration-managed pages are refused. --dry-run runs every check and reports what "
+      + "would be deleted, or staged for removal, without sending anything. A page the site has already deleted "
+      + "or staged for removal (an interrupted run) is only cleaned from the workspace and reports effect "
+      + "alreadyDeleted or alreadyRemovalStaged.",
+  },
   {
     name: VERB_AUTHORS_LIST,
     surface: SURFACE_STANDARD,
@@ -430,7 +467,7 @@ const VERBS = Object.freeze([
     summary: "Check the whole workspace against the live site and order what is left to send. Writes nothing.",
     note: "Runs every check the pushes run — each page against the site's pages, revisions, videos and forms; media that "
       + "pages reference and media upload has not sent; the theme, appearance and footer colors against the site's "
-      + "presentation revision; the footer against its draft; navigation against the live page list — and lists "
+      + "presentation revision; the footer against its draft; navigation against the live page list and the revision pull recorded (an unchanged tree under a stale revision is listed ready with settlesLostPush, so apply settles a push whose answer was lost) — and lists "
       + "every problem with its area, file, code and field. It then orders the steps that remain: media upload, "
       + "pages push, footer push (theme push refuses unsaved footer content), theme push, nav push, each marked "
       + "ready, blocked, or nothing to do with the reason for its place. The result's planHash covers what each "
@@ -463,6 +500,13 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
     tokens: ["nav", "push"],
     summary: "Replace the whole navigation tree from the local workspace.",
+    note: "Fenced by the navigation revision that 'pull' recorded in the manifest: a tree edited in the app since is "
+      + "refused with nav.concurrent_modification and nothing is written; keep a copy of nav.json, run 'pull', "
+      + "re-apply the edits and push again. A manifest with no navigation revision is refused with nav.pull_required. "
+      + "The result's navigation.revision is the revision this push saved, and nav.json and the manifest are updated "
+      + "to match, so the next push is fenced against it. A push whose answer was lost after it committed is settled by running it again: the site already holds the file's tree, so nothing is sent and the result says navigation.alreadyApplied. A page deleted in the app also drops its navigation items "
+      + "and so moves the revision: pull before the next push. Every PAGE target is checked against the site's page "
+      + "list, and the items the replace removes are named in navigation.removed.",
   },
   {
     name: VERB_REDIRECTS_CHECK,
@@ -475,7 +519,8 @@ const VERBS = Object.freeze([
       + "following redirects. A redirect is live only with the release that carries it, so this reads the staged release. "
       + "The check authenticates with its own handoff and never reports it. The result carries no review URL unless "
       + "you pass --handoff, which adds a fresh single-use one in stagingPreview.url (keep it private); "
-      + "'staging review' mints one at any time.",
+      + "'staging review' mints one at any time. Every run mints its own handoff, which ends an earlier review "
+      + "link minted with the same key (see 'help preview').",
   },
   {
     name: VERB_REDIRECTS_PULL,
@@ -566,6 +611,34 @@ const VERBS = Object.freeze([
       + "at render time, so never copy default mappings into a theme: a pinned token shadows its role. Contrast and "
       + "status-color warnings name the nearest passing value the CLI found and checked.",
   },
+  {
+    name: VERB_THEME_RESOLVE,
+    surface: SURFACE_DOCS_PRESENTATION,
+    // Only --site reads the site, and that is the one read of the presentation theme push also makes.
+    capabilities: [CAPABILITY_DESIGN],
+    tokens: ["theme", "resolve"],
+    json: true,
+    resolveOptions: true,
+    summary: "Print the colors Espalier compiles from the theme, per scheme and context, with their contrast ratios.",
+    note: "Reads the pulled workspace's settings/taproot-styles.json offline (run pull first; no credential, no network) "
+      + "and compiles it through Espalier's own pipeline, the one theme push lints and the published page renders "
+      + "through, so a value here cannot differ from the render. For the root page and every declared context in "
+      + "each scheme it lists every semantic color token as oklch and hex (hex is the sRGB the engine gamut-maps the "
+      + "color to), whether it is compiled from the roles or pinned in semanticMappings (origin compiled, pinned, "
+      + "or inherited_pin for a root pin a context carries), and the ramp stop or anchor it came from. It also "
+      + "measures every ink-on-surface pairing Espalier defines (text on background, links, headings, the action "
+      + "label, and so on): the WCAG ratio against the AA minimum (4.5:1 for text, 3:1 for large text and UI) and "
+      + "the APCA Lc against Espalier's target. A pair under AA is listed in flags with the stable code "
+      + "theme.contrast_text_below_aa and the field to edit (for example "
+      + "darkTheme.contexts.inverted); flags never refuse, so the exit code stays 0. An invalid or incomplete theme "
+      + "is refused with the code theme push and validate use, the first fault in error.code and error.field. Without --json the output "
+      + "is a readable table; --json writes the stable result (schemes[].surfaces[].tokens and pairs, contrast, flags). "
+      + "--scheme and --context narrow the output only; the whole pair is always validated. A result too large for "
+      + "the output bound names the surfaces it left out in omittedSurfaces (items, count, truncated). --site reads the site's stored theme "
+      + "instead of the workspace (the effective theme pull would write), which compares a workspace edit with what is "
+      + "live: run it with and without --site. A pair under AA is a finding to read, not a failure: a brand color "
+      + "may be a deliberate choice. See 'taproot-site help theme'.",
+  },
   {
     name: VERB_FOOTER_PUSH,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -634,7 +707,8 @@ const VERBS = Object.freeze([
       + `serving the previous release for up to ${LIMITS.stagingPropagationCeilingSeconds} seconds after a deployment completes, so a Standard site's `
       + "deploy --staging waits until staging serves the new release and reports stagingServed: state served, "
       + "propagating (still the previous release at the bound) or unverified (the change cannot be attributed to this deployment, or the last read did not name the previous release), "
-      + "with the time to wait or the seconds waited.",
+      + "with the time to wait or the seconds waited. "
+      + STAGING_REVIEW_SESSION_NOTE,
   },
   {
     name: VERB_PREVIEW_PAGE,
@@ -695,11 +769,11 @@ const VERBS = Object.freeze([
     tokens: ["staging", "review"],
     summary: "Mint a fresh single-use review handoff for the site's staging host.",
     reviewPath: true,
-    note: "The handoff URL is reported only in the final JSON as stagingPreview.url, is single-use, and expires two "
-      + "minutes after it is minted; keep it private. --path <page> opens the review on that page instead of the "
+    note: "The handoff URL is reported only in the final JSON as stagingPreview.url; keep it private. --path <page> opens the review on that page instead of the "
       + "home page: a page path as 'pull' records it ('about', '/posts/one'), optionally with a query. Open it once, then use the site's theme toggle to review both "
       + "schemes. deploy --staging and redirects check report no review URL unless you pass --handoff, so this is "
-      + "the usual way to get one, on a managed Docs site too.",
+      + "the usual way to get one, on a managed Docs site too. "
+      + STAGING_REVIEW_SESSION_NOTE,
   },
   {
     name: VERB_STATUS,
@@ -845,6 +919,8 @@ function verbHelp(verb) {
     ? " <place-id> <category>"
     : verb.positionals === "placeId"
     ? " <place-id>"
+    : verb.positionals === "deletePagePath"
+    ? " <page-path>"
     : verb.positionals === "metaPagePath"
     ? " <page-path> [--title <text>] [--description <text>] [--author <handle-or-email>]"
     : verb.positionals === "authorHandle"
@@ -883,9 +959,15 @@ function verbHelp(verb) {
     ? `\n  --name <text>        The name readers see on the byline (required).
   --email <address>    A private address, kept to link the person to an account later (optional).`
     : "";
-  const jsonOption = verb.json
+  const jsonOption = verb.json && !verb.resolveOptions
     ? "\n  --json           Emit the stable JSON contract (operational output is always JSON)."
     : "";
+  const resolveOptions = verb.resolveOptions
+    ? `\n  --scheme <light|dark>  Describe one scheme (default: both).
+  --context <name>       Describe one declared context only, not the root page.
+  --site                 Read the site's theme instead of the workspace's; needs a sign-in.
+  --json                 Write the stable JSON result instead of the table.`
+    : "";
   const dryRunOption = verb.dryRun
     ? "\n  --dry-run        Read the site and report what a push would change, without writing."
     : "";
@@ -914,7 +996,11 @@ function verbHelp(verb) {
     ? " It refuses only when a previous sign-in exchange recorded a newer published release than this CLI, because "
       + "Taproot accepts only the latest; with nothing recorded it runs."
     : "";
-  const boundary = verb.name === VERB_VALIDATE
+  const boundary = verb.name === VERB_THEME_RESOLVE
+    ? "By default this verb reads the pulled workspace and uses no credential, makes no network request, and writes "
+      + `nothing to the workspace or the site (GITHUB_OUTPUT, when set, receives the JSON result). With --site it reads the site's presentation with the site-scoped credential from ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} `
+      + `or the sign-in '${CLI_BINARY_NAME} ${VERB_LOGIN}' stores.${upgradeGate}`
+    : verb.name === VERB_VALIDATE
     ? "Validation uses no credential, network or write; it reads the configuration only to find the workspace when "
       + "no directory is given. With --init it reads the pulled workspace or selected configuration and writes a new "
       + `fixture directory, still without credentials or network.${upgradeGate}`
@@ -964,7 +1050,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
+${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${planOption}${nameOption}${note}
 `;
 }
 
@@ -1254,6 +1340,32 @@ function parseNameOption(arguments_, index) {
   return candidate;
 }
 
+const THEME_RESOLVE_SCHEMES = Object.freeze(["light", "dark"]);
+
+function parseThemeScheme(arguments_, index) {
+  const candidate = arguments_[index + 1];
+  if (!THEME_RESOLVE_SCHEMES.includes(candidate)) {
+    throw usageError("theme.scheme_invalid", "--scheme requires 'light' or 'dark'.", { field: "scheme" });
+  }
+  return candidate;
+}
+
+function parseThemeContext(arguments_, index) {
+  const candidate = arguments_[index + 1];
+  if (
+    typeof candidate !== "string"
+    || candidate.length === 0
+    || [...candidate].length > MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS
+    || hasAsciiControl(candidate)
+    || candidate.startsWith("--")
+  ) {
+    throw usageError("theme.context_invalid", "--context requires the name of one declared context.", {
+      field: "context",
+    });
+  }
+  return candidate;
+}
+
 function parseArguments(arguments_) {
   if (!Array.isArray(arguments_) || arguments_.some((argument) => typeof argument !== "string")) {
     throw usageError("cli.usage", "The command line must be a list of strings.");
@@ -1314,6 +1426,9 @@ function parseArguments(arguments_) {
   let since;
   let dryRun = false;
   let json = false;
+  let themeScheme;
+  let themeContext;
+  let fromSite = false;
   let keyName;
   let planHash;
   let metaTitle;
@@ -1423,6 +1538,23 @@ function parseArguments(arguments_) {
       json = true;
       continue;
     }
+    if (verb.resolveOptions && argument === "--scheme") {
+      if (themeScheme !== undefined) throw usageError("cli.duplicate_option", "--scheme may be supplied only once.");
+      themeScheme = parseThemeScheme(rest, index);
+      index += 1;
+      continue;
+    }
+    if (verb.resolveOptions && argument === "--context") {
+      if (themeContext !== undefined) throw usageError("cli.duplicate_option", "--context may be supplied only once.");
+      themeContext = parseThemeContext(rest, index);
+      index += 1;
+      continue;
+    }
+    if (verb.resolveOptions && argument === "--site") {
+      if (fromSite) throw usageError("cli.duplicate_option", "--site may be supplied only once.");
+      fromSite = true;
+      continue;
+    }
     if (verb.planHash && argument === "--plan") {
       if (planHash !== undefined) throw usageError("cli.duplicate_option", "--plan may be supplied only once.");
       planHash = parsePlanOption(rest, index);
@@ -1554,6 +1686,11 @@ function parseArguments(arguments_) {
       { field: "environmentSelector" },
     );
   }
+  if (verb.positionals === "deletePagePath" && positionals.length !== 1) {
+    throw usageError("pages.delete_path_invalid", "pages delete names exactly one page path.", {
+      field: "pagePath",
+    });
+  }
   if (verb.positionals === "metaPagePath" && positionals.length !== 1) {
     throw usageError("pages.meta_path_invalid", "pages meta set names exactly one page path ('/' for the homepage).", {
       field: "pagePath",
@@ -1624,7 +1761,11 @@ function parseArguments(arguments_) {
     ...(browser === undefined ? {} : { browser }),
     init,
     dryRun,
+    json,
     keyName,
+    ...(themeScheme === undefined ? {} : { themeScheme }),
+    ...(themeContext === undefined ? {} : { themeContext }),
+    ...(fromSite ? { fromSite } : {}),
     ...(planHash === undefined ? {} : { planHash }),
     ...(metaTitle === undefined ? {} : { metaTitle }),
     ...(metaDescription === undefined ? {} : { metaDescription }),
@@ -1636,7 +1777,7 @@ function parseArguments(arguments_) {
         key: verb.positionals,
         values: positionals,
         scalar: verb.positionals === "pageSelector" || verb.positionals === "fixturePath" || verb.positionals === "metaPagePath"
-          || verb.positionals === "siteSelector" || verb.positionals === "environmentSelector"
+          || verb.positionals === "deletePagePath" || verb.positionals === "siteSelector" || verb.positionals === "environmentSelector"
           || verb.positionals === "authorHandle",
       }
       : undefined,
@@ -1718,6 +1859,9 @@ export async function runCli({
       quiet: parsed.quiet,
       dryRun: parsed.dryRun,
       keyName: parsed.keyName,
+      ...(parsed.themeScheme === undefined ? {} : { themeScheme: parsed.themeScheme }),
+      ...(parsed.themeContext === undefined ? {} : { themeContext: parsed.themeContext }),
+      ...(parsed.fromSite === undefined ? {} : { fromSite: parsed.fromSite }),
       ...(parsed.planHash === undefined ? {} : { planHash: parsed.planHash }),
       // Only when given, like the other optional fields, so each verb keeps its default (TR00925).
       ...(parsed.deliveryUrl === undefined ? {} : { deliveryUrl: parsed.deliveryUrl }),
@@ -1756,7 +1900,8 @@ export async function runCli({
     if (!isValidationInvocation && environment.GITHUB_OUTPUT) {
       await writeGithubActionsOutput(environment.GITHUB_OUTPUT, result);
     }
-    stdout.write(`${json}\n`);
+    // The table is this verb's default view; --json asks for the contract. A failure is always the JSON result.
+    stdout.write(parsed.verb === VERB_THEME_RESOLVE && !parsed.json ? formatThemeResolve(result) : `${json}\n`);
     return 0;
   } catch (unknownError) {
     progress?.stop();

package/src/constants.js

@@ -84,6 +84,7 @@ export const VERB_LOGIN = "login";
 export const VERB_LOGOUT = "logout";
 export const VERB_PAGES_PUSH = "pages push";
 export const VERB_PAGES_META_SET = "pages meta set";
+export const VERB_PAGES_DELETE = "pages delete";
 export const VERB_AUTHORS_LIST = "authors list";
 export const VERB_AUTHORS_ADD = "authors add";
 export const VERB_NAV_PUSH = "nav push";
@@ -94,6 +95,7 @@ export const VERB_FORMS_PULL = "forms pull";
 export const VERB_FORMS_PUSH = "forms push";
 export const VERB_FORMS_VALIDATE = "forms validate";
 export const VERB_THEME_PUSH = "theme push";
+export const VERB_THEME_RESOLVE = "theme resolve";
 export const VERB_FOOTER_PUSH = "footer push";
 export const VERB_MEDIA_UPLOAD = "media upload";
 export const VERB_APPROVE = "approve";
@@ -112,6 +114,19 @@ export const VERB_CHANGELOG = "changelog";
 export function changelogCommandSince(version) {
   return `${CLI_BINARY_NAME} ${VERB_CHANGELOG} --since ${version}`;
 }
+
+/**
+ * How long a staging review lasts and what ends it (TR01237). The numbers come from the API's
+ * StagingPreviewProtocol (handoff 2 minutes, session 5 minutes, no renewal); every help topic, verb note and
+ * result that tells a reader about them repeats this one text.
+ */
+export const STAGING_REVIEW_SESSION_NOTE = "A review handoff works once and expires two minutes after it is minted. "
+  + "Opening it starts a five-minute review session in that browser, and the session never renews: afterwards the "
+  + "staging site redirects to the Taproot sign-in, so a reviewer without a Taproot account that can preview the "
+  + "site needs a fresh link. Minting another handoff with the same key for the same site (staging review, "
+  + "deploy --staging on a Standard site or with --handoff, redirects check or delivery check --staging) ends the earlier link and any session opened "
+  + "from it, and that browser then shows 'Staging preview unavailable'; mint the link last, just before the "
+  + "reviewer opens it.";
 export const VERB_PLAN = "plan";
 export const VERB_APPLY = "apply";
 export const VERB_PLACES_SEARCH = "places search";
@@ -119,6 +134,8 @@ export const VERB_PLACES_SELECT = "places select";
 export const VERB_PLACES_CATEGORY_SET = "places category set";
 export const VERB_PLACES_CATEGORY_CLEAR = "places category clear";
 export const VERB_PLACES_CATEGORY_LIST = "places category list";
+/** A bare 64-character lowercase hex digest: the shape of every revision and draft hash the site reports. */
+export const HEX_DIGEST = /^[0-9a-f]{64}$/u;
 /** The identity `plan` reports and `apply --plan` requires. */
 export const PLAN_HASH = /^sha256:[0-9a-f]{64}$/u;
 export const VERB_ENV = "env";

package/src/footer-workspace.js

@@ -1,3 +1,4 @@
+import { HEX_DIGEST } from "./constants.js";
 import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
 import { appearanceImageIds } from "./appearance-contract.js";
 import { footerImageIds } from "./footer-contract.js";
@@ -6,7 +7,7 @@ import { computeFooterContentHash, computeFooterDraftHash, stableJson } from "./
 import { readManifest, readMediaManifest, writeManifest } from "./workspace.js";
 
 export const FOOTER_SETTINGS_FILE = "settings/site-publishing-preferences.json";
-const SHA256 = /^[0-9a-f]{64}$/u;
+const SHA256 = HEX_DIGEST;
 
 function invalid(message, field) {
   throw new SiteAuthoringError("footer.pull_required", message, { field });