# Quickstart — Self-Service Tenant Onboarding & Connection Readiness

## Prereqs

- Docker running
- Laravel Sail dependencies installed
- Current feature branch checked out: `240-tenant-onboarding-readiness`

## Run locally

- Start containers: `cd apps/platform && ./vendor/bin/sail up -d`
- Run targeted validation after implementation:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ManagedTenantOnboardingWizardTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftPickerTest.php tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Policies/TenantOnboardingSessionPolicyTest.php tests/Unit/TenantRequiredPermissionsFreshnessTest.php`
- Format after implementation: `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`

## Manual smoke (after implementation)

1. Select a workspace and open `/admin/onboarding`.
2. With multiple resumable drafts, confirm each draft card shows current stage, readiness summary, freshness cue, and one primary next action.
3. Open a draft with missing consent and confirm the workflow points to consent or permission remediation instead of generic incomplete-state copy.
4. Open a draft with a changed provider connection or mismatched verification run and confirm readiness falls back to needs-attention with a canonical `Open operation` link when evidence exists.
5. Open the workflow as a wrong-workspace actor or actor without linked-tenant entitlement and confirm 404; open as a workspace member without onboarding capability and confirm 403 on protected actions.

## Notes

- Filament v5 requires Livewire v4.0+; this repo already satisfies that requirement.
- Laravel 11+ panel providers are registered in `bootstrap/providers.php`; this feature does not add or change panel providers.
- No new Filament Resource or Global Search surface is planned, so global search behavior is unchanged.
- No new assets are registered. Deployment keeps the existing Filament asset step (`cd apps/platform && php artisan filament:assets`) when other asset-bearing changes require it.
- Readiness freshness for this slice reuses existing signals only: connection-change / selected-connection mismatch from onboarding lifecycle state plus stored permission freshness from `TenantRequiredPermissionsViewModelBuilder`.

## Implementation proof — 2026-04-25

- Targeted fast-feedback validation passed: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ManagedTenantOnboardingWizardTest.php tests/Feature/Onboarding/OnboardingDraftPickerTest.php tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php tests/Unit/Policies/TenantOnboardingSessionPolicyTest.php tests/Unit/TenantRequiredPermissionsFreshnessTest.php` — 55 tests, 212 assertions.
- Formatting passed: `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
- Guardrail close-out: keep. No provider-boundary drift, no lane-cost escalation, no new assets, no new persistence, and no follow-up spec required.
- Explicit defers retained: numeric completion score and cross-surface readiness reuse.