# Quickstart: Implementing Spec 145

## Preconditions

1. Start Sail if it is not already running.

```bash
vendor/bin/sail up -d
```

2. Confirm you are on the feature branch.

```bash
git branch --show-current
```

Expected branch: `145-tenant-action-taxonomy-lifecycle-safe-visibility`

## Implementation Sequence

1. Add the central tenant-action policy surface.
   Target areas:
   - `app/Services/Tenants/`
   - `app/Support/Tenants/`

2. Refactor tenant-management surfaces to consume the central action policy.
   Target areas:
   - `app/Filament/Resources/TenantResource.php`
   - `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`
   - `app/Filament/Resources/TenantResource/Pages/EditTenant.php`
   - `app/Filament/Resources/TenantResource/Pages/ListTenants.php`

3. Keep onboarding workflow actions distinct and reuse onboarding lifecycle rules instead of duplicating tenant-surface logic.
   Target area:
   - `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`

4. Reuse existing centralized semantics instead of adding local mappings.
   Relevant existing files:
   - `app/Services/Tenants/TenantOperabilityService.php`
   - `app/Support/Tenants/TenantLifecycle.php`
   - `app/Support/Badges/Domains/TenantStatusBadge.php`
   - `app/Support/Audit/AuditActionId.php`
   - `app/Support/Rbac/UiEnforcement.php`

5. Keep User Story 3 implementation boundaries explicit.
   - `T023` owns runtime reuse of the resolved action catalog across list, detail, and onboarding surfaces.
   - `T024` owns only action-surface declaration cleanup and overflow-contract alignment.
   - Do not move catalog-resolution logic into action-surface declarations.

6. Preserve Filament v5 and Livewire v4 compliance.
   - No v3/v4 Filament APIs.
   - No provider registration changes are needed; Laravel 12 panel providers remain in `bootstrap/providers.php`.
   - Destructive actions remain confirmation-gated.

## Focused Test Pass

Run the minimum targeted suite first:

```bash
vendor/bin/sail artisan test --compact tests/Unit/Tenants/TenantOperabilityServiceTest.php
vendor/bin/sail artisan test --compact tests/Unit/Tenants/TenantActionPolicySurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantResourceAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantLifecycleActionNamingTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php
vendor/bin/sail artisan test --compact tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php
```

These focused tests are part of the required regression baseline for this spec slice. Extend them as needed, but do not treat the central action-policy, confirmation-regression, or cross-surface consistency coverage as optional.

## Formatting

Run Pint after edits:

```bash
vendor/bin/sail bin pint --dirty --format agent
```

## Manual Verification Checklist

1. `draft` tenant on `/admin/tenants`: shows `View` and onboarding-oriented action, not `Archive`.
2. `onboarding` tenant on `/admin/tenants/{tenant}`: shows `Resume onboarding` and readiness/support actions, not active-only lifecycle actions.
3. `active` tenant on index and detail: shows `Archive`, not onboarding-only lifecycle actions.
4. `archived` tenant on index and detail: shows `Restore`, not `Archive` or `Resume onboarding`.
5. Onboarding wizard route: onboarding completion remains workflow-contextual and does not become a generic tenant action.
6. Non-member access still resolves as 404; in-scope member without capability is denied as 403 or disabled-in-UI per existing helper semantics.

## Done Criteria

The implementation is ready for completion review when:

- lifecycle-action assembly is centralized,
- index/detail/onboarding surfaces no longer drift semantically,
- audit and badge semantics remain centralized,
- targeted Pest coverage passes,
- and the Action Surface Contract still validates for touched Filament surfaces.