@taprootio/site-authoring 0.2.0 → 0.4.0

package/src/reference-help.js

@@ -1,4 +1,26 @@
+import { readFileSync } from "node:fs";
+
+import { TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { CLI_BINARY_NAME } from "./constants.js";
+import {
+  FIXTURE_CONTRACT_VERSION,
+  FIXTURE_DELIVERY_ORIGIN_DOMAIN,
+  FIXTURE_MANIFEST_FILE_NAME,
+  FIXTURE_MAXIMUM_DELIVERY_ORIGINS,
+  FIXTURE_METADATA_FIELDS,
+  FIXTURE_OPTIONAL_ROOT_FIELDS,
+  FIXTURE_REQUIRED_ROOT_FIELDS,
+  SHIPPED_FIXTURE_NAME,
+  shippedFixtureDirectory,
+} from "./fixture-contract.js";
+import {
+  DEFAULT_REDIRECT_STATUS,
+  GONE_STATUS,
+  REDIRECT_LIMITS,
+  REDIRECT_STATUSES,
+  REDIRECTS_FILE_NAME,
+} from "./redirects-contract.js";
+import { SETTINGS_GROUPS } from "./settings-catalog.js";
 import {
   canonicalizeComponentData,
   COMPONENT_TYPES,
@@ -20,14 +42,21 @@ import {
 } from "./presentation-reference.js";
 import {
   INTERNAL_PAGE_BASELINE_DIRECTORY,
+  MANIFEST_VERSION,
+  NAVIGATION_FILE_NAME,
   PAGE_READ_ONLY_REASON_SYSTEM_404,
+  PAGE_SOURCE_EXTENSIONS,
+  PAGE_WORKSPACE_MODE_EDITABLE,
   PAGE_WORKSPACE_MODE_READ_ONLY,
+  pageSourceFormat,
+  PAGES_DIRECTORY,
+  SETTINGS_DIRECTORY,
   SYSTEM_PAGE_NOT_FOUND_PATH,
 } from "./workspace.js";
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 15;
+export const REFERENCE_VERSION = 17;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
 export const REFERENCE_TOPICS = Object.freeze([
   Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types." }),
@@ -47,6 +76,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     summary: "Describe one component schema and show a valid example.",
   }),
   Object.freeze({ name: "nav", usage: `${CLI_BINARY_NAME} help nav`, summary: "Describe nav.json item shapes." }),
+  Object.freeze({
+    name: "redirects",
+    usage: `${CLI_BINARY_NAME} help redirects`,
+    summary: "Author redirects.json: entry shape, normalization, and the refusals.",
+  }),
   Object.freeze({
     name: "media",
     usage: `${CLI_BINARY_NAME} help media`,
@@ -72,6 +106,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help footer`,
     summary: "Author and concurrency-safely push the complete footer document.",
   }),
+  Object.freeze({
+    name: "fixture",
+    usage: `${CLI_BINARY_NAME} help fixture`,
+    summary: "State the offline fixture manifest contract and locate the shipped example.",
+  }),
 ]);
 
 const WORKFLOW_REFERENCES = Object.freeze({
@@ -84,6 +123,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "kind is NAV_ITEM_KIND_PAGE, NAV_ITEM_KIND_EXTERNAL_URL, or NAV_ITEM_KIND_GROUP_HEADER.",
       "PAGE uses resourceId from .taproot-site-manifest.json, never pageId or path.",
       "EXTERNAL_URL uses externalUrl; GROUP_HEADER has no target; every kind may carry children.",
+      "externalUrl is an absolute credential-free http/https URL, or a mailto:/tel: contact URL such as "
+      + "tel:+15555550123, published exactly as authored.",
     ]),
     example: Object.freeze({
       siteId: "<site-uuid>",
@@ -96,6 +137,81 @@ const WORKFLOW_REFERENCES = Object.freeze({
       })]),
     }),
   }),
+  redirects: Object.freeze({
+    title: "Redirect map workspace contract",
+    summary:
+      `${REDIRECTS_FILE_NAME} is the site's whole redirect map. 'redirects push' replaces it, fenced by the `
+      + "revision 'redirects pull' recorded, so a stale write is refused rather than deleting an entry a page "
+      + "rename added.",
+    usage: `${CLI_BINARY_NAME} redirects pull | ${CLI_BINARY_NAME} redirects push`,
+    details: Object.freeze([
+      `${REDIRECTS_FILE_NAME} is { siteId, revision, entries }, not a bare array. 'redirects pull' writes it and `
+      + "records the revision in .taproot-site-manifest.json; 'pull' writes it too.",
+      "An entry is { path, kind, target, status }. kind is 'redirect' (the default) or 'gone'; a gone entry "
+      + `carries no target and serves ${GONE_STATUS}.`,
+      `status defaults to ${DEFAULT_REDIRECT_STATUS} and accepts ${REDIRECT_STATUSES.join(", ")}. A migration `
+      + `wants ${DEFAULT_REDIRECT_STATUS}: it is what tells search engines the old URL has moved for good.`,
+      "path is normalized exactly as the published-site edge normalizes a request: a leading slash is added, "
+      + "trailing slashes are stripped, and nothing else changes — so a legacy source keeps its suffix and "
+      + "'/faqs.html' is a real, representable path. It carries no query string, fragment, or host.",
+      "Write a path — and the path part of a site-relative target — in the percent-encoded spelling a browser "
+      + "sends ('/caf%C3%A9', '/old%20page'), never the raw one: the edge keys on the encoded pathname, so a raw "
+      + "space or non-ASCII character is stored under a key no request matches, and a raw target beside an "
+      + "encoded source is the self-loop loop detection cannot see.",
+      "target is a site-relative path such as '/classes', or an absolute credential-free http(s) URL. A "
+      + "site-relative target keeps its trailing slash: it is a Location a browser follows, not a route key.",
+      "A path, or the path part of a site-relative target, is refused when any segment is '.' or '..', when two "
+      + "slashes run together, or when a dot or slash is percent-encoded ('%2e', '%2f'); a target's query string "
+      + "may carry any of those. The edge and the generator resolve "
+      + "those away, so '/x/../visit' would be checked as itself and served as '/visit' — past the occupancy, "
+      + "chain, and loop rules that were asked about a different path. Write the resolved path instead.",
+      "origin is reported by the site and ignored on push: 'authored' is what you declared, 'path_history' is "
+      + "what a page or tag rename recorded. Pull the map, edit it, push the whole thing back — an entry you "
+      + "did not change keeps its origin.",
+      "Refused, offline and again at the site, each naming the entry index: a chain (a target that is itself a "
+      + "source in the same map); a loop (an entry targeting itself); a duplicate path; a gone entry carrying a "
+      + "target; and a status outside the allowed set. A chain or loop is judged on the target's path alone, so "
+      + "'/b?x=1' and '/b' are the same destination to it.",
+      "Refused by the site, which alone knows what it serves: a path a live page, Docs resource, or generated "
+      + "resource already occupies. '/' is such a path while the site's home page is served there — and a "
+      + "usable source once the home page has moved, which is the entry a home-page rename records.",
+      `Bounded: at most ${REDIRECT_LIMITS.entries} entries, ${REDIRECT_LIMITS.pathBytes} bytes of path, and `
+      + `${REDIRECT_LIMITS.targetBytes} bytes of target, matching the edge's own key and value limits.`,
+      `The ${REDIRECT_LIMITS.pathBytes}-byte path bound governs what you declare, not what the site already `
+      + "holds. A page may sit at a longer path, and renaming it records a path_history entry there that "
+      + "'redirects pull' returns; such an entry passes 'validate' and pushes back unchanged. The site is the "
+      + "authority on that — it alone knows whether a push introduces the path or carries it back — so a push "
+      + "that lengthens or changes one is still refused there.",
+      `The ${REDIRECT_LIMITS.entries}-entry bound is scoped the same way: a pulled map already holding more `
+      + "than that validates and pushes back unchanged, and only a document holding more entries than both the "
+      + "bound and the count the last pull recorded is refused — so accumulated path history never has to be "
+      + "deleted to make a push land.",
+      "A push whose recorded revision predates a page rename is refused as redirects.concurrent_modification. "
+      + `Run 'redirects pull', reconcile ${REDIRECTS_FILE_NAME}, and retry; nothing was written.`,
+      "Converting an engagement's CSV into this file is the agent's job. The CLI's contract is JSON, on "
+      + "purpose: a real migration list needs judgement about which old URLs still deserve a destination and "
+      + "which are simply gone.",
+      "Entries take effect on the next deploy, staging first. They are written to the edge's key-value store "
+      + "when the deploy syncs routing, and that store is eventually consistent, so a spot-check run "
+      + "immediately afterwards can briefly still see the previous map. Re-check before concluding an entry "
+      + "did not land.",
+    ]),
+    example: Object.freeze({
+      siteId: "<site-uuid>",
+      revision: "<revision-recorded-by-redirects-pull>",
+      entries: Object.freeze([
+        Object.freeze({ path: "/faqs.html", kind: "redirect", target: "/faq", status: 301 }),
+        Object.freeze({ path: "/old-blog", kind: "redirect", target: "/journal", status: 301 }),
+        Object.freeze({
+          path: "/book",
+          kind: "redirect",
+          target: "https://booking.example.test/riverbend",
+          status: 302,
+        }),
+        Object.freeze({ path: "/summer-2019-retreat.html", kind: "gone" }),
+      ]),
+    }),
+  }),
   media: Object.freeze({
     title: "Media upload contract",
     summary: "Upload workspace-root-relative raster files and receive component-ready media objects.",
@@ -125,6 +241,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
     details: Object.freeze([
       "A page path resolves through .taproot-site-manifest.json; a canonical page UUID works directly.",
       "The homepage's manifest path is empty; address it as '/', which resolves to that empty root path.",
+      "Preview before approving: approve consumes the draft, so an approved page has no draft left to render and answers preview.no_draft. Review it on staging after a deploy instead.",
       "Creation prints pageId, snapshotId, and expiresAt before the bounded render wait starts.",
       "The default stored-preview cap is 10 per authoring key and site; operators can tune it.",
       "Success returns READY with url, snapshotId, expiresAt, storedPreviewCap, storedPreviewCount, and evictedPreviews.",
@@ -134,10 +251,100 @@ const WORKFLOW_REFERENCES = Object.freeze({
     ]),
     example: Object.freeze({ command: `${CLI_BINARY_NAME} preview page classes` }),
   }),
+  fixture: Object.freeze({
+    title: "Offline fixture manifest contract",
+    summary:
+      `${FIXTURE_MANIFEST_FILE_NAME} binds a directory laid out like a pulled workspace to deterministic identities, `
+      + "so validate can prove it with no credential, no network, and no write.",
+    usage: `${CLI_BINARY_NAME} validate <fixture-directory>`,
+    details: Object.freeze([
+      `Required root fields: ${FIXTURE_REQUIRED_ROOT_FIELDS.join(", ")}.`,
+      `Accepted and not read: ${FIXTURE_OPTIONAL_ROOT_FIELDS.join(", ")} — pull writes them, and neither the snapshot `
+      + "time nor a recorded deployment can be checked offline. Any other root field is refused.",
+      `manifestVersion must be ${MANIFEST_VERSION}; fixture.contractVersion must be ${FIXTURE_CONTRACT_VERSION}.`,
+      "siteId, every pageId and resourceId, every settings entityId, and every fixture.imageIds entry is a canonical "
+      + "lowercase UUID. They are deterministic fixture identities, not identities from a live site.",
+      `Each pages[] entry binds one editable free-form source: pageId, resourceId, path, title, templateType `
+      + `${TEMPLATE_TYPE_FREE_FORM}, file, sourceFormat, and workspaceMode ${PAGE_WORKSPACE_MODE_EDITABLE}. `
+      + "status, hasDraft, isGenerated, and description are recorded by pull and not read: the page key set "
+      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string.",
+      `file lives under '${PAGES_DIRECTORY}/' and ends in ${PAGE_SOURCE_EXTENSIONS.join(" or ")}; sourceFormat must be `
+      + `the format that extension implies (${
+        PAGE_SOURCE_EXTENSIONS.map((extension) => `${extension} is '${pageSourceFormat(`page${extension}`)}'`).join(
+          ", ",
+        )
+      }).`,
+      "No two page entries share a pageId, resourceId, file, or path; every declared source must exist; every "
+      + `source under '${PAGES_DIRECTORY}/' must be declared; and each entry's path must equal the path its source `
+      + "declares — a Markdown source's front-matter 'path:' wins, and the entry's value applies only when the "
+      + "front matter omits it.",
+      "pages must declare at least one entry, pagesTruncated must be false, and settingsSkipped must be empty: a "
+      + "partial snapshot is not a fixture.",
+      `navigation binds { file: "${NAVIGATION_FILE_NAME}", items }, and items must equal the tree's own item count.`,
+      `redirects binds { file: "${REDIRECTS_FILE_NAME}", revision, entries }, and entries must equal the map's own `
+      + "entry count. The revision is a deterministic 64-character lowercase hex placeholder, like every other "
+      + "identity in a fixture: it proves the shape, never a live read. No redirect source may be a page in the "
+      + `same fixture. See '${CLI_BINARY_NAME} help redirects' for the entry contract.`,
+      `settings binds all ${SETTINGS_GROUPS.length} authorable groups, each with settingsType, file, and entityId: ${
+        SETTINGS_GROUPS.map((group) => `${group.settingsType} to '${SETTINGS_DIRECTORY}/${group.file}'`).join("; ")
+      }.`,
+      `The fixture block carries ${FIXTURE_METADATA_FIELDS.join(", ")}. Every image a page references by imageId must `
+      + "be listed in fixture.imageIds, and every absolute delivery URL a page uses must sit on a declared origin.",
+      `Each deliveryOrigins entry is an origin-only HTTPS URL (no path, query, fragment, or credentials) on `
+      + `${FIXTURE_DELIVERY_ORIGIN_DOMAIN} or a subdomain of it, at most ${FIXTURE_MAXIMUM_DELIVERY_ORIGINS} of them, `
+      + "with no duplicates. Fixtures are copied and shipped, so a real delivery host in one would be a live "
+      + "reference in every copy.",
+      "validate reads the fixture and writes nothing to it. Copy the directory somewhere writable before editing it.",
+    ]),
+  }),
 });
 
+// The box, rather than the value, is the cache: an absent fixture memoizes
+// `undefined` instead of being re-read on every call.
+let shippedFixtureManifestCache;
+
+/**
+ * The shipped fixture's own manifest, read on demand and memoized, or
+ * `undefined` when this copy of the package has no readable `examples/`.
+ *
+ * The read is lazy because `examples/` ships but is not load-bearing. This
+ * module sits on the path of every verb (`bin/taproot-site.js` imports
+ * `src/cli.js`, which imports this) and of every library consumer through
+ * `src/index.js`, while `examples/` is exactly what a `node_modules` pruner or
+ * an image-slimming step drops. A static import would turn such a pruned
+ * install into an `ERR_MODULE_NOT_FOUND` at module load for `login`, `pull`,
+ * `push`, and every other verb; reading here degrades `help fixture` alone.
+ */
+function shippedFixtureManifest() {
+  shippedFixtureManifestCache ??= { value: readShippedFixtureManifest() };
+  return shippedFixtureManifestCache.value;
+}
+
+function readShippedFixtureManifest() {
+  try {
+    return JSON.parse(readFileSync(
+      new URL(`../examples/${SHIPPED_FIXTURE_NAME}/${FIXTURE_MANIFEST_FILE_NAME}`, import.meta.url),
+      "utf8",
+    ));
+  } catch {
+    // Missing, unreadable, or not JSON. The contract the topic states is
+    // derived from constants and stays complete without an example, so
+    // `help fixture` answers rather than fails.
+    return undefined;
+  }
+}
+
 export function getWorkflowReference(topic) {
-  return WORKFLOW_REFERENCES[topic];
+  const reference = WORKFLOW_REFERENCES[topic];
+  if (topic !== "fixture") return reference;
+  const example = shippedFixtureManifest();
+  // The directory is resolved from this package rather than from the caller's
+  // directory, so the path is right for a global install as well as a
+  // checkout. Both it and the example are reported only when the fixture is
+  // actually present: a pruned install has nothing to locate or to validate.
+  return example === undefined
+    ? reference
+    : Object.freeze({ ...reference, fixtureDirectory: shippedFixtureDirectory(), example });
 }
 
 function componentSummary(type) {
@@ -324,6 +531,8 @@ function decorationReference() {
 }
 
 const INLINE_FACTS_DEFINITION = FREE_FORM_SECTION_REGISTRY.inlineFacts;
+// The third fact carries no label on purpose: a phone number names itself, and
+// the row is allowed to mix labelled and standalone facts.
 const INLINE_FACT_ITEMS_EXAMPLE = Object.freeze([
   Object.freeze({ value: "4.9 ★", label: "Community rating" }),
   Object.freeze({
@@ -331,7 +540,7 @@ const INLINE_FACT_ITEMS_EXAMPLE = Object.freeze([
     label: "Elm Harbor",
     url: "https://maps.example.test/?q=100%20Riverside%20Way%20Elm%20Harbor",
   }),
-  Object.freeze({ value: "(555) 013-7788", label: "Call the studio", url: "tel:+15550137788" }),
+  Object.freeze({ value: "(555) 013-7788", url: "tel:+15550137788" }),
   Object.freeze({ value: "Open today until 8:30 PM", label: "Today's hours", url: "/classes" }),
 ]);
 
@@ -353,6 +562,12 @@ function inlineFactsReference() {
       }),
     }),
     placement: Object.freeze({ ...INLINE_FACTS_DEFINITION.placement }),
+    valuePolicy:
+      `Required non-whitespace plain text; maximum ${items.fields.value.maxScalars} Unicode scalar values.`,
+    labelPolicy:
+      `Optional non-whitespace plain text; maximum ${items.fields.label.maxScalars} Unicode scalar values. `
+      + "Omit it when the value already names itself, such as a rating, an address, or a phone number; a row may "
+      + "mix labelled and standalone facts. An empty string is rejected, so omitting a label stays explicit.",
     urlPolicy:
       "Optional safe HTTP(S), mailto, tel, non-protocol-relative root, fragment, query, or relative URL. Empty/whitespace-only values, other schemes, backslashes, and ASCII controls are rejected; tel: remains a native link.",
     markdown: Object.freeze({
@@ -566,9 +781,11 @@ const FREE_FORM_REFERENCE = Object.freeze({
       pull:
         "pull keeps a tracked source that is still on disk and never writes a second editable file for the same page.",
       internalState:
-        `${INTERNAL_PAGE_BASELINE_DIRECTORY}/<pageId>.pm.json holds the site's document for a page tracked as Markdown. `
-        + "It is internal state: it is never discovered as a page source and is never pushed, and any pull rewrites "
-        + "it, so it is safe to ignore in version control.",
+        `${INTERNAL_PAGE_BASELINE_DIRECTORY}/<pageId>.pm.json holds the site's document for a page tracked as Markdown, `
+        + "and <pageId>.revision.json beside it records the revision a refused pull already showed you — which is what "
+        + "lets the refusal's own recovery push proceed. Both are internal state: never discovered as a page source "
+        + "and never pushed, and a pull that reconciles the page rewrites or removes them, so they are safe to ignore "
+        + "in version control.",
       formatChange:
         "Remove the tracked source, then author the other format beside it. Two editable sources for one path is a "
         + "refusal, not a guess.",
@@ -582,6 +799,24 @@ const FREE_FORM_REFERENCE = Object.freeze({
         + "refuses before changing anything under pages/ and preserves the site's version as internal state. A "
         + "locally edited .pm.json is kept rather than overwritten, and only collides when the site changed too.",
       conflictError: "pages.pull_conflict",
+      conflictDetail:
+        "A reported conflict names the JSON paths at which the site's document differs from the copy this workspace "
+        + "last reconciled with, in error.differences, which carries three states. Absent: the two documents were "
+        + "never compared, because this workspace kept no copy of the site's previous version. Empty: they were "
+        + "compared and the body is identical, so the change was to the page's title, path, or description. "
+        + "Non-empty: the JSON paths at which the body differs.",
+      pushConflict:
+        "pages push fails closed on a concurrent remote edit: the site reports each page's stored-state revision, the "
+        + "workspace records the revision of what it last wrote or pulled, and a push whose target now carries a "
+        + "different revision is refused before any page is sent. The refusal carries both revisions in "
+        + "error.alternatives, recorded first and live second. The guard is armed once both are known — a page this "
+        + "workspace has never reconciled with, or a Taproot that predates the revision contract, leaves it unarmed "
+        + "rather than refusing every push. A pull that refuses records the revision it showed you, so the pull "
+        + "conflict's own recovery push still goes through; a page that moved again since is refused again.",
+      pushConflictError: "pages.push_conflict",
+      revisionSource:
+        "baseline.revision in the manifest, from bodyRevision on the page read, the page listing, and the create and "
+        + "update responses. It is opaque: compare it, never derive or parse it.",
       conflictRecovery:
         "Either push the local source to make the site match it, or delete the local source and pull again to adopt "
         + "the site's document as that page's source.",
@@ -869,7 +1104,13 @@ export function formatReferenceResult(result) {
         sourceRule.renamedSource
       } (${sourceRule.renamedSourceError})\n  conflicts             ${
         sourceRule.conflict
-      } (${sourceRule.conflictError})\n  recovery              ${
+      } (${sourceRule.conflictError})\n  conflict detail       ${
+        sourceRule.conflictDetail
+      }\n  push conflicts        ${
+        sourceRule.pushConflict
+      } (${sourceRule.pushConflictError})\n  revision              ${
+        sourceRule.revisionSource
+      }\n  recovery              ${
         sourceRule.conflictRecovery
       }\n  push selection        ${sourceRule.pushSelection}\n\nSystem page projections:\n${
         page.workspace.systemPages.map((systemPage) =>
@@ -897,7 +1138,7 @@ export function formatReferenceResult(result) {
         page.sections.placementMatrix.map(formatPlacement).join("\n")
       }\n\nSemantic tables:\n  placement             document root or directly inside a top-level section; wide/full-well measure\n  rows                  exactly ${page.tables.structure.headerRows} header row, then ${page.tables.limits.dataRows.min} through ${page.tables.limits.dataRows.max} data rows\n  columns               ${page.tables.limits.columns.min} through ${page.tables.limits.columns.max}; delimiter and every row must match the header width\n  caption               optional non-empty plain text; maximum ${page.tables.limits.captionScalars.max} Unicode scalar values; syntax ${page.tables.markdown.captionSyntax}\n  caption guidance      ${page.tables.captionGuidance}\n  cells                 exactly ${page.tables.structure.paragraphChildrenPerCell} paragraph; headers need non-whitespace text; data cells may be empty; maximum ${page.tables.limits.cellTextScalars.max} text scalars\n  inline                ${page.tables.structure.inlineNodes.join(", ")}; marks ${page.tables.structure.marks.join(", ")}\n  pipes                 outer pipes ${page.tables.markdown.outerPipes}; write a literal pipe as ${page.tables.markdown.literalPipeEscape}\n  spans                 unsupported: ${page.tables.structure.unsupportedSpanAttrs.join(", ")}\n  alignment             ${page.tables.markdown.alignment}; delimiter cells contain hyphens only\n  termination           a blank line ends the table before another block\n\nRate table example:\n${page.tables.examples.rateTable}\n\nComparison table example:\n${page.tables.examples.comparisonTable}\n\nRejected alignment example (${CONTENT_ERROR_CODES.markdownTableAlignment}):\n${page.tables.examples.rejectedAlignment}\nRemove the ':' characters from the delimiter row.\n\nDirect ProseMirror table example:\n${JSON.stringify(page.tables.examples.proseMirror, null, 2)}\n\nTable error corrections:\n${
         page.tables.corrections.map((entry) => `  ${entry.code.padEnd(34)} ${entry.correction}`).join("\n")
-      }\n\nInline facts:\n  placement             document root or directly inside a top-level section; ${page.inlineFacts.placement.measure} measure\n  items                 ${page.inlineFacts.attrs.items.minItems} through ${page.inlineFacts.attrs.items.maxItems}; closed objects in value, label, url order\n  value and label       required non-whitespace plain text; maximum ${page.inlineFacts.attrs.items.fields[0].maxScalars} Unicode scalar values each\n  url                   ${page.inlineFacts.urlPolicy}\n  Markdown              fenced ${page.inlineFacts.markdown.fence} block whose body is a JSON array\n\nInline-facts Markdown example:\n${page.inlineFacts.markdown.example}\n\nDirect ProseMirror inlineFacts example:\n${JSON.stringify(page.inlineFacts.examples.proseMirror, null, 2)}\n\nRaw HTML: ${page.document.rawHtml.default} by default. For a tracked ${page.document.rawHtml.trackedProseMirror.format} document only: ${page.document.rawHtml.trackedProseMirror.behavior} Opt in with ${page.document.rawHtml.trackedProseMirror.optIn}. For ${page.document.rawHtml.markdown.format}, ${page.document.rawHtml.markdown.behavior} ${page.document.rawHtml.warning}\n\nComponents:\n${
+      }\n\nInline facts:\n  placement             document root or directly inside a top-level section; ${page.inlineFacts.placement.measure} measure\n  items                 ${page.inlineFacts.attrs.items.minItems} through ${page.inlineFacts.attrs.items.maxItems}; closed objects in ${page.inlineFacts.attrs.items.itemFieldOrder.join(", ")} order\n  value                 ${page.inlineFacts.valuePolicy}\n  label                 ${page.inlineFacts.labelPolicy}\n  url                   ${page.inlineFacts.urlPolicy}\n  Markdown              fenced ${page.inlineFacts.markdown.fence} block whose body is a JSON array\n\nInline-facts Markdown example:\n${page.inlineFacts.markdown.example}\n\nDirect ProseMirror inlineFacts example:\n${JSON.stringify(page.inlineFacts.examples.proseMirror, null, 2)}\n\nRaw HTML: ${page.document.rawHtml.default} by default. For a tracked ${page.document.rawHtml.trackedProseMirror.format} document only: ${page.document.rawHtml.trackedProseMirror.behavior} Opt in with ${page.document.rawHtml.trackedProseMirror.optIn}. For ${page.document.rawHtml.markdown.format}, ${page.document.rawHtml.markdown.behavior} ${page.document.rawHtml.warning}\n\nComponents:\n${
         page.components.map((component) => `  ${component.type.padEnd(16)} ${component.summary}`).join("\n")
       }\n\nWorkflow:\n${
         page.workflow.map((step) => `  ${step.command}: ${step.result}`).join("\n")
@@ -915,9 +1156,20 @@ export function formatReferenceResult(result) {
     }
     case "workflow": {
       const reference = result.reference;
-      return `${reference.title}\n${reference.summary}\n\nUsage: ${reference.usage}\n\n${
+      // Only the fixture reference carries a shipped directory; every other
+      // workflow topic renders exactly as it did.
+      const shipped = reference.fixtureDirectory === undefined
+        ? ""
+        : `\nShipped example: ${reference.fixtureDirectory}\nValidate it: ${CLI_BINARY_NAME} validate "${reference.fixtureDirectory}"\n`;
+      // Every other topic's example is a literal in this module and is always
+      // present; the fixture topic's is a shipped file, so it is omitted the
+      // same way the shipped-directory lines are when the file is not there.
+      const example = reference.example === undefined
+        ? ""
+        : `\n\nExample:\n${JSON.stringify(reference.example, null, 2)}`;
+      return `${reference.title}\n${reference.summary}\n\nUsage: ${reference.usage}\n${shipped}\n${
         reference.details.map((detail) => `  - ${detail}`).join("\n")
-      }\n\nExample:\n${JSON.stringify(reference.example, null, 2)}\n`;
+      }${example}\n`;
     }
     case "presentation":
       return formatPresentationReference(result.reference);

package/src/session.js

@@ -3,12 +3,17 @@ import {
   CLI_NAME,
   CLI_VERSION,
   DEFAULT_API_BASE_URL,
+  EXTERNAL_WRITES_SETTING_KEY,
+  EXTERNAL_WRITES_SETTING_LOCATION,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  REFUSAL_PLATFORM_PAUSED,
   RESULT_SCHEMA_VERSION,
+  ROLLOUT_REFUSAL_FIELD,
   VERB_LOGIN,
   VERB_USE,
 } from "./constants.js";
 import { loadSiteConfig } from "./config.js";
+import { cliOutdatedError, compareCliVersions, isBehindLatest } from "./cli-release.js";
 import {
   credentialApiOrigin,
   readCredentialStore,
@@ -16,7 +21,7 @@ import {
   updateCredentialMetadata,
 } from "./credentials.js";
 import { SiteAuthoringError } from "./errors.js";
-import { exchangeSiteAuthoringToken } from "./api.js";
+import { exchangeSiteAuthoringToken, withRefusalGuidance } from "./api.js";
 import { SiteApiClient } from "./transport.js";
 import { readStoredApiBaseUrl } from "./settings.js";
 
@@ -38,6 +43,26 @@ import { readStoredApiBaseUrl } from "./settings.js";
 /** The optional seams a test (or a future caller) may inject. */
 const CLIENT_OPTION_KEYS = ["fetch", "signal", "sleep", "now", "timeoutSignal"];
 
+/**
+ * What a session knows about the platform's authoring rollout switch when
+ * nothing told it (TR00692).
+ *
+ * Three states, not two, and the third is the honest one: `TAPROOT_SITE_KEY`
+ * skips the exchange entirely and no other read on the contract exposes the
+ * switch, so those runs know nothing about it. Collapsing unknown into "paused"
+ * would warn on every write against a healthy platform; collapsing it into
+ * "enabled" would claim a fact nobody supplied.
+ */
+const UNKNOWN_PLATFORM = Object.freeze({ externalWritesEnabled: undefined });
+
+/**
+ * What a session knows about the latest published release when nothing told it
+ * (TR00703) — the same three-state shape, and unknown for the same reasons: a
+ * `TAPROOT_SITE_KEY` run never exchanges, and a Taproot that predates the field
+ * answers with nothing.
+ */
+const UNKNOWN_CLI_RELEASE = Object.freeze({ latestVersion: undefined });
+
 function progressSink(invocation) {
   return typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
 }
@@ -166,7 +191,19 @@ export async function openSession(invocation = {}) {
     if (!config.siteId) throw siteMissingError();
     const client = invocation.client
       ?? new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, environmentToken));
-    return { config, client, siteId: config.siteId, now, onProgress };
+    // No exchange happens on this path, and nothing else on the contract reads
+    // the platform switch — so its state is genuinely unknown here rather than
+    // assumed. Reporting it as enabled would be a guess, and reporting it as
+    // paused would warn on every write against a healthy platform.
+    return {
+      config,
+      client,
+      siteId: config.siteId,
+      platform: UNKNOWN_PLATFORM,
+      release: UNKNOWN_CLI_RELEASE,
+      now,
+      onProgress,
+    };
   }
 
   let config;
@@ -192,14 +229,33 @@ export async function openSession(invocation = {}) {
   // A caller may supply the site client directly (tests, and the verbs that
   // already hold one); otherwise the sign-in is exchanged for one.
   if (invocation.client) {
-    return { config, client: invocation.client, siteId: config.siteId, now, onProgress };
+    return {
+      config,
+      client: invocation.client,
+      siteId: config.siteId,
+      platform: UNKNOWN_PLATFORM,
+      release: UNKNOWN_CLI_RELEASE,
+      now,
+      onProgress,
+    };
   }
 
   const accountClient = new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, signIn.key));
-  const exchanged = await exchangeSiteAuthoringToken(accountClient, {
-    siteId: config.siteId,
-    capabilities: invocation.capabilities ?? [],
-  });
+  // Announced here, not left to the generic failure line. The exchange is the
+  // first request every site verb makes and it sits outside each verb's own
+  // `withRefusalGuidance`, so a refusal raised by it used to reach the operator
+  // as a field name and nothing else. That matters most for `cli_outdated`,
+  // whose whole remedy is a command the operator has to be handed (TR00703),
+  // but it is true of every classified refusal the exchange can raise.
+  const exchanged = await withRefusalGuidance(
+    onProgress,
+    "sign-in token exchange",
+    async () =>
+      await exchangeSiteAuthoringToken(accountClient, {
+        siteId: config.siteId,
+        capabilities: invocation.capabilities ?? [],
+      }),
+  );
   // Two non-secret facts the store should now carry: the sign-in's slid
   // deadline, and what this exchange actually produced — the latter is the only
   // thing that lets `whoami` answer offline with the real grant rather than the
@@ -224,6 +280,20 @@ export async function openSession(invocation = {}) {
           siteId: exchanged.siteId,
           capabilities: exchanged.capabilities,
           expiresAt: exchanged.expiresAt,
+          // When this exchange happened, so `whoami` can date what it reports
+          // rather than presenting a snapshot as current fact. Recorded for
+          // every exchange, not only the ones that saw a platform state, so the
+          // field has one meaning.
+          at: new Date(now()).toISOString(),
+          ...(exchanged.externalWritesEnabled === undefined
+            ? {}
+            : { externalWritesEnabled: exchanged.externalWritesEnabled }),
+          // The latest published release Taproot named (TR00703). Recorded for
+          // the offline verbs, which have no request to be refused and would
+          // otherwise keep validating against a contract that has moved.
+          ...(exchanged.latestCliVersion === undefined
+            ? {}
+            : { latestCliVersion: exchanged.latestCliVersion }),
         },
       },
     );
@@ -242,11 +312,95 @@ export async function openSession(invocation = {}) {
       expiresAt: exchanged.expiresAt,
       capabilities: exchanged.capabilities,
     },
+    platform: Object.freeze({ externalWritesEnabled: exchanged.externalWritesEnabled }),
+    release: Object.freeze({ latestVersion: exchanged.latestCliVersion }),
     now,
     onProgress,
   };
 }
 
+/**
+ * Refuses an offline verb when the last exchange said a newer CLI exists
+ * (TR00703).
+ *
+ * **Only for the verbs that make no request.** `help`, `validate`, and `whoami`
+ * are the whole set: every other verb reaches the server, and the server's own
+ * refusal is both authoritative and better informed than this recording. Gating
+ * them here would only duplicate an answer — and gating `login`, `logout`, or
+ * `env` would break the commands an operator needs *while* they are outdated.
+ *
+ * **Best effort, and silent on every uncertainty.** Nothing recorded proceeds,
+ * so a clean machine can still validate a fixture. A store this process cannot
+ * read or parse proceeds too: an unreadable file is not evidence that this CLI
+ * is behind, and turning a corrupt store into a refusal to run `help` would
+ * take away the command that explains how to fix it. Only a recorded version
+ * this side can parse and compare stops anything.
+ *
+ * The store holds one record per API origin, and the highest recorded version
+ * across all of them is what counts. npm publishes one package: whichever
+ * Taproot last answered, it was naming the same registry, so the newest answer
+ * is the current fact rather than a per-origin opinion. Taking the maximum also
+ * keeps a stale development Taproot from masking production's answer.
+ */
+export async function assertCliCurrent(environment = process.env) {
+  let store;
+  try {
+    store = await readCredentialStore(environment);
+  } catch {
+    // Deliberately swallowed; see above.
+    return undefined;
+  }
+  let latest;
+  for (const credential of store.credentials) {
+    const recorded = credential.lastExchange?.latestCliVersion;
+    if (recorded === undefined) continue;
+    if (latest === undefined || (compareCliVersions(recorded, latest) ?? 0) > 0) latest = recorded;
+  }
+  if (latest === undefined || !isBehindLatest(latest)) return undefined;
+  throw cliOutdatedError(latest);
+}
+
+/**
+ * The one pre-write warning: the platform has external site authoring paused,
+ * so this verb's write is going to be refused (TR00692).
+ *
+ * **Advisory, never a gate.** The value is a snapshot the token exchange took
+ * before this run did any work, and the authority is still the transactional
+ * freeze inside the write itself — so a paused platform warns and then proceeds
+ * exactly as before, and the refusal that follows keeps its `platform_paused`
+ * classification for automation to branch on. An operator who flipped the
+ * switch back on between the exchange and the write gets their write.
+ *
+ * Silent in the two cases that are not "paused": enabled, and unknown. Unknown
+ * is the `TAPROOT_SITE_KEY` path, which never exchanges and therefore was never
+ * told — see {@link UNKNOWN_PLATFORM}.
+ *
+ * **Contract.** Call it once, immediately after `openSession` and before any
+ * validation, reading, or wire work, passing the whole session object and the
+ * verb's own name (its `VERB_*` constant). It prints at most one progress line
+ * and returns whether it printed one; it never throws, never reads, and never
+ * changes what the verb does next.
+ *
+ * @param {{ platform?: { externalWritesEnabled?: boolean }, onProgress?: (message: string) => void }} session
+ *   The session `openSession` returned.
+ * @param {string} [verb] The verb's display name, for the warning's first clause.
+ * @returns {boolean} Whether a warning was printed.
+ */
+export function warnIfExternalWritesPaused(session, verb = "This write") {
+  // The guard settles both questions: only a session object can carry `false`
+  // here, so nothing below needs to defend against a missing one.
+  if (session?.platform?.externalWritesEnabled !== false) return false;
+  const onProgress = progressSink(session);
+  onProgress(
+    `WARNING: Taproot has external site authoring paused platform-wide, so '${verb}' is expected to be refused `
+      + `at the write (refusal=${REFUSAL_PLATFORM_PAUSED}, field=${ROLLOUT_REFUSAL_FIELD}). The credential and the `
+      + `request are both fine. A Taproot administrator re-enables it with the platform setting `
+      + `'${EXTERNAL_WRITES_SETTING_KEY}' (${EXTERNAL_WRITES_SETTING_LOCATION}). Continuing anyway: this is what `
+      + "Taproot reported when this run's credential was exchanged, and the write itself is the authority.",
+  );
+  return true;
+}
+
 /**
  * The credential-free half of the session seam, for the verbs that manage the
  * credential rather than use it.