@rathnasgala2/schemas 2.20.3 → 2.22.0

package/openapi/openapi.yaml

@@ -234,6 +234,24 @@ components:
         - activationDetectionPlanDigest
         - activationDetectionObservation
       type: object
+    AppearanceColorMode:
+      enum:
+        - light
+        - dark
+        - system
+      type: string
+    AppearanceThemeId:
+      description: |
+        The closed catalog of themes the server can select. `default` names
+        `@rathnasgala2/theme-default`, `amaze` names
+        `@rathnasgala2/theme-amaze`, and so on.
+      enum:
+        - default
+        - amaze
+        - flashy
+        - minimal
+        - zebra
+      type: string
     AuthenticatorState:
       enum:
         - ACTIVE
@@ -291,6 +309,20 @@ components:
         - kind
         - label
       type: object
+    ContentChangeAppearanceEntry:
+      additionalProperties: false
+      description: |
+        The theme selection inside a batch `content-changes:plan` request.
+        Both members are required.
+      properties:
+        colorModeDefault:
+          $ref: "#/components/schemas/AppearanceColorMode"
+        themeId:
+          $ref: "#/components/schemas/AppearanceThemeId"
+      required:
+        - themeId
+        - colorModeDefault
+      type: object
     ContentChangeAssetEntry:
       additionalProperties: false
       allOf:
@@ -1109,6 +1141,40 @@ components:
         - state
         - operationId
       type: object
+    GetOrganizationsByOrganizationIdPublicationsByPublicationIdAppearanceResponse:
+      additionalProperties: false
+      properties:
+        built:
+          oneOf:
+            - $ref: "#/components/schemas/PublicationAppearanceBuilt"
+            - type: "null"
+        catalog:
+          items:
+            $ref: "#/components/schemas/PublicationAppearanceCatalogEntry"
+          maxItems: 5
+          type: array
+        consistent:
+          type: boolean
+        head:
+          pattern: ^(?:sha1:[0-9a-f]{40}|sha256:[0-9a-f]{64})$
+          type: string
+        openChange:
+          oneOf:
+            - $ref: "#/components/schemas/PublicationAppearanceOpenChange"
+            - type: "null"
+        selected:
+          $ref: "#/components/schemas/PublicationAppearanceSelected"
+        setUp:
+          type: boolean
+      required:
+        - head
+        - setUp
+        - selected
+        - built
+        - consistent
+        - catalog
+        - openChange
+      type: object
     GetOrganizationsByOrganizationIdPublicationsByPublicationIdContentDocumentsResponse:
       additionalProperties: false
       properties:
@@ -1446,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:
@@ -1578,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
@@ -1643,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:
@@ -2165,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:
@@ -3454,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
@@ -3471,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
@@ -9765,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
@@ -9850,12 +10190,20 @@ components:
         Two request shapes, both accepted. The 2.13.0 single-document shape
         (`path`, `contentDigest`, `expectedHead`) plans one document write
         against the exact expected head. The additive batch shape
-        (`baseRevision` and at least one of `documents`/`assets`) plans up
-        to 20 documents and 40 assets -- each `PUT` with its own text or
-        bytes and digest, each `DELETE` naming only its path -- in one
-        change, against the exact expected main-branch head asserted as
-        `baseRevision`. A request mixing the two shapes, or a batch request
-        naming neither `documents` nor `assets`, is `422 VALIDATION_FAILED`.
+        (`baseRevision` and at least one of `documents`/`assets`/`appearance`)
+        plans up to 20 documents and 40 assets -- each `PUT` with its own
+        text or bytes and digest, each `DELETE` naming only its path -- and
+        optionally one theme selection in one change, against the exact
+        expected main-branch head asserted as `baseRevision`. A request
+        mixing the two shapes, or a batch request naming none of
+        `documents`, `assets` and `appearance`, is `422 VALIDATION_FAILED`.
+        `appearance` names a catalog theme and a default colour mode; the
+        server writes `gala/appearance.json` (only `theme` and
+        `colorMode.default` change, every other member is preserved) and the
+        `gala.lock.json` `theme` block from its closed theme catalog, both
+        in the same change. An `appearance` equal to the current selection
+        is `422 VALIDATION_FAILED` pointed at `/appearance`. Document paths
+        under `gala/` and `gala.lock.json` remain forbidden.
         The change's total serialized size must not exceed 100 MiB;
         `assets[].bytesBase64` is base64 over raw bytes, so what counts
         against the per-asset and 100 MiB per-change bounds is the decoded
