@taprootio/site-authoring 0.16.0 → 0.18.0

package/README.md

@@ -464,7 +464,8 @@ moved since this workspace last reconciled with it, naming both revisions;
 names and reports predictions with a session token; `places select
 <googlePlaceId> <sessionToken>` records the match as a Taproot place and
 reports the `placeId` a place review's front matter needs. An article or an
-album can name its place the same way with `place:`.
+album can name its place the same way with `place:`. `places category set
+<placeId> <category>` changes the category this site shows for a place.
 
 `plan` checks the whole workspace against the live site — pages, the media
 they reference and the images the settings name, the footer and the pages it
@@ -567,8 +568,10 @@ paused; retry later), `credential_rejected` (stop and re-issue),
 not exchanged for a capability the request needs; the refusal carries
 `field: "GrantedCapabilities"`, and the CLI's human progress names the
 granted and required capabilities, so report the verb's declared set rather
-than re-issuing the key), `plan_limit` (the plan's published-page allowance,
-surfaced at deploy), and `throttled` (back off).
+than re-issuing the key), `plan_limit` (the plan's published-page allowance or
+its pages-generated allowance, or the bandwidth pause on deploys,
+surfaced at deploy; the allowance shows its reset time, while the bandwidth pause shows the earliest
+time it can lift, since it lifts only after a month ends under the allowance or on upgrade), and `throttled` (back off).
 
 When `GITHUB_OUTPUT` names the runner's existing output file, every
 operational verb appends the same JSON under `taproot_site_result` through a
