# Quickstart: Tenant Lifecycle, Operability, and Context Semantics Foundation

## Purpose

Use this guide to validate follow-up implementation work derived from Spec 143.

## Prerequisites

- Laravel Sail services are running.
- An admin-plane user exists with workspace membership.
- At least one workspace exists with tenants covering these lifecycle states:
  - `draft`
  - `onboarding`
  - `active`
  - `archived`
- At least one authorized `OperationRun` exists for a tenant that is not the currently selected tenant.
- At least one resumable `TenantOnboardingSession` exists for an onboarding tenant.

## Validation flow

### 1. Validate selector eligibility

- Open `/admin/choose-tenant`.
- Confirm only `active` tenants are selectable as normal tenant context.
- Confirm `draft`, `onboarding`, and `archived` tenants are not selectable in the standard tenant chooser.

Expected result:

- The chooser represents normal operating context only.
- No invalid tenant selection path is available.

### 2. Validate management and onboarding visibility

- Open `/admin/tenants` and inspect lifecycle labels and actions.
- Open `/admin/onboarding` and any resumable onboarding draft.

Expected result:

- Onboarding and draft tenants remain visible in the correct surfaces.
- Archived tenants remain visible only where administrative or audit semantics justify them.
- Lifecycle-related actions are vocabulary-correct: `Archive`, `Restore`, `Resume onboarding`.

### 3. Validate canonical operation viewer behavior

- Select tenant B as the remembered tenant context.
- Open `/admin/operations/{run}` for a run linked to tenant A.

Expected result:

- The run remains visible if workspace membership, tenant entitlement, and capability checks pass.
- The page handles the mismatch explicitly in UX if implemented, but does not return a false 404.

### 4. Validate tenant-bound route behavior

- Open `/admin/tenants/{tenant}` for an onboarding tenant that the user is entitled to.
- Repeat for an archived tenant if allowed by the follow-up implementation.

Expected result:

- Route legitimacy comes from the route tenant plus entitlement checks.
- Action availability changes with lifecycle, but route validity does not depend on current header tenant selection.

### 5. Validate authorization semantics

- Attempt the same tenant and operation-run routes as:
  - a non-member user
  - a workspace member without the required capability

Expected result:

- Non-member or non-entitled access resolves as 404.
- Member without capability resolves as 403 for execution attempts.

### 6. Validate status presentation

- Inspect tenant lifecycle badges wherever tenant status appears.

Expected result:

- `draft`, `onboarding`, `active`, and `archived` all render explicit, centralized status presentation.
- No valid lifecycle renders as `Unknown`.

## Suggested focused test targets

- `tests/Feature/Auth/TenantChooserSelectionTest.php`
- `tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php`
- `tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php`
- `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`
- `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`
- `tests/Feature/Spec085/CanonicalMonitoringDoesNotMutateTenantContextTest.php`
- `tests/Feature/Badges/TenantStatusBadgeTest.php`
- `tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
- `tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php`

## Filament and deployment notes

- Livewire v4.0+ compliance remains required because this feature touches Filament v5 surfaces.
- Filament providers remain registered in `bootstrap/providers.php`.
- This foundation adds no new assets, so there is no new `filament:assets` work beyond the project’s existing deploy process.