# Contracts — Managed Tenant Onboarding Wizard v1

This feature is primarily a Filament wizard UI, so the “contracts” are internal (Livewire actions + routes), plus the `OperationRun` types used for enqueue-only verification.

## Routes (tenant-plane)

All routes are within the `/admin` panel and tenant-prefixed (current panel config uses `tenantRoutePrefix('t')`).

- `GET /admin/t/{tenant:external_id}/onboarding`
  - Render wizard and resume active session (no outbound calls; DB-only)
- `POST /admin/t/{tenant:external_id}/onboarding/save`
  - Persist current step + payload (DB-only)
- `POST /admin/t/{tenant:external_id}/onboarding/verify`
  - Enqueue verification operation(s) as `OperationRun` records; return immediately

## Livewire/Filament component actions

All server-side actions MUST:
- enforce membership (404 for non-members)
- enforce capability (403 for members lacking the capability)
- never make outbound HTTP during render/mount

### `startOrResume()`
- Input: tenant context (`tenant_id` inferred from route)
- Output: session id + current step
- Behavior:
  - if an `active` session exists for tenant, load and continue
  - else create new `active` session

### `saveStep(string $step, array $state)`
- Input:
  - `step`: one of `welcome|tenant_details|credentials|permissions|verification`
  - `state`: non-secret state only
- Output: updated session
- Invariants:
  - state must be validated per-step
  - secrets MUST NOT be persisted

### `enqueueVerification()`
- Input: none (reads from session + tenant)
- Output: list of `OperationRun` ids (or one id)
- Behavior:
  - Use `OperationRunService` to create/dedupe an active run identity for this tenant + check type.
  - Dispatch jobs using existing provider operation patterns where applicable.

## OperationRun types

Exact type names should follow existing `ProviderOperationRegistry` conventions.

### `tenant.rbac.verify` (proposed)
- Scope: tenant
- Purpose: enqueue-only verification of tenant RBAC prerequisites
- Identity: stable for `(tenant_id, "tenant.rbac.verify")` when active
- Job side effects:
  - update `tenants.rbac_last_checked_at`
  - write sanitized warning messages to `tenants.rbac_last_warnings`
  - store per-check result details in `tenants.rbac_canary_results`

### Optional: `tenant.credentials.verify` (proposed)
- Scope: tenant
- Only if credentials step is enabled/required

## Legacy entry points

- `GET /admin/new` → redirect to “Choose workspace” (as per spec clarifications)
- Any other legacy onboarding entry points should be redirected or removed.