# Onboarding Wizard — Action Contracts (073)

These are conceptual contracts for the wizard’s server-side actions (Livewire/Filament).
They define inputs/outputs and authorization semantics.

## Identify tenant

- **Purpose:** Upsert or resume a tenant onboarding session and ensure a single tenant record exists per `(workspace_id, entra_tenant_id)`.
- **Inputs:**
  - `entra_tenant_id` (string)
  - `name` (string)
  - `domain` (string|null)
- **Outputs:**
  - `tenant_id` (internal DB id)
  - `onboarding_session_id`
  - `current_step`
- **Errors:**
  - 404: workspace not found or actor not a workspace member
  - 403: actor is a workspace member but lacks onboarding capability

## Select or create Provider Connection

- **Purpose:** Attach an existing default connection (if present) or create/select another connection for the tenant.
- **Inputs:**
  - `provider_connection_id` (int|null)
  - (optional) connection creation fields (non-secret identifiers only)
- **Outputs:**
  - `provider_connection_id`
  - `is_default`
- **Errors:**
  - 404: connection/tenant not in workspace scope
  - 403: member missing capability

## Start verification

- **Purpose:** Start provider connection verification asynchronously.
- **Mechanism:** Create/reuse `OperationRun` of type `provider.connection.check`, enqueue `ProviderConnectionHealthCheckJob`.
- **Inputs:** none (uses selected connection)
- **Outputs:**
  - `operation_run_id`
  - `status` (queued/running/succeeded/failed)
- **Errors:**
  - 404: tenant/connection not in workspace scope
  - 403: member missing capability

## Optional bootstrap actions

- **Purpose:** Start selected post-verify operations as separate runs.
- **Inputs:** list of operation types (must exist in registry)
- **Outputs:** list of `operation_run_id`
- **Errors:**
  - 403/404 semantics as above

## Security & data minimization

- Stored secrets must never be returned.
- Failures are stored as stable reason codes + sanitized messages.