@rathnasgala2/schemas 2.21.0 → 3.0.0

package/openapi/openapi.yaml

@@ -1512,6 +1512,48 @@ components:
         - version
         - state
       type: object
+    GetOrganizationsByOrganizationIdPublicationsByPublicationIdHistoryResponse:
+      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/HistoryEntry"
+          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. The length bounds constrain the string branch only.
+          maxLength: 2048
+          minLength: 1
+          type:
+            - string
+            - "null"
+      required:
+        - items
+        - hasMore
+      type: object
     GetOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryBindingsCurrentResponse:
       additionalProperties: false
       properties:
@@ -1644,6 +1686,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
+        publishingPolicy:
+          $ref: "#/components/schemas/PublishingPolicy"
         slug:
           maxLength: 80
           minLength: 1
@@ -1709,6 +1753,61 @@ components:
         - items
         - hasMore
       type: object
+    GetOrganizationsByOrganizationIdPublicationsByPublicationIdSiteResponse:
+      additionalProperties: false
+      allOf:
+        - else:
+            not:
+              required:
+                - publishing
+          if:
+            properties:
+              state:
+                pattern: ^PUBLISHING$
+                type: string
+                x-gala-const: PUBLISHING
+            required:
+              - state
+          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`.
+      properties:
+        attention:
+          items:
+            $ref: "#/components/schemas/SiteAttentionItem"
+          maxItems: 20
+          type: array
+        lastPublished:
+          $ref: "#/components/schemas/SiteLastPublished"
+        pendingChanges:
+          items:
+            $ref: "#/components/schemas/SitePendingChange"
+          maxItems: 200
+          type: array
+        publishing:
+          $ref: "#/components/schemas/SitePublishing"
+        state:
+          enum:
+            - LIVE
+            - PUBLISHING
+            - NEVER_PUBLISHED
+            - FAILED
+            - UNKNOWN
+          type: string
+        url:
+          maxLength: 2048
+          minLength: 1
+          pattern: ^https://
+          type:
+            - string
+            - "null"
+      required:
+        - url
+        - state
+        - pendingChanges
+        - attention
+      type: object
     GetOrganizationsByOrganizationIdPublicationsResponse:
       additionalProperties: false
       allOf:
@@ -2231,6 +2330,149 @@ components:
         - PRIVATE
         - PUBLIC
       type: string
+    HistoryChange:
+      additionalProperties: false
+      allOf:
+        - else:
+            properties:
+              action:
+                enum:
+                  - CREATE
+                  - EDIT
+                  - DELETE
+          if:
+            properties:
+              kind:
+                pattern: ^LOOK$
+                type: string
+                x-gala-const: LOOK
+            required:
+              - kind
+          then:
+            properties:
+              action:
+                pattern: ^CHANGE$
+                type: string
+                x-gala-const: CHANGE
+      properties:
+        action:
+          description: "`CHANGE` is used for `LOOK` and only for `LOOK`; `POST` and `PAGE` use `CREATE`, `EDIT` or `DELETE`."
+          enum:
+            - CREATE
+            - EDIT
+            - DELETE
+            - CHANGE
+          type: string
+        kind:
+          enum:
+            - POST
+            - PAGE
+            - LOOK
+          type: string
+        path:
+          description: Repository path of the post or page; absent for `LOOK`.
+          maxLength: 512
+          minLength: 1
+          type: string
+        theme:
+          $ref: "#/components/schemas/SiteThemeChange"
+        title:
+          maxLength: 200
+          minLength: 1
+          type: string
+      required:
+        - kind
+        - action
+        - title
+      type: object
+    HistoryEntry:
+      additionalProperties: false
+      allOf:
+        - else:
+            not:
+              required:
+                - failure
+            required:
+              - versionId
+          if:
+            properties:
+              outcome:
+                pattern: ^FAILED$
+                type: string
+                x-gala-const: FAILED
+            required:
+              - outcome
+          then:
+            not:
+              required:
+                - versionId
+            required:
+              - failure
+      description: One version that went live, or the trailing failed attempt. `versionId` is the deployment generation id and is accepted by `POST .../deployments:rollback` as `generationId`.
+      properties:
+        actor:
+          $ref: "#/components/schemas/SiteActor"
+        at:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        changes:
+          items:
+            $ref: "#/components/schemas/HistoryChange"
+          maxItems: 200
+          type: array
+        failedAttemptsBefore:
+          $ref: "#/components/schemas/HistoryFailedAttempts"
+        failure:
+          $ref: "#/components/schemas/HistoryFailure"
+        outcome:
+          description: "`LIVE`: serving visitors now. `REPLACED`: went live and was superseded. `RESTORED`: went live by restoring an earlier version (`restoredFromVersionId`); once superseded it reads `REPLACED`. `FAILED`: only the trailing entry when the latest attempt failed."
+          enum:
+            - LIVE
+            - REPLACED
+            - RESTORED
+            - FAILED
+          type: string
+        restoredFromVersionId:
+          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
+        versionId:
+          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
+      required:
+        - at
+        - actor
+        - outcome
+        - changes
+        - failedAttemptsBefore
+      type: object
+    HistoryFailedAttempts:
+      additionalProperties: false
+      description: Failed publish attempts since the previous entry, folded into this one.
+      properties:
+        count:
+          minimum: 0
+          type: integer
+        lastReason:
+          maxLength: 80
+          minLength: 1
+          type: string
+      required:
+        - count
+      type: object
+    HistoryFailure:
+      additionalProperties: false
+      properties:
+        reasonCode:
+          maxLength: 80
+          minLength: 1
+          type: string
+        retryable:
+          type: boolean
+      required:
+        - reasonCode
+        - retryable
+      type: object
     KernelAttemptSubmission:
       additionalProperties: false
       allOf:
@@ -3520,6 +3762,16 @@ components:
           maxLength: 80
           minLength: 1
           type: string
+        publishingPolicy:
+          additionalProperties: false
+          description: "A partial update of `PublishingPolicy`: an omitted member keeps its current value."
+          minProperties: 1
+          properties:
+            galascribeMerges:
+              type: boolean
+            requireReview:
+              type: boolean
+          type: object
         slug:
           maxLength: 80
           minLength: 1
@@ -3537,6 +3789,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
+        publishingPolicy:
+          $ref: "#/components/schemas/PublishingPolicy"
         slug:
           maxLength: 80
           minLength: 1
@@ -9831,6 +10085,26 @@ components:
     PostOrganizationsByOrganizationIdPublicationImportsResponse:
       allOf:
         - $ref: "#/components/schemas/OperationResponse"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublishRequest:
+      additionalProperties: false
+      properties:
+        changeIds:
+          items:
+            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
+          maxItems: 20
+          minItems: 1
+          type: array
+          uniqueItems: true
+        scheduledFor:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - changeIds
+      type: object
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublishResponse:
+      allOf:
+        - $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdPublishesResponse"
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlanRequest:
       oneOf:
         - additionalProperties: false
@@ -11121,6 +11395,20 @@ components:
         - CANCELLED
         - FINAL_FAILED
       type: string
+    PublishingPolicy:
+      additionalProperties: false
+      description: "How this publication publishes. Absence of the member on the publication resource means the defaults: `requireReview` false, `galascribeMerges` true."
+      properties:
+        galascribeMerges:
+          description: Default true. When true Galascribe opens and merges the pull request itself through the GitHub App; when false each change must already be merged on GitHub before it can be published.
+          type: boolean
+        requireReview:
+          description: Default false. When true a change needs an approved review before it can be published.
+          type: boolean
+      required:
+        - requireReview
+        - galascribeMerges
+      type: object
     PutOrganizationsByOrganizationIdPublicationsByPublicationIdDestinationRequest:
       additionalProperties: false
       allOf:
@@ -12264,72 +12552,232 @@ components:
         - lastSeenAt
         - current
       type: object
-    VerificationPlanEntry:
+    SiteActor:
       additionalProperties: false
+      description: A person named in words. The identity is the display name; no principal id is exposed on this surface.
       properties:
-        byteLength:
-          format: int64
-          minimum: 0
-          type: integer
-        expectedCandidateDigest:
-          pattern: ^sha256:[0-9a-f]{64}$
-          type: string
-        expectedContentType:
-          maxLength: 128
-          minLength: 3
-          pattern: ^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}/[a-z0-9][a-z0-9!#$&^_.+-]{0,62}(?:; charset=utf-8)?$
-          type: string
-        path:
-          $ref: "#/components/schemas/PortableDeploymentReceiptRepoRelativePath"
-        publicRoute:
-          $ref: "#/components/schemas/PortableDeploymentReceiptCanonicalRoute"
-        routeClass:
-          enum:
-            - html
-            - feed
-            - sitemap
-            - asset
-            - error
+        displayName:
+          maxLength: 200
+          minLength: 1
           type: string
       required:
-        - path
-        - publicRoute
-        - routeClass
-        - expectedContentType
-        - byteLength
-        - expectedCandidateDigest
+        - displayName
       type: object
-    VerificationSubmissionFit:
+    SiteAttentionItem:
       additionalProperties: false
-      description: The complete verification plan fits one request, and the request carries every entry.
+      description: Something that needs a person to act. The list is empty when nothing does.
       properties:
-        state:
-          pattern: ^fit$
+        code:
+          enum:
+            - REPOSITORY_NEEDS_UPDATE
+            - CONTENT_CONFLICT
+            - PUBLISH_FAILED
+            - AUTHORIZATION_LOST
+            - REPOSITORY_NOT_SET_UP
+            - DESTINATION_NOT_CHOSEN
+          type: string
+        relatedChangeId:
+          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
-          x-gala-const: fit
-        verificationEntries:
-          items:
-            $ref: "#/components/schemas/VerificationPlanEntry"
-          maxItems: 900
-          minItems: 1
-          type: array
       required:
-        - state
-        - verificationEntries
+        - code
       type: object
-    VerificationSubmissionUnfit:
+    SiteLastPublished:
       additionalProperties: false
-      description: The complete verification plan does not fit one request, so the request states why and by how much instead of carrying a truncated plan.
       properties:
-        canonicalFitRequestByteCount:
-          format: int64
-          minimum: 1
-          type: integer
-        reason:
-          enum:
-            - entry-count-exceeded
-            - encoded-request-limit-exceeded
-          type: string
+        actor:
+          $ref: "#/components/schemas/SiteActor"
+        at:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - at
+        - actor
+      type: object
+    SitePendingChange:
+      additionalProperties: false
+      allOf:
+        - else:
+            properties:
+              action:
+                enum:
+                  - CREATE
+                  - EDIT
+                  - DELETE
+          if:
+            properties:
+              kind:
+                pattern: ^LOOK$
+                type: string
+                x-gala-const: LOOK
+            required:
+              - kind
+          then:
+            properties:
+              action:
+                pattern: ^CHANGE$
+                type: string
+                x-gala-const: CHANGE
+      description: "One unpublished change in words. Exactly one entry exists per path (and one for the look): when several unpublished changes touch the same path only the newest is listed and older ones are superseded and omitted."
+      properties:
+        action:
+          description: "`CHANGE` is used for `LOOK` and only for `LOOK`; `POST` and `PAGE` use `CREATE`, `EDIT` or `DELETE`."
+          enum:
+            - CREATE
+            - EDIT
+            - DELETE
+            - CHANGE
+          type: string
+        author:
+          $ref: "#/components/schemas/SiteActor"
+        changeId:
+          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
+        kind:
+          enum:
+            - POST
+            - PAGE
+            - LOOK
+          type: string
+        path:
+          description: Repository path of the post or page; absent for `LOOK`.
+          maxLength: 512
+          minLength: 1
+          type: string
+        review:
+          description: "`NOT_REQUIRED` when the publication does not require review; otherwise `WAITING`, `APPROVED` or `CHANGES_REQUESTED`."
+          enum:
+            - NOT_REQUIRED
+            - WAITING
+            - APPROVED
+            - CHANGES_REQUESTED
+          type: string
+        reviewId:
+          description: The review a reviewer decides through `POST .../reviews/{reviewId}:decide`. Present when a review exists.
+          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
+        theme:
+          $ref: "#/components/schemas/SiteThemeChange"
+        title:
+          maxLength: 200
+          minLength: 1
+          type: string
+        updatedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - changeId
+        - kind
+        - action
+        - title
+        - review
+        - updatedAt
+        - author
+      type: object
+    SitePublishing:
+      additionalProperties: false
+      properties:
+        operationId:
+          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
+        stage:
+          enum:
+            - PREPARING
+            - BUILDING
+            - GOING_LIVE
+          type: string
+        startedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - operationId
+        - stage
+        - startedAt
+      type: object
+    SiteThemeChange:
+      additionalProperties: false
+      properties:
+        from:
+          maxLength: 200
+          minLength: 1
+          type:
+            - string
+            - "null"
+        to:
+          maxLength: 200
+          minLength: 1
+          type: string
+      required:
+        - from
+        - to
+      type: object
+    VerificationPlanEntry:
+      additionalProperties: false
+      properties:
+        byteLength:
+          format: int64
+          minimum: 0
+          type: integer
+        expectedCandidateDigest:
+          pattern: ^sha256:[0-9a-f]{64}$
+          type: string
+        expectedContentType:
+          maxLength: 128
+          minLength: 3
+          pattern: ^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}/[a-z0-9][a-z0-9!#$&^_.+-]{0,62}(?:; charset=utf-8)?$
+          type: string
+        path:
+          $ref: "#/components/schemas/PortableDeploymentReceiptRepoRelativePath"
+        publicRoute:
+          $ref: "#/components/schemas/PortableDeploymentReceiptCanonicalRoute"
+        routeClass:
+          enum:
+            - html
+            - feed
+            - sitemap
+            - asset
+            - error
+          type: string
+      required:
+        - path
+        - publicRoute
+        - routeClass
+        - expectedContentType
+        - byteLength
+        - expectedCandidateDigest
+      type: object
+    VerificationSubmissionFit:
+      additionalProperties: false
+      description: The complete verification plan fits one request, and the request carries every entry.
+      properties:
+        state:
+          pattern: ^fit$
+          type: string
+          x-gala-const: fit
+        verificationEntries:
+          items:
+            $ref: "#/components/schemas/VerificationPlanEntry"
+          maxItems: 900
+          minItems: 1
+          type: array
+      required:
+        - state
+        - verificationEntries
+      type: object
+    VerificationSubmissionUnfit:
+      additionalProperties: false
+      description: The complete verification plan does not fit one request, so the request states why and by how much instead of carrying a truncated plan.
+      properties:
+        canonicalFitRequestByteCount:
+          format: int64
+          minimum: 1
+          type: integer
+        reason:
+          enum:
+            - entry-count-exceeded
+            - encoded-request-limit-exceeded
+          type: string
         requiredVerificationEntryCount:
           maximum: 200000
           minimum: 1
@@ -19688,6 +20136,8 @@ paths:
       x-gala-success-category: query
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
     patch:
+      description: |
+        Updates publication metadata and state. As of schema 2.22.0 the request may also carry `publishingPolicy` (`requireReview`, `galascribeMerges`), a partial update: an omitted member keeps its value. The publication resource (`GET` and this response) returns `publishingPolicy`; its absence means the defaults, `requireReview` false and `galascribeMerges` true. The policy governs `POST .../changes:publish` and the review of changes.
       operationId: patchOrganizationsByOrganizationIdPublicationsByPublicationId
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -20266,9 +20716,17 @@ paths:
         - NONE
       x-gala-success-category: query
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
-  /v2/organizations/{organizationId}/publications/{publicationId}/configuration-changes:plan:
+  /v2/organizations/{organizationId}/publications/{publicationId}/changes:publish:
     post:
-      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlan
+      description: |
+        Publishes the named repository changes together. For each change, in order:
+
+        1. If the change is behind the main branch head it is brought up to date automatically when that is clean (the same file-level merge as `:bring-up-to-date`). When it is not clean nothing is written for any change and the response is `409 INVALID_SOURCE_STATE` with one error per conflicting path (`code: CONTENT_CONFLICT`, `pointer: /documents/<path>` or `/assets/<path>`) and the live head on `X-Gala-Current-Head`.
+        2. If the publication's `publishingPolicy.requireReview` is true and the change has no approval, `409 INVALID_SOURCE_STATE` with `errors[].code REVIEW_REQUIRED` pointed at `/changeIds/<index>`.
+        3. If `publishingPolicy.galascribeMerges` is true (the default) the server opens and merges the pull request itself through the GitHub App. Otherwise each change must already be merged on GitHub; one that is not is `409 INVALID_SOURCE_STATE` with `errors[].code SOURCE_NOT_MERGED` pointed at `/changeIds/<index>`.
+
+        Then ONE deploy of the resulting main head is started. Success is `202` with the accepted operation (kind `publish`; `publishId` names it, and the operation's `subject.generationId` names the generation once it exists). `scheduledFor` schedules the deploy instead of starting it now and additionally needs `publication.schedule`; it is cancelled with `:cancel` on the publish. `Idempotency-Key` replays the same acceptance. Whole-request validation happens before any change is merged: a refused request merges nothing.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublish
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
         - example: 018f0000-0000-7000-8000-000000000001
@@ -20296,33 +20754,31 @@ paths:
               nominal:
                 summary: Nominal valid request
                 value:
-                  changeKind: PORTABLE_SETTINGS
-                  expectedHead: sha1:0000000000000000000000000000000000000000
-                  inputDigest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+                  changeIds:
+                    - 018f0000-0000-7000-8000-000000000001
             schema:
-              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlanRequest"
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublishRequest"
         required: true
       responses:
-        "201":
+        "202":
           content:
             application/json:
               examples:
                 nominal:
                   summary: Nominal successful response
                   value:
-                    changeId: 018f0000-0000-7000-8000-000000000001
-                    diffDigest: sha256:0000000000000000000000000000000000000000000000000000000000000000
-                    expectedHead: sha1:0000000000000000000000000000000000000000
-                    state: REQUESTED
-                    version: 0
+                    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/PostOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlanResponse"
-          description: plan typed publication or module configuration diff against exact Git head succeeded
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublishResponse"
+          description: publish a batch of changes with one deploy of the resulting main head succeeded
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
-            Location:
-              $ref: "#/components/headers/Location"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
         "400":
@@ -20469,8 +20925,12 @@ paths:
                   value:
                     code: INVALID_SOURCE_STATE
                     correlationId: 018f0000-0000-7000-8000-000000000001
-                    detail: See the operation contract.
-                    errors: []
+                    detail: "One or more changes cannot be published yet. Each error points at the change or path: CONTENT_CONFLICT at /documents/<path> or /assets/<path>, REVIEW_REQUIRED or SOURCE_NOT_MERGED at /changeIds/<index>. See the operation contract."
+                    errors:
+                      - code: CONTENT_CONFLICT
+                        pointer: /documents/content~1articles~1example.md
+                      - code: REVIEW_REQUIRED
+                        pointer: /changeIds/1
                     retryable: false
                     schemaId: urn:gala:schema:problem:2.0.0
                     schemaVersion: 2.0.0
@@ -20485,36 +20945,40 @@ paths:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
+            X-Gala-Current-Head:
+              $ref: "#/components/headers/XGalaCurrentHead"
           x-gala-problem-codes:
             - COMMAND_REPLAY_CONFLICT
             - INVALID_SOURCE_STATE
-        "422":
+        "429":
           content:
             application/problem+json:
               examples:
-                VALIDATION_FAILED:
-                  summary: VALIDATION_FAILED
+                RATE_LIMITED:
+                  summary: RATE_LIMITED
                   value:
-                    code: VALIDATION_FAILED
+                    code: RATE_LIMITED
                     correlationId: 018f0000-0000-7000-8000-000000000001
                     detail: See the operation contract.
                     errors: []
-                    retryable: false
+                    retryable: true
                     schemaId: urn:gala:schema:problem:2.0.0
                     schemaVersion: 2.0.0
-                    status: 422
-                    title: VALIDATION_FAILED
-                    type: urn:gala:problem:validation-failed
+                    status: 429
+                    title: RATE_LIMITED
+                    type: urn:gala:problem:rate-limited
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: VALIDATION_FAILED
+          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:
-            - VALIDATION_FAILED
+            - RATE_LIMITED
         "503":
           content:
             application/problem+json:
@@ -20532,9 +20996,22 @@ paths:
                     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
+          description: CAPABILITY_UNAVAILABLE, DEPENDENCY_UNAVAILABLE
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
@@ -20542,30 +21019,31 @@ paths:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
             - CAPABILITY_UNAVAILABLE
+            - DEPENDENCY_UNAVAILABLE
       security:
         - browserSession: []
-      summary: plan typed publication or module configuration diff against exact Git head
+      summary: publish a batch of changes with one deploy of the resulting main head
       tags:
         - organizations
       x-gala-activation-gate: MVP
       x-gala-activation-guards:
-        - Current expected Git head, active binding epoch, and admitted typed configuration contract
-      x-gala-capability-key: publication.settings.manage
-      x-gala-concurrency: expected-git-head-and-binding-epoch
+        - Active binding epoch, admitted author-source contract, admitted destination, and no transfer or retirement fence
+      x-gala-capability-key: publication.publish
+      x-gala-concurrency: publication-and-destination-epochs
       x-gala-conditional-capabilities:
-        - capabilityKey: publication.modules.manage
-          when: changeKind == MODULES
-        - capabilityKey: publication.policy.manage
-          when: changeKind == POLICY
+        - capabilityKey: publication.schedule
+          when: scheduledFor is present
       x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
       x-gala-nullability: required-and-nullable-are-explicit
-      x-gala-purpose: plan typed publication or module configuration diff against exact Git head
+      x-gala-purpose: publish a batch of changes with one deploy of the resulting main head
       x-gala-reachable-problems:
         - AUTHENTICATION_REQUIRED
         - AUTHORIZATION_DENIED
         - CAPABILITY_UNAVAILABLE
         - COMMAND_REPLAY_CONFLICT
+        - DEPENDENCY_UNAVAILABLE
         - INVALID_SOURCE_STATE
+        - RATE_LIMITED
         - REQUEST_FIELD_UNKNOWN
         - RESOURCE_NOT_FOUND
         - VALIDATION_FAILED
@@ -20573,29 +21051,340 @@ paths:
       x-gala-state-guards:
         - Publication:ACTIVE
         - RepositoryBinding:ACTIVE
-        - RepositoryChange:REQUESTED -> PLANNED
-      x-gala-success-category: create
+        - PublicationDestination:SET|LOCKED
+        - RepositoryChange:PLANNED|AWAITING_CONFIRMATION|COMMITTED -> merged -> published
+      x-gala-success-category: async
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
-  /v2/organizations/{organizationId}/publications/{publicationId}/content:
-    get:
-      description: |
-        One git-trees read per declared content root at the linked repository's
-        current main branch head, bounded at 2,000 entries. For each listed
-        path the server additionally reads that file's header block (bounded,
-        from the person's repository, nothing stored) to fill `summary`.
-        Exactly one of `summary` or `unreadable` is present on every item this
-        operation returns from schema 2.15.0 on: `summary` when the header
-        parses, `unreadable` (with a closed `reason`) when it does not or the
-        file exceeds the read bound. `kind` comes from the header's own
-        `kind` when `summary` is present, and from which declared content
-        root the path is under (ARTICLE for `content/articles/`, PAGE for
-        `content/pages/`) when it is not. `limit` defaults to 50 here (the
-        shared default is 25) because a content list row needs more per
-        round trip than most lists; the server may return fewer items than
-        `limit` even when more are available. `setUp` reports whether
-        `gala/repository.json` is present on main, matching
-        `GET .../repository/setup`'s `state`. `publication` is read from the
-        settings files
+  /v2/organizations/{organizationId}/publications/{publicationId}/configuration-changes:plan:
+    post:
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlan
+      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:
+                  changeKind: PORTABLE_SETTINGS
+                  expectedHead: sha1:0000000000000000000000000000000000000000
+                  inputDigest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlanRequest"
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    changeId: 018f0000-0000-7000-8000-000000000001
+                    diffDigest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+                    expectedHead: sha1:0000000000000000000000000000000000000000
+                    state: REQUESTED
+                    version: 0
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlanResponse"
+          description: plan typed publication or module configuration diff against exact Git head succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Location:
+              $ref: "#/components/headers/Location"
+            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
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_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:
+                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
+                INVALID_SOURCE_STATE:
+                  summary: INVALID_SOURCE_STATE
+                  value:
+                    code: INVALID_SOURCE_STATE
+                    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: INVALID_SOURCE_STATE
+                    type: urn:gala:problem:invalid-source-state
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, INVALID_SOURCE_STATE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - INVALID_SOURCE_STATE
+        "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
+        "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
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: CAPABILITY_UNAVAILABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - CAPABILITY_UNAVAILABLE
+      security:
+        - browserSession: []
+      summary: plan typed publication or module configuration diff against exact Git head
+      tags:
+        - organizations
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - Current expected Git head, active binding epoch, and admitted typed configuration contract
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: expected-git-head-and-binding-epoch
+      x-gala-conditional-capabilities:
+        - capabilityKey: publication.modules.manage
+          when: changeKind == MODULES
+        - capabilityKey: publication.policy.manage
+          when: changeKind == POLICY
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: plan typed publication or module configuration diff against exact Git head
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - CAPABILITY_UNAVAILABLE
+        - COMMAND_REPLAY_CONFLICT
+        - INVALID_SOURCE_STATE
+        - REQUEST_FIELD_UNKNOWN
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - Publication:ACTIVE
+        - RepositoryBinding:ACTIVE
+        - RepositoryChange:REQUESTED -> PLANNED
+      x-gala-success-category: create
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/content:
+    get:
+      description: |
+        One git-trees read per declared content root at the linked repository's
+        current main branch head, bounded at 2,000 entries. For each listed
+        path the server additionally reads that file's header block (bounded,
+        from the person's repository, nothing stored) to fill `summary`.
+        Exactly one of `summary` or `unreadable` is present on every item this
+        operation returns from schema 2.15.0 on: `summary` when the header
+        parses, `unreadable` (with a closed `reason`) when it does not or the
+        file exceeds the read bound. `kind` comes from the header's own
+        `kind` when `summary` is present, and from which declared content
+        root the path is under (ARTICLE for `content/articles/`, PAGE for
+        `content/pages/`) when it is not. `limit` defaults to 50 here (the
+        shared default is 25) because a content list row needs more per
+        round trip than most lists; the server may return fewer items than
+        `limit` even when more are available. `setUp` reports whether
+        `gala/repository.json` is present on main, matching
+        `GET .../repository/setup`'s `state`. `publication` is read from the
+        settings files
         (`gala/repository.json`, `gala/appearance.json`, `gala/authors/`) at
         this same main-branch head, and is returned on every page of the
         inventory, not only the first, so the editor has these facts
@@ -22594,6 +23383,8 @@ paths:
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
   /v2/organizations/{organizationId}/publications/{publicationId}/deployments:rollback:
     post:
+      description: |
+        Also the restore operation of the history read: `generationId` is a history entry's `versionId`. Only a generation that went live is accepted; any other generation is `409 INVALID_SOURCE_STATE`. A restore is recorded in `GET .../history` as an entry with `outcome: RESTORED`. Clients pass a short `reasonCode` such as `RESTORE_FROM_HISTORY`.
       operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDeploymentsRollback
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -23349,127 +24140,317 @@ paths:
                     type: urn:gala:problem:invalid-source-state
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: COMMAND_REPLAY_CONFLICT, INVALID_SOURCE_STATE
+          description: COMMAND_REPLAY_CONFLICT, INVALID_SOURCE_STATE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - INVALID_SOURCE_STATE
+        "412":
+          content:
+            application/problem+json:
+              examples:
+                STALE_AGGREGATE_VERSION:
+                  summary: STALE_AGGREGATE_VERSION
+                  value:
+                    code: STALE_AGGREGATE_VERSION
+                    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: 412
+                    title: STALE_AGGREGATE_VERSION
+                    type: urn:gala:problem:stale-aggregate-version
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: STALE_AGGREGATE_VERSION
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - STALE_AGGREGATE_VERSION
+        "422":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: Region is not one row of the accepted region catalog. See the operation contract for the served/staging-bucket-equal and forbidden-providerBinding variants of this problem.
+                    errors:
+                      - code: VALIDATION_FAILED
+                        pointer: /providerBinding/region
+                    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
+        "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
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: CAPABILITY_UNAVAILABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - CAPABILITY_UNAVAILABLE
+      security:
+        - browserSession: []
+      summary: set publication destination
+      tags:
+        - organizations
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - Accepted region catalog membership, globally unique Spaces bucket names, and an unlocked destination
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: if-match
+      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: set publication destination
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - CAPABILITY_UNAVAILABLE
+        - COMMAND_REPLAY_CONFLICT
+        - INVALID_SOURCE_STATE
+        - REQUEST_FIELD_UNKNOWN
+        - RESOURCE_NOT_FOUND
+        - STALE_AGGREGATE_VERSION
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - Publication:PROVISIONING|ACTIVE|PAUSED
+        - PublicationDestination:UNSET|SET
+      x-gala-success-category: update
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/history:
+    get:
+      description: |
+        Versions of the site that went live, newest first, on a stable keyset cursor, each described by who published it, when, and what changed in words. A failed attempt is never an entry of its own: failed attempts since the previous entry are folded into the next entry that went live as `failedAttemptsBefore`. Only when the latest attempt failed is there one trailing entry with `outcome: FAILED` (the first entry in the list), carrying `failure.reasonCode` and `failure.retryable` and no `versionId`.
+
+        `versionId` is the deployment generation id. To restore a version call `POST .../deployments:rollback` with `generationId` set to `versionId`; no separate restore operation exists. Only a version that went live is accepted; any other generation is `409 INVALID_SOURCE_STATE`.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdHistory
+      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/Cursor"
+        - $ref: "#/components/parameters/Limit"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    hasMore: false
+                    items:
+                      - actor:
+                          displayName: Asha Rao
+                        at: "2026-10-05T09:30:00Z"
+                        changes:
+                          - action: EDIT
+                            kind: POST
+                            path: content/articles/hello.md
+                            title: Hello, world
+                        failedAttemptsBefore:
+                          count: 1
+                          lastReason: BUILD_FAILED
+                        outcome: LIVE
+                        versionId: 018f0000-0000-7000-8000-000000000001
+              schema:
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdHistoryResponse"
+          description: list the versions of this publication that went live succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          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: 400
+                    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:
-            - COMMAND_REPLAY_CONFLICT
-            - INVALID_SOURCE_STATE
-        "412":
+            - VALIDATION_FAILED
+        "401":
           content:
             application/problem+json:
               examples:
-                STALE_AGGREGATE_VERSION:
-                  summary: STALE_AGGREGATE_VERSION
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
                   value:
-                    code: STALE_AGGREGATE_VERSION
+                    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: 412
-                    title: STALE_AGGREGATE_VERSION
-                    type: urn:gala:problem:stale-aggregate-version
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: STALE_AGGREGATE_VERSION
+          description: AUTHENTICATION_REQUIRED
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
-            - STALE_AGGREGATE_VERSION
-        "422":
+            - AUTHENTICATION_REQUIRED
+        "403":
           content:
             application/problem+json:
               examples:
-                VALIDATION_FAILED:
-                  summary: VALIDATION_FAILED
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
                   value:
-                    code: VALIDATION_FAILED
+                    code: AUTHORIZATION_DENIED
                     correlationId: 018f0000-0000-7000-8000-000000000001
-                    detail: Region is not one row of the accepted region catalog. See the operation contract for the served/staging-bucket-equal and forbidden-providerBinding variants of this problem.
-                    errors:
-                      - code: VALIDATION_FAILED
-                        pointer: /providerBinding/region
+                    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
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: VALIDATION_FAILED
+          description: AUTHORIZATION_DENIED
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
-            - VALIDATION_FAILED
-        "503":
+            - AUTHORIZATION_DENIED
+        "404":
           content:
             application/problem+json:
               examples:
-                CAPABILITY_UNAVAILABLE:
-                  summary: CAPABILITY_UNAVAILABLE
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
                   value:
-                    code: CAPABILITY_UNAVAILABLE
+                    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: 503
-                    title: CAPABILITY_UNAVAILABLE
-                    type: urn:gala:problem:capability-unavailable
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: CAPABILITY_UNAVAILABLE
+          description: RESOURCE_NOT_FOUND
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
-            - CAPABILITY_UNAVAILABLE
+            - RESOURCE_NOT_FOUND
       security:
         - browserSession: []
-      summary: set publication destination
+      summary: list the versions of this publication that went live
       tags:
         - organizations
       x-gala-activation-gate: MVP
       x-gala-activation-guards:
-        - Accepted region catalog membership, globally unique Spaces bucket names, and an unlocked destination
-      x-gala-capability-key: publication.settings.manage
-      x-gala-concurrency: if-match
+        - 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: set publication destination
+      x-gala-purpose: list the versions of this publication that went live
       x-gala-reachable-problems:
         - AUTHENTICATION_REQUIRED
         - AUTHORIZATION_DENIED
-        - CAPABILITY_UNAVAILABLE
-        - COMMAND_REPLAY_CONFLICT
-        - INVALID_SOURCE_STATE
-        - REQUEST_FIELD_UNKNOWN
         - RESOURCE_NOT_FOUND
-        - STALE_AGGREGATE_VERSION
         - VALIDATION_FAILED
-      x-gala-replay-identity: idempotency-key
+      x-gala-replay-identity: safe-query
       x-gala-state-guards:
-        - Publication:PROVISIONING|ACTIVE|PAUSED
-        - PublicationDestination:UNSET|SET
-      x-gala-success-category: update
+        - NONE
+      x-gala-success-category: query
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
   /v2/organizations/{organizationId}/publications/{publicationId}/publishes:
     post:
@@ -27877,6 +28858,8 @@ paths:
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
   /v2/organizations/{organizationId}/publications/{publicationId}/reviews/{reviewId}:decide:
     post:
+      description: |
+        The in-Galascribe approval. `APPROVE` approves; `REJECT` is the request-changes decision shown to people as "changes requested". When the publication's `publishingPolicy.galascribeMerges` is true (the default), approving also triggers the merge of the change's pull request through the GitHub App; the pull request is a mirror of the decision, not a second approval. `reviewId` for a pending change is `pendingChanges[].reviewId` of `GET .../site`.
       operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdReviewsByReviewIdDecide
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -28216,6 +29199,209 @@ paths:
         - Review:REQUESTED -> APPROVED|REJECTED
       x-gala-success-category: update
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/site:
+    get:
+      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 `PREPARING`, `BUILDING`, `GOING_LIVE`. Read from the platform's own records; nothing is read from the person's repository.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdSite
+      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
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    attention:
+                      - code: REPOSITORY_NEEDS_UPDATE
+                        relatedChangeId: 018f0000-0000-7000-8000-000000000002
+                    lastPublished:
+                      actor:
+                        displayName: Asha Rao
+                      at: "2026-10-05T09:30:00Z"
+                    pendingChanges:
+                      - action: EDIT
+                        author:
+                          displayName: Asha Rao
+                        changeId: 018f0000-0000-7000-8000-000000000002
+                        kind: POST
+                        path: content/articles/hello.md
+                        review: NOT_REQUIRED
+                        title: Hello, world
+                        updatedAt: "2026-10-05T09:30:00Z"
+                      - action: CHANGE
+                        author:
+                          displayName: Asha Rao
+                        changeId: 018f0000-0000-7000-8000-000000000003
+                        kind: LOOK
+                        review: NOT_REQUIRED
+                        theme:
+                          from: Default
+                          to: Journal
+                        title: Look
+                        updatedAt: "2026-10-05T09:30:00Z"
+                    state: LIVE
+                    url: https://example.galascribe.com/
+              schema:
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdSiteResponse"
+          description: read the site summary of this publication succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          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: 400
+                    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
+        "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
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_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
+      security:
+        - browserSession: []
+      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}:previewRetirement:
     post:
       description: |