@rathnasgala2/schemas 3.23.1 → 3.25.0

package/openapi/openapi.yaml

@@ -4123,7 +4123,7 @@ components:
           then:
             required:
               - publishing
-      description: Everything a Home screen needs in one read. `url` is the live site address, `null` when nothing has been published. `lastPublished` is absent when `state` is `NEVER_PUBLISHED`. `publishing` is present exactly while `state` is `PUBLISHING`. `schedule` (SCHEMA-3.3.0, optional) is present while a scheduled publish is pending; a pending schedule never makes `state` `PUBLISHING` -- the site reads as it would without it until the schedule starts. `nextRelease` (SCHEMA-3.19.0, optional and nullable) is the scheduled draft that the staggered release will publish next, the one with the earliest `publishAfter` date; `null` or absent when there is none.
+      description: Everything a Home screen needs in one read. `url` is the live site address, `null` when nothing has been published. `lastPublished` is absent when `state` is `NEVER_PUBLISHED`. `publishing` is present exactly while `state` is `PUBLISHING`. `schedule` (SCHEMA-3.3.0, optional) is present while a scheduled publish is pending; a pending schedule never makes `state` `PUBLISHING` -- the site reads as it would without it until the schedule starts. `nextRelease` (SCHEMA-3.19.0, optional and nullable) is the scheduled draft that the staggered release will publish next, the one with the earliest `publishAfter` date; `null` or absent when there is none. `liveUpdate` (SCHEMA-3.24.0, required) says whether the live version has fallen behind the repository's default branch and what publishing the update would put live; see `SiteLiveUpdate` and `POST .../site:publish-update`.
       properties:
         attention:
           items:
@@ -4132,6 +4132,8 @@ components:
           type: array
         lastPublished:
           $ref: "#/components/schemas/SiteLastPublished"
+        liveUpdate:
+          $ref: "#/components/schemas/SiteLiveUpdate"
         nextRelease:
           oneOf:
             - $ref: "#/components/schemas/SiteNextRelease"
@@ -4165,6 +4167,7 @@ components:
         - state
         - pendingChanges
         - attention
+        - liveUpdate
       type: object
     GetOrganizationsByOrganizationIdPublicationsByPublicationIdTransfersByTransferIdResponse:
       allOf:
@@ -4773,6 +4776,48 @@ components:
       type: object
     GetPlatformPlansResponse:
       $ref: "#/components/schemas/PlatformPlanCapacityRelease"
+    GetPlatformPrismGenerationsResponse:
+      additionalProperties: false
+      allOf:
+        - else:
+            properties:
+              nextCursor:
+                type: "null"
+          if:
+            properties:
+              hasMore:
+                not:
+                  enum:
+                    - false
+                type: boolean
+                x-gala-const: true
+            required:
+              - hasMore
+          then:
+            properties:
+              nextCursor:
+                type: string
+            required:
+              - nextCursor
+      properties:
+        hasMore:
+          type: boolean
+        items:
+          items:
+            $ref: "#/components/schemas/PlatformPrismGeneration"
+          maxItems: 100
+          type: array
+        nextCursor:
+          description: Opaque cursor for the next page. Present and non-null exactly when `hasMore` is true; absent or null when `hasMore` is false.
+          maxLength: 2048
+          minLength: 1
+          type:
+            - string
+            - "null"
+      required:
+        - items
+        - hasMore
+      type: object
     GetPlatformSettingsByKeyResponse:
       $ref: "#/components/schemas/PlatformSetting"
     GetPlatformSettingsOverridesByKindByIdByKeyResponse:
@@ -5690,7 +5735,7 @@ components:
       additionalProperties: false
       properties:
         reasonCode:
