@rathnasgala2/schemas 3.10.0 → 3.12.0

package/openapi/openapi.yaml

@@ -1048,6 +1048,27 @@ components:
         - detail
         - reversible
       type: object
+    ContactEmail:
+      additionalProperties: false
+      description: The verified GitHub primary email the person agreed to receive account and security notices at. The full address never leaves the server; only a masked form is shown.
+      properties:
+        maskedAddress:
+          description: Masked form such as `a…d@example.com`, never the full address. Null or absent unless `state` is `ON_FILE`.
+          maxLength: 320
+          type:
+            - string
+            - "null"
+        state:
+          enum:
+            - NONE
+            - ON_FILE
+            - WITHDRAWN
+          type: string
+        updatedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - state
+      type: object
     ContentChangeAppearanceEntry:
       additionalProperties: false
       description: |
@@ -1060,9 +1081,20 @@ components:
         optional: the author's publication palette, written as
         `gala/appearance.json`'s `tokens`; when absent the file's `tokens`
         are preserved unchanged, and `{}` resets to the theme's own colours.
+        `brandMark` (SCHEMA-3.12.0) is optional: a repository-relative path
+        under `assets/brand/`, written as `gala/appearance.json`'s
+        `brandMark` (the site icon); `null` clears it and an absent member
+        preserves the file's value. The App uploads the image file as an
+        ordinary `assets[]` entry in the same plan.
       properties:
         attribution:
           $ref: "#/components/schemas/PortableAppearanceAttribution"
+        brandMark:
+          oneOf:
+            - allOf:
+                - $ref: "#/components/schemas/PortableAppearanceRepoRelativePath"
+                - pattern: ^assets/brand/
+            - type: "null"
         colorModeDefault:
           $ref: "#/components/schemas/AppearanceColorMode"
         themeId:
@@ -1187,6 +1219,55 @@ components:
         - path
         - action
       type: object