@@ -9863,6 +10211,8 @@ components:
         category: image 5 MiB, sound 20 MiB, video 50 MiB (documents are
         unchanged since 2.14.0: 20 documents, 1 MiB text each).
       properties:
+        appearance:
+          $ref: "#/components/schemas/ContentChangeAppearanceEntry"
         assets:
           items:
             $ref: "#/components/schemas/ContentChangeAssetEntry"
@@ -10920,37 +11270,119 @@ components:
       type: object
     Problem:
       $ref: "#/components/schemas/PortableProblemDocument"
-    PublicationState:
-      enum:
-        - PROVISIONING
-        - ACTIVE
-        - PAUSED
-        - RETIRING
-        - RETIRED
-      type: string
-    PublicationSummary:
+    PublicationAppearanceBuilt:
       additionalProperties: false
+      description: |
+        From the `theme` block of `gala.lock.json`, the sole authority for the
+        theme a build uses. `themeId` is `null` when the locked package is not
+        in the catalog.
       properties:
-        name:
-          maxLength: 80
+        themeId:
+          oneOf:
+            - $ref: "#/components/schemas/AppearanceThemeId"
+            - type: "null"
+        themePackage:
+          maxLength: 214
           minLength: 1
           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}$
+        version:
+          maxLength: 256
+          minLength: 1
           type: string
-        slug:
+      required:
+        - themeId
+        - themePackage
+        - version
+      type: object
+    PublicationAppearanceCatalogEntry:
+      additionalProperties: false
+      properties:
+        description:
+          maxLength: 280
+          minLength: 1
+          type: string
+        displayName:
           maxLength: 80
           minLength: 1
           type: string
-        state:
-          $ref: "#/components/schemas/PublicationState"
+        package:
+          maxLength: 214
+          minLength: 1
+          type: string
+        themeId:
+          $ref: "#/components/schemas/AppearanceThemeId"
         version:
-          format: int64
-          minimum: 0
-          type: integer
+          maxLength: 256
+          minLength: 1
+          type: string
       required:
-        - publicationId
+        - themeId
+        - package
+        - version
+        - displayName
+        - description
+      type: object
+    PublicationAppearanceOpenChange:
+      additionalProperties: false
+      properties:
+        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
+      required:
+        - changeId
+      type: object
+    PublicationAppearanceSelected:
+      additionalProperties: false
+      description: |
+        From `gala/appearance.json`. `themeId` is `null` ("Custom theme") when
+        `themePackage` is not in the catalog. `themePackage` is the file's
+        `theme` value, a package with its version range.
+      properties:
+        colorModeDefault:
+          $ref: "#/components/schemas/AppearanceColorMode"
+        themeId:
+          oneOf:
+            - $ref: "#/components/schemas/AppearanceThemeId"
+            - type: "null"
+        themePackage:
+          $ref: "#/components/schemas/PortableAppearancePackageRange"
+      required:
+        - themeId
+        - themePackage
+        - colorModeDefault
+      type: object
+    PublicationState:
+      enum:
+        - PROVISIONING
+        - ACTIVE
+        - PAUSED
+        - RETIRING
+        - RETIRED
+      type: string
+    PublicationSummary:
+      additionalProperties: false
+      properties:
+        name:
+          maxLength: 80
+          minLength: 1
+          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
+        slug:
+          maxLength: 80
+          minLength: 1
+          type: string
+        state:
+          $ref: "#/components/schemas/PublicationState"
+        version:
+          format: int64
+          minimum: 0
+          type: integer
+      required:
+        - publicationId
         - version
         - state
         - name
@@ -10963,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:
@@ -12106,6 +12552,166 @@ components:
         - lastSeenAt
         - current
       type: object