-          description: "A free string. Known values: RUN_NOT_STARTED, BUILD_FAILED, RUN_CANCELLED, RUN_TIMED_OUT, WORKFLOW_UNAVAILABLE, DEPLOY_FAILED, PAGES_NOT_AVAILABLE, REPORT_FAILED, LIVE_CHECK_FAILED, CHANGE_CLOSED_ON_GITHUB and, new in 3.17.0, DESTINATION_BUSY_TIMEOUT, DESTINATION_FENCE_EXPIRED, CANONICAL_BASE_MISMATCH, DOMAIN_NOT_READY (the same codes as `OperationReason`). Clients must tolerate other values."
+          description: "A free string. Known values: RUN_NOT_STARTED, BUILD_FAILED, RUN_CANCELLED, RUN_TIMED_OUT, WORKFLOW_UNAVAILABLE, DEPLOY_FAILED, PAGES_NOT_AVAILABLE, REPORT_FAILED, LIVE_CHECK_FAILED, CHANGE_CLOSED_ON_GITHUB and, new in 3.17.0, DESTINATION_BUSY_TIMEOUT, DESTINATION_FENCE_EXPIRED, CANONICAL_BASE_MISMATCH, DOMAIN_NOT_READY and, new in 3.25.0, PAGE_LOSS_GUARD (the same codes as `OperationReason`). Clients must tolerate other values."
           maxLength: 80
           minLength: 1
           type: string
@@ -6476,10 +6521,14 @@ components:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
+        performance:
+          $ref: "#/components/schemas/PortableDeploymentReceiptDeploymentPerformance"
         phase:
           $ref: "#/components/schemas/OperationPhase"
         reason:
           $ref: "#/components/schemas/OperationReason"
+        reasonDetails:
+          $ref: "#/components/schemas/PageLossGuardDetails"
         recoveryActions:
           items:
             maxLength: 80
@@ -7452,6 +7501,8 @@ components:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
+        performance:
+          $ref: "#/components/schemas/PortableDeploymentReceiptDeploymentPerformance"
         phase:
           enum:
             - accepted
@@ -7463,6 +7514,8 @@ components:
           type: string
         reason:
           $ref: "#/components/schemas/OperationReason"
+        reasonDetails:
+          $ref: "#/components/schemas/PageLossGuardDetails"
         recoveryActions:
           items:
             maxLength: 80
