openapi: 3.0.3
info:
  title: TenantPilot Admin — Onboarding Readiness Workflow (Conceptual)
  version: 0.1.0
  description: |
    Conceptual HTTP contract for the operator-facing onboarding readiness workflow.

    NOTE: These routes are implemented as Filament (Livewire) pages and existing
    actions. The exact Livewire payload shape is not part of this contract; this
    file captures the user-visible routes, authorization semantics, and logical
    view-model expectations.
servers:
  - url: /admin
paths:
  /onboarding:
    get:
      summary: View onboarding landing or draft picker
      description: |
        Workspace-scoped onboarding entry point.

        Behavior:
        - No workspace selected: redirect to `/admin/choose-workspace`
        - Non-member or wrong workspace: 404
        - Workspace member without onboarding capability: 403
        - One resumable draft: redirect to `/admin/onboarding/{onboardingDraft}`
        - Multiple resumable drafts: render the draft picker with compact readiness snippets
      responses:
        '200':
          description: Landing picker rendered
          content:
            text/html:
              schema:
                type: string
          x-logical-view-model:
            $ref: '#/components/schemas/OnboardingLandingView'
        '302':
          description: Redirect to choose-workspace or the single resumable draft
        '403':
          description: Forbidden (workspace member lacks onboarding capability)
        '404':
          description: Not found (non-member or wrong workspace)
  /onboarding/{onboardingDraft}:
    get:
      summary: View onboarding draft readiness workflow
      description: |
        Renders the existing managed-tenant onboarding wizard with a derived
        readiness summary, freshness cues, and one primary next action.

        Authorization:
        - Non-member or wrong workspace: 404
        - Missing linked-tenant entitlement: 404
        - Workspace member without onboarding capability: 403
      parameters:
        - name: onboardingDraft
          in: path
          required: true
          schema:
            type: integer
          description: Internal `managed_tenant_onboarding_sessions.id`
      responses:
        '200':
          description: Onboarding draft workflow rendered
          content:
            text/html:
              schema:
                type: string
          x-logical-view-model:
            $ref: '#/components/schemas/OnboardingReadinessView'
        '403':
          description: Forbidden (workspace member lacks onboarding capability)
        '404':
          description: Not found (non-member, wrong workspace, or missing linked-tenant entitlement)
  /onboarding/{onboardingDraft}/actions/start-verification:
    post:
      summary: Start or rerun verification from the onboarding readiness workflow
      description: |
        Conceptual contract for the existing wizard verification action.
        This feature must preserve current authorization, audit, dedupe, and
        shared OperationRun start UX semantics.
      parameters:
        - name: onboardingDraft
          in: path
          required: true
          schema:
            type: integer
      responses:
        '202':
          description: Verification accepted/queued
        '403':
          description: Forbidden (member lacks verification-start capability)
        '404':
          description: Not found (non-member, wrong workspace, or missing linked-tenant entitlement)
  /onboarding/{onboardingDraft}/actions/complete:
    post:
      summary: Complete onboarding when readiness allows activation
      description: |
        Conceptual contract for the existing owner-gated completion action.
        The action remains confirmation-protected and audited.
      parameters:
        - name: onboardingDraft
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Onboarding completed
        '403':
          description: Forbidden (member lacks activation capability)
        '404':
          description: Not found (non-member, wrong workspace, or missing linked-tenant entitlement)
  /operations/{run}:
    get:
      summary: Open canonical supporting operation from onboarding readiness
      description: |
        Existing canonical tenantless operation-detail route linked from the
        onboarding readiness workflow when supporting verification or bootstrap
        evidence exists.
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
          description: Internal `operation_runs.id`
      responses:
        '200':
          description: Operation detail rendered
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Forbidden (member lacks permission for an action on the page)
        '404':
          description: Not found (run inaccessible under current workspace/tenant scope)
components:
  schemas:
    OnboardingLandingView:
      type: object
      required:
        - mode
        - drafts
      properties:
        mode:
          type: string
          enum: [start_state, single_redirect, draft_picker]
        drafts:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingDraftCard'
        primary_action:
          $ref: '#/components/schemas/NextAction'
          nullable: true
    OnboardingDraftCard:
      type: object
      required:
        - draft_id
        - tenant_name
        - current_stage
        - readiness_summary
        - next_action
      properties:
        draft_id:
          type: integer
        tenant_name:
          type: string
        current_stage:
          type: string
        readiness_summary:
          type: string
        freshness_note:
          type: string
          nullable: true
        next_action:
          $ref: '#/components/schemas/NextAction'
    OnboardingReadinessView:
      type: object
      required:
        - draft
        - readiness
        - next_action
      properties:
        draft:
          type: object
          required:
            - id
            - tenant_name
            - current_stage
          properties:
            id:
              type: integer
            tenant_name:
              type: string
            current_stage:
              type: string
            started_by:
              type: string
              nullable: true
            updated_by:
              type: string
              nullable: true
        readiness:
          type: object
          required:
            - lifecycle_state
            - summary
          properties:
            lifecycle_state:
              type: string
            summary:
              type: string
            checkpoint:
              type: string
              nullable: true
            provider_summary:
              type: string
              nullable: true
            freshness_note:
              type: string
              nullable: true
            blocker_reason:
              type: string
              nullable: true
        next_action:
          $ref: '#/components/schemas/NextAction'
        supporting_links:
          type: array
          items:
            $ref: '#/components/schemas/LinkAction'
    NextAction:
      type: object
      required:
        - label
        - kind
      properties:
        label:
          type: string
        kind:
          type: string
          enum:
            - start_onboarding
            - resume_draft
            - grant_consent
            - review_permissions
            - start_verification
            - rerun_verification
            - open_operation
            - review_bootstrap
            - complete_onboarding
        url:
          type: string
          nullable: true
        action_name:
          type: string
          nullable: true
    LinkAction:
      type: object
      required:
        - label
        - url
      properties:
        label:
          type: string
        url:
          type: string