@@ -635,17 +638,49 @@ 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`.
 
-### Link rel in 0.15.0
+### Place categories in 0.18.0
 
-A link publishes followed unless its author chooses otherwise. A link mark's
-`rel` takes space-separated link types (`nofollow`, `sponsored`, `ugc`, `me`,
-and the other standard types except `opener`), on any link; `target: "_blank"`
-opens a new tab with `noopener noreferrer` added. In Markdown, write
-`[Shop](https://shop.example){rel="sponsored nofollow" target="_blank"}`
-(either attribute alone works). Other tokens and
-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`.
+A place has one category for every site, taken from Google's types, and a place
+that Taproot could not classify is filed under `Other`. A site can file a place
+under a category of its own:
+
+```
+taproot-site places category list
+taproot-site places category set <placeId> park
+taproot-site places category clear <placeId>
+```
+
+`list` prints the closed list `set` accepts; a name outside it is refused, and
+capitalization is ignored. The category is the site's alone and applies to every
+review of that place on the site: the place itself and other sites do not
+change. Place-review bylines and the `/places/<category>` pages use it from the
+site's next deployment, including reviews nobody has edited. `clear` removes it.
+Both need the same page-editing permission as `places select`.
+
+### Pages generated in 0.18.0
+
+A site's licence allows a number of pages generated per billing period, and
+`deploy --staging` is charged by the pages it generates, not by the deployment.
+The deploy asks Taproot to plan the candidate first and reports the plan before
+it sends anything: `This will generate 74 pages · 940 of 1,000 left this period
+(resets 2026-11-01T00:00:00.000Z)`. The same figures are in `readiness.pageEstimate`
+(`plannedPageCount`, `pagesGeneratedLimit`, `pagesGeneratedRemaining`, `periodEnd`
+and `exceedsAllowance`; a limit and what remains are `null` on an unlimited
+licence). The number shown is the number charged. Promoting a staged release to
+production generates nothing and costs no pages.
+
+A candidate that does not fit stops with `deploy.page_allowance_exceeded`, naming
+the pages it needs, the pages left, and the reset. A deploy refused by the server
+for the same reason, or for the bandwidth pause, reports `plan_limit` with the
+time it can lift (and `requested_pages` and `remaining_pages` for the allowance):
+the allowance's reset, or for the bandwidth pause the earliest month end that can
+clear it (an upgrade clears it at once).
+
+### Deployment allowances in 0.18.0
+
+A deploy refused for the bandwidth pause reports `plan_limit` with the time it
+can lift: the earliest month end that can clear it (an upgrade clears it at
+once).
 
 ### Authoring feedback in 0.16.0
 
@@ -666,6 +701,18 @@ old default, `noopener noreferrer nofollow`, reads as no choice. See
   generated pages navigation links to), and `validate` and `pages push` warn on
   links that look made by autolinking (`content.link_autolinked`).
 
+### Link rel in 0.15.0
+
+A link publishes followed unless its author chooses otherwise. A link mark's
+`rel` takes space-separated link types (`nofollow`, `sponsored`, `ugc`, `me`,
+and the other standard types except `opener`), on any link; `target: "_blank"`
+opens a new tab with `noopener noreferrer` added. In Markdown, write
+`[Shop](https://shop.example){rel="sponsored nofollow" target="_blank"}`
+(either attribute alone works). Other tokens and
+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`.
+
 ### Staging verification and deployment evidence
 
 `deploy --staging` selects the same changed pages, settings groups and navigation

package/package.json

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

package/src/api.js

@@ -1,5 +1,6 @@
 import { normalizeLatestCliVersion } from "./cli-release.js";
 import {
+  BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CANONICAL_TIMESTAMP,
   CAPABILITY_REFUSAL_FIELD,
   CLI_UPGRADE_COMMAND,
@@ -437,6 +438,34 @@ export function announceRefusal(error, onProgress, action = "request") {
   }
   if (kind === REFUSAL_PLAN_LIMIT) {
     onProgress("");
+    if (error.planLimit !== undefined) {
+      // The allowance and bandwidth refusals ride an ErrorInfo detail, not the
+      // UpgradePrompt field, and name when they can next lift on their own.
+      const bandwidth = error.planLimit.reason === BANDWIDTH_ALLOWANCE_REFUSAL_REASON;
+      onProgress(`PLAN LIMIT (refusal=plan_limit, reason=${error.planLimit.reason})`);
+      onProgress(
+        bandwidth
+          ? `  Taproot paused this ${action}: the site's measured bandwidth was over its monthly allowance for two `
+            + "months in a row. The published site keeps serving; only new deployments wait."
+          : error.planLimit.requestedPages === undefined
+          ? `  Taproot refused this ${action}: it generates more pages than the site's allowance for this billing period has left.`
+          : `  Taproot refused this ${action}: it generates ${pagesLabel(error.planLimit.requestedPages)} and the site has ${
+            (error.planLimit.remainingPages ?? 0).toLocaleString("en-US")
+          } left for this billing period.`,
+      );
+      // The bandwidth pause is not an unconditional reset: it lifts only after
+      // a month ends under the allowance (or on upgrade), so the instant is
+      // the earliest that can happen.
+      onProgress(
+        error.planLimit.resetsAt === undefined
+          ? "  Upgrade the site's plan, then run the request again."
+          : bandwidth
+          ? `  Upgrade the site's plan, or deployments resume after a month ends under the allowance (no earlier than ${error.planLimit.resetsAt}).`
+          : `  Resets at: ${error.planLimit.resetsAt}. Upgrade the site's plan to continue sooner.`,
+      );
+      onProgress("");
+      return;
+    }
     onProgress("PLAN LIMIT (refusal=plan_limit, field=UpgradePrompt)");
     onProgress(
       `  Taproot refused this ${action} against a plan ceiling rather than a content problem.`,
@@ -996,6 +1025,45 @@ export async function selectPlace(client, siteId, { googlePlaceId, sessionToken
   };
 }
 
+function normalizeSiteCategory(value) {
+  const state = requireObject(value, "api.place_contract", "site place category");
+  return {
+    placeId: requireIdentifier(state.placeId, "api.place_contract", "placeId"),
+    category: text(state.category),
+    placeCategory: text(state.placeCategory),
+    isOverride: state.isOverride === true,
+  };
+}
+
+/** Sets this site's own category for a place; the place itself and other sites are unchanged. */
+export async function setPlaceCategory(client, siteId, { placeId, category }) {
+  return normalizeSiteCategory(
+    await client.request(sitePath(siteId, `places/${encodeURIComponent(placeId)}/category`), {
+      method: "PUT",
+      body: { siteId, placeId, category },
+    }),
+  );
+}
+
+/** Removes this site's category for a place, so the place's own category applies again. */
+export async function clearPlaceCategory(client, siteId, { placeId }) {
+  return normalizeSiteCategory(
+    await client.request(sitePath(siteId, `places/${encodeURIComponent(placeId)}/category`), { method: "DELETE" }),
+  );
+}
+
+/** The closed list of place categories, in Taproot's order. */
+export async function listPlaceCategories(client) {
+  const response = requireObject(
+    await client.request(`v1/standard-types${query([["typeGroup", "place_category"], ["maxResults", 1000]])}`),
+    "api.place_contract",
+    "place categories",
+  );
+  return (Array.isArray(response.standardTypes) ? response.standardTypes : [])
+    .map((type) => text(requireObject(type, "api.place_contract", "place category").name))
+    .filter((name) => name !== "");
+}
+
 /**
  * Processing is observed through `ListSiteImages`; `GetImageById` is
  * session-only under TR00602's read list, so a key-authorized client watches
@@ -1122,18 +1190,20 @@ export async function getDeploySelection(client, siteId) {
 }
 
 export async function getPublishingReadiness(client, siteId, selection = {}) {
+  // A body, not a query: the exact selection can run past a URL's limit, and the
+  // estimate must plan the pages the deploy will stage (TR01201).
   const response = requireObject(
-    await client.request(sitePath(
-      siteId,
-      `publishing/readiness${
-        query([
-          ["stagedPageIds", selection.stagedPageIds],
-          ["selectedSettingsTypes", selection.selectedSettingsTypes],
-          ["includeNavigation", selection.includeNavigation],
-          ["useExactPageSelection", selection.useExactPageSelection],
-        ])
-      }`,
-    )),
+    await client.request(sitePath(siteId, "publishing/readiness"), {
+      method: "POST",
+      body: {
+        stagedPageIds: selection.stagedPageIds,
+        selectedSettingsTypes: selection.selectedSettingsTypes,
+        includeNavigation: selection.includeNavigation,
+        useExactPageSelection: selection.useExactPageSelection,
+        includePageEstimate: selection.includePageEstimate,
+        allowFailedPreview: selection.allowFailedPreview,
+      },
+    }),
     "api.readiness_contract",
     "publishing readiness",
   );
@@ -1154,10 +1224,50 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
     redirectsChanged: response.redirectsChanged === true,
     formsChanged: response.formsChanged === true,
     videosChanged: response.videosChanged === true,
+    // The pages staging this candidate would generate, which is the number charged (TR01201).
+    // Absent unless asked for and the candidate could be planned.
+    pageEstimate: pageEstimate(response),
     blockers,
   };
 }
 
+/**
+ * The server's plan for a candidate: the pages staging it generates, the
+ * allowance left this period and when it resets. The CLI never computes any of
+ * it; limit, remaining and period end are null for an unlimited licence.
+ */
+function pageEstimate(response) {
+  if (!Number.isSafeInteger(response.plannedPageCount) || response.plannedPageCount < 0) return null;
+  const periodEnd = typeof response.pagesGeneratedPeriodEnd === "string"
+    ? new Date(response.pagesGeneratedPeriodEnd)
+    : undefined;
+  return {
+    plannedPageCount: response.plannedPageCount,
+    pagesGeneratedLimit: Number.isSafeInteger(response.pagesGeneratedLimit) ? response.pagesGeneratedLimit : null,
+    pagesGeneratedRemaining: Number.isSafeInteger(response.pagesGeneratedRemaining)
+      ? response.pagesGeneratedRemaining
+      : null,
+    periodEnd: periodEnd !== undefined && !Number.isNaN(periodEnd.getTime()) ? periodEnd.toISOString() : null,
+    exceedsAllowance: response.plannedPagesExceedAllowance === true,
+  };
+}
+
+const pagesLabel = (count) => `${count.toLocaleString("en-US")} ${count === 1 ? "page" : "pages"}`;
+
+/**
+ * The one line that states a candidate's plan in pages (TR01201), shared by the
+ * progress output and the refusal so the two never word it differently.
+ */
+export function describePageEstimate(estimate) {
+  const generates = `This will generate ${pagesLabel(estimate.plannedPageCount)}`;
+  if (estimate.pagesGeneratedLimit === null || estimate.pagesGeneratedRemaining === null) return generates;
+  const left = `${estimate.pagesGeneratedRemaining.toLocaleString("en-US")} of ${
+    estimate.pagesGeneratedLimit.toLocaleString("en-US")
+  } left this period`;
+  const resets = estimate.periodEnd === null ? "" : ` (resets ${estimate.periodEnd})`;
+  return `${generates} · ${left}${resets}`;
+}
+
 export async function getStagingPreviewStatus(client, siteId) {
   const response = requireObject(
     await client.request(sitePath(siteId, "staging-preview/status")),
@@ -1353,6 +1463,14 @@ export async function deploySite(client, siteId, body) {
         { field: "AuthoringPreviewFailed", status: error.status },
       );
     }
+    if (error instanceof ApiError && error.hasField("ExpectedPageCount")) {
+      throw new SiteAuthoringError(
+        "deploy.page_estimate_changed",
+        `${error.descriptionFor("ExpectedPageCount") ?? "The pages this publish generates have grown since the estimate."} `
+          + "Nothing was staged; run the command again to confirm the new count.",
+        { field: "ExpectedPageCount", status: error.status },
+      );
+    }
     throw error;
   }
   const deployment = normalizeDeployment(response.deployment);

package/src/cli.js

@@ -34,6 +34,9 @@ import {
   VERB_NAV_PUSH,
   VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
+  VERB_PLACES_CATEGORY_CLEAR,
+  VERB_PLACES_CATEGORY_LIST,
+  VERB_PLACES_CATEGORY_SET,
   VERB_PLACES_SEARCH,
   VERB_PLACES_SELECT,
   VERB_PLAN,
@@ -350,6 +353,39 @@ const VERBS = Object.freeze([
       + "once for every site, so selecting it again returns the same placeId. Use it as placeId in a place review, "
       + "or as place in an article or album.",
   },
+  {
+    name: VERB_PLACES_CATEGORY_SET,
+    surface: SURFACE_STANDARD,
+    // Changes what the site's place reviews publish, so it needs page editing.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "set"],
+    positionals: "placeCategory",
+    summary: "Set this site's category for a place, from the closed category list.",
+    note: "Takes the placeId from 'places select' (or a page's front matter), then one category from "
+      + "'places category list', which prints the closed list; a name outside it is refused, and capitalization is "
+      + "ignored. Use it when Google's own category for a place is not the one this site wants, such as a park filed "
+      + "under Other. The category is this site's alone and applies to every review of that place here: the place "
+      + "itself and other sites do not change. Place-review bylines and the /places/<category> pages use it from the "
+      + "next deployment, which a changed category alone is enough to start. Undo it with 'places category clear'.",
+  },
+  {
+    name: VERB_PLACES_CATEGORY_CLEAR,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "clear"],
+    positionals: "placeId",
+    summary: "Remove this site's category for a place, so the place's own category applies again.",
+    note: "Takes the placeId. Clearing a place this site never set succeeds and changes nothing. Pages use the "
+      + "place's own category from the next deployment.",
+  },
+  {
+    name: VERB_PLACES_CATEGORY_LIST,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "list"],
+    summary: "List the place categories 'places category set' accepts.",
+    note: "The list is closed: a category outside it is refused.",
+  },
   {
     name: VERB_PLAN,
     surface: SURFACE_STANDARD,
@@ -713,7 +749,7 @@ upgrade. Once a run has recorded a newer release, help, validate, and whoami
 refuse the same way offline. --version and --help always answer.
 
 Verbs:
-${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(14)} ${verb.summary}`).join("\n")}
+${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(20)} ${verb.summary}`).join("\n")}
 
 Configuration:
   Site verbs read taproot-site.json, found by walking up from the current