@@ -7591,7 +7644,10 @@ components:
         run settled with no receipt), `CANONICAL_BASE_MISMATCH` (the site's
         canonical base was not the address it is served from when the
         operation was dispatched) and `DOMAIN_NOT_READY` (a custom domain was
-        part-way through its switch and no origin could be verified).
+        part-way through its switch and no origin could be verified). New in
+        3.25.0: `PAGE_LOSS_GUARD` (the publish would have removed too many pages
+        from the live site, so authorization was refused and nothing was
+        deployed; the operation's `reasonDetails` carry the counts).
       maxLength: 64
       minLength: 3
       pattern: ^[A-Z][A-Z0-9_]{2,63}$
@@ -7791,6 +7847,34 @@ components:
         - REVOKED
         - EXPIRED
       type: string
+    PageLossGuardDetails:
+      additionalProperties: false
+      description: |
+        SCHEMA-3.25.0. Present on an operation read when `reason` is
+        `PAGE_LOSS_GUARD`: the candidate build has fewer pages than the last
+        successful deployment of the same site and target. `lostPageCount` is
+        `previousPageCount - candidatePageCount`; `permittedLoss` is the loss
+        the platform settings allow. A person who accepts the loss publishes
+        again with `allowPageLoss: true`.
+      properties:
+        candidatePageCount:
+          minimum: 0
+          type: integer
+        lostPageCount:
+          minimum: 0
+          type: integer
+        permittedLoss:
+          minimum: 0
+          type: integer
+        previousPageCount:
+          minimum: 0
+          type: integer
+      required:
+        - previousPageCount
+        - candidatePageCount
+        - lostPageCount
+        - permittedLoss
+      type: object
     PasskeyState:
       enum:
         - ACTIVE
@@ -8657,6 +8741,36 @@ components:
         - PRO
         - BUSINESS
       type: string
+    PlatformPrismGeneration:
+      additionalProperties: false
+      description: SCHEMA-3.25.0. One Prism generation as the operator list shows it, ownership and state only, never article text or the candidate body.
+      properties:
+        createdAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        editionKind:
+          $ref: "#/components/schemas/PrismEditionKind"
+        generationId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        organizationId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        publicationId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        state:
+          $ref: "#/components/schemas/PrismGenerationState"
+      required:
+        - generationId
+        - organizationId
+        - publicationId
+        - editionKind
+        - state
+        - createdAt
+      type: object
     PlatformSetting:
       additionalProperties: false
       description: "An app-wide setting: the active release value, or the default when none is released."
@@ -9044,6 +9158,10 @@ components:
             minimum: 1
       required: []
       type: object
+    PortableContentFrontmatterDeleteDate:
+      description: "SCHEMA-3.25.0: the calendar date (`YYYY-MM-DD`, day precision, read in the publication's staggered-release timezone) on or after which Galascribe removes this article from the published site: it leaves every listing, feed, sitemap and search index and its route renders a removed-post notice. Same format as `publishAfter`; it must be later than `publishAfter` and `date` when both exist. The API enforces that rule; the schema only fixes the shape."
+      pattern: ^\d{4}-\d{2}-\d{2}$
+      type: string
     PortableContentFrontmatterDigest:
       pattern: ^sha256:[0-9a-f]{64}$
       type: string
@@ -9111,6 +9229,8 @@ components:
           type: array
         createdAt:
           $ref: "#/components/schemas/PortableContentFrontmatterRfc3339"
+        deleteDate:
+          $ref: "#/components/schemas/PortableContentFrontmatterDeleteDate"
         description:
           $ref: "#/components/schemas/PortableContentFrontmatterPlainText"
           x-gala-graphemeLength:
@@ -12985,6 +13105,57 @@ components:
         - evidenceDigest
         - probes
       type: object
+    PortableDeploymentReceiptDeploymentPerformance:
+      additionalProperties: false
+      description: "SCHEMA-3.25.0: the publish kernel's size-budget summary of the final artifact. `budgets` are the effective byte budgets; `overBudgetCount` counts every page asset over budget; `overBudget` lists at most 20, largest first. Informational: it never fails a publish."
+      properties:
+        budgets:
+          additionalProperties: false
+          properties:
+            cssBytes:
+              minimum: 1024
+              type: integer
+            htmlBytes:
+              minimum: 1024
+              type: integer
+            jsBytes:
+              minimum: 1024
+              type: integer
+          required: []
+          type: object
+        overBudget:
+          items:
+            additionalProperties: false
+            properties:
+              budget:
+                minimum: 1024
+                type: integer
+              bytes:
+                minimum: 0
+                type: integer
+              kind:
+                enum:
+                  - html
+                  - css
+                  - js
+              path:
+                $ref: "#/components/schemas/PortableDeploymentReceiptRepoRelativePath"
+            required:
+              - path
+              - kind
+              - bytes
+              - budget
+            type: object
+          maxItems: 20
+          type: array
+        overBudgetCount:
+          minimum: 0
+          type: integer
+      required:
+        - budgets
+        - overBudgetCount
+        - overBudget
+      type: object
     PortableDeploymentReceiptDeploymentWarning:
       oneOf:
         - allOf:
@@ -13834,6 +14005,8 @@ components:
             - superseded
             - unknown-reconciling
             - rolled-back
+        performance:
+          $ref: "#/components/schemas/PortableDeploymentReceiptDeploymentPerformance"
         provenanceDigest:
           $ref: "#/components/schemas/PortableDeploymentReceiptDigest"
         publisher:
@@ -15727,6 +15900,10 @@ components:
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublishRequest:
       additionalProperties: false
       properties:
+        allowPageLoss:
+          default: false
+          description: "SCHEMA-3.25.0: true accepts that this publish may remove many pages from the live site. The server stores it with the operation and skips the page-loss guard; absent or false keeps the guard on (a publish that would lose too many pages ends `FAILED_NO_EFFECT` with reason `PAGE_LOSS_GUARD`)."
+          type: boolean
         changeIds:
           items:
             format: uuid
@@ -16225,6 +16402,10 @@ components:
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdPublishesRequest:
       additionalProperties: false
       properties:
+        allowPageLoss:
+          default: false
+          description: "SCHEMA-3.25.0: true accepts that this publish may remove many pages from the live site. The server stores it with the operation and skips the page-loss guard; absent or false keeps the guard on (a publish that would lose too many pages ends `FAILED_NO_EFFECT` with reason `PAGE_LOSS_GUARD`)."
+          type: boolean
         reviewId:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
@@ -16667,6 +16848,21 @@ components:
         - statusUrl
         - reviewId
       type: object
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdSitePublishUpdateRequest:
+      additionalProperties: false
+      description: |
+        `headCommit` is the `liveUpdate.headCommit` the client read and the
+        person confirmed. The server publishes that head only while it is still
+        the repository's head.
+      properties:
+        headCommit:
+          $ref: "#/components/schemas/PortableDeploymentIntentGitObjectId"
+      required:
+        - headCommit
+      type: object
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdSitePublishUpdateResponse:
+      allOf:
+        - $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdPublishesResponse"
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdTransfersByTransferIdCancelRequest:
       additionalProperties: false
       properties:
@@ -19414,6 +19610,10 @@ components:
         manifestDigest:
           pattern: ^sha256:[0-9a-f]{64}$
           type: string
+        pageCount:
+          description: "SCHEMA-3.25.0: the number of `.html` files in the artifact. Optional so a kernel built before 3.25.0 still validates; an absent count exempts the deployment from the page-loss guard."
+          minimum: 0
+          type: integer
         pagesBuildVersion:
           description: |
             The Pages build version this deployment addresses, when the
@@ -20463,6 +20663,85 @@ components:
         - at
         - actor
       type: object
+    SiteLiveUpdate:
+      additionalProperties: false
+      description: |
+        SCHEMA-3.24.0. Whether the live version has fallen behind the
+        repository's default branch, and what publishing the update would put
+        live. `state` is `CURRENT` when the live version is the head, `BEHIND`
+        when the head holds commits the live version lacks, and `UNKNOWN` when
+        nothing has been published yet, the site has no repository binding, or
+        GitHub could not be reached; a client shows nothing extra for `UNKNOWN`.
+        `servedCommit` is the source commit of the live version and
+        `headCommit` is the head the server compared it against, both `null`
+        when they are not known. A client sends `headCommit` back as the body of
+        `POST .../site:publish-update`. `waiting` counts the commits on the head
+        that are not in the live version. `unreviewed` is true when the site
+        requires review and `waiting.authorCommits` is above 0 or
+        `waiting.truncated` is true (a cut-short comparison cannot rule out such
+        commits): those commits never went through a Galascribe review, and a
+        person's press of the publish action counts as their approval. `restored` is true when the
+        live version is a restore of an older version rather than the newest
+        publish; publishing the update replaces it. `publishing` is true while a
+        publish of any kind is already in flight for the site, so a client shows
+        its progress instead of the action.
+      properties:
+        headCommit:
+          oneOf:
+            - $ref: "#/components/schemas/PortableDeploymentIntentGitObjectId"
+            - type: "null"
+        publishing:
+          type: boolean
+        restored:
+          type: boolean
+        servedCommit:
+          oneOf:
+            - $ref: "#/components/schemas/PortableDeploymentIntentGitObjectId"
+            - type: "null"
+        state:
+          enum:
+            - CURRENT
+            - BEHIND
+            - UNKNOWN
+          type: string
+        unreviewed:
+          type: boolean
+        waiting:
+          $ref: "#/components/schemas/SiteLiveUpdateWaiting"
+      required:
+        - state
+        - servedCommit
+        - headCommit
+        - waiting
+        - unreviewed
+        - restored
+        - publishing
+      type: object
+    SiteLiveUpdateWaiting:
+      additionalProperties: false
+      description: |
+        What the repository's default branch holds that the live version does
+        not: the commits on the head that are not in the live version, split by
+        who made them. `authorCommits` are commits a person made outside
+        Galascribe (a push, the GitHub web editor); `galascribeCommits` are
+        Galascribe's own system commits (set-up, Update now and toolchain
+        updates). Both are 0 when the state is `CURRENT` or `UNKNOWN`.
+        `truncated` is true when the comparison was cut short, in which case
+        the counts are lower bounds.
+      properties:
+        authorCommits:
+          minimum: 0
+          type: integer
+        galascribeCommits:
+          minimum: 0
+          type: integer
+        truncated:
+          type: boolean
+      required:
+        - authorCommits
+        - galascribeCommits
+        - truncated
+      type: object
     SiteNextRelease:
       additionalProperties: false
       description: "The next draft the staggered release will publish (SCHEMA-3.19.0): `slug` is the draft's slug and `publishAfter` its `YYYY-MM-DD` date, read in the publication's staggered-release timezone."
