openapi: 3.1.0
info:
  title: Decision-Based Governance Inbox v1
  version: 0.1.0
  summary: Conceptual contract for the canonical governance inbox page.
paths:
  /admin/governance/inbox:
    get:
      summary: Render the governance inbox page
      description: >-
        Returns the derived governance inbox composition for the current workspace actor.
        This is a conceptual page contract used for planning, not a public API commitment.
      parameters:
        - in: query
          name: tenant_id
          schema:
            type: integer
            nullable: true
          description: Optional tenant prefilter. Out-of-scope values resolve as not found.
        - in: query
          name: family
          schema:
            type: string
            enum:
              - assigned_findings
              - intake_findings
              - stale_operations
              - alert_delivery_failures
              - review_follow_up
          description: Optional source-family filter. `stale_operations` is the canonical key for both stale and terminal-follow-up operations attention.
        - in: query
          name: nav[source_surface]
          schema:
            type: string
          description: Optional shared navigation context source.
      responses:
        '200':
          description: Derived governance inbox payload for page rendering.
          content:
            application/json:
              schema:
                type: object
                required:
                  - title
                  - applied_scope
                  - sections
                properties:
                  title:
                    type: string
                    example: Governance inbox
                  applied_scope:
                    type: object
                    properties:
                      tenant_id:
                        type: integer
                        nullable: true
                      family:
                        type: string
                        nullable: true
                      workspace_scoped:
                        type: boolean
                  sections:
                    type: array
                    items:
                      type: object
                      required:
                        - key
                        - label
                        - count
                        - summary
                        - dominant_action
                        - entries
                      properties:
                        key:
                          type: string
                          description: Family key; `stale_operations` covers stale and terminal-follow-up operations attention.
                        label:
                          type: string
                        count:
                          type: integer
                        summary:
                          type: string
                        empty_state:
                          type: string
                          nullable: true
                          description: Family-specific empty-state copy used when the family is explicitly selected but has no visible entries.
                        dominant_action:
                          type: object
                          required:
                            - label
                            - url
                          properties:
                            label:
                              type: string
                            url:
                              type: string
                        entries:
                          type: array
                          items:
                            type: object
                            required:
                              - family_key
                              - source_model
                              - source_key
                              - headline
                              - status_label
                              - destination_url
                            properties:
                              family_key:
                                type: string
                                description: Matches the owning section key; `stale_operations` covers stale and terminal-follow-up operations attention.
                              source_model:
                                type: string
                              source_key:
                                type: string
                              tenant_id:
                                type: integer
                                nullable: true
                              tenant_label:
                                type: string
                                nullable: true
                              headline:
                                type: string
                              subline:
                                type: string
                                nullable: true
                              urgency_rank:
                                type: integer
                              status_label:
                                type: string
                              destination_url:
                                type: string
                              back_label:
                                type: string
                                nullable: true
        '404':
          description: Workspace membership missing or explicit tenant prefilter is outside scope.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    example: Not Found
        '403':
          description: Workspace member is in scope but lacks every qualifying visible-family capability for the inbox.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    example: Forbidden