+    SiteActor:
+      additionalProperties: false
+      description: A person named in words. The identity is the display name; no principal id is exposed on this surface.
+      properties:
+        displayName:
+          maxLength: 200
+          minLength: 1
+          type: string
+      required:
+        - displayName
+      type: object
+    SiteAttentionItem:
+      additionalProperties: false
+      description: Something that needs a person to act. The list is empty when nothing does.
+      properties:
+        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
+      required:
+        - code
+      type: object
+    SiteLastPublished:
+      additionalProperties: false
+      properties:
+        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:
@@ -19530,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"
@@ -19834,9 +20442,23 @@ paths:
         - Publication:RETIRING|RETIRED -> PROVISIONING
       x-gala-success-category: update
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
-  /v2/organizations/{organizationId}/publications/{publicationId}/configuration-changes:plan:
-    post:
-      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlan
+  /v2/organizations/{organizationId}/publications/{publicationId}/appearance:
+    get:
+      description: |
+        Reads this publication's theme selection at the linked repository's
+        current main branch head: `selected` from `gala/appearance.json`
+        (`theme`, `colorMode.default`), `built` from the `theme` block of
+        `gala.lock.json`, and the closed five-theme `catalog` the server can
+        write. `selected.themeId` and `built.themeId` are `null` when that
+        file names a package outside the catalog ("Custom theme").
+        `consistent` is true when `selected` and `built` name the same
+        package. `setUp` matches `GET .../repository/setup`'s `state`.
+        `openChange` names an existing not-yet-published repository change
+        of this publication that touches appearance, or is `null`, so a
+        client links to it instead of planning a second one. The browser
+        never reads or edits `gala/appearance.json` or `gala.lock.json` as
+        text; `GET .../content/documents` still refuses both paths.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdAppearance
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
         - example: 018f0000-0000-7000-8000-000000000001
@@ -19855,61 +20477,44 @@ paths:
             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":
+        "200":
           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
+                    built:
+                      themeId: default
+                      themePackage: "@rathnasgala2/theme-default"
+                      version: 2.0.0
+                    catalog:
+                      - description: The calm default look.
+                        displayName: Default
+                        package: "@rathnasgala2/theme-default"
+                        themeId: default
+                        version: 2.0.0
+                    consistent: true
+                    head: sha1:0000000000000000000000000000000000000000
+                    openChange: null
+                    selected:
+                      colorModeDefault: system
+                      themeId: default
+                      themePackage: "@rathnasgala2/theme-default@^2.0.0"
+                    setUp: true
               schema:
-                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlanResponse"
-          description: plan typed publication or module configuration diff against exact Git head succeeded
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdAppearanceResponse"
+          description: read this publication's theme selection at the main branch 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:
@@ -19925,14 +20530,13 @@ paths:
                     type: urn:gala:problem:validation-failed
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: REQUEST_FIELD_UNKNOWN, VALIDATION_FAILED
+          description: 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:
@@ -20015,66 +20619,683 @@ paths:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
             - RESOURCE_NOT_FOUND
-        "409":
+        "429":
           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
+                RATE_LIMITED:
+                  summary: RATE_LIMITED
                   value:
-                    code: INVALID_SOURCE_STATE
+                    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: 409
-                    title: INVALID_SOURCE_STATE
-                    type: urn:gala:problem:invalid-source-state
+                    status: 429
+                    title: RATE_LIMITED
+                    type: urn:gala:problem:rate-limited
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: COMMAND_REPLAY_CONFLICT, INVALID_SOURCE_STATE
+          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:
-            - COMMAND_REPLAY_CONFLICT
-            - INVALID_SOURCE_STATE
-        "422":
+            - RATE_LIMITED
+        "503":
           content:
             application/problem+json:
               examples:
-                VALIDATION_FAILED:
-                  summary: VALIDATION_FAILED
+                CAPABILITY_UNAVAILABLE:
+                  summary: CAPABILITY_UNAVAILABLE
                   value:
-                    code: VALIDATION_FAILED
+                    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: 422
-                    title: VALIDATION_FAILED
-                    type: urn:gala:problem:validation-failed
-              schema:
-                $ref: "#/components/schemas/Problem"
+                    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: read this publication's theme selection at the main branch head
+      tags:
+        - organizations
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - Active repository binding and configured GitHub App identity capability
+      x-gala-capability-key: publication.view
+      x-gala-concurrency: binding-epoch
+      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 this publication's theme selection at the main branch head
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - CAPABILITY_UNAVAILABLE
+        - DEPENDENCY_UNAVAILABLE
+        - RATE_LIMITED
+        - 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}/changes:publish:
+    post:
+      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
+          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:
+                  changeIds:
+                    - 018f0000-0000-7000-8000-000000000001
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublishRequest"
+        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/PostOrganizationsByOrganizationIdPublicationsByPublicationIdChangesPublishResponse"
+          description: publish a batch of changes with one deploy of the resulting main head 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
+              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: "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
+                    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-Current-Head:
+              $ref: "#/components/headers/XGalaCurrentHead"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - INVALID_SOURCE_STATE
+        "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 a batch of changes with one deploy of the resulting main head
+      tags:
+        - organizations
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - 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.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: 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
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - Publication:ACTIVE
+        - RepositoryBinding:ACTIVE
+        - 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}/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:
@@ -22162,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"
@@ -22917,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:
@@ -27445,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"
@@ -27784,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: |