@@ -53709,7 +53988,9 @@ paths:
       description: |
         The one read behind a Home screen: the live address, whether the site is live, publishing or has never been published, who published last, the unpublished changes in words, and what needs attention.
 
-        `pendingChanges` holds exactly one entry per path (and one for the look): the newest unpublished change for a path wins, older ones are superseded and omitted. `review` is `NOT_REQUIRED` unless the publication's `publishingPolicy.requireReview` is true. `attention[].code` is a closed vocabulary; `relatedChangeId` names the change that needs the action. `publishing.stage` follows `QUEUED`, `PREPARING`, `BUILDING`, `GOING_LIVE`, `CHECKING_LIVE`; `publishing.runUrl` links the GitHub run and `publishing.stageSince` says when the stage began. Read from the platform's own records; nothing is read from the person's repository.
+        `pendingChanges` holds exactly one entry per path (and one for the look): the newest unpublished change for a path wins, older ones are superseded and omitted. `review` is `NOT_REQUIRED` unless the publication's `publishingPolicy.requireReview` is true. `attention[].code` is a closed vocabulary; `relatedChangeId` names the change that needs the action. `publishing.stage` follows `QUEUED`, `PREPARING`, `BUILDING`, `GOING_LIVE`, `CHECKING_LIVE`; `publishing.runUrl` links the GitHub run and `publishing.stageSince` says when the stage began. Read from the platform's own records, except `liveUpdate`.
+
+        `liveUpdate` (SCHEMA-3.24.0) says whether the live version has fallen behind the repository's default branch, which is what should be live. `state` is `CURRENT`, `BEHIND` or `UNKNOWN` (never published, no repository binding, or GitHub could not be reached; a client shows nothing extra for `UNKNOWN`, and the rest of the read is unaffected). `servedCommit` is the source commit of the live version; `headCommit` is the head the server compared it against, read from GitHub and possibly a short-lived cached read; a client sends `headCommit` back to `POST .../site:publish-update`. `waiting` counts the commits on the head that are not in the live version, split into `authorCommits` (made outside Galascribe) and `galascribeCommits` (Galascribe's own system commits), with `truncated` true when the comparison was cut short. `unreviewed` is true when the site requires review and `waiting.authorCommits` is above 0 or `waiting.truncated` is true. `restored` is true when the live version is a restore of an older version rather than the newest publish. `publishing` is true while a publish of any kind is in flight for the site.
       operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdSite
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -53744,6 +54025,17 @@ paths:
                       actor:
                         displayName: Asha Rao
                       at: "2026-10-05T09:30:00Z"
