npm - @rathnasgala2/schemas - Versions diffs - 3.4.0 → 3.6.0 - Mend

@rathnasgala2/schemas 3.4.0 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/THIRD_PARTY_LICENSES.json +1 -1
package/docs/catalogs/app-components.json +2 -2
package/docs/catalogs/app-routes.json +7 -2
package/docs/catalogs/schema-inventory.json +2 -2
package/openapi/http-catalog.json +62 -2
package/openapi/openapi.yaml +1653 -47
package/package.json +1 -1
package/sbom.cdx.json +23 -23

package/openapi/openapi.yaml CHANGED Viewed

@@ -1256,6 +1256,176 @@ components:
         - RECONCILING
         - INCONCLUSIVE
       type: string
+    DnsConnection:
+      additionalProperties: false
+      description: One attempt to add or remove a domain's DNS records at the person's DNS provider (SCHEMA-3.5.0). `outcome` is present when `phase` is `CANCELLED`, `FAILED` or `EXPIRED`; `plan` when `NEEDS_CONFIRMATION` or `APPLIED`; `applied` when `APPLIED`. The provider's access is used within one request chain (or held encrypted for at most `expiresAt` on `NEEDS_CONFIRMATION`) and revoked afterwards; Galascribe keeps none.
+      properties:
+        applied:
+          additionalProperties: false
+          properties:
+            at:
+              $ref: "#/components/schemas/PortableProblemRfc3339"
+            created:
+              minimum: 0
+              type: integer
+            deleted:
+              minimum: 0
+              type: integer
+            replaced:
+              minimum: 0
+              type: integer
+          required:
+            - at
+            - created
+            - replaced
+            - deleted
+          type: object
+        connectionId:
+          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
+        createdAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        intent:
+          $ref: "#/components/schemas/DnsIntent"
+        outcome:
+          additionalProperties: false
+          properties:
+            code:
+              $ref: "#/components/schemas/DnsConnectionOutcomeCode"
+            detail:
+              maxLength: 500
+              minLength: 1
+              type: string
+          required:
+            - code
+            - detail
+          type: object
+        phase:
+          $ref: "#/components/schemas/DnsConnectionPhase"
+        plan:
+          items:
+            $ref: "#/components/schemas/DnsPlanEntry"
+          maxItems: 32
+          minItems: 0
+          type: array
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+        zone:
+          additionalProperties: false
+          properties:
+            accountName:
+              maxLength: 255
+              minLength: 1
+              type: string
+            name:
+              maxLength: 253
+              minLength: 1
+              type: string
+          required:
+            - name
+            - accountName
+          type: object
+      required:
+        - connectionId
+        - provider
+        - intent
+        - phase
+        - createdAt
+        - expiresAt
+      type: object
+    DnsConnectionOutcomeCode:
+      description: "Why a connection ended without success: `CANCELLED` (consent denied or plan discarded); `ZONE_NOT_FOUND` (the domain is not in the provider account chosen); `ZONE_AMBIGUOUS` (more than one active zone of that name across the accounts granted); `SCOPE_DECLINED` (the person did not grant what was needed); `PROVIDER_FAILED` (the provider failed or refused); `STATE_INVALID` (the return from the provider could not be matched to this connection); `EXPIRED`."
+      enum:
+        - CANCELLED
+        - ZONE_NOT_FOUND
+        - ZONE_AMBIGUOUS
+        - SCOPE_DECLINED
+        - PROVIDER_FAILED
+        - STATE_INVALID
+        - EXPIRED
+      type: string
+    DnsConnectionPhase:
+      description: "`STARTED` (waiting for the person at the provider); `NEEDS_CONFIRMATION` (something would be replaced, nothing touched yet); `APPLIED`; `CANCELLED` (the person declined, or discarded the plan); `FAILED`; `EXPIRED` (the person did not finish in time)."
+      enum:
+        - STARTED
+        - NEEDS_CONFIRMATION
+        - APPLIED
+        - CANCELLED
+        - FAILED
+        - EXPIRED
+      type: string
+    DnsIntent:
+      description: "`ADD` writes the domain's records at the provider; `REMOVE` deletes only the records whose values are Galascribe's targets, never anything else at that name; `PROXY` (SCHEMA-3.6.0) turns the provider's proxy on for exactly the records Galascribe wrote, and is offered only once the domain is live with an issued certificate."
+      enum:
+        - ADD
+        - REMOVE
+        - PROXY
+      type: string
+    DnsPlanAction:
+      description: "`CREATE` a record that is not there; `KEEP` one already identical; `REPLACE` one of the same type, or a CNAME where an A/AAAA must go (or the reverse), that differs; `DELETE` a record carrying a Galascribe target value (`REMOVE` only); `PROXY_ON` (SCHEMA-3.6.0, `PROXY` only) the record exists DNS-only and will be set to proxied."
+      enum:
+        - CREATE
+        - KEEP
+        - REPLACE
+        - DELETE
+        - PROXY_ON
+      type: string
+    DnsPlanEntry:
+      additionalProperties: false
+      description: "One record in a connection's plan. `record` is what Galascribe wants at that name; `existing` is what the provider has there now (absent for `CREATE`). Records are always written DNS-only (`proxied: false`) so GitHub can issue the certificate."
+      properties:
+        action:
+          $ref: "#/components/schemas/DnsPlanAction"
+        existing:
+          additionalProperties: false
+          properties:
+            proxied:
+              type: boolean
+            type:
+              maxLength: 16
+              minLength: 1
+              pattern: ^[A-Z][A-Z0-9]*$
+              type: string
+            value:
+              maxLength: 4096
+              minLength: 1
+              type: string
+          required:
+            - type
+            - value
+            - proxied
+          type: object
+        record:
+          $ref: "#/components/schemas/DomainDnsRecord"
+      required:
+        - action
+        - record
+      type: object
+    DnsProvider:
+      description: Where a domain's DNS records live. `CLOUDFLARE` today; a further provider is an additive value.
+      enum:
+        - CLOUDFLARE
+      type: string
+    DnsProviderOffer:
+      additionalProperties: false
+      description: A provider this environment can connect to for this binding, and what it can do now.
+      properties:
+        intents:
+          items:
+            $ref: "#/components/schemas/DnsIntent"
+          maxItems: 3
+          minItems: 1
+          type: array
+          uniqueItems: true
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+      required:
+        - provider
+        - intents
+      type: object
     DomainBinding:
       additionalProperties: false
       description: A custom domain on GitHub Pages for one publication (SCHEMA-3.3.0). `dns.records` are exactly the records to add at the registrar (a CNAME to `<owner>.github.io` for a subdomain; GitHub's four A and four AAAA records for an apex). Galascribe checks DNS before it sets the Pages custom domain, then waits for GitHub's certificate and routing; `ACTIVE` proposes the change that moves `canonicalBase` to the domain, and the site moves at the next publish. `expiresAt` is set while `OWNERSHIP_PENDING` (7 days).
@@ -1271,6 +1441,13 @@ components:
           properties:
             observed:
               $ref: "#/components/schemas/DomainDnsObservation"
+            providers:
+              description: The DNS providers Galascribe can connect to for this binding right now (SCHEMA-3.5.0). Present only when the provider is configured in this environment and the binding's state has records to add, or (`REMOVE`) to remove. A client shows a connect button exactly when this names the provider and intent; it never decides from `nextStep`.
+              items:
+                $ref: "#/components/schemas/DnsProviderOffer"
+              maxItems: 4
+              minItems: 0
+              type: array
             records:
               items:
                 $ref: "#/components/schemas/DomainDnsRecord"
@@ -1297,6 +1474,18 @@ components:
           $ref: "#/components/schemas/DomainKind"
         nextStep:
           $ref: "#/components/schemas/DomainNextStep"
+        proxy:
+          additionalProperties: false
+          description: Present once Galascribe turned the provider's proxy on for this binding through a connection (SCHEMA-3.6.0). Absent while the records are DNS-only.
+          properties:
+            provider:
+              $ref: "#/components/schemas/DnsProvider"
+            since:
+              $ref: "#/components/schemas/PortableProblemRfc3339"
+          required:
+            - provider
+            - since
+          type: object
         routing:
           $ref: "#/components/schemas/DomainRouting"
         state:
@@ -1372,11 +1561,13 @@ components:
         expiresAt:
           $ref: "#/components/schemas/PortableProblemRfc3339"
         state:
+          description: "`PROXIED` (SCHEMA-3.6.0): the provider's edge terminates TLS; GitHub's own certificate is not renewed while proxied."
           enum:
             - NONE
             - PENDING
             - ISSUED
             - ERRORED
+            - PROXIED
           type: string
       required:
         - state
@@ -1400,9 +1591,13 @@ components:
           minLength: 1
           type: string
         pointsToGithub:
+          description: True when the hostname resolves to GitHub Pages. It stays false while the binding is proxied, because the name then resolves to the provider's proxy; `viaProxy` carries that case.
           type: boolean
         resolves:
           type: boolean
+        viaProxy:
+          description: True when the hostname resolves to the provider's proxy rather than to GitHub and the binding is proxied (`proxy` is present); the routing probe is then the proof of life (SCHEMA-3.6.0). Absent when the binding is not proxied.
+          type: boolean
       required:
         - resolves
         - pointsToGithub
@@ -1439,7 +1634,7 @@ components:
       type: string
     DomainNextStep:
       additionalProperties: false
-      description: What is being waited on, or what the author should do next. Known codes include `ADD_DNS_RECORDS`, `WAIT_FOR_DNS`, `WAIT_FOR_CERTIFICATE`, `WAIT_FOR_ROUTING`, `PUBLISH_TO_SWITCH`, `FIX_DNS_RECORD`, `REMOVE_DNS_RECORDS` and `NONE`; a client shows `detail` for codes it does not know.
+      description: What is being waited on, or what the author should do next. Known codes include `ADD_DNS_RECORDS`, `WAIT_FOR_DNS`, `WAIT_FOR_CERTIFICATE`, `WAIT_FOR_ROUTING`, `PUBLISH_TO_SWITCH`, `FIX_DNS_RECORD`, `REMOVE_DNS_RECORDS`, `TURN_ON_CLOUDFLARE_PROXY` (SCHEMA-3.6.0, the certificate is issued and the author may let Cloudflare proxy the site) and `NONE`; a client shows `detail` for codes it does not know.
       properties:
         code:
           maxLength: 80
@@ -2340,6 +2535,9 @@ components:
         - version
         - state
       type: object
+    GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
     GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdResponse:
       allOf:
         - $ref: "#/components/schemas/DomainBinding"
@@ -11569,6 +11767,10 @@ components:
             - REAUTH
             - RECOVERY
           type: string
+        selectAccount:
+          default: false
+          description: Ask GitHub to show its account picker (`prompt=select_account`) instead of reusing the browser's GitHub session (SCHEMA-3.6.0).
+          type: boolean
       required:
         - purpose
       type: object
@@ -12450,6 +12652,44 @@ components:
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDetachResponse:
       allOf:
         - $ref: "#/components/schemas/DomainBinding"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApplyResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscardResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsRequest:
+      additionalProperties: false
+      properties:
+        intent:
+          $ref: "#/components/schemas/DnsIntent"
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+      required:
+        - provider
+        - intent
+      type: object
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsResponse:
+      additionalProperties: false
+      properties:
+        authorizationUrl:
+          description: The provider's consent address. A client navigates to it only when it is an `https` address on the provider's own host.
+          format: uri
+          maxLength: 4096
+          minLength: 1
+          pattern: ^https://[^\s]+$
+          type: string
+        connectionId:
+          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
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - connectionId
+        - authorizationUrl
+        - expiresAt
+      type: object
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsRequest:
       additionalProperties: false
       properties:
@@ -12906,6 +13146,11 @@ components:
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdReviewsByReviewIdDecideRequest:
       additionalProperties: false
       properties:
+        comment:
+          description: Optional plain-text note from the reviewer, 1 to 4000 characters (SCHEMA-3.6.0). A longer or empty comment is `VALIDATION_FAILED` with pointer `/comment`.
+          maxLength: 4000
+          minLength: 1
+          type: string
         decision:
           enum:
             - APPROVE
@@ -12922,9 +13167,22 @@ components:
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdReviewsByReviewIdDecideResponse:
       additionalProperties: false
       properties:
+        comment:
+          description: The newest decision's reviewer comment (SCHEMA-3.6.0). Absent when the decision carried none.
+          maxLength: 4000
+          minLength: 1
+          type: string
+        decidedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        decidedBy:
+          $ref: "#/components/schemas/SiteActor"
         findingsDigest:
           pattern: ^sha256:[0-9a-f]{64}$
           type: string
+        requestedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        requestedBy:
+          $ref: "#/components/schemas/SiteActor"
         reviewId:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
@@ -15615,9 +15873,22 @@ components:
         review read returns, so a list row and a read of that row never
         disagree.
       properties:
+        comment:
+          description: The newest decision's reviewer comment (SCHEMA-3.6.0). Absent when the decision carried none.
+          maxLength: 4000
+          minLength: 1
+          type: string
+        decidedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        decidedBy:
+          $ref: "#/components/schemas/SiteActor"
         findingsDigest:
           pattern: ^sha256:[0-9a-f]{64}$
           type: string
+        requestedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        requestedBy:
+          $ref: "#/components/schemas/SiteActor"
         reviewId:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
@@ -15936,14 +16207,29 @@ components:
           maxLength: 512
           minLength: 1
           type: string
+        pullRequestUrl:
+          description: The mirror of this change on GitHub (SCHEMA-3.6.0), the canonical GitHub pull-request URL, as `GithubPullRequestSummary.url`. Absent until a pull request is recorded.
+          format: uri
+          pattern: ^https://github[.]com/[A-Za-z0-9][A-Za-z0-9-]{0,38}/[A-Za-z0-9_.-]{1,100}/pull/[1-9][0-9]*$
+          type: string
         review:
-          description: "`NOT_REQUIRED` when the publication does not require review; otherwise `WAITING`, `APPROVED` or `CHANGES_REQUESTED`."
+          description: "`NOT_REQUIRED` when the publication does not require review; otherwise `WAITING`, `APPROVED` or `CHANGES_REQUESTED`. `NEEDS_RE_REVIEW` (SCHEMA-3.6.0): the reviewed revision was replaced by a newer one and the author requests review again."
           enum:
             - NOT_REQUIRED
             - WAITING
             - APPROVED
             - CHANGES_REQUESTED
+            - NEEDS_RE_REVIEW
           type: string
+        reviewComment:
+          description: The newest decision's comment (SCHEMA-3.6.0), shown to the author next to the change. Absent when none.
+          maxLength: 4000
+          minLength: 1
+          type: string
+        reviewDecidedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        reviewDecidedBy:
+          $ref: "#/components/schemas/SiteActor"
         reviewId:
           description: The review a reviewer decides through `POST .../reviews/{reviewId}:decide`. Present when a review exists.
           format: uuid
@@ -16791,6 +17077,77 @@ paths:
         - NONE
       x-gala-success-category: protocol
       x-gala-tenant-scope: NONE
+  /v2/callbacks/cloudflare/oauth:
+    get:
+      description: |
+        The address Cloudflare sends the person back to after the consent screen. It never answers with a problem document for what the provider sends: every outcome, including a denied consent or an unknown `state`, is a `303` to the Domain page with `?dns=<connectionId>` (or without it when the connection cannot be identified), and `GET .../dns-connections/{connectionId}` says what happened. `code`, `state`, `error` and `iss` are never logged or echoed. Only a value longer than its limit is refused as `400 VALIDATION_FAILED`, before any connection is touched.
+      operationId: getCallbacksCloudflareOauth
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: example
+          in: query
+          name: code
+          required: false
+          schema:
+            maxLength: 8192
+            minLength: 1
+            type: string
+        - example: example
+          in: query
+          name: state
+          required: false
+          schema:
+            maxLength: 8192
+            minLength: 1
+            type: string
+        - example: example
+          in: query
+          name: error
+          required: false
+          schema:
+            maxLength: 512
+            minLength: 1
+            type: string
+        - example: example
+          in: query
+          name: iss
+          required: false
+          schema:
+            maxLength: 2048
+            minLength: 1
+            type: string
+      responses:
+        "303":
+          description: consume the exact Cloudflare OAuth callback transaction succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Location:
+              $ref: "#/components/headers/Location"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          $ref: "#/components/responses/ValidationFailed"
+      security: []
+      summary: consume the exact Cloudflare OAuth callback transaction
+      tags:
+        - callbacks
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: null
+      x-gala-concurrency: single-use-transaction
+      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: consume the exact Cloudflare OAuth callback transaction
+      x-gala-reachable-problems:
+        - VALIDATION_FAILED
+      x-gala-replay-identity: oauth-state
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: oauth-callback
+      x-gala-tenant-scope: NONE
   /v2/callbacks/github/app:
     post:
       operationId: postCallbacksGithubApp
@@ -32122,13 +32479,11 @@ paths:
         - NONE
       x-gala-success-category: query
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
-  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}:check:
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections:
     post:
       description: |