+    ContentChangePublicationProfileEntry:
+      additionalProperties: false
+      description: |
+        SCHEMA-3.12.0: site-level settings inside a batch
+        `content-changes:plan` request, the same lifecycle and capability as
+        `appearance` (a pending change that goes live on Publish). The
+        server loads `gala/publication.json` at `baseRevision`, applies the
+        members that are present, validates the result against
+        `publication.schema.json`, and plans one `PUT` of
+        `gala/publication.json`. An absent member is preserved. `null`
+        resets `description` to the publication title (the file requires a
+        description); `null` clears `defaultImageRef` and `crawlers`.
+        `title`, `defaultLanguage` and `socialLinks` cannot be cleared.
+        `socialLinks` (max 32, the publication file's own limit) replaces
+        the whole list. `canonicalBase` is never client-settable: it changes
+        only through domain attach and detach. A profile that changes nothing is
+        `422 VALIDATION_FAILED` pointed at `/publicationProfile`; member
+        failures point at `/publicationProfile/<member>`.
+      properties:
+        crawlers:
+          oneOf:
+            - $ref: "#/components/schemas/PortablePublicationCrawlers"
+            - type: "null"
+        defaultImageRef:
+          oneOf:
+            - allOf:
+                - $ref: "#/components/schemas/PortablePublicationRepoRelativePath"
+                - pattern: ^assets/brand/
+            - type: "null"
+        defaultLanguage:
+          $ref: "#/components/schemas/PortablePublicationBcp47"
+        description:
+          oneOf:
+            - $ref: "#/components/schemas/PortablePublicationPlainText"
+              x-gala-graphemeLength:
+                maximum: 300
+                minimum: 1
+            - type: "null"
+        socialLinks:
+          items:
+            $ref: "#/components/schemas/PortablePublicationSocialLink"
+          maxItems: 32
+          type: array
+        title:
+          $ref: "#/components/schemas/PortablePublicationPlainText"
+          x-gala-graphemeLength:
+            maximum: 120
+            minimum: 1
+      type: object
     ContentFrontmatter:
       $ref: "#/components/schemas/PortableContentFrontmatterDocument"
     ContentInventoryItem:
@@ -1324,14 +1405,36 @@ components:
             $ref: "#/components/schemas/ContentPublicationAuthorSummary"
           maxItems: 200
           type: array
+        crawlers:
+          $ref: "#/components/schemas/PortablePublicationCrawlers"
+        defaultImageRef:
+          $ref: "#/components/schemas/PortablePublicationRepoRelativePath"
         defaultLanguage:
           $ref: "#/components/schemas/PortablePublicationBcp47"
+        description:
+          $ref: "#/components/schemas/PortablePublicationPlainText"
+          x-gala-graphemeLength:
+            maximum: 500
+            minimum: 1
+        socialLinks:
+          items:
+            $ref: "#/components/schemas/PortablePublicationSocialLink"
+          maxItems: 32
+          type: array
         theme:
           $ref: "#/components/schemas/PortableAppearancePackageRange"
+        title:
+          $ref: "#/components/schemas/PortablePublicationPlainText"
+          x-gala-graphemeLength:
+            maximum: 200
+            minimum: 1
       required:
         - defaultLanguage
         - theme
         - authors
+        - title
+        - description
+        - socialLinks
       type: object
     DefaultBranchUpdateState:
       description: |
@@ -4222,6 +4325,8 @@ components:
           uniqueItems: true
         closure:
           $ref: "#/components/schemas/SessionClosure"
+        contactEmail:
+          $ref: "#/components/schemas/ContactEmail"
         credentialEpoch:
           format: int64
           minimum: 0
@@ -6901,6 +7006,9 @@ components:
     PlatformUser:
       additionalProperties: false
       properties:
+        contactEmailOnFile:
+          description: Whether a contact email the person agreed to is on file. The address itself is never returned.
+          type: boolean
         createdAt:
           $ref: "#/components/schemas/PortableProblemRfc3339"
         displayName:
@@ -6943,6 +7051,7 @@ components:
         - lastSignInAt
         - publicationCount
         - planTiers
+        - contactEmailOnFile
       type: object
     PlatformWebhookEvent:
       additionalProperties: false
@@ -7043,6 +7152,15 @@ components:
       minLength: 3
       pattern: ^(?:@[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?/[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?|[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?)@(?:\S+|\S+ \S+)$
       type: string
+    PortableAppearanceRepoRelativePath:
+      description: NFC UTF-8 repository-relative path using slash separators, with no leading slash, dot segment, NUL, backslash, or percent-decoded traversal.
+      format: gala-repository-relative-path
+      maxLength: 512
+      minLength: 1
+      pattern: ^(?!/)(?!.*\\)(?!.*\u0000).+$
+      type: string
+      x-gala-utf8ByteLength:
+        maximum: 512
     PortableAppearanceSemanticTokens:
       additionalProperties: false
       description: "SCHEMA-3.10.0: the author's publication palette. Each role (accent, canvas, text) is optional; when present it carries both light and dark as opaque lowercase #rrggbb. An absent role uses the theme's default; `{}` selects the theme's default palette entirely."
@@ -7145,6 +7263,26 @@ components:
         - generation
         - approvedAt
       type: object
+    PortableContentFrontmatterContentSeo:
+      additionalProperties: false
+      description: "SCHEMA-3.12.0: optional search overrides for one document. `title` replaces the page title in search results (the site suffix is still appended on non-home pages), `description` replaces the search description, `canonicalUrl` is an absolute HTTPS canonical for syndicated or moved content, and `noindex: true` keeps a listed document out of search engines. Every member is optional; absent members fall back to the document's own title and description."
+      properties:
+        canonicalUrl:
+          $ref: "#/components/schemas/PortableContentFrontmatterUrlHttps"
+        description:
+          $ref: "#/components/schemas/PortableContentFrontmatterPlainText"
+          x-gala-graphemeLength:
+            maximum: 300
+            minimum: 1
+        noindex:
+          type: boolean
+        title:
+          $ref: "#/components/schemas/PortableContentFrontmatterPlainText"
+          x-gala-graphemeLength:
+            maximum: 70
+            minimum: 1
+      required: []
+      type: object
     PortableContentFrontmatterDigest:
       pattern: ^sha256:[0-9a-f]{64}$
       type: string
@@ -7241,6 +7379,8 @@ components:
           pattern: ^2\.0\.0$
           type: string
           x-gala-const: 2.0.0
+        seo:
+          $ref: "#/components/schemas/PortableContentFrontmatterContentSeo"
         series:
           $ref: "#/components/schemas/PortableContentFrontmatterPlainLabel"
         seriesOrder:
@@ -7371,6 +7511,11 @@ components:
       description: Lowercase canonical UUIDv7. Once published, it is immutable; its time ordering conveys neither chronology nor authority.
       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
+    PortableContentFrontmatterUrlHttps:
+      description: Absolute HTTPS URL without embedded credentials.
+      format: uri
+      pattern: ^https://(?![^/?#]*@)
+      type: string
     PortableDeploymentIntentAdapterIdentity:
       additionalProperties: false
       properties:
@@ -12926,6 +13071,84 @@ components:
       x-gala-utf8ByteLength:
         maximum: 255
         minimum: 1
+    PortablePublicationCrawlers:
+      additionalProperties: false
+      properties:
+        ai:
+          enum:
+            - allow
+            - block
+      required:
+        - ai
+      type: object
+    PortablePublicationPlainLabel:
+      description: Normalized Unicode plain text without markup, controls, or bidi overrides.
+      format: gala-plain-label
+      type: string
+      x-gala-graphemeLength:
+        maximum: 80
+        minimum: 1
+    PortablePublicationPlainText:
+      description: NFC Unicode text without disallowed C0/C1 controls or bidi override/isolate controls.
+      format: gala-plain-text
+      type: string
+    PortablePublicationRepoRelativePath:
+      description: NFC UTF-8 repository-relative path using slash separators, with no leading slash, dot segment, NUL, backslash, or percent-decoded traversal.
+      format: gala-repository-relative-path
+      maxLength: 512
+      minLength: 1
+      pattern: ^(?!/)(?!.*\\)(?!.*\u0000).+$
+      type: string
+      x-gala-utf8ByteLength:
+        maximum: 512
+    PortablePublicationSocialLink:
+      additionalProperties: false
+      allOf:
+        - else:
+            properties:
+              uri:
+                $ref: "#/components/schemas/PortablePublicationUrlHttps"
+          if:
+            properties:
+              type:
+                pattern: ^email$
+                type: string
+                x-gala-const: email
+            required:
+              - type
+          then:
+            properties:
+              uri:
+                format: uri
+                pattern: "^mailto:"
+                type: string
+      properties:
+        label:
+          $ref: "#/components/schemas/PortablePublicationPlainLabel"
+        type:
+          enum:
+            - website
+            - email
+            - github
+            - linkedin
+            - mastodon
+            - bluesky
+            - x
+            - youtube
+            - other
+        uri:
+          maxLength: 2048
+          minLength: 1
+          type: string
+      required:
+        - type
+        - uri
+      type: object
+    PortablePublicationUrlHttps:
+      description: Absolute HTTPS URL without embedded credentials.
+      format: uri
+      pattern: ^https://(?![^/?#]*@)
+      type: string
     PostAuthenticationGithubTransactionsRequest:
       additionalProperties: false
       properties:
@@ -13704,13 +13927,15 @@ 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`/`appearance`)
+        (`baseRevision` and at least one of `documents`/`assets`/`appearance`/
+        `publicationProfile`)
         plans up to 20 documents and 20 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`.
+        `documents`, `assets`, `appearance` and `publicationProfile`, is
+        `422 VALIDATION_FAILED`.
         `appearance` names a catalog theme and a default colour mode, and
         optionally the footer `attribution` (SCHEMA-3.3.0); the server
         writes `gala/appearance.json` (only `theme`, `colorMode.default` and,
@@ -13720,6 +13945,10 @@ components:
         selection (theme, default colour mode and, when sent, attribution)
         is `422 VALIDATION_FAILED` pointed at `/appearance`. Document paths
         under `gala/` and `gala.lock.json` remain forbidden.
+        `publicationProfile` (SCHEMA-3.12.0) is a further batch member beside
+        `appearance`, counting as one of the named members: it edits
+        `gala/publication.json` through one planned `PUT` (see
+        `ContentChangePublicationProfileEntry`).
         Assets are images only (PNG, JPEG, WebP, GIF, AVIF; SVG is refused):
         at most 20 per change, each at most 5 MiB and together at most
         20 MiB, measured on the decoded bytes -- `assets[].bytesBase64` is
@@ -13752,6 +13981,8 @@ components:
           maxLength: 512
           minLength: 1
           type: string
+        publicationProfile:
+          $ref: "#/components/schemas/ContentChangePublicationProfileEntry"
       required: []
       type: object
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdContentChangesPlanResponse:
@@ -14579,7 +14810,16 @@ components:
         - $ref: "#/components/schemas/PublicationTransfer"
     PostOrganizationsByOrganizationIdPublicationsRequest:
       additionalProperties: false
+      description: |
+        `description` (SCHEMA-3.12.0) is the optional site tagline, written
+        as `gala/publication.json`'s `description`. When absent the server
+        keeps its fallback (the site name).
       properties:
+        description:
+          $ref: "#/components/schemas/PortablePublicationPlainText"
+          x-gala-graphemeLength:
+            maximum: 300
+            minimum: 1
         name:
           maxLength: 80
           minLength: 1
@@ -14869,6 +15109,46 @@ components:
       required:
         - client
       type: object
+    PostPlatformUsersByPersonIdContactRequest:
+      additionalProperties: false
+      properties:
+        body:
+          maxLength: 5000
+          minLength: 1
+          type: string
+        category:
+          enum:
+            - ACCOUNT
+            - SECURITY
+            - SERVICE
+          type: string
+        reason:
+          $ref: "#/components/schemas/PlatformOperatorReasonCode"
+        subject:
+          maxLength: 200
+          minLength: 1
+          type: string
+      required:
+        - category
+        - subject
+        - body
+        - reason
+      type: object
+    PostPlatformUsersByPersonIdContactResponse:
+      additionalProperties: false
+      properties:
+        messageId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        state:
+          enum:
+            - QUEUED
+          type: string
+      required:
+        - messageId
+        - state
+      type: object
     PostPublicCommentsByCommentIdAppealsRequest:
       additionalProperties: false
       properties:
@@ -15119,6 +15399,22 @@ components:
         - state
         - fenceAt
       type: object
+    PostSelfContactEmailGrantResponse:
+      additionalProperties: false
+      properties:
+        contactEmail:
+          $ref: "#/components/schemas/ContactEmail"
+      required:
+        - contactEmail
+      type: object
+    PostSelfContactEmailWithdrawResponse:
+      additionalProperties: false
+      properties:
+        contactEmail:
+          $ref: "#/components/schemas/ContactEmail"
+      required:
+        - contactEmail
+      type: object
     PostSelfExportsByExportIdDownloadResponse:
       additionalProperties: false
       properties:
@@ -15729,10 +16025,19 @@ components:
         (SCHEMA-3.3.0, optional) is the file's footer attribution switch;
         absent means the file has none, which renders as shown. `tokens`
         (SCHEMA-3.10.0, optional) is the file's publication palette as read;
-        absent or `{}` means the theme's own colours.
+        absent or `{}` means the theme's own colours. `brandMark`
+        (SCHEMA-3.12.0, optional): the publication's brand mark as currently
+        committed, absent when none.
       properties:
         attribution:
           $ref: "#/components/schemas/PortableAppearanceAttribution"
+        brandMark:
+          description: "SCHEMA-3.12.0: the publication's brand mark as currently committed, absent when none"
+          oneOf:
+            - allOf:
+                - $ref: "#/components/schemas/PortableAppearanceRepoRelativePath"
+                - pattern: ^assets/brand/
+            - type: "null"
         colorModeDefault:
           $ref: "#/components/schemas/AppearanceColorMode"
         themeId:
@@ -30225,7 +30530,10 @@ paths:
                         - displayName: Example Author
                           id: 018f0000-0000-7000-8000-000000000001
                       defaultLanguage: en
+                      description: Example tagline
+                      socialLinks: []
                       theme: "@rathnasgala2/theme-default@^4.0.0"
+                      title: Example
                     setUp: true
               schema:
                 $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdContentResponse"
@@ -48601,7 +48909,8 @@ paths:
                   value:
                     hasMore: false
                     items:
-                      - createdAt: "2026-09-01T12:00:00.000Z"
+                      - contactEmailOnFile: true
+                        createdAt: "2026-09-01T12:00:00.000Z"
                         displayName: Ada Reader
                         lastSignInAt: "2026-10-10T11:30:00.000Z"
                         login: ada-reader
@@ -48650,6 +48959,140 @@ paths:
         - NONE
       x-gala-success-category: query
       x-gala-tenant-scope: NONE
+  /v2/platform/users/{personId}:contact:
+    post:
+      description: |
+        Operators only, with recent authentication. Queues one message to the
+        person's contact email, which they agreed to at sign-in. The address is
+        never returned; the message carries the fixed Galascribe wrapper and
+        the operator's text. `category` is `ACCOUNT`, `SECURITY` or `SERVICE`.
+        `reason` is a non-sensitive operator reason code recorded in the audit
+        event. `Idempotency-Key` is the queued-message identity. `202` means the
+        message is queued, not delivered. `404 RESOURCE_NOT_FOUND` for an
+        unknown person; `409 CONTACT_EMAIL_ABSENT` when no contact email is on
+        file or it was withdrawn.
+      operationId: postPlatformUsersByPersonIdContact
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: personId
+          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:
+                  body: Your site repository needs attention before we can publish.
+                  category: SERVICE
+                  reason: OPERATOR_REQUESTED
+                  subject: Action needed on your Galascribe site
+            schema:
+              $ref: "#/components/schemas/PostPlatformUsersByPersonIdContactRequest"
+        required: true
+      responses:
+        "202":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    messageId: 018f0000-0000-7000-8000-000000000003
+                    state: QUEUED
+              schema:
+                $ref: "#/components/schemas/PostPlatformUsersByPersonIdContactResponse"
+          description: contact platform user accepted
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          $ref: "#/components/responses/RequestInvalid"
+        "401":
+          $ref: "#/components/responses/PlatformAuthenticationRequired"
+        "403":
+          $ref: "#/components/responses/AuthorizationDenied"
+        "404":
+          $ref: "#/components/responses/ResourceNotFound"
+        "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
+                CONTACT_EMAIL_ABSENT:
+                  summary: CONTACT_EMAIL_ABSENT
+                  value:
+                    code: CONTACT_EMAIL_ABSENT
+                    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: CONTACT_EMAIL_ABSENT
+                    type: urn:gala:problem:contact-email-absent
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, CONTACT_EMAIL_ABSENT
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - CONTACT_EMAIL_ABSENT
+      security:
+        - browserSession: []
+      summary: contact platform user
+      tags:
+        - platform
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: platform.users.contact
+      x-gala-concurrency: none
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: contact platform user
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - CONTACT_EMAIL_ABSENT
+        - REAUTH_REQUIRED
+        - REQUEST_FIELD_UNKNOWN
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: async
+      x-gala-tenant-scope: NONE
   /v2/platform/webhook-events:
     get:
       description: |
@@ -51775,6 +52218,329 @@ paths:
         - NONE
       x-gala-success-category: protocol
       x-gala-tenant-scope: NONE
+  /v2/self/contact-email:grant:
+    post:
+      description: |
+        Records the person's agreement to receive account and security notices
+        at their verified GitHub primary email. The server reads the address from
+        GitHub with the stored sign-in token, seals it, and answers with the
+        masked form only; the full address never leaves the server. Needs
+        recent authentication: a stale session gets `401 REAUTH_REQUIRED`.
+        `409 CONTACT_EMAIL_UNAVAILABLE` when GitHub reports no verified primary
+        email (`errors[].code` `NO_VERIFIED_PRIMARY_EMAIL`) or the sign-in did
+        not grant the email scope (`SCOPE_NOT_GRANTED`), both at pointer
+        `/contactEmail`; the person signs in again to grant the scope.
+      operationId: postSelfContactEmailGrant
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    contactEmail:
+                      maskedAddress: a…d@example.com
+                      state: ON_FILE
+                      updatedAt: "2026-10-13T12:00:00.000Z"
+              schema:
+                $ref: "#/components/schemas/PostSelfContactEmailGrantResponse"
+          description: grant contact email 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
+                REAUTH_REQUIRED:
+                  summary: REAUTH_REQUIRED
+                  value:
+                    code: REAUTH_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: REAUTH_REQUIRED
+                    type: urn:gala:problem:reauth-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED, REAUTH_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+            - REAUTH_REQUIRED
+        "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
+                CONTACT_EMAIL_UNAVAILABLE:
+                  summary: CONTACT_EMAIL_UNAVAILABLE
+                  value:
+                    code: CONTACT_EMAIL_UNAVAILABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors:
+                      - code: NO_VERIFIED_PRIMARY_EMAIL
+                        pointer: /contactEmail
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: CONTACT_EMAIL_UNAVAILABLE
+                    type: urn:gala:problem:contact-email-unavailable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, CONTACT_EMAIL_UNAVAILABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - CONTACT_EMAIL_UNAVAILABLE
+      security:
+        - browserSession: []
+      summary: grant contact email
+      tags:
+        - self
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: null
+      x-gala-concurrency: principal-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: grant contact email
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - COMMAND_REPLAY_CONFLICT
+        - CONTACT_EMAIL_UNAVAILABLE
+        - REAUTH_REQUIRED
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: NONE
+  /v2/self/contact-email:withdraw:
+    post:
+      description: |
+        Withdraws the agreement to receive notices by email. The sealed address
+        is deleted, the state reads `WITHDRAWN`, and the person is not asked
+        again. Safe to repeat. Needs recent authentication: a stale session
+        gets `401 REAUTH_REQUIRED`.
+      operationId: postSelfContactEmailWithdraw
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    contactEmail:
+                      state: WITHDRAWN
+                      updatedAt: "2026-10-13T12:00:00.000Z"
+              schema:
+                $ref: "#/components/schemas/PostSelfContactEmailWithdrawResponse"
+          description: withdraw contact email 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
+                REAUTH_REQUIRED:
+                  summary: REAUTH_REQUIRED
+                  value:
+                    code: REAUTH_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: REAUTH_REQUIRED
+                    type: urn:gala:problem:reauth-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED, REAUTH_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+            - REAUTH_REQUIRED
+        "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
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+      security:
+        - browserSession: []
+      summary: withdraw contact email
+      tags:
+        - self
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: null
+      x-gala-concurrency: principal-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: withdraw contact email
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - COMMAND_REPLAY_CONFLICT
+        - REAUTH_REQUIRED
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: NONE
   /v2/self/exports:
     get:
       description: |