+                    liveUpdate:
+                      headCommit: sha1:2222222222222222222222222222222222222222
+                      publishing: false
+                      restored: false
+                      servedCommit: sha1:1111111111111111111111111111111111111111
+                      state: BEHIND
+                      unreviewed: true
+                      waiting:
+                        authorCommits: 2
+                        galascribeCommits: 1
+                        truncated: false
                     pendingChanges:
                       - action: EDIT
                         author:
@@ -53899,27 +54191,441 @@ paths:
             - RESOURCE_NOT_FOUND
       security:
         - browserSession: []
-      summary: read the site summary of this publication
+      summary: read the site summary of this publication
+      tags:
+        - organizations
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.view
+      x-gala-concurrency: publication-and-destination-epochs
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: read the site summary of this publication
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: safe-query
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: query
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/site:publish-update:
+    post:
+      description: |
+        Publishes the repository's current default-branch head when the live version is behind it ("Publish the update"): the commits made outside Galascribe by a push or the GitHub web editor, Galascribe's own system commits that were held back, and the head after a failed publish. The body names the `headCommit` the client read from the site read's `liveUpdate`. Success is `202` with the accepted operation (kind `publish`; `publishId` names it, and the operation's `subject.generationId` names the generation once it exists), the same shape as `changes:publish`. No change is named and nothing is merged: the head is built as it stands. A post dated for later is a draft with `publishAfter` and a production build leaves drafts out, so publishing the update never releases one early.
+
+        The person pressing the action is the approval. When the publication's `publishingPolicy.requireReview` is true and `liveUpdate.unreviewed` is true, the commits counted in `liveUpdate.waiting.authorCommits` never went through a Galascribe review; a person's press of this action counts as approval of those commits, so no `REVIEW_REQUIRED` refusal applies here and the press is recorded against the person. A client shows what will go live and says so before it asks. The same press replaces a restored version: when `liveUpdate.restored` is true the live version is a restore of an older version (a rollback), and publishing the update puts the head live in its place. The automatic paths (self-heal and the set-up republish) never move a restored site; only this action does. After a publish that gave up or is backing off, a press starts a fresh attempt.
+
+        The person needs `publication.publish` and a recent authentication: a stale session gets `401 REAUTH_REQUIRED` and the client confirms the person again and resumes. `Idempotency-Key` is required; a replay with the same key and body returns the first result, the same key with a different body is `409 COMMAND_REPLAY_CONFLICT`. The server checks, in this order and with nothing written on a refusal: `409 HEAD_MOVED` when the repository head is no longer `headCommit` (the client reads the site again and asks again with the new head); `409 ALREADY_LIVE` when the live version is already that head; `409 PUBLISH_IN_PROGRESS` while a publish of any kind is in flight for the site; `409 NOT_SET_UP` when the repository has not been set up for the current Galascribe toolchain, and Update now (`POST .../repository:set-up`) comes first. This operation is not callable with an admin API key.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdSitePublishUpdate
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      requestBody:
+        content:
+          application/json:
+            examples:
+              nominal:
+                summary: Nominal valid request
+                value:
+                  headCommit: sha1:2222222222222222222222222222222222222222
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdSitePublishUpdateRequest"
+        required: true
+      responses:
+        "202":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    commandId: 018f0000-0000-7000-8000-000000000001
+                    operationId: 018f0000-0000-7000-8000-000000000001
+                    phase: accepted
+                    publishId: 018f0000-0000-7000-8000-000000000003
+                    resourceVersion: 0
+                    statusUrl: /v2/organizations/018f0000-0000-7000-8000-000000000001/operations/018f0000-0000-7000-8000-000000000002
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdSitePublishUpdateResponse"
+          description: publish the repository's current head as the update to the live site succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                REQUEST_FIELD_UNKNOWN:
+                  summary: REQUEST_FIELD_UNKNOWN
+                  value:
+                    code: REQUEST_FIELD_UNKNOWN
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: REQUEST_FIELD_UNKNOWN
+                    type: urn:gala:problem:request-field-unknown
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: REQUEST_FIELD_UNKNOWN, VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - REQUEST_FIELD_UNKNOWN
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+                REAUTH_REQUIRED:
+                  summary: REAUTH_REQUIRED
+                  value:
+                    code: REAUTH_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: REAUTH_REQUIRED
+                    type: urn:gala:problem:reauth-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED, REAUTH_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+            - REAUTH_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                ALREADY_LIVE:
+                  summary: ALREADY_LIVE
+                  value:
+                    code: ALREADY_LIVE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: ALREADY_LIVE
+                    type: urn:gala:problem:already-live
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                HEAD_MOVED:
+                  summary: HEAD_MOVED
+                  value:
+                    code: HEAD_MOVED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: HEAD_MOVED
+                    type: urn:gala:problem:head-moved
+                NOT_SET_UP:
+                  summary: NOT_SET_UP
+                  value:
+                    code: NOT_SET_UP
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: NOT_SET_UP
+                    type: urn:gala:problem:not-set-up
+                PUBLISH_IN_PROGRESS:
+                  summary: PUBLISH_IN_PROGRESS
+                  value:
+                    code: PUBLISH_IN_PROGRESS
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: PUBLISH_IN_PROGRESS
+                    type: urn:gala:problem:publish-in-progress
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: ALREADY_LIVE, COMMAND_REPLAY_CONFLICT, HEAD_MOVED, NOT_SET_UP, PUBLISH_IN_PROGRESS
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - ALREADY_LIVE
+            - COMMAND_REPLAY_CONFLICT
+            - HEAD_MOVED
+            - NOT_SET_UP
+            - PUBLISH_IN_PROGRESS
+        "422":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 422
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "429":
+          content:
+            application/problem+json:
+              examples:
+                RATE_LIMITED:
+                  summary: RATE_LIMITED
+                  value:
+                    code: RATE_LIMITED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: true
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 429
+                    title: RATE_LIMITED
+                    type: urn:gala:problem:rate-limited
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RATE_LIMITED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Retry-After:
+              $ref: "#/components/headers/RetryAfter"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RATE_LIMITED
+        "503":
+          content:
+            application/problem+json:
+              examples:
+                CAPABILITY_UNAVAILABLE:
+                  summary: CAPABILITY_UNAVAILABLE
+                  value:
+                    code: CAPABILITY_UNAVAILABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 503
+                    title: CAPABILITY_UNAVAILABLE
+                    type: urn:gala:problem:capability-unavailable
+                DEPENDENCY_UNAVAILABLE:
+                  summary: DEPENDENCY_UNAVAILABLE
+                  value:
+                    code: DEPENDENCY_UNAVAILABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: true
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 503
+                    title: DEPENDENCY_UNAVAILABLE
+                    type: urn:gala:problem:dependency-unavailable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: CAPABILITY_UNAVAILABLE, DEPENDENCY_UNAVAILABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - CAPABILITY_UNAVAILABLE
+            - DEPENDENCY_UNAVAILABLE
+      security:
+        - browserSession: []
+      summary: publish the repository head as the update to the live site
       tags:
         - organizations