-        Runs the checks for the binding's current state now (DNS, certificate,
-        routing) instead of waiting for the next automatic check, and returns
-        the binding. At most once a minute per binding (`429 RATE_LIMITED`).
-      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdCheck
+        Starts a connection to the person's DNS provider so Galascribe can add (`ADD`) or remove (`REMOVE`) the domain's DNS records there, and returns the provider's consent address (`authorizationUrl`); the App navigates the whole page to it. The provider sends the person back to the Domain page, where `GET .../dns-connections/{connectionId}` says what happened. Only offered when `dns.providers` on the binding lists the provider and the intent. `409 DNS_CONNECTION_NOT_APPLICABLE` when the binding's state has no records to add or remove; `503 DNS_PROVIDER_NOT_CONFIGURED` when this environment has no connection to that provider; `429 RATE_LIMITED` after one start per domain per minute. The connection is valid until `expiresAt`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnections
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
         - example: 018f0000-0000-7000-8000-000000000001
@@ -32157,58 +32512,56 @@ paths:
             type: string
         - $ref: "#/components/parameters/IdempotencyKey"
         - $ref: "#/components/parameters/XCsrfToken"
+      requestBody:
+        content:
+          application/json:
+            examples:
+              nominal:
+                summary: Nominal valid request
+                value:
+                  intent: ADD
+                  provider: CLOUDFLARE
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsRequest"
+        required: true
       responses:
-        "200":
+        "201":
           content:
             application/json:
               examples:
                 nominal:
                   summary: Nominal successful response
                   value:
-                    canonicalBase:
-                      current: https://rathnastest.github.io/g11/
-                      published: false
-                      target: https://blog.maya.dev/
-                    certificate:
-                      state: PENDING
-                    createdAt: "2026-10-09T12:00:00.000Z"
-                    dns:
-                      observed:
-                        addresses: []
-                        checkedAt: "2026-10-09T12:00:00.000Z"
-                        cnameTarget: rathnastest.github.io
-                        pointsToGithub: true
-                        resolves: true
-                      records:
-                        - name: blog
-                          type: CNAME
-                          value: rathnastest.github.io
-                    domainId: 018f0000-0000-7000-8000-000000000001
-                    expiresAt: "2026-10-16T12:00:00.000Z"
-                    hostname: blog.maya.dev
-                    kind: SUBDOMAIN
-                    nextStep:
-                      code: WAIT_FOR_CERTIFICATE
-                      detail: GitHub is issuing the certificate; this can take up to 24 hours.
-                    routing:
-                      httpsEnforced: false
-                      probeOk: false
-                      servedByPages: false
-                    state: CERTIFICATE_PENDING
-                    updatedAt: "2026-10-09T12:00:00.000Z"
-                    version: 3
+                    authorizationUrl: https://dash.cloudflare.com/oauth2/auth?client_id=example&response_type=code&state=example
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    expiresAt: "2026-10-10T12:10:00.000Z"
               schema:
-                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdCheckResponse"
-          description: check a custom domain now succeeded
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsResponse"
+          description: start adding (or removing) a domain's DNS records at the person's DNS provider 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:
@@ -32224,7 +32577,1245 @@ paths:
                     type: urn:gala:problem:validation-failed
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: VALIDATION_FAILED
+          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
+                DNS_CONNECTION_NOT_APPLICABLE:
+                  summary: DNS_CONNECTION_NOT_APPLICABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_APPLICABLE
+                    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: DNS_CONNECTION_NOT_APPLICABLE
+                    type: urn:gala:problem:dns-connection-not-applicable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_APPLICABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_APPLICABLE
+        "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:
+                DNS_PROVIDER_NOT_CONFIGURED:
+                  summary: DNS_PROVIDER_NOT_CONFIGURED
+                  value:
+                    code: DNS_PROVIDER_NOT_CONFIGURED
+                    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: DNS_PROVIDER_NOT_CONFIGURED
+                    type: urn:gala:problem:dns-provider-not-configured
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_PROVIDER_NOT_CONFIGURED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_PROVIDER_NOT_CONFIGURED
+      security:
+        - browserSession: []
+      summary: start adding (or removing) a domain's DNS records at the person's DNS provider
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      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: start adding (or removing) a domain's DNS records at the person's DNS provider
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_NOT_APPLICABLE
+        - DNS_PROVIDER_NOT_CONFIGURED
+        - RATE_LIMITED
+        - REQUEST_FIELD_UNKNOWN
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: create
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:
+    get:
+      description: |
+        One DNS connection of this domain: where it stands (`phase`), what it will or did change (`plan`, `applied`) and, when it ended without success, why (`outcome`). `NEEDS_CONFIRMATION` means something at the provider would be replaced and nothing has been touched yet: `:apply` writes the plan, `:discard` leaves everything as it was. `404 DNS_CONNECTION_NOT_FOUND` for an unknown connection.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionId
+      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
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          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: connectionId
+          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:
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    phase: NEEDS_CONFIRMATION
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdResponse"
+          description: read a DNS connection 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:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_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: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                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: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - RESOURCE_NOT_FOUND
+      security:
+        - browserSession: []
+      summary: read a DNS connection
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.view
+      x-gala-concurrency: domain-binding-version
+      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 a DNS connection
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - DNS_CONNECTION_NOT_FOUND
+        - 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}/domains/{domainId}/dns-connections/{connectionId}:apply:
+    post:
+      description: |
+        Writes the records in the connection's `plan` at the provider, ends the provider's access, runs the domain's DNS check, and returns the connection as `APPLIED`. `409 DNS_CONNECTION_NOT_CONFIRMABLE` unless the connection is `NEEDS_CONFIRMATION`; `410 DNS_CONNECTION_EXPIRED` when the held access has lapsed (the connection is then `EXPIRED`); `502 DNS_PROVIDER_REJECTED` when the provider refused the change (nothing is half-applied).
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApply
+      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
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          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: connectionId
+          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"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    applied:
+                      at: "2026-10-10T12:03:00.000Z"
+                      created: 0
+                      deleted: 0
+                      replaced: 1
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    phase: APPLIED
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApplyResponse"
+          description: apply the DNS changes a connection is waiting to make 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:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_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: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                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: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - 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
+                DNS_CONNECTION_NOT_CONFIRMABLE:
+                  summary: DNS_CONNECTION_NOT_CONFIRMABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_CONFIRMABLE
+                    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: DNS_CONNECTION_NOT_CONFIRMABLE
+                    type: urn:gala:problem:dns-connection-not-confirmable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_CONFIRMABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_CONFIRMABLE
+        "410":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_EXPIRED:
+                  summary: DNS_CONNECTION_EXPIRED
+                  value:
+                    code: DNS_CONNECTION_EXPIRED
+                    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: 410
+                    title: DNS_CONNECTION_EXPIRED
+                    type: urn:gala:problem:dns-connection-expired
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_EXPIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_EXPIRED
+        "502":
+          content:
+            application/problem+json:
+              examples:
+                DNS_PROVIDER_REJECTED:
+                  summary: DNS_PROVIDER_REJECTED
+                  value:
+                    code: DNS_PROVIDER_REJECTED
+                    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: 502
+                    title: DNS_PROVIDER_REJECTED
+                    type: urn:gala:problem:dns-provider-rejected
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_PROVIDER_REJECTED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_PROVIDER_REJECTED
+      security:
+        - browserSession: []
+      summary: apply the DNS changes a connection is waiting to make
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      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: apply the DNS changes a connection is waiting to make
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_EXPIRED
+        - DNS_CONNECTION_NOT_CONFIRMABLE
+        - DNS_CONNECTION_NOT_FOUND
+        - DNS_PROVIDER_REJECTED
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:discard:
+    post:
+      description: |
+        Ends a connection that is waiting for confirmation without changing anything at the provider, ends the provider's access, and returns the connection as `CANCELLED`. `409 DNS_CONNECTION_NOT_CONFIRMABLE` unless the connection is `NEEDS_CONFIRMATION`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscard
+      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
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          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: connectionId
+          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"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    outcome:
+                      code: CANCELLED
+                      detail: The records were left as they were.
+                    phase: CANCELLED
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscardResponse"
+          description: leave the provider's DNS records as they are and end a connection 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:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_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: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                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: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - 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
+                DNS_CONNECTION_NOT_CONFIRMABLE:
+                  summary: DNS_CONNECTION_NOT_CONFIRMABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_CONFIRMABLE
+                    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: DNS_CONNECTION_NOT_CONFIRMABLE
+                    type: urn:gala:problem:dns-connection-not-confirmable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_CONFIRMABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_CONFIRMABLE
+      security:
+        - browserSession: []
+      summary: leave the provider's DNS records as they are and end a connection
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      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: leave the provider's DNS records as they are and end a connection
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_NOT_CONFIRMABLE
+        - DNS_CONNECTION_NOT_FOUND
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}:check:
+    post:
+      description: |
+        Runs the checks for the binding's current state now (DNS, certificate,
+        routing) instead of waiting for the next automatic check, and returns
+        the binding. At most once a minute per binding (`429 RATE_LIMITED`).
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdCheck
+      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
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          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"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    canonicalBase:
+                      current: https://rathnastest.github.io/g11/
+                      published: false
+                      target: https://blog.maya.dev/
+                    certificate:
+                      state: PENDING
+                    createdAt: "2026-10-09T12:00:00.000Z"
+                    dns:
+                      observed:
+                        addresses: []
+                        checkedAt: "2026-10-09T12:00:00.000Z"
+                        cnameTarget: rathnastest.github.io
+                        pointsToGithub: true
+                        resolves: true
+                      records:
+                        - name: blog
+                          type: CNAME
+                          value: rathnastest.github.io
+                    domainId: 018f0000-0000-7000-8000-000000000001
+                    expiresAt: "2026-10-16T12:00:00.000Z"
+                    hostname: blog.maya.dev
+                    kind: SUBDOMAIN
+                    nextStep:
+                      code: WAIT_FOR_CERTIFICATE
+                      detail: GitHub is issuing the certificate; this can take up to 24 hours.
+                    routing:
+                      httpsEnforced: false
+                      probeOk: false
+                      servedByPages: false
+                    state: CERTIFICATE_PENDING
+                    updatedAt: "2026-10-09T12:00:00.000Z"
+                    version: 3
+                proxied:
+                  summary: Live behind Cloudflare's proxy
+                  value:
+                    canonicalBase:
+                      current: https://blog.maya.dev/
+                      published: true
+                      target: https://blog.maya.dev/
+                    certificate:
+                      state: PROXIED
+                    createdAt: "2026-10-09T12:00:00.000Z"
+                    dns:
+                      observed:
+                        addresses:
+                          - 104.21.0.1
+                        checkedAt: "2026-10-10T12:00:00.000Z"
+                        pointsToGithub: false
+                        resolves: true
+                        viaProxy: true
+                      records:
+                        - name: blog
+                          type: CNAME
+                          value: rathnastest.github.io
+                    domainId: 018f0000-0000-7000-8000-000000000001
+                    hostname: blog.maya.dev
+                    kind: SUBDOMAIN
+                    nextStep:
+                      code: NONE
+                      detail: Your site is live behind Cloudflare's proxy.
+                    proxy:
+                      provider: CLOUDFLARE
+                      since: "2026-10-10T12:00:00.000Z"
+                    routing:
+                      httpsEnforced: false
+                      probeOk: true
+                      servedByPages: true
+                    state: ACTIVE
+                    updatedAt: "2026-10-10T12:00:00.000Z"
+                    version: 9
+                stage2Offer:
+                  summary: Certificate issued; the proxy can be turned on
+                  value:
+                    canonicalBase:
+                      current: https://blog.maya.dev/
+                      published: true
+                      target: https://blog.maya.dev/
+                    certificate:
+                      state: ISSUED
+                    createdAt: "2026-10-09T12:00:00.000Z"
+                    dns:
+                      observed:
+                        addresses: []
+                        checkedAt: "2026-10-10T12:00:00.000Z"
+                        cnameTarget: rathnastest.github.io
+                        pointsToGithub: true
+                        resolves: true
+                      providers:
+                        - intents:
+                            - PROXY
+                          provider: CLOUDFLARE
+                      records:
+                        - name: blog
+                          type: CNAME
+                          value: rathnastest.github.io
+                    domainId: 018f0000-0000-7000-8000-000000000001
+                    hostname: blog.maya.dev
+                    kind: SUBDOMAIN
+                    nextStep:
+                      code: TURN_ON_CLOUDFLARE_PROXY
+                      detail: Your certificate is issued. You can now let Cloudflare proxy the site.
+                    routing:
+                      httpsEnforced: true
+                      probeOk: true
+                      servedByPages: true
+                    state: ACTIVE
+                    updatedAt: "2026-10-10T12:00:00.000Z"
+                    version: 8
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdCheckResponse"
+          description: check a custom domain now 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"
@@ -40425,6 +42016,8 @@ paths:
         Authenticated server-sent notification stream for review state changes.
         Events carry no authority or canonical state; a client re-reads the
         ordinary review and repository-change resources after each signal.