@@ -756,6 +792,10 @@ function verbHelp(verb) {
     ? " <query...>"
     : verb.positionals === "placeSelection"
     ? " <google-place-id> <session-token>"
+    : verb.positionals === "placeCategory"
+    ? " <place-id> <category>"
+    : verb.positionals === "placeId"
+    ? " <place-id>"
     : verb.positionals === "metaPagePath"
     ? " <page-path> [--title <text>] [--description <text>] [--author <handle-or-email>]"
     : verb.positionals === "authorHandle"

package/src/constants.js

@@ -110,6 +110,9 @@ export const VERB_PLAN = "plan";
 export const VERB_APPLY = "apply";
 export const VERB_PLACES_SEARCH = "places search";
 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";
 /** The identity `plan` reports and `apply --plan` requires. */
 export const PLAN_HASH = /^sha256:[0-9a-f]{64}$/u;
 export const VERB_ENV = "env";
@@ -204,6 +207,19 @@ export const CAPABILITY_REFUSAL_REASON = "SITE_AUTHORING_CAPABILITY_MISSING";
  */
 export const CAPABILITY_REFUSAL_FIELD = "GrantedCapabilities";
 
+/**
+ * The `google.rpc.ErrorInfo` reasons a deploy carries when the site has hit a
+ * commercial ceiling that no retry can clear (TR00445): the deployments-per-
+ * billing-period allowance, or the bandwidth pause. Wire identities matched
+ * exactly, within {@link SITE_DEPLOYMENT_REFUSAL_DOMAIN}. The refusal is
+ * classified `plan_limit`, the same class as the page-count `UpgradePrompt`
+ * field, because the right next move is the same: upgrade, or wait for the
+ * reset the server names in `resets_at`.
+ */
+export const DEPLOYMENT_ALLOWANCE_REFUSAL_REASON = "DEPLOYMENT_PERIOD_ALLOWANCE_EXCEEDED";
+export const BANDWIDTH_ALLOWANCE_REFUSAL_REASON = "BANDWIDTH_ALLOWANCE_EXCEEDED";
+export const SITE_DEPLOYMENT_REFUSAL_DOMAIN = "sites.taproot.io";
+
 // gRPC `ResourceExhausted`. Transcoded responses carry the numeric code in the
 // body; the HTTP mapping is 429.
 export const GRPC_RESOURCE_EXHAUSTED = 8;

package/src/reference-help.js

@@ -86,7 +86,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 35;
+export const REFERENCE_VERSION = 36;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({

package/src/transport.js

@@ -1,10 +1,12 @@
 import {
+  BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CAPABILITY_REFUSAL_FIELD,
   CAPABILITY_REFUSAL_REASON,
   CLI_NAME,
   CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
   CREDENTIAL_REFUSAL_FIELD,
+  DEPLOYMENT_ALLOWANCE_REFUSAL_REASON,
   GRPC_RESOURCE_EXHAUSTED,
   GRPC_UNAUTHENTICATED,
   HTTP_TOO_MANY_REQUESTS,
@@ -21,6 +23,7 @@ import {
   REFUSAL_THROTTLED,
   REFUSAL_UNCLASSIFIED,
   ROLLOUT_REFUSAL_FIELD,
+  SITE_DEPLOYMENT_REFUSAL_DOMAIN,
 } from "./constants.js";
 import { Readable } from "node:stream";
 
@@ -409,15 +412,10 @@ function capabilityNames(value) {
  * keys on it rather than on `@type`, which a future packing could reshape.
  */
 export function capabilityRefusal(value) {
-  const queue = [{ value, depth: 0 }];
-  let work = 0;
-  while (queue.length > 0 && work < 1_000) {
-    const current = queue.shift();
-    work += 1;
-    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
-    const metadata = current.value.metadata;
+  return findErrorInfo(value, (detail) => {
+    const metadata = detail.metadata;
     if (
-      current.value.reason === CAPABILITY_REFUSAL_REASON
+      detail.reason === CAPABILITY_REFUSAL_REASON
       && metadata !== null
       && typeof metadata === "object"
       && !Array.isArray(metadata)
@@ -434,6 +432,61 @@ export function capabilityRefusal(value) {
         });
       }
     }
+    return undefined;
+  });
+}
+
+/**
+ * The pages-generated allowance or bandwidth-pause refusal the deploy API attaches
+ * as a `google.rpc.ErrorInfo` detail (TR00445, TR01201), or undefined. Keyed on the
+ * namespaced domain and reason, never the message sentence. `resetsAt` is the
+ * server's `resets_at` re-serialized as an ISO-8601 UTC instant, or undefined
+ * when it is absent (a licence that grants no deployments has no period) or
+ * does not parse. `requestedPages` and `remainingPages` are present on the
+ * allowance refusal only.
+ */
+export function planLimitRefusal(value) {
+  return findErrorInfo(value, (detail) => {
+    if (
+      detail.domain !== SITE_DEPLOYMENT_REFUSAL_DOMAIN
+      || (detail.reason !== DEPLOYMENT_ALLOWANCE_REFUSAL_REASON && detail.reason !== BANDWIDTH_ALLOWANCE_REFUSAL_REASON)
+    ) {
+      return undefined;
+    }
+    const metadata = detail.metadata !== null && typeof detail.metadata === "object" ? detail.metadata : {};
+    const resetsAt = typeof metadata.resets_at === "string" ? new Date(metadata.resets_at) : undefined;
+    return Object.freeze({
+      reason: detail.reason,
+      resetsAt: resetsAt !== undefined && !Number.isNaN(resetsAt.getTime()) ? resetsAt.toISOString() : undefined,
+      // The pages the refused request needed and the period had left (TR01201).
+      requestedPages: pageCount(metadata.requested_pages),
+      remainingPages: pageCount(metadata.remaining_pages),
+    });
+  });
+}
+
+/** A page count the server reported as a decimal string, or undefined. */
+function pageCount(value) {
+  const count = typeof value === "string" && /^[0-9]{1,9}$/u.test(value) ? Number(value) : undefined;
+  return Number.isSafeInteger(count) ? count : undefined;
+}
+
+/**
+ * The first object in `value`, breadth first, for which `match` returns a
+ * result. Transcoded `details[]` entries are `Any`-packed and nested, so one
+ * pinned path through them would silently empty every extractor on a contract
+ * change; the walk is bounded in depth and in work so a hostile body cannot
+ * stall it.
+ */
+function findErrorInfo(value, match) {
+  const queue = [{ value, depth: 0 }];
+  let work = 0;
+  while (queue.length > 0 && work < 1_000) {
+    const current = queue.shift();
+    work += 1;
+    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
+    const found = match(current.value);
+    if (found !== undefined) return found;
     for (const child of Object.values(current.value)) {
       if (child !== null && typeof child === "object") queue.push({ value: child, depth: current.depth + 1 });
     }
@@ -459,6 +512,7 @@ export class ApiError extends SiteAuthoringError {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
     const capability = capabilityRefusal(body);
+    const planLimit = planLimitRefusal(body);
     // Only the known upgrade refusal may supply a human message. Other server
     // errors can contain internal diagnostics and retain their generic output.
     const upgradeMessage = fields.includes(CLI_UPGRADE_REFUSAL_FIELD)
@@ -472,6 +526,10 @@ export class ApiError extends SiteAuthoringError {
       "api.request_rejected",
       upgradeMessage || (fields.length > 0
         ? `Taproot rejected the request field '${fields[0]}'.`
+        : planLimit !== undefined
+        ? planLimit.reason === BANDWIDTH_ALLOWANCE_REFUSAL_REASON
+          ? "Taproot paused deployments: the site used more than its monthly bandwidth for two months in a row."
+          : "Taproot refused the request: it generates more pages than the site's allowance for this billing period has left."
         : capability !== undefined
         ? `Taproot refused the request: this credential does not carry a capability granting '${
           capability.permission
@@ -491,6 +549,7 @@ export class ApiError extends SiteAuthoringError {
     this.fields = fields;
     this.violationDescriptions = fieldDescriptions(body);
     this.capability = capability;
+    this.planLimit = planLimit;
     // The `retry-after` trailer (TR00839's deployment throttle, or any other
     // ResourceExhausted refusal that sets it) transcodes to an ordinary
     // response header. Undefined when absent or unparseable — callers must
@@ -545,10 +604,12 @@ export class ApiError extends SiteAuthoringError {
    *   left it unclassified: no `refusal` in the JSON result, and nothing said
    *   on the human channel. The field arrives only from the in-transaction
    *   re-validation, which does attach `ExternalApiKey`.
-   * - `plan_limit` (field `UpgradePrompt`) — a commercial ceiling, surfaced at
+   * - `plan_limit` (field `UpgradePrompt`, or `ErrorInfo` reason
+   *   `DEPLOYMENT_PERIOD_ALLOWANCE_EXCEEDED` / `BANDWIDTH_ALLOWANCE_EXCEEDED`
+   *   with the server's `resets_at`) — a commercial ceiling, surfaced at
    *   deploy time because no pre-flight read of the published-page quota
-   *   exists on the contract. **Upgrade** (or publish fewer pages); the CLI
-   *   never invents the numeric limit.
+   *   exists on the contract. **Upgrade** (or publish fewer pages, or wait for
+   *   the named reset); the CLI never invents the numeric limit.
    * - `throttled` (gRPC `ResourceExhausted` / HTTP 429) — the per-key
    *   throttle. **Back off** and retry with delay.
    * - `capability_missing` (`ErrorInfo` reason `SITE_AUTHORING_CAPABILITY_MISSING`)
@@ -568,7 +629,7 @@ export class ApiError extends SiteAuthoringError {
     if (this.hasField(CLI_UPGRADE_REFUSAL_FIELD)) return REFUSAL_CLI_OUTDATED;
     if (this.hasField(ROLLOUT_REFUSAL_FIELD)) return REFUSAL_PLATFORM_PAUSED;
     if (this.hasField(CREDENTIAL_REFUSAL_FIELD)) return REFUSAL_CREDENTIAL_REJECTED;
-    if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD)) return REFUSAL_PLAN_LIMIT;
+    if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD) || this.planLimit !== undefined) return REFUSAL_PLAN_LIMIT;
     // The named detail ranks with the fields and above the status mappings, for
     // the same reason: it is the specific statement about this refusal.
     if (this.capability !== undefined) return REFUSAL_CAPABILITY_MISSING;

package/src/typed-page-reference.js

@@ -76,7 +76,9 @@ const FIELD_HELP = Object.freeze({
     required: true,
     description:
       "The Taproot place being reviewed. The site fills in its name, address and coordinates from this record. Find "
-      + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'.",
+      + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'. The site publishes the "
+      + "place's category in the byline and files the review under /places/<category>; change it for this site with "
+      + "'places category set <placeId> <category>'.",
   },
   place: {
     type: "UUID",

package/src/verbs/deploy.js

@@ -4,6 +4,7 @@ import {
   DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
   DEPLOYMENT_STATUS_COMPLETED,
   deploySite,
+  describePageEstimate,
   getDeploySelection,
   getPublishingReadiness,
   listDeployments,
@@ -67,9 +68,6 @@ const REDIRECT_ACTIVATION_NOTE =
  */
 
 const MAXIMUM_REPORTED_BLOCKERS = 50;
-// Staged page ids ride in the readiness query string, so a very large candidate
-// is checked at site level instead of pushing an unbounded URL at the API.
-const MAXIMUM_READINESS_PAGE_IDS = 100;
 
 function usageError(code, message, field) {
   return new SiteAuthoringError(code, message, { field, exitCode: 2 });
@@ -157,6 +155,8 @@ function reportReadiness(readiness) {
     redirectsChanged: readiness.redirectsChanged,
     formsChanged: readiness.formsChanged,
     videosChanged: readiness.videosChanged,
+    // The pages this deployment generates and the allowance left: what staging is charged (TR01201).
+    ...(readiness.pageEstimate === null ? {} : { pageEstimate: readiness.pageEstimate }),
     blockers: blockers.items,
     ...(blockers.truncated ? { blockersTruncated: true } : {}),
   };
@@ -341,8 +341,10 @@ export async function deploy(invocation) {
     );
     const readiness = await getPublishingReadiness(client, siteId, {
       ...candidate,
-      stagedPageIds: stagedPageIds.length > MAXIMUM_READINESS_PAGE_IDS ? undefined : stagedPageIds,
       useExactPageSelection: stagedPageIds.length === 0,
+      includePageEstimate: true,
+      // The estimate must recognize the request it is about to be followed by.
+      ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     if (readiness.blockers.length > 0) {
       throw new SiteAuthoringError(
@@ -368,11 +370,29 @@ export async function deploy(invocation) {
     if (!readiness.hasCandidateChanges) {
       onProgress("Taproot reports this candidate contains no changes; deploying it anyway would be a no-op.");
     }
+    // The plan is the charge: the same page count admission uses, shown before anything is sent.
+    if (readiness.pageEstimate !== null) {
+      onProgress(describePageEstimate(readiness.pageEstimate));
+      if (readiness.pageEstimate.exceedsAllowance) {
+        const estimate = readiness.pageEstimate;
+        throw new SiteAuthoringError(
+          "deploy.page_allowance_exceeded",
+          `This candidate generates ${estimate.plannedPageCount.toLocaleString("en-US")} ${
+            estimate.plannedPageCount === 1 ? "page" : "pages"
+          } but the site has ${(estimate.pagesGeneratedRemaining ?? 0).toLocaleString("en-US")} left for this billing `
+            + `period${estimate.periodEnd === null ? "" : ` (it resets ${estimate.periodEnd})`}. Stage a smaller change, `
+            + "or upgrade the site's plan for a larger allowance. Nothing was sent.",
+          { field: "plannedPageCount" },
+        );
+      }
+    }
 
     const created = await deploySite(client, siteId, {
       siteId,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,
       ...candidate,
+      // Confirms the number just shown: the server refuses if the plan has grown since.
+      ...(readiness.pageEstimate === null ? {} : { expectedPageCount: readiness.pageEstimate.plannedPageCount }),
       ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     onProgress(`Staging deployment ${created.id} accepted; waiting for it to complete.`);

package/src/verbs/index.js

@@ -16,6 +16,9 @@ import {
   VERB_NAV_PUSH,
   VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
+  VERB_PLACES_CATEGORY_CLEAR,
+  VERB_PLACES_CATEGORY_LIST,
+  VERB_PLACES_CATEGORY_SET,
   VERB_PLACES_SEARCH,
   VERB_PLACES_SELECT,
   VERB_PLAN,
@@ -48,7 +51,7 @@ import { mediaUpload } from "./media-upload.js";
 import { navPush } from "./nav-push.js";
 import { pagesMetaSet } from "./pages-meta-set.js";
 import { pagesPush } from "./pages-push.js";
-import { placesSearch, placesSelect } from "./places.js";
+import { placesCategoryClear, placesCategoryList, placesCategorySet, placesSearch, placesSelect } from "./places.js";
 import { apply, plan } from "./plan.js";
 import { previewPage } from "./preview-page.js";
 import { previewRevoke } from "./preview-revoke.js";
@@ -106,6 +109,8 @@ import { whoami } from "./whoami.js";
  *                  //   with none, every file under forms/
  *   placeQuery,    // places search: the words of the query
  *   placeSelection, // places select: [googlePlaceId, sessionToken]
+ *   placeCategory, // places category set: [placeId, category]
+ *   placeId,       // places category clear: [placeId]
  *   pagePaths,     // approve: narrow to these page paths; with none, every
  *                  //   draft the workspace manifest tracks is staged
  *   authorHandle,  // authors add: the handle of the site author to create
@@ -148,6 +153,9 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_PLAN]: plan,
   [VERB_PLACES_SEARCH]: placesSearch,
   [VERB_PLACES_SELECT]: placesSelect,
+  [VERB_PLACES_CATEGORY_SET]: placesCategorySet,
+  [VERB_PLACES_CATEGORY_CLEAR]: placesCategoryClear,
+  [VERB_PLACES_CATEGORY_LIST]: placesCategoryList,
   [VERB_APPLY]: apply,
   [VERB_REDIRECTS_CHECK]: redirectsCheck,
   [VERB_REDIRECTS_PULL]: redirectsPull,

package/src/verbs/media-upload.js

@@ -354,7 +354,6 @@ const VIDEO_REFUSAL_FIELDS = Object.freeze([
   "Video",
   "UpgradePrompt",
   "VideoNotIncluded",
-  "VideoPendingDowngrade",
 ]);
 
 /**

package/src/verbs/places.js

@@ -1,7 +1,21 @@
 import { randomUUID } from "node:crypto";
 
-import { isGooglePlaceId, searchPlaces, selectPlace, withRefusalGuidance } from "../api.js";
-import { VERB_PLACES_SEARCH, VERB_PLACES_SELECT } from "../constants.js";
+import {
+  clearPlaceCategory,
+  isGooglePlaceId,
+  listPlaceCategories,
+  searchPlaces,
+  selectPlace,
+  setPlaceCategory,
+  withRefusalGuidance,
+} from "../api.js";
+import {
+  VERB_PLACES_CATEGORY_CLEAR,
+  VERB_PLACES_CATEGORY_LIST,
+  VERB_PLACES_CATEGORY_SET,
+  VERB_PLACES_SEARCH,
+  VERB_PLACES_SELECT,
+} from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { openSession, successResult } from "../session.js";
 
@@ -18,6 +32,9 @@ import { openSession, successResult } from "../session.js";
  */
 
 const MAXIMUM_QUERY_LENGTH = 200;
+const MAXIMUM_CATEGORY_LENGTH = 100;
+// Any UUID version: the server mints place ids from a sequential-style generator.
+const PLACE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
 const SESSION_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
 
 export async function placesSearch(invocation) {
@@ -59,3 +76,56 @@ export async function placesSelect(invocation) {
   onProgress(`Selected ${place.name}: use placeId ${place.placeId} in the page's front matter.`);
   return successResult(VERB_PLACES_SELECT, siteId, { place });
 }
+
+/**
+ * `places category set|clear|list` — this site's own category for a place
+ * (TR01203).
+ *
+ * A place's category is shared by every site, and Google's types do not always
+ * give the one an owner wants. The override is the site's alone: its place
+ * reviews and `/places/<category>` pages use it from the next deployment, and
+ * the platform-wide place is never changed. The server owns the closed list, so
+ * the CLI sends the name as given and lets the server check it.
+ */
+export async function placesCategorySet(invocation) {
+  const [placeId, category, ...extra] = Array.isArray(invocation.placeCategory) ? invocation.placeCategory : [];
+  if (!PLACE_ID.test(placeId ?? "") || extra.length > 0 || typeof category !== "string"
+    || category.trim() === "" || category.length > MAXIMUM_CATEGORY_LENGTH) {
+    throw new SiteAuthoringError(
+      "places.category_invalid",
+      "places category set takes the placeId, then one category from 'places category list'.",
+      { field: "category", exitCode: 2 },
+    );
+  }
+  const session = await openSession(invocation);
+  const { client, siteId, onProgress } = session;
+  const state = await withRefusalGuidance(onProgress, "place category", async () =>
+    await setPlaceCategory(client, siteId, { placeId, category: category.trim() }));
+  onProgress(`This site now files ${placeId} under ${state.category}; deploy for pages to use it.`);
+  return successResult(VERB_PLACES_CATEGORY_SET, siteId, { placeCategory: state });
+}
+
+export async function placesCategoryClear(invocation) {
+  const [placeId, ...extra] = Array.isArray(invocation.placeId) ? invocation.placeId : [];
+  if (!PLACE_ID.test(placeId ?? "") || extra.length > 0) {
+    throw new SiteAuthoringError(
+      "places.category_invalid",
+      "places category clear takes the placeId of the place whose category this site set.",
+      { field: "placeId", exitCode: 2 },
+    );
+  }
+  const session = await openSession(invocation);
+  const { client, siteId, onProgress } = session;
+  const state = await withRefusalGuidance(onProgress, "place category", async () =>
+    await clearPlaceCategory(client, siteId, { placeId }));
+  onProgress(`This site files ${placeId} under ${state.category} again; deploy for pages to use it.`);
+  return successResult(VERB_PLACES_CATEGORY_CLEAR, siteId, { placeCategory: state });
+}
+
+export async function placesCategoryList(invocation) {
+  const session = await openSession(invocation);
+  const { client, siteId, onProgress } = session;
+  const categories = await withRefusalGuidance(onProgress, "place categories", async () =>
+    await listPlaceCategories(client));
+  return successResult(VERB_PLACES_CATEGORY_LIST, siteId, { categories });
+}

package/src/verbs/status.js

@@ -132,10 +132,7 @@ export async function status(invocation) {
     const selection = presentationOnly
       ? { ...reviewed, stagedPageIds: [], includeNavigation: false }
       : reviewed;
-    const readiness = await getPublishingReadiness(client, siteId, {
-      ...selection,
-      stagedPageIds: selection.stagedPageIds.length > 100 ? undefined : selection.stagedPageIds,
-    });
+    const readiness = await getPublishingReadiness(client, siteId, selection);
     onProgress("Reading the deployment log.");
     const {
       deployments,