+      x-gala-action-grant: none
       x-gala-activation-gate: MVP
       x-gala-activation-guards:
-        - NONE
-      x-gala-capability-key: publication.view
+        - Active binding epoch, admitted author-source contract, admitted destination, and no transfer or retirement fence
+      x-gala-assurance-class: RECENT_AUTHENTICATION
+      x-gala-capability-key: publication.publish
       x-gala-concurrency: publication-and-destination-epochs
       x-gala-conditional-capabilities: []
       x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
       x-gala-nullability: required-and-nullable-are-explicit
-      x-gala-purpose: read the site summary of this publication
+      x-gala-purpose: publish the repository head as the update to the live site
       x-gala-reachable-problems:
+        - ALREADY_LIVE
         - AUTHENTICATION_REQUIRED
         - AUTHORIZATION_DENIED
+        - CAPABILITY_UNAVAILABLE
+        - COMMAND_REPLAY_CONFLICT
+        - DEPENDENCY_UNAVAILABLE
+        - HEAD_MOVED
+        - NOT_SET_UP
+        - PUBLISH_IN_PROGRESS
+        - RATE_LIMITED
+        - REAUTH_REQUIRED
+        - REQUEST_FIELD_UNKNOWN
         - RESOURCE_NOT_FOUND
         - VALIDATION_FAILED
