# Quickstart: Onboarding Lifecycle, Operation Checkpoints & Concurrency MVP

## Goal

Validate the lifecycle, checkpoint-monitoring, and optimistic-locking design on the existing managed tenant onboarding wizard without adding routes or replacing the current flow.

## Prerequisites

1. Start the local stack with `vendor/bin/sail up -d`.
2. Ensure the database is migrated after implementation with `vendor/bin/sail artisan migrate --no-interaction`.
3. Use a workspace member with onboarding permissions and, for activation scenarios, an owner-capable actor.

## Manual Validation Flow

### Scenario 1: New draft lifecycle foundation

1. Open `/admin/onboarding`.
2. Create or resume a draft.
3. Confirm the persisted draft starts in `draft` and `current_checkpoint` reflects the current wizard step.

### Scenario 2: Verify Access as a live checkpoint

1. Select a provider connection.
2. Start Verify Access from Step 3.
3. Confirm the draft moves to `verifying` and the step shows live checkpoint messaging.
4. Keep the page open until the run becomes terminal.
5. Confirm the step updates within the active `5s` polling cadence without manual refresh and the lifecycle transitions to either `ready_for_activation` or `action_required`.
6. Confirm the Spec 139 required-permissions assist still works when verification is blocked or needs attention.

### Scenario 3: Bootstrap as an optional live checkpoint

1. Select one or more bootstrap actions in Step 4.
2. Start bootstrap.
3. Confirm the draft moves to `bootstrapping`.
4. Keep the page open until selected runs become terminal.
5. Confirm the step renders per-run status within the active `5s` polling cadence and stops polling when no relevant runs remain active.

### Scenario 4: Activation gating

1. Reach a state that appears ready for activation.
2. Invalidate readiness by changing the provider connection or by forcing a relevant blocking condition in another session.
3. Attempt activation.
4. Confirm activation rechecks backend truth and refuses to complete until readiness is restored.

### Scenario 5: Optimistic locking conflict

1. Open the same onboarding draft in two tabs.
2. Save a draft mutation in Tab A.
3. Submit a stale mutation in Tab B.
4. Confirm Tab B sees a clear conflict notification, remains on the wizard, and does not show a false success state.

## Focused Test Targets

- `tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`
- `tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php`
- `tests/Feature/Onboarding/OnboardingActivationTest.php`
- `tests/Feature/Onboarding/OnboardingVerificationAssistTest.php`
- `tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
- `tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php`
- `tests/Feature/OpsUx/QueuedToastCopyTest.php`
- `tests/Feature/OperationRunServiceTest.php`
- `tests/Browser/OnboardingDraftRefreshTest.php`
- `tests/Browser/OnboardingDraftVerificationResumeTest.php`
- `tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php`
- `tests/Unit/Onboarding/OnboardingDraftStageResolverTest.php`

## Suggested Verification Commands

1. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`
2. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php`
3. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingActivationTest.php`
4. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationAssistTest.php`
5. `vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
6. `vendor/bin/sail artisan test --compact tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php`
7. `vendor/bin/sail artisan test --compact tests/Feature/OpsUx/QueuedToastCopyTest.php`
8. `vendor/bin/sail artisan test --compact tests/Feature/OperationRunServiceTest.php`
9. `vendor/bin/sail artisan test --compact tests/Browser/OnboardingDraftRefreshTest.php`
10. `vendor/bin/sail artisan test --compact tests/Browser/OnboardingDraftVerificationResumeTest.php`
11. `vendor/bin/sail artisan test --compact tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php`

## Expected Outcome

- No new onboarding routes are needed.
- Verify Access and Bootstrap behave as operation-backed checkpoints.
- Lifecycle truth is queryable from top-level draft fields.
- Terminal drafts remain immutable.
- Stale mutations fail safely with visible conflict guidance.