+        SCHEMA-3.6.0: the comment, decision time and actor, request time and
+        actor (`ReviewSummary`) arrive on that re-read, never in the event.
       operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdReviewsEvents
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -40776,7 +42369,8 @@ paths:
               nominal:
                 summary: Nominal valid request
                 value:
-                  decision: APPROVE
+                  comment: Please soften the second paragraph.
+                  decision: REJECT
                   reasonCode: example
             schema:
               $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdReviewsByReviewIdDecideRequest"
@@ -40789,10 +42383,17 @@ paths:
                 nominal:
                   summary: Nominal successful response
                   value:
+                    comment: Please soften the second paragraph.
+                    decidedAt: "2026-10-10T12:00:00.000Z"
+                    decidedBy:
+                      displayName: Maya Rao
+                    requestedAt: "2026-10-10T11:00:00.000Z"
+                    requestedBy:
+                      displayName: Sam Lee
                     reviewId: 018f0000-0000-7000-8000-000000000001
                     sourceRevision: sha1:0000000000000000000000000000000000000000
-                    state: REQUESTED
-                    version: 0
+                    state: REJECTED
+                    version: 1
               schema:
                 $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdReviewsByReviewIdDecideResponse"
           description: approve or reject exact reviewed revision succeeded
@@ -41140,7 +42741,12 @@ paths:
                         changeId: 018f0000-0000-7000-8000-000000000002
                         kind: POST
                         path: content/articles/hello.md
-                        review: NOT_REQUIRED
+                        pullRequestUrl: https://github.com/rathnastest/g11/pull/7
+                        review: NEEDS_RE_REVIEW
+                        reviewComment: Please soften the second paragraph.
+                        reviewDecidedAt: "2026-10-05T09:00:00Z"
+                        reviewDecidedBy:
+                          displayName: Maya Rao
                         title: Hello, world
                         updatedAt: "2026-10-05T09:30:00Z"
                       - action: CHANGE