-      x-gala-replay-identity: safe-query
+      x-gala-replay-identity: idempotency-key
       x-gala-state-guards:
         - NONE
-      x-gala-success-category: query
+      x-gala-success-category: async
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
   /v2/organizations/{organizationId}/publications/{publicationId}/transfers:
     post:
@@ -59322,6 +60028,175 @@ paths:
         - NONE
       x-gala-success-category: update
       x-gala-tenant-scope: NONE
+  /v2/platform/prism-generations:
+    get:
+      description: |
+        Operators only (`ADMIN` or `ROOT`). Every Prism edition generation on
+        the platform across all organizations, newest first, one keyset page at
+        a time. Article text and candidate bodies are never exposed, only the
+        generation's state, size and ownership.
+      operationId: getPlatformPrismGenerations
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - description: Only generations in this state.
+          example: CANDIDATE_READY
+          in: query
+          name: state
+          required: false
+          schema:
+            $ref: "#/components/schemas/PrismGenerationState"
+        - $ref: "#/components/parameters/Cursor"
+        - $ref: "#/components/parameters/Limit"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    hasMore: false
+                    items:
+                      - createdAt: "2026-10-10T12:00:00.000Z"
+                        editionKind: QUICK_READ
+                        generationId: 018f0000-0000-7000-8000-000000000001
+                        organizationId: 018f0000-0000-7000-8000-000000000003
+                        publicationId: 018f0000-0000-7000-8000-000000000002
+                        state: CANDIDATE_READY
+                    nextCursor: null
+              schema:
+                $ref: "#/components/schemas/GetPlatformPrismGenerationsResponse"
+          description: list platform Prism generations succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          $ref: "#/components/responses/ValidationFailed"
+        "401":
+          $ref: "#/components/responses/PlatformAuthenticationRequired"
+        "403":
+          $ref: "#/components/responses/AuthorizationDenied"
+      security:
+        - browserSession: []
+      summary: list platform Prism generations
+      tags:
+        - platform
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: platform.prism.view
+      x-gala-concurrency: none
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: list platform Prism generations
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - REAUTH_REQUIRED
+        - VALIDATION_FAILED
+      x-gala-replay-identity: safe-query
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: query
+      x-gala-tenant-scope: NONE
+  /v2/platform/prism-generations:export:
+    post:
+      description: Operators only (`ADMIN` or `ROOT`), with recent authentication (`401 REAUTH_REQUIRED` when the session is stale). The answer is a UTF-8 CSV file with a header row (`generationId,organizationId,publicationId,editionKind,state,createdAt`) that the operator App saves as a download. A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return is prefixed with an apostrophe so a spreadsheet does not run it as a formula.
+      operationId: postPlatformPrismGenerationsExport
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - $ref: "#/components/parameters/XCsrfToken"
+      responses:
+        "200":
+          content:
+            text/csv:
+              schema:
+                format: binary
+                type: string
+          description: export platform Prism generations as CSV succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Content-Disposition:
+              $ref: "#/components/headers/ContentDispositionAttachment"
+            X-Content-Type-Options:
+              $ref: "#/components/headers/XContentTypeOptionsNosniff"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          $ref: "#/components/responses/ValidationFailed"
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+                REAUTH_REQUIRED:
+                  summary: REAUTH_REQUIRED
+                  value:
+                    code: REAUTH_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: REAUTH_REQUIRED
+                    type: urn:gala:problem:reauth-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED, REAUTH_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+            - REAUTH_REQUIRED
+        "403":
+          $ref: "#/components/responses/AuthorizationDenied"
+      security:
+        - browserSession: []
+      summary: export platform Prism generations as CSV
+      tags:
+        - platform
+      x-gala-action-grant: none
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-assurance-class: RECENT_AUTHENTICATION
+      x-gala-capability-key: platform.prism.export
+      x-gala-concurrency: none
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: export platform Prism generations as CSV
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - REAUTH_REQUIRED
+        - VALIDATION_FAILED
+      x-gala-replay-identity: natural-idempotent-state
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: NONE
   /v2/platform/settings/overrides/{kind}/{id}/{key}:
     delete:
       description: |